@lovelace_lol/polymer 0.0.6 → 0.0.8

package/README.md

@@ -1,8 +1,47 @@
 # Polymer
 
+Character runtime hosts expose `getViseme(index)` and `getVisemeJawScale(index)`
+to snapshot direct mouth-shape controls before a temporary preview. These are
+read-only views of Embody's canonical state, not the current mixer pose. Unset,
+cleared, or out-of-range slots return `0` and `1`. Restore a snapshot with
+`setViseme(index, value, jawScale)`; restoring zero releases the direct override
+and allows any underlying clip to keep playing.
+
 Clean ClojureScript character agency package for Character Loom.
 
-Production releases publish to npm as `@lovelace_lol/polymer` on every push to `main`. Hosts should depend on the npm package (`latest` or a semver range). PR staging may still use git SHA pins or `Depends-on` / pkg.pr.new preview URLs.
+Git stores Polymer source only. CI builds and tests each commit once. Verified
+`main` builds publish versioned packages to npm for production; PRs and requested
+preview SHAs publish compiled packages to [pkg.pr.new](https://pkg.pr.new/). Install the
+[pkg-pr-new GitHub App](https://github.com/apps/pkg-pr-new) on this repository.
+Production consumers pin an exact npm version. Work testing an upstream PR pins
+the immutable full-SHA preview URL emitted by CI. Git-SHA installs are unsupported
+because compiled JavaScript is not checked in.
+
+Polymer consumes the public npm release `@lovelace_lol/embody@0.0.8`, built
+from Embody main source commit
+`a55e89edbb22b26059a63ce002a2c3e25caf0cf0`:
+
+```text
+@lovelace_lol/embody@0.0.8
+```
+
+This release retains the renderer lifecycle support and speech AU 103 in
+the existing `JAW.pitch.aus` list in CC4's `compositeRotations`. LipSync can send
+the AU through Animation and use its saved bone and morph outputs.
+
+The CC4 body-control catalog places hip bend, twist and side bend in **Whole
+body**, separate from the waist, spine and chest controls in **Torso**. These
+existing animation controls rotate the hip bone, which carries both torso and
+legs. They differ from import/setup rotation, which rotates the entire model
+object and saves its orientation as `modelRotation`. Hosts using
+`getBodyControls` inherit the catalog labels and sections unless a profile
+explicitly overrides them. Action IDs and bone motion stay unchanged.
+
+The character host restores `profile.meshes` visibility and material settings
+through Embody when binding a model or applying `setProfile`. Explicit hidden
+meshes, zero opacity, disabled depth flags, and render order survive a saved
+profile round trip. Hosts supply the selected character's profile; they do not
+need a second mesh-settings replay path.
 
 Polymer is intentionally separate from Latticework and Polyester. It is built as
 a Society of Mind agency system: small CLJS agencies collaborate through streams,
@@ -11,6 +50,52 @@ responsible for performing them.
 
 See [docs/agency-architecture.md](docs/agency-architecture.md) for the agency
 collaboration, scheduler, side-effect, stream, and runtime-target rules.
+The Rust host's live-control release and mixer ownership contract is documented
+in [docs/live-control-ownership.md](docs/live-control-ownership.md).
+
+For gaze tracking, head following takes the full target turn from reference neutral,
+bounded by the profile's head AU limits;
+camera-facing preference requires `lockHeadToCamera: true`. With geometry-backed focus, live eye/head strength
+changes move continuously toward the latest value in [0, 1], including when a
+slider reverses direction. See the [eye-contact contract](docs/gaze-tracking-contract.md)
+for geometry, timing, channel ownership, and authored motion behavior.
+
+## Camera and annotation runtime
+
+Polymer directly re-exports Embody's Three.js camera and annotation runtime.
+`DPthreeCameraController`, `DPthree3DMarkers`, `DPthreeHTMLMarkers`, and the
+`DPthree` convenience wrapper are the same constructors provided by
+`@lovelace_lol/embody/three`. Embody owns marker creation, surface projection,
+rendering, camera transitions, visibility timing, and teardown. Polymer does not
+maintain a second implementation or introduce an annotation agency.
+
+```js
+import { DPthree } from '@lovelace_lol/polymer';
+
+const annotations = new DPthree({ scene, camera, domElement: canvas });
+annotations.setModel(model);
+await annotations.loadCharacter(characterConfig);
+await annotations.focus('head');
+// Call annotations.update() from the host's existing render loop.
+// Call annotations.dispose() when its scene is destroyed.
+```
+
+Hosts own editor UI, persistence, scene attachment, and external input wiring.
+Use `createMarkerVisibilityLifecycle` for automatic reveal/hide and
+`createRuntimeAnnotationPreviewLifecycle` for transient editor previews rather
+than implementing host timers. TypeScript declarations are forwarded from
+Embody so runtime classes and their public signatures stay aligned. The package
+contract checks constructor identity against the pinned Embody preview.
+
+For a newly attached model, await the existing camera controller's
+`prepareModelForRender(model, { signal })` before reporting render readiness.
+Embody coordinates compilation and a full-scene preparation draw with its
+existing loop; Polymer forwards the method without another rendering scheduler.
+See [model render readiness](docs/character-host-readiness.md#model-render-readiness).
+
+Pure [unscored questionnaire content contracts](docs/questionnaire-content.md)
+cover authored choice/text validation, participant projection and editor metadata.
+They do not yet provide a Questionnaire runtime agency or participant UI.
 
 ## Agency API
 
@@ -50,7 +135,7 @@ schedulers.
 
 Polymer currently includes early Blink, Animation, Gaze, Eye/Head Tracking,
 TTS, LipSync, Prosodic Expression, and Gesture agencies, plus first slices for
-Conversation, Camera Context, and Transcription. These are implementation
+Conversation, Camera Context, User Perception, and Transcription. These are implementation
 milestones, not the limits of the architecture. Each agency should follow the
 same local GOAP/planner, scheduler, stream, transform, and effector pattern as
 the package grows.
@@ -58,6 +143,68 @@ the package grows.
 The text-only LipSync pronunciation fallback and its accuracy limits are
 documented in [`docs/lipsync-pronunciation-fallback.md`](docs/lipsync-pronunciation-fallback.md).
 
+The five supported live Prosodic settings, revision receipts, safe decision
+projection, and routing-disable lifecycle are documented in
+[`docs/prosodic-configuration-pilot.md`](docs/prosodic-configuration-pilot.md).
+This bounded pilot preserves the other eleven agencies and does not implement a
+global configuration controller or captured-session replay.
+
+Gesture, Gaze, and Camera Context also expose portable definitions and
+agency-local revisioned settings under Action, Cognition, and Perception
+namespaces. Their supported consumers, apply boundaries, and safe diagnostic
+projections are documented in
+[`docs/agency-configuration-families.md`](docs/agency-configuration-families.md).
+Public agency IDs and constructors remain unchanged.
+
+The opt-in [Gaze Lab POC](docs/gaze-attention-poc.md) retains static candidates,
+uses actual routed Conversation credit or explicitly synthetic fixture influence,
+and measures final-goal optical alignment through Animation. It is a bounded
+feedback demonstration, not general moving-peer arbitration or learning; normal
+mouse/webcam behavior remains unchanged.
+
+User Perception's camera, worker, model assets, compact fact contract, and
+privacy boundary are documented in
+[`docs/user-perception.md`](docs/user-perception.md).
+
+LipSync receives rig articulation from the resolved Embody preset/profile.
+After `initEmbodyCore()`, call `resolveVisemeProfile(runtime.getProfile())` once
+when binding the character and after each profile change. The synchronous result
+contains `visemeSlots` in exact runtime order (missing order is zero; ties keep
+source order), weighted/numeric binding targets, resolved jaw amounts and tongue
+AU targets. Use its array indices for manual `setViseme(index, value)` preview and
+configure LipSync with `{ visemeProfile: descriptor }`. This is a host profile
+projection boundary, not work to repeat every frame. A live descriptor change
+rebuilds the current clip at its current audio position. Explicitly configure this
+field after every runtime `setProfile`, even when the descriptor is unchanged:
+profile rebinding can clear animation actions. Polymer re-emits the active clip
+and seeks to the current audio position without restarting audio.
+
+For custom slots, Azure speech matches `providerIds.azure`; generated English
+text matches `phonemes` using CMU/ARPABET symbols with optional stress digits.
+External timelines can carry `provider` and `providerId`, or a `phoneme`.
+A timeline containing only canonical `visemeId` needs an explicit
+`providerIds.canonical` route in a custom profile. An unknown, ambiguous, or
+unbound route retains neutral timing rather than selecting a guessed slot.
+Azure zero reaches a declared zero route; otherwise it is neutral. Custom slots
+can exceed 15: their model indices never become AU or jaw control IDs.
+
+The descriptor overrides both `visemeJawAmounts` and `visemeTongueTargets` so
+articulation uses the same runtime slot order. Without a descriptor, the existing
+canonical 15-slot behavior and separately supplied tables remain supported.
+Keys-only profiles and the unchanged stock CC4 routing metadata also
+retain that behavior, including stock Azure refinement/diphthong rules. The
+stock metadata contains overlapping aliases, so replacing its routing metadata
+opts into explicit matching rather than silently changing legacy speech. Reordering
+all stock slots preserves canonical sound semantics through `canonicalSlotIndices`,
+which maps canonical sounds to their new runtime positions.
+
+Resolution describes authored bindings, not successful deformation: a referenced
+morph can still be missing from the loaded model. Polymer does not infer a VRM
+loader, a complete system recipe, or target correctness from a slot's name.
+Weighted targets are resolved by Embody, and manual and speech channels use that
+same binding. Polymer owns timing, grouping, and curve planning; the profile owns
+jaw apertures and tongue poses. With no profile jaw amounts, no jaw track is authored.
+
 Runtime-specific work belongs at the edge. The current animation path can target
 the existing web runtime, but Polymer core should remain able to support other
 runtime targets such as Babylon, Unity, Godot, robotics, or future animation
@@ -134,10 +281,45 @@ The host supplies the gesture library and may observe streams for diagnostics,
 but Gesture's own scheduler is responsible for replacement, cancellation, and
 completion cleanup before Animation owns the runtime side effect.
 
+### Animation snippet looping
+
+Animation snippets default to repeating when no loop preference is supplied.
+Authored `mixerLoopMode` (`repeat`, `pingpong`, or `once`) takes precedence over
+the snippet's `loop` boolean. A `scheduleSnippet` command's `options.loopMode`
+or `options.loop` overrides that authored preference for the scheduled play;
+an explicit options mode takes precedence over the options boolean.
+The compatibility service's `schedule` method accepts the same options.
+
+Animation uses that effective loop policy for the runtime, schedule snapshots,
+and compatibility UI state. Repeating clips stay scheduled until removed or
+stopped, including when a one-shot is switched to repeat before its original
+completion callback resolves. Explicit one-shots retain completion cleanup.
+
 ## Character host (Embody scene + model loading)
 
-Polymer re-exports Embody's character host so LoomLarge and other hosts can set
-up a character without depending on Embody directly.
+Polymer composes Embody's scene/model utilities with its animation host so
+LoomLarge and other hosts can set up a character without depending on Embody
+directly. Owned scenes await initial renderer preparation before the host
+resolves. The async default is `auto`: Embody tries native WebGPU and releases
+a failed initialization attempt before preparing WebGL. Later scene-preparation
+errors remain errors. Use `scene: { renderer: 'webgl' }` to
+force WebGL or `'webgpu'` to require native WebGPU without fallback. The synchronous scene
+factory stays WebGL-only; `createDefaultCharacterSceneAsync` exposes the
+scene-only Promise API. Three and its declarations use the coordinated r184
+contract.
+
+The new `createDefaultCharacterSceneRuntime` export and `host.rendering`
+forward Embody's renderer-settings controller. It owns switching and recovery;
+Polymer keeps the scene, camera, model, and animation engine intact and exposes
+current renderer/backend getters. This source integration awaits an Embody
+preview with the new controller API; the existing published pin is retained.
+See [renderer settings and replacement](docs/character-host-readiness.md#renderer-settings-and-replacement)
+for subscriptions, capture leases, and ownership.
+
+Pass `signal` to cancel host creation cooperatively, then call `host.dispose()`
+for the resolved host's lifetime. Borrowed external scenes remain caller-owned.
+See [readiness and cleanup semantics](docs/character-host-readiness.md), including
+which GPU/model stages are outside this readiness contract.
 
 Default path — pass a container element and a character URL:
 
@@ -210,19 +392,221 @@ if (supportsRustEmbodyPreset('cc4')) {
 
 The CLJS host owns the JavaScript API and render-loop bridge. Rust owns preset
 lookup, profile merge and intake, compiled bindings, transitions, and packed
-frame evaluation. Unsupported presets must stay on the compatibility host until
+frame evaluation. Rust selects active procedural channels. The host preserves the underlying
+renderer values while applying those packed writes, so releasing live controls
+reveals paused or unchanged mixer samples. Host mixers own clip playback.
+Unsupported presets must stay on the compatibility host until
 they are explicitly embedded; they are never treated as CC4 aliases.
 
-## Git Install Contract
+Authoring controls can read procedural state with `engine.getAU(id)`,
+`engine.getAUBalance(id)` (left/right balance in `-1..1`), and
+`engine.getContinuum(negativeId, positiveId)`. These read Rust's current values,
+including neutral values after `clear()` or `setProfile()`, so a remounted
+control can resume the current pose without maintaining a second state cache.
+
+### Semantic humanoid skeleton
+
+`getHumanoidSpecification()` exposes Embody's canonical VRM 1.0 catalog: all
+55 bone roles, the 15 required roles, and parent/optional-parent requirements.
+Call it after `initEmbodyCore()`, like the other synchronous profile queries.
+`resolveHumanoidCharacterization(profile)` resolves authored role aliases;
+`validateHumanoidCharacterization(model, profile)` additionally checks the
+actual model hierarchy, unique assignments, and supported transform constraints.
+
+`setHumanoidRoleBinding(profile, role, boneName)` returns a new profile that
+assigns an actual model bone; pass `null` to clear a role. Persist the returned
+characterization as a complete replacement, together with changed bone aliases,
+action/composite mappings, and continuum pairs, then reconfigure the runtime. Authored catalogs
+remain authoritative across preset upgrades. Clearing a role makes its semantic
+bone outputs dormant while preserving the rest of the profile.
+
+The CC4 preset supplies a complete role map and controls across torso, head,
+arms, hands/fingers, legs, and feet/toes. Bound UI controls use
+`engine.getBodyControls()` to read descriptors cached from the configured Rust
+profile/model, avoiding scene traversal and repeated profile parsing. The standalone
+`getBodyControls(profile, model)` query remains available for unbound authoring.
+`engine.resetBodyControls()` clears the configured catalog's action values and
+balances in one Rust call and applies one frame, preserving unrelated facial actions
+and morph-strength settings. Head, eye, and jaw controls
+share existing facial actuators; all controls use the existing AU/continuum
+host methods. Applications should show the full role inventory even when a
+model omits optional bones, and allow users to repair its assignments.
+
+Every configured Body action, including each direction of a signed control,
+can drive authored left/right/center morph mappings. Morph strength scales
+those outputs even when the action has no bone bindings. Persist the action's
+`auToMorphs` and `auMixDefaults`, and retain its mesh category: head, eye, and
+jaw controls may share facial actions with different target meshes. The package
+contract tests exercise all six sections through the actual Rust-backed host,
+including mesh selection, balance, zero strength, and mapping removal.
+An explicitly configured mesh list restricts these Body actions to that list;
+an empty list disables their morph outputs rather than selecting other meshes.
+After a temporary direct morph preview, call `engine.releaseMorph(key, meshes)`
+to let current AU/viseme/clip output resume. Setting a morph to zero is still an
+explicit override and intentionally continues to suppress those other sources.
+
+`setAUMorphTargets(profile, auId, side, targets)` edits one action side's
+morph targets without removing the same targets from other actions. Sides are
+`left`, `right`, or `center`; targets are names or numeric morph indices. The
+returned profile includes the complete edited AU row, with other sides preserved
+and explicit empty arrays retained across preset reloads. Hosts can persist just
+that row as an override and reconfigure the runtime.
+
+Head and eye semantic controls use the existing FACS AU IDs, mappings, balances,
+and morph-strength settings. CC4 neck controls seed the corresponding head tissue
+morphs and ratios while keeping separate neck bone actions and profile overrides.
+Neck morphs use the face mesh route; limb muscle morphs use their authored route.
+`auMixDefaults` scales morph deformation without reducing bone movement. Editors
+should expose these settings even when configured morph targets are missing, so
+users can repair the assignment or choose another model.
+
+VRM defines anatomical roles and hierarchy. Motion axes/ranges and muscle morphs
+remain authored rig data. Editing an unmapped import does not silently give it
+the CC4 preset. Polymer provides this compatibility API as a thin Rust adapter;
+it adds no second role catalog, pose evaluator, or character state cache.
+Use `engine.getAU(id)` and `engine.getAUBalance(id)` together when saving a live
+AU pose. The balance reader returns Rust's current control value in `[-1, 1]`
+(`-1` left, `0` both sides, `1` right), or `0` for an unset or cleared AU.
+Save that value in the snippet's `snippetBalanceMap` to preserve sided playback
+through AnimationService. These readers report live control state, not the
+sampled pose of a playing mixer clip.
+
+### Stable character reference poses
+
+The first `onReady` captures the model's loaded transforms and morph weights,
+before Polymer applies the profile or starts playback. `setProfile`, `bindModel`,
+and subsequent `onReady` calls for that model reuse the capture. Animation
+intensity is measured from that same reference. Live inherited animation starts
+still sample the rendered pose when a clip is materialized.
+
+Call `onReady` while a newly loaded model is intentionally in its reference pose.
+This does not infer a skin bind pose or use animation frame zero. If the same
+model survives engine recreation, retain an explicit capture with the model:
 
-Polymer Git-SHA consumers should import checked-in JavaScript artifacts from
-`dist`. They should not need Java, Shadow CLJS, or a local Polymer build during
-application install.
+```js
+import { captureModelReferencePose } from '@lovelace_lol/polymer';
+const referencePose = captureModelReferencePose(model); // before playback/edits
+engine.onReady({ model, referencePose });
+// Pass referencePose again when creating a replacement engine for this model.
+```
+
+Intentional skeleton additions must append new children without renaming,
+removing, or reordering existing nodes. After insertion, call
+`engine.extendReferencePose()` before applying new profile mappings. This returns
+a new immutable capture that includes the added nodes and preserves every old
+reference transform; retain it if the model will outlive its engine. Other
+hierarchy edits fail explicitly before the active profile or playback is cleared.
+Ordinary profile, transform, material, and morph-target edits need no recapture.
+
+Baked-animation pause and resume also publish the current runtime playhead, so
+the paused timeline remains at the displayed pose instead of reverting to an old
+time. These are discrete state updates; playback progress stays in the runtime.
+
+### Optional baked animation assets
+
+Use `engine.loadAnimationClips(initialClips)` during initialization. After the
+model is bound, `engine.registerAnimationClips([clip])` adds a downloaded clip
+without starting it, resetting the mixer, or interrupting native, snippet, or
+hair playback. Re-registering the same clip object does no serialization work.
+A new source under an existing name replaces the next playback; the current
+action continues until playback is explicitly requested. Registered sources
+survive model rebinding, and `removeAnimationClip(name)` also removes them from
+the sources retained for rebinding. Treat registered source objects as immutable.
+
+The Animation agency's existing `loadBakedClips` command accepts lightweight
+`{name, duration, channels}` catalog entries before optional tracks are loaded.
+Hosts can expose that catalog immediately, fetch and register a selected asset,
+then request `playBaked` through Animation. Registration is asset setup; it does
+not introduce an additional scheduler or playback owner.
+
+## Package Distribution Contract
+
+Only source and the hand-authored `types/index.d.ts` declarations are committed.
+`pnpm build` recreates `dist`, builds the npm and worker targets once, and copies
+the declarations into that staging directory. `pnpm verify` checks the
+source-only rule, validates the runtime exports and packed file list, and runs
+the CLJS and worker tests.
 
 The package intentionally has no `prepare`, `install`, or `postinstall` build
-lifecycle. Polymer CI runs the CLJS build, verifies that `dist` exposes the
-browser ESM API that Git-SHA consumers import, and `prepublishOnly` repeats the
-build/test/API check before an npm publish.
+lifecycle. Consumers install an already-built npm release or a pkg.pr.new preview
+for a specific commit and therefore do not need Java, Shadow CLJS, or a local
+Polymer build. For work testing an upstream PR, use the full URL reported by CI:
+
+```text
+https://pkg.pr.new/meekmachine/Polymer/@lovelace_lol/polymer@<40-character-sha>
+```
+
+On pushes to `main`, CI prepares a stable npm version and validates the **committed**
+Embody dependency before the single build. The source manifest must already pin
+an exact stable Embody version, with a synchronized lockfile. CI reads public npm
+metadata anonymously and checks that the selected release records a commit in
+Embody's `main` history. It rejects preview URLs anywhere in the production
+lockfile. Publication never replaces a preview with whatever npm calls `latest`: adopting a release is
+an ordinary dependency PR, so the dependency tested by PR CI is the one shipped.
+The existing preview pin remains until a fresh Embody npm release is available;
+stable publication is intentionally blocked during that bootstrap.
+
+After all checks pass, CI packs the verified output and uploads it to a separate
+publish job using the main-only `npm` environment's `NPM_KEY`. That job publishes
+the same tarball with public access and provenance disabled, without building
+again. The tarball must also declare public access. GitHub source access remains
+separate from distribution of the public compiled npm package.
+
+Package metadata and dependency installation use the public registry without a
+read token. Registry lookups also stay anonymous when a publishing credential is
+present in the environment, and reject redirects to another registry endpoint.
+Only the publish step receives `NPM_KEY`; PR installs and checks receive no npm
+credentials. Same-repository PRs can publish previews; fork PRs can run checks
+without receiving publication or coordination write credentials.
+
+The package allowlist remains `dist` and `README.md`, alongside npm's package
+metadata. The existing CI package checks require staged runtime files and reject
+repository source/test inputs. Build output, source maps, minification and
+obfuscation are unchanged by this release setup.
+
+Successful stable and same-repository PR preview publication dispatch
+`upstream-package-published` to LoomLarge. The write credential
+`CROSS_REPO_CI_TOKEN` belongs in the main-only `release-coordination` environment;
+it must read Embody for release ancestry and dispatch to LoomLarge. PR jobs only
+upload notification JSON and never receive this credential. The separate
+`workflow_run` consumer checks out **main**, validates the completed build job,
+the JSON package identity, and the current open same-repository PR head, then
+sends the event. It never executes a PR script or downloaded artifact. The build
+job must succeed even when the independent production-readiness job rejects a
+preview dependency. During migration the consumer accepts both the former
+`CI and package preview` name and `CI and package publishing`, while requiring
+the exact CI workflow path. Missing credentials or failed dispatch fail visibly.
+
+Stable events include the exact version and source SHA; preview events include
+the PR number and actual published URL, expanded to its full source SHA and
+checked before dispatch. LoomLarge's coordinator owns downstream manifest/lockfile
+PR updates; release-system companion PR links alone do not create package-stack
+dependencies. The coordinator and trusted notification consumer must be on their
+respective main branches before activation. Explicit preview requests without a
+PR publish previews but do not imply a downstream stack to update.
+
+Release versions and source commits are recorded in npm; rerunning a published
+commit retains its version and exact Embody dependency. If a concurrent publisher
+claims that source/version with different runtime dependencies, publication fails
+instead of sending a success notification for a package the job did not verify.
+Main release runs are serialized. A manual run on `main` with no alternate ref can retry publication
+and notification; PRs, repository-dispatch preview requests, and alternate refs
+cannot publish stable npm packages.
+
+The first restored release reads Polymer `0.0.7`'s source from the verified
+canonical `v0.0.7` tag because that legacy npm version has no `gitHead` metadata.
+The tag must still point to `73feb34f8afa5a36962e86bc0f3e91f9d91205ef`, and the
+new release must contain that commit. Subsequent releases use npm's recorded
+`gitHead`; missing or conflicting source information stops publication.
+
+The separate `Production npm dependency` job rejects preview pins and verifies
+the committed Embody registry version before merge. A trusted main-only job checks
+Embody main ancestry before publication. PR build jobs can still publish their
+immutable previews independently. Bootstrap requires publishing and coordinator
+credentials, an Embody main release, adoption of that actual version in Polymer's
+manifest and lockfile, Polymer's main release, then adoption in LoomLarge.
+Upstream feature stacks keep using immutable previews before this release sequence. Production hosts adopt
+actual released versions in dependency PRs whose CI checks the selected packages.
 
 ## Worker Protocol Artifact
 
@@ -238,3 +622,41 @@ not use this artifact yet, and this PR does not decide which agencies should be
 placed in workers. Selective placement, profiling, transferables, and worker
 pool decisions remain tracked in
 [issue #62](https://github.com/meekmachine/Polymer/issues/62).
+
+For generator modules bound to a shared character, see
+[Conversation sessions and interruption](docs/conversation-interruption.md).
+
+Presentation and Questionnaire share pure lifecycle, viewed/active context,
+request correlation and opaque checkpoint helpers. See
+[shared interaction contracts](docs/interaction-contracts.md) for their module
+composition interface, account/mount identity and scoped cleanup rules. These
+contracts do not enable a feature runtime or persist conversation/run data.
+
+### Semantic pose capture and generated animations
+
+The Rust host exposes `getSemanticPoseCatalog()`, `captureSemanticPose()`,
+`validateSemanticPose(pose)` and `applySemanticPose(pose)`. The catalog follows
+the configured profile and actual model, including independent direction support,
+VRM role names, owned bone/morph names and authored default tissue strengths.
+Captures preserve both opposing directions, bilateral balance and morph strength;
+they represent manual semantic state, not inverse inference of a baked pose.
+Validation is atomic and lives in Embody. Known missing outputs may be saved for
+partial rigs; generation should offer only supported catalog directions.
+
+Normal `AnimationService.schedule` snippets may include `semanticAnimation`:
+`{version:1,durationSeconds,tracks:[{controlId,direction,balance?,morphStrength?,
+keyframes:[{time,intensity}]}]}`. Existing `curves` are non-Body facial AUs.
+Embody compiles both sets together into bone/morph tracks, preserving each tissue
+strength without changing live controls. Service save, pause, resume and cleanup
+use the existing snippet lifecycle. `validateSemanticAnimation(animation, options)`
+compiles without retaining clips. `semanticAnimationToClip(name, animation,
+options)` builds an ordinary playback handle; `options.faceCurves` adds facial
+curves for direct callers. IDs and direction labels come from the catalog, amounts
+are normalized `0..1`, balance is character-relative `-1` left / `+1` right, and
+times are seconds. Unknown controls, unsupported directions and invalid tracks fail.
+
+Manual `setAU` / `transitionAU` selects one configured continuum direction:
+nonzero input clears its opposite, negative input selects the opposite, and
+zero releases only the named action. `setContinuum` controls both directions
+explicitly. Body and individual AU/morph previews therefore share the same
+live state; separate axes remain independent.