@ait-co/polyfill 0.1.1

package/README.md

@@ -0,0 +1,83 @@
+# @ait-co/polyfill
+
+> 🚧 **Pre-release (0.1.x)** — implemented, pending `sdk-example` integration verification.
+> Part of the unofficial `apps-in-toss-community` project. Not affiliated with Toss.
+> 비공식 커뮤니티 프로젝트입니다. 토스와 제휴하지 않았습니다.
+
+Web standard API polyfill for Apps in Toss mini-apps. Write your mini-app with **standard Web APIs** (`navigator.clipboard`, `navigator.geolocation`, …) and have it transparently work inside Apps in Toss.
+
+앱인토스 미니앱에서 **웹 표준 API를 그대로 사용**해서 개발할 수 있게 해주는 polyfill. 런타임에 앱인토스 환경을 감지해 내부적으로 `@apps-in-toss/web-framework` 호출로 라우팅하고, 그 외 환경(일반 브라우저, 로컬 개발, 테스트)에서는 브라우저의 원본 구현을 그대로 사용합니다 — no-op shim이 아닙니다.
+
+## Install
+
+```sh
+pnpm add @ait-co/polyfill
+```
+
+`@apps-in-toss/web-framework` is an **optional peer dependency**. Apps that only target a pure-web context don't need to install it — the shim falls through to the native browser path.
+
+```sh
+pnpm add @apps-in-toss/web-framework   # only if you also ship a Toss build
+```
+
+## Usage
+
+### Install every shim (recommended)
+
+Call `install()` once at app entry:
+
+```ts
+import { install } from '@ait-co/polyfill';
+
+install();
+
+await navigator.clipboard.writeText('hello');
+```
+
+`install()` is idempotent — calling it again is a no-op. It returns an uninstall function; a top-level `uninstall()` is also exported for convenience.
+
+```ts
+import { install, uninstall } from '@ait-co/polyfill';
+
+const restore = install();
+// ...
+restore(); // or uninstall()
+```
+
+Each shim stashes the original `navigator`/`window` value so `uninstall()` restores it cleanly — useful in tests.
+
+### Subpath imports (bundle-size sensitive)
+
+Pick just the shims you need and install them explicitly:
+
+```ts
+import { installClipboardShim } from '@ait-co/polyfill/clipboard';
+import { isTossEnvironment } from '@ait-co/polyfill/detect';
+
+installClipboardShim();
+```
+
+The package is marked `"sideEffects": false`, so unused shims are dropped by any modern bundler when you use subpath imports.
+
+## Supported APIs
+
+모든 Tier 1 shim이 단위 테스트까지 통과한 상태이고, 실환경 검증(`sdk-example` 통합)이 남아있습니다. 실환경 검증 이후 일부 API 매핑이 조정될 수 있습니다.
+
+| Web standard | SDK counterpart | Landed in |
+|---|---|---|
+| `navigator.clipboard.readText()` / `writeText(text)` | `getClipboardText()` / `setClipboardText(text)` | 0.1.0 |
+| `navigator.geolocation.getCurrentPosition()` | `getCurrentLocation({ accuracy })` | 0.1.1 (pending) |
+| `navigator.geolocation.watchPosition()` / `clearWatch()` | `startUpdateLocation(...)` | 0.1.1 (pending) |
+| `navigator.share({ title, text, url })` | `share({ message })` (concatenates into `message`) | 0.1.1 (pending) |
+| `navigator.vibrate(pattern)` | `generateHapticFeedback(...)` (best-effort, lossy) | 0.1.1 (pending) |
+| `navigator.onLine` / `navigator.connection.effectiveType` | `getNetworkStatus()` (poll on read; no `change` for seed) | 0.1.1 (pending) |
+
+`(pending)` 표시는 해당 행이 아직 npm으로 공개되지 않았다는 뜻입니다. 다음 Version Packages PR이 merge되어 `0.1.1`이 publish되면 이 표시는 제거됩니다.
+
+See [`TODO.md`](./TODO.md) for the full backlog and tiering.
+
+APIs without a reasonable Web standard counterpart (auth, IAP, ads, analytics, Toss-specific environment info) stay in the `@apps-in-toss/web-framework` namespace — polyfill is not the home for "everything the SDK does." Rationale in [`CLAUDE.md`](./CLAUDE.md).
+
+## License
+
+BSD-3-Clause

package/dist/detect.d.ts

