@statewalker/webrun-files-browser 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @statewalker/webrun-files-browser
+
+Browser File System Access API implementation for the `@statewalker/webrun-files` package.
+
+## Overview
+
+This package provides an `IFilesApi` implementation that works in modern browsers using the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API). It allows web applications to read and write files to:
+
+- **User-selected directories** via `showDirectoryPicker()`
+- **Origin Private File System (OPFS)** - a sandboxed filesystem that persists between sessions
+
+## Installation
+
+```bash
+npm install @statewalker/webrun-files-browser @statewalker/webrun-files
+```
+
+## Usage
+
+### With User-Selected Directory
+
+```typescript
+import { openBrowserFilesApi } from "@statewalker/webrun-files-browser";
+import { FilesApi } from "@statewalker/webrun-files";
+
+// Opens a directory picker dialog (requires user gesture)
+const browserFs = await openBrowserFilesApi();
+const api = new FilesApi(browserFs);
+
+// Write a file
+await api.write("/notes/hello.txt", [
+  new TextEncoder().encode("Hello, World!")
+]);
+
+// Read a file
+const content = await api.readFile("/notes/hello.txt");
+console.log(new TextDecoder().decode(content)); // "Hello, World!"
+
+// List directory contents
+for await (const entry of api.list("/notes")) {
+  console.log(entry.name, entry.kind);
+}
+```
+
+### With Origin Private File System (OPFS)
+
+OPFS provides a sandboxed filesystem that doesn't require user interaction:
+
+```typescript
+import { getOPFSFilesApi } from "@statewalker/webrun-files-browser";
+import { FilesApi } from "@statewalker/webrun-files";
+
+// No user gesture required
+const opfsFs = await getOPFSFilesApi();
+const api = new FilesApi(opfsFs);
+
+// Use the same API as above
+await api.write("/data/config.json", [
+  new TextEncoder().encode('{"theme": "dark"}')
+]);
+```
+
+### With Custom Directory Handle
+
+You can also create a `BrowserFilesApi` instance with any `FileSystemDirectoryHandle`:
+
+```typescript
+import { BrowserFilesApi } from "@statewalker/webrun-files-browser";
+import { FilesApi } from "@statewalker/webrun-files";
+
+// Get a directory handle from drag & drop, IndexedDB, etc.
+const directoryHandle = await getDirectoryHandleSomehow();
+
+const browserFs = new BrowserFilesApi({ rootHandle: directoryHandle });
+const api = new FilesApi(browserFs);
+```
+
+## API Reference
+
+### BrowserFilesApi
+
+Main class implementing `IFilesApi` for browser environments.
+
+```typescript
+interface BrowserFilesApiOptions {
+  rootHandle: FileSystemDirectoryHandle;
+}
+
+class BrowserFilesApi implements IFilesApi {
+  constructor(options: BrowserFilesApiOptions);
+
+  // Core IFilesApi methods
+  list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo>;
+  stats(file: FileRef): Promise<FileInfo | undefined>;
+  remove(file: FileRef): Promise<boolean>;
+  open(file: FileRef): Promise<FileHandle>;
+
+  // Optional methods (implemented)
+  mkdir(file: FileRef): Promise<void>;
+  move(source: FileRef, target: FileRef): Promise<boolean>;
+  copy(source: FileRef, target: FileRef, options?: CopyOptions): Promise<boolean>;
+}
+```
+
+### BrowserFileHandle
+
+File handle class for random access read/write operations.
+
+```typescript
+class BrowserFileHandle implements FileHandle {
+  readonly size: number;
+
+  close(): Promise<void>;
+  appendFile(data: BinaryStream, options?: AppendOptions): Promise<number>;
+  createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
+  createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
+}
+```
+
+### Helper Functions
+
+```typescript
+// Opens a directory picker and returns a BrowserFilesApi instance
+function openBrowserFilesApi(): Promise<BrowserFilesApi>;
+
+// Returns a BrowserFilesApi backed by the Origin Private File System
+function getOPFSFilesApi(): Promise<BrowserFilesApi>;
+```
+
+## How It Works
+
+### Directory Navigation
+
+The implementation navigates the filesystem by traversing `FileSystemDirectoryHandle` entries. Paths like `/docs/notes/file.txt` are resolved by getting directory handles step by step:
+
+```
+root → "docs" → "notes" → "file.txt"
+```
+
+### Reading Files
+
+Files are read using `File.slice()` for efficient partial reads. This enables random access without loading the entire file into memory:
+
+```typescript
+const handle = await api.open("/large-file.bin");
+// Read only bytes 1000-2000
+for await (const chunk of handle.createReadStream({ start: 1000, end: 2000 })) {
+  console.log(chunk);
+}
+await handle.close();
+```
+
+### Writing Files
+
+Writes use `FileSystemWritableFileStream`:
+
+- **Full writes** create a new writable stream and write all data
+- **Partial writes** (with `start` option) preserve content before the start position
+- **Appends** seek to the end of the file before writing
+
+### Directory Creation
+
+Directories are created automatically when writing files. You can also create empty directories:
+
+```typescript
+await api.mkdir("/path/to/new/directory");
+```
+
+## Browser Support
+
+The File System Access API is supported in:
+
+- Chrome/Edge 86+
+- Opera 72+
+- Chrome for Android 86+
+
+For other browsers, you may need a polyfill like [native-file-system-adapter](https://github.com/nicolo-ribaudo/native-file-system-adapter).
+
+## Security Considerations
+
+- **User gesture required**: `showDirectoryPicker()` must be called from a user gesture (click, key press)
+- **Secure context**: The API only works in secure contexts (HTTPS or localhost)
+- **Permission prompts**: Users must grant permission to access directories
+- **OPFS isolation**: Origin Private File System is isolated per-origin and not accessible to the user
+
+## Testing
+
+For testing in Node.js environments, we use [native-file-system-adapter](https://github.com/jimmywarting/native-file-system-adapter) which provides a memory backend:
+
+```typescript
+import { getOriginPrivateDirectory } from "native-file-system-adapter";
+import { BrowserFilesApi } from "@statewalker/webrun-files-browser";
+
+const rootHandle = await getOriginPrivateDirectory(
+  import("native-file-system-adapter/src/adapters/memory.js")
+);
+
+const api = new BrowserFilesApi({ rootHandle });
+```
+
+## License
+
+MIT

package/dist/browser-file-handle.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Browser FileHandle implementation using File System Access API.
+ *
+ * Provides random access read/write operations for browser files.
+ * Uses File.slice() for efficient partial reads and FileSystemWritableFileStream
+ * for writes.
+ */
+import type { AppendOptions, BinaryStream, FileHandle, ReadStreamOptions, WriteStreamOptions } from "@statewalker/webrun-files";
+export interface BrowserFileHandleOptions {
+    fileHandle: FileSystemFileHandle;
+    initialFile: File;
+}
+export declare class BrowserFileHandle implements FileHandle {
+    private fileHandle;
+    private file;
+    private _size;
+    private closed;
+    constructor(options: BrowserFileHandleOptions);
+    get size(): number;
+    close(): Promise<void>;
+    /**
+     * Appends data to the end of the file.
+     */
+    appendFile(data: BinaryStream, options?: AppendOptions): Promise<number>;
+    /**
+     * Creates a read stream for the file.
+     * Uses File.slice() for efficient partial reads.
+     */
+    createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
+    /**
+     * Writes data to the file starting at the specified position.
+     * If start > 0, preserves content before start position.
+     * Truncates file at start position before writing.
+     */
+    createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
+    /**
+     * Random access read from file at a specific position.
+     * Uses File.slice() for efficient partial reads.
+     */
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
+}
+//# sourceMappingURL=browser-file-handle.d.ts.map

package/dist/browser-file-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-file-handle.d.ts","sourceRoot":"","sources":["../src/browser-file-handle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,oBAAoB,CAAC;IACjC,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,wBAAwB;IAM7C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgClF;;;OAGG;IACI,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAAC,UAAU,CAAC;IAmCpF;;;;OAIG;IACG,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC9F;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CA0BlG"}

package/dist/browser-files-api.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Browser implementation of IFilesApi using the File System Access API.
+ *
+ * Provides a filesystem-like interface over browser's FileSystemDirectoryHandle.
+ * Works with directories obtained via showDirectoryPicker() or OPFS.
+ */
+import type { CopyOptions, FileHandle, FileInfo, FileRef, IFilesApi, ListOptions } from "@statewalker/webrun-files";
+export interface BrowserFilesApiOptions {
+    /**
+     * Root FileSystemDirectoryHandle to use as the filesystem root.
+     * Can be obtained via showDirectoryPicker(), navigator.storage.getDirectory(), etc.
+     */
+    rootHandle: FileSystemDirectoryHandle;
+}
+export declare class BrowserFilesApi implements IFilesApi {
+    private rootHandle;
+    constructor(options: BrowserFilesApiOptions);
+    /**
+     * Navigates to a directory handle from a path.
+     * Returns null if the directory doesn't exist and create is false.
+     */
+    private getDirectoryHandle;
+    /**
+     * Gets a file handle from a path.
+     * Returns null if the file doesn't exist and create is false.
+     */
+    private getFileHandle;
+    /**
+     * Lists entries in a directory.
+     */
+    list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo>;
+    /**
+     * Gets file or directory stats.
+     */
+    stats(file: FileRef): Promise<FileInfo | undefined>;
+    /**
+     * Removes a file or directory.
+     */
+    remove(file: FileRef): Promise<boolean>;
+    /**
+     * Opens a file for reading and writing.
+     * Creates the file and parent directories if they don't exist.
+     */
+    open(file: FileRef): Promise<FileHandle>;
+    /**
+     * Creates a directory (and parent directories if needed).
+     */
+    mkdir(file: FileRef): Promise<void>;
+    /**
+     * Moves a file or directory using copy + delete.
+     * The File System Access API doesn't have a native move operation.
+     */
+    move(source: FileRef, target: FileRef): Promise<boolean>;
+    /**
+     * Copies a file or directory.
+     */
+    copy(source: FileRef, target: FileRef, options?: CopyOptions): Promise<boolean>;
+}
+/**
+ * Opens a browser directory picker and returns a BrowserFilesApi instance.
+ * Only works in secure contexts (HTTPS) and requires user gesture.
+ */
+export declare function openBrowserFilesApi(): Promise<BrowserFilesApi>;
+/**
+ * Gets a BrowserFilesApi instance backed by the Origin Private File System (OPFS).
+ * OPFS provides a sandboxed filesystem that persists between sessions.
+ */
+export declare function getOPFSFilesApi(): Promise<BrowserFilesApi>;
+//# sourceMappingURL=browser-files-api.d.ts.map

package/dist/browser-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-files-api.d.ts","sourceRoot":"","sources":["../src/browser-files-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAED,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,UAAU,CAA4B;gBAElC,OAAO,EAAE,sBAAsB;IAI3C;;;OAGG;YACW,kBAAkB;IAkBhC;;;OAGG;YACW,aAAa;IAkB3B;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAsC/E;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA8CzD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB7C;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB9C;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzC;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAM9D;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAiF1F;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAIpE;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,CAGhE"}

package/dist/cjs/index.cjs

@@ -0,0 +1,335 @@
+let __statewalker_webrun_files = require("@statewalker/webrun-files");
+
+//#region src/browser-file-handle.ts
+var BrowserFileHandle = class {
+	fileHandle;
+	file;
+	_size;
+	closed = false;
+	constructor(options) {
+		this.fileHandle = options.fileHandle;
+		this.file = options.initialFile;
+		this._size = options.initialFile.size;
+	}
+	get size() {
+		return this._size;
+	}
+	async close() {
+		this.closed = true;
+		this.file = null;
+	}
+	/**
+	* Appends data to the end of the file.
+	*/
+	async appendFile(data, options = {}) {
+		if (this.closed) throw new Error("FileHandle is closed");
+		const { signal } = options;
+		const writable = await this.fileHandle.createWritable({ keepExistingData: true });
+		let bytesWritten = 0;
+		try {
+			await writable.seek(this._size);
+			for await (const chunk of (0, __statewalker_webrun_files.toBinaryAsyncIterable)(data)) {
+				if (signal?.aborted) throw new Error("Operation aborted");
+				await writable.write(chunk);
+				bytesWritten += chunk.length;
+			}
+		} finally {
+			await writable.close();
+		}
+		this.file = await this.fileHandle.getFile();
+		this._size = this.file.size;
+		return bytesWritten;
+	}
+	/**
+	* Creates a read stream for the file.
+	* Uses File.slice() for efficient partial reads.
+	*/
+	async *createReadStream(options = {}) {
+		if (this.closed) throw new Error("FileHandle is closed");
+		if (!this.file) {
+			this.file = await this.fileHandle.getFile();
+			this._size = this.file.size;
+		}
+		const { start = 0, end = Infinity, signal } = options;
+		const bufferSize = 8192;
+		const actualEnd = Math.min(end, this._size);
+		if (start >= actualEnd || this._size === 0) return;
+		let position = start;
+		while (position < actualEnd) {
+			if (signal?.aborted) throw new Error("Operation aborted");
+			const remaining = actualEnd - position;
+			const toRead = Math.min(bufferSize, remaining);
+			const buffer = await this.file.slice(position, position + toRead).arrayBuffer();
+			yield new Uint8Array(buffer);
+			position += buffer.byteLength;
+		}
+	}
+	/**
+	* Writes data to the file starting at the specified position.
+	* If start > 0, preserves content before start position.
+	* Truncates file at start position before writing.
+	*/
+	async createWriteStream(data, options = {}) {
+		if (this.closed) throw new Error("FileHandle is closed");
+		const { start = 0, signal } = options;
+		const writable = await this.fileHandle.createWritable({ keepExistingData: start > 0 });
+		let bytesWritten = 0;
+		try {
+			if (start > 0) {
+				await writable.seek(start);
+				await writable.truncate(start);
+			}
+			for await (const chunk of (0, __statewalker_webrun_files.toBinaryAsyncIterable)(data)) {
+				if (signal?.aborted) throw new Error("Operation aborted");
+				await writable.write(chunk);
+				bytesWritten += chunk.length;
+			}
+		} finally {
+			await writable.close();
+		}
+		this.file = await this.fileHandle.getFile();
+		this._size = this.file.size;
+		return bytesWritten;
+	}
+	/**
+	* Random access read from file at a specific position.
+	* Uses File.slice() for efficient partial reads.
+	*/
+	async read(buffer, offset, length, position) {
+		if (this.closed) throw new Error("FileHandle is closed");
+		if (!this.file) {
+			this.file = await this.fileHandle.getFile();
+			this._size = this.file.size;
+		}
+		let len = Math.min(length, buffer.length - offset);
+		len = Math.min(len, this._size - position);
+		len = Math.max(0, len);
+		if (len === 0) return 0;
+		const arrayBuffer = await this.file.slice(position, position + len).arrayBuffer();
+		const data = new Uint8Array(arrayBuffer);
+		buffer.set(data, offset);
+		return len;
+	}
+};
+
+//#endregion
+//#region src/browser-files-api.ts
+var BrowserFilesApi = class {
+	rootHandle;
+	constructor(options) {
+		this.rootHandle = options.rootHandle;
+	}
+	/**
+	* Navigates to a directory handle from a path.
+	* Returns null if the directory doesn't exist and create is false.
+	*/
+	async getDirectoryHandle(path, options = {}) {
+		const segments = path.split("/").filter((s) => s.length > 0);
+		let current = this.rootHandle;
+		for (const segment of segments) try {
+			current = await current.getDirectoryHandle(segment, options);
+		} catch {
+			return null;
+		}
+		return current;
+	}
+	/**
+	* Gets a file handle from a path.
+	* Returns null if the file doesn't exist and create is false.
+	*/
+	async getFileHandle(path, options = {}) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(path);
+		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
+		const fileName = (0, __statewalker_webrun_files.basename)(normalized);
+		const parent = await this.getDirectoryHandle(parentPath, options);
+		if (!parent) return null;
+		try {
+			return await parent.getFileHandle(fileName, options);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Lists entries in a directory.
+	*/
+	async *list(file, options = {}) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(file);
+		const dirHandle = await this.getDirectoryHandle(normalized);
+		if (!dirHandle) return;
+		const { recursive = false } = options;
+		for await (const [name, handle] of dirHandle.entries()) {
+			const entryPath = (0, __statewalker_webrun_files.joinPath)(normalized, name);
+			const isDirectory = handle.kind === "directory";
+			const info = {
+				kind: isDirectory ? "directory" : "file",
+				name,
+				path: entryPath,
+				lastModified: 0
+			};
+			if (!isDirectory) try {
+				const file$1 = await handle.getFile();
+				info.size = file$1.size;
+				info.lastModified = file$1.lastModified;
+				info.type = file$1.type;
+			} catch {}
+			yield info;
+			if (recursive && isDirectory) yield* this.list(entryPath, options);
+		}
+	}
+	/**
+	* Gets file or directory stats.
+	*/
+	async stats(file) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(file);
+		const fileName = (0, __statewalker_webrun_files.basename)(normalized);
+		if (normalized === "/") return {
+			kind: "directory",
+			name: "",
+			path: "/",
+			lastModified: 0
+		};
+		const fileHandle = await this.getFileHandle(normalized);
+		if (fileHandle) try {
+			const f = await fileHandle.getFile();
+			return {
+				kind: "file",
+				name: fileName,
+				path: normalized,
+				size: f.size,
+				lastModified: f.lastModified,
+				type: f.type
+			};
+		} catch {
+			return;
+		}
+		if (await this.getDirectoryHandle(normalized)) return {
+			kind: "directory",
+			name: fileName,
+			path: normalized,
+			lastModified: 0
+		};
+	}
+	/**
+	* Removes a file or directory.
+	*/
+	async remove(file) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(file);
+		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
+		const name = (0, __statewalker_webrun_files.basename)(normalized);
+		const parent = await this.getDirectoryHandle(parentPath);
+		if (!parent) return false;
+		try {
+			await parent.removeEntry(name, { recursive: true });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Opens a file for reading and writing.
+	* Creates the file and parent directories if they don't exist.
+	*/
+	async open(file) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(file);
+		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
+		const fileName = (0, __statewalker_webrun_files.basename)(normalized);
+		const parent = await this.getDirectoryHandle(parentPath, { create: true });
+		if (!parent) throw new Error(`Cannot create directory: ${parentPath}`);
+		const fileHandle = await parent.getFileHandle(fileName, { create: true });
+		return new BrowserFileHandle({
+			fileHandle,
+			initialFile: await fileHandle.getFile()
+		});
+	}
+	/**
+	* Creates a directory (and parent directories if needed).
+	*/
+	async mkdir(file) {
+		const normalized = (0, __statewalker_webrun_files.resolveFileRef)(file);
+		await this.getDirectoryHandle(normalized, { create: true });
+	}
+	/**
+	* Moves a file or directory using copy + delete.
+	* The File System Access API doesn't have a native move operation.
+	*/
+	async move(source, target) {
+		if (!await this.copy(source, target)) return false;
+		return this.remove(source);
+	}
+	/**
+	* Copies a file or directory.
+	*/
+	async copy(source, target, options = {}) {
+		const sourcePath = (0, __statewalker_webrun_files.resolveFileRef)(source);
+		const targetPath = (0, __statewalker_webrun_files.resolveFileRef)(target);
+		const { recursive = true } = options;
+		const sourceInfo = await this.stats(source);
+		if (!sourceInfo) return false;
+		if (sourceInfo.kind === "file") {
+			const sourceHandle = await this.getFileHandle(sourcePath);
+			if (!sourceHandle) return false;
+			const sourceFile = await sourceHandle.getFile();
+			const targetParentPath = (0, __statewalker_webrun_files.dirname)(targetPath);
+			const targetFileName = (0, __statewalker_webrun_files.basename)(targetPath);
+			const targetParent = await this.getDirectoryHandle(targetParentPath, { create: true });
+			if (!targetParent) return false;
+			const writable = await (await targetParent.getFileHandle(targetFileName, { create: true })).createWritable();
+			try {
+				const reader = sourceFile.stream().getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					await writable.write(value);
+				}
+			} finally {
+				await writable.close();
+			}
+			return true;
+		}
+		if (!recursive) return false;
+		await this.getDirectoryHandle(targetPath, { create: true });
+		for await (const entry of this.list(source, { recursive: true })) {
+			if (entry.kind === "directory") continue;
+			const newTargetPath = targetPath + entry.path.substring(sourcePath.length);
+			const entryHandle = await this.getFileHandle(entry.path);
+			if (!entryHandle) continue;
+			const entryFile = await entryHandle.getFile();
+			const newTargetParentPath = (0, __statewalker_webrun_files.dirname)(newTargetPath);
+			const newTargetFileName = (0, __statewalker_webrun_files.basename)(newTargetPath);
+			const newTargetParent = await this.getDirectoryHandle(newTargetParentPath, { create: true });
+			if (!newTargetParent) continue;
+			const writable = await (await newTargetParent.getFileHandle(newTargetFileName, { create: true })).createWritable();
+			try {
+				const reader = entryFile.stream().getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					await writable.write(value);
+				}
+			} finally {
+				await writable.close();
+			}
+		}
+		return true;
+	}
+};
+/**
+* Opens a browser directory picker and returns a BrowserFilesApi instance.
+* Only works in secure contexts (HTTPS) and requires user gesture.
+*/
+async function openBrowserFilesApi() {
+	return new BrowserFilesApi({ rootHandle: await globalThis.showDirectoryPicker() });
+}
+/**
+* Gets a BrowserFilesApi instance backed by the Origin Private File System (OPFS).
+* OPFS provides a sandboxed filesystem that persists between sessions.
+*/
+async function getOPFSFilesApi() {
+	return new BrowserFilesApi({ rootHandle: await navigator.storage.getDirectory() });
+}
+
+//#endregion
+exports.BrowserFileHandle = BrowserFileHandle;
+exports.BrowserFilesApi = BrowserFilesApi;
+exports.getOPFSFilesApi = getOPFSFilesApi;
+exports.openBrowserFilesApi = openBrowserFilesApi;