@algorisys/tinyfly 0.95.0 → 0.98.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 (51) hide show
  1. package/README.md +8 -8
  2. package/docs/acting.md +165 -0
  3. package/docs/character-appearance.md +281 -0
  4. package/docs/editor-guide.md +14 -6
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +44 -2
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +8 -6
  11. package/docs/teaching.md +1 -1
  12. package/lib/addons/characters.js +6266 -4087
  13. package/lib/browser/tinyfly.iife.js +16 -14
  14. package/lib/browser/tinyfly.js +8441 -6262
  15. package/lib/browser/tinyfly.umd.js +16 -14
  16. package/lib/types/characters/acting/index.d.ts +1 -0
  17. package/lib/types/characters/acting/surface-script.d.ts +92 -0
  18. package/lib/types/characters/capabilities.d.ts +20 -0
  19. package/lib/types/characters/cast.d.ts +284 -0
  20. package/lib/types/characters/character.d.ts +22 -4
  21. package/lib/types/characters/chart.d.ts +108 -0
  22. package/lib/types/characters/code-panel.d.ts +21 -46
  23. package/lib/types/characters/hands/held-items.d.ts +88 -0
  24. package/lib/types/characters/hands/index.d.ts +1 -0
  25. package/lib/types/characters/head/ears.d.ts +10 -0
  26. package/lib/types/characters/head/facial-hair.d.ts +118 -0
  27. package/lib/types/characters/head/glasses.d.ts +24 -0
  28. package/lib/types/characters/head/hair.d.ts +560 -0
  29. package/lib/types/characters/head/hats.d.ts +58 -0
  30. package/lib/types/characters/head/head-look.d.ts +53 -0
  31. package/lib/types/characters/head/index.d.ts +5 -0
  32. package/lib/types/characters/head/shell.d.ts +64 -0
  33. package/lib/types/characters/index.d.ts +7 -1
  34. package/lib/types/characters/interactions.d.ts +69 -0
  35. package/lib/types/characters/props/families/animals.d.ts +6 -0
  36. package/lib/types/characters/props/index.d.ts +1 -0
  37. package/lib/types/characters/props/prop-surface.d.ts +63 -0
  38. package/lib/types/characters/species/human-motion.d.ts +5 -2
  39. package/lib/types/characters/species/human.d.ts +111 -4
  40. package/lib/types/characters/surface/edit-log.d.ts +47 -0
  41. package/lib/types/characters/surface/index.d.ts +11 -0
  42. package/lib/types/characters/surface/pieces.d.ts +61 -0
  43. package/lib/types/characters/surface/ride.d.ts +31 -0
  44. package/lib/types/characters/surface/surface-box.d.ts +18 -0
  45. package/lib/types/characters/surface/surface.d.ts +79 -0
  46. package/lib/types/characters/wardrobe/basic-outfit.d.ts +19 -5
  47. package/lib/types/characters/whiteboard.d.ts +131 -0
  48. package/llms-full.txt +625 -28
  49. package/llms.txt +29 -28
  50. package/package.json +1 -1
  51. package/skills/tinyfly/SKILL.md +38 -9
@@ -12,5 +12,6 @@ export * from './lip-sync';
12
12
  export * from './script';
13
13
  export * from './hand-path';
14
14
  export * from './beat-check';
15
+ export * from './surface-script';
15
16
  export * from './custom';
16
17
  export * from './persona';
