Eric Cappannelli 99300b3b30 feat(runtime): ship semantic avatar packages and Studio export

- add the v1 AvatarDefinition schema, bounded parser, strict validation, semantic catalog, pure geometry, scene generation, and deterministic playback to @bible-strong/avatar-core
- add the React 19 renderer with semantic controls, SSR-safe embedded/floating layouts, direct frame updates, pointer and keyboard movement, constraints, callbacks, and accessible controls
- add real tarball packaging and a clean React/Vite consumer using the exported Strobi definition
- add Studio semantic-key authoring, runtime readiness, JSON download/copy, bundled-key recovery, concise errors, targeted local-project clearing, npm guidance, syntax highlighting, and a runnable package preview
- preserve the historical ZIP and Studio project exports, regenerate the standalone engine, and synchronize English, French, and Simplified Chinese copy
- add focused contract, playback, renderer, interaction, persistence, export, and localization coverage
- archive the completed runtime and semantic-curation specs, retain the Vite performance draft, and record the engineering session in TIMELOG.md

Validation:
- pnpm check: 19 test files, 162 tests, typecheck, engine freshness, package builds, and Studio production build passed
- npm pack dry runs: 30 core files and 10 React files
- package smoke: real tarballs installed, typechecked, and built outside the workspace
- browser checks: semantic playback, embedded/floating render, drag, mobile overflow, runtime export recovery, formatted copy, syntax colors, and live package preview

Publication remains disabled: both packages stay private and AGPL-3.0-only pending licensing and repository metadata approval. Vue and Angular adapters remain deferred.

2026-08-16 10:18:39 +02:00

7.1 KiB

Raw Blame History

Avatar Runtime Semantic Curation

Status

Approved by Éric on 2026-08-14. This document is the product/design source for the committed STANDARD_ANIMATIONS_V1 runtime manifest.

Implementation state: complete. The approved expression keys, explicit animation keys, and STANDARD_ANIMATIONS_V1 manifest are present in the bundled Studio data and runtime contract. This approval gate no longer blocks phase C; overall implementation progress is tracked in 20260814-avatar-runtime-npm-package-and-semantic-api.md.

It implements the human-validation gate required by 20260814-avatar-runtime-npm-package-and-semantic-api.md, phase B, step 1. No semantic key or standard-animation mapping below may be copied into bundled data or runtime code before explicit approval. That approval has now been recorded below.

Expression catalogue proposal

The 27 bundled Studio expressions were rendered with the framework-independent SVG geometry engine and visually inventoried. Internal IDs remain editor-only identifiers and will not be exposed by the runtime.

Internal expression ID	Proposed semantic key	Visual reading
`expression-00`	`upward-side-glance`	Eyes raised toward one side
`expression-01`	`downward-gaze`	Medium eyes looking downward
`expression-05`	`skeptical-right`	One vertical eye and one horizontal eye
`expression-06`	`small-attentive`	Small attentive eyes
`expression-12`	`wide-downward-gaze`	Large round eyes looking downward
`expression-03`	`surprised-left`	Large offset eyes with a tilted head
`expression-04`	`sleepy-squint`	Narrow tired eyes
`expression-07`	`angry-right`	Tense angular gaze
`expression-08`	`curious-left`	Uneven sideways gaze
`expression-09`	`asymmetric-down-right`	One large and one small eye
`expression-10`	`attentive-left`	Slightly tilted attentive gaze
`expression-11`	`joyful-wide`	Very large open eyes
`expression-13`	`eyes-closed`	Closed, lowered eyes
`expression-02`	`joyful-down-right`	Large eyes angled downward
`expression-14`	`skeptical-left`	Opposite skeptical gaze
`expression-15`	`far-right-glance`	Small eyes strongly offset to one side
`expression-16`	`angry-left`	Opposite angular gaze
`expression-17`	`playful-right`	Lively uneven gaze
`expression-18`	`asymmetric-up-left`	One large and one small raised eye
`expression-19`	`gentle-downward-gaze`	Soft downward gaze
`expression-20`	`wide-down-left`	Very large lowered eyes
`expression-21`	`surprised-wide-left`	Wide round eyes, alternate surprise pose
`expression-22`	`drowsy-closed`	Nearly closed raised eyes
`expression-23`	`suspicious-right`	Wary sideways gaze
`expression-24`	`shy-downward`	Small lowered eyes
`expression-3d2bed26-f97c-477d-922f-77600cb10e92`	`angry-brows`	Strongly inward-sloping eyes
`expression-5220eaee-32fe-4bd8-ad31-432189534cc8`	`uneasy-left`	Uneven worried gaze

Explicit animation-key proposal

The 23 bundled animations already have unique English machine IDs. The proposal is to use each existing ID unchanged as its semanticKey:

sleeping, waking, idle, listening, thinking, searching, working, excited, bored, suspicious, angry, drowsy, happy, curious, confused, surprised, proud, shy, sad, laughing, scared, playful, and celebrate.

`STANDARD_ANIMATIONS_V1` proposal

This proposal retains the established Studio sequence order, timing, playback, and blink behavior. All steps use transitionMs: 500 and transition: "smooth".

Standard key	Ordered semantic-expression steps	`holdMs` per step	Playback mode	Blink: initial / min / max / duration (ms)
`idle`	`upward-side-glance` -> `curious-left`	5200	`loop`	2600 / 3400 / 6200 / 280
`happy`	`joyful-down-right` -> `joyful-wide` -> `playful-right` -> `gentle-downward-gaze`	2300	`loop`	2100 / 2800 / 5000 / 260
`sad`	`sleepy-squint` -> `eyes-closed` -> `drowsy-closed`	3600	`loop`	4800 / 6500 / 9500 / 420
`thinking`	`curious-left` -> `angry-left` -> `skeptical-left` -> `playful-right` -> `skeptical-right`	2300	`loop`	2100 / 2800 / 5000 / 260
`excited`	`joyful-down-right` -> `playful-right` -> `surprised-wide-left` -> `surprised-left` -> `joyful-wide`	2300	`loop`	1200 / 1800 / 3600 / 220
`celebrate`	`joyful-down-right` -> `curious-left` -> `playful-right`	2300	`loop`	1200 / 1800 / 3600 / 220

For each row, the required expression keys are the unique keys appearing in its ordered steps. An explicit animation with the same key will override the corresponding standard animation, as required by the v1 runtime specification.

Approval record

Approver: Éric

Decision date: 2026-08-14

Decision: approved as proposed

Requested changes: none recorded

7.1 KiB Raw Blame History