pi-weave 0.1.8 → 0.1.10

package/src/web/client/note/Note.tsx

@@ -24,6 +24,7 @@
  */
 
 import DOMPurify from "dompurify";
+import { useMemo } from "preact/hooks";
 import type { GraphPayload, NotePayload } from "../../shared/wire";
 import type { EditorEvent, EditorPrompt, EditorToolbar } from "./editor.model";
 import { Editor, EditorBar } from "./Editor";
@@ -74,28 +75,60 @@ function Header({ view }: { view: NoteHeaderView }) {
 export function Note(props: NoteProps) {
   const note = props.note?.note ?? null;
   const empty = noteEmptyMessage(props.selectedId, note);
-  if (note === null) return <p class="weave-note-empty">{empty}</p>;
 
-  const index = wikiIndex(props.graph, note.slug);
+  // Both hook calls sit before the empty-return so the hook order cannot
+  // depend on whether a note is loaded. The memoization is cheap insurance:
+  // one marked parse + DOMPurify pass + O(nodes) index per *body or vault*
+  // instead of per shell render (every editor keystroke and divider pixel
+  // re-renders the shell). The instance the render builds —
+  // `markdownRenderer(index)` inside `renderNote` — stays per-call by design;
+  // only the *result* is memoized.
+  const index = useMemo(() => (note === null ? null : wikiIndex(props.graph, note.slug)), [note, props.graph]);
+  const html = useMemo(
+    () => (note === null || index === null ? "" : renderNote(DOMPurify, note.body, index)),
+    [note, index],
+  );
+
+  if (note === null || index === null) return <p class="weave-note-empty">{empty}</p>;
+
   // Bound once so TypeScript narrows it for both uses below: `toolbar.editing`
   // is what decides whether the textarea renders, and reading it twice off
   // `props` would need a non-null assertion at the second read.
   const toolbar = props.toolbar;
   const shell = { draft: props.draft, prompt: props.prompt, send: props.send };
+  // Keyed on the slug, not the body digest: the article is the scroll
+  // container, so an in-place swap would open every note at the previous
+  // note's scroll offset. A key change remounts it, and a fresh container
+  // starts at the top — no scroll-API effect to untest. The provenance
+  // class is the page's spine: the left rule takes the source's colour,
+  // which is how the desk says who wrote what a glance away from the text.
+  const header = noteHeader(note, props.now);
   return (
-    <article class="weave-note">
-      <Header view={noteHeader(note, props.now)} />
+    <article key={note.slug} class={`weave-note weave-note-${header.provenance}`}>
+      <Header view={header} />
       {toolbar === null ? null : <EditorBar toolbar={toolbar} {...shell} />}
       {toolbar !== null && toolbar.editing ? (
         <Editor toolbar={toolbar} {...shell} />
       ) : (
         <div
           class="weave-note-body"
+          // Programmatic focus target for `⌘2`: without a `tabindex`,
+          // `focusSelector`'s `.focus()` is a silent no-op. `-1` keeps it out
+          // of the Tab order (the workspace moves by `j/k` and `⌘1/2/3`, and
+          // Tab must stay the user's).
+          tabIndex={-1}
           onClick={(event) => {
             // A wikilink carries no href, so nothing is navigating; this only
-            // has to route the click onto the §1.3 context bus.
+            // has to route the click onto the §1.3 context bus. Anywhere else
+            // on the page *is* the edit affordance: a click on the prose opens
+            // the editor. The two never fight, because the link check reads
+            // the exact element the click landed on.
             const target = wikilinkTargetOf(event.target as unknown as Parameters<typeof wikilinkTargetOf>[0]);
-            if (target !== null) props.onSelect(target);
+            if (target !== null) {
+              props.onSelect(target);
+              return;
+            }
+            if (props.toolbar !== null) props.send({ type: "toggle" });
           }}
           onKeyDown={(event) => {
             if (event.key !== "Enter" && event.key !== " ") return;
@@ -105,7 +138,7 @@ export function Note(props: NoteProps) {
             props.onSelect(target);
           }}
           // Sanitised by `renderNote`'s three layers — see note.model.ts.
-          dangerouslySetInnerHTML={{ __html: renderNote(DOMPurify, note.body, index) }}
+          dangerouslySetInnerHTML={{ __html: html }}
         />
       )}
     </article>

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

@@ -729,7 +729,7 @@ export function tagLabel(tag: string): string {
  */
 export function noteEmptyMessage(selectedId: string | null, note: ViewNote | null): string | null {
   if (note !== null) return null;
-  if (selectedId === null) return "Select a note to read it here.";
+  if (selectedId === null) return "Nothing open — search with ⌘K, or walk the tree with j and k.";
   if (selectedId.startsWith(NOTE_PREFIX)) return "Loading…";
   // A module, a file, a package, the git state: real nodes with no prose
   // behind them. The context rail beside this column is where their

package/src/web/client/search/SearchPalette.tsx

@@ -7,7 +7,7 @@
  * `useState`, one memo and three handlers. §10's rule.
  */
 
-import { useMemo, useState } from "preact/hooks";
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
 import type { GraphPayload } from "../../shared/wire";
 import { useFocusTrap } from "../shell/FocusTrap";
 import type { SearchRowView } from "./search.model";
@@ -45,6 +45,15 @@ export function SearchPalette(props: SearchPaletteProps) {
   const [state, setState] = useState(initialSearchState);
   const search = useMemo(() => createSearch({ ...props.ports, onChange: setState }), []);
   const trap = useFocusTrap();
+  const input = useRef<HTMLInputElement | null>(null);
+  // Focus the input, not the container the trap starts on: the palette's
+  // whole surface is its query, and opening it to a container that only
+  // swallows (and does not forward) keystrokes makes the user click before
+  // they can type. Runs after the trap's own effect — hooks run in order,
+  // and the trap is created first — so this is the final word. The input
+  // carries the dialog's `aria-label`, so the announcement the
+  // container-focus exists for still happens.
+  useEffect(() => void input.current?.focus(), []);
   const model = paletteModel(state, props.graph);
 
   const pick = (index: number | null): void => {
@@ -76,7 +85,7 @@ export function SearchPalette(props: SearchPaletteProps) {
         <input
           type="search"
           class="weave-palette-input"
-          autofocus
+          ref={input}
           value={state.query}
           placeholder={PALETTE_PLACEHOLDER}
           aria-label={PALETTE_TITLE}

package/src/web/client/selection.storage.ts

@@ -0,0 +1,69 @@
+/**
+ * selection.storage.ts — the §1.3 context bus's memory across reloads.
+ *
+ * A manual refresh used to drop the open note: `selectedId` is a Preact
+ * signal, and signals do not survive a page load. The layout already
+ * persists (`shell/layout.model.ts`), and this is the same trick for the
+ * one piece of selection state the user actually misses: which note they
+ * were reading.
+ *
+ * ## Restore needs the graph
+ *
+ * A saved id is only offered back if it still names a node of the freshly
+ * loaded graph — a note deleted in another window must not resurrect as a
+ * selection pointing at nothing. That check needs the graph, which arrives
+ * after mount, so the restore is deliberately a pure function of
+ * `(graph, storage)` the shell calls once the first graph lands, not
+ * something this module schedules itself.
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`: storage arrives as a two-method port (same shape as
+ * `LayoutStorage`) rather than the global, because the real `localStorage`
+ * throws in partitioned-storage contexts and a module this small should be
+ * testable without a DOM.
+ */
+
+import type { GraphPayload } from "../shared/wire";
+
+/** The slice of `Storage` this module needs. */
+export interface SelectionStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/** Versioned like `pi-weave.layout.v1`: an id-shape change gets a new key. */
+export const SELECTION_STORAGE_KEY = "pi-weave.selection.v1";
+
+/**
+ * Remember the selection; an empty string records "nothing open".
+ * Reports failure as `false` instead of throwing — a quota or
+ * partitioned-storage error must never break a selection.
+ */
+export function saveSelection(storage: SelectionStorage, id: string | null): boolean {
+  try {
+    storage.setItem(SELECTION_STORAGE_KEY, id ?? "");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The saved selection to restore, or `null`.
+ *
+ * `graph` gates the offer: the id must still name a node of the current
+ * payload, so a note deleted elsewhere is quietly not restored. Reads are
+ * failure-absorbing for the same reason writes are.
+ */
+export function restoreSelection(graph: GraphPayload | null, storage: SelectionStorage): string | null {
+  if (graph === null) return null;
+  let raw: string | null;
+  try {
+    raw = storage.getItem(SELECTION_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+  if (raw === null || raw === "") return null;
+  return graph.model.nodes.some((node) => node.id === raw) ? raw : null;
+}

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

@@ -25,6 +25,7 @@
 import { Fragment } from "preact";
 import { useLayoutEffect, useRef } from "preact/hooks";
 import { Graph } from "../graph/Graph";
+import type { ColorScheme } from "../graph/graph.model";
 import type { PositionStorage } from "../graph/positions";
 import type { RendererFactory } from "../graph/renderer";
 import type { SchemeHost } from "../graph/scheme";
@@ -73,6 +74,16 @@ export interface ColumnsProps {
   renderer: RendererFactory;
   storage: PositionStorage;
   host: SchemeHost;
+  /**
+   * The scheme the shell resolved from the user's theme choice
+   * (`shell/theme.model.ts`'s `effectiveScheme`), or `null` to let the column
+   * read the OS (`graph/scheme.ts`'s `schemeOf`). The stylesheet carries the
+   * choice to everything CSS paints; WebGL cannot read custom properties, so
+   * the graph needs the decision handed to it as a value.
+   */
+  scheme: ColorScheme | null;
+  /** The boot graph fetch failed — see `state.ts`'s `graphFailed`. */
+  bootFailed: boolean;
   /** Slot the graph column fills with its `fit`, for the global `g` key. */
   fit: { current: (() => void) | null };
   /**
@@ -117,6 +128,8 @@ function Column({ id, props }: { id: ColumnId; props: ColumnsProps }) {
           renderer={props.renderer}
           storage={props.storage}
           host={props.host}
+          scheme={props.scheme}
+          bootFailed={props.bootFailed}
           fit={props.fit}
         />
       ) : null}

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

@@ -13,6 +13,8 @@
  * opened would be a worse lie than the disabled version it replaced.
  */
 
+import { LOGO_MARK_B64, LOGO_MARK_MIME } from "../../shared/logo";
+import type { ThemeButtonView } from "./theme.model";
 import type { ConnectionView, HeaderSummary } from "./shell.model";
 import { SEARCH_PLACEHOLDER, searchHint, summaryParts } from "./shell.model";
 
@@ -23,12 +25,25 @@ export interface HeaderProps {
   onRefresh: () => void;
   /** Opens the ⌘K palette. The same action the global key performs. */
   onSearch: () => void;
+  /** The theme control's face (glyph + hint), from `shell.model.ts`'s friend in `theme.model.ts`. */
+  theme: ThemeButtonView;
+  /** Advance the theme choice one step in its cycle. The same action the `t` key performs. */
+  onTheme: () => void;
 }
 
 export function Header(props: HeaderProps) {
   return (
     <header class="weave-header">
-      <span class="weave-brand">🧵 pi-weave</span>
+      <span class="weave-brand">
+        <img
+          class="weave-brand-mark"
+          src={`data:${LOGO_MARK_MIME};base64,${LOGO_MARK_B64}`}
+          alt=""
+          width={18}
+          height={18}
+        />
+        pi-weave
+      </span>
       <button type="button" class="weave-search" title={searchHint(props.shortcut)} onClick={props.onSearch}>
         <span class="weave-search-text">{SEARCH_PLACEHOLDER}</span>
         <kbd>{props.shortcut}</kbd>
@@ -40,6 +55,15 @@ export function Header(props: HeaderProps) {
           </span>
         ))}
       </span>
+      <button
+        type="button"
+        class="weave-theme"
+        onClick={props.onTheme}
+        title={props.theme.hint}
+        aria-label={props.theme.hint}
+      >
+        {props.theme.glyph}
+      </button>
       <button type="button" class="weave-refresh" onClick={props.onRefresh} title="Refetch everything">
         ⟳
       </button>

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

@@ -25,15 +25,19 @@
 
 import { useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { fetchJson } from "../api.dom";
+import type { ColorScheme } from "../graph/graph.model";
+import { schemeOf, watchScheme } from "../graph/scheme";
 import { createSigmaRenderer } from "../graph/renderer.dom";
 import { domEventSource } from "../live";
 import { createEditor, watchUnload, type EditorHandle } from "../note/editor.controller";
 import { editorPrompt, editorToolbar, initialEditorState, shouldBlockUnload } from "../note/editor.model";
 import { SearchPalette } from "../search/SearchPalette";
-import { connection, graph, noteBody, selectedId } from "../state";
+import { restoreSelection, saveSelection } from "../selection.storage";
+import { connection, graph, graphFailed, noteBody, selectedId } from "../state";
 import type { WorkspaceHandle } from "../workspace";
 import { observeNotes, select, startWorkspace } from "../workspace";
 import { Columns } from "./Columns";
+import { deeplinkSelection, formatHash } from "./deeplink.model";
 import { dividerHandlers } from "./drag.model";
 import { Header } from "./Header";
 import { HelpOverlay } from "./HelpOverlay";
@@ -44,8 +48,21 @@ import { breakpointFor, loadLayout, resolveColumns, saveLayout } from "./layout.
 import { StatusBar } from "./StatusBar";
 import type { OverlayId } from "./shell.model";
 import { connectionView, looksApple, searchShortcut, statusBarModel, summarize } from "./shell.model";
+import { cycleTheme, effectiveScheme, loadTheme, saveTheme, themeAttr, themeButton } from "./theme.model";
+import type { ThemeChoice } from "./theme.model";
 import { watchViewport } from "./viewport";
 
+/**
+ * Write the choice onto `<html>`, so the sheet's attribute branch and the
+ * media query agree on who is in charge (see `theme.model.ts`'s header). The
+ * one DOM write the theme needs, and it is here rather than in the model for
+ * the same reason `applyVars` is: it is an effect, not a decision.
+ */
+function applyThemeAttr(choice: ReturnType<typeof themeAttr>): void {
+  if (choice === null) delete document.documentElement.dataset.weaveTheme;
+  else document.documentElement.dataset.weaveTheme = choice;
+}
+
 export interface ShellProps {
   /** From the page bootstrap. Shown in the status bar. */
   cwd: string;
@@ -60,6 +77,12 @@ export function Shell(props: ShellProps) {
   const [overlay, setOverlay] = useState<OverlayId>(null);
   const [layout, setLayout] = useState<LayoutState>(() => loadLayout(localStorage, props.initialWidth));
   const [editorState, setEditorState] = useState(initialEditorState);
+  // The theme: what the user picked, and what the OS is currently saying. Two
+  // states because they answer different questions — `theme` changes on a
+  // button press or the `t` key, `systemScheme` on an OS flip while the user
+  // is in system mode — and `effectiveScheme` is where the two resolve.
+  const [theme, setTheme] = useState<ThemeChoice>(() => loadTheme(localStorage) ?? "system");
+  const [systemScheme, setSystemScheme] = useState<ColorScheme>(() => schemeOf(window));
   const workspace = useRef<WorkspaceHandle | null>(null);
   // Filled by the graph column at mount, cleared on unmount. The global `g`
   // key's only route to the renderer — see `Graph.tsx`'s `fit` prop.
@@ -83,6 +106,37 @@ export function Shell(props: ShellProps) {
     return () => handle.stop();
   }, []);
 
+  // §1.3 continuity: a reload keeps the note you were reading. Saving is
+  // gated on the restore decision so the mount-time `null` cannot wipe the
+  // saved id before the first graph arrives to validate it against.
+  const selectionRestored = useRef(false);
+  // The deep link is read once, at mount, into a ref — the URL is an input
+  // to boot only, and the hash-write effect below must never clear a link
+  // this effect has not read yet.
+  const bootHash = useRef(location.hash);
+  useEffect(() => {
+    if (!selectionRestored.current) return;
+    saveSelection(localStorage, selectedId.value);
+    // replaceState, not pushState: the address bar mirrors the note on
+    // screen, and reading three notes is not three history entries. The
+    // *string* is the model's (`formatHash`); this is the write itself.
+    history.replaceState(null, "", formatHash(selectedId.value));
+  }, [selectedId.value]);
+  useEffect(() => {
+    if (selectionRestored.current || graph.value === null) return;
+    selectionRestored.current = true;
+    if (selectedId.value !== null) return;
+    // A link wins over storage: the address bar is an explicit instruction,
+    // the saved note is a habit. A link to a note the graph does not hold is
+    // refused (see `deeplink.model.ts`) and continuity falls through.
+    const linked = deeplinkSelection(bootHash.current, graph.value);
+    if (linked !== null) void select(fetchJson, linked);
+    else {
+      const saved = restoreSelection(graph.value, localStorage);
+      if (saved !== null) void select(fetchJson, saved);
+    }
+  }, [graph.value]);
+
   // Every note that arrives, from any of the three directions it can arrive
   // from (mount, selection, SSE refetch), so the editor can decide whether it
   // is news or an interruption — see `editor.model.ts`'s header.
@@ -95,6 +149,18 @@ export function Shell(props: ShellProps) {
 
   useEffect(() => watchViewport(window, setWidth), []);
 
+  // The theme's two effects: the attribute decides what the sheet paints, the
+  // save decides what a reload restores. Both keyed on the choice alone — a
+  // system-scheme flip touches neither, because the media query repaints the
+  // stylesheet by itself and the shell only re-resolves the graph's scheme.
+  useEffect(() => applyThemeAttr(themeAttr(theme)), [theme]);
+  useEffect(() => void saveTheme(localStorage, theme), [theme]);
+  // Live OS flips, needed only in system mode but harmless always: the
+  // stylesheet follows the OS on its own; this is what lets the *graph* (and
+  // the header button, which shows the resolved scheme nowhere — it shows the
+  // choice) keep up while the choice is "system".
+  useEffect(() => watchScheme(window, setSystemScheme), []);
+
   useEffect(
     () =>
       watchKeys(document, {
@@ -111,6 +177,7 @@ export function Shell(props: ShellProps) {
             clearSelection: () => editor.send({ type: "navigate", id: null }),
             toggleEdit: () => editor.send({ type: "toggle" }),
             saveNote: () => editor.send({ type: "save" }),
+            cycleTheme: () => setTheme((current) => cycleTheme(current)),
           }),
       }),
     [],
@@ -139,6 +206,8 @@ export function Shell(props: ShellProps) {
         shortcut={searchShortcut(looksApple(props.platform))}
         onRefresh={() => workspace.current?.refresh()}
         onSearch={() => setOverlay("search")}
+        theme={themeButton(theme)}
+        onTheme={() => setTheme((current) => cycleTheme(current))}
       />
       <Columns
         resolved={resolved}
@@ -146,6 +215,8 @@ export function Shell(props: ShellProps) {
         onMove={drag.onMove}
         onUp={drag.onUp}
         onKey={drag.onKey}
+        scheme={effectiveScheme(theme, systemScheme)}
+        bootFailed={graphFailed.value}
         graph={graph.value}
         note={noteBody.value}
         selectedId={selectedId.value}
@@ -180,7 +251,10 @@ export function Shell(props: ShellProps) {
       {overlay === "search" ? (
         <SearchPalette
           graph={graph.value}
-          onSelect={(id) => void select(fetchJson, id)}
+          // Through the editor, like every column's `onSelect`: choosing a hit
+          // while a draft is dirty must park behind the UNSAVED prompt, not
+          // wipe it. This was the one navigation path that skipped the guard.
+          onSelect={(id) => editor.send({ type: "navigate", id })}
           onClose={() => setOverlay(null)}
           ports={{ fetch: fetchJson, now: Date.now, delay: (run, ms) => void setTimeout(run, ms) }}
         />

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

@@ -0,0 +1,61 @@
+/**
+ * Deep links: the selection, addressable (weave-workspace UX backlog T5.4).
+ *
+ * `#note/<slug>` in the location bar is the current selection, both ways:
+ * a `location.hash` naming a real node at boot takes priority over the saved
+ * *last note* (the link is an explicit instruction, storage is a habit), and
+ * every selection change is written back with `history.replaceState` — a
+ * shared URL must mean the note on screen, but reading three notes must not
+ * put three entries in the back button's history.
+ *
+ * Two facts decide the shape. First, only *note* nodes deep-link: a
+ * repository or file node has no URL-worthy permanence (its id is derived
+ * from paths that move), and the note fetch behind a selection 404s for
+ * anything else. Second, a hash naming a node that is *not in the graph*
+ * must refuse rather than select: a stale link pointing at a deleted note
+ * would otherwise land the reader on "Nothing open" with the saved note
+ * passed over — parsing without validation would make every dead link hide
+ * the workspace's own continuity.
+
+ * Everything here is a pure function over strings and payloads (§10); the
+ * `history.replaceState` call itself is the shell's, because it is an effect.
+ */
+
+import type { GraphPayload } from "../../shared/wire";
+
+/**
+ * The note node a hash names, or `null`.
+ *
+ * Accepts the two spellings a user might paste — `#note/<slug>` and the
+ * node id it encodes (`#note:<slug>` is what the tree's own rows use) — and
+ * rejects everything else, including the bare `#` a reader gets from
+ * clearing the hash by hand. An empty slug would produce a request for
+ * `/api/note/`, which means nothing to anyone.
+ */
+export function hashSelection(hash: string): string | null {
+  if (hash === "" || hash === "#") return null;
+  const body = hash.slice(1);
+  const match = /^note[/:](.+)$/.exec(body);
+  return match === null ? null : `note:${match[1]}`;
+}
+
+/**
+ * The boot selection: a hash that names a node the payload actually holds,
+ * or `null`. Validation is *the* point — see the module header.
+ */
+export function deeplinkSelection(hash: string, payload: GraphPayload | null): string | null {
+  const wanted = hashSelection(hash);
+  if (wanted === null || payload === null) return null;
+  return payload.model.nodes.some((node) => node.id === wanted) ? wanted : null;
+}
+
+/**
+ * The URL fragment for a selection: `#note/<slug>`, or `""` for a cleared
+ * selection (an empty string hands `replaceState` the bare URL, clearing the
+ * hash). A non-note id formats to `""` too — the address bar describes the
+ * *note* being read, nothing else.
+ */
+export function formatHash(selectedId: string | null): string {
+  const slug = selectedId === null ? null : selectedId.startsWith("note:") ? selectedId.slice("note:".length) : null;
+  return slug === null || slug === "" ? "" : `#note/${slug}`;
+}

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

@@ -52,11 +52,18 @@ export const FOCUSABLE_SELECTOR = [
  * Where Tab should land next, or `null` to leave the event alone.
  *
  * Returns an **index** rather than an element so the whole thing is testable
- * with an array of numbers if you like. `null` means "not our business":
- * a trap over zero or one focusable elements has nothing to cycle, and
- * calling `preventDefault` in that case would strand the user on a dialog
- * that eats Tab and does nothing with it — strictly worse than an untrapped
- * one they can at least escape.
+ * with an array of numbers if you like. Two refusal cases, by different
+ * reasoning:
+ *
+ * - `count === 0` — nothing to cycle, and holding the user on a dialog that
+ *   eats Tab and does nothing with it is strictly worse than an untrapped one
+ *   they can at least escape.
+ * - `count === 1` — there *is* something to cycle, and the modal must not
+ *   let go: Tab returns the user to the single control, matching the WAI-ARIA
+ *   expectation that focus stays in an open dialog. (This was once `null`
+ *   with the zero case's reasoning — "one thing, nowhere to go" — but a
+ *   palette whose only control is its input would then Tab straight out into
+ *   the covered workspace, typing into a search box the user cannot see.)
  *
  * @param count how many focusables the dialog contains
  * @param at the index of the currently focused one, or `-1` when focus is on
@@ -64,7 +71,8 @@ export const FOCUSABLE_SELECTOR = [
  * @param backwards Shift+Tab
  */
 export function trapTarget(count: number, at: number, backwards: boolean): number | null {
-  if (count <= 1) return null;
+  if (count === 0) return null;
+  if (count === 1) return 0;
   // Focus on the container itself: Tab enters at the top, Shift+Tab at the
   // bottom. Without this the first Tab out of a freshly-opened dialog would
   // compute from -1 and land on the second control, skipping the input.

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

@@ -27,7 +27,7 @@
  * | `⌘1` `⌘2` `⌘3` | always |
  * | `⌘E` `⌘S` | always — the editor's two keys (§11 P5.4) |
  * | `Esc` | an overlay is open, or something is selected. Never otherwise |
- * | `/` `g` `?` | **only** when focus is not in a text field and no overlay is open |
+ * | `/` `g` `?` `t` | **only** when focus is not in a text field and no overlay is open |
  *
  * `⌘S` is claimed **even while typing**, which is the one place this map
  * deliberately overrides the browser. It has to be: the browser's `⌘S` is
@@ -51,6 +51,7 @@
  * `⌘K`, which would otherwise re-open the palette on top of itself.
  */
 
+import { COLUMNS, columnsAt } from "./layout.model";
 import type { ColumnId } from "./layout.model";
 import type { OverlayId } from "./shell.model";
 
@@ -104,7 +105,9 @@ export type ShellAction =
   /** `⌘E` — toggle the note column between read and edit (§11 P5.4). */
   | { readonly type: "toggleEdit" }
   /** `⌘S` — save the open draft. */
-  | { readonly type: "saveNote" };
+  | { readonly type: "saveNote" }
+  /** `t` — cycle the colour theme: system → light → dark → system. */
+  | { readonly type: "cycleTheme" };
 
 /**
  * The command-key letters, as data.
@@ -129,6 +132,18 @@ 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(
+  COLUMNS.filter((c) => columnsAt("medium").includes(c) === false || columnsAt("narrow").includes(c) === false),
+);
+
 /**
  * Whether a modifier combination counts as "the platform's command key".
  *
@@ -162,6 +177,7 @@ export const BARE_KEYS: Readonly<Record<string, ShellAction>> = {
   "/": { type: "filterTree" },
   g: { type: "fitGraph" },
   "?": { type: "openHelp" },
+  t: { type: "cycleTheme" },
 };
 
 /**
@@ -346,6 +362,8 @@ export interface ShellEffects {
   toggleEdit(): void;
   /** `⌘S` — dispatch `save` into the note editor. */
   saveNote(): void;
+  /** `t` — advance the user's theme choice by one step in its cycle. */
+  cycleTheme(): void;
 }
 
 /** Perform an action. Total over {@link ShellAction}. */
@@ -371,6 +389,8 @@ export function runShellAction(action: ShellAction, fx: ShellEffects): void {
       return fx.toggleEdit();
     case "saveNote":
       return fx.saveNote();
+    case "cycleTheme":
+      return fx.cycleTheme();
   }
 }
 
@@ -408,8 +428,12 @@ export function keyHelp(cmd: string): readonly KeyHelpGroup[] {
       title: "Global",
       entries: [
         { combo: `${cmd}K`, what: "Search notes and the repository" },
-        ...Object.entries(COLUMN_DIGITS).map(([digit, column]) => ({ combo: `${cmd}${digit}`, what: `Focus the ${column} column` })),
+        ...Object.entries(COLUMN_DIGITS).map(([digit, column]) => ({
+          combo: `${cmd}${digit}`,
+          what: `Focus the ${column} column${COLLAPSIBLE_COLUMNS.has(column) ? " (when on screen)" : ""}`,
+        })),
         { combo: "?", what: "This help" },
+        { combo: "t", what: "Cycle the colour theme (system / light / dark)" },
         { combo: "Esc", what: "Clear the selection, or close an overlay" },
       ],
     },