Document the unified animation playback model in the README

[meekmachine]

Summary

Document the unified animation playback model in the README.

The current README lists transition APIs, baked animation playback, snippet/curve playback, and clip helpers, but it does not explain how those pieces fit together or why the system is valuable.

Problem

One of Loom3's strongest features is that baked animations and prescribed/generated animations now live in the same playback world and can be remixed in realtime.

The README does not explain that clearly.

In particular, it does not explain:

• how transition playback differs from mixer-backed clip playback
• that loaded baked clips and generated/snippet clips share the same mixer-backed controller surface
• why those animation sources can be layered and remixed together
• how AU / viseme / direct runtime control coexists with clip playback
• what makes the system efficient enough for realtime use
• what makes combined playback reliable and predictable instead of fighting itself

That missing explanation makes the library look like a bag of features instead of a coherent animation system.

Scope

• Add a dedicated README section for the animation architecture
• Explain, at a high level, the roles of:
  • transition playback
  • baked clip playback
  • snippet / curve-to-clip playback
  • shared playback handles and state APIs
  • crossfading / weight / playback rate / loop behavior
• Explain that baked animations and generated/snippet clips are remixable because they use the same mixer-backed playback model
• Explain how direct control APIs fit alongside mixer-backed playback
• Explain the efficiency story in concrete terms, not marketing language
• Explain the reliability story in concrete terms, not marketing language
• Include at least one example that intentionally combines:
  • a baked clip
  • a generated/snippet clip or clip helper
  • live AU or viseme control

Acceptance Criteria

• README includes a section that explains the animation system as a system
• README explains how baked and generated/snippet playback relate to each other
• README explains why those animation types are remixable
• README explains why the playback model is efficient for realtime character motion
• README explains what makes layered playback reliable and predictable
• README includes at least one example of intentional combined playback

Related

• #31

[meekmachine]

Added the working README rewrite discussion here: #124

For this issue, the relevant draft sections are Runtime Model and Animation System. The implementation PR should use that discussion as the planning source before changing the README.

[meekmachine]

Course correction after latest app/package review - 2026-05-25

I reviewed the current remote state of both repos before starting the README PR. The README plan needs to be updated to match the app/package as they exist now, not the May 3 assumptions.

Remote state reviewed

Recent LoomLarge / CharacterLoom app changes that affect README examples:

• LoomLarge #598: consolidated profile-backed Emotes/Gestures work, URL-addressable floating drawer panels, annotations tab, service worker/profile persistence changes, and broader drawer surface changes.
• LoomLarge #600: fixed main Eye & Head tracking activation, making the Eye & Head tab a better live example for prescribed/generated gaze/head motion.
• LoomLarge #607: added guarded geometry-first preview during character loading.
• LoomLarge #609: fixed selected-character loading handoff with the preloader.
• LoomLarge #610: reduced eager picker video preload work.
• LoomLarge #611: lazy-loaded the character upload wizard.
• LoomLarge #612: lazy-loaded the remote control service.
• LoomLarge #616: optimized built-in character thumbnail capture/fallbacks and moved toward checked-in transparent WebP poster thumbnails.
• LoomLarge #547: integrated Loom3 profile-defined viseme runtime into the app.

Recent Loom3 package changes that affect README accuracy:

• Loom3 #120: streamed clip lifecycle events from the mixer update loop.
• Loom3 #123: runtime morph target authoring APIs: addMorphTarget, addMorphTargets, ensureMorphInfluence, and refreshMorphTargets.
• Loom3 #125: README links moved from loomlarge.web.app to www.characterloom.com.
• Loom3 #131: profile-defined viseme mapping system, visemeSlots, visemeBindings, provider adaptation helpers, and setVisemeById / transitionVisemeById APIs.
• Loom3 #133: restored baked additive safety and separated baked animation actions from regular clip/snippet actions into separate mixer passes.
• Loom3 #135: aligned live and baked viseme playback with profile-defined binding targets and jaw aggregation.
• Loom3 #140: moved old character-config responsibilities into profile/preset/runtime-oriented APIs, with old character config names kept as deprecated compatibility aliases.
• Loom3 #145: moved annotation camera-angle/laterality helpers into Loom3.
• Loom3 #132: fixed viseme candidate classification so AU side suffixes are not misclassified as viseme candidates.

