@kieransimkin/dancemoves 3.1.19 → 3.1.21

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,17 @@
 # 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.
+
+**3.1.21** adds `publishPlayback()` and `receiveChildPlayback()` to connect an explicitly selected
+child watch page to its parent runtime. The parent retains its existing cues,
+lyrics and effect owners; closing or losing the child stops its clock. The
+integration composes with the shared player API and requires its verified
+master/excerpt mapping. See [child-page playback](docs/child-playback.md) and the
+[standalone/modal example](examples/child-playback/README.md).
+
 `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 +958,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/child-playback.md

@@ -0,0 +1,94 @@
+# Playback from a child watch page
+
+The parent EPK owns its timing metadata, master association and existing effect
+controllers. A watch page owns its visible player. DanceMoves forwards the
+child's actual playback state into the parent's shared player transport. It
+does not forward cue labels, timing-file URLs, artwork or choreography.
+
+```js
+// Parent: mount the runtime and its effects before opening the modal.
+// Register after the selected master duration is known.
+const child = motion.receiveChildPlayback({
+  iframe: document.querySelector('#watch-frame'),
+  origin: location.origin,
+  channel: 'watch-player',
+  assetId: 'verified-published-video-id',
+  master: document.querySelector('audio'),
+  masterVerified: true,
+  offset: 0, duration: 180
+});
+await child.ready;
+// The existing motion.playbackSource(master) now follows the child.
+// On modal close, dispose BEFORE removing the iframe:
+child.teardown();
+```
+
+```js
+// Child watch page: its real player is present on initial load.
+// Standalone visits have no parent bridge or autoplay.
+if (window.parent !== window) {
+  const publisher = motion.publishPlayback({
+    source: motion.playbackSource(master), // Native or registered YouTube transport.
+    targetWindow: window.parent,
+    origin: location.origin,
+    channel: 'watch-player',
+    assetId: 'verified-published-video-id'
+  });
+  // Dispose on route removal; runtime destruction also disposes the publisher.
+}
+```
+
+The scoped receiver requires the shared `registerPlaybackProvider`/`playbackSource` API.
+Both low-level `createPlaybackReceiver()` and `createPlaybackPublisher()` are
+exported for composition outside a mounted runtime. Their `window` option is an
+explicit browser Window; module import is safe during SSR.
+
+Supply an exact HTTP(S) origin including its port, never `*` or an opaque
+origin. Source Window, channel, asset ID, a fresh receiver session, monotonic
+sequence and finite bounded numeric state are checked on both sides. The asset
+ID is a caller-selected identity, not runtime proof of soundtrack provenance.
+Each frame has one receiver and each explicit route has one publisher until
+teardown; reuse their transports for additional effect consumers.
+Preserve verified published player IDs, render/source hashes and master mappings
+outside the runtime. Do not bind unrelated edits using equal titles/durations.
+
+Playback state includes position, duration, rate, pause, seek, buffering, end and
+error. Position updates are coalesced to four per second; transport changes
+remain immediate. The receiver interpolates between samples for
+at most 500 ms and stops a playing source after 1500 ms without data. The
+`staleAfterMilliseconds` option accepts 750–10000 ms. Native media events can
+arrive sooner. No independent cue/beat parser or animation scheduler is added.
+After a stale connection, call `reconnect()` to start a fresh session and await
+its returned readiness promise; late packets from a disconnected session cannot
+restart it. `ready` exposes the current connection attempt.
+
+Parent pause and seek commands reach the child; parent play is rejected unless
+the publisher explicitly enables `allowPlayCommands:true`. Browser autoplay
+policies still apply and play-command rejection is observable through the
+returned promise. Registering, reconnecting and receiving state never starts
+media. Use real visitor controls and preserve consent flows before registering
+a YouTube iframe. The parent does not play a muted duplicate soundtrack.
+
+For Escape inside the child document, enable `notifyEscape:true` on the
+publisher and subscribe to the receiver player's `dismiss` event to close the
+dialog. Explicit child close buttons may call `publisher.requestClose()`.
+Fullscreen retains its native Escape behaviour. Cross-origin nested players
+may keep keyboard events in their own document; keep a visible parent close
+control and test the actual embed's keyboard behaviour separately.
+
+Frame load, visibility suspension and page restoration rotate the session.
+Closing/removing the frame, pagehide, stale data and teardown stop the remote
+clock; teardown also asks the child to pause and removes timers/listeners.
+`ready` rejects after ten seconds without valid metadata or when removed before
+readiness. Catch readiness failures and show accurate availability. A ready
+bridge does not prove public playback or Google classification.
+
+The parent source retains existing reduced-motion, forced-colour, quality,
+visibility, cue/seek reconciliation and cleanup policies. The modal adapter owns
+only dialog focus, ordinary controls, the iframe and lifecycle calls. Keep a
+normal crawlable watch-page link and a player visible on the standalone page.
+The browser fixture uses original synthetic media and tests cross-document
+playback, seek, rate, preferences and removal; it is not physical Safari or
+phone performance evidence.
+
+Protocol design follows [Window.postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

package/docs/playback-sources.md

@@ -0,0 +1,85 @@
+# 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).
+
+`registerPlaybackProvider()` registers an explicit non-DOM, event-driven player
+with the same verified master and excerpt mapping. It accepts the
+media-compatible player produced by the [child-page receiver](child-playback.md).
+Native DOM players retain `registerPlayer()` and its runtime-root checks.
+Provider registrations share ownership, cue/lyric dispatch and teardown; no
+additional timing engine or hidden media element is created.

package/docs/shared-feature-coverage.md

@@ -7,6 +7,7 @@ physical tests were executed in a restricted development environment.
 
 | Feature | Shared entry/API | Demo/test coverage |
 |---|---|---|
+| Child watch-page playback | `publishPlayback`, `receiveChildPlayback`, low-level receiver/publisher | Origin/session/state and lifecycle contracts; standalone/modal synthetic-media browser example |
 | BPM, ticks, duration quantization, boundaries | Main factory/core methods | Existing clock/scheduling/interval gallery; original core tests |
 | CSS timing/control/lyric disclosure | Core properties + CSS | WordPress-style clock/shared timing demos; original CSS contracts |
 | Named cues, intervals, DOM events, animation ownership | Core methods | React cue panel; original 23-page gallery and core contracts |

package/lib/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.19",
+  "version": "3.1.21",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
@@ -31,23 +31,23 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 189980,
-      "sha256": "2d9f8a6b5ac0ff32d6f940c31c16213e145c85c48fc9957ee2e405ce91d02d02"
+      "bytes": 212321,
+      "sha256": "540af619a286599f2340cb35f70294a70e6899d834b24d0c18a5cbd6b1d1c023"
     },
     {
       "path": "index.cjs",
-      "bytes": 320229,
-      "sha256": "df4670757481c736796dd9878148f33a2a7095713851f2d14218e6efeb4edd4a"
+      "bytes": 361185,
+      "sha256": "8c5b70cafdeb0135a8d4d4afd03a4a72064f71f75443bb253cace82de639bd1a"
     },
     {
       "path": "index.d.ts",
-      "bytes": 10545,
-      "sha256": "218096340a1ac20451ce28a04c31c74881a37ff3dad065decfcc8ac03d883143"
+      "bytes": 13718,
+      "sha256": "82ec16610754f0237cd91e2a7a7ce4f6fe17617d8a61b78d089143e9fdb142e4"
     },
     {
       "path": "index.mjs",
-      "bytes": 319145,
-      "sha256": "8cc48f64271c91392d8036ac4d361c08af310454b9a2132e80cd584858acb8da"
+      "bytes": 360040,
+      "sha256": "c23dfac191d589e317d65ec0c56beacf1f02129c1c78e37493a6d6c3a33dc6db"
     },
     {
       "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": 211126,
+      "sha256": "f7c6f992c84282032e9a9b4257e2538c2424ee41aba07daf6a8957352c4f0f80"
     }
   ]
 }