nebulosity 1.0.0 → 1.1.0

package/app/map/runs.ts

@@ -0,0 +1,108 @@
+import type { CanvasRect } from "./narrow";
+import type { Point } from "./routes";
+
+/**
+ * Which lines the pointer is on (the owner, 2026-10-29). Lines that share an end merge (routes.ts), so on a shared run
+ * the pointer catches whichever line is drawn on top, and one line's sentence there said nothing of the others. The
+ * lines a run is shared by are found from the routes themselves: every drawn line running the same way through the
+ * point the pointer is nearest. Pure, so each rule is tested alone.
+ */
+
+/**
+ * How far apart two routes may run and still be one run. Merged lines share their lanes and tracks exactly, and lines
+ * that share no end keep at least a lane's gap apart (routes.ts), so this only absorbs rounding.
+ */
+const SAME_RUN = 0.75;
+
+/** The point of segment `a`→`b` nearest `p`. */
+function nearestOnSegment(p: Point, a: Point, b: Point): Point {
+    const dx = b.x - a.x, dy = b.y - a.y;
+    const length2 = dx * dx + dy * dy;
+    if (length2 === 0) return a;
+    const t = Math.min(1, Math.max(0, ((p.x - a.x) * dx + (p.y - a.y) * dy) / length2));
+    return { x: a.x + t * dx, y: a.y + t * dy };
+}
+
+const distance = (p: Point, q: Point): number => Math.hypot(p.x - q.x, p.y - q.y);
+
+/** Whether two segments run the same way (or back the other way): a route's runs are level or upright, so near enough. */
+function sameWay(a: Point, b: Point, c: Point, d: Point): boolean {
+    const u = { x: b.x - a.x, y: b.y - a.y }, v = { x: d.x - c.x, y: d.y - c.y };
+    const lengths = Math.hypot(u.x, u.y) * Math.hypot(v.x, v.y);
+    return lengths > 0 && Math.abs(u.x * v.y - u.y * v.x) / lengths < 0.01;
+}
+
+/**
+ * The point of `route` nearest `at`, and the segment it's on: segment i runs from route[i] to route[i + 1]. The first
+ * nearest wins a tie, so a corner belongs to the segment that reaches it. Null for a route of fewer than two points.
+ */
+export function nearestOnRoute(route: readonly Point[], at: Point): { point: Point; segment: number } | null {
+    let best: { point: Point; segment: number; away: number } | null = null;
+    for (let i = 0; i + 1 < route.length; i++){
+        const point = nearestOnSegment(at, route[i], route[i + 1]);
+        const away = distance(at, point);
+        if (best === null || away < best.away) best = { point, segment: i, away };
+    }
+    return best && { point: best.point, segment: best.segment };
+}
+
+/**
+ * The drawn lines that share the run of line `id` at `at` (the Map's own coordinates): the point of its route nearest
+ * `at`, and every drawn line with a segment running the same way through that point, `id` among them, sorted, so the
+ * same run always reads the same. A line that only crosses there runs the other way, so it isn't on the run. Null when
+ * `id` has no route.
+ */
+export function linesSharing(
+    id: string,
+    at: Point,
+    routes: ReadonlyMap<string, readonly Point[]>,
+    drawn: ReadonlySet<string>,
+): { lines: string[]; point: Point; segment: number } | null {
+    const route = routes.get(id);
+    if (route === undefined) return null;
+    const near = nearestOnRoute(route, at);
+    if (near === null) return null;
+    const a = route[near.segment], b = route[near.segment + 1];
+    const lines = [...routes].filter(([other, points]) => other === id || (drawn.has(other) && points.some((c, i) => {
+        const d = points[i + 1];
+        return d !== undefined && sameWay(a, b, c, d) && distance(near.point, nearestOnSegment(near.point, c, d)) <= SAME_RUN;
+    }))).map(([other]) => other).sort();
+    return { lines, point: near.point, segment: near.segment };
+}
+
+/** How near the pointer a bit of its line has to be for the hover card to keep off it, in screen px. */
+const POINTED = 40;
+/** How much wider than the line is drawn the card keeps off it, each side. */
+const LINE_ROOM = 3;
+
+/**
+ * The bit of a line the pointer is on, as rectangles on screen (canvas px), which the hover card keeps off: each
+ * segment of the line's route that comes within POINTED px of the pointer, as wide as the line is drawn with LINE_ROOM
+ * more each side, and its arrowhead (`head`, from weights.ts's arrowHead, its tip RoutedEdge's 3 px over the box) when
+ * that comes as near. `view` is the canvas's pan and zoom, so the route, in the Map's own coordinates, is on screen at
+ * point × zoom + (x, y).
+ */
+export function pointedBits(
+    route: readonly Point[],
+    pointer: Point,
+    view: { x: number; y: number; zoom: number },
+    width: number,
+    head: { half: number; length: number },
+): CanvasRect[] {
+    const screen = (p: Point): Point => ({ x: p.x * view.zoom + view.x, y: p.y * view.zoom + view.y });
+    const half = (width * view.zoom) / 2 + LINE_ROOM;
+    const bits: CanvasRect[] = [];
+    for (let i = 0; i + 1 < route.length; i++){
+        const a = screen(route[i]), b = screen(route[i + 1]);
+        if (distance(pointer, nearestOnSegment(pointer, a, b)) > POINTED) continue;
+        bits.push({ left: Math.min(a.x, b.x) - half, top: Math.min(a.y, b.y) - half, width: Math.abs(b.x - a.x) + 2 * half, height: Math.abs(b.y - a.y) + 2 * half });
+    }
+    const end = route.at(-1);
+    if (end !== undefined){
+        const tip = screen({ x: end.x, y: end.y - 3 });
+        const across = head.half * view.zoom + LINE_ROOM, along = head.length * view.zoom;
+        const rect = { left: tip.x - across, top: tip.y - along, width: 2 * across, height: along };
+        if (distance(pointer, { x: Math.max(rect.left, Math.min(pointer.x, rect.left + rect.width)), y: Math.max(rect.top, Math.min(pointer.y, tip.y)) }) <= POINTED) bits.push(rect);
+    }
+    return bits;
+}