Current README problems confirmed on origin/main

• The README still says “LoomLarge” in several live-demo prose locations while the public links now point to https://www.characterloom.com.
• The demo prose still contains internal authoring commentary, including phrasing like “the README should...” and “pretending it can deep-link...”. That should be removed from product docs.
• The README still links tab=action-units, but the current app drawer has tab id aus and label Emotes. action-units is no longer the right stable deep link. Use tab=aus for the current Emotes/AU surface, or tab=emotes if we intentionally prefer label-based URLs.
• The live tab surface is broader than the current README link table. Current useful public tabs include animation, poses, gestures, speech, blink, aus / Emotes, visemes, tracking / Eye & Head, hair, meshes, bones, mappings, annotations, and properties.
• The animation docs should no longer say or imply that baked clips and generated snippets literally share one mixer. After [codex] Restore baked additive safety #133, they share a playback model/API surface, but baked actions and regular/generated clip actions are intentionally separated into mixer passes so procedural clips can override baked additive face tracks reliably.
• The viseme section is more stale than originally scoped. It should not be framed as a fixed 15-row table only. Current runtime is profile-defined via slots/bindings and supports id-based APIs plus weighted multi-target bindings. Provider mapping research in Research source-of-truth viseme models for CC4, Azure, and ElevenLabs #86 still matters, but the README can already describe the profile-defined runtime accurately.
• The app is moving toward profile-backed Emotes/Gestures/Poses and saved AI expression snippets. The README should treat snippets/generated clips as durable profile/runtime concepts, not only throwaway examples.
• Screenshots should remain illustrative. Recent thumbnail/loading/performance work means the README should prefer live CharacterLoom links for current behavior and avoid making screenshot state the source of truth.

Revised documentation direction

The README should use this product model:

1. CharacterLoom is the public live inspection/demo app linked from the README.
2. LoomLarge is the app/repo context, but public README links should say CharacterLoom unless we are explicitly discussing the internal app repository.
3. Every major README section should include a small “See it live” line pointing to the specific CharacterLoom tab that demonstrates or inspects that concept.
4. The animation claim should be “shared playback model and normalized control surface,” not “one mixer for everything.”
5. The reliability story should explicitly mention precedence: baked playback is evaluated separately from regular/generated snippet playback so additive baked face tracks do not corrupt procedural clip results.
6. The efficiency story should distinguish short transitions from mixer-backed authored/generated clips. Transitions are right for small direct UI changes; mixer-backed clips are right for high-frequency prescribed motion, snippets, speech timing, and reusable animation data.
7. The viseme section should describe profile-defined slots/bindings and id-based runtime APIs now, while leaving provider-specific CC4/Azure/ElevenLabs mapping recommendations tied to Research source-of-truth viseme models for CC4, Azure, and ElevenLabs #86.
8. Preset/profile documentation should follow the profile-first model from [codex] Remove character module in favor of profiles #140 and treat old CharacterConfig / auPresetType paths as compatibility aliases only.
9. Runtime morph authoring and annotation camera helpers should be included in the API/reference pass because they are now public package capabilities.

Current CharacterLoom link map for README examples

Use these as the current live-example links:

