942e2f38ab
`stabilize` is three things wearing one name, and it is now three functions in two stages: `flow/measure/anchor` fits the rigid transform, `flow/condition` smooths its parameters, `flow/measure/mouth` measures the lip rings through the result. Parity is on the COMPOSITION and not on the pieces -- a split that agreed function by function and not end to end would be a split rather than a port. The oracle now drives `stabilize` at three configurations and the port agrees to 1e-9 on ref, rigid, transforms, outer, inner and aperture, plus `smoothContours` at three radii. Two of the three configurations are at aspect 0.5625, a 1080x1920 phone clip, because at aspect 1 `pick` is the identity: a port that dropped the anisotropy correction outright would pass every other assertion in the suite. 148 tests, up from 134. Three decisions worth the reading time. `makeXform` is not ported, and its absence takes the face oval with it. It centres on the oval's bounding box and zooms until the face is 80% of the raster height, so every vertex it touched carried a cropping decision made once, at analysis time, from one frame's landmarks. Geometry belongs in the node's own local space with the framing as a transform on a node, so this is a deletion. The oval's only other consumer was the placeholder plate outline, which is painting. The residual is taken against the RAW fit, and the prototype took it against the smoothed one. That is the only deliberate numeric divergence here, and parity is kept by asserting `anchor/residuals` on exactly what the prototype handed it. The number's job is to say whether a section is stabilisable at all; folding the smoothing error into it makes a slider look like a property of the footage, and docs/architecture.md lists the residual under stage 3, which requires it to be knob-free. `condition/anchor` therefore replaces `:transforms` and leaves `:residual` alone. The stage order is not the strict chain the table in docs/architecture.md looks like, and that document now says so. The fit is knob-free, conditioning smooths it, and the rings are measured *through* the conditioned transform -- so `anchor avg` does re-run the ring mapping, which is a few hundred frames of twenty points. The guarantee was only ever about the part that reads a source pixel, and that part never sees a transform. Two things fall out and are asserted rather than assumed. Smoothing and subsampling commute, because both are per-slot, which is what lets `vertices` stay a stage-5 knob downstream of a stage-4 one -- and it is also why the port can smooth the full twenty slots where the prototype smooths eight and still match. And `condition/contours` is `geom/moving-average` per vertex per axis rather than its own clamped window, so "radius 2" cannot come to mean two different things at the two knobs. One dead end recorded so nobody walks it twice: the synth's head is perfectly rigid -- its jitter is a whole-head translation, which a similarity absorbs exactly -- so every frame's rigid configuration is congruent with frame zero's and the Procrustes mean IS frame zero to 1e-15, jitter or none. "The reference is the mean and not frame zero" cannot be asserted on this track and is asserted in geom-test, where the two can differ. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
122 lines
5.2 KiB
Markdown
122 lines
5.2 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.
|
|
|
|
**Run them through `mise`**, or make sure `mise`'s node is first on PATH. The
|
|
oracle imports `js/*.js` directly, and those are ES modules in a directory with
|
|
no `package.json`, so node needs the module detection that became default in
|
|
20.19. On an older node 20 — an nvm install shadowing the pinned one is the easy
|
|
way to get there — every import fails with "Named export not found ... is a
|
|
CommonJS module", which reads like the oracle being broken and is not.
|
|
|
|
## 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.
|
|
|
|
The page is the hand-written scene from step 2, scrubbed by hand. There is
|
|
deliberately no clock: the audio clock, the rAF loop, the `::resolver`
|
|
subscription and the transport are step 3, and the question this step answers is
|
|
whether the data model evaluates correctly, not whether it evaluates at 30fps.
|
|
A scrubber answers the first and nothing else, which is what makes a failure
|
|
here unambiguous.
|
|
|
|
The scene itself is `src/arthur/demo/scene.edn`, and it is not a face. It is the
|
|
smallest scene that exercises every mechanism the model claims to have —
|
|
inherited exposure, a sparse held `[:xform :pos]`, composition through a group,
|
|
rotation about an anchor, a stencil chain, a keyed `[:vis]`, a `:span`, and
|
|
fractional z among siblings — chosen so that each one is visible when it breaks.
|
|
|
|
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, and `stabilize`'s
|
|
whole output agrees across the three namespaces it was split into.
|
|
|
|
The oracle drives `stabilize` at aspect 0.5625 as well as at 1. Aspect 1 makes the
|
|
anisotropy correction the identity, so a port that dropped it entirely would pass
|
|
— which is the one thing a parity suite on normalised landmarks can be blind to.
|
|
|
|
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/.
|
|
src/arthur/flow/ the stages. `(f params inputs) -> output`, no state.
|
|
src/arthur/demo.cljs the hand-written scene, read from demo/scene.edn
|
|
src/arthur/ui/canvas.cljs the one imperative sink — the only DOM canvas call
|
|
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.
|
|
```
|
|
|
|
## Two evaluators, on purpose
|
|
|
|
`domain/scene` has both `eval-frame` and `resolver`, and they are not
|
|
alternatives:
|
|
|
|
- **`(eval-frame scene f store)`** is the specification. Allocating, order-free,
|
|
obviously correct. Tests and one-off renders use it.
|
|
- **`(resolver scene store)` -> `(fn [f] ops)`** is what playback uses. It caches
|
|
the topological order and the z paths, holds a cursor per channel and reuses
|
|
one point buffer per node, so a frame allocates the op maps and nothing else.
|
|
|
|
Both run the same walk, parameterised by how a channel is read and where its
|
|
points are written — two independent implementations of frame evaluation would
|
|
drift, and the drift would look like a rendering bug rather than like two
|
|
functions disagreeing. What differs between them is exactly the part that can be
|
|
wrong, and `scene-test` asserts they agree frame for frame in forward, backward
|
|
and random order.
|
|
|
|
Because the resolver reuses its buffers, **ops must be rasterised before the
|
|
next frame is asked for.** That is the contract the rAF loop wants anyway: it
|
|
reads, blits, and dispatches nothing.
|