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.
75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# @bible-strong/avatar-core
|
|
|
|
Framework-independent validation, semantic playback and renderer-neutral SVG scene generation for
|
|
Bible Strong procedural avatars. The package has no React, DOM, Motion or browser-storage
|
|
dependency.
|
|
|
|
## Install and validate
|
|
|
|
```sh
|
|
pnpm add @bible-strong/avatar-core
|
|
```
|
|
|
|
Use `parseAvatarDefinition` for untrusted JSON text. It enforces the 256 KiB/depth limits and
|
|
detects duplicate object keys before validating against the v1 schema. Use
|
|
`validateAvatarDefinition` when the value is already materialized.
|
|
|
|
```ts
|
|
import { parseAvatarDefinition } from '@bible-strong/avatar-core'
|
|
|
|
const parsed = parseAvatarDefinition(jsonText)
|
|
if (!parsed.ok) {
|
|
throw new Error(`${parsed.errors[0].path}: ${parsed.errors[0].message}`)
|
|
}
|
|
const definition = parsed.value
|
|
```
|
|
|
|
Both functions return a non-mutating discriminated result. Successful values are deeply frozen;
|
|
errors include an RFC 6901 JSON Pointer, code and message. The committed JSON Schema is exported as
|
|
`@bible-strong/avatar-core/schema`.
|
|
|
|
## Semantic lookup and playback
|
|
|
|
Public calls use semantic keys only. `resolveExpression` and `resolveAnimation` return typed errors
|
|
for unknown keys; standard animations additionally report
|
|
`unavailable_standard_animation` when their required expressions are absent.
|
|
|
|
```ts
|
|
import {
|
|
advanceAvatarPlayback,
|
|
getStandardAnimationAvailabilityV1,
|
|
playAvatarAnimation,
|
|
renderAvatarFrame,
|
|
} from '@bible-strong/avatar-core'
|
|
|
|
const availability = getStandardAnimationAvailabilityV1(definition.expressions)
|
|
const started = playAvatarAnimation(definition, 'idle', 0)
|
|
if (!started.ok) throw new Error(started.error.message)
|
|
|
|
const state = advanceAvatarPlayback(definition, started.value, 500, {
|
|
random: () => 0.5,
|
|
})
|
|
const scene = renderAvatarFrame(definition, state, 500, {
|
|
random: () => 0.5,
|
|
reduceMotion: false,
|
|
})
|
|
```
|
|
|
|
`advanceAvatarPlayback` is a pure state transition driven by a monotonic timestamp and injected
|
|
random source. The timeline for each step is transition then hold. `pauseAvatarPlayback` and
|
|
`resumeAvatarPlayback` preserve exact progress. With `reduceMotion: true`, transitions and ambient
|
|
motion jump deterministically to their target while configured blinks remain active.
|
|
|
|
`renderAvatarDefinition` renders a static semantic expression. `renderAvatarFrame` renders an
|
|
animated frame. Both return paths, visibility and resolved colors without creating DOM nodes.
|
|
|
|
## Entry points
|
|
|
|
- `@bible-strong/avatar-core`: contract, validation, semantic catalog, playback and scene APIs.
|
|
- `@bible-strong/avatar-core/schema`: the v1 Draft 2020-12 JSON Schema.
|
|
- `@bible-strong/avatar-core/geometry`, `/body`, `/surfaces`, `/ambient-motion`: advanced pure
|
|
primitives for renderer authors.
|
|
|
|
This package is private while copyright ownership, Apache-2.0 relicensing and repository metadata
|
|
are confirmed. Local tarballs are for verification only and must not be published.
|