nebulosity 0.0.0-stage → 1.0.0

package/app/map/history.ts

@@ -0,0 +1,61 @@
+/**
+ * The Map's place in the address bar: `/?path=src/vs&page=2`. Every move to another folder or page goes into the
+ * browser's history, so Back returns to the previous folder (owner review), and a reload or a pasted link opens the
+ * same place. The page is counted from 1 for people and from 0 inside the app; the slashes of a path stay readable.
+ */
+export type MapPlace = { path: string; page: number };
+
+const encodePath = (folderPath: string): string => encodeURIComponent(folderPath).replaceAll("%2F", "/");
+
+/**
+ * The address for a place. Inside the editor's panel (`embedded`) it ends with `embed=vscode`, so a reload, a restarted
+ * server or Next's own reload stays embedded and keeps the bridge (V1.8 plan P8); the browser Map never has the flag.
+ */
+export function mapUrl(folderPath: string, page: number, embedded = false): string {
+    const params = [
+        ...(folderPath === "" ? [] : [`path=${encodePath(folderPath)}`]),
+        ...(page > 0 ? [`page=${page + 1}`] : []),
+        ...(embedded ? ["embed=vscode"] : []),
+    ];
+    return params.length === 0 ? "/" : `/?${params.join("&")}`;
+}
+
+/** The place a query string names; anything it can't read is the first page of the root. */
+export function placeFromSearch(search: string): MapPlace {
+    const params = new URLSearchParams(search);
+    const page = params.get("page") ?? "";
+    return { path: params.get("path") ?? "", page: /^\d+$/.test(page) && Number(page) >= 1 ? Number(page) - 1 : 0 };
+}
+
+/**
+ * What the address bar needs when the Map moves to `place`: nothing when it already says so; a rewrite when it names the
+ * same place another way (`?path=src%2Fvs`, `?page=1`, `?path=`), so Back doesn't stop at a step that goes nowhere; and
+ * a new history entry for a move to another place. `address` is the path and query string, `/?path=src`. `embedded`
+ * (see `mapUrl`) makes an address without `embed=vscode` one to rewrite, so the flag is not lost.
+ */
+export function historyStep(address: string, place: MapPlace, embedded = false): "none" | "replace" | "push" {
+    if (address === mapUrl(place.path, place.page, embedded)) return "none";
+    const query = address.includes("?") ? address.slice(address.indexOf("?")) : "";
+    const named = placeFromSearch(query);
+    return named.path === place.path && named.page === place.page ? "replace" : "push";
+}
+
+/**
+ * A move the editor asked for with `follow` (the active editor changed) changes the Map's place but must not fill Back
+ * with a step per file the person clicked through: a push becomes a rewrite of the current entry. A `show` (a deliberate
+ * jump) keeps `mode` "push". Everything else is as `historyStep` said.
+ */
+export function followStep(step: "none" | "replace" | "push", mode: "push" | "replace"): "none" | "replace" | "push" {
+    return step === "push" && mode === "replace" ? "replace" : step;
+}
+
+/**
+ * How many of the Map's own steps lie behind a history entry: the `mapDepth` the Map writes into `history.state` with
+ * each push (and keeps with each rewrite). VS Code's panel has no browser Back, so the Map's own Back control is enabled
+ * only above 0: going back past the Map's first entry would take the webview off the Map (owner review, 2026-10-25).
+ * An entry the Map didn't write, a fresh load's or another page's, is 0, and so is anything that isn't a whole number.
+ */
+export function historyDepth(state: unknown): number {
+    const depth = typeof state === "object" && state !== null ? (state as { mapDepth?: unknown }).mapDepth : undefined;
+    return typeof depth === "number" && Number.isInteger(depth) && depth > 0 ? depth : 0;
+}

package/app/map/labels.ts

@@ -0,0 +1,34 @@
+import type { DescribeResponse, MapNode } from "@/lib/contracts";
+import { formatCount } from "./format";
+
+/**
+ * Words for what the Map draws. The owner's three-task test (2026-10-13) found a newcomer reading an arrow backwards
+ * ("base depends on editor"), so a line says what it means in a sentence when it's hovered.
+ */
+
+/** What a box is called inside a sentence: its name, or for a portal the boxes behind it. */
+function subject(box: MapNode): string {
+    if (box.kind !== "portal") return box.name;
+    return box.pages ? `boxes on ${box.pages.length} other pages` : `boxes on ${box.name}`;
+}
+
+const capitalized = (text: string): string => text.charAt(0).toUpperCase() + text.slice(1);
+
+/** A line's hover label: "editor uses base · 12 imports" (the arrow runs from the user to the used). */
+export function lineLabel(source: MapNode, target: MapNode, count: number): string {
+    const imports = `${formatCount(count)} import${count === 1 ? "" : "s"}`;
+    const verb = source.kind === "portal" ? "use" : "uses";
+    const who = source.kind === "portal" ? capitalized(subject(source)) : subject(source);
+    return `${who} ${verb} ${subject(target)} · ${imports}`;
+}
+
+/** A box's hover title: its path, and its one-line summary when there is one. */
+export function boxTitle(box: Pick<MapNode, "path" | "name" | "tagline">): string {
+    const where = box.path || box.name;
+    return box.tagline ? `${where}: ${box.tagline}` : where;
+}
+
+/** The detail panel's words for a file with no declarations: a file over the size cap had them left unread (ADR-053). */
+export function noDeclarationsText(file: Pick<DescribeResponse, "importsOnly">): string {
+    return file.importsOnly ? "Not read (over the 1 MB size cap; imports only)." : "None found.";
+}

