@ait-co/polyfill 0.1.2 → 0.1.4

package/dist/index.js

@@ -69,6 +69,122 @@ async function loadTossSdk() {
 	}
 }
 //#endregion
+//#region src/shims/_install-helpers.ts
+/**
+* Install `descriptor` at `navigator[prop]`. Prefer instance-level; if the
+* browser refuses (property is non-configurable on the instance), install on
+* `Navigator.prototype` instead.
+*
+* Returns a snapshot describing where the original value was, which
+* `restoreNavigatorProperty` uses to undo the install.
+*/
+function installNavigatorProperty(prop, descriptor) {
+	const nav = navigator;
+	const instanceDesc = Object.getOwnPropertyDescriptor(nav, prop);
+	const instanceHadOwn = instanceDesc !== void 0;
+	if (!instanceDesc || instanceDesc.configurable) try {
+		Object.defineProperty(nav, prop, descriptor);
+		return {
+			location: "instance",
+			originalDescriptor: instanceDesc,
+			instanceHadOwn
+		};
+	} catch {}
+	const proto = Object.getPrototypeOf(nav);
+	const protoDesc = Object.getOwnPropertyDescriptor(proto, prop);
+	if (instanceHadOwn) try {
+		delete nav[prop];
+	} catch {}
+	Object.defineProperty(proto, prop, descriptor);
+	return {
+		location: "prototype",
+		originalDescriptor: protoDesc,
+		instanceHadOwn
+	};
+}
+/**
+* Reverse the install recorded in `snapshot`. If the original descriptor was
+* `undefined` (property didn't exist before), delete the property instead of
+* re-defining it.
+*/
+function restoreNavigatorProperty(prop, snapshot) {
+	const target = snapshot.location === "instance" ? navigator : Object.getPrototypeOf(navigator);
+	if (snapshot.originalDescriptor) try {
+		Object.defineProperty(target, prop, snapshot.originalDescriptor);
+	} catch {}
+	else try {
+		delete target[prop];
+	} catch {}
+}
+/**
+* Mutate methods on an existing object rather than replacing the object
+* itself. This is the path we take for `navigator.geolocation`, `navigator.share`,
+* and `navigator.vibrate` in Chromium, where the slot on `navigator` is a
+* non-configurable own property that we cannot replace — but the methods
+* themselves (or the methods on the referenced object) are still
+* `configurable: true, writable: true`.
+*
+* Each replacement is installed via plain assignment. If any slot is not
+* writable (e.g. frozen object), install is aborted and previously-applied
+* replacements are rolled back, so the caller observes an atomic "all or
+* nothing" failure as `null`. The caller is expected to degrade gracefully
+* (e.g. log a one-time `console.warn`) when that happens.
+*/
+function installObjectMethods(target, replacements) {
+	const methods = {};
+	const applied = [];
+	const bag = target;
+	for (const key of Object.keys(replacements)) {
+		const hadOwn = Object.hasOwn(target, key);
+		const original = bag[key];
+		try {
+			bag[key] = replacements[key];
+		} catch {
+			for (const applieKey of applied) {
+				const prev = methods[applieKey];
+				if (!prev) continue;
+				if (prev.hadOwn) bag[applieKey] = prev.original;
+				else delete bag[applieKey];
+			}
+			return null;
+		}
+		if (bag[key] !== replacements[key]) {
+			for (const applieKey of applied) {
+				const prev = methods[applieKey];
+				if (!prev) continue;
+				if (prev.hadOwn) bag[applieKey] = prev.original;
+				else delete bag[applieKey];
+			}
+			return null;
+		}
+		methods[key] = {
+			hadOwn,
+			original
+		};
+		applied.push(key);
+	}
+	return {
+		target,
+		methods
+	};
+}
+/**
+* Reverse an `installObjectMethods` snapshot. Reassigns originals for slots
+* that were own properties before install; deletes the override for slots
+* that were inherited (so the prototype method surfaces again).
+*/
+function restoreObjectMethods(snapshot) {
+	const bag = snapshot.target;
+	for (const key of Object.keys(snapshot.methods)) {
+		const entry = snapshot.methods[key];
+		if (!entry) continue;
+		try {
+			if (entry.hadOwn) bag[key] = entry.original;
+			else delete bag[key];
+		} catch {}
+	}
+}
+//#endregion
 //#region src/shims/clipboard.ts
 /**
 * `navigator.clipboard` shim.
@@ -81,7 +197,7 @@ async function loadTossSdk() {
 * surfaces unchanged — we don't paper over missing support.
 */
 const BACKUP_KEY$2 = Symbol.for("@ait-co/polyfill/clipboard.original");
