dsh-cait 1.0.4 → 1.1.3

package/lib/libraries.js

@@ -135,6 +135,61 @@ export const libraryMethods = {
     }
     throw new CatError('INVALID_LIBRARY_KIND', '库类型必须是 tm 或 glossary')
   }
+,
+  renameLibrary({ kind, id, name } = {}) {
+    const { idKey, list, notFoundCode } = this.libraryTarget(kind)
+    const library = list.find((item) => item[idKey] === String(id ?? '').trim())
+    if (!library) throw new CatError(notFoundCode, `库不存在: ${String(id ?? '')}`, 404)
+    library.name = cleanLibraryName(name, library.name)
+    library.updatedAt = now()
+    this.touch()
+    this.persist()
+    return { libraries: this.librariesView() }
+  }
+,
+  deleteLibrary({ kind, id } = {}) {
+    const isTm = String(kind ?? '').trim() === 'tm'
+    const { idKey, list, notFoundCode } = this.libraryTarget(kind)
+    const libraryId = String(id ?? '').trim()
+    const index = list.findIndex((item) => item[idKey] === libraryId)
+    if (index < 0) throw new CatError(notFoundCode, `库不存在: ${libraryId}`, 404)
+    if (list.length <= 1) {
+      throw new CatError(
+        isTm ? 'LAST_TM_LIBRARY' : 'LAST_GLOSSARY_LIBRARY',
+        '至少要保留一个库，无法删除最后一个。',
+        409,
+      )
+    }
+
+    list.splice(index, 1)
+    // Entries belong to the library; dropping it drops them with it.
+    if (isTm) {
+      this.tm = this.tm.filter((entry) => (entry.tmId || DEFAULT_TM_ID) !== libraryId)
+    } else {
+      this.glossary = this.glossary.filter((entry) => (entry.glossaryId || DEFAULT_GLOSSARY_ID) !== libraryId)
+    }
+
+    const idsKey = isTm ? 'tmIds' : 'glossaryIds'
+    const defaultKey = isTm ? 'defaultTmId' : 'defaultGlossaryId'
+    const remaining = this.mounts[idsKey].filter((item) => item !== libraryId)
+    this.mounts[idsKey] = remaining.length ? remaining : [list[0][idKey]]
+    if (this.mounts[defaultKey] === libraryId) this.mounts[defaultKey] = this.mounts[idsKey][0]
+
+    this.touch()
+    this.persist()
+    return { deleted: libraryId, mounts: this.mountsView(), libraries: this.librariesView() }
+  }
+,
+  libraryTarget(kind) {
+    const libraryKind = String(kind ?? '').trim()
+    if (libraryKind === 'tm') {
+      return { idKey: 'tmId', list: this.tmLibraries, notFoundCode: 'TM_NOT_FOUND' }
+    }
+    if (libraryKind === 'glossary') {
+      return { idKey: 'glossaryId', list: this.glossaryLibraries, notFoundCode: 'GLOSSARY_NOT_FOUND' }
+    }
+    throw new CatError('INVALID_LIBRARY_KIND', '库类型必须是 tm 或 glossary')
+  }
 ,
   setMounts({ tmIds, glossaryIds, defaultTmId, defaultGlossaryId } = {}) {
     if (tmIds !== undefined && !Array.isArray(tmIds)) {

package/lib/library-export.js

@@ -0,0 +1,75 @@
+/**
+ * Serialisers for the library page: a TM as TMX and a glossary as TBX, CSV
+ * or JSON. They are deliberately dependency-free and mirror what the
+ * importers already accept, so a CSV round-trip never loses notes.
+ */
+
+import { escapeXml } from './xml.js'
+
+const CSV_COLUMNS = ['source', 'target', 'note', 'sourceLang', 'caseSensitive']
+
+function csvCell(value) {
+  const text = String(value ?? '')
+  return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
+}
+
+export function glossaryToCsv(entries) {
+  const lines = [CSV_COLUMNS.join(',')]
+  for (const entry of entries) {
+    lines.push(
+      [
+        csvCell(entry.source),
+        csvCell(entry.target),
+        csvCell(entry.note || ''),
+        csvCell(entry.sourceLang || ''),
+        entry.caseSensitive ? 'true' : 'false',
+      ].join(','),
+    )
+  }
+  return `${lines.join('\n')}\n`
+}
+
+export function glossaryToJson(entries) {
+  return `${JSON.stringify(
+    entries.map((entry) => ({
+      source: entry.source,
+      target: entry.target,
+      note: entry.note || '',
+      sourceLang: entry.sourceLang || '',
+      caseSensitive: Boolean(entry.caseSensitive),
+    })),
+    null,
+    2,
+  )}\n`
+}
+
+/**
+ * TBX-Basic, minimal shape: one termEntry per glossary entry, a langSet per
+ * language with a single tig/term, and the note as a descrip. Not every TBX
+ * consumer likes the minimal header, but this is what the round-trip test
+ * and the requirements doc agreed on (export only, no TBX import).
+ */
+export function glossaryToTbx(entries, { sourceLang = 'en', targetLang = 'zh-CN' } = {}) {
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<tbx style="dca" type="TBX-Basic" xml:lang="${escapeXml(sourceLang)}" version="3">`,
+    '  <header>',
+    `    <file original="cait" sourceLang="${escapeXml(sourceLang)}" targetLang="${escapeXml(targetLang)}"/>`,
+    '  </header>',
+    '  <body>',
+  ]
+  for (const entry of entries) {
+    const entryLang = entry.sourceLang || sourceLang
+    lines.push(`    <termEntry id="${escapeXml(entry.id)}">`)
+    lines.push(`      <langSet xml:lang="${escapeXml(entryLang)}">`)
+    lines.push(`        <tig><term>${escapeXml(entry.source)}</term></tig>`)
+    lines.push('      </langSet>')
+    lines.push(`      <langSet xml:lang="${escapeXml(targetLang)}">`)
+    lines.push(`        <tig><term>${escapeXml(entry.target)}</term></tig>`)
+    lines.push('      </langSet>')
+    if (entry.note) lines.push(`      <descrip type="note">${escapeXml(entry.note)}</descrip>`)
+    lines.push('    </termEntry>')
+  }
+  lines.push('  </body>', '</tbx>', '')
+  return lines.join('\n')
+}

package/lib/library-view.js

@@ -0,0 +1,215 @@
+/**
+ * Library browsing and export. `lookupTM` answers "what matches this segment",
+ * which is a query, not a catalogue: it only looks at mounted libraries, scores
+ * fuzzily and caps at 30 rows. The library page needs the opposite shape —
+ * every entry of a chosen set of libraries, filtered by substring and paged.
+ * These methods are read-only, so `lib/api.js` must not list them in MUTATIONS.
+ */
+
+import { CatError } from './errors.js'
+import { DEFAULT_GLOSSARY_ID, DEFAULT_TM_ID, canonicalLanguage, clampInt } from './store-utils.js'
+import { normalizeText } from './similarity.js'
+import { buildTmxForEntries } from './tmx.js'
+import { glossaryToCsv, glossaryToJson, glossaryToTbx } from './library-export.js'
+
+export const PAGE_SIZE_OPTIONS = [20, 50, 100, 200]
+export const PAGE_SIZE_DEFAULT = 50
+
+const EXPORT_FORMATS = {
+  tm: ['tmx'],
+  glossary: ['tbx', 'csv', 'json'],
+}
+
+function dateStamp(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
+}
+
+function fileStem(name, fallback) {
+  const stem = String(name ?? '')
+    .trim()
+    .replace(/[\\/:*?"<>|]+/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return stem || fallback
+}
+
+function pageSizeOf(value) {
+  const size = Number(value)
+  if (!Number.isFinite(size) || size <= 0) return PAGE_SIZE_DEFAULT
+  // The UI only offers four sizes; snapping keeps the total page count honest
+  // if a stale localStorage value ever reaches the server.
+  return PAGE_SIZE_OPTIONS.reduce(
+    (best, option) => (Math.abs(option - size) < Math.abs(best - size) ? option : best),
+    PAGE_SIZE_OPTIONS[0],
+  )
+}
+
+function pageOf(page, pageSize, total) {
+  const size = pageSizeOf(pageSize)
+  const totalPages = Math.max(1, Math.ceil(total / size))
+  const current = clampInt(page ?? 1, 1, totalPages, 1)
+  return { page: current, pageSize: size, totalPages, offset: (current - 1) * size }
+}
+
+function matchesQuery(entry, query) {
+  if (!query) return true
+  const needle = normalizeText(query)
+  if (!needle) return true
+  return normalizeText(entry.source).includes(needle) || normalizeText(entry.target).includes(needle)
+}
+
+function languageFacet(entries) {
+  const source = new Set()
+  const target = new Set()
+  for (const entry of entries) {
+    if (entry.sourceLang) source.add(entry.sourceLang)
+    if (entry.targetLang) target.add(entry.targetLang)
+  }
+  return { source: [...source].sort(), target: [...target].sort() }
+}
+
+function wantedIds(kind, ids, store) {
+  const clean = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : []
+  if (!clean.length) {
+    return new Set(
+      kind === 'tm'
+        ? store.tmLibraries.map((library) => library.tmId)
+        : store.glossaryLibraries.map((library) => library.glossaryId),
+    )
+  }
+  const scoped = new Set()
+  for (const id of clean) {
+    scoped.add(kind === 'tm' ? store.requireTmLibrary(id) : store.requireGlossaryLibrary(id))
+  }
+  return scoped
+}
+
+export const libraryViewMethods = {
+  listTmEntries({ tmIds, query, page, pageSize, sourceLang, targetLang } = {}) {
+    const scoped = wantedIds('tm', tmIds, this)
+    const src = sourceLang ? canonicalLanguage(sourceLang) : ''
+    const tgt = targetLang ? canonicalLanguage(targetLang) : ''
+
+    const inScope = this.tm.filter((entry) => scoped.has(entry.tmId || DEFAULT_TM_ID))
+    const languages = languageFacet(inScope)
+    const filtered = inScope
+      .filter((entry) => !src || entry.sourceLang === src)
+      .filter((entry) => !tgt || entry.targetLang === tgt)
+      .filter((entry) => matchesQuery(entry, query))
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+
+    const paging = pageOf(page, pageSize, filtered.length)
+    return {
+      kind: 'tm',
+      scopeIds: [...scoped],
+      query: String(query ?? ''),
+      sourceLang: src,
+      targetLang: tgt,
+      total: filtered.length,
+      languages,
+      ...paging,
+      entries: filtered.slice(paging.offset, paging.offset + paging.pageSize).map((entry) => ({
+        id: entry.id,
+        tmId: entry.tmId || DEFAULT_TM_ID,
+        source: entry.source,
+        target: entry.target,
+        note: entry.note || '',
+        sourceLang: entry.sourceLang,
+        targetLang: entry.targetLang,
+        context: entry.context ?? null,
+        contextHash: entry.contextHash ?? null,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+      })),
+    }
+  }
+,
+  listGlossaryEntries({ glossaryIds, query, page, pageSize, sourceLang } = {}) {
+    const scoped = wantedIds('glossary', glossaryIds, this)
+    const src = sourceLang ? canonicalLanguage(sourceLang) : ''
+
+    const inScope = this.glossary.filter((entry) =>
+      scoped.has(entry.glossaryId || DEFAULT_GLOSSARY_ID),
+    )
+    const languages = languageFacet(inScope)
+    const filtered = inScope
+      .filter((entry) => !src || entry.sourceLang === src)
+      .filter((entry) => matchesQuery(entry, query))
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+
+    const paging = pageOf(page, pageSize, filtered.length)
+    return {
+      kind: 'glossary',
+      scopeIds: [...scoped],
+      query: String(query ?? ''),
+      sourceLang: src,
+      total: filtered.length,
+      languages,
+      ...paging,
+      entries: filtered.slice(paging.offset, paging.offset + paging.pageSize).map((entry) => ({
+        id: entry.id,
+        glossaryId: entry.glossaryId || DEFAULT_GLOSSARY_ID,
+        source: entry.source,
+        target: entry.target,
+        note: entry.note || '',
+        sourceLang: entry.sourceLang,
+        caseSensitive: Boolean(entry.caseSensitive),
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+      })),
+    }
+  }
+,
+  exportTM({ tmId, format = 'tmx' } = {}) {
+    const libraryId = this.requireTmLibrary(tmId)
+    const cleanFormat = String(format ?? 'tmx').trim().toLowerCase()
+    if (!EXPORT_FORMATS.tm.includes(cleanFormat)) {
+      throw new CatError('INVALID_EXPORT_FORMAT', `记忆库不支持导出为 ${cleanFormat || '(empty)'}。`)
+    }
+    const library = this.tmLibraries.find((item) => item.tmId === libraryId)
+    const entries = this.tm
+      .filter((entry) => (entry.tmId || DEFAULT_TM_ID) === libraryId)
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+    const sourceLang = entries[0]?.sourceLang || this.settings.sourceLang
+    const targetLang = entries[0]?.targetLang || this.settings.targetLang
+    return {
+      filename: `cait-tm-${fileStem(library?.name, libraryId)}-${dateStamp()}.${cleanFormat}`,
+      mime: 'application/xml; charset=utf-8',
+      format: cleanFormat,
+      count: entries.length,
+      content: buildTmxForEntries(entries, { sourceLang, targetLang }),
+    }
+  }
+,
+  exportGlossary({ glossaryId, format = 'tbx' } = {}) {
+    const libraryId = this.requireGlossaryLibrary(glossaryId)
+    const cleanFormat = String(format ?? 'tbx').trim().toLowerCase()
+    if (!EXPORT_FORMATS.glossary.includes(cleanFormat)) {
+      throw new CatError('INVALID_EXPORT_FORMAT', `术语库不支持导出为 ${cleanFormat || '(empty)'}。`)
+    }
+    const library = this.glossaryLibraries.find((item) => item.glossaryId === libraryId)
+    const entries = this.glossary
+      .filter((entry) => (entry.glossaryId || DEFAULT_GLOSSARY_ID) === libraryId)
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+    const sourceLang = entries[0]?.sourceLang || this.settings.sourceLang
+    const targetLang = this.settings.targetLang
+    const content = cleanFormat === 'csv'
+      ? glossaryToCsv(entries)
+      : cleanFormat === 'json'
+        ? glossaryToJson(entries)
+        : glossaryToTbx(entries, { sourceLang, targetLang })
+    const mime = cleanFormat === 'csv'
+      ? 'text/csv; charset=utf-8'
+      : cleanFormat === 'json'
+        ? 'application/json; charset=utf-8'
+        : 'application/xml; charset=utf-8'
+    return {
+      filename: `cait-glossary-${fileStem(library?.name, libraryId)}-${dateStamp()}.${cleanFormat}`,
+      mime,
+      format: cleanFormat,
+      count: entries.length,
+      content,
+    }
+  },
+}

package/lib/mt.js

@@ -52,17 +52,12 @@ async function discoverRoutes(llm, loader) {
   if (!Array.isArray(adapters)) adapters = []
 
   const configured = configuredProviderIds(loader)
-  const hasLoaderRoutes = adapters.some((adapter) => configured.has(String(adapter?.id ?? '')))
   const providers = []
   const seen = new Set()
 
   for (const adapter of adapters) {
     const id = String(adapter?.id ?? '').trim()
     if (!id || id === MOCK_PROVIDER || seen.has(id)) continue
-    // When the loader exposes provider configs, use it to avoid listing adapters
-    // that have no configured route. If loader discovery found nothing, trust the
-    // adapter catalog (some providers are registered outside loader entries).
-    if (hasLoaderRoutes && !configured.has(id)) continue
     seen.add(id)
 
     let models = []
@@ -73,17 +68,32 @@ async function discoverRoutes(llm, loader) {
         models = []
       }
     }
+    // Loader entries only tell us which providers already have a route
+    // configured; they do not define the catalog. Providers may be registered
+    // outside loader entries (the built-in DeepSeek adapter is one), so the
+    // loader must never decide visibility: filtering on it made every such
+    // adapter vanish as soon as a single custom provider was added.
     providers.push({
       id,
       name: String(adapter?.name ?? id).trim() || id,
       models,
+      configured: configured.has(id),
+      hasModels: models.length > 0,
     })
   }
 
+  // Configured routes first, otherwise keep the adapter catalog order stable.
+  providers.sort((a, b) => Number(b.configured) - Number(a.configured))
+
+  const usable = providers.filter((provider) => provider.hasModels)
   return {
     providers,
-    fallback: providers.length === 0,
-    message: providers.length ? '' : NO_ROUTE_MESSAGE,
+    fallback: usable.length === 0,
+    message: usable.length
+      ? ''
+      : providers.length
+        ? NO_MODEL_MESSAGE
+        : NO_ROUTE_MESSAGE,
   }
 }
 

package/lib/persistence.js

@@ -3,7 +3,8 @@ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from '
 import { join, resolve } from 'node:path'
 import { CatError } from './errors.js'
 import { normalizeText } from './similarity.js'
-import { documentFingerprint, DEFAULT_GLOSSARY_ID, DEFAULT_GLOSSARY_NAME, DEFAULT_SETTINGS, DEFAULT_TM_ID, DEFAULT_TM_NAME, MAX_SEGMENTS, MAX_STORE_BYTES, STORE_FILENAME, STORE_VERSION, clamp, clampInt, cleanFormatMeta, cleanName, cleanSegmentMeta, now, restoreLibraries, restoreMountIds, restoreSettings, restoredDate, restoredLang, restoredText } from './store-utils.js'
+import { contextHashOf, normalizeContext } from './context.js'
+import { documentFingerprint, DEFAULT_GLOSSARY_ID, DEFAULT_GLOSSARY_NAME, DEFAULT_SETTINGS, DEFAULT_TM_ID, DEFAULT_TM_NAME, MAX_SEGMENTS, MAX_STORE_BYTES, SEGMENT_ORIGINS, SEGMENT_STATUSES, STORE_FILENAME, STORE_VERSION, clamp, clampInt, cleanFormatMeta, cleanName, cleanSegmentMeta, normalizeSegmentState, now, restoreLibraries, restoreMountIds, restoreSettings, restoredDate, restoredLang, restoredText } from './store-utils.js'
 
 export const persistenceMethods = {
   load() {
@@ -58,7 +59,14 @@ export const persistenceMethods = {
     if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
       throw new Error('数据文件根节点不是对象')
     }
-    if (payload.version !== 1 && payload.version !== STORE_VERSION) {
+    // v1 and v2 predate the three-state model: their segments only carried
+    // pending/confirmed, so their target text maps onto `translated`.
+    if (
+      payload.version !== 1 &&
+      payload.version !== 2 &&
+      payload.version !== 3 &&
+      payload.version !== STORE_VERSION
+    ) {
       throw new Error(`不兼容的数据版本: ${String(payload.version ?? 'missing')}`)
     }
     if (!Array.isArray(payload.documents) || !Array.isArray(payload.tm) || !Array.isArray(payload.glossary)) {
@@ -82,21 +90,37 @@ export const persistenceMethods = {
         }
         const source = restoredText(rawSegment.source, '原文', { required: true })
         const target = restoredText(rawSegment.target ?? '', '译文')
-        const status = rawSegment.status === 'confirmed' && target ? 'confirmed' : 'pending'
+        const suggestion = restoredText(rawSegment.suggestion ?? '', '译文')
+        const confirmed = rawSegment.status === 'confirmed' && target
+        const origin = SEGMENT_ORIGINS.includes(rawSegment.origin)
+          ? rawSegment.origin
+          : target || suggestion
+            ? 'manual'
+            : null
         const meta = cleanSegmentMeta(rawSegment.meta)
-        return {
+        const segment = {
           id:
             typeof rawSegment.id === 'string' && rawSegment.id
               ? rawSegment.id
               : `s${index + 1}`,
           source,
           target,
-          status,
+          // normalizeSegmentState re-derives this from target/suggestion; the
+          // stored value is only a hint so a v3 file with a stale status still
+          // loads into a consistent model.
+          status: SEGMENT_STATUSES.includes(rawSegment.status) ? rawSegment.status : 'pending',
+          origin,
+          suggestion,
+          suggestionReason:
+            typeof rawSegment.suggestionReason === 'string'
+              ? rawSegment.suggestionReason.slice(0, 500)
+              : '',
           paragraph: Number.isInteger(rawSegment.paragraph) ? rawSegment.paragraph : index,
           ...(meta ? { meta } : {}),
-          confirmedAt: status === 'confirmed' ? restoredDate(rawSegment.confirmedAt) : null,
+          confirmedAt: confirmed ? restoredDate(rawSegment.confirmedAt) : null,
           updatedAt: restoredDate(rawSegment.updatedAt),
         }
+        return normalizeSegmentState(segment)
       })
 
       const doc = {
@@ -144,6 +168,20 @@ export const persistenceMethods = {
           name: cleanName(sourcePptx.name, 'source.pptx'),
         }
       }
+      const sourceEpub = rawDoc.sourceEpub
+      if (
+        sourceEpub &&
+        typeof sourceEpub === 'object' &&
+        sourceEpub.kind === 'file' &&
+        typeof sourceEpub.asset === 'string' &&
+        /^sources\/[A-Za-z0-9_.-]+\.epub$/.test(sourceEpub.asset)
+      ) {
+        doc.sourceEpub = {
+          kind: 'file',
+          asset: sourceEpub.asset,
+          name: cleanName(sourceEpub.name, 'source.epub'),
+        }
+      }
       if (docs.has(doc.id)) throw new Error(`文档 id 重复: ${doc.id}`)
       docs.set(doc.id, doc)
     }
@@ -157,9 +195,13 @@ export const persistenceMethods = {
       const sourceLang = restoredLang(rawEntry.sourceLang, 'en')
       const targetLang = restoredLang(rawEntry.targetLang, 'zh-CN')
       const key = normalizeText(source)
+      // Context is recomputed from its text on load: a stored hash can never be
+      // trusted to agree with the pair it was derived from.
+      const context = normalizeContext(rawEntry.context)
+      const contextHash = contextHashOf(context)
       const tmId =
         typeof rawEntry.tmId === 'string' && rawEntry.tmId ? rawEntry.tmId : DEFAULT_TM_ID
-      const dedupeKey = `${tmId}\u0000${sourceLang}\u0000${targetLang}\u0000${key}`
+      const dedupeKey = `${tmId}\u0000${sourceLang}\u0000${targetLang}\u0000${key}\u0000${contextHash ?? ''}`
       if (tmKeys.has(dedupeKey)) continue
       tmKeys.add(dedupeKey)
       tm.push({
@@ -170,6 +212,8 @@ export const persistenceMethods = {
         target,
         sourceLang,
         targetLang,
+        context,
+        contextHash,
         createdAt: restoredDate(rawEntry.createdAt),
         updatedAt: restoredDate(rawEntry.updatedAt),
       })
@@ -259,6 +303,12 @@ export const persistenceMethods = {
       targetLang: this.settings.targetLang,
       fuzzyThreshold: this.settings.fuzzyThreshold,
       tmLimit: this.settings.tmLimit,
+      uiLang: this.settings.uiLang,
+      preprocess: {
+        normalizeWhitespace: this.settings.preprocess.normalizeWhitespace,
+        stripInvisible: this.settings.preprocess.stripInvisible,
+        collapseBlankLines: this.settings.preprocess.collapseBlankLines,
+      },
       mt: {
         provider: this.settings.mt.provider,
         model: this.settings.mt.model,
@@ -266,9 +316,44 @@ export const persistenceMethods = {
       },
     }
   }
+,
+  /**
+   * Selecting a segment or typing a draft should survive a restart, but neither
+   * is worth a synchronous whole-file write per keystroke, so both schedule a
+   * trailing save instead.
+   */
+  schedulePersist(delay = 1200) {
+    if (!this.storageFile) return
+    if (this.saveTimer) clearTimeout(this.saveTimer)
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null
+      try {
+        this.persist()
+      } catch {
+        // persist() already logged and recorded the failure.
+      }
+    }, delay)
+    this.saveTimer.unref?.()
+  }
+,
+  flushPersist() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer)
+      this.saveTimer = null
+    }
+    try {
+      return this.persist()
+    } catch {
+      return { ok: false }
+    }
+  }
 ,
   persist({ strict = false } = {}) {
     if (!this.storageFile) return { ok: false, skipped: true }
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer)
+      this.saveTimer = null
+    }
 
     let temp = ''
     try {