pi-weave 0.3.0 → 0.3.2

package/src/web/client/shell/StatusBar.tsx

@@ -1,12 +1,11 @@
 /**
  * The status bar (weave-workspace §1.2).
  *
- * Working directory, current selection, and data-as-of stamp. The
+ * Working directory and current selection. The
  * model is built by `statusBarModel`; this renders it.
  */
 
 import type { StatusBarModel } from "./shell.model";
-import { shortStamp } from "./shell.model";
 
 export function StatusBar({ model }: { model: StatusBarModel }) {
   return (
@@ -14,12 +13,9 @@ export function StatusBar({ model }: { model: StatusBarModel }) {
       <span class="weave-status-cwd" title={model.cwd}>
         {model.cwd}
       </span>
-      <span class="weave-status-sel" title="the §1.3 context bus — one signal, every column">
+      <span class="weave-status-sel" title="Current item">
         {model.selection}
       </span>
-      <span class="weave-status-stamp" title="data as of">
-        {shortStamp(model.stamp)}
-      </span>
     </footer>
   );
 }

package/src/web/client/shell/focus.model.ts

@@ -3,8 +3,8 @@
  *
  * P4's exit criterion is "the whole workspace is drivable without a mouse",
  * and a dialog that does not trap focus fails it in the most literal way
- * available: Tab from the last control lands on the header behind the
- * overlay, the user is now typing into a search box they cannot see, and
+ * available: Tab from the last control lands on the workspace behind the
+ * overlay, the user is now typing into a field they cannot see, and
  * `Esc` goes to whatever they landed on. So the palette and the help overlay
  * both trap, and both restore.
  *

package/src/web/client/shell/keys.model.ts

@@ -84,14 +84,16 @@ export interface KeyContext {
 export type ShellAction =
   | { readonly type: "openSearch" }
   | { readonly type: "openHelp" }
+  | { readonly type: "openSettings" }
   | { readonly type: "closeOverlay" }
   | { readonly type: "focusColumn"; readonly column: ColumnId }
   /** Focus the tree's filter box — `/`. */
   | { readonly type: "filterTree" }
   | { readonly type: "fitGraph" }
   | { readonly type: "clearSelection" }
-  /** `t` — cycle the colour theme: system → light → dark → system. */
-  | { readonly type: "cycleTheme" };
+  | { readonly type: "closeTab" }
+  /** `t` — switch between the selected light and dark themes. */
+  | { readonly type: "toggleTheme" };
 
 /**
  * The command-key letters, as data.
@@ -101,6 +103,7 @@ export type ShellAction =
  */
 export const COMMAND_KEYS: Readonly<Record<string, ShellAction>> = {
   k: { type: "openSearch" },
+  ",": { type: "openSettings" },
 };
 
 /**
@@ -112,16 +115,6 @@ export const COMMAND_KEYS: Readonly<Record<string, ShellAction>> = {
  */
 export const COLUMN_DIGITS: Readonly<Record<string, ColumnId>> = { "1": "tree", "2": "note", "3": "graph" };
 
-/**
- * The columns a breakpoint can put off screen — the graph at `"medium"`, the
- * tree too at `"narrow"`, never the note. The help sheet's derived rows use it
- * to stay honest about `⌘1`/`⌘3`: at 900 px the `⌘3` command is a documented
- * no-op, and a help line that hides that is the same lie the `disabled`
- * search button once was. Derived from `columnsAt`, not listed, so the caveat
- * cannot drift from the breakpoints the sheet is attached to.
- */
-const COLLAPSIBLE_COLUMNS: ReadonlySet<ColumnId> = new Set(["tree", "graph"]);
-
 /**
  * Whether a modifier combination counts as "the platform's command key".
  *
@@ -155,7 +148,7 @@ export const BARE_KEYS: Readonly<Record<string, ShellAction>> = {
   "/": { type: "filterTree" },
   g: { type: "fitGraph" },
   "?": { type: "openHelp" },
-  t: { type: "cycleTheme" },
+  t: { type: "toggleTheme" },
 };
 
 /**
@@ -168,6 +161,8 @@ export const BARE_KEYS: Readonly<Record<string, ShellAction>> = {
 export function shellKey(event: KeyDescriptor, ctx: KeyContext): ShellAction | null {
   if (ctx.overlay !== null) return event.key === "Escape" ? { type: "closeOverlay" } : null;
 
+  if (event.alt && !event.meta && !event.ctrl && !event.shift && event.key.toLowerCase() === "w") return { type: "closeTab" };
+
   if (isCommand(event)) {
     // Lower-cased because ⌘K with caps lock on reports `"K"`, and a shortcut
     // that stops working under caps lock is a bug report nobody can reproduce.
@@ -231,6 +226,8 @@ export interface KeyTarget {
  * use, for the same reason: there is no DOM test environment (§10).
  */
 export interface KeyboardEventLike {
+  readonly code?: string;
+  readonly defaultPrevented: boolean;
   readonly key: string;
   readonly ctrlKey: boolean;
   readonly metaKey: boolean;
@@ -243,7 +240,7 @@ export interface KeyboardEventLike {
 /** Reduce a platform event to a {@link KeyDescriptor}. */
 export function describeKey(event: KeyboardEventLike): KeyDescriptor {
   return {
-    key: event.key,
+    key: event.altKey && event.code === "KeyW" ? "w" : event.key,
     ctrl: event.ctrlKey,
     meta: event.metaKey,
     shift: event.shiftKey,
@@ -254,27 +251,15 @@ export function describeKey(event: KeyboardEventLike): KeyDescriptor {
 
 // --- where an action points ---------------------------------------------------------
 
-/**
- * `⌘1/2/3` → the element to focus in that column.
- *
- * Selectors rather than refs, and the reason is the breakpoint: below 1100 px
- * the graph column does not exist and below 800 px the tree does not either,
- * so a ref would be `null` for a column that is legitimately absent and the
- * shell would need a branch per column to cope. A `querySelector` that finds
- * nothing is already the same answer, expressed once.
- *
- * Each target is the column's *content*, not its `<section>`: focusing the
- * section would put the ring around the whole pane and leave the arrow keys
- * pointing at nothing.
- */
+/** Content focus targets; the shell opens hidden sidebars/tabs before focusing. */
 export const COLUMN_FOCUS_SELECTORS: Readonly<Record<ColumnId, string>> = {
-  tree: ".weave-col-tree .weave-rows",
-  note: ".weave-col-note .weave-note-body",
-  graph: ".weave-col-graph .weave-graph-canvas",
+  tree: ".weave-sidebar-notes .weave-rows",
+  note: ".weave-pane-active .weave-note-body",
+  graph: ".weave-graph-host .weave-graph-canvas",
 };
 
 /** `/` → the tree's filter box. */
-export const TREE_FILTER_SELECTOR = ".weave-col-tree .weave-filter";
+export const TREE_FILTER_SELECTOR = ".weave-sidebar-notes .weave-filter";
 
 /** The slice of an element {@link focusable} produces. */
 export interface Focusable {
@@ -336,8 +321,9 @@ export interface ShellEffects {
   fitGraph(): void;
   /** Write `null` to §1.3's `selectedId`. */
   clearSelection(): void;
-  /** `t` — advance the user's theme choice by one step in its cycle. */
-  cycleTheme(): void;
+  closeTab(): void;
+  /** `t` — switch between the user's selected light and dark themes. */
+  toggleTheme(): void;
 }
 
 /** Perform an action. Total over {@link ShellAction}. */
@@ -345,13 +331,14 @@ export function runShellAction(action: ShellAction, fx: ShellEffects): void {
   switch (action.type) {
     case "openSearch":
       return fx.setOverlay("search");
+    case "openSettings":
+      return fx.setOverlay("settings");
     case "openHelp":
       return fx.setOverlay("help");
     case "closeOverlay":
       return fx.setOverlay(null);
     case "focusColumn":
-      // The boolean is deliberately dropped: a column that is not on screen
-      // at this breakpoint is a miss with nothing to report to.
+      // The shell reveals the target before focusing it.
       return void fx.focusSelector(COLUMN_FOCUS_SELECTORS[action.column]);
     case "filterTree":
       return void fx.focusSelector(TREE_FILTER_SELECTOR);
@@ -359,8 +346,10 @@ export function runShellAction(action: ShellAction, fx: ShellEffects): void {
       return fx.fitGraph();
     case "clearSelection":
       return fx.clearSelection();
-    case "cycleTheme":
-      return fx.cycleTheme();
+    case "closeTab":
+      return fx.closeTab();
+    case "toggleTheme":
+      return fx.toggleTheme();
   }
 }
 
@@ -397,13 +386,15 @@ export function keyHelp(cmd: string): readonly KeyHelpGroup[] {
     {
       title: "Global",
       entries: [
+        { combo: "⌥W / Alt W", what: "Close the active tab" },
+        { combo: `${cmd},`, what: "Open settings" },
         { combo: `${cmd}K`, what: "Search notes and the repository" },
         ...Object.entries(COLUMN_DIGITS).map(([digit, column]) => ({
           combo: `${cmd}${digit}`,
-          what: `Focus the ${column} column${COLLAPSIBLE_COLUMNS.has(column) ? " (when on screen)" : ""}`,
+          what: column === "tree" ? "Open and focus the notes sidebar" : column === "graph" ? "Open and focus Graph view" : "Focus the note",
         })),
         { combo: "?", what: "This help" },
-        { combo: "t", what: "Cycle the colour theme (system / light / dark)" },
+        { combo: "t", what: "Switch between selected light and dark themes" },
         { combo: "Esc", what: "Clear the selection, or close an overlay" },
       ],
     },
@@ -418,6 +409,15 @@ export function keyHelp(cmd: string): readonly KeyHelpGroup[] {
         { combo: "Home / End", what: "First / last row" },
       ],
     },
+    {
+      title: "Tabs and panes",
+      entries: [
+        { combo: "Alt ← / →", what: "Reorder the focused tab" },
+        { combo: "← / → / Home / End", what: "Select a tab when the tab strip is focused" },
+        { combo: `${cmd}click`, what: "Open a note or search result in a new tab" },
+        { combo: "Pane options (···)", what: "Split right or down, move a tab, or close a pane" },
+      ],
+    },
     {
       title: "Graph",
       entries: [{ combo: "g", what: "Fit the whole graph" }],
@@ -427,6 +427,7 @@ export function keyHelp(cmd: string): readonly KeyHelpGroup[] {
       entries: [
         { combo: "↑ / ↓", what: "Move through results" },
         { combo: "↵", what: "Open the highlighted result" },
+        { combo: `${cmd}↵`, what: "Open the highlighted result in a new tab" },
         { combo: "Esc", what: "Close the palette" },
       ],
     },

package/src/web/client/shell/keys.ts

@@ -49,6 +49,7 @@ export interface KeyOptions {
  */
 export function watchKeys(host: KeyHost, opts: KeyOptions): () => void {
   const listener = (event: KeyboardEventLike): void => {
+    if (event.defaultPrevented) return;
     const action = shellKey(describeKey(event), opts.context());
     if (action === null) return;
     event.preventDefault();

package/src/web/client/shell/shell.model.ts

@@ -1,8 +1,8 @@
 /**
  * Everything the shell *decides*, as pure functions (weave-workspace §1.2).
  *
- * The header's status summary, the per-column empty-state copy and the status
- * bar's text all live here rather than inside the components that render them.
+ * The Recent list, per-column empty-state copy and footer status text live
+ * here rather than inside the components that render them.
  * That is not a stylistic
  * preference: §10 forbids adding a DOM test environment, so a conditional
  * inside a `.tsx` is a conditional that can never be covered, and §14 lists
@@ -14,67 +14,43 @@
  * types, no `node:*`, no `src/core`.
  */
 
-import type { GraphPayload, WireNodeKind, WireStalenessState } from "../../shared/wire";
-import { COLUMNS, type ColumnId } from "./layout.model";
-export { COLUMNS };
-export type { ColumnId };
+import type { GraphPayload, WireNodeKind } from "../../shared/wire";
+import { kindIcon } from "../tree/tree.model";
+import type { IconName } from "./icons.model";
+export const NOTE_DRAG_TYPE = "application/x-weave-note";
 
-// --- the header summary --------------------------------------------------------
-
-/**
- * The `vault:34 · repo:fresh · 127 nodes` readout from the §1.2 sketch.
- *
- * Kept as three fields rather than one pre-joined string so the component can
- * put a separator between them without this module owning a `·`, and so a
- * test asserts the numbers rather than a formatting decision.
- */
-export interface HeaderSummary {
-  /** Note nodes in the vault. */
-  readonly notes: number;
-  /** Repository index freshness, or `null` when the repo is unindexed. */
-  readonly repo: WireStalenessState | null;
-  /** Every node, of every kind. */
-  readonly nodes: number;
+/** Pane drops open only note IDs that still exist in this workspace. */
+export function noteDropId(graph: GraphPayload | null, id: string): string | null {
+  return id.startsWith("note:") && graph?.model.nodes.some((node) => node.id === id && node.kind === "note") ? id : null;
 }
 
-/** The summary before the first graph arrives. */
-export const EMPTY_SUMMARY: HeaderSummary = { notes: 0, repo: null, nodes: 0 };
+export type ColumnId = "tree" | "note" | "graph";
+export const COLUMNS: readonly ColumnId[] = ["tree", "note", "graph"];
 
-/**
- * Which node kinds count as "vault" for the header.
- *
- * Only `note`. The `vault` node itself is the container, and counting it
- * would make an empty vault read `vault:1` — a number that is technically
- * defensible and would still be read as "there is one note in there".
- */
-const VAULT_KINDS: readonly WireNodeKind[] = ["note"];
+/** Most recent selections in this window, independent of whether their tabs stay open. */
+export function recordVisit(previous: readonly string[], id: string | null): readonly string[] {
+  return id === null ? previous : [id, ...previous.filter((item) => item !== id)].slice(0, 100);
+}
 
-/** Derive the header counts from a payload. */
-export function summarize(payload: GraphPayload | null): HeaderSummary {
-  if (payload === null) return EMPTY_SUMMARY;
-  const nodes = payload.model.nodes;
-  return {
-    notes: nodes.filter((node) => VAULT_KINDS.includes(node.kind)).length,
-    repo: payload.model.staleness?.state ?? null,
-    nodes: nodes.length,
-  };
+/** A selected graph node opens only after its preview has already been shown. */
+export function graphClickOpensTab(previewId: string | null, id: string | null): id is string {
+  return id !== null && id === previewId;
 }
 
-/**
- * The repo segment's text.
- *
- * `"unindexed"` rather than `"missing"` for a null or `missing` staleness:
- * "missing" reads as an error, and a repository that has simply never been
- * scanned is the ordinary first-run state, not a fault. The word the user
- * needs is the one that implies an action they can take.
- */
-export function repoLabel(repo: WireStalenessState | null): string {
-  return repo === null || repo === "missing" ? "unindexed" : repo;
+export interface RecentEntry {
+  readonly id: string;
+  readonly label: string;
+  readonly icon: IconName;
+  readonly selected: boolean;
 }
 
-/** `vault:34 · repo:fresh · 127 nodes`, as the pieces to join. */
-export function summaryParts(summary: HeaderSummary): readonly string[] {
-  return [`vault:${summary.notes}`, `repo:${repoLabel(summary.repo)}`, `${summary.nodes} nodes`];
+/** Present a frozen visit order without changing it when selection moves. */
+export function recentEntries(ids: readonly string[], graph: GraphPayload | null, selectedId: string | null): RecentEntry[] {
+  return ids.map((id) => {
+    const node = graph?.model.nodes.find((entry) => entry.id === id);
+    const kind: WireNodeKind = node?.kind ?? (id.startsWith("vfolder:") ? "module" : id.startsWith("artifact:") ? "file" : "note");
+    return { id, label: node?.label ?? id.replace(/^[^:]+:/, ""), icon: kindIcon(kind), selected: id === selectedId };
+  });
 }
 
 // --- empty states ------------------------------------------------------------------
@@ -84,23 +60,6 @@ export interface EmptyStateCopy {
   readonly title: string;
 }
 
-const EMPTY_STATES: Readonly<Record<ColumnId, EmptyStateCopy>> = {
-  tree: {
-    title: "Tree",
-  },
-  note: {
-    title: "Note",
-  },
-  graph: {
-    title: "Graph",
-  },
-};
-
-/** The empty-state copy for a column. */
-export function emptyStateFor(column: ColumnId): EmptyStateCopy {
-  return EMPTY_STATES[column];
-}
-
 /** The context rail's heading and `aria-label`. */
 export const CONTEXT_EMPTY: EmptyStateCopy = {
   title: "Context",
@@ -120,8 +79,6 @@ export const CONTEXT_EMPTY: EmptyStateCopy = {
 export interface StatusBarModel {
   readonly cwd: string;
   readonly selection: string;
-  /** `null` before the first successful graph fetch. */
-  readonly stamp: string | null;
 }
 
 /** The `—` shown where a value is genuinely absent, not zero. */
@@ -131,49 +88,13 @@ export const NO_VALUE = "—";
 export function statusBarModel(
   cwd: string,
   selectedId: string | null,
-  stamp: string | null,
 ): StatusBarModel {
   return {
     cwd: cwd === "" ? NO_VALUE : cwd,
     selection: selectedId ?? "nothing selected",
-    stamp,
   };
 }
 
-/**
- * A `generatedAt` stamp, shortened for the status bar.
- *
- * Just the `HH:MM:SS`, because the date is almost always today and the whole
- * ISO string is 24 characters of mostly-constant noise in a bar that has
- * three other things to say. A stamp that does not look like an ISO timestamp
- * is passed through untouched rather than sliced blindly — the server derives
- * it from input timestamps and is free to change that derivation, and a
- * mangled substring would be a worse lie than the full value.
- */
-export function shortStamp(stamp: string | null): string {
-  if (stamp === null) return NO_VALUE;
-  const match = /T(\d{2}:\d{2}:\d{2})/.exec(stamp);
-  return match?.[1] ?? stamp;
-}
-
-// --- the refresh button ------------------------------------------------------------
-
-/**
- * The refresh control's glyph, as SVG path data.
- *
- * A drawn icon replaces the `⟳` text character for the same reason §P6.4
- * retires the tree's glyph soup: a text arrow is whatever the platform's
- * fallback font draws it as, while these two strokes are the brand's own
- * weight everywhere. Stored as pure data here — §10 — so `Header.tsx` stays
- * props-in/JSX-out and the shape is testable without a DOM. 24×24 viewBox,
- * stroked, `currentColor`: the header recolours it on hover like any other
- * glyph.
- */
-export const REFRESH_ICON_PATHS: readonly string[] = [
-  "M21 12a9 9 0 1 1-2.64-6.36",
-  "M21 3v6h-6",
-];
-
 /**
  * How often the shell re-renders on its own, in ms.
  *
@@ -189,29 +110,12 @@ export const TICK_MS = 60_000;
 
 // --- the search affordance ---------------------------------------------------------
 
-/**
- * The `⌘K` control.
- *
- * Rendered **disabled** through P1–P3, with a title saying search arrived in
- * P4 — a deliberate choice over omitting it: the keyboard hint taught the
- * shortcut that would exist, and a `disabled` control explaining itself is
- * honest in a way that a working-looking box that does nothing is not.
- *
- * P4 made it live, and it is now a *button* rather than an `<input>`. The
- * palette owns the only text field, so a second one in the header would be
- * two places to type a query into and one of them would be a lie — clicking
- * it opens the overlay and whatever was typed into the header box would be
- * discarded. A button that looks like a search field and opens the real one
- * is the affordance the §1.2 sketch actually describes.
- */
-export const SEARCH_PLACEHOLDER = "Search…";
-
 /** The shortcut hint. `⌘K` on Apple platforms, `Ctrl K` elsewhere. */
 export function searchShortcut(isApple: boolean): string {
   return isApple ? "⌘K" : "Ctrl K";
 }
 
-/** The `title=` on the live search button. Names the key that also opens it. */
+/** The search action's tooltip, including the key that also opens it. */
 export function searchHint(shortcut: string): string {
   return `Search notes and repository (${shortcut})`;
 }
@@ -227,7 +131,7 @@ export function searchHint(shortcut: string): string {
  * other. Making that unrepresentable costs nothing here and removes a whole
  * class of bug from the keyboard layer, which is the thing that opens them.
  */
-export type OverlayId = "search" | "help" | null;
+export type OverlayId = "search" | "help" | "settings" | null;
 
 /**
  * Whether a platform string looks like an Apple one.

package/src/web/client/shell/theme.model.ts

@@ -1,64 +1,18 @@
-/**
- * The theme *choice* — what the user picked, and what that makes the screen
- * do (weave-workspace §1.2).
- *
- * The stylesheet decides what the palettes are (`theme.ts`); this module
- * decides *which one is showing*. The two are separate for §10's reason: the
- * choice is state a user controls, so every decision about it has to be a
- * testable pure function, while the `.tsx` that applies the attribute is
- * three lines no test can reach.
- *
- * ## Why tri-state
- *
- * "Dark" and "light" alone are not enough: stripping a user of "follow my OS"
- * is a regression the moment anyone prefers the *default* behaviour rather
- * than either specific scheme. The cycle is `system → light → dark → system`
- * so the control is one button, never a menu — a popover in a 34 px header is
- * a second focusable thing to reach, and the setting is not worth one.
- *
- * ## The attribute, not a class, not inline styles
- *
- * The sheet's light branch moves from the bare `prefers-color-scheme` media
- * query to a *pair* of selectors: `:root[data-weave-theme="light"]` (the
- * override) plus the media query narrowed by
- * `:root:not([data-weave-theme="dark"])` (system default). The attribute is
- * written on `<html>` because CSP `style-src 'nonce-…'` blocks inline
- * `style=""` attributes outright — the same verified reasoning that pushes
- * `cssvars.ts` through the CSSOM — while `data-*` attribute writes are not
- * style at all and need no exception. In `system` mode the attribute is
- * **cleared**, not set to a third value, so the media query keeps answering
- * a live OS flip without the client listening.
- *
- * ## Tier rules (§2)
- *
- * `src/web/client/**`. Storage arrives as the two-method port
- * `selection.storage.ts` uses, so a fake is an object literal and quota
- * failures stay the caller's problem — a theme the user could not persist is
- * the same cosmetic cost as a selection.
- */
-
+/** Persistent appearance mode and switching between the selected light/dark palettes. */
+import { DEFAULT_PREFERENCES, type Preferences } from "../../shared/preferences";
+import { THEMES } from "../../shared/themes";
+import type { PaletteChoice, ThemeChoice } from "../../shared/themes";
 import type { ColorScheme } from "../graph/graph.model";
+import { THEME_CHOICES, isThemeChoice } from "../../shared/themes";
+export { THEME_CHOICES, isThemeChoice };
+export type { ThemeChoice };
 
-/** What the user picked, as the button cycles it. */
-export type ThemeChoice = "system" | "light" | "dark";
-
-/** The choices in cycle order. */
-export const THEME_CHOICES: readonly ThemeChoice[] = ["system", "light", "dark"];
-
-/** The `localStorage` key. Namespaced and versioned. */
 export const THEME_STORAGE_KEY = "pi-weave.theme.v1";
-
-/** The slice of `Storage` this module needs. */
 export interface ThemeStorage {
   getItem(key: string): string | null;
   setItem(key: string, value: string): void;
 }
 
-/** Structural guard, mirroring `readBootstrap`'s. */
-export function isThemeChoice(value: unknown): value is ThemeChoice {
-  return value === "system" || value === "light" || value === "dark";
-}
-
 /**
  * The stored choice, or `null`.
  *
@@ -76,7 +30,7 @@ export function loadTheme(storage: ThemeStorage): ThemeChoice | null {
   }
 }
 
-/** Persist the choice. Reports failure as `false`, like `saveSelection`. */
+/** Persist the choice. Reports failure as `false`. */
 export function saveTheme(storage: ThemeStorage, choice: ThemeChoice): boolean {
   try {
     storage.setItem(THEME_STORAGE_KEY, choice);
@@ -86,62 +40,38 @@ export function saveTheme(storage: ThemeStorage, choice: ThemeChoice): boolean {
   }
 }
 
-/** The next choice in the cycle {@link THEME_CHOICES}. */
-export function cycleTheme(choice: ThemeChoice): ThemeChoice {
-  const index = THEME_CHOICES.indexOf(choice);
-  // An out-of-table choice cannot exist (the type says so), but a miss
-  // here must not be an `undefined` into the UI: wrap to the head.
-  return THEME_CHOICES[(index + 1) % THEME_CHOICES.length] ?? "system";
+type ThemePair = Pick<Preferences, "lightTheme" | "darkTheme">;
+
+/** Toggle to the selected palette for the opposite effective appearance. */
+export function toggleTheme(choice: ThemeChoice, systemScheme: ColorScheme, pair: ThemePair = DEFAULT_PREFERENCES): PaletteChoice {
+  const current = THEMES[effectiveScheme(choice, systemScheme, pair)].scheme;
+  return current === "light" ? pair.darkTheme : pair.lightTheme;
 }
 
-/**
- * The scheme actually drawing right now.
- *
- * This is the *whole* resolution: the sheet owns what colours a scheme is,
- * `scheme.ts` owns reading the OS once, and this owns the decision — so the
- * graph column, whose WebGL palette cannot read CSS custom properties, takes
- * the same answer the stylesheet's attribute takes.
- */
-export function effectiveScheme(choice: ThemeChoice, systemScheme: ColorScheme): ColorScheme {
-  return choice === "system" ? systemScheme : choice;
+/** System mode uses the user's palette for the current device appearance. */
+export function effectiveScheme(choice: ThemeChoice, systemScheme: ColorScheme, pair: ThemePair = DEFAULT_PREFERENCES): PaletteChoice {
+  return choice === "system" ? (systemScheme === "light" ? pair.lightTheme : pair.darkTheme) : choice;
 }
 
-/**
- * The `data-weave-theme` attribute value, or `null` to clear it.
- *
- * `null` is not a third value on purpose: in `system` mode the media query
- * alone must govern, and any attribute would override the OS. See the module
- * header's "attribute, not class" note.
- */
-export function themeAttr(choice: ThemeChoice): "light" | "dark" | null {
+/** System mode clears the attribute so the media query governs. */
+export function themeAttr(choice: ThemeChoice): PaletteChoice | null {
   return choice === "system" ? null : choice;
 }
 
-// --- the control's view ------------------------------------------------------------
-
-/**
- * The header button's face.
- *
- * The glyphs are the provenance language the tree already teaches
- * (`tree.model.ts`): filled, half and hollow of one shape. Filled `●` is
- * dark, hollower `◐` is system — half machine, half choice — and `○` is
- * light. Three glyphs, one family, no icon font, no `url()`.
- */
 export interface ThemeButtonView {
   readonly glyph: "●" | "◐" | "○";
-  /** The `title=`/`aria-label`. Names where it is *and* what clicking does. */
+  readonly label: string;
   readonly hint: string;
 }
 
-const THEME_GLYPHS: Readonly<Record<ThemeChoice, ThemeButtonView["glyph"]>> = {
-  dark: "●",
-  system: "◐",
-  light: "○",
-};
+function themeName(choice: ThemeChoice): string {
+  return choice === "system" ? "System" : THEMES[choice].name;
+}
 
-export function themeButton(choice: ThemeChoice): ThemeButtonView {
+export function themeButton(choice: ThemeChoice, systemScheme: ColorScheme = "dark", pair: ThemePair = DEFAULT_PREFERENCES): ThemeButtonView {
   return {
-    glyph: THEME_GLYPHS[choice],
-    hint: `Colour theme: ${choice} — click for ${cycleTheme(choice)}`,
+    glyph: choice === "system" ? "◐" : THEMES[choice].scheme === "light" ? "○" : "●",
+    label: themeName(choice),
+    hint: `Colour theme: ${themeName(choice)} — click for ${themeName(toggleTheme(choice, systemScheme, pair))}`,
   };
 }