From 5a842fd0ef211b30b4451d3b562bc79861e96e8b Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Thu, 12 Nov 2026 21:52:31 -0500 Subject: [PATCH] docs: retire unified-navigation All three milestones merged on 2026-10-15 (#45, #49, #55). Move the durable facts into the lasting docs, add the closure record to docs/initiative-history.json, and remove the planning folder. Co-Authored-By: Claude Opus 5.5 --- docs/CODE_MAP.md | 9 + docs/initiative-history.json | 15 + .../unified-navigation/implementation-plan.md | 111 ---- .../unified-navigation/initiative-map.json | 557 ------------------ .../intent/unified-navigation/intent-brief.md | 76 --- docs/intent/unified-navigation/shape-brief.md | 79 --- 6 files changed, 24 insertions(+), 823 deletions(-) delete mode 100644 docs/intent/unified-navigation/implementation-plan.md delete mode 100644 docs/intent/unified-navigation/initiative-map.json delete mode 100644 docs/intent/unified-navigation/intent-brief.md delete mode 100644 docs/intent/unified-navigation/shape-brief.md diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index bef0addc..8b723a3c 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -245,6 +245,15 @@ Ref picker rules: | Scan state that outlives the view (data, progress, cancel, superseded-request guard) | `client/src/state/scanStore.ts` | | Compare ⇄ normal without remount (normal view stays mounted, hidden) | `client/src/App.tsx` (`App`) | +Navigation rules: + +- The URL is the source of truth. Treemap zoom and graph focus are one location (`at`), so a drill in either view moves both. The view switch changes only the projection. +- Every move is a real `pushState` entry. Browser Back restores the previous place with no new scan and never drops the analyzed repo. +- Refresh restores the repo, location and view from the URL. Local paths in the URL are fine, because srcly runs on localhost. +- The graph is fetched once for the repo root, so dependents outside the current folder are never missing. Focus selects inside that graph, and a drill does not refetch. +- `popstate` and the compare switch never remount the app. The scan lives in a store that outlives the view. +- Compare keeps its own `?compare=` parameter, outside the location model. The Explorer tree follows the location but keeps its own expand state. + ### Client: Treemap | Feature | Where | diff --git a/docs/initiative-history.json b/docs/initiative-history.json index 76700bac..074dc98f 100644 --- a/docs/initiative-history.json +++ b/docs/initiative-history.json @@ -28,5 +28,20 @@ "follow_ups": [ "Evaluate dependency compare on a real PR (claim C7). Nothing tracks it." ] + }, + { + "title": "Unified navigation", + "slug": "unified-navigation", + "outcome": "completed", + "retired_at": "2026-11-12", + "summary": "Treemap zoom and graph focus are now one URL location with real Back, refresh and compare keep the repo, a History dropdown lists recent places, and one view switch plus visible node actions replace the old controls. Reconciled against origin/main 0bfb05ba.", + "reason": "All three milestones merged on 2026-10-15 (#45, #49, #55).", + "documentation": [ + "docs/CODE_MAP.md" + ], + "revision": "0bfb05ba", + "follow_ups": [ + "Peripheral idea C8 (animated canvas transition between treemap and graph) was never planned and is not tracked." + ] } ] diff --git a/docs/intent/unified-navigation/implementation-plan.md b/docs/intent/unified-navigation/implementation-plan.md deleted file mode 100644 index 945aa0c1..00000000 --- a/docs/intent/unified-navigation/implementation-plan.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Unified navigation — implementation plan" -slug: "unified-navigation" -phase: plan -status: current -last_updated: "2026-10-15" ---- - -# Unified navigation — implementation plan - -## Plan at a glance - -Milestone 1 makes the location real. A pure location module backs treemap zoom and graph focus with `pushState`, and the graph is fetched once for the repo root, so one place can feed both views. Those two changes have to land together. If graph focus drives treemap zoom while the graph is still fetched for the treemap's folder, every drill would refetch a smaller graph and lose outside dependents, as happens today. After milestone 1, Back undoes a misclick, the breadcrumbs agree, and nothing else has changed. - -Milestone 2 makes refresh and compare lossless. It puts the repo and the view in the URL and lifts the scan into a store that outlives `AppContent`, so `popstate` never wipes it. It also adds the History dropdown. Milestone 3 cleans up the controls: a single Treemap | Graph switch, and visible node actions. Instant toggling and an animated morph stay below the line until milestone 3's timings show whether they're needed. - -**Pushback:** -- The shape put the root-scoped graph fetch into later milestones. The plan moves it into milestone 1, because a shared location doesn't work without it. -- The hover cards in both views are `pointer-events-none` (`DependencyCanvas.tsx:349-363`), so their buttons can't be clicked. Node actions therefore go in a right-click menu plus a hover "⋯" button on the node itself. - -## Implementation strategy - -- **First proof:** on srcly itself in the in-app browser: - 1. drill three levels in the graph; - 2. misclick; - 3. press Back to return to the prior focus, with no scan request in the network log; - 4. check that the treemap breadcrumb shows the same path. -- **Primary seam:** `client/src/navigation/location.ts`. - - Pure `parseLocation(url)` / `toSearch(loc)` and a `HistoryRing`. - - A small `navigation` store exposes `location()`, `go(loc)` (pushState) and `replace(loc)`, and listens to `popstate`. - - All views read the location and call `go`. None write the URL themselves. -- **Fast local loop:** `cd client && pnpm test -- navigation`, then `./dev.sh` with the in-app browser on srcly. -- **Local dependencies:** none. -- **Live confirmation:** manual checks on modeler, recorded in each PR description: refresh restore time and Back after a misclick. -- **Rollout and rollback:** each milestone is its own PR. Milestone 1 keeps `depFocus` readable as an alias for one release, so old links still open. - -## Milestone 1: One location for treemap zoom and graph focus, with real Back - -- **Change: location module** (`client/src/navigation/location.ts`, new) - - `Location = { at: string /* repo-relative; "" = root; "file#symbol" */, view: "treemap" | "graph" }`. - - Supported query parameters are `at`, `view` and the legacy `depFocus`. - - Tests: round-trip, the legacy alias, the empty root, and symbol fragments. -- **Change: treemap reads the location** (`client/src/App.tsx:192`, `:213-217`, `:379-384`) - - `currentRoot` becomes a memo: `findTreeNodeByPath(data, abs(at))`. If that path is gone, fall back to the nearest existing ancestor and show a toast. - - Explorer and Treemap `onZoom` (`App.tsx:576`, `:589-595`) call `go({at: rel(node.path)})`. -- **Change: graph reads the location** (`client/src/viz/deps/DependencyView.tsx:20-37`, `:53-75`, `:97-105`, `:127-150`) - - Remove `readFocusParam`/`writeFocusParam` and the local `focusId`. - - Focus is the location's `at`, mapped to a graph id. Graph file ids are repo-relative (`server/app/services/deps/graph.py:107-131`), and symbols are `file#name`. - - Clicking a node calls `go`. -- **Change: graph fetched for the repo root** (`DependencyView.tsx:39-51`; `Treemap.tsx:252`) - - Pass the scanned root (`App.tsx:204` `scannedPath`), not `currentRoot().path`. The server caches the whole-repo graph by mtime (`graph.py:65-79`). -- **Change: one breadcrumb.** The graph's "Focus path" (`DependencyView.tsx:127-150`) is removed. `TreemapHeader`'s breadcrumb (`:43-68`) serves both views. - -### Desired end state - -- Drilling in either view moves both. Back and Forward step through locations, with no rescan and no graph refetch. -- Neighbors outside the treemap folder now appear in the graph. -- First-open graph time on modeler is measured and recorded in the PR. - -## Milestone 2: Refresh and compare never lose the repo; History dropdown - -- **Change: scan store** (`client/src/state/scanStore.ts`, new) - - Lift `visualizationData`, `loading`, `scan`, `scannedPath`, `activeRequest` and `stopWatching` out of `AppContent` (`App.tsx:171-209`, `:259-344`) into a module-level store with an explicit `dispose`. - - `excludedPaths` and the treemap paint gate stay in the component. -- **Change: repo in the URL** - - Add `repo` to `Location`. - - On load with `?repo=`, call `handleFileSelect(repo)`. The server analysis cache makes this fast. Then apply `at` and `view`. - - `FilePicker`'s Recent list (`FilePicker.tsx:30`, `:50-60`) stays as it is. -- **Change: compare without remount** - - `App`'s `popstate` handler (`App.tsx:156-165`) only switches what is shown. `AppContent` and the scan store survive. - - Compare's `navigateCompare` (`compare/api.ts:127-132`) keeps its own parameter. Leave the seam alone, because the compare-ref-picker worker also edits this file. -- **Change: History dropdown** (in the `App.tsx` header next to Recent) - - A `HistoryRing` of the last 30 locations, with a view icon, a path, and the time. Clicking an entry calls `go`. - - The ring is in memory per tab. It is mirrored to sessionStorage inside a try/catch so it survives a refresh. - -### Desired end state - -- Refresh or a pasted URL restores the repo, location and view. Time to restore on modeler is recorded. -- Entering compare and pressing Back returns to the same scan with no "Map a codebase" screen. -- The History dropdown jumps back several steps at once. - -## Milestone 3: One switch and visible node actions - -- **Change: switch** (`client/src/viz/treemap/components/TreemapHeader.tsx:99-113`) - - A segmented Treemap | Graph control writes `view`. - - The graph's Close button (`DependencyView.tsx:159-168`) is removed. - - This also fixes the toolbar toggle leaving a stale `depFocus` behind. -- **Change: graph filters survive toggling.** The `filters` signal (`DependencyView.tsx:51`) moves into the navigation store, so unmounting the view doesn't reset External, Tests and Type-only. -- **Change: node actions** - - A shared `NodeActionsMenu` opens on right-click in both views and from a hover "⋯" button on graph nodes. - - Its actions are Focus, Open code (the quick-fix A path) and Show folder (`go({at: parent})`). - - In the treemap it opens from `TreemapCanvas`'s `contextmenu`. Alt-click keeps excluding paths. - -### Desired end state - -- One control switches views in place, with the location and filters kept. -- Any node in either view reaches Focus, Open code or Show folder without modifier keys. -- The toggle time on modeler is recorded, to inform the spike below. - -## Open decisions and spikes - -- **Instant toggle vs remount.** - - **Decision required:** keep both views mounted (hidden) so toggling is instant, or not. - - **Evidence to gather:** milestone 3's toggle timings and memory use on modeler. - - **Fallback:** keep remounting, and cache the graph layout per focus. - -## Below the cut line - -- An animated morph between the treemap and the graph. -- Putting the open code viewer, color metric and file filters in the URL. -- Folding compare's parameter into the location model. diff --git a/docs/intent/unified-navigation/initiative-map.json b/docs/intent/unified-navigation/initiative-map.json deleted file mode 100644 index 30379861..00000000 --- a/docs/intent/unified-navigation/initiative-map.json +++ /dev/null @@ -1,557 +0,0 @@ -{ - "schema_version": "0.5.0", - "initiative": { - "title": "Unified navigation", - "slug": "unified-navigation", - "scale": "capability", - "current_phase": "plan", - "last_updated": "2026-10-15", - "summary": "Collapse treemap zoom, dependency focus, toggles, and browser back into one recoverable notion of location: treemap and graph as projections on one canvas, pushState history, a visible history list, and quick jump-to-folder, without hurting speed.", - "status": "planned", - "next_action": "Worker: m1 after quick-fix mA merges" - }, - "artifacts": { - "intent_brief": { - "path": "intent-brief.md", - "status": "current", - "updated_at": "2026-10-15" - }, - "brainstorm": { - "path": "brainstorm.md", - "status": "not-requested", - "updated_at": null - }, - "shape_brief": { - "path": "shape-brief.md", - "status": "current", - "updated_at": "2026-10-15" - }, - "implementation_plan": { - "path": "implementation-plan.md", - "status": "current", - "updated_at": "2026-10-15" - } - }, - "related_initiatives": [ - { - "slug": "dependency-view", - "relation": "promotes 'animations, focus in URL' from its cut line" - }, - { - "slug": "dependency-graph-legibility", - "relation": "shared color overlay / projection idea" - }, - { - "slug": "dependency-and-treemap-quick-fixes", - "relation": "code-viewer open-from-graph fixes live there" - }, - { - "slug": "pr-compare", - "relation": "compare pushState/popstate remount is part of the Back problem" - } - ], - "sources": [ - { - "id": "req-1", - "type": "request", - "location": "conversation", - "anchor": "2026-10-15 request", - "authority": "direct current intent" - }, - { - "id": "vo-0015", - "type": "voiceover-transcript", - "location": "/Users/byronwall/Movies/ContextRecorder/2026-10-15_08-58-32/session.md", - "anchor": "0:15-0:30 performance must remain", - "authority": "direct current intent" - }, - { - "id": "vo-0429", - "type": "voiceover-transcript", - "location": "session.md + screenshots/006.png", - "anchor": "4:29-4:59 misclick in graph, back arrow messes everything up, re-analyze; make it way easier to go back", - "authority": "direct current intent" - }, - { - "id": "vo-0503", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "5:03-5:34 two hierarchies (treemap root vs focus identify_properties); close deps and lose place; too many forms of navigation", - "authority": "direct current intent" - }, - { - "id": "vo-0535", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "5:35-5:39 reopening restores focus - at least stateful", - "authority": "direct current intent" - }, - { - "id": "vo-0539", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "5:39-5:51 dependency and treemap as a toggle on the same view (possibly); history of places clicked", - "authority": "direct current intent" - }, - { - "id": "vo-0710", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "7:10-7:38 common color overlay, views are projections", - "authority": "direct current intent" - }, - { - "id": "vo-1016", - "type": "voiceover-transcript", - "location": "session.md + frames/012.jpg", - "anchor": "10:16 'But now I can't go back'", - "authority": "direct current intent" - }, - { - "id": "vo-1122", - "type": "voiceover-transcript", - "location": "session.md + frames/015.jpg", - "anchor": "11:22-11:30 billboard: go show me this thing's folder; no quick navigation", - "authority": "direct current intent" - }, - { - "id": "vo-1457", - "type": "voiceover-transcript", - "location": "session.md + frames/020.jpg", - "anchor": "14:57-15:11 switch flashes; animated canvas flip treemap<->dependency would be amazing", - "authority": "direct current intent" - }, - { - "id": "repo-depview", - "type": "repository", - "location": "client/src/viz/deps/DependencyView.tsx", - "anchor": "readFocusParam L20-26; writeFocusParam replaceState L28-37; breadcrumbs L127-150; Close L159-168; separate CodeModal L200-202", - "authority": "current implementation reality" - }, - { - "id": "repo-app", - "type": "repository", - "location": "client/src/App.tsx", - "anchor": "popstate L156-165; currentRoot L192; scannedPath L204; landing L475-534", - "authority": "current implementation reality" - }, - { - "id": "repo-treemap", - "type": "repository", - "location": "client/src/components/Treemap.tsx", - "anchor": "showDependencyGraph L56-59; DependencyView path L250-255; Show swap L248-279", - "authority": "current implementation reality" - }, - { - "id": "repo-compare-api", - "type": "repository", - "location": "client/src/compare/api.ts", - "anchor": "navigateCompare pushState L127-132", - "authority": "current implementation reality" - }, - { - "id": "prior-dependency-view", - "type": "prior-initiative", - "location": "docs/intent/dependency-view/initiative-map.json", - "anchor": "cut_line: 'animations, focus in URL'", - "authority": "earlier agent-recorded deferral" - }, - { - "id": "qa-round-1", - "type": "question-round", - "location": "conversation", - "anchor": "2026-10-15 round 1", - "authority": "direct current intent" - }, - { - "id": "repo-graph-scope", - "type": "repository", - "location": "client/src/viz/deps/DependencyView.tsx:39-51; server/app/routers/analysis.py:57-69", - "anchor": "graph fetched for currentRoot folder subtree; dependents outside that folder are absent", - "authority": "current implementation reality" - } - ], - "intent": { - "claims": [ - { - "id": "C1", - "type": "problem", - "statement": "Recovering from a misclick is very poor; browser Back wipes the session and forces re-analysis.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0429", - "vo-1016" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyView.tsx:28-37 replaceState only", - "client/src/App.tsx:156-165 popstate remounts AppContent", - "client/src/App.tsx:475-534 landing state" - ] - }, - { - "id": "C2", - "type": "required behavior", - "statement": "Going back must be easy and never lose the analyzed repo.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0429" - ] - }, - { - "id": "C3", - "type": "problem", - "statement": "Two hierarchies (treemap location vs dependency focus) and too many forms of navigation; closing the graph loses your place.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0503" - ], - "code_anchors": [ - "client/src/viz/treemap/components/TreemapHeader.tsx:43-68", - "client/src/viz/deps/DependencyView.tsx:127-150", - "client/src/components/Treemap.tsx:252 one-way link" - ] - }, - { - "id": "C4", - "type": "desired experience", - "statement": "Treemap and dependency graph are a toggle on the same view, projections of one location and color overlay.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0539", - "vo-0710" - ], - "notes": "'possibly' at 5:39; reinforced at 7:10 and 15:07", - "code_anchors": [ - "client/src/components/Treemap.tsx:248-279 Show swap in containerRef" - ] - }, - { - "id": "C5", - "type": "desired experience", - "statement": "A history of places visited that can be opened to jump back.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0539" - ] - }, - { - "id": "C6", - "type": "preference", - "statement": "Navigation state persisting across graph close/reopen is good; keep it.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0535" - ] - }, - { - "id": "C7", - "type": "desired experience", - "statement": "Quick navigation from a node to its containing folder.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1122" - ] - }, - { - "id": "C8", - "type": "future possibility", - "statement": "Animated canvas transition between treemap and dependency graph.", - "commitment": "tentative", - "importance": "peripheral", - "status": "active", - "time_horizon": "later", - "sources": [ - "vo-1457", - "prior-dependency-view" - ], - "code_anchors": [ - "client/src/components/Treemap.tsx:248 containerRef", - "client/src/viz/treemap/components/TreemapCanvas.tsx (canvas)", - "client/src/viz/deps/DependencyCanvas.tsx (SVG)" - ] - }, - { - "id": "C9", - "type": "constraint", - "statement": "Navigation changes must not slow toggling or drilling.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0015" - ] - }, - { - "id": "C10", - "type": "current repository reality", - "statement": "Repo path, treemap root, metric, and filters are not in the URL; refresh lands on the empty state.", - "commitment": "derived", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-app" - ], - "code_anchors": [ - "client/src/App.tsx:192,204", - "client/src/components/FilePicker.tsx:30,50-60 recent paths in localStorage only" - ] - }, - { - "id": "C11", - "type": "current repository reality", - "statement": "Toolbar Dependencies toggle doesn't clear depFocus; refresh reopens the graph.", - "commitment": "derived", - "importance": "peripheral", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-depview", - "repo-treemap" - ], - "code_anchors": [ - "client/src/viz/treemap/components/TreemapHeader.tsx:108", - "client/src/viz/deps/DependencyView.tsx:162-165" - ] - }, - { - "id": "C12", - "type": "current repository reality", - "statement": "No middle-click handler exists; graph 'open' is Ctrl/Cmd-click or double-click.", - "commitment": "derived", - "importance": "peripheral", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-depview" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:294-303" - ] - }, - { - "id": "C13", - "type": "decision", - "statement": "Treemap zoom and dependency focus are one location: drilling either moves both; one breadcrumb; the toggle only changes projection.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "qa-round-1" - ] - }, - { - "id": "C14", - "type": "current repository reality", - "statement": "The dependency graph is fetched for the treemap current folder, so edges from outside that folder are missing; with one location it should be fetched for the repo root.", - "commitment": "derived", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-graph-scope" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyView.tsx:39-51", - "client/src/components/Treemap.tsx:252", - "server/app/routers/analysis.py:57-69" - ] - } - ], - "themes": [ - "recoverability", - "single location model", - "projections on one canvas", - "history" - ], - "conflicts": [], - "human_questions": [] - }, - "brainstorm": { - "status": "not-requested", - "requested_count": 7, - "options": [], - "selected_option": null - }, - "shape": { - "status": "current", - "appetite": "Medium, client-only: a location module wired into treemap, graph, header, and compare entry/exit.", - "problem": "Several navigation mechanisms disagree; Back drops the repo; two breadcrumbs; no history; graph scoped to treemap folder hides outside dependents.", - "recommended_shape": { - "location": "{repo, path (folder|file|file#symbol), view}", - "url": "?repo=&at=&view=", - "history": "pushState per location change + in-memory History dropdown (~30)", - "toggle": "Treemap|Graph switch replaces Close", - "node_actions": [ - "Focus", - "Open code", - "Show folder" - ], - "files": [ - "client/src/App.tsx:156-165,192,204", - "client/src/components/Treemap.tsx:56-59,248-279", - "client/src/viz/treemap/components/TreemapHeader.tsx:43-68,99-113", - "client/src/viz/deps/DependencyView.tsx:20-37,39-51,127-168", - "client/src/compare/api.ts:107-132", - "client/src/components/FilePicker.tsx" - ] - }, - "success_moves": [ - "URL as the single source of truth with real pushState entries; app signals derive from it", - "Fetch the dependency graph once for the repo root (server-cached) and focus within it: fixes missing outside dependents and keeps drills local", - "Keep the scan in a store that survives compare/normal switches so popstate never remounts or rescans", - "Pure location module (parse/serialize/push/history) covered by vitest before wiring", - "Visible node actions (Focus/Open code/Show folder) so navigation never depends on modifier clicks" - ], - "first_proof": { - "question": "Can one URL-backed location with pushState make misclick recovery and refresh lossless without slowing navigation?", - "artifact": "location module + vitest, wired to treemap zoom and graph focus on srcly itself; in-app browser script", - "observation": "Back after misclick returns to prior focus with no scan request; refresh restores repo, at, and view; History dropdown lists visits", - "decision_rule": "pass -> toggle swap, node actions, compare no-remount, root-scoped graph fetch; refresh restore >~2s on modeler -> show cached last location while rescan validates" - }, - "rabbit_holes": [ - "popstate interplay with compare pushState", - "whole-repo graph first-open cost on large repos", - "treemap zoom to a symbol (scope highlight) semantics", - "Explorer selection sync loops between signals and URL" - ], - "open_decisions": [] - }, - "implementation": { - "status": "current", - "repository_snapshot": { - "root": "/Users/byronwall/repos/srcly", - "revision": "5e396c3", - "worktree_status": "clean", - "subsystems": [ - "client/src/App.tsx", - "client/src/components/Treemap.tsx", - "client/src/viz/deps/DependencyView.tsx", - "client/src/viz/treemap/components/TreemapHeader.tsx", - "client/src/compare/api.ts", - "client/src/components/FilePicker.tsx" - ], - "test_commands": [ - "cd client && pnpm test -- navigation" - ], - "deployment_surfaces": [] - }, - "dependencies": [], - "fast_local_loop": { - "command": "cd client && pnpm test -- navigation", - "starts": "nothing for unit tests; ./dev.sh plus in-app browser on srcly for the misclick/Back script", - "network": false, - "failure_injection": "parseLocation with missing paths, legacy depFocus, symbol fragments; nearest-ancestor fallback" - }, - "milestones": [ - { - "id": "m1", - "title": "One location for treemap zoom and graph focus, with real Back", - "outcome": "Drilling either view moves both; Back/Forward step through locations without rescan or graph refetch; graph includes neighbors outside the treemap folder.", - "dependencies_introduced": [], - "proof": "vitest location round-trip, legacy alias, root, symbol fragment; in-app browser: drill 3, misclick, Back restores prior focus with no scan request; modeler first-open graph time recorded", - "valid_intermediate_state": "Repo still chosen via picker; Close button still present", - "rollback": "Revert PR; depFocus alias keeps old links working", - "status": "planned", - "evidence": [], - "files": [ - "client/src/navigation/location.ts (new)", - "client/src/App.tsx:192,213-217,379-384,576,589-595", - "client/src/viz/deps/DependencyView.tsx:20-37,39-51,53-75,97-105,127-150", - "client/src/components/Treemap.tsx:252", - "client/src/viz/treemap/components/TreemapHeader.tsx:43-68" - ] - }, - { - "id": "m2", - "title": "Refresh and compare never lose the repo; History dropdown", - "outcome": "Refresh/pasted URL restores repo, location, view; compare enter/Back keeps the scan; History dropdown jumps back.", - "dependencies_introduced": [], - "proof": "vitest HistoryRing; manual: refresh restore time on modeler, compare Back without landing page", - "valid_intermediate_state": "Location model complete; old Close/toggle still work", - "rollback": "Revert PR; scan state returns to AppContent", - "status": "planned", - "evidence": [], - "files": [ - "client/src/state/scanStore.ts (new)", - "client/src/App.tsx:156-165,171-209,259-344", - "client/src/compare/api.ts:127-132 (seam only)", - "client/src/components/FilePicker.tsx" - ] - }, - { - "id": "m3", - "title": "One switch and visible node actions", - "outcome": "Treemap|Graph switch replaces Close and keeps location and filters; Focus/Open code/Show folder reachable without modifiers.", - "dependencies_introduced": [], - "proof": "manual on modeler with toggle timing recorded; vitest for filters persisting in store", - "valid_intermediate_state": "Modifier shortcuts still work", - "rollback": "Revert PR", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/treemap/components/TreemapHeader.tsx:99-113", - "client/src/viz/deps/DependencyView.tsx:51,159-168", - "client/src/viz/deps/DependencyCanvas.tsx (hover \u22ef button)", - "client/src/viz/treemap/components/TreemapCanvas.tsx (contextmenu)", - "client/src/components/NodeActionsMenu.tsx (new)" - ] - } - ], - "cut_line": [ - "animated treemap<->graph morph", - "code viewer, color metric, filters in URL", - "folding compare into the location model" - ], - "open_decisions": [ - { - "decision": "Keep both views mounted for instant toggle vs remount", - "evidence": "m3 toggle timings and memory on modeler", - "fallback": "remount with cached graph layout per focus" - } - ], - "sequencing": "Start after quick-fix mA merges (single CodeModal, onOpenFile). Coordinate the DependencyView metricsIndex/colorMetric prop with legibility m4; compare/api.ts edits limited to the popstate seam to avoid colliding with compare-ref-picker." - }, - "history": [ - { - "date": "2026-10-15", - "event": "Initiative created from 2026-10-15 voiceover session (4:29-5:51, 10:16, 11:22, 14:57) with code source map." - }, - { - "date": "2026-10-15", - "event": "Round 1: treemap zoom and graph focus are the same location." - }, - { - "date": "2026-10-15", - "event": "Shape brief written: URL-backed single location, pushState history, root-scoped graph fetch, no remount on popstate." - }, - { - "date": "2026-10-15", - "event": "Implementation plan written: m1 location + pushState + root-scoped graph fetch together; m2 scan store, repo in URL, History; m3 switch and node actions." - } - ], - "closure": null -} diff --git a/docs/intent/unified-navigation/intent-brief.md b/docs/intent/unified-navigation/intent-brief.md deleted file mode 100644 index fc413718..00000000 --- a/docs/intent/unified-navigation/intent-brief.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Unified navigation" -slug: "unified-navigation" -phase: intent -status: current -last_updated: "2026-10-15" ---- - -# Unified navigation - -## My read - -srcly has grown several ways to move around, and they don't agree: - -- the treemap's zoom location; -- the dependency graph's focus path; -- the Explorer tree; -- a Dependencies toggle and a Close button; -- the browser's back button. - -In the session you misclicked a node in the dependency graph and pressed Back. You lost the repo entirely ("now everything's all messed up") and had to re-analyze to get back. You can be looking at `root` in the treemap while the graph is focused on `identify_properties.py`. Closing the graph leaves you unsure where you are. Your summary: "too many forms of navigation going on here". - -What you want is **one notion of "where I am"**. The treemap and the dependency graph become two projections of that location, and you flip between them with a toggle on the same canvas. Every move is recoverable: Back steps through *your* path, a history list lets you jump to any earlier spot, and a misclick costs one keystroke. From any node you can jump straight to its folder. Speed must not drop. Getting back into the repo was fast, and that has to stay true. - -## What matters most - -- **Recoverability.** You can undo any navigation without losing the scan or the repo. This was the most painful moment in the session. -- **One location.** Treemap zoom and graph focus are the same place, viewed two ways. -- **A visible history** of where you've been, so you can return without fighting the back arrow. - -## The experience you appear to want - -You zoom the treemap into `model_making` and press Dependencies. The same canvas flips to the graph, focused on `model_making`. Ideally the change is an animated transition ("Oh man, that'd be amazing"). You click `create_identities.py` and the location moves. The treemap breadcrumb would show the same path if you flipped back. You misclick `mcp_runtime` and press Back (or Alt+←) to return to `app.py`. You open a history list and jump three steps back. On a node like `billboard`, a "show its folder" action takes you to the containing folder in one step. - -## Boundaries - -### Must be true - -- Back or undo never drops the analyzed repo or forces a rescan. -- Treemap ↔ graph switching keeps the location and the active filters. -- Location state is shareable and refresh-safe through the URL, including the repo path. -- No measurable slowdown in toggling or in drilling. - -### Must be avoided - -- Two breadcrumbs showing two different "current" places. -- Navigation hidden in modifier clicks with no visible alternative. - -## What seems settled - -- Navigation state is worth keeping. You liked that reopening the graph restored your focus ("at least stateful"). -- The treemap and the graph are projections of the same data and colors. This is shared with [dependency-graph-legibility](../dependency-graph-legibility/intent-brief.md). - -## Possibilities, not decisions - -- One canvas that morphs between treemap and graph. The animation is an aspiration, and it was deferred in `dependency-view`'s cut line. -- A history panel or dropdown, as opposed to only reliable Back and Forward entries. -- Graph and treemap as a toggle rather than a separate overlay ("possibly", 5:39). - -## Current reality that matters - -- **Back does nothing useful.** Normal mode never creates a history entry: `depFocus` is written with `replaceState` (`client/src/viz/deps/DependencyView.tsx:28-37`). Back leaves the page. -- **Compare is the exception.** It uses `pushState` (`client/src/compare/api.ts:127-132`). The `popstate` handler then remounts `AppContent` (`App.tsx:156-165`), which loses the scan and lands on "Map a codebase". -- **What the URL doesn't hold.** The repo path (`scannedPath`), the treemap root (`currentRoot`, `App.tsx:192`), the color metric, and the filters are all missing. A refresh always lands on the empty state. -- **Two disconnected locations.** The treemap breadcrumb renders from `currentRoot` (`TreemapHeader.tsx:43-68`). The graph's "Focus path" comes from `focusId` (`DependencyView.tsx:127-150`). The only link is one-way: the graph is fetched for `currentRoot().path` (`Treemap.tsx:252`), and the focus never updates the treemap. -- **A hard swap.** The toggle switches two `` blocks in one container (`Treemap.tsx:248-279`): a canvas treemap and an SVG graph, each fully unmounted on switch. `containerRef` is the natural host for a transition. -- **A small bug.** The toolbar Dependencies toggle doesn't clear `depFocus`. Only the in-graph Close does (`TreemapHeader.tsx:108` vs `DependencyView.tsx:162-165`), so a refresh reopens the graph unexpectedly. -- **No middle-click.** There is no middle-click handler anywhere. "Open" in the graph is Ctrl/⌘-click or double-click (`DependencyCanvas.tsx:294-303`). - -## Decided in round 1 - -- **The treemap zoom and the graph focus are the same location.** Drilling in either view moves both, there is one breadcrumb, and the toggle only changes the projection. - -## Next step after confirmation - -Shape the work. The likely first proof is a URL-backed location (repo, root and focus) with `pushState` history and a repo-safe Back. It can be checked by a misclick-recovery script in the browser. diff --git a/docs/intent/unified-navigation/shape-brief.md b/docs/intent/unified-navigation/shape-brief.md deleted file mode 100644 index b5ff0a32..00000000 --- a/docs/intent/unified-navigation/shape-brief.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Unified navigation — shape brief" -slug: "unified-navigation" -phase: shape -status: current -last_updated: "2026-10-15" ---- - -# Unified navigation — what we are adding - -**Outcome:** There is one "where I am". The treemap and the dependency graph are two projections of it. Every move can be undone with Back or a history list, and nothing ever drops the analyzed repo. - -**Primary flow:** Zoom the treemap to `model_making` → toggle to graph (same place) → drill to `create_identities.py` → misclick → press Back → you're on `create_identities.py` again → refresh → same repo, same place, same view. - -## Feature scope - -```text -Unified navigation -├── PLANNED ADDITIONS -│ ├── Location = { repo, path (folder | file | file#symbol), view: treemap | graph } -│ │ ├── kept in the URL: ?repo=…&at=…&view=… -│ │ │ (color metric and filters are evaluated below) -│ │ ├── treemap zoom and graph focus both read and write it -│ │ └── one breadcrumb, shared by both views -│ ├── History -│ │ ├── each location change pushes a browser entry; Back/Forward and Alt+←/→ just work -│ │ └── a History dropdown in the header: last ~30 places, each with a -│ │ view icon and path; click to jump -│ ├── Toggle replaces Close -│ │ └── one Treemap | Graph switch; switching keeps the location and filters -│ ├── Node actions (visible, not modifier-only) -│ │ └── graph card and treemap tooltip offer Focus · Open code · Show folder -│ └── Repo-safe Back -│ └── entering or leaving compare and stepping history never remount the app -│ or rescan -├── EVALUATE BEFORE COMMITTING -│ ├── keep both views mounted (hidden) so toggling is instant -│ └── color metric and filters in the URL -└── LATER POSSIBILITIES - ├── animated canvas morph between treemap and graph - └── the open code viewer as part of the location -``` - -## Behavior - -| Situation | Expected result | -| --- | --- | -| Drill into a graph node | The treemap location and the breadcrumb move to it too | -| Graph focus on a symbol, then toggle to treemap | The treemap zooms to the file with that scope highlighted | -| Back after a misclick | The previous location, in the same view, with no reload or rescan | -| Refresh, or open a pasted URL | The repo is re-analyzed from the server cache, and you land at `at` in `view` | -| `at` no longer exists (file deleted) | The nearest existing ancestor, with a toast | -| Back out of compare | The previous normal-mode location, with the scan intact | - -## Decisions and boundaries - -**Appetite:** Medium. The work is client-only: a small location module, wired into the treemap, the graph, the header and the compare entry and exit. - -**Key decisions:** -- **Fetch the graph once for the repo root.** Today it is fetched for the treemap's current folder (`Treemap.tsx:252` → `?path=`), so dependents outside that folder are silently missing. With one location, fetch the whole-repo graph once and let focus select within it. The whole-repo graph is already mtime-cached on the server, and drills stay local with no refetch. That keeps performance as it is and fixes correctness. -- **The URL is the source of truth.** Location lives in the URL and history gets real `pushState` entries. App signals derive from the URL, not the other way round. This replaces today's mix of `replaceState`, in-memory `currentRoot`, and `pushState` used only by compare. -- **No remount on `popstate`.** Compare and normal mode keep the scan in a store that outlives the view switch (`App.tsx:156-165`). - -**Boundary:** -- Local paths in the URL are fine, since srcly runs on localhost. -- The Explorer tree follows the location but keeps its own expand/collapse state. -- Compare keeps its `?compare=` parameter. Folding compare into the location model is not in scope. - -**Collisions:** Starts after quick-fix PR A, which moves graph open into the app's single CodeModal. It touches `App.tsx`, `Treemap.tsx`, `TreemapHeader.tsx`, `DependencyView.tsx` and `compare/api.ts`. Dependency-graph-legibility touches `DependencyView.tsx` only to add a metrics-index prop, so agree on that prop before running both in parallel. - -**First proof:** -- **Try:** a location module (parse, serialize, push, history list) with Vitest, wired to treemap zoom and graph focus only, on srcly's own repo. -- **Observe:** Using the in-app browser: - - drill 3 levels, misclick, and press Back to return to the prior focus, with no network request for a scan; - - refresh, and the same repo, `at` and view are restored; - - the History dropdown lists the visits. -- **Decide:** If all pass, add the toggle swap, node actions, the compare no-remount path, and the root-scoped graph fetch. If restoring the repo on refresh takes more than about 2s on modeler, show the last location's treemap from the client cache while the rescan validates. - -Intent: [intent-brief.md](intent-brief.md)