-const HAD_KEY$1 = Symbol.for("@ait-co/polyfill/clipboard.hadOriginal");
+const SNAPSHOT_KEY$2 = Symbol.for("@ait-co/polyfill/clipboard.snapshot");
 /**
 * Produces a Clipboard-compatible object whose `readText` / `writeText` methods
 * route to the SDK when in Toss, else fall through to the supplied `fallback`.
@@ -132,34 +248,24 @@ function installClipboardShim() {
 	if (BACKUP_KEY$2 in host) return () => uninstallClipboardShim();
 	const original = navigator.clipboard;
 	host[BACKUP_KEY$2] = original;
-	host[HAD_KEY$1] = "clipboard" in navigator;
-	const shim = createClipboardShim(original);
-	Object.defineProperty(navigator, "clipboard", {
-		value: shim,
+	host[SNAPSHOT_KEY$2] = installNavigatorProperty("clipboard", {
+		value: createClipboardShim(original),
 		configurable: true,
 		writable: true
 	});
 	return uninstallClipboardShim;
 }
 /**
-* Remove the shim and restore the pre-install shape. Uses delete + conditional
-* redefine so a prototype-level `navigator.clipboard` (non-configurable in real
-* browsers) becomes visible again instead of being permanently shadowed.
+* Remove the shim and restore the pre-install shape.
 */
 function uninstallClipboardShim() {
 	if (typeof navigator === "undefined") return;
 	const host = navigator;
 	if (!(BACKUP_KEY$2 in host)) return;
-	const original = host[BACKUP_KEY$2];
-	const had = host[HAD_KEY$1];
-	delete navigator.clipboard;
-	if (had && navigator.clipboard !== original) Object.defineProperty(navigator, "clipboard", {
-		value: original,
-		configurable: true,
-		writable: true
-	});
+	const snapshot = host[SNAPSHOT_KEY$2];
+	if (snapshot) restoreNavigatorProperty("clipboard", snapshot);
 	delete host[BACKUP_KEY$2];
-	delete host[HAD_KEY$1];
+	delete host[SNAPSHOT_KEY$2];
 }
 //#endregion
 //#region src/shims/geolocation.ts