• Animation: baked clips, generated clips, playback handles, speed/weight/looping, clip events.
• Poses: profile-backed pose concepts and reusable character state.
• Gestures: profile-backed gesture/snippet concepts.
• Speech: speech/TTS-driven timing behavior.
• Blink: simple direct transition behavior.
• Emotes: AU/emote expression controls. Prefer tab=aus as the stable id until the app exposes a dedicated emotes id.
• Visemes: direct viseme slot/mouth-shape inspection.
• Eye & Head: gaze/head tracking and prescribed motion examples.
• Hair: hair physics and hair morph controls.
• Meshes: mesh discovery, morph targets, visibility, material state.
• Bones: resolved bones and skeletal inspection.
• Mappings: AU/morph/bone/viseme routing.
• Annotations: annotation/camera/marker context.
• Properties: profile, preset, and character configuration state.

Optional later: if the README wants direct floating-panel examples, the app now supports URL-addressable floating drawer panels via panel / float parameters. That should be used sparingly after verifying the exact panel ids we want to publish.

Revised README outline

# Loom3
## What Loom3 Is
## Runtime Model
## Live Examples In CharacterLoom
## Reading Paths

## 1. Installation & Setup
## 2. Core Concepts
### Profiles and presets
### Action Units, emotes, morphs, bones, visemes, clips
### Runtime update loop

## 3. Presets, Profiles, And Validation
## 4. Inspecting A Character
## 5. Runtime Facial And Emote Control
### Action Units / Emotes
### Mix weights
### Composite rotations
### Continuum pairs
### Direct morph control
### Runtime morph target authoring

## 6. Visemes And Speech-Timed Lip Sync
### Profile-defined viseme slots and bindings
### Index APIs and id-based APIs
### Jaw coupling and overlapping visemes
### Provider mapping notes, linked to #86

## 7. Animation System
### Two control paths: transitions and mixer-backed playback
### Baked GLB/GLTF clips
### Generated AU/morph/viseme/bone clips
### Snippets, gestures, poses, and profile-backed reusable animation data
### Handles, events, weights, speed, loops, reverse, crossfades
### Baked mixer pass vs generated/procedural clip mixer pass
### Why this is efficient
### Why this is reliable

## 8. Hair Physics
## 9. Skeletal-Only Characters
## 10. Regions, Annotations, And Camera Helpers
## 11. API Reference
## Resources
## License

Revised acceptance criteria for this README PR

• Replace “Demo Site Links” with a product-facing CharacterLoom live-example section.
• Remove internal README-authoring commentary from the README prose.
• Replace stale tab=action-units links with the current Emotes/AU tab link, preferably tab=aus.
• Add links to the current poses, gestures, tracking, and annotations tabs where they support the explanation.
• Add a top-level runtime model that explains direct controls, transitions, mixer-backed playback, and profile-backed data.
• Rewrite the animation section around shared playback semantics, while explicitly documenting that baked and generated/procedural clips are evaluated through separate mixer passes after [codex] Restore baked additive safety #133.
• Explain how baked animations, generated snippets, emotes/AUs, visemes, gaze/head tracking, and hair can be composed without fighting over state.
• Update viseme docs to describe profile-defined slots/bindings and id-based APIs, while keeping provider-specific mapping decisions linked to Research source-of-truth viseme models for CC4, Azure, and ElevenLabs #86.
• Update profile/preset docs to reflect the profile-first model from [codex] Remove character module in favor of profiles #140.
• Include runtime morph target authoring APIs in the direct morph/API reference sections.
• Include annotation camera-angle helper exports in the regions/annotations/API reference sections.
• Keep screenshot replacement out of this PR unless a screenshot is actively misleading; asset replacement remains separate from this issue.

[meekmachine]

How to combine this course correction with draft PR #99

I reviewed PR #99 against the May 25 course-correction notes above.

PR #99 current state

• Status: open draft PR.
• Branch: codex/rewrite-readme.
• Base: main.
• Mergeability: currently conflicting.
• Files changed:
  • README.md
  • README_COMPARABLES.md
  • README_FINDINGS.md
  • README_OUTLINE.md
