[feat/MAT-363] Zoom/Pan 인프라

packages/pointer-native-drawing/src/canvas/useCanvasGestureComposer.ts

@@ -0,0 +1,168 @@
+import { useMemo } from 'react';
+import { Gesture, type GestureType } from 'react-native-gesture-handler';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+
+import { type ViewTransform, IDENTITY_TRANSFORM, clampTransform } from '../transform';
+
+export type UseCanvasGestureComposerArgs = {
+  enableZoomPan: boolean;
+  maxZoomScale: number;
+  nativeFingerInput?: boolean;
+  viewTransform: SharedValue<ViewTransform>;
+  viewportWidthShared: SharedValue<number>;
+  viewportHeightShared: SharedValue<number>;
+  canvasHeightShared: SharedValue<number>;
+  drawPanGesture: GestureType;
+};
+
+export function useCanvasGestureComposer({
+  enableZoomPan,
+  maxZoomScale,
+  nativeFingerInput = false,
+  viewTransform,
+  viewportWidthShared,
+  viewportHeightShared,
+  canvasHeightShared,
+  drawPanGesture,
+}: UseCanvasGestureComposerArgs) {
+  // gesture 간 협업용 SharedValues
+  const pinchDeadShared = useSharedValue(false);
+  const pinchActiveShared = useSharedValue(false);
+
+  // base/anchor SharedValue — pinch start 시점의 transform / focal anchor 저장
+  const baseTransformShared = useSharedValue<ViewTransform>(IDENTITY_TRANSFORM);
+  const anchorXShared = useSharedValue(0);
+  const anchorYShared = useSharedValue(0);
+
+  const fingerPanBaseShared = useSharedValue<ViewTransform>(IDENTITY_TRANSFORM);
+  const fingerPanActiveShared = useSharedValue(false);
+
+  const pinchGesture = useMemo(
+    () =>
+      Gesture.Pinch()
+        .onStart((e) => {
+          'worklet';
+          pinchDeadShared.value = false;
+          pinchActiveShared.value = true;
+          const current = viewTransform.value;
+          baseTransformShared.value = current;
+          const s = current.scale || 1;
+          anchorXShared.value = (e.focalX - current.translateX) / s;
+          anchorYShared.value = (e.focalY - current.translateY) / s;
+        })
+        .onUpdate((e) => {
+          'worklet';
+          if (e.numberOfPointers < 2) {
+            pinchDeadShared.value = true;
+            return;
+          }
+          if (pinchDeadShared.value) return;
+
+          const base = baseTransformShared.value;
+          const newScale = Math.min(Math.max(base.scale * e.scale, 1), maxZoomScale);
+          const next: ViewTransform = {
+            scale: newScale,
+            translateX: e.focalX - newScale * anchorXShared.value,
+            translateY: e.focalY - newScale * anchorYShared.value,
+          };
+          viewTransform.value = clampTransform(
+            next,
+            viewportWidthShared.value,
+            canvasHeightShared.value,
+            viewportWidthShared.value,
+            viewportHeightShared.value,
+            maxZoomScale
+          );
+        })
+        .onEnd(() => {
+          'worklet';
+          pinchActiveShared.value = false;
+          // 마지막 clamp 한 번 더 (boundary 보정)
+          viewTransform.value = clampTransform(
+            viewTransform.value,
+            viewportWidthShared.value,
+            canvasHeightShared.value,
+            viewportWidthShared.value,
+            viewportHeightShared.value,
+            maxZoomScale
+          );
+        })
+        .onFinalize(() => {
+          'worklet';
+          pinchActiveShared.value = false;
+        }),
+    [
+      viewTransform,
+      viewportWidthShared,
+      viewportHeightShared,
+      canvasHeightShared,
+      pinchDeadShared,
+      pinchActiveShared,
+      baseTransformShared,
+      anchorXShared,
+      anchorYShared,
+      maxZoomScale,
+    ]
+  );
+
+  const fingerPanGesture = useMemo(
+    () =>
+      Gesture.Pan()
+        .minPointers(2)
+        .maxPointers(2)
+        .minDistance(1)
+        .onStart(() => {
+          'worklet';
+          if (pinchActiveShared.value) return;
+          fingerPanActiveShared.value = true;
+          fingerPanBaseShared.value = viewTransform.value;
+        })
+        .onUpdate((e) => {
+          'worklet';
+          if (pinchActiveShared.value) return;
+          if (!fingerPanActiveShared.value) return;
+          const base = fingerPanBaseShared.value;
+          const next: ViewTransform = {
+            scale: base.scale,
+            translateX: base.translateX + e.translationX,
+            translateY: base.translateY + e.translationY,
+          };
+          viewTransform.value = clampTransform(
+            next,
+            viewportWidthShared.value,
+            canvasHeightShared.value,
+            viewportWidthShared.value,
+            viewportHeightShared.value,
+            maxZoomScale
+          );
+        })
+        .onFinalize(() => {
+          'worklet';
+          fingerPanActiveShared.value = false;
+        }),
+    [
+      viewTransform,
+      viewportWidthShared,
+      viewportHeightShared,
+      canvasHeightShared,
+      pinchActiveShared,
+      fingerPanActiveShared,
+      fingerPanBaseShared,
+      maxZoomScale,
+    ]
+  );
+
+  const composedGesture = useMemo(() => {
+    if (!enableZoomPan) {
+      return drawPanGesture;
+    }
+    if (nativeFingerInput) {
+      // native overlay가 finger touch를 받는 경우 — pinch/finger pan은 native 측 처리.
+      // RNGH는 stylus draw만, zoom은 native에서 별도 게스처로.
+      return drawPanGesture;
+    }
+    return Gesture.Simultaneous(drawPanGesture, fingerPanGesture, pinchGesture);
+  }, [enableZoomPan, nativeFingerInput, drawPanGesture, fingerPanGesture, pinchGesture]);
+
+  return { composedGesture };
+}

