@kieransimkin/dance-rudiments 0.2.4 → 0.3.0

package/AGENTS.md

@@ -7,3 +7,19 @@
 - Keep credentials, account data, private media and rights records out of source, fixtures, logs and packages. Use synthetic fixtures or explicitly authorised public examples and preserve their provenance/licences.
 - Use [CONTRIBUTING.md](CONTRIBUTING.md) for review. Maintainers publish accepted, validated improvements as a fresh matching GitHub release and verify configured registry destinations. Preserve existing tags and release assets; publication and deployment remain subject to applicable authorisation.
 - Website: https://kieransimkin.co.uk/danceflow/
+
+## Keep README documentation current
+
+- Whenever a feature is added or changed, update the relevant README.md in the same change to reflect the resulting behaviour. This applies to every feature addition or modification, including APIs, commands, configuration, defaults, integrations and removals.
+- Update affected feature descriptions, usage instructions, options, examples and limitations. For tools or packages with their own README.md, update that README as well as the repository README when its overview or usage is affected.
+- Check the README against the implemented and verified behaviour before committing, opening or merging a PR, publishing a release or handing off the work. A feature change is incomplete until its README documentation is current; a changelog or other documentation does not replace this requirement.
+
+## Released viewers and coordinated CI/CD
+
+- Read [docs/released-viewers.md](docs/released-viewers.md) before changing dependency, build or release behaviour. The sibling layout is `DanceRudiments/`, `react-timeline-sequence/`, and `stemlab/` under one parent.
+- Release the two companions first (React Timeline Sequence, then DanceRudiments), verify their configured publication workflows and public registries, then synchronize/rebuild/test/release StemLab. A merge or tag alone is not a verified release.
+- StemLab must target the **latest stable official releases**. No unreleased main commit, mutable development override, local `file:` archive or vendor package may substitute for a missing release. Latest is resolved before the build and locked to exact published versions, release commits and registry hashes for that run; fail visibly on stale or incompatible dependencies rather than falling back silently.
+- Use the canonical `stemlab/scripts/Release-DanceFlow.ps1` coordinator from the shared parent directory. Preview first; `-Execute` explicitly performs scoped commits, normal pushes and fresh tags; `-Resume` must preserve source identities and existing tags/assets. Never force-push, move release tags, commit unrelated work, bypass failed checks or change approvals/protections/credentials to manufacture a pass.
+- Update this repository's README.md and AGENTS.md in the same change whenever release policy, dependency rules, automation, commands, controls or validation change. Keep relevant package/feature READMEs current too. A separate guide or changelog does not replace the root README update.
+- Preserve the master-plus-drums/percussion beat-routing contract, 64-pips-per-beat native recording clock, per-dimension bars and combined waveform/spectrogram lanes. New UI features must be supplied by released shared APIs and genuinely rebuilt frontend assets, not copied engines or marker strings.
+- Distinguish source CI, package publication, full-song inference, browser/audio QA, artifact packaging, actual Pages deployment and live URL/audio verification. Keep all four Arcadians pages together; do not report unexecuted, skipped or older-commit checks as success. CI playback evidence is not subjective listening QA.

package/README.md

@@ -24,7 +24,9 @@ Project website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co
 
 ## ▶ Try the pattern visualizer
 
