Where to start?
| If you need to | Start with | Then inspect |
|---|---|---|
| Create or modify a Ghostyle | Ghostyle Authoring Guide | ghostyles/00-template.js |
| Call or integrate a runtime module | Generated JSDoc | lab-js/ source |
| Understand imports, pages, and events | Code map | Module headers and event-bus source |
| Use the public browser API | Ghostmaxxing.d.ts | window.gstmxx in main.js |
| Regenerate or package the project | Maintainer guide | scripts-dev/ |
Currently available webapp.
a few others are in development, but now it matters more to gain feedback.| Page | Controller | Functional role |
|---|---|---|
lab.html | lab-js/main.js | Live camera, local baseline, 2D and mesh views, Ghostyles, composite analysis. |
loader.html | lab-js/loader.js | Repeatable comparison of frames from a local MP4. |
The controller coordinates specialised modules.
| Area | Primary modules | Responsibility |
|---|---|---|
| State and lifecycle | main.js, state.js, config.js | Initialisation, thresholds, shared state, public API, gstmxxReady. |
| Camera and persistence | camera.js, db.js | Media stream, short recording, local saved-face records. |
| 2D analysis | engine.js, landmark-analysis.js | Detection, 68 landmarks, face descriptors, distance, result classification. |
| Mesh and visual embedding | mediapipe-loop.js, engine-3d.js | 478-point geometry and the separate experimental ImageEmbedder path. |
| Composite feedback | auto-find-loop.js, bbox-overlay.js, analyze-panel.js | Slower modified-image pass, live scaffold, status, metrics, report text. |
| Extensions | ghostyles-manager.js, plugins3d-loader.js, ghostyle3d-uv-renderer.js | Load 2D, UV, and hybrid Ghostyles and expose their controls. |
Capabilities come from exports.
A Ghostyle is an ES module listed in ghostyles.json. Runtime capability is detected from exported functions, not from descriptive header tags.
| Export | Capability | Runtime constraint |
|---|---|---|
onDraw(ctx, landmarks, box) | 2D canvas intervention anchored to face-api geometry. | Runs on the rendering hot path. Keep it synchronous and guard missing landmarks. |
paintUV(...) | Texture painting for the MediaPipe mesh and UV renderer. | Use the renderer contract documented by the template and generated API. |
onInit() | Optional setup. | Pair resource allocation with cleanup. |
onClear(ctx) | Optional cleanup when the effect is cleared. | Remove listeners and reset owned state. |
params | Optional parameter controls for supported plugin paths. | Keep defaults deterministic and labels intelligible. |
The header between ==Ghostyle== and ==/Ghostyle== records name, description, authorship, version, licence, technique, supported paths, regions, evidence, and references. The current validator checks only part of that editorial policy. Passing validation is not proof that every recommended field is present.
npm run validate:ghostyle -- ghostyles/your-ghostyle.jsKeep live tracking and composite evidence separate.
The live scaffold follows the unmodified camera frame for responsive visual feedback. The auto-find loop re-runs analysis on the Ghostyle composite at a slower cadence. Pointing both displays at one image would conflate two questions: “where is the face now?” and “what did the modified image do to the comparison?”
When changing either path, test the no-Ghostyle baseline, one 2D effect, one UV effect, detector absence, a matched descriptor, and a disagreement between the face-api and experimental ImageEmbedder paths.
Documentation sources and generated output.
| Layer | Source | Audience |
|---|---|---|
| Functional guides | docs-src/en/*.body.html | People using a released interface. Translatable. |
| Technical orientation | JSDOC_index.md and JSDoc tutorials | Contributors choosing an entry point or learning a contract. |
| API reference | JSDoc comments in source | Developers inspecting modules, functions, parameters, and events. |
| Maintainer operations | scripts-dev/README.md | People regenerating, validating, or packaging the project. |
Do not place functional instructions only inside generated API pages. Do not duplicate complete symbol reference in the functional guide. Link across layers using stable terms and routes.