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.
2.8 KiB
@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
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.
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.
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.