pwa(files): add permission-scoped local file handles, native-like open/save & installed-PWA file handling

[qnbs]

Parent

Part of #478 — PWA first-class excellence/hardening.

Product opportunity

A capable Chromium-class PWA can interact with user-selected local files/directories through the File System Access API without installing a privileged native package. Combined with installed-PWA file handling where supported, this can make WorldScript behave much more like a desktop writing tool while preserving the browser sandbox and explicit user grants.

This is a PWA-first advantage: zero-install + user-granted native-like file workflows.

Current state

The current PWA is primarily browser-storage-backed. Repository search found no dedicated showOpenFilePicker / showSaveFilePicker / FileSystemFileHandle integration or dedicated file-handler issue.

The manifest already contains several advanced installed-PWA entries (launch_handler, handle_links, share target, protocol handler), so this should be designed as part of a coherent installed-app contract rather than as a one-off picker button.

Design principle

File System Access must be an optional adapter, not a replacement for IndexedDB/OPFS authority across all browsers.

Shared project import/export semantics
        │
        ├── Browser baseline: upload/download
        ├── PWA enhanced: File System Access handles
        └── Native Qt: native filesystem adapter

Do not leak browser file handles into shared domain models.

Candidate user workflows

1. Open project/package from disk

• user chooses a supported WorldScript project/export/package;
• validate MIME/extension only as hints — parse and schema-validate content independently;
• show import/open semantics explicitly;
• never execute embedded content;
• retain a handle only with clear user benefit and browser permission semantics.

2. Save / Save As to a user-selected file

Provide direct repeated saves after a user grant where supported, with safe fallback to download elsewhere.

Important distinction:

• browser storage may remain authoritative for live autosave;
• external file can be a user-controlled durable mirror/export;
• or a future mode may deliberately make a selected file authoritative, but only after a separate design decision and conflict model.

Do not accidentally create two silent authorities.

3. User-selected backup folder

Where directory access is supported, allow an opt-in backup target:

• timestamped/versioned backups;
• explicit retention policy;
• no background claim that writes will occur if browser permission/lifecycle does not permit it;
• visible last successful external backup time;
• failure does not corrupt browser authority.

4. Attach/import research assets

Use file handles/pickers for images, documents, references, screenplay assets, or other supported imports without requiring an intermediate browser download/upload dance.

5. Installed-PWA file handling

Evaluate manifest file_handlers for supported WorldScript project/export extensions so opening a project file from the OS can launch the installed PWA.

Use launchQueue/consumer semantics where supported and validate every incoming file exactly as an untrusted import.

Permission model

• request access only in direct response to user intent;
• do not ask for broad directory access at startup;
• explain read vs read/write access;
• detect revoked/expired permissions;
• re-prompt only when the user invokes a workflow that needs it;
• provide “Disconnect local file/folder” controls;
• never imply browser grants are equivalent to unrestricted native filesystem access.

Conflict model

If a retained file changes externally:

• detect using available metadata/content fingerprinting when reopening/saving;
• never overwrite an externally modified file silently;
• offer compare/reload/save-copy/reconcile choices;
• preserve current browser-backed project before destructive import/reload.

Do not build a fragile polling filesystem watcher if the browser cannot provide reliable semantics.

Security

Treat all selected/opened files as untrusted.

• strict schema validation;
• bounded decompression/import sizes;
• zip-slip/path traversal protection for archives;
• safe MIME sniffing/content handling;
• no HTML/script execution from imported files;
• sanitize filenames shown in UI;
• do not persist more path/handle metadata than needed;
• never expose local paths in telemetry/logs.

Coordinate security truth with #382/#478.

Cross-browser fallback

File System Access support is not uniform. Feature-detect rather than UA-sniff.

Fallbacks:

• <input type=file> for open/import;
• Blob/download for save/export;
• browser storage for autosave;
• explicit capability UI rather than broken buttons.

The enhanced Chromium experience is allowed to exceed other browsers; basic writing/import/export must remain usable without it.

Tests

Cover:

• open valid/invalid project;
• permission granted/denied/revoked;
• save succeeds/fails/disk unavailable;
• external modification conflict;
• backup folder permission loss;
• malformed archive/oversized import;
• installed-PWA file launch;
• multiple files launched;
• fallback browser path;
• offline operation;
• encrypted project/export semantics where applicable.

Acceptance criteria

• File System Access is behind a typed PWA adapter/capability boundary.
• Open/import and Save As have enhanced handle-based paths where supported.
• Baseline upload/download remains available.
• No silent dual-authority model exists.
• External modification conflicts cannot be silently overwritten.
• Permissions are user-initiated, least-privilege and revocable.
• Installed-PWA file handling is evaluated/implemented for safe supported formats.
• Incoming files are treated as untrusted and schema/security validated.
• No local path/private metadata is leaked.
• Browser matrix and automated tests cover enhanced and fallback paths.

Non-goals

• unrestricted filesystem access;
• making File System Access mandatory for PWA use;
• pretending unsupported browsers provide identical behavior;
• replacing the future Qt filesystem authority with browser handles;
• background writes that browser lifecycle/permissions cannot honestly guarantee.

[qnbs]

Architecture refinement / import-export authority reconciliation — 2026-08-24

Implement File System Access as an optional PWA adapter over existing project import/export semantics, not as a new project storage authority.

Reuse requirements

Before adding new parsing/serialization paths, reuse:

• the existing project import thunk and schema validation;
• current export/package semantics;
• current project compatibility/migration rules;
• the shared external-launch normalization proposed in pwa(capture): make WorldScript an OS share target and offline research/idea inbox #484.

Selected files remain untrusted input exactly like uploads and native deep-link/file-association inputs.

Default authority model

IndexedDB/browser storage = live autosave/project authority
user-selected file        = explicit mirror/export/backup target

Retaining a FileSystemFileHandle must not silently create a second writer authority.

A future mode where the external file becomes authoritative requires a separate explicit design covering conflict detection, dirty-state transfer, recovery, external modification, permission loss, multi-tab ownership (#480), and compatibility with native/Qt project semantics.

Installed-PWA file handling

file_handlers/launchQueue should feed the same typed ExternalLaunchIntent boundary as share target, protocol handler, shortcuts, and Tauri deep links. Do not add a separate privileged file-launch parser.

Acceptance additions

• Existing import validation is the only project-parser authority used by enhanced file-open paths.
• Repeated direct-save behavior never bypasses live browser autosave authority accidentally.
• Authority mode is visible/testable, never inferred solely from a retained handle.
• Permission loss cannot strand the only recoverable copy.
• External modification reconciliation preserves browser-backed state before destructive reload/overwrite.
• pwa(capabilities): establish progressive-enhancement registry, browser support tiers & runtime diagnostics #489 owns capability reporting; this issue owns file-workflow admission/policy.