@devbycrux/editor 0.1.0

package/src/crop/CanvasCropOverlay.tsx

@@ -0,0 +1,193 @@
+import * as React from 'react'
+import type { ImageElement } from '../types'
+import {
+  renderedSourceRect,
+  fractionToWrapperPx,
+  applyCropHandleDrag,
+  type CropHandle,
+} from './crop-math'
+
+const CROP_HANDLES: CropHandle[] = ['nw', 'n', 'ne', 'w', 'e', 'sw', 's', 'se']
+
+const HANDLE_OFFSET: Record<CropHandle, { dx: 0 | 0.5 | 1; dy: 0 | 0.5 | 1; cursor: string }> = {
+  nw: { dx: 0,   dy: 0,   cursor: 'nw-resize' },
+  n:  { dx: 0.5, dy: 0,   cursor: 'n-resize'  },
+  ne: { dx: 1,   dy: 0,   cursor: 'ne-resize' },
+  w:  { dx: 0,   dy: 0.5, cursor: 'w-resize'  },
+  e:  { dx: 1,   dy: 0.5, cursor: 'e-resize'  },
+  sw: { dx: 0,   dy: 1,   cursor: 'sw-resize' },
+  s:  { dx: 0.5, dy: 1,   cursor: 's-resize'  },
+  se: { dx: 1,   dy: 1,   cursor: 'se-resize' },
+}
+
+export type CanvasCropOverlayProps = {
+  /**
+   * The image element being cropped. Passed to `resolveImageSrc` to obtain a
+   * displayable URL — the overlay never constructs URLs itself.
+   */
+  element: ImageElement
+  /**
+   * Host-supplied resolver. Implement as `(el) => adapter.resolveImageSrc(el)`
+   * on the caller side; the overlay stays host-agnostic.
+   */
+  resolveImageSrc: (element: ImageElement) => string
+  /** Canvas scale factor (CSS pixels per logical element unit). */
+  scale: number
+  /** Current crop as source fractions. Controlled — caller owns the state. */
+  localCrop: { x: number; y: number; w: number; h: number }
+  /** Called on every pointer-move while a handle is held. */
+  onLocalCropChange: (next: { x: number; y: number; w: number; h: number }) => void
+  /** Called once when the <img> fires onLoad with the source's natural dims. */
+  onSrcDimsLoaded: (dims: { width: number; height: number }) => void
+  /** Natural dimensions of the source image, if already known. */
+  srcDims?: { width: number; height: number }
+}
+
+export function CanvasCropOverlay({
+  element,
+  resolveImageSrc,
+  scale,
+  localCrop,
+  onLocalCropChange,
+  onSrcDimsLoaded,
+  srcDims,
+}: CanvasCropOverlayProps) {
+  const srcUrl = resolveImageSrc(element)
+
+  const wrapperW = element.w * scale
+  const wrapperH = element.h * scale
+
+  const rendered = srcDims
+    ? renderedSourceRect({ wrapperW, wrapperH, srcWidth: srcDims.width, srcHeight: srcDims.height })
+    : null
+  const windowPx = rendered ? fractionToWrapperPx({ crop: localCrop, rendered }) : null
+
+  const dragStateRef = React.useRef<{
+    handle: CropHandle
+    startClient: { x: number; y: number }
+    startCrop: { x: number; y: number; w: number; h: number }
+  } | null>(null)
+
+  const onHandlePointerDown = (handle: CropHandle, e: React.PointerEvent<HTMLDivElement>) => {
+    e.stopPropagation()
+    e.currentTarget.setPointerCapture(e.pointerId)
+    dragStateRef.current = {
+      handle,
+      startClient: { x: e.clientX, y: e.clientY },
+      startCrop: localCrop,
+    }
+  }
+
+  const onHandlePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const drag = dragStateRef.current
+    if (!drag || !srcDims) return
+    const dx = e.clientX - drag.startClient.x
+    const dy = e.clientY - drag.startClient.y
+    const next = applyCropHandleDrag({
+      handle: drag.handle,
+      initialCrop: drag.startCrop,
+      deltaPx: { x: dx, y: dy },
+      wrapperW,
+      wrapperH,
+      srcWidth: srcDims.width,
+      srcHeight: srcDims.height,
+    })
+    onLocalCropChange(next)
+  }
+
+  const onHandlePointerUp = () => {
+    dragStateRef.current = null
+  }
+
+  return (
+    <div
+      style={{ position: 'absolute', inset: 0, overflow: 'hidden', pointerEvents: 'auto' }}
+      onPointerDown={(e) => {
+        e.stopPropagation()
+      }}
+    >
+      {/* Letterbox preview of the full source image */}
+      <img
+        src={srcUrl}
+        alt="Crop source"
+        onLoad={(e) => {
+          const img = e.currentTarget
+          onSrcDimsLoaded({ width: img.naturalWidth, height: img.naturalHeight })
+        }}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          objectFit: 'contain',
+          pointerEvents: 'none',
+        }}
+      />
+
+      {windowPx && (
+        <>
+          {/* Dark dimming mask outside the crop window */}
+          <div
+            data-testid="crop-dim"
+            style={{
+              position: 'absolute',
+              inset: 0,
+              background: 'rgba(0, 0, 0, 0.55)',
+              clipPath: `polygon(
+                0 0, 100% 0, 100% 100%, 0 100%, 0 0,
+                ${windowPx.x}px ${windowPx.y}px,
+                ${windowPx.x}px ${windowPx.y + windowPx.h}px,
+                ${windowPx.x + windowPx.w}px ${windowPx.y + windowPx.h}px,
+                ${windowPx.x + windowPx.w}px ${windowPx.y}px,
+                ${windowPx.x}px ${windowPx.y}px
+              )`,
+              pointerEvents: 'none',
+            }}
+          />
+
+          {/* Crop window border */}
+          <div
+            data-testid="crop-window"
+            style={{
+              position: 'absolute',
+              left: windowPx.x,
+              top: windowPx.y,
+              width: windowPx.w,
+              height: windowPx.h,
+              outline: '2px solid var(--editor-selection)',
+              pointerEvents: 'none',
+            }}
+          />
+
+          {/* 8 resize handles */}
+          {CROP_HANDLES.map((handle) => {
+            const o = HANDLE_OFFSET[handle]
+            return (
+              <div
+                key={handle}
+                data-testid={`crop-handle-${handle}`}
+                onPointerDown={(e) => onHandlePointerDown(handle, e)}
+                onPointerMove={onHandlePointerMove}
+                onPointerUp={onHandlePointerUp}
+                style={{
+                  position: 'absolute',
+                  left: windowPx.x + o.dx * windowPx.w - 6,
+                  top: windowPx.y + o.dy * windowPx.h - 6,
+                  width: 12,
+                  height: 12,
+                  backgroundColor: '#fff',
+                  border: '1.5px solid var(--editor-selection)',
+                  borderRadius: 2,
+                  cursor: o.cursor,
+                  zIndex: 10,
+                  pointerEvents: 'auto',
+                  touchAction: 'none',
+                }}
+              />
+            )
+          })}
+        </>
+      )}
+    </div>
+  )
+}

