@bytecodealliance/preview2-shim 0.23.0 → 0.24.0

package/README.md

@@ -4,12 +4,145 @@ WASI Preview2 implementations for Node.js & browsers.
 
 Node.js support is fully tested and conformant against the Wasmtime test suite.
 
-Browser support is considered experimental, and not currently suitable for production applications.
+Browser support is available with the platform limitations documented below.
 
 The Node.js implementation owns its worker artifact. Direct package use and supported downstream
 bundlers should resolve it through the public shim imports; applications do not need to import or
 copy files from `dist/io`.
 
+## Browser support matrix
+
+Browser defaults are capability-safe: clocks and secure randomness use Web APIs, stdout and stderr
+write to the console, stdin is closed, outbound HTTP uses `fetch`, filesystem preopens must be
+configured explicitly, and raw sockets are unavailable unless an embedding supplies an adapter.
+
+| WASI area                     | Browser status                                                | Default capability                                                |
+| ----------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
+| CLI environment and arguments | Configurable per `WASIShim`; compatibility setters are global | Empty snapshots unless configured                                 |
+| CLI stdin                     | Adapter-backed                                                | Closed stream                                                     |
+| CLI stdout and stderr         | Web API                                                       | Console-backed, preserving split UTF-8 writes until flush/newline |
+| CLI terminals                 | Adapter-backed                                                | No terminal resource                                              |
+| Clocks                        | Web API                                                       | `performance.now`, `Date.now`, and timer-backed pollables         |
+| Random                        | Web API                                                       | `crypto.getRandomValues`, including requests larger than 64 KiB   |
+| I/O streams and poll          | Implemented browser resources                                 | Non-blocking streams depend on their injected handlers            |
+| Filesystem                    | Adapter-backed; opt-in in-memory compatibility implementation | No persistent storage is selected implicitly                      |
+| Outbound HTTP                 | Web API                                                       | Delegates to `fetch`                                              |
+| Incoming HTTP                 | Adapter-backed; opt-in in-memory client                       | Browsers cannot listen for arbitrary inbound HTTP                 |
+| TCP and UDP                   | Adapter-backed; opt-in in-memory implementations              | Raw sockets are not exposed by standard browsers                  |
+| DNS                           | Host adapter required                                         | DNS is not exposed independently by standard browsers             |
+| `WASIShim` instantiation      | Implemented                                                   | Interface namespaces can be overridden per instance               |
+
+An operation is not considered supported merely because its interface shape exists. Adapter-backed
+rows require the embedding application to provide that capability; unavailable operations fail with
+a WASI-domain error instead of logging or returning a placeholder resource.
+
+### Detailed browser capabilities
+
+The following table describes the built-in browser implementation. An application-provided
+namespace can replace any row through `WASIShim`.
+
+| Interface                     | Implemented                                                                                       | Host adapter required                                      | Unsupported by browser implementation          |
+| ----------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
+| `wasi:cli`                    | environment, arguments, initial cwd, exit, stream and terminal accessors                          | stdin/stdout/stderr handlers and terminal resources        | —                                              |
+| `wasi:clocks`                 | wall clock, monotonic clock, timer subscriptions                                                  | —                                                          | timezone APIs (not part of Preview 2)          |
+| `wasi:random`                 | secure and insecure bytes, insecure seed                                                          | —                                                          | —                                              |
+| `wasi:io`                     | errors, input/output streams, poll and pollables                                                  | readiness and I/O behavior for injected stream handlers    | synchronous blocking of the browser event loop |
+| `wasi:filesystem`             | descriptors, files, directories, links, metadata, streams, preopens through the ephemeral adapter | persistent storage, permissions, and external file handles | symbolic-link creation and reading             |
+| `wasi:http/outgoing-handler`  | Fetch-backed requests and buffered request bodies                                                 | Fetch implementation and network permission                | request/response trailers; streaming uploads   |
+| `wasi:http/incoming-handler`  | request/response translation, injectable handler, and in-memory client                            | HTTP server, service worker, or other request source       | direct browser listening                       |
+| `wasi:sockets/ip-name-lookup` | interface shape only                                                                              | complete interface replacement                             | built-in DNS lookup                            |
+| `wasi:sockets/tcp*`           | opt-in in-memory server/client implementation                                                     | adapter for external connectivity                          | built-in raw TCP                               |
+| `wasi:sockets/udp*`           | opt-in in-memory server/client implementation                                                     | adapter for external connectivity                          | built-in raw UDP                               |
+
+Outbound HTTP buffers a requested body until `outgoing-body.finish` before calling `fetch`.
+This preserves complete-body semantics across browsers but does not provide streaming upload or
+upload backpressure. Incoming Fetch bodies retain their asynchronous stream behavior. HTTP
+trailers are not implemented.
+
+Chromium-based browsers can opt into Fetch request streaming. This setting uses a
+`ReadableStream` request body with `duplex: "half"`; unsupported browsers reject the request, so
+applications should enable it only after applying their own browser support policy or feature
+detection:
+
+```js
+import { http } from "@bytecodealliance/preview2-shim";
+
+http._setRequestStreaming(true);
+```
+
+The setting affects subsequent requests made through the browser HTTP shim. Call
+`http._setRequestStreaming(false)` to restore portable completion buffering.
+
+Browser applications select storage explicitly. The bundled file-data adapter is ephemeral and must
+be opted into:
+
+```js
+import { filesystem } from "@bytecodealliance/preview2-shim";
+import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation";
+
+const shim = new WASIShim({
+    environment: { MODE: "browser" },
+    arguments: ["component"],
+    stdout: { write: (bytes) => terminal.write(bytes) },
+    browserFilesystem: {
+        adapter: new filesystem.InMemoryFilesystemAdapter(),
+        preopens: { "/data": { dir: {} } },
+    },
+    sandbox: { enableNetwork: false },
+});
+```
+
+The browser shim does not request File System Access permissions or choose IndexedDB/OPFS on an
+application's behalf. Applications that need another storage model implement the generated
+`wasi:filesystem/types` and `wasi:filesystem/preopens` namespaces and inject them through the
+`filesystem` option:
+
+```js
+const shim = new WASIShim({
+    filesystem: {
+        types: applicationFilesystemTypes,
+        preopens: applicationFilesystemPreopens,
+    },
+});
+```
+
+This keeps permission prompts, handle acquisition, persistence, and synchronization policy in
+application code. Raw TCP, UDP, and DNS are denied by default; outbound HTTP remains a separate
+`fetch` capability.
+
+Deterministic in-memory transports are available for components that act as servers and for tests:
+
+```js
+import { http, sockets } from "@bytecodealliance/preview2-shim";
+
+const tcpSockets = new sockets.InMemoryTcpSockets();
+const tcpClient = tcpSockets.connect(serverAddress);
+const udpSockets = new sockets.InMemoryUdpSockets();
+const udpClient = udpSockets.createClient(clientAddress);
+const httpClient = new http.InMemoryHttpClient(component.incomingHandler);
+
+const shim = new WASIShim({ tcpSockets, udpSockets });
+```
+
+These implementations route bytes only within the current JavaScript realm; they do not grant raw
+browser network access. `InMemoryHttpClient.fetch(request)` returns a standard Web `Response`.
+
+For a small application-owned implementation, see the
+[Map-backed browser filesystem test shim](./test/fixtures/filesystem-shim/in-memory-map.ts). It keeps named
+roots in an in-memory `Map`, implements `createPreopens`, and is intentionally example code rather
+than a published or supported filesystem package. The example is exercised through the reusable
+[filesystem implementation test suite](./test/filesystem-conformance.ts), which can also be pointed
+at other implementations.
+
+Browser filesystem adapters own the capabilities passed in `preopens` and the roots returned from
+`getRoot`. A root may be shared by multiple descriptors and preopen names; the adapter is therefore
+responsible for persistence and synchronization of shared mutations. Calling `dispose` on the
+namespace returned by `createFilesystem` calls the adapter's optional `dispose` method once and
+invalidates further preopen access. `WASIShim` does not currently cascade disposal, so embeddings
+using external handles must retain and dispose their application-owned filesystem namespace or
+adapter themselves. The bundled in-memory adapter keeps all state in memory and shares mutations
+for the same file-data object.
+
 # Features
 
 ## WASI Shim object for easy instantiation