@@ -0,0 +1,92 @@
1
+ import type { Track } from '../../engine/types';
2
+ import type { StickStyle } from '../stick-figure';
3
+ import type { Surface } from '../surface/surface';
4
+ import { type BeatProblem } from './beat-check';
5
+ import { type Cast } from './custom';
6
+ import { type Beat, type BeatTarget, type ScriptOptions, type ScriptResult } from './script';
7
+ /**
8
+ * A figure acting on surfaces, written as plain data: beats name the places
9
+ * they act on (`{ surface: 'code', anchor: 'token:4:Println' }`) and say what
10
+ * the surface does in answer (`then`), at a moment of the beat.
11
+ *
12
+ * ```ts
13
+ * const result = surfaceScript('hero', { code }, [
14
+ * { do: 'leap', to: { surface: 'code', anchor: 'line:4' }, onto: { surface: 'code', anchor: 'line:5' } },
15
+ * { do: 'grab', target: { surface: 'code', anchor: 'token:4:Println' },
16
+ * then: { surface: 'code', edit: 'carry', anchor: 'token:4:Println', until: { beat: 2, at: 'release' } } },
17
+ * { do: 'throw', then: { surface: 'code', edit: 'fling', anchor: 'token:4:Println', at: 'release' } },
18
+ * ], { from: 600, ground: code.box.bottom })
19
+ * const timeline = { tracks: result.tracks } // the figure's tracks and every surface's
20
+ * ```
21
+ *
22
+ * It compiles to the same calls written by hand: the beats go to
23
+ * `scriptTracks` with each named place swapped for its box (as laid out,
24
+ * before any edit moves it), then each `then` runs `surface.edit()` at its
25
+ * beat's moment, in the order the beats are written. A `carry` makes the
26
+ * piece follow the figure's hand (`handPath`). Last, the figure is carried
27
+ * by any surface it stands on (`surface.ride()`), unless `ride: false`.
28
+ */
29
+ /** A named place on one of the scene's surfaces (`surfaces[surface].anchor(anchor)`). */
30
+ export interface SurfaceRef {
31
+ surface: string;
32
+ anchor: string;
33
+ }
34
+ /** A moment of a beat: when it starts, when it touches its target, when it lets go, when it ends. */
35
+ export type BeatMoment = 'start' | 'contact' | 'release' | 'end';
36
+ export declare const BEAT_MOMENTS: readonly BeatMoment[];
37
+ /** A moment of this beat, or of a later one (`beat` is its index in the script). */
38
+ export type CueTime = BeatMoment | {
39
+ beat: number;
40
+ at?: BeatMoment;
41
+ };
42
+ /**
43
+ * What a surface does in answer to a beat: one of its edits (or `carry`),
44
+ * at one of its places. Every other field is the edit's own options (`text`,
45
+ * `into`, `to`, `style`…). Its time is a moment of the beat, not ms.
46
+ */
47
+ export interface SurfaceCue {
48
+ surface: string;
49
+ /** One of the surface's edits, or `carry`: the piece at `anchor` follows the hand from `at` to `until` */
50
+ edit: string;
51
+ anchor: string | string[];
52
+ /** When it starts: a moment of the beat (default its contact, or its start when it has none) */
53
+ at?: BeatMoment;
54
+ /** When it ends: sets the edit's duration (`carry` needs it) */
55
+ until?: CueTime;
56
+ [option: string]: unknown;
57
+ }
58
+ /** A beat whose places can be named on a surface, and that a surface can answer. */
59
+ export interface SurfaceBeat extends Omit<Beat, 'target' | 'to' | 'onto'> {
60
+ /** What it acts on: a point or box, or a named place */
61
+ target?: BeatTarget | SurfaceRef;
62
+ /** Walking: where to, scene x, or a named place (its centre x) */
63
+ to?: number | SurfaceRef;
64
+ /** The floor it ends the beat on, scene y, or a named place (its top) */
65
+ onto?: number | SurfaceRef;
66
+ /** What the surfaces do in answer */
67
+ then?: SurfaceCue | SurfaceCue[];
68
+ }
69
+ export interface SurfaceScriptOptions extends ScriptOptions {
70
+ /** How the figure is drawn, for a `carry` to follow its hand (default: just its `height`) */
71
+ figureStyle?: StickStyle;
72
+ /** Carry the figure on the surfaces it stands on (default true) */
73
+ ride?: boolean;
74
+ }
75
+ export interface SurfaceScriptResult extends ScriptResult {
76
+ /** The figure's tracks (ridden), then every surface's tracks, keyed by its name in `surfaces` */
77
+ tracks: Track[];
78
+ /** Just the figure's tracks (ridden) */
79
+ figureTracks: Track[];
80
+ }
81
+ /**
82
+ * Compile beats that act on surfaces into the figure's tracks and the
83
+ * surfaces' edits. Throws when a beat or a cue is wrong (see
84
+ * `checkSurfaceBeats`), naming the beat.
85
+ */
86
+ export declare function surfaceScript(figure: string, surfaces: Record<string, Surface>, beats: SurfaceBeat[], options?: SurfaceScriptOptions): SurfaceScriptResult;
87
+ /**
88
+ * Problems in beats that act on surfaces: everything `checkBeats` finds,
89
+ * plus surfaces, places, edits and moments that do not exist (with the
90
+ * likely intended name). Errors make `surfaceScript` throw.
91
+ */
92
+ export declare function checkSurfaceBeats(beats: unknown, surfaces: Record<string, Surface>, cast?: Cast): BeatProblem[];
@@ -1,4 +1,5 @@
1
1
  import { type PropertyInfo } from '../adapters/canvas/target-properties';
