Fix blank page from stale cached assets; surface errors

A browser or CDN holding an assets/app.js from before the shell's element
IDs were renamed runs it against the newer index.php, where it grabs
btn-logout/btn-rescan/nav-user/nav-username/app — all now null — and throws
before it can unhide #app-shell. The result is a blank page whose only clue
is a TypeError in the console.

- index.php: asset() stamps local css/js with the file mtime, so a deploy is
  a new URL and a stale copy can't be paired with a newer shell.
- index.php: install an error handler ahead of every other script (capture
  phase, so failed resource loads are caught too) that paints uncaught
  errors, rejections and load failures into a #boot-error panel. It works
  even when app.js itself is what failed, which is this case.
- includes/db.php: add a register_shutdown_function fatal handler, since
  set_exception_handler never sees parse errors, exhausted memory or a
  failed require — those were ending requests with an empty body. Both
  handlers flush partial output and answer in JSON; display_errors stays off
  so a warning can't corrupt a JSON body.
- New optional DEBUG config flag adds exception type, file:line and trace to
  those responses. config.php is gitignored, so installs without the setting
  default to false.

Claude-Session: https://claude.ai/code/session_014oyi9DMdhALrGz989MNNZJ

README.md

@@ -71,6 +71,10 @@ Top-level folders become courses on the home page.
      the web server / PHP user).
    - DB credentials (change the password in production).
    - `ALLOW_REGISTRATION`: set `false` once your users have accounts.
+   - `DEBUG`: include the exception type, `file:line` and stack trace in API
+     error responses. Errors go to the PHP error log either way, so leave this
+     `false` on anything publicly reachable. Installs whose `config.php`
+     predates the setting behave as if it were `false`.
 
    No external binaries are needed — PHP with PDO/MySQL is the whole
    dependency list.
@@ -212,6 +216,22 @@ next scan creates it.
   pure PHP, so listings show durations before anyone plays the video. If a file
   can't be parsed, the browser reports its duration on first play instead.
 
+## When something breaks
+
+`index.php` stamps `assets/*.css|js` with the file's mtime (`asset()`), so a
+deploy is always a fresh URL. Without that, a browser or CDN holding a stale
+`app.js` runs it against a newer shell, it grabs element IDs that no longer
+exist, and it throws before unhiding the shell — a blank page whose only clue
+is in the console. If you ever do see a blank page, hard-refresh and purge the
+CDN cache first.
+
+A small handler installed ahead of every other script catches uncaught errors,
+unhandled rejections and failed script/stylesheet loads, and paints them into a
+`#boot-error` panel — so a failure that stops the app is visible on the page
+rather than silent. Server-side, uncaught exceptions *and* fatals (via
+`register_shutdown_function`, which `set_exception_handler` never sees) are
+returned as JSON, with detail gated behind `DEBUG`.
+
 ## Production notes
 
 - PHP streams the video in 512 KB chunks with Range support, which is fine for

assets/style.css

@@ -1166,3 +1166,22 @@ button, input { font-family: inherit; font-size: inherit; }
   * { animation-duration: .001ms !important; animation-iteration-count: 1 !important; transition-duration: .001ms !important; }
   .is-scanning .scan-spin, .is-scanning .scan-mobile svg { animation: spin 1.4s linear infinite !important; }
 }
+
+/* Boot failure report (index.php installs the handler that creates this).
+   Deliberately self-contained — no custom properties — because the whole
+   point is to stay readable when the app never started. */
+#boot-error {
+  position: fixed;
+  inset: 16px;
+  z-index: 9999;
+  overflow: auto;
+  margin: 0;
+  padding: 20px;
+  border: 1px solid #B84A3C;
+  border-radius: 10px;
+  background: #FFF6F4;
+  color: #5A1E16;
+  font: 500 13px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  white-space: pre-wrap;
+  word-break: break-word;
+}

config.example.php

@@ -18,3 +18,8 @@ define('COMPLETE_THRESHOLD', 0.95);
 
 // Allow new users to self-register from the login page.
 define('ALLOW_REGISTRATION', true);
+
+// Return the exception type, file:line and stack trace in API error responses.
+// Errors are written to the PHP error log either way — this only controls what
+// the browser is told, so leave it false on anything publicly reachable.
+define('DEBUG', false);

includes/db.php

@@ -1,16 +1,57 @@
 <?php
 require_once __DIR__ . '/../config.php';
 
