@olenbetong/synergi-react 2.3.8 → 2.3.9

package/src/components/ImageEditor/plugins/redactPlugin/useRedactTool.ts

@@ -0,0 +1,197 @@
+import { useCallback, useRef, useState } from "react";
+
+import type { EditAction } from "../../types.js";
+
+export interface RedactRect {
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+}
+
+interface Drawing {
+	startX: number;
+	startY: number;
+	currentX: number;
+	currentY: number;
+}
+
+export interface ApplyRedactResult {
+	blob: Blob;
+	actions: EditAction[];
+}
+
+export interface RedactToolState {
+	rects: RedactRect[];
+	drawing: Drawing | null;
+	displaySize: { width: number; height: number };
+	handleImageLoad: (e: React.SyntheticEvent<HTMLImageElement>) => void;
+	startDrawing: (x: number, y: number) => void;
+	updateDrawing: (x: number, y: number) => void;
+	finishDrawing: () => void;
+	deleteRect: (index: number) => void;
+	clearAll: () => void;
+	applyRedact: () => Promise<ApplyRedactResult | null>;
+}
+
+/** Manages state and logic for the blur-redaction tool. */
+export function useRedactTool(imageUrl: string): RedactToolState {
+	let [rects, setRects] = useState<RedactRect[]>([]);
+	let [drawing, setDrawing] = useState<Drawing | null>(null);
+	let [displaySize, setDisplaySize] = useState({ width: 0, height: 0 });
+	let imageUrlRef = useRef(imageUrl);
+	imageUrlRef.current = imageUrl;
+
+	let handleImageLoad = useCallback((e: React.SyntheticEvent<HTMLImageElement>) => {
+		let img = e.currentTarget;
+		setDisplaySize({ width: img.clientWidth, height: img.clientHeight });
+	}, []);
+
+	function startDrawing(x: number, y: number) {
+		setDrawing({ startX: x, startY: y, currentX: x, currentY: y });
+	}
+
+	function updateDrawing(x: number, y: number) {
+		setDrawing((d) => (d ? { ...d, currentX: x, currentY: y } : null));
+	}
+
+	function finishDrawing() {
+		setDrawing((d) => {
+			if (!d) return null;
+			let x = Math.min(d.startX, d.currentX);
+			let y = Math.min(d.startY, d.currentY);
+			let w = Math.abs(d.currentX - d.startX);
+			let h = Math.abs(d.currentY - d.startY);
+			if (w > 4 && h > 4) {
+				setRects((prev) => [...prev, { x, y, w, h }]);
+			}
+			return null;
+		});
+	}
+
+	function deleteRect(index: number) {
+		setRects((prev) => prev.filter((_, i) => i !== index));
+	}
+
+	function clearAll() {
+		setRects([]);
+	}
+
+	async function applyRedact(): Promise<ApplyRedactResult | null> {
+		if (rects.length === 0) return null;
+		let img = await loadImage(imageUrlRef.current);
+		let canvas = document.createElement("canvas");
+		canvas.width = img.naturalWidth;
+		canvas.height = img.naturalHeight;
+		let ctx = canvas.getContext("2d")!;
+		ctx.drawImage(img, 0, 0);
+
+		let scaleX = img.naturalWidth / displaySize.width;
+		let scaleY = img.naturalHeight / displaySize.height;
+
+		for (let r of rects) {
+			let nx = Math.round(r.x * scaleX);
+			let ny = Math.round(r.y * scaleY);
+			let nw = Math.round(r.w * scaleX);
+			let nh = Math.round(r.h * scaleY);
+			blurRegionOnCanvas(ctx, img, nx, ny, nw, nh);
+		}
+
+		let blob = await new Promise<Blob>((resolve, reject) => {
+			canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("toBlob failed"))), "image/jpeg", 0.92);
+		});
+		// Store natural-pixel coords so replay doesn't need display size.
+		let actions: EditAction[] = rects.map((r) => ({
+			type: "redact-blur",
+			params: {
+				x: Math.round(r.x * scaleX),
+				y: Math.round(r.y * scaleY),
+				w: Math.round(r.w * scaleX),
+				h: Math.round(r.h * scaleY),
+			},
+		}));
+		return { blob, actions };
+	}
+
+	return {
+		rects,
+		drawing,
+		displaySize,
+		handleImageLoad,
+		startDrawing,
+		updateDrawing,
+		finishDrawing,
+		deleteRect,
+		clearAll,
+		applyRedact,
+	};
+}
+
+function loadImage(url: string): Promise<HTMLImageElement> {
+	return new Promise((resolve, reject) => {
+		let img = new Image();
+		img.onload = () => resolve(img);
+		img.onerror = () => reject(new Error("Failed to load image"));
+		img.src = url;
+	});
+}
+
+/** Standalone replay handler for the "redact-blur" action type. */
+export function replayRedactBlur(imageUrl: string, params: Record<string, unknown>): Promise<Blob> {
+	let { x, y, w, h } = params as { x: number; y: number; w: number; h: number };
+
+	return new Promise((resolve, reject) => {
+		let img = new Image();
+		img.onload = () => {
+			let canvas = document.createElement("canvas");
+			canvas.width = img.naturalWidth;
+			canvas.height = img.naturalHeight;
+			let ctx = canvas.getContext("2d")!;
+			ctx.drawImage(img, 0, 0);
+			blurRegionOnCanvas(ctx, img, x, y, w, h);
+			canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("toBlob failed"))), "image/jpeg", 0.92);
+		};
+		img.onerror = () => reject(new Error("Failed to load image for redact replay"));
+		img.src = imageUrl;
+	});
+}
+
+/**
+ * Redacts a region by downscaling it to a tiny thumbnail then scaling back up.
+ * This produces a strong pixelation effect that is cross-browser (ctx.filter
+ * is unreliable in Firefox).
+ */
+function blurRegionOnCanvas(
+	ctx: CanvasRenderingContext2D,
+	img: HTMLImageElement,
+	x: number,
+	y: number,
+	w: number,
+	h: number,
+) {
+	if (w <= 0 || h <= 0) return;
+	// Scale down to ~5% — each output "pixel" covers a 20×20 block of the original.
+	let smallW = Math.max(1, Math.round(w / 20));
+	let smallH = Math.max(1, Math.round(h / 20));
+	let off = document.createElement("canvas");
+	off.width = smallW;
+	off.height = smallH;
+	let offCtx = off.getContext("2d")!;
+	offCtx.drawImage(img, x, y, w, h, 0, 0, smallW, smallH);
+	ctx.imageSmoothingEnabled = true;
+	ctx.imageSmoothingQuality = "low";
+	ctx.drawImage(off, 0, 0, smallW, smallH, x, y, w, h);
+	// Overlay a semi-opaque fill to prevent text from being readable through the pixelation.
+	ctx.fillStyle = "rgba(128, 128, 128, 0.85)";
+	ctx.fillRect(x, y, w, h);
+}
+
+/** Normalises a drawing into a positional rect (min x/y, positive w/h). */
+export function normRect(d: { startX: number; startY: number; currentX: number; currentY: number }) {
+	return {
+		x: Math.min(d.startX, d.currentX),
+		y: Math.min(d.startY, d.currentY),
+		w: Math.abs(d.currentX - d.startX),
+		h: Math.abs(d.currentY - d.startY),
+	};
+}

