nebulosity 1.0.0 → 1.1.0

package/app/map/Explorer.tsx

@@ -0,0 +1,268 @@
+"use client";
+
+import { memo, useCallback, useEffect, useId, useMemo, useRef, useState, type MouseEvent, type ReactNode } from "react";
+import { IconFile, IconFolder, IconX } from "@tabler/icons-react";
+import type { LevelResponse } from "@/lib/contracts";
+import { explorerView, rowTone, type ExplorerRow, type ExplorerView, type RowTone } from "./explorerRows";
+import { formatCount } from "./format";
+import { useDismiss } from "./useDismiss";
+
+export type ExplorerProps = {
+    /** The level on screen: its folders, files and doorways, its lines, and which page of it this is. */
+    level: LevelResponse;
+    /** The selected box's path, or null. */
+    selected: string | null;
+    /** The paths joined to the selection by a drawn line. */
+    linked: ReadonlySet<string>;
+    /** full is the 236 px list. rail is a 40 px column whose one button opens the list over the canvas. */
+    form: "full" | "rail";
+    /** A click on a row selects that box on the Map. */
+    onSelect: (path: string) => void;
+    /** A double click on a folder's row goes into it. */
+    onOpen: (folder: string) => void;
+};
+
+/**
+ * How long the rail's list stays open after a click on a row. The second click of a double click has to find the row
+ * still there: closed at once, it would land on the canvas underneath and let go of the selection (the pane's click), or
+ * open whatever box sits under the pointer.
+ */
+const DOUBLE_CLICK_WAIT = 350;   // ms
+
+const ROW_TONE: Record<RowTone, string> = {
+    selected: "bg-row-sel text-text",
+    linked: "text-text hover:bg-node",
+    plain: "text-text-2 hover:bg-node",
+};
+const BAR_TONE: Record<RowTone, string> = { selected: "bg-accent", linked: "bg-linked-glyph", plain: "bg-glyph-dim" };
+
+const rowOf = (list: HTMLElement, path: string): HTMLElement | null => list.querySelector<HTMLElement>(`[data-explorer-row="${CSS.escape(path)}"]`);
+
+/**
+ * Scrolls the list just far enough to show the selected row, the way VS Code's explorer follows the editor: a box
+ * selected on the Map may sit far down a long list. Only the list moves. scrollIntoView would scroll every ancestor
+ * that can, the page among them, and the page must never scroll.
+ */
+function reveal(list: HTMLElement | null, path: string | null): void {
+    const row = list !== null && path !== null ? rowOf(list, path) : null;
+    if (list === null || row === null) return;
+    const top = row.offsetTop;
+    const bottom = top + row.offsetHeight;
+    if (top < list.scrollTop) list.scrollTop = top;
+    else if (bottom > list.scrollTop + list.clientHeight) list.scrollTop = bottom - list.clientHeight;
+}
+
+/** "Explorer" and how many items, over the list. The rail's list adds its close button at the end. */
+function Header({ count, tall, children }: { count: string; tall?: boolean; children?: ReactNode }){
+    return (
+        <div className={`flex shrink-0 items-center justify-between gap-2 pl-[14px] text-[11.5px] text-text-3 ${tall ? "h-10 pr-2" : "h-[34px] pr-[14px]"}`}>
+            <span className="truncate">Explorer</span>
+            <span className="flex shrink-0 items-center gap-1.5 whitespace-nowrap">{count}{children}</span>
+        </div>
+    );
+}
+
+/**
+ * One row, a real button: the icon, the name in mono, and for a folder its bar and how many files it holds. The whole
+ * path is its title, since a long name is cut short with an ellipsis. The focus ring is drawn inside, where the list's
+ * edges can't clip it.
+ */
+function Row({ row, tone, onPick, onOpen }: {
+    row: ExplorerRow;
+    tone: RowTone;
+    onPick: (path: string, event: MouseEvent<HTMLButtonElement>) => void;
+    onOpen: (folder: string) => void;
+}){
+    const folder = row.kind === "folder";
+    const Icon = folder ? IconFolder : IconFile;
+    return (
+        <li>
+            <button
+                type="button"
+                data-explorer-row={row.path}
+                aria-current={tone === "selected" ? "true" : undefined}
+                aria-label={folder ? row.label : undefined}
+                title={row.path}
+                onClick={(event) => onPick(row.path, event)}
+                onDoubleClick={folder ? () => onOpen(row.path) : undefined}
+                className={`grid h-[26px] w-full grid-cols-[16px_minmax(0,1fr)_36px_minmax(44px,max-content)] items-center gap-2 pl-[14px] pr-3 text-left focus-visible:-outline-offset-2 ${ROW_TONE[tone]}`}
+            >
+                <Icon aria-hidden size={14} stroke={1.75} className="text-text-3" />
+                <span className={`truncate font-mono text-[12.5px] ${folder ? "" : "col-span-3"}`}>{row.name}</span>
+                {folder && (
+                    <>
+                        <span aria-hidden className={`h-[3px] rounded-[2px] ${BAR_TONE[tone]}`} style={{ width: row.bar }} />
+                        <span className="whitespace-nowrap text-right text-[11.5px] tabular-nums text-text-3">{formatCount(row.files)}</span>
+                    </>
+                )}
+            </button>
+        </li>
+    );
+}
+
+type RowsProps = {
+    view: ExplorerView;
+    selected: string | null;
+    linked: ReadonlySet<string>;
+    onPick: (path: string, event: MouseEvent<HTMLButtonElement>) => void;
+    onOpen: (folder: string) => void;
+};
+
+/**
+ * The rows, scrolling inside when there are more than fit, and under them, for a folder drawn a page at a time, which
+ * page this is. It keeps the selected row in view as the selection changes.
+ */
+function Rows({ view, selected, linked, onPick, onOpen }: RowsProps){
+    const list = useRef<HTMLDivElement>(null);
+    useEffect(() => reveal(list.current, selected), [selected, view]);
+
+    return (
+        <div ref={list} className="relative min-h-0 flex-1 overflow-y-auto pb-[10px]">
+            <ul aria-label="Folders and files">
+                {view.rows.map((row) => <Row key={row.path} row={row} tone={rowTone(row.path, selected, linked)} onPick={onPick} onOpen={onOpen} />)}
+            </ul>
+            {view.pageLine !== null && <p className="px-[14px] pt-2 text-[11.5px] leading-4 text-text-3">{view.pageLine}</p>}
+        </div>
+    );
+}
+
+/**
+ * The list over the canvas, from the rail's right edge. It's a dialog, so the Map's own keys (Escape, Backspace, the
+ * arrows) wait while it's open (MapView asks the page whether one is). The focus goes to the selected row, or the first,
+ * so the keyboard can carry on from the button that opened it.
+ */
+function Overlay({ id, view, selected, linked, onPick, onOpen, onClose }: RowsProps & { id: string; onClose: () => void }){
+    const self = useRef<HTMLDivElement>(null);
+    useEffect(() => {
+        const dialog = self.current;
+        const row = dialog?.querySelector<HTMLElement>('[aria-current="true"]') ?? dialog?.querySelector<HTMLElement>("[data-explorer-row]");
+        // the list has already scrolled to the selection (Rows), so the focus mustn't scroll anything again
+        row?.focus({ preventScroll: true });
+    }, []);
+
+    return (
+        <div
+            ref={self}
+            id={id}
+            role="dialog"
+            aria-label="Explorer"
+            className="absolute bottom-0 left-full top-0 z-20 flex w-[236px] max-w-[calc(100vw_-_48px)] flex-col border-r border-divider bg-panel"
+        >
+            <Header count={view.count} tall>
+                <button type="button" onClick={onClose} aria-label="Close the explorer" className="grid h-6 w-6 place-items-center rounded-md text-text-2 hover:bg-node hover:text-text">
+                    <IconX aria-hidden size={16} stroke={1.75} />
+                </button>
+            </Header>
+            <Rows view={view} selected={selected} linked={linked} onPick={onPick} onOpen={onOpen} />
+        </div>
+    );
+}
+
+/**
+ * The explorer as a 40 px rail, for a window too narrow to keep the whole list beside the canvas: one button that opens
+ * the list over the canvas. Escape, the ×, a click outside or the focus moving away closes it. A click on a row selects
+ * that box and closes it a moment later, so a double click still opens a folder (DOUBLE_CLICK_WAIT). The keyboard's
+ * Enter has no second click to wait for, so it closes at once.
+ */
+function Rail({ view, selected, linked, onSelect, onOpen }: Omit<RowsProps, "onPick" | "onOpen"> & Pick<ExplorerProps, "onSelect" | "onOpen">){
+    const [open, setOpen] = useState(false);
+    // bumped by each click on a row: the list closes DOUBLE_CLICK_WAIT after the last
+    const [picks, setPicks] = useState(0);
+    const id = useId();
+    const button = useRef<HTMLButtonElement>(null);
+
+    /** Closes the list without moving the focus: a click outside, or the focus already gone elsewhere. */
+    const dismiss = useCallback((): void => {
+        setOpen(false);
+        setPicks(0);
+    }, []);
+    const root = useDismiss<HTMLElement>(open, dismiss);
+    /** Closes the list, the focus going back to the rail's button when it was in the list, rather than to the page. */
+    const close = useCallback((): void => {
+        if (root.current?.contains(document.activeElement)) button.current?.focus();
+        dismiss();
+    }, [dismiss, root]);
+
+    useEffect(() => {
+        if (picks === 0) return;
+        const timer = setTimeout(close, DOUBLE_CLICK_WAIT);
+        return () => clearTimeout(timer);
+    }, [picks, close]);
+
+    // Escape closes just the list. Caught first, on the way down, and stopped there, so it doesn't also reach the Map's
+    // Escape, which would let go of the selection the moment the list is gone
+    useEffect(() => {
+        if (!open) return;
+        const onKey = (event: KeyboardEvent): void => {
+            if (event.key !== "Escape") return;
+            event.stopPropagation();
+            close();
+        };
+        window.addEventListener("keydown", onKey, true);
+        return () => window.removeEventListener("keydown", onKey, true);
+    }, [open, close]);
+
+    const pick = (path: string, event: MouseEvent<HTMLButtonElement>): void => {
+        onSelect(path);
+        // a click's detail counts its clicks, and Enter or Space on the row gives 0
+        if (event.detail === 0) close();
+        else setPicks((n) => n + 1);
+    };
+    const openFolder = (folder: string): void => {
+        onOpen(folder);
+        close();
+    };
+
+    return (
+        <aside
+            ref={root}
+            aria-label="Explorer"
+            onBlur={(event) => {
+                // the focus left for something outside (Tab past the last row, the search box opening): close behind it
+                if (open && event.relatedTarget instanceof Node && !event.currentTarget.contains(event.relatedTarget)) dismiss();
+            }}
+            className="relative flex h-full w-full flex-col items-center border-r border-divider bg-panel pt-1.5"
+        >
+            <button
+                ref={button}
+                type="button"
+                aria-label="Open the explorer"
+                title="Explorer"
+                aria-expanded={open}
+                aria-controls={open ? id : undefined}
+                onClick={() => (open ? close() : setOpen(true))}
+                className={`grid h-7 w-7 shrink-0 place-items-center rounded-[5px] ${open ? "bg-node text-text" : "text-text-2 hover:bg-node hover:text-text"}`}
+            >
+                <IconFolder aria-hidden size={18} stroke={1.75} />
+            </button>
+            {open && (
+                <Overlay id={id} view={view} selected={selected} linked={linked} onPick={pick} onOpen={openFolder} onClose={close} />
+            )}
+        </aside>
+    );
+}
+
+/**
+ * The explorer (the Workbench redesign, ADR-070): the boxes of the level on screen as a list beside the canvas, the
+ * browser's answer to VS Code's own side bar, which the panel inside VS Code has instead. Folders come first, the
+ * largest at the top, each with a bar on the same log scale as its dot and how many files it holds, then the files by
+ * name. Doorways to other pages aren't rows, and a folder drawn a page at a time says which page under the list. The rows
+ * follow the Map: the selection's row is filled, and what's joined to it by a line is brighter with a lilac bar. A click
+ * selects that box on the Map, and a double click on a folder goes into it. In a narrower window it's a 40 px rail
+ * whose button opens the same list over the canvas. It fills its parent's height, scrolling inside, and the parent sets
+ * its width.
+ */
+function Explorer({ level, selected, linked, form, onSelect, onOpen }: ExplorerProps){
+    const view = useMemo(() => explorerView(level), [level]);
+
+    if (form === "rail") return <Rail view={view} selected={selected} linked={linked} onSelect={onSelect} onOpen={onOpen} />;
+    return (
+        <aside aria-label="Explorer" className="flex h-full min-h-0 w-full min-w-0 flex-col overflow-hidden border-r border-divider bg-panel">
+            <Header count={view.count} />
+            <Rows view={view} selected={selected} linked={linked} onPick={(path) => onSelect(path)} onOpen={onOpen} />
+        </aside>
+    );
+}
+
+// memo: the list draws again only when its own props change, not with everything else MapView redraws
+export default memo(Explorer);