packages/pointer-native-drawing/src/canvas/useCanvasViewportController.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  type ScrollView,
+} from 'react-native';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+
+import { type ViewTransform, IDENTITY_TRANSFORM, clampTransform } from '../transform';
+import { type RendererViewport } from '../render/rendererTypes';
+
+const MIN_CANVAS_HEIGHT_FLOOR = 400;
+const CANVAS_HEIGHT_BUFFER = 200;
+const ZOOM_CONTENT_HEIGHT_MULTIPLIER = 2;
+
+export type UseCanvasViewportControllerArgs = {
+  minCanvasHeight: number;
+  enableZoomPan: boolean;
+  maxZoomScale: number;
+  maxYRef: React.RefObject<number>;
+  onCanvasHeightChange?: (height: number) => void;
+  onScrollOffsetChange?: (offsetY: number) => void;
+  updateViewport: (viewport: RendererViewport) => void;
+};
+
+export function useCanvasViewportController({
+  minCanvasHeight,
+  enableZoomPan,
+  maxZoomScale,
+  maxYRef,
+  onCanvasHeightChange,
+  onScrollOffsetChange,
+  updateViewport,
+}: UseCanvasViewportControllerArgs) {
+  // viewTransform: SharedValue — gesture worklet 직접 갱신, Skia matrix prop 자동 감지
+  const viewTransform = useSharedValue<ViewTransform>(IDENTITY_TRANSFORM);
+
+  // viewport size — JS state + SharedValue dual (layout은 JS, worklet 사용은 SharedValue)
+  const [viewportSize, setViewportSize] = useState({ width: 0, height: 0 });
+  const viewportWidthShared = useSharedValue(0);
+  const viewportHeightShared = useSharedValue(0);
+
+  useEffect(() => {
+    viewportWidthShared.value = viewportSize.width;
+    viewportHeightShared.value = viewportSize.height;
+  }, [viewportSize.width, viewportSize.height, viewportWidthShared, viewportHeightShared]);
+
+  const scrollViewRef = useRef<ScrollView>(null);
+  const minimumCanvasHeightRef = useRef<number>(Math.max(MIN_CANVAS_HEIGHT_FLOOR, minCanvasHeight));
+  const [canvasHeight, setCanvasHeight] = useState<number>(minimumCanvasHeightRef.current);
+  const canvasHeightRef = useRef(canvasHeight);
+  canvasHeightRef.current = canvasHeight;
+
+  // Low fix: minCanvasHeight prop sync (첫 렌더 capture 회피)
+  useEffect(() => {
+    minimumCanvasHeightRef.current = Math.max(MIN_CANVAS_HEIGHT_FLOOR, minCanvasHeight);
+  }, [minCanvasHeight]);
+
+  const onCanvasHeightChangeRef = useRef(onCanvasHeightChange);
+  const onScrollOffsetChangeRef = useRef(onScrollOffsetChange);
+  onCanvasHeightChangeRef.current = onCanvasHeightChange;
+  onScrollOffsetChangeRef.current = onScrollOffsetChange;
+
+  // Low fix: setState updater 외부에서 callback 분리 (StrictMode 더블 렌더 안전)
+  const setCanvasHeightValue = useCallback((nextHeight: number) => {
+    const normalized = Math.max(minimumCanvasHeightRef.current, nextHeight);
+    if (normalized === canvasHeightRef.current) return;
+    setCanvasHeight(normalized);
+    onCanvasHeightChangeRef.current?.(normalized);
+  }, []);
+
+  const resetCanvasHeight = useCallback(() => {
+    setCanvasHeightValue(minimumCanvasHeightRef.current);
+  }, [setCanvasHeightValue]);
+
+  const maybeGrowCanvasHeight = useCallback(
+    (nextMaxY: number) => {
+      if (nextMaxY > maxYRef.current) {
+        maxYRef.current = nextMaxY;
+        setCanvasHeightValue(nextMaxY + CANVAS_HEIGHT_BUFFER);
+      }
+    },
+    [setCanvasHeightValue, maxYRef]
+  );
+
+  const syncCanvasHeightFromMaxY = useCallback(
+    (nextMaxY: number) => {
+      if (nextMaxY <= 0) {
+        maxYRef.current = 0;
+        resetCanvasHeight();
+        return;
+      }
+      maxYRef.current = nextMaxY;
+      setCanvasHeightValue(nextMaxY + CANVAS_HEIGHT_BUFFER);
+    },
+    [resetCanvasHeight, setCanvasHeightValue, maxYRef]
+  );
+
+  // zoom 활성화 시 content height = max(canvasHeight, viewportHeight × ZOOM_CONTENT_HEIGHT_MULTIPLIER)
+  const effectiveCanvasHeight = enableZoomPan
+    ? Math.max(canvasHeight, viewportSize.height * ZOOM_CONTENT_HEIGHT_MULTIPLIER)
+    : canvasHeight;
+
+  // canvas height SharedValue (worklet에서 clampTransform 호출용)
+  const canvasHeightShared = useSharedValue(canvasHeight);
+  useEffect(() => {
+    canvasHeightShared.value = effectiveCanvasHeight;
+  }, [effectiveCanvasHeight, canvasHeightShared]);
+
+  // applyTransform: JS-side callback. consumer 직접 호출 (e.g. external transform 변경).
+  // gesture worklet 안에서는 inline clampTransform + viewTransform.value 갱신 — runOnJS 매 프레임 회피.
+  const applyTransform = useCallback(
+    (next: ViewTransform) => {
+      const clamped = clampTransform(
+        next,
+        viewportSize.width,
+        effectiveCanvasHeight,
+        viewportSize.width,
+        viewportSize.height,
+        maxZoomScale
+      );
+      viewTransform.value = clamped;
+    },
+    [viewTransform, viewportSize.width, viewportSize.height, effectiveCanvasHeight, maxZoomScale]
+  );
+
+  const viewportRef = useRef<RendererViewport>({ scrollOffsetY: 0, viewportHeight: 0 });
+
+  const handleScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const offsetY = event.nativeEvent.contentOffset.y;
+      updateViewport({
+        scrollOffsetY: offsetY,
+        viewportHeight: viewportRef.current.viewportHeight,
+      });
+      viewportRef.current = { ...viewportRef.current, scrollOffsetY: offsetY };
+      onScrollOffsetChangeRef.current?.(offsetY);
+    },
+    [updateViewport]
+  );
+
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const { width, height } = event.nativeEvent.layout;
+      setViewportSize((prev) => {
+        if (prev.width === width && prev.height === height) return prev;
+        return { width, height };
+      });
+      updateViewport({ scrollOffsetY: viewportRef.current.scrollOffsetY, viewportHeight: height });
+      viewportRef.current = { ...viewportRef.current, viewportHeight: height };
+    },
+    [updateViewport]
+  );
+
+  return {
+    viewTransform,
+    viewportWidthShared,
+    viewportHeightShared,
+    canvasHeightShared,
+    viewportSize,
+    canvasHeight: effectiveCanvasHeight,
+    scrollViewRef,
+    setCanvasHeightValue,
+    resetCanvasHeight,
+    maybeGrowCanvasHeight,
+    syncCanvasHeightFromMaxY,
+    applyTransform,
+    handleScroll,
+    handleLayout,
+  };
+}
+
+export type UseCanvasViewportControllerResult = ReturnType<typeof useCanvasViewportController>;
+
+export type UseCanvasViewportControllerSharedValues = {
+  viewTransform: SharedValue<ViewTransform>;
+  viewportWidthShared: SharedValue<number>;
+  viewportHeightShared: SharedValue<number>;
+  canvasHeightShared: SharedValue<number>;
+};

packages/pointer-native-drawing/src/render/rendererTypes.ts

@@ -0,0 +1,4 @@
+export type RendererViewport = {
+  scrollOffsetY: number;
+  viewportHeight: number;
+};