What a hosted web app can actually do with local files

[stueydubs]

Question

What can a website served from an ordinary origin actually do with files on the user's own disk, and where are the hard limits?

Foundational for the runtime redraw recorded on the map: webtweak 1.0 is a website you visit, not a local Node server you run. Every open ticket that assumed a server now waits on the facts below. This ticket resolves facts, not decisions - the decisions that consume them are separate tickets.

Prefer primary sources and dated statements: the WHATWG File System Access spec, MDN, Chrome for Developers, caniuse, and the WebKit and Mozilla standards positions. Where a capability is Chromium-only, say so explicitly rather than describing it as "supported".

Resolve:

• Browser support. Which engines implement showDirectoryPicker, showOpenFilePicker, showSaveFilePicker and writable file streams. State the current Mozilla and WebKit standards positions and their dates. Whether Safari's partial implementation reaches real user directories or only the origin-private file system. Whether any of it works on mobile.
• Permission lifetime. Whether a granted directory handle survives a reload, a tab close, and a browser restart. What has to be stored, and where (IndexedDB handle persistence). Whether queryPermission / requestPermission can restore access without a fresh user gesture, and whether installing as a PWA changes the answer.
• What counts as a user gesture for opening the picker, and whether a page can trigger it repeatedly, steal focus, or leave one open. This is the fact underneath the folder-dialog half of the now-superseded #16.
• Change notification. Whether there is any way to observe changes to a granted directory, or whether polling is the only option. If polling, what a directory scan costs at the scale of a real site.
• Rendering local files. Whether a service worker can synthesise HTTP responses from bytes read through a directory handle, so a local page renders with its own relative CSS, fonts and images. What the alternatives are (blob URLs, srcdoc, URL rewriting) and what each breaks. Whether Range requests can be synthesised, since the current server supports them for media.
• Isolation options for rendering untrusted local HTML: sandboxed iframes and their flags, and whether any of them yields an origin genuinely distinct from the app's.
• Byte fidelity. Whether reading and writing through this API preserves bytes exactly, including for non-UTF-8 files. The "non-UTF-8 pages are served byte-for-byte" decision in CONTEXT.md depends on this.
• Whether the origin-private file system is relevant here or a red herring, given that the whole point is editing the user's real project folder.

Record the findings as a Markdown file under docs/research/ on a research/ branch, per the house pattern set by docs/research/css-parsing-options.md.

[stueydubs]

Interim findings - research agent stopped before it wrote up

The research agent was stopped by the operator part-way through. It had completed its measurement work but had not written docs/research/browser-local-files.md (the file on branch research/browser-local-files is a header and a PLACEHOLDER, uncommitted). These findings are recorded here so they are not lost, but they are the agent's own summary and have not been independently verified. Treat them as leads to re-confirm, not as settled facts. This ticket stays open.

Method it reported using: probe pages served over http://127.0.0.1 and driven through the DevTools protocol, on Linux x86_64 with Chrome 151.0.7922.71 stable, 2026-08-03. Findings it marked as measured are flagged below.

Rendering an untrusted page in isolation is not achievable in one origin. Measured, and reported as matching the WPT suite. A sandboxed iframe without allow-same-origin gets no service-worker interception at all - not its navigation, not one subresource. The agent watched the request reach the real network and 404. Adding allow-same-origin restores interception, but it then measured that frame reading the parent's DOM, reading its storage, and removing its own sandbox attribute. Reported as cross-engine, WPT-enforced and unchanged for eleven years, with an open feature request describing this exact use case that nobody has implemented.

The only combination it found giving both rendering and isolation is a genuinely separate origin running its own service worker, with bytes shipped over postMessage - because a FileSystemHandle throws DataCloneError when cloned across origins, so the handle itself cannot move. This bears directly on #20 and #21.

The non-service-worker rendering fallbacks are worse than expected. blob: and data: documents have opaque paths, so every relative and root-absolute reference fails at URL parse rather than as a 404 - no request is attempted at all. srcdoc plus <base href> fixes relative URLs but never root-absolute ones, and is only service-worker-controlled while unsandboxed.

Downloads accumulate rather than overwrite. Measured. Repeat saves of the same filename produce edits.webtweak (1).json, (2), and so on. This matters because the whole Firefox and Safari fallback under discussion was "set the browser to ask where to save, and point it at your project folder" - which fails if reconcile reads a fixed filename and each save writes a new one beside it. The agent flagged this as the decisive unknown before measuring it.

Two corrections to things asserted earlier in the same session:

• Chrome on Android does ship all three pickers as of Chrome 132. caniuse reports otherwise and is wrong. So the earlier claim that this architecture excludes mobile entirely is false for Chromium.
• The download-location workaround above does not work, per the measurement.

Unchanged and still decisive: showDirectoryPicker does not exist in Firefox or Safari, and both engines have formally refused it.

Not reached. The agent was waiting on a sub-agent covering the localhost companion pattern (a hosted site talking to a small local program) when it was stopped. It flagged that as the most important remaining question, since it is the only candidate route to full Firefox and Safari support, and noted early evidence it may be blocked in Safari - WebKit bug 171934, reported as still NEW after nine years. That question is unresolved and someone should pick it up.

[stueydubs]

Narrowed by a decision on the map

Settled 2026-08-03: Firefox and Safari are supported at reduced fidelity, never at parity, and nothing is installed on the user's machine. See the map's Settled-while-charting list.

Item 4 of this ticket is now moot. The localhost companion pattern - a hosted site talking to a small local program - was the only remaining candidate for full Firefox and Safari parity, and parity is no longer the goal. Do not spend research budget on it. The early finding that it may be blocked in Safari (WebKit bug 171934, reported still NEW after nine years) is recorded here in case the question ever returns.

Everything else on this ticket still stands and is still needed, in particular permission lifetime, what counts as a user gesture, byte fidelity, and whether a service worker can serve from a directory handle. Those now feed #21, #22 and #24 rather than an open architecture question.

One item is promoted out to its own ticket: whether a prompted download overwrites or accumulates is now #23, because it needs a human clicking through a native save dialog rather than a research pass. The two agents that looked at it disagreed, and the disagreement is load-bearing.

Whoever picks this up next: the previous agent's measurements are in the comment above and are unverified. Re-derive rather than inherit.