Getting started

npm install @cesarvenzac/figures

Plain TypeScript, published as ES modules with their types, and no dependencies. The main entry runs anywhere, Node included; the live figure is @cesarvenzac/figures/react, with React 18 or later as a peer.

A first figure

import { figureFor } from "@cesarvenzac/figures";
import { AgentFigure } from "@cesarvenzac/figures/react";

export function Agent({ name, busy }: Props) {
  return (
    <span className="agent">
      <AgentFigure
        figure={figureFor(name)}
        mood={busy ? "working" : "idle"}
        size={40}
      />
      {name}
    </span>
  );
}

size is its box in pixels, 48 unless said. Its canvas is half as big again, overhanging the box on every side for its halo, its shadow and its hops, and lets the pointer through. A figure is a drawing, hidden from assistive tech, so put words beside it: who it is and what it's doing.

Four choices

A figure is plain data, to keep wherever you keep the agent:

type Figure = {
  shape: "cube" | "sphere" | "pyramid" | "block" | "cloud";
  energy: "calm" | "lively" | "bouncy";
  habit: "look" | "hum" | "nap" | "spin" | "wave" | "morph";
  palette: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
};

• Shape: a cube, a sphere, a pyramid, a block or a cloud, each with acts of its own.
• Energy: how big and quick it moves. Calm is smaller and slower, bouncy bigger and quicker.
• Habit: what it does while it waits: looks around, hums, naps, spins, wobbles or changes shape for a beat.
• Palette: its colourway, blue, green, sun, pink, violet, teal, orange or red (Colours).

figureFor(word) picks all four from a word, the same word always the same figure. readFigure(value) reads a stored one back, taking any part missing or unknown from DEFAULT_FIGURE, and isFigure(value) says whether a value is a whole figure, for a form to check before it saves.

import { figureFor, readFigure } from "@cesarvenzac/figures";

figureFor("Ada");
// { shape: "sphere", energy: "calm", habit: "wave", palette: 6 }
readFigure(JSON.parse(stored)); // never throws

On a server

AgentFigure is a client component ("use client"): a server draws its box and canvas, and it draws itself once the page runs, fading in. Elsewhere it's a component like any other.