@pictor-sdk/ui 0.1.0

package/src/composer/keyboardLayout.ts

@@ -0,0 +1,130 @@
+/**
+ * Keyboard layout maths for the text composer.
+ *
+ * Split from the component so it can be tested without mounting a keyboard,
+ * and kept free of any React Native import so it runs in plain Node.
+ *
+ * The rule this encodes: **the canvas never moves.** Milestone 2 established
+ * that changing canvas metrics mid-interaction moves the ground under the
+ * gesture; the same is true of a caret. So the keyboard's height becomes an
+ * inset for the composer's *controls*, and nothing else in the editor reacts to
+ * it.
+ *
+ * @experimental
+ */
+
+export interface KeyboardFrame {
+  /** Height of the keyboard in dp; 0 when hidden or when a hardware keyboard is attached. */
+  height: number
+  /** Milliseconds the platform will take to move it. Android often reports 0. */
+  duration?: number
+}
+
+export interface ComposerInsets {
+  /** Distance from the bottom of the screen to place the control bar. */
+  bottom: number
+  /** True while the keyboard occupies screen space. */
+  keyboardVisible: boolean
+  /** Animation duration to match the platform's own, clamped to something sane. */
+  duration: number
+}
+
+export const HIDDEN_KEYBOARD: KeyboardFrame = { height: 0 }
+
+/** Longest keyboard animation we will follow; beyond this the UI feels stuck. */
+const MAX_DURATION = 400
+/** Android frequently reports 0; a short move still reads better than a jump. */
+const FALLBACK_DURATION = 180
+
+/**
+ * Where the composer's controls sit, given the keyboard and the safe area.
+ *
+ * When the keyboard is up it already covers the home indicator, so the bottom
+ * safe-area inset must *not* be added on top of it — doing so leaves a visible
+ * gap between the controls and the keyboard on iOS.
+ */
+export function composerInsets(
+  frame: KeyboardFrame,
+  safeAreaBottom = 0,
+): ComposerInsets {
+  const height = Number.isFinite(frame.height) ? Math.max(0, frame.height) : 0
+  const visible = height > 0
+  const raw = frame.duration
+  const duration =
+    raw === undefined || !Number.isFinite(raw) || raw <= 0
+      ? FALLBACK_DURATION
+      : Math.min(MAX_DURATION, raw)
+  return {
+    bottom: visible ? height : Math.max(0, safeAreaBottom),
+    keyboardVisible: visible,
+    duration,
+  }
+}
+
+/**
+ * Whether a keyboard event belongs to the session that is listening.
+ *
+ * Keyboard events arrive asynchronously and can land after a session has
+ * closed — or, worse, after the *next* one has opened. Sessions carry a
+ * monotonic token so a late event from an earlier session is ignored rather
+ * than resizing the wrong composer.
+ */
+export function isCurrentSession(eventToken: number, currentToken: number): boolean {
+  return eventToken === currentToken
+}
+
+/**
+ * Space available for the text itself, between the top chrome and the controls.
+ *
+ * Returns 0 rather than a negative number when the keyboard leaves no room —
+ * a caller sizing a view with this must not be handed a negative height.
+ */
+export function composerContentHeight(
+  screenHeight: number,
+  insets: ComposerInsets,
+  topChrome: number,
+  controlsHeight: number,
+): number {
+  return Math.max(0, screenHeight - topChrome - controlsHeight - insets.bottom)
+}
+
+export interface Box {
+  width: number
+  height: number
+}
+
+export interface CanvasRect {
+  /** Size of the fitted canvas inside the container. */
+  width: number
+  height: number
+  /** Offset of the canvas inside the container, which centres it. */
+  left: number
+  top: number
+}
+
+/**
+ * Where the canvas sits inside a container, fitted to the document's aspect.
+ *
+ * The composer needs this to lay its input over the text it is editing, and it
+ * cannot ask the canvas: `useCanvasMetrics` is provided by `EditorCanvas` to
+ * its own children, and the composer is a sibling of the canvas, not a child.
+ * Reading it there returns `null` — which, when used as a width, silently
+ * produced a zero-width input that swallowed every keystroke.
+ *
+ * So the fit is recomputed here from the same rule `EditorCanvas` uses:
+ * contain, then centre.
+ */
+export function fitCanvasRect(container: Box, document: Box): CanvasRect {
+  if (container.width <= 0 || container.height <= 0 || document.width <= 0 || document.height <= 0) {
+    return { width: 0, height: 0, left: 0, top: 0 }
+  }
+  const scale = Math.min(container.width / document.width, container.height / document.height)
+  const width = document.width * scale
+  const height = document.height * scale
+  return {
+    width,
+    height,
+    left: (container.width - width) / 2,
+    top: (container.height - height) / 2,
+  }
+}

