From 812b4640e202e827fd9bcff7040792fcba2e3d35 Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Mon, 10 Aug 2026 12:24:43 +0800
Subject: [PATCH] feat(web): clamp tabletop camera to the horizon

Add a maxPolarAngle prop to Scene and use it in the tabletop view so the
camera can't dip below the table and peek under face-down cards.
---
 apps/web/src/components/tabletop/TabletopScene.tsx | 3 +++
 apps/web/src/components/viewers/Scene.tsx          | 8 +++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/tabletop/TabletopScene.tsx b/apps/web/src/components/tabletop/TabletopScene.tsx
index b89c534..4e6703a 100644
--- a/apps/web/src/components/tabletop/TabletopScene.tsx
+++ b/apps/web/src/components/tabletop/TabletopScene.tsx
@@ -56,6 +56,9 @@ export default function TabletopScene({
       enablePan
       fullscreen
       shadowScale={shadowScale}
+      // Keep the camera above the table so face-down cards can't be peeked
+      // from below. π/2 clamps the polar angle at the horizon.
+      maxPolarAngle={Math.PI / 2}
       overlay={
         <button
           onClick={() => setShowSurface((v) => !v)}
diff --git a/apps/web/src/components/viewers/Scene.tsx b/apps/web/src/components/viewers/Scene.tsx
index c2d0dd1..ae8c978 100644
--- a/apps/web/src/components/viewers/Scene.tsx
+++ b/apps/web/src/components/viewers/Scene.tsx
@@ -16,7 +16,9 @@ import { EffectComposer, Vignette } from '@react-three/postprocessing';
  *
  * `autoRotate` and `enablePan` tune the orbit controls (a tabletop view, for
  * example, pans instead of rotating). `fullscreen` adds a toggle button that
- * expands the scene to the full screen.
+ * expands the scene to the full screen. `maxPolarAngle` (radians) clamps how
+ * far the camera can tilt below the horizon, e.g. to stop a tabletop view from
+ * peeking under face-down cards.
  */
 export default function Scene({
   children,
@@ -25,6 +27,7 @@ export default function Scene({
   fullscreen = false,
   overlay,
   shadowScale = 22,
+  maxPolarAngle = Math.PI,
 }: {
   children: ReactNode;
   autoRotate?: boolean;
@@ -34,6 +37,8 @@ export default function Scene({
   overlay?: ReactNode;
   /** Contact shadow plane size in world units; defaults to a generous 22. */
   shadowScale?: number;
+  /** Max camera polar angle in radians; defaults to unrestricted (π). */
+  maxPolarAngle?: number;
 }) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [isFullscreen, setIsFullscreen] = useState(false);
@@ -93,6 +98,7 @@ export default function Scene({
           enablePan={enablePan}
           minDistance={0.01}
           maxDistance={8}
+          maxPolarAngle={maxPolarAngle}
           autoRotate={autoRotate}
           makeDefault
         />