pi-weave 0.3.1 → 0.3.3

package/src/web/server/routes.ts

@@ -44,6 +44,9 @@
  */
 
 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";
@@ -379,8 +382,16 @@ 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() }, { "cache-control": "no-store" });
+    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/")) {

package/src/web/shared/forces.ts

@@ -0,0 +1,70 @@
+/** Graph force settings shared without loading the d3 simulation. */
+
+/**
+ * The force constants, as one **mutable** record.
+ *
+ * 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 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}.
+ *
+ * `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.
+ */
+export interface ForceConstants {
+  /** Rest length of a `contains` / `anchored-at` spring: a rosette's radius. */
+  containsRest: number;
+  /** Stiffness of that spring. This is what makes a group *be* a group. */
+  containsStrength: number;
+  /** Rest length of a `links-to` / `mentions` spring: the inter-group reach. */
+  relationDistance: number;
+  /** Stiffness of that spring. Weak, so associations bend without merging. */
+  relationStrength: number;
+  /** `forceManyBody` strength. Negative is repulsion. */
+  charge: number;
+  /**
+   * Distance past which charge is ignored (`forceManyBody.distanceMax`).
+   *
+   * A cap rather than `Infinity` is what keeps a strong charge from simply
+   * inflating the whole graph uniformly: beyond it, neighbours stop pushing
+   * and only the springs and centre gravity speak, so groups separate at
+   * local scale without the picture growing without bound.
+   */
+  chargeMax: number;
+  /** `forceX`/`forceY` pull toward the origin. The no-escape guarantee. */
+  center: number;
+}
+
+/**
+ * The live constants. See {@link ForceConstants} for why this is mutable.
+ *
+ * These values were **found by eye** through the `?sliders=1` tuner and then
+ * frozen here, which is the loop §15.7 describes working as intended. They are
+ * not derived and should not be "corrected" toward rounder numbers: the
+ * previous set (`containsStrength: 0.02`, `charge: -50`, `center: 0.09`) was
+ * defensible on paper and produced a single hairball on screen.
+ */
+export const FORCES: ForceConstants = {
+  containsRest: 55,
+  containsStrength: 0.12,
+  relationDistance: 50,
+  relationStrength: 0.07,
+  charge: -200,
+  chargeMax: 800,
+  center: 0.05,
+};
+
+/** The shipped values, for the tuner's reset and for a test to restore from. */
+export const FORCE_DEFAULTS: Readonly<ForceConstants> = { ...FORCES };
+
+/** Overwrite the live constants in place. The tuner's one write. */
+export function setForces(next: Partial<ForceConstants>): void {
+  Object.assign(FORCES, next);
+}
+

package/src/web/shared/layout.ts

@@ -4,6 +4,10 @@ import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY
 import type { Simulation, SimulationNodeDatum } from "d3-force";
 import type { WireEdgeKind as EdgeKind, WireGraphEdge as GraphEdge, WireGraphModel as GraphModel } from "./graph";
 import type { Point } from "./metrics";
+import { FORCES } from "./forces";
+
+export { FORCES, FORCE_DEFAULTS, setForces } from "./forces";
+export type { ForceConstants } from "./forces";
 
 export type { Point } from "./metrics";
 
@@ -35,75 +39,6 @@ const DEFAULT_TICKS = 300;
 const DEFAULT_SEED = 1;
 const ALPHA_MIN = 0.001;
 
