Skip to content

graph-view-v1-plan.md

Latest commit

 

History

History
210 lines (136 loc) · 5.04 KB

graph-view-v1-plan.md

File metadata and controls

210 lines (136 loc) · 5.04 KB

Graph View Feature Plan (Completed)

Status: completed historical renderer feature plan

This document used "V1" to name the first graph-view implementation slice. That slice has shipped in the current pre-v1 renderer, including graph/tree modes, reference overlays, pan/zoom, focus controls, and a minimap.

It is not the active v1.0.0 stable-release roadmap. See ../V1_RELEASE_PLAN.md for the product release plan.

Goal

Add a graph-style center view to the visualizer without changing scanner intelligence, graph schema, or namespace behavior.

This first slice should make the map feel more like a structural diagram while keeping risk low after the recent client-side rendering regression.

Non-goals

  • No AST or import analysis
  • No new edge types
  • No orient-doc enrichment
  • No replacement of the existing sidebar/detail/routing UI
  • No heavy graph library
  • No dependency additions
  • No generated output committed

Why this scope is intentionally narrow

The current renderer already owns several responsibilities:

  • overview summary
  • domains/groups
  • important nodes
  • filters
  • search list
  • tree view
  • selected detail
  • routing suggestions
  • client-side error handling

Because of that, the first graph-view change should avoid turning render-map.mjs into a full graph engine in one step.

Recommended V1 shape

Add a second center-pane mode

Keep the existing center pane, but add a small mode switch:

  • Tree
  • Graph

The current tree stays intact and remains the fallback view.

Graph view uses only contains edges

V1 graph mode should render only factual hierarchy relationships:

  • folders to folders
  • folders to files

Do not include references edges in the first graph pass.

Reason:

  • contains edges are already tree-shaped and low-risk
  • they match the screenshot direction better than a noisy mixed graph
  • they reduce chances of unreadable output on larger repos

Focus on subtree rendering, not whole-repo-first

V1 graph mode should render:

  • the selected group subtree, or
  • the selected node subtree, or
  • the root subtree when the repo is small

Avoid optimizing for giant whole-repo layouts in the first pass.

Reason:

  • selected-subtree rendering is easier to read
  • deterministic layout is simpler
  • graph density stays manageable without extra controls

Rendering approach

Use inline SVG

Render the graph using self-contained SVG in the generated HTML.

Reason:

  • matches current dependency-free stack
  • works well in a static HTML file
  • easier to keep deterministic than canvas-based force layouts
  • supports click targets, labels, and edges cleanly

Deterministic hierarchy layout

Layout direction:

  • top-to-bottom

Basic layout rules:

  • root or selected parent at top
  • children placed on the next row
  • subtree width determines child spacing
  • node ordering stays alphabetical or graph-order-stable

Do not start with:

  • force simulation
  • auto-physics
  • animated layout

Interaction model

Reuse existing selection flow

The graph should not invent a second selection system.

All graph clicks should call the existing select(id) path so that:

  • selected node detail updates
  • routing suggestions update
  • list view highlights
  • tree view highlights

This keeps the graph as another view of the same state, not a separate app.

Minimal controls in V1

Required:

  • Tree | Graph switch

Optional only if still small:

  • Reset view

Defer:

  • Show references
  • pan/zoom
  • focus mode toggle
  • minimap

Node presentation

V1 node content

Keep nodes visually compact:

  • primary label: file or folder name
  • optional secondary label: short path only when selected or focused
  • color by kind
  • subtle outline or badge for risk-hinted files

Do not try to show too much metadata inside every node.

Selection behavior

Selected node should be clearly emphasized.

Suggested emphasis:

  • brighter border
  • stronger fill
  • thicker connected edges for its local branch

Implementation sequence

  1. Add a center-pane mode switch in render-map.mjs.
  2. Split center-pane rendering into renderTree() and renderGraph().
  3. Add a small SVG container for graph mode.
  4. Build a deterministic hierarchy layout helper for contains edges only.
  5. Render nodes and edges for the current subtree.
  6. Wire node clicks to select(id).
  7. Re-render graph on selection changes.
  8. Keep the existing tree mode untouched as fallback.
  9. Validate against the fixture repo and codebase-orient-skill.

Validation expectations

Fixture repo:

  • graph renders and is readable
  • selected node updates the detail panel
  • no client-side fatal error banner appears

Real repo (codebase-orient-skill):

  • graph is more readable than the current text tree for script-heavy areas
  • selected group or subtree stays understandable
  • no generated docs/ai/visualize/* nodes appear

Follow-up slice after V1

Only after V1 is stable:

  • add optional references overlay
  • add lightweight pan/zoom
  • add a selected-node focus neighborhood mode

That should be a second pass, not part of the initial graph-view change.