@@ -0,0 +1,45 @@
+import * as _$_apps_in_toss_web_framework0 from "@apps-in-toss/web-framework";
+
+//#region src/detect.d.ts
+/**
+ * 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.
+ *
+ * We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK
+ * function during detection (could prompt permission dialogs, fire analytics,
+ * etc.).
+ */
+/**
+ * Reset the cached detection result. Primarily for tests.
+ */
+declare function resetDetection(): void;
+/**
+ * Synchronous read of the cached detection result. Returns:
+ *   - `true` / `false` if an override is active or the async detection has
+ *     already resolved
+ *   - `undefined` if detection hasn't run yet
+ *
+ * Used by spec-sync APIs (e.g. `navigator.canShare`) that can't `await`
+ * detection.
+ */
+declare function isTossEnvironmentCached(): boolean | undefined;
+/**
+ * Returns `true` iff we detect we are running in an environment where the
+ * Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.
+ *
+ * Async because we use dynamic `import()` to probe the optional peer dep
+ * without forcing it into the consumer's bundle.
+ */
+declare function isTossEnvironment(): Promise<boolean>;
+/**
+ * Lazy SDK accessor — returns the module if available, else `null`. Callers
+ * are expected to `await` and null-check. Never throws.
+ */
+declare function loadTossSdk(): Promise<typeof _$_apps_in_toss_web_framework0 | null>;
+//#endregion
+export { isTossEnvironment, isTossEnvironmentCached, loadTossSdk, resetDetection };
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","names":[],"sources":["../src/detect.ts"],"mappings":";;;;;;AAkBA;;;;;AAaA;;;;;AAcA;;iBA3BgB,cAAA,CAAA;;;AA8ChB;;;;;;;iBAjCgB,uBAAA,CAAA;;;;;;;;iBAcM,iBAAA,CAAA,GAAqB,OAAA;;;;;iBAmBrB,WAAA,CAAA,GAAe,OAAA,QAAJ,8BAAA"}

package/dist/detect.js