package/app/map/Header.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { useSyncExternalStore, type ReactNode } from "react";
+import Image from "next/image";
+import { IconSearch } from "@tabler/icons-react";
+import BackButton from "./BackButton";
+import { DEMO } from "./mode";
+
+type HeaderProps = {
+    /** The breadcrumb, with the repo's name and picker first (Breadcrumb, RepoMenu). */
+    crumb: ReactNode;
+    onSearch: () => void;
+    onHelp: () => void;
+    /** Inside VS Code's panel: no logo and no help button (the ? key still opens it). */
+    embedded: boolean;
+    /** Whether Back has one of the Map's own steps to go back to (history.ts's historyDepth). */
+    canGoBack: boolean;
+    /** A short window's toolbar, folded into this bar (shell.ts). */
+    toolbar?: ReactNode;
+    /** A very short window's status dots, at the bar's end (shell.ts). */
+    status?: ReactNode;
+};
+
+const noSubscription = () => () => {};
+
+/**
+ * The search field's icon form: under 640 px, or under 1000 where the toolbar's controls share the bar (and gone under
+ * 360). As a field it gives way before the breadcrumb does (flex-shrink 1000 to its 1), down to 160 px.
+ */
+const SEARCH_ICON = {
+    alone: { field: "max-[640px]:min-w-0 max-[640px]:w-7 max-[640px]:flex-none max-[640px]:cursor-pointer max-[640px]:justify-center max-[640px]:p-0", words: "max-[640px]:hidden" },
+    shared: { field: "max-[1000px]:min-w-0 max-[1000px]:w-7 max-[1000px]:flex-none max-[1000px]:cursor-pointer max-[1000px]:justify-center max-[1000px]:p-0 max-[360px]:hidden", words: "max-[1000px]:hidden" },
+};
+
+/**
+ * The Map's one top bar (the Workbench redesign, ADR-070), 42 px, 38 inside VS Code's panel. Left to right: the logo
+ * and name, Back, the breadcrumb in mono with the repo first, the search field, and help. In the demo the logo goes to
+ * nebulosity.ca (the owner, 2026-10-27). Inside VS Code's panel it's Back, the breadcrumb and search, since VS Code has
+ * its own chrome. Back is the same button in the browser, the demo and the panel, right before the breadcrumb it
+ * changes, and greyed out where none of the Map's own steps lie behind it (the owner's pick, 2026-10-29).
+ *
+ * A narrower window drops secondary parts one step at a time, so nothing sits on anything else and nothing scrolls
+ * sideways: under 1000 px the search's shortcut, under 900 the Nebulosity name (the mark stays), under 640 the search's
+ * words (the field becomes its icon), and under 480 the help button (the toolbar's … menu has it). Under 360 the mark
+ * and its divider go too, and the bar's gaps and Back's box narrow (24 px, 4 px from the breadcrumb), so the folder on
+ * screen keeps a readable name at 200 × 200 with the toolbar and the status dots in this bar. Back never goes, so under
+ * 360 the browser's bar is the panel's. The breadcrumb takes what's left and folds its middle (under 360 the repo's
+ * name with it). In a short window the toolbar's controls and then the status dots join this bar, which then has less
+ * to give: the search is its icon under 1000 px, and under 360 it moves into the toolbar's … menu (Ctrl K still opens
+ * it).
+ */
+export default function Header({ crumb, onSearch, onHelp, embedded, canGoBack, toolbar, status }: HeaderProps){
+    // the server renders "Ctrl K"; a Mac shows "⌘K" once hydrated, without a mismatch
+    const isMac = useSyncExternalStore(noSubscription, () => /Mac|iPhone|iPad/.test(navigator.platform), () => false);
+    const icon = toolbar ? SEARCH_ICON.shared : SEARCH_ICON.alone;
+    const brand = (
+        <>
+            <Image src="/icon.svg" alt="" width={18} height={18} unoptimized className="shrink-0" />
+            <span className="text-[13px] font-semibold text-text max-[900px]:hidden">Nebulosity</span>
+        </>
+    );
+    return (
+        <header className={`relative z-20 flex shrink-0 items-center gap-3 border-b border-divider bg-panel pl-3 pr-2.5 max-[360px]:gap-1.5 max-[360px]:pl-2 max-[360px]:pr-1.5 ${embedded ? "h-[38px]" : "h-[42px]"}`}>
+            {/* at its natural width, so a long breadcrumb takes room from the search field before it truncates */}
+            <div className="flex min-w-0 flex-[1_1_auto] items-center gap-2.5 max-[360px]:gap-1">
+                {!embedded && (DEMO
+                    ? <a href="https://nebulosity.ca" title="nebulosity.ca" className="flex shrink-0 items-center gap-2 rounded-[4px] max-[360px]:hidden">{brand}</a>
+                    : <span className="flex shrink-0 items-center gap-2 max-[360px]:hidden">{brand}</span>)}
+                {!embedded && <span aria-hidden className="h-4 w-px shrink-0 bg-divider max-[360px]:hidden" />}
+                <BackButton enabled={canGoBack} />
+                {crumb}
+            </div>
+            <button
+                type="button"
+                onClick={onSearch}
+                data-testid="search-button"
+                aria-label="Search files and concepts"
+                title={`Search files and concepts (${isMac ? "⌘K" : "Ctrl K"})`}
+                className={`flex h-7 min-w-[160px] flex-[0_1000_440px] cursor-text items-center gap-2 rounded-[5px] border border-border bg-canvas pl-2.5 pr-1.5 text-[13px] text-text-3 hover:border-text-3 ${icon.field}`}
+            >
+                <IconSearch aria-hidden size={14} stroke={2} className="shrink-0" />
+                <span className={`w-0 flex-1 truncate text-left ${icon.words}`}>Search files and concepts</span>
+                <kbd className="shrink-0 rounded-[4px] border border-border px-1.5 font-sans text-[11.5px] leading-[17px] text-text-3 max-[1000px]:hidden">{isMac ? "⌘K" : "Ctrl K"}</kbd>
+            </button>
+            {/* as wide as the left side while the search field is centred, and only its own width once it's an icon; never
+                narrower than what it holds, which would spill left over the search field (its end is aligned) */}
+            <div className={`flex items-center justify-end gap-1.5 ${toolbar ? "shrink-0" : "flex-1 max-[640px]:flex-none"}`}>
+                {toolbar}
+                {!embedded && (
+                    <button
+                        type="button"
+                        onClick={onHelp}
+                        data-testid="help-button"
+                        aria-label="How to use the Map"
+                        title="How to use the Map (?)"
+                        className="grid h-7 w-7 shrink-0 place-items-center rounded-[5px] border border-border text-[13px] font-semibold text-text-2 hover:border-text-3 hover:text-text max-[480px]:hidden"
+                    >
+                        ?
+                    </button>
+                )}
+                {status}
+            </div>
+        </header>
+    );
+}

