@bycrux/editor 0.4.1

package/src/carousel/__tests__/ReadOnlySlide.test.tsx

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { ImageElement, OverlayElement, Slide } from '../../types'
+import ReadOnlySlide from '../ReadOnlySlide'
+
+// ── ResizeObserver mock plumbing ──────────────────────────────────────────────
+// jsdom has no ResizeObserver. We capture the instances so autoFit tests can
+// drive a callback with a controlled parent size.
+let roInstances: Array<{ cb: ResizeObserverCallback; el: Element | null }> = []
+beforeEach(() => {
+  roInstances = []
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    cb: ResizeObserverCallback
+    el: Element | null = null
+    constructor(cb: ResizeObserverCallback) {
+      this.cb = cb
+      roInstances.push(this)
+    }
+    observe(el: Element) {
+      this.el = el
+    }
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+const imgEl: ImageElement = {
+  id: 'el-img',
+  type: 'image',
+  src: 'a.png',
+  x: 100,
+  y: 100,
+  w: 200,
+  h: 200,
+  rotation: 0,
+}
+
+const overlayEl: OverlayElement = {
+  id: 'el-ov',
+  type: 'overlay',
+  overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+  frame: 0,
+  x: 50,
+  y: 800,
+  w: 400,
+  h: 120,
+  rotation: 0,
+}
+
+function makeSlide(elements: Slide['elements']): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements }
+}
+
+describe('ReadOnlySlide', () => {
+  it("renders a slide's image + overlay non-interactively (no interactive chrome)", async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl, overlayEl])}
+        width={1080}
+        height={1080}
+        scale={0.5}
+        resolveImageSrc={(el) => el.src}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+
+    // Image element renders.
+    const img = await waitFor(() => {
+      const el = container.querySelector('[data-element-id="el-img"]') as HTMLElement
+      if (!el) throw new Error('image wrapper not yet rendered')
+      return el
+    })
+
+    // Non-interactive: the canvas root must not advertise interactivity, and the
+    // element wrappers must not receive pointer events (no selection chrome).
+    expect(container.querySelector('[data-interactive]')).toBeNull()
+    expect(img.style.pointerEvents).toBe('none')
+
+    // No resize / rotate handles rendered in read-only mode.
+    expect(container.querySelector('[data-testid="rotate-handle"]')).toBeNull()
+    expect(container.querySelector('[data-testid="resize-handle-nw"]')).toBeNull()
+  })
+
+  it('applies the explicit scale when provided', async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl])}
+        width={1080}
+        height={1080}
+        scale={0.5}
+        resolveImageSrc={(el) => el.src}
+      />,
+    )
+    // displayW = width * scale = 1080 * 0.5 = 540.
+    await waitFor(() => {
+      const inner = container.querySelector('[data-element-id="el-img"]') as HTMLElement
+      if (!inner) throw new Error('not rendered')
+    })
+    const canvas = container.querySelector('div > div') as HTMLElement
+    // The SlideCanvas root sets width to displayW; find a node sized 540px.
+    const sized = Array.from(container.querySelectorAll('div')).some(
+      (d) => (d as HTMLElement).style.width === '540px',
+    )
+    expect(sized).toBe(true)
+    expect(canvas).toBeTruthy()
+  })
+
+  it('measures the parent and applies a fitted scale when autoFit is on', async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl])}
+        width={1080}
+        height={1080}
+        autoFit
+        resolveImageSrc={(el) => el.src}
+      />,
+    )
+
+    // A ResizeObserver was created and is observing the root.
+    await waitFor(() => expect(roInstances.length).toBeGreaterThan(0))
+    const ro = roInstances[0]
+    expect(ro.el).not.toBeNull()
+
+    // Drive the observer: parent of the root is 540x540 → fit = 540/1080 = 0.5.
+    const root = ro.el as HTMLElement
+    Object.defineProperty(root, 'clientWidth', { value: 540, configurable: true })
+    Object.defineProperty(root, 'clientHeight', { value: 540, configurable: true })
+    ro.cb([], ro as unknown as ResizeObserver)
+
+    // After measuring, SlideCanvas renders at displayW = 1080 * 0.5 = 540.
+    await waitFor(() => {
+      const sized = Array.from(container.querySelectorAll('div')).some(
+        (d) => (d as HTMLElement).style.width === '540px',
+      )
+      expect(sized).toBe(true)
+    })
+  })
+})

