resolve workspace and appearance from the warm cache at boot

0.8.6: proxy rewrite, offline deploy method, realpath fix, minor fixes

CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.6] - Karm (2026-06-12)
+
+### Added
+
+- `OBSIDIAN_PACKAGE` env var: unpack a pre-placed `.deb`, `.asar.gz`, or `.asar` on first run instead of downloading, for offline or restricted networks.
+- `PROXY_ALLOW_PRIVATE_HOSTS` env var: IPs or IPv4 CIDRs the cross-origin proxy may reach despite the private-address block.
+
+### Changed
+
+- `fs.promises.realpath` is answered from the client-side cache; vault load no longer issues one realpath request per folder.
+
+### Fixed
+
+- Sync file reads serve virtual plugin files the same as async reads.
+
+### Security
+
+- Cross-origin proxy rewritten for better security
+- Filesystem and vault error responses no longer include absolute server paths.
+- Protocol-relative (`//host`) requests route through the proxy guard.
+- Vault names are validated on creation; `batch-read` caps the number of paths per request.
+- Demo mode: `/api/ext/*` blocked, and several security fixes
+- The `ob` CLI is spawned without a shell.
+- Dependency bumps clearing npm audit.
+
+## [0.8.5] - Karm (2026-06-07)
+
+### Added
+
+- Server settings panel in the Ignis settings tab.
+- `assert`, `constants`, and `stream` shims, plus callback-style `fs` methods and `realpath`.
+
+### Changed
+
+- Write coalescing is now off by default (`WRITE_COALESCE_MS=0`).
+
+### Fixed
+
+- Native menus now stay disabled on platforms where its default is true
+- `/app/data` is now created and owned by the runtime user.
+- Caddy reverse-proxy example uses the current `basic_auth` directive.
+
+### Security
+
+- Cross-origin proxy rejects requests that resolve to private, loopback, or link-local addresses (SSRF guard).
+
 ## [0.8.4] - Karm (2026-06-03)
 
 ### Fixed

CONTRIBUTING.md

@@ -46,18 +46,22 @@ This kind of report makes it straightforward to add the missing shim.
 If you want to contribute code:
 
 1. Fork the repo and create a branch for your change
-2. Run `npm run build` to verify everything builds
-3. start the server with `npm run dev`.
+2. Run `npm install` once at the repo root (npm workspaces)
+3. Run `npm run dev` to build and start the server
 4. Test your change in the browser with at least one vault open
-5. Keep PRs focused - one fix or feature per PR
+5. Run `npm test` and make sure the whole suite passes
+6. Keep PRs focused - one fix or feature per PR
+
+Changes to deliberate behavior (the fs shim's caching and write model, the proxy's request handling, anything documented as a design decision) start as an issue, not a PR. Open the issue first so the approach can be discussed; a patch against an undiscussed design change will be closed on this basis.
 
 ### Project structure
 
-- `src/shims/` - Browser shims for Node.js and Electron APIs
-- `src/ui/` - Svelte UI components (vault manager, dialogs)
-- `plugin/` - The ignis-bridge Obsidian plugin (settings, file actions)
-- `server/` - Express server (fs routes, WebSocket, plugin system)
-- `server/plugins/` - Server plugin packages (e.g., headless-sync)
+- `packages/shim/` - Browser shims for Node.js and Electron APIs
+- `packages/ui/` - Svelte UI components (vault manager, dialogs)
+- `packages/bridge/` - The ignis-bridge Obsidian plugin (settings, file actions)
+- `packages/server-core/` - Shared server helpers (path guards, watcher, WebSocket)
+- `apps/ignis-server/` - Express server, Docker image, demo mode
+- `apps/ignis-server/server/plugins/` - Server plugin packages (e.g., headless-sync)
 
 See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more detail.
 
@@ -65,7 +69,7 @@ See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more detail.
 
 If a plugin needs a Node.js module that isn't shimmed:
 