package/src/crop/__tests__/crop-math.test.ts

@@ -0,0 +1,174 @@
+/// <reference types="vitest/globals" />
+import { renderedSourceRect } from '../crop-math'
+import { fractionToWrapperPx, wrapperPxToFraction } from '../crop-math'
+
+describe('renderedSourceRect', () => {
+  it('1. fits source to width when source is wider than wrapper (letterboxes top/bottom)', () => {
+    // wrapper 400x500 (aspect 0.8), source 1920x1080 (aspect 1.78)
+    const result = renderedSourceRect({ wrapperW: 400, wrapperH: 500, srcWidth: 1920, srcHeight: 1080 })
+    expect(result.width).toBeCloseTo(400)
+    expect(result.height).toBeCloseTo(400 / (1920 / 1080)) // ≈ 225
+    expect(result.offsetX).toBeCloseTo(0)
+    expect(result.offsetY).toBeCloseTo((500 - 225) / 2) // ≈ 137.5
+  })
+
+  it('2. fits source to height when source is taller than wrapper (letterboxes left/right)', () => {
+    // wrapper 500x400 (aspect 1.25), source 1080x1920 (aspect 0.5625)
+    const result = renderedSourceRect({ wrapperW: 500, wrapperH: 400, srcWidth: 1080, srcHeight: 1920 })
+    expect(result.height).toBeCloseTo(400)
+    expect(result.width).toBeCloseTo(400 * (1080 / 1920)) // ≈ 225
+    expect(result.offsetY).toBeCloseTo(0)
+    expect(result.offsetX).toBeCloseTo((500 - 225) / 2) // ≈ 137.5
+  })
+
+  it('3. exact aspect match — no letterbox', () => {
+    const result = renderedSourceRect({ wrapperW: 400, wrapperH: 500, srcWidth: 800, srcHeight: 1000 })
+    expect(result.width).toBeCloseTo(400)
+    expect(result.height).toBeCloseTo(500)
+    expect(result.offsetX).toBeCloseTo(0)
+    expect(result.offsetY).toBeCloseTo(0)
+  })
+})
+
+describe('fractionToWrapperPx', () => {
+  it('4. maps source-fraction crop to wrapper pixels via the rendered source rect', () => {
+    const rendered = { offsetX: 0, offsetY: 137.5, width: 400, height: 225 }
+    const crop = { x: 0.1, y: 0.2, w: 0.5, h: 0.6 }
+    const px = fractionToWrapperPx({ crop, rendered })
+    expect(px.x).toBeCloseTo(0 + 0.1 * 400)        // 40
+    expect(px.y).toBeCloseTo(137.5 + 0.2 * 225)     // 182.5
+    expect(px.w).toBeCloseTo(0.5 * 400)             // 200
+    expect(px.h).toBeCloseTo(0.6 * 225)             // 135
+  })
+})
+
+describe('wrapperPxToFraction', () => {
+  it('5. round-trips with fractionToWrapperPx', () => {
+    const rendered = { offsetX: 50, offsetY: 0, width: 300, height: 400 }
+    const orig = { x: 0.25, y: 0.4, w: 0.3, h: 0.5 }
+    const px = fractionToWrapperPx({ crop: orig, rendered })
+    const back = wrapperPxToFraction({ px, rendered })
+    expect(back.x).toBeCloseTo(orig.x)
+    expect(back.y).toBeCloseTo(orig.y)
+    expect(back.w).toBeCloseTo(orig.w)
+    expect(back.h).toBeCloseTo(orig.h)
+  })
+})
+
+import { applyCropHandleDrag } from '../crop-math'
+
+// Standard fixture: 400x500 element, 800x1000 source — aspect-matched so the
+// rendered source fills the wrapper. Crop fractions map 1:1 to wrapper px on
+// the x axis (400 px wide) and on the y axis (500 px tall) since there's no
+// letterbox.
+const FIXTURE = {
+  wrapperW: 400,
+  wrapperH: 500,
+  srcWidth: 800,
+  srcHeight: 1000,
+  initialCrop: { x: 0.2, y: 0.2, w: 0.6, h: 0.6 }, // pixel: (80, 100)–(320, 400), 240×300
+}
+
+describe('applyCropHandleDrag', () => {
+  it('6. SE handle: only the dragged axis moves (free-form, no aspect lock)', () => {
+    const next = applyCropHandleDrag({
+      handle: 'se',
+      initialCrop: FIXTURE.initialCrop,
+      deltaPx: { x: -50, y: 0 },
+      wrapperW: FIXTURE.wrapperW,
+      wrapperH: FIXTURE.wrapperH,
+      srcWidth: FIXTURE.srcWidth,
+      srcHeight: FIXTURE.srcHeight,
+    })
+    // NW corner anchored. dx=-50 in 400-px-wide rendered = 0.125 in fractions.
+    expect(next.x).toBeCloseTo(0.2)
+    expect(next.y).toBeCloseTo(0.2)
+    expect(next.w).toBeCloseTo(0.6 - 50 / 400) // 0.475
+    expect(next.h).toBeCloseTo(0.6)             // unchanged — no aspect coupling
+  })
+
+  it('7. NW handle: dragging inward shrinks from the top-left only on the dragged axes', () => {
+    const next = applyCropHandleDrag({
+      handle: 'nw',
+      initialCrop: FIXTURE.initialCrop,
+      deltaPx: { x: 40, y: 0 },
+      wrapperW: FIXTURE.wrapperW,
+      wrapperH: FIXTURE.wrapperH,
+      srcWidth: FIXTURE.srcWidth,
+      srcHeight: FIXTURE.srcHeight,
+    })
+    // SE corner anchored at (0.8, 0.8). Only x changed — y/h untouched.
+    expect(next.x).toBeCloseTo(0.3)
+    expect(next.w).toBeCloseTo(0.5)
+    expect(next.y).toBeCloseTo(0.2)
+    expect(next.h).toBeCloseTo(0.6)
+    expect(next.x + next.w).toBeCloseTo(0.8)
+  })
+
+  it('8. N handle: only top edge moves; width is unchanged (free-form)', () => {
+    const next = applyCropHandleDrag({
+      handle: 'n',
+      initialCrop: FIXTURE.initialCrop,
+      deltaPx: { x: 0, y: 50 }, // drag top edge down 50 px in 500-px-tall rendered
+      wrapperW: FIXTURE.wrapperW,
+      wrapperH: FIXTURE.wrapperH,
+      srcWidth: FIXTURE.srcWidth,
+      srcHeight: FIXTURE.srcHeight,
+    })
+    expect(next.y).toBeCloseTo(0.3)
+    expect(next.h).toBeCloseTo(0.5)
+    // width/x untouched
+    expect(next.x).toBeCloseTo(0.2)
+    expect(next.w).toBeCloseTo(0.6)
+  })
+
+  it('9. clamps so the crop never extends past source bounds', () => {
+    const next = applyCropHandleDrag({
+      handle: 'se',
+      initialCrop: { x: 0.5, y: 0.5, w: 0.4, h: 0.4 },
+      deltaPx: { x: 200, y: 200 },
+      wrapperW: FIXTURE.wrapperW,
+      wrapperH: FIXTURE.wrapperH,
+      srcWidth: FIXTURE.srcWidth,
+      srcHeight: FIXTURE.srcHeight,
+    })
+    expect(next.x + next.w).toBeLessThanOrEqual(1.0 + 1e-9)
+    expect(next.y + next.h).toBeLessThanOrEqual(1.0 + 1e-9)
+    expect(next.x).toBeGreaterThanOrEqual(-1e-9)
+    expect(next.y).toBeGreaterThanOrEqual(-1e-9)
+  })
+
+  it('10. enforces a minimum size (no zero-width / zero-height crop)', () => {
+    const next = applyCropHandleDrag({
+      handle: 'se',
+      initialCrop: { x: 0.4, y: 0.4, w: 0.2, h: 0.2 },
+      deltaPx: { x: -1000, y: -1000 },
+      wrapperW: FIXTURE.wrapperW,
+      wrapperH: FIXTURE.wrapperH,
+      srcWidth: FIXTURE.srcWidth,
+      srcHeight: FIXTURE.srcHeight,
+    })
+    expect(next.w).toBeGreaterThan(0)
+    expect(next.h).toBeGreaterThan(0)
+  })
+
+  it('11. aspect-mismatched source: free-form drag still respects letterbox bounds', () => {
+    // Source wider than wrapper → rendered letterboxes top/bottom. Initial crop
+    // is fully inside rendered bounds; a small inward drag should land inside
+    // [0, 1] on both axes.
+    const next = applyCropHandleDrag({
+      handle: 'se',
+      initialCrop: { x: 0.1, y: 0.1, w: 0.5, h: 0.5 },
+      deltaPx: { x: -20, y: 0 },
+      wrapperW: 400,
+      wrapperH: 500,
+      srcWidth: 1920,
+      srcHeight: 1080,
+    })
+    expect(next.x).toBeCloseTo(0.1)
+    expect(next.y).toBeCloseTo(0.1)
+    // dx=-20 px in 400-px-wide rendered = -0.05 in fractions
+    expect(next.w).toBeCloseTo(0.45)
+    expect(next.h).toBeCloseTo(0.5)
+  })
+})

