Persist Graph View layout and exact arrangements

CONTEXT.md

@@ -73,6 +73,10 @@ _Avoid_: Criterion (implies a configurable operator, which the product does not
 The set of vertices and edges a user has loaded through exploration for a given Connection. Persisted to IndexedDB so users can close the browser and restore where they left off.
 _Avoid_: State, workspace
 
+**Graph Arrangement**:
+The reproducible visual state of a Session in the Graph View: the selected layout, exact vertex positions, and viewport pan and zoom. Captured after layouts and user interaction, persisted with the Session, and restored without rerunning a complete layout. See `docs/adr/20260903-persist-exact-graph-arrangements.md`.
+_Avoid_: Layout (only the algorithm), Graph state (too broad)
+
 **Graph View**:
 The interactive canvas where vertices and edges are visualized using Cytoscape.js. Users explore the graph here by expanding neighbors and applying layouts. Nav label: "Graph".
 _Avoid_: Graph Explorer (ambiguous with the product name)
@@ -145,7 +149,7 @@ _Avoid_: Save-status indicator
 - A **Vertex** has one or more **Vertex Types** and zero or more **Properties**
 - An **Edge** connects exactly two **Vertices** (source → target), has one **Edge Type**, and zero or more **Properties**
 - An **Edge Connection** links a source **Vertex Type** to a target **Vertex Type** via an **Edge Type**
-- A **Session** belongs to a **Connection** and contains **Vertices** and **Edges**
+- A **Session** belongs to a **Connection** and contains **Vertices**, **Edges**, and its **Graph Arrangement**
 - **Neighbors** are **Vertices** one hop away from a given **Vertex**
 - **Styles** are scoped per **Vertex Type** (**Vertex Styles**) and **Edge Type** (**Edge Styles**)
 - The **Graph View**, **Data Table View**, and **Schema View** all render from the same **Session** and **Schema**

docs/adr/20260903-persist-exact-graph-arrangements.md

@@ -0,0 +1,37 @@
+# ADR — Persist exact graph arrangements
+
+- **Status:** Accepted
+- **Date:** 2026-09-03
+- **Related:** Issue #890; ADR `indexeddb-not-localstorage-for-persistence`; ADR `read-time-transform-for-persisted-values`.
+
+## Context
+
+A layout algorithm name does not reproduce a Graph View reliably. Some algorithms are randomized, deterministic algorithms can depend on entity order, and manual vertex movement is not represented by the algorithm. Restoring a Session therefore requires the selected layout, exact vertex positions, and viewport pan and zoom.
+
+Graph rendering is asynchronous. Layouts, user interaction, Connection changes, overlapping restoration requests, and delayed Cytoscape events can otherwise overwrite a newer Graph Arrangement or write it to the wrong Session.
+
+## Decision
+
+A Session owns an optional Graph Arrangement. Graph export files carry the same optional arrangement so older files and persisted Sessions remain valid.
+
+- Capture positions and viewport after `layoutstop` and `dragfree`. Debounce pan and zoom capture.
+- Scope capture and restoration to the target Connection. A restoration token prevents stale or overlapping requests from committing.
+- Suppress capture while applying a restoration so programmatic position and viewport changes are not persisted as user changes.
+- Apply a complete arrangement after Cytoscape elements exist and skip one automatic layout. For a partial arrangement, preserve matched positions while laying out unmatched vertices.
+- Treat restoration revisions as monotonic. Once a newer revision is consumed, an older revision cannot replace it.
+- Reconcile Graph Arrangements when Session membership changes: retain positions for surviving vertices, remove deleted positions, and preserve the viewport.
+- Reconstruct a requested endpoint-only vertex from a restored edge when a connector cannot materialize vertex details. RDF resources can exist in the visualization without literal properties or an `rdf:type`.
+- Validate exported arrangements strictly. Invalid persisted local arrangements are dropped during the read-time transform rather than preventing startup.
+
+## Considered Options
+
+- **Persist only the layout algorithm.** Rejected because it cannot reproduce randomized, order-sensitive, or manually adjusted arrangements.
+- **Persist Graph Arrangement as app-global state.** Rejected because Sessions and their visual state belong to a Connection.
+- **Always rerun the layout after restoration.** Rejected because it replaces exact positions and causes a visible transition away from the saved arrangement.
+
+## Consequences
+
+- Graph files and previous Sessions can reproduce the saved visualization exactly.
+- Fresh Graph View instances apply the active Session's arrangement immediately instead of replaying the layout animation.
+- Graph membership changes and incomplete restoration require explicit position reconciliation.
+- New capture or restoration paths must preserve Connection and revision guards.

docs/features/graph-view.md

@@ -12,8 +12,8 @@ The graph visualization canvas that you can interact with. Double-click to expan
 
 - **Layout drop-down & reset:** You can display graph data using standard graph layouts in the Graph View. You can use the circular arrow to reset the physics of a layout.
 - **Screenshot:** Download a picture of the current window in Graph View.
-- **Save Graph:** Save the current rendered graph as a JSON file that can be shared with others having the same connection or reloaded at a later time.
-- **Load Graph:** Load a previously saved graph from a JSON file.
+- **Save Graph:** Save the current graph as a JSON file, including its selected layout, node positions, pan, and zoom. The file can be shared with others using the same connection or loaded later.
+- **Load Graph:** Load a saved graph and restore its arrangement. Graphs saved by older versions remain supported and use the selected or default layout when arrangement data is unavailable.
 - **Zoom In/Out & Clear:** To help users quickly zoom in/out or clear the whole canvas in the Graph View.
 - **Legend (i):** This displays an informational list of icons, colors, and display names available.