@bendyline/docblocks 1.1.2 → 2.1.0

package/dist/filesystem/index.d.ts

@@ -1,8 +1,228 @@
-export type { FileSystemProvider, FileSystemEntry, FileEntry, FolderEntry, FileMeta, } from './types.js';
-export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
-export { IndexedDBContentContainer } from './indexeddb-content-container.js';
-export { FileSystemContentContainer } from './filesystem-content-container.js';
-export { createFileMediaProvider } from './file-media-provider.js';
-export { NativeFileSystemProvider, isNativeFileSystemSupported, openNativeFolder, restoreNativeFolder, storeDirectoryHandle, loadDirectoryHandle, removeDirectoryHandle, } from './native-provider.js';
-export { ElectronFileSystemProvider, isElectronHost } from './electron-provider.js';
-//# sourceMappingURL=index.d.ts.map
+import { P as FsOperation, s as FileSystemProviderV2, r as FileSystemProviderCapabilities, q as FileSystemProvider, c as FileSystemAtomicity, d as FileSystemCaseSensitivity, z as FileSystemSymlinkPolicy, i as FileSystemDurability, 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 } from '../types-BEg5SQ1_.js';
+export { F as FileCommitResult, a as FileEntry, b as FileMeta, e as FileSystemConditionalWriteStrength, f as FileSystemCreateDirectoryMode, j as FileSystemEntry, l as FileSystemEntryWatchEvent, p as FileSystemOverflowWatchEvent, t as FileSystemProviderWithV2, x as FileSystemSnapshotEntry, y as FileSystemSnapshotFile, A as FileSystemVersion, B as FileSystemWatchErrorListener, C as FileSystemWatchEvent, D as FileSystemWatchEventOrigin, E as FileSystemWatchEventType, J as FileSystemWriteMode, L as FolderEntry, M as FsError, N as FsErrorCode, O as FsErrorContext, S as SerializedFsError, Q as deserializeFsError, R as fsErrorFromUnknown, T as getFileSystemProviderV2, U as hasFileSystemProviderV2, V as isQuotaExceededError, W as isSerializedFsError, X as mapDomExceptionToFsErrorCode, Y as mapNodeErrorCodeToFsErrorCode, Z as parseFileSystemVersion, _ as serializeFsError, $ as tryParseFileSystemVersion } from '../types-BEg5SQ1_.js';
+import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
+export { W as WORKSPACE_ROOT, p as parseWorkspacePath, t as tryParseWorkspacePath, w as workspacePathBasename, b as workspacePathContains, c as workspacePathDirname, d as workspacePathJoin, e as workspacePathToLegacy } from '../workspace-path-CWVrcuPL.js';
+import { MemoryFileSystemSnapshot, MemoryFileSystemProvider } from './memory.js';
+export { MemoryFilePayloadKind, MemoryFileSystemProviderV2, MemoryFileSystemSnapshotFile, MemoryFileSystemV2CompatibilityFile, MemoryFileSystemV2Replacement, MemoryFileSystemV2ReplacementFile, MemoryFileSystemV2State, MemoryFileSystemV2StateFile } from './memory.js';
+export { IndexedDBContentContainer, IndexedDBFileSystemProvider, IndexedDBFileSystemProviderV2, IndexedDBFileSystemProviderV2Options, IndexedDBLegacyConflictReason, IndexedDBLegacyConflictResolution, IndexedDBLegacyMigrationConflict, IndexedDBLegacyOpaqueDiscardTarget, IndexedDBLegacyOpaqueRecord, IndexedDBLegacyOpaqueRecordSummary, IndexedDBLegacyOpaqueValue, IndexedDBLegacyRecoveryCandidate, IndexedDBLegacyRecoveryKind } from './indexeddb.js';
+import { ContentContainer, ContentEntry } from '@bendyline/squisq/storage';
+import { MediaProvider } from '@bendyline/squisq/schemas';
+export { NativeFileSystemMovePathState, NativeFileSystemMoveRecoveryError, NativeFileSystemMoveRecoveryState, NativeFileSystemProvider, NativeFileSystemProviderV2, isNativeFileSystemSupported, loadDirectoryHandle, openNativeFolder, removeDirectoryHandle, restoreNativeFolder, storeDirectoryHandle } from './native.js';
+export { ElectronFileSystemProvider, ElectronFileSystemProviderV2 } from './electron.js';
+export { isElectronHost } from '../host/index.js';
+import '../types-CueK0tvU.js';
+
+interface DecodeUtf8TextOptions {
+    /** User-facing description of the payload being decoded. */
+    readonly label?: string;
+    /** Filesystem operation that produced the bytes. */
+    readonly operation?: FsOperation;
+    /** Canonical or display path associated with the payload. */
+    readonly path?: string;
+}
+/**
+ * Decode byte-authoritative text without silently replacing malformed input.
+ * Replacement characters are unsafe at persistence boundaries because a later
+ * save can permanently overwrite the original bytes with altered content.
+ */
+declare function decodeUtf8Text(data: ArrayBuffer | ArrayBufferView, options?: DecodeUtf8TextOptions): string;
+
+type LegacyFilePayloadModel = 'split' | 'binary-first-text-fallback' | 'binary-authoritative';
+interface LegacyFileSystemProviderV2AdapterOptions {
+    /**
+     * Split stores expose independent raw text and binary channels and reject
+     * dual payloads. Binary-first stores synthesize text for binary records, so
+     * the adapter only asks for text after readBinary() returns null. Binary-
+     * authoritative stores expose every file through readBinary().
+     */
+    readonly payloadModel: LegacyFilePayloadModel;
+    readonly writeAtomicity?: FileSystemAtomicity;
+    readonly moveAtomicity?: FileSystemAtomicity;
+    readonly caseSensitivity?: FileSystemCaseSensitivity;
+    readonly symlinkPolicy?: FileSystemSymlinkPolicy;
+    readonly durability?: FileSystemDurability;
+    /** Optional ownership hook; omitted when the adapter does not own the v1 provider. */
+    readonly dispose?: () => void | Promise<void>;
+}
+/**
+ * Correctness bridge for hardened v1 providers while storage backends migrate.
+ *
+ * The adapter deliberately serializes every observable operation. This makes a
+ * version check and its mutation indivisible among v2 callers, but cannot make
+ * calls that bypass the adapter participate in that boundary. Content-derived
+ * versions make those external changes visible on the next adapter operation.
+ */
+declare class LegacyFileSystemProviderV2Adapter implements FileSystemProviderV2 {
+    private readonly provider;
+    private readonly options;
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: FileSystemProviderCapabilities;
+    private operationTail;
+    private readonly subscriptions;
+    private closing;
+    private disposed;
+    private disposePromise;
+    constructor(provider: FileSystemProvider, options: LegacyFileSystemProviderV2AdapterOptions);
+    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 enqueue;
+    private assertAccepting;
+    private canonical;
+    private canonicalNonRoot;
+    private assertExpectedVersion;
+    private assertParents;
+    private captureTree;
+    private captureFile;
+    private invoke;
+    private error;
+}
+
+type DbkWorkspaceAssetLayout = 'auto' | 'preserve' | 'companion';
+interface DbkWorkspaceSnapshotOptions {
+    /** Provider-relative path of the transient workspace's active markdown file. */
+    targetDocumentPath: string;
+    /**
+     * `preserve` treats the DBK as a serialized workspace tree. `companion`
+     * rebases secondary Markdown files beneath `<document>_files/`. `auto`
+     * preserves a DBK whose primary path already matches the target, otherwise
+     * rebasing the secondary documents into the companion directory.
+     */
+    assetLayout?: DbkWorkspaceAssetLayout;
+}
+interface DbkWorkspaceSnapshot extends MemoryFileSystemSnapshot {
+    readonly sourceDocumentPath: string;
+    readonly targetDocumentPath: string;
+    readonly documentContent: string;
+    readonly assetLayout: Exclude<DbkWorkspaceAssetLayout, 'auto'>;
+}
+/**
+ * Fully materialize and validate a DBK container before touching its target
+ * provider. Transient workspace DBKs are intentionally Markdown-only: every
+ * member must be a valid UTF-8 `.md` file. A missing, unreadable, binary, or
+ * differently typed entry fails the snapshot as a whole.
+ */
+declare function createDbkWorkspaceSnapshot(source: ContentContainer, options: DbkWorkspaceSnapshotOptions): Promise<DbkWorkspaceSnapshot>;
+/**
+ * Replace a transient DBK workspace as one logical operation.
+ *
+ * Container reads and validation happen before provider mutation. The memory
+ * provider then stages and swaps the full tree synchronously, which removes
+ * stale files and guarantees the old tree survives any failed replacement.
+ */
+declare function replaceMemoryWorkspaceFromDbk(provider: MemoryFileSystemProvider, source: ContentContainer, options: DbkWorkspaceSnapshotOptions): Promise<DbkWorkspaceSnapshot>;
+
+/**
+ * FileSystemContentContainer — a ContentContainer backed by any
+ * FileSystemProvider, scoped to a sub-path (e.g., ".docblocks/media/").
+ *
+ * Used by the Electron desktop app so media lives inside the workspace
+ * folder (visible as regular files) rather than in a separate IndexedDB
+ * origin that only the app can see.
+ */
+
+declare class FileSystemContentContainer implements ContentContainer {
+    private readonly provider;
+    private readonly prefix;
+    constructor(provider: FileSystemProvider, prefix?: 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>;
+}
+
+/**
+ * createFileMediaProvider — per-file media storage following the pandoc /
+ * Word convention: a markdown file `notes.md` gets a sibling folder
+ * `notes_files/` that holds its images, audio, and video.
+ *
+ * Given:
+ *   • `container` — a ContentContainer scoped to the markdown file's
+ *     parent directory (so `readFile('notes_files/image.png')` maps to the
+ *     parent-relative path)
+ *   • `markdownBasename` — e.g. `"notes.md"`
+ *
+ * Returns a MediaProvider that:
+ *   • Writes new media under `{basename}_files/{name}` in the parent dir
+ *   • Returns the folder-qualified path (`notes_files/image.png`) from
+ *     addMedia so the markdown stays portable outside DocBlocks
+ *   • Resolves both bare (`image.png`) and folder-qualified
+ *     (`notes_files/image.png`) references — so legacy markdown and
+ *     exports from other tools both work
+ */
+
+declare function createFileMediaProvider(container: ContentContainer, markdownBasename: string): MediaProvider;
+
+/** Return the hidden companion directory used for a document's media and versions. */
+declare function documentCompanionPath(documentPath: string): string;
+/**
+ * Move an explorer entry without overwriting an existing entry. Markdown files
+ * carry their hidden `<basename>_files` companion directory with them.
+ */
+declare function moveFileSystemEntry(provider: FileSystemProvider, oldPath: string, newPath: string, kind: 'file' | 'directory'): Promise<void>;
+
+type FileSystemPathPresence = 'present' | 'missing' | 'unknown';
+interface FileSystemPartialMoveState {
+    readonly source: FileSystemPathPresence;
+    readonly destination: FileSystemPathPresence;
+    readonly companionSource: FileSystemPathPresence;
+    readonly companionDestination: FileSystemPathPresence;
+}
+type FileSystemMoveLocation = 'source' | 'destination' | 'both' | 'neither' | 'unknown';
+interface FileSystemEntryMoveState {
+    readonly source: FileSystemPathPresence;
+    readonly destination: FileSystemPathPresence;
+}
+/**
+ * One provider move failed without restoring a provable source-only state.
+ * This is backend-neutral: callers must use `location`, never infer from the
+ * original exception or a provider's advertised move atomicity.
+ */
+declare class FileSystemMoveRecoveryError extends Error {
+    readonly sourcePath: string;
+    readonly destinationPath: string;
+    readonly state: FileSystemEntryMoveState;
+    readonly moveError: unknown;
+    readonly code: "partial-move";
+    constructor(sourcePath: string, destinationPath: string, state: FileSystemEntryMoveState, moveError: unknown);
+    get location(): FileSystemMoveLocation;
+    /** Alias used by DocumentSession's document-retarget recovery protocol. */
+    get documentLocation(): FileSystemMoveLocation;
+}
+/**
+ * A compound document/companion move failed and the document rollback also
+ * failed. Callers must use the recorded post-state instead of assuming the
+ * original path is still authoritative.
+ */
+declare class FileSystemPartialMoveError extends Error {
+    readonly sourcePath: string;
+    readonly destinationPath: string;
+    readonly companionSourcePath: string;
+    readonly companionDestinationPath: string;
+    readonly state: FileSystemPartialMoveState;
+    readonly moveError: unknown;
+    readonly rollbackError: unknown;
+    readonly code: "partial-move";
+    constructor(sourcePath: string, destinationPath: string, companionSourcePath: string, companionDestinationPath: string, state: FileSystemPartialMoveState, moveError: unknown, rollbackError: unknown);
+    get documentLocation(): FileSystemMoveLocation;
+    get companionLocation(): FileSystemMoveLocation;
+}
+declare function isFileSystemPartialMoveError(error: unknown): error is FileSystemPartialMoveError;
+declare function isFileSystemMoveRecoveryError(error: unknown): error is FileSystemMoveRecoveryError;
+declare function isFileSystemMoveStateError(error: unknown): error is FileSystemMoveRecoveryError | FileSystemPartialMoveError;
+declare function describePartialMove(provider: FileSystemProvider, sourcePath: string, destinationPath: string, companionSourcePath: string, companionDestinationPath: string): Promise<FileSystemPartialMoveState>;
+declare function describeEntryMove(provider: FileSystemProvider, sourcePath: string, destinationPath: string): Promise<FileSystemEntryMoveState>;
+
+export { type DbkWorkspaceAssetLayout, type DbkWorkspaceSnapshot, type DbkWorkspaceSnapshotOptions, type DecodeUtf8TextOptions, FileSystemAtomicity, FileSystemCaseSensitivity, FileSystemContentContainer, FileSystemCreateDirectoryOptions, FileSystemDirectorySnapshot, FileSystemDurability, type FileSystemEntryMoveState, FileSystemEntrySnapshot, FileSystemFileRead, FileSystemFileSnapshot, type FileSystemMoveLocation, FileSystemMoveOptions, FileSystemMoveRecoveryError, FileSystemPartialMoveError, type FileSystemPartialMoveState, type FileSystemPathPresence, FileSystemProvider, FileSystemProviderCapabilities, FileSystemProviderV2, FileSystemRemoveOptions, FileSystemRemoveResult, FileSystemSnapshot, FileSystemSymlinkPolicy, FileSystemWatchListener, FileSystemWatchOptions, FileSystemWatchSubscription, FileSystemWriteOptions, FsOperation, type LegacyFilePayloadModel, LegacyFileSystemProviderV2Adapter, type LegacyFileSystemProviderV2AdapterOptions, MemoryFileSystemProvider, MemoryFileSystemSnapshot, WorkspacePath, createDbkWorkspaceSnapshot, createFileMediaProvider, decodeUtf8Text, describeEntryMove, describePartialMove, documentCompanionPath, isFileSystemMoveRecoveryError, isFileSystemMoveStateError, isFileSystemPartialMoveError, moveFileSystemEntry, replaceMemoryWorkspaceFromDbk };

package/dist/filesystem/index.js

@@ -1,7 +1,134 @@
-export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
-export { IndexedDBContentContainer } from './indexeddb-content-container.js';
-export { FileSystemContentContainer } from './filesystem-content-container.js';
-export { createFileMediaProvider } from './file-media-provider.js';
-export { NativeFileSystemProvider, isNativeFileSystemSupported, openNativeFolder, restoreNativeFolder, storeDirectoryHandle, loadDirectoryHandle, removeDirectoryHandle, } from './native-provider.js';
-export { ElectronFileSystemProvider, isElectronHost } from './electron-provider.js';
+import {
+  FileSystemContentContainer,
+  LegacyFileSystemProviderV2Adapter,
+  createDbkWorkspaceSnapshot,
+  createFileMediaProvider,
+  documentCompanionPath,
+  moveFileSystemEntry,
+  replaceMemoryWorkspaceFromDbk
+} from "../chunk-XUML3MKV.js";
+import {
+  IndexedDBContentContainer,
+  IndexedDBFileSystemProvider,
+  IndexedDBFileSystemProviderV2
+} from "../chunk-6IYMTYMQ.js";
+import {
+  MemoryFileSystemProvider,
+  MemoryFileSystemProviderV2
+} from "../chunk-DN7A33LL.js";
+import {
+  NativeFileSystemMoveRecoveryError,
+  NativeFileSystemProvider,
+  NativeFileSystemProviderV2,
+  isNativeFileSystemSupported,
+  loadDirectoryHandle,
+  openNativeFolder,
+  removeDirectoryHandle,
+  restoreNativeFolder,
+  storeDirectoryHandle
+} from "../chunk-WJKYY5QR.js";
+import "../chunk-AEHCVWU5.js";
+import "../chunk-GM5YXU4L.js";
+import {
+  ElectronFileSystemProvider,
+  ElectronFileSystemProviderV2
+} from "../chunk-VTCSF7VS.js";
+import {
+  isElectronHost
+} from "../chunk-BNKV7MTO.js";
+import "../chunk-FNW556FN.js";
+import "../chunk-U722UUFN.js";
+import {
+  parseFileSystemVersion,
+  tryParseFileSystemVersion
+} from "../chunk-P4WATND4.js";
+import {
+  FileSystemMoveRecoveryError,
+  FileSystemPartialMoveError,
+  describeEntryMove,
+  describePartialMove,
+  isFileSystemMoveRecoveryError,
+  isFileSystemMoveStateError,
+  isFileSystemPartialMoveError
+} from "../chunk-MNSZ7EZN.js";
+import {
+  decodeUtf8Text
+} from "../chunk-FA7UNOXK.js";
+import {
+  FsError,
+  WORKSPACE_ROOT,
+  deserializeFsError,
+  fsErrorFromUnknown,
+  isQuotaExceededError,
+  isSerializedFsError,
+  mapDomExceptionToFsErrorCode,
+  mapNodeErrorCodeToFsErrorCode,
+  parseWorkspacePath,
+  serializeFsError,
+  tryParseWorkspacePath,
+  workspacePathBasename,
+  workspacePathContains,
+  workspacePathDirname,
+  workspacePathJoin,
+  workspacePathToLegacy
+} from "../chunk-JS6XFWQK.js";
+import "../chunk-RVPGQBWR.js";
+import {
+  getFileSystemProviderV2,
+  hasFileSystemProviderV2
+} from "../chunk-EZKJZUNJ.js";
+export {
+  ElectronFileSystemProvider,
+  ElectronFileSystemProviderV2,
+  FileSystemContentContainer,
+  FileSystemMoveRecoveryError,
+  FileSystemPartialMoveError,
+  FsError,
+  IndexedDBContentContainer,
+  IndexedDBFileSystemProvider,
+  IndexedDBFileSystemProviderV2,
+  LegacyFileSystemProviderV2Adapter,
+  MemoryFileSystemProvider,
+  MemoryFileSystemProviderV2,
+  NativeFileSystemMoveRecoveryError,
+  NativeFileSystemProvider,
+  NativeFileSystemProviderV2,
+  WORKSPACE_ROOT,
+  createDbkWorkspaceSnapshot,
+  createFileMediaProvider,
+  decodeUtf8Text,
+  describeEntryMove,
+  describePartialMove,
+  deserializeFsError,
+  documentCompanionPath,
+  fsErrorFromUnknown,
+  getFileSystemProviderV2,
+  hasFileSystemProviderV2,
+  isElectronHost,
+  isFileSystemMoveRecoveryError,
+  isFileSystemMoveStateError,
+  isFileSystemPartialMoveError,
+  isNativeFileSystemSupported,
+  isQuotaExceededError,
+  isSerializedFsError,
+  loadDirectoryHandle,
+  mapDomExceptionToFsErrorCode,
+  mapNodeErrorCodeToFsErrorCode,
+  moveFileSystemEntry,
+  openNativeFolder,
+  parseFileSystemVersion,
+  parseWorkspacePath,
+  removeDirectoryHandle,
+  replaceMemoryWorkspaceFromDbk,
+  restoreNativeFolder,
+  serializeFsError,
+  storeDirectoryHandle,
+  tryParseFileSystemVersion,
+  tryParseWorkspacePath,
+  workspacePathBasename,
+  workspacePathContains,
+  workspacePathDirname,
+  workspacePathJoin,
+  workspacePathToLegacy
+};
 //# sourceMappingURL=index.js.map

package/dist/filesystem/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/filesystem/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/filesystem/indexeddb.d.ts

@@ -0,0 +1,284 @@
+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 };