package/app/map/levelLayout.ts

@@ -0,0 +1,199 @@
+import dagre from "@dagrejs/dagre";
+import type { MapEdge, MapNode } from "@/lib/contracts";
+
+/**
+ * Every box is drawn the same size, so the layout needs no measuring (VISUAL_REFRESH.md §4). 56 tall, not V1.3.1's
+ * first 64, and layers 64 apart, not 72: measured on VS Code's busiest levels, the tighter layout fits them 10–30%
+ * larger (src/vs/platform's names from 8.8 to 11.6 px on a 1907 px screen), while GAP stays 40 so the routed lines
+ * keep their channels.
+ */
+export const BOX_WIDTH = 232;
+export const BOX_HEIGHT = 56;
+export const GAP = 40;
+/** Room between layers: enough for a line's arrowhead to read before it meets the box below. */
+export const RANK_GAP = 64;
+
+export type Position = { x: number; y: number };
+
+/** A layer wider than this wraps into rows: 6 boxes span about 1,600 px, a laptop screen at a readable zoom. */
+export const MAX_PER_ROW = 6;
+/** On a wide canvas a layer wraps at 8 instead (about 2,100 px): fewer rows, so a dense level fits larger. */
+export const WIDE_PER_ROW = 8;
+/** A canvas at least this wide counts as wide. Below it, 8 a row would make levels fit smaller, not larger (measured). */
+export const WIDE_CANVAS = 1700;
+
+/** How many boxes a layer holds per row on a canvas this wide. */
+export function perRowFor(canvasWidth: number): number {
+    return canvasWidth >= WIDE_CANVAS ? WIDE_PER_ROW : MAX_PER_ROW;
+}
+
+/**
+ * Dagre's layers, redrawn as centred tiers (VISUAL_REFRESH.md §4: the level fits the viewport). Dagre decides which
+ * layer each box is in and their order within it (the order that crosses fewest lines); its x positions are dropped.
+ * Left to them, 49 files that all import one barrel make one layer 13,000 px wide, and fitting that to a screen
+ * shrinks every box to a sliver. So each layer is centred on x = 0, and one wider than MAX_PER_ROW wraps into rows,
+ * balanced so the last isn't left with one box (13 → 5, 5, 3; at 8 a row, 7 and 6). The tiers stack from y = 0,
+ * RANK_GAP apart.
+ */
+function placeTiers(centres: readonly { path: string; x: number; y: number }[], perRowCap: number): Map<string, Position> {
+    const layers = new Map<number, { path: string; x: number }[]>();
+    for (const { path, x, y } of centres) layers.set(y, [...(layers.get(y) ?? []), { path, x }]);
+
+    const placed = new Map<string, Position>();
+    let top = 0;
+    for (const y of [...layers.keys()].sort((a, b) => a - b)){
+        const layer = layers.get(y)!.sort((a, b) => a.x - b.x || (a.path < b.path ? -1 : 1));
+        const rowCount = Math.ceil(layer.length / perRowCap);
+        const perRow = Math.ceil(layer.length / rowCount);
+        for (let row = 0; row < rowCount; row++){
+            const boxes = layer.slice(row * perRow, (row + 1) * perRow);
+            const left = -(boxes.length * BOX_WIDTH + (boxes.length - 1) * GAP) / 2;
+            boxes.forEach((box, i) => placed.set(box.path, { x: left + i * (BOX_WIDTH + GAP), y: top + row * (BOX_HEIGHT + GAP) }));
+        }
+        top += rowCount * (BOX_HEIGHT + GAP) - GAP + RANK_GAP;
+    }
+    return placed;
+}
+
+/**
+ * At most this many lines shape a level's layout: the heaviest. Dagre's crossing reduction grows with the lines, and
+ * VS Code's src/vs/platform level has 390 of them: about 0.6 s to lay out, against 30 ms with the heaviest 100. Every
+ * line is still drawn; the lighter ones just don't move the boxes (S3, PIVOT_SPEC.md §2).
+ */
+export const LAYOUT_MAX_LINES = 100;
+
+/** The fit's padding (MapCanvas's FIT): React Flow fits a level at most this much smaller than the canvas, each way. */
+export const FIT_PADDING = 0.15;
+/**
+ * Room for the divider over the loose boxes ("Not linked to anything on this page", owner's design, 2026-10-13): a grid
+ * below the tiers starts this far under them, three gaps instead of two, with the line halfway; a column beside them
+ * starts this far down, the line in the band above it.
+ */
+export const BELOW_GAP = 3 * GAP;
+export const DIVIDER_BAND = 64;
+
+/** The canvas a level is judged against when choosing where its loose boxes go: a 1440 × 900 screen less the bars. */
+const NOMINAL_CANVAS = { width: 1440, height: 780 };
+
+/** The zoom React Flow's fit would pick for a level this big on the nominal canvas: never past 100% (MapCanvas's maxZoom). */
+function fitZoom(width: number, height: number): number {
+    return Math.min(1, NOMINAL_CANVAS.width / (width * (1 + FIT_PADDING)), NOMINAL_CANVAS.height / (height * (1 + FIT_PADDING)));
+}
+
+/** A grid of `count` boxes, `columns` wide, from (left, top), in order: the level's order for its loose boxes. */
+function grid(count: number, columns: number, left: number, top: number): Position[] {
+    return Array.from({ length: count }, (_, i) => ({
+        x: left + (i % columns) * (BOX_WIDTH + GAP),
+        y: top + Math.floor(i / columns) * (BOX_HEIGHT + GAP),
+    }));
+}
+
+/** How wide (or tall) `k` boxes side by side (or stacked) are, with the gaps between them. */
+const span = (k: number, size: number): number => k * (size + GAP) - GAP;
+
+/** The paths joined by a line to another box at this level; a line from a box to itself joins nothing. */
+function linkedPaths(edges: readonly MapEdge[]): Set<string> {
+    return new Set(edges.filter((e) => e.source !== e.target).flatMap((e) => [e.source, e.target]));
+}
+
+/**
+ * Where each box of a level goes (ADR-011, PIVOT_SPEC.md §7): dagre's layers, importers above what they import, from
+ * the level's `maxLines` heaviest lines, drawn as centred tiers that wrap past `perRow` (placeTiers). A box with no
+ * line to any other at this level adds nothing to the layering, so those go in a grid, in the level's order, on the
+ * side that lets the whole level fit larger (VISUAL_REFRESH.md §4: readable, fitting the viewport):
+ * - beside the tiers, as tall as them: right for a tall chain on a wide screen (VS Code's root: 91% against 68%);
+ * - or below them, square-ish and centred: right for a short stack with many loose boxes (2 tiers and 20 loose: 95%
+ *   against 42%). A tie stays beside.
+ * Either way they leave room for the divider that says they're not linked (looseDivider, below).
+ * A level with no lines at all is one square-ish grid. Pure and deterministic: the same level always draws the same
+ * picture. Positions are top-left corners, as React Flow places nodes.
+ */
+export function layoutLevel(
+    nodes: readonly MapNode[],
+    edges: readonly MapEdge[],
+    maxLines: number = LAYOUT_MAX_LINES,
+    perRow: number = MAX_PER_ROW,
+): Map<string, Position> {
+    const positions = new Map<string, Position>();
+    const lines = edges.filter((e) => e.source !== e.target);
+    // a box joined by any line stays in the layers, even when only lighter lines join it
+    const linked = linkedPaths(edges);
+    const connected = nodes.filter((n) => linked.has(n.path));
+    const loose = nodes.filter((n) => !linked.has(n.path));
+    // heaviest first; ties by source, then target, so the same level always keeps the same lines
+    const shaping = [...lines]
+        .sort((a, b) => b.count - a.count || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0))
+        .slice(0, maxLines);
+    const squareColumns = Math.max(1, Math.ceil(Math.sqrt(loose.length)));
+
+    if (connected.length === 0){
+        grid(loose.length, squareColumns, 0, 0).forEach((at, i) => positions.set(loose[i].path, at));
+        return positions;
+    }
+
+    const graph = new dagre.graphlib.Graph();
+    graph.setGraph({ rankdir: "TB", nodesep: GAP, ranksep: RANK_GAP, marginx: 0, marginy: 0 });
+    graph.setDefaultEdgeLabel(() => ({}));
+    for (const node of connected) graph.setNode(node.path, { width: BOX_WIDTH, height: BOX_HEIGHT });
+    // a heavier line pulls its boxes closer; the square root keeps 20,000 imports from flattening everything else
+    for (const edge of shaping) graph.setEdge(edge.source, edge.target, { weight: Math.max(1, Math.round(Math.sqrt(edge.count))) });
+    dagre.layout(graph);
+
+    // the tiers are centred on x = 0 and start at y = 0
+    let bottom = 0;
+    let right = 0;
+    for (const [path, at] of placeTiers(connected.map((node) => ({ path: node.path, ...(graph.node(node.path) as { x: number; y: number }) })), perRow)){
+        positions.set(path, at);
+        bottom = Math.max(bottom, at.y + BOX_HEIGHT);
+        right = Math.max(right, at.x + BOX_WIDTH);
+    }
+    if (loose.length === 0) return positions;
+
+    // beside: as many rows as the tiers are tall, starting two gaps right of them and a band down, under the divider
+    const besideRows = Math.max(1, Math.floor((bottom + GAP) / (BOX_HEIGHT + GAP)));
+    const besideColumns = Math.ceil(loose.length / besideRows);
+    const besideWidth = right + 2 * GAP + span(besideColumns, BOX_WIDTH) + right;   // the tiers span -right … right
+    const besideHeight = Math.max(bottom, DIVIDER_BAND + span(Math.ceil(loose.length / besideColumns), BOX_HEIGHT));
+    // below: square-ish, centred, starting BELOW_GAP under the tiers, the divider halfway
+    const belowColumns = Math.min(squareColumns, loose.length);
+    const belowWidth = Math.max(2 * right, span(belowColumns, BOX_WIDTH));
+    const belowHeight = bottom + BELOW_GAP + span(Math.ceil(loose.length / belowColumns), BOX_HEIGHT);
+
+    const cells = fitZoom(belowWidth, belowHeight) > fitZoom(besideWidth, besideHeight)
+        ? grid(loose.length, belowColumns, -span(belowColumns, BOX_WIDTH) / 2, bottom + BELOW_GAP)
+        : grid(loose.length, besideColumns, right + 2 * GAP, DIVIDER_BAND);
+    cells.forEach((at, i) => positions.set(loose[i].path, at));
+    return positions;
+}
+
+/** Where the divider over a level's loose boxes runs: its left end, its centre line, its length. */
+export type Divider = { x: number; y: number; width: number };
+
+/**
+ * The line with "Not linked to anything on this page" in its middle, between the boxes joined by lines and the loose
+ * ones (owner's design, 2026-10-13: without it the loose grid read as randomly placed cards). Below the tiers it runs
+ * the whole level's width, halfway down BELOW_GAP; over a column beside them it's as wide as the column, centred in
+ * DIVIDER_BAND. No divider when every box is linked or none is: there's nothing to set apart.
+ */
+export function looseDivider(nodes: readonly MapNode[], edges: readonly MapEdge[], positions: ReadonlyMap<string, Position>): Divider | null {
+    const linked = linkedPaths(edges);
+    const boundsOf = (paths: readonly string[]) => {
+        const at = paths.map((p) => positions.get(p)).filter((q): q is Position => q !== undefined);
+        return {
+            left: Math.min(...at.map((q) => q.x)),
+            right: Math.max(...at.map((q) => q.x + BOX_WIDTH)),
+            top: Math.min(...at.map((q) => q.y)),
+            bottom: Math.max(...at.map((q) => q.y + BOX_HEIGHT)),
+        };
+    };
+    const joined = nodes.filter((n) => linked.has(n.path)).map((n) => n.path);
+    const loose = nodes.filter((n) => !linked.has(n.path)).map((n) => n.path);
+    if (joined.length === 0 || loose.length === 0) return null;
+
+    const tiers = boundsOf(joined);
+    const grid = boundsOf(loose);
+    // beside: the grid starts right of the tiers (layoutLevel puts it two gaps past them); below, it's centred under them
+    if (grid.left >= tiers.right) return { x: grid.left, y: grid.top - DIVIDER_BAND / 2, width: grid.right - grid.left };
+    const left = Math.min(tiers.left, grid.left);
+    return { x: left, y: (tiers.bottom + grid.top) / 2, width: Math.max(tiers.right, grid.right) - left };
+}

