@kieransimkin/dance-rudiments 0.2.4 → 0.4.0

package/docs/blender-motion-import.md

@@ -0,0 +1,228 @@
+# Import source skeletons and map explicit FK controls
+
+The optional Blender authoring module can extract individual recorded Actions
+from local **BVH, FBX, glTF/GLB and BLEND** files. It preserves the source skeleton
+under a distinct `syn://type/danceflow/motion/skeletal/source/...` identity.
+Generating a source profile does not turn that skeleton into a Rigify rig.
+
+The implementation is `dancerudiments_authoring.blender_import`; the checkout
+wrapper is `tools/blender_motion_import.py`. Importing, extracting and retargeting
+are offline operations. Playback continues to use native `SampledRecording`
+through `RigMotion.player()`, with 64 integer pips per beat. No downloaded motions
+are added to the default catalogue or automatically loaded into a website.
+
+## Inspect and extract a local file
+
+Run these commands in a dedicated Blender process, or with a Python environment
+containing the pinned official `bpy` runtime:
+
+```sh
+blender --background --factory-startup --python tools/blender_motion_import.py -- inspect character.glb --output inspected.json
+blender --background --factory-startup --python tools/blender_motion_import.py -- extract character.glb --source-id my_character --output-dir extracted --sample-fps 30
+```
+
+The inspector lists armatures, Action names, slots, source frame ranges, animated
+bone/property paths and rejected candidates. An existing Action/slot or NLA
+association establishes ownership. Otherwise an unbound Action must contain
+bone paths that resolve on the selected armature. Object-only animation needs
+an existing association. This avoids applying an unrelated camera Action to a
+character simply because it contains location curves.
+
+Select specific `--armature NAME`, `--action NAME` or `--binding-id ID` values
+from the report; each option may be repeated. BLEND files with multiple scenes
+require an explicit `--scene NAME`. Embedded scripts are not executed. Original
+files are preserved, and output paths must be new.
+
+Each successful extraction writes a `.capture.json` and `.profile.json` pair.
+`index.json` records source file SHA-256, importer options, exact Action/slot,
+frame count, channel count, duration, relative output names and unsupported
+animation. `--continue-on-error` retains successful captures and records failures;
+the process returns status 2 if any selected Action failed. A failure without
+that option stops the batch and writes the partial index. The importer does not
+download assets or infer permission from file format.
+
+### Source time and coordinate conventions
+
+The scene's effective `fps / fps_base` converts frames to seconds. BVH import
+preserves the source FPS. glTF timestamps may produce fractional Blender frame
+positions; those endpoints are retained. The shared Action range includes all
+its slots, including an animated parent object's lead-in or final key. NLA
+strip scaling, repeats and blending are not applied when extracting an
+individual Action.
+
+`--sample-fps` selects an explicit sampling rate. Omitting it uses the imported
+scene's rate. `--frame-start` and `--frame-end` select a finite excerpt inside the
+Action; they do not extrapolate choreography. The final endpoint is retained
+even when it falls between regular samples. The first captured frame becomes
+time zero, with original frame bounds and rate retained in provenance.
+
+There is **no assumed musical BPM or phase**. Compile the resulting capture with
+the existing rig-motion compiler and explicit source beat annotations. A pack
+may use a declared time-only 60-BPM coordinate so one beat represents one second;
+that is a duration convention, not evidence that the dance was performed at
+60 BPM. See [rig-motion compilation](rig-motion.md#beat-matching-and-compilation).
+
+BVH accepts explicit `--axis-forward`, `--axis-up` and `--global-scale` options.
+The defaults match Blender's BVH importer: `-Z`, `Y` and `1`. BVH files do not
+establish a physical unit. FBX uses its importer and embedded coordinate metadata,
+with an optional `--global-scale`. glTF and BLEND keep their declared transforms;
+source-axis overrides and a source import scale are rejected for those formats.
+glTF external buffers/textures are not included in the main file's SHA-256; use
+the original dependency set or a self-contained GLB when distributing an asset.
+
+## Portable source profile and native playback
+
+The source carrier has the original named hierarchy and bone rest matrices,
+plus an explicit synthetic root containing the armature object's evaluated
+world transform. Every source bone is considered, including fingers and bones
+with Rigify internal prefixes. Object parenting, constraints and bone inheritance
+are evaluated by Blender and baked into local translation, unit quaternion
+`w,x,y,z`, and scale values on a constraint-free carrier.
+
+The profile stores the portable skeleton as a list of names, parents, row-major
+rest matrices, lengths and deform flags. Carrier inheritance is explicitly full
+scale, inherited rotation and local location, and its object transform is
+identity. A pure BVH decoder may use the actual root joint instead of a synthetic
+object root. It can choose identity joint rest rotations while preserving exact
+joint offsets; displayed bone-tail direction is then a visualization convention.
+
+Only transform groups that remain neutral within the declared tolerance are
+omitted. The default tolerance is `1e-6`; set `--neutral-tolerance 0` to retain
+all numerical differences. Every omitted group and its neutral values are stored
+explicitly. Constant non-neutral groups remain recorded, and quaternion groups
+are always complete. The adapter expands omitted groups during pose application,
+so switching from a previously posed rig cannot leave stale values behind.
+Each compact profile has its own exact fingerprint and numbered channel list;
+do not reuse a channel number from a different profile merely because the source
+skeleton type is the same.
+
+For a package containing several Actions on that same source skeleton, use
+`union_source_profile(capture.profile for capture in captures)` and then
+`rebind_source_capture(capture, union_profile)` for each capture. The union
+preserves the first profile's channel IDs and appends missing bindings in a
+deterministic order. Rebinding expands only the explicitly declared neutral
+groups; it cannot discard movement or change a channel's units or bounds.
+Different skeletons, rest bases, import options or physical bounds need separate
+packages. This explicit conversion gives every clip the exact profile expected
+by the optional package loader without padding every source bone to ten channels.
+
+Physical bounds are fixed options, not fitted independently to each Action:
+locations default to ±10,000 Blender units, scales to ±100, and quaternion
+components to ±1. Negative scale can represent an actual source reflection.
+Out-of-range values fail. Matrices containing shear that local TRS cannot
+represent also fail instead of being silently approximated. The existing scalar
+budget is checked before allocating dense sampled rows; choose an excerpt or
+lower explicit sample rate when necessary.
+
+Create a compatible armature from a profile without requiring the original rig:
+
+```sh
+blender --background --factory-startup --python tools/blender_motion_import.py -- create-carrier extracted/CLIP.profile.json --name source_carrier --save source-carrier.blend
+blender --background source-carrier.blend --python tools/blender_rigify_bridge.py -- apply --armature source_carrier --motion compiled.motion.json --pip 64 --save sampled-source.blend
+```
+
+The carrier supplies the skeleton, not mesh geometry. Keep a licensed source mesh
+and its rest-space skinning data with an optional asset package if a renderer
+needs them. The existing native `apply` and `bake` bridge commands accept source
+profiles, validate the carrier's actual rest basis and hierarchy, expand declared
+neutral groups and save a new Action. They preserve prior actions and prevent
+old NLA blending from contaminating the saved result.
+
+B-Bone segment curvature and mesh shape keys are reported as unsupported
+deformations. Their skeletal bone transforms can still be captured, but the
+carrier does not reproduce those additional deformations. Animated dependencies
+outside the selected Action are rejected by default. Use
+`--allow-scene-dependencies` only after choosing the intended scene context; the
+dependency names are then retained in provenance.
+
+## Rebuild the optional Quaternius Robot package
+
+`tools/import_quaternius_robot.py` is a complete source-to-package example using
+the general APIs above. Supply the original public ZIP from the creator's
+[Animated Lowpoly Robot page](https://opengameart.org/content/animated-lowpoly-robot).
+The recipe verifies its exact SHA-256 and the original BLEND, FBX and licence
+members before opening Blender data. It has no downloader. The package contains
+14 original Actions, including the dance, under the CC0 licence preserved in the
+archive; the equivalent FBX motions are not counted a second time.
+
+With the pinned `bpy==5.2.2` environment and matching native extension installed:
+
+```sh
+python tools/import_quaternius_robot.py --archive Animated_Robot_Oct_2018.zip --work-dir robot-import --output-dir optional-packs/quaternius_robot/1.0.0 --package-archive quaternius_robot-1.0.0.zip
+```
+
+All output paths must be new. The work directory retains the exact source
+archive, licensed source mesh files, captures and verification report. The
+optional motion package contains the union profile, 14 compressed recordings,
+source hashes and notices, and stays separate from the default catalogue. Its
+178 numbered channels retain the source skeleton and fingers. Every compiled
+pip is checked through the native sampler before a package ZIP is produced.
+
+The explicit 60-BPM coordinate preserves elapsed time; musical tempo and phase
+remain unverified. To reproduce an earlier package's exact ingestion provenance,
+pass `--source-record PATH/TO/SOURCES.json` from that package. The recipe verifies
+all source identity fields and retains the original date record. A later run
+without that option records the recipe's source verification date, without
+claiming that it downloaded a file.
+
+## Explicit Rigify FK mapping
+
+The retargeter provides an explicit FK adapter, verified with a generated Basic
+Human Rigify rig and a skinned mesh. It does not infer a bone map from names or
+claim to solve IK poles, foot contacts, collision repair, missing fingers or
+facial morphs.
+
+First export the exact target rig's normal Rigify profile. Then supply a
+`dancerudiments.fk-map` schema 1 JSON document with these fields:
+
+| Field | Required meaning |
+| --- | --- |
+| `source_type_uri` | The exact portable source skeleton type |
+| `target_profile_sha256` | The exact exported target Rigify profile fingerprint |
+| `source_reference_object_matrix` | Explicit rigid 4×4 reference object transform, row-major; it establishes the source's rest coordinate basis |
+| `source_to_target_rotation` | Explicit unit quaternion in `w,x,y,z` order aligning source motion directions with the target |
+| `root_translation_scale` | Positive, explicit root distance scale; never inferred from an arbitrary bone length |
+| `bones` | Entries with exact `source`, `target`, `rotation` and `translation` fields; flags are Boolean and targets are unique |
+| `setup` | Explicit `{ "channel_number": ..., "value": ... }` entries, including required IK/FK switches |
+
+The source reference matrix and alignment quaternion are separate choices. The
+first removes the source object's declared reference orientation/placement when
+forming rest-relative deltas. The second aligns those deltas with the target.
+An identity reference is appropriate only when that is the intended source
+reference. Scale belongs in `root_translation_scale`, not in the reference matrix.
+
+For each mapped joint, the adapter computes the source's evaluated orientation
+relative to its rest basis, aligns that rotation, and applies it to the target
+control's rest orientation. Controls are solved in parent order using Blender's
+[pose/local matrix conversion](https://docs.blender.org/api/5.2/bpy.types.Bone.html#bpy.types.Bone.convert_local_to_pose).
+One mapping may transfer root translation. Source scale animation remains in the
+source capture; target FK scales retain the explicit target baseline. Existing
+target rotation modes and numbered property bindings are preserved. A constraint
+that prevents reaching the requested control orientation causes an error.
+
+```sh
+blender --background --factory-startup --python tools/blender_motion_import.py -- retarget source.capture.json --target-blend dancer.blend --scene Scene --target-armature rig --target-profile dancer.profile.json --mapping source-to-rigify.json --output rigify.capture.json
+```
+
+The output capture uses the exact target Rigify profile. Its provenance includes
+the complete mapping, source capture/profile hashes, fixed setup channels,
+unmapped source bones, unmapped target channels and measured control orientation
+error. Unmapped target controls retain their explicitly documented neutral/setup
+baseline; they are not presented as captured source movement. The operation
+restores the original target pose and animation assignment after authoring.
+
+## Reproducible verification
+
+```sh
+python tools/test_blender_motion_batch.py --output-dir .cache/blender-motion-batch
+python tools/test_blender_motion_imports.py --output-dir .cache/blender-imports
+python tools/test_blender_rigify_bridge.py --output-dir .cache/rigify-bridge-smoke
+```
+
+The new regression creates its own two-action BLEND fixture, non-aligned bone
+rest axes, finger motion and object root translation. It compares evaluated
+source/carrier matrices, verifies fractional multi-slot parent animation, checks
+unresolved dependency rejection, and performs explicit FK retargeting to a real
+generated Basic Human. Native pose application is saved and reopened in a fresh
+Blender process, where actual skinned vertex positions are checked. No external
+assets are downloaded by these tests.

package/docs/mesh-demos.md

@@ -0,0 +1,163 @@
+# Low-poly mesh dance demos
+
+The `meshes/` gallery presents two original skinned characters driven by real
+captured dance recordings. It uses DanceRudiments' existing native recording
+sampler, numbered skeletal channels and optional package loader. The gallery
+is built separately from the default pattern catalogue and base npm/Python
+packages.
+
+| Character | Captured motion | Full source duration | Mesh |
+| --- | --- | --- | --- |
+| **Boxbot** | CMU `60_01`, salsa | About 37.37 seconds, 2,243 source frames at 60 fps | Angular robot, 2,160 weighted vertices. |
+| **Prism** | CMU `05_18`, dance including arabesques, turning jumps and back bends | About 15.24 seconds, 1,830 source frames at approximately 120 fps | Faceted dancer, 2,850 weighted vertices. |
+
+Both meshes contain 31 source joints and vertices blended between neighboring
+bones. Their geometry is generated by the project's own Three.js character
+code. The source poses, movement, timing and root translations come from the
+pinned motion captures. The full source actions, including their calibration
+first frame, are retained.
+
+## Use the gallery
+
+Choose a character, then press **Load & play**. Initial navigation loads the
+interface and renderer; the selected rig, package, profile, recording and WASM
+are requested only after that explicit load. Choosing the other character
+unloads the previous skin, recording cache and native handle. **Unload** releases
+them without loading another character.
+
+The transport supports play/pause, restart, integer-pip seeking and preview
+speed. Playback stops at the final recorded pip. Camera orbit/zoom and reset
+change the view, while the camera follows the captured root translation. A
+reduced-motion preference leaves a newly loaded character paused. Desktop and
+mobile layouts share the same native playback.
+
+The clips have **time-only timing**: one second maps to one nominal beat and
+64 native pips. Their musical BPM and downbeat phase have not been annotated or
+verified. Preview speed changes elapsed playback speed; it does not establish
+musical beat matching. No music is bundled. To align a recording to a song,
+provide source beat anchors and a target clock through the offline
+[rig-motion compiler](rig-motion.md).
+
+## Skeleton and playback contract
+
+Each dance uses its exact source skeleton profile: 31 joints, 127 numbered
+channels, saved rest transforms, a stable type URI and a profile fingerprint.
+These are source-skeleton recordings; Rigify retargeting is a separate explicit
+operation. The browser applies complete WXYZ quaternion groups and root
+translation in source space, then transforms the presentation group for the
+Three.js view. Styling, floor placement and camera framing do not alter the
+recording or its source profile.
+
+The production TypeScript motion-package loader checks the manifest, expected
+profile, compressed byte count and hashes before constructing the existing
+native WASM recording handle. A scene holds only its current motion chunk; the
+transport requests absolute integer pips. JavaScript handles loading, clock
+position, decoded channel application and rendering. Native recording sampling
+remains shared with the Python/C++ implementation.
+
+## Rebuild just the gallery
+
+The asset builder needs the native Python extension and the optional
+`motion-import` NumPy extra. The frontend builder needs the lockfile's exact
+Three.js and esbuild versions. Blender and the bulk optional motion collections
+are not required.
+
+Run the temporary-directory preflight required by
+[AGENTS.md](../AGENTS.md), then:
+
+```sh
+python -m pip install '.[motion-import]'
+npm ci
+python tools/build_mesh_demo_assets.py --output-dir generated/mesh-demo-assets --cache-root .cache/motion-sources/cmu-dance --download
+node tools/build_mesh_demo.mjs --assets-dir generated/mesh-demo-assets --output-dir dist/pages/meshes
+python -m http.server 8000 --directory dist/pages
+```
+
+Open `http://localhost:8000/meshes/`. The builder defaults to the checkout's
+package version and complete Git commit; `--version` and `--commit` may supply
+the validated release identity explicitly.
+
+`--download` authorizes only the two URLs pinned in
+[`tools/mesh_demo_sources.json`](../tools/mesh_demo_sources.json). The source
+files total about 3.1 MB and are checked for exact size and SHA-256 before
+conversion. Without `--download`, the asset builder requires those verified
+files already in its local cache. Use a fresh asset output directory; source
+archives and generated motions stay out of the base packages and default
+catalogue. The frontend builder can replace its own previously generated
+output tree and removes stale files as part of that bounded rebuild.
+
+The source asset directory contains `catalogue.json`, two scoped motion
+packages, source rigs, notices and independent browser references. The final
+HTTP route adds locally bundled Three.js, the production package loader,
+`recording.wasm`, `build.json` and the UI. It has no runtime CDN dependencies.
+
+## Reproduce the browser checks
+
+```sh
+python -m pip install playwright==1.64.0
+python -m playwright install chromium
+npm test
+python -m unittest discover -s tests/python -p test_mesh_demo_assets.py -v
+python -m unittest discover -s tests/python -p test_release_pages.py -v
+python tools/test_mesh_demo_browser.py --site-dir dist/pages --output-dir dist/mesh-qa --gallery-only
+```
+
+The browser tool starts its own loopback HTTP server. `--chromium /path/to/chromium`
+selects an existing matching browser; otherwise it uses Playwright's installed
+Chromium. Software WebGL through ANGLE/SwiftShader is supported for headless CI.
+It saves a JSON receipt and one desktop/mobile PNG per character.
+
+For each dance, four reference pips cover the first frame, an early moving
+frame, the middle and the last sample. The tool compares every native normalized
+channel with separately decoded package bytes, every physical channel with the
+Python-native player, and all 31 joint world matrices with independently
+composed NumPy transforms. It also checks actual skinned vertex movement,
+playback controls, lazy fetches, disposal, layout and unhandled browser errors.
+The browser never fetches the reference files for playback.
+
+A `--gallery-only` run reports exactly that scope. It is useful when developing
+the meshes without rebuilding the large catalogue snapshot, but cannot seal a
+release site. The complete release path first renders and tests the existing
+native visualizer, prepares its navigation link, then runs this tool without
+`--gallery-only` against the combined site. See the
+[release guide](release-demo.md) for exact assembly, attachment and deployment
+commands.
+
+## Sources and rights
+
+The captures originate in the [CMU Graphics Lab Motion Capture Database](http://mocap.cs.cmu.edu/),
+with [subject 60](http://mocap.cs.cmu.edu/search.php?subjectnumber=60) and
+[subject 5](http://mocap.cs.cmu.edu/search.php?subjectnumber=5) identifying the
+performances. The pinned BVH conversion is Bruce Hahne's cgspeed distribution,
+retrieved through the exact mirror commit recorded in the source plan. The
+converter's 60 fps correction for the salsa take is explicit in its provenance.
+The approximately 120 fps value for the second take follows its saved BVH frame
+time. Both retain documented units, axes and source hashes.
+
+The motion data carries CMU's custom terms: it may be copied, modified and used
+in commercial projects, with direct resale of the motion data prohibited.
+It is not relabeled as CC0 or CC BY. Each generated package and downloadable
+mesh bundle includes the source terms, CMU/NSF attribution, converter credit,
+source URLs, hashes and conversion choices. Original character geometry and
+runtime dependencies retain their own project/dependency notices. Consult the
+bundled `LICENSE.txt`, `THIRD_PARTY_NOTICES.md` and `SOURCES.json` for the full
+source-specific record.
+
+## Release and deployment
+
+The [Release demo workflow](../.github/workflows/demo-release.yml) builds this
+gallery from the same exact tag as the root pattern viewer. The
+`DanceRudiments-pages-vX.Y.Z.zip` download contains the complete site; the
+separate `DanceRudiments-mesh-demos-vX.Y.Z.zip` contains the `meshes/` route.
+
+Pages deployment uses the repository's existing enablement variable and
+environment approvals. Only the latest stable release can publish the site;
+older-tag rebuilds keep their release downloads without replacing the latest
+Pages content. The post-deployment verifier checks both routes and every public
+asset against the tested version/commit manifest.
+
+Earlier API/package changes did not add a visible mesh renderer. A green
+main-branch check or a successful deployment of the older pattern visualizer
+therefore does not establish that this gallery was deployed. The mesh page
+requires a fresh release containing these builders; pre-gallery tags such as
+`v0.3.0` cannot acquire the new code through a manual rerun.

package/docs/midi-harness.md

@@ -0,0 +1,180 @@
+# Full-catalogue visualizer and MIDI beat player
+
+The main `harness/index.html` is now a **single self-contained HTML file** with
+all default movements, the C++/WebAssembly snapshot sampler, the complete beat
+library, a small procedural percussion synthesiser, and all interface code.
+`harness/index.json` is an audit sidecar, not a browser dependency. The top of the
+README links directly to the downloadable HTML, rather than an unbuilt harness,
+a GitHub source-code view, or an external JavaScript/WASM dependency.
+
+## Listen and compare
+
+Open the HTML locally and press **Play**. The initial beat is the complete
+four-bar Amen study at the harness's current BPM. **MIDI sound** mutes/unmutes the
+synthesiser; **Volume** controls its level. Nothing auto-plays. Tempo is shared
+with animation, including pause, restart, seeking, single-pip stepping and live
+BPM changes. Changing the beat preserves phase and BPM. **Use suggested BPM** is
+the explicit action that changes tempo to the score's suggestion.
+
+The Library menu separates dance music, recorded Groove MIDI excerpts, abstract
+event studies, and the original C++ sticking rudiments. Search also matches IDs
+and families. A selected beat remains available while filtering.
+
+**Only matching movements** restricts the catalogue to movements derived from
+that score. **Compare this beat's movements** selects its first four mappings;
+other cards can be chosen normally. **Follow compared movement** automatically
+selects the first newly compared movement's source beat. Individual cards also
+have **Use this movement's beat**. A waveform or geometric path without scored
+onsets can still be auditioned against any beat, but is not assigned a fictitious
+source drum pattern.
+
+Expand beat details for the complete onset grid, per-lane mutes, provenance and
+MIDI import/export. The grid uses exact fractional source times and represents
+velocity with dot size/opacity; its numbered axis counts quarter notes over the
+whole loop. It is not an automatically quantised sixteenth-note grid.
+
+The local-audio option is retained. Loading a track pauses MIDI and uses the
+track's audio-element clock, BPM and manually entered beat-zero offset instead.
+Remove the track to return to MIDI. The two audio sources are not accidentally
+played together. Hiding the tab pauses playback to avoid background timer drift.
+
+## Coverage
+
+The current registry includes **305 scores**:
+
+| Source | Scores |
+| --- | ---: |
+| Club 05 + Dancefloor 06, deduplicated by exact shared rhythm identity | 68 |
+| Earlier authored event scores (Euclidean, additive, polyrhythm, swing, sticking, etc.) | 226 |
+| Groove MIDI excerpt A/B, played and grid variants | 4 |
+| Original C++ drum-sticking definitions | 7 |
+
+They are linked to **1,325 movements**. All **1,731** movements are available in the
+same visualizer; continuous shapes without note events can use any accompaniment.
+This is not a claim that 305 unrelated dance genres or recordings were imported.
+Some entries intentionally share timing while differing in instrument/gesture
+emphasis. Abstract event lanes receive explicitly assigned audition timbres.
+
+`tools/harness_beats.py` reads the committed `*/rhythms.json`, `*/*.score.json`,
+pack provenance, and default-selection lock. It also extracts the seven legacy
+stroke lists from their C++ function bodies rather than duplicating those lists.
+A changed/unsupported C++ representation fails loudly. This preserves the saved
+rhythms, not freshly recalculated platform-dependent motion definitions.
+
+The original stroke timestamps represent **gesture starts**; those movement
+peaks occur half a stroke-width later. Generated scores retain their declared
+onset/peak/end anchor semantics. Neither the source timings nor movement tables
+are silently shifted to conceal that distinction.
+
+The Amen study retains all 16 quarter-note beats (four bars), 81 programmed note
+onsets, ghost-note velocities, displaced later backbeats and the cymbal change.
+**Amen / ghost notes A–B** switches to the existing no-ghost comparison, without
+changing the animation tempo. It remains a quantised structural interpretation,
+not the original recording or measured drummer microtiming.
+
+## MIDI support
+
+**Download beat as MIDI** writes a real type-1 Standard MIDI File, with a tempo
+meta-event at the current animation BPM, meter when known, note-on/off events,
+credits and an end-of-track marker at the exact loop endpoint where representable.
+Percussion uses zero-based channel 9 (human channel 10); bass uses channel 1.
+Built-in listening preserves rational source onsets; SMF export chooses a PPQ
+that represents those fractions exactly where possible (maximum 32767). When the
+combined denominators do not fit, it uses 30720 PPQ and reports the maximum timing
+quantisation. MIDI velocities necessarily use 7-bit precision. Notes that would
+extend past the loop end are gated at the boundary in exported files.
+
+**Import MIDI** supports PPQ type-0/type-1 `.mid`/`.midi` files, up to 2 MiB, 65,536
+notes, 128 tracks and 4,096 quarter notes. It handles running status, note-offs,
+velocity-zero note-ons, track-end silence, tempo/meter metadata and ignorable
+SysEx. Invalid/truncated input fails without replacing the current beat. SMPTE
+and independent-sequence type-2 files are deliberately rejected.
+
+Imported tempo maps do **not** change the animation tempo; tick positions are
+normalised to quarter notes and played at the harness BPM. The first embedded
+tempo is offered as a suggestion. Channel-10 notes use the synthesised kit;
+other channels use simple pitched cues. This is a rhythm audition player, **not**
+a full General MIDI sound module: patch changes, controllers, pitch bends,
+sustain pedals and expressive articulation are not emulated. Long imported scores
+have a horizontally scrollable grid; at most 32 distinct lanes are drawn, while
+all valid notes remain scheduled. There is a defensive 256-voice playback cap.
+No MIDI hardware access or permissions are requested.
+
+The Groove MIDI attribution/licence and source/transformation notes are retained
+in the HTML and exported MIDI copyright/text metadata. Original recordings and
+commercial samples are not included. Existing source terms still apply.
+
+## Clock design
+
+Web Audio's `currentTime` is the scheduling clock once audio is enabled. A 25 ms
+control timer schedules a short 100 ms look-ahead window; `requestAnimationFrame`
+never triggers drum hits. Visual phase uses `getOutputTimestamp()` where available
+and a reported-latency fallback, so it follows the output audio clock rather than
+an unrelated elapsed-time counter. Device/display latency can still affect
+perceived synchronisation; this is not a hardware calibration tool.
+
+Each musical window is half-open to avoid duplicate hits at loop boundaries.
+Beat times remain unwrapped; every movement applies its own C++ loop modulus.
+Pause, seek, source changes, mutes and tempo edits cancel queued voices and rebase
+the same clock. Pending audio unlocks are invalidated by pause. A short scheduling
+lead is used when rebasing; the beat position is preserved, but sample-seamless
+DJ-style tempo warping is not promised. Web Audio must first be enabled through
+a user gesture. The maximum accepted tempo is 300 BPM and the minimum is 20 BPM.
+
+## Build and test
+
+```sh
+python -m pip install .
+python tools/build_harness.py
+python tools/harness_beats.py --output harness/beats.json
+node tools/export_harness_midi.mjs dist/midi
+node --test tests/typescript/beat-player.test.js
+python tools/test_midi_harness.py harness/index.html
+```
+
+Generation requires clang++ and wasm-ld, as the previous native release demo did.
+The browser test requires Playwright/Chromium. `--in-memory` is available only for
+restricted test environments and is recorded in the report; normal CI tests local
+file loading. The checked-in HTML is an immediate download; regenerate and commit
+it when changing the catalogue or player. The per-push build produces a fresh
+artifact even when a checked-in preview has not yet been refreshed.
+
+Release generation uses the same template/player and reads that tag's native
+catalogue. The release workflow validates MIDI playback before packaging its
+HTML, screenshots and checksums. Stable `DanceRudiments-visualizer.html` and
+`DanceRudiments-visualizer.json` aliases are attached as well, enabling a stable
+`releases/latest/download/DanceRudiments-visualizer.html` URL after the next release
+containing these changes. Older releases are not retroactively altered.
+
+## Optional live GitHub Pages site
+
+The README's **downloadable HTML works without Pages**. For a hosted click-to-play
+copy at `https://kieransimkin.github.io/DanceRudiments/`:
+
+1. Set Repository **Settings → Pages → Source → GitHub Actions**.
+2. Add the repository Actions variable `DANCERUDIMENTS_PAGES_ENABLED` with value
+   `true`.
+3. Publish a fresh release tag containing the demo builders, or manually run
+   **Release demo** for an existing compatible release tag. The environment's
+   normal deployment approvals still apply.
+
+**Pattern visualizer** builds and tests artifacts on pushes and pull requests.
+It no longer deploys Pages: a visualizer-only deployment would erase the optional
+mesh gallery. **Release demo** is the sole Pages publisher and uses the exact
+validated release tag. It publishes **only `dist/pages`**, containing this
+visualizer at the root and the [3D dance examples](mesh-demos.md) at `meshes/`.
+Source files, caches and the bulk optional motion collections are outside that
+site. A gallery recording loads only after **Load & play** is clicked for that
+character.
+Applying or pushing the code alone does not publish a new release or website.
+
+See [the release demo guide](release-demo.md) for build, attachment verification,
+Pages deployment and post-deployment checks. The existing root URL and offline
+visualizer download remain available through the same interfaces.
+
+## Protocol and hosting references
+
+- W3C Web Audio API: https://www.w3.org/TR/webaudio/
+- MIDI Association, Standard MIDI Files: https://midi.org/standard-midi-files
+- GitHub Pages custom workflows: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
+- GitHub Pages publishing source: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site