pi-weave 0.1.8 → 0.1.10

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

@@ -67,53 +67,78 @@ export type ColorScheme = "dark" | "light";
  */
 export const GRAPH_PALETTE: Readonly<Record<ColorScheme, Readonly<Record<ColorSlot, string>>>> = {
   dark: {
-    accent: "#a48cff",
-    success: "#4ade80",
-    warning: "#fbbf24",
-    dim: "#8f8a9c",
-    text: "#e8e6ee",
-    muted: "#5d5869",
-    line: "#343141",
+    accent: "#b79fdd",
+    success: "#7fc49a",
+    warning: "#e8b04c",
+    dim: "#bb9ecf",
+    text: "#fde2f3",
+    muted: "#aca3d4",
+    line: "#4a527e",
   },
   light: {
-    accent: "#6d4aff",
-    success: "#15803d",
-    warning: "#b45309",
-    dim: "#6f6b66",
-    text: "#1c1b19",
-    muted: "#9a958e",
-    line: "#d2cec8",
+    accent: "#85586f",
+    success: "#3f704e",
+    warning: "#a05a1c",
+    dim: "#7c6257",
+    text: "#43303a",
+    muted: "#7f6455",
+    line: "#d0b8a8",
   },
 };
 
 /**
  * Node kind → colour slot.
  *
- * The same assignment `kindStyle` makes in `src/pi/viewer/tui/theme.ts`, which
- * the client tier may not import. Restated rather than re-derived for the
- * reason `tree.model.ts`'s glyph table gives: someone who has used
- * `/weave-view tui` should recognise the graph, and a second vocabulary is a
- * cost with no benefit. `note` takes `text` there too — a note's identity is
- * carried by its provenance badge, not by its kind.
+ * The shell's design language (shell/theme.ts) is **three greys doing the
+ * structural work and one accent used sparingly** — success/warning are
+ * status colours there (provenance badges, the connection dot), not
+ * decoration. Mapping code kinds onto them painted the canvas green and
+ * amber and read as a different app inside the workspace, so every kind
+ * except the three that carry identity recedes into `dim`:
+ *
+ * - `vault` / `repository` keep `accent` — the two knowledge anchors, the
+ *   same violet the note column's wikilinks are painted in.
+ * - `note` keeps `text` — notes are the product (§1.1), and their identity
+ *   is carried by the provenance badge, not by a hue.
+ * - Generated code — modules, packages, entry points, git, externals, files
+ *   — takes `dim`, the same grey a `generated` row takes in the tree. The
+ *   TUI's `kindStyle` (src/pi/viewer/tui/theme.ts) still maps these kinds to
+ *   success/warning; the two media disagree on purpose, because a pi theme
+ *   has no dark/light stylesheet to violate and a terminal can restyle
+ *   everything. Here the sheet decides, and the sheet says calm.
  */
 export const KIND_SLOT: Readonly<Record<WireNodeKind, ColorSlot>> = {
   vault: "accent",
   note: "text",
   repository: "accent",
-  module: "success",
-  package: "success",
-  entryPoint: "warning",
-  gitState: "warning",
-  external: "warning",
+  module: "dim",
+  package: "dim",
+  entryPoint: "dim",
+  gitState: "dim",
+  external: "dim",
   file: "dim",
 };
 
-/** Edge kind → colour slot. Structure recedes; association is the accent. */
+/**
+ * Edge kind → colour slot. Structure recedes; association is the accent.
+ *
+ * "Recedes" used to mean `line` (`--weave-line-strong`), which read as
+ * *absent* — 1.5:1 against either background, below the 3:1 non-text minimum,
+ * and the reason the skeleton of the graph was invisible until something was
+ * selected. The `dim` slot is 5.5:1 against the dark background and 4.9:1
+ * against the light one, so containment reads as the hairline scaffolding it
+ * is without vanishing.
+ *
+ * `mentions` joins `links-to` on the accent. Both are content associations
+ * between human knowledge and the rest of the graph — splitting them across
+ * two hues is what put a rainbow on the canvas — and §1.3's rail is where
+ * the two kinds are told apart, at reading size, with labels.
+ */
 export const EDGE_SLOT: Readonly<Record<WireEdgeKind, ColorSlot>> = {
-  contains: "line",
-  "anchored-at": "line",
+  contains: "dim",
+  "anchored-at": "dim",
   "links-to": "accent",
-  mentions: "warning",
+  mentions: "accent",
 };
 
 /** The colour a node kind is drawn in. */