package/app/map/shell.ts

@@ -0,0 +1,91 @@
+/**
+ * The Map's layout at any window size (the Workbench redesign, ADR-070; the owner's picks of 2026-10-27). Around the
+ * canvas sit the header, the explorer (the browser only), the toolbar, the legend sentence, the inspector and the
+ * status bar. As the window narrows or shortens each gives way in a fixed order, so nothing is cut off, nothing sits on
+ * anything else, and the page never scrolls sideways (the owner: "nothing should break at any size"). Only the canvas
+ * pans. Pure, so every rule is tested on its own; MapView reads it from the window's size.
+ *
+ * Widths (collapse option C):
+ * - the explorer is full from 1180 px, a 40 px rail from 600, and gone under 600 (search and the breadcrumb still reach
+ *   every folder); VS Code's panel has none;
+ * - the inspector stays beside the canvas while 560 px of canvas is left. With less it moves under the canvas in a window
+ *   at least 640 px tall, so the selected box and its details are both in view; in a shorter one it opens over the
+ *   canvas as a drawer, and where the window is narrow too it covers the canvas, the selected box keeping its Open and
+ *   Details beside it (narrow.ts's actionsPlace).
+ * Heights:
+ * - the legend sentence goes under 560 px tall (the ? help still has it), and under a 420 px canvas or a drawer;
+ * - the toolbar folds into the header under 420 px tall, one bar instead of two;
+ * - the status bar's two dots move to the end of that bar under 300 px tall, and the status bar goes;
+ * - the canvas keeps at least 160 px; below that the page scrolls down, never sideways.
+ */
+
+/** Where the inspector goes: beside the canvas, under it, over it as a drawer, over all of it, or nowhere. */
+export type InspectorPlace = "beside" | "below" | "drawer" | "cover" | "none";
+
+export type Shell = {
+    explorer: "full" | "rail" | "none";
+    inspector: InspectorPlace;
+    /** The toolbar's controls sit in the header's row instead of a row of their own. */
+    toolbarInHeader: boolean;
+    /** The status bar, or its two dots at the end of the header's row, or (VS Code's panel, as the owner picked) its slim form. */
+    status: "bar" | "inHeader";
+    legend: boolean;
+    /** The canvas's width, which the toolbar's steps go by. */
+    canvasWidth: number;
+    /** The least height the page keeps: the canvas's floor plus what's above and below it. Below it the page scrolls down. */
+    minHeight: number;
+};
+
+export const EXPLORER_WIDTH = 236;
+export const RAIL_WIDTH = 40;
+export const INSPECTOR_WIDTH = 300;
+/** The least canvas worth keeping beside the inspector. */
+export const MIN_CANVAS_BESIDE = 560;
+/** The explorer is full from this width, a rail from NARROW, and gone below. */
+export const EXPLORER_FULL = 1180;
+export const NARROW = 600;
+/** A window at least this tall takes the inspector under the canvas rather than over it. */
+export const BELOW_MIN_HEIGHT = 640;
+/** The inspector under the canvas takes this share of the height. */
+export const BELOW_SHARE = 0.42;
+export const LEGEND_MIN_HEIGHT = 560;
+export const LEGEND_MIN_CANVAS = 420;
+export const TOOLBAR_FOLD_HEIGHT = 420;
+export const STATUS_FOLD_HEIGHT = 300;
+/** The least canvas, in px tall: below it the page scrolls down instead. */
+export const MIN_CANVAS_HEIGHT = 160;
+
+/** The bars' heights, in px. */
+export const HEADER_HEIGHT = 42;
+export const EMBEDDED_HEADER_HEIGHT = 38;
+export const TOOLBAR_HEIGHT = 36;
+export const STATUS_HEIGHT = 24;
+export const LEGEND_HEIGHT = 44;
+
+/**
+ * The layout for a window `width` × `height` px. `embedded` is VS Code's panel (no explorer, the slim status bar);
+ * `selected` says whether anything is selected: beside the canvas the inspector describes the folder on screen when
+ * nothing is, and in the other places it shows only for a selection.
+ */
+export function shellLayout({ width, height, embedded, selected }: { width: number; height: number; embedded: boolean; selected: boolean }): Shell {
+    const explorer = embedded ? "none" : width >= EXPLORER_FULL ? "full" : width >= NARROW ? "rail" : "none";
+    const explorerWidth = explorer === "full" ? EXPLORER_WIDTH : explorer === "rail" ? RAIL_WIDTH : 0;
+    const besideRoom = width - explorerWidth - INSPECTOR_WIDTH;
+    const room: InspectorPlace = besideRoom >= MIN_CANVAS_BESIDE ? "beside"
+        : height >= BELOW_MIN_HEIGHT ? "below"
+        : width >= NARROW ? "drawer"
+        : "cover";
+    const inspector: InspectorPlace = room === "beside" || selected ? room : "none";
+    const canvasWidth = width - explorerWidth - (inspector === "beside" ? INSPECTOR_WIDTH : 0);
+    const toolbarInHeader = height < TOOLBAR_FOLD_HEIGHT;
+    const status = height < STATUS_FOLD_HEIGHT ? "inHeader" : "bar";
+    const legend = height >= LEGEND_MIN_HEIGHT && canvasWidth >= LEGEND_MIN_CANVAS && inspector !== "drawer" && inspector !== "cover";
+
+    // what sits above and below the canvas, and the inspector under it, which takes its share of the page's height
+    const chrome = (embedded ? EMBEDDED_HEADER_HEIGHT : HEADER_HEIGHT) + (toolbarInHeader ? 0 : TOOLBAR_HEIGHT)
+        + (status === "bar" ? STATUS_HEIGHT : 0) + (legend ? LEGEND_HEIGHT : 0);
+    const minHeight = inspector === "below"
+        ? Math.ceil((chrome + MIN_CANVAS_HEIGHT) / (1 - BELOW_SHARE))
+        : chrome + MIN_CANVAS_HEIGHT;
+    return { explorer, inspector, toolbarInHeader, status, legend, canvasWidth, minHeight };
+}

