@kieransimkin/dancemoves 3.1.16 → 3.1.18

package/README.md

@@ -1,5 +1,10 @@
 # DanceMoves
 
+`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
+fan-out, motion switches and lifecycle verification.
+
 [![DanceMoves logo](https://raw.githubusercontent.com/kieransimkin/DanceMoves/v3.1.14/docs/branding/logo.png)](https://kieransimkin.co.uk/danceflow/)
 
 By **[Kieran Simkin](https://kieransimkin.co.uk/)** · [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/) · [Vector logo and usage guide](docs/branding/README.md).
@@ -937,3 +942,7 @@ minimal reproduction, expected/actual result and relevant evidence. Do not put
 one-off command mistakes, private workspace paths or resolved incident diaries
 back into this section. Existing release and deployment history remains in Git,
 `migration/` and `qa/`.
+
+## 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/

package/docs/phone-motion-connections.md

@@ -0,0 +1,30 @@
+# Connect existing spatial effects to phone input
+
+`runtime.connectPhoneMotion()` composes the shared permission-aware orientation controller with existing pointer handles and a narrow appearance callback. It does not select choreography or add artwork. Call it after the mount's `ready` promise so the page's pointer handles exist. Use one connection per page, listing all suitable spatial consumers.
+
+```js
+await runtime.ready;
+const connection = runtime.connectPhoneMotion({
+  pointers: ['release:hero-depth', 'release:artwork-depth'],
+  enabled: () => root.dataset.motion !== 'off' && root.dataset.quality !== 'static',
+  watchAttributes: ['class', 'data-motion', 'data-quality'],
+  render: ({x, y}) => {
+    root.style.setProperty('--release-light-x', String(x));
+    root.style.setProperty('--release-light-y', String(y));
+  }
+});
+```
+
+Pointer IDs are resolved for every sample, so a motion switch can replace a pointer without leaving a stale sensor attachment. The render callback may map the same normalized coordinates to other release-owned CSS properties. Keep targets bounded and callbacks nonthrowing. The connection clamps both axes to [-1, 1] and sends zero/reset when suspended. Leave ordinary interactive button hover/focus and scroll controls independent.
+
+Options: `pointers` (string array), `render` (callback), `enabled` (predicate), `watchAttributes` (attributes on the mount root that require reconciliation), `controlParent` (default document body) and `windowMilliseconds` (default 10000). Attribute observation deliberately excludes style writes by default. Call `reconcile()` after an application-owned state change that is not represented by the watched attributes.
+
+On supported secure mobile/touch devices, browsers requiring permission receive a single **Use phone motion** button. Only its click or an explicit gesture calling `enable()` requests permission. Browsers without that method listen directly unless the visitor previously disabled input. A stored enabled choice restores listening without requesting permission. Finite delivered samples establish `sensorActive` and remove the button. With no readings, the 3.5-second check retains **Use phone motion** for permission browsers or shows **Phone motion unavailable** for a direct-listener browser. Permission denial displays **Phone motion blocked**. These states do not certify hardware or browser permission.
+
+If the mount already owns a legacy orientation provider, the connection subscribes to that provider instead of starting a second sensor listener or permission control. That provider retains its existing calibration/window and appearance. Its `subscribe(callback)` returns an unsubscribe function and forwards committed normalized samples plus reset/teardown. `suspend(boolean)` temporarily stops input and controls without changing the visitor's stored choice. No release selectors or identifiers are added to the shared connection.
+
+Reduced motion, forced colours, page hiding, pagehide/pageshow, screen rotation, explicit application enable predicates and mount teardown remain authoritative. Generic orientation controllers also expose `setActive(boolean)` for temporary suspension; `disable()` is a persistent opt-out. The connection returns `enable()`, `reconcile()`, `snapshot()` and `destroy()`. Destroying it removes its control/listeners/observer and resets its consumers; an existing shared provider remains owned by the runtime.
+
+Desktop or unsupported connections create no sensor listener, UI or appearance writes. Existing desktop pointer controllers remain independent. The connection does not create a new quality monitor; use the page's existing quality predicate. Tests must verify all mapped consumers, permission/no-data paths, preference changes and lifecycle cancellation. Physical iPhone/Safari delivery and full-stack frame-rate acceptance require physical evidence, separately from synthetic browser tests.
+
+Quality owners reconcile live preferences while sampling frames as well as on media notifications. A temporarily imposed accessibility tier restores its saved tier promptly; performance recovery cooldowns apply only to measured performance changes.

package/docs/phone-motion-preference.md

@@ -16,6 +16,9 @@ request permission. A denied request stops listening and records disabled.
 Pages without a tilt adapter do not acquire a new effect.
 
 The reusable `createOrientation()` controller follows the same stored choice.
+Use [`connectPhoneMotion()`](phone-motion-connections.md) to attach suitable existing
+pointer handles and appearance callbacks with shared permission UI and lifecycle
+gates. It reuses an existing orientation provider when one is already mounted.
 Its `enabled` and `listening` snapshot fields describe local intent/listener
 state, not verified browser permission or sensor delivery. Applications retain
 ownership of their enable UI. Reduced motion, forced colours and hidden-page

package/lib/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.16",
+  "version": "3.1.18",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
@@ -31,23 +31,23 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 184408,
-      "sha256": "1fa439e1847c95207c3530400fe1337c61f0d8dbe2ca786dab25d9b5097ed4e5"
+      "bytes": 189980,
+      "sha256": "5972c3cf36acf9cdb2781c97044772d946cc9c1f39b7f988b10ede87c75de0e4"
     },
     {
       "path": "index.cjs",
-      "bytes": 309993,
-      "sha256": "37ce10184557c1bf51d736baa499661522c8a20529e14550d577ba8008ce5669"
+      "bytes": 320229,
+      "sha256": "c081cee16c6023f768844d8a5f2505b63c959407ad073981fa1d95f51e1b3194"
     },
     {
       "path": "index.d.ts",
-      "bytes": 10104,
-      "sha256": "5f31e6f495fd92715e7734b497b3eba16a4f75264924b4f9481cdb366345da68"
+      "bytes": 10545,
+      "sha256": "218096340a1ac20451ce28a04c31c74881a37ff3dad065decfcc8ac03d883143"
     },
     {
       "path": "index.mjs",
-      "bytes": 308909,
-      "sha256": "8226b65bb31025fca6419d596d648dd2035c6e1185f1422003812796cd4db4d6"
+      "bytes": 319145,
+      "sha256": "e6aa6994b440a0eb68894c181428ec4f5fff934ae50c5d84c153eb904a534764"
     },
     {
       "path": "react.cjs",
@@ -106,8 +106,8 @@
     },
     {
       "path": "wordpress.js",
-      "bytes": 183218,
-      "sha256": "ed4ae4ae533b7047ca47eea4fb93bf3aa6c6611b8e65b3db26057f1b44593180"
+      "bytes": 188795,
+      "sha256": "674ddf2c62e4c183153c52efdfc4ef9ca4b5c962b5f090feea7b166bb4fe8c25"
     }
   ]
 }