@lovelace_lol/polymer 0.0.1

package/README.md

@@ -0,0 +1,226 @@
+# Polymer
+
+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.
+
+Polymer is intentionally separate from Latticework and Polyester. It is built as
+a Society of Mind agency system: small CLJS agencies collaborate through streams,
+plan locally, schedule their own work, and keep side effects inside the agencies
+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.
+
+## Agency API
+
+The package exposes an agency system:
+
+```js
+const agencies = createCharacterAgencies();
+agencies.dispatch({ agency: "blink", command: { type: "enable" } });
+
+agencies.events.subscribe((message) => {});
+agencies.snapshot();
+```
+
+Agencies communicate through incoming and outgoing streams of plain data.
+Messages may be facts, goals, requests, constraints, priorities, status, or
+diagnostics. Requests that imply side effects are handled by the receiving
+agency's local planner, scheduler, and effector path.
+
+Host applications may dispatch external commands, observe outgoing streams, and
+read snapshots for diagnostics or configuration. Host applications should not
+serve as the normal message bus between Polymer agencies.
+
+## Current Agencies
+
+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
+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.
+
+The text-only LipSync pronunciation fallback and its accuracy limits are
+documented in [`docs/lipsync-pronunciation-fallback.md`](docs/lipsync-pronunciation-fallback.md).
+
+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
+libraries through separate runtime-specific boundaries.
+
+Hair appearance and physics are model/runtime capabilities rather than
+character-behavior agencies. Polymer therefore does not expose a Hair agency,
+Hair planner, or Hair scheduler. It continues to re-export Embody's hair color,
+material-normalization, and Wasm physics APIs so hosts can configure the
+character runtime without importing Embody directly.
+
+## Gesture Agency
+
+Gesture is the arm/hand gesticulation agency. It accepts LoomLarge-authored
+gesture snapshots as plain data and turns them into typed bone-channel animation
+snippets. It does not call scene bones, host UI state, storage, or the animation
+runtime.
+Gesture snapshots are compatible with the Gestures tab profile shape: id/name,
+optional description or text representation, emoji trigger, left/right/both/custom
+scope, captured source metadata, duration, priority, affected bones, static bone
+targets, and optional time-based keyframes.
+
+Gesture commands can still name an exact gesture or emoji, but the planner also
+accepts gesture goals. A goal asks Gesture to choose from the authored library by
+intent, tags, scope, required or avoided effectors, cooldown, active conflicts,
+and capacity before it emits Animation requests.
+
+### Gesture GOAP Planning
+
+Gesture GOAP plans for one local world-state transition: a suitable authored
+arm/hand gesture is selected and safely scheduled through Animation, or the
+agency records why that goal cannot be satisfied. It is not a second public
+playback API.
+
+The planner uses the incoming command, the gesture library, active snippets, and
+Gesture config to decide:
+
+- which gesture best satisfies an explicit gesture id, emoji mapping, intent,
+  tags, text hints, scope, and bone constraints
+- whether the selected gesture is valid motion and is out of cooldown
+- whether active snippets conflict on affected bones
+- whether capacity is available under `maxActive`
+- whether to ignore, remove only conflicting snippets, remove the oldest snippets
+  needed for capacity, build a snippet, schedule Animation, and record the result
+
+Host integrations should prefer the character agency network so Gesture's
+animation requests are routed to Animation inside Polymer:
+
+```js
+const agencies = createCharacterAgencies({
+  animation: { engine },
+  gesture: {
+    gestures: profile.characterGestures,
+    emojiMappings: profile.gestureEmojiMappings,
+  },
+});
+
+agencies.dispatch({ agency: "gesture", command: { type: "playEmoji", emoji: "👋" } });
+agencies.dispatch({
+  agency: "gesture",
+  command: {
+    type: "gesture.goal",
+    goal: {
+      intent: "greeting",
+      tags: ["wave"],
+      scope: "right",
+      avoidBones: ["HAND_L"],
+    },
+  },
+});
+```
+
+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.
+
+## 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.
+
+Default path — pass a container element and a character URL:
+
+```js
+import {
+  createCharacterHost,
+  createCharacterAgencies,
+} from '@lovelace_lol/polymer';
+
+const host = await createCharacterHost({
+  container: document.getElementById('viewport'),
+  character: {
+    modelUrl: '/characters/jonathan.glb',
+    presetType: 'cc4',
+  },
+});
+
+const agencies = createCharacterAgencies({
+  animation: { engine: host.engine },
+});
+```
+
+Named scene types (`studio`, `showcase`, `inspection`, `void`) bundle
+background, lighting preset, and shadow-plane defaults; enumerate them via
+`CHARACTER_SCENE_TYPES` / `CHARACTER_SCENE_TYPE_IDS`:
+
+```js
+const host = await createCharacterHost({
+  container,
+  character: { modelUrl: '/characters/jonathan.glb' },
+  scene: { type: 'showcase' },
+});
+```
+
+Advanced path — inject an existing Three.js scene:
+
+```js
+const host = await createCharacterHost({
+  container: mountEl,
+  character: { modelUrl: '/characters/jonathan.glb', presetType: 'cc4' },
+  external: { scene, renderer, camera },
+});
+```
+
+Polymer stays agency-oriented: it does not own the render loop. Use
+`createCharacterHost` / `loadCharacterModel` for scene+model setup, then inject
+`host.engine` into `createCharacterAgencies`.
+
+For an already-managed Three.js scene, Polymer also exposes a CLJS-owned host
+that talks directly to Embody's Rust/Wasm `RuntimeCore`:
+
+```js
+import {
+  createRustEmbodyHostUnbound,
+  initEmbodyCore,
+  supportsRustEmbodyPreset,
+} from '@lovelace_lol/polymer';
+
+await initEmbodyCore();
+if (supportsRustEmbodyPreset('cc4')) {
+  const engine = createRustEmbodyHostUnbound({
+    presetType: 'cc4',
+    profile: characterProfileOverrides,
+  });
+  engine.onReady({ model, meshes });
+  engine.start();
+}
+```
+
+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
+they are explicitly embedded; they are never treated as CC4 aliases.
+
+## Git Install Contract
+
+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.
+
+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.
+
+## Worker Protocol Artifact
+
+The package also ships `@lovelace_lol/polymer/worker/agency-worker.js` as an
+opt-in transport around the complete character agency API. It accepts
+`createCharacterAgencies`, `dispatch`, `snapshot`, and `dispose` messages and
+returns character events, snapshots, and lifecycle messages as plain data. The
+Worker does not add another planner or route between agencies; Polymer's
+character network keeps that responsibility.
+
+CI executes the compiled artifact in a real Node worker thread. LoomLarge does
+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).