@@ -131,9 +156,13 @@ export function edgeColor(kind: WireEdgeKind, scheme: ColorScheme): string {
 /**
  * The smallest a node is ever drawn, in layout units.
  *
- * A leaf still has to be clickable, and sigma's hit test is the drawn radius.
+ * A leaf still has to be clickable, and sigma's hit test is the drawn radius —
+ * at fit zoom a leaf renders at `MIN_NODE_SIZE · cameraCorrection`, so a floor
+ * of 6 is what keeps every node inside a pointer's reach at overview zoom.
+ * (The d3 gallery's force-directed graphs draw every node the same radius for
+ * exactly this reason; size still varies by degree up to the ceiling.)
  */
-export const MIN_NODE_SIZE = 3;
+export const MIN_NODE_SIZE = 6;
 
 /**
  * The degree at which a node reaches {@link NODE_RADIUS}.
@@ -167,10 +196,10 @@ export function nodeSize(degree: number): number {
   return MIN_NODE_SIZE + (NODE_RADIUS - MIN_NODE_SIZE) * share;
 }
 
-/** Edge thickness by kind. Containment is scaffolding; a wikilink is content. */
+/** Edge thickness by kind. A wikilink keeps its weight; structure is hairline. */
 export const EDGE_SIZE: Readonly<Record<WireEdgeKind, number>> = {
-  contains: 0.8,
-  "anchored-at": 0.8,
+  contains: 1,
+  "anchored-at": 1,
   "links-to": 1.4,
   mentions: 1,
 };
@@ -247,6 +276,52 @@ export interface RenderGraph {
   readonly edges: readonly RenderEdge[];
 }
 
+/** The normalization box the renderer freezes the view to. See {@link frameBox}. */
+export interface ViewBox {
+  readonly x: readonly [number, number];
+  readonly y: readonly [number, number];
+}
+
+/**
+ * The box the graph is framed on — sigma's `customBBox`.
+ *
+ * ## Why a box is frozen at all
+ *
+ * Sigma's default `autoRescale` recomputes the graph→viewport normalization
+ * from the **current extent on every refresh**, and a drag repaints every
+ * frame. The consequence, measured on this repository's graph: the moment a
+ * dragged node crosses the extent boundary — at the edge of the view — the
+ * whole graph rescales under the cursor, so the view "suddenly makes a
+ * distance" and the node ends up dragged very far from the centre while the
+ * user chases it. A frozen box makes the coordinates stable for the whole
+ * session: the node stays under the cursor, the canvas bounds the drag, and
+ * `[fit]` re-frames onto whatever the current positions are.
+ *
+ * The box is the exact extent of the rendered positions — no padding of its
+ * own, because sigma's `stagePadding` (in pixels) already insets the fit, and
+ * the same box handed back on `fit()` re-frames dragged-apart graphs.
+ *
+ * `null` for an empty graph: there is nothing to frame, and the caller
+ * clears the override so sigma falls back to its own behaviour.
+ */
+export function frameBox(points: readonly Point[]): ViewBox | null {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let seen = 0;
+  for (const p of points) {
+    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) continue;
+    seen++;
+    if (p.x < minX) minX = p.x;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.y > maxY) maxY = p.y;
+  }
+  if (seen === 0) return null;
+  return { x: [minX, maxX], y: [minY, maxY] };
+}
+
 /** The empty graph. What the column renders before the first payload lands. */
 export const EMPTY_RENDER_GRAPH: RenderGraph = { nodes: [], edges: [] };
 
