Skip to content
Sprite0.2.0
API reference

sprite

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/sprite";

Exports

Section titled “Exports”
Kind Export Description
type alias AssetPolicy Host-owned admission and resource limits for published avatar artwork.
type alias Asset Decoded transport bytes; adapters use these instead of opening their own URLs.
type alias Control A validated, character-owned customization control.
type alias Appearance Values saved by the shell; no renderer objects or transient activity.
type alias Customization A parsed, saved Sprite customization.
type alias CharacterDocument A portable character, with renderer data still awaiting its native decoder.
type alias Json An opaque JSON value; the selected adapter owns its schema.
type alias CharacterSource A served document URL or a host-installed character key.
type alias AvatarPresentation One complete request. Omitted customization resets to character defaults.
type alias NativePresentation The resolved activity and appearance passed to a native renderer.
type alias NativePlayer The adapter registers native destruction in the selection scope.
type alias RendererContext Native renderer access to the selected document and its admitted assets.
type alias Renderer A native renderer whose resources live in the character selection scope.
type alias EffectivePresentation A request after native fallback and appearance validation.
type alias PlayerState Observable loading, ready, error, and disposal states.
type alias LocalCharacter An installed document and its renderer, loaded together by the shell.
type alias SpriteOptions Host-owned character registry and resource policy.
type alias AvatarPlayer One mounted avatar; dispose releases its native and browser resources.
type alias SpriteService Stable shell configuration that creates independent mounted players.
type alias RenderStyle How a Sprite is drawn over its native renderer.
type alias RenderStyleLayer The filter layer owned by one mounted player.
constant controlSchema Portable editor descriptors; native input bindings belong to each renderer.
constant customizationSchema 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.
constant characterSchema Shared envelope only. The selected adapter must decode data before use.
constant renderStyles 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.
constant renderStyleSchema A saved render style; unknown names fail at the boundary.
constant renderStyleLabels Picker labels for each style, in display order.
function resolveAppearance() Validate the complete appearance before applying any native updates.
function createSprite() Stable shell service; each mounted player owns its own selection.
function createRenderStyleLayer() 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.

AssetPolicytype alias

Section titled “AssetPolicy”
Signature
type AssetPolicy = object;

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

Properties

Section titled “Properties”

baseURL

Section titled “baseURL”
Signature
readonly baseURL: string;

allowedOrigins

Section titled “allowedOrigins”
Signature
readonly allowedOrigins: readonly string[];

maxBytes

Section titled “maxBytes”
Signature
readonly maxBytes: number;

Maximum bytes admitted for one response.

maxTotalBytes

Section titled “maxTotalBytes”
Signature
readonly maxTotalBytes: number;

Cumulative bytes admitted across one character selection.

maxRequests

Section titled “maxRequests”
Signature
readonly maxRequests: number;

Number of requests admitted for one character selection.

fetch?

Section titled “fetch?”
Signature
readonly optional fetch?: typeof fetch;

Assettype alias

Section titled “Asset”
Signature
type Asset = object;

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

Properties

Section titled “Properties”

url

Section titled “url”
Signature
readonly url: string;

bytes

Section titled “bytes”
Signature
readonly bytes: Uint8Array<ArrayBuffer>;

contentType

Section titled “contentType”
Signature
readonly contentType: string;

Controltype alias

Section titled “Control”
Signature
type Control = z.infer<typeof controlSchema>;

A validated, character-owned customization control.

Appearancetype alias

Section titled “Appearance”
Signature
type Appearance = Readonly<Record<string, string | number | boolean>>;

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

Customizationtype alias

Section titled “Customization”
Signature
type Customization = z.infer<typeof customizationSchema>;

A parsed, saved Sprite customization.

CharacterDocumenttype alias

Section titled “CharacterDocument”
Signature
type CharacterDocument = z.infer<typeof characterSchema>;

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

Jsontype alias

Section titled “Json”
Signature
type Json = CharacterDocument["data"];

An opaque JSON value; the selected adapter owns its schema.

CharacterSourcetype alias

Section titled “CharacterSource”
Signature
type CharacterSource =
  | string
  | {
      local: string;
    };

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

AvatarPresentationtype alias

Section titled “AvatarPresentation”
Signature
type AvatarPresentation = object;

One complete request. Omitted customization resets to character defaults.

Properties

Section titled “Properties”

timeMs?

Section titled “timeMs?”
Signature
readonly optional timeMs?: number;

Optional host clock in milliseconds; native animation seeks instead of running live.

src

Section titled “src”
Signature
readonly src: CharacterSource;

activity?

Section titled “activity?”
Signature
readonly optional activity?: string;

expression?

Section titled “expression?”
Signature
readonly optional expression?: string;

appearance?

Section titled “appearance?”
Signature
readonly optional appearance?: Appearance;

renderStyle?

