77 lines
2.5 KiB
Markdown
77 lines
2.5 KiB
Markdown
|
# frontend
|
||
|
|
|
||
|
|
The ClojureScript half. See `docs/port-plan.md` for what is being built and in
|
||
|
|
what order; this file is only how to run it.
|
||
|
|
|
||
|
|
## Once
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mise install # from the REPO ROOT: java 21+, node 20, clojure, python
|
||
|
|
cd frontend && npm install
|
||
|
|
```
|
||
|
|
|
||
|
|
`java` must be 21+. On an older JDK shadow-cljs fails with "CompilerOptions has
|
||
|
|
been compiled by a more recent version of the Java Runtime", which reads like a
|
||
|
|
shadow-cljs bug and is not one. `mise install` is what prevents it.
|
||
|
|
|
||
|
|
## The tests
|
||
|
|
|
||
|
|
```sh
|
||
|
|
cd frontend && npm test
|
||
|
|
```
|
||
|
|
|
||
|
|
That is three things in order: regenerate the JS oracle's answers, compile the
|
||
|
|
`:test` build, run it under node.
|
||
|
|
|
||
|
|
```
|
||
|
|
node test/parity/oracle.mjs # drives js/ and writes test/parity/oracle.json
|
||
|
|
shadow-cljs compile test
|
||
|
|
node out/node-tests.js
|
||
|
|
```
|
||
|
|
|
||
|
|
Run them separately if a compile error is in the way. The oracle JSON is
|
||
|
|
generated, not committed.
|
||
|
|
|
||
|
|
## The app
|
||
|
|
|
||
|
|
```sh
|
||
|
|
cd frontend && npx shadow-cljs watch app
|
||
|
|
```
|
||
|
|
|
||
|
|
Then open **<http://localhost:8778/index.html>** — with the `/index.html`, not
|
||
|
|
bare `/`. This shadow-cljs does no directory-index resolution, so `/` is a 404
|
||
|
|
whatever the roots are.
|
||
|
|
|
||
|
|
Through step 1 the page is a placeholder on purpose: there is nothing to render
|
||
|
|
until the data model exists, and a shell built before the model is a shell built
|
||
|
|
around a guess. Something moves on screen at step 2.
|
||
|
|
|
||
|
|
Port 8778 is deliberately not 8777. `python3 serve.py` from the repo root still
|
||
|
|
runs the old JS tool on 8777, and the two are meant to run side by side — that is
|
||
|
|
the whole reason `js/` is still in the tree.
|
||
|
|
|
||
|
|
From step 9 Django serves the page and `:dev-http` goes away.
|
||
|
|
|
||
|
|
## The oracle
|
||
|
|
|
||
|
|
`js/` is the numeric oracle, not dead weight. `test/parity/` runs both
|
||
|
|
implementations on the same synthetic track and diffs them: `fit-similarity` and
|
||
|
|
`procrustes-mean` agree to 1e-9, the raster pixel-for-pixel.
|
||
|
|
|
||
|
|
Both sides get the identical track because `js/synth.js` reads `Math.random` at
|
||
|
|
call time, so `oracle.mjs` stubs it to a constant and the CLJS side passes
|
||
|
|
`:rand-fn (constantly 0.5)`. `js/` itself is never modified.
|
||
|
|
|
||
|
|
**`test/parity/` and `arthur.parity-test` get deleted in one commit at step 5.**
|
||
|
|
A parity test pins behaviour while code moves; keeping it afterwards would bake
|
||
|
|
the prototype's mistakes into the rewrite and make them permanent.
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```
|
||
|
|
src/arthur/domain/ pure. No re-frame, no DOM, no flow/.
|
||
|
|
test/arthur/synth.cljs the synthetic track — test infrastructure, not src
|
||
|
|
test/parity/ the JS oracle harness. Deletable at step 5.
|
||
|
|
public/index.html dev host page. Django replaces it at step 9.
|
||
|
|
```
|