-1. Create the shim in `src/shims/node/<module>.js`
+1. Create the shim in `packages/shim/src/node/<module>.js`
 2. Export the functions the plugin needs (stub what you can't implement)
-3. Register it in `src/shims/require.js` (import + add to `rawRegistry`)
+3. Register it in `packages/shim/src/require.js` (import + add to `rawRegistry`)
 4. Build and test with the plugin that needed it

README.md

@@ -74,12 +74,12 @@ Compatibility for specific community plugins is tracked in [Issue #9](https://gi
 **Server-side integration.** 
 - Adds a plugin system inside the server itself, separate from Obsidian's community plugin system (WIP).
 - Ignis-specific settings appear as their own tabs inside Obsidian's Settings modal.
+- Server runtime settings (cache sizes, request body limit, etc.) are configurable from the Ignis settings panel.
 - Status bar indicators surface server state and headless sync activity.
 
 ## Roadmap
 
 **Planned:**
-- Server parameter configuration from the Ignis settings panel (LRU cache size, write coalesce window, etc.)
 - Continued shim work to support more community plugins.
 - Server-side plugin system improvements.
 
@@ -94,7 +94,7 @@ A few design decisions worth knowing about for someone evaluating Ignis against
 - A pre-compressed bootstrap response delivers vault info, vault list, metadata tree, and plugin list in a single call.
 - Indexer pre-fetch warms the content cache so Obsidian's startup index hits cache instead of the network.
 - An LRU content cache (50 MB by default) keeps memory use bounded regardless of vault size, so Ignis doesn't hold the whole vault in memory.
-- Write coalescing debounces rapid writes for slow filesystems (rclone, FUSE, NFS, SMB).
+- Optional write coalescing debounces rapid writes for slow filesystems (rclone, FUSE, NFS, SMB); off unless `WRITE_COALESCE_MS` is set.
 
 ## Browser compatibility
 

apps/ignis-server/README.md

@@ -28,6 +28,8 @@ Example configurations for Basic Auth and Authelia are in [`examples/`](examples
 > [!CAUTION]
 > Do not run Ignis on a public network without auth. Anyone with the URL can read and write your vault files.
 
+Ignis also runs a cross-origin proxy (`/api/proxy`) that reaches any public host by default. It rejects private, loopback, and link-local addresses, and you can narrow it to an allowlist or disable it entirely from the proxy settings in the Ignis settings panel.
+
 ## Setup with Docker Compose
 
 Example `docker-compose.yml`:
@@ -73,14 +75,29 @@ To build from source instead of pulling the image, clone the repo and run `docke
 | `DATA_ROOT` | Path to persistent data (plugin config, sync state, auth tokens) | `/app/data` |
 | `OBSIDIAN_VERSION` | Obsidian version to download | `1.12.7` |
 | `OBSIDIAN_ASSETS_PATH` | Where the extracted Obsidian app files live. Override if you're pointing at a pre-extracted directory instead of letting the entrypoint download. | `/app/obsidian-app` |
+| `OBSIDIAN_PACKAGE` | Path to a pre-placed Obsidian package to unpack on first run instead of downloading, for offline or restricted networks. Accepts `.deb` (the form obsidian.md distributes), `.asar.gz`, or `.asar`. | unset |
 | `AUTO_CREATE_DEFAULT` | When `true`, creates a "My Vault" vault on startup if no vaults exist. Useful for fresh installs. | `false` |
 | `PUID` | User ID for file ownership | `1000` |
 | `PGID` | Group ID for file ownership | `1000` |
-| `WRITE_COALESCE_MS` | Debounce window (ms) for rapid writes. Useful for slow filesystems (rclone, NFS, SMB). Set to `0` to disable. | `5000` |
+| `WRITE_COALESCE_MS` | Debounce window (ms) for rapid writes. On slow filesystems (rclone, NFS, SMB), set an appropriate duration. | `0` |
 | `WS_ORIGINS` | Comma-separated allowlist of `Origin` headers accepted on the WebSocket endpoint. When unset, any origin is accepted. | unset |
+| `PROXY_ALLOW_PRIVATE_HOSTS` | Comma-separated IPs or IPv4 CIDRs the cross-origin proxy may reach despite the private-address block, for LAN services. Matched against the resolved IP. Reopens SSRF to the listed targets. | unset |
 
 Demo mode adds its own set of env vars (per-session vaults, auto-cleanup, proxy allowlist, login blocking). See [`examples/demo/`](examples/demo/) if you want to run a public demo deployment.
 
+## Offline / restricted-network install
+
+If the container can't reach GitHub on first run (air-gapped or restricted networks), download Obsidian yourself from [obsidian.md](https://obsidian.md/download) (the `.deb`), mount it into the container, and point `OBSIDIAN_PACKAGE` at it:
+
+```yaml
+    volumes:
+      - ./obsidian_1.12.7_amd64.deb:/packages/obsidian.deb:ro
+    environment:
+      - OBSIDIAN_PACKAGE=/packages/obsidian.deb
+```
+
+On first run the entrypoint unpacks that instead of downloading. Match the version this release pins (see the OCI label and CHANGELOG); a mismatch logs a warning and still boots. `.asar.gz` and `.asar` are also accepted.
+
 ## Migrating an existing vault
 
 Each subdirectory of `/vaults` is treated as a separate vault, so dropping in an existing Obsidian vault directory will make it available in Ignis.

apps/ignis-server/examples/caddy-basic-auth/Caddyfile

@@ -1,6 +1,6 @@
 # Replace with your domain, or use :443 for local access with a self-signed cert.
 ignis.example.com {
-	basicauth {
+	basic_auth {
 		# Username: admin
 		# Replace the hash below with your own. Generate one with:
 		#   docker run --rm caddy:2 caddy hash-password --plaintext YOUR_PASSWORD

apps/ignis-server/scripts/build-image.js

@@ -0,0 +1,111 @@
+// node build-image.js [--push] [--no-latest]
+//
+// --push       build mulit-arch (amd64+arm64) and push as a manifest list, tagged with the package.json version and latest
+// --no-latest  don't move the latest tag
+//
+// Without --push, builds the host arch and loads it as <image>:dev.
+
+const { spawnSync, execSync } = require("child_process");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..", "..", "..");
+const IMAGE = process.env.IGNIS_IMAGE || "nobbe/ignis";
+const BUILDER = "ignis-builder";
+const PLATFORMS = "linux/amd64,linux/arm64";
+
+const args = process.argv.slice(2);
+const push = args.includes("--push");
+const noLatest = args.includes("--no-latest");
+const unknown = args.filter((a) => a !== "--push" && a !== "--no-latest");
+
+if (unknown.length > 0) {
+  console.error("[build-image] unknown arguments:", unknown.join(" "));
+  console.error("usage: node build-image.js [--push] [--no-latest]");
+  process.exit(1);
+}
+
+const version = require(path.join(repoRoot, "package.json")).version;
+
+if (!/^\d+\.\d+\.\d+$/.test(version)) {
+  console.error(
+    `[build-image] version "${version}" is not plain X.Y.Z, refusing to tag`,
+  );
+  process.exit(1);
+}
+
+function run(cmd, cmdArgs, opts = {}) {
+  const result = spawnSync(cmd, cmdArgs, {
+    cwd: repoRoot,
+    stdio: "inherit",
+    ...opts,
+  });
+
+  return result.status === 0;
+}
+
+let dirty = "";
+
+try {
+  dirty = execSync("git status --porcelain", { cwd: repoRoot })
+    .toString()
+    .trim();
+} catch {
+  console.warn("[build-image] could not check git status");
+}
+
+if (dirty) {
+  console.warn(
+    "[build-image] WARNING: working tree has uncommitted changes; the image will not match the committed source",
+  );
+}
+
+const inspect = spawnSync("docker", ["buildx", "inspect", BUILDER], {
+  stdio: "ignore",
+});
+
+if (inspect.status !== 0) {
+  console.log(`[build-image] creating buildx builder ${BUILDER}`);
+
+  const created = run("docker", [
+    "buildx",
+    "create",
+    "--name",
+    BUILDER,
+    "--driver",
+    "docker-container",
+  ]);
+
+  if (!created) {
+    process.exit(1);
+  }
+}
+
+const buildArgs = [
+  "buildx",
+  "build",
+  "--builder",
+  BUILDER,
+  "-f",
+  "apps/ignis-server/Dockerfile",
+];
+
+if (push) {
+  buildArgs.push("--platform", PLATFORMS, "-t", `${IMAGE}:${version}`);
+
+  if (!noLatest) {
+    buildArgs.push("-t", `${IMAGE}:latest`);
+  }
+
+  buildArgs.push("--push");
+  console.log(
+    `[build-image] building ${PLATFORMS} and pushing ${IMAGE}:${version}${noLatest ? "" : ` + ${IMAGE}:latest`}`,
+  );
+} else {
+  // Host arch only. Multi-arch builds can't be loaded into the local image store.
+  buildArgs.push("-t", `${IMAGE}:dev`, "--load");
+  console.log(`[build-image] local build, loading ${IMAGE}:dev`);
+}
+
+buildArgs.push(".");
+
+process.exit(run("docker", buildArgs) ? 0 : 1);

apps/ignis-server/scripts/entrypoint.sh

@@ -23,25 +23,73 @@ else
   echo "[ignis] Using existing user $RUN_USER (UID $PUID)"
 fi
 
-# Fix ownership of volumes
-chown -R "$PUID:$PGID" /vaults /app/obsidian-app
+
+mkdir -p /app/data
+chown -R "$PUID:$PGID" /vaults /app/obsidian-app /app/data
 
 OBSIDIAN_DIR="/app/obsidian-app"
 OBSIDIAN_VERSION="${OBSIDIAN_VERSION:-1.12.7}"
 
+warn_obsidian_version() {
+  if [ -n "$1" ] && [ "$1" != "$OBSIDIAN_VERSION" ]; then
+    echo "[ignis] WARNING: package is Obsidian $1, but this build is pinned to ${OBSIDIAN_VERSION}. The shim may misbehave."
+  fi
+}
+
 if [ ! -f "$OBSIDIAN_DIR/index.html" ]; then
-  echo "[ignis] First run. Downloading Obsidian v${OBSIDIAN_VERSION}..."
+  if [ -n "$OBSIDIAN_PACKAGE" ]; then
+    # Offline / restricted networks: unpack an operator-supplied package instead of downloading.
+    if [ ! -f "$OBSIDIAN_PACKAGE" ]; then
+      echo "[ignis] ERROR: OBSIDIAN_PACKAGE='$OBSIDIAN_PACKAGE' but that file does not exist."
+      exit 1
+    fi
 
-  curl -fSL "https://github.com/obsidianmd/obsidian-releases/releases/download/v${OBSIDIAN_VERSION}/obsidian-${OBSIDIAN_VERSION}.asar.gz" \
-    -o /tmp/obsidian.asar.gz
+    echo "[ignis] First run. Unpacking local Obsidian package: $OBSIDIAN_PACKAGE"
 
-  echo "[ignis] Unpacking asar..."
-  gunzip /tmp/obsidian.asar.gz
-  npx --yes @electron/asar extract /tmp/obsidian.asar "$OBSIDIAN_DIR"
+    case "$OBSIDIAN_PACKAGE" in
+      *.deb)
+        warn_obsidian_version "$(dpkg-deb -f "$OBSIDIAN_PACKAGE" Version 2>/dev/null)"
+        rm -rf /tmp/ob-deb
+        dpkg-deb -x "$OBSIDIAN_PACKAGE" /tmp/ob-deb
+        npx --yes @electron/asar extract \
+          /tmp/ob-deb/opt/Obsidian/resources/obsidian.asar "$OBSIDIAN_DIR"
+        rm -rf /tmp/ob-deb
+        ;;
+      *.asar.gz)
+        warn_obsidian_version "$(basename "$OBSIDIAN_PACKAGE" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+        cp "$OBSIDIAN_PACKAGE" /tmp/obsidian.asar.gz
+        gunzip -f /tmp/obsidian.asar.gz
+        npx --yes @electron/asar extract /tmp/obsidian.asar "$OBSIDIAN_DIR"
+        rm -f /tmp/obsidian.asar
+        ;;
+      *.asar)
+        warn_obsidian_version "$(basename "$OBSIDIAN_PACKAGE" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+        npx --yes @electron/asar extract "$OBSIDIAN_PACKAGE" "$OBSIDIAN_DIR"
+        ;;
+      *)
+        echo "[ignis] ERROR: unsupported OBSIDIAN_PACKAGE format. Supported: .deb, .asar.gz, .asar"
+        exit 1
+        ;;
+    esac
+  else
+    echo "[ignis] First run. Downloading Obsidian v${OBSIDIAN_VERSION}..."
 
-  rm -f /tmp/obsidian.asar
+    curl -fSL "https://github.com/obsidianmd/obsidian-releases/releases/download/v${OBSIDIAN_VERSION}/obsidian-${OBSIDIAN_VERSION}.asar.gz" \
+      -o /tmp/obsidian.asar.gz
 
-  echo "[ignis] Obsidian v${OBSIDIAN_VERSION} ready."
+    echo "[ignis] Unpacking asar..."
+    gunzip /tmp/obsidian.asar.gz
+    npx --yes @electron/asar extract /tmp/obsidian.asar "$OBSIDIAN_DIR"
+
+    rm -f /tmp/obsidian.asar
+  fi
+
+  if [ ! -f "$OBSIDIAN_DIR/index.html" ]; then
+    echo "[ignis] ERROR: setup did not produce $OBSIDIAN_DIR/index.html; the Obsidian package may be invalid."
+    exit 1
+  fi
+
+  echo "[ignis] Obsidian ready (v${OBSIDIAN_VERSION})."
 else
   echo "[ignis] Obsidian already set up."
 fi

apps/ignis-server/server/assets/index.html

@@ -65,25 +65,67 @@
     }, 250);
   }
 
-  update();
+  function appendScripts() {
+    // No Obsidian scripts to load (markup or scrape mismatch); clear the splash instead of pulsing forever.
+    if (scripts.length === 0) {
+      done();
+      return;
+    }
 
-  for (var i = 0; i < scripts.length; i++) {
-    var s = document.createElement("script");
-    s.type = "text/javascript";
-    s.src = scripts[i];
-    s.async = false;
-    s.onload = function () {
-      loaded++;
-      update();
-      if (loaded === scripts.length) done();
-    };
-    s.onerror = function () {
-      loaded++;
-      update();
-      if (loaded === scripts.length) done();
-    };
-    document.body.appendChild(s);
+    update();
+
+    for (var i = 0; i < scripts.length; i++) {
+      var s = document.createElement("script");
+      s.type = "text/javascript";
+      s.src = scripts[i];
+      s.async = false;
+      s.onload = function () {
+        loaded++;
+        update();
+        if (loaded === scripts.length) done();
+      };
+      s.onerror = function () {
+        loaded++;
+        update();
+        if (loaded === scripts.length) done();
+      };
+      document.body.appendChild(s);
+    }
   }
+
+  // Hold Obsidian's scripts until the shim signals the priority cache slice has landed (window.__ignisBootReady), so Obsidian's early config and plugin reads hit the warm cache.
+  // A timeout proceeds anyway, so a missing or never-resolving promise degrades to loading immediately instead of blocking boot.
+  var ready = window.__ignisBootReady;
+  if (!ready || typeof ready.then !== "function") {
+    appendScripts();
+    return;
+  }
+
+  var started = false;
+
+  function start() {
+    if (started) {
+      return;
+    }
+
+    started = true;
+    // Tell the shim's progress writer to stop touching the splash label now that we own it.
+    window.__ignisBootStarted = true;
+    appendScripts();
+  }
+
+  var timer = setTimeout(start, 3000);
+
+  ready.then(
+    function () {
+      clearTimeout(timer);
+      start();
+    },
+    function () {
+      clearTimeout(timer);
+      start();
+    },
+  );
 })();
 </script>
 </body>

apps/ignis-server/server/config.js

@@ -75,16 +75,6 @@ module.exports = {
     vaults = discoverVaults();
     return vaults;
   },
-  writeCoalesceMs:
-    process.env.WRITE_COALESCE_MS !== undefined
-      ? parseInt(process.env.WRITE_COALESCE_MS)
-      : 5000,
-
-  wsOrigins: process.env.WS_ORIGINS
-    ? process.env.WS_ORIGINS.split(",")
-        .map((s) => s.trim())
-        .filter(Boolean)
-    : null,
 
   demoMode: process.env.DEMO_MODE === "true",
   demoMaxSessions: parseInt(process.env.DEMO_MAX_SESSIONS) || 20,

apps/ignis-server/server/demo/demo-provision.js

@@ -80,6 +80,14 @@ async function provisionVault(sessionId, userVaultName) {
   const storageName = makeStorageName(sessionId, userVaultName);
   const vaultPath = path.join(config.vaultRoot, storageName);
 
+  // keep the resolved path inside the vault root.
+  const root = path.resolve(config.vaultRoot);
+  const resolved = path.resolve(vaultPath);
+
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    return { error: "invalid-vault-name" };
+  }
+
   await fsp.mkdir(config.vaultRoot, { recursive: true });
 
   try {

apps/ignis-server/server/demo/demo-sessions.js

@@ -16,6 +16,13 @@ function newSessionId() {
   return crypto.randomBytes(12).toString("hex");
 }
 
+// accept only the format we issue.
+const SESSION_ID_RE = /^[a-f0-9]{24}$/;
+
+function isValidSessionId(id) {
+  return typeof id === "string" && SESSION_ID_RE.test(id);
+}
+
 function prefixFor(sessionId) {
   return "demo-" + sessionId + PREFIX_SEPARATOR;
 }
@@ -61,20 +68,25 @@ function setSessionCookie(res, sessionId) {
 
   res.setHeader(
     "Set-Cookie",
-    `${COOKIE_NAME}=${sessionId}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAgeSeconds}`,
+    `${COOKIE_NAME}=${sessionId}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAgeSeconds}`,
   );
 }
 
 // Resolve the session for a request. If none exists, create one (unless options.peek is true).
 function getOrCreateSession(req, res, options = {}) {
   const cookies = parseCookies(req);
-  const existing = cookies[COOKIE_NAME];
+  const raw = cookies[COOKIE_NAME];
+  const existing = isValidSessionId(raw) ? raw : null;
 
   if (existing && sessions.has(existing)) {
     return existing;
   }
 
   if (existing && !sessions.has(existing)) {
+    if (sessions.size >= config.demoMaxSessions) {
+      return null;
+    }
+
     // Cookie outlived in-memory session. reuse the id to keep the prefix.
     sessions.set(existing, {
       lastActivity: Date.now(),

apps/ignis-server/server/demo/demo-ws.js

@@ -10,6 +10,7 @@ const {
   sessions,
   parseCookies,
   makeStorageName,
+  tryParseUserVaultName,
   touchSession,
 } = require("./demo-sessions");
 
@@ -28,6 +29,20 @@ function wireWebSocket(server) {
         if (userVault && !userVault.startsWith("demo-")) {
           u.searchParams.set("vault", makeStorageName(sessionId, userVault));
           req.url = u.pathname + u.search;
+        } else if (
+          userVault &&
+          userVault.startsWith("demo-") &&
+          tryParseUserVaultName(sessionId, userVault) === null
+        ) {
+          // An already-prefixed vault that isn't this session's: refuse the upgrade.
+          const socket = rest[0];
+
+          if (socket && socket.writable) {
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+            socket.destroy();
+          }
+
+          return;
         }
 
         touchSession(sessionId);

apps/ignis-server/server/demo/index.js

@@ -70,6 +70,16 @@ function setupDemo(app) {
   // Hide server-side plugins (headless-sync) from the demo UI
   app.use("/api/plugins", pluginsBlocker);
 
+  // Plugin routes are not exposed in demo mode.
+  app.use("/api/ext", (req, res) => {
+    res.status(403).json({ error: "Plugin routes are disabled in demo mode" });
+  });
+
+  // Server settings are-fixed in demo mode.
+  app.use("/api/settings", (req, res) => {
+    res.status(403).json({ error: "Settings are disabled in demo mode" });
+  });
+
   // Cleanup timer
   const interval = setInterval(() => {
     cleanupExpired().catch((e) =>

apps/ignis-server/server/index.js

@@ -3,6 +3,7 @@ const fs = require("fs");
 const path = require("path");
 const compression = require("compression");
 const config = require("./config");
+const settings = require("./settings");
 const { getVersion } = require("./version");
 const {
   setupWebSocket,
@@ -19,7 +20,7 @@ const {
   getBundledPluginDirs,
 } = require("./plugin-system/manager");
 const pluginRoutes = require("./routes/plugins");
-writeCoalescer.configure({ writeCoalesceMs: config.writeCoalesceMs });
+writeCoalescer.configure({ writeCoalesceMs: settings.get("writeCoalesceMs") });
 const { flushAll } = writeCoalescer;
 const { setupDemo, wireDemoWebSocket } = require("./demo");
 
@@ -32,7 +33,18 @@ const ANSI_RESET = "\x1b[0m";
 
 const app = express();
 
-app.use(express.json({ limit: "50mb" }));
+// Reject oversized requests by Content-Length before parsing.
+app.use((req, res, next) => {
+  const declared = Number(req.headers["content-length"]);
+
+  if (Number.isFinite(declared) && declared > settings.get("maxBodyBytes")) {
+    return res.status(413).json({ error: "Request body too large" });
+  }
+
+  next();
+});
+
+app.use(express.json({ limit: settings.MAX_BODY_BACKSTOP }));
 app.use(compression());
 
 // logger middleware
@@ -66,6 +78,7 @@ const fsRoutes = require("./routes/fs");
 const vaultRoutes = require("./routes/vault");
 const proxyRoutes = require("./routes/proxy");
 const versionRoutes = require("./routes/version");
+const settingsRoutes = require("./routes/settings");
 const bootstrapRoutes = require("./routes/bootstrap");
 
 app.use("/assets", express.static(path.join(__dirname, "assets")));
@@ -78,6 +91,7 @@ app.use("/api/fs", fsRoutes);
 app.use("/api/vault", vaultRoutes);
 app.use("/api/proxy", proxyRoutes);
 app.use("/api/version", versionRoutes);
+app.use("/api/settings", settingsRoutes);
 app.use("/api/plugins", pluginRoutes);
 app.use("/api/bootstrap", bootstrapRoutes);
 
@@ -197,7 +211,7 @@ const server = app.listen(config.port, async () => {
 
 const wss = setupWebSocket(server, {
   getVaultPath: config.getVaultPath,
-  originAllowlist: config.wsOrigins,
+  originAllowlist: settings.get("wsOrigins"),
 });
 wireDemoWebSocket(server);
 

apps/ignis-server/server/plugins/headless-sync/ob-cli.js

@@ -3,8 +3,6 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
-const isWindows = process.platform === "win32";
-
 // When set via configure(), HOME for the spawned ob points under the plugin's data dir so
 // ob's config dir (~/.config/obsidian-headless/) survives container recreates.
 let configuredDataDir = null;
@@ -39,13 +37,11 @@ function checkInstalled() {
 }
 
 function spawnOb(args, opts = {}) {
-  const home = configuredDataDir
-    ? getObHome(configuredDataDir)
-    : os.homedir();
+  const home = configuredDataDir ? getObHome(configuredDataDir) : os.homedir();
 
   return spawn("ob", args, {
     env: { ...process.env, HOME: home },
-    shell: isWindows,
+    shell: false,
     windowsHide: true,
     ...opts,
   });

apps/ignis-server/server/routes/bootstrap.js

@@ -14,6 +14,7 @@ const {
   getVirtualPluginsForVault,
 } = require("../plugin-system/manager");
 const { getVersion } = require("../version");
+const settings = require("../settings");
 
 const router = express.Router();
 
@@ -140,6 +141,11 @@ async function buildEntry(vaultId) {
     // In demo mode, hide server-side plugins from the client.
     plugins: config.demoMode ? [] : getDiscoveredPlugins(),
     virtualPlugins: getVirtualPluginsForVault(vaultId, getVersion()),
+    settings: {
+      contentCacheBytes: settings.get("contentCacheBytes"),
+      inputCacheBytes: settings.get("inputCacheBytes"),
+      inputCacheTtlMs: settings.get("inputCacheTtlMs"),
+    },
   };
 
   const jsonBuf = Buffer.from(JSON.stringify(response));
@@ -185,6 +191,10 @@ function invalidateVault(vaultId) {
   cache.delete(vaultId);
 }
 
+function invalidateAll() {
+  cache.clear();
+}
+
 async function warmUp() {
   const ids = Object.keys(config.vaults);
 
@@ -251,4 +261,5 @@ router.get("/", async (req, res) => {
 
 module.exports = router;
 module.exports.invalidateVault = invalidateVault;
+module.exports.invalidateAll = invalidateAll;
 module.exports.warmUp = warmUp;

apps/ignis-server/server/routes/fs.js

@@ -98,7 +98,7 @@ router.get("/stat", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -133,7 +133,7 @@ router.get("/readdir", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -184,7 +184,7 @@ router.get("/readFile", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -213,7 +213,7 @@ router.post("/writeFile", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true, mtime: result.mtime, size: result.size });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -231,7 +231,7 @@ router.post("/appendFile", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -251,7 +251,7 @@ router.post("/mkdir", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -280,7 +280,7 @@ router.post("/rename", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -309,7 +309,7 @@ router.post("/copyFile", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -331,7 +331,7 @@ router.delete("/unlink", async (req, res) => {
       // File already gone  -  desired outcome achieved
       res.json({ ok: true });
     } else {
-      res.status(500).json({ error: e.message, code: e.code });
+      res.status(500).json({ error: e.code || "internal", code: e.code });
     }
   }
 });
@@ -350,7 +350,7 @@ router.delete("/rmdir", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -370,7 +370,7 @@ router.delete("/rm", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -388,23 +388,7 @@ router.get("/access", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
-  }
-});
-
-router.get("/realpath", async (req, res) => {
-  const resolved = guardPath(req, res);
-
-  if (!resolved) {
-    return;
-  }
-
-  try {
-    const real = await fs.promises.realpath(resolved);
-
-    res.json({ path: path.relative(req._vaultRoot, real) });
-  } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -426,7 +410,7 @@ router.post("/utimes", async (req, res) => {
     invalidateBootstrap(req);
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -441,6 +425,11 @@ router.post("/batch-read", async (req, res) => {
 
   const paths = Array.isArray(req.body?.paths) ? req.body.paths : [];
 
+  // The indexer prefetcher (the only caller) batches at 50, so a much larger list is not legitimate.
+  if (paths.length > 1000) {
+    return res.status(400).json({ error: "too many paths in batch-read" });
+  }
+
   if (paths.length === 0) {
     return res.json({ files: {} });
   }
@@ -531,7 +520,7 @@ router.get("/tree", async (req, res) => {
 
     res.json(tree);
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -561,7 +550,7 @@ router.get("/download", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -599,7 +588,7 @@ router.get("/download-zip", async (req, res) => {
   } catch (e) {
     res
       .status(e.code === "ENOENT" ? 404 : 500)
-      .json({ error: e.message, code: e.code });
+      .json({ error: e.code || "internal", code: e.code });
   }
 });
 

apps/ignis-server/server/routes/proxy.js

@@ -1,9 +1,349 @@
 const express = require("express");
+const dns = require("dns");
+const net = require("net");
+const http = require("http");
+const https = require("https");
+const zlib = require("zlib");
+const settings = require("../settings");
 
 const router = express.Router();
 
-// POST /api/proxy - forward a request to an external URL to bypass CORS
-// Used by the requestUrl shim for plugin installation, etc.
+const MAX_RESPONSE_BYTES = 50 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const REDIRECT_CODES = new Set([301, 302, 303, 307, 308]);
+
+function isPrivateIp(ip) {
+  const type = net.isIP(ip);
+
+  if (type === 4) {
+    const o = ip.split(".").map(Number);
+
+    return (
+      o[0] === 0 ||
+      o[0] === 10 ||
+      o[0] === 127 ||
+      (o[0] === 169 && o[1] === 254) ||
+      (o[0] === 172 && o[1] >= 16 && o[1] <= 31) ||
+      (o[0] === 192 && o[1] === 168) ||
+      (o[0] === 100 && o[1] >= 64 && o[1] <= 127)
+    );
+  }
+
+  if (type === 6) {
+    const a = ip.toLowerCase();
+
+    if (a === "::1" || a === "::") {
+      return true;
+    }
+
+    if (/^fe[89ab]/.test(a) || a.startsWith("fc") || a.startsWith("fd")) {
+      return true;
+    }
+
+    const mapped = a.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+
+    if (mapped) {
+      return isPrivateIp(mapped[1]);
+    }
+
+    return false;
+  }
+
+  return false;
+}
+
+function ipv4ToInt(ip) {
+  return ip
+    .split(".")
+    .reduce((acc, oct) => ((acc << 8) + Number(oct)) >>> 0, 0);
+}
+
+// Parse PROXY_ALLOW_PRIVATE_HOSTS into matchers.
+// Exact IPs (v4 and v6) and IPv4 CIDRs are supported; IPv6 CIDR and malformed entries are ignored.
+function buildAllowList(entries) {
+  const exact = new Set();
+  const cidrV4 = [];
+
+  for (const entry of entries) {
+    const slash = entry.indexOf("/");
+
+    if (slash === -1) {
+      if (net.isIP(entry)) {
+        exact.add(entry);
+      } else {
+        console.warn(
+          "[proxy] ignoring invalid PROXY_ALLOW_PRIVATE_HOSTS entry:",
+          entry,
+        );
+      }
+
+      continue;
+    }
+
+    const base = entry.slice(0, slash);
+    const prefix = Number(entry.slice(slash + 1));
+
+    if (
+      net.isIP(base) === 4 &&
+      Number.isInteger(prefix) &&
+      prefix >= 0 &&
+      prefix <= 32
+    ) {
+      const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+      cidrV4.push({ network: (ipv4ToInt(base) & mask) >>> 0, mask });
+    } else {
+      console.warn(
+        "[proxy] ignoring unsupported PROXY_ALLOW_PRIVATE_HOSTS entry:",
+        entry,
+      );
+    }
+  }
+
+  return { exact, cidrV4 };
+}
+
+function allowsAddress(allow, ip) {
+  if (allow.exact.has(ip)) {
+    return true;
+  }
+
+  if (net.isIP(ip) === 4) {
+    const value = ipv4ToInt(ip);
+
+    for (const { network, mask } of allow.cidrV4) {
+      if ((value & mask) >>> 0 === network) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+const privateAllowList = buildAllowList(settings.get("proxyAllowPrivate"));
+
+// A public address always passes; a private one passes only when listed it in PROXY_ALLOW_PRIVATE_HOSTS.
+function addressAllowed(ip) {
+  return !isPrivateIp(ip) || allowsAddress(privateAllowList, ip);
+}
+
+function httpError(status, message) {
+  const e = new Error(message);
+  e.statusCode = status;
+  return e;
+}
+
+function safeLookup(hostname, options, callback) {
+  dns.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+    if (err) {
+      callback(err);
+      return;
+    }
+
+    if (!addresses.length) {
+      callback(httpError(502, "DNS resolution failed"));
+      return;
+    }
+
+    for (const a of addresses) {
+      if (!addressAllowed(a.address)) {
+        callback(httpError(403, "Host resolves to a private address"));
+        return;
+      }
+    }
+
+    if (options && options.all) {
+      callback(null, addresses);
+      return;
+    }
+
+    callback(null, addresses[0].address, addresses[0].family);
+  });
+}
+
+// Reject non-http(s) schemes and hosts that resolve to a disallowed address.
+async function assertPublicUrl(urlStr) {
+  let parsed;
+
+  try {
+    parsed = new URL(urlStr);
+  } catch {
+    throw httpError(400, "Invalid URL");
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw httpError(400, "Only http and https URLs are allowed");
+  }
+
+  const host = parsed.hostname;
+
+  if (net.isIP(host)) {
+    if (!addressAllowed(host)) {
+      throw httpError(403, "Host not allowed");
+    }
+
+    return;
+  }
+
+  let addrs;
+
+  try {
+    addrs = await dns.promises.lookup(host, { all: true });
+  } catch {
+    throw httpError(502, "DNS resolution failed");
+  }
+
+  for (const a of addrs) {
+    if (!addressAllowed(a.address)) {
+      throw httpError(403, "Host resolves to a private address");
+    }
+  }
+}
+
+function sameOrigin(a, b) {
+  return a.protocol === b.protocol && a.host === b.host;
+}
+
+function requestOnce(targetUrl, method, headers, body) {
+  return new Promise((resolve, reject) => {
+    const mod = targetUrl.protocol === "https:" ? https : http;
+    const req = mod.request(
+      targetUrl,
+      { method, headers, lookup: safeLookup },
+      resolve,
+    );
+
+    req.on("error", reject);
+
+    if (body && method !== "GET" && method !== "HEAD") {
+      req.write(body);
+    }
+
+    req.end();
+  });
+}
+
+// Follow redirects manually so every hop runs through safeLookup and is re-checked.
+async function proxyRequest({ url, method, headers, body }) {
+  let current = new URL(url);
+  let currentMethod = method;
+  let currentHeaders = headers;
+  let currentBody = body;
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    if (current.protocol !== "http:" && current.protocol !== "https:") {
+      throw httpError(400, "Only http and https URLs are allowed");
+    }
+
+    // An IP-literal host skips DNS, so safeLookup never runs for it; check it here.
+    if (net.isIP(current.hostname) && !addressAllowed(current.hostname)) {
+      throw httpError(403, "Host not allowed");
+    }
+
+    const res = await requestOnce(
+      current,
+      currentMethod,
+      currentHeaders,
+      currentBody,
+    );
+
+    if (!REDIRECT_CODES.has(res.statusCode) || !res.headers.location) {
+      return res;
+    }
+
+    res.resume();
+    const next = new URL(res.headers.location, current);
+
+    // The caller did not choose the redirect target, so credentials do not cross origins.
+    if (!sameOrigin(current, next)) {
+      currentHeaders = { ...currentHeaders };
+
+      for (const key of Object.keys(currentHeaders)) {
+        const lower = key.toLowerCase();
+
+        if (lower === "authorization" || lower === "cookie") {
+          delete currentHeaders[key];
+        }
+      }
+    }
+
+    // 301/302/303 turn a non-GET follow-up into a GET; 307/308 preserve method and body.
+    if (res.statusCode !== 307 && res.statusCode !== 308) {
+      if (currentMethod !== "GET" && currentMethod !== "HEAD") {
+        currentMethod = "GET";
+        currentBody = null;
+      }
+    }
+
+    current = next;
+  }
+
+  throw httpError(508, "Too many redirects");
+}
+
+function readBody(res, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const encoding = (res.headers["content-encoding"] || "").toLowerCase();
+    let stream = res;
+    let decompressor = null;
+
+    if (encoding === "gzip" || encoding === "x-gzip") {
+      decompressor = zlib.createGunzip();
+    } else if (encoding === "deflate") {
+      decompressor = zlib.createInflate();
+    } else if (encoding === "br") {
+      decompressor = zlib.createBrotliDecompress();
+    }
+
+    if (decompressor) {
+      stream = res.pipe(decompressor);
+    }
+
+    const chunks = [];
+    let total = 0;
+    let settled = false;
+
+    function fail(err) {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      res.destroy();
+
+      if (decompressor) {
+        decompressor.destroy();
+      }
+
+      reject(err);
+    }
+
+    stream.on("data", (chunk) => {
+      total += chunk.length;
+
+      if (total > maxBytes) {
+        fail(httpError(413, "Upstream response too large"));
+        return;
+      }
+
+      chunks.push(chunk);
+    });
+
+    stream.on("end", () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+
+    stream.on("error", (e) => fail(httpError(502, e.message)));
+    res.on("error", (e) => fail(httpError(502, e.message)));
+  });
+}
+
+// POST /api/proxy - forward a request to an external URL to bypass CORS.
 router.post("/", async (req, res) => {
   const { url, method, headers, body, binary } = req.body;
 
@@ -11,25 +351,53 @@ router.post("/", async (req, res) => {
     return res.status(400).json({ error: "Missing url" });
   }
 
+  const proxyMode = settings.get("proxyMode");
+
+  if (proxyMode === "disabled") {
+    return res.status(403).json({ error: "Proxy is disabled" });
+  }
+
   try {
-    const fetchOpts = {
+    await assertPublicUrl(url);
+  } catch (e) {
+    return res.status(e.statusCode || 400).json({ error: e.message });
+  }
+
+  if (proxyMode === "allowlist") {
+    const allowlist = settings.get("proxyAllowlist");
+    const host = new URL(url).hostname;
+
+    if (!allowlist.includes(host)) {
+      return res
+        .status(403)
+        .json({ error: `Host not in proxy allowlist: ${host}` });
+    }
+  }
+
+  try {
+    const reqBody =
+      binary && typeof body === "string" ? Buffer.from(body, "base64") : body;
+
+    const upstream = await proxyRequest({
+      url,
       method: method || "GET",
       headers: headers || {},
-    };
+      body: reqBody,
+    });
 
-    if (body && method !== "GET" && method !== "HEAD") {
-      if (binary && typeof body === "string") {
-        fetchOpts.body = Buffer.from(body, "base64");
-      } else {
-        fetchOpts.body = body;
-      }
+    const declaredLength = Number(upstream.headers["content-length"]);
+
+    if (
+      Number.isFinite(declaredLength) &&
+      declaredLength > MAX_RESPONSE_BYTES
+    ) {
+      upstream.destroy();
+      return res.status(413).json({ error: "Upstream response too large" });
     }
 
-    const upstream = await fetch(url, fetchOpts);
-    const respBody = Buffer.from(await upstream.arrayBuffer());
+    const respBody = await readBody(upstream, MAX_RESPONSE_BYTES);
 
-    // Forward response headers, stripping hop-by-hop / encoding headers
-    // since the body is already decompressed by Node's fetch
+    // Strip hop-by-hop and encoding headers; the body is already decompressed.
     const skipHeaders = new Set([
       "content-encoding",
       "transfer-encoding",
@@ -37,20 +405,25 @@ router.post("/", async (req, res) => {
       "connection",
     ]);
     const respHeaders = {};
-    upstream.headers.forEach((val, key) => {
-      if (!skipHeaders.has(key)) {
+
+    for (const [key, val] of Object.entries(upstream.headers)) {
+      if (!skipHeaders.has(key.toLowerCase())) {
         respHeaders[key] = val;
       }
-    });
+    }
 
     res.json({
-      status: upstream.status,
+      status: upstream.statusCode,
       headers: respHeaders,
       body: respBody.toString("base64"),
     });
   } catch (e) {
-    res.status(502).json({ error: e.message });
+    res.status(e.statusCode || 502).json({ error: e.message });
   }
 });
 
 module.exports = router;
+module.exports.isPrivateIp = isPrivateIp;
+module.exports.proxyRequest = proxyRequest;
+module.exports.buildAllowList = buildAllowList;
+module.exports.allowsAddress = allowsAddress;

apps/ignis-server/server/routes/proxy.test.mjs

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const { isPrivateIp, proxyRequest, buildAllowList, allowsAddress } =
+  require("./proxy.js");
+
+describe("isPrivateIp", () => {
+  it("flags private and link-local IPv4", () => {
+    for (const ip of [
+      "0.0.0.0",
+      "10.0.0.1",
+      "127.0.0.1",
+      "169.254.1.1",
+      "172.16.0.1",
+      "172.31.255.255",
+      "192.168.1.1",
+      "100.64.0.1",
+      "100.127.255.255",
+    ]) {
+      expect(isPrivateIp(ip), ip).toBe(true);
+    }
+  });
+
+  it("allows public IPv4, including range boundaries", () => {
+    for (const ip of [
+      "8.8.8.8",
+      "1.1.1.1",
+      "172.15.255.255",
+      "172.32.0.0",
+      "100.63.255.255",
+      "100.128.0.0",
+      "169.253.0.0",
+      "169.255.0.0",
+      "11.0.0.1",
+      "192.169.0.1",
+    ]) {
+      expect(isPrivateIp(ip), ip).toBe(false);
+    }
+  });
+
+  it("flags private and link-local IPv6", () => {
+    for (const ip of ["::1", "::", "fc00::1", "fd12::1", "fe80::1", "feaf::1"]) {
+      expect(isPrivateIp(ip), ip).toBe(true);
+    }
+  });
+
+  it("allows public IPv6", () => {
+    for (const ip of ["2606:4700:4700::1111", "2001:4860:4860::8888"]) {
+      expect(isPrivateIp(ip), ip).toBe(false);
+    }
+  });
+
+  it("classifies IPv4-mapped IPv6 by the embedded address", () => {
+    expect(isPrivateIp("::ffff:127.0.0.1")).toBe(true);
+    expect(isPrivateIp("::ffff:8.8.8.8")).toBe(false);
+  });
+
+  it("returns false for non-IP input", () => {
+    expect(isPrivateIp("not-an-ip")).toBe(false);
+    expect(isPrivateIp("")).toBe(false);
+  });
+});
+
+describe("proxyRequest guard", () => {
+  it("rejects a hostname that resolves to a private address", async () => {
+    await expect(
+      proxyRequest({ url: "http://localhost/", method: "GET", headers: {} }),
+    ).rejects.toMatchObject({ statusCode: 403 });
+  });
+
+  it("rejects a private IP literal (no DNS lookup runs for literals)", async () => {
+    await expect(
+      proxyRequest({ url: "http://127.0.0.1/", method: "GET", headers: {} }),
+    ).rejects.toMatchObject({ statusCode: 403 });
+  });
+});
+
+describe("proxy private-host allow list", () => {
+  it("allows exact IPs and IPv4 CIDRs, rejects everything else", () => {
+    const allow = buildAllowList(["192.168.0.0/16", "10.1.2.3", "::1"]);
+
+    expect(allowsAddress(allow, "192.168.1.5")).toBe(true);
+    expect(allowsAddress(allow, "192.169.0.1")).toBe(false);
+    expect(allowsAddress(allow, "10.1.2.3")).toBe(true);
+    expect(allowsAddress(allow, "10.1.2.4")).toBe(false);
+    expect(allowsAddress(allow, "::1")).toBe(true);
+    expect(allowsAddress(allow, "8.8.8.8")).toBe(false);
+  });
+
+  it("ignores IPv6 CIDR and malformed entries", () => {
+    const allow = buildAllowList(["fd00::/8", "garbage", "192.168.0.0/33"]);
+
+    expect(allow.exact.size).toBe(0);
+    expect(allow.cidrV4.length).toBe(0);
+    expect(allowsAddress(allow, "fd00::1")).toBe(false);
+  });
+});

apps/ignis-server/server/routes/settings.js

@@ -0,0 +1,97 @@
+const express = require("express");
+const { writeCoalescer } = require("@ignis/server-core");
+const settings = require("../settings");
+const bootstrapRoutes = require("./bootstrap");
+
+const router = express.Router();
+
+const NUMBER_KEYS = [
+  "contentCacheBytes",
+  "inputCacheBytes",
+  "inputCacheTtlMs",
+  "writeCoalesceMs",
+  "maxBodyBytes",
+];
+const LIST_KEYS = ["proxyAllowlist"];
+
+function validate(body) {
+  const clean = {};
+
+  if (body.proxyMode !== undefined) {
+    if (!settings.PROXY_MODES.includes(body.proxyMode)) {
+      throw new Error(
+        `proxyMode must be one of: ${settings.PROXY_MODES.join(", ")}`,
+      );
+    }
+
+    clean.proxyMode = body.proxyMode;
+  }
+
+  for (const key of NUMBER_KEYS) {
+    if (body[key] === undefined) {
+      continue;
+    }
+
+    const n = body[key];
+
+    if (!Number.isInteger(n) || n < 0) {
+      throw new Error(`${key} must be a non-negative integer`);
+    }
+
+    if (key === "maxBodyBytes" && (n < 1 || n > settings.MAX_BODY_BACKSTOP)) {
+      throw new Error(
+        `maxBodyBytes must be between 1 and ${settings.MAX_BODY_BACKSTOP}`,
+      );
+    }
+
+    clean[key] = n;
+  }
+
+  for (const key of LIST_KEYS) {
+    if (body[key] === undefined) {
+      continue;
+    }
+
+    const list = body[key];
+
+    if (
+      !Array.isArray(list) ||
+      list.some((v) => typeof v !== "string" || !v.trim())
+    ) {
+      throw new Error(`${key} must be an array of non-empty strings`);
+    }
+
+    clean[key] = list.map((v) => v.trim());
+  }
+
+  return clean;
+}
+
+function applySettings(effective) {
+  writeCoalescer.configure({ writeCoalesceMs: effective.writeCoalesceMs });
+}
+
+router.get("/", (req, res) => {
+  res.json(settings.getAll());
+});
+
+router.post("/", (req, res) => {
+  let clean;
+
+  try {
+    clean = validate(req.body || {});
+  } catch (e) {
+    return res.status(400).json({ error: e.message });
+  }
+
+  const effective = settings.update(clean);
+  applySettings(effective);
+
+  // Cache sizes ride in the bootstrap response; clear it so the next page load picks up new values.
+  bootstrapRoutes.invalidateAll();
+
+  res.json(effective);
+});
+
+module.exports = router;
+module.exports.validate = validate;

apps/ignis-server/server/routes/settings.test.mjs

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const { validate } = require("./settings.js");
+const settings = require("../settings.js");
+
+describe("settings validate", () => {
+  it("rejects an unknown proxy mode", () => {
+    expect(() => validate({ proxyMode: "bogus" })).toThrow();
+  });
+
+  it("rejects negative or non-integer numbers", () => {
+    expect(() => validate({ contentCacheBytes: -1 })).toThrow();
+    expect(() => validate({ contentCacheBytes: 1.5 })).toThrow();
+    expect(() => validate({ contentCacheBytes: "5" })).toThrow();
+  });
+
+  it("enforces maxBodyBytes bounds", () => {
+    expect(() => validate({ maxBodyBytes: 0 })).toThrow();
+    expect(() =>
+      validate({ maxBodyBytes: settings.MAX_BODY_BACKSTOP + 1 }),
+    ).toThrow();
+    expect(validate({ maxBodyBytes: 1048576 })).toEqual({
+      maxBodyBytes: 1048576,
+    });
+  });
+
+  it("trims a valid proxy allowlist", () => {
+    expect(
+      validate({ proxyAllowlist: [" api.example.com ", "github.com"] }),
+    ).toEqual({ proxyAllowlist: ["api.example.com", "github.com"] });
+  });
+
+  it("rejects a non-array allowlist or an empty entry", () => {
+    expect(() => validate({ proxyAllowlist: "x" })).toThrow();
+    expect(() => validate({ proxyAllowlist: ["ok", "  "] })).toThrow();
+  });
+
+  it("ignores wsOrigins, which is env-only", () => {
+    expect(validate({ wsOrigins: ["https://evil.example.com"] })).toEqual({});
+  });
+
+  it("ignores unknown keys", () => {
+    expect(validate({ bogusKey: 1 })).toEqual({});
+  });
+});

apps/ignis-server/server/routes/vault.js

@@ -6,6 +6,25 @@ const bootstrapRoutes = require("./bootstrap");
 
 const router = express.Router();
 
+// Vault names become directories under VAULT_ROOT; reject traversal, hidden, and reserved-device names.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+function isValidVaultName(name) {
+  if (typeof name !== "string" || name.length === 0 || name.length > 255) {
+    return false;
+  }
+
+  if (/[\/\\:*?"<>|]/.test(name)) {
+    return false;
+  }
+
+  if (name.startsWith(".")) {
+    return false;
+  }
+
+  return !WINDOWS_RESERVED.test(name);
+}
+
 // GET /api/vault/list - returns all discovered vaults (re-scans on each call)
 router.get("/list", (req, res) => {
   config.refreshVaults();
@@ -41,7 +60,7 @@ router.get("/info", async (req, res) => {
 router.post("/create", async (req, res) => {
   const name = req.body?.name;
 
-  if (!name || /[\/\\:*?"<>|]/.test(name)) {
+  if (!isValidVaultName(name)) {
     return res.status(400).json({ error: "Invalid vault name" });
   }
 
@@ -62,7 +81,7 @@ router.post("/create", async (req, res) => {
       return res.status(409).json({ error: "Vault already exists" });
     }
 
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -71,7 +90,7 @@ router.post("/rename", async (req, res) => {
   const vaultId = req.body?.vault;
   const newName = req.body?.name;
 
-  if (!newName || /[\/\\:*?"<>|]/.test(newName)) {
+  if (!isValidVaultName(newName)) {
     return res.status(400).json({ error: "Invalid vault name" });
   }
 
@@ -98,7 +117,7 @@ router.post("/rename", async (req, res) => {
         .json({ error: "A vault with that name already exists" });
     }
 
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 
@@ -119,7 +138,7 @@ router.delete("/remove", async (req, res) => {
 
     res.json({ ok: true });
   } catch (e) {
-    res.status(500).json({ error: e.message, code: e.code });
+    res.status(500).json({ error: e.code || "internal", code: e.code });
   }
 });
 

apps/ignis-server/server/settings.js

@@ -0,0 +1,120 @@
+const fs = require("fs");
+const path = require("path");
+const config = require("./config");
+
+// Runtime server settings set through UI.
+
+const SETTINGS_FILE = path.join(config.dataRoot, "server-settings.json");
+
+const DEFAULTS = {
+  contentCacheBytes: 50 * 1024 * 1024,
+  inputCacheBytes: 200 * 1024 * 1024,
+  inputCacheTtlMs: 5 * 60 * 1000,
+  writeCoalesceMs: 0,
+  maxBodyBytes: 50 * 1024 * 1024,
+  // "any" reaches any public host, "allowlist" restricts to proxyAllowlist, "disabled" blocks all proxying.
+  proxyMode: "any",
+  // Empty allows any public host.
+  proxyAllowlist: [],
+  wsOrigins: [],
+  // Private IPs/CIDRs the proxy may reach despite the SSRF guard.
+  proxyAllowPrivate: [],
+};
+
+const PROXY_MODES = ["any", "allowlist", "disabled"];
+
+const KEYS = Object.keys(DEFAULTS);
+
+// Env vars only; never persisted to the settings file.
+const ENV_ONLY_KEYS = ["wsOrigins", "proxyAllowPrivate"];
+
+// Hard ceiling for request bodies.
+const MAX_BODY_BACKSTOP = 500 * 1024 * 1024;
+
+function parseList(raw) {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function fromEnv() {
+  const env = {};
+
+  if (process.env.WRITE_COALESCE_MS !== undefined) {
+    const n = parseInt(process.env.WRITE_COALESCE_MS, 10);
+
+    if (Number.isFinite(n)) {
+      env.writeCoalesceMs = n;
+    }
+  }
+
+  if (process.env.WS_ORIGINS) {
+    env.wsOrigins = parseList(process.env.WS_ORIGINS);
+  }
+
+  if (process.env.PROXY_ALLOW_PRIVATE_HOSTS) {
+    env.proxyAllowPrivate = parseList(process.env.PROXY_ALLOW_PRIVATE_HOSTS);
+  }
+
+  return env;
+}
+
+const envOverrides = fromEnv();
+
+function loadFile() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+    // Keep only known keys so a stale or hand-edited file can't inject junk.
+    const clean = {};
+
+    for (const key of KEYS) {
+      if (ENV_ONLY_KEYS.includes(key)) {
+        continue;
+      }
+
+      if (parsed[key] !== undefined) {
+        clean[key] = parsed[key];
+      }
+    }
+
+    return clean;
+  } catch {
+    return {};
+  }
+}
+
+let fileOverrides = loadFile();
+
+function getAll() {
+  return { ...DEFAULTS, ...envOverrides, ...fileOverrides };
+}
+
+function get(key) {
+  return getAll()[key];
+}
+
+// Merge validated changes into the persisted file and return the new effective settings.
+function update(partial) {
+  for (const [key, value] of Object.entries(partial)) {
+    if (KEYS.includes(key) && !ENV_ONLY_KEYS.includes(key)) {
+      fileOverrides[key] = value;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
+  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(fileOverrides, null, 2));
+
+  return getAll();
+}
+
+module.exports = {
+  DEFAULTS,
+  KEYS,
+  ENV_ONLY_KEYS,
+  PROXY_MODES,
+  MAX_BODY_BACKSTOP,
+  getAll,
+  get,
+  update,
+};

docs/ARCHITECTURE.md

@@ -69,6 +69,9 @@ Immediately after the bootstrap response is applied, the client kicks off a batc
 | `net`                | All classes/functions throw.                                                                    |
 | `http` / `https`     | Module is importable but `request()`/`get()` emit an `error` event; `createServer` throws. Plugins should use `requestUrl` or `fetch` (the shim routes cross-origin `fetch` through the server proxy). |
 | `buffer`             | Aliased to the browser `Buffer` polyfill set up by the loader.                                  |
+| `assert`             | Standard assertions: `assert`, `equal`, `strictEqual`, `deepEqual`, `throws`. |
+| `constants`          | File access and mode constants (`F_OK`, `O_RDONLY`, `S_IFMT`, etc.) for the reported Linux platform. |
+| `stream`             | Base classes (`Stream`, `Readable`, `Writable`, `Duplex`, `Transform`, `PassThrough`) extending EventEmitter. Data-flow methods warn and do nothing. |
 
 Unknown modules return an empty proxy and log a warning. The `node:` prefix is stripped. The shim exposes two console helpers, `window.__shimLog()` (everything that has been accessed) and `window.__shimMisses()` (accessed-but-missing properties).
 
@@ -78,7 +81,7 @@ Two caches on the client side. The **MetadataCache** holds `{ type, size, mtime,
 
 Reads not satisfied by ContentCache go through the transport layer to `/api/fs/readFile`. Sync calls use synchronous XHR to keep Obsidian's pre-boot module code working. Async calls use fetch. The transport handles vault id injection, base64 encoding for binary files, and mapping HTTP error codes back to Node errno values (`ENOENT`, `EEXIST`, `ENOTDIR`).
 
-Writes go through a server-side write coalescer (`packages/server-core/src/write-coalescer.js`) designed for slow filesystems like rclone FUSE mounts. The first write to a path goes to disk immediately. Subsequent writes within a configurable window (default 5 seconds, `WRITE_COALESCE_MS`) are buffered and flushed when the debounce timer fires; the timer resets on each write. Buffered writes return to the HTTP client immediately with synthetic metadata so connection-pool starvation on rapid-fire writes (e.g. `workspace.json` autosaves) doesn't stall unrelated reads. Reads for pending paths serve the buffered content so clients never see stale data. All pending writes are flushed on graceful shutdown.
+Writes go through a server-side write coalescer (`packages/server-core/src/write-coalescer.js`) designed for slow filesystems like rclone FUSE mounts. The first write to a path goes to disk immediately. Subsequent writes within a configurable window (`WRITE_COALESCE_MS`, default `0` which disables coalescing) are buffered and flushed when the debounce timer fires; the timer resets on each write. Buffered writes return to the HTTP client immediately with synthetic metadata so connection-pool starvation on rapid-fire writes (e.g. `workspace.json` autosaves) doesn't stall unrelated reads. Reads for pending paths serve the buffered content so clients never see stale data. All pending writes are flushed on graceful shutdown.
 
 ### Transforms
 
@@ -102,7 +105,7 @@ Obsidian on the desktop can make arbitrary cross-origin HTTP requests because it
 
 The shim handles this transparently. `window.fetch` and `window.requestUrl` are intercepted. Same-origin requests pass through unchanged. Cross-origin requests are POSTed to `/api/proxy`, which performs the outbound call from the server with headers that mimic Obsidian's desktop runtime: `Origin: app://obsidian.md` and the browser's own User-Agent. The response body is returned base64-encoded so binary content survives the JSON round-trip; the shim decodes it and hands the caller a normal `Response` or `requestUrl` result.
 
-The proxy itself is intentionally generic. It forwards method, headers, and body verbatim and returns whatever the upstream sent. In demo mode, an allowlist restricts the hostname to a known-safe set; in normal self-hosted mode there's no restriction, which is one of the reasons the server needs to be behind authentication when exposed to the internet.
+The proxy itself is intentionally generic. It forwards method, headers, and body verbatim and returns whatever the upstream sent. It always rejects requests whose hostname resolves to a private, loopback, or link-local address (SSRF guard). Outbound access is governed by `proxyMode`: `any` (the default) reaches any public host, `allowlist` restricts to a configured host list, and `disabled` blocks all proxying; demo mode pins it to `allowlist`. Under the default `any`, the proxy is an open relay to public hosts, which is one of the reasons the server needs to be behind authentication when exposed to the internet.
 
 ### Workspaces in browser tabs
 
@@ -138,6 +141,7 @@ An Express server that handles filesystem operations, vault management, static f
 - `/api/bootstrap` - one-shot cold-start endpoint; returns vault info + list + metadata tree + plugin list as a single pre-compressed response, cached per vault with mtime-based invalidation.
 - `/api/proxy` - cross-origin HTTP proxy used by the fetch and requestUrl shims.
 - `/api/version` - Ignis version (SemVer), per-build identifier, and pinned Obsidian version.
+- `/api/settings/*` - read and update runtime server settings (cache sizes, request body limit, write-coalesce window, proxy mode and allowlist).
 - `/api/plugins/*` - Ignis plugin management (list, enable, disable). __WIP__
 - `/api/ext/:pluginId/*` - routes registered by individual Ignis plugins.
 - `/vault-files/<vaultId>/<path>` - static file serving rooted at a vault, used by Obsidian for image/attachment resource URLs.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ignis-monorepo",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ignis-monorepo",
-      "version": "0.8.2",
+      "version": "0.8.5",
       "workspaces": [
         "packages/*",
         "apps/*"
@@ -1006,15 +1006,15 @@
       "license": "MIT"
     },
     "node_modules/@vitest/expect": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.4.tgz",
-      "integrity": "sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.6.tgz",
+      "integrity": "sha512-1+7q9BtaKzEmO+fmNT3kYvoNn5Y71XWAx2Q5HRim4tTVRQVRv4uJFAQ5FbK0OPUeNP/WmVCpxYxoJdvuHVjzBQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "3.2.4",
-        "@vitest/utils": "3.2.4",
+        "@vitest/spy": "3.2.6",
+        "@vitest/utils": "3.2.6",
         "chai": "^5.2.0",
         "tinyrainbow": "^2.0.0"
       },
@@ -1023,13 +1023,13 @@
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.4.tgz",
-      "integrity": "sha512-46ryTE9RZO/rfDd7pEqFl7etuyzekzEhUbTW3BvmeO/BcCMEgq59BKhek3dXDWgAj4oMK6OZi+vRr1wPW6qjEQ==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.6.tgz",
+      "integrity": "sha512-EZOrpDbkKotFAP7wPAQV1UIyoGOk4oX7ynWhBhLB7v+meMHbQhU16oPpIYGTTe4oFlhpryGpgpcZP/sin3hYuw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "3.2.4",
+        "@vitest/spy": "3.2.6",
         "estree-walker": "^3.0.3",
         "magic-string": "^0.30.17"
       },
