features

src-tauri/src/dto.rs

@@ -0,0 +1,185 @@
+// The IPC contract. Every type here has a matching declaration in src/ipc.ts. Both sides are
+// frozen once written: implementation modules add bodies, not fields.
+//
+// Types only. No `#[tauri::command]` lives here: the commands sit in the modules that implement
+// them and are registered in lib.rs.
+
+use serde::{Deserialize, Serialize};
+
+/// One open folder. `id` is derived from the path, so it survives a relaunch and a root can be
+/// addressed without the frontend carrying the path around.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RootInfo {
+    pub id: String,
+    pub path: String,
+    /// The folder's own name, which is what the sidebar heading shows.
+    pub name: String,
+    pub opened_ms: i64,
+}
+
+/// A node in one root's tree, including the root itself. The whole tree is read in one go, so
+/// `children` being empty means a directory is empty, never that it is unexplored.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FileNode {
+    pub path: String,
+    pub name: String,
+    /// dir | markdown | text | other
+    pub kind: String,
+    /// True for markdown and .txt, the two kinds that open in the editor. A directory is not
+    /// editable either, so the greyed row in the tree is `kind == "other"` and not `!editable`.
+    pub editable: bool,
+    pub modified_ms: i64,
+    #[serde(default)]
+    pub children: Vec<FileNode>,
+}
+
+/// `modified_ms` is the timestamp the text was read at. The frontend keeps it and hands it back
+/// on write, which is the only way it can tell its buffer apart from a file something else has
+/// touched since. Frontmatter is not split out here: the editor parses it, hides it and writes it
+/// back, so the backend only ever sees a whole document.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReadResult {
+    pub path: String,
+    pub text: String,
+    pub modified_ms: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WriteResult {
+    pub path: String,
+    pub modified_ms: i64,
+    /// The file moved on from the timestamp the caller expected and nothing was written. Not an
+    /// error: the document is still open and still unsaved, and the user has to be asked which
+    /// copy wins.
+    pub conflict: bool,
+}
+
+/// Where a pasted image landed. `rel_path` is what goes into the markdown link, relative to the
+/// document that received the paste; `path` is absolute, which is what the tree needs.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AssetResult {
+    pub path: String,
+    pub rel_path: String,
+}
+
+/// Payload of the `watch-event` event. `root` is a `RootInfo` id.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WatchEvent {
+    pub root: String,
+    pub path: String,
+    /// created | modified | removed | renamed
+    pub kind: String,
+    /// Where the file was before a rename, absent on every other kind.
+    #[serde(default)]
+    pub old_path: Option<String>,
+}
+
+/// Progress of the SQLite index, which lives in the app data directory and never in a user
+/// folder. Also the payload of the `index-progress` event.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct IndexStatus {
+    /// idle | indexing | error
+    pub phase: String,
+    pub indexed: u32,
+    pub total: u32,
+    /// Epoch milliseconds of the last completed pass.
+    pub last_indexed: Option<i64>,
+    pub error: Option<String>,
+    pub message: Option<String>,
+}
+
+impl Default for IndexStatus {
+    fn default() -> Self {
+        IndexStatus {
+            phase: "idle".to_string(),
+            indexed: 0,
+            total: 0,
+            last_indexed: None,
+            error: None,
+            message: None,
+        }
+    }
+}
+
+/// Half-open offsets into whichever string the hit says they belong to, for highlighting.
+///
+/// The unit is a UTF-16 code unit, which is what a JavaScript string is indexed in and what the
+/// `slice` that draws the highlight counts. Not bytes, and deliberately not code points either:
+/// index.rs works in code points throughout and converts once at the boundary, in `to_utf16`,
+/// because the two agree on everything in the BMP and disagree by one per emoji, which is exactly
+/// the kind of difference that is invisible until somebody puts one in a filename.
+///
+/// `SpellIssue` counts differently on purpose. Its offsets address a ProseMirror document, and
+/// ProseMirror counts code points.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MatchRange {
+    pub start: u32,
+    pub end: u32,
+}
+
+/// One quick-open result. `ranges` index into `rel_path`, which is also what the row shows, so a
+/// match on a folder name can be highlighted where it actually was.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QuickOpenHit {
+    pub path: String,
+    pub name: String,
+    pub root: String,
+    pub rel_path: String,
+    pub score: i32,
+    #[serde(default)]
+    pub ranges: Vec<MatchRange>,
+}
+
+/// One full text result. `line` is one-based and counted over the file as it sits on disk,
+/// frontmatter included, so jumping to it lands in the right place. `ranges` index into `snippet`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchHit {
+    pub path: String,
+    pub root: String,
+    pub title: String,
+    pub line: u32,
+    pub snippet: String,
+    #[serde(default)]
+    pub ranges: Vec<MatchRange>,
+}
+
+/// A document that links here, shown at the end of the document it points at. Links between
+/// documents are relative markdown links, so a backlink is a resolved `](../thing.md)` and
+/// nothing more.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Backlink {
+    pub path: String,
+    pub title: String,
+    pub snippet: String,
+}
+
+/// One misspelling in a run of text handed to the checker.
+///
+/// `start` and `end` are half-open offsets in *characters*, not bytes and not UTF-16 units,
+/// because the other end is JavaScript addressing a ProseMirror document and ProseMirror counts
+/// in code points. macspell.rs does the conversion from the UTF-16 ranges AppKit answers in, and
+/// it is the only place in the app where that conversion is allowed to happen.
+///
+/// A word with no guesses is still an issue: NSSpellChecker regularly flags a typo it has no
+/// suggestion for, and dropping it because the menu would be empty is how a checker earns a
+/// reputation for missing things.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SpellIssue {
+    pub start: usize,
+    pub end: usize,
+    pub word: String,
+    #[serde(default)]
+    pub suggestions: Vec<String>,
+}

src-tauri/src/fs.rs