-/**
- * The force constants, as one **mutable** record.
- *
- * 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
- * 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.
- *
- * ponytail: module-level mutable state, fine at one graph per page — thread it
- * as a `LayoutOptions` field if a second concurrent consumer ever appears.
- */
-export interface ForceConstants {
-  /** Rest length of a `contains` / `anchored-at` spring: a rosette's radius. */
-  containsRest: number;
-  /** Stiffness of that spring. This is what makes a group *be* a group. */
-  containsStrength: number;
-  /** Rest length of a `links-to` / `mentions` spring: the inter-group reach. */
-  relationDistance: number;
-  /** Stiffness of that spring. Weak, so associations bend without merging. */
-  relationStrength: number;
-  /** `forceManyBody` strength. Negative is repulsion. */
-  charge: number;
-  /**
-   * Distance past which charge is ignored (`forceManyBody.distanceMax`).
-   *
-   * A cap rather than `Infinity` is what keeps a strong charge from simply
-   * inflating the whole graph uniformly: beyond it, neighbours stop pushing
-   * and only the springs and centre gravity speak, so groups separate at
-   * local scale without the picture growing without bound.
-   */
-  chargeMax: number;
-  /** `forceX`/`forceY` pull toward the origin. The no-escape guarantee. */
-  center: number;
-}
-
-/**
- * The live constants. See {@link ForceConstants} for why this is mutable.
- *
- * These values were **found by eye** through the `?sliders=1` tuner and then
- * frozen here, which is the loop §15.7 describes working as intended. They are
- * not derived and should not be "corrected" toward rounder numbers: the
- * previous set (`containsStrength: 0.02`, `charge: -50`, `center: 0.09`) was
- * defensible on paper and produced a single hairball on screen.
- */
-export const FORCES: ForceConstants = {
-  containsRest: 55,
-  containsStrength: 0.12,
-  relationDistance: 50,
-  relationStrength: 0.07,
-  charge: -200,
-  chargeMax: 800,
-  center: 0.05,
-};
-
-/** The shipped values, for the tuner's reset and for a test to restore from. */
-export const FORCE_DEFAULTS: Readonly<ForceConstants> = { ...FORCES };
-
-/** Overwrite the live constants in place. The tuner's one write. */
-export function setForces(next: Partial<ForceConstants>): void {
-  Object.assign(FORCES, next);
-}
-
 export function isContainment(kind: EdgeKind): boolean {
   return kind === "contains" || kind === "anchored-at";
 }

package/src/web/shared/preferences.ts

@@ -0,0 +1,76 @@
+/** Validated preferences, stored alongside the workspace's existing snapshots. */
+import { FORCE_DEFAULTS } from "./forces";
+import type { ForceConstants } from "./forces";
+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;
+}
+

package/src/web/shared/themes.ts

