@banou/ponyfill 0.0.5 → 0.0.6

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

@@ -119,7 +119,37 @@ var storage = {
 			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

@@ -118,7 +118,37 @@ var storage = {
 			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.5",
+  "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": {