@@ -173,6 +279,13 @@ function uninstallClipboardShim() {
 * Outside Apps in Toss → defers to the browser's native `navigator.geolocation`.
 * If neither is available, the error callback receives a `GeolocationPositionError`.
 *
+* Install strategy: **method-level**. We do **not** replace `navigator.geolocation`
+* itself — Chromium marks that slot as a non-configurable own property, which
+* both `defineProperty(navigator, 'geolocation', …)` and the prototype-level
+* fallback cannot override (the instance shadow blocks prototype reads). We
+* instead mutate the methods on the existing `Geolocation` object, whose own
+* method descriptors are configurable+writable in every browser we've seen.
+*
 * SDK/Web shape mismatch handled here:
 *   - SDK `Accuracy` is a numeric enum (1 = Lowest … 6 = BestForNavigation); the
 *     standard `PositionOptions.enableHighAccuracy` is a boolean. We map
@@ -192,6 +305,7 @@ function uninstallClipboardShim() {
 * `uninstall()`.
 */
 const BACKUP_KEY$1 = Symbol.for("@ait-co/polyfill/geolocation.original");
+const SNAPSHOT_KEY$1 = Symbol.for("@ait-co/polyfill/geolocation.snapshot");
 const ACCURACY_BALANCED = 3;
 const ACCURACY_HIGH = 4;
 function toStandardPosition(sdk) {
@@ -263,7 +377,7 @@ function createGeolocationShim(fallback) {
 						return;
 					}
 				}
-				if (!fallback) {
+				if (!fallback.getCurrentPosition) {
 					error?.(toPositionError(2, "[@ait-co/polyfill] navigator.geolocation is not available in this environment."));
 					return;
 				}
@@ -301,7 +415,7 @@ function createGeolocationShim(fallback) {
 						return;
 					}
 				}
-				if (!fallback) {
+				if (!fallback.watchPosition) {
 					pendingWatches.delete(id);
 					error?.(toPositionError(2, "[@ait-co/polyfill] navigator.geolocation is not available in this environment."));
 					return;
@@ -312,7 +426,7 @@ function createGeolocationShim(fallback) {
 				}
 				const nativeId = fallback.watchPosition(success, error, options);
 				if (pending.cancelled) {
-					fallback.clearWatch(nativeId);
+					fallback.clearWatch?.(nativeId);
 					pendingWatches.delete(id);
 					return;
 				}
@@ -335,7 +449,7 @@ function createGeolocationShim(fallback) {
 				return;
 			}
 			const nativeId = nativeWatches.get(id);
-			if (nativeId !== void 0 && fallback) {
+			if (nativeId !== void 0 && fallback.clearWatch) {
 				fallback.clearWatch(nativeId);
 				nativeWatches.delete(id);
 			}
@@ -346,28 +460,37 @@ function installGeolocationShim() {
 	if (typeof navigator === "undefined") return () => {};
 	const host = navigator;
 	if (BACKUP_KEY$1 in host) return () => uninstallGeolocationShim();
-	const original = navigator.geolocation;
-	host[BACKUP_KEY$1] = original;
-	const shim = createGeolocationShim(original);
-	Object.defineProperty(navigator, "geolocation", {
-		value: shim,
-		configurable: true,
-		writable: true
+	const target = navigator.geolocation;
+	if (!target) {
+		host[BACKUP_KEY$1] = void 0;
+		return () => uninstallGeolocationShim();
+	}
+	const shim = createGeolocationShim({
+		getCurrentPosition: target.getCurrentPosition?.bind(target),
+		watchPosition: target.watchPosition?.bind(target),
+		clearWatch: target.clearWatch?.bind(target)
 	});
+	const snapshot = installObjectMethods(target, {
+		getCurrentPosition: shim.getCurrentPosition,
+		watchPosition: shim.watchPosition,
+		clearWatch: shim.clearWatch
+	});
+	if (!snapshot) {
+		host[BACKUP_KEY$1] = void 0;
+		return () => uninstallGeolocationShim();
+	}
+	host[BACKUP_KEY$1] = { target };
+	host[SNAPSHOT_KEY$1] = snapshot;
 	return uninstallGeolocationShim;
 }
 function uninstallGeolocationShim() {
 	if (typeof navigator === "undefined") return;
 	const host = navigator;
 	if (!(BACKUP_KEY$1 in host)) return;
-	const original = host[BACKUP_KEY$1];
-	delete navigator.geolocation;
-	if (original !== void 0 && navigator.geolocation !== original) Object.defineProperty(navigator, "geolocation", {
-		value: original,
-		configurable: true,
-		writable: true
-	});
+	const snapshot = host[SNAPSHOT_KEY$1];
+	if (snapshot) restoreObjectMethods(snapshot);
 	delete host[BACKUP_KEY$1];
+	delete host[SNAPSHOT_KEY$1];
 }
 //#endregion
 //#region src/shims/network.ts
@@ -392,6 +515,15 @@ function uninstallGeolocationShim() {
 * visible again. We never mutate the prototype — doing so would throw in
 * browsers where the descriptor is non-configurable.
 *
+* Browser-compat caveat (Chromium): `navigator.onLine` and `navigator.connection`
+* are value slots, not methods, so the method-level install trick we use for
+* `geolocation`/`share`/`vibrate` does not apply here. When Chromium marks the
+* instance descriptor as non-configurable AND the prototype descriptor is also
+* non-configurable, we cannot install. In that case the shim logs a one-time
+* `console.warn` and leaves the native values in place — consumers keep the
+* browser's own `onLine`/`connection` values; the SDK-synced state is simply
+* disabled for that session.
+*
 * Caveat: the Web NetworkInformation API is evented (`change` fires on
 * transitions). The SDK exposes only a one-shot query, so listeners attached
 * to `navigator.connection` are accepted but never fire from a `change` event
@@ -413,6 +545,8 @@ function uninstallGeolocationShim() {
 * reads may return the native object.
 */
 const INSTALLED_KEY = Symbol.for("@ait-co/polyfill/network.installed");
+const ON_LINE_SNAPSHOT_KEY = Symbol.for("@ait-co/polyfill/network.onLine.snapshot");
+const CONNECTION_SNAPSHOT_KEY = Symbol.for("@ait-co/polyfill/network.connection.snapshot");
 const REFRESH_THROTTLE_MS = 500;
 function statusToOnline(status) {
 	return status !== "OFFLINE";
@@ -492,47 +626,52 @@ function installNetworkShim() {
 		})();
 		return inflight;
 	}
+	const nativeOnLine = navigator.onLine;
+	const nativeConnection = navigator.connection;
 	refresh();
-	Object.defineProperty(navigator, "onLine", {
-		configurable: true,
-		get() {
-			refresh();
-			if (cachedStatus !== null) return statusToOnline(cachedStatus);
-			const desc = Object.getOwnPropertyDescriptor(navigator, "onLine");
-			delete navigator.onLine;
-			try {
-				return navigator.onLine;
-			} finally {
-				if (desc) Object.defineProperty(navigator, "onLine", desc);
+	let installWarned = false;
+	const warnNonConfigurable = (e) => {
+		if (installWarned) return;
+		installWarned = true;
+		console.warn("[@ait-co/polyfill] navigator.onLine/connection is non-configurable in this browser; Toss network status sync disabled.", e);
+	};
+	try {
+		host[ON_LINE_SNAPSHOT_KEY] = installNavigatorProperty("onLine", {
+			configurable: true,
+			get() {
+				refresh();
+				if (cachedStatus !== null) return statusToOnline(cachedStatus);
+				return nativeOnLine ?? true;
 			}
-		}
-	});
-	Object.defineProperty(navigator, "connection", {
-		configurable: true,
-		get() {
-			refresh();
-			if (cachedStatus === null) {
-				const desc = Object.getOwnPropertyDescriptor(navigator, "connection");
-				delete navigator.connection;
-				try {
-					const native = navigator.connection;
-					if (native !== void 0) return native;
-				} finally {
-					if (desc) Object.defineProperty(navigator, "connection", desc);
-				}
+		});
+	} catch (e) {
+		warnNonConfigurable(e);
+	}
+	try {
+		host[CONNECTION_SNAPSHOT_KEY] = installNavigatorProperty("connection", {
+			configurable: true,
+			get() {
+				refresh();
+				if (cachedStatus === null && nativeConnection !== void 0) return nativeConnection;
+				return connection;
 			}
-			return connection;
-		}
-	});
+		});
+	} catch (e) {
+		warnNonConfigurable(e);
+	}
 	return uninstallNetworkShim;
 }
 function uninstallNetworkShim() {
 	if (typeof navigator === "undefined") return;
 	const host = navigator;
 	if (!host[INSTALLED_KEY]) return;
-	delete navigator.onLine;
-	delete navigator.connection;
+	const onLineSnap = host[ON_LINE_SNAPSHOT_KEY];
+	if (onLineSnap) restoreNavigatorProperty("onLine", onLineSnap);
+	const connSnap = host[CONNECTION_SNAPSHOT_KEY];
+	if (connSnap) restoreNavigatorProperty("connection", connSnap);
 	delete host[INSTALLED_KEY];
+	delete host[ON_LINE_SNAPSHOT_KEY];
+	delete host[CONNECTION_SNAPSHOT_KEY];
 }
 //#endregion
 //#region src/shims/share.ts
@@ -546,11 +685,18 @@ function uninstallNetworkShim() {
 * Outside Apps in Toss → defers to the browser's native `navigator.share`, or
 * throws `NotSupportedError` if unavailable.
 *
+* Install strategy: **method-level** on `navigator`. Assigning
+* `navigator.share = fn` creates an own property that shadows the prototype
+* method. Uninstall deletes the own shadow so the prototype method surfaces
+* again. We do not mutate `Navigator.prototype` — in real browsers its
+* descriptor may be non-configurable, which would throw on reassignment.
+*
 * Caveat: the SDK's share has no counterpart for `files` (Web Share Level 2).
 * `canShare({ files })` returns `false` whenever the sync-accessible detection
 * says Toss is active (or is being forced via the test override).
 */
 const SHARE_BACKUP_KEY = Symbol.for("@ait-co/polyfill/share.original");
+const SHARE_SNAPSHOT_KEY = Symbol.for("@ait-co/polyfill/share.snapshot");
 function buildSdkMessage(data) {
 	const parts = [];
 	if (data?.title != null && data.title !== "") parts.push(data.title);
@@ -577,7 +723,7 @@ async function shareShim(data) {
 	}
 	const original = navigator[SHARE_BACKUP_KEY]?.share;
 	if (!original) throw new DOMException("[@ait-co/polyfill] navigator.share is not available in this environment.", "NotSupportedError");
-	return original.call(navigator, data);
+	return original(data);
 }
 function canShareShim(data) {
 	const hasFiles = Boolean(data?.files && data.files.length > 0);
@@ -588,7 +734,7 @@ function canShareShim(data) {
 	}
 	if (toss === true) return Boolean(data?.title != null && data.title !== "" || data?.text != null && data.text !== "" || data?.url != null && data.url !== "");
 	const originalCanShare = navigator[SHARE_BACKUP_KEY]?.canShare;
-	if (originalCanShare) return originalCanShare.call(navigator, data);
+	if (originalCanShare) return originalCanShare(data);
 	return Boolean(data?.title != null && data.title !== "" || data?.text != null && data.text !== "" || data?.url != null && data.url !== "");
 }
 function installShareShim() {
@@ -597,41 +743,28 @@ function installShareShim() {
 	if (SHARE_BACKUP_KEY in host) return () => uninstallShareShim();
 	const nav = navigator;
 	host[SHARE_BACKUP_KEY] = {
-		share: nav.share,
-		canShare: nav.canShare,
-		hadShare: "share" in nav,
-		hadCanShare: "canShare" in nav
+		share: nav.share ? nav.share.bind(navigator) : void 0,
+		canShare: nav.canShare ? nav.canShare.bind(navigator) : void 0
 	};
-	Object.defineProperty(navigator, "share", {
-		value: shareShim,
-		configurable: true,
-		writable: true
-	});
-	Object.defineProperty(navigator, "canShare", {
-		value: canShareShim,
-		configurable: true,
-		writable: true
+	const snapshot = installObjectMethods(navigator, {
+		share: shareShim,
+		canShare: canShareShim
 	});
+	if (!snapshot) {
+		delete host[SHARE_BACKUP_KEY];
+		return () => uninstallShareShim();
+	}
+	host[SHARE_SNAPSHOT_KEY] = snapshot;
 	return uninstallShareShim;
 }
 function uninstallShareShim() {
 	if (typeof navigator === "undefined") return;
 	const host = navigator;
 	if (!(SHARE_BACKUP_KEY in host)) return;
-	const backup = host[SHARE_BACKUP_KEY];
-	delete navigator.share;
-	if (backup?.hadShare && navigator.share !== backup.share) Object.defineProperty(navigator, "share", {
-		value: backup.share,
-		configurable: true,
-		writable: true
-	});
-	delete navigator.canShare;
-	if (backup?.hadCanShare && navigator.canShare !== backup.canShare) Object.defineProperty(navigator, "canShare", {
-		value: backup.canShare,
-		configurable: true,
-		writable: true
-	});
+	const snapshot = host[SHARE_SNAPSHOT_KEY];
+	if (snapshot) restoreObjectMethods(snapshot);
 	delete host[SHARE_BACKUP_KEY];
+	delete host[SHARE_SNAPSHOT_KEY];
 }
 //#endregion
 //#region src/shims/vibrate.ts
@@ -647,6 +780,11 @@ function uninstallShareShim() {
 * or returns `false` when unavailable (matches the spec — browsers that don't
 * support vibration simply return `false`).
 *
+* Install strategy: **method-level** on `navigator`. We assign our wrapper to
+* `navigator.vibrate` (creating an own shadow over the prototype method) and
+* delete it on uninstall so the prototype re-surfaces. We do not mutate
+* `Navigator.prototype` itself — browsers may mark it non-configurable.
+*
 * Caveats (documented in CLAUDE.md as the known lossy trade-off):
 *   - SDK haptics are qualitative ("tickWeak", "basicMedium"), not millisecond
 *     durations. The shim approximates intensity from duration but cannot
@@ -657,7 +795,7 @@ function uninstallShareShim() {
 *     `true` immediately (fire-and-forget). Errors from the SDK are swallowed.
 */
 const BACKUP_KEY = Symbol.for("@ait-co/polyfill/vibrate.original");
-const HAD_KEY = Symbol.for("@ait-co/polyfill/vibrate.hadOriginal");
+const SNAPSHOT_KEY = Symbol.for("@ait-co/polyfill/vibrate.snapshot");
 const SHORT_VIBRATION_MS = 40;
 async function haptic(type) {
 	const fn = (await loadTossSdk())?.generateHapticFeedback;
@@ -672,7 +810,7 @@ function vibrateShim(pattern) {
 	const arr = Array.isArray(pattern) ? pattern : [pattern];
 	if (arr.length === 0 || arr.every((n) => n === 0)) {
 		(async () => {
-			if (!await isTossEnvironment()) navigator[BACKUP_KEY]?.call(navigator, pattern);
+			if (!await isTossEnvironment()) navigator[BACKUP_KEY]?.(pattern);
 		})();
 		return true;
 	}
@@ -691,7 +829,8 @@ function vibrateShim(pattern) {
 			}
 			return;
 		}
-		navigator[BACKUP_KEY]?.call(navigator, pattern);
+		const original = navigator[BACKUP_KEY];
+		original?.(pattern);
 	})();
 	return true;
 }
@@ -700,33 +839,27 @@ function installVibrateShim() {
 	const host = navigator;
 	if (BACKUP_KEY in host) return () => uninstallVibrateShim();
 	const nav = navigator;
-	host[BACKUP_KEY] = nav.vibrate;
-	host[HAD_KEY] = "vibrate" in nav;
-	Object.defineProperty(navigator, "vibrate", {
-		value: vibrateShim,
-		configurable: true,
-		writable: true
-	});
+	host[BACKUP_KEY] = nav.vibrate ? nav.vibrate.bind(navigator) : void 0;
+	const snapshot = installObjectMethods(navigator, { vibrate: vibrateShim });
+	if (!snapshot) {
+		delete host[BACKUP_KEY];
+		return () => uninstallVibrateShim();
+	}
+	host[SNAPSHOT_KEY] = snapshot;
 	return uninstallVibrateShim;
 }
 function uninstallVibrateShim() {
 	if (typeof navigator === "undefined") return;
 	const host = navigator;
 	if (!(BACKUP_KEY in host)) return;
-	const original = host[BACKUP_KEY];
-	const had = host[HAD_KEY];
-	delete navigator.vibrate;
-	if (had && navigator.vibrate !== original) Object.defineProperty(navigator, "vibrate", {
-		value: original,
-		configurable: true,
-		writable: true
-	});
+	const snapshot = host[SNAPSHOT_KEY];
+	if (snapshot) restoreObjectMethods(snapshot);
 	delete host[BACKUP_KEY];
-	delete host[HAD_KEY];
+	delete host[SNAPSHOT_KEY];
 }
 //#endregion
 //#region src/index.ts
-const VERSION = "0.1.2";
+const VERSION = "0.1.4";
 const NOOP = () => {};
 /**
 * Install every shim this library ships, but only if we detect an Apps in