@@ -0,0 +1,92 @@
+/** Theme candidates. Catppuccin colors: https://github.com/catppuccin/palette (MIT).
+ * Latte colors are deepened and Frappé red lifted for contrast on raised controls.
+ * `light` and `dark` keep existing saved choices compatible.
+ */
+const latte = {
+  bg: "#eff1f5", panel: "#e6e9ef", page: "#dce0e8", raise: "#ccd0da",
+  fg: "#4c4f69", dim: "#56586a", faint: "#606274", line: "#ccd0da", "line-strong": "#bcc0cc",
+  accent: "#7113ec", ok: "#28641b", warn: "#7c4f10", bad: "#b20d30",
+};
+const macchiato = {
+  bg: "#24273a", panel: "#1e2030", page: "#181926", raise: "#363a4f",
+  fg: "#cad3f5", dim: "#a5adcb", faint: "#939ab7", line: "#363a4f", "line-strong": "#494d64",
+  accent: "#c6a0f6", ok: "#a6da95", warn: "#eed49f", bad: "#ed8796",
+};
+
+/** One table drives CSS, WebGL and the appearance theme choices. */
+export const THEMES = {
+  light: { name: "Catppuccin Latte · Mauve", scheme: "light", colors: latte },
+  "latte-blue": { name: "Catppuccin Latte · Blue", scheme: "light", colors: { ...latte, accent: "#1750bf" } },
+  "frappe-teal": { name: "Catppuccin Frappé · Teal", scheme: "dark", colors: {
+    bg: "#303446", panel: "#292c3c", page: "#232634", raise: "#414559",
+    fg: "#c6d0f5", dim: "#b5bfe2", faint: "#a5adce", line: "#414559", "line-strong": "#51576d",
+    accent: "#81c8be", ok: "#a6d189", warn: "#e5c890", bad: "#f4a4a6",
+  } },
+  dark: { name: "Catppuccin Macchiato · Mauve", scheme: "dark", colors: macchiato },
+  "macchiato-peach": { name: "Catppuccin Macchiato · Peach", scheme: "dark", colors: { ...macchiato, accent: "#f5a97f" } },
+  "mocha-lavender": { name: "Catppuccin Mocha · Lavender", scheme: "dark", colors: {
+    bg: "#1e1e2e", panel: "#181825", page: "#11111b", raise: "#313244",
+    fg: "#cdd6f4", dim: "#a6adc8", faint: "#9399b2", line: "#313244", "line-strong": "#45475a",
+    accent: "#b4befe", ok: "#a6e3a1", warn: "#f9e2af", bad: "#f38ba8",
+  } },
+  "paper-blue": { name: "Paper · Blue", scheme: "light", colors: {
+    bg: "#f4f6f8", panel: "#e9edf2", page: "#ffffff", raise: "#dce3eb",
+    fg: "#182334", dim: "#42536a", faint: "#526176", line: "#dce3eb", "line-strong": "#bac6d4",
+    accent: "#174ea6", ok: "#21623b", warn: "#805300", bad: "#a3223c",
+  } },
+  "ink-blue": { name: "Ink · Blue", scheme: "dark", colors: {
+    bg: "#1b2430", panel: "#141c27", page: "#101720", raise: "#2b3748",
+    fg: "#edf2f8", dim: "#becadc", faint: "#a5b5cb", line: "#2b3748", "line-strong": "#46566d",
+    accent: "#8bbcff", ok: "#91d5a5", warn: "#edc47b", bad: "#ff9fae",
+  } },
+  "sand-amber": { name: "Sand · Amber", scheme: "light", colors: {
+    bg: "#f7f3ec", panel: "#ede6da", page: "#fffdf8", raise: "#e2d8c8",
+    fg: "#30291f", dim: "#5b4e3f", faint: "#675847", line: "#e2d8c8", "line-strong": "#c7b8a2",
+    accent: "#814500", ok: "#365c2a", warn: "#795000", bad: "#a12c32",
+  } },
+  "ember-amber": { name: "Ember · Amber", scheme: "dark", colors: {
+    bg: "#29231f", panel: "#211c19", page: "#191512", raise: "#3c322b",
+    fg: "#f3e9dc", dim: "#d0bfab", faint: "#bfa991", line: "#3c322b", "line-strong": "#5c4d40",
+    accent: "#edb96b", ok: "#b5cf8a", warn: "#efc57a", bad: "#f69a91",
+  } },
+  "mist-teal": { name: "Mist · Teal", scheme: "light", colors: {
+    bg: "#eff5f3", panel: "#e1ece8", page: "#fafffd", raise: "#d2e2dc",
+    fg: "#18342e", dim: "#3c5b52", faint: "#48655b", line: "#d2e2dc", "line-strong": "#acc5bc",
+    accent: "#006457", ok: "#2a5e35", warn: "#795300", bad: "#a52a43",
+  } },
+  "forest-teal": { name: "Forest · Teal", scheme: "dark", colors: {
+    bg: "#1c2b27", panel: "#16221e", page: "#101b17", raise: "#2b4038",
+    fg: "#e6f2ec", dim: "#b8d0c4", faint: "#a2bfb0", line: "#2b4038", "line-strong": "#456255",
+    accent: "#7cd8bb", ok: "#a5d6a0", warn: "#e6c582", bad: "#f5a2ac",
+  } },
+} as const;
+
+export type PaletteChoice = keyof typeof THEMES;
+export type ThemeChoice = "system" | PaletteChoice;
+export const THEME_CHOICES: readonly ThemeChoice[] = ["system", ...Object.keys(THEMES) as PaletteChoice[]];
+
+export function isThemeChoice(value: unknown): value is ThemeChoice {
+  return typeof value === "string" && THEME_CHOICES.includes(value as ThemeChoice);
+}
+
+/** Accent selection is independent of the theme's surface palette. */
+export const ACCENTS = {
+  mauve: { name: "Mauve", light: "#7113ec", dark: "#cba9f8" },
+  blue: { name: "Blue", light: "#1750bf", dark: "#8bbcff" },
+  teal: { name: "Teal", light: "#006457", dark: "#7cd8bb" },
+  peach: { name: "Peach", light: "#814500", dark: "#f5a97f" },
+  rose: { name: "Rose", light: "#a52a43", dark: "#f4a4a6" },
+  green: { name: "Green", light: "#28641b", dark: "#a6da95" },
+  amber: { name: "Amber", light: "#775000", dark: "#edb96b" },
+  lavender: { name: "Lavender", light: "#445198", dark: "#b4befe" },
+} as const;
+export type AccentChoice = "theme" | keyof typeof ACCENTS;
+export type GraphTheme = PaletteChoice | { theme: PaletteChoice; accent: AccentChoice };
+
+export function themeId(theme: GraphTheme): PaletteChoice {
+  return typeof theme === "string" ? theme : theme.theme;
+}
+
+export function accentColor(theme: PaletteChoice, accent: AccentChoice): string {
+  return accent === "theme" ? THEMES[theme].colors.accent : ACCENTS[accent][THEMES[theme].scheme];
+}