package/app/map/links.ts

@@ -0,0 +1,14 @@
+import type { GitHubSource } from "./api";
+
+export type LinkTarget = { repo: string; path: string };
+
+/** A file in the user's editor, from the app (PIVOT_SPEC.md §7): needs the repo's absolute root, so never in the demo. */
+export function editorLink(target: LinkTarget, line?: number): string {
+    return `vscode://file/${target.repo}/${target.path}${line ? `:${line}` : ""}`;
+}
+
+/** A file on GitHub at the commit the demo's index was built from, at a declaration's lines (ADR-049). */
+export function githubLink(source: GitHubSource, filePath: string, lines?: { start: number; end: number }): string {
+    const anchor = lines === undefined ? "" : lines.start === lines.end ? `#L${lines.start}` : `#L${lines.start}-L${lines.end}`;
+    return `https://github.com/${source.owner}/${source.name}/blob/${source.commit}/${filePath.split("/").map(encodeURIComponent).join("/")}${anchor}`;
+}

package/app/map/liveConnection.ts

@@ -0,0 +1,37 @@
+/**
+ * Keeps one live stream open while the page is on screen (PIVOT_SPEC.md §8).
+ *
+ * Why this exists: when you leave a page, Chrome may keep it frozen in its back/forward cache so Back is instant, and a
+ * frozen page's EventSource stays connected. Over plain HTTP/1.1 a browser allows only 6 connections to one server, so
+ * after a handful of full page loads in one tab the frozen pages' streams held them all, and the next page's level,
+ * status and repo requests waited forever (measured 2026-10-13: the 7th load stalled with the cache on, never with it
+ * off). So the stream closes on `pagehide` and a new one opens on `pageshow` when the page comes back from the cache.
+ */
+
+/** What a stream must offer: a way to close it. EventSource has it; tests pass a stand-in. */
+export type Closable = { close(): void };
+
+/** Where pagehide and pageshow fire: the window, or a stand-in EventTarget in tests. */
+type PageEvents = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+
+/** Opens a stream now and keeps one open while the page shows; returns a function that closes it and stops listening. */
+export function keepLiveStream(open: () => Closable, page: PageEvents): () => void {
+    let stream: Closable | null = open();
+
+    const onHide = (): void => {
+        stream?.close();
+        stream = null;
+    };
+    // pageshow fires on every load too; only a page restored from the cache (persisted) needs its stream back
+    const onShow = (event: Event): void => {
+        if ((event as PageTransitionEvent).persisted && stream === null) stream = open();
+    };
+
+    page.addEventListener("pagehide", onHide);
+    page.addEventListener("pageshow", onShow);
+    return () => {
+        page.removeEventListener("pagehide", onHide);
+        page.removeEventListener("pageshow", onShow);
+        onHide();
+    };
+}

