Explore the map

What the map shows, how to move around it, and what selecting a place reveals.

spyglass serve /path/to/workspace

The viewer opens on the whole spyglass. Position expresses dependency layer and folder, not physical scale; how far apart two islands sit means nothing.

What you are looking at

Islands are packages. Islands sit in rows by dependency layer: the foundation, the packages that depend on no other, furthest south, and each layer that builds on the ones below it further north. The latitude scale in the right margin numbers the layers; a package the graph could not place sits with the foundation, and its caption says “no layer”. Along a row, islands run west to east in folder order, so packages in one folder, such as apps/ or packages/, sit side by side. Which packages depend on each other is drawn by the lines a selection shows, not by distance. An island’s size grows with its file count.
Marks are files. Files are placed within their island by folder: each folder takes a patch of its own, beside its sibling folders, so a package’s src and test lie side by side. What files import does not move them. The colours drawn over an island closer in are its districts, the responsibilities its files serve; Place names a file’s folder and, once the island is read, its district. Each kind of file has its own ink: source, test, story, config, and other. At overview every file is a dot; closer in, test files are open boxes and stories half-discs, and the other kinds are small blocks.
The legend at the lower right is always open: where north points, the file kinds, the lines for a selection and a coast, and departures with their totals. Its Map key explains each optional layer, drawn as the map draws it.
Departures are drawn by default. A file, folder, or package used mostly from one other package (at least 60% of the modules that use it, counting its own package as one) departs: a magenta notched ring marks it, and a magenta dash-dot line runs from its folder to that package’s coast. A package used by only one other package is marked once, as a whole. Lines are grouped by folder and target, ranked by how dominant the other package’s use is, drawn only when at least two modules there use the place, and at most three run into one package; the legend says how many places depart and how many lines are drawn. While anything is selected, its own lines replace the departure lines. Place says, for a selected file, symbol, or package, where it is used: “placement: departs toward …”, “fits”, “spread”, or “used by no other package”. A departure is an observation, not a defect.
Folders show closer in. On an entered island faint violet-grey lines part its folders, and their names stand in italics with a trailing slash (“web/”), so “lib/” the folder never reads as “lib” the district. Deeper folders’ lines come in as you zoom closer.
Proximity shows closer in. On an entered island a slate dotted tie runs from a file to its responsibility’s folder when the file sits apart from it; a slate dashed tie joins two files in different folders that change together; and two slate arcs set apart, “( )”, mark a folder whose files serve responsibilities that nothing relates. A few ties show on each island, and all of a selected file’s; Place lists the rest.
Place names how a place is nested and what domain it is in. A file reads its folder and path region, an island its path regions and the strongest seams between them, the imports from one region into another. When the workspace declares domains, a place reads its domains, and a departure inside a domain reads as two: the placement departure, toward the package that uses it most, and the domain departure, how many of its consumers share its domains; or that it shares them with every consumer.
A domain can be drawn across islands. When the workspace declares domains, Find lists them. Choose one to draw it with the domains nested in it. A dashed cobalt band runs inside the edge of the folders it covers, and along the whole coast of a package it covers whole, which also takes a cobalt diamond. A file it names alone gets a square. Its name, “domain billing”, is written once on the map. A departure it explains, one whose every consumer elsewhere shares it, has its ring’s notch closed in cobalt. The domain stays drawn while you select places. Clear it in Place, or press Escape once nothing is selected. Place lists what it covers island by island, its symbols, which the map does not draw, and its facets that match nothing.
Dependency is otherwise drawn on selection. How far apart two islands sit means nothing. Selecting an island draws its imports and importers; sea trade routes are an optional layer in the chart settings: switched on, they connect each package to its leading consumers, and a selected island shows its own trade instead. A selected file can trace its imports.
Districts are responsibilities. Inside an island, files that the internal analysis groups under one responsibility share a region.
Natural features carry meaning. A lake is a shared module that many responsibilities draw on. A marsh is a module the analysis could not place in one responsibility, with dotted drains toward the ones it could join. With District streams switched on in the chart settings, a stream is the imports from one responsibility into another, wider where there are more, and a ringed dot marks where streams meet at a composition junction. These describe roles, not quality.

Zoom reveals detail in steps. From the overview, islands are shapes with labels. Closer, districts fade in. Closer still, individual files appear with their names, and at the closest range a file’s declarations can be shown. Labels are budgeted to the viewport so they never overlap.

Moving around

Drag to pan and scroll to zoom towards the cursor. Every control sits in the header: buttons zoom in and out and return to the Whole spyglass, and a Side panel button opens the one panel that holds everything else. On narrow screens the header collapses into a Menu. Clicking a place selects it: a label, a file, a district, or the island itself. Hovering previews. Escape backs out one level at a time: the panel’s search, chart, or evidence first, then the file, then the district, then the island.

Find a place opens the panel’s Find section, a search that matches island names, and, inside a selected island, its districts, responsibilities, and file paths. It is the keyboard route to any place on the map. A Map layer control switches the islands between belonging and files.

What selecting reveals

The panel’s Place section describes the selection: a file’s kind and its incoming and outgoing import counts, or a region’s member count, with the place under the pointer noted beneath it. Trading partners lists what the file imports from and what it supplies, with a Visit link to each. Trace imports draws a dashed line for every import edge into or out of the selected file; the lines follow real directed imports.

Evidence & alternatives expands the architectural evidence for the island below the place: its districts and how they relate, any file’s composition by declaration and who consumes each one, and, where the analysis found credible alternatives, the scenarios it compared, their measured effects, what each preserves, and the limits of the evidence. Nothing here is a recommendation; the panel shows what the scan measured. Evidence is loaded when you ask for it, and if a scan has replaced the dataset since the map loaded, the panel asks you to reload Spyglass.

Chart settings

The app bar extending left from the compass holds zoom out, overview, zoom in, and development FPS. The bottom bar holds the Belonging/Files map-mode switch and the legend. These work without opening settings.

The top-right compass opens Chart controls, a tabbed sidebar with global Reset visualization above its controls. Map shows measured layers. These each draw something the scan measured, and all start off: sea trade routes between each package and its leading consumers, district streams, recorded change, and topographic lines over the summits. Turning a layer on or off moves no island. Rendering contains atmosphere controls for rim waves and cloud shadows, which start on and carry no data. Reset visualization restores the defaults. Settings are not saved between visits.

On the Vite development server, Layers contains connecting land and roads, layout boundaries and spacing. Rendering also includes renderer quality and lighting. Stats shows the live scene composition directly, without an accordion. FPS is always visible in the app bar during development; clicking it opens the settings sidebar. The FPS readout counts submitted map frames, so an idle map reads zero. Production builds omit these tools; ?dev cannot enable them.

Drag the sheet’s handle down to dismiss it, or activate the handle, press Close, click the backdrop, or press Escape. The sidebar closes with its close button or Escape and leaves the map and app bar usable while open. Both return focus to the control that opened them.

Under a reduced-motion preference, focus jumps instead of travelling, and regions appear without fading in.

History

After a scan with --history, packages that existed at an earlier checkpoint but are gone now appear as wrecks, listed in the panel’s Wrecks section. See history.

When the map will not open

The viewer needs WebGL. Without it, the map reports that it could not open and Find a place still works. A missing dataset shows Could not load <file>. Run spyglass scan to generate the dataset.