@banou/ponyfill 0.0.6 → 0.0.7

package/README.md

@@ -71,6 +71,59 @@ Cache is the thing that can be fetched again; a caller that never reclaims becau
 pressure is the failure this replaces. The ceiling still follows the platform DOWNWARD, and is never
 reported below the bytes already held, so `quota - usage` reaches zero and never goes negative.
 
+The ceiling is held per realm and in memory, and it **lets go when the origin's persistence changes**.
+A granted `persist()` moved the reported quota from 12 GB to 3.97 TB on Firefox (measured
+2026-09-01), so the figure learned before that is worse than useless afterwards. The release is keyed
+on the state rather than on the call, because `persist()` only exists on the main thread: a worker
+that latched the old ceiling and could never call it would go on deciding what to delete from a
+number that no longer exists.
+
+### `permissions`
+
+`query()` has four ways of behaving and only one of them is an answer: the engine may have no
+Permissions API, may reject a name it does not implement, may **throw synchronously** for one (which
+a `.catch` on the returned promise never sees), or may answer a real state.
+
+All three non-answers collapse to `'prompt'`. Not `'denied'`, because an engine that cannot be asked
+has not refused anything, and treating silence as refusal costs the person a control that might have
+worked.
+
+### `showOpenFilePicker`, `showDirectoryPicker`, `showSaveFilePicker`
+
+Measured 2026-09-03 across Chromium 149, Firefox 151 and WebKit 26:
+
+| | Chromium | Firefox | WebKit |
+| --- | --- | --- | --- |
+| the three pickers | present | **absent** | **absent** |
+| `FileSystemHandle` and friends as globals | present | present | **absent** |
+| `<input>.webkitdirectory` and its `cancel` event | yes | yes | yes |
+| an object holding its methods as own properties, cloned | `DataCloneError` | `DataCloneError` | `DataCloneError` |
+| the same object with its methods on a prototype | clones, silently | clones, silently | clones, silently |
+| `<input webkitdirectory>` file order, same tree | `a`, `sub/b` | `sub/b`, `a` | `sub/b`, `a` |
+
+**Reading always works, and always answers handles.** Where the platform has a picker it is used and
+its handles come back untouched. Where it does not, an `<input type="file">` is opened and what comes
+back is wrapped in the same shape, so a caller has one call and one return type instead of a
+`FileSystemFileHandle | File` union threaded through everything downstream.
+
+**Writing is refused rather than faked.** `showSaveFilePicker` has no fallback, `showDirectoryPicker`
+refuses `mode: 'readwrite'` where there is no native picker, and a wrapped handle's
+`createWritable()` throws. There is no way to write to a chosen location without the platform's
+picker.
+
+**Refusals happen before the gesture is spent**, and are named `NotAllowedError` so a caller can tell
+them from the `AbortError` the platform throws when the person cancels. A caller has one transient
+activation, and a picker that rejects at call time has already spent part of it.
+
+**A wrapped handle cannot be persisted, and says so loudly.** This is the one difference that cannot
+be absorbed, so what is picked is how it fails. A native handle survives `structuredClone` and comes
+back out of IndexedDB still usable; a wrapper around a `File` cannot, because a snapshot is not an
+entry on a disk. Left as an ordinary object it would clone *successfully* and come back with its
+prototype gone and every method with it, failing after a reload with nothing pointing at the pick. So
+every wrapped handle carries its methods as own properties, which makes the store throw
+`DataCloneError` at the moment of the mistake: one `.catch` where it matters instead of a capability
+probe at every call site.
+
 ## Adding to it
 
 If you hit something that behaves differently between engines, or differently from its own

package/build/file-system.cjs

@@ -1,9 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/file-system.ts
+var NO_SAVE_PICKER = "this browser has no file save picker";
+var NO_FRAMED_PICKER = "a cross origin frame cannot show a file save picker";
+var NO_DOCUMENT = "there is no document here to open a file picker from";
+var NO_WRITE = "this file was opened from a picker that cannot write, so there is nothing to write to";
+var NO_WRITE_FOLDER = "this browser cannot grant write access to a chosen folder";
+var refuse = (message) => new DOMException(message, "NotAllowedError");
 /**
 * Whether this document is framed by another origin.
 *
-* Chromium exposes the picker either way and refuses it at call time, so a property probe says
+* Chromium exposes the pickers either way and refuses them at call time, so a property probe says
 * nothing. A same origin ancestor answers `location.origin`; a cross origin one throws, and so does
 * an opaque origin, which is the case a sandboxed frame presents.
 */
@@ -18,11 +24,242 @@ var framedByAnotherOrigin = () => {
 		return true;
 	}
 };
