@kieransimkin/dancemoves 3.0.2

package/docs/javascript-api.md

@@ -0,0 +1,292 @@
+# Shared JavaScript API
+
+Package: `@kieransimkin/dancemoves`, source candidate 3.0.0.
+This guide describes the public shared module; [WordPress](wordpress-shared-runtime.md)
+loads the same runtime through its adapter.
+
+## Installation and first mount
+
+After publication:
+
+```sh
+npm install @kieransimkin/dancemoves
+```
+
+From this repository before publication, run `npm install --ignore-scripts`,
+commit the generated lockfile, and run `npm run build`. The included demos resolve
+the built package through the repository's own package exports, not a registry
+copy or a sibling checkout.
+
+```js
+import {createDanceMoves} from '@kieransimkin/dancemoves';
+import '@kieransimkin/dancemoves/styles.css';
+
+const root = document.querySelector('#arcadians');
+const runtime = createDanceMoves({
+  root,
+  bpm: 145,
+  lyricTimingUrl: '/media/canonical-lyric-timing.lrc',
+  cueTimingUrl: '/media/sections.cue',
+  masterDurationMilliseconds: 273604.558
+});
+await runtime.ready;
+const stopBeat = runtime.onEveryBeat(({boundaryTick}) => {
+  root.dataset.lastBeat = String(boundaryTick / 16);
+}, {id: 'arcadians:beat'});
+
+// Route/component cleanup:
+stopBeat();
+runtime.destroy();
+```
+
+The root must exist in a browser document. It can contain normal HTML `<audio>`
+elements. The library does not autoplay audio. The canonical discovery rules,
+including explicit `data-dance-moves-master` and configured master-length
+matching, are retained. Mount before starting playback; call `discoverAudio()`
+after adding players dynamically when immediate discovery is required.
+
+Imports are safe during SSR. Only `createDanceMoves` requires the browser.
+CJS is available with `require('@kieransimkin/dancemoves')`. The independent
+`/server` entry requires Node; `/react` requires React; importing the main module
+does not import either dependency.
+
+## Mount configuration
+
+| Option | Default and contract |
+|---|---|
+| `root` | Required Element. One mount per non-overlapping subtree. |
+| `bpm` | Missing/null/empty selects 120 fallback. Otherwise a finite **number** from 20 to 400, rounded to three decimals. Changing tempo requires a new mount. |
+| `pageId` | 0. Optional non-negative safe integer for diagnostics/legacy catalogue settings, not a requirement to have WordPress. |
+| `bpmSource` | Computed; a supplied `fallback` preserves fallback provenance when converting host config. |
+| `lyricTimingUrl`, `cueTimingUrl` | Empty. HTTP(S) or relative URLs; no embedded credentials or executable schemes. Served media must satisfy normal browser CORS rules. |
+| `lyricPopupsEnabled` | false. Boolean, explicit opt-in to the canonical neutral renderer. Use `onLyric` or the React hook for custom treatments. |
+| `masterDurationMilliseconds` | 0 (no length reference); finite number up to one day, rounded to three decimals. |
+| `sharedControlTicks` | 0; enables the inherited control-duration treatment when positive. |
+| `lyricDisclosureTicks` | 6; positive duration ticks. |
+| `effect` | Empty or `paper-planes`. |
+| `catalogue` | false; opt-in CSS timing adoption. |
+| `clay` | false; initialize Clay and its native background adapter when the required Clay markup exists. |
+| `clayPerformance` | Per-mount overrides for the existing Clay monitor. Fields retain their canonical validation and defaults. |
+| `orientation` | Optional `{adapter, transitionTargetTicks, harness}`. Adapter is one of `ORIENTATION_ADAPTERS`. Harness remains loopback-only. |
+| `paperPlanes` | `{atlasUrl, planeCount, compactPlaneCount}`. The atlas URL is required with `effect:'paper-planes'`; use the shipped asset, not a fabricated sprite. |
+| `diagnostics` | false; explicitly enables diagnostic sinks. |
+| `legacyGlobals` | false. WordPress compatibility mode; one per document, not for ordinary React roots. |
+| `nonce` | Optional nonce attached to library-created style elements for an application's CSP. |
+| `onError` | Optional callback for asynchronous readiness and cleanup errors. Handle individual native-controller `ready` failures as well. |
+
+A bad root, overlapping mount or unknown adapter throws. Invalid config values
+throw `TypeError`/`RangeError`; the public API does not silently turn bad BPM into
+another tempo. `readWordPressConfig` is an internal wire adapter because
+WordPress localization stringifies scalar values; generic JS should use typed
+values directly.
+
+`runtime.ready` completes canonical cue/lyric-file setup. Existing nonfatal file
+fetch behaviour is preserved: an empty/unavailable timing file is not proof of a
+working lyric track. Read native readiness separately with
+`await runtime.rudiments.ready()`. `destroy()` is idempotent, aborts internal work
+and removes resources; it does not stop or delete your audio element.
+
+## Core methods: complete inherited surface
+
+The core has **16 ticks per beat**. A tick lasts `3750 / bpm` milliseconds.
+The native library uses **64 pips per beat**, so one core tick is four pips.
+A bar in the convenience methods is four beats.
+
+| Method | Meaning |
+|---|---|
+| `quantizeTicks(value)` | Round half up, minimum one; durations above 16 ticks round to multiples of 16. |
+| `durationMilliseconds(ticks, bpmOverride?)` | Quantized duration at configured/override BPM. Not a raw interval-spacing conversion. |
+| `currentTick(options?)` | `{clock, audio, bpm}`. Uses a supplied/active playing audio clock; otherwise page elapsed time. A paused audio element does **not** give a paused clock through this legacy helper. |
+| `nextIntervalTick(interval, fromTick, strictlyFuture?)` | Next integer-spaced interval boundary; interval spacing is not the long-duration quantizer. |
+| `scheduleAtInterval(interval, callback, options?)` | Schedule a page/audio boundary and return a cancellation function. |
+| `deferStart(element, interval, options?)` | Defer an element's visual start; returns cancellation. The canonical start attributes/options remain available. |
+| `onNextInterval(callback, interval, metadata?)` | Next available audio boundary; returns unsubscribe. |
+| `onEveryInterval(callback, interval, metadata?)` | Repeating audio interval handler; unsubscribe on cleanup. |
+| `onNextBeat(callback, metadata?)` | `onNextInterval` at 16 ticks. |
+| `onEveryBeat(callback, metadata?)` | Repeating 16-tick audio boundaries. |
+| `onNextBar(callback, metadata?)` | Next 64-tick boundary. |
+| `onEveryBar(callback, metadata?)` | Repeating 64-tick boundaries. |
+| `normaliseCueName(value)` | Canonical uppercase normalized matching name. |
+| `parseTimingFile(text)` | Parse bracketed timestamps and named/type cues, sorted by time. |
+| `parseLyricTimingFile(text)` | Parse lyrics including empty clear entries, sorted by time. |
+| `onCue(name, handler, metadata?)` | Subscribe to a name or `*`; returns unsubscribe. |
+| `onLyric(handler, metadata?)` | Subscribe to canonical lyric details; returns unsubscribe. |
+| `fireCue(cue)` | Dispatch through the same named-cue/diagnostic/event path. Supply `{name,type,time,audio?}`. |
+| `registerAnimationScope(root, selectors)` | Explicit ownership of animations that may be reset/speed adjusted by cues. Returns removal function. |
+| `resetRunningAnimations(audio?)` | Reset owned running/pending animations; returns reset count. Not a global animation reset. |
+| `discoverAudio()` | Discover eligible audio in this mount. |
+| `setDiagnosticsSink(callbackOrNull)` | Returns false unless diagnostics was enabled at mount. Sink exceptions are contained. |
+| `diagnosticsEnabled()` | Current sink status. |
+
+Interval callbacks receive `{intervalTicks,boundaryTick,audio,clock}`. Metadata
+can be a handler ID string or `{id,handlerId}` for attribution. Repeating
+intervals preserve the core's seek/deduplication behaviour; use `cueTimeline`
+for deterministic state restoration instead of treating interval callbacks as
+an event-history replay mechanism.
+
+Additional mount properties/methods are `version`, `bpm`, `bpmSource`,
+`ticksPerBeat`, `root`, `config`, `ready`, `destroyed`, `destroy()`, `resources()`
+and `on(eventName, listener)`. `on` returns unsubscribe. Resources reports owned
+listener/timer/frame/observer/generated-node counts, not the browser's entire
+resource inventory.
+
+## Timed files and lyrics
+
+Both cue and lyric files use `[mm:ss.cc]`-style timestamps, optionally three-digit
+fractions. Here `.cue` means the plugin's bracketed cue format, **not a CD
+cuesheet**. Example:
+
+```text
+[01:25.00][BUILD: Build 1]
+[01:44.01][DROP: Drop 1]
+[03:07.54][DROP: Final Drop]
+```
+
+Lyric example with an explicit gap:
+
+```text
+[00:02.89]No crown, no concrete
+[00:07.76]
+[00:07.81]Just mountain breath and moonlit stone
+```
+
+The lyric callback contains `pageId`, `time`, `text`, `normalisedText`, `index`,
+`nextTime`, `nextText`, `nextNormalisedText`, `nextIndex`, `nextVisibleTime`,
+`nextVisibleText`, `nextVisibleNormalisedText`, `nextVisibleIndex`, and `audio`.
+Immediate-next fields can describe a blank clear; next-visible fields skip
+blanks. Absent times are null, text empty and indices -1.
+
+Pause/end do not manufacture empty core lyric events. A custom renderer should
+hide on audio pause/end; `useLyric` already clears its state for pause, end and
+seeking. Render text with `textContent`/React text, not HTML injection. Styling the
+neutral popup differs in scoped mode (inside the root) and WordPress legacy mode
+(under body). The built-in neutral style is not song-specific art direction.
+
+## Shared effect primitives
+
+`runtime.effects` is the canonical registry for this mount. `get(id)` returns a
+controller or null, `snapshot()` returns controller snapshots, `teardown(id)`
+removes one, and `teardownAll()` removes all. Reusing an ID replaces that local
+registry entry. Each factory returns `id`, `type`, `snapshot()` and `teardown()`.
+Pass Elements or scoped selector strings for roots/targets.
+
+| Factory | Configuration and extra methods |
+|---|---|
+| `pointer(options)` | `id`, `root`, `bounds` and event `target`; `finePointer` defaults true, `render({x,y,root,bounds,reason})` optional. Publishes `--dance-moves-x/y`. Controller `set(x,y,reason?)`, `reset(reason?)`. |
+| `playbackPulse(options)` | `id`, `root`, `audio`, `ticks` (16), `className` (`dance-moves-playing`), `propertyPrefix` (`--dance-moves-pulse`), optional render. Publishes duration/delay in seconds. Controller `sync()`. |
+| `cueClass(options)` | `id`, `root`, `cue` (`*`), `className`, **`durationTicks`** (16), optional render. Class is applied to root, not a separate `target`. Controller `fire(detail)`, `clear(reason?)`. Its finite duration is wall-clock based. |
+| `cueTimeline(options)` | `id`, `root`, `audio`, `cues:[{id,time,end?,...}]`, optional `render` and `onCue`. Controller `restore(reason?)`, `start(reason?)`, `stop(reason?)`. |
+| `quality(options)` | `id`, `root`, `tiers`, `initial`, sample/window ratios and cooldowns, optional render. Controller `setTier(index,reason?)`. |
+
+Pulse render receives `{root,audio,duration,delay,ticks}`. Cue-class render
+receives `{root,detail,count,durationMilliseconds}`. Timeline transient crossings
+are separate from restored active intervals: a seek reconstructs state rather
+than firing every cue crossed. Backward seeks start another traversal. Pause,
+visibility and accessibility changes rebuild/stop according to the canonical
+transport implementation. Inspect the existing timeline demo's live snapshot.
+
+Quality defaults are tiers `full/constrained/minimal`, initial 0, sample 1600ms
+(minimum 800), poor windows 2, healthy windows 5, downgrade ratio .72, recovery
+ratio .9, downgrade cooldown 5000ms and recovery cooldown 12000ms. It is not the
+same monitor as Clay's adaptive performance system. Preserve reduced-motion and
+forced-colour CSS; a quality tier is not permission to ignore accessibility.
+
+## Native rudiments and custom renderers
+
+```js
+await runtime.rudiments.ready();
+const controller = runtime.rudiments.animate({
+  id: 'arcadians:drift', root: runtime.root,
+  target: runtime.root.querySelector('.drift'),
+  rudiment: 'clay_background', clock: 'audio', audio: 'audio',
+  rate: 0.5, amplitude: {x: 14, y: 10, z: 0}
+});
+await controller.ready;
+// Later: controller.pause(), resume(), setEnabled(false), reset(), refresh(),
+// snapshot(), destroy() / teardown().
+```
+
+```css
+.drift {
+  translate: var(--dance-moves-rudiment-x, 0px)
+             var(--dance-moves-rudiment-y, 0px);
+}
+```
+
+The native service exposes `ready()`, `catalogue()`, `describe(name)`,
+`sample(name, integerPip)`, `pipsFromTicks`, `pipsFromSeconds`, `animate`, `get`,
+`snapshot` and `destroyAll`. All 15 pinned motions, negative wrapping, CSS output,
+custom Canvas callbacks, page/audio/auto clocks, cue resets and accessibility
+suspension remain available. Controllers share the native service's scheduler
+within a mount. Do not add another timer to advance them.
+
+The complete options, callback fields and limitations are in
+[the native reference](../RUDIMENTS-API.md); `lib/rudiments.d.ts` ships with npm.
+The four-beat Clay pattern at rate .5 preserves the old eight-beat background
+cycle. Native offsets intentionally do not include opacity, rotation or scale;
+the Clay adapter preserves those accents separately at the same phase.
+
+## Catalogue and original adapters
+
+With `catalogue:true`, `applyCatalogueTiming()`, `catalogueTimingSnapshot()` and
+`removeCatalogueAnimationScope()` are attached to the runtime. The latter removes
+animation ownership only; use runtime destruction to dispose the entire mount.
+
+`getClay()` returns the existing Clay controller when initialized. Its methods
+are `setParameters`, `setMotion`, `setMotionTarget`, `setCueState`, `lifecycle`,
+`reset`, `snapshot`, `teardown`. Visual parameters remain `enabled`,
+`masterIntensity`, `coverTiltDegrees`, `coverTranslationPixels`,
+`bloomTravelPixels`, `flareTravelPixels`, `specularTravelPixels`, and
+`particleReleaseTicks`. `getClayRudiment()` exposes its native background
+controller snapshot/teardown. Required markup and all original mapping examples
+remain in the 23-page WordPress-style gallery, now loading the shared package.
+
+`getPaperPlanes()` returns the canonical paper-plane controller; its stage is
+bounded by `.epk-hero`, with `.epk-cover-wrap` and `.epk-heading` for stacking.
+Use `effect:'paper-planes'` and a valid atlas URL. Reduced motion, forced colours,
+compact mode, visibility and resize behaviour remain in that implementation.
+
+`orientation.adapter` accepts all nine names exported by `ORIENTATION_ADAPTERS`.
+Their original DOM/CSS selectors and mobile/permission policy remain unchanged;
+selecting another adapter does not fabricate its required DOM. `getOrientation()`
+returns its existing snapshot/reset/teardown API. The unmodified orientation
+helper surface is at `orientationCore` (14 exports, including both schedulers).
+
+For an arbitrary application layout, prefer the new generic controller:
+
+```js
+const phone = runtime.createOrientation({
+  render: ({x, y}) => {
+    subject.style.transform = `translate(${x * 20}px, ${y * 16}px)`;
+  }
+});
+button.addEventListener('click', () => phone.enable().catch(console.error));
+// phone.disable(); phone.reset(); phone.snapshot(); phone.destroy();
+```
+
+This uses the existing rolling mapper and frame scheduler, with a 2000ms window,
+1.5-degree minimum span and 32ms smoothing constant by default. Permission must
+be requested from a real user gesture. The API does not bypass browser permission
+or produce trusted sensor events from synthetic data.
+
+## Captures, metadata and events
+
+`createRecorder({durationMilliseconds:30000,maxSamples:500})` returns `start()`
+(Promise of the completed capture), `stop(reason?)`, `snapshot()`, and
+`upload(sameOriginUrl,{headers?,signal?})`. Capture is explicit, bounded and never
+automatically uploaded. Its schema matches the WordPress capture schema but
+physical parity is not claimed. See [Node endpoints](javascript-server.md).
+
+`validatePageConfig`, `PAGE_META_KEYS`, `fromWordPressMeta(meta,resolver)` and
+`createMemoryPageStore` are importable without a DOM. The attachment resolver is
+required for nonzero WordPress attachment IDs. The memory store supports `read`,
+`save`, `revisions`, `restore`, `delete`; `expectedRevision` detects concurrent
+updates, and configured page/revision limits bound memory. It is not durable
+storage and not an authorization mechanism.
+
+The core's `dance-moves-ready`, `dance-moves-cue`, `kieran-epk-cue` and
+`dance-moves-lyric` events, plus effects/native ready/error events, are emitted
+on the scoped root. The WordPress adapter preserves document dispatch. Register
+lifecycle subscriptions with `runtime.on`; consumers needing initial native
+readiness should await the Promise instead of hoping to subscribe before an
+initialization event already fired.

