@pictor-sdk/ui 0.1.0

package/src/gestures/controller.ts

@@ -0,0 +1,152 @@
+import {
+  hitTestDocument,
+  snapCenter,
+  snapRotation,
+  type EditorStore,
+  type Transform,
+} from '@pictor-sdk/core'
+
+/** The fitted canvas's size in dp, for turning touches into document units. */
+export interface GestureMetrics {
+  /** canvas size in dp (the fitted preview) */
+  width: number
+  height: number
+}
+
+/** Emitted the moment a gesture snaps — the hook for haptics. */
+export interface GestureSnapEvent {
+  kind: 'rotation' | 'centerX' | 'centerY'
+}
+
+/**
+ * Host callbacks a gesture controller may fire.
+ *
+ * Callbacks rather than behaviour: haptics would mean a native dependency, so
+ * the library reports the moment and the host decides what it means.
+ */
+export interface GestureControllerOptions {
+  /** e.g. trigger haptics — optional callback, no haptics dependency here. */
+  onSnap?: (event: GestureSnapEvent) => void
+}
+
+/**
+ * Pure gesture → command translation, shared by the RN gesture wiring and
+ * unit tests. Pan/pinch/rotate report cumulative deltas; the controller
+ * recomputes the transform from the base captured at gesture start and
+ * commits through a history batch so the whole gesture is ONE undo step.
+ *
+ * DECISION: shared values give 60fps feedback on the UI thread; document
+ * commits hop to JS per frame (cheap — one reducer pass at preview scale)
+ * inside the batch. True UI-thread document mutation would need a worklet
+ * store and is out of scope for v0.1.
+ */
+export function createGestureController(
+  store: Pick<EditorStore, 'getState' | 'dispatch' | 'select' | 'registry'>,
+  getMetrics: () => GestureMetrics | null,
+  options: GestureControllerOptions = {},
+) {
+  let active = 0
+  let base: Transform | null = null
+  let layerId: string | null = null
+  let pan = { x: 0, y: 0 }
+  let pinch = 1
+  let rotate = 0
+  const snapState = { rotation: false, centerX: false, centerY: false }
+
+  function targetLayerId(): string | null {
+    return store.getState().selection[0] ?? null
+  }
+
+  function begin() {
+    if (active === 0) {
+      layerId = targetLayerId()
+      if (!layerId) return
+      const layer = store.getState().document.layers.find((l) => l.id === layerId)
+      if (!layer || layer.locked) {
+        layerId = null
+        return
+      }
+      base = { ...layer.transform }
+      pan = { x: 0, y: 0 }
+      pinch = 1
+      rotate = 0
+      snapState.rotation = snapState.centerX = snapState.centerY = false
+      store.dispatch({ type: 'history/beginBatch', label: 'gesture' })
+    }
+    active++
+  }
+
+  function fireSnap(kind: GestureSnapEvent['kind'], snapped: boolean) {
+    if (snapped && !snapState[kind]) options.onSnap?.({ kind })
+    snapState[kind] = snapped
+  }
+
+  function commit() {
+    if (!base || !layerId) return
+    const metrics = getMetrics()
+    if (!metrics || metrics.width === 0 || metrics.height === 0) return
+
+    const rawX = base.x + pan.x / metrics.width
+    const rawY = base.y + pan.y / metrics.height
+    const rawRotation = base.rotation + rotate
+
+    const sx = snapCenter(rawX)
+    const sy = snapCenter(rawY)
+    const sr = snapRotation(rawRotation)
+    fireSnap('centerX', sx.snapped)
+    fireSnap('centerY', sy.snapped)
+    fireSnap('rotation', sr.snapped)
+
+    store.dispatch({
+      type: 'layer/transform',
+      id: layerId,
+      patch: {
+        x: sx.value,
+        y: sy.value,
+        rotation: sr.value,
+        scale: Math.max(0.01, base.scale * pinch),
+      },
+    })
+  }
+
+  function end() {
+    if (active === 0) return
+    active--
+    if (active === 0) {
+      if (layerId) store.dispatch({ type: 'history/endBatch' })
+      base = null
+      layerId = null
+    }
+  }
+
+  return {
+    /** Pan/pinch/rotate lifecycles — call begin/end once per recognizer. */
+    begin,
+    end,
+    setPan(xDp: number, yDp: number) {
+      pan = { x: xDp, y: yDp }
+      commit()
+    },
+    setPinch(scale: number) {
+      pinch = scale
+      commit()
+    },
+    setRotate(rad: number) {
+      rotate = rad
+      commit()
+    },
+    /** Tap in canvas dp → hit-test → select (empty tap clears selection). */
+    tap(xDp: number, yDp: number) {
+      const metrics = getMetrics()
+      if (!metrics) return
+      const point = { x: xDp / metrics.width, y: yDp / metrics.height }
+      const hit = hitTestDocument(store.getState().document, point, store.registry)
+      store.select(hit ? [hit.id] : [])
+    },
+    /** true while a gesture is in flight (used to mute other UI). */
+    isActive: () => active > 0,
+  }
+}
+
+/** Turns raw gesture input into layer transforms, with snapping. */
+export type GestureController = ReturnType<typeof createGestureController>

