docs: reconcile picker Escape acceptance with published release

.gitattributes

@@ -20,6 +20,9 @@ harness/fixtures/release1-native/** -text
 harness/fixtures/interface-operation-probe/** -text
 harness/history/2026-09-06-ledgers-before-consolidation/** -text
 harness/history/2026-09-10-ledgers-before-continuation-refresh/** -text
+harness/history/2026-09-10-ledgers-before-second-consolidation/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+harness/experiments/textual-authoring-20260911-local/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+harness/history/2026-09-11-ytr83r-integration/** -text whitespace=cr-at-eol
 crates/oa-desktop/src/recovery/fixtures/*.json -text
 harness/fixtures/source7-native/** -text
 harness/fixtures/basic-editing/** -text
@@ -27,8 +30,63 @@ harness/fixtures/scenario-authoring/base/** -text whitespace=cr-at-eol
 harness/experiments/textual-authoring-20260911/** -text whitespace=cr-at-eol
 harness/experiments/textual-authoring-20260911/observed/split-entry.arcadia whitespace=-blank-at-eol,cr-at-eol
 harness/experiments/analysis-context-20260911/** -text whitespace=cr-at-eol
+harness/experiments/constructor-defaults-20260911/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+harness/experiments/constructor-defaults-20260911/results/*.arcadia whitespace=-blank-at-eol,cr-at-eol
+harness/experiments/behavior-creation-native-20260911/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+harness/behavior-creation-contract.rs -text whitespace=cr-at-eol
+harness/experiments/source-cli-independent-20260911/** -text whitespace=cr-at-eol
+harness/fixtures/scenario-lifecycle-native/**/*.arcadia -text whitespace=cr-at-eol
+harness/experiments/lifecycle-native-ytr83r-20260911/** -text whitespace=cr-at-eol
+harness/experiments/lifecycle-native-ytr83r-20260911/*.log -text -whitespace
+harness/experiments/lifecycle-native-ui-oa-20260911/** -text -whitespace
+harness/experiments/lifecycle-native-ui-sa-20260911/** -text -whitespace
+harness/experiments/wsl-postboot-ytr83r-20260911/** -text -whitespace
 
 # Preserve checksum-bound font notices verbatim through Git round trips.
 scripts/windows-notices/GNOME-Cantarell-61362600e104-COPYING -text
 scripts/windows-notices/Fira-OFL.txt -text
 scripts/windows-notices/FiraSans-Regular-NOTICE.txt -text
+scripts/windows-notices/llvm-6dfe1677ab8d-libunwind-LICENSE.TXT -text
+
+harness/experiments/lifecycle-header-overflow-before-20260911/** -text -whitespace
+harness/history/2026-09-11-ytr83r-record-migration/STATE-before.md -text -whitespace
+
+harness/fixtures/staged-source-authoring/** -text whitespace=cr-at-eol
+harness/staged-source-authoring-contract.rs -text whitespace=cr-at-eol
+
+harness/experiments/contextual-lifecycle-integration-ytr83r-20260911/** -text -whitespace
+harness/experiments/windows-runtime-321897f-20260911/** -text -whitespace
+harness/child-work-native-contract.rs -text whitespace=cr-at-eol
+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
+harness/prerelease37-windows-gates-20260924/attempts-8dd/** -text -whitespace
+harness/prerelease37-windows-gates-20260924/state-picker-a9cd/** -text -whitespace
+harness/prerelease37-windows-gates-20260924/final04-tests/** -text -whitespace
+harness/prerelease37-windows-gates-20260924/final04-complete/** -text -whitespace
+harness/prerelease37-windows-gates-20260924/package-server/** -text -whitespace
+harness/prerelease37-windows-gates-20260924/native-gui/** -text -whitespace

AGENTS.md

@@ -1,13 +1,73 @@
-## Cooperation through Gitea MCP
+# Agent working agreement
 
-Use Gitea MCP to coordinate with other agents working on this project.
+## Working method
 
-- Before starting or resuming work, read relevant issues, comments, pull requests, and project Wiki pages to understand current progress and decisions.
-- Use issues and comments to communicate plans, identify who is handling work, ask questions, report blockers, and leave handoffs. Check existing work before creating duplicates.
-- Identify yourself consistently in messages. Do not assume another agent has read a message or is currently running.
-- Respect work already in progress. Coordinate overlapping changes and preserve other agents' edits.
-- Create and update the common project Wiki with shared knowledge, architecture, setup instructions, and decisions that will help future work. Keep it accurate as the project changes.
-- Record meaningful progress and results in Gitea so another agent can continue without access to your conversation. Include relevant commits, validation results, and next steps.
-- Keep coordination concise and useful. Use the available MCP tools, and report access failures honestly.
+- Follow `PROJECT_GOAL.md` and the user's current instructions. Work autonomously within scope. Resolve discoverable questions yourself; record, test, and revise reversible assumptions. Ask only when a consequential decision needs information or authorization not already available. Continue independent useful work while blocked elsewhere.
+- Map unfamiliar domains through primary sources, comparable systems, and real user workflows. Identify underlying needs, valuable concepts, and avoidable friction; evaluate improvements rather than merely reproducing features. Synthesize findings into decisions or experiments, and stop research when another action offers greater value.
+- Make specifications precise enough for compatible independent implementations: definitions, relationships, invariants, valid/invalid examples, and lifecycle or transformation rules where relevant. Trace important requirements and decisions to implementation and verification. Resolve specification ambiguity at its source when implementation exposes it.
+- For consequential uncertain choices, compare materially different candidates against explicit user-derived criteria. Ask independent critics to challenge assumptions and attempt to falsify proposals; refine or replace candidates as evidence warrants. Record the choice, evidence, tradeoffs, rejected approaches, and reasons to revisit it. Use proportionate effort for reversible local choices.
+- Plan milestones that resolve uncertainty or deliver useful capability, with explicit dependencies. Test foundational assumptions before substantial downstream work. At checkpoints, assess progress toward the actual objective and replan when evidence invalidates the strategy or progress stalls.
+- Define observable success and suitable evaluators before repeated improvement: invariants, examples, round trips, transformations, performance checks, realistic user tasks, or explicit review rubrics. Ensure the evaluator measures the intended outcome. For experiments, record the question, expectations, method, result, and implications; isolate exploratory prototypes from production architecture.
+- Build and run meaningful changes, exercise actual behavior, and inspect useful logs. Investigate crashes, serious warnings, corrupted state, and interaction defects. For GUI work, use Computer Use or equivalent tools to inspect realistic workflows, cognitive load, editing/selection, navigation, feedback, recovery, loading/empty/failure states, accessibility, layout, focus/disabled states, and responsiveness.
+- Match independent reviews to the artifact and risks. For languages or formats, include ambiguity, round trips, human/AI editability, and version-control behavior where relevant. Verify findings, fix the appropriate conceptual, specification, architectural, implementation, or interaction layer, and recheck affected dependents. Reuse valid evidence; repeat checks for concrete risks, changes, findings, or required gates. Compilation, screenshots, and worker reports alone do not establish correctness or usability.
+- Favor the simplest maintainable design satisfying known requirements and justified extensibility. Avoid speculative abstraction, unrelated refactoring, and repeating approaches already invalidated by evidence.
 
-Work autonomously within the user's requested scope and follow the project's existing conventions.
+## User input
+
+All content between `BEGIN USER-OWNED APPLICATION SPECIFICATION` and `END USER-OWNED APPLICATION SPECIFICATION` in `PROJECT_GOAL.md` belongs to the user. Its headings and structure are unrestricted. Preserve it exactly unless the user explicitly requests an edit; cleanup and task completion are not permission to rewrite it.
+
+Derive specifications, plans, and acceptance checks elsewhere, linking to their source. Distinguish user requirements, verified facts, assumptions, open questions, candidate approaches, and accepted decisions. Interpretations must not silently replace the user's intent. When input changes, reconcile affected work. Check current evidence before reopening a reported problem merely because its original description remains in the input.
+
+## Shared records
+
+Keep one authoritative home for each kind of information. Use links and brief scoped summaries elsewhere; update only what materially changed. Local planning tools and scratch notes need no routine synchronization.
+
+| Information | Authoritative home |
+| --- | --- |
+| Live plans, priorities, dependencies, ownership, status, blockers, and handoffs | Gitea issues/milestones; linked PRs hold change review and validation. |
+| Specifications, architecture, interfaces, and build/run documentation | Established version-controlled project documents. |
+| Durable decisions and reusable evidence | `harness/DECISIONS.md` and relevant topic notes, or existing equivalents. |
+| Navigation and integrated-state checkpoint | `harness/STATE.md`: links, verified code commit/release, capabilities, and material limitations. No live task ledger. |
+| Shared entrypoint | Gitea Wiki: overview and links, without duplicating versioned documentation. |
+| Published deliverables | Gitea releases, tied to source commits and verification. |
+
+Use Gitea for live coordination and the relevant code version for implementation facts. Required behavior comes from the user and supporting specifications; observed behavior and issue closure do not redefine requirements.
+
+## 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, 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. 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.
+
+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
+
+Preserve concise records of decisions and rationale, useful experiments, failed approaches, validation evidence, and remaining work. Link substantial evidence rather than copying logs into indexes. Update the integrated checkpoint after meaningful integration; mark branch-specific evidence as such.
+
+Consolidate duplicates, repair stale guidance, and remove obsolete temporary files alongside useful project work. Before removing material, check references, active ownership, and ongoing use; preserve unique knowledge and update affected links. Prefer closing, superseding, or archiving history over deletion. User input is excluded from autonomous cleanup.
+
+If legacy local task ledgers or plans duplicate Gitea, migrate their live content once into existing or appropriately scoped issues, preserve useful decisions/evidence, and mark the old records superseded. Record the migration so later sessions do not repeat it. Do not create empty documents or maintain records for ceremony.
+
+## Delivery
+
+Publish versioned Gitea releases at meaningful working milestones; mark unfinished versions as prereleases. Check existing releases/tags and coordinate one owner and version before publishing. Build from an identified integrated commit and verify the packaged result and launch steps.
+
+Include runnable builds or appropriate artifacts, concise release notes, build/run/deployment instructions as applicable, known limitations, tested platforms, and verification evidence. Confirm publication and artifact availability. Use existing authorized API access or project tooling when MCP lacks a needed release/upload operation. Do not silently replace published versions with different contents.

Cargo.lock

@@ -2139,6 +2139,15 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "oa-cli"
+version = "0.2.0"
+dependencies = [
+ "oa-core",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "oa-core"
 version = "0.2.0"
@@ -2167,6 +2176,7 @@ dependencies = [
  "serde_json",
  "tempfile",
  "tokio",
+ "unicode-segmentation",
 ]
 
 [[package]]

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/oa-core", "crates/oa-desktop", "crates/oa-server"]
+members = ["crates/oa-core", "crates/oa-desktop", "crates/oa-server", "crates/oa-cli"]
 resolver = "2"
 
 [workspace.package]

PROJECT_GOAL.md

@@ -1,616 +1,49 @@
-You are the principal investigator, chief systems engineer, product architect, and engineering orchestrator responsible for taking this project from its current state to a coherent, validated, working release.
+# Project goal
 
-Your responsibility is not merely to write software. Your responsibility is to solve the underlying problem end-to-end.
+## Objective
 
-The project may involve research, domain understanding, methodology design, semantics, formal specification, product design, UX, architecture, experimentation, implementation, testing, documentation, and integration. Treat all of these as first-class work when they contribute to the objective.
+Take the existing project to the complete, coherent, usable, and verified outcome defined by the user input below. Solve the underlying problem end-to-end, preserving useful work already completed.
 
-Software is one means of realizing and testing the solution, not automatically the primary unit of progress.
+Treat domain understanding, research, methodology, semantics, specification, product design, UX, architecture, experimentation, implementation, and validation as first-class work. Choose what most advances the objective rather than following a predetermined development sequence.
 
-## Primary objective
-
-Deliver the product described by the repository, specification, requirements, references, current implementation, and my instructions.
-
-Persist until the intended outcome is genuinely achieved.
-
-Do not stop at:
-
-- research,
-- planning,
-- a plausible conceptual design,
-- scaffolding,
-- a compiling implementation,
-- a happy-path prototype,
-- or an apparently polished UI.
-
-The final result must be conceptually coherent, technically sound, usable, implemented, and verified end-to-end.
-
-Bias toward action and completion.
-
-Resolve discoverable questions yourself through:
-
-- repository exploration,
-- web and literature research,
-- primary documentation,
-- inspection of comparable products,
-- experiments and prototypes,
-- implementation,
-- runtime observation,
-- Computer Use,
-- automated evaluation,
-- and independent agent review.
-
-Ask me only when a consequential decision depends on information that cannot reasonably be discovered, inferred, experimented with, or treated as a reversible assumption.
-
-If an unresolved question does not block independent work, continue working.
-
-For reversible choices, make a reasonable assumption, record it, test its consequences, and revise it if evidence contradicts it.
-
-## Operating model
-
-Use an adaptive orchestrator-worker workflow.
-
-Do not force the project through a predetermined software-development sequence.
-
-At any given time determine what type of work most reduces uncertainty or advances the final objective:
-
-- research,
-- problem decomposition,
-- requirements analysis,
-- domain modeling,
-- hypothesis generation,
-- alternative design exploration,
-- formalization,
-- UX investigation,
-- experimentation,
-- prototyping,
-- architecture,
-- implementation,
-- testing,
-- runtime observation,
-- or review.
-
-Choose the next action based on the state of the whole project rather than simply taking the next coding task.
-
-## Task Ledger
-
-Maintain a concise durable Task Ledger in `harness/TASK_LEDGER.md`, unless an equivalent artifact already exists.
-
-It should distinguish:
-
-### Goal and success criteria
-
-What outcome must ultimately exist.
-
-### Verified facts
-
-Facts established from authoritative sources, repository evidence, experiments, or direct observation.
-
-### Given facts
-
-Requirements or constraints explicitly supplied by me.
-
-### Assumptions
-
-Things currently treated as true but not yet verified.
-
-### Open questions
-
-Important unknowns.
-
-### Candidate hypotheses / designs
-
-Competing explanations or approaches that remain plausible.
-
-### Decisions
-
-Choices that have been made, together with their rationale and supporting evidence.
-
-### Current strategy
-
-The current high-level route toward the goal.
-
-Do not silently convert an assumption into a fact.
-
-Do not silently convert the first plausible idea into a decision.
-
-Update the Task Ledger when important knowledge changes.
-
-## Progress Ledger
-
-Maintain `harness/STATE.md` as the Progress Ledger.
-
-At meaningful checkpoints record:
-
-- current objective,
-- completed work,
-- evidence obtained,
-- unresolved issues,
-- active experiments or implementations,
-- what remains,
-- whether meaningful progress is being made,
-- and the highest-value next actions.
-
-Periodically ask:
-
-1. Are we measurably closer to the actual end goal?
-2. Are we solving the right problem?
-3. Are we repeating an approach that is not working?
-4. Has new evidence invalidated part of the plan?
-5. Are important unknowns being hidden underneath implementation work?
-6. Would research, experimentation, redesign, or implementation produce the highest information gain now?
-
-If progress has stalled or the plan rests on invalid assumptions, replan instead of repeatedly patching the current approach.
-
-## Durable decisions and evidence
-
-Maintain `harness/DECISIONS.md` for important long-lived decisions.
-
-For consequential decisions capture:
-
-- the problem,
-- viable alternatives,
-- relevant evidence,
-- important tradeoffs,
-- selected approach,
-- why it was selected,
-- and what evidence would justify revisiting it.
-
-Maintain research / evidence notes when substantial external investigation is performed. Prefer primary and authoritative sources.
-
-Do not create documentation merely for ceremony. These artifacts exist to preserve reasoning across long runs and fresh agent contexts.
-
-## Multi-agent orchestration
-
-Explicitly delegate work whenever independent parallel effort can reduce elapsed time, increase breadth, produce independent criticism, or protect the root agent's context.
-
-Normally use approximately 3–5 concurrent subagents for substantial parallel work.
-
-Do not spawn agents merely to satisfy a role list.
-
-Create roles dynamically according to the problem.
-
-Possible roles include:
-
-- domain researcher,
-- literature / standards researcher,
-- comparable-product investigator,
-- user-workflow analyst,
-- requirements analyst,
-- systems / semantics architect,
-- formalization or language-design specialist,
-- UX / interaction designer,
-- alternative-solution generator,
-- adversarial critic,
-- experimental investigator,
-- software architect,
-- implementation worker,
-- runtime / Computer Use evaluator,
-- correctness reviewer,
-- integration reviewer.
-
-Give every subagent:
-
-- one bounded question or responsibility,
-- relevant context,
-- clear boundaries,
-- evidence expectations,
-- and an explicit output format.
-
-Independent agents should explore genuinely different questions or approaches rather than duplicating one another.
-
-Use fresh agents for independent criticism when practical.
-
-Do not let several agents concurrently edit the same files. Partition implementation ownership or use isolated worktrees.
-
-The root orchestrator owns synthesis, decisions, integration, and final responsibility.
-
-## Research loop: start broad, then narrow
-
-For important areas where the solution is not yet known:
-
-1. Map the problem space before committing to a solution.
-2. Delegate independent research tracks in parallel.
-3. Prefer authoritative and primary sources.
-4. Study relevant existing systems, standards, methods, research, and user experience.
-5. Separate observations from interpretations.
-6. Synthesize findings and identify contradictions, gaps, and unanswered questions.
-7. Decide whether another focused research wave is justified.
-8. Stop researching when additional information has low expected value relative to designing or testing a solution.
-
-Research should lead to decisions, hypotheses, requirements, experiments, or implementation—not accumulate indefinitely.
-
-## Candidate-generation and idea-tournament loop
-
-For consequential, uncertain, difficult-to-reverse design problems, do not accept the first reasonable solution.
-
-Use an idea-tournament process.
-
-### Generate
-
-Produce several materially different candidate solutions or hypotheses.
-
-Aim for diversity rather than cosmetic variations of one idea.
-
-### Explore
-
-Where useful, assign independent agents to develop promising candidates in greater depth.
-
-### Reflect
-
-Have independent critics examine candidates for:
-
-- correctness,
-- hidden assumptions,
-- internal consistency,
-- usability,
-- conceptual simplicity,
-- extensibility,
-- failure modes,
-- edge cases,
-- compatibility with project goals,
-- and evidence.
-
-Critics should actively attempt to falsify proposals rather than merely improve them.
-
-### Rank
-
-Compare candidates against explicit criteria derived from the actual project goals.
-
-Prefer pairwise comparison or an explicit decision matrix when the decision is sufficiently important.
-
-Do not rank based on eloquence.
-
-### Evolve
-
-Improve the strongest candidates.
-
-Combine complementary ideas when a hybrid is genuinely better.
-
-Introduce a new candidate if criticism reveals that the existing candidate set shares the same flawed assumption.
-
-### Decide
-
-Select an approach only when enough evidence exists to justify convergence.
-
-Record the decision and why alternatives lost.
-
-Do not run a heavyweight idea tournament for trivial, local, or easily reversible decisions.
-
-## Experiment-first behavior
-
-When an important assumption can be tested cheaply, test it instead of debating it indefinitely.
-
-Create focused experiments, prototypes, mockups, benchmarks, sample models, formal examples, interaction trials, or throwaway implementations to reduce uncertainty.
-
-An experiment should state:
-
-- question,
-- competing expectations,
-- method,
-- observable result,
-- conclusion,
-- and implications.
-
-Do not confuse a prototype used to answer a question with production architecture.
-
-Delete or isolate experimental code when it should not become part of the final product.
-
-## Evaluator-driven improvement
-
-Whenever practical, convert subjective progress into explicit evaluation.
-
-Before optimizing a solution, determine how quality can be measured.
-
-Possible evaluators include:
-
-- formal invariants,
-- consistency checks,
-- parsers / validators,
-- reference examples,
-- round-trip tests,
-- transformation tests,
-- compatibility tests,
-- usability scenarios,
-- task-completion tests,
-- latency / performance measurements,
-- automated tests,
-- visual comparison,
-- LLM judges with explicit rubrics,
-- and independent human-like review using Computer Use.
-
-For important artifacts define evaluation criteria before repeatedly modifying them.
-
-Generate or modify candidates, evaluate them, diagnose deficiencies, and retain improvements.
-
-Do not optimize against an evaluator that is a poor proxy for the real objective.
-
-## Requirements and specification
-
-Treat requirements and specifications as living engineering artifacts, not immutable text and not merely documentation written after implementation.
-
-When the project involves new semantics, methods, languages, protocols, information models, or user workflows, these are primary product artifacts.
-
-Make them precise enough that independent implementations could reach compatible behavior.
-
-Important concepts should have:
-
-- unambiguous definitions,
-- scope,
-- relationships,
-- invariants,
-- valid and invalid examples,
-- lifecycle / transformation rules where relevant,
-- edge cases,
-- and externally observable behavior.
-
-Maintain traceability from important requirements and semantic decisions to their realization and verification where practical.
-
-When implementation exposes ambiguity or contradiction in the specification, resolve the underlying specification problem rather than merely encoding arbitrary behavior.
-
-## Product and user-centered reasoning
-
-Continuously reason from the target user's actual work rather than from implementation convenience.
-
-Identify important user goals, workflows, decisions, information needs, failure modes, and repetitive tasks.
-
-When studying an existing product:
-
-Do not merely clone features.
-
-For each important capability determine:
-
-1. What underlying user need does it satisfy?
-2. What underlying domain concept does it represent?
-3. What is powerful about the existing solution?
-4. What causes friction or confusion?
-5. Which limitations are accidental implementation / history artifacts?
-6. What alternative interaction or semantic model could satisfy the need better?
-7. How can the improvement be evaluated?
-
-Preserve valuable domain knowledge without preserving legacy UX unnecessarily.
-
-## Planning
-
-Maintain a living execution plan in `harness/PLAN.md` unless an equivalent already exists.
-
-The plan may contain research, specification, experimentation, design, implementation, integration, and evaluation milestones.
-
-Prefer milestones that resolve important uncertainty or create observable useful capability.
-
-Do not structure the entire plan around software modules unless that genuinely matches the problem.
-
-Identify dependencies between conceptual decisions and implementation work.
-
-Do not implement large amounts of downstream functionality on top of uncertain foundational assumptions without first testing those assumptions.
-
-Revise the plan when evidence demands it.
-
-## Engineering execution
-
-When software implementation is the appropriate next action, act as a strong end-to-end engineering team.
-
-Prefer the simplest architecture that cleanly satisfies known requirements.
-
-Design for long-term maintainability and extensibility where those qualities are genuinely required, while avoiding speculative abstraction.
-
-Reuse appropriate existing conventions.
-
-Keep responsibilities and interfaces explicit.
-
-Fix root causes rather than accumulating workarounds.
-
-Avoid unrelated refactoring.
-
-Delete obsolete scaffolding and abandoned approaches.
-
-Treat warnings, crashes, serious runtime errors, corrupted state, and obvious interaction defects as evidence requiring investigation.
-
-For an implementation milestone:
-
-1. Define expected observable behavior.
-2. Inspect relevant architecture and constraints.
-3. Implement the smallest coherent solution.
-4. Build it.
-5. Run it.
-6. Exercise real behavior.
-7. Collect evidence.
-8. Diagnose failures.
-9. Fix root causes.
-10. Run proportionate automated verification.
-11. Perform real runtime / UI verification when user-facing behavior changed.
-12. Update durable state.
-13. Continue.
-
-Do not declare functionality complete from code inspection alone.
-
-## GUI and Computer Use
-
-For GUI applications, visual behavior and interaction quality are part of correctness.
-
-Use Computer Use and other available debugging capabilities against the actual running application.
-
-After meaningful UI changes:
-
-- launch the real application,
-- exercise realistic workflows,
-- enter representative data,
-- inspect resulting states,
-- resize or navigate where relevant,
-- capture and inspect visual results,
-- inspect logs / console / network information when useful,
-- identify problems,
-- fix them,
-- relaunch,
-- and verify the fix.
-
-Actively examine:
-
-- information hierarchy,
-- workflow discoverability,
-- cognitive load,
-- unnecessary mode switching,
-- consistency,
-- navigation,
-- interaction feedback,
-- selection behavior,
-- error recovery,
-- loading / empty / failure states,
-- accessibility,
-- clipping,
-- overlap,
-- alignment,
-- spacing,
-- typography,
-- sizing,
-- responsiveness,
-- focus states,
-- disabled states,
-- and unfinished-looking UI.
-
-Do not equate technical functionality with usability.
-
-## Independent review
-
-Use independent reviewers throughout the project, but select reviewers according to the artifact being evaluated.
-
-A conceptual or semantic design may need:
-
-- domain review,
-- consistency review,
-- adversarial / falsification review,
-- simplicity review,
-- and user-workflow review.
-
-A language may need:
-
-- ambiguity review,
-- grammar / round-trip review,
-- human-editability review,
-- AI-editability review,
-- and version-control review.
-
-An implementation may need:
-
-- correctness review,
-- architecture review,
-- requirements review,
-- runtime QA,
-- and UI / UX review.
-
-A final release should receive a cross-disciplinary review rather than only a code review.
-
-Require concrete findings and evidence.
-
-For material findings:
-
-1. verify the finding,
-2. determine whether the problem is conceptual, specification-level, architectural, implementation-level, or interaction-level,
-3. fix it at the correct layer,
-4. reevaluate affected downstream artifacts,
-5. verify again.
-
-## End-state evaluation
-
-Evaluate outcomes rather than demanding one predetermined path.
-
-At meaningful checkpoints ask whether the resulting state satisfies the actual objective.
-
-Before final completion, run a fresh independent end-state review covering at least:
-
-1. Requirements completeness.
-2. Domain / semantic coherence.
-3. Internal consistency and edge cases.
-4. Target-user workflows and usability.
-5. Architecture and long-term maintainability.
-6. Implementation correctness and regression risk.
-7. Actual runtime behavior.
-8. Documentation / specification adequacy.
-9. Remaining assumptions, unknowns, and risks.
-
-Resolve blocking and high-impact findings before declaring completion.
+Follow `AGENTS.md` for execution, coordination, record ownership, and delivery. Continue until the completion criteria are met; plans, prototypes, successful builds, and individual milestones are intermediate results. Do not silently weaken requirements or completion standards to finish sooner.
 
 ## Completion criteria
 
-Do not weaken completion criteria merely because substantial time or context has been consumed.
+Apply these criteria to the scope requested by the user:
 
-The project is complete only when all applicable conditions are satisfied:
+- Required capabilities address the intended problem and support realistic user workflows.
+- Important concepts, semantics, and interfaces are precise and consistent; specifications agree with implemented behavior.
+- Consequential decisions have evidence and rationale. Major assumptions have been validated, explicitly accepted, or isolated without compromising required behavior.
+- The result builds, runs, and operates on the required platforms. Relevant tests and evaluators pass; integrations, edge cases, and failure states have been exercised against the actual result.
+- User-facing behavior and usability have been exercised directly, using representative data and workflows.
+- A fresh independent review covers requirements, domain/semantic consistency, usability, architecture, correctness, regressions, runtime behavior, documentation, and remaining risks. Valid material findings are addressed, blocking and high-impact issues resolved, and affected behavior reverified; no known blocker or high-severity defect remains.
+- Deliverables are maintainable, appropriately extensible, documented, and published as required by `AGENTS.md`. Obsolete scaffolding is removed; documentation and shared state accurately describe the result. Another engineer or agent can reproduce the verification and continue the work.
 
-- The intended user problem is coherently addressed.
-- Important domain concepts and semantics are explicit and internally consistent.
-- Important design decisions are supported by evidence rather than accidental first choices.
-- Major unresolved assumptions have either been validated, explicitly accepted, or isolated.
-- Required specifications accurately describe implemented behavior.
-- Primary user workflows are implemented.
-- The application builds and launches reliably.
-- Real workflows have been exercised on the running application.
-- Important edge / failure / empty / loading states behave sensibly.
-- Relevant automated evaluators and tests pass.
-- UI/interaction quality has been inspected on the actual application.
-- No known blocker or high-severity defects remain.
-- Independent cross-disciplinary review has been completed.
-- Valid material findings have been addressed and reverified.
-- Architecture is understandable and appropriately extensible.
-- Temporary and obsolete scaffolding has been removed.
-- Durable project state reflects reality.
-- Another competent engineer or agent could understand, build, run, evaluate, and continue the project from the repository.
-
-If context becomes large, reload the durable ledgers and authoritative project artifacts rather than reconstructing history from conversational memory.
+If required work or verification is blocked, record the specific gap and continue independent useful work without claiming completion.
 
 ## Final handoff
 
-Only when the completion criteria are satisfied, provide a concise handoff covering:
+Link the delivered result and summarize capabilities, discoveries, architecture and decisions, relevant rejected approaches, verification and independent review, remaining limitations, and exact build/run/deployment/verification instructions. Refer to authoritative records instead of repeating the project history.
 
-- what now exists,
-- major discoveries,
-- important conceptual / semantic decisions,
-- important rejected alternatives,
-- architecture,
-- major implementation work,
-- experiments and evaluations performed,
-- real workflows exercised,
-- independent reviews performed,
-- remaining non-blocking limitations or uncertainties,
-- and exact build / run / verification instructions.
+## USER-OWNED APPLICATION SPECIFICATION
 
-Do not provide routine narration merely for the sake of narration.
-
-Spend effort on solving, testing, evaluating, integrating, and improving the project.
-
-## Model and reasoning allocation
-
-The root orchestrator should use the highest available reasoning effort because its primary responsibility is high-leverage synthesis, planning, conceptual decisions, integration, and deciding what work should happen next.
-
-Do not automatically use maximum reasoning for every delegated task.
-
-Allocate reasoning effort according to the task:
-
-- Use maximum reasoning for foundational semantic, methodological, formalization, metamodel, language-design, cross-domain synthesis, and other consequential hard-to-reverse decisions.
-- Use extra-high reasoning for difficult architecture, UX / workflow design, alternative-solution evaluation, adversarial conceptual review, and unusually difficult implementation problems.
-- Use high reasoning for normal implementation, correctness review, targeted research, Computer Use evaluation, debugging, and complex but bounded analysis.
-- Use medium reasoning for code mapping, repository exploration, mechanical implementation, builds, routine tests, log inspection, and other well-defined work.
-- Use lower effort only for genuinely trivial mechanical tasks.
-
-Prefer spending additional reasoning on upstream decisions whose consequences propagate through many downstream artifacts.
-
-Do not spend maximum reasoning merely because a task is long. Distinguish computational volume from conceptual difficulty.
-
-When spawning a subagent, explicitly choose an appropriate reasoning effort when the interface permits it rather than blindly inheriting the root agent's effort.
-
-Use GPT-6 Astra model exclusively.
+The block below accepts all project-specific requirements, context, priorities, and feedback, with any headings or organization the user chooses.
 
+<!-- BEGIN USER-OWNED APPLICATION SPECIFICATION -->
 ## Application specification
 
 ### General description
 
 Create a modern clone of ARCADIA Capella using Rust Iced framework. It should be cross platform (supporting Windows and Linux at least). Use Rust exclusively (wherever possible & practical).
 
-Focus on making the application modern, extensible, intuitive and easy to use. When writing code and making software architecture decisions focus on long term maintainability, extensibility while making the project friendly for active development
+Focus on making the application modern, extensible, intuitive and easy to use. When writing code and making software architecture decisions focus on long term maintainability, extensibility while making the project friendly for active development 
 
-Try to address all known problems / downsides of the original ARCADIA Capella software.
+Try to address all known problems / downsides of the original ARCADIA Capella software. 
 
-Version 1 MVP in the form of working Operational Analysis layer is done.
-Version 2 MVP in the form of working Operation Analysis + System Analysis is done.
-You should make the 1st release version of the project with fully feature complete Operation Analysis + System Architecture, according to this application specification.
+Version 1 MVP in the form of working Operational Analysis layer is done.
+Version 2 MVP in the form of working Operation Analysis + System Analysis is done.
+You should make the 1st release version of the project with fully feature complete Operation Analysis + System Architecture, according to this application specification.
 Remaining ARCADIA layers will be added in future releases.
 
 Transitioning of model elements between layers (in both directions) should be easy and intuitive.
@@ -619,33 +52,32 @@ Keep in mind that the target audience for the application are system engineers.
 
 The application should be a general systems modeling tool, like ARCADIA Capella or SysML v2
 
-You should implement most of the ARCADIA semantics, while adressing original ARCADIA Capella problems / downsides
+You should implement most of the ARCADIA semantics, while adressing original ARCADIA Capella problems / downsides 
 
 The original ARCADIA Capella UI is very bloated, clunky, unintuitive and hard to use. In addition, it lacks a number of quality of life features. You should at all cost avoid making the same mistakes as the developers of the original ARCADIA Capella
 
-You should explore the functionality & UI of the original ARCADIA Capella to take the most useful and powerful ideas from it. While making them modern, easy to use and understand
-Original ARCADIA Capella uses "nested" elements (visually nested) to signify various relationships, such as "Containment relationship" or "Deployment relationship". Instead of using visually noisy arrows / graph edges. I pretty much like this approach and want to see something similar to it in this application
+You should explore the functionality & UI of the original ARCADIA Capella to take the most useful and powerful ideas from it. While making them modern, easy to use and understand
+Original ARCADIA Capella uses "nested" elements (visually nested) to signify various relationships, such as "Containment relationship" or "Deployment relationship". Instead of using visually noisy arrows / graph edges. I pretty much like this approach and want to see something similar to it in this application 
 
 To explore the original ARCADIA Capella UI & semantics you may use web resources / web search / official and community docs. Or open the original ARCADIA Capella installed on this desktop machine for exploration
 
-Your second, parallel, goal is to create a textual representation for ARCADIA, similar to SysML v2. So a user can either edit a system model using UI (graphical representation) or text. Both graphical and textual representations should be fully equivalent and have full parity. You may take inspiration from SysML v2. Both graphical and textual representations should have one overarching, concrete, unambiguous spec in reST format, similar to SysML v2 strictness
-The application should support both forms of editing
-The textual representation should be easily editable and understandble for both humans and AI
-The textual representation should be easily handled by version control tools such as Git
-The underlying semantics of the textual / graphical representation should support traceability of various development artifacts (for example - code, CAD files, electrical schematics, Docx files and anything in between)
+Your second, parallel, goal is to create a textual representation for ARCADIA, similar to SysML v2. So a user can either edit a system model using UI (graphical representation) or text. Both graphical and textual representations should be fully equivalent and have full parity. You may take inspiration from SysML v2. Both graphical and textual representations should have one overarching, concrete, unambiguous spec in reST format, similar to SysML v2 strictness
+The application should support both forms of editing 
+The textual representation should be easily editable and understandble for both humans and AI 
+The textual representation should be easily handled by version control tools such as Git 
+The underlying semantics of the textual / graphical representation should support traceability of various development artifacts (for example - code, CAD files, electrical schematics, Docx files and anything in between)
 The textual representation editor should have syntax highlighting and linting
 
-The project should also have a backend server / service that you can deploy. The backend server purpose is to give programmatic access to stored system models. So, there also should be a clear REST API for querying, editing and working with models. The purpose of the REST API is to allow automation, scripting and AI-driven workflows
-An example could be - writing custom plugins for various domain specific software (version control software, CAD software etc...) to establish traceability between development artifacts and a system model
+The project should also have a backend server / service that you can deploy. The backend server purpose is to give programmatic access to stored system models. So, there also should be a clear REST API for querying, editing and working with models. The purpose of the REST API is to allow automation, scripting and AI-driven workflows 
+An example could be - writing custom plugins for various domain specific software (version control software, CAD software etc...) to establish traceability between development artifacts and a system model 
 
 The desktop application should contain built-in guide / help / tutorial with clear and concise info on modeling concepts, underlying semantics, common modeling scenarios and application features / how to use the app. It should be easy to navigate and explore
 
-@Computer
+@Computer 
 
 ### Semantic model / metamodel
 
 Requirements:
-
 - Textual notation.
 - Graphical notation.
 - Constraints and calculations.
@@ -658,7 +90,6 @@ Requirements:
 #### Textual notation
 
 Requirements:
-
 - Should not have visual noise and clutter.
 - Should have means to reduce cognitive load when developing system models.
 - Should be easily editable by humans. And AI agents.
@@ -672,8 +103,9 @@ Long, homogeneous lists in the UI that require user to scroll far or search for
 
 ## Active issues / current guidance
 
-Right now, the behavior & scenarios UI is hard to use. It contains static / uneditable diagrams, which is highly dubious. In addition, user workflow with the behavior & scenarios UI differ significantly from the other UIs - you can't edit diagrams and instead suppose to click on menus for model development
+Right now, the behavior & scenarios UI is hard to use. It contains static / uneditable diagrams, which is highly dubious. In addition, user workflow with the behavior & scenarios UI differ significantly from the other UIs - you can't edit diagrams and instead suppose to click on menus for model development 
 
----
+--- 
 
-The current project state is nowhere near the usability of the original ARCADIA Capella (despite its downfalls) or its functionality / semantics. You should focus on that by studying original ARCADIA Capella very closely and implementing its features in a modern, ergonomic and easy to use way
+The current project state is nowhere near the usability of the original ARCADIA Capella (despite its downfalls) or its functionality / semantics. You should focus on that by studying original ARCADIA Capella very closely and implementing its features in a modern, ergonomic and easy to use way
+<!-- END USER-OWNED APPLICATION SPECIFICATION -->

README.md

@@ -18,7 +18,7 @@ From the repository root:
 cargo run --locked -p oa-desktop --bin arcadia-studio
 ```
 
-Build both desktop and server release executables:
+Build the desktop, server and source CLI release executables:
 
 ```sh
 cargo build --release --workspace --locked
@@ -51,6 +51,21 @@ The earlier V2 package record describes `dist/ArcadiaStudio-Windows.zip` and `di
 
 The current [Windows packaging instructions](docs/windows-packaging.md) stage both executables, verify their runtime DLL dependencies, and produce an archive with checksums and provenance. Native acceptance fixtures and independent expected results are retained in [the release fixture directory](harness/fixtures/release1-native/README.md).
 
+## Work with source files from the command line
+
+The `arcadia` CLI checks an explicit `.arcadia` entry file and its includes without
+starting the desktop or server:
+
+```sh
+cargo run --locked -p oa-cli --bin arcadia -- check examples/text-first/project.arcadia
+```
+
+`stabilize ROOT` previews the identities needed for persistent editing;
+`rename-alias ROOT OLD NEW` previews an alias change and its references. Add
+`--write` to save that invocation's candidate, or `--json` for structured
+diagnostics and changed-file text/diffs. Preview leaves files untouched.
+See [source CLI commands](docs/source-cli.md) for examples and exit codes.
+
 ## Model operational needs and system responsibilities
 
 The desktop starts at **Home**, where you can create a model, open a local project, continue recent files or recover retained work. Missing recent files stay visible with **Locate**; **Remove** only forgets their history entry. Choose **Explore rescue example** for a model combining people, an organization, a System of Interest, information and physical exchange items, normal/degraded behavior and code/CAD evidence.
@@ -63,7 +78,7 @@ The architecture diagram has a compact side palette; expand it to see tool names
 2. Switch to **System Analysis**. Define one System of Interest and external Actors, then functions, missions, capabilities and functional chains. The system boundary has no internal LA/PA components in this version.
 3. Select a System or System Actor and choose **Add port** in the browser or Properties. Choose Standard or Flow, then **Create port**. Use **Boundary exchange** in the diagram palette, or **Draw boundary exchange** on a selected visible source port, to connect compatible component ports directly. Create the other participant's matching port first if none exists. Functions expose separate input/output port actions; the **Functional exchange** palette tool connects them. **Actions** exposes other engineering relationships and off-diagram configuration; **Data & interfaces** holds reusable payloads and contracts.
 4. Create focused views. **Containment** nests semantic children; **Architecture · allocated work** nests work within performers; **Functional dataflow** shows work decomposition and exchanges; **Missions & capabilities** shows objectives and participation. Dashed, italic parent work denotes an allocation summary inferred from its leaves. Ports appear on their owner's boundary. **View properties** stages saved line-kind, category, behavior-coverage, context, label and individual-hide choices. Right-click empty diagram space for **Duplicate view**, retaining the same semantic records in an independent presentation. Placement **Hide** removes a placement; line hiding retains its relationship; **Delete from model** removes semantics and dependent references.
-5. In **Behavior & scenarios**, author processes/chains, scenario lifelines and ordered occurrences, including repeated uses of the same exchange and explicit fragments/branches. Select a State machine and choose **Create diagram** to place its existing regions and states/modes in a saved view. State machines also support availability and state-action links. Conditions are descriptive, not executable simulation code. Behavior and Data authoring preserve your other diagram layouts.
+5. In **Behavior & scenarios**, choose **New**, select Operational process (OA), Functional chain (SA), Scenario or State machine, then enter its name. For a scenario, choose what its lifelines represent; **Add optional context…** links a context without changing its layer-root ownership. For a state machine, search for its existing participant owner; optionally select **Create the first state view**. Choose **Create and open** to start authoring work contributions, lifelines, ordered occurrences or states. **Cancel · Esc** discards the creation draft; if another dialog is open, Escape dismisses that dialog first. Creation and its optional first view form one Undo operation. A new state machine starts without regions or states; **Create diagram** can later place its existing contents in a saved view. Behavior supports repeated exchanges, fragments/branches, availability and state-action links. Conditions are descriptive, not executable simulation code. Behavior and Data authoring preserve your other diagram layouts.
 6. Select an OA or SA element and choose **Create / update counterpart**. Review dependency scope and counterpart choices, then apply one undoable transaction. For an existing trace, **Review semantics…** compares typed content and prior observations, with explicit keep, take or final-value decisions for supported structural, scalar, constructor, individual-row and ordered-collection changes. Open additional trace rows and choose **Include this row** to combine reviewed source contributions into one validated Apply/Undo transaction; conflicting decisions require resolution. Review does not automatically synchronize the perspectives. **Attachments** reviews an existing child’s parent or a relationship endpoint. **Artifact links** reviews metadata, owner moves, explicit source-absence deletion and creation of a reserved counterpart after all introduced metadata is reviewed. These controls have automated coverage; their native acceptance remains pending. Manual traces link other engineering correspondences. **Traceability** also edits artifact URI, revision and fragment metadata.
 7. Review **Model checks**, then save `.arcadia` source or `.json`. Warnings allow incomplete authoring; structural errors preserve the committed model and rejected draft.
 
@@ -87,6 +102,8 @@ In the state view, **Select / move** drags vertices and containers without repar
 
 ## Edit the same model as text
 
+For a short text-only start, open [the distress-response model](examples/text-first/project.arcadia) and follow [its three-step walkthrough](examples/text-first/README.md). Four declarations and three explicit relationships describe participants, work, responsibility and an exchange; no diagram or handwritten UUID is needed.
+
 **Textual model** has a source-file folder tree, per-file drafts, syntax highlighting, live linting and explicit **Apply all**. Collapse/Locate navigate the hierarchy; collapsed folders retain draft and diagnostic indicators. Right-click a file for contextual actions. Projects can use relative includes to organize source into files. For example:
 
 ```text

crates/oa-cli/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "oa-cli"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[[bin]]
+name = "arcadia"
+path = "src/main.rs"
+
+[dependencies]
+oa-core = { path = "../oa-core" }
+serde.workspace = true
+serde_json.workspace = true

crates/oa-cli/src/lib.rs

@@ -0,0 +1,451 @@
+//! Source-only authoring. Preparation captures bytes; only core owns disk writes.
+use oa_core::{
+    Command, language,
+    persistence::MigrationReport,
+    prepare_command,
+    source_files::{self, DiskProject, SourceFileError},
+    source_project::{self, CompiledSourceProject, ProjectLimits, SourceDiagnostic},
+    validation::Severity,
+};
+use serde::Serialize;
+use std::path::{Path, PathBuf};
+
+pub const LIMITS: ProjectLimits = ProjectLimits {
+    max_files: 256,
+    max_include_depth: 32,
+    max_include_edges: 1024,
+    model: language::ParseLimits {
+        max_source_bytes: 64 * 1024 * 1024,
+        max_graph_objects: 100_000,
+        max_records: 250_000,
+        max_step_references: 500_000,
+    },
+};
+
+#[derive(Debug, Clone)]
+pub enum Operation {
+    Check,
+    Stabilize,
+    RenameAlias { old: String, new: String },
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct Location {
+    pub path: String,
+    /// Half-open UTF-8 byte offsets. Line/column are one-based Unicode scalars.
+    pub start: usize,
+    pub end: usize,
+    pub line: Option<usize>,
+    pub column: Option<usize>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct Diagnostic {
+    pub severity: String,
+    pub code: String,
+    pub message: String,
+    pub coordinate_space: String,
+    pub location: Option<Location>,
+    pub related: Vec<Location>,
+    pub object_id: Option<String>,
+    pub field: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct Change {
+    pub path: String,
+    /// Exact captured and proposed UTF-8 text, including line endings.
+    pub before: String,
+    pub after: String,
+    pub diff: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct Report {
+    pub format_version: u32,
+    pub entry: String,
+    pub operation: String,
+    pub status: String,
+    pub exit_code: u8,
+    /// True only after a successful changed save. False on failure does not
+    /// promise rollback: consult the specific error/recovery outcome.
+    pub written: bool,
+    pub diagnostics: Vec<Diagnostic>,
+    pub changes: Vec<Change>,
+    pub identities_to_stabilize: usize,
+    pub migration: Option<MigrationReport>,
+    pub notes: Vec<String>,
+}
+
+impl Report {
+    pub fn failure(
+        entry: &Path,
+        operation: &str,
+        exit_code: u8,
+        code: &str,
+        message: String,
+    ) -> Self {
+        let mut report = Self::empty(entry, operation);
+        report.fail(exit_code, code, message);
+        report
+    }
+
+    fn empty(entry: &Path, operation: &str) -> Self {
+        Self {
+            format_version: 1,
+            entry: entry.to_string_lossy().into_owned(),
+            operation: operation.into(),
+            status: "checked".into(),
+            exit_code: 0,
+            written: false,
+            diagnostics: vec![],
+            changes: vec![],
+            identities_to_stabilize: 0,
+            migration: None,
+            notes: vec![],
+        }
+    }
+
+    fn fail(&mut self, exit_code: u8, code: &str, message: String) {
+        self.status = "rejected".into();
+        self.exit_code = exit_code;
+        self.diagnostics.push(Diagnostic {
+            severity: "error".into(),
+            code: code.into(),
+            message,
+            coordinate_space: "operation".into(),
+            location: None,
+            related: vec![],
+            object_id: None,
+            field: None,
+        });
+    }
+}
+
+fn located(issue: SourceDiagnostic, space: &str) -> Diagnostic {
+    let d = issue.diagnostic;
+    Diagnostic {
+        severity: match d.severity {
+            Severity::Error => "error",
+            Severity::Warning => "warning",
+        }
+        .into(),
+        code: d.code,
+        message: d.message,
+        coordinate_space: space.into(),
+        location: Some(Location {
+            path: issue.path,
+            start: d.span.start,
+            end: d.span.end,
+            line: Some(d.line),
+            column: Some(d.column),
+        }),
+        related: issue
+            .related
+            .into_iter()
+            .map(|at| Location {
+                path: at.path,
+                start: at.span.start,
+                end: at.span.end,
+                line: None,
+                column: None,
+            })
+            .collect(),
+        object_id: d.object_id.map(|id| id.to_string()),
+        field: d.field,
+    }
+}
+
+fn disk_error(report: &mut Report, error: SourceFileError) {
+    let code = match &error {
+        SourceFileError::Conflict(_) => "external_change",
+        SourceFileError::RecoveryRequired(_) => "recovery_required",
+        SourceFileError::RecoveryFailed { .. } => "recovery_failed",
+        SourceFileError::Path(_) => "unsafe_path",
+        SourceFileError::Limit(_) => "source_limit",
+        SourceFileError::UnknownExpectation(_) => "unknown_disk_expectation",
+        SourceFileError::Invalid(_) => "invalid_save_candidate",
+        SourceFileError::Io { .. } => "io_error",
+    };
+    report.fail(3, code, error.to_string());
+}
+
+/// A candidate owns its original expectations and is consumed by saving.
+/// Callers cannot replace its source/model/expectations after preparation.
+pub struct Prepared {
+    report: Report,
+    snapshot: DiskProject,
+    compiled: CompiledSourceProject,
+    mutable: bool,
+}
+
+impl Prepared {
+    pub fn report(&self) -> &Report {
+        &self.report
+    }
+
+    pub fn into_report(self) -> Report {
+        self.report
+    }
+
+    pub fn write(mut self) -> Report {
+        if !self.mutable {
+            self.report
+                .fail(2, "usage", "check/lint does not accept --write".into());
+            return self.report;
+        }
+        match source_files::save_project(&self.snapshot, &self.compiled, LIMITS) {
+            Ok(_) => {
+                self.report.written = !self.report.changes.is_empty();
+                self.report.status = if self.report.written {
+                    "written"
+                } else {
+                    "unchanged"
+                }
+                .into();
+            }
+            Err(error) => disk_error(&mut self.report, error),
+        }
+        self.report
+    }
+}
+
+pub fn prepare(entry: &Path, operation: Operation) -> Result<Prepared, Box<Report>> {
+    let name = match operation {
+        Operation::Check => "check",
+        Operation::Stabilize => "stabilize",
+        Operation::RenameAlias { .. } => "rename-alias",
+    };
+    let mut report = Report::empty(entry, name);
+    let snapshot = source_files::load_project(entry, LIMITS).map_err(|error| {
+        disk_error(&mut report, error);
+        Box::new(report.clone())
+    })?;
+    let raw = snapshot.reachable_bundle();
+    // The loader may include warnings from stabilized compilation. Only its
+    // discovery/IO diagnostics are authoritative on the original bytes.
+    let mut diagnostics: Vec<_> = snapshot
+        .diagnostics
+        .iter()
+        .filter(|d| {
+            matches!(
+                d.diagnostic.code.as_str(),
+                "pending_save"
+                    | "source_encoding"
+                    | "source_limit"
+                    | "invalid_path"
+                    | "missing_include"
+                    | "project_limit"
+            )
+        })
+        .cloned()
+        .collect();
+    for diagnostic in source_project::lint_bundle(&raw, LIMITS) {
+        if !diagnostics.contains(&diagnostic) {
+            diagnostics.push(diagnostic);
+        }
+    }
+    let disk_refusal = snapshot.diagnostics.iter().any(|d| {
+        matches!(
+            d.diagnostic.code.as_str(),
+            "pending_save" | "missing_include" | "invalid_path"
+        )
+    });
+    let invalid = diagnostics
+        .iter()
+        .any(|d| d.diagnostic.severity == Severity::Error);
+    report.diagnostics = diagnostics
+        .into_iter()
+        .map(|d| located(d, "input"))
+        .collect();
+    if invalid {
+        // Do not run declaration analysis or any updater on invalid raw text.
+        // Failed lint may also have allocated provisional object identities.
+        for diagnostic in &mut report.diagnostics {
+            diagnostic.object_id = None;
+        }
+        report.status = "invalid".into();
+        report.exit_code = if disk_refusal { 3 } else { 1 };
+        return Err(Box::new(report));
+    }
+    let explicit_ids: std::collections::BTreeSet<_> = raw
+        .files
+        .values()
+        .flat_map(|text| language::analyze(text).declarations)
+        .filter_map(|d| d.id.map(|id| id.to_string()))
+        .collect();
+    for diagnostic in &mut report.diagnostics {
+        if diagnostic
+            .object_id
+            .as_ref()
+            .is_some_and(|id| !explicit_ids.contains(id))
+        {
+            diagnostic.object_id = None;
+        }
+    }
+    let mut compiled = source_project::compile_bundle(&raw, LIMITS).map_err(|diagnostics| {
+        report.status = "invalid".into();
+        report.exit_code = 1;
+        report
+            .diagnostics
+            .extend(diagnostics.into_iter().map(|d| located(d, "candidate")));
+        Box::new(report.clone())
+    })?;
+    report.identities_to_stabilize = raw
+        .files
+        .values()
+        .map(|text| {
+            language::analyze(text)
+                .declarations
+                .into_iter()
+                .filter(|d| d.id.is_none())
+                .count()
+        })
+        .sum();
+    report.migration = compiled.decoded.migration.clone();
+    let mutable = !matches!(operation, Operation::Check);
+    if let Operation::RenameAlias { old, new } = operation {
+        let project = &compiled.decoded.project;
+        let Some((id, _)) = project
+            .identities()
+            .into_iter()
+            .find(|(_, alias)| *alias == old)
+        else {
+            report.fail(
+                1,
+                "unknown_alias",
+                format!("No declaration has alias '{old}'."),
+            );
+            return Err(Box::new(report));
+        };
+        let command = prepare_command(project, &Command::SetAlias(id, new)).map_err(|error| {
+            report.fail(1, "semantic_command_rejected", error.to_string());
+            Box::new(report.clone())
+        })?;
+        compiled = source_project::update_bundle_with_identity_map(
+            &compiled,
+            &command.project,
+            &command.identity_map,
+            LIMITS,
+        )
+        .map_err(|diagnostics| {
+            report.status = "invalid".into();
+            report.exit_code = 1;
+            report
+                .diagnostics
+                .extend(diagnostics.into_iter().map(|d| located(d, "candidate")));
+            Box::new(report.clone())
+        })?;
+    }
+    if mutable {
+        for (path, after) in &compiled.bundle.files {
+            let before = raw.files.get(path).cloned().unwrap_or_default();
+            if &before != after {
+                report.changes.push(Change {
+                    path: path.clone(),
+                    diff: unified_diff(path, &before, after),
+                    before,
+                    after: after.clone(),
+                });
+            }
+        }
+        report.status = "preview".into();
+        report.notes.push("This invocation's complete proposed changed-file texts and diffs are reported. Without --write nothing is saved; a later invocation may allocate different missing UUIDs. This is not a saved plan or a digest of unchanged dependencies.".into());
+    }
+    report.notes.push("Diagnostic object IDs are omitted for declarations without authored IDs; lint's temporary identities are not the candidate's identities.".into());
+    report.notes.push("Disk writes use the core journal/conflict checks. This is not cross-process atomic visibility or a power-loss durability guarantee; pending saves are never implicitly recovered. A failed write may require explicit journal recovery.".into());
+    Ok(Prepared {
+        report,
+        snapshot,
+        compiled,
+        mutable,
+    })
+}
+
+/// One bounded hunk per file: common prefix/suffix plus three context lines.
+/// Linear in input size; no quadratic LCS allocation for large modules.
+fn unified_diff(path: &str, before: &str, after: &str) -> String {
+    let a: Vec<_> = before.split_inclusive('\n').collect();
+    let b: Vec<_> = after.split_inclusive('\n').collect();
+    let prefix = a.iter().zip(&b).take_while(|(a, b)| a == b).count();
+    let suffix = a[prefix..]
+        .iter()
+        .rev()
+        .zip(b[prefix..].iter().rev())
+        .take_while(|(a, b)| a == b)
+        .count();
+    let start = prefix.saturating_sub(3);
+    let a_end = (a.len() - suffix + 3).min(a.len());
+    let b_end = (b.len() - suffix + 3).min(b.len());
+    let a_start = if a_end == start { start } else { start + 1 };
+    let b_start = if b_end == start { start } else { start + 1 };
+    let mut out = format!(
+        "--- a/{path}\n+++ b/{path}\n@@ -{a_start},{} +{b_start},{} @@\n",
+        a_end - start,
+        b_end - start
+    );
+    let mut emit = |prefix: char, line: &str| {
+        out.push(prefix);
+        out.push_str(line);
+        if !line.ends_with('\n') {
+            out.push_str("\n\\ No newline at end of file\n");
+        }
+    };
+    for line in &a[start..prefix] {
+        emit(' ', line);
+    }
+    for line in &a[prefix..a.len() - suffix] {
+        emit('-', line);
+    }
+    for line in &b[prefix..b.len() - suffix] {
+        emit('+', line);
+    }
+    for line in &a[a.len() - suffix..a_end] {
+        emit(' ', line);
+    }
+    out
+}
+
+pub struct Arguments {
+    pub entry: PathBuf,
+    pub operation: Operation,
+    pub write: bool,
+    pub json: bool,
+}
+
+pub const HELP: &str = "arcadia check ROOT [--json]\narcadia lint ROOT [--json]\narcadia stabilize ROOT [--write] [--json]\narcadia rename-alias ROOT OLD NEW [--write] [--json]\n\nROOT is an explicit .arcadia entry file; includes resolve relative to it.\nMutation commands preview by default. --write applies this invocation's candidate.\nMissing UUIDs in a preview are provisional until written. No canonical formatting.\nExit: 0 valid/success (engineering warnings allowed), 1 invalid source or semantic\ncommand rejection, 2 usage, 3 disk/path/conflict/pending-journal/output failure.\nNo implicit journal recovery. Limits: 64 MiB, 256 files, include depth32/edges1024,\n100000 graph objects, 250000 records, 500000 ordered references.\n";
+
+pub fn arguments(args: &[std::ffi::OsString]) -> Result<Arguments, String> {
+    let mut positional = Vec::new();
+    let (mut write, mut json) = (false, false);
+    for arg in args {
+        if arg == "--write" && !write {
+            write = true;
+        } else if arg == "--json" && !json {
+            json = true;
+        } else if arg.to_string_lossy().starts_with('-') {
+            return Err(format!(
+                "Unknown or repeated option: {}",
+                arg.to_string_lossy()
+            ));
+        } else {
+            positional.push(arg);
+        }
+    }
+    let command = positional.first().and_then(|s| s.to_str()).unwrap_or("");
+    let operation = match (command, positional.len()) {
+        ("check" | "lint", 2) if !write => Operation::Check,
+        ("stabilize", 2) => Operation::Stabilize,
+        ("rename-alias", 4) => Operation::RenameAlias {
+            old: positional[2].to_str().ok_or("Alias must be UTF-8")?.into(),
+            new: positional[3].to_str().ok_or("Alias must be UTF-8")?.into(),
+        },
+        _ => return Err(HELP.into()),
+    };
+    Ok(Arguments {
+        entry: PathBuf::from(positional[1]),
+        operation,
+        write,
+        json,
+    })
+}

crates/oa-cli/src/main.rs

@@ -0,0 +1,102 @@
+use oa_cli::{Report, arguments, prepare};
+use std::{
+    io::{self, Write},
+    path::Path,
+    process::ExitCode,
+};
+
+fn human_report(report: &Report, show_diff: bool) -> io::Result<()> {
+    let mut err = io::stderr().lock();
+    for d in &report.diagnostics {
+        let at = d
+            .location
+            .as_ref()
+            .map(|l| {
+                format!(
+                    "{}:{}:{}",
+                    l.path,
+                    l.line.unwrap_or(0),
+                    l.column.unwrap_or(0)
+                )
+            })
+            .unwrap_or_else(|| report.entry.clone());
+        writeln!(
+            err,
+            "{at}: {}[{}] ({}): {}",
+            d.severity, d.code, d.coordinate_space, d.message
+        )?;
+    }
+    writeln!(
+        err,
+        "{}: {} file changes; {} identities to stabilize",
+        report.status,
+        report.changes.len(),
+        report.identities_to_stabilize
+    )?;
+    if let Some(migration) = &report.migration {
+        writeln!(
+            err,
+            "Source migration: schema {} → {} (separate from identity stabilization)",
+            migration.from_schema, migration.to_schema
+        )?;
+    }
+    for note in &report.notes {
+        writeln!(err, "{note}")?;
+    }
+    if show_diff {
+        let mut out = io::stdout().lock();
+        for change in &report.changes {
+            write!(out, "{}", change.diff)?;
+        }
+        out.flush()?;
+    }
+    err.flush()
+}
+
+fn run() -> io::Result<u8> {
+    let args: Vec<_> = std::env::args_os().skip(1).collect();
+    if args.len() == 1 && (args[0] == "--help" || args[0] == "-h") {
+        io::stdout().write_all(oa_cli::HELP.as_bytes())?;
+        return Ok(0);
+    }
+    if args.len() == 1 && args[0] == "--version" {
+        writeln!(io::stdout(), "arcadia {}", env!("CARGO_PKG_VERSION"))?;
+        return Ok(0);
+    }
+    let json = args.iter().any(|a| a == "--json");
+    let mut displayed = false;
+    let report = match arguments(&args) {
+        Err(error) => Report::failure(Path::new(""), "usage", 2, "usage", error),
+        Ok(args) => match prepare(&args.entry, args.operation) {
+            Err(report) => *report,
+            Ok(prepared) => {
+                if args.write {
+                    if !args.json {
+                        human_report(prepared.report(), true)?;
+                        displayed = true;
+                    }
+                    prepared.write()
+                } else {
+                    prepared.into_report()
+                }
+            }
+        },
+    };
+    if json {
+        serde_json::to_writer_pretty(io::stdout().lock(), &report)?;
+        writeln!(io::stdout())?;
+    } else {
+        human_report(&report, !displayed)?;
+    }
+    Ok(report.exit_code)
+}
+
+fn main() -> ExitCode {
+    match run() {
+        Ok(code) => ExitCode::from(code),
+        Err(error) => {
+            let _ = writeln!(io::stderr(), "Output failed: {error}");
+            ExitCode::from(3)
+        }
+    }
+}

crates/oa-cli/tests/source_cli.rs

@@ -0,0 +1,425 @@
+use oa_cli::{LIMITS, Operation, Prepared, prepare};
+use oa_core::{Id, Project, source_files, source_project};
+use serde_json::Value;
+use std::{
+    collections::BTreeMap,
+    fs,
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+struct Fixture(PathBuf);
+impl Fixture {
+    fn new() -> Self {
+        let path = std::env::temp_dir().join(format!("arcadia-cli-test-{}", Id::new_v4()));
+        fs::create_dir(&path).unwrap();
+        Self(path)
+    }
+    fn put(&self, name: &str, text: &str) {
+        let path = self.0.join(name);
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        fs::write(path, text).unwrap();
+    }
+    fn entry(&self) -> PathBuf {
+        self.0.join("project.arcadia")
+    }
+    fn read(&self, name: &str) -> String {
+        fs::read_to_string(self.0.join(name)).unwrap()
+    }
+    fn prepare(&self, op: Operation) -> Prepared {
+        prepare(&self.entry(), op).unwrap_or_else(|report| panic!("{report:#?}"))
+    }
+    fn model(&self) -> Project {
+        let disk = source_files::load_project(&self.entry(), LIMITS).unwrap();
+        source_project::compile_bundle(&disk.reachable_bundle(), LIMITS)
+            .unwrap()
+            .decoded
+            .project
+    }
+    fn cli(&self, args: &[&str]) -> (i32, Value) {
+        let mut command = Command::new(env!("CARGO_BIN_EXE_arcadia"));
+        command
+            .arg(args[0])
+            .arg(self.entry())
+            .args(&args[1..])
+            .arg("--json");
+        let output = command.output().unwrap();
+        assert!(
+            output.stderr.is_empty(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        (
+            output.status.code().unwrap(),
+            serde_json::from_slice(&output.stdout).unwrap(),
+        )
+    }
+}
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+const SIMPLE: &str = "// 雨: authored defaults stay omitted\r\narcadia 7;\r\nproject rescue \"Rescue\" {\r\n    oa_entity team \"Team\" {}\r\n}\r\n";
+
+#[test]
+fn complete_alarm_example_preview_then_write_and_fixed_point() {
+    let fixture = Fixture::new();
+    let source = include_str!(
+        "../../../harness/experiments/textual-authoring-20260911/alarm-response.arcadia"
+    );
+    fixture.put("project.arcadia", source);
+    let (code, check) = fixture.cli(&["check"]);
+    assert_eq!(code, 0);
+    assert_eq!(check["diagnostics"], serde_json::json!([]));
+    let (code, preview) = fixture.cli(&["stabilize"]);
+    assert_eq!(code, 0);
+    assert_eq!(preview["identities_to_stabilize"], 40);
+    assert_eq!(preview["status"], "preview");
+    assert_eq!(fixture.read("project.arcadia"), source);
+    assert!(
+        preview["changes"][0]["diff"]
+            .as_str()
+            .unwrap()
+            .contains("+project alarm_response")
+    );
+    let (code, written) = fixture.cli(&["stabilize", "--write"]);
+    assert_eq!(code, 0);
+    let saved = fixture.read("project.arcadia");
+    assert_eq!(written["changes"][0]["after"], saved);
+    let project = fixture.model();
+    assert_eq!(project.identities().len(), 40);
+    let mut stripped = saved.clone();
+    for (id, _) in project.identities() {
+        stripped = stripped.replace(&format!(" id \"{id}\""), "");
+    }
+    assert_eq!(stripped, source, "only identity clauses may be inserted");
+    let (code, again) = fixture.cli(&["stabilize", "--write"]);
+    assert_eq!(code, 0);
+    assert_eq!(again["changes"], serde_json::json!([]));
+    assert_eq!(again["status"], "unchanged");
+    assert_eq!(fixture.model(), project);
+    assert_eq!(fixture.read("project.arcadia"), saved);
+}
+
+#[test]
+fn captured_candidate_exact_write_preserves_crlf_comments_and_noop_metadata() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", SIMPLE);
+    let candidate = fixture.prepare(Operation::Stabilize);
+    let expected = candidate.report().changes[0].after.clone();
+    assert_eq!(candidate.report().identities_to_stabilize, 2);
+    assert_eq!(fixture.read("project.arcadia"), SIMPLE);
+    assert_eq!(candidate.write().exit_code, 0);
+    assert_eq!(fixture.read("project.arcadia"), expected);
+    assert!(expected.contains("// 雨: authored defaults stay omitted\r\n"));
+    assert!(!expected.contains("description"));
+    let metadata = fs::metadata(fixture.entry()).unwrap().modified().unwrap();
+    let report = fixture.prepare(Operation::Stabilize).write();
+    assert_eq!(report.status, "unchanged");
+    assert!(!report.written);
+    assert_eq!(
+        fs::metadata(fixture.entry()).unwrap().modified().unwrap(),
+        metadata
+    );
+    assert_eq!(fs::read_dir(&fixture.0).unwrap().count(), 1);
+}
+
+#[test]
+fn alias_rename_across_modules_changes_only_live_tokens_and_retains_all_identity() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", "arcadia 7; project rescue \"Rescue\" { include \"participants.arcadia\"; include \"work.arcadia\"; }\n");
+    fixture.put(
+        "participants.arcadia",
+        "// @team is quoted documentation\noa_entity team \"Team @team\" {}\n",
+    );
+    fixture.put("work.arcadia", "oa_activity assess \"Assess\" {}\noa_activity report \"Report\" {}\nallocation assigned \"Assigned\" { source @team; target @assess; }\ninteraction transfer \"Transfer\" { source @assess; target @report; }\n");
+    assert_eq!(fixture.prepare(Operation::Stabilize).write().exit_code, 0);
+    let before = fixture.model();
+    let original: BTreeMap<_, _> = ["project.arcadia", "participants.arcadia", "work.arcadia"]
+        .into_iter()
+        .map(|p| (p, fixture.read(p)))
+        .collect();
+    let team = before
+        .identities()
+        .into_iter()
+        .find(|(_, alias)| *alias == "team")
+        .unwrap()
+        .0;
+    let candidate = fixture.prepare(Operation::RenameAlias {
+        old: "team".into(),
+        new: "rescue_team".into(),
+    });
+    assert_eq!(candidate.report().changes.len(), 2);
+    assert_eq!(fixture.model(), before, "preview cannot mutate");
+    assert_eq!(candidate.write().exit_code, 0);
+    let mut expected = before;
+    expected.elements.get_mut(&team).unwrap().alias = "rescue_team".into();
+    assert_eq!(fixture.model(), expected);
+    assert_eq!(fixture.read("project.arcadia"), original["project.arcadia"]);
+    assert_eq!(
+        fixture.read("participants.arcadia"),
+        original["participants.arcadia"].replacen("oa_entity team ", "oa_entity rescue_team ", 1)
+    );
+    assert_eq!(
+        fixture.read("work.arcadia"),
+        original["work.arcadia"].replace("source @team;", "source @rescue_team;")
+    );
+}
+
+#[test]
+fn invalid_unicode_raw_edit_is_located_and_never_stabilized_or_written() {
+    let fixture = Fixture::new();
+    let raw = "arcadia 7; project p \"雨\" {\n oa_activity a \"A\" {}\n allocation alloc \"Alloc\" { source @missing; target @a; }\n}\n";
+    fixture.put("project.arcadia", raw);
+    for command in [
+        vec!["check"],
+        vec!["stabilize", "--write"],
+        vec!["rename-alias", "a", "b", "--write"],
+    ] {
+        let (code, report) = fixture.cli(&command);
+        assert_eq!(code, 1);
+        assert_eq!(fixture.read("project.arcadia"), raw);
+        let diagnostics = report["diagnostics"].as_array().unwrap();
+        assert!(!diagnostics.is_empty());
+        for d in diagnostics {
+            assert_eq!(d["coordinate_space"], "input");
+            let at = &d["location"];
+            let start = at["start"].as_u64().unwrap() as usize;
+            assert!(raw.is_char_boundary(start));
+            assert_eq!(
+                at["line"].as_u64().unwrap() as usize,
+                raw[..start].bytes().filter(|b| *b == b'\n').count() + 1
+            );
+            let line = raw[..start]
+                .rsplit_once('\n')
+                .map_or(&raw[..start], |(_, tail)| tail);
+            assert_eq!(
+                at["column"].as_u64().unwrap() as usize,
+                line.chars().count() + 1
+            );
+        }
+    }
+}
+
+#[test]
+fn missing_id_warning_uses_raw_location_and_never_exposes_ephemeral_lint_id() {
+    let fixture = Fixture::new();
+    let raw = "arcadia 7;\nproject p \"雨\" {\n    oa_activity work \"Work\" {}\n}\n";
+    fixture.put("project.arcadia", raw);
+    let (code, result) = fixture.cli(&["lint"]);
+    assert_eq!(code, 0, "engineering warnings do not reject admission");
+    let warning = result["diagnostics"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|d| d["code"] == "work_without_behavior_context")
+        .unwrap();
+    assert_eq!(warning["severity"], "warning");
+    assert_eq!(
+        warning["location"]["start"],
+        raw.find("oa_activity").unwrap()
+    );
+    assert_eq!(warning["location"]["line"], 3);
+    assert_eq!(warning["location"]["column"], 5);
+    assert!(warning["object_id"].is_null());
+    assert_eq!(fixture.read("project.arcadia"), raw);
+}
+
+#[test]
+fn captured_dependency_change_refuses_all_writes_even_on_noop() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", SIMPLE);
+    let pending = fixture.prepare(Operation::Stabilize);
+    let external = format!("{SIMPLE}// editor changed this\n");
+    fixture.put("project.arcadia", &external);
+    let result = pending.write();
+    assert_eq!(result.exit_code, 3);
+    assert_eq!(result.diagnostics.last().unwrap().code, "external_change");
+    assert_eq!(fixture.read("project.arcadia"), external);
+    assert_eq!(fixture.prepare(Operation::Stabilize).write().exit_code, 0);
+    let noop = fixture.prepare(Operation::Stabilize);
+    assert!(noop.report().changes.is_empty());
+    let latest = format!("{}// another edit\n", fixture.read("project.arcadia"));
+    fixture.put("project.arcadia", &latest);
+    assert_eq!(noop.write().exit_code, 3);
+    assert_eq!(fixture.read("project.arcadia"), latest);
+}
+
+#[test]
+fn pending_journal_refuses_read_preview_and_write_without_recovery() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", SIMPLE);
+    assert_eq!(fixture.prepare(Operation::Stabilize).write().exit_code, 0);
+    let noop = fixture.prepare(Operation::Stabilize);
+    let source = fixture.read("project.arcadia");
+    // An opaque incomplete journal must never be interpreted/recovered by CLI.
+    let journal = fixture.0.join(".arcadia-save-project.arcadia.journal");
+    fs::create_dir(&journal).unwrap();
+    fs::write(journal.join("sentinel"), b"retain").unwrap();
+    for op in [Operation::Check, Operation::Stabilize] {
+        let report = prepare(&fixture.entry(), op).err().unwrap();
+        assert_eq!(report.exit_code, 3);
+        assert!(report.diagnostics.iter().any(|d| d.code == "pending_save"));
+    }
+    assert_eq!(
+        noop.write().exit_code,
+        3,
+        "saver must recheck after preview"
+    );
+    assert_eq!(fixture.read("project.arcadia"), source);
+    assert_eq!(fs::read(journal.join("sentinel")).unwrap(), b"retain");
+}
+
+#[test]
+fn rejected_alias_and_same_alias_preserve_source() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", SIMPLE);
+    assert_eq!(fixture.prepare(Operation::Stabilize).write().exit_code, 0);
+    let source = fixture.read("project.arcadia");
+    for (old, new) in [
+        ("team", "rescue"),
+        ("team", "invalid alias"),
+        ("absent", "valid"),
+    ] {
+        let (code, result) = fixture.cli(&["rename-alias", old, new, "--write"]);
+        assert_eq!(code, 1);
+        assert_eq!(result["status"], "rejected");
+        assert_eq!(fixture.read("project.arcadia"), source);
+    }
+    let (code, result) = fixture.cli(&["rename-alias", "team", "team", "--write"]);
+    assert_eq!(code, 0);
+    assert_eq!(result["status"], "unchanged");
+    assert_eq!(fixture.read("project.arcadia"), source);
+}
+
+#[test]
+fn rename_shows_missing_identity_and_separate_source_migration() {
+    let fixture = Fixture::new();
+    let old = "// retain\narcadia 5; project p \"P\" { oa_entity team \"Team\" {} }\n";
+    fixture.put("project.arcadia", old);
+    let candidate = fixture.prepare(Operation::RenameAlias {
+        old: "team".into(),
+        new: "crew".into(),
+    });
+    let report = candidate.report();
+    assert_eq!(report.identities_to_stabilize, 2);
+    assert_eq!(report.migration.as_ref().unwrap().from_schema, 5);
+    assert_eq!(report.migration.as_ref().unwrap().to_schema, 7);
+    assert!(report.changes[0].diff.contains("-arcadia 5;"));
+    assert!(report.changes[0].diff.contains("+arcadia 7;"));
+    assert!(report.changes[0].after.contains("oa_entity crew"));
+    assert_eq!(fixture.read("project.arcadia"), old);
+    assert_eq!(candidate.write().exit_code, 0);
+}
+
+#[test]
+fn entry_is_explicit_and_machine_readable_usage_errors_do_not_write() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", SIMPLE);
+    let output = Command::new(env!("CARGO_BIN_EXE_arcadia"))
+        .current_dir(&fixture.0)
+        .args(["check", "--json"])
+        .output()
+        .unwrap();
+    assert_eq!(output.status.code(), Some(2));
+    let error: Value = serde_json::from_slice(&output.stdout).unwrap();
+    assert_eq!(error["diagnostics"][0]["code"], "usage");
+    assert_eq!(fixture.read("project.arcadia"), SIMPLE);
+    let (code, _) = fixture.cli(&["check", "--write"]);
+    assert_eq!(code, 2);
+    assert!(Path::new(env!("CARGO_BIN_EXE_arcadia")).is_file());
+}
+
+#[test]
+fn loader_encoding_missing_dependency_and_invalid_old_source_keep_original_bytes() {
+    let fixture = Fixture::new();
+    let entry = "arcadia 7; project p \"P\" { include \"part.arcadia\"; }";
+    fixture.put("project.arcadia", entry);
+    let (code, report) = fixture.cli(&["stabilize", "--write"]);
+    assert_eq!(code, 3, "a disk dependency could not be read");
+    assert!(
+        report["diagnostics"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .any(|d| d["code"] == "missing_include")
+    );
+    fs::write(fixture.0.join("part.arcadia"), [0xff, 0xfe]).unwrap();
+    let (code, report) = fixture.cli(&["stabilize", "--write"]);
+    assert_eq!(code, 1, "invalid encoding is invalid raw source");
+    assert!(
+        report["diagnostics"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .any(|d| d["code"] == "source_encoding")
+    );
+    assert_eq!(fixture.read("project.arcadia"), entry);
+    assert_eq!(
+        fs::read(fixture.0.join("part.arcadia")).unwrap(),
+        [0xff, 0xfe]
+    );
+    for raw in [
+        "arcadia 5; project p \"P\" { oa_entity a \"A\" { ??? } }",
+        "arcadia 2; project p \"P\" {}",
+    ] {
+        fixture.put("project.arcadia", raw);
+        let (code, _) = fixture.cli(&["stabilize", "--write"]);
+        assert_eq!(code, 1);
+        assert_eq!(fixture.read("project.arcadia"), raw);
+    }
+}
+
+#[test]
+fn non_element_alias_detached_file_and_unchanged_dependency_conflict() {
+    let fixture = Fixture::new();
+    fixture.put("project.arcadia", "arcadia 7; project p \"P\" { include \"part.arcadia\"; oa_activity a \"A\" {} allocation responsible \"Responsible\" { source @ // keep edge comment\nteam; target @a; } }");
+    fixture.put("part.arcadia", "oa_entity team \"Team\" {}");
+    fixture.put(
+        "detached.arcadia",
+        "invalid detached draft must stay exact 雨",
+    );
+    assert_eq!(fixture.prepare(Operation::Stabilize).write().exit_code, 0);
+    let before = fixture.model();
+    let relation = before
+        .identities()
+        .into_iter()
+        .find(|(_, alias)| *alias == "responsible")
+        .unwrap()
+        .0;
+    let (code, _) = fixture.cli(&["rename-alias", "responsible", "performs", "--write"]);
+    assert_eq!(code, 0);
+    let mut expected = before;
+    expected.relations.get_mut(&relation).unwrap().alias = "performs".into();
+    assert_eq!(fixture.model(), expected);
+    assert!(
+        fixture
+            .read("project.arcadia")
+            .contains("@ // keep edge comment\nteam")
+    );
+    let captured = fixture.prepare(Operation::RenameAlias {
+        old: "p".into(),
+        new: "rescue".into(),
+    });
+    assert!(
+        captured
+            .report()
+            .changes
+            .iter()
+            .all(|c| c.path != "part.arcadia")
+    );
+    let root_before = fixture.read("project.arcadia");
+    fixture.put("part.arcadia", "// external unchanged-dependency edit\n");
+    assert_eq!(captured.write().exit_code, 3);
+    assert_eq!(fixture.read("project.arcadia"), root_before);
+    assert_eq!(
+        fixture.read("part.arcadia"),
+        "// external unchanged-dependency edit\n"
+    );
+    assert_eq!(
+        fixture.read("detached.arcadia"),
+        "invalid detached draft must stay exact 雨"
+    );
+}

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/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/checkpoints.rs

@@ -173,7 +173,12 @@ impl App {
         self.behavior = restored.behavior;
         self.workflow = restored.workflow;
         let focus = self.behavior.pending_owner().unwrap_or(self.selected);
-        if let Some(layer) = self.project().layer_of(focus) {
+        if let Some(layer) = self
+            .behavior
+            .creation
+            .pending_layer()
+            .or_else(|| self.project().layer_of(focus))
+        {
             self.layer = layer;
             self.explorer_index = crate::explorer::Index::new(self.project(), layer);
             self.active_diagram = self.diagram_for(layer, focus);
@@ -209,6 +214,16 @@ impl App {
             .is_some_and(architecture_authoring::State::inline)
         {
             Task::batch([lint, iced::widget::operation::focus("architecture-name")])
+        } else if self.page == Page::Behavior && self.behavior.source_open() {
+            Task::batch([
+                lint,
+                iced::widget::operation::focus(behavior::source_draft::NAME_INPUT),
+            ])
+        } else if self.page == Page::Behavior && self.behavior.creation.created().is_some() {
+            Task::batch([
+                lint,
+                iced::widget::operation::focus(behavior::creation::NAME_INPUT),
+            ])
         } else {
             lint
         }

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/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/creation.rs

@@ -0,0 +1,766 @@
+//! Local behavior creation. A draft is not a model object: only its validated
+//! batch may cross Document::execute, and acknowledgement follows success.
+use iced::{
+    Element as UiElement, Fill,
+    widget::{button, checkbox, column, container, row, scrollable, text, text_input},
+};
+use oa_core::*;
+use serde::{Deserialize, Serialize};
+
+const PAGE_SIZE: usize = 6;
+pub const NAME_INPUT: &str = "behavior-creation-name";
+
+// A focused text input consumes Escape. Preserve the application's modal
+// priority by emitting its ordinary Escape message from this narrow bridge.
+pub fn subscription(active: bool) -> iced::Subscription<()> {
+    if active {
+        iced::event::listen_with(captured_escape)
+    } else {
+        iced::Subscription::none()
+    }
+}
+
+fn captured_escape(
+    event: iced::Event,
+    status: iced::event::Status,
+    _: iced::window::Id,
+) -> Option<()> {
+    (status == iced::event::Status::Captured
+        && matches!(
+            event,
+            iced::Event::Keyboard(iced::keyboard::Event::KeyPressed {
+                key: iced::keyboard::Key::Named(iced::keyboard::key::Named::Escape),
+                ..
+            })
+        ))
+    .then_some(())
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Family {
+    Sequence,
+    Scenario,
+    Machine,
+}
+impl Family {
+    fn kind(self, layer: Layer) -> Kind {
+        match (self, layer) {
+            (Self::Sequence, Layer::Oa) => Kind::Process,
+            (Self::Sequence, Layer::Sa) => Kind::FunctionalChain,
+            (Self::Scenario, _) => Kind::Scenario,
+            (Self::Machine, _) => Kind::StateMachine,
+        }
+    }
+    fn title(self, layer: Layer) -> &'static str {
+        match (self, layer) {
+            (Self::Sequence, Layer::Oa) => "Operational process",
+            (Self::Sequence, Layer::Sa) => "Functional chain",
+            (Self::Scenario, _) => "Scenario",
+            (Self::Machine, _) => "State machine",
+        }
+    }
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Picker {
+    Owner,
+    Context,
+}
+impl Picker {
+    fn index(self) -> usize {
+        match self {
+            Self::Owner => 0,
+            Self::Context => 1,
+        }
+    }
+}
+#[derive(Debug, Clone)]
+pub enum Event {
+    Source(super::source_draft::Event),
+    Open(Layer),
+    Choose(Family),
+    Name(String),
+    Owner(Id),
+    Viewpoint(ScenarioViewpoint),
+    Context(Option<Id>),
+    ContextOptions(bool),
+    FirstView(bool),
+    Search(Picker, String),
+    Page(Picker, usize),
+    Cancel,
+    Submit,
+}
+#[derive(Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Browser {
+    query: String,
+    page: usize,
+}
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Draft {
+    #[serde(default)]
+    source: super::source_draft::State,
+    #[serde(default = "Id::new_v4")]
+    invocation: Id,
+
+    version: u32,
+    document: Id,
+    layer: Layer,
+    family: Option<Family>,
+    name: String,
+    owner: Option<Id>,
+    viewpoint: Option<ScenarioViewpoint>,
+    context: Option<Id>,
+    #[serde(default)]
+    context_open: bool,
+    first_view: bool,
+    element: Id,
+    diagram: Id,
+    placement: Id,
+    browsers: [Browser; 2],
+}
+#[derive(Default)]
+pub struct State {
+    draft: Option<Draft>,
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Created {
+    pub behavior: Id,
+    pub layer: Layer,
+    pub diagram: Option<Id>,
+}
+
+impl State {
+    pub fn source_active(&self) -> bool {
+        self.draft.as_ref().is_some_and(|d| d.source.engaged())
+    }
+
+    pub fn source_open(&self) -> bool {
+        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())
+    }
+
+    pub fn has_pending(&self) -> bool {
+        self.draft.is_some()
+    }
+    pub fn pending_layer(&self) -> Option<Layer> {
+        self.draft.as_ref().map(|d| d.layer)
+    }
+    /// Capture this before successful acknowledgement; never select these IDs
+    /// on mere planning or a rejected source/model transaction.
+    pub fn created(&self) -> Option<Created> {
+        let d = self.draft.as_ref()?;
+        d.family.map(|family| Created {
+            behavior: d.element,
+            layer: d.layer,
+            diagram: (family == Family::Machine && d.first_view).then_some(d.diagram),
+        })
+    }
+    /// Match before execution, then apply this target only after success.
+    /// Identity alone is insufficient: changed bodies or trailing operations
+    /// must not inherit the prepared creation's selection/opening contract.
+    pub fn created_by(&self, p: &Project, command: &Command) -> Option<Created> {
+        let target = self.created()?;
+        (self.prepare_pending(p).ok().as_ref() == Some(command)).then_some(target)
+    }
+    pub fn recovery_snapshot(&self) -> Result<Option<serde_json::Value>, String> {
+        self.draft
+            .as_ref()
+            .map(serde_json::to_value)
+            .transpose()
+            .map_err(|e| e.to_string())
+    }
+    pub fn from_recovery(value: serde_json::Value) -> Result<Self, String> {
+        let draft: Draft = serde_json::from_value(value).map_err(|e| e.to_string())?;
+        if draft.version != 1 {
+            return Err("Unsupported behavior creation draft version.".into());
+        }
+        // Raw values and stale references remain editable; planning validates
+        // against the current document rather than silently fixing the draft.
+        Ok(Self { draft: Some(draft) })
+    }
+    pub fn acknowledge_commit(&mut self) {
+        self.draft = None;
+    }
+    pub fn prepare_pending(&self, p: &Project) -> Result<Command, String> {
+        self.draft
+            .as_ref()
+            .ok_or("Choose New to start a behavior.")?
+            .command(p)
+    }
+    pub fn update(&mut self, p: &Project, event: Event) -> Result<Option<Command>, String> {
+        if let Event::Source(event) = event {
+            if self
+                .draft
+                .as_mut()
+                .ok_or("Start the consumer form first.")?
+                .source
+                .dismiss(&event)?
+            {
+                return Ok(None);
+            }
+            let d = self
+                .draft
+                .as_ref()
+                .ok_or("Start the consumer form first.")?;
+            if d.family != Some(Family::Machine) {
+                return Err("This reference does not support staged source creation.".into());
+            }
+            if d.document != p.id {
+                return Err("This behavior draft belongs to another document.".into());
+            }
+            let mut next = d.clone();
+            if let Some(id) = next.source.update(
+                p,
+                super::source_draft::Scope::Machine { layer: d.layer },
+                d.invocation,
+                event,
+            )? {
+                next.owner = Some(id);
+                let preview = next
+                    .source
+                    .preview(p, next.owner)?
+                    .ok_or("New owner preview is missing.")?;
+                if !eligible(&preview, next.layer, Picker::Owner, id) {
+                    return Err("This participant cannot own the machine.".into());
+                }
+            }
+            self.draft = Some(next);
+            return Ok(None);
+        }
+        if self.source_open() && !matches!(&event, Event::Cancel) {
+            return Err("Use the new source or go Back before editing the parent form.".into());
+        }
+
+        match event {
+            Event::Cancel => {
+                self.draft = None;
+                return Ok(None);
+            }
+            Event::Open(layer) => {
+                if self.has_pending() {
+                    return Err("Create or cancel the pending behavior first.".into());
+                }
+                self.draft = Some(Draft {
+                    source: Default::default(),
+                    invocation: Id::new_v4(),
+                    version: 1,
+                    document: p.id,
+                    layer,
+                    family: None,
+                    name: String::new(),
+                    owner: None,
+                    viewpoint: None,
+                    context: None,
+                    context_open: false,
+                    first_view: false,
+                    element: Id::new_v4(),
+                    diagram: Id::new_v4(),
+                    placement: Id::new_v4(),
+                    browsers: Default::default(),
+                });
+                return Ok(None);
+            }
+            Event::Submit => return self.prepare_pending(p).map(Some),
+            _ => {}
+        }
+        let d = self
+            .draft
+            .as_mut()
+            .ok_or("Choose New to start a behavior.")?;
+        if d.document != p.id {
+            return Err("This draft belongs to another document. Cancel it to start here.".into());
+        }
+        match event {
+            Event::Choose(family) => {
+                if d.family.is_some_and(|old| old != family) {
+                    return Err(
+                        "Cancel this draft before choosing a different behavior family.".into(),
+                    );
+                }
+                d.family = Some(family);
+            }
+            Event::Name(name) => d.name = name,
+            Event::Owner(id) if d.family == Some(Family::Machine) => {
+                if !eligible(p, d.layer, Picker::Owner, id) {
+                    return Err("Choose an existing participant in this layer.".into());
+                }
+                d.owner = Some(id);
+            }
+            Event::Viewpoint(viewpoint) if d.family == Some(Family::Scenario) => {
+                if !viewpoints(d.layer).contains(&viewpoint) {
+                    return Err("Choose a scenario viewpoint from this layer.".into());
+                }
+                d.viewpoint = Some(viewpoint);
+            }
+            Event::Context(id) if d.family == Some(Family::Scenario) => {
+                if id.is_some_and(|id| !eligible(p, d.layer, Picker::Context, id)) {
+                    return Err("Choose an existing same-layer scenario context.".into());
+                }
+                d.context = id;
+            }
+            Event::ContextOptions(open) if d.family == Some(Family::Scenario) => {
+                d.context_open = open;
+            }
+            Event::FirstView(value) if d.family == Some(Family::Machine) => d.first_view = value,
+            Event::Search(picker, query) => d.browsers[picker.index()] = Browser { query, page: 0 },
+            Event::Page(picker, page) => d.browsers[picker.index()].page = page,
+            Event::Cancel | Event::Open(_) | Event::Submit => unreachable!(),
+            _ => return Err("That field does not apply to this behavior family.".into()),
+        }
+        Ok(None)
+    }
+}
+
+fn viewpoints(layer: Layer) -> [ScenarioViewpoint; 2] {
+    match layer {
+        Layer::Oa => [
+            ScenarioViewpoint::OperationalActivity,
+            ScenarioViewpoint::ParticipantInteraction,
+        ],
+        Layer::Sa => [
+            ScenarioViewpoint::Functional,
+            ScenarioViewpoint::BoundaryInterface,
+        ],
+    }
+}
+fn viewpoint_title(viewpoint: ScenarioViewpoint) -> &'static str {
+    match viewpoint {
+        ScenarioViewpoint::OperationalActivity => "Activities · operational exchanges",
+        ScenarioViewpoint::ParticipantInteraction => "Participants · interactions",
+        ScenarioViewpoint::Functional => "Functions · functional exchanges",
+        ScenarioViewpoint::BoundaryInterface => "System boundary · interface exchanges",
+        ScenarioViewpoint::MixedLegacy => "Legacy mixed viewpoint",
+    }
+}
+fn eligible(p: &Project, layer: Layer, picker: Picker, id: Id) -> bool {
+    p.elements.get(&id).is_some_and(|e| {
+        e.layer() == layer
+            && match picker {
+                Picker::Owner => validation::parent_permits(e.kind(), Kind::StateMachine),
+                Picker::Context => {
+                    e.kind().is_sequence()
+                        || e.kind().is_work()
+                        || e.kind().is_performer()
+                        || matches!(
+                            e.kind(),
+                            Kind::Capability
+                                | Kind::SystemCapability
+                                | Kind::OperationalMission
+                                | Kind::Mission
+                        )
+                }
+            }
+    })
+}
+fn choices<'a>(p: &'a Project, layer: Layer, picker: Picker, query: &str) -> Vec<&'a Element> {
+    let query = query.trim().to_lowercase();
+    let mut matches: Vec<_> = p
+        .elements
+        .values()
+        .filter(|e| eligible(p, layer, picker, e.id))
+        .filter(|e| query.is_empty() || reference_label(p, e.id).to_lowercase().contains(&query))
+        .collect();
+    matches.sort_by(|a, b| {
+        a.name
+            .to_lowercase()
+            .cmp(&b.name.to_lowercase())
+            .then(a.id.cmp(&b.id))
+    });
+    matches
+}
+
+fn reference_context(p: &Project, e: &Element) -> String {
+    let mut names = Vec::new();
+    let mut parent = e.parent;
+    let mut seen = std::collections::BTreeSet::new();
+    while let Some(id) = parent {
+        if !seen.insert(id) {
+            break;
+        }
+        let Some(ancestor) = p.elements.get(&id) else {
+            break;
+        };
+        names.push(ancestor.name.as_str());
+        parent = ancestor.parent;
+    }
+    names.reverse();
+    let location = if names.is_empty() {
+        format!("{} root", e.layer())
+    } else {
+        format!("{} / {}", e.layer(), names.join(" / "))
+    };
+    format!("{} · {} · {location}", e.kind(), e.alias)
+}
+pub(super) fn reference_label(p: &Project, id: Id) -> String {
+    p.elements
+        .get(&id)
+        .map(|e| format!("{} · {}", e.name, reference_context(p, e)))
+        .unwrap_or_else(|| "Missing element — choose a replacement".into())
+}
+impl Draft {
+    fn command(&self, p: &Project) -> Result<Command, String> {
+        self.source.check_scope(
+            super::source_draft::Scope::Machine { layer: self.layer },
+            self.owner,
+        )?;
+        let preview = self.source.preview(p, self.owner)?;
+        let command = self.consumer_command(preview.as_ref().unwrap_or(p))?;
+        self.source.combine(p, self.owner, command)
+    }
+    fn consumer_command(&self, p: &Project) -> Result<Command, String> {
+        if self.document != p.id {
+            return Err("This draft belongs to another document.".into());
+        }
+        let family = self
+            .family
+            .ok_or("Choose the behavior you want to create.")?;
+        if self.name.trim().is_empty() {
+            return Err("Enter the behavior's name before creating it.".into());
+        }
+        if [self.element, self.diagram, self.placement]
+            .into_iter()
+            .any(|id| p.contains(id))
+            || self.element == self.diagram
+            || self.element == self.placement
+            || self.diagram == self.placement
+        {
+            return Err(
+                "A reserved creation identity is already in use. Cancel and start a fresh draft."
+                    .into(),
+            );
+        }
+        let kind = family.kind(self.layer);
+        let parent = if family == Family::Machine {
+            Some(
+                self.owner
+                    .filter(|id| eligible(p, self.layer, Picker::Owner, *id))
+                    .ok_or("Choose the participant that owns this state machine.")?,
+            )
+        } else {
+            if self.owner.is_some() {
+                return Err("Processes and scenarios belong at the layer root; context is a separate reference.".into());
+            }
+            None
+        };
+        if family != Family::Machine && self.first_view {
+            return Err("A state view can only accompany a state machine.".into());
+        }
+        let mut body = ElementBody::new(kind, self.layer)
+            .ok_or("This behavior is unavailable in this layer.")?;
+        if family == Family::Scenario {
+            let viewpoint = self
+                .viewpoint
+                .filter(|v| viewpoints(self.layer).contains(v))
+                .ok_or("Choose the scenario's viewpoint explicitly.")?;
+            if self
+                .context
+                .is_some_and(|id| !eligible(p, self.layer, Picker::Context, id))
+            {
+                return Err(
+                    "The selected scenario context is missing or no longer compatible.".into(),
+                );
+            }
+            body = ElementBody::shared_in(
+                self.layer,
+                SharedBody::Scenario {
+                    viewpoint,
+                    context: self.context,
+                    precondition: String::new(),
+                    postcondition: String::new(),
+                    steps: Vec::new(),
+                },
+            );
+        } else if self.viewpoint.is_some() || self.context.is_some() {
+            return Err(
+                "Scenario viewpoint and context cannot be applied to another behavior family."
+                    .into(),
+            );
+        }
+        let element = Element {
+            id: self.element,
+            alias: p.fresh_alias(&self.name, "behavior", self.element),
+            name: self.name.clone(),
+            description: String::new(),
+            parent,
+            body,
+        };
+        let mut commands = vec![Command::CreateElement(element)];
+        if self.first_view {
+            let working = execute_batch(p, &commands).map_err(|e| e.to_string())?;
+            // Reuse the state editor's geometry contract. A new machine has one
+            // root placement; reserve both presentation IDs across retries.
+            let plan = super::state_edit::create_view(&working, self.element)
+                .map_err(|e| e.to_string())?;
+            let Command::Batch(mut view_commands) = plan.command else {
+                return Err("Unexpected state-view plan.".into());
+            };
+            if view_commands.len() != 2 {
+                return Err("Unexpected additional operation in the first state-view plan.".into());
+            }
+            let Some(Command::Layout(layout)) = view_commands.pop() else {
+                return Err("State-view plan must finish with its layout operation.".into());
+            };
+            let Some(Command::CreateDiagram(mut diagram)) = view_commands.pop() else {
+                return Err("State-view plan is missing its diagram.".into());
+            };
+            if diagram.id != layout || diagram.nodes.len() != 1 {
+                return Err("A first state view must contain only its new machine.".into());
+            }
+            let mut node = diagram
+                .nodes
+                .into_values()
+                .next()
+                .ok_or("State-view root is missing.")?;
+            if node.element != self.element {
+                return Err("State-view root differs from the new machine.".into());
+            }
+            diagram.id = self.diagram;
+            diagram.alias = working.fresh_alias(&diagram.name, "state_view", self.diagram);
+            node.id = self.placement;
+            node.alias = working.fresh_alias(
+                &format!("{} placement", self.name),
+                "placement",
+                self.placement,
+            );
+            diagram.nodes = [(node.id, node)].into_iter().collect();
+            commands.push(Command::CreateDiagram(diagram));
+            commands.push(Command::Layout(self.diagram));
+        }
+        let command = Command::Batch(commands);
+        execute_batch(p, std::slice::from_ref(&command)).map_err(|e| e.to_string())?;
+        Ok(command)
+    }
+}
+
+impl State {
+    /// Parent maps these local events into the existing guarded Behavior route.
+    /// The card's fields scroll; Create/Cancel stay outside that scroll region.
+    pub fn view<'a>(&'a self, p: &'a Project) -> Option<UiElement<'a, Event>> {
+        self.view_with(p)
+    }
+    fn view_with<'a, R: iced::advanced::text::Renderer + 'a>(
+        &'a self,
+        p: &'a Project,
+    ) -> Option<UiElement<'a, Event, iced::Theme, R>> {
+        let d = self.draft.as_ref()?;
+        if let Some(view) = d.source.view(p) {
+            return Some(
+                column![
+                    text(format!(
+                        "State machine name: {}",
+                        crate::views::short(&d.name, 60)
+                    ))
+                    .size(12),
+                    view.map(Event::Source)
+                ]
+                .spacing(6)
+                .height(Fill)
+                .into(),
+            );
+        }
+        let mut fields = column![].spacing(10);
+        let title = if let Some(family) = d.family {
+            fields = fields.push(
+                text_input("Exact behavior name", &d.name)
+                    .id(NAME_INPUT)
+                    .on_input(Event::Name)
+                    .on_submit(Event::Submit)
+                    .padding(8),
+            );
+            match family {
+                Family::Sequence => {
+                    fields = fields.push(
+                        text(format!(
+                            "Owned by the {} layer root. Add work and exchange contributions after creation.",
+                            d.layer
+                        ))
+                        .size(12),
+                    );
+                }
+                Family::Scenario => {
+                    fields = fields.push(
+                        text(format!(
+                            "Owned by the {} layer root. Choose what the lifelines represent:",
+                            d.layer
+                        ))
+                        .size(12),
+                    );
+                    for viewpoint in viewpoints(d.layer) {
+                        fields = fields.push(
+                            button(text(viewpoint_title(viewpoint)).size(13))
+                                .style(if d.viewpoint == Some(viewpoint) {
+                                    button::primary
+                                } else {
+                                    button::secondary
+                                })
+                                .on_press(Event::Viewpoint(viewpoint))
+                                .padding(7),
+                        );
+                    }
+                    let context_label = if d.context_open {
+                        "Hide optional context".into()
+                    } else if let Some(id) = d.context {
+                        format!("Context: {} · Change…", reference_label(p, id))
+                    } else {
+                        "Add optional context…".into()
+                    };
+                    fields = fields.push(
+                        button(text(context_label).size(12))
+                            .on_press(Event::ContextOptions(!d.context_open))
+                            .padding(6),
+                    );
+                    if d.context_open {
+                        fields = fields.push(picker_view(p, d, Picker::Context));
+                    }
+                }
+                Family::Machine => {
+                    if let Some(label) = d.source.label(d.owner) {
+                        fields = fields.push(text(label).size(13)).push(text("Create and open commits the new owner and machine together, including the first view only when selected.").size(12));
+                    }
+                    fields = fields.push(picker_view(p, d, Picker::Owner));
+                    fields = fields.push(
+                        button("Create new owner…")
+                            .on_press(Event::Source(super::source_draft::Event::Open(
+                                d.invocation,
+                            )))
+                            .padding(7),
+                    );
+                    fields = fields.push(
+                        checkbox(d.first_view)
+                            .label("Create the first state view")
+                            .on_toggle(Event::FirstView),
+                    );
+                    fields = fields.push(text("The machine starts without regions or states. Add those explicitly in its workspace.").size(12));
+                }
+            }
+            format!("New {}", family.title(d.layer))
+        } else {
+            for family in [Family::Sequence, Family::Scenario, Family::Machine] {
+                let purpose = match family {
+                    Family::Sequence => "A path through work and exchanges",
+                    Family::Scenario => "Ordered interactions from an explicit viewpoint",
+                    Family::Machine => "States and modes of an explicitly chosen participant",
+                };
+                fields = fields.push(
+                    button(
+                        column![text(family.title(d.layer)).size(15), text(purpose).size(12)]
+                            .spacing(3),
+                    )
+                    .on_press(Event::Choose(family))
+                    .padding(10)
+                    .width(Fill),
+                );
+            }
+            format!("New behavior · {}", d.layer)
+        };
+        let mut actions =
+            row![button("Cancel · Esc").on_press(Event::Cancel).padding(8)].spacing(8);
+        if d.family.is_some() {
+            actions = actions.push(button("Create and open").on_press(Event::Submit).padding(8));
+        }
+        Some(
+            container(
+                column![
+                    text(title).size(20),
+                    scrollable(fields)
+                        .id("behavior-creation-fields")
+                        .height(Fill),
+                    container(actions).id("behavior-creation-actions")
+                ]
+                .spacing(12),
+            )
+            .padding(18)
+            .max_width(680)
+            .height(Fill)
+            .style(crate::style::card)
+            .into(),
+        )
+    }
+}
+fn picker_view<'a, R: iced::advanced::text::Renderer + 'a>(
+    p: &'a Project,
+    d: &'a Draft,
+    picker: Picker,
+) -> UiElement<'a, Event, iced::Theme, R> {
+    let browser = &d.browsers[picker.index()];
+    let options = choices(p, d.layer, picker, &browser.query);
+    let page = browser
+        .page
+        .min(options.len().saturating_sub(1) / PAGE_SIZE);
+    let selected = match picker {
+        Picker::Owner => d.owner,
+        Picker::Context => d.context,
+    };
+    let staged_owner = picker == Picker::Owner && d.source.label(selected).is_some();
+    let title = match picker {
+        Picker::Owner if staged_owner => "Or choose an existing participant",
+        Picker::Owner => "Owned by participant",
+        Picker::Context => "Scenario context · optional",
+    };
+    let mut out = column![
+        text(title).size(13),
+        text_input("Search names, aliases or parent context", &browser.query)
+            .on_input(move |query| Event::Search(picker, query))
+            .padding(6)
+    ]
+    .spacing(5);
+    if let Some(id) = selected
+        && !staged_owner
+    {
+        out = out.push(text(format!("Selected: {}", reference_label(p, id))).size(12));
+    } else if picker == Picker::Context {
+        out = out.push(text("No context selected").size(12));
+    }
+    if options.is_empty() {
+        out = out.push(text(match picker {
+            Picker::Owner if staged_owner => "No existing participants match this search. The new owner above remains selected.",
+            Picker::Owner => "No matching participant. Refine the search or choose Create new owner.",
+            Picker::Context => "No matching context. Refine the search, or leave this optional reference empty.",
+        }).size(12));
+    }
+    for e in options.iter().skip(page * PAGE_SIZE).take(PAGE_SIZE) {
+        let message = match picker {
+            Picker::Owner => Event::Owner(e.id),
+            Picker::Context => Event::Context(Some(e.id)),
+        };
+        out = out.push(
+            container(
+                button(
+                    column![
+                        text(&e.name).size(13),
+                        text(reference_context(p, e)).size(11)
+                    ]
+                    .spacing(2),
+                )
+                .style(if selected == Some(e.id) {
+                    button::primary
+                } else {
+                    button::secondary
+                })
+                .on_press(message)
+                .padding(6)
+                .width(Fill),
+            )
+            .id(format!("behavior-creation-candidate-{}", e.id)),
+        );
+    }
+    let mut navigation = row![text(format!("{} matches", options.len())).size(11)].spacing(8);
+    if page > 0 {
+        navigation = navigation.push(button("Previous").on_press(Event::Page(picker, page - 1)));
+    }
+    if (page + 1) * PAGE_SIZE < options.len() {
+        navigation = navigation.push(button("Next").on_press(Event::Page(picker, page + 1)));
+    }
+    if picker == Picker::Context && selected.is_some() {
+        navigation = navigation.push(button("Clear context").on_press(Event::Context(None)));
+    }
+    out.push(navigation).into()
+}
+
+#[cfg(test)]
+mod app_tests;
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior/creation/app_tests.rs

@@ -0,0 +1,340 @@
+//! App-boundary regressions for the coordinated parent wiring. No I/O task is
+//! polled: file dialogs, checkpoint writes and lesson loading remain inactive.
+use super::*;
+use crate::app::{App, Message, Page, Pending};
+use std::sync::Arc;
+
+fn send(app: &mut App, event: Event) {
+    let _ = app.update(Message::Behavior(crate::behavior::Event::Creation(event)));
+}
+fn raw_property(app: &App) -> serde_json::Value {
+    serde_json::to_value(app.draft.as_ref().unwrap().recovery_snapshot()).unwrap()
+}
+fn begin(app: &mut App, layer: Layer, family: Family, name: &str) {
+    let _ = app.update(Message::Layer(layer));
+    let _ = app.update(Message::Page(Page::Behavior));
+    send(app, Event::Open(layer));
+    send(app, Event::Choose(family));
+    send(app, Event::Name(name.into()));
+}
+
+fn focused_escape() -> Message {
+    use iced::advanced::{Layout, Shell, layout, widget};
+    use iced::keyboard::{self, key::Named};
+    let mut input: iced::Element<'_, (), iced::Theme, ()> = text_input("Name", "Unfinished name")
+        .id(NAME_INPUT)
+        .on_input(|_| ())
+        .into();
+    let mut tree = widget::Tree::new(input.as_widget());
+    let size = iced::Size::new(300., 40.);
+    let node =
+        input
+            .as_widget_mut()
+            .layout(&mut tree, &(), &layout::Limits::new(iced::Size::ZERO, size));
+    tree.state
+        .downcast_mut::<iced::widget::text_input::State<()>>()
+        .focus();
+    let event = iced::Event::Keyboard(keyboard::Event::KeyPressed {
+        key: keyboard::Key::Named(Named::Escape),
+        modified_key: keyboard::Key::Named(Named::Escape),
+        physical_key: keyboard::key::Physical::Code(keyboard::key::Code::Escape),
+        location: keyboard::Location::Standard,
+        modifiers: keyboard::Modifiers::empty(),
+        text: None,
+        repeat: false,
+    });
+    let mut messages = Vec::new();
+    let mut shell = Shell::new(&mut messages);
+    input.as_widget_mut().update(
+        &mut tree,
+        &event,
+        Layout::new(&node),
+        iced::mouse::Cursor::Unavailable,
+        &(),
+        &mut iced::advanced::clipboard::Null,
+        &mut shell,
+        &iced::Rectangle::new(iced::Point::ORIGIN, size),
+    );
+    assert!(shell.is_event_captured());
+    assert_eq!(
+        captured_escape(
+            event.clone(),
+            iced::event::Status::Ignored,
+            iced::window::Id::unique()
+        ),
+        None
+    );
+    captured_escape(
+        event,
+        iced::event::Status::Captured,
+        iced::window::Id::unique(),
+    )
+    .unwrap();
+    Message::Escape
+}
+
+#[test]
+fn app_first_captured_escape_dismisses_file_or_pending_overlay_before_creation() {
+    for file in [false, true] {
+        let mut app = App::with_project(Project::empty());
+        begin(
+            &mut app,
+            Layer::Oa,
+            Family::Sequence,
+            "Keep while overlay closes",
+        );
+        let raw = app.behavior.recovery_snapshot().unwrap();
+        let accepted = app.document.snapshot();
+        if file {
+            app.file_prompt = Some(crate::app::FilePrompt {
+                operation: crate::app::FileOperation::Save,
+                path: "unsubmitted-name.arcadia".into(),
+                overwrite: false,
+            });
+        } else {
+            app.pending = Some(Pending::Walkthrough);
+        }
+        let _ = app.update(focused_escape());
+        assert!(app.file_prompt.is_none());
+        assert!(app.pending.is_none());
+        assert_eq!(app.behavior.recovery_snapshot().unwrap(), raw);
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        let _ = app.update(focused_escape());
+        assert!(!app.behavior.has_pending());
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        assert!(!app.document.can_undo());
+    }
+}
+
+#[test]
+fn app_creation_opens_the_actual_new_owner_instead_of_first_or_previously_active_behavior() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut p = Project::empty();
+        let old = p
+            .add_element(Family::Sequence.kind(layer), layer, "Old behavior", None)
+            .unwrap();
+        let mut app = App::with_project(p.clone());
+        let _ = app.update(Message::Select(old));
+        begin(&mut app, layer, Family::Sequence, "  New exact path 雨  ");
+        let target = app.behavior.creation.created().unwrap();
+        assert_ne!(target.behavior, old);
+        let before = app.document.bundle().clone();
+        send(&mut app, Event::Submit);
+        assert_eq!(app.page, Page::Behavior);
+        assert_eq!(app.layer, layer);
+        assert_eq!(app.selected, target.behavior);
+        assert_eq!(app.behavior.active_owner, Some(target.behavior));
+        assert_eq!(crate::behavior::selected_owner(&app), Some(target.behavior));
+        assert_eq!(
+            app.project().elements[&target.behavior].name,
+            "  New exact path 雨  "
+        );
+        assert!(!app.behavior.has_pending());
+        let after = app.document.bundle().clone();
+        let _ = app.update(Message::Undo);
+        assert_eq!(app.document.bundle(), &before);
+        assert!(!app.document.can_undo());
+        let _ = app.update(Message::Redo);
+        assert_eq!(app.document.bundle(), &after);
+        assert_eq!(app.project().elements[&old], p.elements[&old]);
+    }
+}
+
+#[test]
+fn app_machine_behavior_submit_opens_its_opted_in_view_as_one_undoable_transaction() {
+    for first_view in [false, true] {
+        let mut p = Project::empty();
+        let owner = p
+            .add_element(Kind::System, Layer::Sa, "Flight system", None)
+            .unwrap();
+        let mut app = App::with_project(p.clone());
+        begin(&mut app, Layer::Sa, Family::Machine, "  Flight modes 雨  ");
+        send(&mut app, Event::Owner(owner));
+        send(&mut app, Event::FirstView(first_view));
+        let target = app.behavior.creation.created().unwrap();
+        let before = app.document.bundle().clone();
+        let _ = app.update(Message::Behavior(crate::behavior::Event::Submit));
+        assert!(!app.behavior.has_pending(), "{}", app.status);
+        assert_eq!(app.selected, target.behavior);
+        assert_eq!(app.behavior.active_owner, Some(target.behavior));
+        assert_eq!(app.behavior.diagram.diagram, target.diagram);
+        assert_eq!(
+            crate::behavior::state_view::diagram(&app, target.behavior),
+            target.diagram
+        );
+        assert_eq!(app.project().elements[&target.behavior].parent, Some(owner));
+        assert_eq!(app.page, Page::Behavior);
+        let after = app.document.bundle().clone();
+        let _ = app.update(Message::Undo);
+        assert_eq!(app.document.bundle(), &before);
+        assert_eq!(app.project(), &p);
+        assert!(!app.document.can_undo());
+        let _ = app.update(Message::Redo);
+        assert_eq!(app.document.bundle(), &after);
+    }
+}
+
+#[test]
+fn app_stale_layer_open_never_starts_or_replaces_a_draft() {
+    let mut app = App::with_project(Project::empty());
+    let _ = app.update(Message::Layer(Layer::Sa));
+    app.page = Page::Behavior;
+    let accepted = app.document.snapshot();
+    send(&mut app, Event::Open(Layer::Oa));
+    assert!(!app.behavior.has_pending());
+    assert_eq!(app.layer, Layer::Sa);
+    send(&mut app, Event::Open(Layer::Sa));
+    send(&mut app, Event::Choose(Family::Sequence));
+    send(&mut app, Event::Name("Retained system chain".into()));
+    let raw = app.behavior.recovery_snapshot().unwrap();
+    send(&mut app, Event::Open(Layer::Oa));
+    assert_eq!(app.behavior.recovery_snapshot().unwrap(), raw);
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+}
+
+#[test]
+fn app_new_never_auto_applies_valid_or_invalid_property_and_source_drafts() {
+    for dirty in [
+        "property-valid",
+        "property-invalid",
+        "source-valid",
+        "source-invalid",
+    ] {
+        let mut app = App::with_project(Project::empty());
+        app.page = Page::Behavior;
+        match dirty {
+            "property-valid" => app
+                .draft
+                .as_mut()
+                .unwrap()
+                .input("/name", "Raw property name".into()),
+            "property-invalid" => app.draft.as_mut().unwrap().input("/id", "-".into()),
+            "source-valid" => app.source_workspace.edit(
+                format!("{}\n// Retained comment\n", app.source_workspace.text()),
+                app.source_editor.cursor(),
+            ),
+            _ => app
+                .source_workspace
+                .edit("unfinished source 雨".into(), app.source_editor.cursor()),
+        }
+        let accepted = app.document.snapshot();
+        let property = raw_property(&app);
+        let workspace = app.source_workspace.recovery_snapshot();
+        send(&mut app, Event::Open(Layer::Oa));
+        assert!(
+            !app.behavior.creation.has_pending(),
+            "{dirty}: New must refuse without applying another editor"
+        );
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        assert_eq!(raw_property(&app), property);
+        assert_eq!(
+            serde_json::to_value(app.source_workspace.recovery_snapshot()).unwrap(),
+            serde_json::to_value(workspace).unwrap()
+        );
+        assert!(!app.document.can_undo());
+    }
+}
+
+#[test]
+fn app_choosing_another_behavior_or_layer_cannot_commit_a_creation_draft() {
+    let mut p = Project::empty();
+    let old = p
+        .add_element(Kind::Process, Layer::Oa, "Old process", None)
+        .unwrap();
+    let mut app = App::with_project(p);
+    begin(&mut app, Layer::Oa, Family::Sequence, "Retain this process");
+    let raw = app.behavior.recovery_snapshot().unwrap();
+    let accepted = app.document.snapshot();
+    let _ = app.update(Message::Layer(Layer::Sa));
+    let _ = app.update(Message::BehaviorOwner(crate::app::Choice {
+        id: old,
+        label: "Old process".into(),
+    }));
+    assert_eq!(app.layer, Layer::Oa);
+    assert_eq!(app.behavior.recovery_snapshot().unwrap(), raw);
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    let _ = app.update(Message::Escape);
+    assert!(!app.behavior.has_pending());
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    assert!(!app.document.can_undo());
+}
+
+#[test]
+fn app_lesson_request_cancel_retains_creation_then_escape_discards_only_the_draft() {
+    let mut app = App::with_project(Project::empty());
+    begin(
+        &mut app,
+        Layer::Oa,
+        Family::Sequence,
+        "Unfinished engineering path",
+    );
+    let raw = app.behavior.recovery_snapshot().unwrap();
+    let accepted = app.document.snapshot();
+    let task = app.update(Message::Home(crate::home::Event::Walkthrough));
+    assert!(matches!(app.pending, Some(Pending::Walkthrough)));
+    assert!(iced_runtime::task::into_stream(task).is_none());
+    let _ = app.update(Message::Escape);
+    assert!(app.pending.is_none());
+    assert_eq!(app.behavior.recovery_snapshot().unwrap(), raw);
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    let _ = app.update(Message::Escape);
+    assert!(!app.behavior.has_pending());
+    assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+}
+
+#[test]
+fn app_recovered_rootless_sa_creation_retains_layer_ids_and_other_raw_drafts() {
+    let mut app = App::with_project(Project::empty());
+    begin(
+        &mut app,
+        Layer::Sa,
+        Family::Scenario,
+        "  Recovered system scenario 雨  ",
+    );
+    send(
+        &mut app,
+        Event::Viewpoint(ScenarioViewpoint::BoundaryInterface),
+    );
+    // Recovery can contain simultaneous drafts even though new input is guarded.
+    app.draft
+        .as_mut()
+        .unwrap()
+        .input("/name", "Retained property".into());
+    app.source_workspace.edit(
+        "unfinished source preserved".into(),
+        app.source_editor.cursor(),
+    );
+    let snapshot = crate::recovery::Snapshot::capture(
+        app.canvas_document,
+        &app.document,
+        &app.source_workspace,
+        app.draft.as_ref(),
+        &app.behavior,
+        None,
+        app.selected,
+    )
+    .unwrap();
+    let expected = snapshot.clone().restore().unwrap();
+    let raw = app.behavior.recovery_snapshot().unwrap();
+    let mut restored = App::with_project(Project::empty());
+    let _ = restored.update(Message::CheckpointLoaded(Ok(Arc::new(snapshot))));
+    assert_eq!(restored.page, Page::Behavior);
+    assert_eq!(restored.layer, Layer::Sa);
+    assert_eq!(restored.behavior.recovery_snapshot().unwrap(), raw);
+    assert_eq!(
+        restored.behavior.creation.created(),
+        app.behavior.creation.created()
+    );
+    assert_eq!(restored.project(), expected.document.project());
+    assert_eq!(restored.document.bundle(), expected.document.bundle());
+    assert_eq!(
+        restored.source_workspace.bundle(),
+        expected.workspace.bundle()
+    );
+    assert_eq!(raw_property(&restored), raw_property(&app));
+    let before = restored.document.snapshot();
+    send(&mut restored, Event::Submit);
+    assert!(Arc::ptr_eq(&before, &restored.document.snapshot()));
+    assert_eq!(restored.behavior.recovery_snapshot().unwrap(), raw);
+    assert_eq!(raw_property(&restored), raw_property(&app));
+}

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

@@ -0,0 +1,599 @@
+use super::*;
+use crate::document::Document;
+use oa_core::source_project::ProjectLimits;
+
+fn start(p: &Project, layer: Layer, family: Family, name: &str) -> State {
+    let mut state = State::default();
+    assert!(state.update(p, Event::Open(layer)).unwrap().is_none());
+    state.update(p, Event::Choose(family)).unwrap();
+    state.update(p, Event::Name(name.into())).unwrap();
+    state
+}
+
+#[test]
+fn mounted_creation_keeps_actions_visible_and_renders_only_six_owner_candidates() {
+    use iced::advanced::{Layout, layout, widget};
+    use iced::{Rectangle, Size, Vector};
+    struct Geometry {
+        candidates: Vec<widget::Id>,
+        rendered: Vec<widget::Id>,
+        actions: Option<Rectangle>,
+        fields: Option<Rectangle>,
+    }
+    impl widget::Operation for Geometry {
+        fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation)) {
+            visit(self);
+        }
+        fn container(&mut self, id: Option<&widget::Id>, bounds: Rectangle) {
+            if id == Some(&widget::Id::new("behavior-creation-actions")) {
+                self.actions = Some(bounds);
+            }
+            if let Some(id) = id.filter(|id| self.candidates.contains(id)) {
+                self.rendered.push(id.clone());
+            }
+        }
+        fn scrollable(
+            &mut self,
+            id: Option<&widget::Id>,
+            bounds: Rectangle,
+            _: Rectangle,
+            _: Vector,
+            _: &mut dyn widget::operation::Scrollable,
+        ) {
+            if id == Some(&widget::Id::new("behavior-creation-fields")) {
+                self.fields = Some(bounds);
+            }
+        }
+    }
+    let mut p = Project::empty();
+    for index in 0..105 {
+        p.add_element(
+            Kind::Entity,
+            Layer::Oa,
+            &format!(
+                "{index:03} Long engineering participant name {}",
+                "雨 extended ".repeat(20)
+            ),
+            None,
+        )
+        .unwrap();
+    }
+    let candidates: Vec<_> = p
+        .elements
+        .keys()
+        .map(|id| widget::Id::from(format!("behavior-creation-candidate-{id}")))
+        .collect();
+    for family in [Family::Sequence, Family::Scenario, Family::Machine] {
+        let state = start(&p, Layer::Oa, family, "Very long exact behavior name 雨");
+        for size in [
+            Size::new(500., 570.),
+            Size::new(1050., 570.),
+            Size::new(500., 320.),
+        ] {
+            let mut view: UiElement<'_, Event, iced::Theme, ()> = state.view_with(&p).unwrap();
+            let mut tree = widget::Tree::new(view.as_widget());
+            let node =
+                view.as_widget_mut()
+                    .layout(&mut tree, &(), &layout::Limits::new(Size::ZERO, size));
+            let mut geometry = Geometry {
+                candidates: candidates.clone(),
+                rendered: Vec::new(),
+                actions: None,
+                fields: None,
+            };
+            view.as_widget_mut()
+                .operate(&mut tree, Layout::new(&node), &(), &mut geometry);
+            let actions = geometry.actions.unwrap();
+            let fields = geometry.fields.unwrap();
+            assert!(actions.x >= 0. && actions.y >= 0.);
+            assert!(
+                actions.x + actions.width <= size.width
+                    && actions.y + actions.height <= size.height
+            );
+            assert!(fields.height >= 100. && fields.y + fields.height <= actions.y);
+            assert_eq!(
+                geometry.rendered.len(),
+                if family == Family::Machine { 6 } else { 0 }
+            );
+        }
+    }
+}
+
+fn roundtrip(p: Project, state: &mut State) -> Project {
+    let command = state.update(&p, Event::Submit).unwrap().unwrap();
+    assert_eq!(
+        command,
+        state.prepare_pending(&p).unwrap(),
+        "preparation must retain reserved IDs"
+    );
+    let api: Command = serde_json::from_value(serde_json::to_value(&command).unwrap()).unwrap();
+    assert_eq!(api, command);
+    let expected = execute_batch(&p, &[api]).unwrap();
+    let target = state.created().unwrap();
+    let mut document = Document::from_project(p.clone(), ProjectLimits::default()).unwrap();
+    let before_source = document.bundle().clone();
+    document.execute(command).unwrap();
+    assert_eq!(document.project(), &expected);
+    assert!(
+        state.has_pending(),
+        "only successful acknowledgement clears raw fields"
+    );
+    state.acknowledge_commit();
+    assert!(!state.has_pending());
+    assert!(document.project().elements.contains_key(&target.behavior));
+    let after_source = document.bundle().clone();
+    assert!(document.undo());
+    assert_eq!(document.project(), &p);
+    assert_eq!(document.bundle(), &before_source);
+    assert!(!document.can_undo(), "one creation must be one Undo entry");
+    assert!(document.redo());
+    assert_eq!(document.project(), &expected);
+    assert_eq!(document.bundle(), &after_source);
+    let reopened = Document::from_bundle(after_source, ProjectLimits::default()).unwrap();
+    assert_eq!(reopened.project(), &expected);
+    expected
+}
+
+#[test]
+fn oa_process_and_sa_chain_keep_exact_names_root_ownership_and_one_history_entry() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let p = Project::empty();
+        let name = "  Supply \"water\" — режим  ";
+        let mut state = start(&p, layer, Family::Sequence, name);
+        let target = state.created().unwrap();
+        let result = roundtrip(p, &mut state);
+        let element = &result.elements[&target.behavior];
+        assert_eq!(element.name, name);
+        assert_eq!(element.layer(), layer);
+        assert_eq!(
+            element.kind(),
+            if layer == Layer::Oa {
+                Kind::Process
+            } else {
+                Kind::FunctionalChain
+            }
+        );
+        assert_eq!(element.parent, None);
+        assert!(element.steps().unwrap().is_empty());
+        assert!(result.diagrams.is_empty());
+        assert!(result.relations.is_empty());
+    }
+}
+
+#[test]
+fn all_four_viewpoints_are_explicit_and_survive_source_history_reopen() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        for viewpoint in viewpoints(layer) {
+            let mut p = Project::empty();
+            let context = p
+                .add_element(
+                    if layer == Layer::Oa {
+                        Kind::Capability
+                    } else {
+                        Kind::SystemCapability
+                    },
+                    layer,
+                    "Water supply",
+                    None,
+                )
+                .unwrap();
+            let mut state = start(&p, layer, Family::Scenario, "Nominal supply");
+            assert!(
+                state
+                    .prepare_pending(&p)
+                    .unwrap_err()
+                    .contains("explicitly")
+            );
+            assert!(
+                state
+                    .update(&p, Event::Viewpoint(ScenarioViewpoint::MixedLegacy))
+                    .is_err()
+            );
+            let wrong = viewpoints(if layer == Layer::Oa {
+                Layer::Sa
+            } else {
+                Layer::Oa
+            })[0];
+            assert!(state.update(&p, Event::Viewpoint(wrong)).is_err());
+            state.update(&p, Event::Viewpoint(viewpoint)).unwrap();
+            state.update(&p, Event::Context(Some(context))).unwrap();
+            let id = state.created().unwrap().behavior;
+            let result = roundtrip(p, &mut state);
+            assert_eq!(
+                result.elements[&id].parent, None,
+                "context is not containment"
+            );
+            assert!(
+                matches!(result.elements[&id].shared(), Some(SharedBody::Scenario { viewpoint: actual, context: Some(actual_context), steps, .. }) if *actual == viewpoint && *actual_context == context && steps.is_empty())
+            );
+        }
+    }
+}
+
+#[test]
+fn machine_requires_valid_owner_and_first_view_adds_no_region_or_state() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        for first_view in [false, true] {
+            let mut p = Project::empty();
+            let owner = p
+                .add_element(
+                    if layer == Layer::Oa {
+                        Kind::Entity
+                    } else {
+                        Kind::System
+                    },
+                    layer,
+                    "Pump",
+                    None,
+                )
+                .unwrap();
+            let wrong_kind = p
+                .add_element(
+                    if layer == Layer::Oa {
+                        Kind::Activity
+                    } else {
+                        Kind::Function
+                    },
+                    layer,
+                    "Pump water",
+                    None,
+                )
+                .unwrap();
+            let opposite = if layer == Layer::Oa {
+                Layer::Sa
+            } else {
+                Layer::Oa
+            };
+            let wrong_layer = p
+                .add_element(
+                    if opposite == Layer::Oa {
+                        Kind::Entity
+                    } else {
+                        Kind::System
+                    },
+                    opposite,
+                    "Other layer pump",
+                    None,
+                )
+                .unwrap();
+            let mut state = start(&p, layer, Family::Machine, "Pump modes");
+            assert!(
+                state
+                    .prepare_pending(&p)
+                    .unwrap_err()
+                    .contains("participant")
+            );
+            assert!(state.update(&p, Event::Owner(wrong_kind)).is_err());
+            assert!(state.update(&p, Event::Owner(wrong_layer)).is_err());
+            state.update(&p, Event::Owner(owner)).unwrap();
+            state.update(&p, Event::FirstView(first_view)).unwrap();
+            let target = state.created().unwrap();
+            let expected_count = p.elements.len() + 1;
+            let result = roundtrip(p, &mut state);
+            assert_eq!(result.elements.len(), expected_count);
+            assert_eq!(result.elements[&target.behavior].parent, Some(owner));
+            assert_eq!(result.elements[&target.behavior].kind(), Kind::StateMachine);
+            assert_eq!(result.diagrams.len(), usize::from(first_view));
+            if let Some(view) = target.diagram {
+                let diagram = &result.diagrams[&view];
+                assert_eq!(
+                    diagram.projection,
+                    ProjectionKind::StateMachine {
+                        machine: target.behavior
+                    }
+                );
+                assert_eq!(diagram.nodes.len(), 1);
+                assert_eq!(
+                    diagram.nodes.values().next().unwrap().element,
+                    target.behavior
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn cancel_and_illegal_family_layer_switches_never_create_model_objects() {
+    let p = Project::empty();
+    let mut state = start(&p, Layer::Oa, Family::Scenario, "Raw name");
+    state
+        .update(
+            &p,
+            Event::Viewpoint(ScenarioViewpoint::ParticipantInteraction),
+        )
+        .unwrap();
+    let snapshot = state.recovery_snapshot().unwrap();
+    assert!(state.update(&p, Event::Open(Layer::Sa)).is_err());
+    assert!(state.update(&p, Event::Choose(Family::Sequence)).is_err());
+    assert_eq!(state.recovery_snapshot().unwrap(), snapshot);
+    assert!(state.update(&p, Event::Cancel).unwrap().is_none());
+    assert!(!state.has_pending());
+    assert!(state.created().is_none());
+    assert!(state.prepare_pending(&p).is_err());
+    assert!(p.elements.is_empty());
+    assert!(p.diagrams.is_empty());
+}
+
+#[test]
+fn recovery_preserves_exact_raw_inputs_reserved_ids_and_revalidates_stale_owner() {
+    let mut p = Project::empty();
+    let owner = p
+        .add_element(Kind::Entity, Layer::Oa, "Plant", None)
+        .unwrap();
+    let mut state = start(&p, Layer::Oa, Family::Machine, " \nRaw rejected name\0 ");
+    state.update(&p, Event::Owner(owner)).unwrap();
+    state.update(&p, Event::FirstView(true)).unwrap();
+    state
+        .update(&p, Event::Search(Picker::Owner, " Plant ".into()))
+        .unwrap();
+    let raw = state.recovery_snapshot().unwrap().unwrap();
+    let mut restored = State::from_recovery(raw.clone()).unwrap();
+    assert_eq!(restored.recovery_snapshot().unwrap(), Some(raw.clone()));
+    assert_eq!(restored.created(), state.created());
+    assert_eq!(restored.pending_layer(), Some(Layer::Oa));
+    assert!(restored.prepare_pending(&p).is_err());
+    restored
+        .update(&p, Event::Name("Plant modes".into()))
+        .unwrap();
+    let command = restored.prepare_pending(&p).unwrap();
+    let again = State::from_recovery(restored.recovery_snapshot().unwrap().unwrap()).unwrap();
+    assert_eq!(again.prepare_pending(&p).unwrap(), command);
+    p.elements.remove(&owner);
+    let before = restored.recovery_snapshot().unwrap();
+    assert!(
+        restored
+            .prepare_pending(&p)
+            .unwrap_err()
+            .contains("participant")
+    );
+    assert_eq!(restored.recovery_snapshot().unwrap(), before);
+    let different = Project::empty();
+    assert!(
+        restored
+            .prepare_pending(&different)
+            .unwrap_err()
+            .contains("another document")
+    );
+}
+
+#[test]
+fn rejected_source_transaction_keeps_draft_and_every_accepted_source_byte() {
+    let p = Project::empty();
+    let initial = Document::from_project(p.clone(), ProjectLimits::default()).unwrap();
+    let bytes: usize = initial.bundle().files.values().map(String::len).sum();
+    let limits = ProjectLimits {
+        model: language::ParseLimits {
+            max_source_bytes: bytes + 32,
+            ..language::ParseLimits::UNLIMITED
+        },
+        ..ProjectLimits::default()
+    };
+    let mut doc = Document::from_bundle(initial.bundle().clone(), limits).unwrap();
+    let mut state = start(
+        &p,
+        Layer::Oa,
+        Family::Sequence,
+        "A long exact name retained after the source budget refuses this new process",
+    );
+    let raw = state.recovery_snapshot().unwrap();
+    let command = state.prepare_pending(&p).unwrap();
+    assert!(doc.execute(command).is_err());
+    assert_eq!(doc.project(), &p);
+    assert_eq!(doc.bundle(), initial.bundle());
+    assert!(!doc.can_undo());
+    assert_eq!(state.recovery_snapshot().unwrap(), raw);
+    state.update(&p, Event::Cancel).unwrap();
+}
+
+#[test]
+fn owner_search_is_name_ordered_filtered_and_page_sized_not_a_catalog() {
+    let mut p = Project::empty();
+    for index in (0..105).rev() {
+        p.add_element(Kind::Entity, Layer::Oa, &format!("Pump {index:03}"), None)
+            .unwrap();
+    }
+    p.add_element(Kind::System, Layer::Sa, "Pump 999", None)
+        .unwrap();
+    p.add_element(Kind::Activity, Layer::Oa, "Pump work", None)
+        .unwrap();
+    let mut state = start(&p, Layer::Oa, Family::Machine, "Pump modes");
+    let all = choices(&p, Layer::Oa, Picker::Owner, "");
+    assert_eq!(all.len(), 105);
+    assert_eq!(all[0].name, "Pump 000");
+    state
+        .update(&p, Event::Page(Picker::Owner, usize::MAX))
+        .unwrap();
+    assert!(
+        state.view(&p).is_some(),
+        "stale pages are clamped before slicing"
+    );
+    state
+        .update(&p, Event::Search(Picker::Owner, "Pump 104".into()))
+        .unwrap();
+    assert_eq!(state.draft.as_ref().unwrap().browsers[0].page, 0);
+    let found = choices(&p, Layer::Oa, Picker::Owner, "Pump 104");
+    assert_eq!(found.len(), 1);
+    state.update(&p, Event::Owner(found[0].id)).unwrap();
+    assert_eq!(state.draft.as_ref().unwrap().owner, Some(found[0].id));
+}
+
+#[test]
+fn repeated_owner_names_remain_distinguishable_by_searchable_parent_context_and_alias() {
+    let mut p = Project::empty();
+    let north = p
+        .add_element(Kind::Entity, Layer::Oa, "North station", None)
+        .unwrap();
+    let south = p
+        .add_element(Kind::Entity, Layer::Oa, "South station", None)
+        .unwrap();
+    let first = p
+        .add_element(Kind::Entity, Layer::Oa, "Pump", Some(north))
+        .unwrap();
+    let second = p
+        .add_element(Kind::Entity, Layer::Oa, "Pump", Some(south))
+        .unwrap();
+    let label = reference_label(&p, second);
+    assert_ne!(reference_label(&p, first), label);
+    assert!(label.contains("South station") && label.contains("Pump"));
+    assert!(label.contains(&p.elements[&second].alias));
+    let found = choices(&p, Layer::Oa, Picker::Owner, "south station");
+    assert!(found.iter().any(|e| e.id == second));
+    assert!(!found.iter().any(|e| e.id == first));
+    let mut state = start(&p, Layer::Oa, Family::Machine, "Pump states");
+    state.update(&p, Event::Owner(second)).unwrap();
+    let result = execute_batch(&p, &[state.prepare_pending(&p).unwrap()]).unwrap();
+    assert_eq!(
+        result.elements[&state.created().unwrap().behavior].parent,
+        Some(second)
+    );
+}
+
+#[test]
+fn corrupted_recovery_and_reserved_identity_collision_refuse_without_repairing_raw_values() {
+    let p = Project::empty();
+    let state = start(&p, Layer::Sa, Family::Sequence, "Supply");
+    let raw = state.recovery_snapshot().unwrap().unwrap();
+    for (field, value) in [
+        ("version", serde_json::json!(99)),
+        ("unexpected", serde_json::json!(true)),
+    ] {
+        let mut bad = raw.clone();
+        bad[field] = value;
+        assert!(State::from_recovery(bad).is_err());
+    }
+    let mut bad = raw;
+    bad["element"] = serde_json::json!(p.id);
+    let restored = State::from_recovery(bad.clone()).unwrap();
+    assert!(
+        restored
+            .prepare_pending(&p)
+            .unwrap_err()
+            .contains("identity")
+    );
+    assert_eq!(restored.recovery_snapshot().unwrap(), Some(bad));
+}
+
+#[test]
+fn post_commit_selection_is_correlated_with_exact_created_behavior_and_view() {
+    let mut p = Project::empty();
+    let owner = p
+        .add_element(Kind::Entity, Layer::Oa, "Pump", None)
+        .unwrap();
+    let mut state = start(&p, Layer::Oa, Family::Machine, "Pump modes");
+    state.update(&p, Event::Owner(owner)).unwrap();
+    state.update(&p, Event::FirstView(true)).unwrap();
+    let command = state.prepare_pending(&p).unwrap();
+    assert_eq!(state.created_by(&p, &command), state.created());
+    assert_eq!(
+        state.created_by(&p, &Command::Rename(owner, "Unrelated change".into())),
+        None
+    );
+    for edit in 0..4 {
+        let mut changed = command.clone();
+        let Command::Batch(ref mut commands) = changed else {
+            panic!("creation batch");
+        };
+        if edit < 3 {
+            let Command::CreateElement(element) = &mut commands[0] else {
+                panic!("new behavior");
+            };
+            match edit {
+                0 => element.id = Id::new_v4(),
+                1 => element.name = "A different authored draft".into(),
+                _ => element.parent = None,
+            }
+        } else {
+            let Command::CreateDiagram(diagram) = &mut commands[1] else {
+                panic!("new view");
+            };
+            diagram.projection = ProjectionKind::StateMachine { machine: owner };
+        }
+        assert_eq!(state.created_by(&p, &changed), None);
+    }
+    let Command::Batch(commands) = command else {
+        panic!("creation batch");
+    };
+    assert_eq!(
+        state.created_by(&p, &commands[0]),
+        None,
+        "an opt-in view must be part of the actual committed batch"
+    );
+}
+
+#[test]
+fn optional_context_collapses_without_losing_authored_reference_or_raw_search() {
+    let mut p = Project::empty();
+    let context = p
+        .add_element(Kind::Capability, Layer::Oa, "Water supply", None)
+        .unwrap();
+    let mut state = start(&p, Layer::Oa, Family::Scenario, "Supply nominal");
+    assert!(!state.draft.as_ref().unwrap().context_open);
+    state
+        .update(&p, Event::Viewpoint(ScenarioViewpoint::OperationalActivity))
+        .unwrap();
+    state.update(&p, Event::ContextOptions(true)).unwrap();
+    state
+        .update(&p, Event::Search(Picker::Context, " Water ".into()))
+        .unwrap();
+    state.update(&p, Event::Context(Some(context))).unwrap();
+    let command = state.prepare_pending(&p).unwrap();
+    state.update(&p, Event::ContextOptions(false)).unwrap();
+    let restored = State::from_recovery(state.recovery_snapshot().unwrap().unwrap()).unwrap();
+    assert!(!restored.draft.as_ref().unwrap().context_open);
+    assert_eq!(
+        restored.draft.as_ref().unwrap().browsers[1].query,
+        " Water "
+    );
+    assert_eq!(restored.prepare_pending(&p).unwrap(), command);
+    assert_eq!(restored.created_by(&p, &command), restored.created());
+}
+
+#[test]
+fn creation_selection_rejects_changed_scenario_body_and_post_creation_operations() {
+    let mut p = Project::empty();
+    let capability = p
+        .add_element(Kind::SystemCapability, Layer::Sa, "Supply", None)
+        .unwrap();
+    let mut state = start(&p, Layer::Sa, Family::Scenario, "Nominal functions");
+    state
+        .update(&p, Event::Viewpoint(ScenarioViewpoint::Functional))
+        .unwrap();
+    let command = state.prepare_pending(&p).unwrap();
+    assert_eq!(state.created_by(&p, &command), state.created());
+    for edit in 0..4 {
+        let mut altered = command.clone();
+        let Command::Batch(commands) = &mut altered else {
+            panic!("creation batch");
+        };
+        match edit {
+            0 => {
+                let Command::CreateElement(element) = &mut commands[0] else {
+                    panic!("scenario");
+                };
+                let Some(SharedBody::Scenario { viewpoint, .. }) = element.shared_mut() else {
+                    panic!("scenario body");
+                };
+                *viewpoint = ScenarioViewpoint::BoundaryInterface;
+            }
+            1 => {
+                let Command::CreateElement(element) = &mut commands[0] else {
+                    panic!("scenario");
+                };
+                let Some(SharedBody::Scenario { context, .. }) = element.shared_mut() else {
+                    panic!("scenario body");
+                };
+                *context = Some(capability);
+            }
+            2 => commands.push(Command::Rename(
+                state.created().unwrap().behavior,
+                "Changed afterward".into(),
+            )),
+            _ => commands.push(Command::Delete(state.created().unwrap().behavior)),
+        }
+        assert!(
+            execute_batch(&p, std::slice::from_ref(&altered)).is_ok(),
+            "the alternate command is valid, but is not this authored creation"
+        );
+        assert_eq!(state.created_by(&p, &altered), None);
+    }
+}

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)]
@@ -97,7 +100,9 @@ pub enum CanvasEvent {
     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),
@@ -125,8 +130,7 @@ 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 {
@@ -135,7 +139,9 @@ impl CanvasEvent {
             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, _)
@@ -162,6 +168,7 @@ impl std::fmt::Display for Operator {
 }
 #[derive(Debug, Clone)]
 pub enum Event {
+    Source(super::source_draft::Event),
     Start(Id, Tool),
     Cancel,
     Submit,
@@ -197,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;
@@ -211,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 {
@@ -240,6 +249,13 @@ struct CallChoiceContext {
 #[derive(Clone, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 struct Draft {
+    #[serde(default)]
+    source: super::source_draft::State,
+    #[serde(default = "Id::new_v4")]
+    invocation: Id,
+    #[serde(default)]
+    source_origin: Option<(Id, oa_core::Element)>,
+
     owner: Id,
     parent: Id,
     before: Option<Id>,
@@ -272,6 +288,44 @@ 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())
+    }
+    pub(super) fn source_view<'a>(&'a self, p: &'a Project) -> Option<iced::Element<'a, Event>> {
+        self.draft
+            .as_ref()?
+            .source
+            .view(p)
+            .map(|v| v.map(Event::Source))
+    }
+
+    pub fn source_active(&self) -> bool {
+        self.draft.as_ref().is_some_and(|d| d.source.engaged())
+    }
+
+    pub fn source_open(&self) -> bool {
+        self.draft.as_ref().is_some_and(|d| d.source.is_open())
+    }
+    pub fn source_back(&mut self) -> bool {
+        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) {
         if self.presentation.identity != Some((document, owner)) {
             self.presentation = workspace::Presentation {
@@ -279,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
     }
@@ -317,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)
     }
@@ -348,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(
@@ -385,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> {
@@ -413,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,
@@ -452,8 +543,16 @@ impl State {
         }
         cached.as_ref().unwrap().1.clone()
     }
-    pub(crate) fn created_selection(&self, command: &Command) -> Option<Id> {
+    pub(crate) fn created_selection(&self, p: &Project, command: &Command) -> Option<Id> {
         let draft = self.draft.as_ref()?;
+        if self
+            .draft
+            .as_ref()
+            .is_some_and(|d| d.source.label(d.target).is_some())
+            && self.prepare_pending(p).ok().as_ref() != Some(command)
+        {
+            return None;
+        }
         fn created(command: &Command, parent: Id) -> Option<Id> {
             match command {
                 Command::CreateElement(element) if element.parent == Some(parent) => {
@@ -568,6 +667,66 @@ impl State {
     }
 
     pub fn update(&mut self, p: &Project, event: Event) -> Result<Option<Command>, String> {
+        if let Event::Source(event) = event {
+            if self
+                .draft
+                .as_mut()
+                .ok_or("Start the consumer form first.")?
+                .source
+                .dismiss(&event)?
+            {
+                self.remount_form();
+                return Ok(None);
+            }
+            let d = self
+                .draft
+                .as_ref()
+                .ok_or("Start the consumer form first.")?;
+            if d.tool != Tool::Lifeline {
+                return Err("This reference does not support staged source creation.".into());
+            }
+            if d.source_origin.as_ref().is_some_and(|(document, owner)| {
+                *document != p.id || p.elements.get(&d.owner) != Some(owner)
+            }) {
+                return Err("The original consumer changed. Cancel and reopen its form; the current draft is retained.".into());
+            }
+            if d.source_origin.is_none() && d.source.engaged() {
+                return Err("The recovered source draft has no original document binding. Go Back or cancel it.".into());
+            }
+            let mut next = d.clone();
+            if next.source_origin.is_none() && matches!(&event, super::source_draft::Event::Open(_))
+            {
+                next.source_origin = Some((
+                    p.id,
+                    p.elements
+                        .get(&d.owner)
+                        .ok_or("The consumer owner no longer exists.")?
+                        .clone(),
+                ));
+            }
+            if let Some(id) = next.source.update(
+                p,
+                super::source_draft::Scope::Lifeline {
+                    owner: d.owner,
+                    viewpoint: viewpoint(p, d.owner),
+                },
+                d.invocation,
+                event,
+            )? {
+                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) {
+            return Err("Use the new source or go Back before editing the parent form.".into());
+        }
+
         if self.draft.is_some() && matches!(&event, Event::Start(..)) {
             return Err(PENDING_DRAFT.into());
         }
@@ -576,7 +735,13 @@ 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(),
+                    source_origin: Some((p.id, p.elements[&owner].clone())),
                     owner,
                     parent: owner,
                     before: None,
@@ -940,7 +1105,14 @@ fn valid_body_choice(p: &Project, owner: Id, body: OccurrenceBody) -> bool {
     execute_batch(p, &[Command::CreateElement(e)]).is_ok()
 }
 fn sources(p: &Project, d: &Draft) -> Vec<Choice> {
-    let layer = p.elements[&d.owner].layer();
+    let Some(owner) = p
+        .elements
+        .get(&d.owner)
+        .filter(|e| e.kind() == Kind::Scenario)
+    else {
+        return vec![];
+    };
+    let layer = owner.layer();
     let mut values: Vec<_> = p
         .elements
         .values()
@@ -1256,6 +1428,28 @@ impl Draft {
         e
     }
     fn command(&self, p: &Project) -> Result<Command, String> {
+        if self.source.engaged()
+            && self.source_origin.as_ref().is_none_or(|(document, owner)| {
+                *document != p.id || p.elements.get(&self.owner) != Some(owner)
+            })
+        {
+            return Err("The original consumer document or owner changed. Cancel and reopen its form; your draft is retained.".into());
+        }
+        self.source.check_scope(
+            super::source_draft::Scope::Lifeline {
+                owner: self.owner,
+                viewpoint: viewpoint(p, self.owner),
+            },
+            self.target,
+        )?;
+        let preview = self.source.preview(p, self.target)?;
+        let command = self.consumer_command(preview.as_ref().unwrap_or(p))?;
+        self.source.combine(p, self.target, command)
+    }
+    fn consumer_command(&self, p: &Project) -> Result<Command, String> {
+        if p.elements.get(&self.owner).map(oa_core::Element::kind) != Some(Kind::Scenario) {
+            return Err("The scenario no longer exists. Cancel or restore its owner.".into());
+        }
         if !parents(p, self.owner).iter().any(|c| c.id == self.parent) {
             return Err("Choose this scenario or one of its operands as destination.".into());
         }
@@ -1266,6 +1460,8 @@ impl Draft {
             .unwrap_or(self.tool.label());
         let name = if self.name.trim().is_empty() {
             default
+        } else if self.source.label(self.target).is_some() {
+            self.name.as_str()
         } else {
             self.name.trim()
         };
@@ -1857,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);
@@ -1881,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);
@@ -1892,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"
             );
@@ -2074,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,
                     );
@@ -2265,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());
@@ -2459,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(),
@@ -2489,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,
@@ -2517,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 [
@@ -2536,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_lifecycle.rs

@@ -2,6 +2,8 @@
 use oa_core::{FragmentOperator, Id, Kind, MessageKind, OccurrenceBody, Project, SharedBody};
 use std::collections::{BTreeMap, BTreeSet};
 
+pub(super) mod render;
+
 /// Maps already recorded by the sequence renderer. Rows carry their owning sequence.
 pub(crate) struct Geometry<'a> {
     pub rows: &'a BTreeMap<Id, (Id, f32)>,

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

@@ -0,0 +1,392 @@
+//! Scene bridge for local lifetime geometry; no authoring or model mutations.
+use super::{Geometry, LaneLifetime, Life, Marker, MarkerKind, Span, project_lifetimes};
+use crate::{behavior::Line, style, views::short};
+use iced::{
+    Color, Point, Rectangle, Size,
+    widget::canvas::{self, Frame, Path, Stroke, Text},
+};
+use oa_core::{Id, OccurrenceBody, Project, SharedBody};
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, PartialEq)]
+struct EventMarker {
+    event: Marker,
+    lifeline: Id,
+    center: Point,
+    capsule: Rectangle,
+    name: String,
+    sender_x: Option<f32>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq)]
+pub(in crate::behavior) struct Rendering {
+    // Complete rendering positions, including warning-admitted unassigned lanes.
+    // Scene.lanes independently retains the existing authoring eligibility rule.
+    lanes: BTreeMap<Id, f32>,
+    span: Option<Span>,
+    lifetimes: Vec<LaneLifetime>,
+    markers: Vec<EventMarker>,
+}
+
+impl Rendering {
+    pub(in crate::behavior) fn new(
+        project: &Project,
+        owner: Id,
+        lanes: &BTreeMap<Id, f32>,
+        rows: &BTreeMap<Id, (Id, f32)>,
+        insertion_scopes: &BTreeMap<Id, (f32, f32)>,
+        height: f32,
+    ) -> Self {
+        let span = Span {
+            start: 85.,
+            end: height - 20.,
+        };
+        if !span.valid() {
+            return Self::default();
+        }
+        // Insertion scopes deliberately start later and end earlier. Empty and
+        // Create-only scenarios still have the full visible lifetime extent.
+        let mut scopes = insertion_scopes.clone();
+        for (scope, (start, end)) in &mut scopes {
+            if *scope != owner && *start == *end && start.is_finite() {
+                // An empty operand has 42 px between its insertion axis and
+                // frame end. Match the existing 26 px open-activation allowance.
+                *end = *start + 26.;
+            }
+        }
+        scopes.insert(owner, (span.start, span.end));
+        let lifetimes = project_lifetimes(
+            project,
+            owner,
+            &Geometry {
+                rows,
+                scopes: &scopes,
+            },
+        );
+        let lanes: BTreeMap<_, _> = lanes
+            .iter()
+            .filter(|(_, x)| x.is_finite())
+            .map(|(id, x)| (*id, *x))
+            .collect();
+        let mut markers = Vec::new();
+        for lane in &lifetimes {
+            let Some(&x) = lanes.get(&lane.lifeline) else {
+                continue;
+            };
+            for event in &lane.markers {
+                let sender_x = project
+                    .elements
+                    .get(&event.occurrence)
+                    .and_then(|e| e.shared())
+                    .and_then(|body| match body {
+                        SharedBody::Occurrence {
+                            body:
+                                OccurrenceBody::Exchange {
+                                    sender: Some(sender),
+                                    ..
+                                },
+                            ..
+                        } => lanes.get(sender).copied(),
+                        _ => None,
+                    });
+                markers.push(EventMarker {
+                    event: *event,
+                    lifeline: lane.lifeline,
+                    center: Point::new(x, event.y),
+                    capsule: Rectangle::new(
+                        Point::new(x - 70., event.y - 14.),
+                        Size::new(140., 28.),
+                    ),
+                    name: project.named(lane.lifeline).to_owned(),
+                    sender_x,
+                });
+            }
+        }
+        Self {
+            lanes,
+            span: Some(span),
+            lifetimes,
+            markers,
+        }
+    }
+
+    pub(in crate::behavior) fn align_messages(&self, lines: &mut [Line]) {
+        for marker in &self.markers {
+            let Some(sender) = marker.sender_x else {
+                continue;
+            };
+            let Some(line) = lines
+                .iter_mut()
+                .find(|line| line.id == marker.event.occurrence)
+            else {
+                continue;
+            };
+            let x = marker.center.x;
+            let y = marker.center.y;
+            let self_message = sender == x;
+            let end_x = match marker.event.kind {
+                MarkerKind::Birth if sender < x => marker.capsule.x,
+                MarkerKind::Birth => marker.capsule.x + marker.capsule.width,
+                MarkerKind::Death => x,
+            };
+            line.points = if self_message {
+                // The receiver is on the recorded occurrence row, including self
+                // lifecycle events. The elbow stays outside the birth capsule.
+                let elbow = x + 112.;
+                line.label_at = Point::new(x + 12., y - 52.);
+                vec![
+                    Point::new(x, y - 24.),
+                    Point::new(elbow, y - 24.),
+                    Point::new(elbow, y),
+                    Point::new(end_x, y),
+                ]
+            } else {
+                if marker.event.kind == MarkerKind::Birth {
+                    // Keep the label above the capsule, including right-to-left
+                    // messages whose existing label starts beside the receiver.
+                    line.label_at.y = y - 40.;
+                }
+                vec![Point::new(sender, y), Point::new(end_x, y)]
+            };
+        }
+    }
+
+    pub(in crate::behavior) fn alive_spans(
+        &self,
+        lifeline: Id,
+        scope: Id,
+        top: f32,
+        bottom: f32,
+    ) -> Vec<Span> {
+        if !top.is_finite() || !bottom.is_finite() || bottom <= top {
+            return vec![];
+        }
+        self.lifetimes
+            .iter()
+            .find(|lane| lane.lifeline == lifeline)
+            .into_iter()
+            .flat_map(|lane| &lane.intervals)
+            .filter(|interval| interval.scope == scope && interval.life == Life::Alive)
+            .filter_map(|interval| {
+                let start = top.max(interval.span.start);
+                let end = bottom.min(interval.span.end);
+                (start < end).then_some(Span { start, end })
+            })
+            .collect()
+    }
+
+    pub(in crate::behavior) fn marker_at(&self, point: Point) -> Option<Id> {
+        self.markers
+            .iter()
+            .rev()
+            .find(|marker| match marker.event.kind {
+                MarkerKind::Birth => marker.capsule.contains(point),
+                MarkerKind::Death => marker_distance(marker, point) <= 1.25,
+            })
+            .map(|marker| marker.event.occurrence)
+    }
+
+    pub(in crate::behavior) fn nearest_marker(&self, point: Point) -> Option<(Id, f32)> {
+        if !point.x.is_finite() || !point.y.is_finite() {
+            return None;
+        }
+        // Exact visible shapes are tested first by Scene. A low-zoom tolerance
+        // must not outrank another marker's actual capsule, a header, or a label.
+        self.markers
+            .iter()
+            .map(|marker| (marker.event.occurrence, marker_distance(marker, point)))
+            .min_by(|a, b| a.1.total_cmp(&b.1).then_with(|| a.0.cmp(&b.0)))
+    }
+
+    pub(in crate::behavior) fn lane_at(&self, point: Point, scale: f32) -> Option<Id> {
+        let span = self.span?;
+        if !scale.is_finite() || scale <= 0. || point.y < span.start || point.y > span.end {
+            return None;
+        }
+        self.lanes
+            .iter()
+            .filter(|(_, x)| (**x - point.x).abs() < 12. / scale)
+            .min_by(|a, b| (a.1 - point.x).abs().total_cmp(&(b.1 - point.x).abs()))
+            .map(|(id, _)| *id)
+    }
+
+    pub(in crate::behavior) fn draw_lanes(&self, frame: &mut Frame, selected: Id) {
+        let Some(span) = self.span else {
+            return;
+        };
+        for (&id, &x) in &self.lanes {
+            frame.stroke(
+                &Path::line(Point::new(x, span.start), Point::new(x, span.end)),
+                Stroke {
+                    line_dash: canvas::LineDash {
+                        segments: &[2., 5.],
+                        offset: 0,
+                    },
+                    ..Stroke::default()
+                        .with_width(1.)
+                        .with_color(if id == selected {
+                            Color::from_rgb8(148, 190, 187)
+                        } else {
+                            Color::from_rgb8(214, 222, 222)
+                        })
+                },
+            );
+        }
+        for lifetime in &self.lifetimes {
+            let Some(&x) = self.lanes.get(&lifetime.lifeline) else {
+                continue;
+            };
+            for interval in &lifetime.intervals {
+                match interval.life {
+                    Life::Alive => frame.stroke(
+                        &Path::line(
+                            Point::new(x, interval.span.start),
+                            Point::new(x, interval.span.end),
+                        ),
+                        Stroke::default().with_width(2.).with_color(
+                            if lifetime.lifeline == selected {
+                                style::TEAL
+                            } else {
+                                Color::from_rgb8(91, 113, 113)
+                            },
+                        ),
+                    ),
+                    Life::Unresolved if interval.span.end - interval.span.start >= 16. => {
+                        frame.fill_text(Text {
+                            content: "?".into(),
+                            position: Point::new(x + 9., interval.span.start + 2.),
+                            size: 11.into(),
+                            color: style::MUTED,
+                            ..Default::default()
+                        });
+                    }
+                    _ => {}
+                }
+            }
+        }
+        if !self.lanes.is_empty() {
+            frame.fill_text(Text {
+                content:
+                    "Dotted: editing guide · Solid: local lifetime · ?: lifetime depends on path"
+                        .into(),
+                position: Point::new(28., span.end + 4.),
+                size: 10.into(),
+                color: style::MUTED,
+                ..Default::default()
+            });
+        }
+    }
+
+    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
+            } else {
+                style::INK
+            };
+            match marker.event.kind {
+                MarkerKind::Birth => {
+                    let path = Path::rounded_rectangle(
+                        marker.capsule.position(),
+                        marker.capsule.size(),
+                        6.into(),
+                    );
+                    frame.fill(&path, Color::from_rgb8(243, 248, 248));
+                    frame.stroke(
+                        &path,
+                        Stroke::default().with_color(color).with_width(
+                            if selected == marker.event.occurrence {
+                                2.5
+                            } else {
+                                1.5
+                            },
+                        ),
+                    );
+                    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 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),
+                                position: marker.capsule.position() + iced::Vector::new(8., 6.),
+                                size: 12.into(),
+                                color,
+                                ..Default::default()
+                            });
+                        });
+                    }
+                }
+                MarkerKind::Death => {
+                    for (a, b) in death_strokes(marker.center) {
+                        frame.stroke(
+                            &Path::line(a, b),
+                            Stroke::default().with_color(color).with_width(2.5),
+                        );
+                    }
+                }
+            }
+        }
+    }
+}
+
+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(
+            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))
+}
+
+fn marker_distance(marker: &EventMarker, point: Point) -> f32 {
+    match marker.event.kind {
+        MarkerKind::Birth => {
+            let dx = (marker.capsule.x - point.x)
+                .max(point.x - marker.capsule.x - marker.capsule.width)
+                .max(0.);
+            let dy = (marker.capsule.y - point.y)
+                .max(point.y - marker.capsule.y - marker.capsule.height)
+                .max(0.);
+            dx.hypot(dy)
+        }
+        MarkerKind::Death => death_strokes(marker.center)
+            .iter()
+            .map(|(a, b)| crate::diagram::distance_to_segment(point, *a, *b))
+            .fold(f32::INFINITY, f32::min),
+    }
+}
+
+fn death_strokes(center: Point) -> [(Point, Point); 2] {
+    [
+        (
+            center + iced::Vector::new(-7., -7.),
+            center + iced::Vector::new(7., 7.),
+        ),
+        (
+            center + iced::Vector::new(-7., 7.),
+            center + iced::Vector::new(7., -7.),
+        ),
+    ]
+}
+
+#[cfg(test)]
+#[path = "render_tests.rs"]
+mod tests;

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

@@ -0,0 +1,973 @@
+use super::*;
+use crate::{behavior::Scene, document::Document};
+use iced::Size;
+use oa_core::*;
+
+struct Fixture {
+    project: Project,
+    owner: Id,
+    sender: Id,
+    receiver: Id,
+    work: Id,
+    exchange: Id,
+}
+impl Fixture {
+    fn new(layer: Layer) -> Self {
+        let mut project = Project::empty();
+        let kind = if layer == Layer::Oa {
+            Kind::Activity
+        } else {
+            Kind::Function
+        };
+        let a = project.add_element(kind, layer, "Request", None).unwrap();
+        let work = project.add_element(kind, layer, "Provide", None).unwrap();
+        let exchange = project.relate(
+            if layer == Layer::Oa {
+                RelationKind::Interaction
+            } else {
+                RelationKind::FunctionalExchange
+            },
+            "Service",
+            a,
+            work,
+        );
+        let owner = project
+            .add_element(Kind::Scenario, layer, "Lifecycle", None)
+            .unwrap();
+        let mut lane = |name, represented| {
+            let id = project
+                .add_element(Kind::Lifeline, layer, name, Some(owner))
+                .unwrap();
+            *project.elements.get_mut(&id).unwrap().shared_mut().unwrap() = SharedBody::Lifeline {
+                represented: Some(represented),
+            };
+            id
+        };
+        let sender = lane("Requester", a);
+        let receiver = lane("Provider", work);
+        Self {
+            project,
+            owner,
+            sender,
+            receiver,
+            work,
+            exchange,
+        }
+    }
+    fn occurrence(&mut self, parent: Id, name: &str, body: OccurrenceBody) -> Id {
+        let mut element = self
+            .project
+            .make_element(
+                Kind::Occurrence,
+                self.project.elements[&parent].layer(),
+                name,
+                Some(parent),
+            )
+            .unwrap();
+        let id = element.id;
+        *element.shared_mut().unwrap() = SharedBody::Occurrence {
+            body,
+            precondition: String::new(),
+            postcondition: String::new(),
+        };
+        self.project.elements.insert(id, element);
+        let parent = self.project.elements.get_mut(&parent).unwrap();
+        if let Some(steps) = parent.steps_mut() {
+            steps.push(id);
+        } else if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Fragment { branches, .. },
+            ..
+        }) = parent.shared_mut()
+        {
+            branches.push(id);
+        } else {
+            panic!("fixture parent must own ordered occurrences or operands");
+        }
+        id
+    }
+    fn message(&mut self, parent: Id, kind: MessageKind) -> Id {
+        self.occurrence(
+            parent,
+            "Message",
+            OccurrenceBody::Exchange {
+                exchange: Some(self.exchange),
+                sender: Some(self.sender),
+                receiver: Some(self.receiver),
+                message_kind: kind,
+                operation: None,
+                reply_to: None,
+                values: vec![],
+            },
+        )
+    }
+    fn fragment(&mut self, parent: Id, operator: FragmentOperator) -> Id {
+        self.occurrence(
+            parent,
+            "Paths",
+            OccurrenceBody::Fragment {
+                operator,
+                branches: vec![],
+            },
+        )
+    }
+    fn branch(&mut self, fragment: Id) -> Id {
+        self.occurrence(
+            fragment,
+            "Operand",
+            OccurrenceBody::Branch {
+                guard: "condition".into(),
+                occurrences: vec![],
+            },
+        )
+    }
+    fn document(&self) -> Document {
+        validate_candidate(&self.project).expect("ordinary core admission must succeed");
+        let mut bundle = source_project::format_bundle(&self.project);
+        for text in bundle.files.values_mut() {
+            *text = format!(
+                "// Retain exact authored CRLF and Unicode Ω\r\n{}",
+                text.replace('\n', "\r\n")
+            );
+        }
+        let document =
+            Document::from_bundle(bundle.clone(), source_project::ProjectLimits::default())
+                .unwrap();
+        assert_eq!(document.project(), &self.project);
+        assert_eq!(document.bundle(), &bundle);
+        document
+    }
+    fn scene(&self) -> Scene {
+        let document = self.document();
+        let before = document.snapshot();
+        let scene = Scene::sequence(document.project(), self.owner, self.owner);
+        assert_eq!(document.project(), &before.decoded.project);
+        assert_eq!(document.bundle(), &before.bundle);
+        assert_eq!(document.revision(), 0);
+        assert!(!document.can_undo() && !document.can_redo() && !document.dirty());
+        assert_eq!(
+            scene.lifecycle,
+            Scene::sequence(document.project(), self.owner, self.owner).lifecycle
+        );
+        assert!(
+            scene
+                .lines
+                .iter()
+                .flat_map(|line| &line.points)
+                .all(|p| p.x.is_finite() && p.y.is_finite())
+        );
+        scene
+    }
+}
+
+fn intervals(scene: &Scene, lifeline: Id, scope: Id) -> Vec<(f32, f32, Life)> {
+    scene
+        .lifecycle
+        .lifetimes
+        .iter()
+        .find(|lane| lane.lifeline == lifeline)
+        .unwrap()
+        .intervals
+        .iter()
+        .filter(|i| i.scope == scope)
+        .map(|i| (i.span.start, i.span.end, i.life))
+        .collect()
+}
+
+#[test]
+fn real_scene_long_header_title_and_detail_keep_names_and_have_bounded_clips() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        for name in [
+            "W".repeat(18),
+            "界".repeat(24),
+            "e\u{301}".repeat(24),
+            "👩\u{200d}🔧".repeat(12),
+        ] {
+            let mut f = Fixture::new(layer);
+            f.project.elements.get_mut(&f.receiver).unwrap().name = name.clone();
+            f.project.elements.get_mut(&f.work).unwrap().name = name.clone();
+            let scene = f.scene();
+            let header = scene.boxes.iter().find(|b| b.id == f.receiver).unwrap();
+            assert_eq!(header.title, format!("Lane · {name}"));
+            assert_eq!(header.detail, name);
+            assert_eq!(header.rect.size(), Size::new(204., 70.));
+            assert_eq!(scene.hit(header.rect.center()), Some(f.receiver));
+            // 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(
+                    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),
+                );
+                assert!((world.x - header.rect.x - 10.).abs() < 0.001);
+                assert!((world.y - header.rect.y - 8.).abs() < 0.001);
+                assert!((world.width - 184.).abs() < 0.001);
+                assert!((world.height - 54.).abs() < 0.001);
+                assert!(header.rect.contains(world.position()));
+                assert!(
+                    header
+                        .rect
+                        .contains(Point::new(world.x + world.width, world.y + world.height,))
+                );
+            }
+        }
+    }
+}
+
+#[test]
+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(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.),
+        ),
+        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(iced::Vector::ZERO, card, 2., viewport), None);
+    }
+    for scale in [0., -1., f32::NAN, f32::INFINITY] {
+        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(
+                iced::Vector::ZERO,
+                Rectangle::new(Point::ORIGIN, size),
+                1.,
+                card.size()
+            ),
+            None
+        );
+    }
+}
+
+#[test]
+fn real_scene_wide_latin_header_exceeds_old_character_budget() {
+    use iced::advanced::text::{self, Paragraph as _};
+    let mut f = Fixture::new(Layer::Oa);
+    f.project.elements.get_mut(&f.receiver).unwrap().name = "W".repeat(18);
+    f.project.elements.get_mut(&f.work).unwrap().name = "W".repeat(24);
+    let scene = f.scene();
+    let header = scene.boxes.iter().find(|b| b.id == f.receiver).unwrap();
+    for (content, size, divisor) in [(&header.title, 13., 7.), (&header.detail, 11., 6.)] {
+        let label = iced::widget::canvas::Text {
+            content: crate::views::short(content, ((header.rect.width - 25.) / divisor) as usize),
+            size: size.into(),
+            ..Default::default()
+        };
+        // Use the same real paragraph/font/shaping defaults as canvas Text.
+        // The native defect survives short(): glyph width, not scalar count,
+        // is what exceeds the card. This is a font witness, not a pixel gate.
+        let paragraph = <iced::Renderer as text::Renderer>::Paragraph::with_text(text::Text {
+            content: label.content.as_str(),
+            bounds: Size::INFINITE,
+            size: label.size,
+            line_height: label.line_height,
+            font: label.font,
+            align_x: label.align_x,
+            align_y: label.align_y,
+            shaping: label.shaping,
+            wrapping: text::Wrapping::default(),
+        });
+        let old_available = header.rect.width - 12.;
+        assert!(
+            paragraph.min_width() > old_available,
+            "wide glyph fixture must overflow the old unbounded card: {} <= {old_available}",
+            paragraph.min_width()
+        );
+    }
+}
+
+#[test]
+fn birth_label_clip_keeps_padded_world_bounds_at_each_scene_scale() {
+    let capsule = Rectangle::new(Point::new(100., 200.), Size::new(140., 28.));
+    for (scale, expected) in [
+        (
+            0.05,
+            Rectangle::new(Point::new(5.4, 10.2), Size::new(6.2, 1.)),
+        ),
+        (
+            0.5,
+            Rectangle::new(Point::new(54., 102.), Size::new(62., 10.)),
+        ),
+        (
+            1.,
+            Rectangle::new(Point::new(108., 204.), Size::new(124., 20.)),
+        ),
+        (
+            2.,
+            Rectangle::new(Point::new(216., 408.), Size::new(248., 40.)),
+        ),
+    ] {
+        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),
+            (clip.width, expected.width),
+            (clip.height, expected.height),
+        ] {
+            assert!((actual - expected).abs() < 0.0001);
+        }
+        assert!(capsule.contains(Point::new(clip.x / scale, clip.y / scale)));
+        assert!(capsule.contains(Point::new(
+            (clip.x + clip.width) / scale,
+            (clip.y + clip.height) / scale,
+        )));
+    }
+}
+
+#[test]
+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(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(
+            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(iced::Vector::ZERO, capsule, 2., viewport),
+            None
+        );
+    }
+    for scale in [0., -1., f32::NAN, f32::INFINITY] {
+        assert_eq!(
+            birth_label_clip(iced::Vector::ZERO, capsule, scale, Size::new(1000., 1000.)),
+            None
+        );
+    }
+}
+
+#[test]
+fn real_scene_empty_and_create_only_use_visible_root_extents_not_insertion_bounds() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        let empty = f.scene();
+        assert_eq!(empty.sequence_bounds[&f.owner], (106., 106.));
+        assert_eq!(
+            intervals(&empty, f.receiver, f.owner),
+            vec![(85., empty.size.height - 20., Life::Alive)]
+        );
+        assert!(empty.lines.is_empty(), "lane guides are not message lines");
+        let create = f.message(f.owner, MessageKind::Create);
+        let scene = f.scene();
+        let birth = scene.rows[&create].1;
+        assert_eq!(birth, 148.);
+        assert_eq!(scene.sequence_bounds[&f.owner], (106., 198.));
+        assert_eq!(
+            intervals(&scene, f.receiver, f.owner),
+            vec![
+                (85., birth, Life::Absent),
+                (birth, scene.size.height - 20., Life::Alive),
+            ]
+        );
+        assert_eq!(
+            intervals(&scene, f.sender, f.owner),
+            vec![(85., scene.size.height - 20., Life::Alive)]
+        );
+        assert_eq!(scene.slots[0].y, 106.);
+        assert_eq!(
+            scene.lane_at(Point::new(scene.lanes[&f.receiver], 90.)),
+            Some(f.receiver)
+        );
+    }
+}
+
+#[test]
+fn real_scene_birth_death_markers_align_endpoints_and_win_selection_without_mutating_source() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        let create = f.message(f.owner, MessageKind::Create);
+        f.occurrence(
+            f.owner,
+            "Work",
+            OccurrenceBody::Action {
+                action: Some(f.work),
+                lifeline: Some(f.receiver),
+            },
+        );
+        let delete = f.message(f.owner, MessageKind::Delete);
+        let mut scene = f.scene();
+        let birth = scene.rows[&create].1;
+        let death = scene.rows[&delete].1;
+        assert_eq!(
+            intervals(&scene, f.receiver, f.owner),
+            vec![
+                (85., birth, Life::Absent),
+                (birth, death, Life::Alive),
+                (death, scene.size.height - 20., Life::Absent),
+            ]
+        );
+        let capsule = scene
+            .lifecycle
+            .markers
+            .iter()
+            .find(|m| m.event.occurrence == create)
+            .unwrap()
+            .capsule;
+        let line = scene.lines.iter().find(|l| l.id == create).unwrap();
+        let expected_x = if scene.lanes[&f.sender] < scene.lanes[&f.receiver] {
+            capsule.x
+        } else {
+            capsule.x + capsule.width
+        };
+        assert_eq!(line.points.last(), Some(&Point::new(expected_x, birth)));
+        assert!(
+            line.label_at.y + 22. < capsule.y,
+            "message caption clears birth capsule"
+        );
+        let line = scene.lines.iter().find(|l| l.id == delete).unwrap();
+        assert_eq!(
+            line.points.last(),
+            Some(&Point::new(scene.lanes[&f.receiver], death))
+        );
+        for scale in [0.5, 1., 2.] {
+            scene.scale = scale;
+            assert_eq!(
+                scene.hit(Point::new(scene.lanes[&f.receiver], birth)),
+                Some(create)
+            );
+            assert_eq!(
+                scene.hit(Point::new(scene.lanes[&f.receiver], death)),
+                Some(delete)
+            );
+            assert_eq!(
+                scene.hit(Point::new(
+                    scene.lanes[&f.receiver],
+                    scene.size.height - 25.
+                )),
+                Some(f.receiver)
+            );
+            assert_eq!(
+                scene.hit(Point::new(scene.lanes[&f.receiver], 40.)),
+                Some(f.receiver)
+            );
+        }
+    }
+}
+
+#[test]
+fn real_scene_branch_delete_clips_only_its_activation_and_keeps_unanswered_call_visible() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        let call = f.message(f.owner, MessageKind::Call);
+        let fragment = f.fragment(f.owner, FragmentOperator::Alternative);
+        let left = f.branch(fragment);
+        let delete = f.message(left, MessageKind::Delete);
+        let right = f.branch(fragment);
+        let scene = f.scene();
+        let death = scene.rows[&delete].1;
+        let (left_start, left_end) = scene.sequence_bounds[&left];
+        let (right_start, _) = scene.sequence_bounds[&right];
+        let bars: Vec<_> = scene
+            .boxes
+            .iter()
+            .filter(|b| b.id == call && b.rect.width == 8.)
+            .map(|b| b.rect)
+            .collect();
+        assert!(
+            bars.iter()
+                .any(|r| r.y == left_start && r.y + r.height == death)
+        );
+        assert!(
+            !bars
+                .iter()
+                .any(|r| r.y < left_end && r.y + r.height > death && r.y >= left_start)
+        );
+        assert!(
+            bars.iter().any(|r| r.y == right_start && r.height == 26.),
+            "empty exclusive sibling retains its own open activation"
+        );
+        assert_eq!(
+            intervals(&scene, f.receiver, right),
+            vec![(right_start, right_start + 26., Life::Alive)]
+        );
+        let frame_end = scene.boxes.iter().find(|b| b.id == fragment).unwrap().rect;
+        assert!(
+            !bars.iter().any(|r| r.y >= frame_end.y + frame_end.height),
+            "uncertain post-fragment lifetime cannot carry a definite activation bar"
+        );
+        assert!(
+            scene
+                .open_calls
+                .iter()
+                .any(|p| p.y < death && p.y > left_start)
+        );
+        assert!(scene.open_calls.iter().any(|p| p.y > right_start));
+        assert_eq!(
+            intervals(&scene, f.receiver, left),
+            vec![
+                (left_start, death, Life::Alive),
+                (death, left_end, Life::Absent)
+            ]
+        );
+        assert_eq!(
+            intervals(&scene, f.receiver, f.owner).last().unwrap().2,
+            Life::Unresolved
+        );
+        assert!(!f.project.elements.values().any(|e| matches!(
+            e.shared(),
+            Some(SharedBody::Occurrence {
+                body: OccurrenceBody::Exchange {
+                    message_kind: MessageKind::Reply,
+                    ..
+                },
+                ..
+            })
+        )));
+    }
+}
+
+#[test]
+fn real_scene_unassigned_lanes_and_explicit_incomplete_receiver_keep_real_marker_identity() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        *f.project
+            .elements
+            .get_mut(&f.receiver)
+            .unwrap()
+            .shared_mut()
+            .unwrap() = SharedBody::Lifeline { represented: None };
+        let create = f.message(f.owner, MessageKind::Create);
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange { exchange, .. },
+            ..
+        }) = f.project.elements.get_mut(&create).unwrap().shared_mut()
+        {
+            *exchange = None;
+        }
+        let scene = f.scene();
+        assert!(
+            !scene.lanes.contains_key(&f.receiver),
+            "authoring eligibility remains separate"
+        );
+        let x = scene.lifecycle.lanes[&f.receiver];
+        assert_eq!(scene.lifecycle.markers[0].lifeline, f.receiver);
+        assert_eq!(
+            scene.hit(Point::new(x, scene.rows[&create].1)),
+            Some(create)
+        );
+        assert_eq!(scene.hit(Point::new(x, 40.)), Some(f.receiver));
+        assert_eq!(
+            scene.hit(Point::new(x, scene.size.height - 25.)),
+            Some(f.receiver)
+        );
+        assert_eq!(scene.lane_at(Point::new(x, 90.)), None);
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange {
+                receiver, exchange, ..
+            },
+            ..
+        }) = f.project.elements.get_mut(&create).unwrap().shared_mut()
+        {
+            *receiver = None;
+            *exchange = Some(f.exchange);
+        }
+        let missing = f.scene();
+        assert!(
+            missing.lifecycle.markers.is_empty(),
+            "do not infer receiver from global exchange"
+        );
+    }
+}
+
+#[test]
+fn real_scene_minimum_zoom_marker_halos_do_not_steal_adjacent_capsule_or_header_hits() {
+    let mut f = Fixture::new(Layer::Sa);
+    *f.project
+        .elements
+        .get_mut(&f.receiver)
+        .unwrap()
+        .shared_mut()
+        .unwrap() = SharedBody::Lifeline { represented: None };
+    let create = f.message(f.owner, MessageKind::Create);
+    let delete = f.message(f.owner, MessageKind::Delete);
+    for event in [create, delete] {
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange { exchange, .. },
+            ..
+        }) = f.project.elements.get_mut(&event).unwrap().shared_mut()
+        {
+            *exchange = None;
+        }
+    }
+    let mut scene = f.scene();
+    let x = scene.lifecycle.lanes[&f.receiver];
+    assert_eq!(scene.rows[&delete].1 - scene.rows[&create].1, 92.);
+    for scale in [0.05, 0.1, 0.5, 1., 2.] {
+        scene.scale = scale;
+        assert_eq!(
+            scene.hit(Point::new(x, scene.rows[&create].1)),
+            Some(create)
+        );
+        assert_eq!(
+            scene.hit(Point::new(x, scene.rows[&delete].1)),
+            Some(delete)
+        );
+        assert_eq!(scene.hit(Point::new(x, 40.)), Some(f.receiver));
+        if scale <= 0.1 {
+            for offset in [-25., -15., 15., 25.] {
+                assert_eq!(
+                    scene.hit(Point::new(x, scene.rows[&delete].1 + offset)),
+                    Some(delete),
+                    "a nearby death halo must beat an earlier message's wider tolerance"
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn real_scene_minimum_zoom_near_ordinary_message_wins_over_lifecycle_halos() {
+    let mut f = Fixture::new(Layer::Sa);
+    f.message(f.owner, MessageKind::Create);
+    let ordinary = f.message(f.owner, MessageKind::Asynchronous);
+    f.message(f.owner, MessageKind::Delete);
+    let mut scene = f.scene();
+    let x = (scene.lanes[&f.sender] + scene.lanes[&f.receiver]) / 2.;
+    for scale in [0.05, 0.1] {
+        scene.scale = scale;
+        assert_eq!(
+            scene.hit(Point::new(x, scene.rows[&ordinary].1 + 2.)),
+            Some(ordinary)
+        );
+    }
+}
+
+#[test]
+fn real_scene_self_lifecycle_elbows_end_on_recorded_marker_rows() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        for kind in [MessageKind::Create, MessageKind::Delete] {
+            let mut f = Fixture::new(layer);
+            let event = f.message(f.owner, kind);
+            if let Some(SharedBody::Occurrence {
+                body:
+                    OccurrenceBody::Exchange {
+                        exchange, sender, ..
+                    },
+                ..
+            }) = f.project.elements.get_mut(&event).unwrap().shared_mut()
+            {
+                *exchange = None;
+                *sender = Some(f.receiver);
+            }
+            let scene = f.scene();
+            let marker = &scene.lifecycle.markers[0];
+            let line = scene.lines.iter().find(|l| l.id == event).unwrap();
+            assert_eq!(line.points.len(), 4);
+            assert_eq!(line.points[0].y, marker.center.y - 24.);
+            assert_eq!(line.points[3].y, marker.center.y);
+            assert_eq!(
+                line.points[3].x,
+                if marker.event.kind == MarkerKind::Birth {
+                    marker.capsule.x + marker.capsule.width
+                } else {
+                    marker.center.x
+                }
+            );
+            assert!(line.points[1].x > marker.capsule.x + marker.capsule.width);
+            assert_eq!(scene.hit(marker.center), Some(event));
+        }
+    }
+}
+
+#[test]
+fn real_scene_self_delete_caption_clears_the_preceding_action_box() {
+    let mut f = Fixture::new(Layer::Sa);
+    let action = f.occurrence(
+        f.owner,
+        "Finish work",
+        OccurrenceBody::Action {
+            action: Some(f.work),
+            lifeline: Some(f.receiver),
+        },
+    );
+    let delete = f.message(f.owner, MessageKind::Delete);
+    if let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange {
+            exchange, sender, ..
+        },
+        ..
+    }) = f.project.elements.get_mut(&delete).unwrap().shared_mut()
+    {
+        *exchange = None;
+        *sender = Some(f.receiver);
+    }
+    let scene = f.scene();
+    let action = scene.boxes.iter().find(|b| b.id == action).unwrap();
+    let line = scene.lines.iter().find(|l| l.id == delete).unwrap();
+    assert!(line.label_at.y > action.rect.y + action.rect.height);
+    assert!(line.label_at.y + 22. < line.points[0].y);
+    assert_eq!(line.points[3].y, scene.rows[&delete].1);
+    assert_eq!(
+        scene
+            .slots
+            .iter()
+            .find(|s| s.slot.before == Some(delete))
+            .unwrap()
+            .y,
+        scene.rows[&delete].1 - 42.
+    );
+}
+
+#[test]
+fn real_scene_conditional_repeated_and_parallel_scopes_do_not_claim_definite_continuation() {
+    for operator in [
+        FragmentOperator::Alternative,
+        FragmentOperator::Optional,
+        FragmentOperator::Loop,
+        FragmentOperator::Parallel,
+    ] {
+        let mut f = Fixture::new(Layer::Sa);
+        let fragment = f.fragment(f.owner, operator);
+        let first = f.branch(fragment);
+        let create = f.message(first, MessageKind::Create);
+        let scene = f.scene();
+        assert_eq!(scene.lifecycle.markers[0].event.occurrence, create);
+        assert_eq!(
+            intervals(&scene, f.receiver, f.owner).first().unwrap().2,
+            Life::Unresolved
+        );
+        assert_eq!(
+            intervals(&scene, f.receiver, f.owner).last().unwrap().2,
+            Life::Unresolved
+        );
+        assert!(
+            scene
+                .lifecycle
+                .lifetimes
+                .iter()
+                .find(|l| l.lifeline == f.sender)
+                .unwrap()
+                .intervals
+                .iter()
+                .all(|i| i.life == Life::Alive)
+        );
+    }
+}
+
+#[test]
+fn real_scene_lifecycle_edit_undo_redo_restores_exact_source_and_changed_geometry() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let mut f = Fixture::new(layer);
+        let create = f.message(f.owner, MessageKind::Create);
+        let mut document = f.document();
+        let before = document.snapshot();
+        let geometry = Scene::sequence(document.project(), f.owner, create).lifecycle;
+        let mut edited = document.project().elements[&create].clone();
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange { message_kind, .. },
+            ..
+        }) = edited.shared_mut()
+        {
+            *message_kind = MessageKind::Asynchronous;
+        }
+        document
+            .execute(Command::EditElement(create, edited))
+            .unwrap();
+        let after = document.snapshot();
+        let changed = Scene::sequence(document.project(), f.owner, create).lifecycle;
+        assert_ne!(geometry, changed);
+        assert!(changed.markers.is_empty());
+        assert_ne!(before.bundle, after.bundle);
+        assert!(document.undo());
+        assert_eq!(document.project(), &before.decoded.project);
+        assert_eq!(document.bundle(), &before.bundle);
+        assert_eq!(
+            Scene::sequence(document.project(), f.owner, create).lifecycle,
+            geometry
+        );
+        assert!(!document.can_undo() && document.can_redo());
+        assert!(document.redo());
+        assert_eq!(document.project(), &after.decoded.project);
+        assert_eq!(document.bundle(), &after.bundle);
+        assert_eq!(
+            Scene::sequence(document.project(), f.owner, create).lifecycle,
+            changed
+        );
+        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::{
@@ -38,6 +39,7 @@ impl Tool {
 }
 #[derive(Debug, Clone)]
 pub enum Event {
+    Source(super::source_draft::Event),
     Start(Id, Tool, Option<Id>),
     Cancel,
     Submit,
@@ -58,7 +60,6 @@ pub enum Event {
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Shelf {
-    Tools,
     Selection,
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -79,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,
@@ -90,15 +92,22 @@ pub struct State {
     selected_context: Option<oa_core::topology_context::ContextAddress>,
     shelf: Option<Shelf>,
 }
-#[derive(Default, serde::Serialize, serde::Deserialize)]
+#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 struct Browser {
     search: String,
     page: usize,
 }
-#[derive(serde::Serialize, serde::Deserialize)]
+#[derive(Clone, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 struct Draft {
+    #[serde(default)]
+    source: super::source_draft::State,
+    #[serde(default = "Id::new_v4")]
+    invocation: Id,
+    #[serde(default)]
+    source_origin: Option<(Id, oa_core::Element)>,
+
     #[serde(with = "recovery_insertion")]
     insertion: Insertion,
     fixed: bool,
@@ -117,6 +126,40 @@ 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())
+    }
+    pub(super) fn source_view<'a>(&'a self, p: &'a Project) -> Option<iced::Element<'a, Event>> {
+        self.draft
+            .as_ref()?
+            .source
+            .view(p)
+            .map(|v| v.map(Event::Source))
+    }
+
+    pub fn source_active(&self) -> bool {
+        self.draft.as_ref().is_some_and(|d| d.source.engaged())
+    }
+
+    pub fn source_open(&self) -> bool {
+        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())
+    }
+
     pub(super) fn recovery_snapshot(&self) -> Result<Option<serde_json::Value>, String> {
         self.draft
             .as_ref()
@@ -152,6 +195,58 @@ impl State {
     }
 
     pub fn update(&mut self, p: &Project, event: Event) -> Result<Option<Command>, String> {
+        if let Event::Source(event) = event {
+            if self
+                .draft
+                .as_mut()
+                .ok_or("Start the consumer form first.")?
+                .source
+                .dismiss(&event)?
+            {
+                return Ok(None);
+            }
+            let d = self
+                .draft
+                .as_ref()
+                .ok_or("Start the consumer form first.")?;
+            if d.tool != Tool::Work {
+                return Err("This reference does not support staged source creation.".into());
+            }
+            if d.source_origin.as_ref().is_some_and(|(document, owner)| {
+                *document != p.id || p.elements.get(&d.owner) != Some(owner)
+            }) {
+                return Err("The original consumer changed. Cancel and reopen its form; the current draft is retained.".into());
+            }
+            if d.source_origin.is_none() && d.source.engaged() {
+                return Err("The recovered source draft has no original document binding. Go Back or cancel it.".into());
+            }
+            let mut next = d.clone();
+            if next.source_origin.is_none() && matches!(&event, super::source_draft::Event::Open(_))
+            {
+                next.source_origin = Some((
+                    p.id,
+                    p.elements
+                        .get(&d.owner)
+                        .ok_or("The consumer owner no longer exists.")?
+                        .clone(),
+                ));
+            }
+            if let Some(id) = next.source.update(
+                p,
+                super::source_draft::Scope::Work { owner: d.owner },
+                d.invocation,
+                event,
+            )? {
+                next.target = Some(id);
+                next.command(p)?;
+            }
+            self.draft = Some(next);
+            return Ok(None);
+        }
+        if self.source_open() && !matches!(&event, Event::Cancel) {
+            return Err("Use the new source or go Back before editing the parent form.".into());
+        }
+
         if self.draft.is_some() && matches!(&event, Event::Start(..)) {
             return Err(PENDING_DRAFT.into());
         }
@@ -184,6 +279,9 @@ impl State {
                     }
                 });
                 self.draft = Some(Draft {
+                    source: Default::default(),
+                    invocation: Id::new_v4(),
+                    source_origin: Some((p.id, p.elements[&owner].clone())),
                     insertion: Insertion::default(),
                     fixed: false,
                     browsers: Default::default(),
@@ -253,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(
@@ -263,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)
@@ -508,6 +603,22 @@ fn link(p: &Project, source: Id, target: Id, guard: &str) -> Command {
 }
 impl Draft {
     fn command(&self, p: &Project) -> Result<Command, String> {
+        if self.source.engaged()
+            && self.source_origin.as_ref().is_none_or(|(document, owner)| {
+                *document != p.id || p.elements.get(&self.owner) != Some(owner)
+            })
+        {
+            return Err("The original consumer document or owner changed. Cancel and reopen its form; your draft is retained.".into());
+        }
+        self.source.check_scope(
+            super::source_draft::Scope::Work { owner: self.owner },
+            self.target,
+        )?;
+        let preview = self.source.preview(p, self.target)?;
+        let command = self.consumer_command(preview.as_ref().unwrap_or(p))?;
+        self.source.combine(p, self.target, command)
+    }
+    fn consumer_command(&self, p: &Project) -> Result<Command, String> {
         let owner = p
             .elements
             .get(&self.owner)
@@ -615,6 +726,8 @@ impl Draft {
         });
         let name = if self.name.trim().is_empty() {
             default_name
+        } else if self.source.label(self.target).is_some() {
+            self.name.as_str()
         } else {
             self.name.trim()
         };
@@ -798,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,
@@ -806,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,
@@ -866,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> {
@@ -1021,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();
                         }
@@ -1198,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.,
         }
     }
@@ -1298,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 {
@@ -1433,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,
@@ -1513,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| {
@@ -1587,6 +1790,9 @@ mod tests {
     }
     fn branch(owner: Id, a: Id, b: Id, before: Id, after: Id) -> Draft {
         Draft {
+            source: Default::default(),
+            invocation: Id::new_v4(),
+            source_origin: None,
             insertion: Insertion::default(),
             fixed: false,
             browsers: Default::default(),
@@ -2043,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),
         ] {
@@ -2060,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,
@@ -2074,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

@@ -33,7 +33,7 @@ pub enum Event {
     Search(String),
     Page(usize),
 }
-#[derive(Default, serde::Serialize, serde::Deserialize)]
+#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 pub(super) struct Draft {
     edit: Option<Id>,
@@ -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,26 +217,83 @@ 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 created_selection(&self, command: &Command) -> Option<Id> {
+    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
+            .draft
+            .as_ref()
+            .is_some_and(|d| d.source.label(d.target).is_some())
+            && self.prepare_pending(p).ok().as_ref() != Some(command)
+        {
+            return None;
+        }
         if let Command::CreateRelation(r) | Command::EditRelation(_, r) = command
             && matches!(&r.body, RelationBody::ContextualLink { owner: caller, .. } if *caller == owner)
         {
@@ -539,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(
@@ -558,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 => {
@@ -583,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 {
@@ -722,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 {
@@ -845,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.);
@@ -862,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,368 +258,352 @@ 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);
-        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) {
-        let mut form = column![text(d.tool.title()).size(16)].spacing(8);
-        if let Some(contextual) = &d.contextual {
-            form = form
-                .push(
-                    text_input("Link name (retain current when blank)", &d.name)
-                        .on_input(|v| event(Event::Name(v)))
-                        .padding(8)
-                        .size(12),
-                )
-                .push(super::contextual::view(p, owner, contextual));
+        if let Some(child) = d.source.view(p) {
+            form_panel = column![
+                text(format!(
+                    "Consumer name: {}",
+                    crate::views::short(&d.name, 60)
+                ))
+                .size(12),
+                child.map(|e| event(Event::Source(e)))
+            ]
+            .spacing(6)
+            .height(Fill)
+            .into();
         } else {
-            if let Some(link) = d.insertion.link.and_then(|id| p.relations.get(&id)) {
-                let guard = if let RelationBody::SequenceLink { guard, .. } = &link.body {
-                    guard.as_str()
-                } else {
-                    ""
-                };
-                form = form.push(label(format!(
-                    "Insert on {} → {} · preserve path identity and condition [{}]",
-                    p.named(link.source()),
-                    p.named(link.target()),
-                    guard
-                )));
-            } else if d.fixed && ordered {
-                form = form.push(label(match (d.before, d.after) {
-                    (Some(before), Some(after)) => format!(
-                        "Insert between {} → {} · preserve the ordered path",
-                        p.named(before),
-                        p.named(after)
-                    ),
-                    (Some(before), None) => format!("Continue after {}", p.named(before)),
-                    (None, Some(after)) => format!("Insert before {}", p.named(after)),
-                    _ => "Start the ordered path".into(),
-                }));
-            } else if d.fixed
-                && d.tool == Tool::Exchange
-                && let Some(before) = d.before
-            {
-                form = form.push(label(format!(
-                    "Append after {} → new exchange · Create adds an explicit sequence link",
-                    p.named(before)
-                )));
-            } else if d.fixed && d.tool != Tool::Connect {
-                form = form.push(label(
-                    d.insertion
-                        .before
-                        .map_or("Append an unconnected contribution".into(), |id| {
-                            format!("Unconnected contribution before {}", p.named(id))
-                        }),
-                ));
-            }
-            if !legacy_order(p, owner).is_empty() {
-                form = form.push(label(
+            let mut form = column![text(d.tool.title()).size(16)].spacing(8);
+            if let Some(contextual) = &d.contextual {
+                form = form
+                    .push(
+                        text_input("Link name (retain current when blank)", &d.name)
+                            .on_input(|v| event(Event::Name(v)))
+                            .padding(8)
+                            .size(12),
+                    )
+                    .push(super::contextual::view(p, owner, contextual));
+            } else {
+                if let Some(link) = d.insertion.link.and_then(|id| p.relations.get(&id)) {
+                    let guard = if let RelationBody::SequenceLink { guard, .. } = &link.body {
+                        guard.as_str()
+                    } else {
+                        ""
+                    };
+                    form = form.push(label(format!(
+                        "Insert on {} → {} · preserve path identity and condition [{}]",
+                        p.named(link.source()),
+                        p.named(link.target()),
+                        guard
+                    )));
+                } else if d.fixed && ordered {
+                    form = form.push(label(match (d.before, d.after) {
+                        (Some(before), Some(after)) => format!(
+                            "Insert between {} → {} · preserve the ordered path",
+                            p.named(before),
+                            p.named(after)
+                        ),
+                        (Some(before), None) => format!("Continue after {}", p.named(before)),
+                        (None, Some(after)) => format!("Insert before {}", p.named(after)),
+                        _ => "Start the ordered path".into(),
+                    }));
+                } else if d.fixed
+                    && d.tool == Tool::Exchange
+                    && let Some(before) = d.before
+                {
+                    form = form.push(label(format!(
+                        "Append after {} → new exchange · Create adds an explicit sequence link",
+                        p.named(before)
+                    )));
+                } else if d.fixed && d.tool != Tool::Connect {
+                    form = form.push(label(
+                        d.insertion
+                            .before
+                            .map_or("Append an unconnected contribution".into(), |id| {
+                                format!("Unconnected contribution before {}", p.named(id))
+                            }),
+                    ));
+                }
+                if d.tool == Tool::Work {
+                    if let Some(title) = d.source.label(d.target) {
+                        form = form.push(label(title)).push(label("Create commits the new work and contribution together at the chosen path position."));
+                    }
+                    form = form.push(button("Create new source…").on_press(event(Event::Source(
+                        super::super::source_draft::Event::Open(d.invocation),
+                    ))));
+                }
+                if !legacy_order(p, owner).is_empty() {
+                    form = form.push(label(
                     "This edit preserves the ordered path as explicit links in the same undo step.",
                 ));
-            }
-            if matches!(
-                d.tool,
-                Tool::Work | Tool::Exchange | Tool::Reuse | Tool::Branch
-            ) {
-                let choices = targets(p, owner, d.tool)
-                    .into_iter()
-                    .filter(|c| compatible_source(p, d, c.id))
-                    .collect();
-                if d.tool == Tool::Branch {
-                    form = form.push(label("First path work"));
                 }
-                form = form.push(picker(
-                    choices,
-                    d,
-                    0,
-                    d.target,
+                if matches!(
+                    d.tool,
+                    Tool::Work | Tool::Exchange | Tool::Reuse | Tool::Branch
+                ) {
+                    let choices = targets(p, owner, d.tool)
+                        .into_iter()
+                        .filter(|c| compatible_source(p, d, c.id))
+                        .collect();
                     if d.tool == Tool::Branch {
-                        "Choose first path work…"
+                        form = form.push(label("First path work"));
+                    }
+                    form = form.push(picker(
+                        choices,
+                        d,
+                        0,
+                        d.target,
+                        if d.tool == Tool::Branch {
+                            "Choose first path work…"
+                        } else {
+                            "Choose existing source…"
+                        },
+                        Event::Target,
+                    ));
+                }
+                if d.tool != Tool::Connect {
+                    form = form.push(
+                        text_input("Contribution name (defaults to source)", &d.name)
+                            .on_input(|v| event(Event::Name(v)))
+                            .padding(8)
+                            .size(12),
+                    );
+                }
+                if matches!(d.tool, Tool::Control | Tool::Branch) {
+                    let kinds = if d.tool == Tool::Branch {
+                        vec![ControlKind::Choice, ControlKind::Fork]
                     } else {
-                        "Choose existing source…"
-                    },
-                    Event::Target,
-                ));
-            }
-            if d.tool != Tool::Connect {
-                form = form.push(
-                    text_input("Contribution name (defaults to source)", &d.name)
-                        .on_input(|v| event(Event::Name(v)))
+                        vec![
+                            ControlKind::Choice,
+                            ControlKind::Merge,
+                            ControlKind::Fork,
+                            ControlKind::Join,
+                            ControlKind::Loop,
+                        ]
+                    };
+                    form = form.push(
+                        pick_list(
+                            kinds.into_iter().map(ControlChoice).collect::<Vec<_>>(),
+                            Some(ControlChoice(d.control)),
+                            |v| event(Event::Control(v)),
+                        )
+                        .padding(8)
+                        .text_size(12),
+                    );
+                }
+                if d.tool == Tool::Branch {
+                    form = form.push(label("Second path work")).push(picker(
+                        targets(p, owner, Tool::Work),
+                        d,
+                        1,
+                        d.alternate,
+                        "Second path work…",
+                        Event::Alternate,
+                    ));
+                    if d.control != ControlKind::Fork {
+                        form = form
+                            .push(label("First path guard"))
+                            .push(
+                                text_input("First path guard", &d.guard)
+                                    .on_input(|v| event(Event::Guard(v)))
+                                    .padding(8),
+                            )
+                            .push(label("Second path guard"))
+                            .push(
+                                text_input("Second path guard (e.g. else)", &d.alternate_guard)
+                                    .on_input(|v| event(Event::AlternateGuard(v)))
+                                    .padding(8),
+                            );
+                    }
+                }
+                if d.fixed {
+                    if let (Some(a), Some(b)) = (d.before, d.after) {
+                        form = form.push(label(format!("{} → {}", p.named(a), p.named(b))));
+                    }
+                } else {
+                    form = form
+                        .push(label("Preceding contribution"))
+                        .push(picker(
+                            contributions(p, owner),
+                            d,
+                            2,
+                            d.before,
+                            "After contribution…",
+                            Event::Before,
+                        ))
+                        .push(button("Clear preceding").on_press(event(Event::ClearBefore)))
+                        .push(label("Following contribution"))
+                        .push(picker(
+                            contributions(p, owner),
+                            d,
+                            3,
+                            d.after,
+                            "Before contribution…",
+                            Event::After,
+                        ))
+                        .push(button("Clear following").on_press(event(Event::ClearAfter)));
+                }
+                if d.tool != Tool::Branch
+                    && d.insertion.link.is_none()
+                    && (d.before.is_some() || d.tool == Tool::Connect)
+                {
+                    form = form.push(
+                        text_input(
+                            "Path condition (empty remains a Choice / Loop warning)",
+                            &d.guard,
+                        )
+                        .on_input(|v| event(Event::Guard(v)))
                         .padding(8)
                         .size(12),
-                );
+                    );
+                }
             }
-            if matches!(d.tool, Tool::Control | Tool::Branch) {
-                let kinds = if d.tool == Tool::Branch {
-                    vec![ControlKind::Choice, ControlKind::Fork]
+            let valid = match d.command(p) {
+                Ok(_) => true,
+                Err(problem) => {
+                    form = form.push(label(problem));
+                    false
+                }
+            };
+            let actions = row![
+                button(if d.contextual.is_some() {
+                    "Apply link"
                 } else {
-                    vec![
-                        ControlKind::Choice,
-                        ControlKind::Merge,
-                        ControlKind::Fork,
-                        ControlKind::Join,
-                        ControlKind::Loop,
-                    ]
-                };
-                form = form.push(
-                    pick_list(
-                        kinds.into_iter().map(ControlChoice).collect::<Vec<_>>(),
-                        Some(ControlChoice(d.control)),
-                        |v| event(Event::Control(v)),
-                    )
-                    .padding(8)
-                    .text_size(12),
-                );
-            }
-            if d.tool == Tool::Branch {
-                form = form.push(label("Second path work")).push(picker(
-                    targets(p, owner, Tool::Work),
-                    d,
-                    1,
-                    d.alternate,
-                    "Second path work…",
-                    Event::Alternate,
-                ));
-                if d.control != ControlKind::Fork {
-                    form = form
-                        .push(label("First path guard"))
-                        .push(
-                            text_input("First path guard", &d.guard)
-                                .on_input(|v| event(Event::Guard(v)))
-                                .padding(8),
-                        )
-                        .push(label("Second path guard"))
-                        .push(
-                            text_input("Second path guard (e.g. else)", &d.alternate_guard)
-                                .on_input(|v| event(Event::AlternateGuard(v)))
-                                .padding(8),
-                        );
-                }
-            }
-            if d.fixed {
-                if let (Some(a), Some(b)) = (d.before, d.after) {
-                    form = form.push(label(format!("{} → {}", p.named(a), p.named(b))));
-                }
-            } else {
-                form = form
-                    .push(label("Preceding contribution"))
-                    .push(picker(
-                        contributions(p, owner),
-                        d,
-                        2,
-                        d.before,
-                        "After contribution…",
-                        Event::Before,
-                    ))
-                    .push(button("Clear preceding").on_press(event(Event::ClearBefore)))
-                    .push(label("Following contribution"))
-                    .push(picker(
-                        contributions(p, owner),
-                        d,
-                        3,
-                        d.after,
-                        "Before contribution…",
-                        Event::After,
-                    ))
-                    .push(button("Clear following").on_press(event(Event::ClearAfter)));
-            }
-            if d.tool != Tool::Branch
-                && d.insertion.link.is_none()
-                && (d.before.is_some() || d.tool == Tool::Connect)
-            {
-                form = form.push(
-                    text_input(
-                        "Path condition (empty remains a Choice / Loop warning)",
-                        &d.guard,
-                    )
-                    .on_input(|v| event(Event::Guard(v)))
-                    .padding(8)
-                    .size(12),
-                );
-            }
+                    "Create"
+                })
+                .on_press_maybe(valid.then(|| event(Event::Submit))),
+                button("Cancel").on_press(event(Event::Cancel))
+            ]
+            .spacing(7);
+            form_panel = editor_panel(d.invocation, actions.into(), form.into());
         }
-        let valid = match d.command(p) {
-            Ok(_) => true,
-            Err(problem) => {
-                form = form.push(label(problem));
-                false
-            }
-        };
-        let actions = row![
-            button(if d.contextual.is_some() {
-                "Apply link"
-            } else {
-                "Create"
-            })
-            .on_press_maybe(valid.then(|| event(Event::Submit))),
-            button("Cancel").on_press(event(Event::Cancel))
-        ]
-        .spacing(7);
-        form_panel = editor_panel(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/history_fields.rs

@@ -579,11 +579,11 @@ fn render<'a>(
             for (index, item) in items.iter().enumerate().skip(page * PAGE_SIZE).take(PAGE_SIZE) {
                 let item_path = format!("{path}/{index}");
                 let mut card = column![render(draft, project, item_schema, Some(item), &item_path, &format!("{} {}", title, index + 1), depth + 1)].spacing(8);
-                if path == FACETS {
-                    if let Some(current) = current_observation(draft, project, &item_path) {
-                        card = card.push(button("Use current counterpart observations")
-                            .on_press(Message::FieldShape(item_path.clone(), json!(current))).style(style::nav));
-                    }
+                if path == FACETS
+                    && let Some(current) = current_observation(draft, project, &item_path)
+                {
+                    card = card.push(button("Use current counterpart observations")
+                        .on_press(Message::FieldShape(item_path.clone(), json!(current))).style(style::nav));
                 }
                 card = card.push(row![
                     button("↑").on_press_maybe((index > 0).then(|| Message::FieldArray(path.into(), Some(index), -1))),

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",
                             &[
-                                "First create the activities/functions and their exchanges. Check the source and target work for every exchange.",
-                                "Open Behavior & scenarios. Create Process in OA or Functional chain in SA using Create element and + At root.",
-                                "Select that behavior in the page's selector. Open Tools and choose Work or Exchange, then a highlighted path or contribution position to involve an existing source. Each contribution keeps its own identity while referring to the shared engineering definition.",
-                                "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.",
+                                "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.",
+                                "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.",
                             ],
                         ),
@@ -484,28 +488,40 @@ fn article(topic: Topic) -> Article {
             const {
                 Article {
                     summary: "Use a scenario to tell a concrete behavioral story, including repeated messages, actions, state observations and guarded alternatives.",
-                    keywords: "scenario sequence lifeline sender receiver fragment branch alternative loop guard parallel strict optional occurrence exchange action state interface operation allocation call reply unresolved",
+                    keywords: "scenario sequence lifeline lifetime lifecycle birth death capsule sender receiver fragment branch alternative loop guard parallel strict optional occurrence exchange action state interface operation allocation call reply unresolved",
                     sections: &[
                         walkthrough(
                             "Create a scenario",
                             &[
-                                "Open Behavior & scenarios, choose Scenario under Create element and add it at a legal root/owner. Select the scenario in the behavior selector.",
-                                "Use + Lifeline and choose the participant or work it represents. Choices follow the scenario's viewpoint: operational activities, operational participants, system functions or system boundary participants.",
-                                "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.",
+                                "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.",
+                                "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.",
                             ],
                         ),
+                        explain(
+                            "Read lifeline creation and deletion",
+                            "The Lane header and dotted guide identify a lifeline; the guide alone does not establish its lifetime. The stronger solid line shows where the lifeline is known to exist on this scenario path. Create starts that line at a named capsule; Delete ends it at an X. Select the capsule or X to edit that message occurrence. Select the header or guide to inspect the lifeline.",
+                        ),
+                        explain(
+                            "Distinguish uncertain lifetime from an unanswered call",
+                            "A ? means lifetime depends on an alternative, optional, repeated or parallel path. Operands have independent lifetimes: Delete in one alternative does not delete a lifeline in another. Beyond such a fragment, the guide can continue without a definite solid line. This uncertainty is not by itself a model error. The … beside an activation marks a Call that remains unanswered on that path. A reused scenario's internal Create/Delete events appear when you choose Open definition; they do not create or delete the caller's lifelines.",
+                        ),
                         walkthrough(
                             "Invoke an interface operation",
                             &[
@@ -543,7 +559,9 @@ fn article(topic: Topic) -> Article {
                         walkthrough(
                             "Build a state machine",
                             &[
-                                "In Behavior & scenarios, create or select a State machine, then choose Create diagram. This places its existing regions and vertices in a saved view. + View creates another independent layout.",
+                                "In Behavior & scenarios → New → State machine, enter its name and search for the existing same-layer participant that owns it. Candidate labels show parent context and alias to distinguish repeated names.",
+                                "If the owner does not exist, Create new owner retains the machine name and first-view option. Choose its participant kind and semantic parent explicitly. Use this new source returns without changing the model; Create and open commits owner, machine and optional view together.",
+                                "Optionally select Create the first state view, then Create and open. The new machine starts without regions or states. For an existing machine, Create diagram places its existing regions and vertices in a saved view; + View creates another independent layout.",
                                 "Choose + Region and click the highlighted machine, or a State/Mode for a nested region. Choose Initial, State, Mode or another kind from + State / symbol, then click its highlighted owning region. Rename the new element in Properties.",
                                 "Choose Transition and drag from a source vertex to a compatible target, or click the source and then the target. In Select / move, drag states or containers to arrange them; a container moves its descendant placements without changing ownership.",
                                 "Select a drawn transition and drag its endpoint handle to reconnect it. Its right-click menu also offers Reconnect source and Reconnect target; choose one, then click a compatible vertex.",
@@ -787,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",
@@ -800,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.",
@@ -898,6 +928,10 @@ fn article(topic: Topic) -> Article {
                             "A property draft is not yet the model",
                             "Apply changes validates the candidate. When it is rejected, correct the retained draft or use Revert. The canvas continues to show accepted values. Navigation that needs to apply an invalid draft may remain on the current record so your work is not lost. You can read this guide without applying or discarding that draft.",
                         ),
+                        explain(
+                            "A new behavior is still a draft",
+                            "Inside a source subform, Back or the first Escape returns to the unchanged parent. Use this new source stages the prerequisite only. Canceling the parent discards it; choosing an existing reference excludes the staged source from creation. Recovery retains both forms and their reserved identities. An open dialog still receives Escape first. Behavior → New keeps the exact name, owner and viewpoint choices outside the model until Create and open succeeds. Cancel or Escape discards only this draft; if a dialog is open, the first Escape dismisses that dialog. New refuses other unfinished property, source or behavior drafts without applying them. Recovery restores the creation form in its original layer, including rejected raw text, for correction or cancellation.",
+                        ),
                         explain(
                             "Aliases and references",
                             "Stable source aliases must follow the language's identifier rules and avoid reserved words. Use a simple descriptive identifier such as assess_incident. Spaces belong in the displayed Name, not the alias. Reference pickers offer compatible model records; creating the required target first is often the missing step.",

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]
@@ -1663,3 +1690,388 @@ fn adding_bend_between_close_ports_stays_outside_owner_clearance() {
         }]
     );
 }
+
+#[test]
+fn child_work_preserves_allocated_context_and_atomic_history() {
+    use oa_core::projection::project_view;
+    for (layer, performer_kind, work_kind) in [
+        (Layer::Oa, Kind::Entity, Kind::Activity),
+        (Layer::Sa, Kind::System, Kind::Function),
+    ] {
+        for folded in [false, true] {
+            let mut p = Project::empty();
+            let performer = p
+                .add_element(performer_kind, layer, "Performer", None)
+                .unwrap();
+            let work = p
+                .add_element(work_kind, layer, "Parent work", None)
+                .unwrap();
+            let allocation = p.relate(
+                RelationKind::Allocation,
+                "Engineering assignment",
+                performer,
+                work,
+            );
+            p.relations.get_mut(&allocation).unwrap().description =
+                "Retain assignment metadata".into();
+            let original = p.relations[&allocation].clone();
+            let diagram = p.ensure_diagram(layer);
+            p.diagrams.get_mut(&diagram).unwrap().projection = ProjectionKind::Allocation;
+            let performer_node = p.place(diagram, performer, Position { x: 60., y: 60. });
+            let work_node = p.place(diagram, work, Position { x: 84., y: 124. });
+            p = execute_batch(&p, &[Command::Layout(diagram)]).unwrap();
+            for node in [performer_node, work_node] {
+                p.diagrams
+                    .get_mut(&diagram)
+                    .unwrap()
+                    .nodes
+                    .get_mut(&node)
+                    .unwrap()
+                    .collapsed = folded;
+            }
+            let mut app = App::with_project(p);
+            send(&mut app, Message::Layer(layer));
+            send(&mut app, Message::Page(Page::Diagram));
+            send(
+                &mut app,
+                Message::Diagram(crate::app::Choice {
+                    id: diagram,
+                    label: String::new(),
+                }),
+            );
+            let mut first = None;
+            for step in 0..3 {
+                let parent = if step == 2 { first.unwrap() } else { work };
+                send(&mut app, Message::Select(parent));
+                let before = app.project().clone();
+                let before_source = app.document.bundle().clone();
+                send(&mut app, Message::CreateContextElement(work_kind, true));
+                let created = app.selected;
+                assert!(
+                    !before.elements.contains_key(&created),
+                    "{layer:?} step {step}: {}",
+                    app.status
+                );
+                assert_eq!(app.project().elements.len(), before.elements.len() + 1);
+                assert_eq!(app.project().elements[&created].parent, Some(parent));
+                for (id, element) in &before.elements {
+                    assert_eq!(&app.project().elements[id], element);
+                }
+                assert!(
+                    !oa_core::validation::validate(app.project())
+                        .iter()
+                        .any(|i| i.severity == oa_core::validation::Severity::Error)
+                );
+                assert_eq!(
+                    oa_core::validation::allocation_summary(app.project(), work),
+                    Some(performer)
+                );
+                assert_eq!(
+                    oa_core::validation::effective_performer(app.project(), created),
+                    Some(performer)
+                );
+                assert!(
+                    !app.project()
+                        .relations
+                        .values()
+                        .any(|r| r.kind() == RelationKind::Allocation && r.target() == parent)
+                );
+                if step != 1 {
+                    let mut expected = original.clone();
+                    if let RelationBody::Allocation { target, .. } = &mut expected.body {
+                        *target = created;
+                    }
+                    assert_eq!(app.project().relations[&allocation], expected);
+                } else {
+                    assert_eq!(
+                        app.project().relations[&allocation],
+                        before.relations[&allocation]
+                    );
+                }
+                assert_eq!(
+                    app.project().relations.len(),
+                    before.relations.len() + usize::from(step == 1)
+                );
+                let view = project_view(app.project(), diagram);
+                let parent_node = view.nodes.iter().find(|n| n.element == parent).unwrap();
+                let child_node = view.nodes.iter().find(|n| n.element == created).unwrap();
+                let root_node = view.nodes.iter().find(|n| n.element == work).unwrap();
+                assert_eq!(root_node.visual_parent, Some(performer_node));
+                assert_eq!(child_node.visual_parent, Some(parent_node.id));
+                assert!(!app.project().diagrams[&diagram].nodes[&performer_node].collapsed);
+                assert!(!app.project().diagrams[&diagram].nodes[&parent_node.id].collapsed);
+                assert!(child_node.position.x >= parent_node.position.x);
+                assert!(child_node.position.y >= parent_node.position.y + 64.);
+                assert!(
+                    child_node.position.x + child_node.size.width
+                        <= parent_node.position.x + parent_node.size.width
+                );
+                assert!(
+                    child_node.position.y + child_node.size.height
+                        <= parent_node.position.y + parent_node.size.height
+                );
+                for sibling in view
+                    .nodes
+                    .iter()
+                    .filter(|n| n.visual_parent == Some(parent_node.id) && n.id != child_node.id)
+                {
+                    assert!(sibling.position.y + sibling.size.height <= child_node.position.y);
+                }
+                let after = app.project().clone();
+                let after_source = app.document.bundle().clone();
+                send(&mut app, Message::Undo);
+                assert_eq!(
+                    app.project(),
+                    &before,
+                    "creation, allocation and reveal/reflow undo together"
+                );
+                assert_eq!(app.document.bundle(), &before_source);
+                send(&mut app, Message::Redo);
+                assert_eq!(app.project(), &after);
+                assert_eq!(app.document.bundle(), &after_source);
+                if step == 0 {
+                    first = Some(created);
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn child_work_does_not_invent_unallocated_or_mixed_performers() {
+    for (layer, performer_kind, other_kind, work_kind) in [
+        (Layer::Oa, Kind::Entity, Kind::Entity, Kind::Activity),
+        (Layer::Sa, Kind::System, Kind::SystemActor, Kind::Function),
+    ] {
+        // Root leaf, partly unallocated composite, and mixed-performer composite.
+        for context in 0..3 {
+            let mut p = Project::empty();
+            let performer = p
+                .add_element(performer_kind, layer, "Performer", None)
+                .unwrap();
+            let other = p
+                .add_element(other_kind, layer, "Other performer", None)
+                .unwrap();
+            let work = p
+                .add_element(work_kind, layer, "Parent work", None)
+                .unwrap();
+            let mut placed = vec![performer, other, work];
+            if context != 0 {
+                let first = p
+                    .add_element(work_kind, layer, "First leaf", Some(work))
+                    .unwrap();
+                let second = p
+                    .add_element(work_kind, layer, "Second leaf", Some(work))
+                    .unwrap();
+                p.relate(
+                    RelationKind::Allocation,
+                    "First assignment",
+                    performer,
+                    first,
+                );
+                if context == 2 {
+                    p.relate(RelationKind::Allocation, "Other assignment", other, second);
+                }
+                placed.extend([first, second]);
+            }
+            assert_eq!(oa_core::validation::allocation_summary(&p, work), None);
+            let diagram = p.ensure_diagram(layer);
+            p.diagrams.get_mut(&diagram).unwrap().projection = ProjectionKind::Allocation;
+            for id in placed {
+                p.place(diagram, id, Position { x: 60., y: 60. });
+            }
+            p = execute_batch(&p, &[Command::Layout(diagram)]).unwrap();
+            let mut app = App::with_project(p);
+            send(&mut app, Message::Layer(layer));
+            send(&mut app, Message::Page(Page::Diagram));
+            send(
+                &mut app,
+                Message::Diagram(crate::app::Choice {
+                    id: diagram,
+                    label: String::new(),
+                }),
+            );
+            send(&mut app, Message::Select(work));
+            let before = app.project().clone();
+            let before_source = app.document.bundle().clone();
+            send(&mut app, Message::CreateContextElement(work_kind, true));
+            let child = app.selected;
+            assert!(!before.elements.contains_key(&child), "{}", app.status);
+            assert_eq!(app.project().elements[&child].parent, Some(work));
+            assert_eq!(app.project().relations, before.relations);
+            assert_eq!(
+                oa_core::validation::effective_performer(app.project(), child),
+                None
+            );
+            assert_eq!(
+                oa_core::validation::allocation_summary(app.project(), work),
+                None
+            );
+            let after = app.project().clone();
+            let after_source = app.document.bundle().clone();
+            send(&mut app, Message::Undo);
+            assert_eq!(app.project(), &before);
+            assert_eq!(app.document.bundle(), &before_source);
+            send(&mut app, Message::Redo);
+            assert_eq!(app.project(), &after);
+            assert_eq!(app.document.bundle(), &after_source);
+        }
+    }
+}
+
+#[test]
+fn child_work_transfers_leaf_roles_without_fabricating_responsibilities() {
+    // Direct allocation + matching roles, uniquely realized roles only,
+    // unresolved roles, and roles realized by different performers.
+    for context in 0..4 {
+        let mut p = Project::empty();
+        let performer = p
+            .add_element(Kind::Entity, Layer::Oa, "Performer", None)
+            .unwrap();
+        let other = p
+            .add_element(Kind::Entity, Layer::Oa, "Other performer", None)
+            .unwrap();
+        let work = p
+            .add_element(Kind::Activity, Layer::Oa, "Responsible work", None)
+            .unwrap();
+        let mut responsibilities = Vec::new();
+        if context == 0 {
+            responsibilities.push(p.relate(
+                RelationKind::Allocation,
+                "Direct responsibility",
+                performer,
+                work,
+            ));
+        }
+        for index in 0..2 {
+            let role = p
+                .add_element(Kind::Role, Layer::Oa, &format!("Role {index}"), None)
+                .unwrap();
+            responsibilities.push(p.relate(
+                RelationKind::RoleAssignment,
+                &format!("Assigned role {index}"),
+                role,
+                work,
+            ));
+            if context != 2 {
+                let source = if context == 3 && index == 1 {
+                    other
+                } else {
+                    performer
+                };
+                p.relate(RelationKind::RoleRealization, "Realizes role", source, role);
+            }
+        }
+        for (index, id) in responsibilities.iter().enumerate() {
+            let relation = p.relations.get_mut(id).unwrap();
+            relation.description =
+                format!("Responsibility {index}: preserve engineering rationale");
+            let link = Id::new_v4();
+            p.artifact_links.insert(
+                link,
+                ArtifactLink {
+                    id: link,
+                    alias: format!("responsibility_evidence_{index}"),
+                    name: format!("Responsibility evidence {index}"),
+                    description: "Preserve the reference to this exact relation".into(),
+                    owner: *id,
+                    relation: ArtifactRelation::References,
+                    uri: format!("https://example.invalid/responsibility/{index}"),
+                    revision: Some("review-7".into()),
+                    fragment: Some("assignment".into()),
+                },
+            );
+        }
+        let original_relations = p.relations.clone();
+        let diagram = p.ensure_diagram(Layer::Oa);
+        p.diagrams.get_mut(&diagram).unwrap().projection = ProjectionKind::Allocation;
+        p.place(diagram, performer, Position { x: 60., y: 60. });
+        p.place(diagram, work, Position { x: 84., y: 124. });
+        p = execute_batch(&p, &[Command::Layout(diagram)]).unwrap();
+        let expected_performer = (context < 2).then_some(performer);
+        assert_eq!(
+            oa_core::validation::allocation_summary(&p, work),
+            expected_performer
+        );
+        let mut app = App::with_project(p);
+        send(&mut app, Message::Page(Page::Diagram));
+        send(
+            &mut app,
+            Message::Diagram(crate::app::Choice {
+                id: diagram,
+                label: String::new(),
+            }),
+        );
+        let mut first = None;
+        for step in 0..2 {
+            send(&mut app, Message::Select(work));
+            let before = app.project().clone();
+            let before_source = app.document.bundle().clone();
+            send(
+                &mut app,
+                Message::CreateContextElement(Kind::Activity, true),
+            );
+            let child = app.selected;
+            assert!(
+                !before.elements.contains_key(&child),
+                "context {context}, step {step}: {}",
+                app.status
+            );
+            assert_eq!(app.project().elements[&child].parent, Some(work));
+            if step == 0 {
+                first = Some(child);
+            }
+            for (id, original) in &original_relations {
+                let mut expected = original.clone();
+                if responsibilities.contains(id) {
+                    match &mut expected.body {
+                        RelationBody::Allocation { target, .. }
+                        | RelationBody::RoleAssignment { target, .. } => *target = first.unwrap(),
+                        _ => unreachable!(),
+                    }
+                }
+                assert_eq!(app.project().relations[id], expected);
+            }
+            assert_eq!(app.project().artifact_links, before.artifact_links);
+            assert!(!app.project().artifact_links.is_empty());
+            let added = usize::from(step == 1 && expected_performer.is_some());
+            assert_eq!(
+                app.project().relations.len(),
+                before.relations.len() + added
+            );
+            assert_eq!(
+                oa_core::validation::effective_performer(app.project(), child),
+                expected_performer
+            );
+            assert_eq!(
+                app.project()
+                    .relations
+                    .values()
+                    .filter(|r| r.kind() == RelationKind::RoleAssignment && r.target() == child)
+                    .count(),
+                if step == 0 { 2 } else { 0 }
+            );
+            if context != 0 && step == 0 {
+                assert!(
+                    !app.project()
+                        .relations
+                        .values()
+                        .any(|r| r.kind() == RelationKind::Allocation)
+                );
+            }
+            assert!(
+                !oa_core::validation::validate(app.project())
+                    .iter()
+                    .any(|i| i.severity == oa_core::validation::Severity::Error)
+            );
+            let after = app.project().clone();
+            let after_source = app.document.bundle().clone();
+            send(&mut app, Message::Undo);
+            assert_eq!(app.project(), &before);
+            assert_eq!(app.document.bundle(), &before_source);
+            send(&mut app, Message::Redo);
+            assert_eq!(app.project(), &after);
+            assert_eq!(app.document.bundle(), &after_source);
+        }
+    }
+}

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), "…");
+    }
+}