package/docs/javascript-server.md

@@ -0,0 +1,150 @@
+# JavaScript host services (Node)
+
+Import from `@kieransimkin/dancemoves/server` only on the server. Node 22.14+
+is the package baseline; Next route handlers must use `runtime = 'nodejs'`, not
+Edge. The main browser entry contains no filesystem/signing/capture secret.
+
+WordPress retains its existing PHP endpoints and native storage. These services
+provide the corresponding operations to another host; there is no attempt to
+turn a browser into WordPress or to reuse its public fixed capture token as an
+application authentication scheme.
+
+## Page properties and revisions
+
+`validatePageConfig(input)` and `fromWordPressMeta(meta, attachmentResolver)` have
+the same contracts as the main entry. Validation must run on the server before
+persisting untrusted updates even when the React form already validated them.
+Only persist fields the authenticated caller is allowed to change.
+
+`createMemoryPageStore({maxPages:100,maxRevisions:20})` provides:
+
+```js
+const record = pages.save('arcadians', {bpm:145}, {expectedRevision:0});
+const current = pages.read('arcadians');
+const history = pages.revisions('arcadians');
+const restored = pages.restore('arcadians', record.revision,
+  {expectedRevision:current.revision});
+pages.delete('arcadians');
+```
+
+Records are `{revision,config,savedAt}`. Read operations return clones; restore
+creates a new revision. A revision mismatch or exceeded page limit fails. This
+bounded store demonstrates the contract, not a durable production database. Use
+an application transaction/optimistic lock for durable multi-process storage.
+
+## Timing upload validation
+
+`validateTimingFile(textOrUint8Array, {kind:'cue',filename?,maxBytes:1048576})`
+returns frozen `{text,kind,bytes,timestamps}`. It accepts lyric `.lrc` or cue
+`.lrc`/`.cue` extensions, strict UTF-8, no null/replacement characters, at least
+one bracketed timestamp and monotonically ordered timestamps. Equal times and
+lyric clear lines are retained. File parsing into browser events is provided by
+the canonical runtime's parser methods.
+
+Failure uses `ValidationError` with `code`, `message` and `status`. Relevant codes
+are `timing_extension`, `timing_size` (413), `timing_utf8`, `timing_timestamps` and
+`timing_order` (400). Invalid option types throw `TypeError`.
+
+Validate uploaded bytes and server-owned filenames. This API does not fetch
+arbitrary remote timing URLs; adding such a feature to your host requires SSRF,
+redirect, size and content-type controls. The `.cue` convention is bracketed
+musical cues, not the unrelated CD INDEX syntax.
+
+## Signed MP3 attachment delivery
+
+```js
+import {createDownloadService} from '@kieransimkin/dancemoves/server';
+const downloads = createDownloadService({
+  rootDirectory: '/srv/my-app/media',
+  secret: process.env.DANCEMOVES_DOWNLOAD_SECRET,
+  origin: 'https://music.example',
+  route: '/api/download'
+});
+const attachmentUrl = downloads.sign('arcadians.mp3');
+const response = await downloads.handle(request);
+```
+
+`rootDirectory` must be absolute. `secret` is a server-only string/Uint8Array of at
+least 32 bytes. `origin` must be HTTP(S), and route a same-origin absolute path
+without query/fragment. `sign` returns a URL with normalized relative MP3 `path`
+and HMAC-SHA256 `signature` query fields. Unsafe input throws `ValidationError`.
+
+`normalizeDownloadPath(value)` returns the safe decoded relative path or an
+empty string. It rejects traversal, absolute/drive paths, controls, empty path
+segments and non-MP3 suffixes. Signature comparison is timing-safe. The handler
+resolves the real filesystem path and verifies containment below the allowed
+root; symlink escapes are rejected. Do not give an untrusted writer control over
+that directory while serving it.
+
+`handle(Request)` returns a Web `Response`: 200 for valid GET/HEAD, 404 for an
+invalid signature/path/missing file, and 405 (`Allow: GET, HEAD`) for other methods
+with otherwise valid routing. It sends `Content-Type: audio/mpeg`, exact content
+length, UTF-8 attachment filename, `nosniff`, `noindex` and private/no-store cache
+headers. HEAD closes the file without a response body. GET streams the file and
+closes its handle.
+
+Playback and download are deliberately separate. Use the ordinary static media
+URL for `<audio>` so the host can provide range requests. The signed attachment
+handler does not implement playback ranges or rewrite audio/source elements.
+Render the signed URL on an `<a download>` element. A valid signature demonstrates
+a server-produced path, not that the visitor bought access; implement additional
+authorization where needed. Rotating the secret invalidates old links.
+
+## Private motion capture
+
+`validateMotionCapture(payload)` validates and sanitizes the inherited
+`ks-epk-motion-recording/v1` schema. It requires 1–500 samples; finite timestamp
+0–120000ms, beta -180..180 and gamma -90..90; alpha may be null/0..360.
+Optional sample/capture flags and bounded descriptive fields are preserved.
+Invalid nullable optional numeric fields become null, following the existing
+schema's permissive optional-field policy. It caps failure records/counters and
+the sanitized JSON size. The new HTTP boundary also bounds the incoming body
+before JSON parsing, including chunked requests without Content-Length.
+
+```js
+import {createCaptureHandler} from '@kieransimkin/dancemoves/server';
+const POST = createCaptureHandler({
+  allowedOrigin: 'https://music.example',
+  authorize: request => sessions.canCapture(request),
+  rateLimit: request => limits.consumeVerifiedUser(request),
+  store: async (capture, {visibility, request}) => {
+    const id = await database.storePrivateCapture(capture, request);
+    return {captureId:id, storedPrivately:true};
+  }
+});
+```
+
+All three callbacks are required. `authorize` and `rateLimit` return booleans or
+Promises. `store` receives `{visibility:'private',request}` and must return a
+truthy `captureId` and **`storedPrivately:true`**. The flag is a contract with the
+host, not a substitute for real storage permissions. The library cannot verify
+how a custom database adapter publishes its rows.
+
+Responses are JSON, no-store:
+
+| Condition | Status/code |
+|---|---|
+| Not POST | 405 `method_not_allowed`, Allow POST |
+| Wrong or malformed supplied Origin | 403 `ks_motion_origin` |
+| Authorization denied | 403 `ks_motion_forbidden` |
+| Rate limit denied | 429 `ks_motion_rate`, Retry-After 600 |
+| Not application/json | 415 `ks_motion_content_type` |
+| Invalid schema/body/samples | 400 `ks_motion_schema`, `ks_motion_samples`, `ks_motion_invalid_samples` |
+| Body/sanitized payload too large | 413 `ks_motion_size` |
+| Storage/callback failed or did not confirm privacy | 500 `ks_motion_server`, with no internal error details |
+| Success | 200 `{captureId,sampleCount,storedPrivately:true}` |
+
+A missing Origin is not automatically authorization; the mandatory authorization
+callback must still succeed. With cookie/session authentication, enforce your
+host's CSRF policy. Do not authorize based on an untrusted payload flag or
+forwarded IP header. Native/simulated/parity flags remain **client-reported**.
+
+`createMemoryRateLimiter({limit:8,windowMilliseconds:600000,maxKeys:10000,now})`
+returns `{consume(key)}`. It expires old keys, bounds key count and fails closed
+when capacity is reached. This is for local demos/single-process applications;
+replicas or serverless hosts need a shared atomic limiter.
+
+The Next demo's private storage path is checked both lexically and through
+realpath against `public/`. New files use exclusive creation and private POSIX
+modes where supported. Production ACLs, backups, retention, user access and
+data-protection policy remain the host's responsibility.

