refactor(web): retire V1, promote unified-engine 3D to canonical#365
Merged
Conversation
V1's onBackgroundRightClick opened the unified context menu with nodeId=null so the background-only items (Unpin All, etc.) would render. V2 only fired the menu when right-clicking on a node mesh. Add an onContextMenu handler on the canvas-wrapping div. A ref guard filters out the bubble that follows a node-mesh right-click — the mesh handler sets the guard before the same DOM contextmenu event reaches the wrapper, so the background path runs only when the click missed all nodes. After this commit V2 is strictly more capable than V1 for the purposes of cutover.
ADR-702's phase 1 plan: once V2 reaches parity, V1 is removed and the unified-engine plugin becomes the one 3D force-graph. The action-layer unification in PR #363 was the last gating step — V1 and V2 had been routing identical mutations through useExplorationActions, so the V1 plugin was redundant. Atomic because intermediate states (V1 deleted but routes still naming 'force-3d-v2', plugin renamed but registry still importing both) are unshippable. - Delete web/src/explorers/ForceGraph3D/ (V1 react-force-graph-3d wrapper, ~2050 lines) - git mv ForceGraph3DV2/ → ForceGraph3D/; rename main file and V2SettingsPanel → SettingsPanel - Rename internal symbols (ForceGraph3DV2 → ForceGraph3D, ForceGraph3DV2Data/Settings → ForceGraph3DData/Settings, V2SettingsPanel → SettingsPanel) and clean V1/V2 historical comments - Drop 'force-3d-v2' from VisualizationType - explorers/index.ts: stop exporting/importing ForceGraph3DV2Explorer - App.tsx: drop the /explore/3d-v2 route; add a redirect from the old URL to /explore/3d so existing bookmarks resolve - AppLayout.tsx sidebar: collapse two "3D Force Graph" entries into one (the Boxes icon stays, matching the new canonical entry) - ExplorerView.tsx: drop the force-3d-v2 carve-out and the Settings3DPanel branch; the 3D plugin's own settingsPanel is used via the standard plugin contract. Only force-2d still routes through GraphSettingsPanel + SLIDER_RANGES_2D. - Delete explorers/common/3DSettingsPanel.tsx (last consumer removed) and its export from common/index.ts - Update on-canvas chrome label from "ForceGraph3D V2" to "ForceGraph3D" Build, type-check, and the 10-test useExplorationActions suite all clean against the renamed surface.
Both packages were used exclusively by the V1 ForceGraph3D explorer retired in the previous commit. Removing them now shrinks the production bundle and prevents future code from accidentally taking a dependency on the abandoned wrapper API. react-force-graph-2d remains — the 2D explorer hasn't migrated to the unified engine yet (deferred to ADR-702 phase 2).
No stale bookmarks to worry about — the route was added in this branch and is being removed in the same branch before the PR lands.
11 tasks
aaronsb
added a commit
that referenced
this pull request
May 14, 2026
Introspection from the PR #366 boundary surfaced patterns the human corrected or affirmed this session. Two new ways and one drift fix: - web/explorers/explorers.md (new) — concrete R3F/drei guidance for force-graph explorers. The d3 ForceGraph2D interaction model (left-pan, right-context, scroll-zoom) is the reference for any 2D explorer in this project. Top-down ortho with OrbitControls (not MapControls — its screenSpacePanning=false breaks vertical pan for z-locked layouts). Projection-aware label rules. WebGL feature documentation should be empirical-first, not worst-case. - web/evolution/evolution.md (new) — engineering judgement for refactors where two implementations coexist. Engine convergence before polish; scrub V1/V2 framing post-promotion; skip redirects for never-public transitional routes; two-plugin-one-component factory pattern during transition windows. - web/way.md (drift fix) — replace "./operator.sh restart web" with "kg-web-dev runs Vite with HMR" pointing at devmode/way.md. Tripped me up this session; aligned now. Both new ways apply to web/src/explorers/ and web/src/views/ work that's actively in flight (PR #365, PR #366, Phase C).
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ADR-702 phase 1 finish: retire the V1 `react-force-graph-3d`-backed
ForceGraph3D and promote the unified-engine implementation (V2) to be
the canonical `force-3d` plugin. PR #360 landed the unified engine
behind V2. PR #363 unified the action layer so V1 and V2 routed
identical mutations through `useExplorationActions`, removing the
last reason to keep V1 around.
Affirms
path. The two-stack 3D world (V1 wrapper + V2 unified engine) was
always meant to be a temporary phase-1 coexistence; V1 is now gone.
`settingsPanel` via the plugin contract. The hard-coded
`Settings3DPanel` carve-out in `ExplorerView` (which had been
reaching into the V1 settings shape) is removed.
User-visible changes
and "3D Force Graph (V2)").
force-sim engine. ~50× headroom on large graphs (per ADR-702),
shader-driven bezier curves on multi-edges, distance-culled
`` edge labels.
menu with the background-only items (Unpin All, etc.) — V2 only
fired on node right-clicks before.
Mechanism changes
renamed wholesale from `ForceGraph3DV2/`. Types renamed
(`ForceGraph3DV2Data/Settings` → `ForceGraph3DData/Settings`),
symbols renamed (`V2SettingsPanel` → `SettingsPanel`), historical
V1/V2 comments cleaned.
route deleted. Sidebar collapsed.
`Settings3DPanel` carve-out. Only `force-2d` still routes through
`GraphSettingsPanel` + `SLIDER_RANGES_2D` — every other explorer
uses the plugin's own `settingsPanel`.
`web/package.json` (and the lockfile). Both were V1-only.
Parity audit + deferred features
V2 reaches parity for everyday exploration: rendering, color modes,
edge-category filter, drag/pin (+pin-all/unpin-all), context menus,
hover/focus dimming, theme integration, autosave/replay, Reports
export, Legend, StatsPanel.
V1 features explicitly deferred — all tracked in #364:
divergence — V2's settings type is the canonical one; future
additions go there)
One V1 feature is obviated by the new engine: "orient labels to
camera" — `` overlays always face the camera.
Tests + author-verification
surface.
branch is pulled — golden path (search → explore → right-click →
follow / add-adjacent / pin / focus) and the new background
right-click. Not author-verified in CI.
Commits
```
9f55eaa chore(web): drop unused /explore/3d-v2 redirect
47e4f24 chore(web): drop react-force-graph-3d and three-spritetext
2d5638c refactor(web): promote V2 to canonical ForceGraph3D, retire V1
2e09491 feat(web): V2 fires context menu on background right-click
```
Commit 4 reverts a stale-bookmark redirect introduced defensively in
commit 2 — removed on author guidance since this branch is the first
to reference `/explore/3d-v2` outside of the V2 coexistence period
and there are no real bookmarks to preserve.
Test plan
nodes + curved edges + arrows
Pin / Focus / Set Origin / Set Destination / Report
respond