package/src/gestures/drawController.ts

@@ -0,0 +1,104 @@
+import { createId, type EditorStore, type Stroke } from '@pictor-sdk/core'
+import { type GestureMetrics } from './controller'
+
+/** The active brush: kind, colour and width. Width is a fraction of document width. */
+export interface BrushConfig {
+  brush: Stroke['brush']
+  color: string
+  /** 0..1 of document width */
+  width: number
+}
+
+/**
+ * Pure drawing controller: converts a pan gesture into a stroke on the
+ * top-most draw layer (created on first use), committed as ONE undo step.
+ * Live feedback comes from patching the stroke into the document on every
+ * move inside the history batch.
+ */
+export function createDrawController(
+  store: Pick<EditorStore, 'getState' | 'dispatch'>,
+  getMetrics: () => GestureMetrics | null,
+  getBrush: () => BrushConfig,
+) {
+  let drawing = false
+  let layerId: string | null = null
+  let points: Stroke['points'] = []
+  let baseStrokes: Stroke[] = []
+
+  function toDocPoint(xDp: number, yDp: number) {
+    const metrics = getMetrics()
+    if (!metrics || metrics.width === 0 || metrics.height === 0) return null
+    return { x: xDp / metrics.width, y: yDp / metrics.height }
+  }
+
+  function ensureDrawLayer(): string {
+    const doc = store.getState().document
+    for (let i = doc.layers.length - 1; i >= 0; i--) {
+      const layer = doc.layers[i]!
+      if (layer.type === 'draw' && !layer.locked && !layer.hidden) return layer.id
+    }
+    const id = createId('draw')
+    store.dispatch({
+      type: 'layer/add',
+      layer: {
+        id,
+        type: 'draw',
+        transform: { x: 0.5, y: 0.5, scale: 1, rotation: 0 },
+        opacity: 1,
+        blendMode: 'normal',
+        data: { strokes: [] },
+      },
+    })
+    return id
+  }
+
+  function currentStroke(): Stroke {
+    const brush = getBrush()
+    return { points, color: brush.color, width: brush.width, brush: brush.brush }
+  }
+
+  function patch() {
+    if (!layerId) return
+    store.dispatch({
+      type: 'layer/patchData',
+      id: layerId,
+      patch: { strokes: [...baseStrokes, currentStroke()] },
+    })
+  }
+
+  return {
+    begin(xDp: number, yDp: number) {
+      const point = toDocPoint(xDp, yDp)
+      if (!point || drawing) return
+      drawing = true
+      store.dispatch({ type: 'history/beginBatch', label: 'draw' })
+      layerId = ensureDrawLayer()
+      const layer = store.getState().document.layers.find((l) => l.id === layerId)
+      baseStrokes = (layer?.data as { strokes?: Stroke[] } | undefined)?.strokes ?? []
+      points = [point]
+      patch()
+    },
+    move(xDp: number, yDp: number) {
+      if (!drawing) return
+      const point = toDocPoint(xDp, yDp)
+      if (!point) return
+      const last = points[points.length - 1]
+      // drop sub-half-percent movements to keep strokes light
+      if (last && Math.hypot(point.x - last.x, point.y - last.y) < 0.003) return
+      points = [...points, point]
+      patch()
+    },
+    end() {
+      if (!drawing) return
+      drawing = false
+      store.dispatch({ type: 'history/endBatch' })
+      layerId = null
+      points = []
+      baseStrokes = []
+    },
+    isDrawing: () => drawing,
+  }
+}
+
+/** Accumulates touch points into strokes and commits them to the document. */
+export type DrawController = ReturnType<typeof createDrawController>