@@ -0,0 +1,975 @@
+// Rust owns the filesystem and nothing above it. Every byte that reaches or leaves the disk goes
+// through this module: opening a folder, walking it, reading a document, writing one back, sending
+// a file to the Trash, dropping a pasted image beside the document that received it, and the
+// SQLite index that answers the three questions a plain tree cannot. Markdown is never parsed
+// here; that is the bridge's job in TypeScript.
+//
+// Two promises constrain nearly every function below, and both are the product's rather than the
+// implementation's. Opening a folder or a file never writes anything, so nothing here may leave a
+// dotfile, a lock, a cache or a sidecar inside a folder the user opened. And every write is
+// atomic: a temp file beside the target, flushed, then renamed over it, so a crash or a full disk
+// can never leave a half written document where the user's document used to be.
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::ffi::OsString;
+use std::fs;
+use std::io::Write;
+use std::path::{Component, Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering as Memory};
+use std::sync::{Arc, LazyLock, Mutex};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use ignore::WalkBuilder;
+use tauri::{AppHandle, State};
+use tauri_plugin_opener::OpenerExt;
+
+use crate::dto::{
+    AssetResult, Backlink, FileNode, IndexStatus, QuickOpenHit, ReadResult, RootInfo, SearchHit,
+    WriteResult,
+};
+use crate::Roots;
+
+/// Skipped whatever the folder's own gitignore says, because not one of the four is ever a
+/// document and a documents folder that happens to be a checkout should not open with its build
+/// output filling the sidebar.
+///
+/// The index walks by the same rule, so the sidebar and the search box agree about what a folder
+/// holds.
+pub(crate) const ALWAYS_SKIPPED: [&str; 4] = [".git", "node_modules", "target", "dist"];
+
+/// These two mirror `src/model/doc.ts` and have to keep agreeing with it: the frontend decides
+/// from the extension whether a row opens in the editor, and `FileNode.editable` is that same
+/// decision made here.
+const MARKDOWN_EXTENSIONS: [&str; 5] = ["md", "markdown", "mdown", "mkd", "mkdn"];
+const TEXT_EXTENSIONS: [&str; 2] = ["txt", "text"];
+
+/// Where the open folders are remembered between launches, inside the app data directory and never
+/// inside a folder the user opened.
+const ROOTS_FILE: &str = "roots.json";
+
+/// What a pasted image is called when the clipboard suggests nothing usable.
+const FALLBACK_ASSET_NAME: &str = "image.png";
+
+// Path validation. Every path below arrives as a string from the frontend, and the frontend is a
+// webview: a bug in a link resolver, a crafted document, a drag from somewhere unexpected or a
+// stale path belonging to a folder that has since been closed can all put an arbitrary string
+// here. This is the one place in the app where being wrong damages files the user never opened, so
+// the rule is deliberately blunt and every command that takes a path goes through it, reads as
+// well as writes.
+//
+// A path is accepted only when it holds no `..` component at all and, once symlinks have been
+// resolved, sits inside a folder that is currently open. Canonicalising first is what makes the
+// second half mean anything: without it both `~/notes/../../.ssh/id_rsa` and a symlink pointing at
+// /etc read as being inside the root. A path that does not exist yet is resolved against its
+// deepest existing ancestor and the remaining components are appended, so creating a file is
+// checked exactly as strictly as writing one. With no folder open nothing is inside a root, so
+// every path is rejected, which is the right default rather than an inconvenience.
+
+fn path_string(path: &Path) -> String {
+    path.to_string_lossy().into_owned()
+}
+
+fn ms_since_epoch(time: SystemTime) -> i64 {
+    time.duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+fn now_ms() -> i64 {
+    ms_since_epoch(SystemTime::now())
+}
+
+pub(crate) fn modified_ms(meta: &fs::Metadata) -> i64 {
+    meta.modified().map(ms_since_epoch).unwrap_or(0)
+}
+
+/// True for a broken symlink too, which `Path::exists` is not. A name pointing at nothing is still
+/// a name that cannot be created.
+fn taken(path: &Path) -> bool {
+    fs::symlink_metadata(path).is_ok()
+}
+
+pub(crate) fn kind_for(path: &Path, is_dir: bool) -> &'static str {
+    if is_dir {
+        return "dir";
+    }
+    let name = path
+        .file_name()
+        .map(|n| n.to_string_lossy().to_lowercase())
+        .unwrap_or_default();
+    match name.rfind('.') {
+        Some(dot) if dot > 0 => {
+            let ext = &name[dot + 1..];
+            if MARKDOWN_EXTENSIONS.contains(&ext) {
+                "markdown"
+            } else if TEXT_EXTENSIONS.contains(&ext) {
+                "text"
+            } else {
+                "other"
+            }
+        }
+        _ => "other",
+    }
+}
+
+fn node_from(path: &Path, is_dir: bool, modified: i64) -> FileNode {
+    let kind = kind_for(path, is_dir);
+    FileNode {
+        path: path_string(path),
+        name: path
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_else(|| path_string(path)),
+        kind: kind.to_string(),
+        editable: kind == "markdown" || kind == "text",
+        modified_ms: modified,
+        children: Vec::new(),
+    }
+}
+
+fn node_for(path: &Path) -> Result<FileNode, String> {
+    let meta = fs::metadata(path).map_err(|e| format!("{}: {e}", path.display()))?;
+    Ok(node_from(path, meta.is_dir(), modified_ms(&meta)))
+}
+
+/// A base name and not a path. `file_rename` cannot move anything, so a name carrying a separator
+/// is refused rather than quietly turned into a move.
+fn check_name(name: &str) -> Result<&str, String> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() || trimmed == "." || trimmed == ".." {
+        return Err(format!("not a usable name: {name}"));
+    }
+    if trimmed.contains('/') || trimmed.contains('\\') || trimmed.contains('\0') {
+        return Err(format!("a name cannot contain a path separator: {name}"));
+    }
+    Ok(trimmed)
+}
+
+fn resolve(path: &Path) -> Result<PathBuf, String> {
+    if !path.is_absolute() {
+        return Err(format!("path is not absolute: {}", path.display()));
+    }
+    if path.components().any(|c| matches!(c, Component::ParentDir)) {
+        return Err(format!("path contains a parent traversal: {}", path.display()));
+    }
+    let mut tail: Vec<OsString> = Vec::new();
+    let mut cursor = path.to_path_buf();
+    loop {
+        if let Ok(base) = fs::canonicalize(&cursor) {
+            let mut out = base;
+            for part in tail.iter().rev() {
+                out.push(part);
+            }
+            return Ok(out);
+        }
+        let name = cursor
+            .file_name()
+            .ok_or_else(|| format!("cannot resolve path: {}", path.display()))?
+            .to_os_string();
+        tail.push(name);
+        cursor = cursor
+            .parent()
+            .ok_or_else(|| format!("cannot resolve path: {}", path.display()))?
+            .to_path_buf();
+    }
+}
+
+/// The gate described above. `root_paths` are the folders the user has actually opened.
+pub fn resolve_in_roots(root_paths: &[String], raw: &str) -> Result<PathBuf, String> {
+    let resolved = resolve(Path::new(raw))?;
+    for root in root_paths {
+        let base = match fs::canonicalize(root) {
+            Ok(base) => base,
+            Err(_) => continue,
+        };
+        // Component wise, so /notes-old is not read as being inside /notes.
+        if resolved.starts_with(&base) {
+            return Ok(resolved);
+        }
+    }
+    Err(format!("path is outside every open folder: {raw}"))
+}
+
+/// The lock is taken and dropped before any filesystem call, so a slow disk never blocks a command
+/// that only wants to know which folders are open.
+fn open_root_paths(roots: &State<'_, Roots>) -> Result<Vec<String>, String> {
+    let open = roots.0.lock().map_err(|e| e.to_string())?;
+    Ok(open.iter().map(|root| root.path.clone()).collect())
+}
+
+fn checked(roots: &State<'_, Roots>, raw: &str) -> Result<PathBuf, String> {
+    resolve_in_roots(&open_root_paths(roots)?, raw)
+}
+
+/// One lock per document being written, so two saves of one file cannot interleave.
+///
+/// Keyed by the resolved path, because `/tmp/notes/a.md` and `/private/tmp/notes/a.md` are one
+/// document and two keys would be two locks and no mutual exclusion at all. An entry lives only
+/// while somebody holds it: every caller drops the locks nobody is using on the way in, so the map
+/// is the size of the writes in flight rather than of every document ever saved.
+static WRITE_LOCKS: LazyLock<Mutex<HashMap<PathBuf, Arc<Mutex<()>>>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+/// Separates one temp name from the next inside this process, as the pid and the clock separate
+/// this process from any other.
+static WRITE_SEQUENCE: AtomicU64 = AtomicU64::new(0);
+
+/// Enough tries that a name collision has to be deliberate rather than unlucky.
+const TEMP_NAME_TRIES: u32 = 64;
+
+fn write_lock_for(path: &Path) -> Arc<Mutex<()>> {
+    let key = resolve(path).unwrap_or_else(|_| path.to_path_buf());
+    let mut locks = match WRITE_LOCKS.lock() {
+        Ok(locks) => locks,
+        // The guarded value is `()`, so a writer that panicked left nothing half-built behind.
+        Err(poisoned) => poisoned.into_inner(),
+    };
+    locks.retain(|_, held| Arc::strong_count(held) > 1);
+    locks.entry(key).or_default().clone()
+}
+
+/// A name for the temp file that no other write is using and no user is plausibly holding.
+///
+/// Beside the target, because a rename is only atomic within one filesystem. Hidden, so it is not
+/// mistaken for a document by the tree, by the watcher or by the person looking at the folder.
+/// Unique per call, because a name derived from the target alone is a name two concurrent saves
+/// both own and neither can safely delete. `.tmp` last so the watcher's transient rule catches it
+/// whatever the document happens to be called.
+fn temp_path(path: &Path) -> Result<PathBuf, String> {
+    let dir = path
+        .parent()
+        .ok_or_else(|| format!("cannot write {}: no folder to write in", path.display()))?;
+    let name = path
+        .file_name()
+        .ok_or_else(|| format!("cannot write {}: no name to write to", path.display()))?
+        .to_string_lossy()
+        .into_owned();
+    let pid = std::process::id();
+    for _ in 0..TEMP_NAME_TRIES {
+        let n = WRITE_SEQUENCE.fetch_add(1, Memory::Relaxed);
+        let stamp = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        let candidate = dir.join(format!(".{name}.{pid}-{n}-{stamp:x}.tmp"));
+        // A name already on disk is somebody else's, and this call is the only thing allowed to
+        // delete the name it picks.
+        if !taken(&candidate) {
+            return Ok(candidate);
+        }
+    }
+    Err(format!("cannot find a free temp name beside {}", path.display()))
+}
+
+fn fill_temp(path: &Path, tmp: &Path, bytes: &[u8], existed: bool) -> Result<(), String> {
+    let mut options = fs::OpenOptions::new();
+    options.write(true);
+    if existed {
+        fs::copy(path, tmp).map_err(|e| e.to_string())?;
+        options.truncate(true);
+    } else {
+        options.create_new(true);
+    }
+    let mut file = options.open(tmp).map_err(|e| e.to_string())?;
+    file.write_all(bytes).map_err(|e| e.to_string())?;
+    file.sync_all().map_err(|e| e.to_string())
+}
+
+/// Writes `bytes` to `path` through a temp file beside it and a rename, which is atomic within a
+/// filesystem. At no instant does the target hold half a document: it holds every old byte or
+/// every new one, whatever happens in between, and that is what makes an autosaving editor safe
+/// against a crash or a full disk mid-write. A rename that fails has not happened, so the original
+/// is still whole and still where it was.
+///
+/// The temp file starts as a copy of the original rather than as an empty file. On macOS
+/// `fs::copy` carries permissions, ACLs and extended attributes across, and since the file the
+/// user is left with is the temp file, that copy is the only thing stopping a save from quietly
+/// dropping a Finder tag or the executable bit.
+///
+/// There is no `.bak` rotation, deliberately. This is the user's own markdown in the user's own
+/// folder, very often under version control, and the app is already holding the whole source
+/// string in memory and refusing to write when the mtime on disk has moved. A backup sibling buys
+/// none of that back, and a backup named after the target is a file the user may own themselves,
+/// which the rotation would unlink without asking and without the Trash. Nothing is deleted here
+/// but the temp file this call created.
+///
+/// Writes to one path are serialized. Two saves of one document, which is all a debounced autosave
+/// and a Cmd+S landing together are, would otherwise race between two renames and leave the
+/// document at neither name.
+pub fn atomic_write(path: &Path, bytes: &[u8]) -> Result<(), String> {
+    let lock = write_lock_for(path);
+    let _held = match lock.lock() {
+        Ok(held) => held,
+        Err(poisoned) => poisoned.into_inner(),
+    };
+    write_through_temp(path, bytes)
+}
+
+fn write_through_temp(path: &Path, bytes: &[u8]) -> Result<(), String> {
+    let tmp = temp_path(path)?;
+    let existed = taken(path);
+
+    // Both ends of the rename, before either is touched: the watcher sees the temp file appear and
+    // the document change as two unrelated events, and either one getting through is the app's own
+    // save coming back to the frontend as somebody else's edit.
+    crate::watch::note_self_write(&tmp);
+    crate::watch::note_self_write(path);
+
+    if let Err(e) = fill_temp(path, &tmp, bytes, existed) {
+        let _ = fs::remove_file(&tmp);
+        return Err(e);
+    }
+
+    // Again, because the suppression is a window that started before the copy and the fsync, and on
+    // a large document those are most of it.
+    crate::watch::note_self_write(&tmp);
+    crate::watch::note_self_write(path);
+
+    match fs::rename(&tmp, path) {
+        Ok(()) => Ok(()),
+        Err(e) => {
+            let _ = fs::remove_file(&tmp);
+            Err(e.to_string())
+        }
+    }
+}
+
+/// The untitled rule: `untitled.md`, then `untitled-2.md`, and never an overwrite. The suffix goes
+/// before the extension so the file keeps opening in the same app as the one it was named after.
+pub fn free_path(dir: &Path, name: &str) -> PathBuf {
+    let first = dir.join(name);
+    if !taken(&first) {
+        return first;
+    }
+    let as_path = Path::new(name);
+    let stem = as_path
+        .file_stem()
+        .map(|s| s.to_string_lossy().into_owned())
+        .unwrap_or_else(|| name.to_string());
+    let ext = as_path.extension().map(|e| e.to_string_lossy().into_owned());
+    let joined = |suffix: String| match &ext {
+        Some(ext) => dir.join(format!("{stem}-{suffix}.{ext}")),
+        None => dir.join(format!("{stem}-{suffix}")),
+    };
+    for n in 2..10_000u32 {
+        let candidate = joined(n.to_string());
+        if !taken(&candidate) {
+            return candidate;
+        }
+    }
+    joined(now_ms().to_string())
+}
+
+fn compare_nodes(a: &FileNode, b: &FileNode) -> Ordering {
+    let a_dir = a.kind == "dir";
+    let b_dir = b.kind == "dir";
+    b_dir
+        .cmp(&a_dir)
+        .then_with(|| a.name.to_lowercase().cmp(&b.name.to_lowercase()))
+        .then_with(|| a.name.cmp(&b.name))
+}
+
+fn assemble(
+    path: &Path,
+    nodes: &mut HashMap<PathBuf, FileNode>,
+    children: &HashMap<PathBuf, Vec<PathBuf>>,
+) -> Option<FileNode> {
+    let mut node = nodes.remove(path)?;
+    if let Some(kids) = children.get(path) {
+        let mut built: Vec<FileNode> = kids
+            .iter()
+            .filter_map(|kid| assemble(kid, nodes, children))
+            .collect();
+        built.sort_by(compare_nodes);
+        node.children = built;
+    }
+    Some(node)
+}
+
+/// One pass over a folder, returning the root node with everything under it already attached.
+///
+/// `show_ignored` turns off gitignore, the hidden file rule and the four always skipped folders in
+/// one go, for a settings toggle that lets a user see what the tree is holding back.
+pub fn scan_tree(root: &Path, show_ignored: bool) -> Result<FileNode, String> {
+    let meta = fs::metadata(root).map_err(|e| format!("{}: {e}", root.display()))?;
+    if !meta.is_dir() {
+        return Err(format!("not a folder: {}", root.display()));
+    }
+
+    let mut builder = WalkBuilder::new(root);
+    builder
+        // A symlinked folder pointing back at one of its own ancestors would otherwise walk for
+        // ever, and a documents folder is exactly where somebody keeps one.
+        .follow_links(false)
+        // A .gitignore is worth honouring whether or not the folder is a checkout: the user wrote
+        // it about these files either way.
+        .require_git(false)
+        .standard_filters(!show_ignored);
+    if !show_ignored {
+        builder.filter_entry(|entry| {
+            if entry.depth() == 0 {
+                return true;
+            }
+            if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
+                return true;
+            }
+            !ALWAYS_SKIPPED.contains(&entry.file_name().to_string_lossy().as_ref())
+        });
+    }
+
+    let mut nodes: HashMap<PathBuf, FileNode> = HashMap::new();
+    let mut children: HashMap<PathBuf, Vec<PathBuf>> = HashMap::new();
+    for entry in builder.build() {
+        // One unreadable entry is one missing row and not a failed tree. A documents folder can
+        // easily hold something the user cannot stat, and losing the whole sidebar over it would
+        // be a far worse answer than losing the row.
+        let entry = match entry {
+            Ok(entry) => entry,
+            Err(_) => continue,
+        };
+        let path = entry.path().to_path_buf();
+        let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
+        let modified = entry.metadata().map(|m| modified_ms(&m)).unwrap_or(0);
+        if entry.depth() > 0 {
+            if let Some(parent) = path.parent() {
+                children
+                    .entry(parent.to_path_buf())
+                    .or_default()
+                    .push(path.clone());
+            }
+        }
+        nodes.insert(path.clone(), node_from(&path, is_dir, modified));
+    }
+
+    assemble(root, &mut nodes, &children).ok_or_else(|| format!("cannot read {}", root.display()))
+}
+
+pub fn read_document(path: &Path) -> Result<ReadResult, String> {
+    // The mtime is taken before the read rather than after. Read the other way round and a change
+    // landing between the two would be stamped onto older text, and the next save would overwrite
+    // it believing it had seen it.
+    let meta = fs::metadata(path).map_err(|e| format!("{}: {e}", path.display()))?;
+    if meta.is_dir() {
+        return Err(format!("not a file: {}", path.display()));
+    }
+    let text = fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display()))?;
+    Ok(ReadResult {
+        path: path_string(path),
+        text,
+        modified_ms: modified_ms(&meta),
+    })
+}
+
+pub fn write_document(
+    path: &Path,
+    text: &str,
+    expected_modified_ms: Option<i64>,
+) -> Result<WriteResult, String> {
+    // A file that is gone falls through to the write. Recreating a document somebody deleted under
+    // the user is not clobbering a change, and refusing would strand the buffer with nowhere to go.
+    if let (Some(expected), Ok(meta)) = (expected_modified_ms, fs::metadata(path)) {
+        let current = modified_ms(&meta);
+        if current != expected {
+            return Ok(WriteResult {
+                path: path_string(path),
+                modified_ms: current,
+                conflict: true,
+            });
+        }
+    }
+    atomic_write(path, text.as_bytes())?;
+    let meta = fs::metadata(path).map_err(|e| format!("{}: {e}", path.display()))?;
+    Ok(WriteResult {
+        path: path_string(path),
+        modified_ms: modified_ms(&meta),
+        conflict: false,
+    })
+}
+
+pub fn create_file(parent: &Path, name: &str) -> Result<FileNode, String> {
+    let name = check_name(name)?;
+    if !parent.is_dir() {
+        return Err(format!("not a folder: {}", parent.display()));
+    }
+    let target = free_path(parent, name);
+    // create_new rather than a check and then a create: the whole point of the untitled rule is
+    // that nothing is ever overwritten, and another process can take the name between the two.
+    fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&target)
+        .map_err(|e| format!("{}: {e}", target.display()))?;
+    node_for(&target)
+}
+
+pub fn create_folder(parent: &Path, name: &str) -> Result<FileNode, String> {
+    let name = check_name(name)?;
+    if !parent.is_dir() {
+        return Err(format!("not a folder: {}", parent.display()));
+    }
+    let target = free_path(parent, name);
+    fs::create_dir(&target).map_err(|e| format!("{}: {e}", target.display()))?;
+    node_for(&target)
+}
+
+pub fn rename_entry(path: &Path, name: &str) -> Result<FileNode, String> {
+    let name = check_name(name)?;
+    let parent = path
+        .parent()
+        .ok_or_else(|| format!("cannot rename {}", path.display()))?;
+    let target = parent.join(name);
+    if target == path {
+        return node_for(path);
+    }
+    // On a case insensitive volume a case only rename finds the file being renamed already sitting
+    // at the target, which is not a collision.
+    if taken(&target) && fs::canonicalize(&target).ok() != fs::canonicalize(path).ok() {
+        return Err(format!("already exists: {}", target.display()));
+    }
+    fs::rename(path, &target).map_err(|e| format!("{}: {e}", target.display()))?;
+    node_for(&target)
+}
+
+pub fn move_entry(path: &Path, dest_dir: &Path) -> Result<FileNode, String> {
+    if !dest_dir.is_dir() {
+        return Err(format!("not a folder: {}", dest_dir.display()));
+    }
+    if dest_dir.starts_with(path) {
+        return Err(format!("cannot move {} inside itself", path.display()));
+    }
+    if path.parent() == Some(dest_dir) {
+        // Already there. Going on would hand it a free name and leave two of it.
+        return node_for(path);
+    }
+    let name = path
+        .file_name()
+        .ok_or_else(|| format!("cannot move {}", path.display()))?
+        .to_string_lossy()
+        .into_owned();
+    let target = free_path(dest_dir, &name);
+    if fs::rename(path, &target).is_ok() {
+        return node_for(&target);
+    }
+    // A rename cannot cross a volume, so the move becomes a copy and a trip to the Trash. Never a
+    // remove: if anything about this went wrong the original is still recoverable in Finder.
+    copy_tree(path, &target)?;
+    trash_entry(path)?;
+    node_for(&target)
+}
+
+fn copy_tree(src: &Path, dest: &Path) -> Result<(), String> {
+    let meta = fs::symlink_metadata(src).map_err(|e| format!("{}: {e}", src.display()))?;
+    if !meta.is_dir() {
+        return fs::copy(src, dest)
+            .map(|_| ())
+            .map_err(|e| format!("{}: {e}", dest.display()));
+    }
+    fs::create_dir(dest).map_err(|e| format!("{}: {e}", dest.display()))?;
+    for entry in fs::read_dir(src).map_err(|e| format!("{}: {e}", src.display()))? {
+        let entry = entry.map_err(|e| format!("{}: {e}", src.display()))?;
+        copy_tree(&entry.path(), &dest.join(entry.file_name()))?;
+    }
+    Ok(())
+}
+
+pub fn duplicate_entry(path: &Path) -> Result<FileNode, String> {
+    let parent = path
+        .parent()
+        .ok_or_else(|| format!("cannot duplicate {}", path.display()))?;
+    let name = path
+        .file_name()
+        .ok_or_else(|| format!("cannot duplicate {}", path.display()))?
+        .to_string_lossy()
+        .into_owned();
+    let target = free_path(parent, &name);
+    copy_tree(path, &target)?;
+    node_for(&target)
+}
+
+/// Never `fs::remove_file`. These are the user's own documents and this app does not get to be the
+/// reason one of them is gone for good.
+pub fn trash_entry(path: &Path) -> Result<(), String> {
+    trash::delete(path).map_err(|e| format!("{}: {e}", path.display()))
+}
+
+pub fn write_asset(doc_path: &Path, bytes: &[u8], name: &str) -> Result<AssetResult, String> {
+    let dir = doc_path
+        .parent()
+        .ok_or_else(|| format!("cannot place an image beside {}", doc_path.display()))?;
+    // The clipboard suggests the name, so it is a suggestion and not a path: only the last
+    // component of it is ever used.
+    let suggested = Path::new(name)
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .filter(|n| check_name(n).is_ok())
+        .unwrap_or_else(|| FALLBACK_ASSET_NAME.to_string());
+
+    let assets = dir.join("assets");
+    if taken(&assets) {
+        if !assets.is_dir() {
+            return Err(format!("not a folder: {}", assets.display()));
+        }
+    } else {
+        fs::create_dir_all(&assets).map_err(|e| format!("{}: {e}", assets.display()))?;
+    }
+
+    let target = free_path(&assets, &suggested);
+    atomic_write(&target, bytes)?;
+    let file = target
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or(suggested);
+    Ok(AssetResult {
+        path: path_string(&target),
+        rel_path: format!("assets/{file}"),
+    })
+}
+
+/// A root id is a hash of the path and of nothing else, so the same folder is the same root after
+/// a relaunch and the frontend can address one without carrying its path around. FNV-1a rather
+/// than the standard hasher, whose output is only promised to be stable within one build.
+pub fn root_id_for(path: &str) -> String {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for byte in path.as_bytes() {
+        hash ^= *byte as u64;
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    format!("{hash:016x}")
+}
+
+fn roots_file(app: &AppHandle) -> Result<PathBuf, String> {
+    Ok(crate::library::app_data_dir(app)?.join(ROOTS_FILE))
+}
+
+fn load_roots(app: &AppHandle) -> Vec<RootInfo> {
+    let Ok(file) = roots_file(app) else {
+        return Vec::new();
+    };
+    let Ok(text) = fs::read_to_string(file) else {
+        return Vec::new();
+    };
+    serde_json::from_str(&text).unwrap_or_default()
+}
+
+fn save_roots(app: &AppHandle, roots: &[RootInfo]) -> Result<(), String> {
+    let file = roots_file(app)?;
+    let text = serde_json::to_string_pretty(roots).map_err(|e| e.to_string())?;
+    atomic_write(&file, text.as_bytes())
+}
+
+/// Every folder currently open, in the order they were opened, which is the order the sidebar
+/// lists them in.
+///
+/// The list outlives a relaunch, so the first call after launch reads it back from the app data
+/// directory and fills the managed state from it. A root whose folder has since been deleted,
+/// renamed or unmounted is dropped rather than handed back as a row that cannot be expanded.
+#[tauri::command]
+pub fn roots_list(app: AppHandle, roots: State<'_, Roots>) -> Result<Vec<RootInfo>, String> {
+    let mut open = roots.0.lock().map_err(|e| e.to_string())?;
+    if open.is_empty() {
+        *open = load_roots(&app);
+    }
+    let before = open.len();
+    open.retain(|root| Path::new(&root.path).is_dir());
+    if open.len() != before {
+        save_roots(&app, &open)?;
+    }
+    Ok(open.clone())
+}
+
+/// Adds `path` to the open roots and returns it. Idempotent: opening a folder that is already open
+/// returns the entry that is already there rather than a second copy of it.
+///
+/// `id` is derived from the path and from nothing else, so the same folder is the same root across
+/// relaunches and the frontend can address a root without carrying its path around. Opening a
+/// folder never writes anything into it, and that includes not creating it: a `path` that is not
+/// an existing directory is an error, not a mkdir.
+#[tauri::command]
+pub fn root_open(app: AppHandle, roots: State<'_, Roots>, path: String) -> Result<RootInfo, String> {
+    let canonical = fs::canonicalize(&path).map_err(|e| format!("{path}: {e}"))?;
+    if !canonical.is_dir() {
+        return Err(format!("not a folder: {}", canonical.display()));
+    }
+    let path = path_string(&canonical);
+    let id = root_id_for(&path);
+
+    let mut open = roots.0.lock().map_err(|e| e.to_string())?;
+    if open.is_empty() {
+        *open = load_roots(&app);
+    }
+    if let Some(existing) = open.iter().find(|root| root.id == id) {
+        return Ok(existing.clone());
+    }
+    let info = RootInfo {
+        id,
+        name: canonical
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_else(|| path.clone()),
+        path,
+        opened_ms: now_ms(),
+    };
+    open.push(info.clone());
+    save_roots(&app, &open)?;
+    // The lock goes before the index hears about the folder: the indexer's first move is to ask
+    // `Roots` where that root is, and it should not have to wait for this command to return.
+    drop(open);
+    // Scanned now rather than at the next rebuild, or a folder just opened would answer nothing at
+    // all to a search until something else asked for a full pass.
+    crate::index::scan_root(&app, info.clone());
+    Ok(info)
+}
+
+/// Forgets a root and persists the shorter list. Touches nothing inside the folder itself.
+///
+/// Stopping the watcher is not done here. The frontend calls `watch_stop` for the same root, which
+/// keeps this module from having to know that the watcher exists.
+#[tauri::command]
+pub fn root_close(app: AppHandle, roots: State<'_, Roots>, root_id: String) -> Result<(), String> {
+    let mut open = roots.0.lock().map_err(|e| e.to_string())?;
+    let before = open.len();
+    open.retain(|root| root.id != root_id);
+    if open.len() == before {
+        return Ok(());
+    }
+    save_roots(&app, &open)?;
+    drop(open);
+    // The rows go with the folder. Nothing can be opened from a search result that belongs to a
+    // folder that is no longer there to open it in.
+    crate::index::forget_root(&app, &root_id);
+    Ok(())
+}
+
+/// The whole tree for one root in a single pass, the root node itself included. Empty `children`
+/// therefore means an empty directory, never one that has not been explored yet.
+///
+/// Gitignore aware through the `ignore` crate, and `.git` itself is skipped too: a documents folder
+/// under version control should not surface its own ignored build output as if it were documents.
+/// Everything else is returned, including files the editor cannot open, because the tree greys
+/// those rows out rather than hiding them. Children come back sorted directories first and then by
+/// name, case insensitively, so the tree does not reshuffle itself between two reads of an
+/// unchanged folder.
+#[tauri::command(async)]
+pub fn tree_read(roots: State<'_, Roots>, root_id: String) -> Result<FileNode, String> {
+    let path = roots.path_for(&root_id)?;
+    scan_tree(Path::new(&path), false)
+}
+
+/// Opens Finder with the file selected, rather than opening the file.
+#[tauri::command]
+pub fn reveal_in_finder(
+    app: AppHandle,
+    roots: State<'_, Roots>,
+    path: String,
+) -> Result<(), String> {
+    let path = checked(&roots, &path)?;
+    app.opener()
+        .reveal_item_in_dir(&path)
+        .map_err(|e| format!("{}: {e}", path.display()))
+}
+
+/// Hands a file to whatever macOS opens it with. This is the only way a non editable file in the
+/// tree can be opened at all, so it has to work for anything, not just for documents.
+#[tauri::command]
+pub fn open_external(app: AppHandle, roots: State<'_, Roots>, path: String) -> Result<(), String> {
+    let path = checked(&roots, &path)?;
+    app.opener()
+        .open_path(path_string(&path), None::<&str>)
+        .map_err(|e| format!("{}: {e}", path.display()))
+}
+
+/// Reads a document as UTF-8, and reads nothing else: no metadata is written, no lock is taken and
+/// no sidecar appears beside it.
+///
+/// `modified_ms` is the file's mtime as it was at the moment of the read. The caller keeps it and
+/// hands it back on write, which is the only thing that can tell an unsaved buffer apart from a
+/// file another program has touched since. A file that is not valid UTF-8 is an error rather than
+/// a lossy conversion, because a lossy read followed by a save would corrupt the user's file.
+#[tauri::command(async)]
+pub fn file_read(roots: State<'_, Roots>, path: String) -> Result<ReadResult, String> {
+    read_document(&checked(&roots, &path)?)
+}
+
+/// Writes a document atomically: a temp file in the same directory, flushed and synced, then
+/// renamed over the target. The old bytes survive a crash, a full disk and a power cut mid-write.
+///
+/// `expected_modified_ms` is the mtime the caller last saw. If the file has moved on from it,
+/// nothing is written and the result carries `conflict`, which is not an error: the document is
+/// still open, still unsaved, and the user is the one who decides which copy wins. `None` means
+/// write regardless, which is what a first save of a new file does.
+///
+/// Permissions, ownership and any extended attributes of the original survive the rename, since
+/// the file the user ends up with is the temp file and it must not arrive with different bits.
+///
+/// The index is told directly rather than through the watcher. `watch::note_self_write` drops the
+/// app's own writes out of the watch stream so an autosave does not come back as somebody else's
+/// edit, which means the one document the watcher never reports is the one the user is working in.
+/// Without this line the only version of it the index would ever hold is the one from before they
+/// started typing.
+#[tauri::command(async)]
+pub fn file_write(
+    app: AppHandle,
+    roots: State<'_, Roots>,
+    path: String,
+    text: String,
+    expected_modified_ms: Option<i64>,
+) -> Result<WriteResult, String> {
+    let path = checked(&roots, &path)?;
+    let result = write_document(&path, &text, expected_modified_ms)?;
+    // A conflict wrote nothing, and whatever moved the file on is an outside change the watcher
+    // does report.
+    if !result.conflict {
+        crate::index::note_write(&app, &path);
+    }
+    Ok(result)
+}
+
+/// Creates an empty file inside `parent_path`. `name` is a suggestion: a name already taken gets a
+/// suffix, and the node that comes back carries the name that was really used, so the caller never
+/// has to guess at it or race another process for it.
+#[tauri::command]
+pub fn file_create(
+    roots: State<'_, Roots>,
+    parent_path: String,
+    name: String,
+) -> Result<FileNode, String> {
+    create_file(&checked(&roots, &parent_path)?, &name)
+}
+
+/// Creates an empty directory inside `parent_path`, under the same suggested-name rule as
+/// `file_create`.
+#[tauri::command]
+pub fn file_folder_create(
+    roots: State<'_, Roots>,
+    parent_path: String,
+    name: String,
+) -> Result<FileNode, String> {
+    create_folder(&checked(&roots, &parent_path)?, &name)
+}
+
+/// Renames a file or folder where it stands. `name` is a base name and not a path: a `name` holding
+/// a path separator is an error, because this command cannot move anything and quietly doing so
+/// would be worse than refusing.
+///
+/// This is the only thing that changes a document's identity, and it happens because the user asked
+/// for it. Nothing in this app renames a file on its own, least of all because a heading changed.
+#[tauri::command]
+pub fn file_rename(
+    roots: State<'_, Roots>,
+    path: String,
+    name: String,
+) -> Result<FileNode, String> {
+    rename_entry(&checked(&roots, &path)?, &name)
+}
+
+/// Moves a file or folder into `dest_dir`, keeping its name unless that name is taken there.
+///
+/// This command moves bytes and nothing else. The relative links a move breaks are rewritten a
+/// layer up, in src/linkRewrite.ts, which splices one destination at a time into the file's own
+/// text and never hands a document to the serializer, so a file whose links did not move is not
+/// written at all.
+#[tauri::command]
+pub fn file_move(
+    roots: State<'_, Roots>,
+    path: String,
+    dest_dir: String,
+) -> Result<FileNode, String> {
+    let open = open_root_paths(&roots)?;
+    let path = resolve_in_roots(&open, &path)?;
+    let dest_dir = resolve_in_roots(&open, &dest_dir)?;
+    move_entry(&path, &dest_dir)
+}
+
+/// Copies a file, or a folder and everything under it, beside itself under a free name. The copy is
+/// byte for byte: nothing is parsed, normalised or reformatted on the way through.
+#[tauri::command(async)]
+pub fn file_duplicate(roots: State<'_, Roots>, path: String) -> Result<FileNode, String> {
+    duplicate_entry(&checked(&roots, &path)?)
+}
+
+/// Sends a file or folder to the system Trash through the `trash` crate, never `remove_file`. These
+/// are the user's own documents and this app does not get to be the reason one of them is gone for
+/// good, so a delete is always something Finder can undo.
+#[tauri::command(async)]
+pub fn file_trash(roots: State<'_, Roots>, path: String) -> Result<(), String> {
+    trash_entry(&checked(&roots, &path)?)
+}
+
+/// Writes a pasted image into an `assets/` folder beside the document that received the paste,
+/// creating that folder when it is not already there. Images are the only thing other than markdown
+/// this app ever puts inside a user's folder.
+///
+/// `name` is what the clipboard suggested, which is usually `image.png` and usually already taken,
+/// so a taken name gets a suffix. `rel_path` in the result is what goes into the markdown link,
+/// relative to the document, so the folder stays movable and shareable as a whole.
+#[tauri::command(async)]
+pub fn asset_write(
+    roots: State<'_, Roots>,
+    doc_path: String,
+    bytes: Vec<u8>,
+    name: String,
+) -> Result<AssetResult, String> {
+    write_asset(&checked(&roots, &doc_path)?, &bytes, &name)
+}
+
+// The SQLite index, which lives in the app data directory and never inside a folder the user
+// opened. It is derived state rather than a source of truth: every row is rebuilt from the files on
+// disk, so deleting the database costs nothing but the time to walk the open roots again. It is
+// kept current from the same debounced batch the watcher already sends the frontend, plus one call
+// in `file_write` for the app's own saves, which are the changes that batch deliberately never
+// mentions.
+//
+// Everything below is a handful of lines because the index itself is a module of its own: these are
+// the commands, and index.rs is the database.
+
+/// Rescans every open root from scratch and returns the status the pass started with. Progress
+/// arrives on the `index-progress` event, because a full rescan of a large folder outlives any one
+/// command.
+#[tauri::command(async)]
+pub fn index_rebuild(app: AppHandle, roots: State<'_, Roots>) -> Result<IndexStatus, String> {
+    // The roots are read here rather than on the indexer's thread, so the pass covers the folders
+    // that were open when the user asked for it and not whatever the list has become since.
+    let open = roots.0.lock().map_err(|e| e.to_string())?.clone();
+    crate::index::rebuild(&app, open)
+}
+
+/// Where the index has got to, for the status line. Cheap enough to poll and safe to call before
+/// any indexing has ever run.
+#[tauri::command]
+pub fn index_status(app: AppHandle) -> Result<IndexStatus, String> {
+    crate::index::status(&app)
+}
+
+/// Fuzzy match over paths relative to their root, across every open root, best score first.
+///
+/// `ranges` index into `rel_path`, which is also the string the row shows, so a match on a folder
+/// name is highlighted where it really was. They are character offsets and not byte offsets,
+/// because the other end is JavaScript and highlights by character.
+#[tauri::command(async)]
+pub fn search_quick_open(
+    app: AppHandle,
+    query: String,
+    limit: u32,
+) -> Result<Vec<QuickOpenHit>, String> {
+    crate::index::quick_open(&app, &query, limit)
+}
+
+/// Full text search across every open root through FTS5.
+///
+/// `line` is one based and counted over the file as it sits on disk, frontmatter included, so
+/// jumping to a hit lands on the line the user can see in any other editor. `ranges` index into
+/// `snippet`, again by character.
+#[tauri::command(async)]
+pub fn search_text(app: AppHandle, query: String, limit: u32) -> Result<Vec<SearchHit>, String> {
+    crate::index::search(&app, &query, limit)
+}
+
+/// Every document holding a relative markdown link that resolves to `path`.
+///
+/// This is a reverse lookup over links that are already in the files. Nothing is written anywhere
+/// to make a backlink exist, and a document with no incoming links simply has none.
+#[tauri::command(async)]
+pub fn backlinks_for(app: AppHandle, path: String) -> Result<Vec<Backlink>, String> {
+    crate::index::backlinks(&app, &path)
+}

src-tauri/src/lib.rs

@@ -0,0 +1,258 @@
+pub mod dto;
+pub mod fs;
+pub mod index;
+mod library;
+#[cfg(target_os = "macos")]
+mod macspell;
+pub mod spell;
+pub mod watch;
+
+use std::sync::Mutex;
+
+use crate::dto::RootInfo;
+
+#[cfg(desktop)]
+use tauri::menu::{Menu, MenuItemBuilder, MenuItemKind, PredefinedMenuItem, SubmenuBuilder};
+#[cfg(desktop)]
+use tauri::{Emitter, Runtime};
+
+/// The open folders, in the order they were opened.
+///
+/// This lives here rather than in either module because both need it and neither owns the other:
+/// `fs` puts roots in and takes them out, `watch` only ever turns an id back into a path. It is the
+/// in-memory copy of the list; persisting it across a relaunch is `fs`'s business.
+#[derive(Default)]
+pub struct Roots(pub Mutex<Vec<RootInfo>>);
+
+impl Roots {
+    /// The absolute path of an open root. Every command that takes a `rootId` needs this before it
+    /// can touch anything, and an id that is not open is an error rather than an empty result.
+    pub fn path_for(&self, id: &str) -> Result<String, String> {
+        let roots = self.0.lock().map_err(|e| e.to_string())?;
+        roots
+            .iter()
+            .find(|root| root.id == id)
+            .map(|root| root.path.clone())
+            .ok_or_else(|| format!("no such root: {id}"))
+    }
+}
+
+#[cfg(desktop)]
+fn build_menu<R: Runtime>(handle: &tauri::AppHandle<R>) -> tauri::Result<Menu<R>> {
+    let menu = Menu::default(handle)?;
+
+    let open_folder = MenuItemBuilder::with_id("open-folder", "Open Folder…")
+        .accelerator("CmdOrCtrl+O")
+        .build(handle)?;
+    let new_doc = MenuItemBuilder::with_id("new-doc", "New Document")
+        .accelerator("CmdOrCtrl+N")
+        .build(handle)?;
+    let new_folder = MenuItemBuilder::with_id("new-folder", "New Folder").build(handle)?;
+    let quick_open = MenuItemBuilder::with_id("quick-open", "Quick Open…")
+        .accelerator("CmdOrCtrl+P")
+        .build(handle)?;
+    let command_palette = MenuItemBuilder::with_id("command-palette", "Command Palette…")
+        .accelerator("CmdOrCtrl+K")
+        .build(handle)?;
+    let save = MenuItemBuilder::with_id("save", "Save")
+        .accelerator("CmdOrCtrl+S")
+        .build(handle)?;
+    let close_folder = MenuItemBuilder::with_id("close-folder", "Close Folder").build(handle)?;
+    let check_updates =
+        MenuItemBuilder::with_id("check-updates", "Check for Updates…").build(handle)?;
+    let settings = MenuItemBuilder::with_id("settings", "Settings…")
+        .accelerator("CmdOrCtrl+,")
+        .build(handle)?;
+    let find = MenuItemBuilder::with_id("find", "Find…")
+        .accelerator("CmdOrCtrl+F")
+        .build(handle)?;
+    let find_in_files = MenuItemBuilder::with_id("find-in-files", "Find in Files…")
+        .accelerator("CmdOrCtrl+Shift+F")
+        .build(handle)?;
+    let report_issue =
+        MenuItemBuilder::with_id("report-issue", "Report an Issue…").build(handle)?;
+
+    let submenus: Vec<_> = menu
+        .items()?
+        .into_iter()
+        .filter_map(|item| match item {
+            MenuItemKind::Submenu(submenu) => Some(submenu),
+            _ => None,
+        })
+        .collect();
+
+    let find_submenu = |name: &str| {
+        submenus
+            .iter()
+            .find(|submenu| submenu.text().map(|t| t == name).unwrap_or(false))
+            .cloned()
+    };
+
+    match find_submenu("File") {
+        Some(submenu) => {
+            submenu.prepend_items(&[
+                &open_folder,
+                &new_doc,
+                &new_folder,
+                &PredefinedMenuItem::separator(handle)?,
+                &quick_open,
+                &command_palette,
+                &PredefinedMenuItem::separator(handle)?,
+                &save,
+                &PredefinedMenuItem::separator(handle)?,
+                &close_folder,
+                &PredefinedMenuItem::separator(handle)?,
+            ])?;
+        }
+        None => {
+            let submenu = SubmenuBuilder::new(handle, "File")
+                .item(&open_folder)
+                .item(&new_doc)
+                .item(&new_folder)
+                .item(&PredefinedMenuItem::separator(handle)?)
+                .item(&quick_open)
+                .item(&command_palette)
+                .item(&PredefinedMenuItem::separator(handle)?)
+                .item(&save)
+                .item(&PredefinedMenuItem::separator(handle)?)
+                .item(&close_folder)
+                .build()?;
+            menu.insert(&submenu, 1)?;
+        }
+    }
+
+    if let Some(edit) = find_submenu("Edit") {
+        edit.append_items(&[
+            &PredefinedMenuItem::separator(handle)?,
+            &find,
+            &find_in_files,
+        ])?;
+    }
+
+    if let Some(help) = find_submenu("Help") {
+        help.append_items(&[&report_issue])?;
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(app_submenu) = submenus.first() {
+            app_submenu.insert(&check_updates, 1)?;
+            app_submenu.insert(&settings, 3)?;
+            app_submenu.insert(&PredefinedMenuItem::separator(handle)?, 4)?;
+        }
+        if let Some(view) = find_submenu("View") {
+            let toggle_sidebar = MenuItemBuilder::with_id("toggle-sidebar", "Toggle Sidebar")
+                .accelerator("CmdOrCtrl+\\")
+                .build(handle)?;
+            view.prepend_items(&[&toggle_sidebar, &PredefinedMenuItem::separator(handle)?])?;
+        }
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        if let Some(file) = find_submenu("File") {
+            file.append_items(&[&PredefinedMenuItem::separator(handle)?, &check_updates])?;
+        }
+        if let Some(edit) = find_submenu("Edit") {
+            edit.append_items(&[&settings])?;
+        }
+    }
+
+    Ok(menu)
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    let context = tauri::generate_context!();
+
+    #[cfg_attr(mobile, allow(unused_mut))]
+    let mut builder = tauri::Builder::default()
+        .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_dialog::init())
+        .manage(Roots::default())
+        .manage(watch::Watchers::default())
+        .manage(index::Index::default());
+
+    #[cfg(desktop)]
+    {
+        builder = builder.plugin(tauri_plugin_process::init());
+        if context.config().plugins.0.contains_key("updater") {
+            builder = builder.plugin(tauri_plugin_updater::Builder::new().build());
+        }
+    }
+
+    builder = builder.setup(|app| {
+        if let Err(e) = library::app_data_dir(app.handle()) {
+            eprintln!("failed to prepare app data dir: {e}");
+        }
+        // The index is opened here rather than lazily on the first search, because opening it is
+        // where a schema migration runs and a migration that fails should say so at launch rather
+        // than the first time somebody presses Cmd+P. A failure is not fatal: the app is a text
+        // editor with a broken search box, which is worth far more than a window that will not
+        // open.
+        if let Err(e) = index::open(app.handle()) {
+            eprintln!("failed to open the search index: {e}");
+        }
+        Ok(())
+    });
+
+    #[cfg(desktop)]
+    {
+        builder = builder
+            .menu(|handle| build_menu(handle))
+            .on_menu_event(|app, event| {
+                if matches!(
+                    event.id().0.as_str(),
+                    "open-folder"
+                        | "new-doc"
+                        | "new-folder"
+                        | "save"
+                        | "close-folder"
+                        | "settings"
+                        | "find"
+                        | "find-in-files"
+                        | "quick-open"
+                        | "command-palette"
+                        | "toggle-sidebar"
+                        | "check-updates"
+                        | "report-issue"
+                ) {
+                    app.emit("menu-action", event.id().0.as_str()).ok();
+                }
+            });
+    }
+
+    // The whole command surface, in the order dto.rs describes it. Registering a command is this
+    // file's job alone: a module adds a body, never a line here.
+    builder
+        .invoke_handler(tauri::generate_handler![
+            fs::roots_list,
+            fs::root_open,
+            fs::root_close,
+            fs::tree_read,
+            fs::reveal_in_finder,
+            fs::open_external,
+            fs::file_read,
+            fs::file_write,
+            fs::file_create,
+            fs::file_folder_create,
+            fs::file_rename,
+            fs::file_move,
+            fs::file_duplicate,
+            fs::file_trash,
+            fs::asset_write,
+            watch::watch_start,
+            watch::watch_stop,
+            fs::index_rebuild,
+            fs::index_status,
+            fs::search_quick_open,
+            fs::search_text,
+            fs::backlinks_for,
+            spell::spell_check,
+            spell::spell_learn,
+            spell::spell_unlearn,
+            spell::spell_available,
+        ])
+        .run(context)
+        .expect("error while running Margin Docs");
+}