• The PR is useful because it already contains a serious README rewrite attempt plus research/outline notes.
• The PR is not safe to merge directly because it predates several important app/package changes and now conflicts with current main.

What PR #99 gets right and should be preserved

• It correctly identifies that Loom3 should be described as an expressive Three.js character animation system, not just a morph/bone mapping helper.
• It elevates animation architecture earlier in the README instead of treating baked animation as a late appendix.
• It defines curves, clips, and snippets more clearly than the current README.
• It tries to explain why mixer-backed playback matters for realtime characters.
• It includes a combined example using baked animation, generated clip playback, and live AU control.
• README_FINDINGS.md, README_OUTLINE.md, and README_COMPARABLES.md contain useful planning material that should be mined before rewriting from scratch.

What PR #99 must be corrected before it can be combined

• It still links to https://loomlarge.web.app; current public README links should use https://www.characterloom.com.
• It still says LoomLarge Companion; public docs should call the live app CharacterLoom unless explicitly discussing the internal app/repo.
• It still uses stale tab=action-units links. Current app tab id is aus, with visible label Emotes.
• It does not include current drawer tabs added since then: poses, gestures, annotations, and the current tracking Eye & Head tab link.
• It describes imported and generated animation as living in the same AnimationMixer world. After #133, the accurate claim is shared playback model/control surface, with baked actions and regular/generated clip actions separated into mixer passes for reliable precedence.
• It frames visemes around the older fixed low-level table and mentions a future jaw overhaul. Since #131 and #135, the README now needs to describe profile-defined viseme slots/bindings, weighted binding targets, id-based APIs, and strongest-active jaw aggregation.
• It still documents old CharacterConfig / extendCharacterConfigWithPreset flows too prominently. Since #140, those should be compatibility/deprecated paths behind the profile-first model.
• It does not yet include runtime morph authoring from #123 as a first-class direct morph/API reference item.
• It does not yet include annotation camera-angle helper exports from #145 in the regions/annotations/API reference story.

Recommended integration strategy

Do not merge PR #99 as-is. Use it as the source branch/material for the README PR, but rebuild the final diff against current origin/main.

Recommended path:

1. Create a fresh branch from current origin/main, for example codex/readme-runtime-model-characterloom.
2. Pull useful prose and structure from PR [codex] rewrite package README #99 manually instead of rebasing the whole conflicting branch.
3. Keep the best PR [codex] rewrite package README #99 ideas:
   • stronger opening around expressive character animation
   • curve/clip/snippet definitions
   • animation-system-first framing
   • combined playback example
   • comparable-systems/research insights where they improve wording
4. Replace all stale demo/app language with the CharacterLoom link map from the May 25 course-correction comment.
5. Rewrite the animation section around the corrected [codex] Restore baked additive safety #133 architecture:
   • transitions for short interpolated direct changes
   • baked clips loaded/partitioned/evaluated through the baked playback pass
   • generated/procedural clips evaluated through the regular clip pass after baked playback
   • shared handle/state/options model where the public API intentionally feels unified
6. Rewrite the viseme section around the current profile-defined runtime from Add profile-defined viseme mapping system #131/[codex] Align live viseme runtime with bindings #135, while keeping provider-specific final recommendations linked to Research source-of-truth viseme models for CC4, Azure, and ElevenLabs #86.
7. Decide what to do with PR [codex] rewrite package README #99’s planning files:
   • Either keep none of README_COMPARABLES.md, README_FINDINGS.md, README_OUTLINE.md in the final package PR and move the useful material into issue/discussion comments.
   • Or keep a single docs/README_REWRITE_NOTES.md if we want durable internal rationale. My recommendation is not to add three root-level planning docs to the package repo unless maintainers explicitly want them long-term.
8. After the new PR is opened, close PR [codex] rewrite package README #99 as superseded by the new current-main rewrite PR, or force-update PR [codex] rewrite package README #99’s branch only if preserving the PR number is more important than keeping the branch history clean.

