@kieransimkin/dancemoves 3.0.2

package/docs/development.md

@@ -0,0 +1,254 @@
+# Development, validation and operations
+
+[Documentation index](README.md) · [Source audit](source-audit.md)
+
+This guide describes the checked-in 2.8.0 tools, not a claim that a particular
+machine, deployment or physical device has passed them. The authoritative
+publication requirements remain [TEST-PLAN.md](../TEST-PLAN.md). The
+[HARNESS-IMPLEMENTATION-PLAN.md](../HARNESS-IMPLEMENTATION-PLAN.md) contains planned
+and staged work; its existence does not make every proposed feature a production
+API or an implemented test command.
+
+## Repository layout
+
+| Path | Role |
+| --- | --- |
+| `kieran-epk-device-orientation.php` | Plugin identity, page configuration, editor UI, REST capture, signed downloads and content transforms. |
+| `assets/` | Production timing, catalogue, orientation, shared effects, paper-plane sprites, Clay/Stars and admin assets. |
+| `docs/` | User guide and source-audited API reference. |
+| `tests/` | Node contracts, PHP transform checks, integration fixtures and mobile capture/conformance utilities. |
+| `tests/harness/plugin-core/` | Shared local harness assets/contracts. |
+| `tests/harness/clay-stars/`, `tests/harness/california-screamin/` | Release-specific harness configurations. |
+| `tools/` | Validation, preview building, read-only audits and packaging utilities. |
+| `migration/`, `qa/` | Staged migration data and dated evidence. Do not interpret a historical result as approval for a new artifact. |
+| `dist/` | Versioned WordPress ZIPs and manifests. These are not automatically regenerated by documentation edits. |
+
+## Normal unit validation
+
+The existing coordinator is [tools/validate.ps1](../tools/validate.ps1), with:
+
+| Argument | Meaning |
+| --- | --- |
+| `-Mode Unit` | Default. Lint, contracts, encoding, transforms and scaffold checks, without rebuilding migration/package artifacts. |
+| `-Mode Package` | Explicitly rebuild migration and distribution artifacts and check package identity/layout. |
+| `-Mode All` | Run Unit, then Package. This is not a read-only documentation check. |
+| `-ReleasesRoot` | Optional release-workspace root forwarded to the migration builder in Package/All mode. Unit mode does not need it. |
+| `-IncludeFailureFixture` | Deliberately exercise a syntax failure; valid only when Unit runs. Not a normal passing test run. |
+
+The scripts assume the repository's Windows/PowerShell workflow, with `php`,
+`node` and `python` on PATH. The source does not declare a definitive minimum
+version matrix for these tools or for WordPress/PHP. Record actual versions used
+rather than inventing a support guarantee. In particular, Package mode invokes
+`powershell` explicitly and some paths/exclusions are Windows-specific.
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\validate.ps1 -Mode Unit
+```
+
+The process-scoped execution-policy argument does not change machine-wide
+policy. Inspect scripts before running them. Unit mode performs PHP lint,
+JavaScript syntax checks, sequential direct execution of each top-level
+`tests/*.test.cjs`, PHP Clay transform/collision and download-path checks, shared/Clay harness
+scaffold validation, UTF-8/null/replacement-character checks and plugin
+name/version checks. It deliberately excludes the failing fixture from the
+normal syntax scan.
+
+**California Screamin' caveat:** the coordinator treats its full-page scaffold
+audit failure as a warning because the page retains known width/background-position
+blockers. Passing Unit is therefore not a statement that every release's browser,
+visual, accessibility or performance gate passed.
+
+The coordinator runs each Node contract as `node path/to/file.test.cjs`, not one
+parallel `node --test` invocation. That is also the appropriate focused pattern:
+
+```sh
+node tests/dance-moves-core.test.cjs
+node tests/dance-moves-diagnostics.test.cjs
+node tests/timed-lyric-popover.test.cjs
+node tests/exact-cue-seek.test.cjs
+node tests/cue-timeline.test.cjs
+node tests/effects-primitives.test.cjs
+node tests/epk-download-contract.test.cjs
+node tests/paper-dreams-flight.test.cjs
+node tests/catalogue-timing.test.cjs
+node tests/clay-adapter.test.cjs
+node tests/sensor-raf-scheduler.test.cjs
+node tests/runtime.test.cjs
+node tests/california-adapter.test.cjs
+php tests/validate-clay-transform.php
+php tests/validate-clay-legacy-collision.php
+php tests/validate-epk-download-paths.php
+```
+
+These focused commands do **not** replace the coordinator. Other checked-in
+contract files cover WordPress metadata/uploads, shared component timing,
+orientation maths, mobile API parity, capture duration and harness foundations.
+See [tests/](../tests/) for the inventory. Use
+[tools/test-validator-failure.ps1](../tools/test-validator-failure.ps1) when
+verifying that the deliberate failure is correctly attributed and returns a
+nonzero exit status.
+
+## Local harness workflow
+
+Serve the repository rather than opening timing-fetch fixtures through `file:`:
+
+```sh
+python -m http.server 8765 --bind 127.0.0.1
+```
+
+From the resulting local site, open the appropriate checked-in fixture under
+`tests/`, such as `dance-moves-integration.html`, `shared-component-timing.html`
+or `mobile-harness.html`, plus `effects-primitives-preview.html` and
+`paper-dreams-flight-preview.html`, or follow the release harness's own files. Supply only
+approved, locally available media/manifests; repository fixtures are not proof
+that an external canonical master exists on your machine. A local HTTP server
+does not make a LAN-served page a secure physical-phone sensor origin.
+
+The shared harness validation commands used by the coordinator are:
+
+```sh
+python -X utf8 tools/validate-effect-harness.py tests/harness/plugin-core --mode scaffold
+python -X utf8 tools/validate-effect-harness.py tests/harness/clay-stars --mode scaffold --manifest-file tests/harness/clay-stars/clay-stars.json --shared-root tests/harness/plugin-core
+python -X utf8 tools/validate-effect-harness.py tests/harness/california-screamin --mode scaffold --manifest-file tests/harness/california-screamin/california-screamin.json --shared-root tests/harness/plugin-core
+```
+
+The [validator source](../tools/validate-effect-harness.py), release manifests and
+[test plan](../TEST-PLAN.md) define their expected evidence. Manifest-driven
+master/timing/effect controls, deterministic input/cue simulation, attributed
+handler timing, CSS-property audits and release snapshots are development
+facilities. They are not an additional public production control plane.
+`EPKEffectHarnessProbe`, simulated orientation events and capture/conformance
+utilities under `tests/` must not be shipped as front-end dependencies.
+
+When instrumenting the core, set `danceMovesConfig.diagnostics = true` **before**
+the core asset executes, then install a bounded `setDiagnosticsSink()` receiver.
+Give every cue/lyric/interval effect a stable attribution ID. The normal
+WordPress configuration does not enable diagnostics. See
+[diagnostics API](api/javascript.md#diagnostics) for the payloads and limits.
+
+## Release selection before changing documentation
+
+Do not infer the latest plugin from the default branch. At this audit, `main`
+remains 2.4.0 while the latest published tag is **v2.8.0**. The release commit is
+`4cb6a71f60459b5579be87d7e55ac8b1426c578e`; the current staging branch is one
+publication-evidence commit ahead, with identical production source and README.
+Compare tags, release assets and staging before selecting a baseline.
+
+This patch replaces the earlier 2.4.0 documentation patch; it is not incremental.
+Apply to a clean 2.8.0/staging checkout without the previous patch's added `docs/`.
+For example, after saving local work and placing the patch outside the checkout:
+
+```sh
+git fetch origin timed-lyrics-staging-2026-09-20 --tags
+git switch -c docs/complete-api-reference-v2.8.0 origin/timed-lyrics-staging-2026-09-20
+git apply --check /path/to/DanceMoves-2.8.0-documentation.patch
+git apply /path/to/DanceMoves-2.8.0-documentation.patch
+```
+
+For an immutable release-based branch, use `v2.8.0` as the start point instead.
+Review any newly fetched changes before applying. The commands do not push,
+merge, rebuild a ZIP or write to WordPress. No PHP/JavaScript version bump is
+required for a source-documentation change.
+
+## Acceptance checks for an integration
+
+Exercise ordinary playback, pause/resume, end/replay, playback-rate changes,
+forward/backward seeks, more than one player, absent/invalid timing files,
+blank/repeated/long lyric lines and a dynamically inserted audio element. Check
+that only master-length players bind and call `discoverAudio()` after deliberate
+dynamic insertion. Recreate interval subscriptions around backward seeks when
+required by the documented scheduling caveat.
+
+For shared timelines, test zero-time cues, default/opt-in playing and paused
+landings, duplicate IDs, overlapping intervals, gap discontinuities, rate changes,
+callback failures and repeated teardown. Confirm full interval reconstruction,
+not merely a transient class firing. The core landing policy is different from
+the timeline's opt-in policy. Verify every `next*` and `nextVisible*` field across
+blank cues and the final line.
+
+For downloads, test real GET/HEAD and invalid signatures, local-file availability,
+Unicode filenames, cached page links and the original player's seek behaviour.
+For paper planes, test hero clipping/stacking, compact counts, offscreen pause,
+reduced-motion hiding and the forced-colour CSS-versus-loop distinction. For the
+shared quality controller, test a preference already active at initial mount.
+
+Test at desktop, tablet and narrow-mobile widths, signed out, with reduced motion
+and forced colours. Preserve complete readable lyrics, keyboard focus, controls,
+safe areas and static artwork. Test both permissions granted and denied on actual
+supported devices, plus hidden-tab/page lifecycle changes. Confirm the adapter's
+root identity before interpreting diagnostic attributes.
+
+Performance acceptance requires sustained-load measurements and recovery trials,
+not merely a snapshot of `profile: "full"`. Record the exact plugin/source or
+package hash, browser/device, viewport, time and evidence location. Synthetic
+orientation events verify contracts, not native trust, physical-device smoothness
+or input-to-display latency. The motion-capture schema stores orientation/parity
+data; it does not contain all the physical performance telemetry required by the
+test plan.
+
+The plugin release gate and the EPK pre-live gate are independent. `BLOCKED` and
+`NOT RUN` are not `PASS`. No WordPress upload, page-meta write, timing-media upload
+or legacy-plugin deactivation is authorised merely by running a local test.
+
+## Packaging and upgrade identity
+
+Only run the following for an intentional package/migration rebuild:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\validate.ps1 -Mode Package
+```
+
+[tools/package.ps1](../tools/package.ps1) reads the version from the PHP header,
+uses the root `kieran-epk-device-orientation/`, and includes **only** the entrypoint,
+root `README.md` and `assets/`. It writes `dist/DanceMoves-<version>.zip` and the
+matching package manifest, including ZIP/file hashes and layout checks. The
+manifest builder is a separate step invoked by Package mode.
+
+`docs/`, tests, tools, QA, migration evidence and master audio are not copied into
+the WordPress ZIP by the current allowlist. The complete API reference lives in
+the source repository; the root README links to it online for packaged readers.
+This documentation patch deliberately does not alter that packaging policy,
+regenerate immutable evidence, overwrite existing ZIPs or bump runtime versions.
+A later intentional package rebuild will include the updated root README.
+
+Do not rename the internal folder or PHP entrypoint to `DanceMoves`: WordPress
+must recognise the same installed plugin on upgrade. Check both the artifact
+identity and package layout before deployment. Preserve an exact rollback ZIP
+and its checksum. Reactivating the old Clay/Stars effects plugin suppresses the
+new page-252 takeover when its `KS_CLAY_STARS_EFFECTS_VERSION` constant is defined;
+it is not a general rollback for the shared timing core.
+
+## Troubleshooting
+
+| Symptom | Check / documented limitation |
+| --- | --- |
+| `DanceMoves` undefined | Script dependency/order, whether the request is a WordPress Page, footer output and browser console. The core has no public ready event or load promise; `dance-moves-effects-ready` belongs to the separate shared-effects layer. |
+| Page shows fallback BPM | Metadata must be finite and within 20–400; blank/invalid values use 120 without claiming a known tempo. |
+| Cue file has no entries | Use bracketed LRC-style timestamps, not CD `TRACK`/`INDEX` syntax. Blank cue labels are ignored. |
+| Fetch failure looks like status `none` | Final initialisation overwrites the temporary `unavailable` marker. Inspect network/console and entry counts, not status alone. |
+| Cue behaviour differs between integrations | Core LRC playback arms one cue within 50 ms, including at zero; the shared timeline fires crossings and has opt-in playing seek landings. Initialize persistent timeline state in render. |
+| New audio does not follow cues | Insert it before discovery or call `discoverAudio()` after insertion; confirm metadata/duration and then normal playback events. |
+| Repeating interval waits after backward seek | A retained interval boundary is not fully rebased; remove and recreate the subscription for that seek. |
+| Custom lyric output remains visible on pause | `onLyric()` is not a complete playback-state stream. Handle pause/end for your custom renderer. |
+| Lyric CSS does not match | The generated layer is under `body`, outside `.ks-epk`; component-local defaults also outrank merely inherited palette variables. |
+| Phone UI absent | Production mobile/secure-context/sensor gate, root selector, adapter mapping, reduced motion and permission support. |
+| Performance never reaches a fixed 60 FPS | Identify the controller: Clay uses median/p95 and probation; shared quality uses frame-count windows and fixed cooldowns. Neither proves physical refresh rate. |
+| Paper snapshot reports 2.6.3 | This is the adapter-local marker; plugin `DanceMoves.version` is 2.8.0. |
+| MP3 opens inline | Confirm the anchor has `download`, passed through main Page `the_content`, and matched the upload base. Direct player URLs intentionally stay inline. |
+| Untouched assets fail byte hashes | Check `.gitattributes`, checkout line-ending conversion and the exact locked production bytes; never update locks merely to silence a mismatch. |
+| A gate passes on a simulator but not a phone | Keep synthetic contracts and real physical-device evidence separate. |
+
+For additional read-only inspection and preview utilities, inspect the commands
+and assumptions in [tools/](../tools/): `audit-live-epk-motion.mjs`,
+`capture-public-viewports.mjs`, `inspect-phone-epk.mjs`,
+`build-clay-stars-preview.ps1` and `build-california-screamin-preview.ps1`.
+No generic install command or undocumented command-line flags are implied here.
+
+## Documentation maintenance
+
+Keep troubleshooting limited to reproducible current plugin or integration problems,
+with checks and links to the relevant API contract. Put test prerequisites beside
+the commands they affect. Do not accumulate one-time shell/automation mistakes,
+resolved fixture bugs, private workspace notes or dated success reports in the
+README. Retain release provenance in existing version-control and migration/QA
+records; changing documentation is not a new deployment or validation result.

package/docs/guide.md

@@ -0,0 +1,288 @@
+# User and integration guide
+
+[Documentation index](README.md) · [JavaScript API](api/javascript.md) ·
+[WordPress API](api/wordpress.md)
+
+Source: [plugin entrypoint](../kieran-epk-device-orientation.php),
+[timing runtime](../assets/dance-moves-core.js),
+[catalogue adopter](../assets/dance-moves-catalogue-timing.js).
+Baseline: **2.8.0 / `4cb6a71f60459b5579be87d7e55ac8b1426c578e`**.
+
+## Install and upgrade
+
+Use the reviewed release asset `DanceMoves-2.8.0.zip` (also kept in `dist/`),
+not a GitHub source archive, for a
+WordPress installation. Confirm its matching manifest and hashes before upload.
+The visible plugin name is **DanceMoves**, but the installed folder and entrypoint
+remain `kieran-epk-device-orientation/kieran-epk-device-orientation.php`. Keep that
+identity when upgrading; renaming the folder can create a parallel installation.
+
+The plugin header does not declare a minimum WordPress or PHP version. Do not
+infer a supported-version matrix from that absence. Verify the site's PHP,
+WordPress metadata/revision behaviour and target browsers in staging. The browser
+runtime uses modern DOM, Promise/fetch, animation-frame and Web Animations APIs.
+Phone input also needs a supported, secure browser context.
+
+The shared CSS, core JavaScript, shared effect primitives and catalogue adopter are enqueued on singular
+WordPress **Pages**, not arbitrary posts or archive screens. Orientation is
+additionally limited by the configured page-ID map. The plugin does not create an
+EPK, a music player, a lyrics transcript, or a chapter-navigation interface.
+
+## Set page properties
+
+Open the Page editor's **EPK Timing** meta box.
+
+| Field | Input | Behaviour |
+| --- | --- | --- |
+| BPM | Finite 20–400, up to three stored decimal places | Blank clears the stored value. Unknown/invalid stored BPM resolves to 120 with `bpmSource: "fallback"`, not an assertion that the song is 120 BPM. |
+| Lyric Timing File | Media Library `.lrc` attachment | The attachment ID is saved; its current URL is resolved when the page renders. |
+| Cue Timing File | Media Library `.lrc` or `.cue` attachment | Uses the same bracketed timestamp grammar as LRC. |
+| Timed lyric pop-ups | Checkbox, initially off | Enables the neutral built-in visual layer; it does not replace the complete readable lyric section. |
+| Ambient effect | None or Paper planes | Stores `_dance_moves_effect` as `""` or `"paper-planes"`. Only the latter enqueues the plane assets; the page must supply `.ks-epk .epk-hero`. |
+
+The hidden `_dance_moves_master_duration_ms` value is positive milliseconds, up to
+one day, and is maintained through trusted server-side code rather than the meta
+box or the standard page REST response. All six keys are registered for revision
+support. See the [metadata reference](api/wordpress.md#page-metadata).
+
+Editor saves require the plugin nonce, `edit_post` permission and a non-autosave
+request. An invalid nonblank BPM or invalid timing attachment preserves that
+field's previous value and queues an admin error; clearing a selection deletes
+its metadata but **does not delete the shared Media Library attachment**. Fields
+are saved independently, not as an atomic transaction. The checkbox is not
+programmatically prevented from being enabled without a valid lyric file, so the
+release review remains an explicit workflow requirement.
+
+## Prepare cue and lyric files
+
+Files selected through the editor must be readable local Media Library
+attachments, no larger than **1,048,576 bytes**, with strict UTF-8 and no null or
+replacement characters. There must be at least one bracketed timestamp, and all
+timestamp tokens in file order must be nondecreasing. Equal timestamps are
+allowed. Lyric files use `.lrc`; cue files use `.lrc` or `.cue`.
+
+Accepted timestamp syntax is `[M:SS]`, `[MM:SS.ff]`, `[MMM:SS.fff]`, or the same
+fraction introduced with `:`. Minutes have one to three digits, seconds exactly
+two, and fractions one to three. Fractions are decimal seconds, **not frames**.
+Use seconds 00–59 in authored files even though the current parser's pattern does
+not independently reject a higher two-digit seconds field.
+
+Example cue file:
+
+```text
+[00:04.000][SECTION: VERSE 1]
+[00:20.000][SECTION: CHORUS 1]
+[00:36.000]BREAK
+```
+
+Example lyric file:
+
+```text
+[00:00.000]
+[00:04.000]First sung line
+[00:08.000]Second sung line
+[00:12.000]
+[00:20.000]The repeated hook
+[00:24.000]The repeated hook
+```
+
+A blank timed lyric clears the display. It is ignored by the cue parser. Multiple
+timestamps on one line generate multiple entries; make sure their physical order
+still satisfies the server's monotonic check. The browser sorts parsed entries,
+but that does not make an out-of-order upload valid in the editor.
+
+Metadata-only lines are ignored by the browser parsers. LRC offset tags, enhanced
+word-by-word timing and conventional CD `FILE`/`TRACK`/`INDEX` cuesheet syntax are
+not implemented. Timing text is data, never executable code or HTML.
+
+The two files are fetched separately using same-origin credentials and
+`cache: "no-cache"`. Cross-origin hosting needs the browser to permit the fetch.
+The browser parser itself does not repeat the server's byte-size or monotonicity
+validation. REST/programmatic attachment assignments need explicit validation;
+see [WordPress validation](api/wordpress.md#timing-attachment-validation).
+
+## Understand ticks before writing effects
+
+One tick is **one sixteenth of a beat**, not a conventional sixteenth note:
+
+```text
+one tick       = 3750 / BPM milliseconds
+one beat       = 16 ticks
+one 4/4 bar    = 64 ticks
+at 120 BPM     = 31.25 ms/tick, 500 ms/beat, 2000 ms/bar
+```
+
+Visual durations are rounded half upward to a positive integer tick. Results
+above 16 are then rounded to the nearest multiple of 16, again half upward.
+Consequently 17 duration ticks become 16; 24 become 32. Interval spacing uses
+positive integer ticks without that long-duration quantisation. Use
+`durationMilliseconds()` and the published CSS timing variables rather than
+independent millisecond guesses.
+
+The page clock starts when the core script evaluates. Playback interval helpers
+wait for an active, matching audio element. `currentTick({clock: "audio"})` is a
+special case: when no supplied/active audio is currently playing, it falls back to
+the page clock. A paused song must therefore be guarded explicitly in a canvas
+animation, rather than assuming that this call returns a frozen audio position.
+
+There is no beat-offset, time-signature, variable-tempo or tempo-map setting. The
+grid is anchored to audio time zero at a single BPM. For another meter, choose an
+explicit interval, for example 48 ticks for three beats.
+
+## Connect audio
+
+Ordinary `<audio>` elements are discovered after both timing-file loads settle.
+The preferred matching reference is the configured master duration. Otherwise the
+runtime uses the first element in document order matching
+`audio[data-dance-moves-master], #ks-clay-stars-audio`, otherwise the first audio
+element. Mark the canonical
+player explicitly when a page contains previews or unrelated audio:
+
+```html
+<audio id="release-audio" data-dance-moves-master controls preload="metadata">
+  <source src="/media/release-full-length.mp3" type="audio/mpeg">
+</audio>
+```
+
+A positive finite duration matches when the absolute difference is at most
+`max(0.25, audio.duration / 100000)` seconds. A preview, differently trimmed master
+or live/infinite-duration stream is not safely interchangeable with the canonical
+programme. This is a duration check, not audio fingerprinting or beat alignment.
+
+Matching players are marked `data-dance-moves-timing="master-length"`. Each has its
+own cue cursor; interval helpers use the player most recently started via
+`play`/`playing`. Owned animations follow playback-rate changes. Seeking reindexes
+the cue cursor without replaying skipped cues; lyrics resume at the current line.
+The core arms the earliest cue within 50 ms of an initial/seek position, including
+a cue at zero. It dispatches that pending cue once at playback start, or when a
+playing seek completes. Other skipped cues are not replayed. This is not general
+state reconstruction: use `DanceMovesEffects.cueTimeline()` for active intervals
+and deterministic seek restoration, and initialise persistent visuals in its
+`render` callback. The two cue mechanisms have different landing policies; see
+[core cue landings](api/javascript.md#exact-cue-landings) and
+[cue timelines](api/effects.md#cuetimelineoptions).
+
+For dynamically inserted audio, call `DanceMoves.discoverAudio()` after insertion.
+There is no global audio MutationObserver. Install integrations before starting
+playback; discovery is not a transport-control or automatic-play API. Avoid
+simultaneous players: cues are per-player, but the lyric layer, ownership resets
+and active interval clock are shared.
+
+## Subscribe and clean up
+
+Enqueue a page script with `dance-moves-core` as a WordPress dependency. The global
+is available when that script executes, but asynchronous timing fetches may still
+be pending. There is no `DanceMoves.ready()` method or ready event.
+
+```js
+(() => {
+  const dm = window.DanceMoves;
+  const root = document.querySelector('.ks-epk');
+  if (!dm || !root) return;
+
+  const disposers = [
+    dm.onCue('CHORUS 1', detail => {
+      root.dataset.section = detail.normalisedName;
+    }, { id: 'release:chorus-state' }),
+    dm.onEveryInterval(detail => {
+      root.dataset.barTick = String(detail.boundaryTick);
+    }, 64, { id: 'release:bar-state' })
+  ];
+
+  window.addEventListener('pagehide', () => {
+    disposers.forEach(remove => remove());
+  }, { once: true });
+})();
+```
+
+This simple example assumes a normal page load; an application restoring a page
+from the back-forward cache must re-register its own disposed handlers on
+`pageshow`. Keep stable diagnostic IDs, and prefer `onCue()`/`onLyric()` over a
+second parser or clock. For DOM listeners, register on `document`: cue and lyric
+events are dispatched there, not on each EPK child.
+
+## Adopt timed lyrics
+
+A selected lyric file powers `onLyric()` even while the built-in pop-up is off.
+The built-in layer is one body-level `.dance-moves-lyric-popover` containing a
+`.dance-moves-lyric-popover__text`. It uses `textContent`, is noninteractive and
+`aria-hidden`, hides on pause/end, and clears on a blank lyric. Reduced motion
+keeps the words but removes entry/exit movement; forced colours have a fallback.
+
+Before enabling it for a release, inspect that song's artwork and visual-language
+record, distinguish observed/inferred/proposed/adopted decisions, and document a
+distinctive treatment. Keep real text, full readable lyrics, safe areas and player
+clearance. Test normal and long lines, blank clears, repeated hooks, seeking,
+pause/resume/end, narrow screens, reduced motion and forced colours. A generic
+checkbox-only adoption is not the approved workflow.
+
+The renderer is appended to `body`, not inside `.ks-epk`. A selector such as
+`.ks-epk .dance-moves-lyric-popover` will not reach it. Scope release styling through
+an appropriate body page class or other release-specific ancestor context. See
+[lyric styling](api/styling.md#timed-lyric-component).
+
+Custom lyric consumers must handle audio `pause`/`ended` themselves when they need
+to hide: `onLyric()` does not emit a synthetic blank on those events. It also does
+not immediately replay the last value to a newly registered handler.
+
+## Use the shared effects API
+
+Load after `dance-moves-effects`, or mount once in response to the document's
+`dance-moves-effects-ready` event. Select the smallest matching primitive:
+`pointer()` for bounded input, `playbackPulse()` for phase-aligned CSS,
+`cueClass()` for a short cue-triggered class, `cueTimeline()` for reconstructable
+playback state, and `quality()` for a reusable quality controller. Stable IDs
+identify instances for `get()`, `snapshot()` and teardown. Each has explicit
+options, callback payloads and disposal semantics in the [shared API](api/effects.md).
+These are APIs, not auto-enabled visual presets. In particular, a cue timeline
+accepts page-owned cue objects; it does not automatically import the Page cue LRC.
+
+For paper planes, select **Ambient effect → Paper planes** and provide an existing
+hero with explicit containment. Check full and compact counts, clipping, readable
+controls and reduced motion before publication. See the [paper-plane API](api/paper-planes.md).
+
+## Provide MP3 downloads without breaking playback
+
+Use an ordinary same-upload-host MP3 link with an explicit `download` attribute:
+
+```html
+<a href="/wp-content/uploads/2026/09/example.mp3" download>Download MP3</a>
+```
+
+On the main Page content render, DanceMoves rewrites eligible anchors to its
+signed attachment endpoint. It does not rewrite players, `<source>` elements,
+external media or links without `download`. Server-generated signed URLs are
+shareable and do not expire automatically; they are not a private-media service.
+The [download reference](api/downloads.md) covers URL helpers, request methods,
+response headers, path validation and errors.
+
+## Adopt catalogue and orientation motion
+
+The catalogue adopter chooses `.ks-epk` first, with specific fallback roots listed
+in the [adapter reference](api/adapters.md#catalogue-timing). It converts owned
+animation/transition durations and delays, preserving zero and special reduced-
+motion/view-timeline sentinels. It also registers the release root for cue resets
+and observes inserted elements/style-attribute changes. It does not change
+artwork, invent choreography, rewrite keyframe geometry, or retime canvas code.
+
+Phone orientation is a separate nine-page adapter map. The production wrapper
+checks mobile eligibility and sensor support. Permission-requesting browsers get
+**Use phone motion**; denied/unavailable input leaves the ordinary page usable.
+Hidden pages, reduced motion and teardown stop input work; screen rotation
+recalibrates it. Release-specific motion-off controls remain relevant. CSS
+transitions interpolate targets published at a two-tick cadence; the two-second
+rolling window is input processing, not a musical duration.
+
+For Clay/Stars, keep the existing legacy effects plugin active until the approved
+takeover. While `KS_CLAY_STARS_EFFECTS_VERSION` is defined, DanceMoves suppresses
+its Clay CSS/JS and content transform. Deactivating the legacy plugin permits
+takeover on a subsequent request. Do not transplant that release's artwork or
+motion treatment onto other EPKs.
+
+## Diagnostics and deployment
+
+Use [development and operations](development.md) for local tests, diagnostics,
+performance tiers, approval gates and rollback. A motion capture is an explicit
+submission of a supplied recording; ordinary plugin playback does not record or
+upload phone samples. No WordPress upload, metadata write or deployment is part
+of a documentation update.