src-tauri/src/library.rs

@@ -0,0 +1,9 @@
+use std::fs;
+use std::path::PathBuf;
+use tauri::Manager;
+
+pub fn app_data_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    Ok(dir)
+}

src-tauri/src/macspell.rs

@@ -0,0 +1,162 @@
+// The one file in this app that talks to AppKit, and the whole of spelling on macOS.
+//
+// Spelling is NSSpellChecker's rather than this app's. It is the same shared checker Mail, Notes
+// and TextEdit correct into, so a word learned anywhere on the machine is a word this editor does
+// not underline, the user's own configured languages come along for free, and nothing here ships a
+// dictionary or holds an opinion about English. There is no custom word list beside it either:
+// learning a word teaches it to the system, which is where every other Mac app puts it.
+//
+// Three things make this more than a one line binding.
+//
+// Offsets are the first. AppKit answers in NSRange, which counts UTF-16 code units, and the caller
+// is a ProseMirror document, which counts code points. The two agree exactly until the paragraph
+// holds an emoji or anything else outside the basic plane, and from that character onwards every
+// later offset in the run is out by one per astral character. An underline drawn from a UTF-16
+// offset onto a code point document sits under the wrong word, and a suggestion applied at that
+// offset replaces the wrong characters, which is a silent edit to the user's file. `utf16_to_codepoint`
+// is the whole of the fix, and this file is the only place in the app allowed to do that conversion
+// so that there is exactly one thing to keep right.
+//
+// Which results to keep is the second. The checker is asked for Spelling and Link together and
+// only the spelling results are returned. Link earns its place in the request because it makes the
+// checker treat a URL as one span: without it `https://github.com/some-repo` is a run of tokens
+// none of which are in any dictionary, and a paragraph carrying a link comes back with half of it
+// underlined.
+//
+// The main thread is the third, and the answer is that none of this needs it. objc2 asks for a
+// `MainThreadMarker` on exactly the panel accessors of NSSpellChecker (`spellingPanel`,
+// `accessoryView`, `substitutionsPanel`), which this file never touches. The checking and learning
+// calls carry no such requirement, and since each of them round trips to the system spell service
+// over XPC, the caller deliberately runs them off the main thread.
+
+use objc2::rc::autoreleasepool;
+use objc2_app_kit::NSSpellChecker;
+use objc2_foundation::{NSRange, NSString, NSTextCheckingType};
+
+use crate::dto::SpellIssue;
+
+/// A context menu is a menu, not a dictionary page. The checker will happily offer thirty guesses
+/// and the ones past the first few are noise the user has to read past to reach Learn Spelling.
+const MAX_SUGGESTIONS: usize = 5;
+
+/// Zero as the spell document tag, everywhere below. A tag buys a per-document session the checker
+/// remembers ignored words against, and this app has no Ignore: a word is either learned for good
+/// or it stays underlined, so there is no session to allocate.
+const NO_DOCUMENT: isize = 0;
+
+/// UTF-16 offset to code point offset, one entry per code unit of `text` plus a terminal entry, so
+/// both ends of a half-open range are a lookup and neither is a special case.
+///
+/// A character outside the basic plane occupies two code units and one code point, so both of its
+/// units map to the same code point index. An NSRange landing in the middle of a surrogate pair,
+/// which the checker will not produce, therefore resolves to the start of that character rather
+/// than to a position that does not exist.
+fn utf16_to_codepoint(text: &str, utf16_len: usize) -> Vec<usize> {
+    let mut map = Vec::with_capacity(utf16_len + 1);
+    let mut cp = 0;
+    for ch in text.chars() {
+        for _ in 0..ch.len_utf16() {
+            map.push(cp);
+        }
+        cp += 1;
+    }
+    map.push(cp);
+    map
+}
+
+/// Every misspelling in one run of text, with half-open offsets in characters counted from the
+/// start of that run.
+///
+/// The run is not split into words here. NSSpellChecker does that better than any rule this app
+/// could write: it knows about contractions, hyphenation, proper nouns, capitalisation and
+/// whichever languages the user has turned on, and it decides where a word begins in each of them.
+pub fn check(text: &str) -> Vec<SpellIssue> {
+    autoreleasepool(|_| {
+        let checker = NSSpellChecker::sharedSpellChecker();
+        let ns = NSString::from_str(text);
+        let len = ns.length();
+        let results = unsafe {
+            checker.checkString_range_types_options_inSpellDocumentWithTag_orthography_wordCount(
+                &ns,
+                NSRange {
+                    location: 0,
+                    length: len,
+                },
+                (NSTextCheckingType::Spelling | NSTextCheckingType::Link).bits(),
+                None,
+                NO_DOCUMENT,
+                None,
+                std::ptr::null_mut(),
+            )
+        };
+
+        let map = utf16_to_codepoint(text, len);
+        let chars: Vec<char> = text.chars().collect();
+        let mut issues = Vec::new();
+        for result in results.iter() {
+            // Link results were asked for so the checker would recognise a URL as one span, not so
+            // that anything would be reported about them.
+            if result.resultType() != NSTextCheckingType::Spelling {
+                continue;
+            }
+            let range = result.range();
+            // Clamped to the length the map was built from. A range past the end would index out
+            // of it and panic, and a panic here takes down a command the frontend runs on every
+            // keystroke.
+            let start = map[range.location.min(len)];
+            let end = map[range.location.saturating_add(range.length).min(len)];
+
+            // The word comes back out of `text` rather than from the checker, so the string the
+            // frontend matches against is byte for byte the one it sent.
+            let word: String = chars[start..end].iter().collect();
+
+            // Asked in the checker's own coordinates, because this range indexes into `ns`.
+            let mut suggestions = Vec::new();
+            if let Some(guesses) = checker.guessesForWordRange_inString_language_inSpellDocumentWithTag(
+                range,
+                &ns,
+                None,
+                NO_DOCUMENT,
+            ) {
+                for guess in guesses.iter() {
+                    suggestions.push(guess.to_string());
+                    if suggestions.len() >= MAX_SUGGESTIONS {
+                        break;
+                    }
+                }
+            }
+
+            // Reported even with nothing to suggest. NSSpellChecker regularly flags a typo it has
+            // no guess for, and dropping those because the menu would have no replacements in it
+            // is how a checker earns a reputation for missing things.
+            issues.push(SpellIssue {
+                start,
+                end,
+                word,
+                suggestions,
+            });
+        }
+        issues
+    })
+}
+
+/// Teaches `word` to the system, for every app on this machine and not only for this one.
+///
+/// That is not a shortcut, it is what a checker borrowed from the OS does: `learnWord:` hands the
+/// word to the system spell service, exactly where the "Learn Spelling" item in Mail or Pages puts
+/// it, and every app on the machine stops underlining it from then on. This app deliberately keeps
+/// no private word list beside that, because a second dictionary the rest of the system cannot see
+/// is a word the user has to teach twice.
+pub fn learn(word: &str) {
+    autoreleasepool(|_| {
+        NSSpellChecker::sharedSpellChecker().learnWord(&NSString::from_str(word));
+    })
+}
+
+/// Undoes a `learn`, for a word taught by a slip of the hand. Also system wide, and the checker
+/// treats unlearning a word it was never taught as nothing to do rather than as an error.
+pub fn unlearn(word: &str) {
+    autoreleasepool(|_| {
+        NSSpellChecker::sharedSpellChecker().unlearnWord(&NSString::from_str(word));
+    })
+}