Preferred decision

Use PR #99 as research and drafting material, but open a new clean PR from current main.

Reason: PR #99 has too many stale assumptions now. Rebasing it risks spending time resolving conflicts in old text that we already know needs major edits. A clean PR can still credit/link PR #99 and copy forward the useful parts, while avoiding a noisy/confusing diff.

If we must preserve PR #99

If preserving PR #99 is preferred, the safe version is:

1. Create a backup ref of the current PR branch.
2. Reset codex/rewrite-readme to current origin/main.
3. Re-apply only selected README changes from PR [codex] rewrite package README #99.
4. Update the PR body to say it has been rebuilt after the May 25 app/package review.

That keeps the PR number but effectively replaces the branch content. It is workable, but less transparent than opening a new PR and closing #99 as superseded.

[meekmachine]

Second course-correction pass after May 27/28 app and package changes

I reviewed the latest remote state again after the May 25 course-correction comment. Several new changes should alter how the README presents Loom3.

Newly reviewed changes

LoomLarge / CharacterLoom changes:

• LoomLarge #606: broad staging pass for loading, drawer code-splitting, hidden UI timers, profile-backed animation cleanup, model-aware mapping correction, and mesh morph authoring staging.
• LoomLarge #620: visible emoji-to-emote mapping controls in the Emotes tab.
• LoomLarge #621: camera timer fallback limited to unmanaged/no-renderer controllers.
• LoomLarge #625: shared RAF task scheduler for marker/camera UI visibility work.
• LoomLarge #627: Effect profile store ownership fixes; profile updates preserve app-owned fields and queued writes.
• LoomLarge #629: restored SliderDrawer sublevel tab tooltips.
• LoomLarge #631: fixed character loading and reduced load-frame churn with compositor loader, direct GLTF load path, delayed markers, bounded shader/texture warmup, and deferred workbench UI.
• LoomLarge #641: linked Polyester runtime preview support.
• LoomLarge #644: switches the LoomLarge runtime dependency to Polyester behind the existing Latticework import surface.

Loom3 package changes:

• Loom3 #142: supports inherit: true first keyframes, captures current morph/AU/viseme/bone state at playback time, rebuilds inherited dynamic clips at play/replay time, and renames the mixed playback owner from BakedAnimationController to AnimationController while keeping deprecated aliases.
• Loom3 #160: hardens runtime morph authoring with batch preflight, relative/absolute mode consistency checks, and cache refresh after partial failure.

Updated interpretation

The README should move one level higher in how it explains the system.

The package is no longer best presented as “a baked animation system plus procedural clips.” The clearer story is:

Loom3 is a profile-driven character-control and animation layer for Three.js. It maps semantic controls onto morphs, bones, viseme bindings, generated morph targets, and mixer-playable animation. CharacterLoom demonstrates those capabilities through product concepts such as Emotes, Poses, Gestures, Visemes, Eye & Head tracking, Hair, Mappings, and Annotations.

This matters because the app keeps moving toward product-facing controls while the package keeps moving toward reusable runtime primitives. The README should bridge those layers without confusing them.

Presentation changes from the latest review

1. Use product concepts first, API vocabulary second

In CharacterLoom, the user-facing expression surface is now Emotes, with visible emoji mapping controls. In Loom3, the low-level API still uses FACS-style Action Units.

README wording should reflect both:

• Product-facing: Emotes, Poses, Gestures, Visemes, Eye & Head, Hair.
• Package-facing: AUs, profiles, bindings, curves, snippets, mixer clips, morph targets, bones.

Recommended section title:

## Runtime Facial And Emote Control

Then explain:

• Emotes are the authoring/product layer.
• AUs are the stable semantic control vocabulary under that layer.
• Profiles map those controls onto a particular rig.

2. Prefer tab=emotes in product docs, mention aus only if needed