@@ -1050,9 +1050,9 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.4.tgz",
-      "integrity": "sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.6.tgz",
+      "integrity": "sha512-lb7XXXzmm2h2ASzFnRvQpDo6onT1NmMJA3tkGTWiBFtRJ9lxGY3d3mm/Apt36gej2bkkOVLL/yTOtufDaFa/jA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1063,13 +1063,13 @@
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.4.tgz",
-      "integrity": "sha512-oukfKT9Mk41LreEW09vt45f8wx7DordoWUZMYdY/cyAk7w5TWkTRCNZYF7sX7n2wB7jyGAl74OxgwhPgKaqDMQ==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.6.tgz",
+      "integrity": "sha512-HYcoSj1w5tcgUnzoF0HcyaAQjpA1gj9ftUJ7iSJSuipc02jW9gKkigwZbjFldAfYHA1fa8UZVRftdMY5msWM9Q==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "3.2.4",
+        "@vitest/utils": "3.2.6",
         "pathe": "^2.0.3",
         "strip-literal": "^3.0.0"
       },
@@ -1078,13 +1078,13 @@
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.4.tgz",
-      "integrity": "sha512-dEYtS7qQP2CjU27QBC5oUOxLE/v5eLkGqPE0ZKEIDGMs4vKWe7IjgLOeauHsR0D5YuuycGRO5oSRXnwnmA78fQ==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.6.tgz",
+      "integrity": "sha512-H+ZjNTWGpObenh0YnlBctAPnJSI20P81PL8BPzWpx54YXLLTm8hEsWawtcYLMrwvpK48hGxLLbCS+1KRXhsKhw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "3.2.4",
+        "@vitest/pretty-format": "3.2.6",
         "magic-string": "^0.30.17",
         "pathe": "^2.0.3"
       },
@@ -1093,9 +1093,9 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.4.tgz",
-      "integrity": "sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.6.tgz",
+      "integrity": "sha512-oq6BbH68WzcWmwtBrU9nqLeaXTR4XwJF7FSLkKEZo4i6eoXcrxjcwSuTvWBIRUTC6VC72nXYunzqgZA+IKdtxg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1106,13 +1106,13 @@
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.4.tgz",
-      "integrity": "sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.6.tgz",
+      "integrity": "sha512-lI23nIs4bnT3T8NIoh+vFaz5s2/DdP0Jgt2jxwgWljvwn82cLJtyi/If+fjFyoLMGIOz0U/fKvWE0d4jsNQEfg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "3.2.4",
+        "@vitest/pretty-format": "3.2.6",
         "loupe": "^3.1.4",
         "tinyrainbow": "^2.0.0"
       },
@@ -1414,9 +1414,9 @@
       }
     },
     "node_modules/body-parser": {
-      "version": "1.20.4",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.4.tgz",
-      "integrity": "sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==",
+      "version": "1.20.5",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.5.tgz",
+      "integrity": "sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA==",
       "license": "MIT",
       "dependencies": {
         "bytes": "~3.1.2",
@@ -1427,7 +1427,7 @@
         "http-errors": "~2.0.1",
         "iconv-lite": "~0.4.24",
         "on-finished": "~2.4.1",
-        "qs": "~6.14.0",
+        "qs": "~6.15.1",
         "raw-body": "~2.5.3",
         "type-is": "~1.6.18",
         "unpipe": "~1.0.0"
@@ -1438,9 +1438,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
-      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.1.tgz",
+      "integrity": "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0"
@@ -1892,9 +1892,9 @@
       "license": "MIT"
     },
     "node_modules/es-object-atoms": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
-      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
+      "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0"
@@ -2021,14 +2021,14 @@
       }
     },
     "node_modules/express": {
-      "version": "4.22.1",
-      "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz",
-      "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==",
+      "version": "4.22.2",
+      "resolved": "https://registry.npmjs.org/express/-/express-4.22.2.tgz",
+      "integrity": "sha512-IuL+Elrou2ZvCFHs18/CIzy2Nzvo25nZ1/D2eIZlz7c+QUayAcYoiM2BthCjs+EBHVpjYjcuLDAiCWgeIX3X1Q==",
       "license": "MIT",
       "dependencies": {
         "accepts": "~1.3.8",
         "array-flatten": "1.1.1",
-        "body-parser": "~1.20.3",
+        "body-parser": "~1.20.5",
         "content-disposition": "~0.5.4",
         "content-type": "~1.0.4",
         "cookie": "~0.7.1",
@@ -2047,7 +2047,7 @@
         "parseurl": "~1.3.3",
         "path-to-regexp": "~0.1.12",
         "proxy-addr": "~2.0.7",
-        "qs": "~6.14.0",
+        "qs": "~6.15.1",
         "range-parser": "~1.2.1",
         "safe-buffer": "5.2.1",
         "send": "~0.19.0",
@@ -2260,9 +2260,9 @@
       }
     },
     "node_modules/hasown": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