Section titled “renderStyle?”
Signature
readonly optional renderStyle?: RenderStyle;

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

performance?

Section titled “performance?”
Signature
readonly optional performance?: Json;

Renderer data for this presentation; Sprite never reads it. It is compared by identity, so keep the reference stable (for example with useMemo); a new object each render makes the renderer’s set run every time.

NativePresentationtype alias

Section titled “NativePresentation”
Signature
type NativePresentation = object;

The resolved activity and appearance passed to a native renderer.

Properties

Section titled “Properties”

timeMs?

Section titled “timeMs?”
Signature
readonly optional timeMs?: number;

Absolute animation time in milliseconds, when controlled by the host.

activity

Section titled “activity”
Signature
readonly activity: string;

expression

Section titled “expression”
Signature
readonly expression: string | null;

appearance

Section titled “appearance”
Signature
readonly appearance: Appearance;

performance?

Section titled “performance?”
Signature
readonly optional performance?: Json;

The request’s performance, unchanged and compared by identity.

NativePlayertype alias

Section titled “NativePlayer”
Signature
type NativePlayer = object;

The adapter registers native destruction in the selection scope.

Properties

Section titled “Properties”

activities

Section titled “activities”
Signature
readonly activities: readonly string[];

expressions

Section titled “expressions”
Signature
readonly expressions: readonly string[];

Methods

Section titled “Methods”

set()

Section titled “set()”
Signature
set(presentation): void;

Update the existing native instance.

Parameters
Section titled “Parameters”
Parameter Type
presentation NativePresentation
Returns
Section titled “Returns”

void

pause()

Section titled “pause()”
Signature
pause(paused): void;

Pause or resume animation without losing the current frame.

Parameters
Section titled “Parameters”
Parameter Type
paused boolean
Returns
Section titled “Returns”

void

RendererContexttype alias

Section titled “RendererContext”
Signature
type RendererContext = object;

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

Properties

Section titled “Properties”

target

Section titled “target”
Signature
readonly target: HTMLElement;

document

Section titled “document”
Signature
readonly document: CharacterDocument;

signal

Section titled “signal”
Signature
readonly signal: AbortSignal;

maxPixels

Section titled “maxPixels”
Signature
readonly maxPixels: number;

reportError

Section titled “reportError”
Signature
readonly reportError: (error) => void;

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

Parameters
Section titled “Parameters”
Parameter Type
error Error
Returns
Section titled “Returns”

void

reportProgress

Section titled “reportProgress”
Signature
readonly reportProgress: (progress) => void;

Publish renderer progress on the ready state; ignored once the selection closes.

Parameters
Section titled “Parameters”
Parameter Type
progress Json
Returns
Section titled “Returns”

void

assetURL

Section titled “assetURL”
Signature
readonly assetURL: (reference) => Effect.Effect<string, Error, Scope.Scope>;

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

Parameters
Section titled “Parameters”
Parameter Type
reference string
Returns
Section titled “Returns”

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

Renderertype alias

Section titled “Renderer”
Signature
type Renderer = (context) => Effect.Effect<NativePlayer, Error, Scope.Scope>;

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

Parameters

Section titled “Parameters”
Parameter Type
context RendererContext

Returns

Section titled “Returns”

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

EffectivePresentationtype alias

Section titled “EffectivePresentation”
Signature
type EffectivePresentation = NativePresentation & object;

A request after native fallback and appearance validation.

Type Declaration

Section titled “Type Declaration”
Name Type
renderStyle RenderStyle
requestedActivity string
requestedExpression string | null
fallback boolean

PlayerStatetype alias

Section titled “PlayerState”
Signature
type PlayerState =
  | {
      status: "empty" | "loading" | "destroyed";
    }
  | {
      status: "error";
      error: Error;
    }
  | {
      status: "ready";
      document: CharacterDocument;
      presentation: EffectivePresentation;
      updateError?: Error;
      progress?: Json;
    };

Observable loading, ready, error, and disposal states.

Union Members

Section titled “Union Members”

Type Literal

Section titled “Type Literal”
Signature
{
  status: "empty" | "loading" | "destroyed";
}

Type Literal

Section titled “Type Literal”
Signature
{
  status: "error";
  error: Error;
}

Type Literal

Section titled “Type Literal”
Signature
{
  status: "ready";
  document: CharacterDocument;
  presentation: EffectivePresentation;
  updateError?: Error;
  progress?: Json;
}
Name Type Description
status "ready" -
document CharacterDocument -
presentation EffectivePresentation -
updateError? Error -
progress? Json The latest value the renderer passed to reportProgress.

LocalCharactertype alias

Section titled “LocalCharacter”
Signature
type LocalCharacter = object;

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

Properties

Section titled “Properties”

document

Section titled “document”
Signature
readonly document: CharacterDocument;

render

Section titled “render”
Signature
readonly render: Renderer;

