procedural-bot-animations 0.1.0 → 0.2.0

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.
Files changed (59) hide show
  1. package/README.md +167 -47
  2. package/dist/animation.d.ts +90 -0
  3. package/dist/animation.js +396 -0
  4. package/dist/brain.d.ts +194 -35
  5. package/dist/brain.js +578 -54
  6. package/dist/character.d.ts +123 -0
  7. package/dist/character.js +916 -0
  8. package/dist/characters/berry.d.ts +2 -0
  9. package/dist/characters/berry.js +38 -0
  10. package/dist/characters/flame.d.ts +2 -0
  11. package/dist/characters/flame.js +46 -0
  12. package/dist/delta.d.ts +16 -0
  13. package/dist/delta.js +146 -0
  14. package/dist/examples.d.ts +4 -0
  15. package/dist/examples.js +208 -0
  16. package/dist/focus.d.ts +46 -0
  17. package/dist/focus.js +284 -0
  18. package/dist/gaze.d.ts +41 -53
  19. package/dist/gaze.js +125 -82
  20. package/dist/index.d.ts +18 -11
  21. package/dist/index.js +18 -11
  22. package/dist/interactions.d.ts +30 -0
  23. package/dist/interactions.js +100 -0
  24. package/dist/library.d.ts +18 -0
  25. package/dist/library.js +14 -0
  26. package/dist/moods.d.ts +78 -46
  27. package/dist/moods.js +48 -73
  28. package/dist/motion.d.ts +93 -0
  29. package/dist/motion.js +167 -0
  30. package/dist/mount.d.ts +90 -0
  31. package/dist/mount.js +707 -0
  32. package/dist/parts.d.ts +36 -0
  33. package/dist/parts.js +131 -0
  34. package/dist/reactions.d.ts +184 -44
  35. package/dist/reactions.js +1851 -116
  36. package/dist/rig.d.ts +119 -0
  37. package/dist/rig.js +59 -0
  38. package/dist/scroll-traveler.js +1 -1
  39. package/dist/ticker.d.ts +10 -0
  40. package/dist/ticker.js +42 -0
  41. package/dist/transformations.d.ts +21 -0
  42. package/dist/transformations.js +306 -0
  43. package/package.json +7 -11
  44. package/dist/bind.d.ts +0 -27
  45. package/dist/bind.js +0 -42
  46. package/dist/blink.d.ts +0 -25
  47. package/dist/blink.js +0 -48
  48. package/dist/fake3d.d.ts +0 -20
  49. package/dist/fake3d.js +0 -24
  50. package/dist/noise.d.ts +0 -16
  51. package/dist/noise.js +0 -17
  52. package/dist/render.d.ts +0 -29
  53. package/dist/render.js +0 -97
  54. package/dist/rng.d.ts +0 -10
  55. package/dist/rng.js +0 -18
  56. package/dist/spring.d.ts +0 -21
  57. package/dist/spring.js +0 -33
  58. package/dist/types.d.ts +0 -63
  59. package/dist/types.js +0 -46
package/README.md CHANGED
@@ -1,82 +1,202 @@
1
1
  # procedural-bot-animations
2
2
 
