Last Updated: 2026-04-22 (Focus and runtime-extraction rows refreshed for M4.1 slices 1a–1d and M4.4 thumbnail work; see iced-host migration plan §10 Progress Log 2026-04-22) Status: Canonical orientation doc — updated with subsystem status map and dependency topology Purpose: High-level orientation, subsystem status at a glance, and dependency map. Canonical model details live in subsystem and implementation-strategy specs.

Graphshell should prefer external normative standards whenever they specify the behavior we want, and should define internal specifications only when:

1. no relevant external standard exists,
2. Graphshell must project multiple standards into one product-specific model,
3. Graphshell intentionally constrains or deviates from an external standard,
4. Graphshell is the only meaningful source of truth for the behavior.

Practical use of external standards in this codebase:

• as the normative source for browser/content behavior,
• as terminology discipline,
• as a guardrail for host/embedder behavior and interoperability.

Use 2026-03-12_specification_coverage_register.md as the canonical map of:

• which external standards families matter to current/planned features,
• which internal specs already exist,
• which parts of the codebase are still unspecified or underspecified,
• which feature families are inherently Graphshell-defined.

Graphshell is a spatial browser/workbench with three authority domains:

• Graph Tree: semantic identity, node/edge truth, traversal/history truth, lifecycle truth.
• Workbench Tree: panes, splits, tabs, focus regions, frame/workbench arrangement.
• Viewer Runtime: live rendering attachments reconciled from graph/workbench intent.

These domains are strictly separated. Mutation authority, routing, and registry boundaries are defined in implementation_strategy/system/system_architecture_spec.md.

Implementation status at the subsystem level. For per-feature breakdown see implementation_strategy/2026-03-01_complete_feature_inventory.md.

Status legend: ✅ Done / 🔨 Active (current milestone) / 📋 Planned (spec exists) / 🔭 Speculative

All registries use namespace:name key policy. The canonical registry hub is implementation_strategy/system/register/SYSTEM_REGISTER.md.

Data flow and authority dependencies between subsystems. Arrows indicate "depends on / receives authority from."

                        ┌─────────────────────┐
                        │   Storage (WAL)      │
                        │  ✅ persistence layer │
                        └──────────┬──────────┘
                                   │ durable state
                    ┌──────────────▼──────────────┐
                    │        Graph Subsystem        │
                    │  ✅ node/edge/lifecycle truth  │
                    └───┬───────────────────────┬──┘
                        │ node identity          │ traversal edges
              ┌─────────▼──────────┐   ┌────────▼────────────┐
              │  Workbench Subsys  │   │  History Subsystem   │
              │  ✅ tile tree/panes │   │  ✅ done / 📋 replay  │
              └─────────┬──────────┘   └────────┬────────────┘
                        │ pane host               │ timeline data
                        ▼                         ▼
              ┌─────────────────────────────────────────────┐
              │              Viewer Subsystem                │
              │  ✅ Servo/web  🔨 TileRenderMode  📋 non-web  │
              └─────────────────────────┬───────────────────┘
                                        │ render mode
                                        ▼
                              ┌─────────────────────┐
                              │  Render/Compositor   │
                              │  🔨 three-pass active │
                              └─────────────────────┘

         ┌──────────────────────────────────────────────────────────┐
         │                  Cross-Cutting Authorities                │
         │                                                          │
         │  Focus ──────── arbitrates input routing for all above   │
         │  🔨 active       F6 cycle done; unified model in progress │
         │                                                          │
         │  Command Surfaces ── routes actions into all subsystems  │
         │  🔨 active          ActionRegistry; palette/radial active │
         │                                                          │
         │  Diagnostics ─────── observability outlet for all above  │
         │  🔨 active           channel ring; health summaries TBD   │
         │                                                          │
         │  UX Semantics ── runtime semantic tree; test/probe layer │
         │  📋 planned       UxTree partial; scenario runner planned │
         │                                                          │
         │  Accessibility ── AccessKit bridge; Graph Reader planned │
         │  🔨 active         bridge active (degraded); WCAG AA goal │
         └──────────────────────────────────────────────────────────┘

Key dependency rules (from system_architecture_spec.md):

• Graph semantics ≠ tile-tree layout. Graph Reducer owns model mutations; Workbench Authority owns pane arrangement.
• Workbench layout ≠ graph truth. A pane closing does not imply a node deletion.
• Viewers ≠ graph semantics. ViewerRegistry resolves rendering; it does not own node identity.
• Commands ≠ action meaning. ActionRegistry routes; subsystems define semantics.
• Focus is the arbiter of input routing. No subsystem should capture input without going through Focus authority.
• Diagnostics is observability infrastructure only. It does not own state or make routing decisions.

Spec-landed features not yet implemented in the runtime — most likely to be misread as done.

Open concerns as of 2026-03-08. See ../../archive_docs/checkpoint_2026-03-27/graphshell_docs/technical_architecture/ARCHITECTURAL_CONCERNS.md for the archived concern history and resolved items.

• Core browsing graph is functional (force-directed canvas, node lifecycle, WAL persistence).
• Workbench tile tree is functional (tabs, splits, multi-pane, frame snapshots).
• Traversal-aware edge/history model is the canonical runtime model.
• Four-state lifecycle (Active → Warm → Cold → Tombstone) is canonical.
• History Manager timeline/dissolved-tabs surface is active.
• Temporal preview/replay is spec-complete but runtime-pending.
• Faceted filtering is spec-complete but runtime-pending.
• TileRenderMode is active; non-web viewers (Wry/PDF/Markdown) are planned.
• Graphshell's UI backend now runs on egui-wgpu. Remaining renderer work centers on WebRender/runtime convergence and retiring the Servo GL parent-render callback bridge.
• v0.0.2 release gate: AG0–AG8 all closed with evidence (see 2026-03-03_pre_wgpu_plot.md).

For status-by-feature, use implementation_strategy/2026-03-01_complete_feature_inventory.md.

• If you are changing reducer/model behavior → start in the relevant subsystem spec.
• If you are changing pane/open/focus behavior → start in workbench and focus specs.
• If you are changing user-visible interaction → start in the UX coverage matrix and canonical interaction spec.
• If you are changing observability or test gates → start in diagnostics and UxScenario specs.
• If you are adding a registry key → follow namespace:name policy; see SYSTEM_REGISTER.md.
• If you are adding a GraphIntent variant → it must be handled in apply_intents().
• If you are adding a DiagnosticChannelDescriptor → it must have a severity field.

Do not treat this document as authority for:

• concrete Rust type shapes,
• lifecycle transition tables,
• traversal append rules,
• route naming policy,
• diagnostics channel lists,
• acceptance criteria.

Those belong in canonical subsystem/spec docs and must be changed there first.