package/src/web/shared/workspace.ts

@@ -1,4 +1,8 @@
 /** Serializable tab and pane state shared by the browser and persistence API. */
+import { isThemeChoice, THEMES } from "./themes";
+import type { ThemeChoice } from "./themes";
+import { DEFAULT_PREFERENCES, parsePreferences } from "./preferences";
+import type { Preferences } from "./preferences";
 
 export interface WorkspaceTab {
   readonly id: string;
@@ -25,7 +29,8 @@ export interface WorkspaceLayout {
   readonly contextVisible: boolean;
   readonly treeWidth: number;
   readonly contextWidth: number;
-  readonly theme: "system" | "light" | "dark";
+  readonly theme: ThemeChoice;
+  readonly preferences: Preferences;
 }
 
 const MAX_TABS = 40;
@@ -46,6 +51,7 @@ export function initialLayout(): WorkspaceLayout {
     treeWidth: 240,
     contextWidth: 240,
     theme: "system",
+    preferences: DEFAULT_PREFERENCES,
   };
 }
 
@@ -193,6 +199,16 @@ export function closePane(layout: WorkspaceLayout, paneId: string): WorkspaceLay
   return { ...layout, panes: [{ ...kept, tabs: [...kept.tabs, ...closed.tabs] }], activePane: kept.id };
 }
 