package/src/gestures/interactionState.tsx

@@ -0,0 +1,81 @@
+import { NO_SNAP, type LayerSnapState } from '@pictor-sdk/core'
+import { type PreviewLayerTransform } from '@pictor-sdk/skia'
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react'
+
+/**
+ * Transient interaction state shared between the gesture surfaces and the
+ * chrome. None of it is part of the document: it never reaches history,
+ * serialization or export.
+ *
+ * Per-frame transforms stay on the UI thread as shared values (`previews`).
+ * Only the discrete flags below cross to the JS thread, and only when they
+ * actually change — a drag starting, a guide engaging, the delete target being
+ * entered — so the render path is untouched while fingers move.
+ */
+export interface InteractionState {
+  previews: readonly PreviewLayerTransform[]
+  setPreview(preview: PreviewLayerTransform | null): void
+  cropActive: boolean
+  setCropActive(active: boolean): void
+  /** True while a layer is being dragged/scaled/rotated. */
+  layerDragActive: boolean
+  setLayerDragActive(active: boolean): void
+  /** True while the dragged layer is over the delete target. */
+  overDeleteTarget: boolean
+  setOverDeleteTarget(over: boolean): void
+  /** Which alignment guides are currently engaged. */
+  snap: LayerSnapState
+  setSnap(snap: LayerSnapState): void
+}
+
+const Context = createContext<InteractionState | null>(null)
+
+/**
+ * Shares the in-flight interaction between the gesture surfaces and the canvas.
+ *
+ * How a live preview transform reaches the renderer without going through the
+ * document — which would mean dispatching every frame.
+ */
+export function InteractionProvider({ children }: { children?: React.ReactNode }) {
+  const [preview, setPreviewValue] = useState<PreviewLayerTransform | null>(null)
+  const [cropActive, setCropActive] = useState(false)
+  const [layerDragActive, setLayerDragActive] = useState(false)
+  const [overDeleteTarget, setOverDeleteTarget] = useState(false)
+  const [snap, setSnapValue] = useState<LayerSnapState>(NO_SNAP)
+
+  const setPreview = useCallback((value: PreviewLayerTransform | null) => setPreviewValue(value), [])
+  // identity-stable so worklets can call it through runOnJS without re-creating
+  const setSnap = useCallback((value: LayerSnapState) => {
+    setSnapValue((current) =>
+      current.centerX === value.centerX &&
+      current.centerY === value.centerY &&
+      current.rotation === value.rotation
+        ? current
+        : value,
+    )
+  }, [])
+
+  const value = useMemo(
+    () => ({
+      previews: preview ? [preview] : [],
+      setPreview,
+      cropActive,
+      setCropActive,
+      layerDragActive,
+      setLayerDragActive,
+      overDeleteTarget,
+      setOverDeleteTarget,
+      snap,
+      setSnap,
+    }),
+    [preview, setPreview, cropActive, layerDragActive, overDeleteTarget, snap, setSnap],
+  )
+  return <Context.Provider value={value}>{children}</Context.Provider>
+}
+
+/** The current interaction. Throws outside an `<Editor>`, where there is none. */
+export function useInteractionState(): InteractionState {
+  const value = useContext(Context)
+  if (!value) throw new Error('interaction components must be used inside <Editor>')
+  return value
+}

package/src/gestures/layerGestureWorklet.ts