package/src/crop/crop-math.ts

@@ -0,0 +1,125 @@
+// Pure math helpers for in-canvas image cropping.
+//
+// Coordinate spaces:
+// - "wrapper" px: pixels inside the SlideElement wrapper, which is sized
+//   `(element.w * scale, element.h * scale)` and rotated as a whole.
+// - "rendered source" px: pixels inside the letterboxed source image's
+//   rendered rectangle (which sits inside the wrapper at `(offsetX, offsetY)`).
+// - "source fraction": 0–1 fractions of the source's natural dimensions —
+//   exactly the storage format on `ImageElement.crop`.
+
+export type RenderedRect = {
+  offsetX: number
+  offsetY: number
+  width: number
+  height: number
+}
+
+export function renderedSourceRect(args: {
+  wrapperW: number
+  wrapperH: number
+  srcWidth: number
+  srcHeight: number
+}): RenderedRect {
+  const { wrapperW, wrapperH, srcWidth, srcHeight } = args
+  const wrapperAspect = wrapperW / wrapperH
+  const srcAspect = srcWidth / srcHeight
+
+  if (srcAspect >= wrapperAspect) {
+    const width = wrapperW
+    const height = wrapperW / srcAspect
+    return { offsetX: 0, offsetY: (wrapperH - height) / 2, width, height }
+  }
+  const height = wrapperH
+  const width = wrapperH * srcAspect
+  return { offsetX: (wrapperW - width) / 2, offsetY: 0, width, height }
+}
+
+export type CropFraction = { x: number; y: number; w: number; h: number }
+export type WrapperPxRect = { x: number; y: number; w: number; h: number }
+
+export function fractionToWrapperPx(args: {
+  crop: CropFraction
+  rendered: RenderedRect
+}): WrapperPxRect {
+  const { crop, rendered } = args
+  return {
+    x: rendered.offsetX + crop.x * rendered.width,
+    y: rendered.offsetY + crop.y * rendered.height,
+    w: crop.w * rendered.width,
+    h: crop.h * rendered.height,
+  }
+}
+
+export function wrapperPxToFraction(args: {
+  px: WrapperPxRect
+  rendered: RenderedRect
+}): CropFraction {
+  const { px, rendered } = args
+  return {
+    x: (px.x - rendered.offsetX) / rendered.width,
+    y: (px.y - rendered.offsetY) / rendered.height,
+    w: px.w / rendered.width,
+    h: px.h / rendered.height,
+  }
+}
+
+export type CropHandle = 'nw' | 'n' | 'ne' | 'w' | 'e' | 'sw' | 's' | 'se'
+
+const MIN_FRACTION = 0.02 // never let the crop shrink below 2% of source on either axis.
+
+// Free-form crop drag. Each handle moves its own edges by the delta; corners
+// move two edges, edges move one. Result is min-size enforced and clamped to
+// the rendered source bounds. The element box will be resized at commit time
+// to match the resulting crop's aspect — see commitAndExitCropMode.
+export function applyCropHandleDrag(args: {
+  handle: CropHandle
+  initialCrop: CropFraction
+  deltaPx: { x: number; y: number }
+  wrapperW: number
+  wrapperH: number
+  srcWidth: number
+  srcHeight: number
+}): CropFraction {
+  const { handle, initialCrop, deltaPx, wrapperW, wrapperH, srcWidth, srcHeight } = args
+  const rendered = renderedSourceRect({ wrapperW, wrapperH, srcWidth, srcHeight })
+
+  const initialPx = fractionToWrapperPx({ crop: initialCrop, rendered })
+
+  let left = initialPx.x
+  let top = initialPx.y
+  let right = initialPx.x + initialPx.w
+  let bottom = initialPx.y + initialPx.h
+
+  if (handle === 'nw' || handle === 'w' || handle === 'sw') left += deltaPx.x
+  if (handle === 'ne' || handle === 'e' || handle === 'se') right += deltaPx.x
+  if (handle === 'nw' || handle === 'n' || handle === 'ne') top += deltaPx.y
+  if (handle === 'sw' || handle === 's' || handle === 'se') bottom += deltaPx.y
+
+  // Enforce min size, anchored on the side opposite to the dragged edge.
+  const minW = MIN_FRACTION * rendered.width
+  const minH = MIN_FRACTION * rendered.height
+  if (right - left < minW) {
+    if (handle === 'nw' || handle === 'w' || handle === 'sw') left = right - minW
+    else right = left + minW
+  }
+  if (bottom - top < minH) {
+    if (handle === 'nw' || handle === 'n' || handle === 'ne') top = bottom - minH
+    else bottom = top + minH
+  }
+
+  // Clamp to source bounds.
+  const minLeft = rendered.offsetX
+  const minTop = rendered.offsetY
+  const maxRight = rendered.offsetX + rendered.width
+  const maxBottom = rendered.offsetY + rendered.height
+  if (left < minLeft) left = minLeft
+  if (top < minTop) top = minTop
+  if (right > maxRight) right = maxRight
+  if (bottom > maxBottom) bottom = maxBottom
+
+  return wrapperPxToFraction({
+    px: { x: left, y: top, w: right - left, h: bottom - top },
+    rendered,
+  })
+}