+/** Move a tab before another tab, or to the end, without changing its identity or selection. */
+export function reorderTab(layout: WorkspaceLayout, paneId: string, tabId: string, before: string | null): WorkspaceLayout {
+  const found = findTab(layout, paneId, tabId);
+  if (!found || before === tabId || before !== null && !found.pane.tabs.some((tab) => tab.id === before)) return layout;
+  const tabs = found.pane.tabs.filter((tab) => tab.id !== tabId);
+  tabs.splice(before === null ? tabs.length : tabs.findIndex((tab) => tab.id === before), 0, found.tab);
+  if (tabs.every((tab, index) => tab === found.pane.tabs[index])) return layout;
+  return { ...layout, panes: layout.panes.map((pane) => pane.id === paneId ? { ...pane, tabs } : pane) };
+}
+
 /** Accept a tab drop only in another existing pane. */
 export function tabDropSource(layout: WorkspaceLayout, targetPane: string, tabId: string | null): string | null {
   if (!layout.panes.some((pane) => pane.id === targetPane)) return null;
@@ -230,14 +246,20 @@ function boundedId(value: unknown, prefix?: "pane" | "tab"): value is string {
 }
 
 export function parseWorkspaceLayout(value: unknown): WorkspaceLayout | null {
-  if (!record(value) || !exactKeys(value, ["version", "panes", "activePane", "split", "ratio", "treeVisible", "contextVisible", "treeWidth", "contextWidth", "theme"])) return null;
+  if (!record(value) || !exactKeys(value, ["version", "panes", "activePane", "split", "ratio", "treeVisible", "contextVisible", "treeWidth", "contextWidth", "theme", ...(Object.hasOwn(value, "preferences") ? ["preferences"] : [])])) return null;
   if (value["version"] !== 1 || !Array.isArray(value["panes"]) || value["panes"].length < 1 || value["panes"].length > 2 || !boundedId(value["activePane"], "pane")) return null;
   if (value["split"] !== "right" && value["split"] !== "down") return null;
   if (typeof value["ratio"] !== "number" || !Number.isFinite(value["ratio"]) || value["ratio"] < 0.1 || value["ratio"] > 0.9) return null;
   if (typeof value["treeVisible"] !== "boolean" || typeof value["contextVisible"] !== "boolean") return null;
   if (typeof value["treeWidth"] !== "number" || !Number.isFinite(value["treeWidth"]) || value["treeWidth"] < 120 || value["treeWidth"] > 800) return null;
   if (typeof value["contextWidth"] !== "number" || !Number.isFinite(value["contextWidth"]) || value["contextWidth"] < 120 || value["contextWidth"] > 800) return null;
-  if (value["theme"] !== "system" && value["theme"] !== "light" && value["theme"] !== "dark") return null;
+  if (!isThemeChoice(value["theme"])) return null;
+  let preferences = Object.hasOwn(value, "preferences") ? parsePreferences(value["preferences"]) : DEFAULT_PREFERENCES;
+  if (preferences === null) return null;
+  const previousPreferences = value["preferences"];
+  if (value["theme"] !== "system" && (!record(previousPreferences) || !Object.hasOwn(previousPreferences, "lightTheme"))) {
+    preferences = { ...preferences, [`${THEMES[value["theme"]].scheme}Theme`]: value["theme"] };
+  }
   const ids = new Set<string>();
   let count = 0;
   let graphs = 0;
@@ -266,5 +288,23 @@ export function parseWorkspaceLayout(value: unknown): WorkspaceLayout | null {
     panes.push({ id: rawPane["id"], tabs, activeTab: rawPane["activeTab"], ...(typeof lastDocumentTab === "string" ? { lastDocumentTab } : {}) });
   }
   if (count > MAX_TABS || graphs > 1 || !panes.some((pane) => pane.id === value["activePane"])) return null;
-  return { version: 1, panes, activePane: value["activePane"], split: value["split"], ratio: value["ratio"], treeVisible: value["treeVisible"], contextVisible: value["contextVisible"], treeWidth: value["treeWidth"], contextWidth: value["contextWidth"], theme: value["theme"] };
+  return { version: 1, panes, activePane: value["activePane"], split: value["split"], ratio: value["ratio"], treeVisible: value["treeVisible"], contextVisible: value["contextVisible"], treeWidth: value["treeWidth"], contextWidth: value["contextWidth"], theme: value["theme"], preferences };
+}
+
+/** Startup choice resets navigation only; appearance and sidebar preferences survive. */
+export function restoreWorkspace(layout: WorkspaceLayout): WorkspaceLayout {
+  if (layout.preferences.startup === "restore") return layout;
+  const fresh = initialLayout();
+  return { ...layout, panes: fresh.panes, activePane: fresh.activePane };
+}
+
+/** Opening in the background preserves the active pane and tab, including from Graph. */
+export function openWithPreferences(layout: WorkspaceLayout, id: string | null, options: { newTab?: boolean; paneId?: string } = {}): WorkspaceLayout {
+  const next = openDocument(layout, id, options);
+  if (!options.newTab || layout.preferences.focusNewTabs) return next;
+  return { ...next, activePane: layout.activePane, panes: next.panes.map((pane) => {
+    const previous = layout.panes.find((item) => item.id === pane.id)!;
+    const { lastDocumentTab: _remembered, ...rest } = pane;
+    return { ...rest, activeTab: previous.activeTab, ...(previous.lastDocumentTab ? { lastDocumentTab: previous.lastDocumentTab } : {}) };
+  }) };
 }