-// Uncaught exceptions in web requests become JSON errors (the SPA surfaces
+// DEBUG is optional: config.php is not in version control, so an install that
-// them) instead of blank 500 pages; details still go to the PHP error log.
+// predates the setting simply behaves as if it were false.
+if (!defined('DEBUG')) {
+    define('DEBUG', false);
+}
+
+// Everything is logged either way. DEBUG only controls how much detail is sent
+// back to the browser — never turn it on for an install exposed to the public,
+// since the payload includes file paths and stack traces.
+error_reporting(E_ALL);
+ini_set('log_errors', '1');
+// Errors must never be printed inline: every endpoint here answers with JSON,
+// and a warning echoed before the body would corrupt it. They travel in the
+// JSON payload below instead.
+ini_set('display_errors', '0');
+
 if (PHP_SAPI !== 'cli') {
-    set_exception_handler(function (Throwable $e): void {
+    /** Send a JSON error body, replacing whatever partial output exists. */
-        error_log($e);
+    $emit = function (string $message, array $debug = []): void {
-        http_response_code(500);
         if (!headers_sent()) {
+            http_response_code(500);
             header('Content-Type: application/json');
         }
-        echo json_encode(['error' => 'Server error: ' . $e->getMessage()]);
+        while (ob_get_level() > 0) {
+            ob_end_clean();
+        }
+        echo json_encode(DEBUG ? ['error' => $message] + $debug : ['error' => $message]);
+    };
+
+    // Uncaught exceptions become JSON errors (the SPA surfaces them) instead
+    // of blank 500 pages.
+    set_exception_handler(function (Throwable $e) use ($emit): void {
+        error_log($e);
+        $emit('Server error: ' . $e->getMessage(), [
+            'type'  => get_class($e),
+            'file'  => $e->getFile() . ':' . $e->getLine(),
+            'trace' => explode("\n", $e->getTraceAsString()),
+        ]);
+    });
+
+    // set_exception_handler never sees fatals (parse errors, exhausted memory,
+    // failed require) — those end the request silently and are the usual cause
+    // of an endpoint returning an empty body. Catch them on shutdown.
+    register_shutdown_function(function () use ($emit): void {
+        $err = error_get_last();
+        if ($err === null || !($err['type'] & (E_ERROR | E_PARSE | E_CORE_ERROR | E_COMPILE_ERROR))) {
+            return;
+        }
+        $emit('Fatal error: ' . $err['message'], [
+            'file' => $err['file'] . ':' . $err['line'],
+        ]);
     });
 }
 

index.php

@@ -1,4 +1,21 @@
-<?php /* CourseHub SPA shell — all data flows through api/ via fetch. */ ?>
+<?php
+/* CourseHub SPA shell — all data flows through api/ via fetch. */
+
+/**
+ * Version a local asset by its mtime.
+ *
+ * Browsers and CDNs (Cloudflare in front of this app) cache assets/*.css|js
+ * indefinitely otherwise, and a stale app.js against a newer shell fails hard:
+ * it grabs element IDs that no longer exist, throws before it can unhide the
+ * shell, and leaves a blank page with nothing in the markup to explain it.
+ * Stamping the mtime means a deploy is a new URL, so that can't happen.
+ */
+function asset(string $path): string
+{
+    $mtime = @filemtime(__DIR__ . '/' . $path);
+    return $path . '?v=' . ($mtime ?: '0');
+}
+?>
 <!doctype html>
 <html lang="en">
 <head>
@@ -10,7 +27,38 @@
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
 <link href="https://cdn.jsdelivr.net/npm/plyr@3.7.8/dist/plyr.css" rel="stylesheet">
-<link href="assets/style.css" rel="stylesheet">
+<link href="<?= asset('assets/style.css') ?>" rel="stylesheet">
+
+<!-- Installed before every other script so it can report failures in them
+     (including assets/app.js itself). Without it a JS error leaves the shell
+     hidden and the page simply blank, with the reason only in the console. -->
+<script>
+(function () {
+  var box = null;
+  function report(kind, detail) {
+    if (!box) {
+      box = document.createElement('pre');
+      box.id = 'boot-error';
+      box.textContent = 'CourseHub failed to start.\n\n';
+      (document.body || document.documentElement).appendChild(box);
+    }
+    box.textContent += kind + ': ' + detail + '\n';
+  }
+  // Capture phase, because resource load failures don't bubble.
+  window.addEventListener('error', function (e) {
+    var el = e.target;
+    if (el && el !== window && (el.src || el.href)) {
+      report('Failed to load', el.src || el.href);
+    } else {
+      report('Error', (e.message || e.error) +
+             ' (' + (e.filename || '?') + ':' + (e.lineno || '?') + ')');
+    }
+  }, true);
+  window.addEventListener('unhandledrejection', function (e) {
+    report('Unhandled rejection', (e.reason && e.reason.message) || e.reason);
+  });
+})();
+</script>
 </head>
 <body>
 
@@ -80,6 +128,6 @@
 
 <script src="https://cdn.jsdelivr.net/npm/plyr@3.7.8/dist/plyr.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/animejs@3.2.2/lib/anime.min.js"></script>
-<script src="assets/app.js"></script>
+<script src="<?= asset('assets/app.js') ?>"></script>
 </body>
 </html>