@bendyline/docblocks 2.7.2 → 2.7.4

package/THIRD_PARTY_NOTICES.txt

@@ -14,7 +14,7 @@ This notice is included in the published npm tarball. Transitive packages instal
 
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
-| @bendyline/squisq | 2.12.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.12.5 | MIT | https://github.com/bendyline/squisq |
 | @types/debug | 4.1.12 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/hast | 3.0.4 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/katex | 0.16.8 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
@@ -132,7 +132,7 @@ This notice is included in the published npm tarball. Transitive packages instal
 Package-local license, copying, and notice files are reproduced below. Where a published package omits its repository license, the reviewed aggregate or README identified in `Source files` supplies the retained material.
 
 ==============================================================================
-Components: @bendyline/squisq@2.12.0
+Components: @bendyline/squisq@2.12.5
 Source files: node_modules/@bendyline/squisq/LICENSE
 ==============================================================================
 MIT License
@@ -158,7 +158,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq@2.12.0
+Components: @bendyline/squisq@2.12.5
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -189,7 +189,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.12.0
+Components: @bendyline/squisq@2.12.5
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

package/dist/{capabilities-BvUC17t9.d.ts → capabilities-BJEkIsO1.d.ts}

@@ -1,5 +1,5 @@
-import { F as FileCommitResult, c as FileSystemEntry, b as FileMeta } from './types-BvDnr3YU.js';
-import { D as DocBlocksHostFsV2API } from './filesystem-v2-C8AdSXUN.js';
+import { F as FileCommitResult, c as FileSystemEntry, b as FileMeta } from './types-DLteNrK0.js';
+import { D as DocBlocksHostFsV2API } from './filesystem-v2-CXdAPR27.js';
 
 /** Provider-neutral catalog management. IDs never authorize filesystem access. */
 interface AiKnowledgeCatalog {
@@ -190,9 +190,11 @@ interface AiChatMessage {
  * What the request is for.
  *
  * This exists so the host can apply different budgets to a person waiting on a
- * draft and a background review pass. It is never sent to the model.
+ * draft and a background review pass. It is never sent to the model. Only
+ * `write` may spend its output budget reasoning; `study` (summaries, quizzes
+ * and flashcards, made in many small calls with explicit caps) never does.
  */
-type AiChatPurpose = 'write' | 'review' | 'illustrate' | 'chat';
+type AiChatPurpose = 'write' | 'review' | 'illustrate' | 'study' | 'chat';
 interface AiChatRequest {
     readonly messages: readonly AiChatMessage[];
     /** Opaque provider model id. Omitted means "the host's current choice". */
@@ -890,6 +892,8 @@ interface HostExportTargetGrant {
 }
 /** Native export target selection and binary file writing. */
 interface DocBlocksHostExportAPI {
+    /** Open a successfully saved grant in its default app; Markdown opens in DocBlocks. */
+    openSaved?(documentId: string, grantId: string): Promise<void>;
     /** A share-sheet outcome is never a durable export target. Android can only report presentation. */
     share?(filename: string, data: ArrayBuffer | Uint8Array): Promise<'shared' | 'presented' | 'cancelled'>;
     /** Resolve an exact remembered grant or a display-only host suggestion. */
@@ -1186,6 +1190,7 @@ interface HostCapabilities {
     readonly exportDestinations: boolean;
     /** Remembered, re-resolvable export targets (`resolveTarget`/`pickTarget`). */
     readonly exportRememberedTargets: boolean;
+    readonly openSavedExports: boolean;
     readonly externalResources: boolean;
     readonly openRequests: boolean;
     readonly menuCommands: boolean;

package/dist/{chunk-KQ6756AJ.js → chunk-3GSMJ4MQ.js}

@@ -1,6 +1,6 @@
 import {
   workspacePathDirname
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/internal/parent-chain.ts
 function parentChain(path) {

package/dist/{chunk-YWYT6K6J.js → chunk-3LXXRIO2.js}

@@ -1,6 +1,6 @@
 import {
   tryParseWorkspacePath
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/mcp/types.ts
 var DOCBLOCKS_MCP_WIRE_VERSION = 1;

package/dist/{chunk-STUIS5UZ.js → chunk-7LPIGCBG.js}

@@ -1,7 +1,7 @@
 import {
   FILE_SYSTEM_TRANSFER_LIMITS,
   maybeGetDocBlocksHost
-} from "./chunk-NM5KF6YF.js";
+} from "./chunk-KXQDMZFH.js";
 import {
   parseFileSystemCapabilities
 } from "./chunk-245W57QP.js";
@@ -26,11 +26,12 @@ import {
   WORKSPACE_ROOT,
   deserializeFsError,
   fsErrorFromUnknown,
+  isFsErrorCode,
   isSerializedFsError,
   parseWorkspacePath,
   workspacePathBasename,
   workspacePathDirname
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/host-provider-v2.ts
 var fallbackInstanceSequence = 0;
@@ -419,7 +420,13 @@ function normalizeEntry(entry) {
     if (!isNonNegativeSafeInteger(entry.size)) {
       throw new TypeError("Filesystem file size must be a non-negative safe integer.");
     }
-    return Object.freeze({ ...common, kind: "file", size: entry.size });
+    const readIssue = normalizeReadIssue(entry.readIssue);
+    return Object.freeze({
+      ...common,
+      kind: "file",
+      size: entry.size,
+      ...readIssue ? { readIssue } : {}
+    });
   }
   if (entry.kind === "directory") {
     if (entry.size !== null) throw new TypeError("Filesystem directory size must be null.");
@@ -427,6 +434,13 @@ function normalizeEntry(entry) {
   }
   throw new TypeError("Unknown filesystem entry kind.");
 }
+function normalizeReadIssue(value) {
+  if (value === void 0) return void 0;
+  if (!isRecord(value) || !isFsErrorCode(value.code) || !isBoundedString(value.message, HOST_WIRE_LIMITS.messageCharacters, 1)) {
+    throw new TypeError("Filesystem entry read issue is malformed.");
+  }
+  return Object.freeze({ code: value.code, message: value.message });
+}
 function normalizeDirectoryListing(value, parent) {
   if (!Array.isArray(value)) throw new TypeError("Expected a filesystem directory listing.");
   const entries = value.map(normalizeEntry);

package/dist/{chunk-UK7R3RC7.js → chunk-BC42VRYW.js}

@@ -1,6 +1,6 @@
 import {
   parseWorkspacePath
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/workspace-settings/settings.ts
 var WORKSPACE_SETTINGS_DIRECTORY = ".docblocks";

package/dist/{chunk-IGB2VSRE.js → chunk-FIEMYP2N.js}

@@ -3,11 +3,11 @@ import {
 } from "./chunk-XAMILHQP.js";
 import {
   decodeUtf8Text
-} from "./chunk-M5ZNQGR5.js";
+} from "./chunk-IYKGM3PV.js";
 import {
   FsError,
   parseWorkspacePath
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/move-error.ts
 function locationFromPresence(source, destination) {

package/dist/{chunk-M5ZNQGR5.js → chunk-IYKGM3PV.js}

@@ -1,6 +1,6 @@
 import {
   FsError
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/utf8.ts
 function decodeUtf8Text(data, options = {}) {

package/dist/{chunk-6UPO2GE6.js → chunk-K5HRMSXD.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DZB666V7.js";
 import {
   parentChain
-} from "./chunk-KQ6756AJ.js";
+} from "./chunk-3GSMJ4MQ.js";
 import {
   bytesEqual,
   compareSnapshotsByName,
@@ -15,7 +15,7 @@ import {
 } from "./chunk-LPIJ6HKL.js";
 import {
   decodeUtf8Text
-} from "./chunk-M5ZNQGR5.js";
+} from "./chunk-IYKGM3PV.js";
 import {
   FsError,
   WORKSPACE_ROOT,
@@ -25,7 +25,7 @@ import {
   workspacePathContains,
   workspacePathDirname,
   workspacePathJoin
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/native-provider-v2.ts
 var NativeFileSystemMoveRecoveryError = class extends FsError {

package/dist/{chunk-NM5KF6YF.js → chunk-KXQDMZFH.js}

@@ -27,6 +27,7 @@ var NO_CAPABILITIES = Object.freeze({
   clipboard: false,
   exportDestinations: false,
   exportRememberedTargets: false,
+  openSavedExports: false,
   externalResources: false,
   openRequests: false,
   menuCommands: false,
@@ -103,6 +104,7 @@ function deriveHostCapabilities(host) {
     clipboard: hasMethod(host.clipboard, "writeText"),
     exportDestinations: hasMethod(exports, "save"),
     exportRememberedTargets: hasMethod(exports, "resolveTarget") && hasMethod(exports, "pickTarget"),
+    openSavedExports: hasMethod(exports, "openSaved"),
     externalResources: hasMethod(host.external, "readText"),
     openRequests: hasMethod(host, "onOpenRequest"),
     menuCommands: hasMethod(host, "onMenuCommand"),
@@ -148,7 +150,13 @@ var AI_WIRE_LIMITS = Object.freeze({
   downloadBytesCeiling: Number.MAX_SAFE_INTEGER
 });
 var CHAT_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant"]);
-var CHAT_PURPOSES = /* @__PURE__ */ new Set(["write", "review", "illustrate", "chat"]);
+var CHAT_PURPOSES = /* @__PURE__ */ new Set([
+  "write",
+  "review",
+  "illustrate",
+  "study",
+  "chat"
+]);
 var REVIEW_MODES = /* @__PURE__ */ new Set(["off", "explicit", "implicit"]);
 var FINISH_REASONS = /* @__PURE__ */ new Set(["stop", "length", "cancelled"]);
 var UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([

package/dist/{chunk-UDEWLHQI.js → chunk-LDAG5NTQ.js}

@@ -1,6 +1,6 @@
 import {
   parentChainWithRoot
-} from "./chunk-KQ6756AJ.js";
+} from "./chunk-3GSMJ4MQ.js";
 import {
   compareSnapshotsByName,
   compareText,
@@ -11,7 +11,7 @@ import {
 } from "./chunk-LPIJ6HKL.js";
 import {
   decodeUtf8Text
-} from "./chunk-M5ZNQGR5.js";
+} from "./chunk-IYKGM3PV.js";
 import {
   FsError,
   WORKSPACE_ROOT,
@@ -19,7 +19,7 @@ import {
   workspacePathBasename,
   workspacePathContains,
   workspacePathDirname
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/memory-provider-v2.ts
 var MEMORY_CAPABILITIES = Object.freeze({

package/dist/{chunk-7SN7YQL4.js → chunk-LJLQYXVL.js}

@@ -1,6 +1,6 @@
 import {
   guessMimeType
-} from "./chunk-HKOOHM67.js";
+} from "./chunk-Q3OFZWJS.js";
 import {
   bytesEqual,
   compareSnapshotsByName,
@@ -17,7 +17,7 @@ import {
   createFileSystemDocumentTarget,
   describeEntryMove,
   describePartialMove
-} from "./chunk-IGB2VSRE.js";
+} from "./chunk-FIEMYP2N.js";
 import {
   getFileSystemProviderV2
 } from "./chunk-XAMILHQP.js";
@@ -31,7 +31,98 @@ import {
   workspacePathDirname,
   workspacePathJoin,
   workspacePathToLegacy
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
+
+// src/filesystem/wiki-links.ts
+var markdownModule = null;
+function loadMarkdown() {
+  markdownModule ?? (markdownModule = import("@bendyline/squisq/markdown"));
+  return markdownModule;
+}
+async function suggestWikiArticles(files, directories, documentPath, query, extension = ".md", explicitExtensions = false) {
+  const { wikiLinkPath } = await loadMarkdown();
+  if (query.length > 2048 || query && !wikiLinkPath(`${query.trimEnd()}x`)) return [];
+  const source = parseWorkspacePath(documentPath);
+  const parent = workspacePathDirname(source);
+  const rootPrefix = parent ? `${parent}/` : "";
+  const slash = query.lastIndexOf("/");
+  const prefix = query.slice(0, slash + 1);
+  const needle = query.slice(slash + 1).toLowerCase();
+  const candidates = [];
+  const relative = (path) => {
+    if (!path.startsWith(rootPrefix)) return null;
+    const target = path.slice(rootPrefix.length);
+    if (!target.startsWith(prefix)) return null;
+    const name = target.slice(prefix.length);
+    return name && !name.includes("/") && name.toLowerCase().includes(needle) ? target : null;
+  };
+  for (const directory of directories) {
+    const target = relative(directory);
+    if (target && target.length < 2048 && wikiLinkPath(target))
+      candidates.push({
+        target: `${target}/`,
+        label: `${target.slice(prefix.length)}/`,
+        kind: "folder"
+      });
+  }
+  const articlePaths = new Set(files.map((file) => file.path));
+  for (const file of files) {
+    if (file.path === source || !/\.(?:md|html?)$/i.test(file.path)) continue;
+    const target = relative(file.path);
+    if (!target || !wikiLinkPath(target)) continue;
+    const stem = file.path.replace(/\.(?:md|html?)$/i, "");
+    const preferred = [`${stem}${extension}`, `${stem}.md`, `${stem}.html`, `${stem}.htm`].find(
+      (path) => articlePaths.has(path)
+    );
+    const insertion = !explicitExtensions && file.path === preferred ? target.replace(/\.(?:md|html?)$/i, "") : target;
+    candidates.push({ target: insertion, label: insertion.slice(prefix.length), kind: "article" });
+  }
+  return candidates.sort(
+    (a, b) => Number(b.kind === "folder") - Number(a.kind === "folder") || Number(b.label.toLowerCase().startsWith(needle)) - Number(a.label.toLowerCase().startsWith(needle)) || a.label.localeCompare(b.label) || a.target.localeCompare(b.target)
+  ).slice(0, 20);
+}
+async function resolveWikiArticlePath(documentPath, target, extension = ".md") {
+  const { wikiLinkPath } = await loadMarkdown();
+  const relative = wikiLinkPath(target, extension);
+  if (!relative) throw new FsError("invalid-path", "Invalid wiki article name.");
+  return workspacePathJoin(workspacePathDirname(parseWorkspacePath(documentPath)), relative);
+}
+async function findWikiArticle(provider, documentPath, target, extension = ".md") {
+  const { wikiLinkPath } = await loadMarkdown();
+  const preferred = await resolveWikiArticlePath(documentPath, target, extension);
+  const candidates = /\.(?:md|html?)$/i.test(target) ? [target] : [.../* @__PURE__ */ new Set([`${target}${extension}`, `${target}.md`, `${target}.html`, `${target}.htm`])];
+  for (const relativePath of candidates) {
+    const path = await resolveWikiArticlePath(documentPath, relativePath, extension);
+    if (await wikiArticleExists(provider, path)) return { path, relativePath, exists: true };
+  }
+  return { path: preferred, relativePath: wikiLinkPath(target, extension), exists: false };
+}
+async function wikiArticleExists(provider, path) {
+  const v2 = getFileSystemProviderV2(provider);
+  if (!v2) return await provider.stat(path) !== null;
+  const entry = await v2.stat(path);
+  if (entry && entry.kind !== "file")
+    throw new FsError("type-mismatch", "The article path is a folder.");
+  return entry !== null;
+}
+async function ensureWikiArticle(provider, path) {
+  if (await wikiArticleExists(provider, path)) return false;
+  const v2 = getFileSystemProviderV2(provider);
+  if (!v2) throw new FsError("not-supported", "This workspace cannot create articles safely.");
+  try {
+    await v2.writeFile(path, new Uint8Array(), {
+      mode: "create",
+      expectedVersion: null,
+      createParents: true
+    });
+    return true;
+  } catch (error) {
+    if (error instanceof FsError && (error.code === "already-exists" || error.code === "conflict")) {
+      if (await wikiArticleExists(provider, path)) return false;
+    }
+    throw error;
+  }
+}
 
 // src/filesystem/legacy-v2-adapter.ts
 var EPOCH = (/* @__PURE__ */ new Date(0)).toISOString();
@@ -1104,6 +1195,11 @@ function createFileMediaProvider(container, markdownBasename) {
 }
 
 export {
+  suggestWikiArticles,
+  resolveWikiArticlePath,
+  findWikiArticle,
+  wikiArticleExists,
+  ensureWikiArticle,
   LegacyFileSystemProviderV2Adapter,
   rewriteCompanionReferences,
   documentCompanionPath,

package/dist/{chunk-L657M3XG.js → chunk-PSGAZKWO.js}

@@ -1,10 +1,10 @@
 import {
   HostFileSystemProviderV2
-} from "./chunk-STUIS5UZ.js";
+} from "./chunk-7LPIGCBG.js";
 import {
   ELECTRON_FILE_SYSTEM_V2_CAPABILITIES,
   maybeGetDocBlocksHost
-} from "./chunk-NM5KF6YF.js";
+} from "./chunk-KXQDMZFH.js";
 
 // src/filesystem/electron-provider-v2.ts
 var ElectronFileSystemProviderV2 = class extends HostFileSystemProviderV2 {

package/dist/{chunk-HKOOHM67.js → chunk-Q3OFZWJS.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-DZB666V7.js";
 import {
   parentChainWithRoot
-} from "./chunk-KQ6756AJ.js";
+} from "./chunk-3GSMJ4MQ.js";
 import {
   isRecord
 } from "./chunk-73OOROXH.js";
@@ -22,7 +22,7 @@ import {
 } from "./chunk-LPIJ6HKL.js";
 import {
   decodeUtf8Text
-} from "./chunk-M5ZNQGR5.js";
+} from "./chunk-IYKGM3PV.js";
 import {
   FsError,
   WORKSPACE_ROOT,
@@ -31,7 +31,7 @@ import {
   workspacePathBasename,
   workspacePathContains,
   workspacePathDirname
-} from "./chunk-AYWKIZLD.js";
+} from "./chunk-UTH3HYCZ.js";
 
 // src/filesystem/indexeddb-provider-v2.ts
 var ENTRY_SCHEMA_VERSION = 1;

package/dist/{chunk-AYWKIZLD.js → chunk-UTH3HYCZ.js}

@@ -17,6 +17,9 @@ var FS_ERROR_CODES = /* @__PURE__ */ new Set([
   "aborted",
   "io"
 ]);
+function isFsErrorCode(value) {
+  return typeof value === "string" && FS_ERROR_CODES.has(value);
+}
 var FS_OPERATIONS = /* @__PURE__ */ new Set([
   "parse-path",
   "read",
@@ -109,7 +112,7 @@ function mapNodeErrorCodeToFsErrorCode(code) {
 function isSerializedFsError(value) {
   if (!value || typeof value !== "object") return false;
   const candidate = value;
-  return candidate.name === "FsError" && typeof candidate.code === "string" && FS_ERROR_CODES.has(candidate.code) && typeof candidate.message === "string" && (candidate.operation === null || typeof candidate.operation === "string" && FS_OPERATIONS.has(candidate.operation)) && (candidate.path === null || typeof candidate.path === "string") && (candidate.destinationPath === null || typeof candidate.destinationPath === "string") && typeof candidate.retryable === "boolean";
+  return candidate.name === "FsError" && isFsErrorCode(candidate.code) && typeof candidate.message === "string" && (candidate.operation === null || typeof candidate.operation === "string" && FS_OPERATIONS.has(candidate.operation)) && (candidate.path === null || typeof candidate.path === "string") && (candidate.destinationPath === null || typeof candidate.destinationPath === "string") && typeof candidate.retryable === "boolean";
 }
 function deserializeFsError(value) {
   return new FsError(value.code, value.message, {
@@ -205,6 +208,7 @@ function invalidPath(path, message) {
 }
 
 export {
+  isFsErrorCode,
   FsError,
   mapDomExceptionToFsErrorCode,
   mapNodeErrorCodeToFsErrorCode,

package/dist/{chunk-QS5WTLUZ.js → chunk-XI2LYBRR.js}

@@ -4,6 +4,166 @@ import {
 import {
   getFileSystemProviderV2
 } from "./chunk-XAMILHQP.js";
+import {
+  parseWorkspacePath
+} from "./chunk-UTH3HYCZ.js";
+
+// src/workspace/backup.ts
+var WORKSPACE_BACKUP_MANIFEST = "docblocks-backup.json";
+var WORKSPACE_BACKUP_LIMITS = Object.freeze({
+  maxEntries: 1e4,
+  maxUncompressedBytes: 128 * 1024 * 1024,
+  maxEntryUncompressedBytes: 64 * 1024 * 1024,
+  maxCompressionRatio: 1e3
+});
+function exactRecord(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid workspace backup metadata.");
+  }
+  const record = value;
+  if (Object.keys(record).length !== keys.length || keys.some((key) => !(key in record))) {
+    throw new Error("Unrecognized workspace backup metadata fields.");
+  }
+  return record;
+}
+function entryPath(value) {
+  if (typeof value !== "string" || value.length > 4096)
+    throw new Error("Invalid backup entry path.");
+  const path = parseWorkspacePath(value);
+  if (!path || path !== value)
+    throw new Error("Backup entries must have canonical relative paths.");
+  return path;
+}
+function parseWorkspaceBackupManifest(value) {
+  const record = exactRecord(value, ["format", "version", "workspaces"]);
+  if (record.format !== "docblocks-workspace-backup" || record.version !== 1) {
+    throw new Error("This workspace backup version is not supported.");
+  }
+  if (!Array.isArray(record.workspaces) || !record.workspaces.length || record.workspaces.length > 100) {
+    throw new Error("A backup must contain between 1 and 100 workspaces.");
+  }
+  let directoryCount = 0;
+  const workspaces = record.workspaces.map((value2, index) => {
+    const workspace = exactRecord(value2, ["name", "prefix", "directories"]);
+    if (typeof workspace.name !== "string" || !workspace.name.trim() || workspace.name.length > 1024) {
+      throw new Error("Invalid backup workspace name.");
+    }
+    if (workspace.prefix !== `workspaces/${index + 1}` || !Array.isArray(workspace.directories)) {
+      throw new Error("Invalid backup workspace location.");
+    }
+    directoryCount += workspace.directories.length;
+    if (directoryCount > WORKSPACE_BACKUP_LIMITS.maxEntries)
+      throw new Error("Too many backup directories.");
+    const directories = workspace.directories.map(entryPath);
+    if (new Set(directories).size !== directories.length)
+      throw new Error("Duplicate backup directories.");
+    return { name: workspace.name, prefix: workspace.prefix, directories };
+  });
+  return { format: "docblocks-workspace-backup", version: 1, workspaces };
+}
+async function appendWorkspaceBackup(container, provider, previous) {
+  const snapshot = await provider.snapshot();
+  const workspace = {
+    name: provider.label || "Workspace",
+    prefix: `workspaces/${previous.length + 1}`,
+    directories: snapshot.entries.filter((entry) => entry.kind === "directory" && entry.path !== "").map((entry) => entry.path)
+  };
+  const workspaces = [...previous, workspace];
+  parseWorkspaceBackupManifest({ format: "docblocks-workspace-backup", version: 1, workspaces });
+  for (const entry of snapshot.entries) {
+    if (entry.kind === "file") {
+      entryPath(entry.path);
+      if (entry.data.byteLength > WORKSPACE_BACKUP_LIMITS.maxEntryUncompressedBytes) {
+        throw new Error(`Backup file exceeds the 64 MiB restore limit: ${entry.path}`);
+      }
+      await container.writeFile(`${workspace.prefix}/${entry.path}`, entry.data);
+    }
+  }
+  return workspaces;
+}
+async function finishWorkspaceBackup(container, workspaces) {
+  const manifest = parseWorkspaceBackupManifest({
+    format: "docblocks-workspace-backup",
+    version: 1,
+    workspaces
+  });
+  const bytes = new TextEncoder().encode(JSON.stringify(manifest));
+  if (bytes.byteLength > 1024 * 1024) throw new Error("Workspace backup metadata is too large.");
+  await container.writeFile(WORKSPACE_BACKUP_MANIFEST, bytes);
+  await readWorkspaceBackup(container, "Workspace");
+}
+async function readWorkspaceBackup(container, legacyName) {
+  const entries = await container.listFiles();
+  if (entries.length > WORKSPACE_BACKUP_LIMITS.maxEntries)
+    throw new Error("Too many backup files.");
+  const paths = entries.map((entry) => entryPath(entry.path));
+  if (new Set(paths).size !== paths.length) throw new Error("Duplicate backup files.");
+  const archiveEntries = new Set(paths);
+  for (const path of paths) {
+    const parts = path.split("/");
+    while (parts.length > 1) {
+      parts.pop();
+      archiveEntries.add(`${parts.join("/")}/`);
+    }
+  }
+  if (archiveEntries.size > WORKSPACE_BACKUP_LIMITS.maxEntries)
+    throw new Error("Too many backup entries.");
+  const metadata = paths.includes(parseWorkspacePath(WORKSPACE_BACKUP_MANIFEST)) ? await container.readFile(WORKSPACE_BACKUP_MANIFEST) : null;
+  if (metadata && metadata.byteLength > 1024 * 1024)
+    throw new Error("Workspace backup metadata is too large.");
+  const manifest = metadata ? parseWorkspaceBackupManifest(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(metadata))
+  ) : null;
+  const workspaces = manifest?.workspaces ?? [{ name: legacyName, prefix: "", directories: [] }];
+  if (paths.length + workspaces.reduce((count, workspace) => count + workspace.directories.length, 0) > WORKSPACE_BACKUP_LIMITS.maxEntries) {
+    throw new Error("Too many backup files and directories.");
+  }
+  const result = workspaces.map((workspace) => ({
+    ...workspace,
+    files: []
+  }));
+  let total = metadata?.byteLength ?? 0;
+  for (const path of paths) {
+    if (manifest && path === WORKSPACE_BACKUP_MANIFEST) continue;
+    const index = manifest ? workspaces.findIndex((workspace) => path.startsWith(`${workspace.prefix}/`)) : 0;
+    if (index < 0) throw new Error(`Backup file is outside its workspace: ${path}`);
+    const relative = entryPath(manifest ? path.slice(workspaces[index].prefix.length + 1) : path);
+    const data = await container.readFile(path);
+    if (!data) throw new Error(`Backup file is missing: ${path}`);
+    total += data.byteLength;
+    if (data.byteLength > WORKSPACE_BACKUP_LIMITS.maxEntryUncompressedBytes || total > WORKSPACE_BACKUP_LIMITS.maxUncompressedBytes) {
+      throw new Error("Workspace backup exceeds the restore size limits.");
+    }
+    result[index].files.push({ path: relative, data });
+  }
+  for (const workspace of result) {
+    const files = new Set(workspace.files.map((file) => file.path));
+    for (const path of [...workspace.directories, ...files]) {
+      if (workspace.directories.includes(path) && files.has(path))
+        throw new Error(`Conflicting backup entry: ${path}`);
+      const parts = path.split("/");
+      while (parts.length > 1) {
+        parts.pop();
+        if (files.has(parseWorkspacePath(parts.join("/"))))
+          throw new Error(`Backup file is also a parent directory: ${path}`);
+      }
+    }
+  }
+  return result;
+}
+async function restoreWorkspaceBackup(workspace, provider) {
+  if ((await provider.readDirectory(parseWorkspacePath(""))).length)
+    throw new Error("Restore requires a new, empty workspace.");
+  for (const path of workspace.directories)
+    await provider.createDirectory(path, { createParents: true });
+  for (const file of workspace.files) {
+    await provider.writeFile(file.path, file.data, {
+      mode: "create",
+      createParents: true,
+      expectedVersion: null
+    });
+  }
+}
 
 // src/workspace/workspace-schema.ts
 var MAX_IDENTIFIER_CHARACTERS = 256;
@@ -214,6 +374,13 @@ function reconcileElectronWorkspaceDescriptors(local, hostWorkspaces, platform,
 }
 
 export {
+  WORKSPACE_BACKUP_MANIFEST,
+  WORKSPACE_BACKUP_LIMITS,
+  parseWorkspaceBackupManifest,
+  appendWorkspaceBackup,
+  finishWorkspaceBackup,
+  readWorkspaceBackup,
+  restoreWorkspaceBackup,
   parsePersistedWorkspaceList,
   DEFAULT_WORKSPACE_ID,
   registerTransientWorkspace,

package/dist/document/index.d.ts

@@ -1,5 +1,5 @@
-import { d as FileSystemProvider } from '../types-BvDnr3YU.js';
-import '../v2-BVnZZyd4.js';
+import { d as FileSystemProvider } from '../types-DLteNrK0.js';
+import '../v2-DwxWjFC0.js';
 import '../workspace-path-CWVrcuPL.js';
 
 /**

package/dist/document/index.js

@@ -9,10 +9,10 @@ import {
   DocumentSession,
   DocumentSessionConflictError,
   createFileSystemDocumentTarget
-} from "../chunk-IGB2VSRE.js";
+} from "../chunk-FIEMYP2N.js";
 import "../chunk-XAMILHQP.js";
-import "../chunk-M5ZNQGR5.js";
-import "../chunk-AYWKIZLD.js";
+import "../chunk-IYKGM3PV.js";
+import "../chunk-UTH3HYCZ.js";
 export {
   DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION,
   DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY,