pi-weave 0.3.0 → 0.3.2

package/src/web/client/tree/Tree.tsx

@@ -1,5 +1,6 @@
 /** The vault and repository tree column. */
 
+import { NOTE_DRAG_TYPE } from "../shell/shell.model";
 import { useLayoutEffect, useRef, useState } from "preact/hooks";
 import { createFolder, deleteFolder, deleteNote, moveNote, renameFolder, renameNote } from "../api";
 import { fetchJson } from "../api.dom";
@@ -20,7 +21,6 @@ import {
   deleteNeedsConfirmation,
   depthVar,
   dropFolder,
-  expand,
   initialTreeView,
   newFolderParent,
   newFolderPath,
@@ -33,6 +33,8 @@ import {
   rowCountLabel,
   rowViews,
   rowsFor,
+  revealFolder,
+  affectedNoteSlugs,
   setQuery,
   toggleExpanded,
   toggleInternals,
@@ -44,12 +46,12 @@ export interface TreeProps {
   graph: GraphPayload | null;
   selectedId: string | null;
   recentIds: ReadonlySet<string>;
-  onSelect: (id: string) => void;
+  onSelect: (id: string, newTab?: boolean, keepSidebar?: boolean) => void;
   /**
    * Ask before a mutation that would invalidate an open draft. `false` means
    * keep editing: the mutation must not run.
    */
-  onMutate: () => boolean;
+  onMutate: (slugs: readonly string[]) => boolean;
   onRefresh: () => void;
   now: number;
 }
@@ -74,7 +76,7 @@ export function Icon({ name, class: className }: { name: IconName; class?: strin
   );
 }
 
-function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMenu, onDrop }: { view: ReturnType<typeof rowViews>[number]; recentIds: ReadonlySet<string>; edit: string | null; onEdit: (value: string) => void; onRename: (value: string | null) => void; onSelect: () => void; onToggle: () => void; onMenu: (x: number, y: number) => void; onDrop: (id: string) => void }) {
+function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMenu, onDrop }: { view: ReturnType<typeof rowViews>[number]; recentIds: ReadonlySet<string>; edit: string | null; onEdit: (value: string) => void; onRename: (value: string | null) => void; onSelect: (newTab: boolean) => void; onToggle: () => void; onMenu: (x: number, y: number) => void; onDrop: (id: string) => void }) {
   const folder = dropFolder(view.id);
   return (
     <li
@@ -88,10 +90,10 @@ function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMe
       aria-selected={view.selected}
       aria-expanded={view.hasKids ? view.expanded : undefined}
       style={depthVar(view.depth)}
-      onClick={onSelect}
+      onClick={(event) => onSelect(event.metaKey || event.ctrlKey)}
       draggable={view.id.startsWith("note:")}
       aria-label={view.id === DRAFT_FOLDER_ID ? "New folder" : undefined}
-      onDragStart={(event) => event.dataTransfer?.setData("text/plain", view.id)}
+      onDragStart={(event) => { event.dataTransfer?.setData("text/plain", view.id); event.dataTransfer?.setData(NOTE_DRAG_TYPE, view.id); if (event.dataTransfer) event.dataTransfer.effectAllowed = "copyMove"; }}
       onDragOver={folder === undefined ? undefined : (event) => event.preventDefault()}
       onDrop={folder === undefined ? undefined : (event) => { event.preventDefault(); onDrop(event.dataTransfer?.getData("text/plain") ?? ""); }}
       onContextMenu={(event) => { event.preventDefault(); event.stopPropagation(); onMenu(event.clientX, event.clientY); }}
@@ -161,6 +163,14 @@ export function Tree(props: TreeProps) {
    * what makes a mis-click cheap.
    */
   const [menu, setMenu] = useState<{ id: string; label: string; x: number; y: number; armed?: boolean } | null>(null);
+  const root = useRef<HTMLDivElement | null>(null);
+  useLayoutEffect(() => {
+    if (menu !== null) root.current?.querySelector<HTMLButtonElement>(".weave-menu button")?.focus();
+  }, [menu?.id]);
+  const closeMenu = (): void => {
+    setMenu(null);
+    root.current?.querySelector<HTMLButtonElement>(".weave-tree-actions")?.focus();
+  };
   const [editing, setEditing] = useState<{ id: string; label: string; value: string } | null>(null);
   /**
    * The parent path a pending "New folder" will be created under, or `null`.
@@ -190,15 +200,16 @@ export function Tree(props: TreeProps) {
       // gesture `rename` already uses, and it shows *where* the folder will
       // land, which a prompt cannot.
       const parent = newFolderParent(target);
-      if (parent !== "") setState((current) => expand(current, `vfolder:${parent}`));
+      setState((current) => revealFolder(current, parent));
       setDraft(parent);
       setEditing({ id: DRAFT_FOLDER_ID, label: "", value: "" });
     } else if (action === "rename") {
+      setState((current) => revealFolder(current, target.path.split("/").slice(0, -1).join("/")));
       setEditing({ id: menu.id, label: menu.label, value: menu.label });
     } else if (target.type !== "vault") {
       // Before the request: asking after a delete is asking about a file that
       // is already gone, and "keep editing" would strand the draft on a 404.
-      if (deletesSelection(props.selectedId, target) && !props.onMutate()) return;
+      if (!props.onMutate(affectedNoteSlugs(props.graph, target))) return;
       await run(target.type === "note" ? deleteNote(fetchJson, target.path) : deleteFolder(fetchJson, target.path), deletesSelection(props.selectedId, target) ? "vault" : undefined);
     }
   };
@@ -247,24 +258,32 @@ export function Tree(props: TreeProps) {
     // is the least useful moment to ask. Renaming back is one more rename.
     // An open draft is a different question; `onMutate` asks that one.
     if (target !== null && name && name !== current.label) {
-      if (deletesSelection(props.selectedId, target) && !props.onMutate()) return;
+      if (!props.onMutate(affectedNoteSlugs(props.graph, target))) return;
       void run(target.type === "note" ? renameNote(fetchJson, target.path, name) : renameFolder(fetchJson, target.path, name));
     }
   };
 
   return (
-    <div class="weave-tree" onKeyDown={(event) => {
+    <div class="weave-tree" ref={root} onKeyDown={(event) => {
+      if (menu !== null && event.key === "Escape") {
+        event.preventDefault(); event.stopPropagation(); closeMenu(); return;
+      }
       const target = event.target as KeyTarget;
       const next = treeKey(rows, state, props.selectedId, event.key, isTextEntry(target?.tagName ?? null, target?.isContentEditable === true));
       if (!next.handled) return;
       event.preventDefault();
       setState(next.state);
-      if (next.selectedId !== null) props.onSelect(next.selectedId);
+      if (next.selectedId !== null) props.onSelect(next.selectedId, false, true);
     }}>
       <div class="weave-tree-controls">
         <input type="search" class="weave-filter" value={state.query} placeholder={FILTER_PLACEHOLDER} aria-label={FILTER_LABEL} title={FILTER_HINT} onInput={(event) => setState(setQuery(state, event.currentTarget.value))} />
         <button type="button" class="weave-chip" title={provenanceHint(state.provFilter)} onClick={() => setState(cycleProvenance(state))}>◧ {provenanceLabel(state.provFilter)}</button>
         <button type="button" class="weave-chip" title={internalsHint(state.showInternals)} onClick={() => setState(toggleInternals(state))}>◧ {internalsLabel(state.showInternals)}</button>
+        <button type="button" class="weave-chip weave-tree-actions" aria-label="File actions" title="File actions for the selected item" onClick={(event) => {
+          const id = props.selectedId !== null && mutableTreeRow(props.selectedId) !== null ? props.selectedId : "vault";
+          const at = event.currentTarget.getBoundingClientRect();
+          setMenu({ id, label: props.graph?.model.nodes.find((node) => node.id === id)?.label ?? "Vault", x: at.left, y: at.bottom });
+        }}>···</button>
       </div>
       {empty === null ? (
         <ul
@@ -278,7 +297,7 @@ export function Tree(props: TreeProps) {
             setMenu({ id: "vault", label: "Vault", x: event.clientX, y: event.clientY });
           }}
         >
-          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={commitEdit} onSelect={() => { props.onSelect(view.id); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) { if (dragged === props.selectedId && !props.onMutate()) return; void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); } }} />)}
+          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={commitEdit} onSelect={(newTab) => { props.onSelect(view.id, newTab); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) { const target = mutableTreeRow(dragged); if (target !== null && !props.onMutate(affectedNoteSlugs(props.graph, target))) return; void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); } }} />)}
         </ul>
       ) : <p class="weave-tree-empty">{empty}</p>}
       <p class="weave-tree-count">{rowCountLabel(rows)}</p>
@@ -286,8 +305,18 @@ export function Tree(props: TreeProps) {
         const target = mutableTreeRow(menu.id)!;
         return (
           <>
-            <button type="button" class="weave-menu-backdrop" aria-label="Close context menu" onClick={() => setMenu(null)} />
-            <div class="weave-menu" role="menu" style={{ left: `${menu.x}px`, top: `${menu.y}px` }}>
+            <button type="button" class="weave-menu-backdrop" aria-label="Close context menu" onClick={closeMenu} />
+            <div class="weave-menu" role="menu" style={{ left: `${menu.x}px`, top: `${menu.y}px` }} onKeyDown={(event) => {
+              if (event.key === "Escape") { event.preventDefault(); closeMenu(); }
+              else if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+                event.preventDefault();
+                const items = [...event.currentTarget.querySelectorAll<HTMLButtonElement>("button")];
+                const index = items.indexOf(document.activeElement as HTMLButtonElement);
+                const next = event.key === "Home" ? 0 : event.key === "End" ? items.length - 1 : (index + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+                items[next]?.focus();
+              }
+              event.stopPropagation();
+            }}>
               <button type="button" role="menuitem" onClick={() => void act("newFolder")}>New folder…</button>
               {target.type !== "vault" ? (
                 <>

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

@@ -74,6 +74,17 @@ export function initialTreeView(roots: readonly string[] = ["vault", "repository
   return { expanded: new Set(roots), showInternals: false, provFilter: null, query: "" };
 }
 
+/** Make an inline file operation visible even when its destination was filtered or collapsed. */
+export function revealFolder(state: TreeViewState, path: string): TreeViewState {
+  const expanded = new Set(state.expanded).add("vault");
+  let parent = "";
+  for (const part of path ? path.split("/") : []) {
+    parent = parent ? `${parent}/${part}` : part;
+    expanded.add(`vfolder:${parent}`);
+  }
+  return { ...state, expanded, query: "", provFilter: null };
+}
+
 // --- reassembling the wire payload -------------------------------------------------
 
 /**
@@ -224,6 +235,14 @@ export function mutableTreeRow(id: string): { type: "note" | "folder" | "vault";
   return null;
 }
 
+/** Note slugs a note or folder mutation can invalidate. */
+export function affectedNoteSlugs(graph: GraphPayload | null, target: { type: "note" | "folder" | "vault"; path: string }): string[] {
+  if (target.type === "note") return [target.path];
+  if (target.type !== "folder" || graph === null) return [];
+  const prefix = `note:${target.path}/`;
+  return graph.model.nodes.filter((node) => node.kind === "note" && node.id.startsWith(prefix)).map((node) => node.id.slice(5));
+}
+
 export function deletesSelection(selectedId: string | null, target: { type: "note" | "folder" | "vault"; path: string }): boolean {
   if (selectedId === null) return false;
   if (target.type === "note") return selectedId === `note:${target.path}`;

package/src/web/client/workspace.ts

@@ -1,6 +1,6 @@
 /** Fetching and polling for the browser workspace. */
 
-import type { GraphPayload } from "../shared/wire";
+import type { GraphPayload, NotePayload } from "../shared/wire";
 import type { ApiResult, FetchLike } from "./api";
 import { fetchGraph, fetchNote } from "./api";
 import type { WorkspaceState } from "./state";
@@ -115,3 +115,21 @@ export function startWorkspace(opts: WorkspaceOptions): WorkspaceHandle {
     },
   };
 }
+
+/** Per-document loading: retry failures, and drop completions after a tab leaves. */
+export function watchNote(fetch: FetchLike, slug: string, notify: (result: ApiResult<NotePayload>) => void,
+  defer: (fn: () => void, ms: number) => () => void = (fn, ms) => {
+    const timer = setTimeout(fn, ms); return () => clearTimeout(timer);
+  }): () => void {
+  let stopped = false;
+  let cancel: (() => void) | null = null;
+  const load = async (): Promise<void> => {
+    if (stopped) return;
+    const result = await fetchNote(fetch, slug);
+    if (stopped) return;
+    notify(result);
+    if (!result.ok) cancel = defer(() => void load(), POLL_MS);
+  };
+  void load();
+  return () => { stopped = true; cancel?.(); };
+}

package/src/web/server/backup.ts

@@ -0,0 +1,59 @@
+/** Create a complete archive before offering a download; originals are read only. */
+import { createReadStream } from "node:fs";
+import { mkdtemp, open, readdir, realpath, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Zip, ZipDeflate } from "fflate";
+
+export async function createVaultBackup(vaultRoot: string): Promise<{ path: string; dispose: () => Promise<void> }> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-weave-backup-"));
+  const path = join(directory, "vault.zip");
+  const dispose = (): Promise<void> => rm(directory, { recursive: true, force: true });
+  try {
+    const output = await open(path, "w");
+    try {
+      let pending = Promise.resolve();
+      let failure: Error | null = null;
+      let entries = 0;
+      const zip = new Zip((error, chunk) => {
+        if (error) { failure = error; return; }
+        pending = pending.then(() => output.writeFile(chunk));
+      });
+      const flush = async (): Promise<void> => { await pending; if (failure) throw failure; };
+      const walk = async (directory: string, prefix: string, ancestors: ReadonlySet<string>): Promise<void> => {
+        const resolved = await realpath(directory);
+        if (ancestors.has(resolved)) throw new Error(`Symbolic-link cycle in vault: ${prefix}`);
+        const next = new Set([...ancestors, resolved]);
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+          // ZIP readers on Windows treat backslashes as path separators.
+          if (entry.name.includes("\\")) throw new Error(`Unsupported backup filename: ${entry.name}`);
+          const source = join(directory, entry.name);
+          const info = await stat(source);
+          const name = prefix + entry.name + (info.isDirectory() ? "/" : "");
+          if (!info.isDirectory() && !info.isFile()) throw new Error(`Unsupported vault entry: ${name}`);
+          if (++entries > 65535 || info.isFile() && info.size > 0xffffffff) throw new Error("Vault exceeds ZIP format limits");
+          const file = new ZipDeflate(name, { level: 1 });
+          file.mtime = new Date(Math.max(new Date(1980, 0, 1).getTime(), Math.min(new Date(2099, 11, 31).getTime(), info.mtime.getTime())));
+          zip.add(file);
+          await flush();
+          if (info.isDirectory()) {
+            file.push(new Uint8Array(), true);
+            await flush();
+            await walk(source, name, next);
+          } else {
+            for await (const chunk of createReadStream(source)) {
+              file.push(chunk as Uint8Array);
+              await flush();
+            }
+            file.push(new Uint8Array(), true);
+            await flush();
+          }
+        }
+      };
+      await walk(vaultRoot, "", new Set());
+      zip.end();
+      await flush();
+    } finally { await output.close(); }
+    return { path, dispose };
+  } catch (error) { await dispose(); throw error; }
+}

