@kieransimkin/dancemoves 3.1.23 → 3.3.0

package/README.md

@@ -1,5 +1,23 @@
 # DanceMoves
 
+**3.3.0** adds source-bound beat alignment, connecting saved StemLab BPM/first-beat readings
+to the shared audio clock. WordPress's **EPK Timing** panel stores the reading
+and verifies its selected master attachment by SHA-256. Procedural rudiments,
+audio interval starts, pulses and sprite cycles use its fractional phase after
+clip/preroll mapping; audio and lyric/cue timestamps keep their original clock.
+Detector phase and fitted BPM remain labelled estimates. See
+[beat-alignment setup, APIs and verification](docs/beat-alignment.md).
+
+![Actual DanceMoves 3.3.0 example paused on the first beat: source time 0.125 seconds and rhythmic position zero](docs/screenshots/beat-alignment-first-beat.png)
+
+The original synthetic click example starts its first beat at 0.125 seconds.
+The blue source clock and amber rhythmic clock remain separately inspectable.
+[Watch the actual browser demonstration](docs/videos/beat-alignment-browser.mp4)
+(silent; native bounce, pulse and clock readings advance while lyric timestamps
+retain source time). Capture context and hashes: [media receipt](docs/beat-alignment-media.json).
+
+**3.2.0** adds native, non-looping playback of StemLab/DanceRudiments audio-derived movement recordings.  `runtime.recordings` composes the existing audio clock, shared player mapping, accessibility preferences and lifecycle. Captured BPM must match page metadata; samples retain their original integer-pip clock and never wrap. See [recording playback](docs/audio-recording-playback.md).
+
 **3.1.23** secures WordPress motion-capture writes with authenticated
 `manage_options` authorization. The private capture administration UI uses the
 same capability. Published tokens no longer authorize uploads; cookie clients

package/docs/audio-recording-playback.md

