@ait-co/polyfill 0.1.1 → 0.1.3

package/dist/index.js

@@ -2,14 +2,19 @@
 /**
 * Environment detection: are we running inside Apps in Toss, or a plain browser?
 *
-* Strategy: feature-sniff `@apps-in-toss/web-framework`. The SDK is declared as
-* an **optional** peer dependency. If it resolves and exposes a known export,
-* we assume we can route calls through it; otherwise we fall back to the
-* browser's native implementation in each shim.
+* Strategy: call the SDK's `getAppsInTossGlobals()` — a synchronous export
+* that returns the runtime's Toss globals (deploymentId, brand name, …)
+* inside the Apps in Toss runtime and throws (RN bridge unavailable)
+* anywhere else. The SDK itself is an **optional** peer dependency; if its
+* module can't be imported we are definitely not inside Toss.
 *
-* We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK
-* function during detection (could prompt permission dialogs, fire analytics,
-* etc.).
+* Just having the SDK module resolvable is not enough — apps can bundle it
+* and still run in a plain browser. We need the bridge probe to confirm.
+*
+* UA sniffing (spoofable) is avoided. We do call `getAppsInTossGlobals`, but
+* that's a constant read from the bridge — no permission dialogs, no
+* analytics fire. In a plain browser the bridge lookup fails fast (sync
+* throw, microsecond-scale), so the startup cost is negligible.
 */
 let cached;
 /**
@@ -39,7 +44,17 @@ async function isTossEnvironment() {
 	if (force === "toss") return true;
 	if (force === "browser") return false;
 	if (cached !== void 0) return cached;
-	cached = typeof (await loadTossSdk())?.getClipboardText === "function";
+	const mod = await loadTossSdk();
+	if (typeof mod?.getAppsInTossGlobals !== "function") {
+		cached = false;
+		return cached;
+	}
+	try {
+		const globals = mod.getAppsInTossGlobals();
+		cached = Boolean(globals) && typeof globals === "object";
+	} catch {
+		cached = false;
+	}
 	return cached;
 }
 /**
@@ -54,6 +69,54 @@ 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 {}
+}
+//#endregion
 //#region src/shims/clipboard.ts
 /**
 * `navigator.clipboard` shim.
@@ -66,7 +129,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`.
@@ -117,34 +180,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
@@ -177,6 +230,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) {
@@ -333,9 +387,8 @@ function installGeolocationShim() {
 	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,
+	host[SNAPSHOT_KEY$1] = installNavigatorProperty("geolocation", {
+		value: createGeolocationShim(original),
 		configurable: true,
 		writable: true
 	});
@@ -345,14 +398,10 @@ 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) restoreNavigatorProperty("geolocation", snapshot);
 	delete host[BACKUP_KEY$1];
+	delete host[SNAPSHOT_KEY$1];
 }
 //#endregion
 //#region src/shims/network.ts
@@ -398,6 +447,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";
@@ -477,35 +528,22 @@ function installNetworkShim() {
 		})();
 		return inflight;
 	}
+	const nativeOnLine = navigator.onLine;
+	const nativeConnection = navigator.connection;
 	refresh();
-	Object.defineProperty(navigator, "onLine", {
+	host[ON_LINE_SNAPSHOT_KEY] = installNavigatorProperty("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);
-			}
+			return nativeOnLine ?? true;
 		}
 	});
-	Object.defineProperty(navigator, "connection", {
+	host[CONNECTION_SNAPSHOT_KEY] = installNavigatorProperty("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);
-				}
-			}
+			if (cachedStatus === null && nativeConnection !== void 0) return nativeConnection;
 			return connection;
 		}
 	});
@@ -515,9 +553,13 @@ 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
@@ -536,6 +578,8 @@ function uninstallNetworkShim() {
 * 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");
+const CAN_SHARE_SNAPSHOT_KEY = Symbol.for("@ait-co/polyfill/canShare.snapshot");
 function buildSdkMessage(data) {
 	const parts = [];
 	if (data?.title != null && data.title !== "") parts.push(data.title);
@@ -587,12 +631,12 @@ function installShareShim() {
 		hadShare: "share" in nav,
 		hadCanShare: "canShare" in nav
 	};
-	Object.defineProperty(navigator, "share", {
+	host[SHARE_SNAPSHOT_KEY] = installNavigatorProperty("share", {
 		value: shareShim,
 		configurable: true,
 		writable: true
 	});
-	Object.defineProperty(navigator, "canShare", {
+	host[CAN_SHARE_SNAPSHOT_KEY] = installNavigatorProperty("canShare", {
 		value: canShareShim,
 		configurable: true,
 		writable: true
@@ -603,20 +647,13 @@ 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 shareSnap = host[SHARE_SNAPSHOT_KEY];
+	if (shareSnap) restoreNavigatorProperty("share", shareSnap);
+	const canShareSnap = host[CAN_SHARE_SNAPSHOT_KEY];
+	if (canShareSnap) restoreNavigatorProperty("canShare", canShareSnap);
 	delete host[SHARE_BACKUP_KEY];
+	delete host[SHARE_SNAPSHOT_KEY];
+	delete host[CAN_SHARE_SNAPSHOT_KEY];
 }
 //#endregion
 //#region src/shims/vibrate.ts
@@ -642,7 +679,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;
@@ -684,10 +721,8 @@ function installVibrateShim() {
 	if (typeof navigator === "undefined") return () => {};
 	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", {
+	host[BACKUP_KEY] = navigator.vibrate?.bind(navigator);
+	host[SNAPSHOT_KEY] = installNavigatorProperty("vibrate", {
 		value: vibrateShim,
 		configurable: true,
 		writable: true
@@ -698,34 +733,31 @@ 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) restoreNavigatorProperty("vibrate", snapshot);
 	delete host[BACKUP_KEY];
-	delete host[HAD_KEY];
+	delete host[SNAPSHOT_KEY];
 }
 //#endregion
 //#region src/index.ts
-const VERSION = "0.1.1";
+const VERSION = "0.1.3";
+const NOOP = () => {};
 /**
-* Install every shim this library ships. Idempotent — safe to call more than
-* once. Returns an uninstall function that restores every original API.
+* Install every shim this library ships, but only if we detect an Apps in
+* Toss runtime. In a plain browser `install()` is a no-op — the browser's
+* native APIs stay untouched.
 *
-* Install order: clipboard → geolocation → share → vibrate → network.
-* `uninstall()` tears them down in the same order (each per-shim uninstall is
-* independent, so order doesn't affect correctness; documented for clarity).
+* Returns a promise that resolves with an uninstall function. If the
+* environment turns out not to be Toss, the uninstall function is a no-op.
 *
-* Not atomic on failure: if a later per-shim install throws (e.g., a consumer
-* has pinned one of the target navigator properties as non-configurable),
-* earlier shims are already installed. Callers should catch and invoke
-* `uninstall()` to roll back.
+* Install order (when active): clipboard → geolocation → share → vibrate →
+* network. Not atomic on failure — if a per-shim install throws (e.g., a
+* consumer pinned a target navigator property as non-configurable), earlier
+* shims are already in place. Callers should catch and invoke the returned
+* uninstall to roll back.
 */
-function install() {
+async function install() {
+	if (!await isTossEnvironment()) return NOOP;
 	const uninstalls = [
 		installClipboardShim(),
 		installGeolocationShim(),