@@ -0,0 +1,65 @@
+//#region src/detect.ts
+/**
+* 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.
+*
+* We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK
+* function during detection (could prompt permission dialogs, fire analytics,
+* etc.).
+*/
+let cached;
+/**
+* Reset the cached detection result. Primarily for tests.
+*/
+function resetDetection() {
+	cached = void 0;
+}
+/**
+* Synchronous read of the cached detection result. Returns:
+*   - `true` / `false` if an override is active or the async detection has
+*     already resolved
+*   - `undefined` if detection hasn't run yet
+*
+* Used by spec-sync APIs (e.g. `navigator.canShare`) that can't `await`
+* detection.
+*/
+function isTossEnvironmentCached() {
+	const force = globalThis.__AIT_POLYFILL_FORCE__;
+	if (force === "toss") return true;
+	if (force === "browser") return false;
+	return cached;
+}
+/**
+* Returns `true` iff we detect we are running in an environment where the
+* Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.
+*
+* Async because we use dynamic `import()` to probe the optional peer dep
+* without forcing it into the consumer's bundle.
+*/
+async function isTossEnvironment() {
+	const force = globalThis.__AIT_POLYFILL_FORCE__;
+	if (force === "toss") return true;
+	if (force === "browser") return false;
+	if (cached !== void 0) return cached;
+	cached = typeof (await loadTossSdk())?.getClipboardText === "function";
+	return cached;
+}
+/**
+* Lazy SDK accessor — returns the module if available, else `null`. Callers
+* are expected to `await` and null-check. Never throws.
+*/
+async function loadTossSdk() {
+	try {
+		return await import("@apps-in-toss/web-framework");
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { isTossEnvironment, isTossEnvironmentCached, loadTossSdk, resetDetection };
+
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","names":[],"sources":["../src/detect.ts"],"sourcesContent":["/**\n * Environment detection: are we running inside Apps in Toss, or a plain browser?\n *\n * Strategy: feature-sniff `@apps-in-toss/web-framework`. The SDK is declared as\n * an **optional** peer dependency. If it resolves and exposes a known export,\n * we assume we can route calls through it; otherwise we fall back to the\n * browser's native implementation in each shim.\n *\n * We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK\n * function during detection (could prompt permission dialogs, fire analytics,\n * etc.).\n */\n\nlet cached: boolean | undefined;\n\n/**\n * Reset the cached detection result. Primarily for tests.\n */\nexport function resetDetection(): void {\n  cached = undefined;\n}\n\n/**\n * Synchronous read of the cached detection result. Returns:\n *   - `true` / `false` if an override is active or the async detection has\n *     already resolved\n *   - `undefined` if detection hasn't run yet\n *\n * Used by spec-sync APIs (e.g. `navigator.canShare`) that can't `await`\n * detection.\n */\nexport function isTossEnvironmentCached(): boolean | undefined {\n  const force = globalThis.__AIT_POLYFILL_FORCE__;\n  if (force === 'toss') return true;\n  if (force === 'browser') return false;\n  return cached;\n}\n\n/**\n * Returns `true` iff we detect we are running in an environment where the\n * Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.\n *\n * Async because we use dynamic `import()` to probe the optional peer dep\n * without forcing it into the consumer's bundle.\n */\nexport async function isTossEnvironment(): Promise<boolean> {\n  // Override check precedes cache so `devtools` / tests can flip the result\n  // mid-session without a `resetDetection()` call.\n  const force = globalThis.__AIT_POLYFILL_FORCE__;\n  if (force === 'toss') return true;\n  if (force === 'browser') return false;\n\n  if (cached !== undefined) return cached;\n\n  const mod = await loadTossSdk();\n  // Presence of a well-known export is our smoke test.\n  cached = typeof mod?.getClipboardText === 'function';\n  return cached;\n}\n\n/**\n * Lazy SDK accessor — returns the module if available, else `null`. Callers\n * are expected to `await` and null-check. Never throws.\n */\nexport async function loadTossSdk(): Promise<typeof import('@apps-in-toss/web-framework') | null> {\n  try {\n    return await import('@apps-in-toss/web-framework');\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,IAAI;;;;AAKJ,SAAgB,iBAAuB;AACrC,UAAS,KAAA;;;;;;;;;;;AAYX,SAAgB,0BAA+C;CAC7D,MAAM,QAAQ,WAAW;AACzB,KAAI,UAAU,OAAQ,QAAO;AAC7B,KAAI,UAAU,UAAW,QAAO;AAChC,QAAO;;;;;;;;;AAUT,eAAsB,oBAAsC;CAG1D,MAAM,QAAQ,WAAW;AACzB,KAAI,UAAU,OAAQ,QAAO;AAC7B,KAAI,UAAU,UAAW,QAAO;AAEhC,KAAI,WAAW,KAAA,EAAW,QAAO;AAIjC,UAAS,QAFG,MAAM,aAAa,GAEV,qBAAqB;AAC1C,QAAO;;;;;;AAOT,eAAsB,cAA4E;AAChG,KAAI;AACF,SAAO,MAAM,OAAO;SACd;AACN,SAAO"}

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import * as _$_apps_in_toss_web_framework0 from "@apps-in-toss/web-framework";
+
+//#region src/detect.d.ts
+/**
+ * Synchronous read of the cached detection result. Returns:
+ *   - `true` / `false` if an override is active or the async detection has
+ *     already resolved
+ *   - `undefined` if detection hasn't run yet
+ *
+ * Used by spec-sync APIs (e.g. `navigator.canShare`) that can't `await`
+ * detection.
+ */
+declare function isTossEnvironmentCached(): boolean | undefined;
+/**
+ * Returns `true` iff we detect we are running in an environment where the
+ * Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.
+ *
+ * Async because we use dynamic `import()` to probe the optional peer dep
+ * without forcing it into the consumer's bundle.
+ */
+declare function isTossEnvironment(): Promise<boolean>;
+/**
+ * Lazy SDK accessor — returns the module if available, else `null`. Callers
+ * are expected to `await` and null-check. Never throws.
+ */
+declare function loadTossSdk(): Promise<typeof _$_apps_in_toss_web_framework0 | null>;
+//#endregion
+//#region src/shims/clipboard.d.ts
+/**
+ * `navigator.clipboard` shim.
+ *
+ * Inside Apps in Toss → routes `readText` / `writeText` through the SDK
+ * (`getClipboardText` / `setClipboardText`).
+ *
+ * Outside Apps in Toss → defers to the browser's native `navigator.clipboard`.
+ * If the browser doesn't implement it, the standard `TypeError` / `DOMException`
+ * surfaces unchanged — we don't paper over missing support.
+ */
+/**
+ * Install the `navigator.clipboard` shim.
+ *
+ * @returns an uninstall function that restores the original `navigator.clipboard`.
+ *          Calling install twice without uninstalling is a no-op on the second call
+ *          and returns the same uninstall function.
+ */
+declare function installClipboardShim(): () => void;
+/**
+ * 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.
+ */
+declare function uninstallClipboardShim(): void;
+//#endregion
+//#region src/shims/geolocation.d.ts
+/**
+ * `navigator.geolocation` shim.
+ *
+ * Inside Apps in Toss → routes through the SDK:
+ *   - `getCurrentPosition` → `getCurrentLocation({ accuracy })`
+ *   - `watchPosition` / `clearWatch` → `startUpdateLocation({ onEvent, onError, options })`
+ *
+ * Outside Apps in Toss → defers to the browser's native `navigator.geolocation`.
+ * If neither is available, the error callback receives a `GeolocationPositionError`.
+ *
+ * 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
+ *     `true → Accuracy.High (4, "~10m")` and `false → Accuracy.Balanced (3)`.
+ *     `Highest (5)` / `BestForNavigation (6)` are available but carry a battery
+ *     cost that's rarely what mini-apps want; consumers who need them should
+ *     call the SDK directly.
+ *   - SDK coords lack `speed`; we surface `null` (per the W3C spec when unknown).
+ *   - SDK `startUpdateLocation` returns an `unsubscribe` fn; we wrap it behind
+ *     a numeric watch id so `clearWatch(id)` behaves like the standard.
+ *
+ * Caveat: watch ids reset whenever the shim is uninstalled and reinstalled;
+ * they are not stable across such cycles. Ids obtained before uninstall
+ * cannot be cleared after uninstall — `clearWatch(id)` on the restored native
+ * `navigator.geolocation` uses a different id space, so the SDK subscription
+ * leaks. Consumers should `clearWatch` all outstanding ids before calling
+ * `uninstall()`.
+ */
+declare function installGeolocationShim(): () => void;
+declare function uninstallGeolocationShim(): void;
+//#endregion
+//#region src/shims/network.d.ts
+/**
+ * `navigator.onLine` + `navigator.connection` shim.
+ *
+ * Inside Apps in Toss → seeded from SDK `getNetworkStatus()` on install and
+ * refreshed on read (throttled):
+ *   - `'OFFLINE'`   → `onLine = false`
+ *   - `'WIFI'`      → `onLine = true`, `effectiveType = '4g'` (no web wifi value)
+ *   - `'2G'/'3G'/'4G'/'5G'` → `onLine = true`, `effectiveType = <lowercased>`
+ *   - `'WWAN'/'UNKNOWN'`    → `onLine = true`, `effectiveType = '4g'` (best guess)
+ *
+ * Outside Apps in Toss → both `navigator.onLine` and `navigator.connection`
+ * read through to the native value. Install installs own-instance getters
+ * that consult the Toss-seeded cache first; when the cache is empty (which
+ * it always is in browser mode), the getter temporarily removes its own
+ * shadow, reads the prototype value, and reinstates the shadow.
+ *
+ * Uninstall `delete`s the instance-level override so the prototype descriptor
+ * (where `onLine` and `connection` actually live in real browsers) becomes
+ * visible again. We never mutate the prototype — doing so would throw in
+ * browsers where the descriptor is non-configurable.
+ *
+ * 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
+ * unless the shim observes a real status transition. Synthesising richer
+ * events via polling is tracked in TODO.md.
+ *
+ * Lifecycle: `navigator.connection` is a ShimConnection instance that lives in
+ * the install closure. On uninstall the instance-level override is removed,
+ * but listeners the consumer attached to the old instance stay bound to that
+ * (now-orphan) object and will not see events from a subsequent install.
+ * Consumers should re-attach listeners after each install.
+ *
+ * Seed-boundary race: in Toss mode, reads before the install-time SDK seed
+ * completes fall through to the native `navigator.connection`. After the seed
+ * lands, subsequent reads return the shim's ShimConnection. Consumers that
+ * specifically need the ShimConnection instance (e.g., to attach `change`
+ * listeners that fire on Toss network transitions) should wait a microtask
+ * after `install()` before attaching listeners, or accept that pre-seed
+ * reads may return the native object.
+ */
+declare function installNetworkShim(): () => void;
+declare function uninstallNetworkShim(): void;
+//#endregion
+//#region src/shims/share.d.ts
+/**
+ * `navigator.share` shim.
+ *
+ * Inside Apps in Toss → routes through SDK `share({ message })`. The SDK only
+ * accepts a single `message` string, so we concatenate `title`, `text`, and
+ * `url` with newline separators (skipping missing/empty values).
+ *
+ * Outside Apps in Toss → defers to the browser's native `navigator.share`, or
+ * throws `NotSupportedError` if unavailable.
+ *
+ * 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).
+ */
+declare function installShareShim(): () => void;
+declare function uninstallShareShim(): void;
+//#endregion
+//#region src/shims/vibrate.d.ts
+/**
+ * `navigator.vibrate` shim.
+ *
+ * Inside Apps in Toss → best-effort mapping to SDK `generateHapticFeedback`:
+ *   - `vibrate(0)` → no-op (web standard: cancels pending vibration)
+ *   - `vibrate(number)`: short (< 40ms) → `tickWeak`, long (≥ 40ms) → `basicMedium`
+ *   - `vibrate(number[])`: iterate "on" segments (even indices) as `tap` pulses
+ *
+ * Outside Apps in Toss → defers to the browser's native `navigator.vibrate`,
+ * or returns `false` when unavailable (matches the spec — browsers that don't
+ * support vibration simply return `false`).
+ *
+ * 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
+ *     reproduce exact patterns.
+ *   - Arrays are fired sequentially via `setTimeout`; gaps between pulses are
+ *     honoured only as "time until the next tap", not as silent-vs-vibrating.
+ *   - `vibrate` is spec'd as **synchronous**; the SDK call is async. We return
+ *     `true` immediately (fire-and-forget). Errors from the SDK are swallowed.
+ */
+declare function installVibrateShim(): () => void;
+declare function uninstallVibrateShim(): void;
+//#endregion
+//#region src/index.d.ts
+declare const VERSION: string;
+/**
+ * Install every shim this library ships. Idempotent — safe to call more than
+ * once. Returns an uninstall function that restores every original API.
+ *
+ * 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).
+ *
+ * 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.
+ */
+declare function install(): () => void;
+/**
+ * Uninstall every shim installed by `install()`. Safe to call when no shim is
+ * installed — each installer's uninstall is a no-op in that case.
+ */
+declare function uninstall(): void;
+//#endregion
+export { VERSION, install, installClipboardShim, installGeolocationShim, installNetworkShim, installShareShim, installVibrateShim, isTossEnvironment, isTossEnvironmentCached, loadTossSdk, uninstall, uninstallClipboardShim, uninstallGeolocationShim, uninstallNetworkShim, uninstallShareShim, uninstallVibrateShim };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/detect.ts","../src/shims/clipboard.ts","../src/shims/geolocation.ts","../src/shims/network.ts","../src/shims/share.ts","../src/shims/vibrate.ts","../src/index.ts"],"mappings":";;;;;;;;ACyHA;;;;iBD1FgB,uBAAA,CAAA;AC6HhB;;;;;;;AAAA,iBD/GsB,iBAAA,CAAA,GAAqB,OAAA;AEyN3C;;;;AAAA,iBFtMsB,WAAA,CAAA,GAAe,OAAA,QAAJ,8BAAA;;;;;;AAjCjC;;;;;AAcA;;;;;AAmBA;;;;iBCyDgB,oBAAA,CAAA;;;;AAAhB;;iBAmCgB,sBAAA,CAAA;;;;;;AD7HhB;;;;;AAcA;;;;;AAmBA;;;;;;;;ACyDA;;;;;AAmCA;;iBC0GgB,sBAAA,CAAA;AAAA,iBAuBA,wBAAA,CAAA;;;;;;AF9PhB;;;;;AAcA;;;;;AAmBA;;;;;;;;ACyDA;;;;;AAmCA;;;;;;;;AC0GA;;;;;AAuBA;;iBCzJgB,kBAAA,CAAA;AAAA,iBAqGA,oBAAA,CAAA;;;;;;AH1MhB;;;;;AAcA;;;;;AAmBA;iBI2DgB,gBAAA,CAAA;AAAA,iBAsCA,kBAAA,CAAA;;;;;;AJlIhB;;;;;AAcA;;;;;AAmBA;;;;;;;;iBK2CgB,kBAAA,CAAA;AAAA,iBAuBA,oBAAA,CAAA;;;cCzGH,OAAA;;;;ALgGb;;;;;AAmCA;;;;;iBKpHgB,OAAA,CAAA;;;AJ8NhB;;iBI7MgB,SAAA,CAAA"}