site: make every interactive part an explicit state machine

.github/copilot-instructions.md

@@ -14,6 +14,7 @@
 - Homepage behavior: `assets/js/index-page.js`
 - Photography page behavior: `assets/js/photo-page.js`
 - Lab loader and navigation: `assets/js/portfolio-labs.js` (lazy-imports `path-playground.js` and `lab-experiments.js`, which pull in three.js)
+- Interactive state: `assets/js/state-machine.js`. Every interactive part is an explicit machine mirrored to `<html data-<name>-state>`; `PortfolioState.snapshot()` returns them all. Read and extend the table in `docs/site/STATE.md` instead of adding booleans, timers or your own Escape/focus-trap handlers.
 
 ## CSS Layout
 

README.md

@@ -27,6 +27,7 @@ This repo is not React and is not driven by Jekyll templates in its current main
 
 - `index.html` and `photo.html` are the main live surfaces.
 - Shared shell behavior lives in `assets/js/site-shell.js`.
+- Interactive state lives in explicit state machines (`assets/js/state-machine.js`), mirrored to `<html data-<name>-state>`. See `docs/site/STATE.md` for the full table and the rules.
 - Page-specific behavior lives in:
   - `assets/js/index-page.js`
   - `assets/js/photo-page.js`
@@ -107,6 +108,7 @@ assets/
     lab-experiments.js
     lab-models.mjs
     fly-brain.js
+    state-machine.js
   vendor/
     clippyjs/
     three/

assets/js/fly-brain.js

@@ -96,18 +96,34 @@ export async function mountBrain({ stage, canvas, framing = 'hero' }) {
         state.yaw += steps[event.key];
         draw();
     });
+    // The loop runs only while the stage is on screen and the GPU context is alive; off screen it costs nothing.
+    let contextLost = false;
+    const syncLoop = () => {
+        const spin = !reduced && state.visible && !contextLost;
+        renderer.setAnimationLoop(spin ? () => {
+            if (!state.dragging) state.yaw += 0.0022;
+            draw();
+        } : null);
+    };
     new IntersectionObserver((entries) => {
         state.visible = entries[0].isIntersecting;
+        syncLoop();
     }).observe(stage);
+    canvas.addEventListener('webglcontextlost', (event) => {
+        event.preventDefault();
+        contextLost = true;
+        syncLoop();
+        stage.classList.remove('is-live');
+    });
+    canvas.addEventListener('webglcontextrestored', () => {
+        contextLost = false;
+        stage.classList.add('is-live');
+        draw();
+        syncLoop();
+    });
 
     stage.classList.add('is-live');
-    if (!reduced) {
-        renderer.setAnimationLoop(() => {
-            if (!state.visible) return;
-            if (!state.dragging) state.yaw += 0.0022;
-            draw();
-        });
-    }
+    syncLoop();
 
     return {
         // Additive blending makes black points invisible, so a region can switch off without rebuilding anything.
@@ -125,7 +141,14 @@ export async function mountBrain({ stage, canvas, framing = 'hero' }) {
 const heroStage = document.getElementById('brain-stage');
 const heroCanvas = document.getElementById('brain-canvas');
 if (heroStage && heroCanvas && 'WebGL2RenderingContext' in window) {
-    const begin = () => mountBrain({ stage: heroStage, canvas: heroCanvas }).catch(() => {});
+    // On fly101.html the poster image is the fallback, so failure only needs to be visible to tests and agents.
+    const hero = window.PortfolioState?.defineLoader('brain-hero');
+    const begin = () => {
+        hero?.send('load');
+        mountBrain({ stage: heroStage, canvas: heroCanvas })
+            .then(() => hero?.send('resolve'))
+            .catch(() => hero?.send('reject'));
+    };
     if (document.readyState === 'complete') begin();
     else window.addEventListener('load', begin, { once: true });
 }