package/app/map/shortcuts.ts

@@ -26,7 +26,8 @@ export type ShortcutState = {
  * The Map's keyboard (HelpDialog's "Keyboard" list). Ctrl K or ⌘K opens search from anywhere. Every other key is the
  * Map's only while nothing is being typed and no dialog is open: with the source viewer open, Backspace or an arrow
  * would otherwise move the Map underneath and close the viewer with the panel it belongs to (second review I2).
- * Escape inside a dialog closes just that dialog; the dialogs handle it themselves.
+ * Escape inside a dialog closes just that dialog, and with a popover open just the popover. They handle it themselves and
+ * stop it before it gets here (useDismiss).
  */
 export function mapShortcut(event: { key: string; ctrlKey: boolean; metaKey: boolean }, state: ShortcutState): MapShortcut {
     if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") return { type: "search" };

package/app/map/summaries.ts

@@ -1,4 +1,4 @@
-import type { ErrorCode, SummaryStatus } from "@/lib/contracts";
+import type { DescribeResponse, ErrorCode, SummaryStatus } from "@/lib/contracts";
 
 /** A "summarize now" answer that isn't a summary: the error's code and its sentence (ApiError has both). */
 type SummaryAnswer = { code: ErrorCode | "NETWORK"; message: string };
@@ -10,15 +10,51 @@ type SummaryAnswer = { code: ErrorCode | "NETWORK"; message: string };
  */
 const WAITING: ReadonlySet<string> = new Set(["NOT_READY", "SUMMARIES_OFF"]);
 
-/** Whether opening a target should ask for its summary now (PIVOT_SPEC.md §5.3): it's missing or out of date. "off" never asks. */
-export function wantsSummary(status: SummaryStatus): boolean {
-    return status === "pending" || status === "stale";
+const missingOrOutOfDate = (status: SummaryStatus): boolean => status === "pending" || status === "stale";
+
+/**
+ * Whether opening a target should ask for its summary now (PIVOT_SPEC.md §5.3). It's missing or out of date, or a model
+ * wrote it with an older version of the prompt, which opening rewrites in the current style (Q2 B). While summaries are
+ * off that one isn't asked for, since the answer could only be SUMMARIES_OFF (P11). "off" never asks.
+ */
+export function wantsSummary(target: Pick<DescribeResponse, "summaryStatus" | "summaryOlderStyle">, summariesOff: boolean): boolean {
+    return missingOrOutOfDate(target.summaryStatus) || (target.summaryOlderStyle === true && !summariesOff);
+}
+
+/**
+ * What the panel remembers having asked for. A missing or out-of-date summary is asked for once per index version, as
+ * the index moving can mean it changed again. One that's only in the older style is asked for once per panel. A rewrite
+ * that fails leaves it current in the older style and moves the index (the stage refresh after it), so asking at each
+ * version would send again and again for as long as the panel stays open.
+ */
+export function askKey(target: Pick<DescribeResponse, "path" | "indexVersion" | "summaryStatus">): string {
+    return missingOrOutOfDate(target.summaryStatus) ? `${target.path}@${target.indexVersion}` : `${target.path}@older`;
+}
+
+/** What's on show in the panel: the description, or the "summarize now" answer that replaced it. */
+type ShownSummary = { tagline?: string; summary?: string; summaryStatus: SummaryStatus; summaryOlderStyle?: true };
+
+/**
+ * The quiet lines under a summary. "Refreshing…" while it's rewritten. "Out of date, it changed since it was
+ * summarized." when its input changed, except for a folder or the repo an older prompt wrote, which reads stale once a
+ * child is restyled though no code changed (P10). Nothing for the older style itself (Q1 A). testsNote is the import-count
+ * note, which belongs to a file's older summary only, since the current prompt gives no counts.
+ */
+export function summaryNotes(shown: ShownSummary, kind: DescribeResponse["kind"], refreshing: boolean): { notes: string[]; testsNote: boolean } {
+    const olderFolder = kind !== "file" && shown.summaryOlderStyle === true;
+    const notes = [
+        refreshing && shown.tagline ? "Refreshing…" : "",
+        shown.summaryStatus === "stale" && !refreshing && !olderFolder ? "Out of date, it changed since it was summarized." : "",
+    ].filter(Boolean);
+    // an older summary was written from an "Imported by" line that counts tests apart, and "Used by" counts them
+    const testsNote = Boolean(shown.summary) && kind === "file" && shown.summaryOlderStyle === true;
+    return { notes, testsNote };
 }
 
 /** What the panel says in place of a summary it doesn't have. */
 export function placeholderFor(status: SummaryStatus): string {
     switch (status){
-        case "off": return "Summaries are off: ANTHROPIC_API_KEY isn't set. With a key, each file and folder gets a short plain-language summary here, and search can match by meaning.";
+        case "off": return "Summaries are off, since ANTHROPIC_API_KEY isn't set. With a key, each file and folder gets a short plain-language summary here, and search can match by meaning.";
         case "failed": return "The last attempt to summarize this failed.";
         case "pending": return "Summarizing…";
         default: return "";

package/app/map/text.ts

@@ -36,14 +36,22 @@ function wordBefore(text: string, end: number): string {
     return text.slice(start, end).replace(/^\(/, "").toLowerCase();
 }
 
+/** A blank line, the break between two paragraphs. parseSummary leaves exactly one, but any whitespace on it counts. */
+const PARAGRAPH_BREAK = /\n\s*\n/;
+
 /**
- * A summary's first sentence (the panel's lead) and the rest, behind "Read full summary" (VISUAL_REFRESH.md §5).
+ * A summary's lead, which the panel shows first, and the rest, behind "Full summary" (VISUAL_REFRESH.md §5). A summary
+ * in paragraphs leads with its whole first paragraph, which the prompt keeps to a sentence or two on what the thing is
+ * for (D10). One in a single block, the way an older prompt wrote nearly all of them, leads with its first sentence.
  * A sentence ends at ".", "!" or "?" outside code, followed by whitespace and then something a sentence starts with,
  * unless the word before the period is an abbreviation. "3.4" and `main.ts` never split, since no space follows
  * their periods. When in doubt it doesn't split: a longer lead costs a line, a cut-off one costs the meaning.
  */
 export function splitSummary(summary: string): { lead: string; rest: string } {
     const text = summary.trim();
+    const paragraph = PARAGRAPH_BREAK.exec(text);
+    if (paragraph) return { lead: text.slice(0, paragraph.index), rest: text.slice(paragraph.index + paragraph[0].length) };
+
     let inCode = false;
 
     for (let i = 0; i < text.length; i++){

package/app/map/theme.ts

@@ -0,0 +1,197 @@
+/**
+ * The Map's colors (the Workbench redesign, 2026-10-27). Every gray comes from a theme: inside VS Code's panel the
+ * person's own (posted by the panel's relay, API_CONTRACTS §20's `nebulosity.theme`), in the browser and the demo a
+ * fixed one, VS Code's Dark 2026. Purple only means something (the selection, what's linked to it, the one primary
+ * button, the active tab, the logo), in the logo's own colors, a step darker on light themes so they keep their
+ * contrast against white. Gold, across from it, means what uses the selection.
+ *
+ * `fromTheme` is the approved mockup's rule (mockup3.html, the owner's picks of 2026-10-27): each part is mixed from the
+ * theme's background toward its text color by a set amount, strong enough that every box stands off any background.
+ * Pure, so the rule is tested on its own, and app/globals.css holds its result for Dark 2026.
+ */
+
+import type { BridgeThemeColors, ThemeKind } from "@/lib/contracts";
+
+export type { ThemeKind };
+
+/** A theme's colors, as the panel's relay reads them from VS Code's `--vscode-*` variables. Hex, `#rrggbb`. */
+export type ThemeInput = {
+    kind: ThemeKind;
+    /** editor.background: under the Map. */
+    editor: string;
+    /** sideBar.background: the Map's panels (header, explorer, inspector, status bar). */
+    side: string;
+    /** A border the theme defines (its high contrast border, a widget's, the panel's), if it has one. */
+    border?: string;
+    /** foreground: names and headings. */
+    fg: string;
+    /** descriptionForeground: the quietest text, if the theme has one. */
+    desc?: string;
+    /** focusBorder: the keyboard focus ring, if the theme has one. */
+    focus?: string;
+};
+
+/** Every token the Map draws with, by its CSS name (`--canvas`, …), each a `#rrggbb`, and `fade` a percentage. */
+export type Palette = {
+    canvas: string;
+    panel: string;
+    node: string;
+    "node-sel": string;
+    "row-sel": string;
+    divider: string;
+    border: string;
+    "linked-border": string;
+    text: string;
+    "text-2": string;
+    "text-3": string;
+    "edge-dim": string;
+    /** What the selection uses, in the logo's spoke color: its lines out, and Uses' bars, underline and mark (emphasis.ts's SIDE_COLOR). */
+    "edge-strong": string;
+    "glyph-dim": string;
+    "linked-glyph": string;
+    /** What uses the selection, in gold across from the purple of what it uses: its lines in, and Used by's bars, underline and mark. */
+    "used-by-edge": string;
+    accent: string;
+    "on-accent": string;
+    core: string;
+    agent: string;
+    danger: string;
+    ok: string;
+    focus: string;
+    /** How much of its own color a box away from the selection keeps, mixed with the background: "50%". */
+    fade: string;
+};
+
+/** VS Code's Dark 2026 (theme-defaults/themes/2026-dark.json), its default dark theme: the browser's and the demo's palette. */
+export const DARK_2026: ThemeInput = { kind: "dark", editor: "#121314", side: "#191A1B", border: "#2A2B2C", fg: "#BFBFBF", desc: "#8C8C8C" };
+
+const rgbOf = (hex: string): [number, number, number] => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) as [number, number, number];
+const hexOf = (rgb: readonly number[]): string => "#" + rgb.map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0")).join("").toUpperCase();
+
+/** `a` moved `t` of the way to `b`, channel by channel in sRGB (CSS's `color-mix(in srgb, …)` does the same). */
+export function mix(a: string, b: string, t: number): string {
+    const [x, y] = [rgbOf(a), rgbOf(b)];
+    return hexOf(x.map((v, i) => v + (y[i] - v) * t));
+}
+
+/**
+ * A CSS color as `#rrggbb`, or null when it isn't one this reads: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` and
+ * `rgba()`. A see-through color is laid over `under` first, since a box drawn in it would show what's behind it (VS
+ * Code gives some borders as a gray with alpha).
+ */
+export function parseColor(value: string, under: string = "#000000"): string | null {
+    const text = value.trim().toLowerCase();
+    let rgba: number[] | null = null;
+    const hex = /^#([0-9a-f]{3,8})$/.exec(text);
+    if (hex && [3, 4, 6, 8].includes(hex[1].length)){
+        const digits = hex[1].length <= 4 ? [...hex[1]].map((d) => d + d).join("") : hex[1];
+        rgba = [0, 2, 4, 6].map((i) => (i < digits.length ? parseInt(digits.slice(i, i + 2), 16) : 255));
+        rgba[3] /= 255;
+    }
+    const fn = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+%?)\s*)?\)$/.exec(text);
+    if (fn){
+        const alpha = fn[4] === undefined ? 1 : fn[4].endsWith("%") ? parseFloat(fn[4]) / 100 : parseFloat(fn[4]);
+        rgba = [Number(fn[1]), Number(fn[2]), Number(fn[3]), alpha];
+    }
+    if (rgba === null || rgba.some((v) => Number.isNaN(v))) return null;
+    const [r, g, b, a] = rgba;
+    const base = rgbOf(under);
+    const alpha = Math.min(1, Math.max(0, a));
+    return hexOf([r, g, b].map((v, i) => base[i] + (v - base[i]) * alpha));
+}
+
+/**
+ * The Map's palette for a theme. On high contrast themes the boxes are drawn in the theme's own border color and a box
+ * away from the selection keeps 70% of its color instead of 50%.
+ */
+export function fromTheme(t: ThemeInput): Palette {
+    const light = t.kind === "light" || t.kind === "hc-light";
+    const hc = t.kind === "hc" || t.kind === "hc-light";
+    const bg = t.editor;
+    const fg = t.fg;
+    const accent = light ? "#9333EA" : "#A855F7";
+    // how far each part is mixed from the background toward the text: boxes strong in every theme (the owner, 2026-10-27)
+    const k = { node: light ? 0.05 : 0.09, line: light ? 0.28 : 0.3, linked: 0.75, edge: 0.3, glyph: light ? 0.4 : 0.45 };
+    const line = mix(bg, fg, k.line);
+    // what uses the selection, in the owner's gold (2026-10-29, after pink was too like the purple), across from the
+    // purple of what it uses, a mustard on light themes and a step darker again on high contrast light, the way purple
+    // steps darker there, so its lines keep their contrast against white
+    const gold = t.kind === "hc-light" ? "#A16207" : light ? "#CA8A04" : "#FCD34D";
+    return {
+        canvas: bg,
+        panel: t.side,
+        node: hc ? bg : mix(bg, fg, k.node),
+        "node-sel": mix(bg, accent, light ? 0.1 : 0.16),
+        "row-sel": mix(t.side, accent, light ? 0.12 : 0.18),
+        divider: t.border ?? mix(bg, fg, 0.12),
+        border: hc ? t.border ?? line : line,
+        "linked-border": hc ? (light ? "#7E22CE" : "#C084FC") : mix(bg, accent, k.linked),
+        text: fg,
+        "text-2": mix(fg, bg, 0.22),
+        "text-3": t.desc ?? mix(fg, bg, 0.3),
+        "edge-dim": mix(bg, fg, hc ? 0.5 : k.edge),
+        "edge-strong": light ? "#7E22CE" : "#E9D5FF",
+        "glyph-dim": mix(bg, fg, hc ? 0.6 : k.glyph),
+        "linked-glyph": light ? "#A855F7" : "#C084FC",
+        "used-by-edge": gold,
+        accent,
+        "on-accent": light ? "#FFFFFF" : "#120C1C",
+        core: light ? accent : "#F0FDFF",
+        // Claude Code's orange, errors, the indexed dot and the focus ring, each a step darker on light themes
+        agent: light ? "#C2410C" : "#F08A4B",
+        danger: light ? "#B91C1C" : "#F07A7A",
+        ok: light ? "#0E7490" : "#5FC9D9",
+        focus: t.focus ?? (light ? "#0E7490" : "#67E8F9"),
+        fade: hc ? "70%" : "50%",
+    };
+}
+
+/** Whether a theme kind is a light one: the syntax colors, the native scrollbars and React Flow's own parts follow it. */
+export const isLightKind = (kind: ThemeKind | null): boolean => kind === "light" || kind === "hc-light";
+
+/**
+ * The theme a `nebulosity.theme` message names, its colors read as hex (each over the editor's background, so a
+ * see-through border becomes the gray it looks like), or null when its editor, side bar or text color can't be read.
+ */
+export function themeInputOf(kind: ThemeKind, colors: BridgeThemeColors): ThemeInput | null {
+    const editor = parseColor(colors.editor);
+    if (editor === null) return null;
+    const over = (value: string | undefined): string | null => (value === undefined ? null : parseColor(value, editor));
+    const side = over(colors.side);
+    const fg = over(colors.fg);
+    if (side === null || fg === null) return null;
+    const optional = (value: string | undefined): string | undefined => over(value) ?? undefined;
+    return { kind, editor, side, fg, border: optional(colors.border), desc: optional(colors.desc), focus: optional(colors.focus) };
+}
+
+/** The element the tokens live on, the page's `<html>`: the real one fits, and tests pass a stand-in. */
+export type ThemeRoot = { style: { setProperty(name: string, value: string): void }; setAttribute(name: string, value: string): void };
+
+/** Sets every token from a theme on the page's root, over globals.css's own values, and names its kind (`data-kind`). */
+export function applyTheme(root: ThemeRoot, input: ThemeInput): void {
+    for (const [name, value] of Object.entries(fromTheme(input))) root.style.setProperty(`--${name}`, value);
+    root.setAttribute("data-kind", input.kind);
+}
+
+/**
+ * Stand-ins for the other kinds until the panel's message brings the person's own colors: VS Code's Light 2026 and its
+ * two high contrast themes (theme-defaults/themes). The panel's address names the kind (`&kind=light`), so a light
+ * theme's Map is light from its first paint instead of flashing dark until the bridge is up.
+ */
+export const KIND_DEFAULTS: Record<Exclude<ThemeKind, "dark">, ThemeInput> = {
+    light: { kind: "light", editor: "#FFFFFF", side: "#FAFAFD", border: "#E2E2E5", fg: "#202020", desc: "#606060" },
+    hc: { kind: "hc", editor: "#000000", side: "#000000", border: "#6FC3DF", fg: "#FFFFFF", desc: "#FFFFFF" },
+    "hc-light": { kind: "hc-light", editor: "#FFFFFF", side: "#FFFFFF", border: "#0F4A85", fg: "#292929" },
+};
+
+/**
+ * The script the page runs before its first paint (app/layout.tsx): inside VS Code's panel, with a kind other than
+ * dark in the address, it sets that kind's stand-in tokens. Anywhere else it does nothing, so the browser and the
+ * demo keep globals.css's Dark 2026.
+ */
+export function earlyThemeScript(): string {
+    const palettes = Object.fromEntries(Object.entries(KIND_DEFAULTS).map(([kind, input]) => [kind, fromTheme(input)]));
+    return `(function(){try{var q=new URLSearchParams(location.search);if(q.get("embed")!=="vscode")return;`
+        + `var k=q.get("kind"),P=${JSON.stringify(palettes)},p=Object.prototype.hasOwnProperty.call(P,k)?P[k]:null;if(!p)return;`
+        + `var r=document.documentElement;for(var n in p)r.style.setProperty("--"+n,p[n]);r.setAttribute("data-kind",k);}catch(e){}})();`;
+}

package/app/map/useDismiss.ts

@@ -3,9 +3,25 @@
 import { useEffect, useRef, type RefObject } from "react";
 
 /**
- * Closes a popover (the status menu, the repo picker) on a click anywhere outside it or on Escape. Left open, the
- * status menu sat over the details panel until its button was clicked again (owner review of the refresh). Returns the
- * ref to put on the element that holds both the button and the popover, so clicking the button still toggles it.
+ * The popover's Escape. It closes the popover and stops the press at the document, before it reaches the window, where
+ * the Map's own Escape (MapView) would let go of the selection too. The help promises one press each, the popover, then
+ * the selection, then Claude Code's highlights. It stays on the document rather than catching the press first, on the
+ * way down, as the help and the source viewer do, so either of them opened over a popover still closes alone. On its
+ * own so a test can press it without a page (useDismiss.test.ts).
+ */
+export function closeOnEscape(onDismiss: () => void): (event: Pick<KeyboardEvent, "key" | "stopPropagation">) => void {
+    return (event) => {
+        if (event.key !== "Escape") return;
+        event.stopPropagation();
+        onDismiss();
+    };
+}
+
+/**
+ * Closes a popover (the toolbar's … menu, the status menu, the repo picker, the breadcrumb's folded folders) on a click
+ * anywhere outside it or on Escape, which goes no further (closeOnEscape). Left open, the status menu sat over the
+ * details panel until its button was clicked again (owner review of the refresh). Returns the ref to put on the element
+ * that holds both the button and the popover, so clicking the button still toggles it.
  */
 export function useDismiss<T extends HTMLElement>(open: boolean, onDismiss: () => void): RefObject<T | null> {
     const ref = useRef<T>(null);
@@ -19,9 +35,7 @@ export function useDismiss<T extends HTMLElement>(open: boolean, onDismiss: () =
         const onPointer = (event: PointerEvent): void => {
             if (ref.current && event.target instanceof Node && !ref.current.contains(event.target)) latest.current();
         };
-        const onKey = (event: KeyboardEvent): void => {
-            if (event.key === "Escape") latest.current();
-        };
+        const onKey = closeOnEscape(() => latest.current());
         document.addEventListener("pointerdown", onPointer);
         document.addEventListener("keydown", onKey);
         return () => {

package/app/map/useEditorBridge.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useSyncExternalStore } from "react";
 import type { BridgeFromMap, BridgeToMap } from "@/lib/contracts";
 import { createBridge, isEmbedded, type BridgeWindow } from "./embed";
 import { DEMO } from "./mode";
@@ -12,6 +12,17 @@ import { DEMO } from "./mode";
  */
 export const EMBEDDED = !DEMO && typeof window !== "undefined" && isEmbedded(window.location.search);
 
+const noSubscription = () => () => {};
+
+/**
+ * EMBEDDED for what the page draws: false on the server and while the page hydrates (the server can't know it's in VS
+ * Code's panel), then the real value. Reading EMBEDDED itself in a render made the panel's first client render differ
+ * from the server's, and React threw the page away and drew it again.
+ */
+export function useEmbedded(): boolean {
+    return useSyncExternalStore(noSubscription, () => EMBEDDED, () => false);
+}
+
 type Handlers = { onMessage: (message: BridgeToMap) => void; onReady: () => BridgeFromMap | null };
 
 export type EditorLink = {

package/app/map/useThemeKind.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import type { ThemeKind } from "@/lib/contracts";
+
+const KINDS: ReadonlySet<string> = new Set<ThemeKind>(["dark", "light", "hc", "hc-light"]);
+
+/** The page's theme kind (`data-kind` on `<html>`, set by theme.ts), dark when none is set. */
+function readKind(): ThemeKind {
+    const kind = document.documentElement.getAttribute("data-kind");
+    return kind !== null && KINDS.has(kind) ? (kind as ThemeKind) : "dark";
+}
+
+/** Calls `onChange` whenever `<html>`'s `data-kind` changes: the panel's theme message, or VS Code's theme switched. */
+function subscribe(onChange: () => void): () => void {
+    const observer = new MutationObserver(onChange);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-kind"] });
+    return () => observer.disconnect();
+}
+
+/**
+ * The theme kind the Map is drawn in, for what CSS can't follow by itself (React Flow's own color mode). Dark on the
+ * server and in the browser; inside VS Code's panel, the person's kind, from its first paint (theme.ts's
+ * earlyThemeScript) and again whenever the theme changes.
+ */
+export function useThemeKind(): ThemeKind {
+    return useSyncExternalStore(subscribe, readKind, () => "dark");
+}

package/app/map/useWindowSize.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import type { Size } from "./useSize";
+
+/** What the server renders the layout for, and what hydration starts from: the size the Map was designed at. */
+const SERVER_SIZE = "1440x900";
+
+/**
+ * The window's size as one string, so an unchanged size is the same snapshot. The width is the page's own, without a
+ * vertical scrollbar (clientWidth): a short window scrolls down below the canvas's floor (shell.ts), and laying out for
+ * the width with the scrollbar would push the page sideways by its width.
+ */
+function snapshot(): string {
+    return `${document.documentElement.clientWidth}x${window.innerHeight}`;
+}
+
+function subscribe(onChange: () => void): () => void {
+    window.addEventListener("resize", onChange);
+    // the scrollbar coming or going changes clientWidth without a resize
+    const observer = new ResizeObserver(onChange);
+    observer.observe(document.documentElement);
+    return () => {
+        window.removeEventListener("resize", onChange);
+        observer.disconnect();
+    };
+}
+
+/**
+ * The window's size in px, which the Map's layout goes by (shell.ts). Inside VS Code's panel the window is the panel.
+ * The server and the first client render use 1440 × 900, then the real size, so hydration never mismatches.
+ */
+export function useWindowSize(): Size {
+    const text = useSyncExternalStore(subscribe, snapshot, () => SERVER_SIZE);
+    const [width, height] = text.split("x").map(Number);
+    return { width, height };
+}