+/**
+* The `accept` attribute for an `<input>`, from the picker's own `types`.
+*
+* Both halves of each entry go in. The attribute takes MIME types and extensions in one comma
+* separated list, and an engine that does not recognise one of them ignores that one rather than the
+* whole attribute, so listing both is strictly better than choosing. `*` patterns are dropped: they
+* are what `excludeAcceptAllOption: false` already means, and an `accept` of `*` filters nothing
+* while making the dialog claim it does.
+*/
+var acceptFrom = (types) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const type of types ?? []) for (const [mime, extensions] of Object.entries(type.accept ?? {})) {
+		if (mime && !mime.includes("*")) out.add(mime);
+		for (const extension of extensions) out.add(extension);
+	}
+	return [...out].join(",");
+};
+/**
+* One pick through a detached `<input type="file">`, resolving the files or rejecting like a cancel.
+*
+* The `cancel` event is what makes this a promise that always settles, and it is why this fallback is
+* worth having at all rather than being a hazard: measured present on all three engines above. An
+* engine without it would leave a picker that was dismissed pending forever, which is worse than not
+* offering one.
+*
+* NEEDS THE CALLER'S TRANSIENT ACTIVATION, exactly as the platform picker does. `click()` on a file
+* input opens nothing without a gesture, so this has to be reached synchronously from the handler,
+* and an `await` before it loses that. The same rule the native picker has, for the same reason.
+*
+* The input is attached and removed rather than left detached: a detached input's `click()` is
+* ignored by some engines, and leaving it in the document would leave one element per pick behind.
+*/
+var pickThroughInput = (setup) => {
+	const document = globalThis.document;
+	if (!document?.body) return Promise.reject(refuse(NO_DOCUMENT));
+	return new Promise((resolve, reject) => {
+		const input = document.createElement("input");
+		input.type = "file";
+		input.style.display = "none";
+		input.setAttribute("aria-hidden", "true");
+		setup(input);
+		const settle = (finish) => {
+			input.remove();
+			finish();
+		};
+		input.addEventListener("change", () => settle(() => resolve([...input.files ?? []])), { once: true });
+		input.addEventListener("cancel", () => settle(() => reject(new DOMException("the file picker was closed", "AbortError"))), { once: true });
+		document.body.append(input);
+		input.click();
+	});
+};
+var handles = /* @__PURE__ */ new WeakMap();
+/**
+* Entries in a fixed order, which the platform does not promise and the engines do not agree on.
+*
+* Measured above: the same tree comes out of `<input webkitdirectory>` in one order on Chromium and
+* the opposite on Firefox and WebKit. Sorted by code unit rather than `localeCompare`, because a
+* locale sensitive sort is one more thing that differs between two machines running the same code.
+*/
+var ordered = (children) => [...children].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+var fileHandleFor = (node) => {
+	return {
+		kind: "file",
+		name: node.name,
+		/**
+		* The same `File` every time, where the platform hands back a fresh one.
+		*
+		* A `File` from an input is a snapshot taken when it was picked. It cannot be re-read from disk,
+		* so `lastModified` never moves and a staleness check across it can never fire. What it does do
+		* is throw on READ once the file underneath has changed, so a pass over the bytes still refuses
+		* to produce a mixture of two versions; it just reports it as a failed read rather than a
+		* changed file.
+		*/
+		getFile: async () => node.file,
+		createWritable: async () => {
+			throw refuse(NO_WRITE);
+		},
+		isSameEntry: async (other) => other === handles.get(node)
+	};
+};
+var directoryHandleFor = (node) => {
+	const child = (name) => node.children.get(name);
+	const entries = async function* () {
+		for (const [name, entry] of ordered(node.children)) yield [name, handleFor(entry)];
+	};
+	return {
+		kind: "directory",
+		name: node.name,
+		entries,
+		keys: async function* () {
+			for (const [name] of ordered(node.children)) yield name;
+		},
+		values: async function* () {
+			for (const [, entry] of ordered(node.children)) yield handleFor(entry);
+		},
+		[Symbol.asyncIterator]: entries,
+		getFileHandle: async (name, options) => {
+			if (options?.create) throw refuse(NO_WRITE);
+			const found = child(name);
+			if (!found) throw new DOMException(`there is no ${name} here`, "NotFoundError");
+			if (found.kind !== "file") throw new DOMException(`${name} is a directory`, "TypeMismatchError");
+			return handleFor(found);
+		},
+		getDirectoryHandle: async (name, options) => {
+			if (options?.create) throw refuse(NO_WRITE);
+			const found = child(name);
+			if (!found) throw new DOMException(`there is no ${name} here`, "NotFoundError");
+			if (found.kind !== "directory") throw new DOMException(`${name} is a file`, "TypeMismatchError");
+			return handleFor(found);
+		},
+		removeEntry: async () => {
+			throw refuse(NO_WRITE);
+		},
+		/** The path from here down to a handle in this tree, or null where it is not in it. */
+		resolve: async (descendant) => {
+			const search = (from, path) => {
+				for (const [name, entry] of ordered(from.children)) {
+					if (handles.get(entry) === descendant) return [...path, name];
+					if (entry.kind === "directory") {
+						const deeper = search(entry, [...path, name]);
+						if (deeper) return deeper;
+					}
+				}
+				return null;
+			};
+			return handles.get(node) === descendant ? [] : search(node, []);
+		},
+		isSameEntry: async (other) => other === handles.get(node)
+	};
+};
+var handleFor = (node) => {
+	const made = handles.get(node);
+	if (made) return made;
+	const fresh = node.kind === "file" ? fileHandleFor(node) : directoryHandleFor(node);
+	handles.set(node, fresh);
+	return fresh;
+};
+/**
+* The picked folder, rebuilt from the flat list an input hands over.
+*
+* `webkitRelativePath` is the whole tree already flattened: `Pack/Subs/E01.ass` for a folder called
+* `Pack`. The first segment is the folder's own name, so it becomes the root's name and is dropped
+* from every path under it, which is what makes this the same shape `showDirectoryPicker` returns.
+*
+* AN EMPTY FOLDER LOSES ITS NAME, and nothing can be done about that. The name is only ever learned
+* from a file's path, so a folder with nothing in it comes back named `''`. It is a real pick rather
+* than a cancel, since `change` fired, and reporting it as an empty directory is the closest true
+* answer available.
+*
+* A name used twice, once as a file and once as a folder, resolves to the folder, because a path
+* continuing through it proves it is one. Two files with the same path keep the last, which is what
+* a map does and what re-picking the same tree would do anyway.
+*/
+var treeFrom = (files) => {
+	const root = {
+		kind: "directory",
+		name: "",
+		children: /* @__PURE__ */ new Map()
+	};
+	for (const file of files) {
+		const segments = (file.webkitRelativePath || file.name).split("/").filter(Boolean);
+		if (!segments.length) continue;
+		const rooted = Boolean(file.webkitRelativePath) && segments.length > 1;
+		if (rooted && !root.name) root.name = segments[0];
+		const path = rooted ? segments.slice(1) : segments;
+		let level = root.children;
+		for (const name of path.slice(0, -1)) {
+			const existing = level.get(name);
+			const directory = existing?.kind === "directory" ? existing : {
+				kind: "directory",
+				name,
+				children: /* @__PURE__ */ new Map()
+			};
+			if (existing !== directory) level.set(name, directory);
+			level = directory.children;
+		}
+		const leaf = path[path.length - 1];
+		level.set(leaf, {
+			kind: "file",
+			name: leaf,
+			file
+		});
+	}
+	return root;
+};
+/**
+* Same name and signature, refusing before the gesture is spent and never faking a save.
+*
+* The one picker with no fallback. Writing to a location somebody chose needs the platform's picker,
+* and what an app does instead is a product decision rather than a shim: see the header.
+*/
 var showSaveFilePicker = async (options) => {
 	const picker = globalThis.showSaveFilePicker;
-	if (!picker) throw new DOMException("this browser has no file save picker", "NotAllowedError");
-	if (framedByAnotherOrigin()) throw new DOMException("a cross origin frame cannot show a file save picker", "NotAllowedError");
+	if (!picker) throw refuse(NO_SAVE_PICKER);
+	if (framedByAnotherOrigin()) throw refuse(NO_FRAMED_PICKER);
 	return picker(options);
 };