package/app/map/mode.ts

@@ -0,0 +1,7 @@
+/**
+ * True in the static demo's build (ADR-049). `npm run build-demo` builds with NEBULOSITY_DEMO=1, which next.config.ts
+ * turns into NEXT_PUBLIC_NEBULOSITY_DEMO ("1" in the demo, "0" in the app) for the browser; Next inlines it at build
+ * time. For the components. The transport's own switch is written inline in api.ts, so the bundler can drop the demo's
+ * code from the app.
+ */
+export const DEMO = process.env.NEXT_PUBLIC_NEBULOSITY_DEMO === "1";

package/app/map/narrow.ts

@@ -0,0 +1,168 @@
+/**
+ * The Map at any window size (VISUAL_REFRESH.md, "Narrow windows (2026-10-24)"). At 1100 × 700 and up nothing here
+ * changes how the Map looks. Narrower, each surface gives up secondary text first; below the floor the Map stops
+ * shrinking and the page scrolls instead, with the theme's thin scrollbars. Pure, so each rule is tested on its own.
+ */
+
+import { TOP_INSET } from "./viewport";
+
+/**
+ * The floor: the smallest the Map lays itself out at. Narrower or shorter, the page scrolls sideways or down.
+ * 360 px wide holds the top bar's essentials (logo, repo, search, help, status dot) and a canvas as wide as the floor
+ * beside nothing. 320 px tall leaves a 200 px canvas under the bars (48 + 40 + 32 px), which stacks a paged level's
+ * pill (16 + 44 px from the top) over the zoom controls (104 px, 15 px from the bottom) with about 20 px between them.
+ */
+export const MIN_WIDTH = 360;
+export const MIN_HEIGHT = 320;
+
+/** The details panel's width, when there's room beside it (VISUAL_REFRESH.md §5). */
+export const PANEL_WIDTH = 400;
+/**
+ * The least canvas worth keeping beside the panel: the floor's own width. With less left, the panel covers the whole
+ * canvas (its × closes it), since a sliver of Map beside it can't be read or used.
+ */
+export const MIN_CANVAS_BESIDE_PANEL = MIN_WIDTH;
+
+/**
+ * Whether the panel covers the whole canvas in a Map area `mainWidth` px wide; beside it, it's PANEL_WIDTH wide.
+ * `null`, before the area is measured, is the normal case: beside the canvas.
+ */
+export function panelLayout(mainWidth: number | null): { covers: boolean } {
+    return { covers: mainWidth !== null && mainWidth - PANEL_WIDTH < MIN_CANVAS_BESIDE_PANEL };
+}
+
+/**
+ * Where a selected box's actions go while the panel would cover the canvas (owner review, 2026-10-25). A click then only
+ * selects, so a double click still reaches the box and the Map stays in sight, and the box shows Open and Details beside
+ * it. They go under a box whose middle is in the canvas's top half, clear of the page pill's band, and over one lower
+ * down, clear of the legend and the zoom controls. `boxTop` and `boxHeight` are the box's on screen, in canvas px.
+ */
+export function actionsSide(boxTop: number, boxHeight: number, canvasHeight: number): "top" | "bottom" {
+    return boxTop + boxHeight / 2 < canvasHeight / 2 ? "bottom" : "top";
+}
+
+/** The gap between a box and its actions, and the least room they keep from the canvas's sides. */
+const ACTIONS_GAP = 8;
+
+/**
+ * Where the selected box's actions go on the canvas (their top-left corner, canvas px), given the box and the actions'
+ * size on screen: on actionsSide's side, 8 px off the box, centred on it, but kept 8 px inside the canvas's sides, so a
+ * box hanging off an edge (a level opened from its top at 75%) never takes them past it. Each axis is its own rule.
+ */
+export function actionsPlace(
+    box: { left: number; top: number; width: number; height: number },
+    actions: { width: number; height: number },
+    canvasWidth: number,
+    canvasHeight: number,
+): { left: number; top: number } {
+    const top = actionsSide(box.top, box.height, canvasHeight) === "bottom" ? box.top + box.height + ACTIONS_GAP : box.top - ACTIONS_GAP - actions.height;
+    const centred = box.left + box.width / 2 - actions.width / 2;
+    const left = Math.min(Math.max(centred, ACTIONS_GAP), canvasWidth - ACTIONS_GAP - actions.width);
+    return { left, top };
+}
+
+/**
+ * How much the page pill says, by the canvas width it sits in (`null`: not measured yet, the normal case):
+ * "Page 2 of 5 · 44 of 182 folders and files", "Page 2 of 5", or "2 / 5". The whole note is about 350 px, 370 at
+ * most with four-digit counts; with its 16 px inset on the right and as much again on its left that's about 400 px,
+ * and 440 leaves room for a wider font.
+ */
+export type PillForm = "full" | "page" | "numbers";
+const FULL_PILL_ROOM = 440;
+const PAGE_PILL_ROOM = 240;
+
+export function pillForm(room: number | null): PillForm {
+    if (room === null || room >= FULL_PILL_ROOM) return "full";
+    return room >= PAGE_PILL_ROOM ? "page" : "numbers";
+}
+
+/**
+ * The first breadcrumb step to show so the trail fits in `available` px: the steps before it fold into one "…" step
+ * (`ellipsis` px), so the trail truncates from its start and the current folder stays. `widths` are the steps' natural
+ * widths, `gap` the space between steps. The last step always shows, and truncates itself if it alone is too wide.
+ */
+export function trailStart(widths: readonly number[], available: number, ellipsis: number, gap: number): number {
+    const last = widths.length - 1;
+    if (last <= 0) return 0;
+    let needed = widths.reduce((sum, w) => sum + w, 0) + gap * last;
+    if (needed <= available) return 0;
+    // drop steps from the start, one at a time; the "…" stands in for all of them
+    needed += ellipsis + gap;
+    for (let start = 1; start < last; start++){
+        needed -= widths[start - 1] + gap;
+        if (needed <= available) return start;
+    }
+    return last;
+}
+
+/** The space a popover keeps from the Map's edges. */
+const POPOVER_GUTTER = 16;
+
+/**
+ * A popover (the repo list, the status menu) placed to stay inside the Map: aligned with its anchor's start or end
+ * edge as at normal sizes, moved in only as far as it takes to keep 16 px from the Map's edges, and narrowed only when
+ * the Map is narrower than the popover and both margins. `shift` is how far it moved from that alignment (px, + is
+ * right): a start-aligned popover's `left`, an end-aligned one's `right` negated.
+ */
+export function fitPopover(
+    anchor: { left: number; right: number },
+    container: { left: number; right: number },
+    width: number,
+    align: "start" | "end",
+): { shift: number; width: number } {
+    const fitted = Math.min(width, container.right - container.left - 2 * POPOVER_GUTTER);
+    const natural = align === "start" ? anchor.left : anchor.right - fitted;
+    const left = Math.min(Math.max(natural, container.left + POPOVER_GUTTER), container.right - POPOVER_GUTTER - fitted);
+    return { shift: left - natural, width: fitted };
+}
+
+/*
+ * The Map's error line (a failed jump, a level that wouldn't load), over the canvas beside the panel. Its place at
+ * normal sizes is the one it always had: 24 px down, in the page pill's band, centred, now over the canvas you can
+ * see rather than under an open panel, and keeping clear of the pill. Where that band can't hold it, it's a solid card
+ * in the canvas's top-left corner instead, clear of the pill and the zoom controls. Over a panel that covers the
+ * canvas it's the panel's own last row (DetailPanel). It never takes a click.
+ */
+
+/** The overlays' inset from the canvas's edges (the pill's right-4, the legend's left-4 and bottom-4). */
+const OVERLAY_INSET = 16;
+/** The gap the banner keeps from the pill and the legend. */
+const OVERLAY_GAP = 8;
+/** React Flow's zoom controls: 26 px wide, 15 px in from the canvas's right edge. */
+const ZOOM_COLUMN = 15 + 26;
+/** The banner's distance from the canvas's top: as a line in the pill's band (top-6), and as a card (top-4). */
+export const BANNER_TOP = 24;
+export const CARD_TOP = OVERLAY_INSET;
+
+export type BannerForm = "band" | "card";
+
+/**
+ * Which form the banner takes, by the height it has as a line in the band (`null`: not measured yet, the normal case):
+ * the band while it ends inside the pill's 64 px band, where a paged level's boxes don't open (two lines), else the card.
+ */
+export function bannerForm(bandHeight: number | null): BannerForm {
+    return bandHeight === null || BANNER_TOP + bandHeight <= TOP_INSET ? "band" : "card";
+}
+
+/**
+ * The room the line keeps on its right for the pill, past the band's own 16 px padding: the pill's width and a gap,
+ * and as much on its left, so it stays centred over the canvas while it can (`null`: no pill, or not measured yet).
+ */
+export function bandClear(pillWidth: number | null): number {
+    return pillWidth === null ? 0 : pillWidth + OVERLAY_GAP;
+}
+
+/** How far the card's right edge keeps from the canvas's right edge: past the pill, and always past the zoom controls. */
+export function cardClear(pillWidth: number | null): number {
+    return Math.max(ZOOM_COLUMN + OVERLAY_GAP, pillWidth === null ? 0 : OVERLAY_INSET + pillWidth + OVERLAY_GAP);
+}
+
+/**
+ * The open legend's greatest height on a canvas `canvasHeight` px tall (`0`: not measured yet, then no cap). It sits
+ * 16 px from the bottom and stops short of what's above it: 16 px from the top, a paged level's pill band, or the
+ * banner's bottom (`bannerBottom`, 0 with none) and a gap. Its rows scroll inside.
+ */
+export function legendMaxHeight(canvasHeight: number, pillBand: number, bannerBottom: number): number | undefined {
+    if (canvasHeight <= 0) return undefined;
+    return canvasHeight - OVERLAY_INSET - Math.max(OVERLAY_INSET, pillBand, bannerBottom > 0 ? bannerBottom + OVERLAY_GAP : 0);
+}

