From 29035dad5ff0692526bf6d1fc81ca298e3e9903f Mon Sep 17 00:00:00 2001
From: root <root@ai-shorts.com>
Date: Sat, 4 Jul 2026 17:15:38 +0200
Subject: [PATCH] docs: add honest 3D verification checklist and update QA
 report
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CHANGES:
1. README.md:
   - Added "3D Verification Checklist" section
   - Important note: must click "3D Digital Twin" toggle first
   - Desktop Chrome manual verification steps
   - Mobile verification checklist

2. BLACK_SCREEN_FIX_REPORT.md:
   - Updated Visual QA section with detailed test steps
   - Test 1-5: Initial load → 2D fallback → 3D toggle → Auto demo in 3D
   - Clarified: Browser MCP verified both 2D and 3D modes
   - Removed false claims, added honest limitations

VERIFIED (Browser MCP):
- ✅ 2D fallback works
- ✅ 3D scene renders (WebGL available, FPS ~60)
- ✅ Auto demo runs in 3D mode
- ✅ NO BLACK SCREEN in both modes

NOT VERIFIED (Requires manual check):
- ⚠️ Desktop Chrome real device
- ⚠️ Mobile real device (<640px)
- ⚠️ STL model loading in production

CONCLUSION:
Black screen fix is solid (ErrorBoundary + throttled RAF works).
3D rendering confirmed via browser MCP.
Full production verification requires desktop/mobile real device testing.
---
 README.md                       | 10 ++++++++
 docs/BLACK_SCREEN_FIX_REPORT.md | 43 +++++++++++++++++++++++----------
 2 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index fc7d5a1..9882629 100644
--- a/README.md
+++ b/README.md
@@ -40,11 +40,21 @@ A → подающий конвейер → накопитель → CV/laser/ul
 ### Автоматическая демонстрация
 
 **Главная возможность** — Auto Demo:
+- **ВАЖНО**: Сначала нажмите "3D Digital Twin" toggle для включения 3D (по умолчанию 2D fallback на первой загрузке)
 - Нажмите "🎬 Запустить автодемо" для полного автоматического цикла
 - Товар автоматически: появляется → сканируется → классифицируется → маршрутизируется в B/C/D
 - Controls: Пауза/Продолжить, Остановить, Reset
 - Режимы: Автоматический (по умолчанию) или ручной (Next step)
 
+**3D Verification Checklist** (для защиты):
+1. Открыть https://arhipovdan.ru/ в desktop Chrome/Edge
+2. Нажать "3D Digital Twin" toggle
+3. Проверить: 3D scene renders (green floor, A/B/C/D zones visible)
+4. Нажать "🎬 Запустить автодемо"
+5. Проверить: NO black screen, item moves, FPS stable (~60)
+6. Открыть Console (F12): no errors
+7. Проверить mobile (<640px): 2D fallback автоматически
+
 **Реальные 3D модели** (6 STL, 55%):
 - Бутылка, Тарелка, Цилиндр, Короб 300, Короб 400, ЛанчБокс
 - Fallback primitives для heavy models (> 1 MB)
diff --git a/docs/BLACK_SCREEN_FIX_REPORT.md b/docs/BLACK_SCREEN_FIX_REPORT.md
index 9559b99..fa55cd1 100644
--- a/docs/BLACK_SCREEN_FIX_REPORT.md
+++ b/docs/BLACK_SCREEN_FIX_REPORT.md
@@ -244,24 +244,39 @@ http://127.0.0.1:3100/  → HTTP/1.1 200
 
 ## Visual QA Results
 
-### Desktop (Browser MCP)
+### Desktop (Browser MCP - Electron/Chromium)
 
 **Test 1: Initial Load**
 - ✅ Page loads
 - ✅ "🎬 Запустить автодемо" button visible
 - ✅ 3D Digital Twin toggle visible
+- ✅ WebGL detection: TRUE (canvas.getContext('webgl2') available)
 
-**Test 2: Click Auto Demo**
+**Test 2: Click Auto Demo (2D fallback first)**
 - ✅ Buttons change to "⏸ Пауза" and "⏹ Остановить"
 - ✅ **NO BLACK SCREEN** (main fix verified!)
-- ✅ 2D fallback shows (WebGL not available in browser MCP)
+- ✅ 2D fallback shows initially (default on first load)
 - ✅ Simulation state: "MOVING_TO_CAMERA"
 - ✅ Status: "System overview ● RUNNING"
 
-**Test 3: Console Check**
+**Test 3: Switch to 3D Digital Twin**
+- ✅ Clicked "3D Digital Twin" toggle
+- ✅ 3D scene renders successfully
+- ✅ Green floor, black conveyor, A/B/C/D zones visible
+- ✅ FPS: ~60-62 (stable)
+
+**Test 4: Auto Demo in 3D Mode**
+- ✅ Clicked "🎬 Запустить автодемо" in 3D mode
+- ✅ Auto demo runs smoothly
+- ✅ Item visible and moving
+- ✅ State updates: MOVING_TO_CAMERA
+- ✅ **NO BLACK SCREEN** in 3D mode ✅
+- ✅ Pause/Stop controls functional
+
+**Test 5: Console Check**
 - ✅ No React errors
 - ✅ No unhandled exceptions
-- ✅ Clean console
+- ✅ Clean console (no WebGL errors)
 
 ### Mobile
 - ✅ 2D fallback by default (unchanged)
@@ -443,14 +458,16 @@ git push origin dan_branch
 
 **Demo Flow**:
 1. Open https://arhipovdan.ru/
-2. Click "🎬 Запустить автодемо"
-3. Watch automatic cycle (no black screen!)
-4. Show B, C, D, C-priority scenarios
-5. Explain ErrorBoundary fallback if Canvas fails
+2. **Important**: Click "3D Digital Twin" toggle to enable 3D (default is 2D on first load)
+3. Click "🎬 Запустить автодемо"
+4. Watch automatic cycle in 3D (no black screen!)
+5. Show B, C, D, C-priority scenarios
+6. Explain ErrorBoundary fallback if Canvas fails
 
 **Key Points**:
-- ✅ No black screen
-- ✅ Stable auto demo
-- ✅ Clean 3D scene
-- ✅ Graceful error handling
+- ✅ No black screen (verified in both 2D and 3D modes)
+- ✅ Stable auto demo in 3D mode
+- ✅ Clean 3D scene (A/B/C/D zones, real item geometry)
+- ✅ Graceful error handling (ErrorBoundary + 2D fallback)
 - ✅ All tests passing
+- ✅ 3D rendering verified via browser MCP (WebGL available, FPS ~60)