dancer

A realtime, procedural dancing agent: it listens to music it has never heard, maintains a hierarchical belief about the metre with calibrated precision, and drives a body that moves before the beat, commits to long moves only when it is sure, and hedges when it is not.

The research roadmap is docs/BLUE_SKY_PLAN.md; per-layer designs are in docs/plans/. This branch is executing the engineering-only tier, whose build order is docs/plans/T1_IMPLEMENTATION.md.

Layout

packages/core/     @dancer/core: pure TypeScript, no DOM, runs in Node and the browser
  src/time         sample clocks and frame-rate constants
  src/rng          seeded RNG; nothing in the system calls Math.random
  src/types        the contracts every layer speaks
  src/sim          Score -> ground truth, activations and audio (the test oracle)
  src/metrics      every metric in the gate, as pure functions over traces
  src/replay       recorder, replayer, canonical hashing
  src/ears         DSP features and the BEAST adapter
  src/pulse        templates, bar-pointer filter, PIPPET phase filter
  src/form         bars, phrases, sections, drop forecasting, repeat memory
  src/feel         energy, syncopation, groove, urge to move
  src/choreo       motif library and planner
  src/body         phase-time motion, retiming, layered limbs
  bench/           the frozen gate: cases, thresholds.json, NOTES.md
apps/web/          Vite + React + three.js live app
research/          optional Python: oracles, ONNX provenance
stimuli/           generated test audio (not committed)

Commands

npm run monitor    # the live pulse monitor at http://localhost:5173
npm run gate       # typecheck + tests + bench. Run before every commit.
npm test           # unit tests only
npm run bench      # the gate cases and their thresholds
npm run stimuli    # render the stimulus set to stimuli/*.wav
npm run fixtures   # cache real-ONNX activations for the S12 stimuli
npm run replay -- recording.json

Hearing it

npm run monitor opens a page that runs Ears and Pulse on live audio - microphone, tab audio, or a file - and schedules a click on the predicted beat, ahead of real time. If the belief is right the click fuses with the music; if it is wrong you know instantly, which no number on a panel tells you as quickly.

Three synthetic tracks with exact ground truth are built in. Start with those: you know what the answer is, so you can tell a problem with the system from a problem with the track.

What to look for:

• lock in two to four beats, and the click sitting inside the kick rather than beside it
• talking over the music or waving a hand at the microphone should not move the belief at all
• a real tempo change should take four or five beats to absorb, the way a person does
• through a breakdown the mode should read coasting and the click should keep going

Rules that are not negotiable

1. The gate is frozen. Thresholds live in packages/core/bench/thresholds.json. Nothing here may lower one, widen a tolerance or skip a case. If a threshold looks wrong, the argument goes in packages/core/bench/NOTES.md and the case stays red until a human changes it.
2. Determinism is a feature. All randomness goes through an injected seeded RNG. Two runs with the same inputs and seed produce byte-identical output.
3. Evidence is counted once. Overlapping-window model outputs are never fed to a filter as independent observations. This is what the old tracker got wrong.
4. The future is never read from the file. In player mode the page knows the upcoming audio; the live path must not touch it. It is an evaluation oracle only.
5. Estimates come with precision. No layer emits a bare number: every predicted time carries a standard deviation, every label a distribution.