package/app/map/paths.ts

@@ -0,0 +1,60 @@
+import type { LevelResponse } from "@/lib/contracts";
+
+// The UI imports from lib/ only types and the few pure, browser-safe modules ARCHITECTURE.md §3 names, and
+// lib/index/paths.ts isn't one of them, so these few lines mirror it.
+
+/** The folder that holds a path ("" for something at the root). */
+export function parentOf(targetPath: string): string {
+    const slash = targetPath.lastIndexOf("/");
+    return slash === -1 ? "" : targetPath.slice(0, slash);
+}
+
+/** What a path is called on screen: its last segment, or the repo's folder name for the root. */
+export function nameOf(targetPath: string, repoRoot: string): string {
+    if (targetPath === "") return repoRoot.slice(repoRoot.lastIndexOf("/") + 1) || repoRoot;
+    return targetPath.slice(targetPath.lastIndexOf("/") + 1);
+}
+
+/** A path's last two segments, "src/vs/platform/files/common" → "files/common": enough to tell areas apart in a chip. */
+export function shortPath(targetPath: string): string {
+    return targetPath.split("/").slice(-2).join("/");
+}
+
+/**
+ * The extensions of each language the index reads, named as GET /api/source and highlight.js name them (E4, ADR-065).
+ * The UI can't import lib/index/languages/rules.ts (ARCHITECTURE.md §3 rule 3), so this mirrors it, one row per
+ * language; syntax.test.ts holds the two equal for every extension the rules claim.
+ */
+const LANGUAGES: readonly (readonly [extension: RegExp, language: string])[] = [
+    [/\.(ts|tsx|mts|cts)$/, "typescript"],
+    [/\.(js|jsx|mjs|cjs)$/, "javascript"],
+    [/\.pyi?$/, "python"],
+    [/\.go$/, "go"],
+    [/\.java$/, "java"],
+    [/\.cs$/, "csharp"],
+    [/\.rs$/, "rust"],
+];
+
+/** The language a path's extension implies, the way GET /api/source names it (the UI can't import lib's copy). */
+export function languageFor(filePath: string): string {
+    return LANGUAGES.find(([extension]) => extension.test(filePath))?.[1] ?? "text";
+}
+
+/** Whether `targetPath` is strictly inside `folder` ("" holds everything but itself). */
+export function isInside(targetPath: string, folder: string): boolean {
+    return folder === "" ? targetPath !== "" : targetPath.startsWith(`${folder}/`);
+}
+
+/**
+ * The box on this level that holds `targetPath`: the child on the way down to it, or, when that child is on another
+ * page, the portal standing for that page. Null when the path isn't inside this level, is the level itself, or is on a
+ * page this one has no portal to. Live pulses and highlights use it.
+ */
+export function boxFor(level: Pick<LevelResponse, "path" | "nodes">, targetPath: string): string | null {
+    if (!isInside(targetPath, level.path)) return null;
+    const below = level.path === "" ? targetPath : targetPath.slice(level.path.length + 1);
+    const slash = below.indexOf("/");
+    const child = slash === -1 ? targetPath : `${level.path === "" ? "" : `${level.path}/`}${below.slice(0, slash)}`;
+    if (level.nodes.some((n) => n.path === child)) return child;
+    return level.nodes.find((n) => n.kind === "portal" && n.members?.includes(child))?.path ?? null;
+}

