Reference

OPFS glossary

Shared vocabulary for this workspace. Lessons stick to these meanings. Terms grow as you demonstrate understanding — this seed covers lessons 1–5.

Lesson 1 Lesson 2 Lesson 3 Lesson 4 Lesson 5 Root / handles sheet Sync access sheet Checklist Playbook Resources Mission

Origin Private File System (OPFS): An origin-scoped virtual filesystem endpoint: files and directories private to the site origin, not shown in the OS file explorer. Part of the File System API. Entry point: navigator.storage.getDirectory().
Origin-scoped: Storage isolated to a site origin (scheme + host + port). Other origins cannot read your OPFS data. Same isolation model as IndexedDB and Cache Storage.
User-visible file system: Real files/folders the user can see in Finder/Explorer. Reached via File System Access pickers (showOpenFilePicker, etc.) with permission prompts — not OPFS. In this workspace, “user-visible FS” always means that path.
File System Access API (pickers): APIs that open/save user-chosen files on the user-visible file system. Related handle types to OPFS, different job: user permission and real paths, not a private app sandbox.
FileSystemDirectoryHandle: Handle to a directory. The OPFS root is one of these. Use getFileHandle / getDirectoryHandle to create or open children.
FileSystemFileHandle: Handle to a file. On the main thread, typical path is createWritable() / getFile(). In a dedicated worker, can open a sync access handle for high-throughput byte I/O.
FileSystemSyncAccessHandle: Synchronous, in-place read/write/truncate/flush/close handle for an OPFS file. Opened with createSyncAccessHandle() (async open; sync methods). Dedicated workers + OPFS only — not the window main thread, not user-visible picker files. Fast path for Wasm/DB engines; not the default for ordinary text/blob I/O.
Exclusive lock (sync access): Default createSyncAccessHandle mode (readwrite) takes an exclusive lock on that OPFS file. Other exclusive sync handles or createWritable streams fail until close(). Modes read-only and readwrite-unsafe change sharing rules — design multi-tab deliberately.
Dedicated worker: A classic new Worker(…) script with its own global scope. Required home for FileSystemSyncAccessHandle. Distinct from shared workers and service workers for this API surface.
Client storage: Data kept in the browser (or device) for an origin — not the same as “source of truth on the server.” Includes memory, Web Storage, Cache API, OPFS, IndexedDB, cookies, etc.
Cache Storage API (Cache API): Stores Request/Response pairs for load/offline HTTP resources. Wrong default for arbitrary file trees or entity rows.
IndexedDB: Async structured client database (object stores, keys, indexes). Prefer for app entities, drafts, and offline queues — not as the default home for file-shaped byte pipelines (that’s OPFS).
Web Storage: localStorage / sessionStorage: synchronous string maps with small practical limits. Wrong tool for bulk files or structured records at scale.
Quota / eviction: Browser limits on how much an origin may store, and policies that may delete best-effort site data under pressure (or Safari’s interaction caps). OPFS counts toward origin storage with IndexedDB, Cache, etc. Writes can fail with QuotaExceededError.
Persistent storage: Origin storage marked so the browser will not auto-evict it under normal disk pressure. Request with navigator.storage.persist(); check with persisted(). Not immortality — users can still clear site data. Granting is permission/heuristic dependent by browser.
Best-effort storage: Default bucket for site data (including OPFS until persistence is granted): the browser may clear it under storage pressure without treating it as user-critical. Design re-hydrate paths.
createWritable (FileSystemWritableFileStream): Main-thread write path on a file handle: open a writable stream, write, then close to persist. Prefer this over sync access handles for ordinary async app code.
remove / removeEntry: Delete primitives: handle.remove() on the entry itself (optional recursive for directories), or parent.removeEntry(name) by child name.