-      "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==",
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
+      "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
       "license": "MIT",
       "dependencies": {
         "function-bind": "^1.1.2"
@@ -2493,9 +2493,9 @@
       "license": "MIT"
     },
     "node_modules/lodash": {
-      "version": "4.17.23",
-      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz",
-      "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==",
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
       "license": "MIT"
     },
     "node_modules/loupe": {
@@ -2766,9 +2766,9 @@
       }
     },
     "node_modules/path-to-regexp": {
-      "version": "0.1.12",
-      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz",
-      "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
+      "version": "0.1.13",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz",
+      "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==",
       "license": "MIT"
     },
     "node_modules/pathe": {
@@ -2807,9 +2807,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "license": "MIT",
       "engines": {
         "node": ">=8.6"
@@ -2876,9 +2876,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.14.2",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz",
-      "integrity": "sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==",
+      "version": "6.15.2",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
+      "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"
@@ -3107,14 +3107,14 @@
       }
     },
     "node_modules/side-channel": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
-      "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",
+      "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==",
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
-        "object-inspect": "^1.13.3",
-        "side-channel-list": "^1.0.0",
+        "object-inspect": "^1.13.4",
+        "side-channel-list": "^1.0.1",
         "side-channel-map": "^1.0.1",
         "side-channel-weakmap": "^1.0.2"
       },
@@ -3126,13 +3126,13 @@
       }
     },
     "node_modules/side-channel-list": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz",
-      "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==",
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
+      "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
-        "object-inspect": "^1.13.3"
+        "object-inspect": "^1.13.4"
       },
       "engines": {
         "node": ">= 0.4"
@@ -4160,20 +4160,20 @@
       }
     },
     "node_modules/vitest": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.4.tgz",
-      "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.6.tgz",
+      "integrity": "sha512-xejya+bT/j/+R/AGa1XOfRxLmNUlLtlwjRsFUILF+xHfzElmGcmFydy2gqqIrd62ptIEfwVMofd19uNWD9L7Nw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/chai": "^5.2.2",
-        "@vitest/expect": "3.2.4",
-        "@vitest/mocker": "3.2.4",
-        "@vitest/pretty-format": "^3.2.4",
-        "@vitest/runner": "3.2.4",
-        "@vitest/snapshot": "3.2.4",
-        "@vitest/spy": "3.2.4",
-        "@vitest/utils": "3.2.4",
+        "@vitest/expect": "3.2.6",
+        "@vitest/mocker": "3.2.6",
+        "@vitest/pretty-format": "^3.2.6",
+        "@vitest/runner": "3.2.6",
+        "@vitest/snapshot": "3.2.6",
+        "@vitest/spy": "3.2.6",
+        "@vitest/utils": "3.2.6",
         "chai": "^5.2.0",
         "debug": "^4.4.1",
         "expect-type": "^1.2.1",
@@ -4203,8 +4203,8 @@
         "@edge-runtime/vm": "*",
         "@types/debug": "^4.1.12",
         "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
-        "@vitest/browser": "3.2.4",
-        "@vitest/ui": "3.2.4",
+        "@vitest/browser": "3.2.6",
+        "@vitest/ui": "3.2.6",
         "happy-dom": "*",
         "jsdom": "*"
       },
@@ -4394,9 +4394,9 @@
       }
     },
     "node_modules/ws": {
-      "version": "8.19.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
-      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
@@ -4430,10 +4430,7 @@
     },
     "packages/bridge": {
       "name": "@ignis/bridge",
-      "version": "0.0.0-internal",
-      "devDependencies": {
-        "esbuild": "^0.20.0"
-      }
+      "version": "0.0.0-internal"
     },
     "packages/bridge-plugin": {
       "name": "@ignis/bridge-plugin",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ignis-monorepo",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "private": true,
   "description": "Monorepo for Ignis: a browser-based Obsidian client. Self-hosted server in apps/ignis-server; shim, UI, and shared libraries in packages/.",
   "workspaces": [
@@ -11,6 +11,7 @@
     "build": "node build.js",
     "dev:server": "node apps/ignis-server/server/index.js",
     "dev": "npm run build && npm run dev:server",
+    "docker:build": "node apps/ignis-server/scripts/build-image.js",
     "test": "vitest run",
     "test:watch": "vitest"
   },

packages/bridge/package.json

@@ -2,5 +2,6 @@
   "name": "@ignis/bridge",
   "version": "0.0.0-internal",
   "private": true,
+  "type": "module",
   "main": "src/main.js"
 }

packages/bridge/src/demo-guards.js

@@ -51,4 +51,4 @@ function stopDemoGuards() {
   }
 }
 
-module.exports = { startDemoGuards, stopDemoGuards };
+export { startDemoGuards, stopDemoGuards, isDemoMode };

packages/bridge/src/file-actions.js

@@ -1,4 +1,4 @@
-const { Notice, TFile, TFolder } = require("obsidian");
+import { Notice, TFile, TFolder } from "obsidian";
 
 function getVaultId() {
   return window.__currentVaultId || "";
@@ -92,4 +92,4 @@ function addFolderMenuItems(menu, folder, app) {
   });
 }
 
-module.exports = { showFilePicker, addFileMenuItems, addFolderMenuItems };
+export { showFilePicker, addFileMenuItems, addFolderMenuItems };

packages/bridge/src/main.js

@@ -1,17 +1,17 @@
-const { Plugin, TFile, TFolder } = require("obsidian");
-const {
+import { Plugin, TFile, TFolder } from "obsidian";
+import {
   showFilePicker,
   addFileMenuItems,
   addFolderMenuItems,
-} = require("./file-actions");
-const {
+} from "./file-actions.js";
+import {
   patchSettingsModal,
   unpatchSettingsModal,
-} = require("./settings/inject");
-const pluginRegistry = require("./plugin-registry");
-const { initStatusBar } = require("./status-bar");
-const { WorkspacePickerModal } = require("./workspace-picker");
-const { startDemoGuards, stopDemoGuards } = require("./demo-guards");
+} from "./settings/inject.js";
+import * as pluginRegistry from "./plugin-registry.js";
+import { initStatusBar } from "./status-bar.js";
+import { WorkspacePickerModal } from "./workspace-picker.js";
+import { startDemoGuards, stopDemoGuards } from "./demo-guards.js";
 
 class IgnisBridgePlugin extends Plugin {
   async onload() {
@@ -65,4 +65,4 @@ class IgnisBridgePlugin extends Plugin {
   }
 }
 
-module.exports = IgnisBridgePlugin;
+export default IgnisBridgePlugin;

packages/bridge/src/plugin-registry.js

@@ -34,4 +34,4 @@ function getKnownIds() {
   return knownIds;
 }
 
-module.exports = { refresh, isIgnisPlugin, addId, getKnownIds };
+export { refresh, isIgnisPlugin, addId, getKnownIds };

packages/bridge/src/settings/general-tab.js

@@ -1,4 +1,7 @@
-const { Setting } = require("obsidian");
+import { Setting, Notice } from "obsidian";
+import { isDemoMode } from "../demo-guards.js";
+import { stripBuildMetadata, isNewer } from "../util/version.js";
+import { ListEditorModal } from "./list-editor-modal.js";
 
 const GITHUB_URL = "https://github.com/Nystik-gh/ignis";
 const GITHUB_API_LATEST =
@@ -8,11 +11,6 @@ function getVersion() {
   return window.__ignis?.version || "unknown";
 }
 
-// SemVer build metadata (`+xyz`) is informational and ignored for precedence.
-function stripBuildMetadata(version) {
-  return (version || "").split("+")[0];
-}
-
 async function checkForUpdate(currentVersion) {
   try {
     const res = await fetch(GITHUB_API_LATEST);
@@ -25,7 +23,7 @@ async function checkForUpdate(currentVersion) {
     const latest = stripBuildMetadata(data.tag_name?.replace(/^v/, ""));
     const current = stripBuildMetadata(currentVersion);
 
-    if (latest && latest !== current) {
+    if (isNewer(latest, current)) {
       return { version: latest, url: data.html_url };
     }
 
@@ -88,6 +86,7 @@ function display(containerEl, app) {
   });
 
   addServerStatus(containerEl);
+  addServerSettings(containerEl, app);
 }
 
 const STATUS_LABELS = {
@@ -102,10 +101,22 @@ const STATUS_DOT_CLASSES = {
   closed: "ignis-status-disconnected",
 };
 
+function createSettingGroup(containerEl, heading) {
+  const group = containerEl.createDiv("setting-group");
+
+  if (heading) {
+    new Setting(group).setName(heading).setHeading();
+  }
+
+  return group.createDiv("setting-items");
+}
+
 function addServerStatus(containerEl) {
   const ws = window.__ignis.ws;
 
-  const setting = new Setting(containerEl).setName("Server status");
+  const items = createSettingGroup(containerEl);
+
+  const setting = new Setting(items).setName("Server status");
 
   const dotEl = setting.controlEl.createEl("span", {
     cls: "ignis-status-dot",
@@ -138,4 +149,214 @@ function addServerStatus(containerEl) {
   });
 }
 
-module.exports = { display };
+const MB = 1024 * 1024;
+const MINUTE = 60 * 1000;
+
+function addServerSettings(containerEl, app) {
+  if (isDemoMode()) {
+    const items = createSettingGroup(containerEl);
+
+    new Setting(items)
+      .setName("Server settings")
+      .setDesc("Server settings are disabled in demo mode.");
+    return;
+  }
+
+  const loading = containerEl.createEl("p", {
+    text: "Loading server settings...",
+    cls: "setting-item-description",
+  });
+
+  fetch("/api/settings")
+    .then((res) => (res.ok ? res.json() : Promise.reject(res)))
+    .then((current) => {
+      loading.remove();
+      renderServerSettings(containerEl, current, app);
+    })
+    .catch(() => {
+      loading.setText("Failed to load server settings.");
+    });
+}
+
+function renderServerSettings(containerEl, current, app) {
+  const caching = createSettingGroup(containerEl, "Caching");
+
+  numberField(caching, {
+    name: "Content cache (MB)",
+    desc: "Browser cache of file content. Applies after reload.",
+    value: Math.round(current.contentCacheBytes / MB),
+    key: "contentCacheBytes",
+    toStored: (n) => n * MB,
+  });
+
+  numberField(caching, {
+    name: "Input cache (MB)",
+    desc: "Cache for files picked for import. Applies after reload.",
+    value: Math.round(current.inputCacheBytes / MB),
+    key: "inputCacheBytes",
+    toStored: (n) => n * MB,
+  });
+
+  numberField(caching, {
+    name: "Input cache TTL (minutes)",
+    desc: "How long picked files stay cached. Applies after reload.",
+    value: Math.round(current.inputCacheTtlMs / MINUTE),
+    key: "inputCacheTtlMs",
+    toStored: (n) => n * MINUTE,
+  });
+
+  const security = createSettingGroup(containerEl, "Security");
+
+  numberField(security, {
+    name: "Max request body (MB)",
+    desc: "Largest request the server accepts.",
+    value: Math.round(current.maxBodyBytes / MB),
+    key: "maxBodyBytes",
+    toStored: (n) => n * MB,
+  });
+
+  proxyAccessField(security, current, app);
+
+  const advanced = createSettingGroup(containerEl, "Advanced");
+
+  numberField(advanced, {
+    name: "Write coalesce window (ms)",
+    desc: "Debounce window for rapid writes on slow filesystems. 0 disables.",
+    value: current.writeCoalesceMs,
+    key: "writeCoalesceMs",
+    toStored: (n) => n,
+  });
+}
+
+// Persist a single setting. The server validates, applies the live ones, and saves.
+async function saveSetting(partial) {
+  try {
+    const res = await fetch("/api/settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(partial),
+    });
+
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      throw new Error(data.error || "Save failed");
+    }
+  } catch (e) {
+    new Notice(`Failed to save setting: ${e.message}`);
+  }
+}
+
+function numberField(containerEl, { name, desc, value, key, toStored }) {
+  let committed = value;
+
+  new Setting(containerEl)
+    .setName(name)
+    .setDesc(desc)
+    .addText((text) => {
+      text.setValue(String(value));
+
+      // Commit only on change.
+      const commit = () => {
+        const n = parseInt(text.getValue(), 10);
+
+        if (!Number.isInteger(n) || n < 0 || n === committed) {
+          return;
+        }
+
+        committed = n;
+        saveSetting({ [key]: toStored(n) });
+      };
+
+      text.inputEl.addEventListener("blur", commit);
+      text.inputEl.addEventListener("keydown", (e) => {
+        if (e.key === "Enter") {
+          commit();
+        }
+      });
+    });
+}
+
+// Proxy access mode plus the allowlist row, which only shows in "allowlist" mode.
+function proxyAccessField(parent, current, app) {
+  let mode = current.proxyMode || "any";
+
+  const setting = new Setting(parent)
+    .setName("Proxy access")
+    .setDesc(
+      "Which external hosts Obsidian may reach through the server's CORS proxy.",
+    );
+
+  const allowlistSetting = listField(parent, {
+    name: "Proxy host allowlist",
+    desc: "Hostnames the proxy may reach, matched exactly.",
+    value: current.proxyAllowlist,
+    key: "proxyAllowlist",
+    app,
+    modal: {
+      placeholder: "api.example.com",
+      emptyNote: "No hosts yet.",
+      recommended: {
+        note: "Restricting the proxy stops Obsidian's plugin and theme browser and updates from working unless their hosts are allowed.",
+        hosts: [
+          "releases.obsidian.md",
+          "github.com",
+          "api.github.com",
+          "raw.githubusercontent.com",
+        ],
+        buttonText: "Add recommended hosts",
+      },
+    },
+  });
+
+  const applyVisibility = () => {
+    allowlistSetting.settingEl.style.display =
+      mode === "allowlist" ? "" : "none";
+  };
+
+  setting.addDropdown((dd) => {
+    dd.addOption("any", "Any public host");
+    dd.addOption("allowlist", "Allowlist only");
+    dd.addOption("disabled", "Disabled");
+    dd.setValue(mode);
+
+    dd.onChange((value) => {
+      mode = value;
+      saveSetting({ proxyMode: value });
+      applyVisibility();
+    });
+  });
+
+  applyVisibility();
+}
+
+function listField(containerEl, { name, desc, value, key, app, modal }) {
+  let current = [...(value || [])];
+
+  const setting = new Setting(containerEl).setName(name).setDesc(desc);
+
+  const setLabel = (btn) =>
+    btn.setButtonText(current.length ? `Edit (${current.length})` : "Edit");
+
+  setting.addButton((btn) => {
+    setLabel(btn);
+
+    btn.onClick(() => {
+      new ListEditorModal(app, {
+        title: name,
+        placeholder: modal.placeholder,
+        emptyNote: modal.emptyNote,
+        recommended: modal.recommended,
+        values: current,
+        onChange: (next) => {
+          current = next;
+          saveSetting({ [key]: current });
+          setLabel(btn);
+        },
+      }).open();
+    });
+  });
+
+  return setting;
+}
+
+export { display };

packages/bridge/src/settings/inject.js

@@ -1,14 +1,14 @@
-const generalTab = require("./general-tab");
-const serverPluginsTab = require("./server-plugins-tab");
-const { createNavEl, createTab, createGroup } = require("./settings-ui");
-const {
+import * as generalTab from "./general-tab.js";
+import * as serverPluginsTab from "./server-plugins-tab.js";
+import { createNavEl, createTab, createGroup } from "./settings-ui.js";
+import {
   allIgnisNavEls,
   setupPluginTabs,
   reconcilePluginTabs,
   hideIgnisFromCommunityPlugins,
   restoreCommunityPlugins,
   clearOwnedPluginIds,
-} = require("./plugin-tabs");
+} from "./plugin-tabs.js";
 
 function removeExistingIgnisGroups(tabHeadersEl) {
   const groups = tabHeadersEl.querySelectorAll(".vertical-tab-header-group");
@@ -139,4 +139,4 @@ function unpatchSettingsModal(plugin) {
   clearOwnedPluginIds();
 }
 
-module.exports = { patchSettingsModal, unpatchSettingsModal, reconcilePluginTabs };
+export { patchSettingsModal, unpatchSettingsModal, reconcilePluginTabs };

packages/bridge/src/settings/list-editor-modal.js

@@ -0,0 +1,134 @@
+import { Modal, Setting, Notice } from "obsidian";
+
+// Modal editor for a list of string entries (the proxy host allowlist).
+class ListEditorModal extends Modal {
+  constructor(app, opts) {
+    super(app);
+    this.opts = opts;
+    this.values = [...(opts.values || [])];
+  }
+
+  onOpen() {
+    this.titleEl.setText(this.opts.title);
+
+    if (this.opts.recommended) {
+      new Setting(this.contentEl)
+        .setDesc(this.opts.recommended.note)
+        .addButton((btn) =>
+          btn
+            .setButtonText(
+              this.opts.recommended.buttonText || "Add recommended",
+            )
+            .onClick(() => this.addRecommended()),
+        );
+    }
+
+    this.listEl = this.contentEl.createDiv("ignis-list-editor");
+    this.renderList();
+
+    new Setting(this.contentEl)
+      .setName("Add entry")
+      .addText((text) => {
+        this.input = text;
+        text.setPlaceholder(this.opts.placeholder || "");
+
+        text.inputEl.addEventListener("keydown", (e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            this.addCurrent();
+          }
+        });
+      })
+      .addButton((btn) =>
+        btn
+          .setButtonText("Add")
+          .setCta()
+          .onClick(() => this.addCurrent()),
+      );
+  }
+
+  addEntry(entry) {
+    if (this.values.includes(entry)) {
+      return false;
+    }
+
+    this.values.push(entry);
+    return true;
+  }
+
+  addCurrent() {
+    const entry = this.input.getValue().trim();
+
+    if (!entry) {
+      return;
+    }
+
+    if (!this.addEntry(entry)) {
+      new Notice("That entry is already in the list.");
+      return;
+    }
+
+    this.input.setValue("");
+    this.input.inputEl.focus();
+    this.commit();
+    this.renderList();
+  }
+
+  addRecommended() {
+    let added = 0;
+
+    for (const host of this.opts.recommended.hosts) {
+      if (this.addEntry(host)) {
+        added++;
+      }
+    }
+
+    if (added > 0) {
+      this.commit();
+      this.renderList();
+    }
+
+    new Notice(
+      added > 0
+        ? `Added ${added} host${added === 1 ? "" : "s"}.`
+        : "All recommended hosts are already in the list.",
+    );
+  }
+
+  remove(entry) {
+    this.values = this.values.filter((v) => v !== entry);
+    this.commit();
+    this.renderList();
+  }
+
+  renderList() {
+    this.listEl.empty();
+
+    if (this.values.length === 0) {
+      this.listEl.createDiv({
+        text: this.opts.emptyNote,
+        cls: "ignis-list-empty",
+      });
+      return;
+    }
+
+    for (const entry of this.values) {
+      new Setting(this.listEl).setName(entry).addExtraButton((btn) =>
+        btn
+          .setIcon("trash-2")
+          .setTooltip("Remove")
+          .onClick(() => this.remove(entry)),
+      );
+    }
+  }
+
+  commit() {
+    this.opts.onChange([...this.values]);
+  }
+
+  onClose() {
+    this.contentEl.empty();
+  }
+}
+
+export { ListEditorModal };

packages/bridge/src/settings/plugin-tabs.js

@@ -1,6 +1,6 @@
-const { setIcon } = require("obsidian");
-const { findGroupByTitle } = require("./settings-ui");
-const { isIgnisPlugin } = require("../plugin-registry");
+import { setIcon } from "obsidian";
+import { findGroupByTitle } from "./settings-ui.js";
+import { isIgnisPlugin } from "../plugin-registry.js";
 
 // All ignis-managed nav elements (both Ignis group and Ignis Core Plugins group).
 // Shared with inject.js so the openTab patch can manage is-active across all of them.
@@ -232,7 +232,7 @@ function clearOwnedPluginIds() {
   ownedPluginIds.clear();
 }
 
-module.exports = {
+export {
   allIgnisNavEls,
   setupPluginTabs,
   reconcilePluginTabs,

packages/bridge/src/settings/server-plugins-tab.js

@@ -1,5 +1,5 @@
-const { Setting, Notice } = require("obsidian");
-const { reconcilePluginTabs } = require("./plugin-tabs");
+import { Setting, Notice } from "obsidian";
+import { reconcilePluginTabs } from "./plugin-tabs.js";
 
 function getVaultId() {
   return window.__currentVaultId || "";
@@ -94,4 +94,4 @@ function display(containerEl, app) {
     });
 }
 
-module.exports = { display };
+export { display };

packages/bridge/src/settings/settings-ui.js

@@ -1,4 +1,4 @@
-const { setIcon } = require("obsidian");
+import { setIcon } from "obsidian";
 
 function createNavEl(tab, setting) {
   const nav = document.createElement("div");
@@ -86,4 +86,4 @@ function findGroupByTitle(tabHeadersEl, title) {
   return null;
 }
 
-module.exports = { createNavEl, createTab, createGroup, findGroupByTitle };
+export { createNavEl, createTab, createGroup, findGroupByTitle };

packages/bridge/src/status-bar.js

@@ -32,4 +32,4 @@ function initStatusBar(plugin) {
   return ws.onStateChange(render);
 }
 
-module.exports = { initStatusBar };
+export { initStatusBar };

packages/bridge/src/util/version.js

@@ -0,0 +1,39 @@
+// Version comparison helpers for the update check.
+
+// SemVer build metadata (`+xyz`) is informational and ignored for precedence.
+function stripBuildMetadata(version) {
+  return (version || "").split("+")[0];
+}
+
+// Parse X.Y.Z to [major, minor, patch], or null when it isn't three integers.
+function parseSemver(version) {
+  const parts = (version || "").split(".");
+
+  if (parts.length < 3) {
+    return null;
+  }
+
+  const nums = parts.slice(0, 3).map((p) => parseInt(p, 10));
+
+  return nums.some((n) => !Number.isInteger(n)) ? null : nums;
+}
+
+// True only when latest is strictly newer than current.
+function isNewer(latest, current) {
+  const a = parseSemver(latest);
+  const b = parseSemver(current);
+
+  if (!a || !b) {
+    return false;
+  }
+
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) {
+      return a[i] > b[i];
+    }
+  }
+
+  return false;
+}
+
+export { stripBuildMetadata, parseSemver, isNewer };

packages/bridge/src/util/version.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { stripBuildMetadata, isNewer } from "./version.js";
+
+describe("isNewer", () => {
+  it("is true when latest is strictly newer", () => {
+    expect(isNewer("0.8.4", "0.8.3")).toBe(true);
+    expect(isNewer("1.0.0", "0.9.9")).toBe(true);
+    expect(isNewer("0.9.0", "0.8.9")).toBe(true);
+  });
+
+  it("is false for older or equal, so no downgrade is prompted", () => {
+    expect(isNewer("0.8.3", "0.8.4")).toBe(false);
+    expect(isNewer("0.8.4", "0.8.4")).toBe(false);
+    expect(isNewer("0.9.9", "1.0.0")).toBe(false);
+  });
+
+  it("is false for malformed versions", () => {
+    expect(isNewer("x", "0.8.4")).toBe(false);
+    expect(isNewer("0.8", "0.8.4")).toBe(false);
+    expect(isNewer("1.x.0", "0.8.4")).toBe(false);
+  });
+
+  it("ignores build metadata, so an equal version with a build tag is not newer", () => {
+    expect(
+      isNewer(stripBuildMetadata("0.8.4"), stripBuildMetadata("0.8.4+q2fmfox")),
+    ).toBe(false);
+  });
+});

packages/bridge/src/workspace-picker.js

@@ -1,4 +1,4 @@
-const { FuzzySuggestModal } = require("obsidian");
+import { FuzzySuggestModal } from "obsidian";
 
 class WorkspacePickerModal extends FuzzySuggestModal {
   constructor(app) {
@@ -29,4 +29,4 @@ class WorkspacePickerModal extends FuzzySuggestModal {
   }
 }
 
-module.exports = { WorkspacePickerModal };
+export { WorkspacePickerModal };

packages/bridge/styles.css

@@ -141,3 +141,18 @@
   font-size: var(--font-ui-small);
   margin-bottom: 16px;
 }
+
+.ignis-list-editor {
+  border: 1px solid var(--background-modifier-border);
+  border-radius: var(--radius-m);
+  max-height: 220px;
+  overflow-y: auto;
+  padding: 0 var(--size-4-3);
+  margin-bottom: var(--size-4-4);
+}
+
+.ignis-list-empty {
+  color: var(--text-muted);
+  font-size: var(--font-ui-smaller);
+  padding: var(--size-4-3) 0;
+}

packages/server-core/src/write-coalescer.js

@@ -31,9 +31,19 @@ async function writeToDisk(absPath, data, encoding) {
   );
 
   lastWriteTime.set(absPath, Date.now());
-  const stat = await fs.promises.stat(absPath);
 
-  return { mtime: stat.mtimeMs, size: stat.size };
+  // A concurrent delete can remove the file between the write and the stat (a rapid write-then-delete on the same path).
+  // The write itself succeeds, so report synthetic metadata rather than failing the request on the now-missing file.
+  try {
+    const stat = await fs.promises.stat(absPath);
+    return { mtime: stat.mtimeMs, size: stat.size };
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return { mtime: Date.now(), size: estimateSize(data, encoding) };
+    }
+
+    throw e;
+  }
 }
 
 function flushEntry(absPath) {

packages/server-core/src/write-coalescer.test.mjs

@@ -99,6 +99,18 @@ describe("writeCoalesced", () => {
 
     expect(elapsed).toBeLessThan(20);
   });
+
+  it("returns synthetic metadata when the file is deleted before the post-write stat", async () => {
+    const filePath = path.join(tmpDir, "race.txt");
+    vi.spyOn(fs.promises, "stat").mockRejectedValueOnce(
+      Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+    );
+
+    const result = await coalescer.writeCoalesced(filePath, "hello", "utf-8");
+
+    expect(result.size).toBe(5);
+    expect(result.mtime).toBeGreaterThan(0);
+  });
 });
 
 describe("getPending", () => {

packages/server-core/src/ws.js

@@ -2,6 +2,27 @@ const { WebSocketServer } = require("ws");
 const url = require("url");
 const watcher = require("./watcher");
 
+// Null / undefined / empty array means no Origin check.
+function toOriginSet(list) {
+  return Array.isArray(list) && list.length > 0 ? new Set(list) : null;
+}
+
+const HEARTBEAT_INTERVAL_MS = 30000;
+
+// Terminates sockets that have not ponged since the previous sweep, and pings the rest.
+// A socket silently dropped by an idle-timeout proxy fails the next isAlive check and is terminated.
+function heartbeatSweep(clients) {
+  for (const ws of clients) {
+    if (ws.isAlive === false) {
+      ws.terminate();
+      continue;
+    }
+
+    ws.isAlive = false;
+    ws.ping();
+  }
+}
+
 function setupWebSocket(server, opts = {}) {
   const { getVaultPath, originAllowlist } = opts;
 
@@ -9,11 +30,7 @@ function setupWebSocket(server, opts = {}) {
     throw new Error("setupWebSocket: opts.getVaultPath is required");
   }
 
-  // Null / undefined / empty array = no Origin check.
-  const originSet =
-    Array.isArray(originAllowlist) && originAllowlist.length > 0
-      ? new Set(originAllowlist)
-      : null;
+  const originSet = toOriginSet(originAllowlist);
 
   const wss = new WebSocketServer({ server, path: "/ws" });
 
@@ -125,6 +142,12 @@ function setupWebSocket(server, opts = {}) {
     const vaultPath = getVaultPath(vaultId);
     console.log(`[ws] Client connected to vault: ${vaultId}`);
 
+    // isAlive is reset by each pong; the heartbeat sweep terminates sockets that miss one.
+    ws.isAlive = true;
+    ws.on("pong", () => {
+      ws.isAlive = true;
+    });
+
     if (!clientsByVault.has(vaultId)) {
       clientsByVault.set(vaultId, new Set());
     }
@@ -208,7 +231,16 @@ function setupWebSocket(server, opts = {}) {
     });
   });
 
+  // Terminate dead connections behind proxies that silently drop idle sockets.
+  const heartbeat = setInterval(
+    () => heartbeatSweep(wss.clients),
+    HEARTBEAT_INTERVAL_MS,
+  );
+  heartbeat.unref?.();
+
+  wss.on("close", () => clearInterval(heartbeat));
+
   return wss;
 }
 