package/src/components/ImageEditor/plugins/rotatePlugin.ts

@@ -0,0 +1,43 @@
+import RotateLeftIcon from "@mui/icons-material/RotateLeft";
+import RotateRightIcon from "@mui/icons-material/RotateRight";
+
+import type { ActionPlugin } from "../types.js";
+
+function rotateBlob(imageUrl: string, direction: "cw" | "ccw"): Promise<Blob> {
+	return new Promise((resolve, reject) => {
+		let img = new Image();
+		img.onload = () => {
+			let canvas = document.createElement("canvas");
+			canvas.width = img.naturalHeight;
+			canvas.height = img.naturalWidth;
+			let ctx = canvas.getContext("2d")!;
+			if (direction === "cw") {
+				ctx.translate(canvas.width, 0);
+				ctx.rotate(Math.PI / 2);
+			} else {
+				ctx.translate(0, canvas.height);
+				ctx.rotate(-Math.PI / 2);
+			}
+			ctx.drawImage(img, 0, 0);
+			canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("toBlob failed"))), "image/jpeg", 0.92);
+		};
+		img.onerror = () => reject(new Error("Failed to load image"));
+		img.src = imageUrl;
+	});
+}
+
+export const rotateCcwPlugin: ActionPlugin = {
+	type: "action",
+	id: "rotate-ccw",
+	label: "Rotate left",
+	Icon: RotateLeftIcon,
+	execute: (url) => rotateBlob(url, "ccw"),
+};
+
+export const rotateCwPlugin: ActionPlugin = {
+	type: "action",
+	id: "rotate-cw",
+	label: "Rotate right",
+	Icon: RotateRightIcon,
+	execute: (url) => rotateBlob(url, "cw"),
+};

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomCanvas.tsx