@@ -0,0 +1,198 @@
+import { type ResolvedLayerGestureConfig } from '@pictor-sdk/core'
+
+/**
+ * UI-thread twin of `composeLayerGesture` from @pictor-sdk/core.
+ *
+ * DECISION: the gesture math exists twice on purpose. @pictor-sdk/core must stay
+ * free of Reanimated (invariant 5) and must run in plain Node, so it cannot
+ * carry a `'worklet'` directive; but the preview has to recompute the
+ * transform on the UI thread every frame, which requires a worklet. Rather
+ * than rely on the consumer's Babel config workletizing another package's
+ * source, the worklet lives here — and `worklet-parity.test.ts` asserts the
+ * two implementations agree across a grid of inputs, so they cannot drift.
+ *
+ * Keep this function free of imports and closures over anything but plain
+ * numbers and frozen config objects.
+ */
+export interface WorkletTransform {
+  x: number
+  y: number
+  scale: number
+  rotation: number
+  snapCenterX: boolean
+  snapCenterY: boolean
+  snapRotation: boolean
+}
+
+export interface WorkletBase {
+  x: number
+  y: number
+  scale: number
+  rotation: number
+}
+
+export interface WorkletInput {
+  panX: number
+  panY: number
+  pinch: number
+  rotate: number
+  focalX: number
+  focalY: number
+}
+
+export interface WorkletPrevSnap {
+  centerX: boolean
+  centerY: boolean
+  rotation: boolean
+}
+
+export function composeLayerGestureUI(
+  base: WorkletBase,
+  input: WorkletInput,
+  aspect: number,
+  config: ResolvedLayerGestureConfig,
+  previous: WorkletPrevSnap,
+  settle: boolean,
+): WorkletTransform {
+  'worklet'
+  const requested = base.scale * input.pinch
+  let scale: number
+  if (settle) {
+    scale = Math.min(config.maxScale, Math.max(config.minScale, requested))
+  } else if (requested < config.minScale) {
+    scale = config.minScale - (config.minScale - requested) * config.scaleResistance
+  } else if (requested > config.maxScale) {
+    scale = config.maxScale + (requested - config.maxScale) * config.scaleResistance
+  } else {
+    scale = requested
+  }
+
+  const ratio = scale / Math.max(base.scale, 1e-9)
+  const rotationDelta = config.rotationEnabled ? input.rotate : 0
+
+  const dx = base.x - input.focalX
+  const dy = (base.y - input.focalY) * aspect
+  const cos = Math.cos(rotationDelta)
+  const sin = Math.sin(rotationDelta)
+  const rx = (dx * cos - dy * sin) * ratio
+  const ry = (dx * sin + dy * cos) * ratio
+
+  let x = input.focalX + rx + input.panX
+  let y = input.focalY + ry / aspect + input.panY
+  let rotation = base.rotation + rotationDelta
+
+  let snapCenterX = false
+  let snapCenterY = false
+  let snapRotation = false
+
+  if (config.centerSnap !== false) {
+    const engage = config.centerSnap
+    const release = Math.max(engage, config.centerSnapRelease)
+    const tx = previous.centerX ? release : engage
+    if (Math.abs(x - 0.5) <= tx + 1e-9) {
+      x = 0.5
+      snapCenterX = true
+    }
+    const ty = previous.centerY ? release : engage
+    if (Math.abs(y - 0.5) <= ty + 1e-9) {
+      y = 0.5
+      snapCenterY = true
+    }
+  }
+
+  if (config.rotationSnap !== false && config.rotationEnabled) {
+    const engage = config.rotationSnap
+    const release = Math.max(engage, config.rotationSnapRelease)
+    const step = Math.PI / 2
+    const nearest = Math.round(rotation / step) * step
+    const tr = previous.rotation ? release : engage
+    if (Math.abs(rotation - nearest) <= tr + 1e-9) {
+      rotation = nearest
+      snapRotation = true
+    }
+  }
+
+  return { x, y, scale, rotation, snapCenterX, snapCenterY, snapRotation }
+}
+
+/**
+ * UI-thread twin of `isOverDeleteTarget`.
+ *
+ * Same reason as above: a worklet may only call other worklets, and
+ * @pictor-sdk/core cannot carry the directive. Held to core by the parity test.
+ */
+export function isOverDeleteTargetUI(
+  x: number,
+  y: number,
+  target: { x: number; y: number; radius: number },
+  aspect: number,
+): boolean {
+  'worklet'
+  const dx = x - target.x
+  const dy = (y - target.y) * aspect
+  return Math.sqrt(dx * dx + dy * dy) <= target.radius
+}
+
+/**
+ * Renderer delta from the immutable committed transform to the live transform.
+ * Pointer-frame rebasing must never change these reference values.
+ */
+export function layerPreviewDeltaUI(
+  committed: { x: number; y: number; scale: number; rotation: number },
+  live: { x: number; y: number; scale: number; rotation: number },
+  width: number,
+  height: number,
+) {
+  'worklet'
+  return [
+    { translateX: live.x * width },
+    { translateY: live.y * height },
+    { rotate: live.rotation - committed.rotation },
+    { scale: live.scale / Math.max(committed.scale, 1e-9) },
+    { translateX: -committed.x * width },
+    { translateY: -committed.y * height },
+  ]
+}
+
+export interface LayerHitCandidateUI {
+  id: string
+  x: number
+  y: number
+  scale: number
+  rotation: number
+  width: number
+  height: number
+  anchorX: number
+  anchorY: number
+  flipX: boolean
+  flipY: boolean
+}
+
+/** Top-most bounding-box hit test used to activate built-in overlays instantly. */
+export function hitTestLayerCandidatesUI(
+  x: number,
+  y: number,
+  candidates: readonly LayerHitCandidateUI[],
+  documentWidth: number,
+  documentHeight: number,
+): LayerHitCandidateUI | null {
+  'worklet'
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i]!
+    let dx = x * documentWidth - candidate.x * documentWidth
+    let dy = y * documentHeight - candidate.y * documentHeight
+    const cos = Math.cos(-candidate.rotation)
+    const sin = Math.sin(-candidate.rotation)
+    const rx = dx * cos - dy * sin
+    const ry = dx * sin + dy * cos
+    dx = candidate.flipX ? -rx : rx
+    dy = candidate.flipY ? -ry : ry
+    const width = candidate.scale * candidate.width * documentWidth
+    const height = candidate.scale * candidate.height * documentWidth
+    if (width <= 0 || height <= 0) continue
+    const localX = dx / width + candidate.anchorX
+    const localY = dy / height + candidate.anchorY
+    if (localX >= 0 && localX <= 1 && localY >= 0 && localY <= 1) return candidate
+  }
+  return null
+}

