@banou/ponyfill 0.0.4 → 0.0.6

package/README.md

@@ -58,10 +58,18 @@ That is not hypothetical. It is why four of ripple's storage eviction tests sat
 they filled the origin to provoke that condition, and 3.5 GB of padding left the free figure
 identical to the byte.
 
-This package does **not** invent a normalised quota, and does not add API for the difference either:
-on Chromium you really can write 10 more GiB, so the native answer is true, and there is no platform
-name for "which shape is this". It is written down here and in the source because the two are
-indistinguishable at rest, which is how the difference went unnoticed for months.
+**The behaviour picked is Firefox's: a ceiling does not rise because you put something under it.**
+`quota` is reported as the lowest the platform has stated for this origin, which needs no probe and
+no user agent sniffing, and invents nothing: the platform really did say the origin could hold that
+much. Two ordinary things are broken by the rising version, and both were seen in ripple:
+`usage / quota` as a gauge never fills, and `quota - usage < floor` never fires, so nothing can
+detect pressure at all.
+
+The cost is deliberate and in the safe direction. On Chromium, once bytes are written the reported
+headroom is smaller than what could really be written, so a caller reclaims cache 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. 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.
 
 ## Adding to it
 

package/build/file-system.cjs

@@ -0,0 +1,28 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/file-system.ts
+/**
+* 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
+* 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.
+*/
+var framedByAnotherOrigin = () => {
+	if (typeof window === "undefined") return false;
+	const top = window.top;
+	if (!top || top === window.self) return false;
+	try {
+		top.location.origin;
+		return false;
+	} catch {
+		return true;
+	}
+};
+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");
+	return picker(options);
+};
+//#endregion
+exports.showSaveFilePicker = showSaveFilePicker;

