nebulosity 1.0.0 → 1.1.0

package/app/map/viewport.ts

@@ -1,11 +1,19 @@
+import type { MapEdge } from "@/lib/contracts";
+import { edgeKey } from "./emphasis";
 import { BOX_HEIGHT, BOX_WIDTH, FIT_PADDING, type Position } from "./levelLayout";
+import type { Point } from "./routes";
+import { arrowHead, boxHeadWidths, lineWidth, maxImportsOf } from "./weights";
 
 /**
  * Where a level opens (owner, 2026-10-13: "when you first open it, it should be a readable size"). A level is fitted to
  * the canvas as before, unless fitting it whole would shrink it past MIN_READABLE_ZOOM. Then it opens as wide as the
  * canvas allows (less SIDE_ROOM each side), between that floor and 100%, from its top, centred across, and the rest is
  * a scroll or a drag away: the floor alone left wide empty margins on busy levels (an outside critique, owner's pick).
- * The zoom controls' fit button still shows the whole level, and zooming out by hand still works (MapCanvas's minZoom).
+ * The toolbar's Fit still shows the whole level, and zooming out by hand still works (MapCanvas's minZoom).
+ *
+ * Both frame the drawn lines too (the owner, 2026-10-28): a lane beside the boxes ran off under the inspector. The
+ * boxes win, so framing the lines never shrinks them past LINES_FRAME_LEAST of their own fit, nor a level that opens
+ * fitted past MIN_READABLE_ZOOM. Lines cut off after a pan or a zoom are the person's doing, and stay.
  */
 
 /** Box names are 15 px, so at 0.75 they're 11.25 px: the smallest the Map opens a level at. */
@@ -22,9 +30,18 @@ export const TOP_INSET = 64;
  * opens VS Code's contrib, page 2, at 83% on a 1907 px screen instead of 75%.
  */
 export const SIDE_ROOM = 72;
+/** The room framed past the drawn lines' extent, so the outermost lane doesn't run along the canvas's edge. */
+export const LINES_MARGIN = 16;
+/**
+ * The least of the boxes' own fit that framing the lines may zoom out to: past it the boxes are framed alone and the
+ * outermost lines run off. Over VS Code, Fit then frames the lines on every page at rest, and with every line drawn
+ * keeps the boxes' fit on the densest few only (the merged-lines plan, fit4-final.log).
+ */
+export const LINES_FRAME_LEAST = 0.85;
 
 export type Bounds = { x: number; y: number; width: number; height: number };
 export type Viewport = { x: number; y: number; zoom: number };