@@ -57,9 +190,9 @@ const component = await instantiate(loader, new WASIShim().getImportObject());
 
 ## Sandboxing
 
-By default, the preview2-shim provides full access to the host filesystem, environment variables,
-and network - matching the default behavior of Node.js libraries. However, you can configure
-sandboxing to restrict what guests can access.
+On Node.js, the preview2-shim provides host filesystem, environment, and network access by default,
+matching the usual behavior of Node.js libraries. Browser defaults expose no filesystem preopens or
+raw sockets. Both platforms can configure which capabilities a guest receives.
 
 ### Using WASIShim for sandboxing
 
@@ -78,7 +211,7 @@ const sandboxedShim = new WASIShim({
     },
 });
 
-// Limited filesystem access - map virtual paths to host paths
+// Node.js only: map virtual paths to host paths
 const limitedShim = new WASIShim({
     sandbox: {
         preopens: {
@@ -95,13 +228,21 @@ const component = await instantiate(loader, sandboxedShim.getImportObject());
 ### Notes on sandboxing
 
 - By default (when no options are passed), the shim is providing full access to match typical
-  Node.js library behavior.
+  Node.js library behavior. In browsers, filesystem preopens remain empty until the application
+  explicitly injects filesystem namespaces or selects the ephemeral file-data adapter.
+- `sandbox.preopens` maps guest paths to Node.js host paths on Node.js. With
+  `browserFilesystem`, the same option maps guest paths to capabilities understood by its adapter
+  and overrides `browserFilesystem.preopens`. A custom `filesystem` can implement
+  `createPreopens(preopens)` to interpret the provided properties and return its own
+  `wasi:filesystem/preopens` namespace. The shim passes those properties through unchanged.
 - Each `WASIShim` instance has its own isolated preopens, environment variables, and arguments.
   Multiple instances with different configurations will not affect each other.
 - The direct preopen functions (`_setPreopens`, `_clearPreopens`, etc.) modify global state and
   affect all components not using `WASIShim` with explicit configuration. For isolation, prefer
   using `WASIShim` with the `sandbox` option containing `preopens` and `env`.
-- When `sandbox.enableNetwork: false`, all socket and HTTP operations will throw "access-denied" errors.
+- When `sandbox.enableNetwork: false`, Node.js socket operations receive an instance-local denied
+  network capability. Outbound HTTP is a separate Fetch capability; replace or omit the HTTP
+  namespace when the embedding must deny it as well.
 
 [jco]: https://www.npmjs.com/package/@bytecodealliance/jco
 

package/dist/browser/cli.d.ts

@@ -1,4 +1,4 @@
-import type { exit as ExitNamespace, stderr as StderrNamespace, stdin as StdinNamespace, stdout as StdoutNamespace, terminalInput as TerminalInputNamespace, terminalOutput as TerminalOutputNamespace, terminalStderr as TerminalStderrNamespace, terminalStdin as TerminalStdinNamespace, terminalStdout as TerminalStdoutNamespace } from "../../types/cli.js";
+import type { environment as EnvironmentNamespace, exit as ExitNamespace, stderr as StderrNamespace, stdin as StdinNamespace, stdout as StdoutNamespace, terminalInput as TerminalInputNamespace, terminalOutput as TerminalOutputNamespace, terminalStderr as TerminalStderrNamespace, terminalStdin as TerminalStdinNamespace, terminalStdout as TerminalStdoutNamespace } from "../../types/cli.js";
 import { type InputStreamHandler, type OutputStreamHandler } from "./io.js";
 export { _setEnv, _setArgs, environment } from "./environment.js";
 export { _setCwd } from "./config.js";
@@ -6,6 +6,14 @@ export declare const exit: typeof ExitNamespace;
 export declare function _setStdin(handler: InputStreamHandler): void;
 export declare function _setStderr(handler: OutputStreamHandler): void;
 export declare function _setStdout(handler: OutputStreamHandler): void;
+export interface BrowserCliConfig {
+    environment?: Record<string, string>;
+    arguments?: string[];
+    initialCwd?: string;
+    stdin?: InputStreamHandler;
+    stdout?: OutputStreamHandler;
+    stderr?: OutputStreamHandler;
+}
 export declare const stdin: typeof StdinNamespace;
 export declare const stdout: typeof StdoutNamespace;
 export declare const stderr: typeof StderrNamespace;
@@ -14,3 +22,16 @@ export declare const terminalOutput: typeof TerminalOutputNamespace;
 export declare const terminalStderr: typeof TerminalStderrNamespace;
 export declare const terminalStdin: typeof TerminalStdinNamespace;
 export declare const terminalStdout: typeof TerminalStdoutNamespace;
+/** Create isolated browser CLI interfaces without changing compatibility globals. */
+export declare function createCli(config?: BrowserCliConfig): {
+    environment: typeof EnvironmentNamespace;
+    exit: typeof ExitNamespace;
+    stdin: typeof StdinNamespace;
+    stdout: typeof StdoutNamespace;
+    stderr: typeof StderrNamespace;
+    terminalInput: typeof TerminalInputNamespace;
+    terminalOutput: typeof TerminalOutputNamespace;
+    terminalStdin: typeof TerminalStdinNamespace;
+    terminalStdout: typeof TerminalStdoutNamespace;
+    terminalStderr: typeof TerminalStderrNamespace;
+};

package/dist/browser/cli.js

@@ -29,41 +29,46 @@ export function _setStdout(handler) {
     stdoutStream.handler = handler;
 }
 const stdinStream = inputStreamCreate({
-    blockingRead(_len) {
-        // TODO
-        return new Uint8Array(0);
+    blockingRead() {
+        throw { tag: "closed" };
     },
     subscribe() {
-        // TODO
         return pollableCreate();
     },
-    [symbolDispose]() {
-        // TODO
-    },
-});
-const textDecoder = new TextDecoder();
-const stdoutStream = outputStreamCreate({
-    write(contents) {
-        if (contents.at(-1) == 10) {
-            // console.log already appends a new line
-            contents = contents.subarray(0, -1);
-        }
-        console.log(textDecoder.decode(contents));
-    },
-    blockingFlush() { },
     [symbolDispose]() { },
 });
-const stderrStream = outputStreamCreate({
-    write(contents) {
-        if (contents.at(-1) == 10) {
-            // console.error already appends a new line
-            contents = contents.subarray(0, -1);
+function consoleStream(writeLine) {
+    const decoder = new TextDecoder();
+    let pending = "";
+    const emitCompleteLines = () => {
+        const lines = pending.split("\n");
+        pending = lines.pop();
+        for (const line of lines) {
+            writeLine(line.endsWith("\r") ? line.slice(0, -1) : line);
         }
-        console.error(textDecoder.decode(contents));
-    },
-    blockingFlush() { },
-    [symbolDispose]() { },
-});
+    };
+    return {
+        write(contents) {
+            pending += decoder.decode(contents, { stream: true });
+            emitCompleteLines();
+        },
+        flush() {
+            pending += decoder.decode();
+            if (pending) {
+                writeLine(pending);
+            }
+            pending = "";
+        },
+        blockingFlush() {
+            this.flush?.();
+        },
+        drop() {
+            this.flush?.();
+        },
+    };
+}
+const stdoutStream = outputStreamCreate(consoleStream((line) => console.log(line)));
+const stderrStream = outputStreamCreate(consoleStream((line) => console.error(line)));
 export const stdin = {
     getStdin() {
         return stdinStream;
@@ -83,9 +88,6 @@ class TerminalInput {
 }
 class TerminalOutput {
 }
-const terminalStdoutInstance = new TerminalOutput();
-const terminalStderrInstance = new TerminalOutput();
-const terminalStdinInstance = new TerminalInput();
 export const terminalInput = {
     TerminalInput,
 };
@@ -94,16 +96,46 @@ export const terminalOutput = {
 };
 export const terminalStderr = {
     getTerminalStderr() {
-        return terminalStderrInstance;
+        return undefined;
     },
 };
 export const terminalStdin = {
     getTerminalStdin() {
-        return terminalStdinInstance;
+        return undefined;
     },
 };
 export const terminalStdout = {
     getTerminalStdout() {
-        return terminalStdoutInstance;
+        return undefined;
     },
 };
+/** Create isolated browser CLI interfaces without changing compatibility globals. */
+export function createCli(config = {}) {
+    const stdinInstance = inputStreamCreate(config.stdin ?? {
+        blockingRead() {
+            throw { tag: "closed" };
+        },
+        subscribe: () => pollableCreate(),
+    });
+    const stdoutInstance = outputStreamCreate(config.stdout ?? consoleStream((line) => console.log(line)));
+    const stderrInstance = outputStreamCreate(config.stderr ?? consoleStream((line) => console.error(line)));
+    const env = Object.entries(config.environment ?? {});
+    const args = [...(config.arguments ?? [])];
+    const cwd = config.initialCwd ?? "/";
+    return {
+        environment: {
+            getEnvironment: () => env.map(([key, value]) => [key, value]),
+            getArguments: () => [...args],
+            initialCwd: () => cwd,
+        },
+        exit,
+        stdin: { getStdin: () => stdinInstance },
+        stdout: { getStdout: () => stdoutInstance },
+        stderr: { getStderr: () => stderrInstance },
+        terminalInput,
+        terminalOutput,
+        terminalStdin,
+        terminalStdout,
+        terminalStderr,
+    };
+}

package/dist/browser/clocks.js

@@ -1,4 +1,21 @@
+import { checkedU64 } from "./common.js";
 import { pollableCreate } from "./io.js";
+const MAX_TIMEOUT_MS = 0x7fffffff;
+function timeout(durationNs) {
+    let remainingMs = Number((durationNs + 999999n) / 1000000n);
+    return new Promise((resolve) => {
+        const next = () => {
+            if (remainingMs <= 0) {
+                resolve();
+                return;
+            }
+            const delay = Math.min(remainingMs, MAX_TIMEOUT_MS);
+            remainingMs -= delay;
+            setTimeout(next, delay);
+        };
+        next();
+    });
+}
 export const monotonicClock = {
     resolution() {
         // usually we dont get sub-millisecond accuracy in the browser
@@ -10,17 +27,19 @@ export const monotonicClock = {
         return BigInt(Math.floor(performance.now() * 1e6));
     },
     subscribeInstant(instant) {
-        instant = BigInt(instant);
+        instant = checkedU64(instant, "instant");
         const now = monotonicClock.now();
         if (instant <= now) {
-            return pollableCreate(new Promise((resolve) => setTimeout(resolve, 0)));
+            return pollableCreate();
         }
         return monotonicClock.subscribeDuration(instant - now);
     },
     subscribeDuration(duration) {
-        duration = BigInt(duration);
-        const ms = duration <= 0n ? 0 : Number(duration / 1000000n);
-        return pollableCreate(new Promise((resolve) => setTimeout(resolve, ms)));
+        duration = checkedU64(duration, "duration");
+        if (duration === 0n) {
+            return pollableCreate();
+        }
+        return pollableCreate(timeout(duration));
     },
 };
 export const wallClock = {

package/dist/browser/common.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_U64: bigint;
+/** Validate and return a WebAssembly u64 value. */
+export declare function checkedU64(value: bigint, name: string): bigint;
+/** Convert a WebAssembly u64 value to a lossless JavaScript number. */
+export declare function checkedU64AsNumber(value: bigint, name: string): number;

package/dist/browser/common.js

@@ -0,0 +1,16 @@
+export const MAX_U64 = (1n << 64n) - 1n;
+/** Validate and return a WebAssembly u64 value. */
+export function checkedU64(value, name) {
+    if (typeof value !== "bigint" || value < 0n || value > MAX_U64) {
+        throw new TypeError(`${name} must be a valid u64`);
+    }
+    return value;
+}
+/** Convert a WebAssembly u64 value to a lossless JavaScript number. */
+export function checkedU64AsNumber(value, name) {
+    checkedU64(value, name);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError(`${name} exceeds JavaScript's safe integer range`);
+    }
+    return Number(value);
+}

package/dist/browser/filesystem.d.ts

@@ -1,104 +1,75 @@
 import { types as TypesNamespace, preopens as PreopensNamespace } from "../../types/filesystem.js";
-import { InputStream as IInputStream, OutputStream as IOutputStream } from "../../types/interfaces/wasi-io-streams.js";
+import type { FileData } from "./in-memory-filesystem.js";
 export { _setCwd } from "./config.js";
+export { InMemoryFilesystemAdapter } from "./in-memory-filesystem.js";
+export type { FileData, FileDataEntry } from "./in-memory-filesystem.js";
 type Filesize = TypesNamespace.Filesize;
 type OpenFlags = TypesNamespace.OpenFlags;
 type PathFlags = TypesNamespace.PathFlags;
-export interface FileDataEntry {
-    dir?: Record<string, FileDataEntry>;
-    source?: Uint8Array | string;
+export interface BrowserDirectoryEntryStream {
+    readDirectoryEntry(): TypesNamespace.DirectoryEntry | undefined;
+}
+export interface BrowserFilesystemDescriptor extends Omit<TypesNamespace.Descriptor, "isSameObject" | "linkAt" | "openAt" | "readDirectory" | "renameAt"> {
+    readDirectory(): BrowserDirectoryEntryStream;
+    linkAt(oldPathFlags: PathFlags, oldPath: string, newDescriptor: BrowserFilesystemDescriptor, newPath: string): void;
+    openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: TypesNamespace.DescriptorFlags): BrowserFilesystemDescriptor;
+    renameAt(oldPath: string, newDescriptor: BrowserFilesystemDescriptor, newPath: string): void;
+    isSameObject(other: BrowserFilesystemDescriptor): boolean;
+}
+export interface BrowserFilesystemAdapter<Capability = unknown> {
+    getRoot(capability: Capability): BrowserFilesystemDescriptor;
+    dispose?(): void;
+}
+export interface BrowserFilesystemConfig<Capability> {
+    adapter: BrowserFilesystemAdapter<Capability>;
+    preopens: Record<string, Capability>;
 }
-/**
- * Root file data structure representing a filesystem tree.
- * Each entry is either a directory (has `dir` property) or a file (has `source` property).
- * @example
- * // A simple filesystem with one directory containing one file:
- * const fileData = {
- *   dir: {
- *     'myfile.txt': { source: new Uint8Array([72, 101, 108, 108, 111]) }
- *   }
- * };
- */
-export type FileData = FileDataEntry;
-export declare function _setFileData(fileData: FileData): void;
-export declare function _getFileData(): string;
 declare class DirectoryEntryStream implements TypesNamespace.DirectoryEntryStream {
-    idx: number;
-    entries: [string, FileDataEntry][];
-    static _create(entries: [string, FileDataEntry][]): DirectoryEntryStream;
+    #private;
+    static _create(implementation: BrowserDirectoryEntryStream): DirectoryEntryStream;
     readDirectoryEntry(): TypesNamespace.DirectoryEntry | undefined;
 }
 declare class Descriptor implements TypesNamespace.Descriptor {
     #private;
-    _getEntry(descriptor: Descriptor): FileDataEntry;
-    static _create(entry: FileDataEntry | any, isStream?: boolean): Descriptor;
-    readViaStream(_offset: bigint): IInputStream;
-    writeViaStream(_offset: bigint): IOutputStream;
-    appendViaStream(): IOutputStream;
+    _getImplementation(descriptor: Descriptor): BrowserFilesystemDescriptor;
+    static _create(implementation: BrowserFilesystemDescriptor): Descriptor;
+    readViaStream(offset: Filesize): import("../../types/interfaces/wasi-io-streams.js").InputStream;
+    writeViaStream(offset: Filesize): import("../../types/interfaces/wasi-io-streams.js").OutputStream;
+    appendViaStream(): import("../../types/interfaces/wasi-io-streams.js").OutputStream;
     advise(offset: Filesize, length: Filesize, advice: TypesNamespace.Advice): void;
     syncData(): void;
     getFlags(): TypesNamespace.DescriptorFlags;
-    getType(): "directory" | "fifo" | "regular-file" | "unknown";
-    setSize(size: bigint): void;
-    setTimes(dataAccessTimestamp: any, dataModificationTimestamp: any): void;
-    read(length: bigint, offset: bigint): [Uint8Array<ArrayBufferLike>, boolean];
+    getType(): TypesNamespace.DescriptorType;
+    setSize(size: Filesize): void;
+    setTimes(dataAccessTimestamp: TypesNamespace.NewTimestamp, dataModificationTimestamp: TypesNamespace.NewTimestamp): void;
+    read(length: Filesize, offset: Filesize): [Uint8Array<ArrayBufferLike>, boolean];
     write(buffer: Uint8Array, offset: Filesize): bigint;
     readDirectory(): DirectoryEntryStream;
     sync(): void;
     createDirectoryAt(path: string): void;
-    stat(): {
-        type: "directory" | "regular-file" | "unknown";
-        linkCount: bigint;
-        size: bigint;
-        dataAccessTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-        dataModificationTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-        statusChangeTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-    };
-    statAt(_pathFlags: PathFlags, path: string): {
-        type: "directory" | "regular-file" | "unknown";
-        linkCount: bigint;
-        size: bigint;
-        dataAccessTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-        dataModificationTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-        statusChangeTimestamp: {
-            seconds: bigint;
-            nanoseconds: number;
-        };
-    };
-    setTimesAt(): void;
-    linkAt(): void;
-    openAt(_pathFlags: PathFlags, path: string, openFlags: OpenFlags, _flags: TypesNamespace.DescriptorFlags): Descriptor;
-    readlinkAt(_path: string): string;
-    removeDirectoryAt(): void;
-    renameAt(): void;
-    symlinkAt(): void;
-    unlinkFileAt(): void;
+    stat(): TypesNamespace.DescriptorStat;
+    statAt(pathFlags: PathFlags, path: string): TypesNamespace.DescriptorStat;
+    setTimesAt(pathFlags: PathFlags, path: string, dataAccessTimestamp: TypesNamespace.NewTimestamp, dataModificationTimestamp: TypesNamespace.NewTimestamp): void;
+    linkAt(oldPathFlags: PathFlags, oldPath: string, newDescriptor: TypesNamespace.Descriptor, newPath: string): void;
+    openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: TypesNamespace.DescriptorFlags): Descriptor;
+    readlinkAt(path: string): string;
+    removeDirectoryAt(path: string): void;
+    renameAt(oldPath: string, newDescriptor: TypesNamespace.Descriptor, newPath: string): void;
+    symlinkAt(oldPath: string, newPath: string): void;
+    unlinkFileAt(path: string): void;
     isSameObject(other: TypesNamespace.Descriptor): boolean;
-    metadataHash(): {
-        upper: bigint;
-        lower: bigint;
-    };
-    metadataHashAt(_pathFlags: any, _path: string): {
-        upper: bigint;
-        lower: bigint;
-    };
+    metadataHash(): TypesNamespace.MetadataHashValue;
+    metadataHashAt(pathFlags: PathFlags, path: string): TypesNamespace.MetadataHashValue;
 }
 export declare const preopens: typeof PreopensNamespace;
+/** Create isolated filesystem namespaces backed by an application-selected adapter. */
+export declare function createFilesystem<Capability>({ adapter, preopens: configuredPreopens, }: BrowserFilesystemConfig<Capability>): {
+    types: typeof TypesNamespace;
+    preopens: typeof PreopensNamespace;
+    dispose(): void;
+};
+export declare function _setFileData(fileData: FileData): void;
+export declare function _getFileData(): string;
 /**
  * Replace all preopens with the given set.
  * @param preopensConfig - Map of virtual paths to file data entries
@@ -110,23 +81,10 @@ export declare function _setPreopens(preopensConfig: Record<string, FileData>):
  * @param fileData - The file data object representing the directory
  */
 export declare function _addPreopen(virtualPath: string, fileData: FileData): void;
-/**
- * Clear all preopens, giving the guest no filesystem access.
- *
- * This functionality exists mostly to maintain backwards compatibility. Prefer setting preopens
- * via `WASIShim` rather than making top level changes to preopens using these functions.
- */
+/** Clear all preopens, giving the guest no filesystem access. */
 export declare function _clearPreopens(): void;
-/**
- * Get current preopens configuration.
- * @returns Array of [descriptor, virtualPath] pairs
- */
+/** Get current preopens configuration. */
 export declare function _getPreopens(): [Descriptor, string][];
-/**
- * Create a preopen descriptor for a host path.
- * This is used internally to create isolated preopen instances.
- * @param  hostPreopen - The host filesystem path
- * @returns A preopen descriptor
- */
-export declare function _createPreopenDescriptor(hostPreopen: string): Descriptor;
+/** Reject host paths because browser filesystems require explicit capabilities. */
+export declare function _createPreopenDescriptor(hostPreopen: string): void;
 export declare const types: typeof TypesNamespace;