+/**
+* Same name and signature, answering file handles on every engine.
+*
+* The native picker is preferred wherever it can actually be shown, and its handles come back
+* UNTOUCHED: they are structured cloneable, they can be re-granted after a reload, and wrapping them
+* would take exactly that away. A cross origin frame is skipped rather than tried, since the platform
+* refuses there and refusing costs part of the click the fallback still needs.
+*/
+var showOpenFilePicker = async (options = {}) => {
+	const picker = globalThis.showOpenFilePicker;
+	if (picker && !framedByAnotherOrigin()) return picker(options);
+	const accept = acceptFrom(options.types);
+	return (await pickThroughInput((input) => {
+		input.multiple = options.multiple === true;
+		if (accept) input.accept = accept;
+	})).map((file) => handleFor({
+		kind: "file",
+		name: file.name,
+		file
+	}));
+};
+/**
+* Same name and signature, answering a directory handle wherever reading one is possible.
+*
+* `mode: 'readwrite'` is refused where there is no native picker, and that refusal is the honest
+* answer rather than a gap: an `<input>` hands over copies of bytes and there is no route from one
+* back to the folder it came from. Refusing at the ask beats handing back a handle whose every write
+* fails later.
+*/
+var showDirectoryPicker = async (options = {}) => {
+	const picker = globalThis.showDirectoryPicker;
+	if (picker && !framedByAnotherOrigin()) return picker(options);
+	if (options.mode === "readwrite") throw refuse(NO_WRITE_FOLDER);
+	return handleFor(treeFrom(await pickThroughInput((input) => {
+		input.webkitdirectory = true;
+		input.multiple = true;
+	})));
+};
 //#endregion
+exports.showDirectoryPicker = showDirectoryPicker;
+exports.showOpenFilePicker = showOpenFilePicker;
 exports.showSaveFilePicker = showSaveFilePicker;

package/build/file-system.d.ts