package/src/gestures/helpers/__tests__/element-transform.test.ts

@@ -0,0 +1,30 @@
+/// <reference types="vitest/globals" />
+import { buildElementTransform } from '../element-transform'
+
+describe('buildElementTransform', () => {
+  it('returns only translate when rotation is zero', () => {
+    expect(buildElementTransform(10, 20, 2, 0)).toBe('translate(20px, 40px)')
+  })
+
+  it('omits rotation when rotation is undefined', () => {
+    expect(buildElementTransform(0, 0, 1, undefined)).toBe('translate(0px, 0px)')
+  })
+
+  it('omits rotation when rotation is null', () => {
+    expect(buildElementTransform(0, 0, 1, null as unknown as undefined))
+      .toBe('translate(0px, 0px)')
+  })
+
+  it('composes translate + rotate when rotation is non-zero', () => {
+    expect(buildElementTransform(5, 5, 2, 45))
+      .toBe('translate(10px, 10px) rotate(45deg)')
+  })
+
+  it('handles negative coordinates', () => {
+    expect(buildElementTransform(-3, -4, 1, 0)).toBe('translate(-3px, -4px)')
+  })
+
+  it('handles fractional scale (passes through to sub-pixel CSS)', () => {
+    expect(buildElementTransform(10, 10, 0.5, 0)).toBe('translate(5px, 5px)')
+  })
+})

