@kieransimkin/dancemoves 3.1.20 → 3.1.22

package/README.md

@@ -1,10 +1,22 @@
 # DanceMoves
 
+**3.1.22** fixes WordPress.org submission metadata: the Author URI points to
+[Kieran's website](https://kieransimkin.co.uk/), separately from the plugin
+homepage. The release checker rejects duplicate plugin/author URLs before
+packaging. The plugin name remains **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

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

@@ -76,3 +76,10 @@ 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/docs/wordpress-org.md

@@ -1,5 +1,11 @@
 # WordPress.org publication
 
+The plugin and author URI headers must identify different pages. The author
+header uses https://kieransimkin.co.uk/; the plugin retains its published My Songs
+homepage. `npm run check:release` rejects duplicate URLs (including a trailing
+slash variation), matching the directory upload validation. Keep the public
+plugin name **DanceMoves** and its existing compatibility identifiers.
+
 Run the official Plugin Check against the exact production ZIP with the intended directory slug. Do not scan tests as installed runtime code, ignore an entire category or treat a passing static scan as a security audit. Review all warnings and document each contextual finding. Keep the readme stable tag, main PHP version and GitHub release aligned. After directory approval, publish the same verified source through the assigned SVN repository; verify the downloaded directory ZIP independently. No directory password belongs in source.
 
 ## Potential problems

package/lib/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.20",
+  "version": "3.1.22",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
@@ -31,23 +31,23 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 201822,
-      "sha256": "2c2f314a6582488e8c969009ff7115428f6bcf8b5f0b1467c683adca59cdd30b"
+      "bytes": 212321,
+      "sha256": "36651cd57003477609ac0024c66ae69698cf51ef1ae083f3dd25e7a7ad41e3c4"
     },
     {
       "path": "index.cjs",
-      "bytes": 342587,
-      "sha256": "9bdad4f199b86ea24644342c7fbd65afaf301f476dcfb7c3d21fa6c32dd198f3"
+      "bytes": 361185,
+      "sha256": "1f02fb91fa046ac132a0757ceed994843adae20728fbb80327a1ea6c314a515a"
     },
     {
       "path": "index.d.ts",
-      "bytes": 11816,
-      "sha256": "2f579874839048da9bfdb207e8dc90941bfeae1b09d61e5f94d56d8780f2cb5c"
+      "bytes": 13718,
+      "sha256": "82ec16610754f0237cd91e2a7a7ce4f6fe17617d8a61b78d089143e9fdb142e4"
     },
     {
       "path": "index.mjs",
-      "bytes": 341503,
-      "sha256": "30f1ec52e914f24a2b0ae73d2ba8a14bcc8c05ae070a223ad7a9ff320d7e55af"
+      "bytes": 360040,
+      "sha256": "1766fb4365f13191b75dc77ac01c9e51c8e8250e8408c34a7d7bf19ce77fe32b"
     },
     {
       "path": "react.cjs",
@@ -106,8 +106,8 @@
     },
     {
       "path": "wordpress.js",
-      "bytes": 200656,
-      "sha256": "df31e8c47103cb28bbd0c12b230d6804cabd872882c8cbe35045e1bee11e1fcb"
+      "bytes": 211126,
+      "sha256": "fcea9c493f3e895320eb15673580cdfebd6b8fd333cd90e2a11c0054fbe8317d"
     }
   ]
 }