feat(viewer): add map scopes, grouping depth and dependency focus

[nakul-malhotra]

Summary

Make the Architecture Map navigable by named folder scopes, configurable grouping depth, and dependency focus.

Select a module and choose Focus to show it and its transitive dependencies. Switch to Used by to trace callers instead. Focus searches the indexed repository beyond the selected folder, so a component's page-level consumers remain visible. Clear focus restores the previous folder and grouping settings.

Previously, folder-local relationships could make a component appear to have no callers when its consumers lived elsewhere. The fixed grouping ceiling also limited inspection of deeply nested folders. Named scopes and configurable depth control the starting view; focus follows relationships across that boundary.

How it fits together

1. The existing codegraph.json loader supplies validated map presets and grouping limits.
2. Ordinary map requests retain their folder scope.
3. Focus captures the resolved folder and depth, then asks for repository context at that scope's equivalent absolute grouping depth, including outside callers without rerunning automatic grouping.
4. A pure UI helper computes directional reachability over eligible module links before visual thinning and layout.
5. The URL keeps that snapshot, the focused module and direction alongside the original view settings. Sharing and reload retain the focused grouping; Clear restores the original settings, including automatic mode.

This establishes reachability between indexed modules, not exact runtime execution paths. Existing confidence rules and the test-module filter still apply. Grouping stays fixed during focus; removing or renaming the selected module in the index still produces a recoverable error.

Project configuration

{
  "viewer": {
    "map": {
      "maxDepth": 12,
      "scopes": [
        { "label": "Backend", "root": "server" },
        { "label": "Shared services", "root": "server/shared" },
        { "label": "Frontend", "root": "src" }
      ]
    }
  }
}

Manual grouping defaults to four levels and accepts configured limits from 1 to 32. Automatic grouping retains its four-level ceiling and respects a lower configured limit. Refreshing applies configuration changes without rebuilding the index.

Compatibility and limits

The UI retains its independent package boundary and replaceable adapter. Ordinary views work with older adapters; a focus request lacking repository-context support produces an explicit recovery message instead of a misleading folder-only graph. No extraction, index schema, telemetry or dependency changes are included.

New focus URLs include the resolved grouping snapshot. Earlier canonical focus URLs with an explicit folder and depth remain valid; ambiguous automatic-focus links and malformed roots fail with a recovery action.

Focus is at module granularity: aggregation can connect relationships that belong to different symbols within a module. Large transitive closures can remain visually dense. The existing narrow-screen page overflow is outside this change.

Preview and verification

The supplied visual evidence uses a synthetic twelve-file project.

Final control states: keyboard Focus action, dependency focus, included tests with expanded Key, and an automatic-origin focus with its return settings.

Traversal examples before the final return-label refinement

Used by: callers outside the starting feature folder become visible.

Depends on: the selected module, multi-hop dependencies and their cycle.

An isolated module remains visible, with an explanation and a named return destination.

An unavailable focus produces one recovery action.

Ordinary folder view before focus support (left) and after (right): the negative control for graph membership and layout.

Browser checks cover both directions, multi-hop paths and cycles, test-mediated paths, isolated modules, refocusing, clear and folder changes, reload/sharing/history, invalid links, retrieval failures, and older adapters without repository-context support. Captures cover light/dark preferences at 1500×1000 and 390×844; the narrow page retains its pre-existing horizontal overflow.

The test scope includes map configuration, real map API fixtures, graph models, URL and HTTP-adapter boundaries, the mounted UI package, and shared Screens/Program layout consumers. Application and standalone UI-library builds are checked separately. An isolated consumer has also rendered the packaged map with a replacement adapter.

Unmeasured: production-scale closure latency, completeness of extracted relationships against actual runtime behavior, and broad screen-reader/platform coverage. No full-repository test-suite or general mobile-layout claim is made.