-module.exports = { setupWebSocket };
+module.exports = { setupWebSocket, heartbeatSweep };

packages/server-core/src/ws.test.mjs

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from "vitest";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const { heartbeatSweep } = require("./ws.js");
+
+function fakeSocket(isAlive) {
+  return { isAlive, ping: vi.fn(), terminate: vi.fn() };
+}
+
+describe("ws heartbeat sweep", () => {
+  it("terminates a socket that has not ponged since the last sweep", () => {
+    const dead = fakeSocket(false);
+
+    heartbeatSweep([dead]);
+
+    expect(dead.terminate).toHaveBeenCalledTimes(1);
+    expect(dead.ping).not.toHaveBeenCalled();
+  });
+
+  it("pings a live socket and marks it pending until its next pong", () => {
+    const alive = fakeSocket(true);
+
+    heartbeatSweep([alive]);
+
+    expect(alive.ping).toHaveBeenCalledTimes(1);
+    expect(alive.terminate).not.toHaveBeenCalled();
+    expect(alive.isAlive).toBe(false);
+  });
+
+  it("terminates the dead and pings the live in the same sweep", () => {
+    const dead = fakeSocket(false);
+    const alive = fakeSocket(true);
+
+    heartbeatSweep(new Set([dead, alive]));
+
+    expect(dead.terminate).toHaveBeenCalledTimes(1);
+    expect(dead.ping).not.toHaveBeenCalled();
+    expect(alive.ping).toHaveBeenCalledTimes(1);
+    expect(alive.terminate).not.toHaveBeenCalled();
+    expect(alive.isAlive).toBe(false);
+  });
+});

packages/shim/src/electron/ipc-renderer.js

@@ -1,6 +1,6 @@
 import { showVaultManager } from "../ui-registry.js";
 import { vaultService } from "@ignis/services";
-import { arrayBufferToBase64, base64ToArrayBuffer } from "../util/base64.js";
+import { proxyFetch } from "../util/proxy.js";
 
 const listeners = new Map();
 
