feat(vfs/opfs): add root-scoped VFS and extract lock/path modules

Introduce `OpfsVfs::with_root(worker_url, root)` so multiple independent
databases can coexist in the same browser origin without colliding on the
shared OPFS path namespace.  `OpfsVfs::new` becomes a thin wrapper that
passes an empty root, preserving the existing layout.

Path resolution is centralised in `OpfsVfs::resolve`, which delegates to
the new `path` module (`normalize_root` + `join_root`).  Keeping the
helpers in a target-independent file lets them be unit-tested on the host
even though the rest of the OPFS backend is wasm-only.

The lock manager (`LockMap` / `OpfsLockHandle`) is moved from `vfs_impl`
into its own `lock` module so each file has a single responsibility.
`OpfsLockHandle` is re-exported from `opfs::lock` rather than
`opfs::vfs_impl`; the public path (`opfs::OpfsLockHandle`) is unchanged.

Additional cleanup in the same pass:
- Replace `std::io::Error::new(ErrorKind::Other, …)` with the
  `std::io::Error::other(…)` shorthand throughout the OPFS backend.
- Use `std::sync::PoisonError::into_inner` as the closure directly
  instead of the `|e| e.into_inner()` lambda form.

Author: farhan-syah

src/vfs/opfs/handle.rs

@@ -172,9 +172,6 @@ pub(crate) fn map_err(reason: &str, kind: ErrKind) -> PagedbError {
             PagedbError::Io(std::io::Error::from(std::io::ErrorKind::AlreadyExists))
         }
         ErrKind::PermissionDenied => PagedbError::ReadOnly,
-        ErrKind::Io | ErrKind::Other => PagedbError::Io(std::io::Error::new(
-            std::io::ErrorKind::Other,
-            reason.to_string(),
-        )),
+        ErrKind::Io | ErrKind::Other => PagedbError::Io(std::io::Error::other(reason.to_string())),
     }
 }

src/vfs/opfs/lock.rs

@@ -0,0 +1,85 @@
+//! In-process advisory file locking for the OPFS VFS.
+//!
+//! OPFS itself exposes no cross-handle locking primitive, so `OpfsVfs`
+//! arbitrates `lock_exclusive` / `lock_shared` within the single browser JS
+//! realm using the [`LockMap`] reference-counted table. [`OpfsLockHandle`] is
+//! the RAII guard handed back to callers; dropping it releases the lock.
+
+#![cfg(all(target_arch = "wasm32", feature = "opfs"))]
+// The unsafe Send + Sync impls below are required to satisfy `Vfs: Send + Sync`
+// on wasm32. Safety justification is on the impl blocks.
+#![allow(unsafe_code)]
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+#[derive(Clone, Copy)]
+enum LockKind {
+    Exclusive,
+    Shared,
+}
+
+/// Reference-counted advisory lock table keyed by resolved path.
+#[derive(Default)]
+pub(super) struct LockMap {
+    entries: HashMap<String, (LockKind, u32)>,
+}
+
+impl LockMap {
+    pub(super) fn try_exclusive(&mut self, path: &str) -> bool {
+        if self.entries.contains_key(path) {
+            return false;
+        }
+        self.entries
+            .insert(path.to_string(), (LockKind::Exclusive, 1));
+        true
+    }
+
+    pub(super) fn try_shared(&mut self, path: &str) -> bool {
+        match self.entries.get_mut(path) {
+            None => {
+                self.entries.insert(path.to_string(), (LockKind::Shared, 1));
+                true
+            }
+            Some((LockKind::Shared, n)) => {
+                *n += 1;
+                true
+            }
+            Some((LockKind::Exclusive, _)) => false,
+        }
+    }
+
+    pub(super) fn release(&mut self, path: &str) {
+        let remove = match self.entries.get_mut(path) {
+            Some((_, n)) if *n <= 1 => true,
+            Some((_, n)) => {
+                *n -= 1;
+                false
+            }
+            None => false,
+        };
+        if remove {
+            self.entries.remove(path);
+        }
+    }
+}
+
+/// RAII advisory lock handle returned by `lock_exclusive` / `lock_shared`.
+pub struct OpfsLockHandle {
+    pub(super) path: String,
+    pub(super) locks: Arc<Mutex<LockMap>>,
+}
+
+// SAFETY: wasm32 is single-threaded by browser spec. All access to
+// OpfsLockHandle happens on the spawning thread. The Arc<Mutex<LockMap>>
+// field contains no JS types and is naturally Send+Sync.
+unsafe impl Send for OpfsLockHandle {}
+unsafe impl Sync for OpfsLockHandle {}
+
+impl Drop for OpfsLockHandle {
+    fn drop(&mut self) {
+        if let Ok(mut map) = self.locks.lock() {
+            map.release(&self.path);
+        }
+    }
+}

src/vfs/opfs/mod.rs

@@ -20,17 +20,25 @@
 //! target (or when the `opfs` feature is absent) a thin shim is compiled
 //! instead; every method returns [`crate::errors::PagedbError::Unsupported`].
 
