@fungi.computer/sprite

Type Aliases

AssetPolicy

AssetPolicy = object

Host-owned admission and resource limits for published avatar artwork.

Properties

baseURL

readonly baseURL: string

allowedOrigins

readonly allowedOrigins: readonly string[]

maxBytes

readonly maxBytes: number

Maximum bytes admitted for one response.

maxTotalBytes

readonly maxTotalBytes: number

Cumulative bytes admitted across one character selection.

maxRequests

readonly maxRequests: number

Number of requests admitted for one character selection.

fetch?

readonly optional fetch?: typeof fetch

Asset

Asset = object

Decoded transport bytes; adapters use these instead of opening their own URLs.

Properties

url

readonly url: string

bytes

readonly bytes: Uint8Array<ArrayBuffer>>

contentType

readonly contentType: string

Control

Control = z.infer<typeof controlSchema>>

A validated, character-owned customization control.

Appearance

Appearance = Readonly<Record<string, string | number | boolean>>>>

Values saved by the shell; no renderer objects or transient activity.

Customization

Customization = z.infer<typeof customizationSchema>>

A parsed, saved Sprite customization.

CharacterDocument

CharacterDocument = z.infer<typeof characterSchema>>

A portable character, with renderer data still awaiting its native decoder.

CharacterSource

CharacterSource = string | { local: string; }

A served document URL or a host-installed character key.

AvatarPresentation

AvatarPresentation = object

One complete request. Omitted customization resets to character defaults.

Properties

src

readonly src: CharacterSource

activity?

readonly optional activity?: string

expression?

readonly optional expression?: string

appearance?

readonly optional appearance?: Appearance

renderStyle?

readonly optional renderStyle?: RenderStyle

SVG filter drawn over the character; omitted draws it plain.

NativePresentation

NativePresentation = object

The resolved activity and appearance passed to a native renderer.

Properties

activity

readonly activity: string

expression

readonly expression: string | null

appearance

readonly appearance: Appearance

NativePlayer

NativePlayer = object

The adapter registers native destruction in the selection scope.

Properties

activities

readonly activities: readonly string[]

expressions

readonly expressions: readonly string[]

Methods

set()

set(presentation): void

Update the existing native instance.

Parameters

presentation

NativePresentation

Returns

void

pause()

pause(paused): void

Pause or resume animation without losing the current frame.

Parameters

paused

boolean

Returns

void

RendererContext

RendererContext = object

Native renderer access to the selected document and its admitted assets.

Properties

target

readonly target: HTMLElement

document

readonly document: CharacterDocument

signal

readonly signal: AbortSignal

maxPixels

readonly maxPixels: number

reportError

readonly reportError: (error) => void

Report a native failure that occurs after the renderer has become ready.

Parameters

error

Error

Returns

void

assetURL

readonly assetURL: (reference) => Effect.Effect<string, Error, Scope.Scope>>

Admit an asset and revoke its object URL when the selection closes.

Parameters

reference

string

Returns

Effect.Effect<string, Error, Scope.Scope>

Renderer

Renderer = (context) => Effect.Effect<NativePlayer, Error, Scope.Scope>>

A native renderer whose resources live in the character selection scope.

Parameters

context

RendererContext

Returns

Effect.Effect<NativePlayer, Error, Scope.Scope>

EffectivePresentation

EffectivePresentation = NativePresentation & object

A request after native fallback and appearance validation.

Type Declaration

renderStyle

readonly renderStyle: RenderStyle

requestedActivity

readonly requestedActivity: string

requestedExpression

readonly requestedExpression: string | null

fallback

readonly fallback: boolean

PlayerState

PlayerState = { status: "empty" | "loading" | "destroyed"; } | { status: "error"; error: Error; } | { status: "ready"; document: CharacterDocument; presentation: EffectivePresentation; updateError?: Error; }

Observable loading, ready, error, and disposal states.

LocalCharacter

LocalCharacter = object

An installed document and its renderer, loaded together by the shell.

Properties

document

readonly document: CharacterDocument

render

readonly render: Renderer

SpriteOptions

SpriteOptions = object

Host-owned character registry and resource policy.

Properties

assets?

readonly optional assets?: AssetPolicy

Omit for local-only characters; network access is denied by default.

maxPixels?

readonly optional maxPixels?: number

renderers?

readonly optional renderers?: Readonly<Record<string, () => Promise<{ default: Renderer; }>>>

Native adapters allowed for served character documents.

characters?

readonly optional characters?: Readonly<Record<string, () => Promise<LocalCharacter>>>>>>

Lazy local characters installed by this shell.

AvatarPlayer

AvatarPlayer = object

One mounted avatar; dispose releases its native and browser resources.

Properties

state

readonly state: PlayerState

Current public state.

Methods

subscribe(listener): () => void

Observe state changes until the returned unsubscribe function is called.

Parameters

listener

(next) => void

Returns

() => void

set()

set(next): void

Select a source or update its activity and appearance.

Parameters

AvatarPresentation

Returns

void

pause()

pause(value): void

Pause or resume the current native animation.

Parameters

value

boolean

Returns

void

dispose()

dispose(): Promise<void>>

