@canvas-glide/react 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vangel Trajkovski
+
+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

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @canvas-glide/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components and a hook for [canvas-glide](https://github.com/vrtexe/canvas-glide): pan, zoom and pinch-to-zoom for an image, or for any content you render, with mouse, touch, pen and wheel input.
+
+[![npm version](https://img.shields.io/npm/v/@canvas-glide/react.svg?style=flat-square)](https://www.npmjs.com/package/@canvas-glide/react)
+[![types](https://img.shields.io/npm/types/@canvas-glide/react.svg?style=flat-square)](https://github.com/vrtexe/canvas-glide-react/blob/main/src/GlideCanvas.tsx)
+[![license](https://img.shields.io/npm/l/@canvas-glide/react.svg?style=flat-square)](LICENSE.md)
+
+[Live demo](https://vrtexe.github.io/canvas-glide-react-demo/)
+
+The package has two layers. `GlideCanvas` is a ready image viewer: give it a `Blob` and it shows the image fitted to its box, with drag to pan, wheel and pinch to zoom, and a ref for zoom buttons. `useGlideCanvas` and `Viewport` are the parts `GlideCanvas` is built from; use them to pan and zoom your own content. The package re-exports everything from `canvas-glide`, so one import covers the engine API too.
+
+## Install
+
+```sh
+npm install @canvas-glide/react
+```
+
+`canvas-glide` is a dependency and installs with it. `react` 19 is a peer dependency.
+
+## Image viewer
+
+```tsx
+import { useRef, useState } from 'react';
+import { GlideCanvas, Renderer, type GlideCanvasRef } from '@canvas-glide/react';
+
+export function Viewer() {
+  const [file, setFile] = useState<File | null>(null);
+  const viewer = useRef<GlideCanvasRef>(null);
+
+  return (
+    <>
+      <input type="file" accept="image/*" onChange={(e) => setFile(e.target.files?.[0] ?? null)} />
+      <button onClick={() => viewer.current?.zoomIn()}>+</button>
+      <button onClick={() => viewer.current?.zoomOut()}>−</button>
+      <button onClick={() => viewer.current?.fit()}>Fit</button>
+
+      <div style={{ width: 800, height: 500 }}>
+        <GlideCanvas ref={viewer} renderer={Renderer.Image} image={file} />
+      </div>
+    </>
+  );
+}
+```
+
+`GlideCanvas` fills its parent, so the parent needs a size. At scale 1 the image is fitted inside the box with its aspect ratio kept, and `fit()` returns to that view. By default the image can be panned until it just leaves the box, and no further.
+
+## Renderers
+
+`renderer` picks how the image is drawn. All three use the same engine and the same coordinates; a renderer calls `fit()` when its image has loaded, so switching renderers starts from the fitted view.
+
+| Renderer | How it draws | `canvasConfig.children` |
+|---|---|---|
+| `Renderer.Canvas` (default) | Draws the decoded bitmap into a `<canvas>` sized in device pixels. | Not rendered. |
+| `Renderer.Image` | Moves and scales an `<img>` with a CSS `transform`. | Rendered inside the transformed box, so overlays move and scale with the image. |
+| `Renderer.Html` | Resizes the `<img>` to the zoomed size and scrolls its container, with no CSS transform, so the browser rasterizes the image at its displayed size. | Rendered after the `<img>` inside the scrolled container. |
+
+## `GlideCanvas` props
+
+| Prop | Type | Usage |
+|---|---|---|
+| `image` | `Blob \| null` | The image to show. A `File` from an `<input type="file">` is a `Blob`. `null` clears the view. The image and HTML renderers load PNG, JPEG, GIF, WebP, AVIF and BMP through a `blob:` URL and every other type, such as SVG, through a `data:` URL, so a script inside an uploaded SVG cannot run in your page's origin. |
+| `renderer` | `Renderer` | `Renderer.Canvas` (default), `Renderer.Image` or `Renderer.Html`. |
+| `config` | engine options | The `canvas-glide` options except the two rect getters, which `GlideCanvas` supplies: `state`, `move`, `scale` and `constraints`. |
+| `viewportConfig` | `ViewportOptions` | Props for the outer `<div>`; see [Viewport](#viewport). |
+| `canvasConfig` | renderer options | `content` (props for the `<img>` or `<canvas>`), `container` (props for the wrapping element; for the canvas renderer, also the `<canvas>`), `children`, and `afterDraw(transform, ref)`, called after each frame. A renderer chosen at runtime cannot take `canvasConfig`. |
+| `ref` | `GlideCanvasRef` | Every engine method (`zoomIn`, `zoomOut`, `zoomTo`, `panTo`, `fit`, `center`, `reset`, `getTransform`, ...) plus `viewportRef` and `canvasRef`. |
+
+The engine methods are documented in the [canvas-glide README](https://github.com/vrtexe/canvas-glide#methods).
+
+`GlideCanvas` redraws once per animation frame. It calls `config.state.onTransformChange` once per frame with a copy of the transform, while `onScaleChange` and `onOriginChange` run on every input event.
+
+## Your own content
+
+`useGlideCanvas` creates the engine, and `Viewport` is the element that receives the input. This example pans and zooms a 1200 by 800 pixel `<div>`:
+
+```tsx
+import { useRef } from 'react';
+import { useGlideCanvas, Viewport, type ViewportRef } from '@canvas-glide/react';
+
+export function Board() {
+  const viewport = useRef<ViewportRef>(null);
+  const content = useRef<HTMLDivElement>(null);
+
+  const glide = useGlideCanvas({
+    getViewportRect: () => viewport.current?.getRect() ?? null,
+    getCanvasRect: () => ({ x: 0, y: 0, width: 1200, height: 800 }),
+    state: {
+      onTransformChange: ({ origin, scale }) => {
+        if (!content.current) return;
+        content.current.style.transform = `translate(${-origin.x * scale}px, ${-origin.y * scale}px) scale(${scale})`;
+      },
+    },
+  });
+
+  return (
+    <Viewport ref={viewport} lib={glide} style={{ width: 800, height: 500 }}>
+      <div ref={content} style={{ width: 1200, height: 800, transformOrigin: '0 0' }}>
+        Your content
+      </div>
+    </Viewport>
+  );
+}
+```
+
+`useGlideCanvas` adds an origin limit that keeps the content reachable, and passing `config.constraints.origin` replaces it. The hook creates the engine once: callbacks and the rect getters always use the latest props, while `move`, `scale`, `constraints` and `state.initial` are read when the component mounts. To apply new values for those, remount the component, for example by changing its `key`.
+
+## Viewport
+
+`Viewport` renders a `<div>` with `overflow: hidden`, `touch-action: none`, `user-select: none` and `overscroll-behavior: contain`, and attaches the engine's pointer handlers and a non-passive wheel listener. It accepts every `<div>` prop, and these:
+
+| Prop | Default | Usage |
+|---|---|---|
+| `lib` | none | The object returned by `useGlideCanvas`. |
+| `onResize` | none | Called with the `ViewportRef` when the element's size changes. |
+| `pointerDownEnabled`, `pointerMoveEnabled`, `pointerUpEnabled`, `pointerCancelEnabled` | `true` | `false` leaves that pointer event to the page. |
+| `wheelEnabled` | `true` | `false` removes the wheel listener, so the wheel does not zoom. |
+
+Its ref, `ViewportRef`, has `getElement()`, `getRect()` (the element's client rectangle, read on each call), `getClientWidth()` and `getClientHeight()` in CSS pixels, and `getWidth()` and `getHeight()` in device pixels.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run build
+npm run lint
+```
+
+`npm test` runs the Vitest suite in `test/` in jsdom, with the 2D context, `createImageBitmap` and `ResizeObserver` stubbed.
+
+`npm run build` type-checks with `tsc -b` and writes `dist/` with Vite: `canvas-glide.js` (ES module) and the type declarations. `canvas-glide`, `react` and `react/jsx-runtime` stay external.
+
+`canvas-glide` comes from npm. To work against an unreleased engine, build it and run `npm link ../lib` (the path to a local `canvas-glide` checkout); `npm install` restores the published version.
+
+Publishing a GitHub release runs `.github/workflows/npm-publish.yml`: it lints, tests and builds the tag, sets `package.json` on the default branch to the release version, and stages the package on npm with trusted publishing; `npm stage approve` publishes it.
+
+## License
+
+MIT, see [LICENSE.md](LICENSE.md).

package/dist/GlideCanvas.d.ts

@@ -0,0 +1,36 @@
+import { Ref } from 'react';
+import { GlideCanvasInstance, GlideCanvasOptions } from './useGlideCanvas.ts';
+import { ViewportRef, ViewportOptions } from './Viewport.tsx';
+import { Renderer, CanvasOptions, RendererRef } from './renderer/base.tsx';
+export type BaseGlideCanvasRef<R> = GlideCanvasInstance & {
+    viewportRef?: ViewportRef | null;
+    canvasRef?: R | null;
+};
+export type GlideCanvasRef<T extends Renderer = Renderer> = BaseGlideCanvasRef<RendererRef[T]>;
+export type BaseGlideCanvasProps = {
+    config?: Omit<GlideCanvasOptions, "getViewportRect" | "getCanvasRect">;
+    viewportConfig?: ViewportOptions;
+    image?: Blob | null;
+    ref?: Ref<GlideCanvasRef>;
+};
+/**
+ * Discriminated union over `renderer`: call sites with a literal renderer get
+ * their exact canvasConfig checked. The last arm supports a runtime-decided
+ * renderer (e.g. tab switching); it cannot accept canvasConfig, because no
+ * single config shape fits all renderers. For fully custom rendering, compose
+ * the primitives directly: useGlideCanvas + Viewport + your own component.
+ */
+export type GlideCanvasProps = (BaseGlideCanvasProps & {
+    renderer?: typeof Renderer.Canvas;
+    canvasConfig?: CanvasOptions<typeof Renderer.Canvas>;
+}) | (BaseGlideCanvasProps & {
+    renderer: typeof Renderer.Image;
+    canvasConfig?: CanvasOptions<typeof Renderer.Image>;
+}) | (BaseGlideCanvasProps & {
+    renderer: typeof Renderer.Html;
+    canvasConfig?: CanvasOptions<typeof Renderer.Html>;
+}) | (BaseGlideCanvasProps & {
+    renderer: Renderer;
+    canvasConfig?: undefined;
+});
+export declare function GlideCanvas(props: GlideCanvasProps): import("react").JSX.Element;

package/dist/Viewport.d.ts

@@ -0,0 +1,27 @@
+import { HTMLProps, PropsWithChildren, Ref } from 'react';
+import { GlideCanvasInstance } from './useGlideCanvas.ts';
+export type ViewportRef = {
+    getElement: () => HTMLDivElement | null;
+    /** Width in CSS pixels. */
+    getClientWidth: () => number;
+    /** Height in CSS pixels. */
+    getClientHeight: () => number;
+    getRect: () => DOMRect | null;
+    /** Width in device pixels (CSS pixels × devicePixelRatio). */
+    getWidth: () => number;
+    /** Height in device pixels (CSS pixels × devicePixelRatio). */
+    getHeight: () => number;
+};
+export type ViewportOptions = Omit<HTMLProps<HTMLDivElement>, "ref"> & {
+    onResize?: (ref: ViewportRef) => void;
+    pointerDownEnabled?: boolean;
+    pointerMoveEnabled?: boolean;
+    pointerUpEnabled?: boolean;
+    pointerCancelEnabled?: boolean;
+    wheelEnabled?: boolean;
+};
+export type ViewportProps = ViewportOptions & {
+    ref?: Ref<ViewportRef>;
+    lib?: GlideCanvasInstance;
+};
+export declare function Viewport({ ref, lib, children, style, className, onResize, pointerDownEnabled, pointerMoveEnabled, pointerUpEnabled, pointerCancelEnabled, wheelEnabled, ...rest }: PropsWithChildren<ViewportProps>): import("react").JSX.Element;

package/dist/canvas-glide.d.ts

@@ -0,0 +1,8 @@
+export * from 'canvas-glide';
+export * from './useGlideCanvas.ts';
+export * from './Viewport.tsx';
+export * from './GlideCanvas.tsx';
+export * from './renderer/base.tsx';
+export * from './renderer/Canvas.tsx';
+export * from './renderer/HtmlCanvas.tsx';
+export * from './renderer/ImageCanvas.tsx';

package/dist/canvas-glide.js

@@ -0,0 +1,455 @@
+"use no memo";
+import { constrainTo as e, copyTransform as t, createEngine as n } from "canvas-glide";
+import { useEffect as r, useImperativeHandle as i, useMemo as a, useRef as o, useState as s } from "react";
+import { jsx as c, jsxs as l } from "react/jsx-runtime";
+export * from "canvas-glide";
+function u(e) {
+	return (t) => {
+		let n = e.getViewportRect(), r = e.getCanvasRect();
+		return !n || !r || r.width <= 0 ? t : d(t, e.getScale(), n, r);
+	};
+}
+function d(t, n, r, i) {
+	let a = r.width / n, o = r.height / n;
+	return {
+		x: e(t.x, -a + 0, i.width - 0),
+		y: e(t.y, -o + 0, i.height - 0)
+	};
+}
+//#endregion
+//#region src/useGlideCanvas.ts
+function f(e) {
+	let t = o(null), r = o(e);
+	if (r.current = e, t.current === null) {
+		let i = u({
+			getViewportRect: () => r.current.getViewportRect(),
+			getCanvasRect: () => r.current.getCanvasRect(),
+			getScale: () => t.current.getScale()
+		});
+		t.current = n({
+			...e,
+			constraints: {
+				...e.constraints,
+				origin: e.constraints?.origin ?? {
+					enabled: !0,
+					constrain: i
+				}
+			},
+			getViewportRect: () => r.current.getViewportRect(),
+			getCanvasRect: () => r.current.getCanvasRect(),
+			state: {
+				...e.state,
+				onTransformChange: (e) => r.current.state?.onTransformChange?.(e),
+				onScaleChange: (e) => r.current.state?.onScaleChange?.(e),
+				onOriginChange: (e) => r.current.state?.onOriginChange?.(e)
+			},
+			move: {
+				...e.move,
+				onIsMovingChange: (e) => r.current.move?.onIsMovingChange?.(e)
+			}
+		});
+	}
+	let i = t.current;
+	return a(() => ({
+		...i,
+		engine: i,
+		onPointerDown: i.event.onPointerDown,
+		onPointerMove: i.event.onPointerMove,
+		onPointerUp: i.event.onPointerUp,
+		onWheel: i.event.onWheel
+	}), [i]);
+}
+//#endregion
+//#region src/util/event.ts
+function p(e, t, n) {
+	if (e) return m("wheel", e, t, n);
+}
+function m(e, t, n, r) {
+	if (t) return t.addEventListener(e, n, r), () => {
+		t.removeEventListener(e, n, r);
+	};
+}
+//#endregion
+//#region src/Viewport.tsx
+var h = {
+	width: "100%",
+	height: "100%",
+	position: "relative",
+	background: "transparent",
+	overflow: "hidden",
+	userSelect: "none",
+	touchAction: "none",
+	overscrollBehavior: "contain"
+};
+function g({ ref: e, lib: t, children: n, style: a, className: s, onResize: l, pointerDownEnabled: u = !0, pointerMoveEnabled: d = !0, pointerUpEnabled: f = !0, pointerCancelEnabled: m = !0, wheelEnabled: g = !0, ..._ }) {
+	let v = o(null), y = o(l);
+	y.current = l;
+	let b = {
+		...h,
+		...a
+	};
+	function x() {
+		return v?.current ? v.current.clientWidth * (window.devicePixelRatio || 1) : 0;
+	}
+	function S() {
+		return v?.current ? v.current.clientHeight * (window.devicePixelRatio || 1) : 0;
+	}
+	r(() => {
+		if (t?.onWheel !== void 0 && g !== !1) return p(v.current, t.onWheel, { passive: !1 });
+	}, [t?.onWheel, g]), r(() => {
+		if (!v.current) return;
+		let e = new ResizeObserver(() => y.current?.(C.current));
+		return e.observe(v.current), () => e.disconnect();
+	}, []);
+	let C = o({
+		getElement: () => v.current,
+		getClientWidth: () => v.current?.clientWidth || 0,
+		getClientHeight: () => v.current?.clientHeight || 0,
+		getWidth: x,
+		getHeight: S,
+		getRect: () => v.current?.getBoundingClientRect() ?? null
+	});
+	return i(e, () => C.current), /* @__PURE__ */ c("div", {
+		ref: v,
+		className: s,
+		style: b,
+		onPointerDown: u ? t?.onPointerDown : void 0,
+		onPointerMove: d ? t?.onPointerMove : void 0,
+		onPointerUp: f ? t?.onPointerUp : void 0,
+		onPointerCancel: m ? t?.onPointerUp : void 0,
+		..._,
+		children: n
+	});
+}
+//#endregion
+//#region src/util/asyncMemo.ts
+function _(e, t, n) {
+	let [i, a] = s(null);
+	return r(() => {
+		let t = !0, r = null;
+		return e().then((e) => {
+			r = e, t ? a(e) : e && (n?.(e), r = null);
+		}).catch(() => {
+			t && a(null);
+		}), () => {
+			t = !1, r &&= (n?.(r), null), a(null);
+		};
+	}, t), i;
+}
+//#endregion
+//#region src/util/image.ts
+var v = /^image\/(png|jpeg|gif|webp|avif|bmp)$/i;
+function y(e) {
+	return e ? createImageBitmap(e) : Promise.resolve(null);
+}
+function b(e) {
+	return e ? v.test(e.type) ? Promise.resolve(URL.createObjectURL(e)) : S(e) : Promise.resolve(null);
+}
+function x(e) {
+	e?.startsWith("blob:") && URL.revokeObjectURL(e);
+}
+function S(e) {
+	return new Promise((t, n) => {
+		let r = new FileReader();
+		r.onload = () => t(r.result), r.onerror = (e) => n(e), r.readAsDataURL(e);
+	});
+}
+//#endregion
+//#region src/util/useIdealScale.ts
+function C(e, t) {
+	let n = o(1);
+	function r() {
+		let r = e?.current, i = t();
+		if (!r || !i?.width || !i?.height) {
+			n.current = 1;
+			return;
+		}
+		n.current = Math.min(r.getClientWidth() / i.width, r.getClientHeight() / i.height);
+	}
+	function i(e) {
+		let r = t();
+		return {
+			x: e?.offsetLeft || 0,
+			y: e?.offsetTop || 0,
+			width: (r?.width || 0) * n.current,
+			height: (r?.height || 0) * n.current
+		};
+	}
+	return {
+		idealScale: n,
+		updateIdealScale: r,
+		getImageRect: i
+	};
+}
+//#endregion
+//#region src/renderer/Canvas.tsx
+var w = {
+	position: "absolute",
+	top: 0,
+	left: 0,
+	height: "100%",
+	width: "100%"
+};
+function T({ viewportRef: e, ref: t, afterDraw: n, image: a, lib: l, container: u, content: d }) {
+	let { style: f, ref: p, ...m } = u ?? {}, { style: h, ref: g, ...v } = d ?? {}, b = {
+		...w,
+		...f,
+		...h
+	}, x = _(() => y(a), [a], (e) => e?.close()), S = o(null), [T] = s(() => document.createElement("canvas")), E = o(null);
+	function D(e) {
+		e.imageSmoothingEnabled = !0, e.imageSmoothingQuality = "high";
+	}
+	r(() => {
+		E.current || (E.current = S?.current?.getContext("2d") || null, E.current && D(E.current));
+	}, []);
+	let { idealScale: O, updateIdealScale: k, getImageRect: A } = C(e, () => ({
+		width: T.width,
+		height: T.height
+	}));
+	r(() => {
+		if (!x) {
+			T.width = 0, T.height = 0, j();
+			return;
+		}
+		P(x), I(e?.current), k(), l?.fit(), M(l?.stateService.getTransform());
+	}, [x]);
+	function j() {
+		let e = S.current, t = E.current;
+		!e || !t || (t.resetTransform(), t.clearRect(0, 0, e.width, e.height));
+	}
+	function M(t) {
+		if (!S.current || !t || !x) return;
+		let r = S.current, i = t.scale, a = t.origin.x, o = t.origin.y, s = E.current;
+		if (!s) return;
+		let c = e?.current;
+		c && (r.width !== Math.floor(c.getWidth()) || r.height !== Math.floor(c.getHeight())) && F(c.getWidth(), c.getHeight());
+		let l = window.devicePixelRatio || 1;
+		j();
+		let u = i * l;
+		s.setTransform(u, 0, 0, u, -a * u, -o * u), s.drawImage(T, 0, 0, T.width * O.current, T.height * O.current), n?.(t, L);
+	}
+	function N() {
+		M(l?.stateService.getTransform());
+	}
+	function P(e) {
+		T.width = e.width, T.height = e.height, T.getContext("2d")?.drawImage(e, 0, 0);
+	}
+	function F(e, t) {
+		S.current && (S.current.width = e, S.current.height = t, E.current && D(E.current), k());
+	}
+	function I(e) {
+		e && (F(e.getWidth(), e.getHeight()), N());
+	}
+	let L = {
+		getContainerRef: () => S.current,
+		getContentRef: () => S.current,
+		draw: M,
+		handleViewportResize: I,
+		getImageRect: () => A(S.current)
+	};
+	return i(t, () => L), /* @__PURE__ */ c("canvas", {
+		style: b,
+		ref: S,
+		...m,
+		...v
+	});
+}
+//#endregion
+//#region src/renderer/ImageCanvas.tsx
+var E = {
+	position: "relative",
+	transformOrigin: "top left"
+}, D = {
+	display: "block",
+	height: "100%",
+	width: "100%"
+};
+function O({ viewportRef: e, afterDraw: t, children: n, ref: a, image: u, lib: d, container: f, content: p }) {
+	let { style: m, ref: h, ...g } = p ?? {}, { style: v, ref: y, ...S } = f ?? {}, w = o(null), T = o(null), [O, k] = s("hidden"), A = _(() => b(u), [u], x), { idealScale: j, updateIdealScale: M, getImageRect: N } = C(e, () => T.current ? {
+		width: T.current.naturalWidth,
+		height: T.current.naturalHeight
+	} : null);
+	function P(e) {
+		!e || !w.current || (w.current.style.transform = `scale(${e.scale}) translate(${-e.origin.x}px, ${-e.origin.y}px)`, t?.(e, B));
+	}
+	function F() {
+		P(d?.stateService.getTransform());
+	}
+	function I() {
+		if (!w.current || !T.current) return;
+		let { naturalWidth: e, naturalHeight: t } = T.current;
+		w.current.style.width = `${e * j.current}px`, w.current.style.height = `${t * j.current}px`;
+	}
+	function L(e) {
+		e && (M(), I(), F());
+	}
+	function R() {
+		M(), I(), d?.fit(), F(), k("visible");
+	}
+	r(() => {
+		T.current?.complete && T.current.naturalWidth && R();
+	}, [A]);
+	let z = {
+		...E,
+		...v
+	}, B = {
+		getContainerRef: () => w.current,
+		getContentRef: () => T.current,
+		draw: P,
+		handleViewportResize: L,
+		getImageRect: () => N(w.current)
+	};
+	i(a, () => B);
+	let V = {
+		...D,
+		visibility: O,
+		...m
+	};
+	return /* @__PURE__ */ l("div", {
+		ref: w,
+		style: z,
+		...S,
+		children: [/* @__PURE__ */ c("img", {
+			hidden: !A,
+			style: V,
+			ref: T,
+			src: A || void 0,
+			draggable: !1,
+			onLoad: R,
+			...g
+		}), n]
+	});
+}
+//#endregion
+//#region src/renderer/HtmlCanvas.tsx
+function k({ viewportRef: e, afterDraw: t, children: n, ref: r, image: a, lib: s, container: u, content: d }) {
+	let { style: f, ref: p, ...m } = u ?? {}, { style: h, ref: g, ...v } = d ?? {}, y = o(null), S = o(null), w = _(() => b(a), [a], x), { idealScale: T, updateIdealScale: E, getImageRect: D } = C(e, () => S.current ? {
+		width: S.current.naturalWidth,
+		height: S.current.naturalHeight
+	} : null);
+	function O(n) {
+		let r = y.current, i = S.current, a = e?.current;
+		if (!n || !r || !i?.naturalWidth || !a) return;
+		let { scale: o, origin: s } = n, c = i.naturalWidth * T.current * o, l = i.naturalHeight * T.current * o, u = a.getClientWidth(), d = a.getClientHeight();
+		i.style.width = `${c}px`, i.style.height = `${l}px`, i.style.padding = `${d}px ${u}px`, r.scrollTo(u + s.x * o, d + s.y * o), t?.(n, M);
+	}
+	function k() {
+		O(s?.stateService.getTransform());
+	}
+	function A() {
+		E(), k();
+	}
+	function j() {
+		E(), s?.fit(), k();
+	}
+	let M = {
+		getContainerRef: () => y.current,
+		getContentRef: () => S.current,
+		draw: O,
+		handleViewportResize: A,
+		getImageRect: () => D(y.current)
+	};
+	i(r, () => M);
+	let N = {
+		width: "100%",
+		height: "100%",
+		overflow: "hidden",
+		position: "relative",
+		...f
+	}, P = {
+		display: "block",
+		boxSizing: "content-box",
+		...h
+	};
+	return /* @__PURE__ */ l("div", {
+		style: N,
+		ref: y,
+		...m,
+		children: [/* @__PURE__ */ c("img", {
+			ref: S,
+			src: w || void 0,
+			style: P,
+			draggable: !1,
+			onLoad: j,
+			...v
+		}), n]
+	});
+}
+//#endregion
+//#region src/renderer/base.tsx
+var A = Object.freeze({
+	Canvas: "canvas",
+	Image: "image",
+	Html: "html"
+});
+//#endregion
+//#region src/GlideCanvas.tsx
+function j(e) {
+	let n = o(null), a = o(null), l = o(null), u = (e) => {
+		a.current = e;
+	}, [d, p] = s(!1), { config: m } = e, h = f({
+		...m,
+		getViewportRect: () => n.current?.getRect() || null,
+		getCanvasRect: () => a.current?.getImageRect?.() || null,
+		move: {
+			...m?.move,
+			onIsMovingChange(e) {
+				p(e), m?.move?.onIsMovingChange?.(e);
+			}
+		},
+		state: {
+			...m?.state,
+			onTransformChange() {
+				v();
+			}
+		}
+	});
+	function _(t) {
+		a.current?.handleViewportResize?.(t), e.viewportConfig?.onResize?.(t);
+	}
+	i(e.ref, () => ({
+		viewportRef: n.current,
+		canvasRef: a.current,
+		...h
+	}));
+	function v() {
+		l.current === null && (l.current = requestAnimationFrame(() => {
+			l.current = null;
+			let e = h.stateService.getTransform();
+			a.current?.draw?.(e), m?.state?.onTransformChange?.(t(e));
+		}));
+	}
+	return r(() => () => {
+		l.current !== null && cancelAnimationFrame(l.current);
+	}, []), /* @__PURE__ */ c(g, {
+		ref: n,
+		lib: h,
+		...e.viewportConfig,
+		style: {
+			cursor: d ? "grabbing" : h.isPanEnabled() ? "grab" : "default",
+			...e.viewportConfig?.style
+		},
+		onResize: _,
+		children: e.renderer === A.Image ? /* @__PURE__ */ c(O, {
+			viewportRef: n,
+			ref: u,
+			lib: h,
+			image: e.image,
+			...e.canvasConfig
+		}) : e.renderer === A.Html ? /* @__PURE__ */ c(k, {
+			viewportRef: n,
+			ref: u,
+			lib: h,
+			image: e.image,
+			...e.canvasConfig
+		}) : /* @__PURE__ */ c(T, {
+			viewportRef: n,
+			ref: u,
+			lib: h,
+			image: e.image,
+			...e.canvasConfig
+		})
+	});
+}
+//#endregion
+export { T as Canvas, j as GlideCanvas, k as HtmlCanvas, O as ImageCanvas, A as Renderer, g as Viewport, f as useGlideCanvas };

package/dist/renderer/Canvas.d.ts

@@ -0,0 +1,4 @@
+import { Renderer, RendererConfig } from './base.tsx';
+export type CanvasRendererProps = RendererConfig<typeof Renderer.Canvas>;
+export declare function Canvas({ viewportRef, ref, afterDraw, image, lib, container, content }: CanvasRendererProps): import("react").JSX.Element;
+export default Canvas;

package/dist/renderer/HtmlCanvas.d.ts

@@ -0,0 +1,13 @@
+import { Renderer, RendererConfig } from './base.tsx';
+export type HtmlRendererProps = RendererConfig<typeof Renderer.Html>;
+/**
+ * Scroll-based renderer: no CSS transforms and no <canvas>.
+ * Zoom resizes the <img> element itself (the browser re-rasterizes at the
+ * layout size, so it stays sharp — unlike transformed layers on Safari) and
+ * pan is a programmatic scroll of an overflow:hidden box (an element does not
+ * need visible scrollbars to be scrollable via scrollTo). The img's padding
+ * carries one viewport of slack on every side — a scroll range only exists
+ * where a descendant box occupies it, and padding is part of the img's border
+ * box — so the image can be panned fully off-screen in every direction.
+ */
+export declare function HtmlCanvas({ viewportRef, afterDraw, children, ref, image, lib, container, content, }: HtmlRendererProps): import("react").JSX.Element;

package/dist/renderer/ImageCanvas.d.ts

@@ -0,0 +1,3 @@
+import { Renderer, RendererConfig } from './base.tsx';
+export type ImageRendererProps = RendererConfig<typeof Renderer.Image>;
+export declare function ImageCanvas({ viewportRef, afterDraw, children, ref, image, lib, container, content, }: ImageRendererProps): import("react").JSX.Element;

package/dist/renderer/base.d.ts

@@ -0,0 +1,46 @@
+import { Rect, Transform } from 'canvas-glide';
+import { ViewportRef } from '../Viewport.tsx';
+import { HTMLProps, ReactNode, Ref, RefObject } from 'react';
+import { GlideCanvasInstance } from '../useGlideCanvas.ts';
+export type CanvasRef<T, C> = {
+    getContainerRef?: () => C | null;
+    getContentRef?: () => T | null;
+    getImageRect?: () => Rect;
+    handleViewportResize?: (viewport: ViewportRef) => void;
+    draw?: (transform?: Transform) => void;
+};
+export type RendererComponentProps<T> = HTMLProps<T> & {
+    className?: string;
+    style?: React.CSSProperties;
+};
+export type RendererProps<R extends Renderer, T = unknown, C = unknown> = {
+    content?: RendererComponentProps<T>;
+    container?: RendererComponentProps<C>;
+    children?: ReactNode | undefined;
+    afterDraw?: (transform?: Transform, data?: RendererRef[R]) => void;
+};
+export type RendererPropsMap = {
+    [Renderer.Canvas]: RendererProps<typeof Renderer.Canvas, HTMLCanvasElement, HTMLCanvasElement>;
+    [Renderer.Image]: RendererProps<typeof Renderer.Image, HTMLImageElement, HTMLDivElement>;
+    [Renderer.Html]: RendererProps<typeof Renderer.Html, HTMLImageElement, HTMLDivElement>;
+};
+export type BaseRenderConfig<R> = {
+    viewportRef?: RefObject<ViewportRef | null>;
+    image?: Blob | null;
+    lib?: GlideCanvasInstance;
+    ref?: Ref<R>;
+};
+export type RendererConfig<T extends Renderer> = RendererPropsMap[T] & BaseRenderConfig<RendererRef[T]>;
+export type RendererRef = {
+    [Renderer.Canvas]: CanvasRef<HTMLCanvasElement, HTMLCanvasElement>;
+    [Renderer.Image]: CanvasRef<HTMLImageElement, HTMLDivElement>;
+    [Renderer.Html]: CanvasRef<HTMLImageElement, HTMLDivElement>;
+};
+export type Renderer = (typeof Renderer)[keyof typeof Renderer];
+export declare const Renderer: Readonly<{
+    readonly Canvas: "canvas";
+    readonly Image: "image";
+    /** Renders the image as a resized, scrolled `<img>`, not arbitrary HTML. */
+    readonly Html: "html";
+}>;
+export type CanvasOptions<T extends Renderer> = RendererPropsMap[T];

package/dist/useGlideCanvas.d.ts

@@ -0,0 +1,18 @@
+import { PointerEventHandler, WheelEventHandler as ReactWheelEventHandler } from 'react';
+import { CanvasEngine, CanvasEngineOptions } from 'canvas-glide';
+export type GlideCanvasOptions = CanvasEngineOptions;
+export type BaseElement = Element;
+export type DomEventListener<T extends BaseElement, K extends keyof E, E extends HTMLElementEventMap = HTMLElementEventMap> = (this: T, ev: E[K]) => unknown;
+export type PointerDownEventHandler<T extends BaseElement> = DomEventListener<T, "pointerdown">;
+export type PointerUpEventHandler<T extends BaseElement> = DomEventListener<T, "pointerup">;
+export type PointerMoveEventHandler<T extends BaseElement> = DomEventListener<T, "pointermove">;
+export type WheelEventHandler<T extends BaseElement> = DomEventListener<T, "wheel">;
+export type GlideCanvasInstance = CanvasEngine & {
+    engine: CanvasEngine;
+    onPointerDown: PointerEventHandler<Element> & PointerDownEventHandler<Element>;
+    onPointerMove: PointerEventHandler<Element> & PointerMoveEventHandler<Element>;
+    onPointerUp: PointerEventHandler<Element> & PointerUpEventHandler<Element>;
+    onWheel: ReactWheelEventHandler<HTMLDivElement> & WheelEventHandler<Element>;
+};
+/** Creates the engine once: callbacks and rect getters follow the latest config, all other options are read at mount. */
+export declare function useGlideCanvas(config: GlideCanvasOptions): GlideCanvasInstance;

package/dist/util/asyncMemo.d.ts

@@ -0,0 +1,11 @@
+import { DependencyList } from 'react';
+/**
+ * Async-derived value tied to a dependency list.
+ *
+ * `dispose` releases a produced value when it is replaced, unmounted, or
+ * arrives after its generation was superseded (e.g. `(bitmap) => bitmap.close()`).
+ * Each effect run only ever disposes the value IT produced — never a newer
+ * generation's. A rejected `asyncFn` resolves the value to null instead of
+ * leaking an unhandled rejection.
+ */
+export declare function useAsyncMemo<T>(asyncFn: () => Promise<T>, dependencies: DependencyList, dispose?: (value: T) => void): T | null;

package/dist/util/constraint.d.ts

@@ -0,0 +1,9 @@
+import { Point, PointConstrainer, Rect } from 'canvas-glide';
+export declare const CONSTRAINT_THRESHOLD = 0;
+export type OriginConstrainerConfig = {
+    getViewportRect: () => Rect | null;
+    getCanvasRect: () => Rect | null;
+    getScale: () => number;
+};
+export declare function createConstrainer(config: OriginConstrainerConfig): PointConstrainer;
+export declare function constrainOrigin(origin: Point, scale: number, viewport: Rect, canvas: Rect): Point;

package/dist/util/event.d.ts

@@ -0,0 +1,2 @@
+export declare function attachWheelEvent<T extends HTMLElement>(element: T | null, handler: (e: WheelEvent) => void, options?: AddEventListenerOptions): (() => void) | undefined;
+export declare function attachEvent<K extends keyof HTMLElementEventMap, T extends HTMLElement | Window>(event: K, element: T | null, handler: (this: T, ev: HTMLElementEventMap[K]) => any, options?: AddEventListenerOptions | boolean): (() => void) | undefined;

package/dist/util/image.d.ts

@@ -0,0 +1,3 @@
+export declare function createImageBitmapSafe(blob?: Blob | null | undefined): Promise<ImageBitmap | null>;
+export declare function createImageUrlSafe(blob?: Blob | null | undefined): Promise<string | null>;
+export declare function revokeImageUrl(url: string | null): void;

package/dist/util/useIdealScale.d.ts

@@ -0,0 +1,20 @@
+import { RefObject } from 'react';
+import { Rect } from 'canvas-glide';
+import { ViewportRef } from '../Viewport.tsx';
+export type ContentSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Shared contain-fit state for renderers: `idealScale` maps the content's
+ * natural size to the viewport at engine scale 1, so engine origins are
+ * expressed in the same scale-1 frame for every renderer.
+ */
+export declare function useIdealScale(viewportRef: RefObject<ViewportRef | null> | undefined, getContentSize: () => ContentSize | null): {
+    idealScale: RefObject<number>;
+    updateIdealScale: () => void;
+    getImageRect: (element: {
+        offsetLeft: number;
+        offsetTop: number;
+    } | null) => Rect;
+};

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@canvas-glide/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "React components and hook for canvas-glide: pan, zoom and pinch-to-zoom for images on a canvas, an img or a scrolled view, with mouse, touch, pen and wheel input.",
+  "keywords": [
+    "react",
+    "react-component",
+    "pan-zoom",
+    "panzoom",
+    "pinch-zoom",
+    "pinch-to-zoom",
+    "zoom",
+    "pan",
+    "image-viewer",
+    "image-zoom",
+    "canvas",
+    "gestures",
+    "touch",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://vrtexe.github.io/canvas-glide-react-demo/",
+  "bugs": {
+    "url": "https://github.com/vrtexe/canvas-glide-react/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vrtexe/canvas-glide-react.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:dev": "tsc -b && vite build --watch",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "canvas-glide": "^1.0.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "main": "./dist/canvas-glide.js",
+  "types": "./dist/canvas-glide.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/canvas-glide.d.ts",
+      "default": "./dist/canvas-glide.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.4",
+    "jsdom": "^31.0.1",
+    "localforage": "^1.10.0",
+    "oxlint": "^1.75.0",
+    "typescript": "~6.0.2",
+    "vite": "^8.2.0",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^5.1.0"
+  }
+}