SpriteOptionstype alias

Section titled “SpriteOptions”
Signature
type SpriteOptions = object;

Host-owned character registry and resource policy.

Properties

Section titled “Properties”

assets?

Section titled “assets?”
Signature
readonly optional assets?: AssetPolicy;

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

maxPixels?

Section titled “maxPixels?”
Signature
readonly optional maxPixels?: number;

renderers?

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

Native adapters allowed for served character documents.

characters?

Section titled “characters?”
Signature
readonly optional characters?: Readonly<Record<string, () => Promise<LocalCharacter>>>;

Lazy local characters installed by this shell.

AvatarPlayertype alias

Section titled “AvatarPlayer”
Signature
type AvatarPlayer = object;

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

Properties

Section titled “Properties”

state

Section titled “state”
Signature
readonly state: PlayerState;

Current public state.

Methods

Section titled “Methods”

subscribe()

Section titled “subscribe()”
Signature
subscribe(listener): () => void;

Observe state changes until the returned unsubscribe function is called.

Parameters
Section titled “Parameters”
Parameter Type
listener (next) => void
Returns
Section titled “Returns”

() => void

set()

Section titled “set()”
Signature
set(next): void;

Select a source or update its activity and appearance.

Parameters
Section titled “Parameters”
Parameter Type
next AvatarPresentation
Returns
Section titled “Returns”

void

pause()

Section titled “pause()”
Signature
pause(value): void;

Pause or resume the current native animation.

Parameters
Section titled “Parameters”
Parameter Type
value boolean
Returns
Section titled “Returns”

void

dispose()

Section titled “dispose()”
Signature
dispose(): Promise<void>;

Cancel loading and release the current native selection.

Returns
Section titled “Returns”

Promise<void>

SpriteServicetype alias

Section titled “SpriteService”
Signature
type SpriteService = object;

Stable shell configuration that creates independent mounted players.

Methods

Section titled “Methods”

mount()

Section titled “mount()”
Signature
mount(target): AvatarPlayer;

Claim one DOM host for a new avatar instance.

Parameters
Section titled “Parameters”
Parameter Type
target HTMLElement
Returns
Section titled “Returns”

AvatarPlayer

RenderStyletype alias

Section titled “RenderStyle”
Signature
type RenderStyle = z.infer<typeof renderStyleSchema>;

How a Sprite is drawn over its native renderer.

RenderStyleLayertype alias

Section titled “RenderStyleLayer”
Signature
type RenderStyleLayer = object;

The filter layer owned by one mounted player.

Methods

Section titled “Methods”

set()

Section titled “set()”
Signature
set(style, stage): void;

Draw stage in style; plain removes the filter.

Parameters
Section titled “Parameters”
Parameter Type
style | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"
stage HTMLElement
Returns
Section titled “Returns”

void

still()

Section titled “still()”
Signature
still(value): void;

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

Parameters
Section titled “Parameters”
Parameter Type
value boolean
Returns
Section titled “Returns”

void

dispose()

Section titled “dispose()”
Signature
dispose(): void;

Stop the boil and remove the filter and its definitions.

Returns
Section titled “Returns”

void

controlSchemaconstant

Section titled “controlSchema”
Signature
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.

customizationSchemaconstant

Section titled “customizationSchema”
Signature
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.

characterSchemaconstant

Section titled “characterSchema”
Signature
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.

renderStylesconstant

Section titled “renderStyles”
Signature
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.

renderStyleSchemaconstant

Section titled “renderStyleSchema”
Signature
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.

renderStyleLabelsconstant

Section titled “renderStyleLabels”
Signature
const renderStyleLabels: object;

Picker labels for each style, in display order.

Type Declaration

Section titled “Type Declaration”
Name Type Default value
plain "Plain" "Plain"
pencil "Pencil" "Pencil"
manga "Manga" "Manga"
riso "Riso" "Riso"
halftone "Halftone" "Halftone"
blueprint "Blueprint" "Blueprint"
crt "CRT" "CRT"
watercolor "Watercolor" "Watercolor"

resolveAppearance()function

Section titled “resolveAppearance()”
Signature
function resolveAppearance(controls, overrides?): Appearance;

Validate the complete appearance before applying any native updates.

Parameters

Section titled “Parameters”
Parameter Type
controls Readonly<Record<string, Control>>
overrides Appearance

Returns

Section titled “Returns”

Appearance

createSprite()function

Section titled “createSprite()”
Signature
function createSprite(options): SpriteService;

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

Parameters

Section titled “Parameters”
Parameter Type
options SpriteOptions

Returns

Section titled “Returns”

SpriteService

createRenderStyleLayer()function

Section titled “createRenderStyleLayer()”
Signature
function 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

Section titled “Parameters”
Parameter Type
host HTMLElement

Returns

Section titled “Returns”

RenderStyleLayer