@kieransimkin/dancemoves 3.0.2

package/docs/releasing-shared.md

@@ -0,0 +1,162 @@
+# Shared builds, CI and npm/GitHub publication
+
+The same repository now produces:
+
+| Distribution | Output |
+|---|---|
+| npm | `@kieransimkin/dancemoves` tarball, with ESM, CJS, React/Node entrypoints, declarations and styles |
+| Plain browser | `DanceMoves-web-VERSION.zip` with minified `dancemoves.min.js`, styles and static assets |
+| WordPress | `DanceMoves-VERSION.zip` preserving `kieran-epk-device-orientation/` |
+
+The source candidate is 3.0.0. The already-published 2.9.0 tag and artifacts must
+not be overwritten. Package publishing is not WordPress deployment.
+
+## First checkout: dependency lock is required before a release
+
+```sh
+npm install --ignore-scripts
+npm run build
+npm test
+npm run test:legacy
+npm run demo:prepare
+npx playwright-core install --with-deps chromium
+npm run test:browser
+npm run test:next
+npm run test:next:smoke
+```
+
+Commit the generated **package-lock.json** with the reviewed source. This patch
+pins direct development dependencies, but does not invent registry integrity
+values without fetching them. CI can bootstrap an unlocked pull request so its
+resolved lockfile is inspectable; **tag/release builds fail closed without a
+committed lockfile**. From then on use `npm ci --ignore-scripts`.
+
+The lockfile and compiler versions are part of the build input. Minified assets
+are ignored/generated, not hand-maintained alongside canonical sources. Never
+edit `lib/` or `.build/wordpress/` as a way to fix a source bug.
+
+## Local independent builds
+
+```sh
+npm run build:library
+npm run package:web
+npm run package:wordpress
+```
+
+`build:library` creates shared outputs only. `build:wordpress` also stages the
+WordPress adapter. `package:wordpress` builds/stages then uses the Python ZIP
+packager; the retained `tools/package.ps1` delegates to that command. No private
+`Z:` drive or migration-evidence directory is needed to build an archive.
+
+`npm run build` builds all targets once. CI then packages the already-tested
+staging tree, web files and npm package without rebuilding between artifacts.
+Archives use sorted paths and fixed timestamps. WordPress output checks its
+single-runtime invariant; every distribution has SHA-256 metadata.
+
+For a local npm tarball after a successful build:
+
+```sh
+npm pack
+```
+
+Prepack checks the generated manifest against actual output bytes. Do not publish
+a tarball from an earlier build under a newer source version.
+
+## CI
+
+`.github/workflows/ci.yml` runs on main pushes and pull requests. It builds/tests
+on Ubuntu and Windows, with Node 22 and 24, PHP 8.3 and Python 3.12. Node/React
+SSR tests, existing engine/PHP/harness tests, source integrity and packaging
+checks remain gates. A browser job runs real Chromium/React and a production
+Next build/route smoke test using canonical Arcadians assets.
+
+Missing dependencies, source files, media or a blocked browser are failures, not
+successful skipped tests. The CI workflows do not deploy the WordPress site.
+Real Safari/phone measurements and application-specific accessibility checks
+remain attended acceptance work.
+
+## One-time npm setup
+
+The workflow cannot register your npm account permissions through repository
+source code. Before the first publication:
+
+1. Ensure your npm account may publish public packages under `@kieransimkin`.
+2. Create a GitHub environment named **npm**, optionally with required reviewers.
+3. Register the package once if it does not exist. The release workflow supports
+   a narrowly scoped, short-lived **NPM_BOOTSTRAP_TOKEN** environment secret for
+   that first publish. Alternatively publish the exact tested CI tarball
+   interactively; do not rebuild different bytes for the same version.
+4. On npm package Settings → Trusted Publisher, configure **GitHub Actions**:
+   owner `kieransimkin`, repository `DanceMoves`, filename `release.yml`,
+   environment `npm`. Permit **direct `npm publish`**, not stage-only publication.
+5. Remove the bootstrap token after trusted publishing works. Keep permissions
+   and protection rules on release tags and the npm environment deliberate.
+
+The job uses a GitHub-hosted runner, Node 24, npm 11.6.0 and `id-token: write`.
+It publishes with provenance. New npm trusted publishers currently default to
+stage publishing unless direct publishing is explicitly allowed; a stage-only
+configuration will not make this direct-publish workflow succeed.
+
+These requirements follow the official npm trusted-publishing documentation:
+<https://docs.npmjs.com/trusted-publishers/>. npm requires at least CLI 11.5.1 and
+Node 22.14 for this route. No package registration or publisher configuration is
+claimed to have been performed by applying this patch.
+
+## Release tags
+
+After the migration, tests and setup are committed:
+
+```sh
+git status --short
+npm run check:release
+git tag -a v3.0.0 -m "DanceMoves 3.0.0: shared JavaScript runtime"
+git push origin HEAD
+git push origin refs/tags/v3.0.0
+```
+
+The release workflow triggers on `v*` tag pushes, also supports an existing
+published GitHub release event, and has a manual retry input for an **existing**
+tag. It verifies the tag, npm version, PHP header and runtime constant, then:
+
+- runs build and release tests;
+- creates the npm tarball, minified browser ZIP, WordPress ZIP, manifests and
+  `SHA256SUMS.txt` from that tested build;
+- uploads them as an Actions artifact;
+- publishes the exact tarball to npm using the protected npm job;
+- attaches the same artifacts to the GitHub release and publishes it.
+
+A prerelease version such as `3.0.1-rc.1` uses npm's **next** dist-tag and a GitHub
+prerelease. Stable versions use **latest**. A tag alone cannot bypass a failed
+test or incomplete setup. The three products are generated even if a later npm
+authorization step fails; retrieve the tested Actions artifact while fixing the
+publisher setup.
+
+Re-running a job is safe only for identical outputs. Existing npm versions are
+compared using SHA-512 integrity; different bytes fail. Existing GitHub assets
+are compared by SHA-256 and are never uploaded with `--clobber`. A registry
+network/server error is not treated as proof that a version is absent. There
+is intentionally no operation that moves an existing tag or overwrites a
+published package version.
+
+## Updating the next version
+
+```sh
+npm version 3.0.1 --no-git-tag-version
+npm run build
+npm test
+npm run test:legacy
+```
+
+The version lifecycle synchronizes the PHP header/constant, current phone cache
+keys and gallery version. Review and commit **all** resulting version changes,
+including package-lock.json, before creating `v3.0.1`. Run browser/Next acceptance
+again as appropriate to the changes. Native API/upstream dependency versions and
+historical evidence are independent: do not globally replace their version text.
+
+## Verify the result
+
+On GitHub inspect the tag commit, build/test jobs, npm job, attached filenames and
+checksums. Confirm the registry version and its provenance. For WordPress,
+install the exact generated ZIP separately, retain rollback artifacts and check
+public pages/caches. Publication does not set page metadata, migrate site data
+or prove live rendering.

