fix(web): fallback to 2d when webgl is unstable

Author: xiaojilele-glitch

src/web/src/pages/tasks/page.tsx

@@ -21,6 +21,7 @@ import type {
   TaskRecord,
 } from '@features/tasks/types';
 import { getCurrentAppPath, navigate, subscribeNavigation } from '@shared/navigation';
+import { shouldPrefer2D, supportsWebGL } from '@shared/platform';
 
 const taskStyles = `
 :root {
@@ -1367,7 +1368,8 @@ async function fetchJson<T>(url: string, init?: RequestInit): Promise<T> {
 }
 
 export default function TasksPage() {
-  const [interiorViewMode, setInteriorViewMode] = useState<'3d' | '2d'>('3d');
+  const disable3D = useMemo(() => shouldPrefer2D() || !supportsWebGL(), []);
+  const [interiorViewMode, setInteriorViewMode] = useState<'3d' | '2d'>(() => (disable3D ? '2d' : '3d'));
   const pathname = useSyncExternalStore(subscribeNavigation, getCurrentAppPath, () => '/tasks');
   const selectedTaskId = parseSelectedTaskId(pathname);
   const detailMode = Boolean(selectedTaskId);
@@ -1392,6 +1394,12 @@ export default function TasksPage() {
   const [edgeBusy, setEdgeBusy] = useState(false);
   const [edgeError, setEdgeError] = useState<string | null>(null);
 
+  useEffect(() => {
+    if (disable3D && interiorViewMode === '3d') {
+      setInteriorViewMode('2d');
+    }
+  }, [disable3D, interiorViewMode]);
+
   async function refreshUniverse(): Promise<void> {
     try {
       const planetData = await fetchJson<PlanetListResponse>('/api/planets?limit=50');
@@ -1775,7 +1783,7 @@ export default function TasksPage() {
 
   const interiorContent = selectedTask && selectedPlanet ? (
     interior && interiorTaskId === selectedTask.id && !interiorError ? (
-      interiorViewMode === '3d' ? (
+      interiorViewMode === '3d' && !disable3D ? (
         <PlanetInteriorScene3D
           planet={selectedPlanet}
           interior={interior}
@@ -1855,19 +1863,21 @@ export default function TasksPage() {
 
               <div className="task-detail-grid">
                 <main className="task-shell task-detail-main">
-                  <div className="task-main-head">
-                    <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16 }}>
-                      <div>
-                        <h1 style={{ margin: 0, fontSize: 18 }}>Task detail</h1>
+                    <div className="task-main-head">
+                      <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16 }}>
+                        <div>
+                          <h1 style={{ margin: 0, fontSize: 18 }}>Task detail</h1>
                         <div style={{ marginTop: 6, color: 'var(--task-dim)', fontSize: 13 }}>
                           This page is optimized for the Feishu progress card and focuses on one task.
                         </div>
                       </div>
                       <div className="task-view-switch">
                         <button
                           type="button"
-                          className={`task-tool-btn ${interiorViewMode === '3d' ? 'active' : ''}`}
+                          className={`task-tool-btn ${interiorViewMode === '3d' && !disable3D ? 'active' : ''}`}
                           onClick={() => setInteriorViewMode('3d')}
+                          disabled={disable3D}
+                          title={disable3D ? '3D 视图在当前设备/内置浏览器环境下容易白屏，已默认切换到 2D。' : undefined}
                         >
                           Workspace
                         </button>
@@ -2243,8 +2253,10 @@ export default function TasksPage() {
                 <div className="task-view-switch">
                   <button
                     type="button"
-                    className={`task-tool-btn ${interiorViewMode === '3d' ? 'active' : ''}`}
+                    className={`task-tool-btn ${interiorViewMode === '3d' && !disable3D ? 'active' : ''}`}
                     onClick={() => setInteriorViewMode('3d')}
+                    disabled={disable3D}
+                    title={disable3D ? '3D 视图在当前设备/内置浏览器环境下容易白屏，已默认切换到 2D。' : undefined}
                   >
                     像素办公室
                   </button>
@@ -2265,7 +2277,7 @@ export default function TasksPage() {
           <div className="task-main-body">
             {selectedTask && selectedPlanet ? (
               interior && interiorTaskId === selectedTask.id && !interiorError ? (
-                interiorViewMode === '3d' ? (
+                interiorViewMode === '3d' && !disable3D ? (
                   <PlanetInteriorScene3D
                     planet={selectedPlanet}
                     interior={interior}

src/web/src/pages/universe/page.tsx

@@ -5,6 +5,7 @@ import type { PlanetEdge, PlanetListResponse, PlanetOverviewItem, TaskRecord } f
 import UniverseCanvas from '@features/tasks/universe/UniverseCanvas';
 import UniverseScene3D from '@features/tasks/universe/UniverseScene3D';
 import { navigate, subscribeNavigation } from '@shared/navigation';
+import { shouldPrefer2D, supportsWebGL } from '@shared/platform';
 
 const universeStyles = `
 :root {
@@ -462,6 +463,8 @@ function parseFocusPlanetId(search: string): string | null {
 }
 
 function parseViewMode(search: string): UniverseViewMode {
+  const disable3D = shouldPrefer2D() || !supportsWebGL();
+  if (disable3D) return '2d';
   const view = new URLSearchParams(search).get('view');
   return view === '2d' ? '2d' : '3d';
 }
@@ -585,6 +588,7 @@ export default function UniversePage() {
   const search = useSyncExternalStore(subscribeNavigation, () => window.location.search, () => '');
   const focusPlanetId = parseFocusPlanetId(search);
   const viewMode = parseViewMode(search);
+  const disable3D = useMemo(() => shouldPrefer2D() || !supportsWebGL(), []);
   const [planets, setPlanets] = useState<PlanetOverviewItem[]>([]);
   const [edges, setEdges] = useState<PlanetEdge[]>([]);
   const [loading, setLoading] = useState(true);
@@ -799,8 +803,10 @@ export default function UniversePage() {
               <div className="universe-view-switch">
                 <button
                   type="button"
-                  className={`universe-btn ${viewMode === '3d' ? 'primary' : ''}`}
+                  className={`universe-btn ${viewMode === '3d' && !disable3D ? 'primary' : ''}`}
                   onClick={() => navigate(buildUniverseUrl(selectedPlanet?.id ?? focusPlanetId, '3d'))}
+                  disabled={disable3D}
+                  title={disable3D ? '3D 视图在当前设备/内置浏览器环境下容易白屏，已默认切换到 2D。' : undefined}
                 >
                   3D 星图
                 </button>
@@ -925,7 +931,7 @@ export default function UniversePage() {
                     当前服务器尚未提供 Planet API。现在展示的是由 `/api/tasks` 推导出的宇宙视图，因此连线关系和更丰富的星球元数据暂不可用。
                   </div>
                 ) : null}
-                {viewMode === '3d' ? (
+                {viewMode === '3d' && !disable3D ? (
                   <UniverseScene3D
                     planets={planets}
                     edges={filteredUniverse.visibleEdges}

src/web/src/shared/platform.ts

@@ -0,0 +1,42 @@
+export function isProbablyIOS(): boolean {
+  if (typeof navigator === 'undefined') return false;
+
+  const ua = navigator.userAgent || '';
+  if (/iPad|iPhone|iPod/i.test(ua)) return true;
+
+  // iPadOS 13+ reports itself as Macintosh; detect by touch capability.
+  const platform = navigator.platform || '';
+  const touchPoints = (navigator as unknown as { maxTouchPoints?: number }).maxTouchPoints ?? 0;
+  return platform === 'MacIntel' && touchPoints > 1;
+}
+
+export function isFeishuInAppBrowser(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const ua = navigator.userAgent || '';
+  // Heuristic tokens seen in Feishu/Lark app webviews.
+  return /feishu|lark|bytedancelark/i.test(ua);
+}
+
+export function supportsWebGL(): boolean {
+  if (typeof document === 'undefined') return false;
+  try {
+    const canvas = document.createElement('canvas');
+    return Boolean(
+      canvas.getContext('webgl2')
+      || canvas.getContext('webgl')
+      || canvas.getContext('experimental-webgl'),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * iOS in-app webviews are the most common source of "flash then white screen"
+ * when heavy WebGL scenes initialize. Prefer 2D to keep the task detail usable.
+ */
+export function shouldPrefer2D(): boolean {
+  if (!isProbablyIOS()) return false;
+  return true;
+}
+