@ait-co/polyfill 0.1.5 → 0.1.7

package/README.md

@@ -1,5 +1,7 @@
 # @ait-co/polyfill
 
+![@ait-co/polyfill — 표준 Web API로 미니앱을 작성](./assets/og/image.png)
+
 > Part of the unofficial `apps-in-toss-community` project. Not affiliated with Toss.
 > 비공식 커뮤니티 프로젝트입니다. 토스와 제휴하지 않았습니다.
 
@@ -19,6 +21,8 @@ pnpm add @ait-co/polyfill
 pnpm add @apps-in-toss/web-framework   # only if you also ship a Toss build
 ```
 
+The package ships dual ESM + CJS builds, so `require('@ait-co/polyfill/auto')` works in CommonJS hosts too.
+
 ## Usage
 
 ### Just add the dep (recommended)
@@ -60,7 +64,7 @@ import { installClipboardShim } from '@ait-co/polyfill/clipboard';
 installClipboardShim(); // installs unconditionally — gate with detect.ts if you want Toss-only
 ```
 
-The package is marked `sideEffects: ["./dist/auto.js"]`, so only the `/auto` entry is kept when tree-shaking; everything else is drop-if-unused.
+The package is marked `sideEffects: ["./dist/auto.js", "./dist/auto.cjs"]`, so only the `/auto` entry (in either format) is kept when tree-shaking; everything else is drop-if-unused.
 
 ## Environment detection
 
@@ -78,13 +82,61 @@ Tier 1 — all shipped; paired SDK routing is live when inside Apps in Toss.
 | `navigator.geolocation.getCurrentPosition()` | `getCurrentLocation({ accuracy })` | 0.1.1 |
 | `navigator.geolocation.watchPosition()` / `clearWatch()` | `startUpdateLocation(...)` | 0.1.1 |
 | `navigator.share({ title, text, url })` | `share({ message })` (concatenates into `message`) | 0.1.1 |
-| `navigator.vibrate(pattern)` | `generateHapticFeedback(...)` (best-effort, lossy) | 0.1.1 |
+| `navigator.vibrate(pattern)` | `generateHapticFeedback(...)` (best-effort, lossy; see below) | 0.1.1 |
 | `navigator.onLine` / `navigator.connection.effectiveType` | `getNetworkStatus()` (poll on read; no `change` for seed) | 0.1.1 |
 
-See [`TODO.md`](./TODO.md) for the full backlog and tiering.
+### `navigator.vibrate` mapping
+
+The Web `vibrate` spec only takes durations; the SDK's `generateHapticFeedback` is qualitative. Single-duration calls bucket like this inside Apps in Toss:
+
+| Input | SDK haptic |
+|---|---|
+| `vibrate(0)` / `vibrate([])` | no-op (cancels native pending vibration) |
+| `vibrate(1..20)` | `tickWeak` |
+| `vibrate(21..45)` | `tickMedium` |
+| `vibrate(>=46)` | `basicMedium` |
+| `vibrate([on, off, on, off, ...])` | each non-zero "on" slot fires `tap`, with `setTimeout` honouring the gaps |
+
+Length-only mapping cannot recover semantic intent (success vs. error vs. warning). When the caller knows what the haptic *means*, prefer the helper:
+
+```ts
+import { vibrateSemantic } from '@ait-co/polyfill/vibrate-semantic';
+
+vibrateSemantic('success');   // → SDK 'success'
+vibrateSemantic('error');     // → SDK 'error'
+vibrateSemantic('warning');   // → SDK 'tickMedium' (no direct variant)
+vibrateSemantic('selection'); // → SDK 'tickWeak'  (no direct variant)
+```
+
+The helper does not install anything and does not touch `navigator.vibrate`. It also re-exports from the package root (`import { vibrateSemantic } from '@ait-co/polyfill'`) for convenience, but the sub-path is the tree-shake-friendly form.
+
+Outside Apps in Toss, `vibrateSemantic` falls back to a short `navigator.vibrate(...)` so the user still gets *some* feedback. `navigator.vibrate(...)` keeps its standard signature in every environment — the helper is the only way to pass intent.
+
+See [`INTEGRATION.md`](./INTEGRATION.md) for an adoption guide (Vite + React
+snippet, recommended pairing with `@ait-co/devtools`, per-API one-liners).
 
 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).
 
+## Development
+
+```sh
+pnpm install
+pnpm test
+pnpm lint
+pnpm typecheck
+pnpm build
+```
+
+### Pre-commit hook
+
+Optional but recommended. After cloning, activate the standard pre-commit hook (runs `biome check` on staged files):
+
+```sh
+git config core.hooksPath .githooks
+```
+
+This is a developer convenience for fast feedback before push. CI runs the same checks as the enforcement layer, so contributors who don't activate the hook will still see lint failures in their PR.
+
 ## License
 
 BSD-3-Clause