package/src/web/server/routes.ts

@@ -43,7 +43,10 @@
  * `resolveNotePath` (via `getNote`) rejects unsafe slugs.
  */
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { createVaultBackup } from "./backup";
 import { readFile } from "node:fs/promises";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { WorkspaceSnapshot } from "../../core/cache/workspace";
@@ -65,6 +68,8 @@ import type {
 } from "../shared/wire";
 import { WIRE_MODEL_OMITTED_KEYS } from "../shared/wire";
 import { renderPage } from "./page";
+import { isWorkspaceViewId, type WorkspaceStateStore } from "./workspace-state";
+import { parseWorkspaceLayout } from "../shared/workspace";
 import type { RequestFacts, SecurityPolicy } from "./security";
 import { requestFacts } from "./security";
 
@@ -78,6 +83,7 @@ export interface RouteDeps {
   bundlePath: string;
   /** Test seam for `POST /api/open`; defaults to the real editor shell-out. */
   openNote?: ((slug: string) => Promise<boolean>) | undefined;
+  workspaceState: WorkspaceStateStore;
 }
 
 const JSON_TYPE = "application/json; charset=utf-8";
@@ -160,8 +166,9 @@ export function parseTarget(url: string): Target {
  * the caller has exactly one failure branch.
  */
 export const MAX_BODY_BYTES = 64 * 1024;
+const MAX_WORKSPACE_STATE_BODY_BYTES = 256 * 1024;
 
-export async function readJsonBody(req: IncomingMessage): Promise<unknown | null> {
+export async function readJsonBody(req: IncomingMessage, maxBytes = MAX_BODY_BYTES): Promise<unknown | null> {
   const chunks: Buffer[] = [];
   let size = 0;
   // `IncomingMessage` yields Buffers unless `setEncoding` was called, and we
@@ -169,7 +176,7 @@ export async function readJsonBody(req: IncomingMessage): Promise<unknown | null
   // pretending to be defensive.
   for await (const chunk of req as AsyncIterable<Buffer>) {
     size += chunk.length;
-    if (size > MAX_BODY_BYTES) return null;
+    if (size > maxBytes) return null;
     chunks.push(chunk);
   }
   if (chunks.length === 0) return null;
@@ -375,6 +382,18 @@ async function route(
   if (method === "GET" && path === "/") return sendShell(deps, res);
   if (method === "GET" && path === "/app.js") return sendBundle(deps, res);
   if (method === "GET" && path === "/api/graph") return sendGraph(deps, req, res);
+  if (method === "GET" && path === "/api/backup") {
+    const backup = await createVaultBackup(deps.vaultRoot);
+    try {
+      res.writeHead(200, { ...baseHeaders(), "content-type": "application/zip", "content-disposition": `attachment; filename="weave-vault-${new Date().toISOString().slice(0, 10)}.zip"`, "cache-control": "no-store" });
+      await pipeline(createReadStream(backup.path), res);
+    } finally { await backup.dispose(); }
+    return;
+  }
+  if (method === "GET" && path === "/api/workspace-state") {
+    return sendJson(res, 200, { viewId: randomUUID(), layout: await deps.workspaceState.readLatest(), info: { vaultRoot: deps.vaultRoot, version: (JSON.parse(await readFile(new URL("../../../package.json", import.meta.url), "utf8")) as { version: string }).version } }, { "cache-control": "no-store" });
+  }
+  if (method === "POST" && path === "/api/workspace-state") return saveWorkspaceState(deps, req, res);
   if (path.startsWith("/api/folder/")) {
     const handled = await routeFolder(deps, method, path.slice("/api/folder/".length), req, res);
     if (handled) return;
@@ -396,6 +415,29 @@ async function route(
 
 // --- handlers ----------------------------------------------------------------
 
+async function saveWorkspaceState(deps: RouteDeps, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const body = await readJsonBody(req, MAX_WORKSPACE_STATE_BODY_BYTES);
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    sendJson(res, 400, { error: "Expected a workspace state object" });
+    return;
+  }
+  const record = body as Record<string, unknown>;
+  if (
+    Object.keys(record).length !== 2 || !Object.hasOwn(record, "viewId") || !Object.hasOwn(record, "layout") ||
+    !isWorkspaceViewId(record.viewId)
+  ) {
+    sendJson(res, 400, { error: "Expected a UUID viewId and a valid layout" });
+    return;
+  }
+  const layout = parseWorkspaceLayout(record.layout);
+  if (layout === null) {
+    sendJson(res, 400, { error: "Invalid workspace layout" });
+    return;
+  }
+  await deps.workspaceState.write(record.viewId, layout);
+  sendJson(res, 200, { ok: true }, { "cache-control": "no-store" });
+}
+
 function sendShell(deps: RouteDeps, res: ServerResponse): void {
   const page = renderPage({
     bootstrap: { cwd: deps.cwd },

package/src/web/server/server.ts

@@ -19,6 +19,7 @@ import { WorkspaceCache } from "../../core/cache/workspace";
 import { resolveVaultRoot } from "../../core/paths";
 import { handleRequest, type RouteDeps } from "./routes";
 import { createSecurityPolicy, type SecurityPolicy } from "./security";
+import { createWorkspaceStateStore, defaultWorkspaceStateDir } from "./workspace-state";
 
 /**
  * The committed bundle, resolved relative to this module rather than to
@@ -41,6 +42,8 @@ export interface StartWorkspaceServerOptions {
   cookieName?: string | undefined;
   /** Absolute path to the client bundle. Defaults to the committed one. */
   bundlePath?: string | undefined;
+  /** Presentation snapshot directory. Defaults to the user's pi-weave config directory. */
+  presentationStateDir?: string | undefined;
   /** Test seam for `POST /api/open`. */
   openNote?: ((slug: string) => Promise<boolean>) | undefined;
 }
@@ -61,6 +64,7 @@ export interface WorkspaceServer {
 export async function startWorkspaceServer(opts: StartWorkspaceServerOptions): Promise<WorkspaceServer> {
   const vaultRoot = opts.vaultRoot ?? resolveVaultRoot();
   const cache = opts.cache ?? new WorkspaceCache({ cwd: opts.cwd, vaultRoot });
+  const workspaceState = await createWorkspaceStateStore(opts.cwd, vaultRoot, opts.presentationStateDir ?? defaultWorkspaceStateDir());
   // `deps` is assembled before `listen` because the request handler closes
   // over it, but the security policy needs the bound port — so the policy
   // slot is filled after binding and the handler reads it through the
@@ -104,6 +108,7 @@ export async function startWorkspaceServer(opts: StartWorkspaceServerOptions): P
     security,
     bundlePath: opts.bundlePath ?? defaultBundlePath(),
     ...(opts.openNote !== undefined ? { openNote: opts.openNote } : {}),
+    workspaceState,
   };
 
   return {

package/src/web/server/workspace-state.ts

@@ -0,0 +1,121 @@
+import { createHash, randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { findGitRoot } from "../../core/git";
+import { withMutationQueue } from "../../core/mutex";
+import { parseWorkspaceLayout, type WorkspaceLayout } from "../shared/workspace";
+
+const MAX_SNAPSHOTS = 8;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isWorkspaceViewId(value: unknown): value is string {
+  return typeof value === "string" && UUID.test(value);
+}
+
+interface Snapshot {
+  viewId: string;
+  savedAt: number;
+  layout: WorkspaceLayout;
+}
+
+interface SnapshotFile {
+  version: 1;
+  viewId: string;
+  layout: WorkspaceLayout;
+}
+
+export interface WorkspaceStateStore {
+  readLatest(): Promise<WorkspaceLayout | null>;
+  write(viewId: string, layout: WorkspaceLayout): Promise<void>;
+}
+
+export function defaultWorkspaceStateDir(): string {
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "pi-weave", "presentation");
+}
+
+export function createWorkspaceStateStore(
+  cwd: string,
+  vaultRoot: string,
+  stateDir = defaultWorkspaceStateDir(),
+): WorkspaceStateStore {
+  let directoryPromise: Promise<string> | null = null;
+  const directory = (): Promise<string> => {
+    directoryPromise ??= (async () => {
+      const [vault, repo] = await Promise.all([canonical(vaultRoot), findGitRoot(cwd)]);
+      const workspaceRoot = await canonical(repo ?? cwd);
+      const id = createHash("sha256").update(JSON.stringify([vault, workspaceRoot])).digest("hex");
+      return join(stateDir, id);
+    })();
+    return directoryPromise;
+  };
+
+  return {
+    async readLatest() {
+      return (await readSnapshots(await directory()))[0]?.layout ?? null;
+    },
+    async write(viewId, layout) {
+      if (!isWorkspaceViewId(viewId)) throw new Error("viewId must be a UUID");
+      const dir = await directory();
+      const file = join(dir, `${viewId}.json`);
+      await withMutationQueue(file, async () => {
+        await writeSnapshot(dir, file, { version: 1, viewId, layout });
+      });
+    },
+  };
+}
+
+async function canonical(path: string): Promise<string> {
+  const absolute = resolve(path);
+  try {
+    return await fs.realpath(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+async function readSnapshots(directory: string): Promise<Snapshot[]> {
+  let names: string[];
+  try {
+    names = await fs.readdir(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  const snapshots = await Promise.all(names.filter((name) => UUID.test(name.slice(0, -5)) && name.endsWith(".json")).map(async (name) => {
+    const file = join(directory, name);
+    try {
+      const [text, info] = await Promise.all([fs.readFile(file, "utf8"), fs.stat(file)]);
+      const raw = JSON.parse(text) as SnapshotFile;
+      const layout = raw.version === 1 && raw.viewId === name.slice(0, -5) ? parseWorkspaceLayout(raw.layout) : null;
+      return layout ? { viewId: raw.viewId, savedAt: info.mtimeMs, layout } : null;
+    } catch {
+      return null;
+    }
+  }));
+  return snapshots.filter((item): item is Snapshot => item !== null).sort((a, b) => b.savedAt - a.savedAt).slice(0, MAX_SNAPSHOTS);
+}
+
+async function writeSnapshot(directory: string, file: string, state: SnapshotFile): Promise<void> {
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(state), { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, file);
+    const entries = await Promise.all((await fs.readdir(directory)).filter((name) => name.endsWith(".json")).map(async (name) => {
+      const path = join(directory, name);
+      try {
+        return { path, mtime: (await fs.stat(path)).mtimeMs };
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+      }
+    }));
+    const existing = entries.filter((entry): entry is NonNullable<typeof entry> => entry !== null);
+    existing.sort((a, b) => b.mtime - a.mtime);
+    await Promise.all(existing.slice(MAX_SNAPSHOTS).map(({ path }) => fs.rm(path, { force: true })));
+  } catch (error) {
+    await fs.rm(temporary, { force: true });
+    throw error;
+  }
+}

package/src/web/shared/layout.ts

@@ -41,14 +41,13 @@ const ALPHA_MIN = 0.001;
  * Mutable because picking these numbers is an act of taste, not of
  * derivation: the difference between "one hairball" and "legible groups" is a
  * ratio between containment cohesion, charge and centre gravity that is far
- * easier to *see* than to reason about. The hidden tuner (`?sliders=1`, see
- * `client/graph/tuner.model.ts` and docs/weave-workspace.md §15.7) writes here
- * and re-lays out live, so a human can find the values by eye and they then
+ * easier to *see* than to reason about. The settings sliders (see
+ * `client/graph/tuner.model.ts` and docs/weave-workspace.md §15.7) update this record
+ * and re-run the layout live, so a human can find the values by eye and they then
  * get frozen back into {@link FORCE_DEFAULTS}.
  *
- * Determinism is untouched: every production and test path only ever *reads*
- * this, so `computeLayout(model, { seed })` stays byte-identical. The tuner is
- * the one writer, and it is unreachable without the query flag.
+ * `computeLayout(model, { seed })` stays deterministic for a given set of forces.
+ * Settings are the production writer of this record.
  *
  * ponytail: module-level mutable state, fine at one graph per page — thread it
  * as a `LayoutOptions` field if a second concurrent consumer ever appears.

package/src/web/shared/preferences.ts

@@ -0,0 +1,76 @@
+/** Validated preferences, stored alongside the workspace's existing snapshots. */
+import { FORCE_DEFAULTS } from "./layout";
+import type { ForceConstants } from "./layout";
+import { ACCENTS, THEMES, isThemeChoice } from "./themes";
+import type { AccentChoice, PaletteChoice } from "./themes";
+
+/** One slider: which constant it drives, and the range it may drive it over. */
+export interface SliderSpec {
+  readonly key: keyof ForceConstants;
+  readonly label: string;
+  /** One line under the label saying what moving it does. */
+  readonly hint: string;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}
+
+/** Graph forces, ordered from group cohesion to repulsion and centering. */
+export const FORCE_SLIDERS: readonly SliderSpec[] = [
+  { key: "containsStrength", label: "Group cohesion", hint: "how hard a parent holds its children — group cohesion", min: 0, max: 1, step: 0.01 },
+  { key: "containsRest", label: "Group radius", hint: "how far children sit from their parent — rosette radius", min: 10, max: 300, step: 5 },
+  { key: "relationStrength", label: "Link strength", hint: "pull of links-to / mentions across groups", min: 0, max: 1, step: 0.01 },
+  { key: "relationDistance", label: "Link distance", hint: "how long those cross-group springs are", min: 20, max: 600, step: 10 },
+  { key: "charge", label: "Repulsion", hint: "node-to-node repulsion — more negative pushes harder", min: -1200, max: 0, step: 10 },
+  { key: "chargeMax", label: "Repulsion range", hint: "distance past which repulsion stops — caps overall spread", min: 100, max: 4000, step: 50 },
+  { key: "center", label: "Center gravity", hint: "pull toward the origin — too much makes one blob", min: 0, max: 0.3, step: 0.005 },
+];
+
+
+export interface Preferences {
+  readonly lightTheme: PaletteChoice;
+  readonly darkTheme: PaletteChoice;
+  readonly accent: AccentChoice;
+  readonly fontSize: number;
+  readonly readable: boolean;
+  readonly spellcheck: boolean;
+  readonly defaultEdit: boolean;
+  readonly startup: "restore" | "empty";
+  readonly focusNewTabs: boolean;
+  readonly groupColors: boolean;
+  readonly forces: ForceConstants;
+}
+
+export const DEFAULT_PREFERENCES: Preferences = {
+  lightTheme: "light", darkTheme: "dark", accent: "theme", fontSize: 14, readable: true, spellcheck: true, defaultEdit: false,
+  startup: "restore", focusNewTabs: true, groupColors: true, forces: { ...FORCE_DEFAULTS },
+};
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parsePreferences(input: unknown): Preferences | null {
+  if (!record(input)) return null;
+  const legacy = !Object.hasOwn(input, "lightTheme") && !Object.hasOwn(input, "darkTheme");
+  const value = legacy ? { ...input, lightTheme: "light", darkTheme: "dark" } : input;
+  if (Object.keys(value).length !== Object.keys(DEFAULT_PREFERENCES).length) return null;
+  for (const scheme of ["light", "dark"] as const) {
+    const theme = value[`${scheme}Theme`];
+    if (!isThemeChoice(theme) || theme === "system" || THEMES[theme].scheme !== scheme) return null;
+  }
+  if (value["accent"] !== "theme" && (typeof value["accent"] !== "string" || !Object.hasOwn(ACCENTS, value["accent"]))) return null;
+  if (typeof value["fontSize"] !== "number" || !Number.isInteger(value["fontSize"]) || value["fontSize"] < 12 || value["fontSize"] > 22) return null;
+  for (const key of ["readable", "spellcheck", "defaultEdit", "focusNewTabs", "groupColors"] as const) {
+    if (typeof value[key] !== "boolean") return null;
+  }
+  if (value["startup"] !== "restore" && value["startup"] !== "empty") return null;
+  const forces = value["forces"];
+  if (!record(forces) || Object.keys(forces).length !== FORCE_SLIDERS.length) return null;
+  for (const { key, min, max } of FORCE_SLIDERS) {
+    const force = forces[key];
+    if (typeof force !== "number" || !Number.isFinite(force) || force < min || force > max) return null;
+  }
+  return value as unknown as Preferences;
+}
+