use-zoom-pinch 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+For pre-1.0 releases (`0.x.y`), minor version bumps may include breaking changes.
+
+## [0.4.0] — 2026-07-13
+
+### Breaking
+
+These changes affect `resetView`, the keyboard `0` key, and `doubleTap` modes
+`"reset"` / `"toggle"`. Apps that relied on the previous hardcoded reset target
+should adjust.
+
+- **`resetView()` now returns to `initialViewState`** instead of the hardcoded
+  `{ x: 0, y: 0, zoom: 1, rotation: 0 }`. If `initialViewState` is not provided,
+  the default `{ 0, 0, 1 }` is still used.
+- **Keyboard `0`** resets to `initialViewState` (was: hardcoded reset).
+- **`doubleTap` `"reset"` and `"toggle"`** modes animate back to `initialViewState`,
+  preserving the initial `x` / `y` / `zoom` / `rotation`. Previously they reset to
+  `{ 0, 0, 1 }` and silently dropped rotation.
+
+### Added
+
+- **`setView(view, { skipConstraints: true })`** — bypasses bounds clamping, axis
+  locking, and snap-to-grid for precise programmatic positioning (even outside
+  bounds). Only affects `setView`; gestures are always constrained.
+- **`activationKeys.rotate`** is now honored (previously declared in the type but
+  ignored). Rotation via touch pinch, the Safari `GestureEvent`, and keyboard
+  `[` / `]` is gated by the configured activation key.
+- **`cursor.zooming`** is now applied while wheel-zooming, and the cursor restores
+  to `idle` once the debounced zoom-end fires (previously the option was unused).
+- **Exported math helpers** `clamp`, `distance`, `angleBetween` for manual
+  coordinate conversion.
+- **Debounced `ResizeObserver`** (150ms) for `fitToContent` auto-resize, so window
+  resize no longer yanks the viewport on every intermediate frame.
+- **Unified `onTransformEnd`** now fires after `doubleTap` and after **inertia
+  fully settles** (previously it fired only after pan/zoom/pinch end, and during
+  inertia it fired too early at pointer-up).
+
+### Fixed
+
+- **Wheel `preventDefault` ordering** — the wheel handler no longer calls
+  `preventDefault()` when it will not handle the event. Previously, with
+  `activationKeys.zoom` set but the key not held, or with the relevant gesture
+  disabled, the hook still suppressed the browser's native wheel behavior
+  (page scroll, ctrl+wheel page zoom).
+- **`animateTo` with `duration <= 0`** no longer poisons the view with `NaN`.
+  It now jumps to the target immediately.
+- **`activationKeys` no longer "stick"** when the user alt-tabs while holding a
+  modifier — pressed keys are cleared on `window blur` and `visibilitychange`.
+- **`contextmenu` is suppressed** when `panButton: 2` (right mouse), making
+  right-button panning usable.
+
+### Tests
+
+- Added `src/__tests__/bugfixes.test.ts` with 27 tests covering all fixes above,
+  including wheel `preventDefault` ordering, the duration guard, `skipConstraints`,
+  blur-clear, and `onTransformEnd` consistency after double-tap and inertia.
+- Fixed a dead test for rotation snap (it had no assertions); replaced with a real
+  pinch-gesture-based assertion.
+- Updated existing tests to match the new `resetView` / `initialViewState` semantics.
+
+## [0.3.0]
+
+### Added
+
+- Bounds bounce (rubber-band overscroll with snap-back), axis locking, cursor
+  management, `wheelMode`, rotation snap levels, activation keys, `onTransformEnd`,
+  navigation helpers (`panTo`, `panBy`, `zoomTo`, `fitToRect`), double-tap zoom,
+  inertia, animated transitions, controlled mode.
+- Test coverage thresholds and `eslint-plugin-react-hooks`.
+- README improvements and bundle-size badge.
+
+### Fixed
+
+- Initial release bug fixes.
+
+## [0.1.0]
+
+- Initial release: `useZoomPinch` React hook.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 nemezzizz
+Copyright (c) 2026 NemeZZiZZ
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,46 @@
 # useZoomPinch
 