+// Pure path-rooting helpers — target-independent so they are unit-testable on
+// the host even though the OPFS backend itself is wasm-only.
+mod path;
+
 #[cfg(all(target_arch = "wasm32", feature = "opfs"))]
 mod handle;
 #[cfg(all(target_arch = "wasm32", feature = "opfs"))]
+mod lock;
+#[cfg(all(target_arch = "wasm32", feature = "opfs"))]
 mod protocol;
 #[cfg(all(target_arch = "wasm32", feature = "opfs"))]
 mod vfs_impl;
 
 #[cfg(all(target_arch = "wasm32", feature = "opfs"))]
 pub use handle::OpfsFile;
 #[cfg(all(target_arch = "wasm32", feature = "opfs"))]
-pub use vfs_impl::{OpfsLockHandle, OpfsVfs};
+pub use lock::OpfsLockHandle;
+#[cfg(all(target_arch = "wasm32", feature = "opfs"))]
+pub use vfs_impl::OpfsVfs;
 
 /// Embedded source of the pure-JS OPFS Web Worker.
 ///
@@ -62,6 +70,11 @@ mod shim {
         pub fn new(_worker_url: &str) -> Result<Self> {
             Err(PagedbError::Unsupported)
         }
+
+        /// Always returns `Err(PagedbError::Unsupported)`.
+        pub fn with_root(_worker_url: &str, _root: &str) -> Result<Self> {
+            Err(PagedbError::Unsupported)
+        }
     }
 
     pub struct OpfsFileShim;

src/vfs/opfs/path.rs

@@ -0,0 +1,84 @@
+//! Pure path helpers for the OPFS VFS root-prefixing scheme.
+//!
+//! The OPFS backend only compiles for `wasm32 + opfs`, but the rooting logic is
+//! plain string manipulation. Keeping it here as target-independent free
+//! functions lets it be unit-tested on the host even though the rest of the
+//! backend cannot be. `OpfsVfs` (wasm) is the sole production caller, so on
+//! every other target these are legitimately dead — hence the `allow`.
+
+/// Normalise a caller-supplied root directory into a single leading-slash
+/// prefix, or the empty string when no rooting is requested.
+///
+/// Surrounding slashes are trimmed: `"db"`, `"/db"`, and `"/db/"` all map to
+/// `"/db"`; `""`, `"/"`, and `"///"` map to `""` (legacy origin-root layout).
+#[cfg_attr(not(all(target_arch = "wasm32", feature = "opfs")), allow(dead_code))]
+pub(super) fn normalize_root(root: &str) -> String {
+    let trimmed = root.trim_matches('/');
+    if trimmed.is_empty() {
+        String::new()
+    } else {
+        format!("/{trimmed}")
+    }
+}
+
+/// Join a virtual VFS path under a normalised root.
+///
+/// pagedb hands the VFS origin-relative *virtual* paths (e.g. `/main.db`); the
+/// native `TokioVfs` joins them onto its on-disk root the same way. The leading
+/// `/` is stripped and the remainder joined under `root` with exactly one
+/// separator, so the result is correct whether `path` arrives absolute
+/// (`/main.db`) or relative (`main.db`) — it never glues into `/dbmain.db`. An
+/// empty `root` returns `path` unchanged, preserving the legacy layout exactly.
+#[cfg_attr(not(all(target_arch = "wasm32", feature = "opfs")), allow(dead_code))]
+pub(super) fn join_root(root: &str, path: &str) -> String {
+    if root.is_empty() {
+        path.to_string()
+    } else {
+        format!("{}/{}", root, path.trim_start_matches('/'))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalize_trims_surrounding_slashes() {
+        assert_eq!(normalize_root("db"), "/db");
+        assert_eq!(normalize_root("/db"), "/db");
+        assert_eq!(normalize_root("/db/"), "/db");
+        assert_eq!(normalize_root("a/b"), "/a/b");
+    }
+
+    #[test]
+    fn normalize_empty_or_slash_only_means_no_root() {
+        assert_eq!(normalize_root(""), "");
+        assert_eq!(normalize_root("/"), "");
+        assert_eq!(normalize_root("///"), "");
+    }
+
+    #[test]
+    fn join_uses_single_separator_regardless_of_leading_slash() {
+        // Absolute virtual path — how pagedb actually calls the VFS.
+        assert_eq!(join_root("/db", "/main.db"), "/db/main.db");
+        // Relative virtual path — must NOT glue into "/dbmain.db".
+        assert_eq!(join_root("/db", "main.db"), "/db/main.db");
+        // Nested segments are preserved.
+        assert_eq!(join_root("/db", "/segments/seg-1"), "/db/segments/seg-1");
+    }
+
+    #[test]
+    fn empty_root_passes_path_through_unchanged() {
+        assert_eq!(join_root("", "/main.db"), "/main.db");
+        assert_eq!(join_root("", "main.db"), "main.db");
+    }
+
+    #[test]
+    fn distinct_roots_never_collide_on_the_fixed_main_db_path() {
+        let a = join_root(&normalize_root("alpha"), "/main.db");
+        let b = join_root(&normalize_root("beta"), "/main.db");
+        assert_eq!(a, "/alpha/main.db");
+        assert_eq!(b, "/beta/main.db");
+        assert_ne!(a, b);
+    }
+}