@kieransimkin/dance-rudiments 0.3.0 → 0.4.1

package/AGENTS.md

@@ -4,6 +4,7 @@
 - Use the relevant existing capabilities as fully as the task warrants. Always look for a useful improvement to this tool. Fix a reusable gap here rather than copying its engine or carrying a private workaround; record why no change is justified when that is the result.
 - Submit improvements as PRs to https://github.com/kieransimkin/DanceRudiments/pulls. Never leave a completed reusable improvement only in a local fork. Keep changes focused and preserve the tool's identity and compatibility contracts.
 - Add relevant regression coverage, documentation and a reproducible example when behaviour changes. Use tools/release_version.py and tools/check_release_version.py. Run the native and relevant binding tests from .github/workflows/ before packaging.
+- Run `python tools/check_package_docs.py` before packaging; every nested first-party `README.md` in the package input trees must retain the canonical author music link. Preserve third-party `sources/` attribution and keep the actual archive checks enabled.
 - 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/
@@ -23,3 +24,60 @@
 - 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.
+- A `main` branch deployment rule does not authorize version tags. If the environment rejects a tag, report the exact annotation and request the maintainer's explicit tag-rule authorization; do not bypass it. Once authorized, retry the failed deployment from the same run while its artifact remains available. Do not rebuild or overwrite completed release attachments to recover a deployment-only failure.
+- 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,14 +13,15 @@ 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
 
@@ -40,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://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.
+
+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,
@@ -116,6 +175,97 @@ 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
@@ -135,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
@@ -514,9 +632,50 @@ 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
 
+Run `python tools/check_package_docs.py` before packaging. Its source preflight
+checks nested first-party `README.md` files in the package input trees, including
+rig-motion examples and optional source-plan documentation, for the canonical
+author music link. Third-party `sources/` documentation retains its original
+attribution. Release jobs also check the actual archives; passing source checks
+does not establish package publication or registry availability.
+
+Tagged Pages deployments require an allowed **Tag** rule in the existing
+`github-pages` environment, in addition to any allowed `main` branch rule.
+A maintainer must explicitly authorize the intended release tags; the workflow
+does not change environment protections. See [release demo recovery](docs/release-demo.md#recovering-a-deployment-rejected-by-environment-rules)
+for retrying an already built site without rebuilding its immutable release assets.
+
 The additional `.github/workflows/csharp.yml` builds the shared C ABI and C# wrapper, tests actual installed NuGet packages, and publishes .NET packages only for release tags. Its NuGet.org setup is documented in [the C# guide](docs/csharp.md).
 
 `.github/workflows/ci.yml` builds and tests the C++ core on Linux, Windows, and macOS; builds and imports the Python package; compiles/tests the TypeScript and browser runtime; and creates a Conan package on every push to `main` and every pull request.
@@ -552,26 +711,6 @@ 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
-
-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).
-
-
 ## Coordinated releases and latest-release dependencies
 
 Keep `DanceRudiments`, `react-timeline-sequence`, and `stemlab` as sibling
@@ -612,3 +751,11 @@ 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;