Sync agent instructions from main

.gitattributes

@@ -61,3 +61,26 @@ harness/fixtures/child-work-native/** -text whitespace=cr-at-eol
 harness/experiments/windows-gates-865483b-20260911/** -text -whitespace
 harness/experiments/native-child-oa-865483b-20260911/** -text -whitespace
 harness/experiments/packaged-server-865483b-20260911/** -text -whitespace
+
+harness/experiments/canvas-union-a57c334-20260911/** -text -whitespace
+harness/experiments/windows-gates-a57c334-20260911/** -text -whitespace
+harness/experiments/native-child-continuation-865483b-20260911/** -text -whitespace
+harness/experiments/lifecycle-header-correction-native-865483b-20260911/** -text -whitespace
+harness/release-native-child-continuation-review-20260911.md -text -whitespace
+
+harness/experiments/packaged-gui-close-865483b-20260911/** -text -whitespace
+harness/release-grapheme-shortening-review-20260911.md -text -whitespace
+harness/experiments/staged-source-native-a57c334-20260911/** -text -whitespace
+harness/experiments/grapheme-windows-cb91525-20260911/** -text -whitespace
+harness/experiments/canvas-native-close-a57c334-20260911/** -text -whitespace
+harness/release-staged-native-a57-independent-review-20260911.md -text -whitespace
+harness/release-saved-destination-independent-review-20260912.md -text -whitespace
+harness/experiments/repair-union-windows-33e30c1-20260912/** -text -whitespace
+harness/experiments/canvas-camera-a57c334-20260912/** -text -whitespace
+harness/release-camera-a57-independent-review-20260912.md -text -whitespace
+
+harness/experiments/canvas-repair-package-33e30c1-20260912/** -text -whitespace
+harness/experiments/canvas-repair-native-33e30c1-20260912/** -text -whitespace
+harness/experiments/canvas-repair-server-33e30c1-20260912/** -text -whitespace
+
+harness/experiments/canvas-repair-publication-20260912/** -text -whitespace

AGENTS.md

@@ -35,20 +35,28 @@ Use Gitea for live coordination and the relevant code version for implementation
 
 ## Coordination and integration
 
+All independent agents coordinating through Gitea run on completely separate machines, each with its own clone, filesystem, tools, processes, and runtime. Gitea and pushed Git history are the shared communication and delivery channels. Local files (including `harness`), unpushed commits, worktrees, test results, and localhost services are not accessible to peers. Matching branch names or paths do not imply synchronized contents.
+
 1. On starting or resuming, including after compaction, inspect the working branch, local changes, applicable instructions, relevant shared records, and existing implementation. Recover context from authoritative records. Check for newer shared instructions on the actual remote default branch without overwriting local work. Read what is relevant; avoid repeated full-history scans and constant polling.
-2. Search before creating tasks. Claim a meaningful outcome in its Gitea issue with a stable session identity, scope, branch/worktree, and acceptance criteria. Keep small steps within that task. Recheck after claiming; comments are not atomic locks. Respect existing ownership and resolve overlapping claims before overlapping work.
-3. Independent sessions are peers. Each owns its contribution and delegated work. Record one integration/release owner when a milestone needs shared coordination. Use separate worktrees or checkouts, partition files/interfaces, and coordinate changes to shared specifications and documents.
-4. At meaningful checkpoints or handoffs, record changed results, commit/PR links, verification commands and environment, blockers, and next actions. Identify the tested code version and uncommitted or unpublished work; make required artifacts accessible to other sessions. Do not assume another agent is running or has read a message; silence alone does not establish abandonment. Record evidence and preserve existing work when reassigning a task.
-5. Follow project review and merge conventions. Inspect upstream changes, resolve conflicts while preserving others' edits, and verify the combined result. Do not overwrite others' work or force-push shared history to resolve coordination problems.
+2. Search before creating tasks. Claim a meaningful outcome in its Gitea issue with a stable session identity, scope, remote repository/branch, and acceptance criteria. Keep small steps within that task. Recheck after claiming; comments are not atomic locks. Respect existing ownership and resolve overlapping claims before overlapping work.
+3. Independent sessions are peers. Each owns its contribution and delegated work on its own machine. Record one integration/release owner when a milestone needs shared coordination. Use distinct remote work branches, partition files/interfaces, and coordinate changes to shared specifications and documents. Worktrees provide local isolation only; they do not share work between machines.
+4. At meaningful checkpoints or handoffs, record changed results, commit/PR links, verification commands and environment, blockers, and next actions. Identify the tested code version and label uncommitted or unpublished work as local-only. Before asking peers to consume results, push the required code and versioned documentation, including relevant `harness` updates; publish other required artifacts in Gitea and link them. Use repository-relative paths with commit references, reproducible commands, and necessary environment details; local paths and localhost URLs alone are not handoffs. Do not assume another agent is running or has read a message; silence alone does not establish abandonment. Record evidence and preserve existing work when reassigning a task.
+5. Follow project review and merge conventions. Fetch the relevant remote branches and inspect the identified commits before reviewing or integrating another machine's work. Resolve conflicts while preserving others' edits, and verify the combined result locally; report material environment differences. Local instruction-file edits reach peers only after publication and retrieval. Do not overwrite others' work or force-push shared history to resolve coordination problems.
 6. Close work when its acceptance criteria are met and the result is integrated or delivered as appropriate. Mark duplicates and superseded tasks explicitly with replacement links. Then choose further useful unowned work while the requested objective remains incomplete.
 
 Use Gitea MCP for shared coordination. If unavailable, report the failure, buffer necessary handoff information locally, and continue already-owned or clearly non-overlapping work. Reconcile with current Gitea state when access returns; do not claim an ownership update, review, or publication succeeded without confirmation.
 
 ## Delegation and reasoning
 
-Use GPT-6 Astra exclusively. Delegate bounded independent research, design, implementation, or review when it improves progress, judgment, or preserves the parent's context. Give subagents the relevant context, ownership boundaries, result format, and evidence requirements. Use fresh critics when practical. The parent owns synthesis and integration and normally consolidates results into Gitea. Choose concurrency according to useful independent work and available resources, including other sessions; there is no agent-count quota.
+Use GPT-6 Astra exclusively. Gitea peers are independent remote sessions, not subagents controlled by this session. Spawned subagents use the execution environment actually provided by the agent tools; do not assume they share files, and publish their results before Gitea peers need them. Delegate bounded independent research, design, implementation, or review when it improves progress, judgment, or preserves the parent's context. Give subagents the relevant context, ownership boundaries, result format, and evidence requirements. Use fresh critics when practical. The parent owns synthesis and integration and normally consolidates results into Gitea. Choose concurrency according to useful independent work and available resources, including other sessions; there is no agent-count quota.
 
-Use the highest available reasoning effort for orchestration and foundational semantic, methodological, formal, or cross-domain decisions. For subagents, use extra-high for difficult design, adversarial review, or unusually hard implementation; high for normal implementation, targeted research, correctness review, debugging, and runtime evaluation; medium for routine exploration, mechanical changes, builds, and tests; and lower for trivial work. Allocate by difficulty, not length, using supported controls; do not claim an unapplied change or alter global configuration merely to enforce these preferences.
+Optimize reasoning effort for verified outcomes per cost, including review, retries, and repair:
+
+- Main agent: default to high for planning, synthesis, integration, and acceptance decisions; medium for dispatching a settled plan and routine coordination.
+- Subagents: default to medium for bounded implementation and targeted research; low for straightforward retrieval, mechanical edits, and running established checks; high for complex debugging, correctness review, adversarial analysis, or ambiguous design.
+- Use extra-high selectively for difficult foundational semantic, methodological, formal, or cross-domain decisions. Reserve max for exceptional unresolved problems where additional reasoning is likely to justify its cost. Retain higher settings when evidence supports their value.
+
+Allocate by task difficulty and consequences, not role or length alone. Start higher when a clearly difficult decision has expensive downstream consequences. Escalate for concrete reasoning difficulties; resolve missing evidence or unclear requirements at their source. Set subagent effort explicitly through supported controls to avoid unintended inheritance. Do not claim an unapplied change or alter global configuration merely to enforce these preferences.
 
 ## Memory and maintenance
 

Cargo.lock

@@ -2176,6 +2176,7 @@ dependencies = [
  "serde_json",
  "tempfile",
  "tokio",
+ "unicode-segmentation",
 ]
 
 [[package]]

crates/oa-core/src/language.rs

@@ -142,12 +142,87 @@ pub struct Analysis {
     pub declarations: Vec<DeclarationSpan>,
 }
 
+/// Check the decoded spelling required by declaration-header UUID clauses.
+/// This is the shared 36-byte/hyphen shape rule, not a hexadecimal parser:
+/// callers must additionally parse the UUID. Uppercase hex and JSON escapes
+/// that decode to this spelling remain accepted. URN/braced/compact forms do not.
+pub fn has_uuid_header_shape(decoded: &str) -> bool {
+    decoded.len() == 36
+        && [8, 13, 18, 23]
+            .into_iter()
+            .all(|index| decoded.as_bytes()[index] == b'-')
+}
+
+/// Budgets for one original source buffer. Policy is caller-owned; these
+/// limits do not change the grammar or perform model admission.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OutlineLimits {
+    pub max_source_bytes: usize,
+    pub max_tokens: usize,
+    pub max_declarations: usize,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutlineResource {
+    SourceBytes,
+    Tokens,
+    Declarations,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OutlineLimit {
+    pub resource: OutlineResource,
+    pub limit: usize,
+    pub observed_at_least: usize,
+    /// Original byte offset where admission stopped; never a rewritten offset.
+    pub offset: usize,
+}
+
+/// Roles discovered by the existing tolerant declaration walk. Keeping the
+/// wrapper preserves DeclarationSpan and Analysis as existing public APIs.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OutlineDeclaration {
+    pub declaration: DeclarationSpan,
+    pub kind_span: Span,
+    pub alias_span: Span,
+    /// Whole quoted header ID token, even if it is not a valid UUID. In that
+    /// case declaration.id is None. Missing/non-string ID values have no span.
+    pub id_literal_span: Option<Span>,
+}
+
+/// A full-file tolerant scan, not a successful parse or validated model. Invalid
+/// text remains available. Lexical errors and unmatched braces are facts only:
+/// their absence does not establish syntactic or semantic validity.
+///
+/// A budget failure returns Err and no partial Outline. Include reachability,
+/// project completeness and editor revision are intentionally not inferred here.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Outline<'a> {
+    pub source: &'a str,
+    pub tokens: Vec<TokenSpan>,
+    pub declarations: Vec<OutlineDeclaration>,
+    pub has_lexical_errors: bool,
+    pub has_unmatched_braces: bool,
+}
+
 /// Tolerant highlighting tokens cover the whole input, including incomplete
 /// strings and unexpected characters. No model is created or modified.
 pub fn tokenize(source: &str) -> Vec<TokenSpan> {
+    tokenize_with_limit(source, usize::MAX).expect("unlimited token scan")
+}
+
+fn tokenize_with_limit(source: &str, max_tokens: usize) -> Result<Vec<TokenSpan>, OutlineLimit> {
     let mut tokens = Vec::new();
     let mut cursor = 0;
     while cursor < source.len() {
+        if tokens.len() == max_tokens {
+            return Err(OutlineLimit {
+                resource: OutlineResource::Tokens,
+                limit: max_tokens,
+                observed_at_least: tokens.len().saturating_add(1),
+                offset: cursor,
+            });
+        }
         let start = cursor;
         let ch = source[cursor..].chars().next().expect("in bounds");
         let class = if matches!(ch, ' ' | '\t' | '\r' | '\n') {
@@ -224,7 +299,7 @@ pub fn tokenize(source: &str) -> Vec<TokenSpan> {
             span: Span { start, end: cursor },
         });
     }
-    tokens
+    Ok(tokens)
 }
 
 pub fn lint(source: &str) -> Vec<Diagnostic> {
@@ -1230,11 +1305,7 @@ impl Parser<'_> {
         self.cursor += 1;
         let offset = self.current().span.start;
         let value = self.quoted()?;
-        if value.len() != 36
-            || ![8, 13, 18, 23]
-                .into_iter()
-                .all(|i| value.as_bytes()[i] == b'-')
-        {
+        if !has_uuid_header_shape(&value) {
             return Err(Error {
                 code: "invalid_source",
                 offset,
@@ -1962,8 +2033,49 @@ fn take_required_id(fields: &mut Map<String, Value>, key: &str) -> Result<Id, St
 
 /// Analyze an incomplete source buffer without adopting a candidate. Declaration
 /// spans remain available even when a later declaration contains errors.
+/// Invalid compact/braced/URN header IDs retain no authored identity, matching
+/// the declaration parser rather than the UUID crate's broader accepted forms.
 pub fn analyze(source: &str) -> Analysis {
     let tokens = tokenize(source);
+    let (declarations, _) =
+        declaration_outline(source, &tokens, usize::MAX).expect("unlimited declaration walk");
+    Analysis {
+        tokens,
+        diagnostics: lint(source),
+        declarations: declarations.into_iter().map(|d| d.declaration).collect(),
+    }
+}
+
+/// Read exact current text without lint, parsing a model, stabilization or I/O.
+/// Source bytes are admitted before token allocation; token/declaration limits
+/// are checked before lexing the next token or materializing the next record.
+pub fn outline(source: &str, limits: OutlineLimits) -> Result<Outline<'_>, OutlineLimit> {
+    if source.len() > limits.max_source_bytes {
+        return Err(OutlineLimit {
+            resource: OutlineResource::SourceBytes,
+            limit: limits.max_source_bytes,
+            observed_at_least: source.len(),
+            offset: 0,
+        });
+    }
+    let tokens = tokenize_with_limit(source, limits.max_tokens)?;
+    let has_lexical_errors = tokens.iter().any(|token| token.class == TokenClass::Error);
+    let (declarations, has_unmatched_braces) =
+        declaration_outline(source, &tokens, limits.max_declarations)?;
+    Ok(Outline {
+        source,
+        tokens,
+        declarations,
+        has_lexical_errors,
+        has_unmatched_braces,
+    })
+}
+
+fn declaration_outline(
+    source: &str,
+    tokens: &[TokenSpan],
+    max_declarations: usize,
+) -> Result<(Vec<OutlineDeclaration>, bool), OutlineLimit> {
     let significant = tokens
         .iter()
         .filter(|t| !matches!(t.class, TokenClass::Whitespace | TokenClass::Comment))
@@ -1972,17 +2084,21 @@ pub fn analyze(source: &str) -> Analysis {
     // again would make tolerant navigation quadratic on deeply nested drafts.
     let mut body_ends = vec![None; significant.len()];
     let mut bodies = Vec::new();
+    let mut unmatched_close = false;
     for (index, token) in significant.iter().enumerate() {
         match &source[token.span.start..token.span.end] {
             "{" => bodies.push(index),
             "}" => {
                 if let Some(open) = bodies.pop() {
                     body_ends[open] = Some(token.span.end);
+                } else {
+                    unmatched_close = true;
                 }
             }
             _ => {}
         }
     }
+    let has_unmatched_braces = unmatched_close || !bodies.is_empty();
     let mut declarations = Vec::new();
     for (i, t) in significant.iter().enumerate() {
         let word = &source[t.span.start..t.span.end];
@@ -2007,7 +2123,16 @@ pub fn analyze(source: &str) -> Analysis {
             }
             j += 1;
         }
+        if declarations.len() == max_declarations {
+            return Err(OutlineLimit {
+                resource: OutlineResource::Declarations,
+                limit: max_declarations,
+                observed_at_least: declarations.len().saturating_add(1),
+                offset: t.span.start,
+            });
+        }
         let mut id = None;
+        let mut id_literal_span = None;
         if significant
             .get(j)
             .is_some_and(|t| &source[t.span.start..t.span.end] == "id")
@@ -2015,39 +2140,51 @@ pub fn analyze(source: &str) -> Analysis {
             if let Some(value) = significant.get(j + 1)
                 && value.class == TokenClass::String
             {
+                id_literal_span = Some(value.span);
                 let text =
                     serde_json::from_str::<String>(&source[value.span.start..value.span.end])
                         .unwrap();
-                id = Id::parse_str(&text).ok();
+                if has_uuid_header_shape(&text) {
+                    id = Id::parse_str(&text).ok();
+                }
             }
             j += 2;
         }
-        let mut end = significant
-            .get(j)
-            .map_or(alias_token.span.end, |t| t.span.end);
+        // A recognized header ID at EOF must remain inside the whole span.
+        // Keep the old next-token/body behavior; only the EOF fallback changes.
+        let header_end = significant
+            .get(j.saturating_sub(1))
+            .or_else(|| significant.last())
+            .map_or(alias_token.span.end, |token| token.span.end);
+        let mut end = significant.get(j).map_or(header_end, |t| t.span.end);
         if significant
             .get(j)
             .is_some_and(|t| &source[t.span.start..t.span.end] == "{")
         {
             end = body_ends[j].unwrap_or(source.len());
         }
-        declarations.push(DeclarationSpan {
-            alias: alias.into(),
-            id,
-            kind: word.into(),
-            span: Span {
-                start: t.span.start,
-                end,
+        declarations.push(OutlineDeclaration {
+            declaration: DeclarationSpan {
+                alias: alias.into(),
+                id,
+                kind: word.into(),
+                span: Span {
+                    start: t.span.start,
+                    end,
+                },
             },
+            kind_span: t.span,
+            alias_span: alias_token.span,
+            id_literal_span,
         });
     }
-    Analysis {
-        tokens,
-        diagnostics: lint(source),
-        declarations,
-    }
+    Ok((declarations, has_unmatched_braces))
 }
 
+#[cfg(test)]
+#[path = "language_outline_tests.rs"]
+mod outline_tests;
+
 #[cfg(test)]
 #[path = "language_nesting_tests.rs"]
 mod nesting_tests;
@@ -2442,11 +2579,7 @@ pub(crate) mod legacy {
             let value = self.quoted()?;
             // Require the portable 8-4-4-4-12 spelling, not the UUID crate's URN,
             // braces, or compact alternatives. Uppercase hexadecimal is accepted.
-            if value.len() != 36
-                || ![8, 13, 18, 23]
-                    .into_iter()
-                    .all(|index| value.as_bytes()[index] == b'-')
-            {
+            if !super::has_uuid_header_shape(&value) {
                 return Err(Error {
                     code: "invalid_source",
                     offset,

crates/oa-core/src/language_outline_tests.rs

@@ -0,0 +1,386 @@
+//! Prepared outline tests. Explicit compatibility tests additionally exercise
+//! the existing parsers/analyze; the outline entry itself never calls them.
+use super::*;
+
+fn limits() -> OutlineLimits {
+    OutlineLimits {
+        max_source_bytes: 1024 * 1024,
+        max_tokens: 100_000,
+        max_declarations: 1_000,
+    }
+}
+
+fn declaration<'a>(result: &'a Outline<'_>, alias: &str) -> &'a OutlineDeclaration {
+    result
+        .declarations
+        .iter()
+        .find(|d| d.declaration.alias == alias)
+        .unwrap()
+}
+
+fn text(source: &str, span: Span) -> &str {
+    &source[span.start..span.end]
+}
+
+#[test]
+fn outline_roles_preserve_unicode_crlf_and_exact_escaped_uuid_literal() {
+    let source = "// 検査 🚒\r\noa_actor responder \"救助\" id \"\\u00300000000-0000-0000-0000-000000000001\" {}\r\nsource @ // 使用\r\n responder;";
+    let before = source.as_bytes().to_vec();
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.source.as_bytes(), before);
+    assert_eq!(result.source.as_ptr(), source.as_ptr());
+    let d = declaration(&result, "responder");
+    assert_eq!(text(source, d.kind_span), "oa_actor");
+    assert_eq!(text(source, d.alias_span), "responder");
+    assert_eq!(
+        text(source, d.id_literal_span.unwrap()),
+        "\"\\u00300000000-0000-0000-0000-000000000001\""
+    );
+    assert_eq!(d.declaration.id, Some(Id::from_u128(1)));
+    assert_eq!(d.declaration.span.start, source.find("oa_actor").unwrap());
+    assert_eq!(d.declaration.span.end, source.find("{}\r\n").unwrap() + 2);
+    let mut end = 0;
+    for token in &result.tokens {
+        assert_eq!(token.span.start, end);
+        assert!(token.span.start < token.span.end);
+        assert!(source.is_char_boundary(token.span.start));
+        assert!(source.is_char_boundary(token.span.end));
+        end = token.span.end;
+    }
+    assert_eq!(end, source.len());
+    assert!(!result.has_lexical_errors);
+    assert!(!result.has_unmatched_braces);
+}
+
+#[test]
+fn closed_id_at_eof_is_inside_the_declaration_extent() {
+    for source in [
+        "oa_actor a \"Actor\" id \"00000000-0000-0000-0000-000000000001\"",
+        "node placed id \"00000000-0000-0000-0000-000000000001\"",
+    ] {
+        let result = outline(source, limits()).unwrap();
+        let d = &result.declarations[0];
+        let literal = d.id_literal_span.unwrap();
+        assert_eq!(d.declaration.id, Some(Id::from_u128(1)));
+        assert_eq!(d.declaration.span.end, source.len());
+        assert!(d.declaration.span.start <= literal.start);
+        assert!(literal.end <= d.declaration.span.end);
+    }
+    for source in ["oa_actor a \"Actor\"", "oa_actor a \"Actor\" id"] {
+        let result = outline(source, limits()).unwrap();
+        let d = &result.declarations[0];
+        assert_eq!(d.declaration.span.end, source.len());
+        assert_eq!(d.declaration.id, None);
+        assert_eq!(d.id_literal_span, None);
+    }
+}
+
+#[test]
+fn missing_bad_and_historical_ids_never_allocate_authored_identity() {
+    let source = "oa_actor missing \"No ID\" {}\noa_actor bad \"Bad ID\" id \"not-a-uuid\" {}\noa_actor historical \"00000000-0000-0000-0000-000000000001\" { history uuid \"00000000-0000-0000-0000-000000000001\"; }";
+    let first = outline(source, limits()).unwrap();
+    let second = outline(source, limits()).unwrap();
+    assert_eq!(first, second);
+    assert!(
+        first
+            .declarations
+            .iter()
+            .all(|d| d.declaration.id.is_none())
+    );
+    assert_eq!(declaration(&first, "missing").id_literal_span, None);
+    assert_eq!(declaration(&first, "historical").id_literal_span, None);
+    assert_eq!(
+        text(source, declaration(&first, "bad").id_literal_span.unwrap()),
+        "\"not-a-uuid\""
+    );
+    // Balanced tokens are not a successful syntax/semantic validation claim.
+    assert!(!first.has_lexical_errors);
+    assert!(!first.has_unmatched_braces);
+}
+
+#[test]
+fn invalid_full_scan_keeps_closed_children_and_reports_lexical_body_facts() {
+    let source = "oa_entity outer \"Outer\" {\n oa_actor ready \"Ready\" { description \"} stays text\"; }\n oa_actor pending \"Pending\" { description \"unfinished 🌊";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.source, source);
+    assert_eq!(result.tokens.last().unwrap().span.end, source.len());
+    assert!(result.has_lexical_errors);
+    assert!(result.has_unmatched_braces);
+    let ready = declaration(&result, "ready");
+    assert_eq!(
+        text(source, ready.declaration.span),
+        "oa_actor ready \"Ready\" { description \"} stays text\"; }"
+    );
+    assert_eq!(
+        declaration(&result, "outer").declaration.span.end,
+        source.len()
+    );
+    assert_eq!(
+        declaration(&result, "pending").declaration.span.end,
+        source.len()
+    );
+    let unmatched_close = outline("}\n// brace in comment {\n", limits()).unwrap();
+    assert!(unmatched_close.has_unmatched_braces);
+    assert!(!unmatched_close.has_lexical_errors);
+}
+
+#[test]
+fn missing_body_syntax_is_unchecked_even_when_known_error_flags_are_clear() {
+    let source = "oa_actor a \"A\" id \"00000000-0000-0000-0000-000000000001\"";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 1);
+    assert!(!result.has_lexical_errors);
+    assert!(!result.has_unmatched_braces);
+    // There is deliberately no `valid` flag: the known-complete fact is scanning
+    // these bytes, not the missing body becoming legal or the draft being applied.
+    assert_eq!(result.source, source);
+}
+
+#[test]
+fn keyword_alias_and_collisions_keep_every_source_ordered_header() {
+    let source = "project root_model \"Model\" {\n oa_actor oa_activity \"First\" id \"00000000-0000-0000-0000-000000000001\" {}\n oa_actor oa_activity \"Second\" id \"00000000-0000-0000-0000-000000000001\" {}\n diagram view_one \"View\" {}\n node placement { diagram @view_one; }\n}";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 5);
+    let duplicates: Vec<_> = result
+        .declarations
+        .iter()
+        .filter(|d| d.declaration.alias == "oa_activity")
+        .collect();
+    assert_eq!(duplicates.len(), 2);
+    assert!(duplicates[0].alias_span.start < duplicates[1].alias_span.start);
+    assert_eq!(duplicates[0].declaration.id, duplicates[1].declaration.id);
+    assert!(
+        result
+            .tokens
+            .iter()
+            .any(|t| t.span == duplicates[0].alias_span && t.class == TokenClass::Keyword)
+    );
+    assert_eq!(
+        text(source, declaration(&result, "placement").kind_span),
+        "node"
+    );
+    assert_eq!(declaration(&result, "placement").declaration.id, None);
+}
+
+#[test]
+fn bounds_refuse_before_returning_a_partial_outline() {
+    let source = "oa_actor a \"A\" {}\noa_actor b \"B\" {}";
+    let admitted = outline(source, limits()).unwrap();
+    let exact = OutlineLimits {
+        max_source_bytes: source.len(),
+        max_tokens: admitted.tokens.len(),
+        max_declarations: 2,
+    };
+    assert_eq!(outline(source, exact).unwrap(), admitted);
+    for resource in [
+        OutlineResource::SourceBytes,
+        OutlineResource::Tokens,
+        OutlineResource::Declarations,
+    ] {
+        let mut lower = exact;
+        match resource {
+            OutlineResource::SourceBytes => lower.max_source_bytes -= 1,
+            OutlineResource::Tokens => lower.max_tokens -= 1,
+            OutlineResource::Declarations => lower.max_declarations -= 1,
+        }
+        let error = outline(source, lower).unwrap_err();
+        assert_eq!(error.resource, resource);
+        assert!(error.observed_at_least > error.limit);
+        assert!(source.is_char_boundary(error.offset));
+        if resource == OutlineResource::Declarations {
+            assert_eq!(error.offset, source.find("oa_actor b").unwrap());
+        }
+    }
+    let empty = outline(
+        "",
+        OutlineLimits {
+            max_source_bytes: 0,
+            max_tokens: 0,
+            max_declarations: 0,
+        },
+    )
+    .unwrap();
+    assert!(empty.tokens.is_empty() && empty.declarations.is_empty());
+    let unicode = "// 🌊\r\noa_actor a \"A\" {}";
+    let error = outline(
+        unicode,
+        OutlineLimits {
+            max_source_bytes: 4,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::SourceBytes);
+    assert_eq!(error.offset, 0);
+    let error = outline(
+        unicode,
+        OutlineLimits {
+            max_tokens: 1,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::Tokens);
+    assert_eq!(error.offset, unicode.find('\n').unwrap());
+}
+
+#[test]
+fn outline_ranges_follow_current_bytes_without_identity_stabilization() {
+    let old = "oa_actor a \"A\" {}\nsource @a;";
+    let current = format!("// 航海 🚒\r\n{old}");
+    let old_outline = outline(old, limits()).unwrap();
+    let current_outline = outline(&current, limits()).unwrap();
+    let shift = current.len() - old.len();
+    let old_role = &old_outline.declarations[0];
+    let current_role = &current_outline.declarations[0];
+    assert_eq!(
+        current_role.alias_span.start,
+        old_role.alias_span.start + shift
+    );
+    assert_eq!(
+        current_role.kind_span.start,
+        old_role.kind_span.start + shift
+    );
+    assert_eq!(
+        current_role.declaration.span.end,
+        old_role.declaration.span.end + shift
+    );
+    assert_eq!(current_outline.source, current);
+    assert_eq!(old_outline.source, old);
+    assert_eq!(current_role.declaration.id, None);
+    assert!(!current_outline.source.contains(" id "));
+    // Workspace revision/stale-handle rejection belongs to the query/adapter,
+    // not a claim that an old owned span can be applied to any other string.
+}
+
+#[test]
+fn deeply_nested_bounds_use_the_same_iterative_walk_and_declaration_budget() {
+    let mut source = String::new();
+    for index in 0..600 {
+        source.push_str(&format!("oa_activity work_{index} \"Work\" {{\n"));
+    }
+    source.push_str(&"}\n".repeat(600));
+    let result = outline(&source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 600);
+    assert!(!result.has_unmatched_braces);
+    assert_eq!(
+        result.declarations[0].declaration.span.end,
+        source.len() - 1
+    );
+    let error = outline(
+        &source,
+        OutlineLimits {
+            max_declarations: 599,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::Declarations);
+    assert_eq!(error.observed_at_least, 600);
+    assert_eq!(error.offset, source.find("oa_activity work_599").unwrap());
+}
+
+#[test]
+fn noncanonical_uuid_spellings_have_no_outline_or_analysis_identity() {
+    for raw in [
+        "00000000000000000000000000000001",
+        "{00000000-0000-0000-0000-000000000001}",
+        "urn:uuid:00000000-0000-0000-0000-000000000001",
+    ] {
+        assert!(
+            Id::parse_str(raw).is_ok(),
+            "The UUID crate alone is too permissive"
+        );
+        assert!(!has_uuid_header_shape(raw));
+        let literal = format!("\"{raw}\"");
+        let modern = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+        let before = modern.clone();
+        let result = outline(&modern, limits()).unwrap();
+        let d = declaration(&result, "model");
+        assert_eq!(d.declaration.id, None);
+        assert_eq!(text(&modern, d.id_literal_span.unwrap()), literal);
+        assert_eq!(modern, before);
+        let errors = parse(&modern).unwrap_err();
+        assert!(
+            errors
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12")
+                    && error.span.start == modern.find(&literal).unwrap())
+        );
+        // Intentional compatibility correction: old analyze yielded Some(Id(1))
+        // here despite lint rejecting the header. It now shares outline's None.
+        let analysis = analyze(&modern);
+        assert_eq!(
+            analysis
+                .declarations
+                .iter()
+                .find(|d| d.alias == "model")
+                .unwrap()
+                .id,
+            None
+        );
+        assert!(
+            analysis
+                .diagnostics
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12"))
+        );
+        let legacy_source = format!("arcadia 1; project \"Legacy\" id {literal} {{}}");
+        let legacy_errors = legacy::parse(&legacy_source).unwrap_err();
+        assert!(
+            legacy_errors
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12"))
+        );
+    }
+}
+
+#[test]
+fn uppercase_and_json_escaped_header_ids_survive_both_parsers_and_outline() {
+    let expected = Id::from_u128(0xabcdef);
+    let canonical = expected.to_string();
+    let uppercase = canonical.to_uppercase();
+    assert_ne!(uppercase, canonical);
+    for raw in [uppercase.clone(), format!("\\u0030{}", &uppercase[1..])] {
+        let literal = format!("\"{raw}\"");
+        let decoded: String = serde_json::from_str(&literal).unwrap();
+        assert!(has_uuid_header_shape(&decoded));
+        let modern = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+        let result = outline(&modern, limits()).unwrap();
+        let d = declaration(&result, "model");
+        assert_eq!(d.declaration.id, Some(expected));
+        assert_eq!(text(&modern, d.id_literal_span.unwrap()), literal);
+        assert_eq!(result.source.as_bytes(), modern.as_bytes());
+        assert_eq!(parse(&modern).unwrap().id, expected);
+        let analysis = analyze(&modern);
+        assert_eq!(analysis.declarations[0].id, Some(expected));
+        assert!(
+            !analysis
+                .diagnostics
+                .iter()
+                .any(|error| error.severity == crate::validation::Severity::Error)
+        );
+        let legacy_source = format!("arcadia 1; project \"Legacy\" id {literal} {{}}");
+        assert_eq!(legacy::parse(&legacy_source).unwrap().id, expected);
+    }
+}
+
+#[test]
+fn header_shape_still_requires_valid_hexadecimal_uuid_data() {
+    let raw = "00000000-0000-0000-0000-00000000000Z";
+    assert!(has_uuid_header_shape(raw));
+    assert!(Id::parse_str(raw).is_err());
+    let literal = format!("\"{raw}\"");
+    let source = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+    let result = outline(&source, limits()).unwrap();
+    let d = declaration(&result, "model");
+    assert_eq!(d.declaration.id, None);
+    assert_eq!(text(&source, d.id_literal_span.unwrap()), literal);
+    assert!(
+        parse(&source)
+            .unwrap_err()
+            .iter()
+            .any(|error| error.message == "Invalid UUID identity.")
+    );
+    assert_eq!(analyze(&source).declarations[0].id, None);
+}

crates/oa-desktop/Cargo.toml

@@ -18,6 +18,7 @@ serde_json.workspace = true
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
 tokio = { version = "1", features = ["rt", "time"] }
 tempfile = "3"
+unicode-segmentation = "1.13.3"
 
 [dev-dependencies]
 iced_runtime = "0.14"

crates/oa-desktop/src/app.rs

@@ -2,11 +2,15 @@ pub(crate) mod architecture_authoring;
 #[cfg(test)]
 mod architecture_authoring_tests;
 mod checkpoints;
+mod diagram_reveal;
 #[cfg(test)]
 mod diagram_selection_tests;
+mod diagram_usages;
 mod hosted;
+mod reference_authoring;
 #[cfg(test)]
 mod review_navigation_tests;
+mod source_symbols;
 #[cfg(test)]
 mod transition_context_tests;
 #[cfg(test)]
@@ -57,7 +61,7 @@ mod direct_scenario_tests {
         }
     }
     #[test]
-    fn direct_scenario_scroll_and_real_resize_invalidate_only_pointer_context() {
+    fn direct_scenario_camera_details_and_real_resize_invalidate_only_pointer_context() {
         let (mut app, f) = setup();
         let original = app.document.bundle().clone();
         let event = begin(&app, &f);
@@ -73,18 +77,26 @@ mod direct_scenario_tests {
         let _ = app.update(Message::ScenarioCanvas(event));
         assert!(!app.behavior.has_pending());
         let context = app.scenario_context().unwrap();
-        for (area, offset) in [
-            (scenario::ScrollArea::Canvas, iced::Vector::new(30., 150.)),
-            (scenario::ScrollArea::Page, iced::Vector::new(0., 90.)),
-        ] {
+        let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Camera(
+            context,
+            app.camera_epoch,
+            behavior::canvas_workspace::Event::Pan(iced::Vector::new(30., 150.)),
+        )));
+        assert_ne!(app.scenario_context(), Some(context));
+        let context = app.scenario_context().unwrap();
+        for offset in [iced::Vector::new(0., 90.), iced::Vector::new(0., 150.)] {
             let before = app.scenario_context().unwrap();
             let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
-                context, area, offset,
+                context,
+                scenario::ScrollArea::Page,
+                offset,
             )));
             assert_ne!(app.scenario_context(), Some(before));
             let current = app.scenario_context().unwrap();
             let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
-                context, area, offset,
+                context,
+                scenario::ScrollArea::Page,
+                offset,
             )));
             assert_eq!(
                 app.scenario_context(),
@@ -113,7 +125,7 @@ mod direct_scenario_tests {
             }
             let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
                 stale,
-                scenario::ScrollArea::Canvas,
+                scenario::ScrollArea::Page,
                 iced::Vector::new(0., 900.),
             )));
             assert_eq!(app.scenario_context(), Some(current));
@@ -318,6 +330,7 @@ pub struct FilePrompt {
 
 #[derive(Debug, Clone)]
 pub enum Message {
+    BehaviorControl(behavior::canvas_workspace::Intent),
     Architecture(architecture_authoring::Event),
     Home(crate::home::Event),
     CheckpointTick,
@@ -371,6 +384,8 @@ pub enum Message {
     FieldValuePath(String, crate::data_values::FieldPathKey),
     FieldValueBrowse(String, Option<crate::data_values::FieldPathKey>, usize),
     FieldReferenceBrowse(String, String, usize),
+    FieldReferenceOpen(crate::forms::reference_chooser::adapter::Open),
+    FieldReferenceEvent(crate::forms::reference_chooser::Event),
     FieldVariant(String, Value),
     FieldArray(String, Option<usize>, i32),
     Apply,
@@ -415,9 +430,18 @@ pub enum Message {
     Linted(u64, Result<Vec<SourceDiagnostic>, String>),
     SourceDiagnostic(usize),
     SourceRelated(SourceLocation),
-    SourceViewport,
+    SourceViewport(Option<Id>),
+    SourceSymbols(
+        crate::source_navigation::SymbolContext,
+        crate::source_navigation::SymbolEvent,
+    ),
+    SourceSymbolsReady(crate::source_navigation::Completion),
+    DiagramUsage(crate::diagram_usage::Event),
+    DiagramUsagesReady(crate::diagram_usage::Completion),
+    DiagramRevealViewport(crate::diagram_usage::Context, u64, iced::Size),
     SourceForSelection,
     SourceNavigation(crate::source_navigation::Event),
+    SourceFindClose(crate::source_navigation::SymbolContext, Id),
     Save(bool),
     SavePath(Option<PathBuf>),
     Saved(Result<Option<FileSnapshot>, SaveFailure>),
@@ -445,10 +469,14 @@ pub struct App {
     pub hosted: crate::hosted::State,
     pub connection: Option<crate::connection_edit::Session>,
     pub model_menu: Option<crate::model_menu::Opened>,
+    reference_authoring: reference_authoring::State,
     pub source_tree: crate::source_tree::State,
     menu_sequence: u64,
     pub canvas_document: Id,
     pub canvas_epoch: u64,
+    /// Camera batches survive their own updates, never external presentation changes.
+    pub camera_epoch: u64,
+    camera_boundary_epoch: u64,
     pub selected_bend: Option<(Id, usize)>,
     pub exact_strings: bool,
     pub document: Document,
@@ -491,6 +519,17 @@ pub struct App {
     pub source_jump: Option<text_editor::Cursor>,
     source_select_line: bool,
     pub source_navigation: crate::source_navigation::State,
+    source_find_instance: Id,
+    pub source_symbols: crate::source_navigation::SymbolState,
+    pub(crate) diagram_usages: Option<crate::diagram_usage::Panel>,
+    pub(crate) diagram_navigation_focus: Option<crate::diagram_usage::Focus>,
+    source_diagram_job: Option<Id>,
+    diagram_lookup_in_flight: Option<Id>,
+    pending_diagram_reveal: Option<(
+        crate::diagram_usage::Context,
+        crate::diagram_usage::Usage,
+        u64,
+    )>,
     pub model_issues: Vec<validation::Issue>,
     pub migration: Option<persistence::MigrationReport>,
     source_version: u64,
@@ -547,10 +586,13 @@ impl App {
             checkpoint_close: None,
             connection: None,
             model_menu: None,
+            reference_authoring: Default::default(),
             source_tree: Default::default(),
             menu_sequence: 0,
             canvas_document: Id::new_v4(),
             canvas_epoch: 0,
+            camera_epoch: 0,
+            camera_boundary_epoch: 0,
             selected_bend: None,
             exact_strings: false,
             document,
@@ -596,6 +638,13 @@ impl App {
             source_jump: None,
             source_select_line: false,
             source_navigation: crate::source_navigation::State::default(),
+            source_find_instance: Id::new_v4(),
+            source_symbols: crate::source_navigation::SymbolState::default(),
+            diagram_usages: None,
+            diagram_navigation_focus: None,
+            source_diagram_job: None,
+            diagram_lookup_in_flight: None,
+            pending_diagram_reveal: None,
             model_issues,
             migration: None,
             source_version: 0,
@@ -649,6 +698,7 @@ impl App {
         self.lint_requested = None;
     }
     fn show_source_file(&mut self, restore_cursor: bool) {
+        self.source_symbols.reveal = None;
         self.source_tree.reveal(&self.source_workspace.active);
         self.source_select_line = false;
         let source = self.source_workspace.text().to_owned();
@@ -663,6 +713,9 @@ impl App {
                     .map(|b| b.cursor)
             })
             .flatten();
+        if let Some(cursor) = self.source_jump {
+            self.queue_source_reveal(cursor, false);
+        }
     }
     fn selected_architecture_placement(&self) -> Option<Id> {
         self.active_diagram
@@ -916,6 +969,8 @@ impl App {
         let canvas_size = self.canvas_size;
         let source_version = self.source_version + 1;
         let lint_running = self.lint_running;
+        let navigation_in_flight = self.source_symbols.in_flight;
+        let diagram_lookup_in_flight = self.diagram_lookup_in_flight;
         let guide = std::mem::take(&mut self.guide);
         let mut hosted = std::mem::take(&mut self.hosted);
         hosted.leave_document();
@@ -927,6 +982,8 @@ impl App {
         self.canvas_size = canvas_size;
         self.source_version = source_version;
         self.lint_running = lint_running;
+        self.source_symbols.in_flight = navigation_in_flight;
+        self.diagram_lookup_in_flight = diagram_lookup_in_flight;
         self.guide = guide;
         self.path = path;
         self.status = "Project ready".into();
@@ -1027,16 +1084,70 @@ impl App {
             crate::model_menu::popup(self),
         )
         .into();
-        crate::hosted::view::overlay(self, base)
+        crate::source_navigation::interaction::observe(
+            crate::behavior::scenario::focus::root(
+                behavior::canvas_workspace::focus_root(
+                    crate::hosted::view::overlay(
+                        self,
+                        self.reference_overlay(crate::diagram_usage::view::overlay(self, base)),
+                    ),
+                    behavior::canvas_workspace::Scope::input_owner(self),
+                ),
+                self.scenario_focus_owner(),
+            ),
+            self.source_symbols.raw_interaction.clone(),
+        )
     }
     pub fn subscription(&self) -> Subscription<Message> {
         Subscription::batch([
+            self.diagram_usages
+                .as_ref()
+                .map_or_else(Subscription::none, |panel| {
+                    iced::event::listen_with(|event, status, _| {
+                        let iced::Event::Keyboard(keyboard::Event::KeyPressed {
+                            key,
+                            modifiers,
+                            ..
+                        }) = event
+                        else {
+                            return None;
+                        };
+                        if !modifiers.is_empty() {
+                            return None;
+                        }
+                        match key {
+                            keyboard::Key::Named(keyboard::key::Named::ArrowUp) => Some(-1i8),
+                            keyboard::Key::Named(keyboard::key::Named::ArrowDown) => Some(1i8),
+                            keyboard::Key::Named(keyboard::key::Named::Enter)
+                                if status == iced::event::Status::Ignored =>
+                            {
+                                Some(0i8)
+                            }
+                            _ => None,
+                        }
+                    })
+                    .with(panel.token)
+                    .map(|(token, step)| {
+                        Message::DiagramUsage(if step == 0 {
+                            crate::diagram_usage::Event::Activate(token)
+                        } else {
+                            crate::diagram_usage::Event::Move(token, step)
+                        })
+                    })
+                }),
             iced::time::every(std::time::Duration::from_secs(10)).map(|_| Message::CheckpointTick),
             window::close_requests().map(|id| Message::Request(Pending::Close(id))),
             window::resize_events().map(|(_, size)| Message::WindowResized(size)),
             architecture_authoring::subscription(self),
+            // Use one captured-Escape bridge: a focused Find input consumes
+            // Escape, while modal priority remains in the ordinary handler.
             behavior::creation::subscription(
-                self.behavior.creation.has_pending() || self.behavior.source_active(),
+                self.behavior.creation.has_pending()
+                    || self.diagram_usages.is_some()
+                    || self.behavior.source_active()
+                    || (self.page == Page::Text
+                        && (self.source_symbols.open || self.source_navigation.open)
+                        && self.architecture.is_none()),
             )
             .map(|()| Message::Escape),
             iced::event::listen_with(|event, status, _| {
@@ -1083,6 +1194,201 @@ impl App {
         ])
     }
     pub fn update(&mut self, message: Message) -> Task<Message> {
+        let usage_viewport = self.diagram_reveal_viewport(&message);
+        let window_resized = matches!(&message, Message::WindowResized(_));
+        // Reject stale measurements before legacy viewport handlers can change
+        // dimensions or invalidate the exact pending destination epoch.
+        if self.pending_diagram_reveal.is_some()
+            && Self::is_diagram_viewport(&message)
+            && usage_viewport.is_none()
+        {
+            return Task::none();
+        }
+        self.reconcile_pending_diagram_reveal(&message);
+        if let Message::BehaviorControl(intent) = message {
+            return self.behavior_control(intent);
+        }
+        let camera = matches!(
+            &message,
+            Message::ScenarioCanvas(crate::behavior::scenario::CanvasEvent::Camera(..))
+                | Message::TopologyCanvas(crate::behavior::topology::CanvasEvent::Camera(..))
+        );
+        let before = self.camera_boundary();
+        let task = self.update_inner(message);
+        if window_resized && let Some((_, _, epoch)) = &mut self.pending_diagram_reveal {
+            *epoch = self.canvas_epoch;
+        }
+        if let Some(surface) = usage_viewport {
+            self.finish_diagram_reveal(surface);
+        }
+        if self
+            .diagram_navigation_focus
+            .as_ref()
+            .is_some_and(|focus| self.diagram_focus(focus.usage.surface).is_none())
+        {
+            self.diagram_navigation_focus = None;
+        }
+        if !camera && self.camera_boundary() != before {
+            self.camera_epoch = self.camera_epoch.wrapping_add(1);
+            self.camera_boundary_epoch = self.canvas_epoch;
+        }
+        task
+    }
+    fn behavior_control(&mut self, intent: behavior::canvas_workspace::Intent) -> Task<Message> {
+        use behavior::canvas_workspace::{self, Event as Camera, Scope};
+        use behavior::scenario::CanvasEvent as Scenario;
+        use behavior::topology::CanvasEvent as Process;
+        if Scope::input_owner(self) != Some(intent.scope) {
+            return Task::none();
+        }
+        let mut message = *intent.message;
+        let scope = intent.scope;
+        let valid_scenario = |c: behavior::scenario::Context| {
+            c.document == scope.document
+                && c.scenario == scope.owner
+                && c.revision == scope.revision
+                && self.camera_toolbar_epoch(c.epoch)
+        };
+        let valid_process = |c: behavior::topology::Context| {
+            c.document == scope.document
+                && c.owner == scope.owner
+                && c.revision == scope.revision
+                && self.camera_toolbar_epoch(c.epoch)
+        };
+        // This whitelist contains only the production presentation controls.
+        // A stamped toolbar cannot smuggle an arbitrary authoring command.
+        match &mut message {
+            Message::ScenarioCanvas(Scenario::Camera(c, lifetime, Camera::Focus))
+                if valid_scenario(*c) && *lifetime == scope.epoch =>
+            {
+                return canvas_workspace::focus_task(scope, Camera::Focus);
+            }
+            Message::TopologyCanvas(Process::Camera(c, lifetime, Camera::Focus))
+                if valid_process(*c) && *lifetime == scope.epoch =>
+            {
+                return canvas_workspace::focus_task(scope, Camera::Focus);
+            }
+            Message::ScenarioCanvas(
+                Scenario::Zoom(c, _)
+                | Scenario::Choose(c, _)
+                | Scenario::Focus(c)
+                | Scenario::Shelf(c, _),
+            ) if valid_scenario(*c) => {
+                c.epoch = self.canvas_epoch;
+            }
+            Message::TopologyCanvas(
+                Process::Zoom(c, _) | Process::Choose(c, _) | Process::Focus(c),
+            ) if valid_process(*c) => {
+                c.epoch = self.canvas_epoch;
+            }
+            Message::Behavior(behavior::Event::Topology(behavior::topology::Event::Shelf(_)))
+                if self.topology_context().is_some() => {}
+            _ => return Task::none(),
+        }
+        let task = self.update(message);
+        // Reapplying Fit or a tool also ends a held gesture. Focus is stamped
+        // after the action, for Iced's final-view ordering.
+        if self.camera_epoch == scope.epoch {
+            self.camera_epoch = self.camera_epoch.wrapping_add(1);
+            self.camera_boundary_epoch = self.canvas_epoch;
+        }
+        let focus = Scope::input_owner(self).map_or_else(Task::none, |scope| {
+            canvas_workspace::focus_task(scope, Camera::ControlFocus(intent.name))
+        });
+        Task::batch([task, focus])
+    }
+    fn camera_toolbar_epoch(&self, epoch: u64) -> bool {
+        epoch >= self.camera_boundary_epoch && epoch <= self.canvas_epoch
+    }
+    fn camera_boundary(&self) -> impl PartialEq + use<> {
+        (
+            self.canvas_epoch,
+            self.canvas_document,
+            self.document.revision(),
+            crate::behavior::selected_owner(self),
+            self.page,
+            self.window_size,
+            crate::behavior::canvas_workspace::keyboard_enabled(self),
+            self.behavior.has_pending(),
+            self.draft_dirty(),
+            self.source_dirty(),
+            self.behavior.topology.camera_boundary(),
+            self.behavior.scenario.camera_boundary(),
+        )
+    }
+    fn update_inner(&mut self, message: Message) -> Task<Message> {
+        let message = match message {
+            Message::SourceFindClose(context, instance) => {
+                if context != self.source_symbol_context()
+                    || instance != self.source_find_instance
+                    || !self.source_navigation.open
+                    || !self.source_navigation_available()
+                {
+                    return Task::none();
+                }
+                // Only the checked envelope may enter the legacy Close handler.
+                Message::SourceNavigation(crate::source_navigation::Event::Close)
+            }
+            Message::SourceNavigation(crate::source_navigation::Event::Close) => {
+                return Task::none();
+            }
+            message => message,
+        };
+        if let Message::SourceSymbols(context, _) = &message
+            && (context.session != self.source_workspace.session()
+                || context.path != self.source_workspace.active)
+        {
+            return Task::none();
+        }
+        // Internal results and geometry do not constitute a new user intent.
+        // Process query completion even behind a modal to release its worker slot;
+        // its handler independently refuses navigation outside the live editor.
+        if let Message::SourceSymbolsReady(completion) = message {
+            return self.source_symbols_ready(completion);
+        }
+        if let Message::DiagramUsagesReady(completion) = message {
+            return self.diagram_usages_ready(completion);
+        }
+        if !matches!(
+            &message,
+            Message::CheckpointTick
+                | Message::CheckpointWritten(..)
+                | Message::Lint(_)
+                | Message::Linted(..)
+                | Message::SourceViewport(_)
+                | Message::WindowResized(_)
+                | Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+        ) {
+            self.source_interaction();
+        }
+        if let Message::DiagramUsage(event) = message {
+            return self.diagram_usage_event(event);
+        }
+        if let Some(panel) = &self.diagram_usages {
+            if matches!(&message, Message::Request(Pending::Close(_))) {
+                self.diagram_usages = None;
+                return self.update(message);
+            }
+            if matches!(&message, Message::Escape) {
+                return self.diagram_usage_event(crate::diagram_usage::Event::Close(panel.token));
+            }
+            if !matches!(
+                &message,
+                Message::CheckpointTick
+                    | Message::CheckpointWritten(..)
+                    | Message::Lint(_)
+                    | Message::Linted(..)
+                    | Message::WindowResized(_)
+                    | Message::CanvasResized(_)
+                    | Message::SourceViewport(_)
+            ) {
+                return Task::none();
+            }
+        }
+        if let Some(task) = self.reference_message(&message) {
+            return task;
+        }
         if matches!(&message, Message::Connection(_))
             && self
                 .architecture
@@ -1147,7 +1453,7 @@ impl App {
                     | Message::CanvasResized(_)
                     | Message::Lint(_)
                     | Message::Linted(_, _)
-                    | Message::SourceViewport
+                    | Message::SourceViewport(_)
                     | Message::Request(Pending::Close(_))
             )
         {
@@ -1193,7 +1499,7 @@ impl App {
                     | Message::Exported(_)
                     | Message::WindowResized(_)
                     | Message::CanvasResized(_)
-                    | Message::SourceViewport
+                    | Message::SourceViewport(_)
             )
         {
             return Task::none();
@@ -1231,7 +1537,7 @@ impl App {
                 | Message::CheckpointLoaded(..)
                 | Message::WindowResized(_)
                 | Message::CanvasResized(_)
-                | Message::SourceViewport
+                | Message::SourceViewport(_)
                 | Message::Lint(_)
                 | Message::Linted(_, _)
                 | Message::Saved(_)
@@ -1305,6 +1611,7 @@ impl App {
             self.last_workspace_page = self.page;
         }
         let mut task = self.handle(message);
+        self.reconcile_reference_chooser();
         self.route_state_diagram_workspace();
         if self.page != Page::Home {
             self.last_workspace_page = self.page;
@@ -1372,8 +1679,23 @@ impl App {
                 epoch: self.canvas_epoch,
             })
     }
+    pub(crate) fn scenario_focus_owner(&self) -> Option<crate::behavior::scenario::focus::Stamp> {
+        if self.busy
+            || self.hosted.visible
+            || self.workflow.is_some()
+            || self.architecture.is_some()
+            || self.model_menu.is_some()
+            || self.file_prompt.is_some()
+            || self.delete_pending
+            || self.pending.is_some()
+        {
+            return None;
+        }
+        self.behavior.scenario.focus_stamp(self.scenario_context()?)
+    }
     fn handle(&mut self, message: Message) -> Task<Message> {
         match message {
+            Message::BehaviorControl(intent) => return self.behavior_control(intent),
             Message::Architecture(event) => return self.architecture_event(event),
             Message::Home(event) => return self.home_event(event),
             Message::CheckpointTick => return self.checkpoint_tick(),
@@ -1389,6 +1711,18 @@ impl App {
             Message::ScenarioCanvas(event) => {
                 use crate::behavior::scenario::{self, CanvasEvent};
                 let context = event.context();
+                if let CanvasEvent::FormShown(_, mount) = event {
+                    if self.scenario_context().is_some_and(|current| {
+                        current.document == context.document
+                            && current.scenario == context.scenario
+                            && current.revision == context.revision
+                    }) && self.scenario_focus_owner().is_some()
+                        && self.behavior.scenario.take_form_focus(mount)
+                    {
+                        return scenario::focus::task(self.scenario_focus_owner().unwrap());
+                    }
+                    return Task::none();
+                }
                 if let CanvasEvent::Viewport(_, size) = event {
                     if self.scenario_context().is_some_and(|current| {
                         current.document == context.document
@@ -1413,9 +1747,9 @@ impl App {
                     return Task::none();
                 }
                 if let CanvasEvent::Scrolled(_, area, offset) = event {
-                    // Canvas and outline notifications may come from the
-                    // same frame. Accept both across the first epoch bump,
-                    // while still rejecting another owner/document/revision.
+                    // Details may report more than once in a frame. Accept the
+                    // current owner's passive clamps across an epoch bump while
+                    // still rejecting another document, owner or revision.
                     if self.scenario_context().is_some_and(|current| {
                         current.document == context.document
                             && current.scenario == context.scenario
@@ -1426,6 +1760,49 @@ impl App {
                     }
                     return Task::none();
                 }
+                if let CanvasEvent::Camera(_, lifetime, input) = event {
+                    use crate::behavior::canvas_workspace::{self, Event};
+                    if lifetime != self.camera_epoch
+                        || !self.scenario_context().is_some_and(|c| {
+                            c.document == context.document
+                                && c.scenario == context.scenario
+                                && c.revision == context.revision
+                        })
+                    {
+                        return Task::none();
+                    }
+                    let scope = canvas_workspace::Scope {
+                        document: context.document,
+                        owner: context.scenario,
+                        revision: context.revision,
+                        epoch: lifetime,
+                    };
+                    if self.behavior.has_pending()
+                        || self.draft_dirty()
+                        || self.source_dirty()
+                        || !canvas_workspace::keyboard_enabled(self)
+                    {
+                        return Task::none();
+                    }
+                    match input {
+                        Event::Focus
+                        | Event::Traverse(_)
+                        | Event::ControlFocus(_)
+                        | Event::ToggleFocus
+                        | Event::Leave => {
+                            return canvas_workspace::focus_task(scope, input);
+                        }
+                        Event::CancelGesture => {
+                            self.canvas_epoch = self.canvas_epoch.wrapping_add(1)
+                        }
+                        input => {
+                            if self.behavior.scenario.camera(input) {
+                                self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+                            }
+                        }
+                    }
+                    return Task::none();
+                }
                 if self.scenario_context() != Some(context) {
                     return Task::none();
                 }
@@ -1439,9 +1816,11 @@ impl App {
                         self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
                     }
                     CanvasEvent::Zoom(_, scale) => {
-                        if self.behavior.scenario.zoom(scale) {
+                        let mut state = std::mem::take(&mut self.behavior.scenario);
+                        if state.camera_zoom(self.project(), context.scenario, scale) {
                             self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
                         }
+                        self.behavior.scenario = state;
                     }
                     CanvasEvent::OpenUse(_, occurrence) => {
                         if self.behavior.has_pending() || self.draft_dirty() || self.source_dirty()
@@ -1525,37 +1904,6 @@ impl App {
                             return Task::none();
                         }
                         match mutation {
-                            CanvasEvent::First(_, tool) => {
-                                let empty = match tool {
-                                    scenario::Tool::Lifeline => !self
-                                        .project()
-                                        .children(context.scenario)
-                                        .any(|e| e.kind() == Kind::Lifeline),
-                                    scenario::Tool::Message | scenario::Tool::Action => {
-                                        self.project()
-                                            .children(context.scenario)
-                                            .any(|e| e.kind() == Kind::Lifeline)
-                                            && !self
-                                                .project()
-                                                .children(context.scenario)
-                                                .any(|e| e.kind() == Kind::Occurrence)
-                                    }
-                                    _ => false,
-                                };
-                                if !empty {
-                                    self.status="This scenario already has content. Use its current authoring tools.".into();
-                                    return Task::none();
-                                }
-                                let mut state = std::mem::take(&mut self.behavior.scenario);
-                                let result = state.update(
-                                    self.project(),
-                                    scenario::Event::Start(context.scenario, tool),
-                                );
-                                self.behavior.scenario = state;
-                                if let Err(error) = result {
-                                    self.status = error;
-                                }
-                            }
                             CanvasEvent::BeginOccurrence {
                                 tool,
                                 slot,
@@ -1563,13 +1911,22 @@ impl App {
                                 ..
                             } => {
                                 let mut state = std::mem::take(&mut self.behavior.scenario);
-                                let result = state.begin_occurrence(
-                                    self.project(),
-                                    context,
-                                    tool,
-                                    slot,
-                                    lifeline,
-                                );
+                                let result = if tool == scenario::Tool::Lifeline {
+                                    state
+                                        .update(
+                                            self.project(),
+                                            scenario::Event::Start(context.scenario, tool),
+                                        )
+                                        .map(|_| ())
+                                } else {
+                                    state.begin_occurrence(
+                                        self.project(),
+                                        context,
+                                        tool,
+                                        slot,
+                                        lifeline,
+                                    )
+                                };
                                 self.behavior.scenario = state;
                                 match result {
                                     Ok(()) => {
@@ -1791,6 +2148,8 @@ impl App {
                 return self.update(Message::Add(child));
             }
             Message::Escape => {
+                let restore_source_focus = self.source_navigation_available()
+                    && (self.source_navigation.open || self.source_symbols.open);
                 if self.behavior.source_back() {
                     self.status =
                         "Returned to the unchanged parent form; no source was created.".into();
@@ -1807,6 +2166,12 @@ impl App {
                     self.status = "Drawing cancelled · Select / move is active".into();
                 }
                 self.source_navigation.open = false;
+                self.source_symbols.open = false;
+                self.source_symbols.results = None;
+                self.source_symbols.notice = None;
+                if restore_source_focus {
+                    self.restore_source_editor_focus();
+                }
                 self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
                 self.selected_bend = None;
             }
@@ -1862,6 +2227,9 @@ impl App {
                         .insert(path, crate::forms::ValueBrowser { scope, page });
                 }
             }
+            Message::FieldReferenceOpen(_) | Message::FieldReferenceEvent(_) => {
+                return Task::none();
+            }
             Message::FieldReferenceBrowse(path, query, page) => {
                 if let Some(draft) = &mut self.draft {
                     let page = if draft
@@ -2102,7 +2470,7 @@ impl App {
                     if let crate::workflow::Workflow::Semantic(state) = &mut workflow {
                         match event {
                             crate::workflow::Event::Semantic(event) => {
-                                state.update(self.project(), event)
+                                state.update(self.project(), *event)
                             }
                             crate::workflow::Event::Apply => {
                                 let focus = state.target(self.project());
@@ -2855,12 +3223,21 @@ impl App {
                                 if self.path.is_none()
                                     || self.path.as_ref() == Some(&receipt.target)
                                 {
+                                    if self.path.as_ref() != Some(&receipt.target) {
+                                        self.source_workspace.reset_navigation_session();
+                                    }
                                     self.path = Some(receipt.target);
+                                    self.document.bind_repair_baseline(disk.reachable_bundle());
                                     self.disk_project = Some(disk);
                                 }
                                 self.status = "Interrupted disk save recovered. Current model and drafts are retained; Save all can be retried.".into();
                             }
                             Err(error) => {
+                                if self.path.is_none()
+                                    || self.path.as_ref() == Some(&receipt.target)
+                                {
+                                    self.document.invalidate_saved_baseline();
+                                }
                                 self.status = format!(
                                     "Disk recovery completed; files could not be reloaded: {error}"
                                 )
@@ -2917,13 +3294,28 @@ impl App {
                 }
             }
             Message::SourceRelated(location) => self.jump_to_source(location),
-            Message::SourceViewport => {
-                if let Some(cursor) = self.source_jump.take() {
-                    self.source_editor.move_to(cursor);
-                    if self.source_select_line && cursor.selection.is_none() {
-                        self.source_editor.perform(text_editor::Action::SelectLine);
-                    }
-                    return iced::widget::operation::focus("source-editor");
+            Message::SourceViewport(ticket) => return self.source_viewport(ticket),
+            Message::SourceFindClose(..) => return Task::none(), // update checks and unwraps it
+            Message::SourceSymbols(_, event) => return self.source_symbol_event(event),
+            Message::SourceSymbolsReady(completion) => {
+                return self.source_symbols_ready(completion);
+            }
+            Message::DiagramUsage(event) => return self.diagram_usage_event(event),
+            Message::DiagramUsagesReady(completion) => {
+                return self.diagram_usages_ready(completion);
+            }
+            Message::DiagramRevealViewport(context, epoch, size) => {
+                if self
+                    .pending_diagram_reveal
+                    .as_ref()
+                    .is_some_and(|(c, _, e)| *c == context && *e == epoch)
+                    && self
+                        .diagram_reveal_viewport(&Message::DiagramRevealViewport(
+                            context, epoch, size,
+                        ))
+                        .is_some()
+                {
+                    return self.handle(Message::CanvasResized(size));
                 }
             }
             Message::ApplySource => {
@@ -2970,6 +3362,7 @@ impl App {
                             return Task::none();
                         }
                         self.page = Page::Text;
+                        self.source_find_instance = Id::new_v4();
                         self.source_navigation.open = true;
                         self.source_navigation.refresh(&self.source_editor.text());
                         return iced::widget::operation::focus(if go_to_line {
@@ -2978,13 +3371,22 @@ impl App {
                             "source-find"
                         });
                     }
-                    Event::Close => self.source_navigation.open = false,
+                    Event::Close => {
+                        let was_open = self.source_navigation.open;
+                        self.source_navigation.open = false;
+                        if was_open {
+                            self.restore_source_editor_focus();
+                        }
+                    }
                     Event::Query(query) => {
                         self.source_navigation.query = query;
                         self.source_navigation.refresh(&self.source_editor.text());
                     }
                     Event::Next(backwards) if self.page == Page::Text => {
                         self.source_jump = self.source_navigation.next(backwards);
+                        if let Some(cursor) = self.source_jump {
+                            self.queue_source_reveal(cursor, false);
+                        }
                         if self.source_jump.is_none() {
                             self.status = "No matching source text.".into();
                         }
@@ -2995,8 +3397,7 @@ impl App {
                         .destination(self.source_editor.line_count())
                     {
                         Ok(cursor) => {
-                            self.source_jump = Some(cursor);
-                            self.source_select_line = true;
+                            self.queue_source_reveal(cursor, true);
                         }
                         Err(error) => self.status = error,
                     },
@@ -3079,6 +3480,9 @@ impl App {
                                 }
                                 self.sync_source();
                             }
+                            if self.path.as_ref() != Some(&receipt.path) {
+                                self.source_workspace.reset_navigation_session();
+                            }
                             self.disk_project = Some(disk);
                             self.path = Some(receipt.path);
                             self.hosted.session = None;
@@ -3677,8 +4081,9 @@ impl App {
                 self.canvas_document = Id::new_v4();
                 self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
                 self.path = Some(path);
+                self.document.bind_repair_baseline(disk.reachable_bundle());
                 self.source_workspace = Workspace::new(&disk.bundle, false);
-                self.source_workspace.reachable = disk.reachable.clone();
+                self.source_workspace.set_reachable(disk.reachable.clone());
                 self.show_source_file(false);
                 self.source_diagnostics = error.diagnostics().to_vec();
                 self.source_version += 1;
@@ -3730,11 +4135,13 @@ impl App {
         let column = prefix
             .rfind('\n')
             .map_or(offset, |start| offset - start - 1);
-        self.source_jump = Some(text_editor::Cursor {
-            position: text_editor::Position { line, column },
-            selection: None,
-        });
-        self.source_select_line = true;
+        self.queue_source_reveal(
+            text_editor::Cursor {
+                position: text_editor::Position { line, column },
+                selection: None,
+            },
+            true,
+        );
     }
 
     fn create_source_file(&mut self) -> Result<(), String> {
@@ -4344,6 +4751,10 @@ fn read_snapshot(path: PathBuf) -> Result<LoadedSnapshot, String> {
 #[path = "app/save_as_tests.rs"]
 mod save_as_tests;
 
+#[cfg(test)]
+#[path = "app/repair_save_state_tests.rs"]
+mod repair_save_state_tests;
+
 #[cfg(test)]
 mod source_project_tests {
     use super::*;

crates/oa-desktop/src/app/architecture_authoring/tests.rs

@@ -70,6 +70,7 @@ fn architecture_f2_routes_selected_node_to_inline_rename_and_exact_undo() {
         view_index: None,
         diagram: app.active_diagram.unwrap(),
         selected: element,
+        navigation_focus: None,
         zoom: app.zoom,
         pan: app.pan,
         context: app.route_context().unwrap(),

crates/oa-desktop/src/app/architecture_authoring_tests.rs

@@ -225,6 +225,7 @@ fn architecture_canvas_left_click_uses_world_coordinate_once_at_zoom_and_pan() {
         view_index: None,
         diagram: app.active_diagram.unwrap(),
         selected: app.selected,
+        navigation_focus: None,
         zoom: app.zoom,
         pan: app.pan,
         context: app.route_context().unwrap(),
@@ -299,6 +300,7 @@ fn architecture_f2_rename_preserves_identity_placement_and_atomic_history() {
         view_index: None,
         diagram: app.active_diagram.unwrap(),
         selected: element,
+        navigation_focus: None,
         zoom: app.zoom,
         pan: app.pan,
         context: app.route_context().unwrap(),

crates/oa-desktop/src/app/diagram_reveal.rs

@@ -0,0 +1,145 @@
+//! Complete a navigation camera after the destination reports its real viewport.
+use super::*;
+use crate::diagram_usage::{Context, Surface};
+#[cfg(test)]
+mod tests;
+
+impl App {
+    pub(super) fn is_diagram_viewport(message: &Message) -> bool {
+        matches!(
+            message,
+            Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+                | Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(..))
+                | Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(..))
+                | Message::StateDiagram(behavior::state_edit::Event::Viewport(..))
+        )
+    }
+    pub(crate) fn architecture_reveal_stamp(&self, diagram: Id) -> Option<(Context, u64)> {
+        self.pending_diagram_reveal
+            .as_ref()
+            .filter(|(_, u, _)| u.surface == Surface::Saved(diagram))
+            .map(|(context, _, epoch)| (*context, *epoch))
+    }
+
+    pub(super) fn diagram_reveal_viewport(&self, message: &Message) -> Option<Surface> {
+        let (context, usage, epoch) = self.pending_diagram_reveal.as_ref()?;
+        if context.document != self.canvas_document
+            || context.revision != self.document.revision()
+            || *epoch != self.canvas_epoch
+        {
+            return None;
+        }
+        let (surface, size, valid) = match message {
+            Message::DiagramRevealViewport(c, e, size) => (
+                usage.surface,
+                *size,
+                c == context
+                    && e == epoch
+                    && self.page == Page::Diagram
+                    && Some(usage.surface.id()) == self.active_diagram,
+            ),
+            Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(c, size)) => (
+                Surface::Process(c.owner),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(c, size)) => (
+                Surface::Scenario(c.scenario),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            Message::StateDiagram(behavior::state_edit::Event::Viewport(c, size)) => (
+                Surface::Saved(c.diagram),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            _ => return None,
+        };
+        (valid
+            && surface == usage.surface
+            && size.width.is_finite()
+            && size.height.is_finite()
+            && size.width > 0.
+            && size.height > 0.)
+            .then_some(surface)
+    }
+
+    pub(super) fn reconcile_pending_diagram_reveal(&mut self, message: &Message) {
+        if !matches!(
+            message,
+            Message::CheckpointTick
+                | Message::CheckpointWritten(..)
+                | Message::Lint(_)
+                | Message::Linted(..)
+                | Message::SourceViewport(_)
+                | Message::WindowResized(_)
+                | Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+                | Message::DiagramUsage(_)
+                | Message::DiagramUsagesReady(_)
+                | Message::SourceSymbolsReady(_)
+                | Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(..))
+                | Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(..))
+                | Message::StateDiagram(behavior::state_edit::Event::Viewport(..))
+        ) {
+            self.pending_diagram_reveal = None;
+            if !Self::is_navigation_camera(message) {
+                self.diagram_navigation_focus = None;
+            }
+        }
+    }
+
+    fn is_navigation_camera(message: &Message) -> bool {
+        if let Message::BehaviorControl(intent) = message {
+            return Self::is_navigation_camera(&intent.message);
+        }
+        matches!(
+            message,
+            Message::Pan(_)
+                | Message::Zoom(_)
+                | Message::Fit
+                | Message::TopologyCanvas(
+                    behavior::topology::CanvasEvent::Camera(..)
+                        | behavior::topology::CanvasEvent::Zoom(..)
+                        | behavior::topology::CanvasEvent::Scrolled(..)
+                        | behavior::topology::CanvasEvent::Focus(..)
+                )
+                | Message::ScenarioCanvas(
+                    behavior::scenario::CanvasEvent::Camera(..)
+                        | behavior::scenario::CanvasEvent::Zoom(..)
+                        | behavior::scenario::CanvasEvent::Scrolled(..)
+                        | behavior::scenario::CanvasEvent::Focus(..)
+                )
+                | Message::StateDiagram(
+                    behavior::state_edit::Event::Pan(..)
+                        | behavior::state_edit::Event::Zoom(..)
+                        | behavior::state_edit::Event::Fit(..)
+                )
+        )
+    }
+
+    pub(super) fn finish_diagram_reveal(&mut self, surface: Surface) {
+        let Some((context, usage, _)) = self.pending_diagram_reveal.take() else {
+            return;
+        };
+        if context.document == self.canvas_document
+            && context.revision == self.document.revision()
+            && usage.surface == surface
+            && !self.draft_dirty()
+            && !self.source_dirty()
+            && !self.behavior.has_pending()
+        {
+            // The normal viewport handler has now stored the measured size.
+            // Target identity was validated for this revision before navigation.
+            self.reveal_diagram_usage(&usage);
+        }
+        self.pending_diagram_reveal = None;
+    }
+}

crates/oa-desktop/src/app/diagram_reveal/tests.rs

@@ -0,0 +1,403 @@
+//! Independent first-layout navigation oracles, through the real App boundary.
+use super::*;
+use crate::diagram_usage::{self as usage, Target, Usage};
+use iced::{Size, Vector};
+use std::collections::BTreeMap;
+
+#[derive(Clone, Copy, Debug)]
+enum Canvas {
+    Architecture,
+    Process,
+    Scenario,
+    State,
+}
+const CANVASES: [Canvas; 4] = [
+    Canvas::Architecture,
+    Canvas::Process,
+    Canvas::Scenario,
+    Canvas::State,
+];
+const WIDE: Size = Size::new(1200., 700.);
+const ACTUAL: Size = Size::new(500., 300.);
+
+fn send(app: &mut App, message: Message) {
+    let _ = app.update(message);
+}
+
+fn fixture(canvas: Canvas) -> (App, Usage) {
+    let mut p = Project::empty();
+    let work = p
+        .add_element(Kind::Activity, Layer::Oa, "Respond", None)
+        .unwrap();
+    let (surface, subject) = match canvas {
+        Canvas::Architecture => {
+            let diagram = p.ensure_diagram(Layer::Oa);
+            p.place(
+                diagram,
+                work,
+                Position {
+                    x: 12_000.,
+                    y: 9_000.,
+                },
+            );
+            (Surface::Saved(diagram), work)
+        }
+        Canvas::Process | Canvas::Scenario => {
+            let kind = if matches!(canvas, Canvas::Process) {
+                Kind::Process
+            } else {
+                Kind::Scenario
+            };
+            let owner = p.add_element(kind, Layer::Oa, "Response", None).unwrap();
+            let occurrence = p
+                .add_element(Kind::Occurrence, Layer::Oa, "Respond here", Some(owner))
+                .unwrap();
+            *p.elements
+                .get_mut(&occurrence)
+                .unwrap()
+                .shared_mut()
+                .unwrap() = SharedBody::Occurrence {
+                body: OccurrenceBody::Action {
+                    action: Some(work),
+                    lifeline: None,
+                },
+                precondition: String::new(),
+                postcondition: String::new(),
+            };
+            let steps = p.elements.get_mut(&owner).unwrap().steps_mut().unwrap();
+            if !steps.contains(&occurrence) {
+                steps.push(occurrence);
+            }
+            (
+                if matches!(canvas, Canvas::Process) {
+                    Surface::Process(owner)
+                } else {
+                    Surface::Scenario(owner)
+                },
+                occurrence,
+            )
+        }
+        Canvas::State => {
+            let machine = p
+                .add_element(Kind::StateMachine, Layer::Oa, "Modes", None)
+                .unwrap();
+            let region = p
+                .add_element(Kind::Region, Layer::Oa, "Main", Some(machine))
+                .unwrap();
+            let state = p
+                .add_element(Kind::State, Layer::Oa, "Ready", Some(region))
+                .unwrap();
+            let diagram = Id::new_v4();
+            p.diagrams.insert(
+                diagram,
+                Diagram {
+                    id: diagram,
+                    alias: "ready_view".into(),
+                    name: "Ready view".into(),
+                    description: String::new(),
+                    layer: Layer::Oa,
+                    projection: ProjectionKind::StateMachine { machine },
+                    nodes: BTreeMap::new(),
+                    routes: vec![],
+                    view_options: Default::default(),
+                },
+            );
+            p.place(
+                diagram,
+                state,
+                Position {
+                    x: 8_000.,
+                    y: 11_000.,
+                },
+            );
+            (Surface::Saved(diagram), state)
+        }
+    };
+    let mut app = App::with_project(p);
+    let found = usage::collect(
+        app.project(),
+        subject,
+        &app.behavior.topology,
+        &app.behavior.scenario,
+    )
+    .into_iter()
+    .find(|u| u.surface == surface && u.target != Target::Whole)
+    .unwrap();
+    app.canvas_size = Some(WIDE);
+    app.behavior.diagram.viewport = Some(WIDE);
+    if let Surface::Process(owner) = surface {
+        app.behavior.topology.enter(app.canvas_document, owner);
+        app.behavior.topology.viewport(WIDE);
+    }
+    if let Surface::Scenario(owner) = surface {
+        app.behavior.scenario.enter(app.canvas_document, owner);
+        app.behavior.scenario.viewport(WIDE);
+    }
+    app.page = Page::Text;
+    (app, found)
+}
+
+fn measurement(
+    canvas: Canvas,
+    context: Context,
+    epoch: u64,
+    surface: Surface,
+    size: Size,
+) -> Message {
+    match canvas {
+        Canvas::Architecture => Message::DiagramRevealViewport(context, epoch, size),
+        Canvas::Process => Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(
+            behavior::topology::Context {
+                document: context.document,
+                owner: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+        Canvas::Scenario => Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(
+            behavior::scenario::Context {
+                document: context.document,
+                scenario: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+        Canvas::State => Message::StateDiagram(behavior::state_edit::Event::Viewport(
+            behavior::state_edit::Context {
+                document: context.document,
+                diagram: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+    }
+}
+
+fn stamp(app: &App) -> (Context, u64) {
+    let (context, _, epoch) = app
+        .pending_diagram_reveal
+        .as_ref()
+        .expect("reveal awaits measured destination");
+    (*context, *epoch)
+}
+
+fn assert_centered(app: &App, canvas: Canvas, target: &Usage) {
+    // All independently authored fixture targets fit ACTUAL at the readable cap.
+    // This oracle does not call the production camera/reveal implementation.
+    let zoom = 1.25;
+    let pan = Vector::new(
+        250. - target.bounds.center_x() * zoom,
+        150. - target.bounds.center_y() * zoom,
+    );
+    match canvas {
+        Canvas::Architecture => {
+            assert_eq!(app.canvas_size, Some(ACTUAL));
+            assert_eq!(app.zoom, zoom);
+            assert_eq!(app.pan, pan);
+            assert!(!app.fit_to_view);
+        }
+        Canvas::State => {
+            assert_eq!(app.behavior.diagram.viewport, Some(ACTUAL));
+            assert_eq!(app.behavior.diagram.zoom, zoom);
+            assert_eq!(app.behavior.diagram.pan, pan);
+            assert!(!app.behavior.diagram.fit);
+        }
+        Canvas::Process => {
+            let mut expected = behavior::topology::State::default();
+            expected.enter(app.canvas_document, target.surface.id());
+            expected.viewport(ACTUAL);
+            expected.zoom(Some(zoom));
+            expected.camera(behavior::canvas_workspace::Event::Pan(pan));
+            assert!(app.behavior.topology.camera_boundary() == expected.camera_boundary());
+        }
+        Canvas::Scenario => {
+            let mut expected = behavior::scenario::State::default();
+            expected.enter(app.canvas_document, target.surface.id());
+            expected.choose_tool(target.surface.id(), behavior::scenario::CanvasTool::Select);
+            expected.viewport(ACTUAL);
+            expected.zoom(Some(zoom));
+            expected.camera(behavior::canvas_workspace::Event::Pan(pan));
+            assert!(app.behavior.scenario.camera_boundary() == expected.camera_boundary());
+        }
+    }
+}
+
+#[test]
+fn all_reveal_surfaces_recenter_once_after_the_real_viewport_and_preserve_authored_state() {
+    for canvas in CANVASES {
+        let (mut app, target) = fixture(canvas);
+        let accepted = app.document.snapshot();
+        let drafts = app.source_workspace.bundle();
+        let revision = app.document.revision();
+        let history = (
+            app.document.can_undo(),
+            app.document.can_redo(),
+            app.document.dirty(),
+        );
+        assert!(app.reveal_diagram_usage(&target));
+        let (context, epoch) = stamp(&app);
+        send(
+            &mut app,
+            measurement(canvas, context, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert_centered(&app, canvas, &target);
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        assert_eq!(app.source_workspace.bundle(), drafts);
+        assert_eq!(app.document.revision(), revision);
+        assert_eq!(
+            (
+                app.document.can_undo(),
+                app.document.can_redo(),
+                app.document.dirty()
+            ),
+            history
+        );
+        // The exact delivered callback is a replay after the one-shot is consumed.
+        let camera = app.camera_boundary();
+        send(
+            &mut app,
+            measurement(canvas, context, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert!(app.camera_boundary() == camera);
+        assert_centered(&app, canvas, &target);
+    }
+}
+
+#[test]
+fn malformed_or_wrong_stamp_measurements_cannot_poison_a_pending_reveal() {
+    for canvas in CANVASES {
+        for invalid in 0..6 {
+            let (mut app, target) = fixture(canvas);
+            assert!(app.reveal_diagram_usage(&target));
+            let (context, epoch) = stamp(&app);
+            let camera = app.camera_boundary();
+            let mut stale = context;
+            let mut wrong_epoch = epoch;
+            let mut size = Size::new(111., 122.);
+            match invalid {
+                0 => stale.document = Id::new_v4(),
+                1 => stale.revision = stale.revision.wrapping_add(1),
+                2 => wrong_epoch = wrong_epoch.wrapping_add(1),
+                3 => size.width = f32::NAN,
+                4 => size.height = f32::INFINITY,
+                _ => size.width = 0.,
+            }
+            send(
+                &mut app,
+                measurement(canvas, stale, wrong_epoch, target.surface, size),
+            );
+            assert!(
+                app.pending_diagram_reveal.is_some(),
+                "{canvas:?} invalid case {invalid}"
+            );
+            assert_eq!(stamp(&app), (context, epoch));
+            assert_eq!(app.canvas_epoch, epoch);
+            assert!(
+                app.camera_boundary() == camera,
+                "{canvas:?} invalid case {invalid}"
+            );
+            send(
+                &mut app,
+                measurement(canvas, context, epoch, target.surface, ACTUAL),
+            );
+            assert!(app.pending_diagram_reveal.is_none());
+            assert_centered(&app, canvas, &target);
+        }
+    }
+}
+
+#[test]
+fn actual_window_resize_before_first_measurement_retains_focus_for_the_new_context() {
+    for canvas in CANVASES {
+        let (mut app, target) = fixture(canvas);
+        let accepted = app.document.snapshot();
+        assert!(app.reveal_diagram_usage(&target));
+        let (context, old_epoch) = stamp(&app);
+        send(&mut app, Message::WindowResized(Size::new(1100., 700.)));
+        let (current, epoch) = stamp(&app);
+        assert_eq!(current, context);
+        assert_eq!(epoch, app.canvas_epoch);
+        if matches!(canvas, Canvas::Process | Canvas::Scenario) {
+            assert_ne!(epoch, old_epoch);
+            let camera = app.camera_boundary();
+            send(
+                &mut app,
+                measurement(canvas, context, old_epoch, target.surface, ACTUAL),
+            );
+            assert_eq!(stamp(&app), (current, epoch));
+            assert!(app.camera_boundary() == camera);
+        }
+        send(
+            &mut app,
+            measurement(canvas, current, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert_centered(&app, canvas, &target);
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    }
+}
+
+#[test]
+fn user_camera_edit_and_navigation_cancel_deferred_focus_without_late_snapping() {
+    for canvas in CANVASES {
+        for action in 0..3 {
+            let (mut app, target) = fixture(canvas);
+            let accepted = app.document.snapshot();
+            assert!(app.reveal_diagram_usage(&target));
+            let (context, epoch) = stamp(&app);
+            let event = match action {
+                0 => match canvas {
+                    Canvas::Architecture => Message::Pan(Vector::new(31., -17.)),
+                    Canvas::State => Message::StateDiagram(behavior::state_edit::Event::Pan(
+                        app.state_context().unwrap(),
+                        Vector::new(31., -17.),
+                    )),
+                    Canvas::Process => {
+                        Message::TopologyCanvas(behavior::topology::CanvasEvent::Camera(
+                            app.topology_context().unwrap(),
+                            app.camera_epoch,
+                            behavior::canvas_workspace::Event::Pan(Vector::new(31., -17.)),
+                        ))
+                    }
+                    Canvas::Scenario => {
+                        Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Camera(
+                            app.scenario_context().unwrap(),
+                            app.camera_epoch,
+                            behavior::canvas_workspace::Event::Pan(Vector::new(31., -17.)),
+                        ))
+                    }
+                },
+                1 => Message::Field("/name".into(), "Pending title edit".into()),
+                _ => Message::Page(Page::Catalog),
+            };
+            send(&mut app, event);
+            assert!(
+                app.pending_diagram_reveal.is_none(),
+                "{canvas:?} action {action}"
+            );
+            let camera = app.camera_boundary();
+            let page = app.page;
+            // A stale layout callback at the already retained size cannot
+            // restore the old navigation camera after deliberate user input.
+            send(
+                &mut app,
+                measurement(canvas, context, epoch, target.surface, WIDE),
+            );
+            assert!(app.pending_diagram_reveal.is_none());
+            assert!(
+                app.camera_boundary() == camera,
+                "{canvas:?} action {action}"
+            );
+            assert_eq!(app.page, page);
+            assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+            if action == 1 {
+                assert!(app.draft_dirty());
+            }
+        }
+    }
+}

crates/oa-desktop/src/app/diagram_usages.rs

@@ -0,0 +1,445 @@
+//! Navigation-only adapter: validates destinations before changing presentation.
+use super::*;
+use crate::diagram_usage::{self as usage, Context, Event, Panel, Surface, Target, Usage};
+#[cfg(test)]
+mod tests;
+
+impl App {
+    pub(crate) fn diagram_usage_message(&self, subject: Id) -> Message {
+        Message::DiagramUsage(Event::Open(Context {
+            document: self.canvas_document,
+            revision: self.document.revision(),
+            subject,
+        }))
+    }
+
+    fn usage_navigation_available(&self) -> bool {
+        !self.busy
+            && self.pending.is_none()
+            && self.file_prompt.is_none()
+            && !self.delete_pending
+            && self.workflow.is_none()
+            && !self.hosted.visible
+            && self.architecture.is_none()
+            && !self.reference_input_active()
+            && !self.behavior.has_pending()
+            && !self.draft_dirty()
+            && !self.source_dirty()
+    }
+
+    /// Admit at most one expensive lookup, including one accepted Project clone.
+    /// A replacement panel waits for the previous worker's exact completion.
+    fn start_diagram_lookup(&mut self) -> Task<Message> {
+        let Some(panel) = self.diagram_usages.as_ref() else {
+            return Task::none();
+        };
+        if !panel.loading || self.diagram_lookup_in_flight.is_some() {
+            return Task::none();
+        }
+        let (token, context) = (panel.token, panel.context);
+        if context.document != self.canvas_document
+            || context.revision != self.document.revision()
+            || !self.usage_navigation_available()
+        {
+            let panel = self.diagram_usages.as_mut().unwrap();
+            panel.loading = false;
+            panel.notice = Some(
+                "The model or pending edits changed. Reopen diagram navigation when ready.".into(),
+            );
+            return Task::none();
+        }
+        let project = self.project().clone();
+        let presentation = self.behavior.topology.usage_snapshot();
+        self.diagram_lookup_in_flight = Some(token);
+        Task::perform(
+            async move {
+                let result = tokio::task::spawn_blocking(move || {
+                    let process = presentation.into_query_state();
+                    let scenario = behavior::scenario::State::default();
+                    usage::collect(&project, context.subject, &process, &scenario)
+                })
+                .await
+                .map_err(|error| format!("Diagram lookup failed: {error}. Close and try again."));
+                usage::Completion {
+                    token,
+                    context,
+                    result,
+                }
+            },
+            Message::DiagramUsagesReady,
+        )
+    }
+
+    fn refresh_diagram_lookup(&mut self, notice: &str) -> Task<Message> {
+        let Some(panel) = self.diagram_usages.as_mut() else {
+            return Task::none();
+        };
+        panel.token = Id::new_v4();
+        panel.context.revision = self.document.revision();
+        panel.usages.clear();
+        panel.loading = true;
+        panel.page = 0;
+        panel.cursor = 0;
+        panel.destination = None;
+        panel.notice = Some(notice.into());
+        self.start_diagram_lookup()
+    }
+
+    /// Must run before modal/input dispatch. A closed or replaced panel still
+    /// owns its worker slot until this exact completion arrives.
+    pub(super) fn diagram_usages_ready(&mut self, completion: usage::Completion) -> Task<Message> {
+        if self.diagram_lookup_in_flight != Some(completion.token) {
+            return Task::none();
+        }
+        self.diagram_lookup_in_flight = None;
+        let Some(panel) = self.diagram_usages.as_ref() else {
+            return Task::none();
+        };
+        if panel.context.document != self.canvas_document {
+            self.diagram_usages = None;
+            return Task::none();
+        }
+        if panel.context.revision != self.document.revision() {
+            return self
+                .refresh_diagram_lookup("The model changed. Review the refreshed destinations.");
+        }
+        if panel.token != completion.token {
+            // A newer Open/refresh waited without cloning or spawning a second job.
+            return self.start_diagram_lookup();
+        }
+        let panel = self.diagram_usages.as_mut().unwrap();
+        if panel.context != completion.context || !panel.loading {
+            panel.loading = false;
+            panel.notice = Some(
+                "This lookup no longer matches the requested model. Close and try again.".into(),
+            );
+            return Task::none();
+        }
+        panel.loading = false;
+        match completion.result {
+            Ok(usages) => panel.usages = usages,
+            Err(error) => panel.notice = Some(error),
+        }
+        Task::none()
+    }
+
+    /// Selection validates one destination only; opening the chooser does the
+    /// whole-project scan on its worker, never on the GUI thread.
+    fn current_surface_usages(&self, subject: Id, surface: Surface) -> Vec<Usage> {
+        match surface {
+            Surface::Saved(diagram) => {
+                usage::saved_usages_for(self.project(), subject, Some(diagram))
+            }
+            Surface::Process(owner) => {
+                self.behavior
+                    .topology
+                    .diagram_usages(self.project(), owner, subject)
+            }
+            Surface::Scenario(owner) => {
+                self.behavior
+                    .scenario
+                    .diagram_usages(self.project(), owner, subject)
+            }
+        }
+    }
+
+    pub(super) fn diagram_usage_event(&mut self, event: Event) -> Task<Message> {
+        if let Event::Open(context) = event {
+            if context.document != self.canvas_document
+                || context.revision != self.document.revision()
+                || !self.project().contains(context.subject)
+            {
+                return Task::none();
+            }
+            if !self.usage_navigation_available() {
+                self.status = "Apply or revert pending edits before opening diagram navigation. Your inputs are retained.".into();
+                return Task::none();
+            }
+            let mut panel = Panel::new(context, Vec::new());
+            panel.loading = true;
+            let filter_id = format!("diagram-usage-filter-{}", panel.token);
+            self.diagram_usages = Some(panel);
+            self.model_menu = None;
+            // Only an accepted new chooser supersedes the previous reveal.
+            // Rejected/stale panel envelopes leave its first measurement intact.
+            self.pending_diagram_reveal = None;
+            self.diagram_navigation_focus = None;
+            self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+            return Task::batch([
+                self.start_diagram_lookup(),
+                iced::widget::operation::focus(filter_id),
+            ]);
+        }
+        let token = match &event {
+            Event::Open(_) => unreachable!(),
+            Event::Close(t)
+            | Event::Search(t, _)
+            | Event::Page(t, _)
+            | Event::Move(t, _)
+            | Event::Activate(t)
+            | Event::Destination(t, _)
+            | Event::Choose(t, _) => *t,
+        };
+        let Some(panel) = &self.diagram_usages else {
+            return Task::none();
+        };
+        if panel.token != token {
+            return Task::none();
+        }
+        if matches!(event, Event::Close(_)) {
+            self.diagram_usages = None;
+            if self.page == Page::Text {
+                self.restore_source_editor_focus();
+            }
+            return Task::none();
+        }
+        if panel.context.document != self.canvas_document {
+            self.diagram_usages = None;
+            return Task::none();
+        }
+        if panel.context.revision != self.document.revision() {
+            return self
+                .refresh_diagram_lookup("The model changed. Review the refreshed destinations.");
+        }
+        if panel.loading {
+            // Search and Close remain useful while loading; queued activation
+            // must not perform a synchronous fallback or choose an old row.
+            if let Event::Search(_, query) = event {
+                self.diagram_usages.as_mut().unwrap().search = query;
+            }
+            return Task::none();
+        }
+        match event {
+            Event::Move(_, direction) => {
+                let panel = self.diagram_usages.as_ref().unwrap();
+                let count = panel.choices(self.project()).len();
+                let panel = self.diagram_usages.as_mut().unwrap();
+                if count > 0 {
+                    panel.cursor = if direction < 0 {
+                        (panel.cursor + count - 1) % count
+                    } else {
+                        (panel.cursor + 1) % count
+                    };
+                    panel.page = panel.cursor / 6;
+                }
+            }
+            Event::Activate(_) => {
+                let panel = self.diagram_usages.as_ref().unwrap();
+                if let Some(event) = panel.choices(self.project()).get(panel.cursor).cloned() {
+                    return self.diagram_usage_event(event);
+                }
+            }
+            Event::Search(_, query) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                panel.search = query;
+                panel.page = 0;
+                panel.cursor = 0;
+            }
+            Event::Page(_, page) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                panel.page = page;
+                panel.cursor = page.saturating_mul(6);
+            }
+            Event::Destination(_, surface) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                if surface.is_none() || panel.usages.iter().any(|u| Some(u.surface) == surface) {
+                    panel.destination = surface;
+                    panel.page = 0;
+                    panel.cursor = 0;
+                }
+            }
+            Event::Choose(_, requested) => {
+                if !self.usage_navigation_available() {
+                    return Task::none();
+                }
+                let subject = self.diagram_usages.as_ref().unwrap().context.subject;
+                let fresh = self
+                    .current_surface_usages(subject, requested.surface)
+                    .into_iter()
+                    .find(|u| u.subject == requested.subject && u.target == requested.target);
+                let Some(fresh) = fresh else {
+                    return self.refresh_diagram_lookup(
+                        "This representation changed. Review the refreshed destinations.",
+                    );
+                };
+                if self.reveal_diagram_usage(&fresh) {
+                    self.diagram_usages = None;
+                    self.status = format!(
+                        "{} · {} in {}",
+                        self.project().named(subject),
+                        fresh.role,
+                        self.project().named(fresh.surface.id())
+                    );
+                    return Task::batch(["model-explorer", "model-browser", "inspector"].map(
+                        |id| {
+                            iced::widget::operation::snap_to(
+                                id,
+                                iced::widget::scrollable::RelativeOffset::START,
+                            )
+                        },
+                    ));
+                }
+            }
+            Event::Open(_) | Event::Close(_) => unreachable!(),
+        }
+        Task::none()
+    }
+
+    pub(super) fn reveal_diagram_usage(&mut self, usage: &Usage) -> bool {
+        if !self.usage_navigation_available() {
+            return false;
+        }
+        let previous_layer = self.layer;
+        let p = self.document.project();
+        let (selected, placement) = match &usage.target {
+            Target::Whole => (usage.surface.id(), None),
+            Target::Placement(id) => {
+                let Some(node) = p
+                    .diagrams
+                    .get(&usage.surface.id())
+                    .and_then(|d| d.nodes.get(id))
+                else {
+                    return false;
+                };
+                (node.element, Some(*id))
+            }
+            Target::Port { port, placement } => (*port, Some(*placement)),
+            Target::StateRow {
+                placement,
+                relation,
+            } => (*relation, Some(*placement)),
+            Target::Edge(id)
+            | Target::ProcessLink(id)
+            | Target::ScenarioObject(id)
+            | Target::AllocationGrouping { relation: id, .. }
+            | Target::ProcessPreviewLink { relation: id, .. } => (*id, None),
+            Target::ProcessOccurrence(endpoint) => (
+                endpoint
+                    .references
+                    .first()
+                    .copied()
+                    .unwrap_or(endpoint.occurrence),
+                None,
+            ),
+        };
+        match usage.surface {
+            Surface::Saved(id) => {
+                let Some(diagram) = p.diagrams.get(&id) else {
+                    return false;
+                };
+                self.layer = diagram.layer;
+                self.active_diagram = Some(id);
+                if let Some(machine) = diagram.projection.state_machine() {
+                    let viewport = self.behavior.diagram.viewport.unwrap_or(iced::Size::new(
+                        (self.window_size.width - 610.).max(280.),
+                        (self.window_size.height - 320.).max(240.),
+                    ));
+                    let (zoom, pan) = usage::camera_for(&usage.target, usage.bounds, viewport);
+                    self.behavior.diagram = behavior::state_view::State {
+                        diagram: Some(id),
+                        placement,
+                        viewport: Some(viewport),
+                        zoom,
+                        pan,
+                        fit: false,
+                        ..Default::default()
+                    };
+                    self.behavior.active_owner = Some(machine);
+                    self.page = Page::Behavior;
+                } else {
+                    let viewport = self.canvas_size.unwrap_or(iced::Size::new(
+                        (self.window_size.width - 550.).max(280.),
+                        (self.window_size.height - 284.).max(240.),
+                    ));
+                    (self.zoom, self.pan) =
+                        usage::camera_for(&usage.target, usage.bounds, viewport);
+                    self.fit_to_view = false;
+                    self.page = Page::Diagram;
+                }
+            }
+            Surface::Process(owner) => {
+                if !self.behavior.topology.reveal_usage(
+                    p,
+                    self.canvas_document,
+                    owner,
+                    &usage.target,
+                ) {
+                    return false;
+                }
+                self.layer = p.elements[&owner].layer();
+                self.behavior.active_owner = Some(owner);
+                self.page = Page::Behavior;
+            }
+            Surface::Scenario(owner) => {
+                if !self.behavior.scenario.reveal_usage(
+                    p,
+                    self.canvas_document,
+                    owner,
+                    &usage.target,
+                ) {
+                    return false;
+                }
+                self.layer = p.elements[&owner].layer();
+                self.behavior.active_owner = Some(owner);
+                self.page = Page::Behavior;
+            }
+        }
+        self.selected = selected;
+        self.selected_node = placement;
+        self.model_menu = None;
+        self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+        self.selected_bend = None;
+        self.connection = None;
+        self.last_workspace_page = self.page;
+        if previous_layer != self.layer {
+            self.data_state = Default::default();
+            self.explorer_index = crate::explorer::Index::new(self.project(), self.layer);
+            self.explorer_focus = None;
+            self.explorer_group = None;
+            self.explorer_page = 0;
+        }
+        self.normalize_creation();
+        self.reveal_explorer_selection();
+        self.refresh_draft();
+        self.diagram_navigation_focus = Some(usage::Focus {
+            context: Context {
+                document: self.canvas_document,
+                revision: self.document.revision(),
+                subject: usage.subject,
+            },
+            usage: usage.clone(),
+            selected,
+        });
+        self.pending_diagram_reveal = Some((
+            Context {
+                document: self.canvas_document,
+                revision: self.document.revision(),
+                subject: usage.subject,
+            },
+            usage.clone(),
+            self.canvas_epoch,
+        ));
+        true
+    }
+
+    /// Validated presentation identity. Edit selection and Delete capture remain
+    /// semantic; a port owner or allocation work box is only a visual marker.
+    pub(crate) fn diagram_focus(&self, surface: Surface) -> Option<&Usage> {
+        let focus = self.diagram_navigation_focus.as_ref()?;
+        let current_surface = match surface {
+            Surface::Saved(id) => {
+                self.active_diagram == Some(id)
+                    && matches!(self.page, Page::Diagram | Page::Behavior)
+            }
+            Surface::Process(owner) | Surface::Scenario(owner) => {
+                self.page == Page::Behavior && self.behavior.active_owner == Some(owner)
+            }
+        };
+        (current_surface
+            && focus.usage.surface == surface
+            && focus.context.document == self.canvas_document
+            && focus.context.revision == self.document.revision()
+            && focus.selected == self.selected)
+            .then_some(&focus.usage)
+    }
+}

crates/oa-desktop/src/app/hosted.rs

@@ -213,6 +213,14 @@ impl App {
             self.pending = None;
             return Task::none();
         }
+        if self.path.is_some()
+            || self.hosted.session.as_ref().is_none_or(|session| {
+                session.resource_id != remote.resource_id
+                    || session.connection.base() != request.connection.base()
+            })
+        {
+            self.source_workspace.reset_navigation_session();
+        }
         self.hosted.session = Some(Session {
             connection: request.connection.clone(),
             resource_id: remote.resource_id,
@@ -345,6 +353,14 @@ impl App {
                         match self.document.apply_compiled((*remote.compiled).clone()) {
                             Ok(_) => {
                                 self.document.mark_saved(remote.compiled.clone());
+                                if self.path.is_some()
+                                    || self.hosted.session.as_ref().is_none_or(|session| {
+                                        session.resource_id != remote.resource_id
+                                            || session.connection.base() != connection.base()
+                                    })
+                                {
+                                    self.source_workspace.reset_navigation_session();
+                                }
                                 self.hosted.session = Some(Session {
                                     connection,
                                     resource_id: remote.resource_id,

crates/oa-desktop/src/app/process_canvas.rs

@@ -15,18 +15,15 @@ impl App {
             epoch: self.canvas_epoch,
         })
     }
-    pub(super) fn reveal_process_selection(&self) -> Task<Message> {
-        let Some(context) = self.topology_context() else {
-            return Task::none();
-        };
-        let Some(offset) =
-            self.behavior
-                .topology
-                .selection_offset(self.project(), context.owner, self.selected)
-        else {
-            return Task::none();
-        };
-        iced::widget::operation::scroll_to("process-canvas", offset)
+    pub(super) fn reveal_process_selection(&mut self) -> Task<Message> {
+        if let Some(context) = self.topology_context() {
+            let mut state = std::mem::take(&mut self.behavior.topology);
+            if state.reveal_selection(self.project(), context.owner, self.selected) {
+                self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+            }
+            self.behavior.topology = state;
+        }
+        Task::none()
     }
     pub(super) fn edit_process_canvas(&mut self, event: CanvasEvent) -> Task<Message> {
         let context = event.context();
@@ -52,6 +49,47 @@ impl App {
             }
             return Task::none();
         }
+        if let CanvasEvent::Camera(_, lifetime, input) = event {
+            use crate::behavior::canvas_workspace::{self, Event};
+            if lifetime != self.camera_epoch
+                || !self.topology_context().is_some_and(|c| {
+                    c.document == context.document
+                        && c.owner == context.owner
+                        && c.revision == context.revision
+                })
+            {
+                return Task::none();
+            }
+            let scope = canvas_workspace::Scope {
+                document: context.document,
+                owner: context.owner,
+                revision: context.revision,
+                epoch: lifetime,
+            };
+            if self.behavior.has_pending()
+                || self.draft_dirty()
+                || self.source_dirty()
+                || !canvas_workspace::keyboard_enabled(self)
+            {
+                return Task::none();
+            }
+            match input {
+                Event::Focus
+                | Event::Traverse(_)
+                | Event::ControlFocus(_)
+                | Event::ToggleFocus
+                | Event::Leave => {
+                    return canvas_workspace::focus_task(scope, input);
+                }
+                Event::CancelGesture => self.canvas_epoch = self.canvas_epoch.wrapping_add(1),
+                input => {
+                    if self.behavior.topology.camera(input) {
+                        self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+                    }
+                }
+            }
+            return Task::none();
+        }
         if self.topology_context() != Some(context) {
             return Task::none();
         }
@@ -81,6 +119,7 @@ impl App {
                             .first()
                             .copied()
                             .unwrap_or(endpoint.occurrence),
+                        resolved.defining_sequence,
                     );
                     self.behavior.active_owner = Some(resolved.defining_sequence);
                     self.select(endpoint.occurrence);
@@ -118,14 +157,18 @@ impl App {
                 }
             }
             CanvasEvent::Choose(_, tool) => {
-                if self.behavior.has_pending() || !self.apply() {
+                if self.behavior.has_pending() || self.draft_dirty() || self.source_dirty() {
+                    self.status =
+                        "Apply or cancel pending edits before choosing a process tool.".into();
                     return Task::none();
                 }
                 self.behavior.topology.choose(tool);
                 self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
             }
             CanvasEvent::Zoom(_, zoom) => {
-                self.behavior.topology.zoom(zoom);
+                let mut state = std::mem::take(&mut self.behavior.topology);
+                state.camera_zoom(self.project(), context.owner, zoom);
+                self.behavior.topology = state;
                 self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
             }
             CanvasEvent::Expand(_, id) => {
@@ -149,7 +192,9 @@ impl App {
                         .get(&target)
                         .is_some_and(|e| matches!(e.kind(), Kind::Process | Kind::FunctionalChain))
                     {
-                        self.behavior.topology.remember(context.owner, occurrence);
+                        self.behavior
+                            .topology
+                            .remember(context.owner, occurrence, target);
                         self.behavior.active_owner = Some(target);
                     }
                     self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
@@ -524,32 +569,30 @@ mod tests {
         assert!(!app.behavior.has_pending());
     }
     #[test]
-    fn direct_process_app_save_scroll_resize_and_passive_geometry_keep_drafts_and_current_origin() {
+    fn direct_process_app_save_details_resize_and_passive_geometry_keep_drafts_and_camera() {
         let (mut app, f) = setup();
         let context = app.topology_context().unwrap();
+        let _ = app.update(Message::TopologyCanvas(CanvasEvent::Camera(
+            context,
+            app.camera_epoch,
+            behavior::canvas_workspace::Event::Pan(iced::Vector::new(25., 100.)),
+        )));
+        let context = app.topology_context().unwrap();
         let original = app.document.snapshot();
         app.busy = true;
-        for (area, offset) in [
-            (
-                behavior::scenario::ScrollArea::Canvas,
-                iced::Vector::new(25., 100.),
-            ),
-            (
-                behavior::scenario::ScrollArea::Page,
-                iced::Vector::new(0., 40.),
-            ),
-        ] {
-            let _ = app.update(Message::TopologyCanvas(CanvasEvent::Scrolled(
-                context, area, offset,
-            )));
-        }
+        let _ = app.update(Message::TopologyCanvas(CanvasEvent::Scrolled(
+            context,
+            behavior::scenario::ScrollArea::Page,
+            iced::Vector::new(0., 40.),
+        )));
         let _ = app.update(Message::TopologyCanvas(CanvasEvent::Viewport(
             context,
             iced::Size::new(500., 300.),
         )));
+        let camera = app.behavior.topology.camera_boundary();
         assert_eq!(
-            app.behavior.topology.scroll_offset(),
-            iced::Vector::new(25., 140.)
+            app.behavior.topology.details_offset(),
+            iced::Vector::new(0., 40.)
         );
         assert_ne!(app.topology_context(), Some(context));
         assert!(app.busy);
@@ -557,12 +600,12 @@ mod tests {
         stale.document = Id::new_v4();
         let _ = app.update(Message::TopologyCanvas(CanvasEvent::Scrolled(
             stale,
-            behavior::scenario::ScrollArea::Canvas,
+            behavior::scenario::ScrollArea::Page,
             iced::Vector::new(0., 900.),
         )));
         assert_eq!(
-            app.behavior.topology.scroll_offset(),
-            iced::Vector::new(25., 140.)
+            app.behavior.topology.details_offset(),
+            iced::Vector::new(0., 40.)
         );
         let root = PathBuf::from("process-scroll-save-fixture");
         let receipt = FileSnapshot {
@@ -582,6 +625,7 @@ mod tests {
         assert!(!app.busy);
         assert!(!app.document.can_undo());
         assert_eq!(app.project(), &f.p);
+        assert!(app.behavior.topology.camera_boundary() == camera);
         let context = app.topology_context().unwrap();
         let size = app.window_size;
         let _ = app.update(Message::WindowResized(size));

crates/oa-desktop/src/app/reference_authoring.rs

@@ -0,0 +1,304 @@
+//! One transient chooser for the currently mounted Inspector or review field.
+//! Browsing never calls a draft setter or semantic planner.
+use super::{App, Message, Page, Pending};
+use crate::{
+    forms::{
+        Draft,
+        reference_chooser::{self as chooser, Action, Close, Outcome, adapter, trigger},
+    },
+    navigation::InspectorTab,
+    semantic_review::{self, RowAddress, RowEvent},
+    workflow,
+};
+use iced::{Element, Rectangle, Task};
+use oa_core::{FacetSelector, Id, Layer};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Host {
+    Inspector,
+    Review {
+        address: Option<RowAddress>,
+        facet: FacetSelector,
+    },
+}
+impl Host {
+    fn message(&self, event: chooser::Event) -> Message {
+        match self {
+            Self::Inspector => Message::FieldReferenceEvent(event),
+            Self::Review { address, facet } => {
+                Message::Workflow(workflow::Event::semantic(semantic_review::Event::Row {
+                    address: *address,
+                    facet: Some(facet.clone()),
+                    event: RowEvent::ReferenceEvent(event),
+                }))
+            }
+        }
+    }
+}
+struct Opened {
+    host: Host,
+    request: adapter::Open,
+    document_session: Id,
+    page: Page,
+    layer: Layer,
+    chooser: chooser::State,
+}
+#[derive(Default)]
+pub(super) struct State {
+    opened: Option<Opened>,
+}
+
+impl App {
+    pub(crate) fn reference_input_active(&self) -> bool {
+        self.reference_authoring.opened.is_some()
+    }
+
+    fn reference_draft(&self, host: &Host, path: &str) -> Option<&Draft> {
+        match host {
+            Host::Inspector
+                if self.workflow.is_none() && self.inspector_tab == InspectorTab::Properties =>
+            {
+                self.draft.as_ref()
+            }
+            Host::Review { address, facet } => match self.workflow.as_ref()? {
+                workflow::Workflow::Semantic(state) => {
+                    state.reference_draft(self.project(), *address, facet, path)
+                }
+                _ => None,
+            },
+            _ => None,
+        }
+    }
+    fn reference_available(&self) -> bool {
+        !self.busy
+            && !self.hosted.visible
+            && self.architecture.is_none()
+            && self.model_menu.is_none()
+            && self.file_prompt.is_none()
+            && !self.delete_pending
+            && self.pending.is_none()
+            && !self.source_dirty()
+            && !self.behavior.has_pending()
+            && !matches!(self.page, Page::Home | Page::Guide | Page::Text)
+    }
+    fn reference_valid(&self, opened: &Opened) -> bool {
+        self.reference_available()
+            && self.canvas_document == opened.document_session
+            && self.page == opened.page
+            && self.layer == opened.layer
+            && self.document.revision() == opened.chooser.stamp().context.revision
+            && self.project().id == opened.request.document
+            && self
+                .reference_draft(&opened.host, &opened.request.path)
+                .is_some_and(|draft| draft.reference_matches(&opened.request))
+    }
+    pub(super) fn reconcile_reference_chooser(&mut self) {
+        if self
+            .reference_authoring
+            .opened
+            .as_ref()
+            .is_some_and(|opened| !self.reference_valid(opened))
+        {
+            self.reference_authoring
+                .opened
+                .as_mut()
+                .unwrap()
+                .chooser
+                .invalidate();
+            self.reference_authoring.opened = None;
+        }
+    }
+    fn open_reference(&mut self, host: Host, request: adapter::Open) -> Task<Message> {
+        if !self.reference_available() {
+            return Task::none();
+        }
+        let Some(draft) = self.reference_draft(&host, &request.path) else {
+            return Task::none();
+        };
+        let Ok(chooser) =
+            draft.reference_catalog(self.project(), &request, self.document.revision())
+        else {
+            return Task::none();
+        };
+        self.reference_authoring.opened = Some(Opened {
+            host,
+            request,
+            document_session: self.canvas_document,
+            page: self.page,
+            layer: self.layer,
+            chooser,
+        });
+        Task::none()
+    }
+    fn reference_event(&mut self, host: Host, event: chooser::Event) -> Task<Message> {
+        let Some(mut opened) = self.reference_authoring.opened.take() else {
+            return Task::none();
+        };
+        if !self.reference_valid(&opened) {
+            return Task::none();
+        }
+        if opened.host != host {
+            self.reference_authoring.opened = Some(opened);
+            return Task::none();
+        }
+        match opened.chooser.update(event) {
+            Outcome::Ignored | Outcome::Browsed => {
+                self.reference_authoring.opened = Some(opened);
+                Task::none()
+            }
+            Outcome::Closed(reason) => self.reference_focus(
+                &opened,
+                match reason {
+                    Close::Escape => Some(0),
+                    Close::Tab { backwards } => Some(if backwards { -1 } else { 1 }),
+                    Close::Outside | Close::WindowChanged => None,
+                },
+            ),
+            Outcome::Write { context, value } => {
+                let intent = adapter::Set {
+                    context,
+                    generation: opened.request.generation,
+                    value,
+                };
+                let result = match &opened.host {
+                    Host::Inspector => self
+                        .draft
+                        .as_mut()
+                        .ok_or_else(|| "The property editor closed.".to_owned())
+                        .and_then(|draft| draft.reference_set(self.document.project(), &intent)),
+                    Host::Review { address, facet } => match self.workflow.as_mut() {
+                        Some(workflow::Workflow::Semantic(state)) => {
+                            state.set_reference(self.document.project(), *address, facet, intent)
+                        }
+                        _ => Err("The review editor closed.".into()),
+                    },
+                };
+                if let Err(error) = result {
+                    self.status = error;
+                }
+                // A scoped write rotates field generation. The task targets the
+                // newly rendered field, while a later structural edit makes it inert.
+                self.reference_focus(&opened, Some(0))
+            }
+        }
+    }
+    fn reference_focus(&self, opened: &Opened, step: Option<i32>) -> Task<Message> {
+        let Some(step) = step else {
+            return Task::none();
+        };
+        let Some(draft) = self.reference_draft(&opened.host, &opened.request.path) else {
+            return Task::none();
+        };
+        if draft.reference_session() != opened.request.session {
+            return Task::none();
+        }
+        trigger::focus(
+            draft.reference_session(),
+            draft.reference_generation(),
+            &opened.request.path,
+            step,
+        )
+    }
+    /// Called before generic modal dispatch: the review owns a modal, and this
+    /// chooser owns only its active field. All browser events stop here.
+    pub(super) fn reference_message(&mut self, message: &Message) -> Option<Task<Message>> {
+        self.reconcile_reference_chooser();
+        match message {
+            Message::FieldReferenceOpen(request) => {
+                Some(self.open_reference(Host::Inspector, request.clone()))
+            }
+            Message::FieldReferenceEvent(event) => {
+                Some(self.reference_event(Host::Inspector, event.clone()))
+            }
+            Message::Workflow(workflow::Event::Semantic(review_event)) => {
+                let semantic_review::Event::Row {
+                    address,
+                    facet: Some(facet),
+                    event,
+                } = review_event.as_ref()
+                else {
+                    return None;
+                };
+                let host = Host::Review {
+                    address: *address,
+                    facet: facet.clone(),
+                };
+                match event {
+                    RowEvent::ReferenceOpen(request) => {
+                        Some(self.open_reference(host, request.clone()))
+                    }
+                    RowEvent::ReferenceEvent(event) => {
+                        Some(self.reference_event(host, event.clone()))
+                    }
+                    _ => None,
+                }
+            }
+            Message::Escape | Message::Request(Pending::Close(_))
+                if self.reference_authoring.opened.is_some() =>
+            {
+                let opened = self.reference_authoring.opened.as_ref().unwrap();
+                let host = opened.host.clone();
+                let event = opened.chooser.event(Action::Close(Close::Escape));
+                Some(self.reference_event(host, event))
+            }
+            // Global shortcuts are also emitted for keys captured by the search
+            // input. They must not apply drafts, navigate, or undo the model.
+            Message::Save(_)
+            | Message::ShortcutUndo(_)
+            | Message::Request(Pending::Open | Pending::New)
+            | Message::SourceNavigation(_)
+            | Message::Page(Page::Guide)
+                if self.reference_authoring.opened.is_some() =>
+            {
+                Some(Task::none())
+            }
+            _ => None,
+        }
+    }
+    pub(super) fn reference_overlay<
+        'a,
+        R: iced::advanced::text::Renderer<Font = iced::Font> + 'a,
+    >(
+        &'a self,
+        content: Element<'a, Message, iced::Theme, R>,
+    ) -> Element<'a, Message, iced::Theme, R> {
+        let opened = self
+            .reference_authoring
+            .opened
+            .as_ref()
+            .filter(|opened| self.reference_valid(opened));
+        let host = opened
+            .map(|opened| opened.host.clone())
+            .unwrap_or(Host::Inspector);
+        let focus_scope = if self.reference_available() {
+            match self.workflow.as_ref() {
+                None if self.inspector_tab == InspectorTab::Properties => {
+                    self.draft.as_ref().map(|draft| trigger::FormScope {
+                        session: draft.reference_session(),
+                        modal: false,
+                    })
+                }
+                Some(workflow::Workflow::Semantic(state)) => state
+                    .reference_form(self.project())
+                    .map(|draft| trigger::FormScope {
+                        session: draft.reference_session(),
+                        modal: true,
+                    }),
+                _ => None,
+            }
+        } else {
+            None
+        };
+        chooser::widget::Popup::new(
+            content,
+            opened.map(|opened| &opened.chooser),
+            opened.map_or(Rectangle::default(), |opened| opened.request.anchor),
+            move |event| host.message(event),
+        )
+        .focus_scope(focus_scope)
+        .into()
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/app/reference_authoring/tests.rs

@@ -0,0 +1,586 @@
+use super::*;
+use crate::forms::Draft;
+use oa_core::*;
+use serde_json::{Value, json};
+
+const OWNER: Id = Id::from_u128(100);
+const BASE: u128 = 10_000;
+const PATH: &str = "/body/Oa/Shared/DataType/definition/Record/supertype";
+
+fn element(p: &mut Project, id: Id, kind: Kind, layer: Layer, name: &str, parent: Option<Id>) {
+    let generated = p.add_element(kind, layer, name, parent).unwrap();
+    let mut element = p.elements.remove(&generated).unwrap();
+    element.id = id;
+    element.alias = format!("object_{}", id.as_u128());
+    if let Some(SharedBody::DataType { definition, .. }) = element.shared_mut() {
+        *definition = DataTypeDefinition::Record { supertype: None };
+    }
+    p.elements.insert(id, element);
+}
+fn catalog() -> Project {
+    let mut p = Project::empty();
+    p.id = Id::from_u128(1);
+    p.name = "Reference catalog".into();
+    element(
+        &mut p,
+        OWNER,
+        Kind::DataType,
+        Layer::Oa,
+        "Edited record",
+        None,
+    );
+    for n in (0..1_000).rev() {
+        let id = Id::from_u128(BASE + n);
+        element(&mut p, id, Kind::DataType, Layer::Oa, "Controller", None);
+        p.elements.get_mut(&id).unwrap().alias = format!("controller_{n:04}");
+    }
+    element(
+        &mut p,
+        Id::from_u128(200),
+        Kind::DataType,
+        Layer::Sa,
+        "Controller",
+        None,
+    );
+    element(
+        &mut p,
+        Id::from_u128(201),
+        Kind::Activity,
+        Layer::Oa,
+        "Controller",
+        None,
+    );
+    p
+}
+fn inspector(p: Project, selected: Id) -> App {
+    let mut app = App::with_project(p);
+    let _ = app.update(Message::Select(selected));
+    app
+}
+fn request(app: &App, host: &Host, path: &str) -> adapter::Open {
+    app.reference_draft(host, path).unwrap().reference_open(
+        app.project(),
+        path,
+        Rectangle {
+            x: 790.,
+            y: 640.,
+            width: 278.,
+            height: 32.,
+        },
+    )
+}
+fn open(app: &mut App, host: &Host, path: &str) {
+    let request = request(app, host, path);
+    let message = match host {
+        Host::Inspector => Message::FieldReferenceOpen(request),
+        Host::Review { address, facet } => {
+            Message::Workflow(workflow::Event::semantic(semantic_review::Event::Row {
+                address: *address,
+                facet: Some(facet.clone()),
+                event: RowEvent::ReferenceOpen(request),
+            }))
+        }
+    };
+    let _ = app.update(message);
+    assert!(
+        app.reference_authoring.opened.is_some(),
+        "field must open: {}",
+        app.status
+    );
+}
+fn event(app: &App, action: Action) -> Message {
+    let opened = app.reference_authoring.opened.as_ref().unwrap();
+    opened.host.message(opened.chooser.event(action))
+}
+fn search(app: &mut App, query: &str) {
+    let serial = app
+        .reference_authoring
+        .opened
+        .as_ref()
+        .unwrap()
+        .chooser
+        .query_serial()
+        + 1;
+    let event = event(
+        app,
+        Action::Query {
+            text: query.into(),
+            serial,
+        },
+    );
+    let _ = app.update(event);
+}
+fn choose(app: &mut App, id: Id) {
+    let event = event(app, Action::Choose(id));
+    let _ = app.update(event);
+}
+fn raw(app: &App) -> Value {
+    serde_json::to_value(app.draft.as_ref().unwrap().recovery_snapshot()).unwrap()
+}
+fn review(app: &App) -> &semantic_review::State {
+    let Some(workflow::Workflow::Semantic(state)) = app.workflow.as_ref() else {
+        panic!("Review is open")
+    };
+    state
+}
+fn send_review(app: &mut App, event: RowEvent) {
+    let addressed = review(app).address_event(event);
+    let _ = app.update(Message::Workflow(workflow::Event::semantic(addressed)));
+}
+fn review_host(app: &App) -> Host {
+    let semantic_review::Event::Row {
+        address,
+        facet: Some(facet),
+        ..
+    } = review(app).address_event(RowEvent::Preview)
+    else {
+        panic!("Active facet")
+    };
+    Host::Review { address, facet }
+}
+fn trace(p: &mut Project, id: Id, oa: Id, sa: Id) {
+    p.traces.insert(
+        id,
+        Trace {
+            id,
+            alias: format!("trace_{}", id.as_u128()),
+            name: "Rationale".into(),
+            description: String::new(),
+            oa,
+            sa,
+            kind: TraceKind::Manual,
+            baseline: None,
+        },
+    );
+}
+
+#[test]
+fn inspector_reference_browse_is_read_only_then_one_scoped_value_applies_with_exact_undo_redo() {
+    let p = catalog();
+    let mut app = inspector(p.clone(), OWNER);
+    let before = app.document.bundle().clone();
+    let revision = app.document.revision();
+    // Malformed escaped text is unrelated to the selected reference. Browsing
+    // and the scoped write must keep its exact spelling and inactive payload.
+    app.draft.as_mut().unwrap().set_exact(true).unwrap();
+    let _ = app.update(Message::Field("/name".into(), "\"unfinished".into()));
+    let raw_before = raw(&app);
+    open(&mut app, &Host::Inspector, PATH);
+    assert_eq!(
+        app.reference_authoring
+            .opened
+            .as_ref()
+            .unwrap()
+            .chooser
+            .count(),
+        1_000
+    );
+    search(&mut app, "controller @controller_0720 OA");
+    let picker = &app.reference_authoring.opened.as_ref().unwrap().chooser;
+    assert_eq!(picker.count(), 1);
+    assert_eq!(picker.highlighted().unwrap().id, Id::from_u128(BASE + 720));
+    assert_eq!(raw(&app), raw_before);
+    assert_eq!(app.document.bundle(), &before);
+    assert_eq!(app.document.revision(), revision);
+    assert!(!app.document.can_undo());
+    // Captured search shortcuts cannot accidentally save/apply or undo a model.
+    let _ = app.update(Message::Save(false));
+    let _ = app.update(Message::ShortcutUndo(false));
+    assert_eq!(raw(&app), raw_before);
+    assert_eq!(app.document.bundle(), &before);
+    choose(&mut app, Id::from_u128(BASE + 720));
+    let mut expected_raw = raw_before;
+    *expected_raw["value"].pointer_mut(PATH).unwrap() = json!(Id::from_u128(BASE + 720));
+    expected_raw["inputs"][PATH] = json!(Id::from_u128(BASE + 720).to_string());
+    assert_eq!(raw(&app), expected_raw);
+    assert_eq!(app.document.bundle(), &before);
+    assert!(!app.document.can_undo());
+    let _ = app.update(Message::Apply);
+    assert_eq!(
+        app.document.bundle(),
+        &before,
+        "Unrelated invalid text remains an Apply error"
+    );
+    let _ = app.update(Message::Field("/name".into(), "\"Edited record\"".into()));
+    let _ = app.update(Message::Apply);
+    let mut expected = p;
+    if let Some(SharedBody::DataType { definition, .. }) =
+        expected.elements.get_mut(&OWNER).unwrap().shared_mut()
+    {
+        *definition = DataTypeDefinition::Record {
+            supertype: Some(Id::from_u128(BASE + 720)),
+        };
+    }
+    assert_eq!(app.project(), &expected);
+    let accepted = app.document.bundle().clone();
+    assert_ne!(accepted, before);
+    let _ = app.update(Message::Undo);
+    assert_eq!(app.document.bundle(), &before);
+    let _ = app.update(Message::Redo);
+    assert_eq!(app.document.bundle(), &accepted);
+    assert_eq!(app.project(), &expected);
+}
+
+#[test]
+fn inspector_reference_retains_invalid_missing_and_incompatible_current_until_explicit_clear() {
+    for (raw_id, expected) in [
+        ("-".into(), "invalid"),
+        (Id::from_u128(999).to_string(), "missing"),
+        (Id::from_u128(200).to_string(), "incompatible"),
+    ] {
+        let mut app = inspector(catalog(), OWNER);
+        app.draft
+            .as_mut()
+            .unwrap()
+            .shape_scoped(PATH, json!(raw_id))
+            .unwrap();
+        let original = raw(&app);
+        let accepted = app.document.bundle().clone();
+        open(&mut app, &Host::Inspector, PATH);
+        let current = &app
+            .reference_authoring
+            .opened
+            .as_ref()
+            .unwrap()
+            .chooser
+            .current;
+        assert!(matches!(
+            (expected, current),
+            ("invalid", chooser::Current::InvalidRaw(_))
+                | ("missing", chooser::Current::Missing(_))
+                | ("incompatible", chooser::Current::Incompatible(_))
+        ));
+        let _ = app.update(Message::Escape);
+        assert_eq!(raw(&app), original);
+        open(&mut app, &Host::Inspector, PATH);
+        let clear = event(&app, Action::Clear);
+        let _ = app.update(clear);
+        assert!(
+            app.draft
+                .as_ref()
+                .unwrap()
+                .value
+                .pointer(PATH)
+                .unwrap()
+                .is_null()
+        );
+        assert_eq!(app.document.bundle(), &accepted);
+        assert!(!app.document.can_undo());
+    }
+}
+
+#[test]
+fn chooser_rejects_old_results_after_context_recovery_reload_or_modal_and_keeps_history_text_out() {
+    for change in 0..7 {
+        let mut app = inspector(catalog(), OWNER);
+        open(&mut app, &Host::Inspector, PATH);
+        let delayed = event(&app, Action::Choose(Id::from_u128(BASE + 1)));
+        match change {
+            0 => {
+                app.draft
+                    .as_mut()
+                    .unwrap()
+                    .shape_scoped(PATH, json!(Id::from_u128(BASE + 2)))
+                    .unwrap();
+            }
+            1 => {
+                let saved = app.draft.as_ref().unwrap().recovery_snapshot();
+                app.draft = Some(Draft::from_recovery(app.project(), saved).unwrap());
+            }
+            2 => {
+                app.canvas_document = Id::new_v4();
+            }
+            3 => {
+                app.hosted.visible = true;
+            }
+            4 => {
+                app.draft
+                    .as_mut()
+                    .unwrap()
+                    .set_context(Some(json!({"different":"scope"})));
+            }
+            5 => {
+                let _ = app.update(Message::Command(Command::Rename(
+                    Id::from_u128(BASE + 3),
+                    "Changed model".into(),
+                )));
+            }
+            _ => {
+                app.source_workspace.edit(
+                    "unfinished source".into(),
+                    iced::widget::text_editor::Cursor {
+                        position: iced::widget::text_editor::Position { line: 0, column: 0 },
+                        selection: None,
+                    },
+                );
+            }
+        }
+        let expected = raw(&app);
+        let source = app.document.bundle().clone();
+        let _ = app.update(delayed);
+        assert!(app.reference_authoring.opened.is_none());
+        assert_eq!(raw(&app), expected);
+        assert_eq!(app.document.bundle(), &source);
+    }
+    let mut p = catalog();
+    trace(&mut p, Id::from_u128(300), OWNER, Id::from_u128(200));
+    let app = inspector(p, Id::from_u128(300));
+    let draft = app.draft.as_ref().unwrap();
+    let request = draft.reference_open(
+        app.project(),
+        "/baseline/semantic/facets/0/references/0/target",
+        Rectangle::default(),
+    );
+    assert!(draft.reference_catalog(app.project(), &request, 0).is_err());
+}
+
+#[test]
+fn reference_array_row_reorder_and_constructor_switch_invalidate_exact_old_field() {
+    let mut p = Project::empty();
+    for n in 0..3 {
+        element(
+            &mut p,
+            Id::from_u128(BASE + n),
+            Kind::ExchangeItem,
+            Layer::Oa,
+            "Signal item",
+            None,
+        );
+    }
+    element(&mut p, OWNER, Kind::Event, Layer::Oa, "Signal", None);
+    *p.elements.get_mut(&OWNER).unwrap().shared_mut().unwrap() = SharedBody::Event {
+        body: EventBody::Signal {
+            items: vec![Id::from_u128(BASE), Id::from_u128(BASE + 1)],
+        },
+    };
+    let mut app = inspector(p, OWNER);
+    let list = "/body/Oa/Shared/Event/body/Signal/items";
+    let path = format!("{list}/0");
+    open(&mut app, &Host::Inspector, &path);
+    let delayed = event(&app, Action::Choose(Id::from_u128(BASE + 2)));
+    let _ = app.update(Message::FieldArray(list.into(), Some(0), 1));
+    let expected = raw(&app);
+    assert_eq!(
+        app.draft.as_ref().unwrap().value.pointer(list),
+        Some(&json!([Id::from_u128(BASE + 1), Id::from_u128(BASE)]))
+    );
+    let _ = app.update(delayed);
+    assert_eq!(raw(&app), expected);
+    open(&mut app, &Host::Inspector, &path);
+    let delayed = event(&app, Action::Choose(Id::from_u128(BASE + 2)));
+    let _ = app.update(Message::FieldVariant(
+        "/body/Oa/Shared/Event/body".into(),
+        json!({"Change":{"expression":"unfinished"}}),
+    ));
+    let expected = raw(&app);
+    let _ = app.update(delayed);
+    assert_eq!(raw(&app), expected);
+    assert!(!app.document.can_undo());
+}
+
+#[test]
+fn review_reference_facets_groups_and_attachment_hosts_browse_without_replanning_and_reject_old_facet()
+ {
+    for mode in 0..3 {
+        let mut p = Project::empty();
+        p.id = Id::from_u128(1);
+        for (id, layer, parent) in [
+            (100, Layer::Oa, None),
+            (101, Layer::Sa, None),
+            (102, Layer::Sa, None),
+            (103, Layer::Oa, Some(Id::from_u128(100))),
+            (104, Layer::Sa, Some(Id::from_u128(101))),
+        ] {
+            element(
+                &mut p,
+                Id::from_u128(id),
+                if parent.is_some() {
+                    Kind::DataField
+                } else {
+                    Kind::DataType
+                },
+                layer,
+                "Record",
+                parent,
+            );
+        }
+        trace(
+            &mut p,
+            Id::from_u128(300),
+            Id::from_u128(100),
+            Id::from_u128(101),
+        );
+        let facet = match mode {
+            0 => FacetSelector::Data(DataFacet::RecordSupertype),
+            1 => FacetSelector::Data(DataFacet::Constructor),
+            _ => FacetSelector::Child(KeyPair {
+                oa: Some(Id::from_u128(103)),
+                sa: Some(Id::from_u128(104)),
+            }),
+        };
+        let path = if mode == 2 {
+            "/parent"
+        } else {
+            "/body/Sa/Shared/DataType/definition/Record/supertype"
+        };
+        let mut app = App::with_project(p.clone());
+        let _ = app.update(Message::StartSemanticReview(Id::from_u128(100)));
+        if mode == 2 {
+            // A paired attachment is a real catalog facet only after explicit
+            // correspondence; selecting an unstaged synthetic pair is rejected.
+            for (id, oa) in [(103, true), (104, false)] {
+                let choice = crate::app::Choice {
+                    id: Id::from_u128(id),
+                    label: format!("Record · @object_{id}"),
+                };
+                send_review(
+                    &mut app,
+                    if oa {
+                        RowEvent::ReferenceOa(choice)
+                    } else {
+                        RowEvent::ReferenceSa(choice)
+                    },
+                );
+            }
+            send_review(&mut app, RowEvent::AddReference);
+        }
+        send_review(&mut app, RowEvent::Select(facet.clone()));
+        send_review(
+            &mut app,
+            RowEvent::Decide(facet.clone(), Some(SemanticDecision::Candidate)),
+        );
+        let host = review_host(&app);
+        let record = if mode == 2 {
+            Id::from_u128(104)
+        } else {
+            Id::from_u128(101)
+        };
+        assert_eq!(
+            app.reference_draft(&host, path)
+                .unwrap_or_else(|| {
+                    panic!(
+                        "Reference fixture mode={mode}, facet={facet:?}, selected={:?}, decisions={:?}, error={:?}",
+                        review(&app).selected,
+                        review(&app).decisions,
+                        review(&app).error
+                    )
+                })
+                .original,
+            record
+        );
+        let before = review(&app).recovery_snapshot().unwrap();
+        let plan = serde_json::to_value(&review(&app).plan).unwrap();
+        let proposed = review(&app).proposed.clone();
+        let source = app.document.bundle().clone();
+        open(&mut app, &host, path);
+        search(&mut app, "@object_102 SA");
+        assert_eq!(
+            app.reference_authoring
+                .opened
+                .as_ref()
+                .unwrap()
+                .chooser
+                .count(),
+            1
+        );
+        assert_eq!(review(&app).recovery_snapshot().unwrap(), before);
+        assert_eq!(serde_json::to_value(&review(&app).plan).unwrap(), plan);
+        assert_eq!(review(&app).proposed, proposed);
+        assert_eq!(app.document.bundle(), &source);
+        let old = event(&app, Action::Choose(Id::from_u128(102)));
+        send_review(
+            &mut app,
+            RowEvent::Select(FacetSelector::Header(HeaderFacet::Name)),
+        );
+        let switched = review(&app).recovery_snapshot().unwrap();
+        let _ = app.update(old);
+        assert_eq!(review(&app).recovery_snapshot().unwrap(), switched);
+        send_review(&mut app, RowEvent::Select(facet));
+        open(&mut app, &host, path);
+        choose(&mut app, Id::from_u128(102));
+        let draft = app.reference_draft(&host, path).unwrap();
+        let mut expected_record = serde_json::to_value(&p.elements[&record]).unwrap();
+        *expected_record.pointer_mut(path).unwrap() = json!(Id::from_u128(102));
+        assert_eq!(draft.materialize().unwrap(), expected_record);
+        assert_eq!(app.document.bundle(), &source);
+        assert!(
+            !app.document.can_undo(),
+            "A choice only stages the active review candidate"
+        );
+    }
+}
+
+mod mounted;
+
+#[test]
+fn review_reference_cannot_reopen_or_write_a_banked_row_after_another_row_takes_focus() {
+    let mut p = Project::empty();
+    for (id, layer) in [
+        (100, Layer::Oa),
+        (101, Layer::Sa),
+        (102, Layer::Sa),
+        (110, Layer::Oa),
+        (111, Layer::Sa),
+    ] {
+        element(
+            &mut p,
+            Id::from_u128(id),
+            Kind::DataType,
+            layer,
+            "Record",
+            None,
+        );
+    }
+    trace(
+        &mut p,
+        Id::from_u128(300),
+        Id::from_u128(100),
+        Id::from_u128(101),
+    );
+    trace(
+        &mut p,
+        Id::from_u128(310),
+        Id::from_u128(110),
+        Id::from_u128(111),
+    );
+    let mut app = App::with_project(p);
+    let _ = app.update(Message::StartSemanticReview(Id::from_u128(300)));
+    let facet = FacetSelector::Data(DataFacet::RecordSupertype);
+    send_review(&mut app, RowEvent::Select(facet.clone()));
+    send_review(
+        &mut app,
+        RowEvent::Decide(facet, Some(SemanticDecision::Candidate)),
+    );
+    let host = review_host(&app);
+    let path = "/body/Sa/Shared/DataType/definition/Record/supertype";
+    let old_open = request(&app, &host, path);
+    open(&mut app, &host, path);
+    let old_choice = event(&app, Action::Choose(Id::from_u128(102)));
+    for event in [
+        semantic_review::Event::ChooseTrace(crate::app::Choice {
+            id: Id::from_u128(310),
+            label: "Second exact trace".into(),
+        }),
+        semantic_review::Event::OpenTrace,
+    ] {
+        let _ = app.update(Message::Workflow(workflow::Event::semantic(event)));
+    }
+    assert_eq!(review(&app).target(app.project()), Some(Id::from_u128(111)));
+    let expected = review(&app).recovery_snapshot().unwrap();
+    let source = app.document.bundle().clone();
+    let _ = app.update(old_choice);
+    let Host::Review { address, facet } = host else {
+        unreachable!()
+    };
+    let _ = app.update(Message::Workflow(workflow::Event::semantic(
+        semantic_review::Event::Row {
+            address,
+            facet: Some(facet),
+            event: RowEvent::ReferenceOpen(old_open),
+        },
+    )));
+    assert!(app.reference_authoring.opened.is_none());
+    assert_eq!(review(&app).recovery_snapshot().unwrap(), expected);
+    assert_eq!(app.document.bundle(), &source);
+    assert!(!app.document.can_undo());
+}

crates/oa-desktop/src/app/reference_authoring/tests/mounted.rs

@@ -0,0 +1,910 @@
+//! Real field + app-root overlay interaction. The null text renderer lets the
+//! same retained widget tree exercise focus and geometry without a GPU/window.
+use super::*;
+use iced::futures::StreamExt;
+use iced::{
+    Element, Event as Input, Point, Size, Theme, Vector,
+    advanced::{
+        Layout, Shell, layout,
+        widget::{Id as WidgetId, Operation, Tree, operation},
+    },
+    keyboard, mouse,
+    widget::{Space, column, container, opaque, scrollable, stack, text_input},
+};
+use oa_core::transitions::TransitionDirection;
+
+#[derive(Default)]
+struct Clipboard;
+impl iced::advanced::Clipboard for Clipboard {
+    fn read(&self, _: iced::advanced::clipboard::Kind) -> Option<String> {
+        None
+    }
+    fn write(&mut self, _: iced::advanced::clipboard::Kind, _: String) {}
+}
+#[derive(Default)]
+struct Fields {
+    values: Vec<(WidgetId, Rectangle, bool)>,
+    scrolls: Vec<(Rectangle, Vector)>,
+}
+impl Operation for Fields {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        visit(self);
+    }
+    fn focusable(
+        &mut self,
+        id: Option<&WidgetId>,
+        bounds: Rectangle,
+        state: &mut dyn operation::Focusable,
+    ) {
+        if let Some(id) = id {
+            self.values.push((id.clone(), bounds, state.is_focused()));
+        }
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&WidgetId>,
+        bounds: Rectangle,
+        _: Rectangle,
+        translation: Vector,
+        _: &mut dyn operation::Scrollable,
+    ) {
+        self.scrolls.push((bounds, translation));
+    }
+}
+impl Fields {
+    fn field(&self, id: &WidgetId) -> (Rectangle, bool) {
+        self.values
+            .iter()
+            .find(|(actual, _, _)| actual == id)
+            .map(|(_, bounds, focused)| (*bounds, *focused))
+            .expect("Mounted field identity")
+    }
+}
+fn view(
+    app: &App,
+    scrolled: bool,
+    nested: bool,
+    show_review: bool,
+) -> Element<'_, Message, Theme, ()> {
+    let draft = app.draft.as_ref().unwrap();
+    let form = column![
+        text_input("Name", &draft.inputs["/name"].raw)
+            .id("before-reference")
+            .on_input(|raw| Message::Field("/name".into(), raw)),
+        adapter::field(draft, app.project(), PATH),
+        text_input("Description", &draft.inputs["/description"].raw)
+            .id("after-reference")
+            .on_input(|raw| Message::Field("/description".into(), raw)),
+    ]
+    .spacing(9);
+    let form = trigger::scope(form, draft.reference_session());
+    let base: Element<'_, Message, Theme, ()> = if scrolled {
+        container(
+            scrollable(column![Space::new().height(500), form])
+                .id("reference-scroll")
+                .height(180),
+        )
+        .width(300)
+        .into()
+    } else {
+        container(form).width(300).height(iced::Fill).into()
+    };
+    let base: Element<'_, Message, Theme, ()> = if nested {
+        scrollable(column![Space::new().height(400), base])
+            .id("outer-reference-scroll")
+            .height(180)
+            .width(300)
+            .into()
+    } else {
+        base
+    };
+    let base = if show_review {
+        let review: Element<'_, Message, Theme, ()> = match app.workflow.as_ref() {
+            Some(workflow::Workflow::Semantic(state)) => {
+                match state.reference_form(app.project()) {
+                    Some(draft) => {
+                        let mut content = column![];
+                        if let Some(raw) = &state.operation_omission {
+                            content = content.push(
+                                text_input("Required engineering rationale", raw)
+                                    .id("review-rationale")
+                                    .on_input(|raw| {
+                                        Message::Workflow(workflow::Event::semantic(
+                                            state.address_event(RowEvent::OperationRationale(raw)),
+                                        ))
+                                    }),
+                            );
+                        }
+                        content = content.push(trigger::scope(
+                            adapter::field(draft, app.project(), "/parent").map(|message| {
+                                match message {
+                                    Message::FieldReferenceOpen(request) => {
+                                        Message::Workflow(workflow::Event::semantic(
+                                            state.address_event(RowEvent::ReferenceOpen(request)),
+                                        ))
+                                    }
+                                    other => other,
+                                }
+                            }),
+                            draft.reference_session(),
+                        ));
+                        opaque(container(trigger::modal(content)).width(300).height(180))
+                    }
+                    None => Space::new().into(),
+                }
+            }
+            _ => Space::new().into(),
+        };
+        stack![base, review].into()
+    } else {
+        base
+    };
+    app.reference_overlay(base)
+}
+struct Mount {
+    tree: Option<Tree>,
+    size: Size,
+    scrolled: bool,
+    nested: bool,
+    show_review: bool,
+}
+impl Default for Mount {
+    fn default() -> Self {
+        Self {
+            tree: None,
+            size: Size::new(360., 320.),
+            scrolled: false,
+            nested: false,
+            show_review: false,
+        }
+    }
+}
+impl Mount {
+    fn frame(
+        &mut self,
+        app: &App,
+        events: &[(Input, Option<Point>)],
+    ) -> (Vec<Message>, Fields, Option<Rectangle>) {
+        let mut view = view(app, self.scrolled, self.nested, self.show_review);
+        let tree = self.tree.get_or_insert_with(|| Tree::new(view.as_widget()));
+        view.as_widget().diff(tree);
+        let node =
+            view.as_widget_mut()
+                .layout(tree, &(), &layout::Limits::new(Size::ZERO, self.size));
+        let viewport = Rectangle::with_size(self.size);
+        let overlay_node = view
+            .as_widget_mut()
+            .overlay(tree, Layout::new(&node), &(), &viewport, Vector::ZERO)
+            .map(|mut overlay| overlay.as_overlay_mut().layout(&(), self.size));
+        let mut messages = Vec::new();
+        for (input, point) in events {
+            let mut shell = Shell::new(&mut messages);
+            let cursor = point.map_or(mouse::Cursor::Unavailable, mouse::Cursor::Available);
+            if let Some(overlay_node) = &overlay_node {
+                let mut overlay = view
+                    .as_widget_mut()
+                    .overlay(tree, Layout::new(&node), &(), &viewport, Vector::ZERO)
+                    .unwrap();
+                overlay.as_overlay_mut().update(
+                    input,
+                    Layout::new(overlay_node),
+                    cursor,
+                    &(),
+                    &mut Clipboard,
+                    &mut shell,
+                );
+                assert!(shell.is_event_captured());
+            } else {
+                view.as_widget_mut().update(
+                    tree,
+                    input,
+                    Layout::new(&node),
+                    cursor,
+                    &(),
+                    &mut Clipboard,
+                    &mut shell,
+                    &viewport,
+                );
+            }
+        }
+        let mut fields = Fields::default();
+        view.as_widget_mut()
+            .operate(tree, Layout::new(&node), &(), &mut fields);
+        (
+            messages,
+            fields,
+            overlay_node.map(|node| node.children()[0].bounds()),
+        )
+    }
+    fn click(&mut self, app: &App, point: Point) -> Vec<Message> {
+        self.frame(
+            app,
+            &[
+                (
+                    Input::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                    Some(point),
+                ),
+                (
+                    Input::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)),
+                    Some(point),
+                ),
+            ],
+        )
+        .0
+    }
+    async fn perform(&mut self, app: &App, task: Task<Message>) {
+        let Some(mut stream) = iced_runtime::task::into_stream(task) else {
+            return;
+        };
+        while let Some(action) = stream.next().await {
+            let iced_runtime::Action::Widget(mut operation) = action else {
+                panic!("Chooser only requests scoped widget focus")
+            };
+            let mut view = view(app, self.scrolled, self.nested, self.show_review);
+            let tree = self.tree.get_or_insert_with(|| Tree::new(view.as_widget()));
+            view.as_widget().diff(tree);
+            let node =
+                view.as_widget_mut()
+                    .layout(tree, &(), &layout::Limits::new(Size::ZERO, self.size));
+            loop {
+                view.as_widget_mut()
+                    .operate(tree, Layout::new(&node), &(), operation.as_mut());
+                match operation.finish() {
+                    operation::Outcome::Chain(next) => operation = next,
+                    _ => break,
+                }
+            }
+        }
+    }
+    async fn dispatch(&mut self, app: &mut App, messages: Vec<Message>) {
+        for message in messages {
+            let task = app.update(message);
+            self.perform(app, task).await;
+        }
+    }
+}
+fn key(key: keyboard::key::Named, shift: bool) -> Input {
+    Input::Keyboard(keyboard::Event::KeyPressed {
+        key: keyboard::Key::Named(key),
+        modified_key: keyboard::Key::Named(key),
+        physical_key: keyboard::key::Physical::Code(keyboard::key::Code::Space),
+        location: keyboard::Location::Standard,
+        modifiers: if shift {
+            keyboard::Modifiers::SHIFT
+        } else {
+            keyboard::Modifiers::empty()
+        },
+        text: None,
+        repeat: false,
+    })
+}
+fn typing(raw: &str) -> Vec<(Input, Option<Point>)> {
+    raw.chars()
+        .map(|character| {
+            let raw = character.to_string();
+            (
+                Input::Keyboard(keyboard::Event::KeyPressed {
+                    key: keyboard::Key::Character(raw.clone().into()),
+                    modified_key: keyboard::Key::Character(raw.clone().into()),
+                    physical_key: keyboard::key::Physical::Code(keyboard::key::Code::KeyA),
+                    location: keyboard::Location::Standard,
+                    modifiers: keyboard::Modifiers::empty(),
+                    text: Some(raw.into()),
+                    repeat: false,
+                }),
+                None,
+            )
+        })
+        .collect()
+}
+
+#[tokio::test]
+async fn mounted_reference_trigger_tabs_to_root_popup_search_escape_and_exact_adjacent_fields() {
+    let mut app = inspector(catalog(), OWNER);
+    let accepted = app.document.bundle().clone();
+    let original = raw(&app);
+    let mut mount = Mount::default();
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(
+        &app,
+        fields.field(&WidgetId::new("before-reference")).0.center(),
+    );
+    mount.dispatch(&mut app, messages).await;
+    let (_, fields, _) = mount.frame(&app, &[(key(keyboard::key::Named::Tab, false), None)]);
+    let id = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+    assert!(
+        fields.field(&id).1,
+        "Tab reaches the real reference trigger"
+    );
+    let messages = mount
+        .frame(&app, &[(key(keyboard::key::Named::Enter, false), None)])
+        .0;
+    assert_eq!(messages.len(), 1, "One keyboard activation opens one field");
+    mount.dispatch(&mut app, messages).await;
+    let popup = mount
+        .frame(&app, &[])
+        .2
+        .expect("App root overlay is mounted");
+    assert!(
+        popup.x >= 0.
+            && popup.y >= 0.
+            && popup.x + popup.width <= 360.
+            && popup.y + popup.height <= 320.
+    );
+    let mut inputs = typing("@controller_0720");
+    inputs.push((key(keyboard::key::Named::Escape, false), None));
+    let messages = mount.frame(&app, &inputs).0;
+    mount.dispatch(&mut app, messages).await;
+    let (_, fields, popup) = mount.frame(&app, &[]);
+    assert!(popup.is_none());
+    assert!(
+        fields.field(&id).1,
+        "Escape returns to its exact reference field"
+    );
+    assert_eq!(raw(&app), original);
+    assert_eq!(app.document.bundle(), &accepted);
+    for (backwards, expected) in [(false, "after-reference"), (true, "before-reference")] {
+        let messages = mount.click(&app, fields.field(&id).0.center());
+        mount.dispatch(&mut app, messages).await;
+        let messages = mount
+            .frame(&app, &[(key(keyboard::key::Named::Tab, backwards), None)])
+            .0;
+        mount.dispatch(&mut app, messages).await;
+        let (_, fields, popup) = mount.frame(&app, &[]);
+        assert!(popup.is_none());
+        assert!(
+            fields.field(&WidgetId::new(expected)).1,
+            "Chooser Tab stays within the originating form"
+        );
+    }
+    assert_eq!(app.document.bundle(), &accepted);
+}
+
+#[tokio::test]
+async fn mounted_reference_choice_stages_literal_identity_and_delayed_focus_cannot_hit_replacement_field()
+ {
+    let mut app = inspector(catalog(), OWNER);
+    let accepted = app.document.bundle().clone();
+    let mut mount = Mount::default();
+    let id = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(&app, fields.field(&id).0.center());
+    mount.dispatch(&mut app, messages).await;
+    let messages = mount.frame(&app, &typing("@controller_0720")).0;
+    mount.dispatch(&mut app, messages).await;
+    assert_eq!(
+        app.reference_authoring
+            .opened
+            .as_ref()
+            .unwrap()
+            .chooser
+            .count(),
+        1
+    );
+    let messages = mount
+        .frame(&app, &[(key(keyboard::key::Named::Enter, false), None)])
+        .0;
+    assert_eq!(messages.len(), 1);
+    let delayed_focus = app.update(messages.into_iter().next().unwrap());
+    assert_eq!(
+        app.draft.as_ref().unwrap().value.pointer(PATH),
+        Some(&json!(Id::from_u128(BASE + 720)))
+    );
+    assert_eq!(app.document.bundle(), &accepted);
+    // A structural edit occurs after Choose but before its asynchronous focus.
+    app.draft
+        .as_mut()
+        .unwrap()
+        .shape_scoped(PATH, Value::Null)
+        .unwrap();
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(
+        &app,
+        fields.field(&WidgetId::new("after-reference")).0.center(),
+    );
+    mount.dispatch(&mut app, messages).await;
+    mount.perform(&app, delayed_focus).await;
+    let fields = mount.frame(&app, &[]).1;
+    assert!(
+        fields.field(&WidgetId::new("after-reference")).1,
+        "A missing old field target makes no focus changes"
+    );
+    assert!(
+        !fields
+            .field(&trigger::field_id(
+                app.draft.as_ref().unwrap().reference_generation(),
+                PATH
+            ))
+            .1
+    );
+    assert_eq!(app.document.bundle(), &accepted);
+}
+
+#[tokio::test]
+async fn mounted_scrolled_reference_anchor_uses_window_geometry_for_pointer_and_keyboard() {
+    let mut app = inspector(catalog(), OWNER);
+    let mut mount = Mount {
+        scrolled: true,
+        ..Default::default()
+    };
+    mount.frame(&app, &[]);
+    mount
+        .perform(
+            &app,
+            iced::widget::operation::snap_to("reference-scroll", scrollable::RelativeOffset::END),
+        )
+        .await;
+    let fields = mount.frame(&app, &[]).1;
+    let id = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+    let content = fields.field(&id).0;
+    let (viewport, offset) = fields.scrolls[0];
+    assert!(offset.y > 400., "Fixture is genuinely scrolled");
+    let expected = Rectangle {
+        x: content.x - offset.x,
+        y: content.y - offset.y,
+        ..content
+    }
+    .intersection(&viewport)
+    .unwrap();
+    let messages = mount.click(&app, expected.center());
+    let [Message::FieldReferenceOpen(request)] = messages.as_slice() else {
+        panic!("Scrolled field should emit one actual Open")
+    };
+    assert_eq!(request.anchor, expected);
+    mount.dispatch(&mut app, messages).await;
+    let close = app.update(Message::Escape);
+    mount.perform(&app, close).await;
+    let messages = mount
+        .frame(&app, &[(key(keyboard::key::Named::Enter, false), None)])
+        .0;
+    let [Message::FieldReferenceOpen(request)] = messages.as_slice() else {
+        panic!("Focused scrolled field opens without a pointer")
+    };
+    assert_eq!(request.anchor, expected);
+}
+
+#[tokio::test]
+async fn mounted_fresh_tab_reveals_offscreen_reference_and_return_reveals_it_again() {
+    for nested in [false, true] {
+        let mut app = inspector(catalog(), OWNER);
+        let original = raw(&app);
+        let source = app.document.bundle().clone();
+        let mut mount = Mount {
+            scrolled: true,
+            nested,
+            ..Default::default()
+        };
+        let fields = mount.frame(&app, &[]).1;
+        assert!(
+            fields
+                .scrolls
+                .iter()
+                .all(|(_, offset)| *offset == Vector::ZERO)
+        );
+        assert!(fields.field(&WidgetId::new("before-reference")).0.y > 180.);
+        let messages = mount
+            .frame(&app, &[(key(keyboard::key::Named::Tab, false), None)])
+            .0;
+        assert!(
+            messages.is_empty(),
+            "Keyboard reveal must not author any input"
+        );
+        let fields = mount.frame(&app, &[]).1;
+        assert!(fields.field(&WidgetId::new("before-reference")).1);
+        assert!(
+            fields.scrolls.iter().all(|(_, offset)| offset.y > 0.),
+            "Every enclosing viewport reveals fresh focus"
+        );
+        let id = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+        let offset: f32 = fields.scrolls.iter().map(|(_, offset)| offset.y).sum();
+        assert!(
+            fields.field(&id).0.y - offset >= 180.,
+            "The next reference starts below the fold"
+        );
+        let messages = mount
+            .frame(&app, &[(key(keyboard::key::Named::Tab, false), None)])
+            .0;
+        assert!(messages.is_empty());
+        let fields = mount.frame(&app, &[]).1;
+        let offset: f32 = fields.scrolls.iter().map(|(_, offset)| offset.y).sum();
+        let (bounds, focused) = fields.field(&id);
+        assert!(focused);
+        assert!(bounds.y - offset >= -0.01 && bounds.y + bounds.height - offset <= 180.01);
+        let messages = mount
+            .frame(&app, &[(key(keyboard::key::Named::Enter, false), None)])
+            .0;
+        assert_eq!(
+            messages.len(),
+            1,
+            "A newly revealed field opens through Enter"
+        );
+        mount.dispatch(&mut app, messages).await;
+        let return_focus = app.update(Message::Escape);
+        mount
+            .perform(
+                &app,
+                iced::widget::operation::snap_to(
+                    "reference-scroll",
+                    scrollable::RelativeOffset::START,
+                ),
+            )
+            .await;
+        if nested {
+            mount
+                .perform(
+                    &app,
+                    iced::widget::operation::snap_to(
+                        "outer-reference-scroll",
+                        scrollable::RelativeOffset::START,
+                    ),
+                )
+                .await;
+        }
+        assert!(
+            mount
+                .frame(&app, &[])
+                .1
+                .scrolls
+                .iter()
+                .all(|(_, offset)| *offset == Vector::ZERO)
+        );
+        mount.perform(&app, return_focus).await;
+        let fields = mount.frame(&app, &[]).1;
+        let offset: f32 = fields.scrolls.iter().map(|(_, offset)| offset.y).sum();
+        let (bounds, focused) = fields.field(&id);
+        assert!(
+            focused && bounds.y - offset >= -0.01 && bounds.y + bounds.height - offset <= 180.01
+        );
+        assert_eq!(raw(&app), original);
+        assert_eq!(app.document.bundle(), &source);
+    }
+}
+
+#[tokio::test]
+async fn mounted_form_tab_enters_in_both_directions_and_cycles_boundaries_without_losing_focus() {
+    for backwards in [false, true] {
+        let app = inspector(catalog(), OWNER);
+        let original = raw(&app);
+        let mut mount = Mount::default();
+        let reference = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+        let forward = [
+            WidgetId::new("before-reference"),
+            reference.clone(),
+            WidgetId::new("after-reference"),
+        ];
+        let reverse = [
+            WidgetId::new("after-reference"),
+            reference,
+            WidgetId::new("before-reference"),
+        ];
+        let expected = if backwards { &reverse } else { &forward };
+        for n in 0..7 {
+            let (messages, fields, popup) =
+                mount.frame(&app, &[(key(keyboard::key::Named::Tab, backwards), None)]);
+            assert!(messages.is_empty() && popup.is_none());
+            assert!(fields.field(&expected[n % 3]).1);
+            assert_eq!(
+                fields
+                    .values
+                    .iter()
+                    .filter(|(_, _, focused)| *focused)
+                    .count(),
+                1
+            );
+        }
+        assert_eq!(raw(&app), original);
+        assert!(!app.document.can_undo());
+    }
+}
+
+#[tokio::test]
+async fn mounted_delayed_return_cannot_focus_under_review_and_fresh_modal_tab_owns_its_form() {
+    let mut p = catalog();
+    trace(&mut p, Id::from_u128(300), OWNER, Id::from_u128(200));
+    let mut app = inspector(p, OWNER);
+    let source = app.document.bundle().clone();
+    let original = raw(&app);
+    let mut mount = Mount {
+        show_review: true,
+        ..Default::default()
+    };
+    let id = trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH);
+    let session = app.draft.as_ref().unwrap().reference_session();
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(&app, fields.field(&id).0.center());
+    mount.dispatch(&mut app, messages).await;
+    let return_focus = app.update(Message::Escape);
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(
+        &app,
+        fields.field(&WidgetId::new("after-reference")).0.center(),
+    );
+    mount.dispatch(&mut app, messages).await;
+    let _ = app.update(Message::StartSemanticReview(Id::from_u128(300)));
+    let facet = FacetSelector::Header(HeaderFacet::Parent);
+    send_review(&mut app, RowEvent::Select(facet.clone()));
+    send_review(
+        &mut app,
+        RowEvent::Decide(facet, Some(SemanticDecision::Candidate)),
+    );
+    assert_eq!(
+        app.draft.as_ref().unwrap().reference_session(),
+        session,
+        "Old Inspector really remains mounted"
+    );
+    assert_eq!(
+        trigger::field_id(app.draft.as_ref().unwrap().reference_generation(), PATH),
+        id
+    );
+    let review_before = review(&app).recovery_snapshot().unwrap();
+    let review_field = trigger::field_id(
+        review(&app)
+            .reference_form(app.project())
+            .unwrap()
+            .reference_generation(),
+        "/parent",
+    );
+    mount.perform(&app, return_focus).await;
+    let fields = mount.frame(&app, &[]).1;
+    assert!(
+        !fields.field(&id).1,
+        "A live old field underneath a modal cannot receive the stale focus task"
+    );
+    assert!(fields.field(&WidgetId::new("after-reference")).1);
+    assert!(!fields.field(&review_field).1);
+    let (messages, fields, _) = mount.frame(&app, &[(key(keyboard::key::Named::Tab, false), None)]);
+    assert!(messages.is_empty());
+    assert!(
+        fields.field(&review_field).1,
+        "Review entry ignores retained focus under its modal"
+    );
+    assert!(
+        !fields.field(&WidgetId::new("after-reference")).1,
+        "Modal focus acquisition deactivates background inputs"
+    );
+    let messages = mount.frame(&app, &typing("x")).0;
+    assert!(
+        messages.is_empty(),
+        "A character at the focused Review trigger cannot type into the Inspector below it"
+    );
+    let (messages, fields, _) = mount.frame(&app, &[(key(keyboard::key::Named::Tab, true), None)]);
+    assert!(messages.is_empty());
+    assert!(fields.field(&review_field).1);
+    assert!(!fields.field(&id).1);
+    assert_eq!(review(&app).recovery_snapshot().unwrap(), review_before);
+    assert_eq!(raw(&app), original);
+    assert_eq!(app.document.bundle(), &source);
+}
+
+#[tokio::test]
+async fn mounted_review_pointer_open_and_outside_dismissal_keep_background_input_inactive() {
+    let mut p = catalog();
+    trace(&mut p, Id::from_u128(300), OWNER, Id::from_u128(200));
+    let mut app = inspector(p, OWNER);
+    let original = raw(&app);
+    let source = app.document.bundle().clone();
+    let mut mount = Mount {
+        show_review: true,
+        ..Default::default()
+    };
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(
+        &app,
+        fields.field(&WidgetId::new("after-reference")).0.center(),
+    );
+    mount.dispatch(&mut app, messages).await;
+    let _ = app.update(Message::StartSemanticReview(Id::from_u128(300)));
+    let facet = FacetSelector::Header(HeaderFacet::Parent);
+    send_review(&mut app, RowEvent::Select(facet.clone()));
+    send_review(
+        &mut app,
+        RowEvent::Decide(facet, Some(SemanticDecision::Candidate)),
+    );
+    let saved = review(&app).recovery_snapshot().unwrap();
+    let id = trigger::field_id(
+        review(&app)
+            .reference_form(app.project())
+            .unwrap()
+            .reference_generation(),
+        "/parent",
+    );
+    let fields = mount.frame(&app, &[]).1;
+    assert!(
+        fields.field(&WidgetId::new("after-reference")).1,
+        "Fixture retains Inspector focus before the modal receives input"
+    );
+    let messages = mount.click(&app, fields.field(&id).0.center());
+    mount.dispatch(&mut app, messages).await;
+    assert!(matches!(
+        &app.reference_authoring.opened.as_ref().unwrap().host,
+        Host::Review { .. }
+    ));
+    let fields = mount.frame(&app, &[]).1;
+    assert!(!fields.field(&WidgetId::new("after-reference")).1);
+    let messages = mount.click(&app, Point::new(359., 319.));
+    assert!(matches!(
+        messages.as_slice(),
+        [Message::Workflow(workflow::Event::Semantic(event))] if matches!(event.as_ref(),
+            semantic_review::Event::Row {
+                event: RowEvent::ReferenceEvent(chooser::Event {
+                    action: Action::Close(Close::Outside),
+                    ..
+                }),
+                ..
+            }
+        )
+    ));
+    for message in messages {
+        let task = app.update(message);
+        assert!(
+            iced_runtime::task::into_stream(task).is_none(),
+            "Outside dismissal must not request focus or apply"
+        );
+    }
+    let (messages, fields, popup) = mount.frame(&app, &typing("x"));
+    assert!(messages.is_empty() && popup.is_none());
+    assert!(!fields.field(&WidgetId::new("after-reference")).1);
+    assert_eq!(review(&app).recovery_snapshot().unwrap(), saved);
+    assert_eq!(raw(&app), original);
+    assert_eq!(app.document.bundle(), &source);
+}
+
+#[tokio::test]
+async fn mounted_reverse_review_required_rationale_remains_editable_beside_candidate_reference_form()
+ {
+    let mut p = persistence::decode(include_bytes!(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../../harness/fixtures/interface-operation-probe/output/boundary-only.json"
+    )))
+    .unwrap();
+    let sa = p
+        .elements
+        .values()
+        .find(|element| element.alias == "operation_probe_43")
+        .unwrap()
+        .id;
+    let allocation = p
+        .relations
+        .values()
+        .find(|relation| relation.alias == "operation_probe_30")
+        .unwrap()
+        .id;
+    // The boundary fixture deliberately has no selected operation. Author one
+    // through the validated command path before testing reverse omission.
+    let mut message = p.elements[&sa].clone();
+    let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange { operation, .. },
+        ..
+    }) = message.shared_mut()
+    else {
+        panic!("The operation fixture must contain an Exchange call")
+    };
+    *operation = Some(OperationUse {
+        allocation: Some(allocation),
+    });
+    p = execute_batch(&p, &[Command::EditElement(sa, message)]).unwrap();
+    assert!(matches!(
+        oa_core::operations::resolve(&p, sa).unwrap(),
+        oa_core::operations::OperationResolution::Selected(value)
+            if value.allocation == allocation
+    ));
+    let inspector_id = Id::new_v4();
+    element(
+        &mut p,
+        inspector_id,
+        Kind::DataType,
+        Layer::Oa,
+        "Inspector record",
+        None,
+    );
+    let scenario = p
+        .add_element(Kind::Scenario, Layer::Oa, "Operational counterpart", None)
+        .unwrap();
+    let oa = p
+        .add_element(
+            Kind::Occurrence,
+            Layer::Oa,
+            "Operational message",
+            Some(scenario),
+        )
+        .unwrap();
+    *p.elements.get_mut(&oa).unwrap().shared_mut().unwrap() = SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange {
+            exchange: None,
+            sender: None,
+            receiver: None,
+            message_kind: MessageKind::Asynchronous,
+            reply_to: None,
+            values: vec![],
+            operation: None,
+        },
+        precondition: String::new(),
+        postcondition: String::new(),
+    };
+    p.elements
+        .get_mut(&scenario)
+        .unwrap()
+        .steps_mut()
+        .unwrap()
+        .push(oa);
+    let trace_id = Id::new_v4();
+    trace(&mut p, trace_id, oa, sa);
+    let mut app = inspector(p, inspector_id);
+    let source = app.document.bundle().clone();
+    let inspector_raw = raw(&app);
+    let _ = app.update(Message::StartSemanticReview(trace_id));
+    let _ = app.update(Message::Workflow(workflow::Event::semantic(
+        semantic_review::Event::Direction(TransitionDirection::SaToOa),
+    )));
+    let facet = FacetSelector::Header(HeaderFacet::Parent);
+    send_review(&mut app, RowEvent::Select(facet.clone()));
+    send_review(
+        &mut app,
+        RowEvent::Decide(facet, Some(SemanticDecision::Candidate)),
+    );
+    send_review(&mut app, RowEvent::OperationOmission(true));
+    assert_eq!(review(&app).direction, TransitionDirection::SaToOa);
+    assert_eq!(review(&app).operation_omission.as_deref(), Some(""));
+    let candidate = serde_json::to_value(
+        review(&app)
+            .reference_form(app.project())
+            .unwrap_or_else(|| {
+                panic!(
+                    "Reverse review candidate: selected={:?}, decisions={:?}, error={:?}",
+                    review(&app).selected,
+                    review(&app).decisions,
+                    review(&app).error
+                )
+            })
+            .recovery_snapshot(),
+    )
+    .unwrap();
+    let mut mount = Mount {
+        show_review: true,
+        ..Default::default()
+    };
+    let fields = mount.frame(&app, &[]).1;
+    let messages = mount.click(
+        &app,
+        fields.field(&WidgetId::new("review-rationale")).0.center(),
+    );
+    mount.dispatch(&mut app, messages).await;
+    let messages = mount.frame(&app, &typing("Engineering reason")).0;
+    assert_eq!(
+        messages.len(),
+        "Engineering reason".chars().count(),
+        "Every key reaches the legitimate sibling inside Review"
+    );
+    assert!(messages.iter().all(|message| matches!(
+        message,
+        Message::Workflow(workflow::Event::Semantic(event)) if matches!(event.as_ref(), semantic_review::Event::Row {
+            event: RowEvent::OperationRationale(_),
+            ..
+        })
+    )));
+    mount.dispatch(&mut app, messages).await;
+    assert_eq!(
+        review(&app).operation_omission.as_deref(),
+        Some("Engineering reason")
+    );
+    assert!(
+        mount
+            .frame(&app, &[])
+            .1
+            .field(&WidgetId::new("review-rationale"))
+            .1
+    );
+    assert_eq!(
+        serde_json::to_value(
+            review(&app)
+                .reference_form(app.project())
+                .unwrap()
+                .recovery_snapshot()
+        )
+        .unwrap(),
+        candidate
+    );
+    assert_eq!(raw(&app), inspector_raw);
+    assert_eq!(app.document.bundle(), &source);
+    assert!(!app.document.can_undo());
+}

crates/oa-desktop/src/app/repair_save_state_tests.rs

@@ -0,0 +1,263 @@
+use super::*;
+
+const VALID: &str = concat!(
+    "arcadia 7;\r\n",
+    "project repair \"Repair 救援\" id \"9e8f0000-0000-4000-8000-000000000001\" {\r\n",
+    "    oa_activity assess \"Assess\" id \"9e8f0000-0000-4000-8000-000000000002\" {}\r\n",
+    "}\r\n",
+);
+
+fn open(app: &mut App, path: &std::path::Path) {
+    let _ = app.update(Message::Loaded(Ok(Some(
+        read_snapshot(path.to_owned()).unwrap(),
+    ))));
+}
+
+fn edit(app: &mut App, text: &str) {
+    let _ = app.update(Message::SourceEdit(text_editor::Action::SelectAll));
+    let _ = app.update(Message::SourceEdit(text_editor::Action::Edit(
+        text_editor::Edit::Paste(Arc::new(text.into())),
+    )));
+}
+
+fn save(app: &mut App, path: &std::path::Path) {
+    let receipt = write_snapshot(
+        app.canvas_document,
+        app.document.revision(),
+        app.document.snapshot(),
+        path.to_owned(),
+        app.disk_project.clone(),
+    )
+    .unwrap();
+    let _ = app.update(Message::Saved(Ok(Some(receipt))));
+}
+
+#[test]
+fn repair_to_previous_saved_bytes_requires_save_at_new_destination_and_guards_close() {
+    for extra in [
+        "    include \"missing.arcadia\";\r\n",
+        "    oa_activity assess \"Duplicate\" id \"9e8f0000-0000-4000-8000-000000000003\" {}\r\n",
+    ] {
+        let first = tempfile::tempdir().unwrap();
+        let second = tempfile::tempdir().unwrap();
+        let first_path = first.path().canonicalize().unwrap().join("project.arcadia");
+        let second_path = second
+            .path()
+            .canonicalize()
+            .unwrap()
+            .join("project.arcadia");
+        let invalid = VALID.strip_suffix("}\r\n").unwrap().to_owned() + extra + "}\r\n";
+        std::fs::write(&first_path, VALID).unwrap();
+        std::fs::write(&second_path, &invalid).unwrap();
+        let mut app = App::with_project(Project::empty());
+        open(&mut app, &first_path);
+        assert!(!app.dirty());
+        let before = app.document.snapshot();
+        let revision = app.document.revision();
+        open(&mut app, &second_path);
+        assert!(!app.source_workspace.applied);
+        assert!(Arc::ptr_eq(&before, &app.document.snapshot()));
+        edit(&mut app, VALID);
+        assert!(app.apply_source(), "{}", app.status);
+        assert!(app.source_workspace.applied);
+        assert!(!app.source_dirty());
+        assert_eq!(app.document.bundle(), &before.bundle);
+        assert_eq!(app.project(), &before.decoded.project);
+        assert_eq!(app.document.revision(), revision);
+        assert!(
+            !app.document.can_undo(),
+            "Equal content creates no history step"
+        );
+        assert!(app.document.dirty());
+        assert_eq!(app.hosted_label(), "Unsaved changes");
+        assert_eq!(std::fs::read(&second_path).unwrap(), invalid.as_bytes());
+        assert_eq!(std::fs::read(&first_path).unwrap(), VALID.as_bytes());
+        let close = window::Id::unique();
+        let task = app.update(Message::Request(Pending::Close(close)));
+        assert!(iced_runtime::task::into_stream(task).is_none());
+        assert!(matches!(app.pending, Some(Pending::Close(id)) if id == close));
+        let _ = app.update(Message::Cancel);
+        save(&mut app, &second_path);
+        assert!(!app.dirty());
+        assert_eq!(app.hosted_label(), "All changes saved");
+        assert_eq!(std::fs::read(&second_path).unwrap(), VALID.as_bytes());
+        assert_eq!(std::fs::read(&first_path).unwrap(), VALID.as_bytes());
+    }
+}
+
+#[test]
+fn repair_history_compares_to_new_disk_baseline_and_then_successful_save() {
+    let directory = tempfile::tempdir().unwrap();
+    let path = directory
+        .path()
+        .canonicalize()
+        .unwrap()
+        .join("project.arcadia");
+    std::fs::write(&path, VALID).unwrap();
+    let mut app = App::with_project(Project::empty());
+    open(&mut app, &path);
+    let before = app.document.snapshot();
+    let invalid = format!("{VALID} unfinished {{");
+    std::fs::write(&path, &invalid).unwrap();
+    open(&mut app, &path);
+    let repaired = format!("{VALID}// Repaired rationale\r\n");
+    edit(&mut app, &repaired);
+    assert!(app.apply_source());
+    assert!(app.dirty());
+    let _ = app.update(Message::Undo);
+    assert_eq!(app.document.bundle(), &before.bundle);
+    assert!(
+        app.dirty(),
+        "Old saved bytes are not saved at the repair destination"
+    );
+    let _ = app.update(Message::Redo);
+    assert!(app.dirty());
+    assert_eq!(std::fs::read(&path).unwrap(), invalid.as_bytes());
+
+    std::fs::write(&path, "external edit").unwrap();
+    let failed = write_snapshot(
+        app.canvas_document,
+        app.document.revision(),
+        app.document.snapshot(),
+        path.clone(),
+        app.disk_project.clone(),
+    )
+    .unwrap_err();
+    let _ = app.update(Message::Saved(Err(failed)));
+    assert!(app.dirty());
+    assert_eq!(std::fs::read(&path).unwrap(), b"external edit");
+    std::fs::write(&path, &invalid).unwrap();
+    save(&mut app, &path);
+    assert!(!app.dirty());
+    let _ = app.update(Message::Undo);
+    assert!(app.dirty());
+    assert_eq!(app.document.bundle(), &before.bundle);
+    let _ = app.update(Message::Redo);
+    assert!(!app.dirty(), "Redo to the new saved snapshot is clean");
+    assert_eq!(std::fs::read(&path).unwrap(), repaired.as_bytes());
+}
+
+#[test]
+fn valid_equal_content_at_distinct_destinations_stays_clean() {
+    let first = tempfile::tempdir().unwrap();
+    let second = tempfile::tempdir().unwrap();
+    let first_path = first.path().canonicalize().unwrap().join("project.arcadia");
+    let second_path = second
+        .path()
+        .canonicalize()
+        .unwrap()
+        .join("project.arcadia");
+    std::fs::write(&first_path, VALID).unwrap();
+    std::fs::write(&second_path, VALID).unwrap();
+    let mut app = App::with_project(Project::empty());
+    open(&mut app, &first_path);
+    let before = app.document.bundle().clone();
+    open(&mut app, &second_path);
+    assert_eq!(app.document.bundle(), &before);
+    assert_eq!(app.path.as_ref(), Some(&second_path));
+    assert!(!app.dirty());
+    assert_eq!(app.hosted_label(), "All changes saved");
+}
+
+#[test]
+fn recovering_applied_repair_rebinds_rolled_back_disk_bytes_without_changing_model() {
+    let first = tempfile::tempdir().unwrap();
+    let second = tempfile::tempdir().unwrap();
+    let first_path = first.path().canonicalize().unwrap().join("project.arcadia");
+    let root = second.path().canonicalize().unwrap();
+    let path = root.join("project.arcadia");
+    let before = VALID.replace("Repair 救援", "Before 救援");
+    std::fs::write(&first_path, VALID).unwrap();
+    std::fs::write(&path, VALID).unwrap();
+    let journal = root.join(".arcadia-save-project.arcadia.journal");
+    std::fs::create_dir(&journal).unwrap();
+    std::fs::write(
+        journal.join("journal.json"),
+        br#"{"version":1,"entry":"project.arcadia","files":[{"path":"project.arcadia","before":true,"write":true}]}"#,
+    )
+    .unwrap();
+    std::fs::write(journal.join("0.before"), &before).unwrap();
+    std::fs::write(journal.join("0.after"), VALID).unwrap();
+    let mut app = App::with_project(Project::empty());
+    open(&mut app, &first_path);
+    let accepted = app.document.snapshot();
+    open(&mut app, &path);
+    assert_eq!(app.pending_recovery.as_ref(), Some(&path));
+    assert!(!app.source_workspace.applied);
+    assert!(app.apply_source());
+    assert!(
+        !app.dirty(),
+        "Current bytes still match disk before rollback"
+    );
+    let _ = app.update(Message::SourceRecovered(recover_snapshot(path.clone())));
+    assert!(app.pending_recovery.is_none());
+    assert!(!journal.exists());
+    assert_eq!(std::fs::read(&path).unwrap(), before.as_bytes());
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    assert!(!app.source_dirty());
+    assert!(app.dirty(), "Recovery changed disk, not the accepted model");
+    assert_eq!(app.hosted_label(), "Unsaved changes");
+    save(&mut app, &path);
+    assert!(!app.dirty());
+    assert_eq!(std::fs::read(&path).unwrap(), VALID.as_bytes());
+}
+
+#[test]
+fn recovery_missing_entry_or_failed_reload_preserves_current_destination_save_authority() {
+    for (current_destination, failed_reload) in
+        [(true, false), (false, false), (true, true), (false, true)]
+    {
+        let directory = tempfile::tempdir().unwrap();
+        let root = directory.path().canonicalize().unwrap();
+        let path = root.join("project.arcadia");
+        std::fs::write(&path, VALID).unwrap();
+        let mut app = App::with_project(Project::empty());
+        open(&mut app, &path);
+        let accepted = app.document.snapshot();
+        let journal = root.join(".arcadia-save-project.arcadia.journal");
+        std::fs::create_dir(&journal).unwrap();
+        std::fs::write(
+            journal.join("journal.json"),
+            br#"{"version":1,"entry":"project.arcadia","files":[{"path":"project.arcadia","before":false,"write":true}]}"#,
+        )
+        .unwrap();
+        std::fs::write(journal.join("0.after"), VALID).unwrap();
+        open(&mut app, &path);
+        assert!(app.apply_source());
+        assert!(!app.dirty());
+        let destination = tempfile::tempdir().unwrap();
+        let saved_elsewhere = destination
+            .path()
+            .canonicalize()
+            .unwrap()
+            .join("project.arcadia");
+        if !current_destination {
+            save(&mut app, &saved_elsewhere);
+            assert_eq!(app.path.as_ref(), Some(&saved_elsewhere));
+            assert_eq!(app.pending_recovery.as_ref(), Some(&path));
+        }
+        let mut receipt = recover_snapshot(path.clone()).unwrap();
+        assert!(
+            receipt.disk.as_ref().unwrap().bundle.files.is_empty(),
+            "Missing entry reloads as an empty repair workspace"
+        );
+        if failed_reload {
+            // Separately exercise the adapter's successful-recovery/failed-read
+            // boundary; first-save rollback itself does not cause a read error.
+            receipt.disk = Err("Injected post-recovery reload failure".into());
+        }
+        let _ = app.update(Message::SourceRecovered(Ok(receipt)));
+        assert!(!path.exists());
+        assert!(!journal.exists());
+        assert!(app.pending_recovery.is_none());
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        assert_eq!(app.dirty(), current_destination);
+        if current_destination {
+            let _ = app.update(Message::Request(Pending::New));
+            assert!(matches!(app.pending, Some(Pending::New)));
+        } else {
+            assert_eq!(app.path.as_ref(), Some(&saved_elsewhere));
+            assert_eq!(std::fs::read(&saved_elsewhere).unwrap(), VALID.as_bytes());
+        }
+    }
+}

crates/oa-desktop/src/app/review_navigation_tests.rs

@@ -16,7 +16,7 @@ fn state(app: &App) -> &State {
 }
 fn row_event(app: &mut App, event: RowEvent) {
     let event = state(app).address_event(event);
-    send(app, Message::Workflow(Event::Semantic(event)));
+    send(app, Message::Workflow(Event::semantic(event)));
 }
 fn fixture(reverse: bool, destination_view: bool) -> (App, Id, Id, Id, Option<Id>) {
     let mut p = Project::empty();

crates/oa-desktop/src/app/source_symbols.rs

@@ -0,0 +1,507 @@
+//! Current draft navigation, isolated from model application and disk discovery.
+use super::*;
+use crate::source_navigation::{self as nav, query};
+use std::sync::atomic::Ordering;
+
+fn admission_notice(error: query::AdmissionError) -> String {
+    use nav::symbols::{BuildError, InputProblem, Resource};
+    let (limit, resource) = match error {
+        query::AdmissionError::Index(BuildError::Limit { limit, resource, .. }) => (limit, resource),
+        query::AdmissionError::Outline { error, .. } => (error.limit, match error.resource {
+            language::OutlineResource::SourceBytes => Resource::SourceBytes,
+            language::OutlineResource::Tokens => Resource::Tokens,
+            language::OutlineResource::Declarations => Resource::Records,
+        }),
+        query::AdmissionError::Index(BuildError::Input { problem, .. }) => return match problem {
+            InputProblem::NonCanonicalPath | InputProblem::DuplicateOrCaseCollidingPath =>
+                "Navigation needs distinct relative source paths. Check file names and include paths.".into(),
+            _ => "Navigation could not verify the current source locations. Correct source errors and try again.".into(),
+        },
+    };
+    let unit = match resource {
+        Resource::Files => "loaded files",
+        Resource::SourceBytes => "source bytes",
+        Resource::PathBytes => "bytes in file paths",
+        Resource::Tokens => "source tokens",
+        Resource::Records => "declarations and references",
+    };
+    format!(
+        "Navigation reached its limit of {limit} {unit}. Reduce the loaded source size and try again."
+    )
+}
+
+impl App {
+    pub fn source_symbol_context(&self) -> nav::SymbolContext {
+        nav::SymbolContext {
+            session: self.source_workspace.session(),
+            path: self.source_workspace.active.clone(),
+        }
+    }
+
+    pub fn source_symbol_message(&self, event: nav::SymbolEvent) -> Message {
+        Message::SourceSymbols(self.source_symbol_context(), event)
+    }
+
+    pub fn source_find_close_message(&self) -> Message {
+        Message::SourceFindClose(self.source_symbol_context(), self.source_find_instance)
+    }
+    pub fn source_key(&self) -> query::SnapshotKey {
+        query::SnapshotKey {
+            workspace: self.source_workspace.session(),
+            revision: self.source_workspace.revision(),
+        }
+    }
+
+    fn with_source_input<T>(&self, use_input: impl FnOnce(query::Input<'_>) -> T) -> T {
+        let files: Vec<_> = self
+            .source_workspace
+            .files
+            .iter()
+            .map(|(path, buffer)| query::DraftFile {
+                path,
+                text: &buffer.text,
+            })
+            .collect();
+        let accepted = self.document.bundle();
+        let validated: Vec<_> = accepted
+            .files
+            .iter()
+            .map(|(path, text)| query::DraftFile { path, text })
+            .collect();
+        use_input(query::Input {
+            key: self.source_key(),
+            entry: &self.source_workspace.entry,
+            files: &files,
+            applied: self.source_workspace.applied,
+            validation: self
+                .source_workspace
+                .applied
+                .then_some(query::ValidatedSources {
+                    entry: &accepted.entry,
+                    files: &validated,
+                }),
+        })
+    }
+
+    fn source_snapshot_matches(&self, snapshot: &query::Snapshot) -> bool {
+        snapshot.key() == self.source_key()
+            && self.with_source_input(|input| snapshot.matches(input))
+    }
+
+    pub fn source_navigation_available(&self) -> bool {
+        self.page == Page::Text
+            && !self.busy
+            && self.pending.is_none()
+            && self.file_prompt.is_none()
+            && !self.delete_pending
+            && self.workflow.is_none()
+            && !self.hosted.visible
+            && self.model_menu.is_none()
+            && self.diagram_usages.is_none()
+            && !self.reference_input_active()
+            && self.architecture.is_none()
+            && !self.behavior.has_pending()
+    }
+
+    /// Mounted widget IDs change when another interaction supersedes a reveal.
+    /// A queued focus operation therefore cannot find a subsequently reused editor.
+    pub fn source_editor_id(&self) -> iced::widget::Id {
+        iced::widget::Id::from(format!(
+            "source-editor-{}-{}-{}",
+            self.source_workspace.session(),
+            self.source_workspace.active,
+            self.source_symbols.interaction
+        ))
+    }
+
+    pub fn source_reveal_ticket(&self) -> Option<Id> {
+        self.source_symbols
+            .reveal
+            .as_ref()
+            .map(|reveal| reveal.ticket)
+    }
+
+    pub(super) fn source_interaction(&mut self) {
+        self.source_symbols.interaction = Id::new_v4();
+        self.source_symbols.request = None;
+        self.source_symbols.reveal = None;
+        self.source_jump = None;
+    }
+
+    pub(super) fn queue_source_reveal(&mut self, cursor: text_editor::Cursor, select_line: bool) {
+        self.source_jump = Some(cursor);
+        self.source_select_line = select_line;
+        self.source_symbols.reveal = Some(nav::Reveal {
+            ticket: Id::new_v4(),
+            interaction: self.source_symbols.interaction,
+            raw_interaction: self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+            snapshot: self.source_key(),
+            path: self.source_workspace.active.clone(),
+        });
+    }
+
+    pub(super) fn restore_source_editor_focus(&mut self) {
+        let cursor = self.source_editor.cursor();
+        if self.source_navigation_available()
+            && nav::exact_cursor(self.source_workspace.text(), cursor)
+        {
+            self.queue_source_reveal(cursor, false);
+        }
+    }
+
+    pub(super) fn source_viewport(&mut self, ticket: Option<Id>) -> Task<Message> {
+        let Some(reveal) = &self.source_symbols.reveal else {
+            return Task::none();
+        };
+        if Some(reveal.ticket) != ticket
+            || reveal.interaction != self.source_symbols.interaction
+            || !nav::interaction::is_current(
+                &self.source_symbols.raw_interaction,
+                reveal.raw_interaction,
+            )
+            || reveal.snapshot != self.source_key()
+            || reveal.path != self.source_workspace.active
+            || !self.source_navigation_available()
+        {
+            return Task::none();
+        }
+        let raw_interaction = reveal.raw_interaction;
+        self.source_symbols.reveal = None;
+        if let Some(cursor) = self.source_jump.take() {
+            if !nav::exact_cursor(self.source_workspace.text(), cursor) {
+                return Task::none();
+            }
+            self.source_editor.move_to(cursor);
+            if self.source_select_line && cursor.selection.is_none() {
+                self.source_editor.perform(text_editor::Action::SelectLine);
+            }
+            return nav::interaction::guarded_focus(
+                self.source_editor_id(),
+                self.source_symbols.raw_interaction.clone(),
+                raw_interaction,
+            );
+        }
+        Task::none()
+    }
+
+    pub(super) fn source_symbol_event(&mut self, event: nav::SymbolEvent) -> Task<Message> {
+        if !self.source_navigation_available() {
+            return Task::none();
+        }
+        match event {
+            nav::SymbolEvent::DiagramUsages => {
+                if self.source_dirty() || !self.source_workspace.applied {
+                    self.source_symbols.open = true;
+                    self.source_symbols.notice = Some("Apply source before finding diagram representations. Your current text is retained.".into());
+                    return Task::none();
+                }
+                let task = self.start_source_query(query::Action::Definition);
+                self.source_diagram_job = self
+                    .source_symbols
+                    .request
+                    .as_ref()
+                    .map(|request| request.job);
+                return task;
+            }
+            nav::SymbolEvent::Close => {
+                self.source_symbols.open = false;
+                self.source_symbols.results = None;
+                self.source_symbols.notice = None;
+            }
+            nav::SymbolEvent::Back => {
+                self.source_symbol_back();
+                // A successful Back needs no empty results panel. Retain an
+                // already open panel, or reveal an actionable return notice.
+                self.source_symbols.open |= self.source_symbols.notice.is_some();
+            }
+            nav::SymbolEvent::Choose {
+                stamp,
+                reference,
+                index,
+            } => {
+                let Some(results) = self.source_symbols.results.clone() else {
+                    return Task::none();
+                };
+                if results.stamp != stamp
+                    || stamp.snapshot != self.source_key()
+                    || self
+                        .source_symbols
+                        .cache
+                        .as_ref()
+                        .is_none_or(|cache| !self.source_snapshot_matches(cache))
+                {
+                    self.source_symbols.notice =
+                        Some("Source changed. Run navigation again for current locations.".into());
+                    return Task::none();
+                }
+                let destination = if reference {
+                    results
+                        .references
+                        .get(index)
+                        .map(|row| (&row.path, row.position, row.end_position))
+                } else {
+                    results
+                        .definitions
+                        .get(index)
+                        .map(|row| (&row.path, row.position, row.end_position))
+                };
+                if let Some((path, start, end)) = destination {
+                    self.source_symbol_jump(path, start, end);
+                }
+            }
+            nav::SymbolEvent::Query(action) => return self.start_source_query(action),
+        }
+        Task::none()
+    }
+
+    fn start_source_query(&mut self, action: query::Action) -> Task<Message> {
+        self.source_symbols.open = true;
+        if !nav::interaction::is_current(
+            &self.source_symbols.raw_interaction,
+            self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+        ) {
+            self.source_symbols.notice = Some("Reopen this workspace to reset navigation.".into());
+            return Task::none();
+        }
+        if self.source_symbols.in_flight.is_some() {
+            self.source_symbols.notice = Some("Navigation is finishing. Try again shortly.".into());
+            return Task::none();
+        }
+        let cursor = self.source_editor.cursor();
+        let Some(offset) = nav::cursor_offset(self.source_workspace.text(), cursor) else {
+            self.source_symbols.notice =
+                Some("Place the cursor on an alias or its @ reference.".into());
+            return Task::none();
+        };
+        self.source_symbols.serial = match self.source_symbols.serial.checked_add(1) {
+            Some(serial) => serial,
+            None => {
+                self.source_workspace.reset_navigation_session();
+                self.source_symbols.back.clear();
+                self.source_symbols.cache = None;
+                0
+            }
+        };
+        let request = nav::Request {
+            job: Id::new_v4(),
+            interaction: self.source_symbols.interaction,
+            raw_interaction: self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+            stamp: query::QueryStamp {
+                snapshot: self.source_key(),
+                serial: self.source_symbols.serial,
+            },
+            path: self.source_workspace.active.clone(),
+            offset,
+            cursor,
+            action,
+        };
+        let cache = self
+            .source_symbols
+            .cache
+            .as_ref()
+            .filter(|cache| self.source_snapshot_matches(cache))
+            .cloned();
+        let input = if cache.is_none() {
+            match self
+                .with_source_input(|input| query::admit_owned(input, query::Limits::default()))
+            {
+                Ok(input) => Some(input),
+                Err(error) => {
+                    self.source_symbols.notice = Some(admission_notice(error));
+                    return Task::none();
+                }
+            }
+        } else {
+            None
+        };
+        self.source_symbols.in_flight = Some(request.job);
+        self.source_symbols.request = Some(request.clone());
+        self.source_symbols.results = None;
+        self.source_symbols.notice = None;
+        Task::perform(
+            async move {
+                let worker_request = request.clone();
+                let result = tokio::task::spawn_blocking(move || {
+                    let snapshot = match cache {
+                        Some(cache) => cache,
+                        None => Arc::new(
+                            input
+                                .expect("admitted input for uncached request")
+                                .capture()
+                                .map_err(admission_notice)?,
+                        ),
+                    };
+                    let results = snapshot
+                        .query(query::Query {
+                            stamp: worker_request.stamp,
+                            path: &worker_request.path,
+                            byte_offset: worker_request.offset,
+                            action: worker_request.action,
+                        })
+                        .map_err(|error| match error {
+                            query::QueryError::ResultEnvelopeLimit => "These result details exceed the display limit. Try literal Find for this alias.".to_owned(),
+                            _ => "Navigation could not verify this location. Place the cursor on an alias and try again.".to_owned(),
+                        })?;
+                    Ok((snapshot, Arc::new(results)))
+                })
+                .await
+                .unwrap_or_else(|error| Err(format!("Navigation task failed: {error}")));
+                nav::Completion { request, result }
+            },
+            Message::SourceSymbolsReady,
+        )
+    }
+
+    pub(super) fn source_symbols_ready(&mut self, completion: nav::Completion) -> Task<Message> {
+        let request = completion.request;
+        if self.source_symbols.in_flight != Some(request.job) {
+            return Task::none();
+        }
+        self.source_symbols.in_flight = None;
+        let diagram_query = self.source_diagram_job == Some(request.job);
+        if diagram_query {
+            self.source_diagram_job = None;
+        }
+        let wanted = self
+            .source_symbols
+            .request
+            .take()
+            .is_some_and(|current| current.job == request.job)
+            && request.interaction == self.source_symbols.interaction
+            && request.stamp.snapshot == self.source_key()
+            && nav::interaction::is_current(
+                &self.source_symbols.raw_interaction,
+                request.raw_interaction,
+            )
+            && request.path == self.source_workspace.active
+            && request.cursor == self.source_editor.cursor()
+            && self.source_navigation_available();
+        if !wanted {
+            return Task::none();
+        }
+        match completion.result {
+            Ok((snapshot, results)) if self.source_snapshot_matches(&snapshot) => {
+                self.source_symbols.cache = Some(snapshot);
+                self.source_symbols.results = Some(results.clone());
+                if diagram_query {
+                    if results.disposition == query::Disposition::Direct
+                        && results.scope.validated
+                        && results.omitted_definitions == 0
+                        && let [row] = results.definitions.as_slice()
+                        && let query::Identity::Unique(identity) = row.declaration.identity
+                        && row.membership == query::Membership::Included
+                        && row.evidence == query::Evidence::Validated
+                        && self.project().contains(identity.id())
+                        && crate::diagram_usage::alias(self.project(), identity.id())
+                            == row.declaration.alias
+                    {
+                        self.source_symbols.open = false;
+                        return self.diagram_usage_event(crate::diagram_usage::Event::Open(
+                            crate::diagram_usage::Context {
+                                document: self.canvas_document,
+                                revision: self.document.revision(),
+                                subject: identity.id(),
+                            },
+                        ));
+                    }
+                    self.source_symbols.notice = Some("Place the caret on a uniquely resolved alias in applied source to find diagram representations.".into());
+                    return Task::none();
+                }
+                if results.disposition == query::Disposition::Direct
+                    && let Some(row) = results.definitions.first()
+                {
+                    self.source_symbol_jump(&row.path, row.position, row.end_position);
+                }
+            }
+            Ok(_) => {
+                self.source_symbols.notice = Some("Source changed. Run navigation again.".into())
+            }
+            Err(error) => self.source_symbols.notice = Some(error),
+        }
+        Task::none()
+    }
+
+    fn source_symbol_jump(&mut self, path: &str, start: query::Position, end: query::Position) {
+        let cursor = text_editor::Cursor {
+            position: text_editor::Position {
+                line: start.line,
+                column: start.byte_column,
+            },
+            selection: Some(text_editor::Position {
+                line: end.line,
+                column: end.byte_column,
+            }),
+        };
+        if self
+            .source_workspace
+            .files
+            .get(path)
+            .is_none_or(|buffer| !nav::exact_cursor(&buffer.text, cursor))
+        {
+            self.source_symbols.notice =
+                Some("That source location is no longer available. Run navigation again.".into());
+            return;
+        }
+        if let Some(buffer) = self
+            .source_workspace
+            .files
+            .get(&self.source_workspace.active)
+        {
+            let origin = nav::HistoryEntry {
+                session: self.source_workspace.session(),
+                path: self.source_workspace.active.clone(),
+                generation: buffer.generation(),
+                cursor: self.source_editor.cursor(),
+            };
+            self.source_symbols
+                .back
+                .retain(|entry| entry.session == origin.session);
+            if self.source_symbols.back.len() == 64 {
+                self.source_symbols.back.remove(0);
+            }
+            self.source_symbols.back.push(origin);
+        }
+        self.source_workspace
+            .switch(path, self.source_editor.cursor());
+        self.show_source_file(false);
+        self.queue_source_reveal(cursor, false);
+    }
+
+    fn source_symbol_back(&mut self) {
+        while let Some(origin) = self.source_symbols.back.pop() {
+            if origin.session != self.source_workspace.session() {
+                continue;
+            }
+            let Some(buffer) = self.source_workspace.files.get(&origin.path) else {
+                self.source_symbols.notice = Some("The previous file is no longer loaded.".into());
+                return;
+            };
+            let unchanged = origin.generation == buffer.generation();
+            let cursor = if unchanged {
+                origin.cursor
+            } else if origin.path == self.source_workspace.active {
+                self.source_editor.cursor()
+            } else {
+                buffer.cursor
+            };
+            if !nav::exact_cursor(&buffer.text, cursor) {
+                self.source_symbols.notice = Some(
+                    "The previous location changed. Open the file to choose a current position."
+                        .into(),
+                );
+                return;
+            }
+            self.source_workspace
+                .switch(&origin.path, self.source_editor.cursor());
+            self.show_source_file(false);
+            self.queue_source_reveal(cursor, false);
+            self.source_symbols.notice =
+                (!unchanged).then(|| "This draft changed; its current cursor was restored.".into());
+            return;
+        }
+        self.source_symbols.notice = Some("No previous source location in this workspace.".into());
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior.rs

@@ -14,9 +14,11 @@ use iced::{
 };
 use oa_core::*;
 use std::collections::BTreeMap;
+pub(crate) mod canvas_workspace;
 #[cfg(test)]
 mod contextual_source_tests;
 pub(crate) mod creation;
+mod form_session;
 pub(crate) mod scenario;
 mod scenario_lifecycle;
 pub(crate) mod source_draft;
@@ -37,6 +39,7 @@ mod scenario_scroll {
     pub(super) fn observe<'a, R: renderer::Renderer + 'a>(
         context: scenario::Context,
         area: scenario::ScrollArea,
+        process: bool,
         restore: Option<scenario::ScrollRestore>,
         content: impl Into<Element<'a, Message, Theme, R>>,
     ) -> Element<'a, Message, Theme, R> {
@@ -44,28 +47,10 @@ mod scenario_scroll {
             content: content.into(),
             context,
             area,
-            process: false,
+            process,
             restore,
         })
     }
-    pub(super) fn observe_topology<'a>(
-        context: topology::Context,
-        area: scenario::ScrollArea,
-        content: impl Into<Element<'a, Message>>,
-    ) -> Element<'a, Message> {
-        Element::new(Observer {
-            content: content.into(),
-            context: scenario::Context {
-                document: context.document,
-                scenario: context.owner,
-                revision: context.revision,
-                epoch: context.epoch,
-            },
-            area,
-            process: true,
-            restore: None,
-        })
-    }
     struct Observer<'a, R = Renderer> {
         content: Element<'a, Message, Theme, R>,
         context: scenario::Context,
@@ -336,7 +321,7 @@ mod scenario_scroll {
         fn observer(height: f32, context: scenario::Context) -> Observer<'static, ()> {
             Observer {
                 context,
-                area: scenario::ScrollArea::Canvas,
+                area: scenario::ScrollArea::Page,
                 process: false,
                 restore: None,
                 content: scrollable(iced::widget::Space::new().width(200.).height(height))
@@ -406,97 +391,96 @@ mod scenario_scroll {
                     std::time::Instant::now(),
                 ))
             };
-            for area in [ScrollArea::Canvas, ScrollArea::Page] {
-                for returned_height in [600., 250.] {
-                    let (project, [a, _, _], [use_id, _, _]) = navigation_fixture();
-                    let mut app = App::with_project(project.clone());
-                    let _ = app.update(Message::Select(a));
-                    let _ = app.update(Message::Page(crate::app::Page::Behavior));
-                    let source = app.document.bundle().clone();
-                    let mut view = observer(600., app.scenario_context().unwrap());
-                    view.area = area;
-                    let mut tree = widget::Tree::new(&view as &dyn Widget<Message, Theme, ()>);
-                    for message in update(&mut view, &mut tree, redraw()).0 {
-                        let _ = app.update(message);
-                    }
-                    for message in update(
-                        &mut view,
-                        &mut tree,
-                        iced::Event::Mouse(mouse::Event::WheelScrolled {
-                            delta: mouse::ScrollDelta::Pixels { x: 0., y: -180. },
-                        }),
-                    )
-                    .0
-                    {
-                        let _ = app.update(message);
-                    }
-                    assert_eq!(actual_offset(&mut view, &mut tree), Vector::new(0., 180.));
-                    navigation_event(&mut app, |ctx| CanvasEvent::OpenUse(ctx, use_id));
-                    view = observer(600., app.scenario_context().unwrap());
-                    view.area = area;
-                    view.diff(&mut tree);
-                    for message in update(&mut view, &mut tree, redraw()).0 {
-                        let _ = app.update(message);
-                    }
-                    assert_eq!(actual_offset(&mut view, &mut tree), Vector::ZERO);
-                    navigation_event(&mut app, CanvasEvent::Back);
-                    assert_eq!(app.selected, use_id);
-                    let context = app.scenario_context().unwrap();
-                    let request = app.behavior.scenario.scroll_restore(context, area).unwrap();
-                    view = observer(returned_height, context);
-                    view.area = area;
-                    view.restore = Some(request);
-                    view.diff(&mut tree);
-                    let expected = Vector::new(0., (returned_height - 200.).min(180.));
-                    let messages = update(&mut view, &mut tree, redraw()).0;
-                    assert!(
-                        matches!(messages.as_slice(), [Message::ScenarioCanvas(CanvasEvent::Restored(_, _, _, actual))] if *actual == expected)
-                    );
-                    assert_eq!(actual_offset(&mut view, &mut tree), expected);
-                    for message in messages {
-                        let _ = app.update(message);
-                    }
-                    assert!(
-                        app.behavior
-                            .scenario
-                            .scroll_restore(app.scenario_context().unwrap(), area)
-                            .is_none()
-                    );
-                    // A delayed receipt leaves the same request in the view; later input must not snap back.
-                    for message in update(
-                        &mut view,
-                        &mut tree,
-                        iced::Event::Mouse(mouse::Event::WheelScrolled {
-                            delta: mouse::ScrollDelta::Pixels { x: 0., y: 20. },
-                        }),
-                    )
-                    .0
-                    {
-                        let _ = app.update(message);
-                    }
-                    let moved = expected - Vector::new(0., 20.);
-                    assert_eq!(actual_offset(&mut view, &mut tree), moved);
-                    view.context = app.scenario_context().unwrap();
-                    view.diff(&mut tree);
-                    assert!(update(&mut view, &mut tree, redraw()).0.is_empty());
-                    assert_eq!(actual_offset(&mut view, &mut tree), moved);
-                    navigation_event(&mut app, |ctx| {
-                        CanvasEvent::Restored(ctx, request.token, area, Vector::new(0., 999.))
-                    });
-                    let late_context = app.scenario_context().unwrap();
-                    let _ = app.update(Message::Page(crate::app::Page::Diagram));
-                    let epoch = app.canvas_epoch;
-                    let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Restored(
-                        late_context,
-                        request.token,
-                        area,
-                        Vector::ZERO,
-                    )));
-                    assert_eq!(app.canvas_epoch, epoch);
-                    assert_eq!(app.project(), &project);
-                    assert_eq!(app.document.bundle(), &source);
-                    assert!(!app.document.can_undo());
+            let area = ScrollArea::Page;
+            for returned_height in [600., 250.] {
+                let (project, [a, _, _], [use_id, _, _]) = navigation_fixture();
+                let mut app = App::with_project(project.clone());
+                let _ = app.update(Message::Select(a));
+                let _ = app.update(Message::Page(crate::app::Page::Behavior));
+                let source = app.document.bundle().clone();
+                let mut view = observer(600., app.scenario_context().unwrap());
+                view.area = area;
+                let mut tree = widget::Tree::new(&view as &dyn Widget<Message, Theme, ()>);
+                for message in update(&mut view, &mut tree, redraw()).0 {
+                    let _ = app.update(message);
                 }
+                for message in update(
+                    &mut view,
+                    &mut tree,
+                    iced::Event::Mouse(mouse::Event::WheelScrolled {
+                        delta: mouse::ScrollDelta::Pixels { x: 0., y: -180. },
+                    }),
+                )
+                .0
+                {
+                    let _ = app.update(message);
+                }
+                assert_eq!(actual_offset(&mut view, &mut tree), Vector::new(0., 180.));
+                navigation_event(&mut app, |ctx| CanvasEvent::OpenUse(ctx, use_id));
+                view = observer(600., app.scenario_context().unwrap());
+                view.area = area;
+                view.diff(&mut tree);
+                for message in update(&mut view, &mut tree, redraw()).0 {
+                    let _ = app.update(message);
+                }
+                assert_eq!(actual_offset(&mut view, &mut tree), Vector::ZERO);
+                navigation_event(&mut app, CanvasEvent::Back);
+                assert_eq!(app.selected, use_id);
+                let context = app.scenario_context().unwrap();
+                let request = app.behavior.scenario.scroll_restore(context, area).unwrap();
+                view = observer(returned_height, context);
+                view.area = area;
+                view.restore = Some(request);
+                view.diff(&mut tree);
+                let expected = Vector::new(0., (returned_height - 200.).min(180.));
+                let messages = update(&mut view, &mut tree, redraw()).0;
+                assert!(
+                    matches!(messages.as_slice(), [Message::ScenarioCanvas(CanvasEvent::Restored(_, _, _, actual))] if *actual == expected)
+                );
+                assert_eq!(actual_offset(&mut view, &mut tree), expected);
+                for message in messages {
+                    let _ = app.update(message);
+                }
+                assert!(
+                    app.behavior
+                        .scenario
+                        .scroll_restore(app.scenario_context().unwrap(), area)
+                        .is_none()
+                );
+                // A delayed receipt leaves the same request in the view; later input must not snap back.
+                for message in update(
+                    &mut view,
+                    &mut tree,
+                    iced::Event::Mouse(mouse::Event::WheelScrolled {
+                        delta: mouse::ScrollDelta::Pixels { x: 0., y: 20. },
+                    }),
+                )
+                .0
+                {
+                    let _ = app.update(message);
+                }
+                let moved = expected - Vector::new(0., 20.);
+                assert_eq!(actual_offset(&mut view, &mut tree), moved);
+                view.context = app.scenario_context().unwrap();
+                view.diff(&mut tree);
+                assert!(update(&mut view, &mut tree, redraw()).0.is_empty());
+                assert_eq!(actual_offset(&mut view, &mut tree), moved);
+                navigation_event(&mut app, |ctx| {
+                    CanvasEvent::Restored(ctx, request.token, area, Vector::new(0., 999.))
+                });
+                let late_context = app.scenario_context().unwrap();
+                let _ = app.update(Message::Page(crate::app::Page::Diagram));
+                let epoch = app.canvas_epoch;
+                let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Restored(
+                    late_context,
+                    request.token,
+                    area,
+                    Vector::ZERO,
+                )));
+                assert_eq!(app.canvas_epoch, epoch);
+                assert_eq!(app.project(), &project);
+                assert_eq!(app.document.bundle(), &source);
+                assert!(!app.document.can_undo());
             }
         }
         #[test]
@@ -578,9 +562,9 @@ mod scenario_scroll {
             other.scenario = Id::new_v4();
             let mut state = topology::State::default();
             state.enter(context.document, context.scenario);
-            state.scrolled(scenario::ScrollArea::Canvas, Vector::new(0., 180.));
+            state.scrolled(scenario::ScrollArea::Page, Vector::new(0., 180.));
             state.enter(other.document, other.scenario);
-            assert_eq!(state.scroll_offset(), Vector::ZERO);
+            assert_eq!(state.details_offset(), Vector::ZERO);
             view = observer(600., other);
             view.process = true;
             view.diff(&mut tree);
@@ -597,92 +581,91 @@ mod scenario_scroll {
          {
             use widget::operation::scrollable::{AbsoluteOffset, scroll_to};
             for process in [false, true] {
-                for area in [scenario::ScrollArea::Canvas, scenario::ScrollArea::Page] {
-                    for change in 0..4 {
-                        let context = scenario::direct_tests::context(Id::new_v4());
-                        let mut view = observer(600., context);
-                        view.process = process;
-                        view.area = area;
-                        let mut tree = widget::Tree::new(&view as &dyn Widget<Message, Theme, ()>);
-                        let node = view.layout(
-                            &mut tree,
-                            &(),
-                            &layout::Limits::new(Size::ZERO, Size::new(800., 700.)),
-                        );
-                        // Model a programmatic reveal before the observer has reported.
-                        // Mounted identity must not depend on its last scroll notification.
-                        let mut operation = scroll_to::<()>(
-                            widget::Id::new("observer-test"),
-                            AbsoluteOffset {
-                                x: None,
-                                y: Some(180.),
-                            },
-                        );
-                        view.operate(&mut tree, Layout::new(&node), &(), &mut operation);
-                        let mut next = context;
-                        match change {
-                            0 => next.scenario = Id::new_v4(),
-                            1 => next.document = Id::new_v4(),
-                            2 => {
-                                next.revision += 1;
-                                next.epoch += 5;
-                            }
-                            _ => {}
+                let area = scenario::ScrollArea::Page;
+                for change in 0..4 {
+                    let context = scenario::direct_tests::context(Id::new_v4());
+                    let mut view = observer(600., context);
+                    view.process = process;
+                    view.area = area;
+                    let mut tree = widget::Tree::new(&view as &dyn Widget<Message, Theme, ()>);
+                    let node = view.layout(
+                        &mut tree,
+                        &(),
+                        &layout::Limits::new(Size::ZERO, Size::new(800., 700.)),
+                    );
+                    // Model a programmatic reveal before the observer has reported.
+                    // Mounted identity must not depend on its last scroll notification.
+                    let mut operation = scroll_to::<()>(
+                        widget::Id::new("observer-test"),
+                        AbsoluteOffset {
+                            x: None,
+                            y: Some(180.),
+                        },
+                    );
+                    view.operate(&mut tree, Layout::new(&node), &(), &mut operation);
+                    let mut next = context;
+                    match change {
+                        0 => next.scenario = Id::new_v4(),
+                        1 => next.document = Id::new_v4(),
+                        2 => {
+                            next.revision += 1;
+                            next.epoch += 5;
                         }
-                        view = observer(if change == 3 { 800. } else { 600. }, next);
-                        view.process = process;
-                        view.area = area;
-                        view.diff(&mut tree);
-                        let redraw = || {
-                            iced::Event::Window(iced::window::Event::RedrawRequested(
-                                std::time::Instant::now(),
-                            ))
-                        };
-                        let (messages, _) = update(&mut view, &mut tree, redraw());
-                        let actual = messages
-                            .into_iter()
-                            .filter_map(|message| match message {
-                                Message::TopologyCanvas(topology::CanvasEvent::Scrolled(
-                                    c,
-                                    reported_area,
-                                    offset,
-                                )) => {
-                                    assert_eq!(
-                                        (c.document, c.owner, c.revision, c.epoch),
-                                        (next.document, next.scenario, next.revision, next.epoch)
-                                    );
-                                    assert_eq!(
-                                        std::mem::discriminant(&reported_area),
-                                        std::mem::discriminant(&area)
-                                    );
-                                    Some(offset)
-                                }
-                                Message::ScenarioCanvas(scenario::CanvasEvent::Scrolled(
-                                    c,
-                                    reported_area,
-                                    offset,
-                                )) => {
-                                    assert_eq!(c, next);
-                                    assert_eq!(
-                                        std::mem::discriminant(&reported_area),
-                                        std::mem::discriminant(&area)
-                                    );
-                                    Some(offset)
-                                }
-                                _ => None,
-                            })
-                            .collect::<Vec<_>>();
-                        assert_eq!(
-                            actual,
-                            vec![if change < 2 {
-                                Vector::ZERO
-                            } else {
-                                Vector::new(0., 180.)
-                            }],
-                            "process={process} area={area:?} change={change}"
-                        );
-                        assert!(update(&mut view, &mut tree, redraw()).0.is_empty());
+                        _ => {}
                     }
+                    view = observer(if change == 3 { 800. } else { 600. }, next);
+                    view.process = process;
+                    view.area = area;
+                    view.diff(&mut tree);
+                    let redraw = || {
+                        iced::Event::Window(iced::window::Event::RedrawRequested(
+                            std::time::Instant::now(),
+                        ))
+                    };
+                    let (messages, _) = update(&mut view, &mut tree, redraw());
+                    let actual = messages
+                        .into_iter()
+                        .filter_map(|message| match message {
+                            Message::TopologyCanvas(topology::CanvasEvent::Scrolled(
+                                c,
+                                reported_area,
+                                offset,
+                            )) => {
+                                assert_eq!(
+                                    (c.document, c.owner, c.revision, c.epoch),
+                                    (next.document, next.scenario, next.revision, next.epoch)
+                                );
+                                assert_eq!(
+                                    std::mem::discriminant(&reported_area),
+                                    std::mem::discriminant(&area)
+                                );
+                                Some(offset)
+                            }
+                            Message::ScenarioCanvas(scenario::CanvasEvent::Scrolled(
+                                c,
+                                reported_area,
+                                offset,
+                            )) => {
+                                assert_eq!(c, next);
+                                assert_eq!(
+                                    std::mem::discriminant(&reported_area),
+                                    std::mem::discriminant(&area)
+                                );
+                                Some(offset)
+                            }
+                            _ => None,
+                        })
+                        .collect::<Vec<_>>();
+                    assert_eq!(
+                        actual,
+                        vec![if change < 2 {
+                            Vector::ZERO
+                        } else {
+                            Vector::new(0., 180.)
+                        }],
+                        "process={process} area={area:?} change={change}"
+                    );
+                    assert!(update(&mut view, &mut tree, redraw()).0.is_empty());
                 }
             }
         }
@@ -1134,6 +1117,10 @@ fn in_machine(p: &Project, id: Id, machine: Id) -> bool {
     false
 }
 
+#[cfg(test)]
+#[path = "../../../harness/experiments/behavior-layout-scene-20260912/mod.rs"]
+mod behavior_layout_scene_experiment;
+
 struct BoxItem {
     id: Id,
     rect: Rectangle,
@@ -1141,12 +1128,26 @@ struct BoxItem {
     detail: String,
     marker: Option<Kind>,
 }
-fn box_text_clip(rect: Rectangle, scale: f32, viewport: Size) -> Option<Rectangle> {
-    if !scale.is_finite() || scale <= 0. || rect.width <= 20. || rect.height <= 16. {
+fn box_text_clip(
+    pan: iced::Vector,
+    rect: Rectangle,
+    scale: f32,
+    viewport: Size,
+) -> Option<Rectangle> {
+    if !pan.x.is_finite()
+        || !pan.y.is_finite()
+        || !scale.is_finite()
+        || scale <= 0.
+        || rect.width <= 20.
+        || rect.height <= 16.
+    {
         return None;
     }
     Rectangle::new(
-        Point::new((rect.x + 10.) * scale, (rect.y + 8.) * scale),
+        Point::new(
+            pan.x + (rect.x + 10.) * scale,
+            pan.y + (rect.y + 8.) * scale,
+        ),
         Size::new((rect.width - 20.) * scale, (rect.height - 16.) * scale),
     )
     .intersection(&Rectangle::new(Point::ORIGIN, viewport))
@@ -1159,13 +1160,24 @@ struct Line {
     label_at: Point,
     dashed: bool,
 }
+impl Line {
+    fn label_bounds(&self) -> Rectangle {
+        Rectangle::new(
+            self.label_at,
+            Size::new(
+                (self.label.chars().count() as f32 * 6.8 + 8.).min(225.),
+                25.,
+            ),
+        )
+    }
+}
 struct Scene {
     boxes: Vec<BoxItem>,
     lines: Vec<Line>,
     size: Size,
     selected: Id,
     scale: f32,
-    scroll_offset: iced::Vector,
+    camera_pan: iced::Vector,
     interaction: Option<(scenario::Context, scenario::CanvasTool, bool)>,
     pending_placement: Option<(scenario::Slot, Option<Id>)>,
     lanes: BTreeMap<Id, f32>,
@@ -1220,7 +1232,7 @@ impl Scene {
     fn sequence(p: &Project, owner: Id, selected: Id) -> Self {
         let mut scene = Self {
             scale: 1.,
-            scroll_offset: iced::Vector::ZERO,
+            camera_pan: iced::Vector::ZERO,
             boxes: vec![],
             lines: vec![],
             size: Size::new(700., 200.),
@@ -1427,6 +1439,8 @@ impl Scene {
                 // the preceding action/state/reference box, before recording rows.
                 *y += 16.;
             }
+            #[cfg(test)]
+            behavior_layout_scene_experiment::resolve_row_anchor(*id, y);
             if ordered {
                 let slot = scenario::Slot {
                     parent: owner,
@@ -1834,17 +1848,7 @@ impl Scene {
             .or_else(|| {
                 self.lines
                     .iter()
-                    .find(|line| {
-                        !line.label.is_empty()
-                            && Rectangle::new(
-                                line.label_at,
-                                Size::new(
-                                    (line.label.chars().count() as f32 * 6.8 + 8.).min(225.),
-                                    25.,
-                                ),
-                            )
-                            .contains(point)
-                    })
+                    .find(|line| !line.label.is_empty() && line.label_bounds().contains(point))
                     .map(|line| line.id)
             })
             .or_else(|| self.near_sequence_item(point))
@@ -1931,8 +1935,7 @@ impl canvas::Program<Message> for Scene {
         if !editable {
             state.cancel();
         }
-        // Scrollable marks a pointer outside its visible viewport unavailable,
-        // even when it lies inside the full (scrolled) canvas rectangle.
+        // The viewport masks input outside its visible canvas bounds.
         let visible = cursor.position().is_some();
         if !visible
             && matches!(
@@ -1955,7 +1958,7 @@ impl canvas::Program<Message> for Scene {
                         SequencePress::Occurrence { .. } => {}
                     }
                 }
-                mouse::Cursor::Available(*position + self.scroll_offset)
+                mouse::Cursor::Available(*position)
             }
             canvas::Event::Mouse(mouse::Event::WheelScrolled { .. })
             | canvas::Event::Window(iced::window::Event::Resized(_))
@@ -1967,11 +1970,9 @@ impl canvas::Program<Message> for Scene {
             }
             canvas::Event::Mouse(
                 mouse::Event::ButtonPressed(_) | mouse::Event::ButtonReleased(_),
-            ) => state
-                .pointer
-                .map_or(cursor, |p| mouse::Cursor::Available(p + self.scroll_offset)),
+            ) => state.pointer.map_or(cursor, mouse::Cursor::Available),
             canvas::Event::Window(iced::window::Event::RedrawRequested(_)) => {
-                state.pointer = cursor.position().map(|p| p - self.scroll_offset);
+                state.pointer = cursor.position();
                 cursor
             }
             canvas::Event::Keyboard(iced::keyboard::Event::KeyPressed {
@@ -1983,9 +1984,12 @@ impl canvas::Program<Message> for Scene {
             }
             _ => cursor,
         };
-        let world = cursor
-            .position_in(bounds)
-            .map(|p| Point::new(p.x / self.scale, p.y / self.scale));
+        let world = cursor.position_in(bounds).map(|p| {
+            Point::new(
+                (p.x - self.camera_pan.x) / self.scale,
+                (p.y - self.camera_pan.y) / self.scale,
+            )
+        });
         match event {
             canvas::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)) => {
                 if !visible {
@@ -2005,14 +2009,14 @@ impl canvas::Program<Message> for Scene {
                         state.press = Some(SequencePress::Message {
                             source,
                             slot,
-                            start: cursor.position()? - self.scroll_offset,
+                            start: cursor.position()?,
                             first,
                             moved: false,
                         });
                         return Some(Action::request_redraw().and_capture());
                     }
                     if let CanvasTool::Add(tool) = tool {
-                        if !tool.canvas_occurrence() {
+                        if !tool.canvas_occurrence() && tool != scenario::Tool::Lifeline {
                             return None;
                         }
                         state.press = Some(SequencePress::Occurrence {
@@ -2022,11 +2026,19 @@ impl canvas::Program<Message> for Scene {
                         });
                         return Some(Action::request_redraw().and_capture());
                     }
-                    if self.reorder_handle().is_some_and(|r| r.contains(point)) {
+                    if let Some(occurrence) = self
+                        .hit(point)
+                        .filter(|id| self.rows.contains_key(id))
+                        .or_else(|| {
+                            self.reorder_handle()
+                                .filter(|r| r.contains(point))
+                                .map(|_| self.selected)
+                        })
+                    {
                         state.press = Some(SequencePress::Reorder {
-                            occurrence: self.selected,
-                            parent: self.rows[&self.selected].0,
-                            start: cursor.position()? - self.scroll_offset,
+                            occurrence,
+                            parent: self.rows[&occurrence].0,
+                            start: cursor.position()?,
                             moved: false,
                         });
                         return Some(Action::request_redraw().and_capture());
@@ -2100,6 +2112,18 @@ impl canvas::Program<Message> for Scene {
                             );
                         }
                     }
+                    SequencePress::Reorder {
+                        occurrence,
+                        moved: false,
+                        ..
+                    } => {
+                        return Some(
+                            Action::publish(Message::ScenarioCanvas(CanvasEvent::Select(
+                                context, occurrence,
+                            )))
+                            .and_capture(),
+                        );
+                    }
                     SequencePress::Reorder {
                         occurrence,
                         parent,
@@ -2137,6 +2161,7 @@ impl canvas::Program<Message> for Scene {
     ) -> Vec<canvas::Geometry> {
         let mut f = Frame::new(renderer, bounds.size());
         f.fill_rectangle(Point::ORIGIN, bounds.size(), Color::WHITE);
+        f.translate(self.camera_pan);
         f.scale(self.scale);
         self.lifecycle.draw_lanes(&mut f, self.selected);
         for b in &self.boxes {
@@ -2217,10 +2242,11 @@ impl canvas::Program<Message> for Scene {
             }
         }
         for b in &self.boxes {
-            if let Some(clip) = box_text_clip(b.rect, self.scale, f.size()) {
+            if let Some(clip) = box_text_clip(self.camera_pan, b.rect, self.scale, f.size()) {
                 // Clipped child frames start with an identity transform. Match
-                // the card's scale explicitly, as for lifecycle Create labels.
+                // the card's pan and scale, as for lifecycle Create labels.
                 f.with_clip(clip, |label| {
+                    label.translate(self.camera_pan);
                     label.scale(self.scale);
                     label.fill_text(Text {
                         content: short(&b.title, ((b.rect.width - 25.) / 7.) as usize),
@@ -2255,12 +2281,15 @@ impl canvas::Program<Message> for Scene {
             });
         }
         self.lifecycle
-            .draw_markers(&mut f, self.selected, self.scale);
+            .draw_markers(&mut f, self.selected, self.scale, self.camera_pan);
         if let Some((context, tool, editable)) = self.interaction {
             let active = editable && state.context == Some(context) && state.tool == tool;
-            let point = cursor
-                .position_in(bounds)
-                .map(|p| Point::new(p.x / self.scale, p.y / self.scale));
+            let point = cursor.position_in(bounds).map(|p| {
+                Point::new(
+                    (p.x - self.camera_pan.x) / self.scale,
+                    (p.y - self.camera_pan.y) / self.scale,
+                )
+            });
             let source = active.then_some(state.source).flatten();
             let reorder = active.then_some(state.press).flatten().and_then(|press| {
                 if let SequencePress::Reorder { parent, .. } = press {
@@ -2305,6 +2334,18 @@ impl canvas::Program<Message> for Scene {
             } else {
                 None
             };
+            if reorder.is_some()
+                && slot.is_none()
+                && let Some(point) = point
+            {
+                f.fill_text(Text {
+                    content: "Other operand: move stays in the current sequence".into(),
+                    position: Point::new(point.x + 8., point.y + 12.),
+                    size: (11. / self.scale).into(),
+                    color: Color::from_rgb(0.75, 0.2, 0.15),
+                    ..Default::default()
+                });
+            }
             if let Some(slot) = slot {
                 f.stroke(
                     &Path::line(
@@ -2510,25 +2551,26 @@ mod direct_canvas_tests {
         }
     }
     #[test]
-    fn direct_scrolled_canvas_maps_raw_pointer_events_to_the_visible_slot() {
+    fn direct_panned_canvas_maps_ordered_pointer_events_to_the_visible_slot() {
         let (f, mut scene) = scene();
-        scene.scroll_offset = iced::Vector::new(35., 140.);
+        scene.camera_pan = iced::Vector::new(-35., -140.);
         let bounds = Rectangle::new(Point::new(20., 230.), scene.size);
         let slot = scene.slots.last().unwrap().slot;
         let y = scene.slots.last().unwrap().y;
-        let a = Point::new(bounds.x + scene.lanes[&f.sender], bounds.y + y) - scene.scroll_offset;
-        let b = Point::new(bounds.x + scene.lanes[&f.receiver], bounds.y + y) - scene.scroll_offset;
+        let a = Point::new(bounds.x + scene.lanes[&f.sender], bounds.y + y) + scene.camera_pan;
+        let b = Point::new(bounds.x + scene.lanes[&f.receiver], bounds.y + y) + scene.camera_pan;
+        assert!(bounds.contains(a) && bounds.contains(b));
         let mut state = SequenceInput::default();
-        // Iced Scrollable passes raw event coordinates and a translated cursor.
+        // Batched pointer events use their own positions with the final cursor.
         for event in [
             mouse::Event::CursorMoved { position: a },
             mouse::Event::ButtonPressed(mouse::Button::Left),
             mouse::Event::CursorMoved { position: b },
         ] {
-            send(&scene, &mut state, event, b + scene.scroll_offset, bounds);
+            send(&scene, &mut state, event, b, bounds);
         }
         assert!(
-            matches!(send(&scene, &mut state, mouse::Event::ButtonReleased(mouse::Button::Left), b + scene.scroll_offset, bounds), Some(CanvasEvent::Begin { sender, receiver, slot: actual, .. }) if sender == f.sender && receiver == f.receiver && actual == slot)
+            matches!(send(&scene, &mut state, mouse::Event::ButtonReleased(mouse::Button::Left), b, bounds), Some(CanvasEvent::Begin { sender, receiver, slot: actual, .. }) if sender == f.sender && receiver == f.receiver && actual == slot)
         );
     }
     #[test]

crates/oa-desktop/src/behavior/canvas_workspace.rs

@@ -0,0 +1,244 @@
+//! Shared presentation and input contract; contains no model commands.
+use crate::app::{App, Message};
+use iced::widget::{button, column, container, opaque, row, scrollable, stack, text, tooltip};
+use iced::{Element, Length::Fill, Point, Theme, Vector};
+use oa_core::Id;
+mod control;
+mod focus;
+mod viewport;
+pub use control::Control;
+pub use viewport::Viewport;
+
+pub fn keyboard_enabled(app: &crate::app::App) -> bool {
+    !app.busy
+        && !app.hosted.visible
+        && app.workflow.is_none()
+        && app.file_prompt.is_none()
+        && !app.delete_pending
+        && app.pending.is_none()
+        && app.model_menu.is_none()
+        && app.diagram_usages.is_none()
+        && !app.reference_input_active()
+}
+
+pub fn controls<'a>(
+    scope: Scope,
+    keyboard: bool,
+    scale: f32,
+    details: Message,
+    focus: Option<Message>,
+    zoom: impl Fn(Option<f32>) -> Message,
+    publish: impl Fn(Event) -> Message + Copy + 'a,
+) -> Element<'a, Message> {
+    let control = |name: &'static str, label: &'static str, message: Option<Message>| {
+        let message = message.map(|message| intent(scope, name, message));
+        Control::new(
+            button(text(label).size(12))
+                .padding(6)
+                .on_press_maybe(message.clone()),
+            scope,
+            name,
+            keyboard,
+            message,
+            publish,
+        )
+    };
+    row![
+        control("Details", "Details", Some(details)),
+        tooltip(control("Canvas", "Canvas", focus),
+            container(text("F6: enter/leave canvas controls · Tab: next · Enter/Space: activate · Esc: leave").size(12)).padding(7).style(crate::style::card),
+            tooltip::Position::Bottom),
+        control("Fit", "Fit", Some(zoom(None))),
+        control("ZoomOut", "−", Some(zoom(Some(scale / 1.25)))),
+        text(format!("{:.0}%", scale * 100.)).size(12),
+        control("ZoomIn", "+", Some(zoom(Some(scale * 1.25)))),
+        control("ActualSize", "100%", Some(zoom(Some(1.)))),
+    ].spacing(4).align_y(iced::Center).into()
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Scope {
+    pub document: Id,
+    pub owner: Id,
+    pub revision: u64,
+    pub epoch: u64,
+}
+impl Scope {
+    pub(crate) fn current(app: &App) -> Option<Self> {
+        if let Some(context) = app.scenario_context() {
+            Some(Self {
+                document: context.document,
+                owner: context.scenario,
+                revision: context.revision,
+                epoch: app.camera_epoch,
+            })
+        } else {
+            let context = app.topology_context()?;
+            Some(Self {
+                document: context.document,
+                owner: context.owner,
+                revision: context.revision,
+                epoch: app.camera_epoch,
+            })
+        }
+    }
+    pub(crate) fn input_owner(app: &App) -> Option<Self> {
+        if keyboard_enabled(app)
+            && !app.behavior.has_pending()
+            && !app.draft_dirty()
+            && !app.source_dirty()
+        {
+            Self::current(app)
+        } else {
+            None
+        }
+    }
+
+    pub fn control_id(self, name: &str) -> iced::advanced::widget::Id {
+        iced::advanced::widget::Id::from(format!(
+            "behavior-control:{}:{}:{}:{name}",
+            self.document, self.owner, self.revision
+        ))
+    }
+}
+/// Only a live presentation intent may carry a toolbar action across its own pan.
+#[derive(Debug, Clone)]
+pub struct Intent {
+    pub scope: Scope,
+    pub name: &'static str,
+    pub message: Box<Message>,
+}
+pub fn intent(scope: Scope, name: &'static str, message: Message) -> Message {
+    Message::BehaviorControl(Intent {
+        scope,
+        name,
+        message: Box::new(message),
+    })
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum Event {
+    CancelGesture,
+    Pan(Vector),
+    Zoom { factor: f32, at: Point, base: f32 },
+    Focus,
+    Traverse(bool),
+    ControlFocus(&'static str),
+    ToggleFocus,
+    Leave,
+}
+
+pub use focus::{focus_task, root as focus_root};
+/// Fold relative input in event order. The base scale is used only on leaving Fit.
+pub fn change(pan: &mut Vector, zoom: &mut Option<f32>, fit: &mut bool, event: Event) -> bool {
+    match event {
+        Event::Pan(delta) if delta.x.is_finite() && delta.y.is_finite() => {
+            let next = *pan + delta;
+            if next.x.is_finite() && next.y.is_finite() && next != *pan {
+                *pan = next;
+                true
+            } else {
+                false
+            }
+        }
+        Event::Zoom { factor, at, base }
+            if factor.is_finite()
+                && factor > 0.
+                && base.is_finite()
+                && base > 0.
+                && at.x.is_finite()
+                && at.y.is_finite() =>
+        {
+            let old = if *fit { base } else { zoom.unwrap_or(base) };
+            let next = (old * factor).clamp(0.05, 3.);
+            if old == next {
+                return false;
+            }
+            let anchor = Vector::new(at.x, at.y);
+            let next_pan = anchor - (anchor - *pan) * (next / old);
+            if !next_pan.x.is_finite() || !next_pan.y.is_finite() {
+                return false;
+            }
+            *pan = next_pan;
+            *zoom = Some(next);
+            *fit = false;
+            true
+        }
+        _ => false,
+    }
+}
+
+/// Constant-width labelled palette. Arming a tool never reallocates the canvas.
+pub fn palette<'a>(
+    scope: Scope,
+    keyboard: bool,
+    publish: impl Fn(Event) -> Message + Copy + 'a,
+    entries: impl IntoIterator<Item = (&'static str, &'static str, bool, Option<Message>)>,
+) -> Element<'a, Message> {
+    let mut tools = column![].spacing(3);
+    for (glyph, label, selected, message) in entries {
+        let message = message.map(|message| intent(scope, glyph, message));
+        tools = tools.push(tooltip(
+            container(Control::new(
+                button(text(glyph).size(12))
+                    .width(34)
+                    .height(30)
+                    .padding(3)
+                    .style(if selected {
+                        button::primary
+                    } else {
+                        crate::style::nav
+                    })
+                    .on_press_maybe(message.clone()),
+                scope,
+                glyph,
+                keyboard,
+                message,
+                publish,
+            ))
+            .id(format!("behavior-tool:{glyph}")),
+            container(text(label).size(12))
+                .padding(7)
+                .style(crate::style::card),
+            tooltip::Position::Left,
+        ));
+    }
+    container(scrollable(tools).id(scope.control_id("palette-scroll")))
+        .width(40)
+        .height(Fill)
+        .padding(3)
+        .style(crate::style::panel)
+        .into()
+}
+
+/// Header and palette are permanent. Details/editors overlay the same viewport.
+pub fn host<'a, Message: 'a, R: iced::advanced::text::Renderer + 'a>(
+    header: Element<'a, Message, Theme, R>,
+    palette: Element<'a, Message, Theme, R>,
+    canvas: Element<'a, Message, Theme, R>,
+    editor: Option<Element<'a, Message, Theme, R>>,
+) -> Element<'a, Message, Theme, R> {
+    let mut body = stack![canvas];
+    if let Some(editor) = editor {
+        body = body.push(
+            container(opaque(
+                container(editor)
+                    .width(300)
+                    .height(Fill)
+                    .style(crate::style::card),
+            ))
+            .align_right(Fill)
+            .height(Fill)
+            .padding(8),
+        );
+    }
+    column![header, row![body, palette].height(Fill)]
+        .spacing(6)
+        .padding(8)
+        .width(Fill)
+        .height(Fill)
+        .into()
+}
+
+#[cfg(test)]
+pub(crate) mod tests;

crates/oa-desktop/src/behavior/canvas_workspace/control.rs

@@ -0,0 +1,256 @@
+//! A real focusable keyboard target around the existing styled pointer button.
+use super::{Event as CameraEvent, Scope, focus::Member};
+use iced::advanced::{
+    Clipboard, Layout, Shell, Widget, layout, overlay, renderer,
+    widget::{Operation, Tree, operation, tree},
+};
+use iced::{Border, Element, Event, Length, Rectangle, Size, Theme, Vector, keyboard, mouse};
+
+#[derive(Default)]
+struct Input {
+    identity: Option<iced::advanced::widget::Id>,
+    focused: bool,
+}
+impl operation::Focusable for Input {
+    fn is_focused(&self) -> bool {
+        self.focused
+    }
+    fn focus(&mut self) {
+        self.focused = true;
+    }
+    fn unfocus(&mut self) {
+        self.focused = false;
+    }
+}
+pub struct Control<'a, Message, R = iced::Renderer>
+where
+    R: renderer::Renderer,
+{
+    content: Element<'a, Message, Theme, R>,
+    scope: Scope,
+    name: &'static str,
+    enabled: bool,
+    activate: Option<Message>,
+    publish: Box<dyn Fn(CameraEvent) -> Message + 'a>,
+}
+impl<'a, Message, R: renderer::Renderer> Control<'a, Message, R> {
+    pub fn new(
+        content: impl Into<Element<'a, Message, Theme, R>>,
+        scope: Scope,
+        name: &'static str,
+        enabled: bool,
+        activate: Option<Message>,
+        publish: impl Fn(CameraEvent) -> Message + 'a,
+    ) -> Self {
+        Self {
+            content: content.into(),
+            scope,
+            name,
+            enabled: enabled && activate.is_some(),
+            activate,
+            publish: Box::new(publish),
+        }
+    }
+}
+impl<Message: Clone, R: renderer::Renderer> Widget<Message, Theme, R> for Control<'_, Message, R> {
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<Input>()
+    }
+    fn state(&self) -> tree::State {
+        tree::State::new(Input {
+            identity: Some(self.scope.control_id(self.name)),
+            focused: false,
+        })
+    }
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+    fn diff(&self, tree: &mut Tree) {
+        let state = tree.state.downcast_mut::<Input>();
+        let identity = self.scope.control_id(self.name);
+        if state.identity.as_ref() != Some(&identity) || !self.enabled {
+            *state = Input {
+                identity: Some(identity),
+                focused: false,
+            };
+        }
+        tree.diff_children(std::slice::from_ref(&self.content));
+    }
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        let id = self.scope.control_id(self.name);
+        operation.container(Some(&id), layout.bounds());
+        if self.enabled {
+            operation.custom(Some(&id), layout.bounds(), &mut Member(self.scope));
+            operation.focusable(
+                Some(&id),
+                layout.bounds(),
+                tree.state.downcast_mut::<Input>(),
+            );
+        }
+        operation.traverse(&mut |operation| {
+            self.content.as_widget_mut().operate(
+                &mut tree.children[0],
+                layout,
+                renderer,
+                operation,
+            );
+        });
+    }
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        if shell.is_event_captured() {
+            return;
+        }
+        let state = tree.state.downcast_mut::<Input>();
+        if self.enabled {
+            if let Event::Keyboard(keyboard::Event::KeyPressed {
+                key,
+                modifiers,
+                repeat,
+                ..
+            }) = event
+                && state.focused
+            {
+                use keyboard::{Key, key::Named};
+                let action = match key.as_ref() {
+                    Key::Named(Named::Tab) => {
+                        Some((self.publish)(CameraEvent::Traverse(modifiers.shift())))
+                    }
+                    Key::Named(Named::Escape) => Some((self.publish)(CameraEvent::Leave)),
+                    Key::Named(Named::F6) if modifiers.is_empty() && !repeat => {
+                        Some((self.publish)(CameraEvent::ToggleFocus))
+                    }
+                    Key::Named(Named::Enter | Named::Space) if modifiers.is_empty() && !repeat => {
+                        self.activate.clone()
+                    }
+                    _ => None,
+                };
+                if let Some(action) = action {
+                    shell.publish(action);
+                    shell.capture_event();
+                    shell.request_redraw();
+                    return;
+                }
+            }
+            if matches!(
+                event,
+                Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left))
+            ) && !layout
+                .bounds()
+                .intersection(viewport)
+                .is_some_and(|bounds| cursor.is_over(bounds))
+            {
+                state.focused = false;
+            }
+        }
+        if matches!(event, Event::Window(iced::window::Event::Unfocused)) {
+            state.focused = false;
+        }
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            style,
+            layout,
+            cursor,
+            viewport,
+        );
+        if self.enabled && tree.state.downcast_ref::<Input>().focused {
+            renderer.fill_quad(
+                renderer::Quad {
+                    bounds: layout.bounds(),
+                    border: Border {
+                        color: crate::style::INK,
+                        width: 2.,
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+                iced::Color::TRANSPARENT,
+            );
+        }
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        self.content.as_widget().mouse_interaction(
+            &tree.children[0],
+            layout,
+            cursor,
+            viewport,
+            renderer,
+        )
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        tree: &'a mut Tree,
+        layout: Layout<'a>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'a, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}
+impl<'a, Message: Clone + 'a, R: renderer::Renderer + 'a> From<Control<'a, Message, R>>
+    for Element<'a, Message, Theme, R>
+{
+    fn from(control: Control<'a, Message, R>) -> Self {
+        Element::new(control)
+    }
+}

crates/oa-desktop/src/behavior/canvas_workspace/focus.rs

@@ -0,0 +1,293 @@
+//! Explicit canvas entry; ordinary initial Tab continues to belong to Inspector.
+use super::{Event, Scope};
+use iced::advanced::widget::{Id, Operation, Tree, operation};
+use iced::advanced::{Clipboard, Layout, Shell, Widget, layout, overlay, renderer};
+use iced::{Element, Event as InputEvent, Length, Rectangle, Size, Theme, Vector, mouse};
+
+pub(super) struct Member(pub Scope);
+
+pub fn focus_task<Message: Send + 'static>(scope: Scope, event: Event) -> iced::Task<Message> {
+    iced::advanced::widget::operate(Collect {
+        scope,
+        valid: false,
+        event,
+        members: vec![],
+        focused: None,
+        palette: None,
+    })
+}
+struct Collect {
+    scope: Scope,
+    valid: bool,
+    event: Event,
+    members: Vec<(Id, Rectangle)>,
+    focused: Option<usize>,
+    palette: Option<(Rectangle, Rectangle)>,
+}
+impl<T: Send + 'static> Operation<T> for Collect {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation<T>)) {
+        visit(self);
+    }
+    fn custom(&mut self, id: Option<&Id>, bounds: Rectangle, value: &mut dyn std::any::Any) {
+        if let Some(owner) = value.downcast_ref::<Owner>() {
+            self.valid = owner.0 == Some(self.scope);
+        }
+        if self.valid
+            && value
+                .downcast_ref::<Member>()
+                .is_some_and(|m| m.0 == self.scope)
+            && let Some(id) = id
+        {
+            self.members.push((id.clone(), bounds));
+        }
+    }
+    fn focusable(&mut self, id: Option<&Id>, _: Rectangle, value: &mut dyn operation::Focusable) {
+        if value.is_focused() {
+            self.focused = self
+                .members
+                .iter()
+                .position(|(member, _)| Some(member) == id)
+                .or(self.focused);
+        }
+    }
+    fn scrollable(
+        &mut self,
+        id: Option<&Id>,
+        bounds: Rectangle,
+        content: Rectangle,
+        _: Vector,
+        _: &mut dyn operation::Scrollable,
+    ) {
+        if id == Some(&self.scope.control_id("palette-scroll")) {
+            self.palette = Some((bounds, content));
+        }
+    }
+    fn finish(&self) -> operation::Outcome<T> {
+        let canvas = self.scope.control_id("viewport");
+        // An enabled viewport witnesses the live lifetime. Hidden/dirty/modal
+        // owners expose no members; a delayed request cannot clear their focus.
+        if !self.valid || !self.members.iter().any(|(id, _)| *id == canvas) {
+            return operation::Outcome::None;
+        }
+        let target = match self.event {
+            Event::Focus => Some(canvas),
+            Event::ControlFocus(name) => Some(self.scope.control_id(name)),
+            Event::ToggleFocus if self.focused.is_none() => Some(canvas),
+            Event::ToggleFocus | Event::Leave if self.focused.is_some() => None,
+            Event::Traverse(back) => {
+                let Some(current) = self.focused else {
+                    return operation::Outcome::None;
+                };
+                let next = if back {
+                    (current + self.members.len() - 1) % self.members.len()
+                } else {
+                    (current + 1) % self.members.len()
+                };
+                Some(self.members[next].0.clone())
+            }
+            _ => return operation::Outcome::None,
+        };
+        if target
+            .as_ref()
+            .is_some_and(|target| !self.members.iter().any(|(id, _)| id == target))
+        {
+            return operation::Outcome::None;
+        }
+        let reveal = target.as_ref().and_then(|target| {
+            let (_, field) = self.members.iter().find(|(id, _)| id == target)?;
+            let (bounds, content) = self.palette?;
+            // Only the palette has member controls inside this scrollable.
+            (field.x >= bounds.x && field.x < bounds.x + bounds.width).then(|| {
+                (field.center_y() - bounds.y - bounds.height / 2.)
+                    .clamp(0., (content.height - bounds.height).max(0.))
+            })
+        });
+        operation::Outcome::Chain(Box::new(Apply {
+            scope: self.scope,
+            valid: false,
+            target,
+            members: self.members.iter().map(|(id, _)| id.clone()).collect(),
+            palette: self.scope.control_id("palette-scroll"),
+            reveal,
+        }))
+    }
+}
+struct Apply {
+    scope: Scope,
+    valid: bool,
+    target: Option<Id>,
+    members: Vec<Id>,
+    palette: Id,
+    reveal: Option<f32>,
+}
+impl<T> Operation<T> for Apply {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation<T>)) {
+        visit(self);
+    }
+    fn custom(&mut self, _: Option<&Id>, _: Rectangle, value: &mut dyn std::any::Any) {
+        if let Some(owner) = value.downcast_ref::<Owner>() {
+            self.valid = owner.0 == Some(self.scope);
+        }
+    }
+    fn focusable(&mut self, id: Option<&Id>, _: Rectangle, state: &mut dyn operation::Focusable) {
+        if !self.valid {
+            return;
+        }
+        if self
+            .target
+            .as_ref()
+            .is_some_and(|target| Some(target) == id)
+        {
+            state.focus();
+        } else if self.target.is_some() || id.is_some_and(|id| self.members.contains(id)) {
+            state.unfocus();
+        }
+    }
+    fn scrollable(
+        &mut self,
+        id: Option<&Id>,
+        _: Rectangle,
+        _: Rectangle,
+        _: Vector,
+        state: &mut dyn operation::Scrollable,
+    ) {
+        if self.valid
+            && id == Some(&self.palette)
+            && let Some(y) = self.reveal
+        {
+            state.scroll_to(operation::scrollable::AbsoluteOffset {
+                x: None,
+                y: Some(y),
+            });
+        }
+    }
+}
+
+// Every Collect/Apply pass observes current ownership before touching any field.
+struct Owner(Option<Scope>);
+
+struct Root<'a, Message, R: renderer::Renderer> {
+    owner: Option<Scope>,
+    content: Element<'a, Message, Theme, R>,
+}
+
+pub fn root<'a, Message: 'a, R: renderer::Renderer + 'a>(
+    content: impl Into<Element<'a, Message, Theme, R>>,
+    owner: Option<Scope>,
+) -> Element<'a, Message, Theme, R> {
+    Element::new(Root {
+        owner,
+        content: content.into(),
+    })
+}
+
+impl<Message, R: renderer::Renderer> Widget<Message, Theme, R> for Root<'_, Message, R> {
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+
+    fn diff(&self, tree: &mut Tree) {
+        tree.diff_children(std::slice::from_ref(&self.content));
+    }
+
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        operation.custom(None, layout.bounds(), &mut Owner(self.owner));
+        self.content
+            .as_widget_mut()
+            .operate(&mut tree.children[0], layout, renderer, operation);
+    }
+
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &InputEvent,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            style,
+            layout,
+            cursor,
+            viewport,
+        );
+    }
+
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        self.content.as_widget().mouse_interaction(
+            &tree.children[0],
+            layout,
+            cursor,
+            viewport,
+            renderer,
+        )
+    }
+
+    fn overlay<'b>(
+        &'b mut self,
+        tree: &'b mut Tree,
+        layout: Layout<'b>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'b, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}

crates/oa-desktop/src/behavior/canvas_workspace/tests.rs

@@ -0,0 +1,757 @@
+use super::*;
+use crate::app::{App, Message};
+use iced::advanced::{Layout, Shell, layout, widget};
+use iced::futures::{
+    StreamExt,
+    stream::{BoxStream, SelectAll},
+};
+use iced::{Rectangle, Size, mouse};
+use iced_runtime::{
+    Action,
+    user_interface::{Cache, UserInterface},
+};
+use std::collections::HashMap;
+
+type Pending = SelectAll<BoxStream<'static, Action<Message>>>;
+
+// iced_winit drains messages while collecting immediately ready actions. A
+// pending Task stream survives until its widget operation sends its result.
+fn enqueue(task: iced::Task<Message>, ready: &mut Vec<Action<Message>>, pending: &mut Pending) {
+    if let Some(mut stream) = iced_runtime::task::into_stream(task) {
+        let waker = iced::futures::task::noop_waker();
+        let mut context = std::task::Context::from_waker(&waker);
+        loop {
+            match stream.poll_next_unpin(&mut context) {
+                std::task::Poll::Ready(Some(action)) => ready.push(action),
+                std::task::Poll::Ready(None) => break,
+                std::task::Poll::Pending => {
+                    pending.push(stream);
+                    break;
+                }
+            }
+        }
+    }
+}
+
+#[derive(Default)]
+pub(crate) struct Geometry {
+    pub containers: HashMap<widget::Id, Rectangle>,
+    pub focused: Vec<(Option<widget::Id>, Rectangle, bool)>,
+    pub text_inputs: Vec<Rectangle>,
+    pub scrolls: HashMap<widget::Id, (Rectangle, Vector)>,
+}
+impl widget::Operation for Geometry {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation)) {
+        visit(self);
+    }
+    fn focusable(
+        &mut self,
+        id: Option<&widget::Id>,
+        bounds: Rectangle,
+        state: &mut dyn widget::operation::Focusable,
+    ) {
+        self.focused.push((id.cloned(), bounds, state.is_focused()));
+    }
+    fn text_input(
+        &mut self,
+        _: Option<&widget::Id>,
+        bounds: Rectangle,
+        _: &mut dyn widget::operation::TextInput,
+    ) {
+        self.text_inputs.push(bounds);
+    }
+    fn container(&mut self, id: Option<&widget::Id>, bounds: Rectangle) {
+        if let Some(id) = id {
+            self.containers.insert(id.clone(), bounds);
+        }
+    }
+    fn scrollable(
+        &mut self,
+        id: Option<&widget::Id>,
+        bounds: Rectangle,
+        _: Rectangle,
+        offset: Vector,
+        _: &mut dyn widget::operation::Scrollable,
+    ) {
+        if let Some(id) = id {
+            self.scrolls.insert(id.clone(), (bounds, offset));
+        }
+    }
+}
+impl Geometry {
+    pub fn bounds(&self, id: &str) -> Rectangle {
+        self.containers[&widget::Id::from(id.to_owned())]
+    }
+}
+
+/// Mount the actual App root, production widgets and renderer. Events are
+/// delivered in order with Iced's final-batch cursor, then fed through App::update.
+/// This deliberately does not seed any private canvas gesture state.
+pub(crate) struct Mounted {
+    pub renderer: iced::Renderer,
+    cache: Cache,
+    pub operations: usize,
+}
+impl Mounted {
+    pub async fn unshown() -> Self {
+        use iced::advanced::renderer::Headless;
+        let renderer = <iced::Renderer as Headless>::new(iced::Font::DEFAULT, 16.into(), None)
+            .await
+            .expect("production mounted tests require the supported WGPU headless renderer");
+        Self {
+            renderer,
+            cache: Cache::new(),
+            operations: 0,
+        }
+    }
+    pub async fn new(app: &mut App) -> Self {
+        let mut mounted = Self::unshown().await;
+        mounted.settle(app).await;
+        mounted
+    }
+    pub fn geometry(&mut self, app: &App) -> Geometry {
+        let mut geometry = Geometry::default();
+        self.operate(app, &mut geometry);
+        geometry
+    }
+    /// One operation pass, including every nested overlay, via installed Iced.
+    pub fn operate(&mut self, app: &App, operation: &mut dyn widget::Operation) {
+        let mut ui = UserInterface::build(
+            app.view(),
+            app.window_size,
+            std::mem::take(&mut self.cache),
+            &mut self.renderer,
+        );
+        ui.operate(&self.renderer, operation);
+        self.cache = ui.into_cache();
+    }
+    pub async fn settle(&mut self, app: &mut App) {
+        for _ in 0..3 {
+            self.batch(
+                app,
+                &[iced::Event::Window(iced::window::Event::RedrawRequested(
+                    std::time::Instant::now(),
+                ))],
+                mouse::Cursor::Unavailable,
+            )
+            .await;
+        }
+    }
+    pub async fn batch(
+        &mut self,
+        app: &mut App,
+        events: &[iced::Event],
+        cursor: mouse::Cursor,
+    ) -> Vec<Message> {
+        let messages = self.input(app, events, cursor);
+        let mut ready = vec![];
+        let mut pending = Pending::new();
+        for message in messages.iter().cloned() {
+            enqueue(app.update(message), &mut ready, &mut pending);
+        }
+        self.drain(app, ready, pending).await;
+        messages
+    }
+    pub fn input(
+        &mut self,
+        app: &App,
+        events: &[iced::Event],
+        cursor: mouse::Cursor,
+    ) -> Vec<Message> {
+        let mut messages = vec![];
+        let mut ui = UserInterface::build(
+            app.view(),
+            app.window_size,
+            std::mem::take(&mut self.cache),
+            &mut self.renderer,
+        );
+        let _ = ui.update(
+            events,
+            cursor,
+            &mut self.renderer,
+            &mut iced::advanced::clipboard::Null,
+            &mut messages,
+        );
+        self.cache = ui.into_cache();
+        messages
+    }
+    pub async fn perform(&mut self, app: &mut App, task: iced::Task<Message>) {
+        let mut ready = vec![];
+        let mut pending = Pending::new();
+        enqueue(task, &mut ready, &mut pending);
+        self.drain(app, ready, pending).await;
+    }
+    async fn drain(
+        &mut self,
+        app: &mut App,
+        mut ready: Vec<Action<Message>>,
+        mut pending: Pending,
+    ) {
+        loop {
+            let mut outputs = vec![];
+            if !ready.is_empty() {
+                // Build only after all App messages in this cycle have run.
+                let mut ui = UserInterface::build(
+                    app.view(),
+                    app.window_size,
+                    std::mem::take(&mut self.cache),
+                    &mut self.renderer,
+                );
+                for action in ready.drain(..) {
+                    match action {
+                        Action::Output(message) => outputs.push(message),
+                        Action::Widget(mut operation) => {
+                            self.operations += 1;
+                            loop {
+                                ui.operate(&self.renderer, &mut *operation);
+                                match operation.finish() {
+                                    widget::operation::Outcome::Chain(next) => operation = next,
+                                    widget::operation::Outcome::None
+                                    | widget::operation::Outcome::Some(()) => break,
+                                }
+                            }
+                        }
+                        action => {
+                            panic!("Unexpected native action in mounted App harness: {action:?}")
+                        }
+                    }
+                }
+                self.cache = ui.into_cache();
+            }
+            for message in outputs {
+                enqueue(app.update(message), &mut ready, &mut pending);
+            }
+            if !ready.is_empty() {
+                continue;
+            }
+            let Some(action) = pending.next().await else {
+                break;
+            };
+            ready.push(action);
+            let waker = iced::futures::task::noop_waker();
+            let mut context = std::task::Context::from_waker(&waker);
+            while let std::task::Poll::Ready(Some(action)) = pending.poll_next_unpin(&mut context) {
+                ready.push(action);
+            }
+        }
+    }
+    pub fn pixels(&mut self, app: &App) -> Vec<u8> {
+        use iced::advanced::renderer::Headless;
+        let mut ui = UserInterface::build(
+            app.view(),
+            app.window_size,
+            std::mem::take(&mut self.cache),
+            &mut self.renderer,
+        );
+        // update initializes the nested overlay layout used by draw.
+        let mut messages = vec![];
+        let _ = ui.update(
+            &[],
+            mouse::Cursor::Unavailable,
+            &mut self.renderer,
+            &mut iced::advanced::clipboard::Null,
+            &mut messages,
+        );
+        assert!(
+            messages.is_empty(),
+            "An empty draw preparation must not drop App messages"
+        );
+        ui.draw(
+            &mut self.renderer,
+            &crate::style::theme(),
+            &iced::advanced::renderer::Style {
+                text_color: crate::style::INK,
+            },
+            mouse::Cursor::Unavailable,
+        );
+        self.cache = ui.into_cache();
+        Headless::screenshot(
+            &mut self.renderer,
+            Size::new(app.window_size.width as u32, app.window_size.height as u32),
+            1.,
+            crate::style::BG,
+        )
+    }
+    pub async fn click(&mut self, app: &mut App, point: Point) -> Vec<Message> {
+        self.batch(
+            app,
+            &[
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: point }),
+                iced::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                iced::Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)),
+            ],
+            mouse::Cursor::Available(point),
+        )
+        .await
+    }
+    pub async fn pan(&mut self, app: &mut App, start: Point, end: Point) -> Vec<Message> {
+        self.batch(
+            app,
+            &[
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: start }),
+                iced::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Middle)),
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: end }),
+                iced::Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Middle)),
+            ],
+            mouse::Cursor::Available(end),
+        )
+        .await
+    }
+    pub fn scroll(&mut self, app: &App, id: &str, offset: f32) {
+        let mut operation = widget::operation::scrollable::scroll_to::<()>(
+            widget::Id::from(id.to_owned()),
+            widget::operation::scrollable::AbsoluteOffset {
+                x: None,
+                y: Some(offset),
+            },
+        );
+        self.operate(app, &mut operation);
+    }
+}
+
+pub(crate) fn key(named: iced::keyboard::key::Named) -> iced::Event {
+    use iced::keyboard::{self, Key};
+    iced::Event::Keyboard(keyboard::Event::KeyPressed {
+        key: Key::Named(named),
+        modified_key: Key::Named(named),
+        physical_key: keyboard::key::Physical::Unidentified(
+            keyboard::key::NativeCode::Unidentified,
+        ),
+        location: keyboard::Location::Standard,
+        modifiers: keyboard::Modifiers::empty(),
+        text: None,
+        repeat: false,
+    })
+}
+
+#[test]
+fn relative_camera_zoom_keeps_the_cursor_world_point_and_rejects_nonfinite_inputs() {
+    for scale in [0.05, 0.5, 1., 2.] {
+        let mut pan = Vector::new(-130., 75.);
+        let mut zoom = Some(scale);
+        let mut fit = false;
+        let at = Point::new(171., 93.);
+        let world = (at - Point::ORIGIN - pan) / scale;
+        change(
+            &mut pan,
+            &mut zoom,
+            &mut fit,
+            Event::Zoom {
+                factor: 1.25,
+                at,
+                base: scale,
+            },
+        );
+        let after = (at - Point::ORIGIN - pan) / zoom.unwrap();
+        assert!((after.x - world.x).abs() < 0.001 && (after.y - world.y).abs() < 0.001);
+        let before = (pan, zoom, fit);
+        for input in [
+            Event::Pan(Vector::new(f32::INFINITY, 0.)),
+            Event::Zoom {
+                factor: f32::NAN,
+                at,
+                base: scale,
+            },
+            Event::Zoom {
+                factor: 0.,
+                at,
+                base: scale,
+            },
+        ] {
+            assert!(!change(&mut pan, &mut zoom, &mut fit, input));
+            assert_eq!((pan, zoom, fit), before);
+        }
+    }
+}
+
+#[test]
+fn viewport_ordered_batch_uses_each_event_position_and_cancels_before_camera_motion() {
+    use iced::widget::Space;
+    let scope = Scope {
+        document: Id::new_v4(),
+        owner: Id::new_v4(),
+        revision: 2,
+        epoch: 0,
+    };
+    let mut view: Element<'_, Event, Theme, ()> = Viewport::new(
+        Space::new().width(Fill).height(Fill),
+        scope,
+        1.,
+        true,
+        |e| e,
+    )
+    .into();
+    let mut tree = widget::Tree::new(view.as_widget());
+    let node = view
+        .as_widget_mut()
+        .layout(
+            &mut tree,
+            &(),
+            &layout::Limits::new(Size::ZERO, Size::new(400., 300.)),
+        )
+        .move_to(Point::new(30., 80.));
+    let start = Point::new(90., 160.);
+    let middle = Point::new(125., 175.);
+    let end = Point::new(145., 185.);
+    let mut messages = vec![];
+    for event in [
+        mouse::Event::CursorMoved { position: start },
+        mouse::Event::ButtonPressed(mouse::Button::Middle),
+        mouse::Event::CursorMoved { position: middle },
+        mouse::Event::CursorMoved { position: end },
+        mouse::Event::ButtonReleased(mouse::Button::Middle),
+    ] {
+        view.as_widget_mut().update(
+            &mut tree,
+            &iced::Event::Mouse(event),
+            Layout::new(&node),
+            mouse::Cursor::Available(end),
+            &(),
+            &mut iced::advanced::clipboard::Null,
+            &mut Shell::new(&mut messages),
+            &Rectangle::with_size(Size::new(700., 600.)),
+        );
+    }
+    assert!(matches!(messages.first(), Some(Event::CancelGesture)));
+    let total = messages
+        .iter()
+        .fold(Vector::ZERO, |total, event| match event {
+            Event::Pan(delta) => total + *delta,
+            _ => total,
+        });
+    assert_eq!(total, end - start);
+}
+
+pub(crate) fn scope(app: &App) -> Scope {
+    if let Some(context) = app.scenario_context() {
+        Scope {
+            document: context.document,
+            owner: context.scenario,
+            revision: context.revision,
+            epoch: app.camera_epoch,
+        }
+    } else {
+        let context = app.topology_context().expect("mounted behavior owner");
+        Scope {
+            document: context.document,
+            owner: context.owner,
+            revision: context.revision,
+            epoch: app.camera_epoch,
+        }
+    }
+}
+pub(crate) fn focused(mounted: &mut Mounted, app: &App, name: &str) -> bool {
+    let id = scope(app).control_id(name);
+    mounted
+        .geometry(app)
+        .focused
+        .iter()
+        .any(|(member, _, focused)| member.as_ref() == Some(&id) && *focused)
+}
+pub(crate) async fn tab_to(mounted: &mut Mounted, app: &mut App, name: &str) {
+    for _ in 0..32 {
+        if focused(mounted, app, name) {
+            return;
+        }
+        mounted
+            .batch(
+                app,
+                &[key(iced::keyboard::key::Named::Tab)],
+                mouse::Cursor::Unavailable,
+            )
+            .await;
+    }
+    panic!("Keyboard traversal did not reach {name}");
+}
+pub(crate) fn camera_delta(messages: &[Message]) -> Message {
+    messages.iter().find(|m| matches!(m,
+        Message::ScenarioCanvas(crate::behavior::scenario::CanvasEvent::Camera(_, _, Event::Pan(delta)))
+        | Message::TopologyCanvas(crate::behavior::topology::CanvasEvent::Camera(_, _, Event::Pan(delta))) if *delta != Vector::ZERO
+    )).expect("actual nonzero camera delta from a mounted gesture").clone()
+}
+pub(crate) async fn press_middle(mounted: &mut Mounted, app: &mut App, point: Point) {
+    mounted
+        .batch(
+            app,
+            &[
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: point }),
+                iced::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Middle)),
+            ],
+            mouse::Cursor::Available(point),
+        )
+        .await;
+}
+pub(crate) async fn release_middle(
+    mounted: &mut Mounted,
+    app: &mut App,
+    point: Point,
+) -> Vec<Message> {
+    mounted
+        .batch(
+            app,
+            &[
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: point }),
+                iced::Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Middle)),
+            ],
+            mouse::Cursor::Available(point),
+        )
+        .await
+}
+pub(crate) fn assert_drawn_focus(before: &[u8], after: &[u8], size: Size, bounds: Rectangle) {
+    let width = size.width as usize;
+    assert_eq!(before.len(), width * size.height as usize * 4);
+    assert_eq!(after.len(), before.len());
+    let mut changed = 0;
+    for y in bounds.y.ceil() as usize..(bounds.y + bounds.height).floor() as usize {
+        for x in bounds.x.ceil() as usize..(bounds.x + bounds.width).floor() as usize {
+            if x as f32 - bounds.x > 2.
+                && bounds.x + bounds.width - x as f32 > 2.
+                && y as f32 - bounds.y > 2.
+                && bounds.y + bounds.height - y as f32 > 2.
+            {
+                continue;
+            }
+            let start = (y * width + x) * 4;
+            if before[start..start + 3] != after[start..start + 3] {
+                changed += 1;
+            }
+        }
+    }
+    assert!(
+        changed >= bounds.width.min(bounds.height) as usize,
+        "Focus must change visible border pixels, changed={changed}, bounds={bounds:?}"
+    );
+}
+
+pub(crate) fn character(value: &str) -> iced::Event {
+    let mut event = key(iced::keyboard::key::Named::Space);
+    if let iced::Event::Keyboard(iced::keyboard::Event::KeyPressed {
+        key,
+        modified_key,
+        text,
+        ..
+    }) = &mut event
+    {
+        *key = iced::keyboard::Key::Character(value.into());
+        *modified_key = key.clone();
+        *text = Some(value.into());
+    }
+    event
+}
+
+/// Inspect the action without stripping the lifetime from retained packets.
+pub(crate) fn intent_action(message: &Message) -> &Message {
+    match message {
+        Message::BehaviorControl(intent) => &intent.message,
+        message => message,
+    }
+}
+
+/// Deliberately retain a returned Chain to test the stronger ownership invariant.
+/// Native Iced runs Chain passes synchronously; this is not a native interleaving.
+pub(crate) async fn retained_focus_apply(
+    mounted: &mut Mounted,
+    app: &mut App,
+) -> Box<dyn widget::Operation> {
+    let entry = mounted.input(
+        app,
+        &[key(iced::keyboard::key::Named::F6)],
+        mouse::Cursor::Unavailable,
+    );
+    assert_eq!(
+        entry.len(),
+        1,
+        "actual initial F6 must emit one canvas focus request"
+    );
+    let mut stream = iced_runtime::task::into_stream(app.update(entry[0].clone()))
+        .expect("F6 returns a widget Task");
+    let Some(Action::Widget(mut operation)) = stream.next().await else {
+        panic!("F6 first action must be Collect");
+    };
+    mounted.operate(app, &mut *operation);
+    match operation.finish() {
+        widget::operation::Outcome::Chain(apply) => apply,
+        _ => panic!("Live Collect must produce its guarded Apply pass"),
+    }
+}
+
+pub(crate) async fn overflow_last_tool(mounted: &mut Mounted, app: &mut App, last: &'static str) {
+    use iced::keyboard::key::Named;
+    let geometry = mounted.geometry(app);
+    let last_bounds = geometry.containers[&scope(app).control_id(last)];
+    let (rail, offset) = geometry.scrolls[&scope(app).control_id("palette-scroll")];
+    assert_eq!(offset.y, 0.);
+    assert!(
+        last_bounds.y >= rail.y + rail.height,
+        "last tool starts fully below the overflowing palette: tool={last_bounds:?}, rail={rail:?}"
+    );
+    mounted
+        .batch(app, &[key(Named::F6)], mouse::Cursor::Unavailable)
+        .await;
+    tab_to(mounted, app, last).await;
+    let geometry = mounted.geometry(app);
+    let mut visible = geometry.containers[&scope(app).control_id(last)];
+    let (rail, offset) = geometry.scrolls[&scope(app).control_id("palette-scroll")];
+    assert!(offset.y > 0., "keyboard traversal must scroll the palette");
+    visible.x -= offset.x;
+    visible.y -= offset.y;
+    assert!(
+        visible.y >= rail.y && visible.y + visible.height <= rail.y + rail.height + 0.5,
+        "the entire last tool is revealed: tool={visible:?}, rail={rail:?}"
+    );
+    let messages = mounted
+        .batch(app, &[key(Named::Enter)], mouse::Cursor::Unavailable)
+        .await;
+    assert!(
+        messages.iter().any(
+            |message| matches!(message, Message::BehaviorControl(intent) if intent.name == last)
+        ),
+        "the revealed last tool is keyboard activated"
+    );
+    assert!(focused(mounted, app, last));
+    let on = mounted.pixels(app);
+    mounted
+        .batch(app, &[key(Named::Escape)], mouse::Cursor::Unavailable)
+        .await;
+    let off = mounted.pixels(app);
+    assert_drawn_focus(&off, &on, app.window_size, visible);
+}
+
+pub(crate) async fn retained_toolbar_boundaries(
+    mounted: &mut Mounted,
+    app: &mut App,
+    tool: &'static str,
+) {
+    use iced::keyboard::key::Named;
+    for boundary in ["Chooser", "Dirty", "Picker"] {
+        let mut packets = vec![];
+        for name in ["Fit", tool, "Details", "Panels", "Canvas"] {
+            packets.push(capture_toolbar(mounted, app, name));
+        }
+        let lifetime = app.camera_epoch;
+        let epoch = app.canvas_epoch;
+        let process = app.behavior.topology.camera_boundary();
+        let scenario = app.behavior.scenario.camera_boundary();
+        match boundary {
+            "Chooser" => {
+                let draft = app.draft.as_ref().unwrap();
+                let id = crate::forms::reference_chooser::trigger::field_id(
+                    draft.reference_generation(),
+                    "/parent",
+                );
+                let bounds = mounted
+                    .geometry(app)
+                    .focused
+                    .iter()
+                    .find(|(field, _, _)| field.as_ref() == Some(&id))
+                    .expect("real Inspector parent reference trigger")
+                    .1;
+                let request = draft.reference_open(app.project(), "/parent", bounds);
+                let task = app.update(Message::FieldReferenceOpen(request));
+                mounted.perform(app, task).await;
+                assert!(app.reference_input_active());
+                mounted
+                    .batch(app, &[key(Named::Escape)], mouse::Cursor::Unavailable)
+                    .await;
+                assert!(!app.reference_input_active());
+            }
+            "Dirty" => {
+                let task = app.update(Message::Field(
+                    "/name".into(),
+                    "Unsaved camera boundary".into(),
+                ));
+                mounted.perform(app, task).await;
+                assert!(app.draft_dirty());
+                // Every retained packet is also rejected while the owner is dirty.
+                for packet in packets.iter().cloned() {
+                    let task = app.update(packet);
+                    mounted.perform(app, task).await;
+                }
+                assert!(app.draft_dirty());
+                let task = app.update(Message::RevertProperties);
+                mounted.perform(app, task).await;
+                assert!(!app.draft_dirty());
+            }
+            "Picker" => {
+                // Public transitions, with cancellation injected at the external
+                // picker boundary. Never poll the native dialog future here.
+                let picker = app.update(Message::Save(true));
+                if cfg!(target_os = "linux") {
+                    assert!(app.file_prompt.is_some());
+                    mounted.perform(app, picker).await;
+                    let task = app.update(Message::CancelFile);
+                    mounted.perform(app, task).await;
+                } else {
+                    assert!(app.busy, "Save As enters the real native-picker busy state");
+                    drop(picker);
+                    for packet in packets.iter().cloned() {
+                        let task = app.update(packet);
+                        mounted.perform(app, task).await;
+                    }
+                    let task = app.update(Message::SavePath(None));
+                    mounted.perform(app, task).await;
+                    assert!(!app.busy);
+                }
+            }
+            _ => unreachable!(),
+        }
+        assert_ne!(
+            app.camera_epoch, lifetime,
+            "{boundary} changes the presentation lifetime"
+        );
+        assert_eq!(
+            app.canvas_epoch, epoch,
+            "{boundary} cycle leaves semantic context unchanged"
+        );
+        let focus_before = mounted
+            .geometry(app)
+            .focused
+            .into_iter()
+            .filter(|(_, _, value)| *value)
+            .collect::<Vec<_>>();
+        let current_lifetime = app.camera_epoch;
+        for packet in packets {
+            let task = app.update(packet);
+            mounted.perform(app, task).await;
+        }
+        assert_eq!(
+            app.camera_epoch, current_lifetime,
+            "{boundary} retained intents cannot start a new lifetime"
+        );
+        assert!(
+            app.behavior.topology.camera_boundary() == process,
+            "{boundary} retained toolbar packet changed process presentation"
+        );
+        assert!(
+            app.behavior.scenario.camera_boundary() == scenario,
+            "{boundary} retained toolbar packet changed scenario presentation"
+        );
+        assert_eq!(
+            mounted
+                .geometry(app)
+                .focused
+                .into_iter()
+                .filter(|(_, _, value)| *value)
+                .collect::<Vec<_>>(),
+            focus_before,
+            "{boundary} retained toolbar packet stole field focus"
+        );
+    }
+}
+
+pub(crate) fn capture_toolbar(mounted: &mut Mounted, app: &App, name: &'static str) -> Message {
+    let point = mounted.geometry(app).containers[&scope(app).control_id(name)].center();
+    mounted
+        .input(
+            app,
+            &[
+                iced::Event::Mouse(mouse::Event::CursorMoved { position: point }),
+                iced::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                iced::Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)),
+            ],
+            mouse::Cursor::Available(point),
+        )
+        .into_iter()
+        .find(|message| matches!(message, Message::BehaviorControl(intent) if intent.name == name))
+        .expect("actual production toolbar packet")
+}

crates/oa-desktop/src/behavior/canvas_workspace/viewport.rs

@@ -0,0 +1,426 @@
+use super::{Event as CameraEvent, Scope};
+use iced::advanced::{
+    Clipboard, Layout, Shell, Widget, layout, overlay, renderer,
+    widget::{Operation, Tree, operation, tree},
+};
+use iced::{Border, Element, Event, Length, Point, Rectangle, Size, Theme, Vector};
+use iced::{keyboard, mouse};
+
+#[derive(Default)]
+struct Input {
+    scope: Option<Scope>,
+    focused: bool,
+    pointer: Option<Point>,
+    pan: Option<(mouse::Button, Point)>,
+    space: bool,
+    bounds: Option<Rectangle>,
+}
+impl operation::Focusable for Input {
+    fn is_focused(&self) -> bool {
+        self.focused
+    }
+    fn focus(&mut self) {
+        self.focused = true;
+    }
+    fn unfocus(&mut self) {
+        self.focused = false;
+        self.pan = None;
+        self.space = false;
+    }
+}
+pub struct Viewport<'a, Message, R = iced::Renderer>
+where
+    R: renderer::Renderer,
+{
+    content: Element<'a, Message, Theme, R>,
+    scope: Scope,
+    scale: f32,
+    keyboard: bool,
+    blank_pan: bool,
+    publish: Box<dyn Fn(CameraEvent) -> Message + 'a>,
+}
+impl<'a, Message, R: renderer::Renderer> Viewport<'a, Message, R> {
+    pub fn new(
+        content: impl Into<Element<'a, Message, Theme, R>>,
+        scope: Scope,
+        scale: f32,
+        keyboard: bool,
+        publish: impl Fn(CameraEvent) -> Message + 'a,
+    ) -> Self {
+        Self {
+            content: content.into(),
+            scope,
+            scale,
+            keyboard,
+            blank_pan: false,
+            publish: Box::new(publish),
+        }
+    }
+    pub fn pan_background(mut self, enabled: bool) -> Self {
+        self.blank_pan = enabled;
+        self
+    }
+}
+impl<Message, R: renderer::Renderer> Widget<Message, Theme, R> for Viewport<'_, Message, R> {
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<Input>()
+    }
+    fn state(&self) -> tree::State {
+        tree::State::new(Input {
+            scope: Some(self.scope),
+            ..Default::default()
+        })
+    }
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+    fn diff(&self, tree: &mut Tree) {
+        let state = tree.state.downcast_mut::<Input>();
+        if state.scope.is_none_or(|s| {
+            (s.document, s.owner, s.revision)
+                != (self.scope.document, self.scope.owner, self.scope.revision)
+        }) {
+            *state = Input::default();
+        }
+        if state
+            .scope
+            .is_some_and(|scope| scope.epoch != self.scope.epoch)
+            || !self.keyboard
+        {
+            state.pan = None;
+            state.space = false;
+        }
+        if !self.keyboard {
+            state.focused = false;
+        }
+        state.scope = Some(self.scope);
+        tree.diff_children(std::slice::from_ref(&self.content));
+    }
+    fn size(&self) -> Size<Length> {
+        Size::new(Length::Fill, Length::Fill)
+    }
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        if self.keyboard {
+            let id = self.scope.control_id("viewport");
+            operation.custom(
+                Some(&id),
+                layout.bounds(),
+                &mut super::focus::Member(self.scope),
+            );
+            operation.focusable(
+                Some(&id),
+                layout.bounds(),
+                tree.state.downcast_mut::<Input>(),
+            );
+        }
+        self.content
+            .as_widget_mut()
+            .operate(&mut tree.children[0], layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        if shell.is_event_captured() {
+            return;
+        }
+        let state = tree.state.downcast_mut::<Input>();
+        let changed_bounds = state.bounds.is_some_and(|bounds| bounds != layout.bounds());
+        state.bounds = Some(layout.bounds());
+        if changed_bounds || !self.keyboard {
+            state.pan = None;
+            state.space = false;
+        }
+        if !self.keyboard {
+            state.focused = false;
+        }
+        if let Event::Mouse(mouse::Event::CursorMoved { position }) = event {
+            state.pointer = Some(*position);
+        }
+        let pointer = match event {
+            Event::Mouse(
+                mouse::Event::ButtonPressed(_)
+                | mouse::Event::ButtonReleased(_)
+                | mouse::Event::WheelScrolled { .. },
+            ) => state.pointer.or_else(|| cursor.position()),
+            Event::Mouse(mouse::Event::CursorMoved { position }) => Some(*position),
+            _ => cursor.position().or(state.pointer),
+        };
+        let visible = layout.bounds().intersection(viewport);
+        let inside = pointer.is_some_and(|p| visible.is_some_and(|v| v.contains(p)))
+            && cursor.position().is_some();
+        if !self.keyboard {
+            state.space = false;
+        }
+        let mut cancel = changed_bounds;
+        let mut camera = None;
+        let mut capture = false;
+        match event {
+            Event::Window(iced::window::Event::Unfocused | iced::window::Event::Resized(_)) => {
+                state.pan = None;
+                state.space = false;
+                state.focused = false;
+            }
+            Event::Mouse(mouse::Event::CursorLeft) => {
+                state.pan = None;
+                state.pointer = None;
+            }
+            Event::Mouse(mouse::Event::ButtonPressed(button)) => {
+                if state.pan.is_some_and(|(held, _)| held != *button) || !inside {
+                    state.pan = None;
+                    state.space = false;
+                    cancel = true;
+                }
+                state.focused = inside && self.keyboard;
+                if inside
+                    && self.keyboard
+                    && (*button == mouse::Button::Middle
+                        || (*button == mouse::Button::Left && state.space))
+                {
+                    state.pan = pointer.map(|p| (*button, p));
+                    cancel = true;
+                    camera = Some(CameraEvent::CancelGesture);
+                    capture = true;
+                }
+            }
+            Event::Mouse(mouse::Event::CursorMoved { position }) => {
+                if let Some((button, previous)) = state.pan {
+                    state.pan = Some((button, *position));
+                    camera = Some(CameraEvent::Pan(*position - previous));
+                    capture = true;
+                }
+            }
+            Event::Mouse(mouse::Event::ButtonReleased(button)) => {
+                if let Some((held, previous)) = state.pan
+                    && held == *button
+                {
+                    state.pan = None;
+                    camera = pointer
+                        .filter(|_| inside)
+                        .map(|p| CameraEvent::Pan(p - previous));
+                    capture = true;
+                }
+            }
+            Event::Mouse(mouse::Event::WheelScrolled { delta }) if inside && state.focused => {
+                state.pan = None;
+                cancel = true;
+                let y = match delta {
+                    mouse::ScrollDelta::Lines { y, .. } => *y,
+                    mouse::ScrollDelta::Pixels { y, .. } => *y / 40.,
+                };
+                if y != 0. {
+                    let at = pointer.unwrap() - Vector::new(layout.bounds().x, layout.bounds().y);
+                    camera = Some(CameraEvent::Zoom {
+                        factor: 1.1_f32.powf(y.clamp(-8., 8.)),
+                        at,
+                        base: self.scale,
+                    });
+                    capture = true;
+                }
+            }
+            Event::Keyboard(keyboard::Event::KeyPressed {
+                key: keyboard::Key::Named(keyboard::key::Named::F6),
+                modifiers,
+                repeat: false,
+                ..
+            }) if self.keyboard && modifiers.is_empty() => {
+                camera = Some(CameraEvent::ToggleFocus);
+                capture = true;
+                cancel = true;
+            }
+            Event::Keyboard(keyboard::Event::KeyPressed { key, modifiers, .. })
+                if state.focused && self.keyboard =>
+            {
+                use keyboard::{Key, key::Named};
+                match key.as_ref() {
+                    Key::Named(Named::Space) => {
+                        state.space = true;
+                        cancel = true;
+                        camera = Some(CameraEvent::CancelGesture);
+                        capture = true;
+                    }
+                    Key::Named(Named::Tab) => {
+                        camera = Some(CameraEvent::Traverse(modifiers.shift()));
+                        capture = true;
+                    }
+                    Key::Named(Named::Escape) => {
+                        state.pan = None;
+                        state.space = false;
+                        camera = Some(CameraEvent::Leave);
+                        capture = true;
+                    }
+                    Key::Named(key) if modifiers.is_empty() => {
+                        let delta = match key {
+                            Named::ArrowLeft => Some(Vector::new(60., 0.)),
+                            Named::ArrowRight => Some(Vector::new(-60., 0.)),
+                            Named::ArrowUp => Some(Vector::new(0., 60.)),
+                            Named::ArrowDown => Some(Vector::new(0., -60.)),
+                            _ => None,
+                        };
+                        camera = delta.map(CameraEvent::Pan);
+                        capture = camera.is_some();
+                        cancel = capture;
+                    }
+                    _ => {}
+                }
+            }
+            Event::Keyboard(keyboard::Event::KeyReleased { key, .. })
+                if *key == keyboard::Key::Named(keyboard::key::Named::Space) =>
+            {
+                state.space = false;
+            }
+            _ => {}
+        }
+        if cancel {
+            self.content.as_widget_mut().update(
+                &mut tree.children[0],
+                &Event::Window(iced::window::Event::Unfocused),
+                layout,
+                cursor,
+                renderer,
+                clipboard,
+                shell,
+                viewport,
+            );
+        }
+        if let Some(event) = camera {
+            shell.publish((self.publish)(event));
+        }
+        if capture {
+            shell.capture_event();
+            shell.request_redraw();
+            return;
+        }
+        if matches!(event, Event::Keyboard(_)) && (!state.focused || !self.keyboard) {
+            return;
+        }
+        let child_cursor = if inside {
+            pointer.map_or(mouse::Cursor::Unavailable, mouse::Cursor::Available)
+        } else {
+            mouse::Cursor::Unavailable
+        };
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            child_cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+        // A semantic hit or armed creation tool gets first refusal. In Select,
+        // an otherwise unused blank press starts the same camera gesture.
+        if self.blank_pan
+            && self.keyboard
+            && inside
+            && !shell.is_event_captured()
+            && matches!(
+                event,
+                Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left))
+            )
+        {
+            state.pan = pointer.map(|p| (mouse::Button::Left, p));
+            shell.publish((self.publish)(CameraEvent::CancelGesture));
+            shell.capture_event();
+            shell.request_redraw();
+        }
+    }
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        renderer.with_layer(layout.bounds(), |renderer| {
+            self.content.as_widget().draw(
+                &tree.children[0],
+                renderer,
+                theme,
+                style,
+                layout,
+                cursor,
+                viewport,
+            );
+        });
+        if tree.state.downcast_ref::<Input>().focused && self.keyboard {
+            renderer.fill_quad(
+                renderer::Quad {
+                    bounds: layout.bounds(),
+                    border: Border {
+                        color: crate::style::TEAL,
+                        width: 1.,
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+                iced::Color::TRANSPARENT,
+            );
+        }
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        if tree.state.downcast_ref::<Input>().pan.is_some() {
+            mouse::Interaction::Grabbing
+        } else {
+            self.content.as_widget().mouse_interaction(
+                &tree.children[0],
+                layout,
+                cursor,
+                viewport,
+                renderer,
+            )
+        }
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        tree: &'a mut Tree,
+        layout: Layout<'a>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'a, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}
+impl<'a, Message: 'a, R: renderer::Renderer + 'a> From<Viewport<'a, Message, R>>
+    for Element<'a, Message, Theme, R>
+{
+    fn from(viewport: Viewport<'a, Message, R>) -> Self {
+        Element::new(viewport)
+    }
+}

crates/oa-desktop/src/behavior/contextual_source_tests.rs

@@ -886,7 +886,7 @@ fn contextual_source_incomplete_recovered_kind_reports_error_without_panicking()
 }
 
 #[test]
-fn contextual_source_old_empty_action_cannot_open_a_previous_owner_or_layer() {
+fn contextual_source_empty_palette_lifeline_cannot_open_a_previous_owner_or_layer() {
     use crate::app::{App, Message, Page};
     let (mut p, a) = scenario_project(Layer::Oa, ScenarioViewpoint::OperationalActivity);
     let b = p
@@ -898,30 +898,32 @@ fn contextual_source_old_empty_action_cannot_open_a_previous_owner_or_layer() {
     app.behavior.active_owner = Some(a);
     app.selected = a;
     let context = app.scenario_context().unwrap();
+    let source = app.document.bundle().clone();
+    let begin = |context| scenario::CanvasEvent::BeginOccurrence {
+        context,
+        tool: scenario::Tool::Lifeline,
+        slot: scenario::Slot {
+            parent: a,
+            before: None,
+        },
+        lifeline: None,
+    };
     app.behavior.active_owner = Some(b);
     app.selected = b;
-    let _ = app.update(Message::ScenarioCanvas(scenario::CanvasEvent::First(
-        context,
-        scenario::Tool::Lifeline,
-    )));
+    let _ = app.update(Message::ScenarioCanvas(begin(context)));
     assert!(!app.behavior.has_pending());
     assert_eq!(app.project(), &p);
     app.behavior.active_owner = Some(a);
     app.selected = a;
     app.layer = Layer::Sa;
-    let _ = app.update(Message::ScenarioCanvas(scenario::CanvasEvent::First(
-        context,
-        scenario::Tool::Lifeline,
-    )));
+    let _ = app.update(Message::ScenarioCanvas(begin(context)));
     assert!(!app.behavior.has_pending());
     app.layer = Layer::Oa;
     let current = app.scenario_context().unwrap();
-    let _ = app.update(Message::ScenarioCanvas(scenario::CanvasEvent::First(
-        current,
-        scenario::Tool::Lifeline,
-    )));
+    let _ = app.update(Message::ScenarioCanvas(begin(current)));
     assert_eq!(app.behavior.pending_owner(), Some(a));
     assert_eq!(app.project(), &p);
+    assert_eq!(app.document.bundle(), &source);
     assert!(!app.document.can_undo());
 }
 

crates/oa-desktop/src/behavior/form_session.rs

@@ -0,0 +1,148 @@
+//! Keep behavior field state within one editing session and reset it on replacement.
+use iced::advanced::widget::{Operation, Tree, tree};
+use iced::advanced::{Clipboard, Layout, Shell, Widget, layout, overlay, renderer};
+use iced::{Element, Event, Length, Rectangle, Size, Theme, Vector, mouse};
+use oa_core::Id;
+
+struct Identity(Id);
+
+struct Session<'a, Message, R: renderer::Renderer> {
+    identity: Id,
+    content: Element<'a, Message, Theme, R>,
+}
+
+pub(super) fn reset_on_change<'a, Message: 'a, R: renderer::Renderer + 'a>(
+    identity: Id,
+    content: impl Into<Element<'a, Message, Theme, R>>,
+) -> Element<'a, Message, Theme, R> {
+    Element::new(Session {
+        identity,
+        content: content.into(),
+    })
+}
+
+impl<Message, R: renderer::Renderer> Widget<Message, Theme, R> for Session<'_, Message, R> {
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<Identity>()
+    }
+
+    fn state(&self) -> tree::State {
+        tree::State::new(Identity(self.identity))
+    }
+
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+
+    fn diff(&self, tree: &mut Tree) {
+        let retained = tree.state.downcast_mut::<Identity>();
+        if retained.0 != self.identity {
+            retained.0 = self.identity;
+            // Iced's keyed column preserves same-length child replacements.
+            // An editing-session replacement must instead get fresh field state.
+            tree.children = self.children();
+        } else {
+            tree.diff_children(std::slice::from_ref(&self.content));
+        }
+    }
+
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        self.content
+            .as_widget_mut()
+            .operate(&mut tree.children[0], layout, renderer, operation);
+    }
+
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            style,
+            layout,
+            cursor,
+            viewport,
+        );
+    }
+
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        self.content.as_widget().mouse_interaction(
+            &tree.children[0],
+            layout,
+            cursor,
+            viewport,
+            renderer,
+        )
+    }
+
+    fn overlay<'b>(
+        &'b mut self,
+        tree: &'b mut Tree,
+        layout: Layout<'b>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'b, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}

crates/oa-desktop/src/behavior/scenario.rs

@@ -4,7 +4,10 @@ use super::topology::{occurrence, unique_batch};
 use super::*;
 use iced::widget::{Column, column, text_input};
 use std::{cell::RefCell, collections::BTreeSet};
+pub(crate) mod focus;
+mod usage;
 mod workspace;
+pub(crate) use workspace::NAME_INPUT;
 pub use workspace::{Shelf, view};
 
 #[cfg(test)]
@@ -94,11 +97,12 @@ impl std::fmt::Display for CanvasTool {
 }
 #[derive(Debug, Clone)]
 pub enum CanvasEvent {
-    First(Context, Tool),
     Scrolled(Context, ScrollArea, iced::Vector),
     Restored(Context, Id, ScrollArea, iced::Vector),
     Viewport(Context, Size),
+    FormShown(Context, Id),
     Zoom(Context, Option<f32>),
+    Camera(Context, u64, super::canvas_workspace::Event),
     Focus(Context),
     Shelf(Context, Shelf),
     OpenUse(Context, Id),
@@ -126,18 +130,18 @@ pub enum CanvasEvent {
 }
 #[derive(Debug, Clone, Copy)]
 pub enum ScrollArea {
-    Canvas,
-    // Retained navigation channel, now the independent Selection/outline shelf.
+    // The independent Details/outline scroller; viewport motion uses Camera.
     Page,
 }
 impl CanvasEvent {
     pub fn context(&self) -> Context {
         match self {
-            Self::First(context, _)
-            | Self::Scrolled(context, _, _)
+            Self::Scrolled(context, _, _)
             | Self::Restored(context, ..)
             | Self::Viewport(context, _)
+            | Self::FormShown(context, _)
             | Self::Zoom(context, _)
+            | Self::Camera(context, ..)
             | Self::Focus(context)
             | Self::Shelf(context, _)
             | Self::OpenUse(context, _)
@@ -200,11 +204,14 @@ const VALUE_PAGE_SIZE: usize = 24;
 #[derive(Default)]
 pub struct State {
     draft: Option<Draft>,
+    form_session: Id,
+    form_mount: Id,
+    form_focus_pending: bool,
     canvas_tool: Option<(Id, CanvasTool)>,
     call_choices: RefCell<Option<(CallChoiceContext, Vec<Choice>)>>,
-    scroll_offsets: [iced::Vector; 2],
+    details_offset: iced::Vector,
     return_to: Vec<Caller>,
-    restore: Option<ViewportRestore>,
+    restore: Option<DetailsRestore>,
     presentation: workspace::Presentation,
 }
 const CALLER_LIMIT: usize = 32;
@@ -214,15 +221,14 @@ pub(crate) struct Caller {
     pub occurrence: Id,
     target: Id,
     tool: CanvasTool,
-    offsets: [iced::Vector; 2],
+    details_offset: iced::Vector,
     presentation: workspace::Presentation,
 }
-struct ViewportRestore {
+struct DetailsRestore {
     document: Id,
     owner: Id,
     token: Id,
-    offsets: [iced::Vector; 2],
-    pending: [bool; 2],
+    offset: iced::Vector,
 }
 #[derive(Clone, Copy)]
 pub(super) struct ScrollRestore {
@@ -282,6 +288,18 @@ struct Draft {
     choice_page: usize,
 }
 impl State {
+    pub(crate) fn camera_boundary(&self) -> impl PartialEq + use<> {
+        (
+            self.canvas_tool,
+            self.presentation.focused,
+            self.presentation.shelf,
+            self.presentation.viewport,
+            self.presentation.pan,
+            self.presentation.zoom,
+            self.presentation.fit,
+        )
+    }
+
     pub(super) fn pending_name(&self) -> Option<&str> {
         self.draft.as_ref().map(|d| d.name.as_str())
     }
@@ -301,7 +319,11 @@ impl State {
         self.draft.as_ref().is_some_and(|d| d.source.is_open())
     }
     pub fn source_back(&mut self) -> bool {
-        self.draft.as_mut().is_some_and(|d| d.source.back())
+        let returned = self.draft.as_mut().is_some_and(|d| d.source.back());
+        if returned {
+            self.remount_form();
+        }
+        returned
     }
 
     pub(crate) fn enter(&mut self, document: Id, owner: Id) {
@@ -311,16 +333,38 @@ impl State {
                 focused: self.presentation.focused,
                 ..Default::default()
             };
-            self.scroll_offsets = [iced::Vector::ZERO; 2];
+            self.details_offset = iced::Vector::ZERO;
             self.restore = None;
         }
     }
     pub(crate) fn viewport(&mut self, size: Size) -> bool {
         self.presentation.viewport(size)
     }
+    pub(crate) fn camera(&mut self, event: super::canvas_workspace::Event) -> bool {
+        let p = &mut self.presentation;
+        super::canvas_workspace::change(&mut p.pan, &mut p.zoom, &mut p.fit, event)
+    }
     pub(crate) fn zoom(&mut self, scale: Option<f32>) -> bool {
         self.presentation.zoom(scale)
     }
+    pub(crate) fn camera_zoom(&mut self, p: &Project, owner: Id, zoom: Option<f32>) -> bool {
+        let size = Scene::sequence(p, owner, owner).size;
+        let old = self.presentation.scale(size);
+        if let Some(next) = zoom {
+            let viewport = self.presentation.viewport.unwrap_or(Size::new(500., 300.));
+            self.camera(super::canvas_workspace::Event::Zoom {
+                factor: next / old,
+                at: Point::new(viewport.width / 2., viewport.height / 2.),
+                base: old,
+            })
+        } else {
+            self.zoom(None);
+            let fitted = self.presentation.scale(size);
+            self.zoom(Some(fitted));
+            self.presentation.pan = iced::Vector::ZERO;
+            true
+        }
+    }
     pub(crate) fn focused(&self) -> bool {
         self.presentation.focused
     }
@@ -349,11 +393,11 @@ impl State {
             occurrence,
             target,
             tool: self.canvas_tool(context.scenario),
-            offsets: self.scroll_offsets,
+            details_offset: self.details_offset,
             presentation: self.presentation.clone(),
         });
         self.canvas_tool = Some((target, CanvasTool::Select));
-        self.scroll_offsets = [iced::Vector::ZERO; 2];
+        self.details_offset = iced::Vector::ZERO;
         self.restore = None;
         Ok(target)
     }
@@ -380,34 +424,30 @@ impl State {
             return;
         }
         self.canvas_tool = Some((frame.owner, frame.tool));
-        self.scroll_offsets = frame.offsets;
+        self.details_offset = frame.details_offset;
         self.presentation = frame.presentation;
         self.presentation.identity = Some((context.document, context.scenario));
-        self.restore = Some(ViewportRestore {
+        self.restore = Some(DetailsRestore {
             document: context.document,
             owner: frame.owner,
             token: Id::new_v4(),
-            offsets: frame.offsets,
-            pending: [true; 2],
+            offset: frame.details_offset,
         });
     }
     pub(super) fn scroll_restore(
         &self,
         context: Context,
-        area: ScrollArea,
+        ScrollArea::Page: ScrollArea,
     ) -> Option<ScrollRestore> {
-        let index = match area {
-            ScrollArea::Canvas => 0,
-            ScrollArea::Page => 1,
-        };
-        let restore = self.restore.as_ref().filter(|r| {
-            r.document == context.document && r.owner == context.scenario && r.pending[index]
-        })?;
+        let restore = self
+            .restore
+            .as_ref()
+            .filter(|r| r.document == context.document && r.owner == context.scenario)?;
         Some(ScrollRestore {
             document: restore.document,
             owner: restore.owner,
             token: restore.token,
-            offset: restore.offsets[index],
+            offset: restore.offset,
         })
     }
     pub(crate) fn restored(
@@ -417,22 +457,12 @@ impl State {
         area: ScrollArea,
         offset: iced::Vector,
     ) -> bool {
-        let index = match area {
-            ScrollArea::Canvas => 0,
-            ScrollArea::Page => 1,
-        };
-        let Some(restore) = self.restore.as_mut().filter(|r| {
-            r.document == context.document
-                && r.owner == context.scenario
-                && r.token == token
-                && r.pending[index]
-        }) else {
+        if !self.restore.as_ref().is_some_and(|r| {
+            r.document == context.document && r.owner == context.scenario && r.token == token
+        }) {
             return false;
-        };
-        restore.pending[index] = false;
-        if !restore.pending.contains(&true) {
-            self.restore = None;
         }
+        self.restore = None;
         self.scrolled(area, offset)
     }
     pub(super) fn recovery_snapshot(&self) -> Result<Option<serde_json::Value>, String> {
@@ -445,28 +475,57 @@ impl State {
 
     pub(super) fn from_recovery(value: serde_json::Value) -> Result<Self, String> {
         let draft = serde_json::from_value(value).map_err(|e| e.to_string())?;
+        let session = Id::new_v4();
         Ok(Self {
             draft: Some(draft),
+            form_session: session,
+            form_mount: session,
+            form_focus_pending: true,
             ..Default::default()
         })
     }
 
-    pub(crate) fn scrolled(&mut self, area: ScrollArea, offset: iced::Vector) -> bool {
+    pub(crate) fn form_session(&self) -> Option<Id> {
+        self.draft.as_ref().map(|_| self.form_session)
+    }
+
+    pub(crate) fn form_mount(&self) -> Option<Id> {
+        self.draft
+            .as_ref()
+            .filter(|d| !d.source.is_open())
+            .map(|_| self.form_mount)
+    }
+
+    pub(crate) fn focus_stamp(&self, context: Context) -> Option<focus::Stamp> {
+        (self.draft.as_ref()?.owner == context.scenario).then_some(focus::Stamp::new(
+            context,
+            self.form_session,
+            self.form_mount()?,
+        ))
+    }
+
+    fn remount_form(&mut self) {
+        self.form_mount = Id::new_v4();
+        self.form_focus_pending = true;
+    }
+
+    pub(crate) fn take_form_focus(&mut self, mount: Id) -> bool {
+        if self.form_mount() == Some(mount) && self.form_focus_pending {
+            self.form_focus_pending = false;
+            true
+        } else {
+            false
+        }
+    }
+
+    pub(crate) fn scrolled(&mut self, ScrollArea::Page: ScrollArea, offset: iced::Vector) -> bool {
         if !offset.x.is_finite() || !offset.y.is_finite() || offset.x < 0. || offset.y < 0. {
             return false;
         }
-        let index = match area {
-            ScrollArea::Canvas => 0,
-            ScrollArea::Page => 1,
-        };
-        let changed = self.scroll_offsets[index] != offset;
-        self.scroll_offsets[index] = offset;
+        let changed = self.details_offset != offset;
+        self.details_offset = offset;
         changed
     }
-    fn scroll_offset(&self) -> iced::Vector {
-        // The former page scroll now belongs to a sibling outline shelf.
-        self.scroll_offsets[0]
-    }
     fn call_choices(&self, p: &Project, context: Context, draft: &Draft) -> Vec<Choice> {
         let key = CallChoiceContext {
             document: context.document,
@@ -616,6 +675,7 @@ impl State {
                 .source
                 .dismiss(&event)?
             {
+                self.remount_form();
                 return Ok(None);
             }
             let d = self
@@ -656,7 +716,11 @@ impl State {
                 next.target = Some(id);
                 next.command(p)?;
             }
+            let returned = d.source.is_open() && !next.source.is_open();
             self.draft = Some(next);
+            if returned {
+                self.remount_form();
+            }
             return Ok(None);
         }
         if self.source_open() && !matches!(&event, Event::Cancel) {
@@ -671,6 +735,9 @@ impl State {
                 if p.elements.get(&owner).map(oa_core::Element::kind) != Some(Kind::Scenario) {
                     return Err("Choose a scenario.".into());
                 }
+                self.form_session = Id::new_v4();
+                self.form_mount = self.form_session;
+                self.form_focus_pending = true;
                 self.draft = Some(Draft {
                     source: Default::default(),
                     invocation: Id::new_v4(),
@@ -1986,20 +2053,31 @@ pub(crate) mod direct_tests {
             navigation_event(&mut app, |ctx| {
                 CanvasEvent::Choose(ctx, CanvasTool::Add(Tool::Reuse))
             });
+            navigation_event(&mut app, |ctx| CanvasEvent::Zoom(ctx, None));
+            let camera_epoch = app.camera_epoch;
             navigation_event(&mut app, |ctx| {
-                CanvasEvent::Scrolled(ctx, ScrollArea::Canvas, iced::Vector::new(25., 170.))
+                CanvasEvent::Camera(
+                    ctx,
+                    camera_epoch,
+                    super::super::canvas_workspace::Event::Pan(iced::Vector::new(25., 170.)),
+                )
             });
             navigation_event(&mut app, |ctx| {
                 CanvasEvent::Scrolled(ctx, ScrollArea::Page, iced::Vector::new(0., 80.))
             });
             navigation_event(&mut app, |ctx| CanvasEvent::OpenUse(ctx, caller));
             assert_eq!(app.selected, b);
-            assert_eq!(app.behavior.scenario.scroll_offset(), iced::Vector::ZERO);
+            assert_eq!(app.behavior.scenario.presentation.pan, iced::Vector::ZERO);
             navigation_event(&mut app, |ctx| {
                 CanvasEvent::Choose(ctx, CanvasTool::Message(MessageStyle::Timer))
             });
+            let camera_epoch = app.camera_epoch;
             navigation_event(&mut app, |ctx| {
-                CanvasEvent::Scrolled(ctx, ScrollArea::Canvas, iced::Vector::new(0., 115.))
+                CanvasEvent::Camera(
+                    ctx,
+                    camera_epoch,
+                    super::super::canvas_workspace::Event::Pan(iced::Vector::new(0., 115.)),
+                )
             });
             navigation_event(&mut app, |ctx| CanvasEvent::OpenUse(ctx, nested));
             assert_eq!(app.selected, c);
@@ -2010,7 +2088,7 @@ pub(crate) mod direct_tests {
                 CanvasTool::Message(MessageStyle::Timer)
             );
             assert_eq!(
-                app.behavior.scenario.scroll_offset(),
+                app.behavior.scenario.presentation.pan,
                 iced::Vector::new(0., 115.)
             );
             navigation_event(&mut app, CanvasEvent::Back);
@@ -2021,11 +2099,11 @@ pub(crate) mod direct_tests {
                 CanvasTool::Add(Tool::Reuse)
             );
             assert_eq!(
-                app.behavior.scenario.scroll_offset(),
+                app.behavior.scenario.presentation.pan,
                 iced::Vector::new(25., 170.)
             );
             assert_eq!(
-                app.behavior.scenario.scroll_offsets[1],
+                app.behavior.scenario.details_offset,
                 iced::Vector::new(0., 80.),
                 "The caller's independent outline scroll is restored separately"
             );
@@ -2203,22 +2281,24 @@ pub(crate) mod direct_tests {
                     let before = app.document.bundle().clone();
                     let mut scene = Scene::sequence(app.project(), f.owner, f.call);
                     scene.interaction = Some((context, CanvasTool::Add(tool), true));
-                    scene.scroll_offset = iced::Vector::new(23., 80.);
-                    let bounds = Rectangle::new(Point::new(20., 40.), scene.size);
+                    scene.camera_pan = iced::Vector::new(23., 80.);
+                    let bounds = Rectangle::new(
+                        Point::new(20., 40.),
+                        Size::new(scene.size.width + 46., scene.size.height + 160.),
+                    );
                     let y = scene.slots.iter().find(|s| s.slot == slot).unwrap().y;
                     let x = if on_lifeline {
                         scene.lanes[&f.sender]
                     } else {
                         scene.size.width - 35.
                     };
-                    let point = Point::new(bounds.x + x, bounds.y + y);
+                    let point = Point::new(bounds.x + x, bounds.y + y) + scene.camera_pan;
+                    assert!(bounds.contains(point));
                     let mut input = SequenceInput::default();
                     canvas_mouse(
                         &scene,
                         &mut input,
-                        mouse::Event::CursorMoved {
-                            position: point - scene.scroll_offset,
-                        },
+                        mouse::Event::CursorMoved { position: point },
                         point,
                         bounds,
                     );
@@ -2394,10 +2474,10 @@ pub(crate) mod direct_tests {
             assert!(!app.behavior.has_pending());
         }
         let old_context = app.scenario_context().unwrap();
-        let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
+        let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Camera(
             old_context,
-            ScrollArea::Canvas,
-            iced::Vector::new(0., 100.),
+            app.camera_epoch,
+            super::super::canvas_workspace::Event::Pan(iced::Vector::new(0., 100.)),
         )));
         let _ = app.update(Message::ScenarioCanvas(event(old_context)));
         assert!(!app.behavior.has_pending());
@@ -2588,26 +2668,29 @@ pub(crate) mod direct_tests {
         );
     }
     #[test]
-    fn direct_busy_save_keeps_observed_scroll_current_for_the_next_pointer_gesture() {
+    fn direct_busy_save_keeps_details_current_and_camera_for_the_next_pointer_gesture() {
         let f = fixture();
         let mut app = App::with_project(f.project.clone());
         let _ = app.update(Message::Select(f.owner));
         let _ = app.update(Message::Page(crate::app::Page::Behavior));
         let context = app.scenario_context().unwrap();
+        let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Camera(
+            context,
+            app.camera_epoch,
+            super::super::canvas_workspace::Event::Pan(iced::Vector::new(-25., -100.)),
+        )));
+        let context = app.scenario_context().unwrap();
         let original = app.document.snapshot();
         app.busy = true;
-        for (area, offset) in [
-            (ScrollArea::Canvas, iced::Vector::new(25., 100.)),
-            (ScrollArea::Page, iced::Vector::new(0., 40.)),
-        ] {
-            let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
-                context, area, offset,
-            )));
-        }
+        let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
+            context,
+            ScrollArea::Page,
+            iced::Vector::new(0., 40.),
+        )));
         assert!(app.busy);
         assert_eq!(
-            app.behavior.scenario.scroll_offset(),
-            iced::Vector::new(25., 100.)
+            app.behavior.scenario.details_offset,
+            iced::Vector::new(0., 40.)
         );
         assert_ne!(
             app.scenario_context(),
@@ -2618,14 +2701,14 @@ pub(crate) mod direct_tests {
         stale.document = Id::new_v4();
         let _ = app.update(Message::ScenarioCanvas(CanvasEvent::Scrolled(
             stale,
-            ScrollArea::Canvas,
+            ScrollArea::Page,
             iced::Vector::new(0., 900.),
         )));
         assert_eq!(
-            app.behavior.scenario.scroll_offset(),
-            iced::Vector::new(25., 100.)
+            app.behavior.scenario.details_offset,
+            iced::Vector::new(0., 40.)
         );
-        let root = std::path::PathBuf::from("scenario-scroll-save-fixture");
+        let root = std::path::PathBuf::from("scenario-details-save-fixture");
         let receipt = crate::app::FileSnapshot {
             document: context.document,
             revision: context.revision,
@@ -2646,12 +2729,17 @@ pub(crate) mod direct_tests {
         let context = app.scenario_context().unwrap();
         let mut scene = Scene::sequence(app.project(), f.owner, f.call);
         scene.interaction = Some((context, CanvasTool::Message(MessageStyle::CallReply), true));
-        scene.scroll_offset = app.behavior.scenario.scroll_offset();
+        assert_eq!(
+            app.behavior.scenario.presentation.pan,
+            iced::Vector::new(-25., -100.)
+        );
+        scene.camera_pan = app.behavior.scenario.presentation.pan;
         let slot = scene.slots.last().unwrap().slot;
         let bounds = Rectangle::new(Point::new(20., 250.), scene.size);
         let y = bounds.y + scene.slots.last().unwrap().y;
-        let a = Point::new(bounds.x + scene.lanes[&f.sender], y) - scene.scroll_offset;
-        let b = Point::new(bounds.x + scene.lanes[&f.receiver], y) - scene.scroll_offset;
+        let a = Point::new(bounds.x + scene.lanes[&f.sender], y) + scene.camera_pan;
+        let b = Point::new(bounds.x + scene.lanes[&f.receiver], y) + scene.camera_pan;
+        assert!(bounds.contains(a) && bounds.contains(b));
         let mut input = super::super::SequenceInput::default();
         let mut published = vec![];
         for event in [
@@ -2665,7 +2753,7 @@ pub(crate) mod direct_tests {
                 &mut input,
                 &canvas::Event::Mouse(event),
                 bounds,
-                mouse::Cursor::Available(b + scene.scroll_offset),
+                mouse::Cursor::Available(b),
             )
             .and_then(|action| action.into_inner().0)
             {

crates/oa-desktop/src/behavior/scenario/focus.rs

@@ -0,0 +1,334 @@
+//! A delayed focus request must still own the live parent tree when executed.
+//! Collect first: a missing target must not unfocus unrelated fields.
+use super::Context;
+use iced::advanced::widget::{Id, Operation, Tree, operation};
+use iced::advanced::{Clipboard, Layout, Shell, Widget, layout, overlay, renderer};
+use iced::{Element, Event, Length, Rectangle, Size, Task, Theme, Vector, mouse};
+use oa_core::Id as ModelId;
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Stamp {
+    document: ModelId,
+    owner: ModelId,
+    revision: u64,
+    session: ModelId,
+    mount: ModelId,
+}
+impl Stamp {
+    pub(crate) fn new(context: Context, session: ModelId, mount: ModelId) -> Self {
+        Self {
+            document: context.document,
+            owner: context.scenario,
+            revision: context.revision,
+            session,
+            mount,
+        }
+    }
+}
+pub(crate) fn name_id(stamp: Stamp) -> Id {
+    Id::from(format!(
+        "{}:{}:{}:{}:{}:{}",
+        super::NAME_INPUT,
+        stamp.document,
+        stamp.owner,
+        stamp.revision,
+        stamp.session,
+        stamp.mount
+    ))
+}
+struct Owner(Option<Stamp>);
+struct Root<'a, Message, R: renderer::Renderer> {
+    content: Element<'a, Message, Theme, R>,
+    owner: Option<Stamp>,
+}
+pub(crate) fn root<'a, Message: 'a, R: renderer::Renderer + 'a>(
+    content: impl Into<Element<'a, Message, Theme, R>>,
+    owner: Option<Stamp>,
+) -> Element<'a, Message, Theme, R> {
+    Element::new(Root {
+        content: content.into(),
+        owner,
+    })
+}
+impl<Message, R: renderer::Renderer> Widget<Message, Theme, R> for Root<'_, Message, R> {
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+    fn diff(&self, tree: &mut Tree) {
+        tree.diff_children(std::slice::from_ref(&self.content));
+    }
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        op: &mut dyn Operation,
+    ) {
+        // This is computed from the current App view, never retained widget state.
+        op.custom(None, layout.bounds(), &mut Owner(self.owner));
+        self.content
+            .as_widget_mut()
+            .operate(&mut tree.children[0], layout, renderer, op);
+    }
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            style,
+            layout,
+            cursor,
+            viewport,
+        );
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        self.content.as_widget().mouse_interaction(
+            &tree.children[0],
+            layout,
+            cursor,
+            viewport,
+            renderer,
+        )
+    }
+    fn overlay<'b>(
+        &'b mut self,
+        tree: &'b mut Tree,
+        layout: Layout<'b>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'b, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}
+
+#[derive(Clone)]
+struct Scroll {
+    index: usize,
+    bounds: Rectangle,
+    capacity: Vector,
+    offset: Vector,
+}
+struct Collect {
+    stamp: Stamp,
+    valid: bool,
+    translation: Vector,
+    scrolls: Vec<Scroll>,
+    pending: Option<Scroll>,
+    index: usize,
+    target: Option<(Rectangle, Vec<Scroll>)>,
+}
+pub(crate) fn task<Message: Send + 'static>(stamp: Stamp) -> Task<Message> {
+    iced::advanced::widget::operate(Collect {
+        stamp,
+        valid: false,
+        translation: Vector::ZERO,
+        scrolls: vec![],
+        pending: None,
+        index: 0,
+        target: None,
+    })
+    .discard()
+}
+impl Operation for Collect {
+    fn custom(&mut self, _: Option<&Id>, _: Rectangle, state: &mut dyn std::any::Any) {
+        if let Some(owner) = state.downcast_ref::<Owner>() {
+            self.valid = owner.0 == Some(self.stamp);
+        }
+    }
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        let previous = (self.translation, self.scrolls.len());
+        if let Some(scroll) = self.pending.take() {
+            self.translation += scroll.offset;
+            self.scrolls.push(scroll);
+        }
+        visit(self);
+        self.translation = previous.0;
+        self.scrolls.truncate(previous.1);
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&Id>,
+        bounds: Rectangle,
+        content: Rectangle,
+        offset: Vector,
+        _: &mut dyn operation::Scrollable,
+    ) {
+        self.pending = Some(Scroll {
+            index: self.index,
+            bounds: translated(bounds, self.translation),
+            capacity: Vector::new(
+                (content.width - bounds.width).max(0.),
+                (content.height - bounds.height).max(0.),
+            ),
+            offset,
+        });
+        self.index += 1;
+    }
+    fn focusable(&mut self, id: Option<&Id>, bounds: Rectangle, _: &mut dyn operation::Focusable) {
+        if id == Some(&name_id(self.stamp)) {
+            self.target = Some((translated(bounds, self.translation), self.scrolls.clone()));
+        }
+    }
+    fn finish(&self) -> operation::Outcome<()> {
+        if !self.valid {
+            return operation::Outcome::None;
+        }
+        let Some((mut bounds, ancestors)) = self.target.clone() else {
+            return operation::Outcome::None;
+        };
+        let mut shifts = BTreeMap::new();
+        for ancestor in ancestors.iter().rev() {
+            let dx = reveal(
+                bounds.x,
+                bounds.width,
+                ancestor.bounds.x,
+                ancestor.bounds.width,
+            );
+            let dy = reveal(
+                bounds.y,
+                bounds.height,
+                ancestor.bounds.y,
+                ancestor.bounds.height,
+            );
+            // Drawing offsets are rounded; an already-visible axis must not
+            // acquire a scroll delta from a fractional capacity alone.
+            let delta = Vector::new(
+                if dx == 0. {
+                    0.
+                } else {
+                    (ancestor.offset.x + dx).clamp(0., ancestor.capacity.x) - ancestor.offset.x
+                },
+                if dy == 0. {
+                    0.
+                } else {
+                    (ancestor.offset.y + dy).clamp(0., ancestor.capacity.y) - ancestor.offset.y
+                },
+            );
+            if delta != Vector::ZERO {
+                shifts.insert(ancestor.index, delta);
+            }
+            bounds = translated(bounds, delta);
+        }
+        operation::Outcome::Chain(Box::new(Apply {
+            stamp: self.stamp,
+            valid: false,
+            shifts,
+            index: 0,
+        }))
+    }
+}
+fn translated(bounds: Rectangle, delta: Vector) -> Rectangle {
+    Rectangle {
+        x: bounds.x - delta.x,
+        y: bounds.y - delta.y,
+        ..bounds
+    }
+}
+fn reveal(start: f32, length: f32, viewport: f32, size: f32) -> f32 {
+    if start < viewport || length > size {
+        start - viewport
+    } else {
+        (start + length - viewport - size).max(0.)
+    }
+}
+struct Apply {
+    stamp: Stamp,
+    valid: bool,
+    shifts: BTreeMap<usize, Vector>,
+    index: usize,
+}
+impl Operation for Apply {
+    fn custom(&mut self, _: Option<&Id>, _: Rectangle, state: &mut dyn std::any::Any) {
+        if let Some(owner) = state.downcast_ref::<Owner>() {
+            self.valid = owner.0 == Some(self.stamp);
+        }
+    }
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        visit(self);
+    }
+    fn focusable(&mut self, id: Option<&Id>, _: Rectangle, state: &mut dyn operation::Focusable) {
+        if self.valid {
+            if id == Some(&name_id(self.stamp)) {
+                state.focus();
+            } else {
+                state.unfocus();
+            }
+        }
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&Id>,
+        bounds: Rectangle,
+        content: Rectangle,
+        _: Vector,
+        state: &mut dyn operation::Scrollable,
+    ) {
+        if self.valid
+            && let Some(delta) = self.shifts.get(&self.index)
+        {
+            state.scroll_by(
+                operation::scrollable::AbsoluteOffset {
+                    x: delta.x,
+                    y: delta.y,
+                },
+                bounds,
+                content,
+            );
+        }
+        self.index += 1;
+    }
+}

crates/oa-desktop/src/behavior/scenario/usage.rs

@@ -0,0 +1,207 @@
+//! Navigation is derived from the same opaque-reference scene that is painted.
+use super::*;
+use crate::diagram_usage::{Surface, Target, Usage};
+
+/// The renderer collapses whitespace before shortening. Require at least one
+/// actual character of this field, rather than an ellipsis at its start.
+fn label_field_visible(full: &str, prefix: &str, value: &str) -> bool {
+    if value.trim().is_empty() {
+        return false;
+    }
+    let normalized = full.split_whitespace().collect::<Vec<_>>().join(" ");
+    let normalized_prefix = prefix.split_whitespace().collect::<Vec<_>>().join(" ");
+    let start = normalized_prefix.len()
+        + usize::from(prefix.ends_with(char::is_whitespace) && !normalized_prefix.is_empty());
+    let painted = crate::views::short(full, 32);
+    let retained = normalized
+        .chars()
+        .zip(painted.chars())
+        .take_while(|(a, b)| a == b)
+        .map(|(c, _)| c.len_utf8())
+        .sum::<usize>();
+    start < retained
+}
+
+fn usages(p: &Project, owner: Id, subject: Id, scene: &Scene) -> Vec<Usage> {
+    let mut result = Vec::new();
+    let mut add = |id, bounds, role: &str| {
+        // Activation bars share the occurrence identity with a labelled message;
+        // they must not inflate its target count.
+        if !result
+            .iter()
+            .any(|u: &Usage| u.target == Target::ScenarioObject(id))
+        {
+            result.push(Usage {
+                subject,
+                surface: Surface::Scenario(owner),
+                target: Target::ScenarioObject(id),
+                role: role.into(),
+                bounds,
+            });
+        }
+    };
+    for item in scene.boxes.iter().filter(|item| !item.title.is_empty()) {
+        let Some(element) = p.elements.get(&item.id) else {
+            continue;
+        };
+        if subject == item.id {
+            // A fragment's selectable header is useful even when its frame is
+            // much larger than the viewport.
+            let mut bounds = item.rect;
+            if item.marker == Some(Kind::Occurrence) {
+                bounds.height = bounds.height.min(38.);
+            }
+            add(item.id, bounds, "scenario object");
+        }
+        let represented = match element.shared() {
+            Some(SharedBody::Lifeline { represented }) => represented.map(|id| (id, "lifeline")),
+            Some(SharedBody::Occurrence { body, .. }) => match body {
+                OccurrenceBody::Action { action, .. } => action.map(|id| (id, "action occurrence")),
+                OccurrenceBody::State { state, .. } => state.map(|id| (id, "state observation")),
+                OccurrenceBody::SequenceReference { sequence } => {
+                    sequence.map(|id| (id, "process reference"))
+                }
+                OccurrenceBody::ScenarioUse { scenario, .. } => {
+                    scenario.map(|id| (id, "scenario reference"))
+                }
+                // An incomplete message fallback box only paints the occurrence
+                // name and a repair hint, not its exchange or operation.
+                _ => None,
+            },
+            _ => None,
+        };
+        if let Some((id, role)) = represented.filter(|(id, _)| *id == subject) {
+            let _ = id;
+            add(item.id, item.rect, role);
+        }
+    }
+    for line in scene.lines.iter().filter(|line| !line.label.is_empty()) {
+        let Some(element) = p.elements.get(&line.id) else {
+            continue;
+        };
+        let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange { exchange, .. },
+            ..
+        }) = element.shared()
+        else {
+            continue;
+        };
+        let bounds = line.label_bounds();
+        if subject == line.id || *exchange == Some(subject) {
+            add(line.id, bounds, "message occurrence");
+        }
+        // Replies derive their operation from the exact call, matching the
+        // operation label formatter rather than scanning raw reference fields.
+        if let Ok(operations::OperationResolution::Selected(operation)) =
+            operations::resolve(p, line.id)
+            && let Some(label) = crate::data_values::operation_label(p, element)
+            && let Some(prefix) = line.label.strip_suffix(&label)
+        {
+            let allocation = &p.relations[&operation.allocation];
+            let operation_prefix = if matches!(
+                element.shared(),
+                Some(SharedBody::Occurrence {
+                    body: OccurrenceBody::Exchange {
+                        message_kind: MessageKind::Reply,
+                        ..
+                    },
+                    ..
+                })
+            ) {
+                "Reply operation from Call: "
+            } else {
+                "Operation: "
+            };
+            let fields = [
+                (allocation.source(), format!("{prefix}{operation_prefix}")),
+                (
+                    allocation.target(),
+                    format!(
+                        "{prefix}{operation_prefix}{} / ",
+                        p.named(allocation.source())
+                    ),
+                ),
+                (
+                    allocation.id,
+                    format!(
+                        "{prefix}{operation_prefix}{} / {} · ",
+                        p.named(allocation.source()),
+                        p.named(allocation.target())
+                    ),
+                ),
+            ];
+            for (id, prefix) in fields {
+                if id == subject && label_field_visible(&line.label, &prefix, p.named(id)) {
+                    add(line.id, bounds, "operation label");
+                }
+            }
+        }
+    }
+    if subject == owner {
+        result.insert(
+            0,
+            Usage {
+                subject,
+                surface: Surface::Scenario(owner),
+                target: Target::Whole,
+                role: "scenario".into(),
+                bounds: Rectangle::new(Point::ORIGIN, scene.size),
+            },
+        );
+    }
+    result
+}
+
+impl State {
+    pub(crate) fn diagram_usages(&self, p: &Project, owner: Id, subject: Id) -> Vec<Usage> {
+        if !p
+            .elements
+            .get(&owner)
+            .is_some_and(|e| e.kind() == Kind::Scenario)
+        {
+            return vec![];
+        }
+        usages(p, owner, subject, &Scene::sequence(p, owner, subject))
+    }
+
+    pub(crate) fn reveal_usage(
+        &mut self,
+        p: &Project,
+        document: Id,
+        owner: Id,
+        target: &Target,
+    ) -> bool {
+        if self.draft.is_some()
+            || !p
+                .elements
+                .get(&owner)
+                .is_some_and(|e| e.kind() == Kind::Scenario)
+        {
+            return false;
+        }
+        let id = match target {
+            Target::Whole => owner,
+            Target::ScenarioObject(id) => *id,
+            _ => return false,
+        };
+        let Some(usage) = self
+            .diagram_usages(p, owner, id)
+            .into_iter()
+            .find(|u| &u.target == target)
+        else {
+            return false;
+        };
+        // Preserve an existing mounted viewport across enter's owner reset.
+        let viewport = self.presentation.viewport.unwrap_or(Size::new(500., 300.));
+        self.enter(document, owner);
+        self.presentation.viewport = Some(viewport);
+        self.canvas_tool = Some((owner, CanvasTool::Select));
+        let (zoom, pan) = crate::diagram_usage::camera_for(target, usage.bounds, viewport);
+        self.presentation.zoom(Some(zoom));
+        self.presentation.pan = pan;
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior/scenario/usage/tests.rs

@@ -0,0 +1,276 @@
+use super::*;
+
+fn add_occurrence(p: &mut Project, owner: Id, name: &str, body: OccurrenceBody) -> Id {
+    let layer = p.elements[&owner].layer();
+    let id = p
+        .add_element(Kind::Occurrence, layer, name, Some(owner))
+        .unwrap();
+    *p.elements.get_mut(&id).unwrap().shared_mut().unwrap() = SharedBody::Occurrence {
+        body,
+        precondition: String::new(),
+        postcondition: String::new(),
+    };
+    if let Some(steps) = p.elements.get_mut(&owner).unwrap().steps_mut() {
+        if !steps.contains(&id) {
+            steps.push(id);
+        }
+    }
+    id
+}
+
+fn targets(state: &State, p: &Project, owner: Id, subject: Id) -> BTreeSet<Id> {
+    state
+        .diagram_usages(p, owner, subject)
+        .into_iter()
+        .filter_map(|u| match u.target {
+            Target::ScenarioObject(id) => Some(id),
+            _ => None,
+        })
+        .collect()
+}
+
+#[test]
+fn scenario_usage_counts_nested_occurrences_and_lifelines_but_keeps_reuse_opaque() {
+    for (layer, work_kind, participant_kind) in [
+        (Layer::Oa, Kind::Activity, Kind::Entity),
+        (Layer::Sa, Kind::Function, Kind::SystemActor),
+    ] {
+        let mut p = Project::empty();
+        let owner = p
+            .add_element(Kind::Scenario, layer, "Caller", None)
+            .unwrap();
+        let other = p
+            .add_element(Kind::Scenario, layer, "Definition", None)
+            .unwrap();
+        let work = p.add_element(work_kind, layer, "Respond", None).unwrap();
+        let unused = p.add_element(work_kind, layer, "Respond", None).unwrap();
+        let participant = p
+            .add_element(participant_kind, layer, "Operator", None)
+            .unwrap();
+        let lanes = ["First role", "Second role"].map(|name| {
+            let id = p
+                .add_element(Kind::Lifeline, layer, name, Some(owner))
+                .unwrap();
+            *p.elements.get_mut(&id).unwrap().shared_mut().unwrap() = SharedBody::Lifeline {
+                represented: Some(participant),
+            };
+            id
+        });
+        let first = add_occurrence(
+            &mut p,
+            owner,
+            "First action",
+            OccurrenceBody::Action {
+                action: Some(work),
+                lifeline: Some(lanes[0]),
+            },
+        );
+        let fragment = add_occurrence(
+            &mut p,
+            owner,
+            "Decision",
+            OccurrenceBody::Fragment {
+                operator: FragmentOperator::Alternative,
+                branches: vec![],
+            },
+        );
+        let branch = add_occurrence(
+            &mut p,
+            fragment,
+            "When ready",
+            OccurrenceBody::Branch {
+                guard: "ready".into(),
+                occurrences: vec![],
+            },
+        );
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Fragment { branches, .. },
+            ..
+        }) = p.elements.get_mut(&fragment).unwrap().shared_mut()
+        {
+            branches.push(branch);
+        }
+        let nested = add_occurrence(
+            &mut p,
+            branch,
+            "Again",
+            OccurrenceBody::Action {
+                action: Some(work),
+                lifeline: Some(lanes[1]),
+            },
+        );
+        let inside = add_occurrence(
+            &mut p,
+            other,
+            "Hidden inside definition",
+            OccurrenceBody::Action {
+                action: Some(unused),
+                lifeline: None,
+            },
+        );
+        let use_a = add_occurrence(
+            &mut p,
+            owner,
+            "Use A",
+            OccurrenceBody::ScenarioUse {
+                scenario: Some(other),
+                bindings: vec![],
+            },
+        );
+        let use_b = add_occurrence(
+            &mut p,
+            owner,
+            "Use B",
+            OccurrenceBody::ScenarioUse {
+                scenario: Some(other),
+                bindings: vec![],
+            },
+        );
+        let before = p.clone();
+        let state = State::default();
+        assert_eq!(
+            targets(&state, &p, owner, work),
+            BTreeSet::from([first, nested])
+        );
+        assert_eq!(
+            targets(&state, &p, owner, participant),
+            BTreeSet::from(lanes)
+        );
+        assert_eq!(
+            targets(&state, &p, owner, other),
+            BTreeSet::from([use_a, use_b])
+        );
+        assert!(targets(&state, &p, owner, unused).is_empty());
+        assert!(targets(&state, &p, owner, inside).is_empty());
+        assert_eq!(targets(&state, &p, owner, branch), BTreeSet::from([branch]));
+        assert_eq!(
+            state.diagram_usages(&p, owner, owner)[0].target,
+            Target::Whole
+        );
+        assert_eq!(p, before);
+    }
+}
+
+#[test]
+fn scenario_usage_keeps_repeated_messages_and_reveal_is_read_only_and_revalidated() {
+    let f = super::super::direct_tests::fixture();
+    let mut p = f.project;
+    let mut state = State::default();
+    assert_eq!(
+        targets(&state, &p, f.owner, f.exchange),
+        BTreeSet::from([f.call, f.reply])
+    );
+    let before = p.clone();
+    let target = Target::ScenarioObject(f.reply);
+    state.viewport(Size::new(900., 500.));
+    assert!(state.reveal_usage(&p, Id::new_v4(), f.owner, &target));
+    let usage = state
+        .diagram_usages(&p, f.owner, f.reply)
+        .into_iter()
+        .find(|u| u.target == target)
+        .unwrap();
+    let zoom = state
+        .presentation
+        .scale(Scene::sequence(&p, f.owner, f.reply).size);
+    let centered = Point::new(
+        usage.bounds.center_x() * zoom,
+        usage.bounds.center_y() * zoom,
+    ) + state.presentation.pan;
+    assert!((centered.x - 450.).abs() < 0.01 && (centered.y - 250.).abs() < 0.01);
+    assert!(zoom >= 0.5);
+    assert_eq!(p, before);
+    // Keeping an orphan semantic occurrence does not keep its painted target.
+    p.elements
+        .get_mut(&f.owner)
+        .unwrap()
+        .steps_mut()
+        .unwrap()
+        .retain(|id| *id != f.reply);
+    let camera = state.camera_boundary();
+    assert!(!state.reveal_usage(&p, Id::new_v4(), f.owner, &target));
+    assert!(camera == state.camera_boundary());
+    assert!(!state.reveal_usage(&p, Id::new_v4(), f.owner, &Target::Edge(f.exchange)));
+    // A message whose endpoints are incomplete paints only its repair box.
+    if let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange { receiver, .. },
+        ..
+    }) = p.elements.get_mut(&f.call).unwrap().shared_mut()
+    {
+        *receiver = None;
+    }
+    assert!(targets(&state, &p, f.owner, f.exchange).is_empty());
+    assert_eq!(
+        targets(&state, &p, f.owner, f.call),
+        BTreeSet::from([f.call])
+    );
+}
+
+#[test]
+fn scenario_operation_label_membership_excludes_ellipsis_only_and_normalizes_whitespace() {
+    assert!(label_field_visible(
+        "1. call · X · Operation: I / O",
+        "1. call · X · Operation: ",
+        "I"
+    ));
+    assert!(!label_field_visible(
+        "1234567890123456789012345678901Ixyz",
+        "1234567890123456789012345678901",
+        "Ixyz"
+    ));
+    assert!(!label_field_visible(
+        "A very long occurrence label · Operation: I",
+        "A very long occurrence label · Operation: ",
+        "I"
+    ));
+    assert!(label_field_visible(
+        "call\n\t· Operation: 界",
+        "call\n\t· Operation: ",
+        "界"
+    ));
+    assert!(!label_field_visible("Operation: ", "Operation: ", ""));
+}
+
+#[test]
+fn scenario_usage_only_reports_the_resolved_operation_fields_actually_in_the_label() {
+    let mut p = persistence::decode(include_bytes!(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../../harness/fixtures/interface-operation-probe/output/boundary-only.json"
+    )))
+    .unwrap();
+    let id = |n| Id::parse_str(&format!("52060906-0000-4000-8000-{n:012x}")).unwrap();
+    let (owner, call, exchange, allocation) = (id(40), id(43), id(34), id(30));
+    let (interface, item) = (
+        p.relations[&allocation].source(),
+        p.relations[&allocation].target(),
+    );
+    for (id, name) in [(call, "x"), (interface, "I"), (item, "O")] {
+        p.elements.get_mut(&id).unwrap().name = name.into();
+    }
+    p.relations.get_mut(&exchange).unwrap().name = "x".into();
+    p.relations.get_mut(&allocation).unwrap().name = "A".into();
+    if let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange { operation, .. },
+        ..
+    }) = p.elements.get_mut(&call).unwrap().shared_mut()
+    {
+        *operation = Some(OperationUse {
+            allocation: Some(allocation),
+        });
+    }
+    assert!(matches!(
+        operations::resolve(&p, call),
+        Ok(operations::OperationResolution::Selected(_))
+    ));
+    let state = State::default();
+    let before = p.clone();
+    assert_eq!(
+        targets(&state, &p, owner, interface),
+        BTreeSet::from([call])
+    );
+    assert_eq!(targets(&state, &p, owner, item), BTreeSet::from([call]));
+    assert!(targets(&state, &p, owner, allocation).is_empty());
+    assert_eq!(p, before);
+    p.elements.get_mut(&call).unwrap().name = "This occurrence has a deliberately long name".into();
+    assert!(targets(&state, &p, owner, interface).is_empty());
+    assert!(targets(&state, &p, owner, item).is_empty());
+}

crates/oa-desktop/src/behavior/scenario/workspace.rs

@@ -1,11 +1,12 @@
 //! Scenario presentation. Layout/camera controls never construct model commands.
-use super::super::scenario_scroll;
+use super::super::{form_session, scenario_scroll};
 use super::*;
 use iced::widget::{Space, column, sensor};
 
+pub(crate) const NAME_INPUT: &str = "scenario-form-name";
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Shelf {
-    Tools,
     Selection,
 }
 
@@ -15,6 +16,7 @@ pub(super) struct Presentation {
     pub(super) viewport: Option<Size>,
     pub(super) focused: bool,
     pub(super) shelf: Option<Shelf>,
+    pub(super) pan: iced::Vector,
     pub(super) zoom: Option<f32>,
     pub(super) fit: bool,
 }
@@ -44,23 +46,19 @@ impl Presentation {
     }
     fn fit_scale(&self, scene: Size) -> Option<f32> {
         let viewport = self.viewport?;
-        // This is the measured inner Scrollable, never a window-height estimate.
-        // Leave room for the overlay scrollbars on both axes.
+        // Fit uses the actual mounted viewport with a small visual gutter.
         Some(
             ((viewport.width - 16.).max(1.) / scene.width.max(1.))
                 .min((viewport.height - 16.).max(1.) / scene.height.max(1.)),
         )
     }
-    fn scale(&self, scene: Size) -> f32 {
+    pub(super) fn scale(&self, scene: Size) -> f32 {
         if self.fit {
             self.fit_scale(scene).unwrap_or(1.).clamp(MIN_SCALE, 1.)
         } else {
             self.zoom.unwrap_or(1.)
         }
     }
-    fn fit_limited(&self, scene: Size) -> bool {
-        self.fit && self.fit_scale(scene).is_some_and(|scale| scale < MIN_SCALE)
-    }
 }
 
 pub fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Element<'a, Message> {
@@ -76,249 +74,188 @@ pub fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Element<'a
     let clean = !app.behavior.has_pending() && !app.draft_dirty() && !app.source_dirty();
     let mut scene = Scene::sequence(p, owner, app.selected);
     let scale = presentation.scale(scene.size);
-    let limited = presentation.fit_limited(scene.size);
     scene.scale = scale;
+    scene.camera_pan = presentation.pan;
     scene.interaction = Some((context, tool, clean));
-    // The outline is a sibling shelf, not an ancestor of this canvas.
-    scene.scroll_offset = state.scroll_offset();
     scene.pending_placement = state.pending_placement(owner);
-    let size = Size::new(scene.size.width * scale, scene.size.height * scale);
-    let canvas = canvas_pane(
-        context,
-        state.scroll_restore(context, ScrollArea::Canvas),
-        canvas::Canvas::new(scene)
-            .width(size.width)
-            .height(size.height)
-            .into(),
-    );
+    let scope = super::super::canvas_workspace::Scope {
+        document: context.document,
+        owner,
+        revision: context.revision,
+        epoch: app.camera_epoch,
+    };
+    let keyboard = clean && super::super::canvas_workspace::keyboard_enabled(app);
+    let camera = move |e| Message::ScenarioCanvas(CanvasEvent::Camera(context, scope.epoch, e));
+    let canvas = container(
+        sensor(
+            super::super::canvas_workspace::Viewport::new(
+                canvas::Canvas::new(scene).width(Fill).height(Fill),
+                scope,
+                scale,
+                keyboard,
+                camera,
+            )
+            .pan_background(tool == CanvasTool::Select),
+        )
+        .key((context.document, owner))
+        .on_show(move |size| Message::ScenarioCanvas(CanvasEvent::Viewport(context, size)))
+        .on_resize(move |size| Message::ScenarioCanvas(CanvasEvent::Viewport(context, size))),
+    )
+    .id("scenario-viewport")
+    .width(Fill)
+    .height(Fill)
+    .style(style::card)
+    .into();
     let mut navigation = row![
         out.width(Fill),
-        button(
-            text(if presentation.focused {
-                "Restore panels"
-            } else {
-                "Focus canvas"
-            })
-            .size(12)
+        super::super::canvas_workspace::Control::new(
+            button(
+                text(if presentation.focused {
+                    "Restore panels"
+                } else {
+                    "Focus canvas"
+                })
+                .size(12)
+            )
+            .padding(6)
+            .on_press(super::super::canvas_workspace::intent(
+                scope,
+                "Panels",
+                Message::ScenarioCanvas(CanvasEvent::Focus(context))
+            )),
+            scope,
+            "Panels",
+            keyboard,
+            Some(super::super::canvas_workspace::intent(
+                scope,
+                "Panels",
+                Message::ScenarioCanvas(CanvasEvent::Focus(context))
+            )),
+            camera
         )
-        .padding(6)
-        .on_press(Message::ScenarioCanvas(CanvasEvent::Focus(context)))
-    ]
-    .spacing(6)
-    .align_y(iced::Center);
-    if state.can_back(p, context) {
-        navigation = navigation.push(
-            button(text("Back to caller").size(12))
-                .padding(6)
-                .on_press_maybe(
-                    clean.then_some(Message::ScenarioCanvas(CanvasEvent::Back(context))),
-                ),
-        );
-    }
-    let mut header = column![
-        navigation,
-        row![
-            button(text("Tools").size(12))
-                .padding(6)
-                .style(if presentation.shelf == Some(Shelf::Tools) {
-                    button::primary
-                } else {
-                    style::nav
-                })
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Shelf(
-                    context,
-                    Shelf::Tools
-                ))),
-            button(text("Selection").size(12))
-                .padding(6)
-                .style(if presentation.shelf == Some(Shelf::Selection) {
-                    button::primary
-                } else {
-                    style::nav
-                })
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Shelf(
-                    context,
-                    Shelf::Selection
-                ))),
-            button(text("Fit overview").size(12))
-                .padding(6)
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Zoom(context, None))),
-            button(text("−").size(12))
-                .padding(6)
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Zoom(
-                    context,
-                    Some(scale / 1.25)
-                ))),
-            text(format!("{:.0}%", scale * 100.)).size(12),
-            button(text("+").size(12))
-                .padding(6)
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Zoom(
-                    context,
-                    Some(scale * 1.25)
-                ))),
-            button(text("100%").size(12))
-                .padding(6)
-                .on_press(Message::ScenarioCanvas(CanvasEvent::Zoom(
-                    context,
-                    Some(1.)
-                )))
-        ]
-        .spacing(6)
-        .align_y(iced::Center)
-        .wrap(),
-        text(if pending {
-            "Pending form · the highlighted sequence position is retained".to_owned()
-        } else if !p.children(owner).any(|e| e.kind() == Kind::Lifeline) {
-            "Start with a lifeline representing existing or explicitly new work / participants."
-                .into()
-        } else if !p.children(owner).any(|e| e.kind() == Kind::Occurrence) {
-            "Choose a first message, action or another tool; no occurrence is selected yet.".into()
-        } else {
-            let guidance = match tool {
-                CanvasTool::Message(_) => {
-                    "Click a source position, then click or drag to a target · Esc cancels"
-                }
-                CanvasTool::Add(Tool::Action | Tool::Observation) => {
-                    "Click a highlighted position · a lifeline click preselects that lifeline"
-                }
-                CanvasTool::Add(Tool::Reuse | Tool::Fragment) => {
-                    "Click a highlighted sequence position to open its form"
-                }
-                _ => "Select a lifeline or occurrence · drag its ↕ handle to reorder",
-            };
-            format!("{tool} · {guidance}")
-        })
-        .size(11)
     ]
     .spacing(6);
-    if !pending {
-        if !p.children(owner).any(|e| e.kind() == Kind::Lifeline) {
-            header = header.push(
-                row![
-                    text(format!("No lifelines · {:?}", viewpoint(p, owner))).size(12),
-                    button("Add first lifeline").on_press_maybe(clean.then_some({
-                        Message::ScenarioCanvas(CanvasEvent::First(context, Tool::Lifeline))
-                    }))
-                ]
-                .spacing(8),
-            );
-        } else if !p.children(owner).any(|e| e.kind() == Kind::Occurrence) {
-            header = header.push(
-                row![
-                    text("No occurrences yet").size(12),
-                    button("Add first message").on_press_maybe(clean.then_some({
-                        Message::ScenarioCanvas(CanvasEvent::First(context, Tool::Message))
-                    })),
-                    button("Add first action").on_press_maybe(clean.then_some({
-                        Message::ScenarioCanvas(CanvasEvent::First(context, Tool::Action))
-                    }))
-                ]
-                .spacing(8),
-            );
-        }
+    if state.can_back(p, context) {
+        navigation =
+            navigation.push(button(text("Back").size(12)).padding(6).on_press_maybe(
+                clean.then_some(Message::ScenarioCanvas(CanvasEvent::Back(context))),
+            ));
     }
-    if limited {
-        header = header
-            .push(text("Minimum zoom reached · scroll to see the remaining scenario.").size(11));
+    let header = column![
+        navigation,
+        super::super::canvas_workspace::controls(
+            scope,
+            keyboard,
+            scale,
+            Message::ScenarioCanvas(CanvasEvent::Shelf(context, Shelf::Selection)),
+            clean.then_some(Message::ScenarioCanvas(CanvasEvent::Camera(
+                context,
+                scope.epoch,
+                super::super::canvas_workspace::Event::Focus
+            ))),
+            move |zoom| Message::ScenarioCanvas(CanvasEvent::Zoom(context, zoom)),
+            camera
+        )
+    ]
+    .spacing(4);
+    let entries = [
+        ("S", "Select / reorder occurrences", CanvasTool::Select),
+        (
+            "L",
+            "Lifeline: click to choose represented work or participant",
+            CanvasTool::Add(Tool::Lifeline),
+        ),
+        (
+            "C/R",
+            "Call and correlated reply",
+            CanvasTool::Message(MessageStyle::CallReply),
+        ),
+        (
+            "M",
+            "Asynchronous message",
+            CanvasTool::Message(MessageStyle::Asynchronous),
+        ),
+        (
+            "C",
+            "Synchronous call",
+            CanvasTool::Message(MessageStyle::Call),
+        ),
+        (
+            "R",
+            "Reply to existing call",
+            CanvasTool::Message(MessageStyle::Reply),
+        ),
+        (
+            "+L",
+            "Create participant",
+            CanvasTool::Message(MessageStyle::Create),
+        ),
+        (
+            "-L",
+            "Delete participant",
+            CanvasTool::Message(MessageStyle::Delete),
+        ),
+        ("T", "Local timer", CanvasTool::Message(MessageStyle::Timer)),
+        (
+            "A",
+            "Action: click a sequence position",
+            CanvasTool::Add(Tool::Action),
+        ),
+        (
+            "St",
+            "State observation: click a sequence position",
+            CanvasTool::Add(Tool::Observation),
+        ),
+        (
+            "ref",
+            "Reuse scenario: click a sequence position",
+            CanvasTool::Add(Tool::Reuse),
+        ),
+        (
+            "alt",
+            "Fragment: click a sequence position",
+            CanvasTool::Add(Tool::Fragment),
+        ),
+    ];
+    let palette = super::super::canvas_workspace::palette(
+        scope,
+        keyboard,
+        camera,
+        entries.into_iter().map(|(glyph, label, choice)| {
+            (
+                glyph,
+                label,
+                choice == tool,
+                clean.then_some(Message::ScenarioCanvas(CanvasEvent::Choose(
+                    context, choice,
+                ))),
+            )
+        }),
+    );
+    let mut details = column![
+        text(format!("Selected: {}", p.named(app.selected))).size(12),
+        button(text("Properties").size(12))
+            .on_press_maybe(clean.then_some(Message::EditProperties(app.selected)))
+    ]
+    .spacing(6);
+    if referenced_scenario(p, owner, app.selected).is_some() {
+        details = details.push(button(text("Open definition").size(12)).on_press_maybe(
+            clean.then_some(Message::ScenarioCanvas(CanvasEvent::OpenUse(
+                context,
+                app.selected,
+            ))),
+        ));
     }
-    let details = match presentation.shelf {
-        Some(Shelf::Tools) => {
-            let choose = move |tool| Message::ScenarioCanvas(CanvasEvent::Choose(context, tool));
-            let tool_picker: Element<'_, Message> = if clean {
-                pick_list(
-                    vec![
-                        CanvasTool::Select,
-                        CanvasTool::Message(MessageStyle::CallReply),
-                        CanvasTool::Message(MessageStyle::Asynchronous),
-                        CanvasTool::Message(MessageStyle::Call),
-                        CanvasTool::Message(MessageStyle::Reply),
-                        CanvasTool::Message(MessageStyle::Create),
-                        CanvasTool::Message(MessageStyle::Delete),
-                        CanvasTool::Message(MessageStyle::Timer),
-                        CanvasTool::Add(Tool::Action),
-                        CanvasTool::Add(Tool::Observation),
-                        CanvasTool::Add(Tool::Reuse),
-                        CanvasTool::Add(Tool::Fragment),
-                    ],
-                    Some(tool),
-                    choose,
-                )
-                .text_size(12)
-                .padding(6)
-                .width(Fill)
-                .into()
-            } else {
-                button(text(format!("{tool} · finish pending edits to change tools")).size(12))
-                    .padding(6)
-                    .width(Fill)
-                    .into()
-            };
-            column![
-                tool_picker,
-                row![
-                    button(text("+ Lifeline").size(12))
-                        .padding(6)
-                        .on_press_maybe(
-                            clean.then_some(event(Event::Start(owner, Tool::Lifeline)))
-                        ),
-                    button(text("Scenario properties").size(12))
-                        .padding(6)
-                        .on_press_maybe(clean.then_some(Message::EditProperties(owner))),
-                ]
-                .spacing(6)
-                .wrap(),
-                text(match viewpoint(p, owner) {
-                    ScenarioViewpoint::OperationalActivity =>
-                        "Activity scenario · lifelines represent activities",
-                    ScenarioViewpoint::Functional =>
-                        "Functional scenario · lifelines represent system functions",
-                    ScenarioViewpoint::ParticipantInteraction =>
-                        "Participant scenario · entities, actors or roles",
-                    ScenarioViewpoint::BoundaryInterface =>
-                        "Interface scenario · system and external actors",
-                    ScenarioViewpoint::MixedLegacy => "Mixed scenario · work or participants",
-                })
-                .size(11),
-            ]
-            .spacing(6)
-        }
-        _ => {
-            let mut details =
-                column![text(format!("Selected: {}", p.named(app.selected))).size(12)].spacing(6);
-            let mut navigation = row![].spacing(6);
-            if referenced_scenario(p, owner, app.selected).is_some() {
-                navigation = navigation.push(
-                    button(text("Open definition").size(12))
-                        .padding(6)
-                        .on_press_maybe(clean.then_some(Message::ScenarioCanvas(
-                            CanvasEvent::OpenUse(context, app.selected),
-                        ))),
-                );
-            }
-            navigation = navigation.push(
-                button(text("Properties").size(12))
-                    .padding(6)
-                    .on_press_maybe(clean.then_some(Message::EditProperties(app.selected))),
-            );
-            details = details.push(navigation.wrap());
-            if lines(p, owner).is_empty() && p.elements[&owner].steps().is_none_or(Vec::is_empty) {
-                details.push(
-                    text("Use Tools to add lifelines, then draw messages or insert occurrences.")
-                        .size(12),
-                )
-            } else {
-                sequence_rows(p, context, owner, details, clean)
-            }
-        }
-    };
     let details = details_pane(
         context,
         state.scroll_restore(context, ScrollArea::Page),
-        details.into(),
-        presentation.shelf.is_some(),
-        pending,
+        sequence_rows(p, context, owner, details, clean).into(),
+    );
+    let mut form_panel = editor_panel(
+        Id::nil(),
+        Space::new().height(0).into(),
+        Space::new().height(0).into(),
     );
-    let mut form_panel = editor_panel(Space::new().height(0).into(), Space::new().height(0).into());
     if let Some(d) = app
         .behavior
         .scenario
@@ -342,6 +279,9 @@ pub fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Element<'a
             let mut form = column![
                 text(d.tool.label()).size(16),
                 text_input("Name (defaults to selected source)", &d.name)
+                    .id(focus::name_id(
+                        state.focus_stamp(context).expect("visible parent form")
+                    ))
                     .on_input(|s| event(Event::Name(s)))
                     .padding(9)
                     .size(12)
@@ -619,10 +559,20 @@ pub fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Element<'a
                 action("Cancel", event(Event::Cancel))
             ]
             .spacing(7);
-            form_panel = editor_panel(footer.into(), form.into());
+            let session = state.form_session().expect("visible scenario draft");
+            let mount = state.form_mount().expect("visible parent form");
+            form_panel = sensor(editor_panel(session, footer.into(), form.into()))
+                .key(mount)
+                .on_show(move |_| Message::ScenarioCanvas(CanvasEvent::FormShown(context, mount)))
+                .into();
         }
     }
-    workspace_layout(header.into(), details, canvas, form_panel, pending)
+    let editor = if pending {
+        Some(form_panel)
+    } else {
+        presentation.shelf.map(|_| details)
+    };
+    super::super::canvas_workspace::host(header.into(), palette, canvas, editor)
 }
 
 fn sequence_action<'a>(
@@ -636,101 +586,38 @@ fn sequence_action<'a>(
         .on_press_maybe(enabled.then_some(message))
 }
 
-// Permanent header/shelf/body and canvas/form slots. Zero-sized disclosures
-// must remain in the tree: Column::push otherwise drops them and remounts siblings.
-fn workspace_layout<'a, R: iced::advanced::text::Renderer + 'a>(
-    header: iced::Element<'a, Message, Theme, R>,
-    details: iced::Element<'a, Message, Theme, R>,
-    canvas: iced::Element<'a, Message, Theme, R>,
-    form: iced::Element<'a, Message, Theme, R>,
-    pending: bool,
-) -> iced::Element<'a, Message, Theme, R> {
-    let panes = Column::from_vec(vec![
-        container(canvas).width(Fill).height(Fill).into(),
-        container(form)
-            .width(Fill)
-            .height(if pending {
-                Fill
-            } else {
-                iced::Length::Fixed(0.)
-            })
-            .clip(true)
-            .into(),
-    ])
-    .spacing(if pending { 6 } else { 0 })
-    .width(Fill)
-    .height(Fill);
-    Column::from_vec(vec![header, details, panes.into()])
-        .spacing(6)
-        .padding(8)
-        .width(Fill)
-        .height(Fill)
-        .into()
-}
-
 fn details_pane<'a, R: iced::advanced::text::Renderer + 'a>(
     context: Context,
     restore: Option<ScrollRestore>,
     details: iced::Element<'a, Message, Theme, R>,
-    open: bool,
-    pending: bool,
 ) -> iced::Element<'a, Message, Theme, R> {
     scenario_scroll::observe(
         context,
         ScrollArea::Page,
+        false,
         restore,
         scrollable(details)
             .id("scenario-details")
             .width(Fill)
-            .height(if open {
-                if pending { 72. } else { 100. }
-            } else {
-                0.
-            }),
+            .height(Fill),
     )
 }
 
-fn canvas_pane<'a, R: iced::advanced::text::Renderer + 'a>(
-    context: Context,
-    restore: Option<ScrollRestore>,
-    content: iced::Element<'a, Message, Theme, R>,
-) -> iced::Element<'a, Message, Theme, R> {
-    container(
-        sensor(scenario_scroll::observe(
-            context,
-            ScrollArea::Canvas,
-            restore,
-            scrollable(content)
-                .id("scenario-canvas")
-                .direction(scrollable::Direction::Both {
-                    vertical: scrollable::Scrollbar::default(),
-                    horizontal: scrollable::Scrollbar::default(),
-                })
-                .width(Fill)
-                .height(Fill),
-        ))
-        .key((context.document, context.scenario))
-        .on_show(move |size| Message::ScenarioCanvas(CanvasEvent::Viewport(context, size)))
-        .on_resize(move |size| Message::ScenarioCanvas(CanvasEvent::Viewport(context, size))),
-    )
-    .padding(8)
-    .width(Fill)
-    .height(Fill)
-    .style(style::card)
-    .into()
-}
-
 fn editor_panel<'a, R: iced::advanced::text::Renderer + 'a>(
+    session: Id,
     actions: iced::Element<'a, Message, Theme, R>,
     fields: iced::Element<'a, Message, Theme, R>,
 ) -> iced::Element<'a, Message, Theme, R> {
     container(
         column![
             container(actions).id("scenario-actions").width(Fill),
-            scrollable(fields)
-                .id("scenario-form")
-                .width(Fill)
-                .height(Fill),
+            form_session::reset_on_change(
+                session,
+                scrollable(fields)
+                    .id("scenario-form")
+                    .width(Fill)
+                    .height(Fill),
+            ),
         ]
         .spacing(6),
     )

crates/oa-desktop/src/behavior/scenario_lifecycle/render.rs

@@ -277,7 +277,13 @@ impl Rendering {
         }
     }
 
-    pub(in crate::behavior) fn draw_markers(&self, frame: &mut Frame, selected: Id, scale: f32) {
+    pub(in crate::behavior) fn draw_markers(
+        &self,
+        frame: &mut Frame,
+        selected: Id,
+        scale: f32,
+        pan: iced::Vector,
+    ) {
         for marker in &self.markers {
             let color = if selected == marker.event.occurrence || selected == marker.lifeline {
                 style::TEAL
@@ -302,10 +308,11 @@ impl Rendering {
                             },
                         ),
                     );
-                    if let Some(clip) = birth_label_clip(marker.capsule, scale, frame.size()) {
+                    if let Some(clip) = birth_label_clip(pan, marker.capsule, scale, frame.size()) {
                         // WGPU clipped frames start with an identity transform;
-                        // neither the parent's scale nor its clip is inherited.
+                        // neither the parent's pan/scale nor its clip is inherited.
                         frame.with_clip(clip, |label| {
+                            label.translate(pan);
                             label.scale(scale);
                             label.fill_text(Text {
                                 content: short(&marker.name, 18),
@@ -330,12 +337,20 @@ impl Rendering {
     }
 }
 
-fn birth_label_clip(capsule: Rectangle, scale: f32, viewport: Size) -> Option<Rectangle> {
-    if !scale.is_finite() || scale <= 0. {
+fn birth_label_clip(
+    pan: iced::Vector,
+    capsule: Rectangle,
+    scale: f32,
+    viewport: Size,
+) -> Option<Rectangle> {
+    if !pan.x.is_finite() || !pan.y.is_finite() || !scale.is_finite() || scale <= 0. {
         return None;
     }
     Rectangle::new(
-        Point::new((capsule.x + 8.) * scale, (capsule.y + 4.) * scale),
+        Point::new(
+            pan.x + (capsule.x + 8.) * scale,
+            pan.y + (capsule.y + 4.) * scale,
+        ),
         Size::new((capsule.width - 16.) * scale, (capsule.height - 8.) * scale),
     )
     .intersection(&Rectangle::new(Point::ORIGIN, viewport))

crates/oa-desktop/src/behavior/scenario_lifecycle/render_tests.rs

@@ -194,9 +194,13 @@ fn real_scene_long_header_title_and_detail_keep_names_and_have_bounded_clips() {
             // Scroll offset is handled by the existing outer canvas/scrollable;
             // these are the local drawing frame's coordinates, not screen input.
             for scale in [0.05, 0.5, 0.512, 0.64, 0.8, 1., 1.953125, 2.] {
-                let clip =
-                    crate::behavior::box_text_clip(header.rect, scale, Size::new(2000., 2000.))
-                        .unwrap();
+                let clip = crate::behavior::box_text_clip(
+                    iced::Vector::ZERO,
+                    header.rect,
+                    scale,
+                    Size::new(2000., 2000.),
+                )
+                .unwrap();
                 let world = Rectangle::new(
                     Point::new(clip.x / scale, clip.y / scale),
                     Size::new(clip.width / scale, clip.height / scale),
@@ -221,11 +225,12 @@ fn box_text_clip_intersects_parent_viewport_and_rejects_empty_interiors() {
     use crate::behavior::box_text_clip;
     let card = Rectangle::new(Point::new(100., 200.), Size::new(204., 70.));
     assert_eq!(
-        box_text_clip(card, 2., Size::new(300., 500.)),
+        box_text_clip(iced::Vector::ZERO, card, 2., Size::new(300., 500.)),
         Some(Rectangle::new(Point::new(220., 416.), Size::new(80., 84.)))
     );
     assert_eq!(
         box_text_clip(
+            iced::Vector::ZERO,
             Rectangle::new(Point::new(-20., -10.), card.size()),
             2.,
             Size::new(300., 500.),
@@ -233,14 +238,22 @@ fn box_text_clip_intersects_parent_viewport_and_rejects_empty_interiors() {
         Some(Rectangle::new(Point::ORIGIN, Size::new(300., 104.)))
     );
     for viewport in [Size::new(200., 500.), Size::new(300., 400.), Size::ZERO] {
-        assert_eq!(box_text_clip(card, 2., viewport), None);
+        assert_eq!(box_text_clip(iced::Vector::ZERO, card, 2., viewport), None);
     }
     for scale in [0., -1., f32::NAN, f32::INFINITY] {
-        assert_eq!(box_text_clip(card, scale, Size::new(1000., 1000.)), None);
+        assert_eq!(
+            box_text_clip(iced::Vector::ZERO, card, scale, Size::new(1000., 1000.)),
+            None
+        );
     }
     for size in [Size::new(20., 70.), Size::new(204., 16.), Size::ZERO] {
         assert_eq!(
-            box_text_clip(Rectangle::new(Point::ORIGIN, size), 1., card.size()),
+            box_text_clip(
+                iced::Vector::ZERO,
+                Rectangle::new(Point::ORIGIN, size),
+                1.,
+                card.size()
+            ),
             None
         );
     }
@@ -304,7 +317,8 @@ fn birth_label_clip_keeps_padded_world_bounds_at_each_scene_scale() {
             Rectangle::new(Point::new(216., 408.), Size::new(248., 40.)),
         ),
     ] {
-        let clip = birth_label_clip(capsule, scale, Size::new(1000., 1000.)).unwrap();
+        let clip =
+            birth_label_clip(iced::Vector::ZERO, capsule, scale, Size::new(1000., 1000.)).unwrap();
         for (actual, expected) in [
             (clip.x, expected.x),
             (clip.y, expected.y),
@@ -325,20 +339,28 @@ fn birth_label_clip_keeps_padded_world_bounds_at_each_scene_scale() {
 fn birth_label_clip_preserves_parent_viewport_bounds() {
     let capsule = Rectangle::new(Point::new(100., 200.), Size::new(140., 28.));
     assert_eq!(
-        birth_label_clip(capsule, 2., Size::new(300., 420.)),
+        birth_label_clip(iced::Vector::ZERO, capsule, 2., Size::new(300., 420.)),
         Some(Rectangle::new(Point::new(216., 408.), Size::new(84., 12.)))
     );
     let crossing_origin = Rectangle::new(Point::new(-20., -10.), Size::new(140., 28.));
     assert_eq!(
-        birth_label_clip(crossing_origin, 2., Size::new(300., 420.)),
+        birth_label_clip(
+            iced::Vector::ZERO,
+            crossing_origin,
+            2.,
+            Size::new(300., 420.)
+        ),
         Some(Rectangle::new(Point::ORIGIN, Size::new(224., 28.)))
     );
     for viewport in [Size::new(200., 420.), Size::new(300., 400.), Size::ZERO] {
-        assert_eq!(birth_label_clip(capsule, 2., viewport), None);
+        assert_eq!(
+            birth_label_clip(iced::Vector::ZERO, capsule, 2., viewport),
+            None
+        );
     }
     for scale in [0., -1., f32::NAN, f32::INFINITY] {
         assert_eq!(
-            birth_label_clip(capsule, scale, Size::new(1000., 1000.)),
+            birth_label_clip(iced::Vector::ZERO, capsule, scale, Size::new(1000., 1000.)),
             None
         );
     }
@@ -794,3 +816,158 @@ fn real_scene_lifecycle_edit_undo_redo_restores_exact_source_and_changed_geometr
         assert!(!document.can_redo());
     }
 }
+
+#[test]
+fn panned_header_and_create_clips_use_screen_translation_and_actual_viewport() {
+    use crate::behavior::box_text_clip;
+    use iced::Vector;
+    let header = Rectangle::new(Point::new(100., 200.), Size::new(204., 70.));
+    let capsule = Rectangle::new(header.position(), Size::new(140., 28.));
+    let rect = |x, y, w, h| Rectangle::new(Point::new(x, y), Size::new(w, h));
+    for (pan, scale, viewport, header_expected, birth_expected) in [
+        (
+            Vector::new(37., -41.),
+            0.5,
+            Size::new(300., 400.),
+            rect(92., 63., 92., 27.),
+            rect(91., 61., 62., 10.),
+        ),
+        (
+            Vector::new(37., -41.),
+            1.,
+            Size::new(300., 400.),
+            rect(147., 167., 153., 54.),
+            rect(145., 163., 124., 20.),
+        ),
+        (
+            Vector::new(37., -41.),
+            2.,
+            Size::new(300., 400.),
+            rect(257., 375., 43., 25.),
+            rect(253., 367., 47., 33.),
+        ),
+        (
+            Vector::new(-200., -400.),
+            2.,
+            Size::new(300., 100.),
+            rect(20., 16., 280., 84.),
+            rect(16., 8., 248., 40.),
+        ),
+        (
+            Vector::new(-237., -411.),
+            2.,
+            Size::new(300., 100.),
+            rect(0., 5., 300., 95.),
+            rect(0., 0., 227., 37.),
+        ),
+    ] {
+        assert_eq!(
+            box_text_clip(pan, header, scale, viewport),
+            Some(header_expected)
+        );
+        assert_eq!(
+            birth_label_clip(pan, capsule, scale, viewport),
+            Some(birth_expected)
+        );
+    }
+    for pan in [
+        Vector::new(1000., 1000.),
+        Vector::new(-1000., -1000.),
+        Vector::new(f32::NAN, 0.),
+        Vector::new(0., f32::INFINITY),
+    ] {
+        assert_eq!(box_text_clip(pan, header, 2., Size::new(300., 100.)), None);
+        assert_eq!(
+            birth_label_clip(pan, capsule, 2., Size::new(300., 100.)),
+            None
+        );
+    }
+}
+
+#[test]
+fn real_scene_panned_zoomed_program_keeps_header_birth_and_death_hit_identity() {
+    use crate::{
+        app::Message,
+        behavior::{
+            SequenceInput,
+            scenario::{CanvasEvent, CanvasTool},
+        },
+    };
+    use iced::{Vector, mouse, widget::canvas};
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        f.project.elements.get_mut(&f.receiver).unwrap().name = "界".repeat(24);
+        let create = f.message(f.owner, MessageKind::Create);
+        let delete = f.message(f.owner, MessageKind::Delete);
+        let document = f.document();
+        let before = document.snapshot();
+        for scale in [0.5, 1., 2.] {
+            for pan in [Vector::new(35., 40.), Vector::new(-35., -5.)] {
+                let mut scene = f.scene();
+                scene.scale = scale;
+                scene.camera_pan = pan;
+                let context = crate::behavior::scenario::direct_tests::context(f.owner);
+                scene.interaction = Some((context, CanvasTool::Select, true));
+                let header = scene.boxes.iter().find(|b| b.id == f.sender).unwrap();
+                let targets = [
+                    (f.sender, header.rect.center()),
+                    (
+                        create,
+                        scene
+                            .lifecycle
+                            .markers
+                            .iter()
+                            .find(|m| m.event.occurrence == create)
+                            .unwrap()
+                            .center,
+                    ),
+                    (
+                        delete,
+                        scene
+                            .lifecycle
+                            .markers
+                            .iter()
+                            .find(|m| m.event.occurrence == delete)
+                            .unwrap()
+                            .center,
+                    ),
+                ];
+                // Absolute widget origin models the outer layout/scroll translation;
+                // camera pan remains local screen units and must be subtracted once.
+                let bounds = Rectangle::new(Point::new(73., 119.), Size::new(2000., 1200.));
+                for (expected, world) in targets {
+                    let screen =
+                        bounds.position() + pan + Vector::new(world.x * scale, world.y * scale);
+                    assert!(bounds.contains(screen));
+                    let mut state = SequenceInput::default();
+                    let mut published = Vec::new();
+                    for event in [
+                        mouse::Event::CursorMoved { position: screen },
+                        mouse::Event::ButtonPressed(mouse::Button::Left),
+                        mouse::Event::ButtonReleased(mouse::Button::Left),
+                    ] {
+                        if let Some(message) = canvas::Program::update(
+                            &scene,
+                            &mut state,
+                            &canvas::Event::Mouse(event),
+                            bounds,
+                            mouse::Cursor::Available(screen),
+                        )
+                        .and_then(|a| a.into_inner().0)
+                        {
+                            published.push(message);
+                        }
+                    }
+                    assert!(
+                        matches!(published.as_slice(), [Message::ScenarioCanvas(CanvasEvent::Select(actual_context, actual))] if *actual_context == context && *actual == expected),
+                        "Pan/zoom must retain the typed hit identity"
+                    );
+                }
+                assert_eq!(scene.lifecycle, f.scene().lifecycle);
+            }
+        }
+        assert_eq!(document.project(), &before.decoded.project);
+        assert_eq!(document.bundle(), &before.bundle);
+        assert!(!document.can_undo() && !document.dirty());
+    }
+}

crates/oa-desktop/src/behavior/state_canvas.rs

@@ -27,6 +27,8 @@ pub struct StateCanvas<'a> {
     pub diagram: Id,
     pub context: Context,
     pub selected: Id,
+    /// Presentation-only navigation marker; never an authoring placement.
+    pub navigation_focus: Option<Rectangle>,
     pub tool: Tool,
     pub zoom: f32,
     pub pan: Vector,
@@ -415,6 +417,171 @@ fn state_action_label(project: &Project, relation: &Relation) -> String {
     format!("{phase} / {}", project.named(target))
 }
 
+/// Match a typed label field by its structural offset, never by a display-name
+/// substring (names may duplicate or also occur in free-form guards).
+fn retained_label_field(full: &str, painted: &str, start: usize) -> bool {
+    start
+        < full
+            .chars()
+            .zip(painted.chars())
+            .take_while(|(a, b)| a == b)
+            .map(|(c, _)| c.len_utf8())
+            .sum::<usize>()
+}
+
+fn transition_label_role(
+    project: &Project,
+    relation: &Relation,
+    subject: Id,
+    width: f32,
+) -> Option<&'static str> {
+    let full = routing::state_transition_summary(project, relation);
+    transition_label_role_in_text(project, relation, subject, &short(&full, width, 10.))
+}
+
+fn transition_label_role_in_text(
+    project: &Project,
+    relation: &Relation,
+    subject: Id,
+    painted: &str,
+) -> Option<&'static str> {
+    let RelationBody::StateTransition {
+        transition_kind,
+        triggers,
+        effects,
+        effect,
+        ..
+    } = &relation.body
+    else {
+        return None;
+    };
+    if project.named(subject).trim().is_empty() {
+        return None;
+    }
+    let full = routing::state_transition_summary(project, relation);
+    let mut offset = format!("{transition_kind:?} · ").len();
+    for id in triggers {
+        if *id == subject && retained_label_field(&full, painted, offset) {
+            return Some("transition trigger");
+        }
+        offset += project.named(*id).len() + " OR ".len();
+    }
+    if !effects.is_empty() {
+        // The canonical routing summary appends typed effects before optional
+        // authored effect prose. Derive its offset from that exact suffix.
+        let mut suffix = format!(
+            " / {}",
+            effects
+                .iter()
+                .map(|id| project.named(*id))
+                .collect::<Vec<_>>()
+                .join(", ")
+        );
+        if !effect.is_empty() {
+            suffix.push_str(&format!(" / {effect}"));
+        }
+        if let Some(prefix) = full.strip_suffix(&suffix) {
+            offset = prefix.len() + " / ".len();
+            for id in effects {
+                if *id == subject && retained_label_field(&full, painted, offset) {
+                    return Some("transition effect");
+                }
+                offset += project.named(*id).len() + ", ".len();
+            }
+        }
+    }
+    None
+}
+
+/// Actual state compartments and painted transition-reference labels. Generic
+/// projected node/edge identities are handled by the shared saved-view query.
+pub(crate) fn diagram_usages(
+    project: &Project,
+    diagram: &Diagram,
+    view: &ProjectedView,
+    subject: Id,
+) -> Vec<crate::diagram_usage::Usage> {
+    use crate::diagram_usage::{Surface, Target, Usage};
+    if diagram.projection.state_machine().is_none() {
+        return vec![];
+    }
+    let mut result = Vec::new();
+    for node in &view.nodes {
+        for (relation, bounds) in state_action_rows(project, node) {
+            let label = state_action_label(project, relation);
+            let painted = short(&label, bounds.width - 12., 11.);
+            let role = if relation.id == subject {
+                Some("state action")
+            } else if relation.target() == subject
+                && retained_label_field(
+                    &label,
+                    &painted,
+                    label.len() - project.named(subject).len(),
+                )
+            {
+                Some("state action work")
+            } else {
+                None
+            };
+            if let Some(role) = role {
+                result.push(Usage {
+                    subject,
+                    surface: Surface::Saved(diagram.id),
+                    target: Target::StateRow {
+                        placement: node.id,
+                        relation: relation.id,
+                    },
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        }
+        for (relation, bounds) in internal_rows(project, node) {
+            let role = if relation.id == subject {
+                Some("internal transition")
+            } else {
+                transition_label_role(project, relation, subject, bounds.width - 12.)
+            };
+            if let Some(role) = role {
+                result.push(Usage {
+                    subject,
+                    surface: Surface::Saved(diagram.id),
+                    target: Target::StateRow {
+                        placement: node.id,
+                        relation: relation.id,
+                    },
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        }
+    }
+    for edge in routing::route_diagram(project, diagram, view)
+        .edges
+        .values()
+    {
+        let Some(relation) = project.relations.get(&edge.id) else {
+            continue;
+        };
+        if edge.id == subject || edge.label.text.is_empty() {
+            continue;
+        }
+        // Routing already shortens external summaries before the canvas applies
+        // its width limit. Compare against precisely that doubly shortened text.
+        let painted = short(&edge.label.text, edge.label.bounds.size.width - 10., 10.);
+        if let Some(role) = transition_label_role_in_text(project, relation, subject, &painted) {
+            result.push(Usage {
+                subject,
+                surface: Surface::Saved(diagram.id),
+                target: Target::Edge(edge.id),
+                role: role.into(),
+                bounds: crate::diagram_usage::edge_focus_bounds(edge),
+            });
+        }
+    }
+    result
+}
+
 impl StateCanvas<'_> {
     fn scale(&self) -> f32 {
         if self.zoom.is_finite() {
@@ -1148,6 +1315,14 @@ impl canvas::Program<Event> for StateCanvas<'_> {
         overlay.with_clip(content, |frame| {
             frame.translate(self.offset());
             frame.scale(self.scale());
+            if let Some(bounds) = self.navigation_focus {
+                frame.stroke(
+                    &Path::rectangle(bounds.position(), bounds.size()),
+                    Stroke::default()
+                        .with_color(style::TEAL)
+                        .with_width(2.5 / self.scale()),
+                );
+            }
             if let Some(at) = world
                 && self.editable
             {
@@ -1575,6 +1750,189 @@ mod tests {
         }
     }
 
+    #[test]
+    fn diagram_usage_state_rows_and_label_references_follow_actual_projection() {
+        use crate::diagram_usage::Target;
+        let mut f = fixture();
+        let work = f
+            .project
+            .add_element(Kind::Function, Layer::Sa, "Act", None)
+            .unwrap();
+        let event = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "E", None)
+            .unwrap();
+        let unused = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "E", None)
+            .unwrap();
+        let action = f
+            .project
+            .relate(RelationKind::StateAction, "Entry", f.a, work);
+        let internal = f
+            .project
+            .relate(RelationKind::StateTransition, "Internal", f.a, f.a);
+        let external = f
+            .project
+            .relate(RelationKind::StateTransition, "External", f.a, f.b);
+        for (id, kind) in [
+            (internal, TransitionKind::Internal),
+            (external, TransitionKind::External),
+        ] {
+            if let RelationBody::StateTransition {
+                transition_kind,
+                triggers,
+                effects,
+                ..
+            } = &mut f.project.relations.get_mut(&id).unwrap().body
+            {
+                *transition_kind = kind;
+                *triggers = vec![event];
+                *effects = vec![work];
+            }
+        }
+        let before = f.project.clone();
+        let diagram = &f.project.diagrams[&f.diagram];
+        let view = projection::project_diagram(&f.project, diagram);
+        let placement = view.nodes.iter().find(|n| n.element == f.a).unwrap().id;
+        let action_target = Target::StateRow {
+            placement,
+            relation: action,
+        };
+        let internal_target = Target::StateRow {
+            placement,
+            relation: internal,
+        };
+        assert_eq!(
+            diagram_usages(&f.project, diagram, &view, action)[0].target,
+            action_target
+        );
+        assert_eq!(
+            diagram_usages(&f.project, diagram, &view, internal)[0].target,
+            internal_target
+        );
+        let events = diagram_usages(&f.project, diagram, &view, event);
+        assert_eq!(events.len(), 2);
+        assert!(events.iter().any(|u| u.target == internal_target));
+        assert!(events.iter().any(|u| u.target == Target::Edge(external)));
+        assert!(diagram_usages(&f.project, diagram, &view, unused).is_empty());
+        // External edge identity belongs to the shared saved-view adapter.
+        assert!(diagram_usages(&f.project, diagram, &view, external).is_empty());
+        let work_usages = diagram_usages(&f.project, diagram, &view, work);
+        assert!(work_usages.iter().any(|u| u.target == action_target));
+        assert!(work_usages.iter().any(|u| u.target == internal_target));
+        let row = work_usages
+            .iter()
+            .find(|u| u.target == action_target)
+            .unwrap();
+        let canvas = canvas(&f, Tool::Select, 1.);
+        let scene = canvas.scene(&State::default()).unwrap();
+        assert_eq!(
+            canvas.hit(&scene, row.bounds.center()),
+            Some(Hit::StateAction(action))
+        );
+        assert_eq!(f.project, before);
+        f.project
+            .diagrams
+            .get_mut(&f.diagram)
+            .unwrap()
+            .nodes
+            .get_mut(&placement)
+            .unwrap()
+            .collapsed = true;
+        let diagram = &f.project.diagrams[&f.diagram];
+        let folded = projection::project_diagram(&f.project, diagram);
+        assert!(diagram_usages(&f.project, diagram, &folded, action).is_empty());
+        assert!(diagram_usages(&f.project, diagram, &folded, internal).is_empty());
+    }
+
+    #[test]
+    fn diagram_usage_transition_labels_do_not_match_prose_or_fields_beyond_cutoff() {
+        let mut f = fixture();
+        let early = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "A", None)
+            .unwrap();
+        let late = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "B", None)
+            .unwrap();
+        let relation = f
+            .project
+            .relate(RelationKind::StateTransition, "Transition", f.a, f.b);
+        if let RelationBody::StateTransition {
+            triggers, guard, ..
+        } = &mut f.project.relations.get_mut(&relation).unwrap().body
+        {
+            *triggers = vec![early, late];
+            *guard = "B".into();
+        }
+        let relation = &f.project.relations[&relation];
+        assert_eq!(
+            transition_label_role(&f.project, relation, early, 84.),
+            Some("transition trigger")
+        );
+        assert_eq!(transition_label_role(&f.project, relation, late, 84.), None);
+        assert_eq!(
+            transition_label_role(&f.project, relation, late, 800.),
+            Some("transition trigger")
+        );
+        assert!(!retained_label_field("1234A678", "1234…", 4));
+    }
+
+    #[test]
+    fn diagram_usage_external_labels_obey_routing_cutoff_while_internal_rows_retain_full_summary() {
+        use crate::diagram_usage::Target;
+        let mut f = fixture();
+        let first = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, &"A".repeat(35), None)
+            .unwrap();
+        let second = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "Second", None)
+            .unwrap();
+        let external = f
+            .project
+            .relate(RelationKind::StateTransition, "External", f.a, f.b);
+        let internal = f
+            .project
+            .relate(RelationKind::StateTransition, "Internal", f.a, f.a);
+        for (id, kind) in [
+            (external, TransitionKind::External),
+            (internal, TransitionKind::Internal),
+        ] {
+            if let RelationBody::StateTransition {
+                transition_kind,
+                triggers,
+                ..
+            } = &mut f.project.relations.get_mut(&id).unwrap().body
+            {
+                *transition_kind = kind;
+                *triggers = vec![first, second];
+            }
+        }
+        let diagram = &f.project.diagrams[&f.diagram];
+        let view = projection::project_diagram(&f.project, diagram);
+        let routed = routing::route_diagram(&f.project, diagram, &view);
+        let edge = &routed.edges[&external];
+        let painted = short(&edge.label.text, edge.label.bounds.size.width - 10., 10.);
+        // Independent painted-text oracle: 11 prefix characters + 35 As, then
+        // only the space before OR survives the routing limit.
+        assert_eq!(edge.label.text, format!("External · {} …", "A".repeat(35)));
+        assert!(!painted.contains("Second"));
+        let usages = diagram_usages(&f.project, diagram, &view, second);
+        assert!(!usages.iter().any(|u| u.target == Target::Edge(external)));
+        assert!(usages.iter().any(
+            |u| matches!(u.target, Target::StateRow { relation, .. } if relation == internal)
+        ));
+        assert!(
+            diagram_usages(&f.project, diagram, &view, first)
+                .iter()
+                .any(|u| u.target == Target::Edge(external))
+        );
+    }
+
     fn canvas(f: &Fixture, tool: Tool, zoom: f32) -> StateCanvas<'_> {
         StateCanvas {
             project: &f.project,
@@ -1586,6 +1944,7 @@ mod tests {
                 epoch: 3,
             },
             selected: f.machine,
+            navigation_focus: None,
             tool,
             zoom,
             pan: Vector::new(20., 30.),

crates/oa-desktop/src/behavior/state_view.rs

@@ -165,6 +165,9 @@ pub fn view<'a>(app: &'a App, machine: Id, mut out: Column<'a, Message>) -> Elem
         diagram: id,
         context,
         selected: app.selected,
+        navigation_focus: app
+            .diagram_focus(crate::diagram_usage::Surface::Saved(id))
+            .map(|usage| usage.bounds),
         tool: state.tool,
         zoom: state.zoom,
         pan: state.pan,

crates/oa-desktop/src/behavior/topology.rs

@@ -5,6 +5,7 @@ use iced::widget::{Column, text_input};
 use std::collections::BTreeSet;
 pub(crate) mod contextual;
 mod direct;
+mod usages;
 mod view;
 use direct::Input;
 pub(crate) use direct::{
@@ -59,7 +60,6 @@ pub enum Event {
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Shelf {
-    Tools,
     Selection,
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -80,10 +80,11 @@ pub struct State {
     identity: Option<(Id, Id)>,
     tool: CanvasTool,
     expanded: BTreeSet<Id>,
-    scroll_offsets: [iced::Vector; 2],
-    return_to: Vec<(Id, Id, Option<oa_core::topology_context::ContextAddress>)>,
+    details_offset: iced::Vector,
+    return_to: Vec<direct::ReturnFrame>,
     draft: Option<Draft>,
     viewport: Option<Size>,
+    pan: iced::Vector,
     zoom: Option<f32>,
     fit: bool,
     pub(crate) focused: bool,
@@ -125,6 +126,18 @@ struct Draft {
     contextual: Option<contextual::Draft>,
 }
 impl State {
+    pub(crate) fn camera_boundary(&self) -> impl PartialEq + use<> {
+        (
+            self.tool,
+            self.focused,
+            self.shelf,
+            self.viewport,
+            self.pan,
+            self.zoom,
+            self.fit,
+        )
+    }
+
     pub(super) fn pending_name(&self) -> Option<&str> {
         self.draft.as_ref().map(|d| d.name.as_str())
     }
@@ -338,8 +351,8 @@ impl State {
     }
 
     fn fit_area(&self, fallback_width: f32) -> Size {
-        // The sensor measures the inner scroller, independent of graph content.
-        // Leave a small gutter for scrollbars; before first layout use a compact
+        // The sensor measures the viewport, independent of graph content.
+        // Leave a small content gutter; before first layout use a compact
         // provisional viewport and recompute when the sensor reports actual size.
         let viewport = self.viewport.unwrap_or(Size::new(fallback_width, 180.));
         Size::new(
@@ -348,10 +361,7 @@ impl State {
         )
     }
 
-    fn canvas_offset(&self) -> iced::Vector {
-        self.scroll_offsets[0]
-    }
-
+    #[cfg(test)]
     fn fit_limited(&self, graph: Size, fallback_width: f32) -> bool {
         let available = self.fit_area(fallback_width);
         self.fit && (graph.width * 0.05 > available.width || graph.height * 0.05 > available.height)
@@ -901,6 +911,13 @@ fn sequence_links(p: &Project, owner: Id) -> Vec<&Relation> {
         })
         .collect()
 }
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct PreviewLink {
+    relation: Id,
+    source: OccurrenceEndpoint,
+    target: OccurrenceEndpoint,
+}
+
 struct GraphNode {
     id: Id,
     rect: Rectangle,
@@ -909,26 +926,98 @@ struct GraphNode {
     control: Option<ControlKind>,
     source: Option<Id>,
     preview: Vec<(OccurrenceEndpoint, String)>,
-    preview_links: Vec<(OccurrenceEndpoint, OccurrenceEndpoint)>,
+    preview_links: Vec<PreviewLink>,
     preview_total: usize,
 }
 impl GraphNode {
+    fn preview_link_points(&self, link: &PreviewLink) -> Option<[Point; 2]> {
+        if ![&link.source, &link.target]
+            .into_iter()
+            .all(|endpoint| self.preview.iter().any(|(shown, _)| shown == endpoint))
+        {
+            return None;
+        }
+        let a = self.endpoint_rect(&link.source);
+        let b = self.endpoint_rect(&link.target);
+        Some([
+            Point::new(a.x + a.width, a.center_y()),
+            Point::new(b.x, b.center_y()),
+        ])
+    }
+
+    fn preview_link_visible_segment(&self, link: &PreviewLink) -> Option<[Point; 2]> {
+        visible_preview_segment(
+            self.preview_link_points(link)?,
+            (0..self.preview.len()).map(|index| self.preview_rect(index)),
+        )
+    }
+
+    fn preview_rect(&self, index: usize) -> Rectangle {
+        Rectangle::new(
+            Point::new(
+                self.rect.x + 12. + (index % 2) as f32 * 125.,
+                self.rect.y + 118. + (index / 2) as f32 * 44.,
+            ),
+            Size::new(113., 32.),
+        )
+    }
+
     fn endpoint_rect(&self, endpoint: &OccurrenceEndpoint) -> Rectangle {
         self.preview
             .iter()
             .position(|(candidate, _)| candidate == endpoint)
-            .map(|i| {
-                Rectangle::new(
-                    Point::new(
-                        self.rect.x + 12. + (i % 2) as f32 * 125.,
-                        self.rect.y + 118. + (i / 2) as f32 * 44.,
-                    ),
-                    Size::new(113., 32.),
-                )
-            })
+            .map(|index| self.preview_rect(index))
             .unwrap_or(self.rect)
     }
 }
+
+/// Preview tiles are painted after their arrows. Focus only a remaining line
+/// segment, excluding opaque tile interiors and their one-pixel borders.
+fn visible_preview_segment(
+    [a, b]: [Point; 2],
+    tiles: impl Iterator<Item = Rectangle>,
+) -> Option<[Point; 2]> {
+    let delta = b - a;
+    let length = (delta.x * delta.x + delta.y * delta.y).sqrt();
+    if !length.is_finite() || length <= 0.5 {
+        return None;
+    }
+    let mut hidden = Vec::new();
+    for tile in tiles {
+        let mut low = 0_f32;
+        let mut high = 1_f32;
+        for (origin, step, min, max) in [
+            (a.x, delta.x, tile.x - 1., tile.x + tile.width + 1.),
+            (a.y, delta.y, tile.y - 1., tile.y + tile.height + 1.),
+        ] {
+            if step.abs() <= f32::EPSILON {
+                if origin < min || origin > max {
+                    high = -1.;
+                    break;
+                }
+            } else {
+                let first = (min - origin) / step;
+                let last = (max - origin) / step;
+                low = low.max(first.min(last));
+                high = high.min(first.max(last));
+            }
+        }
+        if high > low {
+            hidden.push((low, high));
+        }
+    }
+    hidden.sort_by(|a, b| a.0.total_cmp(&b.0));
+    let mut cursor = 0_f32;
+    let mut best = (0_f32, 0_f32);
+    for (low, high) in hidden.into_iter().chain([(1., 1.)]) {
+        if low - cursor > best.1 - best.0 {
+            best = (cursor, low);
+        }
+        cursor = cursor.max(high);
+    }
+    ((best.1 - best.0) * length > 0.5).then(|| [a + delta * best.0, a + delta * best.1])
+}
+
 struct GraphEdge {
     id: Id,
     source: Id,
@@ -969,13 +1058,16 @@ mod contextual_routing;
 struct Graph<'a> {
     project: &'a Project,
     interaction: Option<(Context, CanvasTool, bool)>,
-    scroll_offset: iced::Vector,
+    camera_pan: iced::Vector,
+    pending_insertion: Option<Insertion>,
     nodes: Vec<GraphNode>,
     edges: Vec<GraphEdge>,
     ordered_paths: Vec<OrderedPath>,
     ordered: bool,
     size: Size,
     selected: Id,
+    selected_preview: Option<OccurrenceEndpoint>,
+    selected_preview_link: Option<PreviewLink>,
     scale: f32,
 }
 impl<'a> Graph<'a> {
@@ -1124,17 +1216,16 @@ impl<'a> Graph<'a> {
                                         occurrence: r.target(),
                                     })
                                 })
-                                .map(|r| {
-                                    (
-                                        OccurrenceEndpoint {
-                                            references: vec![e.id],
-                                            occurrence: r.source(),
-                                        },
-                                        OccurrenceEndpoint {
-                                            references: vec![e.id],
-                                            occurrence: r.target(),
-                                        },
-                                    )
+                                .map(|r| PreviewLink {
+                                    relation: r.id,
+                                    source: OccurrenceEndpoint {
+                                        references: vec![e.id],
+                                        occurrence: r.source(),
+                                    },
+                                    target: OccurrenceEndpoint {
+                                        references: vec![e.id],
+                                        occurrence: r.target(),
+                                    },
                                 })
                                 .collect();
                         }
@@ -1301,13 +1392,16 @@ impl<'a> Graph<'a> {
         Self {
             project: p,
             interaction: None,
-            scroll_offset: iced::Vector::ZERO,
+            camera_pan: iced::Vector::ZERO,
+            pending_insertion: None,
             nodes,
             edges,
             ordered_paths,
             ordered: !order.is_empty(),
             size,
             selected,
+            selected_preview: None,
+            selected_preview_link: None,
             scale: 1.,
         }
     }
@@ -1401,6 +1495,7 @@ impl canvas::Program<Message> for Graph<'_> {
     ) -> Vec<canvas::Geometry> {
         let mut f = Frame::new(renderer, bounds.size());
         f.fill_rectangle(Point::ORIGIN, bounds.size(), Color::WHITE);
+        f.translate(self.camera_pan);
         f.scale(self.scale);
         for pass in PAINT_PASSES {
             match pass {
@@ -1536,39 +1631,41 @@ impl canvas::Program<Message> for Graph<'_> {
                             let mini: BTreeMap<_, _> = n
                                 .preview
                                 .iter()
-                                .enumerate()
-                                .map(|(i, (id, _))| {
-                                    (
-                                        id.clone(),
-                                        Rectangle::new(
-                                            Point::new(
-                                                n.rect.x + 12. + (i % 2) as f32 * 125.,
-                                                n.rect.y + 118. + (i / 2) as f32 * 44.,
-                                            ),
-                                            Size::new(113., 32.),
-                                        ),
-                                    )
-                                })
+                                .map(|(id, _)| (id.clone(), n.endpoint_rect(id)))
                                 .collect();
-                            for (a, b) in &n.preview_links {
-                                let a = mini[a];
-                                let b = mini[b];
+                            for link in &n.preview_links {
+                                let Some(points) = n.preview_link_points(link) else {
+                                    continue;
+                                };
+                                let selected = self.selected_preview_link.as_ref() == Some(link);
                                 draw_arrow(
                                     &mut f,
-                                    &[
-                                        Point::new(a.x + a.width, a.center_y()),
-                                        Point::new(b.x, b.center_y()),
-                                    ],
-                                    style::MUTED,
-                                    1.,
+                                    &points,
+                                    if selected { style::TEAL } else { style::MUTED },
+                                    if selected { 3. } else { 1. },
                                 );
                             }
                             for (id, name) in &n.preview {
                                 let r = mini[id];
-                                f.fill_rectangle(r.position(), r.size(), Color::WHITE);
+                                let selected = self.selected_preview.as_ref() == Some(id);
+                                f.fill_rectangle(
+                                    r.position(),
+                                    r.size(),
+                                    if selected {
+                                        Color::from_rgb8(224, 247, 242)
+                                    } else {
+                                        Color::WHITE
+                                    },
+                                );
                                 f.stroke(
                                     &Path::rectangle(r.position(), r.size()),
-                                    Stroke::default().with_color(style::LINE),
+                                    Stroke::default()
+                                        .with_color(if selected {
+                                            style::TEAL
+                                        } else {
+                                            style::LINE
+                                        })
+                                        .with_width(if selected { 2.5 } else { 1. }),
                                 );
                                 draw_text(
                                     &mut f,
@@ -1616,7 +1713,10 @@ impl canvas::Program<Message> for Graph<'_> {
         cursor: mouse::Cursor,
     ) -> mouse::Interaction {
         if cursor.position_in(bounds).is_some_and(|p| {
-            let p = Point::new(p.x / self.scale, p.y / self.scale);
+            let p = Point::new(
+                (p.x - self.camera_pan.x) / self.scale,
+                (p.y - self.camera_pan.y) / self.scale,
+            );
             self.nodes.iter().any(|n| n.rect.contains(p))
                 || self.ordered_paths.iter().any(|path| {
                     path.points.windows(2).any(|pair| {
@@ -2149,7 +2249,6 @@ mod tests {
         let accepted = app.document.snapshot();
         assert!(app.behavior.prepare_pending(app.project()).is_err());
         for (shelf, expected) in [
-            (Shelf::Tools, Some(Shelf::Tools)),
             (Shelf::Selection, Some(Shelf::Selection)),
             (Shelf::Selection, None),
         ] {
@@ -2166,10 +2265,12 @@ mod tests {
     }
 
     #[test]
-    fn process_fit_canvas_selection_ignores_retained_ordered_page_scroll() {
+    fn process_camera_selection_ignores_independent_details_scroll() {
         let (p, owner, _, _, _, _) = fixture();
         let mut state = State::default();
-        state.scrolled(scenario::ScrollArea::Canvas, iced::Vector::new(11., 19.));
+        state.camera(crate::behavior::canvas_workspace::Event::Pan(
+            iced::Vector::new(11., 19.),
+        ));
         state.scrolled(scenario::ScrollArea::Page, iced::Vector::new(0., 370.));
         let context = Context {
             document: p.id,
@@ -2180,16 +2281,17 @@ mod tests {
         for scale in [0.45, 1.] {
             let mut graph = Graph::new(&p, owner, owner);
             graph.scale = scale;
-            graph.scroll_offset = state.canvas_offset();
+            graph.camera_pan = state.pan;
             graph.interaction = Some((context, CanvasTool::Select, true));
             let node = &graph.nodes[0];
             let id = node.id;
             let point = node.rect.center();
             let bounds = Rectangle::new(Point::new(40., 100.), Size::new(800., 300.));
             let screen = Point::new(
-                bounds.x + point.x * scale - 11.,
-                bounds.y + point.y * scale - 19.,
+                bounds.x + point.x * scale + 11.,
+                bounds.y + point.y * scale + 19.,
             );
+            assert!(bounds.contains(screen));
             let message = graph
                 .input(
                     &mut Input::default(),

crates/oa-desktop/src/behavior/topology/contextual.rs

@@ -608,7 +608,11 @@ mod tests {
             "Authored endpoint is retained for explicit repair"
         );
         assert!(state.prepare_pending(&deleted).is_err());
-        state.remember(owner, reference);
+        state.remember(
+            owner,
+            reference,
+            super::super::direct::referenced(&p, owner, reference).unwrap(),
+        );
         assert_eq!(state.back(&deleted), Some((owner, reference)));
         assert!(state.selected_context.is_none());
         state.draft = None;

crates/oa-desktop/src/behavior/topology/direct.rs

@@ -60,6 +60,7 @@ pub enum CanvasEvent {
     Open(Context, Id),
     Back(Context),
     Zoom(Context, Option<f32>),
+    Camera(Context, u64, super::super::canvas_workspace::Event),
     Focus(Context),
     Viewport(Context, Size),
 }
@@ -77,6 +78,7 @@ impl CanvasEvent {
             | Self::Back(c)
             | Self::AppendExchange(c)
             | Self::Zoom(c, ..)
+            | Self::Camera(c, ..)
             | Self::Focus(c)
             | Self::Viewport(c, ..) => *c,
             Self::Begin { context, .. }
@@ -86,6 +88,19 @@ impl CanvasEvent {
         }
     }
 }
+pub(super) struct ReturnFrame {
+    identity: Option<(Id, Id)>,
+    owner: Id,
+    occurrence: Id,
+    target: Id,
+    address: Option<oa_core::topology_context::ContextAddress>,
+    pan: iced::Vector,
+    zoom: Option<f32>,
+    fit: bool,
+    viewport: Option<Size>,
+    expanded: BTreeSet<Id>,
+    contextual_expanded: BTreeSet<OccurrenceEndpoint>,
+}
 impl State {
     pub(crate) fn select_context(&mut self, address: oa_core::topology_context::ContextAddress) {
         self.selected_context = Some(address);
@@ -138,35 +153,49 @@ impl State {
         if self.identity != Some((document, owner)) {
             self.identity = Some((document, owner));
             self.tool = CanvasTool::Select;
+            self.pan = iced::Vector::ZERO;
             self.zoom = Some(1.);
             self.fit = false;
             self.viewport = None;
             self.expanded.clear();
-            self.scroll_offsets = [iced::Vector::ZERO; 2];
+            self.details_offset = iced::Vector::ZERO;
         }
     }
     #[cfg(test)]
-    pub(crate) fn scroll_offset(&self) -> iced::Vector {
-        self.scroll_offsets[0] + self.scroll_offsets[1]
+    pub(crate) fn details_offset(&self) -> iced::Vector {
+        self.details_offset
     }
-    pub(crate) fn scrolled(&mut self, area: scenario::ScrollArea, offset: iced::Vector) -> bool {
-        let index = match area {
-            scenario::ScrollArea::Canvas => 0,
-            scenario::ScrollArea::Page => 1,
-        };
-        let changed = self.scroll_offsets[index] != offset;
-        self.scroll_offsets[index] = offset;
+    pub(crate) fn scrolled(
+        &mut self,
+        scenario::ScrollArea::Page: scenario::ScrollArea,
+        offset: iced::Vector,
+    ) -> bool {
+        if !offset.x.is_finite() || !offset.y.is_finite() || offset.x < 0. || offset.y < 0. {
+            return false;
+        }
+        let changed = self.details_offset != offset;
+        self.details_offset = offset;
         changed
     }
     pub(crate) fn choose(&mut self, tool: CanvasTool) {
         // Choosing how to edit must retain the user's current view.
         self.tool = tool;
     }
+    pub(crate) fn camera(&mut self, event: super::super::canvas_workspace::Event) -> bool {
+        super::super::canvas_workspace::change(&mut self.pan, &mut self.zoom, &mut self.fit, event)
+    }
     pub(crate) fn zoom(&mut self, value: Option<f32>) {
         self.fit = value.is_none();
-        self.zoom = value.map(|v| v.clamp(0.5, 2.));
+        self.zoom = value.map(|v| v.clamp(0.05, 3.));
     }
     pub(crate) fn viewport(&mut self, size: Size) -> bool {
+        if !size.width.is_finite()
+            || !size.height.is_finite()
+            || size.width <= 0.
+            || size.height <= 0.
+        {
+            return false;
+        }
         let changed = self.viewport != Some(size);
         self.viewport = Some(size);
         changed
@@ -188,24 +217,73 @@ impl State {
         }
         true
     }
-    pub(crate) fn remember(&mut self, owner: Id, occurrence: Id) {
-        self.return_to
-            .push((owner, occurrence, self.selected_context.clone()));
+    pub(crate) fn remember(&mut self, owner: Id, occurrence: Id, target: Id) {
+        if self.return_to.len() == 32 {
+            self.return_to.remove(0);
+        }
+        self.return_to.push(ReturnFrame {
+            identity: self.identity,
+            owner,
+            occurrence,
+            target,
+            address: self.selected_context.clone(),
+            pan: self.pan,
+            zoom: self.zoom,
+            fit: self.fit,
+            viewport: self.viewport,
+            expanded: self.expanded.clone(),
+            contextual_expanded: self.contextual_expanded.clone(),
+        });
     }
     pub(crate) fn back(&mut self, p: &Project) -> Option<(Id, Id)> {
-        while let Some((owner, occurrence, address)) = self.return_to.pop() {
-            if is_contribution(p, owner, occurrence) {
-                self.selected_context = address.filter(|address| {
-                    address.owner == owner
-                        && oa_core::topology_context::TopologyIndex::new(p)
-                            .resolve(owner, &address.endpoint)
-                            .is_ok()
+        while let Some(frame) = self.return_to.pop() {
+            if frame.identity.map(|i| i.0) != self.identity.map(|i| i.0) {
+                continue;
+            }
+            let valid = referenced(p, frame.owner, frame.occurrence) == Some(frame.target)
+                || if let Some(address) = &frame.address {
+                    oa_core::topology_context::TopologyIndex::new(p)
+                        .resolve(frame.owner, &address.endpoint)
+                        .is_ok_and(|r| r.defining_sequence == frame.target)
+                } else {
+                    false
+                };
+            if valid && is_contribution(p, frame.owner, frame.occurrence) {
+                self.identity = frame.identity;
+                self.selected_context = frame.address.filter(|a| {
+                    oa_core::topology_context::TopologyIndex::new(p)
+                        .resolve(frame.owner, &a.endpoint)
+                        .is_ok()
                 });
-                return Some((owner, occurrence));
+                self.pan = frame.pan;
+                self.zoom = frame.zoom;
+                self.fit = frame.fit;
+                self.viewport = frame.viewport;
+                self.expanded = frame.expanded;
+                self.contextual_expanded = frame.contextual_expanded;
+                return Some((frame.owner, frame.occurrence));
             }
         }
         None
     }
+    pub(crate) fn camera_zoom(&mut self, p: &Project, owner: Id, zoom: Option<f32>) {
+        let graph =
+            Graph::expanded_qualified(p, owner, owner, &self.expanded, &self.contextual_expanded);
+        let old = self.scale(graph.size, 500.);
+        if let Some(next) = zoom {
+            let size = self.viewport.unwrap_or(Size::new(500., 300.));
+            self.camera(super::super::canvas_workspace::Event::Zoom {
+                factor: next / old,
+                at: Point::new(size.width / 2., size.height / 2.),
+                base: old,
+            });
+        } else {
+            self.zoom(None);
+            let fitted = self.scale(graph.size, 500.);
+            self.zoom(Some(fitted));
+            self.pan = iced::Vector::ZERO;
+        }
+    }
     pub(crate) fn created_selection(&self, p: &Project, command: &Command) -> Option<Id> {
         let owner = self.pending_owner()?;
         if self
@@ -547,7 +625,7 @@ impl Graph<'_> {
                 {
                     *moved |= position.distance(*start) >= 3.;
                 }
-                mouse::Cursor::Available(*position + self.scroll_offset)
+                mouse::Cursor::Available(*position)
             }
             canvas::Event::Mouse(mouse::Event::WheelScrolled { .. } | mouse::Event::CursorLeft)
             | canvas::Event::Window(
@@ -566,18 +644,19 @@ impl Graph<'_> {
             }
             canvas::Event::Mouse(
                 mouse::Event::ButtonPressed(_) | mouse::Event::ButtonReleased(_),
-            ) => state
-                .pointer
-                .map_or(cursor, |p| mouse::Cursor::Available(p + self.scroll_offset)),
+            ) => state.pointer.map_or(cursor, mouse::Cursor::Available),
             canvas::Event::Window(iced::window::Event::RedrawRequested(_)) => {
-                state.pointer = cursor.position().map(|p| p - self.scroll_offset);
+                state.pointer = cursor.position();
                 cursor
             }
             _ => cursor,
         };
-        let world = cursor
-            .position_in(bounds)
-            .map(|p| Point::new(p.x / self.scale, p.y / self.scale));
+        let world = cursor.position_in(bounds).map(|p| {
+            Point::new(
+                (p.x - self.camera_pan.x) / self.scale,
+                (p.y - self.camera_pan.y) / self.scale,
+            )
+        });
         let publish = |event| Some(Action::publish(Message::TopologyCanvas(event)).and_capture());
         match event {
             canvas::Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)) if visible => {
@@ -591,7 +670,7 @@ impl Graph<'_> {
                 if !editable {
                     return None;
                 }
-                let start = cursor.position()? - self.scroll_offset;
+                let start = cursor.position()?;
                 match tool {
                     CanvasTool::Add(..) => {
                         state.press = Some(Press::Add {
@@ -730,15 +809,35 @@ impl Graph<'_> {
         let Some((context, tool, editable)) = self.interaction else {
             return;
         };
+        if let Some(insertion) = self.pending_insertion {
+            if let Some(edge) = insertion
+                .link
+                .and_then(|id| self.edges.iter().find(|e| e.id == id))
+            {
+                draw_arrow(f, &edge.points, style::TEAL, 3.);
+            } else if let Some(node) = insertion
+                .before
+                .and_then(|id| self.nodes.iter().find(|n| n.id == id))
+            {
+                f.stroke(
+                    &Path::rounded_rectangle(node.rect.position(), node.rect.size(), 10.into()),
+                    Stroke::default().with_color(style::TEAL).with_width(3.),
+                );
+            }
+        }
         if !editable {
             return;
         }
         let point = state
             .pointer
-            .map(|p| p + self.scroll_offset)
             .or_else(|| cursor.position())
             .filter(|p| bounds.contains(*p))
-            .map(|p| Point::new((p.x - bounds.x) / self.scale, (p.y - bounds.y) / self.scale));
+            .map(|p| {
+                Point::new(
+                    (p.x - bounds.x - self.camera_pan.x) / self.scale,
+                    (p.y - bounds.y - self.camera_pan.y) / self.scale,
+                )
+            });
         let live =
             state.context == Some(context) && state.tool == tool && state.bounds == Some(bounds);
         if live && let Some(source) = state.source {
@@ -853,12 +952,7 @@ impl Graph<'_> {
 }
 
 impl State {
-    pub(crate) fn selection_offset(
-        &self,
-        p: &Project,
-        owner: Id,
-        id: Id,
-    ) -> Option<scrollable::AbsoluteOffset> {
+    pub(crate) fn reveal_selection(&mut self, p: &Project, owner: Id, id: Id) -> bool {
         let graph =
             Graph::expanded_qualified(p, owner, id, &self.expanded, &self.contextual_expanded);
         let scale = self.scale(graph.size, 500.);
@@ -870,10 +964,25 @@ impl State {
                 self.qualified_selection(p, owner)
                     .map_or(n.rect, |a| n.endpoint_rect(&a.endpoint))
             })
-            .or_else(|| graph.edges.iter().find(|e| e.id == id).map(|e| e.label))?;
-        Some(scrollable::AbsoluteOffset {
-            x: (rect.x * scale - 12.).max(0.),
-            y: (rect.y * scale - 12.).max(0.),
-        })
+            .or_else(|| graph.edges.iter().find(|e| e.id == id).map(|e| e.label));
+        let Some(rect) = rect else {
+            return false;
+        };
+        let viewport = self.viewport.unwrap_or(Size::new(500., 300.));
+        let x = rect.x * scale + self.pan.x;
+        let y = rect.y * scale + self.pan.y;
+        let delta = iced::Vector::new(
+            if x < 12. || x + rect.width * scale > viewport.width - 12. {
+                12. - x
+            } else {
+                0.
+            },
+            if y < 12. || y + rect.height * scale > viewport.height - 12. {
+                12. - y
+            } else {
+                0.
+            },
+        );
+        self.camera(super::super::canvas_workspace::Event::Pan(delta))
     }
 }

crates/oa-desktop/src/behavior/topology/direct_tests.rs

@@ -540,7 +540,7 @@ fn send(
         input,
         &canvas::Event::Mouse(event),
         bounds,
-        mouse::Cursor::Available(point + graph.scroll_offset),
+        mouse::Cursor::Available(point),
     )
     .and_then(|a| a.into_inner().0)
 }
@@ -554,16 +554,20 @@ fn position(graph: &Graph<'_>, id: Id) -> Point {
         .center()
 }
 #[test]
-fn direct_process_production_click_click_drag_insert_and_scroll_coordinates() {
+fn direct_process_production_click_click_drag_insert_and_camera_coordinates() {
     let f = fixture(Layer::Oa);
     for drag in [false, true] {
         let mut graph = graph(&f, CanvasTool::Connect);
-        graph.scroll_offset = iced::Vector::new(35., 90.);
-        let bounds = Rectangle::new(Point::new(10., 20.), graph.size);
+        graph.camera_pan = iced::Vector::new(35., 90.);
+        let bounds = Rectangle::new(
+            Point::new(10., 20.),
+            Size::new(graph.size.width + 70., graph.size.height + 180.),
+        );
         let screen =
-            |id| position(&graph, id) + iced::Vector::new(bounds.x, bounds.y) - graph.scroll_offset;
+            |id| position(&graph, id) + iced::Vector::new(bounds.x, bounds.y) + graph.camera_pan;
         let a = screen(f.nodes[0]);
         let b = screen(f.nodes[2]);
+        assert!(bounds.contains(a) && bounds.contains(b));
         let mut input = Input::default();
         send(
             &graph,
@@ -732,7 +736,7 @@ fn direct_process_readable_default_fit_expansion_and_bounded_choices() {
     state.zoom(None);
     assert!(state.scale(Size::new(3262., 220.), 500.) < 0.2);
     state.zoom(Some(0.1));
-    assert_eq!(state.scale(Size::new(3262., 220.), 500.), 0.5);
+    assert_eq!(state.scale(Size::new(3262., 220.), 500.), 0.1);
     state.enter(Id::new_v4(), f.owner);
     assert_eq!(state.scale(Size::new(3262., 220.), 500.), 1.);
     let mut all = Vec::new();
@@ -1331,7 +1335,9 @@ fn direct_process_palette_preserves_fit_and_manual_camera() {
         let document = Id::new_v4();
         state.enter(document, f.owner);
         state.viewport(Size::new(500., 300.));
-        state.scrolled(scenario::ScrollArea::Canvas, iced::Vector::new(35., 90.));
+        state.camera(super::super::canvas_workspace::Event::Pan(
+            iced::Vector::new(35., 90.),
+        ));
         state.scrolled(scenario::ScrollArea::Page, iced::Vector::new(0., 120.));
         for camera in [None, Some(0.75), Some(1.5)] {
             state.zoom(camera);
@@ -1353,90 +1359,16 @@ fn direct_process_palette_preserves_fit_and_manual_camera() {
                     "{layer:?} {camera:?} {tool:?}"
                 );
                 assert_eq!(state.fit, camera.is_none());
-                assert_eq!(state.scroll_offset(), iced::Vector::new(35., 210.));
+                assert_eq!(state.pan, iced::Vector::new(35., 90.));
+                assert_eq!(state.details_offset(), iced::Vector::new(0., 120.));
                 state.enter(document, f.owner);
                 assert_eq!(state.scale(size, 500.), before);
             }
         }
         state.enter(Id::new_v4(), f.owner);
         assert_eq!(state.scale(Size::new(690., 250.), 500.), 1.);
-        assert_eq!(state.scroll_offset(), iced::Vector::ZERO);
-    }
-}
-
-#[test]
-fn direct_process_pending_form_diff_retains_the_canvas_scroll_state() {
-    use iced::advanced::widget::{Tree, tree};
-    use std::rc::Rc;
-    fn path_to(tree: &Tree, tag: tree::Tag) -> Option<Vec<usize>> {
-        if tree.tag == tag {
-            return Some(Vec::new());
-        }
-        tree.children.iter().enumerate().find_map(|(index, child)| {
-            let mut path = path_to(child, tag)?;
-            path.insert(0, index);
-            Some(path)
-        })
-    }
-    fn at<'a>(mut tree: &'a mut Tree, path: &[usize]) -> &'a mut Tree {
-        for &index in path {
-            tree = &mut tree.children[index];
-        }
-        tree
-    }
-    for layer in [Layer::Oa, Layer::Sa] {
-        for size in [Size::new(1440., 900.), Size::new(1100., 700.)] {
-            for tool in [Tool::Control, Tool::Branch, Tool::Connect] {
-                let f = fixture(layer);
-                let mut app = App::with_project(f.p.clone());
-                let _ = app.update(Message::Select(f.nodes[1]));
-                let _ = app.update(Message::Page(crate::app::Page::Behavior));
-                app.window_size = size;
-                let original = app.document.snapshot();
-                let graph: Element<'_, Message> =
-                    canvas::Canvas::new(Graph::new(app.project(), f.owner, f.nodes[1])).into();
-                let canvas_tag = Tree::new(graph.as_widget()).tag;
-                drop(graph);
-                let scroll: Element<'_, Message> = scrollable(text("")).into();
-                let scroll_tag = Tree::new(scroll.as_widget()).tag;
-                let mut tree = Tree::new(view::view(&app, f.owner, Column::new()).as_widget());
-                let mut scroll_path = path_to(&tree, canvas_tag).unwrap();
-                scroll_path.pop();
-                assert_eq!(at(&mut tree, &scroll_path).tag, scroll_tag);
-                // Scrollable::diff treats its local state as opaque. A retained marker
-                // proves the real Iced diff preserves the state that owns the offsets.
-                // No layout or input operation runs on this test-only marker state.
-                let marker = Rc::new(());
-                at(&mut tree, &scroll_path).state = tree::State::new(Rc::clone(&marker));
-                let _ = app.update(Message::Behavior(super::super::Event::Topology(
-                    Event::Start(f.owner, tool, Some(f.nodes[1])),
-                )));
-                assert!(app.behavior.has_pending());
-                tree.diff(view::view(&app, f.owner, Column::new()).as_widget());
-                assert_eq!(
-                    Rc::strong_count(&marker),
-                    2,
-                    "form open: {layer:?} {size:?} {tool:?}"
-                );
-                let mut current_path = path_to(&tree, canvas_tag).unwrap();
-                current_path.pop();
-                assert_eq!(current_path, scroll_path);
-                assert!(Rc::ptr_eq(
-                    at(&mut tree, &scroll_path).state.downcast_ref::<Rc<()>>(),
-                    &marker,
-                ));
-                let _ = app.update(Message::Behavior(super::super::Event::Topology(
-                    Event::Cancel,
-                )));
-                tree.diff(view::view(&app, f.owner, Column::new()).as_widget());
-                assert_eq!(
-                    Rc::strong_count(&marker),
-                    2,
-                    "form cancel: {layer:?} {size:?} {tool:?}"
-                );
-                assert!(std::sync::Arc::ptr_eq(&app.document.snapshot(), &original));
-            }
-        }
+        assert_eq!(state.pan, iced::Vector::ZERO);
+        assert_eq!(state.details_offset(), iced::Vector::ZERO);
     }
 }
 
@@ -1447,15 +1379,18 @@ fn direct_process_scaled_control_and_link_gestures_use_visible_positions() {
         for scale in [0.15, 0.6898551, 1.5] {
             let mut graph = graph(&f, CanvasTool::Add(Tool::Control, ControlKind::Choice));
             graph.scale = scale;
-            graph.scroll_offset = iced::Vector::new(11., 19.);
+            graph.camera_pan = iced::Vector::new(11., 19.);
             let bounds = Rectangle::new(
                 Point::new(40., 70.),
-                Size::new(graph.size.width * scale, graph.size.height * scale),
+                Size::new(
+                    graph.size.width * scale + 22.,
+                    graph.size.height * scale + 38.,
+                ),
             );
             let screen = |world: Point| {
                 Point::new(
-                    world.x * scale + bounds.x - 11.,
-                    world.y * scale + bounds.y - 19.,
+                    world.x * scale + bounds.x + 11.,
+                    world.y * scale + bounds.y + 19.,
                 )
             };
             let edge = &graph.edges[0];
@@ -1463,6 +1398,7 @@ fn direct_process_scaled_control_and_link_gestures_use_visible_positions() {
                 (edge.points[0].x + edge.points[1].x) / 2.,
                 edge.points[0].y,
             ));
+            assert!(bounds.contains(point));
             let mut input = Input::default();
             send(
                 &graph,
@@ -1493,6 +1429,7 @@ fn direct_process_scaled_control_and_link_gestures_use_visible_positions() {
                 let mut input = Input::default();
                 let a = screen(position(&graph, f.nodes[0]));
                 let b = screen(position(&graph, f.nodes[2]));
+                assert!(bounds.contains(a) && bounds.contains(b));
                 send(
                     &graph,
                     &mut input,

crates/oa-desktop/src/behavior/topology/usages.rs

@@ -0,0 +1,274 @@
+//! Read-only usages of the actual process graph, including bounded reuse tiles.
+use super::*;
+use crate::diagram_usage::{Surface, Target, Usage};
+
+/// The only presentation inputs needed by a background usage query. Drafts,
+/// focus, camera, history and widget state never cross the worker boundary.
+#[derive(Clone)]
+pub(crate) struct UsageSnapshot {
+    identity: Option<(Id, Id)>,
+    expanded: BTreeSet<Id>,
+    contextual_expanded: BTreeSet<OccurrenceEndpoint>,
+}
+
+impl UsageSnapshot {
+    pub(crate) fn into_query_state(self) -> State {
+        State {
+            identity: self.identity,
+            expanded: self.expanded,
+            contextual_expanded: self.contextual_expanded,
+            ..State::default()
+        }
+    }
+}
+
+impl State {
+    pub(crate) fn usage_snapshot(&self) -> UsageSnapshot {
+        UsageSnapshot {
+            identity: self.identity,
+            expanded: self.expanded.clone(),
+            contextual_expanded: self.contextual_expanded.clone(),
+        }
+    }
+}
+
+fn owner_exists(p: &Project, owner: Id) -> bool {
+    p.elements
+        .get(&owner)
+        .is_some_and(|e| matches!(e.kind(), Kind::Process | Kind::FunctionalChain))
+}
+
+fn occurrence_role(p: &Project, occurrence: Id, subject: Id) -> Option<&'static str> {
+    let e = p.elements.get(&occurrence)?;
+    if occurrence == subject {
+        return Some("contribution");
+    }
+    match e.shared()? {
+        SharedBody::Occurrence {
+            body: OccurrenceBody::Action {
+                action: Some(id), ..
+            },
+            ..
+        } if *id == subject => Some("action occurrence"),
+        SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange {
+                exchange: Some(id), ..
+            },
+            ..
+        } if *id == subject => Some("exchange occurrence"),
+        SharedBody::Occurrence {
+            body: OccurrenceBody::SequenceReference { sequence: Some(id) },
+            ..
+        } if *id == subject => Some("reused process / chain"),
+        _ => None,
+    }
+}
+
+impl Graph<'_> {
+    fn usage_bounds(&self, target: &Target) -> Option<Rectangle> {
+        match target {
+            Target::Whole => Some(Rectangle::new(Point::ORIGIN, self.size)),
+            Target::ProcessOccurrence(endpoint) => {
+                let root = endpoint
+                    .references
+                    .first()
+                    .copied()
+                    .unwrap_or(endpoint.occurrence);
+                let node = self.nodes.iter().find(|node| node.id == root)?;
+                if endpoint.references.is_empty() {
+                    Some(node.rect)
+                } else {
+                    // endpoint_rect intentionally has a proxy fallback for other callers;
+                    // a usage promises an actual tile and must never take that fallback.
+                    node.preview
+                        .iter()
+                        .any(|(shown, _)| shown == endpoint)
+                        .then(|| node.endpoint_rect(endpoint))
+                }
+            }
+            Target::ProcessLink(id) => {
+                let edge = self.edges.iter().find(|edge| edge.id == *id)?;
+                if !edge.guard.is_empty() {
+                    Some(edge.label)
+                } else {
+                    let segment = edge
+                        .points
+                        .windows(2)
+                        .nth(edge.points.len().saturating_sub(1) / 2)?;
+                    let center = Point::new(
+                        (segment[0].x + segment[1].x) / 2.,
+                        (segment[0].y + segment[1].y) / 2.,
+                    );
+                    Some(Rectangle::new(
+                        center - iced::Vector::new(16., 16.),
+                        Size::new(32., 32.),
+                    ))
+                }
+            }
+            Target::ProcessPreviewLink {
+                relation,
+                source,
+                target,
+            } => {
+                let node = self
+                    .nodes
+                    .iter()
+                    .find(|node| source.references.first() == Some(&node.id))?;
+                let link = node.preview_links.iter().find(|link| {
+                    link.relation == *relation && link.source == *source && link.target == *target
+                })?;
+                let [a, b] = node.preview_link_visible_segment(link)?;
+                Some(Rectangle::new(
+                    Point::new((a.x + b.x) / 2. - 16., (a.y + b.y) / 2. - 16.),
+                    Size::new(32., 32.),
+                ))
+            }
+            _ => None,
+        }
+    }
+}
+
+impl State {
+    /// Inactive owners use the same default preview policy as entering their canvas.
+    fn usage_graph<'a>(&self, p: &'a Project, owner: Id) -> Graph<'a> {
+        if self.identity.is_some_and(|(_, current)| current == owner) {
+            Graph::expanded_qualified(p, owner, owner, &self.expanded, &self.contextual_expanded)
+        } else {
+            Graph::new(p, owner, owner)
+        }
+    }
+
+    pub(crate) fn diagram_usages(&self, p: &Project, owner: Id, subject: Id) -> Vec<Usage> {
+        if !owner_exists(p, owner)
+            || !(p.elements.contains_key(&subject) || p.relations.contains_key(&subject))
+        {
+            return vec![];
+        }
+        let graph = self.usage_graph(p, owner);
+        let mut usages = vec![];
+        let mut add = |target: Target, role: &str| {
+            if let Some(bounds) = graph.usage_bounds(&target) {
+                usages.push(Usage {
+                    subject,
+                    surface: Surface::Process(owner),
+                    target,
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        };
+        if subject == owner {
+            add(Target::Whole, "process / chain canvas");
+        }
+        for node in &graph.nodes {
+            if let Some(role) = occurrence_role(p, node.id, subject) {
+                add(
+                    Target::ProcessOccurrence(OccurrenceEndpoint {
+                        references: vec![],
+                        occurrence: node.id,
+                    }),
+                    role,
+                );
+            }
+            for (endpoint, _) in &node.preview {
+                if let Some(role) = occurrence_role(p, endpoint.occurrence, subject) {
+                    add(
+                        Target::ProcessOccurrence(endpoint.clone()),
+                        &format!("reused {role}"),
+                    );
+                }
+            }
+            for link in &node.preview_links {
+                if link.relation == subject {
+                    add(
+                        Target::ProcessPreviewLink {
+                            relation: link.relation,
+                            source: link.source.clone(),
+                            target: link.target.clone(),
+                        },
+                        "reused sequence link",
+                    );
+                }
+            }
+        }
+        for edge in &graph.edges {
+            let role = if edge.id == subject {
+                Some("process link")
+            } else {
+                match p.relations.get(&edge.id).map(|r| &r.body) {
+                    Some(RelationBody::ContextualLink {
+                        purpose: ContextualLinkPurpose::Exchange { exchange },
+                        ..
+                    }) if *exchange == subject => Some("assembly exchange"),
+                    Some(RelationBody::ContextualLink {
+                        purpose: ContextualLinkPurpose::CommonWork { work },
+                        ..
+                    }) if *work == subject => Some("common work"),
+                    _ => None,
+                }
+            };
+            if let Some(role) = role {
+                add(Target::ProcessLink(edge.id), role);
+            }
+        }
+        usages
+    }
+
+    /// Returns success, not whether the camera changed. App must separately guard
+    /// its other drafts and revalidate the queried subject's current usage.
+    pub(crate) fn reveal_usage(
+        &mut self,
+        p: &Project,
+        document: Id,
+        owner: Id,
+        target: &Target,
+    ) -> bool {
+        if !owner_exists(p, owner) || self.draft.is_some() {
+            return false;
+        }
+        let same = self.identity == Some((document, owner));
+        let graph = if same {
+            self.usage_graph(p, owner)
+        } else {
+            Graph::new(p, owner, owner)
+        };
+        let Some(bounds) = graph.usage_bounds(target) else {
+            return false;
+        };
+        let address = if let Target::ProcessOccurrence(endpoint) = target {
+            let Ok(resolved) =
+                oa_core::topology_context::TopologyIndex::new(p).resolve(owner, endpoint)
+            else {
+                return false;
+            };
+            (!endpoint.references.is_empty()).then_some(resolved.address)
+        } else {
+            None
+        };
+        let viewport = self.viewport.unwrap_or(Size::new(500., 300.));
+        self.enter(document, owner);
+        if !same {
+            self.contextual_expanded.clear();
+        }
+        self.selected_context = address;
+        self.tool = CanvasTool::Select;
+        self.viewport = Some(viewport);
+        let fit = ((viewport.width - 48.).max(1.) / bounds.width.max(1.))
+            .min((viewport.height - 48.).max(1.) / bounds.height.max(1.));
+        let scale = if matches!(target, Target::Whole) {
+            fit.clamp(0.0001, 1.)
+        } else {
+            fit.clamp(0.6, 1.25)
+        };
+        self.zoom = Some(scale);
+        self.fit = false;
+        self.pan = iced::Vector::new(
+            viewport.width / 2. - bounds.center_x() * scale,
+            viewport.height / 2. - bounds.center_y() * scale,
+        );
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior/topology/usages/tests.rs

@@ -0,0 +1,439 @@
+use super::*;
+
+fn add(p: &mut Project, owner: Id, name: &str, body: OccurrenceBody) -> Id {
+    let e = occurrence(p, owner, name, body);
+    let id = e.id;
+    *p = execute_batch(p, &[Command::CreateElement(e)]).unwrap();
+    id
+}
+
+fn reused_fixture() -> (Project, Id, Id, Id, [Id; 2], Vec<Id>) {
+    let f = super::super::direct_tests::fixture(Layer::Oa);
+    let mut p = f.p;
+    let sequence = p
+        .make_element(Kind::Process, Layer::Oa, "Reviewed checks", None)
+        .unwrap();
+    let sequence_id = sequence.id;
+    p = execute_batch(&p, &[Command::CreateElement(sequence)]).unwrap();
+    let mut leaves = vec![];
+    for name in [
+        "Check one",
+        "Check two",
+        "Check three",
+        "Check four",
+        "Check five",
+    ] {
+        leaves.push(add(
+            &mut p,
+            sequence_id,
+            name,
+            OccurrenceBody::Action {
+                action: Some(f.work[0]),
+                lifeline: None,
+            },
+        ));
+    }
+    let first = add(
+        &mut p,
+        f.owner,
+        "First invocation",
+        OccurrenceBody::SequenceReference {
+            sequence: Some(sequence_id),
+        },
+    );
+    let second = add(
+        &mut p,
+        f.owner,
+        "Second invocation",
+        OccurrenceBody::SequenceReference {
+            sequence: Some(sequence_id),
+        },
+    );
+    (p, f.owner, sequence_id, f.work[0], [first, second], leaves)
+}
+
+#[test]
+fn process_usages_exclude_endpoint_coincidence_and_keep_actual_occurrences_and_links() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let f = super::super::direct_tests::fixture(layer);
+        let mut p = f.p;
+        let state = State::default();
+        // Both exchange endpoints have Action contributions, but there is no
+        // Exchange occurrence and no exchange arrow in this process.
+        assert!(state.diagram_usages(&p, f.owner, f.exchange).is_empty());
+        let direct = state.diagram_usages(&p, f.owner, f.work[0]);
+        assert_eq!(direct.len(), 1);
+        assert_eq!(
+            direct[0].target,
+            Target::ProcessOccurrence(OccurrenceEndpoint {
+                references: vec![],
+                occurrence: f.nodes[0]
+            })
+        );
+        let link = state.diagram_usages(&p, f.owner, f.link);
+        assert_eq!(link.len(), 1);
+        assert_eq!(link[0].target, Target::ProcessLink(f.link));
+        let first = add(
+            &mut p,
+            f.owner,
+            "First exchange",
+            OccurrenceBody::Exchange {
+                exchange: Some(f.exchange),
+                sender: None,
+                receiver: None,
+                message_kind: MessageKind::Asynchronous,
+                reply_to: None,
+                values: vec![],
+                operation: None,
+            },
+        );
+        let second = add(
+            &mut p,
+            f.owner,
+            "Second exchange",
+            OccurrenceBody::Exchange {
+                exchange: Some(f.exchange),
+                sender: None,
+                receiver: None,
+                message_kind: MessageKind::Asynchronous,
+                reply_to: None,
+                values: vec![],
+                operation: None,
+            },
+        );
+        let usages = state.diagram_usages(&p, f.owner, f.exchange);
+        assert_eq!(usages.len(), 2);
+        assert_eq!(
+            usages
+                .iter()
+                .map(|usage| usage.target.clone())
+                .collect::<Vec<_>>(),
+            vec![
+                Target::ProcessOccurrence(OccurrenceEndpoint {
+                    references: vec![],
+                    occurrence: first
+                }),
+                Target::ProcessOccurrence(OccurrenceEndpoint {
+                    references: vec![],
+                    occurrence: second
+                }),
+            ]
+        );
+    }
+}
+
+#[test]
+fn process_usages_keep_caller_paths_and_exclude_unshown_fifth_preview() {
+    let (p, owner, sequence, work, calls, leaves) = reused_fixture();
+    let before = p.clone();
+    let mut state = State::default();
+    let leaf = state.diagram_usages(&p, owner, leaves[0]);
+    assert_eq!(leaf.len(), 2);
+    for (usage, call) in leaf.iter().zip(calls) {
+        assert_eq!(
+            usage.target,
+            Target::ProcessOccurrence(OccurrenceEndpoint {
+                references: vec![call],
+                occurrence: leaves[0]
+            })
+        );
+    }
+    assert_ne!(leaf[0].bounds, leaf[1].bounds);
+    assert!(state.diagram_usages(&p, owner, leaves[4]).is_empty());
+    assert_eq!(state.diagram_usages(&p, owner, sequence).len(), 2);
+    // One local action and four tiles in each of two caller boxes.
+    assert_eq!(state.diagram_usages(&p, owner, work).len(), 9);
+    state.enter(Id::new_v4(), owner);
+    assert!(state.expand(&p, owner, calls[0]));
+    let fifth = state.diagram_usages(&p, owner, leaves[4]);
+    assert_eq!(fifth.len(), 1);
+    assert_eq!(
+        fifth[0].target,
+        Target::ProcessOccurrence(OccurrenceEndpoint {
+            references: vec![calls[0]],
+            occurrence: leaves[4]
+        })
+    );
+    // Another active owner must not leak its expansion to this queried canvas.
+    state.enter(Id::new_v4(), sequence);
+    assert!(state.diagram_usages(&p, owner, leaves[4]).is_empty());
+    assert_eq!(p, before);
+}
+
+#[test]
+fn process_usage_reveal_validates_before_state_changes_and_centers_the_exact_tile() {
+    let (p, owner, _, _, calls, leaves) = reused_fixture();
+    let before = p.clone();
+    let document = Id::new_v4();
+    let mut state = State::default();
+    state.enter(document, owner);
+    state.viewport(Size::new(880., 460.));
+    state.pan = iced::Vector::new(-3000., -900.);
+    let hidden = Target::ProcessOccurrence(OccurrenceEndpoint {
+        references: vec![calls[0]],
+        occurrence: leaves[4],
+    });
+    let prior = (
+        state.identity,
+        state.pan,
+        state.zoom,
+        state.fit,
+        state.selected_context.clone(),
+    );
+    assert!(!state.reveal_usage(&p, document, owner, &hidden));
+    assert_eq!(
+        (
+            state.identity,
+            state.pan,
+            state.zoom,
+            state.fit,
+            state.selected_context.clone()
+        ),
+        prior
+    );
+    assert!(!state.reveal_usage(&p, document, Id::new_v4(), &Target::Whole));
+    assert_eq!(
+        (
+            state.identity,
+            state.pan,
+            state.zoom,
+            state.fit,
+            state.selected_context.clone()
+        ),
+        prior
+    );
+    let endpoint = OccurrenceEndpoint {
+        references: vec![calls[1]],
+        occurrence: leaves[0],
+    };
+    let target = Target::ProcessOccurrence(endpoint.clone());
+    assert!(state.reveal_usage(&p, document, owner, &target));
+    assert_eq!(state.selected_context.as_ref().unwrap().endpoint, endpoint);
+    let bounds = state
+        .diagram_usages(&p, owner, leaves[0])
+        .into_iter()
+        .find(|usage| usage.target == target)
+        .unwrap()
+        .bounds;
+    let scale = state.zoom.unwrap();
+    assert!(scale >= 0.6);
+    assert!((bounds.center_x() * scale + state.pan.x - 440.).abs() < 0.01);
+    assert!((bounds.center_y() * scale + state.pan.y - 230.).abs() < 0.01);
+    assert!(state.reveal_usage(&p, document, owner, &Target::Whole));
+    assert!(state.selected_context.is_none());
+    state
+        .update(&p, Event::Start(owner, Tool::Work, None))
+        .unwrap();
+    let draft = state.recovery_snapshot().unwrap();
+    let camera = (state.pan, state.zoom, state.fit);
+    assert!(!state.reveal_usage(&p, document, owner, &target));
+    assert_eq!(state.recovery_snapshot().unwrap(), draft);
+    assert_eq!((state.pan, state.zoom, state.fit), camera);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn process_contextual_purpose_and_painted_preview_links_keep_distinct_identities() {
+    let (mut p, owner, sequence, work, calls, leaves) = reused_fixture();
+    let source = OccurrenceEndpoint {
+        references: vec![calls[0]],
+        occurrence: leaves[0],
+    };
+    let target = OccurrenceEndpoint {
+        references: vec![calls[1]],
+        occurrence: leaves[0],
+    };
+    let relation = Relation {
+        id: Id::new_v4(),
+        alias: "same_check".into(),
+        name: "One common check".into(),
+        description: String::new(),
+        body: RelationBody::ContextualLink {
+            owner,
+            source,
+            target,
+            purpose: ContextualLinkPurpose::CommonWork { work },
+        },
+    };
+    let contextual = relation.id;
+    p = execute_batch(&p, &[Command::CreateRelation(relation)]).unwrap();
+    let Command::CreateRelation(relation) = link(&p, leaves[0], leaves[1], "next") else {
+        unreachable!()
+    };
+    let local_link = relation.id;
+    p = execute_batch(&p, &[Command::CreateRelation(relation)]).unwrap();
+    let state = State::default();
+    assert!(
+        state
+            .diagram_usages(&p, owner, work)
+            .iter()
+            .any(|usage| usage.target == Target::ProcessLink(contextual)
+                && usage.role == "common work")
+    );
+    assert_eq!(state.diagram_usages(&p, owner, contextual).len(), 1);
+    let previews = state.diagram_usages(&p, owner, local_link);
+    assert_eq!(previews.len(), 2);
+    for (usage, call) in previews.iter().zip(calls) {
+        assert_eq!(
+            usage.target,
+            Target::ProcessPreviewLink {
+                relation: local_link,
+                source: OccurrenceEndpoint {
+                    references: vec![call],
+                    occurrence: leaves[0]
+                },
+                target: OccurrenceEndpoint {
+                    references: vec![call],
+                    occurrence: leaves[1]
+                },
+            }
+        );
+    }
+    assert_eq!(state.diagram_usages(&p, sequence, local_link).len(), 1);
+}
+
+#[test]
+fn preview_arrow_focus_is_in_the_painted_gap_and_hidden_endpoints_never_fallback() {
+    let (mut p, owner, _, _, calls, leaves) = reused_fixture();
+    let Command::CreateRelation(shown) = link(&p, leaves[0], leaves[1], "next") else {
+        unreachable!()
+    };
+    let shown_id = shown.id;
+    p = execute_batch(&p, &[Command::CreateRelation(shown)]).unwrap();
+    let Command::CreateRelation(hidden) = link(&p, leaves[0], leaves[4], "later") else {
+        unreachable!()
+    };
+    let hidden_id = hidden.id;
+    p = execute_batch(&p, &[Command::CreateRelation(hidden)]).unwrap();
+    let before = p.clone();
+    let document = Id::new_v4();
+    let mut state = State::default();
+    state.enter(document, owner);
+    state.viewport(Size::new(800., 460.));
+    let rows = state.diagram_usages(&p, owner, shown_id);
+    assert_eq!(rows.len(), 2);
+    let graph = Graph::new(&p, owner, owner);
+    for (row, call) in rows.iter().zip(calls) {
+        let node = graph.nodes.iter().find(|n| n.id == call).unwrap();
+        // The painter places 113px tiles 125px apart, beginning 12px in.
+        // The 12px gap is centered 131px into the caller, 134px below its top.
+        assert_eq!(
+            row.bounds.center(),
+            Point::new(node.rect.x + 131., node.rect.y + 134.)
+        );
+        assert!(
+            node.preview
+                .iter()
+                .all(|(e, _)| !node.endpoint_rect(e).contains(row.bounds.center()))
+        );
+    }
+    assert_ne!(rows[0].bounds, rows[1].bounds);
+    assert!(state.diagram_usages(&p, owner, hidden_id).is_empty());
+    assert!(state.reveal_usage(&p, document, owner, &rows[1].target));
+    assert!(
+        state.selected_context.is_none(),
+        "an arrow is not an occurrence authoring context"
+    );
+    let zoom = state.zoom.unwrap();
+    assert!((rows[1].bounds.center_x() * zoom + state.pan.x - 400.).abs() < 0.01);
+    assert!((rows[1].bounds.center_y() * zoom + state.pan.y - 230.).abs() < 0.01);
+    assert!(state.expand(&p, owner, calls[0]));
+    let expanded = state.diagram_usages(&p, owner, hidden_id);
+    assert_eq!(expanded.len(), 1);
+    assert!(
+        matches!(&expanded[0].target, Target::ProcessPreviewLink { source, .. }
+        if source.references == vec![calls[0]])
+    );
+    let mut stale = rows[1].target.clone();
+    if let Target::ProcessPreviewLink { source, .. } = &mut stale {
+        source.references = vec![Id::new_v4()];
+    }
+    let prior = (state.pan, state.zoom, state.fit);
+    assert!(!state.reveal_usage(&p, document, owner, &stale));
+    assert_eq!((state.pan, state.zoom, state.fit), prior);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn visible_preview_segment_excludes_all_opaque_tiles_for_reverse_and_cross_row_arrows() {
+    let tiles = [
+        Rectangle::new(Point::new(12., 118.), Size::new(113., 32.)),
+        Rectangle::new(Point::new(137., 118.), Size::new(113., 32.)),
+        Rectangle::new(Point::new(12., 162.), Size::new(113., 32.)),
+        Rectangle::new(Point::new(137., 162.), Size::new(113., 32.)),
+    ];
+    for points in [
+        [Point::new(250., 134.), Point::new(12., 134.)],
+        [Point::new(125., 134.), Point::new(137., 178.)],
+        [Point::new(250., 178.), Point::new(12., 134.)],
+    ] {
+        let [a, b] = visible_preview_segment(points, tiles.into_iter()).unwrap();
+        for fraction in [0.1, 0.5, 0.9] {
+            let point = a + (b - a) * fraction;
+            assert!(tiles.iter().all(|tile| !tile.contains(point)));
+        }
+    }
+    assert!(
+        visible_preview_segment(
+            [Point::new(30., 134.), Point::new(100., 134.)],
+            tiles.into_iter()
+        )
+        .is_none()
+    );
+    assert!(
+        visible_preview_segment([Point::new(1., 1.), Point::new(1., 1.)], tiles.into_iter())
+            .is_none()
+    );
+}
+
+#[test]
+fn expanded_nested_tiles_do_not_invent_links_the_preview_painter_does_not_emit() {
+    let (mut p, owner, sequence, work, calls, _) = reused_fixture();
+    let nested = p
+        .make_element(Kind::Process, Layer::Oa, "Nested checks", None)
+        .unwrap();
+    let nested_id = nested.id;
+    p = execute_batch(&p, &[Command::CreateElement(nested)]).unwrap();
+    let leaves: Vec<_> = ["Nested one", "Nested two"]
+        .into_iter()
+        .map(|name| {
+            add(
+                &mut p,
+                nested_id,
+                name,
+                OccurrenceBody::Action {
+                    action: Some(work),
+                    lifeline: None,
+                },
+            )
+        })
+        .collect();
+    let Command::CreateRelation(relation) = link(&p, leaves[0], leaves[1], "next") else {
+        unreachable!()
+    };
+    let relation_id = relation.id;
+    p = execute_batch(&p, &[Command::CreateRelation(relation)]).unwrap();
+    let reference = add(
+        &mut p,
+        sequence,
+        "Nested invocation",
+        OccurrenceBody::SequenceReference {
+            sequence: Some(nested_id),
+        },
+    );
+    let mut state = State::default();
+    state.enter(Id::new_v4(), owner);
+    state.expanded.insert(calls[0]);
+    state.contextual_expanded.insert(OccurrenceEndpoint {
+        references: vec![calls[0]],
+        occurrence: reference,
+    });
+    let shown = state.diagram_usages(&p, owner, leaves[0]);
+    assert_eq!(shown.len(), 1);
+    assert!(
+        matches!(&shown[0].target, Target::ProcessOccurrence(endpoint)
+        if endpoint.references == vec![calls[0], reference])
+    );
+    assert!(state.diagram_usages(&p, owner, relation_id).is_empty());
+    assert_eq!(state.diagram_usages(&p, nested_id, relation_id).len(), 1);
+}

crates/oa-desktop/src/behavior/topology/view.rs

@@ -66,107 +66,7 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
     let pending = state.draft.is_some();
     let ordered = !legacy_order(p, owner).is_empty();
     let selected = is_contribution(p, owner, app.selected).then_some(app.selected);
-    let choose = |tool| Message::TopologyCanvas(CanvasEvent::Choose(context, tool));
-    let mut controls = Column::new().spacing(6);
-    if !pending {
-        controls = controls
-            .push(
-                row![
-                    button("Select / reorder")
-                        .style(if state.tool == CanvasTool::Select {
-                            button::primary
-                        } else {
-                            style::nav
-                        })
-                        .on_press(choose(CanvasTool::Select)),
-                    button("Work")
-                        .style(
-                            if state.tool == CanvasTool::Add(Tool::Work, ControlKind::Choice) {
-                                button::primary
-                            } else {
-                                style::nav
-                            }
-                        )
-                        .on_press(choose(CanvasTool::Add(Tool::Work, ControlKind::Choice))),
-                    button("Exchange")
-                        .style(
-                            if state.tool == CanvasTool::Add(Tool::Exchange, ControlKind::Choice) {
-                                button::primary
-                            } else {
-                                style::nav
-                            }
-                        )
-                        .on_press(choose(CanvasTool::Add(Tool::Exchange, ControlKind::Choice))),
-                    button("Reuse")
-                        .style(
-                            if state.tool == CanvasTool::Add(Tool::Reuse, ControlKind::Choice) {
-                                button::primary
-                            } else {
-                                style::nav
-                            }
-                        )
-                        .on_press(choose(CanvasTool::Add(Tool::Reuse, ControlKind::Choice)))
-                ]
-                .spacing(6),
-            )
-            .push(
-                row![
-                    pick_list(
-                        vec![
-                            ControlKind::Choice,
-                            ControlKind::Merge,
-                            ControlKind::Fork,
-                            ControlKind::Join,
-                            ControlKind::Loop
-                        ]
-                        .into_iter()
-                        .map(ControlChoice)
-                        .collect::<Vec<_>>(),
-                        if let CanvasTool::Add(Tool::Control, kind) = state.tool {
-                            Some(ControlChoice(kind))
-                        } else {
-                            None
-                        },
-                        move |c| Message::TopologyCanvas(CanvasEvent::Choose(
-                            context,
-                            CanvasTool::Add(Tool::Control, c.0)
-                        ))
-                    )
-                    .placeholder("Draw control…")
-                    .text_size(12)
-                    .padding(8),
-                    button("Sequence link")
-                        .style(if state.tool == CanvasTool::Connect {
-                            button::primary
-                        } else {
-                            style::nav
-                        })
-                        .on_press(choose(CanvasTool::Connect)),
-                    button("Two paths…").on_press(event(Event::Start(
-                        owner,
-                        Tool::Branch,
-                        selected
-                    )))
-                ]
-                .spacing(6),
-            );
-    }
-    controls=controls.push(label(if pending{"Pending contribution · apply or cancel below"}else if ordered{"Ordered exchange path · click a path to insert or empty canvas to continue; the edit preserves its order"}else{match state.tool{
-        CanvasTool::Select=>"Select local contributions and paths · drag path endpoints to reconnect · ↕ reorders within a column",
-        CanvasTool::Connect=>"Sequence link · click or drag from preceding to following contribution · Escape cancels",
-        CanvasTool::Add(..)=>"Choose a highlighted path or contribution position · existing work stays shared · Escape cancels"}}));
-    if !pending && ordered {
-        controls = controls.push(button("Append exchange…").on_press(Message::TopologyCanvas(
-            CanvasEvent::AppendExchange(context),
-        )));
-        let commands = preserved_order(p, owner, None);
-        if !commands.is_empty() {
-            controls = controls.push(
-                button("Edit path links and guards")
-                    .on_press(Message::Command(unique_batch(p, commands))),
-            );
-        }
-    }
+    let clean = !app.behavior.has_pending() && !app.draft_dirty() && !app.source_dirty();
     // A fixed sibling keeps Iced's canvas scroll state through selection/form changes.
     let mut navigation = column![].spacing(6);
     if let Some(Relation {
@@ -211,11 +111,6 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
             );
         }
     }
-    if !pending {
-        controls = controls.push(button("Qualified link / assembly…").on_press(event(
-            Event::Start(owner, Tool::Contextual, Some(app.selected)),
-        )));
-    }
     if let Some(id) = selected {
         let mut actions =
             row![button("Contribution properties").on_press(Message::EditProperties(id))]
@@ -256,27 +151,105 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
             button("Back to caller").on_press(Message::TopologyCanvas(CanvasEvent::Back(context))),
         );
     }
-    let diagram = {
-        let mut graph = Graph::expanded_qualified(
-            p,
-            owner,
-            app.selected,
-            &state.expanded,
-            &state.contextual_expanded,
+    navigation = navigation
+        .push(
+            button("Two paths...").on_press_maybe(clean.then_some(event(Event::Start(
+                owner,
+                Tool::Branch,
+                selected,
+            )))),
+        )
+        .push(
+            button("Qualified link / assembly...").on_press_maybe(clean.then_some(event(
+                Event::Start(owner, Tool::Contextual, Some(app.selected)),
+            ))),
         );
-        graph.scale = state.scale(graph.size, (app.window_size.width - 600.).max(200.));
-        graph.interaction = Some((
-            context,
-            state.tool,
-            !app.behavior.has_pending() && !app.draft_dirty() && !app.source_dirty(),
-        ));
-        // Explicit graphs no longer have a scrolling page ancestor. A retained
-        // offset from an ordered view must not distort their pointer coordinates.
-        graph.scroll_offset = state.canvas_offset();
-        let scale = graph.scale;
-        let mut header = column![
-            row![
-                out.width(Fill),
+    if ordered {
+        navigation = navigation.push(button("Append exchange...").on_press_maybe(clean.then_some(
+            Message::TopologyCanvas(CanvasEvent::AppendExchange(context)),
+        )));
+        let commands = preserved_order(p, owner, None);
+        if !commands.is_empty() {
+            navigation = navigation.push(
+                button("Edit path links and guards")
+                    .on_press_maybe(clean.then_some(Message::Command(unique_batch(p, commands)))),
+            );
+        }
+    }
+    let mut graph = Graph::expanded_qualified(
+        p,
+        owner,
+        app.selected,
+        &state.expanded,
+        &state.contextual_expanded,
+    );
+    graph.selected_preview = state
+        .qualified_selection(p, owner)
+        .filter(|address| {
+            address
+                .endpoint
+                .references
+                .first()
+                .copied()
+                .unwrap_or(address.endpoint.occurrence)
+                == app.selected
+        })
+        .map(|address| address.endpoint.clone());
+    graph.selected_preview_link = app
+        .diagram_focus(crate::diagram_usage::Surface::Process(owner))
+        .and_then(|usage| match &usage.target {
+            crate::diagram_usage::Target::ProcessPreviewLink {
+                relation,
+                source,
+                target,
+            } => Some(PreviewLink {
+                relation: *relation,
+                source: source.clone(),
+                target: target.clone(),
+            }),
+            _ => None,
+        });
+    graph.scale = state.scale(graph.size, (app.window_size.width - 600.).max(200.));
+    graph.camera_pan = state.pan;
+    graph.pending_insertion = state
+        .draft
+        .as_ref()
+        .filter(|d| d.owner == owner && d.fixed)
+        .map(|d| d.insertion);
+    graph.interaction = Some((context, state.tool, clean));
+    let scale = graph.scale;
+    let scope = super::super::canvas_workspace::Scope {
+        document: context.document,
+        owner,
+        revision: context.revision,
+        epoch: app.camera_epoch,
+    };
+    let keyboard = clean && super::super::canvas_workspace::keyboard_enabled(app);
+    let camera = move |e| Message::TopologyCanvas(CanvasEvent::Camera(context, scope.epoch, e));
+    let canvas = container(
+        iced::widget::sensor(
+            super::super::canvas_workspace::Viewport::new(
+                canvas::Canvas::new(graph).width(Fill).height(Fill),
+                scope,
+                scale,
+                keyboard,
+                camera,
+            )
+            .pan_background(state.tool == CanvasTool::Select),
+        )
+        .key((context.document, owner))
+        .on_show(move |size| Message::TopologyCanvas(CanvasEvent::Viewport(context, size)))
+        .on_resize(move |size| Message::TopologyCanvas(CanvasEvent::Viewport(context, size))),
+    )
+    .id("process-viewport")
+    .width(Fill)
+    .height(Fill)
+    .style(style::card)
+    .into();
+    let header = column![
+        row![
+            out.width(Fill),
+            super::super::canvas_workspace::Control::new(
                 button(
                     text(if state.focused {
                         "Restore panels"
@@ -285,121 +258,104 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
                     })
                     .size(12)
                 )
-                .on_press(Message::TopologyCanvas(CanvasEvent::Focus(context)))
                 .padding(6)
-            ]
-            .spacing(6)
-            .align_y(iced::Center),
-            row![
-                button(text("Tools").size(12))
-                    .padding(6)
-                    .style(if state.shelf == Some(Shelf::Tools) {
-                        button::primary
-                    } else {
-                        style::nav
-                    })
-                    .on_press(event(Event::Shelf(Shelf::Tools))),
-                button(text("Selection details").size(12))
-                    .padding(6)
-                    .style(if state.shelf == Some(Shelf::Selection) {
-                        button::primary
-                    } else {
-                        style::nav
-                    })
-                    .on_press(event(Event::Shelf(Shelf::Selection))),
-                button(text("Fit overview").size(12))
-                    .padding(6)
-                    .on_press(Message::TopologyCanvas(CanvasEvent::Zoom(context, None))),
-                button(text("−").size(12))
-                    .padding(6)
-                    .on_press(Message::TopologyCanvas(CanvasEvent::Zoom(
-                        context,
-                        Some(scale / 1.25)
-                    ))),
-                label(format!("{:.0}%", scale * 100.)),
-                button(text("+").size(12))
-                    .padding(6)
-                    .on_press(Message::TopologyCanvas(CanvasEvent::Zoom(
-                        context,
-                        Some(scale * 1.25)
-                    ))),
-                button(text("100%").size(12))
-                    .padding(6)
-                    .on_press(Message::TopologyCanvas(CanvasEvent::Zoom(
-                        context,
-                        Some(1.)
-                    )))
-            ]
-            .spacing(6)
-            .wrap(),
+                .on_press(super::super::canvas_workspace::intent(
+                    scope,
+                    "Panels",
+                    Message::TopologyCanvas(CanvasEvent::Focus(context))
+                )),
+                scope,
+                "Panels",
+                keyboard,
+                Some(super::super::canvas_workspace::intent(
+                    scope,
+                    "Panels",
+                    Message::TopologyCanvas(CanvasEvent::Focus(context))
+                )),
+                camera
+            )
         ]
-        .spacing(6);
-        if state.fit_limited(graph.size, (app.window_size.width - 600.).max(200.)) {
-            header = header
-                .push(text("Minimum zoom reached · scroll to see the remaining graph.").size(11));
-        }
-        if graph.nodes.is_empty() {
-            controls = controls.push(label(
-                "Choose Work, Exchange, Reuse or a control, then click the canvas to start.",
-            ));
-        }
-        let size = Size::new(graph.size.width * scale, graph.size.height * scale);
-        let canvas = scrollable(
-            canvas::Canvas::new(graph)
-                .width(size.width)
-                .height(size.height),
-        )
-        .id("process-canvas")
-        .direction(scrollable::Direction::Both {
-            vertical: scrollable::Scrollbar::default(),
-            horizontal: scrollable::Scrollbar::default(),
-        })
-        .width(Fill)
-        .height(Fill);
-        let canvas = container(
-            iced::widget::sensor(super::super::scenario_scroll::observe_topology(
+        .spacing(6),
+        super::super::canvas_workspace::controls(
+            scope,
+            keyboard,
+            scale,
+            event(Event::Shelf(Shelf::Selection)),
+            clean.then_some(Message::TopologyCanvas(CanvasEvent::Camera(
                 context,
-                scenario::ScrollArea::Canvas,
-                canvas,
-            ))
-            .on_show(move |size| Message::TopologyCanvas(CanvasEvent::Viewport(context, size)))
-            .on_resize(move |size| Message::TopologyCanvas(CanvasEvent::Viewport(context, size))),
+                scope.epoch,
+                super::super::canvas_workspace::Event::Focus
+            ))),
+            move |zoom| Message::TopologyCanvas(CanvasEvent::Zoom(context, zoom)),
+            camera
         )
-        .padding(8)
-        .width(Fill)
-        .height(Fill)
-        .style(style::card);
-        if !pending && !p.children(owner).any(|e| is_contribution(p, owner, e.id)) {
-            let title = if p.layer_of(owner) == Some(Layer::Oa) {
-                "Add first activity contribution"
-            } else {
-                "Add first function contribution"
-            };
-            header = header.push(button(title).on_press_maybe(
-                (!app.behavior.has_pending() && !app.draft_dirty() && !app.source_dirty()).then(
-                    || {
-                        Message::TopologyCanvas(CanvasEvent::Begin {
-                            context,
-                            tool: Tool::Work,
-                            control: ControlKind::Choice,
-                            insertion: Insertion::default(),
-                        })
-                    },
-                ),
-            ));
-        }
-        let details: Element<'_, Message> = match state.shelf {
-            Some(Shelf::Tools) => controls.into(),
-            _ => navigation.push(text("Full qualified identities and definition actions appear here for the selected contribution or link.").size(11)).into(),
-        };
-        explicit_pane(
-            header.into(),
-            details,
-            canvas.into(),
-            state.shelf.is_some(),
-            pending,
-        )
-    };
+    ]
+    .spacing(4);
+    let entries = [
+        ("S", "Select contributions or paths", CanvasTool::Select),
+        (
+            "W",
+            "Work: click a path or empty space",
+            CanvasTool::Add(Tool::Work, ControlKind::Choice),
+        ),
+        (
+            "E",
+            "Exchange: click a path or empty space",
+            CanvasTool::Add(Tool::Exchange, ControlKind::Choice),
+        ),
+        (
+            "ref",
+            "Reuse process / chain",
+            CanvasTool::Add(Tool::Reuse, ControlKind::Choice),
+        ),
+        (
+            "OR",
+            "Choice",
+            CanvasTool::Add(Tool::Control, ControlKind::Choice),
+        ),
+        (
+            "M",
+            "Merge",
+            CanvasTool::Add(Tool::Control, ControlKind::Merge),
+        ),
+        (
+            "AND",
+            "Fork",
+            CanvasTool::Add(Tool::Control, ControlKind::Fork),
+        ),
+        (
+            "J",
+            "Join",
+            CanvasTool::Add(Tool::Control, ControlKind::Join),
+        ),
+        (
+            "IT",
+            "Loop",
+            CanvasTool::Add(Tool::Control, ControlKind::Loop),
+        ),
+        (
+            "->",
+            "Sequence link: click or drag between contributions",
+            CanvasTool::Connect,
+        ),
+    ];
+    let palette = super::super::canvas_workspace::palette(
+        scope,
+        keyboard,
+        camera,
+        entries.into_iter().map(|(glyph, label, choice)| {
+            (
+                glyph,
+                label,
+                choice == state.tool,
+                clean.then_some(Message::TopologyCanvas(CanvasEvent::Choose(
+                    context, choice,
+                ))),
+            )
+        }),
+    );
+    let details = scrollable(navigation.push(text("Layout is derived. The reorder handle changes display order within its column; it does not author a position.").size(11)))
+        .id("process-details").width(Fill).height(Fill).into();
     let mut form_panel: Element<'_, Message> = iced::widget::Space::new().height(0).into();
     if let Some(d) = state.draft.as_ref().filter(|d| d.owner == owner) {
         if let Some(child) = d.source.view(p) {
@@ -617,77 +573,37 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
                 button("Cancel").on_press(event(Event::Cancel))
             ]
             .spacing(7);
-            form_panel = editor_panel(actions.into(), form.into());
+            form_panel = editor_panel(d.invocation, actions.into(), form.into());
         }
     }
-    panes(diagram, form_panel, pending)
-}
-
-/// A permanent three-slot tree: variable controls never remount the canvas.
-/// The shelf scrolls independently; the canvas receives actual remaining height.
-fn explicit_pane<'a, R: iced::advanced::text::Renderer + 'a>(
-    header: iced::Element<'a, Message, iced::Theme, R>,
-    details: iced::Element<'a, Message, iced::Theme, R>,
-    canvas: iced::Element<'a, Message, iced::Theme, R>,
-    show_details: bool,
-    pending: bool,
-) -> iced::Element<'a, Message, iced::Theme, R> {
-    // Column::push drops Fixed(0) children. from_vec retains the closed shelf
-    // slot so its disclosure cannot move/remount the following canvas tree.
-    Column::from_vec(vec![
-        container(header).width(Fill).into(),
-        scrollable(details)
-            .id("process-details")
-            .width(Fill)
-            .height(if show_details {
-                if pending { 64. } else { 112. }
-            } else {
-                0.
-            })
-            .into(),
-        container(canvas).width(Fill).height(Fill).into(),
-    ])
-    .spacing(6)
-    .padding(8)
-    .width(Fill)
-    .height(Fill)
-    .into()
-}
-
-/// Keep the diagram mounted while an independent editor uses the remaining
-/// workspace height. The editor must never be clipped by the page scrollable.
-fn panes<'a, R: iced::advanced::Renderer + 'a>(
-    diagram: iced::Element<'a, Message, iced::Theme, R>,
-    form: iced::Element<'a, Message, iced::Theme, R>,
-    pending: bool,
-) -> iced::Element<'a, Message, iced::Theme, R> {
-    column![
-        container(diagram).width(Fill).height(if pending {
-            iced::Length::FillPortion(1)
-        } else {
-            Fill
-        }),
-        container(form).width(Fill).height(if pending {
-            iced::Length::FillPortion(1)
-        } else {
-            iced::Length::Shrink
-        }),
-    ]
-    .width(Fill)
-    .height(Fill)
-    .into()
+    let editor = if pending {
+        Some(form_panel)
+    } else {
+        state.shelf.map(|_| details)
+    };
+    super::super::canvas_workspace::host(header.into(), palette, canvas, editor)
 }
 
 fn editor_panel<'a, R: iced::advanced::text::Renderer + 'a>(
+    session: Id,
     actions: iced::Element<'a, Message, iced::Theme, R>,
     fields: iced::Element<'a, Message, iced::Theme, R>,
 ) -> iced::Element<'a, Message, iced::Theme, R> {
     container(
-        container(column![actions, scrollable(fields).id("process-form").height(Fill)].spacing(8))
-            .width(Fill)
-            .height(Fill)
-            .padding(12)
-            .style(style::card),
+        container(
+            column![
+                container(actions).id("process-actions"),
+                super::super::form_session::reset_on_change(
+                    session,
+                    scrollable(fields).id("process-form").height(Fill)
+                )
+            ]
+            .spacing(8),
+        )
+        .width(Fill)
+        .height(Fill)
+        .padding(12)
+        .style(style::card),
     )
     .width(Fill)
     .height(Fill)

crates/oa-desktop/src/diagram.rs

@@ -41,6 +41,8 @@ pub struct DiagramCanvas<'a> {
     pub view_index: Option<&'a oa_core::view_options::ViewIndex>,
     pub diagram: Id,
     pub selected: Id,
+    /// Presentation-only navigation marker; never used by hit tests or edits.
+    pub navigation_focus: Option<Rectangle>,
     pub zoom: f32,
     pub pan: Vector,
     pub context: Context,
@@ -1193,6 +1195,14 @@ impl canvas::Program<Message> for DiagramCanvas<'_> {
                 f.fill(&Path::circle(center, 1.5), color);
             }
         }
+        if let Some(bounds) = self.navigation_focus {
+            f.stroke(
+                &Path::rectangle(bounds.position(), bounds.size()),
+                Stroke::default()
+                    .with_color(style::TEAL)
+                    .with_width(2.5 / self.zoom),
+            );
+        }
         if let Some(edge) = scene.routed.edges.get(&self.selected)
             && !edge.custom_suspended
         {
@@ -1902,6 +1912,7 @@ mod tests {
             connection: None,
             diagram,
             selected: p.id,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::ZERO,
         };
@@ -1976,6 +1987,7 @@ mod tests {
             connection: None,
             diagram,
             selected: p.id,
+            navigation_focus: None,
             zoom: 0.6,
             pan: Vector::new(10., 20.),
         };
@@ -2092,6 +2104,7 @@ mod tests {
                 diagram,
                 context,
                 selected: p.id,
+                navigation_focus: None,
                 selected_bend: None,
                 zoom,
                 pan: Vector::new(20., 30.),
@@ -2259,6 +2272,7 @@ mod tests {
                 view_index: None,
                 diagram,
                 selected: edge,
+                navigation_focus: None,
                 zoom,
                 pan: Vector::new(150., 300.),
                 context: Context {
@@ -2334,6 +2348,7 @@ mod tests {
             view_index: None,
             diagram,
             selected: edge,
+            navigation_focus: None,
             zoom: 0.5,
             pan: Vector::new(150., 300.),
             context: Context {
@@ -2430,6 +2445,7 @@ mod tests {
             view_index: None,
             diagram,
             selected: edge,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::new(150., 300.),
             context: Context {
@@ -2557,6 +2573,7 @@ mod tests {
                 view_index: None,
                 diagram,
                 selected: edge,
+                navigation_focus: None,
                 zoom: 0.7,
                 pan: Vector::new(350., 350.),
                 context: Context {
@@ -2610,6 +2627,7 @@ mod tests {
             view_index: None,
             diagram,
             selected: p.id,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::new(100., 400.),
             context: Context {
@@ -2683,6 +2701,7 @@ mod tests {
             view_index: None,
             diagram,
             selected: edge,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::new(100., 400.),
             context: Context {
@@ -2715,6 +2734,7 @@ mod tests {
             view_index: None,
             diagram,
             selected,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::ZERO,
             context: Context {

crates/oa-desktop/src/diagram/lifecycle_tests.rs

@@ -57,6 +57,7 @@ fn canvas(app: &App) -> DiagramCanvas<'_> {
         view_index: None,
         diagram: app.active_diagram.unwrap(),
         selected: app.selected,
+        navigation_focus: None,
         zoom: 1.,
         pan: app.pan,
         context: app.route_context().unwrap(),

crates/oa-desktop/src/diagram/pointer_tests.rs

@@ -65,6 +65,7 @@ fn canvas(app: &App, zoom: f32) -> DiagramCanvas<'_> {
         view_index: None,
         diagram: app.active_diagram.unwrap(),
         selected: app.selected,
+        navigation_focus: None,
         zoom,
         pan: app.pan,
         context: app.route_context().unwrap(),

crates/oa-desktop/src/diagram/port_hit_tests.rs

@@ -6,6 +6,7 @@ fn canvas(project: &Project, diagram: Id, zoom: f32) -> DiagramCanvas<'_> {
         view_index: None,
         diagram,
         selected: Id::nil(),
+        navigation_focus: None,
         zoom,
         pan: Vector::new(17., 23.),
         context: Context {

crates/oa-desktop/src/diagram/port_labels.rs

@@ -178,6 +178,7 @@ mod tests {
             view_index: None,
             diagram: app.active_diagram.unwrap(),
             selected: app.selected,
+            navigation_focus: None,
             zoom: 1.,
             pan: Vector::ZERO,
             context: app.route_context().unwrap(),

crates/oa-desktop/src/diagram_usage.rs

@@ -0,0 +1,472 @@
+//! Read-only identities for objects actually represented by a diagram renderer.
+use iced::Rectangle;
+use oa_core::{Id, OccurrenceEndpoint, Project, projection, routing, view_options::ViewIndex};
+pub(crate) mod view;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Context {
+    pub document: Id,
+    pub revision: u64,
+    pub subject: Id,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) enum Event {
+    Open(Context),
+    Close(Id),
+    Search(Id, String),
+    Page(Id, usize),
+    Destination(Id, Option<Surface>),
+    Choose(Id, Usage),
+    Move(Id, i8),
+    Activate(Id),
+}
+
+/// One completed immutable accepted-model lookup. The token owns one worker slot.
+#[derive(Debug, Clone)]
+pub(crate) struct Completion {
+    pub token: Id,
+    pub context: Context,
+    pub result: Result<Vec<Usage>, String>,
+}
+
+pub(crate) struct Panel {
+    pub token: Id,
+    pub context: Context,
+    pub usages: Vec<Usage>,
+    pub loading: bool,
+    pub search: String,
+    pub page: usize,
+    pub cursor: usize,
+    pub destination: Option<Surface>,
+    pub notice: Option<String>,
+}
+
+impl Panel {
+    pub fn new(context: Context, usages: Vec<Usage>) -> Self {
+        Self {
+            token: Id::new_v4(),
+            context,
+            usages,
+            loading: false,
+            search: String::new(),
+            page: 0,
+            cursor: 0,
+            destination: None,
+            notice: None,
+        }
+    }
+
+    pub fn matches<'a>(&'a self, p: &Project) -> Vec<&'a Usage> {
+        let query = self.search.to_lowercase();
+        if query.is_empty() {
+            return self.usages.iter().collect();
+        }
+        self.usages
+            .iter()
+            .filter(|usage| {
+                let surface = usage.surface;
+                let searchable = format!(
+                    "{} {} {} {} {}",
+                    surface.category(p),
+                    p.named(surface.id()),
+                    alias(p, surface.id()),
+                    target_name(p, usage),
+                    usage.role
+                );
+                searchable.to_lowercase().contains(&query)
+            })
+            .collect()
+    }
+
+    pub fn choices(&self, p: &Project) -> Vec<Event> {
+        if self.loading {
+            return Vec::new();
+        }
+        let matches = self.matches(p);
+        if let Some(surface) = self.destination {
+            matches
+                .into_iter()
+                .filter(|u| u.surface == surface)
+                .map(|u| Event::Choose(self.token, u.clone()))
+                .collect()
+        } else {
+            let mut seen = std::collections::BTreeSet::new();
+            matches
+                .into_iter()
+                .filter(|u| seen.insert(u.surface))
+                .map(|u| Event::Destination(self.token, Some(u.surface)))
+                .collect()
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) enum Surface {
+    Saved(Id),
+    Process(Id),
+    Scenario(Id),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum Target {
+    Whole,
+    Placement(Id),
+    Port {
+        port: Id,
+        placement: Id,
+    },
+    Edge(Id),
+    StateRow {
+        placement: Id,
+        relation: Id,
+    },
+    AllocationGrouping {
+        relation: Id,
+        work_placement: Id,
+        performer_placement: Id,
+    },
+    ProcessOccurrence(OccurrenceEndpoint),
+    ProcessLink(Id),
+    ProcessPreviewLink {
+        relation: Id,
+        source: OccurrenceEndpoint,
+        target: OccurrenceEndpoint,
+    },
+    ScenarioObject(Id),
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct Usage {
+    pub subject: Id,
+    pub surface: Surface,
+    pub target: Target,
+    /// Concise, truthful explanation, e.g. "action occurrence" or "entry action".
+    pub role: String,
+    /// Actual current renderer coordinates. Recompute before activation.
+    pub bounds: Rectangle,
+}
+
+/// A navigation highlight is presentation state, never an edit/Delete target.
+pub(crate) struct Focus {
+    pub context: Context,
+    pub usage: Usage,
+    pub selected: Id,
+}
+
+impl Surface {
+    pub fn id(self) -> Id {
+        match self {
+            Self::Saved(id) | Self::Process(id) | Self::Scenario(id) => id,
+        }
+    }
+
+    pub fn category(self, p: &Project) -> &'static str {
+        match self {
+            Self::Saved(id)
+                if p.diagrams
+                    .get(&id)
+                    .is_some_and(|d| d.projection.state_machine().is_some()) =>
+            {
+                "State views"
+            }
+            Self::Saved(_) => "Architecture",
+            Self::Process(_) => "Processes and chains",
+            Self::Scenario(_) => "Scenarios",
+        }
+    }
+}
+
+pub(crate) fn collect(
+    p: &Project,
+    subject: Id,
+    process: &crate::behavior::topology::State,
+    scenario: &crate::behavior::scenario::State,
+) -> Vec<Usage> {
+    let mut usages = saved_usages(p, subject);
+    for element in p.elements.values() {
+        match element.kind() {
+            oa_core::Kind::Process | oa_core::Kind::FunctionalChain => {
+                usages.extend(process.diagram_usages(p, element.id, subject));
+            }
+            oa_core::Kind::Scenario => {
+                usages.extend(scenario.diagram_usages(p, element.id, subject));
+            }
+            _ => {}
+        }
+    }
+    usages.sort_by_cached_key(|u| {
+        (
+            u.surface.category(p),
+            p.named(u.surface.id()).to_lowercase(),
+            u.surface,
+            target_name(p, u).to_lowercase(),
+        )
+    });
+    usages
+        .dedup_by(|a, b| a.subject == b.subject && a.surface == b.surface && a.target == b.target);
+    usages
+}
+
+pub(crate) fn alias(p: &Project, id: Id) -> &str {
+    p.elements
+        .get(&id)
+        .map(|e| e.alias.as_str())
+        .or_else(|| p.relations.get(&id).map(|r| r.alias.as_str()))
+        .or_else(|| p.diagrams.get(&id).map(|d| d.alias.as_str()))
+        .or_else(|| p.traces.get(&id).map(|t| t.alias.as_str()))
+        .or_else(|| {
+            p.diagrams
+                .values()
+                .find_map(|d| d.nodes.get(&id).map(|n| n.alias.as_str()))
+        })
+        .unwrap_or("")
+}
+
+pub(crate) fn target_name(p: &Project, usage: &Usage) -> String {
+    let id = match &usage.target {
+        Target::Whole => usage.surface.id(),
+        Target::Placement(id) => p
+            .diagrams
+            .get(&usage.surface.id())
+            .and_then(|d| d.nodes.get(id))
+            .map_or(*id, |n| n.element),
+        Target::Port { port, .. } => *port,
+        Target::Edge(id)
+        | Target::StateRow { relation: id, .. }
+        | Target::AllocationGrouping { relation: id, .. }
+        | Target::ProcessLink(id)
+        | Target::ScenarioObject(id) => *id,
+        Target::ProcessOccurrence(endpoint) => {
+            return endpoint
+                .references
+                .iter()
+                .copied()
+                .chain([endpoint.occurrence])
+                .map(|id| format!("{} (@{})", p.named(id), alias(p, id)))
+                .collect::<Vec<_>>()
+                .join(" / ");
+        }
+        Target::ProcessPreviewLink {
+            relation, source, ..
+        } => {
+            return source
+                .references
+                .iter()
+                .copied()
+                .chain([*relation])
+                .map(|id| format!("{} (@{})", p.named(id), alias(p, id)))
+                .collect::<Vec<_>>()
+                .join(" / ");
+        }
+    };
+    format!("{} (@{})", p.named(id), alias(p, id))
+}
+
+/// Saved view membership is the renderer's final projection, including folds,
+/// projection-kind exclusions and explicit view filters. Stored route metadata
+/// and merely having both relation endpoints placed do not imply visibility.
+pub(crate) fn saved_usages(p: &Project, subject: Id) -> Vec<Usage> {
+    saved_usages_for(p, subject, None)
+}
+
+/// Revalidate only the requested saved surface before activation. The optional
+/// filter is applied before projection and routing, never after a whole lookup.
+pub(crate) fn saved_usages_for(p: &Project, subject: Id, only_diagram: Option<Id>) -> Vec<Usage> {
+    if only_diagram.is_some_and(|id| !p.diagrams.contains_key(&id)) {
+        return Vec::new();
+    }
+    let index = ViewIndex::new(p);
+    let mut usages = Vec::new();
+    for diagram in p
+        .diagrams
+        .values()
+        .filter(|diagram| only_diagram.is_none_or(|id| diagram.id == id))
+    {
+        let view = projection::project_diagram_with_index(p, diagram, &index);
+        let surface = Surface::Saved(diagram.id);
+        if subject == diagram.id || diagram.projection.state_machine() == Some(subject) {
+            usages.push(Usage {
+                subject,
+                surface,
+                target: Target::Whole,
+                role: if subject == diagram.id {
+                    "diagram"
+                } else {
+                    "state machine view"
+                }
+                .into(),
+                bounds: routed_bounds(routing::route_diagram(p, diagram, &view).bounds),
+            });
+        }
+        for node in &view.nodes {
+            if subject == node.element || subject == node.id {
+                usages.push(Usage {
+                    subject,
+                    surface,
+                    target: Target::Placement(node.id),
+                    role: "node".into(),
+                    bounds: Rectangle {
+                        x: node.position.x,
+                        y: node.position.y,
+                        // Reveal the labelled header, not the empty interior of
+                        // a large expanded container at the minimum zoom.
+                        width: node.size.width.min(420.),
+                        height: node.size.height.min(64.),
+                    },
+                });
+            }
+        }
+        for port in &view.ports {
+            if subject == port.element {
+                usages.push(Usage {
+                    subject,
+                    surface,
+                    target: Target::Port {
+                        port: port.element,
+                        placement: port.owner,
+                    },
+                    role: "port".into(),
+                    bounds: Rectangle {
+                        x: port.position.x - 12.,
+                        y: port.position.y - 12.,
+                        width: 24.,
+                        height: 24.,
+                    },
+                });
+            }
+        }
+        // Allocation arrows are suppressed in this projection. A direct
+        // relation is represented only by its actual visible containment chain;
+        // aggregate summaries never manufacture inherited relations.
+        if diagram.projection == oa_core::ProjectionKind::Allocation
+            && let Some(relation) = p.relations.get(&subject)
+            && relation.kind() == oa_core::RelationKind::Allocation
+        {
+            let placements: std::collections::BTreeMap<_, _> =
+                view.nodes.iter().map(|node| (node.id, node)).collect();
+            for work in view.nodes.iter().filter(|n| n.element == relation.target()) {
+                let mut parent = work.visual_parent;
+                let mut seen = std::collections::BTreeSet::new();
+                while let Some(id) = parent.filter(|id| seen.insert(*id)) {
+                    let Some(performer) = placements.get(&id) else {
+                        break;
+                    };
+                    if performer.element == relation.source() {
+                        usages.push(Usage {
+                            subject,
+                            surface,
+                            target: Target::AllocationGrouping {
+                                relation: subject,
+                                work_placement: work.id,
+                                performer_placement: performer.id,
+                            },
+                            role: "allocation grouping".into(),
+                            bounds: Rectangle {
+                                x: work.position.x,
+                                y: work.position.y,
+                                width: work.size.width.min(420.),
+                                height: work.size.height.min(64.),
+                            },
+                        });
+                        break;
+                    }
+                    parent = performer.visual_parent;
+                }
+            }
+        }
+        if view.edges.iter().any(|edge| edge.id == subject)
+            && let Some(edge) = routing::route_diagram(p, diagram, &view)
+                .edges
+                .get(&subject)
+        {
+            usages.push(Usage {
+                subject,
+                surface,
+                target: Target::Edge(subject),
+                role: "relationship".into(),
+                bounds: edge_focus_bounds(edge),
+            });
+        }
+        if diagram.projection.state_machine().is_some() {
+            usages.extend(crate::behavior::state_canvas::diagram_usages(
+                p, diagram, &view, subject,
+            ));
+        }
+    }
+    usages
+}
+
+pub(crate) fn routed_bounds(bounds: routing::RoutingBounds) -> Rectangle {
+    Rectangle {
+        x: bounds.position.x,
+        y: bounds.position.y,
+        width: bounds.size.width,
+        height: bounds.size.height,
+    }
+}
+
+/// Focus a named edge at its label. For an unlabelled line, focus its middle
+/// segment instead of shrinking a long connector to fit the whole diagram.
+pub(crate) fn edge_focus_bounds(edge: &routing::RoutedEdge) -> Rectangle {
+    if !edge.label.text.is_empty() {
+        return routed_bounds(edge.label.bounds);
+    }
+    let point = edge
+        .points
+        .get(edge.points.len() / 2)
+        .copied()
+        .unwrap_or(edge.label.center);
+    Rectangle {
+        x: point.x - 40.,
+        y: point.y - 24.,
+        width: 80.,
+        height: 48.,
+    }
+}
+
+/// Whole-canvas navigation fits its entire extent; an individual target keeps
+/// the readable minimum zoom of `camera` rather than shrinking unrelated space.
+pub(crate) fn camera_for(
+    target: &Target,
+    bounds: Rectangle,
+    viewport: iced::Size,
+) -> (f32, iced::Vector) {
+    if !matches!(target, Target::Whole) {
+        return camera(bounds, viewport);
+    }
+    let available = iced::Size::new(
+        (viewport.width - 64.).max(1.),
+        (viewport.height - 64.).max(1.),
+    );
+    let zoom = (available.width / bounds.width.max(1.))
+        .min(available.height / bounds.height.max(1.))
+        .clamp(0.0001, 1.25);
+    let pan = iced::Vector::new(
+        viewport.width / 2. - bounds.center_x() * zoom,
+        viewport.height / 2. - bounds.center_y() * zoom,
+    );
+    (zoom, pan)
+}
+
+/// Return a readable, centered camera without modifying authored geometry.
+pub(crate) fn camera(bounds: Rectangle, viewport: iced::Size) -> (f32, iced::Vector) {
+    let available = iced::Size::new(
+        (viewport.width - 64.).max(1.),
+        (viewport.height - 64.).max(1.),
+    );
+    let zoom = (available.width / bounds.width.max(1.))
+        .min(available.height / bounds.height.max(1.))
+        .clamp(0.5, 1.25);
+    let pan = iced::Vector::new(
+        viewport.width / 2. - bounds.center_x() * zoom,
+        viewport.height / 2. - bounds.center_y() * zoom,
+    );
+    (zoom, pan)
+}
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(test)]
+mod coverage_tests;

crates/oa-desktop/src/diagram_usage/coverage_tests.rs

@@ -0,0 +1,386 @@
+//! Independent allocation membership oracles. Expected targets and coordinates
+//! come from handwritten fixtures, never from the usage predicate under test.
+use super::{Surface, Target, Usage, saved_usages, saved_usages_for};
+use iced::Rectangle;
+use oa_core::{
+    Id, Kind, Layer, Position, Project, ProjectionKind, RelationKind, Size, projection, validation,
+};
+
+struct AllocationFixture {
+    project: Project,
+    diagram: Id,
+    performer: Id,
+    work: Id,
+    relation: Id,
+    performer_node: Id,
+    work_node: Id,
+}
+
+fn assert_valid(project: &Project) {
+    let errors: Vec<_> = validation::validate(project)
+        .into_iter()
+        .filter(|issue| issue.severity == validation::Severity::Error)
+        .collect();
+    assert!(
+        errors.is_empty(),
+        "fixture must be structurally valid: {errors:?}"
+    );
+}
+
+fn fixture() -> AllocationFixture {
+    let mut project = Project::empty();
+    let performer = project
+        .add_element(Kind::Entity, Layer::Oa, "Rescue team", None)
+        .unwrap();
+    let work = project
+        .add_element(Kind::Activity, Layer::Oa, "Dispatch", None)
+        .unwrap();
+    let relation = project.relate(RelationKind::Allocation, "Performs", performer, work);
+    let diagram = project.ensure_diagram(Layer::Oa);
+    project.diagrams.get_mut(&diagram).unwrap().projection = ProjectionKind::Allocation;
+    let performer_node = project.place(diagram, performer, Position { x: 20., y: 40. });
+    let work_node = project.place(diagram, work, Position { x: 240., y: 320. });
+    project
+        .diagrams
+        .get_mut(&diagram)
+        .unwrap()
+        .nodes
+        .get_mut(&work_node)
+        .unwrap()
+        .size = Size {
+        width: 320.,
+        height: 110.,
+    };
+    assert_valid(&project);
+    AllocationFixture {
+        project,
+        diagram,
+        performer,
+        work,
+        relation,
+        performer_node,
+        work_node,
+    }
+}
+
+fn expected(f: &AllocationFixture) -> Usage {
+    Usage {
+        subject: f.relation,
+        surface: Surface::Saved(f.diagram),
+        target: Target::AllocationGrouping {
+            relation: f.relation,
+            work_placement: f.work_node,
+            performer_placement: f.performer_node,
+        },
+        role: "allocation grouping".into(),
+        bounds: Rectangle {
+            x: 240.,
+            y: 320.,
+            width: 320.,
+            height: 64.,
+        },
+    }
+}
+
+/// Two semantic decomposition levels, both summaries of the one allocated leaf.
+/// No Allocation relation targets either summary.
+fn nest_under_summaries(f: &mut AllocationFixture) -> (Id, Id, Id, Id) {
+    let top = f
+        .project
+        .add_element(Kind::Activity, Layer::Oa, "Respond", None)
+        .unwrap();
+    let middle = f
+        .project
+        .add_element(Kind::Activity, Layer::Oa, "Coordinate", Some(top))
+        .unwrap();
+    f.project.elements.get_mut(&f.work).unwrap().parent = Some(middle);
+    let top_node = f
+        .project
+        .place(f.diagram, top, Position { x: 70., y: 120. });
+    let middle_node = f
+        .project
+        .place(f.diagram, middle, Position { x: 130., y: 210. });
+    assert_valid(&f.project);
+    (top, middle, top_node, middle_node)
+}
+
+#[test]
+fn allocation_grouping_has_exact_relation_placements_and_readable_work_geometry() {
+    let f = fixture();
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    let work = view
+        .nodes
+        .iter()
+        .find(|node| node.id == f.work_node)
+        .unwrap();
+    assert_eq!(work.visual_parent, Some(f.performer_node));
+    assert_eq!(work.position, Position { x: 240., y: 320. });
+    assert_eq!(
+        work.size,
+        Size {
+            width: 320.,
+            height: 110.
+        }
+    );
+    assert!(!view.edges.iter().any(|edge| edge.id == f.relation));
+
+    assert_eq!(saved_usages(&f.project, f.relation), vec![expected(&f)]);
+    assert_eq!(
+        saved_usages_for(&f.project, f.relation, Some(f.diagram)),
+        vec![expected(&f)]
+    );
+    assert!(saved_usages_for(&f.project, f.relation, Some(Id::new_v4())).is_empty());
+    // The semantic work and its placement remain ordinary node selections.
+    for subject in [f.work, f.work_node] {
+        let usages = saved_usages(&f.project, subject);
+        assert_eq!(usages.len(), 1);
+        assert_eq!(usages[0].target, Target::Placement(f.work_node));
+    }
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn allocation_grouping_walks_two_visible_summary_levels_without_inventing_allocations() {
+    let mut f = fixture();
+    let (top, middle, top_node, middle_node) = nest_under_summaries(&mut f);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    for (node_id, parent, summary) in [
+        (f.work_node, Some(middle_node), false),
+        (middle_node, Some(top_node), true),
+        (top_node, Some(f.performer_node), true),
+    ] {
+        let node = view.nodes.iter().find(|node| node.id == node_id).unwrap();
+        assert_eq!(node.visual_parent, parent);
+        assert_eq!(node.allocation_summary, summary);
+    }
+    assert_eq!(f.project.relations.len(), 1);
+    assert_eq!(saved_usages(&f.project, f.relation), vec![expected(&f)]);
+    for (element, node) in [(top, top_node), (middle, middle_node)] {
+        let usages = saved_usages(&f.project, element);
+        assert_eq!(usages.len(), 1);
+        assert_eq!(usages[0].target, Target::Placement(node));
+    }
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn folded_summary_or_performer_does_not_substitute_a_visible_ancestor_for_the_leaf() {
+    let mut f = fixture();
+    let (_, _, top_node, middle_node) = nest_under_summaries(&mut f);
+    for folded in [f.performer_node, top_node, middle_node] {
+        let mut project = f.project.clone();
+        project
+            .diagrams
+            .get_mut(&f.diagram)
+            .unwrap()
+            .nodes
+            .get_mut(&folded)
+            .unwrap()
+            .collapsed = true;
+        assert_valid(&project);
+        let before = project.clone();
+        let view = projection::project_view(&project, f.diagram);
+        assert!(view.nodes.iter().any(|node| node.id == folded));
+        assert!(!view.nodes.iter().any(|node| node.id == f.work_node));
+        assert!(saved_usages(&project, f.relation).is_empty());
+        assert_eq!(project, before);
+    }
+}
+
+#[test]
+fn absent_endpoint_placements_and_hidden_performer_do_not_create_grouping_targets() {
+    let mut f = fixture();
+    let (_, _, top_node, _) = nest_under_summaries(&mut f);
+    for absent in [f.performer_node, f.work_node] {
+        let mut project = f.project.clone();
+        project
+            .diagrams
+            .get_mut(&f.diagram)
+            .unwrap()
+            .nodes
+            .remove(&absent);
+        assert_valid(&project);
+        let before = project.clone();
+        let view = projection::project_view(&project, f.diagram);
+        // The aggregate card remains visible even when the actual leaf or its
+        // actual performer has no placement. It cannot stand in for that end.
+        assert!(
+            view.nodes
+                .iter()
+                .any(|node| node.id == top_node && node.allocation_summary)
+        );
+        assert!(saved_usages(&project, f.relation).is_empty());
+        assert_eq!(project, before);
+    }
+
+    let outer = f
+        .project
+        .add_element(Kind::Entity, Layer::Oa, "Organization", None)
+        .unwrap();
+    f.project.elements.get_mut(&f.performer).unwrap().parent = Some(outer);
+    let outer_node = f
+        .project
+        .place(f.diagram, outer, Position { x: -40., y: -60. });
+    f.project
+        .diagrams
+        .get_mut(&f.diagram)
+        .unwrap()
+        .nodes
+        .get_mut(&outer_node)
+        .unwrap()
+        .collapsed = true;
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    assert!(view.nodes.iter().any(|node| node.id == outer_node));
+    assert!(!view.nodes.iter().any(|node| node.id == f.performer_node));
+    assert!(saved_usages(&f.project, f.relation).is_empty());
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn collapsed_leaf_and_edge_filter_still_leave_the_actual_nesting_visible() {
+    let mut f = fixture();
+    let diagram = f.project.diagrams.get_mut(&f.diagram).unwrap();
+    diagram.nodes.get_mut(&f.work_node).unwrap().collapsed = true;
+    // hidden_edges controls arrows. Allocation is drawn as nesting, which is
+    // still visible; do not mistake the filter for a hidden node/grouping.
+    diagram.view_options.hidden_edges.push(f.relation);
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    let work = view
+        .nodes
+        .iter()
+        .find(|node| node.id == f.work_node)
+        .unwrap();
+    assert!(work.collapsed);
+    assert_eq!(work.visual_parent, Some(f.performer_node));
+    assert_eq!(saved_usages(&f.project, f.relation), vec![expected(&f)]);
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn other_projections_do_not_report_allocation_nesting_when_only_an_arrow_or_nothing_is_drawn() {
+    let mut f = fixture();
+    f.project.diagrams.get_mut(&f.diagram).unwrap().projection = ProjectionKind::Overview;
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    assert!(view.edges.iter().any(|edge| edge.id == f.relation));
+    assert!(view.nodes.iter().all(|node| node.visual_parent.is_none()));
+    let usages = saved_usages(&f.project, f.relation);
+    assert_eq!(usages.len(), 1);
+    assert_eq!(usages[0].subject, f.relation);
+    assert_eq!(usages[0].surface, Surface::Saved(f.diagram));
+    assert_eq!(usages[0].target, Target::Edge(f.relation));
+    assert_eq!(f.project, before);
+
+    f.project.diagrams.get_mut(&f.diagram).unwrap().projection = ProjectionKind::FunctionalDataflow;
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    assert!(view.nodes.iter().any(|node| node.id == f.work_node));
+    assert!(!view.nodes.iter().any(|node| node.id == f.performer_node));
+    assert!(saved_usages(&f.project, f.relation).is_empty());
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn repeated_saved_views_keep_allocation_placement_identity_and_geometry_independent() {
+    let mut f = fixture();
+    // The first diagram is Allocation, so this creates a different Overview.
+    let second = f.project.ensure_diagram(Layer::Oa);
+    assert_ne!(second, f.diagram);
+    f.project.diagrams.get_mut(&second).unwrap().projection = ProjectionKind::Allocation;
+    let second_performer = f
+        .project
+        .place(second, f.performer, Position { x: 900., y: 600. });
+    let second_work = f
+        .project
+        .place(second, f.work, Position { x: 1000., y: 700. });
+    f.project
+        .diagrams
+        .get_mut(&second)
+        .unwrap()
+        .nodes
+        .get_mut(&second_work)
+        .unwrap()
+        .size = Size {
+        width: 520.,
+        height: 130.,
+    };
+    assert_ne!(second_performer, f.performer_node);
+    assert_ne!(second_work, f.work_node);
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let other = Usage {
+        subject: f.relation,
+        surface: Surface::Saved(second),
+        target: Target::AllocationGrouping {
+            relation: f.relation,
+            work_placement: second_work,
+            performer_placement: second_performer,
+        },
+        role: "allocation grouping".into(),
+        bounds: Rectangle {
+            x: 1000.,
+            y: 700.,
+            width: 420.,
+            height: 64.,
+        },
+    };
+    let usages = saved_usages(&f.project, f.relation);
+    assert_eq!(usages.len(), 2);
+    assert!(usages.contains(&expected(&f)));
+    assert!(usages.contains(&other));
+    assert_eq!(
+        saved_usages_for(&f.project, f.relation, Some(second)),
+        vec![other]
+    );
+    assert_eq!(f.project, before);
+}
+
+#[test]
+fn role_derived_nesting_without_a_direct_allocation_does_not_invent_one() {
+    let mut f = fixture();
+    f.project.relations.remove(&f.relation);
+    let role = f
+        .project
+        .add_element(Kind::Role, Layer::Oa, "Dispatcher", None)
+        .unwrap();
+    let realization = f.project.relate(
+        RelationKind::RoleRealization,
+        "Realizes dispatcher",
+        f.performer,
+        role,
+    );
+    let assignment = f
+        .project
+        .relate(RelationKind::RoleAssignment, "Dispatches", role, f.work);
+    assert_valid(&f.project);
+    let before = f.project.clone();
+    let view = projection::project_view(&f.project, f.diagram);
+    let work = view
+        .nodes
+        .iter()
+        .find(|node| node.id == f.work_node)
+        .unwrap();
+    assert_eq!(work.visual_parent, Some(f.performer_node));
+    assert!(work.allocation_summary);
+    assert!(
+        f.project
+            .relations
+            .values()
+            .all(|relation| relation.kind() != RelationKind::Allocation)
+    );
+    for subject in [f.relation, realization, assignment] {
+        assert!(saved_usages(&f.project, subject).is_empty());
+    }
+    let usages = saved_usages(&f.project, f.work);
+    assert_eq!(usages.len(), 1);
+    assert_eq!(usages[0].target, Target::Placement(f.work_node));
+    assert_eq!(f.project, before);
+}

crates/oa-desktop/src/diagram_usage/tests.rs

@@ -0,0 +1,196 @@
+use super::*;
+use oa_core::{Kind, Layer, Position, RelationKind};
+
+#[test]
+fn saved_membership_respects_filters_and_does_not_change_project() {
+    let mut p = Project::empty();
+    let first = p.add(Kind::Activity, "Same name", 20., 20.);
+    let second = p.add(Kind::Activity, "Same name", 340., 20.);
+    let relation = p.relate(RelationKind::Interaction, "Handoff", first, second);
+    let shown = p.ensure_diagram(Layer::Oa);
+    let mut hidden = p.diagrams[&shown].clone();
+    hidden.id = Id::new_v4();
+    hidden.alias = "filtered_copy".into();
+    hidden.nodes = hidden
+        .nodes
+        .into_values()
+        .map(|mut node| {
+            node.id = Id::new_v4();
+            node.alias = format!("filtered_{}", node.alias);
+            (node.id, node)
+        })
+        .collect();
+    hidden.view_options.hidden_edges.push(relation);
+    let hidden_id = hidden.id;
+    p.diagrams.insert(hidden_id, hidden);
+    let before = p.clone();
+
+    let hits = saved_usages(&p, relation);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].surface, Surface::Saved(shown));
+    assert_eq!(hits[0].target, Target::Edge(relation));
+    let hits = saved_usages(&p, first);
+    assert_eq!(hits.len(), 2);
+    assert!(hits.iter().all(|hit| match hit.target {
+        Target::Placement(node) => p.diagrams[&hit.surface.id()].nodes[&node].element == first,
+        _ => false,
+    }));
+    assert_eq!(p, before);
+}
+
+#[test]
+fn folded_child_is_not_a_visible_node_and_placement_identity_stays_exact() {
+    let mut p = Project::empty();
+    let parent = p.add(Kind::Activity, "Container", 20., 20.);
+    let child = p
+        .add_element(Kind::Activity, Layer::Oa, "Nested", Some(parent))
+        .unwrap();
+    let diagram = p.ensure_diagram(Layer::Oa);
+    let child_node = p.place(diagram, child, Position { x: 50., y: 100. });
+    let parent_node = p.diagrams[&diagram]
+        .nodes
+        .values()
+        .find(|n| n.element == parent)
+        .unwrap()
+        .id;
+    let hits = saved_usages(&p, child_node);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].target, Target::Placement(child_node));
+    p.diagrams
+        .get_mut(&diagram)
+        .unwrap()
+        .nodes
+        .get_mut(&parent_node)
+        .unwrap()
+        .collapsed = true;
+    let before = p.clone();
+    assert!(saved_usages(&p, child).is_empty());
+    assert!(saved_usages(&p, child_node).is_empty());
+    assert_eq!(saved_usages(&p, parent).len(), 1);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn ports_are_found_at_the_visible_owner_and_unplaced_elements_do_not_match_names() {
+    let mut p = Project::empty();
+    let owner = p.add(Kind::Function, "Compute", 20., 20.);
+    let port = Id::new_v4();
+    let element = oa_core::ports::make_port(
+        &p,
+        port,
+        owner,
+        "Input",
+        oa_core::PortContract::FunctionInput {
+            incoming_items: vec![],
+        },
+    )
+    .unwrap();
+    p = oa_core::execute_batch(&p, &[oa_core::Command::CreateElement(element)]).unwrap();
+    let unrelated = p
+        .add_element(Kind::Function, Layer::Sa, "Compute", None)
+        .unwrap();
+    let hits = saved_usages(&p, port);
+    assert_eq!(hits.len(), 1);
+    let view = projection::project_view(&p, hits[0].surface.id());
+    let painted = view
+        .ports
+        .iter()
+        .find(|shown| shown.element == port)
+        .unwrap();
+    assert_eq!(
+        hits[0].target,
+        Target::Port {
+            port,
+            placement: painted.owner
+        }
+    );
+    assert_eq!(
+        hits[0].bounds.center(),
+        iced::Point::new(painted.position.x, painted.position.y)
+    );
+    assert!(saved_usages(&p, unrelated).is_empty());
+    assert!(saved_usages(&p, Id::new_v4()).is_empty());
+}
+
+#[test]
+fn reveal_camera_centers_target_without_whole_view_shrink() {
+    let bounds = Rectangle {
+        x: 100_000.,
+        y: -50_000.,
+        width: 224.,
+        height: 94.,
+    };
+    let viewport = iced::Size::new(700., 500.);
+    let (zoom, pan) = camera(bounds, viewport);
+    assert_eq!(zoom, 1.25);
+    assert!((bounds.center_x() * zoom + pan.x - 350.).abs() < 0.01);
+    assert!((bounds.center_y() * zoom + pan.y - 250.).abs() < 0.01);
+}
+
+#[test]
+fn oversized_container_reveal_targets_its_labelled_header() {
+    let mut p = Project::empty();
+    let container = p.add(Kind::Activity, "Large enclosing activity", 40., 70.);
+    let diagram = p.ensure_diagram(Layer::Oa);
+    let node = p
+        .diagrams
+        .get_mut(&diagram)
+        .unwrap()
+        .nodes
+        .values_mut()
+        .next()
+        .unwrap();
+    node.size = oa_core::Size {
+        width: 4000.,
+        height: 4000.,
+    };
+    let before = p.clone();
+    let hits = saved_usages(&p, container);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].bounds.x, 40.);
+    assert_eq!(hits[0].bounds.y, 70.);
+    assert!(hits[0].bounds.width <= 420.);
+    assert!(hits[0].bounds.height <= 64.);
+    let (zoom, pan) = camera(hits[0].bounds, iced::Size::new(500., 300.));
+    assert!((hits[0].bounds.center_x() * zoom + pan.x - 250.).abs() < 0.01);
+    assert!(70. * zoom + pan.y >= 0.);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn state_machine_owner_finds_its_view_without_a_machine_placement() {
+    let mut p = Project::empty();
+    let machine = p
+        .add_element(Kind::StateMachine, Layer::Sa, "Monitor", None)
+        .unwrap();
+    let unrelated = p
+        .add_element(Kind::StateMachine, Layer::Sa, "Other", None)
+        .unwrap();
+    let diagram = p.ensure_diagram(Layer::Sa);
+    p.diagrams.get_mut(&diagram).unwrap().projection =
+        oa_core::ProjectionKind::StateMachine { machine };
+    let before = p.clone();
+    let hits = saved_usages(&p, machine);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].surface, Surface::Saved(diagram));
+    assert_eq!(hits[0].target, Target::Whole);
+    assert_eq!(hits[0].role, "state machine view");
+    assert!(saved_usages(&p, unrelated).is_empty());
+    assert_eq!(p, before);
+}
+
+#[test]
+fn whole_diagram_camera_fits_large_bounds_instead_of_individual_object_scale() {
+    let bounds = Rectangle {
+        x: 2000.,
+        y: -4000.,
+        width: 100_000.,
+        height: 80_000.,
+    };
+    let (zoom, pan) = camera_for(&Target::Whole, bounds, iced::Size::new(500., 300.));
+    assert!(zoom < 0.01);
+    assert!(bounds.x * zoom + pan.x >= 0.);
+    assert!(bounds.y * zoom + pan.y >= 0.);
+    assert!((bounds.x + bounds.width) * zoom + pan.x <= 500.);
+    assert!((bounds.y + bounds.height) * zoom + pan.y <= 300.);
+}

crates/oa-desktop/src/diagram_usage/view.rs

@@ -0,0 +1,220 @@
+use super::*;
+use crate::{
+    app::{App, Message},
+    style,
+    views::{action, short},
+};
+use iced::{
+    Element, Fill,
+    widget::{self, column, container, row, text, text_input, tooltip},
+};
+use std::collections::BTreeSet;
+
+const PAGE_SIZE: usize = 6;
+
+pub(crate) fn overlay<'a>(app: &'a App, base: Element<'a, Message>) -> Element<'a, Message> {
+    let Some(panel) = &app.diagram_usages else {
+        return base;
+    };
+    let p = app.project();
+    let token = panel.token;
+    let message = |event| Message::DiagramUsage(event);
+    let matched = panel.matches(p);
+    let mut surfaces = Vec::new();
+    let mut seen = BTreeSet::new();
+    for usage in &matched {
+        if seen.insert(usage.surface) {
+            surfaces.push(usage.surface);
+        }
+    }
+    let targets: Vec<_> = matched
+        .iter()
+        .copied()
+        .filter(|usage| Some(usage.surface) == panel.destination)
+        .collect();
+    let count = if panel.destination.is_some() {
+        targets.len()
+    } else {
+        surfaces.len()
+    };
+    let last = count.saturating_sub(1) / PAGE_SIZE;
+    let page = panel.page.min(last);
+    let total_surfaces = panel
+        .usages
+        .iter()
+        .map(|u| u.surface)
+        .collect::<BTreeSet<_>>()
+        .len();
+    let mut content = column![
+        row![
+            text("Show in diagrams").size(22).width(Fill),
+            action("Close", message(Event::Close(token)))
+        ]
+        .spacing(12),
+        tooltip(
+            text(format!(
+                "{}  ·  @{}",
+                short(p.named(panel.context.subject), 48),
+                short(alias(p, panel.context.subject), 48)
+            ))
+            .size(14),
+            container(
+                widget::scrollable(
+                    text(format!(
+                        "{}\n@{}",
+                        p.named(panel.context.subject),
+                        alias(p, panel.context.subject)
+                    ))
+                    .size(13)
+                )
+                .height(220)
+            )
+            .padding(10)
+            .width(620)
+            .style(style::card),
+            tooltip::Position::Bottom
+        ),
+        text(if panel.loading {
+            "Searching rendered objects…".into()
+        } else {
+            format!(
+                "{} diagram destinations · {} representations",
+                total_surfaces,
+                panel.usages.len()
+            )
+        })
+        .size(12)
+        .color(style::MUTED),
+        text_input("Filter diagram, occurrence, or alias", &panel.search)
+            .id(format!("diagram-usage-filter-{}", panel.token))
+            .padding(9)
+            .on_input(move |value| Message::DiagramUsage(Event::Search(token, value)))
+            .on_submit(message(Event::Activate(token))),
+    ]
+    .spacing(10);
+    if let Some(notice) = &panel.notice {
+        content = content.push(text(notice).size(13));
+    }
+    if let Some(surface) = panel.destination {
+        content = content.push(
+            row![
+                action("All diagrams", message(Event::Destination(token, None))),
+                text(short(p.named(surface.id()), 55)).size(15),
+            ]
+            .spacing(10),
+        );
+        for (index, usage) in targets
+            .into_iter()
+            .enumerate()
+            .skip(page * PAGE_SIZE)
+            .take(PAGE_SIZE)
+        {
+            let name = target_name(p, usage);
+            content = content.push(tooltip(
+                action(
+                    &format!("{} · {}", usage.role, short(&name, 70)),
+                    message(Event::Choose(token, usage.clone())),
+                )
+                .width(Fill)
+                .style(if panel.cursor == index {
+                    style::selected
+                } else {
+                    style::nav
+                }),
+                container(text(name).size(13))
+                    .padding(10)
+                    .max_width(680)
+                    .style(style::card),
+                tooltip::Position::Top,
+            ));
+        }
+    } else {
+        for (index, surface) in surfaces
+            .into_iter()
+            .enumerate()
+            .skip(page * PAGE_SIZE)
+            .take(PAGE_SIZE)
+        {
+            let targets = matched.iter().filter(|u| u.surface == surface).count();
+            let name = format!(
+                "{} · {} (@{}) · {} representations",
+                surface.category(p),
+                p.named(surface.id()),
+                alias(p, surface.id()),
+                targets
+            );
+            let layer = p
+                .diagrams
+                .get(&surface.id())
+                .map(|d| d.layer)
+                .or_else(|| p.layer_of(surface.id()))
+                .map(|l| l.to_string())
+                .unwrap_or_default();
+            content = content.push(tooltip(
+                action(
+                    &format!(
+                        "{} · {} · {} · {}",
+                        surface.category(p),
+                        layer,
+                        short(p.named(surface.id()), 34),
+                        targets
+                    ),
+                    message(Event::Destination(token, Some(surface))),
+                )
+                .width(Fill)
+                .style(if panel.cursor == index {
+                    style::selected
+                } else {
+                    style::nav
+                }),
+                container(text(name).size(13))
+                    .padding(10)
+                    .max_width(680)
+                    .style(style::card),
+                tooltip::Position::Top,
+            ));
+        }
+    }
+    if panel.loading {
+        content = content.push(text("Finding diagram representations…").size(13));
+    } else if count == 0 {
+        content = content.push(text(if panel.usages.is_empty() {
+            "No currently rendered representation found. Folded or filtered objects and unexpanded reuse contents are excluded."
+        } else { "No results match this filter." }).size(13));
+    }
+    let mut paging = row![
+        text(format!(
+            "Page {} of {} · {} matches",
+            page + 1,
+            last + 1,
+            count
+        ))
+        .size(12)
+        .width(Fill)
+    ]
+    .spacing(8);
+    if page > 0 {
+        paging = paging.push(action("Previous", message(Event::Page(token, page - 1))));
+    }
+    if page < last {
+        paging = paging.push(action("Next", message(Event::Page(token, page + 1))));
+    }
+    content = content.push(paging).push(text("↑ ↓ choose · Enter opens · Escape closes. Source and saved view settings are preserved.").size(12).color(style::MUTED));
+    widget::stack![
+        base,
+        widget::opaque(
+            container(
+                container(content)
+                    .padding(22)
+                    .width((app.window_size.width - 80.).clamp(620., 820.))
+                    .style(style::card)
+            )
+            .center(Fill)
+            .style(|_| container::Style {
+                background: Some(iced::Color::from_rgba(0.08, 0.12, 0.18, 0.38).into()),
+                ..Default::default()
+            })
+        )
+    ]
+    .into()
+}

crates/oa-desktop/src/document.rs

@@ -95,7 +95,7 @@ pub struct Document {
     past: Vec<HistoryEntry>,
     future: Vec<HistoryEntry>,
     current_bytes: usize,
-    saved: Arc<SourceBundle>,
+    saved: Option<Arc<SourceBundle>>,
     revision: u64,
     view_index: std::cell::OnceCell<oa_core::view_options::ViewIndex>,
     limits: ProjectLimits,
@@ -125,7 +125,7 @@ impl Document {
             current_bytes,
             past: Vec::new(),
             future: Vec::new(),
-            saved: Arc::new(bundle),
+            saved: Some(Arc::new(bundle)),
             revision: 0,
             view_index: Default::default(),
             limits,
@@ -156,7 +156,7 @@ impl Document {
     }
 
     pub fn dirty(&self) -> bool {
-        self.recovered_unsaved || self.bundle() != self.saved.as_ref()
+        self.recovered_unsaved || self.saved.as_deref() != Some(self.bundle())
     }
 
     /// Recovered work is a detached copy until explicitly saved by its user.
@@ -181,10 +181,24 @@ impl Document {
     /// Records the bytes actually saved, even when later edits remain current.
     /// The I/O adapter owns document identity and save completion ordering.
     pub fn mark_saved(&mut self, snapshot: Arc<CompiledSourceProject>) {
-        self.saved = Arc::new(snapshot.bundle.clone());
+        self.saved = Some(Arc::new(snapshot.bundle.clone()));
         self.recovered_unsaved = false;
     }
 
+    /// Bind an installed or recovered repair destination to source read there.
+    /// These bytes may be invalid or differ from the retained accepted model,
+    /// but must replace the previous disk baseline. Accepted history is retained;
+    /// applying or undoing to old saved content does not save this destination.
+    pub(crate) fn bind_repair_baseline(&mut self, source: SourceBundle) {
+        self.saved = Some(Arc::new(source));
+    }
+
+    /// Recovery changed the current destination, but its source could not be
+    /// reloaded. No accepted or historical snapshot is known to be saved there.
+    pub(crate) fn invalidate_saved_baseline(&mut self) {
+        self.saved = None;
+    }
+
     /// Check a source Save as before writing any files. A retained included file
     /// must never be displaced by the new entry, including on a later Undo.
     pub fn check_save_entry(&self, entry: &str) -> Result<(), DocumentError> {

crates/oa-desktop/src/forms.rs

@@ -18,6 +18,7 @@ mod context_fields;
 mod data_fields;
 mod history_fields;
 mod port_fields;
+pub(crate) mod reference_chooser;
 mod view_fields;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -85,6 +86,8 @@ pub struct Draft {
     pub value_browsers: BTreeMap<String, ValueBrowser>,
     pub reference_browsers: BTreeMap<String, ReferenceBrowser>,
     history: history_fields::State,
+    reference_session: Id,
+    reference_generation: Id,
 }
 
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
@@ -209,11 +212,14 @@ impl Draft {
             value_browsers: BTreeMap::new(),
             reference_browsers: BTreeMap::new(),
             history: Default::default(),
+            reference_session: Id::new_v4(),
+            reference_generation: Id::new_v4(),
         };
         draft.rebuild();
         Some(draft)
     }
     fn rebuild(&mut self) {
+        self.reference_generation = Id::new_v4();
         // Array/variant edits can change the meaning of a row path.
         self.value_browsers.clear();
         self.inputs.clear();
@@ -274,6 +280,9 @@ impl Draft {
             .unwrap_or_else(|| self.materialize().unwrap_or_else(|_| self.value.clone()))
     }
     pub fn set_context(&mut self, context: Option<Value>) {
+        if self.context != context {
+            self.reference_generation = Id::new_v4();
+        }
         self.context = context;
     }
     /// Materialize selected scalar subtrees without parsing retained, unselected drafts.
@@ -359,6 +368,9 @@ impl Draft {
     }
     pub fn input(&mut self, path: &str, value: String) {
         if let Some(input) = self.inputs.get_mut(path) {
+            if input.raw != value {
+                self.reference_generation = Id::new_v4();
+            }
             input.editor = text_editor::Content::with_text(&value);
             input.raw = value;
         }
@@ -366,7 +378,11 @@ impl Draft {
     pub fn edit_text(&mut self, path: &str, action: text_editor::Action) {
         if let Some(input) = self.inputs.get_mut(path) {
             input.editor.perform(action);
-            input.raw = input.editor.text();
+            let raw = input.editor.text();
+            if input.raw != raw {
+                self.reference_generation = Id::new_v4();
+            }
+            input.raw = raw;
         }
     }
     pub fn shape(&mut self, path: &str, value: Value) -> Result<(), String> {
@@ -1795,7 +1811,7 @@ pub fn view<'a>(draft: &'a Draft, project: &'a Project) -> View<'a, Message> {
             ));
         }
     }
-    content.into()
+    reference_chooser::trigger::scope(content, draft.reference_session)
 }
 
 /// Render one closed property subtree for a workflow-owned typed draft.
@@ -1937,41 +1953,12 @@ fn property<'a>(
         return out.into();
     }
     if reference(path) && (value.is_string() || value.is_null()) {
-        let raw = draft
-            .inputs
-            .get(path)
-            .map(|v| v.raw.as_str())
-            .or_else(|| value.as_str());
-        let current = raw.and_then(|s| s.parse::<Id>().ok()).unwrap_or(Id::nil());
-        let choices = reference_choices(draft, project, path, current);
-        let selected = choices.iter().find(|c| c.id == current).cloned();
-        let owned_path = path.to_string();
-        let optional = optional_reference(path);
-        let mut content = column![
+        return column![
             label_view(),
-            pick_list(choices, selected, move |choice| Message::FieldShape(
-                owned_path.clone(),
-                if choice.id.is_nil() && optional {
-                    Value::Null
-                } else {
-                    json!(choice.id)
-                }
-            ))
-            .text_size(12)
-            .padding(8)
-            .width(Fill)
+            reference_chooser::adapter::field(draft, project, path)
         ]
-        .spacing(5);
-        if let Some(raw) = raw
-            && raw.parse::<Id>().is_err()
-        {
-            content = content.push(
-                text(format!("Invalid reference retained in the draft: {raw}"))
-                    .size(11)
-                    .color(style::MUTED),
-            );
-        }
-        return content.into();
+        .spacing(5)
+        .into();
     }
     match value {
         Value::Object(map) => {

crates/oa-desktop/src/forms/data_fields.rs

@@ -670,7 +670,7 @@ mod tests {
     }
     fn semantic_send(app: &mut crate::app::App, event: crate::semantic_review::RowEvent) {
         let event = semantic_state(app).address_event(event);
-        let _ = app.update(Message::Workflow(crate::workflow::Event::Semantic(event)));
+        let _ = app.update(Message::Workflow(crate::workflow::Event::semantic(event)));
     }
     fn semantic_decide(app: &mut crate::app::App, facet: FieldFacet, decision: SemanticDecision) {
         use crate::semantic_review::RowEvent as Event;

crates/oa-desktop/src/forms/reference_chooser.rs

@@ -0,0 +1,389 @@
+//! Isolated live-reference chooser experiment, declared only under cfg(test).
+//! The host supplies an eligible catalog and revalidates every
+//! Write intent against the current document before changing a staged scalar.
+//! No core command, draft serialization, or App message belongs in this module.
+use oa_core::Id;
+use std::collections::BTreeSet;
+
+pub mod adapter;
+#[cfg(test)]
+mod tests;
+pub mod trigger;
+pub mod widget;
+
+pub const MAX_ROWS: usize = 6;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Context {
+    pub document: Id,
+    pub revision: u64,
+    pub draft: Id,
+    pub record: Id,
+    pub path: String,
+    pub optional: bool,
+}
+impl Context {
+    /// This is an additional historical-path guard, not live schema discovery.
+    /// Call only after the parent form has identified a live reference field.
+    pub fn live(
+        document: Id,
+        revision: u64,
+        draft: Id,
+        record: Id,
+        path: impl Into<String>,
+        optional: bool,
+    ) -> Result<Self, &'static str> {
+        let path = path.into();
+        if !path.starts_with('/') || path.split('/').any(|part| part == "baseline") {
+            return Err("The chooser requires a live reference property.");
+        }
+        Ok(Self {
+            document,
+            revision,
+            draft,
+            record,
+            path,
+            optional,
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Candidate {
+    /// For a diagram placement this is the placement ID, not its element ID.
+    pub id: Id,
+    pub name: String,
+    pub alias: String,
+    pub kind: String,
+    pub scope: String,
+    pub containment: String,
+}
+impl Candidate {
+    pub fn context_label(&self) -> String {
+        format!("{} · {} · {}", self.scope, self.kind, self.containment)
+    }
+    pub fn detail(&self) -> String {
+        format!(
+            "{} · @{} · {} · {}",
+            self.name,
+            self.alias,
+            self.context_label(),
+            self.id
+        )
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Current {
+    Unassigned,
+    Valid(Candidate),
+    Incompatible(Candidate),
+    Missing(Id),
+    InvalidRaw(String),
+}
+impl Current {
+    pub fn label(&self) -> String {
+        match self {
+            Self::Unassigned => "Not assigned".into(),
+            Self::Valid(c) => format!("Current: {} · @{}", c.name, c.alias),
+            Self::Incompatible(c) => {
+                format!("Current choice needs review: {} · @{}", c.name, c.alias)
+            }
+            Self::Missing(id) => format!("Missing reference: {id}"),
+            Self::InvalidRaw(raw) => format!("Invalid reference retained: {raw}"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+struct Searchable {
+    candidate: Candidate,
+    all: String,
+    alias: String,
+    name: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Stamp {
+    pub context: Context,
+    pub invocation: Id,
+    pub results: u64,
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Close {
+    Escape,
+    Tab { backwards: bool },
+    Outside,
+    WindowChanged,
+}
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Action {
+    /// The mounted text input numbers emitted edits. Multiple edits in one
+    /// runtime batch may share the old result stamp; none may be dropped.
+    Query {
+        text: String,
+        serial: u64,
+    },
+    Move {
+        delta: i32,
+        rows: usize,
+    },
+    Page {
+        delta: i32,
+        rows: usize,
+    },
+    Highlight(Id),
+    Choose(Id),
+    Clear,
+    Close(Close),
+}
+impl Action {
+    pub fn writes_staged_value(&self) -> bool {
+        matches!(self, Self::Choose(_) | Self::Clear)
+    }
+}
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Event {
+    pub stamp: Stamp,
+    pub action: Action,
+}
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Outcome {
+    Ignored,
+    Browsed,
+    Closed(Close),
+    /// The host must still check current eligibility and scoped draft guards.
+    Write {
+        context: Context,
+        value: Option<Id>,
+    },
+}
+
+#[derive(Debug, Clone)]
+pub struct State {
+    context: Context,
+    invocation: Id,
+    results: u64,
+    serial: u64,
+    open: bool,
+    candidates: Vec<Searchable>,
+    filtered: Vec<usize>,
+    query: String,
+    start: usize,
+    highlight: Option<usize>,
+    pub current: Current,
+    pub scope_label: String,
+}
+impl State {
+    pub fn open(
+        context: Context,
+        candidates: Vec<Candidate>,
+        current: Current,
+        scope_label: impl Into<String>,
+    ) -> Result<Self, &'static str> {
+        // Context fields are public for host comparisons; check again in case
+        // a caller constructed one without the live-path constructor.
+        if !context.path.starts_with('/') || context.path.split('/').any(|p| p == "baseline") {
+            return Err("Historical values are not live reference candidates.");
+        }
+        let mut seen = BTreeSet::new();
+        let mut indexed = Vec::with_capacity(candidates.len());
+        for candidate in candidates {
+            if candidate.id.is_nil() || !seen.insert(candidate.id) {
+                return Err("Eligible references must have distinct, non-nil identities.");
+            }
+            indexed.push(Searchable {
+                all: candidate.detail().to_lowercase(),
+                alias: candidate.alias.to_lowercase(),
+                name: candidate.name.to_lowercase(),
+                candidate,
+            });
+        }
+        indexed.sort_by(|a, b| {
+            (&a.name, &a.alias, a.candidate.id).cmp(&(&b.name, &b.alias, b.candidate.id))
+        });
+        let filtered: Vec<_> = (0..indexed.len()).collect();
+        let highlight = (!filtered.is_empty()).then_some(0);
+        Ok(Self {
+            context,
+            invocation: Id::new_v4(),
+            results: 0,
+            serial: 0,
+            open: true,
+            candidates: indexed,
+            filtered,
+            query: String::new(),
+            start: 0,
+            highlight,
+            current,
+            scope_label: scope_label.into(),
+        })
+    }
+    pub fn stamp(&self) -> Stamp {
+        Stamp {
+            context: self.context.clone(),
+            invocation: self.invocation,
+            results: self.results,
+        }
+    }
+    pub fn event(&self, action: Action) -> Event {
+        Event {
+            stamp: self.stamp(),
+            action,
+        }
+    }
+    pub fn is_open(&self) -> bool {
+        self.open
+    }
+    pub fn query(&self) -> &str {
+        &self.query
+    }
+    pub fn query_serial(&self) -> u64 {
+        self.serial
+    }
+    pub fn count(&self) -> usize {
+        self.filtered.len()
+    }
+    pub fn start(&self) -> usize {
+        self.start
+    }
+    pub fn optional(&self) -> bool {
+        self.context.optional
+    }
+    pub fn highlighted(&self) -> Option<&Candidate> {
+        self.highlight.and_then(|i| self.at(i))
+    }
+    fn at(&self, index: usize) -> Option<&Candidate> {
+        self.filtered
+            .get(index)
+            .map(|i| &self.candidates[*i].candidate)
+    }
+    pub fn visible(&self, rows: usize) -> impl Iterator<Item = &Candidate> {
+        self.filtered
+            .iter()
+            .skip(self.start)
+            .take(rows.min(MAX_ROWS))
+            .map(|index| &self.candidates[*index].candidate)
+    }
+    /// The host calls this before rendering on any path/document/facet/context
+    /// replacement. Existing events remain tied to the old invocation.
+    pub fn invalidate(&mut self) {
+        self.open = false;
+    }
+
+    pub fn update(&mut self, event: Event) -> Outcome {
+        if !self.open
+            || event.stamp.context != self.context
+            || event.stamp.invocation != self.invocation
+        {
+            return Outcome::Ignored;
+        }
+        // Absolute row actions require exactly the presented result set.
+        // Relative navigation and dismissal are processed in input order within
+        // this session: typing must not make a following Escape stale.
+        if matches!(event.action, Action::Choose(_) | Action::Highlight(_))
+            && event.stamp.results != self.results
+        {
+            return Outcome::Ignored;
+        }
+        match event.action {
+            Action::Query { text, serial } => {
+                if serial <= self.serial {
+                    return Outcome::Ignored;
+                }
+                self.serial = serial;
+                self.query = text;
+                let query = self.query.to_lowercase();
+                let terms: Vec<_> = query.split_whitespace().collect();
+                self.filtered = self
+                    .candidates
+                    .iter()
+                    .enumerate()
+                    .filter_map(|(i, c)| {
+                        terms
+                            .iter()
+                            .all(|term| match term.strip_prefix('@') {
+                                Some(alias) => c.alias.contains(alias),
+                                None => c.all.contains(term),
+                            })
+                            .then_some(i)
+                    })
+                    .collect();
+                self.start = 0;
+                self.highlight = (!self.filtered.is_empty()).then_some(0);
+            }
+            Action::Page { delta, rows } => {
+                let rows = rows.clamp(1, MAX_ROWS);
+                if self.filtered.is_empty() {
+                    return Outcome::Ignored;
+                }
+                let relative = self
+                    .highlight
+                    .unwrap_or(self.start)
+                    .saturating_sub(self.start)
+                    .min(rows - 1);
+                let last_page = (self.filtered.len() - 1) / rows * rows;
+                self.start = (self.start as i64 + i64::from(delta) * rows as i64)
+                    .clamp(0, last_page as i64) as usize;
+                self.highlight = Some((self.start + relative).min(self.filtered.len() - 1));
+            }
+            Action::Move { delta, rows } => {
+                let rows = rows.clamp(1, MAX_ROWS);
+                if self.filtered.is_empty() {
+                    return Outcome::Ignored;
+                }
+                let current = self.highlight.unwrap_or(self.start) as i64;
+                let next =
+                    (current + i64::from(delta)).clamp(0, self.filtered.len() as i64 - 1) as usize;
+                self.highlight = Some(next);
+                if next < self.start {
+                    self.start = next;
+                }
+                if next >= self.start + rows {
+                    self.start = next + 1 - rows;
+                }
+            }
+            Action::Highlight(id) => {
+                let Some(index) = self
+                    .filtered
+                    .iter()
+                    .position(|i| self.candidates[*i].candidate.id == id)
+                else {
+                    return Outcome::Ignored;
+                };
+                if self.highlight == Some(index) {
+                    return Outcome::Ignored;
+                }
+                self.highlight = Some(index);
+            }
+            Action::Choose(id) => {
+                if !self
+                    .filtered
+                    .iter()
+                    .any(|i| self.candidates[*i].candidate.id == id)
+                {
+                    return Outcome::Ignored;
+                }
+                self.open = false;
+                return Outcome::Write {
+                    context: self.context.clone(),
+                    value: Some(id),
+                };
+            }
+            Action::Clear if self.context.optional => {
+                self.open = false;
+                return Outcome::Write {
+                    context: self.context.clone(),
+                    value: None,
+                };
+            }
+            Action::Clear => return Outcome::Ignored,
+            Action::Close(reason) => {
+                self.open = false;
+                return Outcome::Closed(reason);
+            }
+        }
+        self.results = self.results.wrapping_add(1);
+        Outcome::Browsed
+    }
+}

crates/oa-desktop/src/forms/reference_chooser/adapter.rs

@@ -0,0 +1,307 @@
+//! Live form adapter. Compatibility stays in the existing parent adapter;
+//! browser metadata and scoped writes never reinterpret historical UUID text.
+use super::super::{Draft, friendly, history_fields, optional_reference, reference, reference_ids};
+use super::{Candidate, Context, Current, State, trigger};
+use crate::{app::Message, style};
+use iced::{
+    Element, Fill, Rectangle,
+    widget::{column, container, row, text, tooltip},
+};
+use oa_core::{Id, Project};
+use serde_json::{Value, json};
+use std::collections::BTreeSet;
+
+#[derive(Debug, Clone)]
+pub struct Open {
+    pub document: Id,
+    pub session: Id,
+    pub generation: Id,
+    pub record: Id,
+    pub path: String,
+    pub anchor: Rectangle,
+}
+#[derive(Debug, Clone)]
+pub struct Set {
+    pub context: Context,
+    pub generation: Id,
+    pub value: Option<Id>,
+}
+impl Draft {
+    pub fn reference_session(&self) -> Id {
+        self.reference_session
+    }
+    pub fn reference_generation(&self) -> Id {
+        self.reference_generation
+    }
+    pub fn reference_open(&self, project: &Project, path: &str, anchor: Rectangle) -> Open {
+        Open {
+            document: project.id,
+            session: self.reference_session,
+            generation: self.reference_generation,
+            record: self.original,
+            path: path.into(),
+            anchor,
+        }
+    }
+    pub fn reference_matches(&self, request: &Open) -> bool {
+        self.reference_session == request.session
+            && self.reference_generation == request.generation
+            && self.original == request.record
+            && self.live_reference(&request.path)
+    }
+    fn live_reference(&self, path: &str) -> bool {
+        !history_fields::is_path(path)
+            && reference(path)
+            && self
+                .value
+                .pointer(path)
+                .is_some_and(|v| v.is_string() || v.is_null())
+    }
+    pub fn reference_catalog(
+        &self,
+        project: &Project,
+        request: &Open,
+        revision: u64,
+    ) -> Result<State, String> {
+        if request.document != project.id || !self.reference_matches(request) {
+            return Err("The reference field changed. Open its chooser again.".into());
+        }
+        let allowed: BTreeSet<_> = reference_ids(self, project, &request.path)
+            .into_iter()
+            .filter(|id| !id.is_nil())
+            .collect();
+        let candidates = allowed
+            .iter()
+            .filter_map(|id| candidate(project, *id))
+            .collect();
+        let raw = self
+            .inputs
+            .get(&request.path)
+            .map(|v| v.raw.as_str())
+            .or_else(|| self.value.pointer(&request.path).and_then(Value::as_str));
+        let current = match raw {
+            None => Current::Unassigned,
+            Some(raw) => match raw.parse::<Id>() {
+                Ok(id) if id.is_nil() => Current::Unassigned,
+                Ok(id) => match candidate(project, id) {
+                    Some(c) if allowed.contains(&id) => Current::Valid(c),
+                    Some(c) => Current::Incompatible(c),
+                    None => Current::Missing(id),
+                },
+                Err(_) => Current::InvalidRaw(raw.into()),
+            },
+        };
+        let context = Context::live(
+            project.id,
+            revision,
+            self.reference_session,
+            self.original,
+            &request.path,
+            optional_reference(&request.path),
+        )
+        .map_err(str::to_owned)?;
+        State::open(
+            context,
+            candidates,
+            current,
+            format!(
+                "{} · compatible references",
+                friendly(request.path.rsplit('/').next().unwrap_or("Reference"))
+            ),
+        )
+        .map_err(str::to_owned)
+    }
+    pub fn reference_set(&mut self, project: &Project, intent: &Set) -> Result<(), String> {
+        let value = self.reference_value(project, intent)?;
+        self.shape_scoped(&intent.context.path, value)
+    }
+    pub fn reference_value(&self, project: &Project, intent: &Set) -> Result<Value, String> {
+        let context = &intent.context;
+        if context.document != project.id
+            || context.draft != self.reference_session
+            || context.record != self.original
+            || intent.generation != self.reference_generation
+            || !self.live_reference(&context.path)
+            || context.optional != optional_reference(&context.path)
+        {
+            return Err("The originating reference field is no longer current.".into());
+        }
+        let value = match intent.value {
+            Some(id)
+                if !id.is_nil() && reference_ids(self, project, &context.path).contains(&id) =>
+            {
+                json!(id)
+            }
+            None if context.optional => Value::Null,
+            _ => return Err("Choose a currently compatible reference.".into()),
+        };
+        Ok(value)
+    }
+}
+
+fn named(project: &Project, id: Id) -> String {
+    if let Some(e) = project.elements.get(&id) {
+        format!("{} · @{}", e.name, e.alias)
+    } else {
+        project.named(id).into()
+    }
+}
+fn ancestry(project: &Project, id: Id) -> String {
+    let mut parts = vec![];
+    let mut seen = BTreeSet::new();
+    let mut current = project.elements.get(&id).and_then(|e| e.parent);
+    while let Some(id) = current {
+        if !seen.insert(id) {
+            parts.push("[containment cycle]".into());
+            break;
+        }
+        parts.push(named(project, id));
+        current = project.elements.get(&id).and_then(|e| e.parent);
+    }
+    parts.reverse();
+    if parts.is_empty() {
+        project.name.clone()
+    } else {
+        parts.join(" / ")
+    }
+}
+pub(crate) fn candidate(project: &Project, id: Id) -> Option<Candidate> {
+    let layer = |layer| format!("{layer:?}").to_uppercase();
+    if id == project.id {
+        return Some(Candidate {
+            id,
+            name: project.name.clone(),
+            alias: project.alias.clone(),
+            kind: "Project".into(),
+            scope: "Model".into(),
+            containment: "Model root".into(),
+        });
+    }
+    if let Some(e) = project.elements.get(&id) {
+        return Some(Candidate {
+            id,
+            name: e.name.clone(),
+            alias: e.alias.clone(),
+            kind: e.kind().to_string(),
+            scope: layer(e.layer()),
+            containment: ancestry(project, id),
+        });
+    }
+    if let Some(r) = project.relations.get(&id) {
+        return Some(Candidate {
+            id,
+            name: r.name.clone(),
+            alias: r.alias.clone(),
+            kind: r.kind().to_string(),
+            scope: project.layer_of(id).map_or_else(|| "Model".into(), layer),
+            containment: format!(
+                "{} → {}",
+                named(project, r.source()),
+                named(project, r.target())
+            ),
+        });
+    }
+    for diagram in project.diagrams.values() {
+        if id == diagram.id {
+            return Some(Candidate {
+                id,
+                name: diagram.name.clone(),
+                alias: diagram.alias.clone(),
+                kind: format!("{:?} diagram", diagram.projection),
+                scope: layer(diagram.layer),
+                containment: project.name.clone(),
+            });
+        }
+        if let Some(node) = diagram.nodes.get(&id) {
+            return Some(Candidate {
+                id,
+                name: project.named(node.element).into(),
+                alias: node.alias.clone(),
+                kind: "Placement".into(),
+                scope: layer(diagram.layer),
+                containment: format!(
+                    "{} · @{} / {}",
+                    diagram.name,
+                    diagram.alias,
+                    named(project, node.element)
+                ),
+            });
+        }
+    }
+    if let Some(link) = project.artifact_links.get(&id) {
+        return Some(Candidate {
+            id,
+            name: link.name.clone(),
+            alias: link.alias.clone(),
+            kind: "Artifact link".into(),
+            scope: project
+                .layer_of(link.owner)
+                .map_or_else(|| "Model".into(), layer),
+            containment: named(project, link.owner),
+        });
+    }
+    project.traces.get(&id).map(|trace| Candidate {
+        id,
+        name: trace.name.clone(),
+        alias: trace.alias.clone(),
+        kind: "Trace".into(),
+        scope: "OA ↔ SA".into(),
+        containment: format!(
+            "{} ↔ {}",
+            named(project, trace.oa),
+            named(project, trace.sa)
+        ),
+    })
+}
+
+pub fn field<'a, R: iced::advanced::text::Renderer<Font = iced::Font> + 'a>(
+    draft: &'a Draft,
+    project: &'a Project,
+    path: &str,
+) -> Element<'a, Message, iced::Theme, R> {
+    let raw = draft
+        .inputs
+        .get(path)
+        .map(|v| v.raw.as_str())
+        .or_else(|| draft.value.pointer(path).and_then(Value::as_str));
+    let (label, detail) = match raw {
+        None => (
+            if optional_reference(path) {
+                "Not assigned"
+            } else {
+                "Choose a reference…"
+            }
+            .into(),
+            String::new(),
+        ),
+        Some(raw) => match raw.parse::<Id>() {
+            Ok(id) if id.is_nil() => ("Choose a reference…".into(), String::new()),
+            Ok(id) => match candidate(project, id) {
+                Some(c) => (format!("{} · @{}", c.name, c.alias), c.detail()),
+                None => ("Missing reference".into(), raw.into()),
+            },
+            Err(_) => ("Invalid reference retained".into(), raw.into()),
+        },
+    };
+    let label = crate::views::short(&label, 35);
+    let body = container(row![text(label).size(12).width(Fill), text("⌄").size(12)].spacing(6))
+        .padding(8)
+        .width(Fill);
+    let path = path.to_owned();
+    let id = trigger::field_id(draft.reference_generation, &path);
+    let field = trigger::Field::new(body, id, move |anchor| {
+        Message::FieldReferenceOpen(draft.reference_open(project, &path, anchor))
+    });
+    if detail.is_empty() {
+        field.into()
+    } else {
+        tooltip(
+            field,
+            container(column![text(detail).size(11)])
+                .padding(8)
+                .style(style::card),
+            tooltip::Position::Left,
+        )
+        .into()
+    }
+}

crates/oa-desktop/src/forms/reference_chooser/tests.rs

@@ -0,0 +1,803 @@
+use super::*;
+use iced::{
+    Element, Event as Input, Point, Rectangle, Size, Theme, Vector,
+    advanced::{Layout, Shell, layout, widget::Tree},
+    keyboard, mouse,
+    widget::{Space, mouse_area},
+};
+
+fn context(optional: bool) -> Context {
+    Context::live(
+        Id::from_u128(1),
+        7,
+        Id::from_u128(2),
+        Id::from_u128(3),
+        "/body/SequenceUse/sequence",
+        optional,
+    )
+    .unwrap()
+}
+fn candidate(index: u128) -> Candidate {
+    Candidate {
+        id: Id::from_u128(10_000 + index),
+        name: "Control".into(),
+        alias: format!("controller_{index:04}"),
+        kind: "Function".into(),
+        scope: "SA".into(),
+        containment: format!("System / Subsystem {} / Controller", index / 100),
+    }
+}
+fn thousand(current: Current, optional: bool) -> State {
+    // Reverse the fixture input to falsify accidental dependence on ingestion
+    // order. Expected IDs and aliases below are literal fixture identities.
+    State::open(
+        context(optional),
+        (0..1_000).rev().map(candidate).collect(),
+        current,
+        "SA · compatible functions",
+    )
+    .unwrap()
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Message {
+    Chooser(Event),
+    UnderPress,
+    UnderRelease,
+}
+
+#[derive(Default)]
+struct Clipboard(Option<String>);
+impl iced::advanced::Clipboard for Clipboard {
+    fn read(&self, _: iced::advanced::clipboard::Kind) -> Option<String> {
+        self.0.clone()
+    }
+    fn write(&mut self, _: iced::advanced::clipboard::Kind, text: String) {
+        self.0 = Some(text);
+    }
+}
+
+struct Mount {
+    tree: Option<Tree>,
+    size: Size,
+    anchor: Rectangle,
+    clipboard: Clipboard,
+}
+impl Default for Mount {
+    fn default() -> Self {
+        Self {
+            tree: None,
+            size: Size::new(1100., 700.),
+            anchor: Rectangle {
+                x: 790.,
+                y: 640.,
+                width: 278.,
+                height: 32.,
+            },
+            clipboard: Clipboard::default(),
+        }
+    }
+}
+impl Mount {
+    fn batch(
+        &mut self,
+        state: Option<&State>,
+        events: &[(Input, Option<Point>)],
+    ) -> (Vec<Message>, Option<layout::Node>) {
+        let underneath: Element<'_, Message, Theme, ()> =
+            mouse_area(Space::new().width(iced::Fill).height(iced::Fill))
+                .on_press(Message::UnderPress)
+                .on_release(Message::UnderRelease)
+                .into();
+        let mut view: Element<'_, Message, Theme, ()> =
+            widget::Popup::new(underneath, state, self.anchor, Message::Chooser).into();
+        let tree = self.tree.get_or_insert_with(|| Tree::new(view.as_widget()));
+        view.as_widget().diff(tree);
+        let node =
+            view.as_widget_mut()
+                .layout(tree, &(), &layout::Limits::new(Size::ZERO, self.size));
+        let viewport = Rectangle::with_size(self.size);
+        let overlay_node = view
+            .as_widget_mut()
+            .overlay(tree, Layout::new(&node), &(), &viewport, Vector::ZERO)
+            .map(|mut overlay| overlay.as_overlay_mut().layout(&(), self.size));
+        let mut messages = Vec::new();
+        for (event, point) in events {
+            let cursor = point.map_or(mouse::Cursor::Unavailable, mouse::Cursor::Available);
+            let mut shell = Shell::new(&mut messages);
+            if let Some(overlay_node) = &overlay_node {
+                // Reconstruct the overlay between layout and every input, as
+                // Iced does. Geometry must live in the measured layout tree.
+                let mut overlay = view
+                    .as_widget_mut()
+                    .overlay(tree, Layout::new(&node), &(), &viewport, Vector::ZERO)
+                    .unwrap();
+                overlay.as_overlay_mut().update(
+                    event,
+                    Layout::new(overlay_node),
+                    cursor,
+                    &(),
+                    &mut self.clipboard,
+                    &mut shell,
+                );
+                overlay.as_overlay().draw(
+                    &mut (),
+                    &crate::style::theme(),
+                    &iced::advanced::renderer::Style {
+                        text_color: iced::Color::BLACK,
+                    },
+                    Layout::new(overlay_node),
+                    cursor,
+                );
+                if matches!(
+                    event,
+                    Input::Mouse(_) | Input::Keyboard(_) | Input::Touch(_) | Input::InputMethod(_)
+                ) {
+                    assert!(shell.is_event_captured(), "An open chooser owns input");
+                }
+            } else {
+                view.as_widget_mut().update(
+                    tree,
+                    event,
+                    Layout::new(&node),
+                    cursor,
+                    &(),
+                    &mut self.clipboard,
+                    &mut shell,
+                    &viewport,
+                );
+            }
+        }
+        (messages, overlay_node)
+    }
+    fn send(&mut self, state: &mut State, event: Input) -> Vec<Outcome> {
+        let (messages, _) = self.batch(Some(state), &[(event, None)]);
+        messages
+            .into_iter()
+            .map(|message| match message {
+                Message::Chooser(event) => state.update(event),
+                _ => panic!("Popup leaked input to its parent"),
+            })
+            .collect()
+    }
+    fn type_text(&mut self, state: &mut State, text: &str) -> Vec<Outcome> {
+        let (messages, _) = self.batch(Some(state), &typing(text));
+        messages
+            .into_iter()
+            .map(|message| match message {
+                Message::Chooser(event) => state.update(event),
+                _ => panic!("Typing leaked input to its parent"),
+            })
+            .collect()
+    }
+    fn geometry(&mut self, state: &State) -> widget::Geometry {
+        let (_, node) = self.batch(Some(state), &[]);
+        widget::Geometry::from_bounds(node.unwrap().children()[0].bounds())
+    }
+    fn click(&mut self, state: &State, point: Point) -> Vec<Message> {
+        self.batch(
+            Some(state),
+            &[
+                (
+                    Input::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                    Some(point),
+                ),
+                (
+                    Input::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)),
+                    Some(point),
+                ),
+            ],
+        )
+        .0
+    }
+}
+
+fn named(key: keyboard::key::Named) -> Input {
+    Input::Keyboard(keyboard::Event::KeyPressed {
+        key: keyboard::Key::Named(key),
+        modified_key: keyboard::Key::Named(key),
+        physical_key: keyboard::key::Physical::Code(keyboard::key::Code::Space),
+        location: keyboard::Location::Standard,
+        modifiers: keyboard::Modifiers::empty(),
+        text: None,
+        repeat: false,
+    })
+}
+// Iced 0.14's physical-key path intentionally inserts one scalar from text.
+// Whole-string typing is several key events; paste and IME commit are separate
+// input paths and are exercised below rather than faked as one physical key.
+fn typed(character: char) -> Input {
+    let text = character.to_string();
+    Input::Keyboard(keyboard::Event::KeyPressed {
+        key: keyboard::Key::Character(text.clone().into()),
+        modified_key: keyboard::Key::Character(text.clone().into()),
+        physical_key: keyboard::key::Physical::Code(keyboard::key::Code::KeyA),
+        location: keyboard::Location::Standard,
+        modifiers: keyboard::Modifiers::empty(),
+        text: Some(text.into()),
+        repeat: false,
+    })
+}
+fn typing(text: &str) -> Vec<(Input, Option<Point>)> {
+    text.chars()
+        .map(|character| (typed(character), None))
+        .collect()
+}
+fn query(state: &mut State, value: &str) {
+    let event = state.event(Action::Query {
+        text: value.into(),
+        serial: state.query_serial() + 1,
+    });
+    assert_eq!(state.update(event), Outcome::Browsed);
+}
+
+#[test]
+fn catalog_search_disambiguates_repeated_names_containment_alias_and_exact_placement_identity() {
+    let mut state = thousand(Current::Unassigned, false);
+    assert_eq!(
+        state.visible(6).map(|c| c.id).collect::<Vec<_>>(),
+        (10_000..10_006).map(Id::from_u128).collect::<Vec<_>>()
+    );
+    query(&mut state, "control subsystem 6 @controller_0617");
+    assert_eq!(state.count(), 1);
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_617));
+    query(&mut state, "OA");
+    assert_eq!(state.count(), 0);
+    query(&mut state, &Id::from_u128(10_617).to_string());
+    assert_eq!(state.count(), 1);
+    assert_eq!(state.highlighted().unwrap().alias, "controller_0617");
+
+    let placement = Candidate {
+        id: Id::from_u128(20_001),
+        name: "Control".into(),
+        alias: "control_placement".into(),
+        kind: "Placement".into(),
+        scope: "SA".into(),
+        containment: "Architecture / Main diagram / Control".into(),
+    };
+    let mut state = State::open(
+        context(false),
+        vec![placement],
+        Current::Unassigned,
+        "SA · placements",
+    )
+    .unwrap();
+    query(&mut state, "placement main");
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(20_001));
+    let event = state.event(Action::Choose(Id::from_u128(20_000)));
+    assert_eq!(
+        state.update(event),
+        Outcome::Ignored,
+        "Semantic ID is not the placement identity"
+    );
+    assert!(
+        State::open(
+            context(false),
+            vec![candidate(1), candidate(1)],
+            Current::Unassigned,
+            "SA"
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn mounted_overlay_clamps_at_three_field_positions_and_keeps_results_and_query_bounded() {
+    let state = thousand(Current::InvalidRaw("not a uuid".into()), true);
+    for size in [
+        Size::new(1100., 700.),
+        Size::new(1600., 1000.),
+        Size::new(320., 320.),
+    ] {
+        for y in [5., size.height / 2., size.height - 34.] {
+            let mut mount = Mount {
+                size,
+                anchor: Rectangle {
+                    x: size.width - 300.,
+                    y,
+                    width: 278.,
+                    height: 32.,
+                },
+                ..Default::default()
+            };
+            let (_, node) = mount.batch(Some(&state), &[]);
+            let node = node.unwrap();
+            let bounds = node.children()[0].bounds();
+            let geometry = widget::Geometry::from_bounds(bounds);
+            assert!(bounds.x >= 8. && bounds.y >= 8.);
+            assert!(bounds.x + bounds.width <= size.width - 8.);
+            assert!(bounds.y + bounds.height <= size.height - 8.);
+            assert!(bounds.width <= 420. && bounds.height <= 360.);
+            assert!(geometry.rows > 0 && geometry.rows <= 6);
+            assert_eq!(geometry.rows, if size.height == 320. { 4 } else { 6 });
+            let search = node.children()[1].bounds();
+            assert!(
+                bounds.contains(search.position())
+                    && bounds.contains(Point::new(
+                        search.x + search.width,
+                        search.y + search.height
+                    ))
+            );
+            assert!(geometry.row(geometry.rows - 1).y + 34. <= geometry.detail.y);
+            assert_eq!(state.visible(geometry.rows).count(), geometry.rows);
+        }
+    }
+}
+
+#[test]
+fn mounted_input_preserves_rapid_same_batch_typing_and_cursor_across_controlled_rebuilds() {
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    let (messages, _) = mount.batch(Some(&state), &[(typed('a'), None), (typed('b'), None)]);
+    assert_eq!(
+        messages.len(),
+        2,
+        "Actual focused input must publish each edit"
+    );
+    let mut queries = Vec::new();
+    for message in messages {
+        let Message::Chooser(event) = message else {
+            panic!("Unexpected parent event")
+        };
+        let Action::Query { text, .. } = &event.action else {
+            panic!("Typing must not choose a reference")
+        };
+        queries.push(text.clone());
+        assert_eq!(state.update(event), Outcome::Browsed);
+    }
+    assert_eq!(queries, ["a", "ab"]);
+    assert_eq!(state.query(), "ab");
+    assert!(
+        mount
+            .send(&mut state, named(keyboard::key::Named::Home))
+            .is_empty()
+    );
+    assert_eq!(mount.send(&mut state, typed('z')), [Outcome::Browsed]);
+    assert_eq!(
+        state.query(),
+        "zab",
+        "Rebuilding the controlled widget must not refocus at the end"
+    );
+    assert_eq!(state.current, Current::Unassigned);
+}
+
+#[test]
+fn mounted_keyboard_pages_and_selects_only_the_highlighted_visible_candidate_once() {
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    assert_eq!(
+        mount.send(&mut state, named(keyboard::key::Named::PageDown)),
+        [Outcome::Browsed]
+    );
+    assert_eq!(state.start(), 6);
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_006));
+    assert_eq!(
+        mount.send(&mut state, named(keyboard::key::Named::ArrowDown)),
+        [Outcome::Browsed]
+    );
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_007));
+    let (messages, _) = mount.batch(
+        Some(&state),
+        &[
+            (named(keyboard::key::Named::Enter), None),
+            (named(keyboard::key::Named::Enter), None),
+        ],
+    );
+    assert_eq!(messages.len(), 1);
+    let Message::Chooser(event) = messages.into_iter().next().unwrap() else {
+        panic!()
+    };
+    assert!(event.action.writes_staged_value());
+    assert_eq!(
+        state.update(event),
+        Outcome::Write {
+            context: context(false),
+            value: Some(Id::from_u128(10_007))
+        }
+    );
+    assert!(!state.is_open());
+}
+
+#[test]
+fn mounted_filtered_row_click_uses_the_displayed_identity_and_scoped_write_intent() {
+    let mut state = thousand(Current::Missing(Id::from_u128(99)), false);
+    let mut mount = Mount::default();
+    let query = "@controller_0731";
+    assert_eq!(
+        mount.type_text(&mut state, query),
+        vec![Outcome::Browsed; query.chars().count()]
+    );
+    assert_eq!(state.query(), query);
+    assert_eq!(state.count(), 1);
+    let point = mount.geometry(&state).row(0).center();
+    let messages = mount.click(&state, point);
+    assert_eq!(messages.len(), 1);
+    let Message::Chooser(event) = messages[0].clone() else {
+        panic!()
+    };
+    assert_eq!(
+        state.update(event),
+        Outcome::Write {
+            context: context(false),
+            value: Some(Id::from_u128(10_731))
+        }
+    );
+    assert_eq!(state.current, Current::Missing(Id::from_u128(99)));
+}
+
+#[test]
+fn mounted_query_change_rejects_old_release_and_old_result_events_without_locking_popup() {
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    let point = mount.geometry(&state).row(4).center();
+    let captured = mount.click(&state, point);
+    let Message::Chooser(old_choice) = captured[0].clone() else {
+        panic!()
+    };
+    query(&mut state, "@controller_0700");
+    assert_eq!(state.update(old_choice), Outcome::Ignored);
+    // The rejected old Choose had marked the widget closing; a changed result
+    // context must unlock it so an explicit current click can complete.
+    let point = mount.geometry(&state).row(0).center();
+    let messages = mount.click(&state, point);
+    assert_eq!(messages.len(), 1);
+    let Message::Chooser(event) = messages[0].clone() else {
+        panic!()
+    };
+    assert_eq!(
+        state.update(event),
+        Outcome::Write {
+            context: context(false),
+            value: Some(Id::from_u128(10_700))
+        }
+    );
+
+    let mut state = thousand(Current::Unassigned, false);
+    let point = mount.geometry(&state).row(0).center();
+    assert!(
+        mount
+            .batch(
+                Some(&state),
+                &[(
+                    Input::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                    Some(point)
+                )]
+            )
+            .0
+            .is_empty()
+    );
+    query(&mut state, "@controller_0319");
+    assert!(
+        mount
+            .batch(
+                Some(&state),
+                &[(
+                    Input::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)),
+                    Some(point)
+                )]
+            )
+            .0
+            .is_empty()
+    );
+    assert!(state.is_open());
+}
+
+#[test]
+fn captured_choice_cannot_cross_document_revision_draft_record_or_array_path() {
+    let source = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    let point = mount.geometry(&source).row(0).center();
+    let Message::Chooser(event) = mount.click(&source, point).remove(0) else {
+        panic!()
+    };
+    for changed in 0..6 {
+        let mut destination = context(false);
+        match changed {
+            0 => destination.document = Id::from_u128(999),
+            1 => destination.revision += 1,
+            2 => destination.draft = Id::from_u128(999),
+            3 => destination.record = Id::from_u128(999),
+            4 => destination.path = "/body/SomeList/members/1/scenario".into(),
+            _ => {} // A new invocation even with every semantic ID unchanged.
+        }
+        let mut state = State::open(
+            destination,
+            vec![candidate(0)],
+            Current::InvalidRaw("unfinished".into()),
+            "SA",
+        )
+        .unwrap();
+        assert_eq!(state.update(event.clone()), Outcome::Ignored);
+        assert_eq!(state.current, Current::InvalidRaw("unfinished".into()));
+        assert!(state.is_open());
+    }
+    let mut invalidated = source.clone();
+    invalidated.invalidate();
+    assert_eq!(invalidated.update(event), Outcome::Ignored);
+}
+
+#[test]
+fn empty_search_escape_tab_and_optional_clear_do_not_silently_choose_nil() {
+    for current in [
+        Current::Missing(Id::from_u128(999)),
+        Current::InvalidRaw("@incomplete/".into()),
+        Current::Incompatible(candidate(999)),
+    ] {
+        let mut state = thousand(current.clone(), false);
+        let mut mount = Mount::default();
+        let query = "no match exists";
+        assert_eq!(
+            mount.type_text(&mut state, query),
+            vec![Outcome::Browsed; query.chars().count()]
+        );
+        assert_eq!(state.query(), query);
+        assert_eq!(
+            state.count(),
+            0,
+            "Verify actual input reached the empty-result state before Enter"
+        );
+        assert!(
+            mount
+                .send(&mut state, named(keyboard::key::Named::Enter))
+                .is_empty()
+        );
+        assert!(state.is_open());
+        assert_eq!(state.current, current);
+        assert_eq!(
+            mount.send(&mut state, named(keyboard::key::Named::Escape)),
+            [Outcome::Closed(Close::Escape)]
+        );
+        assert_eq!(state.current, current);
+    }
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    assert_eq!(
+        mount.send(&mut state, named(keyboard::key::Named::Tab)),
+        [Outcome::Closed(Close::Tab { backwards: false })]
+    );
+    let mut state = thousand(Current::InvalidRaw("?".into()), true);
+    let point = mount.geometry(&state).clear.center();
+    let Message::Chooser(event) = mount.click(&state, point).remove(0) else {
+        panic!()
+    };
+    assert_eq!(
+        state.update(event),
+        Outcome::Write {
+            context: context(true),
+            value: None
+        }
+    );
+    let mut required = thousand(Current::Unassigned, false);
+    let clear = required.event(Action::Clear);
+    assert_eq!(required.update(clear), Outcome::Ignored);
+}
+
+#[test]
+fn dismissal_swallows_matching_release_across_closed_rebuild_but_next_click_reaches_parent() {
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    let outside = Point::new(20., 20.);
+    let (messages, _) = mount.batch(
+        Some(&state),
+        &[(
+            Input::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+            Some(outside),
+        )],
+    );
+    let [Message::Chooser(event)] = messages.as_slice() else {
+        panic!("Expected only popup dismissal")
+    };
+    assert_eq!(state.update(event.clone()), Outcome::Closed(Close::Outside));
+    let release = Input::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left));
+    assert!(
+        mount
+            .batch(None, &[(release.clone(), Some(outside))])
+            .0
+            .is_empty()
+    );
+    assert_eq!(
+        mount
+            .batch(
+                None,
+                &[
+                    (
+                        Input::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+                        Some(outside)
+                    ),
+                    (release, Some(outside)),
+                ]
+            )
+            .0,
+        [Message::UnderPress, Message::UnderRelease]
+    );
+}
+
+#[test]
+fn historical_paths_never_open_and_only_explicit_choice_or_clear_is_a_write() {
+    for path in [
+        "/baseline",
+        "/baseline/oa/value",
+        "/baseline/sa/value/TypeRef/Named",
+    ] {
+        assert!(
+            Context::live(
+                Id::from_u128(1),
+                0,
+                Id::from_u128(2),
+                Id::from_u128(3),
+                path,
+                true
+            )
+            .is_err()
+        );
+        let mut forged = context(true);
+        forged.path = path.into();
+        assert!(State::open(forged, vec![candidate(0)], Current::Unassigned, "History").is_err());
+    }
+    for action in [
+        Action::Query {
+            text: "Control".into(),
+            serial: 1,
+        },
+        Action::Highlight(Id::from_u128(10_000)),
+        Action::Move { delta: 1, rows: 6 },
+        Action::Page { delta: 1, rows: 6 },
+        Action::Close(Close::Escape),
+    ] {
+        assert!(!action.writes_staged_value());
+    }
+    assert!(Action::Choose(Id::from_u128(10_000)).writes_staged_value());
+    assert!(Action::Clear.writes_staged_value());
+}
+
+#[test]
+fn out_of_order_query_serials_cannot_restore_obsolete_results() {
+    let mut state = thousand(Current::Unassigned, false);
+    let old = state.event(Action::Query {
+        text: "@controller_0001".into(),
+        serial: 1,
+    });
+    let new = state.event(Action::Query {
+        text: "@controller_0999".into(),
+        serial: 2,
+    });
+    assert_eq!(state.update(new), Outcome::Browsed);
+    assert_eq!(state.update(old), Outcome::Ignored);
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_999));
+}
+
+#[test]
+fn mounted_query_then_escape_in_one_batch_closes_and_relative_keys_keep_input_order() {
+    let mut state = thousand(Current::InvalidRaw("unfinished".into()), false);
+    let mut mount = Mount::default();
+    let query = "@controller_0720";
+    let mut inputs = typing(query);
+    inputs.push((named(keyboard::key::Named::Escape), None));
+    let (messages, _) = mount.batch(Some(&state), &inputs);
+    let outcomes: Vec<_> = messages
+        .into_iter()
+        .map(|message| {
+            let Message::Chooser(event) = message else {
+                panic!("Input escaped the popup")
+            };
+            state.update(event)
+        })
+        .collect();
+    let mut expected = vec![Outcome::Browsed; query.chars().count()];
+    expected.push(Outcome::Closed(Close::Escape));
+    assert_eq!(outcomes, expected);
+    assert_eq!(state.query(), "@controller_0720");
+    assert_eq!(state.current, Current::InvalidRaw("unfinished".into()));
+
+    let mut state = thousand(Current::Unassigned, false);
+    let old_absolute_row = state.event(Action::Choose(Id::from_u128(10_000)));
+    let (messages, _) = mount.batch(
+        Some(&state),
+        &[
+            (named(keyboard::key::Named::PageDown), None),
+            (named(keyboard::key::Named::PageDown), None),
+            (named(keyboard::key::Named::ArrowUp), None),
+        ],
+    );
+    assert_eq!(messages.len(), 3);
+    for message in messages {
+        let Message::Chooser(event) = message else {
+            panic!("Input escaped the popup")
+        };
+        assert_eq!(state.update(event), Outcome::Browsed);
+    }
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_011));
+    assert_eq!(state.start(), 11);
+    assert_eq!(state.update(old_absolute_row), Outcome::Ignored);
+    assert!(state.is_open());
+}
+
+#[test]
+fn mounted_clipboard_paste_and_ime_commit_preserve_whole_strings_without_selecting() {
+    let mut state = thousand(Current::Unassigned, false);
+    let mut mount = Mount::default();
+    mount.clipboard.0 = Some("@controller_0472".into());
+    let paste = Input::Keyboard(keyboard::Event::KeyPressed {
+        key: keyboard::Key::Character("v".into()),
+        modified_key: keyboard::Key::Character("v".into()),
+        physical_key: keyboard::key::Physical::Code(keyboard::key::Code::KeyV),
+        location: keyboard::Location::Standard,
+        modifiers: keyboard::Modifiers::COMMAND,
+        text: None,
+        repeat: false,
+    });
+    let (messages, _) = mount.batch(
+        Some(&state),
+        &[
+            (
+                Input::Keyboard(keyboard::Event::ModifiersChanged(
+                    keyboard::Modifiers::COMMAND,
+                )),
+                None,
+            ),
+            (paste, None),
+            (
+                Input::Keyboard(keyboard::Event::ModifiersChanged(
+                    keyboard::Modifiers::empty(),
+                )),
+                None,
+            ),
+        ],
+    );
+    let [Message::Chooser(event)] = messages.as_slice() else {
+        panic!("Paste should emit exactly one whole-string query")
+    };
+    assert_eq!(state.update(event.clone()), Outcome::Browsed);
+    assert_eq!(state.query(), "@controller_0472");
+    assert_eq!(state.count(), 1);
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(10_472));
+    assert_eq!(state.current, Current::Unassigned);
+    assert!(state.is_open());
+
+    let unicode_name = "Режим Δ負荷";
+    let unicode = Candidate {
+        id: Id::from_u128(30_111),
+        name: unicode_name.into(),
+        alias: "mode_unicode".into(),
+        kind: "Function".into(),
+        scope: "SA".into(),
+        containment: "Система / 控制".into(),
+    };
+    let mut state = State::open(
+        context(false),
+        vec![unicode],
+        Current::InvalidRaw("retained".into()),
+        "SA",
+    )
+    .unwrap();
+    use iced::advanced::input_method::Event as Ime;
+    let preedit = [
+        (Input::InputMethod(Ime::Opened), None),
+        (
+            Input::InputMethod(Ime::Preedit(unicode_name.into(), None)),
+            None,
+        ),
+    ];
+    assert!(
+        mount.batch(Some(&state), &preedit).0.is_empty(),
+        "Composition is not a committed query"
+    );
+    assert_eq!(state.query(), "");
+    let (messages, _) = mount.batch(
+        Some(&state),
+        &[
+            (Input::InputMethod(Ime::Preedit(String::new(), None)), None),
+            (Input::InputMethod(Ime::Commit(unicode_name.into())), None),
+            (Input::InputMethod(Ime::Closed), None),
+        ],
+    );
+    let [Message::Chooser(event)] = messages.as_slice() else {
+        panic!("IME commit should emit one complete query")
+    };
+    assert_eq!(state.update(event.clone()), Outcome::Browsed);
+    assert_eq!(state.query(), unicode_name);
+    assert_eq!(state.count(), 1);
+    assert_eq!(state.highlighted().unwrap().id, Id::from_u128(30_111));
+    assert_eq!(state.current, Current::InvalidRaw("retained".into()));
+    assert!(state.is_open());
+}

crates/oa-desktop/src/forms/reference_chooser/trigger.rs

@@ -0,0 +1,447 @@
+//! Keyboard entry and focus operations scoped to one property form. Focus
+//! targets include the draft generation so delayed operations cannot focus a
+//! replacement array row or a recovered document with the same semantic IDs.
+use crate::style;
+use iced::{
+    Border, Color, Element, Event, Length, Rectangle, Size, Task, Theme, Vector,
+    advanced::{
+        Clipboard, Layout, Shell, Widget, layout, overlay, renderer,
+        widget::{Id, Operation, Tree, operation, tree},
+    },
+    keyboard, mouse,
+    widget::container,
+};
+use oa_core::Id as ModelId;
+mod focus;
+
+#[derive(Clone, Copy)]
+pub struct FormScope {
+    pub session: ModelId,
+    pub modal: bool,
+}
+pub(super) struct FormOwner(pub Option<FormScope>);
+const REVIEW_MODAL: &str = "reference-owning-review-modal";
+
+/// Marks the entire Review dialog without changing its layout or event flow.
+pub fn modal<'a, Message: 'a, R: renderer::Renderer + 'a>(
+    content: impl Into<Element<'a, Message, Theme, R>>,
+) -> Element<'a, Message, Theme, R> {
+    Field {
+        content: content.into(),
+        id: Some(Id::new(REVIEW_MODAL)),
+        on_open: None,
+    }
+    .into()
+}
+
+pub fn field_id(generation: ModelId, path: &str) -> Id {
+    Id::from(format!("reference:{generation}:{path}"))
+}
+pub fn scope_id(session: ModelId) -> Id {
+    Id::from(format!("reference-form:{session}"))
+}
+
+#[derive(Default)]
+struct Interaction {
+    focused: bool,
+    pressed: bool,
+    identity: Option<Id>,
+    anchor: Option<Rectangle>,
+}
+impl operation::Focusable for Interaction {
+    fn is_focused(&self) -> bool {
+        self.focused
+    }
+    fn focus(&mut self) {
+        self.focused = true;
+    }
+    fn unfocus(&mut self) {
+        self.focused = false;
+        self.pressed = false;
+    }
+}
+pub struct Field<'a, Message, R = iced::Renderer>
+where
+    R: renderer::Renderer,
+{
+    content: Element<'a, Message, Theme, R>,
+    id: Option<Id>,
+    on_open: Option<Box<dyn Fn(Rectangle) -> Message + 'a>>,
+}
+impl<'a, Message, R: renderer::Renderer> Field<'a, Message, R> {
+    pub fn new(
+        content: impl Into<Element<'a, Message, Theme, R>>,
+        id: Id,
+        on_open: impl Fn(Rectangle) -> Message + 'a,
+    ) -> Self {
+        Self {
+            content: content.into(),
+            id: Some(id),
+            on_open: Some(Box::new(on_open)),
+        }
+    }
+}
+pub fn scope<'a, Message: 'a, R: renderer::Renderer + 'a>(
+    content: impl Into<Element<'a, Message, Theme, R>>,
+    session: ModelId,
+) -> Element<'a, Message, Theme, R> {
+    container(Field {
+        content: content.into(),
+        id: None,
+        on_open: None,
+    })
+    .id(scope_id(session))
+    .width(Length::Fill)
+    .into()
+}
+
+fn run<Message, R: renderer::Renderer>(
+    content: &mut Element<'_, Message, Theme, R>,
+    tree: &mut Tree,
+    layout: Layout<'_>,
+    renderer: &R,
+    mut operation: Box<dyn Operation>,
+) -> bool {
+    let mut changed = false;
+    loop {
+        content
+            .as_widget_mut()
+            .operate(tree, layout, renderer, &mut *operation);
+        match operation.finish() {
+            operation::Outcome::Chain(next) => {
+                operation = next;
+                changed = true;
+            }
+            _ => break,
+        }
+    }
+    changed
+}
+
+pub(super) fn tab<Message, R: renderer::Renderer>(
+    content: &mut Element<'_, Message, Theme, R>,
+    tree: &mut Tree,
+    layout: Layout<'_>,
+    renderer: &R,
+    scope: FormScope,
+    backwards: bool,
+) -> bool {
+    run(
+        content,
+        tree,
+        layout,
+        renderer,
+        Box::new(focus::relative(scope.session, backwards, scope.modal)),
+    )
+}
+pub(super) fn own_input<Message, R: renderer::Renderer>(
+    content: &mut Element<'_, Message, Theme, R>,
+    tree: &mut Tree,
+    layout: Layout<'_>,
+    renderer: &R,
+) {
+    content
+        .as_widget_mut()
+        .operate(tree, layout, renderer, &mut focus::exclusive());
+}
+impl<Message, R: renderer::Renderer> Widget<Message, Theme, R> for Field<'_, Message, R> {
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<Interaction>()
+    }
+    fn state(&self) -> tree::State {
+        tree::State::new(Interaction {
+            identity: self.id.clone(),
+            ..Default::default()
+        })
+    }
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(self.content.as_widget())]
+    }
+    fn diff(&self, tree: &mut Tree) {
+        let state = tree.state.downcast_mut::<Interaction>();
+        if state.identity != self.id {
+            *state = Interaction {
+                identity: self.id.clone(),
+                ..Default::default()
+            };
+        }
+        tree.diff_children(std::slice::from_ref(&self.content));
+    }
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        if let Some(id) = &self.id
+            && self.on_open.is_some()
+        {
+            operation.focusable(
+                Some(id),
+                layout.bounds(),
+                tree.state.downcast_mut::<Interaction>(),
+            );
+            operation.custom(
+                Some(id),
+                layout.bounds(),
+                tree.state.downcast_mut::<Interaction>(),
+            );
+        }
+        if self.on_open.is_none() {
+            operation.container(self.id.as_ref(), layout.bounds());
+            operation.traverse(&mut |operation| {
+                self.content.as_widget_mut().operate(
+                    &mut tree.children[0],
+                    layout,
+                    renderer,
+                    operation,
+                )
+            });
+        } else {
+            self.content.as_widget_mut().operate(
+                &mut tree.children[0],
+                layout,
+                renderer,
+                operation,
+            );
+        }
+    }
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        if let Some(on_open) = &self.on_open {
+            let state = tree.state.downcast_mut::<Interaction>();
+            let visible = layout.bounds().intersection(viewport);
+            let hovered = visible.is_some_and(|bounds| cursor.is_over(bounds));
+            let activate = match event {
+                Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)) if hovered => {
+                    state.focused = true;
+                    state.pressed = true;
+                    shell.capture_event();
+                    shell.request_redraw();
+                    false
+                }
+                Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)) => {
+                    let activate = state.pressed && hovered;
+                    if state.pressed {
+                        shell.capture_event();
+                    }
+                    state.pressed = false;
+                    activate
+                }
+                Event::Keyboard(keyboard::Event::KeyPressed {
+                    key:
+                        keyboard::Key::Named(keyboard::key::Named::Enter | keyboard::key::Named::Space),
+                    repeat: false,
+                    ..
+                }) if state.focused => true,
+                Event::Mouse(mouse::Event::ButtonPressed(_)) => {
+                    state.focused = false;
+                    state.pressed = false;
+                    false
+                }
+                _ => false,
+            };
+            if activate && let Some(bounds) = state.anchor {
+                shell.publish(on_open(bounds));
+                shell.capture_event();
+                return;
+            }
+        }
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        renderer_style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        if self.on_open.is_some() {
+            let focus = tree.state.downcast_ref::<Interaction>().focused;
+            renderer.fill_quad(
+                renderer::Quad {
+                    bounds: layout.bounds(),
+                    border: Border {
+                        color: if focus || cursor.is_over(layout.bounds()) {
+                            style::TEAL
+                        } else {
+                            style::LINE
+                        },
+                        width: if focus { 2. } else { 1. },
+                        radius: 5.into(),
+                    },
+                    ..Default::default()
+                },
+                Color::WHITE,
+            );
+        }
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            renderer_style,
+            layout,
+            cursor,
+            viewport,
+        );
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        if self.on_open.is_some() && cursor.is_over(layout.bounds()) {
+            mouse::Interaction::Pointer
+        } else {
+            self.content.as_widget().mouse_interaction(
+                &tree.children[0],
+                layout,
+                cursor,
+                viewport,
+                renderer,
+            )
+        }
+    }
+    fn overlay<'b>(
+        &'b mut self,
+        tree: &'b mut Tree,
+        layout: Layout<'b>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'b, Message, Theme, R>> {
+        self.content.as_widget_mut().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+            viewport,
+            translation,
+        )
+    }
+}
+
+/// Scrollable child updates use content coordinates. The root visits the
+/// retained tree before each input, so field anchors use current window
+/// coordinates even when a wheel event and activation share one runtime batch.
+pub(super) fn measure<Message, R: renderer::Renderer>(
+    content: &mut Element<'_, Message, Theme, R>,
+    tree: &mut Tree,
+    layout: Layout<'_>,
+    renderer: &R,
+    viewport: Rectangle,
+) {
+    content.as_widget_mut().operate(
+        tree,
+        layout,
+        renderer,
+        &mut Measure {
+            translation: Vector::ZERO,
+            viewport: Some(viewport),
+            pending: None,
+        },
+    );
+}
+struct Measure {
+    translation: Vector,
+    viewport: Option<Rectangle>,
+    pending: Option<(Vector, Option<Rectangle>)>,
+}
+impl Operation for Measure {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        let previous = (self.translation, self.viewport);
+        if let Some((translation, viewport)) = self.pending.take() {
+            self.translation = translation;
+            self.viewport = viewport;
+        }
+        visit(self);
+        (self.translation, self.viewport) = previous;
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&Id>,
+        bounds: Rectangle,
+        _: Rectangle,
+        translation: Vector,
+        _: &mut dyn operation::Scrollable,
+    ) {
+        let bounds = Rectangle {
+            x: bounds.x - self.translation.x,
+            y: bounds.y - self.translation.y,
+            ..bounds
+        };
+        self.pending = Some((
+            self.translation + translation,
+            self.viewport
+                .and_then(|viewport| viewport.intersection(&bounds)),
+        ));
+    }
+    fn custom(&mut self, _: Option<&Id>, bounds: Rectangle, state: &mut dyn std::any::Any) {
+        if let Some(state) = state.downcast_mut::<Interaction>() {
+            let bounds = Rectangle {
+                x: bounds.x - self.translation.x,
+                y: bounds.y - self.translation.y,
+                ..bounds
+            };
+            state.anchor = self
+                .viewport
+                .and_then(|viewport| viewport.intersection(&bounds));
+        }
+    }
+}
+impl<'a, Message: 'a, R: renderer::Renderer + 'a> From<Field<'a, Message, R>>
+    for Element<'a, Message, Theme, R>
+{
+    fn from(field: Field<'a, Message, R>) -> Self {
+        Element::new(field)
+    }
+}
+
+pub fn focus_operation(
+    session: ModelId,
+    generation: ModelId,
+    path: &str,
+    step: i32,
+) -> impl Operation + 'static {
+    focus::exact(session, generation, path, step)
+}
+pub fn focus<Message: Send + 'static>(
+    session: ModelId,
+    generation: ModelId,
+    path: &str,
+    step: i32,
+) -> Task<Message> {
+    iced::advanced::widget::operate(focus_operation(session, generation, path, step)).discard()
+}

crates/oa-desktop/src/forms/reference_chooser/trigger/focus.rs

@@ -0,0 +1,313 @@
+//! Focus movement and reveal share one root traversal. A form may be inside a
+//! scrollable; restricting traversal to its container would hide that ancestor.
+use super::{FormOwner, Id, ModelId, Operation, Rectangle, Vector, field_id, operation, scope_id};
+use std::collections::BTreeMap;
+
+enum Origin {
+    Current,
+    Exact(Id),
+}
+#[derive(Clone)]
+struct Scroll {
+    index: usize,
+    bounds: Rectangle,
+    capacity: Vector,
+    offset: Vector,
+}
+struct Field {
+    id: Option<Id>,
+    bounds: Rectangle,
+    ancestors: Vec<Scroll>,
+}
+pub(super) struct Collect {
+    scope: Id,
+    origin: Origin,
+    step: i32,
+    inside: bool,
+    entering: Option<bool>,
+    translation: Vector,
+    scrolls: Vec<Scroll>,
+    pending_scroll: Option<Scroll>,
+    scroll_index: usize,
+    fields: Vec<Field>,
+    focused: Option<usize>,
+    outside_focused: bool,
+    modal: bool,
+    owner_valid: bool,
+}
+impl Collect {
+    fn new(scope: Id, origin: Origin, step: i32) -> Self {
+        let owner_valid = matches!(origin, Origin::Current);
+        Self {
+            scope,
+            origin,
+            step,
+            inside: false,
+            entering: None,
+            translation: Vector::ZERO,
+            scrolls: vec![],
+            pending_scroll: None,
+            scroll_index: 0,
+            fields: vec![],
+            focused: None,
+            outside_focused: false,
+            modal: false,
+            owner_valid,
+        }
+    }
+}
+pub(super) fn relative(session: ModelId, backwards: bool, modal: bool) -> Collect {
+    Collect {
+        modal,
+        ..Collect::new(
+            scope_id(session),
+            Origin::Current,
+            if backwards { -1 } else { 1 },
+        )
+    }
+}
+pub(super) fn exact(session: ModelId, generation: ModelId, path: &str, step: i32) -> Collect {
+    Collect::new(
+        scope_id(session),
+        Origin::Exact(field_id(generation, path)),
+        step,
+    )
+}
+impl Operation for Collect {
+    fn custom(&mut self, _: Option<&Id>, _: Rectangle, state: &mut dyn std::any::Any) {
+        if let Some(owner) = state.downcast_ref::<FormOwner>() {
+            self.owner_valid = owner
+                .0
+                .is_some_and(|owner| scope_id(owner.session) == self.scope);
+            self.modal = owner.0.is_some_and(|owner| owner.modal);
+        }
+    }
+    fn container(&mut self, id: Option<&Id>, _: Rectangle) {
+        self.entering = Some(self.inside || id == Some(&self.scope));
+    }
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        let previous = (self.inside, self.translation, self.scrolls.len());
+        if let Some(inside) = self.entering.take() {
+            self.inside = inside;
+        }
+        if let Some(scroll) = self.pending_scroll.take() {
+            self.translation += scroll.offset;
+            self.scrolls.push(scroll);
+        }
+        visit(self);
+        self.inside = previous.0;
+        self.translation = previous.1;
+        self.scrolls.truncate(previous.2);
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&Id>,
+        bounds: Rectangle,
+        content: Rectangle,
+        offset: Vector,
+        _: &mut dyn operation::Scrollable,
+    ) {
+        self.pending_scroll = Some(Scroll {
+            index: self.scroll_index,
+            bounds: translated(bounds, self.translation),
+            capacity: Vector::new(
+                (content.width - bounds.width).max(0.),
+                (content.height - bounds.height).max(0.),
+            ),
+            offset,
+        });
+        self.scroll_index += 1;
+    }
+    fn focusable(
+        &mut self,
+        id: Option<&Id>,
+        bounds: Rectangle,
+        state: &mut dyn operation::Focusable,
+    ) {
+        if !self.inside {
+            self.outside_focused |= state.is_focused();
+            return;
+        }
+        if state.is_focused() {
+            self.focused = Some(self.fields.len());
+        }
+        self.fields.push(Field {
+            id: id.cloned(),
+            bounds: translated(bounds, self.translation),
+            ancestors: self.scrolls.clone(),
+        });
+    }
+    fn finish(&self) -> operation::Outcome<()> {
+        if !self.owner_valid || self.fields.is_empty() {
+            return operation::Outcome::None;
+        }
+        let origin = match &self.origin {
+            Origin::Current if self.focused.is_none() && self.outside_focused && !self.modal => {
+                return operation::Outcome::None;
+            }
+            Origin::Current => self
+                .focused
+                .map(|index| index as i64)
+                .unwrap_or(if self.step < 0 {
+                    self.fields.len() as i64
+                } else {
+                    -1
+                }),
+            Origin::Exact(id) => {
+                let Some(index) = self
+                    .fields
+                    .iter()
+                    .position(|field| field.id.as_ref() == Some(id))
+                else {
+                    return operation::Outcome::None;
+                };
+                index as i64
+            }
+        };
+        // A form keeps a reachable focus at both boundaries. Initial Tab enters
+        // the first field; initial Shift+Tab enters the last field.
+        let target = (origin + i64::from(self.step)).rem_euclid(self.fields.len() as i64) as usize;
+        let field = &self.fields[target];
+        let mut bounds = field.bounds;
+        let mut shifts = BTreeMap::new();
+        for ancestor in field.ancestors.iter().rev() {
+            let dx = reveal_axis(
+                bounds.x,
+                bounds.width,
+                ancestor.bounds.x,
+                ancestor.bounds.width,
+            );
+            let dy = reveal_axis(
+                bounds.y,
+                bounds.height,
+                ancestor.bounds.y,
+                ancestor.bounds.height,
+            );
+            // Iced reports rounded drawing offsets, while capacity can be
+            // fractional. Clamping an already-visible axis can move it a pixel.
+            let delta = Vector::new(
+                if dx == 0. {
+                    0.
+                } else {
+                    (ancestor.offset.x + dx).clamp(0., ancestor.capacity.x) - ancestor.offset.x
+                },
+                if dy == 0. {
+                    0.
+                } else {
+                    (ancestor.offset.y + dy).clamp(0., ancestor.capacity.y) - ancestor.offset.y
+                },
+            );
+            if delta != Vector::ZERO {
+                shifts.insert(ancestor.index, delta);
+            }
+            bounds = translated(bounds, delta);
+        }
+        operation::Outcome::Chain(Box::new(Apply {
+            scope: self.scope.clone(),
+            inside: false,
+            entering: None,
+            target,
+            field_index: 0,
+            scroll_index: 0,
+            shifts,
+            owner_valid: matches!(self.origin, Origin::Current),
+            clear_outside: self.modal,
+            preserve_inside: false,
+        }))
+    }
+}
+fn translated(bounds: Rectangle, delta: Vector) -> Rectangle {
+    Rectangle {
+        x: bounds.x - delta.x,
+        y: bounds.y - delta.y,
+        ..bounds
+    }
+}
+fn reveal_axis(start: f32, length: f32, viewport_start: f32, viewport_length: f32) -> f32 {
+    if start < viewport_start || length > viewport_length {
+        start - viewport_start
+    } else {
+        (start + length - viewport_start - viewport_length).max(0.)
+    }
+}
+pub(super) struct Apply {
+    scope: Id,
+    inside: bool,
+    entering: Option<bool>,
+    target: usize,
+    field_index: usize,
+    scroll_index: usize,
+    shifts: BTreeMap<usize, Vector>,
+    owner_valid: bool,
+    clear_outside: bool,
+    preserve_inside: bool,
+}
+pub(super) fn exclusive() -> Apply {
+    Apply {
+        scope: Id::new(super::REVIEW_MODAL),
+        inside: false,
+        entering: None,
+        target: 0,
+        field_index: 0,
+        scroll_index: 0,
+        shifts: BTreeMap::new(),
+        owner_valid: true,
+        clear_outside: true,
+        preserve_inside: true,
+    }
+}
+impl Operation for Apply {
+    fn custom(&mut self, _: Option<&Id>, _: Rectangle, state: &mut dyn std::any::Any) {
+        if let Some(owner) = state.downcast_ref::<FormOwner>() {
+            self.owner_valid = owner
+                .0
+                .is_some_and(|owner| scope_id(owner.session) == self.scope);
+            self.clear_outside = owner.0.is_some_and(|owner| owner.modal);
+        }
+    }
+    fn container(&mut self, id: Option<&Id>, _: Rectangle) {
+        self.entering = Some(self.inside || id == Some(&self.scope));
+    }
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn Operation)) {
+        let previous = self.inside;
+        if let Some(inside) = self.entering.take() {
+            self.inside = inside;
+        }
+        visit(self);
+        self.inside = previous;
+    }
+    fn scrollable(
+        &mut self,
+        _: Option<&Id>,
+        bounds: Rectangle,
+        content: Rectangle,
+        _: Vector,
+        state: &mut dyn operation::Scrollable,
+    ) {
+        if self.owner_valid
+            && let Some(delta) = self.shifts.get(&self.scroll_index)
+        {
+            state.scroll_by(
+                operation::scrollable::AbsoluteOffset {
+                    x: delta.x,
+                    y: delta.y,
+                },
+                bounds,
+                content,
+            );
+        }
+        self.scroll_index += 1;
+    }
+    fn focusable(&mut self, _: Option<&Id>, _: Rectangle, state: &mut dyn operation::Focusable) {
+        if self.owner_valid && self.inside && !self.preserve_inside {
+            if self.field_index == self.target {
+                state.focus();
+            } else {
+                state.unfocus();
+            }
+            self.field_index += 1;
+        } else if self.owner_valid && !self.inside && self.clear_outside {
+            state.unfocus();
+        }
+    }
+}

crates/oa-desktop/src/forms/reference_chooser/widget.rs

@@ -0,0 +1,994 @@
+//! Root overlay adapter. Keep the wrapper mounted while closed so the release
+//! from a dismissal gesture cannot reach the underlying content. Parent modal
+//! ownership is supplied by the host (pass no chooser while a modal is active).
+use super::{Action, Close, Event as ChoiceEvent, MAX_ROWS, Stamp, State as Chooser};
+use crate::style;
+use iced::{
+    Border, Color, Element, Event, Font, Length, Point, Rectangle, Size, Theme, Vector,
+    advanced::{
+        Clipboard, Layout, Shell, Widget, layout, overlay, renderer,
+        text::{self, Paragraph as _},
+        widget::{Operation, Tree, tree},
+    },
+    alignment, keyboard, mouse, touch,
+    widget::text_input,
+    window,
+};
+use std::{cell::Cell, rc::Rc};
+
+const ROW: f32 = 34.;
+const MARGIN: f32 = 8.;
+
+#[derive(Debug, Clone, Copy)]
+pub(super) struct Geometry {
+    pub popup: Rectangle,
+    pub search: Rectangle,
+    pub current: Rectangle,
+    pub detail: Rectangle,
+    pub close: Rectangle,
+    pub previous: Rectangle,
+    pub next: Rectangle,
+    pub clear: Rectangle,
+    pub rows: usize,
+}
+impl Geometry {
+    fn new(anchor: Rectangle, viewport: Size) -> Self {
+        let width = anchor
+            .width
+            .clamp(278., 420.)
+            .min((viewport.width - 2. * MARGIN).max(0.));
+        let height = 360f32.min((viewport.height - 2. * MARGIN).max(0.));
+        let x = anchor.x.clamp(
+            MARGIN.min(viewport.width / 2.),
+            (viewport.width - MARGIN - width).max(MARGIN.min(viewport.width / 2.)),
+        );
+        let below = anchor.y + anchor.height + 4.;
+        let preferred = if below + height + MARGIN <= viewport.height {
+            below
+        } else {
+            anchor.y - height - 4.
+        };
+        let y = preferred.clamp(
+            MARGIN.min(viewport.height / 2.),
+            (viewport.height - MARGIN - height).max(MARGIN.min(viewport.height / 2.)),
+        );
+        Self::from_bounds(Rectangle {
+            x,
+            y,
+            width,
+            height,
+        })
+    }
+    pub(super) fn from_bounds(popup: Rectangle) -> Self {
+        let inner = (popup.width - 16.).max(0.);
+        let rect = |left, top, width, height| Rectangle {
+            x: popup.x + left,
+            y: popup.y + top,
+            width,
+            height,
+        };
+        let footer = (popup.height - 32.).max(0.);
+        let detail_height = if popup.height >= 180. { 32. } else { 0. };
+        let detail_top = (footer - detail_height - 4.).max(84.);
+        let rows = (((detail_top - 88.).max(0.) / ROW) as usize).min(MAX_ROWS);
+        Self {
+            popup,
+            search: rect(8., 28., inner, 30.),
+            current: rect(8., 62., inner, 18.),
+            detail: rect(8., detail_top, inner, detail_height),
+            close: rect((popup.width - 58.).max(0.), 4., 50f32.min(popup.width), 22.),
+            previous: rect(8., footer, 28., 24.),
+            next: rect(40., footer, 28., 24.),
+            clear: rect((popup.width - 84.).max(0.), footer, 76., 24.),
+            rows,
+        }
+    }
+    pub fn row(&self, index: usize) -> Rectangle {
+        Rectangle {
+            x: self.popup.x + 8.,
+            y: self.popup.y + 84. + index as f32 * ROW,
+            width: (self.popup.width - 16.).max(0.),
+            height: ROW,
+        }
+    }
+    fn hit(&self, chooser: &Chooser, point: Point) -> Option<Action> {
+        if self.close.contains(point) {
+            return Some(Action::Close(Close::Escape));
+        }
+        if self.previous.contains(point) && chooser.start() > 0 {
+            return Some(Action::Page {
+                delta: -1,
+                rows: self.rows,
+            });
+        }
+        if self.next.contains(point) && chooser.start() + self.rows < chooser.count() {
+            return Some(Action::Page {
+                delta: 1,
+                rows: self.rows,
+            });
+        }
+        if self.clear.contains(point) && chooser.optional() {
+            return Some(Action::Clear);
+        }
+        chooser
+            .visible(self.rows)
+            .enumerate()
+            .find_map(|(i, c)| self.row(i).contains(point).then_some(Action::Choose(c.id)))
+    }
+}
+
+#[derive(Default)]
+struct Interaction {
+    stamp: Option<Stamp>,
+    serial: u64,
+    pressed: Option<(ChoiceEvent, Pointer)>,
+    closing: bool,
+    swallow_mouse: Option<mouse::Button>,
+    swallow_touch: Option<touch::Finger>,
+    held_mouse: Option<mouse::Button>,
+    held_touch: Option<touch::Finger>,
+    detail_scroll: f32,
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Pointer {
+    Mouse,
+    Touch(touch::Finger),
+}
+impl Interaction {
+    fn swallow(&mut self, event: &Event) -> bool {
+        match event {
+            Event::Mouse(mouse::Event::ButtonReleased(button))
+                if self.swallow_mouse == Some(*button) =>
+            {
+                self.swallow_mouse = None;
+                true
+            }
+            Event::Touch(
+                touch::Event::FingerLifted { id, .. } | touch::Event::FingerLost { id, .. },
+            ) if self.swallow_touch == Some(*id) => {
+                self.swallow_touch = None;
+                true
+            }
+            _ => false,
+        }
+    }
+}
+
+pub struct Popup<'a, Message, R = iced::Renderer>
+where
+    R: text::Renderer<Font = Font>,
+{
+    content: Element<'a, Message, Theme, R>,
+    input: Element<'a, String, Theme, R>,
+    chooser: Option<&'a Chooser>,
+    anchor: Rectangle,
+    on_event: Rc<dyn Fn(ChoiceEvent) -> Message + 'a>,
+    focus_scope: Option<super::trigger::FormScope>,
+}
+impl<'a, Message: Clone + 'a, R: text::Renderer<Font = Font> + 'a> Popup<'a, Message, R> {
+    pub fn new(
+        content: impl Into<Element<'a, Message, Theme, R>>,
+        chooser: Option<&'a Chooser>,
+        anchor: Rectangle,
+        on_event: impl Fn(ChoiceEvent) -> Message + 'a,
+    ) -> Self {
+        let chooser = chooser.filter(|state| state.is_open());
+        let input = text_input(
+            "Name, @alias, kind or containment",
+            chooser.map_or("", Chooser::query),
+        )
+        .on_input(std::convert::identity)
+        .size(12)
+        .padding(6)
+        .width(Length::Fill)
+        .into();
+        Self {
+            content: content.into(),
+            input,
+            chooser,
+            anchor,
+            on_event: Rc::new(on_event),
+            focus_scope: None,
+        }
+    }
+    pub fn focus_scope(mut self, scope: Option<super::trigger::FormScope>) -> Self {
+        self.focus_scope = scope;
+        self
+    }
+    fn reconcile(&self, tree: &mut Tree) {
+        let state = tree.state.downcast_mut::<Interaction>();
+        let stamp = self.chooser.map(Chooser::stamp);
+        if state.stamp.as_ref().map(|s| s.invocation) != stamp.as_ref().map(|s| s.invocation) {
+            let input = tree.children[1]
+                .state
+                .downcast_mut::<text_input::State<R::Paragraph>>();
+            if stamp.is_some() {
+                input.focus();
+            } else {
+                input.unfocus();
+            }
+            state.closing = false;
+            state.serial = self.chooser.map_or(0, Chooser::query_serial);
+        }
+        if state.stamp != stamp {
+            state.pressed = None;
+            // A queued Choose can be rejected after a preceding query changed
+            // the result generation. Reconciliation must unlock this view.
+            state.closing = false;
+            state.detail_scroll = 0.;
+        }
+        state.stamp = stamp;
+    }
+}
+impl<Message: Clone, R: text::Renderer<Font = Font>> Widget<Message, Theme, R>
+    for Popup<'_, Message, R>
+{
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<Interaction>()
+    }
+    fn state(&self) -> tree::State {
+        tree::State::new(Interaction::default())
+    }
+    fn children(&self) -> Vec<Tree> {
+        vec![
+            Tree::new(self.content.as_widget()),
+            Tree::new(self.input.as_widget()),
+        ]
+    }
+    fn diff(&self, tree: &mut Tree) {
+        tree.children[0].diff(self.content.as_widget());
+        tree.children[1].diff(self.input.as_widget());
+        self.reconcile(tree);
+    }
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn layout(&mut self, tree: &mut Tree, renderer: &R, limits: &layout::Limits) -> layout::Node {
+        self.reconcile(tree);
+        self.content
+            .as_widget_mut()
+            .layout(&mut tree.children[0], renderer, limits)
+    }
+    fn operate(
+        &mut self,
+        tree: &mut Tree,
+        layout: Layout<'_>,
+        renderer: &R,
+        operation: &mut dyn Operation,
+    ) {
+        let mut owner =
+            super::trigger::FormOwner(self.focus_scope.filter(|_| self.chooser.is_none()));
+        operation.custom(None, layout.bounds(), &mut owner);
+        self.content
+            .as_widget_mut()
+            .operate(&mut tree.children[0], layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        let state = tree.state.downcast_mut::<Interaction>();
+        if state.swallow(event) || self.chooser.is_some() && is_input(event) {
+            shell.capture_event();
+            return;
+        }
+        if is_input(event) && self.focus_scope.is_some_and(|scope| scope.modal) {
+            super::trigger::own_input(&mut self.content, &mut tree.children[0], layout, renderer);
+        }
+        if let Event::Keyboard(keyboard::Event::KeyPressed {
+            key: keyboard::Key::Named(keyboard::key::Named::Tab),
+            modifiers,
+            ..
+        }) = event
+            && let Some(scope) = self.focus_scope
+            && super::trigger::tab(
+                &mut self.content,
+                &mut tree.children[0],
+                layout,
+                renderer,
+                scope,
+                modifiers.shift(),
+            )
+        {
+            shell.capture_event();
+            shell.request_redraw();
+            return;
+        }
+        super::trigger::measure(
+            &mut self.content,
+            &mut tree.children[0],
+            layout,
+            renderer,
+            *viewport,
+        );
+        self.content.as_widget_mut().update(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor,
+            renderer,
+            clipboard,
+            shell,
+            viewport,
+        );
+    }
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut R,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            theme,
+            style,
+            layout,
+            if self.chooser.is_some() {
+                mouse::Cursor::Unavailable
+            } else {
+                cursor
+            },
+            viewport,
+        );
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        if self.chooser.is_some() {
+            mouse::Interaction::None
+        } else {
+            self.content.as_widget().mouse_interaction(
+                &tree.children[0],
+                layout,
+                cursor,
+                viewport,
+                renderer,
+            )
+        }
+    }
+    fn overlay<'b>(
+        &'b mut self,
+        tree: &'b mut Tree,
+        layout: Layout<'b>,
+        renderer: &R,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'b, Message, Theme, R>> {
+        if let Some(chooser) = self.chooser {
+            Some(overlay::Element::new(Box::new(ChooserOverlay {
+                chooser,
+                anchor: self.anchor,
+                state: tree.state.downcast_mut(),
+                input: &mut self.input,
+                input_tree: &mut tree.children[1],
+                on_event: &*self.on_event,
+            })))
+        } else {
+            self.content.as_widget_mut().overlay(
+                &mut tree.children[0],
+                layout,
+                renderer,
+                viewport,
+                translation,
+            )
+        }
+    }
+}
+impl<'a, Message: Clone + 'a, R: text::Renderer<Font = Font> + 'a> From<Popup<'a, Message, R>>
+    for Element<'a, Message, Theme, R>
+{
+    fn from(popup: Popup<'a, Message, R>) -> Self {
+        Element::new(popup)
+    }
+}
+
+struct ChooserOverlay<'b, 'a, Message, R: text::Renderer<Font = Font>> {
+    chooser: &'a Chooser,
+    anchor: Rectangle,
+    state: &'b mut Interaction,
+    input: &'b mut Element<'a, String, Theme, R>,
+    input_tree: &'b mut Tree,
+    on_event: &'b dyn Fn(ChoiceEvent) -> Message,
+}
+impl<Message, R: text::Renderer<Font = Font>> ChooserOverlay<'_, '_, Message, R> {
+    fn geometry(&self, layout: Layout<'_>) -> Geometry {
+        Geometry::from_bounds(
+            layout
+                .children()
+                .next()
+                .expect("measured chooser bounds")
+                .bounds(),
+        )
+    }
+    fn publish(&mut self, action: Action, shell: &mut Shell<'_, Message>) {
+        if self.state.closing {
+            return;
+        }
+        if action.writes_staged_value() || matches!(action, Action::Close(_)) {
+            self.state.closing = true;
+            self.state.swallow_mouse = self.state.held_mouse.or(self.state.swallow_mouse);
+            self.state.swallow_touch = self.state.held_touch.or(self.state.swallow_touch);
+        }
+        shell.publish((self.on_event)(self.chooser.event(action)));
+    }
+    fn press(
+        &mut self,
+        point: Point,
+        pointer: Pointer,
+        geometry: Geometry,
+        shell: &mut Shell<'_, Message>,
+    ) {
+        if !geometry.popup.contains(point) {
+            self.publish(Action::Close(Close::Outside), shell);
+        } else {
+            self.state.pressed = geometry
+                .hit(self.chooser, point)
+                .map(|action| (self.chooser.event(action), pointer));
+        }
+    }
+    fn release(
+        &mut self,
+        point: Point,
+        pointer: Pointer,
+        geometry: Geometry,
+        shell: &mut Shell<'_, Message>,
+    ) {
+        if let Some((pressed, origin)) = self.state.pressed.take()
+            && origin == pointer
+            && pressed.stamp == self.chooser.stamp()
+            && geometry.hit(self.chooser, point).as_ref() == Some(&pressed.action)
+        {
+            self.publish(pressed.action, shell);
+        }
+    }
+}
+impl<Message: Clone, R: text::Renderer<Font = Font>> overlay::Overlay<Message, Theme, R>
+    for ChooserOverlay<'_, '_, Message, R>
+{
+    fn layout(&mut self, renderer: &R, bounds: Size) -> layout::Node {
+        let geometry = Geometry::new(self.anchor, bounds);
+        let input = self
+            .input
+            .as_widget_mut()
+            .layout(
+                self.input_tree,
+                renderer,
+                &layout::Limits::new(Size::ZERO, geometry.search.size()),
+            )
+            .move_to(geometry.search.position());
+        layout::Node::with_children(
+            bounds,
+            vec![
+                layout::Node::new(geometry.popup.size()).move_to(geometry.popup.position()),
+                input,
+            ],
+        )
+    }
+    fn operate(&mut self, layout: Layout<'_>, renderer: &R, operation: &mut dyn Operation) {
+        self.input.as_widget_mut().operate(
+            self.input_tree,
+            layout.children().nth(1).unwrap(),
+            renderer,
+            operation,
+        );
+    }
+    fn update(
+        &mut self,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+    ) {
+        let geometry = self.geometry(layout);
+        match event {
+            Event::Mouse(mouse::Event::ButtonPressed(button)) => {
+                self.state.held_mouse = Some(*button)
+            }
+            Event::Mouse(mouse::Event::ButtonReleased(button))
+                if self.state.held_mouse == Some(*button) =>
+            {
+                self.state.held_mouse = None
+            }
+            Event::Touch(touch::Event::FingerPressed { id, .. }) => {
+                self.state.held_touch = Some(*id)
+            }
+            Event::Touch(
+                touch::Event::FingerLifted { id, .. } | touch::Event::FingerLost { id, .. },
+            ) if self.state.held_touch == Some(*id) => self.state.held_touch = None,
+            _ => {}
+        }
+        if self.state.swallow(event) {
+            shell.capture_event();
+            return;
+        }
+        if self.state.closing {
+            if is_input(event) {
+                shell.capture_event();
+            }
+            return;
+        }
+        let mut handled = false;
+        match event {
+            Event::Keyboard(keyboard::Event::KeyPressed { key, modifiers, .. }) => {
+                use keyboard::key::Named;
+                let action = match key {
+                    keyboard::Key::Named(Named::Escape) => Some(Action::Close(Close::Escape)),
+                    keyboard::Key::Named(Named::Tab) => Some(Action::Close(Close::Tab {
+                        backwards: modifiers.shift(),
+                    })),
+                    keyboard::Key::Named(Named::ArrowDown) => Some(Action::Move {
+                        delta: 1,
+                        rows: geometry.rows,
+                    }),
+                    keyboard::Key::Named(Named::ArrowUp) => Some(Action::Move {
+                        delta: -1,
+                        rows: geometry.rows,
+                    }),
+                    keyboard::Key::Named(Named::PageDown) => Some(Action::Page {
+                        delta: 1,
+                        rows: geometry.rows,
+                    }),
+                    keyboard::Key::Named(Named::PageUp) => Some(Action::Page {
+                        delta: -1,
+                        rows: geometry.rows,
+                    }),
+                    keyboard::Key::Named(Named::Enter) => {
+                        handled = true;
+                        self.chooser
+                            .highlighted()
+                            .filter(|c| self.chooser.visible(geometry.rows).any(|v| v.id == c.id))
+                            .map(|c| Action::Choose(c.id))
+                    }
+                    keyboard::Key::Character(c)
+                        if modifiers.control()
+                            && modifiers.shift()
+                            && c.eq_ignore_ascii_case("c") =>
+                    {
+                        clipboard.write(
+                            iced::advanced::clipboard::Kind::Standard,
+                            self.chooser
+                                .highlighted()
+                                .map_or_else(|| self.chooser.current.label(), |c| c.detail()),
+                        );
+                        handled = true;
+                        None
+                    }
+                    _ => None,
+                };
+                if let Some(action) = action {
+                    self.publish(action, shell);
+                    handled = true;
+                }
+            }
+            Event::Window(window::Event::Resized(_) | window::Event::Unfocused) => {
+                self.publish(Action::Close(Close::WindowChanged), shell);
+                handled = true;
+            }
+            Event::Mouse(mouse::Event::ButtonPressed(button)) => {
+                if let Some(point) = cursor.position() {
+                    if !geometry.popup.contains(point) {
+                        self.state.swallow_mouse = Some(*button);
+                        self.press(point, Pointer::Mouse, geometry, shell);
+                        handled = true;
+                    } else if *button == mouse::Button::Left && !geometry.search.contains(point) {
+                        self.press(point, Pointer::Mouse, geometry, shell);
+                        handled = true;
+                    }
+                }
+            }
+            Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left))
+                if self.state.pressed.is_some() =>
+            {
+                if let Some(point) = cursor.position() {
+                    self.release(point, Pointer::Mouse, geometry, shell);
+                } else {
+                    self.state.pressed = None;
+                }
+                handled = true;
+            }
+            Event::Mouse(mouse::Event::CursorMoved { position })
+                if self.state.pressed.is_none() =>
+            {
+                if let Some(Action::Choose(id)) = geometry.hit(self.chooser, *position)
+                    && self
+                        .chooser
+                        .highlighted()
+                        .is_none_or(|candidate| candidate.id != id)
+                {
+                    self.publish(Action::Highlight(id), shell);
+                }
+            }
+            Event::Mouse(mouse::Event::WheelScrolled { delta }) => {
+                let (x, y) = match delta {
+                    mouse::ScrollDelta::Lines { x, y } => (*x * 24., *y * 24.),
+                    mouse::ScrollDelta::Pixels { x, y } => (*x, *y),
+                };
+                self.state.pressed = None;
+                if cursor
+                    .position()
+                    .is_some_and(|p| geometry.detail.contains(p))
+                {
+                    let detail = self
+                        .chooser
+                        .highlighted()
+                        .map_or_else(|| self.chooser.current.label(), |c| c.detail());
+                    let max = (measure::<R>(&detail, 11., renderer.default_font())
+                        - geometry.detail.width)
+                        .max(0.);
+                    self.state.detail_scroll =
+                        (self.state.detail_scroll - if x != 0. { x } else { y }).clamp(0., max);
+                    shell.request_redraw();
+                } else if y != 0. {
+                    self.publish(
+                        Action::Page {
+                            delta: if y < 0. { 1 } else { -1 },
+                            rows: geometry.rows,
+                        },
+                        shell,
+                    );
+                }
+                handled = true;
+            }
+            Event::Touch(touch::Event::FingerPressed { id, position })
+                if !geometry.search.contains(*position) =>
+            {
+                if !geometry.popup.contains(*position) {
+                    self.state.swallow_touch = Some(*id);
+                }
+                self.press(*position, Pointer::Touch(*id), geometry, shell);
+                handled = true;
+            }
+            Event::Touch(touch::Event::FingerLifted { id, position })
+                if self.state.pressed.is_some() =>
+            {
+                self.release(*position, Pointer::Touch(*id), geometry, shell);
+                handled = true;
+            }
+            Event::Touch(touch::Event::FingerLost { .. } | touch::Event::FingerMoved { .. }) => {
+                self.state.pressed = None;
+            }
+            _ => {}
+        }
+        if !handled {
+            let mut messages = Vec::new();
+            let mut input_shell = Shell::new(&mut messages);
+            self.input.as_widget_mut().update(
+                self.input_tree,
+                event,
+                layout.children().nth(1).unwrap(),
+                cursor,
+                renderer,
+                clipboard,
+                &mut input_shell,
+                &geometry.popup,
+            );
+            let serial = Cell::new(self.state.serial);
+            shell.merge(input_shell, |text| {
+                serial.set(serial.get().saturating_add(1));
+                (self.on_event)(self.chooser.event(Action::Query {
+                    text,
+                    serial: serial.get(),
+                }))
+            });
+            self.state.serial = serial.get();
+        }
+        if is_input(event) {
+            shell.capture_event();
+        }
+    }
+    fn draw(
+        &self,
+        renderer: &mut R,
+        theme: &Theme,
+        renderer_style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+    ) {
+        let geometry = self.geometry(layout);
+        renderer.fill_quad(
+            renderer::Quad {
+                bounds: geometry.popup,
+                border: Border {
+                    color: style::LINE,
+                    width: 1.,
+                    radius: 8.into(),
+                },
+                ..Default::default()
+            },
+            Color::WHITE,
+        );
+        renderer.with_layer(geometry.popup, |renderer| {
+            label(
+                renderer,
+                &self.chooser.scope_label,
+                11.,
+                style::MUTED,
+                Rectangle {
+                    x: geometry.popup.x + 8.,
+                    y: geometry.popup.y + 4.,
+                    width: (geometry.popup.width - 78.).max(0.),
+                    height: 22.,
+                },
+            );
+            label(renderer, "Close", 11., style::TEAL, geometry.close);
+            label(
+                renderer,
+                &self.chooser.current.label(),
+                11.,
+                style::MUTED,
+                geometry.current,
+            );
+            for (i, candidate) in self.chooser.visible(geometry.rows).enumerate() {
+                let row = geometry.row(i);
+                if self
+                    .chooser
+                    .highlighted()
+                    .is_some_and(|c| c.id == candidate.id)
+                {
+                    renderer.fill_quad(
+                        renderer::Quad {
+                            bounds: row,
+                            ..Default::default()
+                        },
+                        Color::from_rgb8(218, 238, 235),
+                    );
+                }
+                let alias_width = (row.width * 0.42).min(
+                    measure::<R>(
+                        &format!("@{}", candidate.alias),
+                        11.,
+                        renderer.default_font(),
+                    ) + 4.,
+                );
+                label(
+                    renderer,
+                    &candidate.name,
+                    12.,
+                    style::INK,
+                    Rectangle {
+                        width: (row.width - alias_width - 6.).max(0.),
+                        height: 17.,
+                        ..row
+                    },
+                );
+                label(
+                    renderer,
+                    &format!("@{}", candidate.alias),
+                    11.,
+                    style::INK,
+                    Rectangle {
+                        x: row.x + row.width - alias_width,
+                        width: alias_width,
+                        height: 17.,
+                        ..row
+                    },
+                );
+                label(
+                    renderer,
+                    &candidate.context_label(),
+                    10.,
+                    style::MUTED,
+                    Rectangle {
+                        y: row.y + 17.,
+                        height: 17.,
+                        ..row
+                    },
+                );
+            }
+            if self.chooser.count() == 0 {
+                label(
+                    renderer,
+                    "No compatible matches. Clear the query.",
+                    11.,
+                    style::MUTED,
+                    geometry.row(0),
+                );
+            }
+            let detail = self
+                .chooser
+                .highlighted()
+                .map_or_else(|| self.chooser.current.label(), |c| c.detail());
+            renderer.with_layer(geometry.detail, |renderer| {
+                raw_label(
+                    renderer,
+                    detail,
+                    11.,
+                    style::MUTED,
+                    Rectangle {
+                        x: geometry.detail.x - self.state.detail_scroll,
+                        width: geometry.detail.width + self.state.detail_scroll,
+                        height: 16.,
+                        ..geometry.detail
+                    },
+                );
+                label(
+                    renderer,
+                    "Scroll details · Ctrl+Shift+C copies",
+                    10.,
+                    style::MUTED,
+                    Rectangle {
+                        y: geometry.detail.y + 16.,
+                        height: 16.,
+                        ..geometry.detail
+                    },
+                );
+            });
+            label(
+                renderer,
+                "‹",
+                15.,
+                if self.chooser.start() > 0 {
+                    style::TEAL
+                } else {
+                    style::MUTED
+                },
+                geometry.previous,
+            );
+            label(
+                renderer,
+                "›",
+                15.,
+                if self.chooser.start() + geometry.rows < self.chooser.count() {
+                    style::TEAL
+                } else {
+                    style::MUTED
+                },
+                geometry.next,
+            );
+            let count = if self.chooser.count() == 0 {
+                "0 results".into()
+            } else {
+                format!(
+                    "{}–{} / {}",
+                    self.chooser.start() + 1,
+                    (self.chooser.start() + geometry.rows).min(self.chooser.count()),
+                    self.chooser.count()
+                )
+            };
+            label(
+                renderer,
+                &count,
+                11.,
+                style::MUTED,
+                Rectangle {
+                    x: geometry.next.x + 30.,
+                    width: (geometry.clear.x - geometry.next.x - 32.).max(0.),
+                    ..geometry.next
+                },
+            );
+            if self.chooser.optional() {
+                label(
+                    renderer,
+                    "Clear reference",
+                    10.,
+                    style::TEAL,
+                    geometry.clear,
+                );
+            }
+            self.input.as_widget().draw(
+                self.input_tree,
+                renderer,
+                theme,
+                renderer_style,
+                layout.children().nth(1).unwrap(),
+                cursor,
+                &geometry.popup,
+            );
+        });
+    }
+    fn mouse_interaction(
+        &self,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &R,
+    ) -> mouse::Interaction {
+        let geometry = self.geometry(layout);
+        if cursor
+            .position()
+            .is_some_and(|p| geometry.hit(self.chooser, p).is_some())
+        {
+            mouse::Interaction::Pointer
+        } else {
+            self.input.as_widget().mouse_interaction(
+                self.input_tree,
+                layout.children().nth(1).unwrap(),
+                cursor,
+                &geometry.popup,
+                renderer,
+            )
+        }
+    }
+}
+
+fn is_input(event: &Event) -> bool {
+    matches!(
+        event,
+        Event::Mouse(_) | Event::Touch(_) | Event::Keyboard(_) | Event::InputMethod(_)
+    )
+}
+fn measure<R: text::Renderer<Font = Font>>(content: &str, size: f32, font: Font) -> f32 {
+    R::Paragraph::with_text(text::Text {
+        content,
+        bounds: Size::INFINITE,
+        size: size.into(),
+        line_height: text::LineHeight::default(),
+        font,
+        align_x: text::Alignment::Left,
+        align_y: alignment::Vertical::Center,
+        shaping: text::Shaping::Advanced,
+        wrapping: text::Wrapping::None,
+    })
+    .min_width()
+}
+fn label<R: text::Renderer<Font = Font>>(
+    renderer: &mut R,
+    content: &str,
+    size: f32,
+    color: Color,
+    bounds: Rectangle,
+) {
+    let font = renderer.default_font();
+    let mut display = content.to_owned();
+    if measure::<R>(content, size, font) > bounds.width {
+        let ends: Vec<_> = content
+            .char_indices()
+            .map(|(i, _)| i)
+            .chain(std::iter::once(content.len()))
+            .collect();
+        let (mut low, mut high) = (0, ends.len());
+        while low + 1 < high {
+            let middle = (low + high) / 2;
+            if measure::<R>(&format!("{}…", &content[..ends[middle]]), size, font) <= bounds.width
+            {
+                low = middle;
+            } else {
+                high = middle;
+            }
+        }
+        display = format!("{}…", &content[..ends[low]]);
+    }
+    raw_label(renderer, display, size, color, bounds);
+}
+fn raw_label<R: text::Renderer<Font = Font>>(
+    renderer: &mut R,
+    content: String,
+    size: f32,
+    color: Color,
+    bounds: Rectangle,
+) {
+    renderer.fill_text(
+        text::Text {
+            content,
+            bounds: bounds.size(),
+            size: size.into(),
+            line_height: text::LineHeight::default(),
+            font: renderer.default_font(),
+            align_x: text::Alignment::Left,
+            align_y: alignment::Vertical::Center,
+            shaping: text::Shaping::Advanced,
+            wrapping: text::Wrapping::None,
+        },
+        Point::new(bounds.x, bounds.center_y()),
+        color,
+        bounds,
+    );
+}

crates/oa-desktop/src/guide.rs

@@ -445,28 +445,32 @@ fn article(topic: Topic) -> Article {
                         walkthrough(
                             "Describe a path through exchanges",
                             &[
-                                "A blank path offers Add first activity/function contribution. You can use existing work or stage a new source in that form; exchanges still need explicit compatible source and target work.",
+                                "On an empty path, choose Work (W) from the right palette and click the canvas. You can use existing work or stage a new source in that form; exchanges still need explicit compatible source and target work.",
                                 "Open Behavior & scenarios → New. Choose Operational process in OA or Functional chain in SA, enter its exact name, then Create and open. The new behavior belongs at the layer root and opens immediately; Undo removes the creation as one edit.",
-                                "Open Tools and choose Work or Exchange, then a highlighted position. In Work, Create new source keeps the contribution name and position while you name its Activity/Function and choose its semantic parent. Use this new source stages it; Create commits source and contribution in one Undo. An adjacent exchange may require a particular existing work identity.",
-                                "In Tools, choose Sequence link and click or drag from the preceding contribution to the following contribution. Choose Tools → Select / reorder to drag a selected path endpoint and reconnect it; a contribution's ↕ handle changes its position within a column. These are local contributions and sequence links, not new architecture exchanges.",
-                                "Select a contribution, then add another after it. Tools → Two paths… creates a split, two paths and their merge in one undoable edit. Enter explicit alternative conditions. Fit overview uses the visible canvas area; 100% keeps working scale with scrollbars. If the minimum zoom is reached, scroll to inspect the remainder.",
+                                "Choose Work (W) or Exchange (E) from the permanent palette on the right, then a highlighted position. Hover a palette button to read its tool name. In Work, Create new source keeps the contribution name and position while you name its Activity/Function and choose its semantic parent. Use this new source stages it; Create commits source and contribution in one Undo. An adjacent exchange may require a particular existing work identity.",
+                                "Choose Sequence link (->) and click or drag from the preceding contribution to the following contribution. Choose Select contributions or paths (S) to drag a selected path endpoint and reconnect it. A contribution's ↕ handle reorders contributions within the same column; links determine the columns. These are local contributions and sequence links, not new architecture exchanges.",
+                                "Select a contribution, then add another after it. Details → Two paths... creates a split, two paths and their merge in one undoable edit. Enter explicit alternative conditions.",
                                 "Use Chain involvement from the Process/Functional chain to the capability it supports. Read Model checks for unfinished or disconnected paths.",
                             ],
                         ),
+                        explain(
+                            "Navigate the canvas",
+                            "The header and palette stay available while Details and creation forms overlay the canvas. Fit frames the contents; −/+ changes zoom and 100% restores working scale. Focus the canvas to zoom with the wheel or pan with middle-button drag or Space + left drag. F6 enters or leaves canvas controls; Tab moves to the next control, Enter/Space activates it, and Escape leaves canvas controls or cancels a gesture.",
+                        ),
                         explain(
                             "Choose the right behavioral description",
                             "A chain concentrates on a route through existing exchanges. A scenario can also carry actions, state observations, lifelines and nested fragments. The architecture diagram remains a view of the possible relationships rather than an execution trace.",
                         ),
                         explain(
                             "Review the path as an engineer",
-                            "Check that exchanges express meaningful handoffs and that the links and branch guards support the selected outcome. Use Tools → Reuse to involve an existing process or chain as a nested reference. For an imported ordered exchange path, Append exchange… continues that path; Convert ordered path to explicit links exposes its implied links for topology editing. Conversion preserves the original order in one undoable change.",
+                            "Check that exchanges express meaningful handoffs and that the links and branch guards support the selected outcome. Use Reuse process / chain (ref) in the palette to involve an existing process or chain as a nested reference. For an imported ordered exchange path, Details → Append exchange... continues that path; Edit path links and guards exposes its implied links for topology editing. Conversion preserves the original order in one undoable change.",
                         ),
                         walkthrough(
                             "Connect a particular use of a procedure",
                             &[
-                                "Choose Focus canvas for more working space; Restore panels brings the explorer and properties back. Select a contribution inside a reusable preview, then open Selection details to read its complete caller and reference identity.",
-                                "In Selection details, use Expand nested reference or Fold nested reference to inspect that instance. Open source or Open contribution definition visits the shared definition; Back to caller returns to the original caller context.",
-                                "Open Tools → Qualified link / assembly… and choose its source and target. Use Enter reference to open an instance's contributions, Up one reference for its caller scope, or Root for the link owner. Search and page through all contributions in that scope, then select the exact endpoint. The first and second uses of a procedure remain different choices even when their work has the same name.",
+                                "Choose Focus canvas for more working space; Restore panels brings the explorer and properties back. Select a contribution inside a reusable preview, then open Details to read its complete caller and reference identity.",
+                                "In Details, use Expand nested reference or Fold nested reference to inspect that instance. Open source or Open contribution definition visits the shared definition; Back to caller returns to the original caller context.",
+                                "Open Details → Qualified link / assembly... and choose its source and target. Use Enter reference to open an instance's contributions, Up one reference for its caller scope, or Root for the link owner. Search and page through all contributions in that scope, then select the exact endpoint. The first and second uses of a procedure remain different choices even when their work has the same name.",
                                 "Choose Precedence to describe order and its guard, Exchange assembly to identify a work exchange between the contributions, or Common work incidence to state that both use the same work. Select the engineering identity when required, then Apply link.",
                             ],
                         ),
@@ -490,19 +494,23 @@ fn article(topic: Topic) -> Article {
                             "Create a scenario",
                             &[
                                 "Open Behavior & scenarios → New → Scenario and enter its name. Explicitly choose Activities or Participants in OA, or Functions or System boundary in SA. Add optional context only when needed: this is a reference, while the scenario itself belongs at the layer root. Create and open starts the empty scenario.",
-                                "Use Add first lifeline on an empty scenario, or + Lifeline. Choose existing work/participant or Create new source. The explicit viewpoint limits its kinds; choose participant kinds deliberately. Source name and lifeline name are separate, and the source semantic parent is independent of the scenario. No allocation or capability involvement is inferred.",
-                                "Choose a message style in the tool selector. Start at a highlighted sequence position on a lifeline, then click or drag to the receiving lifeline. Complete the exchange and details in the form, which retains that sequence position. Escape cancels the gesture.",
-                                "Call + correlated reply creates both occurrences in one edit. Reply to existing call offers valid unanswered calls. A local timer has an expression and a lifeline, with no global exchange. Create and delete messages describe participant lifetime; Model checks also flag risks inside repeated loops.",
-                                "Choose Add action, Observe state, Reuse scenario or Add fragment and click the intended sequence position. Clicking an action or observation on a lifeline also selects that lifeline. Complete any remaining choices before Create.",
-                                "In Select / reorder, click an occurrence and drag its ↕ handle to another position within the same sequence. The ordered list's up/down controls provide another way to reorder. Select an occurrence to inspect its particular use of the exchange, including its message values.",
+                                "Choose Lifeline (L) in the permanent palette on the right, then click the canvas. Choose existing work/participant or Create new source. The explicit viewpoint limits its kinds; choose participant kinds deliberately. Source name and lifeline name are separate, and the source semantic parent is independent of the scenario. No allocation or capability involvement is inferred.",
+                                "Choose a message style from the palette; hover a button to read its tool name. Start at a highlighted sequence position on a lifeline, then click or drag to the receiving lifeline. Complete the exchange and details in the form, which retains that sequence position. Escape cancels the gesture.",
+                                "Call and correlated reply (C/R) creates both occurrences in one edit. Reply to existing call offers valid unanswered calls. A local timer has an expression and a lifeline, with no global exchange. Create and delete messages describe participant lifetime; Model checks also flag risks inside repeated loops.",
+                                "Choose Action (A), State observation (St), Reuse scenario (ref) or Fragment (alt) and click the intended sequence position. Clicking an action or observation on a lifeline also selects that lifeline. Complete any remaining choices before Create.",
+                                "Choose Select / reorder occurrences (S) and drag an occurrence itself to another position within the same sequence. A drag into another fragment operand is refused. Open Details for the ordered list's up/down controls or Properties for the selected occurrence, including its message values.",
                             ],
                         ),
+                        explain(
+                            "Navigate the canvas",
+                            "The header and palette stay available while Details and creation forms overlay the canvas. Fit frames the contents; −/+ changes zoom and 100% restores working scale. Focus the canvas to zoom with the wheel or pan with middle-button drag or Space + left drag. F6 enters or leaves canvas controls; Tab moves to the next control, Enter/Space activates it, and Escape leaves canvas controls or cancels a gesture.",
+                        ),
                         walkthrough(
                             "Describe alternatives",
                             &[
-                                "Choose Add fragment, click its sequence position and select ALT, PAR, LOOP or OPT. Enter the branch conditions; the tool creates the fragment and its operands together.",
+                                "Choose Fragment (alt), click its sequence position and select ALT, PAR, LOOP or OPT. Enter the branch conditions; the tool creates the fragment and its operands together.",
                                 "Click the highlighted position inside an operand to place the next message, action or reference there. The form shows its destination and insertion position. Append to this sequence instead explicitly moves the pending insertion to that sequence's end.",
-                                "Choose Reuse scenario and click its position, then bind every referenced lifeline to a compatible local lifeline explicitly. Select the resulting use and choose Open definition. Back to caller returns to that exact use and its viewport after you apply or cancel pending edits.",
+                                "Choose Reuse scenario and click its position, then bind every referenced lifeline to a compatible local lifeline explicitly. Select the resulting use and choose Details → Open definition. Back returns to that exact use and its viewport after you apply or cancel pending edits.",
                                 "Inspect the scenario projection and Model checks. State exactly what each guard means, including units and assumptions where relevant.",
                             ],
                         ),
@@ -797,7 +805,7 @@ fn article(topic: Topic) -> Article {
             const {
                 Article {
                     summary: "The text editor and graphical forms edit the same model. Source projects preserve file organization and comments for human review, automation and version control.",
-                    keywords: "text textual source language syntax highlighting lint parser git aliases uuid identity rename diff merge restructuredtext spec canonical parity",
+                    keywords: "text textual source language syntax highlighting lint parser git aliases uuid identity rename diff merge restructuredtext spec canonical parity definition references lexical navigation F12 back",
                     sections: &[
                         walkthrough(
                             "Edit and review source",
@@ -810,6 +818,18 @@ fn article(topic: Topic) -> Article {
                                 "Save all writes the entry and its included UTF-8 files. Review the Git diff before committing, including relationships, traces and diagram changes that belong to the same engineering edit.",
                             ],
                         ),
+                        explain(
+                            "Follow definitions and lexical references",
+                            "Place the caret on a declaration alias or an @reference. Choose Definition (F12) to locate its declaration, or References (Shift+F12) to list lexical uses. Choose a row when a definition is ambiguous, draft or detached. Lexical uses exclude comments and strings; they do not establish typed relationships or resolve an ambiguous alias to one declaration. Back (Alt+Left) returns to the previous source location; if that draft changed, it restores the current cursor instead of an obsolete selection. These shortcuts work while the source editor has focus; the Text toolbar also offers the actions.",
+                        ),
+                        explain(
+                            "Read the navigation scope",
+                            "Queries inspect bounded snapshots of currently loaded drafts, without applying them or loading missing included files. The panel identifies partial scope, draft evidence, detached or unverified files, and alias or ID collisions. Counts show total, displayed and omitted rows. A missing result in partial scope does not establish that the whole project has no match. If sources change, stale rows are disabled; run Definition or References again. Row locations use one-based lines and UTF-8 byte columns. Navigation preserves your source drafts and the accepted model.",
+                        ),
+                        explain(
+                            "Find the record in diagrams",
+                            "Choose Show in diagrams from the Text toolbar on a unique verified alias in clean sources, or from the chosen model-tree record's context menu. Choose a diagram destination, then an exact representation. Results follow visible projection: ports, state rows, repeated caller tiles and their drawn sequence links remain distinct. Hidden tiles and nested links that are not drawn are excluded. A direct allocation can be represented by visible grouping; aggregate summaries do not invent allocation relations. A visual marker locates the port, row or grouped work while keeping the queried semantic record selected for model actions. Moving the camera preserves that marker. Finish pending edits first; navigation preserves accepted geometry, sources and history.",
+                        ),
                         explain(
                             "Names, aliases and IDs serve different purposes",
                             "The displayed name is engineering prose. A stable @alias is the readable source reference and need not change when the name changes. UUID identity distinguishes the persistent record. Preserve IDs when revising the same engineering object; changing identity is a deliberate operation that affects references.",

crates/oa-desktop/src/main.rs

@@ -7,6 +7,7 @@ mod context_menu;
 mod data_values;
 mod data_view;
 mod diagram;
+mod diagram_usage;
 mod document;
 mod explorer;
 mod explorer_view;

crates/oa-desktop/src/model_menu.rs

@@ -281,6 +281,11 @@ pub fn popup(app: &App) -> Option<Menu<Message>> {
         }
         entries.push(item("Properties", Message::EditProperties(id), true));
         entries.push(item("Open source", Message::SourceForSelection, true));
+        entries.push(item(
+            "Show in diagrams…",
+            app.diagram_usage_message(id),
+            true,
+        ));
         entries.push(item(
             "Connections & references",
             Message::InspectorTab(crate::navigation::InspectorTab::Connections),

crates/oa-desktop/src/navigation.rs

@@ -126,28 +126,8 @@ fn groups(p: &Project, selected: Id) -> Vec<Group> {
     ]
 }
 
-pub fn diagrams_containing(p: &Project, selected: Id) -> Vec<Id> {
-    let endpoints = p.relations.get(&selected).map(|r| [r.source(), r.target()]);
-    p.diagrams
-        .values()
-        .filter(|d| {
-            let placed = |id| {
-                let e = p.elements.get(&id);
-                let owner = e
-                    .filter(|e| e.kind() == Kind::Port)
-                    .and_then(|e| e.parent)
-                    .unwrap_or(id);
-                let kind = p.elements.get(&owner).map(|e| e.kind());
-                kind.is_none_or(|kind| d.projection.includes(kind))
-                    && d.nodes.values().any(|n| n.element == owner || n.id == id)
-            };
-            placed(selected) || endpoints.is_some_and(|ends| ends.into_iter().all(placed))
-        })
-        .map(|d| d.id)
-        .collect()
-}
-
-pub fn view(p: &Project, selected: Id) -> Element<'_, Message> {
+pub fn view(app: &crate::app::App, selected: Id) -> Element<'_, Message> {
+    let p = app.project();
     let mut content = column![
         text(short(p.named(selected), 50)).size(18),
         text("Follow ownership, usage and engineering relationships.")
@@ -203,25 +183,8 @@ pub fn view(p: &Project, selected: Id) -> Element<'_, Message> {
             content = content.push(container(entry).padding(8).style(style::subtle));
         }
     }
-    let diagrams = diagrams_containing(p, selected);
-    if !diagrams.is_empty() {
-        content = content.push(label("SHOWN IN DIAGRAMS"));
-        for id in diagrams {
-            content = content.push(
-                action(
-                    &short(p.named(id), 42),
-                    Message::RevealInDiagram(id, selected),
-                )
-                .width(Fill),
-            );
-        }
-    } else if p.elements.contains_key(&selected) {
-        content = content.push(
-            text("This element has no diagram placement yet.")
-                .size(12)
-                .color(style::MUTED),
-        );
-    }
+    content =
+        content.push(action("Show in diagrams…", app.diagram_usage_message(selected)).width(Fill));
     if count == 0 {
         content = content.push(text("No semantic connections yet. Use Actions or right-click an element to add relationships.").size(12).color(style::MUTED));
     }

crates/oa-desktop/src/semantic_review.rs

@@ -87,6 +87,9 @@ pub enum RowEvent {
     ValuePath(String, crate::data_values::FieldPathKey),
     ValueBrowse(String, Option<crate::data_values::FieldPathKey>, usize),
     ReferenceBrowse(String, String, usize),
+    ReferenceOpen(crate::forms::reference_chooser::adapter::Open),
+    ReferenceEvent(crate::forms::reference_chooser::Event),
+    ReferenceSet(crate::forms::reference_chooser::adapter::Set),
     OperationOmission(bool),
     OperationRationale(String),
     Tab(Tab),

crates/oa-desktop/src/semantic_review/batch.rs

@@ -296,6 +296,51 @@ impl State {
         }
         Ok(())
     }
+    pub(crate) fn reference_form(&self, project: &Project) -> Option<&Draft> {
+        let facet = self.active.selected.as_ref()?;
+        if self.frozen(project).is_err()
+            || self.active.tab != Tab::Facts
+            || self.active.decisions.get(facet) != Some(&SemanticDecision::Candidate)
+        {
+            return None;
+        }
+        self.active.candidate_draft(facet)
+    }
+    pub(crate) fn reference_draft(
+        &self,
+        project: &Project,
+        address: Option<RowAddress>,
+        facet: &FacetSelector,
+        path: &str,
+    ) -> Option<&Draft> {
+        if self.frozen(project).is_err()
+            || self.active_address != address
+            || self.active.tab != Tab::Facts
+        {
+            return None;
+        }
+        self.active.reference_draft(project, facet, path)
+    }
+    pub(crate) fn set_reference(
+        &mut self,
+        project: &Project,
+        address: Option<RowAddress>,
+        facet: &FacetSelector,
+        intent: crate::forms::reference_chooser::adapter::Set,
+    ) -> Result<(), String> {
+        self.reference_draft(project, address, facet, &intent.context.path)
+            .ok_or("The originating review row or property is no longer active.")?
+            .reference_value(project, &intent)?;
+        self.update(
+            project,
+            Event::Row {
+                address,
+                facet: Some(facet.clone()),
+                event: RowEvent::ReferenceSet(intent),
+            },
+        );
+        Ok(())
+    }
     pub fn update(&mut self, project: &Project, event: impl Into<Event>) {
         let event = event.into();
         #[cfg(test)]
@@ -303,6 +348,30 @@ impl State {
             Event::Editor(event) => self.address_event(event),
             other => other,
         };
+        match &event {
+            Event::Row {
+                event: RowEvent::ReferenceOpen(_) | RowEvent::ReferenceEvent(_),
+                ..
+            }
+            | Event::Editor(RowEvent::ReferenceOpen(_) | RowEvent::ReferenceEvent(_)) => return,
+            Event::Row {
+                address,
+                facet,
+                event: RowEvent::ReferenceSet(intent),
+            } => {
+                let valid = facet
+                    .as_ref()
+                    .and_then(|facet| {
+                        self.reference_draft(project, *address, facet, &intent.context.path)
+                    })
+                    .is_some_and(|draft| draft.reference_value(project, intent).is_ok());
+                if !valid {
+                    return;
+                }
+            }
+            Event::Editor(RowEvent::ReferenceSet(_)) => return,
+            _ => {}
+        }
         if let Err(error) = self.frozen(project) {
             // Withdrawing a pending reset is authored intent only. Retain it while
             // keeping the original accepted base and disabling every stale plan.
@@ -464,7 +533,8 @@ impl State {
                             );
                             let scoped_edit = matches!(
                                 event,
-                                RowEvent::Input(_, _)
+                                RowEvent::ReferenceSet(_)
+                                    | RowEvent::Input(_, _)
                                     | RowEvent::Text(_, _)
                                     | RowEvent::Shape(_, _)
                                     | RowEvent::Variant(_, _)
@@ -624,7 +694,7 @@ impl State {
             Fill,
             widget::{button, checkbox, column, pick_list, row, text},
         };
-        let message = |event| Message::Workflow(crate::workflow::Event::Semantic(event));
+        let message = |event| Message::Workflow(crate::workflow::Event::semantic(event));
         let mut available: Vec<_> = self
             .base
             .traces
@@ -747,13 +817,19 @@ impl State {
         if let Some(notice) = &self.notice {
             header = header.push(text(notice).size(11));
         }
-        self.active
+        let view = self
+            .active
             .view(&self.base, header.into(), self.can_apply())
             .map(move |message| match message {
-                Message::Workflow(crate::workflow::Event::Semantic(Event::Editor(event))) => {
-                    Message::Workflow(crate::workflow::Event::Semantic(self.address_event(event)))
+                Message::Workflow(crate::workflow::Event::Semantic(event)) => {
+                    let event = match *event {
+                        Event::Editor(event) => self.address_event(event),
+                        other => other,
+                    };
+                    Message::Workflow(crate::workflow::Event::semantic(event))
                 }
                 other => other,
-            })
+            });
+        crate::forms::reference_chooser::trigger::modal(view)
     }
 }

crates/oa-desktop/src/semantic_review/batch_tests.rs

@@ -522,10 +522,10 @@ fn batch_apply_is_one_exact_source_and_history_undo_redo_roundtrip() {
         &mut app,
         RowEvent::Input(path(f.direction, "minimum"), "120".into()),
     );
-    let _ = app.update(Message::Workflow(crate::workflow::Event::Semantic(
+    let _ = app.update(Message::Workflow(crate::workflow::Event::semantic(
         Event::ChooseTrace(view::choice(&f.project, f.traces[1])),
     )));
-    let _ = app.update(Message::Workflow(crate::workflow::Event::Semantic(
+    let _ = app.update(Message::Workflow(crate::workflow::Event::semantic(
         Event::OpenTrace,
     )));
     tests::decide(

crates/oa-desktop/src/semantic_review/row.rs

@@ -166,6 +166,14 @@ impl ReviewRow {
     pub fn update(&mut self, project: &Project, event: RowEvent) {
         let mut replan = true;
         let result = match event {
+            // Browser messages belong to the app overlay and must never replan.
+            RowEvent::ReferenceOpen(_) | RowEvent::ReferenceEvent(_) => return,
+            RowEvent::ReferenceSet(intent) => {
+                let path = intent.context.path.clone();
+                self.edit(project, &path, |draft| {
+                    draft.reference_set(project, &intent)
+                })
+            }
             RowEvent::OperationOmission(enabled) => {
                 self.operation_omission =
                     enabled.then(|| self.operation_omission.clone().unwrap_or_default());
@@ -518,6 +526,25 @@ impl ReviewRow {
         }
     }
 
+    pub(super) fn reference_draft(
+        &self,
+        project: &Project,
+        facet: &FacetSelector,
+        path: &str,
+    ) -> Option<&Draft> {
+        if self.selected.as_ref() != Some(facet)
+            || self.decisions.get(facet) != Some(&SemanticDecision::Candidate)
+            || matches!(path, "/id" | "/alias" | "/body" | "/layer")
+            || !self
+                .candidate_roots(project, facet)?
+                .iter()
+                .any(|root| path == root || path.starts_with(&format!("{root}/")))
+        {
+            return None;
+        }
+        self.candidate_draft(facet)
+    }
+
     fn edit(
         &mut self,
         project: &Project,
@@ -895,7 +922,9 @@ pub fn form_event(message: Message) -> Message {
         Message::FieldReferenceBrowse(path, query, page) => {
             RowEvent::ReferenceBrowse(path, query, page)
         }
+        Message::FieldReferenceOpen(request) => RowEvent::ReferenceOpen(request),
+        Message::FieldReferenceEvent(event) => RowEvent::ReferenceEvent(event),
         _ => RowEvent::Preview,
     };
-    Message::Workflow(crate::workflow::Event::Semantic(Event::Editor(event)))
+    Message::Workflow(crate::workflow::Event::semantic(Event::Editor(event)))
 }

crates/oa-desktop/src/semantic_review/tests.rs

@@ -3,7 +3,7 @@ use crate::{app::App, document::Document, workflow::Workflow};
 use serde_json::json;
 
 pub(super) fn send(app: &mut App, event: RowEvent) {
-    let _ = app.update(Message::Workflow(crate::workflow::Event::Semantic(
+    let _ = app.update(Message::Workflow(crate::workflow::Event::semantic(
         state(app).address_event(event),
     )));
 }

crates/oa-desktop/src/semantic_review/view.rs

@@ -13,7 +13,7 @@ use iced::{
 mod reserved_artifact_tests;
 
 fn event(event: RowEvent) -> Message {
-    Message::Workflow(crate::workflow::Event::Semantic(Event::Editor(event)))
+    Message::Workflow(crate::workflow::Event::semantic(Event::Editor(event)))
 }
 fn action<'a>(
     label: impl Into<String>,
@@ -867,7 +867,13 @@ impl ReviewRow {
         ) {
             detail = detail.push(text("Attached facts are separate from referenced definitions. Removing membership never implies deleting a semantic object.").size(11).color(style::MUTED));
         }
-        detail.into()
+        if self.decisions.get(&fact.selector) == Some(&SemanticDecision::Candidate)
+            && let Some(draft) = self.candidate_draft(&fact.selector)
+        {
+            crate::forms::reference_chooser::trigger::scope(detail, draft.reference_session())
+        } else {
+            detail.into()
+        }
     }
 
     fn members_view<'a>(&'a self, project: &'a Project) -> Element<'a, Message> {

crates/oa-desktop/src/source_navigation.rs

@@ -1,4 +1,9 @@
 //! Literal source search and line navigation, independent of accepted model state.
+mod controller;
+pub mod interaction;
+pub mod query;
+pub mod symbols;
+pub use controller::*;
 use iced::widget::text_editor::{Cursor, Position};
 
 #[derive(Debug, Clone)]

crates/oa-desktop/src/source_navigation/controller.rs

@@ -0,0 +1,126 @@
+//! Ephemeral editor navigation; no model commands or filesystem operations.
+use super::query;
+use iced::widget::text_editor::{Cursor, Position};
+use oa_core::Id;
+use std::sync::Arc;
+use std::sync::atomic::AtomicU64;
+
+#[derive(Debug, Clone)]
+pub enum SymbolEvent {
+    DiagramUsages,
+    Query(query::Action),
+    Back,
+    Close,
+    Choose {
+        stamp: query::QueryStamp,
+        reference: bool,
+        index: usize,
+    },
+}
+
+/// Identity of the mounted source view that emitted an action. Message queues
+/// may outlive that view; request-time stamping alone cannot detect replay.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SymbolContext {
+    pub session: Id,
+    pub path: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct HistoryEntry {
+    pub session: Id,
+    pub path: String,
+    pub generation: u64,
+    pub cursor: Cursor,
+}
+
+#[derive(Debug, Clone)]
+pub struct Request {
+    pub job: Id,
+    pub interaction: Id,
+    pub raw_interaction: u64,
+    pub stamp: query::QueryStamp,
+    pub path: String,
+    pub offset: usize,
+    pub cursor: Cursor,
+    pub action: query::Action,
+}
+
+#[derive(Debug, Clone)]
+pub struct Completion {
+    pub request: Request,
+    pub result: Result<(Arc<query::Snapshot>, Arc<query::Results>), String>,
+}
+
+pub struct Reveal {
+    pub ticket: Id,
+    pub interaction: Id,
+    pub raw_interaction: u64,
+    pub snapshot: query::SnapshotKey,
+    pub path: String,
+}
+
+pub struct SymbolState {
+    pub open: bool,
+    pub interaction: Id,
+    pub raw_interaction: Arc<AtomicU64>,
+    pub serial: u64,
+    pub in_flight: Option<Id>,
+    pub request: Option<Request>,
+    pub cache: Option<Arc<query::Snapshot>>,
+    pub results: Option<Arc<query::Results>>,
+    pub notice: Option<String>,
+    pub back: Vec<HistoryEntry>,
+    pub reveal: Option<Reveal>,
+}
+
+impl Default for SymbolState {
+    fn default() -> Self {
+        Self {
+            open: false,
+            interaction: Id::new_v4(),
+            raw_interaction: Arc::new(AtomicU64::new(0)),
+            serial: 0,
+            in_flight: None,
+            request: None,
+            cache: None,
+            results: None,
+            notice: None,
+            back: Vec::new(),
+            reveal: None,
+        }
+    }
+}
+
+/// Iced uses zero-based UTF-8 byte columns. Reject stale or split-codepoint
+/// coordinates; do not normalize CRLF or silently clamp query destinations.
+pub fn byte_offset(text: &str, position: Position) -> Option<usize> {
+    let start = if position.line == 0 {
+        0
+    } else {
+        text.match_indices('\n').nth(position.line - 1)?.0 + 1
+    };
+    let end = text[start..]
+        .find('\n')
+        .map_or(text.len(), |end| start + end);
+    let offset = start.checked_add(position.column)?;
+    (offset <= end && text.is_char_boundary(offset)).then_some(offset)
+}
+
+pub fn cursor_offset(text: &str, cursor: Cursor) -> Option<usize> {
+    let position = cursor.selection.map_or(cursor.position, |selection| {
+        if (selection.line, selection.column) < (cursor.position.line, cursor.position.column) {
+            selection
+        } else {
+            cursor.position
+        }
+    });
+    byte_offset(text, position)
+}
+
+pub fn exact_cursor(text: &str, cursor: Cursor) -> bool {
+    byte_offset(text, cursor.position).is_some()
+        && cursor
+            .selection
+            .is_none_or(|position| byte_offset(text, position).is_some())
+}

crates/oa-desktop/src/source_navigation/interaction.rs

@@ -0,0 +1,284 @@
+//! Raw input invalidation and focus checks at widget-operation execution time.
+use iced::advanced::{Clipboard, Layout, Shell, Widget, layout, overlay, renderer, widget};
+use iced::{Element, Event, Length, Rectangle, Size, Task, Vector, keyboard, mouse, touch};
+use std::sync::{
+    Arc,
+    atomic::{AtomicU64, Ordering},
+};
+
+/// Exhaustion fails closed: a saturated clock can never authorize navigation.
+/// Replace the clock with a new workspace/controller, rather than wrapping it.
+pub fn is_current(clock: &AtomicU64, expected: u64) -> bool {
+    expected != u64::MAX && clock.load(Ordering::Acquire) == expected
+}
+
+fn invalidate(clock: &AtomicU64, event: &Event) {
+    if matches!(
+        event,
+        Event::Keyboard(keyboard::Event::KeyPressed { .. })
+            | Event::Mouse(mouse::Event::ButtonPressed(_) | mouse::Event::WheelScrolled { .. })
+            | Event::Touch(touch::Event::FingerPressed { .. })
+            | Event::Window(iced::window::Event::Unfocused)
+    ) {
+        let _ = clock.fetch_update(Ordering::AcqRel, Ordering::Acquire, |value| {
+            Some(value.saturating_add(1))
+        });
+    }
+}
+
+/// Transparent, including overlays: invalidate before the child can capture input.
+pub fn observe<'a, Message: 'a, Theme: 'a, Renderer: renderer::Renderer + 'a>(
+    content: Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+) -> Element<'a, Message, Theme, Renderer> {
+    Element::new(Observed { content, clock })
+}
+
+struct Observed<'a, Message, Theme, Renderer> {
+    content: Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+}
+
+impl<Message, Theme, Renderer: renderer::Renderer> Widget<Message, Theme, Renderer>
+    for Observed<'_, Message, Theme, Renderer>
+{
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn size_hint(&self) -> Size<Length> {
+        self.content.as_widget().size_hint()
+    }
+    fn tag(&self) -> widget::tree::Tag {
+        self.content.as_widget().tag()
+    }
+    fn state(&self) -> widget::tree::State {
+        self.content.as_widget().state()
+    }
+    fn children(&self) -> Vec<widget::Tree> {
+        self.content.as_widget().children()
+    }
+    fn diff(&self, tree: &mut widget::Tree) {
+        self.content.as_widget().diff(tree);
+    }
+    fn layout(
+        &mut self,
+        tree: &mut widget::Tree,
+        renderer: &Renderer,
+        limits: &layout::Limits,
+    ) -> layout::Node {
+        self.content.as_widget_mut().layout(tree, renderer, limits)
+    }
+    fn draw(
+        &self,
+        tree: &widget::Tree,
+        renderer: &mut Renderer,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content
+            .as_widget()
+            .draw(tree, renderer, theme, style, layout, cursor, viewport);
+    }
+    fn operate(
+        &mut self,
+        tree: &mut widget::Tree,
+        layout: Layout<'_>,
+        renderer: &Renderer,
+        operation: &mut dyn widget::Operation,
+    ) {
+        self.content
+            .as_widget_mut()
+            .operate(tree, layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        tree: &mut widget::Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        invalidate(&self.clock, event);
+        self.content.as_widget_mut().update(
+            tree, event, layout, cursor, renderer, clipboard, shell, viewport,
+        );
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &widget::Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &Renderer,
+    ) -> mouse::Interaction {
+        self.content
+            .as_widget()
+            .mouse_interaction(tree, layout, cursor, viewport, renderer)
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        tree: &'a mut widget::Tree,
+        layout: Layout<'a>,
+        renderer: &Renderer,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
+        let clock = self.clock.clone();
+        self.content
+            .as_widget_mut()
+            .overlay(tree, layout, renderer, viewport, translation)
+            .map(|content| overlay::Element::new(Box::new(ObservedOverlay { content, clock })))
+    }
+}
+
+struct ObservedOverlay<'a, Message, Theme, Renderer> {
+    content: overlay::Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+}
+impl<Message, Theme, Renderer: renderer::Renderer> overlay::Overlay<Message, Theme, Renderer>
+    for ObservedOverlay<'_, Message, Theme, Renderer>
+{
+    fn layout(&mut self, renderer: &Renderer, bounds: Size) -> layout::Node {
+        self.content.as_overlay_mut().layout(renderer, bounds)
+    }
+    fn draw(
+        &self,
+        renderer: &mut Renderer,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+    ) {
+        self.content
+            .as_overlay()
+            .draw(renderer, theme, style, layout, cursor);
+    }
+    fn operate(
+        &mut self,
+        layout: Layout<'_>,
+        renderer: &Renderer,
+        operation: &mut dyn widget::Operation,
+    ) {
+        self.content
+            .as_overlay_mut()
+            .operate(layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+    ) {
+        invalidate(&self.clock, event);
+        self.content
+            .as_overlay_mut()
+            .update(event, layout, cursor, renderer, clipboard, shell);
+    }
+    fn mouse_interaction(
+        &self,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+    ) -> mouse::Interaction {
+        self.content
+            .as_overlay()
+            .mouse_interaction(layout, cursor, renderer)
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        layout: Layout<'a>,
+        renderer: &Renderer,
+    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
+        let clock = self.clock.clone();
+        self.content
+            .as_overlay_mut()
+            .overlay(layout, renderer)
+            .map(|content| overlay::Element::new(Box::new(ObservedOverlay { content, clock })))
+    }
+    fn index(&self) -> f32 {
+        self.content.as_overlay().index()
+    }
+}
+
+/// Inspect all focus owners, then focus only the mounted target. Iced executes
+/// Operation::Chain synchronously, without an intervening input event. Both
+/// traversals recheck the raw clock; no result message authorizes later focus.
+pub fn guarded_focus<Message: Send + 'static>(
+    target: widget::Id,
+    clock: Arc<AtomicU64>,
+    expected: u64,
+) -> Task<Message> {
+    widget::operate(GuardedFocus::new(target, clock, expected))
+}
+
+struct GuardedFocus {
+    target: widget::Id,
+    clock: Arc<AtomicU64>,
+    expected: u64,
+    target_count: usize,
+    foreign_focus: bool,
+    apply: bool,
+}
+impl GuardedFocus {
+    fn new(target: widget::Id, clock: Arc<AtomicU64>, expected: u64) -> Self {
+        Self {
+            target,
+            clock,
+            expected,
+            target_count: 0,
+            foreign_focus: false,
+            apply: false,
+        }
+    }
+}
+impl<Message: 'static> widget::Operation<Message> for GuardedFocus {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation<Message>)) {
+        if is_current(&self.clock, self.expected) {
+            visit(self);
+        }
+    }
+    fn focusable(
+        &mut self,
+        id: Option<&widget::Id>,
+        _: Rectangle,
+        state: &mut dyn widget::operation::Focusable,
+    ) {
+        if !is_current(&self.clock, self.expected) {
+            return;
+        }
+        if id == Some(&self.target) {
+            self.target_count += 1;
+            if self.apply {
+                state.focus();
+            }
+        } else if state.is_focused() {
+            self.foreign_focus = true;
+        }
+    }
+    fn finish(&self) -> widget::operation::Outcome<Message> {
+        if !self.apply
+            && self.target_count == 1
+            && !self.foreign_focus
+            && is_current(&self.clock, self.expected)
+        {
+            widget::operation::Outcome::Chain(Box::new(Self {
+                apply: true,
+                ..Self::new(self.target.clone(), self.clock.clone(), self.expected)
+            }))
+        } else {
+            widget::operation::Outcome::None
+        }
+    }
+}
+
+#[cfg(all(test, debug_assertions))]
+mod tests;

crates/oa-desktop/src/source_navigation/interaction/tests.rs

@@ -0,0 +1,190 @@
+use super::*;
+use iced::advanced::widget::operation::{Focusable, Outcome};
+use iced::widget::{column, text_input};
+use iced::{Point, Theme};
+
+#[derive(Default)]
+struct FocusMap(Vec<(Option<widget::Id>, Rectangle, bool)>);
+impl widget::Operation for FocusMap {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation)) {
+        visit(self);
+    }
+    fn focusable(&mut self, id: Option<&widget::Id>, bounds: Rectangle, state: &mut dyn Focusable) {
+        self.0.push((id.cloned(), bounds, state.is_focused()));
+    }
+}
+
+struct Mounted {
+    element: Element<'static, (), Theme, ()>,
+    tree: widget::Tree,
+    node: layout::Node,
+}
+impl Mounted {
+    fn new(clock: Arc<AtomicU64>) -> Self {
+        let content = column![
+            text_input("Editor", "source")
+                .id("editor")
+                .on_input(|_| ())
+                .padding(12),
+            text_input("Find", "")
+                .id("find")
+                .on_input(|_| ())
+                .padding(12),
+        ]
+        .spacing(10)
+        .into();
+        let mut element = observe(content, clock);
+        let mut tree = widget::Tree::new(element.as_widget());
+        let node = element.as_widget_mut().layout(
+            &mut tree,
+            &(),
+            &layout::Limits::new(Size::ZERO, Size::new(400., 200.)),
+        );
+        Self {
+            element,
+            tree,
+            node,
+        }
+    }
+    fn pass(&mut self, operation: &mut dyn widget::Operation) {
+        self.element.as_widget_mut().operate(
+            &mut self.tree,
+            Layout::new(&self.node),
+            &(),
+            operation,
+        );
+    }
+    fn run(&mut self, operation: impl widget::Operation + 'static) {
+        let mut next: Box<dyn widget::Operation> = Box::new(operation);
+        loop {
+            self.pass(next.as_mut());
+            match next.finish() {
+                Outcome::Chain(chained) => next = chained,
+                Outcome::None => break,
+                Outcome::Some(()) => panic!("focus must not publish an application message"),
+            }
+        }
+    }
+    fn focus(&mut self) -> FocusMap {
+        let mut focus = FocusMap::default();
+        self.pass(&mut focus);
+        focus
+    }
+    fn click(&mut self, id: &str) {
+        let bounds = self
+            .focus()
+            .0
+            .into_iter()
+            .find(|(found, _, _)| found.as_ref() == Some(&widget::Id::from(id.to_owned())))
+            .unwrap()
+            .1;
+        let mut messages = Vec::new();
+        let mut shell = Shell::new(&mut messages);
+        self.element.as_widget_mut().update(
+            &mut self.tree,
+            &Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+            Layout::new(&self.node),
+            mouse::Cursor::Available(bounds.center()),
+            &(),
+            &mut iced::advanced::clipboard::Null,
+            &mut shell,
+            &Rectangle::with_size(Size::new(400., 200.)),
+        );
+        assert!(shell.is_event_captured());
+        assert!(
+            messages.is_empty(),
+            "focus-only click must not rely on App messages"
+        );
+    }
+    fn focused(&mut self, id: &str) -> bool {
+        self.focus()
+            .0
+            .into_iter()
+            .find(|(found, _, _)| found.as_ref() == Some(&widget::Id::from(id.to_owned())))
+            .unwrap()
+            .2
+    }
+}
+
+#[test]
+fn captured_find_click_invalidates_without_app_message_and_preserves_focus() {
+    let clock = Arc::new(AtomicU64::new(0));
+    let mut ui = Mounted::new(clock.clone());
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 0));
+    assert!(ui.focused("editor"));
+    ui.click("find");
+    assert!(!is_current(&clock, 0));
+    assert!(ui.focused("find"));
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 0));
+    assert!(ui.focused("find"));
+    // Even a matching clock cannot authorize stealing another widget's focus.
+    ui.run(GuardedFocus::new(
+        "editor".into(),
+        clock.clone(),
+        clock.load(Ordering::Acquire),
+    ));
+    assert!(ui.focused("find"));
+    assert!(!ui.focused("editor"));
+}
+
+#[test]
+fn focus_rechecks_clock_between_inspection_and_application_and_missing_target_is_inert() {
+    let clock = Arc::new(AtomicU64::new(0));
+    let mut ui = Mounted::new(clock.clone());
+    let mut operation = GuardedFocus::new("editor".into(), clock.clone(), 0);
+    ui.pass(&mut operation);
+    let Outcome::Chain(mut apply) = <GuardedFocus as widget::Operation<()>>::finish(&operation)
+    else {
+        panic!("mounted, unopposed target must be eligible");
+    };
+    clock.store(1, Ordering::Release);
+    ui.pass(apply.as_mut());
+    assert!(!ui.focused("editor"));
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 1));
+    assert!(ui.focused("editor"));
+    ui.run(GuardedFocus::new("removed-editor".into(), clock, 1));
+    assert!(ui.focused("editor"));
+}
+
+#[test]
+fn raw_navigation_inputs_advance_but_passive_geometry_does_not_and_exhaustion_refuses() {
+    let clock = AtomicU64::new(0);
+    let events = [
+        Event::Keyboard(keyboard::Event::KeyPressed {
+            key: keyboard::Key::Named(keyboard::key::Named::ArrowLeft),
+            modified_key: keyboard::Key::Named(keyboard::key::Named::ArrowLeft),
+            physical_key: keyboard::key::Physical::Code(keyboard::key::Code::ArrowLeft),
+            location: keyboard::Location::Standard,
+            modifiers: keyboard::Modifiers::empty(),
+            text: None,
+            repeat: false,
+        }),
+        Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+        Event::Mouse(mouse::Event::WheelScrolled {
+            delta: mouse::ScrollDelta::Lines { x: 0., y: 1. },
+        }),
+        Event::Touch(touch::Event::FingerPressed {
+            id: touch::Finger(1),
+            position: Point::ORIGIN,
+        }),
+        Event::Window(iced::window::Event::Unfocused),
+    ];
+    for (index, event) in events.iter().enumerate() {
+        invalidate(&clock, event);
+        assert_eq!(clock.load(Ordering::Acquire), index as u64 + 1);
+    }
+    invalidate(
+        &clock,
+        &Event::Mouse(mouse::Event::CursorMoved {
+            position: Point::ORIGIN,
+        }),
+    );
+    invalidate(&clock, &Event::Window(iced::window::Event::Focused));
+    assert!(is_current(&clock, 5));
+    clock.store(u64::MAX - 1, Ordering::Release);
+    invalidate(&clock, &events[0]);
+    assert!(!is_current(&clock, u64::MAX));
+    invalidate(&clock, &events[0]);
+    assert_eq!(clock.load(Ordering::Acquire), u64::MAX);
+    assert!(!is_current(&clock, 0));
+}

crates/oa-desktop/src/source_navigation/query_tests.rs

@@ -0,0 +1,989 @@
+use super::*;
+
+const PROJECT: &str = "00000000-0000-0000-0000-000000000001";
+const PUMP: &str = "00000000-0000-0000-0000-000000000002";
+const LINK: &str = "00000000-0000-0000-0000-000000000003";
+
+#[derive(Clone)]
+struct Fixture {
+    entry: String,
+    files: Vec<(String, String)>,
+}
+
+impl Fixture {
+    fn standard() -> Self {
+        Self {
+            entry: "project.arcadia".into(),
+            files: vec![
+                (
+                    "project.arcadia".into(),
+                    format!(
+                        "arcadia 7;\r\nproject model \"Harbour\" id \"{PROJECT}\" {{\r\n include \"模块/活動.arcadia\";\r\n include \"links.arcadia\";\r\n}}\r\n"
+                    ),
+                ),
+                (
+                    "模块/活動.arcadia".into(),
+                    format!(
+                        "// 原文 remains exact\r\noa_activity pump \"泵 🚀\" id \"{PUMP}\" {{}}\r\n"
+                    ),
+                ),
+                (
+                    "links.arcadia".into(),
+                    format!(
+                        "// 航海\r\ninteraction connection \"流れ\" id \"{LINK}\" {{\r\n source @ // separator @pump\r\n   pump;\r\n description \"船 @pump\"; target @pump;\r\n}}\r\n"
+                    ),
+                ),
+            ],
+        }
+    }
+
+    fn borrowed(&self) -> Vec<DraftFile<'_>> {
+        self.files
+            .iter()
+            .map(|(path, text)| DraftFile { path, text })
+            .collect()
+    }
+
+    fn text(&self, path: &str) -> &str {
+        &self
+            .files
+            .iter()
+            .find(|(candidate, _)| candidate == path)
+            .unwrap()
+            .1
+    }
+
+    fn text_mut(&mut self, path: &str) -> &mut String {
+        &mut self
+            .files
+            .iter_mut()
+            .find(|(candidate, _)| candidate == path)
+            .unwrap()
+            .1
+    }
+
+    fn snapshot(&self, validated: Option<&Self>, applied: bool, limits: Limits) -> Snapshot {
+        let current = self.borrowed();
+        let old = validated.map(Self::borrowed);
+        capture(
+            Input {
+                key: key(1),
+                entry: &self.entry,
+                files: &current,
+                applied,
+                validation: old.as_ref().map(|files| ValidatedSources {
+                    entry: &validated.unwrap().entry,
+                    files,
+                }),
+            },
+            limits,
+        )
+        .unwrap()
+    }
+}
+
+fn key(revision: u64) -> SnapshotKey {
+    SnapshotKey {
+        workspace: Id::from_u128(100),
+        revision,
+    }
+}
+
+fn query(snapshot: &Snapshot, path: &str, byte_offset: usize, action: Action) -> Results {
+    snapshot
+        .query(Query {
+            stamp: QueryStamp {
+                snapshot: snapshot.key(),
+                serial: 37,
+            },
+            path,
+            byte_offset,
+            action,
+        })
+        .unwrap()
+}
+
+fn reference_offset(fixture: &Fixture) -> usize {
+    fixture.text("links.arcadia").find("source @").unwrap() + "source ".len()
+}
+
+#[test]
+fn exact_multifile_unicode_crlf_definition_and_repeated_lexical_references() {
+    let fixture = Fixture::standard();
+    let original = fixture.files.clone();
+    let snapshot = fixture.snapshot(Some(&fixture), true, Limits::default());
+    assert!(snapshot.scope().closure_complete && snapshot.scope().validated);
+    assert_eq!(
+        (
+            snapshot.scope().included_files,
+            snapshot.scope().detached_files
+        ),
+        (3, 0)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Direct);
+    assert_eq!(
+        (result.total_definitions, result.omitted_definitions),
+        (1, 0)
+    );
+    let definition = &result.definitions[0];
+    assert_eq!(definition.path, "模块/活動.arcadia");
+    assert_eq!(definition.declaration.kind, "oa_activity");
+    assert_eq!(definition.declaration.name.as_deref(), Some("泵 🚀"));
+    assert_eq!(
+        definition.declaration.authored_id,
+        Some(Id::parse_str(PUMP).unwrap())
+    );
+    assert_eq!(
+        definition.position,
+        Position {
+            line: 1,
+            byte_column: "oa_activity ".len()
+        }
+    );
+    assert_eq!(
+        &fixture.text(&definition.path)[definition.span.start..definition.span.end],
+        "pump"
+    );
+    let uses = query(
+        &snapshot,
+        &definition.path,
+        definition.span.start,
+        Action::References,
+    );
+    assert_eq!(uses.disposition, Disposition::LexicalReferences);
+    assert_eq!((uses.total_references, uses.omitted_references), (2, 0));
+    assert_eq!(
+        uses.references[0].position,
+        Position {
+            line: 3,
+            byte_column: 3
+        }
+    );
+    let target_prefix = " description \"船 @pump\"; target @";
+    assert_ne!(target_prefix.len(), target_prefix.chars().count());
+    assert_eq!(
+        uses.references[1].position,
+        Position {
+            line: 4,
+            byte_column: target_prefix.len()
+        }
+    );
+    for row in &uses.references {
+        let text = fixture.text(&row.path);
+        assert_eq!(&text[row.span.start..row.span.end], "pump");
+        assert_eq!(&text[row.marker.start..row.marker.end], "@");
+        let context = row.context.as_ref().unwrap();
+        assert_eq!(context.alias, "connection");
+        assert_eq!(context.kind, "interaction");
+        assert_eq!(context.name.as_deref(), Some("流れ"));
+        assert_eq!(row.evidence, Evidence::Validated);
+    }
+    assert_eq!(
+        uses.stamp,
+        QueryStamp {
+            snapshot: key(1),
+            serial: 37
+        }
+    );
+    assert_eq!(
+        fixture.files, original,
+        "no stabilization, newline rewrite or accepted adoption"
+    );
+    for (index, (path, text)) in original.iter().enumerate() {
+        let owned = snapshot.file(index).unwrap();
+        assert_eq!((owned.path, owned.text), (path.as_str(), text.as_str()));
+    }
+}
+
+#[test]
+fn comments_strings_and_comment_gap_are_not_navigation_hits() {
+    let fixture = Fixture::standard();
+    let snapshot = fixture.snapshot(None, true, Limits::default());
+    let text = fixture.text("links.arcadia");
+    for offset in [
+        text.find("separator @pump").unwrap() + "separator ".len(),
+        text.find("船 @pump").unwrap() + "船 ".len(),
+        text.find("@ //").unwrap() + 1,
+    ] {
+        let result = query(&snapshot, "links.arcadia", offset, Action::Definition);
+        assert_eq!(result.disposition, Disposition::NoSymbol);
+        assert_eq!(result.total_definitions, 0);
+    }
+    assert_eq!(
+        query(
+            &snapshot,
+            "links.arcadia",
+            text.find("   pump;").unwrap() + 3,
+            Action::Definition
+        )
+        .total_definitions,
+        1
+    );
+    let inside_utf8 = text.find('船').unwrap() + 1;
+    assert_eq!(
+        snapshot.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(1),
+                serial: 1
+            },
+            path: "links.arcadia",
+            byte_offset: inside_utf8,
+            action: Action::Definition
+        }),
+        Err(QueryError::Query(symbols::QueryError::InvalidBytePosition))
+    );
+}
+
+#[test]
+fn dirty_but_parseable_text_has_current_names_and_no_validated_fallback() {
+    let original = Fixture::standard();
+    let mut dirty = original.clone();
+    *dirty.text_mut("模块/活動.arcadia") = dirty
+        .text("模块/活動.arcadia")
+        .replace("泵 🚀", "Edited 泵\\nwith detail");
+    let snapshot = dirty.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().closure_complete);
+    assert!(!snapshot.scope().validated);
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&dirty),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(
+        result.definitions[0].declaration.name.as_deref(),
+        Some("Edited 泵\nwith detail")
+    );
+    assert_eq!(result.definitions[0].evidence, Evidence::Draft);
+    assert_eq!(
+        snapshot.file(1).unwrap().text,
+        dirty.text("模块/活動.arcadia")
+    );
+    assert_ne!(
+        snapshot.file(1).unwrap().text,
+        original.text("模块/活動.arcadia")
+    );
+}
+
+#[test]
+fn invalid_include_syntax_never_borrows_the_old_reachable_file_set() {
+    let original = Fixture::standard();
+    let mut invalid = original.clone();
+    *invalid.text_mut("project.arcadia") = invalid
+        .text("project.arcadia")
+        .replace("include \"links.arcadia\";", "include \"links.arcadia\"");
+    let snapshot = invalid.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().partial());
+    assert!(!snapshot.scope().validated);
+    assert!(
+        snapshot
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::InvalidIncludes)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&invalid),
+        Action::Definition,
+    );
+    assert_eq!(result.total_definitions, 1);
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(result.definitions[0].membership, Membership::Unverified);
+}
+
+#[test]
+fn missing_include_partial_scope_does_not_resurrect_witness_text() {
+    let original = Fixture::standard();
+    let mut missing = original.clone();
+    missing
+        .files
+        .retain(|(path, _)| path != "模块/活動.arcadia");
+    let snapshot = missing.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().partial());
+    assert!(
+        snapshot
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::MissingInclude)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&missing),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::NoDefinition);
+    assert!(result.definitions.is_empty());
+    assert!(
+        result.scope.partial(),
+        "zero means no loaded definition, not no project definition"
+    );
+    assert!(snapshot.file(2).is_none());
+}
+
+#[test]
+fn detached_alias_and_identity_collisions_never_auto_select() {
+    let accepted = Fixture::standard();
+    for (alias, id) in [
+        ("pump", "00000000-0000-0000-0000-000000000099"),
+        ("other", PUMP),
+    ] {
+        let mut loaded = accepted.clone();
+        loaded.files.push((
+            "detached.arcadia".into(),
+            format!("oa_activity {alias} \"Detached\" id \"{id}\" {{}}"),
+        ));
+        let snapshot = loaded.snapshot(Some(&accepted), true, Limits::default());
+        assert!(snapshot.scope().validated);
+        assert_eq!(snapshot.scope().detached_files, 1);
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&loaded),
+            Action::Definition,
+        );
+        assert_eq!(result.disposition, Disposition::Choices);
+        if alias == "pump" {
+            assert_eq!(result.total_definitions, 2);
+            assert!(result.definitions.iter().any(
+                |row| row.membership == Membership::Detached && row.evidence == Evidence::Draft
+            ));
+        } else {
+            assert_eq!(result.total_definitions, 1);
+            assert_eq!(
+                result.definitions[0].declaration.identity,
+                Identity::Collision { count: 2 }
+            );
+        }
+    }
+}
+
+#[test]
+fn sole_detached_candidate_and_unapplied_equal_bytes_require_choice() {
+    let accepted = Fixture::standard();
+    let mut detached = accepted.clone();
+    *detached.text_mut("project.arcadia") = detached
+        .text("project.arcadia")
+        .replace(" include \"模块/活動.arcadia\";\r\n", "");
+    let snapshot = detached.snapshot(None, true, Limits::default());
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&detached),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(result.definitions[0].membership, Membership::Detached);
+    let unapplied = accepted.snapshot(Some(&accepted), false, Limits::default());
+    assert!(unapplied.scope().closure_complete && unapplied.scope().partial());
+    assert!(!unapplied.scope().validated);
+    assert_eq!(
+        query(
+            &unapplied,
+            "links.arcadia",
+            reference_offset(&accepted),
+            Action::Definition
+        )
+        .disposition,
+        Disposition::Choices
+    );
+}
+
+#[test]
+fn include_cycle_depth_and_aggregate_edges_are_explicit_partial_outcomes() {
+    let mut fixture = Fixture::standard();
+    fixture
+        .text_mut("模块/活動.arcadia")
+        .push_str("include \"../project.arcadia\";\r\n");
+    let cycle = fixture.snapshot(None, true, Limits::default());
+    assert!(
+        cycle
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::IncludeCycle)
+    );
+    let fixture = Fixture::standard();
+    for (depth, edges, expected) in [
+        (0, 1024, ScopeIssueKind::IncludeDepth),
+        (32, 1, ScopeIssueKind::IncludeBudget),
+    ] {
+        let snapshot = fixture.snapshot(
+            None,
+            true,
+            Limits {
+                include_depth: depth,
+                include_edges: edges,
+                ..Limits::default()
+            },
+        );
+        assert!(snapshot.scope().partial());
+        assert!(
+            snapshot
+                .scope()
+                .issues
+                .iter()
+                .any(|issue| issue.kind == expected)
+        );
+        assert_eq!(
+            query(
+                &snapshot,
+                "links.arcadia",
+                reference_offset(&fixture),
+                Action::Definition
+            )
+            .disposition,
+            Disposition::Choices
+        );
+    }
+}
+
+#[test]
+fn exact_snapshot_readback_rejects_same_key_byte_membership_and_evidence_changes() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let validation = Some(ValidatedSources {
+        entry: &fixture.entry,
+        files: &files,
+    });
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation,
+    };
+    let snapshot = capture(input, Limits::default()).unwrap();
+    assert!(snapshot.matches(input));
+    assert!(!snapshot.matches(Input {
+        key: key(2),
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        validation: None,
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        applied: false,
+        ..input
+    }));
+    let mut reversed = files.clone();
+    reversed.reverse();
+    assert!(snapshot.matches(Input {
+        files: &reversed,
+        ..input
+    }));
+    let mut changed = fixture.clone();
+    changed.text_mut("links.arcadia").push(' ');
+    let altered = changed.borrowed();
+    assert!(!snapshot.matches(Input {
+        files: &altered,
+        ..input
+    }));
+    let missing = &files[..files.len() - 1];
+    assert!(!snapshot.matches(Input {
+        files: missing,
+        ..input
+    }));
+    let duplicated = [files[0], files[0], files[2]];
+    assert!(!snapshot.matches(Input {
+        files: &duplicated,
+        ..input
+    }));
+    assert_eq!(
+        snapshot.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(2),
+                serial: 37
+            },
+            path: "links.arcadia",
+            byte_offset: 0,
+            action: Action::Definition
+        }),
+        Err(QueryError::Query(symbols::QueryError::StaleSnapshot))
+    );
+}
+
+#[test]
+fn omitted_rows_are_counted_before_result_allocation_and_never_confer_uniqueness() {
+    let fixture = Fixture::standard();
+    let snapshot = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_rows: 2,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::References,
+    );
+    assert_eq!((result.total_definitions, result.total_references), (1, 2));
+    assert_eq!(
+        (
+            result.definitions.len(),
+            result.references.len(),
+            result.omitted_references
+        ),
+        (1, 1, 1)
+    );
+    let zero = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_rows: 0,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &zero,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(
+        (
+            result.definitions.len(),
+            result.total_definitions,
+            result.omitted_definitions
+        ),
+        (0, 1, 1)
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    let envelope = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_bytes: 0,
+            ..Limits::default()
+        },
+    );
+    assert_eq!(
+        envelope.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(1),
+                serial: 1
+            },
+            path: "links.arcadia",
+            byte_offset: reference_offset(&fixture),
+            action: Action::Definition
+        }),
+        Err(QueryError::ResultEnvelopeLimit)
+    );
+}
+
+#[test]
+fn large_display_name_cannot_escape_the_owned_row_string_budget() {
+    let mut fixture = Fixture::standard();
+    *fixture.text_mut("模块/活動.arcadia") = fixture
+        .text("模块/活動.arcadia")
+        .replace("泵 🚀", &"長".repeat(8192));
+    let original = fixture.files.clone();
+    let snapshot = fixture.snapshot(
+        None,
+        true,
+        Limits {
+            result_bytes: 64,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(
+        (result.total_definitions, result.omitted_definitions),
+        (1, 1)
+    );
+    assert!(result.definitions.is_empty());
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(fixture.files, original);
+}
+
+#[test]
+fn validation_witness_must_match_entry_and_complete_included_file_set() {
+    let fixture = Fixture::standard();
+    for mutation in 0..3 {
+        let mut witness = fixture.clone();
+        match mutation {
+            0 => witness.entry = "other.arcadia".into(),
+            1 => {
+                witness.files.pop();
+            }
+            _ => witness.files.push(("unused.arcadia".into(), String::new())),
+        }
+        let snapshot = fixture.snapshot(Some(&witness), true, Limits::default());
+        assert!(snapshot.scope().closure_complete);
+        assert!(!snapshot.scope().validated);
+        assert_eq!(
+            query(
+                &snapshot,
+                "links.arcadia",
+                reference_offset(&fixture),
+                Action::Definition
+            )
+            .disposition,
+            Disposition::Choices
+        );
+    }
+}
+
+#[test]
+fn raw_aggregate_limits_refuse_before_outline_or_copied_snapshot() {
+    // Token budget zero and malformed paths/text would fail later. Raw byte/path
+    // limits must win, including a large second file; no partial Snapshot exists.
+    let large = "not a model \0".repeat(16_384);
+    let files = [
+        DraftFile {
+            path: "../bad.arcadia",
+            text: "?",
+        },
+        DraftFile {
+            path: "large.arcadia",
+            text: &large,
+        },
+    ];
+    let input = Input {
+        key: key(1),
+        entry: "project.arcadia",
+        files: &files,
+        applied: true,
+        validation: None,
+    };
+    for (resource, files_limit, bytes_limit, paths_limit) in [
+        (symbols::Resource::Files, 1, usize::MAX, usize::MAX),
+        (symbols::Resource::SourceBytes, 8, 1, usize::MAX),
+        (symbols::Resource::PathBytes, 8, usize::MAX, 1),
+    ] {
+        let limits = Limits {
+            index: symbols::Limits {
+                files: files_limit,
+                source_bytes: bytes_limit,
+                path_bytes: paths_limit,
+                tokens: 0,
+                records: 0,
+            },
+            ..Limits::default()
+        };
+        assert!(
+            matches!(capture(input, limits), Err(AdmissionError::Index(symbols::BuildError::Limit { resource: actual, .. })) if actual == resource)
+        );
+    }
+    assert_eq!(files[1].text, large);
+}
+
+#[test]
+fn token_declaration_and_live_reference_limits_are_aggregate_not_per_file() {
+    let files = [
+        DraftFile {
+            path: "a.arcadia",
+            text: "oa_activity a \"A\" {}",
+        },
+        DraftFile {
+            path: "b.arcadia",
+            text: "oa_activity b \"B\" {}",
+        },
+    ];
+    let input = Input {
+        key: key(1),
+        entry: "a.arcadia",
+        files: &files,
+        applied: false,
+        validation: None,
+    };
+    let limits = Limits {
+        index: symbols::Limits {
+            tokens: 10,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(input, limits),
+        Err(AdmissionError::Outline {
+            file: 1,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Tokens,
+                ..
+            }
+        })
+    ));
+    let limits = Limits {
+        index: symbols::Limits {
+            records: 1,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(input, limits),
+        Err(AdmissionError::Outline {
+            file: 1,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Declarations,
+                ..
+            }
+        })
+    ));
+    let use_files = [
+        files[0],
+        DraftFile {
+            path: "uses.arcadia",
+            text: "source @a; target @a; // @a ignored\n",
+        },
+    ];
+    let limits = Limits {
+        index: symbols::Limits {
+            records: 2,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(
+            Input {
+                files: &use_files,
+                ..input
+            },
+            limits
+        ),
+        Err(AdmissionError::Index(symbols::BuildError::Limit {
+            resource: symbols::Resource::Records,
+            observed_at_least: 3,
+            ..
+        }))
+    ));
+}
+
+#[test]
+fn missing_and_noncanonical_authored_ids_remain_draft_spans_without_generated_anchors() {
+    let fixture = Fixture::standard();
+    for replacement in [
+        String::new(),
+        " id \"00000000000000000000000000000002\"".into(),
+    ] {
+        let mut draft = fixture.clone();
+        let original_id = format!(" id \"{PUMP}\"");
+        *draft.text_mut("模块/活動.arcadia") = draft
+            .text("模块/活動.arcadia")
+            .replace(&original_id, &replacement);
+        draft
+            .text_mut("模块/活動.arcadia")
+            .push_str(&format!("// Historical UUID {PUMP} and @pump\r\n"));
+        let before = draft.files.clone();
+        let snapshot = draft.snapshot(None, false, Limits::default());
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&draft),
+            Action::Definition,
+        );
+        assert_eq!(result.definitions[0].declaration.authored_id, None);
+        assert_eq!(
+            result.definitions[0].declaration.identity,
+            Identity::Missing
+        );
+        assert_eq!(result.disposition, Disposition::Choices);
+        assert_eq!(draft.files, before);
+        assert_eq!(
+            snapshot.file(1).unwrap().text,
+            draft.text("模块/活動.arcadia")
+        );
+    }
+}
+
+#[test]
+fn keyword_alias_and_loaded_path_case_collisions_use_reviewed_index_rules() {
+    let mut fixture = Fixture::standard();
+    for (_, text) in &mut fixture.files {
+        *text = text.replace("pump", "source");
+    }
+    let snapshot = fixture.snapshot(None, true, Limits::default());
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(result.alias.as_deref(), Some("source"));
+    assert_eq!(result.total_definitions, 1);
+    fixture.files.push(("LINKS.arcadia".into(), String::new()));
+    let files = fixture.borrowed();
+    assert!(matches!(
+        capture(
+            Input {
+                key: key(1),
+                entry: &fixture.entry,
+                files: &files,
+                applied: true,
+                validation: None
+            },
+            Limits::default()
+        ),
+        Err(AdmissionError::Index(symbols::BuildError::Input {
+            problem: symbols::InputProblem::DuplicateOrCaseCollidingPath,
+            ..
+        }))
+    ));
+}
+
+#[test]
+fn owned_request_moves_exact_text_into_worker_snapshot_and_matches_sync_results() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation: Some(ValidatedSources {
+            entry: &fixture.entry,
+            files: &files,
+        }),
+    };
+    let owned = admit_owned(input, Limits::default()).unwrap();
+    let allocations: Vec<_> = owned.files.iter().map(|file| file.text.as_ptr()).collect();
+    let snapshot = owned.capture().unwrap();
+    for (file, allocation) in allocations.iter().enumerate() {
+        assert_eq!(
+            snapshot.file(file).unwrap().text.as_ptr(),
+            *allocation,
+            "worker moves the one current-text copy"
+        );
+    }
+    assert!(snapshot.matches(input));
+    let synchronous = capture(input, Limits::default()).unwrap();
+    assert_eq!(
+        query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&fixture),
+            Action::References
+        ),
+        query(
+            &synchronous,
+            "links.arcadia",
+            reference_offset(&fixture),
+            Action::References
+        )
+    );
+    let mut edited = fixture.clone();
+    edited
+        .text_mut("links.arcadia")
+        .push_str("// edited after request\r\n");
+    let changed = edited.borrowed();
+    assert!(!snapshot.matches(Input {
+        files: &changed,
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        validation: None,
+        ..input
+    }));
+}
+
+#[test]
+fn owned_request_checks_raw_limits_immediately_and_extracts_only_on_worker() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation: None,
+    };
+    let no_tokens = Limits {
+        index: symbols::Limits {
+            tokens: 0,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    let owned = admit_owned(input, no_tokens).expect("request admission does not lex or parse");
+    assert!(matches!(
+        owned.capture(),
+        Err(AdmissionError::Outline {
+            file: 0,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Tokens,
+                ..
+            }
+        })
+    ));
+    let no_bytes = Limits {
+        index: symbols::Limits {
+            source_bytes: 1,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        admit_owned(input, no_bytes),
+        Err(AdmissionError::Index(symbols::BuildError::Limit {
+            resource: symbols::Resource::SourceBytes,
+            ..
+        }))
+    ));
+    assert_eq!(files[1].text, fixture.text("模块/活動.arcadia"));
+}
+
+#[test]
+fn owned_validation_proof_preserves_full_witness_count_and_partial_scope() {
+    let accepted = Fixture::standard();
+    for missing_include in [false, true] {
+        let mut current = accepted.clone();
+        current
+            .files
+            .retain(|(path, _)| path != "模块/活動.arcadia");
+        if !missing_include {
+            *current.text_mut("project.arcadia") = current
+                .text("project.arcadia")
+                .replace(" include \"模块/活動.arcadia\";\r\n", "");
+        }
+        let files = current.borrowed();
+        let old = accepted.borrowed();
+        let input = Input {
+            key: key(1),
+            entry: &current.entry,
+            files: &files,
+            applied: true,
+            validation: Some(ValidatedSources {
+                entry: &accepted.entry,
+                files: &old,
+            }),
+        };
+        let snapshot = admit_owned(input, Limits::default())
+            .unwrap()
+            .capture()
+            .unwrap();
+        assert_eq!(snapshot.scope().closure_complete, !missing_include);
+        assert!(
+            !snapshot.scope().validated,
+            "the old witness is not silently reduced to matching loaded files"
+        );
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&current),
+            Action::Definition,
+        );
+        assert_eq!(result.disposition, Disposition::NoDefinition);
+        assert!(snapshot.matches(input));
+    }
+}

crates/oa-desktop/src/source_workspace.rs

@@ -1,7 +1,7 @@
 //! Per-file drafts and navigation. Accepted model/source history lives in Document.
 use iced::widget::text_editor::Cursor;
 use oa_core::{
-    language,
+    Id, language,
     source_project::{self, CompiledSourceProject, ProjectLimits, SourceBundle, SourceDiagnostic},
 };
 use std::collections::{BTreeMap, BTreeSet};
@@ -86,6 +86,7 @@ pub struct Buffer {
     pub cursor: Cursor,
     past: Vec<String>,
     future: Vec<String>,
+    generation: u64,
 }
 
 impl Buffer {
@@ -99,14 +100,20 @@ impl Buffer {
             },
             past: Vec::new(),
             future: Vec::new(),
+            generation: 0,
         }
     }
     pub fn dirty(&self) -> bool {
         self.text != self.baseline
     }
+    pub fn generation(&self) -> u64 {
+        self.generation
+    }
 }
 
 pub struct Workspace {
+    session: Id,
+    revision: u64,
     pub entry: String,
     pub active: String,
     pub files: BTreeMap<String, Buffer>,
@@ -117,6 +124,35 @@ pub struct Workspace {
 }
 
 impl Workspace {
+    /// Ephemeral editor identity, never a model identity or recovery payload.
+    pub fn session(&self) -> Id {
+        self.session
+    }
+    pub fn revision(&self) -> u64 {
+        self.revision
+    }
+    fn advance(&mut self) -> u64 {
+        if let Some(revision) = self.revision.checked_add(1) {
+            self.revision = revision;
+        } else {
+            self.reset_navigation_session();
+        }
+        self.revision
+    }
+    /// A changed filesystem root must not reuse queued navigation from Save As.
+    pub fn reset_navigation_session(&mut self) {
+        self.session = Id::new_v4();
+        self.revision = 0;
+        for buffer in self.files.values_mut() {
+            buffer.generation = 0;
+        }
+    }
+    pub fn set_reachable(&mut self, reachable: BTreeSet<String>) {
+        if self.reachable != reachable {
+            self.advance();
+            self.reachable = reachable;
+        }
+    }
     pub fn recovery_snapshot(&self) -> RecoveryWorkspace {
         RecoveryWorkspace {
             entry: self.entry.clone(),
@@ -136,6 +172,8 @@ impl Workspace {
     pub fn from_recovery(saved: RecoveryWorkspace) -> Result<Self, String> {
         saved.validate()?;
         Ok(Self {
+            session: Id::new_v4(),
+            revision: 0,
             entry: saved.entry,
             active: saved.active,
             files: saved
@@ -154,6 +192,8 @@ impl Workspace {
     }
     pub fn new(bundle: &SourceBundle, applied: bool) -> Self {
         Self {
+            session: Id::new_v4(),
+            revision: 0,
             entry: bundle.entry.clone(),
             active: bundle.entry.clone(),
             files: bundle
@@ -191,11 +231,20 @@ impl Workspace {
         }
     }
     pub fn edit(&mut self, text: String, cursor: Cursor) {
+        let changed = self.files.get(&self.active).is_none_or(|b| b.text != text);
+        let generation = if changed {
+            self.advance()
+        } else {
+            self.revision
+        };
         let buffer = self
             .files
             .entry(self.active.clone())
             .or_insert_with(|| Buffer::new(String::new()));
         buffer.cursor = cursor;
+        if changed {
+            buffer.generation = generation;
+        }
         if text != buffer.text {
             buffer.past.push(std::mem::replace(&mut buffer.text, text));
             if buffer.past.len() > 100 {
@@ -268,6 +317,8 @@ impl Workspace {
         } else {
             buffer.future.push(previous);
         }
+        let generation = self.advance();
+        self.files.get_mut(&self.active).unwrap().generation = generation;
         self.trim_history(DRAFT_HISTORY_BYTES);
         true
     }
@@ -281,6 +332,7 @@ impl Workspace {
         }
     }
     pub fn accept(&mut self, bundle: &SourceBundle) {
+        let generation = self.advance();
         if self.entry != bundle.entry
             && !bundle.files.contains_key(&self.entry)
             && self.files.get(&self.entry).is_some_and(|b| !b.dirty())
@@ -291,7 +343,13 @@ impl Workspace {
         self.reachable = bundle.files.keys().cloned().collect();
         for (path, text) in &bundle.files {
             let cursor = self.files.get(path).map(|b| b.cursor);
+            let previous_generation = self
+                .files
+                .get(path)
+                .filter(|b| b.text == *text)
+                .map(|b| b.generation);
             let mut buffer = Buffer::new(text.clone());
+            buffer.generation = previous_generation.unwrap_or(generation);
             if let Some(cursor) = cursor {
                 buffer.cursor = cursor;
             }
@@ -303,10 +361,22 @@ impl Workspace {
         self.applied = true;
     }
     pub fn discovered(&mut self, bundle: &SourceBundle, reachable: BTreeSet<String>) {
+        let changed = self.reachable != reachable
+            || bundle
+                .files
+                .keys()
+                .any(|path| !self.files.contains_key(path));
+        let generation = if changed {
+            self.advance()
+        } else {
+            self.revision
+        };
         for (path, text) in &bundle.files {
-            self.files
-                .entry(path.clone())
-                .or_insert_with(|| Buffer::new(text.clone()));
+            self.files.entry(path.clone()).or_insert_with(|| {
+                let mut buffer = Buffer::new(text.clone());
+                buffer.generation = generation;
+                buffer
+            });
         }
         self.reachable = reachable;
     }
@@ -314,6 +384,7 @@ impl Workspace {
         if self.reachable.contains(path) || self.files.get(path).is_none_or(Buffer::dirty) {
             return false;
         }
+        self.advance();
         self.files.remove(path);
         if self.active == path {
             self.active = self.entry.clone();
@@ -376,6 +447,148 @@ pub fn lint(bundle: &SourceBundle) -> Vec<SourceDiagnostic> {
 mod tests {
     use super::*;
     use oa_core::Project;
+
+    #[test]
+    fn fresh_session_cannot_reuse_a_retained_buffer_generation() {
+        let bundle = SourceBundle {
+            entry: "main.arcadia".into(),
+            files: BTreeMap::from([
+                ("main.arcadia".into(), "first".into()),
+                ("other.arcadia".into(), "other".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let cursor = workspace.files["main.arcadia"].cursor;
+        workspace.edit("second".into(), cursor);
+        workspace.reset_navigation_session();
+        let before = workspace.files["main.arcadia"].generation();
+        workspace.edit("third".into(), cursor);
+        assert_ne!(workspace.files["main.arcadia"].generation(), before);
+        workspace.switch("other.arcadia", cursor);
+        workspace.revision = u64::MAX;
+        workspace.edit("changed other".into(), cursor);
+        let after_wrap = workspace.files["main.arcadia"].generation();
+        workspace.switch("main.arcadia", cursor);
+        workspace.edit("fourth".into(), cursor);
+        assert_ne!(workspace.files["main.arcadia"].generation(), after_wrap);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.text(), "third");
+    }
+
+    #[test]
+    fn navigation_versions_distinguish_reopened_recovered_and_changed_drafts() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([
+                ("project.arcadia".into(), "entry\r\n".into()),
+                ("part.arcadia".into(), "雨 draft\r\n".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let reopened = Workspace::new(&bundle, true);
+        let recovered = Workspace::from_recovery(workspace.recovery_snapshot()).unwrap();
+        assert_ne!(workspace.session(), reopened.session());
+        assert_ne!(workspace.session(), recovered.session());
+        assert_eq!(workspace.bundle(), recovered.bundle());
+        let saved = serde_json::to_value(workspace.recovery_snapshot()).unwrap();
+        assert!(saved.get("session").is_none() && saved.get("revision").is_none());
+
+        let cursor = Cursor {
+            position: iced::widget::text_editor::Position { line: 0, column: 3 },
+            selection: None,
+        };
+        let revision = workspace.revision();
+        workspace.edit(workspace.text().into(), cursor);
+        assert_eq!(
+            workspace.revision(),
+            revision,
+            "selection is not a text change"
+        );
+        workspace.switch("part.arcadia", cursor);
+        assert_eq!(
+            workspace.revision(),
+            revision,
+            "switching retains the snapshot"
+        );
+        let untouched = workspace.files["project.arcadia"].generation();
+        workspace.edit("雨 unfinished !\r\n".into(), cursor);
+        let edited = workspace.files["part.arcadia"].generation();
+        assert!(workspace.revision() > revision);
+        assert_eq!(workspace.files["project.arcadia"].generation(), untouched);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.bundle(), bundle);
+        assert!(workspace.files["part.arcadia"].generation() > edited);
+        assert!(workspace.undo(true));
+        assert_eq!(workspace.text(), "雨 unfinished !\r\n");
+        let previous_session = workspace.session();
+        let previous_text = workspace.bundle();
+        workspace.reset_navigation_session();
+        assert_ne!(workspace.session(), previous_session);
+        assert_eq!(workspace.bundle(), previous_text);
+        assert!(
+            workspace.undo(false),
+            "session reset preserves text history"
+        );
+    }
+
+    #[test]
+    fn navigation_scope_changes_invalidate_without_changing_unchanged_positions() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([
+                ("project.arcadia".into(), "entry".into()),
+                ("part.arcadia".into(), "part".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let entry_generation = workspace.files[&bundle.entry].generation();
+        let initial_revision = workspace.revision();
+        workspace.set_reachable(BTreeSet::from([bundle.entry.clone()]));
+        assert!(workspace.revision() > initial_revision);
+        let membership_revision = workspace.revision();
+        workspace.set_reachable(workspace.reachable.clone());
+        assert_eq!(workspace.revision(), membership_revision);
+        assert!(workspace.discard_detached("part.arcadia"));
+        assert!(workspace.revision() > membership_revision);
+        let closed_revision = workspace.revision();
+        workspace.discovered(&bundle, BTreeSet::from([bundle.entry.clone()]));
+        assert!(workspace.revision() > closed_revision);
+        assert_eq!(
+            workspace.files[&bundle.entry].generation(),
+            entry_generation
+        );
+        assert!(workspace.files["part.arcadia"].generation() > closed_revision);
+        let discovered_revision = workspace.revision();
+        workspace.discovered(&bundle, workspace.reachable.clone());
+        assert_eq!(workspace.revision(), discovered_revision);
+        workspace.accept(&bundle);
+        assert!(
+            workspace.revision() > discovered_revision,
+            "validation evidence changed"
+        );
+        assert_eq!(
+            workspace.files[&bundle.entry].generation(),
+            entry_generation
+        );
+        assert_eq!(workspace.bundle(), bundle);
+    }
+
+    #[test]
+    fn navigation_revision_wrap_cannot_reuse_an_old_workspace_key() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([("project.arcadia".into(), "original".into())]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        workspace.revision = u64::MAX;
+        let before = workspace.session();
+        let cursor = workspace.files[&bundle.entry].cursor;
+        workspace.edit("changed".into(), cursor);
+        assert_ne!(workspace.session(), before);
+        assert_eq!(workspace.revision(), 0);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.bundle(), bundle);
+    }
     #[test]
     fn draft_history_budget_covers_inactive_files_without_discarding_drafts() {
         let bundle = SourceBundle {

crates/oa-desktop/src/tests.rs

@@ -377,7 +377,8 @@ fn source_navigation_waits_for_editor_layout_and_cancels_on_edit() {
     send(&mut app, Message::SourceForSelection);
     assert_eq!(app.page, Page::Text);
     assert!(app.source_jump.is_some());
-    send(&mut app, Message::SourceViewport);
+    let ticket = app.source_reveal_ticket();
+    send(&mut app, Message::SourceViewport(ticket));
     assert!(app.source_jump.is_none());
     send(&mut app, Message::SourceForSelection);
     assert!(app.source_jump.is_some());
@@ -409,7 +410,8 @@ fn source_find_navigates_an_invalid_draft_without_applying_or_losing_it() {
         cursor.selection,
         Some(text_editor::Position { line: 0, column: 9 })
     );
-    send(&mut app, Message::SourceViewport);
+    let ticket = app.source_reveal_ticket();
+    send(&mut app, Message::SourceViewport(ticket));
     assert_eq!(app.source_editor.cursor(), cursor);
     send(
         &mut app,
@@ -1269,7 +1271,26 @@ fn revealing_an_implicit_function_port_unfolds_its_visible_architecture_owner()
         .get_mut(&ancestor)
         .unwrap()
         .collapsed = true;
-    assert!(crate::navigation::diagrams_containing(&p, port).contains(&diagram));
+    // The usage query reports rendered objects; this port's owner is folded.
+    // The legacy authoring reveal below explicitly expands its saved ancestor.
+    assert!(
+        !oa_core::projection::project_view(&p, diagram)
+            .ports
+            .iter()
+            .any(|shown| shown.element == port)
+    );
+    assert!(crate::diagram_usage::saved_usages_for(&p, port, Some(diagram)).is_empty());
+    // Other saved views of this function may still paint the port.
+    let elsewhere = crate::diagram_usage::saved_usages(&p, port);
+    assert!(
+        !elsewhere.is_empty(),
+        "the demo still paints this port in another saved view"
+    );
+    assert!(
+        elsewhere
+            .iter()
+            .all(|usage| usage.surface != crate::diagram_usage::Surface::Saved(diagram))
+    );
     let mut app = App::with_project(p);
     send(&mut app, Message::RevealInDiagram(diagram, port));
     assert_eq!(app.selected, port);
@@ -1281,6 +1302,12 @@ fn revealing_an_implicit_function_port_unfolds_its_visible_architecture_owner()
             .iter()
             .any(|p| p.element == port)
     );
+    assert!(
+        crate::diagram_usage::saved_usages_for(app.project(), port, Some(diagram))
+            .iter()
+            .any(|usage| matches!(usage.target,
+            crate::diagram_usage::Target::Port { port: found, .. } if found == port))
+    );
 }
 
 #[test]

crates/oa-desktop/src/views.rs

@@ -1,3 +1,4 @@
+mod source_symbols;
 pub(crate) mod traceability;
 use crate::{
     app::{App, Choice, FileOperation, Message, Page, Pending},
@@ -12,6 +13,7 @@ use iced::{
     },
 };
 use oa_core::*;
+use unicode_segmentation::UnicodeSegmentation;
 
 pub fn label<'a>(s: impl Into<String>) -> widget::Text<'a> {
     text(s.into()).size(11).color(style::MUTED)
@@ -24,10 +26,12 @@ pub fn action<'a>(s: &str, m: Message) -> widget::Button<'a, Message> {
 }
 pub fn short(s: &str, limit: usize) -> String {
     let s = s.split_whitespace().collect::<Vec<_>>().join(" ");
-    if s.chars().count() > limit {
+    if s.graphemes(true).count() > limit {
         format!(
             "{}…",
-            s.chars().take(limit.saturating_sub(1)).collect::<String>()
+            s.graphemes(true)
+                .take(limit.saturating_sub(1))
+                .collect::<String>()
         )
     } else {
         s
@@ -446,6 +450,9 @@ fn diagram(app: &App) -> View<'_, Message> {
             view_index: Some(app.document.view_index()),
             diagram: id,
             selected: app.selected,
+            navigation_focus: app
+                .diagram_focus(crate::diagram_usage::Surface::Saved(id))
+                .map(|usage| usage.bounds),
             zoom: app.zoom,
             pan: app.pan,
             context: app.route_context().unwrap(),
@@ -466,10 +473,17 @@ fn diagram(app: &App) -> View<'_, Message> {
         if let Some(editor) = crate::app::architecture_authoring::inline_editor(app) {
             scene = scene.push(editor);
         }
+        let reveal = app.architecture_reveal_stamp(id);
         row![
             widget::sensor(scene)
-                .on_show(Message::CanvasResized)
-                .on_resize(Message::CanvasResized),
+                .on_show(move |size| reveal
+                    .map_or(Message::CanvasResized(size), |(context, epoch)| {
+                        Message::DiagramRevealViewport(context, epoch, size)
+                    }))
+                .on_resize(move |size| reveal
+                    .map_or(Message::CanvasResized(size), |(context, epoch)| {
+                        Message::DiagramRevealViewport(context, epoch, size)
+                    })),
             crate::app::architecture_authoring::palette(app)
         ]
         .height(Fill)
@@ -585,7 +599,7 @@ fn inspector(app: &App) -> View<'_, Message> {
         return container(
             column![
                 tabs,
-                scrollable(crate::navigation::view(p, app.selected)).height(Fill)
+                scrollable(crate::navigation::view(app, app.selected)).height(Fill)
             ]
             .spacing(14),
         )
@@ -1019,7 +1033,7 @@ fn source(app: &App) -> View<'_, Message> {
                 ),
                 action("Next", Message::SourceNavigation(SourceEvent::Next(false))),
                 label(app.source_navigation.label()),
-                action("Close", Message::SourceNavigation(SourceEvent::Close)),
+                action("Close", app.source_find_close_message()),
             ]
             .spacing(6)
             .align_y(iced::Center),
@@ -1113,8 +1127,12 @@ fn source(app: &App) -> View<'_, Message> {
         }
     }
     let editor = widget::text_editor(&app.source_editor)
-        .id("source-editor")
+        .id(app.source_editor_id())
         .on_action(Message::SourceEdit)
+        .key_binding({
+            let context = app.source_symbol_context();
+            move |press| source_binding(press, &context)
+        })
         .font(Font::MONOSPACE)
         .size(14)
         .padding(16)
@@ -1123,8 +1141,7 @@ fn source(app: &App) -> View<'_, Message> {
             app.source_snapshot.clone(),
             crate::highlight::format,
         );
-    column![
-        container(
+    let header = container(
             column![
                 row![
                     container(heading(
@@ -1167,17 +1184,501 @@ fn source(app: &App) -> View<'_, Message> {
                     "Undo text affects this file's draft. Model Undo restores accepted files together (100 changes / about 32 MiB)."
                 }),
                 navigation,
+                row![
+                    action("Definition · F12", app.source_symbol_message(crate::source_navigation::SymbolEvent::Query(crate::source_navigation::query::Action::Definition))),
+                    action("References · Shift F12", app.source_symbol_message(crate::source_navigation::SymbolEvent::Query(crate::source_navigation::query::Action::References))),
+                    action("Show in diagrams…", app.source_symbol_message(crate::source_navigation::SymbolEvent::DiagramUsages)),
+                    button(text("Back · Alt ←").size(12)).padding([8, 10]).style(style::nav)
+                        .on_press_maybe((app.source_symbols.back.iter().any(|entry| entry.session == app.source_workspace.session())).then(|| app.source_symbol_message(crate::source_navigation::SymbolEvent::Back))),
+                ].spacing(7),
                 scrollable(diagnostics)
                     .height((visible_diagnostics as f32 * 32.).min(132.))
             ]
             .spacing(12)
         )
-        .padding(18),
-        widget::sensor(editor).key((app.source_workspace.active.clone(),app.source_jump))
-            .on_show(|_| Message::SourceViewport).on_resize(|_| Message::SourceViewport)
+        .padding(18);
+    let editor = widget::sensor(editor)
+        .key((
+            app.source_workspace.active.clone(),
+            app.source_reveal_ticket(),
+        ))
+        .on_show({
+            let ticket = app.source_reveal_ticket();
+            move |_| Message::SourceViewport(ticket)
+        })
+        .on_resize({
+            let ticket = app.source_reveal_ticket();
+            move |_| Message::SourceViewport(ticket)
+        });
+    let workspace: View<'_, Message> = if app.source_symbols.open {
+        row![
+            container(editor).width(Fill).height(Fill),
+            container(scrollable(source_symbols::panel(app)))
+                .width(300)
+                .height(Fill),
+        ]
+        .height(Fill)
+        .into()
+    } else {
+        container(editor).width(Fill).height(Fill).into()
+    };
+    source_layout(header.into(), workspace, app.window_size.height)
+}
+
+fn source_layout<'a, Renderer: iced::advanced::text::Renderer + 'a>(
+    header: View<'a, Message, iced::Theme, Renderer>,
+    workspace: View<'a, Message, iced::Theme, Renderer>,
+    window_height: f32,
+) -> View<'a, Message, iced::Theme, Renderer> {
+    // Lint clears and repopulates diagnostics asynchronously. Reserve the same
+    // outer slot so a pointer aimed at the editor cannot land in the header.
+    column![
+        container(scrollable(header).id("source-header")).height((window_height * 0.42).max(180.)),
+        workspace,
     ]
+    .height(Fill)
     .into()
 }
+fn source_binding(
+    press: widget::text_editor::KeyPress,
+    context: &crate::source_navigation::SymbolContext,
+) -> Option<widget::text_editor::Binding<Message>> {
+    use crate::source_navigation::{SymbolEvent, query::Action};
+    use iced::keyboard::{Key, key::Named};
+    use widget::text_editor::{Binding, Status};
+    // Windows owns Alt+Space for its window menu. Iced's default binding would
+    // otherwise insert a supplied space payload, even after that menu closes.
+    // Keep Ctrl+Alt (AltGr), shifted input, and ordinary Space unchanged.
+    #[cfg(target_os = "windows")]
+    if matches!(press.status, Status::Focused { .. })
+        && press.modifiers == iced::keyboard::Modifiers::ALT
+        && matches!(
+            press.key.as_ref(),
+            Key::Named(Named::Space) | Key::Character(" ")
+        )
+    {
+        return None;
+    }
+    if matches!(press.status, Status::Focused { .. })
+        && !press.modifiers.control()
+        && !press.modifiers.logo()
+    {
+        let event = match &press.key {
+            Key::Named(Named::F12) if !press.modifiers.alt() => {
+                Some(SymbolEvent::Query(if press.modifiers.shift() {
+                    Action::References
+                } else {
+                    Action::Definition
+                }))
+            }
+            Key::Named(Named::ArrowLeft) if press.modifiers.alt() && !press.modifiers.shift() => {
+                Some(SymbolEvent::Back)
+            }
+            _ => None,
+        };
+        if let Some(event) = event {
+            return Some(Binding::Custom(Message::SourceSymbols(
+                context.clone(),
+                event,
+            )));
+        }
+    }
+    Binding::from_key_press(press)
+}
+
+#[cfg(all(test, debug_assertions))]
+mod source_tests {
+    use super::*;
+    use iced::advanced::{
+        Layout, Shell, graphics, layout, renderer, text as shaped, widget as core_widget,
+    };
+    use iced::widget::column;
+    use iced::{Background, Color, Pixels, Point, Rectangle, Size, Transformation, Vector};
+
+    // Measure real Iced paragraphs/editor text without constructing a window or GPU.
+    struct FontLayout;
+    impl renderer::Renderer for FontLayout {
+        fn start_layer(&mut self, _: Rectangle) {}
+        fn end_layer(&mut self) {}
+        fn start_transformation(&mut self, _: Transformation) {}
+        fn end_transformation(&mut self) {}
+        fn reset(&mut self, _: Rectangle) {}
+        fn fill_quad(&mut self, _: renderer::Quad, _: impl Into<Background>) {}
+        fn allocate_image(
+            &mut self,
+            handle: &iced::advanced::image::Handle,
+            callback: impl FnOnce(
+                Result<iced::advanced::image::Allocation, iced::advanced::image::Error>,
+            ) + Send
+            + 'static,
+        ) {
+            renderer::Renderer::allocate_image(&mut (), handle, callback);
+        }
+    }
+    impl shaped::Renderer for FontLayout {
+        type Font = Font;
+        type Paragraph = graphics::text::Paragraph;
+        type Editor = graphics::text::Editor;
+        const ICON_FONT: Font = Font::DEFAULT;
+        const CHECKMARK_ICON: char = '0';
+        const ARROW_DOWN_ICON: char = '0';
+        const SCROLL_UP_ICON: char = '0';
+        const SCROLL_DOWN_ICON: char = '0';
+        const SCROLL_LEFT_ICON: char = '0';
+        const SCROLL_RIGHT_ICON: char = '0';
+        const ICED_LOGO: char = '0';
+        fn default_font(&self) -> Font {
+            Font::DEFAULT
+        }
+        fn default_size(&self) -> Pixels {
+            Pixels(16.)
+        }
+        fn fill_paragraph(&mut self, _: &Self::Paragraph, _: Point, _: Color, _: Rectangle) {}
+        fn fill_editor(&mut self, _: &Self::Editor, _: Point, _: Color, _: Rectangle) {}
+        fn fill_text(&mut self, _: shaped::Text, _: Point, _: Color, _: Rectangle) {}
+    }
+
+    #[derive(Default)]
+    struct Geometry {
+        header: Option<(Rectangle, Rectangle, Vector)>,
+        editor: Option<Rectangle>,
+    }
+    impl core_widget::Operation for Geometry {
+        fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn core_widget::Operation)) {
+            visit(self);
+        }
+        fn container(&mut self, id: Option<&core_widget::Id>, bounds: Rectangle) {
+            if id == Some(&core_widget::Id::new("test-source-editor")) {
+                self.editor = Some(bounds);
+            }
+        }
+        fn scrollable(
+            &mut self,
+            id: Option<&core_widget::Id>,
+            bounds: Rectangle,
+            content: Rectangle,
+            offset: Vector,
+            _: &mut dyn core_widget::operation::Scrollable,
+        ) {
+            if id == Some(&core_widget::Id::new("source-header")) {
+                self.header = Some((bounds, content, offset));
+            }
+        }
+    }
+
+    fn mounted_source<'a>(
+        content: &'a widget::text_editor::Content<FontLayout>,
+        diagnostics: usize,
+        find: bool,
+        window_height: f32,
+    ) -> View<'a, Message, iced::Theme, FontLayout> {
+        let mut notices = column![].spacing(5);
+        for index in 0..diagnostics {
+            notices = notices.push(button(text(format!(
+                "救援/assess.arcadia:{}:5 · Warning: verify this participant's engineering allocation", index + 1,
+            )).size(12)).padding([4, 6]).width(Fill));
+        }
+        let find: View<'_, Message, iced::Theme, FontLayout> = if find {
+            column![
+                text_input("Find literal text", "assess").on_input(|s| Message::SourceNavigation(
+                    crate::source_navigation::Event::Query(s)
+                )),
+                text_input("Line", "1").on_input(|s| Message::SourceNavigation(
+                    crate::source_navigation::Event::Line(s)
+                )),
+            ]
+            .spacing(8)
+            .into()
+        } else {
+            Space::new().into()
+        };
+        let header = container(
+            column![
+                text("Textual model").size(24),
+                text("Edit the current file. Apply text validates the complete included model.")
+                    .size(11),
+                row![
+                    button(text("Apply text")),
+                    button(text("Undo text")),
+                    button(text("Model Undo"))
+                ]
+                .spacing(8),
+                text("救援/assess.arcadia · All files applied to the accepted model").size(11),
+                text("Undo text affects this draft. Model Undo restores accepted files together.")
+                    .size(11),
+                find,
+                row![
+                    button(text("Definition · F12")),
+                    button(text("References · Shift F12")),
+                    button(text("Back"))
+                ]
+                .spacing(7),
+                scrollable(notices).height((diagnostics as f32 * 32.).min(132.)),
+            ]
+            .spacing(12),
+        )
+        .padding(18);
+        let editor = container(
+            widget::text_editor(content)
+                .on_action(Message::SourceEdit)
+                .font(Font::MONOSPACE)
+                .size(14)
+                .padding(16)
+                .height(Fill),
+        )
+        .id("test-source-editor")
+        .height(Fill)
+        .width(Fill);
+        source_layout(header.into(), editor.into(), window_height)
+    }
+
+    #[test]
+    fn source_header_keeps_editor_bounds_stable_through_lint_and_find_rebuilds() {
+        for (host, window_height) in [
+            (Size::new(720., 540.), 700.),
+            (Size::new(1180., 890.), 1080.),
+        ] {
+            let content = widget::text_editor::Content::<FontLayout>::with_text(
+                "// is excluded\r\n// 雨\r\n",
+            );
+            let mut tree = core_widget::Tree::empty();
+            let mut baseline = None;
+            for (diagnostics, find) in [
+                (0, false),
+                (6, false),
+                (0, false),
+                (6, true),
+                (1, true),
+                (0, false),
+            ] {
+                let mut ui = mounted_source(&content, diagnostics, find, window_height);
+                tree.diff(ui.as_widget());
+                let node = ui.as_widget_mut().layout(
+                    &mut tree,
+                    &FontLayout,
+                    &layout::Limits::new(Size::ZERO, host),
+                );
+                let mut geometry = Geometry::default();
+                ui.as_widget_mut().operate(
+                    &mut tree,
+                    Layout::new(&node),
+                    &FontLayout,
+                    &mut geometry,
+                );
+                let editor = geometry.editor.unwrap();
+                let (header, _, _) = geometry.header.unwrap();
+                let slot = node.children()[0].bounds();
+                assert_eq!(slot.height, (window_height * 0.42).max(180.));
+                assert!(
+                    header.height <= slot.height,
+                    "short content may shrink inside the fixed slot"
+                );
+                assert!(
+                    editor.height >= 240.,
+                    "remaining editor must stay usable: {editor:?}"
+                );
+                assert_eq!(editor.y, slot.y + slot.height);
+                if let Some(expected) = baseline {
+                    assert_eq!(editor, expected, "diagnostics={diagnostics}, find={find}");
+                } else {
+                    baseline = Some(editor);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn source_header_remains_scrollable_and_preserves_offset_across_diagnostic_refresh() {
+        let content = widget::text_editor::Content::<FontLayout>::with_text("// 雨\r\n");
+        let host = Size::new(720., 540.);
+        let mut tree = core_widget::Tree::empty();
+        let mut saved = None;
+        for diagnostics in [6, 7] {
+            let mut ui = mounted_source(&content, diagnostics, true, 700.);
+            tree.diff(ui.as_widget());
+            let node = ui.as_widget_mut().layout(
+                &mut tree,
+                &FontLayout,
+                &layout::Limits::new(Size::ZERO, host),
+            );
+            let mut geometry = Geometry::default();
+            ui.as_widget_mut()
+                .operate(&mut tree, Layout::new(&node), &FontLayout, &mut geometry);
+            let (bounds, contents, _) = geometry.header.unwrap();
+            assert!(
+                contents.height > bounds.height,
+                "fixture must actually overflow"
+            );
+            if saved.is_none() {
+                let mut messages = Vec::new();
+                let mut shell = Shell::new(&mut messages);
+                ui.as_widget_mut().update(
+                    &mut tree,
+                    &iced::Event::Mouse(iced::mouse::Event::WheelScrolled {
+                        delta: iced::mouse::ScrollDelta::Pixels { x: 0., y: -45. },
+                    }),
+                    Layout::new(&node),
+                    iced::mouse::Cursor::Available(Point::new(bounds.x + 8., bounds.y + 8.)),
+                    &FontLayout,
+                    &mut iced::advanced::clipboard::Null,
+                    &mut shell,
+                    &Rectangle::with_size(host),
+                );
+                assert!(shell.is_event_captured());
+            }
+            let mut geometry = Geometry::default();
+            ui.as_widget_mut()
+                .operate(&mut tree, Layout::new(&node), &FontLayout, &mut geometry);
+            let offset = geometry.header.unwrap().2;
+            assert!(offset.y > 0., "the actual mounted Scrollable must move");
+            if let Some(before) = saved {
+                assert_eq!(offset, before);
+            } else {
+                saved = Some(offset);
+            }
+        }
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn source_editor_windows_menu_payload_is_inert_but_space_and_altgr_still_edit() {
+        use core_widget::operation::Focusable;
+        use iced::keyboard::{
+            self, Key, Modifiers,
+            key::{Code, Named, Physical},
+        };
+        use widget::text_editor::{Binding, Content, KeyPress, State, Status};
+        let baseline = "// is excluded\r\n// 雨\r\n";
+        let context = crate::source_navigation::SymbolContext {
+            session: Id::new_v4(),
+            path: "救援/assess.arcadia".into(),
+        };
+        for (key, physical_key, modifiers, payload, inserted) in [
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::ALT,
+                " ",
+                false,
+            ),
+            (
+                Key::Character(" ".into()),
+                Physical::Code(Code::Space),
+                Modifiers::ALT,
+                " ",
+                false,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::empty(),
+                " ",
+                true,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::CTRL | Modifiers::ALT,
+                " ",
+                true,
+            ),
+            (
+                Key::Character("e".into()),
+                Physical::Code(Code::KeyE),
+                Modifiers::CTRL | Modifiers::ALT,
+                "€",
+                true,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::ALT | Modifiers::SHIFT,
+                " ",
+                true,
+            ),
+        ] {
+            let mut content = Content::<FontLayout>::with_text(baseline);
+            content.move_to(widget::text_editor::Cursor {
+                position: widget::text_editor::Position { line: 0, column: 5 },
+                selection: None,
+            });
+            let press = KeyPress {
+                key: key.clone(),
+                modified_key: key.clone(),
+                physical_key,
+                modifiers,
+                text: Some(payload.into()),
+                status: Status::Focused { is_hovered: false },
+            };
+            assert!(
+                matches!(
+                    Binding::<Message>::from_key_press(press),
+                    Some(Binding::Insert(_))
+                ),
+                "the supplied event must expose the default insertion path"
+            );
+            let mut messages = Vec::new();
+            {
+                let mut editor: View<'_, Message, iced::Theme, FontLayout> =
+                    widget::text_editor(&content)
+                        .on_action(Message::SourceEdit)
+                        .font(Font::MONOSPACE)
+                        .size(14)
+                        .padding(16)
+                        .height(Fill)
+                        .key_binding(|press| source_binding(press, &context))
+                        .into();
+                let mut tree = core_widget::Tree::new(editor.as_widget());
+                let size = Size::new(600., 240.);
+                let node = editor.as_widget_mut().layout(
+                    &mut tree,
+                    &FontLayout,
+                    &layout::Limits::new(Size::ZERO, size),
+                );
+                tree.state
+                    .downcast_mut::<State<shaped::highlighter::PlainText>>()
+                    .focus();
+                let event = iced::Event::Keyboard(keyboard::Event::KeyPressed {
+                    key: key.clone(),
+                    modified_key: key,
+                    physical_key,
+                    location: keyboard::Location::Standard,
+                    modifiers,
+                    text: Some(payload.into()),
+                    repeat: false,
+                });
+                let mut shell = Shell::new(&mut messages);
+                editor.as_widget_mut().update(
+                    &mut tree,
+                    &event,
+                    Layout::new(&node),
+                    iced::mouse::Cursor::Unavailable,
+                    &FontLayout,
+                    &mut iced::advanced::clipboard::Null,
+                    &mut shell,
+                    &Rectangle::with_size(size),
+                );
+            }
+            assert_eq!(
+                messages.len(),
+                usize::from(inserted),
+                "modifiers={modifiers:?}"
+            );
+            for message in messages {
+                let Message::SourceEdit(action) = message else {
+                    panic!("unexpected navigation action");
+                };
+                content.perform(action);
+            }
+            let expected = if inserted {
+                format!("// is{payload} excluded\r\n// 雨\r\n")
+            } else {
+                baseline.into()
+            };
+            assert_eq!(content.text(), expected);
+        }
+    }
+}
 fn checks(app: &App) -> View<'_, Message> {
     let issues = &app.model_issues;
     let mut out = column![heading(
@@ -1290,3 +1791,57 @@ fn checks(app: &App) -> View<'_, Message> {
     }
     scrollable(out.padding(24)).into()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::short;
+
+    #[test]
+    fn short_preserves_native_lifeline_clusters_at_cutoff() {
+        let oa = "abcdefghijklmnope\u{0301}尾";
+        assert_eq!(short(oa, 17), "abcdefghijklmnop…");
+        assert_eq!(short(oa, 18), oa);
+        assert_eq!(short(oa, 19), oa);
+
+        let sa = "abcdefghijklmnop👩\u{200d}🔬 tail";
+        assert_eq!(short(sa, 17), "abcdefghijklmnop…");
+        assert_eq!(short(sa, 18), "abcdefghijklmnop👩\u{200d}🔬…");
+        assert_eq!(short(sa, 19), "abcdefghijklmnop👩\u{200d}🔬 …");
+        assert_eq!(short(sa, 22), sa);
+    }
+
+    #[test]
+    fn short_never_splits_retained_extended_graphemes() {
+        for cluster in ["e\u{0301}", "👩\u{200d}🔬", "👍🏽", "🇫🇷"] {
+            let value = format!("A{cluster}BC");
+            assert_eq!(short(&value, 2), "A…");
+            assert_eq!(short(&value, 3), format!("A{cluster}…"));
+            assert_eq!(short(&value, 4), value);
+        }
+    }
+
+    #[test]
+    fn short_preserves_ascii_cjk_and_whitespace_policy() {
+        assert_eq!(short("abcd", 3), "ab…");
+        assert_eq!(short("abcd", 4), "abcd");
+        assert_eq!(short("abcd", 5), "abcd");
+        assert_eq!(short("甲乙丙丁", 3), "甲乙…");
+        assert_eq!(short("甲乙丙丁", 4), "甲乙丙丁");
+        assert_eq!(short(" \tA\r\n e\u{0301}\u{2003}B  ", 5), "A e\u{0301} B");
+        assert_eq!(short(" \tA\r\n e\u{0301}\u{2003}B  ", 4), "A e\u{0301}…");
+    }
+
+    #[test]
+    fn short_preserves_empty_and_small_limit_policy() {
+        for limit in [0, 1, 2] {
+            assert_eq!(short("", limit), "");
+            assert_eq!(short(" \t\r\n", limit), "");
+        }
+        assert_eq!(short("A", 0), "…");
+        assert_eq!(short("A", 1), "A");
+        assert_eq!(short("AB", 1), "…");
+        assert_eq!(short("e\u{0301}", 0), "…");
+        assert_eq!(short("e\u{0301}", 1), "e\u{0301}");
+        assert_eq!(short("e\u{0301}B", 1), "…");
+    }
+}

crates/oa-desktop/src/views/source_symbols.rs

@@ -0,0 +1,260 @@
+use crate::{
+    app::{App, Message},
+    source_navigation::{
+        SymbolEvent,
+        query::{self, Declaration, Disposition, Evidence, Identity, Membership, Position},
+    },
+    style,
+};
+use iced::{
+    Element, Fill,
+    widget::{Space, button, column, container, row, scrollable, text, tooltip},
+};
+
+pub(super) fn panel(app: &App) -> Element<'_, Message> {
+    let state = &app.source_symbols;
+    if !state.open
+        || (state.results.is_none() && state.in_flight.is_none() && state.notice.is_none())
+    {
+        return column![].into();
+    }
+    let title = state.results.as_ref().map_or_else(
+        || "Source symbols".to_owned(),
+        |results| {
+            let action = match results.action {
+                query::Action::Definition => "Definitions",
+                query::Action::References => "References",
+            };
+            results.alias.as_ref().map_or_else(
+                || action.to_owned(),
+                |alias| format!("{action} · @{}", preview(alias, 40)),
+            )
+        },
+    );
+    let mut content = column![
+        row![
+            text(title).size(13),
+            Space::new().width(Fill),
+            button(text("Close").size(11))
+                .padding([3, 8])
+                .style(style::nav)
+                .on_press(app.source_symbol_message(SymbolEvent::Close)),
+        ]
+        .align_y(iced::Center)
+    ]
+    .spacing(5);
+
+    if let Some(notice) = &state.notice {
+        content = content.push(super::label(preview(notice, 240)));
+    }
+    if state.in_flight.is_some() {
+        content = content.push(super::label("Finding source symbols…"));
+    } else if let Some(results) = &state.results {
+        let stale = results.stamp.snapshot != app.source_key();
+        if stale {
+            content = content.push(super::label(
+                "Stale results — source changed. Run Definition or References again.",
+            ));
+        }
+        let scope = &results.scope;
+        content = content.push(super::label(format!(
+            "{} · {} · {} included / {} detached / {} unverified files · {} scope issues",
+            if scope.partial() {
+                "Partial scope"
+            } else {
+                "Complete include scope"
+            },
+            if !scope.applied {
+                "Unapplied drafts"
+            } else if scope.validated {
+                "Validated sources"
+            } else {
+                "Draft sources"
+            },
+            scope.included_files,
+            scope.detached_files,
+            scope.unverified_files,
+            scope.issues.len(),
+        )));
+        let explanation = match results.disposition {
+            Disposition::NoSymbol => "Place the caret on a declaration alias or an @reference.",
+            Disposition::NoDefinition => "No matching declaration in the loaded sources.",
+            Disposition::Choices => {
+                "Choose a declaration; draft and detached candidates need an explicit choice."
+            }
+            Disposition::Direct => "Definition in the current sources.",
+            Disposition::LexicalReferences => {
+                "Lexical uses of this alias; these do not establish a semantic target."
+            }
+        };
+        content = content.push(super::label(explanation));
+        if results.total_definitions > 1 {
+            content = content.push(super::label(format!(
+                "Alias collision: {} declarations. Uses are not attributed to a single declaration.",
+                results.total_definitions,
+            )));
+        }
+        let enabled = !stale && !app.busy;
+        let mut rows = column![super::label(counts(
+            "Declarations",
+            results.definitions.len(),
+            results.total_definitions,
+            results.omitted_definitions,
+        ))]
+        .spacing(4);
+        for (index, definition) in results.definitions.iter().enumerate() {
+            rows = rows.push(location_row(
+                declaration_title(&definition.declaration),
+                &definition.path,
+                definition.position,
+                provenance(
+                    definition.membership,
+                    definition.evidence,
+                    definition.declaration.identity,
+                    false,
+                ),
+                enabled.then(|| {
+                    app.source_symbol_message(SymbolEvent::Choose {
+                        stamp: results.stamp,
+                        reference: false,
+                        index,
+                    })
+                }),
+            ));
+        }
+        rows = rows.push(super::label(counts(
+            "Lexical uses",
+            results.references.len(),
+            results.total_references,
+            results.omitted_references,
+        )));
+        for (index, reference) in results.references.iter().enumerate() {
+            let title = reference.context.as_ref().map_or_else(
+                || format!("@{} · lexical use", preview(&reference.alias, 48)),
+                |context| {
+                    format!(
+                        "@{} · inside {}",
+                        preview(&reference.alias, 48),
+                        declaration_title(context)
+                    )
+                },
+            );
+            rows = rows.push(location_row(
+                title,
+                &reference.path,
+                reference.position,
+                provenance(
+                    reference.membership,
+                    reference.evidence,
+                    reference
+                        .context
+                        .as_ref()
+                        .map_or(Identity::Missing, |context| context.identity),
+                    true,
+                ),
+                enabled.then(|| {
+                    app.source_symbol_message(SymbolEvent::Choose {
+                        stamp: results.stamp,
+                        reference: true,
+                        index,
+                    })
+                }),
+            ));
+        }
+        let row_count = results.definitions.len() + results.references.len();
+        content =
+            content.push(scrollable(rows).height((44.0 + row_count as f32 * 48.0).min(180.0)));
+    }
+    container(content)
+        .padding(8)
+        .width(Fill)
+        .style(style::subtle)
+        .into()
+}
+
+fn counts(label: &str, shown: usize, total: usize, omitted: usize) -> String {
+    format!("{label}: {total} total · {shown} shown · {omitted} omitted")
+}
+
+fn declaration_title(declaration: &Declaration) -> String {
+    let name = declaration
+        .name
+        .as_ref()
+        .map_or_else(String::new, |name| format!(" \"{}\"", preview(name, 48)));
+    format!(
+        "{}{} · @{}",
+        preview(&declaration.kind, 24),
+        name,
+        preview(&declaration.alias, 48)
+    )
+}
+
+fn provenance(
+    membership: Membership,
+    evidence: Evidence,
+    identity: Identity,
+    context: bool,
+) -> String {
+    let membership = match membership {
+        Membership::Included => "Included",
+        Membership::Detached => "Detached",
+        Membership::Unverified => "Unverified",
+    };
+    let evidence = match evidence {
+        Evidence::Validated => "Validated",
+        Evidence::Draft => "Draft",
+    };
+    let collision = match identity {
+        Identity::Collision { count } => format!(
+            " · {}ID collision ({count})",
+            if context { "Context " } else { "" },
+        ),
+        Identity::Missing | Identity::Unique(_) => String::new(),
+    };
+    format!("{membership} · {evidence}{collision}")
+}
+
+fn location_row(
+    title: String,
+    path: &str,
+    position: Position,
+    status: String,
+    event: Option<Message>,
+) -> Element<'static, Message> {
+    let line = position.line.saturating_add(1);
+    let column = position.byte_column.saturating_add(1);
+    let location = format!("{}:{line}:{column}", preview(path, 72));
+    tooltip(
+        button(
+            column![
+                text(title).size(12),
+                super::label(format!("{location} · {status}"))
+            ]
+            .spacing(2),
+        )
+        .padding([4, 6])
+        .width(Fill)
+        .style(style::nav)
+        .on_press_maybe(event),
+        text(format!(
+            "{path}:{line}:{column} (1-based line and UTF-8 byte column)"
+        ))
+        .size(11),
+        tooltip::Position::Top,
+    )
+    .into()
+}
+
+/// Keep headings compact without copying the remainder of a long admitted value.
+fn preview(value: &str, limit: usize) -> String {
+    let mut chars = value.chars();
+    let mut result: String = chars
+        .by_ref()
+        .take(limit)
+        .map(|ch| if ch.is_whitespace() { ' ' } else { ch })
+        .collect();
+    if chars.next().is_some() {
+        result.push('…');
+    }
+    result
+}

crates/oa-desktop/src/workflow.rs

@@ -19,7 +19,7 @@ mod transition_tests;
 
 #[derive(Debug, Clone)]
 pub enum Event {
-    Semantic(crate::semantic_review::Event),
+    Semantic(Box<crate::semantic_review::Event>),
     Port(crate::port_workflow::Event),
     ExchangeItem(Id, bool),
     Endpoint(bool, EndpointChoice),
@@ -41,6 +41,11 @@ pub enum Event {
     Resolve(Id, TransitionField, FieldDecision),
     Preview,
 }
+impl Event {
+    pub fn semantic(event: crate::semantic_review::Event) -> Self {
+        Self::Semantic(Box::new(event))
+    }
+}
 pub enum Workflow {
     Semantic(Box<crate::semantic_review::State>),
     Ports(Box<crate::port_workflow::State>),

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,46 @@ 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><strong>Show in diagrams</strong> finds representations of a model record in saved diagrams,
+process/chain canvases and scenarios. Use the Text toolbar with the caret on a
+unique, verified alias in clean accepted sources, or the model tree's context
+menu for the chosen record. Choose a destination, then its exact representation.
+Lookup runs from an accepted-model snapshot; navigation preserves source drafts,
+accepted geometry and history. Pending edits or modal operations must be
+finished first. Changed or stale results cannot activate a different target.</p>
+<p>Membership follows the actual projection, including visible ports, state action
+and internal-transition rows, qualified reuse tiles, and SequenceLink arrows
+painted inside caller previews. Repeated callers have distinct destinations
+within the same canvas. Hidden preview endpoints and deeper nested links that
+the renderer does not draw are excluded; projected adjacency without an actual
+relation is not a SequenceLink usage. Preview-arrow focus lies on a visible
+line segment outside opaque tiles.</p>
+<p>An Allocation projection represents a direct Allocation relation by grouping
+only when its visible source performer placement occurs on the visible target
+work placement's actual visual-parent chain. Aggregate-only allocation summaries
+do not create direct relation usages. The navigation marker can focus a work
+header, port owner or state row independently of semantic selection: selecting
+an Allocation or state-action relation retains that relation as the model action
+target. Camera movement preserves a valid marker; changing the selected record,
+document, accepted revision or represented context retires it. Navigation does
+not alter allocation ownership or the meaning of Delete.</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,51 @@ 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.
+
+**Show in diagrams** finds representations of a model record in saved diagrams,
+process/chain canvases and scenarios. Use the Text toolbar with the caret on a
+unique, verified alias in clean accepted sources, or the model tree's context
+menu for the chosen record. Choose a destination, then its exact representation.
+Lookup runs from an accepted-model snapshot; navigation preserves source drafts,
+accepted geometry and history. Pending edits or modal operations must be
+finished first. Changed or stale results cannot activate a different target.
+
+Membership follows the actual projection, including visible ports, state action
+and internal-transition rows, qualified reuse tiles, and SequenceLink arrows
+painted inside caller previews. Repeated callers have distinct destinations
+within the same canvas. Hidden preview endpoints and deeper nested links that
+the renderer does not draw are excluded; projected adjacency without an actual
+relation is not a SequenceLink usage. Preview-arrow focus lies on a visible
+line segment outside opaque tiles.
+
+An Allocation projection represents a direct Allocation relation by grouping
+only when its visible source performer placement occurs on the visible target
+work placement's actual visual-parent chain. Aggregate-only allocation summaries
+do not create direct relation usages. The navigation marker can focus a work
+header, port owner or state row independently of semantic selection: selecting
+an Allocation or state-action relation retains that relation as the model action
+target. Camera movement preserves a valid marker; changing the selected record,
+document, accepted revision or represented context retires it. Navigation does
+not alter allocation ownership or the meaning of Delete.
+
 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

harness/DECISIONS.md

@@ -346,3 +346,42 @@ regressions; it does not broaden admission or add a new rule. Compilation and
 native acceptance of the renderer are still pending at this decision. Revisit the
 visual encoding if actual minimum-size engineering workflows make marker identity,
 uncertain continuation or the distinction between guide and existence unclear.
+
+## Diagram representation navigation — 2026-09-12
+
+Codex-ytr83r /root. User issues [14](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14)
+and [17](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17)
+share one typed query and destination chooser; the [contract](../docs/diagram-navigation.rst)
+defines identity, visible membership, source freshness and nonmutation. A result
+retains its representation identity separately from its queried semantic subject.
+Use the actual saved projection, process Graph, scenario Scene and state row
+geometry. Repeated occurrences and qualified reuse paths remain distinct.
+
+Reject endpoint-only membership and generic semantic-reference enumeration:
+they admit suppressed edges and opaque callee contents while missing behavioral
+occurrences and state rows. Reject a destination submenu containing every use or
+always-visible per-line lenses: both add noise and scale poorly for the user's
+editing workflow. An explicitly invoked, searchable chooser groups destinations
+and exposes their occurrences on demand. Independent design work identified
+minimum-window, repeated-name, source-caret, stale-result and full-history oracles
+before implementation; passing those evaluators remains necessary for acceptance.
+
+Ordinary navigation must not reuse the legacy reveal action's implicit Apply and
+persisted fold expansion. Resolve the exact target before changing presentation;
+center that target at readable scale. This first implementation lists currently
+rendered representations and explicitly discloses folded/filtered/unexpanded
+exclusions. It does not claim complete authored-membership discovery. Revisit
+transient hidden-object reveal after measured user workflows; adding a result
+must never imply an invisible object was actually shown or silently edit a view.
+
+The Text entry point builds on delivered source navigation from33c6d83, including
+eeeaa12 native corrections, while preserving the later canvas/chooser/repair
+integration. It requires verified applied-source identity and never substitutes
+model selection for the caret. Dirty-source semantic lookup remains a disclosed
+limitation. Implementation is branch-specific at this decision; Windows build,
+combined tests and native acceptance are not established by this record.
+
+
+## 2026-09-12 — Cross-machine coordination evidence
+
+User clarification: independent Gitea peer sessions run on different machines and cannot access this session’s `.local` directory. In-thread delegated agents share this workspace. Publish required source, reviews and runtime evidence through versioned Gitea commits or attachments before handing them to peers; verify access and link the exact version. Local paths are provenance only for remote peers. Local compiler, process and native-window observations do not establish another machine’s state or a shared hardware lease.

harness/STATE.md

@@ -1,9 +1,15 @@
-# Integrated checkpoint — 2026-09-11
+# Integrated checkpoint — 2026-09-12
 
-Codex-ytr83r, branch `codex/release1-ytr83r`. The full [user goal](../PROJECT_GOAL.md) remains incomplete. Live integration/acceptance work is in [Gitea issue5](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/5); the [project overview](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/1) and [process/scenario requirement](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/2) link other work. This file scopes integrated code and evidence.
+Codex-ytr83r, isolated branch `codex/canvas-union-ytr83r-20260911`. Current source `33e30c1` combines the a57 canvas, cb91525 grapheme and narrow saved-destination repair corrections. Its 530 frozen inputs match HEAD; independent repair review found no actionable finding. Windows desktop tests, strict Clippy, GUI build and bounded matching native/package acceptance passed. The [canvas-repair Windows prerelease](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/releases/tag/v0.2.0-preview.canvas-repair.20260912) is published; ZIP, checksum and validation attachments were downloaded and hash-verified. [Publication record](release-canvas-repair-publication-20260912.md) preserves the exact identities. This is not a full [user-goal](../PROJECT_GOAL.md) completion claim. Live [canvas integration](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/2), [native/release acceptance](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/5), [saved-destination repair](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/6) and [project overview](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/1) retain ownership and plans. Earlier production `865483b` and its package remain preserved.
 
 ## Verified code and capabilities
 
+Source `33e30c1` binds repair dirty state to the actual saved destination, preserving accepted-model history even when Apply is an identical-content no-op. It selectively incorporates peer `33c6d83` in three files. Windows focused repair **5**, full desktop **761**, strict desktop all-targets Clippy and GUI build passed; the five are included in 761. All **530 files / 9,727,025 bytes** remained unchanged between gates and matched HEAD after the build. The preserved GUI `50486253…` passed matching repair/history/recovery and Unicode selection/passive-save checks, packaged walkthrough/help smoke and normal exit0 with empty logs. All559 package files stayed unchanged; fresh extracted server25-request editing/persistence checks passed. [Current validation and artifact hashes](release-canvas-repair-validation-20260912.md) links the exact raw archives and independent reviews. [Repair union and limits](release-repair-union-ytr83r-20260912.md), [closed gates and exact inputs](experiments/repair-union-windows-33e30c1-20260912/README.md), [verbatim independent review](release-saved-destination-independent-review-20260912.md).
+
+Source `cb91525` preserves extended grapheme clusters in the shared display helper. Its four focused tests, full desktop 756 and strict desktop Clippy passed; the four overlap the 756. Its GUI build was intentionally superseded by the repair union; matching combined33e native Unicode evidence is recorded above, without reattributing that result to cb91525. [Correction and limits](release-grapheme-shortening-ytr83r-20260911.md), [closed Windows evidence](experiments/grapheme-windows-cb91525-20260911/README.md).
+
+The isolated `a57c334` union selectively combines peer `a31b40d` canvas/chooser/form prerequisites with B4 lifetime rendering and contextual source/child-work corrections. Windows lifecycle **27**, full desktop **752**, strict desktop Clippy and Studio build passed on 529 unchanged frozen inputs. GUI `69DBB90F…` passed bounded staged source/consumer creation, Cancel, Save, Undo/Redo and reopen checks: 13 oracles and 45 screenshots at the default wide window only. [Canvas checkpoint](release-canvas-union-ytr83r-20260911.md), [staged archive](experiments/staged-source-native-a57c334-20260911/README.md), [independent review](release-staged-native-a57-independent-review-20260911.md). A fresh a57 camera session subsequently passed bounded OA 100%/125%/Fit and minimum 1100×700 client Fit66 checks, OA/SA pan and moved Create/Delete hit selection, exact passive Save equality and normal exit 0. The 18 images support bounded clipping without toolbar bleed; labels are small at 66%. [Camera archive and limits](experiments/canvas-camera-a57c334-20260912/README.md), [verbatim independent review](release-camera-a57-independent-review-20260912.md). The [earlier picker failure](experiments/canvas-native-close-a57c334-20260911/README.md) remains historical evidence. These pre-grapheme a57 results do not establish current `33e30c1` native or complete usability acceptance.
+
 Earlier published checkpoint `3ade397008cffe826d5f5a70e7c0233159e3bd42` contains production `29084050a7c020e0fb488be37c6e1ab235769cc0`; push and exact remote readback passed. It combines prior named behavior creation/history integration (`c81e285`, `e207b04`), corrected creation-oracle evidence (`b853a1e`), CLI-only integration (`023e3a8`) and B4 lifecycle rendering.
 
 B4 renders local lifetimes, branch-local activation termination, neutral incomplete lanes, Create capsules and Delete markers with original occurrence identity. Real Windows OA/SA six-case matrices and separate name-only Save/Undo/Redo/reopen workflows passed complete independent Project, reachable-source and physical-file comparisons. These are bounded fixture checks, not complete product usability acceptance.
@@ -15,7 +21,7 @@ B4 renders local lifetimes, branch-local activation termination, neutral incompl
 
 Source `321897fd55af9e07afa2c6ebf1e50be49e86f7d9` integrates the published contextual source-creation/minimum-card corrections from b2c3e540 with B4 and the header clipping correction. Its own Windows desktop all-targets gate passed 704 tests. [Exact selective integration, independent union review and Windows results](release-contextual-integration-update-ytr83r-20260911.md).
 
-Published production `865483b4c66361a01fe0d9e731859220bafb4136` adds the reviewed child-work correction: first refinement transfers existing Allocation and RoleAssignment identities, metadata and artifact references to the child; later siblings inherit only a unique performer. OA/SA regressions cover nested children, roles, folded grouping, unallocated/mixed controls and exact history. The extracted Studio `BF9C2E61…` passed actual OA first-child, sibling and grandchild creation plus Save/Undo/Redo comparisons against original complete model/source checkpoints. Reopening and the SA native counterpart remain unverified. [Child-work fixture and oracle](fixtures/child-work-native/README.md); [native OA evidence](experiments/native-child-oa-865483b-20260911/README.md); [live acceptance boundary](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/4).
+Published production `865483b4c66361a01fe0d9e731859220bafb4136` adds the reviewed child-work correction: first refinement transfers existing Allocation and RoleAssignment identities, metadata and artifact references to the child; later siblings inherit only a unique performer. OA/SA regressions cover nested children, roles, folded grouping, unallocated/mixed controls and exact history. The old extracted Studio `BF9C2E61…` passed OA first-child, sibling and grandchild Save/Undo/Redo checks, then confirmed OA reopen/Save and the SA first/sibling/grandchild, Undo/Redo and reopen/Save continuation. Original identity carriers and complete source/physical snapshots matched. These are native results for **865483b/BF9**, not a57/69DB. [Original OA evidence](experiments/native-child-oa-865483b-20260911/README.md), [closed continuation](experiments/native-child-continuation-865483b-20260911/README.md), [independent continuation review](release-native-child-continuation-review-20260911.md), [fixture/oracle](fixtures/child-work-native/README.md) and [issue4](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/4) preserve the exact scope.
 
 ## Verification scope
 
@@ -30,13 +36,15 @@ The closed 321897f Windows gate passed 704 desktop tests with zero failed/ignore
 
 The later 865483b Windows desktop gate passed **707 tests**, including the three focused child-work regressions, with zero failed/ignored/filtered. All 261 recorded build inputs stayed unchanged. The matching debug GUI build and strict **desktop-only** all-targets Clippy passed; child-work and staged-source checker compilation/admission also passed. [Closed gates and exact inputs](experiments/windows-gates-865483b-20260911/README.md). These checks do not establish the remaining native rendering or packaged acceptance.
 
-The extracted package's unchanged server `ABA87A5F…` passed the actual HTTP schema checks (204/19/9) and 25-request REST editing/persistence/restart probe with a restricted process PATH and unrelated working directory. Seven raw response pairs and exact source snapshots matched; all five test-owned server processes stopped. The first REST run's PowerShell-added PATH directory is preserved as historical evidence; the corrected restricted-PATH rerun is authoritative. [Packaged server evidence](experiments/packaged-server-865483b-20260911/README.md). This completes bounded server runtime acceptance, while the new Windows preview remains unpublished pending the separate GUI checks.
+The extracted package's unchanged server `ABA87A5F…` passed the actual HTTP schema checks (204/19/9) and 25-request REST editing/persistence/restart probe with a restricted process PATH and unrelated working directory. Seven raw response pairs and exact source snapshots matched; all five test-owned server processes stopped. The first REST run's PowerShell-added PATH directory is preserved as historical evidence; the corrected restricted-PATH rerun is authoritative. [Packaged server evidence](experiments/packaged-server-865483b-20260911/README.md). This completed the earlier bounded server runtime acceptance. Fresh33e package/server/GUI results are linked above; the old receipts retain their own source attribution.
 
 ## Material limitations
 
-Native wide Latin/CJK checks found neutral lifeline header text overflowing its card; Create labels remained contained. The [header correction](lifecycle-header-overflow-correction-ytr83r-20260911.md) is included in the tested 865483b source, but matching corrected pixels and combining/emoji native appearance remain unverified. The old GUI's wide-name passive Save pass establishes identity/model/source/file equality, not corrected rendering. Complete combined native and packaged acceptance remain separate. During the OA reopen check, the Computer helper repeatedly failed with `window capture timed out: timed out waiting on channel`; fresh window selection and one clean helper restart did not recover capture. Native input stopped at the Open dialog with the accepted grandchild result already saved. This is a validation-tool failure, not evidence of a model failure or a successful reopen.
+Earlier native wide Latin/CJK checks found neutral lifeline header text overflowing its card while Create labels stayed contained. The [header correction](lifecycle-header-overflow-correction-ytr83r-20260911.md) is included in 865483b and retained in a57. Actual corrected wide-W/CJK observations in BF9 show bounded headers and Create labels, including selected zoom, scroll and minimum-window cases. Both complete wide and cluster sources remained unchanged after passive Save. Cluster checks exposed a separate scalar-shortening defect: an accent or joined emoji can be split at the label cutoff. The later cb91525 correction and current33e accent/ZWJ selection/passive-save checks resolve the observed string-splitting case. Long wide labels can still be hard-clipped and arbitrary font/DPI presentation is unverified; see the historical [native typography record](experiments/lifecycle-header-correction-native-865483b-20260911/README.md).
 
-Other chooser/canvas and text-navigation contributions still require their own integration and verification. Calculations, quantities/units, maintained libraries, practical large-model textual workflows, complete OA↔SA engineering parity, documentation and fresh cross-disciplinary review remain full-goal requirements. See the [analysis proposal](release-analysis-semantics-design-20260910.md), [library proposal](release-libraries-semantics-design-20260910.md), [text-authoring design](release-textual-authoring-design-20260911.md) and [decisions](DECISIONS.md) for attributed design evidence, not completed implementation claims.
+The earlier capture failures and pending Open dialog are historical: later confirmed OA and SA reopen/Save actions are preserved in the [continuation archive](experiments/native-child-continuation-865483b-20260911/README.md). Its first OA `reopened-1948` receipts remain data-only evidence. Bounded a57 staged and camera workflows above are complete; full focus/keyboard, every clipping edge/zoom and accessibility remain unverified. Bounded combined `33e30c1` native/package acceptance is now linked above. Small 66% labels are a recorded limitation. The BF9 Home page, scenario guide and bundled water-pressure example opened; one normal Alt+F4 then completed, with the process absent and empty stdout/stderr. The [old Home/Guide/close archive](experiments/packaged-gui-close-865483b-20260911/README.md) preserves those old865/BF9 observations and package readback. No exit code was captured for that older BF9 process; the separate a57 exit 0 does not change its evidence.
+
+The selected chooser/canvas union now has a57 source and Windows gate evidence; broader persistent graphical manipulation and separate text-navigation contributions retain their own integration/acceptance boundaries. Calculations, quantities/units, maintained libraries, practical large-model textual workflows, complete OA↔SA engineering parity, documentation and fresh cross-disciplinary review remain full-goal requirements. See the [analysis proposal](release-analysis-semantics-design-20260910.md), [library proposal](release-libraries-semantics-design-20260910.md), [text-authoring design](release-textual-authoring-design-20260911.md) and [decisions](DECISIONS.md) for attributed design evidence, not completed implementation claims.
 
 ## Platform and published deliverables
 

harness/experiments/behavior-layout-policy-20260912/README.md

@@ -0,0 +1,11 @@
+# Scenario layout policy experiment — bounded evidence
+
+Question: can absolute desired coordinates and gap-before records express the same small feasible layouts, and what semantics must a movement planner preserve? This is an isolated JavaScript experiment, not production Rust or a substitute for actual Arcadia Scene, parser, REST, history, or native acceptance. The ten-unit separation and rectangle metrics are illustrative.
+
+[Source](experiment.mjs) executed through Node REPL and wrote [results](results.json): 3,555 feasible three-row layouts and 53,325 single-move cases passed. Handwritten numeric cases expose different naive reorder/delete/resize behavior. Both encodings can express the enumerated feasible outputs. Changed-coordinate counts compare only the specific single-edit forward policy, not equally expressive retained intent across histories. Elapsed time includes assertions and this machine’s load; it is not a renderer performance result.
+
+[Independent review](independent-review.md) found an omitted conflict-then-zero-motion history. [The negative probe](negative-zero-motion.mjs) reuses the same experiment with that additional assertion; root executed it and [reproduced the expected assertion failure](negative-zero-motion-result.json): a zero-screen-motion operation changes B.desired from200 to280. The original source/results remain preserved. No production failure is implied.
+
+The next experiment must distinguish a pointer gesture (original frame and actual delta; zero motion preserves authored input) from an explicit SetDesiredY/Normalize operation, and test move-away/back and resize histories. Equal visible geometry does not imply equal latent layout intent. Before schema adoption, exercise one parsed real scenario through the actual Scene/attachment adapter, including self-message and nested/lifetime cases. The [design proposal and critique](../behavior-navigation-review-20260912/README.md) remain conditional.
+
+To reproduce, copy experiment.mjs and negative-zero-motion.mjs into an empty directory and run `node experiment.mjs`, then `node negative-zero-motion.mjs`. The first writes results.json; the second must fail its zero-distance assertion. Existing output is never overwritten. Node built-ins only; no package installation or network is required. [Hashes](hashes.json) bind the exact executed source/result artifacts.

harness/experiments/behavior-layout-policy-20260912/experiment.mjs

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import { writeFile } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
+// Isolated policy comparison; these illustrative metrics are not Studio rules.
+const separation = 10;
+function absolute(rows) {
+  let end = -separation;
+  return rows.map(r => { const y = Math.max(r.y, end + separation); end=y+r.height; return {...r,y}; });
+}
+function gaps(rows) {
+  let end=0;
+  return rows.map((r,i) => { assert(r.gap >= (i?separation:0)); const y=end+r.gap; end=y+r.height; return {...r,y}; });
+}
+function encodeGaps(rows) {
+  return rows.map((r,i)=>({...r,gap:r.y-(i?rows[i-1].y+rows[i-1].height:0)}));
+}
+const positions = rows=>rows.map(r=>r.y);
+function moveAbsolute(rows,index,requested) {
+  const current=absolute(rows);
+  const floor=index?current[index-1].y+current[index-1].height+separation:0;
+  const candidate=rows.map((r,i)=>({...r,y:i===index?Math.max(requested,floor):r.y}));
+  return {candidate,preview:absolute(candidate)};
+}
+function changeCount(before,after,key) {return before.reduce((n,r,i)=>n+(r[key]!==after[i][key]),0);}
+const initial=[{id:'A',y:100,height:20},{id:'B',y:200,height:20}];
+const initialG=encodeGaps(initial);
+const cases=[];
+function named(name,a,g,expectedA,expectedG) {
+  assert.deepEqual(positions(a),expectedA,name+' absolute');
+  assert.deepEqual(positions(g),expectedG,name+' gaps');
+  cases.push({name,absolute:positions(a),gapsWithoutInverse:positions(g)});
+}
+named('move A to50',absolute([{...initial[0],y:50},initial[1]]),gaps([{...initialG[0],gap:50},initialG[1]]),[50,200],[50,150]);
+named('move A to250',absolute([{...initial[0],y:250},initial[1]]),gaps([{...initialG[0],gap:250},initialG[1]]),[250,280],[250,350]);
+named('resize A to80',absolute([{...initial[0],height:80},initial[1]]),gaps([{...initialG[0],height:80},initialG[1]]),[100,200],[100,260]);
+named('resize A to120',absolute([{...initial[0],height:120},initial[1]]),gaps([{...initialG[0],height:120},initialG[1]]),[100,230],[100,300]);
+named('source reorder B A',absolute([initial[1],initial[0]]),gaps([initialG[1],initialG[0]]),[200,230],[80,200]);
+named('delete A',absolute([initial[1]]),gaps([initialG[1]]),[200],[80]);
+assert.deepEqual(positions(moveAbsolute(initial,1,110).preview),[100,130]);
+let feasible=0,moves=0,absoluteChanges=0,gapChanges=0;
+const started=performance.now();
+for(const ha of [10,20,30])for(const hb of [10,20,30])for(const hc of [10,20,30])
+for(let a=0;a<=40;a+=10)for(let b=a+ha+10;b<=90;b+=10)for(let c=b+hb+10;c<=140;c+=10) {
+  const rows=[{id:'A',height:ha,y:a},{id:'B',height:hb,y:b},{id:'C',height:hc,y:c}];
+  assert.deepEqual(positions(absolute(rows)),[a,b,c]);
+  assert.deepEqual(positions(gaps(encodeGaps(rows))),[a,b,c]);
+  feasible++;
+  for(let i=0;i<3;i++)for(const delta of [-50,-20,0,10,40]) {
+    const requested=rows[i].y+delta, {candidate,preview}=moveAbsolute(rows,i,requested);
+    const independent=[];
+    for(let j=0;j<3;j++) {
+      const floor=j?independent[j-1]+rows[j-1].height+10:0;
+      independent.push(Math.max(j===i?requested:rows[j].y,floor));
+    }
+    assert.deepEqual(positions(preview),independent);
+    assert.deepEqual(positions(absolute(preview)),independent);
+    assert.deepEqual(positions(absolute(JSON.parse(JSON.stringify(candidate)))),independent);
+    const encoded=encodeGaps(preview);
+    assert.deepEqual(positions(gaps(encoded)),independent);
+    assert.deepEqual(candidate.map(r=>r.id),['A','B','C']);
+    for(let j=0;j<i;j++) assert.deepEqual(candidate[j],rows[j]);
+    absoluteChanges+=changeCount(rows,candidate,'y');
+    gapChanges+=changeCount(encodeGaps(rows),encoded,'gap');
+    moves++;
+  }
+}
+// Independent event/frame attachment probes: no actual Scene/activation engine.
+const selfCall=absolute([{id:'call',y:250,height:24},{id:'reply',y:320,height:0}]);
+assert.equal(selfCall[0].y+24,274);
+assert.equal(selfCall[1].y,320);
+const children=[{y:160,height:20},{y:260,height:20}];
+const requiredFrameBottom=Math.max(...children.map(r=>r.y+r.height))+20;
+assert.equal(requiredFrameBottom,300);
+assert.equal(Math.max(300,requiredFrameBottom),300);
+assert.equal(Math.max(220,requiredFrameBottom),300);
+assert.deepEqual(children,[{y:160,height:20},{y:260,height:20}]);
+assert.equal(220-90,130); // delayed header top from moved create receive and header height
+const result={
+  scope:'Illustrative linear policy and anchor experiment; no production parser, REST, Scene, GUI or full fragment/lifecycle acceptance.',
+  separation, cases, feasibleLayouts:feasible, moveCases:moves,
+  changedAuthoredCoordinateRecords:{absolute:absoluteChanges,gapsWithInverse:gapChanges},
+  elapsedMs:performance.now()-started,
+  assertions:'passed',
+  interpretation:'Both policies express all enumerated feasible layouts. Absolute coordinates preserve unaffected positions with fewer authored coordinate changes under these fixtures. Choose no production schema from this alone; full scope/anchor/inverse and source lifecycle validation remain required.'
+};
+await writeFile(new URL('./results.json',import.meta.url),JSON.stringify(result,null,2)+'\n',{flag:'wx'});
+export default result;

harness/experiments/behavior-layout-policy-20260912/hashes.json

@@ -0,0 +1,22 @@
+[
+  {
+    "file": "experiment.mjs",
+    "bytes": 5123,
+    "sha256": "8a2b5adc35a25173ec2d37a46572cebac12d73bc8c9440f3cfdff784858c52c1"
+  },
+  {
+    "file": "results.json",
+    "bytes": 1633,
+    "sha256": "866e4c81c42a922033669aa6c591857029303627db28c5307b0126503a6791b8"
+  },
+  {
+    "file": "negative-zero-motion.mjs",
+    "bytes": 5383,
+    "sha256": "b76b1aa1c5d19043540381fc31224ecb86298796fb3adf2cdc8847c412b034ce"
+  },
+  {
+    "file": "negative-zero-motion-result.json",
+    "bytes": 707,
+    "sha256": "1dab9972fdef1586e48c89f5afe8dd6a3cfa5d58adf68088e74440dbf4eb70a9"
+  }
+]

harness/experiments/behavior-layout-policy-20260912/independent-review.md

@@ -0,0 +1,55 @@
+# Review of the isolated layout-policy experiment
+
+2026-09-12. Independent reviewer `/root/diagram_usage_workflows`; read [experiment.mjs](experiment.mjs) and [results.json](results.json). Root reports executing the experiment. This review inspected code/results without rerunning them; no production edits, builds, UI, or Gitea operations. Local links are for this shared agent workspace; root will publish portable artifacts before any external peer handoff.
+
+## Findings and justified conclusion
+
+**Useful result:** both encodings reproduce all 3,555 enumerated feasible three-row layouts. Under the particular forward-only, minimum-gap movement policy, a gap inverse can reproduce the absolute planner's 53,325 single-move previews. This rebuts the idea that gap storage inherently prevents precise placement. Absolute coordinates are a reasonable candidate for the next experiment.
+
+**Not established:** the best production policy, equivalent edit-history behavior, source/API parity, real scenario anchors, fragments/lifetimes, minimal record changes in general, responsiveness, or schema adoption. The result file correctly disclaims most of these. Its “fewer authored coordinate changes” claim should be scoped to single edits from initially feasible layouts, using this forward resolver and this gap encoding. It is not yet a fair comparison of equally expressive persistent intent across histories.
+
+### 1. A concrete omitted history violates the proposed zero-movement contract
+
+Starting authored A100/B200, height20 each:
+
+1. `moveAbsolute(rows, A, 250)` stores A250/B200 and displays A250/B280.
+2. Select B and release at unchanged displayed y280.
+3. `moveAbsolute(candidate, B, 280)` stores B280, changing its previous desired200 despite no screen movement.
+
+The experiment starts each move from a feasible layout, so its delta=0 cases cannot find this. A pointer gesture should carry its original frame, original authored candidate and actual pointer delta, returning that original candidate for zero delta before inverse mapping. That is an additional required contract, not something tested here. An explicit text/API `SetDesiredY` may legitimately change latent authored intent even when the current projected coordinate is equal; explicitly applying the displayed coordinate through Properties could likewise be a meaningful normalization operation. The toy function has no operation-intent input and is not a complete gesture planner. An untouched pointer gesture must remain a no-op.
+
+Another important history is moving A back to100. Retaining absolute B.desired=200 restores B200, whereas the first gap inverse encoded the displaced output B280 and did not preserve B's original desired position. A gap planner can preserve the current visible B280 or use extra latent intent to restore200; choose the intended behavior explicitly. Neither result is intrinsically correct, but the current counters compare representations containing different information after the first conflict.
+
+### 2. Oracle independence is partial
+
+- The six named example outputs are hand-authored numerical expectations. They are useful independent checks of the proposed policy examples, though they do not exercise Studio.
+- The loop called `independent` repeats the same left-to-right `max(requested-or-old, predecessor-bottom+10)` recurrence as `moveAbsolute` plus `absolute`. It can catch implementation inconsistencies but does not independently establish that the chosen movement policy matches user intent or is the least disruptive feasible solution.
+- `absolute(preview)` checks idempotence on already resolved geometry. It does not prove that authored unresolved intent survives a sequence of commands or that the inverse preserves inactive fields.
+- JSON stringify/parse of plain toy records demonstrates only that these small numeric values survive JavaScript JSON. There is no Arcadia grammar, source comment ownership, schema version, f32 precision, REST conditional transaction, or Document history exercised.
+- Checking the three IDs remain A/B/C and earlier rows are unchanged is useful but does not exercise steps, sender/receiver, reply_to, branch membership, or lifecycle semantics.
+- “Independent event/frame attachment probes” is too strong a label. `250+24=274`, `max(child bottoms)+20=300`, and `220-90=130` are arithmetic expectations. They do not invoke a self-message, frame resize or lifetime implementation. The unchanged-children assertion observes an array no code attempted to change. Treat these as fixture seeds for future tests.
+
+### 3. Fairness and coverage of the comparison
+
+Encoding the same final preview with `encodeGaps` is a fair test of gap expressiveness and a narrowly useful coordinate-update count. It is not an independent gap-policy optimizer: the desired final layout comes from the absolute policy. The named gap cases intentionally omit an inverse and should illustrate naive behavior only, not count as evidence against gap-based direct manipulation.
+
+The recorded totals, 37,134 absolute-coordinate changes versus 61,371 gap changes, exclude latent-intent equivalence, bytes, comments, identities, transactions, secondary geometry and histories. An absolute edit leaves displaced followers' authored y unchanged; the gap inverse rewrites them to encode resolved positions. Count logical preserved intent, visible displacement and serialized changes separately. Also remove unused y fields from the conceptual gap representation when estimating storage; `encodeGaps` currently retains them through object spread even though `gaps` ignores/overwrites them.
+
+The enumerator covers nonnegative integer tops on a ten-unit grid, three rows, fixed minimum separation, and five deltas. The third height varies but constrains no successor, so the count contains geometrically equivalent positioning cases. This does not invalidate the result; it limits the diversity implied by the headline number. Negative/fractional/extreme coordinates, variable per-kind clearances, mixed resize/move sequences, preexisting conflicts, simultaneous branches, nested frames and route geometry are absent. The elapsed time includes assertions and allocations; it is not a renderer performance measurement.
+
+### 4. Important absent lifecycle/source cases
+
+The isolated source-reorder and delete examples change array order/membership but test no cleanup or diagnostics. Missing are: repeated source reorder; deleting a displaced predecessor; insert between authored neighbors; rename/content growth; reparent between operands; reorder across call/reply or creation/deletion constraints; hidden records; reset one override; two saved views; first-edit identity capture; undo/redo; and comments keyed by typed addresses. Frame anchors need header/operand containment, while self calls need both send and receive geometry consumed by activation logic. These are specification gates, not reasons to expand the toy to thousands more similar rows.
+
+## Bounded next experiment
+
+First add a small history table to the isolated experiment: conflict then zero-distance drag, move away/back, resize away/back, delete predecessor, and source reorder/reverse. Assert authored records and displayed positions separately. Use a tiny exhaustive feasible-layout oracle with a declared lexicographic objective (selected target error, predecessor changes, other displacement, then record changes) to check a few cases without duplicating the forward recurrence. The objective itself remains a policy proposal to review. Run both candidate representations through their own repeated histories rather than deriving every gap state from an absolute preview.
+
+Then stop scaling the toy and make **one real-model renderer experiment**, isolated from the production schema:
+
+1. Parse a real minimal Arcadia scenario through the existing parser: two lifelines, separate call/reply occurrences using one exchange, and an action/state box between them. Use an experimental presentation adapter in a test boundary consumed by the actual Scene geometry; do not relocate the entire renderer or invent production syntax yet.
+2. Exercise call movement that displaces the box/reply, zero-motion on the displaced box, movement back, and box-height changes. Record independent numeric anchor expectations and compare actual rendered bounds/line endpoints. Execute a valid source/SetSteps reorder of the independent box and confirm the semantic order, model validation and presentation diagnostic. The semantic Project must remain unchanged during cosmetic previews.
+3. Extend that same bounded fixture with one nested operand and a self-message, then a delayed-created lifeline case. Assert send/receive anchors, header attachment, frame containment and child authored-coordinate preservation against the actual Scene/lifecycle outputs. Coordinate with #16 and #21 owners; do not duplicate or replace their implementation.
+4. Compare absolute and gap adapters on those identical requested layouts and histories. Capture unmet constraints explicitly; do not auto-normalize source or silently reorder behavior. Select the candidate only after defining its conflict and inverse behavior.
+
+This next experiment can validate real semantic/geometry integration without pretending to prove persistence. Once it passes, the next separate slice is the smallest versioned typed-layout record through parser/formatter, Document transaction, JSON/REST and reopen. Native editing and usability remain subsequent required evidence. Publish the exact experiment source, inputs and results together with this review so remote peers can reproduce the bounded claims.

harness/experiments/behavior-layout-policy-20260912/negative-zero-motion-result.json

@@ -0,0 +1,29 @@
+{
+  "status": "expected assertion failure reproduced",
+  "assertion": "zero-distance pointer operation must preserve authored intent\n+ actual - expected\n... Skipped lines\n\n  [\n    {\n      height: 20,\n      id: 'A',\n      y: 250\n...\n      id: 'B',\n+     y: 280\n-     y: 200\n    }\n  ]\n",
+  "actual": [
+    {
+      "id": "A",
+      "y": 250,
+      "height": 20
+    },
+    {
+      "id": "B",
+      "y": 280,
+      "height": 20
+    }
+  ],
+  "expected": [
+    {
+      "id": "A",
+      "y": 250,
+      "height": 20
+    },
+    {
+      "id": "B",
+      "y": 200,
+      "height": 20
+    }
+  ],
+  "scope": "Same toy planner, additional conflict-then-zero-motion history; no production failure claim."
+}

harness/experiments/behavior-layout-policy-20260912/negative-zero-motion.mjs

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+import { writeFile } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
+// Isolated policy comparison; these illustrative metrics are not Studio rules.
+const separation = 10;
+function absolute(rows) {
+  let end = -separation;
+  return rows.map(r => { const y = Math.max(r.y, end + separation); end=y+r.height; return {...r,y}; });
+}
+function gaps(rows) {
+  let end=0;
+  return rows.map((r,i) => { assert(r.gap >= (i?separation:0)); const y=end+r.gap; end=y+r.height; return {...r,y}; });
+}
+function encodeGaps(rows) {
+  return rows.map((r,i)=>({...r,gap:r.y-(i?rows[i-1].y+rows[i-1].height:0)}));
+}
+const positions = rows=>rows.map(r=>r.y);
+function moveAbsolute(rows,index,requested) {
+  const current=absolute(rows);
+  const floor=index?current[index-1].y+current[index-1].height+separation:0;
+  const candidate=rows.map((r,i)=>({...r,y:i===index?Math.max(requested,floor):r.y}));
+  return {candidate,preview:absolute(candidate)};
+}
+function changeCount(before,after,key) {return before.reduce((n,r,i)=>n+(r[key]!==after[i][key]),0);}
+const initial=[{id:'A',y:100,height:20},{id:'B',y:200,height:20}];
+const initialG=encodeGaps(initial);
+const cases=[];
+function named(name,a,g,expectedA,expectedG) {
+  assert.deepEqual(positions(a),expectedA,name+' absolute');
+  assert.deepEqual(positions(g),expectedG,name+' gaps');
+  cases.push({name,absolute:positions(a),gapsWithoutInverse:positions(g)});
+}
+named('move A to50',absolute([{...initial[0],y:50},initial[1]]),gaps([{...initialG[0],gap:50},initialG[1]]),[50,200],[50,150]);
+named('move A to250',absolute([{...initial[0],y:250},initial[1]]),gaps([{...initialG[0],gap:250},initialG[1]]),[250,280],[250,350]);
+named('resize A to80',absolute([{...initial[0],height:80},initial[1]]),gaps([{...initialG[0],height:80},initialG[1]]),[100,200],[100,260]);
+named('resize A to120',absolute([{...initial[0],height:120},initial[1]]),gaps([{...initialG[0],height:120},initialG[1]]),[100,230],[100,300]);
+named('source reorder B A',absolute([initial[1],initial[0]]),gaps([initialG[1],initialG[0]]),[200,230],[80,200]);
+named('delete A',absolute([initial[1]]),gaps([initialG[1]]),[200],[80]);
+assert.deepEqual(positions(moveAbsolute(initial,1,110).preview),[100,130]);
+let feasible=0,moves=0,absoluteChanges=0,gapChanges=0;
+const started=performance.now();
+for(const ha of [10,20,30])for(const hb of [10,20,30])for(const hc of [10,20,30])
+for(let a=0;a<=40;a+=10)for(let b=a+ha+10;b<=90;b+=10)for(let c=b+hb+10;c<=140;c+=10) {
+  const rows=[{id:'A',height:ha,y:a},{id:'B',height:hb,y:b},{id:'C',height:hc,y:c}];
+  assert.deepEqual(positions(absolute(rows)),[a,b,c]);
+  assert.deepEqual(positions(gaps(encodeGaps(rows))),[a,b,c]);
+  feasible++;
+  for(let i=0;i<3;i++)for(const delta of [-50,-20,0,10,40]) {
+    const requested=rows[i].y+delta, {candidate,preview}=moveAbsolute(rows,i,requested);
+    const independent=[];
+    for(let j=0;j<3;j++) {
+      const floor=j?independent[j-1]+rows[j-1].height+10:0;
+      independent.push(Math.max(j===i?requested:rows[j].y,floor));
+    }
+    assert.deepEqual(positions(preview),independent);
+    assert.deepEqual(positions(absolute(preview)),independent);
+    assert.deepEqual(positions(absolute(JSON.parse(JSON.stringify(candidate)))),independent);
+    const encoded=encodeGaps(preview);
+    assert.deepEqual(positions(gaps(encoded)),independent);
+    assert.deepEqual(candidate.map(r=>r.id),['A','B','C']);
+    for(let j=0;j<i;j++) assert.deepEqual(candidate[j],rows[j]);
+    absoluteChanges+=changeCount(rows,candidate,'y');
+    gapChanges+=changeCount(encodeGaps(rows),encoded,'gap');
+    moves++;
+  }
+}
+// Independent event/frame attachment probes: no actual Scene/activation engine.
+const selfCall=absolute([{id:'call',y:250,height:24},{id:'reply',y:320,height:0}]);
+assert.equal(selfCall[0].y+24,274);
+assert.equal(selfCall[1].y,320);
+const children=[{y:160,height:20},{y:260,height:20}];
+const requiredFrameBottom=Math.max(...children.map(r=>r.y+r.height))+20;
+assert.equal(requiredFrameBottom,300);
+assert.equal(Math.max(300,requiredFrameBottom),300);
+assert.equal(Math.max(220,requiredFrameBottom),300);
+assert.deepEqual(children,[{y:160,height:20},{y:260,height:20}]);
+assert.equal(220-90,130); // delayed header top from moved create receive and header height
+const conflicting = moveAbsolute(initial,0,250);
+const zeroMotion = moveAbsolute(conflicting.candidate,1,conflicting.preview[1].y);
+assert.deepEqual(zeroMotion.candidate, conflicting.candidate, 'zero-distance pointer operation must preserve authored intent');
+const result={
+  scope:'Illustrative linear policy and anchor experiment; no production parser, REST, Scene, GUI or full fragment/lifecycle acceptance.',
+  separation, cases, feasibleLayouts:feasible, moveCases:moves,
+  changedAuthoredCoordinateRecords:{absolute:absoluteChanges,gapsWithInverse:gapChanges},
+  elapsedMs:performance.now()-started,
+  assertions:'passed',
+  interpretation:'Both policies express all enumerated feasible layouts. Absolute coordinates preserve unaffected positions with fewer authored coordinate changes under these fixtures. Choose no production schema from this alone; full scope/anchor/inverse and source lifecycle validation remain required.'
+};
+await writeFile(new URL('./results.json',import.meta.url),JSON.stringify(result,null,2)+'\n',{flag:'wx'});
+export default result;

harness/experiments/behavior-layout-policy-20260912/results.json

@@ -0,0 +1,79 @@
+{
+  "scope": "Illustrative linear policy and anchor experiment; no production parser, REST, Scene, GUI or full fragment/lifecycle acceptance.",
+  "separation": 10,
+  "cases": [
+    {
+      "name": "move A to50",
+      "absolute": [
+        50,
+        200
+      ],
+      "gapsWithoutInverse": [
+        50,
+        150
+      ]
+    },
+    {
+      "name": "move A to250",
+      "absolute": [
+        250,
+        280
+      ],
+      "gapsWithoutInverse": [
+        250,
+        350
+      ]
+    },
+    {
+      "name": "resize A to80",
+      "absolute": [
+        100,
+        200
+      ],
+      "gapsWithoutInverse": [
+        100,
+        260
+      ]
+    },
+    {
+      "name": "resize A to120",
+      "absolute": [
+        100,
+        230
+      ],
+      "gapsWithoutInverse": [
+        100,
+        300
+      ]
+    },
+    {
+      "name": "source reorder B A",
+      "absolute": [
+        200,
+        230
+      ],
+      "gapsWithoutInverse": [
+        80,
+        200
+      ]
+    },
+    {
+      "name": "delete A",
+      "absolute": [
+        200
+      ],
+      "gapsWithoutInverse": [
+        80
+      ]
+    }
+  ],
+  "feasibleLayouts": 3555,
+  "moveCases": 53325,
+  "changedAuthoredCoordinateRecords": {
+    "absolute": 37134,
+    "gapsWithInverse": 61371
+  },
+  "elapsedMs": 24777.856600000057,
+  "assertions": "passed",
+  "interpretation": "Both policies express all enumerated feasible layouts. Absolute coordinates preserve unaffected positions with fewer authored coordinate changes under these fixtures. Choose no production schema from this alone; full scope/anchor/inverse and source lifecycle validation remain required."
+}