From dcd2fc01a9252a762642c554ff2a1088c72ea575 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 12 Nov 2026 09:41:28 -0500
Subject: [PATCH 1/5] feat(mosaic): add ImageCropper primitive

---
 .changeset/mosaic-image-cropper-primitive.md  |   2 +
 .../src/primitives/image-cropper/README.md    | 114 ++++++++
 .../__tests__/crop-image.browser.test.tsx     |  62 +++++
 .../image-cropper/__tests__/crop.test.ts      |  78 ++++++
 .../__tests__/image-cropper.test.tsx          | 258 ++++++++++++++++++
 .../primitives/image-cropper/crop-image.ts    |  41 +++
 .../src/primitives/image-cropper/crop.ts      | 104 +++++++
 .../image-cropper/image-cropper-area.tsx      |  22 ++
 .../image-cropper/image-cropper-context.ts    |  28 ++
 .../image-cropper/image-cropper-image.tsx     |  56 ++++
 .../image-cropper/image-cropper-reset.tsx     |  33 +++
 .../image-cropper/image-cropper-root.tsx      |  67 +++++
 .../image-cropper/image-cropper-rotate.tsx    |  33 +++
 .../image-cropper/image-cropper-viewport.tsx  | 153 +++++++++++
 .../image-cropper/image-cropper-zoom-step.tsx |  52 ++++
 .../image-cropper/image-cropper-zoom.tsx      |  37 +++
 .../src/primitives/image-cropper/index.ts     |  15 +
 .../src/primitives/image-cropper/parts.ts     |  13 +
 18 files changed, 1168 insertions(+)
 create mode 100644 .changeset/mosaic-image-cropper-primitive.md
 create mode 100644 packages/mosaic/src/primitives/image-cropper/README.md
 create mode 100644 packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/__tests__/crop.test.ts
 create mode 100644 packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/crop-image.ts
 create mode 100644 packages/mosaic/src/primitives/image-cropper/crop.ts
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-area.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-context.ts
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-reset.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-rotate.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-zoom-step.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/image-cropper-zoom.tsx
 create mode 100644 packages/mosaic/src/primitives/image-cropper/index.ts
 create mode 100644 packages/mosaic/src/primitives/image-cropper/parts.ts