src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release, DO NOT REMOVE!!
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    margin_docs_lib::run()
+}

src-tauri/src/spell.rs

@@ -0,0 +1,95 @@
+// The four spelling commands, and the only place in this crate that knows whether the machine has
+// a checker at all.
+//
+// Everything real happens in macspell.rs, which is compiled on macOS alone. This module exists so
+// that the frontend gets the same four commands on every platform: it picks a checker at compile
+// time and each command below has one body rather than a cfg in the middle of it.
+//
+// A run with no misspellings and a build with no checker both answer with an empty list, and that
+// is deliberate. Returning an error from `spell_check` on a platform without NSSpellChecker would
+// put a permanent failure toast in front of a user whose actual situation is "this build cannot
+// check spelling", which is not a failure and is not something they can act on. `spell_available`
+// is where that fact belongs, because it is the one answer the UI can do something with: it hides
+// the underlines and the menu rather than offering a menu that does nothing.
+//
+// There is no state here and no dictionary file. The system holds the learned words, so there is
+// nothing for this module to load at launch, nothing to keep in sync and nothing to migrate.
+
+use crate::dto::SpellIssue;
+
+#[cfg(target_os = "macos")]
+use crate::macspell as checker;
+#[cfg(not(target_os = "macos"))]
+use self::no_checker as checker;
+
+/// Spelling on a platform this app has no system checker for: every call succeeds and does
+/// nothing. The alternative is a cfg inside each of the three commands that touch a checker, and
+/// three chances to get the non-macOS answer subtly different from each other.
+#[cfg(not(target_os = "macos"))]
+mod no_checker {
+    use crate::dto::SpellIssue;
+
+    pub fn check(_text: &str) -> Vec<SpellIssue> {
+        Vec::new()
+    }
+
+    pub fn learn(_word: &str) {}
+
+    pub fn unlearn(_word: &str) {}
+}
+
+/// Every misspelling in one run of text.
+///
+/// Offsets are half-open and counted in characters from the start of the run that was passed in,
+/// never from the start of a document. The checker is told about a paragraph and answers about that
+/// paragraph; it has no idea a document exists, which is what leaves the caller free to send a
+/// paragraph, a visible screenful or one sentence, and to add its own base offset afterwards.
+///
+/// Runs off the main thread. The call reaches the system spell service over XPC and a long
+/// paragraph is enough work that a window held still for the length of it would be visible, which
+/// matters more here than elsewhere because this is called while the user is typing.
+#[tauri::command(async)]
+pub fn spell_check(text: String) -> Result<Vec<SpellIssue>, String> {
+    Ok(checker::check(&text))
+}
+
+/// Teaches a word to the system dictionary, for every app on the machine and not only for this
+/// one.
+///
+/// That is the honest behaviour of a checker borrowed from the OS, and it is exactly what the
+/// "Learn Spelling" item in every other Mac app does. This app ships no dictionary of its own and
+/// keeps no private word list, so there is nowhere else for the word to go and nothing that would
+/// need teaching twice.
+///
+/// A blank word is nothing to learn rather than an error: the frontend takes the word from
+/// whatever the user right clicked, and an empty selection is a mis-click, not a failure worth a
+/// toast.
+#[tauri::command(async)]
+pub fn spell_learn(word: String) -> Result<(), String> {
+    let word = word.trim();
+    if word.is_empty() {
+        return Ok(());
+    }
+    checker::learn(word);
+    Ok(())
+}
+
+/// Undoes a `spell_learn`, for a word taught by a slip of the hand. System wide in the same way,
+/// and unlearning a word that was never learned is nothing to do rather than an error.
+#[tauri::command(async)]
+pub fn spell_unlearn(word: String) -> Result<(), String> {
+    let word = word.trim();
+    if word.is_empty() {
+        return Ok(());
+    }
+    checker::unlearn(word);
+    Ok(())
+}
+
+/// Whether this build has a checker behind it. Answered from the target rather than by asking
+/// AppKit anything: NSSpellChecker is part of macOS itself, so on a build that has it there is no
+/// failure mode where it is absent, and on any other build there is nothing to ask.
+#[tauri::command]
+pub fn spell_available() -> Result<bool, String> {
+    Ok(cfg!(target_os = "macos"))
+}