@@ -0,0 +1,123 @@
+import { type ReactNode, useEffect, useRef } from "react";
+import { ZOOM_STEP } from "./useZoomPan.js";
+import { useZoom } from "./ZoomContext.js";
+
+interface Props {
+	children: ReactNode;
+	/**
+	 * Whether single-pointer drag pans the canvas. Pass false in tool mode so
+	 * 1-finger events are owned by the tool; 2-finger pinch/drag still works.
+	 * Defaults to true.
+	 */
+	panEnabled?: boolean;
+}
+
+/**
+ * Fills the canvas area, applies zoom/pan transform to its children, and
+ * captures pointer events for gestures.
+ *
+ * • Ctrl/Cmd + scroll: zoom anchored at cursor (desktop)
+ * • 2-finger pinch + translate: simultaneous zoom + pan anchored at midpoint
+ * • 1-finger drag (when panEnabled): pan
+ */
+export function ZoomCanvas({ children, panEnabled = true }: Props) {
+	let { zoom, panX, panY, pan, panAndZoomAtPoint, zoomByDeltaAtPoint } = useZoom();
+
+	let containerRef = useRef<HTMLDivElement>(null);
+	let pointers = useRef(new Map<number, { x: number; y: number }>());
+	let lastPinchDist = useRef<number | null>(null);
+	let lastPinchMid = useRef<{ x: number; y: number } | null>(null);
+
+	// Stable refs so the DOM wheel listener never needs re-registration.
+	let panRef = useRef(pan);
+	let panAndZoomAtPointRef = useRef(panAndZoomAtPoint);
+	let zoomByDeltaAtPointRef = useRef(zoomByDeltaAtPoint);
+	panRef.current = pan;
+	panAndZoomAtPointRef.current = panAndZoomAtPoint;
+	zoomByDeltaAtPointRef.current = zoomByDeltaAtPoint;
+
+	function focalFromClient(clientX: number, clientY: number) {
+		let rect = containerRef.current?.getBoundingClientRect();
+		if (!rect) return { fx: 0, fy: 0 };
+		return { fx: clientX - rect.left - rect.width / 2, fy: clientY - rect.top - rect.height / 2 };
+	}
+
+	useEffect(() => {
+		let el = containerRef.current;
+		if (!el) return;
+
+		function onWheel(e: WheelEvent) {
+			if (!e.ctrlKey && !e.metaKey) return;
+			e.preventDefault();
+			let { fx, fy } = focalFromClient(e.clientX, e.clientY);
+			zoomByDeltaAtPointRef.current(e.deltaY < 0 ? ZOOM_STEP : -ZOOM_STEP, fx, fy);
+		}
+
+		el.addEventListener("wheel", onWheel, { passive: false });
+		return () => el.removeEventListener("wheel", onWheel);
+	}, []);
+
+	function onPointerDown(e: React.PointerEvent) {
+		// Only capture the pointer for panning. In tool mode (panEnabled=false) the inner
+		// tool elements (DragHandle, redact SVG) call setPointerCapture themselves after
+		// this event bubbles up — don't override their capture.
+		if (panEnabled) {
+			e.currentTarget.setPointerCapture(e.pointerId);
+		}
+		pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+		lastPinchDist.current = null;
+		lastPinchMid.current = null;
+	}
+
+	function onPointerMove(e: React.PointerEvent) {
+		// Ignore hover — only process pointers that went through onPointerDown.
+		if (!pointers.current.has(e.pointerId)) return;
+
+		let prev = pointers.current.get(e.pointerId);
+		pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+
+		if (pointers.current.size === 2) {
+			let [a, b] = [...pointers.current.values()];
+			let dist = Math.hypot(a.x - b.x, a.y - b.y);
+			let midX = (a.x + b.x) / 2;
+			let midY = (a.y + b.y) / 2;
+
+			if (lastPinchDist.current !== null && lastPinchDist.current > 0) {
+				let { fx, fy } = focalFromClient(midX, midY);
+				let scaleFactor = dist / lastPinchDist.current;
+				// Translate from midpoint movement + zoom from pinch — both in one state update.
+				let dx = lastPinchMid.current ? midX - lastPinchMid.current.x : 0;
+				let dy = lastPinchMid.current ? midY - lastPinchMid.current.y : 0;
+				panAndZoomAtPointRef.current(dx, dy, scaleFactor, fx, fy);
+			}
+
+			lastPinchDist.current = dist;
+			lastPinchMid.current = { x: midX, y: midY };
+		} else if (pointers.current.size === 1 && prev && panEnabled) {
+			panRef.current(e.clientX - prev.x, e.clientY - prev.y);
+		}
+	}
+
+	function onPointerUp(e: React.PointerEvent) {
+		pointers.current.delete(e.pointerId);
+		if (pointers.current.size < 2) {
+			lastPinchDist.current = null;
+			lastPinchMid.current = null;
+		}
+	}
+
+	return (
+		<div
+			ref={containerRef}
+			className="zoom-canvas-root"
+			onPointerDown={onPointerDown}
+			onPointerMove={onPointerMove}
+			onPointerUp={onPointerUp}
+			onPointerCancel={onPointerUp}
+		>
+			<div className="zoom-canvas-inner" style={{ transform: `translate(${panX}px, ${panY}px) scale(${zoom})` }}>
+				{children}
+			</div>
+		</div>
+	);
+}

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomContext.tsx