package/app/map/perf.ts

@@ -0,0 +1,31 @@
+/**
+ * Interaction timings for S3 (PIVOT_SPEC.md §2: click, zoom or level change → rendered ≤ 100 ms). A start mark goes
+ * down when the interaction begins, and the measure is taken after the frame that painted its result. Task 22 reads
+ * them from window.__nebulosityPerf.
+ */
+type PerfWindow = Window & { __nebulosityPerf?: { name: string; ms: number }[] };
+
+export function markStart(name: string): void {
+    performance.clearMarks(`${name}:start`);
+    performance.mark(`${name}:start`);
+}
+
+/**
+ * Drops a start mark nothing will measure: a jump that ended without a new level (the editor's quiet jump to a path the
+ * index doesn't hold, or a failed one). Left down, the next level drawn without a mark of its own (an index update's
+ * redraw) would be timed from it, as one long change.
+ */
+export function clearStart(name: string): void {
+    performance.clearMarks(`${name}:start`);
+}
+
+export function measureAfterPaint(name: string): void {
+    // the first frame callback runs before the paint that shows the change; the second runs after it
+    requestAnimationFrame(() => requestAnimationFrame(() => {
+        if (performance.getEntriesByName(`${name}:start`, "mark").length === 0) return;
+        const measure = performance.measure(name, `${name}:start`);
+        performance.clearMarks(`${name}:start`);
+        const w = window as PerfWindow;
+        (w.__nebulosityPerf ??= []).push({ name, ms: Math.round(measure.duration * 10) / 10 });
+    }));
+}

