diff --git a/src/bin/mdo-open.rs b/src/bin/mdo-open.rs
index df36de0..5cbb1f6 100644
--- a/src/bin/mdo-open.rs
+++ b/src/bin/mdo-open.rs
@@ -10,10 +10,13 @@
 //! but break terminal usage (no stdout to the parent shell, output races the
 //! returning prompt under cmd/PowerShell).
 //!
-//! Instead, `mdo-open[.exe]` is a tiny desktop wrapper that:
-//!   1. Locates `mdo[.exe]` next to itself.
-//!   2. Spawns it with `--open` and the rest of the args, using
-//!      `CREATE_NO_WINDOW` so the child never gets a console allocated.
+//! Instead, `mdo-open[.exe]` is a tiny desktop wrapper that consumes the
+//! shared handler invocation contract (`mdo_cli::handler`):
+//!   1. Locates `mdo[.exe]` next to itself (the one sibling-binary
+//!      discovery function, so a missing sibling gets one clear message).
+//!   2. Spawns it with the contract argv (`--open` plus the file args),
+//!      using `CREATE_NO_WINDOW` so the child never gets a console
+//!      allocated.
 //!   3. If launched directly with no file args, opens onboarding: Windows
 //!      starts the terminal setup in Windows Terminal when available; Linux
 //!      opens `mdo-setup` for native first-run onboarding. This step is
@@ -48,8 +51,8 @@ use std::process::{Command, ExitCode};
 
 #[cfg(target_os = "windows")]
 use std::io;
-#[cfg(target_os = "windows")]
-use std::path::Path;
+
+use mdo_cli::handler;
 
 #[cfg(target_os = "windows")]
 const MDO_BIN: &str = "mdo.exe";