@@ -0,0 +1,15 @@
+import { createContext, type ReactNode, use } from "react";
+import { useZoomPan, type ZoomPanResult } from "./useZoomPan.js";
+
+let ZoomContext = createContext<ZoomPanResult | null>(null);
+
+export function useZoom(): ZoomPanResult {
+	let ctx = use(ZoomContext);
+	if (!ctx) throw new Error("useZoom must be used within ZoomProvider");
+	return ctx;
+}
+
+export function ZoomProvider({ children }: { children: ReactNode }) {
+	let state = useZoomPan();
+	return <ZoomContext value={state}>{children}</ZoomContext>;
+}

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomControls.tsx

@@ -0,0 +1,43 @@
+import ZoomInIcon from "@mui/icons-material/ZoomIn";
+import ZoomInMapIcon from "@mui/icons-material/ZoomInMap";
+import ZoomOutIcon from "@mui/icons-material/ZoomOut";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import { ResponsiveButton } from "../../ResponsiveButton.js";
+import { useZoom } from "./ZoomContext.js";
+
+interface Props {
+	disabled?: boolean;
+	isSmall?: boolean;
+}
+
+export function ZoomControls({ disabled, isSmall = false }: Props) {
+	let { zoom, zoomIn, zoomOut, resetZoom, canZoomIn, canZoomOut, isZoomed } = useZoom();
+
+	return (
+		<>
+			<ResponsiveButton
+				icon={<ZoomOutIcon />}
+				label={getLocalizedString("Zoom out")}
+				onClick={zoomOut}
+				disabled={disabled || !canZoomOut}
+				isSmall={isSmall}
+			/>
+			<span className="image-editor__zoom-level">{Math.round(zoom * 100)}%</span>
+			<ResponsiveButton
+				icon={<ZoomInIcon />}
+				label={getLocalizedString("Zoom in")}
+				onClick={zoomIn}
+				disabled={disabled || !canZoomIn}
+				isSmall={isSmall}
+			/>
+			{isZoomed && (
+				<ResponsiveButton
+					icon={<ZoomInMapIcon />}
+					label={getLocalizedString("Reset zoom")}
+					onClick={resetZoom}
+					isSmall={isSmall}
+				/>
+			)}
+		</>
+	);
+}

package/src/components/ImageEditor/plugins/zoomPlugin/index.ts

