@kieransimkin/dancemoves 3.1.19 → 3.1.20

package/AGENTS.md

@@ -7,3 +7,9 @@
 - Keep credentials, account data, private media and rights records out of source, fixtures, logs and packages. Use synthetic fixtures or explicitly authorised public examples and preserve their provenance/licences.
 - Use [CONTRIBUTING.md](CONTRIBUTING.md) for review. Maintainers publish accepted, validated improvements as a fresh matching GitHub release and verify configured registry destinations. Preserve existing tags and release assets; publication and deployment remain subject to applicable authorisation.
 - Website: https://kieransimkin.co.uk/danceflow/
+
+## Keep README documentation current
+
+- Whenever a feature is added or changed, update the relevant README.md in the same change to reflect the resulting behaviour. This applies to every feature addition or modification, including APIs, commands, configuration, defaults, integrations and removals.
+- Update affected feature descriptions, usage instructions, options, examples and limitations. For tools or packages with their own README.md, update that README as well as the repository README when its overview or usage is affected.
+- Check the README against the implemented and verified behaviour before committing, opening or merging a PR, publishing a release or handing off the work. A feature change is incomplete until its README documentation is current; a changelog or other documentation does not replace this requirement.

package/README.md

@@ -1,5 +1,10 @@
 # DanceMoves
 
+**3.1.20** adds a shared playback transport for explicitly verified native and
+YouTube players. Full-master players drive the existing musical effects; Shorts
+map their offset and duration onto the master clock. See
+[playback sources](docs/playback-sources.md) for provenance, controls and lifecycle.
+
 `connectPhoneMotion()` attaches suitable existing spatial effects to one shared
 phone input route, preserving desktop pointer input. See the
 [connection guide](docs/phone-motion-connections.md) for permission UI, consumer
@@ -946,3 +951,12 @@ back into this section. Existing release and deployment history remains in Git,
 ## WordPress.org publication
 
 The release workflow can update the WordPress.org directory automatically after a validated release tag. Initial directory submission and human approval remain required. After approval, configure repository variables `WPORG_PLUGIN_APPROVED=true` and `WPORG_PLUGIN_SLUG` with the directory-assigned slug, plus `WPORG_SVN_USERNAME` and `WPORG_SVN_PASSWORD` secrets in the `wordpress-org` environment. The job verifies the exact tested release artifacts after the matching GitHub release exists, then uploads the packaged plugin through SVN. It remains disabled while the initial submission is queued; it does not install the plugin on a website. Website: https://kieransimkin.co.uk/danceflow/
+
+## Agent guidance releases
+
+Source-only agent guidance releases use `readme-policy-vMAJOR.MINOR.PATCH` tags
+and contain the updated instructions with a source manifest and checksums.
+They version the documentation policy independently of the runtime packages.
+The runtime release workflow accepts tags starting with `v` and then verifies
+the exact semantic version and immutable source before building and publishing
+packages. Guidance release events skip that workflow's build and publishing jobs.

package/docs/playback-sources.md