+type Canvas = { width: number; height: number };
 
 /** The rectangle every box of a level covers; positions are top-left corners (levelLayout.ts). */
 export function boundsOf(positions: ReadonlyMap<string, Position>): Bounds {
@@ -39,30 +56,131 @@ export function boundsOf(positions: ReadonlyMap<string, Position>): Bounds {
     return { x: left, y: top, width: right - left, height: bottom - top };
 }
 
+/**
+ * How far drawn lines reach: each line's corners grown by half its width, and its head's half-width either side of its
+ * tip. Every route ends going down into its box's top (RoutedEdge.tsx), so the head reaches across there, not past it.
+ * Null when no line has a route.
+ */
+export function linesBounds(lines: readonly { points: readonly Point[]; width: number; headHalf: number }[]): Bounds | null {
+    let left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity;
+    for (const { points, width, headHalf } of lines){
+        if (points.length === 0) continue;
+        for (const { x, y } of points){
+            left = Math.min(left, x - width / 2);
+            top = Math.min(top, y - width / 2);
+            right = Math.max(right, x + width / 2);
+            bottom = Math.max(bottom, y + width / 2);
+        }
+        const tip = points[points.length - 1];
+        left = Math.min(left, tip.x - headHalf);
+        right = Math.max(right, tip.x + headHalf);
+    }
+    return left === Infinity ? null : { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/**
+ * The routed lines' reach (linesBounds), each as wide as MapCanvas draws it and under its box's one head (weights.ts),
+ * so what's framed is what's on screen.
+ */
+export function drawnLinesBounds(routes: ReadonlyMap<string, readonly Point[]>, edges: readonly MapEdge[]): Bounds | null {
+    const max = maxImportsOf(edges);
+    const heads = boxHeadWidths(edges);
+    const byKey = new Map(edges.map((e) => [edgeKey(e), e]));
+    return linesBounds([...routes].flatMap(([key, points]) => {
+        const edge = byKey.get(key);
+        if (edge === undefined) return [];
+        const width = lineWidth(edge.count, max);
+        return [{ points, width, headHalf: arrowHead(heads.get(edge.target) ?? width).half }];
+    }));
+}
+
+/** What a fit frames, by its middle and its size. */
+type Frame = { middle: Point; width: number; height: number };
+
+/**
+ * One side to side (or top to bottom) span of a frame, from the boxes' middle, as React Flow centres its fit: half the
+ * boxes and FIT_PADDING's share each way, or as far as the lines and LINES_MARGIN reach past that. Worked out from the
+ * middle, so lines inside the boxes' frame leave it exactly as it was.
+ */
+function span(start: number, size: number, lines?: { start: number; size: number }): { middle: number; size: number } {
+    const middle = start + size / 2;
+    const boxes = size / 2 + (size * FIT_PADDING) / 2;
+    if (lines === undefined) return { middle, size: 2 * boxes };
+    const before = Math.max(boxes, middle - (lines.start - LINES_MARGIN));
+    const after = Math.max(boxes, lines.start + lines.size + LINES_MARGIN - middle);
+    return { middle: middle + (after - before) / 2, size: before + after };
+}
+
+/** The boxes as React Flow's fit frames them, and with `lines`, as far as they reach past them too. */
+function frameOf(boxes: Bounds, lines?: Bounds): Frame {
+    const across = span(boxes.x, boxes.width, lines && { start: lines.x, size: lines.width });
+    const down = span(boxes.y, boxes.height, lines && { start: lines.y, size: lines.height });
+    return { middle: { x: across.middle, y: down.middle }, width: across.size, height: down.size };
+}
+
+const zoomFor = (frame: Frame, room: Canvas): number => Math.min(MAX_FIT_ZOOM, room.width / frame.width, room.height / frame.height);
+
+/** The boxes' frame, grown to the lines when that keeps LINES_FRAME_LEAST of the boxes' own fit (the boxes win). */
+function framed(boxes: Bounds, lines: Bounds | null, room: Canvas): Frame {
+    const own = frameOf(boxes);
+    if (lines === null) return own;
+    const both = frameOf(boxes, lines);
+    return zoomFor(both, room) >= LINES_FRAME_LEAST * zoomFor(own, room) ? both : own;
+}
+
+/**
+ * The toolbar's Fit: the level's boxes and its drawn lines (linesBounds) centred in the canvas, never past 100%, with
+ * no readable floor, since the person asked to see it whole. React Flow's own fit frames the boxes alone, and floors
+ * its padding to whole pixels, so a level without lines fits within a pixel of it.
+ */
+export function fitViewport(boxes: Bounds, lines: Bounds | null, canvas: Canvas): Viewport {
+    if (boxes.width === 0 || boxes.height === 0 || canvas.width === 0 || canvas.height === 0){
+        return { x: canvas.width / 2 - (boxes.x + boxes.width / 2), y: canvas.height / 2 - (boxes.y + boxes.height / 2), zoom: 1 };
+    }
+    const frame = framed(boxes, lines, canvas);
+    const zoom = zoomFor(frame, canvas);
+    return { x: canvas.width / 2 - frame.middle.x * zoom, y: canvas.height / 2 - frame.middle.y * zoom, zoom };
+}
+
 /**
  * The viewport a level opens at: React Flow's fit (the same zoom and centring, with FIT_PADDING) when that's readable,
  * otherwise as wide as the canvas allows, from the level's top, never under MIN_READABLE_ZOOM or over MAX_FIT_ZOOM.
  * `topBand` keeps a fitted level below a strip at the top: on a paged level the page pill sits there, and a level
- * centred in the whole canvas could open with its top-right box under the pill (deferred minor). Pure, so the rule is
- * tested apart from React Flow.
+ * centred in the whole canvas could open with its top-right box under the pill (deferred minor). `lines` is the drawn
+ * lines' reach (drawnLinesBounds), framed as Fit frames it while the fit stays readable, and across a level that opens
+ * from its top. Pure, so the rule is tested apart from React Flow.
  */
-export function initialViewport(bounds: Bounds, canvas: { width: number; height: number }, topBand = 0): Viewport {
+export function initialViewport(bounds: Bounds, canvas: Canvas, topBand = 0, lines: Bounds | null = null): Viewport {
     const below = canvas.height - topBand;
-    const centre = (zoom: number): Viewport => ({
-        x: canvas.width / 2 - (bounds.x + bounds.width / 2) * zoom,
-        y: topBand + below / 2 - (bounds.y + bounds.height / 2) * zoom,
+    const centre = (frame: Frame, zoom: number): Viewport => ({
+        x: canvas.width / 2 - frame.middle.x * zoom,
+        y: topBand + below / 2 - frame.middle.y * zoom,
         zoom,
     });
-    if (bounds.width === 0 || bounds.height === 0 || canvas.width === 0 || canvas.height === 0) return centre(1);
+    if (bounds.width === 0 || bounds.height === 0 || canvas.width === 0 || canvas.height === 0) return centre(frameOf(bounds), 1);
 
-    const fit = Math.min(
-        MAX_FIT_ZOOM,
-        canvas.width / (bounds.width * (1 + FIT_PADDING)),
-        below / (bounds.height * (1 + FIT_PADDING)),
-    );
-    if (fit >= MIN_READABLE_ZOOM) return centre(fit);
+    const room = { width: canvas.width, height: below };
+    const own = frameOf(bounds);
+    const fit = zoomFor(own, room);
+    if (fit >= MIN_READABLE_ZOOM){
+        // the lines may not take a page that fits readably under the floor: then it keeps the boxes' view
+        const frame = framed(bounds, lines, room);
+        const zoom = zoomFor(frame, room);
+        return zoom >= MIN_READABLE_ZOOM ? centre(frame, zoom) : centre(own, fit);
+    }
 
     // a tall level reads top to bottom like a page, so its width decides the zoom
-    const zoom = Math.min(MAX_FIT_ZOOM, Math.max(MIN_READABLE_ZOOM, (canvas.width - 2 * SIDE_ROOM) / bounds.width));
-    return { x: canvas.width / 2 - (bounds.x + bounds.width / 2) * zoom, y: TOP_INSET - bounds.y * zoom, zoom };
+    const wide = (width: number): number => Math.min(MAX_FIT_ZOOM, Math.max(MIN_READABLE_ZOOM, (canvas.width - 2 * SIDE_ROOM) / width));
+    let zoom = wide(bounds.width);
+    let middle = bounds.x + bounds.width / 2;
+    if (lines !== null){
+        // the boxes and the lines across, SIDE_ROOM their margin, unless that shrinks the boxes past LINES_FRAME_LEAST
+        const left = Math.min(bounds.x, lines.x);
+        const right = Math.max(bounds.x + bounds.width, lines.x + lines.width);
+        if (wide(right - left) >= LINES_FRAME_LEAST * zoom){
+            zoom = wide(right - left);
+            middle = (left + right) / 2;
+        }
+    }
+    return { x: canvas.width / 2 - middle * zoom, y: TOP_INSET - bounds.y * zoom, zoom };
 }

package/app/map/weights.ts

@@ -0,0 +1,80 @@
+import type { MapEdge, MapNode } from "@/lib/contracts";
+
+/**
+ * What the Map draws bigger when there's more of it (the Workbench redesign, ADR-070): a folder's dot by how many files
+ * it holds, a line's width by how many imports it carries, and a box's arrowhead by the heaviest line into it, since
+ * its lines share one (boxHeadWidths). Each is a log scale against the largest on the page, so VS Code's src (10,280
+ * files) and a folder of 3 both read. Pure, so the scales are tested alone.
+ */
+
+/** A folder's dot, 6 px across for an empty one up to 18 px for the page's largest. */
+export const DOT_MIN = 6;
+export const DOT_MAX = 18;
+
+export function dotSize(files: number, maxFiles: number): number {
+    if (maxFiles <= 0) return DOT_MIN;
+    return DOT_MIN + ((DOT_MAX - DOT_MIN) * Math.log10(Math.max(0, files) + 1)) / Math.log10(maxFiles + 1);
+}
+
+/**
+ * A line, 1 px for a single import up to 6 px for the page's heaviest. The spec's 10 px made every strong line of a dense
+ * level a 7 to 10 px tube, too alike to tell apart (the owner, 2026-10-27, on src/vs).
+ */
+export const LINE_MIN = 1;
+export const LINE_MAX = 6;
+
+export function lineWidth(imports: number, maxImports: number): number {
+    if (maxImports <= 1 || imports <= 1) return LINE_MIN;
+    return LINE_MIN + ((LINE_MAX - LINE_MIN) * Math.log(imports)) / Math.log(maxImports);
+}
+
+/**
+ * A filled arrowhead wider than its line by a margin on each side, so it still stands out on the thickest line (the
+ * owner, 2026-10-27: the spec's small open chevron disappeared on thick lines). `half` is half its width, `length` how
+ * far it reaches back from its tip, both in px.
+ */
+export function arrowHead(width: number): { half: number; length: number } {
+    return { half: Math.max(4.5, 0.9 * width + 3), length: Math.max(7, 1.2 * width + 5) };
+}
+
+/** The largest folder on a page, by files: what its dots are scaled against. Doorways stand for other pages, so they don't count. */
+export const maxFilesOf = (nodes: readonly MapNode[]): number => Math.max(0, ...nodes.filter((n) => n.kind === "folder").map((n) => n.fileCount));
+
+/** The heaviest line on a page, by imports. */
+export const maxImportsOf = (edges: readonly MapEdge[]): number => Math.max(0, ...edges.map((e) => e.count));
+
+/**
+ * The width each box's one arrowhead is sized for (arrowHead), by box. The lines into a box share its head, so it's
+ * sized for the heaviest of them on the page, drawn or not, and never grows when a hover draws a heavier one (the
+ * owner, 2026-10-28). A line from a box to itself isn't drawn, so it doesn't count.
+ */
+export function boxHeadWidths(edges: readonly MapEdge[]): Map<string, number> {
+    const max = maxImportsOf(edges);
+    const heads = new Map<string, number>();
+    for (const e of edges){
+        if (e.source !== e.target) heads.set(e.target, Math.max(heads.get(e.target) ?? 0, lineWidth(e.count, max)));
+    }
+    return heads;
+}
+
+/** How many of the page's heaviest lines carry their count, whatever is selected. */
+export const LABELLED_LINES = 3;
+
+/**
+ * The lines whose count is written on them: the page's three heaviest (ties by source, then target, so the same page
+ * always labels the same ones) and every line of the selected box. A line that carries one import goes without, on any
+ * page: a busy box's lines were covered in 1s, the thinnest line already says it, and the inspector and a line's hover
+ * sentence give it in words (the owner, 2026-10-28). Keys are "source->target", as React Flow's ids. A count is drawn
+ * only where it fits clear of everything else (routes.ts's placeCounts).
+ */
+export function labelledLines(edges: readonly MapEdge[], selected: string | null): Set<string> {
+    const key = (e: MapEdge): string => `${e.source}->${e.target}`;
+    const counted = edges.filter((e) => e.count > 1);
+    const heaviest = counted
+        .filter((e) => e.source !== e.target)
+        .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, LABELLED_LINES)
+        .map(key);
+    const ofSelected = selected === null ? [] : counted.filter((e) => e.source === selected || e.target === selected).map(key);
+    return new Set([...heaviest, ...ofSelected]);
+}

package/app/page.tsx

@@ -1,13 +1,11 @@
 import MapView from "./map/MapView";
-import { MIN_HEIGHT, MIN_WIDTH } from "./map/narrow";
 
 export default function Home(){
     // A server component: a flat canvas (VISUAL_REFRESH.md §3). The Map loads its data in the browser, through app/map/api.ts.
-    // It fills the window down to the floor (narrow.ts); below it, it keeps that size and the page scrolls. It fills the
-    // body's column rather than 100dvh: a sideways scrollbar takes height from the window, and 100dvh would then scroll
-    // down by the scrollbar's height too.
+    // It fills the window at any size (app/map/shell.ts); in a window shorter than its least height it keeps that height
+    // and the page scrolls down. Nothing in it is wider than the window, so the page never scrolls sideways.
     return (
-        <div data-testid="map-root" style={{ minWidth: MIN_WIDTH, minHeight: MIN_HEIGHT }} className="relative w-full flex-1 overflow-hidden bg-canvas">
+        <div data-testid="map-root" className="relative flex w-full flex-1 flex-col bg-canvas">
             <MapView />
         </div>
     );

package/lib/background/child.ts

@@ -2,6 +2,7 @@ import type { IndexEventMap, SummarizeResponse } from "../contracts";
 import type { StoredSummary } from "../db/store/summaries";
 import { errorResponseFor } from "../engine/errors";
 import type { IndexResult } from "../index/pipeline";
+import { writtenInOlderStyle } from "../index/summarize/prompts";
 import type { ChildMessage, ParentMessage } from "./protocol";
 import type { BackgroundService } from "./service";
 
@@ -13,6 +14,7 @@ export function toSummarizeResponse(row: StoredSummary): SummarizeResponse {
         ...(row.tagline ? { tagline: row.tagline, summary: row.summary ?? "" } : {}),
         summaryStatus: row.status,
         ...(row.status === "failed" && row.error ? { summaryError: row.error } : {}),
+        ...(writtenInOlderStyle(row) ? { summaryOlderStyle: true as const } : {}),
     };
 }
 

package/lib/background/service.ts

@@ -12,6 +12,7 @@ import { configuredSummaryModels, SummaryModelsError, type SummaryModelsResoluti
 import { DEFAULT_BUDGET_USD, runSummaries, StructureNotReadyError, summarizeNow } from "../index/summarize/run";
 import type { PlannedTarget } from "../index/summarize/plan";
 import { snapshotOf } from "../index/summarize/pricing";
+import { writtenInOlderStyle } from "../index/summarize/prompts";
 import { refreshSummaryStatus } from "../index/summarize/status";
 import type { Summarizer } from "../index/summarize/types";
 import { applyFileChanges } from "../index/update";
@@ -200,20 +201,24 @@ export function createBackgroundService(deps: BackgroundDeps): BackgroundService
         return (repoId === null ? null : approvedBudgetUsd(db, repoId)) ?? DEFAULT_BUDGET_USD;
     }
 
+    /** The repo's stored summaries by targetKey, read once per job as it starts, so every check the job makes reads the same rows. */
+    function storedRows(repo: string): Map<string, StoredSummary> {
+        const db = getDb();
+        const repoId = findRepository(db, repoKey(repo));
+        return new Map(repoId === null ? [] : loadSummaries(db, repoId).map((s) => [targetKey(s.kind, s.path), s]));
+    }
+
     /**
      * What an automatic job (a refresh after a save, the sweep) may send without asking (ADR-066, R17): a target whose
      * stored text the model now in use for its kind wrote (so it's out of date only because its inputs changed), or one
      * no model has written yet. Text another model wrote waits for `nebulosity summarize`'s estimate and yes, "Summarize
      * now", or a panel being opened: redoing it is a model change, and only a yes pays for that. A dated snapshot the API
      * reported (`<model>-20261001`) counts as its model, and nothing else does: claude-sonnet-5-5 isn't claude-sonnet-5
-     * (snapshotOf). Read once per job, from the rows as the job starts.
+     * (snapshotOf). `rows` are the job's storedRows.
      */
-    function sentUnasked(repo: string): (target: PlannedTarget) => boolean {
-        const db = getDb();
-        const repoId = findRepository(db, repoKey(repo));
-        const writtenBy = new Map(repoId === null ? [] : loadSummaries(db, repoId).map((s) => [targetKey(s.kind, s.path), s.model]));
+    function sentUnasked(rows: ReadonlyMap<string, StoredSummary>): (target: PlannedTarget) => boolean {
         return (target) => {
-            const model = writtenBy.get(targetKey(target.kind, target.path));
+            const model = rows.get(targetKey(target.kind, target.path))?.model;
             return !model || model === "template" || model === target.model || snapshotOf(model) === target.model;
         };
     }
@@ -276,7 +281,7 @@ export function createBackgroundService(deps: BackgroundDeps): BackgroundService
         }
 
         const wanted = new Set(paths.map((p) => targetKey("file", p)));
-        const unasked = sentUnasked(repo);
+        const unasked = sentUnasked(storedRows(repo));
         // The content whose quiet minute is up: each file's input hash as this run first plans it. A file saved again
         // mid-refresh (structure updates don't wait for refreshes) plans with a new hash and isn't sent again here: its
         // update restarted its own minute. Otherwise every save during a wave would be paid for at once.
@@ -318,7 +323,8 @@ export function createBackgroundService(deps: BackgroundDeps): BackgroundService
     /**
      * Out-of-date folders whose children are settled, deepest first, at most SWEEP_MAX_FOLDERS (PIVOT_SPEC.md §5.6): only
      * those the model now in use wrote, or that no model has written (sentUnasked). After a folder or repo model change
-     * the rest wait for a yes, instead of being redone 20 every 10 minutes with no estimate (R17).
+     * the rest wait for a yes, instead of being redone 20 every 10 minutes with no estimate (R17). A folder or the repo
+     * an older prompt version wrote waits too, to be opened or redone by `nebulosity summarize` (Q2 B).
      */
     async function runSweep(): Promise<void> {
         const repo = root;
@@ -332,18 +338,28 @@ export function createBackgroundService(deps: BackgroundDeps): BackgroundService
             return;
         }
 
-        const unasked = sentUnasked(repo);
+        const rows = storedRows(repo);
+        const unasked = sentUnasked(rows);
+        const olderStyle = (target: PlannedTarget): boolean => {
+            const row = rows.get(targetKey(target.kind, target.path));
+            return row !== undefined && writtenInOlderStyle(row);
+        };
         try{
             const result = await runSummaries(repo, {
                 summarizer: deps.summarizer,
                 models,
                 transport: "direct",
                 refreshStaleFolders: true,
+                // such a folder plans lazy, so it never keeps the folder above it waiting (Q2 B, the select below)
+                olderFoldersWaitToBeOpened: true,
                 wait: false,
                 budgetUsd: INCREMENTAL_BUDGET_USD,
                 budgetScope: "run",
                 repoBudgetUsd: approvedBudget(repo),
-                select: (target) => target.kind !== "file" && unasked(target),
+                // Q2 B: a folder or the repo an older prompt wrote is left to be opened, even once its inputs change (an
+                // edit below it, or a child a panel restyled), so the sweep never restyles the folders above an edit
+                // unasked. The refresh after a save keeps redoing an edited file whatever prompt wrote it (P1).
+                select: (target) => target.kind !== "file" && unasked(target) && !olderStyle(target),
                 maxTargets: SWEEP_MAX_FOLDERS,
                 onProgress: (message) => log(`sweep: ${message}`),
             });

package/lib/contracts.ts

@@ -132,6 +132,8 @@ export type DescribeResponse = {
   summaryStatus: SummaryStatus;
   /** Why the last attempt failed, when summaryStatus is "failed". */
   summaryError?: string;
+  /** A model wrote this summary with an older version of the prompt (ADR-034, amended 2026-10-29). It reads in the older style, one block that may count importers, until it's rewritten. */
+  summaryOlderStyle?: true;
   /** For a folder or file, the docs linked to it or the folders above it; for the repo, the docs to read first (ADR-054). Left out when none. */
   docs?: DocPointer[];
   stats: { fileCount: number; lineCount: number };
@@ -189,6 +191,8 @@ export type SummarizeResponse = {
   summaryStatus: SummaryStatus;
   /** Why it failed, when summaryStatus is "failed". */
   summaryError?: string;
+  /** A model wrote this summary with an older version of the prompt (ADR-034, amended 2026-10-29). It reads in the older style, one block that may count importers, until it's rewritten. */
+  summaryOlderStyle?: true;
 };
 
 /** Where a repo was cloned from: its origin remote's owner and name ("microsoft" / "vscode") — docs/API_CONTRACTS.md §15 */
@@ -220,13 +224,32 @@ export type BridgeToMap =
   /** A deliberate jump: focus on the path, pushing a history entry. */
   | { type: "nebulosity.show"; path: string }
   | { type: "nebulosity.highlight"; paths: string[] }
-  | { type: "nebulosity.clear" };
+  | { type: "nebulosity.clear" }
+  /**
+   * The editor's color theme, sent by the webview itself after the handshake and again whenever the theme changes, so
+   * the Map takes its grays from it (the Workbench redesign, ADR-070). Added without a version change: an older Map
+   * ignores it, and an older webview never sends it, so the Map keeps its own palette.
+   */
+  | { type: "nebulosity.theme"; kind: ThemeKind; colors: BridgeThemeColors };
+
+/** Which kind of theme VS Code has on: its webview's `vscode-light`, `vscode-dark` and two high contrast kinds. */
+export type ThemeKind = "dark" | "light" | "hc" | "hc-light";
+
+/**
+ * A theme's colors as the webview reads them from VS Code's `--vscode-*` variables, raw CSS colors (`#1f1f1f`,
+ * `rgba(…)`): editor.background, sideBar.background, a border (the high contrast border, else a widget's, the
+ * panel's or the side bar's), foreground, descriptionForeground and focusBorder. A theme may leave out the optional ones.
+ */
+export type BridgeThemeColors = { editor: string; side: string; fg: string; border?: string; desc?: string; focus?: string };
 
 /** Messages from the Map to the webview — docs/API_CONTRACTS.md §20. */
 export type BridgeFromMap =
   /** The answer to hello. */
   | { type: "nebulosity.ready"; version: 1 }
-  /** A file box or a declaration was picked. */
+  /**
+   * Open the file in the editor: Open in VS Code (the source viewer's at its highlighted line), a double-clicked file
+   * box, or a narrow window's Open beside it. A click on a box only selects it (amended 2026-10-29).
+   */
   | { type: "nebulosity.open"; path: string; line?: number }
   /** A new level was drawn, the selection changed on the level drawn, or a `ready` was answered while a level is on screen (the extension's test and benchmarks read it). */
   | { type: "nebulosity.drawn"; path: string; page: number; selected: string | null };

package/lib/db/migrations/0011_plain_summaries_prompt_version.sql

@@ -0,0 +1 @@
+ALTER TABLE `summaries` ADD `prompt_version` integer;