package/docs/rudiments-source-integrity.md

@@ -0,0 +1,80 @@
+# DanceRudiments source integrity and Windows line endings
+
+The native source identity in `vendor/dancerudiments/UPSTREAM.json` is the
+upstream **Git blob SHA-1**, not a SHA-256 file checksum. Generated JavaScript
+and compiled WebAssembly are separately checked against SHA-256 values in
+`assets/vendor/dancerudiments/build-manifest.json`.
+
+## A clean Windows checkout reports a different header hash
+
+The DanceRudiments 0.1.3 pinned LF header has Git blob ID
+`6414362b2720262c8dd01630d7750b2501fd0c14`. Converting **only** its 47 LF line
+endings to CRLF produces `2376c476651fe506e8a92c9e3786f4775c1e9b38`.
+The file grows from 1,734 to 1,781 bytes; its C++ text is unchanged.
+
+Git may convert unspecified text paths according to `core.autocrlf`.
+The repository previously specified LF for JavaScript and other formats, but
+not C++ headers, C++ sources or extensionless `LICENSE` files. Explicit LF
+attributes now cover those paths, including both copies of the MIT licence.
+See the [Git attributes reference](https://git-scm.com/docs/gitattributes).
+
+Existing working files may remain CRLF after changing attributes. No reset,
+reclone, global Git setting change, manual re-encoding or pin update is needed.
+
+## Verification rules
+
+`node tools/verify-rudiments.cjs` checks each pinned upstream text file as follows:
+
+1. Accept its exact bytes when its Git blob ID matches the existing pin.
+2. Otherwise replace only CRLF byte pairs with LF **in memory**, and accept the
+   result only when that reconstructs the same existing Git blob ID.
+3. Reject every other difference, with the filename, expected ID, raw ID and
+   canonical ID in the error. Working files and pins are never changed.
+
+There is no Unicode decoding/re-encoding, whitespace trimming, BOM stripping,
+blank-line removal or conversion of lone CR characters. Mixed LF/CRLF is
+accepted only when CRLF-to-LF reconstructs the exact pin. Both licence copies
+must independently match the licence pin; two identically damaged copies do
+not pass. This tolerance applies **only to pinned upstream source/licence
+text**, not generated JavaScript, WASM bytes, or package-manifest checksums.
+
+The verifier still checks manifest/pin agreement, byte-exact generated JS,
+WASM hashes, no host imports, ABI, catalogue periods, bounded finite values,
+negative wrapping, sample count and invalid IDs. No source hashes, native
+samples, runtime code, plugin version or release artifacts change in this fix.
+
+## Native rebuilding
+
+`python tools/build-rudiments.py --check` uses the same pinned-text rule. It
+compiles verified source bytes staged into a temporary directory, not modified
+working-tree files. The normal rebuild writes explicit UTF-8 bytes so Windows
+cannot translate generated JS or manifest line endings, and writes the verified
+upstream licence bytes. The rebuild still requires the documented compiler(s);
+ordinary validation needs none.
+
+A normal rebuild may produce different compiler-dependent WASM bytes and
+updates its generated manifest as before. Those changes need review; this fix
+does not regenerate the shipped backend or claim cross-compiler byte identity.
+
+## Regression checks
+
+```powershell
+node .\tools\verify-rudiments.cjs
+node .\tests\rudiments-line-endings.test.cjs
+```
+
+The regression suite uses temporary copies, reproduces the reported hashes,
+checks the actual verifier and source-ownership test under LF and CRLF,
+rejects substantive source/licence edits and JS/WASM tampering, verifies a
+local Git checkout with `core.autocrlf=true`, and runs the Python builder's
+matching tests. The existing Unit runner discovers the new `.test.cjs` file.
+It requires Git and Python as well as Node, but no C++ compiler and no network.
+
+An independently runnable Python check is:
+
+```powershell
+python -X utf8 .\tests\test-rudiments-line-endings.py
+```
+
+After the targeted checks, rerun the repository's complete Unit gate. A source
+integrity pass is not a browser, WordPress deployment or release approval.

package/docs/shared-feature-coverage.md

@@ -0,0 +1,34 @@
+# Feature coverage and execution boundaries
+
+No original browser engine is reimplemented in WordPress or React. The shared
+factory compiles the ten canonical engine/data files and retains the existing
+CSS and admin source. This table is a feature map, not a claim that browser or
+physical tests were executed in a restricted development environment.
+
+| Feature | Shared entry/API | Demo/test coverage |
+|---|---|---|
+| BPM, ticks, duration quantization, boundaries | Main factory/core methods | Existing clock/scheduling/interval gallery; original core tests |
+| CSS timing/control/lyric disclosure | Core properties + CSS | WordPress-style clock/shared timing demos; original CSS contracts |
+| Named cues, intervals, DOM events, animation ownership | Core methods | React cue panel; original 23-page gallery and core contracts |
+| Lyrics, clear entries, both look-aheads, master matching | Core + React useLyric | Canonical Arcadians player in both React apps; old lyrics/master demos |
+| Pointer, playbackPulse, cueClass, cueTimeline, quality | `runtime.effects` | Five React panels, actual transformed-registry tests, original effects/timeline tests |
+| Catalogue CSS adoption | `catalogue:true` | Original catalogue demo now imports the module; original source test |
+| All nine named orientation adapters | `orientation.adapter`, orientationCore | All nine original gallery layouts retained; original adapter/scheduler tests |
+| Generic orientation and recorder | `createOrientation`, `createRecorder` | React permission/capture panels; lifecycle/server tests; real-device permission still manual |
+| Clay cover/lights/particles/quality/native background | `clay:true`, getClay/getClayRudiment | React Clay panel, original Clay contracts and native adapter tests |
+| Paper planes | `effect:'paper-planes'` | React/Next plane panel using the shipped atlas; original flight tests |
+| All 15 native patterns and custom render callbacks | `runtime.rudiments` | React 15-motion grid; original Canvas/clock demos; actual WASM tests |
+| Diagnostic attribution and lifetime inspection | diagnostic sink, resources/on/destroy | Original diagnostic demo, React inspect/unmount controls, scope tests |
+| Page metadata and validation/revisions | Config exports, PageMetadataEditor, memory store | React metadata panel; server config tests; PHP's original native storage kept |
+| Timing upload validation | `/server.validateTimingFile` | Strict UTF-8/order/extension/clear-line tests; PHP validation retained |
+| Signed MP3 downloads | `/server.createDownloadService` | Actual temp-file GET/HEAD/path/signature tests and Next route smoke |
+| Private capture HTTP handling | `/server.createCaptureHandler` | Auth/origin/body/storage/rate tests, Next private-file route, original PHP posts retained |
+| SSR/Strict Mode and independent roots | createScope + React hooks | ESM/CJS/React SSR tests, actual Chromium mount/unmount tests, focused resource tests |
+| No duplicate WordPress frontend | PHP aliases + shared build | PHP queue test; ZIP builder's byte equality and two-JS invariant |
+| npm/web/WordPress release pipeline | CI/release workflows | Version/lock/checksum gates and idempotent publisher scripts |
+
+The React/Next gallery reuses one React implementation and one Arcadians media
+set. The 23 original workbench pages remain separately addressable but now load
+the module rather than raw plugin scripts. A simulated metadata/HTTP demo is
+not evidence of real WordPress capabilities, and synthetic sensor data is not
+physical-device performance evidence.

package/docs/shared-runtime-migration.md

@@ -0,0 +1,111 @@
+# DanceMoves 3: one source, three distributions
+
+This is the 3.0.0 **source candidate**, based on DanceMoves 2.9.0 commit
+`3a6e67652a1bf6968b9ac0715ee5d5eff1e74c98`. Applying the patch does not publish
+anything or change an installed WordPress site. The npm package name is
+`@kieransimkin/dancemoves`; package registration and trusted publishing require
+maintainer action before the first publication.
+
+## Repository architecture
+
+| Location | Responsibility |
+|---|---|
+| `assets/` | The single maintained implementation of the existing browser engines, CSS, editor frontend and native data. These are now shared-library source, not a second WordPress implementation. |
+| `src/index.mjs`, `src/scope.mjs` | Explicit per-root mounting and ownership of browser resources. |
+| `src/config.mjs` | Host-neutral metadata validation, WordPress metadata conversion and bounded revision-store abstraction. |
+| `src/react.mjs` | Optional client-only React hooks, provider, rudiment component and metadata editor. |
+| `src/server.mjs` | Node HTTP services for timing validation, signed MP3 attachments and private captures. |
+| `src/wordpress.mjs`, `src/wordpress-config.mjs` | Thin adapter that imports the shared factory, reads WordPress's localized configuration and restores legacy globals. No animation implementation. |
+| `kieran-epk-device-orientation.php`, `dance-moves-rudiments.php` | WordPress-native settings, media, metadata revisions, download/capture endpoints, page selection and enqueue aliases. |
+| `tools/build-modules.mjs` | Deterministically compiles the existing engines into scoped ESM installer functions. No runtime eval, Function constructor, CDN or script injection. |
+| `tools/build-shared.mjs` | Produces ESM/CommonJS, React/Node entrypoints, minified browser and WordPress library artifacts with esbuild. |
+| `lib/` | Generated shared-library outputs; ignored by Git, included in npm. |
+| `.build/wordpress/` | Separate WordPress staging tree; includes selected **byte-identical** `lib/` outputs, never raw engine sources. |
+
+The compiler does not create a second definition of a movement, timing parser,
+cue handler or adapter. It moves each canonical script's execution inside an
+installer function and instruments resource ownership using a TypeScript AST.
+The small checked source substitutions expose timing-file readiness and qualify
+CSS owner identifiers. Unexpected source changes at those integration points
+stop the build rather than silently emitting an incompatible wrapper.
+
+Both distributions consume those same functions. The WordPress archive contains
+`lib/wordpress.js` and `lib/admin.min.js` as its only JavaScript files; the former
+bundles the shared module and its initialization adapter. It does **not** also
+ship a second `assets/dance-moves-core.js`, a separate effect engine or separate
+native-data script. Existing script handles are kept as WordPress dependency
+aliases with `src=false`.
+
+The native movement authority remains the pinned DanceRudiments 0.1.3 C++/WASM
+sample bank. This patch does not import a newer atlas from a sibling checkout.
+`tools/verify-rudiments.cjs` still checks its existing source, licence and native
+hash contracts before building the library.
+
+## Instance lifetime and compatibility
+
+`createDanceMoves({root,...})` installs a runtime into one DOM subtree. Queries,
+CSS timing properties, generated nodes and event dispatch are scoped to that
+root. Separate, non-overlapping roots may use different BPMs and the same local
+controller IDs. Overlapping mounts are rejected. Consumers must call `destroy()`
+on route changes; the React hook does this automatically, including development
+Strict Mode's setup/cleanup/remount cycle.
+
+Mount-time listeners, timers, frames, observers, fetches and generated styles
+are tracked. Disposal aborts outstanding internal fetches, suppresses late
+promise callbacks, removes generated nodes and restores owned style/attribute
+values when the host has not subsequently changed them. A retained destroyed
+runtime is not a valid factory for more effects.
+
+Consumer-owned callbacks that mutate other elements remain the consumer's
+responsibility. Destroy your controllers and undo those writes in your effect
+cleanup. The scope is resource ownership, not a security sandbox.
+
+Normal JavaScript imports do not read or write browser globals. The WordPress
+adapter deliberately enables `legacyGlobals`, preserving `window.DanceMoves`,
+`window.KieranEpkMotion`, `window.DanceMovesEffects`, the native API and adapter
+aliases for existing EPK page scripts. There should be only one legacy-global
+mount per document. Do not run two copies of the WordPress bundle.
+
+## Important boundaries
+
+The new package includes JavaScript equivalents of the server features; it does
+not run PHP in a browser or pretend a client-side object is a database. WordPress
+continues using its own capabilities, nonces, Media Library, post metadata,
+revision storage and private posts. Other applications provide authorization,
+private persistence and production rate limiting to the Node APIs.
+
+The browser API never contains the server download secret. Signed attachment
+URLs are not a DRM/paywall: the ordinary playable MP3 remains a separate static
+URL. Motion-capture client flags are reported observations, not server-attested
+physical-device evidence.
+
+Catalogue adoption is opt-in outside WordPress. In scoped mounts it adopts
+computed durations and inline styles inside that root, without rewriting shared
+stylesheet rules that other React roots may use. Legacy WordPress mode preserves
+the existing global stylesheet-adoption behaviour. Both paths use the same
+canonical catalogue implementation.
+
+## WordPress migration
+
+Build and install the new WordPress ZIP. Keep the existing plugin directory
+`kieran-epk-device-orientation/` and its PHP entrypoint. No page IDs, timing
+attachments or `_dance_moves_*` keys are renamed. The Clay legacy-plugin guard
+and existing page-to-orientation mappings remain in PHP.
+
+Scripts enqueued by handle continue to work. Hand-written URLs to old raw
+`assets/*.js` files must be replaced with handle dependencies or the public npm
+API. Raw source checkouts are not installable plugin ZIPs: build first. Cache
+URLs now point into `lib/` and use the new plugin version.
+
+For using a retained 2.9.x release, use that release's instructions; do not move
+its published tag or replace its assets. The new release workflow is for tags
+created after this migration is committed.
+
+## Guides
+
+- [JavaScript API](javascript-api.md)
+- [React and Next.js](react-next.md)
+- [Node services](javascript-server.md)
+- [WordPress installation and metadata](wordpress-shared-runtime.md)
+- [Builds, CI and publishing](releasing-shared.md)
+- [Unchanged native API contract](../RUDIMENTS-API.md)

package/docs/source-audit.md

@@ -0,0 +1,120 @@
+# Documentation source audit
+
+[Documentation index](README.md) · [Machine-readable inventory](api/surface.json)
+
+## Baseline and scope
+
+This documentation describes **DanceMoves 2.8.0**, release tag `v2.8.0` at
+`4cb6a71f60459b5579be87d7e55ac8b1426c578e`, whose commit message is
+“Add shared cue timeline transport recovery” (28 September 2026). GitHub's latest
+published release was rechecked on 29 September 2026. The default branch `main`
+is not the current release baseline: it still points to 2.4.0.
+
+The staging branch `timed-lyrics-staging-2026-09-20` at
+`c95f24f326a5f5334e4fe63c1e705ec13b1d59d6` is one commit ahead. The comparison
+changes only `migration/dance-moves-2.8.0-cue-timeline-staging-2026-09-28.md`
+(publication evidence); no runtime or README delta is being silently omitted.
+This reference and patch target the release and also match that staging revision.
+No 2.9 feature is inferred from a recollection or an unverified local workspace.
+
+The published release asset lists ZIP SHA-256
+`599d6e377f142d8b56dfb735df96122993fb8ce1015fe582533f21e408f30e48`.
+That is provenance from the release metadata, not a claim that this documentation
+review independently downloaded/deployed that ZIP or verified a live WordPress
+installation. This patch changes documentation only and supersedes the earlier
+2.4.0 documentation patch rather than layering on top of it.
+
+The reference covers the public timing object and alias, conditional catalogue
+additions, orientation helper exports and diagnostic lifecycle handle, Clay/Stars
+adapter, paper-plane API, all five shared effect factories and their returned
+handles, all entrypoint PHP functions, metadata, registered hooks, enqueued
+handles, signed-download HTTP API, REST capture, timing formats, events, CSS/DOM state and development
+workflow. It does not promote internal local functions or test-only globals into
+supported page APIs.
+
+[api/surface.json](api/surface.json) records the reviewed source blob IDs and
+export/function inventory, so the next documentation update can compare actual
+exports rather than relying on release prose. A symbol appearing in that
+inventory means it was documented; it is not an assertion that every code path
+has an automated or physical-device test.
+
+## Source-to-reference map
+
+| Source | Reference coverage |
+| --- | --- |
+| [Plugin entrypoint](../kieran-epk-device-orientation.php) | [WordPress/PHP/REST](api/wordpress.md): constants, all PHP functions, metadata schemas and sanitisation, editor validation, capture permission/payload/errors, asset loading and legacy collision. |
+| [Shared effects](../assets/dance-moves-effects.js) | [Effects API](api/effects.md): all factories, registry methods, return handles, options, payloads, restoration, accessibility and quality rules. |
+| [Paper-plane JS](../assets/paper-dreams-flight.js), [CSS](../assets/paper-dreams-flight.css) | [Paper-plane API](api/paper-planes.md): metadata gate, config, DOM requirements, methods, snapshot, physics/clock distinction and lifecycle. |
+| [Download helpers in PHP](../kieran-epk-device-orientation.php) | [Downloads](api/downloads.md): all eight functions, query vars, filtering scope, HMAC, GET/HEAD, headers, errors and security limits. |
+| [Timing core](../assets/dance-moves-core.js) | [JavaScript](api/javascript.md): properties, all exported methods, types, clocks, scheduling, parsing, audio selection, ownership, events, diagnostics and limitations. |
+| [Catalogue adopter](../assets/dance-moves-catalogue-timing.js) | [Adapters](api/adapters.md): conditional methods/aliases, root selection, conversion evidence and observer/ownership boundaries. |
+| [Orientation core](../assets/ks-epk-device-orientation-core.js) | [Adapters](api/adapters.md): every exported helper, factory options, returned methods and snapshot/detail fields. |
+| [Orientation runtime](../assets/ks-epk-device-orientation.js) | [Adapters](api/adapters.md): all nine page adapters, configuration, permission and lifecycle behavior; [styling](api/styling.md): state and release-local outputs. |
+| [Clay/Stars runtime](../assets/clay-stars-effects.js) | [Adapters](api/adapters.md): parameters, methods, complete snapshot, lifecycle, adaptive performance configuration and recovery. |
+| [Core CSS](../assets/dance-moves-core.css), [orientation CSS](../assets/ks-epk-device-orientation.css), [Clay/Stars CSS](../assets/clay-stars-effects.css) | [Styling](api/styling.md): timed variables, declarative starts, lyric structure, shared transitions, output attributes, performance/reduced-motion/forced-colours treatments. |
+| [Admin selector](../assets/dance-moves-admin.js) | [Guide](guide.md) and [WordPress](api/wordpress.md): selection/clear UI, filename extension check and the stronger server-side save validation. |
+| [Unit/package coordinator](../tools/validate.ps1), [packager](../tools/package.ps1) | [Development](development.md): exact invocation, side effects, package allowlist and warning-vs-gate distinction. |
+| [Tests](../tests/) and [test plan](../TEST-PLAN.md) | [Development](development.md): focused contracts, planned versus implemented checks, acceptance evidence and physical-device limitations. |
+
+## Corrections and details that matter to integrations
+
+| Previous ambiguity or easy assumption | Source-accurate contract in this reference |
+| --- | --- |
+| Performance quality only steps down, using fixed 45/50 FPS cutoffs | The current runtime can recover, uses session-observed cadence-relative thresholds and defaults to three poor windows. In Clay/Stars, legacy fixed-FPS fields are read but no longer drive decisions; the generic quality primitive is a different algorithm. |
+| The latest plugin must be whatever `main` says | Releases/tags establish 2.8.0; staging differs only in publication evidence. |
+| Every lyric preview means the next LRC entry | `next*` includes blank clears; `nextVisible*` skips them. Both have timestamps and sentinel values. |
+| Core and shared timelines use identical seek rules | Core queues one nearby cue by default; timeline landing callbacks are opt-in and not queued while paused. |
+| A timeline snapshot `fired` list is an execution log | It also contains past cues marked consumed on rebuild; `active` holds half-open interval IDs. |
+| All motion uses one scheduling model | Page scheduling can invoke synchronously at an immediate boundary; audio scheduling waits for playback. Interval subscriptions and duration quantisation use different tick rounding rules. |
+| `currentTick({clock:"audio"})` freezes while paused | Without usable playing audio, it returns the page clock. Playback-bound schedulers separately wait for playback. |
+| A file called `.cue` accepts standard CD cuesheets | The plugin consumes bracketed LRC-style timestamped labels, not `TRACK`/`INDEX` syntax. |
+| Upload validation, editor selection and REST updates are equivalent | Upload checks are limited, editor selection validates file content/order, and REST attachment metadata only sanitises the ID. Trusted integrations must explicitly use the full attachment validator. |
+| Pop-up opt-in makes lyrics into a generic design preset | The component is neutral and visual-only. A release-specific treatment and accessible full lyric section are required. |
+| `onLyric()` reports every playback state | It reports indexed lyric changes/re-indexing. Pause/end hide the built-in layer but do not emit an empty lyric event. |
+| No layer can exist without valid lyrics | Initial creation checks the entry list, but a later bound-audio tick can create an empty idle layer when pop-ups are enabled. Layer existence is not successful-load evidence. |
+| Lyric overrides belong under `.ks-epk` | The renderer appends the layer to `body`, outside the EPK root. Override the component using a release-specific ancestor/page selector. |
+| Cue callbacks contain all parser fields | The dispatched cue detail omits `normalisedLabel`, although parsed cue entries include it. |
+| Repeating intervals are fully seek-aware | Forward jumps skip old boundaries; backward seeks can retain the old boundary. Remove/re-register where immediate rebasing is needed. |
+| All matching audio players share one independent clock per effect | Cue/lyric detection binds per player, but interval helpers follow the latest active player and the visual lyric layer is shared. Avoid simultaneous playback. |
+| `discoverAudio()` supplies automatic dynamic observation | It is an explicit discovery pass; call it after inserting new audio. Existing bound elements are not fully revalidated when their source changes. |
+| Catalogue ownership is a complete CSS isolation boundary | Selectors and referenced variable definitions can also match outside the release. Broad/mixed selectors still require an ownership review. |
+| Every orientation transition is compositor-only | The existing Light Will Win hero transitions `background-position`; device performance remains an empirical acceptance check. |
+| All public JavaScript has a global destroy/reconfigure API | The core has no global destroy or dynamic BPM setter. Each registration owns its remover, and some adapter teardowns leave CSS or registered scopes. |
+| Motion capture is authenticated by a private deployment secret | The legacy capture token is fixed in public source, with no user-capability check on that route. Origin checking is conditional on a supplied origin. Treat it as a restricted legacy diagnostic interface, not a strong authentication design. |
+| Unit success means every EPK has passed pre-live validation | The California full-page scaffold failure is a warning in the current coordinator. Browser, release and physical-device evidence remain separate gates. |
+| Shared quality equals the Clay performance adapter | Different sample metrics, limits, cooldowns and preference-initialization behaviour are explicitly documented. |
+| Signed MP3 URLs authenticate individual users or expire | They sign a path with the WordPress auth salt; they are shareable, non-expiring and do not make source media private. |
+| Paper planes are fully beat-quantized and audio-seekable | Page-clock ambient phase and frame-delta physical simulation are different from cue-timeline playback. |
+| A paper snapshot version is the plugin version | Adapter snapshot is 2.6.3 inside DanceMoves 2.8.0. |
+| Paper static mode guarantees three visible reduced-motion sprites | Final reduced-motion CSS hides all planes. Forced colours hides the stage without itself stopping JS. |
+| A docs directory will automatically be included in the plugin ZIP | The packager includes only the PHP entrypoint, root README and assets. This patch keeps full reference docs in the source repository and leaves packaging unchanged. |
+
+These are documentation corrections or exposed implementation constraints, not
+runtime fixes. The patch does not change authentication, parser validation,
+scheduler semantics, CSS ownership, tests, release assets or packaging code.
+Security or lifecycle changes should be reviewed and tested separately rather
+than silently described as already implemented.
+
+## Maintaining the reference
+
+On a later source update, compare the core object literal, catalogue additions,
+orientation factory exports, shared effects and returned handles, paper-plane and
+Clay/Stars object literals, PHP function declarations,
+metadata registration, route registration, configuration reads, event dispatches
+and generated CSS/DOM state against `surface.json`. Update examples, defaults,
+return types, failure behavior and cleanup semantics together.
+
+Run documentation link/encoding/example checks and the repository's unit
+coordinator in a suitable checkout. Verify any changed examples against the
+actual runtime. Mark physical/browser/WordPress checks as `NOT RUN` until they
+have been performed against the exact candidate. Preserve dated QA evidence;
+do not rewrite old results to imply a new build was tested.
+
+## Troubleshooting cleanup
+
+The root README now keeps current, actionable integration checks. The duplicate
+early incident section, long one-off error diary and dated performance incident
+register were removed, not relocated into a new archive document. Current API
+limitations, performance guidance and publication gates remain documented.
+The original complete 89,530-byte README was materialized from GitHub and verified
+against blob `5b58348ff8f1a2b7ace30c3e8cae389dc7061c62` before generating the patch.

package/docs/validation-setup.md

@@ -0,0 +1,102 @@
+# Validation from a clean checkout
+
+[Release guide](../RELEASING.md)
+
+Run the usual command from a complete DanceMoves checkout:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\validate.ps1 -Mode Unit
+if ($LASTEXITCODE -ne 0) { throw "Validation failed; do not release" }
+```
+
+The coordinator now prepares the ignored unit HTML before any adapter test
+tries to read it. No external song workspace, `Z:` drive, browser, network
+request, audio download, C++ compiler or WordPress installation is required for
+that preparation. Node, PHP and Python are still required by the test suite.
+
+## Inputs and outputs
+
+| Harness | Tracked input | Generated unit output |
+| --- | --- | --- |
+| California | `tests/fixtures/california-screamin-unit.html` (synthetic DOM contract) | `qa/california-screamin-unit-candidate.html` |
+| Clay | `qa/prelive/clay-stars/canonical-live-2.3.2.html` (existing pinned signed-out snapshot) | `qa/clay-stars-unit-candidate.html` |
+
+The Clay source must match SHA-256
+`2F3EC40E763E712CCFD5F94C818E0D651F9F98EF8CA925FEB05A9F39D464B038`.
+The builder checks its title, single release root, single player, five chapter
+controls and absence of the WordPress admin bar. It removes old plugin assets
+and injects current local assets, including the effects and rudiments modules.
+The current PHP header and `DANCE_MOVES_VERSION` must agree. Existing production
+asset hashes in the harness manifests are still checked, not regenerated to
+make tests pass.
+
+California's fixture tests the expected adapter DOM and local asset wiring. It
+is explicitly **not** the production page's layout, imagery, audio or complete
+motion stack. Tests of native sensor mapping and lifecycle continue to run
+against the actual production JavaScript elsewhere in the existing suite.
+
+The generator writes only `*-unit-candidate.html`; existing
+`*-harness-candidate.html` full-page QA files are not overwritten. Repeat runs
+leave identical generated bytes and timestamps alone. Unit HTML is already
+ignored by `qa/*.html` and remains excluded from the WordPress ZIP.
+
+Preparation can also be invoked separately for diagnosis:
+
+```powershell
+node .\tools\prepare-test-harnesses.cjs
+node .\tests\california-adapter.test.cjs
+node .\tests\clay-adapter.test.cjs
+```
+
+Both adapter tests prepare their own unit input when invoked directly. Do not
+create an empty missing HTML file or comment out a failing assertion.
+
+## Why the old command failed
+
+The old California adapter test unconditionally opened an ignored generated
+file, but the Unit coordinator never generated it. The old preview builder
+also assumed a private path under `Z:\My Songs\Releases\California Screamin'`.
+Clay's test had the same unprepared-output dependency. Those private/generated
+prerequisites are now outside the normal Unit path.
+
+The historical preview builders are not called by Unit and have not been
+silently repurposed as production evidence. Their full-page workflows still
+need a verified source payload and appropriate live/browser review.
+
+## Unit versus pre-live acceptance
+
+The coordinator supplies `--candidate-file` to the existing Python scaffold
+validator. It changes the candidate input for **that invocation only**, not the
+manifest or its full-page path. All existing manifest, production-hash, CSS-risk
+and encoding checks continue to run. A failure in either unit scaffold is fatal;
+the California unit audit is no longer hidden behind a broad warning.
+
+The generated HTML has:
+
+```html
+<meta name="dance-moves-fixture" content="unit-only">
+```
+
+The Python validator reports this limitation during scaffold checks and rejects
+it in `--mode prelive`. Pre-live mode also rejects `--candidate-file`, even when
+called as a Python function instead of through the CLI. It still uses the
+manifest's full-page candidate and requires the existing browser, screenshot and
+physical-device evidence. A passing Unit run does not approve deployment.
+
+## Missing or changed tracked input
+
+A missing Clay source, wrong source hash, missing runtime asset, invalid release
+identity or mismatched plugin version is a hard error before candidate writes.
+Check `git status` and restore only the affected tracked input from the intended
+revision after preserving deliberate local edits. Do not automatically update
+hashes, copy an unrelated EPK or recreate a private drive to get past the error.
+
+Regression checks added for this setup:
+
+```powershell
+node .\tests\harness-preparation.test.cjs
+python .\tests\test-harness-candidate-selection.py
+```
+
+No plugin runtime, page metadata, release version or packaging behavior changes
+as part of this validation-setup repair.