@cesarvenzac/figures 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 César Venzac
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,153 @@
1
- # Temporary Holding Version
1
+ # @cesarvenzac/figures
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Small figures for the agents in your interface: a cube, a sphere, a pyramid, a block or a cloud,
4
+ really in 3D, with two eyes painted on its face.
5
+
6
+ They have no mouth, arms or hats. They say everything with their eyes and the way they move, as
7
+ Anki's Cozmo does: lids cut into the eyes for each expression, or the eyes become a shape (^ ^,
8
+ stars, hearts, × ×), the head turning and tipping with them. Each shape has acts of its own: the
9
+ cube solves itself like a Rubik's cube while it thinks, the block turns its dials like a cryptex,
10
+ the pyramid's capstone floats, the sphere has moons, the cloud rains while it works. Give one a
11
+ mood and it shows it, and reacts as it changes: it celebrates a finished run, loses its colour at
12
+ a failed one, yawns when it's switched off.
13
+
14
+ The docs are at [cesarvenzac.com/figures](https://cesarvenzac.com/figures), and the figures to
15
+ make, pet and watch in [the Lab](https://cesarvenzac.com/lab/figures).
16
+
17
+ ```sh
18
+ npm install @cesarvenzac/figures
19
+ ```
20
+
21
+ ## Use
22
+
23
+ ```tsx
24
+ import { figureFor } from "@cesarvenzac/figures";
25
+ import { AgentFigure } from "@cesarvenzac/figures/react";
26
+
27
+ const ada = figureFor("Ada"); // { shape: "sphere", energy: "calm", habit: "wave", palette: 6 }
28
+
29
+ <AgentFigure figure={ada} mood="thinking" size={48} />;
30
+ ```
31
+
32
+ A figure is four choices, plain data you can store: its `shape` (`cube`, `sphere`, `pyramid`,
33
+ `block`, `cloud`), its `energy` (`calm`, `lively`, `bouncy`: how big and quick it moves), its
34
+ `habit` (what it does while it waits: `look`, `hum`, `nap`, `spin`, `wave`, `morph`) and its
35
+ `palette` (a colourway, 1 to 8). `figureFor(word)` makes one from any word, the same word the same
36
+ figure every time, so an agent's name is enough. `readFigure(value)` reads a stored one back,
37
+ filling in anything missing or unknown; `isFigure(value)` says whether a value is a whole figure.
38
+
39
+ ## Moods
40
+
41
+ What the agent it stands for is doing. Each mood has its expression and its loop:
42
+
43
+ | Mood | Shows |
44
+ | --- | --- |
45
+ | `idle` | Waiting: breathing, blinking, doing its habit now and then |
46
+ | `thinking` | Setting up: looking up and aside, the cube scrambling and solving itself |
47
+ | `working` | At work: eyes narrowed and scanning, each shape busy its own way |
48
+ | `happy` | Done, something to look at: happy eyes, turning into a star now and then |
49
+ | `trouble` | In trouble: squeezed eyes, worrying, shaking now and then |
50
+ | `sleep` | Switched off: eyes shut, grey and dim, z's |
51
+
52
+ As the mood changes it reacts (`reactionTo(from, to)` says which): to `happy`, it celebrates (the
53
+ cube bursts and snaps back, the sphere splashes, the pyramid launches its capstone, the block
54
+ spins its dials like a slot machine, the cloud gets a rainbow); to `trouble`, it fails; into work,
55
+ it gets going; to `sleep`, it dozes off, and back, it wakes.
56
+
57
+ ## `AgentFigure`
58
+
59
+ ```tsx
60
+ <AgentFigure
61
+ figure={ada}
62
+ mood="working"
63
+ size={48} // its box, in pixels; the canvas overhangs it for its halo, shadow and hops
64
+ look // turns toward the pointer on a desktop (default true)
65
+ react // smiles and bounces when the link or button it's in is hovered (default true)
66
+ pet // clicked, it's petted, and the link it's in doesn't open (default true)
67
+ grab={false} // dragged, it turns, springing home when let go
68
+ still={false} // drawn once, never moving
69
+ drain={0} // 0 to 1: greys it, for an agent running out of budget, say
70
+ />
71
+ ```
72
+
73
+ To set it outright rather than by mood: `expression` (one of `EXPRESSIONS`: `neutral`, `happy`,
74
+ `sad`, `tired`, `thinking`, `working`, `listening`, `speaking`, `sleeping`, `surprised`,
75
+ `trouble`, `love`, `excited`, `failed`) and `motion` (a loop to move in, one of `LOOPS`). `play`
76
+ makes a move now, again whenever its `at` changes:
77
+
78
+ ```tsx
79
+ <AgentFigure figure={ada} play={{ motion: "spin", at: Date.now() }} />
80
+ ```
81
+
82
+ The moves are `MOVES` (`hop`, `bounce`, `spin`, `turn`, `flip`, `nod`, `shake`, `wave`, `pop`,
83
+ `melt`, `love`) and the reactions `REACTIONS` (`pet`, `celebrate`, `fail`, `start`, `doze`,
84
+ `wake`). `aim` (`{ x, y }`, −1 to 1 each way, right and down) says where it looks, in place of the
85
+ pointer; `lift` (a function of the frame's time, 0 to 1) hops it off the ground as it walks, its
86
+ shadow staying put. Both are read every frame. `className` and `style` go on its box, after its own
87
+ styles.
88
+
89
+ Every figure on a page notices the others: when one is petted, finishes or fails, the rest turn
90
+ to look, and now and then one glances at whichever is busy. A hover on a link or button the
91
+ figure is in makes it smile; to react to another element's hover, mark it `data-figure-host`.
92
+
93
+ It's a drawing, hidden from assistive tech: put words beside it saying who it is and what it's
94
+ doing. It holds still under reduced motion and while it's off screen. Until its shader is ready
95
+ it's a flat drawing, from the server on, which the 3D one fades in over where it stands; where
96
+ there's no WebGL 2 it stays flat.
97
+
98
+ ## Colours
99
+
100
+ Each colourway is three colours, `main`, `light` and `deep`, which its material flows through
101
+ (`COLOURWAYS`: blue, green, sun, pink, violet, teal, orange, red). Give one your own with
102
+ `colours`, and the eyes theirs with `ink` (`INK`, a near black, unless you do). Any CSS colour
103
+ works, and a custom property is read from the page's root, so your tokens stay the one place
104
+ they're said:
105
+
106
+ ```tsx
107
+ <AgentFigure figure={ada} colours={{ main: "var(--brand)", light: "var(--brand-light)", deep: "var(--brand-deep)" }} ink="var(--ink)" />
108
+ ```
109
+
110
+ `AgentDot` is a figure's colours alone, as a dot, where a whole figure wouldn't read (a table's
111
+ row): `<AgentDot figure={ada} size={8} />`, with `colours` too.
112
+
113
+ ## A still
114
+
115
+ `svgOf(figure, expression?, colours?, size?, id?)` writes a figure as an SVG file, seen from the
116
+ front: for an email, a social card, anywhere a live figure can't go. It runs anywhere, Node
117
+ included.
118
+
119
+ ```ts
120
+ import { figureFor, svgOf } from "@cesarvenzac/figures";
121
+
122
+ svgOf(figureFor("Ada"), "happy", {}, 128); // '<svg xmlns="http://www.w3.org/2000/svg" …'
123
+ ```
124
+
125
+ ## Cost
126
+
127
+ Every figure on a page is drawn by one WebGL 2 context, raymarching the shapes in a fragment
128
+ shader, and copied onto its own canvas; the canvas is at most 512 device pixels across, and a
129
+ figure is drawn every frame only while something happens, every other frame while it only
130
+ breathes, and not at all off screen. They all share one frame loop and one pointer listener.
131
+
132
+ The shader is big, and a slow or software driver takes seconds over it (headless Chromium's
133
+ SwiftShader spends two on its first draw), so it's made ready without holding up the page: compiled
134
+ with `KHR_parallel_shader_compile` where the browser has it, else once the page is idle, then drawn
135
+ once on a single pixel, each step waited for a frame at a time, never asked about before it's done.
136
+ The page answers throughout; the figures show their flat drawings meanwhile.
137
+
138
+ ## Development
139
+
140
+ ```sh
141
+ npm ci
142
+ npm test
143
+ npm run typecheck
144
+ npm run check # packed as npm publishes it, then installed and run as a user's would be
145
+ ```
146
+
147
+ This repository is a copy. The package is developed inside the site it was made for, whose
148
+ repository is private, and every release copies it here and publishes it to npm from here, with
149
+ provenance. Issues are welcome; pull requests are read, and their changes made at the source.
150
+
151
+ ## Licence
152
+
153
+ MIT. The material is the one the site's Aura experiment drew, on MaterialX's Perlin noise.
@@ -0,0 +1,55 @@
1
+ import type { Loop, Reaction, Shape } from "./figure.ts";
2
+ import { type Bit, type Pose, REST } from "./figure-pose.ts";
3
+ /**
4
+ * What each shape does its own way, as the cube solves itself like a Rubik's cube while it thinks:
5
+ * pure functions of time, giving a pose (figure-pose.ts) with the shape's own parts.
6
+ *
7
+ * Reactions, once, `p` from 0 to 1 (`actAt`):
8
+ * - Petted: heart eyes and hearts floating up; the cube twirls its top layer, the sphere dents and
9
+ * ripples like jelly, the pyramid leans like jelly, the block's dials rock as it purrs, the
10
+ * cloud's puffs bounce one after another.
11
+ * - A run finished: starry eyes and sparks; the cube bursts into its cubelets, twisting, and snaps
12
+ * back; the sphere splashes into droplets that fly out and run back together; the pyramid
13
+ * launches its capstone, spinning, and catches it; the block spins its dials like a slot machine,
14
+ * the eyes coming round last; the cloud's puffs pop and a rainbow sweeps over it.
15
+ * - A run failed: × × eyes and drained colour; the cube's layers glitch and it slumps; the sphere
16
+ * deflates, wrinkled, and fills again; the pyramid's slabs slip sideways and back; the block's
17
+ * dials jam and jerk; the cloud storms, rain and lightning.
18
+ * - Work starting, switched off, switched on: a determined nod, a yawn as the eyes close, a
19
+ * stretch as they open wide; each shape turning a layer, a capstone or its dials its own way.
20
+ *
21
+ * Loops, at `t` seconds, as strong as `env` (0 to 1: how far it has come in, or gone out)
22
+ * (`actLoopAt`): thinking, the sphere's moons orbit, the pyramid's capstone floats and turns, the
23
+ * block's dials turn like a cryptex's, the cloud boils (the cube's Rubik's turns are
24
+ * rubik.ts); at work, the cube's layers tick like clockwork, the sphere's colour rolls
25
+ * with a moon going round, the capstone stamps, the block's side dials roll like wheels, the cloud
26
+ * rains; asleep, z's rise and the cube's cubelets loosen; worried, goosebumps, a rattle, a grey
27
+ * drizzle. A loop that turns something (`QUANTUM`) comes back to where it started every so many
28
+ * seconds, so it can stop there.
29
+ */
30
+ /** Where in the picture a shape's top is, as it rests (world units from the picture's middle). */
31
+ export declare const topOf: (shape: Shape) => number;
32
+ /** Where in the picture its middle is. */
33
+ export declare const middleOf: (shape: Shape) => number;
34
+ /** Hearts floating up from above its head, one after another from `from`, each living `life` of the move. */
35
+ export declare function hearts(p: number, shape: Shape, from: number, every: number, life: number, count: number): Bit[];
36
+ /** Sparks round it, popping one after another from `from`, each living `life`. */
37
+ export declare function sparks(p: number, shape: Shape, from: number, life: number): Bit[];
38
+ /** Z's asleep: one rising every 2.2 seconds, each for 3.3, the first once it has had time to doze off. */
39
+ export declare function zs(t: number, shape: Shape, strength?: number): Bit[];
40
+ /** Where a reaction has got to `p` of the way through (0 to 1), for a shape, at an energy's amplitude. */
41
+ export declare function actAt(act: Reaction, p: number, shape: Shape, amp?: number): Pose;
42
+ /**
43
+ * How often each shape's loop comes back to where it started, in seconds at lively energy: a
44
+ * loop that turns its parts stops only then, so nothing jumps. 0 is any time. The thinking cube's
45
+ * Rubik's turns finish their own round (figure-motion.ts).
46
+ */
47
+ export declare const QUANTUM: Record<Loop, Record<Shape, number>>;
48
+ /** How long a loop's own act takes to come in and to go out, in seconds. */
49
+ export declare const ENVELOPE: {
50
+ readonly in: 0.6;
51
+ readonly out: 0.5;
52
+ };
53
+ /** Where a shape's own loop act is at `t` seconds, as strong as `env`. */
54
+ export declare function actLoopAt(loop: Loop, t: number, shape: Shape, amp?: number, env?: number): Pose;
55
+ export { REST };