99300b3b30
- 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.
90 lines
7.1 KiB
Markdown
90 lines
7.1 KiB
Markdown
# 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
|