nebulosity 1.0.0 → 1.1.0

package/app/map/narrow.ts

@@ -1,36 +1,9 @@
 /**
- * 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.
+ * The Map's small placements at any window size (VISUAL_REFRESH.md, "Narrow windows"): a selected box's actions, a
+ * folded breadcrumb, a popover kept inside the window, and the error line's form. The layout itself, what gives way as
+ * the window narrows or shortens, is shell.ts's (the Workbench redesign, ADR-070). Pure, so each rule is tested alone.
  */
 
-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
@@ -47,7 +20,9 @@ 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.
+ * box hanging off an edge (a level opened from its top at 75%) never takes them past it. Each axis is its own rule. A
+ * box out of sight above or below (selected by a search pick or Follow in a short window, or panned away) keeps them 8 px
+ * inside the canvas's top or bottom, since they stand in for the inspector, which is always in sight (2026-10-29).
  */
 export function actionsPlace(
     box: { left: number; top: number; width: number; height: number },
@@ -55,27 +30,13 @@ export function actionsPlace(
     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 beside = actionsSide(box.top, box.height, canvasHeight) === "bottom" ? box.top + box.height + ACTIONS_GAP : box.top - ACTIONS_GAP - actions.height;
+    const top = Math.max(Math.min(beside, canvasHeight - ACTIONS_GAP - actions.height), ACTIONS_GAP);
     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
@@ -95,6 +56,151 @@ export function trailStart(widths: readonly number[], available: number, ellipsi
     return last;
 }
 
+/** A rectangle on the canvas, in canvas px. */
+export type CanvasRect = { left: number; top: number; width: number; height: number };
+
+/** The least room the card keeps from the canvas's sides. */
+export const CARD_EDGE = 8;
+/**
+ * The tail a card points at its line with, a comic's speech bubble's (the owner, 2026-10-29): this wide at its base and
+ * this long, one size whatever the line, its tip TAIL_GAP short of the line's edge, its middle TAIL_INSET along the
+ * card's side from the corner nearest the line, so the card keeps the same distance from the spot it's about.
+ */
+export const TAIL_BASE = 12;
+export const TAIL_LENGTH = 7;
+const TAIL_GAP = 1;
+const TAIL_INSET = 16;
+/** The least a tail's middle keeps from the card's corners, its base clear of their 6 px rounding. */
+const TAIL_END = 12;
+/**
+ * The bit of line right at the spot, each way from it, which the card covers in no window it fits, as wide as the
+ * heaviest line is drawn.
+ */
+const CARD_SPOT = 6;
+
+/** Which side of the card its tail comes out of. */
+export type TailSide = "top" | "bottom" | "left" | "right";
+/**
+ * A card's place (its top-left corner, canvas px), and its tail: the side it comes out of and how far along that side
+ * its middle is, from the card's left or top. No tail where the card couldn't keep its distance from the spot.
+ * `rises` says the card runs up from its tail, so a pinned card grows up from it.
+ */
+export type BubblePlace = { left: number; top: number; tail: { side: TailSide; at: number } | null; rises: boolean };
+
+const overlaps = (a: CanvasRect, b: CanvasRect): boolean =>
+    a.left < b.left + b.width && b.left < a.left + a.width && a.top < b.top + b.height && b.top < a.top + a.height;
+
+/** How far the card's side keeps from the middle of a line `half` px wide each side, its tail between them. */
+const tailReach = (half: number): number => half + TAIL_GAP + TAIL_LENGTH;
+
+/**
+ * Where the card about the lines under the pointer goes, pointing at `spot`, the point of the line nearest the pointer
+ * (canvas px), with its tail across the line, never along it. Beside a line that runs up and down there (`upright`),
+ * the tail comes out of the card's side, and over or under a level one out of its bottom or top, so the card never
+ * lies on the line it's about. `half` is half the line's width on screen. The places are tried above and left first
+ * (the owner's pick of 2026-10-29, closest to the pointer's tip, where nothing of the pointer is, and clear of the box
+ * a line runs down into): left of an upright line rising from the tail, then right of it, then left and right going
+ * down; over a level line reaching left from the tail, then right, then under it; then each of those slid along the
+ * line, its tail still on the spot, to fit the canvas near its edge. The first inside the canvas, CARD_EDGE in from its
+ * sides, and clear of `line` (the bit of line pointed at and its arrowhead, as rectangles as wide
+ * as they're drawn) and of `clear` (what's over the canvas: a drawer, a box's actions, the banner) wins, then the first
+ * inside and clear of the rest that keeps off the line right at the spot. Where none fits, the first moved inside the
+ * canvas that's clear, then the first moved inside that keeps off the spot, then just over or under the spot (a canvas
+ * too narrow for the card beside an upright line), then the first moved inside: the card never leaves the canvas, and
+ * moved, it can't keep its tail.
+ */
+export function bubblePlace(
+    spot: { x: number; y: number },
+    upright: boolean,
+    half: number,
+    card: { width: number; height: number },
+    canvas: { width: number; height: number },
+    line: readonly CanvasRect[],
+    clear: readonly CanvasRect[],
+): BubblePlace {
+    const { width, height } = card;
+    const reach = tailReach(half);
+    const tries: BubblePlace[] = upright ? [
+        { left: spot.x - reach - width, top: spot.y + TAIL_INSET - height, tail: { side: "right", at: height - TAIL_INSET }, rises: true },
+        { left: spot.x + reach, top: spot.y + TAIL_INSET - height, tail: { side: "left", at: height - TAIL_INSET }, rises: true },
+        { left: spot.x - reach - width, top: spot.y - TAIL_INSET, tail: { side: "right", at: TAIL_INSET }, rises: false },
+        { left: spot.x + reach, top: spot.y - TAIL_INSET, tail: { side: "left", at: TAIL_INSET }, rises: false },
+    ] : [
+        { left: spot.x + TAIL_INSET - width, top: spot.y - reach - height, tail: { side: "bottom", at: width - TAIL_INSET }, rises: true },
+        { left: spot.x - TAIL_INSET, top: spot.y - reach - height, tail: { side: "bottom", at: TAIL_INSET }, rises: true },
+        { left: spot.x + TAIL_INSET - width, top: spot.y + reach, tail: { side: "top", at: width - TAIL_INSET }, rises: false },
+        { left: spot.x - TAIL_INSET, top: spot.y + reach, tail: { side: "top", at: TAIL_INSET }, rises: false },
+    ];
+    // near the canvas's edge, each place also slides along the line, inside the canvas, with its tail still on the spot,
+    // as far as the tail keeps TAIL_END from the card's corners: the tail stays one size
+    const slid = tries.map((at): BubblePlace => {
+        const along = upright
+            ? Math.max(CARD_EDGE, Math.min(at.top, canvas.height - CARD_EDGE - height))
+            : Math.max(CARD_EDGE, Math.min(at.left, canvas.width - CARD_EDGE - width));
+        const tailAt = (upright ? spot.y : spot.x) - along;
+        if (at.tail === null || tailAt < TAIL_END || tailAt > (upright ? height : width) - TAIL_END) return at;
+        return { ...at, ...(upright ? { top: along } : { left: along }), tail: { side: at.tail.side, at: tailAt } };
+    });
+    const placed = [...tries, ...slid];
+    const box = (at: { left: number; top: number }): CanvasRect => ({ ...at, width, height });
+    const inside = (at: BubblePlace): boolean =>
+        at.left >= CARD_EDGE && at.top >= CARD_EDGE && at.left + width <= canvas.width - CARD_EDGE && at.top + height <= canvas.height - CARD_EDGE;
+    const free = (at: { left: number; top: number }): boolean => [...line, ...clear].every((r) => !overlaps(box(at), r));
+    const near = { left: spot.x - CARD_SPOT, top: spot.y - CARD_SPOT, width: 2 * CARD_SPOT, height: 2 * CARD_SPOT };
+    const offSpot = (at: { left: number; top: number }): boolean => !overlaps(box(at), near) && clear.every((r) => !overlaps(box(at), r));
+    const movedIn = tries.map((at): BubblePlace => ({ ...insideCanvas(at, card, canvas), tail: null, rises: at.rises }));
+    const overUnder = [spot.y - CARD_SPOT - 1 - height, spot.y + CARD_SPOT + 1]
+        .map((top): BubblePlace => ({ ...insideCanvas({ left: spot.x - width / 2, top }, card, canvas), tail: null, rises: top < spot.y }));
+    return placed.find((at) => inside(at) && free(at)) ?? placed.find((at) => inside(at) && offSpot(at))
+        ?? movedIn.find(free) ?? [...movedIn, ...overUnder].find(offSpot) ?? movedIn[0];
+}
+
+/** Whether a card `cardWidth` wide fits beside an upright line at `spotX`, its tail between them, on either side. */
+const fitsBeside = (spotX: number, half: number, cardWidth: number, canvasWidth: number): boolean =>
+    Math.max(spotX - tailReach(half) - CARD_EDGE, canvasWidth - CARD_EDGE - spotX - tailReach(half)) >= cardWidth;
+
+/**
+ * A card's place moved inside the canvas, CARD_EDGE in from its sides, the least it takes: a pinned card the wheel's
+ * zoom took to the canvas's edge stays in sight (LineCard), as a card with no place that fits does.
+ */
+export function insideCanvas(at: { left: number; top: number }, card: { width: number; height: number }, canvas: { width: number; height: number }): { left: number; top: number } {
+    return {
+        left: Math.max(CARD_EDGE, Math.min(at.left, canvas.width - CARD_EDGE - card.width)),
+        top: Math.max(CARD_EDGE, Math.min(at.top, canvas.height - CARD_EDGE - card.height)),
+    };
+}
+
+/**
+ * The height a card `cardWidth` wide has for itself on `canvas`, pointing at `spot` (bubblePlace): over or under a level
+ * line, past its tail, whichever has more, or beside an upright one the canvas's height inside its edges, the card
+ * sliding along the line to fit. Where the card can't be beside an upright line, too wide for the canvas there or the
+ * spot within TAIL_END of the canvas's top or bottom, it's the room just over or under the spot. So a card that fits it
+ * stays off the line at the spot in any window, and keeps its tail wherever it can.
+ */
+export function bubbleRoom(spot: { x: number; y: number }, upright: boolean, half: number, cardWidth: number, canvas: { width: number; height: number }): number {
+    if (!upright) return Math.max(spot.y - tailReach(half) - CARD_EDGE, canvas.height - CARD_EDGE - spot.y - tailReach(half));
+    const tailFits = spot.y >= CARD_EDGE + TAIL_END && spot.y <= canvas.height - CARD_EDGE - TAIL_END;
+    return fitsBeside(spot.x, half, cardWidth, canvas.width) && tailFits
+        ? canvas.height - 2 * CARD_EDGE
+        : Math.max(spot.y - CARD_SPOT - 1 - CARD_EDGE, canvas.height - CARD_EDGE - spot.y - CARD_SPOT - 1);
+}
+
+/** The most lines the hover card lists before "and N more" (the owner, 2026-10-29), and each row's height (leading-[18px]). */
+export const CARD_ROWS = 5;
+export const CARD_ROW = 18;
+/** The card's border and padding, top and bottom together (border and py-1). */
+export const CARD_FRAME = 10;
+
+/**
+ * How many of a run's `total` lines the hover card lists in `room` px of height: CARD_ROWS, or all of them where one
+ * more would only replace the "and 1 more" row, but no more than fit under the title with the "and N more" row.
+ */
+export function hoverCardRows(total: number, room: number): number {
+    let rows = total <= CARD_ROWS + 1 ? total : CARD_ROWS;
+    while (rows > 0 && CARD_FRAME + CARD_ROW * (1 + rows + (rows < total ? 1 : 0)) > room) rows--;
+    return rows;
+}
+
 /** The space a popover keeps from the Map's edges. */
 const POPOVER_GUTTER = 16;
 
@@ -117,52 +223,26 @@ export function fitPopover(
 }
 
 /*
- * 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 Map's error line (a failed jump, a level that wouldn't load), over the canvas: 24 px down, centred, and where
+ * that can't hold it in two lines, a solid card in the canvas's top-left corner. Over an inspector that covers the
+ * canvas it's the inspector'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). */
+/** The card's inset from the canvas's edges. */
+const CARD_INSET = 16;
+/** The line's distance from the canvas's top (top-6), and how tall it may grow before it becomes the card. */
 export const BANNER_TOP = 24;
-export const CARD_TOP = OVERLAY_INSET;
+const BANNER_BAND = 64;
 
 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.
+ * Which form the banner takes, by the height it has as a line (`null`: not measured yet, the normal case): the line
+ * while it ends inside the canvas's top 64 px (two lines), else the card.
  */
 export function bannerForm(bandHeight: number | null): BannerForm {
-    return bandHeight === null || BANNER_TOP + bandHeight <= TOP_INSET ? "band" : "card";
+    return bandHeight === null || BANNER_TOP + bandHeight <= BANNER_BAND ? "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);
-}
+/** How far the card keeps from the canvas's sides, together: its inset on the left and as much on the right. */
+export const CARD_CLEAR = 2 * CARD_INSET;

package/app/map/opening.ts

@@ -0,0 +1,16 @@
+import type { MapNode } from "@/lib/contracts";
+
+/** What opening a box does: a folder opens on the Map, a doorway turns to its page, a file opens in the editor. */
+export type BoxOpening = { type: "folder"; path: string } | { type: "page"; page: number } | { type: "editor"; path: string };
+
+/**
+ * What opening `box` does, by a double-click on it or the Open beside it in a narrow window (BoxActions); null when it
+ * has nothing to open. Inside VS Code's panel (`inEditor`) a click only selects a file, and opening it is how it reaches
+ * the editor (the owner, 2026-10-29, ADR-062 amended); a browser tab has no editor to open it in. The merged doorway
+ * stands for several pages, so it stays selected for its panel to pick one.
+ */
+export function openingOf(box: MapNode, inEditor: boolean): BoxOpening | null {
+    if (box.kind === "folder") return { type: "folder", path: box.path };
+    if (box.kind === "portal") return box.page === undefined ? null : { type: "page", page: box.page };
+    return inEditor ? { type: "editor", path: box.path } : null;
+}

package/app/map/portals.ts

@@ -29,11 +29,11 @@ export function portalTitle(box: Pick<MapNode, "page" | "pages">): string {
 }
 
 /**
- * Under a doorway's name: "44 folders and files · 6 imports" (the owner's wording; "boxes" read as jargon). Imports, as a
+ * Under a doorway's name: "44 folders and files, 6 imports" (the owner's wording; "boxes" read as jargon). Imports, as a
  * line's hover sentence counts them; "links" read as a count of lines (deferred minor, 2026-10-13).
  */
 export function portalCaption(box: Pick<MapNode, "hiddenCount">, imports: number): string {
-    return `${plural(box.hiddenCount ?? 0, "folder or file", "folders and files")} · ${plural(imports, "import", "imports")}`;
+    return `${plural(box.hiddenCount ?? 0, "folder or file", "folders and files")}, ${plural(imports, "import", "imports")}`;
 }
 
 /**