@kieransimkin/dance-rudiments 0.2.4 → 0.4.0

package/AGENTS.md

@@ -7,3 +7,75 @@
 - 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.
+
+## Full ecosystem and release preflight
+
+Before every new workflow run, check the latest stable official release and observe the actual runtime used by the job. Follow [the shared preflight](https://github.com/kieransimkin/DanceFlow/blob/main/docs/workflows/release-preflight.md) and this project's [people-and-agent guide](docs/ECOSYSTEM.md). Review the complete relevant capability inventory rather than only a familiar command. Consider every DanceFlow component against the actual task; use and compose all applicable supported capabilities, and improve a concrete reusable gap in its canonical repository. Record why existing capabilities suffice when no change is justified. No catalogue checklist expands the task, authorises model downloads/training, or proves integration. Preserve exact source/package identity, clocks, model-local storage, privacy, costs, immutable releases and separate deployment gates.
+
+## Release mesh demos and Pages
+
+- Read `docs/release-demo.md` and `docs/mesh-demos.md` before changing demo builds or deployment. Keep the root native visualizer and `meshes/` gallery together in `dist/pages`. `demo-release.yml` is the sole Pages publisher; main/PR `visualizer.yml` runs remain artifact-only and must not erase a released mesh route.
+- Build from the exact validated tag and commit. Use tag pushes or manual dispatch for an existing compatible published tag; do not depend on a `release.published` event created with `GITHUB_TOKEN`. Old tags without the gallery cannot be retrofitted, moved or overwritten.
+- Retain the `DANCERUDIMENTS_PAGES_ENABLED == 'true'` guard, `github-pages` environment, approvals and protections. Read Pages configuration without enabling or changing it. Only the latest stable official release may deploy, with a second latest-release check after waiting for the shared deployment concurrency slot. Older-tag attachment builds must report a Pages skip accurately.
+- Keep original mesh geometry separate from captured source motion. The selected two-source builder may download only its explicitly requested, pinned files and must retain CMU/converter terms, hashes, units, axes and unverified musical timing. Optional motion files must remain outside the default catalogue and base package artifacts.
+- Run `npm test`, `test_mesh_demo_assets.py`, `test_release_pages.py`, the existing native visualizer/MIDI browser gates, and `tools/test_mesh_demo_browser.py` for the complete site before sealing release assets. Preserve the shared native 64-pip sampler, exact profile bindings, lazy scene loading and resource disposal. A `--gallery-only` receipt is local evidence and cannot seal a complete release site.
+- Bind browser evidence to every packaged site file and the exact release identity. Keep archives outside the Pages tree. Existing release assets are immutable: compare every collision before upload, retain identical bytes and refuse changed assets; never use `--clobber` for demo releases.
+- Distinguish source tests, browser QA, sealed artifacts, attachment verification, actual Pages deployment and live route/asset verification. Check hosted precompressed motion bytes without HTTP content decoding. Do not report a successful main preview or older-commit deployment as a verified mesh release.
+
+## Rigify motion validation
+
+For rig-motion changes, read `docs/rig-motion.md`, `docs/rigify-catalogue.md` and
+`docs/motion-sources.md`. Keep native 64-pip playback and the existing normalized
+Recording contract; do not introduce another live sampler. Preserve each saved
+profile's numbered channels and fingerprint. Regenerate built-in profiles only
+with the explicitly pinned Blender/Rigify source, and label contextual components
+and custom rigs accurately. Run the `test_motion*.py` and `test_rig*.py` suites
+and `tools/test_blender_rigify_bridge.py` in the pinned `bpy` environment for
+Blender-facing changes. For interchange changes, also run
+`tools/test_blender_motion_imports.py --output-dir .cache/blender-imports`.
+The `Rigify motion` workflow supplies that optional
+integration gate. Use synthetic fixtures; research catalogue entries do not
+authorize downloading or bundling third-party motion, models or media.
+
+## Optional motion packages
+
+Read `docs/motion-packages.md` and `docs/blender-motion-import.md` for changes to
+optional model recordings. Keep motion payloads in ignored `motion-packs/`,
+outside base npm/Python/native artifacts and the default catalogue. Do not add
+automatic downloads, global data registration or a second live sampler.
+Source-package downloads require task authorization and source-specific rights;
+retain licence, attribution, source hash and conversion changes with every pack.
+Never label a source skeleton as a Rigify retarget or time-only data as musical
+beat alignment. Preserve complete-action pip bounds and distinguish action counts
+from chunk counts.
+
+Run `test_motion_packages.py`, `test_bvh_import.py`, the TypeScript package/page
+tests via `npm test`, and the existing rig/recording tests. Blender import changes
+also require `tools/test_blender_motion_batch.py` in the pinned runtime. The
+`motion-import` extra supplies NumPy only for offline BVH conversion. Verify
+base-package file lists exclude generated motion data before packaging; npm's
+separate recording WASM asset must match its checked-in source hashes.
+
+## Preflight temporary-directory access
+
+Before any long, costly, model-backed, media-rendering, build, test, packaging or release command that creates private or atomic temporary directories, run a disposable preflight with the exact runtime, user or sandbox, and intended output parent. The probe must create a unique directory, write and read a file, atomically rename it, then remove the file and directory.
+
+Keep temporary data and caches under the owning project on `Z:`; model weights and model-specific caches remain under that project's ignored `models/`. If the probe returns `WinError 5`, access denied, a rename failure or a cleanup failure, stop before the expensive command. Preserve the exact error and use the documented narrowly approved unrestricted recovery from the outset only when the task requires it. Use a fresh output directory and do not repeat the already-failing full job in the restricted shell.
+
+After any unrestricted recovery, verify that the final output is readable and writable from the normal managed environment. If it is not, copy the completed bytes into a pre-created project-local directory that passed the probe, verify hashes, and retain the original failure and recovery evidence. Do not edit global ACLs, switch caches to `C:`, terminate unrelated processes or claim the underlying permission problem is fixed. Repositories that own temporary-directory creation should provide and test a reusable preflight helper rather than relying only on this instruction.

package/CONTRIBUTING.md

@@ -10,3 +10,11 @@ Agents and people are welcome to improve DanceRudiments. Review its current capa
 Maintainers review accepted changes, reserve a fresh version and publish a matching GitHub release from the validated source. They verify installable assets, checksums and each configured registry separately. Existing tags and release assets remain immutable. A submitted PR is a contribution awaiting review, not a published release or permission for unrelated deployment.
 
 Website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co.uk/danceflow/).