package/src/gestures/helpers/drag.ts

@@ -0,0 +1,24 @@
+export type DragState = {
+  elementId: string;
+  startCursor: { x: number; y: number };
+  startElement: { x: number; y: number };
+};
+
+export function startDrag(
+  elementId: string,
+  cursor: { x: number; y: number },
+  element: { x: number; y: number },
+): DragState {
+  return { elementId, startCursor: cursor, startElement: element };
+}
+
+export function nextDragPosition(
+  state: DragState,
+  cursor: { x: number; y: number },
+  scale: number,
+): { x: number; y: number } {
+  return {
+    x: state.startElement.x + (cursor.x - state.startCursor.x) / scale,
+    y: state.startElement.y + (cursor.y - state.startCursor.y) / scale,
+  };
+}

package/src/gestures/helpers/element-transform.ts

@@ -0,0 +1,15 @@
+// Builds the CSS `transform` value for an element wrapper. Centralised so
+// React renders (JSX style) and in-gesture mutations (direct DOM style
+// writes in SlideCanvas) produce byte-identical strings — that prevents
+// the wrapper from "snapping" on commit when React's render writes a
+// slightly different transform than the one the DOM already has.
+
+export function buildElementTransform(
+  x: number,
+  y: number,
+  scale: number,
+  rotation: number | undefined | null,
+): string {
+  const base = `translate(${x * scale}px, ${y * scale}px)`
+  return rotation ? `${base} rotate(${rotation}deg)` : base
+}