@@ -1,46 +1,129 @@
 /**
- * The File System Access pickers, with the same names and one behaviour picked.
+ * The File System Access pickers, with the same names and one behaviour picked for each.
+ *
+ * ## What was measured, on what, and when
+ *
+ * 2026-09-03, one machine, three engines driven headless through Playwright, same probe in each:
+ *
+ * | | Chromium 149 | Firefox 151 | WebKit 26 |
+ * | --- | --- | --- | --- |
+ * | `showOpenFilePicker` / `showDirectoryPicker` / `showSaveFilePicker` | all present | all absent | all absent |
+ * | `FileSystemHandle` and friends as globals | present | present | ABSENT |
+ * | `queryPermission` on a native handle | function | undefined | no handles to ask |
+ * | `<input>.webkitdirectory` | yes | yes | yes |
+ * | the input's `cancel` event | yes | yes | yes |
+ * | an object holding its methods as OWN properties, cloned | DataCloneError | DataCloneError | DataCloneError |
+ * | the same object with its methods on a PROTOTYPE, cloned | clones, silently | clones, silently | clones, silently |
+ * | `<input webkitdirectory>` file order, same tree | `a.bin`, `sub/b.bin` | `sub/b.bin`, `a.bin` | `sub/b.bin`, `a.bin` |
+ *
+ * Four of those rows decide something below, and each is noted where it does.
  *
  * ## The divergence
  *
- * `showSaveFilePicker` exists on the window in Chromium whether or not it can actually be used, and
- * refuses at CALL time in two cases that a property probe cannot see:
+ * Two engines of three have NO picker at all, so an app that wants files from a person carries a
+ * second route for them: an `<input type="file">`, a `File` where the others have a handle, and a
+ * union type threaded through everything downstream. That union is the cost, and it is paid in every
+ * file the bytes pass through rather than at the boundary where the difference actually is.
+ *
+ * `showSaveFilePicker` diverges a second way, which is why it is the one entry here with no
+ * fallback. Chromium exposes it whether or not it can be used and refuses at CALL time in two cases a
+ * property probe cannot see: a cross origin ancestor frame ("Cross origin sub frames aren't allowed
+ * to show a file picker") and no transient activation.
+ *
+ * ## The picks
  *
- *  - a cross origin ancestor frame, which fails with "Cross origin sub frames aren't allowed to show
- *    a file picker"
- *  - no transient activation, which fails with "Must be handling a user gesture to show a file picker"
+ * READING ALWAYS WORKS, and always answers handles. `showOpenFilePicker` and `showDirectoryPicker`
+ * open the platform's picker where there is one and hand back its handles untouched; where there is
+ * none they open an `<input type="file">` and wrap what comes back in the same shape. One call, one
+ * return type, no branch in the caller.
  *
- * Firefox does not expose it at all, so `'showSaveFilePicker' in window` answers a different question
- * on each engine: on one it means "might work", on the other "will never work".
+ * WRITING IS REFUSED RATHER THAN FAKED. `showSaveFilePicker` has no fallback, `showDirectoryPicker`
+ * refuses `mode: 'readwrite'` where it has no native picker, and a wrapped handle's
+ * `createWritable()` throws. There is no way to write to a chosen location without the platform's
+ * picker, and a download that appeared in someone's downloads folder instead would be a different
+ * thing wearing the same name.
  *
- * ## The pick
+ * REFUSALS HAPPEN BEFORE THE GESTURE IS SPENT, and are named so a caller can tell them from a
+ * cancel. A caller with a fallback chain has one transient activation, and a picker that rejects at
+ * call time has already consumed part of it, so the fallback reached for next can fail too.
+ * `NotAllowedError` for every refusal and never `AbortError`, because `AbortError` is what the
+ * platform throws when the PERSON cancels: a caller that cannot tell those apart reports a failure
+ * for something somebody chose to do.
  *
- * REJECT BEFORE THE ACTIVATION IS SPENT, with a rejection a caller can tell apart from a cancel.
+ * A WRAPPED HANDLE CANNOT BE PERSISTED, AND SAYS SO LOUDLY. This is the one difference that cannot be
+ * absorbed, so what is picked is how it FAILS. A native handle survives `structuredClone` and comes
+ * back out of IndexedDB still usable, which is the whole reason handles are worth having; a wrapper
+ * around a `File` cannot, because the thing it refers to is a snapshot rather than an entry on a
+ * disk. Left as an ordinary object it would clone SUCCESSFULLY and come back with its prototype gone
+ * and every method with it, so the app would store it, reload, and fail somewhere else entirely with
+ * nothing pointing back here. Measured on all three engines above, both halves of that.
  *
- * That ordering is the whole of it. A caller with a fallback chain has one transient activation to
- * spend, and a picker that rejects at call time has already consumed part of it, so the fallback the
- * caller reaches for next can fail too. Rejecting before the call keeps the gesture intact.
+ * So every wrapped handle carries its methods as OWN properties, which makes `structuredClone` and
+ * `IDBObjectStore.put` throw `DataCloneError` at the moment of the mistake. `await set(key, handle)`
+ * rejecting where the browser cannot remember it is the honest shape, and it is one `.catch` at the
+ * one place that cares rather than a capability probe at every call site.
  *
- * `NotAllowedError` for both refusals rather than `AbortError`, because `AbortError` is what the
- * platform throws when the PERSON cancels, and a caller that cannot tell those apart shows an error
- * for something the person chose to do. Ripple's `isSaveCancelled` matches on `AbortError`, so this
- * distinction is load bearing rather than tidy.
+ * WHAT IS NOT ABSORBED, deliberately:
  *
- * WHAT IS NOT ABSORBED, deliberately. The fallback chain itself stays with the caller: an anchor
- * download, a service worker sink, or holding bytes in memory are not platform names and choosing
- * between them is a product decision about what a page does when it cannot save. A ponyfill that
- * silently downloaded something instead of opening a picker would be lying about which API it is.
+ *  - the fallback chain for saving. An anchor download, a service worker sink, or holding bytes in
+ *    memory are not platform names, and choosing between them is a product decision about what a page
+ *    does when it cannot save.
+ *  - `queryPermission` and `requestPermission` on a handle. They are Chromium's alone, absent from
+ *    Firefox even on its own native handles, and they are methods on an object the caller already
+ *    holds rather than a name this package could export without inventing one.
+ *  - re-opening. Nothing here makes a snapshot durable. An app that needs the bytes after a reload
+ *    has to copy them somewhere it owns, which spends the origin's quota and is therefore its
+ *    decision to make rather than this package's to make silently.
  */
+type FilePickerAcceptType = {
+    description?: string;
+    accept: Record<string, string[]>;
+};
 type SaveFilePickerOptions = {
     suggestedName?: string;
-    types?: {
-        description?: string;
-        accept: Record<string, string[]>;
-    }[];
+    types?: FilePickerAcceptType[];
+    excludeAcceptAllOption?: boolean;
+    id?: string;
+    startIn?: unknown;
+};
+type OpenFilePickerOptions = {
+    multiple?: boolean;
+    types?: FilePickerAcceptType[];
     excludeAcceptAllOption?: boolean;
     id?: string;
     startIn?: unknown;
 };
+type DirectoryPickerOptions = {
+    id?: string;
+    mode?: 'read' | 'readwrite';
+    startIn?: unknown;
+};
 type SaveFilePicker = (options?: SaveFilePickerOptions) => Promise<FileSystemFileHandle>;
+type OpenFilePicker = (options?: OpenFilePickerOptions) => Promise<FileSystemFileHandle[]>;
+type DirectoryPicker = (options?: DirectoryPickerOptions) => Promise<FileSystemDirectoryHandle>;
+/**
+ * Same name and signature, refusing before the gesture is spent and never faking a save.
+ *
+ * The one picker with no fallback. Writing to a location somebody chose needs the platform's picker,
+ * and what an app does instead is a product decision rather than a shim: see the header.
+ */
 export declare const showSaveFilePicker: SaveFilePicker;
+/**
+ * Same name and signature, answering file handles on every engine.
+ *
+ * The native picker is preferred wherever it can actually be shown, and its handles come back
+ * UNTOUCHED: they are structured cloneable, they can be re-granted after a reload, and wrapping them
+ * would take exactly that away. A cross origin frame is skipped rather than tried, since the platform
+ * refuses there and refusing costs part of the click the fallback still needs.
+ */
+export declare const showOpenFilePicker: OpenFilePicker;
+/**
+ * Same name and signature, answering a directory handle wherever reading one is possible.
+ *
+ * `mode: 'readwrite'` is refused where there is no native picker, and that refusal is the honest
+ * answer rather than a gap: an `<input>` hands over copies of bytes and there is no route from one
+ * back to the folder it came from. Refusing at the ask beats handing back a handle whose every write
+ * fails later.
+ */
+export declare const showDirectoryPicker: DirectoryPicker;
 export {};

package/build/file-system.js

@@ -1,8 +1,14 @@
 //#region src/file-system.ts
