fix(preload): split into disk-cache phase + CPU-load phase to unblock GPU callbacks

Previous: _MODEL_LOCK held during entire snapshot_download (minutes) → GPU
callback blocks waiting for lock → ZeroGPU 240 s budget expires → error.

Fix: Phase 1 downloads both repos to HF disk cache without holding any lock.
Phase 2 instantiates Hunyuan3D from cache under lock (fast, no network I/O).
GPU callbacks can now acquire the lock quickly even if the user clicks early.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app.py

@@ -135,16 +135,37 @@ def _load_geometry_cpu_locked() -> None:
 
 
 def _preload_worker() -> None:
-    # Only preload Hunyuan3D on CPU — it is safe (no CUDA init during loading).
-    # NeAR triggers CUDA init during from_pretrained (BiRefNet/DINOv2 init with
-    # trust_remote_code), which is not allowed in ZeroGPU's main process.
-    # NeAR loads lazily inside the first @GPU callback instead.
+    """Two-phase background preload (avoids blocking GPU callbacks):
+
+    Phase 1 — disk cache warm-up (no lock, no CUDA):
+        snapshot_download both repos so GPU callbacks never wait for network I/O.
+    Phase 2 — CPU instantiation (lock held briefly, no CUDA):
+        Load Hunyuan3D weights into CPU RAM from the local cache.
+
+    NeAR instantiates lazily inside @GPU callbacks — its BiRefNet/DINOv2 init
+    triggers CUDA which is not allowed in the ZeroGPU main process.
+    """
     try:
+        from huggingface_hub import snapshot_download
+
+        # Phase 1: download repos to disk — no lock needed.
+        for _repo in (
+            os.environ.get("NEAR_HUNYUAN_PRETRAINED", "tencent/Hunyuan3D-2.1"),
+            "luh0502/NeAR",
+        ):
+            try:
+                print(f"[NeAR] preload: caching {_repo!r} to disk…", flush=True)
+                snapshot_download(repo_id=_repo, token=os.environ.get("HF_TOKEN"))
+                print(f"[NeAR] preload: {_repo!r} disk-cache ready.", flush=True)
+            except Exception as _exc:
+                print(f"[NeAR] preload: disk-cache {_repo!r} failed: {_exc}", flush=True)
+
+        # Phase 2: instantiate Hunyuan3D on CPU (fast now that files are on disk).
         with _MODEL_LOCK:
             _load_geometry_cpu_locked()
-        print("[NeAR] CPU preload complete (Hunyuan3D only).", flush=True)
+        print("[NeAR] preload: complete.", flush=True)
     except Exception as exc:
-        print(f"[NeAR] CPU preload failed: {exc}", flush=True)
+        print(f"[NeAR] preload failed: {exc}", flush=True)
 
 
 # ── GPU ensure helpers ────────────────────────────────────────────────────────