package/build/file-system.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The File System Access pickers, with the same names and one behaviour picked.
+ *
+ * ## 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:
+ *
+ *  - 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"
+ *
+ * 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".
+ *
+ * ## The pick
+ *
+ * REJECT BEFORE THE ACTIVATION IS SPENT, with a rejection a caller can tell apart from a cancel.
+ *
+ * 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.
+ *
+ * `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. 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.
+ */
+type SaveFilePickerOptions = {
+    suggestedName?: string;
+    types?: {
+        description?: string;
+        accept: Record<string, string[]>;
+    }[];
+    excludeAcceptAllOption?: boolean;
+    id?: string;
+    startIn?: unknown;
+};
+type SaveFilePicker = (options?: SaveFilePickerOptions) => Promise<FileSystemFileHandle>;
+export declare const showSaveFilePicker: SaveFilePicker;
+export {};

package/build/file-system.js

@@ -0,0 +1,27 @@
+//#region src/file-system.ts
+/**
+* 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
+* 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.
+*/
+var framedByAnotherOrigin = () => {
+	if (typeof window === "undefined") return false;
+	const top = window.top;
+	if (!top || top === window.self) return false;
+	try {
+		top.location.origin;
+		return false;
+	} catch {
+		return true;
+	}
+};
+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");
+	return picker(options);
+};
+//#endregion
+export { showSaveFilePicker };

package/build/index.cjs

@@ -1,3 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 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.showSaveFilePicker = require_file_system.showSaveFilePicker;
 exports.storage = require_storage.storage;

package/build/index.d.ts

@@ -13,8 +13,12 @@
  * anything: it is a utility library wearing the word. So the surface here is exactly the platform's
  * surface, and a helper only becomes public if the platform has one by that name.
  *
- * Everything else lives behind it. The walk that corrects `estimate().usage`, the bounds on that
- * walk, and the reconciliation between the measured and reported figures are all internal, because
+ * WHERE ENGINES DIVERGE, ONE BEHAVIOUR IS PICKED and made consistent, so application code never
+ * branches. That is the point of the package rather than a liberty it takes. Each pick is argued
+ * where it lives, and each says what it gives up.
+ *
+ * Everything else stays behind the surface. The walk that corrects `estimate().usage`, the bounds on
+ * that walk, and the reconciliation between measured and reported figures are all internal, because
  * `navigator.storage` has no such members and neither should this.
  *
  * ## What belongs in here
@@ -25,7 +29,11 @@
  * next person is not made to repeat it.
  *
  * Every module here states what was measured, on what, and when. A workaround with no measurement
- * behind it is a guess that outlives the bug it was written for.
+ * behind it is a guess that outlives the bug it was written for, and where a measurement is missing
+ * the module says so rather than implying one.
  */
 export { storage } from './storage';
+export { permissions } from './permissions';
+export { showSaveFilePicker } from './file-system';
 export type { StorageEstimate } from './storage';
+export type { PermissionStatus } from './permissions';

package/build/index.js

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

package/build/permissions.cjs

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/permissions.ts
+var isState = (value) => value === "granted" || value === "denied" || value === "prompt";
+var permissions = { 
+/**
+* Same name and same signature, answering `'prompt'` wherever the platform would not answer.
+*
+* The `await` is INSIDE the `try` on purpose, and it is the whole reason this is a wrapper rather
+* than a one-line `.catch`. `query` can throw synchronously for a name the engine does not know
+* and reject asynchronously for one it does, and a `.catch` on the returned promise sees only the
+* second. Getting that wrong turns a missing permission name into an uncaught exception at
+* whatever moment the feature is first used.
+*/
+query: async (descriptor) => {
+	try {
+		const status = await (globalThis.navigator?.permissions)?.query(descriptor);
+		return { state: isState(status?.state) ? status.state : "prompt" };
+	} catch {
+		return { state: "prompt" };
+	}
+} };
+//#endregion
+exports.permissions = permissions;

package/build/permissions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `navigator.permissions`, with the same member name and one behaviour picked.
+ *
+ * ## The divergence
+ *
+ * `query()` has FOUR ways of not answering, and an app that wants a permission state has to handle
+ * all of them separately even though every one means the same thing to it:
+ *
+ *  1. the engine has no Permissions API at all, so `navigator.permissions` is undefined
+ *  2. the engine has it but rejects the name, because `PermissionName` is a per-engine list
+ *  3. the engine has it and THROWS SYNCHRONOUSLY for a name it does not know, which a `.catch` on
+ *     the returned promise does not see at all
+ *  4. it answers, with a real `PermissionState`
+ *
+ * Only the fourth is the platform's documented behaviour. The other three are the same question
+ * coming back unanswered in three different shapes, and the shapes are not interchangeable: case 3
+ * needs a `try` around the CALL rather than a `.catch` on its result, which is the kind of detail
+ * that is correct in the one file someone thought about it in and wrong everywhere else.
+ *
+ * ## The pick
+ *
+ * All three collapse to `'prompt'`.
+ *
+ * `'prompt'` rather than `'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. `'prompt'` is
+ * also the honest description of what happens next: press the button and the browser will decide.
+ *
+ * WHAT THAT LOSES, stated rather than buried: after the collapse, `'prompt'` means either "the
+ * browser will ask" or "the browser cannot be asked at all", and nothing distinguishes them any
+ * more. That is deliberate. An app that genuinely needs to tell those apart is asking a question the
+ * Permissions API does not answer either, since case 2 and case 4 are indistinguishable from a
+ * rejected promise.
+ *
+ * NOT MEASURED, and this is the one entry in the package without a dated number behind it. What is
+ * recorded upstream is the SHAPE of the failure rather than an engine and a version: a query for a
+ * name an engine does not implement rejects, or throws outright. Both are handled here, and the
+ * absence of a measurement is why this file says so rather than inventing one.
+ */
+/** The platform's own `PermissionStatus`, narrowed to the member anything actually reads. */
+export type PermissionStatus = {
+    state: PermissionState;
+};
+export declare const permissions: {
+    /**
+     * Same name and same signature, answering `'prompt'` wherever the platform would not answer.
+     *
+     * The `await` is INSIDE the `try` on purpose, and it is the whole reason this is a wrapper rather
+     * than a one-line `.catch`. `query` can throw synchronously for a name the engine does not know
+     * and reject asynchronously for one it does, and a `.catch` on the returned promise sees only the
+     * second. Getting that wrong turns a missing permission name into an uncaught exception at
+     * whatever moment the feature is first used.
+     */
+    query: (descriptor: PermissionDescriptor) => Promise<PermissionStatus>;
+};

package/build/permissions.js