package/src/gestures/helpers/resize.ts

@@ -0,0 +1,60 @@
+export type ResizeHandle = 'nw' | 'n' | 'ne' | 'w' | 'e' | 'sw' | 's' | 'se';
+
+export type ResizeState = {
+  elementId: string;
+  handle: ResizeHandle;
+  startCursor: { x: number; y: number };
+  startBox: { x: number; y: number; w: number; h: number };
+};
+
+export function startResize(
+  elementId: string,
+  handle: ResizeHandle,
+  cursor: { x: number; y: number },
+  box: { x: number; y: number; w: number; h: number },
+): ResizeState {
+  return { elementId, handle, startCursor: cursor, startBox: box };
+}
+
+export function nextResizeBox(
+  state: ResizeState,
+  cursor: { x: number; y: number },
+  scale: number,
+): { x: number; y: number; w: number; h: number } {
+  const dx = (cursor.x - state.startCursor.x) / scale;
+  const dy = (cursor.y - state.startCursor.y) / scale;
+  let { x, y, w, h } = state.startBox;
+
+  if (state.handle.includes('w')) {
+    const proposedW = state.startBox.w - dx;
+    if (proposedW < 1) {
+      x = state.startBox.x + state.startBox.w - 1;
+      w = 1;
+    } else {
+      x = state.startBox.x + dx;
+      w = proposedW;
+    }
+  }
+  if (state.handle.includes('e')) {
+    w = state.startBox.w + dx;
+  }
+  if (state.handle.includes('n')) {
+    const proposedH = state.startBox.h - dy;
+    if (proposedH < 1) {
+      y = state.startBox.y + state.startBox.h - 1;
+      h = 1;
+    } else {
+      y = state.startBox.y + dy;
+      h = proposedH;
+    }
+  }
+  if (state.handle.includes('s')) {
+    h = state.startBox.h + dy;
+  }
+  return {
+    x,
+    y,
+    w: Math.max(w, 1),
+    h: Math.max(h, 1),
+  };
+}