@@ -0,0 +1,12 @@
+import type { ViewPlugin } from "../../types.js";
+import { ZoomCanvas } from "./ZoomCanvas.js";
+import { ZoomProvider } from "./ZoomContext.js";
+import { ZoomControls } from "./ZoomControls.js";
+
+export const zoomPlugin: ViewPlugin = {
+	type: "view",
+	id: "zoom",
+	Provider: ZoomProvider,
+	CanvasWrapper: ZoomCanvas,
+	TopBarControls: ZoomControls,
+};

package/src/components/ImageEditor/plugins/zoomPlugin/useZoomPan.ts

@@ -0,0 +1,126 @@
+import { useCallback, useState } from "react";
+
+export const MIN_ZOOM = 0.5;
+export const MAX_ZOOM = 5;
+export const ZOOM_STEP = 0.25;
+
+interface State {
+	zoom: number;
+	panX: number;
+	panY: number;
+}
+
+export interface ZoomPanResult {
+	zoom: number;
+	panX: number;
+	panY: number;
+	canZoomIn: boolean;
+	canZoomOut: boolean;
+	isZoomed: boolean;
+	zoomIn: () => void;
+	zoomOut: () => void;
+	resetZoom: () => void;
+	/** Translate by (dx, dy) screen pixels. */
+	pan: (dx: number, dy: number) => void;
+	/**
+	 * Zoom by a multiplicative scale factor, anchored at a focal point.
+	 * focalX/focalY are in px relative to the container centre.
+	 */
+	zoomByScaleAtPoint: (scaleFactor: number, focalX: number, focalY: number) => void;
+	/**
+	 * Zoom by an additive step delta, anchored at a focal point.
+	 * focalX/focalY are in px relative to the container centre.
+	 */
+	zoomByDeltaAtPoint: (delta: number, focalX: number, focalY: number) => void;
+	/**
+	 * Simultaneously pan by (dx, dy) and zoom by a multiplicative scale factor,
+	 * anchored at a focal point. Used for 2-finger gestures where the midpoint
+	 * may translate while the fingers pinch.
+	 */
+	panAndZoomAtPoint: (dx: number, dy: number, scaleFactor: number, focalX: number, focalY: number) => void;
+}
+
+export function useZoomPan(): ZoomPanResult {
+	let [{ zoom, panX, panY }, setState] = useState<State>({ zoom: 1, panX: 0, panY: 0 });
+
+	let zoomIn = useCallback(() => {
+		// Zoom from centre (focalX = 0, focalY = 0)
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, s.zoom + ZOOM_STEP).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return { zoom: newZoom, panX: s.panX * scale, panY: s.panY * scale };
+		});
+	}, []);
+
+	let zoomOut = useCallback(() => {
+		setState((s) => {
+			let newZoom = +Math.max(MIN_ZOOM, s.zoom - ZOOM_STEP).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return { zoom: newZoom, panX: s.panX * scale, panY: s.panY * scale };
+		});
+	}, []);
+
+	let resetZoom = useCallback(() => {
+		setState({ zoom: 1, panX: 0, panY: 0 });
+	}, []);
+
+	let pan = useCallback((dx: number, dy: number) => {
+		setState((s) => ({ ...s, panX: s.panX + dx, panY: s.panY + dy }));
+	}, []);
+
+	let zoomByScaleAtPoint = useCallback((scaleFactor: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom * scaleFactor)).toFixed(3);
+			let realScale = newZoom / s.zoom;
+			return {
+				zoom: newZoom,
+				// Keep the focal point fixed on screen: pan adjusts to compensate for the zoom shift.
+				panX: focalX * (1 - realScale) + s.panX * realScale,
+				panY: focalY * (1 - realScale) + s.panY * realScale,
+			};
+		});
+	}, []);
+
+	let zoomByDeltaAtPoint = useCallback((delta: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom + delta)).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return {
+				zoom: newZoom,
+				panX: focalX * (1 - scale) + s.panX * scale,
+				panY: focalY * (1 - scale) + s.panY * scale,
+			};
+		});
+	}, []);
+
+	let panAndZoomAtPoint = useCallback((dx: number, dy: number, scaleFactor: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom * scaleFactor)).toFixed(3);
+			let realScale = newZoom / s.zoom;
+			// Apply pan first, then zoom around the focal point.
+			let panXAfterPan = s.panX + dx;
+			let panYAfterPan = s.panY + dy;
+			return {
+				zoom: newZoom,
+				panX: focalX * (1 - realScale) + panXAfterPan * realScale,
+				panY: focalY * (1 - realScale) + panYAfterPan * realScale,
+			};
+		});
+	}, []);
+
+	return {
+		zoom,
+		panX,
+		panY,
+		canZoomIn: zoom < MAX_ZOOM,
+		canZoomOut: zoom > MIN_ZOOM,
+		isZoomed: zoom !== 1 || panX !== 0 || panY !== 0,
+		zoomIn,
+		zoomOut,
+		resetZoom,
+		pan,
+		zoomByScaleAtPoint,
+		zoomByDeltaAtPoint,
+		panAndZoomAtPoint,
+	};
+}

