/**
 * @packageDocumentation Read/write IOStream backed by the browser File System Access API's
 * `FileSystemSyncAccessHandle` (available in dedicated web workers).
 *
 * In read-only mode the stream falls back to slice-based reads from the
 * underlying `File` blob — identical in spirit to {@link BlobStream}.
 */
import { ByteVector } from "../byteVector.js";
import { type offset_t, Position } from "./types.js";
import { IOStream } from "./ioStream.js";
/**
 * A read/write {@link IOStream} backed by a `FileSystemFileHandle` from the
 * browser's File System Access API.
 *
 * **Read-write mode** (default): opens a `FileSystemSyncAccessHandle` and uses
 * its `read`/`write` methods with explicit byte offsets (`at` option) so that
 * the internal cursor stays in sync without extra round-trips.
 *
 * **Read-only mode**: retrieves the underlying `File` blob from the handle and
 * performs lazy slice-based reads — identical to {@link BlobStream} but named
 * after the originating `FileSystemFileHandle`.
 *
 * The constructor is private; always use the async factory:
 * ```ts
 * const stream = await FileSystemFileHandleStream.open(fileHandle);
 * ```
 *
 * @example
 * // In a dedicated web worker:
 * const [fileHandle] = await window.showOpenFilePicker();
 * const stream = await FileSystemFileHandleStream.open(fileHandle);
 * const tag = await FileRef.open(stream);
 */
export declare class FileSystemFileHandleStream extends IOStream {
    private readonly _name;
    private readonly _readOnly;
    /** Sync access handle (read-write mode only). */
    private readonly _handle;
    /** Blob used for read-only slice reads. */
    private readonly _blob;
    /** `false` once `close()` has been called. */
    private _open;
    /** Current logical byte position. */
    private _position;
    private constructor();
    /**
     * Opens a `FileSystemFileHandle` and wraps it in a stream.
     *
     * @param fileHandle - The handle to open. Must be obtained via the File
     *   System Access API (e.g. `window.showOpenFilePicker()`).
     * @param readOnly   - When `true`, the stream opens the handle's `File` blob
     *   for read-only slice-based access instead of creating a sync handle.
     *   Defaults to `false`.
     * @returns A fully initialised `FileSystemFileHandleStream`.
     */
    static open(fileHandle: FileSystemFileHandle, readOnly?: boolean): Promise<FileSystemFileHandleStream>;
    /** Returns the name of the underlying file. */
    name(): string;
    /** Returns `true` if this stream was opened in read-only mode. */
    readOnly(): boolean;
    /** Returns `true` if the stream has not yet been closed. */
    isOpen(): boolean;
    /**
     * Reads up to `length` bytes from the current position and advances the
     * position by the number of bytes actually read.
     *
     * @param length - Maximum number of bytes to read.
     * @returns Resolves with a {@link ByteVector} containing the bytes read.
     */
    readBlock(length: number): Promise<ByteVector>;
    /**
     * Writes `data` at the current position, extending the file if necessary,
     * and advances the position by `data.length`.
     *
     * @param data - The bytes to write.
     * @throws {Error} If the stream is read-only.
     */
    writeBlock(data: ByteVector): Promise<void>;
    /**
     * Inserts `data` at byte offset `start`, optionally replacing `replace`
     * bytes of existing content.
     *
     * Because `FileSystemSyncAccessHandle` does not support in-place insertion,
     * this method reads the tail of the file, writes the new data, then writes
     * the tail back.
     *
     * @param data    - The bytes to insert.
     * @param start   - Byte offset at which to begin the insertion.
     * @param replace - Number of existing bytes to overwrite. Defaults to 0.
     * @throws {Error} If the stream is read-only.
     */
    insert(data: ByteVector, start: offset_t, replace?: number): Promise<void>;
    /**
     * Removes `length` bytes beginning at byte offset `start`, shifting all
     * subsequent bytes towards the beginning of the file.
     *
     * @param start  - Byte offset of the first byte to remove.
     * @param length - Number of bytes to remove.
     * @throws {Error} If the stream is read-only.
     */
    removeBlock(start: offset_t, length: number): Promise<void>;
    /**
     * Moves the read/write position within the stream.
     *
     * @param offset   - Number of bytes to move relative to `position`.
     * @param position - Reference point for the seek. Defaults to
     *   {@link Position.Beginning}.
     */
    seek(offset: offset_t, position?: Position): Promise<void>;
    /** Resets the stream position to the beginning. */
    clear(): Promise<void>;
    /** Returns the current read/write position in bytes. */
    tell(): Promise<offset_t>;
    /** Returns the total length of the file in bytes. */
    length(): Promise<offset_t>;
    /**
     * Truncates or zero-extends the file to exactly `length` bytes. If the
     * current position exceeds the new length, it is clamped.
     *
     * @param length - The desired file length in bytes.
     * @throws {Error} If the stream is read-only.
     */
    truncate(length: offset_t): Promise<void>;
    /**
     * Flushes pending writes and closes the underlying sync access handle.
     * This is a no-op in read-only mode (the blob requires no cleanup).
     *
     * After calling `close()`, {@link isOpen} returns `false` and further I/O
     * will produce undefined behaviour.
     */
    close(): Promise<void>;
}
//# sourceMappingURL=fileSystemFileHandleStream.d.ts.map