@bendyline/docblocks 1.1.2 → 2.1.0

package/dist/chunk-COYQXQK3.js

@@ -0,0 +1,1071 @@
+import {
+  isFileSystemMoveStateError
+} from "./chunk-MNSZ7EZN.js";
+import {
+  decodeUtf8Text
+} from "./chunk-FA7UNOXK.js";
+import {
+  FsError,
+  parseWorkspacePath
+} from "./chunk-JS6XFWQK.js";
+import {
+  getFileSystemProviderV2
+} from "./chunk-EZKJZUNJ.js";
+
+// src/document/document-session.ts
+var DEFAULT_AUTO_SAVE_RETRY_DELAYS_MS = [1e3, 3e3, 1e4];
+var DocumentCommitConflictError = class extends Error {
+  constructor(message, externalContent, externalVersion = null) {
+    super(message);
+    this.name = "DocumentCommitConflictError";
+    this.externalContent = externalContent;
+    this.externalVersion = externalVersion;
+  }
+};
+var DocumentSessionConflictError = class extends Error {
+  constructor(conflict) {
+    super("The document changed outside DocBlocks while local edits were pending.");
+    this.name = "DocumentSessionConflictError";
+    this.conflict = conflict;
+  }
+};
+var DocumentSession = class {
+  constructor(options = {}) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.target = null;
+    this.content = "";
+    this.persistedContent = null;
+    this.revision = 0;
+    this.persistedRevision = 0;
+    this.savingRevision = null;
+    this.savingContent = null;
+    this.generation = 0;
+    this.externalSequence = -1;
+    this.lifecycle = "open";
+    this.frozen = false;
+    this.error = null;
+    this.conflict = null;
+    this.autoSaveTimer = null;
+    this.autoSaveRetryAttempt = 0;
+    this.drainPromise = null;
+    this.haltDrain = false;
+    this.operationTail = Promise.resolve();
+    this.subscribe = (listener) => {
+      this.listeners.add(listener);
+      return () => this.listeners.delete(listener);
+    };
+    this.getSnapshot = () => this.snapshot;
+    this.autoSaveDelayMs = Math.max(0, options.autoSaveDelayMs ?? 500);
+    this.autoSaveEnabled = options.autoSaveEnabled ?? true;
+    this.autoSaveRetryDelaysMs = normalizeRetryDelays(
+      options.autoSaveRetryDelaysMs ?? DEFAULT_AUTO_SAVE_RETRY_DELAYS_MS
+    );
+    this.recoveryJournal = options.recoveryJournal ?? null;
+    this.snapshot = this.createSnapshot();
+  }
+  /** Enable or disable automatic persistence without weakening explicit or lifecycle flushes. */
+  setAutoSaveEnabled(enabled) {
+    if (this.autoSaveEnabled === enabled) return;
+    this.autoSaveEnabled = enabled;
+    if (!enabled) {
+      this.clearAutoSaveTimer();
+      return;
+    }
+    if (this.target && this.lifecycle === "open" && !this.frozen && !this.conflict && this.persistedRevision < this.revision) {
+      this.scheduleAutoSave();
+    }
+  }
+  /**
+   * Record a complete local snapshot and schedule its persistence.
+   * Returns the assigned monotonic revision.
+   */
+  edit(content, scope) {
+    if (!this.target || this.lifecycle !== "open" || this.frozen) {
+      throw new Error("Cannot edit a document session that is not open.");
+    }
+    if (scope.targetKey !== this.target.key || scope.generation !== this.generation) {
+      throw new Error("Cannot apply an edit from an obsolete document instance.");
+    }
+    if (content === this.content) return this.revision;
+    this.content = content;
+    this.revision += 1;
+    this.error = null;
+    this.autoSaveRetryAttempt = 0;
+    if (this.conflict) {
+      this.conflict = {
+        ...this.conflict,
+        localContent: content,
+        localRevision: this.revision
+      };
+    }
+    this.writeRecoverySnapshot();
+    if (!this.conflict) this.scheduleAutoSave();
+    this.emit();
+    return this.revision;
+  }
+  /**
+   * Persist the revision current when flush() is called. A later edit may
+   * advance the session again, but commits remain strictly serialized.
+   */
+  async flush(reason = "manual") {
+    this.clearAutoSaveTimer();
+    if (!this.target) return this.snapshot;
+    if (this.conflict) throw new DocumentSessionConflictError(this.conflict);
+    const requiredRevision = this.revision;
+    while (this.target && this.persistedRevision < requiredRevision) {
+      if (this.conflict) throw new DocumentSessionConflictError(this.conflict);
+      if (this.haltDrain) {
+        throw new Error("Document persistence was cancelled before the requested revision saved.");
+      }
+      try {
+        await this.ensureDrain(reason);
+      } catch (error) {
+        if (this.conflict) throw new DocumentSessionConflictError(this.conflict);
+        throw error;
+      }
+    }
+    if (this.conflict) throw new DocumentSessionConflictError(this.conflict);
+    if (this.persistedRevision < requiredRevision) {
+      throw new Error("The document target closed before the requested revision saved.");
+    }
+    return this.snapshot;
+  }
+  /**
+   * Flush the old document, then replace it with a new clean baseline.
+   * UI state should change only after this promise resolves.
+   */
+  transitionTo(target, content) {
+    return this.enqueueOperation(
+      () => this.performTransition(async () => ({ target, content })).then((snapshot) => {
+        if (!snapshot) throw new Error("A fixed document transition cannot be cancelled.");
+        return snapshot;
+      })
+    );
+  }
+  /**
+   * Freeze and flush the current document before reading the next one. The
+   * loader may return null when a navigation request was superseded, leaving
+   * the current target active and clean.
+   */
+  transitionWithLoad(load) {
+    return this.enqueueOperation(() => this.performTransition(load));
+  }
+  /**
+   * Flush the current path, run the storage move, and only then swap the
+   * commit target. No edit can enter between those steps.
+   */
+  retarget(nextTarget, moveStorage) {
+    return this.enqueueOperation(async () => {
+      this.assertNotPreparingClose();
+      if (!this.target) throw new Error("Cannot retarget a session without a document.");
+      this.lifecycle = "transitioning";
+      this.frozen = true;
+      this.emit();
+      try {
+        this.haltDrain = false;
+        await this.flush("transition");
+        await moveStorage();
+        this.generation += 1;
+        this.externalSequence = -1;
+        this.target = nextTarget;
+        this.error = null;
+        this.conflict = null;
+        this.lifecycle = "open";
+        this.frozen = false;
+        this.emit();
+        return this.snapshot;
+      } catch (error) {
+        if (isFileSystemMoveStateError(error)) {
+          if (error.documentLocation === "destination") {
+            this.generation += 1;
+            this.externalSequence = -1;
+            this.target = nextTarget;
+          }
+          this.haltDrain = true;
+          this.error = error;
+          this.lifecycle = "open";
+          this.frozen = true;
+          this.emit();
+          throw error;
+        }
+        this.lifecycle = "open";
+        this.frozen = false;
+        this.emit();
+        throw error;
+      }
+    });
+  }
+  /**
+   * Cancel queued writes, wait for an already-running write, then delete.
+   * The deletion is therefore the final storage operation for this target.
+   */
+  delete(deleteStorage) {
+    return this.enqueueOperation(async () => {
+      this.assertNotPreparingClose();
+      this.lifecycle = "transitioning";
+      this.frozen = true;
+      this.haltDrain = true;
+      this.clearAutoSaveTimer();
+      this.emit();
+      await this.awaitActiveDrain();
+      try {
+        await deleteStorage();
+      } catch (error) {
+        this.haltDrain = false;
+        this.lifecycle = "open";
+        this.frozen = false;
+        if (this.target && this.persistedRevision < this.revision && !this.conflict) {
+          this.scheduleAutoSave();
+        }
+        this.emit();
+        throw error;
+      }
+      this.discardRecoverySnapshot();
+      this.detach();
+      return this.snapshot;
+    });
+  }
+  /**
+   * Discard queued changes and detach without mutating storage. This is used
+   * for explicitly abandoned sessions, never as an implicit effect cleanup.
+   */
+  cancel() {
+    return this.enqueueOperation(async () => {
+      this.lifecycle = "transitioning";
+      this.frozen = true;
+      this.haltDrain = true;
+      this.clearAutoSaveTimer();
+      this.emit();
+      await this.awaitActiveDrain();
+      this.discardRecoverySnapshot();
+      this.detach();
+      return this.snapshot;
+    });
+  }
+  /**
+   * Observe a filesystem/host change captured for targetKey. Clean sessions
+   * adopt it. Dirty or saving sessions preserve local text and enter conflict.
+   */
+  observeExternal(change) {
+    if (!this.target || change.targetKey !== this.target.key || this.lifecycle === "closed") {
+      return "ignored";
+    }
+    if (change.sequence !== void 0) {
+      if (!Number.isSafeInteger(change.sequence) || change.sequence <= this.externalSequence) {
+        return "ignored";
+      }
+      this.externalSequence = change.sequence;
+    }
+    if (this.conflict && change.content === this.content && this.savingRevision === null && this.lifecycle === "open") {
+      this.clearAutoSaveTimer();
+      this.autoSaveRetryAttempt = 0;
+      this.persistedRevision = this.revision;
+      this.persistedContent = this.content;
+      this.haltDrain = false;
+      this.error = null;
+      this.conflict = null;
+      this.discardRecoverySnapshot();
+      this.emit();
+      return "applied";
+    }
+    if (this.conflict) {
+      const externalVersion = change.version ?? null;
+      if (this.conflict.localContent === this.content && this.conflict.localRevision === this.revision && this.conflict.externalContent === change.content && this.conflict.externalVersion === externalVersion) {
+        return "ignored";
+      }
+      this.clearAutoSaveTimer();
+      this.haltDrain = true;
+      this.conflict = {
+        targetKey: change.targetKey,
+        localContent: this.content,
+        localRevision: this.revision,
+        externalContent: change.content,
+        externalVersion
+      };
+      this.error = null;
+      this.writeRecoverySnapshot();
+      this.emit();
+      return "conflict";
+    }
+    if (change.content === this.content || change.content === this.persistedContent || this.savingRevision !== null && change.content === this.savingContent) {
+      return "ignored";
+    }
+    const isClean = this.persistedRevision === this.revision && this.savingRevision === null && this.error === null && this.conflict === null;
+    if (isClean && change.content !== null) {
+      this.content = change.content;
+      this.revision += 1;
+      this.persistedRevision = this.revision;
+      this.persistedContent = change.content;
+      this.generation += 1;
+      this.discardRecoverySnapshot();
+      this.emit();
+      return "applied";
+    }
+    this.clearAutoSaveTimer();
+    this.haltDrain = true;
+    this.conflict = {
+      targetKey: change.targetKey,
+      localContent: this.content,
+      localRevision: this.revision,
+      externalContent: change.content,
+      externalVersion: change.version ?? null
+    };
+    this.error = null;
+    this.writeRecoverySnapshot();
+    this.emit();
+    return "conflict";
+  }
+  resolveConflict(strategy) {
+    return this.enqueueOperation(async () => {
+      if (!this.conflict) return this.snapshot;
+      this.clearAutoSaveTimer();
+      this.haltDrain = true;
+      await this.awaitActiveDrain();
+      const currentConflict = this.conflict;
+      if (!currentConflict) return this.snapshot;
+      if (strategy === "use-external") {
+        this.discardRecoverySnapshot();
+        this.generation += 1;
+        this.revision += 1;
+        this.conflict = null;
+        this.error = null;
+        this.haltDrain = false;
+        if (currentConflict.externalContent === null) {
+          this.target = null;
+          this.content = "";
+          this.persistedContent = null;
+          this.persistedRevision = this.revision;
+          this.lifecycle = "closed";
+          this.frozen = true;
+        } else {
+          this.content = currentConflict.externalContent;
+          this.persistedContent = currentConflict.externalContent;
+          this.persistedRevision = this.revision;
+          this.lifecycle = "open";
+          this.frozen = false;
+        }
+        this.emit();
+        return this.snapshot;
+      }
+      this.persistedContent = currentConflict.externalContent;
+      this.revision += 1;
+      this.conflict = null;
+      this.error = null;
+      this.haltDrain = false;
+      this.lifecycle = "open";
+      this.frozen = false;
+      this.writeRecoverySnapshot();
+      this.emit();
+      return this.flush("conflict");
+    });
+  }
+  /**
+   * Freeze edits and flush through the latest revision. A successful call
+   * remains frozen until cancelClose(); the owning host may now destroy it.
+   */
+  prepareClose() {
+    return this.enqueueOperation(async () => {
+      if (this.lifecycle === "closing") return this.snapshot;
+      this.lifecycle = "closing";
+      this.frozen = true;
+      this.haltDrain = false;
+      this.emit();
+      try {
+        await this.flush("close");
+        return this.snapshot;
+      } catch (error) {
+        this.lifecycle = "open";
+        this.frozen = false;
+        this.emit();
+        throw error;
+      }
+    });
+  }
+  /** Resume editing when a host cancels a prepared close. */
+  cancelClose() {
+    if (this.lifecycle !== "closing") return;
+    this.lifecycle = "open";
+    this.frozen = false;
+    this.haltDrain = false;
+    if (this.target && this.persistedRevision < this.revision && !this.conflict) {
+      this.scheduleAutoSave();
+    }
+    this.emit();
+  }
+  async performTransition(load) {
+    this.assertNotPreparingClose();
+    this.lifecycle = "transitioning";
+    this.frozen = true;
+    this.emit();
+    try {
+      this.haltDrain = false;
+      await this.flush("transition");
+      this.clearAutoSaveTimer();
+      const next = await load();
+      if (!next) {
+        this.lifecycle = "open";
+        this.frozen = false;
+        this.emit();
+        return null;
+      }
+      this.generation += 1;
+      this.externalSequence = -1;
+      this.target = next.target;
+      this.content = next.content;
+      this.revision += 1;
+      this.persistedRevision = this.revision;
+      this.persistedContent = next.target ? next.content : null;
+      this.savingRevision = null;
+      this.savingContent = null;
+      this.error = null;
+      this.conflict = null;
+      this.haltDrain = false;
+      this.lifecycle = "open";
+      this.frozen = false;
+      const recoveryState = this.restoreRecoverySnapshot();
+      if (recoveryState === "dirty") this.scheduleAutoSave();
+      this.emit();
+      return this.snapshot;
+    } catch (error) {
+      this.lifecycle = "open";
+      this.frozen = false;
+      this.emit();
+      throw error;
+    }
+  }
+  scheduleAutoSave(delayMs = this.autoSaveDelayMs) {
+    this.clearAutoSaveTimer();
+    if (!this.autoSaveEnabled) return;
+    this.autoSaveTimer = setTimeout(() => {
+      this.autoSaveTimer = null;
+      const target = this.target;
+      const generation = this.generation;
+      void this.flush("autosave").then(
+        () => {
+          this.autoSaveRetryAttempt = 0;
+        },
+        () => {
+          if (this.autoSaveTimer !== null || !target || target !== this.target || generation !== this.generation || this.lifecycle !== "open" || this.frozen || this.haltDrain || this.conflict || this.persistedRevision >= this.revision) {
+            return;
+          }
+          const retryDelay = this.autoSaveRetryDelaysMs[this.autoSaveRetryAttempt];
+          if (retryDelay === void 0) return;
+          this.autoSaveRetryAttempt += 1;
+          this.scheduleAutoSave(retryDelay);
+        }
+      );
+    }, delayMs);
+  }
+  clearAutoSaveTimer() {
+    if (this.autoSaveTimer === null) return;
+    clearTimeout(this.autoSaveTimer);
+    this.autoSaveTimer = null;
+  }
+  ensureDrain(reason) {
+    if (this.drainPromise) return this.drainPromise;
+    const running = this.drain(reason);
+    this.drainPromise = running;
+    const clear = () => {
+      if (this.drainPromise === running) this.drainPromise = null;
+    };
+    void running.then(clear, clear);
+    return running;
+  }
+  async drain(reason) {
+    while (this.target && !this.haltDrain && !this.conflict && this.persistedRevision < this.revision) {
+      const target = this.target;
+      const generation = this.generation;
+      const saveRevision = this.revision;
+      const saveContent = this.content;
+      const previousPersistedRevision = this.persistedRevision;
+      const previousPersistedContent = this.persistedContent;
+      this.savingRevision = saveRevision;
+      this.savingContent = saveContent;
+      this.error = null;
+      this.emit();
+      try {
+        await target.commit({
+          targetKey: target.key,
+          content: saveContent,
+          revision: saveRevision,
+          persistedRevision: previousPersistedRevision,
+          persistedContent: previousPersistedContent,
+          reason
+        });
+      } catch (error) {
+        this.savingRevision = null;
+        this.savingContent = null;
+        if (error instanceof DocumentCommitConflictError) {
+          this.haltDrain = true;
+          this.conflict = {
+            targetKey: target.key,
+            localContent: this.content,
+            localRevision: this.revision,
+            externalContent: error.externalContent,
+            externalVersion: error.externalVersion
+          };
+          this.error = null;
+        } else {
+          this.error = toError(error);
+        }
+        this.emit();
+        throw error;
+      }
+      if (generation !== this.generation || target !== this.target) return;
+      this.persistedRevision = Math.max(this.persistedRevision, saveRevision);
+      this.persistedContent = saveContent;
+      this.autoSaveRetryAttempt = 0;
+      this.savingRevision = null;
+      this.savingContent = null;
+      this.error = null;
+      const activeConflict = this.getSnapshot().conflict;
+      if (activeConflict?.externalContent === saveContent && this.content === saveContent) {
+        this.conflict = null;
+        this.haltDrain = false;
+      }
+      this.recoveryJournal?.acknowledge({
+        targetKey: target.key,
+        generation,
+        persistedRevision: this.persistedRevision
+      });
+      this.emit();
+    }
+  }
+  async awaitActiveDrain() {
+    const active = this.drainPromise;
+    if (!active) return;
+    try {
+      await active;
+    } catch {
+    }
+  }
+  /**
+   * Rehydrate a synchronous crash snapshot after the durable baseline has
+   * been read. A matching baseline is safe to resume as dirty; a changed
+   * baseline becomes an explicit conflict and is never auto-overwritten.
+   */
+  restoreRecoverySnapshot() {
+    if (!this.target || !this.recoveryJournal) return "none";
+    const recovered = this.recoveryJournal.lookup(this.target.key);
+    if (!recovered) return "none";
+    if (recovered.content === this.content) {
+      this.recoveryJournal.acknowledge({
+        targetKey: recovered.targetKey,
+        generation: recovered.generation,
+        persistedRevision: recovered.revision
+      });
+      return "none";
+    }
+    const externalContent = this.content;
+    this.generation = Math.max(this.generation, recovered.generation) + 1;
+    this.revision = Math.max(this.revision, recovered.revision) + 1;
+    this.content = recovered.content;
+    if (recovered.persistedContent === externalContent) {
+      this.writeRecoverySnapshot();
+      return "dirty";
+    }
+    this.persistedContent = recovered.persistedContent;
+    this.haltDrain = true;
+    this.conflict = {
+      targetKey: this.target.key,
+      localContent: recovered.content,
+      localRevision: this.revision,
+      externalContent,
+      externalVersion: null
+    };
+    this.writeRecoverySnapshot();
+    return "conflict";
+  }
+  writeRecoverySnapshot() {
+    if (!this.target || !this.recoveryJournal) return;
+    if (this.persistedRevision >= this.revision && !this.conflict) return;
+    this.recoveryJournal.write({
+      targetKey: this.target.key,
+      generation: this.generation,
+      revision: this.revision,
+      content: this.content,
+      persistedContent: this.persistedContent
+    });
+  }
+  discardRecoverySnapshot() {
+    if (!this.target) return;
+    this.recoveryJournal?.discard(this.target.key);
+  }
+  detach() {
+    this.clearAutoSaveTimer();
+    this.autoSaveRetryAttempt = 0;
+    this.generation += 1;
+    this.externalSequence = -1;
+    this.target = null;
+    this.persistedContent = null;
+    this.savingRevision = null;
+    this.savingContent = null;
+    this.error = null;
+    this.conflict = null;
+    this.haltDrain = false;
+    this.lifecycle = "closed";
+    this.frozen = true;
+    this.emit();
+  }
+  assertNotPreparingClose() {
+    if (this.lifecycle === "closing") {
+      throw new Error("The document is already prepared for close.");
+    }
+  }
+  enqueueOperation(operation) {
+    const run = this.operationTail.then(operation, operation);
+    this.operationTail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  createSnapshot() {
+    return Object.freeze({
+      targetKey: this.target?.key ?? null,
+      content: this.content,
+      revision: this.revision,
+      persistedRevision: this.persistedRevision,
+      persistedContent: this.persistedContent,
+      savingRevision: this.savingRevision,
+      generation: this.generation,
+      status: this.computeStatus(),
+      lifecycle: this.lifecycle,
+      frozen: this.frozen,
+      error: this.error,
+      conflict: this.conflict
+    });
+  }
+  computeStatus() {
+    if (this.lifecycle === "closed") return "closed";
+    if (!this.target) return "idle";
+    if (this.conflict) return "conflict";
+    if (this.error) return "error";
+    if (this.savingRevision !== null) return "saving";
+    return this.persistedRevision < this.revision ? "dirty" : "saved";
+  }
+  emit() {
+    this.snapshot = this.createSnapshot();
+    for (const listener of [...this.listeners]) listener();
+  }
+};
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function normalizeRetryDelays(delays) {
+  return delays.map((delay) => {
+    if (!Number.isFinite(delay) || delay < 0) {
+      throw new TypeError("Autosave retry delays must be finite, non-negative numbers.");
+    }
+    return Math.floor(delay);
+  });
+}
+
+// src/document/filesystem-target.ts
+function createFileSystemDocumentTarget(provider, path, options = {}) {
+  const verifyExternalChanges = options.verifyExternalChanges ?? true;
+  const canonicalPath = parseWorkspacePath(path);
+  const providerV2 = getFileSystemProviderV2(provider);
+  return {
+    key: provider.id + ":" + canonicalPath,
+    async commit(request) {
+      if (providerV2 && providerV2.capabilities.conditionalWrite !== "none") {
+        const current = await providerV2.readFile(canonicalPath);
+        const currentContent = current ? decodeUtf8Text(current.data, {
+          label: "The external document",
+          path: canonicalPath
+        }) : null;
+        if (currentContent !== request.persistedContent && currentContent !== request.content) {
+          throw new DocumentCommitConflictError(
+            "The document changed outside DocBlocks: " + path,
+            currentContent,
+            current?.entry.version ?? null
+          );
+        }
+        if (currentContent === request.content) {
+          options.onCommitted?.(request.content, request.revision);
+          return { version: current?.entry.version ?? null };
+        }
+        try {
+          const committed = await providerV2.writeFile(
+            canonicalPath,
+            new TextEncoder().encode(request.content),
+            {
+              mode: current ? "replace" : "create",
+              createParents: true,
+              expectedVersion: current?.entry.version ?? null
+            }
+          );
+          options.onCommitted?.(request.content, request.revision);
+          return { version: committed.version };
+        } catch (error) {
+          if (error instanceof FsError && (error.code === "conflict" || error.code === "already-exists" || error.code === "not-found")) {
+            const external = await providerV2.readFile(canonicalPath);
+            throw new DocumentCommitConflictError(
+              "The document changed outside DocBlocks: " + path,
+              external ? decodeUtf8Text(external.data, {
+                label: "The external document",
+                path: canonicalPath
+              }) : null,
+              external?.entry.version ?? null
+            );
+          }
+          throw error;
+        }
+      }
+      if (provider.commitFile) {
+        const result = await provider.commitFile(path, request.content, request.persistedContent);
+        if (result.status === "conflict") {
+          throw new DocumentCommitConflictError(
+            "The document changed outside DocBlocks: " + path,
+            result.content,
+            result.version
+          );
+        }
+        options.onCommitted?.(request.content, request.revision);
+        return { version: result.version };
+      }
+      if (verifyExternalChanges) {
+        const current = await provider.readFile(path);
+        if (current !== request.persistedContent && current !== request.content) {
+          const meta2 = await provider.stat(path).catch(() => null);
+          const version = meta2?.lastModified ?? null;
+          throw new DocumentCommitConflictError(
+            "The document changed outside DocBlocks: " + path,
+            current,
+            version
+          );
+        }
+      }
+      await provider.writeFile(path, request.content);
+      options.onCommitted?.(request.content, request.revision);
+      const meta = await provider.stat(path).catch(() => null);
+      return { version: meta?.lastModified ?? null };
+    }
+  };
+}
+
+// src/document/recovery-journal.ts
+var DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY = "docblocks:document-recovery:v1";
+var DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION = 1;
+var DEFAULT_MAX_ENTRIES = 20;
+var DEFAULT_MAX_STORAGE_BYTES = 2e6;
+var DEFAULT_MAX_RECORD_BYTES = 1e6;
+var DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+var MAX_TARGET_KEY_LENGTH = 4096;
+var DocumentRecoveryJournal = class {
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.storageKey = options.storageKey?.trim() || DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY;
+    this.maxEntries = positiveInteger(options.maxEntries, DEFAULT_MAX_ENTRIES);
+    this.maxStorageBytes = positiveInteger(options.maxStorageBytes, DEFAULT_MAX_STORAGE_BYTES);
+    this.maxRecordBytes = Math.min(
+      positiveInteger(options.maxRecordBytes, DEFAULT_MAX_RECORD_BYTES),
+      this.maxStorageBytes
+    );
+    this.maxAgeMs = nonNegativeFinite(options.maxAgeMs, DEFAULT_MAX_AGE_MS);
+    this.maxFutureSkewMs = nonNegativeFinite(options.maxFutureSkewMs, DEFAULT_MAX_FUTURE_SKEW_MS);
+    this.now = options.now ?? Date.now;
+  }
+  /**
+   * Synchronously persist the latest dirty snapshot for a target.
+   * Storage/quota failures are returned, never thrown into an editor onChange.
+   */
+  write(input) {
+    const timestamp = this.now();
+    if (!isValidWrite(input) || !Number.isFinite(timestamp) || timestamp < 0) {
+      return { status: "rejected", reason: "invalid-record", evicted: 0 };
+    }
+    if (!this.storage) {
+      return { status: "rejected", reason: "storage-unavailable", evicted: 0 };
+    }
+    if (estimatedBytes(input.content) > this.maxRecordBytes || input.persistedContent !== null && estimatedBytes(input.persistedContent) > this.maxRecordBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    const loaded = this.load(timestamp);
+    const existing = loaded.records.find((record) => record.targetKey === input.targetKey);
+    if (existing) {
+      const ordering = compareGenerationRevision(input, existing);
+      if (ordering < 0) return { status: "ignored-stale", evicted: 0 };
+      if (ordering === 0) {
+        if (existing.content === input.content && existing.persistedContent === input.persistedContent) {
+          return { status: "unchanged", evicted: 0 };
+        }
+        return { status: "rejected", reason: "invalid-record", evicted: 0 };
+      }
+    }
+    const candidate = {
+      targetKey: input.targetKey,
+      generation: input.generation,
+      revision: input.revision,
+      content: input.content,
+      persistedContent: input.persistedContent,
+      createdAt: existing?.createdAt ?? timestamp,
+      updatedAt: timestamp
+    };
+    if (estimatedBytes(JSON.stringify(candidate)) > this.maxRecordBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    if (estimatedBytes(serializeEnvelope([candidate])) > this.maxStorageBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    const next = loaded.records.filter((record) => record.targetKey !== input.targetKey);
+    next.push(candidate);
+    const persisted = this.persistBounded(next, input.targetKey);
+    if (!persisted.stored) {
+      return {
+        status: "rejected",
+        reason: persisted.reason ?? "quota-exceeded",
+        evicted: persisted.evicted
+      };
+    }
+    return { status: "stored", evicted: persisted.evicted };
+  }
+  /** Return the recoverable snapshot for one target, if present and valid. */
+  lookup(targetKey, generation) {
+    if (!isValidTargetKey(targetKey) || !isOptionalGeneration(generation)) return null;
+    const record = this.load(this.now()).records.find(
+      (candidate) => candidate.targetKey === targetKey && (generation === void 0 || candidate.generation === generation)
+    );
+    return record ? cloneRecord(record) : null;
+  }
+  /** List valid records, newest first. Optionally restrict to one target. */
+  list(targetKey) {
+    if (targetKey !== void 0 && !isValidTargetKey(targetKey)) return [];
+    return this.load(this.now()).records.filter((record) => targetKey === void 0 || record.targetKey === targetKey).sort(compareNewestFirst).map(cloneRecord);
+  }
+  /**
+   * Clear a record only when the same generation has durably acknowledged at
+   * least the journaled revision. A stale acknowledgement cannot erase a newer
+   * crash-recovery snapshot.
+   */
+  acknowledge(input) {
+    if (!isValidAcknowledgement(input) || !this.storage) return false;
+    const records = this.load(this.now()).records;
+    const record = records.find((candidate) => candidate.targetKey === input.targetKey);
+    if (!record || record.generation !== input.generation || record.revision > input.persistedRevision) {
+      return false;
+    }
+    return this.persistExact(records.filter((candidate) => candidate !== record));
+  }
+  /** Explicitly discard recovery data after a user or lifecycle decision. */
+  discard(targetKey, generation) {
+    if (!isValidTargetKey(targetKey) || !isOptionalGeneration(generation) || !this.storage) {
+      return false;
+    }
+    const records = this.load(this.now()).records;
+    const next = records.filter(
+      (record) => record.targetKey !== targetKey || generation !== void 0 && record.generation !== generation
+    );
+    if (next.length === records.length) return false;
+    return this.persistExact(next);
+  }
+  load(timestamp) {
+    if (!this.storage) return { records: [], needsRepair: false };
+    let raw;
+    try {
+      raw = this.storage.getItem(this.storageKey);
+    } catch {
+      return { records: [], needsRepair: false };
+    }
+    if (raw === null) return { records: [], needsRepair: false };
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      this.tryRemove();
+      return { records: [], needsRepair: true };
+    }
+    if (!isEnvelope(parsed)) {
+      this.tryRemove();
+      return { records: [], needsRepair: true };
+    }
+    const byTarget = /* @__PURE__ */ new Map();
+    let needsRepair = estimatedBytes(raw) > this.maxStorageBytes;
+    for (const candidate of parsed.records) {
+      if (!isValidStoredRecord(candidate, timestamp, this.maxAgeMs, this.maxFutureSkewMs)) {
+        needsRepair = true;
+        continue;
+      }
+      if (estimatedBytes(JSON.stringify(candidate)) > this.maxRecordBytes) {
+        needsRepair = true;
+        continue;
+      }
+      const current = byTarget.get(candidate.targetKey);
+      if (!current || compareStoredRecords(candidate, current) > 0) {
+        if (current) needsRepair = true;
+        byTarget.set(candidate.targetKey, cloneRecord(candidate));
+      } else {
+        needsRepair = true;
+      }
+    }
+    const records = [...byTarget.values()].sort(compareNewestFirst);
+    while (records.length > this.maxEntries) {
+      records.pop();
+      needsRepair = true;
+    }
+    while (records.length > 0 && estimatedBytes(serializeEnvelope(records)) > this.maxStorageBytes) {
+      records.pop();
+      needsRepair = true;
+    }
+    if (needsRepair) {
+      this.persistBounded(records);
+    }
+    return { records, needsRepair };
+  }
+  persistBounded(records, protectedTarget) {
+    if (!this.storage) {
+      return { stored: false, evicted: 0, reason: "storage-unavailable" };
+    }
+    const next = [...records].sort(compareNewestFirst);
+    let evicted = 0;
+    while (next.length > this.maxEntries) {
+      if (!evictOldest(next, protectedTarget)) break;
+      evicted += 1;
+    }
+    let serialized = serializeEnvelope(next);
+    while (estimatedBytes(serialized) > this.maxStorageBytes) {
+      if (!evictOldest(next, protectedTarget)) {
+        return { stored: false, evicted, reason: "quota-exceeded" };
+      }
+      evicted += 1;
+      serialized = serializeEnvelope(next);
+    }
+    for (; ; ) {
+      try {
+        this.storage.setItem(this.storageKey, serialized);
+        return { stored: true, evicted };
+      } catch {
+        if (!evictOldest(next, protectedTarget)) {
+          return { stored: false, evicted, reason: "quota-exceeded" };
+        }
+        evicted += 1;
+        serialized = serializeEnvelope(next);
+      }
+    }
+  }
+  persistExact(records) {
+    if (!this.storage) return false;
+    if (records.length === 0) {
+      try {
+        this.storage.removeItem(this.storageKey);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      this.storage.setItem(this.storageKey, serializeEnvelope(records));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  tryRemove() {
+    try {
+      this.storage?.removeItem(this.storageKey);
+    } catch {
+    }
+  }
+};
+function getDefaultDocumentRecoveryStorage() {
+  try {
+    const candidate = Reflect.get(globalThis, "localStorage");
+    if (!isStorage(candidate)) return null;
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+function serializeEnvelope(records) {
+  const envelope = {
+    schemaVersion: DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION,
+    records
+  };
+  return JSON.stringify(envelope);
+}
+function estimatedBytes(value) {
+  return value.length * 2;
+}
+function positiveInteger(value, fallback) {
+  return Number.isSafeInteger(value) && (value ?? 0) > 0 ? value : fallback;
+}
+function nonNegativeFinite(value, fallback) {
+  return Number.isFinite(value) && (value ?? -1) >= 0 ? value : fallback;
+}
+function isEnvelope(value) {
+  if (!isObject(value)) return false;
+  return value.schemaVersion === DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION && Array.isArray(value.records);
+}
+function isValidStoredRecord(value, timestamp, maxAgeMs, maxFutureSkewMs) {
+  if (!isObject(value)) return false;
+  if (!isValidTargetKey(value.targetKey) || !isNonNegativeSafeInteger(value.generation) || !isNonNegativeSafeInteger(value.revision) || typeof value.content !== "string" || value.persistedContent !== null && typeof value.persistedContent !== "string" || !isNonNegativeFiniteNumber(value.createdAt) || !isNonNegativeFiniteNumber(value.updatedAt) || value.createdAt > value.updatedAt) {
+    return false;
+  }
+  if (!Number.isFinite(timestamp) || timestamp < 0) return false;
+  if (value.updatedAt > timestamp + maxFutureSkewMs) return false;
+  return timestamp - value.updatedAt <= maxAgeMs;
+}
+function isValidWrite(value) {
+  return isValidTargetKey(value.targetKey) && isNonNegativeSafeInteger(value.generation) && isNonNegativeSafeInteger(value.revision) && typeof value.content === "string" && (value.persistedContent === null || typeof value.persistedContent === "string");
+}
+function isValidAcknowledgement(value) {
+  return isValidTargetKey(value.targetKey) && isNonNegativeSafeInteger(value.generation) && isNonNegativeSafeInteger(value.persistedRevision);
+}
+function isValidTargetKey(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_TARGET_KEY_LENGTH;
+}
+function isOptionalGeneration(value) {
+  return value === void 0 || isNonNegativeSafeInteger(value);
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isStorage(value) {
+  if (!isObject(value)) return false;
+  return typeof value.getItem === "function" && typeof value.setItem === "function" && typeof value.removeItem === "function";
+}
+function compareGenerationRevision(left, right) {
+  if (left.generation !== right.generation) return left.generation - right.generation;
+  return left.revision - right.revision;
+}
+function compareStoredRecords(left, right) {
+  return compareGenerationRevision(left, right) || left.updatedAt - right.updatedAt;
+}
+function compareNewestFirst(left, right) {
+  return right.updatedAt - left.updatedAt || right.revision - left.revision;
+}
+function cloneRecord(record) {
+  return { ...record };
+}
+function evictOldest(records, protectedTarget) {
+  let oldestIndex = -1;
+  for (let index = 0; index < records.length; index += 1) {
+    if (records[index].targetKey === protectedTarget) continue;
+    if (oldestIndex < 0 || compareNewestFirst(records[index], records[oldestIndex]) > 0) {
+      oldestIndex = index;
+    }
+  }
+  if (oldestIndex < 0) return false;
+  records.splice(oldestIndex, 1);
+  return true;
+}
+
+export {
+  DocumentCommitConflictError,
+  DocumentSessionConflictError,
+  DocumentSession,
+  createFileSystemDocumentTarget,
+  DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY,
+  DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION,
+  DocumentRecoveryJournal,
+  getDefaultDocumentRecoveryStorage
+};
+//# sourceMappingURL=chunk-COYQXQK3.js.map