package/src/carousel/__tests__/SlideCanvasCrop.test.tsx

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { ImageElement, Slide } from '../../types'
+import SlideCanvas from '../SlideCanvas'
+
+beforeEach(() => {
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+function makeSlide(el: ImageElement): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements: [el] }
+}
+
+describe('SlideCanvas crop display', () => {
+  it('renders the oversized-cover crop variant when element.crop is present (non-interactive)', async () => {
+    const el: ImageElement = {
+      id: 'el-img',
+      type: 'image',
+      src: 'a.png',
+      x: 0,
+      y: 0,
+      w: 200,
+      h: 200,
+      rotation: 0,
+      crop: { x: 0.25, y: 0.1, w: 0.5, h: 0.5 },
+    }
+    const { container } = render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        resolveImageSrc={(e) => e.src}
+      />,
+    )
+
+    const img = await waitFor(() => {
+      const found = container.querySelector('[data-element-id="el-img"] img') as HTMLImageElement
+      if (!found) throw new Error('img not rendered')
+      return found
+    })
+
+    // Oversized cover: width = 100/cw = 200%, height = 100/ch = 200%.
+    expect(img.style.width).toBe('200%')
+    expect(img.style.height).toBe('200%')
+    // marginLeft = -cx*100/cw = -0.25*100/0.5 = -50%; marginTop = -0.1*100/0.5 = -20%.
+    expect(img.style.marginLeft).toBe('-50%')
+    expect(img.style.marginTop).toBe('-20%')
+    // Tailwind-preflight defeat.
+    expect(img.style.maxWidth).toBe('none')
+    expect(img.style.maxHeight).toBe('none')
+
+    // The crop wrapper clips overflow.
+    const wrapper = img.parentElement as HTMLElement
+    expect(wrapper.style.overflow).toBe('hidden')
+  })
+
+  it('renders plain cover (no crop wrapper) when element.crop is absent', async () => {
+    const el: ImageElement = {
+      id: 'el-img',
+      type: 'image',
+      src: 'a.png',
+      x: 0,
+      y: 0,
+      w: 200,
+      h: 200,
+      rotation: 0,
+    }
+    const { container } = render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        resolveImageSrc={(e) => e.src}
+      />,
+    )
+
+    const img = await waitFor(() => {
+      const found = container.querySelector('[data-element-id="el-img"] img') as HTMLImageElement
+      if (!found) throw new Error('img not rendered')
+      return found
+    })
+    expect(img.style.objectFit).toBe('cover')
+    expect(img.style.width).toBe('100%')
+    expect(img.style.height).toBe('100%')
+  })
+})

package/src/carousel/__tests__/SlideCanvasFonts.test.tsx

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { OverlayElement, Slide } from '../../types'
+
+// Spy on the shared font loader so we can assert the carousel overlay path
+// invokes it with the element's googleFonts list (unit-level — we do not assert
+// actual font bytes load in jsdom).
+const { ensureGoogleFontsLoaded } = vi.hoisted(() => ({ ensureGoogleFontsLoaded: vi.fn() }))
+vi.mock('../../lib/google-fonts', () => ({ ensureGoogleFontsLoaded }))
+
+import SlideCanvas from '../SlideCanvas'
+
+beforeEach(() => {
+  ensureGoogleFontsLoaded.mockClear()
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+function makeSlide(el: OverlayElement): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements: [el] }
+}
+
+describe('SlideCanvas carousel overlay Google Fonts', () => {
+  it('loads an overlay element’s googleFonts via the shared helper', async () => {
+    const el: OverlayElement = {
+      id: 'el-ov',
+      type: 'overlay',
+      overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+      frame: 0,
+      x: 0,
+      y: 0,
+      w: 400,
+      h: 120,
+      rotation: 0,
+      googleFonts: ['Syne:wght@800', 'Inter:wght@400'],
+    }
+    render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+
+    await waitFor(() =>
+      expect(ensureGoogleFontsLoaded).toHaveBeenCalledWith(['Syne:wght@800', 'Inter:wght@400']),
+    )
+  })
+
+  it('does not throw when an overlay element has no googleFonts', async () => {
+    const el: OverlayElement = {
+      id: 'el-ov',
+      type: 'overlay',
+      overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+      frame: 0,
+      x: 0,
+      y: 0,
+      w: 400,
+      h: 120,
+      rotation: 0,
+    }
+    render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+    // Helper is still invoked (with undefined) — it no-ops internally.
+    await waitFor(() => expect(ensureGoogleFontsLoaded).toHaveBeenCalledWith(undefined))
+  })
+})

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)
+  })
+})