-Lightweight React hook for **pan**, **pinch-to-zoom**, and **scroll zoom** with trackpad and touch support. Zero dependencies beyond React.
+Lightweight React hook for **pan**, **pinch-to-zoom**, **rotation**, and **scroll zoom** with trackpad and touch support. Zero dependencies beyond React.
+
+[![npm](https://img.shields.io/npm/v/use-zoom-pinch)](https://www.npmjs.com/package/use-zoom-pinch)
+[![CI](https://github.com/NemeZZiZZ/use-zoom-pinch/actions/workflows/ci.yml/badge.svg)](https://github.com/NemeZZiZZ/use-zoom-pinch/actions/workflows/ci.yml)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/use-zoom-pinch)](https://bundlephobia.com/package/use-zoom-pinch)
 
 [**Live Demo**](https://nemezzizz.github.io/use-zoom-pinch/)
+[**Changelog**](./CHANGELOG.md)
 
 ## Features
 
 - **Scroll to pan** — mouse wheel and trackpad two-finger scroll
 - **Pinch to zoom** — trackpad pinch (via `ctrlKey` + wheel) and multi-touch pinch on mobile
 - **Pointer drag** — mouse drag and single-touch drag for panning
+- **Rotation** — two-finger rotation with `rotateTo`/`rotateBy` methods
+- **Gesture toggles** — enable/disable pan, zoom, and rotate independently
+- **Double-tap zoom** — configurable toggle/zoomIn/reset modes
+- **Inertia** — momentum-based pan with configurable friction
+- **Animated transitions** — smooth easing for programmatic view changes
+- **Bounds** — constrain panning within rectangular limits
+- **Keyboard navigation** — arrow keys, +/-, rotation with [ / ]
+- **Coordinate conversion** — `screenToContent` / `contentToScreen`
+- **Zoom snap levels** — snap to predefined zoom levels on gesture end
+- **Snap to grid** — snap positions to a grid (continuous or on end)
+- **Auto-fit content** — `fitToContent` with ResizeObserver auto-resize
+- **Configurable pan button** — left, middle, or right mouse button
+- **Bounce at bounds** — rubber-band overscroll with snap-back animation
+- **Axis locking** — restrict pan to horizontal or vertical only
+- **Cursor management** — automatic grab/grabbing cursor on drag
+- **Wheel mode** — swap default: wheel zooms, ctrl+wheel pans
+- **Rotation constraints** — min/max angle and rotation snap levels
+- **Activation keys** — require Shift/Alt/Ctrl for specific gestures
+- **`onTransformEnd`** — unified callback after any gesture ends
+- **Navigation** — `panTo`, `panBy`, `zoomTo`, `fitToRect` for precise viewport control
 - **Controlled & uncontrolled** modes
+- **Granular events** — `onPanStart/End`, `onZoomStart/End`, `onPinchStart/End`, `onRotateStart/End`
+- **Event filtering** — `shouldHandleEvent` to exclude interactive elements
 - **Stable listeners** — config changes don't re-register event listeners
 - **TypeScript-first** with full type exports
 - **Tree-shakeable** ESM + CJS dual build
-- **~2 KB** minified + gzipped
+- **~5.8 KB** minified + gzipped
 
 ## Installation
 
@@ -59,7 +86,7 @@ function ControlledCanvas() {
   const containerRef = useRef<HTMLDivElement>(null)
   const [viewState, setViewState] = useState<ViewState>({ x: 0, y: 0, zoom: 1 })
 
-  const { view, centerZoom, resetView } = useZoomPinch({
+  const { view, zoomIn, zoomOut, resetView } = useZoomPinch({
     containerRef,
     viewState,
     onViewStateChange: setViewState,
@@ -67,9 +94,9 @@ function ControlledCanvas() {
 
   return (
     <div>
-      <button onClick={() => centerZoom(view.zoom * 1.5)}>Zoom In</button>
-      <button onClick={() => centerZoom(view.zoom / 1.5)}>Zoom Out</button>
-      <button onClick={resetView}>Reset</button>
+      <button onClick={() => zoomIn(1.5, { animate: true })}>Zoom In</button>
+      <button onClick={() => zoomOut(1.5, { animate: true })}>Zoom Out</button>
+      <button onClick={() => resetView({ animate: true })}>Reset</button>
 
       <div
         ref={containerRef}
@@ -89,43 +116,463 @@ function ControlledCanvas() {
 }
 ```
 
+## Animated Transitions
+
+All programmatic methods accept an optional `AnimationOptions` parameter:
+
+```tsx
+const {
+  setView,
+  centerZoom,
+  resetView,
+  zoomIn,
+  zoomOut,
+  zoomToElement,
+  panTo,
+  panBy,
+  zoomTo,
+  fitToRect,
+} = useZoomPinch({
+  containerRef,
+})
+
+// Instant (default, backward-compatible)
+setView({ x: 100, y: 200, zoom: 2 })
+
+// Animated
+setView({ x: 100, y: 200, zoom: 2 }, { animate: true, duration: 300 })
+
+// Skip bounds/axis/snap constraints (precise positioning even outside bounds)
+setView({ x: 1000, y: 1000, zoom: 2 }, { skipConstraints: true })
+
+// With custom easing
+import { easeInOut } from "use-zoom-pinch"
+resetView({ animate: true, duration: 500, easing: easeInOut })
+
+// Zoom to a specific element
+const elRef = useRef<HTMLDivElement>(null)
+zoomToElement(elRef.current!, 2, { animate: true })
+```
+
+### Built-in Easings
+
+- `linear` — constant speed
+- `easeOut` — fast start, slow end (default)
+- `easeInOut` — slow start, fast middle, slow end
+
+### Skipping Constraints
+
+`setView` normally applies bounds clamping, axis locking, and snap-to-grid. Pass `skipConstraints: true` to bypass them when you need precise programmatic positioning (even outside bounds):
+
+```tsx
+setView({ x: 9999, y: 9999, zoom: 2 }, { skipConstraints: true })
+```
+
+### Exported Helpers
+
+The library also exports a few pure math helpers for manual coordinate work:
+
+```ts
+import { clamp, distance, angleBetween } from "use-zoom-pinch"
+
+clamp(15, 0, 10) // 10
+distance(0, 0, 3, 4) // 5
+angleBetween(0, 0, 0, 10) // 90 (degrees)
+```
+
+## Navigation
+
+```tsx
+const { panTo, panBy, zoomTo, fitToRect } = useZoomPinch({ containerRef })
+
+// Center on a point in content space
+panTo(500, 300, { animate: true })
+
+// Shift viewport by 100px right, 50px down (screen-space delta)
+panBy(100, 50)
+
+// Zoom to 3x centered on a content-space point
+zoomTo(3, { x: 500, y: 300 }, { animate: true })
+
+// Fit a region into view with padding
+fitToRect({ x: 100, y: 100, width: 400, height: 300 }, { animate: true, padding: 20 })
+```
+
+## Rotation
+
+Two-finger rotation is detected during pinch gestures. Disabled by default — enable via `gestures`:
+
+```tsx
+const { view, rotateTo, rotateBy } = useZoomPinch({
+  containerRef,
+  gestures: { rotate: true },
+})
+
+// Apply with CSS:
+// transform: `translate(${view.x}px, ${view.y}px) scale(${view.zoom}) rotate(${view.rotation ?? 0}deg)`
+
+// Programmatic rotation
+rotateTo(45, { animate: true })
+rotateBy(90, { animate: true })
+```
+
+## Gesture Toggles
+
+Enable or disable individual gesture types:
+
+```tsx
+// Only zoom, no pan or rotate
+useZoomPinch({ containerRef, gestures: { pan: false, zoom: true, rotate: false } })
+
+// Only rotate (e.g. image rotation tool)
+useZoomPinch({ containerRef, gestures: { pan: false, zoom: false, rotate: true } })
+
+// All gestures (pan + zoom + rotate)
+useZoomPinch({ containerRef, gestures: { rotate: true } })
+```
+
+Imperative methods (`setView`, `panTo`, `rotateTo`, etc.) always work regardless of gesture toggles.
+
+## Double-Tap Zoom
+
+Double-tap (or double-click) zooms to the tap point. Enabled by default in `toggle` mode.
+
+```tsx
+// Default: toggle between 1x and 2x zoom
+useZoomPinch({ containerRef })
+
+// Customize behavior
+useZoomPinch({
+  containerRef,
+  doubleTap: { mode: "zoomIn", step: 3 }, // always zoom in by 3x
+})
+
+// Disable double-tap
+useZoomPinch({ containerRef, doubleTap: false })
+```
+
+### Modes
+
+- `"toggle"` (default) — zoom in if at 1x, reset if zoomed in
+- `"zoomIn"` — always zoom in by `step`
+- `"reset"` — always reset to `{ x: 0, y: 0, zoom: 1 }`
+
+## Inertia
+
+Pan with momentum after releasing the pointer. Enabled by default.
+
+```tsx
+// Default: friction 0.92
+useZoomPinch({ containerRef })
+
+// Custom friction (lower = more friction, faster stop)
+useZoomPinch({ containerRef, inertia: { friction: 0.85 } })
+
+// Disable inertia
+useZoomPinch({ containerRef, inertia: false })
+```
+
+## Event Filtering
+
+Exclude interactive elements (buttons, inputs) from gesture handling:
+
+```tsx
+useZoomPinch({
+  containerRef,
+  shouldHandleEvent: (e) => !(e.target as HTMLElement).closest(".no-pan"),
+})
+```
+
+## Granular Events
+
+```tsx
+useZoomPinch({
+  containerRef,
+  onPanStart: (view) => console.log("Pan started", view),
+  onPanEnd: (view) => console.log("Pan ended", view),
+  onZoomStart: (view) => console.log("Zoom started", view),
+  onZoomEnd: (view) => console.log("Zoom ended", view),
+  onPinchStart: (view) => console.log("Pinch started", view),
+  onPinchEnd: (view) => console.log("Pinch ended", view),
+  onRotateStart: (view) => console.log("Rotate started", view),
+  onRotateEnd: (view) => console.log("Rotate ended", view),
+})
+```
+
+## Bounds
+
+Constrain panning within rectangular limits:
+
+```tsx
+useZoomPinch({
+  containerRef,
+  bounds: { minX: -500, maxX: 500, minY: -300, maxY: 300 },
+})
+```
+
+## Keyboard Navigation
+
+Enable keyboard controls with arrow keys, zoom (+/-), reset (0), and rotation ([ / ]):
+
+```tsx
+// Enable with defaults (panStep: 50, zoomStep: 1.5, rotateStep: 15)
+useZoomPinch({ containerRef, keyboard: true })
+
+// Custom steps
+useZoomPinch({
+  containerRef,
+  keyboard: { enabled: true, panStep: 100, zoomStep: 2 },
+})
+```
+
+## Coordinate Conversion
+
+Convert between screen and content coordinates:
+
+```tsx
+const { screenToContent, contentToScreen } = useZoomPinch({ containerRef })
+
+// Map a click to content space
+const handleClick = (e: MouseEvent) => {
+  const pos = screenToContent(e.clientX, e.clientY)
+  console.log("Clicked at content position:", pos)
+}
+
+// Position a tooltip over content
+const screenPos = contentToScreen(itemX, itemY)
+```
+
+## Zoom Snap Levels
+
+Snap zoom to predefined levels on gesture end:
+
+```tsx
+useZoomPinch({
+  containerRef,
+  zoomSnapLevels: [0.5, 1, 2, 4],
+})
+```
+
+## Snap to Grid
+
+Snap pan position to a grid:
+
+```tsx
+// Snap on gesture end (with animation)
+useZoomPinch({ containerRef, snapToGrid: { size: 50 } })
+
+// Snap continuously during gestures
+useZoomPinch({ containerRef, snapToGrid: { size: 50, mode: "always" } })
+```
+
+## Fit to Content
+
+Auto-fit content to container on mount and resize:
+
+```tsx
+const { fitToContent } = useZoomPinch({
+  containerRef,
+  contentRect: { width: 1920, height: 1080 }, // auto-fits on mount + resize
+})
+
+// Manual fit with padding
+fitToContent({ animate: true, padding: 20 })
+```
+
+## Pan Button
+
+Configure which mouse button triggers panning:
+
+```tsx
+// Use middle mouse button for pan (frees left click for selection)
+useZoomPinch({ containerRef, panButton: 1 })
+```
+
 ## API
 
 ### `useZoomPinch(options)`
 
 #### Options
 
-| Option              | Type                             | Default                   | Description                         |
-| ------------------- | -------------------------------- | ------------------------- | ----------------------------------- |
-| `containerRef`      | `RefObject<HTMLElement \| null>` | _required_                | Ref to the container element        |
-| `minScale`          | `number`                         | `0.1`                     | Minimum zoom level                  |
-| `maxScale`          | `number`                         | `50`                      | Maximum zoom level                  |
-| `panSpeed`          | `number`                         | `1`                       | Pan speed multiplier (mouse wheel)  |
-| `zoomSpeed`         | `number`                         | `1`                       | Zoom speed multiplier (mouse wheel) |
-| `initialViewState`  | `ViewState`                      | `{ x: 0, y: 0, zoom: 1 }` | Initial view for uncontrolled mode  |
-| `viewState`         | `ViewState`                      | —                         | Controlled view state               |
-| `onViewStateChange` | `(view: ViewState) => void`      | —                         | Callback on view change             |
-| `enabled`           | `boolean`                        | `true`                    | Enable/disable gesture handling     |
+| Option              | Type                             | Default                                    | Description                                      |
+| ------------------- | -------------------------------- | ------------------------------------------ | ------------------------------------------------ |
+| `containerRef`      | `RefObject<HTMLElement \| null>` | _required_                                 | Ref to the container element                     |
+| `minScale`          | `number`                         | `0.1`                                      | Minimum zoom level                               |
+| `maxScale`          | `number`                         | `50`                                       | Maximum zoom level                               |
+| `panSpeed`          | `number`                         | `1`                                        | Pan speed multiplier (mouse wheel)               |
+| `zoomSpeed`         | `number`                         | `1`                                        | Zoom speed multiplier (mouse wheel)              |
+| `initialViewState`  | `ViewState`                      | `{ x: 0, y: 0, zoom: 1 }`                  | Initial view for uncontrolled mode               |
+| `viewState`         | `ViewState`                      | —                                          | Controlled view state                            |
+| `onViewStateChange` | `(view: ViewState) => void`      | —                                          | Callback on view change                          |
+| `enabled`           | `boolean`                        | `true`                                     | Enable/disable gesture handling                  |
+| `gestures`          | `GesturesOptions`                | `{ pan: true, zoom: true, rotate: false }` | Toggle individual gesture types                  |
+| `panButton`         | `0 \| 1 \| 2`                    | `0`                                        | Mouse button for pan (0=left, 1=middle, 2=right) |
+| `bounds`            | `BoundsOptions`                  | —                                          | Constrain panning within bounds                  |
+| `keyboard`          | `KeyboardOptions \| boolean`     | `false`                                    | Keyboard navigation (pass `true` for defaults)   |
+| `zoomSnapLevels`    | `number[]`                       | —                                          | Snap zoom to nearest level on gesture end        |
+| `snapToGrid`        | `SnapToGridOptions \| false`     | `false`                                    | Snap position to grid                            |
+| `contentRect`       | `{ width; height }`              | —                                          | Content size for `fitToContent` + auto-fit       |
+| `rotation`          | `RotationOptions`                | —                                          | Min/max angle and rotation snap levels           |
+| `wheelMode`         | `"pan" \| "zoom"`                | `"pan"`                                    | Default wheel behavior                           |
+| `cursor`            | `CursorOptions \| false`         | enabled                                    | Auto cursor (grab/grabbing). `false` to disable  |
+| `axis`              | `"x" \| "y"`                     | —                                          | Restrict gestures to a single axis               |
+| `activationKeys`    | `ActivationKeyOptions`           | —                                          | Require key held for specific gestures           |
+| `shouldHandleEvent` | `(event) => boolean`             | —                                          | Filter which events are handled                  |
+| `doubleTap`         | `DoubleTapOptions \| false`      | `{ mode: "toggle", step: 2 }`              | Double-tap zoom config, or `false` to disable    |
+| `inertia`           | `InertiaOptions \| false`        | `{ friction: 0.92 }`                       | Pan inertia config, or `false` to disable        |
+| `onPanStart`        | `(view: ViewState) => void`      | —                                          | Fired when drag starts                           |
+| `onPanEnd`          | `(view: ViewState) => void`      | —                                          | Fired when drag ends                             |
+| `onZoomStart`       | `(view: ViewState) => void`      | —                                          | Fired when wheel zoom starts                     |
+| `onZoomEnd`         | `(view: ViewState) => void`      | —                                          | Fired when wheel zoom ends (150ms debounce)      |
+| `onPinchStart`      | `(view: ViewState) => void`      | —                                          | Fired when pinch starts                          |
+| `onPinchEnd`        | `(view: ViewState) => void`      | —                                          | Fired when pinch ends                            |
+| `onRotateStart`     | `(view: ViewState) => void`      | —                                          | Fired when rotation starts                       |
+| `onRotateEnd`       | `(view: ViewState) => void`      | —                                          | Fired when rotation ends                         |
+| `onTransformEnd`    | `(view: ViewState) => void`      | —                                          | Fired after any gesture ends                     |
 
 #### Returns
 
-| Property     | Type                        | Description                          |
-| ------------ | --------------------------- | ------------------------------------ |
-| `view`       | `ViewState`                 | Current view state                   |
-| `setView`    | `(view: ViewState) => void` | Imperatively set the view            |
-| `centerZoom` | `(zoom: number) => void`    | Zoom to level, centered in container |
-| `resetView`  | `() => void`                | Reset to `{ x: 0, y: 0, zoom: 1 }`   |
+| Property          | Type                               | Description                                           |
+| ----------------- | ---------------------------------- | ----------------------------------------------------- |
+| `view`            | `ViewState`                        | Current view state                                    |
+| `isAnimating`     | `boolean`                          | Whether an animation is running                       |
+| `setView`         | `(view, options?) => void`         | Imperatively set the view                             |
+| `centerZoom`      | `(zoom, options?) => void`         | Zoom to level, centered in container                  |
+| `resetView`       | `(options?) => void`               | Reset to `initialViewState` (or `{0,0,1,0}` if unset) |
+| `zoomIn`          | `(step?, options?) => void`        | Zoom in by step (default 1.5x)                        |
+| `zoomOut`         | `(step?, options?) => void`        | Zoom out by step (default 1.5x)                       |
+| `zoomToElement`   | `(el, scale?, options?) => void`   | Zoom and center on an element                         |
+| `panTo`           | `(x, y, options?) => void`         | Center viewport on content-space point                |
+| `panBy`           | `(dx, dy, options?) => void`       | Shift viewport by relative offset (screen px)         |
+| `zoomTo`          | `(zoom, point?, options?) => void` | Zoom to level, optionally anchored                    |
+| `fitToRect`       | `(rect, options?) => void`         | Fit a content-space rectangle into view               |
+| `rotateTo`        | `(angle, options?) => void`        | Set rotation to absolute angle (degrees)              |
+| `rotateBy`        | `(delta, options?) => void`        | Rotate by relative delta (degrees)                    |
+| `screenToContent` | `(screenX, screenY) => { x, y }`   | Convert screen to content coordinates                 |
+| `contentToScreen` | `(contentX, contentY) => { x, y }` | Convert content to screen coordinates                 |
+| `fitToContent`    | `(options?) => void`               | Fit content to container (needs `contentRect`)        |
+| `snapZoom`        | `(options?) => void`               | Snap zoom to nearest `zoomSnapLevels`                 |
 
-### `ViewState`
+### Types
 
 ```ts
 interface ViewState {
   x: number // horizontal offset in pixels
   y: number // vertical offset in pixels
   zoom: number // scale factor (1 = 100%)
+  rotation?: number // angle in degrees (default 0)
+}
+
+interface GesturesOptions {
+  pan?: boolean // default true
+  zoom?: boolean // default true
+  rotate?: boolean // default false
+}
+
+interface AnimationOptions {
+  animate?: boolean // default false
+  duration?: number // default 300ms
+  easing?: EasingFunction // default easeOut
+  skipConstraints?: boolean // default false (setView only)
 }
+
+type EasingFunction = (t: number) => number
+
+interface DoubleTapOptions {
+  enabled?: boolean // default true
+  mode?: "zoomIn" | "reset" | "toggle" // default "toggle"
+  step?: number // default 2
+}
+
+interface InertiaOptions {
+  enabled?: boolean // default true
+  friction?: number // 0–1, default 0.92
+}
+
+interface BoundsOptions {
+  minX?: number
+  maxX?: number
+  minY?: number
+  maxY?: number
+  mode?: "clamp" | "bounce" // default "clamp"
+}
+
+interface KeyboardOptions {
+  enabled?: boolean // default false
+  panStep?: number // default 50
+  zoomStep?: number // default 1.5
+  rotateStep?: number // default 15
+}
+
+interface SnapToGridOptions {
+  size: number
+  mode?: "end" | "always" // default "end"
+}
+
+type ZoomSnapLevel = number
+
+interface RotationOptions {
+  minAngle?: number
+  maxAngle?: number
+  snapLevels?: number[] // e.g. [0, 90, 180, 270]
+}
+
+interface CursorOptions {
+  enabled?: boolean // default true
+  idle?: string // default "grab"
+  dragging?: string // default "grabbing"
+  zooming?: string // default "zoom-in"
+}
+
+interface ActivationKeyOptions {
+  pan?: string // e.g. "Shift"
+  zoom?: string // e.g. "Alt"
+  rotate?: string // e.g. "Control"
+}
+```
+
+## Container Setup
+
+The container element **must** have `touchAction: "none"` to prevent the browser from intercepting touch gestures (scroll, pinch-zoom) before the hook can handle them:
+
+```tsx
+<div ref={containerRef} style={{ touchAction: "none", overflow: "hidden" }}>
 ```
 
+Without `touchAction: "none"`, pinch-to-zoom and touch drag will trigger native browser behavior instead of your custom handling. The `overflow: "hidden"` prevents content from leaking outside the viewport.
+
+## Browser Compatibility
+
+The hook uses standard Web APIs available in all modern browsers:
+
+| Feature               | Chrome | Firefox | Safari | Edge | iOS Safari | Android Chrome |
+| --------------------- | ------ | ------- | ------ | ---- | ---------- | -------------- |
+| Pointer Events        | 55+    | 59+     | 13+    | 12+  | 13+        | 55+            |
+| Wheel Events          | 31+    | 17+     | 7+     | 12+  | 7+         | 31+            |
+| Touch Events          | 22+    | 52+     | 10+    | 12+  | 10+        | 22+            |
+| ResizeObserver        | 64+    | 69+     | 13.1+  | 79+  | 13.4+      | 64+            |
+| requestAnimationFrame | 10+    | 23+     | 6+     | 12+  | 6+         | 10+            |
+
+**Minimum:** Chrome/Edge 64+, Firefox 69+, Safari 13.1+, iOS 13.4+.
+
+> Safari Gesture Events (`GestureEvent`) are used when available for native trackpad pinch-zoom on macOS.
+
+## Comparison
+
+| Feature               | useZoomPinch | react-zoom-pan-pinch | @use-gesture/react | motion/react        |
+| --------------------- | ------------ | -------------------- | ------------------ | ------------------- |
+| Size (min+gzip)       | **~5.8 KB**  | ~13.2 KB             | ~8.9 KB            | ~41.6 KB            |
+| Approach              | Hook         | Components + hook    | Gesture primitives | Animation + gesture |
+| Controlled mode       | ✅ Native    | ❌                   | ❌                 | ❌                  |
+| DOM wrappers          | ✅ None      | +2 divs              | ✅ None            | +1 div              |
+| Bounds / constraints  | ✅           | ✅                   | 🔧 Manual          | 🔧 dragConstraints  |
+| Keyboard navigation   | ✅           | ❌                   | ❌                 | ❌                  |
+| Coordinate conversion | ✅           | ❌                   | ❌                 | ❌                  |
+| Snap to grid          | ✅           | ❌                   | ❌                 | ❌                  |
+| Zoom snap levels      | ✅           | ❌                   | ❌                 | ❌                  |
+| Rotation gestures     | ✅           | ❌                   | 🔧 Manual          | ❌                  |
+| Ready-to-use zoom/pan | ✅           | ✅                   | 🔧 Manual          | 🔧 Manual           |
+
 ## License
 
 MIT