feat(cnn_v3/tools): embed default weights in HTML tool; add --html export flag

- cnn_v3/tools/weights.js: new file — base64-encoded cnn_v3_weights.bin +
  cnn_v3_film_mlp.bin; loaded at startup so the tool works without dropping files
- tester.js: preload() falls back to embedded weights.js constants when fetch
  fails; logs "Loaded embedded" vs "Preloaded" to distinguish the two paths
- index.html: load weights.js before tester.js
- export_cnn_v3_weights.py: add --html / --html-output flags that call
  update_weights_js() to regenerate weights.js after a training run
- HOW_TO_CNN.md: update pipeline diagram, §3 export commands, §7 HTML tool
  section (file table, workflow, weights.js description), Appendix A

handoff(Gemini): weights.js now the canonical source for HTML tool defaults;
regenerate with `uv run export_cnn_v3_weights.py <ckpt> --output ... --html`

1 files changed, 28 insertions, 0 deletions

diff --git a/cnn_v3/training/export_cnn_v3_weights.py b/cnn_v3/training/export_cnn_v3_weights.py
index 99f3a81..edf76e2 100644
--- a/cnn_v3/training/export_cnn_v3_weights.py
+++ b/cnn_v3/training/export_cnn_v3_weights.py
@@ -31,6 +31,7 @@ Usage
 """
 
 import argparse
+import base64
 import struct
 import sys
 from pathlib import Path
@@ -158,13 +159,40 @@ def export_weights(checkpoint_path: str, output_dir: str) -> None:
     print(f"\nDone → {out}/")
 
 
+_WEIGHTS_JS_DEFAULT = Path(__file__).parent.parent / 'tools' / 'weights.js'
+
+
+def update_weights_js(weights_bin: Path, film_mlp_bin: Path,
+                      js_path: Path = _WEIGHTS_JS_DEFAULT) -> None:
+    """Encode both .bin files as base64 and write cnn_v3/tools/weights.js."""
+    w_b64 = base64.b64encode(weights_bin.read_bytes()).decode('ascii')
+    f_b64 = base64.b64encode(film_mlp_bin.read_bytes()).decode('ascii')
+    js_path.write_text(
+        "'use strict';\n"
+        "// Auto-generated by export_cnn_v3_weights.py --html  — do not edit by hand.\n"
+        f"const CNN_V3_WEIGHTS_B64='{w_b64}';\n"
+        f"const CNN_V3_FILM_MLP_B64='{f_b64}';\n"
+    )
+    print(f"\nweights.js  →  {js_path}")
+    print(f"  CNN_V3_WEIGHTS_B64   {len(w_b64)} chars  ({weights_bin.stat().st_size} bytes)")
+    print(f"  CNN_V3_FILM_MLP_B64  {len(f_b64)} chars  ({film_mlp_bin.stat().st_size} bytes)")
+
+
 def main() -> None:
     p = argparse.ArgumentParser(description='Export CNN v3 trained weights to .bin')
     p.add_argument('checkpoint', help='Path to .pth checkpoint file')
     p.add_argument('--output', default='export',
                    help='Output directory (default: export/)')
+    p.add_argument('--html', action='store_true',
+                   help=f'Also update {_WEIGHTS_JS_DEFAULT} with base64-encoded weights')
+    p.add_argument('--html-output', default=None, metavar='PATH',
+                   help='Override default weights.js path (implies --html)')
     args = p.parse_args()
     export_weights(args.checkpoint, args.output)
+    if args.html or args.html_output:
+        out = Path(args.output)
+        js_path = Path(args.html_output) if args.html_output else _WEIGHTS_JS_DEFAULT
+        update_weights_js(out / 'cnn_v3_weights.bin', out / 'cnn_v3_film_mlp.bin', js_path)
 
 
 if __name__ == '__main__':