package/src/composer/useTextSession.ts

@@ -0,0 +1,230 @@
+import {
+  clampTextSize,
+  collapseTextSpans,
+  createTextDraft,
+  needsSpanCollapse,
+  isBlankText,
+  patchTextSpan,
+  resolveTextSession,
+  textSpanOf,
+  textValueOf,
+  useEditor,
+  type Layer,
+  type TextLayerData,
+  type TextSpan,
+} from '@pictor-sdk/core'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+/**
+ * The state and commands behind a text-editing session.
+ *
+ * This is the whole contract a composer needs, so the default composer and any
+ * replacement are built on exactly the same surface — which is what makes the
+ * default one genuinely replaceable rather than merely swappable-in-principle.
+ *
+ * The session owns its history batch. The text tool has no bottom-sheet panel —
+ * the composer *is* its UI — so `ToolPanelHost` never opens one for it, and the
+ * session must, or every keystroke would be its own undo entry. Opening it here
+ * also fixes the ordering: the batch is open before the draft is created,
+ * which it would not be if a parent opened it in its own mount effect (effects
+ * run child-first).
+ *
+ * @experimental
+ */
+export interface TextSessionController {
+  /** The layer being edited — a fresh draft, or the one that was selected. */
+  layer: Layer | undefined
+  /** Whether this session created the layer, which decides blank-Done. */
+  kind: 'draft' | 'existing'
+  /** Current text. Mirrors the document; drives the input's value. */
+  value: string
+  /** Replace the text. */
+  setValue(next: string): void
+  /** The span the composer styles as a whole. */
+  span: TextSpan | undefined
+  /** Full layer data, for alignment/fill/stroke/shadow controls. */
+  data: TextLayerData | undefined
+  /** Patch the styled span — font, size, colour, weight, spacing. */
+  styleSpan(patch: Partial<TextSpan>): void
+  /** Patch layer-level text data — alignment, fill, stroke, shadow, maxWidth. */
+  styleText(patch: Partial<TextLayerData>): void
+  /** Set a normalized font size, held inside the supported range. */
+  setSize(size: number): void
+  /**
+   * Finish. A draft that ended blank is discarded and records nothing.
+   *
+   * Returns the committed layer id, or `null` when nothing was kept.
+   */
+  commit(): string | null
+  /** Abandon. Restores the document to exactly its state when the tool opened. */
+  cancel(): void
+}
+
+/** Hooks into the composing session — chiefly what to do when it ends. */
+export interface UseTextSessionOptions {
+  /**
+   * Edit this layer instead of resolving from the selection. Lets a custom UI
+   * request editing for a specific layer — the re-entry API.
+   */
+  layerId?: string
+  /** Called once the session has committed or been discarded. */
+  onFinished?: (layerId: string | null) => void
+}
+
+/**
+ * Open a text-editing session for the current selection (or `layerId`).
+ *
+ * Creates its draft on mount so the canvas shows the layer immediately and the
+ * caret has something to sit on.
+ */
+export function useTextSession(options: UseTextSessionOptions = {}): TextSessionController {
+  const { document, dispatch, profile, selection, select } = useEditor()
+  const { layerId: requestedId, onFinished } = options
+
+  // Resolved once: what the session is editing must not change under the user
+  // because the selection moved.
+  const [session] = useState(() =>
+    resolveTextSession(document.layers, requestedId ? [requestedId] : selection),
+  )
+  const [draftId, setDraftId] = useState<string | null>(null)
+  const finished = useRef(false)
+  /**
+   * The selection as it was before the session opened.
+   *
+   * Rolling the *document* back is not enough: a draft replaces the selection
+   * with its own id, so a rollback that clears the selection leaves the editor
+   * in a state the user never chose. Captured once, restored on every rollback
+   * path — Cancel, blank-draft Done, and unmount.
+   */
+  const priorSelection = useRef<string[]>([])
+  const capturedPrior = useRef(false)
+  if (!capturedPrior.current) {
+    capturedPrior.current = true
+    priorSelection.current = [...selection]
+  }
+
+  const latest = useRef({ document, dispatch, select, selection, profile })
+  latest.current = { document, dispatch, select, selection, profile }
+
+  // Open the transaction, then create the draft inside it. Both exactly once:
+  // a second draft would be a second layer, and a second batch would leak depth.
+  useEffect(() => {
+    latest.current.dispatch({ type: 'history/beginBatch', label: 'text' })
+    if (session.kind === 'draft') {
+      const draft = createTextDraft(latest.current.profile)
+      setDraftId(draft.id)
+      latest.current.dispatch({ type: 'layer/add', layer: draft })
+      latest.current.select([draft.id])
+    } else if (session.layerId) {
+      // Whole-layer editing cannot address more than one span, so a multi-span
+      // layer is collapsed up front — inside the batch, so Cancel reverses it
+      // exactly. See `collapseTextSpans` for why.
+      const layer = latest.current.document.layers.find((l) => l.id === session.layerId)
+      const layerData = layer?.data as TextLayerData | undefined
+      if (layerData && needsSpanCollapse(layerData)) {
+        latest.current.dispatch({
+          type: 'layer/patchData',
+          id: session.layerId,
+          patch: { spans: collapseTextSpans(layerData).spans },
+        })
+      }
+    }
+    return () => {
+      // Unmounting without Done or Cancel — a tool switch, a navigation, an
+      // unmount mid-typing — must not leave the batch open or the edit applied.
+      if (finished.current) return
+      finished.current = true
+      latest.current.dispatch({ type: 'history/cancelBatch' })
+      latest.current.select(priorSelection.current)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const layerId = session.kind === 'existing' ? session.layerId! : draftId
+  const layer = layerId ? document.layers.find((l) => l.id === layerId) : undefined
+  const data = layer ? (layer.data as TextLayerData) : undefined
+  const span = data ? textSpanOf(data) : undefined
+  const value = data ? textValueOf(data) : ''
+
+  // Read through refs so the commands keep a stable identity: a composer that
+  // re-created its callbacks each keystroke would remount its controls.
+  const idRef = useRef<string | null>(null)
+  idRef.current = layerId ?? null
+  const dataRef = useRef<TextLayerData | undefined>(undefined)
+  dataRef.current = data
+
+  const patchData = useCallback((patch: Partial<TextLayerData>) => {
+    const id = idRef.current
+    if (!id) return
+    latest.current.dispatch({ type: 'layer/patchData', id, patch: patch as Record<string, unknown> })
+  }, [])
+
+  const setValue = useCallback(
+    (next: string) => {
+      const current = dataRef.current
+      if (!current) return
+      patchData({ spans: patchTextSpan(current, { text: next }).spans })
+    },
+    [patchData],
+  )
+
+  const styleSpan = useCallback(
+    (patch: Partial<TextSpan>) => {
+      const current = dataRef.current
+      if (!current) return
+      patchData({ spans: patchTextSpan(current, patch).spans })
+    },
+    [patchData],
+  )
+
+  const setSize = useCallback(
+    (size: number) => styleSpan({ fontSize: clampTextSize(size) }),
+    [styleSpan],
+  )
+
+  const commit = useCallback((): string | null => {
+    if (finished.current) return null
+    finished.current = true
+    const id = idRef.current
+    const blank = isBlankText(dataRef.current ? textValueOf(dataRef.current) : '')
+    // A blank draft is discarded by cancelling, not by removing and committing:
+    // `endBatch` compares opening and closing documents by identity, so
+    // add-then-remove still pushes an undo entry that appears to do nothing.
+    if (session.kind === 'draft' && blank) {
+      latest.current.dispatch({ type: 'history/cancelBatch' })
+      latest.current.select(priorSelection.current)
+      onFinished?.(null)
+      return null
+    }
+    latest.current.dispatch({ type: 'history/endBatch' })
+    onFinished?.(id ?? null)
+    return id ?? null
+  }, [session.kind, onFinished])
+
+  const cancel = useCallback(() => {
+    if (finished.current) return
+    finished.current = true
+    latest.current.dispatch({ type: 'history/cancelBatch' })
+    // Restore the whole editor state, not just the document: the session may
+    // have moved the selection to its draft.
+    latest.current.select(priorSelection.current)
+    onFinished?.(null)
+  }, [onFinished])
+
+  return useMemo(
+    () => ({
+      layer,
+      kind: session.kind,
+      value,
+      setValue,
+      span,
+      data,
+      styleSpan,
+      styleText: patchData,
+      setSize,
+      commit,
+      cancel,
+    }),
+    [layer, session.kind, value, setValue, span, data, styleSpan, patchData, setSize, commit, cancel],
+  )
+}

package/src/gestures/CropGestureSurface.tsx

@@ -0,0 +1,270 @@
+import {
+  clampCropTransform,
+  cropFitScale,
+  cropPanBounds,
+  focalZoomTransform,
+  type ImageLayerData,
+  type Transform,
+} from '@pictor-sdk/core'
+import { useCanvasMetrics } from '@pictor-sdk/skia'
+import React, { useEffect, useMemo, useRef } from 'react'
+import { StyleSheet } from 'react-native'
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, { useDerivedValue, useSharedValue, withTiming } from 'react-native-reanimated'
+import { runOnJS } from 'react-native-worklets'
+import { useTargetImageLayer } from '../panels/useTargetImageLayer'
+import { useEditor } from '@pictor-sdk/core'
+import { useInteractionState } from './interactionState'
+
+/** Overrides for crop gestures, defaulting to the profile's interaction settings. */
+export interface CropGestureSurfaceProps {
+  /** Override profile crop fit for this surface. */
+  fit?: 'contain' | 'cover'
+  maxScale?: number
+  /** Enable free two-finger rotation; disabled by the default Post profile. */
+  rotationEnabled?: boolean
+  /** Optional host haptic/motion callback. */
+  onInteractionChange?: (active: boolean) => void
+}
+
+/**
+ * Fixed-viewport photo crop gestures. Pan and focal-point pinch run as shared
+ * values on the UI thread; one normalized transform is committed on release.
+ */
+export function CropGestureSurface({ fit, maxScale, rotationEnabled, onInteractionChange }: CropGestureSurfaceProps) {
+  const { document, dispatch, profile } = useEditor()
+  const layer = useTargetImageLayer()
+  const metrics = useCanvasMetrics()
+  const interaction = useInteractionState()
+  const config = profile.interaction?.crop
+  const source = (layer?.data as ImageLayerData | undefined)?.intrinsic
+  const resolvedFit = fit ?? config?.fit ?? 'contain'
+  const resolvedMax = maxScale ?? config?.maxScale ?? 8
+  const resolvedRotation = rotationEnabled ?? config?.rotationEnabled ?? false
+
+  const liveX = useSharedValue(layer?.transform.x ?? 0.5)
+  const liveY = useSharedValue(layer?.transform.y ?? 0.5)
+  const liveScale = useSharedValue(layer?.transform.scale ?? 1)
+  // Seed from React state directly; reading shared values during render trips
+  // Reanimated strict mode on real devices.
+  const baseX = useSharedValue(layer?.transform.x ?? 0.5)
+  const baseY = useSharedValue(layer?.transform.y ?? 0.5)
+  const baseScale = useSharedValue(layer?.transform.scale ?? 1)
+  const liveRotation = useSharedValue(layer?.transform.rotation ?? 0)
+  const baseRotation = useSharedValue(layer?.transform.rotation ?? 0)
+  const panX = useSharedValue(0)
+  const panY = useSharedValue(0)
+  const pinchScale = useSharedValue(1)
+  const rotateDelta = useSharedValue(0)
+  const focalX = useSharedValue(0.5)
+  const focalY = useSharedValue(0.5)
+  const activeRecognizers = useSharedValue(0)
+  const commitTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const minScale = source
+    ? cropFitScale(source, document.size, resolvedFit, layer?.transform.rotation ?? 0)
+    : 1
+
+  useEffect(() => {
+    if (!layer) return
+    liveX.value = layer.transform.x
+    liveY.value = layer.transform.y
+    liveScale.value = layer.transform.scale
+    liveRotation.value = layer.transform.rotation
+  // Shared-value identities are stable; only committed scalar values resync them.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layer?.transform.x, layer?.transform.y, layer?.transform.scale, layer?.transform.rotation])
+
+  const previewTransform = useDerivedValue(() => {
+    const ratio = liveScale.value / Math.max(baseScale.value, 0.000001)
+    return [
+      { translateX: liveX.value * document.size.width },
+      { translateY: liveY.value * document.size.height },
+      { rotate: liveRotation.value - baseRotation.value },
+      { scale: ratio },
+      { translateX: -baseX.value * document.size.width },
+      { translateY: -baseY.value * document.size.height },
+    ]
+  }, [document.size.width, document.size.height])
+
+  useEffect(() => {
+    if (!layer) return
+    interaction.setPreview({ layerId: layer.id, transform: previewTransform })
+    return () => interaction.setPreview(null)
+  // Register by layer identity; crop-active context changes must not replace it.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layer?.id, previewTransform, interaction.setPreview])
+
+  const setActive = (active: boolean) => {
+    interaction.setCropActive(active)
+    onInteractionChange?.(active)
+  }
+
+  const commit = (candidate: Transform) => {
+    if (!layer || !source) return
+    if (commitTimer.current) clearTimeout(commitTimer.current)
+    const settledMinScale = cropFitScale(source, document.size, resolvedFit, candidate.rotation)
+    const bounds = cropPanBounds(source, document.size, candidate.scale, settledMinScale, resolvedMax, candidate.rotation)
+    const settled = clampCropTransform(candidate, bounds)
+    liveX.value = withTiming(settled.x, { duration: 160 })
+    liveY.value = withTiming(settled.y, { duration: 160 })
+    liveScale.value = withTiming(settled.scale, { duration: 160 })
+    liveRotation.value = withTiming(settled.rotation, { duration: 160 })
+    commitTimer.current = setTimeout(() => {
+      dispatch({
+        type: 'layer/transform',
+        id: layer.id,
+        patch: {
+          x: settled.x,
+          y: settled.y,
+          scale: settled.scale,
+          ...(resolvedRotation ? { rotation: settled.rotation } : {}),
+        },
+      })
+      baseX.value = settled.x
+      baseY.value = settled.y
+      baseScale.value = settled.scale
+      baseRotation.value = settled.rotation
+      liveX.value = settled.x
+      liveY.value = settled.y
+      liveScale.value = settled.scale
+      liveRotation.value = settled.rotation
+      setActive(false)
+    }, 165)
+  }
+
+  const toggleZoom = (xDp: number, yDp: number) => {
+    if (!layer || !source || !metrics) return
+    baseX.value = layer.transform.x
+    baseY.value = layer.transform.y
+    baseScale.value = layer.transform.scale
+    baseRotation.value = layer.transform.rotation
+    liveX.value = layer.transform.x
+    liveY.value = layer.transform.y
+    liveScale.value = layer.transform.scale
+    liveRotation.value = layer.transform.rotation
+    setActive(true)
+    const atMinimum = Math.abs(layer.transform.scale - minScale) < 0.01
+    const targetScale = atMinimum
+      ? Math.min(resolvedMax, minScale * (config?.doubleTapScale ?? 2))
+      : minScale
+    commit(focalZoomTransform(layer.transform, targetScale, {
+      x: xDp / metrics.width,
+      y: yDp / metrics.height,
+    }))
+  }
+
+  const gesture = useMemo(() => {
+    if (!metrics || !source || !layer) return Gesture.Tap()
+    const begin = () => {
+      'worklet'
+      if (activeRecognizers.value === 0) {
+        baseX.value = liveX.value
+        baseY.value = liveY.value
+        baseScale.value = liveScale.value
+        baseRotation.value = liveRotation.value
+        panX.value = 0
+        panY.value = 0
+        pinchScale.value = 1
+        rotateDelta.value = 0
+        runOnJS(setActive)(true)
+      }
+      activeRecognizers.value += 1
+    }
+    const updateLive = () => {
+      'worklet'
+      const rotation = baseRotation.value + rotateDelta.value
+      const naturalWidth = document.size.width
+      const naturalHeight = document.size.width * (source.height / source.width)
+      const cos = Math.abs(Math.cos(rotation))
+      const sin = Math.abs(Math.sin(rotation))
+      const rotatedWidth = naturalWidth * cos + naturalHeight * sin
+      const rotatedHeight = naturalWidth * sin + naturalHeight * cos
+      const widthScale = document.size.width / rotatedWidth
+      const heightScale = document.size.height / rotatedHeight
+      const dynamicMin = resolvedFit === 'contain' ? Math.min(widthScale, heightScale) : Math.max(widthScale, heightScale)
+      const rawScale = baseScale.value * pinchScale.value
+      const resistance = config?.resistance ?? 0.35
+      const scale = rawScale < dynamicMin
+        ? dynamicMin - (dynamicMin - rawScale) * resistance
+        : rawScale > resolvedMax
+          ? resolvedMax + (rawScale - resolvedMax) * resistance
+          : rawScale
+      const ratio = scale / Math.max(baseScale.value, 0.000001)
+      const zoomX = focalX.value - (focalX.value - baseX.value) * ratio
+      const zoomY = focalY.value - (focalY.value - baseY.value) * ratio
+      liveRotation.value = rotation
+      const dx = Math.max(0, (rotatedWidth * scale - document.size.width) / (2 * document.size.width))
+      const dy = Math.max(0, (rotatedHeight * scale - document.size.height) / (2 * document.size.height))
+      liveScale.value = scale
+      const rawX = zoomX + panX.value
+      const rawY = zoomY + panY.value
+      const minX = 0.5 - dx
+      const maxX = 0.5 + dx
+      const minY = 0.5 - dy
+      const maxY = 0.5 + dy
+      liveX.value = rawX < minX ? minX - (minX - rawX) * resistance : rawX > maxX ? maxX + (rawX - maxX) * resistance : rawX
+      liveY.value = rawY < minY ? minY - (minY - rawY) * resistance : rawY > maxY ? maxY + (rawY - maxY) * resistance : rawY
+    }
+    const finish = () => {
+      'worklet'
+      activeRecognizers.value = Math.max(0, activeRecognizers.value - 1)
+      if (activeRecognizers.value === 0) {
+        runOnJS(commit)({
+          x: liveX.value,
+          y: liveY.value,
+          scale: liveScale.value,
+          rotation: liveRotation.value,
+          ...(layer.transform.anchor ? { anchor: layer.transform.anchor } : {}),
+          ...(layer.transform.flipX !== undefined ? { flipX: layer.transform.flipX } : {}),
+          ...(layer.transform.flipY !== undefined ? { flipY: layer.transform.flipY } : {}),
+        })
+      }
+    }
+    const pan = Gesture.Pan()
+      .minPointers(1)
+      .onStart(begin)
+      .onUpdate((event) => {
+        'worklet'
+        panX.value = event.translationX / metrics.width
+        panY.value = event.translationY / metrics.height
+        updateLive()
+      })
+      .onFinalize(finish)
+    const pinch = Gesture.Pinch()
+      .onStart(begin)
+      .onUpdate((event) => {
+        'worklet'
+        pinchScale.value = event.scale
+        focalX.value = event.focalX / metrics.width
+        focalY.value = event.focalY / metrics.height
+        updateLive()
+      })
+      .onFinalize(finish)
+    const rotate = Gesture.Rotation()
+      .enabled(resolvedRotation)
+      .onStart(begin)
+      .onUpdate((event) => {
+        'worklet'
+        rotateDelta.value = event.rotation
+        updateLive()
+      })
+      .onFinalize(finish)
+    const doubleTap = Gesture.Tap()
+      .numberOfTaps(2)
+      .onEnd((event) => {
+        'worklet'
+        runOnJS(toggleZoom)(event.x, event.y)
+      })
+    return Gesture.Exclusive(doubleTap, Gesture.Simultaneous(pan, pinch, rotate))
+  // Gesture worklets read stable shared values; recreate only for geometry/config changes.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [metrics, source, layer, resolvedFit, resolvedMax, resolvedRotation, minScale, document.size.width, document.size.height, config?.resistance, config?.doubleTapScale])
+
+  if (!layer) return null
+  return (
+    <GestureDetector gesture={gesture}>
+      <Animated.View style={StyleSheet.absoluteFill} />
+    </GestureDetector>
+  )
+}

package/src/gestures/CropGrid.tsx

@@ -0,0 +1,24 @@
+import React from 'react'
+import { StyleSheet, View } from 'react-native'
+import { useInteractionState } from './interactionState'
+
+/** Rule-of-thirds overlay shown only while crop interaction is active. */
+export function CropGrid({ always = false }: { always?: boolean }) {
+  const { cropActive } = useInteractionState()
+  if (!always && !cropActive) return null
+  return (
+    <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+      {[1 / 3, 2 / 3].map((fraction) => (
+        <React.Fragment key={fraction}>
+          <View style={[styles.vertical, { left: `${fraction * 100}%` }]} />
+          <View style={[styles.horizontal, { top: `${fraction * 100}%` }]} />
+        </React.Fragment>
+      ))}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  vertical: { position: 'absolute', top: 0, bottom: 0, width: 1, backgroundColor: '#ffffff88' },
+  horizontal: { position: 'absolute', left: 0, right: 0, height: 1, backgroundColor: '#ffffff88' },
+})