Current app code uses tab id aus with label Emotes, and URL resolution accepts both ids and slugified labels. The latest smoke in #620 used ?tab=emotes successfully.

For README links, prefer the product-facing URL:

• Emotes

If we need a more implementation-stable internal link, tab=aus still resolves. But the README should not publish tab=action-units anymore.

3. Rename the animation section away from “Baked Animations”

After #142, the code uses AnimationController as the owning name, with BakedAnimationController kept only as a deprecated alias. The README should stop centering the section name on “Baked Animations.”

Recommended section title:

## Animation System: Clips, Snippets, Poses, And Gestures

This section should still explain baked GLB/GLTF clips, but as one input source among several.

4. Explain inherited starts as a core reason snippets feel reliable

inherit: true is important enough to explain in the main animation narrative, not only as an API footnote.

Recommended explanation:

Snippets can start from the character's current state instead of resetting to an authored neutral value. When the first keyframe has inherit: true, Loom3 samples the live AU, morph, viseme, bone rotation, or bone translation value at playback time and uses that as the first mixer key. That lets reusable gestures, eye/head motion, emotes, and speech-adjacent snippets layer onto whatever the character is already doing without a visible snap.

This is a better reliability story than the previous wording because it explains a real mechanism.

5. Keep the mixer explanation precise

The current accurate wording is:

• Loom3 has a unified playback/control surface through AnimationController.
• Baked clip playback and generated/procedural clip playback are both mixer-backed.
• Baked and regular/generated clips are intentionally evaluated through separate mixer passes so procedural snippets can override baked additive face tracks reliably.
• That separation is an implementation reliability feature, not a contradiction of the shared playback model.

Avoid:

• “everything lives in the same mixer”
• “same AnimationMixer world”
• “baked and procedural are the same internally”

Use:

• “shared playback model”
• “mixer-backed playback paths”
• “separate mixer passes for predictable precedence”
• “one controller surface for clips, snippets, handles, events, weights, rates, and loops”

6. Treat CharacterLoom loading/performance behavior as app context, not package architecture

The latest LoomLarge changes around compositor loaders, deferred drawer chunks, thumbnail capture, GLTF loading, marker scheduling, and Polyester runtime switching are important for the demo app, but most of that should not be explained in the Loom3 README.

README implication:

• Keep CharacterLoom links as live examples and inspection surfaces.
• Do not describe CharacterLoom’s loader, runtime dependency pinning, Polyester/Latticework compatibility layer, or preview infrastructure as if it were Loom3 package behavior.
• Say that CharacterLoom is the live companion app demonstrating Loom3-style profile/runtime concepts.
• Keep the Loom3 package boundary clean.

7. Update the profile story again

#627 reinforces that profile state is the durable product boundary. #140 already moved Loom3 toward profile-first APIs.

README implication:

• Present profiles as the durable semantic contract for a character.
• Present presets as reusable base profiles.
• Present emotes, gestures, poses, viseme bindings, morph authoring, and annotations as profile-adjacent concepts, even when some persistence lives in CharacterLoom.
• Keep Firestore/backend details out of the Loom3 README unless explaining CharacterLoom specifically.

8. Put model validation before advanced authoring

#606 added model-aware mapping correction before engine creation in LoomLarge. That reinforces the README ordering:

1. Load/inspect model.
2. Validate preset/profile fit.
3. Apply corrections or profile overrides.
4. Create runtime controller and play/author animation.

The quickstart can remain short, but the main docs should recommend validation before serious authoring.

9. Reframe runtime morph authoring as an authoring primitive, not a normal first-use control

#160 makes runtime morph authoring safer, but it is still an advanced authoring capability.

README implication:

• Keep direct setMorph() / transitionMorph() in the runtime control section.
• Put addMorphTarget(), addMorphTargets(), ensureMorphInfluence(), and refreshMorphTargets() under “Runtime Morph Authoring” or “Advanced Authoring.”
• Mention batch preflight and relative/absolute mode consistency at a high level.
• Do not make morph authoring part of the first quickstart path.