package/app/map/popover.ts

@@ -0,0 +1,36 @@
+import { useEffect, type CSSProperties } from "react";
+import { fitPopover } from "./narrow";
+
+/** How far below its anchor's top a popover opens (top-9), and the room it keeps from the Map's bottom edge. */
+const POPOVER_TOP = 36;
+const POPOVER_BOTTOM_ROOM = 8;
+
+/**
+ * Where a popover opened from `anchor` goes, read from the page as it opens (narrow.ts's fitPopover): aligned with the
+ * anchor's start or end edge, kept 16 px inside the Map's sides, and no taller than the Map leaves below it, above the
+ * activity bar, which is drawn over it (it then scrolls). At normal sizes that's exactly where it always opened. The
+ * Map's box is the top bar's parent, MapView's column, which spans the Map down to the floor.
+ */
+export function placePopover(anchor: HTMLElement, width: number, align: "start" | "end"): CSSProperties {
+    const column = anchor.closest("header")?.parentElement ?? document.documentElement;
+    const map = column.getBoundingClientRect();
+    const bottom = column.querySelector(":scope > footer")?.getBoundingClientRect().top ?? map.bottom;
+    const box = anchor.getBoundingClientRect();
+    const fitted = fitPopover(box, map, width, align);
+    const maxHeight = bottom - box.top - POPOVER_TOP - POPOVER_BOTTOM_ROOM;
+    return align === "start"
+        ? { left: fitted.shift, width: fitted.width, maxHeight }
+        : { right: -fitted.shift, width: fitted.width, maxHeight };
+}
+
+/**
+ * Places an open popover again whenever the window resizes: VS Code's panel can be dragged narrower with a popover
+ * open, and one placed for the old width would run past the Map's edge, or keep a height cap it no longer needs.
+ */
+export function usePlaceOnResize(open: boolean, place: () => void): void {
+    useEffect(() => {
+        if (!open) return;
+        window.addEventListener("resize", place);
+        return () => window.removeEventListener("resize", place);
+    }, [open, place]);
+}