Browser Storage Quota, Eviction, and Recovery

Working case

Inspector 47 captures 29 high-resolution scans while offline. The cached display copies and the unsent case notes compete for the same origin storage. The app keeps compact thumbnails, bounds the attachment queue, and warns before taking another large scan. If a write fails with a quota error, it retains the current form values in memory long enough to offer retry, smaller file selection, or an encrypted export chosen by the user. Once online, the app uploads and verifies the server copy before deleting an unsent local source. A fresh install with empty storage starts from server state instead of assuming a prior cache exists.

Implementation boundary

function nextStorageAction(queuedBytes, budgetBytes, newScanBytes) {
  return queuedBytes + newScanBytes > budgetBytes ? 'offer-smaller-file-or-export' : 'attempt-transaction';
}
console.log(nextStorageAction(47_000_000, 62_000_000, 29_000_000));
// Output: offer-smaller-file-or-export

Use storage estimates to guide a budget, not as a guaranteed reservation. Record byte counts for queued attachments and drafts, cap the queue, and evict regenerable thumbnails before unsent user data. Wrap each local write in an error path and wait for its transaction completion. Request persistent storage only if the product can explain why it needs it; handle denial. An export must include version and integrity metadata and be tested through restore. On startup, distinguish empty cache from an unsent queue and from corrupt local records. The server acknowledges uploaded bytes and record version before the client marks an item safe to remove.

Cost and boundaries

Large binary records consume disk, serialization time, and memory during readback. If n scans average s bytes, queued storage is O(n times s), excluding thumbnails and duplicate temporary buffers. Storage estimates can be padded for privacy and vary by browser, so leave headroom rather than filling to a reported limit. Clearing thumbnails costs extra downloads later; losing an unsent report costs far more. Track quota failures, queue bytes, age of oldest unsent item, restore success, and the fraction of users denied persistence without recording document contents.

Failure trace

The app labels an attachment saved immediately after calling a write method, then the transaction aborts for quota. The inspector closes the tab and loses the only copy. Reproduce an abort after the UI starts a save and verify the status remains unsaved until completion. Simulate origin eviction between sessions, private-browsing cleanup, a user clearing site data, and a partial export file. The startup flow must tell the difference between no local work and missing local work; a server sync check can recover acknowledged records, while an unacknowledged draft needs a separately tested export path.

Verification

Write status waits for transaction completion.
Quota failure preserves a user-visible recovery path.
Server acknowledgment precedes local source deletion.

Practice drill

Fill a test origin near its usable storage budget with 29 scans. Attempt one more write, catch the failure, discard only regenerable thumbnails, and retry the record transaction. Export an unsent report, clear site data, and restore it into a fresh profile. Compare restored record IDs and revision markers with the original queue. Then reconnect and verify the server acknowledgment before deleting local bytes.

Decision note

Local storage improves continuity; verified server state or a tested export protects against its loss.

Common Mistakes

Treating an estimated quota as reserved capacity.
Deleting unsent user data before regenerable cache entries.
Assuming a granted persistence request survives explicit clearing.

Connected practice

Build Project: offline case review across upgrades and review Web Development: offline and browser-key decisions quiz.