Revised top-level README story

A better first-page structure now looks like this:

# Loom3

## What Loom3 Is
Loom3 is a profile-driven character-control and animation layer for Three.js. It lets applications control expressive characters through semantic concepts such as Action Units, visemes, morph targets, bones, clips, snippets, poses, gestures, and runtime profiles instead of one-off rig plumbing.

## Why It Matters
A believable realtime character needs several motion sources to cooperate: baked body motion, live expression control, speech timing, gaze/head motion, hair response, generated snippets, and authoring-time morph or mapping edits. Loom3 gives those systems a shared profile/runtime contract.

## See It Live In CharacterLoom
Link directly to product concepts: Emotes, Animation, Poses, Gestures, Visemes, Speech, Eye & Head, Hair, Mappings, Meshes, Bones, Annotations, Properties.

## How To Read This README
Split paths by first successful character, retargeting/profile work, animation/snippet authoring, viseme/lip-sync work, and annotation/camera tooling.

Revised section outline

## 1. Installation & Setup
## 2. Core Concepts
### Profiles, presets, and mappings
### Emotes and Action Units
### Morphs, bones, visemes, and clips
### Runtime update ownership

## 3. Inspect And Validate A Character
### Meshes, morphs, bones, animations
### Preset/profile fit
### Suggested corrections

## 4. Profiles, Presets, And Runtime Configuration
### Profile-first model
### Preset lookup and extension
### Compatibility aliases
### Profile hot-swap / `setProfile()`

## 5. Runtime Facial And Emote Control
### Action Units under emotes
### Mix weights
### Composite rotations
### Continuums
### Direct morph control

## 6. Visemes And Speech-Timed Lip Sync
### Profile-defined viseme slots and bindings
### Index APIs and id-based APIs
### Jaw coupling and overlapping visemes
### Provider mapping notes linked to #86

## 7. Animation System: Clips, Snippets, Poses, And Gestures
### Transitions vs mixer-backed playback
### `AnimationController`
### Baked clips
### Generated clips and snippets
### `inherit: true` starts
### Handles, events, weights, rates, loops
### Separate mixer passes and predictable precedence

## 8. Runtime Morph Authoring
### Generated/sidecar morph targets
### Batch preflight
### Relative vs absolute target mode consistency
### Cache refresh and active-state reapplication

## 9. Hair Physics
## 10. Skeletal-Only Characters
## 11. Regions, Annotations, And Camera Helpers
## 12. API Reference

Updated live link map

Use product-facing links where possible:

• Animation
• Poses
• Gestures
• Speech
• Blink
• Emotes
• Visemes
• Eye & Head
• Hair
• Meshes
• Bones
• Mappings
• Annotations
• Properties

New acceptance criteria for the README rewrite

Add these to the prior list:

• Use CharacterLoom, not LoomLarge, for public live demo references.
• Replace Action Units tab live links with Emotes links, preferably tab=emotes.
• Rename/reframe Baked Animations as a broader animation-system section.
• Use AnimationController terminology, with BakedAnimationController only as deprecated/internal compatibility context if mentioned at all.
• Explain inherit: true as the mechanism that lets snippets start from current character state without snapping.
• Explain mixer-backed playback as separate, predictable mixer passes under one controller/control surface.
• Keep Polyester/Latticework runtime-switch details out of the Loom3 README except as app-internal context if needed elsewhere.
• Present runtime morph authoring as advanced authoring, including high-level batch/mode safety constraints from Harden runtime morph authoring #160.
• Present profiles as the durable contract that product-facing emotes/poses/gestures/visemes/mappings build on.

[meekmachine]

Full triage — COMBINE into docs epic #31

README/docs accuracy absorbed by #31 (PR #99 may supersede on merge).

Plan: https://github.com/meekmachine/Polymer/discussions/59