zoooom 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Steuber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# zoooom
+
+<div align="center">
+
+![enhance](https://media.tenor.com/atZ7_JeUlugAAAAM/enhance-supertroopers.gif)
+
+*"Enhance."*
+
+</div>
+
+---
+
+You know the scene. Someone squints at a blurry surveillance photo, says "enhance," and suddenly it's crystal clear at 4000x zoom. Every cop show. Every sci-fi movie. Every time, you think: that's not how images work.
+
+**Except now it is.**
+
+`zoooom` is a zero-dependency pan/zoom engine for images. Mouse, touch, trackpad, keyboard, and — because why not — a virtual joystick. Drop it on any image and let people *enhance* to their heart's content.
+
+## Install
+
+```bash
+npm install zoooom
+```
+
+## Quick Start
+
+```js
+import Zoooom from 'zoooom';
+
+const viewer = new Zoooom('#photo', { src: 'evidence.jpg' });
+viewer.enhance(); // you know you want to
+```
+
+That's it. Two lines. You now have:
+- Mouse drag to pan
+- Scroll wheel / trackpad pinch to zoom (toward your cursor, not the center like an animal)
+- Touch: single-finger pan, two-finger pinch
+- Keyboard: arrows to pan, `+`/`-` to zoom, `R` to reset
+- A loading spinner that fades out when the image is ready
+- Momentum on release (that satisfying drift)
+- Auto-calculated max zoom from the image's actual resolution
+
+## Script Tag
+
+No bundler? No problem.
+
+```html
+<div id="viewer" style="width: 100%; height: 100vh;"></div>
+<script src="https://unpkg.com/zoooom/dist/zoooom.iife.global.js"></script>
+<script>
+  new Zoooom('#viewer', { src: 'satellite.jpg' });
+</script>
+```
+
+## What Makes This Different
+
+Most image zoom libraries are either:
+1. jQuery plugins from 2014 that zoom to center (not cursor position)
+2. React/Vue wrappers that bring 200KB of framework along
+3. Overkill map engines that want tile servers
+
+`zoooom` is none of those. It's the interaction engine extracted from an accessibility-first image viewer I built to display 165 high-resolution infographics. Battle-tested with mouse, touch, trackpad, keyboard, and even joystick input across Chrome, Firefox, Safari, and mobile.
+
+**Zero dependencies. ~25KB core (before gzip). Works with any image.**
+
+The zoom-toward-cursor math is correct (not the naive "scale from center" that most libs do). Trackpad detection distinguishes precision scrolling from mouse wheel clicks. Safari gesture events are handled. Pinch-to-zoom tracks the actual pinch center, not the image center.
+
+## Options
+
+```js
+new Zoooom('#container', {
+  src: 'photo.jpg',           // required
+  alt: 'A satellite image',   // default: 'Image'
+  minScale: 0.8,              // how far you can zoom out
+  maxScale: 'auto',           // 'auto' = calculated from natural image dimensions
+  zoomFactor: 1.5,            // multiplier per zoom step
+  velocityDamping: 0.85,      // momentum friction (0 = ice rink, 1 = brick wall)
+  trackpadSensitivity: 0.002, // fine-tuning for continuous trackpad zoom
+  mouse: true,                // enable mouse input
+  touch: true,                // enable touch input
+  wheel: true,                // enable wheel/trackpad
+  keyboard: true,             // enable keyboard nav
+  loading: true,              // show loading spinner
+  injectStyles: true,         // auto-inject CSS (disable for BYO styles)
+  respectReducedMotion: true, // honor prefers-reduced-motion
+  onLoad: () => {},           // fires when image is ready
+  onZoom: (scale) => {},      // fires on zoom change
+  onPan: (x, y) => {},        // fires on pan
+});
+```
+
+## API
+
+```js
+const viewer = new Zoooom('#el', { src: 'img.jpg' });
+
+viewer.zoomIn();           // zoom in by zoomFactor
+viewer.zoomOut();          // zoom out
+viewer.enhance();          // same as zoomIn(), but funnier
+viewer.zoomTo(3);          // set specific scale
+viewer.zoomToPoint(2, x, y); // zoom toward a point
+viewer.panTo(100, -50);   // set position directly
+viewer.panBy(10, 0);      // relative pan
+viewer.reset();            // back to scale=1, centered
+viewer.center();           // center without changing zoom
+viewer.load('new.jpg');    // load a different image
+viewer.destroy();          // clean up everything
+
+// Read state
+viewer.scale;        // current zoom level
+viewer.translateX;   // current X offset
+viewer.translateY;   // current Y offset
+viewer.isLoaded;     // whether image is ready
+
+// Events
+viewer.on('load', () => {});
+viewer.on('zoom', (scale) => {});
+viewer.on('pan', (x, y) => {});
+viewer.on('reset', () => {});
+viewer.on('destroy', () => {});
+viewer.off('zoom', handler);
+```
+
+## Joystick Plugin
+
+For when arrow keys aren't enough and you want that drone-camera-operator feeling:
+
+```js
+import Zoooom from 'zoooom';
+import { ZoooomJoystick } from 'zoooom/joystick';
+
+const viewer = new Zoooom('#container', { src: 'map.jpg' });
+const joystick = new ZoooomJoystick(viewer);
+```
+
+The joystick gives you:
+- A virtual disc for 8-directional panning (hover or drag)
+- Split-circle center for zoom in/out
+- Dwell-to-activate (hover 100ms, then move to pan)
+- Direction arrows showing which way you're going
+- Screen reader ARIA support (announces direction + speed)
+- Compass toggle button to show/hide
+
+```js
+// Joystick options
+new ZoooomJoystick(viewer, {
+  radius: 60,          // panning zone radius (px)
+  deadzone: 0.1,       // center deadzone (fraction)
+  maxSpeed: 10,        // max pan speed (px/frame)
+  showToggle: true,    // show the toggle button
+  dwellTimeout: 100,   // ms before dwell activates
+});
+
+joystick.show();       // show programmatically
+joystick.hide();       // hide
+joystick.destroy();    // remove from DOM
+```
+
+Script tag (full bundle with joystick included):
+
+```html
+<script src="https://unpkg.com/zoooom/dist/zoooom-full.iife.global.js"></script>
+<script>
+  const viewer = new Zoooom('#container', { src: 'photo.jpg' });
+  const joystick = new ZoooomJoystick(viewer);
+</script>
+```
+
+## CSS Customization
+
+Styles are auto-injected. Override with CSS variables:
+
+```css
+[data-zoooom] {
+  --zoooom-bg: #1a1a1a;
+  --zoooom-spinner-color: #ff6b6b;
+  --zoooom-spinner-track: rgba(255, 255, 255, 0.2);
+  --zoooom-spinner-size: 48px;
+  --zoooom-loading-bg: rgba(0, 0, 0, 0.9);
+  --zoooom-loading-radius: 12px;
+  --zoooom-cursor: crosshair;
+  --zoooom-cursor-active: move;
+}
+```
+
+Or disable auto-injection and bring your own:
+
+```js
+new Zoooom('#el', { src: 'img.jpg', injectStyles: false });
+```
+
+```html
+<link rel="stylesheet" href="node_modules/zoooom/dist/zoooom.css">
+```
+
+## Accessibility
+
+- Full keyboard navigation (arrows, +/-, R, Tab)
+- `prefers-reduced-motion` respected — no transitions, no momentum, instant show
+- ARIA labels on all interactive elements
+- Joystick announces direction and speed to screen readers
+- Container is focusable and has `role="application"` with usage hints
+- Minimum 44px touch targets
+
+## Browser Support
+
+ES2020+: Chrome 80+, Firefox 74+, Safari 14+, Edge 80+.
+
+## The Name
+
+Four o's because three felt restrained and five was too many.
+
+## License
+
+MIT

package/dist/Zoooom-BypxEt9q.d.cts

@@ -0,0 +1,128 @@
+/** Configuration options for the Zoooom viewer */
+interface ZoooomOptions {
+    /** Image URL to display (required) */
+    src: string;
+    /** Alt text for the image */
+    alt?: string;
+    /** Minimum zoom scale (default: 0.8) */
+    minScale?: number;
+    /** Maximum zoom scale — 'auto' calculates from natural dimensions (default: 'auto') */
+    maxScale?: number | 'auto';
+    /** Multiplier beyond native resolution for max zoom (default: 2) */
+    overscaleFactor?: number;
+    /** Zoom multiplier per discrete step (default: 1.5) */
+    zoomFactor?: number;
+    /** Keyboard pan distance in pixels (default: 50) */
+    panStep?: number;
+    /** Momentum friction coefficient, 0-1 (default: 0.85) */
+    velocityDamping?: number;
+    /** Sensitivity for continuous trackpad zoom (default: 0.002) */
+    trackpadSensitivity?: number;
+    /** Enable mouse drag/wheel (default: true) */
+    mouse?: boolean;
+    /** Enable touch pan/pinch (default: true) */
+    touch?: boolean;
+    /** Enable wheel/trackpad zoom (default: true) */
+    wheel?: boolean;
+    /** Enable keyboard navigation (default: true) */
+    keyboard?: boolean;
+    /** Show loading spinner — true for default, string for custom HTML, false to disable */
+    loading?: boolean | string;
+    /** Auto-inject bundled CSS (default: true) */
+    injectStyles?: boolean;
+    /** Honor prefers-reduced-motion (default: true) */
+    respectReducedMotion?: boolean;
+    onLoad?: () => void;
+    onError?: (error: Error) => void;
+    onZoom?: (scale: number) => void;
+    onPan?: (x: number, y: number) => void;
+}
+/** Internal mutable state for the viewer */
+interface ZoooomState {
+    scale: number;
+    translateX: number;
+    translateY: number;
+    velocityX: number;
+    velocityY: number;
+    maxScale: number;
+    isDragging: boolean;
+    isAnimating: boolean;
+    isLoaded: boolean;
+    startX: number;
+    startY: number;
+    initialDistance: number;
+    initialScale: number;
+    initialTranslateX: number;
+    initialTranslateY: number;
+    pinchCenter: {
+        x: number;
+        y: number;
+    };
+    wheelTimeout: ReturnType<typeof setTimeout> | null;
+    reducedMotion: boolean;
+}
+/** Event types emitted by Zoooom */
+type ZoooomEvent = 'load' | 'error' | 'zoom' | 'pan' | 'reset' | 'destroy';
+/** Event handler function */
+type ZoooomEventHandler = (...args: unknown[]) => void;
+/** DOM elements managed by the viewer */
+interface ZoooomElements {
+    container: HTMLElement;
+    image: HTMLImageElement;
+    loadingOverlay: HTMLElement | null;
+}
+/** Joystick plugin options */
+interface JoystickOptions {
+    /** Panning zone radius in pixels (default: 60) */
+    radius?: number;
+    /** Center deadzone as fraction 0-1 (default: 0.1) */
+    deadzone?: number;
+    /** Max panning speed in px/frame (default: 10) */
+    maxSpeed?: number;
+    /** Position of the joystick (default: 'bottom-center') */
+    position?: 'bottom-center' | 'bottom-left' | 'bottom-right';
+    /** Show compass toggle button (default: true) */
+    showToggle?: boolean;
+    /** Milliseconds before dwell activates panning (default: 100) */
+    dwellTimeout?: number;
+}
+
+declare class Zoooom {
+    private state;
+    private elements;
+    private options;
+    private cleanups;
+    private listeners;
+    private resizeHandler;
+    constructor(container: string | HTMLElement, options: ZoooomOptions);
+    get scale(): number;
+    get translateX(): number;
+    get translateY(): number;
+    get isLoaded(): boolean;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** "Enhance." */
+    enhance(): void;
+    zoomTo(scale: number): void;
+    zoomToPoint(scale: number, x: number, y: number): void;
+    panTo(x: number, y: number): void;
+    panBy(dx: number, dy: number): void;
+    reset(): void;
+    center(): void;
+    load(src: string, alt?: string): void;
+    /**
+     * Apply velocity directly (used by joystick plugin).
+     * Sets velocity and lets the rAF loop handle movement.
+     */
+    applyVelocity(vx: number, vy: number): void;
+    /** Get the internal state (for plugin access) */
+    getState(): Readonly<ZoooomState>;
+    /** Get the managed elements (for plugin access) */
+    getElements(): Readonly<ZoooomElements>;
+    on(event: ZoooomEvent, handler: ZoooomEventHandler): void;
+    off(event: ZoooomEvent, handler: ZoooomEventHandler): void;
+    emit(event: string, ...args: unknown[]): void;
+    destroy(): void;
+}
+
+export { type JoystickOptions as J, Zoooom as Z, type ZoooomEvent as a, type ZoooomEventHandler as b, type ZoooomOptions as c };

package/dist/Zoooom-BypxEt9q.d.ts

@@ -0,0 +1,128 @@
+/** Configuration options for the Zoooom viewer */
+interface ZoooomOptions {
+    /** Image URL to display (required) */
+    src: string;
+    /** Alt text for the image */
+    alt?: string;
+    /** Minimum zoom scale (default: 0.8) */
+    minScale?: number;
+    /** Maximum zoom scale — 'auto' calculates from natural dimensions (default: 'auto') */
+    maxScale?: number | 'auto';
+    /** Multiplier beyond native resolution for max zoom (default: 2) */
+    overscaleFactor?: number;
+    /** Zoom multiplier per discrete step (default: 1.5) */
+    zoomFactor?: number;
+    /** Keyboard pan distance in pixels (default: 50) */
+    panStep?: number;
+    /** Momentum friction coefficient, 0-1 (default: 0.85) */
+    velocityDamping?: number;
+    /** Sensitivity for continuous trackpad zoom (default: 0.002) */
+    trackpadSensitivity?: number;
+    /** Enable mouse drag/wheel (default: true) */
+    mouse?: boolean;
+    /** Enable touch pan/pinch (default: true) */
+    touch?: boolean;
+    /** Enable wheel/trackpad zoom (default: true) */
+    wheel?: boolean;
+    /** Enable keyboard navigation (default: true) */
+    keyboard?: boolean;
+    /** Show loading spinner — true for default, string for custom HTML, false to disable */
+    loading?: boolean | string;
+    /** Auto-inject bundled CSS (default: true) */
+    injectStyles?: boolean;
+    /** Honor prefers-reduced-motion (default: true) */
+    respectReducedMotion?: boolean;
+    onLoad?: () => void;
+    onError?: (error: Error) => void;
+    onZoom?: (scale: number) => void;
+    onPan?: (x: number, y: number) => void;
+}
+/** Internal mutable state for the viewer */
+interface ZoooomState {
+    scale: number;
+    translateX: number;
+    translateY: number;
+    velocityX: number;
+    velocityY: number;
+    maxScale: number;
+    isDragging: boolean;
+    isAnimating: boolean;
+    isLoaded: boolean;
+    startX: number;
+    startY: number;
+    initialDistance: number;
+    initialScale: number;
+    initialTranslateX: number;
+    initialTranslateY: number;
+    pinchCenter: {
+        x: number;
+        y: number;
+    };
+    wheelTimeout: ReturnType<typeof setTimeout> | null;
+    reducedMotion: boolean;
+}
+/** Event types emitted by Zoooom */
+type ZoooomEvent = 'load' | 'error' | 'zoom' | 'pan' | 'reset' | 'destroy';
+/** Event handler function */
+type ZoooomEventHandler = (...args: unknown[]) => void;
+/** DOM elements managed by the viewer */
+interface ZoooomElements {
+    container: HTMLElement;
+    image: HTMLImageElement;
+    loadingOverlay: HTMLElement | null;
+}
+/** Joystick plugin options */
+interface JoystickOptions {
+    /** Panning zone radius in pixels (default: 60) */
+    radius?: number;
+    /** Center deadzone as fraction 0-1 (default: 0.1) */
+    deadzone?: number;
+    /** Max panning speed in px/frame (default: 10) */
+    maxSpeed?: number;
+    /** Position of the joystick (default: 'bottom-center') */
+    position?: 'bottom-center' | 'bottom-left' | 'bottom-right';
+    /** Show compass toggle button (default: true) */
+    showToggle?: boolean;
+    /** Milliseconds before dwell activates panning (default: 100) */
+    dwellTimeout?: number;
+}
+
+declare class Zoooom {
+    private state;
+    private elements;
+    private options;
+    private cleanups;
+    private listeners;
+    private resizeHandler;
+    constructor(container: string | HTMLElement, options: ZoooomOptions);
+    get scale(): number;
+    get translateX(): number;
+    get translateY(): number;
+    get isLoaded(): boolean;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** "Enhance." */
+    enhance(): void;
+    zoomTo(scale: number): void;
+    zoomToPoint(scale: number, x: number, y: number): void;
+    panTo(x: number, y: number): void;
+    panBy(dx: number, dy: number): void;
+    reset(): void;
+    center(): void;
+    load(src: string, alt?: string): void;
+    /**
+     * Apply velocity directly (used by joystick plugin).
+     * Sets velocity and lets the rAF loop handle movement.
+     */
+    applyVelocity(vx: number, vy: number): void;
+    /** Get the internal state (for plugin access) */
+    getState(): Readonly<ZoooomState>;
+    /** Get the managed elements (for plugin access) */
+    getElements(): Readonly<ZoooomElements>;
+    on(event: ZoooomEvent, handler: ZoooomEventHandler): void;
+    off(event: ZoooomEvent, handler: ZoooomEventHandler): void;
+    emit(event: string, ...args: unknown[]): void;
+    destroy(): void;
+}
+
+export { type JoystickOptions as J, Zoooom as Z, type ZoooomEvent as a, type ZoooomEventHandler as b, type ZoooomOptions as c };