@bendyline/docblocks 2.0.0 → 2.1.1

package/dist/filesystem/indexeddb.d.ts

@@ -1,5 +1,284 @@
-/** Browser-local persistent filesystem provider entry point. */
-export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
-export { IndexedDBFileSystemProviderV2, type IndexedDBFileSystemProviderV2Options, type IndexedDBLegacyConflictReason, type IndexedDBLegacyConflictResolution, type IndexedDBLegacyMigrationConflict, type IndexedDBLegacyRecoveryCandidate, type IndexedDBLegacyRecoveryKind, } from './indexeddb-provider-v2.js';
-export { IndexedDBContentContainer } from './indexeddb-content-container.js';
-//# sourceMappingURL=indexeddb.d.ts.map
+import { s as FileSystemProviderV2, r as FileSystemProviderCapabilities, k as FileSystemEntrySnapshot, m as FileSystemFileRead, K as FileSystemWriteOptions, n as FileSystemFileSnapshot, g as FileSystemCreateDirectoryOptions, h as FileSystemDirectorySnapshot, u as FileSystemRemoveOptions, v as FileSystemRemoveResult, o as FileSystemMoveOptions, w as FileSystemSnapshot, G as FileSystemWatchListener, H as FileSystemWatchOptions, I as FileSystemWatchSubscription, b as FileMeta, q as FileSystemProvider, F as FileCommitResult, j as FileSystemEntry } from '../types-BEg5SQ1_.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+import { ContentContainer, ContentEntry } from '@bendyline/squisq/storage';
+
+/**
+ * Minimal, error-propagating IndexedDB store used by the virtual filesystem.
+ *
+ * The previous Squisq LocalForage adapter intentionally converted failed
+ * reads/enumerations/removals into null/empty/success. Those semantics are
+ * unsuitable for filesystem mutations: an unavailable database must never be
+ * interpreted as an absent file. This layer opens the old database and object
+ * store directly so existing data can be migrated in one transaction.
+ */
+type IndexedDBFileSystemTransactionMode = 'readonly' | 'readwrite';
+/** The database holding one browser-local workspace's files. */
+declare function indexedDBWorkspaceDatabaseName(workspaceId: string): string;
+/**
+ * Delete a browser-local workspace's stored files.
+ *
+ * Removing a workspace descriptor alone leaves these bytes behind: invisible to
+ * the user, still counted against the origin's quota, and ready to reappear
+ * under any later workspace that reuses the same id.
+ */
+declare function deleteIndexedDBWorkspaceData(workspaceId: string): Promise<void>;
+interface IndexedDBFileSystemTransaction {
+    get<T>(key: string): Promise<T | null>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    /** O(log n) namespace probe in the concrete IndexedDB implementation. */
+    hasKeyWithPrefix(prefix: string): Promise<boolean>;
+}
+interface IndexedDBFileSystemStore {
+    transaction<T>(mode: IndexedDBFileSystemTransactionMode, operation: (transaction: IndexedDBFileSystemTransaction) => Promise<T>): Promise<T>;
+    close?(): void;
+}
+
+type IndexedDBLegacyConflictReason = 'dual-payload' | 'kind-collision' | 'authority-collision' | 'stale-client-write';
+type IndexedDBLegacyRecoveryKind = 'file' | 'directory';
+interface IndexedDBLegacyRecoveryCandidate {
+    readonly kind: IndexedDBLegacyRecoveryKind;
+    readonly reason: IndexedDBLegacyConflictReason;
+    readonly text: string | null;
+    readonly binary: ArrayBuffer | null;
+    readonly metadata: FileMeta | null;
+    readonly detectedAt: string;
+}
+interface IndexedDBLegacyMigrationConflict {
+    readonly path: WorkspacePath;
+    /** Backward-compatible projection of the newest quarantined candidate. */
+    readonly reason: IndexedDBLegacyConflictReason;
+    readonly kind: IndexedDBLegacyRecoveryKind;
+    readonly text: string | null;
+    readonly binary: ArrayBuffer | null;
+    readonly metadata: FileMeta | null;
+    readonly detectedAt: string;
+    readonly candidates: readonly IndexedDBLegacyRecoveryCandidate[];
+}
+type IndexedDBLegacyConflictResolution = 'v2' | 'text' | 'binary' | {
+    readonly candidate: number;
+    readonly payload: 'text' | 'binary' | 'directory';
+};
+/** One archived snapshot of an unrecognized legacy key's value. */
+interface IndexedDBLegacyOpaqueValue {
+    /**
+     * The structured-clone value exactly as the legacy key held it. DocBlocks
+     * never interpreted these bytes, so the shape is whatever the writing tool
+     * chose. Callers must treat it as untrusted and narrow it themselves.
+     */
+    readonly value: unknown;
+    /** Byte size when the value is sized (bytes or string); null otherwise. */
+    readonly byteLength: number | null;
+    /** Null for values archived before archival timestamps were recorded. */
+    readonly archivedAt: string | null;
+}
+/** What is archived under one unrecognized legacy key, without its values. */
+interface IndexedDBLegacyOpaqueRecordSummary {
+    /** The original legacy key, decoded (for example `fs:some-other-tool`). */
+    readonly key: string;
+    /** Archived snapshots of this key, oldest first. Never zero. */
+    readonly valueCount: number;
+    /** Total bytes across values; null when any value is not sized. */
+    readonly byteLength: number | null;
+    readonly firstArchivedAt: string | null;
+    readonly lastArchivedAt: string | null;
+}
+/** An archived legacy key together with every value snapshot it holds. */
+interface IndexedDBLegacyOpaqueRecord extends IndexedDBLegacyOpaqueRecordSummary {
+    /** Oldest first. Index N here matches index N of the archival order. */
+    readonly values: readonly IndexedDBLegacyOpaqueValue[];
+}
+/**
+ * One record a caller has looked at and intends to destroy.
+ *
+ * Both {@link IndexedDBLegacyOpaqueRecordSummary} and
+ * {@link IndexedDBLegacyOpaqueRecord} satisfy this shape, so the value returned
+ * by a list or read can be handed straight to the discard call.
+ */
+interface IndexedDBLegacyOpaqueDiscardTarget {
+    readonly key: string;
+    /**
+     * The number of archived values the caller saw. The discard fails if the
+     * record has since grown, so a snapshot that arrived after the caller looked
+     * is never destroyed unseen.
+     */
+    readonly valueCount: number;
+}
+interface IndexedDBFileSystemProviderV2Options {
+    /** Injectable store for fault, migration, and concurrency tests. */
+    readonly store?: IndexedDBFileSystemStore;
+    readonly now?: () => Date;
+    /** Shared-store owners can retain the connection when this facade is disposed. */
+    readonly closeStoreOnDispose?: boolean;
+}
+/**
+ * IndexedDB implementation of the correctness-first filesystem contract.
+ *
+ * Each canonical path has one authoritative structured-clone record containing
+ * its kind, owned bytes (for files), version, and metadata. Every mutation and
+ * snapshot is one IndexedDB transaction. Legacy v1 keys are imported once;
+ * ambiguous or stale branches move into durable recovery records before the
+ * legacy namespace is deleted, leaving one live authority.
+ */
+declare class IndexedDBFileSystemProviderV2 implements FileSystemProviderV2 {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: FileSystemProviderCapabilities;
+    private readonly store;
+    private readonly now;
+    private readonly closeStoreOnDispose;
+    private readonly versionPrefix;
+    private readonly subscriptions;
+    private readonly inFlight;
+    private initialization;
+    private disposePromise;
+    private storeClosed;
+    private disposed;
+    constructor(id: string, label: string, options?: IndexedDBFileSystemProviderV2Options);
+    /** Track accepted storage work so disposal can join it before closing. */
+    private runSharedTransaction;
+    stat(path: WorkspacePath): Promise<FileSystemEntrySnapshot | null>;
+    readFile(path: WorkspacePath): Promise<FileSystemFileRead | null>;
+    readDirectory(path: WorkspacePath): Promise<readonly FileSystemEntrySnapshot[]>;
+    writeFile(path: WorkspacePath, data: ArrayBuffer | Uint8Array, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    createDirectory(path: WorkspacePath, options?: FileSystemCreateDirectoryOptions): Promise<FileSystemDirectorySnapshot>;
+    remove(path: WorkspacePath, options?: FileSystemRemoveOptions): Promise<FileSystemRemoveResult>;
+    move(oldPath: WorkspacePath, newPath: WorkspacePath, options?: FileSystemMoveOptions): Promise<FileSystemEntrySnapshot>;
+    snapshot(): Promise<FileSystemSnapshot>;
+    /** IndexedDB has no reliable cross-browser external-change observer. */
+    watch(_listener: FileSystemWatchListener, options?: FileSystemWatchOptions): FileSystemWatchSubscription;
+    dispose(): Promise<void>;
+    /** List unresolved, byte-preserving conflicts found during v1 migration. */
+    listLegacyMigrationConflicts(): Promise<readonly IndexedDBLegacyMigrationConflict[]>;
+    /** Resolve quarantined legacy data by choosing v2 or one legacy byte payload. */
+    resolveLegacyMigrationConflict(path: WorkspacePath, resolution: IndexedDBLegacyConflictResolution): Promise<FileSystemEntrySnapshot>;
+    /** Explicitly discard every quarantined legacy candidate at a path. */
+    discardLegacyMigrationConflict(path: WorkspacePath): Promise<boolean>;
+    /**
+     * List the unrecognized legacy keys this workspace archived during migration.
+     *
+     * Migration deletes the legacy `fs:` namespace, but a key it cannot interpret
+     * is copied aside first rather than dropped: those bytes belong to whatever
+     * tool wrote them against this origin, and DocBlocks is not entitled to
+     * decide they are worthless. Nothing else reads that archive, so without this
+     * call the bytes are invisible and their quota is unaccountable.
+     *
+     * Values are deliberately excluded — an archive large enough to matter is an
+     * archive too large to materialize just to count it. Use
+     * {@link readLegacyOpaqueRecord} for the values themselves.
+     */
+    listLegacyOpaqueRecords(): Promise<readonly IndexedDBLegacyOpaqueRecordSummary[]>;
+    /** Retrieve every archived value for one unrecognized legacy key. */
+    readLegacyOpaqueRecord(key: string): Promise<IndexedDBLegacyOpaqueRecord | null>;
+    /**
+     * Permanently destroy archived legacy values. This is the only operation that
+     * can lose data the archive exists to protect.
+     *
+     * For every target, all of that key's archived value snapshots are erased and
+     * the quota they held is reclaimed. There is no undo, no tombstone, and no
+     * other copy: migration already deleted the original `fs:` key, so the
+     * archive is the last one. Retrieve anything worth keeping with
+     * {@link readLegacyOpaqueRecord} before calling this.
+     *
+     * Each target must carry the `valueCount` the caller actually observed, which
+     * is why a target is a value returned by {@link listLegacyOpaqueRecords} or
+     * {@link readLegacyOpaqueRecord} rather than a bare key. A stale client can
+     * append a new snapshot at any time; if any target has grown since it was
+     * observed, the whole call fails with `conflict` and destroys nothing, so
+     * re-list and look again. A key that is already absent is not an error —
+     * discarding what is gone is a no-op — but a key whose count disagrees is.
+     *
+     * @returns how many records were destroyed.
+     */
+    discardLegacyOpaqueRecords(targets: readonly IndexedDBLegacyOpaqueDiscardTarget[]): Promise<number>;
+    private ensureInitialized;
+    private migrateLegacy;
+    private quarantineExistingLegacy;
+    private transaction;
+    private withMutationLock;
+    private nextMutationVersion;
+    private advanceState;
+    private makeVersion;
+    private planParents;
+    private addDirectories;
+    private touchParents;
+    private canonicalNonRoot;
+    private assertExpectedVersion;
+    private assertOpen;
+    private error;
+}
+
+/**
+ * Legacy FileSystemProvider facade over the revisioned IndexedDB authority.
+ *
+ * The old `fs:*` namespace is migration input only. Keeping this facade as an
+ * adapter prevents current callers from recreating a second persistent source
+ * of truth while the workspace moves to FileSystemProviderV2.
+ */
+
+interface IndexedDBFileSystemProviderOptions {
+    /** Injectable transaction store for deterministic fault/concurrency tests. */
+    store?: IndexedDBFileSystemStore;
+    /** Injectable metadata clock. */
+    now?: () => Date;
+}
+declare class IndexedDBFileSystemProvider implements FileSystemProvider {
+    readonly id: string;
+    readonly label: string;
+    readonly v2: IndexedDBFileSystemProviderV2;
+    private disposed;
+    constructor(id: string, label: string, options?: IndexedDBFileSystemProviderOptions);
+    /** Release the underlying database connection after accepted work settles. */
+    dispose(): Promise<void>;
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    commitFile(path: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    delete(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    readDirectory(path: string): Promise<FileSystemEntry[]>;
+    exists(path: string): Promise<boolean>;
+    createDirectory(path: string): Promise<void>;
+    stat(path: string): Promise<FileMeta | null>;
+    readBinary(path: string): Promise<ArrayBuffer | null>;
+    writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Canonicalize only. Root policy is the v2 authority's to state: it accepts
+     * the root wherever the root is a legitimate target (`stat`, `readDirectory`,
+     * `createDirectory`) and rejects it with one consistent code and message
+     * everywhere else. Re-deriving that policy here is how this facade previously
+     * drifted from both v2 and its sibling facades.
+     */
+    private path;
+    /**
+     * Byte-authoritative entries may hold payloads that are not valid UTF-8. A
+     * lossy decode would hand the caller replacement characters that a later save
+     * writes back over the user's original bytes, so surface the fault instead.
+     */
+    private decode;
+    private assertOpen;
+}
+
+/**
+ * IndexedDBContentContainer — a ContentContainer backed by IndexedDB.
+ *
+ * Uses a dedicated IndexedDBFileSystemProvider instance (separate store)
+ * to persist media files across page refreshes.
+ */
+
+declare class IndexedDBContentContainer implements ContentContainer {
+    private readonly provider;
+    constructor(workspaceId: string);
+    readFile(path: string): Promise<ArrayBuffer | null>;
+    writeFile(path: string, data: ArrayBuffer | Uint8Array, _mimeType?: string): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    listFiles(prefix?: string): Promise<ContentEntry[]>;
+    exists(path: string): Promise<boolean>;
+    getDocumentPath(): Promise<string | null>;
+    readDocument(): Promise<string | null>;
+    writeDocument(markdown: string, filename?: string): Promise<void>;
+    /** Release the IndexedDB connection when a long-lived container is retired. */
+    dispose(): Promise<void>;
+}
+
+export { IndexedDBContentContainer, IndexedDBFileSystemProvider, IndexedDBFileSystemProviderV2, type IndexedDBFileSystemProviderV2Options, type IndexedDBLegacyConflictReason, type IndexedDBLegacyConflictResolution, type IndexedDBLegacyMigrationConflict, type IndexedDBLegacyOpaqueDiscardTarget, type IndexedDBLegacyOpaqueRecord, type IndexedDBLegacyOpaqueRecordSummary, type IndexedDBLegacyOpaqueValue, type IndexedDBLegacyRecoveryCandidate, type IndexedDBLegacyRecoveryKind, deleteIndexedDBWorkspaceData, indexedDBWorkspaceDatabaseName };

package/dist/filesystem/indexeddb.js

@@ -1,5 +1,22 @@
-/** Browser-local persistent filesystem provider entry point. */
-export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
-export { IndexedDBFileSystemProviderV2, } from './indexeddb-provider-v2.js';
-export { IndexedDBContentContainer } from './indexeddb-content-container.js';
-//# sourceMappingURL=indexeddb.js.map
+import {
+  IndexedDBContentContainer,
+  IndexedDBFileSystemProvider,
+  IndexedDBFileSystemProviderV2
+} from "../chunk-YM7O3PWO.js";
+import "../chunk-DZB666V7.js";
+import "../chunk-KQ6756AJ.js";
+import "../chunk-73OOROXH.js";
+import "../chunk-M62ZGJ5I.js";
+import "../chunk-M5ZNQGR5.js";
+import "../chunk-AYWKIZLD.js";
+import {
+  deleteIndexedDBWorkspaceData,
+  indexedDBWorkspaceDatabaseName
+} from "../chunk-OQCPBOQA.js";
+export {
+  IndexedDBContentContainer,
+  IndexedDBFileSystemProvider,
+  IndexedDBFileSystemProviderV2,
+  deleteIndexedDBWorkspaceData,
+  indexedDBWorkspaceDatabaseName
+};

package/dist/filesystem/memory.d.ts

@@ -1,4 +1,152 @@
-/** Transient in-memory filesystem provider entry point. */
-export { MemoryFileSystemProvider, type MemoryFileSystemSnapshot, type MemoryFileSystemSnapshotFile, } from './memory-provider.js';
-export { MemoryFileSystemProviderV2, type MemoryFilePayloadKind, type MemoryFileSystemV2CompatibilityFile, type MemoryFileSystemV2Replacement, type MemoryFileSystemV2ReplacementFile, type MemoryFileSystemV2State, type MemoryFileSystemV2StateFile, } from './memory-provider-v2.js';
-//# sourceMappingURL=memory.d.ts.map
+import { s as FileSystemProviderV2, r as FileSystemProviderCapabilities, K as FileSystemWriteOptions, n as FileSystemFileSnapshot, F as FileCommitResult, k as FileSystemEntrySnapshot, m as FileSystemFileRead, g as FileSystemCreateDirectoryOptions, h as FileSystemDirectorySnapshot, u as FileSystemRemoveOptions, v as FileSystemRemoveResult, o as FileSystemMoveOptions, w as FileSystemSnapshot, G as FileSystemWatchListener, H as FileSystemWatchOptions, I as FileSystemWatchSubscription, q as FileSystemProvider, j as FileSystemEntry, b as FileMeta } from '../types-BEg5SQ1_.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+
+type MemoryFilePayloadKind = 'text' | 'binary';
+interface MemoryFileSystemV2StateFile {
+    readonly path: WorkspacePath;
+    readonly data: ArrayBuffer;
+    readonly payloadKind: MemoryFilePayloadKind;
+}
+interface MemoryFileSystemV2CompatibilityFile {
+    readonly data: ArrayBuffer;
+    readonly payloadKind: MemoryFilePayloadKind;
+}
+interface MemoryFileSystemV2State {
+    readonly revision: number;
+    readonly files: readonly MemoryFileSystemV2StateFile[];
+    readonly directories: readonly WorkspacePath[];
+}
+interface MemoryFileSystemV2ReplacementFile {
+    readonly path: WorkspacePath;
+    readonly data: ArrayBuffer | Uint8Array;
+    readonly payloadKind: MemoryFilePayloadKind;
+}
+interface MemoryFileSystemV2Replacement {
+    readonly files: readonly MemoryFileSystemV2ReplacementFile[];
+    readonly directories?: readonly WorkspacePath[];
+}
+/**
+ * Correctness reference for FileSystemProviderV2.
+ *
+ * Every mutation validates first, stages a fresh map, swaps it once, and only
+ * then emits notifications. File buffers are owned by the provider and every
+ * read/snapshot returns a defensive copy.
+ */
+declare class MemoryFileSystemProviderV2 implements FileSystemProviderV2 {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: FileSystemProviderCapabilities;
+    private entries;
+    private readonly watchers;
+    private readonly subscriptions;
+    private readonly pendingEvents;
+    private emittingEvents;
+    private mutationCounter;
+    private eventSequence;
+    private treeVersion;
+    private disposed;
+    private disposePromise;
+    constructor(id: string, label: string);
+    /** Monotonic in-process revision used by synchronous transient-workspace staging. */
+    get mutationRevision(): number;
+    /** @internal Atomically couple owned bytes to their v1 compatibility kind. */
+    readCompatibilityFile(path: WorkspacePath): MemoryFileSystemV2CompatibilityFile | null;
+    /** @internal Capture an owned synchronous copy for DBK whole-tree staging. */
+    captureState(): MemoryFileSystemV2State;
+    /** @internal Atomically replace a transient workspace after complete validation. */
+    replaceState(replacement: MemoryFileSystemV2Replacement, expectedRevision?: number): void;
+    /** @internal Synchronous setup hook used before a transient provider is published. */
+    seedText(path: WorkspacePath, content: string): void;
+    /** @internal Legacy text write that preserves text/binary compatibility metadata. */
+    writeText(path: WorkspacePath, content: string, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    /** @internal Legacy binary write that explicitly changes compatibility payload kind. */
+    writeBinary(path: WorkspacePath, data: ArrayBuffer | Uint8Array, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    /** @internal Atomic legacy compare-and-write over the authoritative v2 entry. */
+    commitText(path: WorkspacePath, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    stat(path: WorkspacePath): Promise<FileSystemEntrySnapshot | null>;
+    readFile(path: WorkspacePath): Promise<FileSystemFileRead | null>;
+    readDirectory(path: WorkspacePath): Promise<readonly FileSystemEntrySnapshot[]>;
+    writeFile(path: WorkspacePath, data: ArrayBuffer | Uint8Array, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    private writeFileNow;
+    createDirectory(path: WorkspacePath, options?: FileSystemCreateDirectoryOptions): Promise<FileSystemDirectorySnapshot>;
+    remove(path: WorkspacePath, options?: FileSystemRemoveOptions): Promise<FileSystemRemoveResult>;
+    move(oldPath: WorkspacePath, newPath: WorkspacePath, options?: FileSystemMoveOptions): Promise<FileSystemEntrySnapshot>;
+    snapshot(): Promise<FileSystemSnapshot>;
+    watch(listener: FileSystemWatchListener, options?: FileSystemWatchOptions): FileSystemWatchSubscription;
+    dispose(): Promise<void>;
+    private canonical;
+    private canonicalNonRoot;
+    private assertOpen;
+    private assertExpectedVersion;
+    private planParents;
+    private addDirectories;
+    private touchParents;
+    private withVersion;
+    private nextVersion;
+    private toEntrySnapshot;
+    private toFileSnapshot;
+    private toDirectorySnapshot;
+    private emit;
+    private error;
+}
+
+/**
+ * In-memory filesystem used by transient loose-file and DBK workspaces.
+ *
+ * MemoryFileSystemProviderV2 is authoritative. This class is the temporary
+ * text-oriented v1 facade retained while callers migrate to the byte contract.
+ */
+
+type MemoryFileSystemSnapshotFile = {
+    readonly kind: 'text';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly kind: 'binary';
+    readonly path: string;
+    readonly data: ArrayBuffer | Uint8Array;
+};
+/** Complete provider-relative state for a transient memory workspace. */
+interface MemoryFileSystemSnapshot {
+    readonly files: readonly MemoryFileSystemSnapshotFile[];
+    readonly directories?: readonly string[];
+}
+/**
+ * Legacy facade over the correctness-first memory provider.
+ *
+ * Synchronous seed/snapshot replacement methods remain because DBK import
+ * fully stages external bytes before publishing one atomic in-memory swap.
+ */
+declare class MemoryFileSystemProvider implements FileSystemProvider {
+    readonly id: string;
+    readonly label: string;
+    readonly v2: MemoryFileSystemProviderV2;
+    constructor(id: string, label: string);
+    /** Monotonic version of the complete in-memory tree. */
+    get treeVersion(): number;
+    /** Capture an owned deterministic copy of the complete transient tree. */
+    captureContents(): MemoryFileSystemSnapshot;
+    /** Atomically replace the complete tree after validating and owning all input. */
+    replaceContents(snapshot: MemoryFileSystemSnapshot, expectedTreeVersion?: number): void;
+    /** Seed synchronously before publishing a transient provider to consumers. */
+    seedText(path: string, content: string): void;
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    commitFile(path: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    delete(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    readDirectory(path: string): Promise<FileSystemEntry[]>;
+    exists(path: string): Promise<boolean>;
+    createDirectory(path: string): Promise<void>;
+    stat(path: string): Promise<FileMeta | null>;
+    /**
+     * Every stored file is bytes, so every stored file is readable as binary.
+     * `payloadKind` records how a file was written for DBK export fidelity; it is
+     * not a filter. Gating on it made `readBinary` report an existing text file as
+     * missing, which no other provider does and which callers read as "no file".
+     */
+    readBinary(path: string): Promise<ArrayBuffer | null>;
+    writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+}
+
+export { type MemoryFilePayloadKind, MemoryFileSystemProvider, MemoryFileSystemProviderV2, type MemoryFileSystemSnapshot, type MemoryFileSystemSnapshotFile, type MemoryFileSystemV2CompatibilityFile, type MemoryFileSystemV2Replacement, type MemoryFileSystemV2ReplacementFile, type MemoryFileSystemV2State, type MemoryFileSystemV2StateFile };

package/dist/filesystem/memory.js

@@ -1,4 +1,12 @@
-/** Transient in-memory filesystem provider entry point. */
-export { MemoryFileSystemProvider, } from './memory-provider.js';
-export { MemoryFileSystemProviderV2, } from './memory-provider-v2.js';
-//# sourceMappingURL=memory.js.map
+import {
+  MemoryFileSystemProvider,
+  MemoryFileSystemProviderV2
+} from "../chunk-ZO7G53QP.js";
+import "../chunk-KQ6756AJ.js";
+import "../chunk-M62ZGJ5I.js";
+import "../chunk-M5ZNQGR5.js";
+import "../chunk-AYWKIZLD.js";
+export {
+  MemoryFileSystemProvider,
+  MemoryFileSystemProviderV2
+};

package/dist/filesystem/native.d.ts

@@ -1,4 +1,136 @@
-/** Browser File System Access API provider entry point. */
-export { NativeFileSystemProvider, isNativeFileSystemSupported, openNativeFolder, restoreNativeFolder, storeDirectoryHandle, loadDirectoryHandle, removeDirectoryHandle, } from './native-provider.js';
-export { NativeFileSystemProviderV2, NativeFileSystemMoveRecoveryError, type NativeFileSystemMovePathState, type NativeFileSystemMoveRecoveryState, } from './native-provider-v2.js';
-//# sourceMappingURL=native.d.ts.map
+import { M as FsError, s as FileSystemProviderV2, r as FileSystemProviderCapabilities, k as FileSystemEntrySnapshot, m as FileSystemFileRead, K as FileSystemWriteOptions, n as FileSystemFileSnapshot, g as FileSystemCreateDirectoryOptions, h as FileSystemDirectorySnapshot, u as FileSystemRemoveOptions, v as FileSystemRemoveResult, o as FileSystemMoveOptions, w as FileSystemSnapshot, G as FileSystemWatchListener, H as FileSystemWatchOptions, I as FileSystemWatchSubscription, q as FileSystemProvider, F as FileCommitResult, j as FileSystemEntry, b as FileMeta } from '../types-BEg5SQ1_.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+
+type NativeFileSystemMovePathState = 'present' | 'missing' | 'unknown';
+interface NativeFileSystemMoveRecoveryState {
+    readonly source: NativeFileSystemMovePathState;
+    readonly destination: NativeFileSystemMovePathState;
+}
+/**
+ * A copy/delete move failed and the provider could not prove that rollback
+ * restored the source-only state. Callers must inspect `state` before retrying.
+ */
+declare class NativeFileSystemMoveRecoveryError extends FsError {
+    readonly primaryError: FsError;
+    readonly recoveryErrors: readonly FsError[];
+    readonly state: NativeFileSystemMoveRecoveryState;
+    constructor(sourcePath: WorkspacePath, destinationPath: WorkspacePath, primaryError: FsError, recoveryErrors: readonly FsError[], state: NativeFileSystemMoveRecoveryState);
+}
+/** Direct File System Access API implementation of FileSystemProviderV2. */
+declare class NativeFileSystemProviderV2 implements FileSystemProviderV2 {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: FileSystemProviderCapabilities;
+    private readonly root;
+    private readonly lockKey;
+    private readonly subscriptions;
+    private readonly inFlight;
+    private disposed;
+    private disposePromise;
+    constructor(id: string, root: FileSystemDirectoryHandle);
+    stat(path: WorkspacePath): Promise<FileSystemEntrySnapshot | null>;
+    readFile(path: WorkspacePath): Promise<FileSystemFileRead | null>;
+    readDirectory(path: WorkspacePath): Promise<readonly FileSystemEntrySnapshot[]>;
+    writeFile(path: WorkspacePath, data: ArrayBuffer | Uint8Array, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    createDirectory(path: WorkspacePath, options?: FileSystemCreateDirectoryOptions): Promise<FileSystemDirectorySnapshot>;
+    remove(path: WorkspacePath, options?: FileSystemRemoveOptions): Promise<FileSystemRemoveResult>;
+    move(oldPath: WorkspacePath, newPath: WorkspacePath, options?: FileSystemMoveOptions): Promise<FileSystemEntrySnapshot>;
+    snapshot(): Promise<FileSystemSnapshot>;
+    watch(_listener: FileSystemWatchListener, options?: FileSystemWatchOptions): FileSystemWatchSubscription;
+    dispose(): Promise<void>;
+    private canonical;
+    private canonicalNonRoot;
+    private execute;
+    private mutate;
+    private assertOpen;
+    private translateError;
+    private error;
+    private assertExpectedVersion;
+    private resolveDirectory;
+    private getHandle;
+    private tryScanMetadata;
+    private tryScanSnapshot;
+    private requireMetadata;
+    private requireSnapshot;
+    private scanMetadataHandle;
+    private scanSnapshotHandle;
+    private scanHandle;
+    private scanFileMetadata;
+    private scanFileSnapshot;
+    private getFileSnapshot;
+    private fileMetadata;
+    private planParents;
+    private createDirectories;
+    private rollbackDirectories;
+    private writeBytes;
+    private removeEntry;
+    private removeEmptyFileIfPresent;
+    private currentTreeVersion;
+    private writeTree;
+    private rollbackMoveAndThrow;
+    /**
+     * Whether the source still holds exactly the bytes the move captured.
+     *
+     * A probe that fails answers "no": rollback must never treat an unverifiable
+     * source as whole, because that is precisely what licenses deleting the copy
+     * at the destination.
+     */
+    private matchesCapturedSource;
+    private probeScan;
+    private probeSnapshot;
+    private probePresence;
+}
+
+/**
+ * NativeFileSystemProvider — wraps the File System Access API
+ * (window.showDirectoryPicker / FileSystemDirectoryHandle).
+ *
+ * Progressive enhancement: only available in browsers that support
+ * the API (Chrome, Edge). Feature-detect with `isNativeFileSystemSupported()`.
+ */
+
+declare function isNativeFileSystemSupported(): boolean;
+/** Persist a FileSystemDirectoryHandle so it survives page reloads. */
+declare function storeDirectoryHandle(workspaceId: string, handle: FileSystemDirectoryHandle): Promise<void>;
+/** Retrieve a previously stored handle. Returns null if not found. */
+declare function loadDirectoryHandle(workspaceId: string): Promise<FileSystemDirectoryHandle | null>;
+/** Remove a stored handle (e.g. when deleting a workspace). */
+declare function removeDirectoryHandle(workspaceId: string): Promise<void>;
+declare class NativeFileSystemProvider implements FileSystemProvider {
+    readonly id: string;
+    readonly label: string;
+    readonly v2: NativeFileSystemProviderV2;
+    private root;
+    constructor(id: string, root: FileSystemDirectoryHandle);
+    private withMutationLock;
+    private copyDirectory;
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    private writeFileUnlocked;
+    commitFile(path: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    delete(path: string): Promise<void>;
+    private deleteUnlocked;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    private renameUnlocked;
+    readDirectory(path: string): Promise<FileSystemEntry[]>;
+    exists(path: string): Promise<boolean>;
+    createDirectory(path: string): Promise<void>;
+    stat(path: string): Promise<FileMeta | null>;
+    readBinary(path: string): Promise<ArrayBuffer | null>;
+    writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    private writeBinaryUnlocked;
+}
+/**
+ * Prompt the user to pick a local folder and return a NativeFileSystemProvider.
+ * The directory handle is persisted in IndexedDB so it can be restored later.
+ * Throws if the user cancels or the API is unsupported.
+ */
+declare function openNativeFolder(): Promise<NativeFileSystemProvider>;
+/**
+ * Restore a previously opened native folder from a persisted handle.
+ * Re-requests read/write permission (browser will show a prompt).
+ * Returns null if the handle is not found or permission is denied.
+ */
+declare function restoreNativeFolder(workspaceId: string): Promise<NativeFileSystemProvider | null>;
+
+export { type NativeFileSystemMovePathState, NativeFileSystemMoveRecoveryError, type NativeFileSystemMoveRecoveryState, NativeFileSystemProvider, NativeFileSystemProviderV2, isNativeFileSystemSupported, loadDirectoryHandle, openNativeFolder, removeDirectoryHandle, restoreNativeFolder, storeDirectoryHandle };

package/dist/filesystem/native.js

@@ -1,4 +1,27 @@
-/** Browser File System Access API provider entry point. */
-export { NativeFileSystemProvider, isNativeFileSystemSupported, openNativeFolder, restoreNativeFolder, storeDirectoryHandle, loadDirectoryHandle, removeDirectoryHandle, } from './native-provider.js';
-export { NativeFileSystemProviderV2, NativeFileSystemMoveRecoveryError, } from './native-provider-v2.js';
-//# sourceMappingURL=native.js.map
+import {
+  NativeFileSystemMoveRecoveryError,
+  NativeFileSystemProvider,
+  NativeFileSystemProviderV2,
+  isNativeFileSystemSupported,
+  loadDirectoryHandle,
+  openNativeFolder,
+  removeDirectoryHandle,
+  restoreNativeFolder,
+  storeDirectoryHandle
+} from "../chunk-4437YWLE.js";
+import "../chunk-DZB666V7.js";
+import "../chunk-KQ6756AJ.js";
+import "../chunk-M62ZGJ5I.js";
+import "../chunk-M5ZNQGR5.js";
+import "../chunk-AYWKIZLD.js";
+export {
+  NativeFileSystemMoveRecoveryError,
+  NativeFileSystemProvider,
+  NativeFileSystemProviderV2,
+  isNativeFileSystemSupported,
+  loadDirectoryHandle,
+  openNativeFolder,
+  removeDirectoryHandle,
+  restoreNativeFolder,
+  storeDirectoryHandle
+};