+
+## Before every new workflow
+
+Check the latest stable official release and the actual installed/imported version before starting; do not infer currency from a directory name or a development checkout. Read the current release notes, tagged capability documentation and relevant Potential problems. Use the [DanceFlow release preflight](https://github.com/kieransimkin/DanceFlow/blob/main/docs/workflows/release-preflight.md) and [complete capability references](https://github.com/kieransimkin/DanceFlow/blob/main/docs/capabilities/index.md).
+
+People and agents should consider the full ecosystem, use all capabilities that materially serve the task, compose supported files/APIs, and improve a demonstrated reusable gap in its canonical tool. Record why no worthwhile change is justified when that is the result. Keep independent tool identities, compatibility, source clocks, privacy, model/download costs and publication/deployment permissions intact. Store weights and model-specific caches in the owning project's ignored `models/`.
+
+Read [the people-and-agent ecosystem guide](docs/ECOSYSTEM.md) before selecting or extending a tool.

package/README.md

@@ -13,18 +13,21 @@ By **[Kieran Simkin — My Songs](https://kieransimkin.co.uk/my-songs/)** · Par
 
 <a id="visualizer"></a>
 
+## Before every new workflow
 
-## Agents and contributors
+Check the latest stable official release and the actual installed/imported version before starting; do not infer currency from a directory name or a development checkout. Read the current release notes, tagged capability documentation and relevant Potential problems. Use the [DanceFlow release preflight](https://github.com/kieransimkin/DanceFlow/blob/main/docs/workflows/release-preflight.md) and [complete capability references](https://github.com/kieransimkin/DanceFlow/blob/main/docs/capabilities/index.md).
 
-Agents using DanceRudiments should inspect its available capabilities, use them fully where they fit the task, and look for useful improvements wherever possible. When a required feature is missing, or a reusable reliability, usability, performance or documentation gap is found, improve this tool rather than maintaining a separate workaround. If no worthwhile change is justified, explain why.
+People and agents should consider the full ecosystem, use all capabilities that materially serve the task, compose supported files/APIs, and improve a demonstrated reusable gap in its canonical tool. Record why no worthwhile change is justified when that is the result. Keep independent tool identities, compatibility, source clocks, privacy, model/download costs and publication/deployment permissions intact. Store weights and model-specific caches in the owning project's ignored `models/`.
 
-Submit every improvement as a pull request to [DanceRudiments](https://github.com/kieransimkin/DanceRudiments/pulls), with relevant tests, documentation and a reproducible example. Follow [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for the contribution and validation workflow.
+## Find your route
 
-Project website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co.uk/danceflow/).
+[▶ Try the pattern visualizer](#-try-the-pattern-visualizer) · [3D dance examples](#3d-dance-examples) · [Which package should I use?](#which-package-should-i-use) · [Included rudiments](#included-rudiments) · [Default collections](#default-collections) · [Dancefloor 06](#dancefloor-06) · [BPM-synchronised N-dimensional recordings and comparison harness](#bpm-synchronised-n-dimensional-recordings-and-comparison-harness) · [Rigify character motion](#rigify-character-motion) · [Curve and event authoring](#curve-and-event-authoring) · [Language bindings](#language-bindings) · [Harness](#harness)
 
 ## ▶ 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
@@ -38,19 +41,77 @@ together. Compare any movements, or use **Only matching movements** and
 Sound is synthesised from note events, not the original Amen recording.
 
 The downloadable file is the checked-in snapshot; the **Pattern visualizer**
-workflow also rebuilds a fresh version from every pushed native catalogue.
+workflow also rebuilds and tests a fresh artifact from every pushed native catalogue.
+The **Release demo** workflow publishes the complete tagged site, including the
+3D examples below, when Pages is enabled. Main-branch visualizer builds do not
+replace that released site.
 [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.*
 
+## 3D dance examples
+
+The release build adds a separate **`meshes/` gallery** beside the pattern
+visualizer. It contains two original low-poly skinned characters with different
+captured dances:
+
+| Character | Movement | Source recording |
+| --- | --- | --- |
+| Boxbot | Salsa | CMU 60_01, with the documented 60 fps source timing restored |
+| Prism | Ballet: attitude, arabesque, turning jump and back bend | CMU 05_18 |
 
+Each character has its own optional motion package and independently bound rig
+profile. Loading a scene fetches only its own rig, profile and selected recording
+chunk. Play, pause, seek, restart and playback-rate controls use the existing
+native C++/WASM sampler. Unloading releases that scene's requests, recordings and
+GPU resources. The gallery uses actual weighted triangle meshes; no model or
+motion data is added to the base package or the site's pattern page.
 
-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.
+These are complete source recordings with **original timing**, including their
+calibration frame. They have no verified musical beat/downbeat annotations and
+are not presented as beat-matched to a song. The CMU source terms, attribution,
+source hashes and conversion details accompany the examples.
+
+The release workflow builds and browser-tests both characters, attaches a
+separate gallery ZIP and a complete-site ZIP, and deploys the existing visualizer
+and gallery together. Pages must already use GitHub Actions with
+`DANCERUDIMENTS_PAGES_ENABLED=true`; environment approvals remain in effect.
+The gallery becomes live at
+[`https://kieransimkin.github.io/DanceRudiments/meshes/`](https://kieransimkin.github.io/DanceRudiments/meshes/)
+after the first successful release containing these tools. Applying source
+changes alone does not deploy the website. See [building and validating the
+mesh demos](docs/mesh-demos.md) and the [release workflow guide](docs/release-demo.md).
+
+
+
+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.
 
+## Which package should I use?
+
+| You are building | Install or download | What you get |
+| --- | --- | --- |
+| C# / .NET application | `dotnet add package DanceRudiments` from [NuGet.org](https://www.nuget.org/packages/DanceRudiments) after its first release | Managed .NET 8+ wrapper and x64/ARM64 native assets for Windows, Linux and macOS |
+| Python application | `pip install dancerudiments` from [PyPI](https://pypi.org/project/dancerudiments/) | Native Python extension and the catalogue/sample API |
+| TypeScript or JavaScript application | `npm install @kieransimkin/dance-rudiments` from [npm](https://www.npmjs.com/package/@kieransimkin/dance-rudiments) | TypeScript declarations, JavaScript wrapper, and WebAssembly module |
+| C++ application using a listed release platform | Download the matching `DanceRudiments-cpp-<version>-<platform>-static.zip` from [GitHub Releases](https://github.com/kieransimkin/DanceRudiments/releases) | Headers, static library, CMake package files, licence, platform manifest, and instructions |
+| C++ application using another toolchain or architecture | Build from source or use `conan create` with `conanfile.py` | A library compiled for your own settings |
+
+GitHub automatically adds “Source code” ZIP and tar.gz links to every release; those are repository snapshots, not precompiled packages. Python wheels belong on PyPI, the C# package on NuGet.org (mirrored to GitHub Packages), and the TypeScript/WASM package on npm, while GitHub release attachments include C++ archives and the separately generated HTML demos, screenshots and checksums.
+
+## Included rudiments
+
+The general motions are `bounce`, `sway`, `circle`, `figure_eight`, `step_touch`, `box_step`, `helix`, and `clay_background`.
+
+The first drum-derived set is `single_stroke_roll`, `multiple_bounce_roll`, `double_stroke_roll`, `single_paradiddle`, `flam`, `drag`, and `five_stroke_roll`. The first six mirror the fundamentals in Vic Firth's Tier One learning sequence and collectively cover the roll, diddle, flam, and drag families in the Percussive Arts Society's 40 International Drum Rudiments. A right-hand stroke moves right, a left-hand stroke moves left, and both rise slightly. Every stroke is a raised-cosine (`sin²`) gesture: zero displacement at the start, smooth attack, a rounded peak, and smooth decay back to zero before the next motion. Accents use greater amplitude rather than an instantaneous position jump.
+
+Source references: [Percussive Arts Society International Drum Rudiments](https://pas.org/rudiments/) and [Vic Firth 40 Essential Rudiments](https://ae.vicfirth.com/education/40-essential-rudiments/), accessed 28 September 2026.
+
+`clay_background` preserves the translation waypoints from the Clay/Stars `ks-particle-dance` background treatment as a normalized 256-pip lookup table. The source effect's opacity, rotation, and scale are not position offsets, so they are intentionally excluded.
+
 ## Default collections
 
 The default catalogue contains **1,731 movements**: 15 original routines, 28 Initial 01,
@@ -87,6 +148,124 @@ 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.
+
+## Rigify character motion
+
+Typed rig motions now bind the native N-dimensional recording sampler to **Blender
+Rigify character controls**. The pinned Blender **5.2.2 LTS** catalogue covers all
+**eight built-in metarig presets** and **28 rig component types**, with numbered
+channel manifests generated from actual rigs. Each channel identifies its bone,
+property, component, physical units, range, neutral value and interpolation.
+The [catalogue guide](docs/rigify-catalogue.md) records exact counts and any
+component context; custom/generated characters can export their own profiles.
+
+Model types use a hierarchy such as
+`syn://type/danceflow/motion/rigify/metarig/human` and
+`syn://type/danceflow/motion/rigify/component/limbs/arm`.
+`synny://` is an equivalent spelling, not another type. Channel numbers persist
+across explicit profile extensions; profile hashes prevent applying a recording
+to an incompatible skeleton, rest basis or control layout.
+
+```sh
+python tools/rig_motion.py catalogue
+python tools/rig_motion.py profile human --output generated/human.profile.json
+python tools/rig_motion.py channels generated/human.profile.json --output generated/human.channels.csv
+python examples/rig-motion/quickstart.py --output generated/rig-motion --native
+```
+
+The installed CLI is `dancerudiments-rig`. The optional Blender bridge imports
+local **BVH, FBX and glTF/GLB**, captures animation already retargeted/baked onto
+Rigify controls, and applies or bakes motion using the actual native sampler.
+`dancerudiments.rig-motion` combines an exact profile with the unchanged normalized
+Recording format: float64 `[-1,1]`, 64 pips/beat, explicit bounds and non-looping
+playback. Scalar controls interpolate linearly during authoring, quaternion
+groups use shortest-path SLERP, and discrete switches hold their values.
+
+Source BPM/phase or measured beat anchors control compilation. A separate target
+beat map permits variable-tempo playback, absolute seeking and explicit
+half/double-time without accumulating frame-clock drift. The existing XYZ
+catalogue and C++ playback engine remain the movement authority.
+
+Read the **[complete rig-motion guide](docs/rig-motion.md)** for capture, compile,
+native playback, Blender baking, actual model mappings and compatibility. The
+**[motion-source research](docs/motion-sources.md)** records motion libraries and
+their format/licence/access constraints. The
+**[Blender import guide](docs/blender-motion-import.md)** covers multiple Actions,
+source-skeleton reconstruction and explicit Rigify FK mappings. Musical beat
+detection and foot-contact/transition repair remain separate authoring steps.
+The dedicated **Rigify motion** CI checks native playback and an
+actual skinned mesh using the pinned Blender runtime. These APIs require this
+development revision until a new stable package is released.
+
+### Optional model-specific motion packages
+
+Large character recordings are **independent optional packages**. They are not
+added to the 1,731 default rudiments, fetched at startup or loaded site-wide.
+Each package shares one exact numbered rig profile and stores individual
+compressed recordings with hashes, timing, source attribution and licence.
+Only the selected page or scene loads its requested clips.
+
+The new TypeScript `./motion-packages` subpath provides a lazy, scene-owned loader
+and the existing native C++/WASM recording accessor. The
+[page lifecycle example](examples/motion-packages/page-motion.mjs) follows the
+host's integer beat clock, keeps one recording chunk loaded, handles seeking and
+releases requests/memory on route exit. Rig application remains the consuming
+scene's responsibility; the existing XYZ visualizer does not become a mesh renderer.
+
+Python provides `MotionPackage`, `MotionPackageBuilder` and the explicit
+`dancerudiments-motion-pack` install/inspect/export CLI. Offline BVH import uses
+the optional `motion-import` extra; the base package does not acquire NumPy or
+Blender dependencies. Public source plans and reproducible import tools produce
+external data under ignored `motion-packs/`; the base npm/Python/native packages
+exclude those assets.
+
+Reproducible source recipes cover ACCAD human actions, 100STYLE locomotion,
+Lifelike Agility dog captures, Space-XR dance/movement recordings, a deduplicated
+CMU dance subset and all 14
+Actions of Quaternius' CC0 robot. The [source plan index](motion-packages/README.md)
+records separate data terms and acquisition commands. A collection can be large
+without increasing the base package or its startup work.
+
+```sh
+python -m pip install '.[motion-import]'
+python tools/import_motion_collection.py download --sources accad
+python tools/import_motion_collection.py build --sources accad
+python tools/motion_package.py list --root ./motion-packs
+```
+
+Complete source actions can span contiguous bounded chunks. Unknown musical
+timing is labelled **time-only**: a 60 BPM seconds coordinate is not an observed
+music tempo. Supply source tempo and beat phase or measured beat anchors before
+claiming musical alignment. The [optional-package guide](docs/motion-packages.md)
+describes formats, hosting, exact profile compatibility, source conventions,
+native playback and separate package licences.
+
 ## Curve and event authoring
 
 The optional **Python authoring tools** compile LFOs, segmented curves, sampled
@@ -106,38 +285,6 @@ formats, event anchoring, loop validation, generated functions, Python playback,
 WASM loading, provenance and testing. These are original infrastructure examples,
 not imported third-party preset banks.
 
-## DanceFlow ecosystem
-
-DanceRudiments is the reusable motion-vocabulary layer in Kieran Simkin's DanceFlow BPM and motion-response ecosystem:
-
-- **StemLab** is the music-understanding layer. It analyses audio to produce BPM, beat, structure, stem, lyric, harmony, and related timing evidence.
-- **DanceRudiments** turns integer musical positions at 64 pips per beat into deterministic 1D, 2D, or 3D position offsets.
-- **DanceMoves** is the WordPress EPK motion runtime. It schedules and applies BPM-, cue-, and lyric-timed effects on public pages.
-
-The three components can also be used independently. They exchange explicit timing and analysis data rather than depending directly on one another. DanceRudiments' 64-pips-per-beat sampling convention is intentionally higher resolution and is not the same unit as DanceMoves' 16-ticks-per-beat runtime clock.
-
-## Which package should I use?
-
-| You are building | Install or download | What you get |
-| --- | --- | --- |
-| C# / .NET application | `dotnet add package DanceRudiments` from [NuGet.org](https://www.nuget.org/packages/DanceRudiments) after its first release | Managed .NET 8+ wrapper and x64/ARM64 native assets for Windows, Linux and macOS |
-| Python application | `pip install dancerudiments` from [PyPI](https://pypi.org/project/dancerudiments/) | Native Python extension and the catalogue/sample API |
-| TypeScript or JavaScript application | `npm install @kieransimkin/dance-rudiments` from [npm](https://www.npmjs.com/package/@kieransimkin/dance-rudiments) | TypeScript declarations, JavaScript wrapper, and WebAssembly module |
-| C++ application using a listed release platform | Download the matching `DanceRudiments-cpp-<version>-<platform>-static.zip` from [GitHub Releases](https://github.com/kieransimkin/DanceRudiments/releases) | Headers, static library, CMake package files, licence, platform manifest, and instructions |
-| C++ application using another toolchain or architecture | Build from source or use `conan create` with `conanfile.py` | A library compiled for your own settings |
-
-GitHub automatically adds “Source code” ZIP and tar.gz links to every release; those are repository snapshots, not precompiled packages. Python wheels belong on PyPI, the C# package on NuGet.org (mirrored to GitHub Packages), and the TypeScript/WASM package on npm, while GitHub release attachments include C++ archives and the separately generated HTML demos, screenshots and checksums.
-
-## Included rudiments
-
-The general motions are `bounce`, `sway`, `circle`, `figure_eight`, `step_touch`, `box_step`, `helix`, and `clay_background`.
-
-The first drum-derived set is `single_stroke_roll`, `multiple_bounce_roll`, `double_stroke_roll`, `single_paradiddle`, `flam`, `drag`, and `five_stroke_roll`. The first six mirror the fundamentals in Vic Firth's Tier One learning sequence and collectively cover the roll, diddle, flam, and drag families in the Percussive Arts Society's 40 International Drum Rudiments. A right-hand stroke moves right, a left-hand stroke moves left, and both rise slightly. Every stroke is a raised-cosine (`sin²`) gesture: zero displacement at the start, smooth attack, a rounded peak, and smooth decay back to zero before the next motion. Accents use greater amplitude rather than an instantaneous position jump.
-
-Source references: [Percussive Arts Society International Drum Rudiments](https://pas.org/rudiments/) and [Vic Firth 40 Essential Rudiments](https://ae.vicfirth.com/education/40-essential-rudiments/), accessed 28 September 2026.
-
-`clay_background` preserves the translation waypoints from the Clay/Stars `ks-particle-dance` background treatment as a normalized 256-pip lookup table. The source effect's opacity, rotation, and scale are not position offsets, so they are intentionally excluded.
-
 ## Language bindings
 
 All four language interfaces sample the **same C++ runtime**. Choose the interface, not
@@ -152,7 +299,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.
@@ -485,6 +632,34 @@ after installing this checkout's native extension. The builder also needs
 `clang++` and `wasm-ld`; screenshot automation needs Playwright/Chromium. Those
 are build-time requirements, not dependencies of the downloaded HTML.
 
+## DanceFlow ecosystem
+
+DanceRudiments is the reusable motion-vocabulary layer in Kieran Simkin's DanceFlow BPM and motion-response ecosystem:
+
+- **StemLab** is the music-understanding layer. It analyses audio to produce BPM, beat, structure, stem, lyric, harmony, and related timing evidence.
+- **DanceRudiments** turns integer musical positions at 64 pips per beat into deterministic 1D, 2D, or 3D position offsets.
+- **DanceMoves** is the WordPress EPK motion runtime. It schedules and applies BPM-, cue-, and lyric-timed effects on public pages.
+
+The three components can also be used independently. They exchange explicit timing and analysis data rather than depending directly on one another. DanceRudiments' 64-pips-per-beat sampling convention is intentionally higher resolution and is not the same unit as DanceMoves' 16-ticks-per-beat runtime clock.
+
+## Motion safety
+
+Apply an output to a bounded subject. DanceRudiments changes position only; it must not be used to add a repetitive full-frame tint, brightness, flash, or colour-grade effect. Under `prefers-reduced-motion`, do not autoplay the harness or production motion.
+
+## 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).
 
 ## Continuous integration and releases
 
@@ -523,10 +698,51 @@ One-time registry configuration is required before the first release:
 
 The PyPI publishing job requests short-lived OIDC identity. npm can use Trusted Publishing when configured; the workflow retains `NPM_TOKEN` as a bootstrap/fallback credential. See the official [PyPI Trusted Publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/) and [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) documentation.
 
-## Motion safety
+## Coordinated releases and latest-release dependencies
 
-Apply an output to a bounded subject. DanceRudiments changes position only; it must not be used to add a repetitive full-frame tint, brightness, flash, or colour-grade effect. Under `prefers-reduced-motion`, do not autoplay the harness or production motion.
+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.
 
-## Troubleshooting history
+From the parent folder, preview and then explicitly execute:
 
-See [build and release troubleshooting](docs/troubleshooting.md) for prior failures, causes and fixes.
+```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.
+
+## Agents and contributors
+
+Agents using DanceRudiments should inspect its available capabilities, use them fully where they fit the task, and look for useful improvements wherever possible. When a required feature is missing, or a reusable reliability, usability, performance or documentation gap is found, improve this tool rather than maintaining a separate workaround. If no worthwhile change is justified, explain why.
+
+Submit every improvement as a pull request to [DanceRudiments](https://github.com/kieransimkin/DanceRudiments/pulls), with relevant tests, documentation and a reproducible example. Follow [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for the contribution and validation workflow.
+
+Project website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co.uk/danceflow/).

package/dist/recording/recording.wasm.json

@@ -0,0 +1,5 @@
+{
+  "tools/recording_wasm.cpp": "f4713cc7c773fa065715383fc68dccd91398fff08cd89167c5f24e64c0cecea9",
+  "include/dancerudiments/recording_view.hpp": "19dd73a150a82c4d9074fe4b9ba4c2f09d41e206028a6a6dc922d94e00dc4b8d",
+  "wasm_sha256": "d4cd976156860aa7a5c9665b27d2fda3cf6a0fa0da3dc0b9df365e425f1c6e29"
+}

package/dist/typescript/index.d.ts

@@ -1,4 +1,6 @@
 import { ApprovedDefaultName } from "./defaults.js";
+export { createMotionPackageLoader, createRecordingWasmAdapter } from "./motion-packages.js";
+export type { MotionJson, MotionJsonObject, MotionPackageAsset, MotionPackageClip, MotionPackageManifest, MotionRigChannel, MotionRigProfile, MotionRecordingClock, MotionRecording, NativeMotionRecording, NativeMotionRecordingFactory, MotionPackageTarget, MotionLoadOptions, MotionPackageLoaderOptions, LoadedRigMotion, MotionPackageLoader, } from "./motion-packages.js";
 export type Offset3 = Readonly<{
     x: number;
     y: number;
@@ -43,4 +45,3 @@ export type PatternLibraryHandle = Readonly<{
 }>;
 /** Load compiled JSON into a private C++ bank. No JavaScript motion fallback. */
 export declare function createPatternLibrary(document: unknown): PatternLibraryHandle;
-export {};

package/dist/typescript/index.js

@@ -1,4 +1,5 @@
 import { approvedDefaults } from "./defaults.js";
+export { createMotionPackageLoader, createRecordingWasmAdapter } from "./motion-packages.js";
 // Widen metadata before spreading thousands of literal records. Keep the name
 // union precise, without asking TypeScript to construct a huge object union.
 const generatedCatalogue = approvedDefaults;

package/dist/typescript/motion-packages.d.ts

@@ -0,0 +1,125 @@
+/** Optional, scene-owned rig recordings. No assets are fetched at module import. */
+export type MotionJson = null | boolean | number | string | readonly MotionJson[] | MotionJsonObject;
+export type MotionJsonObject = {
+    readonly [key: string]: MotionJson;
+};
+export type MotionPackageAsset = Readonly<{
+    path: string;
+    sha256: string;
+    byte_length: number;
+}>;
+export type MotionPackageClip = MotionPackageAsset & Readonly<{
+    id: string;
+    decoded_byte_length: number;
+    encoding: "json" | "gzip";
+    start_pip: number;
+    sample_count: number;
+    metadata?: MotionJsonObject;
+}>;
+export type MotionPackageManifest = Readonly<{
+    format: "dancerudiments.motion-package";
+    schema_version: 1;
+    id: string;
+    version: string;
+    title: string;
+    type_uri: string;
+    profile_sha256: string;
+    dimensions: readonly string[];
+    profile: MotionPackageAsset;
+    clips: readonly MotionPackageClip[];
+    license: MotionJsonObject;
+    provenance: MotionJsonObject;
+}>;
+export type MotionRigChannel = Readonly<{
+    number: number;
+    name: string;
+    bone: string;
+    data_path: string;
+    array_index: number;
+    unit: string;
+    minimum: number;
+    maximum: number;
+    neutral: number;
+    value_type: "float" | "integer" | "boolean";
+    interpolation: "linear" | "step" | "quaternion";
+    rotation_mode: string;
+    enum_items: readonly (readonly [number, string])[];
+}>;
+export type MotionRigProfile = Readonly<{
+    format: "dancerudiments.rig-profile";
+    schema_version: 1;
+    type_uri: string;
+    model: string;
+    version: number;
+    channels: readonly MotionRigChannel[];
+    source: MotionJsonObject;
+}>;
+export type MotionRecordingClock = Readonly<{
+    bpm: number;
+    bpm_source: string;
+    bpm_status: "estimated" | "confirmed";
+    beat_zero_seconds: number;
+    phase_status: "unverified" | "estimated" | "supplied";
+    start_pip: number;
+}>;
+export type MotionRecording = Readonly<{
+    format: "dancerudiments.recording";
+    schema_version: 1;
+    pips_per_beat: 64;
+    sample_dtype: "float64";
+    sample_decimals: 12;
+    name: string;
+    dimensions: readonly string[];
+    clock: MotionRecordingClock;
+    samples: readonly (readonly number[])[];
+    provenance: MotionJsonObject;
+}>;
+export type NativeMotionRecording = Readonly<{
+    sample(pip: number): readonly number[];
+    dispose(): void;
+}>;
+export type NativeMotionRecordingFactory = (recording: MotionRecording, options: Readonly<{
+    signal: AbortSignal;
+}>) => NativeMotionRecording | Promise<NativeMotionRecording>;
+export type MotionPackageTarget = Readonly<{
+    typeUri: string;
+    sha256: string;
+    dimensions: readonly string[];
+}>;
+export type MotionLoadOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
+export type MotionPackageLoaderOptions = Readonly<{
+    manifestUrl: string | URL;
+    packageId: string;
+    expectedProfile: MotionPackageTarget;
+    nativeFactory: NativeMotionRecordingFactory;
+    fetch?: typeof fetch;
+    manifestSha256?: string;
+}>;
+export type LoadedRigMotion = Readonly<{
+    id: string;
+    profile: MotionRigProfile;
+    profileSha256: string;
+    dimensions: readonly string[];
+    clock: MotionRecordingClock;
+    startPip: number;
+    sampleCount: number;
+    metadata: MotionJsonObject;
+    readonly disposed: boolean;
+    sampleNormalized(pip: number): readonly number[];
+    sample(pip: number): readonly (number | boolean)[];
+}>;
+export type MotionPackageLoader = Readonly<{
+    catalogue(options?: MotionLoadOptions): Promise<MotionPackageManifest>;
+    load(id: string, options?: MotionLoadOptions): Promise<LoadedRigMotion>;
+    unload(id: string): void;
+    dispose(): void;
+}>;
+/** Construct an inert loader owned by one page/scene. No global motion registry. */
+export declare function createMotionPackageLoader(options: MotionPackageLoaderOptions): MotionPackageLoader;
+/** Use the existing recording_wasm.cpp runtime, supplied explicitly by the app.
+ * Each clip owns an isolated WASM memory, released when its handle is disposed.
+ * Compilation/fetching of the module is an explicit caller operation.
+ */
+export declare function createRecordingWasmAdapter(module: WebAssembly.Module): NativeMotionRecordingFactory;