@@ -88,41 +88,19 @@ const syncHandlers = {
 
 async function handleRequestUrl(requestId, request) {
   try {
-    let body = request.body;
-    let binary = false;
-
-    if (body instanceof ArrayBuffer) {
-      body = arrayBufferToBase64(body);
-      binary = true;
-    }
-
-    const res = await fetch("/api/proxy", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        url: request.url,
-        method: request.method || "GET",
-        headers: request.headers || {},
-        contentType: request.contentType,
-        body,
-        binary,
-      }),
+    const result = await proxyFetch({
+      url: request.url,
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      contentType: request.contentType,
     });
 
-    const proxyResult = await res.json();
-
-    if (!res.ok) {
-      ipcRenderer._emit(requestId, {
-        error: proxyResult.error || "Proxy request failed",
-      });
-      return;
-    }
-
     // Electron's e.reply(requestId, data) sends on the requestId channel
     ipcRenderer._emit(requestId, {
-      status: proxyResult.status,
-      headers: proxyResult.headers,
-      body: base64ToArrayBuffer(proxyResult.body),
+      status: result.status,
+      headers: result.headers,
+      body: result.body,
     });
   } catch (e) {
     ipcRenderer._emit(requestId, {

packages/shim/src/fs/callback.js

@@ -0,0 +1,34 @@
+const CALLBACK_METHODS = [
+  "stat",
+  "lstat",
+  "readdir",
+  "readFile",
+  "writeFile",
+  "appendFile",
+  "unlink",
+  "rename",
+  "mkdir",
+  "rmdir",
+  "rm",
+  "copyFile",
+  "access",
+  "utimes",
+  "chmod",
+];
+
+export function createFsCallbacks(fsPromises) {
+  const callbacks = {};
+
+  for (const name of CALLBACK_METHODS) {
+    callbacks[name] = function (...args) {
+      const callback = args.pop();
+
+      fsPromises[name](...args).then(
+        (result) => callback(null, result),
+        (err) => callback(err),
+      );
+    };
+  }
+
+  return callbacks;
+}

packages/shim/src/fs/callback.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { createFsCallbacks } from "./callback.js";
+
+describe("fs callbacks", () => {
+  it("resolves the promise result through the callback", async () => {
+    const fakePromises = { readFile: async (p) => `data:${p}` };
+    const cb = createFsCallbacks(fakePromises);
+
+    const result = await new Promise((resolve) =>
+      cb.readFile("/x", (err, data) => resolve([err, data])),
+    );
+
+    expect(result).toEqual([null, "data:/x"]);
+  });
+
+  it("passes a rejection to the callback as the error argument", async () => {
+    const boom = new Error("nope");
+    const fakePromises = {
+      stat: async () => {
+        throw boom;
+      },
+    };
+    const cb = createFsCallbacks(fakePromises);
+
+    const result = await new Promise((resolve) =>
+      cb.stat("/x", (err) => resolve(err)),
+    );
+
+    expect(result).toBe(boom);
+  });
+
+  it("forwards the arguments that precede the callback", async () => {
+    let received = null;
+    const fakePromises = {
+      mkdir: async (p, opts) => {
+        received = [p, opts];
+      },
+    };
+    const cb = createFsCallbacks(fakePromises);
+
+    await new Promise((resolve) =>
+      cb.mkdir("/d", { recursive: true }, () => resolve()),
+    );
+
+    expect(received).toEqual(["/d", { recursive: true }]);
+  });
+});

packages/shim/src/fs/content-cache.js

@@ -10,6 +10,14 @@ export class ContentCache {
     this._maxSize = maxSize;
   }
 
+  setMaxSize(maxSize) {
+    this._maxSize = maxSize;
+
+    while (this._currentSize > this._maxSize && this._cache.size > 0) {
+      this._evictOne();
+    }
+  }
+
   has(path) {
     return this._cache.has(this._normalize(path));
   }

packages/shim/src/fs/fd.js

@@ -1,9 +1,8 @@
-// File descriptor shim  -  maps fake integer fds to in-memory file buffers.
-// Enables libraries like yauzl that use fs.open/fs.read/fs.close to seek
-// around files without loading them via readFileSync upfront.
+// File descriptor shim. Maps fake integer fds to in-memory file buffers.
 
 import { isInputCachePath, inputCacheGet } from "./input-cache.js";
 import { resolvePath } from "./transforms.js";
+import { hasVirtualFile, getVirtualFile } from "./virtual-files.js";
 
 let nextFd = 100;
 const openFiles = new Map();
@@ -24,6 +23,15 @@ export function createFdOps(metadataCache, contentCache, transport) {
     }
 
     const resolved = resolvePath(path);
+
+    if (hasVirtualFile(resolved)) {
+      const content = getVirtualFile(resolved);
+
+      return typeof content === "string"
+        ? new TextEncoder().encode(content)
+        : content;
+    }
+
     const cached = contentCache.get(resolved);
 
     if (cached !== null) {
@@ -60,7 +68,11 @@ export function createFdOps(metadataCache, contentCache, transport) {
     const hasInCache = isInputCachePath(path) && inputCacheGet(path) !== null;
     const resolved = resolvePath(path);
 
-    if (!hasInCache && !metadataCache.has(resolved)) {
+    if (
+      !hasInCache &&
+      !hasVirtualFile(resolved) &&
+      !metadataCache.has(resolved)
+    ) {
       const err = new Error(
         `ENOENT: no such file or directory, open '${path}'`,
       );

packages/shim/src/fs/index.js

@@ -6,6 +6,8 @@ import { createFsSync } from "./sync.js";
 import { createFsWatch } from "./watch.js";
 import { createWatcherClient } from "./watcher-client.js";
 import { createFdOps } from "./fd.js";
+import { createFsCallbacks } from "./callback.js";
+import { realpath, realpathSync } from "./realpath.js";
 import { constants } from "./constants.js";
 import { registerReadTransform, removeReadTransform, resolvePath } from "./transforms.js";
 import { wsClient } from "../ws-client.js";
@@ -16,12 +18,21 @@ const contentCache = new ContentCache();
 const fsPromises = createFsPromises(metadataCache, contentCache, transport);
 const fsSync = createFsSync(metadataCache, contentCache, transport);
 const fsWatch = createFsWatch(transport);
-const watcherClient = createWatcherClient(metadataCache, contentCache, fsWatch, wsClient);
+const watcherClient = createWatcherClient(
+  metadataCache,
+  contentCache,
+  fsWatch,
+  wsClient,
+  transport,
+);
 const fdOps = createFdOps(metadataCache, contentCache, transport);
+const fsCallbacks = createFsCallbacks(fsPromises);
 
 export const fsShim = {
   promises: fsPromises,
 
+  ...fsCallbacks,
+
   existsSync: fsSync.existsSync,
   readFileSync: fsSync.readFileSync,
   writeFileSync: fsSync.writeFileSync,
@@ -29,6 +40,18 @@ export const fsShim = {
   accessSync: fsSync.accessSync,
   statSync: fsSync.statSync,
   readdirSync: fsSync.readdirSync,
+  lstatSync: fsSync.lstatSync,
+  mkdirSync: fsSync.mkdirSync,
+  rmdirSync: fsSync.rmdirSync,
+  rmSync: fsSync.rmSync,
+  renameSync: fsSync.renameSync,
+  copyFileSync: fsSync.copyFileSync,
+  appendFileSync: fsSync.appendFileSync,
+  utimesSync: fsSync.utimesSync,
+  chmodSync: fsSync.chmodSync,
+
+  realpath,
+  realpathSync,
 
   open: fdOps.open,
   openSync: fdOps.openSync,

packages/shim/src/fs/indexer-prefetch.js

@@ -1,10 +1,7 @@
-// Eager batch pre-fetch of vault content into ContentCache.
-//
-// Fired once after the metadata cache is populated. Iterates the tree in
-// directory-traversal order and pulls text file contents in batches via
-// /api/fs/batch-read. Caps at MAX_BYTES so it doesn't thrash the LRU.
-// Drops content directly into ContentCache; the indexer hits the cache
-// instead of fetching each file individually.
+// Batch pre-fetch of vault content into ContentCache.
+// Pulls text file contents in batches via /api/fs/batch-read and drops them into ContentCache so Obsidian's startup reads hit the cache instead of fetching each file individually.
+// The priority slice (.obsidian configs and plugin entry files) is fetched first and its promise resolves once it lands, so boot can wait for those reads to be warm.
+// The bulk slice (everything else) streams afterward without blocking boot.
 
 const TEXT_EXTENSIONS = new Set([
   ".md", ".markdown", ".txt", ".json", ".csv",
@@ -13,8 +10,12 @@ const TEXT_EXTENSIONS = new Set([
   ".svg",
 ]);
 
-const MAX_BYTES = 30 * 1024 * 1024; // 30 MB
-const MAX_FILE_BYTES = 512 * 1024; // skip files larger than 512 KB
+const MAX_BYTES = 30 * 1024 * 1024; // 30 MB total across both slices
+const MAX_FILE_BYTES = 512 * 1024; // skip bulk files larger than 512 KB
+// Plugin main.js bundles can run a few MB and Obsidian needs them at boot, so the priority slice accepts larger files than the bulk slice.
+const PRIORITY_MAX_FILE_BYTES = 4 * 1024 * 1024; // 4 MB
+// Cap the priority slice's share of the total so a heavy config or plugin set cannot starve the bulk slice.
+const PRIORITY_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
 const BATCH_SIZE = 50;
 
 function isTextPath(path) {
@@ -27,36 +28,68 @@ function isTextPath(path) {
   return TEXT_EXTENSIONS.has(path.slice(dot).toLowerCase());
 }
 
-function selectPrefetchTargets(tree) {
-  const paths = [];
+// Boot-critical files: root-level .obsidian configs and each plugin's entry files.
+// Plugin data.json and other nested config fall to the bulk slice so a large blob does not inflate the awaited slice.
+function isPriorityPath(path) {
+  if (!path.startsWith(".obsidian/")) {
+    return false;
+  }
+
+  // Root-level configs only (app.json, appearance.json, core-plugins.json, workspace.json, etc.).
+  if (/^\.obsidian\/[^/]+\.json$/.test(path)) {
+    return true;
+  }
+
+  return /^\.obsidian\/plugins\/[^/]+\/(main\.js|manifest\.json|styles\.css)$/.test(
+    path,
+  );
+}
+
+function collectSlice(entries, predicate, perFileCap, budget) {
+  const files = [];
   let bytes = 0;
 
-  // Iterate in tree key order, which already matches directory traversal
-  // because the server's walk emits parent-before-children.
-  for (const [path, entry] of Object.entries(tree)) {
-    if (entry.type !== "file") {
-      continue;
-    }
-
-    if (!isTextPath(path)) {
+  for (const [path, entry] of entries) {
+    if (entry.type !== "file" || !isTextPath(path) || !predicate(path)) {
       continue;
     }
 
     const size = entry.size || 0;
 
-    if (size === 0 || size > MAX_FILE_BYTES) {
+    if (size === 0 || size > perFileCap) {
       continue;
     }
 
-    if (bytes + size > MAX_BYTES) {
-      break;
+    if (bytes + size > budget) {
+      continue;
     }
 
-    paths.push(path);
+    files.push({ path, size });
     bytes += size;
   }
 
-  return { paths, bytes };
+  return { files, bytes };
+}
+
+function selectPrefetchTargets(tree) {
+  // Tree key order matches directory traversal (the server walk emits parent before children).
+  const entries = Object.entries(tree);
+  const priority = collectSlice(
+    entries,
+    isPriorityPath,
+    PRIORITY_MAX_FILE_BYTES,
+    PRIORITY_MAX_BYTES,
+  );
+
+  // Bulk fills whatever byte budget the priority slice left.
+  const bulk = collectSlice(
+    entries,
+    (path) => !isPriorityPath(path),
+    MAX_FILE_BYTES,
+    MAX_BYTES - priority.bytes,
+  );
+
+  return { priority, bulk };
 }
 
 async function fetchBatch(vaultId, paths) {
@@ -73,41 +106,84 @@ async function fetchBatch(vaultId, paths) {
   return res.json();
 }
 
-export async function prefetchVaultContent(vaultId, tree, contentCache) {
-  if (!vaultId || !tree) {
-    return;
-  }
-
-  const { paths, bytes } = selectPrefetchTargets(tree);
-
-  if (paths.length === 0) {
+async function runBatches(vaultId, slice, contentCache, label, onProgress) {
+  if (slice.files.length === 0) {
     return;
   }
 
   const t0 = Date.now();
   let cached = 0;
+  let received = 0;
 
-  for (let i = 0; i < paths.length; i += BATCH_SIZE) {
-    const batch = paths.slice(i, i + BATCH_SIZE);
+  // Report the total up front so the splash shows the target before the first batch lands.
+  if (onProgress) {
+    onProgress(0, slice.bytes);
+  }
+
+  for (let i = 0; i < slice.files.length; i += BATCH_SIZE) {
+    const batch = slice.files.slice(i, i + BATCH_SIZE);
+
+    let result;
 
     try {
-      const result = await fetchBatch(vaultId, batch);
-
-      for (const [path, content] of Object.entries(result.files || {})) {
-        if (typeof content === "string") {
-          contentCache.set(path, content);
-          cached++;
-        }
-      }
+      result = await fetchBatch(
+        vaultId,
+        batch.map((f) => f.path),
+      );
     } catch (e) {
-      console.warn("[ignis] Prefetch batch failed:", e.message);
+      // Abandon the rest of this slice; the returned promise still resolves so boot is never blocked on a failed batch.
+      console.warn(`[ignis] Prefetch ${label} batch failed:`, e.message);
       return;
     }
+
+    for (const [path, content] of Object.entries(result.files || {})) {
+      if (typeof content === "string") {
+        contentCache.set(path, content);
+        cached++;
+      }
+    }
+
+    if (onProgress) {
+      for (const f of batch) {
+        received += f.size;
+      }
+
+      onProgress(received, slice.bytes);
+    }
   }
 
   const ms = Date.now() - t0;
 
   console.log(
-    `[ignis] Prefetched ${cached}/${paths.length} files (${(bytes / 1024).toFixed(0)} KB) in ${ms}ms`,
+    `[ignis] Prefetched ${label} ${cached}/${slice.files.length} files (${(slice.bytes / 1024).toFixed(0)} KB) in ${ms}ms`,
   );
 }
+
+// Returns { priority, bulk }: a promise for each slice.
+// The priority promise resolves once the boot-critical files have landed (or were abandoned on a batch failure), so it is always safe to await.
+export function prefetchVaultContent(vaultId, tree, contentCache, options = {}) {
+  if (!vaultId || !tree) {
+    return { priority: Promise.resolve(), bulk: Promise.resolve() };
+  }
+
+  const { priority, bulk } = selectPrefetchTargets(tree);
+
+  const priorityDone = runBatches(
+    vaultId,
+    priority,
+    contentCache,
+    "priority",
+    options.onProgress,
+  );
+
+  // Bulk streams after the priority slice so it does not contend for the connection pool while boot is waiting on priority.
+  // It runs regardless of how priority settled and swallows its own rejection, since init.js discards this promise.
+  const bulkDone = priorityDone
+    .catch(() => {})
+    .then(() => runBatches(vaultId, bulk, contentCache, "bulk"))
+    .catch((e) => {
+      console.warn("[ignis] Prefetch bulk failed:", e && e.message);
+    });
+
+  return { priority: priorityDone, bulk: bulkDone };
+}

packages/shim/src/fs/indexer-prefetch.test.js

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { prefetchVaultContent } from "./indexer-prefetch.js";
+
+const MB = 1024 * 1024;
+
+// Every selection rule.
+const tree = {
+  ".obsidian/app.json": { type: "file", size: 100 },
+  ".obsidian/community-plugins.json": { type: "file", size: 50 },
+  ".obsidian/plugins/big/main.js": { type: "file", size: 2 * MB },
+  ".obsidian/plugins/big/manifest.json": { type: "file", size: 80 },
+  ".obsidian/plugins/big/styles.css": { type: "file", size: 200 },
+  ".obsidian/plugins/big/data.json": { type: "file", size: 300 * 1024 },
+  "Note.md": { type: "file", size: 100 },
+  "Big.md": { type: "file", size: 600 * 1024 },
+  "plugins/fake/main.js": { type: "file", size: 100 },
+  somedir: { type: "directory" },
+};
+
+const PRIORITY_BYTES = 100 + 50 + 2 * MB + 80 + 200;
+
+let fetchCalls;
+
+function makeCache() {
+  const store = new Map();
+  return { store, set: (path, content) => store.set(path, content) };
+}
+
+beforeEach(() => {
+  fetchCalls = [];
+  globalThis.fetch = vi.fn(async (url, init) => {
+    const paths = JSON.parse(init.body).paths;
+    fetchCalls.push(paths);
+
+    const files = {};
+
+    for (const p of paths) {
+      files[p] = "content:" + p;
+    }
+
+    return { ok: true, json: async () => ({ files }) };
+  });
+});
+
+afterEach(() => {
+  delete globalThis.fetch;
+  vi.restoreAllMocks();
+});
+
+describe("prefetchVaultContent slicing", () => {
+  it("fetches the priority slice before the bulk slice", async () => {
+    const result = prefetchVaultContent("v", tree, makeCache());
+    await result.bulk;
+
+    expect(fetchCalls.length).toBe(2);
+    const [priorityPaths, bulkPaths] = fetchCalls;
+
+    expect(priorityPaths).toEqual(
+      expect.arrayContaining([
+        ".obsidian/app.json",
+        ".obsidian/community-plugins.json",
+        ".obsidian/plugins/big/main.js",
+        ".obsidian/plugins/big/manifest.json",
+        ".obsidian/plugins/big/styles.css",
+      ]),
+    );
+    expect(priorityPaths).not.toContain("Note.md");
+
+    expect(bulkPaths).toEqual(
+      expect.arrayContaining(["Note.md", "plugins/fake/main.js"]),
+    );
+  });
+
+  it("anchors the plugin predicate to .obsidian, so a bare plugins/ path is bulk", async () => {
+    const result = prefetchVaultContent("v", tree, makeCache());
+    await result.bulk;
+
+    expect(fetchCalls[0]).not.toContain("plugins/fake/main.js");
+    expect(fetchCalls[1]).toContain("plugins/fake/main.js");
+  });
+
+  it("leaves plugin data.json to the bulk slice, not priority", async () => {
+    const result = prefetchVaultContent("v", tree, makeCache());
+    await result.bulk;
+
+    expect(fetchCalls[0]).not.toContain(".obsidian/plugins/big/data.json");
+    expect(fetchCalls[1]).toContain(".obsidian/plugins/big/data.json");
+  });
+
+  it("caps the priority slice at its own byte budget", async () => {
+    // Three 4MB plugin entry files: two fit the 10MB priority budget, the third is dropped.
+    const bigTree = {
+      ".obsidian/plugins/a/main.js": { type: "file", size: 4 * MB },
+      ".obsidian/plugins/b/main.js": { type: "file", size: 4 * MB },
+      ".obsidian/plugins/c/main.js": { type: "file", size: 4 * MB },
+    };
+
+    const result = prefetchVaultContent("v", bigTree, makeCache());
+    await result.bulk;
+
+    expect(fetchCalls[0].length).toBe(2);
+  });
+
+  it("drops a bulk file over the 512KB per-file cap", async () => {
+    const result = prefetchVaultContent("v", tree, makeCache());
+    await result.bulk;
+
+    expect(fetchCalls.flat()).not.toContain("Big.md");
+  });
+
+  it("reports priority byte progress from zero up to the slice total", async () => {
+    const onProgress = vi.fn();
+    const result = prefetchVaultContent("v", tree, makeCache(), { onProgress });
+    await result.priority;
+
+    expect(onProgress).toHaveBeenCalledWith(0, PRIORITY_BYTES);
+    expect(onProgress).toHaveBeenLastCalledWith(PRIORITY_BYTES, PRIORITY_BYTES);
+  });
+
+  it("caches returned content under its path", async () => {
+    const cache = makeCache();
+    const result = prefetchVaultContent("v", tree, cache);
+    await result.bulk;
+
+    expect(cache.store.get(".obsidian/app.json")).toBe(
+      "content:.obsidian/app.json",
+    );
+    expect(cache.store.get("Note.md")).toBe("content:Note.md");
+  });
+
+  it("resolves both promises without fetching when there is no vault", async () => {
+    const result = prefetchVaultContent("", tree, makeCache());
+
+    await result.priority;
+    await result.bulk;
+
+    expect(fetchCalls.length).toBe(0);
+  });
+
+  it("resolves the priority promise even when a batch fails", async () => {
+    globalThis.fetch = vi.fn(async () => ({ ok: false, status: 500 }));
+
+    const result = prefetchVaultContent("v", tree, makeCache());
+
+    await expect(result.priority).resolves.toBeUndefined();
+  });
+});

packages/shim/src/fs/input-cache.js

@@ -7,8 +7,8 @@
 
 import { normalize } from "../util/path.js";
 
-const MAX_SIZE = 200 * 1024 * 1024;
-const TTL_MS = 5 * 60 * 1000;
+let MAX_SIZE = 200 * 1024 * 1024;
+let TTL_MS = 5 * 60 * 1000;
 
 const cache = new Map(); // path -> { data, size, createdAt }
 let currentSize = 0;
@@ -112,6 +112,20 @@ export function inputCacheClear() {
   currentSize = 0;
 }
 
+export function setInputCacheLimits({ maxSize, ttlMs }) {
+  if (Number.isFinite(maxSize)) {
+    MAX_SIZE = maxSize;
+
+    while (currentSize > MAX_SIZE && cache.size > 0) {
+      evictOldest();
+    }
+  }
+
+  if (Number.isFinite(ttlMs)) {
+    TTL_MS = ttlMs;
+  }
+}
+
 export function isInputCachePath(path) {
   const norm = normalize(path);
   return norm.startsWith(".obsidian/imports/");

packages/shim/src/fs/metadata-cache.js

@@ -93,6 +93,11 @@ export class MetadataCache {
     return this._entries.size;
   }
 
+  // Normalized keys of every entry, for callers that diff the cache against a fresh tree.
+  keys() {
+    return [...this._entries.keys()];
+  }
+
   toStat(path) {
     const meta = this.get(path);
 

packages/shim/src/fs/promises-mutations.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { createFsPromises } from "./promises.js";
+import { registerPathResolver, _reset } from "./transforms.js";
+import { isRecentLocalOp } from "./echo-guard.js";
+
+function makeDeps() {
+  const store = new Map();
+
+  const metadataCache = {
+    has: (p) => store.has(p),
+    get: (p) => (store.has(p) ? store.get(p) : null),
+    set: (p, m) => store.set(p, m),
+    delete: (p) => store.delete(p),
+    toStat: (p) =>
+      store.has(p)
+        ? {
+            type: store.get(p).type,
+            isDirectory: () => store.get(p).type === "directory",
+            isFile: () => store.get(p).type === "file",
+          }
+        : null,
+    readdir: () => [],
+  };
+
+  const contentCache = {
+    get: () => null,
+    set: vi.fn(),
+    delete: vi.fn(),
+    invalidate: vi.fn(),
+  };
+
+  const transport = {
+    mkdir: vi.fn(async () => {}),
+    rmdir: vi.fn(async () => {}),
+    stat: vi.fn(async () => ({ type: "file", size: 1 })),
+    readFile: vi.fn(async () => {
+      throw new Error("transport.readFile should not be called");
+    }),
+  };
+
+  return { metadataCache, contentCache, transport, store };
+}
+
+describe("promises directory mutations honor path resolvers", () => {
+  afterEach(() => _reset());
+
+  it("mkdir uses the resolved path for cache, echo-guard, and transport", async () => {
+    registerPathResolver(
+      (p) => p === "logical/dir",
+      () => "physical/dir",
+    );
+
+    const deps = makeDeps();
+    const fs = createFsPromises(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    await fs.mkdir("logical/dir", { recursive: true });
+
+    expect(deps.store.get("physical/dir")).toEqual({ type: "directory" });
+    expect(deps.store.has("logical/dir")).toBe(false);
+    expect(deps.transport.mkdir).toHaveBeenCalledWith("physical/dir", true);
+    expect(isRecentLocalOp("physical/dir")).toBe(true);
+    expect(isRecentLocalOp("logical/dir")).toBe(false);
+  });
+
+  it("rmdir uses the resolved path for cache, echo-guard, and transport", async () => {
+    registerPathResolver(
+      (p) => p === "logical/dir",
+      () => "physical/dir",
+    );
+
+    const deps = makeDeps();
+    const fs = createFsPromises(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    deps.store.set("physical/dir", { type: "directory" });
+
+    await fs.rmdir("logical/dir");
+
+    expect(deps.store.has("physical/dir")).toBe(false);
+    expect(deps.transport.rmdir).toHaveBeenCalledWith("physical/dir");
+    expect(isRecentLocalOp("physical/dir")).toBe(true);
+  });
+});
+
+describe("promises readFile existence", () => {
+  afterEach(() => _reset());
+
+  it("answers ENOENT from the cache for a missing non-redirected path, no transport", async () => {
+    const deps = makeDeps();
+    const fs = createFsPromises(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    await expect(
+      fs.readFile("/.obsidian/backlink.json", "utf8"),
+    ).rejects.toThrow(/ENOENT/);
+    expect(deps.transport.readFile).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the original path for a redirected miss", async () => {
+    registerPathResolver(
+      (p) => p === ".obsidian/workspace.json",
+      () => ".obsidian/workspace.Work.json",
+    );
+
+    const deps = makeDeps();
+    deps.transport.readFile = vi.fn(async (p) => {
+      if (p === ".obsidian/workspace.Work.json") {
+        const e = new Error("ENOENT");
+        e.code = "ENOENT";
+        throw e;
+      }
+
+      return "BASE";
+    });
+
+    const fs = createFsPromises(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    // Returns the base content after the redirect target 404s: the fallback fired.
+    await expect(fs.readFile("/.obsidian/workspace.json", "utf8")).resolves.toBe(
+      "BASE",
+    );
+    expect(deps.transport.readFile).toHaveBeenCalledWith(
+      ".obsidian/workspace.Work.json",
+      "utf8",
+    );
+  });
+});

packages/shim/src/fs/promises.js

@@ -1,7 +1,13 @@
 import { markLocalOp } from "./echo-guard.js";
 import { isInputCachePath, inputCacheGet } from "./input-cache.js";
-import { applyReadTransform, applyWriteTransform, resolvePath } from "./transforms.js";
+import {
+  applyReadTransform,
+  applyWriteTransform,
+  resolvePath,
+  resolvePathInfo,
+} from "./transforms.js";
 import { hasVirtualFile, getVirtualFile } from "./virtual-files.js";
+import { realpathSync } from "./realpath.js";
 
 export function createFsPromises(metadataCache, contentCache, transport) {
   return {
@@ -48,7 +54,7 @@ export function createFsPromises(metadataCache, contentCache, transport) {
       }
 
       const wantText = encoding === "utf8" || encoding === "utf-8";
-      const resolved = resolvePath(path);
+      const { resolved, redirected } = resolvePathInfo(path);
 
       // Virtual plugin source overrides any cache/transport version.
       if (hasVirtualFile(resolved)) {
@@ -81,8 +87,9 @@ export function createFsPromises(metadataCache, contentCache, transport) {
           throw e;
         }
 
-        if (!meta && resolved && resolved === path) {
-          // Throw ENOENT only when not redirected; redirected paths fall through to the transport's fallback.
+        if (!meta && !redirected) {
+          // The metadata cache holds every existing path (populated at bootstrap, kept current by the watcher).
+          // A cache miss on a non-redirected path is genuinely absent. Redirected paths fall through to the transport.
           const e = new Error(
             `ENOENT: no such file or directory, open '${path}'`,
           );
@@ -97,7 +104,7 @@ export function createFsPromises(metadataCache, contentCache, transport) {
         try {
           result = await transport.readFile(resolved, encoding);
         } catch (e) {
-          if (resolved !== path && e.code === "ENOENT") {
+          if (redirected && e.code === "ENOENT") {
             result = await transport.readFile(path, encoding);
           } else {
             throw e;
@@ -202,16 +209,20 @@ export function createFsPromises(metadataCache, contentCache, transport) {
       const recursive =
         typeof options === "object" ? !!options.recursive : !!options;
 
-      markLocalOp(path);
-      metadataCache.set(path, { type: "directory" });
+      const resolved = resolvePath(path);
 
-      await transport.mkdir(path, recursive);
+      markLocalOp(resolved);
+      metadataCache.set(resolved, { type: "directory" });
+
+      await transport.mkdir(resolved, recursive);
     },
 
     async rmdir(path) {
-      markLocalOp(path);
-      metadataCache.delete(path);
-      await transport.rmdir(path);
+      const resolved = resolvePath(path);
+
+      markLocalOp(resolved);
+      metadataCache.delete(resolved);
+      await transport.rmdir(resolved);
     },
 
     async rm(path, options) {
@@ -256,7 +267,8 @@ export function createFsPromises(metadataCache, contentCache, transport) {
         return "/";
       }
 
-      return transport.realpath(path);
+      // No symlinks in the vault FS, so realpath is the identity.
+      return realpathSync(path);
     },
 
     async utimes(path, atime, mtime) {
@@ -270,6 +282,10 @@ export function createFsPromises(metadataCache, contentCache, transport) {
       }
     },
 
+    async chmod() {
+      // No permission bits in the vault FS. No-op.
+    },
+
     async open(path, flags) {
       const hasInCache = isInputCachePath(path) && inputCacheGet(path) !== null;
       const resolved = resolvePath(path);

packages/shim/src/fs/realpath.js

@@ -0,0 +1,12 @@
+export function realpathSync(path) {
+  return typeof path === "string" ? path : String(path);
+}
+
+export function realpath(path, options, callback) {
+  const cb = typeof options === "function" ? options : callback;
+
+  queueMicrotask(() => cb(null, realpathSync(path)));
+}
+
+realpath.native = realpath;
+realpathSync.native = realpathSync;

packages/shim/src/fs/realpath.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { realpath } from "./realpath.js";
+import { createFsPromises } from "./promises.js";
+
+describe("fs realpath shim", () => {
+  it("realpath invokes the callback with the path", async () => {
+    const result = await new Promise((resolve) =>
+      realpath("/a/b.md", (err, p) => resolve(p)),
+    );
+
+    expect(result).toBe("/a/b.md");
+  });
+
+  it("realpath accepts an options argument before the callback", async () => {
+    const result = await new Promise((resolve) =>
+      realpath("/a/b.md", "utf8", (err, p) => resolve(p)),
+    );
+
+    expect(result).toBe("/a/b.md");
+  });
+});
+
+describe("fs.promises realpath", () => {
+  it("answers locally without touching the transport", async () => {
+    const fs = createFsPromises({}, {}, {});
+
+    expect(await fs.realpath("/a/b.md")).toBe("/a/b.md");
+  });
+
+  it("maps empty and root paths to /", async () => {
+    const fs = createFsPromises({}, {}, {});
+
+    expect(await fs.realpath("")).toBe("/");
+    expect(await fs.realpath(".")).toBe("/");
+  });
+});

packages/shim/src/fs/sync-mutations.test.js

@@ -0,0 +1,245 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { createFsSync } from "./sync.js";
+import { resolvePath, registerPathResolver, _reset } from "./transforms.js";
+import { isRecentLocalOp } from "./echo-guard.js";
+
+function makeDeps() {
+  const store = new Map();
+
+  const metadataCache = {
+    has: (p) => store.has(p),
+    get: (p) => (store.has(p) ? store.get(p) : null),
+    set: (p, m) => store.set(p, m),
+    delete: (p) => store.delete(p),
+    rename: (a, b) => {
+      if (store.has(a)) {
+        store.set(b, store.get(a));
+        store.delete(a);
+      }
+    },
+    toStat: (p) =>
+      store.has(p)
+        ? {
+            type: store.get(p).type,
+            isDirectory: () => store.get(p).type === "directory",
+            isFile: () => store.get(p).type === "file",
+          }
+        : null,
+    readdir: () => [],
+  };
+
+  const contentCache = {
+    get: () => null,
+    set: vi.fn(),
+    delete: vi.fn(),
+    invalidate: vi.fn(),
+  };
+
+  const transport = {
+    mkdir: vi.fn(async () => {}),
+    rmdir: vi.fn(async () => {}),
+    rm: vi.fn(async () => {}),
+    rename: vi.fn(async () => {}),
+    copyFile: vi.fn(async () => {}),
+    appendFile: vi.fn(async () => {}),
+    utimes: vi.fn(async () => {}),
+    stat: vi.fn(async () => ({ type: "file", size: 1 })),
+    readFileSync: vi.fn(() => {
+      throw new Error("transport.readFileSync should not be called");
+    }),
+  };
+
+  return { metadataCache, contentCache, transport, store };
+}
+
+describe("sync fs mutations", () => {
+  it("lstatSync mirrors statSync", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    deps.store.set(resolvePath("dir"), { type: "directory" });
+
+    expect(fs.lstatSync("dir").isDirectory()).toBe(true);
+  });
+
+  it("mkdirSync updates the cache and fires the transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    fs.mkdirSync("newdir", { recursive: true });
+
+    expect(deps.store.get("newdir")).toEqual({ type: "directory" });
+    expect(deps.transport.mkdir).toHaveBeenCalledWith("newdir", true);
+  });
+
+  it("rmSync deletes from the cache and fires the transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    const key = resolvePath("gone.md");
+    deps.store.set(key, { type: "file" });
+
+    fs.rmSync("gone.md", { recursive: true });
+
+    expect(deps.store.has(key)).toBe(false);
+    expect(deps.transport.rm).toHaveBeenCalled();
+  });
+
+  it("renameSync moves cache metadata and fires the transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    const from = resolvePath("a.md");
+    const to = resolvePath("b.md");
+    deps.store.set(from, { type: "file", size: 2 });
+
+    fs.renameSync("a.md", "b.md");
+
+    expect(deps.store.has(from)).toBe(false);
+    expect(deps.store.get(to)).toEqual({ type: "file", size: 2 });
+    expect(deps.transport.rename).toHaveBeenCalled();
+  });
+
+  it("copyFileSync optimistically mirrors source metadata and fires the transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    const srcKey = resolvePath("src.md");
+    const destKey = resolvePath("dest.md");
+    deps.store.set(srcKey, { type: "file", size: 9 });
+
+    fs.copyFileSync("src.md", "dest.md");
+
+    expect(deps.store.get(destKey)).toEqual({ type: "file", size: 9 });
+    expect(deps.transport.copyFile).toHaveBeenCalled();
+  });
+
+  it("utimesSync sets mtime and fires the transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    const key = resolvePath("note.md");
+    deps.store.set(key, { type: "file", mtime: 0 });
+
+    fs.utimesSync("note.md", 111, 222);
+
+    expect(deps.store.get(key).mtime).toBe(222);
+    expect(deps.transport.utimes).toHaveBeenCalled();
+  });
+});
+
+describe("directory mutations honor path resolvers", () => {
+  afterEach(() => _reset());
+
+  it("mkdirSync uses the resolved path for cache, echo-guard, and transport", () => {
+    registerPathResolver(
+      (p) => p === "logical/dir",
+      () => "physical/dir",
+    );
+
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    fs.mkdirSync("logical/dir", { recursive: true });
+
+    expect(deps.store.get("physical/dir")).toEqual({ type: "directory" });
+    expect(deps.store.has("logical/dir")).toBe(false);
+    expect(deps.transport.mkdir).toHaveBeenCalledWith("physical/dir", true);
+    expect(isRecentLocalOp("physical/dir")).toBe(true);
+    expect(isRecentLocalOp("logical/dir")).toBe(false);
+  });
+
+  it("rmdirSync uses the resolved path for cache, echo-guard, and transport", () => {
+    registerPathResolver(
+      (p) => p === "logical/dir",
+      () => "physical/dir",
+    );
+
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+    deps.store.set("physical/dir", { type: "directory" });
+
+    fs.rmdirSync("logical/dir");
+
+    expect(deps.store.has("physical/dir")).toBe(false);
+    expect(deps.transport.rmdir).toHaveBeenCalledWith("physical/dir");
+    expect(isRecentLocalOp("physical/dir")).toBe(true);
+  });
+});
+
+describe("readFileSync existence", () => {
+  afterEach(() => _reset());
+
+  it("answers ENOENT from the cache for a missing non-redirected path, no transport", () => {
+    const deps = makeDeps();
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    // Leading slash: normalize strips it, so resolved !== the raw argument.
+    expect(() => fs.readFileSync("/.obsidian/backlink.json", "utf8")).toThrow(
+      /ENOENT/,
+    );
+    expect(deps.transport.readFileSync).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the original path for a redirected miss", () => {
+    registerPathResolver(
+      (p) => p === ".obsidian/workspace.json",
+      () => ".obsidian/workspace.Work.json",
+    );
+
+    const deps = makeDeps();
+    deps.transport.readFileSync = vi.fn((p) => {
+      if (p === ".obsidian/workspace.Work.json") {
+        const e = new Error("ENOENT");
+        e.code = "ENOENT";
+        throw e;
+      }
+
+      return "BASE";
+    });
+
+    const fs = createFsSync(
+      deps.metadataCache,
+      deps.contentCache,
+      deps.transport,
+    );
+
+    // Returns the base content after the redirect target 404s: the fallback fired.
+    expect(fs.readFileSync("/.obsidian/workspace.json", "utf8")).toBe("BASE");
+    expect(deps.transport.readFileSync).toHaveBeenCalledWith(
+      ".obsidian/workspace.Work.json",
+      "utf8",
+    );
+  });
+});

packages/shim/src/fs/sync.js

@@ -4,7 +4,9 @@ import {
   applyReadTransform,
   applyWriteTransform,
   resolvePath,
+  resolvePathInfo,
 } from "./transforms.js";
+import { hasVirtualFile, getVirtualFile } from "./virtual-files.js";
 
 export function createFsSync(metadataCache, contentCache, transport) {
   return {
@@ -68,7 +70,22 @@ export function createFsSync(metadataCache, contentCache, transport) {
       }
 
       const wantText = encoding === "utf8" || encoding === "utf-8";
-      const resolved = resolvePath(path);
+      const { resolved, redirected } = resolvePathInfo(path);
+
+      // Virtual plugin source overrides any cache or transport version.
+      if (hasVirtualFile(resolved)) {
+        const content = getVirtualFile(resolved);
+
+        if (wantText) {
+          return typeof content === "string"
+            ? content
+            : new TextDecoder().decode(content);
+        }
+
+        return typeof content === "string"
+          ? new TextEncoder().encode(content)
+          : content;
+      }
 
       const meta = metadataCache.get(resolved);
       if (meta && meta.type === "directory") {
@@ -92,13 +109,22 @@ export function createFsSync(metadataCache, contentCache, transport) {
         result = contentCache.get(resolved);
       }
 
+      // The metadata cache is kept fresh by the filewatcher and a miss here genuinely means the file is absent.
+      // Redirected paths fall through to the transport, so we can't trust the cache for them, but non-redirected misses are definitive.
+      if (result === null && !meta && !redirected) {
+        const e = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        e.code = "ENOENT";
+        throw e;
+      }
+
       if (result === null) {
-        // ENOENT fallback: if the resolved path doesn't exist, try the original.
-        // Covers per-name workspace files that haven't been saved yet.
+        // A resolver can map a path onto a physical target that does not exist yet, so a redirected miss retries the original path before failing.
         try {
           result = transport.readFileSync(resolved, encoding);
         } catch (e) {
-          if (resolved !== path && e.code === "ENOENT") {
+          if (redirected && e.code === "ENOENT") {
             console.warn(
               "[shim:fs] readFileSync cache miss, using sync XHR:",
               path,
@@ -180,5 +206,159 @@ export function createFsSync(metadataCache, contentCache, transport) {
       const entries = metadataCache.readdir(path);
       return entries.map((e) => e.name);
     },
+
+    lstatSync(path) {
+      // No symlinks in our context.
+      return this.statSync(path);
+    },
+
+    mkdirSync(path, options) {
+      const recursive =
+        typeof options === "object" ? !!options.recursive : !!options;
+
+      const resolved = resolvePath(path);
+
+      markLocalOp(resolved);
+      metadataCache.set(resolved, { type: "directory" });
+
+      transport.mkdir(resolved, recursive).catch((e) => {
+        console.error(
+          "[shim:fs] mkdirSync background create failed:",
+          resolved,
+          e,
+        );
+      });
+    },
+
+    rmdirSync(path) {
+      const resolved = resolvePath(path);
+
+      markLocalOp(resolved);
+      metadataCache.delete(resolved);
+
+      transport.rmdir(resolved).catch((e) => {
+        console.error(
+          "[shim:fs] rmdirSync background remove failed:",
+          resolved,
+          e,
+        );
+      });
+    },
+
+    rmSync(path, options) {
+      const recursive =
+        typeof options === "object" ? !!options.recursive : false;
+
+      const resolved = resolvePath(path);
+
+      markLocalOp(resolved);
+      metadataCache.delete(resolved);
+      contentCache.delete(resolved);
+
+      transport.rm(resolved, recursive).catch((e) => {
+        console.error(
+          "[shim:fs] rmSync background remove failed:",
+          resolved,
+          e,
+        );
+      });
+    },
+
+    renameSync(oldPath, newPath) {
+      const resolvedOld = resolvePath(oldPath);
+      const resolvedNew = resolvePath(newPath);
+
+      markLocalOp(resolvedOld);
+      markLocalOp(resolvedNew);
+      const content = contentCache.get(resolvedOld);
+
+      if (content !== null) {
+        contentCache.set(resolvedNew, content);
+        contentCache.delete(resolvedOld);
+      }
+
+      metadataCache.rename(resolvedOld, resolvedNew);
+
+      transport.rename(resolvedOld, resolvedNew).catch((e) => {
+        console.error(
+          "[shim:fs] renameSync background rename failed:",
+          resolvedOld,
+          e,
+        );
+      });
+    },
+
+    copyFileSync(src, dest) {
+      const resolvedSrc = resolvePath(src);
+      const resolvedDest = resolvePath(dest);
+
+      markLocalOp(resolvedDest);
+
+      // Optimistically mirror the source so a sync read right after sees it.
+      const content = contentCache.get(resolvedSrc);
+
+      if (content !== null) {
+        contentCache.set(resolvedDest, content);
+      }
+
+      const srcMeta = metadataCache.get(resolvedSrc);
+
+      if (srcMeta) {
+        metadataCache.set(resolvedDest, { ...srcMeta });
+      }
+
+      transport
+        .copyFile(src, resolvedDest)
+        .then(() => transport.stat(resolvedDest))
+        .then((meta) => metadataCache.set(resolvedDest, meta))
+        .catch((e) => {
+          console.error(
+            "[shim:fs] copyFileSync background copy failed:",
+            resolvedDest,
+            e,
+          );
+        });
+    },
+
+    appendFileSync(path, data) {
+      const resolved = resolvePath(path);
+
+      markLocalOp(resolved);
+      contentCache.invalidate(resolved);
+
+      transport
+        .appendFile(resolved, data)
+        .then(() => transport.stat(resolved))
+        .then((meta) => metadataCache.set(resolved, meta))
+        .catch((e) => {
+          console.error(
+            "[shim:fs] appendFileSync background append failed:",
+            resolved,
+            e,
+          );
+        });
+    },
+
+    utimesSync(path, atime, mtime) {
+      const resolved = resolvePath(path);
+      const meta = metadataCache.get(resolved);
+
+      if (meta) {
+        meta.mtime = typeof mtime === "number" ? mtime : mtime.getTime();
+        metadataCache.set(resolved, meta);
+      }
+
+      transport.utimes(resolved, atime, mtime).catch((e) => {
+        console.error(
+          "[shim:fs] utimesSync background utimes failed:",
+          resolved,
+          e,
+        );
+      });
+    },
+
+    chmodSync() {
+      // The vault FS does not model permission bits. No-op.
+    },
   };
 }

packages/shim/src/fs/transforms.js

@@ -12,7 +12,9 @@ export function registerPathResolver(matcher, resolver) {
   pathResolvers.push({ matcher, resolver });
 }
 
-export function resolvePath(path) {
+// resolved is the physical path.
+// redirected is true when a path resolver sent the request to a different path.
+export function resolvePathInfo(path) {
   const norm = normalize(path);
 
   for (const { matcher, resolver } of pathResolvers) {
@@ -21,13 +23,17 @@ export function resolvePath(path) {
         const resolved = resolver(norm);
 
         if (typeof resolved === "string" && resolved.length > 0) {
-          return resolved;
+          return { resolved, redirected: true };
         }
       }
     } catch {}
   }
 
-  return norm;
+  return { resolved: norm, redirected: false };
+}
+
+export function resolvePath(path) {
+  return resolvePathInfo(path).resolved;
 }
 
 // --- Read transforms ---

packages/shim/src/fs/transport.js

@@ -19,6 +19,18 @@ function vaultId() {
   return window.__currentVaultId || "";
 }
 
+const KEEPALIVE_MAX_BYTES = 64 * 1024;
+
+// keepalive lets a request finish after the page starts unloading.
+// Its body is capped at 64KB across a shared pool, so opt in only under that limit.
+function withinKeepaliveCap(body) {
+  if (!body) {
+    return true;
+  }
+
+  return new TextEncoder().encode(body).length <= KEEPALIVE_MAX_BYTES;
+}
+
 async function request(method, endpoint, params = {}) {
   const url = new URL(API_BASE + endpoint, window.location.origin);
 
@@ -37,6 +49,11 @@ async function request(method, endpoint, params = {}) {
     options.body = JSON.stringify({ vault: vaultId(), ...params });
   }
 
+  // A write (POST/DELETE) opts into keepalive so a page dismissal does not drop it.
+  if (method !== "GET" && withinKeepaliveCap(options.body)) {
+    options.keepalive = true;
+  }
+
   const res = await fetch(url.toString(), options);
   if (!res.ok) {
     const err = await res
@@ -177,13 +194,6 @@ export const transport = {
     return requestJson("GET", "/access", { path: normPath(path) });
   },
 
-  async realpath(path) {
-    const result = await requestJson("GET", "/realpath", {
-      path: normPath(path),
-    });
-    return result.path;
-  },
-
   async utimes(path, atime, mtime) {
     return requestJson("POST", "/utimes", {
       path: normPath(path),

packages/shim/src/fs/transport.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { transport } from "./transport.js";
+
+let fetchMock;
+
+beforeEach(() => {
+  fetchMock = vi.fn(async () => ({
+    ok: true,
+    json: async () => ({}),
+    text: async () => "",
+    arrayBuffer: async () => new ArrayBuffer(0),
+  }));
+  globalThis.fetch = fetchMock;
+  globalThis.window = {
+    location: { origin: "http://localhost" },
+    __currentVaultId: "v",
+  };
+});
+
+afterEach(() => {
+  delete globalThis.fetch;
+  delete globalThis.window;
+});
+
+function lastInit() {
+  return fetchMock.mock.calls.at(-1)[1];
+}
+
+describe("transport keepalive gating", () => {
+  it("sets keepalive on a small write", async () => {
+    await transport.writeFile("a.md", "hello", "utf-8");
+
+    expect(lastInit().keepalive).toBe(true);
+  });
+
+  it("omits keepalive when the body exceeds the 64KB cap", async () => {
+    await transport.writeFile("a.md", "x".repeat(70 * 1024), "utf-8");
+
+    expect(lastInit().keepalive).toBeFalsy();
+  });
+
+  it("counts base64 inflation against the cap for binary writes", async () => {
+    // 60KB of bytes inflates to ~80KB of base64, over the cap.
+    await transport.writeFile("a.bin", new Uint8Array(60 * 1024));
+
+    expect(lastInit().keepalive).toBeFalsy();
+  });
+
+  it("sets keepalive on a bodyless delete", async () => {
+    await transport.unlink("a.md");
+
+    expect(lastInit().keepalive).toBe(true);
+  });
+
+  it("does not set keepalive on a read", async () => {
+    await transport.readFile("a.md", "utf8");
+
+    expect(lastInit().keepalive).toBeUndefined();
+  });
+});

packages/shim/src/fs/watcher-client.js

@@ -2,8 +2,17 @@
 // The WebSocket itself is owned by ws-client.js; this module is a consumer.
 
 import { isRecentLocalOp } from "./echo-guard.js";
+import { normalize } from "../util/path.js";
 
-export function createWatcherClient(metadataCache, contentCache, fsWatch, wsClient) {
+const RESYNC_DEBOUNCE_MS = 1000;
+
+export function createWatcherClient(
+  metadataCache,
+  contentCache,
+  fsWatch,
+  wsClient,
+  transport,
+) {
   function handleCreated(msg) {
     const { path, stat } = msg;
 
@@ -72,6 +81,74 @@ export function createWatcherClient(metadataCache, contentCache, fsWatch, wsClie
   wsClient.subscribe("modified", handleModified);
   wsClient.subscribe("deleted", handleDeleted);
 
+  // Re-derive the cache from a freshly fetched tree after a reconnect.
+  // Each delta runs through the live-event handlers, matching live behavior.
+  function reconcile(tree) {
+    const fresh = new Set(Object.keys(tree).map(normalize));
+
+    for (const [path, meta] of Object.entries(tree)) {
+      const existing = metadataCache.get(path);
+
+      if (!existing) {
+        if (meta.type === "directory") {
+          handleFolderCreated({ path });
+        } else {
+          handleCreated({
+            path,
+            stat: { size: meta.size, mtime: meta.mtime, ctime: meta.ctime },
+          });
+        }
+      } else if (
+        meta.type === "file" &&
+        (existing.mtime !== meta.mtime || existing.size !== meta.size)
+      ) {
+        handleModified({
+          path,
+          stat: { size: meta.size, mtime: meta.mtime, ctime: meta.ctime },
+        });
+      }
+    }
+
+    // A cache key absent from the fresh tree was deleted while disconnected.
+    // The empty root key is preserved because the tree never lists it.
+    for (const key of metadataCache.keys()) {
+      if (key === "" || fresh.has(key)) {
+        continue;
+      }
+
+      handleDeleted({ path: key });
+    }
+  }
+
+  async function resync() {
+    let tree;
+
+    try {
+      tree = await transport.fetchTree();
+    } catch (e) {
+      console.warn("[shim:fs] reconnect resync failed:", e);
+      return;
+    }
+
+    reconcile(tree);
+  }
+
+  // Coalesce a burst of reconnects into a single resync once the socket settles.
+  let resyncTimer = null;
+
+  function scheduleResync() {
+    if (resyncTimer) {
+      clearTimeout(resyncTimer);
+    }
+
+    resyncTimer = setTimeout(() => {
+      resyncTimer = null;
+      resync();
+    }, RESYNC_DEBOUNCE_MS);
+  }
+
+  wsClient.onReconnect(scheduleResync);
+
   function connect(vaultId) {
     wsClient.connect(vaultId);
   }
@@ -83,5 +160,6 @@ export function createWatcherClient(metadataCache, contentCache, fsWatch, wsClie
   return {
     connect,
     disconnect,
+    reconcile,
   };
 }

packages/shim/src/fs/watcher-client.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from "vitest";
+import { createWatcherClient } from "./watcher-client.js";
+import { markLocalOp } from "./echo-guard.js";
+
+function makeDeps() {
+  const store = new Map();
+
+  const metadataCache = {
+    get: (p) => store.get(p) || null,
+    set: (p, m) => store.set(p, m),
+    delete: (p) => store.delete(p),
+    has: (p) => store.has(p),
+    keys: () => [...store.keys()],
+  };
+
+  const contentCache = {
+    invalidate: vi.fn(),
+    set: vi.fn(),
+    delete: vi.fn(),
+    get: () => null,
+  };
+
+  const fsWatch = { _dispatch: vi.fn() };
+  const wsClient = { subscribe: vi.fn(), onReconnect: vi.fn() };
+  const transport = { fetchTree: vi.fn() };
+
+  const client = createWatcherClient(
+    metadataCache,
+    contentCache,
+    fsWatch,
+    wsClient,
+    transport,
+  );
+
+  return { store, metadataCache, contentCache, fsWatch, wsClient, transport, client };
+}
+
+describe("watcher-client reconcile", () => {
+  it("adds a file present in the tree but missing from the cache", () => {
+    const d = makeDeps();
+
+    d.client.reconcile({ "new.md": { type: "file", size: 5, mtime: 100, ctime: 50 } });
+
+    expect(d.store.get("new.md")).toMatchObject({ type: "file", size: 5 });
+    expect(d.contentCache.invalidate).toHaveBeenCalledWith("new.md");
+    expect(d.fsWatch._dispatch).toHaveBeenCalledWith("created", "new.md");
+  });
+
+  it("adds a directory as a folder", () => {
+    const d = makeDeps();
+
+    d.client.reconcile({ newdir: { type: "directory" } });
+
+    expect(d.store.get("newdir")).toEqual({ type: "directory" });
+    expect(d.fsWatch._dispatch).toHaveBeenCalledWith("folder-created", "newdir");
+  });
+
+  it("modifies a file whose mtime or size changed", () => {
+    const d = makeDeps();
+    d.store.set("a.md", { type: "file", size: 1, mtime: 10 });
+
+    d.client.reconcile({ "a.md": { type: "file", size: 2, mtime: 20, ctime: 5 } });
+
+    expect(d.store.get("a.md")).toMatchObject({ size: 2, mtime: 20 });
+    expect(d.fsWatch._dispatch).toHaveBeenCalledWith("modified", "a.md");
+  });
+
+  it("is a no-op for an unchanged file", () => {
+    const d = makeDeps();
+    d.store.set("a.md", { type: "file", size: 1, mtime: 10 });
+
+    d.client.reconcile({ "a.md": { type: "file", size: 1, mtime: 10, ctime: 5 } });
+
+    expect(d.fsWatch._dispatch).not.toHaveBeenCalled();
+  });
+
+  it("deletes a cache entry absent from the tree and preserves the root", () => {
+    const d = makeDeps();
+    d.store.set("", { type: "directory" });
+    d.store.set("gone.md", { type: "file", size: 1, mtime: 10 });
+    d.store.set("keep.md", { type: "file", size: 1, mtime: 10 });
+
+    d.client.reconcile({ "keep.md": { type: "file", size: 1, mtime: 10, ctime: 5 } });
+
+    expect(d.store.has("gone.md")).toBe(false);
+    expect(d.store.has("")).toBe(true);
+    expect(d.fsWatch._dispatch).toHaveBeenCalledWith("deleted", "gone.md");
+    expect(d.fsWatch._dispatch).not.toHaveBeenCalledWith("deleted", "keep.md");
+  });
+
+  it("skips a path with a recent local op", () => {
+    const d = makeDeps();
+    const p = "recent-local-op-reconcile.md";
+    markLocalOp(p);
+
+    d.client.reconcile({ [p]: { type: "file", size: 5, mtime: 100, ctime: 50 } });
+
+    expect(d.store.has(p)).toBe(false);
+    expect(d.fsWatch._dispatch).not.toHaveBeenCalled();
+  });
+});

packages/shim/src/globals.js

@@ -4,8 +4,8 @@ import {
   unregisterPopupWindow,
 } from "./electron/remote/window.js";
 import { showVaultManager } from "./ui-registry.js";
-import { arrayBufferToBase64, base64ToArrayBuffer } from "./util/base64.js";
 import { isSameOrigin } from "./util/url.js";
+import { proxyFetch } from "./util/proxy.js";
 
 function installProcess() {
   window.process = processShim;
@@ -73,6 +73,15 @@ function installBuffer() {
 function installWindowClose() {
   window.close = function () {
     console.log("[ignis] window.close() blocked");
+
+    // Obsidian's quit flow shows the progress overlay, awaits its pending save work, then calls window.close().
+    // Since we don't actually want to close the window, we clean up the progress state instead.
+    if (document.body.classList.contains("in-progress")) {
+      document.querySelector(".progress-bar-container")?.remove();
+      document.body.classList.remove("in-progress");
+      return;
+    }
+
     if (!window.__vaultConfig) {
       showVaultManager();
     }
@@ -167,17 +176,15 @@ function installFetchShim() {
     }
 
     let body = null;
-    let binary = false;
 
     if (init?.body && method !== "GET" && method !== "HEAD") {
       if (typeof init.body === "string") {
         body = init.body;
-      } else if (init.body instanceof ArrayBuffer) {
-        body = arrayBufferToBase64(init.body);
-        binary = true;
-      } else if (init.body instanceof Uint8Array) {
-        body = arrayBufferToBase64(init.body.buffer);
-        binary = true;
+      } else if (
+        init.body instanceof ArrayBuffer ||
+        init.body instanceof Uint8Array
+      ) {
+        body = init.body;
       } else if (typeof init.body === "object") {
         body = JSON.stringify(init.body);
       } else {
@@ -187,23 +194,15 @@ function installFetchShim() {
 
     console.log("[shim:fetch] Proxying cross-origin:", method, url);
 
-    const proxyRes = await originalFetch("/api/proxy", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ url, method, headers, body, binary }),
-    });
+    let result;
 
-    if (!proxyRes.ok) {
-      const err = await proxyRes
-        .json()
-        .catch(() => ({ error: "Proxy request failed" }));
-      throw new TypeError(err.error || "Failed to fetch");
+    try {
+      result = await proxyFetch({ url, method, headers, body });
+    } catch (e) {
+      throw new TypeError(e.message || "Failed to fetch");
     }
 
-    const result = await proxyRes.json();
-    const respBody = base64ToArrayBuffer(result.body);
-
-    return new Response(respBody, {
+    return new Response(result.body, {
       status: result.status,
       headers: result.headers,
     });
@@ -238,7 +237,12 @@ function installContextMenuFix() {
   );
 }
 
+function installGlobalAlias() {
+  window.global = window;
+}
+
 export function installGlobals() {
+  installGlobalAlias();
   installProcess();
   installBuffer();
   installFetchShim();

packages/shim/src/init.js

@@ -8,11 +8,26 @@ import {
   initWorkspacePatch,
 } from "./workspace.js";
 import { prefetchVaultContent } from "./fs/indexer-prefetch.js";
+import { setInputCacheLimits } from "./fs/input-cache.js";
 import { autoTrustDemoVaults, maybeProvisionDemoVault } from "./demo.js";
 import { initNativeMenuGuard } from "./native-menu-guard.js";
 
 let bootstrapVirtualPlugins = [];
 
+// Cache sizes come from the bootstrap response and are applied at page load.
+// The server owns the rest of the settings and applies them on its side.
+function applyServerSettings(s) {
+  if (!s) {
+    return;
+  }
+
+  if (Number.isFinite(s.contentCacheBytes)) {
+    fsShim._contentCache.setMaxSize(s.contentCacheBytes);
+  }
+
+  setInputCacheLimits({ maxSize: s.inputCacheBytes, ttlMs: s.inputCacheTtlMs });
+}
+
 export function getBootstrapVirtualPlugins() {
   return bootstrapVirtualPlugins;
 }
@@ -156,8 +171,7 @@ function applyCoreSyncGuard(plugins) {
       return data;
     }
 
-    let text =
-      typeof data === "string" ? data : new TextDecoder().decode(data);
+    let text = typeof data === "string" ? data : new TextDecoder().decode(data);
 
     try {
       const config = JSON.parse(text);
@@ -193,15 +207,38 @@ function initCoreSyncGuardFallback() {
   }
 }
 
+// Reflect the priority prefetch's byte progress on the boot splash so the awaited slice reads as active rather than hung.
+// The splash logo keeps pulsing through a transit stall, when the byte count would otherwise freeze.
+function updateBootProgress(received, total) {
+  // Once the injector starts appending Obsidian's scripts it owns the splash label, so stop writing progress over it.
+  if (window.__ignisBootStarted) {
+    return;
+  }
+
+  const label = document.getElementById("ignis-status-label");
+
+  if (!label || !total) {
+    return;
+  }
+
+  const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+  label.textContent = `Loading plugins... ${mb(received)}/${mb(total)} MB`;
+}
+
+// Resolve the active workspace and snapshot the appearance config.
+function resolveWorkspaceAndAppearance() {
+  resolveWorkspaceName();
+  loadPresetIfRequested();
+  initNativeMenuGuard();
+}
+
 export function initialize() {
   if (maybeProvisionDemoVault()) {
+    window.__ignisBootReady = Promise.resolve();
     return;
   }
 
   resolveVaultId();
-  resolveWorkspaceName();
-  loadPresetIfRequested();
-  initNativeMenuGuard(window.__currentVaultId);
 
   const bootstrap = fetchBootstrap();
 
@@ -212,19 +249,28 @@ export function initialize() {
     applyTree(bootstrap.tree);
     applyCoreSyncGuard(bootstrap.plugins);
     bootstrapVirtualPlugins = bootstrap.virtualPlugins || [];
+    applyServerSettings(bootstrap.settings);
 
-    // Race the indexer: batch-fetch text content into ContentCache so
-    // Obsidian's startup indexing reads hit the cache instead of the network.
-    prefetchVaultContent(
+    // Warm the caches before Obsidian boots.
+    // The priority slice (configs and plugin entry files) resolves window.__ignisBootReady, which the index.html injector waits on before appending Obsidian's scripts, so Obsidian's early reads hit the cache.
+    // The bulk slice streams afterward without blocking boot.
+    const { priority } = prefetchVaultContent(
       window.__currentVaultId,
       bootstrap.tree,
       fsShim._contentCache,
+      { onProgress: updateBootProgress },
     );
+
+    // Chain workspace/appearance resolution onto readiness so its config reads hit the warm priority slice instead of the network.
+    window.__ignisBootReady = priority.then(resolveWorkspaceAndAppearance);
   } else {
     initVaultConfigFallback();
     initVaultListFallback();
     initMetadataCacheFallback();
     initCoreSyncGuardFallback();
+    // No prefetch on the fallback path, so resolve directly; the reads fall through to the network.
+    resolveWorkspaceAndAppearance();
+    window.__ignisBootReady = Promise.resolve();
   }
 
   installRequestUrlShim();

packages/shim/src/loader.js

@@ -52,7 +52,7 @@ if (window.__currentVaultId) {
 
 extractObsidianModule()
   .then(async () => {
-    // Dynamic import so bridge's top-level require("obsidian") fires after installRequire + extractObsidianModule.
+    // Dynamic import so the bridge's top-level obsidian import resolves after installRequire + extractObsidianModule.
     const mod = await import("@ignis/bridge");
     const IgnisBridgePlugin = mod.default || mod;
     const bridge = new IgnisBridgePlugin(window.app, BRIDGE_MANIFEST);

packages/shim/src/native-menu-guard.js

@@ -6,34 +6,16 @@ import {
   registerReadTransform,
   registerWriteTransform,
 } from "./fs/transforms.js";
+import { fsShim } from "./fs/index.js";
 
 const APPEARANCE_PATH = ".obsidian/appearance.json";
 
 // undefined = key absent on disk; write transform keeps it absent.
 let preservedNativeMenus = undefined;
 
-function snapshotAppearance(vaultId) {
-  if (!vaultId) {
-    return;
-  }
-
+function snapshotAppearance() {
   try {
-    const xhr = new XMLHttpRequest();
-    const url =
-      "/api/fs/readFile?vault=" +
-      encodeURIComponent(vaultId) +
-      "&path=" +
-      encodeURIComponent(APPEARANCE_PATH) +
-      "&encoding=utf-8";
-
-    xhr.open("GET", url, false);
-    xhr.send();
-
-    if (xhr.status !== 200) {
-      return;
-    }
-
-    const obj = JSON.parse(xhr.responseText);
+    const obj = JSON.parse(fsShim.readFileSync(APPEARANCE_PATH, "utf-8"));
 
     if ("nativeMenus" in obj) {
       preservedNativeMenus = obj.nativeMenus;
@@ -49,7 +31,8 @@ function readTransform(data) {
   try {
     const obj = JSON.parse(text);
 
-    if (obj.nativeMenus) {
+    // force native menus to false since its never appropriate in a browser context.
+    if (obj.nativeMenus !== false) {
       obj.nativeMenus = false;
       return JSON.stringify(obj);
     }
@@ -100,6 +83,9 @@ function patchSetConfig() {
     };
     vault.__ignisNativeMenuGuarded = true;
 
+    // set to false to override any platform default (like macOS).
+    vault.setConfig("nativeMenus", false);
+
     return true;
   };
 
@@ -154,9 +140,9 @@ function disableNativeMenuToggle() {
   });
 }
 
-export function initNativeMenuGuard(vaultId) {
-  // Snapshot before registering transforms so the write transform has the original disk value to substitute back.
-  snapshotAppearance(vaultId);
+export function initNativeMenuGuard() {
+  // Snapshot before registering the read transform so the captured value is the original on disk, not the forced value.
+  snapshotAppearance();
   registerReadTransform(APPEARANCE_PATH, readTransform);
   registerWriteTransform(APPEARANCE_PATH, writeTransform);
   patchSetConfig();

packages/shim/src/node/assert.js

@@ -0,0 +1,82 @@
+class AssertionError extends Error {
+  constructor(message) {
+    super(message || "Assertion failed");
+    this.name = "AssertionError";
+  }
+}
+
+function assert(value, message) {
+  if (!value) {
+    throw new AssertionError(message);
+  }
+}
+
+assert.AssertionError = AssertionError;
+assert.ok = assert;
+assert.strict = assert;
+
+assert.fail = function (message) {
+  throw new AssertionError(message || "Failed");
+};
+
+assert.equal = function (actual, expected, message) {
+  if (actual != expected) {
+    throw new AssertionError(message || `${actual} == ${expected}`);
+  }
+};
+
+assert.notEqual = function (actual, expected, message) {
+  if (actual == expected) {
+    throw new AssertionError(message || `${actual} != ${expected}`);
+  }
+};
+
+assert.strictEqual = function (actual, expected, message) {
+  if (actual !== expected) {
+    throw new AssertionError(message || `${actual} === ${expected}`);
+  }
+};
+
+assert.notStrictEqual = function (actual, expected, message) {
+  if (actual === expected) {
+    throw new AssertionError(message || `${actual} !== ${expected}`);
+  }
+};
+
+assert.deepEqual = function (actual, expected, message) {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new AssertionError(message || "deepEqual");
+  }
+};
+
+assert.deepStrictEqual = assert.deepEqual;
+
+assert.throws = function (fn, message) {
+  let threw = false;
+
+  try {
+    fn();
+  } catch {
+    threw = true;
+  }
+
+  if (!threw) {
+    throw new AssertionError(message || "Missing expected exception");
+  }
+};
+
+assert.doesNotThrow = function (fn, message) {
+  try {
+    fn();
+  } catch (e) {
+    throw new AssertionError(message || `Got unwanted exception: ${e.message}`);
+  }
+};
+
+assert.ifError = function (value) {
+  if (value) {
+    throw new AssertionError(`ifError got unwanted exception: ${value}`);
+  }
+};
+
+export const assertShim = assert;

packages/shim/src/node/assert.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { assertShim as assert } from "./assert.js";
+
+describe("assert shim", () => {
+  it("is callable and throws on a falsy value", () => {
+    expect(() => assert(false)).toThrow();
+    expect(() => assert(true)).not.toThrow();
+  });
+
+  it("equal throws on mismatch and passes on loose match", () => {
+    expect(() => assert.equal(1, 2)).toThrow();
+    expect(() => assert.equal(1, 1)).not.toThrow();
+    expect(() => assert.equal(1, "1")).not.toThrow();
+  });
+
+  it("strictEqual distinguishes type", () => {
+    expect(() => assert.strictEqual(1, "1")).toThrow();
+    expect(() => assert.strictEqual(1, 1)).not.toThrow();
+  });
+
+  it("throws() verifies that a function threw", () => {
+    expect(() =>
+      assert.throws(() => {
+        throw new Error("x");
+      }),
+    ).not.toThrow();
+
+    expect(() => assert.throws(() => {})).toThrow();
+  });
+});

packages/shim/src/node/constants.js

@@ -0,0 +1,50 @@
+// Linux constant values, to match the platform the process shim reports.
+// O_SYMLINK and other macOS/BSD flags are omitted so feature checks treat platform as linux
+
+export const constantsShim = {
+  // File access checks (fs.access mode).
+  F_OK: 0,
+  X_OK: 1,
+  W_OK: 2,
+  R_OK: 4,
+
+  // open() flags.
+  O_RDONLY: 0,
+  O_WRONLY: 1,
+  O_RDWR: 2,
+  O_CREAT: 64,
+  O_EXCL: 128,
+  O_NOCTTY: 256,
+  O_TRUNC: 512,
+  O_APPEND: 1024,
+  O_DIRECTORY: 65536,
+  O_NOATIME: 262144,
+  O_NOFOLLOW: 131072,
+  O_SYNC: 1052672,
+  O_DSYNC: 4096,
+  O_NONBLOCK: 2048,
+
+  // File type bits (st_mode & S_IFMT).
+  S_IFMT: 61440,
+  S_IFREG: 32768,
+  S_IFDIR: 16384,
+  S_IFCHR: 8192,
+  S_IFBLK: 24576,
+  S_IFIFO: 4096,
+  S_IFLNK: 40960,
+  S_IFSOCK: 49152,
+
+  // Permission bits.
+  S_IRWXU: 448,
+  S_IRUSR: 256,
+  S_IWUSR: 128,
+  S_IXUSR: 64,
+  S_IRWXG: 56,
+  S_IRGRP: 32,
+  S_IWGRP: 16,
+  S_IXGRP: 8,
+  S_IRWXO: 7,
+  S_IROTH: 4,
+  S_IWOTH: 2,
+  S_IXOTH: 1,
+};

packages/shim/src/node/stream.js

@@ -0,0 +1,85 @@
+import { EventEmitter } from "./events.js";
+
+let warned = false;
+
+function warnNoDataFlow(method) {
+  if (warned) {
+    return;
+  }
+
+  warned = true;
+  console.warn(
+    `[shim:stream] ${method}() called, but stream data flow is not implemented. ` +
+      "This plugin needs the full stream shim.",
+  );
+}
+
+export class Stream extends EventEmitter {
+  pipe(destination) {
+    warnNoDataFlow("pipe");
+    return destination;
+  }
+}
+
+export class Readable extends Stream {
+  constructor(options) {
+    super();
+    this.readable = true;
+    this._readableState = { options: options || {} };
+  }
+
+  read() {
+    warnNoDataFlow("read");
+    return null;
+  }
+
+  push() {
+    warnNoDataFlow("push");
+    return false;
+  }
+
+  _read() {}
+}
+
+export class Writable extends Stream {
+  constructor(options) {
+    super();
+    this.writable = true;
+    this._writableState = { options: options || {} };
+  }
+
+  write() {
+    warnNoDataFlow("write");
+    return false;
+  }
+
+  end() {
+    warnNoDataFlow("end");
+    return this;
+  }
+
+  _write() {}
+}
+
+export class Duplex extends Readable {
+  constructor(options) {
+    super(options);
+    this.writable = true;
+  }
+
+  write() {
+    warnNoDataFlow("write");
+    return false;
+  }
+
+  end() {
+    warnNoDataFlow("end");
+    return this;
+  }
+}
+
+export class Transform extends Duplex {
+  _transform() {}
+}
+
+export class PassThrough extends Transform {}

packages/shim/src/node/stream.test.js

@@ -0,0 +1,16 @@
+import { describe, it, expect, vi } from "vitest";
+import { Readable, Writable } from "./stream.js";
+
+describe("stream shim", () => {
+  it("warns once when data-flow methods are used", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    new Readable().read();
+    new Writable().write("x");
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain("[shim:stream]");
+
+    warn.mockRestore();
+  });
+});

packages/shim/src/process.js

@@ -1,5 +1,6 @@
 export const processShim = {
   platform: "linux",
+  version: "v18.18.0",
   versions: {
     electron: "28.2.3",
     node: "18.18.0",

packages/shim/src/request-url.js

@@ -2,7 +2,7 @@
 // Obsidian sets window.requestUrl in app.js, so we override it after app.js loads.
 
 import { isSameOrigin } from "./util/url.js";
-import { arrayBufferToBase64, base64ToArrayBuffer } from "./util/base64.js";
+import { proxyFetch } from "./util/proxy.js";
 
 async function proxyRequestUrl(request) {
   if (typeof request === "string") {
@@ -28,42 +28,14 @@ async function proxyRequestUrl(request) {
   }
 
   // Cross-origin: route through server proxy
-  let body = request.body;
-  let binary = false;
-
-  if (body instanceof ArrayBuffer) {
-    body = arrayBufferToBase64(body);
-    binary = true;
-  }
-
-  const res = await fetch("/api/proxy", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      url: request.url,
-      method: request.method || "GET",
-      headers: request.headers || {},
-      body,
-      binary,
-    }),
+  const result = await proxyFetch({
+    url: request.url,
+    method: request.method,
+    headers: request.headers,
+    body: request.body,
   });
 
-  if (!res.ok) {
-    const err = await res
-      .json()
-      .catch(() => ({ error: "Proxy request failed" }));
-    throw new Error(err.error);
-  }
-
-  const proxyResult = await res.json();
-  const arrayBuf = base64ToArrayBuffer(proxyResult.body);
-
-  return makeResponse(
-    request,
-    proxyResult.status,
-    proxyResult.headers,
-    arrayBuf,
-  );
+  return makeResponse(request, result.status, result.headers, result.body);
 }
 
 function makeResponse(request, status, headers, arrayBuf) {

packages/shim/src/require.js

@@ -11,6 +11,9 @@ import * as netShim from "./node/net.js";
 import * as httpShim from "./node/http.js";
 import * as zlibShim from "./node/zlib.js";
 import * as utilShim from "./node/util.js";
+import { constantsShim } from "./node/constants.js";
+import { assertShim } from "./node/assert.js";
+import * as streamShim from "./node/stream.js";
 import { wrapWithProxy, installDebugHelpers } from "./debug.js";
 
 const rawRegistry = {
@@ -29,6 +32,9 @@ const rawRegistry = {
   https: httpShim,
   zlib: zlibShim,
   util: utilShim,
+  constants: constantsShim,
+  assert: assertShim,
+  stream: streamShim,
 };
 
 const shimRegistry = {};

packages/shim/src/util/proxy.js

@@ -0,0 +1,54 @@
+// Single round-trip through the server's /api/proxy endpoint for cross-origin requests.
+// Encodes a binary request body to base64, returns the upstream response with its body as an ArrayBuffer.
+// Throws an Error carrying the server's message on failure.
+
+import { arrayBufferToBase64, base64ToArrayBuffer } from "./base64.js";
+
+export async function proxyFetch({ url, method, headers, body, contentType }) {
+  let encodedBody = null;
+  let binary = false;
+
+  if (body instanceof ArrayBuffer) {
+    encodedBody = arrayBufferToBase64(body);
+    binary = true;
+  } else if (body instanceof Uint8Array) {
+    encodedBody = arrayBufferToBase64(body.buffer);
+    binary = true;
+  } else if (body != null) {
+    encodedBody = body;
+  }
+
+  const payload = {
+    url,
+    method: method || "GET",
+    headers: headers || {},
+    body: encodedBody,
+    binary,
+  };
+
+  if (contentType !== undefined) {
+    payload.contentType = contentType;
+  }
+
+  // Use native fetch to avoid an unnecessary call through the shim. proxy is already same origin.
+  const nativeFetch = window.__originalFetch || fetch;
+
+  const res = await nativeFetch("/api/proxy", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.error || "Proxy request failed");
+  }
+
+  const result = await res.json();
+
+  return {
+    status: result.status,
+    headers: result.headers,
+    body: base64ToArrayBuffer(result.body),
+  };
+}

packages/shim/src/util/url.js

@@ -2,7 +2,7 @@
 function isSameOrigin(url) {
   if (
     !url ||
-    url.startsWith("/") ||
+    (url.startsWith("/") && !url.startsWith("//")) ||
     url.startsWith("./") ||
     url.startsWith("../")
   ) {

packages/shim/src/util/url.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { isSameOrigin } from "./url.js";
+
+describe("isSameOrigin", () => {
+  beforeEach(() => {
+    global.window = { location: { origin: "https://vault.example.com" } };
+  });
+
+  afterEach(() => {
+    delete global.window;
+  });
+
+  it("treats a root-relative path as same-origin", () => {
+    expect(isSameOrigin("/api/fs/readFile")).toBe(true);
+  });
+
+  it("treats a protocol-relative URL as cross-origin", () => {
+    expect(isSameOrigin("//evil.com/x")).toBe(false);
+  });
+
+  it("matches the page origin and rejects a different host", () => {
+    expect(isSameOrigin("https://vault.example.com/x")).toBe(true);
+    expect(isSameOrigin("https://evil.com/x")).toBe(false);
+  });
+});

packages/shim/src/workspace.js

@@ -86,71 +86,40 @@ export function loadPresetIfRequested() {
   }
 }
 
-export function resolveWorkspaceName() {
+function readJsonIfPresent(path) {
   try {
-    const vaultParam = window.__currentVaultId
-      ? "?vault=" + encodeURIComponent(window.__currentVaultId)
-      : "";
+    return JSON.parse(fsShim.readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
 
-    const sep = vaultParam ? "&" : "?";
+export function resolveWorkspaceName() {
+  // With no URL param, only resolve a workspace when the workspaces core plugin is enabled.
+  if (!window.__workspaceName) {
+    const corePlugins = readJsonIfPresent(".obsidian/core-plugins.json");
 
-    // If no param provided, check if workspaces plugin is enabled before resolving.
-    if (!window.__workspaceName) {
-      const coreXhr = new XMLHttpRequest();
-
-      coreXhr.open(
-        "GET",
-        "/api/fs/readFile" +
-          vaultParam +
-          sep +
-          "path=.obsidian/core-plugins.json&encoding=utf-8",
-        false,
-      );
-      coreXhr.send();
-
-      if (coreXhr.status !== 200) {
-        return;
-      }
-
-      const corePlugins = JSON.parse(coreXhr.responseText);
-
-      if (!corePlugins.workspaces) {
-        return;
-      }
-    }
-
-    // Read workspaces.json to get the active field.
-    const xhr = new XMLHttpRequest();
-
-    xhr.open(
-      "GET",
-      "/api/fs/readFile" +
-        vaultParam +
-        sep +
-        "path=.obsidian/workspaces.json&encoding=utf-8",
-      false,
-    );
-    xhr.send();
-
-    if (xhr.status !== 200) {
+    if (!corePlugins || !corePlugins.workspaces) {
       return;
     }
+  }
 
-    const workspaces = JSON.parse(xhr.responseText);
+  const workspaces = readJsonIfPresent(WORKSPACES_PATH);
 
-    // Always store the original active value for the write transform.
-    if (workspaces.active) {
-      window.__originalActiveWorkspace = workspaces.active;
-    }
+  if (!workspaces) {
+    return;
+  }
 
-    // If no param was provided, seed from the active workspace.
-    if (!window.__workspaceName && workspaces.active) {
-      window.__workspaceName = workspaces.active;
-      setWorkspaceParam(workspaces.active);
-      console.log("[ignis] Workspace resolved from active:", workspaces.active);
-    }
-  } catch (e) {
-    console.warn("[ignis] Failed to resolve workspace name:", e);
+  // Keep the original active value so the write transform can restore it on disk.
+  if (workspaces.active) {
+    window.__originalActiveWorkspace = workspaces.active;
+  }
+
+  // With no URL param, seed from the active workspace.
+  if (!window.__workspaceName && workspaces.active) {
+    window.__workspaceName = workspaces.active;
+    setWorkspaceParam(workspaces.active);
+    console.log("[ignis] Workspace resolved from active:", workspaces.active);
   }
 }
 

packages/shim/src/ws-client.js

@@ -8,12 +8,14 @@ export function createWsClient() {
   let vaultId = null;
   let reconnectTimer = null;
   let manuallyClosed = false;
+  let hasConnectedBefore = false;
   let state = "closed"; // "closed" | "connecting" | "open"
 
   const globalSubs = new Map(); // type -> Set<handler>
   const channelSubs = new Map(); // channelName -> Map<type, Set<handler>>
   const channelSubCount = new Map(); // channelName -> integer
   const stateSubs = new Set(); // handler(state)
+  const reconnectSubs = new Set(); // handler() fired on a re-open, not the first open
 
   function setState(next) {
     if (state === next) {
@@ -107,6 +109,20 @@ export function createWsClient() {
       for (const name of channelSubCount.keys()) {
         sendSubscribeChannel(name);
       }
+
+      // A re-open can miss watcher events that fired while the socket was down.
+      // Boot covers the first open, so handlers fire only on later opens.
+      if (hasConnectedBefore) {
+        for (const fn of reconnectSubs) {
+          try {
+            fn();
+          } catch (e) {
+            console.error("[ws] reconnect subscriber threw:", e);
+          }
+        }
+      } else {
+        hasConnectedBefore = true;
+      }
     };
 
     ws.onmessage = (event) => {
@@ -252,6 +268,14 @@ export function createWsClient() {
     };
   }
 
+  function onReconnect(handler) {
+    reconnectSubs.add(handler);
+
+    return () => {
+      reconnectSubs.delete(handler);
+    };
+  }
+
   return {
     connect,
     disconnect,
@@ -260,6 +284,7 @@ export function createWsClient() {
     channel,
     isOpen,
     onStateChange,
+    onReconnect,
   };
 }
 

packages/shim/src/ws-client.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createWsClient } from "./ws-client.js";
+
+let sockets;
+
+beforeEach(() => {
+  sockets = [];
+
+  class FakeWebSocket {
+    constructor(url) {
+      this.url = url;
+      this.readyState = 0;
+      sockets.push(this);
+    }
+    send() {}
+    close() {}
+  }
+
+  FakeWebSocket.OPEN = 1;
+  globalThis.WebSocket = FakeWebSocket;
+  globalThis.window = { location: { protocol: "http:", host: "localhost" } };
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  delete globalThis.WebSocket;
+  delete globalThis.window;
+});
+
+describe("ws-client reconnect", () => {
+  it("fires onReconnect on a re-open but not on the first open", () => {
+    const client = createWsClient();
+    const onReconnect = vi.fn();
+    client.onReconnect(onReconnect);
+
+    client.connect("v1");
+    sockets[0].onopen();
+    expect(onReconnect).not.toHaveBeenCalled();
+
+    sockets[0].onclose();
+    vi.advanceTimersByTime(2000);
+    sockets[1].onopen();
+
+    expect(onReconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops firing after unsubscribe", () => {
+    const client = createWsClient();
+    const onReconnect = vi.fn();
+    const off = client.onReconnect(onReconnect);
+
+    client.connect("v1");
+    sockets[0].onopen();
+    off();
+
+    sockets[0].onclose();
+    vi.advanceTimersByTime(2000);
+    sockets[1].onopen();
+
+    expect(onReconnect).not.toHaveBeenCalled();
+  });
+});