+var NO_SAVE_PICKER = "this browser has no file save picker";
+var NO_FRAMED_PICKER = "a cross origin frame cannot show a file save picker";
+var NO_DOCUMENT = "there is no document here to open a file picker from";
+var NO_WRITE = "this file was opened from a picker that cannot write, so there is nothing to write to";
+var NO_WRITE_FOLDER = "this browser cannot grant write access to a chosen folder";
+var refuse = (message) => new DOMException(message, "NotAllowedError");
 /**
 * Whether this document is framed by another origin.
 *
-* Chromium exposes the picker either way and refuses it at call time, so a property probe says
+* Chromium exposes the pickers either way and refuses them at call time, so a property probe says
 * nothing. A same origin ancestor answers `location.origin`; a cross origin one throws, and so does
 * an opaque origin, which is the case a sandboxed frame presents.
 */
@@ -17,11 +23,240 @@ var framedByAnotherOrigin = () => {
 		return true;
 	}
 };
+/**
+* The `accept` attribute for an `<input>`, from the picker's own `types`.
+*
+* Both halves of each entry go in. The attribute takes MIME types and extensions in one comma
+* separated list, and an engine that does not recognise one of them ignores that one rather than the
+* whole attribute, so listing both is strictly better than choosing. `*` patterns are dropped: they
+* are what `excludeAcceptAllOption: false` already means, and an `accept` of `*` filters nothing
+* while making the dialog claim it does.
+*/
+var acceptFrom = (types) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const type of types ?? []) for (const [mime, extensions] of Object.entries(type.accept ?? {})) {
+		if (mime && !mime.includes("*")) out.add(mime);
+		for (const extension of extensions) out.add(extension);
+	}
+	return [...out].join(",");
+};
+/**
+* One pick through a detached `<input type="file">`, resolving the files or rejecting like a cancel.
+*
+* The `cancel` event is what makes this a promise that always settles, and it is why this fallback is
+* worth having at all rather than being a hazard: measured present on all three engines above. An
+* engine without it would leave a picker that was dismissed pending forever, which is worse than not
+* offering one.
+*
+* NEEDS THE CALLER'S TRANSIENT ACTIVATION, exactly as the platform picker does. `click()` on a file
+* input opens nothing without a gesture, so this has to be reached synchronously from the handler,
+* and an `await` before it loses that. The same rule the native picker has, for the same reason.
+*
+* The input is attached and removed rather than left detached: a detached input's `click()` is
+* ignored by some engines, and leaving it in the document would leave one element per pick behind.
+*/
+var pickThroughInput = (setup) => {
+	const document = globalThis.document;
+	if (!document?.body) return Promise.reject(refuse(NO_DOCUMENT));
+	return new Promise((resolve, reject) => {
+		const input = document.createElement("input");
+		input.type = "file";
+		input.style.display = "none";
+		input.setAttribute("aria-hidden", "true");
+		setup(input);
+		const settle = (finish) => {
+			input.remove();
+			finish();
+		};
+		input.addEventListener("change", () => settle(() => resolve([...input.files ?? []])), { once: true });
+		input.addEventListener("cancel", () => settle(() => reject(new DOMException("the file picker was closed", "AbortError"))), { once: true });
+		document.body.append(input);
+		input.click();
+	});
+};
+var handles = /* @__PURE__ */ new WeakMap();
+/**
+* Entries in a fixed order, which the platform does not promise and the engines do not agree on.
+*
+* Measured above: the same tree comes out of `<input webkitdirectory>` in one order on Chromium and
+* the opposite on Firefox and WebKit. Sorted by code unit rather than `localeCompare`, because a
+* locale sensitive sort is one more thing that differs between two machines running the same code.
+*/
+var ordered = (children) => [...children].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+var fileHandleFor = (node) => {
+	return {
+		kind: "file",
+		name: node.name,
+		/**
+		* The same `File` every time, where the platform hands back a fresh one.
+		*
+		* A `File` from an input is a snapshot taken when it was picked. It cannot be re-read from disk,
+		* so `lastModified` never moves and a staleness check across it can never fire. What it does do
+		* is throw on READ once the file underneath has changed, so a pass over the bytes still refuses
+		* to produce a mixture of two versions; it just reports it as a failed read rather than a
+		* changed file.
+		*/
+		getFile: async () => node.file,
+		createWritable: async () => {
+			throw refuse(NO_WRITE);
+		},
+		isSameEntry: async (other) => other === handles.get(node)
+	};
+};
+var directoryHandleFor = (node) => {
+	const child = (name) => node.children.get(name);
+	const entries = async function* () {
+		for (const [name, entry] of ordered(node.children)) yield [name, handleFor(entry)];
+	};
+	return {
+		kind: "directory",
+		name: node.name,
+		entries,
+		keys: async function* () {
+			for (const [name] of ordered(node.children)) yield name;
+		},
+		values: async function* () {
+			for (const [, entry] of ordered(node.children)) yield handleFor(entry);
+		},
+		[Symbol.asyncIterator]: entries,
+		getFileHandle: async (name, options) => {
+			if (options?.create) throw refuse(NO_WRITE);
+			const found = child(name);
+			if (!found) throw new DOMException(`there is no ${name} here`, "NotFoundError");
+			if (found.kind !== "file") throw new DOMException(`${name} is a directory`, "TypeMismatchError");
+			return handleFor(found);
+		},
+		getDirectoryHandle: async (name, options) => {
+			if (options?.create) throw refuse(NO_WRITE);
+			const found = child(name);
+			if (!found) throw new DOMException(`there is no ${name} here`, "NotFoundError");
+			if (found.kind !== "directory") throw new DOMException(`${name} is a file`, "TypeMismatchError");
+			return handleFor(found);
+		},
+		removeEntry: async () => {
+			throw refuse(NO_WRITE);
+		},
+		/** The path from here down to a handle in this tree, or null where it is not in it. */
+		resolve: async (descendant) => {
+			const search = (from, path) => {
+				for (const [name, entry] of ordered(from.children)) {
+					if (handles.get(entry) === descendant) return [...path, name];
+					if (entry.kind === "directory") {
+						const deeper = search(entry, [...path, name]);
+						if (deeper) return deeper;
+					}
+				}
+				return null;
+			};
+			return handles.get(node) === descendant ? [] : search(node, []);
+		},
+		isSameEntry: async (other) => other === handles.get(node)
+	};
+};
+var handleFor = (node) => {
+	const made = handles.get(node);
+	if (made) return made;
+	const fresh = node.kind === "file" ? fileHandleFor(node) : directoryHandleFor(node);
+	handles.set(node, fresh);
+	return fresh;
+};
+/**
+* The picked folder, rebuilt from the flat list an input hands over.
+*
+* `webkitRelativePath` is the whole tree already flattened: `Pack/Subs/E01.ass` for a folder called
+* `Pack`. The first segment is the folder's own name, so it becomes the root's name and is dropped
+* from every path under it, which is what makes this the same shape `showDirectoryPicker` returns.
+*
+* AN EMPTY FOLDER LOSES ITS NAME, and nothing can be done about that. The name is only ever learned
+* from a file's path, so a folder with nothing in it comes back named `''`. It is a real pick rather
+* than a cancel, since `change` fired, and reporting it as an empty directory is the closest true
+* answer available.
+*
+* A name used twice, once as a file and once as a folder, resolves to the folder, because a path
+* continuing through it proves it is one. Two files with the same path keep the last, which is what
+* a map does and what re-picking the same tree would do anyway.
+*/
+var treeFrom = (files) => {
+	const root = {
+		kind: "directory",
+		name: "",
+		children: /* @__PURE__ */ new Map()
+	};
+	for (const file of files) {
+		const segments = (file.webkitRelativePath || file.name).split("/").filter(Boolean);
+		if (!segments.length) continue;
+		const rooted = Boolean(file.webkitRelativePath) && segments.length > 1;
+		if (rooted && !root.name) root.name = segments[0];
+		const path = rooted ? segments.slice(1) : segments;
+		let level = root.children;
+		for (const name of path.slice(0, -1)) {
+			const existing = level.get(name);
+			const directory = existing?.kind === "directory" ? existing : {
+				kind: "directory",
+				name,
+				children: /* @__PURE__ */ new Map()
+			};
+			if (existing !== directory) level.set(name, directory);
+			level = directory.children;
+		}
+		const leaf = path[path.length - 1];
+		level.set(leaf, {
+			kind: "file",
+			name: leaf,
+			file
+		});
+	}
+	return root;
+};
+/**
+* Same name and signature, refusing before the gesture is spent and never faking a save.
+*
+* The one picker with no fallback. Writing to a location somebody chose needs the platform's picker,
+* and what an app does instead is a product decision rather than a shim: see the header.
+*/
 var showSaveFilePicker = async (options) => {
 	const picker = globalThis.showSaveFilePicker;
-	if (!picker) throw new DOMException("this browser has no file save picker", "NotAllowedError");
-	if (framedByAnotherOrigin()) throw new DOMException("a cross origin frame cannot show a file save picker", "NotAllowedError");
+	if (!picker) throw refuse(NO_SAVE_PICKER);
+	if (framedByAnotherOrigin()) throw refuse(NO_FRAMED_PICKER);
 	return picker(options);
 };