package/src/components/ImageEditor/types.ts

@@ -0,0 +1,69 @@
+import type { ComponentType, ReactNode } from "react";
+
+/** A single atomic edit operation, recorded for undo/redo replay. */
+export interface EditAction {
+	type: string;
+	params: Record<string, unknown>;
+}
+
+/**
+ * Registers a replay handler for a specific action type.
+ * Must be a pure async function — no React hooks, no side-effect state.
+ */
+export interface ActionHandler {
+	type: string;
+	apply: (imageUrl: string, params: Record<string, unknown>) => Promise<Blob>;
+}
+
+/** Maps action type → replay function. Built by ImageEditor from the plugins array. */
+export type ActionRegistry = Map<string, ActionHandler["apply"]>;
+
+export interface ToolProviderProps {
+	imageUrl: string;
+	/** Called when the tool has produced a transformed image. */
+	onApply: (blob: Blob, actions: EditAction[]) => void;
+	onCancel: () => void;
+	children: ReactNode;
+}
+
+/**
+ * A mode tool: activates a persistent editing state with its own canvas overlay and toolbar.
+ * The Provider shares state between Overlay and Toolbar via React context.
+ * `actions` registers replay handlers so the history can reconstruct any past state.
+ */
+export interface ToolPlugin {
+	type: "tool";
+	id: string;
+	label: string;
+	Icon: ComponentType;
+	Provider: ComponentType<ToolProviderProps>;
+	Overlay: ComponentType;
+	Toolbar: ComponentType;
+	/** Replay handlers for every action type this tool can produce. */
+	actions: ActionHandler[];
+}
+
+/** An action tool: executes a transform immediately without entering a persistent mode. */
+export interface ActionPlugin {
+	type: "action";
+	id: string;
+	label: string;
+	Icon: ComponentType;
+	execute: (imageUrl: string) => Promise<Blob>;
+}
+
+export type Plugin = ToolPlugin | ActionPlugin;
+
+/**
+ * A view plugin: provides zoom/pan or other viewport transforms without modifying the image.
+ * Wraps the main image area with gesture handling and contributes controls to the top toolbar.
+ */
+export interface ViewPlugin {
+	type: "view";
+	id: string;
+	Provider: ComponentType<{ children: ReactNode }>;
+	/** Wraps the main image; applies transforms and captures pinch/pan gestures. */
+	CanvasWrapper: ComponentType<{ children: ReactNode; panEnabled?: boolean }>;
+	/** Controls rendered in the top toolbar (e.g. zoom in/out/reset). */
+	TopBarControls: ComponentType<{ disabled?: boolean; isSmall?: boolean }>;
+}

package/src/components/ImageEditor/useActiveTool.ts

@@ -0,0 +1,21 @@
+import { useState } from "react";
+
+import type { Plugin, ToolPlugin } from "./types.js";
+
+interface UseActiveToolResult {
+	activePlugin: ToolPlugin | null;
+	activateTool: (id: string) => void;
+	deactivateTool: () => void;
+}
+
+/** Manages which tool plugin is currently active. */
+export function useActiveTool(plugins: Plugin[]): UseActiveToolResult {
+	let [activeId, setActiveId] = useState<string | null>(null);
+	let activePlugin = (plugins.find((p) => p.type === "tool" && p.id === activeId) ?? null) as ToolPlugin | null;
+
+	return {
+		activePlugin,
+		activateTool: setActiveId,
+		deactivateTool: () => setActiveId(null),
+	};
+}