-**[Download the self-contained visualizer — HTML](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)**
+**[▶ Open the movement visualiser](https://kieransimkin.github.io/DanceRudiments/)**
+
+[Download the self-contained HTML for offline use](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
 
 Save the file and open it in a browser. **No install, server, CDN, soundfont or
 separate WASM file is required.** The complete 1,731-movement catalogue includes a
@@ -41,13 +43,13 @@ The downloadable file is the checked-in snapshot; the **Pattern visualizer**
 workflow also rebuilds a fresh version from every pushed native catalogue.
 [Beat player, rebuilding, release downloads and optional live hosting](docs/midi-harness.md).
 
-[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
+[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://kieransimkin.github.io/DanceRudiments/)
 
 *Captured from the running C++/WebAssembly visualizer at beat 2.75. Audio was not started during this screenshot.*
 
 
 
-DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every sampler wraps positive or negative input into its own loop before sampling.
+DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every legacy pattern sampler wraps positive or negative input into its own loop before sampling.
 
 Outputs are dimensionless offsets, normally in `[-1, 1]`. The caller chooses pixels, CSS units, metres, or another scale. There is deliberately no time interpolation in the public API: renderers advance with integer pips and get one exact sample per pip.
 
@@ -87,6 +89,33 @@ python tools/build_default_catalogue.py --check
 The release workflow builds the complete native catalogue demo plus an offline,
 audio-enabled 68-rhythm / 16-mapping comparison page. All live motion comes from C++/WASM.
 
+## BPM-synchronised N-dimensional recordings and comparison harness
+
+The additive `dancerudiments.recording` format stores **any number of named
+float64 dimensions** at **64 pips per beat**, with a mandatory BPM estimate or
+confirmed value and separate beat-phase provenance. `SampledRecording` provides
+native non-looping C++/Python playback, including captures beyond the old
+65,535-pip loop length; existing XYZ patterns and their wrapping rules are unchanged.
+
+```python
+from dancerudiments_authoring import load_recording
+from dancerudiments_authoring.harness import build_recording_harness
+r = load_recording("output/recordings/audio_recording.json")
+values = r.to_native().sample(r.clock.start_pip)  # every dimension, real C++
+build_recording_harness([r], "output/index.html")
+```
+
+The exported page uses **the same packaged visualizer assets as catalogue/release
+pages**, with native WASM sampling, shared transport, four-card comparison and
+review import/export. Recording mode adds arbitrary-axis X/Y/Z selection, locked
+BPM/origin and non-looping completion. The tiny generic WASM sampler is bundled;
+no compiler or CDN is needed at export time. StemLab's `record-rudiment` and
+`generate-batch` produce individual or varied stem/filter combinations using this
+API without copying it. Music is not bundled unless explicitly requested.
+
+See **[recording format, harness, native API and compatibility](docs/recordings.md)**.
+Build the updated source to use this unreleased API; earlier releases lack it.
+
 ## Curve and event authoring
 
 The optional **Python authoring tools** compile LFOs, segmented curves, sampled
@@ -152,7 +181,7 @@ another movement implementation. The examples below are checked into
 | TypeScript / JavaScript | `catalogue` (an array, not a function) | `sample(name, pip)` after `bindNative()` | `info.periodPips` | Call the custom bank's `dispose()` |
 
 **One beat is 64 pips.** Supply a signed 32-bit integer, not milliseconds or a
-floating-point beat number. Every sampler wraps negative as well as positive
+floating-point beat number. Every legacy pattern sampler wraps negative as well as positive
 positions into its own loop. Offsets are `{x, y, z}`, dimensionless and bounded to
 `[-1, 1]`; choose the pixel/metre scale in your application. There is no automatic
 interpolation, BPM detection or audio playback inside a binding.
@@ -530,3 +559,56 @@ Apply an output to a bounded subject. DanceRudiments changes position only; it m
 ## Troubleshooting history
 
 See [build and release troubleshooting](docs/troubleshooting.md) for prior failures, causes and fixes.
+
+### Switch the shared visualizer between trajectories and bars
+
+Use **Movement view → X–Y plot / Bar graph**. Bar view uses the same native
+C++/WebAssembly sample and the existing clock, shows **every dimension** as a
+separate signed bar, and keeps comparison cards on one common scale. Switching
+views does not interrupt playback or change the underlying recording. The
+selection is local to your browser; long dimension sets scroll horizontally.
+This applies to catalogue/release pages and recording harnesses exported by
+StemLab. Rebuild old generated pages to include the control. See
+[recording visualizer controls](docs/recordings.md#trajectory-or-all-dimension-bars).
+
+
+## Coordinated releases and latest-release dependencies
+
+Keep `DanceRudiments`, `react-timeline-sequence`, and `stemlab` as sibling
+checkouts. The release order is **React Timeline Sequence → DanceRudiments →
+StemLab**: publish and verify the companions before updating the consuming app.
+StemLab must use their **latest stable official releases**, not an unreleased
+commit, sibling source package or vendored npm archive. Each build records exact
+released versions/commits/integrity after latest-release resolution so all its
+jobs use the same bytes; CI fails clearly when that snapshot is stale.
+
+From the parent folder, preview and then explicitly execute:
+
+```powershell
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot .
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot . -Execute
+```
+
+For the first migration use the same commands with
+`.\release-kit\Release-DanceFlow.ps1` after extracting the complete kit. It
+applies the three repository patches, updates versions, performs scoped commits
+and normal pushes, waits for exact-commit CI, then creates **new** release tags.
+The existing GitHub Actions workflows publish packages; no protection rules,
+credentials, old tags or assets are changed. The initial expected next-minor
+versions are only a preview proposal, never a claim that they are published.
+
+Use Node.js 24, Python 3.11+, PowerShell 5.1+, Git and authenticated GitHub CLI.
+Required main/registry/Pages jobs must pass; missing approvals and partial
+publication are blockers, not success. The default script releases all three
+projects, is opt-in via `-Execute`, and supports a saved exact-source `-Resume`
+session. A changed checkout or pre-commit build failure requires review rather
+than an automatic stash/reset or guessed recovery.
+
+StemLab's helper updates npm manifests/lock, optional native dependency minimum,
+release/build metadata and the genuinely rebuilt JS/CSS together. Its daily
+release-update workflow proposes subsequent updates by PR without auto-merging.
+A tagged StemLab release generates all four Arcadians pages and validates actual
+Pages deployment, live HTML and seekable audio. Do not start a duplicate manual
+Arcadians analysis during that tagged build. Read
+**[the full release, resume, verification and troubleshooting guide](docs/released-viewers.md)**
+before running it. Keep this README and AGENTS.md synchronized with future changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kieransimkin/dance-rudiments",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Deterministic rhythmic position functions with C++, Python, TypeScript/WASM and C# bindings. https://kieransimkin.co.uk/my-songs/",
   "license": "MIT AND BSD-3-Clause AND CC0-1.0 AND CC-BY-4.0",
   "type": "module",