Persist Graph View layout and exact arrangements

[mjuarros]

Description

Persist the selected Graph View layout in exported graph files and per-connection previous sessions. The second commit extends that foundation with exact node positions and viewport pan/zoom because the algorithm alone cannot reproduce randomized, order-sensitive, or manually adjusted arrangements.

The commits intentionally separate the owner decision:

1. eaede47f provides layout-only persistence.
2. 65d4478c adds exact arrangements, lifecycle/race hardening, and the restoration fixes discovered during browser validation.

Note

This draft depends on #2144. Until that PR merges, GitHub temporarily shows its already-reviewed Schema View commit in this PR. The #890 changes begin at eaede47f; the prerequisite diff will disappear after #2144 merges into main.

How to read

1. packages/graph-explorer/src/core/StateProvider/graphSession/graphViewLayoutAlgorithm.ts — layout-only session ownership and persistence
2. packages/graph-explorer/src/core/StateProvider/graphSession/arrangement.ts — exact position and viewport model
3. packages/graph-explorer/src/core/StateProvider/graphSession/restoration.ts — target/token-scoped restoration transaction
4. packages/graph-explorer/src/components/Graph/Graph.tsx — apply positions and skip or constrain layout work
5. packages/graph-explorer/src/modules/GraphViewer/GraphViewer.tsx — capture and remount integration
6. packages/graph-explorer/src/modules/GraphViewer/exportedGraph.ts — strict graph-file validation and legacy compatibility

Performance impact

Median measurements on an Apple M3 Pro with Node 24.16, using the project’s capture, serialization, validation, export, and import functions:

Nodes	Added session size	Save before → after	Load before → after	Export before → after	Import before → after
100	6.2 KiB	0.02 → 0.13 ms	0.04 → 0.12 ms	0.01 → 0.04 ms	0.08 → 0.17 ms
1,000	62.4 KiB	0.09 → 0.56 ms	0.21 → 0.54 ms	0.04 → 0.18 ms	0.36 → 0.76 ms
10,000	635.3 KiB	0.48 → 4.67 ms	1.61 → 4.68 ms	0.33 → 1.90 ms	3.47 → 8.16 ms
50,000	3.16 MiB	2.41 → 28.12 ms	8.23 → 29.64 ms	1.59 → 10.30 ms	26.36 → 49.82 ms
100,000	6.33 MiB	4.62 → 52.12 ms	16.92 → 60.61 ms	3.03 → 20.52 ms	44.99 → 93.48 ms

Arrangement-only capture/application measured 1.02/0.45 ms at 10,000 nodes, 5.51/2.14 ms at 50,000, and 11.00/4.71 ms at 100,000. Storage grows by approximately 65 bytes per node.

All measured operations remain below 10 ms at 10,000 nodes. At 50,000 nodes and above, serialization and import become noticeable. Measurements exclude IndexedDB transaction latency, network fetches, actual Cytoscape rendering/layout, and browser/device variability.

Validation

• pnpm checks
• pnpm test — 226 files, 2,741 tests
• Manual browser validation:
  • graph JSON export/import restores layout and arrangement
  • refresh and previous-session restore preserve exact shape, pan, and zoom
  • manual node movement survives Graph View navigation
  • graph expansion and membership changes preserve the arrangement
  • legacy graph/session data without arrangement remains usable

Related Issues

• Closes Save layout choice to saved graph file & previous session #890
• Depends on Persist schema view layout selection #2144
• Related to Persist graph layout choice per session #884
• Related to Graph Layout Enhancements #2017
• Related to Kickoff: Graph Layout Enhancements #2018

Check List

• I confirm that my contribution is made under the terms of the Apache 2.0 license.
• I have verified pnpm checks passes with no errors.
• I have verified pnpm test passes with no failures.
• I have covered new added functionality with unit tests if necessary.
• I have updated documentation if necessary.