@@ -455,6 +530,7 @@ export function edgeReducer(
  */
 export interface GraphSettings {
   readonly hideEdgesOnMove: boolean;
+  readonly enableCameraPanning: boolean;
   readonly renderEdgeLabels: boolean;
   readonly labelDensity: number;
   readonly labelGridCellSize: number;
@@ -505,6 +581,9 @@ export function graphSettings(scheme: ColorScheme): GraphSettings {
     // §7.4. A pan over a few thousand edges is the one interaction that drops
     // frames, and the edges are the part nobody is reading mid-gesture.
     hideEdgesOnMove: true,
+    // The renderer toggles this off while a node is being dragged, so the
+    // gesture pins the node to the cursor instead of panning the camera.
+    enableCameraPanning: true,
     renderEdgeLabels: false,
     labelDensity: LABEL_DENSITY,
     labelGridCellSize: LABEL_GRID_CELL_SIZE,

package/src/web/client/graph/positions.ts

@@ -34,10 +34,34 @@
  * the root `tsconfig.json` project compiles the tests.
  */
 
-import { computeLayout, hashId } from "../../shared/layout";
+import { computeLayout } from "../../shared/layout";
 import type { LayoutOptions, Point } from "../../shared/layout";
 import type { WireGraphEdge, WireGraphNode } from "../../shared/wire";
 
+/**
+ * FNV-1a (32-bit) followed by MurmurHash3's `fmix32` avalanche.
+ *
+ * The finalizer is not optional: FNV-1a mixes its *low* bits well but its high
+ * bits poorly for short, near-identical inputs — and the digest folds the hash
+ * into a bounded key, so the high bits are the significant part. Raw FNV-1a
+ * over `leaf001…leaf199` put 199 ids into six of twelve sectors; `fmix32`
+ * costs four lines and makes every bit depend on every input bit.
+ */
+export function hashId(id: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < id.length; i++) {
+    h ^= id.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+
 // --- computing ----------------------------------------------------------------------
 
 /**
@@ -64,22 +88,39 @@ export const LAYOUT_SEED = 1;
  * re-running from a settled state is a near-fixed-point, which is the property
  * that makes an expand feel like an expand.
  *
- * The viewport is **not** a parameter, deliberately. `computeLayout` centres
- * its output on the width and height it is given, and sigma's camera fits
- * whatever extent it is handed — so feeding the real column width in would
- * re-run the simulation on every divider drag to produce a picture the camera
- * immediately normalises away. A fixed nominal viewport keeps the layout a
- * function of the *graph*, which is what makes it cacheable at all.
+ * **New containment children start at their parent** (d3's own collapse/
+ * expand pattern): a newly visible node without a stored position enters the
+ * simulation at its parent's warm position, so the relaxation it needs is
+ * local — the collide force makes it step out among its siblings — instead of
+ * d3's phyllotaxis spiral dropping it across the graph and dragging the whole
+ * arrangement along.
+ *
+ * The viewport is **not** a parameter, deliberately. The layout is centred on
+ * the origin by `forceX()`/`forceY()`, and sigma's camera fits whatever extent
+ * it is handed — so feeding the real column width in would re-run the
+ * simulation on every divider drag to produce a picture the camera
+ * immediately normalises away. Keeping the layout a function of the *graph*
+ * alone is what makes it cacheable at all.
  */
 export function layoutFor(
   nodes: readonly WireGraphNode[],
   edges: readonly WireGraphEdge[],
   warm?: ReadonlyMap<string, Point>,
 ): Map<string, Point> {
-  const options: LayoutOptions = { ticks: LAYOUT_TICKS, seed: LAYOUT_SEED };
+  const seeded = new Map<string, Point>(warm ?? []);
+  if (seeded.size > 0) {
+    for (const e of edges) {
+      if (e.kind !== "contains" && e.kind !== "anchored-at") continue;
+      if (seeded.has(e.target)) continue;
+      const at = seeded.get(e.source);
+      if (at !== undefined) seeded.set(e.target, { x: at.x, y: at.y });
+    }
+  }
+  const options: LayoutOptions = { ticks: LAYOUT_TICKS, seed: LAYOUT_SEED, pinWarm: true };
+  if (seeded.size > 0) options.initial = seeded;
   return computeLayout(
-    { generatedAt: "", staleness: null, nodes: [...nodes], edges: [...edges] },
-    warm === undefined ? options : { ...options, initial: warm },
+    { generatedAt: "", staleness: null, nodes: [...nodes], edges: [...edges], contentDigest: "" },
+    options,
   );
 }
 
@@ -161,7 +202,7 @@ export interface PositionStorage {
 }
 
 /** The `localStorage` key. Namespaced and versioned, like the layout's. */
-export const POSITIONS_STORAGE_KEY = "pi-weave.graph.positions.v1";
+export const POSITIONS_STORAGE_KEY = "pi-weave.graph.positions.v2";
 
 /**
  * Coordinates are rounded to **one** decimal before storage.
@@ -188,7 +229,11 @@ function round1(value: number): number {
 export function serializePositions(key: string, positions: ReadonlyMap<string, Point>): string {
   const at: Record<string, [number, number]> = {};
   for (const [id, point] of positions) at[id] = [round1(point.x), round1(point.y)];
-  return JSON.stringify({ v: 1, key, at });
+  // `v: 2` — the branch-anchor layout (separated sibling blobs). A v1 entry
+  // is a tangled arrangement from the single-centre recipe, and the shape key
+  // cannot tell the two apart because the recipe changed under the same node
+  // and edge set. The version can.
+  return JSON.stringify({ v: 2, key, at });
 }
 
 /**
@@ -220,7 +265,7 @@ export function deserializePositions(raw: string | null, key: string): Map<strin
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
 
   const record = parsed as Record<string, unknown>;
-  if (record["v"] !== 1) return null;
+  if (record["v"] !== 2) return null;
   if (record["key"] !== key) return null;
 
   const at = record["at"];

package/src/web/client/graph/renderer.ts

@@ -49,8 +49,8 @@
  */
 
 import type { Point } from "../../shared/layout";
-import type { ColorScheme, EdgeDisplayOverride, GraphSettings, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode } from "./graph.model";
-import { edgeReducer, graphSettings, nodeReducer } from "./graph.model";
+import type { ColorScheme, EdgeDisplayOverride, GraphSettings, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode, ViewBox } from "./graph.model";
+import { edgeReducer, frameBox, graphSettings, nodeReducer } from "./graph.model";
 import type { ProjectedGraph } from "./project";
 import { positionsOf, project, syncPositions } from "./project";
 
@@ -94,6 +94,12 @@ export interface GraphRenderer {
   fit(): void;
   /** Current positions, for warm-starting a re-run. */
   positions(): Map<string, Point>;
+  /** Called when the user starts dragging a node. */
+  onDragStart(handler: (id: string) => void): void;
+  /** Called with graph-space coordinates while a node is dragged. */
+  onDragMove(handler: (id: string, at: Point) => void): void;
+  /** Called when a node drag ends. */
+  onDragEnd(handler: (id: string) => void): void;
   /** Tear down. Idempotent, and must leave no listener behind. */
   destroy(): void;
 }
@@ -130,6 +136,9 @@ export function nullRenderer(): GraphRenderer {
     setHighlight() {},
     onSelect() {},
     fit() {},
+    onDragStart() {},
+    onDragMove() {},
+    onDragEnd() {},
     positions() {
       return new Map();
     },
@@ -174,9 +183,23 @@ export interface CameraLike {
 export interface SigmaLike {
   on(event: "clickNode", handler: (payload: { node: string }) => void): unknown;
   on(event: "clickStage", handler: () => void): unknown;
+  on(event: "downNode", handler: (payload: { node: string }) => void): unknown;
+  on(event: "moveBody", handler: (payload: { event: { x: number; y: number }; preventSigmaDefault(): void }) => void): unknown;
+  on(event: "upNode" | "upStage", handler: () => void): unknown;
+  viewportToGraph(position: { x: number; y: number }): Point;
   setSetting(key: "nodeReducer", value: (id: string, data: RenderNode) => NodeDisplayOverride): unknown;
   setSetting(key: "edgeReducer", value: (key: string, data: RenderEdge) => EdgeDisplayOverride): unknown;
+  setSetting(key: "enableCameraPanning", value: boolean): unknown;
   setGraph(graph: ProjectedGraph): unknown;
+  /**
+   * Freeze the graph→viewport normalization onto a fixed box.
+   *
+   * Sigma's own `autoRescale` would recompute that mapping from the moving
+   * extent on every repaint — which a drag does every frame — so crossing the
+   * view's edge rescaled the whole graph under the cursor. `graph.model.ts`'s
+   * {@link frameBox} records the why in full.
+   */
+  setCustomBBox(box: ViewBox | null): unknown;
   refresh(): unknown;
   getCamera(): CameraLike;
   kill(): void;
@@ -212,6 +235,24 @@ export function sigmaRenderer(create: SigmaFactory, scheme: ColorScheme): GraphR
   let graph: ProjectedGraph = project({ nodes: [], edges: [] });
   let highlight: ReadonlySet<string> | null = null;
   let select: (id: string | null) => void = () => {};
+  let dragStart: (id: string) => void = () => {};
+  let dragMove: (id: string, at: Point) => void = () => {};
+  let dragEnd: (id: string) => void = () => {};
+  let dragging: string | null = null;
+
+  const endDrag = (id: string | null): void => {
+    if (dragging === null) return;
+    const current = dragging;
+    dragging = null;
+    // A node drag is a pin, not a pan: sigma's captor would otherwise move the
+    // camera on the same gesture that is moving the node, and the node would
+    // slide away from the cursor. Re-enable panning only when the drag ends.
+    sigma?.setSetting("enableCameraPanning", true);
+    if (id === null || id === current) dragEnd(current);
+  };
+
+  /** The box to freeze the view on, from the graph's *current* positions. */
+  const boxOf = (): ViewBox | null => frameBox([...positionsOf(graph).values()]);
 
   /**
    * Push the current highlight into sigma's reducers (§7.4).
@@ -236,13 +277,41 @@ export function sigmaRenderer(create: SigmaFactory, scheme: ColorScheme): GraphR
       // the tree and the context rail all recompute from it.
       instance.on("clickNode", ({ node }) => select(node));
       instance.on("clickStage", () => select(null));
+      instance.on("downNode", ({ node }) => {
+        dragging = node;
+        // Hold the view still while the node follows the cursor (see endDrag).
+        sigma?.setSetting("enableCameraPanning", false);
+        dragStart(node);
+      });
+      instance.on("moveBody", (payload) => {
+        if (dragging !== null) {
+          // Sigma's captor pans the camera on every mouse move while the
+          // button is down; during a node drag that is the pan the gesture
+          // must not be. `preventSigmaDefault` is the captor's own gate — it
+          // is consulted right after this handler returns — and without it
+          // the camera follows the cursor 1:1 while the pin follows it too,
+          // so the node appears to slide away under the view.
+          payload.preventSigmaDefault();
+          dragMove(dragging, instance.viewportToGraph({ x: payload.event.x, y: payload.event.y }));
+        }
+      });
+      instance.on("upNode", () => endDrag(dragging));
+      instance.on("upStage", () => endDrag(null));
       applyReducers(instance);
+      // Freeze the view box for whatever graph arrived before mount, so the
+      // first frame is already framed and stable — see `SigmaLike.setCustomBBox`.
+      instance.setCustomBBox(boxOf());
       sigma = instance;
     },
 
     setGraph(next) {
       graph = project(next);
       sigma?.setGraph(graph);
+      // Re-frame on a shape change: new nodes legitimately change the extent,
+      // and the box is what keeps the *drag* frames from also changing it.
+      // Deliberately not touched by `setPositions` — a settling simulation
+      // must not move the view under the user.
+      sigma?.setCustomBBox(boxOf());
     },
 
     setPositions(positions) {
@@ -261,16 +330,31 @@ export function sigmaRenderer(create: SigmaFactory, scheme: ColorScheme): GraphR
       select = handler;
     },
 
+    onDragStart(handler) {
+      dragStart = handler;
+    },
+
+    onDragMove(handler) {
+      dragMove = handler;
+    },
+
+    onDragEnd(handler) {
+      dragEnd = handler;
+    },
+
     fit() {
-      // `animatedReset` settles when the animation ends. Nothing awaits a
-      // camera move, and a rejection from a camera killed mid-flight is noise.
+      // Re-frame onto the **current** positions — a graph the user has pulled
+      // apart wants its dragged nodes inside the view — then reset the camera
+      // onto that box. `animatedReset` settles when the animation ends. Nothing
+      // awaits a camera move, and a rejection from a camera killed mid-flight
+      // is noise.
+      sigma?.setCustomBBox(boxOf());
       void sigma?.getCamera().animatedReset();
     },
 
     positions() {
       return positionsOf(graph);
     },
-
     destroy() {
       sigma?.kill();
       sigma = null;

package/src/web/client/graph/scheme.ts

@@ -18,14 +18,14 @@ import type { ColorScheme } from "./graph.model";
 /**
  * The slice of `window` this module reads.
  *
- * `matchMedia` returns far more than `matches`, and naming `MediaQueryList`
- * would make the module uncompilable by the root `tsconfig.json` project (no
- * `DOM` lib), which is what a test importing it runs under. The narrow shape
- * is the same trick `viewport.ts` and `cssvars.ts` use, and the real `window`
- * satisfies it structurally.
+ * `matchMedia` returns far more than a {@link SchemeList}, and naming
+ * `MediaQueryList` would make the module uncompilable by the root
+ * `tsconfig.json` project (no `DOM` lib), which is what a test importing it
+ * runs under. The narrow shape is the same trick `viewport.ts` and
+ * `cssvars.ts` use, and the real `window` satisfies it structurally.
  */
 export interface SchemeHost {
-  matchMedia(query: string): { readonly matches: boolean };
+  matchMedia(query: string): SchemeList;
 }
 
 /** The query. Light is the exception; see the module header. */
@@ -42,3 +42,48 @@ export function schemeOf(host: SchemeHost | null | undefined): ColorScheme {
   if (host === null || host === undefined || typeof host.matchMedia !== "function") return "dark";
   return host.matchMedia(LIGHT_QUERY).matches ? "light" : "dark";
 }
+
+// --- the live watcher ---------------------------------------------------------------
+
+/**
+ * The slice of `MediaQueryList` the watcher reads.
+ *
+ * Three members, so the platform's list satisfies it structurally and a fake
+ * is an object literal with a listener slot.
+ */
+export interface SchemeList {
+  readonly matches: boolean;
+  addEventListener(type: "change", listener: () => void): void;
+  removeEventListener(type: "change", listener: () => void): void;
+}
+
+/**
+ * Watch for an OS scheme flip, calling back with the resolved scheme.
+ *
+ * The stylesheet answers an OS flip on its own (the media query repaints
+ * without JavaScript), but the graph cannot: sigma's palette is fixed at
+ * renderer construction ("the scheme is fixed at construction" —
+ * `renderer.ts`), so the shell must learn about the flip to hand the column a
+ * new scheme and let it remount. This is that one listener.
+ *
+ * The returned `stop` removes the listener; the shell registers the watch in
+ * a mount effect, so a hot reload cannot stack listeners. A host without
+ * `matchMedia` gets a do-nothing cleanup — the same "legible, not throwing"
+ * answer `schemeOf` gives, because a graph in a stale palette beats a
+ * workspace that crashed on mount.
+ *
+ * A manual choice ("light" / "dark") ignores this callback entirely — the
+ * shell simply does not consult the OS while overridden, and the stylesheet's
+ * `:root[data-weave-theme=…]` attribute wins over the media query the same way.
+ */
+export function watchScheme(
+  host: SchemeHost,
+  onChange: (scheme: ColorScheme) => void,
+): () => void {
+  if (typeof host.matchMedia !== "function") return () => {};
+  const list: SchemeList = host.matchMedia(LIGHT_QUERY);
+  if (typeof list.addEventListener !== "function") return () => {};
+  const listener = (): void => onChange(list.matches ? "light" : "dark");
+  list.addEventListener("change", listener);
+  return () => list.removeEventListener("change", listener);
+}

package/src/web/client/main.tsx

@@ -15,6 +15,7 @@ import { BOOTSTRAP_ELEMENT_ID } from "../shared/wire";
 import { readBootstrap } from "./bootstrap";
 import { Shell } from "./shell/Shell";
 import { installTheme } from "./shell/theme";
+import { loadTheme, themeAttr } from "./shell/theme.model";
 
 const host = document.getElementById("app");
 if (host !== null) {
@@ -22,6 +23,17 @@ if (host !== null) {
   // installing it after would show one unstyled frame. It copies the
   // per-response CSP nonce off the server's own `<style>` — see `theme.ts`.
   installTheme(document);
+  // And before the first paint: a stored manual choice must govern from frame
+  // one, or a light-theme user sees one dark frame. `null` (system mode)
+  // writes nothing — the media query already answered.
+  applyPrePaintTheme();
   const boot = readBootstrap(document.getElementById(BOOTSTRAP_ELEMENT_ID)?.textContent ?? null);
   render(<Shell cwd={boot.cwd} initialWidth={window.innerWidth} platform={navigator.platform} />, host);
 }
+
+/** Apply the stored theme choice to `<html>` synchronously, pre-render. */
+function applyPrePaintTheme(): void {
+  const attr = themeAttr(loadTheme(localStorage) ?? "system");
+  if (attr === null) return;
+  document.documentElement.dataset.weaveTheme = attr;
+}

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

@@ -42,19 +42,26 @@ function Prompt({ prompt, send }: { prompt: EditorPrompt; send: (event: EditorEv
   );
 }
 
-/** The toolbar: edit/done, save, open-in-$EDITOR, and the status word. */
+/** The toolbar while editing: done, save, open-in-$EDITOR, and the status word.
+ *
+ * There is no button in read mode: the note itself is the edit affordance —
+ * clicking its text opens the editor (see `Note.tsx`), and `⌘E` still works.
+ * Rendering the button only while editing keeps the read view down to prose
+ * and the `Open in $EDITOR` control. */
 export function EditorBar(props: EditorProps) {
   const { toolbar, send } = props;
   return (
     <div class="weave-note-bar">
-      <button
-        type="button"
-        class="weave-note-toggle"
-        aria-pressed={toolbar.editing}
-        onClick={() => send({ type: "toggle" })}
-      >
-        {toolbar.toggleLabel}
-      </button>
+      {toolbar.editing ? (
+        <button
+          type="button"
+          class="weave-note-toggle"
+          aria-pressed={toolbar.editing}
+          onClick={() => send({ type: "toggle" })}
+        >
+          {toolbar.toggleLabel}
+        </button>
+      ) : null}
       {toolbar.editing ? (
         <button type="button" class="weave-note-save" disabled={!toolbar.canSave} onClick={() => send({ type: "save" })}>
           {toolbar.saveLabel}