@lovelace_lol/embody 0.0.15 → 0.0.16

package/README.md

@@ -9,6 +9,28 @@ Embody is a Rust/Wasm character animation core for facial action units,
 visemes, bone controls, baked animation clips, and hair motion. Three.js is a
 host adapter, not the runtime implementation.
 
+## Reading historical saved movements
+
+`decodeLegacyPose(record, historicalProfile?)` and
+`decodeLegacyAnimation(record, historicalProfile?)` translate retired named
+`semanticPose` / `semanticAnimation` records into existing numeric AU fields.
+The translation and conflict checks live in Rust. Await `initEmbodyCore()` before
+decoding historical records; ordinary records without the retired field return
+unchanged and do not require initialization. Inputs are JSON saved records.
+
+Explicit `historicalProfile.bodyControls` metadata is authoritative, including an
+empty map. Only when that metadata is absent does the decoder use the embedded
+historical table. Unresolved names, conflicting authored values, and opposing
+pose directions fail without changing the input. Keyframe seconds, balance,
+morph strength, custom profile IDs, and unrelated saved metadata are preserved.
+The returned copy removes the decoded retired field; this does not write storage.
+
+These readers do not consolidate eye mappings, assign FACS/body namespaces,
+convert curve snippets into explicit channels, or change native playback. Those
+migrations require profile-specific equivalence and compiler parity work under
+[Polymer epic #325](https://github.com/meekmachine/Polymer/issues/325). Semantic
+readback and slider ownership remain separate integration work.
+
 ## Architecture
 
 ```text
@@ -16,14 +38,16 @@ src/                 Rust source (the Wasm crate) — hair, clips, profiles, run
 assets/presets/      Embedded typed character profiles
 assets/templates/    Embedded humanoid skeleton templates
 three/               Thin Three.js inspection/application adapter only
+model-tools/         Browser/Node GLB preparation, public types, and CLI
 wasm/                Generated-Wasm JS loader + ABI constants
 index.ts             Package re-exports only
 ```
 
-There is no parallel TypeScript hair/physics/runtime core. Hair idle, impulse,
-gravity curves and the spring solver live in `src/hair_curves.rs` /
+There is no parallel TypeScript hair/physics/runtime core. Hair idle, impulse
+and gravity curve helpers and the continuous response live in `src/hair_curves.rs` /
 `src/hair.rs` and are exported through Wasm. Hosts schedule the resulting
-ClipIR on their mixer; they must not reimplement hair sampling in TS.
+ClipIR on their mixer; they must not reimplement hair sampling in TS. See
+[Hair motion](#hair-motion) for how the character host drives them.
 
 The Rust core owns:
 
@@ -35,8 +59,9 @@ The Rust core owns:
 - hair curves, hair physics, and appearance normalization
 - annotation regions, camera gestures/flights/orbits, marker placement and visibility,
   preview/reveal lifecycles, and humanoid template fitting
-- profile-aware screen-space gaze geometry for eye/head AU trajectories
+- on-demand semantic AU reads of active AU-curve clips (no clock or polling)
 - renderer-neutral model analysis and packed live frame generation
+- transient mesh highlight selection, styling, transitions, and versioned preview snapshots
 
 `resolveMorphMeshSelections(profile, categories, availableNames)` resolves editor
 mesh selections in one Rust request. It returns each requested category's effective
@@ -62,6 +87,38 @@ The host animation library (Three `AnimationMixer`, Unity Animator, etc.) owns
 clip playback, lerping, blending, looping, seeking, and crossfades. Rust must
 not sample or lerp clips on the hot path.
 
+For portable body clips, Rust converts Mixamo references/keys into standard
+VRM Animation 1.0 `.vrma` GLB files and retargets supported humanoid tracks.
+The Three adapter exposes `convertMixamoFbxToVrmAnimations`,
+`convertMixamoToVrmAnimation`, `inspectVrmAnimation`, and
+`createAnimationClipFromVrmAnimation`. Initialize Wasm first; supply explicit
+units and a target T-pose reference. See [body-animation interchange](docs/ANIMATION_REFERENCE_POSES.md#mixamo-fbx-and-vrm-animation-body-interchange)
+for examples, supported inputs and errors. VRMA joint rotations remain distinct
+from authored semantic action-space controls and facial/morph snippets.
+
+The same native `Embody` character exposes `supportsVrmAnimation()`,
+`convertMixamoFbxToVrmAnimations`, `getVrmAnimationInfo`,
+`registerVrmAnimation(name, bytes, { metersPerUnit })` and
+`releaseVrmAnimation(name)`. Registration uses the character's captured reference
+and resolved profile, and does not play or stop an action. Polymer's Animation
+agency schedules later playback. Cleanup removes only the accepted native source
+on the original model, preserving a later same-name replacement; disposal is safe.
+
+`Embody` is the character API exposed by the native Three adapter.
+`createRustEmbodyHost`, `createRustEmbodyHostUnbound` and
+`createCharacterHost(...).engine` use that same class. Its profile, mesh,
+material, hair and clip-catalog result types come from `three/authoringTypes.ts`;
+downstream libraries can re-export them without another character interface.
+`getProfile()` returns `Partial<Profile>` because an explicit profile may be
+empty, and `getHairPhysicsConfig()` may be empty before the first model bind.
+`ProfileInput` accepts sparse mappings and app metadata without adding arbitrary
+keys to the output `Profile` declaration. Humanoid queries accept sparse profiles;
+`setHumanoidRoleBinding` returns a sparse profile because Rust omits empty tables.
+The bone editor queries and mutation results follow the same sparse data contract.
+`setAUMorphTargets` preserves its input JSON and guarantees the edited `auToMorphs`
+map. An omitted serialized field is not a request to delete an authored override.
+These type declarations add no playback state, lifecycle or animation clock.
+
 An AU animation drives its profile's mapped bones and morphs through the same
 Rust evaluation used by live AU controls. For example, speech can send an AU
 103 curve and separate viseme shape curves; the profile decides which bones
@@ -78,6 +135,17 @@ construction. Annotation adapters capture DOM input, observe native geometry,
 apply Rust camera/marker frames, render labels and release native resources.
 Camera integration, region selection and marker state belong to Rust.
 
+`createSceneSceneryRenderer` from `@lovelace_lol/embody/three` applies resolved
+scenery layouts to the existing scene: self-contained GLB placements with independent
+world XYZ positions, equirectangular skyboxes, image backdrops and solid colors.
+Applications supply an abortable authorized byte loader and retain saved layouts,
+asset catalogs and Persona/Character/Interaction selection policy. The adapter
+owns model/texture loading, stale-result cancellation and renderer-drained cleanup;
+it preserves the character, lights and existing render loop. Character scene
+settings remain the inherited background beneath scenery, so clearing an override
+restores the latest character configuration. See the
+[scenery contract](docs/SCENE_READINESS.md#scenery-layouts-and-background-ownership).
+
 `ThreeFrameApplier.applyMeshMaterialConfigs(model, profile.meshes)` replays named
 mesh visibility and material overrides when a host binds or replaces a profile.
 It applies explicit `visible: false` and `visible: true` even without a material
@@ -95,6 +163,88 @@ replacing differently sized geometry. Hiding or changing the hover clears its
 sample cache; an explicitly empty mesh selection produces no preview. Applications
 forward hover/show/hide events and dispose the overlay when its scene is released.
 
+### Preparing Actor Models
+
+`@lovelace_lol/embody/model-tools` exposes `inspectActorModel(bytes)` and
+`prepareActorModel(bytes, options)` to prepare separate GLB files for an Actor.
+This module owns file transformations; LoomLarge owns the guided workflow,
+Model upload, Actor persistence, and Mapping selection. It does not load the
+animation runtime or initialize Embody's runtime Wasm.
+
+```js
+import { inspectActorModel, prepareActorModel } from '@lovelace_lol/embody/model-tools';
+
+const source = new Uint8Array(await file.arrayBuffer());
+const inspection = await inspectActorModel(source);
+// Show inspection.meshes to the creator before choosing explicit mesh IDs.
+const prepared = await prepareActorModel(source, {
+  kind: 'low-resolution',
+  targetRatio: 0.5,
+  maxError: 0.001,
+  signal: abortController.signal,
+});
+// Persist prepared.bytes as a new Model only after the operation succeeds.
+```
+
+Inspection returns source-scoped mesh IDs, original names, node names,
+materials, vertex/triangle counts, skin and morph presence, total byte length,
+and processing limitations. Preparation returns a new byte array, before/after
+inspection, the removed source mesh IDs, and warnings. It never writes into the
+input array, fetches resources, or persists an Actor.
+
+| Kind | File operation |
+| --- | --- |
+| `original` | Copy source bytes exactly. |
+| `optimized` | Compact unused vertex data and remove explicitly selected meshes and orphaned file resources. |
+| `low-resolution` | Reduce triangle count; default target is 50%, limited by geometry, rig protection, and error. |
+| `miniature` | Apply an explicitly supplied uniform `scale` above existing scene roots. This changes physical scale, not texture resolution. |
+| `bust` | Keep explicit `keepMeshIds`; requires separately authored body-part meshes. |
+| `outfit` | Keep/remove explicit mesh IDs for a prepared outfit; never guess garments from names. |
+
+`targetRatio` accepts 0.05–1 and `maxError` accepts 0–0.05 relative to each
+primitive's extent. `scale` is required only for miniature and accepts 0.01–0.99.
+Mesh IDs belong to the inspected input; inspect each new file before editing it
+again. Removing a shared mesh removes all its instances. A combined body mesh
+must be split in a modeling tool before a bust or garment can be removed. These
+tools do not generate clothing, transfer garments between rigs, cut surfaces,
+or implement runtime garment switching.
+
+Processed variants require self-contained, extension-free GLB. Unsupported
+extensions (including compression and VRM) or resource URIs produce an explicit
+error before rewriting. Original copies retain such payloads and inspection
+reports `canTransform: false`; hosts must still apply their upload policy.
+Textures keep their original bytes and dimensions. Output includes actual byte
+and triangle counts; a requested reduction is not a size guarantee.
+
+Triangle reduction locks vertices participating in any morph and vertices at
+skin-influence transitions. It preserves topological borders and weighs normals,
+UVs, and colors. All retained attributes, including joints, weights and every
+morph target, use one vertex remap. Existing mesh/node names, skeleton hierarchy,
+bind matrices and surviving animation targets remain intact. Only morph animation
+channels targeting an explicitly removed mesh are removed, with a warning.
+No node, joint, or surviving morph target is renamed. Hosts must review Mapping
+targets when source names are missing/duplicated or a mapped mesh was removed;
+vertex-index annotations require remapping after compaction.
+
+Cancellation is checked between processing stages and primitives. A synchronous
+simplifier call cannot be interrupted halfway through; hosts should use a worker
+when processing large assets must not occupy the UI thread.
+
+The installed `embody-prepare-actor` command uses the same implementation:
+
+```bash
+embody-prepare-actor --input character.glb --inspect
+embody-prepare-actor --input character.glb --output low.glb --kind low-resolution --ratio 0.5
+embody-prepare-actor --input character.glb --output outfit.glb --kind outfit --remove-mesh mesh:2
+embody-prepare-actor --input character.glb --output bust.glb --kind bust --keep-mesh mesh:0
+```
+
+Repeat `--remove-mesh`/`--keep-mesh` for multiple selections. The CLI refuses an
+existing output path, including the source file or a symlink to it. It prints a
+JSON report after creating the new file. In a source checkout, invoke
+`node model-tools/prepare-actor.mjs` with the same arguments. CI runs the
+`test:model-tools` regression source as part of the existing package checks.
+
 ### Annotation runtime
 
 `AnnotationRuntime` in `src/annotation_runtime/` owns the annotation behavior
@@ -124,11 +274,31 @@ HTML overlays align with the canvas rectangle inside its container, update on
 resize/rebind, and restore borrowed parent positioning when the final view is
 disposed. These coordinates assume axis-aligned CSS boxes without transforms.
 
-AU morph anchors currently sample native deformed vertices during marker
-preparation, then follow the selected object's transform. They do not yet
-resample morph weights or skinning on subsequent frames. Animated surface
-tracking requires cached vertex candidates and per-frame pose observations;
-ordinary object-transform tracking does not provide that behavior.
+AU morph anchors follow morph and skeletal animation on each annotation update.
+Rust selects and caches affected vertices and their influence weights during
+marker preparation, using mesh-space geometry so rotating a character cannot
+change the selected semantic band. The adapter evaluates those vertices in the
+current native pose and supplies packed world-space positions; Rust updates the
+existing anchors without restarting reveal or rebuilding marker resources.
+Explicit point and whole-model anchors retain their existing behavior. Model or
+region changes invalidate the plans, and stale or invalid pose observations are
+ignored. Geometry replacement, attribute replacement, morph dictionary edits and
+relative/absolute mode changes are observed on `update()`. For in-place attribute
+edits, set the Three attribute's `needsUpdate = true` (including interleaved
+attributes). Rust retires the affected plans and selects replacements without
+reloading regions or replacing marker resources. When a previously valid
+attachment loses usable position or morph data, its marker becomes hidden and
+`getMarkerPosition()` returns `null` until that data returns. Other attachments
+and current selection remain intact.
+
+`getRuntimeAUMorphAnchorPoint` uses the same Rust mesh-space selection and weighted
+pose reduction as live attachments, including rotated and skinned meshes. Native
+adapters only report geometry identities/versions and evaluate selected vertices;
+they do not choose semantic bands or compute attachment weights. Other adapters
+can report monotonically increasing per-object revisions with
+`observe_morph_geometry` before preparing replacement plans, then submit packed
+world-space XYZ samples to `observe_morph_anchor`. Plan IDs are scoped to the
+runtime generation; retired IDs and older geometry revisions are rejected.
 
 This is a breaking replacement of the DPthree exports. Use
 `ThreeAnnotationController.create(options)` or `ThreeAnnotations.create(options)`
@@ -141,16 +311,20 @@ instance. Region and camera snapshots are observations; mutate through controlle
 methods. Explicit `undefined` fields in `updateAnnotationRegion` remove overrides.
 `getCharacterConfig()` retains snapshot identity until configuration content or
 the model changes; selection, visibility and camera input do not replace it.
+Authored intro focus targets use the same framing as manual region selection;
+extra eye padding and composition bias apply only to the default region target.
 Call `clearModel()` before releasing a removed model's native resources. The
 controller retains renderer rebinding, canvas input reconnect and resource-drain
 support through the scene's rendering controller.
 Runtime preview region IDs retain the `runtime:annotation:` namespace.
 
 When the annotation controller owns the renderer loop, it advances registered
-native character mixers before observing annotation transforms and drawing the
+native character mixers before observing annotation poses and drawing the
 scene. The first frame establishes the timer origin; skipped asynchronous draws
 do not accumulate playback time. External render loops use the existing
-`createScenePlaybackFrame` integration to advance character playback.
+`createScenePlaybackFrame` integration to advance character playback, then call
+`annotations.update()` before drawing. No per-frame application-side anchor
+logic or agency registration is required.
 
 ```ts
 import { ThreeAnnotations } from '@lovelace_lol/embody/three';
@@ -209,6 +383,29 @@ React hosts forward user events and subscribe to controller state. They do not
 need local copies of the camera, marker, placement or timer algorithms.
 The convenience facade delegates to one controller-owned marker layer.
 
+## Character model loading
+
+The Three adapter loads GLB/glTF and FBX characters into the same
+`{ model, meshes, animations, gltf }` result. `meshes` contains morph-enabled
+meshes; FBX results have `gltf: null`. Both formats use the same shadow setup,
+model transforms, inspection, and disposal helpers.
+
+```ts
+import { loadCharacterModel, parseCharacterModel } from '@lovelace_lol/embody/three';
+
+const character = await loadCharacterModel('/characters/avatar.fbx');
+// For blob URLs or endpoints without a file extension, supply the format.
+const uploaded = await loadCharacterModel(objectUrl, { format: 'fbx' });
+// Standard binary/ASCII FBX headers are detected automatically. The resource path resolves
+// external textures referenced by the file.
+const cached = await parseCharacterModel(buffer, '/characters/textures/');
+```
+
+Use `format: 'gltf'` or `format: 'fbx'` to override detection. Draco options apply
+to glTF only. FBX rigs, morph names, scale, and external texture paths depend on
+the export; use a matching character profile and model transform as needed.
+Loading a format does not automatically retarget its rig or rename its morphs.
+
 ## Runtime Use
 
 Embody is an ES module package. Use `import` / dynamic `import()`; CommonJS
@@ -258,8 +455,61 @@ function update(dtSeconds: number) {
 }
 ```
 
-Application-facing JavaScript APIs belong in the host package. Polymer owns
-the CLJS character host used by LoomLarge and calls the Wasm exports directly.
+Embody owns the native Three character API and mixer binding. Polymer exposes
+that API through its CLJS facade for LoomLarge; the facade does not own another
+playback clock or hair simulation.
+
+### Hair motion
+
+When the profile enables `hairPhysics` and its registered hair/eyebrow meshes
+contain mapped targets, the Three character host plays one additive native action,
+`__embody_hair_response`. Rust's `HairResponse` owns velocity, spring displacement,
+ambient phase and gravity response. `RuntimeCore.build_hair_response_clip` emits
+zero-neutral morph offsets; the host replaces samples on the existing native
+action when its target bindings stay the same. Numeric tuning and head retargets
+preserve both the action identity and the simulation state.
+
+After every mixer has sampled, and before native completion releases its
+resources, `renderScenePlayback` passes the effective mixer delta to the character.
+The character observes the profile's humanoid `head` role in model space relative
+to the captured reference pose, including parent neck/spine motion. It expresses
+that delta in the bound local reference before passing primitive quaternions to
+Rust. The model root's placement rotation is excluded. Snippets, baked clips,
+live setters and external bone writers therefore drive the same response.
+A profile without a head role still supports idle and wind with no invented rig
+mapping. Rebinding primes head history only after restored live controls have
+sampled, avoiding a false rest-to-pose impulse.
+
+Rust combines observed angular velocity, idle/wind, and smoothed pitch gravity
+using `inertia`, `stiffness`, `damping`, `gravity`, `responseScale` and `direction`.
+Directional mapping approaches neutral with zero slope. Contributions sharing a
+concrete morph add before a soft limit keeps that response within `[0, 2]`.
+The next native mixer sample applies the resulting offsets, so output trails the
+observed head by one render step. There is no second mixer update or hair timer.
+Playing, replaying or retargeting a caller clip performs no hair work.
+
+`Embody.stop()` suspends response sampling with rendering. Mixer time scale zero
+freezes physics; reversed native playback still advances physics forward while
+the actual reversed pose determines motion direction. A renderer gap longer than
+250 ms re-primes head velocity and integrates at most 250 ms of settling. Numeric
+configuration edits preserve momentum and ambient phase. Clearing mappings releases
+native output without erasing simulation state; disabling hair resets dynamics.
+Registration, model rebind and profile replacement start a new response binding.
+Disposal removes its render hook and releases native output.
+
+Hair actions have explicit character ownership. `stopAllAnimations`, `crossfadeTo`,
+`pauseAllAnimations` and `resumeAllAnimations` leave them running; Stop All and
+crossfade also leave live setter targets intact. Aggregate pause/resume continues
+to pause/resume live setter transitions as well as caller playback. Explicit
+`pauseAnimation('__embody_hair_response')` freezes the simulation, and that pause
+survives cleared mappings and disable/re-enable until the matching
+`resumeAnimation` call. Profile replacement starts a new configuration.
+
+`playHairImpulse(horizontal, vertical)` retains its existing separately controllable
+one-shot native handle. It is never triggered by caller clip admission. The lower
+level `RuntimeCore.add_hair_response_impulse` instead injects velocity into the
+continuous response without creating an action; neither path replaces head history.
+Legacy idle/impulse/gravity curve exports remain available to explicit consumers.
 
 ### Direct viseme snapshots
 
@@ -337,50 +587,6 @@ when the Three clip is constructed. Hosts must construct it again to capture
 a fresh pose; this does not change cached host replay or generated bone
 inheritance behavior.
 
-### Gaze geometry contract
-
-`solve_profile_screen_space_gaze` and `solve_profile_viewer_space_gaze` return
-14 floats: combined target XY, eye target XY, head target XY, total yaw/pitch,
-camera yaw/pitch, eye-to-camera distance, and viewer world XYZ. XY outputs are
-signed AU intensities in [-1, 1]; positive Y is up and horizontal direction is
-subject-relative. Angular values are degrees.
-
-Pass current world camera position/quaternion, character eye midpoint, and
-model quaternion. The viewer solver takes normalized image XY (+Y up) and
-depth behind the virtual camera; depth and all positions must share scene
-units. Convert physical webcam estimates before calling and supply the actual
-source FOV/aspect. Zero viewer XY extends the character-eye-to-camera bearing,
-so the character looks at the viewer even when scene framing puts its eyes
-away from image center. Offsets retain the camera's right/up axes; when the
-camera coincides with the eyes, its local +Z supplies the fallback bearing.
-The depth guard is 0.2–10 scene units. Mouse and webcam can share this contract
-when they use the same calibration.
-
-Ordinary head following participates toward the common target from calibrated
-model-neutral +Z: `head_follow_fraction` is a share of the target yaw/pitch,
-defaulting to 0.35 for a non-finite value. Zero prefers neutral, one follows the
-full target, and eye overflow can recruit more head movement within its limits.
-The explicit `lock_head_to_camera` flag instead prefers the camera bearing while
-eyes can reach; a zero follow fraction alone does not select that policy. When
-eyes are disabled the head carries the target regardless of follow or lock.
-This removes the previous implicit camera bias, which could point the head
-opposite the selected target when the camera was off-center. Hosts that intend
-camera-facing behavior must request the explicit viewer-solver lock; Polymer's
-`headFollowEyes: false` maps to zero participation, not an implicit lock.
-Eye angles are solved in the
-rotated head frame, using yaw then pitch to match runtime composition. Limits
-and AU normalization are directional and include each binding's scale. Missing
-or morph-only mappings contribute no inferred angular capacity.
-
-The profile must describe the active rig with calibrated semantic axes:
-model +Z is forward, +Y is up. This ABI does not include the skeleton's rest
-frames or optical axes, per-eye origins, current animated head pose, or
-webcam-to-display calibration. It solves an endpoint in the assumed calibrated
-basis; it does not provide binocular convergence or compensate intermediate
-head motion. Shared eye commands use the smaller mapped eye capacity; unequal
-left/right ranges need separate calibration. Hosts must compose the requested
-rotations without averaging independent yaw/pitch clips together.
-
 For import-time inspection, `captureModelReferencePose` provides an explicit,
 immutable transform and morph reference that hosts can reuse after playback.
 `extendModelReferencePose` explicitly adds appended skeletons while preserving
@@ -449,94 +655,6 @@ const report = JSON.parse(wasm.analyze_model_descriptor(
 ));
 ```
 
-## Pose-aware focus
-
-`ThreeGazeFocus` from `@lovelace_lol/embody/three` applies a focus constraint
-inside an animation runtime. It has no clock or target-selection policy:
-call `restore()` before evaluating the base animation, then `apply(request,
-controls)` after it. Restoration compares quaternion orientations independently
-of Float32 sample norms, preserving the exact authored sample and any newer
-authored orientation. Repeated applications between mixer ticks do not accumulate
-the constraint's previous correction. Controls are the current positions of existing motor
-tracks. The optional sampled `controls.headIntensity` and `controls.eyeIntensity`
-override the matching request fields, so the host can animate configuration
-changes on its existing motor tracks. Both mean contribution in [0, 1]: zero
-preserves the evaluated base, one applies the full solved excursion, and legacy
-values above one normalize to one. Intermediate eye contribution proportionally
-reduces the correction; it does not shrink anatomical limits. Reduced eye
-contribution deliberately leaves focus error. These controls do not amplify
-input displacement or control response speed.
-
-During travel, the remaining sampled bearing rotates the requested finite
-target. At the endpoint that rotation becomes identity, reaching the exact
-world target continuously. There is no settled-threshold switch between targets
-constructed from the authored and tracking-shifted eye origins; a larger head
-turn must not introduce a final eye snap.
-
-Pass `{ referencePose }` as the constructor's third argument, reusing the
-reference captured at import. Without it, construction captures the current
-pose, so callers must construct before playback. The head solves its bounded
-gaze excursion in that reference hierarchy under the model's current scene
-transform, then composes the excursion onto the evaluated authored head pose.
-Head and neck gestures retain their motion instead of being cancelled or
-reversed by tracking. Each eye then solves toward the same finite target from
-its own origin in the final animated hierarchy. Full eye contribution retains
-binocular focus wherever the combined authored motion and gaze are reachable;
-otherwise diagnostics report the remaining angular error and limits. Authored
-gestures are not suppressed to force a target into range. The signed limits
-bound the tracking excursion; they do not clamp the final authored pose plus
-that excursion against a neutral-reference joint range. Authored motion can
-therefore take the combined pose beyond that range or the eyes' reach.
-
-`readControlState({worldTarget, headIntensity, eyeIntensity})` provides initial
-motor bearings without changing the rig. It inverts existing focus contributions
-against their saved base, and seeds zero added head excursion when enabling on
-a purely authored pose. When replacing legacy AU controls, also provide the
-evaluated local `headBaseQuaternion` and/or `eyeBaseQuaternions` (a map keyed by
-bone name), with those legacy controls excluded. `headSeedLimited` and
-`eyeSeedLimited` report poses that cannot be represented by the bounded motor
-bearings. Parallel legacy eyes cannot both be preserved exactly by a shared
-finite target; inverse eye contribution avoids double attenuation but does not
-remove that convergence residual. This helper supplies no handoff transition
-clock; the host owns activation policy and movement timing.
-
-The optional `profile.gazeCalibration` supplies bone-local
-`head`, `leftEye`, and `rightEye` optical axes and `modelUnitsPerMeter`.
-Without explicit optical axes, signed yaw/pitch bindings determine the optical
-frame. Unresolvable joints remain untouched and are reported in diagnostics.
-
-`solve_profile_viewer_space_gaze_scaled` adds `world_units_per_meter` as its
-last argument. Multiply the authored units-per-meter calibration by the
-presentation's uniform root scale. The original viewer solver keeps its
-existing scale-one behavior. Neither solver infers physical webcam/display
-placement from face landmarks.
-
-`solve_profile_tracking_gaze` maps normalized display-right/up controls to the
-profile's full signed head AU rotation range. Pass `head_follow_fraction = 1`
-for full participation: on an aligned display axis, an input endpoint of +/-1
-requests the same head rotation as the corresponding AU at intensity 1. Binding
-scale and asymmetric `maxDegrees` remain authoritative. Camera distance and FOV
-do not reduce this range. Intermediate inputs interpolate between the bounded
-camera bearing at zero and the corresponding signed endpoint; camera roll
-rotates the display axes into the model frame. With head tracking disabled,
-the target spans the eye AU range instead.
-
-The signature is `(profile_json, tracking_target, camera_position,
-camera_quaternion, gaze_origin, model_quaternion, eyes_enabled, head_enabled,
-head_follow_fraction, lock_head_to_camera, world_units_per_meter)`. It returns
-the same 14-float layout as the existing physical projection solvers. Target Z
-is depth in meters, clamped to 0.2–10 before scene scaling; it sets a finite
-binocular focus distance without attenuating the angular range. X/Y clamp to
-[-1, 1], nonfinite coordinates become zero, invalid positive depth/scale use
-0.8/1 respectively, and absent AU bindings supply no angular capacity.
-
-This is an input-range mapping, not a physical reconstruction of the viewer's
-position. The existing screen/viewer projection APIs retain their contracts.
-Consumers must select this entry point and request full head participation to
-use it; adding the export alone does not change LoomLarge tracking. Eye focus
-still uses the resulting finite target and reports residual error when reduced
-strength, authored motion, or rig limits make that target unreachable.
-
 ## npm releases and PR previews
 
 Production consumers install an exact published `@lovelace_lol/embody` version
@@ -550,9 +668,11 @@ It chooses the next patch version, records the source commit in `gitHead`, and
 builds and validates once. Stable version selection reads public metadata from
 `registry.npmjs.org` anonymously; redirects and failed lookups stop the release.
 Metadata reads never transmit publishing credentials. The separate
-publish job first requires `npm access get status` to report the existing package
-as public, then uses the `npm` environment's `NPM_KEY` to publish the packed
-output with public access and creates its Git tag and GitHub release. Stable
+publish job first requires the npm visibility endpoint (the endpoint used by
+`npm access get status`) to report the existing package as public. It reads this
+anonymously without npm token configuration, then uses GitHub OIDC trusted
+publishing in the `npm` environment
+to publish the packed output with public access and create its Git tag and GitHub release. Stable
 releases are serialized through version selection and publication. Provenance
 remains disabled for the private source repository. Retrying a published commit
 reuses its existing version, and an older unpublished commit cannot replace a
@@ -564,6 +684,16 @@ previews for testing linked upstream changes. An explicit ref remains a preview
 request even when it names `main`; it does not publish to npm. Manual and
 repository dispatch requests may include `upstream_pr` to identify their linked PR.
 
+For an Embody → Polymer → LoomLarge feature stack, open every draft from its own
+current `main` without waiting for publication. The Polymer PR body declares
+`Depends-on: https://github.com/meekmachine/embody/pull/<number>` and the LoomLarge
+PR body declares `Depends-on: https://github.com/meekmachine/Polymer/pull/<number>`.
+CI resolves the compiled previews in temporary test checkouts. Committed
+manifests and lockfiles retain exact stable npm versions; the release coordinator
+adopts a stable release containing the change after upstream merge and publication.
+Agents do not add preview URLs before opening downstream drafts.
+Documentation-only companion PRs use ordinary reciprocal links instead.
+
 After publication, the producing workflow uploads a JSON notification record
 without a dispatch credential. The separate `Notify package publication`
 `workflow_run` receiver checks out `main`, treats the artifact only as data, and
@@ -587,7 +717,8 @@ release-stack PR's first preview remains usable by its immutable URL before
 that bootstrap merge; subsequent successful publications notify automatically.
 
 Before enabling stable releases, the existing npm package must have public
-visibility and `NPM_KEY` must permit publishing it. No npm read token is required.
+visibility and its npm trusted publisher must match the configuration below.
+No npm publishing secret or read token is required.
 Configure both the `npm` and `release-coordination` GitHub
 environments to allow deployments from `main` only. Store `CROSS_REPO_CI_TOKEN`
 only in `release-coordination`, with permission to dispatch to LoomLarge. These
@@ -595,6 +726,52 @@ account, environment protection, and secret settings are prerequisites; source
 changes do not configure them. Existing versions are never republished or
 overwritten.
 
+### Configure and recover stable publication
+
+The npm package settings must register this GitHub Actions trusted publisher:
+
+| Setting | Value |
+| --- | --- |
+| Package | `@lovelace_lol/embody` |
+| Organization or user | `meekmachine` |
+| Repository | `embody` |
+| Workflow filename | `pr-checks.yml` |
+| Environment | `npm` |
+| Publishing permission | **Allow npm publish** |
+
+New npm trusted publishers default to staging only; explicitly allow publishing.
+The package's `repository.url` must match `git+https://github.com/meekmachine/embody.git`.
+These settings live on npm and cannot be configured by merging workflow YAML.
+Retain account 2FA and GitHub environment protections. The job uses Node 24 and
+requires npm >=11.5.1 (with Node >=22.14.0), publishes without `NPM_KEY` or
+`NODE_AUTH_TOKEN`, and never grants an OIDC token to PR or preview jobs.
+Provenance remains disabled for this private source repository.
+
+A green `pkg.pr.new` preview confirms a preview, not stable publication. The
+main-only publish job writes a **Stable npm publication confirmed** summary only
+after an anonymous exact-version registry read confirms the version and `gitHead`, and
+records the release's SHA-512 integrity. New uploads must match the verified
+tarball's integrity. Retries confirm an existing immutable release without
+assuming that rebuilding the same source reproduces every archive byte. A failed publish or conflicting registry result
+fails the job and blocks downstream notification. npm authentication failures show
+the error code and exact publisher settings to repair, without echoing raw npm
+output or tokens. The publisher checks the exact-version endpoint before any
+upload, with `Cache-Control: no-cache`, so a stale package index cannot cause a
+duplicate upload. Only HTTP 404 means absent; other lookup failures stop publication.
+A new upload gets one exact-version confirmation lookup, without polling. A transient registry failure can leave an upload present
+but unconfirmed; rerun the main release after investigation rather than upload a
+replacement version blindly.
+
+After repairing configuration, run this workflow on current `main` with its `ref`
+input empty. A successful current-main stable release contains all source changes
+already merged into that repository; individual failed intermediate releases do
+not need replaying. Explicit refs and preview dispatches publish previews only.
+An existing matching release is confirmed without publishing it again; source or
+dependency conflicts and new-upload archive conflicts stop instead of overwriting it. The receipt
+establishes npm publication, while the LoomLarge coordinator separately opens or
+updates reviewed stable dependency PRs and lockfiles. It does not establish that
+Polymer or the application adopted the release or deployed it.
+
 ## Development
 
 ```bash
@@ -643,6 +820,31 @@ Reset an authored control by setting its mapped AU values to zero. Hosts select
 which mapped AU IDs to reset; unrelated face state and saved mix strengths remain
 under their existing owners.
 
+### Reading current AU state
+
+Rust records each admitted AU-curve clip's authored keys, resolved inherited
+start, strength and easing. Those records change only at admission or a
+strength/easing edit; nothing ticks them. Reads evaluate them on demand at the
+native action's time and effective weight, so a fading slot reports
+value × weight:
+
+- `readAUContribution(name)` returns one slot's own `{auId: value}`, or `null`
+  when it is not playing or was not an AU-curve clip.
+- `readAUState()` returns `{live, animated, total, unreadable}`: live control
+  values, active AU-curve clip contributions and their sum. Baked/native and
+  typed clips animate rig outputs directly and cannot be inverted to AU values,
+  so they are listed in `unreadable` rather than estimated.
+- `measureAUGoal(name, destinations)` returns `{distance, reversal, current}`:
+  the largest travel from the slot's current contribution to `{auId: value}`
+  destinations, measured along profile `continuumPairs` as `positive − negative`
+  (crossing neutral from 0.3 negative to 0.3 positive is 0.6), and whether it
+  reverses the slot's unfinished travel. Callers apply their own timing policy
+  and send an ordinary inherited clip with the duration they choose.
+
+Each call does a small amount of work in Rust; read when deciding, not every
+frame. See [inherited clip starts](docs/INHERITED_CLIP_STARTS.md) for how
+inherited starts and weights resolve.
+
 Named semantic pose/animation APIs and profile `bodyControls` are retired.
 Persisted named records must be decoded at the storage boundary to numeric AU
 values/curves, using their original profile mappings. `LEGACY_BODY_CONTROL_AUS`
@@ -650,6 +852,62 @@ is a deprecated reader-only historical identity snapshot for old CC4 records;
 it is never consulted for current controls, actuation or profile compilation.
 Unknown legacy names must be reported rather than silently omitted.
 
+### Mesh highlight previews
+
+Rust owns transient mesh highlight state and its renderer-neutral output in
+`src/highlighting.rs`, exposed through `RuntimeCore`. This preview is independent
+of AU/morph/bone actuation, clip playback, and persisted profile data. Rust resolves
+mesh names (including duplicate names) against the configured model, chooses the
+default gold color and intensity, computes darker edges in linear color space,
+and advances a 400 ms eased transition. Interrupted fades resume from the current
+strength; changing targets removes the old preview immediately. Clearing or an
+unknown name fades out the current selection. Repeated identical requests do not
+restart a fade. Model reconfiguration clears transient highlights.
+
+| Core operation | Contract |
+| --- | --- |
+| `request_mesh_highlight(name?, color?, intensity?)` | Request a mesh name or omit it to clear. Optional color is packed 24-bit sRGB; intensity is clamped to 0–1, with nonfinite values using the default. |
+| `evaluate_mesh_highlight_frame()` | Return the current complete JSON snapshot without advancing time. |
+| `advance_mesh_highlight(delta_seconds)` | Advance preview time using the host render clock and return the snapshot. Negative/nonfinite deltas do not advance time. |
+
+Snapshot version 1 contains `highlights`, an array of writes with `meshId`,
+`fillColor`, `fillIntensity`, `edgeColor`, `edgeMode: "triangles"`, and `edgeOpacity`.
+Colors are linear RGB triplets, strength/opacity are in 0–1, and IDs refer to the
+configured model descriptor. The fill is an emissive surface preview and the
+edges show triangle topology. An omitted mesh ID means restore its original
+appearance and release its preview resources. `{ "version": 1, "highlights": [] }`
+clears every preview. The TypeScript contract is exported from
+`@lovelace_lol/embody/wasm` without importing a renderer.
+
+Another renderer configures the same `RuntimeCore` from its own model descriptor,
+keeps a map of mesh IDs to native surfaces, sends requests, and applies snapshots
+from its existing render tick. It does not traverse by name, derive edge colors,
+or reproduce the easing curve. For example, after configuring `core`:
+
+```ts
+core.request_mesh_highlight('Face');
+// Apply the initial snapshot immediately to remove obsolete selections.
+applyNativePreview(JSON.parse(core.evaluate_mesh_highlight_frame()));
+// Inside the host's existing render tick (seconds, independent of clip speed):
+applyNativePreview(JSON.parse(core.advance_mesh_highlight(deltaSeconds)));
+```
+
+`applyNativePreview` is the renderer's effect boundary: resolve `meshId`, apply
+emission and triangle edges from the supplied values, and remove omitted previews.
+The host must advance the core once per frame, even with no playing clips. Pausing
+its render clock pauses preview progression; no additional animation loop exists.
+
+For Three, `character.highlightMesh(name, color?, intensity?)` sends the core
+request; the existing scene playback binding supplies elapsed seconds and calls
+`ThreeFrameApplier.applyMeshHighlightFrame`. The applier only binds mesh IDs and
+manages native materials/overlays, deformation, picking exclusion and disposal.
+It does not choose colors, resolve names, or sample fades. Temporary materials
+are isolated from shared source materials; geometry and skeletons remain owned
+by the source model. Native overlays follow source geometry, morph weights and
+skeletons. Character rebind/disposal removes them. Direct applier consumers must
+call `clearMeshHighlights()` on disposal. Other renderers implement their own
+snapshot application; this change does not supply a second native renderer.
+
 ### Character-derived studio background
 
 The Three `createCharacterHost` paints its container with soft gradients sampled