package/app/map/HelpDialog.tsx

@@ -7,11 +7,13 @@ import { DEMO } from "./mode";
 import { useScrollLock } from "./useScrollLock";
 
 /**
- * How to use the Map (owner review: "it's kinda confusing at first as to what all of this does"). Opens from the top
- * bar's "?" button or the ? key, and by itself on a first visit. Rendered into the page's body, above everything;
- * Escape or a click outside closes it. In the static demo it opens with what the demo can't do (ADR-049).
+ * How to use the Map (owner review: "it's kinda confusing at first as to what all of this does"). Opens from the
+ * header's "?" button, the toolbar's … menu where there's no room for it, or the ? key. It no longer opens by itself on
+ * a first visit, since the legend sentence under the canvas says what the marks mean (ADR-070). Rendered into the
+ * page's body, above everything; Escape or a click outside closes it. In the static demo it opens with what the demo
+ * can't do (ADR-049). Inside VS Code's panel (`embedded`) it says how a file opens in the editor.
  */
-export default function HelpDialog({ onClose }: { onClose: () => void }){
+export default function HelpDialog({ onClose, embedded = false }: { onClose: () => void; embedded?: boolean }){
     useScrollLock();
     useEffect(() => {
         const onKey = (event: KeyboardEvent): void => {
@@ -50,59 +52,60 @@ export default function HelpDialog({ onClose }: { onClose: () => void }){
                             at the top right, or the ? key.
                         </p>
                     </div>
-                    <button type="button" onClick={onClose} aria-label="Close help" className="shrink-0 rounded-md p-1 text-text-2 hover:bg-surface hover:text-text">
+                    <button type="button" onClick={onClose} aria-label="Close help" className="shrink-0 rounded-md p-1 text-text-2 hover:bg-node hover:text-text">
                         <IconX aria-hidden size={16} stroke={1.75} />
                     </button>
                 </div>
 
                 <div className="mt-6 grid gap-x-8 gap-y-6 text-[14px] leading-normal text-text sm:grid-cols-2">
                     <Section title="Getting around">
-                        <li><b>Click</b> a box to see what it is, in the panel on the right.</li>
-                        <li><b>Double-click</b> a folder to go inside it.</li>
-                        <li>Go back up with the path at the top left, <Key>Backspace</Key>, or your browser&apos;s Back button. The repo&apos;s name at the very top goes back to the start.</li>
-                        <li>Big folders are split into pages of related boxes: turn the page with the arrows at the top right, or <Key>←</Key> <Key>→</Key>.</li>
-                        <li>A busy folder opens at a readable size, from its top: drag to see the rest, or press the fit button at the bottom right to see it all.</li>
+                        <li><b>Click</b> a box to see what it is, in the inspector beside or under the Map.</li>
+                        <li><b>Double-click</b> a folder to go inside it, or click a folder in the explorer on the left.</li>
+                        {/* a click only selects a file in the panel too (the owner, 2026-10-29) */}
+                        {embedded && <li>In VS Code, <b>double-click</b> a file to open it in the editor, or press <b>Open in VS Code</b> in the inspector.</li>}
+                        <li>Go back up with the path at the top left, <Key>Backspace</Key>, or your browser&apos;s Back button. The repo&apos;s name at its start goes back to the top.</li>
+                        <li>Big folders are split into pages of related boxes. Turn the page with the arrows in the toolbar, or <Key>←</Key> <Key>→</Key>.</li>
+                        <li>A busy folder opens at a readable size, from its top. Drag to see the rest, or press <b>Fit</b> in the toolbar to see it all.</li>
                         <li>Search files and concepts with <Key>Ctrl K</Key> (<Key>⌘K</Key> on a Mac).</li>
                     </Section>
                     <Section title="Reading the Map">
-                        <li>A box is a folder (with how many files it holds) or a file.</li>
-                        <li>A line from A to B means A uses code from B: the arrow points at what&apos;s being used. A box&apos;s panel lists both sides: <b>Depends on</b> (what it uses) and <b>Used by</b> (what uses it).</li>
-                        <li>Hover a box to see its summary and preview its lines. Hover a line to read it as a sentence, like &quot;editor uses base · 12 imports&quot;.</li>
-                        <li>Busy folders (more than 60 lines) draw only the lines of the box you hover or select. <b>Show all lines</b>, at the top right, brings back the rest.</li>
-                        <li>Boxes with no lines on the page sit under a line that says &quot;Not linked to anything on this page&quot;.</li>
-                        <li>Lines to other pages end at a doorway, a dashed box like &quot;Lines to page 2&quot;; double-click it to go there.</li>
+                        <li>A box is a folder or a file. A folder&apos;s dot grows with how many files it holds, and it has a second card behind it. A file has a page.</li>
+                        <li>A line from A to B means A uses code from B, and the arrow points at what&apos;s being used. Its weight, and the number on it, show how many imports it carries.</li>
+                        <li>Hover a box to bring its lines forward. Hover a line to read it as a sentence, like &quot;editor uses base, 12 imports&quot;. Where lines join, it lists every line on that stretch, and a click keeps the list open until you press Escape or click elsewhere.</li>
+                        <li><b>Strong links only</b>, in the toolbar, hides the lines under 2% of the heaviest line&apos;s imports. Every line of the box you select or hover still shows.</li>
+                        <li>With a box selected, <b>Uses</b> or <b>Used by</b> in the toolbar keeps only its lines to what it uses, or from what uses it, in color, and turns its other lines gray. <b>All</b> colors both, and it&apos;s back to All when you select something else.</li>
+                        <li>Busy folders (more than 60 lines) draw only the lines of the box you hover or select, until you ask for <b>Show all lines</b>.</li>
+                        <li>Boxes with no lines on the page sit under a line that says &quot;Not linked to anything here&quot;. Lines to other pages end at a doorway, a dashed box like &quot;Lines to page 2&quot;, and double-clicking it goes there.</li>
                     </Section>
                     <Section title="Colors">
-                        <li><Swatch className="border-2 border-select bg-select-fill" /> Purple: the box you selected and its lines. Everything else fades.</li>
-                        <li><Swatch className="outline-2 outline-offset-1 outline-agent" /> Orange: what Claude Code is touching right now.</li>
-                        <li><Swatch className="rounded-full bg-control" /> Cyan: something you can click, like a link or the Map&apos;s buttons.</li>
-                        <li><Swatch className="rounded-full bg-ok" /> Green: the index is up to date.</li>
-                        <li><Swatch className="rounded-full bg-danger" /> Red: something failed.</li>
+                        <li><Swatch className="border-2 border-accent bg-node-sel" /> Purple is the box you selected, the lines to what it uses, and what they join. <span className="whitespace-nowrap"><Swatch className="bg-used-by-edge" /> Gold</span> is the lines from what uses it. Everything else fades.</li>
+                        <li><Swatch className="outline-2 outline-offset-1 outline-agent" /> Orange is what Claude Code is touching right now.</li>
+                        <li><Swatch className="rounded-full bg-ok" /> The cyan dot at the bottom left says the index is up to date.</li>
+                        <li><Swatch className="rounded-full bg-danger" /> Red means something failed.</li>
                     </Section>
-                    <Section title="The details panel">
-                        <li>A short summary; <b>Read full summary</b> shows the rest.</li>
-                        <li><b>Depends on</b> and <b>Used by</b>: click one to jump to it on the Map.</li>
-                        <li><b>Contents</b>: click a folder to go in, or a file to select it.</li>
+                    <Section title="The inspector">
+                        <li>A short summary, and <b>Full summary</b> for the rest.</li>
+                        <li><b>Uses</b>, <b>Used by</b> and <b>Contents</b> are tabs. Click a row to jump to it on the Map.</li>
                         {DEMO
-                            ? <li>For a file, <b>View on GitHub</b> opens its code at the indexed commit; click a declaration to open it there.</li>
-                            : <li>For a file, <b>View source</b> shows its code; click a declaration to jump to it there.</li>}
+                            ? <li>For a file, <b>View on GitHub</b> opens its code at the indexed commit, and a declaration opens there too.</li>
+                            : <li>For a file, <b>View source</b> shows its code, and a declaration jumps to its line there.</li>}
                     </Section>
                     <Section title="Claude Code">
                         {DEMO
-                            ? <li>In the app, the bar along the bottom shows Claude Code&apos;s last 3 tool calls, and the boxes they touched get an orange ring.</li>
+                            ? <li>In the app, the status bar along the bottom shows Claude Code&apos;s newest tool call as it works, and the boxes it touched get an orange ring.</li>
                             : (
                                 <>
-                                    <li>The bar along the bottom shows Claude Code&apos;s last 3 tool calls, newest first.</li>
+                                    <li>The status bar along the bottom shows Claude Code&apos;s newest tool call as it works.</li>
                                     <li>Boxes holding what it touched get an orange ring for 30 seconds.</li>
                                 </>
                             )}
                     </Section>
                     <Section title="The index">
-                        <li>The status at the top right says whether the index is up to date. Click it for each stage{DEMO ? "." : ", and to re-index."}</li>
+                        <li>The status bar&apos;s first cell says whether the index is up to date. Click it for each stage{DEMO ? "." : ", and to re-index."}</li>
                     </Section>
                 </div>
 
-                <h3 className="mt-6 text-[13px] font-medium text-title">Keyboard</h3>
+                <h3 className="mt-6 text-[13px] font-medium text-text">Keyboard</h3>
                 <dl className="mt-2 grid grid-cols-[max-content_1fr] gap-x-4 gap-y-1 text-[13px] text-text-2 max-[360px]:grid-cols-1 max-[360px]:[&_dd]:mb-1.5">
                     <dt><Key>Ctrl K</Key></dt><dd>Search files and concepts</dd>
                     <dt><Key>Esc</Key></dt><dd>Close what&apos;s open, let go of the selection, then clear Claude Code&apos;s highlights</dd>
@@ -119,14 +122,14 @@ export default function HelpDialog({ onClose }: { onClose: () => void }){
 function Section({ title, children }: { title: string; children: ReactNode }){
     return (
         <section>
-            <h3 className="text-[13px] font-medium text-title">{title}</h3>
-            <ul className="mt-2 space-y-1.5 text-text-body [&_b]:font-medium [&_b]:text-text">{children}</ul>
+            <h3 className="text-[13px] font-medium text-text">{title}</h3>
+            <ul className="mt-2 space-y-1.5 text-text-2 [&_b]:font-medium [&_b]:text-text">{children}</ul>
         </section>
     );
 }
 
 function Key({ children }: { children: ReactNode }){
-    return <kbd className="rounded-md border border-border bg-surface px-1.5 py-px font-sans text-[12px] text-text">{children}</kbd>;
+    return <kbd className="rounded-md border border-border bg-node px-1.5 py-px font-sans text-[12px] text-text">{children}</kbd>;
 }
 
 function Swatch({ className }: { className: string }){

package/app/map/Legend.tsx

@@ -1,82 +1,26 @@
 "use client";
 
-import { useState, type ReactNode } from "react";
-import { IconChevronDown, IconChevronUp } from "@tabler/icons-react";
-
-/** Remembers in this browser whether the legend was left open. */
-const LEGEND_OPEN = "nebulosity.legendOpen";
-
-function readOpen(): boolean {
-    try{
-        return window.localStorage.getItem(LEGEND_OPEN) === "1";
-    } catch{
-        return false;   // no storage (a private window): start closed
-    }
-}
-
 /**
- * What the lines and colors mean (VISUAL_REFRESH.md §4: "label the relationship"), said once in a corner instead of on
- * every line. Closed, it's a small "Legend" button; open, a narrow card of short rows (owner review, 2026-10-13: the wide
- * block ran into the boxes). Like the other overlays it's a solid card in the logo's violet with no outline: lines are
- * never filled, so it can't be mistaken for one (a light outline was), and no box is that colour. Its button is cyan, the
- * color of everything you click.
- * The canvas only renders in the browser, so reading storage on the first render is safe. On a short canvas (a narrow
- * window's floor), it's at most `maxHeight` tall, its rows scrolling inside, so it never reaches the page pill.
+ * What the Map's marks mean, in a sentence under the canvas (the Workbench redesign, ADR-070). It replaces both the
+ * legend card in the canvas's corner and the help that opened by itself on a first visit: the full help stays behind
+ * the ? button and key. The doorways, Claude Code's rings and a busy folder's hidden lines get a sentence of their own
+ * only where they appear. In a short window or over a narrow canvas it goes (shell.ts), the help still having it.
  */
-export default function Legend({ quietLines, doorways, maxHeight }: { quietLines: boolean; doorways: boolean; maxHeight?: number }){
-    const [open, setOpen] = useState(readOpen);
-    const toggle = (): void => {
-        const next = !open;
-        setOpen(next);
-        try{
-            window.localStorage.setItem(LEGEND_OPEN, next ? "1" : "0");
-        } catch{
-            // nothing to remember it in
-        }
-    };
-    const Chevron = open ? IconChevronDown : IconChevronUp;
-
-    return (
-        <div aria-label="Legend" style={{ maxHeight }} className={`nopan nodrag nowheel absolute bottom-4 left-4 z-[5] flex flex-col ${open ? "w-[252px]" : ""} rounded-lg bg-overlay text-[12px] text-overlay-text-2`}>
-            {open && (
-                <div className="min-h-0 space-y-1.5 overflow-y-auto border-b border-overlay-line px-3 py-2">
-                    {/* one sentence for direction: "arrows out / arrows in" rows read as abstract, even to the owner */}
-                    <Row glyph={<Arrow color="var(--text-2)" />}>A → B: A uses B. The arrow points at what&apos;s being used.</Row>
-                    <Row glyph={<Arrow color="var(--select)" />}>Selected box and its lines</Row>
-                    <Row glyph={<span className="block h-3 w-3 rounded-sm outline-2 outline-agent" />}>What Claude Code is touching</Row>
-                    {/* only where there are doorways: a page of a big folder (deferred minor: the legend had no row for them) */}
-                    {doorways && <Row glyph={<span className="block h-3 w-5 rounded-sm border border-dashed border-text-2" />}>Dashed box: a doorway to another page</Row>}
-                    {quietLines && <Row glyph={<span aria-hidden className="text-[14px] leading-none">⋯</span>}>Busy folder: hover a box to see its lines</Row>}
-                </div>
-            )}
-            <button
-                type="button"
-                data-testid="legend-toggle"
-                onClick={toggle}
-                aria-expanded={open}
-                className="flex w-full shrink-0 items-center justify-between gap-3 rounded-lg px-3 py-1.5 text-[12px] font-medium text-control hover:bg-overlay-line"
-            >
-                Legend
-                <Chevron aria-hidden size={16} stroke={1.75} />
-            </button>
-        </div>
-    );
-}
-
-function Row({ glyph, children }: { glyph: ReactNode; children: ReactNode }){
-    return (
-        <div className="flex items-start gap-2">
-            <span aria-hidden className="flex h-4 w-6 shrink-0 items-center justify-center">{glyph}</span>
-            <span className="leading-4">{children}</span>
-        </div>
-    );
-}
-
-function Arrow({ color }: { color: string }){
+export default function Legend({ doorways, agent, quiet }: {
+    /** The level has doorways to its other pages. */
+    doorways: boolean;
+    /** Claude Code is touching boxes on screen. */
+    agent: boolean;
+    /** A busy level, whose lines show on hover. */
+    quiet: boolean;
+}){
     return (
-        <svg width="24" height="8" viewBox="0 0 24 8" style={{ color }}>
-            <line x1="0" y1="4" x2="18" y2="4" stroke="currentColor" strokeWidth="1.5" />
-            <path d="M17 0.5 L24 4 L17 7.5 Z" fill="currentColor" />
-        </svg>
+        <p data-testid="legend" className="shrink-0 border-t border-divider px-3.5 py-2.5 text-[12px] leading-[1.45] text-text-3">
+            Dot size shows how many files a folder has. Line weight, and the number on a line, show how many imports it carries. Arrows point at the code being used.
+            Folders are stacked cards, and a page marks a single file.
+            {doorways && " A dashed box is a doorway to another page of this folder."}
+            {agent && " An orange ring is what Claude Code is touching right now."}
+            {quiet && " In a busy folder, hover a box to see its lines."}
+        </p>
     );
 }