+/**
+* Same name and signature, answering file handles on every engine.
+*
+* The native picker is preferred wherever it can actually be shown, and its handles come back
+* UNTOUCHED: they are structured cloneable, they can be re-granted after a reload, and wrapping them
+* would take exactly that away. A cross origin frame is skipped rather than tried, since the platform
+* refuses there and refusing costs part of the click the fallback still needs.
+*/
+var showOpenFilePicker = async (options = {}) => {
+	const picker = globalThis.showOpenFilePicker;
+	if (picker && !framedByAnotherOrigin()) return picker(options);
+	const accept = acceptFrom(options.types);
+	return (await pickThroughInput((input) => {
+		input.multiple = options.multiple === true;
+		if (accept) input.accept = accept;
+	})).map((file) => handleFor({
+		kind: "file",
+		name: file.name,
+		file
+	}));
+};
+/**
+* Same name and signature, answering a directory handle wherever reading one is possible.
+*
+* `mode: 'readwrite'` is refused where there is no native picker, and that refusal is the honest
+* answer rather than a gap: an `<input>` hands over copies of bytes and there is no route from one
+* back to the folder it came from. Refusing at the ask beats handing back a handle whose every write
+* fails later.
+*/
+var showDirectoryPicker = async (options = {}) => {
+	const picker = globalThis.showDirectoryPicker;
+	if (picker && !framedByAnotherOrigin()) return picker(options);
+	if (options.mode === "readwrite") throw refuse(NO_WRITE_FOLDER);
+	return handleFor(treeFrom(await pickThroughInput((input) => {
+		input.webkitdirectory = true;
+		input.multiple = true;
+	})));
+};
 //#endregion
-export { showSaveFilePicker };
+export { showDirectoryPicker, showOpenFilePicker, showSaveFilePicker };

package/build/index.cjs

@@ -3,5 +3,7 @@ const require_storage = require("./storage.cjs");
 const require_permissions = require("./permissions.cjs");
 const require_file_system = require("./file-system.cjs");
 exports.permissions = require_permissions.permissions;
+exports.showDirectoryPicker = require_file_system.showDirectoryPicker;
+exports.showOpenFilePicker = require_file_system.showOpenFilePicker;
 exports.showSaveFilePicker = require_file_system.showSaveFilePicker;
 exports.storage = require_storage.storage;

package/build/index.d.ts

@@ -34,6 +34,6 @@
  */
 export { storage } from './storage';
 export { permissions } from './permissions';
-export { showSaveFilePicker } from './file-system';
+export { showDirectoryPicker, showOpenFilePicker, showSaveFilePicker } from './file-system';
 export type { StorageEstimate } from './storage';
 export type { PermissionStatus } from './permissions';