Cancel loading and release the current native selection.

Returns

Promise<void>

SpriteService

SpriteService = object

Stable shell configuration that creates independent mounted players.

Methods

mount()

mount(target): AvatarPlayer

Claim one DOM host for a new avatar instance.

Parameters

target

HTMLElement

Returns

AvatarPlayer

RenderStyle

RenderStyle = z.infer<typeof renderStyleSchema>>

How a Sprite is drawn over its native renderer.

RenderStyleLayer

RenderStyleLayer = object

The filter layer owned by one mounted player.

Methods

set()

set(style, stage): void

Draw stage in style; plain removes the filter.

Parameters

style

stage

HTMLElement

Returns

void

still()

still(value): void

Hold one still frame: paused, hidden, or reduced motion.

Parameters

value

boolean

Returns

void

dispose()

dispose(): void

Stop the boil and remove the filter and its definitions.

Returns

void

Variables

controlSchema

const controlSchema: ZodDiscriminatedUnion<[ZodObject<{ type: ZodLiteral<"number">>; label: ZodString; default: ZodNumber; min: ZodNumber; max: ZodNumber; step: ZodOptional<ZodNumber>>; }, $strict>>, ZodObject<{ type: ZodLiteral<"choice">>; label: ZodString; default: ZodString; options: ZodArray<ZodObject<{ value: ZodString; label: ZodString; }, $strict>>>>; }, $strict>>, ZodObject<{ type: ZodLiteral<"color">>; label: ZodString; default: ZodString; }, $strict>>, ZodObject<{ type: ZodLiteral<"boolean">>; label: ZodString; default: ZodBoolean; }, $strict>>], "type">>

Portable editor descriptors; native input bindings belong to each renderer.

customizationSchema

const customizationSchema: ZodObject<{ appearance: ZodOptional<ZodRecord<ZodString, ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>>>; renderStyle: ZodDefault<ZodEnum<{ plain: "plain"; pencil: "pencil"; manga: "manga"; riso: "riso"; halftone: "halftone"; blueprint: "blueprint"; crt: "crt"; watercolor: "watercolor"; }>>; }, $strict>>

What a person saves about their Sprite. Hosts parse stored values with this schema at their boundary; character controls still validate appearance against the selected document when it is presented.

characterSchema

const characterSchema: ZodObject<{ version: ZodLiteral<1>>; name: ZodString; renderer: ZodString; controls: ZodDefault<ZodRecord<ZodString, ZodDiscriminatedUnion<[ZodObject<{ type: ZodLiteral<"number">>; label: ZodString; default: ZodNumber; min: ZodNumber; max: ZodNumber; step: ZodOptional<ZodNumber>>; }, $strict>>, ZodObject<{ type: ZodLiteral<"choice">>; label: ZodString; default: ZodString; options: ZodArray<ZodObject<{ value: …; label: …; }, $strict>>>>; }, $strict>>, ZodObject<{ type: ZodLiteral<"color">>; label: ZodString; default: ZodString; }, $strict>>, ZodObject<{ type: ZodLiteral<"boolean">>; label: ZodString; default: ZodBoolean; }, $strict>>], "type">>>>>>; poster: ZodOptional<ZodString>>; data: ZodJSONSchema; }, $strict>>

Shared envelope only. The selected adapter must decode data before use.

renderStyles

const renderStyles: readonly ["plain", "pencil", "manga", "riso", "halftone", "blueprint", "crt", "watercolor"]

Render styles: an SVG filter drawn over a mounted Sprite. This module owns the style vocabulary, every filter definition, and the DOM layer that mounts one filter per player with ids unique to that player.

renderStyleSchema

const renderStyleSchema: ZodEnum<{ plain: "plain"; pencil: "pencil"; manga: "manga"; riso: "riso"; halftone: "halftone"; blueprint: "blueprint"; crt: "crt"; watercolor: "watercolor"; }>

A saved render style; unknown names fail at the boundary.

renderStyleLabels

const renderStyleLabels: object

Picker labels for each style, in display order.

Type Declaration

plain

readonly plain: "Plain" = "Plain"

pencil

readonly pencil: "Pencil" = "Pencil"

manga

readonly manga: "Manga" = "Manga"

riso

readonly riso: "Riso" = "Riso"

halftone

readonly halftone: "Halftone" = "Halftone"

blueprint

readonly blueprint: "Blueprint" = "Blueprint"

crt

readonly crt: "CRT" = "CRT"

watercolor

readonly watercolor: "Watercolor" = "Watercolor"

Functions

resolveAppearance()

resolveAppearance(controls, overrides?): Appearance

Validate the complete appearance before applying any native updates.

Parameters

controls

Readonly<Record<string, Control>>

overrides?

Appearance = {}

Returns

Appearance

createSprite()

createSprite(options): SpriteService

Stable shell service; each mounted player owns its own selection.

Parameters

options

SpriteOptions

Returns

SpriteService

createRenderStyleLayer()

createRenderStyleLayer(host): RenderStyleLayer

Mount a render-style layer in host. The filter applies only to the stage box, and its boil runs only while the host is on screen and not still.

Parameters

host

HTMLElement

Returns

RenderStyleLayer