package/src/gestures/mediaGestureWorklet.ts

@@ -0,0 +1,159 @@
+import { type ResolvedMediaConfig } from '@pictor-sdk/core'
+
+/**
+ * UI-thread twin of `composeMediaGesture` from @pictor-sdk/core.
+ *
+ * DECISION: the same deliberate duplication as `layerGestureWorklet`. Core must
+ * stay free of Reanimated and must run in plain Node, so it cannot carry a
+ * `'worklet'` directive; but the preview recomputes the transform every frame
+ * on the UI thread, which requires one. `media-worklet-parity.test.ts` holds
+ * the two implementations together across a grid of inputs, so they cannot
+ * drift.
+ *
+ * Keep this file free of imports beyond types, and of closures over anything
+ * but plain numbers and frozen config objects.
+ */
+export interface MediaWorkletTransform {
+  x: number
+  y: number
+  scale: number
+  rotation: number
+}
+
+export interface MediaWorkletInput {
+  panX: number
+  panY: number
+  pinch: number
+  rotate: number
+  focalX: number
+  focalY: number
+}
+
+export interface MediaWorkletSize {
+  width: number
+  height: number
+}
+
+/** Mirror of core's `mediaFitScale`. */
+export function mediaFitScaleUI(
+  intrinsic: MediaWorkletSize,
+  canvas: MediaWorkletSize,
+  fit: 'width' | 'cover' | 'contain',
+  rotation: number,
+): number {
+  'worklet'
+  if (intrinsic.width <= 0 || intrinsic.height <= 0) return 1
+  if (fit === 'width') return 1
+  const w = canvas.width
+  const h = canvas.width * (intrinsic.height / intrinsic.width)
+  const cos = Math.abs(Math.cos(rotation))
+  const sin = Math.abs(Math.sin(rotation))
+  const byWidth = canvas.width / (w * cos + h * sin)
+  const byHeight = canvas.height / (w * sin + h * cos)
+  return fit === 'cover' ? Math.max(byWidth, byHeight) : Math.min(byWidth, byHeight)
+}
+
+/** Mirror of core's `mediaPanBounds`. */
+export function mediaPanBoundsUI(
+  _intrinsic: MediaWorkletSize,
+  _canvas: MediaWorkletSize,
+  _scale: number,
+  _rotation: number,
+): { minX: number; maxX: number; minY: number; maxY: number } {
+  'worklet'
+  // Mirror of core's `mediaPanBounds`: the media is freely positionable, held
+  // only so its anchor stays on the canvas and it can always be dragged back.
+  return { minX: 0, maxX: 1, minY: 0, maxY: 1 }
+}
+
+/** Mirror of core's `composeMediaGesture`. */
+export function composeMediaGestureUI(
+  base: MediaWorkletTransform,
+  input: MediaWorkletInput,
+  canvas: MediaWorkletSize,
+  intrinsic: MediaWorkletSize,
+  config: ResolvedMediaConfig,
+  settle: boolean,
+): MediaWorkletTransform {
+  'worklet'
+  const rotationDelta = config.rotationEnabled ? input.rotate : 0
+  const rotation = base.rotation + rotationDelta
+
+  const fit = mediaFitScaleUI(intrinsic, canvas, config.fit, rotation)
+  const minScale = fit * config.minScaleFactor
+  const maxScale = Math.max(minScale, config.maxScale)
+
+  const requested = base.scale * input.pinch
+  let scale: number
+  if (settle) {
+    scale = Math.min(maxScale, Math.max(minScale, requested))
+  } else if (requested < minScale) {
+    scale = minScale - (minScale - requested) * config.resistance
+  } else if (requested > maxScale) {
+    scale = maxScale + (requested - maxScale) * config.resistance
+  } else {
+    scale = requested
+  }
+
+  const aspect = canvas.height / canvas.width
+  const ratio = scale / Math.max(base.scale, 1e-9)
+  const dx = base.x - input.focalX
+  const dy = (base.y - input.focalY) * aspect
+  const cos = Math.cos(rotationDelta)
+  const sin = Math.sin(rotationDelta)
+  const rx = (dx * cos - dy * sin) * ratio
+  const ry = (dx * sin + dy * cos) * ratio
+
+  const rawX = input.focalX + rx + input.panX
+  const rawY = input.focalY + ry / aspect + input.panY
+
+  const bounds = mediaPanBoundsUI(intrinsic, canvas, scale, rotation)
+  let x: number
+  let y: number
+  if (settle) {
+    x = Math.min(bounds.maxX, Math.max(bounds.minX, rawX))
+    y = Math.min(bounds.maxY, Math.max(bounds.minY, rawY))
+  } else {
+    x =
+      rawX < bounds.minX
+        ? bounds.minX - (bounds.minX - rawX) * config.resistance
+        : rawX > bounds.maxX
+          ? bounds.maxX + (rawX - bounds.maxX) * config.resistance
+          : rawX
+    y =
+      rawY < bounds.minY
+        ? bounds.minY - (bounds.minY - rawY) * config.resistance
+        : rawY > bounds.maxY
+          ? bounds.maxY + (rawY - bounds.maxY) * config.resistance
+          : rawY
+  }
+
+  return { x, y, scale, rotation }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Recognizer lifecycle
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Pan, pinch and rotation run simultaneously, and each finalises on its own.
+ * Lifting one finger of a two-finger gesture finalises pinch and rotation while
+ * the pan recognizer keeps running with the remaining finger — so an
+ * interaction must only be considered over once *every* recognizer has
+ * finalised. Counting them is what makes two-fingers-to-one continuous instead
+ * of ending the gesture early.
+ *
+ * Pure and worklet-safe so the surface and its tests share one definition.
+ */
+export function onRecognizerBegin(count: number): { count: number; isFirst: boolean } {
+  'worklet'
+  const next = Math.max(0, count) + 1
+  return { count: next, isFirst: next === 1 }
+}
+
+/** Returns `isLast` only when this was the final live recognizer. */
+export function onRecognizerEnd(count: number): { count: number; isLast: boolean } {
+  'worklet'
+  const next = Math.max(0, count - 1)
+  return { count: next, isLast: next === 0 && count > 0 }
+}