package/src/gestures/helpers/rotate.ts

@@ -0,0 +1,44 @@
+export type RotateState = {
+  elementId: string;
+  center: { x: number; y: number };
+  startCursorAngle: number; // degrees
+  startRotation: number;     // degrees
+};
+
+const RAD_TO_DEG = 180 / Math.PI;
+
+function angleOf(center: { x: number; y: number }, cursor: { x: number; y: number }): number {
+  return Math.atan2(cursor.y - center.y, cursor.x - center.x) * RAD_TO_DEG;
+}
+
+export function startRotate(
+  elementId: string,
+  center: { x: number; y: number },
+  cursor: { x: number; y: number },
+  rotation: number,
+): RotateState {
+  return {
+    elementId,
+    center,
+    startCursorAngle: angleOf(center, cursor),
+    startRotation: rotation,
+  };
+}
+
+export function nextRotation(
+  state: RotateState,
+  cursor: { x: number; y: number },
+  snapThresholdDeg: number = 5,
+): number {
+  const cursorAngle = angleOf(state.center, cursor);
+  const delta = cursorAngle - state.startCursorAngle;
+  const raw = state.startRotation + delta;
+  // Normalize to [0, 360).
+  const norm = ((raw % 360) + 360) % 360;
+  for (const snap of [0, 90, 180, 270]) {
+    if (Math.abs(norm - snap) <= snapThresholdDeg) return snap;
+  }
+  // Also check the 360 boundary (which is 0).
+  if (Math.abs(norm - 360) <= snapThresholdDeg) return 0;
+  return norm;
+}