bible-strong-avatar-lab/packages/avatar-core

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