src-tauri/src/watch.rs

@@ -0,0 +1,463 @@
+// One filesystem watcher per open root. Changes never come back as a return value: each debounced
+// batch is emitted as a `watch-event`, so a file another program touched reaches the frontend the
+// same way whether anything asked for it or not.
+//
+// Debounced because one logical change is a burst of raw events. A git checkout rewrites a hundred
+// files, another editor's atomic save is a create, a rename and a remove for what the user thinks
+// of as one save, and a folder copied in arrives file by file. Reacting to raw events would reload
+// the open document several times over for a single save somewhere else.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{LazyLock, Mutex};
+use std::time::{Duration, Instant, SystemTime};
+
+use notify::event::{ModifyKind, RenameMode};
+use notify::{EventKind, RecommendedWatcher, RecursiveMode};
+use notify_debouncer_full::{
+    new_debouncer_opt, DebounceEventResult, DebouncedEvent, Debouncer, NoCache,
+};
+use tauri::{AppHandle, Emitter, Manager, State};
+
+use crate::dto::WatchEvent;
+use crate::Roots;
+
+/// Mirrors `WATCH_EVENT` in src/ipc.ts.
+const WATCH_EVENT: &str = "watch-event";
+
+/// How long a burst of raw events for one path is allowed to settle before it is reported.
+///
+/// Long enough that an atomic save arrives as one batch rather than as its create, rename and
+/// remove parts, short enough that a file changed by another program shows up while the user is
+/// still looking at the window that changed it.
+const DEBOUNCE: Duration = Duration::from_millis(300);
+
+/// How long a path stays on the self-written list.
+///
+/// The event for a write cannot reach the callback sooner than `DEBOUNCE` after the write finishes,
+/// and the debouncer's tick is a further `DEBOUNCE / 4`, so nothing under about 375ms would suppress
+/// anything at all. The rest is headroom for the write itself: an fsync on a large document on a
+/// busy disk can take a good fraction of a second, and the path is registered before the write
+/// starts, not after. Two seconds leaves room for that several times over, and the cost of
+/// overshooting is bounded and mild.
+///
+/// What that cost is: an external change to a file the app itself wrote less than two seconds ago is
+/// dropped. That is the right answer anyway. The only way to be inside that window is for the user
+/// to be typing in that document right now, and a reload mid-keystroke would throw away their
+/// unsaved text to show them somebody else's. The next save catches it regardless, because
+/// `file_write` compares mtimes and reports a conflict. Erring the other way is not symmetric: a
+/// leaked echo of the app's own autosave reloads the editor under the cursor on every save, which
+/// makes the app unusable rather than briefly out of date.
+///
+/// Entries expire on time and are not consumed on the first match, because one atomic save can
+/// produce several debounced events for the same path and suppressing only the first would defeat
+/// the whole thing.
+const SELF_WRITE_WINDOW: Duration = Duration::from_millis(2_000);
+
+/// How long after a change was raised a file may have been born and still count as created by it.
+///
+/// Covers the write landing, the backend noticing and the timestamp's own granularity. Too tight
+/// and a new file is reported as a modification of a file the tree has never heard of; too loose
+/// and editing a file made moments ago is reported as making it again.
+const BIRTH_SLACK: Duration = Duration::from_millis(250);
+
+/// Paths this app wrote, and when.
+///
+/// A global rather than managed state because the commands that write files take a path and nothing
+/// else: their signatures are the frozen contract, so there is no `State` for them to reach the
+/// watcher through. Keyed by the path with its directory resolved, since that is the only form both
+/// sides can agree on.
+static SELF_WRITES: LazyLock<Mutex<HashMap<PathBuf, Instant>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+/// Records that this app is about to write `path`, so the watcher drops the event that comes back.
+///
+/// Call it immediately before every write, for every path the write touches. An atomic save touches
+/// two, the temp file and the target it is renamed over, and each end raises its own events, so
+/// registering only the target lets the temp file's half through on its own. `fs::atomic_write` is
+/// the one caller, and every write in the app goes through it.
+///
+/// Cheap, so a caller unsure whether a path will really be written should register it anyway. The
+/// entry expires on its own and registering a path that is never written costs one map slot for two
+/// seconds.
+pub fn note_self_write<P: AsRef<Path>>(path: P) {
+    let key = resolve(path.as_ref());
+    let now = Instant::now();
+    if let Ok(mut writes) = SELF_WRITES.lock() {
+        writes.retain(|_, at| now.duration_since(*at) < SELF_WRITE_WINDOW);
+        writes.insert(key, now);
+    }
+}
+
+/// The live watchers, keyed by root id.
+///
+/// Dropping a debouncer stops its thread, so both `watch_stop` and closing a folder come down to a
+/// remove from this map and nothing else. The map is the only place a watcher is held: a watcher
+/// that is not in here is not running.
+#[derive(Default)]
+pub struct Watchers(pub Mutex<HashMap<String, Debouncer<RecommendedWatcher, NoCache>>>);
+
+/// Starts watching one open root, recursively. Idempotent: starting a watch that is already running
+/// is a no-op rather than a second watcher on the same folder.
+///
+/// Every debounced change is emitted as one `watch-event` carrying the root id, so the frontend can
+/// tell which tree to patch without matching path prefixes, and no path is ever the subject of more
+/// than one event per batch.
+///
+/// A rename is two events on macOS and not one: a `removed` for the name that went and a `created`
+/// or `modified` for the name that arrived. FSEvents describes the two ends as unrelated changes and
+/// nothing here can prove otherwise, so `old_path` stays empty and a frontend that wants to follow a
+/// renamed document has to pair them up itself, or rely on `file_rename` for the renames it made.
+/// `created` and `modified` are likewise a hint rather than a promise, since the only thing
+/// separating them is how recently the file was born: both mean the row should be inserted or
+/// refreshed. `removed` is exact, because it is a fact about the disk read at the moment of
+/// emitting.
+///
+/// The app's own writes are filtered out, on the strength of the paths `note_self_write` was told
+/// about. The frontend cannot do this itself: by the time it hears about a change it has already
+/// been handed a path and a reason to reload, and the mtime it holds cannot tell it apart from a
+/// write another program made in the same second.
+///
+/// The search index reads the same batch, which makes that filter its blind spot: the one document
+/// this stream never mentions is the one the user is typing in, because that is the one this app
+/// keeps saving. `fs::file_write` tells the index about its own saves for exactly that reason.
+///
+/// The root going away takes the watcher with it. A folder deleted or moved out from under a
+/// running watch emits one `removed` for the root path and then the watcher is dropped, since a
+/// watch on a path that no longer exists reports nothing and would sit in the map forever.
+#[tauri::command]
+pub fn watch_start(
+    app: AppHandle,
+    roots: State<'_, Roots>,
+    watchers: State<'_, Watchers>,
+    root_id: String,
+) -> Result<(), String> {
+    let root_path = roots.path_for(&root_id)?;
+
+    let mut live = watchers.0.lock().map_err(|e| e.to_string())?;
+    if live.contains_key(&root_id) {
+        return Ok(());
+    }
+
+    let handle = app.clone();
+    let dead_root = root_path.clone();
+    let dead_id = root_id.clone();
+    let debouncer = spawn_watcher(root_id.clone(), root_path, move |events| {
+        for event in &events {
+            handle.emit(WATCH_EVENT, event).ok();
+        }
+        // The index reads the same batch the frontend does, so a file another program wrote is
+        // searchable at the same moment the tree learns about it. It goes here rather than inside
+        // `spawn_watcher` because that function is also what the tests drive, with a real folder and
+        // no app at all to hold an index.
+        crate::index::note_watch_events(&handle, &events);
+        if events
+            .iter()
+            .any(|event| event.kind == "removed" && event.path == dead_root)
+        {
+            reap(handle.clone(), dead_id.clone());
+        }
+    })?;
+
+    live.insert(root_id, debouncer);
+    Ok(())
+}
+
+/// Stops the watcher for one root and drops it. Stopping a watch that is not running is a no-op, so
+/// the frontend can close a folder and stop its watcher without having to remember whether it ever
+/// started one.
+#[tauri::command]
+pub fn watch_stop(watchers: State<'_, Watchers>, root_id: String) -> Result<(), String> {
+    let mut live = watchers.0.lock().map_err(|e| e.to_string())?;
+    live.remove(&root_id);
+    Ok(())
+}
+
+/// Watches `root_path` recursively and hands each debounced batch to `sink` as `watch-event`
+/// payloads. The watch runs until the returned debouncer is dropped.
+///
+/// `watch_start` is a thin wrapper over this: everything above the Tauri event lives here so the
+/// tests can drive a real watcher over a real folder without an app to emit into.
+pub fn spawn_watcher<F>(
+    root_id: String,
+    root_path: String,
+    sink: F,
+) -> Result<Debouncer<RecommendedWatcher, NoCache>, String>
+where
+    F: Fn(Vec<WatchEvent>) + Send + 'static,
+{
+    let root = PathBuf::from(&root_path);
+    if !root.is_dir() {
+        return Err(format!("not a folder: {root_path}"));
+    }
+    let canonical = std::fs::canonicalize(&root).map_err(|e| e.to_string())?;
+
+    let watched = canonical.clone();
+    let handler = move |result: DebounceEventResult| {
+        let batch = match result {
+            Ok(batch) => batch,
+            Err(errors) => {
+                for error in errors {
+                    eprintln!("watch error under {}: {error}", watched.display());
+                }
+                return;
+            }
+        };
+        let events = watch_events(&batch, &root_id, &watched, &root);
+        if !events.is_empty() {
+            sink(events);
+        }
+    };
+
+    // Deliberately without the file id cache the crate would otherwise pick. Its whole job is to
+    // recognise the two halves of a rename by inode, and on macOS it does more harm than good: it
+    // decides the halves belong together, folds the old name's events into the new name's queue,
+    // and then throws away the rename event that carried the old name, because FSEvents claims the
+    // old name was created. What comes out is a modification of the new path and no word at all
+    // that the old path is gone, which leaves a row in the tree for a file that no longer exists.
+    // With no cache the two halves stay separate and both ends get reported.
+    let mut debouncer: Debouncer<RecommendedWatcher, NoCache> = new_debouncer_opt(
+        DEBOUNCE,
+        None,
+        handler,
+        NoCache::new(),
+        notify::Config::default(),
+    )
+    .map_err(|e| e.to_string())?;
+
+    debouncer
+        .watch(&canonical, RecursiveMode::Recursive)
+        .map_err(|e| e.to_string())?;
+    Ok(debouncer)
+}
+
+/// Drops a root's watcher from another thread.
+///
+/// The call site is inside the debouncer's own callback, and dropping a debouncer from the thread it
+/// is calling you on is asking for a join on yourself. One short-lived thread is the whole fix.
+fn reap(app: AppHandle, root_id: String) {
+    std::thread::spawn(move || {
+        if let Some(watchers) = app.try_state::<Watchers>() {
+            if let Ok(mut live) = watchers.0.lock() {
+                live.remove(&root_id);
+            }
+        }
+    });
+}
+
+/// One debounced batch turned into the events the frontend sees: classified, filtered and reduced
+/// to at most one event per path.
+fn watch_events(
+    batch: &[DebouncedEvent],
+    root_id: &str,
+    canonical_root: &Path,
+    root_path: &Path,
+) -> Vec<WatchEvent> {
+    let mut events: Vec<WatchEvent> = Vec::new();
+    let mut index: HashMap<String, usize> = HashMap::new();
+
+    for event in batch {
+        // The kernel dropped events under load and the backend is telling us so. Nothing in the
+        // batch describes what was missed, so the honest answer is to report the root as changed
+        // and let the frontend read the tree again.
+        let next = if event.need_rescan() {
+            WatchEvent {
+                root: root_id.to_string(),
+                path: root_path.to_string_lossy().into_owned(),
+                kind: "modified".to_string(),
+                old_path: None,
+            }
+        } else {
+            let Some((kind, path, old_path)) = classify(event) else {
+                continue;
+            };
+            // The root itself is exempt from the transient rule: a folder called `.notes` is a
+            // perfectly good root, and its own removal is the one event nothing under it can
+            // describe.
+            if was_self_written(&path)
+                || old_path.as_deref().is_some_and(was_self_written)
+                || (path.as_path() != canonical_root && is_transient(&path))
+                || is_hidden_below(&path, canonical_root)
+            {
+                continue;
+            }
+            WatchEvent {
+                root: root_id.to_string(),
+                path: rebase(&path, canonical_root, root_path),
+                kind: kind.to_string(),
+                old_path: old_path.map(|path| rebase(&path, canonical_root, root_path)),
+            }
+        };
+
+        merge(&mut events, &mut index, next);
+    }
+
+    // The root itself going away is the one change nothing under it can describe. macOS does report
+    // it as an event on the watched path, but a folder moved rather than emptied is a single rename
+    // this side may never see, so the state of the folder is checked rather than waited for.
+    if !canonical_root.exists() {
+        merge(
+            &mut events,
+            &mut index,
+            WatchEvent {
+                root: root_id.to_string(),
+                path: root_path.to_string_lossy().into_owned(),
+                kind: "removed".to_string(),
+                old_path: None,
+            },
+        );
+    }
+
+    events
+}
+
+fn merge(events: &mut Vec<WatchEvent>, index: &mut HashMap<String, usize>, next: WatchEvent) {
+    match index.get(&next.path) {
+        // A later `modified` says nothing a create or a rename in the same batch has not already
+        // said, and would lose that event's `old_path`. Anything else supersedes.
+        Some(_) if next.kind == "modified" => {}
+        Some(&at) => events[at] = next,
+        None => {
+            index.insert(next.path.clone(), events.len());
+            events.push(next);
+        }
+    }
+}
+
+/// The kind, the path it happened to and, for a rename, where the file was before.
+///
+/// Almost nothing here comes from the event's own kind, and that is deliberate. FSEvents does not
+/// describe a change, it describes a file: every event it reports for a path carries the union of
+/// everything that has ever happened to that path, so `ItemCreated` is set on the modification of a
+/// file that was created last week and on the deletion of one created a second ago. Trusting it
+/// would report every save as a create and, once the debouncer has folded a create and a remove
+/// together, every deletion as a modification.
+///
+/// So the file itself is asked instead. The event says which path changed, which is the one thing
+/// FSEvents is reliable about, and a stat at the moment of emitting says what it changed into. That
+/// is also fresher than the flags: by the time a batch comes out it is at least a debounce window
+/// old, and what is on disk now is what the frontend is about to go and read.
+fn classify(event: &DebouncedEvent) -> Option<(&'static str, PathBuf, Option<PathBuf>)> {
+    let first = event.paths.first()?.clone();
+
+    // The one thing a stat cannot answer afterwards is where a file used to be, so a rename the
+    // debouncer managed to stitch back together is read from the event. macOS never gets here: it
+    // reports the two ends of a rename as unrelated events and the pairing is left to the inode
+    // cache this watcher deliberately does without. A backend that names both ends itself, which
+    // inotify does through the rename cookie, still arrives whole.
+    if let EventKind::Modify(ModifyKind::Name(RenameMode::Both)) = &event.kind {
+        let to = event.paths.get(1)?.clone();
+        if is_transient(&to) || !to.exists() {
+            return Some(("removed", first, None));
+        }
+        if is_transient(&first) {
+            // Another editor saving the way this one does: a temp file renamed over the target.
+            // Reporting the temp name as the document's previous name would have the frontend go
+            // looking for a tree row that never existed.
+            return Some((appearance(event, &to), to, None));
+        }
+        return Some(("renamed", to, Some(first)));
+    }
+
+    if matches!(&event.kind, EventKind::Access(_) | EventKind::Other) {
+        return None;
+    }
+
+    Some((appearance(event, &first), first, None))
+}
+
+/// What is at the path now: `created`, `modified` or `removed`.
+///
+/// Created and modified are told apart by the file's birth time, since nothing else survives to
+/// here. A file born within a slack of when the event was raised was born by the change the event
+/// describes; anything older was only touched by it. The slack covers the gap between the write
+/// landing and the backend seeing it, and erring towards `created` is the cheaper mistake: both
+/// kinds mean the same thing to a tree that inserts or refreshes a row, and only `removed` means
+/// something a frontend must not get wrong.
+fn appearance(event: &DebouncedEvent, path: &Path) -> &'static str {
+    let Ok(meta) = std::fs::symlink_metadata(path) else {
+        return "removed";
+    };
+    let Ok(born) = meta.created() else {
+        return "modified";
+    };
+    let happened = SystemTime::now().checked_sub(event.time.elapsed());
+    match (born.checked_add(BIRTH_SLACK), happened) {
+        (Some(fresh_until), Some(happened)) if fresh_until >= happened => "created",
+        _ => "modified",
+    }
+}
+
+/// A name no tree row will ever carry: an editor's lock file, swap file or backup, or the temp file
+/// half of somebody's atomic save.
+///
+/// Every path in a batch goes through this, not only the two ends of a rename the debouncer managed
+/// to stitch together. macOS never reports a rename whole, so the branch in `classify` that used to
+/// be the only caller never ran there, and the temp file of every save in the folder was reported to
+/// the frontend as a document appearing and then vanishing.
+///
+/// This app's own temp file, `.<name>.<unique>.tmp`, is caught twice over, by the leading dot and by
+/// the extension. That is on purpose: `note_self_write` already covers it, and a save that somehow
+/// outran its two second window should still not put a temp name in front of the user.
+fn is_transient(path: &Path) -> bool {
+    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+        return false;
+    };
+    name.starts_with('.')
+        || name.ends_with('~')
+        || name.ends_with(".tmp")
+        || name.ends_with(".swp")
+        || name.ends_with(".swx")
+}
+
+/// Whether the path sits under a dot-directory or is a dotfile, counted from the root down.
+///
+/// The tree hides those, so reporting them would be reporting changes to rows that do not exist:
+/// `.git` alone would fire hundreds of times for one checkout. Counted from the root and not from
+/// `/` because a root may perfectly well be a folder inside `~/.config`, and that folder's contents
+/// are not hidden from anybody.
+fn is_hidden_below(path: &Path, root: &Path) -> bool {
+    let Ok(rel) = path.strip_prefix(root) else {
+        return false;
+    };
+    rel.components()
+        .any(|part| part.as_os_str().to_string_lossy().starts_with('.'))
+}
+
+/// The path as the frontend knows it: under the root exactly as `Roots` spells it.
+///
+/// FSEvents reports resolved paths, so a root opened as `/tmp/notes` comes back as
+/// `/private/tmp/notes` and every path the frontend holds would fail to match.
+fn rebase(path: &Path, canonical_root: &Path, root_path: &Path) -> String {
+    match path.strip_prefix(canonical_root) {
+        Ok(rel) if rel.as_os_str().is_empty() => root_path.to_string_lossy().into_owned(),
+        Ok(rel) => root_path.join(rel).to_string_lossy().into_owned(),
+        Err(_) => path.to_string_lossy().into_owned(),
+    }
+}
+
+/// A path with its directory resolved through any symlink, which is the form event paths arrive in.
+///
+/// The directory and not the path itself, because the file about to be written may not exist yet and
+/// there is nothing to canonicalise. macOS alone makes this necessary: `/tmp` and `/var` are
+/// symlinks into `/private`, so a document under either would never match the event describing it.
+fn resolve(path: &Path) -> PathBuf {
+    let (Some(parent), Some(name)) = (path.parent(), path.file_name()) else {
+        return path.to_path_buf();
+    };
+    match std::fs::canonicalize(parent) {
+        Ok(dir) => dir.join(name),
+        Err(_) => path.to_path_buf(),
+    }
+}
+
+/// Event paths arrive already resolved, because the watch is placed on the canonicalised root, so
+/// they can be looked up as they are.
+fn was_self_written(path: &Path) -> bool {
+    let Ok(writes) = SELF_WRITES.lock() else {
+        return false;
+    };
+    writes
+        .get(path)
+        .is_some_and(|at| Instant::now().duration_since(*at) < SELF_WRITE_WINDOW)
+}