3
- ![Three Berry characters, each with a different personality, animated by this engine](skills/procedural-bot-animations/assets/cover.gif)
3
+ [![npm version](https://img.shields.io/npm/v/procedural-bot-animations.svg)](https://www.npmjs.com/package/procedural-bot-animations)
4
4
 
5
- A procedural animation engine for a silhouette-plus-eyes avatar — the shape format from [Open Bot Avatar](https://github.com/DominikScholz/open-bot-avatar) — with weighted/blended moods, one-shot reaction timelines (bounce, fright, nod, double-blink), gaze with saccade/pursuit/microsaccade physics and a fake-3D turn, plus a typed state machine for tying it all to real app events.
5
+ ![Three Berry characters animated by an earlier version of this engine](skills/procedural-bot-animations/assets/cover.gif)
6
6
 
7
- Open Bot Avatar is used only to **model** the shape (its editor or `generate-avatar` skill produce the JSON). This package never calls Open Bot Avatar's own renderer or runtime — it renders the shape itself, so moods and reactions can actually deform the eyes and body frame to frame.
7
+ A procedural animation engine for 2D SVG mascots and bot avatars. A character is a body outline, two eyes and up to three moving parts. The engine adds one pose per frame on top of that: an idle that never repeats, blended moods, looping activities, one-shot reactions, eyes that look, blink and react, and parts that sway and bend on springs. It renders plain DOM (one SVG, no framework). The part that computes the pose does not touch the DOM, so you can draw it yourself.
8
8
 
9
- ```
9
+ Characters and animations are plain JSON, so you can write them by hand or generate them with an LLM. The package also contains a typed state machine and a scroll traveler.
10
+
11
+ The cover image was made with an earlier version of the engine. It shows Berry, one of the two built-in characters.
12
+
13
+ ## Install
14
+
15
+ Package page: [npmjs.com/package/procedural-bot-animations](https://www.npmjs.com/package/procedural-bot-animations)
16
+
17
+ ```bash
10
18
  npm install procedural-bot-animations
11
19
  ```
12
20
 
21
+ The package is ESM only, needs a DOM for `mountCharacter`, and has no runtime dependencies.
22
+
23
+ ## Quick start
24
+
13
25
  ```ts
14
- import { getExample } from "open-bot-avatar"; // optional: a source of example shapes
15
- import { bindBrain, createStateMachine } from "procedural-bot-animations";
16
-
17
- const host = document.querySelector("#bot")!;
18
-
19
- const machine = createStateMachine({
20
- initial: "idle",
21
- states: {
22
- idle: { id: "idle" },
23
- thinking: { id: "thinking" },
24
- success: { id: "success", after: { ms: 1800, to: "idle" } },
25
- },
26
- transitions: [
27
- { from: "idle", event: "ask", to: "thinking" },
28
- { from: "thinking", event: "resolve", to: "success" },
29
- ],
26
+ import { mountCharacter, RIG_BERRY } from "procedural-bot-animations";
27
+
28
+ const host = document.querySelector<HTMLElement>("#bot")!;
29
+
30
+ const bot = mountCharacter(host, {
31
+ rig: RIG_BERRY,
32
+ size: 200,
33
+ color: "#e11d2e",
34
+ label: "Berry, the assistant",
30
35
  });
31
36
 
32
- const bot = bindBrain({ host, definition: getExample("mug")!, color: "#ff6a1a" });
33
- machine.subscribe((state) => {
34
- if (state === "thinking") bot.brain.setMood({ focused: 1 });
35
- if (state === "success") { bot.brain.setMood({ proud: 1 }); bot.brain.react("bounce"); }
36
- if (state === "idle") bot.brain.setMood({ focused: 0, proud: 0 });
37
+ bot.update({ mood: "curious" }); // a held expression
38
+ bot.update({ mood: { curious: 0.6, focused: 0.4 }, activity: "thinking" }); // a blend, plus a loop
39
+ bot.react("success"); // a one-shot reaction
40
+ // bot.destroy(); // removes the SVG and the listeners
41
+ ```
42
+
43
+ By default the character looks at the pointer, reacts when the pointer enters it or it is clicked, and follows `prefers-reduced-motion`. The built-in moods, activities and reactions are listed in [`skills/procedural-bot-animations/references/motion-cookbook.md`](skills/procedural-bot-animations/references/motion-cookbook.md) and exported as `MOODS`, `ACTIVITIES` and `REACTIONS`.
44
+
45
+ A minimal page is in [`examples/minimal.html`](examples/minimal.html).
46
+
47
+ ## The Studio
48
+
49
+ The Studio is a static demo in [`site/`](site), served from GitHub Pages at <https://jp-mainieri.github.io/procedural-bot-animations/>. It shows a character on a stage, lets you import your own character and animation JSON, and has prompts you can copy into an LLM to generate them. [`examples/README.md`](examples/README.md) says how to run it locally.
50
+
51
+ ## Bring your own character
52
+
53
+ A character is one JSON object in a 0..100 box. Its core keys (`version`, `id`, `name`, `body.path`, `eyes`) are an [Open Bot Avatar](https://github.com/dominikscholz/open-bot-avatar) definition, so any valid Open Bot Avatar definition is accepted unchanged. An optional `rig` key adds moving parts, eye styles, idle sway and flicker.
54
+
55
+ ```ts
56
+ import { mountCharacter, parseCharacter } from "procedural-bot-animations";
57
+
58
+ const parsed = parseCharacter(jsonText); // never throws
59
+ if (!parsed.ok) throw new Error(parsed.errors.join("\n")); // every problem, each starting with its JSON path
60
+
61
+ mountCharacter(host, {
62
+ rig: parsed.value.rig,
63
+ color: parsed.value.definition.rig?.color, // the format's suggested colour; you pass it on yourself
37
64
  });
38
- bot.start();
65
+ ```
39
66
 
40
- // elsewhere in your app:
41
- machine.send("ask");
67
+ The full contract, with every limit and a worked example, is in [`docs/character-format.md`](docs/character-format.md). `parseCharacter` runs `validateCharacter` and then `characterToRig`; both are exported too.
68
+
69
+ ## Bring your own animations
70
+
71
+ An animation is one JSON object of kind `reaction` (plays once), `activity` (loops) or `mood` (a held pose). It is a set of keyframe tracks over named fields such as `bodySy`, `partL`, `lidTop` or `eyeX`. Every value is an offset from the resting pose.
72
+
73
+ ```ts
74
+ import {
75
+ RIG_BERRY,
76
+ addToLibrary,
77
+ createLibrary,
78
+ mountCharacter,
79
+ parseAnimation,
80
+ } from "procedural-bot-animations";
81
+
82
+ const library = createLibrary(); // a copy of the built-ins that is safe to extend
83
+
84
+ const result = parseAnimation(jsonText); // never throws
85
+ if (!result.ok) throw new Error(result.errors.join("\n"));
86
+ addToLibrary(library, result.value.compiled);
87
+
88
+ const bot = mountCharacter(host, { rig: RIG_BERRY, library });
89
+ // or, on a character that is already mounted: bot.update({ library });
90
+
91
+ const { kind, id } = result.value.definition;
92
+ if (kind === "reaction") bot.react(id);
93
+ if (kind === "activity") bot.update({ activity: id });
94
+ if (kind === "mood") bot.update({ mood: id });
42
95
  ```
43
96
 
44
- A full, running version of this — with buttons, a mood/reaction panel, a character picker, light/dark and reduced-motion support — is in [`examples/states-demo.html`](examples/states-demo.html).
97
+ The full contract, the field list with ranges and a house style for good motion are in [`docs/animation-format.md`](docs/animation-format.md). `describeAnimation(definition)` returns a one-paragraph summary of what an animation does.
98
+
99
+ ## Generate them with an LLM
100
+
101
+ Both format documents end with a **Prompt** section: a self-contained block you copy into any LLM, followed by a description of what you want.
102
+
103
+ - Characters: [Prompt in `docs/character-format.md`](docs/character-format.md#prompt)
104
+ - Animations: [Prompt in `docs/animation-format.md`](docs/animation-format.md#prompt)
105
+
106
+ Paste the model's JSON into `parseCharacter` or `parseAnimation`. Each error starts with the JSON path of the problem, so you can paste the errors back to the model and ask for a fix. The Studio offers the same prompts. If you use Claude Code, the skill in [`skills/procedural-bot-animations/`](skills/procedural-bot-animations) teaches an agent to generate and self-check both formats.
45
107
 
46
108
  ## What's in this repo
47
109
 
48
110
  | Path | What |
49
111
  |---|---|
50
- | [`src/`](src) | The engine: `render.ts` (mounts a definition as this package's own SVG — body path + two posable eyes), `moods.ts` (weighted/blended named moods), `reactions.ts` (one-shot keyframe-free closed-form reaction curves with a priority queue), `gaze.ts` (pursuit/saccade/microsaccade physics, autonomous wander), `fake3d.ts` (the flat-silhouette "head turn" illusion), `blink.ts`, `brain.ts` (composes all of the above into one `Pose` per frame, no DOM), `bind.ts` (the DOM/`requestAnimationFrame` glue), `state-machine.ts` (generic FSM), `scroll-traveler.ts` (a character that travels between page sections on scroll) |
51
- | [`skills/procedural-bot-animations/`](skills/procedural-bot-animations) | A [Claude Code](https://claude.com/claude-code) skill teaching an agent to use this engine, with a calibrated motion cookbook, a state-machine design guide, and a case study |
52
- | [`examples/`](examples) | A runnable states demo (Open Bot Avatar example shapes) and [`examples/berry-live/`](examples/berry-live) — see below |
53
- | [`docs/architecture.md`](docs/architecture.md) | How the layers fit together, and how to point this at a different renderer |
54
- | [`tests/`](tests) | Vitest unit tests (no DOM required — `render.ts`/`bind.ts` are the only DOM-dependent modules, verified by hand via the examples) |
112
+ | [`src/mount.ts`](src/mount.ts), [`src/ticker.ts`](src/ticker.ts) | `mountCharacter`, the plain-DOM SVG renderer, and the shared `requestAnimationFrame` loop |
113
+ | [`src/brain.ts`](src/brain.ts) | `Brain`: computes one `Pose` per frame. No DOM |
114
+ | [`src/gaze.ts`](src/gaze.ts), [`src/focus.ts`](src/focus.ts) | Eye movement (saccade, pursuit, microsaccades, attention, boredom) and the gaze modes (`free`, `focus`, `data-bot-focus` anchors) |
115
+ | [`src/moods.ts`](src/moods.ts), [`src/reactions.ts`](src/reactions.ts), [`src/interactions.ts`](src/interactions.ts), [`src/transformations.ts`](src/transformations.ts) | 9 moods, 5 activities, 36 reactions, the hover and click gestures, and the body-to-object transformations |
116
+ | [`src/parts.ts`](src/parts.ts), [`src/motion.ts`](src/motion.ts), [`src/delta.ts`](src/delta.ts) | Part physics and path bending, springs, keyframe tracks, blink, jump, and the list of animatable fields |
117
+ | [`src/rig.ts`](src/rig.ts), [`src/characters/`](src/characters) | The `Rig` type, and the built-in characters Berry and Flame |
118
+ | [`src/character.ts`](src/character.ts), [`src/animation.ts`](src/animation.ts), [`src/library.ts`](src/library.ts), [`src/examples.ts`](src/examples.ts) | The two JSON formats (validate, compile, parse), the per-instance library, and original example characters and animations written as data |
119
+ | [`src/state-machine.ts`](src/state-machine.ts), [`src/scroll-traveler.ts`](src/scroll-traveler.ts) | A typed state machine and a scroll traveler. Both are DOM-free |
120
+ | [`docs/`](docs) | [`architecture.md`](docs/architecture.md), [`character-format.md`](docs/character-format.md), [`animation-format.md`](docs/animation-format.md) |
121
+ | [`skills/procedural-bot-animations/`](skills/procedural-bot-animations) | A [Claude Code](https://claude.com/claude-code) skill: mount a character, generate character and animation JSON, tune motion |
122
+ | [`site/`](site) | The Studio |
123
+ | [`examples/`](examples) | A minimal page |
124
+ | [`tests/`](tests) | Vitest tests. They run in Node, with no DOM |
125
+
126
+ ## The eyes
127
+
128
+ The eyes are most of why a character feels alive. What the engine does, all of it in `src/gaze.ts`, `src/brain.ts` and `src/mount.ts`:
129
+
130
+ - **Saccades.** When the target jumps, the eye hops there on a slightly underdamped spring, aims a little short and settles. It does not glide in a straight line.
131
+ - **Pursuit.** When the target moves slowly, such as a cursor, the eye follows it smoothly. A fast cursor is followed firmly instead of with a chain of hops.
132
+ - **Microsaccades.** At rest, the eye makes tiny random shifts every 0.5 to 1.6 s, so it is never perfectly still.
133
+ - **Blinks.** A random interval of 1.8 to 6 s. One blink in five is a double blink. A large saccade can trigger a blink. There are no blinks while the character sleeps.
134
+ - **Attention and boredom.** Big saccades, a fast cursor and a close cursor raise attention: the eyes grow and the lids open. When nothing happens for a few seconds, boredom rises and the lids get heavy.
135
+ - **Shape follows movement.** During a fast saccade the eyes stretch along the movement and tilt toward it, then relax. Looking up enlarges the eye. Looking down lowers the eyelid.
136
+ - **Cross-eyed look.** With the cursor right on top of the character, the eyes move closer together.
137
+ - **Real eyelids.** The upper and lower lids are clip paths with an adjustable tilt, so a mood can frown or squint instead of only scaling the eye. A happy eye crossfades into an arc.
138
+ - **Fake 3D turn.** The `turn` field slides the eyes sideways and shrinks the far one. Past 1, the face turns to a profile where one eye vanishes.
139
+ - **Where to look.** `gaze: "pointer"` follows the cursor. `"free"` wanders across the page and gets drawn to page events. `"focus"` looks at what matters: focused fields, typing, clicks, scrolling and elements with `data-bot-focus`. You can also pass a point or a function.
55
140
 
56
- ## Berry: a case study, not a toy example
141
+ The numbers are in [`skills/procedural-bot-animations/references/motion-cookbook.md`](skills/procedural-bot-animations/references/motion-cookbook.md). How the pieces connect is in [`docs/architecture.md`](docs/architecture.md).
57
142
 
58
- [`examples/berry-live/`](examples/berry-live) is a faithful, working port of [DevBerry](https://devberry.app)'s actual mascot — real body-and-leaf geometry, real spring/leaf-bend physics, real keyframed personality reactions (wink, flatten, somersault), ported line-for-line from its production engine (credit and detail in [`skills/procedural-bot-animations/references/berry-case-study.md`](skills/procedural-bot-animations/references/berry-case-study.md)). It's **not** part of the installable package — Berry has a multi-part rig (three independently-sprung leaves), a different shape than the single silhouette `src/` targets. It's here so the gap between "a generic single-silhouette engine" and "a production multi-part character" is something you can see and copy from, not just a sentence in a README.
143
+ ## State machine and scroll traveler
59
144
 
60
- ## Relationship to Open Bot Avatar
145
+ `createStateMachine` is a small typed state machine with timed transitions (`after`), interrupt rules (`interruptibleBy`) and subscribers. It does not know about characters: you connect a state to `update({ mood, activity })` or `react(...)` yourself. Call `tick(dtMs)` every frame to advance the `after` timers. See [`skills/procedural-bot-animations/references/state-machine-guide.md`](skills/procedural-bot-animations/references/state-machine-guide.md).
61
146
 
62
- This is an independent, unofficial companion project — not affiliated with or published by Open Bot Avatar's author. It depends on nothing from `open-bot-avatar` at runtime: the engine only needs a `{ body: { path }, eyes: { x, y, spacing, scale } }` definition, which you can get from Open Bot Avatar's editor/skill, hand-write, or generate any other way.
147
+ `travelerFrame` and `findActiveSlot` compute where a character should be as the page scrolls between sections. They take numbers (slot rectangles that you read yourself) and return numbers.
63
148
 
64
- Open Bot Avatar is MIT-licensed by Dominik Scholz. This repo is also MIT-licensed; see [LICENSE](LICENSE). Berry is DevBerry's mascot, included in `examples/berry-live/` with its owner's permission (see the case study for exactly what's ported and what isn't).
149
+ ## Accessibility
150
+
151
+ - **Reduced motion.** `reducedMotion` is `"auto"` by default and follows `prefers-reduced-motion`. You can force it with `true` or ignore it with `false`. When it applies, the character stops idling, jumping, squashing and blinking, and the idle sway of the parts stops. Reactions lose their movement fields (position, rotation, scale, turn, sparks, embers, smoke and transformations). The gaze follows its target with simple smoothing instead of saccades. Changes of expression (eyelids, eye shape, happy eyes, accessories such as `!` and `?`) still show.
152
+ - **Screen readers.** With the `label` option the SVG gets `role="img"` and `aria-label`. Without it the SVG is `aria-hidden="true"`.
153
+ - **Decorative mode.** `interactive: false` turns off hover and click reactions.
154
+ - The SVG has no tab stop and no keyboard handlers. If a click on the character does something in your app, give that action a real button.
155
+
156
+ ## Relationship to Open Bot Avatar and DevBerry
157
+
158
+ **Open Bot Avatar.** This project is independent and unofficial. It is not affiliated with Open Bot Avatar or published by its author, Dominik Scholz. Open Bot Avatar is MIT-licensed. From it, this project uses only the shape of its JSON definition (`version`, `id`, `name`, `body.path`, `eyes`), and it adapts its path grammar. It has no runtime dependency on the `open-bot-avatar` package and never calls its renderer.
159
+
160
+ **DevBerry.** The engine is a TypeScript port of the mascot engine behind [DevBerry](https://devberry.app), made generic: the rig, the brain, the gaze, the moods, the reactions and the transformations come from there. Berry and the Flame are DevBerry's characters, included with the owner's permission.
161
+
162
+ ## Migrating from 0.1
163
+
164
+ 0.2.0 replaces the whole engine. It is a breaking change, with no compatibility layer.
165
+
166
+ 0.1 was a small engine for one silhouette with two pill eyes. These 0.1 exports no longer exist:
167
+
168
+ | 0.1 export | Use instead |
169
+ |---|---|
170
+ | `bindBrain`, `BoundBot`, `BindOptions` | `mountCharacter(host, { rig })`, which returns `{ brain, svg, update, react, jump, currentReaction, getGazeState, destroy }` |
171
+ | `mountRig`, `MountedRig`, `RenderOptions`, `Bounds` | `mountCharacter` |
172
+ | `AvatarDefinitionLike` | `CharacterDefinition` and `parseCharacter(json)`, which also returns a `Rig`. Open Bot Avatar definitions are accepted unchanged |
173
+ | `brain.setMood({...})` | `bot.update({ mood: "curious" })` or `{ mood: { curious: 0.6, focused: 0.4 } }`. The new `mood` replaces the previous one; it does not merge |
174
+ | `brain.react("bounce")` | `bot.react("success")` or another name from `REACTIONS`. The 0.1 reactions `bounce`, `doubleBlink` and `nod` are gone. `fright` still exists but is a new, different reaction |
175
+ | `ReactionPlayer`, `ReactionDefinition`, `builtinReactions`, `bounce`, `fright`, `doubleBlink`, `nod` | `REACTIONS`, `ReactionDef`, a `Library`, and `Brain.react(name, now)`. Write your own with the animation JSON format |
176
+ | `MoodBlender`, `MoodBlenderOptions`, `blendMoods`, `builtinMoods`, `MoodDefinition` | `MOODS`. The `Brain` blends the mood weights itself. Custom moods go through a `Library` |
177
+ | `GazeEngine`, `GazeEngineOptions`, `Point2D`, `ArrivalStyle` | `Gaze` (used by the `Brain`), or the `gaze` option of `mountCharacter` (`"pointer"`, `"free"`, `"focus"`, a point, a function, or `null`) |
178
+ | `BlinkScheduler`, `BlinkOptions` | Blinking is built into the `Brain` (`newBlink` and `stepBlink` in `src/motion.ts`) |
179
+ | `fakeTurn`, `FakeTurnOptions` | The `turn` field, handled by the `Brain` |
180
+ | `neverRepeating`, `breathing`, `BreathingOptions` | Built into the `Brain` |
181
+ | `mulberry32`, `randRange`, `chance` | Removed. `Brain` takes an `rng` option, and the `Rng` type is still exported |
182
+ | `safeDt` | Removed. The `Brain` limits `dt` itself |
183
+ | `neutralPose`, `neutralEyePose`, `neutralBodyPose`, `addPose`, `addEyePose`, `addBodyPose`, `PoseDelta`, `resolveDelta`, `BodyPose` | Removed. `Pose` and `EyePose` still exist but are different types. Animations use the `Delta` fields in `src/delta.ts` |
184
+ | `Brain`, `BrainOptions` | Same names, new API: `new Brain(rig, options)` and `brain.step(now, input)` |
185
+ | `SpringState` (`value`, `velocity`) | `Spring` (`a`, `v`). `spring(m, target, k, c, dt)` mutates `m` and returns nothing |
186
+
187
+ `clamp`, `lerp`, `smooth` and `damp` are still exported with the same signatures, now from `src/motion.ts`. `createStateMachine` and the scroll traveler are unchanged. The optional `peerDependencies` entry for `open-bot-avatar` is gone.
65
188
 
66
189
  ## Development
67
190
 
68
191
  ```bash
69
192
  npm install
70
- npm run typecheck
71
- npm test
72
- npm run build
193
+ npm run typecheck # tsc --noEmit
194
+ npm test # vitest run
195
+ npm run build # tsc -p tsconfig.build.json, into dist/
196
+ npm run check # all three, as CI runs them
73
197
  ```
74
198
 
75
- `npm run check` runs all three in sequence — the same thing CI runs on every push.
76
-
77
- ## Contributing
78
-
79
- Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
199
+ CI runs on Node 20 and 22. See [CONTRIBUTING.md](CONTRIBUTING.md).
80
200
 
81
201
  ## License
82
202
 
@@ -0,0 +1,90 @@
1
+ import type { DeltaField, PartialDelta } from "./delta.js";
2
+ import type { CurveName } from "./motion.js";
3
+ import type { ActivityDef, ReactionDef } from "./reactions.js";
4
+ import type { ValidationResult } from "./character.js";
5
+ export type { ValidationResult };
6
+ export type FieldGroup = "body" | "parts" | "eyes" | "lids" | "accessories" | "flame" | "morph";
7
+ export type FieldUnit = "px" | "deg" | "scale" | "0..1" | "-1..1";
8
+ export interface FieldInfo {
9
+ group: FieldGroup;
10
+ /** `px`: drawing pixels; `deg`: degrees; `scale`: increment over 1 (-0.5 = half); `0..1` / `-1..1`: plain amounts. */
11
+ unit: FieldUnit;
12
+ min: number;
13
+ max: number;
14
+ rest: 0;
15
+ description: string;
16
+ }
17
+ /**
18
+ * One entry per delta field. The hard ranges come from the extreme values the
19
+ * built-in reactions, activities and moods actually reach, widened about 1.5×.
20
+ * 0 is always the character at rest.
21
+ */
22
+ export declare const FIELD_INFO: Record<DeltaField, FieldInfo>;
23
+ /** Group of every field, in the order of `FIELDS`. */
24
+ export declare const FIELD_GROUPS: readonly FieldGroup[];
25
+ export declare const CURVE_NAMES: CurveName[];
26
+ export type AnimationKeyframe = [number, number] | [number, number, CurveName];
27
+ export type AnimationTracks = Partial<Record<DeltaField, AnimationKeyframe[]>>;
28
+ export type AnimationDefinition = {
29
+ version: 1;
30
+ kind: "reaction";
31
+ id: string;
32
+ name: string;
33
+ duration: number;
34
+ tracks: AnimationTracks;
35
+ } | {
36
+ version: 1;
37
+ kind: "activity";
38
+ id: string;
39
+ name: string;
40
+ period: number;
41
+ tracks: AnimationTracks;
42
+ } | {
43
+ version: 1;
44
+ kind: "mood";
45
+ id: string;
46
+ name: string;
47
+ pose: Partial<Record<DeltaField, number>>;
48
+ };
49
+ export type CompiledAnimation = {
50
+ kind: "reaction";
51
+ id: string;
52
+ name: string;
53
+ def: ReactionDef;
54
+ } | {
55
+ kind: "activity";
56
+ id: string;
57
+ name: string;
58
+ def: ActivityDef;
59
+ } | {
60
+ kind: "mood";
61
+ id: string;
62
+ name: string;
63
+ def: PartialDelta;
64
+ };
65
+ export declare const ANIMATION_LIMITS: {
66
+ readonly reactionDuration: readonly [0.2, 10];
67
+ readonly activityPeriod: readonly [0.3, 20];
68
+ readonly maxTracks: 24;
69
+ readonly maxKeyframes: 40;
70
+ readonly nameMax: 60;
71
+ };
72
+ /** The valid field names closest to `name` (case-insensitive edit distance, substring matches first). */
73
+ export declare function closestFields(name: string, count?: number): DeltaField[];
74
+ /** Checks any JSON value as an animation definition. Collects every problem; warnings never block. */
75
+ export declare function validateAnimation(input: unknown): ValidationResult<AnimationDefinition>;
76
+ /** Turns a validated definition into what the library stores. */
77
+ export declare function compileAnimation(def: AnimationDefinition): CompiledAnimation;
78
+ /** JSON text → validated definition plus compiled entry. Never throws. */
79
+ export declare function parseAnimation(json: string): ValidationResult<{
80
+ definition: AnimationDefinition;
81
+ compiled: CompiledAnimation;
82
+ }>;
83
+ /** Structural type so this file does not depend on library.ts. */
84
+ export declare function addToLibrary(lib: {
85
+ reactions: Record<string, ReactionDef>;
86
+ activities: Record<string, ActivityDef>;
87
+ moods: Record<string, PartialDelta>;
88
+ }, a: CompiledAnimation): void;
89
+ /** One-paragraph plain-English summary: length, which groups move and the peak values. */
90
+ export declare function describeAnimation(def: AnimationDefinition): string;