The visible problem may look like one API or tuning value, but reliability is decided by state ownership, resource bounds, and recovery after failure. A handle can be stored in IndexedDB while permission later returns to prompt. Resume must query and request from a user gesture instead of promising permanent background access.
Browser capability depends on version, permission, visibility, and device policy. Use capability detection and an explained fallback instead of treating one development machine as the product contract.
Make the implementation decisions explicit
List non-negotiable invariants before selecting performance knobs. Tuning can roll out gradually; identity, permission, and terminal-state rules cannot drift at runtime.
- Bind handles to local tasks and devices without sending serialized details through signaling or analytics.
- After reopening, compare size, modification, and digest because the file behind a handle may change.
- Fall back to a normal picker after unsupported or denied permission while preserving received progress.
Handles improve reselection convenience without changing user control. Recheck permission and content identity on every recovery.
Failure paths that are easy to miss
Boundaries turn hidden assumptions into incidents. Weak networks, refresh, concurrency, and capacity need combined coverage because retries can hide each one in isolation.
- Startup calls requestPermission outside a user gesture and is rejected.
- A valid handle skips digest checks and resumes an overwritten source into an old task.
- The UI promises permanent access and makes later revocation inexplicable.
How to verify it before release
Write the expected state trace before injecting faults. At every phase, reconcile user-visible outcome, both protocol endpoints, persistent records, and resource counts to prove the loop.
- Resume one task after grant, denial, revocation, move, and content overwrite.
- Run identical integrity cases on the handle path and ordinary picker fallback.
- Inspect exports, logs, and sync records for handles, real paths, or permission details.
Completion is not one passing path. Every terminal state reconciles, automation stays below user intent, and every operational cost has an explicit ceiling.