@@ -0,0 +1,22 @@
+//#region src/permissions.ts
+var isState = (value) => value === "granted" || value === "denied" || value === "prompt";
+var permissions = { 
+/**
+* Same name and same signature, answering `'prompt'` wherever the platform would not answer.
+*
+* The `await` is INSIDE the `try` on purpose, and it is the whole reason this is a wrapper rather
+* than a one-line `.catch`. `query` can throw synchronously for a name the engine does not know
+* and reject asynchronously for one it does, and a `.catch` on the returned promise sees only the
+* second. Getting that wrong turns a missing permission name into an uncaught exception at
+* whatever moment the feature is first used.
+*/
+query: async (descriptor) => {
+	try {
+		const status = await (globalThis.navigator?.permissions)?.query(descriptor);
+		return { state: isState(status?.state) ? status.state : "prompt" };
+	} catch {
+		return { state: "prompt" };
+	}
+} };
+//#endregion
+export { permissions };

package/build/storage.cjs

@@ -66,6 +66,40 @@ var reconcile = (estimate, walked) => {
 	}
 	return Math.max(reported, walked);
 };
+/**
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* 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.
+*/
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -78,13 +112,44 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: reconcile(estimate, walked)
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
-	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),
+	/**
+	* Same name and signature, resolving what the origin IS rather than what the call said it did.
+	*
+	* TWO PICKS, both inside one call.
+	*
+	* FIRST, the answer. `persist()` resolves its own claim, and `persisted()` resolves the state the
+	* app then lives in. Those are different questions and only the second decides anything: whether
+	* the origin can still be evicted. A call can resolve false on an engine where the origin is
+	* already persistent, and an app reading the first answer then offers a button that has nothing
+	* 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.
+	*
+	* 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
+	* answering, and `persisted()` reports the same false afterwards.
+	*/
+	persist: async () => {
+		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;
+	},
 	persisted: () => globalThis.navigator?.storage?.persisted?.() ?? Promise.resolve(false),
 	getDirectory: () => {
 		const native = globalThis.navigator?.storage;

package/build/storage.d.ts

@@ -81,6 +81,29 @@ export declare const storage: {
      * downgrade, because the platform's figure is a floor rather than a guess.
      */
     estimate: () => Promise<StorageEstimate>;
+    /**
+     * Same name and signature, resolving what the origin IS rather than what the call said it did.
+     *
+     * TWO PICKS, both inside one call.
+     *
+     * FIRST, the answer. `persist()` resolves its own claim, and `persisted()` resolves the state the
+     * app then lives in. Those are different questions and only the second decides anything: whether
+     * the origin can still be evicted. A call can resolve false on an engine where the origin is
+     * already persistent, and an app reading the first answer then offers a button that has nothing
+     * 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.
+     *
+     * 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
+     * answering, and `persisted()` reports the same false afterwards.
+     */
     persist: () => Promise<boolean>;
     persisted: () => Promise<boolean>;
     getDirectory: () => Promise<FileSystemDirectoryHandle>;

package/build/storage.js

@@ -65,6 +65,40 @@ var reconcile = (estimate, walked) => {
 	}
 	return Math.max(reported, walked);
 };
+/**
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* 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.
+*/
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -77,13 +111,44 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: reconcile(estimate, walked)
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
-	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),
+	/**
+	* Same name and signature, resolving what the origin IS rather than what the call said it did.
+	*
+	* TWO PICKS, both inside one call.
+	*
+	* FIRST, the answer. `persist()` resolves its own claim, and `persisted()` resolves the state the
+	* app then lives in. Those are different questions and only the second decides anything: whether
+	* the origin can still be evicted. A call can resolve false on an engine where the origin is
+	* already persistent, and an app reading the first answer then offers a button that has nothing
+	* 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.
+	*
+	* 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
+	* answering, and `persisted()` reports the same false afterwards.
+	*/
+	persist: async () => {
+		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;
+	},
 	persisted: () => globalThis.navigator?.storage?.persisted?.() ?? Promise.resolve(false),
 	getDirectory: () => {
 		const native = globalThis.navigator?.storage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/ponyfill",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "build/index.cjs",
   "module": "build/index.js",
@@ -15,6 +15,16 @@
       "types": "./build/storage.d.ts",
       "import": "./build/storage.js",
       "require": "./build/storage.cjs"
+    },
+    "./permissions": {
+      "types": "./build/permissions.d.ts",
+      "import": "./build/permissions.js",
+      "require": "./build/permissions.cjs"
+    },
+    "./file-system": {
+      "types": "./build/file-system.d.ts",
+      "import": "./build/file-system.js",
+      "require": "./build/file-system.cjs"
     }
   },
   "scripts": {