@kieransimkin/dancemoves 3.0.2

package/RUDIMENTS-API.md

@@ -0,0 +1,394 @@
+# DanceMoves rudiment animation API
+
+API **1.0.0**, introduced by the **2.9.0 integration candidate**, based on released DanceMoves **2.8.0** (`4cb6a71f60459b5579be87d7e55ac8b1426c578e`). This source patch is not a published release or evidence of a WordPress deployment.
+
+The integration pins DanceRudiments **0.1.3**, commit `0df000db8753f04f397311f5b7c6ae6561e1d260`. The pinned C++ source, header and MIT licence are under [vendor/dancerudiments](vendor/dancerudiments/). [UPSTREAM.json](vendor/dancerudiments/UPSTREAM.json) records their Git blob identities. [TypeScript declarations](RUDIMENTS-API.d.ts) describe the complete public interface.
+
+## Contents
+
+[Architecture](#architecture-and-native-authority) · [Quick start](#quick-start) · [Catalogue](#catalogue) · [Service API](#service-api) · [Animation options](#animation-options) · [Controller API](#controller-api) · [Frame payload](#render-callback-payload) · [Clocks](#clock-and-lifecycle-contract) · [CSS](#css-and-html-contract) · [Events](#events-and-errors) · [Clay migration](#claystars-integration) · [WordPress](#wordpress-and-packaging) · [Build and validation](#building-and-testing) · [Limitations](#limits-and-extension-policy)
+
+## Architecture and native authority
+
+DanceRudiments defines positions; DanceMoves supplies musical time, lifecycle and rendering. There is no second audio clock, no beat detector, no LRC reparser and no JavaScript copy of a movement formula.
+
+The backend is a **complete-integer-domain C++/WASM lookup build**, not the upstream npm/Emscripten wrapper. This distinction matters:
+
+1. The build compiles and executes the unmodified upstream C++17 library. It samples **every** integer pip of **every** catalogue period, checking positive and negative wrap parity.
+2. The resulting IEEE-double values are emitted as hexadecimal C++ literals. Clang compiles those tables and a tiny C++ lookup ABI into import-free WebAssembly.
+3. The generated browser asset contains the native module as base64 plus catalogue metadata. JavaScript selects the pattern and musical pip; native WASM returns the three coordinates.
+
+For this pinned upstream API, each function depends only on a name and an integer pip, with a finite periodic domain. Exhaustively compiling that domain preserves the upstream sampling contract; it is not sparse curve fitting or a JS approximation. The 15 patterns comprise 1,856 unique positions. The shipped native module is 44,921 bytes, with fixed 128 KiB linear memory and no host imports. It does not call JavaScript trigonometry. The build compares all three axes at 5,568 wrapped positions against the native exporter, with tolerance `1e-12` for platform floating-point variation.
+
+The compiled browser asset is checked in. **No npm install, CDN access, Python interpreter, compiler or WASM MIME configuration is needed on the WordPress server.** Compilation is lazy and occurs once per document when `ready()` or `animate()` is used. If WASM is unavailable or blocked, loading rejects; there is deliberately no fallback JS motion implementation. Clay retains its existing CSS instead.
+
+This backend covers the pinned **integer-position** API only. Future upstream parameterised, stateful, curve or event APIs must receive a separately versioned binding. They must not silently be reduced to this fixed lookup contract.
+
+## Quick start
+
+Enqueue your page adapter with `dance-moves-rudiments` as a WordPress script dependency. That ensures the synchronous API object exists before the adapter executes; `ready()` handles asynchronous WASM compilation.
+
+```js
+const rudiments = window.DanceMovesRudiments;
+// window.DanceMoves.rudiments is the same object.
+const controller = rudiments.animate({
+  id: 'my-release:hero-sway',
+  rudiment: 'sway',
+  root: '.my-release',
+  target: '.my-release .moving-subject',
+  clock: 'audio',
+  audio: '.my-release audio',
+  amplitude: { x: 12, y: 0, z: 0 }
+});
+controller.ready.catch(error => {
+  console.warn('Rudiment unavailable; keep the static artwork.', error);
+  controller.destroy();
+});
+// On page-adapter teardown, call controller.destroy().
+```
+
+```css
+.my-release .moving-subject {
+  transform: translate3d(
+    var(--dance-moves-rudiment-x, 0px),
+    var(--dance-moves-rudiment-y, 0px),
+    var(--dance-moves-rudiment-z, 0px)
+  );
+}
+@media (prefers-reduced-motion: reduce), (forced-colors: active) {
+  .my-release .moving-subject { transform: none; }
+}
+```
+
+The target must already exist. Target a bounded decorative child, not player controls or a full-page colour layer. The default CSS renderer writes variables, **not** a `transform`, so it cannot overwrite an existing transform accidentally. A page may compose those variables with its own CSS transform or use a separate child for motion.
+
+For manual/native sampling without an animation controller:
+
+```js
+await window.DanceMovesRudiments.ready();
+const offset = window.DanceMovesRudiments.sample('clay_background', 100);
+// Approximately { x: -1, y: 0.9, z: 0 }; caller selects units.
+const pip = window.DanceMovesRudiments.pipsFromTicks(16); // 64, not 16
+```
+
+## Catalogue
+
+Use names as identifiers. `index` is native catalogue order for this pin, not a stable identifier across upgrades. Dimensions indicate occupied axes, not automatic mapping to a particular CSS direction. In particular, upstream's `bounce` description says vertical, but its single coordinate is returned in **x**; a vertical consumer must map x to its y translation.
+
+| Name | Period pips | Beats at rate 1 | Dimensions |
+| --- | ---: | ---: | ---: |
+| `bounce` | 64 | 1 | 1 |
+| `sway` | 128 | 2 | 1 |
+| `circle` | 64 | 1 | 2 |
+| `figure_eight` | 128 | 2 | 2 |
+| `step_touch` | 128 | 2 | 2 |
+| `box_step` | 256 | 4 | 2 |
+| `helix` | 256 | 4 | 3 |
+| `clay_background` | 256 | 4 | 2 |
+| `single_stroke_roll` | 64 | 1 | 2 |
+| `double_stroke_roll` | 64 | 1 | 2 |
+| `multiple_bounce_roll` | 64 | 1 | 2 |
+| `single_paradiddle` | 128 | 2 | 2 |
+| `flam` | 64 | 1 | 2 |
+| `drag` | 64 | 1 | 2 |
+| `five_stroke_roll` | 128 | 2 | 2 |
+
+## Service API
+
+The frozen service is available as both `window.DanceMovesRudiments` and `window.DanceMoves.rudiments` after the integration script executes. It does not replace `DanceMoves`, `KieranEpkMotion` or `DanceMovesEffects`.
+
+### Properties
+
+| Property | Value / meaning |
+| --- | --- |
+| `version` | `'1.0.0'`: this API's contract version, not the plugin version |
+| `upstreamVersion` | `'0.1.3'`: the bundled library version |
+| `upstreamCommit` | Exact pinned source commit |
+| `pipsPerBeat` | `64` |
+| `ticksPerBeat` | `16`: DanceMoves timing ticks |
+| `pipsPerTick` | `4` |
+
+### `ready(): Promise<RudimentApi>`
+
+Lazily compile and validate the bundled WASM ABI, pattern count and periods. Repeated calls return the same promise and never create duplicate native instances. Resolves with the service. Rejects when data is absent/incompatible, WASM compilation is unavailable/blocked or the native ABI disagrees. A rejected load is cached; reload the document after correcting the cause rather than creating a retry loop.
+
+`catalogue()`, `describe()` and unit conversion work before native compilation. `sample()` requires readiness. `animate()` obtains readiness internally and exposes its own `controller.ready`.
+
+### `catalogue(): readonly RudimentInfo[]`
+
+Return the frozen catalogue array; each record is also frozen. Fields: `name`, `description`, `periodPips`, `dimensions` and `index`. No WASM compilation is started by this call.
+
+### `describe(name: string): RudimentInfo | null`
+
+Exact, case-sensitive lookup. Returns the same frozen catalogue record or `null` for an unknown name. Does not create an instance.
+
+### `sample(name: RudimentName, pip: number): Offset3`
+
+Return a fresh `{ x, y, z }` native offset for an **integer** musical pip. Coordinates are dimensionless and normally within `[-1,1]`. Negative inputs wrap around the period. JavaScript safe integers larger than signed 32-bit are reduced to the period **before** entering the native signed-int ABI.
+
+Unknown names throw `RangeError`; non-numeric/non-finite inputs throw `TypeError`; fractions or unsafe integers throw `RangeError`; an unready backend throws `Error`. There is no implicit numeric-string coercion, interpolation, amplitude scaling, DOM write, timestamp conversion or registration.
+
+### `pipsFromTicks(ticks: number): number`
+
+Convert DanceMoves ticks to an integer pip: `floor(ticks * 4)`. Finite fractions and negative positions are allowed. A tiny `1e-9` pip tolerance prevents floating-point roundoff just below an exact musical boundary from selecting the preceding pip. The result must be a safe integer. Do **not** pass this value through `DanceMoves.quantizeTicks()`.
+
+### `pipsFromSeconds(seconds: number, bpm?: number): number`
+
+Convert seconds to pips: `floor(seconds * bpm * 64 / 60)`, with the same boundary tolerance. BPM defaults to the page's `DanceMoves.bpm`; explicit BPM must be finite and within `[20,400]`. Seconds must be a finite number. This is a pure conversion; it does not inspect audio playback or change the page BPM.
+
+### `animate(options: RudimentOptions): RudimentAnimation`
+
+Synchronously validate the registration, reserve its ID and return a controller with a `ready` promise. Mounting does not call `audio.play()` or change playback rate. The first eligible pose is rendered after native readiness; hidden, offscreen or manually paused mounts defer drawing until eligible. A destroyed pending mount cannot revive itself when compilation completes.
+
+Duplicate IDs are rejected, **not** silently replaced. Destroy the old instance first. Only one automatic CSS-output owner may target a given element. Multiple custom-render instances may share a target with `css:false`, but the page must keep their outputs separate.
+
+### `get(id: string): RudimentAnimation | null`
+
+Return the existing controller, including a pending or failed controller, or `null`. The ID is the exact trimmed registration ID. No new controller is constructed.
+
+### `snapshot(): object`
+
+Return `{ version, upstreamVersion, loaded, error, framePending, instances }`. `loaded` means the shared WASM backend compiled. `error` is the native-loading error or `null`; per-controller rendering errors are in `instances`. `framePending` refers only to this integration's shared scheduler, not all DanceMoves or theme animation. `instances` contains fresh controller snapshots, not live DOM references. No frame history, audio history, logging or telemetry is retained by the service.
+
+### `destroyAll(): void`
+
+Destroy every currently registered rudiment controller. It does not pause audio, destroy the core DanceMoves runtime or unload the shared WASM backend. The singleton's visibility/page-lifecycle listeners remain available for subsequent registrations. Prefer per-controller destruction when several page adapters coexist.
+
+## Animation options
+
+Options are fixed after construction except `enabled` and the local pause state. Change name, rate, amplitude, phase, target or audio by destroying and remounting. The provided object is not a supported live configuration channel.
+
+| Option | Type / default | Contract |
+| --- | --- | --- |
+| `id` | Required string | Trimmed, 1–160 characters, unique per document. Use a release/effect-specific stable ID. |
+| `rudiment` | Required catalogue name | Exact case-sensitive name. |
+| `target` | Required Element or selector | Must resolve now to one element. Selectors use `document.querySelector`. |
+| `root` | Element or selector; defaults to target | Lifecycle/visibility root; target must equal it or be its descendant. |
+| `clock` | `'page'` by default; `'audio'` or `'auto'` | Clock semantics below. |
+| `audio` | HTMLAudioElement or selector | Required for `audio` and `auto`. Ignored for `page`. Cannot be a video or arbitrary clock object. |
+| `rate` | Number; `1` | Rudiment cycles per native musical period; strictly greater than 0, at most 64. `0.5` doubles cycle duration. It is **not** `audio.playbackRate`. |
+| `phasePips` | Safe integer; `0` | Signed native-pip offset, applied after rate conversion. |
+| `amplitude` | Number or `{x?,y?,z?}`; `1` | Pixel gains. A scalar applies to all axes. Missing object axes are zero. Finite signed gains within ±10,000 are allowed; the page must choose appropriately bounded motion. |
+| `enabled` | Boolean; `true` | `false` displays a neutral zero-offset pose and stops sampling. |
+| `css` | Boolean; `true` | Write scoped x/y/z pixel custom properties. `false` leaves visual output entirely to `render`. |
+| `cssPrefix` | String; `'--dance-moves-rudiment'` | Prefix for `-x`, `-y`, `-z`; must match `^--[A-Za-z][A-Za-z0-9_-]{0,75}$`. |
+| `offscreen` | Boolean; `true` | Suspend outside the root's intersection when IntersectionObserver is available. No polyfill or offscreen suspension is promised without it. |
+| `resetOnCue` | Boolean or cue name; `false` | `true` subscribes to all core cues; a non-empty string selects one normalised core cue name. Matching audio or manual cues reset the phase origin. Unrelated players are ignored. |
+| `renderEveryFrame` | Boolean; `false` | Default suppresses unchanged-pip frame callbacks. `true` delivers continuous phase for companion art direction; native positions still use discrete integer pips. |
+| `render` | Optional function | Receives the frame payload after optional CSS output. Called synchronously; do not return a promise or create a second clock. |
+
+Invalid types/numbers/selectors throw synchronously before registration. A failed native or stylesheet mount rejects `controller.ready` and reports an error event. Runtime callback failures stop that instance, release its CSS ownership and report the error; unrelated instances continue.
+
+The controller snapshots the options used by the contract. Do not mutate callback payloads or use them as writable state; their TypeScript interfaces are readonly. Callback objects are short-lived observations.
+
+## Controller API
+
+`id` is readonly. `ready: Promise<RudimentAnimation>` resolves to the same controller when native/CSS setup is complete (drawing can remain deferred by lifecycle state); it can resolve to an already-destroyed controller when teardown happened during a successful shared load. It rejects on native, CSS-output or initial-render failure. Catch it even though the implementation internally marks rejection handled for fire-and-forget use.
+
+| Method | Result and lifecycle effect |
+| --- | --- |
+| `pause(): void` | Locally hold the last pose and remove the instance from the shared frame scheduler. Does not pause audio. |
+| `resume(): void` | Clear local pause and resample the current clock when permitted. Does not bypass `enabled:false`, reduced motion, forced colours, hidden/offscreen state or paused audio. |
+| `setEnabled(boolean): void` | Disable to neutral zero output and stop work; enable to reconstruct current position. Suitable for a quality-tier gate. Non-boolean values throw. |
+| `reset(): void` | Set the current source beat as the new phase origin; the next eligible sample starts at `phasePips`. Does not seek audio or replay events. |
+| `refresh(): void` | Reconcile lifecycle and render the current permitted pose, including a paused audio seek result. Local `pause`, hidden/offscreen and in-progress seeking continue to hold. |
+| `snapshot(): RudimentAnimationSnapshot` | Return serialisable diagnostic state; fields below. |
+| `destroy(): void` | Idempotently stop work, release ID/CSS ownership, remove audio/media-query/cue/intersection listeners and restore the target's original CSS cascade. |
+| `teardown(): void` | Exact alias of `destroy()`, for consistency with other DanceMoves adapters. |
+
+After destruction, lifecycle mutators are no-ops; `snapshot()` still works. `setEnabled()` still validates its argument. Do not remount from a stale destroyed handle; call the service with a new registration. The service automatically destroys registrations when their root or target is removed (MutationObserver when available, otherwise while a running frame is reconciled).
+
+Controller snapshot fields are `id`, `rudiment`, `status`, `enabled`, configured `clock`, `rate`, `phasePips`, `destroyed`, `loaded`, `error`, `updates`, last `pip`, last `sourceClock`, last pixel `position`, and `framePending`. `updates` counts payload publications, including lifecycle neutral updates; it is not the display's rendered FPS. Last-position fields are `null` before a first render. `loaded` remains true after a previously loaded controller is destroyed; consult `destroyed`/`status` for activity.
+
+Status values: `loading`, `running`, `paused`, `disabled`, `hidden`, `offscreen`, `reduced-motion`, `forced-colors`, `audio-paused`, `seeking`, `ended`, `error`, `destroyed`. They are observations, not a writable enum.
+
+## Render callback payload
+
+| Field | Meaning |
+| --- | --- |
+| `id`, `rudiment` | Registration ID and pattern name |
+| `root`, `target` | Actual elements; never serialise these into telemetry |
+| `audio` | Selected audio when using the audio clock; otherwise `null` |
+| `clock` | Resolved `'page'` or `'audio'`, never `'auto'` |
+| `sourceBeats` | Current source position in page-configured beats |
+| `bpm`, `rate` | Effective page BPM and rudiment rate |
+| `pip` | Wrapped integer in `[0,periodPips)`; `null` for neutral accessibility/disabled updates |
+| `positionPips` | Unwrapped integer pip after origin/rate/phase; likewise `null` for neutral updates |
+| `loopProgress` | Continuous wrapped phase `[0,1)` from the same clock; zero for a neutral update |
+| `durationMilliseconds` | One pattern cycle at page BPM and rudiment rate, expressed for audio playbackRate 1 |
+| `offset` | Native normalised `{x,y,z}`, or all zero for a neutral update |
+| `position` | Pixel `{x,y,z}` after amplitude scaling |
+| `reason` | `'frame'` or the status that caused a lifecycle publication |
+
+`loopProgress` exists for companion CSS/WAAPI art direction. It is not an interpolated native coordinate. `sample()` and `offset` remain exactly integer-pip based. A slow display skips visual samples and renders the latest pip; the API does not dispatch one event for each skipped pip or attempt timer catch-up.
+
+A custom renderer can consume normalised coordinates in another unit with `css:false`. It remains responsible for hiding/stopping its custom drawing on neutral updates and for cleaning up its own objects after controller destruction. `destroy()` removes integration resources; it cannot reverse arbitrary DOM/canvas mutations performed by a callback. Use CSSOM or WAAPI for visual updates where possible: writing inline `style` attributes inside the catalogue-owned root can invoke the existing catalogue timing observer.
+
+## Clock and lifecycle contract
+
+One DanceMoves tick is `1/16` beat; one native pip is `1/64` beat. The clocks are converted explicitly:
+
+```text
+page source beats = DanceMoves.currentTick({clock:'page'}) / 16
+audio source beats = audio.currentTime * DanceMoves.bpm / 60
+precise native pips = (source beats - reset origin) * 64 * rate + phasePips
+sample pip = positive modulo(floor(precise native pips + 1e-9), periodPips)
+loop duration ms = (periodPips / 64 / rate) * (60000 / page BPM)
+```
+
+`page` follows the existing page clock independently of audio. `audio` always reads the explicit player's current time, even while paused. It does **not** call `DanceMoves.currentTick({clock:'audio'})`, whose core implementation can fall back to the page clock. The new API therefore cannot accidentally resume ambient motion when a selected audio player pauses.
+
+`auto` uses page time until it observes the first playback of its selected audio (or the audio is already playing at mount). It then latches to that audio, including pauses/end; it does not switch back to page time. This preserves an ambient introduction without inventing a second timer. Auto's first page-to-audio transition clears the prior page-clock reset origin.
+
+`audio.playbackRate` already affects the rate at which `audio.currentTime` advances. Multiplying by it again would double-count the tempo. The `rate` option independently compresses/stretches the rudiment's musical period.
+
+On `seeking`, clear the old reset origin and hold the previous visual until `seeked`. On landing, reconstruct from the player's actual time; no skipped pattern samples or cue events are replayed. An explicitly enabled core cue reset may establish a new origin at a cue landing through the existing core event path. Pause holds the audio pose, and end stops frame scheduling. Replay/seek uses the same absolute-time rules.
+
+Hidden documents, pagehide, offscreen roots, reduced motion, forced colours and disabled instances do not keep an integration-owned RAF alive. When work becomes eligible again, sample the actual current position rather than integrating a wall-clock delta. With several eligible instances there is **one** shared RAF, not one per rudiment.
+
+`pause()` is a local pose hold, not transport time preservation: if the source continues, `resume()` jumps to its correct current phase. `reset()` is an explicit phase-origin change, not a tempo change. Existing DanceMoves core cue resets and the new `resetOnCue` option are distinct mechanisms; use the latter only when a page deliberately wants its native cycle to restart at cues.
+
+## CSS and HTML contract
+
+Automatic output creates a stylesheet rule targeting the generated `data-dance-moves-rudiment-owner` attribute on the exact target. It sets `<prefix>-x`, `<prefix>-y`, `<prefix>-z` as six-decimal **pixel** values with `!important`. It does not set `transform`, `translate`, colour, opacity, dimensions or positioning.
+
+The defaults are `--dance-moves-rudiment-x`, `--dance-moves-rudiment-y` and `--dance-moves-rudiment-z`. A target must not already contain the reserved owner attribute. Use `css:false` to opt out of this ownership contract. Do not use competing inline-important declarations for these reserved output variables.
+
+The stylesheet is `#dance-moves-rudiment-values`. Hot-path values update `CSSStyleRule.style`, **not** `target.style`; this avoids activating the existing catalogue adopter's subtree `style`-attribute observer on every sample. This does not mean CSS changes are free: rendering/style costs still need profiling on the full page. Only changed strings are written. The owned rule and attribute are removed on destroy, revealing the original author cascade; no original inline style is deleted or rewritten.
+
+Reduced motion and forced colours publish zero-offset output and stop scheduling. Retain page-level CSS fallbacks as well, especially for custom renderers and environments where the integration script never loads.
+
+## Events and errors
+
+Events are non-bubbling `CustomEvent`s dispatched on `document`.
+
+| Event | Detail | When |
+| --- | --- | --- |
+| `dance-moves-rudiments-ready` | `{api, version, upstreamVersion, upstreamCommit}` | Once after successful lazy native compilation |
+| `dance-moves-rudiments-error` | `{id, message}` | Shared load failure (`id:null`) or a specific mount/render failure |
+
+Subscribe before calling `ready()` when event order matters; events are not replayed to late listeners. Prefer the readiness promise for mounting. No per-pip DOM event is emitted, avoiding event storms.
+
+Synchronous registration errors throw. Asynchronous initial errors reject `controller.ready`; ongoing render errors set its state to `error`, stop its frame work and release CSS ownership. Failed controllers remain inspectable in the registry until destroyed. Native-loading failure can produce both the shared error and per-controller errors; consumers should not treat those as separate user-facing incidents.
+
+CSP can block WASM compilation or the generated stylesheet. A compatible policy must permit the bundled script, WebAssembly compilation and this style creation. Do not weaken a site's policy automatically. Correctly retain static/legacy rendering on failure and obtain a reviewed site-policy change where needed. No remote executable text, timing-file text or caller-provided CSS source is evaluated by this API.
+
+## Clay/Stars integration
+
+The existing release source assigns `ks-particle-dance` to `.ks-clay-stars-v2 .epk-atmosphere::after`, using `--dance-moves-128t`: **eight beats**. DanceRudiments' `clay_background` represents the positional waypoints in a 256-pip, **four-beat** period. Direct rate-1 substitution would double the visual speed.
+
+The bundled adapter therefore uses:
+
+```js
+// This is already mounted by assets/clay-stars-rudiments.js on page 252.
+// Do not paste a second copy into the WordPress page.
+const settings = {
+  id: 'clay-stars:background-rudiment',
+  rudiment: 'clay_background',
+  rate: 0.5,
+  amplitude: { x: 14, y: 10, z: 0 },
+  clock: 'auto',
+  cssPrefix: '--ks-clay-rudiment',
+  resetOnCue: true,
+  renderEveryFrame: true
+};
+```
+
+At page BPM 90 the cycle remains approximately `5333.333333ms`. The ±14px x and ±10px y gains restore the original positional scale; `--ks-master-intensity` continues to control the existing non-positional treatment rather than silently multiplying native translation.
+
+A new, release-scoped `ks-clay-rudiment-treatment` CSS animation preserves the original rotation, scale and opacity keyframes **without their translations**. CSS individual `translate` consumes the native position. The companion animation stays paused and its `currentTime` is explicitly scrubbed from the rudiment's `loopProgress`. Thus it does not introduce a separate free-running phase or leave the old translation active underneath the new one. Cloud drift, cover tilt, button choreography, lyrics, artwork, player behaviour and warm-light input are not replaced.
+
+The positional path now follows the **library's discrete, smoothstep-generated table**, rather than the old CSS's continuous linear interpolation between percentage waypoints. Source key percentages are also quantised to native pips. The waypoint vocabulary, spatial scale and eight-beat pace are preserved; byte-for-byte or pixel-for-pixel continuous trajectory identity is not claimed.
+
+Only a successful native mount sets `data-dance-moves-rudiment-clay="active"`. Required DOM/capabilities: the existing `.ks-epk.ks-clay-stars-v2` root, `.epk-atmosphere`, the existing `DanceMovesClayStars` runtime, CSS individual translate support and `getAnimations()`. The first root audio supplies `auto` playback timing; a missing audio explicitly selects the page clock. If prerequisites are absent, no migration is mounted and the existing CSS remains.
+
+The marker's states are `active`, `suspended` and `fallback`; it is absent before successful mounting and after teardown. `suspended` follows the existing Clay quality profile or disabled setting. In constrained/minimal profiles the existing static quality CSS remains authoritative and the native controller is disabled. Recovery re-samples the current clock. Reduced motion/forced colours also remove both translation and accents. This adapter does not create a competing quality sampler.
+
+### `window.DanceMovesClayRudiment`
+
+Available only after a compatible Clay mount attempt. It exposes `root`, `snapshot()` and `teardown()`.
+
+`snapshot()` returns `{status, error, destroyed, loaded, rudiment, cycleBeats, rate, controller}`. `status` is `loading`, `active`, `suspended`, `fallback` or `destroyed`; `controller` is the underlying controller snapshot or `null`. `loaded` means a native controller was mounted, not that it is currently running. Inspect `controller.status` for accessibility/transport state.
+
+`teardown()` is idempotent. It disconnects the adapter observer/error listener, destroys its native controller, removes the marker and restores the original CSS fallback. Root removal or teardown of the original Clay runtime also tears down this adapter. This is an adapter teardown, not a WordPress plugin deactivation.
+
+The underlying controller is available through `DanceMovesRudiments.get('clay-stars:background-rudiment')`. For normal page integration, let the bundled adapter manage its enabled state and teardown. Do not mount another controller on the same atmosphere element.
+
+### Adoption and rollback
+
+No WordPress page-content edit or new metadata is required for the existing page-252 adapter. The plugin's PHP integration enqueues the new assets behind the existing legacy-plugin coexistence guard. The compiled backend must be present before packaging; the package gate verifies it.
+
+Before publishing, check full/constrained/minimal, reduced motion, forced colours, hidden/visible, offscreen, pause/resume, both seek directions, exact chapter landings, playback-rate changes, long playback, deliberate WASM failure and teardown on the real page. Confirm that only one translation owner exists and that no catalogue rescan occurs per frame. Test signed out at desktop, tablet and narrow-mobile sizes; profile the complete effect stack.
+
+On native-load failure the original CSS remains active. To remove this migration from a staged/live build, disable its PHP enqueue module or restore the prior approved plugin package through the normal release procedure. `DanceMovesClayRudiment.teardown()` is a useful in-document diagnostic rollback; it is not a persistent deployment rollback.
+
+## WordPress and packaging
+
+The entrypoint requires `dance-moves-rudiments.php`. It defines `DANCE_MOVES_RUDIMENTS_API_VERSION` (`1.0.0`) and registers `dance_moves_enqueue_rudiments(): void` on `wp_enqueue_scripts` at priority **25**, after the existing core runtime's priority 20.
+
+| Handle | Type | Dependencies / scope |
+| --- | --- | --- |
+| `dance-moves-rudiments-native` | Footer script | Bundled C++/WASM asset; all WordPress Pages |
+| `dance-moves-rudiments` | Footer script | `dance-moves-core`, `dance-moves-rudiments-native`; all Pages |
+| `dance-moves-clay-rudiments` | Style | `dance-moves-clay-stars`; existing Clay page only |
+| `dance-moves-clay-rudiments` | Footer script | `dance-moves-rudiments`, `dance-moves-clay-stars`; existing Clay page only |
+
+The API can be used on any Page; only the release adapter is tied to the existing Clay page ID. Non-Page requests receive none of these assets. When `KS_CLAY_STARS_EFFECTS_VERSION` indicates the legacy Clay effects plugin, the reusable API still loads on Pages but the new Clay migration assets are suppressed.
+
+Cache versions combine the plugin version and API version. The patch increments the plugin candidate to **2.9.0** and aligns the known version-sensitive contract and phone-fixture cache keys. It does not publish that version, regenerate migration manifests or replace existing `dist` releases.
+
+`tools/package.ps1` verifies the native bundle before packaging and includes the new PHP module, both API-reference files and the pinned vendor directory, alongside the existing assets. The package retains `kieran-epk-device-orientation` as its WordPress upgrade slug. Tests and build tooling remain repository-only. The MIT licence accompanies both the vendored C++ and generated native browser asset.
+
+## Building and testing
+
+Normal consumers use the checked-in generated native bundle. Rebuild only when reviewing an upstream/library/backend change.
+
+```sh
+# Host GCC or Clang in C++17 mode; Clang must support wasm32 and have wasm-ld.
+# Python orchestrates compilation; it does not implement motion functions.
+python tools/build-rudiments.py --cxx g++ --clang clang++
+
+# Compare the committed backend against freshly executed upstream C++ samplers.
+# --check writes no repository files and needs only the host C++ compiler and Node.
+python tools/build-rudiments.py --check --cxx g++
+
+# Read-only package/hash/ABI gate; no compiler required.
+node tools/verify-rudiments.cjs
+
+node tests/rudiments-runtime.test.cjs
+node tests/clay-rudiments.test.cjs
+node tests/rudiments-source.test.cjs
+php tests/rudiments-wordpress.php
+tsc --noEmit --strict --lib es2020,dom RUDIMENTS-API.d.ts
+```
+
+`--cxx` and `--clang` accept executable paths; the host compiler needs GCC/Clang-style command-line arguments. The generator verifies vendored Git blob identities before compilation. It rejects unreviewed source edits rather than fetching a moving branch. Review a new exact upstream commit and source hashes deliberately, rebuild, rerun exhaustive parity, then update both the plugin release version and evidence.
+
+The build's local repeatability can be checked with output hashes. Different native math libraries/compilers can differ by floating-point roundoff for transcendental functions; cross-toolchain **bitwise** reproducibility is not guaranteed. The committed native asset and recorded digest are the release artifact; regeneration validates coordinates to `1e-12` and records compiler identities without wall-clock timestamps.
+
+The normal Unit validator discovers the new `.test.cjs` files and explicitly runs the PHP enqueue test. It remains necessary to run the existing DanceMoves suite. Package mode has its pre-existing migration/release-workspace prerequisites.
+
+[Browser fixture](tests/rudiments-browser.html) uses real integration code and WASM with explicitly labelled legacy API test doubles and locally generated silent audio. It is not the live Clay EPK. With Python Playwright and a permitted Chromium installation:
+
+```sh
+python tests/test-rudiments-browser.py --chromium /path/to/chromium --output qa/rudiments-browser
+```
+
+The fixture exercises pseudo-element translation, companion phase, real audio seeking, quality/accessibility state, failure fallback and teardown. It also counts inline style mutations. A browser navigation failure means the rendering tests did not run; it is not a pass. Headless results do not establish physical-device FPS, GPU cost, input latency or WordPress compatibility.
+
+## Limits and extension policy
+
+This API does not import timing files, infer BPM, synchronise multiple players, emit drumming stroke events, expose Python tooling in the browser or wrap unmerged future curve/event infrastructure. Each controller has an explicit clock/target; a new controller is required to change them. A pattern is sampled only at integer native pips, with no implicit interpolation.
+
+The core's animation-reset API does not own this controller's CSSOM variables; use `resetOnCue` deliberately. Conversely, the new controller does not own or stop unrelated core/theme RAF loops. `snapshot().framePending === false` means the rudiment scheduler is idle, not that the whole page is idle.
+
+CSSOM output still has rendering cost; callbacks allocate payload objects and may be expensive. Clay also updates a paused CSS animation's current time. Full-page performance must be measured before deployment. Browser rendering was not proven merely by native or mocked-DOM tests.
+
+As the upstream library grows, retain C++ as movement authority. For a future API whose domain cannot be exhaustively precompiled, add a direct compiled binding rather than inventing JavaScript formulas. Keep any new backend behind the same readiness, unit, lifecycle and capability-error contracts and document its compatibility separately.
+
+## Source references
+
+- [DanceMoves 2.8.0 source](https://github.com/kieransimkin/DanceMoves/tree/4cb6a71f60459b5579be87d7e55ac8b1426c578e): core clock, existing Clay adapter, stylesheet, enqueue and packaging contracts.
+- [Clay stylesheet and original keyframes](https://github.com/kieransimkin/DanceMoves/blob/4cb6a71f60459b5579be87d7e55ac8b1426c578e/assets/clay-stars-effects.css).
+- [Pinned DanceRudiments source](https://github.com/kieransimkin/DanceRudiments/tree/0df000db8753f04f397311f5b7c6ae6561e1d260): integer-pip contract, catalogue, C++ functions and MIT licence.
+- [Target public page](https://kieransimkin.co.uk/made-from-the-clay-and-the-stars-anunnaki/). The public page text was inspected; the integration is based on the pinned release source, not a claim that the modified runtime has been deployed there.

package/docs/README.md

@@ -0,0 +1,73 @@
+# DanceMoves documentation
+
+**Implemented baseline:** DanceMoves **2.8.0**, release tag `v2.8.0`, commit
+`4cb6a71f60459b5579be87d7e55ac8b1426c578e` (28 September 2026).
+This reference was checked against that source on 29 September 2026. It documents
+implemented behaviour, including limitations, rather than treating historical QA
+notes or planned harness work as a shipping API.
+
+DanceMoves is **Kieran Simkin's WordPress EPK motion runtime**, part of the wider
+**DanceFlow** BPM and motion-response workflow. It supplies shared timing, cue and
+lyric state, shared effect primitives, signed MP3 downloads, configurable paper-plane
+effects, CSS timing adoption, and permission-aware orientation input. A release
+supplies its own artwork, markup, players and visual language.
+
+The default branch is not the release baseline: `main` was still at 2.4.0 when
+reviewed. The staging branch `timed-lyrics-staging-2026-09-20` at
+`c95f24f326a5f5334e4fe63c1e705ec13b1d59d6` adds only publication evidence
+after `v2.8.0`; runtime and README are identical. This reference covers the release,
+not a hypothetical 2.9. See [source provenance](source-audit.md).
+
+## Read by task
+
+| Task | Reference |
+| --- | --- |
+| Install, configure a Page, prepare timing files, enable lyrics | [User and integration guide](guide.md) |
+| Mount pointer, pulse, cue-class, cue-timeline or quality effects | [Shared effect API](api/effects.md) |
+| Enable or integrate the paper-plane renderer | [Paper-plane API](api/paper-planes.md) |
+| Create reliable MP3 download links and understand the HTTP endpoint | [Download API](api/downloads.md) |
+| Call the musical clock, schedule work, subscribe to cues/lyrics | [JavaScript API](api/javascript.md) |
+| Read/write metadata, validate files, integrate PHP, submit captures | [WordPress, PHP and REST API](api/wordpress.md) |
+| Use timing variables, style lyrics, inspect DOM state | [CSS and HTML contract](api/styling.md) |
+| Integrate orientation, catalogue timing or Clay/Stars effects | [Adapters and orientation API](api/adapters.md) |
+| Run tests, use local harnesses, package and troubleshoot | [Development and operations](development.md) |
+| Check reference coverage and important implementation caveats | [Source audit](source-audit.md) and [symbol inventory](api/surface.json) |
+
+## Feature map
+
+| Feature | What ships | Important boundary |
+| --- | --- | --- |
+| Page properties | BPM, lyric attachment, cue attachment, lyric-pop-up opt-in, ambient-effect selection; hidden master duration | Attachment content validation on the editor save path is stronger than REST metadata sanitisation. |
+| Musical clock | 16 ticks per beat, duration quantisation, page and audio clocks, beat/bar helpers | A bar helper means four beats; this is not a meter or tempo-map engine. |
+| Cue timing | LRC-style timed labels, named/wildcard handlers, scoped animation resets, legacy event alias | `.cue` means the plugin's timestamped text format, not a CD cuesheet. |
+| Timed lyrics | One neutral visual layer, blank clears, playback/seek following, immediate-next and next-visible previews, callbacks and DOM events | Off by default; a release-specific design review is required before adoption. |
+| Shared effects | `pointer`, `playbackPulse`, `cueClass`, `cueTimeline`, `quality`; stable-ID instance management | Page code owns appearance; callback, transport and accessibility contracts differ between primitives. |
+| Signed MP3 downloads | Attachment-only GET/HEAD endpoint and rewriting of explicit upload download links | HMAC is not user authorisation or an expiring URL; players keep their original URLs. |
+| Paper planes | Page-configured hero effect, atlas sprites, compact mode, offscreen/hidden pause | DOM structure, CSS containment and count limits must be preserved; no user-facing tuning panel. |
+| Catalogue timing | EPK-owned stylesheet, inline, computed and pseudo-element timing conversion | It cannot rewrite canvas/WebGL phase logic or supply an arbitrary new root registration API. |
+| Orientation | Nine release adapters, permission UI, rolling mapping, latest-sample frame coalescing and two-tick target writes | Mobile/capability detection and reduced motion gate the production input runtime. |
+| Clay/Stars | Cover/light response, particle release, cue state and recoverable performance tiers | Page 252 only; the legacy effects-plugin constant suppresses takeover. |
+| Motion capture | Bounded, sanitised JSON saved as private WordPress posts | Dedicated submission endpoint, not automatic tracking or a secure user-authenticated telemetry service. |
+| Diagnostics | Explicitly enabled synchronous timing sink and bounded catalogue evidence | No core diagnostic retention/transmission; external consumers own their storage and privacy obligations. |
+| Development | Contract tests, local harnesses, deployment evidence and package tooling | Tests and harness globals are not front-end production APIs. |
+
+## API scope and compatibility
+
+The documented integration surface is `window.DanceMoves` (also exposed as
+`window.KieranEpkMotion`), `window.DanceMovesEffects`, the documented conditional adapter globals, the PHP
+helpers and WordPress metadata/REST contracts. The internal orientation lifecycle
+object is documented for diagnostics but is not a general adapter registry.
+
+There are **no plugin shortcodes, Gutenberg blocks, WP-CLI commands, custom
+DanceMoves action/filter extension points, stem-separation models, automatic BPM
+analysis, track-loop extraction, or public capture-reading endpoint** in this
+baseline. The plugin consumes prepared timing data; it does not call StemLab or a
+React timeline service. Those projects can participate upstream in a DanceFlow
+workflow without implying an implemented network integration here.
+
+All source links in these documents are repository-relative. The exact audited
+blob identifiers are recorded in [surface.json](api/surface.json). When reading a
+newer checkout, compare the exports and configuration against that inventory.
+The root README contains current usage and troubleshooting. Dated evidence in Git,
+`migration/`, `qa/` and the [test plan](../TEST-PLAN.md) does not establish the status
+of a newer build or deployment.