@hardikg/mdview 0.7.0 → 0.8.1

package/bin/mdview.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync, readFileSync, realpathSync, statSync } from "fs";
-import path11 from "path";
+import dns from "dns/promises";
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync, statSync as statSync4 } from "fs";
+import path14 from "path";
 import { fileURLToPath } from "url";
+import chokidar3 from "chokidar";
 import openBrowser from "open";
 
 // src/server/config.ts
@@ -329,13 +331,430 @@ async function runIgnoreSubcommand(argv) {
   }
 }
 
+// src/daemon/client.ts
+import { spawn } from "child_process";
+import { closeSync, openSync as openSync2, statSync as statSync2, truncateSync } from "fs";
+
+// src/daemon/state.ts
+import { mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
+import path3 from "path";
+function stateDir() {
+  return path3.dirname(globalConfigPath());
+}
+function daemonStatePath() {
+  return path3.join(stateDir(), "daemon.json");
+}
+function workspaceFilePath() {
+  return path3.join(stateDir(), "workspace.json");
+}
+function daemonLogPath() {
+  return path3.join(stateDir(), "daemon.log");
+}
+function daemonLockPath() {
+  return path3.join(stateDir(), "daemon.lock");
+}
+function writeJsonAtomic(file, value) {
+  mkdirSync(path3.dirname(file), { recursive: true, mode: 448 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  renameSync(tmp, file);
+}
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isPositiveInt(v) {
+  return typeof v === "number" && Number.isInteger(v) && v > 0;
+}
+function readDaemonState() {
+  const raw = readJsonSafe(daemonStatePath());
+  if (!raw || typeof raw !== "object") return null;
+  const { pid, port, startedAt } = raw;
+  if (!isPositiveInt(pid) || !isPositiveInt(port) || !isPositiveInt(startedAt)) return null;
+  if (port > 65535) return null;
+  return { pid, port, startedAt };
+}
+function writeDaemonState(state) {
+  writeJsonAtomic(daemonStatePath(), state);
+}
+function clearDaemonState() {
+  rmSync(daemonStatePath(), { force: true });
+}
+function tryTakeSpawnLock(staleAfterMs = 1e4) {
+  mkdirSync(stateDir(), { recursive: true, mode: 448 });
+  const file = daemonLockPath();
+  try {
+    openSync(file, "wx");
+    return true;
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+  try {
+    if (Date.now() - statSync(file).mtimeMs < staleAfterMs) return false;
+    rmSync(file, { force: true });
+    openSync(file, "wx");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function releaseSpawnLock() {
+  rmSync(daemonLockPath(), { force: true });
+}
+
+// src/daemon/client.ts
+var HEALTH_TIMEOUT_MS = 500;
+var START_TIMEOUT_MS = 8e3;
+var POLL_INTERVAL_MS = 50;
+var LOG_TRUNCATE_BYTES = 1024 * 1024;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function probeHealth(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (typeof body.pid !== "number" || typeof body.startedAt !== "number") return null;
+    return {
+      pid: body.pid,
+      startedAt: body.startedAt,
+      roots: Array.isArray(body.roots) ? body.roots.filter((r) => typeof r === "string") : []
+    };
+  } catch {
+    return null;
+  }
+}
+async function findLiveDaemon() {
+  const state = readDaemonState();
+  if (!state) return null;
+  const health = await probeHealth(state.port);
+  if (!health) return null;
+  if (health.pid !== state.pid || health.startedAt !== state.startedAt) return null;
+  return { state, health };
+}
+function spawnDaemon(cliEntry) {
+  try {
+    if (statSync2(daemonLogPath()).size > LOG_TRUNCATE_BYTES) {
+      truncateSync(daemonLogPath(), 0);
+    }
+  } catch {
+  }
+  const log = openSync2(daemonLogPath(), "a");
+  try {
+    const child = spawn(process.execPath, [cliEntry, "--daemon"], {
+      detached: true,
+      // Nothing may hold the terminal: stdout and stderr go to the log so the
+      // parent can exit while the daemon keeps running.
+      stdio: ["ignore", log, log]
+    });
+    child.unref();
+    return child;
+  } finally {
+    closeSync(log);
+  }
+}
+async function ensureDaemon(cliEntry) {
+  const existing = await findLiveDaemon();
+  if (existing) return existing.state;
+  if (!tryTakeSpawnLock()) {
+    const found = await waitFor(() => findLiveDaemon(), START_TIMEOUT_MS);
+    if (found) return found.state;
+    throw new Error("Timed out waiting for the mdview background server to start.");
+  }
+  try {
+    clearDaemonState();
+    spawnDaemon(cliEntry);
+    const found = await waitFor(() => findLiveDaemon(), START_TIMEOUT_MS);
+    if (!found) {
+      throw new Error(
+        `The mdview background server did not start. See ${daemonLogPath()} for why.`
+      );
+    }
+    return found.state;
+  } finally {
+    releaseSpawnLock();
+  }
+}
+async function waitFor(attempt, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const result = await attempt();
+    if (result) return result;
+    if (Date.now() >= deadline) return null;
+    await sleep(POLL_INTERVAL_MS);
+  }
+}
+async function waitForRoot(port, rootId, timeoutMs = 3e3) {
+  const found = await waitFor(async () => {
+    const health = await probeHealth(port);
+    return health?.roots.includes(rootId) ? health : null;
+  }, timeoutMs);
+  return found !== null;
+}
+async function stopDaemon() {
+  const state = readDaemonState();
+  if (!state) return { kind: "not-running" };
+  const live = await findLiveDaemon();
+  if (!live) {
+    clearDaemonState();
+    return { kind: "stale" };
+  }
+  try {
+    if (process.platform === "win32") {
+      process.kill(live.state.pid);
+    } else {
+      process.kill(live.state.pid, "SIGTERM");
+    }
+  } catch {
+    clearDaemonState();
+    return { kind: "stale" };
+  }
+  await waitFor(async () => await probeHealth(live.state.port) === null ? true : null, 3e3);
+  clearDaemonState();
+  return { kind: "stopped", pid: live.state.pid };
+}
+
+// src/daemon/workspace-file.ts
+import { existsSync, statSync as statSync3 } from "fs";
+import path5 from "path";
+
+// src/server/workspace.ts
+import path4 from "path";
+var ROOT_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+function isValidRootId(id) {
+  return id !== "." && id !== ".." && ROOT_ID_PATTERN.test(id);
+}
+function deriveRootId(absPath, taken) {
+  const slug = path4.basename(absPath).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").replace(/[-.]+$/, "").slice(0, 64);
+  const stem = isValidRootId(slug) ? slug : "root";
+  if (!taken.has(stem)) return stem;
+  for (let n = 2; ; n++) {
+    const candidate = `${stem.slice(0, 60)}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+function resolveRootId(spec, taken) {
+  if (spec.id && isValidRootId(spec.id) && !taken.has(spec.id)) return spec.id;
+  return deriveRootId(spec.absPath, taken);
+}
+function describeRoot(spec, id) {
+  return {
+    id,
+    name: spec.name ?? path4.basename(spec.absPath),
+    kind: spec.kind,
+    filePath: spec.kind === "file" ? spec.filePath ?? "" : ""
+  };
+}
+function parseWorkspacePath(roots, wsPath) {
+  const primary = roots[0];
+  if (!primary) return null;
+  const trimmed = wsPath.replace(/^\/+/, "");
+  const slash = trimmed.indexOf("/");
+  const head = slash === -1 ? trimmed : trimmed.slice(0, slash);
+  const match = roots.find((r) => r.root.id === head);
+  if (!match) return { state: primary, rel: trimmed };
+  return { state: match, rel: slash === -1 ? "" : trimmed.slice(slash + 1) };
+}
+function toWorkspacePath(rootId, rel) {
+  return rel ? `${rootId}/${rel}` : rootId;
+}
+
+// src/daemon/workspace-file.ts
+var MAX_ROOTS = 8;
+function validateRecord(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  if (typeof r.id !== "string" || !isValidRootId(r.id)) return null;
+  if (typeof r.path !== "string" || !path5.isAbsolute(r.path)) return null;
+  if (r.kind !== "file" && r.kind !== "dir") return null;
+  const out = { id: r.id, path: r.path, kind: r.kind };
+  if (typeof r.name === "string" && r.name.length > 0 && r.name.length <= 128) out.name = r.name;
+  if (r.kind === "file") {
+    if (typeof r.filePath !== "string" || r.filePath.length === 0) return null;
+    if (r.filePath.includes("/") || r.filePath.includes("\\")) return null;
+    out.filePath = r.filePath;
+  }
+  return out;
+}
+function readWorkspace() {
+  const raw = readJsonSafe(workspaceFilePath());
+  if (!raw || typeof raw !== "object") return { roots: [] };
+  const list = raw.roots;
+  if (!Array.isArray(list)) return { roots: [] };
+  const seen = /* @__PURE__ */ new Set();
+  const roots = [];
+  for (const entry of list.slice(0, MAX_ROOTS)) {
+    const rec = validateRecord(entry);
+    if (!rec || seen.has(rec.id)) continue;
+    seen.add(rec.id);
+    roots.push(rec);
+  }
+  return { roots };
+}
+function writeWorkspace(record) {
+  writeJsonAtomic(workspaceFilePath(), record);
+}
+function toRootSpecs(record) {
+  return record.roots.map((r) => ({
+    absPath: r.path,
+    id: r.id,
+    ...r.name === void 0 ? {} : { name: r.name },
+    kind: r.kind,
+    ...r.filePath === void 0 ? {} : { filePath: r.filePath }
+  }));
+}
+function resolveTarget(target) {
+  const abs = path5.resolve(target);
+  if (!existsSync(abs)) throw new Error(`Path does not exist: ${abs}`);
+  const st = statSync3(abs);
+  if (st.isDirectory()) {
+    return { absPath: abs, kind: "dir", filePath: "", name: path5.basename(abs) };
+  }
+  if (st.isFile()) {
+    const dir = path5.dirname(abs);
+    return { absPath: dir, kind: "file", filePath: path5.basename(abs), name: path5.basename(abs) };
+  }
+  throw new Error(`Unsupported path type: ${abs}`);
+}
+function findCovering(roots, abs) {
+  let best = null;
+  for (const root of roots) {
+    if (root.kind !== "dir" && root.path !== abs) continue;
+    const rel = path5.relative(root.path, abs);
+    if (rel.startsWith("..") || path5.isAbsolute(rel)) continue;
+    if (!best || root.path.length > best.root.path.length) {
+      best = { root, rel: rel.split(path5.sep).join("/") };
+    }
+  }
+  return best;
+}
+function addRoot(target) {
+  const resolved = resolveTarget(target);
+  const record = readWorkspace();
+  const fullPath = resolved.kind === "file" ? path5.join(resolved.absPath, resolved.filePath) : resolved.absPath;
+  const covering = findCovering(record.roots, fullPath);
+  if (covering) {
+    const wsPath = covering.rel ? `${covering.root.id}/${covering.rel}` : covering.root.id;
+    return {
+      root: covering.root,
+      filePath: resolved.kind === "file" ? wsPath : "",
+      focusPath: resolved.kind === "file" ? "" : wsPath,
+      changed: false
+    };
+  }
+  if (record.roots.length >= MAX_ROOTS) {
+    throw new Error(
+      `Workspace is full (${MAX_ROOTS} folders). Close one with 'mdview rm <name>' first.`
+    );
+  }
+  const id = deriveRootId(resolved.absPath, new Set(record.roots.map((r) => r.id)));
+  const root = {
+    id,
+    path: resolved.absPath,
+    kind: resolved.kind,
+    ...resolved.kind === "file" ? { name: resolved.name, filePath: resolved.filePath } : {}
+  };
+  record.roots.push(root);
+  writeWorkspace(record);
+  return {
+    root,
+    filePath: resolved.kind === "file" ? `${id}/${resolved.filePath}` : "",
+    focusPath: resolved.kind === "file" ? "" : id,
+    changed: true
+  };
+}
+function removeRoot(idOrPath) {
+  const record = readWorkspace();
+  const abs = path5.resolve(idOrPath);
+  const idx = record.roots.findIndex((r) => r.id === idOrPath || r.path === abs);
+  if (idx === -1) return null;
+  const [removed] = record.roots.splice(idx, 1);
+  writeWorkspace(record);
+  return removed ?? null;
+}
+
+// src/cli-workspace.ts
+function tilde(abs) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return home && abs.startsWith(home) ? `~${abs.slice(home.length)}` : abs;
+}
+async function runListCommand() {
+  const { roots } = readWorkspace();
+  const live = await findLiveDaemon();
+  if (roots.length === 0) {
+    console.log("No folders open. Run `mdview <path>` to add one.");
+  } else {
+    const open = new Set(live?.health.roots ?? []);
+    const idWidth = Math.max(...roots.map((r) => r.id.length));
+    for (const [i, r] of roots.entries()) {
+      const mark = live ? open.has(r.id) ? "\u25CF" : "\u25CB" : " ";
+      const label = i === 0 ? "  (primary)" : "";
+      const suffix = r.kind === "file" ? `  \u2192 ${r.filePath}` : "";
+      console.log(`${mark} ${r.id.padEnd(idWidth)}  ${tilde(r.path)}${suffix}${label}`);
+    }
+    if (roots.length >= MAX_ROOTS) {
+      console.log(`
+Workspace is full (${MAX_ROOTS}). Remove one with \`mdview rm <name>\`.`);
+    }
+  }
+  console.log("");
+  if (live) {
+    console.log(`server:  http://mdview.localhost:${live.state.port}/  (pid ${live.state.pid})`);
+    console.log(`logs:    ${daemonLogPath()}`);
+  } else {
+    console.log("server:  not running \u2014 the next `mdview <path>` will start it");
+  }
+  return 0;
+}
+async function runRemoveCommand(argv) {
+  const targets = argv.filter((a) => !a.startsWith("-"));
+  if (targets.length === 0) {
+    console.error("Usage: mdview rm <name|path>\u2026");
+    return 2;
+  }
+  let removedAny = false;
+  for (const target of targets) {
+    const removed = removeRoot(target);
+    if (removed) {
+      removedAny = true;
+      console.log(`Removed ${removed.id} (${tilde(removed.path)})`);
+    } else {
+      console.error(`Not open: ${target}`);
+    }
+  }
+  if (!removedAny) return 2;
+  console.log("Open tabs will update on their own.");
+  return 0;
+}
+async function runStopCommand() {
+  const outcome = await stopDaemon();
+  switch (outcome.kind) {
+    case "stopped":
+      console.log(`mdview: stopped (pid ${outcome.pid})`);
+      return 0;
+    case "not-running":
+      console.log("mdview: not running");
+      return 0;
+    case "stale":
+      console.log("mdview: not running (cleared a stale record)");
+      return 0;
+  }
+}
+
 // src/server/index.ts
-import path10 from "path";
+import path13 from "path";
 import chokidar2 from "chokidar";
 import Fastify from "fastify";
 
 // src/server/fs/ignore.ts
-import path3 from "path";
+import path6 from "path";
 var DEFAULT_IGNORED_DIRS2 = new Set(DEFAULT_IGNORED_DIRS);
 function buildIgnoreSet(extra = []) {
   return /* @__PURE__ */ new Set([...DEFAULT_IGNORED_DIRS2, ...extra]);
@@ -344,9 +763,9 @@ function isDirIgnored(name, set) {
   return name.startsWith(".") || set.has(name);
 }
 function isPathIgnored(abs, root, set) {
-  const rel = path3.relative(root, abs);
+  const rel = path6.relative(root, abs);
   if (rel === "" || rel.startsWith("..")) return false;
-  for (const seg of rel.split(path3.sep)) {
+  for (const seg of rel.split(path6.sep)) {
     if (!seg) continue;
     if (seg.startsWith(".")) return true;
     if (set.has(seg)) return true;
@@ -354,21 +773,41 @@ function isPathIgnored(abs, root, set) {
   return false;
 }
 
+// src/server/hosts.ts
+var LOOPBACK_NAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+var MAX_HOST_LEN = 253;
+function hostOnly(value) {
+  const h = value.trim().toLowerCase();
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    return end === -1 ? h : h.slice(0, end + 1);
+  }
+  if (h.indexOf(":") !== h.lastIndexOf(":")) return h;
+  const colon = h.indexOf(":");
+  return colon === -1 ? h : h.slice(0, colon);
+}
+function isAllowedHost(value) {
+  if (!value || value.length > MAX_HOST_LEN) return false;
+  if (!/^[\x21-\x7e]+$/.test(value)) return false;
+  const host = hostOnly(value);
+  return LOOPBACK_NAMES.has(host) || /^[a-z0-9][a-z0-9.-]*\.localhost$/.test(host);
+}
+
 // src/server/routes/api-asset.ts
 import { createReadStream } from "fs";
 import { stat } from "fs/promises";
-import path5 from "path";
+import path8 from "path";
 
 // src/server/fs/resolve.ts
-import path4 from "path";
+import path7 from "path";
 function resolveSafePath(root, relPath) {
-  if (path4.isAbsolute(relPath)) {
+  if (path7.isAbsolute(relPath)) {
     throw new Error(`Refusing absolute path: ${relPath}`);
   }
-  const absRoot = path4.resolve(root);
-  const candidate = path4.resolve(absRoot, relPath);
-  const rel = path4.relative(absRoot, candidate);
-  if (rel.startsWith("..") || path4.isAbsolute(rel)) {
+  const absRoot = path7.resolve(root);
+  const candidate = path7.resolve(absRoot, relPath);
+  const rel = path7.relative(absRoot, candidate);
+  if (rel.startsWith("..") || path7.isAbsolute(rel)) {
     throw new Error(`Path resolves outside root: ${relPath}`);
   }
   return candidate;
@@ -393,12 +832,16 @@ var MIME = {
   ".pdf": "application/pdf",
   ".txt": "text/plain; charset=utf-8"
 };
-function registerApiAsset(app, rootAbsPath) {
+function registerApiAsset(app, roots) {
   app.get("/__asset/*", async (req, reply) => {
-    const rel = (req.params["*"] ?? "").replace(/^\/+/, "");
+    const wsPath = (req.params["*"] ?? "").replace(/^\/+/, "");
+    const resolved = parseWorkspacePath(roots, wsPath);
+    if (!resolved) {
+      return reply.code(404).send({ error: "Asset not found" });
+    }
     let abs;
     try {
-      abs = resolveSafePath(rootAbsPath, rel);
+      abs = resolveSafePath(resolved.state.absPath, resolved.rel);
     } catch (err) {
       return reply.code(400).send({ error: err.message });
     }
@@ -411,7 +854,7 @@ function registerApiAsset(app, rootAbsPath) {
     if (!st.isFile()) {
       return reply.code(404).send({ error: "Not a file" });
     }
-    const ext = path5.extname(abs).toLowerCase();
+    const ext = path8.extname(abs).toLowerCase();
     const mime = MIME[ext];
     if (!mime) {
       return reply.code(404).send({ error: "Asset type not allowed" });
@@ -464,18 +907,18 @@ function computeBodyStartLine(raw) {
 }
 
 // src/render/links.ts
-import path6 from "path/posix";
+import path9 from "path/posix";
 var MD_EXT_RE = /\.(md|markdown|mdx)$/i;
 var HREF_RE = /<a\s+([^>]*?)href="([^"#?]*)(\?[^"#]*)?(#[^"]*)?"([^>]*)>/gi;
 var IMG_SRC_RE = /<img\s+([^>]*?)src="([^"]+)"([^>]*)>/gi;
 function tagInternalLinks(html, currentRelPath) {
-  const currentDir = path6.dirname(currentRelPath);
+  const currentDir = path9.dirname(currentRelPath);
   return html.replace(HREF_RE, (full, pre, target, query, hash, post) => {
     if (!target || /^https?:\/\//i.test(target) || target.startsWith("mailto:")) {
       return full;
     }
     if (!MD_EXT_RE.test(target)) return full;
-    const resolved = path6.normalize(path6.join(currentDir, target));
+    const resolved = path9.normalize(path9.join(currentDir, target));
     let decoded;
     try {
       decoded = decodeURIComponent(resolved);
@@ -488,12 +931,12 @@ function tagInternalLinks(html, currentRelPath) {
   });
 }
 function rewriteImageSrc(html, currentRelPath) {
-  const currentDir = path6.dirname(currentRelPath);
+  const currentDir = path9.dirname(currentRelPath);
   return html.replace(IMG_SRC_RE, (full, pre, src, post) => {
     if (!src) return full;
     if (/^(https?:\/\/|data:|\/__asset\/)/i.test(src)) return full;
     const trimmed = src.replace(/^\/+/, "");
-    const resolved = path6.normalize(path6.join(currentDir, trimmed));
+    const resolved = path9.normalize(path9.join(currentDir, trimmed));
     if (resolved.startsWith("..")) return full;
     return `<img ${pre}src="/__asset/${resolved}"${post}>`;
   });
@@ -725,27 +1168,34 @@ function nest(flat) {
 }
 
 // src/server/routes/api-file.ts
-function registerApiFile(app, rootAbsPath, rootInfo) {
+function registerApiFile(app, roots) {
   app.get("/api/file", async (req, reply) => {
     const requested = req.query.path?.trim() ?? "";
-    let relPath;
-    if (rootInfo.rootKind === "file") {
-      if (requested && requested !== rootInfo.rootRelPath) {
-        return reply.code(404).send({ error: "File not found in single-file mode" });
-      }
-      relPath = rootInfo.rootRelPath;
-    } else {
-      if (!requested) {
+    const primary = roots[0];
+    if (!primary) {
+      return reply.code(404).send({ error: "No folders are open" });
+    }
+    let wsPath = requested;
+    if (!wsPath) {
+      if (primary.root.kind !== "file") {
         return reply.code(400).send({ error: "Missing ?path" });
       }
-      relPath = requested;
+      wsPath = toWorkspacePath(primary.root.id, primary.root.filePath);
     }
-    if (!/\.(md|markdown|mdx)$/i.test(relPath)) {
+    const resolved = parseWorkspacePath(roots, wsPath);
+    if (!resolved) {
+      return reply.code(404).send({ error: "File not found" });
+    }
+    const { state, rel } = resolved;
+    if (state.root.kind === "file" && rel !== state.root.filePath) {
+      return reply.code(404).send({ error: "File not found in single-file mode" });
+    }
+    if (!/\.(md|markdown|mdx)$/i.test(rel)) {
       return reply.code(400).send({ error: "Only markdown files are supported" });
     }
     let absPath;
     try {
-      absPath = resolveSafePath(rootAbsPath, relPath);
+      absPath = resolveSafePath(state.absPath, rel);
     } catch (err) {
       return reply.code(400).send({ error: err.message });
     }
@@ -763,11 +1213,12 @@ function registerApiFile(app, rootAbsPath, rootInfo) {
     }
     const { data, body, bodyStartLine } = parseFrontmatter(raw);
     const { html: rawHtml, tokens } = await renderMarkdown(body, bodyStartLine);
-    const html = rewriteImageSrc(tagInternalLinks(rawHtml, relPath), relPath);
+    const wsRel = toWorkspacePath(state.root.id, rel);
+    const html = rewriteImageSrc(tagInternalLinks(rawHtml, wsRel), wsRel);
     const outline = extractOutline(tokens);
     const title = (typeof data?.title === "string" ? data.title : null) ?? outline[0]?.text ?? null;
     const result = {
-      relPath,
+      relPath: wsRel,
       html,
       outline,
       frontmatter: data,
@@ -865,13 +1316,12 @@ function flattenMdRelPaths(nodes, out = []) {
 
 // src/server/fs/tree.ts
 import { readdir } from "fs/promises";
-import path7 from "path";
+import path10 from "path";
 async function walkFolder(root, opts = {}) {
   const ignore = opts.ignore ?? DEFAULT_IGNORED_DIRS2;
-  return walkInner(root, "", ignore);
+  return walkInner(root, opts.relBase ?? "", ignore);
 }
-async function walkInner(root, relBase, ignore) {
-  const absDir = path7.join(root, relBase);
+async function walkInner(absDir, relBase, ignore) {
   const entries = await readdir(absDir, { withFileTypes: true });
   const out = [];
   for (const entry of entries) {
@@ -882,7 +1332,7 @@ async function walkInner(root, relBase, ignore) {
     }
     const childRel = relBase ? `${relBase}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
-      const children = await walkInner(root, childRel, ignore);
+      const children = await walkInner(path10.join(absDir, entry.name), childRel, ignore);
       out.push({
         name: entry.name,
         relPath: childRel,
@@ -890,7 +1340,7 @@ async function walkInner(root, relBase, ignore) {
         children
       });
     } else if (entry.isFile()) {
-      const ext = path7.extname(entry.name).toLowerCase();
+      const ext = path10.extname(entry.name).toLowerCase();
       out.push({
         name: entry.name,
         relPath: childRel,
@@ -920,7 +1370,7 @@ function buildSnippet(line, start, end, radius) {
     highlight: [hlStart, hlEnd]
   };
 }
-async function grepFiles(rootAbsPath, query, opts = {}) {
+async function grepFiles(roots, query, opts = {}) {
   const perFileCap = opts.perFileCap ?? 20;
   const globalCap = opts.globalCap ?? 200;
   const snippetRadius = opts.snippetRadius ?? 60;
@@ -936,64 +1386,75 @@ async function grepFiles(rootAbsPath, query, opts = {}) {
     regex: opts.regex ?? false
   });
   if (!pattern.valid) return { query, results: [], truncated: false };
-  const tree = await walkFolder(rootAbsPath, { ignore: opts.ignore });
-  const files = flattenMdRelPaths(tree);
   const results = [];
   let totalHits = 0;
   let truncated = false;
-  for (const relPath of files) {
+  for (const root of roots) {
     if (totalHits >= globalCap) {
       truncated = true;
       break;
     }
-    let absPath;
-    try {
-      absPath = resolveSafePath(rootAbsPath, relPath);
-    } catch {
-      continue;
-    }
-    let raw;
-    try {
-      raw = await readFile4(absPath, "utf8");
-    } catch {
-      continue;
-    }
-    const { body } = parseFrontmatter(raw);
-    const lines = body.split(/\r?\n/);
-    const fileHits = [];
-    let fileTotal = 0;
-    let fileTruncated = false;
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (regexMode && line.length > maxLineLenForRegex) {
-        fileTruncated = true;
+    const tree = await walkFolder(root.absPath, { ignore: root.ignore ?? opts.ignore });
+    const files = flattenMdRelPaths(tree);
+    for (const relPath of files) {
+      if (totalHits >= globalCap) {
+        truncated = true;
+        break;
+      }
+      let absPath;
+      try {
+        absPath = resolveSafePath(root.absPath, relPath);
+      } catch {
         continue;
       }
-      const { matches, truncated: lineTruncated } = regexMode ? pattern.matchAllWithBudget(line, perLineBudgetMs) : { matches: pattern.matchAll(line), truncated: false };
-      if (lineTruncated) fileTruncated = true;
-      for (const m of matches) {
-        fileTotal++;
-        if (fileHits.length < perFileCap) {
-          const { snippet, highlight } = buildSnippet(
-            line,
-            m.index,
-            m.index + m.length,
-            snippetRadius
-          );
-          fileHits.push({ line: i + 1, col: m.index, snippet, highlight });
-          totalHits++;
-        } else {
+      let raw;
+      try {
+        raw = await readFile4(absPath, "utf8");
+      } catch {
+        continue;
+      }
+      const { body } = parseFrontmatter(raw);
+      const lines = body.split(/\r?\n/);
+      const fileHits = [];
+      let fileTotal = 0;
+      let fileTruncated = false;
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (regexMode && line.length > maxLineLenForRegex) {
           fileTruncated = true;
+          continue;
         }
-        if (totalHits >= globalCap) {
-          truncated = true;
-          break;
+        const { matches, truncated: lineTruncated } = regexMode ? pattern.matchAllWithBudget(line, perLineBudgetMs) : { matches: pattern.matchAll(line), truncated: false };
+        if (lineTruncated) fileTruncated = true;
+        for (const m of matches) {
+          fileTotal++;
+          if (fileHits.length < perFileCap) {
+            const { snippet, highlight } = buildSnippet(
+              line,
+              m.index,
+              m.index + m.length,
+              snippetRadius
+            );
+            fileHits.push({ line: i + 1, col: m.index, snippet, highlight });
+            totalHits++;
+          } else {
+            fileTruncated = true;
+          }
+          if (totalHits >= globalCap) {
+            truncated = true;
+            break;
+          }
         }
+        if (totalHits >= globalCap) break;
+      }
+      if (fileHits.length > 0) {
+        results.push({
+          relPath: `${root.id}/${relPath}`,
+          hits: fileHits,
+          total: fileTotal,
+          truncated: fileTruncated
+        });
       }
-      if (totalHits >= globalCap) break;
-    }
-    if (fileHits.length > 0) {
-      results.push({ relPath, hits: fileHits, total: fileTotal, truncated: fileTruncated });
     }
   }
   return { query, results, truncated };
@@ -1004,11 +1465,8 @@ var MAX_QUERY_LEN = 200;
 function isTrue(v) {
   return v === "1" || v === "true";
 }
-function registerApiSearch(app, rootAbsPath, rootInfo, configState) {
+function registerApiSearch(app, roots) {
   app.get("/api/search", async (req, reply) => {
-    if (rootInfo.rootKind === "file") {
-      return reply.send({ query: req.query.q ?? "", results: [], truncated: false });
-    }
     const q = (req.query.q ?? "").trim();
     if (q.length === 0) {
       return reply.send({ query: "", results: [], truncated: false });
@@ -1016,43 +1474,76 @@ function registerApiSearch(app, rootAbsPath, rootInfo, configState) {
     if (q.length > MAX_QUERY_LEN) {
       return reply.code(400).send({ error: "Query too long" });
     }
-    const out = await grepFiles(rootAbsPath, q, {
+    const searchable = roots.filter((r) => r.root.kind === "dir").map((r) => ({ absPath: r.absPath, id: r.root.id, ignore: r.ignoreSet }));
+    const out = await grepFiles(searchable, q, {
       caseSensitive: isTrue(req.query.case),
       wholeWord: isTrue(req.query.word),
-      regex: isTrue(req.query.regex),
-      ignore: configState.ignoreSet
+      regex: isTrue(req.query.regex)
     });
     return reply.send(out);
   });
 }
 
 // src/server/routes/api-tree.ts
-import path8 from "path";
+import path11 from "path";
 function applyOverrides(config, paletteOverride) {
   if (!paletteOverride) return config;
   return { ...config ?? {}, palette: paletteOverride };
 }
-function registerApiTree(app, rootAbsPath, rootInfo, configState) {
+async function rootChildren(state) {
+  const { id, kind, filePath } = state.root;
+  if (kind === "file") {
+    return [
+      {
+        name: path11.basename(filePath),
+        relPath: toWorkspacePath(id, filePath),
+        type: "file",
+        isMarkdown: true
+      }
+    ];
+  }
+  return walkFolder(state.absPath, { ignore: state.ignoreSet, relBase: id });
+}
+function registerApiTree(app, roots, paletteOverride) {
   app.get("/api/tree", async (_req, reply) => {
-    const config = applyOverrides(configState.current, configState.paletteOverride);
-    if (rootInfo.rootKind === "file") {
-      const single = [
-        {
-          name: path8.basename(rootInfo.rootRelPath),
-          relPath: rootInfo.rootRelPath,
-          type: "file",
-          isMarkdown: true
-        }
-      ];
-      return reply.send({ root: rootInfo, tree: single, config });
+    const config = applyOverrides(roots[0]?.config ?? null, paletteOverride);
+    if (roots.length === 1) {
+      const only = roots[0];
+      return reply.send({
+        roots: [only.root],
+        tree: await rootChildren(only),
+        config
+      });
     }
-    const tree = await walkFolder(rootAbsPath, { ignore: configState.ignoreSet });
-    return reply.send({ root: rootInfo, tree, config });
+    const tree = [];
+    for (const state of roots) {
+      tree.push({
+        name: state.root.name,
+        relPath: state.root.id,
+        type: "dir",
+        children: await rootChildren(state)
+      });
+    }
+    return reply.send({ roots: roots.map((r) => r.root), tree, config });
   });
 }
 
+// src/server/routes/health.ts
+function registerHealth(app, identity, roots) {
+  app.get(
+    "/api/health",
+    async (_req, reply) => reply.send({
+      ok: true,
+      pid: identity.pid,
+      startedAt: identity.startedAt,
+      roots: roots.map((r) => r.root.id)
+    })
+  );
+}
+
 // src/server/routes/sse.ts
-function registerSse(app, watcher) {
+function registerSse(app, hub, hooks = {}) {
+  let clients = 0;
   app.get("/api/watch", (req, reply) => {
     reply.raw.writeHead(200, {
       "Content-Type": "text/event-stream",
@@ -1062,11 +1553,15 @@ function registerSse(app, watcher) {
     });
     reply.raw.write(": connected\n\n");
     let closed = false;
+    clients++;
+    hooks.onClientsChanged?.(clients);
     const cleanup = () => {
       if (closed) return;
       closed = true;
       clearInterval(heartbeat);
-      watcher.off("event", send);
+      hub.off("event", send);
+      clients--;
+      hooks.onClientsChanged?.(clients);
       try {
         reply.raw.end();
       } catch {
@@ -1092,7 +1587,7 @@ function registerSse(app, watcher) {
         cleanup();
       }
     }, 15e3);
-    watcher.on("event", send);
+    hub.on("event", send);
     req.raw.on("close", cleanup);
     req.raw.on("error", cleanup);
     reply.raw.on("error", cleanup);
@@ -1102,12 +1597,25 @@ function registerSse(app, watcher) {
 
 // src/server/watcher.ts
 import { EventEmitter } from "events";
-import path9 from "path";
+import path12 from "path";
 import chokidar from "chokidar";
+function createEventHub() {
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(0);
+  return {
+    on: (event, listener) => emitter.on(event, listener),
+    off: (event, listener) => emitter.off(event, listener),
+    emitSynthetic: (e) => emitter.emit("event", e),
+    close: async () => {
+      emitter.removeAllListeners();
+    }
+  };
+}
 function createWatcher(rootAbsPath, opts = {}) {
   const emitter = new EventEmitter();
   emitter.setMaxListeners(0);
   const ignore = opts.ignore ?? DEFAULT_IGNORED_DIRS2;
+  const prefix = opts.prefix ?? "";
   const watcher = chokidar.watch(rootAbsPath, {
     ignoreInitial: true,
     ignored: (p) => isPathIgnored(p, rootAbsPath, ignore),
@@ -1130,9 +1638,10 @@ function createWatcher(rootAbsPath, opts = {}) {
     }
   });
   function emit(kind, abs) {
-    const rel = path9.relative(rootAbsPath, abs).split(path9.sep).join("/");
+    const rel = path12.relative(rootAbsPath, abs).split(path12.sep).join("/");
     if (!rel) return;
-    emitter.emit("event", { kind, relPath: rel });
+    const relPath = prefix ? `${prefix}/${rel}` : rel;
+    emitter.emit("event", { kind, relPath });
   }
   watcher.on("change", (p) => emit("change", p));
   watcher.on("add", (p) => emit("add", p));
@@ -1147,8 +1656,7 @@ function createWatcher(rootAbsPath, opts = {}) {
 
 // src/server/index.ts
 function buildCspHtml(embedMode) {
-  const frameAncestors = embedMode ? "*" : "'none'";
-  return [
+  const directives = [
     "default-src 'self'",
     "script-src 'self'",
     // KaTeX + mermaid inject inline styles into rendered output; the rest of
@@ -1157,14 +1665,19 @@ function buildCspHtml(embedMode) {
     "img-src 'self' data: blob:",
     "font-src 'self' data:",
     "connect-src 'self'",
-    `frame-ancestors ${frameAncestors}`,
     "base-uri 'none'",
     "form-action 'none'"
-  ].join("; ");
+  ];
+  if (!embedMode) directives.push("frame-ancestors 'none'");
+  return directives.join("; ");
 }
 async function createServer(opts) {
   const app = Fastify({ logger: false });
   const cspHtml = buildCspHtml(opts.embedMode ?? false);
+  app.addHook("onRequest", async (req, reply) => {
+    if (isAllowedHost(req.headers.host)) return;
+    return reply.code(403).type("text/plain; charset=utf-8").send("Forbidden");
+  });
   app.addHook("onSend", async (_req, reply, payload) => {
     const ct = String(reply.getHeader("content-type") ?? "");
     if (ct.startsWith("text/html")) {
@@ -1174,33 +1687,76 @@ async function createServer(opts) {
     }
     return payload;
   });
-  const initialConfig = await loadEffectiveConfig(opts.rootAbsPath);
-  const ignoreSet = buildIgnoreSet(initialConfig?.ignore ?? []);
-  const configState = {
-    current: initialConfig,
-    ignoreSet,
-    paletteOverride: opts.paletteOverride
-  };
-  const watcher = createWatcher(opts.rootAbsPath, { ignore: ignoreSet });
-  const configPath = path10.join(opts.rootAbsPath, CONFIG_FILENAME);
-  const configWatcher = chokidar2.watch(configPath, {
-    ignoreInitial: true,
-    persistent: true,
-    awaitWriteFinish: { stabilityThreshold: 60, pollInterval: 30 }
-  });
-  const reloadConfig = async () => {
-    configState.current = await loadEffectiveConfig(opts.rootAbsPath);
-    const event = { kind: "config", relPath: CONFIG_FILENAME };
-    watcher.emitSynthetic?.(event);
-  };
-  configWatcher.on("add", () => void reloadConfig());
-  configWatcher.on("change", () => void reloadConfig());
-  configWatcher.on("unlink", () => void reloadConfig());
-  registerApiFile(app, opts.rootAbsPath, opts.rootInfo);
-  registerApiTree(app, opts.rootAbsPath, opts.rootInfo, configState);
-  registerApiAsset(app, opts.rootAbsPath);
-  registerApiSearch(app, opts.rootAbsPath, opts.rootInfo, configState);
-  registerSse(app, watcher);
+  const roots = [];
+  const configWatchers = /* @__PURE__ */ new Map();
+  const hub = createEventHub();
+  async function openRoot(spec, id) {
+    const config = await loadEffectiveConfig(spec.absPath);
+    const ignoreSet = buildIgnoreSet(config?.ignore ?? []);
+    const state = {
+      root: describeRoot(spec, id),
+      absPath: spec.absPath,
+      ignoreSet,
+      config,
+      watcher: createWatcher(spec.absPath, { ignore: ignoreSet, prefix: id })
+    };
+    state.watcher.on("event", (e) => hub.emitSynthetic(e));
+    const configWatcher = chokidar2.watch(path13.join(spec.absPath, CONFIG_FILENAME), {
+      ignoreInitial: true,
+      persistent: true,
+      awaitWriteFinish: { stabilityThreshold: 60, pollInterval: 30 }
+    });
+    const reloadConfig = async () => {
+      state.config = await loadEffectiveConfig(spec.absPath);
+      const event = { kind: "config", relPath: `${id}/${CONFIG_FILENAME}` };
+      hub.emitSynthetic(event);
+    };
+    configWatcher.on("add", () => void reloadConfig());
+    configWatcher.on("change", () => void reloadConfig());
+    configWatcher.on("unlink", () => void reloadConfig());
+    configWatchers.set(id, configWatcher);
+    return state;
+  }
+  async function closeRoot(state) {
+    const cw = configWatchers.get(state.root.id);
+    configWatchers.delete(state.root.id);
+    await Promise.all([state.watcher.close(), cw?.close()]);
+  }
+  async function setRoots(specs) {
+    const taken = /* @__PURE__ */ new Set();
+    const wanted = specs.map((spec) => {
+      const id = resolveRootId(spec, taken);
+      taken.add(id);
+      return { id, spec };
+    });
+    const keep = new Map(
+      roots.filter((r) => wanted.some((w) => w.id === r.root.id && w.spec.absPath === r.absPath)).map((r) => [r.root.id, r])
+    );
+    const dropped = roots.filter((r) => !keep.has(r.root.id));
+    const next = [];
+    for (const { id, spec } of wanted) {
+      const existing = keep.get(id);
+      next.push(existing ?? await openRoot(spec, id));
+    }
+    roots.length = 0;
+    roots.push(...next);
+    await Promise.all(dropped.map(closeRoot));
+    hub.emitSynthetic({ kind: "workspace" });
+  }
+  {
+    const taken = /* @__PURE__ */ new Set();
+    for (const spec of opts.roots) {
+      const id = resolveRootId(spec, taken);
+      taken.add(id);
+      roots.push(await openRoot(spec, id));
+    }
+  }
+  registerApiFile(app, roots);
+  registerApiTree(app, roots, opts.paletteOverride);
+  registerApiAsset(app, roots);
+  registerApiSearch(app, roots);
+  registerSse(app, hub, { ...opts.onSseClientsChanged ? { onClientsChanged: opts.onSseClientsChanged } : {} });
+  if (opts.identity) registerHealth(app, opts.identity, roots);
   await app.register(import("@fastify/static"), {
     root: opts.clientDir,
     prefix: "/"
@@ -1225,10 +1781,13 @@ async function createServer(opts) {
     return reply.sendFile("index.html");
   });
   app.addHook("onClose", async () => {
-    await watcher.close();
-    await configWatcher.close();
+    await Promise.all([
+      ...roots.map((r) => r.watcher.close()),
+      ...[...configWatchers.values()].map((w) => w.close())
+    ]);
+    await hub.close();
   });
-  return app;
+  return { app, setRoots };
 }
 
 // src/cli.ts
@@ -1237,33 +1796,48 @@ function printUsage() {
 mdview \u2014 local markdown viewer
 
 Usage:
-  mdview [path]            View file or folder (default: cwd)
+  mdview [path]            Open a file or folder and return the shell (default: cwd)
+  mdview ls                List open folders and the background server
+  mdview rm <name|path>\u2026   Stop serving a folder
+  mdview stop              Stop the background server
   mdview config <\u2026>        Read or edit the global config (run 'mdview config -h')
 
+One background server serves every folder you open, so 'mdview .' in a second
+repo adds it alongside the first instead of starting a rival server.
+
 Options:
-  --port <n>               Port to listen on (default: 7331; auto-fallback)
+  --foreground, -f         Run a server in this terminal instead (Ctrl-C to stop)
   --no-open                Don't auto-launch the browser
-  --palette <name>         Override the palette for this run (one of: ${PALETTES.join(", ")})
+  --port <n>               Port to listen on; implies --foreground
+  --palette <name>         Palette for this run; implies --foreground (one of: ${PALETTES.join(", ")})
   --version, -v            Print version and exit
   --help, -h               Show this help
 
+Environment:
+  PORT                     Port for the background server (default: 7331)
+  MDVIEW_IDLE_TIMEOUT      Minutes with no open tab after which the background
+                           server exits (default: off \u2014 use 'mdview stop')
+  MDVIEW_DEBUG=1           Print full stack traces on unexpected errors
+
 Examples:
-  mdview ./docs                          Browse a folder
+  mdview ./docs                          Browse a folder, shell stays free
   mdview README.md                       View a single file
-  mdview --port 9000                     Use a specific port
+  mdview ls                              What's open, and where
+  mdview --foreground ./docs             Keep it in this terminal
+  mdview --port 9000 ./docs              One-off server on a specific port
   mdview config ignore add deps _site    Hide extra build dirs globally
   mdview config path                     Print global config path
 `.trim());
 }
 function readVersion() {
-  const here = path11.dirname(fileURLToPath(import.meta.url));
+  const here = path14.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path11.resolve(here, "../package.json"),
-    path11.resolve(here, "../../package.json")
+    path14.resolve(here, "../package.json"),
+    path14.resolve(here, "../../package.json")
   ];
   for (const p of candidates) {
     try {
-      const raw = readFileSync(p, "utf8");
+      const raw = readFileSync2(p, "utf8");
       const v = JSON.parse(raw).version;
       if (typeof v === "string") return v;
     } catch {
@@ -1271,8 +1845,38 @@ function readVersion() {
   }
   return "unknown";
 }
-function parseArgs(argv) {
-  const args = { target: ".", port: 7331, portExplicit: false, open: true, embedMode: false };
+var DEFAULT_PORT = 7331;
+var FRIENDLY_HOST = "mdview.localhost";
+function isLoopbackAddress(addr) {
+  return addr === "::1" || addr.startsWith("127.");
+}
+async function resolveDisplayHost() {
+  try {
+    const addrs = await dns.lookup(FRIENDLY_HOST, { all: true });
+    if (addrs.length > 0 && addrs.every((a) => isLoopbackAddress(a.address))) {
+      return FRIENDLY_HOST;
+    }
+  } catch {
+  }
+  return "127.0.0.1";
+}
+function envPort() {
+  const raw = process.env.PORT;
+  if (!raw) return void 0;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) return void 0;
+  return n;
+}
+function parseArgs(argv, defaultPort = DEFAULT_PORT) {
+  const args = {
+    target: ".",
+    port: defaultPort,
+    portExplicit: false,
+    open: true,
+    embedMode: false,
+    foreground: false,
+    daemon: false
+  };
   let targetSet = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -1286,6 +1890,14 @@ function parseArgs(argv) {
       args.embedMode = true;
       continue;
     }
+    if (a === "-f" || a === "--foreground") {
+      args.foreground = true;
+      continue;
+    }
+    if (a === "--daemon") {
+      args.daemon = true;
+      continue;
+    }
     if (a === "--port") {
       const v = argv[++i];
       if (!v) throw new Error("--port requires a number");
@@ -1309,26 +1921,24 @@ function parseArgs(argv) {
     targetSet = true;
   }
   if (args.embedMode) args.open = false;
+  if (args.portExplicit || args.palette !== void 0 || args.embedMode) args.foreground = true;
   return { kind: "run", args };
 }
 function detectRoot(target) {
-  const abs = path11.resolve(target);
-  if (!existsSync(abs)) throw new Error(`Path does not exist: ${abs}`);
-  const st = statSync(abs);
+  const abs = path14.resolve(target);
+  if (!existsSync2(abs)) throw new Error(`Path does not exist: ${abs}`);
+  const st = statSync4(abs);
   if (st.isDirectory()) {
-    return {
-      rootAbsPath: abs,
-      rootInfo: { rootKind: "dir", rootRelPath: "", rootName: path11.basename(abs) }
-    };
+    return { absPath: abs, id: deriveRootId(abs, /* @__PURE__ */ new Set()), kind: "dir" };
   }
   if (st.isFile()) {
+    const dir = path14.dirname(abs);
     return {
-      rootAbsPath: path11.dirname(abs),
-      rootInfo: {
-        rootKind: "file",
-        rootRelPath: path11.basename(abs),
-        rootName: path11.basename(abs)
-      }
+      absPath: dir,
+      id: deriveRootId(dir, /* @__PURE__ */ new Set()),
+      name: path14.basename(abs),
+      kind: "file",
+      filePath: path14.basename(abs)
     };
   }
   throw new Error(`Unsupported path type: ${abs}`);
@@ -1377,48 +1987,41 @@ Find the process with: ${portFinderHint(port)}`
   }
   throw new Error("Could not bind a port (tried 10 in a row).");
 }
-async function main() {
-  const argv = process.argv.slice(2);
-  if (argv[0] === "config") {
-    const code = await runConfigSubcommand(argv.slice(1));
-    process.exit(code);
-  }
-  let parsed;
-  try {
-    parsed = parseArgs(argv);
-  } catch (err) {
-    console.error(err.message);
-    printUsage();
-    process.exit(2);
-  }
-  if (parsed.kind === "help") {
-    printUsage();
-    process.exit(0);
-  }
-  if (parsed.kind === "version") {
-    console.log(readVersion());
-    process.exit(0);
-  }
-  const args = parsed.args;
-  const { rootAbsPath, rootInfo } = detectRoot(args.target);
-  const here = path11.dirname(fileURLToPath(import.meta.url));
-  const clientDirCandidates = [
-    path11.resolve(here, "../dist/client"),
-    path11.resolve(here, "../../dist/client")
+function requireClientDir() {
+  const here = path14.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path14.resolve(here, "../dist/client"),
+    path14.resolve(here, "../../dist/client")
   ];
-  const clientDir = clientDirCandidates.find(existsSync);
-  if (!clientDir) {
-    console.error("Client bundle not found. Run `npm run build:client` first.");
-    process.exit(1);
-  }
-  const app = await createServer({ rootAbsPath, rootInfo, clientDir, paletteOverride: args.palette, embedMode: args.embedMode });
+  const dir = candidates.find(existsSync2);
+  if (!dir) throw new Error("Client bundle not found. Run `npm run build:client` first.");
+  return dir;
+}
+function idleTimeoutMs() {
+  const raw = process.env.MDVIEW_IDLE_TIMEOUT;
+  if (raw === void 0) return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.round(n * 6e4);
+}
+async function runForeground(args) {
+  const root = detectRoot(args.target);
+  const clientDir = requireClientDir();
+  const { app } = await createServer({
+    roots: [root],
+    clientDir,
+    ...args.palette === void 0 ? {} : { paletteOverride: args.palette },
+    embedMode: args.embedMode
+  });
   const boundPort = await listen(app, args.port, args.portExplicit);
-  const url = rootInfo.rootKind === "file" ? `http://127.0.0.1:${boundPort}/?file=${encodeURIComponent(rootInfo.rootRelPath)}` : `http://127.0.0.1:${boundPort}/`;
+  const host = args.embedMode ? "127.0.0.1" : await resolveDisplayHost();
+  const url = root.kind === "file" ? `http://${host}:${boundPort}/?file=${encodeURIComponent(`${root.id}/${root.filePath}`)}` : `http://${host}:${boundPort}/`;
   if (args.embedMode) {
-    process.stdout.write(JSON.stringify({ event: "ready", url, port: boundPort }) + "\n");
+    process.stdout.write(`${JSON.stringify({ event: "ready", url, port: boundPort })}
+`);
   } else {
     console.log(`mdview \u2192 ${url}`);
-    console.log(`watching: ${rootAbsPath}`);
+    console.log(`watching: ${root.absPath}`);
   }
   if (args.open) await openBrowser(url);
   let shuttingDown = false;
@@ -1448,6 +2051,104 @@ async function main() {
     process.stdin.resume();
   }
 }
+async function runDaemon(args) {
+  const clientDir = requireClientDir();
+  const startedAt = Date.now();
+  let idleTimer;
+  const server = await createServer({
+    roots: toRootSpecs(readWorkspace()),
+    clientDir,
+    identity: { pid: process.pid, startedAt },
+    onSseClientsChanged: (count) => {
+      if (count > 0) {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = void 0;
+      } else {
+        armIdle();
+      }
+    }
+  });
+  const boundPort = await listen(server.app, args.port, args.portExplicit);
+  writeDaemonState({ pid: process.pid, port: boundPort, startedAt });
+  console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] mdview daemon pid ${process.pid} on port ${boundPort}`);
+  const wsWatcher = chokidar3.watch(workspaceFilePath(), {
+    ignoreInitial: true,
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 60, pollInterval: 30 }
+  });
+  const reload = () => {
+    void server.setRoots(toRootSpecs(readWorkspace())).catch((err) => {
+      console.error(`[mdview] failed to apply workspace change: ${String(err)}`);
+    });
+  };
+  wsWatcher.on("add", reload);
+  wsWatcher.on("change", reload);
+  wsWatcher.on("unlink", reload);
+  let shuttingDown = false;
+  const shutdown = async (why) => {
+    if (shuttingDown) process.exit(130);
+    shuttingDown = true;
+    console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] mdview daemon stopping (${why})`);
+    clearDaemonState();
+    const timeout = new Promise((resolve) => setTimeout(resolve, 1500));
+    await Promise.race([
+      Promise.all([server.app.close().catch(() => void 0), wsWatcher.close()]).then(
+        () => void 0
+      ),
+      timeout
+    ]);
+    process.exit(0);
+  };
+  function armIdle() {
+    const ms = idleTimeoutMs();
+    if (ms <= 0) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => void shutdown("idle"), ms);
+  }
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  if (process.platform !== "win32") process.on("SIGHUP", () => void shutdown("SIGHUP"));
+  armIdle();
+}
+async function runAttach(args) {
+  const added = addRoot(args.target);
+  const state = await ensureDaemon(fileURLToPath(import.meta.url));
+  await waitForRoot(state.port, added.root.id);
+  const host = await resolveDisplayHost();
+  const base = `http://${host}:${state.port}/`;
+  const url = added.filePath ? `${base}?file=${encodeURIComponent(added.filePath)}` : `${base}?root=${encodeURIComponent(added.focusPath)}`;
+  console.log(`mdview \u2192 ${url}`);
+  console.log(`${added.changed ? "added" : "open"}: ${added.root.path} (${added.root.id})`);
+  if (args.open) await openBrowser(url);
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const sub = argv[0];
+  if (sub === "config") process.exit(await runConfigSubcommand(argv.slice(1)));
+  if (sub === "ls" || sub === "status") process.exit(await runListCommand());
+  if (sub === "rm") process.exit(await runRemoveCommand(argv.slice(1)));
+  if (sub === "stop") process.exit(await runStopCommand());
+  let parsed;
+  try {
+    parsed = parseArgs(argv, envPort() ?? DEFAULT_PORT);
+  } catch (err) {
+    console.error(err.message);
+    printUsage();
+    process.exit(2);
+  }
+  if (parsed.kind === "help") {
+    printUsage();
+    process.exit(0);
+  }
+  if (parsed.kind === "version") {
+    console.log(readVersion());
+    process.exit(0);
+  }
+  const args = parsed.args;
+  if (args.daemon) return runDaemon(args);
+  if (args.foreground) return runForeground(args);
+  return runAttach(args);
+}
 function formatError(err) {
   if (!(err instanceof Error)) return null;
   const errno = err;
@@ -1460,7 +2161,16 @@ function formatError(err) {
   const msg = err.message;
   if (msg.startsWith("Port ")) return { message: msg, code: 1 };
   if (msg.startsWith("Client bundle not found")) return { message: `mdview: ${msg}`, code: 1 };
-  if (msg.startsWith("Path does not exist") || msg.startsWith("Unsupported path type") || msg.startsWith("Could not bind a port") || msg.startsWith("Unexpected argument")) {
+  const EXPECTED = [
+    "Path does not exist",
+    "Unsupported path type",
+    "Could not bind a port",
+    "Unexpected argument",
+    "Workspace is full",
+    "Timed out waiting for the mdview background server",
+    "The mdview background server did not start"
+  ];
+  if (EXPECTED.some((prefix) => msg.startsWith(prefix))) {
     return { message: `mdview: ${msg}`, code: 1 };
   }
   return null;
@@ -1492,6 +2202,8 @@ if (isEntryPoint) {
   });
 }
 export {
+  DEFAULT_PORT,
+  idleTimeoutMs,
   parseArgs
 };
 //# sourceMappingURL=mdview.mjs.map