@@ -60,12 +63,16 @@ const MDO_BIN: &str = "mdo";
 const SETUP_BIN: &str = "mdo-setup";
 
 fn main() -> ExitCode {
-    let mut exe_path = match env::current_exe() {
+    // A GUI-launched binary often has no console attached, so this message
+    // may still go nowhere on Windows — but silent failure is worse
+    // everywhere, and on Linux it reaches the file manager's stderr log.
+    let exe_path = match env::current_exe() {
         Ok(p) => p,
-        Err(_) => return ExitCode::from(1),
+        Err(e) => {
+            eprintln!("mdo-open: cannot locate its own executable: {e}");
+            return ExitCode::from(1);
+        }
     };
-    exe_path.pop(); // strip the file name, keep the directory
-
     let args = env::args_os().skip(1).collect::<Vec<_>>();
 
     #[cfg(target_os = "windows")]
@@ -77,7 +84,10 @@ fn main() -> ExitCode {
         if args.is_empty() {
             return match spawn_windows_onboarding(&exe_path) {
                 Ok(()) => ExitCode::SUCCESS,
-                Err(_) => ExitCode::from(1),
+                Err(e) => {
+                    eprintln!("mdo-open: {e}");
+                    ExitCode::from(1)
+                }
             };
         }
 
@@ -90,33 +100,47 @@ fn main() -> ExitCode {
         // instead of always reporting success.
         match spawn_windows_open(&exe_path, args) {
             Ok(status) => exit_code_from_status(status),
-            Err(_) => ExitCode::from(1),
+            Err(e) => {
+                eprintln!("mdo-open: {e}");
+                ExitCode::from(1)
+            }
         }
     }
 
     #[cfg(not(target_os = "windows"))]
     {
         #[cfg(target_os = "linux")]
-        let mut cmd = if args.is_empty() {
-            let setup = exe_path.join(SETUP_BIN);
-            if !setup.exists() {
-                return ExitCode::from(1);
+        if args.is_empty() {
+            // No-file launch is onboarding, not open: hand off to the
+            // sibling `mdo-setup`.
+            let setup = match handler::sibling_binary(&exe_path, SETUP_BIN) {
+                Ok(path) => path,
+                Err(e) => {
+                    eprintln!("mdo-open: {e}");
+                    return ExitCode::from(1);
+                }
+            };
+            let mut cmd = Command::new(setup);
+            match cmd.status() {
+                Ok(status) => return exit_code_from_status(status),
+                Err(e) => {
+                    eprintln!("mdo-open: {e}");
+                    return ExitCode::from(1);
+                }
             }
-            Command::new(setup)
-        } else {
-            let mut cmd = Command::new(exe_path.join(MDO_BIN));
-            cmd.arg("--open");
-            cmd.args(args);
-            cmd
-        };
+        }
 
-        #[cfg(not(target_os = "linux"))]
-        let mut cmd = {
-            let mut cmd = Command::new(exe_path.join(MDO_BIN));
-            cmd.arg("--open");
-            cmd.args(args);
-            cmd
+        // Everything else is the forward: sibling mdo with the contract
+        // argv (`--open` plus the files as received).
+        let mdo_bin = match handler::sibling_binary(&exe_path, MDO_BIN) {
+            Ok(path) => path,
+            Err(e) => {
+                eprintln!("mdo-open: {e}");
+                return ExitCode::from(1);
+            }
         };
+        let mut cmd = Command::new(mdo_bin);
+        cmd.args(handler::open_argv(&args));
 
         // Non-Windows binaries never had a console-flash problem to begin
         // with (that's Windows Explorer + console-subsystem-exe behavior),
@@ -126,7 +150,10 @@ fn main() -> ExitCode {
         // in an already-attached terminal) and propagate its exit status.
         match cmd.status() {
             Ok(status) => exit_code_from_status(status),
-            Err(_) => ExitCode::from(1),
+            Err(e) => {
+                eprintln!("mdo-open: {e}");
+                ExitCode::from(1)
+            }
         }
     }
 }
@@ -137,10 +164,17 @@ fn main() -> ExitCode {
 /// a failure whose low byte is zero (e.g. 0x100) must not truncate to
 /// "success"; any failing status maps to a non-zero code.
 fn exit_code_from_status(status: std::process::ExitStatus) -> ExitCode {
-    if status.success() {
+    exit_code_from_parts(status.success(), status.code())
+}
+
+/// The truncation rule of [`exit_code_from_status`], split from
+/// `ExitStatus` so it is unit-testable portably (Unix cannot even produce a
+/// failed status with a zero low byte; Windows can).
+fn exit_code_from_parts(success: bool, code: Option<i32>) -> ExitCode {
+    if success {
         return ExitCode::SUCCESS;
     }
-    match status.code() {
+    match code {
         Some(code) if code as u8 != 0 => ExitCode::from(code as u8),
         _ => ExitCode::FAILURE,
     }
@@ -148,28 +182,18 @@ fn exit_code_from_status(status: std::process::ExitStatus) -> ExitCode {
 
 #[cfg(target_os = "windows")]
 fn spawn_windows_open(
-    exe_dir: &Path,
+    anchor_exe: &std::path::Path,
     args: Vec<std::ffi::OsString>,
 ) -> io::Result<std::process::ExitStatus> {
-    let mut cmd = Command::new(exe_dir.join(MDO_BIN));
-    cmd.arg("--open");
-    cmd.args(args);
+    let mdo_bin = handler::sibling_binary(anchor_exe, MDO_BIN)?;
+    let mut cmd = Command::new(mdo_bin);
+    cmd.args(handler::open_argv(&args));
     spawn_without_console(cmd)
 }
 
 #[cfg(target_os = "windows")]
-fn spawn_windows_onboarding(exe_dir: &Path) -> io::Result<()> {
-    let mdo = exe_dir.join(MDO_BIN);
-    if !mdo.exists() {
-        return Err(io::Error::new(
-            io::ErrorKind::NotFound,
-            format!(
-                "expected {MDO_BIN} next to mdo-open.exe at {}",
-                mdo.display()
-            ),
-        ));
-    }
-
+fn spawn_windows_onboarding(anchor_exe: &std::path::Path) -> io::Result<()> {
+    let mdo = handler::sibling_binary(anchor_exe, MDO_BIN)?;
     mdo_cli::windows_setup::spawn_terminal_setup(&mdo)
 }
 
@@ -189,3 +213,51 @@ fn spawn_without_console(mut cmd: Command) -> io::Result<std::process::ExitStatu
     let mut child = cmd.spawn()?;
     child.wait()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn exit_code_success_is_success() {
+        assert_eq!(exit_code_from_parts(true, Some(0)), ExitCode::SUCCESS);
+        assert_eq!(exit_code_from_parts(true, None), ExitCode::SUCCESS);
+    }
+
+    #[test]
+    fn small_exit_codes_pass_through() {
+        assert_eq!(exit_code_from_parts(false, Some(1)), ExitCode::from(1));
+        assert_eq!(exit_code_from_parts(false, Some(7)), ExitCode::from(7));
+        assert_eq!(exit_code_from_parts(false, Some(255)), ExitCode::from(255));
+    }
+
+    #[test]
+    fn failure_with_zero_low_byte_must_not_read_as_success() {
+        // The truncation trap: 0x100 has a zero low byte, but the child
+        // FAILED. Truncating to `ExitCode::from(0)` would report success.
+        assert_eq!(exit_code_from_parts(false, Some(0x100)), ExitCode::FAILURE);
+        assert_eq!(exit_code_from_parts(false, Some(0x200)), ExitCode::FAILURE);
+        assert_eq!(exit_code_from_parts(false, Some(0xFF00)), ExitCode::FAILURE);
+    }
+
+    #[test]
+    fn unknown_termination_falls_back_to_failure() {
+        // Signal deaths (and nested nested process terminations) offer no
+        // exit code at all: a generic failure keeps mdo-open honest.
+        assert_eq!(exit_code_from_parts(false, None), ExitCode::FAILURE);
+    }
+
+    // Windows-only end-to-end of the truncation rule: only Windows can
+    // actually produce a failed child whose exit code has a zero low byte.
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn real_windows_exit_code_256_means_failure() {
+        let status = Command::new("cmd.exe")
+            .args(["/C", "exit", "256"])
+            .status()
+            .expect("cmd.exe should be spawnable on Windows");
+        assert!(!status.success());
+        assert_eq!(status.code(), Some(256));
+        assert_eq!(exit_code_from_status(status), ExitCode::FAILURE);
+    }
+}
diff --git a/src/bin/mdo-setup.rs b/src/bin/mdo-setup.rs
index 609d381..f45e724 100644
--- a/src/bin/mdo-setup.rs
+++ b/src/bin/mdo-setup.rs
@@ -93,13 +93,7 @@ mod linux_setup {
 
     pub fn run() -> io::Result<()> {
         continue_after_launcher_registration(register_launcher());
-        let mdo = sibling_binary("mdo")?;
-        if !mdo.exists() {
-            return Err(io::Error::new(
-                io::ErrorKind::NotFound,
-                format!("expected mdo next to mdo-setup at {}", mdo.display()),
-            ));
-        }
+        let mdo = mdo_cli::handler::sibling_binary(&std::env::current_exe()?, "mdo")?;
 
         // Already attached to a terminal (e.g. run from a shell): show guided setup
         // right here instead of spawning a second window. The `?` still
@@ -254,12 +248,6 @@ mod linux_setup {
             .unwrap_or(false)
     }
 
-    fn sibling_binary(name: &str) -> io::Result<PathBuf> {
-        let mut path = std::env::current_exe()?;
-        path.pop();
-        Ok(path.join(name))
-    }
-
     #[cfg(test)]
     mod tests {
         use super::*;
@@ -338,7 +326,7 @@ mod windows_setup {
     };
 
     pub fn run() -> io::Result<()> {
-        let mdo = sibling_binary("mdo.exe")?;
+        let mdo = mdo_cli::handler::sibling_binary(&std::env::current_exe()?, "mdo.exe")?;
         if !mdo.exists() {
             return Err(io::Error::new(
                 io::ErrorKind::NotFound,
@@ -375,12 +363,6 @@ mod windows_setup {
         Ok(button)
     }
 
-    fn sibling_binary(name: &str) -> io::Result<PathBuf> {
-        let mut path = std::env::current_exe()?;
-        path.pop();
-        Ok(path.join(name))
-    }
-
     fn wide(value: &str) -> Vec<u16> {
         value.encode_utf16().chain(iter::once(0)).collect()
     }
diff --git a/src/file_manager.rs b/src/file_manager.rs
index 3674b2f..8140994 100644
--- a/src/file_manager.rs
+++ b/src/file_manager.rs
@@ -4,6 +4,8 @@ use std::process::Command;
 #[cfg(target_os = "windows")]
 use std::process::Stdio;
 
+use crate::handler;
+
 const APP_DISPLAY_NAME: &str = "Open as HTML";
 #[cfg(target_os = "linux")]
 const DESKTOP_FILE_NAME: &str = "mdo.desktop";
@@ -27,103 +29,284 @@ const SVG_ICON: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" width="256" h
 #[cfg(any(target_os = "linux", target_os = "windows"))]
 use std::fs;
 
+/// Register the file-manager integration for this user. On Linux this
+/// writes the hidden `mdo.desktop` entry and its icon through a pure
+/// planning step and a thin executor; on Windows it shells out to
+/// `reg.exe` (see [`install_windows_plan`] for the registry shape).
+/// Windows ignores `set_default`: choosing a default app lives in
+/// Explorer's Open with dialog, not in the registration.
+#[cfg(target_os = "linux")]
 pub fn install(set_default: bool) -> io::Result<()> {
-    install_impl(set_default)
-}
+    let exe = std::env::current_exe()?;
+    let data_home = xdg_data_home()?;
 
-pub fn uninstall() -> io::Result<()> {
-    uninstall_impl()
+    let plan = linux_install_plan(&data_home, &exe, set_default);
+    let report = apply_linux_install_plan(&plan)?;
+    print_linux_install_report(&report);
+    Ok(())
 }
 
-/// Report whether mdo's own handler registration is present for this user.
-///
-/// This is deliberately a cheap owned-state check (ADR 0004 defers the full
-/// integration-state manager): it only asks "did mdo's install step leave its
-/// own registration behind?" and never inspects handler health, partial or
-/// stale remnants, system-wide registrations, or the effective default app.
-/// A query failure reads as "not detected", so setup falls back to the
-/// ordinary first-time flow — which is safe because install is idempotent.
-pub fn integration_installed() -> bool {
-    integration_installed_impl()
+/// Data-first description of a Linux integration install: everything the
+/// executor touches, decided without disk or environment access so the
+/// planning step stays a pure function (unit-tested without spawn-capture),
+/// mirroring the registry's [`install_windows_plan`].
+#[cfg(target_os = "linux")]
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct LinuxInstallPlan {
+    /// The hidden `mdo.desktop` handler entry and where it goes.
+    desktop_file: PathBuf,
+    /// The entry's content, handler-invocation contract spelling included.
+    desktop_entry: String,
+    /// The hicolor icon file and where it goes.
+    icon_file: PathBuf,
+    /// Whether xdg-mime should try to register mdo as the default handler
+    /// for the mimes in [`LinuxInstallPlan::default_mimes`].
+    set_default: bool,
+    /// The mimes to register, in order, exactly as the original inline flow
+    /// did.
+    default_mimes: &'static [&'static str],
+    /// The data root the legacy nautilus script cleanup runs against.
+    legacy_cleanup_root: Option<PathBuf>,
 }
 
+/// What the Linux install executor changed, for the caller to print. File
+/// entries are paths; the default outcome is the one piece of xdg-mime's
+/// best-effort behavior a human needs to see.
 #[cfg(target_os = "linux")]
-fn install_impl(set_default: bool) -> io::Result<()> {
-    let exe = std::env::current_exe()?;
-    install_linux_for_exe(&exe, set_default)
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct LinuxInstallReport {
+    desktop_file: PathBuf,
+    icon_file: PathBuf,
+    default: LinuxDefaultOutcome,
 }
 
 #[cfg(target_os = "linux")]
-pub fn install_linux_for_exe(current_exe: &Path, set_default: bool) -> io::Result<()> {
-    let data_home = xdg_data_home()?;
-    let desktop_dir = data_home.join("applications");
-    let desktop_file = desktop_dir.join(DESKTOP_FILE_NAME);
-    let icon_root = data_home.join("icons").join("hicolor");
-    let icon_dir = icon_root.join("scalable").join("apps");
-    let icon_file = icon_dir.join("mdo.svg");
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum LinuxDefaultOutcome {
+    /// xdg-mime registered mdo for at least one of the mimes.
+    Applied,
+    /// Defaulting was requested but xdg-mime could not comply (tool
+    /// missing or non-zero exit): the manual hint applies.
+    NeedsManualHint,
+    /// Defaulting was not requested: integration stays Open With-only.
+    NotRequested,
+}
 
-    fs::create_dir_all(&desktop_dir)?;
-    fs::create_dir_all(&icon_dir)?;
-    fs::write(&icon_file, SVG_ICON)?;
+#[cfg(target_os = "linux")]
+fn linux_install_plan(data_home: &Path, current_exe: &Path, set_default: bool) -> LinuxInstallPlan {
+    LinuxInstallPlan {
+        desktop_file: data_home.join("applications").join(DESKTOP_FILE_NAME),
+        desktop_entry: linux_desktop_entry(current_exe),
+        icon_file: data_home
+            .join("icons")
+            .join("hicolor")
+            .join("scalable")
+            .join("apps")
+            .join("mdo.svg"),
+        set_default,
+        default_mimes: &["text/markdown", "text/x-markdown"],
+        legacy_cleanup_root: Some(data_home.to_path_buf()),
+    }
+}
 
-    let desktop_entry = linux_desktop_entry(current_exe);
-    fs::write(&desktop_file, desktop_entry)?;
+/// Apply the plan in the original write order: directories, icon, entry
+/// (mode 0644), best-effort desktop-database refresh, the optional default
+/// registration, and the legacy cleanup. A scalable SVG under
+/// hicolor/scalable/apps is resolved by name, so it needs no icon-cache
+/// refresh; gtk-update-icon-cache on a user theme dir without an
+/// index.theme just fails — skip it.
+#[cfg(target_os = "linux")]
+fn apply_linux_install_plan(plan: &LinuxInstallPlan) -> io::Result<LinuxInstallReport> {
+    if let Some(applications) = plan.desktop_file.parent() {
+        fs::create_dir_all(applications)?;
+    }
+    if let Some(icon_dir) = plan.icon_file.parent() {
+        fs::create_dir_all(icon_dir)?;
+    }
+    fs::write(&plan.icon_file, SVG_ICON)?;
+    fs::write(&plan.desktop_file, &plan.desktop_entry)?;
 
     #[cfg(unix)]
     {
         use std::os::unix::fs::PermissionsExt;
-        fs::set_permissions(&desktop_file, fs::Permissions::from_mode(0o644))?;
+        fs::set_permissions(&plan.desktop_file, fs::Permissions::from_mode(0o644))?;
     }
 
-    run_optional("update-desktop-database", &[desktop_dir.as_os_str()]);
-
-    // A scalable SVG under hicolor/scalable/apps is resolved by name, so it
-    // needs no icon-cache refresh; gtk-update-icon-cache on a user theme dir
-    // without an index.theme just fails. Skip it.
+    if let Some(applications) = plan.desktop_file.parent() {
+        run_optional("update-desktop-database", &[applications.as_os_str()]);
+    }
 
-    let default_set = if set_default {
+    let default = if plan.set_default {
         let mut ok = false;
-        for mime in ["text/markdown", "text/x-markdown"] {
+        for mime in plan.default_mimes {
             ok |= run_optional_status(
                 "xdg-mime",
                 &[
                     std::ffi::OsStr::new("default"),
                     std::ffi::OsStr::new(DESKTOP_FILE_NAME),
-                    std::ffi::OsStr::new(mime),
+                    std::ffi::OsStr::new(*mime),
                 ],
             );
         }
-        ok
+        if ok {
+            LinuxDefaultOutcome::Applied
+        } else {
+            LinuxDefaultOutcome::NeedsManualHint
+        }
     } else {
-        false
+        LinuxDefaultOutcome::NotRequested
     };
 
-    remove_legacy_nautilus_scripts(&data_home)?;
+    if let Some(root) = &plan.legacy_cleanup_root {
+        remove_legacy_nautilus_scripts(root)?;
+    }
 
-    println!("Installed desktop entry: {}", desktop_file.display());
-    println!("Installed icon: {}", icon_file.display());
-    if set_default {
-        if default_set {
+    Ok(LinuxInstallReport {
+        desktop_file: plan.desktop_file.clone(),
+        icon_file: plan.icon_file.clone(),
+        default,
+    })
+}
+
+/// Print the executor's report. This is the Linux install's whole CLI
+/// surface; the exact lines mirror the pre-plan flow byte for byte.
+#[cfg(target_os = "linux")]
+fn print_linux_install_report(report: &LinuxInstallReport) {
+    println!("Installed desktop entry: {}", report.desktop_file.display());
+    println!("Installed icon: {}", report.icon_file.display());
+    match report.default {
+        LinuxDefaultOutcome::Applied => {
             println!("{APP_DISPLAY_NAME} is now the default Markdown handler.");
-        } else {
+        }
+        LinuxDefaultOutcome::NeedsManualHint => {
             println!(
                 "Could not set {APP_DISPLAY_NAME} as the default automatically (is xdg-mime installed?)."
             );
             println!("To set it manually, run: xdg-mime default {DESKTOP_FILE_NAME} text/markdown");
             println!("(and the same for text/x-markdown)");
         }
-    } else {
+        LinuxDefaultOutcome::NotRequested => {
+            println!(
+                "{APP_DISPLAY_NAME} is available from Open With without changing your default Markdown handler."
+            );
+        }
+    }
+}
+
+/// Windows registration: resolve the handler beside the running exe, write
+/// the icon, then apply the registry plan (planning and its tests are
+/// pure; the executor is the only registry-touching step).
+#[cfg(target_os = "windows")]
+pub fn install(_set_default: bool) -> io::Result<()> {
+    let current_exe = std::env::current_exe()?;
+    let handler_selection = windows_handler_for(&current_exe);
+    let command = windows_registry_command(&handler_selection.path, handler_selection.is_wrapper);
+    let icon_file = install_windows_icon()?;
+    let icon_ref = format!("\"{}\",0", icon_file.display());
+    let current_exe_command = windows_registry_command(&current_exe, false);
+
+    // Registry mutation is split into a pure planning step (`install_windows_plan`,
+    // unit-tested below without touching the registry) and a thin executor
+    // (`apply_registry_plan`) that shells out to `reg.exe`. This keeps the
+    // "which keys/values would be written, in what order, with which
+    // failure semantics" logic testable in CI without mutating the real
+    // registry on the CI machine.
+    let plan = install_windows_plan(
+        handler_selection.is_wrapper,
+        &command,
+        &current_exe_command,
+        &icon_ref,
+    );
+    apply_registry_plan(&plan)?;
+
+    println!("Using handler: {}", handler_selection.path.display());
+    println!("Using icon: {}", icon_file.display());
+    if !handler_selection.is_wrapper {
         println!(
-            "{APP_DISPLAY_NAME} is available from Open With without changing your default Markdown handler."
+            "Note: mdo-open.exe was not found next to mdo.exe, so Explorer will launch mdo.exe directly."
         );
     }
+    println!("{APP_DISPLAY_NAME} is registered for Markdown files.");
+    println!("To make it the default, use Open with -> Choose another app -> {APP_DISPLAY_NAME} -> Always.");
 
     Ok(())
 }
 
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
+pub fn install(_set_default: bool) -> io::Result<()> {
+    Err(io::Error::new(
+        io::ErrorKind::Unsupported,
+        "built-in file-manager installation is currently supported on Windows and Linux",
+    ))
+}
+
+#[cfg(target_os = "linux")]
+pub fn uninstall() -> io::Result<()> {
+    let data_home = xdg_data_home()?;
+    let desktop_dir = data_home.join("applications");
+    remove_linux_handler_files(&data_home)?;
+
+    for mimeapps in mimeapps_paths(&data_home) {
+        remove_desktop_from_mimeapps(&mimeapps)?;
+    }
+
+    run_optional("update-desktop-database", &[desktop_dir.as_os_str()]);
+
+    println!("Done.");
+    Ok(())
+}
+
+#[cfg(target_os = "windows")]
+pub fn uninstall() -> io::Result<()> {
+    // Uninstall was already best-effort (every op ignores failures), so this
+    // reduces to applying the plan; `apply_registry_plan` returns `Ok(())`
+    // whenever every op in the plan is best-effort, which is always true here.
+    apply_registry_plan(&uninstall_windows_plan())?;
+    let _ = remove_windows_icon();
+
+    println!("Done.");
+    println!(
+        "If {APP_DISPLAY_NAME} was set as the default handler for .md, Windows will prompt you to pick a new default the next time you open a .md file."
+    );
+    Ok(())
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
+pub fn uninstall() -> io::Result<()> {
+    Err(io::Error::new(
+        io::ErrorKind::Unsupported,
+        "built-in file-manager uninstallation is currently supported on Windows and Linux",
+    ))
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
+pub fn integration_installed() -> bool {
+    false
+}
+
+/// Report whether mdo's own handler registration is present for this user.
+///
+/// This is deliberately a cheap owned-state check (ADR 0004 defers the full
+/// integration-state manager): it only asks "did mdo's install step leave its
+/// own registration behind?" and never inspects handler health, partial or
+/// stale remnants, system-wide registrations, or the effective default app.
+/// A query failure reads as "not detected", so setup falls back to the
+/// ordinary first-time flow — which is safe because install is idempotent.
+#[cfg(target_os = "linux")]
+pub fn integration_installed() -> bool {
+    xdg_data_home()
+        .map(|data_home| linux_integration_installed_at(&data_home))
+        .unwrap_or(false)
+}
+
+#[cfg(target_os = "windows")]
+pub fn integration_installed() -> bool {
+    reg_key_exists(WINDOWS_OWNED_PROGID_COMMAND_KEY)
+}
+
 /// Install the application-menu entry for the native setup launcher.
 ///
-/// This is deliberately separate from [`install_linux_for_exe`]: the latter
+/// This is deliberately separate from the install step above: the latter
 /// owns the hidden Markdown file-handler entry and may be uninstalled without
 /// making setup disappear from the application menu.
 #[cfg(target_os = "linux")]
@@ -153,13 +336,6 @@ fn write_linux_setup_launcher(setup_exe: &Path, data_home: &Path) -> io::Result<
     Ok(desktop_file)
 }
 
-#[cfg(target_os = "linux")]
-fn integration_installed_impl() -> bool {
-    xdg_data_home()
-        .map(|data_home| linux_integration_installed_at(&data_home))
-        .unwrap_or(false)
-}
-
 /// The owned-state check only looks for the mdo-owned handler desktop entry.
 /// The visible `mdo-setup.desktop` launcher has its own lifecycle and does not
 /// count as handler integration.
@@ -171,22 +347,6 @@ fn linux_integration_installed_at(data_home: &Path) -> bool {
         .is_file()
 }
 
-#[cfg(target_os = "linux")]
-fn uninstall_impl() -> io::Result<()> {
-    let data_home = xdg_data_home()?;
-    let desktop_dir = data_home.join("applications");
-    remove_linux_handler_files(&data_home)?;
-
-    for mimeapps in mimeapps_paths(&data_home) {
-        remove_desktop_from_mimeapps(&mimeapps)?;
-    }
-
-    run_optional("update-desktop-database", &[desktop_dir.as_os_str()]);
-
-    println!("Done.");
-    Ok(())
-}
-
 #[cfg(target_os = "linux")]
 fn remove_linux_handler_files(data_home: &Path) -> io::Result<()> {
     let desktop_file = data_home.join("applications").join(DESKTOP_FILE_NAME);
@@ -202,47 +362,6 @@ fn remove_linux_handler_files(data_home: &Path) -> io::Result<()> {
     remove_legacy_nautilus_scripts(data_home)
 }
 
-#[cfg(target_os = "windows")]
-fn install_impl(set_default: bool) -> io::Result<()> {
-    let current_exe = std::env::current_exe()?;
-    install_windows_for_exe(&current_exe, set_default)
-}
-
-#[cfg(target_os = "windows")]
-pub fn install_windows_for_exe(current_exe: &Path, _set_default: bool) -> io::Result<()> {
-    let handler = windows_handler_for(current_exe);
-    let command = windows_registry_command(&handler.path, handler.is_wrapper);
-    let icon_file = install_windows_icon()?;
-    let icon_ref = format!("\"{}\",0", icon_file.display());
-    let current_exe_command = windows_registry_command(current_exe, false);
-
-    // Registry mutation is split into a pure planning step (`install_windows_plan`,
-    // unit-tested below without touching the registry) and a thin executor
-    // (`apply_registry_plan`) that shells out to `reg.exe`. This keeps the
-    // "which keys/values would be written, in what order, with which
-    // failure semantics" logic testable in CI without mutating the real
-    // registry on the CI machine.
-    let plan = install_windows_plan(
-        handler.is_wrapper,
-        &command,
-        &current_exe_command,
-        &icon_ref,
-    );
-    apply_registry_plan(&plan)?;
-
-    println!("Using handler: {}", handler.path.display());
-    println!("Using icon: {}", icon_file.display());
-    if !handler.is_wrapper {
-        println!(
-            "Note: mdo-open.exe was not found next to mdo.exe, so Explorer will launch mdo.exe directly."
-        );
-    }
-    println!("{APP_DISPLAY_NAME} is registered for Markdown files.");
-    println!("To make it the default, use Open with -> Choose another app -> {APP_DISPLAY_NAME} -> Always.");
-
-    Ok(())
-}
-
 /// The single registry key the owned-state check queries: the open command of
 /// mdo's own `mdo.md` ProgID. Install writes it (see [`install_windows_plan`])
 /// and uninstall deletes its parent ProgID key, so its presence tracks exactly
@@ -250,11 +369,6 @@ pub fn install_windows_for_exe(current_exe: &Path, _set_default: bool) -> io::Re
 #[cfg(target_os = "windows")]
 const WINDOWS_OWNED_PROGID_COMMAND_KEY: &str = r"HKCU\Software\Classes\mdo.md\shell\open\command";
 
-#[cfg(target_os = "windows")]
-fn integration_installed_impl() -> bool {
-    reg_key_exists(WINDOWS_OWNED_PROGID_COMMAND_KEY)
-}
-
 #[cfg(target_os = "windows")]
 fn reg_key_exists(key: &str) -> bool {
     Command::new("reg")
@@ -266,42 +380,6 @@ fn reg_key_exists(key: &str) -> bool {
         .unwrap_or(false)
 }
 
-#[cfg(target_os = "windows")]
-fn uninstall_impl() -> io::Result<()> {
-    // Uninstall was already best-effort (every op ignores failures), so this
-    // reduces to applying the plan; `apply_registry_plan` returns `Ok(())`
-    // whenever every op in the plan is best-effort, which is always true here.
-    apply_registry_plan(&uninstall_windows_plan())?;
-    let _ = remove_windows_icon();
-
-    println!("Done.");
-    println!(
-        "If {APP_DISPLAY_NAME} was set as the default handler for .md, Windows will prompt you to pick a new default the next time you open a .md file."
-    );
-    Ok(())
-}
-
-#[cfg(not(any(target_os = "linux", target_os = "windows")))]
-fn install_impl(_set_default: bool) -> io::Result<()> {
-    Err(io::Error::new(
-        io::ErrorKind::Unsupported,
-        "built-in file-manager installation is currently supported on Windows and Linux",
-    ))
-}
-
-#[cfg(not(any(target_os = "linux", target_os = "windows")))]
-fn uninstall_impl() -> io::Result<()> {
-    Err(io::Error::new(
-        io::ErrorKind::Unsupported,
-        "built-in file-manager uninstallation is currently supported on Windows and Linux",
-    ))
-}
-
-#[cfg(not(any(target_os = "linux", target_os = "windows")))]
-fn integration_installed_impl() -> bool {
-    false
-}
-
 #[cfg(target_os = "linux")]
 fn xdg_data_home() -> io::Result<PathBuf> {
     if let Some(value) = std::env::var_os("XDG_DATA_HOME") {
@@ -320,13 +398,16 @@ fn xdg_data_home() -> io::Result<PathBuf> {
 #[cfg(target_os = "linux")]
 fn linux_desktop_entry(exe: &Path) -> String {
     let quoted_exe = quote_desktop_exec_arg(&exe.to_string_lossy());
+    // The Exec line is the handler invocation contract in desktop-entry
+    // spelling: the binary, the contract flags, then the %f file placeholder.
+    let open_flags = handler::OPEN_FLAGS.join(" ");
     format!(
         "[Desktop Entry]\n\
          Type=Application\n\
          Name={APP_DISPLAY_NAME}\n\
          GenericName=Markdown HTML Opener\n\
          Comment=Open Markdown as HTML in the default browser\n\
-         Exec={quoted_exe} --open %f\n\
+         Exec={quoted_exe} {open_flags} %f\n\
          Icon=mdo\n\
          Terminal=false\n\
          NoDisplay=true\n\
@@ -503,26 +584,32 @@ struct WindowsHandler {
 
 #[cfg(target_os = "windows")]
 fn windows_handler_for(current_exe: &Path) -> WindowsHandler {
-    let sibling_wrapper = current_exe.with_file_name("mdo-open.exe");
-    if sibling_wrapper.exists() {
-        WindowsHandler {
-            path: sibling_wrapper,
+    let sibling_wrapper = handler::sibling_binary(current_exe, "mdo-open.exe").ok();
+    match sibling_wrapper {
+        Some(path) => WindowsHandler {
+            path,
             is_wrapper: true,
-        }
-    } else {
-        WindowsHandler {
+        },
+        None => WindowsHandler {
             path: current_exe.to_path_buf(),
             is_wrapper: false,
-        }
+        },
     }
 }
 
 #[cfg(target_os = "windows")]
-fn windows_registry_command(handler: &Path, is_wrapper: bool) -> String {
+fn windows_registry_command(handler_path: &Path, is_wrapper: bool) -> String {
     if is_wrapper {
-        format!("\"{}\" \"%1\"", handler.display())
+        format!("\"{}\" \"%1\"", handler_path.display())
     } else {
-        format!("\"{}\" --open \"%1\"", handler.display())
+        // The registry command is the handler invocation contract in
+        // registry spelling: the binary, the contract flags, then the %1
+        // file placeholder.
+        format!(
+            "\"{}\" {} \"%1\"",
+            handler_path.display(),
+            handler::OPEN_FLAGS.join(" ")
+        )
     }
 }
 
@@ -611,7 +698,7 @@ fn application_registration_ops(exe_name: &str, command: &str, icon_ref: &str) -
     ]
 }
 
-/// Pure planning step for [`install_windows_for_exe`]: given the already
+/// Pure planning step for the install executor below: given the already
 /// pure-computed handler command, current-exe command, and icon reference,
 /// produce the ordered list of registry writes install would perform.
 /// Unit-tested directly (see `windows_tests`) so the composition — which
@@ -679,7 +766,7 @@ fn install_windows_plan(
     ops
 }
 
-/// Pure planning step for [`uninstall_impl`]: every op here is best-effort,
+/// Pure planning step for [`uninstall`]: every op here is best-effort,
 /// matching the original `let _ = reg_delete_*(...)` calls — uninstall
 /// should remove everything it can rather than stop at the first missing
 /// key.
@@ -867,6 +954,104 @@ mod linux_tests {
         );
     }
 
+    #[test]
+    fn linux_install_plan_derives_standard_paths_and_entry_content() {
+        let data_home = Path::new("/home/u/.local/share");
+        let exe = Path::new("/opt/my tools/mdo");
+
+        let plan = linux_install_plan(data_home, exe, true);
+        assert_eq!(
+            plan.desktop_file,
+            data_home.join("applications").join(DESKTOP_FILE_NAME)
+        );
+        assert_eq!(
+            plan.icon_file,
+            data_home
+                .join("icons")
+                .join("hicolor")
+                .join("scalable")
+                .join("apps")
+                .join("mdo.svg")
+        );
+        // The entry content carries the handler invocation contract with the
+        // quoting rules applied (same emitted form the integration registers).
+        assert!(plan
+            .desktop_entry
+            .contains("Exec=\"/opt/my tools/mdo\" --open %f\n"));
+        assert!(plan.set_default);
+        assert_eq!(plan.default_mimes, &["text/markdown", "text/x-markdown"]);
+        assert_eq!(plan.legacy_cleanup_root, Some(data_home.to_path_buf()));
+
+        let plan_without_default = linux_install_plan(data_home, exe, false);
+        assert!(!plan_without_default.set_default);
+    }
+
+    #[test]
+    fn apply_linux_install_plan_writes_entry_and_icon_and_reports() {
+        let dir = std::env::temp_dir().join(format!(
+            "mdo-install-plan-test-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        let exe = dir.join("mdo");
+        fs::create_dir_all(&dir).unwrap();
+
+        let mut plan = linux_install_plan(&dir, &exe, false);
+        // No legacy scripts exist in this fixture; the cleanup would be a
+        // no-op either way (it only removes known files if present).
+        plan.legacy_cleanup_root = None;
+
+        let report = apply_linux_install_plan(&plan).expect("apply should write the registration");
+        assert_eq!(
+            report.default,
+            LinuxDefaultOutcome::NotRequested,
+            "no default was requested"
+        );
+
+        let entry = fs::read_to_string(&report.desktop_file).expect("entry written");
+        assert!(entry.contains("[Desktop Entry]\n"));
+        // The entry content carries the handler invocation contract with the
+        // quoting rules applied (exe path comes from this fixture's anchor).
+        assert!(
+            entry.contains(&format!("Exec=\"{}\" --open %f\n", exe.display())),
+            "entry should carry the contract Exec line: {entry}"
+        );
+        let icon = fs::read_to_string(&report.icon_file).expect("icon written");
+        assert!(icon.contains("<svg"));
+
+        use std::os::unix::fs::PermissionsExt;
+        let mode = fs::metadata(&report.desktop_file)
+            .expect("entry metadata")
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o777, 0o644, "the entry must stay mode 0644");
+
+        fs::remove_dir_all(dir).unwrap();
+    }
+
+    #[test]
+    fn apply_linux_install_plan_requested_default_without_mimes_needs_manual_hint() {
+        // set_default=true with an empty mime list cannot spawn xdg-mime at
+        // all, so the branch is deterministic: the executor must not assume
+        // success just because defaulting was requested.
+        let dir = std::env::temp_dir().join(format!(
+            "mdo-install-plan-hint-test-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        let exe = dir.join("mdo");
+        fs::create_dir_all(&dir).unwrap();
+
+        let mut plan = linux_install_plan(&dir, &exe, true);
+        plan.default_mimes = &[];
+        plan.legacy_cleanup_root = None;
+
+        let report = apply_linux_install_plan(&plan).expect("apply should complete");
+        assert_eq!(report.default, LinuxDefaultOutcome::NeedsManualHint);
+
+        fs::remove_dir_all(dir).unwrap();
+    }
+
     #[test]
     fn setup_launcher_is_visible_and_not_a_file_handler() {
         let entry = linux_setup_desktop_entry(Path::new(r#"/opt/mdo tools/a\b"c$d`e/mdo-setup"#));
@@ -962,12 +1147,55 @@ text/markdown=code.desktop;other.desktop;\n\
 image/png=viewer.desktop;\n"
         );
     }
+
+    /// The desktop Exec line is one of the two emitted forms of the handler
+    /// invocation contract (the other is the Windows registry command): the
+    /// same binary and the same contract flags, derived from the contract
+    /// rather than restated as a literal so the two cannot drift apart.
+    #[test]
+    fn desktop_entry_reflects_the_handler_invocation_contract() {
+        let entry = linux_desktop_entry(Path::new("/opt/mdo/mdo"));
+        let expected = format!(
+            "Exec=\"/opt/mdo/mdo\" {} %f\n",
+            handler::OPEN_FLAGS.join(" ")
+        );
+        assert!(
+            entry.contains(&expected),
+            "entry should carry the contract Exec line: {entry}"
+        );
+
+        // The setup launcher entry is not open-mode: no contract flags.
+        let setup_entry = linux_setup_desktop_entry(Path::new("/usr/bin/mdo-setup"));
+        assert!(!setup_entry.contains(handler::OPEN_FLAGS[0]));
+    }
 }
 
 #[cfg(all(test, target_os = "windows"))]
 mod windows_tests {
     use super::*;
 
+    /// The registry command is one of the two emitted forms of the handler
+    /// invocation contract (the other is the Linux desktop Exec line): it
+    /// must carry the same binary and the same contract flags, derived here
+    /// rather than restated as a literal so the two cannot drift apart.
+    #[test]
+    fn registry_command_reflects_the_handler_invocation_contract() {
+        let command = windows_registry_command(Path::new(r"C:\Tools\mdo.exe"), false);
+        let expected = format!(
+            r#""C:\Tools\mdo.exe" {} "%1""#,
+            handler::OPEN_FLAGS.join(" ")
+        );
+        assert_eq!(command, expected);
+
+        // The forwarding wrapper carries NO flags: it owns the contract
+        // itself and forwards the file as received.
+        let wrapper = windows_registry_command(Path::new(r"C:\Tools\mdo-open.exe"), true);
+        assert_eq!(wrapper, r#""C:\Tools\mdo-open.exe" "%1""#);
+        assert!(!wrapper.contains(handler::OPEN_FLAGS[0]));
+    }
+
+    use super::*;
+
     #[test]
     fn registry_command_uses_open_flag_without_wrapper() {
         let command = windows_registry_command(Path::new(r"C:\Tools\mdo.exe"), false);
diff --git a/src/handler.rs b/src/handler.rs
new file mode 100644
index 0000000..e879228
--- /dev/null
+++ b/src/handler.rs
@@ -0,0 +1,141 @@
+//! The Open-as-HTML handler invocation contract.
+//!
+//! Every platform surface that registers or forwards Open as HTML spells
+//! the same two facts — how a handler launches mdo (`--open` plus the
+//! file), and how mdo's binaries are found beside each other (siblings of
+//! the running executable). This module owns both; the Linux desktop-entry
+//! template, the Windows registry command builders, and the `mdo-open`
+//! forwarding binary are thin adapters consuming them, so a change to the
+//! invocation is made here once and every platform entry stays in step.
+//!
+//! The file argument itself is platform presentation: a `%f` placeholder in
+//! a desktop entry, `%1` in a Windows registry command string, and the real
+//! path when a binary is spawned. Only the argv prefix is the contract.
+
+use std::ffi::OsString;
+use std::io;
+use std::path::{Path, PathBuf};
+
+/// The flags a handler command puts before the file argument when it
+/// launches mdo directly. Spelled once: the desktop-entry template, the
+/// Windows registry command, and the forward binary all consume this, so
+/// the contract cannot drift between the six places that used to repeat it.
+pub const OPEN_FLAGS: &[&str] = &["--open"];
+
+/// The full open-mode argv a handler spawns mdo with: the contract flags
+/// (see [`OPEN_FLAGS`]) followed by the files to open, in order.
+pub fn open_argv(files: &[OsString]) -> Vec<OsString> {
+    let mut argv = Vec::with_capacity(OPEN_FLAGS.len() + files.len());
+    argv.extend(OPEN_FLAGS.iter().map(OsString::from));
+    argv.extend(files.iter().cloned());
+    argv
+}
+
+/// Locate a sibling binary beside the running one (or beside whichever
+/// executable the caller anchors on). This is the one discovery function
+/// and the one error mode for everything mdo ships: the binaries always
+/// run from the same directory.
+///
+/// The error is a `NotFound` io error naming the anchor and the path that
+/// was checked, so callers can print it as-is instead of inventing their
+/// own "not found" story.
+pub fn sibling_binary(exe: &Path, name: &str) -> io::Result<PathBuf> {
+    let parent = exe.parent().ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::NotFound,
+            format!(
+                "no parent directory for {} (looking for {name})",
+                exe.display()
+            ),
+        )
+    })?;
+    let sibling = parent.join(name);
+    if !sibling.is_file() {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            format!(
+                "no {name} found beside {} (looked at {})",
+                exe.display(),
+                sibling.display()
+            ),
+        ));
+    }
+    Ok(sibling)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    fn fixture_dir(name: &str) -> PathBuf {
+        let uuid = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .expect("system time should be after Unix epoch")
+            .as_nanos();
+        let dir = std::env::temp_dir().join(format!(
+            "mdo-handler-test-{name}-{}-{uuid}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&dir).expect("failed to create temp fixture dir");
+        dir
+    }
+
+    #[test]
+    fn open_argv_prepends_the_contract_flags_before_the_files() {
+        let files = vec![OsString::from("notes.md"), OsString::from("todo.md")];
+        let argv = open_argv(&files);
+        let argv: Vec<String> = argv
+            .iter()
+            .map(|arg| arg.to_string_lossy().into_owned())
+            .collect();
+        assert_eq!(argv[0], OPEN_FLAGS[0], "the contract flag comes first");
+        assert_eq!(argv[1..], ["notes.md", "todo.md"]);
+    }
+
+    #[test]
+    fn sibling_binary_resolves_a_real_sibling() {
+        let dir = fixture_dir("resolves");
+        let anchor = dir.join("mdo");
+        fs::write(&anchor, "binary").expect("failed to write anchor fixture");
+        let sibling = dir.join("mdo-open");
+        fs::write(&sibling, "binary").expect("failed to write sibling fixture");
+
+        let found = sibling_binary(&anchor, "mdo-open")
+            .expect("a real sibling beside the anchor should resolve");
+        assert_eq!(found, sibling);
+    }
+
+    #[test]
+    fn sibling_binary_error_names_anchor_and_looked_at_path() {
+        let dir = fixture_dir("missing");
+        let anchor = dir.join("mdo");
+        fs::write(&anchor, "binary").expect("failed to write anchor fixture");
+
+        let err = sibling_binary(&anchor, "mdo-open")
+            .expect_err("a missing sibling is the one error mode");
+        assert_eq!(err.kind(), io::ErrorKind::NotFound);
+        let message = err.to_string();
+        assert!(
+            message.contains(&anchor.display().to_string()),
+            "error should name the anchor: {message}"
+        );
+        assert!(
+            message.contains(&dir.join("mdo-open").display().to_string()),
+            "error should name the path that was checked: {message}"
+        );
+    }
+
+    #[test]
+    fn sibling_binary_rejects_a_directory_named_like_a_binary() {
+        let dir = fixture_dir("not-a-file");
+        let anchor = dir.join("mdo");
+        fs::write(&anchor, "binary").expect("failed to write anchor fixture");
+        let dir_sibling = dir.join("mdo-open");
+        fs::create_dir_all(&dir_sibling).expect("failed to create decoy dir");
+
+        let err =
+            sibling_binary(&anchor, "mdo-open").expect_err("a directory is not a runnable sibling");
+        assert_eq!(err.kind(), io::ErrorKind::NotFound);
+    }
+}
diff --git a/src/launch.rs b/src/launch.rs
new file mode 100644
index 0000000..b2c5ca4
--- /dev/null
+++ b/src/launch.rs
@@ -0,0 +1,102 @@
+//! Launch: browser openers. Non-blocking, fire-and-forget platform
+//! openers plus the xdg-open/gio fallback chain.
+
+use std::io;
+use std::path::Path;
+use std::time::Duration;
+/// Launch the platform's default handler for `path` (typically a web browser
+/// for `.html`). Non-blocking — the spawned process runs independently.
+pub fn launch_browser(path: &Path) -> std::io::Result<()> {
+    #[cfg(target_os = "windows")]
+    {
+        // SECURITY: open via the Win32 ShellExecuteW API (through the `opener`
+        // crate) rather than `cmd /C start`. `start` runs the path through
+        // cmd.exe's command-line parser, so cmd metacharacters (`&`, `^`, …) —
+        // which are legal in Windows filenames and reach us via the input
+        // file's stem in temp_output_for — would be interpreted as commands
+        // (e.g. opening `a&calc&.md` would launch calc.exe). ShellExecuteW
+        // takes the path as a single typed argument, so those characters stay
+        // inert. It is non-blocking, preserving the fire-and-forget behavior.
+        opener::open(path).map_err(io::Error::other)?;
+    }
+    #[cfg(target_os = "macos")]
+    {
+        // `open` returns promptly once Launch Services accepts the request,
+        // so waiting for it doesn't block on the browser itself — and a
+        // nonzero exit (no handler for the file) must surface as a launch
+        // failure rather than being discarded with the child handle.
+        let status = std::process::Command::new("open").arg(path).status()?;
+        if !status.success() {
+            return Err(io::Error::other(format!("open exited with {status}")));
+        }
+    }
+    #[cfg(all(unix, not(target_os = "macos")))]
+    {
+        launch_via_xdg_open(path)?;
+    }
+    Ok(())
+}
+
+/// Open `path` with the first available freedesktop opener. Falls back through
+/// common launchers when `xdg-open` (xdg-utils) is not installed, and reaps the
+/// launcher process in a detached thread so it does not linger as a zombie
+/// during long `--watch` sessions.
+///
+/// Spawning an opener is not the same as launching a browser: `xdg-open` can
+/// exist, start, and then exit nonzero because no browser handler is
+/// configured. We therefore listen for each opener's exit for a short window
+/// — a quick nonzero exit is an honest failure (and we fall through to the
+/// next opener), while an opener still running after the window has almost
+/// certainly handed off (or, in xdg-open's no-desktop fallback, IS the
+/// browser), so we detach and call it success. We never block on the browser
+/// itself beyond that window.
+#[cfg(all(unix, not(target_os = "macos")))]
+fn launch_via_xdg_open(path: &Path) -> std::io::Result<()> {
+    const OPENERS: &[(&str, &[&str])] = &[
+        ("xdg-open", &[]),
+        ("gio", &["open"]),
+        ("gnome-open", &[]),
+        ("kde-open5", &[]),
+        ("kde-open", &[]),
+        ("wslview", &[]),
+    ];
+    const LAUNCH_FAILURE_WINDOW: Duration = Duration::from_secs(2);
+
+    let mut last_failure: Option<String> = None;
+    for (program, leading) in OPENERS {
+        let mut command = std::process::Command::new(program);
+        command.args(*leading).arg(path);
+        let Ok(mut child) = command.spawn() else {
+            continue; // not installed; try the next opener
+        };
+
+        // The waiting thread doubles as the reaper for the detached-success
+        // case: it always waits the child to completion, we just stop
+        // listening for the result after the failure window.
+        let (tx, rx) = std::sync::mpsc::channel();
+        std::thread::spawn(move || {
+            let _ = tx.send(child.wait());
+        });
+
+        match rx.recv_timeout(LAUNCH_FAILURE_WINDOW) {
+            Ok(Ok(status)) if status.success() => return Ok(()),
+            Ok(Ok(status)) => {
+                last_failure = Some(format!("{program} exited with {status}"));
+            }
+            Ok(Err(e)) => {
+                last_failure = Some(format!("failed waiting on {program}: {e}"));
+            }
+            // Still running after the window: it handed off to (or is) the
+            // browser. The waiting thread reaps it eventually.
+            Err(_) => return Ok(()),
+        }
+    }
+
+    match last_failure {
+        Some(failure) => Err(io::Error::other(failure)),
+        None => Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            "no desktop opener found (install xdg-utils)",
+        )),
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 26a262e..45990b4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,34 +1,38 @@
-//! Shared mdo rendering, temp-output, browser launch, and integration helpers.
+//! Shared mdo rendering, watch-mode, temp-output, browser launch, page
+//! assembly, and integration helpers.
+//!
+//! The crate is organized by its four real concerns (names per GLOSSARY.md):
+//! [`render`] (Markdown to fragment plus the deep `convert` workflow),
+//! [`page`] (assets, styles/scripts, document wrapping), [`temp_output`]
+//! (per-source private output locations), and [`launch`] (browser openers).
+//! Each keeps its internals private behind thin public exports re-exported
+//! here, so caller paths do not change when the layout does.
 
-use std::collections::hash_map::DefaultHasher;
-use std::collections::BTreeSet;
-use std::fmt;
 use std::fs;
-use std::hash::{Hash, Hasher};
 use std::io;
-#[cfg(unix)]
-use std::io::Write;
-use std::path::{Path, PathBuf};
-use std::time::{Duration, Instant, UNIX_EPOCH};
-
-#[cfg(unix)]
-use std::fs::OpenOptions;
-#[cfg(unix)]
-use std::os::unix::fs::{DirBuilderExt, MetadataExt, OpenOptionsExt, PermissionsExt};
-
-use pulldown_cmark::Options;
-use url::Url;
+use std::path::PathBuf;
 
 #[cfg(target_os = "android")]
 mod android;
 pub mod file_manager;
+pub mod handler;
 mod highlight;
+pub mod launch;
+pub mod page;
+pub mod render;
+pub mod temp_output;
+pub mod watch;
 #[cfg(target_os = "windows")]
 pub mod windows_setup;
 
-const SIMPLE_CSS: &str = include_str!("../assets/simple.min.css");
-const APP_DISPLAY_NAME: &str = "mdo";
-const APP_VERSION: &str = env!("CARGO_PKG_VERSION");
+use temp_output::{ensure_private_dir, private_temp_root};
+
+pub use launch::launch_browser;
+pub use render::{
+    convert, render_markdown_document, ConvertOutcome, ConvertRequest, RenderError, StageTimings,
+};
+pub use temp_output::temp_output_for;
+
 const SETUP_SAMPLE_FILE_NAME: &str = "welcome-to-open-as-html-with-mdo.md";
 const SETUP_SAMPLE_MARKDOWN: &str = "\
 # Welcome to the world of Open as HTML with mdo
@@ -39,1069 +43,6 @@ opened it successfully.
 Next, right-click any `.md` file and choose **Open as HTML** to read it this way.
 If you make mdo your default Markdown app, a double-click does the same.
 ";
-const UNSAFE_TEMP_OUTPUT_STEM_CHARS: &[char] = &[
-    '&', '^', '%', '(', ')', '!', '"', '\'', '<', '>', '|', ';', '`', '$', '\\', '/', ':',
-];
-
-// mdo keeps simple.css as the base stylesheet but softens the heading/body
-// scale for generated documents. Users who prefer the unmodified vendored
-// simple.css typography can pass assets/restore-simple-css.css with --css.
-const MDO_DEFAULT_TYPOGRAPHY_CSS: &str = include_str!("../assets/mdo-default-typography.css");
-
-// pulldown-cmark emits GFM alerts as blockquotes with a
-// `markdown-alert-{kind}` class. Keep the presentation in the generated
-// document so alerts also work for bare installs with no external assets.
-// The plain `:root` and prefers-color-scheme rules keep alerts styled when
-// JavaScript is disabled (the theme-toggle script never runs, so no
-// data-theme attribute is ever set); the higher-specificity
-// `:root[data-theme=...]` rules then follow the theme toggle rather than the
-// OS preference once a reader has selected a manual theme.
-const GFM_ALERTS_CSS: &str = r#"
-:root{--alert-note:#0969da;--alert-tip:#1a7f37;--alert-important:#8250df;--alert-warning:#9a6700;--alert-caution:#cf222e}
-@media (prefers-color-scheme: dark){:root{--alert-note:#58a6ff;--alert-tip:#3fb950;--alert-important:#a371f7;--alert-warning:#d29922;--alert-caution:#f85149}}
-:root[data-theme="light"]{--alert-note:#0969da;--alert-tip:#1a7f37;--alert-important:#8250df;--alert-warning:#9a6700;--alert-caution:#cf222e}
-:root[data-theme="dark"]{--alert-note:#58a6ff;--alert-tip:#3fb950;--alert-important:#a371f7;--alert-warning:#d29922;--alert-caution:#f85149}
-blockquote[class^="markdown-alert-"]{--alert-color:var(--accent);border-left:.3rem solid var(--alert-color);background:var(--accent-bg);padding:.75rem 1rem}
-blockquote.markdown-alert-note{--alert-color:var(--alert-note)}blockquote.markdown-alert-tip{--alert-color:var(--alert-tip)}blockquote.markdown-alert-important{--alert-color:var(--alert-important)}blockquote.markdown-alert-warning{--alert-color:var(--alert-warning)}blockquote.markdown-alert-caution{--alert-color:var(--alert-caution)}
-"#;
-
-// ─── BEGIN THEME TOGGLE ────────────────────────────────────────────────
-// Self-contained light/dark mode toggle. To remove this feature entirely:
-//   1. Delete this block (down to "END THEME TOGGLE").
-//   2. Delete the `{theme_toggle}` line and `theme_toggle = ...` arg in
-//      `wrap_html5` below.
-// Variable values mirror simple.css's @media (prefers-color-scheme: dark).
-//
-// Behavior notes:
-// - OS theme is detected automatically and tracked live until the user makes
-//   a manual choice; the manual choice persists via localStorage.
-// - localStorage can throw on file:// pages in some browsers/configurations,
-//   so every access is wrapped \u2014 the toggle still works for the current page
-//   even when persistence is unavailable.
-// - An in-memory `manual` flag (not the localStorage read) is the source of
-//   truth for "the user made an explicit choice". It is initialized from the
-//   saved value and set on every toggle click regardless of whether
-//   localStorage.setItem succeeds, so a later prefers-color-scheme change
-//   can never clobber an explicit choice just because persistence failed
-//   (e.g. on file:// pages).
-// - The button is a real <button> (keyboard focusable/activatable) with a
-//   state-aware aria-label.
-// - This <style> block is emitted before the --css override block, so custom
-//   CSS can restyle or hide the toggle (e.g. `#theme-toggle{display:none}`)
-//   and reclaim the reserved narrow-screen padding (`body{padding-top:0}`).
-const THEME_TOGGLE: &str = r#"<style id="mdo-theme-toggle">
-:root[data-theme="light"]{color-scheme:light;--bg:#fff;--accent-bg:#f5f7ff;--text:#212121;--text-light:#585858;--accent:#0d47a1;--accent-hover:#1266e2;--accent-text:var(--bg);--code:#d81b60;--preformatted:#444;--disabled:#efefef}
-:root[data-theme="dark"]{color-scheme:dark;--bg:#212121;--accent-bg:#2b2b2b;--text:#dcdcdc;--text-light:#ababab;--accent:#ffb300;--accent-hover:#ffe099;--accent-text:var(--bg);--code:#f06292;--preformatted:#ccc;--disabled:#111}
-:root[data-theme="dark"] img,:root[data-theme="dark"] video{opacity:.8}
-#theme-toggle{position:fixed;top:.75rem;right:.75rem;z-index:1000;padding:.25rem .6rem;font-size:1rem;line-height:1;cursor:pointer;border-radius:var(--standard-border-radius);border:var(--border-width) solid var(--border);background:var(--accent-bg);color:var(--text)}
-@media (max-width:55rem){body{padding-top:2.75rem}}
-@media print{#theme-toggle{display:none}}
-</style>
-<script>
-(function(){
-  var read=function(){try{return localStorage.getItem('theme')}catch(e){return null}};
-  var apply=function(t){document.documentElement.dataset.theme=t;};
-  var mq=matchMedia('(prefers-color-scheme: dark)');
-  var saved=read();
-  var manual=saved!==null;
-  apply(saved||(mq.matches?'dark':'light'));
-  document.addEventListener('DOMContentLoaded',function(){
-    var b=document.createElement('button');
-    b.id='theme-toggle';b.type='button';
-    var sync=function(){
-      var dark=document.documentElement.dataset.theme==='dark';
-      b.textContent=dark?'\u2600':'\u263E';
-      var label=dark?'Switch to light theme':'Switch to dark theme';
-      b.title=label;
-      b.setAttribute('aria-label',label);
-    };
-    b.onclick=function(){
-      var next=document.documentElement.dataset.theme==='dark'?'light':'dark';
-      apply(next);
-      manual=true;
-      try{localStorage.setItem('theme',next)}catch(e){}
-      sync();
-    };
-    if(mq.addEventListener){
-      mq.addEventListener('change',function(e){
-        if(!manual){apply(e.matches?'dark':'light');sync();}
-      });
-    }
-    document.body.appendChild(b);
-    sync();
-  });
-})();
-</script>
-"#;
-// ─── END THEME TOGGLE ──────────────────────────────────────────────────
-
-/// Stable per-source-path location under a private temp/cache dir, e.g.
-/// `%TEMP%\mdo-<uid>\<hash>\<stem>.html`. Re-opening the same source
-/// overwrites the same file rather than accumulating new ones.
-pub fn temp_output_for(input: &Path) -> io::Result<PathBuf> {
-    let canonical = fs::canonicalize(input).unwrap_or_else(|_| input.to_path_buf());
-    let mut hasher = DefaultHasher::new();
-    canonical.hash(&mut hasher);
-    let hash = hasher.finish();
-
-    let stem = input
-        .file_stem()
-        .and_then(|s| s.to_str())
-        .unwrap_or("document");
-    let stem = sanitize_temp_output_stem(stem);
-
-    let root = private_temp_root();
-    ensure_private_dir(&root)?;
-
-    let source_dir = root.join(format!("{:016x}", hash));
-    ensure_private_dir(&source_dir)?;
-
-    Ok(source_dir.join(format!("{stem}.html")))
-}
-
-fn sanitize_temp_output_stem(stem: &str) -> String {
-    let mut sanitized = String::with_capacity(stem.len());
-
-    for ch in stem.chars() {
-        if ch.is_control() || UNSAFE_TEMP_OUTPUT_STEM_CHARS.contains(&ch) {
-            sanitized.push('_');
-        } else {
-            sanitized.push(ch);
-        }
-    }
-
-    if sanitized.chars().any(|ch| ch != '_') {
-        sanitized
-    } else {
-        "document".to_string()
-    }
-}
-
-fn private_temp_root() -> PathBuf {
-    let mut p = std::env::temp_dir();
-    #[cfg(unix)]
-    p.push(format!("mdo-{}", unsafe { libc::geteuid() }));
-    #[cfg(not(unix))]
-    p.push("mdo");
-    p
-}
-
-#[cfg(unix)]
-fn ensure_private_dir(path: &Path) -> io::Result<()> {
-    match fs::symlink_metadata(path) {
-        Ok(metadata) => {
-            let file_type = metadata.file_type();
-            if file_type.is_symlink() || !file_type.is_dir() {
-                return Err(io::Error::new(
-                    io::ErrorKind::AlreadyExists,
-                    format!("{path:?} exists but is not a directory"),
-                ));
-            }
-
-            let uid = unsafe { libc::geteuid() };
-            if metadata.uid() != uid {
-                return Err(io::Error::new(
-                    io::ErrorKind::PermissionDenied,
-                    format!("{path:?} is not owned by the current user"),
-                ));
-            }
-
-            let mode = metadata.permissions().mode();
-            if mode & 0o077 != 0 {
-                fs::set_permissions(path, fs::Permissions::from_mode(mode & !0o077))?;
-            }
-        }
-        Err(e) if e.kind() == io::ErrorKind::NotFound => {
-            let mut builder = fs::DirBuilder::new();
-            builder.mode(0o700);
-            if let Err(create_error) = builder.create(path) {
-                if create_error.kind() == io::ErrorKind::AlreadyExists {
-                    return ensure_private_dir(path);
-                }
-
-                return Err(create_error);
-            }
-        }
-        Err(e) => return Err(e),
-    }
-
-    Ok(())
-}
-
-#[cfg(not(unix))]
-fn ensure_private_dir(path: &Path) -> io::Result<()> {
-    fs::create_dir_all(path)
-}
-
-/// Build a `file://` URL for a directory, suitable for use as `<base href>`.
-///
-/// Delegates to [`Url::from_directory_path`], which correctly
-/// percent-encodes reserved and non-ASCII characters (spaces, `#`, `%`, `?`,
-/// Unicode, …) and handles Windows drive letters, UNC paths, and the
-/// `\\?\`/`\\?\UNC\` extended-length prefixes that `fs::canonicalize`
-/// produces — a hand-rolled string transform got all of this subtly wrong
-/// (e.g. a literal `#` in a directory name would truncate the URL when a
-/// browser parsed it as a fragment). Always includes a trailing slash so
-/// relative refs resolve correctly against the directory.
-///
-/// Returns `None` if `dir` can't be represented as a `file://` URL (notably:
-/// relative paths). Callers should fall back to omitting the `<base href>`
-/// tag entirely rather than emit a broken URL.
-fn dir_to_file_url(dir: &Path) -> Option<String> {
-    Url::from_directory_path(dir)
-        .ok()
-        .map(|url| url.to_string())
-}
-
-/// Launch the platform's default handler for `path` (typically a web browser
-/// for `.html`). Non-blocking — the spawned process runs independently.
-pub fn launch_browser(path: &Path) -> std::io::Result<()> {
-    #[cfg(target_os = "windows")]
-    {
-        // SECURITY: open via the Win32 ShellExecuteW API (through the `opener`
-        // crate) rather than `cmd /C start`. `start` runs the path through
-        // cmd.exe's command-line parser, so cmd metacharacters (`&`, `^`, …) —
-        // which are legal in Windows filenames and reach us via the input
-        // file's stem in temp_output_for — would be interpreted as commands
-        // (e.g. opening `a&calc&.md` would launch calc.exe). ShellExecuteW
-        // takes the path as a single typed argument, so those characters stay
-        // inert. It is non-blocking, preserving the fire-and-forget behavior.
-        opener::open(path).map_err(io::Error::other)?;
-    }
-    #[cfg(target_os = "macos")]
-    {
-        // `open` returns promptly once Launch Services accepts the request,
-        // so waiting for it doesn't block on the browser itself — and a
-        // nonzero exit (no handler for the file) must surface as a launch
-        // failure rather than being discarded with the child handle.
-        let status = std::process::Command::new("open").arg(path).status()?;
-        if !status.success() {
-            return Err(io::Error::other(format!("open exited with {status}")));
-        }
-    }
-    #[cfg(all(unix, not(target_os = "macos")))]
-    {
-        launch_via_xdg_open(path)?;
-    }
-    Ok(())
-}
-
-/// Open `path` with the first available freedesktop opener. Falls back through
-/// common launchers when `xdg-open` (xdg-utils) is not installed, and reaps the
-/// launcher process in a detached thread so it does not linger as a zombie
-/// during long `--watch` sessions.
-///
-/// Spawning an opener is not the same as launching a browser: `xdg-open` can
-/// exist, start, and then exit nonzero because no browser handler is
-/// configured. We therefore listen for each opener's exit for a short window
-/// — a quick nonzero exit is an honest failure (and we fall through to the
-/// next opener), while an opener still running after the window has almost
-/// certainly handed off (or, in xdg-open's no-desktop fallback, IS the
-/// browser), so we detach and call it success. We never block on the browser
-/// itself beyond that window.
-#[cfg(all(unix, not(target_os = "macos")))]
-fn launch_via_xdg_open(path: &Path) -> std::io::Result<()> {
-    const OPENERS: &[(&str, &[&str])] = &[
-        ("xdg-open", &[]),
-        ("gio", &["open"]),
-        ("gnome-open", &[]),
-        ("kde-open5", &[]),
-        ("kde-open", &[]),
-        ("wslview", &[]),
-    ];
-    const LAUNCH_FAILURE_WINDOW: Duration = Duration::from_secs(2);
-
-    let mut last_failure: Option<String> = None;
-    for (program, leading) in OPENERS {
-        let mut command = std::process::Command::new(program);
-        command.args(*leading).arg(path);
-        let Ok(mut child) = command.spawn() else {
-            continue; // not installed; try the next opener
-        };
-
-        // The waiting thread doubles as the reaper for the detached-success
-        // case: it always waits the child to completion, we just stop
-        // listening for the result after the failure window.
-        let (tx, rx) = std::sync::mpsc::channel();
-        std::thread::spawn(move || {
-            let _ = tx.send(child.wait());
-        });
-
-        match rx.recv_timeout(LAUNCH_FAILURE_WINDOW) {
-            Ok(Ok(status)) if status.success() => return Ok(()),
-            Ok(Ok(status)) => {
-                last_failure = Some(format!("{program} exited with {status}"));
-            }
-            Ok(Err(e)) => {
-                last_failure = Some(format!("failed waiting on {program}: {e}"));
-            }
-            // Still running after the window: it handed off to (or is) the
-            // browser. The waiting thread reaps it eventually.
-            Err(_) => return Ok(()),
-        }
-    }
-
-    match last_failure {
-        Some(failure) => Err(io::Error::other(failure)),
-        None => Err(io::Error::new(
-            io::ErrorKind::NotFound,
-            "no desktop opener found (install xdg-utils)",
-        )),
-    }
-}
-
-fn markdown_options() -> Options {
-    let mut options = Options::empty();
-    options.insert(Options::ENABLE_STRIKETHROUGH);
-    options.insert(Options::ENABLE_TABLES);
-    options.insert(Options::ENABLE_FOOTNOTES);
-    options.insert(Options::ENABLE_TASKLISTS);
-    options.insert(Options::ENABLE_GFM);
-
-    options
-}
-
-fn markdown_to_html(
-    markdown: &str,
-    placeholder_discriminator: u64,
-    plain_fences: &BTreeSet<usize>,
-) -> highlight::RenderedMarkdown {
-    // Front matter is stripped here, before parsing, by the same
-    // `yaml_front_matter` splitter that title derivation uses, so one set of
-    // acceptance rules governs both. Options::ENABLE_YAML_STYLE_METADATA_BLOCKS
-    // is deliberately NOT enabled: pulldown-cmark 0.13 recognizes metadata
-    // blocks anywhere at indent 0, not just at document start, which silently
-    // swallows mid-document text framed by `---` lines.
-    let markdown = yaml_front_matter(markdown)
-        .map(|(_, body)| body)
-        .unwrap_or(markdown);
-
-    highlight::render(
-        markdown,
-        markdown_options(),
-        placeholder_discriminator,
-        plain_fences,
-    )
-}
-
-/// Upper bound on placeholder-collision retries. A collision requires
-/// document text that normalizes into the current placeholder token, so more
-/// than a couple of retries only happens with adversarial input; past the cap
-/// the document renders with highlighting disabled rather than looping.
-const MAX_PLACEHOLDER_RETRIES: u32 = 16;
-
-/// Shared render/process/splice loop behind [`safe_markdown_body`] and
-/// [`convert`].
-///
-/// Highlighted spans are generated by mdo from escaped code text and spliced
-/// into the raw renderer output only after all placeholders have been
-/// validated. `process` (usually ammonia) then handles the completed document,
-/// including generated markup, so no string insertion happens beyond the
-/// sanitizer boundary. The loop is guaranteed to terminate:
-///
-/// - a destroyed placeholder can never survive under any discriminator, so
-///   its fence is added to the strictly growing `plain_fences` set and
-///   rendered as an ordinary escaped code block instead;
-/// - collisions retry with a fresh discriminator at most
-///   [`MAX_PLACEHOLDER_RETRIES`] times, after which every fence is rendered
-///   plain, leaving nothing to splice.
-fn spliced_markdown_body(
-    markdown: &str,
-    mut render: impl FnMut(&str, u64, &BTreeSet<usize>) -> highlight::RenderedMarkdown,
-    mut process: impl FnMut(&str) -> String,
-) -> (String, Option<&'static str>) {
-    let mut discriminator = 0_u64;
-    let mut collision_retries = 0_u32;
-    let mut plain_fences = BTreeSet::new();
-
-    loop {
-        let rendered = render(markdown, discriminator, &plain_fences);
-        match rendered.finish(rendered.raw_html().to_string()) {
-            Ok(body) => return (process(&body), rendered.css()),
-            Err(highlight::SpliceError::Destroyed(fences)) => {
-                plain_fences.extend(fences);
-            }
-            Err(highlight::SpliceError::Collision) => {
-                collision_retries += 1;
-                if collision_retries > MAX_PLACEHOLDER_RETRIES {
-                    plain_fences.extend(0..rendered.fence_count());
-                }
-                discriminator += 1;
-            }
-        }
-    }
-}
-
-/// Render and sanitize Markdown, splicing generated highlighting before the
-/// completed document crosses the sanitizer boundary.
-fn safe_markdown_body(markdown: &str) -> (String, Option<&'static str>) {
-    spliced_markdown_body(markdown, markdown_to_html, sanitize_html)
-}
-
-fn sanitize_html(html: &str) -> String {
-    ammonia::Builder::default()
-        // The global "class" allowance is intentional: user-authored class
-        // names are inert here because classes only select styles from mdo's
-        // own generated stylesheet. Highlight safety does not rest on this
-        // allowlist either: highlighted markup is generated from escaped code
-        // text, spliced before sanitization, and then cleaned with the rest of
-        // the document.
-        .add_generic_attributes(&["class", "id"])
-        .add_tags(&["input"])
-        .add_tag_attributes("input", &["checked", "type"])
-        .add_tag_attribute_values("input", "checked", &[""])
-        .add_tag_attribute_values("input", "type", &["checkbox"])
-        .set_tag_attribute_value("input", "disabled", "")
-        .clean(html)
-        .to_string()
-}
-
-/// Render Markdown supplied in memory as a complete, self-contained HTML page.
-///
-/// This is the platform-neutral entry point used by the Android application.
-/// Raw HTML is always sanitized, matching the safe default of the desktop CLI.
-/// `fallback_title` is used only when the document has no top-level heading.
-pub fn render_markdown_document(
-    markdown: &str,
-    fallback_title: &str,
-    source_modified_unix_secs: Option<u64>,
-) -> String {
-    let (body, highlight_css) = safe_markdown_body(markdown);
-    let title = derive_title(markdown, fallback_title);
-    wrap_html5(
-        &body,
-        &title,
-        None,
-        None,
-        highlight_css,
-        source_modified_unix_secs,
-    )
-}
-
-fn derive_title(markdown: &str, fallback: &str) -> String {
-    if let Some(title) = front_matter_title(markdown) {
-        return title;
-    }
-
-    // A valid metadata block is not document content. Exclude it from the
-    // existing H1 search even when it has no usable title key.
-    let markdown = yaml_front_matter(markdown)
-        .map(|(_, document)| document)
-        .unwrap_or(markdown);
-
-    // Strip fenced code blocks first so a heading — whether an ATX `# ` line or
-    // a raw <h1> — inside a ``` or ~~~ block is never mistaken for the title.
-    let without_fences = strip_code_fences(markdown);
-    for line in without_fences.lines() {
-        let trimmed = line.trim_start();
-        if let Some(rest) = trimmed.trim_end().strip_prefix("# ") {
-            return rest.trim().to_string();
-        }
-    }
-    if let Some(title) = derive_raw_html_h1_title(&without_fences) {
-        return title;
-    }
-    fallback.to_string()
-}
-
-/// Extract a simple scalar `title:` from a complete YAML-style metadata block
-/// at the start of the document.
-///
-/// pulldown-cmark deliberately recognizes the block delimiters without
-/// interpreting YAML. mdo follows that narrow behavior: it reads only an
-/// unindented `title` key and does not add a general-purpose YAML parser (and
-/// its dependency/security surface) merely to title the generated page.
-fn front_matter_title(markdown: &str) -> Option<String> {
-    let (metadata, _) = yaml_front_matter(markdown)?;
-    let mut title = None;
-    for line in metadata.lines() {
-        if line.starts_with(char::is_whitespace) {
-            continue;
-        }
-        if let Some((key, value)) = line.split_once(':') {
-            if key == "title" {
-                let value = unquote_front_matter_scalar(value.trim());
-                if !value.is_empty() {
-                    title = Some(value.to_string());
-                }
-            }
-        }
-    }
-
-    title
-}
-
-/// Split a complete YAML-style metadata block from the document body. The
-/// returned metadata excludes delimiters.
-///
-/// This splitter is the single source of truth for front-matter recognition
-/// (both hiding the block from rendered output and title extraction), and its
-/// acceptance rules are deliberately conservative and GitHub-like:
-///
-/// - the opening `---` must be the very first line of the document;
-/// - the closing delimiter is `---` or `...` on its own line — trailing
-///   spaces are allowed but tabs are not;
-/// - the block must be non-empty and its first line must not be blank.
-///   GitHub and pulldown-cmark both reject blocks whose first content line is
-///   blank, so treating them as front matter here would hide visible content
-///   and let e.g. `---\n\ntitle: fake\n---` spoof the page title.
-fn yaml_front_matter(markdown: &str) -> Option<(&str, &str)> {
-    fn delimiter(line: &str) -> Option<&str> {
-        let line = line.trim_end_matches(['\r', '\n']).trim_end_matches(' ');
-        (line == "---" || line == "...").then_some(line)
-    }
-
-    let first_line_end = markdown.find('\n').unwrap_or(markdown.len());
-    if delimiter(&markdown[..first_line_end]) != Some("---") || first_line_end == markdown.len() {
-        return None;
-    }
-
-    let metadata_start = first_line_end + 1;
-    let remainder = &markdown[metadata_start..];
-    let mut consumed = 0;
-    // split_inclusive also yields a final segment without a trailing newline,
-    // so a closing delimiter at end-of-input is found by the loop as well.
-    for segment in remainder.split_inclusive('\n') {
-        if delimiter(segment).is_some() {
-            let metadata = &remainder[..consumed];
-            let first_content_line = metadata.lines().next()?;
-            if first_content_line.trim().is_empty() {
-                return None;
-            }
-            return Some((metadata, &remainder[consumed + segment.len()..]));
-        }
-        consumed += segment.len();
-    }
-
-    None
-}
-
-fn unquote_front_matter_scalar(value: &str) -> &str {
-    if value.len() < 2 {
-        return value;
-    }
-
-    let bytes = value.as_bytes();
-    if matches!(
-        (bytes[0], bytes[value.len() - 1]),
-        (b'\'', b'\'') | (b'"', b'"')
-    ) {
-        &value[1..value.len() - 1]
-    } else {
-        value
-    }
-}
-
-/// Return `markdown` with fenced code blocks (``` or ~~~) removed, so title
-/// detection never reads inside code samples.
-fn strip_code_fences(markdown: &str) -> String {
-    let mut out = String::with_capacity(markdown.len());
-    let mut fence: Option<char> = None;
-    for line in markdown.lines() {
-        if let Some(marker) = code_fence_marker(line.trim_start()) {
-            match fence {
-                Some(open) if open == marker => fence = None,
-                Some(_) => {}
-                None => fence = Some(marker),
-            }
-            continue;
-        }
-        if fence.is_some() {
-            continue;
-        }
-        out.push_str(line);
-        out.push('\n');
-    }
-    out
-}
-
-/// Detect a code-fence line, returning its marker char when the line starts
-/// with at least three backticks or tildes. This is a pragmatic subset of
-/// CommonMark (it does not bound the indent or require the closing fence to be
-/// at least as long), which is sufficient for title detection.
-fn code_fence_marker(trimmed_start: &str) -> Option<char> {
-    if trimmed_start.starts_with("```") {
-        Some('`')
-    } else if trimmed_start.starts_with("~~~") {
-        Some('~')
-    } else {
-        None
-    }
-}
-
-fn derive_raw_html_h1_title(markdown: &str) -> Option<String> {
-    let lower = markdown.to_ascii_lowercase();
-    let mut search_start = 0;
-
-    while let Some(offset) = lower[search_start..].find("<h1") {
-        let start = search_start + offset;
-        let after_tag_name = start + 3;
-        let next = lower.as_bytes().get(after_tag_name).copied();
-        if !matches!(
-            next,
-            Some(b'>') | Some(b' ') | Some(b'\t') | Some(b'\r') | Some(b'\n')
-        ) {
-            search_start = after_tag_name;
-            continue;
-        }
-
-        let content_start = start + markdown[start..].find('>')? + 1;
-        let content_end = content_start + lower[content_start..].find("</h1>")?;
-        let title = strip_html_tags(&markdown[content_start..content_end])
-            .split_whitespace()
-            .collect::<Vec<_>>()
-            .join(" ");
-        if !title.is_empty() {
-            return Some(title);
-        }
-
-        search_start = content_end + 5;
-    }
-
-    None
-}
-
-fn strip_html_tags(input: &str) -> String {
-    let mut output = String::with_capacity(input.len());
-    let mut in_tag = false;
-
-    for ch in input.chars() {
-        match ch {
-            '<' => in_tag = true,
-            '>' if in_tag => in_tag = false,
-            _ if !in_tag => output.push(ch),
-            _ => {}
-        }
-    }
-
-    output
-}
-
-fn wrap_html5(
-    body: &str,
-    title: &str,
-    base_href: Option<&str>,
-    css_override: Option<&str>,
-    highlight_css: Option<&str>,
-    source_modified_unix_secs: Option<u64>,
-) -> String {
-    // `<base href>` makes relative image/link refs in the rendered HTML resolve
-    // against the *source* directory even when the HTML lives elsewhere
-    // (e.g. when --open writes to %TEMP%). Must come before any element that
-    // references a URL, so we put it first inside <head>.
-    let base_tag = match base_href {
-        Some(href) => format!("<base href=\"{}\">\n", html_escape(href)),
-        None => String::new(),
-    };
-    let css_override_block = css_override
-        .filter(|css| !css.trim().is_empty())
-        .map(|css| {
-            format!(
-                "<style id=\"mdo-css-override\">\n/* Custom CSS from --css */\n{}\n</style>\n",
-                escape_style_end_tags(css)
-            )
-        })
-        .unwrap_or_default();
-    let mdo_default_typography = format!(
-        "<style id=\"mdo-default-typography\">\n{}\n</style>\n",
-        escape_style_end_tags(MDO_DEFAULT_TYPOGRAPHY_CSS)
-    );
-    let highlight_css = highlight_css.unwrap_or_default();
-    // Provenance lives only in <meta name="generator">; the visible page
-    // carries no mdo branding, version, or render timing (v0.6 quiet output).
-    let generator = format!("{APP_DISPLAY_NAME} {APP_VERSION}");
-    // Restrained source-freshness footer: the source file's filesystem
-    // modification time, rendered as UTC with a machine-readable datetime.
-    // The tiny inline script re-formats it in the reader's locale/timezone
-    // when JavaScript is available. Omitted entirely when the timestamp is
-    // missing or unreadable.
-    let source_meta = source_modified_unix_secs
-        .map(|secs| {
-            let machine = utc_datetime_from_unix_secs(secs);
-            let human = human_utc_datetime_from_unix_secs(secs);
-            format!(
-                "<footer class=\"mdo-source-meta\">Source modified: <time datetime=\"{machine}\">{human}</time></footer>\n\
-                 <script>\n\
-                 (function(){{var t=document.querySelector('.mdo-source-meta time');if(!t)return;var d=new Date(t.getAttribute('datetime'));if(isNaN(d))return;try{{t.textContent=d.toLocaleString(undefined,{{year:'numeric',month:'long',day:'numeric',hour:'numeric',minute:'2-digit'}});}}catch(e){{}}}})();\n\
-                 </script>\n",
-                machine = html_escape(&machine),
-                human = html_escape(&human),
-            )
-        })
-        .unwrap_or_default();
-    format!(
-        "<!DOCTYPE html>\n\
-         <html lang=\"en\">\n\
-         <head>\n\
-         <meta charset=\"utf-8\">\n\
-         <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n\
-         <meta name=\"generator\" content=\"{generator}\">\n\
-         {base_tag}\
-         <title>{title}</title>\n\
-         <style>\n{css}\n{gfm_alerts_css}\n{highlight_css}\n.mdo-source-meta{{margin-top:3rem;border:0;padding:1rem 0 1.5rem;font-size:.8rem;line-height:1.4;color:var(--text-light);text-align:center}}\n</style>\n\
-         {theme_toggle}\
-         {mdo_default_typography}\
-         {css_override_block}\
-         </head>\n\
-         <body>\n\
-         <main>\n{body}\n</main>\n\
-         {source_meta}\
-         </body>\n\
-         </html>\n",
-        generator = html_escape(&generator),
-        base_tag = base_tag,
-        title = html_escape(title),
-        css = SIMPLE_CSS,
-        gfm_alerts_css = GFM_ALERTS_CSS,
-        highlight_css = highlight_css,
-        theme_toggle = THEME_TOGGLE, // ← THEME TOGGLE injection point (delete this line to remove)
-        mdo_default_typography = mdo_default_typography,
-        css_override_block = css_override_block,
-        body = body,
-        source_meta = source_meta,
-    )
-}
-
-fn escape_style_end_tags(css: &str) -> String {
-    const STYLE_END_PREFIX: &[u8] = b"</style";
-
-    let mut escaped = String::with_capacity(css.len());
-    let bytes = css.as_bytes();
-    let mut i = 0;
-
-    while i < css.len() {
-        if i + STYLE_END_PREFIX.len() <= css.len()
-            && bytes[i..i + STYLE_END_PREFIX.len()].eq_ignore_ascii_case(STYLE_END_PREFIX)
-        {
-            escaped.push_str("<\\/style");
-            i += STYLE_END_PREFIX.len();
-        } else {
-            let ch = css[i..]
-                .chars()
-                .next()
-                .expect("index should always point at a char boundary");
-            escaped.push(ch);
-            i += ch.len_utf8();
-        }
-    }
-
-    escaped
-}
-
-const MONTH_NAMES: [&str; 12] = [
-    "January",
-    "February",
-    "March",
-    "April",
-    "May",
-    "June",
-    "July",
-    "August",
-    "September",
-    "October",
-    "November",
-    "December",
-];
-
-/// The source file's mtime as seconds since the Unix epoch, or `None` when
-/// the metadata is missing or unreadable (which must never block rendering).
-fn source_modified_unix_secs(input: &Path) -> Option<u64> {
-    fs::metadata(input)
-        .and_then(|metadata| metadata.modified())
-        .ok()
-        .and_then(|mtime| mtime.duration_since(UNIX_EPOCH).ok())
-        .map(|elapsed| elapsed.as_secs())
-}
-
-/// ISO 8601 UTC datetime, e.g. `2026-07-14T17:42:05Z`, for `<time datetime>`.
-fn utc_datetime_from_unix_secs(secs: u64) -> String {
-    let days = (secs / 86_400) as i64;
-    let (year, month, day) = civil_from_days(days);
-    let seconds_of_day = secs % 86_400;
-    let hour = seconds_of_day / 3_600;
-    let minute = (seconds_of_day % 3_600) / 60;
-    let second = seconds_of_day % 60;
-
-    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}Z")
-}
-
-/// Readable UTC fallback text, e.g. `July 14, 2026, 5:42 PM UTC`, shown when
-/// JavaScript cannot re-format the timestamp in the reader's locale.
-fn human_utc_datetime_from_unix_secs(secs: u64) -> String {
-    let days = (secs / 86_400) as i64;
-    let (year, month, day) = civil_from_days(days);
-    let seconds_of_day = secs % 86_400;
-    let hour24 = seconds_of_day / 3_600;
-    let minute = (seconds_of_day % 3_600) / 60;
-    let (hour12, meridiem) = match hour24 {
-        0 => (12, "AM"),
-        1..=11 => (hour24, "AM"),
-        12 => (12, "PM"),
-        _ => (hour24 - 12, "PM"),
-    };
-    let month_name = MONTH_NAMES[(month - 1) as usize];
-
-    format!("{month_name} {day}, {year}, {hour12}:{minute:02} {meridiem} UTC")
-}
-
-fn civil_from_days(days_since_unix_epoch: i64) -> (i64, i64, i64) {
-    // Howard Hinnant's civil-from-days algorithm, shifted for Unix epoch days.
-    let z = days_since_unix_epoch + 719_468;
-    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
-    let doe = z - era * 146_097;
-    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
-    let y = yoe + era * 400;
-    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
-    let mp = (5 * doy + 2) / 153;
-    let day = doy - (153 * mp + 2) / 5 + 1;
-    let month = mp + if mp < 10 { 3 } else { -9 };
-    let year = y + if month <= 2 { 1 } else { 0 };
-
-    (year, month, day)
-}
-
-fn html_escape(s: &str) -> String {
-    s.replace('&', "&amp;")
-        .replace('<', "&lt;")
-        .replace('>', "&gt;")
-        .replace('"', "&quot;")
-}
-
-/// Wall-clock time spent in each stage of one render workflow, plus the
-/// workflow's total. Reported to stderr by the CLI's `--verbose` output.
-/// Stages that do not run for a given invocation (`sanitize` under
-/// `--unsafe-html`, `assemble` under `--bare`) report zero.
-#[derive(Debug, Default)]
-pub struct StageTimings {
-    pub read: Duration,
-    pub markdown: Duration,
-    pub sanitize: Duration,
-    pub assemble: Duration,
-    pub write: Duration,
-    /// Wall-clock time of the whole workflow, always at least the sum of
-    /// the stages.
-    pub total: Duration,
-}
-
-/// One render request for [`convert`]: a Markdown input, a destination, and
-/// the render options. `verbose` is deliberately absent — diagnostics are
-/// the caller's presentation concern, and [`ConvertOutcome::timings`]
-/// carries everything a caller needs to print them.
-#[derive(Debug)]
-pub struct ConvertRequest<'a> {
-    /// The Markdown source file.
-    pub input: &'a Path,
-    /// The HTML file to write; created when missing, overwritten when
-    /// present.
-    pub output: &'a Path,
-    /// Emit only the HTML fragment (no `<html>`, `<head>`, `<body>`, no CSS).
-    pub bare: bool,
-    /// Preserve raw HTML from the Markdown source instead of sanitizing it.
-    pub unsafe_html: bool,
-    /// Write the output file readable only by the current user.
-    pub private_output: bool,
-    /// Custom CSS appended after mdo's default styling. Read from disk here
-    /// and ignored under `bare`, because bare output emits no CSS.
-    pub css_override: Option<&'a Path>,
-}
-
-/// What a successful [`convert`] wrote: the output file plus the workflow's
-/// stage-by-stage timing record.
-#[derive(Debug)]
-pub struct ConvertOutcome {
-    /// The output file that was written.
-    pub output: PathBuf,
-    /// Wall-clock timing record for the completed workflow.
-    pub timings: StageTimings,
-}
-
-/// Why a [`convert`] workflow failed, typed per failure site with the
-/// underlying `io::Error` and the path it concerns, so callers keep printing
-/// their own messages instead of the library doing it for them.
-#[derive(Debug)]
-pub enum RenderError {
-    /// Reading the Markdown input file failed.
-    Read { path: PathBuf, source: io::Error },
-    /// Reading the `--css` override file failed.
-    ReadCssOverride { path: PathBuf, source: io::Error },
-    /// Creating the output file's parent directory failed.
-    CreateOutputDir { path: PathBuf, source: io::Error },
-    /// Writing the rendered HTML file failed.
-    Write { path: PathBuf, source: io::Error },
-}
-
-impl fmt::Display for RenderError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let (action, path, source) = match self {
-            RenderError::Read { path, source } => ("failed to read", path, source),
-            RenderError::ReadCssOverride { path, source } => {
-                ("failed to read CSS override", path, source)
-            }
-            RenderError::CreateOutputDir { path, source } => ("failed to create", path, source),
-            RenderError::Write { path, source } => ("failed to write", path, source),
-        };
-        write!(f, "{} {}: {}", action, path.display(), source)
-    }
-}
-
-impl std::error::Error for RenderError {
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        Some(match self {
-            RenderError::Read { source, .. }
-            | RenderError::ReadCssOverride { source, .. }
-            | RenderError::CreateOutputDir { source, .. }
-            | RenderError::Write { source, .. } => source,
-        })
-    }
-}
-
-/// Render one Markdown file to HTML: the render pipeline's single deep
-/// entry point.
-///
-/// The workflow: read the source (and any CSS override), render and splice
-/// highlighting, sanitize (unless `unsafe_html`), assemble the page (unless
-/// `bare`), create the output's parent directory when missing, then write
-/// the file (O_NOFOLLOW, mode 0o600 under `private_output`). The workflow
-/// prints nothing itself — success carries a [`ConvertOutcome`] with the
-/// written file and timing record, failure a typed [`RenderError`] — so the
-/// same workflow serves the CLI, the setup sample, and any other host, and
-/// the generated HTML is byte-identical everywhere it is invoked from.
-pub fn convert(request: ConvertRequest) -> Result<ConvertOutcome, RenderError> {
-    let workflow_start = Instant::now();
-    let mut timings = StageTimings::default();
-
-    let stage_start = Instant::now();
-    let markdown = fs::read_to_string(request.input).map_err(|source| RenderError::Read {
-        path: request.input.to_path_buf(),
-        source,
-    })?;
-    timings.read = stage_start.elapsed();
-
-    let css_override = if request.bare {
-        None
-    } else {
-        match request.css_override {
-            Some(path) => {
-                let stage_start = Instant::now();
-                let css =
-                    fs::read_to_string(path).map_err(|source| RenderError::ReadCssOverride {
-                        path: path.to_path_buf(),
-                        source,
-                    })?;
-                timings.read += stage_start.elapsed();
-                Some(css)
-            }
-            None => None,
-        }
-    };
-
-    // Same splice loop as `safe_markdown_body`, instrumented for the
-    // outcome's timing record.
-    let (body, highlight_css) = spliced_markdown_body(
-        &markdown,
-        |markdown, discriminator, plain_fences| {
-            let stage_start = Instant::now();
-            let rendered = markdown_to_html(markdown, discriminator, plain_fences);
-            timings.markdown += stage_start.elapsed();
-            rendered
-        },
-        |html| {
-            if request.unsafe_html {
-                html.to_string()
-            } else {
-                let sanitize_start = Instant::now();
-                let sanitized = sanitize_html(html);
-                timings.sanitize += sanitize_start.elapsed();
-                sanitized
-            }
-        },
-    );
-
-    let final_html = if request.bare {
-        body
-    } else {
-        let stage_start = Instant::now();
-        let fallback = request
-            .input
-            .file_stem()
-            .and_then(|s| s.to_str())
-            .unwrap_or("Document");
-        let title = derive_title(&markdown, fallback);
-
-        // Only inject <base href> when the output lives in a different
-        // directory from the source — otherwise relative refs already
-        // resolve correctly and a base tag would just add noise.
-        let base_href = match (
-            fs::canonicalize(request.input)
-                .ok()
-                .and_then(|p| p.parent().map(Path::to_path_buf)),
-            request
-                .output
-                .parent()
-                .and_then(|p| fs::canonicalize(p).ok()),
-        ) {
-            (Some(in_dir), Some(out_dir)) if in_dir != out_dir => dir_to_file_url(&in_dir),
-            _ => None,
-        };
-
-        let wrapped = wrap_html5(
-            &body,
-            &title,
-            base_href.as_deref(),
-            css_override.as_deref(),
-            highlight_css,
-            source_modified_unix_secs(request.input),
-        );
-        timings.assemble = stage_start.elapsed();
-        wrapped
-    };
-
-    let stage_start = Instant::now();
-    if let Some(parent) = request.output.parent() {
-        if !parent.as_os_str().is_empty() {
-            fs::create_dir_all(parent).map_err(|source| RenderError::CreateOutputDir {
-                path: parent.to_path_buf(),
-                source,
-            })?;
-        }
-    }
-
-    write_output_file(request.output, &final_html, request.private_output).map_err(|source| {
-        RenderError::Write {
-            path: request.output.to_path_buf(),
-            source,
-        }
-    })?;
-    timings.write = stage_start.elapsed();
-    timings.total = workflow_start.elapsed();
-
-    Ok(ConvertOutcome {
-        output: request.output.to_path_buf(),
-        timings,
-    })
-}
-
-#[cfg(unix)]
-fn write_output_file(output: &Path, contents: &str, private_output: bool) -> io::Result<()> {
-    let mut options = OpenOptions::new();
-    options
-        .write(true)
-        .create(true)
-        .truncate(true)
-        .custom_flags(libc::O_NOFOLLOW);
-
-    if private_output {
-        options.mode(0o600);
-    }
-
-    let mut file = options.open(output)?;
-    file.write_all(contents.as_bytes())
-}
-
-#[cfg(not(unix))]
-fn write_output_file(output: &Path, contents: &str, _private_output: bool) -> io::Result<()> {
-    fs::write(output, contents)
-}
 
 pub fn open_setup_sample() -> io::Result<()> {
     let source = setup_sample_input_path()?;
@@ -1130,563 +71,9 @@ fn setup_sample_input_path() -> io::Result<PathBuf> {
     ensure_private_dir(&dir)?;
     Ok(dir.join(SETUP_SAMPLE_FILE_NAME))
 }
-
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::sync::atomic::{AtomicU64, Ordering};
-    use std::time::SystemTime;
-
-    static NEXT_TEMP_FIXTURE_ID: AtomicU64 = AtomicU64::new(0);
-
-    fn rendered_markdown_html(markdown: &str) -> String {
-        let rendered = markdown_to_html(markdown, 0, &BTreeSet::new());
-        rendered
-            .finish(rendered.raw_html().to_string())
-            .expect("unsanitized renderer should preserve its unique placeholders")
-    }
-
-    #[test]
-    fn temp_output_stem_replaces_shell_metacharacters() {
-        let input = unique_temp_input("a&calc&.md");
-        let output = temp_output_for(&input).expect("temp path should be built");
-        let file_name = output
-            .file_name()
-            .and_then(|s| s.to_str())
-            .expect("temp path should end with unicode filename");
-
-        assert_eq!(file_name, "a_calc_.html");
-        assert!(!file_name.contains('&'));
-
-        cleanup_temp_fixture(&input, &output);
-    }
-
-    #[test]
-    fn temp_output_stem_keeps_readable_normal_names() {
-        let input = unique_temp_input("résumé-draft_2026.md");
-        let output = temp_output_for(&input).expect("temp path should be built");
-        let file_name = output
-            .file_name()
-            .and_then(|s| s.to_str())
-            .expect("temp path should end with unicode filename");
-
-        assert_eq!(file_name, "résumé-draft_2026.html");
-
-        cleanup_temp_fixture(&input, &output);
-    }
-
-    fn unique_temp_input(file_name: &str) -> PathBuf {
-        let nonce = SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .expect("system time should be after epoch")
-            .as_nanos();
-        let counter = NEXT_TEMP_FIXTURE_ID.fetch_add(1, Ordering::Relaxed);
-        let dir = std::env::temp_dir().join(format!(
-            "mdo-unit-test-{}-{nonce}-{counter}",
-            std::process::id()
-        ));
-        fs::create_dir_all(&dir).expect("test temp dir should be created");
-        let input = dir.join(file_name);
-        fs::write(&input, "# Test\n").expect("test input should be written");
-        input
-    }
-
-    fn cleanup_temp_fixture(input: &Path, output: &Path) {
-        if let Some(parent) = output.parent() {
-            let _ = fs::remove_dir_all(parent);
-        }
-        if let Some(parent) = input.parent() {
-            let _ = fs::remove_dir_all(parent);
-        }
-    }
-
-    #[test]
-    fn formats_unix_timestamps_as_machine_utc_datetimes() {
-        assert_eq!(utc_datetime_from_unix_secs(0), "1970-01-01T00:00:00Z");
-        assert_eq!(
-            utc_datetime_from_unix_secs(951_827_696),
-            "2000-02-29T12:34:56Z"
-        );
-    }
-
-    #[test]
-    fn formats_unix_timestamps_as_readable_utc_datetimes() {
-        // Midnight and noon exercise the 12-hour AM/PM edge cases.
-        assert_eq!(
-            human_utc_datetime_from_unix_secs(0),
-            "January 1, 1970, 12:00 AM UTC"
-        );
-        assert_eq!(
-            human_utc_datetime_from_unix_secs(951_827_696),
-            "February 29, 2000, 12:34 PM UTC"
-        );
-        assert_eq!(
-            human_utc_datetime_from_unix_secs(13 * 3_600 + 5 * 60),
-            "January 1, 1970, 1:05 PM UTC"
-        );
-    }
-
-    #[test]
-    fn wrap_html5_keeps_generator_meta_without_visible_branding() {
-        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, Some(0));
-
-        assert!(html.contains(&format!(
-            "<meta name=\"generator\" content=\"mdo {APP_VERSION}\">"
-        )));
-        assert!(!html.contains("Generated by"));
-        assert!(!html.contains("mdo-generated"));
-    }
-
-    #[test]
-    fn wrap_html5_shows_source_modified_time_with_machine_datetime() {
-        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, Some(951_827_696));
-
-        assert!(html.contains(
-            "<footer class=\"mdo-source-meta\">Source modified: \
-             <time datetime=\"2000-02-29T12:34:56Z\">February 29, 2000, 12:34 PM UTC</time></footer>"
-        ));
-    }
-
-    #[test]
-    fn wrap_html5_renders_without_source_modified_time() {
-        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, None);
-
-        assert!(html.contains("<main>\n<p>hi</p>\n</main>"));
-        assert!(!html.contains("Source modified"));
-        assert!(!html.contains("<footer"));
-    }
-
-    #[test]
-    fn in_memory_render_uses_shared_safe_document_pipeline() {
-        let html = render_markdown_document(
-            "# Phone note\n\nHello **Android**.\n\n<script>alert('no')</script>",
-            "fallback.md",
-            None,
-        );
-
-        assert!(html.contains("<title>Phone note</title>"));
-        assert!(html.contains("<strong>Android</strong>"));
-        assert!(html.contains("<meta name=\"generator\" content=\"mdo "));
-        assert!(!html.contains("<script>alert('no')</script>"));
-    }
-
-    #[test]
-    fn markdown_extensions_keep_their_existing_html() {
-        let markdown = "~~gone~~\n\n\
-                        | A | B |\n\
-                        | - | - |\n\
-                        | 1 | 2 |\n\n\
-                        Footnote[^one].\n\n\
-                        [^one]: Detail\n\n\
-                        - [x] done\n\
-                        - [ ] later\n";
-        let expected = "<p><del>gone</del></p>\n\
-                        <table><thead><tr><th>A</th><th>B</th></tr></thead><tbody>\n\
-                        <tr><td>1</td><td>2</td></tr>\n\
-                        </tbody></table>\n\
-                        <p>Footnote<sup class=\"footnote-reference\"><a href=\"#one\">1</a></sup>.</p>\n\
-                        <div class=\"footnote-definition\" id=\"one\"><sup class=\"footnote-definition-label\">1</sup>\n\
-                        <p>Detail</p>\n\
-                        </div>\n\
-                        <ul>\n\
-                        <li><input disabled=\"\" type=\"checkbox\" checked=\"\"/>\n\
-                        done</li>\n\
-                        <li><input disabled=\"\" type=\"checkbox\"/>\n\
-                        later</li>\n\
-                        </ul>\n";
-
-        assert_eq!(rendered_markdown_html(markdown), expected);
-    }
-
-    #[test]
-    fn gfm_alerts_render_all_supported_classes_and_survive_sanitizing() {
-        for kind in ["note", "tip", "important", "warning", "caution"] {
-            let markdown = format!("> [!{}]\n> Alert text\n", kind.to_uppercase());
-            let raw = rendered_markdown_html(&markdown);
-            let class = format!("class=\"markdown-alert-{kind}\"");
-
-            assert!(raw.contains(&class), "{raw}");
-            assert!(!raw.contains("[!"), "{raw}");
-            assert!(sanitize_html(&raw).contains(&class), "{raw}");
-        }
-    }
-
-    #[test]
-    fn wrapped_document_styles_alerts_in_light_and_dark_palettes() {
-        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, None);
-
-        // No-JS defaults: plain :root plus an OS dark-mode media query, so
-        // alerts stay styled when the theme-toggle script never runs.
-        assert!(html.contains("\n:root{--alert-note:"));
-        assert!(html.contains("@media (prefers-color-scheme: dark){:root{--alert-note:"));
-        // Manual theme-toggle overrides.
-        assert!(html.contains(":root[data-theme=\"light\"]{--alert-note:"));
-        assert!(html.contains(":root[data-theme=\"dark\"]{--alert-note:"));
-        for kind in ["note", "tip", "important", "warning", "caution"] {
-            assert!(html.contains(&format!("blockquote.markdown-alert-{kind}")));
-        }
-    }
-
-    #[test]
-    fn yaml_front_matter_is_hidden_and_supplies_document_title() {
-        let markdown =
-            "---\ntitle: 'Front Matter Title'\nauthor: Example\n...\n\n# Heading Title\n";
-        let body = rendered_markdown_html(markdown);
-
-        assert_eq!(body, "<h1>Heading Title</h1>\n");
-        assert_eq!(derive_title(markdown, "fallback"), "Front Matter Title");
-
-        let document = render_markdown_document(markdown, "fallback", None);
-        assert!(document.contains("<title>Front Matter Title</title>"));
-        assert!(!document.contains("author: Example"));
-    }
-
-    #[test]
-    fn mid_document_metadata_style_blocks_are_rendered_not_swallowed() {
-        let markdown = "# Top\n\nintro\n\n---\nnot a heading\n---\n\ntail\n";
-        let html = rendered_markdown_html(markdown);
-
-        assert!(html.contains("not a heading"), "{html}");
-        assert!(html.contains("tail"), "{html}");
-        assert_eq!(derive_title(markdown, "fallback"), "Top");
-    }
-
-    #[test]
-    fn blank_first_line_block_is_not_front_matter() {
-        // GitHub and pulldown-cmark reject metadata blocks whose first content
-        // line is blank; accepting one here would hide visible text and let it
-        // spoof the page title.
-        let markdown = "---\n\ntitle: fake\n---\n\n# Real Heading\n";
-        let html = rendered_markdown_html(markdown);
-
-        assert!(html.contains("title: fake"), "{html}");
-        assert_eq!(derive_title(markdown, "fallback"), "Real Heading");
-
-        // An empty block is likewise not front matter.
-        assert!(yaml_front_matter("---\n---\n# Heading\n").is_none());
-    }
-
-    #[test]
-    fn front_matter_title_supports_colons_and_double_quotes() {
-        let markdown = "---\ntitle: \"Project: Alpha\"\n---\n\n# Heading\n";
-        assert_eq!(derive_title(markdown, "fallback"), "Project: Alpha");
-    }
-
-    #[test]
-    fn missing_empty_or_unclosed_front_matter_title_uses_existing_fallbacks() {
-        assert_eq!(
-            derive_title("---\nauthor: Example\n---\n\n# Heading\n", "fallback"),
-            "Heading"
-        );
-        assert_eq!(
-            derive_title("---\ntitle: \n---\n", "Fallback Title"),
-            "Fallback Title"
-        );
-        assert_eq!(
-            derive_title("---\ntitle: Incomplete\n# Real Heading\n", "fallback"),
-            "Real Heading"
-        );
-        assert_eq!(
-            derive_title(
-                "---\ndescription: |\n# Metadata, not a heading\n---\n\n# Real Heading\n",
-                "fallback"
-            ),
-            "Real Heading"
-        );
-    }
-
-    #[test]
-    fn smart_punctuation_is_not_enabled() {
-        let html = rendered_markdown_html("-- --- ... \"straight\" 'quotes'\n");
-
-        assert_eq!(html, "<p>-- --- ... \"straight\" 'quotes'</p>\n");
-        assert!(!html.contains(['–', '—', '…', '“', '”', '‘', '’']));
-    }
-
-    #[test]
-    fn recognized_fences_are_highlighted_with_both_theme_palettes() {
-        let markdown = "```rust\nfn main() { let html = \"<script>x</script>\"; }\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert!(html.contains(
-            "<pre class=\"mdo-highlight mdo-syntect-code\"><code class=\"language-rust\">"
-        ));
-        assert!(html.contains("mdo-syntect-keyword"), "{html}");
-        assert!(html.contains(":root[data-theme=\"light\"] .mdo-syntect-code"));
-        assert!(html.contains(":root[data-theme=\"dark\"] .mdo-syntect-code"));
-        assert!(!html.contains("<script>x</script>"));
-        assert!(html.contains("&lt;script&gt;"));
-    }
-
-    #[test]
-    fn unknown_fences_remain_plain_and_do_not_add_theme_css() {
-        let markdown = "```not-a-real-language\n<unsafe> & plain\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert!(html.contains(
-            "<pre><code class=\"language-not-a-real-language\">&lt;unsafe&gt; &amp; plain\n</code></pre>"
-        ));
-        assert!(!html.contains("mdo-highlight"));
-        assert!(!html.contains("Syntax highlighting generated by syntect"));
-    }
-
-    #[test]
-    fn pages_without_code_do_not_add_highlight_css() {
-        let html = render_markdown_document("# Just prose\n", "fallback", None);
-        assert!(!html.contains("Syntax highlighting generated by syntect"));
-        assert!(!html.contains("mdo-syntect-"));
-
-        let unlabeled = render_markdown_document("```\nplain code\n```\n", "fallback", None);
-        assert!(unlabeled.contains("<pre><code>plain code\n</code></pre>"));
-        assert!(!unlabeled.contains("Syntax highlighting generated by syntect"));
-    }
-
-    #[test]
-    fn literal_placeholder_spoof_does_not_capture_generated_markup() {
-        let spoof = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
-        let markdown = format!("`{spoof}`\n\n```rust\nlet answer = 42;\n```\n");
-        let html = render_markdown_document(&markdown, "fallback", None);
-
-        assert!(html.contains(spoof));
-        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
-        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
-    }
-
-    #[test]
-    fn entity_normalized_placeholder_spoof_cannot_capture_generated_markup() {
-        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
-        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
-        let markdown = format!("{encoded}\n\n```rust\nlet answer = 42;\n```\n");
-        let html = render_markdown_document(&markdown, "fallback", None);
-
-        assert!(html.contains(normalized), "{html}");
-        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
-        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
-    }
-
-    #[test]
-    fn attribute_normalized_placeholder_cannot_receive_generated_markup() {
-        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
-        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
-        let markdown = format!(
-            "<span title=\"{encoded}\">probe</span>\n\n```rust\nlet one = 1;\n```\n\n```python\nprint(2)\n```\n"
-        );
-        let html = render_markdown_document(&markdown, "fallback", None);
-
-        assert!(html.contains(&format!("title=\"{normalized}\"")), "{html}");
-        assert!(!html.contains("title=\"<pre"), "{html}");
-        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 2);
-        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
-        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_1__"));
-    }
-
-    #[test]
-    fn normalized_spoof_cannot_mask_a_sanitizer_destroyed_placeholder() {
-        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
-        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
-        let markdown = format!(
-            "<span title=\"{encoded}\">probe</span>\n\n<style>\n\n```rust\nfn main() {{}}\n```\n"
-        );
-        let html = render_markdown_document(&markdown, "fallback", None);
-
-        assert!(html.contains(&format!("title=\"{normalized}\"")), "{html}");
-        assert!(!html.contains("title=\"<pre"), "{html}");
-        assert!(!html.contains("<pre class=\"mdo-highlight "), "{html}");
-        assert!(!html.contains("<code class=\"language-rust\""), "{html}");
-    }
-
-    #[test]
-    fn unclosed_style_before_fence_terminates_without_post_sanitize_splice() {
-        // Inline `<style>` never closes, so ammonia swallows and strips all
-        // subsequent markup. Highlight splicing happens before that single
-        // sanitizer pass, so this terminates without a placeholder retry.
-        let markdown = "before <style> after\n\n```rust\nfn main() {}\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert!(html.contains("before"));
-        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
-        assert!(!html.contains("mdo-highlight"));
-    }
-
-    #[test]
-    fn unclosed_script_before_fence_terminates_without_post_sanitize_splice() {
-        let markdown = "before <script> after\n\n```rust\nfn main() {}\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert!(html.contains("before"));
-        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
-        assert!(!html.contains("mdo-highlight"));
-    }
-
-    #[test]
-    fn sanitizer_drops_only_highlight_markup_after_unclosed_style() {
-        // The first fence precedes the unclosed <style>, so its generated
-        // markup survives sanitization. Only the second fence is swallowed.
-        let markdown =
-            "```rust\nlet first = 1;\n```\n\ntext <style> text\n\n```rust\nlet second = 2;\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
-        assert!(html.contains("let"), "{html}");
-        assert!(html.contains("first"), "{html}");
-        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
-    }
-
-    #[test]
-    fn multiple_highlighted_blocks_splice_once_each() {
-        let markdown = "```rust\nlet one = 1;\n```\n\n```python\nprint(2)\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 2);
-        assert!(html.contains("language-rust"));
-        assert!(html.contains("language-python"));
-        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
-    }
-
-    #[test]
-    fn raw_user_html_still_crosses_the_ammonia_boundary() {
-        let markdown = "<div onclick=\"alert(1)\"><script>bad()</script><span class=\"mdo-syntect-keyword\">user</span></div>\n\n```rust\nlet safe = \"<b>code</b>\";\n```\n";
-        let html = render_markdown_document(markdown, "fallback", None);
-
-        assert!(!html.contains("onclick=\"alert(1)\""));
-        assert!(!html.contains("<script>bad()</script>"));
-        assert!(html.contains(">user</span>"));
-        assert!(!html.contains("<b>code</b>"));
-        assert!(html.contains("&lt;b&gt;"));
-    }
-
-    #[test]
-    fn title_can_come_from_raw_html_h1() {
-        let title = derive_title(
-            r#"<section><h1 class="hero-title">Project <span>Home</span></h1></section>"#,
-            "fallback",
-        );
-
-        assert_eq!(title, "Project Home");
-    }
-
-    #[test]
-    fn derive_title_ignores_headings_in_code_fences() {
-        let markdown = "```sh\n# not a title\n```\n\n# Real Title\n";
-        assert_eq!(derive_title(markdown, "fallback"), "Real Title");
-    }
-
-    #[test]
-    fn derive_title_falls_back_when_only_heading_is_fenced() {
-        let markdown = "~~~\n# fenced heading\n~~~\n";
-        assert_eq!(derive_title(markdown, "Fallback Title"), "Fallback Title");
-    }
-
-    #[test]
-    fn derive_title_ignores_raw_html_h1_inside_code_fence() {
-        let markdown = "```html\n<h1>Not the title</h1>\n```\n\n# Real Title\n";
-        assert_eq!(derive_title(markdown, "fallback"), "Real Title");
-    }
-
-    #[test]
-    fn css_override_escapes_style_end_tags() {
-        let escaped = escape_style_end_tags("h1{} </STYLE><script>alert(1)</script>");
-
-        assert!(escaped.contains("<\\/style><script>"));
-        assert!(!escaped.to_ascii_lowercase().contains("</style><script>"));
-    }
-
-    // Unix-rooted paths like `/home/user/...` are NOT absolute on Windows
-    // (no drive or UNC prefix), so `Url::from_directory_path` rejects them
-    // there — every test using such a path must be `#[cfg(unix)]`-gated or
-    // it panics under the Windows CI test job. Windows path forms get their
-    // own `#[cfg(windows)]` tests below.
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_adds_trailing_slash() {
-        let url =
-            dir_to_file_url(Path::new("/home/user/docs")).expect("absolute path should convert");
-        assert!(url.ends_with('/'));
-        assert_eq!(url, "file:///home/user/docs/");
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_spaces() {
-        let url = dir_to_file_url(Path::new("/home/user/my docs")).expect("should convert");
-        assert_eq!(url, "file:///home/user/my%20docs/");
-    }
-
-    // `#` is a legal Windows filename character but is not exercised there
-    // because these are pure-path conversions, not filesystem operations —
-    // gating still keeps the Windows suite focused on Windows-specific forms
-    // (drive letters, UNC, `\\?\`) covered below.
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_hash() {
-        let url = dir_to_file_url(Path::new("/home/user/docs#1")).expect("should convert");
-        assert_eq!(url, "file:///home/user/docs%231/");
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_percent() {
-        let url = dir_to_file_url(Path::new("/home/user/50%done")).expect("should convert");
-        assert_eq!(url, "file:///home/user/50%25done/");
-    }
-
-    // `?` is invalid in Windows filenames, so this case can't arise there.
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_question_mark() {
-        let url = dir_to_file_url(Path::new("/home/user/docs?draft")).expect("should convert");
-        assert_eq!(url, "file:///home/user/docs%3Fdraft/");
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_unicode_accented() {
-        let url = dir_to_file_url(Path::new("/home/user/résumé")).expect("should convert");
-        assert_eq!(url, "file:///home/user/r%C3%A9sum%C3%A9/");
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn dir_to_file_url_encodes_unicode_cjk() {
-        let url = dir_to_file_url(Path::new("/home/user/日本語")).expect("should convert");
-        assert_eq!(url, "file:///home/user/%E6%97%A5%E6%9C%AC%E8%AA%9E/");
-    }
-
-    #[test]
-    fn dir_to_file_url_returns_none_for_relative_path() {
-        assert_eq!(dir_to_file_url(Path::new("relative/dir")), None);
-    }
-
-    #[cfg(windows)]
-    #[test]
-    fn dir_to_file_url_windows_drive_letter() {
-        let url = dir_to_file_url(Path::new(r"C:\foo\bar")).expect("should convert");
-        assert_eq!(url, "file:///C:/foo/bar/");
-    }
-
-    #[cfg(windows)]
-    #[test]
-    fn dir_to_file_url_windows_drive_letter_with_space() {
-        let url = dir_to_file_url(Path::new(r"C:\Program Files\mdo")).expect("should convert");
-        assert_eq!(url, "file:///C:/Program%20Files/mdo/");
-    }
-
-    // `fs::canonicalize` on Windows produces the `\\?\` extended-length
-    // prefix; browsers don't understand `file:////?/C:/...`, so this must
-    // normalize to the same form as the plain drive-letter case.
-    #[cfg(windows)]
-    #[test]
-    fn dir_to_file_url_windows_extended_length_prefix() {
-        let url = dir_to_file_url(Path::new(r"\\?\C:\foo\bar")).expect("should convert");
-        assert_eq!(url, "file:///C:/foo/bar/");
-    }
-
-    #[cfg(windows)]
-    #[test]
-    fn dir_to_file_url_windows_unc_path() {
-        let url = dir_to_file_url(Path::new(r"\\server\share\dir")).expect("should convert");
-        assert_eq!(url, "file://server/share/dir/");
-    }
 
     #[test]
     fn setup_sample_contains_welcome_copy() {
diff --git a/src/main.rs b/src/main.rs
index bb60f10..c98e10a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -33,15 +33,13 @@
 
 use std::io::{self, IsTerminal, Write};
 use std::path::{Path, PathBuf};
-use std::sync::mpsc::channel;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 use clap::Parser;
 use mdo_cli::{
-    convert, file_manager, launch_browser, open_setup_sample, temp_output_for, ConvertOutcome,
-    ConvertRequest, RenderError, StageTimings,
+    convert, file_manager, launch_browser, open_setup_sample, temp_output_for, watch,
+    ConvertOutcome, ConvertRequest, RenderError, StageTimings,
 };
-use notify::{recommended_watcher, EventKind, RecursiveMode, Watcher};
 
 /// Markdown to HTML converter. Converts once by default; pass --watch to keep watching.
 #[derive(Parser)]
@@ -398,190 +396,122 @@ fn main() -> notify::Result<()> {
         (None, false) => (input.with_extension("html"), false),
     };
 
-    // Register the watch BEFORE the initial render so a save that lands
-    // while that render runs is queued by the watcher rather than silently
-    // lost; the watch loop below drains it and re-renders. Registration
-    // failure aborts before any rendering, which is fine — the user asked
-    // for a watch we cannot deliver.
-    //
-    // Watch the parent DIRECTORY rather than the file itself. Editors that
-    // save atomically (write a temp file, then rename it over the target)
-    // replace the target's inode; a watch on the file itself goes dead the
-    // moment that happens because the inode/handle notify was watching is
-    // gone. Watching the directory survives renames, deletes, and recreates
-    // — we just have to filter directory events down to ones that touch our
-    // target file.
-    //
-    // Resolve the target once, up front. Comparing later events against
-    // this fixed absolute path — rather than re-canonicalizing each event's
-    // path — matters because the target may momentarily not exist
-    // mid-rename, which would make canonicalize fail and misclassify a
-    // perfectly relevant event.
-    //
-    // Known limitation: canonicalizing a symlinked input means we watch the
-    // TARGET's parent, so edits made through the link are seen, but an
-    // editor atomically replacing the symlink itself is not. Watching both
-    // parents isn't worth the complexity until someone actually hits this.
-    let watch_setup = if args.watch {
-        let input_absolute = std::fs::canonicalize(&input).unwrap_or_else(|_| {
-            std::env::current_dir()
-                .map(|cwd| cwd.join(&input))
-                .unwrap_or_else(|_| input.clone())
+    if args.watch {
+        // Watch's contract: register before rendering (a save that lands
+        // while the initial render runs is queued by the watcher rather
+        // than silently lost), run the render callback once immediately,
+        // then pump. In watch mode we deliberately do NOT apply the one-shot
+        // exit-code check below: a one-time --open failure must not end
+        // watch mode, since the whole point is to keep re-rendering on
+        // future edits.
+        let mut pending_open_launch = args.open;
+        return watch::run(&input, &mut || {
+            let result = render_and_report(
+                &input,
+                &output,
+                args.bare,
+                args.unsafe_html,
+                args.css.as_deref(),
+                private_output,
+                args.verbose,
+            );
+            if pending_open_launch {
+                // The launch hook is a one-time post-initial-render duty
+                // (the pump runs the callback immediately): consume the
+                // pending flag on the first callback whether or not that
+                // render succeeded, exactly as the pre-module flow did.
+                if result.is_ok() {
+                    launch_open_output(&output, args.verbose);
+                }
+                pending_open_launch = false;
+            }
+            result.map(|_| ())
         });
-        let watch_dir = input_absolute
-            .parent()
-            .map(PathBuf::from)
-            .unwrap_or_else(|| PathBuf::from("."));
-        let target_file_name = input_absolute.file_name().map(|n| n.to_os_string());
-
-        let (tx, rx) = channel();
-        let mut watcher = recommended_watcher(tx)?;
-        watcher.watch(&watch_dir, RecursiveMode::NonRecursive)?;
-        Some((watcher, rx, watch_dir, target_file_name))
-    } else {
-        None
-    };
+    }
 
-    let converted = report_render(
+    let converted = render_and_report(
         &input,
         &output,
-        &convert(ConvertRequest {
-            input: &input,
-            output: &output,
-            bare: args.bare,
-            unsafe_html: args.unsafe_html,
-            private_output,
-            css_override: args.css.as_deref(),
-        }),
+        args.bare,
+        args.unsafe_html,
+        args.css.as_deref(),
+        private_output,
         args.verbose,
-    );
+    )
+    .is_ok();
 
     // Track whether --open promised a browser launch and failed to deliver
     // one, so the one-shot exit code below can be honest about it.
     let mut open_launch_failed = false;
     if args.open && converted {
-        // Browser launch is reported separately from the render workflow:
-        // launch_browser only initiates the launch (fire-and-forget), so
-        // this measures initiation, not the browser starting up.
-        let launch_start = std::time::Instant::now();
-        match launch_browser(&output) {
-            Ok(()) => {
-                if args.verbose {
-                    eprintln!(
-                        "⏱  Browser launch initiated in {:.3} ms",
-                        launch_start.elapsed().as_secs_f64() * 1000.0
-                    );
-                }
-                println!("🌐 Opened {:?} in default browser", output);
-            }
-            Err(e) => {
-                // The render already succeeded and nothing removes the
-                // rendered file on a launch failure, so point the user at it
-                // instead of silently downgrading this to a warning.
-                eprintln!("❌ Failed to launch browser: {}", e);
-                eprintln!("   Rendered output is available at {:?}", output);
-                open_launch_failed = true;
-            }
-        }
+        open_launch_failed = launch_open_output(&output, args.verbose);
     }
 
-    if !args.watch {
-        // Exit non-zero on a failed one-shot render so scripts and the docs
-        // pipeline can detect errors. A failed --open browser launch is the
-        // same kind of broken promise even though the render itself
-        // succeeded: `mdo --open` only fully succeeds when the file is both
-        // rendered AND opened, so it exits non-zero here too. In watch mode
-        // we deliberately do NOT apply this exit-code check: watch's
-        // contract is to keep running regardless of a one-time --open
-        // failure, since the whole point is to keep re-rendering on future
-        // edits. The stderr message above still fires so the user learns
-        // about the failed launch either way.
-        if converted && !open_launch_failed {
-            return Ok(());
-        }
-        std::process::exit(1);
+    // Exit non-zero on a failed one-shot render so scripts and the docs
+    // pipeline can detect errors. A failed --open browser launch is the
+    // same kind of broken promise even though the render itself succeeded:
+    // `mdo --open` only fully succeeds when the file is both rendered AND
+    // opened, so it exits non-zero here too.
+    if converted && !open_launch_failed {
+        return Ok(());
     }
+    std::process::exit(1);
+}
 
-    let (_watcher, rx, watch_dir, target_file_name) =
-        watch_setup.expect("watch setup was built above whenever --watch is set");
-
-    // Still named after the file, not the directory: that's what the user
-    // asked to watch, even though the underlying notify watch is scoped one
-    // level up.
-    println!("👀 Watching {:?} for changes... (Ctrl+C to stop)", input);
-
-    // Trailing-edge debounce window: once a relevant event arrives we keep
-    // draining/absorbing further relevant events for this long before
-    // rendering, so a burst (e.g. truncate + write, or temp-file write +
-    // rename) collapses into exactly one render of the final content. This
-    // is unlike a leading-edge "ignore anything for N ms after the last
-    // render" debounce, which can drop the trailing event of a burst if the
-    // burst runs longer than the window.
-    const DEBOUNCE: Duration = Duration::from_millis(200);
-
-    loop {
-        // Block for the next event. Anything that isn't a relevant,
-        // content-changing event (wrong file, Access events, watcher
-        // errors) is skipped without starting a debounce window.
-        let event = match rx.recv() {
-            Ok(Ok(event)) => event,
-            Ok(Err(e)) => {
-                eprintln!("⚠️  Watcher error: {}", e);
-                continue;
-            }
-            Err(_) => return Ok(()), // watcher/channel gone; nothing left to watch
-        };
-
-        if !is_relevant_event(&event, target_file_name.as_deref(), &watch_dir) {
-            continue;
-        }
+/// Run one render request and report it. All rendering output lives behind
+/// `report_render`, so the one-shot path and watch-mode re-renders report
+/// identically. The typed outcome still comes back: the watch callback
+/// feeds its `Err` into `watch::run`, which must not end watch mode on a
+/// transient filesystem state mid-rename.
+fn render_and_report(
+    input: &Path,
+    output: &Path,
+    bare: bool,
+    unsafe_html: bool,
+    css_override: Option<&Path>,
+    private_output: bool,
+    verbose: bool,
+) -> Result<(), RenderError> {
+    let outcome = convert(ConvertRequest {
+        input,
+        output,
+        bare,
+        unsafe_html,
+        private_output,
+        css_override,
+    });
+    report_render(input, output, &outcome, verbose);
+    outcome.map(|_| ())
+}
 
-        // Drain/absorb further relevant events for a quiet window, then
-        // render once. This covers direct writes, truncate+rewrite, and
-        // atomic saves (temp file write followed by a rename onto the
-        // target) uniformly: whichever event kinds the editor and platform
-        // happen to emit (Create, Modify, Rename-as-Modify(Name), Remove
-        // followed by a Create), each just extends the quiet window until
-        // the burst settles. Only RELEVANT events extend the deadline:
-        // sibling-file noise merely waits out the remaining window, so a
-        // busy directory (a build churning artifacts next to the watched
-        // file) cannot postpone the render indefinitely.
-        let mut deadline = std::time::Instant::now() + DEBOUNCE;
-        loop {
-            let remaining = deadline.saturating_duration_since(std::time::Instant::now());
-            if remaining.is_zero() {
-                break;
-            }
-            match rx.recv_timeout(remaining) {
-                Ok(Ok(event)) => {
-                    if is_relevant_event(&event, target_file_name.as_deref(), &watch_dir) {
-                        deadline = std::time::Instant::now() + DEBOUNCE;
-                    }
-                    // Irrelevant events neither extend nor cut the window.
-                }
-                Ok(Err(e)) => eprintln!("⚠️  Watcher error: {}", e),
-                Err(_) => break, // quiet window elapsed (or channel closed)
+/// `--open`'s post-render launch hook: initiate the browser launch and
+/// report it. Returns whether the launch failed to deliver on the promise —
+/// the one-shot exit code owes this honesty; watch mode ignores failures
+/// and keeps watching to re-render future edits.
+fn launch_open_output(output: &Path, verbose: bool) -> bool {
+    // Browser launch is reported separately from the render workflow:
+    // launch_browser only initiates the launch (fire-and-forget), so
+    // this measures initiation, not the browser starting up.
+    let launch_start = Instant::now();
+    match launch_browser(output) {
+        Ok(()) => {
+            if verbose {
+                eprintln!(
+                    "⏱  Browser launch initiated in {:.3} ms",
+                    launch_start.elapsed().as_secs_f64() * 1000.0
+                );
             }
+            println!("🌐 Opened {:?} in default browser", output);
+            false
+        }
+        Err(e) => {
+            // The render already succeeded and nothing removes the
+            // rendered file on a launch failure, so point the user at it
+            // instead of silently downgrading this to a warning.
+            eprintln!("❌ Failed to launch browser: {}", e);
+            eprintln!("   Rendered output is available at {:?}", output);
+            true
         }
-
-        println!("🔁 File changed, re-rendering...");
-        // A failed render (e.g. convert returned Err while the file was
-        // momentarily absent mid-rename) must not end watch mode; the ❌
-        // error is reported by `report_render`, so we just loop and wait
-        // for the next event.
-        let _ = report_render(
-            &input,
-            &output,
-            &convert(ConvertRequest {
-                input: &input,
-                output: &output,
-                bare: args.bare,
-                unsafe_html: args.unsafe_html,
-                private_output,
-                css_override: args.css.as_deref(),
-            }),
-            args.verbose,
-        );
     }
 }
 
@@ -643,36 +573,6 @@ fn report_render_timings(input: &Path, timings: &StageTimings) {
     eprintln!("   total    {:>10.3} ms", ms(timings.total));
 }
 
-/// True if `event` plausibly changed the content of the file named
-/// `target_file_name` inside `watch_dir`. We match by file name (and, when
-/// notify reports one, by parent directory) rather than canonicalizing the
-/// event's path, since the target can momentarily not exist mid-rename.
-/// Access events (reads, permission-bit-only changes) are excluded; every
-/// other kind (Create, Modify, Remove, Any, Other) is treated as a possible
-/// content change so recreation-after-remove and atomic renames are all
-/// covered by the same check.
-fn is_relevant_event(
-    event: &notify::Event,
-    target_file_name: Option<&std::ffi::OsStr>,
-    watch_dir: &std::path::Path,
-) -> bool {
-    if matches!(event.kind, EventKind::Access(_)) {
-        return false;
-    }
-
-    let Some(target_file_name) = target_file_name else {
-        return false;
-    };
-
-    event.paths.iter().any(|p| {
-        p.file_name() == Some(target_file_name)
-            && match p.parent() {
-                Some(parent) => parent == watch_dir,
-                None => true,
-            }
-    })
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/src/page.rs b/src/page.rs
new file mode 100644
index 0000000..1468125
--- /dev/null
+++ b/src/page.rs
@@ -0,0 +1,380 @@
+//! Page assembly: everything that turns an HTML fragment into the final
+//! HTML document - styles, scripts, and document wrapping.
+
+use std::fs;
+use std::path::Path;
+use std::time::UNIX_EPOCH;
+const SIMPLE_CSS: &str = include_str!("../assets/simple.min.css");
+const APP_DISPLAY_NAME: &str = "mdo";
+const APP_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+// mdo keeps simple.css as the base stylesheet but softens the heading/body
+// scale for generated documents. Users who prefer the unmodified vendored
+// simple.css typography can pass assets/restore-simple-css.css with --css.
+const MDO_DEFAULT_TYPOGRAPHY_CSS: &str = include_str!("../assets/mdo-default-typography.css");
+
+// pulldown-cmark emits GFM alerts as blockquotes with a
+// `markdown-alert-{kind}` class. Keep the presentation in the generated
+// document so alerts also work for bare installs with no external assets.
+// The plain `:root` and prefers-color-scheme rules keep alerts styled when
+// JavaScript is disabled (the theme-toggle script never runs, so no
+// data-theme attribute is ever set); the higher-specificity
+// `:root[data-theme=...]` rules then follow the theme toggle rather than the
+// OS preference once a reader has selected a manual theme.
+const GFM_ALERTS_CSS: &str = r#"
+:root{--alert-note:#0969da;--alert-tip:#1a7f37;--alert-important:#8250df;--alert-warning:#9a6700;--alert-caution:#cf222e}
+@media (prefers-color-scheme: dark){:root{--alert-note:#58a6ff;--alert-tip:#3fb950;--alert-important:#a371f7;--alert-warning:#d29922;--alert-caution:#f85149}}
+:root[data-theme="light"]{--alert-note:#0969da;--alert-tip:#1a7f37;--alert-important:#8250df;--alert-warning:#9a6700;--alert-caution:#cf222e}
+:root[data-theme="dark"]{--alert-note:#58a6ff;--alert-tip:#3fb950;--alert-important:#a371f7;--alert-warning:#d29922;--alert-caution:#f85149}
+blockquote[class^="markdown-alert-"]{--alert-color:var(--accent);border-left:.3rem solid var(--alert-color);background:var(--accent-bg);padding:.75rem 1rem}
+blockquote.markdown-alert-note{--alert-color:var(--alert-note)}blockquote.markdown-alert-tip{--alert-color:var(--alert-tip)}blockquote.markdown-alert-important{--alert-color:var(--alert-important)}blockquote.markdown-alert-warning{--alert-color:var(--alert-warning)}blockquote.markdown-alert-caution{--alert-color:var(--alert-caution)}
+"#;
+
+// ─── BEGIN THEME TOGGLE ────────────────────────────────────────────────
+// Self-contained light/dark mode toggle. To remove this feature entirely:
+//   1. Delete this block (down to "END THEME TOGGLE").
+//   2. Delete the `{theme_toggle}` line and `theme_toggle = ...` arg in
+//      `wrap_html5` below.
+// Variable values mirror simple.css's @media (prefers-color-scheme: dark).
+//
+// Behavior notes:
+// - OS theme is detected automatically and tracked live until the user makes
+//   a manual choice; the manual choice persists via localStorage.
+// - localStorage can throw on file:// pages in some browsers/configurations,
+//   so every access is wrapped \u2014 the toggle still works for the current page
+//   even when persistence is unavailable.
+// - An in-memory `manual` flag (not the localStorage read) is the source of
+//   truth for "the user made an explicit choice". It is initialized from the
+//   saved value and set on every toggle click regardless of whether
+//   localStorage.setItem succeeds, so a later prefers-color-scheme change
+//   can never clobber an explicit choice just because persistence failed
+//   (e.g. on file:// pages).
+// - The button is a real <button> (keyboard focusable/activatable) with a
+//   state-aware aria-label.
+// - This <style> block is emitted before the --css override block, so custom
+//   CSS can restyle or hide the toggle (e.g. `#theme-toggle{display:none}`)
+//   and reclaim the reserved narrow-screen padding (`body{padding-top:0}`).
+const THEME_TOGGLE: &str = r#"<style id="mdo-theme-toggle">
+:root[data-theme="light"]{color-scheme:light;--bg:#fff;--accent-bg:#f5f7ff;--text:#212121;--text-light:#585858;--accent:#0d47a1;--accent-hover:#1266e2;--accent-text:var(--bg);--code:#d81b60;--preformatted:#444;--disabled:#efefef}
+:root[data-theme="dark"]{color-scheme:dark;--bg:#212121;--accent-bg:#2b2b2b;--text:#dcdcdc;--text-light:#ababab;--accent:#ffb300;--accent-hover:#ffe099;--accent-text:var(--bg);--code:#f06292;--preformatted:#ccc;--disabled:#111}
+:root[data-theme="dark"] img,:root[data-theme="dark"] video{opacity:.8}
+#theme-toggle{position:fixed;top:.75rem;right:.75rem;z-index:1000;padding:.25rem .6rem;font-size:1rem;line-height:1;cursor:pointer;border-radius:var(--standard-border-radius);border:var(--border-width) solid var(--border);background:var(--accent-bg);color:var(--text)}
+@media (max-width:55rem){body{padding-top:2.75rem}}
+@media print{#theme-toggle{display:none}}
+</style>
+<script>
+(function(){
+  var read=function(){try{return localStorage.getItem('theme')}catch(e){return null}};
+  var apply=function(t){document.documentElement.dataset.theme=t;};
+  var mq=matchMedia('(prefers-color-scheme: dark)');
+  var saved=read();
+  var manual=saved!==null;
+  apply(saved||(mq.matches?'dark':'light'));
+  document.addEventListener('DOMContentLoaded',function(){
+    var b=document.createElement('button');
+    b.id='theme-toggle';b.type='button';
+    var sync=function(){
+      var dark=document.documentElement.dataset.theme==='dark';
+      b.textContent=dark?'\u2600':'\u263E';
+      var label=dark?'Switch to light theme':'Switch to dark theme';
+      b.title=label;
+      b.setAttribute('aria-label',label);
+    };
+    b.onclick=function(){
+      var next=document.documentElement.dataset.theme==='dark'?'light':'dark';
+      apply(next);
+      manual=true;
+      try{localStorage.setItem('theme',next)}catch(e){}
+      sync();
+    };
+    if(mq.addEventListener){
+      mq.addEventListener('change',function(e){
+        if(!manual){apply(e.matches?'dark':'light');sync();}
+      });
+    }
+    document.body.appendChild(b);
+    sync();
+  });
+})();
+</script>
+"#;
+// ─── END THEME TOGGLE ──────────────────────────────────────────────────
+
+pub(crate) fn wrap_html5(
+    body: &str,
+    title: &str,
+    base_href: Option<&str>,
+    css_override: Option<&str>,
+    highlight_css: Option<&str>,
+    source_modified_unix_secs: Option<u64>,
+) -> String {
+    // `<base href>` makes relative image/link refs in the rendered HTML resolve
+    // against the *source* directory even when the HTML lives elsewhere
+    // (e.g. when --open writes to %TEMP%). Must come before any element that
+    // references a URL, so we put it first inside <head>.
+    let base_tag = match base_href {
+        Some(href) => format!("<base href=\"{}\">\n", html_escape(href)),
+        None => String::new(),
+    };
+    let css_override_block = css_override
+        .filter(|css| !css.trim().is_empty())
+        .map(|css| {
+            format!(
+                "<style id=\"mdo-css-override\">\n/* Custom CSS from --css */\n{}\n</style>\n",
+                escape_style_end_tags(css)
+            )
+        })
+        .unwrap_or_default();
+    let mdo_default_typography = format!(
+        "<style id=\"mdo-default-typography\">\n{}\n</style>\n",
+        escape_style_end_tags(MDO_DEFAULT_TYPOGRAPHY_CSS)
+    );
+    let highlight_css = highlight_css.unwrap_or_default();
+    // Provenance lives only in <meta name="generator">; the visible page
+    // carries no mdo branding, version, or render timing (v0.6 quiet output).
+    let generator = format!("{APP_DISPLAY_NAME} {APP_VERSION}");
+    // Restrained source-freshness footer: the source file's filesystem
+    // modification time, rendered as UTC with a machine-readable datetime.
+    // The tiny inline script re-formats it in the reader's locale/timezone
+    // when JavaScript is available. Omitted entirely when the timestamp is
+    // missing or unreadable.
+    let source_meta = source_modified_unix_secs
+        .map(|secs| {
+            let machine = utc_datetime_from_unix_secs(secs);
+            let human = human_utc_datetime_from_unix_secs(secs);
+            format!(
+                "<footer class=\"mdo-source-meta\">Source modified: <time datetime=\"{machine}\">{human}</time></footer>\n\
+                 <script>\n\
+                 (function(){{var t=document.querySelector('.mdo-source-meta time');if(!t)return;var d=new Date(t.getAttribute('datetime'));if(isNaN(d))return;try{{t.textContent=d.toLocaleString(undefined,{{year:'numeric',month:'long',day:'numeric',hour:'numeric',minute:'2-digit'}});}}catch(e){{}}}})();\n\
+                 </script>\n",
+                machine = html_escape(&machine),
+                human = html_escape(&human),
+            )
+        })
+        .unwrap_or_default();
+    format!(
+        "<!DOCTYPE html>\n\
+         <html lang=\"en\">\n\
+         <head>\n\
+         <meta charset=\"utf-8\">\n\
+         <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n\
+         <meta name=\"generator\" content=\"{generator}\">\n\
+         {base_tag}\
+         <title>{title}</title>\n\
+         <style>\n{css}\n{gfm_alerts_css}\n{highlight_css}\n.mdo-source-meta{{margin-top:3rem;border:0;padding:1rem 0 1.5rem;font-size:.8rem;line-height:1.4;color:var(--text-light);text-align:center}}\n</style>\n\
+         {theme_toggle}\
+         {mdo_default_typography}\
+         {css_override_block}\
+         </head>\n\
+         <body>\n\
+         <main>\n{body}\n</main>\n\
+         {source_meta}\
+         </body>\n\
+         </html>\n",
+        generator = html_escape(&generator),
+        base_tag = base_tag,
+        title = html_escape(title),
+        css = SIMPLE_CSS,
+        gfm_alerts_css = GFM_ALERTS_CSS,
+        highlight_css = highlight_css,
+        theme_toggle = THEME_TOGGLE, // ← THEME TOGGLE injection point (delete this line to remove)
+        mdo_default_typography = mdo_default_typography,
+        css_override_block = css_override_block,
+        body = body,
+        source_meta = source_meta,
+    )
+}
+
+fn escape_style_end_tags(css: &str) -> String {
+    const STYLE_END_PREFIX: &[u8] = b"</style";
+
+    let mut escaped = String::with_capacity(css.len());
+    let bytes = css.as_bytes();
+    let mut i = 0;
+
+    while i < css.len() {
+        if i + STYLE_END_PREFIX.len() <= css.len()
+            && bytes[i..i + STYLE_END_PREFIX.len()].eq_ignore_ascii_case(STYLE_END_PREFIX)
+        {
+            escaped.push_str("<\\/style");
+            i += STYLE_END_PREFIX.len();
+        } else {
+            let ch = css[i..]
+                .chars()
+                .next()
+                .expect("index should always point at a char boundary");
+            escaped.push(ch);
+            i += ch.len_utf8();
+        }
+    }
+
+    escaped
+}
+
+const MONTH_NAMES: [&str; 12] = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+
+/// The source file's mtime as seconds since the Unix epoch, or `None` when
+/// the metadata is missing or unreadable (which must never block rendering).
+pub(crate) fn source_modified_unix_secs(input: &Path) -> Option<u64> {
+    fs::metadata(input)
+        .and_then(|metadata| metadata.modified())
+        .ok()
+        .and_then(|mtime| mtime.duration_since(UNIX_EPOCH).ok())
+        .map(|elapsed| elapsed.as_secs())
+}
+
+/// ISO 8601 UTC datetime, e.g. `2026-07-14T17:42:05Z`, for `<time datetime>`.
+fn utc_datetime_from_unix_secs(secs: u64) -> String {
+    let days = (secs / 86_400) as i64;
+    let (year, month, day) = civil_from_days(days);
+    let seconds_of_day = secs % 86_400;
+    let hour = seconds_of_day / 3_600;
+    let minute = (seconds_of_day % 3_600) / 60;
+    let second = seconds_of_day % 60;
+
+    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}Z")
+}
+
+/// Readable UTC fallback text, e.g. `July 14, 2026, 5:42 PM UTC`, shown when
+/// JavaScript cannot re-format the timestamp in the reader's locale.
+fn human_utc_datetime_from_unix_secs(secs: u64) -> String {
+    let days = (secs / 86_400) as i64;
+    let (year, month, day) = civil_from_days(days);
+    let seconds_of_day = secs % 86_400;
+    let hour24 = seconds_of_day / 3_600;
+    let minute = (seconds_of_day % 3_600) / 60;
+    let (hour12, meridiem) = match hour24 {
+        0 => (12, "AM"),
+        1..=11 => (hour24, "AM"),
+        12 => (12, "PM"),
+        _ => (hour24 - 12, "PM"),
+    };
+    let month_name = MONTH_NAMES[(month - 1) as usize];
+
+    format!("{month_name} {day}, {year}, {hour12}:{minute:02} {meridiem} UTC")
+}
+
+fn civil_from_days(days_since_unix_epoch: i64) -> (i64, i64, i64) {
+    // Howard Hinnant's civil-from-days algorithm, shifted for Unix epoch days.
+    let z = days_since_unix_epoch + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let day = doy - (153 * mp + 2) / 5 + 1;
+    let month = mp + if mp < 10 { 3 } else { -9 };
+    let year = y + if month <= 2 { 1 } else { 0 };
+
+    (year, month, day)
+}
+
+fn html_escape(s: &str) -> String {
+    s.replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+        .replace('"', "&quot;")
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn formats_unix_timestamps_as_machine_utc_datetimes() {
+        assert_eq!(utc_datetime_from_unix_secs(0), "1970-01-01T00:00:00Z");
+        assert_eq!(
+            utc_datetime_from_unix_secs(951_827_696),
+            "2000-02-29T12:34:56Z"
+        );
+    }
+
+    #[test]
+    fn formats_unix_timestamps_as_readable_utc_datetimes() {
+        // Midnight and noon exercise the 12-hour AM/PM edge cases.
+        assert_eq!(
+            human_utc_datetime_from_unix_secs(0),
+            "January 1, 1970, 12:00 AM UTC"
+        );
+        assert_eq!(
+            human_utc_datetime_from_unix_secs(951_827_696),
+            "February 29, 2000, 12:34 PM UTC"
+        );
+        assert_eq!(
+            human_utc_datetime_from_unix_secs(13 * 3_600 + 5 * 60),
+            "January 1, 1970, 1:05 PM UTC"
+        );
+    }
+
+    #[test]
+    fn wrap_html5_keeps_generator_meta_without_visible_branding() {
+        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, Some(0));
+
+        assert!(html.contains(&format!(
+            "<meta name=\"generator\" content=\"mdo {APP_VERSION}\">"
+        )));
+        assert!(!html.contains("Generated by"));
+        assert!(!html.contains("mdo-generated"));
+    }
+
+    #[test]
+    fn wrap_html5_shows_source_modified_time_with_machine_datetime() {
+        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, Some(951_827_696));
+
+        assert!(html.contains(
+            "<footer class=\"mdo-source-meta\">Source modified: \
+             <time datetime=\"2000-02-29T12:34:56Z\">February 29, 2000, 12:34 PM UTC</time></footer>"
+        ));
+    }
+
+    #[test]
+    fn wrap_html5_renders_without_source_modified_time() {
+        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, None);
+
+        assert!(html.contains("<main>\n<p>hi</p>\n</main>"));
+        assert!(!html.contains("Source modified"));
+        assert!(!html.contains("<footer"));
+    }
+
+    #[test]
+    fn wrapped_document_styles_alerts_in_light_and_dark_palettes() {
+        let html = wrap_html5("<p>hi</p>", "Title", None, None, None, None);
+
+        // No-JS defaults: plain :root plus an OS dark-mode media query, so
+        // alerts stay styled when the theme-toggle script never runs.
+        assert!(html.contains("\n:root{--alert-note:"));
+        assert!(html.contains("@media (prefers-color-scheme: dark){:root{--alert-note:"));
+        // Manual theme-toggle overrides.
+        assert!(html.contains(":root[data-theme=\"light\"]{--alert-note:"));
+        assert!(html.contains(":root[data-theme=\"dark\"]{--alert-note:"));
+        for kind in ["note", "tip", "important", "warning", "caution"] {
+            assert!(html.contains(&format!("blockquote.markdown-alert-{kind}")));
+        }
+    }
+
+    #[test]
+    fn css_override_escapes_style_end_tags() {
+        let escaped = escape_style_end_tags("h1{} </STYLE><script>alert(1)</script>");
+
+        assert!(escaped.contains("<\\/style><script>"));
+        assert!(!escaped.to_ascii_lowercase().contains("</style><script>"));
+    }
+
+    // Unix-rooted paths like `/home/user/...` are NOT absolute on Windows
+    // (no drive or UNC prefix), so `Url::from_directory_path` rejects them
+    // there — every test using such a path must be `#[cfg(unix)]`-gated or
+    // it panics under the Windows CI test job. Windows path forms get their
+    // own `#[cfg(windows)]` tests below.
+}
diff --git a/src/render.rs b/src/render.rs
new file mode 100644
index 0000000..bf573b5
--- /dev/null
+++ b/src/render.rs
@@ -0,0 +1,1026 @@
+//! Render pipeline: the path from Markdown source to an HTML fragment -
+//! parsing, syntax-highlight splicing, sanitizing, title derivation, in
+//! that order, sanitized once, after splicing - plus the single deep
+//! workflow entry point (convert) that reads the source, renders, and
+//! writes the page with per-worker private-output safeguards.
+
+use std::collections::BTreeSet;
+use std::fmt;
+use std::fs;
+use std::io;
+#[cfg(unix)]
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+#[cfg(unix)]
+use std::fs::OpenOptions;
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
+
+use pulldown_cmark::Options;
+use url::Url;
+
+use crate::highlight;
+use crate::page::{source_modified_unix_secs, wrap_html5};
+
+/// Build a `file://` URL for a directory, suitable for use as `<base href>`.
+///
+/// Delegates to [`Url::from_directory_path`], which correctly
+/// percent-encodes reserved and non-ASCII characters (spaces, `#`, `%`, `?`,
+/// Unicode, …) and handles Windows drive letters, UNC paths, and the
+/// `\\?\`/`\\?\UNC\` extended-length prefixes that `fs::canonicalize`
+/// produces — a hand-rolled string transform got all of this subtly wrong
+/// (e.g. a literal `#` in a directory name would truncate the URL when a
+/// browser parsed it as a fragment). Always includes a trailing slash so
+/// relative refs resolve correctly against the directory.
+///
+/// Returns `None` if `dir` can't be represented as a `file://` URL (notably:
+/// relative paths). Callers should fall back to omitting the `<base href>`
+/// tag entirely rather than emit a broken URL.
+fn dir_to_file_url(dir: &Path) -> Option<String> {
+    Url::from_directory_path(dir)
+        .ok()
+        .map(|url| url.to_string())
+}
+
+fn markdown_options() -> Options {
+    let mut options = Options::empty();
+    options.insert(Options::ENABLE_STRIKETHROUGH);
+    options.insert(Options::ENABLE_TABLES);
+    options.insert(Options::ENABLE_FOOTNOTES);
+    options.insert(Options::ENABLE_TASKLISTS);
+    options.insert(Options::ENABLE_GFM);
+
+    options
+}
+
+fn markdown_to_html(
+    markdown: &str,
+    placeholder_discriminator: u64,
+    plain_fences: &BTreeSet<usize>,
+) -> highlight::RenderedMarkdown {
+    // Front matter is stripped here, before parsing, by the same
+    // `yaml_front_matter` splitter that title derivation uses, so one set of
+    // acceptance rules governs both. Options::ENABLE_YAML_STYLE_METADATA_BLOCKS
+    // is deliberately NOT enabled: pulldown-cmark 0.13 recognizes metadata
+    // blocks anywhere at indent 0, not just at document start, which silently
+    // swallows mid-document text framed by `---` lines.
+    let markdown = yaml_front_matter(markdown)
+        .map(|(_, body)| body)
+        .unwrap_or(markdown);
+
+    highlight::render(
+        markdown,
+        markdown_options(),
+        placeholder_discriminator,
+        plain_fences,
+    )
+}
+
+/// Upper bound on placeholder-collision retries. A collision requires
+/// document text that normalizes into the current placeholder token, so more
+/// than a couple of retries only happens with adversarial input; past the cap
+/// the document renders with highlighting disabled rather than looping.
+const MAX_PLACEHOLDER_RETRIES: u32 = 16;
+
+/// Shared render/process/splice loop behind [`safe_markdown_body`] and
+/// [`convert`].
+///
+/// Highlighted spans are generated by mdo from escaped code text and spliced
+/// into the raw renderer output only after all placeholders have been
+/// validated. `process` (usually ammonia) then handles the completed document,
+/// including generated markup, so no string insertion happens beyond the
+/// sanitizer boundary. The loop is guaranteed to terminate:
+///
+/// - a destroyed placeholder can never survive under any discriminator, so
+///   its fence is added to the strictly growing `plain_fences` set and
+///   rendered as an ordinary escaped code block instead;
+/// - collisions retry with a fresh discriminator at most
+///   [`MAX_PLACEHOLDER_RETRIES`] times, after which every fence is rendered
+///   plain, leaving nothing to splice.
+fn spliced_markdown_body(
+    markdown: &str,
+    mut render: impl FnMut(&str, u64, &BTreeSet<usize>) -> highlight::RenderedMarkdown,
+    mut process: impl FnMut(&str) -> String,
+) -> (String, Option<&'static str>) {
+    let mut discriminator = 0_u64;
+    let mut collision_retries = 0_u32;
+    let mut plain_fences = BTreeSet::new();
+
+    loop {
+        let rendered = render(markdown, discriminator, &plain_fences);
+        match rendered.finish(rendered.raw_html().to_string()) {
+            Ok(body) => return (process(&body), rendered.css()),
+            Err(highlight::SpliceError::Destroyed(fences)) => {
+                plain_fences.extend(fences);
+            }
+            Err(highlight::SpliceError::Collision) => {
+                collision_retries += 1;
+                if collision_retries > MAX_PLACEHOLDER_RETRIES {
+                    plain_fences.extend(0..rendered.fence_count());
+                }
+                discriminator += 1;
+            }
+        }
+    }
+}
+
+/// Render and sanitize Markdown, splicing generated highlighting before the
+/// completed document crosses the sanitizer boundary.
+fn safe_markdown_body(markdown: &str) -> (String, Option<&'static str>) {
+    spliced_markdown_body(markdown, markdown_to_html, sanitize_html)
+}
+
+fn sanitize_html(html: &str) -> String {
+    ammonia::Builder::default()
+        // The global "class" allowance is intentional: user-authored class
+        // names are inert here because classes only select styles from mdo's
+        // own generated stylesheet. Highlight safety does not rest on this
+        // allowlist either: highlighted markup is generated from escaped code
+        // text, spliced before sanitization, and then cleaned with the rest of
+        // the document.
+        .add_generic_attributes(&["class", "id"])
+        .add_tags(&["input"])
+        .add_tag_attributes("input", &["checked", "type"])
+        .add_tag_attribute_values("input", "checked", &[""])
+        .add_tag_attribute_values("input", "type", &["checkbox"])
+        .set_tag_attribute_value("input", "disabled", "")
+        .clean(html)
+        .to_string()
+}
+
+/// Render Markdown supplied in memory as a complete, self-contained HTML page.
+///
+/// This is the platform-neutral entry point used by the Android application.
+/// Raw HTML is always sanitized, matching the safe default of the desktop CLI.
+/// `fallback_title` is used only when the document has no top-level heading.
+pub fn render_markdown_document(
+    markdown: &str,
+    fallback_title: &str,
+    source_modified_unix_secs: Option<u64>,
+) -> String {
+    let (body, highlight_css) = safe_markdown_body(markdown);
+    let title = derive_title(markdown, fallback_title);
+    wrap_html5(
+        &body,
+        &title,
+        None,
+        None,
+        highlight_css,
+        source_modified_unix_secs,
+    )
+}
+
+fn derive_title(markdown: &str, fallback: &str) -> String {
+    if let Some(title) = front_matter_title(markdown) {
+        return title;
+    }
+
+    // A valid metadata block is not document content. Exclude it from the
+    // existing H1 search even when it has no usable title key.
+    let markdown = yaml_front_matter(markdown)
+        .map(|(_, document)| document)
+        .unwrap_or(markdown);
+
+    // Strip fenced code blocks first so a heading — whether an ATX `# ` line or
+    // a raw <h1> — inside a ``` or ~~~ block is never mistaken for the title.
+    let without_fences = strip_code_fences(markdown);
+    for line in without_fences.lines() {
+        let trimmed = line.trim_start();
+        if let Some(rest) = trimmed.trim_end().strip_prefix("# ") {
+            return rest.trim().to_string();
+        }
+    }
+    if let Some(title) = derive_raw_html_h1_title(&without_fences) {
+        return title;
+    }
+    fallback.to_string()
+}
+
+/// Extract a simple scalar `title:` from a complete YAML-style metadata block
+/// at the start of the document.
+///
+/// pulldown-cmark deliberately recognizes the block delimiters without
+/// interpreting YAML. mdo follows that narrow behavior: it reads only an
+/// unindented `title` key and does not add a general-purpose YAML parser (and
+/// its dependency/security surface) merely to title the generated page.
+fn front_matter_title(markdown: &str) -> Option<String> {
+    let (metadata, _) = yaml_front_matter(markdown)?;
+    let mut title = None;
+    for line in metadata.lines() {
+        if line.starts_with(char::is_whitespace) {
+            continue;
+        }
+        if let Some((key, value)) = line.split_once(':') {
+            if key == "title" {
+                let value = unquote_front_matter_scalar(value.trim());
+                if !value.is_empty() {
+                    title = Some(value.to_string());
+                }
+            }
+        }
+    }
+
+    title
+}
+
+/// Split a complete YAML-style metadata block from the document body. The
+/// returned metadata excludes delimiters.
+///
+/// This splitter is the single source of truth for front-matter recognition
+/// (both hiding the block from rendered output and title extraction), and its
+/// acceptance rules are deliberately conservative and GitHub-like:
+///
+/// - the opening `---` must be the very first line of the document;
+/// - the closing delimiter is `---` or `...` on its own line — trailing
+///   spaces are allowed but tabs are not;
+/// - the block must be non-empty and its first line must not be blank.
+///   GitHub and pulldown-cmark both reject blocks whose first content line is
+///   blank, so treating them as front matter here would hide visible content
+///   and let e.g. `---\n\ntitle: fake\n---` spoof the page title.
+fn yaml_front_matter(markdown: &str) -> Option<(&str, &str)> {
+    fn delimiter(line: &str) -> Option<&str> {
+        let line = line.trim_end_matches(['\r', '\n']).trim_end_matches(' ');
+        (line == "---" || line == "...").then_some(line)
+    }
+
+    let first_line_end = markdown.find('\n').unwrap_or(markdown.len());
+    if delimiter(&markdown[..first_line_end]) != Some("---") || first_line_end == markdown.len() {
+        return None;
+    }
+
+    let metadata_start = first_line_end + 1;
+    let remainder = &markdown[metadata_start..];
+    let mut consumed = 0;
+    // split_inclusive also yields a final segment without a trailing newline,
+    // so a closing delimiter at end-of-input is found by the loop as well.
+    for segment in remainder.split_inclusive('\n') {
+        if delimiter(segment).is_some() {
+            let metadata = &remainder[..consumed];
+            let first_content_line = metadata.lines().next()?;
+            if first_content_line.trim().is_empty() {
+                return None;
+            }
+            return Some((metadata, &remainder[consumed + segment.len()..]));
+        }
+        consumed += segment.len();
+    }
+
+    None
+}
+
+fn unquote_front_matter_scalar(value: &str) -> &str {
+    if value.len() < 2 {
+        return value;
+    }
+
+    let bytes = value.as_bytes();
+    if matches!(
+        (bytes[0], bytes[value.len() - 1]),
+        (b'\'', b'\'') | (b'"', b'"')
+    ) {
+        &value[1..value.len() - 1]
+    } else {
+        value
+    }
+}
+
+/// Return `markdown` with fenced code blocks (``` or ~~~) removed, so title
+/// detection never reads inside code samples.
+fn strip_code_fences(markdown: &str) -> String {
+    let mut out = String::with_capacity(markdown.len());
+    let mut fence: Option<char> = None;
+    for line in markdown.lines() {
+        if let Some(marker) = code_fence_marker(line.trim_start()) {
+            match fence {
+                Some(open) if open == marker => fence = None,
+                Some(_) => {}
+                None => fence = Some(marker),
+            }
+            continue;
+        }
+        if fence.is_some() {
+            continue;
+        }
+        out.push_str(line);
+        out.push('\n');
+    }
+    out
+}
+
+/// Detect a code-fence line, returning its marker char when the line starts
+/// with at least three backticks or tildes. This is a pragmatic subset of
+/// CommonMark (it does not bound the indent or require the closing fence to be
+/// at least as long), which is sufficient for title detection.
+fn code_fence_marker(trimmed_start: &str) -> Option<char> {
+    if trimmed_start.starts_with("```") {
+        Some('`')
+    } else if trimmed_start.starts_with("~~~") {
+        Some('~')
+    } else {
+        None
+    }
+}
+
+fn derive_raw_html_h1_title(markdown: &str) -> Option<String> {
+    let lower = markdown.to_ascii_lowercase();
+    let mut search_start = 0;
+
+    while let Some(offset) = lower[search_start..].find("<h1") {
+        let start = search_start + offset;
+        let after_tag_name = start + 3;
+        let next = lower.as_bytes().get(after_tag_name).copied();
+        if !matches!(
+            next,
+            Some(b'>') | Some(b' ') | Some(b'\t') | Some(b'\r') | Some(b'\n')
+        ) {
+            search_start = after_tag_name;
+            continue;
+        }
+
+        let content_start = start + markdown[start..].find('>')? + 1;
+        let content_end = content_start + lower[content_start..].find("</h1>")?;
+        let title = strip_html_tags(&markdown[content_start..content_end])
+            .split_whitespace()
+            .collect::<Vec<_>>()
+            .join(" ");
+        if !title.is_empty() {
+            return Some(title);
+        }
+
+        search_start = content_end + 5;
+    }
+
+    None
+}
+
+fn strip_html_tags(input: &str) -> String {
+    let mut output = String::with_capacity(input.len());
+    let mut in_tag = false;
+
+    for ch in input.chars() {
+        match ch {
+            '<' => in_tag = true,
+            '>' if in_tag => in_tag = false,
+            _ if !in_tag => output.push(ch),
+            _ => {}
+        }
+    }
+
+    output
+}
+
+/// Wall-clock time spent in each stage of one render workflow, plus the
+/// workflow's total. Reported to stderr by the CLI's `--verbose` output.
+/// Stages that do not run for a given invocation (`sanitize` under
+/// `--unsafe-html`, `assemble` under `--bare`) report zero.
+#[derive(Debug, Default)]
+pub struct StageTimings {
+    pub read: Duration,
+    pub markdown: Duration,
+    pub sanitize: Duration,
+    pub assemble: Duration,
+    pub write: Duration,
+    /// Wall-clock time of the whole workflow, always at least the sum of
+    /// the stages.
+    pub total: Duration,
+}
+
+/// One render request for [`convert`]: a Markdown input, a destination, and
+/// the render options. `verbose` is deliberately absent — diagnostics are
+/// the caller's presentation concern, and [`ConvertOutcome::timings`]
+/// carries everything a caller needs to print them.
+#[derive(Debug)]
+pub struct ConvertRequest<'a> {
+    /// The Markdown source file.
+    pub input: &'a Path,
+    /// The HTML file to write; created when missing, overwritten when
+    /// present.
+    pub output: &'a Path,
+    /// Emit only the HTML fragment (no `<html>`, `<head>`, `<body>`, no CSS).
+    pub bare: bool,
+    /// Preserve raw HTML from the Markdown source instead of sanitizing it.
+    pub unsafe_html: bool,
+    /// Write the output file readable only by the current user.
+    pub private_output: bool,
+    /// Custom CSS appended after mdo's default styling. Read from disk here
+    /// and ignored under `bare`, because bare output emits no CSS.
+    pub css_override: Option<&'a Path>,
+}
+
+/// What a successful [`convert`] wrote: the output file plus the workflow's
+/// stage-by-stage timing record.
+#[derive(Debug)]
+pub struct ConvertOutcome {
+    /// The output file that was written.
+    pub output: PathBuf,
+    /// Wall-clock timing record for the completed workflow.
+    pub timings: StageTimings,
+}
+
+/// Why a [`convert`] workflow failed, typed per failure site with the
+/// underlying `io::Error` and the path it concerns, so callers keep printing
+/// their own messages instead of the library doing it for them.
+#[derive(Debug)]
+pub enum RenderError {
+    /// Reading the Markdown input file failed.
+    Read { path: PathBuf, source: io::Error },
+    /// Reading the `--css` override file failed.
+    ReadCssOverride { path: PathBuf, source: io::Error },
+    /// Creating the output file's parent directory failed.
+    CreateOutputDir { path: PathBuf, source: io::Error },
+    /// Writing the rendered HTML file failed.
+    Write { path: PathBuf, source: io::Error },
+}
+
+impl fmt::Display for RenderError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let (action, path, source) = match self {
+            RenderError::Read { path, source } => ("failed to read", path, source),
+            RenderError::ReadCssOverride { path, source } => {
+                ("failed to read CSS override", path, source)
+            }
+            RenderError::CreateOutputDir { path, source } => ("failed to create", path, source),
+            RenderError::Write { path, source } => ("failed to write", path, source),
+        };
+        write!(f, "{} {}: {}", action, path.display(), source)
+    }
+}
+
+impl std::error::Error for RenderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        Some(match self {
+            RenderError::Read { source, .. }
+            | RenderError::ReadCssOverride { source, .. }
+            | RenderError::CreateOutputDir { source, .. }
+            | RenderError::Write { source, .. } => source,
+        })
+    }
+}
+
+/// Render one Markdown file to HTML: the render pipeline's single deep
+/// entry point.
+///
+/// The workflow: read the source (and any CSS override), render and splice
+/// highlighting, sanitize (unless `unsafe_html`), assemble the page (unless
+/// `bare`), create the output's parent directory when missing, then write
+/// the file (O_NOFOLLOW, mode 0o600 under `private_output`). The workflow
+/// prints nothing itself — success carries a [`ConvertOutcome`] with the
+/// written file and timing record, failure a typed [`RenderError`] — so the
+/// same workflow serves the CLI, the setup sample, and any other host, and
+/// the generated HTML is byte-identical everywhere it is invoked from.
+pub fn convert(request: ConvertRequest) -> Result<ConvertOutcome, RenderError> {
+    let workflow_start = Instant::now();
+    let mut timings = StageTimings::default();
+
+    let stage_start = Instant::now();
+    let markdown = fs::read_to_string(request.input).map_err(|source| RenderError::Read {
+        path: request.input.to_path_buf(),
+        source,
+    })?;
+    timings.read = stage_start.elapsed();
+
+    let css_override = if request.bare {
+        None
+    } else {
+        match request.css_override {
+            Some(path) => {
+                let stage_start = Instant::now();
+                let css =
+                    fs::read_to_string(path).map_err(|source| RenderError::ReadCssOverride {
+                        path: path.to_path_buf(),
+                        source,
+                    })?;
+                timings.read += stage_start.elapsed();
+                Some(css)
+            }
+            None => None,
+        }
+    };
+
+    // Same splice loop as `safe_markdown_body`, instrumented for the
+    // outcome's timing record.
+    let (body, highlight_css) = spliced_markdown_body(
+        &markdown,
+        |markdown, discriminator, plain_fences| {
+            let stage_start = Instant::now();
+            let rendered = markdown_to_html(markdown, discriminator, plain_fences);
+            timings.markdown += stage_start.elapsed();
+            rendered
+        },
+        |html| {
+            if request.unsafe_html {
+                html.to_string()
+            } else {
+                let sanitize_start = Instant::now();
+                let sanitized = sanitize_html(html);
+                timings.sanitize += sanitize_start.elapsed();
+                sanitized
+            }
+        },
+    );
+
+    let final_html = if request.bare {
+        body
+    } else {
+        let stage_start = Instant::now();
+        let fallback = request
+            .input
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .unwrap_or("Document");
+        let title = derive_title(&markdown, fallback);
+
+        // Only inject <base href> when the output lives in a different
+        // directory from the source — otherwise relative refs already
+        // resolve correctly and a base tag would just add noise.
+        let base_href = match (
+            fs::canonicalize(request.input)
+                .ok()
+                .and_then(|p| p.parent().map(Path::to_path_buf)),
+            request
+                .output
+                .parent()
+                .and_then(|p| fs::canonicalize(p).ok()),
+        ) {
+            (Some(in_dir), Some(out_dir)) if in_dir != out_dir => dir_to_file_url(&in_dir),
+            _ => None,
+        };
+
+        let wrapped = wrap_html5(
+            &body,
+            &title,
+            base_href.as_deref(),
+            css_override.as_deref(),
+            highlight_css,
+            source_modified_unix_secs(request.input),
+        );
+        timings.assemble = stage_start.elapsed();
+        wrapped
+    };
+
+    let stage_start = Instant::now();
+    if let Some(parent) = request.output.parent() {
+        if !parent.as_os_str().is_empty() {
+            fs::create_dir_all(parent).map_err(|source| RenderError::CreateOutputDir {
+                path: parent.to_path_buf(),
+                source,
+            })?;
+        }
+    }
+
+    write_output_file(request.output, &final_html, request.private_output).map_err(|source| {
+        RenderError::Write {
+            path: request.output.to_path_buf(),
+            source,
+        }
+    })?;
+    timings.write = stage_start.elapsed();
+    timings.total = workflow_start.elapsed();
+
+    Ok(ConvertOutcome {
+        output: request.output.to_path_buf(),
+        timings,
+    })
+}
+
+#[cfg(unix)]
+fn write_output_file(output: &Path, contents: &str, private_output: bool) -> io::Result<()> {
+    let mut options = OpenOptions::new();
+    options
+        .write(true)
+        .create(true)
+        .truncate(true)
+        .custom_flags(libc::O_NOFOLLOW);
+
+    if private_output {
+        options.mode(0o600);
+    }
+
+    let mut file = options.open(output)?;
+    file.write_all(contents.as_bytes())
+}
+
+#[cfg(not(unix))]
+fn write_output_file(output: &Path, contents: &str, _private_output: bool) -> io::Result<()> {
+    fs::write(output, contents)
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::BTreeSet;
+
+    fn rendered_markdown_html(markdown: &str) -> String {
+        let rendered = markdown_to_html(markdown, 0, &BTreeSet::new());
+        rendered
+            .finish(rendered.raw_html().to_string())
+            .expect("unsanitized renderer should preserve its unique placeholders")
+    }
+
+    #[test]
+    fn in_memory_render_uses_shared_safe_document_pipeline() {
+        let html = render_markdown_document(
+            "# Phone note\n\nHello **Android**.\n\n<script>alert('no')</script>",
+            "fallback.md",
+            None,
+        );
+
+        assert!(html.contains("<title>Phone note</title>"));
+        assert!(html.contains("<strong>Android</strong>"));
+        assert!(html.contains("<meta name=\"generator\" content=\"mdo "));
+        assert!(!html.contains("<script>alert('no')</script>"));
+    }
+
+    #[test]
+    fn markdown_extensions_keep_their_existing_html() {
+        let markdown = "~~gone~~\n\n\
+                        | A | B |\n\
+                        | - | - |\n\
+                        | 1 | 2 |\n\n\
+                        Footnote[^one].\n\n\
+                        [^one]: Detail\n\n\
+                        - [x] done\n\
+                        - [ ] later\n";
+        let expected = "<p><del>gone</del></p>\n\
+                        <table><thead><tr><th>A</th><th>B</th></tr></thead><tbody>\n\
+                        <tr><td>1</td><td>2</td></tr>\n\
+                        </tbody></table>\n\
+                        <p>Footnote<sup class=\"footnote-reference\"><a href=\"#one\">1</a></sup>.</p>\n\
+                        <div class=\"footnote-definition\" id=\"one\"><sup class=\"footnote-definition-label\">1</sup>\n\
+                        <p>Detail</p>\n\
+                        </div>\n\
+                        <ul>\n\
+                        <li><input disabled=\"\" type=\"checkbox\" checked=\"\"/>\n\
+                        done</li>\n\
+                        <li><input disabled=\"\" type=\"checkbox\"/>\n\
+                        later</li>\n\
+                        </ul>\n";
+
+        assert_eq!(rendered_markdown_html(markdown), expected);
+    }
+
+    #[test]
+    fn gfm_alerts_render_all_supported_classes_and_survive_sanitizing() {
+        for kind in ["note", "tip", "important", "warning", "caution"] {
+            let markdown = format!("> [!{}]\n> Alert text\n", kind.to_uppercase());
+            let raw = rendered_markdown_html(&markdown);
+            let class = format!("class=\"markdown-alert-{kind}\"");
+
+            assert!(raw.contains(&class), "{raw}");
+            assert!(!raw.contains("[!"), "{raw}");
+            assert!(sanitize_html(&raw).contains(&class), "{raw}");
+        }
+    }
+
+    #[test]
+    fn yaml_front_matter_is_hidden_and_supplies_document_title() {
+        let markdown =
+            "---\ntitle: 'Front Matter Title'\nauthor: Example\n...\n\n# Heading Title\n";
+        let body = rendered_markdown_html(markdown);
+
+        assert_eq!(body, "<h1>Heading Title</h1>\n");
+        assert_eq!(derive_title(markdown, "fallback"), "Front Matter Title");
+
+        let document = render_markdown_document(markdown, "fallback", None);
+        assert!(document.contains("<title>Front Matter Title</title>"));
+        assert!(!document.contains("author: Example"));
+    }
+
+    #[test]
+    fn mid_document_metadata_style_blocks_are_rendered_not_swallowed() {
+        let markdown = "# Top\n\nintro\n\n---\nnot a heading\n---\n\ntail\n";
+        let html = rendered_markdown_html(markdown);
+
+        assert!(html.contains("not a heading"), "{html}");
+        assert!(html.contains("tail"), "{html}");
+        assert_eq!(derive_title(markdown, "fallback"), "Top");
+    }
+
+    #[test]
+    fn blank_first_line_block_is_not_front_matter() {
+        // GitHub and pulldown-cmark reject metadata blocks whose first content
+        // line is blank; accepting one here would hide visible text and let it
+        // spoof the page title.
+        let markdown = "---\n\ntitle: fake\n---\n\n# Real Heading\n";
+        let html = rendered_markdown_html(markdown);
+
+        assert!(html.contains("title: fake"), "{html}");
+        assert_eq!(derive_title(markdown, "fallback"), "Real Heading");
+
+        // An empty block is likewise not front matter.
+        assert!(yaml_front_matter("---\n---\n# Heading\n").is_none());
+    }
+
+    #[test]
+    fn front_matter_title_supports_colons_and_double_quotes() {
+        let markdown = "---\ntitle: \"Project: Alpha\"\n---\n\n# Heading\n";
+        assert_eq!(derive_title(markdown, "fallback"), "Project: Alpha");
+    }
+
+    #[test]
+    fn missing_empty_or_unclosed_front_matter_title_uses_existing_fallbacks() {
+        assert_eq!(
+            derive_title("---\nauthor: Example\n---\n\n# Heading\n", "fallback"),
+            "Heading"
+        );
+        assert_eq!(
+            derive_title("---\ntitle: \n---\n", "Fallback Title"),
+            "Fallback Title"
+        );
+        assert_eq!(
+            derive_title("---\ntitle: Incomplete\n# Real Heading\n", "fallback"),
+            "Real Heading"
+        );
+        assert_eq!(
+            derive_title(
+                "---\ndescription: |\n# Metadata, not a heading\n---\n\n# Real Heading\n",
+                "fallback"
+            ),
+            "Real Heading"
+        );
+    }
+
+    #[test]
+    fn smart_punctuation_is_not_enabled() {
+        let html = rendered_markdown_html("-- --- ... \"straight\" 'quotes'\n");
+
+        assert_eq!(html, "<p>-- --- ... \"straight\" 'quotes'</p>\n");
+        assert!(!html.contains(['–', '—', '…', '“', '”', '‘', '’']));
+    }
+
+    #[test]
+    fn recognized_fences_are_highlighted_with_both_theme_palettes() {
+        let markdown = "```rust\nfn main() { let html = \"<script>x</script>\"; }\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert!(html.contains(
+            "<pre class=\"mdo-highlight mdo-syntect-code\"><code class=\"language-rust\">"
+        ));
+        assert!(html.contains("mdo-syntect-keyword"), "{html}");
+        assert!(html.contains(":root[data-theme=\"light\"] .mdo-syntect-code"));
+        assert!(html.contains(":root[data-theme=\"dark\"] .mdo-syntect-code"));
+        assert!(!html.contains("<script>x</script>"));
+        assert!(html.contains("&lt;script&gt;"));
+    }
+
+    #[test]
+    fn unknown_fences_remain_plain_and_do_not_add_theme_css() {
+        let markdown = "```not-a-real-language\n<unsafe> & plain\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert!(html.contains(
+            "<pre><code class=\"language-not-a-real-language\">&lt;unsafe&gt; &amp; plain\n</code></pre>"
+        ));
+        assert!(!html.contains("mdo-highlight"));
+        assert!(!html.contains("Syntax highlighting generated by syntect"));
+    }
+
+    #[test]
+    fn pages_without_code_do_not_add_highlight_css() {
+        let html = render_markdown_document("# Just prose\n", "fallback", None);
+        assert!(!html.contains("Syntax highlighting generated by syntect"));
+        assert!(!html.contains("mdo-syntect-"));
+
+        let unlabeled = render_markdown_document("```\nplain code\n```\n", "fallback", None);
+        assert!(unlabeled.contains("<pre><code>plain code\n</code></pre>"));
+        assert!(!unlabeled.contains("Syntax highlighting generated by syntect"));
+    }
+
+    #[test]
+    fn literal_placeholder_spoof_does_not_capture_generated_markup() {
+        let spoof = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
+        let markdown = format!("`{spoof}`\n\n```rust\nlet answer = 42;\n```\n");
+        let html = render_markdown_document(&markdown, "fallback", None);
+
+        assert!(html.contains(spoof));
+        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
+        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
+    }
+
+    #[test]
+    fn entity_normalized_placeholder_spoof_cannot_capture_generated_markup() {
+        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
+        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
+        let markdown = format!("{encoded}\n\n```rust\nlet answer = 42;\n```\n");
+        let html = render_markdown_document(&markdown, "fallback", None);
+
+        assert!(html.contains(normalized), "{html}");
+        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
+        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
+    }
+
+    #[test]
+    fn attribute_normalized_placeholder_cannot_receive_generated_markup() {
+        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
+        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
+        let markdown = format!(
+            "<span title=\"{encoded}\">probe</span>\n\n```rust\nlet one = 1;\n```\n\n```python\nprint(2)\n```\n"
+        );
+        let html = render_markdown_document(&markdown, "fallback", None);
+
+        assert!(html.contains(&format!("title=\"{normalized}\"")), "{html}");
+        assert!(!html.contains("title=\"<pre"), "{html}");
+        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 2);
+        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_0__"));
+        assert!(!html.contains("__MDO_HIGHLIGHT_PLACEHOLDER_1_1__"));
+    }
+
+    #[test]
+    fn normalized_spoof_cannot_mask_a_sanitizer_destroyed_placeholder() {
+        let normalized = "__MDO_HIGHLIGHT_PLACEHOLDER_0_0__";
+        let encoded = "&#95;&#95;MDO&#95;HIGHLIGHT&#95;PLACEHOLDER&#95;0&#95;0&#95;&#95;";
+        let markdown = format!(
+            "<span title=\"{encoded}\">probe</span>\n\n<style>\n\n```rust\nfn main() {{}}\n```\n"
+        );
+        let html = render_markdown_document(&markdown, "fallback", None);
+
+        assert!(html.contains(&format!("title=\"{normalized}\"")), "{html}");
+        assert!(!html.contains("title=\"<pre"), "{html}");
+        assert!(!html.contains("<pre class=\"mdo-highlight "), "{html}");
+        assert!(!html.contains("<code class=\"language-rust\""), "{html}");
+    }
+
+    #[test]
+    fn unclosed_style_before_fence_terminates_without_post_sanitize_splice() {
+        // Inline `<style>` never closes, so ammonia swallows and strips all
+        // subsequent markup. Highlight splicing happens before that single
+        // sanitizer pass, so this terminates without a placeholder retry.
+        let markdown = "before <style> after\n\n```rust\nfn main() {}\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert!(html.contains("before"));
+        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
+        assert!(!html.contains("mdo-highlight"));
+    }
+
+    #[test]
+    fn unclosed_script_before_fence_terminates_without_post_sanitize_splice() {
+        let markdown = "before <script> after\n\n```rust\nfn main() {}\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert!(html.contains("before"));
+        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
+        assert!(!html.contains("mdo-highlight"));
+    }
+
+    #[test]
+    fn sanitizer_drops_only_highlight_markup_after_unclosed_style() {
+        // The first fence precedes the unclosed <style>, so its generated
+        // markup survives sanitization. Only the second fence is swallowed.
+        let markdown =
+            "```rust\nlet first = 1;\n```\n\ntext <style> text\n\n```rust\nlet second = 2;\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 1);
+        assert!(html.contains("let"), "{html}");
+        assert!(html.contains("first"), "{html}");
+        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
+    }
+
+    #[test]
+    fn multiple_highlighted_blocks_splice_once_each() {
+        let markdown = "```rust\nlet one = 1;\n```\n\n```python\nprint(2)\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert_eq!(html.matches("<pre class=\"mdo-highlight ").count(), 2);
+        assert!(html.contains("language-rust"));
+        assert!(html.contains("language-python"));
+        assert!(!html.contains("MDO_HIGHLIGHT_PLACEHOLDER"));
+    }
+
+    #[test]
+    fn raw_user_html_still_crosses_the_ammonia_boundary() {
+        let markdown = "<div onclick=\"alert(1)\"><script>bad()</script><span class=\"mdo-syntect-keyword\">user</span></div>\n\n```rust\nlet safe = \"<b>code</b>\";\n```\n";
+        let html = render_markdown_document(markdown, "fallback", None);
+
+        assert!(!html.contains("onclick=\"alert(1)\""));
+        assert!(!html.contains("<script>bad()</script>"));
+        assert!(html.contains(">user</span>"));
+        assert!(!html.contains("<b>code</b>"));
+        assert!(html.contains("&lt;b&gt;"));
+    }
+
+    #[test]
+    fn title_can_come_from_raw_html_h1() {
+        let title = derive_title(
+            r#"<section><h1 class="hero-title">Project <span>Home</span></h1></section>"#,
+            "fallback",
+        );
+
+        assert_eq!(title, "Project Home");
+    }
+
+    #[test]
+    fn derive_title_ignores_headings_in_code_fences() {
+        let markdown = "```sh\n# not a title\n```\n\n# Real Title\n";
+        assert_eq!(derive_title(markdown, "fallback"), "Real Title");
+    }
+
+    #[test]
+    fn derive_title_falls_back_when_only_heading_is_fenced() {
+        let markdown = "~~~\n# fenced heading\n~~~\n";
+        assert_eq!(derive_title(markdown, "Fallback Title"), "Fallback Title");
+    }
+
+    #[test]
+    fn derive_title_ignores_raw_html_h1_inside_code_fence() {
+        let markdown = "```html\n<h1>Not the title</h1>\n```\n\n# Real Title\n";
+        assert_eq!(derive_title(markdown, "fallback"), "Real Title");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_adds_trailing_slash() {
+        let url =
+            dir_to_file_url(Path::new("/home/user/docs")).expect("absolute path should convert");
+        assert!(url.ends_with('/'));
+        assert_eq!(url, "file:///home/user/docs/");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_spaces() {
+        let url = dir_to_file_url(Path::new("/home/user/my docs")).expect("should convert");
+        assert_eq!(url, "file:///home/user/my%20docs/");
+    }
+
+    // `#` is a legal Windows filename character but is not exercised there
+    // because these are pure-path conversions, not filesystem operations —
+    // gating still keeps the Windows suite focused on Windows-specific forms
+    // (drive letters, UNC, `\\?\`) covered below.
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_hash() {
+        let url = dir_to_file_url(Path::new("/home/user/docs#1")).expect("should convert");
+        assert_eq!(url, "file:///home/user/docs%231/");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_percent() {
+        let url = dir_to_file_url(Path::new("/home/user/50%done")).expect("should convert");
+        assert_eq!(url, "file:///home/user/50%25done/");
+    }
+
+    // `?` is invalid in Windows filenames, so this case can't arise there.
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_question_mark() {
+        let url = dir_to_file_url(Path::new("/home/user/docs?draft")).expect("should convert");
+        assert_eq!(url, "file:///home/user/docs%3Fdraft/");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_unicode_accented() {
+        let url = dir_to_file_url(Path::new("/home/user/résumé")).expect("should convert");
+        assert_eq!(url, "file:///home/user/r%C3%A9sum%C3%A9/");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn dir_to_file_url_encodes_unicode_cjk() {
+        let url = dir_to_file_url(Path::new("/home/user/日本語")).expect("should convert");
+        assert_eq!(url, "file:///home/user/%E6%97%A5%E6%9C%AC%E8%AA%9E/");
+    }
+
+    #[test]
+    fn dir_to_file_url_returns_none_for_relative_path() {
+        assert_eq!(dir_to_file_url(Path::new("relative/dir")), None);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn dir_to_file_url_windows_drive_letter() {
+        let url = dir_to_file_url(Path::new(r"C:\foo\bar")).expect("should convert");
+        assert_eq!(url, "file:///C:/foo/bar/");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn dir_to_file_url_windows_drive_letter_with_space() {
+        let url = dir_to_file_url(Path::new(r"C:\Program Files\mdo")).expect("should convert");
+        assert_eq!(url, "file:///C:/Program%20Files/mdo/");
+    }
+
+    // `fs::canonicalize` on Windows produces the `\\?\` extended-length
+    // prefix; browsers don't understand `file:////?/C:/...`, so this must
+    // normalize to the same form as the plain drive-letter case.
+
+    #[cfg(windows)]
+    #[test]
+    fn dir_to_file_url_windows_extended_length_prefix() {
+        let url = dir_to_file_url(Path::new(r"\\?\C:\foo\bar")).expect("should convert");
+        assert_eq!(url, "file:///C:/foo/bar/");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn dir_to_file_url_windows_unc_path() {
+        let url = dir_to_file_url(Path::new(r"\\server\share\dir")).expect("should convert");
+        assert_eq!(url, "file://server/share/dir/");
+    }
+}
diff --git a/src/temp_output.rs b/src/temp_output.rs
new file mode 100644
index 0000000..6ef1c29
--- /dev/null
+++ b/src/temp_output.rs
@@ -0,0 +1,176 @@
+//! Temp output: the per-source private location under the OS temp
+//! directory where rendered pages are written for opening. Stable per
+//! source path; never written next to the source.
+
+use std::collections::hash_map::DefaultHasher;
+use std::fs;
+use std::hash::{Hash, Hasher};
+use std::io;
+use std::path::{Path, PathBuf};
+
+#[cfg(unix)]
+use std::os::unix::fs::{DirBuilderExt, MetadataExt, PermissionsExt};
+
+const UNSAFE_TEMP_OUTPUT_STEM_CHARS: &[char] = &[
+    '&', '^', '%', '(', ')', '!', '"', '\'', '<', '>', '|', ';', '`', '$', '\\', '/', ':',
+];
+
+/// Stable per-source-path location under a private temp/cache dir, e.g.
+/// `%TEMP%\mdo-<uid>\<hash>\<stem>.html`. Re-opening the same source
+/// overwrites the same file rather than accumulating new ones.
+pub fn temp_output_for(input: &Path) -> io::Result<PathBuf> {
+    let canonical = fs::canonicalize(input).unwrap_or_else(|_| input.to_path_buf());
+    let mut hasher = DefaultHasher::new();
+    canonical.hash(&mut hasher);
+    let hash = hasher.finish();
+
+    let stem = input
+        .file_stem()
+        .and_then(|s| s.to_str())
+        .unwrap_or("document");
+    let stem = sanitize_temp_output_stem(stem);
+
+    let root = private_temp_root();
+    ensure_private_dir(&root)?;
+
+    let source_dir = root.join(format!("{:016x}", hash));
+    ensure_private_dir(&source_dir)?;
+
+    Ok(source_dir.join(format!("{stem}.html")))
+}
+
+fn sanitize_temp_output_stem(stem: &str) -> String {
+    let mut sanitized = String::with_capacity(stem.len());
+
+    for ch in stem.chars() {
+        if ch.is_control() || UNSAFE_TEMP_OUTPUT_STEM_CHARS.contains(&ch) {
+            sanitized.push('_');
+        } else {
+            sanitized.push(ch);
+        }
+    }
+
+    if sanitized.chars().any(|ch| ch != '_') {
+        sanitized
+    } else {
+        "document".to_string()
+    }
+}
+
+pub(crate) fn private_temp_root() -> PathBuf {
+    let mut p = std::env::temp_dir();
+    #[cfg(unix)]
+    p.push(format!("mdo-{}", unsafe { libc::geteuid() }));
+    #[cfg(not(unix))]
+    p.push("mdo");
+    p
+}
+
+#[cfg(unix)]
+pub(crate) fn ensure_private_dir(path: &Path) -> io::Result<()> {
+    match fs::symlink_metadata(path) {
+        Ok(metadata) => {
+            let file_type = metadata.file_type();
+            if file_type.is_symlink() || !file_type.is_dir() {
+                return Err(io::Error::new(
+                    io::ErrorKind::AlreadyExists,
+                    format!("{path:?} exists but is not a directory"),
+                ));
+            }
+
+            let uid = unsafe { libc::geteuid() };
+            if metadata.uid() != uid {
+                return Err(io::Error::new(
+                    io::ErrorKind::PermissionDenied,
+                    format!("{path:?} is not owned by the current user"),
+                ));
+            }
+
+            let mode = metadata.permissions().mode();
+            if mode & 0o077 != 0 {
+                fs::set_permissions(path, fs::Permissions::from_mode(mode & !0o077))?;
+            }
+        }
+        Err(e) if e.kind() == io::ErrorKind::NotFound => {
+            let mut builder = fs::DirBuilder::new();
+            builder.mode(0o700);
+            if let Err(create_error) = builder.create(path) {
+                if create_error.kind() == io::ErrorKind::AlreadyExists {
+                    return ensure_private_dir(path);
+                }
+
+                return Err(create_error);
+            }
+        }
+        Err(e) => return Err(e),
+    }
+
+    Ok(())
+}
+
+#[cfg(not(unix))]
+pub(crate) fn ensure_private_dir(path: &Path) -> io::Result<()> {
+    fs::create_dir_all(path)
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    static NEXT_TEMP_FIXTURE_ID: AtomicU64 = AtomicU64::new(0);
+
+    #[test]
+    fn temp_output_stem_replaces_shell_metacharacters() {
+        let input = unique_temp_input("a&calc&.md");
+        let output = temp_output_for(&input).expect("temp path should be built");
+        let file_name = output
+            .file_name()
+            .and_then(|s| s.to_str())
+            .expect("temp path should end with unicode filename");
+
+        assert_eq!(file_name, "a_calc_.html");
+        assert!(!file_name.contains('&'));
+
+        cleanup_temp_fixture(&input, &output);
+    }
+
+    #[test]
+    fn temp_output_stem_keeps_readable_normal_names() {
+        let input = unique_temp_input("résumé-draft_2026.md");
+        let output = temp_output_for(&input).expect("temp path should be built");
+        let file_name = output
+            .file_name()
+            .and_then(|s| s.to_str())
+            .expect("temp path should end with unicode filename");
+
+        assert_eq!(file_name, "résumé-draft_2026.html");
+
+        cleanup_temp_fixture(&input, &output);
+    }
+
+    fn unique_temp_input(file_name: &str) -> PathBuf {
+        let nonce = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("system time should be after epoch")
+            .as_nanos();
+        let counter = NEXT_TEMP_FIXTURE_ID.fetch_add(1, Ordering::Relaxed);
+        let dir = std::env::temp_dir().join(format!(
+            "mdo-unit-test-{}-{nonce}-{counter}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&dir).expect("test temp dir should be created");
+        let input = dir.join(file_name);
+        fs::write(&input, "# Test\n").expect("test input should be written");
+        input
+    }
+
+    fn cleanup_temp_fixture(input: &Path, output: &Path) {
+        if let Some(parent) = output.parent() {
+            let _ = fs::remove_dir_all(parent);
+        }
+        if let Some(parent) = input.parent() {
+            let _ = fs::remove_dir_all(parent);
+        }
+    }
+}
diff --git a/src/watch.rs b/src/watch.rs
new file mode 100644
index 0000000..6ed723a
--- /dev/null
+++ b/src/watch.rs
@@ -0,0 +1,558 @@
+//! Watch-mode mechanics, behind one interface: folder watching, event
+//! relevance, and the trailing-edge debounce.
+//!
+//! The module owns exactly the three mechanics `mdo --watch` needs; the
+//! render itself and how the CLI reports it belong to the caller, passed as
+//! a render callback. `watch::run` registers the watch, runs the callback
+//! once immediately, and then once per settled quiet window whenever the
+//! watched file plausibly changed content. A callback `Err` (e.g. a
+//! transient filesystem state mid-rename) is ignored and never ends watch
+//! mode, matching the CLI's contract; channel death ends the watch
+//! gracefully.
+//!
+//! Both the debounce timing and the loop clock are injectable at the pump
+//! level, so unit tests script fake event channels with a virtual clock and
+//! cover burst collapse, late events, sibling noise, watcher error storms,
+//! and channel death cross-platform by construction.
+
+use std::ffi::OsStr;
+use std::path::{Path, PathBuf};
+use std::sync::mpsc::{self, channel, RecvError, RecvTimeoutError};
+use std::time::{Duration, Instant};
+
+use notify::{recommended_watcher, Event, EventKind, RecursiveMode, Watcher};
+
+use crate::RenderError;
+
+/// Trailing-edge debounce window: once a relevant event arrives the pump
+/// keeps draining/absorbing further relevant events for this long before
+/// rendering, so a burst (e.g. truncate + write, or temp-file write +
+/// rename) collapses into exactly one render of the final content. This is
+/// unlike a leading-edge "ignore anything for N ms after the last render"
+/// debounce, which can drop the trailing event of a burst if the burst runs
+/// longer than the window.
+const DEFAULT_DEBOUNCE: Duration = Duration::from_millis(200);
+
+/// Run watch mode for `input`: register a parent-directory watch, run
+/// `render` once immediately, then re-run it once per settled burst of
+/// events that plausibly changed the file's content.
+///
+/// `render` runs once immediately — before any event is seen — so callers
+/// that must do a one-time thing after the initial render (e.g. the
+/// `--open` browser launch) guard that in their own callback state. Its
+/// `Err` is ignored: a failed render must never end watch mode.
+///
+/// Errors propagate only from registration itself, before any render: a
+/// watch we cannot deliver aborts up front rather than rendering once and
+/// failing later. Once pumping, the loop returns `Ok(())` only when the
+/// watcher channel dies; it otherwise runs until killed.
+pub fn run<F: FnMut() -> Result<(), RenderError>>(
+    input: &Path,
+    render: &mut F,
+) -> notify::Result<()> {
+    // Watch the parent DIRECTORY rather than the file itself. Editors that
+    // save atomically (write a temp file, then rename it over the target)
+    // replace the target's inode; a watch on the file itself goes dead the
+    // moment that happens because the inode/handle notify was watching is
+    // gone. Watching the directory survives renames, deletes, and recreates
+    // — we just have to filter directory events down to ones that touch our
+    // target file.
+    //
+    // Resolve the target once, up front. Comparing later events against
+    // this fixed absolute path — rather than re-canonicalizing each event's
+    // path — matters because the target may momentarily not exist
+    // mid-rename, which would make canonicalize fail and misclassify a
+    // perfectly relevant event.
+    //
+    // Known limitation: canonicalizing a symlinked input means we watch the
+    // TARGET's parent, so edits made through the link are seen, but an
+    // editor atomically replacing the symlink itself is not. Watching both
+    // parents isn't worth the complexity until someone actually hits this.
+    let input_absolute = std::fs::canonicalize(input).unwrap_or_else(|_| {
+        std::env::current_dir()
+            .map(|cwd| cwd.join(input))
+            .unwrap_or_else(|_| input.to_path_buf())
+    });
+    let watch_dir = input_absolute
+        .parent()
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("."));
+    let target_file_name = input_absolute.file_name().map(|n| n.to_os_string());
+
+    // Register the watch BEFORE the initial render so a save that lands
+    // while that render runs is queued by the watcher rather than silently
+    // lost; the pump below drains it and re-renders. Registration
+    // failure aborts before any rendering, which is fine — the user asked
+    // for a watch we cannot deliver.
+
+    let (tx, rx) = channel();
+    let mut watcher = recommended_watcher(tx)?;
+    watcher.watch(&watch_dir, RecursiveMode::NonRecursive)?;
+
+    let _ = render();
+
+    // Still named after the file, not the directory: that's what the user
+    // asked to watch, even though the underlying notify watch is scoped one
+    // level up.
+    println!("👀 Watching {:?} for changes... (Ctrl+C to stop)", input);
+
+    pump(
+        &rx,
+        &watch_dir,
+        target_file_name.as_deref(),
+        render,
+        DEFAULT_DEBOUNCE,
+        &SystemClock,
+    );
+    Ok(())
+}
+
+/// The event pump: block for the next event, skip everything that isn't a
+/// relevant change to the target file, drain/absorb bursts through the
+/// trailing-edge debounce window, then render once per settled burst.
+///
+/// `debounce` and `clock` are the injectable timing seams (unit tests
+/// script relative arrival times against a virtual clock; production uses
+/// the system monotonic clock).
+fn pump<R: EventRx, F: FnMut() -> Result<(), RenderError>, C: Clock>(
+    rx: &R,
+    watch_dir: &Path,
+    target_file_name: Option<&OsStr>,
+    render: &mut F,
+    debounce: Duration,
+    clock: &C,
+) {
+    loop {
+        // Block for the next event. Anything that isn't a relevant,
+        // content-changing event (wrong file, Access events, watcher
+        // errors) is skipped without starting a debounce window.
+        let event = match rx.recv() {
+            Ok(Ok(event)) => event,
+            Ok(Err(e)) => {
+                eprintln!("⚠️  Watcher error: {}", e);
+                continue;
+            }
+            Err(_) => return, // watcher/channel gone; nothing left to watch
+        };
+
+        if !is_relevant_event(&event, target_file_name, watch_dir) {
+            continue;
+        }
+
+        // Drain/absorb further relevant events for a quiet window, then
+        // render once. This covers direct writes, truncate+rewrite, and
+        // atomic saves (temp file write followed by a rename onto the
+        // target) uniformly: whichever event kinds the editor and platform
+        // happen to emit (Create, Modify, Rename-as-Modify(Name), Remove
+        // followed by a Create), each just extends the quiet window until
+        // the burst settles. Only RELEVANT events extend the deadline:
+        // sibling-file noise merely waits out the remaining window, so a
+        // busy directory (a build churning artifacts next to the watched
+        // file) cannot postpone the render indefinitely.
+        let mut deadline = clock.now() + debounce;
+        loop {
+            let remaining = deadline.saturating_duration_since(clock.now());
+            if remaining.is_zero() {
+                break;
+            }
+            match rx.recv_timeout(remaining) {
+                Ok(Ok(event)) => {
+                    if is_relevant_event(&event, target_file_name, watch_dir) {
+                        deadline = clock.now() + debounce;
+                    }
+                    // Irrelevant events neither extend nor cut the window.
+                }
+                Ok(Err(e)) => eprintln!("⚠️  Watcher error: {}", e),
+                Err(_) => break, // quiet window elapsed (or channel closed)
+            }
+        }
+
+        println!("🔁 File changed, re-rendering...");
+        // A failed render (e.g. one that ran while the file was momentarily
+        // absent mid-rename) must not end watch mode; its reporting already
+        // happened inside the callback, so just loop and wait for the next
+        // event.
+        let _ = render();
+    }
+}
+
+/// True if `event` plausibly changed the content of the file named
+/// `target_file_name` inside `watch_dir`. We match by file name (and, when
+/// notify reports one, by parent directory) rather than canonicalizing the
+/// event's path, since the target can momentarily not exist mid-rename.
+/// Access events (reads, permission-bit-only changes) are excluded; every
+/// other kind (Create, Modify, Remove, Any, Other) is treated as a possible
+/// content change so recreation-after-remove and atomic renames are all
+/// covered by the same check.
+fn is_relevant_event(event: &Event, target_file_name: Option<&OsStr>, watch_dir: &Path) -> bool {
+    if matches!(event.kind, EventKind::Access(_)) {
+        return false;
+    }
+
+    let Some(target_file_name) = target_file_name else {
+        return false;
+    };
+
+    event.paths.iter().any(|p| {
+        p.file_name() == Some(target_file_name)
+            && match p.parent() {
+                Some(parent) => parent == watch_dir,
+                None => true,
+            }
+    })
+}
+
+/// One item on the watch event channel: a real event, or a watcher-level
+/// error delivered as a channel payload (the queue keeps flowing either
+/// way).
+type EventItem = Result<Event, notify::Error>;
+
+/// The receiving half of the watch event channel narrowed to the exact
+/// shape the pump uses. Abstracted so unit tests script fake sequences.
+trait EventRx {
+    fn recv(&self) -> Result<EventItem, RecvError>;
+    fn recv_timeout(&self, timeout: Duration) -> Result<EventItem, RecvTimeoutError>;
+}
+
+impl EventRx for mpsc::Receiver<EventItem> {
+    fn recv(&self) -> Result<EventItem, RecvError> {
+        mpsc::Receiver::recv(self)
+    }
+
+    fn recv_timeout(&self, timeout: Duration) -> Result<EventItem, RecvTimeoutError> {
+        mpsc::Receiver::recv_timeout(self, timeout)
+    }
+}
+
+/// Where the pump reads its clock. Production uses the system monotonic
+/// clock; tests inject a virtual one.
+trait Clock {
+    fn now(&self) -> Instant;
+}
+
+struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now(&self) -> Instant {
+        Instant::now()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::Cell;
+    use std::cell::RefCell;
+    use std::collections::VecDeque;
+    use std::rc::Rc;
+
+    use notify::event::{AccessKind, ModifyKind};
+
+    /// Virtual monotonic clock shared with the fake channel: entries in a
+    /// script declare how long after "now" their payload is ready.
+    #[derive(Clone)]
+    struct VirtualClock(Rc<Cell<Instant>>);
+
+    impl VirtualClock {
+        fn new() -> Self {
+            Self(Rc::new(Cell::new(Instant::now())))
+        }
+
+        fn advance(&self, by: Duration) {
+            self.0.set(self.0.get() + by);
+        }
+    }
+
+    impl Clock for VirtualClock {
+        fn now(&self) -> Instant {
+            self.0.get()
+        }
+    }
+
+    /// One scripted channel entry: a payload plus how long after the
+    /// current virtual time it becomes available.
+    struct Scripted {
+        ready_after: Duration,
+        payload: EventItem,
+    }
+
+    /// Fake channel half driving `pump` from a script. Events ready within
+    /// the polled timeout are delivered on that poll; anything later goes
+    /// past the window (timed out), exactly as a real channel would.
+    struct FakeRx {
+        clock: VirtualClock,
+        script: RefCell<VecDeque<Scripted>>,
+    }
+
+    impl FakeRx {
+        fn now_or_elapsed(&self, timeout: Duration) -> Result<EventItem, RecvTimeoutError> {
+            let next = self.script.borrow().front().map(|s| s.ready_after);
+            match next {
+                Some(ready_after) if ready_after <= timeout => {
+                    self.clock.advance(ready_after);
+                    let scripted = self
+                        .script
+                        .borrow_mut()
+                        .pop_front()
+                        .expect("front checked above");
+                    Ok(scripted.payload)
+                }
+                _ => {
+                    self.clock.advance(timeout);
+                    Err(RecvTimeoutError::Timeout)
+                }
+            }
+        }
+    }
+
+    impl EventRx for FakeRx {
+        fn recv(&self) -> Result<EventItem, RecvError> {
+            match self.script.borrow_mut().pop_front() {
+                Some(scripted) => {
+                    self.clock.advance(scripted.ready_after);
+                    Ok(scripted.payload)
+                }
+                None => Err(RecvError),
+            }
+        }
+
+        fn recv_timeout(&self, timeout: Duration) -> Result<EventItem, RecvTimeoutError> {
+            self.now_or_elapsed(timeout)
+        }
+    }
+
+    fn event_ready_after(ready_after: u64, kind: EventKind, path: PathBuf) -> Scripted {
+        Scripted {
+            ready_after: Duration::from_millis(ready_after),
+            payload: Ok(Event::new(kind).add_path(path)),
+        }
+    }
+
+    fn watcher_error_after(ready_after: u64) -> Scripted {
+        Scripted {
+            ready_after: Duration::from_millis(ready_after),
+            payload: Err(notify::Error::io(std::io::Error::other("watcher failed"))),
+        }
+    }
+
+    /// A content-changing event for `name` inside `watch_dir`.
+    fn modify(name: &str, watch_dir: &Path, ready_after: u64) -> Scripted {
+        event_ready_after(
+            ready_after,
+            EventKind::Modify(ModifyKind::Any),
+            watch_dir.join(name),
+        )
+    }
+
+    /// A change to a file that is not the watched target.
+    fn sibling(name: &str, watch_dir: &Path, ready_after: u64) -> Scripted {
+        event_ready_after(
+            ready_after,
+            EventKind::Modify(ModifyKind::Any),
+            watch_dir.join(name),
+        )
+    }
+
+    fn access(watch_dir: &Path, ready_after: u64) -> Scripted {
+        event_ready_after(
+            ready_after,
+            EventKind::Access(AccessKind::Any),
+            watch_dir.join("sample.md"),
+        )
+    }
+
+    /// Pump over a script, counting renders in the callback.
+    fn pump_scripted(script: Vec<Scripted>) -> (usize, VirtualClock) {
+        let clock = VirtualClock::new();
+        let renders = Rc::new(Cell::new(0_usize));
+        let rx = FakeRx {
+            clock: clock.clone(),
+            script: RefCell::new(script.into()),
+        };
+        pump(
+            &rx,
+            Path::new("/watch"),
+            Some(OsStr::new("sample.md")),
+            &mut || {
+                renders.set(renders.get() + 1);
+                Ok(())
+            },
+            Duration::from_millis(200),
+            &clock,
+        );
+        (renders.get(), clock)
+    }
+
+    #[test]
+    fn burst_collapses_into_one_render() {
+        // Three events inside one window: one render of the final content.
+        let (renders, _clock) = pump_scripted(vec![
+            modify("sample.md", Path::new("/watch"), 50),
+            modify("sample.md", Path::new("/watch"), 70),
+            modify("sample.md", Path::new("/watch"), 60),
+        ]);
+        assert_eq!(renders, 1, "a settled burst renders exactly once");
+    }
+
+    #[test]
+    fn burst_running_longer_than_window_still_renders_the_trailing_event() {
+        // Events every 80ms outrun a 200ms quiet window for a while; no
+        // render fires mid-burst — the trailing event is never dropped.
+        let (renders, _clock) = pump_scripted(vec![
+            modify("sample.md", Path::new("/watch"), 50),
+            modify("sample.md", Path::new("/watch"), 80),
+            modify("sample.md", Path::new("/watch"), 80),
+            modify("sample.md", Path::new("/watch"), 80),
+            modify("sample.md", Path::new("/watch"), 80),
+        ]);
+        assert_eq!(renders, 1, "a long burst settles into exactly one render");
+    }
+
+    #[test]
+    fn event_after_the_window_renders_again() {
+        // One burst, then quiet past the window, then another event: the
+        // first event settles into render one; the late event is NOT
+        // dropped — it becomes the next outer event and renders again.
+        let (renders, _clock) = pump_scripted(vec![
+            modify("sample.md", Path::new("/watch"), 50),
+            modify("sample.md", Path::new("/watch"), 700),
+        ]);
+        assert_eq!(renders, 2, "events after the window are fresh triggers");
+    }
+
+    #[test]
+    fn sibling_noise_renders_nothing() {
+        // Sibling-file churn alone never triggers or extends a window.
+        let (renders, _clock) = pump_scripted(vec![
+            sibling("other.md", Path::new("/watch"), 50),
+            sibling("build.log", Path::new("/watch"), 80),
+        ]);
+        assert_eq!(renders, 0, "no target file in any event, no render");
+    }
+
+    #[test]
+    fn sibling_noise_waits_out_but_does_not_extend_the_window() {
+        // A sibling event arriving well past the current window cannot
+        // extend the deadline: the pump waits out only the remaining window
+        // (bounded by one debounce) and renders; the sibling is then seen
+        // as the next outer event, classified irrelevant, and skipped.
+        let (renders, _clock) = pump_scripted(vec![
+            modify("sample.md", Path::new("/watch"), 50),
+            sibling("other.md", Path::new("/watch"), 1000),
+        ]);
+        assert_eq!(renders, 1, "the sibling burst never postponed the render");
+    }
+
+    #[test]
+    fn access_events_are_never_relevant() {
+        let (renders, _clock) = pump_scripted(vec![access(Path::new("/watch"), 50)]);
+        assert_eq!(renders, 0, "Access events are excluded");
+    }
+
+    #[test]
+    fn channel_death_before_any_event_ends_the_watch_gracefully() {
+        let (renders, _clock) = pump_scripted(vec![]);
+        assert_eq!(renders, 0);
+    }
+
+    #[test]
+    fn channel_death_during_drain_renders_and_exits() {
+        // An event lands, the window is open, the channel dies: the
+        // pending burst still renders, then the watch ends.
+        let (renders, _clock) = pump_scripted(vec![modify("sample.md", Path::new("/watch"), 50)]);
+        assert_eq!(renders, 1);
+    }
+
+    #[test]
+    fn watcher_error_storm_renders_nothing_and_survives() {
+        let script: Vec<Scripted> = (0..50u64)
+            .map(|i| watcher_error_after(i * 10 + 1))
+            .collect();
+        let (renders, _clock) = pump_scripted(script);
+        assert_eq!(renders, 0, "watcher errors are not renders");
+    }
+
+    #[test]
+    fn watcher_errors_inside_the_drain_do_not_extend_the_window() {
+        // Errors arriving inside a window neither extend nor cut it: they
+        // wait out the remaining window like any other noise.
+        let script = vec![
+            modify("sample.md", Path::new("/watch"), 50),
+            watcher_error_after(60),
+            watcher_error_after(60),
+        ];
+        let (renders, _clock) = pump_scripted(script);
+        assert_eq!(renders, 1);
+    }
+
+    #[test]
+    fn callback_errors_never_end_watch_mode() {
+        // A render callback that reports a transient filesystem failure
+        // (e.g. the file was absent mid-rename) must not end watch mode.
+        let clock = VirtualClock::new();
+        let renders = Rc::new(Cell::new(0_usize));
+        let failures = Rc::new(Cell::new(0_usize));
+        let rx = FakeRx {
+            clock: clock.clone(),
+            script: RefCell::new(
+                vec![
+                    // Two bursts separated past the window: render One and
+                    // render two must BOTH happen for the errors never to
+                    // have ended watch mode.
+                    modify("sample.md", Path::new("/watch"), 50),
+                    modify("sample.md", Path::new("/watch"), 700),
+                ]
+                .into(),
+            ),
+        };
+        let renders_flag = renders.clone();
+        let failures_flag = failures.clone();
+        pump(
+            &rx,
+            Path::new("/watch"),
+            Some(OsStr::new("sample.md")),
+            &mut || {
+                renders_flag.set(renders_flag.get() + 1);
+                failures_flag.set(failures_flag.get() + 1);
+                Err(RenderError::Read {
+                    path: PathBuf::from("/watch/sample.md"),
+                    source: std::io::Error::other("transient"),
+                })
+            },
+            Duration::from_millis(200),
+            &clock,
+        );
+        assert_eq!(renders.get(), 2, "every burst was rendered");
+        assert_eq!(failures.get(), 2, "every callback Err surfaced to it");
+    }
+
+    #[test]
+    fn relevance_requires_name_and_parent_match() {
+        let watch_dir = Path::new("/watch");
+        let named = Some(OsStr::new("sample.md"));
+
+        let same_dir =
+            Event::new(EventKind::Modify(ModifyKind::Any)).add_path(watch_dir.join("sample.md"));
+        assert!(is_relevant_event(&same_dir, named, watch_dir));
+
+        // A bare relative path has parent Some("") — never equal to a real
+        // watch dir, so it is not relevant. Real events carry absolute
+        // paths, so this only matters to the filter's strictness, not to
+        // production labeling.
+        let bare_relative =
+            Event::new(EventKind::Modify(ModifyKind::Any)).add_path(PathBuf::from("sample.md"));
+        assert!(!is_relevant_event(&bare_relative, named, watch_dir));
+
+        let other_dir = Event::new(EventKind::Modify(ModifyKind::Any))
+            .add_path(PathBuf::from("/elsewhere/sample.md"));
+        assert!(!is_relevant_event(&other_dir, named, watch_dir));
+
+        let other_name =
+            Event::new(EventKind::Modify(ModifyKind::Any)).add_path(watch_dir.join("other.md"));
+        assert!(!is_relevant_event(&other_name, named, watch_dir));
+
+        // No resolvable target: nothing is ever relevant.
+        let none: Option<&OsStr> = None;
+        assert!(!is_relevant_event(&same_dir, none, watch_dir));
+    }
+}
diff --git a/tests/cli.rs b/tests/cli.rs
index f426c92..124b056 100644
--- a/tests/cli.rs
+++ b/tests/cli.rs
@@ -838,58 +838,6 @@ fn watch_survives_atomic_rename() {
     fs::remove_dir_all(dir).expect("failed to clean up temp fixture dir");
 }
 
-#[cfg(unix)]
-#[test]
-fn watch_ignores_sibling_changes() {
-    use std::process::Stdio;
-
-    let dir = fixture_dir("watch-sibling-changes");
-    let input = dir.join("sample.md");
-    let output_path = dir.join("sample.html");
-    let sibling = dir.join("other.md");
-    fs::write(&input, "# Initial\n").expect("failed to write markdown fixture");
-
-    let child = Command::new(env!("CARGO_BIN_EXE_mdo"))
-        .arg("--watch")
-        .arg(&input)
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()
-        .expect("failed to spawn mdo --watch");
-    let _guard = WatchGuard(child);
-
-    assert!(
-        wait_for_file_containing(&output_path, "Initial", Duration::from_secs(10)),
-        "initial render should appear within the timeout"
-    );
-    let rendered_before =
-        fs::read_to_string(&output_path).expect("failed to read initial rendered output");
-    let mtime_before = fs::metadata(&output_path)
-        .and_then(|m| m.modified())
-        .expect("failed to read initial rendered output mtime");
-
-    fs::write(&sibling, "# Sibling\n\nUnrelated file.\n")
-        .expect("failed to write sibling markdown file");
-    std::thread::sleep(Duration::from_secs(1));
-
-    // A sibling-file event must not trigger a re-render. Byte-comparing the
-    // output alone is not conclusive — the embedded generated date is
-    // day-granular and fast renders can format to the same duration — so
-    // also require the file's mtime (nanosecond granularity on Linux) to be
-    // untouched: any rewrite, even byte-identical, would bump it.
-    let rendered_after = fs::read_to_string(&output_path)
-        .expect("failed to read rendered output after sibling change");
-    let mtime_after = fs::metadata(&output_path)
-        .and_then(|m| m.modified())
-        .expect("failed to read rendered output mtime after sibling change");
-    assert_eq!(
-        rendered_before, rendered_after,
-        "watch mode should not re-render sample.html for changes to an unrelated sibling file"
-    );
-    assert_eq!(
-        mtime_before, mtime_after,
-        "sample.html should not have been rewritten (mtime changed) for a sibling-file change"
-    );
-
-    fs::remove_dir_all(dir).expect("failed to clean up temp fixture dir");
-}
+// Sibling-noise and burst semantics moved into src/watch.rs unit tests
+// (fake event channel + virtual clock, cross-platform by construction);
+// this file keeps only the spawned-binary e2e smoke test.