package/build/index.js

@@ -1,4 +1,4 @@
 import { storage } from "./storage.js";
 import { permissions } from "./permissions.js";
-import { showSaveFilePicker } from "./file-system.js";
-export { permissions, showSaveFilePicker, storage };
+import { showDirectoryPicker, showOpenFilePicker, showSaveFilePicker } from "./file-system.js";
+export { permissions, showDirectoryPicker, showOpenFilePicker, showSaveFilePicker, storage };

package/build/storage.cjs

@@ -91,15 +91,45 @@ var reconcile = (estimate, walked) => {
 * slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
 * it never sees pressure is the failure this replaces.
 *
-* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
-* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
+* In memory, and per REALM rather than per page: a worker holds its own. Persisting it would mean
+* owning storage to describe storage, and a reload re-anchors on a figure the platform stated at
+* that moment, which is the same guarantee. What a realm cannot be allowed to do is hold a ceiling
+* that has since moved, and the release below is how it lets go without any realm telling another.
 */
 var narrowest;
-var ceiling = (reported, usage) => {
+/**
+* Whether the origin was persistent when the ceiling above was latched.
+*
+* THE LATCH HAS TO BE ABLE TO LET GO, AND IN A REALM THAT NEVER ASKED. A grant moves the ceiling by
+* orders of magnitude (measured 2026-09-01 on Firefox: 12 GB to 3.97 TB), so the figure learned
+* before it is worse than useless afterwards. `persist()` is a MAIN THREAD call, because a worker's
+* StorageManager has none, so a worker that latched 12 GB would hold it for its whole life while the
+* page moved on. Anything deciding what to delete from that figure would go on deleting against a
+* ceiling that no longer exists.
+*
+* So the release is keyed on the STATE rather than on the call: every `estimate()` reads
+* `persisted()` alongside the quota, and a change since the latch drops it. That works in every
+* realm, including the ones that could not have made the call, and it needs no shared state between
+* them. `undefined` means the engine would not say, and an engine that will not say has not reported
+* a change, so the latch stands.
+*/
+var latchedUnder;
+var ceiling = (reported, usage, persistent) => {
 	if (reported === void 0) return void 0;
+	if (persistent !== latchedUnder) narrowest = void 0;
+	latchedUnder = persistent;
 	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
 	return Math.max(narrowest, usage ?? 0);
 };
+/**
+* Whether this origin is persistent, or undefined where the engine has no way to be asked.
+*
+* A REJECTION IS NOT A CHANGE OF STATE, so it answers whatever the ceiling was latched under and the
+* latch is left alone. Treating a failed read as a third value would make an engine that fails this
+* call intermittently drop the ceiling every other estimate, which is the pick quietly turning
+* itself off on exactly the engines least able to spare it.
+*/
+var persistence = async (native) => native.persisted ? native.persisted().then((value) => value === true).catch(() => latchedUnder) : void 0;
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -112,11 +142,12 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
+		const [walked, persistent] = await Promise.all([native.getDirectory ? native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null, persistence(native)]);
+		const usage = reconcile(estimate, walked);
 		return {
 			...estimate,
 			usage,
-			quota: ceiling(estimate.quota, usage)
+			quota: ceiling(estimate.quota, usage, persistent)
 		};
 	},
 	/**
@@ -131,12 +162,16 @@ var storage = {
 	* left to do. So this resolves `persisted()`, falling back to the call's own answer only where the
 	* platform will not state the state.
 	*
-	* SECOND, the ceiling. A granted persist can move the quota by orders of magnitude: measured
-	* 2026-09-01 on Firefox, granting the "Store data in persistent storage" doorhanger moved the
-	* reported quota from 12 GB to 3.97 TB on an 8.03 TB device, about 330 times. `estimate()` latches
-	* the narrowest quota it has seen, which is right while nothing changes the ceiling and wrong the
-	* moment something does, so a successful grant forgets it. The next `estimate()` re-anchors on
-	* whatever the platform now says.
+	* SECOND, the ceiling, which this call does NOT release and deliberately so. A granted persist can
+	* move the quota by orders of magnitude: measured 2026-09-01 on Firefox, granting the "Store data
+	* in persistent storage" doorhanger moved the reported quota from 12 GB to 3.97 TB on an 8.03 TB
+	* device, about 330 times. `estimate()` latches the narrowest quota it has seen, which is right
+	* while nothing changes the ceiling and wrong the moment something does.
+	*
+	* Releasing it HERE would only release it in the realm that made the call, and this call can only
+	* be made from the main thread. So the release lives in `estimate()`, keyed on the persistence
+	* state rather than on the call, and every realm picks the change up on its next read. See
+	* `latchedUnder`.
 	*
 	* Chromium, measured 2026-08-30 on Chrome 151, refuses this on every attempt with no prompt shown
 	* at any point, and the quota stays flat. That is not a failure to handle: it is the engine
@@ -146,9 +181,7 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.persist) return false;
 		const answered = await native.persist().catch(() => false);
-		const persisted = await native.persisted?.().catch(() => null) ?? null ?? answered;
-		if (persisted) narrowest = void 0;
-		return persisted;
+		return await persistence(native) ?? null ?? answered;
 	},
 	persisted: () => globalThis.navigator?.storage?.persisted?.() ?? Promise.resolve(false),
 	getDirectory: () => {

package/build/storage.d.ts

@@ -93,12 +93,16 @@ export declare const storage: {
      * left to do. So this resolves `persisted()`, falling back to the call's own answer only where the
      * platform will not state the state.
      *
-     * SECOND, the ceiling. A granted persist can move the quota by orders of magnitude: measured
-     * 2026-09-01 on Firefox, granting the "Store data in persistent storage" doorhanger moved the
-     * reported quota from 12 GB to 3.97 TB on an 8.03 TB device, about 330 times. `estimate()` latches
-     * the narrowest quota it has seen, which is right while nothing changes the ceiling and wrong the
-     * moment something does, so a successful grant forgets it. The next `estimate()` re-anchors on
-     * whatever the platform now says.
+     * SECOND, the ceiling, which this call does NOT release and deliberately so. A granted persist can
+     * move the quota by orders of magnitude: measured 2026-09-01 on Firefox, granting the "Store data
+     * in persistent storage" doorhanger moved the reported quota from 12 GB to 3.97 TB on an 8.03 TB
+     * device, about 330 times. `estimate()` latches the narrowest quota it has seen, which is right
+     * while nothing changes the ceiling and wrong the moment something does.
+     *
+     * Releasing it HERE would only release it in the realm that made the call, and this call can only
+     * be made from the main thread. So the release lives in `estimate()`, keyed on the persistence
+     * state rather than on the call, and every realm picks the change up on its next read. See
+     * `latchedUnder`.
      *
      * Chromium, measured 2026-08-30 on Chrome 151, refuses this on every attempt with no prompt shown
      * at any point, and the quota stays flat. That is not a failure to handle: it is the engine

package/build/storage.js

@@ -90,15 +90,45 @@ var reconcile = (estimate, walked) => {
 * slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
 * it never sees pressure is the failure this replaces.
 *
-* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
-* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
+* In memory, and per REALM rather than per page: a worker holds its own. Persisting it would mean
+* owning storage to describe storage, and a reload re-anchors on a figure the platform stated at
+* that moment, which is the same guarantee. What a realm cannot be allowed to do is hold a ceiling
+* that has since moved, and the release below is how it lets go without any realm telling another.
 */
 var narrowest;
-var ceiling = (reported, usage) => {
+/**
+* Whether the origin was persistent when the ceiling above was latched.
+*
+* THE LATCH HAS TO BE ABLE TO LET GO, AND IN A REALM THAT NEVER ASKED. A grant moves the ceiling by
+* orders of magnitude (measured 2026-09-01 on Firefox: 12 GB to 3.97 TB), so the figure learned
+* before it is worse than useless afterwards. `persist()` is a MAIN THREAD call, because a worker's
+* StorageManager has none, so a worker that latched 12 GB would hold it for its whole life while the
+* page moved on. Anything deciding what to delete from that figure would go on deleting against a
+* ceiling that no longer exists.
+*
+* So the release is keyed on the STATE rather than on the call: every `estimate()` reads
+* `persisted()` alongside the quota, and a change since the latch drops it. That works in every
+* realm, including the ones that could not have made the call, and it needs no shared state between
+* them. `undefined` means the engine would not say, and an engine that will not say has not reported
+* a change, so the latch stands.
+*/
+var latchedUnder;
+var ceiling = (reported, usage, persistent) => {
 	if (reported === void 0) return void 0;
+	if (persistent !== latchedUnder) narrowest = void 0;
+	latchedUnder = persistent;
 	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
 	return Math.max(narrowest, usage ?? 0);
 };
+/**
+* Whether this origin is persistent, or undefined where the engine has no way to be asked.
+*
+* A REJECTION IS NOT A CHANGE OF STATE, so it answers whatever the ceiling was latched under and the
+* latch is left alone. Treating a failed read as a third value would make an engine that fails this
+* call intermittently drop the ceiling every other estimate, which is the pick quietly turning
+* itself off on exactly the engines least able to spare it.
+*/
+var persistence = async (native) => native.persisted ? native.persisted().then((value) => value === true).catch(() => latchedUnder) : void 0;
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -111,11 +141,12 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
+		const [walked, persistent] = await Promise.all([native.getDirectory ? native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null, persistence(native)]);
+		const usage = reconcile(estimate, walked);
 		return {
 			...estimate,
 			usage,
-			quota: ceiling(estimate.quota, usage)
+			quota: ceiling(estimate.quota, usage, persistent)
 		};
 	},
 	/**
@@ -130,12 +161,16 @@ var storage = {
 	* left to do. So this resolves `persisted()`, falling back to the call's own answer only where the
 	* platform will not state the state.
 	*
-	* SECOND, the ceiling. A granted persist can move the quota by orders of magnitude: measured
-	* 2026-09-01 on Firefox, granting the "Store data in persistent storage" doorhanger moved the
-	* reported quota from 12 GB to 3.97 TB on an 8.03 TB device, about 330 times. `estimate()` latches
-	* the narrowest quota it has seen, which is right while nothing changes the ceiling and wrong the
-	* moment something does, so a successful grant forgets it. The next `estimate()` re-anchors on
-	* whatever the platform now says.
+	* SECOND, the ceiling, which this call does NOT release and deliberately so. A granted persist can
+	* move the quota by orders of magnitude: measured 2026-09-01 on Firefox, granting the "Store data
+	* in persistent storage" doorhanger moved the reported quota from 12 GB to 3.97 TB on an 8.03 TB
+	* device, about 330 times. `estimate()` latches the narrowest quota it has seen, which is right
+	* while nothing changes the ceiling and wrong the moment something does.
+	*
+	* Releasing it HERE would only release it in the realm that made the call, and this call can only
+	* be made from the main thread. So the release lives in `estimate()`, keyed on the persistence
+	* state rather than on the call, and every realm picks the change up on its next read. See
+	* `latchedUnder`.
 	*
 	* Chromium, measured 2026-08-30 on Chrome 151, refuses this on every attempt with no prompt shown
 	* at any point, and the quota stays flat. That is not a failure to handle: it is the engine
@@ -145,9 +180,7 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.persist) return false;
 		const answered = await native.persist().catch(() => false);
-		const persisted = await native.persisted?.().catch(() => null) ?? null ?? answered;
-		if (persisted) narrowest = void 0;
-		return persisted;
+		return await persistence(native) ?? null ?? answered;
 	},
 	persisted: () => globalThis.navigator?.storage?.persisted?.() ?? Promise.resolve(false),
 	getDirectory: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/ponyfill",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "type": "module",
   "main": "build/index.cjs",
   "module": "build/index.js",