feat/realtime

.gitignore

@@ -23,8 +23,15 @@ EXTRACTED-text-*.md
 # Generated technical reference
 /docs/jsdoc/
 
-# Fake-webcam fixtures and measurements built by scripts-dev/build-face-fixtures.cjs
-/tests/fixtures/synthetic-faces/y4m/
+# Local research videos. The small synthetic MP4 remains committed for CI.
+/tests/fixtures/*.mp4
+/tests/fixtures/*.webm
+/tests/fixtures/*.mkv
+/tests/fixtures/*.mov
+/tests/fixtures/*.m4v
+!/tests/fixtures/my-moving-face.mp4
+
+# Local measurements produced while calibrating model thresholds.
 /tests/fixtures/synthetic-faces/lab-measurements.json
 
 # scripts-dev/lab-capture.cjs render writes candidate pictures here. They are

JSDOC_index.md

@@ -1,7 +1,7 @@
 # Ghostmaxxing technical reference
 
-> Version 0.9.11  
-> Last updated: September 2026  
+> Version 0.9.11
+> Last updated: October 2026
 > Functional documentation: [use the tools and understand the results](/docs/)
 
 Ghostmaxxing is a static browser lab for testing how selected face-analysis models respond to visible interventions. This site is the generated developer reference. It documents runtime modules, functions, parameters, events, and the Ghostyle extension contract.
@@ -12,7 +12,7 @@ If you want to operate an interface, begin with the functional guides. If you ar
 
 | Question | Documentation |
 |---|---|
-| How do I use the Lab, Video Loader, Transfer, or Face Brush? | [Functional guides](/docs/) |
+| How do I use the Lab, Video Loader, Latent Space Visualizer, or Face Brush? | [Functional guides](/docs/) |
 | What does a match state, threshold, descriptor, or landmark mean? | [Understand the results](/docs/understand/) and [technical glossary](/docs/glossary/) |
 | How do I create a Ghostyle? | [Ghostyle Authoring Guide](tutorial-ghostyle-authoring.html), then [`ghostyles/00-template.js`](module-ghostyles_00-template.html) |
 | Which module, function, parameter, or event do I need? | Generated API reference in this site's sidebar |
@@ -34,7 +34,17 @@ Use it when exact media time matters more than a live webcam.
 
 Use it to explore appearance transfer. A visually successful transfer is not evidence that the target image evades recognition.
 
-`realtime.html` is not part of the initial released documentation set.
+### Latent Space Visualizer
+
+`realtime.html` loads `lab-js/realtime/realtime.js`. It captures a temporal 2D
+face-api baseline, filters frames whose 2D pose, framing, or ambient light is not
+comparable, and lets the operator mark and aggregate successive makeup steps.
+The input may be a live camera or a local video. The timeline, equalizer, and
+radial fingerprint are different views of the same descriptor-distance session.
+
+Begin with the [functional guide](/docs/guides/realtime.html), then use the
+[combined operating guide and methodology](/docs/jsdoc/tutorials/realtime) before
+interpreting the threshold, noise floor, or per-coordinate plots.
 
 ## Runtime architecture
 
@@ -53,6 +63,13 @@ lab.html
 loader.html
   └─ lab-js/loader.js
 
+realtime.html
+  └─ lab-js/realtime/realtime.js
+       ├─ realtime-capture.js (quality, temporal collectors, spike/frame buffer)
+       ├─ realtime-graph.js + realtime-radial.js
+       ├─ realtime-settings.js
+       └─ realtime-gallery.js
+
 ```
 
 ### Core state and lifecycle

README.md

@@ -1,6 +1,6 @@
 # Ghostmaxxing
 <!-- coverage-badge:start -->
-[![Unit Test Coverage](https://img.shields.io/badge/coverage-96.79%25-green)](coverage/)
+[![Unit Test Coverage](https://img.shields.io/badge/coverage-88.94%25-green)](coverage/)
 <!-- coverage-badge:end -->
 
 [![CI](https://github.com/vecna/ghostmaxxing/actions/workflows/ci.yml/badge.svg)](https://github.com/vecna/ghostmaxxing/actions/workflows/ci.yml)
@@ -76,6 +76,7 @@ npm run check              # validator + unit tests (run before proposing change
 npm run test:unit          # Vitest unit tests
 npm run test:unit -- --coverage
 npm run test:e2e           # Playwright browser tests
+npm run test:e2e:realtime  # Focused realtime camera/video workflow
 npm run docs               # generate the JSDoc site into docs/jsdoc/
 npm run validate:ghostyles # validate every ghostyle in ghostyles/
 npm run validate:ghostyle -- ghostyles/your-slug.js   # validate one

about.html

@@ -472,6 +472,7 @@ <h2>About the project</h2>
           <a href="/docs/">Technical documentation</a>
           <a href="https://github.com/vecna/ghostmaxxing">Code</a>
           <a href="/loader.html">Video Loader</a>
+          <a href="/realtime.html">Latent Space Visualizer</a>
         </div>
       </div>
     </footer>

docs-src/en/develop.body.html

@@ -22,6 +22,7 @@ <h2>Choose a starting point</h2>
                 <tr><td>Call or integrate a runtime module</td><td><a href="/docs/jsdoc/">Generated JSDoc</a></td><td><a href="https://github.com/vecna/ghostmaxxing/tree/main/lab-js"><code>lab-js/</code> source</a></td></tr>
                 <tr><td>Understand imports, pages, and events</td><td><a href="/codemap/codemap.html">Code map</a></td><td>Module headers and event-bus source</td></tr>
                 <tr><td>Use the public browser API</td><td><a href="https://github.com/vecna/ghostmaxxing/blob/main/lab-js/Ghostmaxxing.d.ts"><code>Ghostmaxxing.d.ts</code></a></td><td><code>window.gstmxx</code> in <code>main.js</code></td></tr>
+                <tr><td>Run and inspect the realtime measurement method</td><td><a href="/docs/jsdoc/tutorials/realtime">Realtime guide and methodology</a></td><td><a href="https://github.com/vecna/ghostmaxxing/tree/main/lab-js/realtime"><code>lab-js/realtime/</code> source</a></td></tr>
                 <tr><td>Regenerate or package the project</td><td><a href="/docs/maintain/">Maintainer guide</a></td><td><a href="https://github.com/vecna/ghostmaxxing/tree/main/scripts-dev"><code>scripts-dev/</code></a></td></tr>
               </tbody>
             </table>
@@ -36,14 +37,9 @@ <h2>Available interfaces</h2>
               <tbody>
                 <tr><td><code>lab.html</code></td><td><code>lab-js/main.js</code></td><td>Live camera, local baseline, 2D and mesh views, Ghostyles, composite analysis.</td></tr>
                 <tr><td><code>loader.html</code></td><td><code>lab-js/loader.js</code></td><td>Repeatable comparison of frames from a local MP4.</td></tr>
+                <tr><td><code>realtime.html</code></td><td><code>lab-js/realtime/realtime.js</code></td><td>Temporal baseline and operator-declared makeup-step measurements from a camera or local video.</td></tr>
               </tbody>
             </table>
-            <!--
-            <div class="docs-note">
-              <p>
-                <code>realtime.html</code> is not part of the initial released documentation set. Add it only when its release contract and user guide are ready.
-              </p>
-            </div> -->
           </section>
 
           <section id="lab-runtime">
@@ -58,6 +54,7 @@ <h2>Runtime modules</h2>
                 <tr><td>Mesh and visual embedding</td><td><code>mediapipe-loop.js</code>, <code>engine-3d.js</code></td><td>478-point geometry and the separate experimental ImageEmbedder path.</td></tr>
                 <tr><td>Composite feedback</td><td><code>auto-find-loop.js</code>, <code>bbox-overlay.js</code>, <code>analyze-panel.js</code></td><td>Slower modified-image pass, live scaffold, status, metrics, report text.</td></tr>
                 <tr><td>Extensions</td><td><code>ghostyles-manager.js</code>, <code>plugins3d-loader.js</code>, <code>ghostyle3d-uv-renderer.js</code></td><td>Load 2D, UV, and hybrid Ghostyles and expose their controls.</td></tr>
+                <tr><td>Realtime experiment</td><td><code>realtime.js</code>, <code>realtime-capture.js</code>, <code>realtime-graph.js</code>, <code>realtime-radial.js</code></td><td>2D-only temporal capture, comparable-condition filtering, phase timeline, and 128-value descriptor views.</td></tr>
               </tbody>
             </table>
           </section>

docs-src/en/index.body.html

@@ -33,6 +33,16 @@ <h3>Video Loader</h3>
             </div>
           </article>
 
+          <article class="docs-card">
+            <span class="docs-card__number">Tool 03 [Experimental!]</span>
+            <h3>Latent Space Visualizer</h3>
+            <p>Mark makeup steps and measure face-descriptor drift over short, comparable time windows using a camera or local video.</p>
+            <div class="docs-card__actions">
+              <a class="docs-link docs-link--primary" href="/realtime.html">Open the Visualizer &#8599;</a>
+              <a class="docs-link" href="/docs/guides/realtime.html">Read the guide</a>
+            </div>
+          </article>
+
         </div>
 
         <div class="docs-note">

docs-src/en/maintain.body.html

@@ -24,6 +24,7 @@ <h2>Implemented in <code>packages.json</code></h2>
                 <tr><td>Validate all Ghostyles</td><td><code>npm run validate:ghostyles</code></td><td>Reports errors and warnings; stops on the first failed file.</td></tr>
                 <tr><td>Run fast checks</td><td><code>npm run check</code></td><td>Validates Ghostyles, then runs unit tests.</td></tr>
                 <tr><td>Run all tests</td><td><code>npm test</code></td><td>Runs unit tests, then Playwright end-to-end tests.</td></tr>
+                <tr><td>Test the realtime workflow</td><td><code>npm run test:e2e:realtime</code></td><td>Runs the focused Chromium suite, including local-video upload and declared-step measurement.</td></tr>
                 <tr><td>Build architecture map</td><td><code>npm run codemap</code></td><td>Writes the JSON graph and standalone HTML viewer.</td></tr>
                 <tr><td>Extract translations</td><td><code>npm run i18n:extract</code></td><td>Overwrites POT and pipe-delimited summary files.</td></tr>
               </tbody>

docs-src/en/pages.json

@@ -21,6 +21,13 @@
     "description": "Use a local MP4 and exact timestamps to record and compare faces with the Ghostmaxxing Video Loader.",
     "section": "tools"
   },
+  {
+    "source": "realtime.body.html",
+    "output": "docs/guides/realtime.html",
+    "title": "Measure a makeup session over time — Ghostmaxxing",
+    "description": "Capture a temporal baseline, mark makeup steps, and inspect local face-descriptor drift with the Ghostmaxxing Latent Space Visualizer.",
+    "section": "tools"
+  },
   {
     "source": "face-brush.body.html",
     "output": "docs/guides/face-brush.html",

docs-src/en/realtime.body.html

@@ -0,0 +1,88 @@
+      <section class="content-page__header-area gm-prose" aria-labelledby="realtime-guide-title">
+        <span class="content-page__kicker">Functional guide · Latent Space Visualizer</span>
+        <h1 id="realtime-guide-title">Measure a makeup session over time.</h1>
+        <p class="content-page__lead">Capture a clean baseline, mark each application interval, and aggregate the descriptor change after every finished step.</p>
+        <p class="content-page__deck">The visualizer uses only the 2D face-api/dlib path. It excludes sufficiently different pose, framing, and ambient-light frames; it does not mathematically correct them or predict another recognition system.</p>
+        <div class="content-page__actions">
+          <a class="docs-link docs-link--primary" href="/realtime.html">Open the Visualizer &#8599;</a>
+          <a class="docs-link" href="/docs/jsdoc/tutorials/realtime">Read how it works and why</a>
+        </div>
+      </section>
+
+      <div class="docs-reader">
+        <article class="docs-article gm-prose">
+          <section id="source">
+            <span class="docs-eyebrow">Input</span>
+            <h2>Use the camera or a local video.</h2>
+            <p>The camera is the default. Open <strong>Source</strong> to select a local video; the file remains on this device and can be paused, sought, and replayed. Changing source invalidates the current baseline.</p>
+            <div class="docs-note"><p><strong>Source → Brightness</strong> changes only how bright the video looks on screen. The model reads the original video pixels, so this control cannot improve lighting or change a measurement.</p></div>
+          </section>
+
+          <section id="procedure">
+            <span class="docs-eyebrow">Session workflow</span>
+            <h2>Baseline, application, measurement.</h2>
+            <div class="docs-step-list">
+              <div class="docs-step"><span class="docs-step__number">01</span><div><h3>Set the baseline</h3><p>Use a neutral frontal pose and stable light, then press <strong>Set baseline</strong>. Hold still and follow the centre target while five accepted samples are distributed across at least two seconds.</p></div></div>
+              <div class="docs-step"><span class="docs-step__number">02</span><div><h3>Start one makeup step</h3><p>Press <strong>Start makeup step</strong> before applying one change. The timeline marks the event and shades the application interval.</p></div></div>
+              <div class="docs-step"><span class="docs-step__number">03</span><div><h3>Return to comparable conditions</h3><p>Finish the change, then return to the baseline pose, framing, and room light. Leaving the frame during application produces a marked no-face interval without an invented distance line.</p></div></div>
+              <div class="docs-step"><span class="docs-step__number">04</span><div><h3>Measure the step</h3><p>Press <strong>Measure this step</strong> and hold still. Eight comparable frames over at least three seconds become one temporal snapshot.</p></div></div>
+              <div class="docs-step"><span class="docs-step__number">05</span><div><h3>Read and repeat</h3><p>Record the distance, baseline noise floor, and step temporal spread together. Use <strong>Start next step</strong> for the next cumulative change.</p></div></div>
+            </div>
+          </section>
+
+          <section id="exclusions">
+            <span class="docs-eyebrow">Nuisance control</span>
+            <h2>Different pose and light are omitted, not normalised.</h2>
+            <p>Baseline capture checks confidence, scale, framing, 2D roll/yaw, and face-crop exposure. After makeup starts, confidence and face-crop exposure may legitimately change, so they no longer reject a frame. Scale, framing, roll, and yaw still apply, followed by a comparison with the baseline's averaged 2D conditions and ambient luminance outside the face box.</p>
+            <div class="docs-warning"><p>The gate reduces obvious confounds; it cannot prove that makeup caused the remaining distance. It does not estimate pitch and cannot separate every intervention from every shadow.</p></div>
+          </section>
+
+          <section id="views">
+            <span class="docs-eyebrow">Feedback</span>
+            <h2>Read the trace and the 128-value fingerprints.</h2>
+            <table>
+              <thead><tr><th>View</th><th>What it shows</th><th>Do not infer</th></tr></thead>
+              <tbody>
+                <tr><td><strong>Distance timeline</strong></td><td>Smoothed live distance, gaps, phase backgrounds, event lines, measured noise floor, and the cited 0.60 dlib reference.</td><td>That the space between the two reference lines has a calibrated meaning.</td></tr>
+                <tr><td><strong>Equalizer</strong></td><td>Absolute change for each of 128 descriptor coordinates.</td><td>That one row corresponds to a facial region.</td></tr>
+                <tr><td><strong>Radial distribution</strong></td><td>All 128 deltas sorted into 16 ranked RMS bands, with the live reading as an outline and the latest measured step as a filled shape.</td><td>That a spoke or direction identifies a makeup line, cheek, or eyebrow.</td></tr>
+                <tr><td><strong>Step capture</strong></td><td>The sharpest accepted frame from the measurement window, watermarked with local result metadata.</td><td>That one model-local result transfers to a deployed system.</td></tr>
+              </tbody>
+            </table>
+          </section>
+
+          <section id="video">
+            <span class="docs-eyebrow">Recorded sessions</span>
+            <h2>Use video as a repeatable fixture.</h2>
+            <p>Local-video event labels include media time. Pause or seek to inspect the recording, then mark application and measurement moments. Starting either interval resumes a paused video so the temporal collector does not repeatedly inspect one frozen frame.</p>
+          </section>
+
+          <section id="privacy">
+            <span class="docs-eyebrow">Data</span>
+            <h2>Local does not mean insignificant.</h2>
+            <ul>
+              <li>Camera baselines persist in localStorage; local-video baselines exist only for the current page session.</li>
+              <li>Manual, sustained-spike, and declared-step JPEG captures use browser IndexedDB.</li>
+              <li>The selected video is neither uploaded nor persisted by the page.</li>
+              <li><strong>Delete baseline</strong> does not erase the gallery. Delete captures separately when they are no longer needed.</li>
+            </ul>
+          </section>
+
+          <nav class="docs-next" aria-label="Continue reading">
+            <a class="docs-link" href="/docs/">&#8592; Documentation home</a>
+            <a class="docs-link" href="/docs/understand/">Next: understand the results &#8594;</a>
+          </nav>
+        </article>
+
+        <aside class="docs-toc">
+          <h2>On this page</h2>
+          <nav>
+            <a href="#source">Choose a source</a>
+            <a href="#procedure">Session workflow</a>
+            <a href="#exclusions">Excluded frames</a>
+            <a href="#views">Feedback views</a>
+            <a href="#video">Recorded sessions</a>
+            <a href="#privacy">Local data</a>
+          </nav>
+        </aside>
+      </div>

fediverse.html

@@ -407,6 +407,7 @@ <h2>On this page</h2>
           <a href="/docs/">Technical documentation</a>
           <a href="https://github.com/vecna/ghostmaxxing">Code</a>
           <a href="/loader.html">Video Loader</a>
+          <a href="/realtime.html">Latent Space Visualizer</a>
         </div>
       </div>
     </footer>

genealogy.html

@@ -1099,6 +1099,7 @@ <h2 class="gen-row__title">Wearable readers</h2>
         <a href="/docs/">Technical documentation</a>
         <a href="https://github.com/vecna/ghostmaxxing">Code</a>
         <a href="/loader.html">Video Loader</a>
+        <a href="/realtime.html">Latent Space Visualizer</a>
       </div>
     </div>
   </footer>

index.html

@@ -542,6 +542,7 @@ <h2 class="story__title" id="storyTitle">Disrupt Face Recognition, one Ghostyle
           <a href="/docs/">Technical documentation</a>
           <a href="https://github.com/vecna/ghostmaxxing">Code</a>
           <a href="/loader.html">Video Loader</a>
+          <a href="/realtime.html">Latent Space Visualizer</a>
         </div>
       </div>
     </footer>