흰 화면 부트 진단 추가

apps/web/index.html

@@ -63,6 +63,131 @@
       rel="stylesheet"
       href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/variable/pretendardvariable.min.css"
     />
+    <script>
+      (function () {
+        var errors = [];
+        var loadedAt = Date.now();
+        function short(value) {
+          return String(value || "").slice(0, 900);
+        }
+        function assetLabel() {
+          var scripts = Array.prototype.slice.call(document.scripts || []);
+          var match = scripts
+            .map(function (script) {
+              return script.src || "";
+            })
+            .filter(function (src) {
+              return src.indexOf("/assets/index-") !== -1 && /\.js($|\?)/.test(src);
+            })
+            .pop();
+          return match ? match.split("/").pop() : "module-not-discovered";
+        }
+        function remember(kind, detail) {
+          errors.push({
+            kind: kind,
+            detail: short(detail),
+            at: new Date().toISOString(),
+          });
+          if (errors.length > 5) errors.shift();
+          render("runtime-error");
+        }
+        function visibleCount() {
+          var nodes = Array.prototype.slice.call(
+            document.querySelectorAll(
+              "main,header,h1,h2,p,a,button,input,select,article,section,.vg-shell,.ad-head,.ad-diagnostic,.lg-root",
+            ),
+          );
+          return nodes.filter(function (node) {
+            var rect = node.getBoundingClientRect();
+            var style = window.getComputedStyle(node);
+            return (
+              rect.width > 1 &&
+              rect.height > 1 &&
+              style.display !== "none" &&
+              style.visibility !== "hidden" &&
+              style.opacity !== "0"
+            );
+          }).length;
+        }
+        function render(reason) {
+          var path = window.location.pathname;
+          var isAdmin = path === "/admin" || path.indexOf("/admin/") === 0;
+          var text = (document.body && document.body.innerText ? document.body.innerText : "").trim();
+          var visible = visibleCount();
+          var hasAdminContent =
+            !isAdmin ||
+            Boolean(document.querySelector(".ad-head,.ad-diagnostic,.ad-status,.ad-section,.ad-panel"));
+          if (reason === "watchdog" && text.length > 24 && visible > 0 && hasAdminContent) {
+            var old = document.getElementById("vignette-boot-diagnostic");
+            if (old) old.remove();
+            return;
+          }
+
+          var panel = document.getElementById("vignette-boot-diagnostic");
+          if (!panel) {
+            panel = document.createElement("section");
+            panel.id = "vignette-boot-diagnostic";
+            panel.setAttribute("role", "alert");
+            panel.style.cssText =
+              "position:fixed;z-index:2147483647;inset:24px auto auto 24px;max-width:min(760px,calc(100vw - 48px));padding:18px;border:1px solid #d59b47;border-radius:8px;background:#fffaf0;color:#21312e;box-shadow:0 18px 48px rgba(10,20,18,.18);font:13px/1.5 system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;white-space:normal;";
+            document.body.appendChild(panel);
+          }
+          var lines = [
+            "<b style=\"display:block;font-size:18px;margin-bottom:6px\">Vignette 화면 진단</b>",
+            "<div>React 화면이 정상 콘텐츠를 표시하지 못해서 HTML 부트스트랩 진단을 띄웠습니다.</div>",
+            "<dl style=\"display:grid;grid-template-columns:132px minmax(0,1fr);gap:0;margin:12px 0 0;border:1px solid rgba(0,0,0,.12);border-radius:8px;overflow:hidden\">",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">reason</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              reason +
+              "</dd>",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">path</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              path +
+              "</dd>",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">asset</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              assetLabel() +
+              "</dd>",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">bodyText</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              text.length +
+              "</dd>",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">visibleNodes</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              visible +
+              "</dd>",
+            "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">elapsed</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere\">" +
+              (Date.now() - loadedAt) +
+              "ms</dd>",
+          ];
+          if (errors.length) {
+            lines.push(
+              "<dt style=\"padding:7px 9px;background:rgba(0,0,0,.04);font-weight:700\">errors</dt><dd style=\"margin:0;padding:7px 9px;overflow-wrap:anywhere;white-space:pre-wrap\">" +
+                errors
+                  .map(function (item) {
+                    return item.at + " " + item.kind + ": " + item.detail;
+                  })
+                  .join("\n") +
+                "</dd>",
+            );
+          }
+          lines.push("</dl>");
+          panel.innerHTML = lines.join("");
+        }
+        window.addEventListener("error", function (event) {
+          remember("error", event.message || event.error || "unknown error");
+        });
+        window.addEventListener("unhandledrejection", function (event) {
+          remember("unhandledrejection", event.reason && (event.reason.stack || event.reason.message || event.reason));
+        });
+        window.__VIGNETTE_BOOT_DIAG__ = {
+          check: function () {
+            render("manual");
+          },
+        };
+        window.setTimeout(function () {
+          render("watchdog");
+        }, 3500);
+        window.setTimeout(function () {
+          render("watchdog");
+        }, 8000);
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>

docs/HANDOFF.md

@@ -30,7 +30,7 @@
 - M3 인증 claim 1차: Google/SAML/dev-login이 설정 기반 cohort map과 SAML cohort claim을 `cohort_ids`로 넘기고, 관리 사용자 `external_id`는 provider subject 기반(`google:`/`saml:`/`dev:`)으로 저장한다. 운영 SAML 서명검증·기관 claim schema·deprovisioning audit은 후속.
 - 페르소나 저작/P4~P7 적재 2차: `data/personas/P4.json`~`P7.json`을 저장소 관리 `PersonaCard`로 읽어 `materialize_seed_personas()`와 seed fallback catalog에 포함했다. 검증: `python -m pytest app/test_persona_review.py -q` 22 passed, 로컬 dev DB materialize 결과 `approved_codes=P1,P2,P3,P4,P5,P6,P7`, 인증된 로컬 `GET /personas`도 `P1..P7` 반환.
 - Google OAuth 진단 1차: provider callback error는 `access_denied`/`provider_error`로 분리하고, 로그인 화면은 실패 reason code를 함께 표시한다. 실제 Google 계정 완료 proof는 아직 owner 로그인/storageState가 필요하다.
-- 관리자 기본 진입 경로와 blank diagnostics: `initialPathForUser()`가 pending/onboarding/admin-entitled landing을 소유한다. 관리자 콘솔 접근권이 있는 계정은 primary role이 learner/teacher여도 `/` 또는 로그인 완료 뒤 `/admin`으로 들어간다. `App.tsx`는 pathname 변경마다 document scroll을 0으로 복원해 긴 관리자 화면에서 짧은 `/admin/access`로 이동해도 sticky shell만 보이는 빈 화면을 만들지 않는다. 관리자 화면은 `/admin/users`와 `/admin/tickets` payload 계약 위반을 안전하게 정규화하고 `관리자 데이터 진단`으로 깨진 필드/path/asset을 표시한다. 앱 route-level error boundary도 렌더 예외를 full white page 대신 진단 화면으로 대체하며, 0-height main도 진단 패널로 노출한다. 검증: `npm run typecheck`, `npm run build`, `npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "admin route guards"` 5 passed, custom domain 새 asset 확인.
+- 관리자 기본 진입 경로와 blank diagnostics: `initialPathForUser()`가 pending/onboarding/admin-entitled landing을 소유한다. 관리자 콘솔 접근권이 있는 계정은 primary role이 learner/teacher여도 `/` 또는 로그인 완료 뒤 `/admin`으로 들어간다. `App.tsx`는 pathname 변경마다 document scroll을 0으로 복원해 긴 관리자 화면에서 짧은 `/admin/access`로 이동해도 sticky shell만 보이는 빈 화면을 만들지 않는다. 관리자 화면은 `/admin/users`와 `/admin/tickets` payload 계약 위반을 안전하게 정규화하고 `관리자 데이터 진단`으로 깨진 필드/path/asset을 표시한다. 앱 route-level error boundary도 렌더 예외를 full white page 대신 진단 화면으로 대체하며, 0-height main도 진단 패널로 노출한다. `index.html`에는 React/module 실행 자체가 실패해도 3.5초 뒤 `Vignette 화면 진단`을 body에 직접 띄우는 boot watchdog이 있다. 검증: `npm run typecheck`, `npm run build`, `npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "admin route guards"` 5 passed, dist file JS-missing watchdog smoke passed, custom domain 새 asset 확인.
 - `frontenddesign` 스킬은 현재 세션의 사용 가능 스킬 목록에 없었다. 대신 `docs/DESIGN_CONCEPT.md`를 SSOT로 사용했다.
 - 공개 API 터널은 현재 `C:\Users\encep\.cloudflared\vignette-config.yml`에서 `http://127.0.0.1:8001`을 본다.
 - 공개용 API 프로세스는 `127.0.0.1:8001`에서 `ENVIRONMENT=prod`로 떠 있다. 로컬 개발 API `127.0.0.1:8000`과 Tailnet 개발 API `127.0.0.1:8010`도 `ENVIRONMENT=dev`로 떠 있다.

docs/dev_dashboard.html

@@ -963,7 +963,7 @@
                   <tr><td>P2a RBAC/audit/visibility</td><td><code>app.test_rbac_idor</code></td><td>11 tests OK; other learner 403, read_session audit, evaluator-only hidden, teacher session review read allowed, super_admin learner review principal is promoted to admin for evaluation/worksheet/review-status loaders, admin_access-only learner remains blocked, and learner worksheet write remains 403</td></tr>
                   <tr><td>Admin access delegation</td><td><code>C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe -X utf8 -m pytest -p no:cacheprovider app/test_admin_ops.py app/test_auth_providers.py::AuthProviderScaffoldTest::test_admin_role_can_enter_admin_console_even_with_stale_access_flag app/test_auth_providers.py::AuthProviderScaffoldTest::test_admin_role_can_enter_all_role_spaces_without_super_admin app/test_auth_providers.py::AuthProviderScaffoldTest::test_admin_access_flag_without_admin_role_does_not_enter_learner_space -q</code> / <code>npx playwright test e2e/admin.spec.ts --project=chromium-desktop --project=chromium-mobile --workers=1 --grep "approved admin without onboarding"</code> / <code>npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "admin route guards"</code> / <code>npm run typecheck</code></td><td>13 backend focused passed + admin onboarding guard E2E 2 passed + latest admin route guards 5 passed + web typecheck/build passed. 실제 <code>admin</code> role은 <code>admin_access=false</code> 세션이어도 <code>can_access_role(Role.ADMIN)</code>으로 관리자 API를 열고, 승인된 관리자 또는 <code>admin_access</code> 계정은 <code>/admin*</code>에서 학습자 온보딩으로 우회하지 않는다. 최초 진입 경로도 <code>initialPathForUser</code>가 소유해 primary role이 learner/teacher인 관리자 권한 계정이 <code>/</code> 또는 로그인 완료 후 <code>/admin</code>으로 들어간다. 관리자 sidebar와 기존 workspace 전환 계약은 유지된다.</td></tr>
                   <tr><td>SPA route scroll reset</td><td><code>npm run typecheck</code> / <code>npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "resets scroll"</code> / Pages deploy</td><td>Typecheck passed and focused E2E 1 passed. <code>App.tsx</code> resets document scroll to top on <code>pathname</code> changes, so moving from a long admin page to short <code>/admin/access</code> no longer preserves stale <code>scrollY</code> and shows only the sticky topbar/sidebar over an empty main area. Probe proof: previous <code>scrollY=1000</code>, after clicking <code>권한</code> <code>scrollY=0</code>, heading <code>역할, 그룹, 접근 범위</code> in viewport. Live custom domain now serves <code>assets/index-R5KK7hZI.js</code>/<code>assets/index-DzdAkRsn.css</code>.</td></tr>
-                  <tr><td>Admin silent-blank diagnostics</td><td><code>npm run typecheck</code> / <code>npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "admin route guards"</code></td><td>Typecheck passed and route-guard E2E 5 passed. Admin now normalizes malformed <code>/admin/users</code> payload fields such as <code>cohort_ids=null</code>, <code>active_sessions=null</code>, and <code>created_at=null</code>, plus malformed <code>/admin/tickets</code> payloads such as <code>summary=null</code>, instead of throwing during render. The screen shows <code>관리자 데이터 진단</code> with section/path/asset and broken field keys. App-level route render errors now fall back to a full-page diagnostic instead of a white screen, and zero-height main content still falls back to the admin diagnostic panel.</td></tr>
+                  <tr><td>Admin silent-blank diagnostics</td><td><code>npm run typecheck</code> / <code>npx playwright test e2e/admin.spec.ts --project=chromium-desktop --workers=1 --grep "admin route guards"</code> / dist watchdog smoke</td><td>Typecheck passed and route-guard E2E 5 passed. Admin now normalizes malformed <code>/admin/users</code> payload fields such as <code>cohort_ids=null</code>, <code>active_sessions=null</code>, and <code>created_at=null</code>, plus malformed <code>/admin/tickets</code> payloads such as <code>summary=null</code>, instead of throwing during render. The screen shows <code>관리자 데이터 진단</code> with section/path/asset and broken field keys. App-level route render errors now fall back to a full-page diagnostic instead of a white screen, and zero-height main content still falls back to the admin diagnostic panel. If the React module itself fails before mount, <code>index.html</code> boot watchdog appends <code>Vignette 화면 진단</code> directly to body; file-based JS-missing smoke confirmed the panel appears with path/asset/bodyText/visibleNodes.</td></tr>
                   <tr><td>OAuth/SAML admin landing</td><td><code>C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe -X utf8 -m pytest -p no:cacheprovider app/test_auth_providers.py -q</code> / public runtime restart</td><td>36 passed; OAuth/SAML callback now normalizes generic saved <code>next</code> paths such as <code>/learn</code> and <code>/teach</code> to <code>/admin</code> for admin-entitled users while preserving deep links such as <code>/learn/session/...</code>. Live proof after commits <code>998acb44</code>/<code>6b6241f4</code> and latest route-boundary deploy <code>287029f2</code>: local/public <code>/health</code> returned <code>prod</code>, <code>db=true</code>, <code>engine=true</code>; custom domain now serves <code>assets/index-R5KK7hZI.js</code>/<code>assets/index-DzdAkRsn.css</code>; unauthenticated <code>/personas</code> remains <code>401</code>.</td></tr>
                   <tr><td>Session read-model DB readiness</td><td><code>python scripts\check-deploy-preflight.py --skip-db --env-file infra\.env.example --allow-placeholder-secrets</code> / <code>https://api-vignette.chanpaca.net/health</code></td><td>2026-06-29 prod 503 원인은 운영 DB의 <code>app.turns.provider_events</code> 컬럼 누락이었다. 운영 DB hotfix 후 <code>/teacher/dashboard</code> code path는 <code>source=database</code>로 복구됐다. 현재 <code>db.healthcheck()</code>, runtime table readiness, deploy preflight DB mode는 <code>app.turns</code> 음성 메타 컬럼 5개(<code>audio_ref</code>, <code>silence_ms</code>, <code>speech_rate</code>, <code>barge_in</code>, <code>provider_events</code>), <code>app.session_review_status</code> worksheet 컬럼, <code>app.safety_events</code> 필수 컬럼을 함께 검증한다. 2026-06-30에는 Docker Desktop/DB 중단으로 public API 530/error code 1033이 재발했지만, Docker Desktop/DB 재기동 뒤 public health가 <code>environment=prod</code>, <code>db=true</code>, <code>engine=true</code>로 복구됐다.</td></tr>
                   <tr><td>Admin usage persistence</td><td><code>python -m pytest app/test_admin_ops.py app/test_runtime_policy.py -q</code> / authenticated local public-API smoke</td><td>26 passed; <code>/admin/usage</code> returns 200 with <code>source=database</code>, <code>durable=true</code>. Cloudflare blocked raw Python public smoke with 1010, so app-level HTTP was verified against <code>127.0.0.1:8001</code> using the same prod process.</td></tr>

docs/guides/architecture.md

@@ -732,6 +732,9 @@ DB 레벨 이중강제(`04_audit_eval_rls.sql` §5, `app/db.py` `acquire()`):
   패널에 깨진 필드와 asset/path를 표시한다. 앱 route-level error boundary는 관리자 컴포넌트 바깥에서
   터진 렌더 예외도 full white page 대신 진단 화면으로 노출하고, 본문 0-height 상태도 route-scoped
   diagnostic panel로 표시해 운영자가 원인 없이 빈칸만 보지 않게 한다.
+- `index.html`은 React module 실행 자체가 실패하는 경우도 full white page로 두지 않는다. 부트스트랩 watchdog은
+  3.5초/8초 시점에 body/root visible content와 관리자 본문 marker를 검사하고, 실패 시 `Vignette 화면 진단`
+  패널을 React root 바깥 body에 직접 추가해 path, asset, bodyText, visibleNodes, global error를 표시한다.
 - OAuth/SAML callback은 저장된 `next`가 일반 진입 경로(`/`, `/learn`, `/teach`, `/login`, `/onboarding`)이고
   로그인 사용자가 관리자 콘솔 접근권을 가지면 `/admin`으로 정규화한다. 단, `/learn/session/...` 같은 깊은
   링크는 사용자가 의도적으로 연 URL일 수 있으므로 보존한다.