@@ -0,0 +1,78 @@
+# Audio, video and excerpt playback
+
+One verified master can have several native audio/video and YouTube players.
+`playbackSource(master)` returns a stable, event-driven transport. Existing
+shared cues, lyrics, pulse, sprite, timeline and rudiment consumers resolve that
+transport automatically when given its native master element. Page callbacks
+that directly read a native element must instead read the returned transport.
+The visible native controls keep controlling their original element.
+
+Register each additional player explicitly, after its master duration is known:
+
+```js
+const master = root.querySelector('audio');
+const source = motion.playbackSource(master);
+const full = motion.registerPlayer({master, player: root.querySelector('video'),
+  masterVerified: true});
+const short = motion.registerYouTube({master,
+  iframe: root.querySelector('iframe'), masterVerified: true,
+  offset: 48, duration: 20});
+await short.ready;
+// Player time 3 seconds is master time 51 seconds.
+// Dispose before removing/replacing the player:
+short.teardown();
+```
+
+A video-only page may pass one stable `{id, duration}` master reference instead
+of a native element, using the verified recording identity and exact master
+duration. This avoids adding or playing hidden audio. Reuse that reference for
+all of the recording's players and pass `playbackSource(reference)` to its
+effects. Registration joins the existing timing engine after runtime readiness.
+WordPress still obtains its lyric/cue files exclusively from selected metadata.
+If a native master is present but its metadata is still loading, include that
+element as `element` in the reference. Its existing consumers keep the same
+transport and the verified duration supplies the initial clock without waiting
+for another media download. Conflicting or mismatched durations are rejected.
+
+All values are seconds. `offset` is the start in the associated master,
+`duration` is its contiguous excerpt length, and optional `playerStart` is the
+point in the video where that soundtrack starts. Default offset/playerStart are
+zero and default duration is the complete master. Negative, nonfinite, empty or
+out-of-master windows are rejected. Preroll/postroll do not acquire a song clock.
+This mapping describes a contiguous, unchanged-rate excerpt, not a mashup,
+reordered edit or changed recording. Such media needs a separately verified
+mapping and must not be falsely assigned to this master.
+
+`masterVerified: true` is the caller's explicit provenance attestation. It is
+never inferred from equal duration, similar titles or artwork. Preserve the
+render/source hashes and exact published-player identity outside the runtime.
+The top campaign video must use the exact release master as its soundtrack;
+other full-master players share its clock, while distinct edits retain their
+own identity. YouTube necessarily transcodes the upload: exactness here means
+the supplied soundtrack and timing, not byte identity of YouTube's stream.
+
+The first playing associated player pauses the prior associated player. It does
+not secretly play muted duplicate audio. The source exposes master `currentTime`
+and `duration`, actual playback state/rate, `activePlayer` and native `element`.
+Mapped source seeks are clamped to the selected excerpt. Switching players
+reconciles a seek without replaying skipped cues. Buffering pauses the source;
+seek/rate/loop changes use the same existing effect lifecycle.
+Preroll and postroll stay outside the song clock. Replaying an excerpt re-arms
+its actual starting cue. Existing consumers of another associated native audio
+element retain a stable source while the group keeps one cue dispatcher.
+
+YouTube uses the official IFrame API, adds `enablejsapi=1` and the current origin,
+and preserves an existing API-ready callback. Register after the visitor/consent
+flow permits the iframe. Registration itself never requests autoplay. `ready`
+rejects API/player failures or timeout. Always handle that promise and show an
+accurate unavailable state. A successfully constructed player does not prove
+playback or soundtrack identity. Test an advancing content timeline, controls,
+pause, seek, rate, buffering, replay, visibility and teardown on real embeds.
+
+Sampling runs only for the active, playing, visible YouTube source. Native
+players use their events without a second scheduler. `teardown()` is idempotent;
+runtime destruction releases registered owners. Shared effects retain their
+reduced-motion, forced-colour, quality and visibility policies. Physical-device
+performance still needs physical evidence.
+
+Reference: [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference).

package/lib/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.19",
+  "version": "3.1.20",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
@@ -31,23 +31,23 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 189980,
-      "sha256": "2d9f8a6b5ac0ff32d6f940c31c16213e145c85c48fc9957ee2e405ce91d02d02"
+      "bytes": 201822,
+      "sha256": "2c2f314a6582488e8c969009ff7115428f6bcf8b5f0b1467c683adca59cdd30b"
     },
     {
       "path": "index.cjs",
-      "bytes": 320229,
-      "sha256": "df4670757481c736796dd9878148f33a2a7095713851f2d14218e6efeb4edd4a"
+      "bytes": 342587,
+      "sha256": "9bdad4f199b86ea24644342c7fbd65afaf301f476dcfb7c3d21fa6c32dd198f3"
     },
     {
       "path": "index.d.ts",
-      "bytes": 10545,
-      "sha256": "218096340a1ac20451ce28a04c31c74881a37ff3dad065decfcc8ac03d883143"
+      "bytes": 11816,
+      "sha256": "2f579874839048da9bfdb207e8dc90941bfeae1b09d61e5f94d56d8780f2cb5c"
     },
     {
       "path": "index.mjs",
-      "bytes": 319145,
-      "sha256": "8cc48f64271c91392d8036ac4d361c08af310454b9a2132e80cd584858acb8da"
+      "bytes": 341503,
+      "sha256": "30f1ec52e914f24a2b0ae73d2ba8a14bcc8c05ae070a223ad7a9ff320d7e55af"
     },
     {
       "path": "react.cjs",
@@ -66,8 +66,8 @@
     },
     {
       "path": "rudiments.d.ts",
-      "bytes": 4579,
-      "sha256": "cde62af2e915cd2c7dd7ea2356cf877886642b019223f4dcff0b6f7753cc24c1"
+      "bytes": 4900,
+      "sha256": "e7e534e3c78addfafe8b3994a7c4931b36b22f93d1587ef4eeea842cc4f03964"
     },
     {
       "path": "server.cjs",
@@ -106,8 +106,8 @@
     },
     {
       "path": "wordpress.js",
-      "bytes": 188795,
-      "sha256": "a759919bdc14b8850adc8a68a87445fa6341d629113c282834d798b27da97e9c"
+      "bytes": 200656,
+      "sha256": "df31e8c47103cb28bbd0c12b230d6804cabd872882c8cbe35045e1bee11e1fcb"
     }
   ]
 }