bible-strong-avatar-lab/packages/avatar-core/README.md

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

Definitions from the earlier pre-release runtime export may still contain standardAnimationSet: 1; the marker is accepted for compatibility but does not add any implicit animations.

Semantic lookup and playback

Public calls use semantic keys only. resolveExpression and resolveAnimation return typed errors for keys that are not present in the validated definition. Every animation is explicit in the definition, so the JSON remains the single source of truth for what an avatar can play.

import {
  advanceAvatarPlayback,
  playAvatarAnimation,
  renderAvatarFrame,
} from '@bible-strong/avatar-core'

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.

Application integrations are kept in separate packages: @bible-strong/avatar-react renders with React 19, while @bible-strong/avatar-web mounts the same definition directly into the DOM. Both depend on this package and use the same playback and scene implementation.

The package follows Semantic Versioning. While it remains below 1.0.0, breaking API changes increment the minor version and fixes increment the patch version.