@@ -0,0 +1,56 @@
+# Audio-derived recording playback
+
+DanceMoves 3.2.0 adds `runtime.recordings` for the bounded `dancerudiments.recording`
+v1 JSON format exported by StemLab and DanceRudiments 0.3.0. Named native patterns
+continue to loop at their own periods. Recordings retain their captured origin,
+64-pip resolution, named dimensions and exact extent; they never wrap or interpolate.
+
+```js
+const recording = await runtime.recordings.load('/approved-motion.json');
+const motion = runtime.recordings.animate({
+  id: 'subject:recording', root, target, audio,
+  recording,
+  render({values, reason}) {
+    // Map bounded native samples to the existing subject's appearance.
+    // A CSSOM rule avoids high-frequency inline-style mutation observers.
+    rule.style.setProperty('--subject-angle', `${values[0] * 6}deg`);
+  }
+});
+await motion.ready;
+motion.setEnabled(false); // neutral values, preserving the captured clock
+motion.setEnabled(true);
+motion.destroy();
+```
+
+The controller composes the existing native DanceMoves audio scheduler and its
+shared-player mapping. Pause holds the source pose; seeking reconstructs it.
+Reduced motion, forced colours and explicit disable output zeroes. Hidden and
+offscreen subjects suspend through the existing lifecycle. Positions outside the
+recording emit zeroes with `reason: 'outside-recording'`; seeking back into the
+capture resumes its exact native sample. Runtime disposal destroys all recording
+controllers, including pending native loads. Use `pause()`, `resume()`, `refresh()`,
+`snapshot()`, `recordings.get(id)` and `recordings.snapshot()` for ownership and QA.
+
+The recording BPM must match the authoritative runtime/page BPM. A controller
+cannot override tempo, rate, phase or clock. BPM provenance and phase provenance
+remain separate. The page's WordPress EPK Timing metadata remains the only source
+for lyric/cue attachments; a movement recording never replaces those fields.
+Use the exact track/master, same-clock stem provenance and original capture origin.
+StemLab owns separation, filtering and smoothing; this player performs no DSP.
+All smoothing variants should use a fixed reference scale for a fair comparison.
+
+The sampler is the official native C++/WebAssembly accessor from DanceRudiments
+0.3.0. There is no JavaScript movement fallback. Its embedded binary SHA-256 is
+`d4cd976156860aa7a5c9665b27d2fda3cf6a0fa0da3dc0b9df365e425f1c6e29`, built from
+upstream `include/dancerudiments/recording_view.hpp` SHA-256
+`19dd73a150a82c4d9074fe4b9ba4c2f09d41e206028a6a6dc922d94e00dc4b8d` and
+`tools/recording_wasm.cpp` SHA-256
+`f4713cc7c773fa065715383fc68dccd91398fff08cd89167c5f24e64c0cecea9`.
+See the [upstream recording contract](https://github.com/kieransimkin/DanceRudiments/blob/v0.3.0/docs/recordings.md).
+The existing bundled named catalogue and its separate version are unchanged.
+
+Inputs are limited to 64 MiB JSON, 8,388,608 finite values in [-1,1], 1..64 unique
+named dimensions and signed 32-bit integer pip bounds. Loading fails closed for
+bad UTF-8, schema, samples, HTTP responses, mismatched BPM or unavailable WASM.
+Treat `ready` rejection as an unavailable motion state and retain static content.
+These source/build changes do not deploy a WordPress plugin or page.

package/docs/beat-alignment-media.json

@@ -0,0 +1,99 @@
+{
+  "context": "DanceMoves 3.3.0 source-bound beat alignment example in actual Edge browser",
+  "input": "Original synthetic 120 BPM click fixture; first beat 0.125 s; offset -16 pips",
+  "screenshot": "Paused first-beat seek: blue source 0.125 s, amber rhythmic tick zero",
+  "video": "Silent actual browser screenshots at retained wall-clock capture cadence; not frame-accurate performance evidence",
+  "transcription": "The native DanceRudiments bounce, playback pulse, source-time and rhythmic-time readings advance during playback. Lyric text remains attached to original source timestamps.",
+  "frame_count": 16,
+  "frame_ledger": [
+    {
+      "frame": 0,
+      "wallMilliseconds": 1792120075634,
+      "sourceSeconds": 1.235186
+    },
+    {
+      "frame": 1,
+      "wallMilliseconds": 1792120075772,
+      "sourceSeconds": 1.365459
+    },
+    {
+      "frame": 2,
+      "wallMilliseconds": 1792120075897,
+      "sourceSeconds": 1.499385
+    },
+    {
+      "frame": 3,
+      "wallMilliseconds": 1792120076076,
+      "sourceSeconds": 1.632385
+    },
+    {
+      "frame": 4,
+      "wallMilliseconds": 1792120076224,
+      "sourceSeconds": 1.765944
+    },
+    {
+      "frame": 5,
+      "wallMilliseconds": 1792120076271,
+      "sourceSeconds": 1.882867
+    },
+    {
+      "frame": 6,
+      "wallMilliseconds": 1792120076411,
+      "sourceSeconds": 1.999107
+    },
+    {
+      "frame": 7,
+      "wallMilliseconds": 1792120076534,
+      "sourceSeconds": 2.13241
+    },
+    {
+      "frame": 8,
+      "wallMilliseconds": 1792120076675,
+      "sourceSeconds": 2.268592
+    },
+    {
+      "frame": 9,
+      "wallMilliseconds": 1792120076800,
+      "sourceSeconds": 2.39849
+    },
+    {
+      "frame": 10,
+      "wallMilliseconds": 1792120076945,
+      "sourceSeconds": 2.532626
+    },
+    {
+      "frame": 11,
+      "wallMilliseconds": 1792120077074,
+      "sourceSeconds": 2.66667
+    },
+    {
+      "frame": 12,
+      "wallMilliseconds": 1792120077212,
+      "sourceSeconds": 2.797329
+    },
+    {
+      "frame": 13,
+      "wallMilliseconds": 1792120077331,
+      "sourceSeconds": 2.931918
+    },
+    {
+      "frame": 14,
+      "wallMilliseconds": 1792120077472,
+      "sourceSeconds": 3.068549
+    },
+    {
+      "frame": 15,
+      "wallMilliseconds": 1792120077613,
+      "sourceSeconds": 3.197775
+    }
+  ],
+  "generated_illustration_omission": "Actual interface captures explain this clock contract; a generated illustration adds no useful evidence.",
+  "browser_cleanup": {
+    "connected": false,
+    "contexts": 0
+  },
+  "files": {
+    "docs\\screenshots\\beat-alignment-first-beat.png": "c2c0d9e92706ce594a326c23e372064004e3b534971764dab2bf99fb0b942d0a",
+    "docs\\videos\\beat-alignment-browser.mp4": "8115f23dece23fc6c21e1c76f48ebc13e3594a360f464f676445ff1a2f373acf"
+  }
+}

package/docs/beat-alignment.md

@@ -0,0 +1,79 @@
+# Source-bound beat alignment
+
+![Actual first-beat seek in the DanceMoves 3.3.0 synthetic browser example: original source time 0.125 seconds maps to rhythmic tick zero](screenshots/beat-alignment-first-beat.png)
+
+[Play the silent browser demonstration](videos/beat-alignment-browser.mp4).
+The native bounce, playback pulse and two clock readings advance together;
+the displayed lyric still follows its original source timestamp. These are
+actual interface captures from an original synthetic 120 BPM click fixture,
+with a first beat at 0.125 seconds and a -16 pip reading. The video preserves
+the screenshot capture cadence; it is an interface demonstration rather than
+frame-accurate musical performance evidence. [Capture provenance](beat-alignment-media.json).
+
+WordPress **EPK Timing** has a **Beat alignment reading (StemLab JSON)** field
+and **Analysed Master Audio** attachment selection. Generate the reading from
+saved detector evidence with current StemLab:
+
+```powershell
+stemlab beat-offset RESULTS --output NEW-REPORT --audio EXACT-MASTER.mp3 `
+  --alignment-analysis consensus --alignment-bpm-basis canonical
+```
+
+Use `combined_fit` when canonical BPM is unknown and the reviewed constant-grid
+fit supports that choice. Review canonical, saved combined, half/same/double
+interpretations and individual detectors first. A half-time result is a normal
+metrical interpretation. Selecting a fitted tempo does not confirm canonical
+BPM or first-downbeat authority.
+
+Paste the exact `beat-alignment.json`, select its exact already public master
+attachment and save through the existing site approval process. WordPress checks
+the local attachment SHA-256, field bounds, numeric/rational consistency, source
+frame bounds and BPM agreement before accepting the reading. Invalid input
+preserves prior EPK timing fields; REST rejects it before content/meta writes.
+Both new properties participate in revisions and the normal edit capability and
+nonce protections. Unrecognized fields/private paths are omitted from public
+configuration. No JSON upload permission or arbitrary filesystem path is added.
+
+The attachment URL and normalized reading are localized as
+`danceMovesConfig.beatAlignment`. The browser additionally checks exact rational
+clock identity with BigInt. Native/master playback identity must match the
+selected attachment URL before applying phase. An identified remote master may
+supply `sourceUrl` in its verified master reference. Register a clip with the
+existing `offset`, `duration`, `playerStart` and `masterVerified` mapping first.
+
+`rhythmicTime(audio)` subtracts the first beat from the **mapped master time**;
+`sourceTick(audio)` returns its fractional position at 16 ticks per beat. At the
+first beat it is zero; before that it may be negative. This is the same as adding
+the signed 64-pip offset and dividing by four. No integer rounding is introduced.
+Core audio interval scheduling, procedural rudiments, playback pulses and sprite
+cycles share this clock. Page-only clocks retain their own elapsed time.
+
+```js
+const state = runtime.beatAlignmentState(master);
+// applied, status, firstBeatSeconds, offsetPips, sourceSha256, bpmStatus
+const ticks = runtime.sourceTick(master); // also works during paused seek review
+```
+
+The audio, transport `currentTime`, lyric/cue timestamps and captured recording
+sample clocks remain in original song time. The native frame's `sourceBeats`
+remains the mapped source position for recorded movement; `rhythmicBeats`
+exposes the aligned procedural position separately. Existing explicit sprite
+phase offsets are additional choreography; audit them before migrating a page which
+already compensates manually, to avoid applying the same phase twice.
+
+Blank metadata means unverified phase. A hash mismatch is not a zero-offset
+confirmation. Estimated phase stays estimated; an analysis-derived working BPM
+has `bpmSource: 'analysis'`, separate from artist-confirmed canonical metadata.
+An explicit stored BPM must agree with the selected reading (within its existing
+three-decimal storage precision); the reading's full tempo precision is used.
+The editor describes an active analysis-derived BPM explicitly; it does not
+label that reading as the 120 BPM fallback. An invalid saved master association
+shows an unavailable reading while retaining its metadata for correction.
+A single page reading applies to its exact master only. Distinct tracks need
+their own verified source association and scope; a title or equal duration is
+insufficient. A constant grid is not proof of variable-tempo or whole-song fit.
+
+Software publication does not deploy the WordPress plugin or change any EPK.
+After approved deployment/save, verify installed/served version, fresh selected
+metadata, exact hosted lyric/cue bytes, parser bounds, actual consumers, seek and
+player switching, responsive output and preserved motion/accessibility controls.

package/lib/admin.min.js

@@ -1 +1 @@
-(()=>{(function(i){"use strict";function a(t){var e=String(t||"").toLowerCase().split(".");return e.length>1?e.pop():""}i(function(){i(document).on("click",".dance-moves-select-file",function(t){t.preventDefault();var e=i(this).closest(".dance-moves-file-field"),o=String(e.data("allowed-extensions")||"").split(",").filter(Boolean),l=wp.media({title:"Choose timing file",button:{text:"Use timing file"},multiple:!1});l.on("select",function(){var n=l.state().get("selection").first().toJSON(),f=a(n.filename);if(o.indexOf(f)===-1){window.alert("Choose a ."+o.join(" or .")+" timing file.");return}e.find("input[type=hidden]").val(n.id),e.find(".dance-moves-file-name").text(n.filename),e.find(".dance-moves-file-url").attr("href",n.url).prop("hidden",!1),e.find(".dance-moves-clear-file").prop("hidden",!1)}),l.open()}),i(document).on("click",".dance-moves-clear-file",function(t){t.preventDefault();var e=i(this).closest(".dance-moves-file-field");e.find("input[type=hidden]").val(""),e.find(".dance-moves-file-name").text("No file selected"),e.find(".dance-moves-file-url").attr("href","#").prop("hidden",!0),i(this).prop("hidden",!0)})})})(jQuery);})();
+(()=>{(function(t){"use strict";function a(n){var e=String(n||"").toLowerCase().split(".");return e.length>1?e.pop():""}t(function(){t(document).on("click",".dance-moves-select-file",function(n){n.preventDefault();var e=t(this).closest(".dance-moves-file-field"),o=String(e.data("allowed-extensions")||"").split(",").filter(Boolean),l=wp.media({title:"Choose "+e.find("label").text(),button:{text:"Use selected file"},multiple:!1});l.on("select",function(){var i=l.state().get("selection").first().toJSON(),f=a(i.filename);if(o.indexOf(f)===-1){window.alert("Choose a ."+o.join(" or .")+" file.");return}e.find("input[type=hidden]").val(i.id),e.find(".dance-moves-file-name").text(i.filename),e.find(".dance-moves-file-url").attr("href",i.url).prop("hidden",!1),e.find(".dance-moves-clear-file").prop("hidden",!1)}),l.open()}),t(document).on("click",".dance-moves-clear-file",function(n){n.preventDefault();var e=t(this).closest(".dance-moves-file-field");e.find("input[type=hidden]").val(""),e.find(".dance-moves-file-name").text("No file selected"),e.find(".dance-moves-file-url").attr("href","#").prop("hidden",!0),t(this).prop("hidden",!0)})})})(jQuery);})();

package/lib/build-manifest.json

@@ -1,13 +1,13 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.23",
+  "version": "3.3.0",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
       "path": "admin.min.js",
-      "bytes": 1157,
-      "sha256": "db6ca41f28d0943a52c89093d279cc287a74702d412ea54c80b4c741525b9e43"
+      "bytes": 1164,
+      "sha256": "9f3ca5be76ca369ffb02c3977088d6b9304aa2038cd1bf9787936e518744aa0c"
     },
     {
       "path": "assets/DanceRudiments-build-manifest.json",
@@ -31,28 +31,28 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 212321,
-      "sha256": "2d7a7ec476e32d695fd88277967009b3e10a2ef889e0ecafa59ac4eaf6e15f2a"
+      "bytes": 221968,
+      "sha256": "b10addc676f3e6040f08567659717452218b2a5e643bba9c5884c6b8326fae52"
     },
     {
       "path": "index.cjs",
-      "bytes": 361185,
-      "sha256": "cf41f6c466acbb9f170ca37258fdf15ef7695457543e3bc29dc8b38ff38fed54"
+      "bytes": 376474,
+      "sha256": "cf55212b8ebdc691b03c12f8f623937f242744db8a50d24c221224f04379c069"
     },
     {
       "path": "index.d.ts",
-      "bytes": 13718,
-      "sha256": "82ec16610754f0237cd91e2a7a7ce4f6fe17617d8a61b78d089143e9fdb142e4"
+      "bytes": 15987,
+      "sha256": "1fdc5de3107b3f12cadd293c93f124c9ea4fe4ca6c648424d24c6728db454f1a"
     },
     {
       "path": "index.mjs",
-      "bytes": 360040,
-      "sha256": "abd302d298b2c808d83507eed49235602a4c7530dd3771083e4dfe16d84997ba"
+      "bytes": 375300,
+      "sha256": "5f66f30766ff0199c83b25526cf103a92f5b7278ccfe4737fead1aec4d29895d"
     },
     {
       "path": "react.cjs",
-      "bytes": 6595,
-      "sha256": "ed117a524b15a7b28264e74267a80963c0bcb0ce7739d256a9089809cdd3f1bd"
+      "bytes": 7147,
+      "sha256": "87be24114d28e43ba9c04dc0af3ed239fcf6de5874e68828a1a2b13bc2e4fbff"
     },
     {
       "path": "react.d.ts",
@@ -61,8 +61,8 @@
     },
     {
       "path": "react.mjs",
-      "bytes": 4909,
-      "sha256": "9513a1e019df45b7eef1e8e703eabbd063ae6b80e3c5e30852cdd0a510f6a635"
+      "bytes": 5383,
+      "sha256": "c5882b16ad6660b94ad2f7651c2294fb65b5e1dbc9a053624b23fb4ecde6153b"
     },
     {
       "path": "rudiments.d.ts",
@@ -71,8 +71,8 @@
     },
     {
       "path": "server.cjs",
-      "bytes": 21735,
-      "sha256": "2db5e089683bc23768a5b233ff5c35fb4d3b5babe04a63232152d923feb2ab90"
+      "bytes": 25715,
+      "sha256": "38a59bc5ae969cfcdaf16d3b83020d4148a9a4e7df0b14de98a073bfb24589e0"
     },
     {
       "path": "server.d.ts",
@@ -81,8 +81,8 @@
     },
     {
       "path": "server.mjs",
-      "bytes": 19290,
-      "sha256": "cf6a3934f29feffb369ce1e78064e42854e8e10e2b6e457a9b12e41ca0e664af"
+      "bytes": 23270,
+      "sha256": "03e6f53a9a5d854bc55f762f00f46f767e423090dade9ea13355cd42a2fc6928"
     },
     {
       "path": "styles/clay-stars-effects.css",
@@ -106,8 +106,8 @@
     },
     {
       "path": "wordpress.js",
-      "bytes": 211126,
-      "sha256": "dfb55567a063115518847ab70485924fed0bd4d64e790f9d659be97e1f0f08f5"
+      "bytes": 221102,
+      "sha256": "8fc80531c71a0a342284294e2e5eb0a845f1a7c3b93049e655b1f241f9d55b27"
     }
   ]
 }