2
+ import type { SurfaceAbout } from './surface/surface';
2
3
  import type { Cast } from './acting/custom';
3
4
  export interface Capabilities {
4
5
  version?: string;
@@ -61,6 +62,21 @@ export interface Capabilities {
61
62
  poses: string[];
62
63
  expressions: string[];
63
64
  gags: string[];
65
+ /** `build` option */
66
+ builds: string[];
67
+ /** `hair` option (`{ style, color, length, … }` changes any field) */
68
+ hair: string[];
69
+ hairColors: Record<string, string>;
70
+ /** `facialHair` option */
71
+ facialHair: string[];
72
+ glasses: string[];
73
+ hats: string[];
74
+ /** `castMember(name, height)` */
75
+ cast: string[];
76
+ /** `holding: { left | right | both: item }`, and which hands each takes */
77
+ heldItems: Record<string, string>;
78
+ /** `meetHands(kind, a, b)` */
79
+ handMeetings: string[];
64
80
  };
65
81
  codePanel: {
66
82
  languages: readonly string[];
@@ -68,6 +84,10 @@ export interface Capabilities {
68
84
  anchors: Record<string, string>;
69
85
  edits: Record<string, string>;
70
86
  };
87
+ /** Surfaces figures act on, by kind: their named anchors and edits (`surface.anchor(name)`, `surface.edit(name, anchor, options)`) */
88
+ surfaces: Record<string, SurfaceAbout>;
89
+ /** Beats that act on surfaces (`surfaceScript`): named places and the cues surfaces answer with */
90
+ surfaceScript: Record<string, string>;
71
91
  cameraShots: Record<string, string>;
72
92
  teach: Record<string, string>;
73
93
  cli: Record<string, string>;
@@ -0,0 +1,284 @@
1
+ import type { CharacterOptions } from './character';
2
+ /**
3
+ * A ready-made recurring cast: a family of characters a viewer can tell
4
+ * apart at a glance, by build, hair, facial hair, glasses and clothes. Each
5
+ * member is plain character options (no height: `scale` is how tall they
6
+ * stand next to an adult), so it can be saved, changed field by field, or
7
+ * given any pose, expression or action.
8
+ *
9
+ * These are starting points from the age-and-cast reference sheet, not rules:
10
+ * any hairstyle, build or outfit suits anyone, and age is shown by hair and
11
+ * proportions, never by a stoop or a walking aid unless one is chosen.
12
+ */
13
+ export interface CastMember {
14
+ /** What to call them in a picker */
15
+ label: string;
16
+ /** `family` (ages and looks) or `work` (dressed for a job, from the occupations sheet) */
17
+ group: 'family' | 'work';
18
+ /** Height next to an adult (1) */
19
+ scale: number;
20
+ /** Everything else about them */
21
+ options: Omit<CharacterOptions, 'height'>;
22
+ }
23
+ export declare const CHARACTER_CAST: {
24
+ boy: {
25
+ label: string;
26
+ group: "family";
27
+ scale: number;
28
+ options: {
29
+ build: "child";
30
+ hair: "short";
31
+ ears: true;
32
+ outfit: {
33
+ shirt: string;
34
+ trousers: string;
35
+ bottom: "shorts";
36
+ };
37
+ };
38
+ };
39
+ girl: {
40
+ label: string;
41
+ group: "family";
42
+ scale: number;
43
+ options: {
44
+ build: "child";
45
+ hair: {
46
+ style: "bob";
47
+ color: "#7b4a2b";
48
+ };
49
+ ears: true;
50
+ outfit: {
51
+ shirt: string;
52
+ trousers: string;
53
+ bottom: "skirt";
54
+ };
55
+ };
56
+ };
57
+ youngMan: {
58
+ label: string;
59
+ group: "family";
60
+ scale: number;
61
+ options: {
62
+ build: "tall";
63
+ hair: "spiky";
64
+ ears: true;
65
+ outfit: {
66
+ shirt: string;
67
+ trousers: string;
68
+ };
69
+ };
70
+ };
71
+ youngWoman: {
72
+ label: string;
73
+ group: "family";
74
+ scale: number;
75
+ options: {
76
+ build: "slim";
77
+ hair: {
78
+ style: "highPonytail";
79
+ color: "#9a4426";
80
+ };
81
+ ears: true;
82
+ outfit: {
83
+ shirt: string;
84
+ trousers: string;
85
+ };
86
+ };
87
+ };
88
+ man: {
89
+ label: string;
90
+ group: "family";
91
+ scale: number;
92
+ options: {
93
+ build: "broad";
94
+ hair: "sidePart";
95
+ facialHair: "chevron";
96
+ ears: true;
97
+ outfit: {
98
+ shirt: string;
99
+ trousers: string;
100
+ sleeves: "long";
101
+ collar: true;
102
+ tie: string;
103
+ };
104
+ };
105
+ };
106
+ woman: {
107
+ label: string;
108
+ group: "family";
109
+ scale: number;
110
+ options: {
111
+ build: "curvy";
112
+ hair: {
113
+ style: "shoulderWaves";
114
+ color: "#22201f";
115
+ };
116
+ ears: true;
117
+ outfit: {
118
+ shirt: string;
119
+ trousers: string;
120
+ sleeves: "long";
121
+ };
122
+ };
123
+ };
124
+ grandpa: {
125
+ label: string;
126
+ group: "family";
127
+ scale: number;
128
+ options: {
129
+ build: "stocky";
130
+ hair: {
131
+ style: "receding";
132
+ color: "#a7a29c";
133
+ };
134
+ facialHair: {
135
+ style: "shortBoxed";
136
+ color: "#ecebe7";
137
+ };
138
+ glasses: "square";
139
+ ears: true;
140
+ outfit: {
141
+ shirt: string;
142
+ trousers: string;
143
+ sleeves: "long";
144
+ collar: true;
145
+ };
146
+ };
147
+ };
148
+ grandma: {
149
+ label: string;
150
+ group: "family";
151
+ scale: number;
152
+ options: {
153
+ build: "short";
154
+ hair: {
155
+ style: "topBun";
156
+ color: "#ecebe7";
157
+ };
158
+ glasses: "round";
159
+ ears: true;
160
+ outfit: {
161
+ shirt: string;
162
+ trousers: string;
163
+ sleeves: "long";
164
+ bottom: "skirt";
165
+ };
166
+ };
167
+ };
168
+ doctor: {
169
+ label: string;
170
+ group: "work";
171
+ scale: number;
172
+ options: {
173
+ build: "slim";
174
+ hair: {
175
+ style: "lowPonytail";
176
+ color: "#22201f";
177
+ };
178
+ ears: true;
179
+ outfit: {
180
+ shirt: string;
181
+ trousers: string;
182
+ over: "labCoat";
183
+ collar: true;
184
+ };
185
+ };
186
+ };
187
+ cook: {
188
+ label: string;
189
+ group: "work";
190
+ scale: number;
191
+ options: {
192
+ build: "stocky";
193
+ hair: "crewCut";
194
+ facialHair: "shortMoustache";
195
+ ears: true;
196
+ outfit: {
197
+ shirt: string;
198
+ trousers: string;
199
+ sleeves: "long";
200
+ over: "apron";
201
+ overColor: string;
202
+ };
203
+ };
204
+ };
205
+ builder: {
206
+ label: string;
207
+ group: "work";
208
+ scale: number;
209
+ options: {
210
+ build: "broad";
211
+ hair: "short";
212
+ facialHair: "stubble";
213
+ hat: "hardHat";
214
+ ears: true;
215
+ outfit: {
216
+ shirt: string;
217
+ trousers: string;
218
+ };
219
+ };
220
+ };
221
+ courier: {
222
+ label: string;
223
+ group: "work";
224
+ scale: number;
225
+ options: {
226
+ build: "standard";
227
+ hair: "short";
228
+ hat: {
229
+ style: "cap";
230
+ color: string;
231
+ };
232
+ ears: true;
233
+ outfit: {
234
+ shirt: string;
235
+ trousers: string;
236
+ bottom: "shorts";
237
+ };
238
+ };
239
+ };
240
+ teacher: {
241
+ label: string;
242
+ group: "work";
243
+ scale: number;
244
+ options: {
245
+ build: "tall";
246
+ hair: "slickBack";
247
+ glasses: "square";
248
+ ears: true;
249
+ outfit: {
250
+ shirt: string;
251
+ trousers: string;
252
+ sleeves: "long";
253
+ collar: true;
254
+ tie: string;
255
+ };
256
+ };
257
+ };
258
+ farmer: {
259
+ label: string;
260
+ group: "work";
261
+ scale: number;
262
+ options: {
263
+ build: "stocky";
264
+ hair: {
265
+ style: "shoulderStraight";
266
+ color: "#d9b55a";
267
+ };
268
+ hat: "sunHat";
269
+ ears: true;
270
+ outfit: {
271
+ shirt: string;
272
+ trousers: string;
273
+ sleeves: "long";
274
+ };
275
+ };
276
+ };
277
+ };
278
+ export type CastName = keyof typeof CHARACTER_CAST;
279
+ /**
280
+ * Character options for a cast member at an adult `height` (px; they stand
281
+ * at their own scale of it), with any options changed: `castMember('grandpa',
282
+ * 300, { look: 'pencil' })`.
283
+ */
284
+ export declare function castMember(name: CastName, height?: number, changes?: Partial<CharacterOptions>): CharacterOptions;
@@ -5,7 +5,10 @@ import type { FrameInfo } from '../headless/video-scene';
5
5
  import type { BodyPlan, Pose, Vec3 } from './rig/body-plan';
6
6
  import { type SolvedHead, type ViewProjection } from './rig/skeleton';
7
7
  import { type Look, type Pen, type PencilOptions } from './look/pen';
8
- import { type HumanPoseName } from './species/human';
8
+ import { type HeadLook, type HeadLookOptions } from './head/head-look';
9
+ import { type HumanBuildName, type HumanPoseName } from './species/human';
10
+ import { type BasicOutfitOptions } from './wardrobe/basic-outfit';
11
+ import { type Holding, type HoldingSpec } from './hands/held-items';
9
12
  import { type HandPose } from './hands/hand-rig';
10
13
  /**
11
14
  * Characters (v2): any body plan, posed by numbers, turned in 3D, drawn flat
@@ -19,9 +22,10 @@ export type FigureStyle = 'fluid' | 'stick';
19
22
  /**
20
23
  * Draws part of a character: clothes, hair, a prop. The context is in the
21
24
  * character's drawing space (feet at 0, 0), saved and restored around the
22
- * call. Draw with `pen` so it matches the look.
25
+ * call. Draw with `pen` so it matches the look. `pose` is the full pose being
26
+ * drawn (for a layer that a pose field switches, like a held item's `held.*`).
23
27
  */
24
- export type CharacterLayer = (ctx: CanvasRenderingContext2D, joints: CharacterJoints, pen: Pen, time: number) => void;
28
+ export type CharacterLayer = (ctx: CanvasRenderingContext2D, joints: CharacterJoints, pen: Pen, time: number, pose?: Pose) => void;
25
29
  export interface CharacterLayers {
26
30
  /** Before anything (a shadow, a cape) */
27
31
  behind?: CharacterLayer;
@@ -33,9 +37,19 @@ export interface CharacterLayers {
33
37
  /** After everything (a prop in front) */
34
38
  front?: CharacterLayer;
35
39
  }
36
- export interface CharacterOptions {
40
+ export interface CharacterOptions extends HeadLookOptions {
37
41
  /** Body plan (default: human, built from the options below) */
38
42
  plan?: BodyPlan;
43
+ /** A named build (`child`, `tall`, `broad`…; see HUMAN_BUILDS): its proportions, unless the options below set them */
44
+ build?: HumanBuildName;
45
+ /** Leg length, as a share of the standard (default 1) */
46
+ legLength?: number;
47
+ /** Arm length, as a share of the standard (default 1) */
48
+ armLength?: number;
49
+ /** A T-shirt and trousers in these colours (see basicOutfit), as data; drawn under any `layers` */
50
+ outfit?: BasicOutfitOptions | null;
51
+ /** What each hand holds (`{ right: 'mug' }`, `{ both: 'parcel' }`); a pose field `held.<side>` below 0.5 lets go */
52
+ holding?: HoldingSpec | null;
39
53
  figure?: FigureStyle;
40
54
  look?: Look;
41
55
  /** Feet to top of head, px (default 300) */
@@ -92,6 +106,10 @@ export interface Character {
92
106
  hands: 'dot' | 'cartoon';
93
107
  handStyle: 'glove' | 'natural';
94
108
  handSize: number;
109
+ /** Hair, facial hair, glasses, a hat and ears: every choice spelled out, so a saved character never changes when a preset does */
110
+ head: HeadLook;
111
+ /** What each hand holds (drawn by its layers) */
112
+ holding: Holding;
95
113
  }
96
114
  export declare function character(options?: CharacterOptions): Character;
97
115
  /** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
@@ -0,0 +1,108 @@
1
+ import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
2
+ import type { Track } from '../engine/types';
3
+ import { type EditOptions } from './surface/edit-log';
4
+ import { type FlingOptions, type SurfacePiece, type TimedPoint } from './surface/pieces';
5
+ import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from './surface/surface';
6
+ import { type SurfaceBox } from './surface/surface-box';
7
+ /**
8
+ * A bar or line chart as a scene object figures act on: they point at a
9
+ * bar, highlight the dip, and stand on a bar as it grows.
10
+ *
11
+ * ```ts
12
+ * const sales = chart({
13
+ * x: 40, y: 30, width: 420, height: 280, kind: 'bar', title: 'Sales',
14
+ * data: [
15
+ * { id: 'q1', label: 'Q1', value: 40 },
16
+ * { id: 'q2', label: 'Q2', value: 25 },
17
+ * { id: 'q3', label: 'Q3', value: 55, hidden: true },
18
+ * ],
19
+ * })
20
+ * sales.edit('highlight', 'bar:q2', { at: 600 })
21
+ * sales.edit('show', 'bar:q3', { at: 1200 }) // grows in from the axis
22
+ * sales.edit('set', 'bar:q1', { at: 2000, value: 80 }) // and its value label counts up
23
+ * ```
24
+ *
25
+ * The data is declared up front; the scale (`max`) is fixed when it is made
26
+ * (from the data, or given), so a bar set past it grows out of the plot.
27
+ * Its places follow the values: `anchor('bar:q1', time)` is the bar as it
28
+ * stands at `time` (default: after every edit; a surface script aims beats
29
+ * at it as laid out). A figure standing on a bar's top is carried up and
30
+ * down with it (`ride()`). Edits are keys on its props: `bar.ID.value`,
31
+ * `bar.ID.show`, `bar.ID.highlight` (or `point.ID.…` on a line chart).
32
+ */
33
+ export type ChartKind = 'bar' | 'line';
34
+ export declare const CHART_KINDS: readonly ChartKind[];
35
+ export type ChartThemeName = 'light' | 'dark';
36
+ export interface ChartTheme {
37
+ background: string;
38
+ text: string;
39
+ /** Axis and grid lines */
40
+ grid: string;
41
+ /** Bars, the line and its points */
42
+ color: string;
43
+ /** A highlighted bar or point */
44
+ highlight: string;
45
+ font: string;
46
+ }
47
+ export declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
48
+ /** One bar or point. */
49
+ export interface ChartDatum {
50
+ id: string;
51
+ /** Under it, on the axis (default its id) */
52
+ label?: string;
53
+ value: number;
54
+ /** Start at nothing: a bar flat on the axis, a point the line has not reached; brought in with `show` */
55
+ hidden?: boolean;
56
+ }
57
+ export interface ChartOptions {
58
+ /** Top-left corner, scene px */
59
+ x: number;
60
+ y: number;
61
+ width: number;
62
+ height: number;
63
+ kind: ChartKind;
64
+ data: ChartDatum[];
65
+ /** The value at the top of the plot (default: a round number above the largest value) */
66
+ max?: number;
67
+ title?: string;
68
+ theme?: ChartThemeName | Partial<ChartTheme>;
69
+ /** Value labels: decimal places (default 0), and text before and after the number */
70
+ decimals?: number;
71
+ prefix?: string;
72
+ suffix?: string;
73
+ /** Show each value above its bar or point (default true) */
74
+ values?: boolean;
75
+ }
76
+ export interface Chart extends Surface {
77
+ readonly kind: 'chart';
78
+ readonly chartKind: ChartKind;
79
+ readonly target: CustomTarget;
80
+ readonly box: SurfaceBox;
81
+ /** The value at the top of the plot */
82
+ readonly max: number;
83
+ /** The box at a named place, as it stands at `time`: `box`, `bar:ID` or `point:ID`, `label:ID`, `value:ID` */
84
+ anchor(name: string, time?: number): SurfaceBox;
85
+ /** A chart has no pieces: this throws */
86
+ piece(anchor: string): SurfacePiece;
87
+ /** Change the chart at a time by name, at named places (see `CHART_SURFACE.edits`) */
88
+ edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Chart;
89
+ follow(piece: SurfacePiece, path: TimedPoint[]): Chart;
90
+ fling(piece: SurfacePiece, options: FlingOptions): Chart;
91
+ move(piece: SurfacePiece, options: EditOptions & {
92
+ to: {
93
+ x: number;
94
+ y: number;
95
+ };
96
+ }): Chart;
97
+ /** A figure's tracks with it carried up and down by the bar it stands on */
98
+ ride(tracks: Track[], target: string, options: {
99
+ ground: number;
100
+ every?: number;
101
+ }): Track[];
102
+ tracks(target: string): Track[];
103
+ }
104
+ /** A chart's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
105
+ export declare const CHART_SURFACE: SurfaceAbout;
106
+ export declare function chart(options: ChartOptions): Chart;
107
+ /** The smallest of 1, 2, 2.5, 5 × a power of ten at or above `value`. */
108
+ export declare function niceCeiling(value: number): number;
@@ -1,5 +1,9 @@
1
1
  import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
2
- import type { EasingType, Track } from '../engine/types';
2
+ import type { Track } from '../engine/types';
3
+ import { type EditOptions } from './surface/edit-log';
4
+ import { type FlingOptions, type SurfacePiece, type TimedPoint } from './surface/pieces';
5
+ import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from './surface/surface';
6
+ import { type SurfaceBox } from './surface/surface-box';
3
7
  /**
4
8
  * A code listing as a scene object characters can act on: they stand on its
5
9
  * lines, point at its tokens and swipe lines away.
@@ -66,23 +70,9 @@ export interface CodePanelOptions {
66
70
  theme?: Partial<CodeTheme>;
67
71
  }
68
72
  /** A place on the panel, scene px. Stand on `top`; point at `x`, `y` (the centre). */
69
- export interface CodeBox {
70
- x: number;
71
- y: number;
72
- left: number;
73
- right: number;
74
- top: number;
75
- bottom: number;
76
- width: number;
77
- height: number;
78
- }
79
- export interface CodeEditOptions {
80
- /** When the edit starts, ms */
81
- at: number;
82
- /** ms (default 300) */
83
- duration?: number;
84
- easing?: EasingType;
85
- }
73
+ export type CodeBox = SurfaceBox;
74
+ export type CodeEditOptions = EditOptions;
75
+ export type { TimedPoint };
86
76
  /** How a removed line goes: wiped away, knocked off the panel, or out of focus. */
87
77
  export type CodeRemoveStyle = 'wipe' | 'fly' | 'blur';
88
78
  export declare const REMOVE_STYLES: readonly CodeRemoveStyle[];
@@ -94,38 +84,15 @@ export interface CodeRemoveOptions extends CodeEditOptions {
94
84
  /** How long the lines below take to close the gap, ms (default 250) */
95
85
  close?: number;
96
86
  }
97
- /** A word that can come loose from its line: made by `piece()`. */
98
- export interface CodePiece {
99
- /** Its key in the panel's props (`piece.K.x`…) */
100
- readonly id: number;
87
+ /** A word that can come loose from its line: made by `piece()`. Its `home` is where it sits in its line. */
88
+ export interface CodePiece extends SurfacePiece {
101
89
  readonly line: number;
102
90
  readonly column: number;
103
91
  readonly text: string;
104
- /** Where it sits in its line */
105
- readonly home: CodeBox;
106
- }
107
- /** A point at a time, scene px: a path for a piece to follow (see `handPath`). */
108
- export interface TimedPoint {
109
- time: number;
110
- x: number;
111
- y: number;
112
- }
113
- export interface CodeFlingOptions {
114
- /** When it leaves, ms */
115
- at: number;
116
- /** px/ms (default: how fast it was moving along its `follow` path at `at`, or up and to the right) */
117
- velocity?: {
118
- x: number;
119
- y: number;
120
- };
121
- /** Turns, degrees per ms (default 0.6, signed by the throw's direction) */
122
- spin?: number;
123
- /** px/ms² (default 0.0016) */
124
- gravity?: number;
125
- /** How long it flies before it is gone, ms (default 900) */
126
- duration?: number;
127
92
  }
128
- export interface CodePanel {
93
+ export type CodeFlingOptions = FlingOptions;
94
+ export interface CodePanel extends Surface {
95
+ readonly kind: 'code';
129
96
  /** The canvas target that draws the panel; put it in the scene's targets */
130
97
  readonly target: CustomTarget;
131
98
  readonly lines: readonly string[];
@@ -147,6 +114,12 @@ export interface CodePanel {
147
114
  type(n: number, options: CodeEditOptions): CodePanel;
148
115
  /** Make the `occurrence`th `text` on line `n` a piece that can come loose */
149
116
  piece(n: number, text: string, occurrence?: number): CodePiece;
117
+ /** Make the word at a token anchor (`token:7:Println`) a piece that can come loose */
118
+ piece(anchor: string): CodePiece;
119
+ /** The box at a named place: `box`, `line:N`, `token:N:TEXT` (`token:N#K:TEXT` for the Kth), `spot:N:C` or `spot:N:C:W` */
120
+ anchor(name: string, time?: number): CodeBox;
121
+ /** Change the panel at a time by name, at named places (see `CODE_SURFACE.edits`): `edit('highlight', 'line:4', { at: 1200 })` */
122
+ edit(name: string, anchor: string | string[], options: SurfaceEditOptions): CodePanel;
150
123
  /** Carry a piece along a path of scene points (its centre follows them) */
151
124
  follow(piece: CodePiece, path: TimedPoint[]): CodePanel;
152
125
  /** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
@@ -188,6 +161,8 @@ export interface CodePanel {
188
161
  /** The recorded edits as tracks on `target` (the panel's key in the scene) */
189
162
  tracks(target: string): Track[];
190
163
  }
164
+ /** A code panel's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
165
+ export declare const CODE_SURFACE: SurfaceAbout;
191
166
  export declare function codePanel(options: CodePanelOptions): CodePanel;
192
167
  /** What a code panel's methods do, for its `about` and the capability catalog. */
193
168
  export declare const CODE_PANEL_EDITS: Record<string, string>;