diff --git a/.changeset/mosaic-image-cropper-primitive.md b/.changeset/mosaic-image-cropper-primitive.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-image-cropper-primitive.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/mosaic/src/primitives/image-cropper/README.md b/packages/mosaic/src/primitives/image-cropper/README.md
new file mode 100644
index 00000000000..7b60f90ae72
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/README.md
@@ -0,0 +1,114 @@
+# ImageCropper
+
+A headless image cropper. The user pans the image by dragging or with the arrow keys, zooms with the
+wheel, a pinch, the keyboard, a slider or step buttons, turns it a quarter at a time, and resets it.
+The crop is a square. `cropImage` draws the square the user chose into a new image.
+
+## When to Use
+
+- Cropping a picked image to a square before uploading it, such as an avatar or a logo.
+
+The primitive emits zero styles. The caller sizes the frame, draws any mask over it, and styles the
+controls through `data-*` attributes.
+
+## Usage
+
+```tsx
+import { type Crop, cropImage, ImageCropper, INITIAL_CROP } from '../../primitives/image-cropper';
+
+function Cropper({ src, onSave }: { src: string; onSave: (blob: Blob) => void }) {
+  const [crop, setCrop] = useState<Crop>(INITIAL_CROP);
+
+  return (
+    <ImageCropper.Root
+      src={src}
+      value={crop}
+      onValueChange={setCrop}
+    >
+      <ImageCropper.Viewport aria-label='Crop. Drag or use the arrow keys to move, plus and minus to zoom.'>
+        <ImageCropper.Area>
+          <ImageCropper.Image />
+        </ImageCropper.Area>
+      </ImageCropper.Viewport>
+      <ImageCropper.ZoomOut aria-label='Zoom out'>−</ImageCropper.ZoomOut>
+      <ImageCropper.Zoom aria-label='Zoom' />
+      <ImageCropper.ZoomIn aria-label='Zoom in'>+</ImageCropper.ZoomIn>
+      <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
+      <ImageCropper.Reset>Reset</ImageCropper.Reset>
+      <button onClick={async () => onSave(await cropImage(src, crop, { size: 512, type: 'image/png' }))}>Save</button>
+    </ImageCropper.Root>
+  );
+}
+```
+
+`Area` is optional. Without it the whole `Viewport` is the crop. With it, the crop is the `Area`, and
+the `Viewport` around it shows the rest of the image for context. Drags are measured against the
+`Area`, so the image follows the pointer either way.
+
+## Parts
+
+| Part                    | Default Element        | Description                                                            |
+| ----------------------- | ---------------------- | ---------------------------------------------------------------------- |
+| `ImageCropper.Root`     | none                   | Owns the crop and the image size, provides context                     |
+| `ImageCropper.Viewport` | `<div>`                | The frame: pans on drag and arrow keys, zooms on wheel, pinch and keys |
+| `ImageCropper.Area`     | `<div>`                | The square that is cropped, when it is smaller than the frame          |
+| `ImageCropper.Image`    | `<img>`                | The image, placed by the crop. Reports its size on load                |
+| `ImageCropper.Zoom`     | `<input type="range">` | Sets the zoom, from 1 to `maxZoom`                                     |
+| `ImageCropper.ZoomIn`   | `<button>`             | Zooms in one step. Disabled at `maxZoom`                               |
+| `ImageCropper.ZoomOut`  | `<button>`             | Zooms out one step. Disabled at 1                                      |
+| `ImageCropper.Rotate`   | `<button>`             | Turns the image a quarter clockwise                                    |
+| `ImageCropper.Reset`    | `<button>`             | Returns to `INITIAL_CROP`                                              |
+
+Every control stays disabled until the image has loaded, because the crop limits depend on its size.
+
+## Props
+
+### `ImageCropper.Root`
+
+| Prop            | Type                   | Default        | Description                                     |
+| --------------- | ---------------------- | -------------- | ----------------------------------------------- |
+| `src`           | `string`               | —              | The image to crop, such as an object URL        |
+| `value`         | `Crop`                 | —              | Controlled crop                                 |
+| `defaultValue`  | `Crop`                 | `INITIAL_CROP` | Initial crop (uncontrolled)                     |
+| `onValueChange` | `(crop: Crop) => void` | —              | Called on every pan, zoom, turn and reset       |
+| `maxZoom`       | `number`               | `4`            | Largest zoom, as a multiple of the cover scale  |
+| `disabled`      | `boolean`              | `false`        | Ignores every gesture and disables the controls |
+
+A `Crop` is `{ x, y, zoom, rotation }`. `x` and `y` move the image centre from the frame centre, as a
+fraction of the frame. `zoom` 1 is the smallest scale that still covers the frame. `rotation` is `0`,
+`90`, `180` or `270`. The crop is always clamped so the image covers the frame.
+
+Other parts take no additional props. All parts except `Root` accept a `render` prop and standard
+HTML attributes for their default element.
+
+### `cropImage(src, crop, { size, type })`
+
+Returns a `Promise<Blob>` holding the square the crop shows, `size` pixels wide, encoded as `type`.
+It draws to a canvas, so an animated image keeps only its first frame.
+
+## Keyboard
+
+On a focused `Viewport`:
+
+| Key        | Action                   |
+| ---------- | ------------------------ |
+| Arrow keys | Pan. Hold Shift for more |
+| `+` / `=`  | Zoom in one step         |
+| `-` / `_`  | Zoom out one step        |
+| `0`        | Reset                    |
+
+## Data Attributes
+
+| Attribute       | Applies To                                     | Description                         |
+| --------------- | ---------------------------------------------- | ----------------------------------- |
+| `data-dragging` | Viewport                                       | Present while a pointer is dragging |
+| `data-loaded`   | Image                                          | Present once the image has loaded   |
+| `data-disabled` | Viewport, Zoom, ZoomIn, ZoomOut, Rotate, Reset | Present when the part is disabled   |
+
+## ARIA
+
+- `Viewport` has `role="application"` so screen readers pass the arrow keys through. Give it an
+  `aria-label` that names the keys. It leaves the tab order until the image has loaded.
+- `Image` has an empty `alt`, because the `Viewport` label describes it.
+- `ZoomIn`, `ZoomOut`, `Rotate` and `Reset` render `<button type="button">`. Give icon-only buttons an
+  `aria-label`.
diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx b/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
new file mode 100644
index 00000000000..89d23340835
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import { INITIAL_CROP } from '../crop';
+import { cropImage } from '../crop-image';
+
+const RED = [255, 0, 0];
+const BLUE = [0, 0, 255];
+
+function halves(width: number, height: number): string {
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d');
+  if (!context) {
+    throw new Error('no canvas');
+  }
+  context.fillStyle = 'rgb(255 0 0)';
+  context.fillRect(0, 0, width / 2, height);
+  context.fillStyle = 'rgb(0 0 255)';
+  context.fillRect(width / 2, 0, width / 2, height);
+  return canvas.toDataURL('image/png');
+}
+
+async function pixels(blob: Blob) {
+  const bitmap = await createImageBitmap(blob);
+  const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+  const context = canvas.getContext('2d');
+  if (!context) {
+    throw new Error('no canvas');
+  }
+  context.drawImage(bitmap, 0, 0);
+  const at = (x: number, y: number) => [...context.getImageData(x, y, 1, 1).data.slice(0, 3)];
+  return { width: bitmap.width, height: bitmap.height, at };
+}
+
+describe('cropImage', () => {
+  it('draws the square the frame shows at the requested size and type', async () => {
+    const blob = await cropImage(halves(200, 100), INITIAL_CROP, { size: 64, type: 'image/png' });
+    const image = await pixels(blob);
+
+    expect(blob.type).toBe('image/png');
+    expect([image.width, image.height]).toEqual([64, 64]);
+    expect(image.at(8, 32)).toEqual(RED);
+    expect(image.at(56, 32)).toEqual(BLUE);
+  });
+
+  it('follows a pan', async () => {
+    const blob = await cropImage(halves(200, 100), { ...INITIAL_CROP, x: 0.5 }, { size: 64, type: 'image/png' });
+    const image = await pixels(blob);
+
+    expect(image.at(8, 32)).toEqual(RED);
+    expect(image.at(56, 32)).toEqual(RED);
+  });
+
+  it('follows a quarter turn', async () => {
+    const blob = await cropImage(halves(200, 100), { ...INITIAL_CROP, rotation: 90 }, { size: 64, type: 'image/png' });
+    const image = await pixels(blob);
+
+    expect(image.at(32, 8)).toEqual(RED);
+    expect(image.at(32, 56)).toEqual(BLUE);
+  });
+});
diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/crop.test.ts b/packages/mosaic/src/primitives/image-cropper/__tests__/crop.test.ts
new file mode 100644
index 00000000000..117f8a11f49
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/crop.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { clampCrop, type Crop, INITIAL_CROP, pixelCrop, rotateCrop, zoomCrop } from '../crop';
+
+const wide = { width: 200, height: 100 };
+const tall = { width: 100, height: 200 };
+const square = { width: 100, height: 100 };
+const maxZoom = 4;
+
+function crop(overrides: Partial<Crop>): Crop {
+  return { ...INITIAL_CROP, ...overrides };
+}
+
+describe('clampCrop', () => {
+  it('lets a wide image pan sideways until its edge meets the frame', () => {
+    expect(clampCrop(crop({ x: 2, y: 2 }), wide, maxZoom)).toEqual(crop({ x: 0.5, y: 0 }));
+    expect(clampCrop(crop({ x: -2 }), wide, maxZoom)).toEqual(crop({ x: -0.5 }));
+  });
+
+  it('lets a tall image pan up and down until its edge meets the frame', () => {
+    expect(clampCrop(crop({ x: 2, y: -2 }), tall, maxZoom)).toEqual(crop({ x: 0, y: -0.5 }));
+  });
+
+  it('widens the pan range as the image zooms in', () => {
+    expect(clampCrop(crop({ x: 5, y: 5, zoom: 2 }), square, maxZoom)).toEqual(crop({ x: 0.5, y: 0.5, zoom: 2 }));
+  });
+
+  it('keeps zoom between cover and the max', () => {
+    expect(clampCrop(crop({ zoom: 0.5 }), square, maxZoom).zoom).toBe(1);
+    expect(clampCrop(crop({ zoom: 9 }), square, maxZoom).zoom).toBe(4);
+  });
+
+  it('swaps the pan axes for an image turned a quarter', () => {
+    expect(clampCrop(crop({ x: 2, y: 2, rotation: 90 }), wide, maxZoom)).toEqual(crop({ x: 0, y: 0.5, rotation: 90 }));
+  });
+});
+
+describe('zoomCrop', () => {
+  it('keeps the point under the centre of the frame in place', () => {
+    expect(zoomCrop(crop({ x: 0.25, zoom: 2 }), 4, square, maxZoom)).toEqual(crop({ x: 0.5, zoom: 4 }));
+  });
+
+  it('pulls the pan back inside the image when zooming out', () => {
+    expect(zoomCrop(crop({ x: 1.5, zoom: 2 }), 1, wide, maxZoom)).toEqual(crop({ x: 0.5, zoom: 1 }));
+  });
+});
+
+describe('rotateCrop', () => {
+  it('turns the image a quarter clockwise around the centre of the frame', () => {
+    expect(rotateCrop(crop({ x: 0.5 }), wide, maxZoom)).toEqual(crop({ x: 0, y: 0.5, rotation: 90 }));
+  });
+
+  it('wraps back to upright after four turns', () => {
+    expect(rotateCrop(crop({ rotation: 270 }), square, maxZoom).rotation).toBe(0);
+  });
+});
+
+describe('pixelCrop', () => {
+  it('takes the whole of a square image at rest', () => {
+    expect(pixelCrop(INITIAL_CROP, square)).toEqual({ x: 0, y: 0, size: 100 });
+  });
+
+  it('takes the middle of a wide image at rest', () => {
+    expect(pixelCrop(INITIAL_CROP, wide)).toEqual({ x: 50, y: 0, size: 100 });
+  });
+
+  it('takes the left side when the image is panned right', () => {
+    expect(pixelCrop(crop({ x: 0.5 }), wide)).toEqual({ x: 0, y: 0, size: 100 });
+  });
+
+  it('takes a smaller square when zoomed in', () => {
+    expect(pixelCrop(crop({ zoom: 2 }), wide)).toEqual({ x: 75, y: 25, size: 50 });
+  });
+
+  it('measures from the turned image', () => {
+    expect(pixelCrop(crop({ y: 0.5, rotation: 90 }), wide)).toEqual({ x: 0, y: 0, size: 100 });
+  });
+});
diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
new file mode 100644
index 00000000000..ea2e685fd11
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
@@ -0,0 +1,258 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { axe } from '../../test-utils/axe';
+import type { Crop } from '../crop';
+import { ImageCropper, type ImageCropperRootProps } from '../index';
+
+afterEach(() => cleanup());
+
+function Harness(props: Partial<ImageCropperRootProps>) {
+  return (
+    <ImageCropper.Root
+      src='photo.png'
+      {...props}
+    >
+      <ImageCropper.Viewport aria-label='Crop'>
+        <ImageCropper.Image alt='' />
+      </ImageCropper.Viewport>
+      <ImageCropper.Zoom aria-label='Zoom' />
+      <ImageCropper.ZoomOut aria-label='Zoom out' />
+      <ImageCropper.ZoomIn aria-label='Zoom in' />
+      <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
+      <ImageCropper.Reset>Reset</ImageCropper.Reset>
+    </ImageCropper.Root>
+  );
+}
+
+function load(width: number, height: number) {
+  const image = document.querySelector('img');
+  if (!image) {
+    throw new Error('no image');
+  }
+  Object.defineProperty(image, 'naturalWidth', { value: width });
+  Object.defineProperty(image, 'naturalHeight', { value: height });
+  fireEvent.load(image);
+  return image;
+}
+
+function lastCrop(onValueChange: ReturnType<typeof vi.fn<(crop: Crop) => void>>): Crop | undefined {
+  return onValueChange.mock.lastCall?.[0];
+}
+
+describe('ImageCropper', () => {
+  it('keeps the controls disabled until the image has loaded', () => {
+    render(<Harness />);
+
+    expect(screen.getByRole('slider', { name: 'Zoom' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Rotate' })).toBeDisabled();
+
+    load(200, 100);
+
+    expect(screen.getByRole('slider', { name: 'Zoom' })).toBeEnabled();
+    expect(screen.getByRole('button', { name: 'Rotate' })).toBeEnabled();
+  });
+
+  it('sizes the image to cover the frame', () => {
+    render(<Harness />);
+    const image = load(200, 100);
+
+    expect(image.style.width).toBe('200%');
+    expect(image.style.height).toBe('100%');
+    expect(image.style.left).toBe('50%');
+  });
+
+  it('zooms from the slider', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(100, 100);
+
+    fireEvent.change(screen.getByRole('slider', { name: 'Zoom' }), { target: { value: '2' } });
+
+    expect(lastCrop(onValueChange)?.zoom).toBe(2);
+  });
+
+  it('steps the zoom from the zoom in and out buttons, and stops at each end', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <Harness
+        maxZoom={2}
+        onValueChange={onValueChange}
+      />,
+    );
+    load(100, 100);
+    const zoomIn = screen.getByRole('button', { name: 'Zoom in' });
+    const zoomOut = screen.getByRole('button', { name: 'Zoom out' });
+    expect(zoomOut).toBeDisabled();
+
+    await user.click(zoomIn);
+    expect(lastCrop(onValueChange)?.zoom).toBeGreaterThan(1);
+    expect(zoomOut).toBeEnabled();
+
+    await user.click(zoomIn);
+    await user.click(zoomIn);
+    await user.click(zoomIn);
+    expect(lastCrop(onValueChange)?.zoom).toBe(2);
+    expect(zoomIn).toBeDisabled();
+
+    await user.click(zoomOut);
+    expect(lastCrop(onValueChange)?.zoom).toBeLessThan(2);
+  });
+
+  it('turns the image a quarter clockwise', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(100, 100);
+
+    await user.click(screen.getByRole('button', { name: 'Rotate' }));
+
+    expect(lastCrop(onValueChange)?.rotation).toBe(90);
+  });
+
+  it('resets the crop', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <Harness
+        defaultValue={{ x: 0.2, y: 0, zoom: 2, rotation: 180 }}
+        onValueChange={onValueChange}
+      />,
+    );
+    load(100, 100);
+
+    await user.click(screen.getByRole('button', { name: 'Reset' }));
+
+    expect(lastCrop(onValueChange)).toEqual({ x: 0, y: 0, zoom: 1, rotation: 0 });
+  });
+
+  it('pans and zooms from the keyboard', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(200, 100);
+
+    screen.getByRole('application', { name: 'Crop' }).focus();
+    await user.keyboard('{ArrowRight}');
+    expect(lastCrop(onValueChange)?.x).toBeGreaterThan(0);
+
+    await user.keyboard('+');
+    expect(lastCrop(onValueChange)?.zoom).toBeGreaterThan(1);
+
+    await user.keyboard('-');
+    expect(lastCrop(onValueChange)?.zoom).toBeCloseTo(1);
+
+    await user.keyboard('0');
+    expect(lastCrop(onValueChange)).toEqual({ x: 0, y: 0, zoom: 1, rotation: 0 });
+  });
+
+  it('pans by dragging, in fractions of the frame', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <Harness
+        defaultValue={{ x: 0, y: 0, zoom: 2, rotation: 0 }}
+        onValueChange={onValueChange}
+      />,
+    );
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ width: 200, height: 200 }));
+
+    fireEvent.pointerDown(viewport, { pointerId: 1, clientX: 100, clientY: 100, button: 0 });
+    fireEvent.pointerMove(viewport, { pointerId: 1, clientX: 150, clientY: 80 });
+    expect(viewport).toHaveAttribute('data-dragging');
+    fireEvent.pointerUp(viewport, { pointerId: 1, clientX: 150, clientY: 80 });
+
+    expect(lastCrop(onValueChange)).toEqual({ x: 0.25, y: -0.1, zoom: 2, rotation: 0 });
+    expect(viewport).not.toHaveAttribute('data-dragging');
+  });
+
+  it('pans in fractions of the crop area when the frame is larger than it', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <ImageCropper.Root
+        src='photo.png'
+        defaultValue={{ x: 0, y: 0, zoom: 2, rotation: 0 }}
+        onValueChange={onValueChange}
+      >
+        <ImageCropper.Viewport aria-label='Crop'>
+          <ImageCropper.Area data-testid='area'>
+            <ImageCropper.Image alt='' />
+          </ImageCropper.Area>
+        </ImageCropper.Viewport>
+      </ImageCropper.Root>,
+    );
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ width: 200, height: 200 }));
+    vi.spyOn(screen.getByTestId('area'), 'getBoundingClientRect').mockReturnValue(
+      DOMRect.fromRect({ width: 100, height: 100 }),
+    );
+
+    fireEvent.pointerDown(viewport, { pointerId: 1, clientX: 100, clientY: 100, button: 0 });
+    fireEvent.pointerMove(viewport, { pointerId: 1, clientX: 120, clientY: 100 });
+
+    expect(lastCrop(onValueChange)).toEqual({ x: 0.2, y: 0, zoom: 2, rotation: 0 });
+  });
+
+  it('ends a drag when the pointer is cancelled', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <Harness
+        defaultValue={{ x: 0, y: 0, zoom: 2, rotation: 0 }}
+        onValueChange={onValueChange}
+      />,
+    );
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ width: 200, height: 200 }));
+
+    fireEvent.pointerDown(viewport, { pointerId: 1, clientX: 100, clientY: 100, button: 0 });
+    fireEvent.pointerCancel(viewport, { pointerId: 1 });
+    fireEvent.pointerMove(viewport, { pointerId: 1, clientX: 150, clientY: 100 });
+
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(viewport).not.toHaveAttribute('data-dragging');
+  });
+
+  it('zooms with a two-finger pinch', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ width: 200, height: 200 }));
+
+    fireEvent.pointerDown(viewport, { pointerId: 1, clientX: 50, clientY: 100, button: 0 });
+    fireEvent.pointerDown(viewport, { pointerId: 2, clientX: 150, clientY: 100, button: 0 });
+    fireEvent.pointerMove(viewport, { pointerId: 2, clientX: 250, clientY: 100 });
+
+    expect(lastCrop(onValueChange)?.zoom).toBe(2);
+  });
+
+  it('ignores every gesture while disabled', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <Harness
+        disabled
+        onValueChange={onValueChange}
+      />,
+    );
+    load(100, 100);
+
+    expect(screen.getByRole('button', { name: 'Reset' })).toBeDisabled();
+    screen.getByRole('application', { name: 'Crop' }).focus();
+    await user.keyboard('+');
+
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it('has no axe violations', async () => {
+    const { container } = render(<Harness />);
+    load(100, 100);
+
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
diff --git a/packages/mosaic/src/primitives/image-cropper/crop-image.ts b/packages/mosaic/src/primitives/image-cropper/crop-image.ts
new file mode 100644
index 00000000000..3904b49cfd5
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/crop-image.ts
@@ -0,0 +1,41 @@
+import { type Crop, pixelCrop, turned } from './crop';
+
+export interface CropImageOptions {
+  /** Width and height of the output, in pixels. */
+  size: number;
+  /** Image type to encode, such as `image/png`. */
+  type: string;
+}
+
+/**
+ * Draws the square a crop shows into a new image.
+ *
+ * @example
+ * const blob = await cropImage(objectUrl, crop, { size: 512, type: 'image/png' });
+ */
+export async function cropImage(src: string, crop: Crop, { size, type }: CropImageOptions): Promise<Blob> {
+  const image = new Image();
+  image.src = src;
+  await image.decode();
+
+  const natural = { width: image.naturalWidth, height: image.naturalHeight };
+  const area = pixelCrop(crop, natural);
+  const upright = turned(natural, crop.rotation);
+
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (!context) {
+    throw new Error('Canvas 2D context is unavailable');
+  }
+  context.imageSmoothingQuality = 'high';
+  context.scale(size / area.size, size / area.size);
+  context.translate(upright.width / 2 - area.x, upright.height / 2 - area.y);
+  context.rotate((crop.rotation * Math.PI) / 180);
+  context.drawImage(image, -natural.width / 2, -natural.height / 2);
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(blob => (blob ? resolve(blob) : reject(new Error('Could not encode the cropped image'))), type);
+  });
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/crop.ts b/packages/mosaic/src/primitives/image-cropper/crop.ts
new file mode 100644
index 00000000000..2aae1f578b8
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/crop.ts
@@ -0,0 +1,104 @@
+/** A quarter turn, clockwise, in degrees. */
+export type Rotation = 0 | 90 | 180 | 270;
+
+/**
+ * Where the image sits in the square frame. `x` and `y` move the image centre from the frame
+ * centre, as a fraction of the frame. `zoom` 1 is the smallest scale that still covers the frame.
+ */
+export interface Crop {
+  x: number;
+  y: number;
+  zoom: number;
+  rotation: Rotation;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/** The square to cut from the image after it is turned by `rotation`, in image pixels. */
+export interface PixelCrop {
+  x: number;
+  y: number;
+  size: number;
+}
+
+export const INITIAL_CROP: Crop = { x: 0, y: 0, zoom: 1, rotation: 0 };
+
+/** How much one zoom in or out step scales the image, from a button or the keyboard. */
+export const ZOOM_STEP = 1.25;
+
+/**
+ * Keeps the frame covered: zoom stays between 1 and `maxZoom`, and the image cannot pan past its edge.
+ *
+ * @example
+ * clampCrop({ x: 2, y: 0, zoom: 1, rotation: 0 }, { width: 200, height: 100 }, 4) // x: 0.5
+ */
+export function clampCrop(crop: Crop, size: Size, maxZoom: number): Crop {
+  const zoom = clamp(crop.zoom, 1, maxZoom);
+  const { width, height } = turned(size, crop.rotation);
+  const short = Math.min(width, height);
+  const rangeX = ((width / short) * zoom - 1) / 2;
+  const rangeY = ((height / short) * zoom - 1) / 2;
+  return { x: clamp(crop.x, -rangeX, rangeX), y: clamp(crop.y, -rangeY, rangeY), zoom, rotation: crop.rotation };
+}
+
+/**
+ * Zooms around the frame centre, so the point under it stays put.
+ *
+ * @example
+ * zoomCrop(crop, crop.zoom * 1.1, size, 4)
+ */
+export function zoomCrop(crop: Crop, zoom: number, size: Size, maxZoom: number): Crop {
+  const next = clamp(zoom, 1, maxZoom);
+  const ratio = next / crop.zoom;
+  return clampCrop({ ...crop, x: crop.x * ratio, y: crop.y * ratio, zoom: next }, size, maxZoom);
+}
+
+/**
+ * Turns the image a quarter clockwise around the frame centre.
+ *
+ * @example
+ * rotateCrop(crop, size, 4)
+ */
+export function rotateCrop(crop: Crop, size: Size, maxZoom: number): Crop {
+  return clampCrop({ ...crop, x: -crop.y, y: crop.x, rotation: nextRotation(crop.rotation) }, size, maxZoom);
+}
+
+/**
+ * The square the frame shows, in pixels of the image after it is turned by `crop.rotation`.
+ *
+ * @example
+ * pixelCrop({ x: 0, y: 0, zoom: 2, rotation: 0 }, { width: 200, height: 100 }) // { x: 75, y: 25, size: 50 }
+ */
+export function pixelCrop(crop: Crop, size: Size): PixelCrop {
+  const { width, height } = turned(size, crop.rotation);
+  const side = Math.min(width, height) / crop.zoom;
+  return {
+    x: width / 2 - crop.x * side - side / 2,
+    y: height / 2 - crop.y * side - side / 2,
+    size: side,
+  };
+}
+
+export function turned(size: Size, rotation: Rotation): Size {
+  return rotation === 90 || rotation === 270 ? { width: size.height, height: size.width } : size;
+}
+
+function nextRotation(rotation: Rotation): Rotation {
+  switch (rotation) {
+    case 0:
+      return 90;
+    case 90:
+      return 180;
+    case 180:
+      return 270;
+    case 270:
+      return 0;
+  }
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max) + 0;
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-area.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-area.tsx
new file mode 100644
index 00000000000..25dc87cc011
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-area.tsx
@@ -0,0 +1,22 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperAreaProps = ComponentProps<'div'>;
+
+export const ImageCropperArea = React.forwardRef<HTMLDivElement, ImageCropperAreaProps>(
+  function ImageCropperArea(props, ref) {
+    const { render, ...otherProps } = props;
+    const { area } = useImageCropperContext();
+
+    return useRender({
+      defaultTagName: 'div',
+      ref: [area, ref],
+      render,
+      props: mergeProps<'div'>({}, otherProps),
+    });
+  },
+);
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-context.ts b/packages/mosaic/src/primitives/image-cropper/image-cropper-context.ts
new file mode 100644
index 00000000000..92f4be822e3
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-context.ts
@@ -0,0 +1,28 @@
+import { createContext, type RefObject, useContext } from 'react';
+
+import type { Crop, Size } from './crop';
+
+export interface ImageCropperContextValue {
+  src: string;
+  crop: Crop;
+  size: Size | undefined;
+  maxZoom: number;
+  disabled: boolean;
+  area: RefObject<HTMLDivElement | null>;
+  setSize: (size: Size) => void;
+  pan: (dx: number, dy: number) => void;
+  zoomTo: (zoom: number) => void;
+  zoomBy: (factor: number) => void;
+  rotate: () => void;
+  reset: () => void;
+}
+
+export const ImageCropperContext = createContext<ImageCropperContextValue | null>(null);
+
+export function useImageCropperContext(): ImageCropperContextValue {
+  const context = useContext(ImageCropperContext);
+  if (!context) {
+    throw new Error('ImageCropper parts must be rendered inside <ImageCropper.Root>');
+  }
+  return context;
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
new file mode 100644
index 00000000000..7508ed40843
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
@@ -0,0 +1,56 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { type Crop, type Size, turned } from './crop';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperImageProps = ComponentProps<'img'>;
+
+export const ImageCropperImage = React.forwardRef<HTMLImageElement, ImageCropperImageProps>(
+  function ImageCropperImage(props, ref) {
+    const { render, ...otherProps } = props;
+    const { src, crop, size, setSize } = useImageCropperContext();
+
+    const defaultProps = {
+      src,
+      alt: '',
+      draggable: false,
+      style: size ? placement(crop, size) : { visibility: 'hidden' },
+      onLoad: event => {
+        const { naturalWidth, naturalHeight } = event.currentTarget;
+        setSize({ width: naturalWidth, height: naturalHeight });
+      },
+    } satisfies DefaultProps<'img'>;
+
+    return useRender({
+      defaultTagName: 'img',
+      ref,
+      render,
+      state: { loaded: size !== undefined },
+      stateAttributesMapping: {
+        loaded: (v: boolean) => (v ? { 'data-loaded': '' } : null),
+      },
+      props: mergeProps<'img'>(defaultProps, otherProps),
+    });
+  },
+);
+
+function placement(crop: Crop, size: Size): React.CSSProperties {
+  const { width, height } = turned(size, crop.rotation);
+  const short = Math.min(width, height);
+  return {
+    position: 'absolute',
+    left: percent(0.5 + crop.x),
+    top: percent(0.5 + crop.y),
+    width: percent((size.width / short) * crop.zoom),
+    height: percent((size.height / short) * crop.zoom),
+    maxWidth: 'none',
+    transform: `translate(-50%, -50%) rotate(${crop.rotation}deg)`,
+  };
+}
+
+function percent(fraction: number): string {
+  return `${fraction * 100}%`;
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-reset.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-reset.tsx
new file mode 100644
index 00000000000..1dec59200cd
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-reset.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperResetProps = ComponentProps<'button'>;
+
+export const ImageCropperReset = React.forwardRef<HTMLButtonElement, ImageCropperResetProps>(
+  function ImageCropperReset(props, ref) {
+    const { render, ...otherProps } = props;
+    const { size, disabled, reset } = useImageCropperContext();
+    const inactive = disabled || size === undefined;
+
+    const defaultProps = {
+      type: 'button',
+      disabled: inactive,
+      onClick: () => reset(),
+    } satisfies DefaultProps<'button'>;
+
+    return useRender({
+      defaultTagName: 'button',
+      ref,
+      render,
+      state: { disabled: inactive },
+      stateAttributesMapping: {
+        disabled: (v: boolean) => (v ? { 'data-disabled': '' } : null),
+      },
+      props: mergeProps<'button'>(defaultProps, otherProps),
+    });
+  },
+);
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
new file mode 100644
index 00000000000..4eeac191035
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
@@ -0,0 +1,67 @@
+'use client';
+
+import { type ReactNode, useMemo, useRef, useState } from 'react';
+
+import { useControllableState } from '../hooks/use-controllable-state';
+import { clampCrop, type Crop, INITIAL_CROP, rotateCrop, type Size, zoomCrop } from './crop';
+import { ImageCropperContext, type ImageCropperContextValue } from './image-cropper-context';
+
+export interface ImageCropperRootProps {
+  /** The image to crop, such as an object URL for a picked file. */
+  src: string;
+  /** Controlled crop. */
+  value?: Crop;
+  /** Initial crop (uncontrolled). @default INITIAL_CROP */
+  defaultValue?: Crop;
+  /** Called with the next crop whenever the user pans, zooms, turns or resets the image. */
+  onValueChange?: (crop: Crop) => void;
+  /** Largest zoom, as a multiple of the scale that covers the frame. @default 4 */
+  maxZoom?: number;
+  /** Ignore every gesture and disable the controls. @default false */
+  disabled?: boolean;
+  children: ReactNode;
+}
+
+export function ImageCropperRoot({
+  src,
+  value,
+  defaultValue = INITIAL_CROP,
+  onValueChange,
+  maxZoom = 4,
+  disabled = false,
+  children,
+}: ImageCropperRootProps) {
+  const [crop, setCrop] = useControllableState(value, defaultValue, onValueChange);
+  const [size, setSize] = useState<Size>();
+  const area = useRef<HTMLDivElement | null>(null);
+  const latest = useRef(crop);
+  // eslint-disable-next-line react/refs -- This ref holds an imperative resource or the latest callback outside React state.
+  latest.current = crop;
+
+  const contextValue = useMemo<ImageCropperContextValue>(() => {
+    const update = (next: (current: Crop, size: Size) => Crop) => {
+      if (disabled || !size) {
+        return;
+      }
+      latest.current = next(latest.current, size);
+      setCrop(latest.current);
+    };
+
+    return {
+      src,
+      crop,
+      size,
+      maxZoom,
+      disabled,
+      area,
+      setSize,
+      pan: (dx, dy) => update((c, s) => clampCrop({ ...c, x: c.x + dx, y: c.y + dy }, s, maxZoom)),
+      zoomTo: zoom => update((c, s) => zoomCrop(c, zoom, s, maxZoom)),
+      zoomBy: factor => update((c, s) => zoomCrop(c, c.zoom * factor, s, maxZoom)),
+      rotate: () => update((c, s) => rotateCrop(c, s, maxZoom)),
+      reset: () => update(() => INITIAL_CROP),
+    };
+  }, [src, crop, size, maxZoom, disabled, setCrop]);
+
+  return <ImageCropperContext.Provider value={contextValue}>{children}</ImageCropperContext.Provider>;
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-rotate.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-rotate.tsx
new file mode 100644
index 00000000000..b67dd1c7fd2
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-rotate.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperRotateProps = ComponentProps<'button'>;
+
+export const ImageCropperRotate = React.forwardRef<HTMLButtonElement, ImageCropperRotateProps>(
+  function ImageCropperRotate(props, ref) {
+    const { render, ...otherProps } = props;
+    const { size, disabled, rotate } = useImageCropperContext();
+    const inactive = disabled || size === undefined;
+
+    const defaultProps = {
+      type: 'button',
+      disabled: inactive,
+      onClick: () => rotate(),
+    } satisfies DefaultProps<'button'>;
+
+    return useRender({
+      defaultTagName: 'button',
+      ref,
+      render,
+      state: { disabled: inactive },
+      stateAttributesMapping: {
+        disabled: (v: boolean) => (v ? { 'data-disabled': '' } : null),
+      },
+      props: mergeProps<'button'>(defaultProps, otherProps),
+    });
+  },
+);
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
new file mode 100644
index 00000000000..7bbafffb42e
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
@@ -0,0 +1,153 @@
+'use client';
+
+import React, { useEffect, useRef, useState } from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { ZOOM_STEP } from './crop';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperViewportProps = ComponentProps<'div'>;
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+const KEY_PAN = 0.02;
+const KEY_PAN_LARGE = 0.1;
+const WHEEL_ZOOM = 0.002;
+
+export const ImageCropperViewport = React.forwardRef<HTMLDivElement, ImageCropperViewportProps>(
+  function ImageCropperViewport(props, ref) {
+    const { render, ...otherProps } = props;
+    const { size, disabled, area, pan, zoomBy, reset } = useImageCropperContext();
+    const elementRef = useRef<HTMLDivElement | null>(null);
+    const pointers = useRef(new Map<number, Point>());
+    const [dragging, setDragging] = useState(false);
+
+    useEffect(() => {
+      const element = elementRef.current;
+      if (!element) {
+        return;
+      }
+      const onWheel = (event: WheelEvent) => {
+        event.preventDefault();
+        zoomBy(Math.exp(-event.deltaY * WHEEL_ZOOM));
+      };
+      element.addEventListener('wheel', onWheel, { passive: false });
+      return () => element.removeEventListener('wheel', onWheel);
+    }, [zoomBy]);
+
+    const release = (pointerId: number) => {
+      pointers.current.delete(pointerId);
+      if (pointers.current.size === 0) {
+        setDragging(false);
+      }
+    };
+
+    const ready = size !== undefined && !disabled;
+
+    const defaultProps = {
+      role: 'application',
+      tabIndex: ready ? 0 : -1,
+      style: { touchAction: 'none' },
+      onPointerDown: event => {
+        if (!ready || event.button !== 0) {
+          return;
+        }
+        event.currentTarget.setPointerCapture?.(event.pointerId);
+        pointers.current.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        setDragging(true);
+      },
+      onPointerMove: event => {
+        const previous = pointers.current.get(event.pointerId);
+        if (!previous) {
+          return;
+        }
+        const before = [...pointers.current.values()];
+        pointers.current.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        const after = [...pointers.current.values()];
+        const frame = (area.current ?? event.currentTarget).getBoundingClientRect().width;
+        if (frame === 0) {
+          return;
+        }
+        const from = midpoint(before);
+        const to = midpoint(after);
+        pan((to.x - from.x) / frame, (to.y - from.y) / frame);
+        const [a, b] = before;
+        const [c, d] = after;
+        if (a && b && c && d) {
+          zoomBy(distance(c, d) / distance(a, b));
+        }
+      },
+      onPointerUp: event => release(event.pointerId),
+      onPointerCancel: event => release(event.pointerId),
+      onLostPointerCapture: event => release(event.pointerId),
+      onKeyDown: event => {
+        if (!ready) {
+          return;
+        }
+        const step = event.shiftKey ? KEY_PAN_LARGE : KEY_PAN;
+        const action = keyAction(event.key, step);
+        if (!action) {
+          return;
+        }
+        event.preventDefault();
+        if (action.type === 'pan') {
+          pan(action.dx, action.dy);
+        } else if (action.type === 'zoom') {
+          zoomBy(action.factor);
+        } else {
+          reset();
+        }
+      },
+    } satisfies DefaultProps<'div'>;
+
+    return useRender({
+      defaultTagName: 'div',
+      ref: [elementRef, ref],
+      render,
+      state: { dragging, disabled },
+      stateAttributesMapping: {
+        dragging: (v: boolean) => (v ? { 'data-dragging': '' } : null),
+        disabled: (v: boolean) => (v ? { 'data-disabled': '' } : null),
+      },
+      // eslint-disable-next-line react/refs -- This ref holds an imperative resource or the latest callback outside React state.
+      props: mergeProps<'div'>(defaultProps, otherProps),
+    });
+  },
+);
+
+type KeyAction = { type: 'pan'; dx: number; dy: number } | { type: 'zoom'; factor: number } | { type: 'reset' };
+
+function keyAction(key: string, step: number): KeyAction | undefined {
+  switch (key) {
+    case 'ArrowLeft':
+      return { type: 'pan', dx: -step, dy: 0 };
+    case 'ArrowRight':
+      return { type: 'pan', dx: step, dy: 0 };
+    case 'ArrowUp':
+      return { type: 'pan', dx: 0, dy: -step };
+    case 'ArrowDown':
+      return { type: 'pan', dx: 0, dy: step };
+    case '+':
+    case '=':
+      return { type: 'zoom', factor: ZOOM_STEP };
+    case '-':
+    case '_':
+      return { type: 'zoom', factor: 1 / ZOOM_STEP };
+    case '0':
+      return { type: 'reset' };
+    default:
+      return undefined;
+  }
+}
+
+function midpoint(points: Point[]): Point {
+  const sum = points.reduce((total, point) => ({ x: total.x + point.x, y: total.y + point.y }), { x: 0, y: 0 });
+  return { x: sum.x / points.length, y: sum.y / points.length };
+}
+
+function distance(a: Point, b: Point): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom-step.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom-step.tsx
new file mode 100644
index 00000000000..6899794f158
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom-step.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { ZOOM_STEP } from './crop';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperZoomInProps = ComponentProps<'button'>;
+export type ImageCropperZoomOutProps = ComponentProps<'button'>;
+
+export const ImageCropperZoomIn = React.forwardRef<HTMLButtonElement, ImageCropperZoomInProps>(
+  function ImageCropperZoomIn(props, ref) {
+    const { crop, maxZoom } = useImageCropperContext();
+    return useZoomStep(props, ref, ZOOM_STEP, crop.zoom >= maxZoom);
+  },
+);
+
+export const ImageCropperZoomOut = React.forwardRef<HTMLButtonElement, ImageCropperZoomOutProps>(
+  function ImageCropperZoomOut(props, ref) {
+    const { crop } = useImageCropperContext();
+    return useZoomStep(props, ref, 1 / ZOOM_STEP, crop.zoom <= 1);
+  },
+);
+
+function useZoomStep(
+  props: ComponentProps<'button'>,
+  ref: React.ForwardedRef<HTMLButtonElement>,
+  factor: number,
+  atLimit: boolean,
+) {
+  const { render, ...otherProps } = props;
+  const { size, disabled, zoomBy } = useImageCropperContext();
+  const inactive = disabled || size === undefined || atLimit;
+
+  const defaultProps = {
+    type: 'button',
+    disabled: inactive,
+    onClick: () => zoomBy(factor),
+  } satisfies DefaultProps<'button'>;
+
+  return useRender({
+    defaultTagName: 'button',
+    ref,
+    render,
+    state: { disabled: inactive },
+    stateAttributesMapping: {
+      disabled: (v: boolean) => (v ? { 'data-disabled': '' } : null),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom.tsx
new file mode 100644
index 00000000000..18503b19a20
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-zoom.tsx
@@ -0,0 +1,37 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
+import { useImageCropperContext } from './image-cropper-context';
+
+export type ImageCropperZoomProps = ComponentProps<'input'>;
+
+export const ImageCropperZoom = React.forwardRef<HTMLInputElement, ImageCropperZoomProps>(
+  function ImageCropperZoom(props, ref) {
+    const { render, ...otherProps } = props;
+    const { crop, size, maxZoom, disabled, zoomTo } = useImageCropperContext();
+    const inactive = disabled || size === undefined;
+
+    const defaultProps = {
+      type: 'range',
+      min: 1,
+      max: maxZoom,
+      step: 0.01,
+      value: crop.zoom,
+      disabled: inactive,
+      onChange: event => zoomTo(Number(event.currentTarget.value)),
+    } satisfies DefaultProps<'input'>;
+
+    return useRender({
+      defaultTagName: 'input',
+      ref,
+      render,
+      state: { disabled: inactive },
+      stateAttributesMapping: {
+        disabled: (v: boolean) => (v ? { 'data-disabled': '' } : null),
+      },
+      props: mergeProps<'input'>(defaultProps, otherProps),
+    });
+  },
+);
diff --git a/packages/mosaic/src/primitives/image-cropper/index.ts b/packages/mosaic/src/primitives/image-cropper/index.ts
new file mode 100644
index 00000000000..ce9ef57fc96
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/index.ts
@@ -0,0 +1,15 @@
+export * as ImageCropper from './parts';
+export { type Crop, INITIAL_CROP, type PixelCrop, type Rotation, type Size, ZOOM_STEP } from './crop';
+
+export type {
+  ImageCropperAreaProps,
+  ImageCropperImageProps,
+  ImageCropperResetProps,
+  ImageCropperRootProps,
+  ImageCropperRotateProps,
+  ImageCropperViewportProps,
+  ImageCropperZoomInProps,
+  ImageCropperZoomOutProps,
+  ImageCropperZoomProps,
+} from './parts';
+export { cropImage, type CropImageOptions } from './crop-image';
diff --git a/packages/mosaic/src/primitives/image-cropper/parts.ts b/packages/mosaic/src/primitives/image-cropper/parts.ts
new file mode 100644
index 00000000000..1c3b756bbe9
--- /dev/null
+++ b/packages/mosaic/src/primitives/image-cropper/parts.ts
@@ -0,0 +1,13 @@
+export { type ImageCropperRootProps, ImageCropperRoot as Root } from './image-cropper-root';
+export { type ImageCropperViewportProps, ImageCropperViewport as Viewport } from './image-cropper-viewport';
+export { type ImageCropperAreaProps, ImageCropperArea as Area } from './image-cropper-area';
+export { type ImageCropperImageProps, ImageCropperImage as Image } from './image-cropper-image';
+export { type ImageCropperZoomProps, ImageCropperZoom as Zoom } from './image-cropper-zoom';
+export {
+  type ImageCropperZoomInProps,
+  type ImageCropperZoomOutProps,
+  ImageCropperZoomIn as ZoomIn,
+  ImageCropperZoomOut as ZoomOut,
+} from './image-cropper-zoom-step';
+export { type ImageCropperRotateProps, ImageCropperRotate as Rotate } from './image-cropper-rotate';
+export { type ImageCropperResetProps, ImageCropperReset as Reset } from './image-cropper-reset';

From 6b52ec4bf3d967726c780b94728fff29841c7bf2 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 12 Nov 2026 09:42:05 -0500
Subject: [PATCH 2/5] docs(mosaic): list ImageCropper in reuse before you write

---
 packages/mosaic/AGENTS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/mosaic/AGENTS.md b/packages/mosaic/AGENTS.md
index 6ce43ec589a..03e42907fa7 100644
--- a/packages/mosaic/AGENTS.md
+++ b/packages/mosaic/AGENTS.md
@@ -87,6 +87,7 @@ Most problems a feature hits already have a shared answer. Find the line for you
 - The seconds left on a resend cooldown, for display → `useResendSeconds` (`src/hooks/`), from a `resendAvailableAt` time kept in the machine
 - An avatar or logo row: picker, drop target, Upload button or manage menu → `AvatarUpload` (`src/blocks/avatar-upload/`), laid out by the caller
 - Any other file picker or drop zone, such as a metadata or key file → `FileUpload` (`src/primitives/file-upload/`), see its `README.md`
+- Cropping an image to a square: pan, zoom, rotate, then draw the result → `ImageCropper` and `cropImage` (`src/primitives/image-cropper/`), see its `README.md`
 - An inline notice inside content: info, warning, error or success → `Banner` (`src/components/banner/`); a form-level error on a card uses `Card.Banner`
 - Siblings that slide when an item is added or removed → `useLayoutAnimation` (`src/primitives/hooks/`)
 - An input that reformats as the user types without moving the caret → `useFormattedInput` (`src/primitives/hooks/`)

From d0ec8a703785d1f26c3e884548467df1143b2ff7 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 12 Nov 2026 10:05:39 -0500
Subject: [PATCH 3/5] fix(mosaic): size an image cropper image that loaded
 before it mounted

---
 .../__tests__/image-cropper.test.tsx             | 16 +++++++++++++++-
 .../image-cropper/image-cropper-image.tsx        | 10 +++++++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
index ea2e685fd11..c211d863e9b 100644
--- a/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
@@ -6,7 +6,10 @@ import { axe } from '../../test-utils/axe';
 import type { Crop } from '../crop';
 import { ImageCropper, type ImageCropperRootProps } from '../index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
 
 function Harness(props: Partial<ImageCropperRootProps>) {
   return (
@@ -54,6 +57,17 @@ describe('ImageCropper', () => {
     expect(screen.getByRole('button', { name: 'Rotate' })).toBeEnabled();
   });
 
+  it('takes the size of an image that finished loading before it mounted', () => {
+    vi.spyOn(HTMLImageElement.prototype, 'complete', 'get').mockReturnValue(true);
+    vi.spyOn(HTMLImageElement.prototype, 'naturalWidth', 'get').mockReturnValue(200);
+    vi.spyOn(HTMLImageElement.prototype, 'naturalHeight', 'get').mockReturnValue(100);
+
+    render(<Harness />);
+
+    expect(screen.getByRole('slider', { name: 'Zoom' })).toBeEnabled();
+    expect(document.querySelector('img')?.style.width).toBe('200%');
+  });
+
   it('sizes the image to cover the frame', () => {
     render(<Harness />);
     const image = load(200, 100);
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
index 7508ed40843..baa08b5e0bb 100644
--- a/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-image.tsx
@@ -12,6 +12,14 @@ export const ImageCropperImage = React.forwardRef<HTMLImageElement, ImageCropper
   function ImageCropperImage(props, ref) {
     const { render, ...otherProps } = props;
     const { src, crop, size, setSize } = useImageCropperContext();
+    const readLoaded = React.useCallback(
+      (image: HTMLImageElement | null) => {
+        if (image?.complete && image.naturalWidth > 0) {
+          setSize({ width: image.naturalWidth, height: image.naturalHeight });
+        }
+      },
+      [setSize],
+    );
 
     const defaultProps = {
       src,
@@ -26,7 +34,7 @@ export const ImageCropperImage = React.forwardRef<HTMLImageElement, ImageCropper
 
     return useRender({
       defaultTagName: 'img',
-      ref,
+      ref: [ref, readLoaded],
       render,
       state: { loaded: size !== undefined },
       stateAttributesMapping: {

From 09960bfd55d0a49aa4b5546b858a584453b1b179 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 12 Nov 2026 10:05:40 -0500
Subject: [PATCH 4/5] docs(swingset): add ImageCropper primitive page

---
 .../swingset/src/components/DocsViewer.tsx    |   1 +
 packages/swingset/src/lib/registry.ts         |   3 +
 .../swingset/src/stories/image-cropper.mdx    | 141 ++++++++++++++++++
 .../src/stories/image-cropper.stories.tsx     |  76 ++++++++++
 4 files changed, 221 insertions(+)
 create mode 100644 packages/swingset/src/stories/image-cropper.mdx
 create mode 100644 packages/swingset/src/stories/image-cropper.stories.tsx

diff --git a/packages/swingset/src/components/DocsViewer.tsx b/packages/swingset/src/components/DocsViewer.tsx
index 76da1ecc6e7..07d9df7de02 100644
--- a/packages/swingset/src/components/DocsViewer.tsx
+++ b/packages/swingset/src/components/DocsViewer.tsx
@@ -136,6 +136,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     drawer: dynamic(() => import('../stories/drawer.mdx')),
     'file-upload': dynamic(() => import('../stories/file-upload.mdx')),
     flow: dynamic(() => import('../stories/flow.mdx')),
+    'image-cropper': dynamic(() => import('../stories/image-cropper.mdx')),
     menu: dynamic(() => import('../stories/menu.mdx')),
     otp: dynamic(() => import('../stories/otp.mdx')),
     popover: dynamic(() => import('../stories/popover.mdx')),
diff --git a/packages/swingset/src/lib/registry.ts b/packages/swingset/src/lib/registry.ts
index ebe23ff82dc..681fa5211d7 100644
--- a/packages/swingset/src/lib/registry.ts
+++ b/packages/swingset/src/lib/registry.ts
@@ -123,6 +123,7 @@ import {
   Sizes as IconFrameSizes,
   Treatments as IconFrameTreatments,
 } from '../stories/icon-frame.stories';
+import { meta as imageCropperMeta } from '../stories/image-cropper.stories';
 import {
   Default,
   Disabled as InputDisabled,
@@ -1026,6 +1027,7 @@ const dialogModule: StoryModule = { meta: dialogMeta };
 const drawerModule: StoryModule = { meta: drawerMeta };
 const fileUploadModule: StoryModule = { meta: fileUploadMeta };
 const flowModule: StoryModule = { meta: flowMeta };
+const imageCropperModule: StoryModule = { meta: imageCropperMeta };
 const menuModule: StoryModule = { meta: menuMeta };
 const otpModule: StoryModule = { meta: otpMeta };
 const popoverModule: StoryModule = { meta: popoverMeta };
@@ -1434,6 +1436,7 @@ export const registry: StoryModule[] = [
   drawerModule,
   fileUploadModule,
   flowModule,
+  imageCropperModule,
   menuModule,
   otpModule,
   popoverModule,
diff --git a/packages/swingset/src/stories/image-cropper.mdx b/packages/swingset/src/stories/image-cropper.mdx
new file mode 100644
index 00000000000..31930bf95fb
--- /dev/null
+++ b/packages/swingset/src/stories/image-cropper.mdx
@@ -0,0 +1,141 @@
+import * as ImageCropperStories from './image-cropper.stories';
+
+# Image Cropper
+
+Crops an image to a square. The user pans by dragging or with the arrow keys, zooms with the wheel, a
+pinch, the keyboard, a slider or step buttons, turns it a quarter at a time, and resets it.
+`cropImage` then draws the chosen square into a new image. It is a **headless** primitive: it ships
+**no styles**. You size the frame, draw any mask over it, and style the controls through the `data-*`
+attributes each part emits.
+
+## Example
+
+The demo is intentionally unstyled. The only inline styles give the frame a size and clip the image,
+which the primitive leaves to you. Drag, zoom or rotate the image, then press Crop to see the 128px
+result from `cropImage`.
+
+<Story
+  name='Default'
+  storyModule={ImageCropperStories}
+/>
+
+## Usage
+
+```tsx
+import { type Crop, cropImage, ImageCropper, INITIAL_CROP } from '@clerk/mosaic/primitives/image-cropper';
+
+const [crop, setCrop] = useState<Crop>(INITIAL_CROP);
+
+<ImageCropper.Root
+  src={src}
+  value={crop}
+  onValueChange={setCrop}
+>
+  <ImageCropper.Viewport aria-label='Crop. Drag or use the arrow keys to move, plus and minus to zoom.'>
+    <ImageCropper.Image />
+  </ImageCropper.Viewport>
+  <ImageCropper.ZoomOut aria-label='Zoom out'>−</ImageCropper.ZoomOut>
+  <ImageCropper.Zoom aria-label='Zoom' />
+  <ImageCropper.ZoomIn aria-label='Zoom in'>+</ImageCropper.ZoomIn>
+  <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
+  <ImageCropper.Reset>Reset</ImageCropper.Reset>
+</ImageCropper.Root>;
+
+const blob = await cropImage(src, crop, { size: 512, type: 'image/png' });
+```
+
+### A crop area inside a larger frame
+
+Without `Area`, the whole `Viewport` is the crop. Wrap the image in `Area` to make the crop a smaller
+square, and the `Viewport` around it shows the rest of the image for context. Drags are measured
+against the `Area`, so the image follows the pointer either way.
+
+```tsx
+<ImageCropper.Viewport aria-label='Crop'>
+  <ImageCropper.Area>
+    <ImageCropper.Image />
+  </ImageCropper.Area>
+</ImageCropper.Viewport>
+```
+
+## Parts
+
+| Part                    | Default Element        | Description                                                            |
+| ----------------------- | ---------------------- | ---------------------------------------------------------------------- |
+| `ImageCropper.Root`     | none                   | Owns the crop and the image size, provides context                     |
+| `ImageCropper.Viewport` | `<div>`                | The frame: pans on drag and arrow keys, zooms on wheel, pinch and keys |
+| `ImageCropper.Area`     | `<div>`                | The square that is cropped, when it is smaller than the frame          |
+| `ImageCropper.Image`    | `<img>`                | The image, placed by the crop. Reports its size on load                |
+| `ImageCropper.Zoom`     | `<input type="range">` | Sets the zoom, from 1 to `maxZoom`                                     |
+| `ImageCropper.ZoomIn`   | `<button>`             | Zooms in one step. Disabled at `maxZoom`                               |
+| `ImageCropper.ZoomOut`  | `<button>`             | Zooms out one step. Disabled at 1                                      |
+| `ImageCropper.Rotate`   | `<button>`             | Turns the image a quarter clockwise                                    |
+| `ImageCropper.Reset`    | `<button>`             | Returns to `INITIAL_CROP`                                              |
+
+All parts except `Root` accept a `render` prop and standard HTML attributes for their default
+element. Every control stays disabled until the image has loaded, because the crop limits depend on
+its size.
+
+## Props
+
+### `ImageCropper.Root`
+
+| Prop                       | Type                              | Default                   | Description                                     |
+| -------------------------- | --------------------------------- | ------------------------- | ----------------------------------------------- |
+| <code>src</code>           | <code>string</code>               | — (required)              | The image to crop, such as an object URL        |
+| <code>value</code>         | <code>Crop</code>                 | —                         | Controlled crop                                 |
+| <code>defaultValue</code>  | <code>Crop</code>                 | <code>INITIAL_CROP</code> | Initial crop (uncontrolled)                     |
+| <code>onValueChange</code> | <code>(crop: Crop) => void</code> | —                         | Called on every pan, zoom, turn and reset       |
+| <code>maxZoom</code>       | <code>number</code>               | <code>4</code>            | Largest zoom, as a multiple of the cover scale  |
+| <code>disabled</code>      | <code>boolean</code>              | <code>false</code>        | Ignores every gesture and disables the controls |
+
+A `Crop` is `{ x, y, zoom, rotation }`. `x` and `y` move the image centre from the frame centre, as a
+fraction of the frame. `zoom` 1 is the smallest scale that still covers the frame. `rotation` is `0`,
+`90`, `180` or `270`. The crop is always clamped so the image covers the frame.
+
+Other parts take no additional props beyond standard HTML attributes for their default element.
+
+### `cropImage(src, crop, { size, type })`
+
+Returns a `Promise<Blob>` holding the square the crop shows, `size` pixels wide, encoded as `type`. It
+draws to a canvas, so an animated image keeps only its first frame.
+
+### Keyboard
+
+On a focused `Viewport`:
+
+| Key        | Action                   |
+| ---------- | ------------------------ |
+| Arrow keys | Pan. Hold Shift for more |
+| `+` / `=`  | Zoom in one step         |
+| `-` / `_`  | Zoom out one step        |
+| `0`        | Reset                    |
+
+## Styling
+
+The primitive sets only the `Image` placement (absolute, centred, scaled and rotated by the crop) and
+`touch-action: none` on the `Viewport`. Give the `Viewport` a size, `position: relative` and
+`overflow: hidden`.
+
+| Attribute       | Applies To                                     | Description                         |
+| --------------- | ---------------------------------------------- | ----------------------------------- |
+| `data-dragging` | Viewport                                       | Present while a pointer is dragging |
+| `data-loaded`   | Image                                          | Present once the image has loaded   |
+| `data-disabled` | Viewport, Zoom, ZoomIn, ZoomOut, Rotate, Reset | Present when the part is disabled   |
+
+```css
+.cropper-viewport {
+  position: relative;
+  overflow: hidden;
+  width: 240px;
+  height: 240px;
+  cursor: grab;
+}
+.cropper-viewport[data-dragging] {
+  cursor: grabbing;
+}
+```
+
+`Viewport` has `role="application"` so screen readers pass the arrow keys through; give it an
+`aria-label` that names the keys. It leaves the tab order until the image has loaded. `Image` has an
+empty `alt`, because the `Viewport` label describes it. Give icon-only buttons an `aria-label`.
diff --git a/packages/swingset/src/stories/image-cropper.stories.tsx b/packages/swingset/src/stories/image-cropper.stories.tsx
new file mode 100644
index 00000000000..a7fd899d177
--- /dev/null
+++ b/packages/swingset/src/stories/image-cropper.stories.tsx
@@ -0,0 +1,76 @@
+import { type Crop, cropImage, ImageCropper, INITIAL_CROP } from '@clerk/mosaic/primitives/image-cropper';
+import { useEffect, useState } from 'react';
+
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Primitives',
+  status: 'stable',
+  title: 'ImageCropper',
+  label: 'Image Cropper',
+  source: 'packages/mosaic/src/primitives/image-cropper/index.ts',
+};
+
+const SAMPLE = `data:image/svg+xml,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="400" viewBox="0 0 640 400">
+    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#6c47ff"/><stop offset="1" stop-color="#ffb547"/></linearGradient></defs>
+    <rect width="640" height="400" fill="url(#g)"/>
+    <circle cx="320" cy="200" r="90" fill="#fff" fill-opacity="0.85"/>
+    <text x="320" y="214" font-family="sans-serif" font-size="40" text-anchor="middle">top</text>
+  </svg>`,
+)}`;
+
+export function Default() {
+  const [crop, setCrop] = useState<Crop>(INITIAL_CROP);
+  const [result, setResult] = useState<string | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (result) {
+        URL.revokeObjectURL(result);
+      }
+    };
+  }, [result]);
+
+  return (
+    <div>
+      <ImageCropper.Root
+        src={SAMPLE}
+        value={crop}
+        onValueChange={setCrop}
+      >
+        <ImageCropper.Viewport
+          aria-label='Crop. Drag or use the arrow keys to move, plus and minus to zoom.'
+          style={{ position: 'relative', overflow: 'hidden', width: 240, height: 240 }}
+        >
+          <ImageCropper.Image />
+        </ImageCropper.Viewport>
+        <div>
+          <ImageCropper.ZoomOut aria-label='Zoom out'>−</ImageCropper.ZoomOut>
+          <ImageCropper.Zoom aria-label='Zoom' />
+          <ImageCropper.ZoomIn aria-label='Zoom in'>+</ImageCropper.ZoomIn>
+          <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
+          <ImageCropper.Reset>Reset</ImageCropper.Reset>
+          <button
+            type='button'
+            onClick={() => {
+              void cropImage(SAMPLE, crop, { size: 128, type: 'image/png' }).then(blob =>
+                setResult(URL.createObjectURL(blob)),
+              );
+            }}
+          >
+            Crop
+          </button>
+        </div>
+      </ImageCropper.Root>
+      {result ? (
+        <img
+          src={result}
+          alt='Cropped result'
+          width={128}
+          height={128}
+        />
+      ) : null}
+    </div>
+  );
+}

From f80d585dce328367b2d5194e44eefa950761921b Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 12 Nov 2026 10:31:59 -0500
Subject: [PATCH 5/5] fix(mosaic): address ImageCropper review feedback

- clamp a crop passed in, on screen and in cropImage
- convert wheel deltas in lines or pages to pixels
- skip a pinch that starts with zero distance
- leave the wheel and touch to the page until the image loads
- leave arrow keys to controls placed inside the viewport
- import useState in the usage examples
---
 .../src/primitives/image-cropper/README.md    |  2 +
 .../__tests__/crop-image.browser.test.tsx     |  8 +++
 .../__tests__/image-cropper.test.tsx          | 67 +++++++++++++++++++
 .../primitives/image-cropper/crop-image.ts    |  4 +-
 .../image-cropper/image-cropper-root.tsx      |  3 +-
 .../image-cropper/image-cropper-viewport.tsx  | 30 ++++++---
 .../swingset/src/stories/image-cropper.mdx    |  4 +-
 7 files changed, 105 insertions(+), 13 deletions(-)

diff --git a/packages/mosaic/src/primitives/image-cropper/README.md b/packages/mosaic/src/primitives/image-cropper/README.md
index 7b60f90ae72..04a5ed852d0 100644
--- a/packages/mosaic/src/primitives/image-cropper/README.md
+++ b/packages/mosaic/src/primitives/image-cropper/README.md
@@ -14,6 +14,8 @@ controls through `data-*` attributes.
 ## Usage
 
 ```tsx
+import { useState } from 'react';
+
 import { type Crop, cropImage, ImageCropper, INITIAL_CROP } from '../../primitives/image-cropper';
 
 function Cropper({ src, onSave }: { src: string; onSave: (blob: Blob) => void }) {
diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx b/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
index 89d23340835..4e6718e84c0 100644
--- a/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/crop-image.browser.test.tsx
@@ -59,4 +59,12 @@ describe('cropImage', () => {
     expect(image.at(32, 8)).toEqual(RED);
     expect(image.at(32, 56)).toEqual(BLUE);
   });
+
+  it('clamps a crop that would leave part of the square outside the image', async () => {
+    const blob = await cropImage(halves(100, 100), { ...INITIAL_CROP, x: 0.5 }, { size: 64, type: 'image/png' });
+    const image = await pixels(blob);
+
+    expect(image.at(8, 32)).toEqual(RED);
+    expect(image.at(56, 32)).toEqual(BLUE);
+  });
 });
diff --git a/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
index c211d863e9b..e0f11efd802 100644
--- a/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/__tests__/image-cropper.test.tsx
@@ -245,6 +245,73 @@ describe('ImageCropper', () => {
     expect(lastCrop(onValueChange)?.zoom).toBe(2);
   });
 
+  it('keeps a pinch that starts with both fingers on one point from breaking the crop', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ width: 200, height: 200 }));
+
+    fireEvent.pointerDown(viewport, { pointerId: 1, clientX: 100, clientY: 100, button: 0 });
+    fireEvent.pointerDown(viewport, { pointerId: 2, clientX: 100, clientY: 100, button: 0 });
+    fireEvent.pointerMove(viewport, { pointerId: 2, clientX: 200, clientY: 100 });
+
+    expect(lastCrop(onValueChange)?.zoom).toBe(1);
+  });
+
+  it('zooms the same amount whether the wheel reports pixels or lines', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(<Harness onValueChange={onValueChange} />);
+    load(100, 100);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+
+    fireEvent.wheel(viewport, { deltaY: -48, deltaMode: WheelEvent.DOM_DELTA_PIXEL });
+    const byPixels = lastCrop(onValueChange)?.zoom;
+    fireEvent.keyDown(viewport, { key: '0' });
+    fireEvent.wheel(viewport, { deltaY: -3, deltaMode: WheelEvent.DOM_DELTA_LINE });
+
+    expect(lastCrop(onValueChange)?.zoom).toBeCloseTo(byPixels ?? Number.NaN);
+  });
+
+  it('leaves the wheel and touch to the page until the image has loaded', () => {
+    render(<Harness />);
+    const viewport = screen.getByRole('application', { name: 'Crop' });
+
+    expect(fireEvent.wheel(viewport, { deltaY: -48 })).toBe(true);
+    expect(viewport.style.touchAction).toBe('');
+
+    load(100, 100);
+
+    expect(fireEvent.wheel(viewport, { deltaY: -48 })).toBe(false);
+    expect(viewport.style.touchAction).toBe('none');
+  });
+
+  it('leaves arrow keys to a slider placed inside the frame', () => {
+    const onValueChange = vi.fn<(crop: Crop) => void>();
+    render(
+      <ImageCropper.Root
+        src='photo.png'
+        onValueChange={onValueChange}
+      >
+        <ImageCropper.Viewport aria-label='Crop'>
+          <ImageCropper.Image alt='' />
+          <ImageCropper.Zoom aria-label='Zoom' />
+        </ImageCropper.Viewport>
+      </ImageCropper.Root>,
+    );
+    load(100, 100);
+
+    expect(fireEvent.keyDown(screen.getByRole('slider', { name: 'Zoom' }), { key: 'ArrowLeft' })).toBe(true);
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it('clamps a crop passed in, so the image still covers the frame', () => {
+    render(<Harness value={{ x: 0.5, y: 0, zoom: 1, rotation: 0 }} />);
+    const image = load(100, 100);
+
+    expect(image.style.left).toBe('50%');
+  });
+
   it('ignores every gesture while disabled', async () => {
     const user = userEvent.setup();
     const onValueChange = vi.fn<(crop: Crop) => void>();
diff --git a/packages/mosaic/src/primitives/image-cropper/crop-image.ts b/packages/mosaic/src/primitives/image-cropper/crop-image.ts
index 3904b49cfd5..5fc2e359a2b 100644
--- a/packages/mosaic/src/primitives/image-cropper/crop-image.ts
+++ b/packages/mosaic/src/primitives/image-cropper/crop-image.ts
@@ -1,4 +1,4 @@
-import { type Crop, pixelCrop, turned } from './crop';
+import { clampCrop, type Crop, pixelCrop, turned } from './crop';
 
 export interface CropImageOptions {
   /** Width and height of the output, in pixels. */
@@ -19,7 +19,7 @@ export async function cropImage(src: string, crop: Crop, { size, type }: CropIma
   await image.decode();
 
   const natural = { width: image.naturalWidth, height: image.naturalHeight };
-  const area = pixelCrop(crop, natural);
+  const area = pixelCrop(clampCrop(crop, natural, Number.POSITIVE_INFINITY), natural);
   const upright = turned(natural, crop.rotation);
 
   const canvas = document.createElement('canvas');
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
index 4eeac191035..a08604c73fe 100644
--- a/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-root.tsx
@@ -31,8 +31,9 @@ export function ImageCropperRoot({
   disabled = false,
   children,
 }: ImageCropperRootProps) {
-  const [crop, setCrop] = useControllableState(value, defaultValue, onValueChange);
+  const [stored, setCrop] = useControllableState(value, defaultValue, onValueChange);
   const [size, setSize] = useState<Size>();
+  const crop = useMemo(() => (size ? clampCrop(stored, size, maxZoom) : stored), [stored, size, maxZoom]);
   const area = useRef<HTMLDivElement | null>(null);
   const latest = useRef(crop);
   // eslint-disable-next-line react/refs -- This ref holds an imperative resource or the latest callback outside React state.
diff --git a/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx b/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
index 7bbafffb42e..c22a9c71e73 100644
--- a/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
+++ b/packages/mosaic/src/primitives/image-cropper/image-cropper-viewport.tsx
@@ -16,6 +16,7 @@ interface Point {
 const KEY_PAN = 0.02;
 const KEY_PAN_LARGE = 0.1;
 const WHEEL_ZOOM = 0.002;
+const WHEEL_LINE = 16;
 
 export const ImageCropperViewport = React.forwardRef<HTMLDivElement, ImageCropperViewportProps>(
   function ImageCropperViewport(props, ref) {
@@ -25,18 +26,20 @@ export const ImageCropperViewport = React.forwardRef<HTMLDivElement, ImageCroppe
     const pointers = useRef(new Map<number, Point>());
     const [dragging, setDragging] = useState(false);
 
+    const ready = size !== undefined && !disabled;
+
     useEffect(() => {
       const element = elementRef.current;
-      if (!element) {
+      if (!element || !ready) {
         return;
       }
       const onWheel = (event: WheelEvent) => {
         event.preventDefault();
-        zoomBy(Math.exp(-event.deltaY * WHEEL_ZOOM));
+        zoomBy(Math.exp(-wheelPixels(event, element.clientHeight) * WHEEL_ZOOM));
       };
       element.addEventListener('wheel', onWheel, { passive: false });
       return () => element.removeEventListener('wheel', onWheel);
-    }, [zoomBy]);
+    }, [ready, zoomBy]);
 
     const release = (pointerId: number) => {
       pointers.current.delete(pointerId);
@@ -45,12 +48,10 @@ export const ImageCropperViewport = React.forwardRef<HTMLDivElement, ImageCroppe
       }
     };
 
-    const ready = size !== undefined && !disabled;
-
     const defaultProps = {
       role: 'application',
       tabIndex: ready ? 0 : -1,
-      style: { touchAction: 'none' },
+      style: ready ? { touchAction: 'none' } : undefined,
       onPointerDown: event => {
         if (!ready || event.button !== 0) {
           return;
@@ -76,15 +77,16 @@ export const ImageCropperViewport = React.forwardRef<HTMLDivElement, ImageCroppe
         pan((to.x - from.x) / frame, (to.y - from.y) / frame);
         const [a, b] = before;
         const [c, d] = after;
-        if (a && b && c && d) {
-          zoomBy(distance(c, d) / distance(a, b));
+        const start = a && b ? distance(a, b) : 0;
+        if (c && d && start > 0) {
+          zoomBy(distance(c, d) / start);
         }
       },
       onPointerUp: event => release(event.pointerId),
       onPointerCancel: event => release(event.pointerId),
       onLostPointerCapture: event => release(event.pointerId),
       onKeyDown: event => {
-        if (!ready) {
+        if (!ready || event.target !== event.currentTarget) {
           return;
         }
         const step = event.shiftKey ? KEY_PAN_LARGE : KEY_PAN;
@@ -143,6 +145,16 @@ function keyAction(key: string, step: number): KeyAction | undefined {
   }
 }
 
+function wheelPixels(event: WheelEvent, page: number): number {
+  if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) {
+    return event.deltaY * WHEEL_LINE;
+  }
+  if (event.deltaMode === WheelEvent.DOM_DELTA_PAGE) {
+    return event.deltaY * page;
+  }
+  return event.deltaY;
+}
+
 function midpoint(points: Point[]): Point {
   const sum = points.reduce((total, point) => ({ x: total.x + point.x, y: total.y + point.y }), { x: 0, y: 0 });
   return { x: sum.x / points.length, y: sum.y / points.length };
diff --git a/packages/swingset/src/stories/image-cropper.mdx b/packages/swingset/src/stories/image-cropper.mdx
index 31930bf95fb..a48c7f3ee68 100644
--- a/packages/swingset/src/stories/image-cropper.mdx
+++ b/packages/swingset/src/stories/image-cropper.mdx
@@ -22,6 +22,8 @@ result from `cropImage`.
 ## Usage
 
 ```tsx
+import { useState } from 'react';
+
 import { type Crop, cropImage, ImageCropper, INITIAL_CROP } from '@clerk/mosaic/primitives/image-cropper';
 
 const [crop, setCrop] = useState<Crop>(INITIAL_CROP);
@@ -114,7 +116,7 @@ On a focused `Viewport`:
 ## Styling
 
 The primitive sets only the `Image` placement (absolute, centred, scaled and rotated by the crop) and
-`touch-action: none` on the `Viewport`. Give the `Viewport` a size, `position: relative` and
+`touch-action: none` on the `Viewport` once the image has loaded. Give the `Viewport` a size, `position: relative` and
 `overflow: hidden`.
 
 | Attribute       | Applies To                                     | Description                         |