package/docs/react-next.md

@@ -0,0 +1,185 @@
+# React and Next.js
+
+The React entry is optional and starts with `"use client"`. Neither the main
+entry nor the hooks create a browser runtime during module import/server render.
+The hooks call the same shared `createDanceMoves` factory and dispose it on
+unmount. There is no React-only animation engine.
+
+## A React component
+
+```jsx
+'use client';
+import {useMemo, useRef} from 'react';
+import {useDanceMoves, useRudiment, useLyric} from '@kieransimkin/dancemoves/react';
+import '@kieransimkin/dancemoves/styles.css';
+
+export default function ArcadiansPlayer() {
+  const root = useRef(null);
+  const target = useRef(null);
+  const config = useMemo(() => ({
+    bpm: 145,
+    lyricTimingUrl: '/media/canonical-lyric-timing.lrc',
+    cueTimingUrl: '/media/sections.cue',
+    masterDurationMilliseconds: 273604.558
+  }), []);
+  const motion = useMemo(() => ({
+    id: 'arcadians:sway', rudiment: 'sway', clock: 'audio', audio: 'audio',
+    amplitude: {x: 24, y: 12, z: 0}
+  }), []);
+  const {runtime, error} = useDanceMoves(root, config);
+  const native = useRudiment(runtime, target, motion);
+  const lyric = useLyric(runtime);
+  return <section ref={root} className="ks-epk">
+    <audio controls preload="metadata" src="/media/arcadians.mp3" />
+    <div ref={target} className="drifting-art">Arcadians</div>
+    <p>{lyric?.text || ''}</p>
+    {(error || native.error) && <p role="alert">{(error || native.error).message}</p>}
+  </section>;
+}
+```
+
+```css
+.drifting-art {
+  translate: var(--dance-moves-rudiment-x, 0px)
+             var(--dance-moves-rudiment-y, 0px);
+}
+```
+
+Keep `config` and controller options stable with `useMemo`. New options deliberately
+cause a destroy/remount so page clocks, media files and tempo are never partially
+reconfigured. A ref must be attached when the effect runs. Remount the component
+when its root changes; do not mount nested providers over the same subtree.
+
+## Hook and component reference
+
+| Export | Contract |
+|---|---|
+| `useDanceMoves(rootRef, options?)` | `{runtime, error}`; runtime is initially null during SSR/first render. Automatically creates and destroys the shared runtime. |
+| `DanceMovesProvider({options, children, className, ...divProps})` | Owns one `div.ks-epk` and exposes the hook result through context. |
+| `useDanceMovesContext()` | Returns that context; throws outside a provider. |
+| `useCue(runtime, name, callback)` | Subscribes/unsubscribes canonical cues; callback ref keeps the latest closure without recreating subscriptions. |
+| `useLyric(runtime)` | Current lyric payload or null. Clears on player pause/end/seeking as well as canonical blank cues. |
+| `useRudiment(runtime, targetRef, options)` | `{controller,error}`; owns one native animation and destroys it on dependency changes/unmount. |
+| `Rudiment({runtime, options, children, ...divProps})` | Div wrapper using `useRudiment`. CSS consumes its scoped native output. |
+| `PageMetadataEditor({value,onSave})` | Controlled host-neutral BPM, timing URLs, duration, popup and effect editor. Validates before calling `onSave`; persistence/auth are not supplied by a browser form. |
+
+The provider does not inject audio, attach an automatic upload endpoint or
+replace your application's router. Keep event subscriptions and custom renderer
+writes inside effects with cleanup. Development Strict Mode is supported, not
+disabled to hide duplicate initialization.
+
+## Next.js App Router
+
+Import global DanceMoves CSS in `app/layout.jsx`. Put the player/hooks inside a
+Client Component. The shared `/server` entry belongs only in Server Components,
+route handlers or other server-only modules. The download secret must never be
+named `NEXT_PUBLIC_*` or passed to a Client Component.
+
+The included `examples/next` app imports `examples/react/App.jsx`; there is one
+React demonstration implementation, not a copy maintained in both apps. The
+repository root supplies the local package exports and a single React install.
+`tools/run-next.mjs` runs Next in that app directory. Do not `npm install` a
+second copy of the library inside the demo app.
+
+The production download/capture examples are Node route handlers:
+
+```js
+// app/api/download/route.js
+import path from 'node:path';
+import {createDownloadService} from '@kieransimkin/dancemoves/server';
+export const runtime = 'nodejs';
+const downloads = createDownloadService({
+  rootDirectory: path.resolve(process.cwd(), 'public/media'),
+  origin: process.env.DANCEMOVES_ORIGIN,
+  secret: process.env.DANCEMOVES_DOWNLOAD_SECRET
+});
+export const GET = request => downloads.handle(request);
+export const HEAD = request => downloads.handle(request);
+```
+
+Sign the known, allowed filename in a Server Component and pass only the signed
+URL to the player. Do not expose an unauthenticated public endpoint that signs
+arbitrary filenames. The capture example requires a separate key and private
+folder outside `public/`; its single-process limiter is for demonstration.
+Replace it with application sessions, capabilities and a shared limiter for
+production replicas. Filesystem persistence is unsuitable for read-only or
+stateless hosting; provide a durable private database/object-store callback.
+
+## Run the Arcadians demos
+
+From the repository root after applying the patch:
+
+```sh
+npm install --ignore-scripts
+npm run build
+npm run demo:prepare
+npm run demo:react
+```
+
+Open `http://127.0.0.1:4173/`. The media preparer downloads the hash-pinned Arcadians
+MP3 and artwork from StemLab; it never generates a substitute. Existing canonical
+LRC and section data are reused. A local StemLab checkout can be supplied through
+`python tools/prepare-app-demos.py --stemlab-root ../stemlab`.
+
+The React gallery has panels for all native motions, pointer mapping, playback
+pulse, named cues, cue timeline, quality, generic phone orientation, Clay, planes,
+metadata/revisions and private capture. Every panel uses the same Arcadians
+player. Chapter buttons, playback rate, canonical lyrics, lifetime inspection,
+and runtime unmount/remount controls are shared. Camera/sensor parity and
+physical performance are not simulated as proof of real-device behaviour.
+
+For Next.js:
+
+```sh
+npm run demo:next
+```
+
+Open `http://localhost:3000/`. Copy `examples/next/.env.example` to
+`examples/next/.env.local` and set your own server-only secrets to enable signed
+downloads/captures. Use at least 32 bytes of unpredictable secret material;
+example test values in the automated tests are not production secrets.
+Without configuration those server features are disabled/reject requests, not
+silently backed by a public token. The song still plays via its ordinary media URL.
+
+The existing 23-page WordPress-style gallery also imports `/lib/index.mjs` now:
+
+```sh
+python tools/serve-wordpress-examples.py
+```
+
+Open `http://127.0.0.1:8765/examples/wordpress/`. It retains all nine legacy
+orientation mappings, all 23 core methods, the catalogue and diagnostic workbench,
+all 15 native motions, HTTP simulations and page metadata inspectors. Those
+simulated PHP/HTTP behaviours are labelled; the frontend module is real.
+
+## Tests and production builds
+
+```sh
+npm test
+npm run test:legacy
+npx playwright-core install --with-deps chromium
+npm run test:browser
+npm run test:next
+npm run test:next:smoke
+```
+
+`npm test` includes real ESM/CJS imports and React server rendering after a build.
+Browser tests use the real React bundle, actual WASM and canonical MP3, check
+chapter seeking, feature mounts, cue effects, Strict Mode disposal/remount and
+capture a reduced-motion screenshot. The Next smoke test starts the actual
+production build and exercises server rendering, signed HEAD downloads,
+unauthenticated rejection and private capture persistence. Missing build/media
+or browser prerequisites fail; they are not reported as passing skipped tests.
+
+Desktop Chromium automation does not certify iOS permission prompts, Safari
+pseudo-element animation behaviour, screen orientation or real device cadence.
+Keep attended mobile/browser checks before deployment.
+
+## CSP and accessibility
+
+Serve the atlas and media as same-origin public assets unless CORS is deliberately
+configured. Dynamic style elements can use the `nonce` mount option. The native
+backend needs browser WebAssembly permission under the application's CSP; do not
+turn on arbitrary JavaScript eval. Test actual CSP headers and fallback behaviour.
+Avoid full-frame flashes or brightness/tint modulation. Honour reduced motion
+and forced colours in custom callbacks as well as in the shipped CSS.