크로스 플랫폼 캔버스에서 웹 전용 뷰포트 구현 회고록

// canvas-container.tsx
const { panningHandler, transform, zoomIn, zoomOut, minScale } = usePanningZoom({
  containerRef,  // 바깥 컨테이너 DOM
  width,         // 캔버스 원본 width
  height,        // 캔버스 원본 height
  isReady,       // Wasm 로딩 완료 여부
});


// CSS transform으로 반영
<div style={{
  transform: `translate(${transform.x}px, ${transform.y}px) scale(${transform.scale})`,
  transformOrigin: 'top left',
  willChange: 'transform',
}}>
  <WasmCanvas ... />
</div>
```

const updateTransform = useCallback(
  (containerWidth: number, containerHeight: number) => {
    const scaleX = containerWidth / width;
    const scaleY = containerHeight / height;
    // 비율 유지를 위해 더 작은 scale을 사용
    const initialScale = Math.min(scaleX, scaleY);
    const initialX = (containerWidth - width * initialScale) / 2;
    const initialY = (containerHeight - height * initialScale) / 2;

    minScale.current = initialScale; // 이게 "최소 축소 한계"가 된다
    setTransform({ x: initialX, y: initialY, scale: initialScale });
  },
  [width, height],
);

// react-zoom-pan-pinch/src/core/bounds/bounds.utils.ts
export function getMouseBoundedPosition(...) {
  // 원래 경계 [min, max]에 padding을 더해서 [min - padding, max + padding]으로 확장
  const x = boundLimiter(positionX, minPositionX - paddingX, maxPositionX + paddingX, limitToBounds);
  const y = boundLimiter(positionY, minPositionY - paddingY, maxPositionY + paddingY, limitToBounds);
  return { x, y };
}

// react-zoom-pan-pinch/src/core/pan/panning.logic.ts
export function handlePanningEnd(contextInstance) {
  if (shouldAnimate) {
    handleVelocityPanning(contextInstance); // 관성이 있으면 관성 + 복귀
  } else {
    handleAlignToBounds(contextInstance);   // 관성 없으면 바로 복귀
  }
}
export function handleAlignToBounds(contextInstance) {
  const targetState = handlePanToBounds(contextInstance); // padding 없는 진짜 경계 좌표 계산
  animate(contextInstance, targetState, animationTime, animationType); // easeOut으로 부드럽게 복귀
}

const getBoundedTransform = useCallback(
  (targetTransform: { x: number; y: number; scale: number }, usePadding = true) => {
    const container = containerRef.current;
    if (!container) return targetTransform;
    const { x, y, scale } = targetTransform;
    const containerWidth = container.clientWidth;
    const containerHeight = container.clientHeight;
    const scaledWidth = width * scale;
    const scaledHeight = height * scale;
    // usePadding 플래그로 경계 확장 여부를 결정
    const appliedPadding = usePadding ? panningPadding : 0;
    let minX, maxX, minY, maxY;
    if (scaledWidth > containerWidth) {
      // 확대된 상태: 캔버스가 컨테이너보다 크므로 좌우로 이동 가능
      minX = containerWidth - scaledWidth - appliedPadding;
      maxX = appliedPadding;
    } else {
      // 축소/원본 상태: 캔버스가 컨테이너 안에 있으므로 중앙 정렬 기준으로 제한
      const offsetX = (containerWidth - scaledWidth) / 2;
      minX = offsetX - appliedPadding;
      maxX = offsetX + appliedPadding;
    }
    // Y축도 동일 로직 ...
    return {
      scale,
      x: Math.max(minX, Math.min(x, maxX)),
      y: Math.max(minY, Math.min(y, maxY)),
    };
  },
  [width, height, panningPadding],
);

const handleMouseMove = useCallback((e: React.MouseEvent) => {
  if (!panState.current.isPanning) return;
  const newTransform = getBoundedTransform({
    x: e.clientX - panState.current.startX,
    y: e.clientY - panState.current.startY,
    scale: transformRef.current.scale,
  }, true); // 여긴 true
  requestAnimationFrame(() => setTransform(newTransform));
}, [getBoundedTransform]);



// 드래그 끝 — 패딩 없는 진짜 경계로 복귀
const handleMouseUpOrLeave = useCallback(() => {
  panState.current.isPanning = false;
  const finalTransform = getBoundedTransform(transformRef.current, false); // 여긴 false 
  
  // 이미 경계 안이면 아무것도 안 함
  if (finalTransform.x === transformRef.current.x && finalTransform.y === transformRef.current.y) return;
  
  // easeOut 커빙으로 부드럽게 복귀
  const from = transformRef.current;
  const to = finalTransform;
  const duration = 250;
  const animateToFinalPosition = (timestamp: number) => {
    const progress = Math.min((timestamp - startTime) / duration, 1);
    const easeOutProgress = 1 - Math.pow(1 - progress, 3);
    setTransform({
      x: from.x + (to.x - from.x) * easeOutProgress,
      y: from.y + (to.y - from.y) * easeOutProgress,
      scale: to.scale,
    });
    if (progress < 1) requestAnimationFrame(animateToFinalPosition);
  };
  requestAnimationFrame(animateToFinalPosition);
}, [getBoundedTransform]);

const handleMouseDown = useCallback((e) => {
  // 스냅백 애니메이션 중이면 즉시 취소
  if (snapAnimationId.current) {
    cancelAnimationFrame(snapAnimationId.current);
  }
  // ... 패닝 시작
}, []);

[React 레이어]
  - webToolbarState: 'drawing' | 'textElement' | 'grab'  ← 'grab'은 웹 전용
  - isDrawingDisabled: boolean  ← true면 Wasm 위에 투명 div를 덮어서 입력 차단 (상태관리)

[Wasm 레이어]
  - currentTool: 'pen' | 'eraser' | ... (핸드 모드를 모름)

// canvas-container.tsx — 투명 오버레이
{isDrawingDisabled && <div className="absolute inset-0 w-full h-full" />}

const handleHandToolShortcut = useCallback(
  (isHand: boolean) => {
    if (isHand) {
      setIsActiveHand(true);
      setIsDrawingDisabled(true);

      // 지우개 상태였으면 기억해뒀다가 나중에 복원
      if (webTool === "eraser") {
        eraserSnapshotRef.current = true;
        setTool("pen"); // 코어 도구를 잠시 바꿈
      }
    } else {
      setIsActiveHand(false);
      setIsDrawingDisabled(false);
      // 핸드 모드 해제 시 지우개로 복원
      if (eraserSnapshotRef.current) {
        setTool("eraser");
        eraserSnapshotRef.current = false;
      }
    }
  },
  [setTool, webTool],
);

┌──────────── 웹 레이어 (React) ────────────┐
│  usePanningZoom: scale, x, y 관리        │
│  CSS transform으로 뷰포트 제어              │
│  스페이스바 핸드 모드 (투명 div 오버레이)       │
│  경계 보정 + 스냅백 애니메이션                 │
├─────────────────────────────────────────┤
│  window.flutter_canvas (브릿지)           │
├─────────────────────────────────────────┤
│  Flutter Wasm (코어 엔진)                 │
│  → 자기 좌표계에서 그림만 그림                 │
│  → 뷰포트 존재를 모름                        │
└─────────────────────────────────────────┘