@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
@@ -0,0 +1,64 @@
1
+ import type { Point } from '../../adapters/canvas/sketch';
2
+ import type { Vec3 } from '../rig/body-plan';
3
+ import { type SolvedHead } from '../rig/skeleton';
4
+ /**
5
+ * Regions on and around the head: hair, a beard, a hat's crown. A region is
6
+ * described in the head's own terms and drawn wherever the head's turn, nod
7
+ * and tilt put it, so it turns with the head through every view instead of
8
+ * being a flat drawing pasted on.
9
+ *
10
+ * A point on the head is named by two numbers:
11
+ * - `around`: radians around the head from the middle of the face, toward the
12
+ * character's left +, so ±π is the back of the head;
13
+ * - `up`: head radii from the head's centre, +1 the crown, -1 under the chin
14
+ * (below -1 only for things that hang, like long hair or a long beard).
15
+ *
16
+ * The region says where it is (`inside`, positive inside) and where each of
17
+ * its points sits (`position`, in head radii: x toward the character's left,
18
+ * y up, z forward). It is cut into the part facing the viewer and the part
19
+ * facing away; each part's outline is traced (marching squares over a grid
20
+ * of `around` × `up`) and projected to the screen. The far part is drawn
21
+ * before the head and the near part after it, so a bob shows beside the face
22
+ * and its fringe crosses the forehead, and from behind the hair covers the
23
+ * whole head. Same input, same outline: no randomness, no state.
24
+ */
25
+ export interface ShellRegion {
26
+ /** Positive inside the region, negative outside; continuous across the boundary */
27
+ inside(around: number, up: number): number;
28
+ /** Where a point of the region is, head radii (x toward its left, y up, z forward) */
29
+ position(around: number, up: number): Vec3;
30
+ /** Which way the surface faces there (default: away from the head's centre) */
31
+ normal?(around: number, up: number): Vec3;
32
+ /** Highest `up` the region reaches (default 1, the crown) */
33
+ top?: number;
34
+ /** Lowest `up` the region reaches (default -1, under the chin) */
35
+ bottom?: number;
36
+ }
37
+ /** The two halves of a region as seen: outlines on the screen. */
38
+ export interface ShellOutlines {
39
+ /** The part facing the viewer: drawn over the head */
40
+ near: Point[][];
41
+ /** The part facing away: drawn behind the head */
42
+ far: Point[][];
43
+ }
44
+ /** A point on the unit sphere from `around` and `up`. */
45
+ export declare function spherePoint(around: number, up: number): Vec3;
46
+ /** How directly a head-space direction faces the viewer: 1 straight on, 0 at the edge, negative away. */
47
+ export declare function facingOf(head: SolvedHead, [x, y, z]: Vec3): number;
48
+ /** A head-space point (head radii) on the screen. */
49
+ export declare function onScreen(head: SolvedHead, point: Vec3): Point;
50
+ /** Smallest angle between two `around` values. */
51
+ export declare function aroundDistance(a: number, b: number): number;
52
+ /**
53
+ * Trace the outlines of a region's near and far parts, on the screen.
54
+ * `columns` around the head: more for fine texture (spikes, curls).
55
+ */
56
+ export declare function shellOutlines(head: SolvedHead, region: ShellRegion, columns?: number): ShellOutlines;
57
+ export declare function cachedOutlines(head: SolvedHead, key: unknown, make: () => ShellOutlines): ShellOutlines;
58
+ /**
59
+ * Run `draw` with the head's disc cut out of the canvas, for things behind
60
+ * the head: they show only around it, even when the head is see-through.
61
+ */
62
+ export declare function behindHead(ctx: CanvasRenderingContext2D, head: SolvedHead, draw: () => void): void;
63
+ /** Split a head-space polyline into the runs that face the viewer, on the screen. */
64
+ export declare function visibleRuns(head: SolvedHead, points: Vec3[], normals: Vec3[], threshold?: number): Point[][];
@@ -17,14 +17,20 @@ export * from '../adapters/canvas/sketch';
17
17
  export * from '../adapters/canvas/camera';
18
18
  export * from './erase';
19
19
  export * from './code-panel';
20
+ export * from './whiteboard';
21
+ export * from './chart';
22
+ export * from './surface';
20
23
  export * from '../adapters/canvas/polyline';
21
24
  export * from './hand';
22
25
  export * from './character';
23
- export { humanPlan, humanPose, mirrorHumanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, type HumanBuild, type HumanPoseName } from './species/human';
26
+ export { humanPlan, humanPose, mirrorHumanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, HUMAN_BUILDS, type HumanBuild, type HumanBuildName, type HumanPoseName, type HumanExpressionName } from './species/human';
27
+ export { CHARACTER_CAST, castMember, type CastMember, type CastName } from './cast';
28
+ export { meetHands, meetingSpacing, HAND_MEETINGS, type HandMeeting, type HandsMeet, type MeetingPartner, type MeetHandsOptions } from './interactions';
24
29
  export * from './species/human-motion';
25
30
  export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec, Pose as CharacterPose, Vec3 } from './rig/body-plan';
26
31
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
27
32
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
33
+ export * from './head';
28
34
  export * from './hands';
29
35
  export * from './acting';
30
36
  export * from './capabilities';
@@ -0,0 +1,69 @@
1
+ import { type Character } from './character';
2
+ import type { Pose } from './rig/body-plan';
3
+ /**
4
+ * Two characters whose hands meet: a handshake, a high five, a fist bump, or
5
+ * a parcel handed from one to the other. Rather than playing two clips and
6
+ * hoping the hands line up, both arms reach (exactly, see `reachCharacter`)
7
+ * for one shared point, worked out from where the two stand and how tall
8
+ * they are. The result is two poses and the point, plain data to key as
9
+ * tracks; any field of the poses can still be changed.
10
+ *
11
+ * Both stand on the same ground line, `a` on the left facing right and `b`
12
+ * on the right facing left, turned three-quarters toward the viewer (or side
13
+ * on, with `view: 'side'`). Hands are the characters' right hands (a hand
14
+ * over uses both).
15
+ */
16
+ export type HandMeeting = 'handshake' | 'highFive' | 'fistBump' | 'handOver';
17
+ export interface MeetingPartner {
18
+ character: Character;
19
+ /** Starting pose (default rest); its arms are replaced, the rest kept */
20
+ pose?: Pose;
21
+ /** Scene x of the feet */
22
+ x: number;
23
+ }
24
+ export interface MeetHandsOptions {
25
+ /** `threeQuarter` (default): turned toward the viewer as well as each other; `side`: in profile */
26
+ view?: 'threeQuarter' | 'side';
27
+ /** Where the hands meet, as a share of the shorter one's height above the ground (default by kind) */
28
+ height?: number;
29
+ }
30
+ export interface HandsMeet {
31
+ a: Pose;
32
+ b: Pose;
33
+ /** Where the hands meet: scene x, and px above the ground (negative y, as drawing space) */
34
+ point: {
35
+ x: number;
36
+ y: number;
37
+ };
38
+ /** Both reached it (they stand close enough; see `meetingSpacing`) */
39
+ reached: boolean;
40
+ }
41
+ /**
42
+ * Each kind: how high the hands meet and how far apart the two stand for
43
+ * it (both as a share of the shorter one's height), and how far they lean in.
44
+ */
45
+ export declare const HAND_MEETINGS: {
46
+ handshake: {
47
+ height: number;
48
+ spacing: number;
49
+ lean: number;
50
+ };
51
+ highFive: {
52
+ height: number;
53
+ spacing: number;
54
+ lean: number;
55
+ };
56
+ fistBump: {
57
+ height: number;
58
+ spacing: number;
59
+ lean: number;
60
+ };
61
+ handOver: {
62
+ height: number;
63
+ spacing: number;
64
+ lean: number;
65
+ };
66
+ };
67
+ /** How far apart (px, feet to feet) two characters stand for their hands to meet comfortably. */
68
+ export declare function meetingSpacing(kind: HandMeeting, a: Character, b: Character): number;
69
+ export declare function meetHands(kind: HandMeeting, a: MeetingPartner, b: MeetingPartner, options?: MeetHandsOptions): HandsMeet;
@@ -139,6 +139,12 @@ export declare function sittingPose(h: Pick<QuadrupedHelpers, 'upper' | 'lower'
139
139
  export declare const QUADRUPED_ACTING: ActingRig;
140
140
  /** Kept for the horse's name. */
141
141
  export declare const HORSE_ACTING: ActingRig;
142
+ /**
143
+ * Lying down with the head up (a sphinx pose): the body lowered until the
144
+ * folded hind legs and the belly are on the ground, the front legs stretched
145
+ * forward along it, paws flat.
146
+ */
147
+ export declare function lyingPose(h: Pick<QuadrupedHelpers, 'upper' | 'lower' | 'foot' | 'legLength' | 'tailHangs'>): Record<string, number>;
142
148
  export interface AnimalOptions {
143
149
  kind?: string;
144
150
  summary?: string;
@@ -21,3 +21,4 @@ export * from './presets';
21
21
  export * from './scene-objects';
22
22
  export * from './script-3d';
23
23
  export * from './ride-3d';
24
+ export * from './prop-surface';
@@ -0,0 +1,63 @@
1
+ import type { Track } from '../../engine/types';
2
+ import { type EditOptions } from '../surface/edit-log';
3
+ import { type FlingOptions, type SurfacePiece, type TimedPoint } from '../surface/pieces';
4
+ import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from '../surface/surface';
5
+ import { type SurfaceBox } from '../surface/surface-box';
6
+ import { type PropTarget } from './target';
7
+ /**
8
+ * A prop as a surface: its state is something a figure changes. A figure
9
+ * opens the car's door, switches the house's lights on, shakes the tree.
10
+ *
11
+ * ```ts
12
+ * const car = propTarget({ x: 300, y: 380, prop: carPreset() })
13
+ * const carSurface = propSurface(car)
14
+ * carSurface.anchor('control:door') // where the door is
15
+ * carSurface.edit('switch', 'control:door', { at: 1200 }) // opens it
16
+ * carSurface.edit('switch', 'control:lights', { at: 2000, on: false })
17
+ *
18
+ * surfaceScript('hero', { car: carSurface }, [
19
+ * { do: 'grab', target: { surface: 'car', anchor: 'control:door' },
20
+ * then: { surface: 'car', edit: 'switch', anchor: 'control:door', until: 'end' } },
21
+ * ])
22
+ * ```
23
+ *
24
+ * Its places: `anchor:NAME` (one of the rig's anchors, as posed),
25
+ * `part:ID` (one of its parts, as seen: `window-1`, `wheel-0-left`),
26
+ * `control:NAME` (where the parts that control moves or lights are), and
27
+ * `box`. They are worked out at a time from the prop's values then: its
28
+ * starting values, the edits made here, and the prop's own tracks when it is
29
+ * scripted too (`tracks`, from its `propScript`), so the places follow a car
30
+ * that drives off. Edits are keys on its controls, written out by `tracks()`
31
+ * on the prop target's id. Do not key a control both here and in its own
32
+ * script: the later track wins.
33
+ */
34
+ export interface PropSurfaceOptions {
35
+ /** The prop's own tracks (its `propScript` result), so its places follow it as it moves */
36
+ tracks?: Track[];
37
+ }
38
+ export interface PropSurface extends Surface {
39
+ readonly kind: 'prop';
40
+ readonly prop: PropTarget;
41
+ /** The box at a named place, at `time` (default: after every edit): `box`, `anchor:NAME`, `part:ID`, `control:NAME` */
42
+ anchor(name: string, time?: number): SurfaceBox;
43
+ /** A prop has no pieces: this throws */
44
+ piece(anchor: string): SurfacePiece;
45
+ /** Change the prop at a time: `set` a control to a value, or `switch` it on (open) or off (shut) */
46
+ edit(name: string, anchor: string | string[], options: SurfaceEditOptions): PropSurface;
47
+ follow(piece: SurfacePiece, path: TimedPoint[]): PropSurface;
48
+ fling(piece: SurfacePiece, options: FlingOptions): PropSurface;
49
+ move(piece: SurfacePiece, options: EditOptions & {
50
+ to: {
51
+ x: number;
52
+ y: number;
53
+ };
54
+ }): PropSurface;
55
+ /** Nothing on a prop carries a figure yet: the tracks come back as they are */
56
+ ride(tracks: Track[], target: string, options: {
57
+ ground: number;
58
+ every?: number;
59
+ }): Track[];
60
+ tracks(target: string): Track[];
61
+ }
62
+ export declare const PROP_SURFACE: SurfaceAbout;
63
+ export declare function propSurface(target: PropTarget, options?: PropSurfaceOptions): PropSurface;
@@ -8,8 +8,11 @@ import { type Gait, type GaitName } from '../gaits';
8
8
  * `base`'s. `stride` scales the swing.
9
9
  */
10
10
  export declare function humanGaitPose(gait: GaitName | Gait | string | undefined, phase: number, base?: Pose, stride?: number): Pose;
11
- /** Ground covered by one gait cycle (two steps) for a character `height` px tall: the feet stay planted. */
12
- export declare function humanGaitStrideLength(gait: GaitName | Gait | string | undefined, height: number, stride?: number): number;
11
+ /**
12
+ * Ground covered by one gait cycle (two steps) for a character `height` px
13
+ * tall: the feet stay planted. `legLength` is the build's (see HUMAN_BUILDS).
14
+ */
15
+ export declare function humanGaitStrideLength(gait: GaitName | Gait | string | undefined, height: number, stride?: number, legLength?: number): number;
13
16
  /** One step of a gag: when (ms in), what changes from the pose so far, and the ease into it. */
14
17
  export interface HumanGagStep {
15
18
  after: number;
@@ -1,5 +1,4 @@
1
1
  import type { BodyPlan, Pose } from '../rig/body-plan';
2
- import { type ExpressionName } from '../stick-figure';
3
2
  /**
4
3
  * The human body plan for the v2 character system: a two-bone spine, a neck,
5
4
  * two arms and two legs with feet, and a head.
@@ -19,7 +18,10 @@ import { type ExpressionName } from '../stick-figure';
19
18
  * turned-out plié), and the same for `.right`
20
19
  * - `stretch` (1 normal), `lift` (fraction of height above the ground), `roll` (whole-figure roll, degrees)
21
20
  * - the face: `mouth`, `smile`, `mouthWidth`, `blink`, `eye.left`, `eye.right`,
22
- * `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` (as the v1 stick figure)
21
+ * `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` (as the v1 stick figure),
22
+ * and marks that fade in from 0 to 1: `blush` (cheeks), `tears`, `sweat` (a bead at the temple)
23
+ * - `held.left`, `held.right`, `held.both`: whether what the character holds
24
+ * there shows (1, the default) or has been let go (below 0.5)
23
25
  *
24
26
  * The character's left is +x: facing the viewer its left arm is on screen-right.
25
27
  */
@@ -30,7 +32,67 @@ export interface HumanBuild {
30
32
  shoulderWidth?: number;
31
33
  /** Half the hip width, fraction of the height (0: both legs from one point) */
32
34
  hipWidth?: number;
35
+ /** Leg length, as a share of the standard (default 1); the body takes up the difference */
36
+ legLength?: number;
37
+ /** Arm length, as a share of the standard (default 1) */
38
+ armLength?: number;
33
39
  }
40
+ /**
41
+ * Ready-made builds: proportions only, so the same poses, gaits and actions
42
+ * work on each. Age, posture and clothes are separate choices: a child build
43
+ * has a larger head and shorter limbs, nothing more. How tall a character
44
+ * stands is its `height`; a build changes how that height is shared out.
45
+ */
46
+ export declare const HUMAN_BUILDS: {
47
+ standard: {};
48
+ slim: {
49
+ headSize: number;
50
+ shoulderWidth: number;
51
+ hipWidth: number;
52
+ };
53
+ tall: {
54
+ headSize: number;
55
+ legLength: number;
56
+ armLength: number;
57
+ };
58
+ short: {
59
+ headSize: number;
60
+ legLength: number;
61
+ shoulderWidth: number;
62
+ hipWidth: number;
63
+ };
64
+ broad: {
65
+ shoulderWidth: number;
66
+ hipWidth: number;
67
+ };
68
+ curvy: {
69
+ shoulderWidth: number;
70
+ hipWidth: number;
71
+ };
72
+ stocky: {
73
+ headSize: number;
74
+ shoulderWidth: number;
75
+ hipWidth: number;
76
+ };
77
+ kid: {
78
+ headSize: number;
79
+ };
80
+ child: {
81
+ headSize: number;
82
+ legLength: number;
83
+ armLength: number;
84
+ shoulderWidth: number;
85
+ hipWidth: number;
86
+ };
87
+ toddler: {
88
+ headSize: number;
89
+ legLength: number;
90
+ armLength: number;
91
+ shoulderWidth: number;
92
+ hipWidth: number;
93
+ };
94
+ };
95
+ export type HumanBuildName = keyof typeof HUMAN_BUILDS;
34
96
  export declare const HUMAN_REST: Pose;
35
97
  /** A full human pose from the fields that differ from rest. */
36
98
  export declare function humanPose(changes?: Pose): Pose;
@@ -59,6 +121,17 @@ export declare const HUMAN_POSES: {
59
121
  crouch: Pose;
60
122
  crawl: Pose;
61
123
  lieDown: Pose;
124
+ sleep: Pose;
125
+ stretch: Pose;
126
+ sitFloor: Pose;
127
+ carry: Pose;
128
+ lift: Pose;
129
+ push: Pose;
130
+ pull: Pose;
131
+ drink: Pose;
132
+ phone: Pose;
133
+ read: Pose;
134
+ type: Pose;
62
135
  };
63
136
  export type HumanPoseName = keyof typeof HUMAN_POSES;
64
137
  /** A human body plan; the same pose fields work on every build. */
@@ -67,6 +140,40 @@ export declare function humanPlan(build?: HumanBuild): BodyPlan;
67
140
  export declare function humanFieldLabel(field: string): string;
68
141
  /**
69
142
  * The ready-made faces (happy, sad, surprised, angry…), as human pose fields.
70
- * Each sets every face field, so applying one replaces the whole face.
143
+ * Each sets every face field, so applying one replaces the whole face; any
144
+ * two blend. The second group, from the emotions reference sheet, uses the
145
+ * human face's marks (blush, tears, sweat).
71
146
  */
72
- export declare const HUMAN_EXPRESSIONS: Record<ExpressionName, Pose>;
147
+ export declare const HUMAN_EXPRESSIONS: {
148
+ laughing: Pose;
149
+ afraid: Pose;
150
+ bored: Pose;
151
+ tired: Pose;
152
+ embarrassed: Pose;
153
+ proud: Pose;
154
+ determined: Pose;
155
+ affectionate: Pose;
156
+ hurt: Pose;
157
+ suspicious: Pose;
158
+ relieved: Pose;
159
+ excited: Pose;
160
+ neutral: Pose;
161
+ happy: Pose;
162
+ joyful: Pose;
163
+ sad: Pose;
164
+ crying: Pose;
165
+ surprised: Pose;
166
+ shocked: Pose;
167
+ angry: Pose;
168
+ furious: Pose;
169
+ worried: Pose;
170
+ scared: Pose;
171
+ confused: Pose;
172
+ skeptical: Pose;
173
+ thinking: Pose;
174
+ sleepy: Pose;
175
+ disgusted: Pose;
176
+ smug: Pose;
177
+ wink: Pose;
178
+ };
179
+ export type HumanExpressionName = keyof typeof HUMAN_EXPRESSIONS;
@@ -0,0 +1,47 @@
1
+ import type { EasingType, Track } from '../../engine/types';
2
+ /**
3
+ * The timed edits a surface records on its own props, written out as plain
4
+ * keyframes by `tracks()`. A surface's methods (highlight a line, grow a
5
+ * bar, fling a piece) only ever add keys here; nothing is applied until the
6
+ * timeline plays the tracks, so the same calls always give the same tracks.
7
+ */
8
+ /** One recorded key on a prop. */
9
+ export type EditKey = {
10
+ time: number;
11
+ value: number;
12
+ easing?: EasingType;
13
+ };
14
+ /** When an edit happens. */
15
+ export interface EditOptions {
16
+ /** When the edit starts, ms */
17
+ at: number;
18
+ /** ms (default depends on the edit) */
19
+ duration?: number;
20
+ easing?: EasingType;
21
+ }
22
+ /** A span of time a prop is changing in, ms. */
23
+ export interface TimeWindow {
24
+ start: number;
25
+ end: number;
26
+ }
27
+ export interface EditLog {
28
+ /** The keys recorded on a prop so far (undefined when it has none) */
29
+ keys(prop: string): EditKey[] | undefined;
30
+ /** Add keys to a prop */
31
+ push(prop: string, ...keys: EditKey[]): void;
32
+ /** An edit from one value to another, as a start and an end key */
33
+ tween(prop: string, from: number, to: number, edit: EditOptions, defaultDuration?: number): void;
34
+ /** The value of a prop's latest key, or `fallback` when it has none */
35
+ last(prop: string, fallback: number): number;
36
+ /** A prop's recorded value at `time` (see `valueAt`) */
37
+ valueAt(prop: string, time: number): number;
38
+ /** Drop the keys after `time` on each prop (a later edit takes over from there) */
39
+ cutAfter(props: string[], time: number): void;
40
+ /** The recorded edits as tracks on `target` (the surface's key in the scene) */
41
+ tracks(target: string): Track[];
42
+ }
43
+ export declare function editLog(): EditLog;
44
+ /** A recorded prop's value at `time`: linear between its keys, held before the first and after the last (0 with none). */
45
+ export declare function valueAt(keys: EditKey[] | undefined, time: number): number;
46
+ /** When a prop's recorded value is changing: each pair of neighbouring keys with different values. */
47
+ export declare function changingWindows(keys: EditKey[] | undefined): TimeWindow[];
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Surfaces: scene objects figures act on (a code panel today; boards,
3
+ * charts and stateful props next). Each records timed edits on its own
4
+ * props, lets parts come loose as pieces, and carries a figure standing on
5
+ * it. These are the parts every surface shares.
6
+ */
7
+ export * from './surface-box';
8
+ export * from './edit-log';
9
+ export * from './pieces';
10
+ export * from './ride';
11
+ export * from './surface';
@@ -0,0 +1,61 @@
1
+ import type { EditLog, EditOptions } from './edit-log';
2
+ import type { SurfaceBox } from './surface-box';
3
+ /**
4
+ * Parts of a surface that come loose: a word off a line of code, a note off
5
+ * a board, a slice out of a chart. A piece is drawn by its surface at its
6
+ * home plus the offsets recorded here, as `piece.K.x`, `.y` (px from home),
7
+ * `.rotate` (degrees) and `.opacity`. The surface makes its pieces (it knows
8
+ * what they look like); this moves them, the same way on every surface.
9
+ */
10
+ /** A part of a surface that can come loose. */
11
+ export interface SurfacePiece {
12
+ /** Its key in the surface's props (`piece.K.x`…) */
13
+ readonly id: number;
14
+ /** Where it sits on the surface */
15
+ readonly home: SurfaceBox;
16
+ }
17
+ /** A point at a time, scene px: a path for a piece to follow (see `handPath`). */
18
+ export interface TimedPoint {
19
+ time: number;
20
+ x: number;
21
+ y: number;
22
+ }
23
+ export interface FlingOptions {
24
+ /** When it leaves, ms */
25
+ at: number;
26
+ /** px/ms (default: how fast it was moving along its `follow` path at `at`, or up and to the right) */
27
+ velocity?: {
28
+ x: number;
29
+ y: number;
30
+ };
31
+ /** Turns, degrees per ms (default 0.6, signed by the throw's direction) */
32
+ spin?: number;
33
+ /** px/ms² (default 0.0016) */
34
+ gravity?: number;
35
+ /** How long it flies before it is gone, ms (default 900) */
36
+ duration?: number;
37
+ }
38
+ /** How often a fling's arc (and a ride) is sampled, ms. */
39
+ export declare const SAMPLE_STEP = 33;
40
+ export interface PieceMotion {
41
+ /** Where a piece's centre is at `time`, scene px */
42
+ at(piece: SurfacePiece, time: number): {
43
+ x: number;
44
+ y: number;
45
+ };
46
+ /** Drop a piece's position and turn after `time` (a fling or a move takes over from there) */
47
+ cutAfter(piece: SurfacePiece, time: number): void;
48
+ /** Carry a piece along a path of scene points (its centre follows them) */
49
+ follow(piece: SurfacePiece, path: TimedPoint[]): void;
50
+ /** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
51
+ fling(piece: SurfacePiece, options: FlingOptions): void;
52
+ /** Move a piece's centre to a scene point (back home: its `home` centre) */
53
+ move(piece: SurfacePiece, options: EditOptions & {
54
+ to: {
55
+ x: number;
56
+ y: number;
57
+ };
58
+ }): void;
59
+ }
60
+ /** Moves pieces by recording their offsets in `log`. */
61
+ export declare function pieceMotion(log: EditLog): PieceMotion;
@@ -0,0 +1,31 @@
1
+ import type { Track } from '../../engine/types';
2
+ import type { TimeWindow } from './edit-log';
3
+ /**
4
+ * A figure carried by what it stands on: a line of code moving up as the one
5
+ * above it is removed, a shelf sliding, a bar of a chart growing. A surface
6
+ * says where its floors are and how they move; `rideFloors` rewrites the
7
+ * figure's `y` track so its feet stay on them.
8
+ */
9
+ /** Somewhere a figure can stand on a surface. */
10
+ export interface Floor {
11
+ /** Its top as laid out (before it has moved), scene y */
12
+ top: number;
13
+ /** How far it has moved at `time`, px (up is negative) */
14
+ offset(time: number): number;
15
+ /** When it is moving */
16
+ windows: TimeWindow[];
17
+ }
18
+ export interface RideOptions {
19
+ /** The script's ground, scene y (the figure's y track is measured from it) */
20
+ ground: number;
21
+ /** How often a moving stretch is sampled, ms */
22
+ every: number;
23
+ floors: Floor[];
24
+ }
25
+ /**
26
+ * `target`'s tracks with its `y` carried by the floor under its feet. Each
27
+ * segment of the `y` track keeps its keys (and easing) where what is under
28
+ * it does not move; where a floor under it moves (or it steps from one
29
+ * floor to another that has moved), the segment is sampled every `every` ms.
30
+ */
31
+ export declare function rideFloors(tracks: Track[], target: string, { ground, every, floors }: RideOptions): Track[];
@@ -0,0 +1,18 @@
1
+ /**
2
+ * A place on a surface, scene px: a line of code, a word, a bar of a chart,
3
+ * a note on a board. A figure stands on `top`, points at `x`, `y` (the
4
+ * centre) and swipes from `left` to `right`, so a box is a beat's target as
5
+ * it is.
6
+ */
7
+ export interface SurfaceBox {
8
+ x: number;
9
+ y: number;
10
+ left: number;
11
+ right: number;
12
+ top: number;
13
+ bottom: number;
14
+ width: number;
15
+ height: number;
16
+ }
17
+ /** The box with this top-left corner and size. */
18
+ export declare function surfaceBox(left: number, top: number, width: number, height: number): SurfaceBox;
@@ -0,0 +1,79 @@
1
+ import type { CustomTarget } from '../../adapters/canvas/canvas-adapter';
2
+ import type { Track } from '../../engine/types';
3
+ import type { EditOptions } from './edit-log';
4
+ import type { FlingOptions, SurfacePiece, TimedPoint } from './pieces';
5
+ import type { SurfaceBox } from './surface-box';
6
+ /**
7
+ * A surface: a scene object figures act on. A code panel is one; boards,
8
+ * charts and stateful props follow the same contract.
9
+ *
10
+ * Its places are named by strings, `kind:args`, so a beat can aim at one as
11
+ * plain data: `line:7` and `token:7:Println` on a code panel. `anchor(name)`
12
+ * gives the box there (stand on `top`, point at `x`, `y`), `piece(name)`
13
+ * makes the part there come loose, and `edit(name, anchor, options)` changes
14
+ * the surface at a time. Every edit is recorded as keys on the surface's own
15
+ * props and written out by `tracks()`, so the same calls always give the
16
+ * same tracks.
17
+ *
18
+ * ```ts
19
+ * const code = codePanel({ code: source, language: 'go', x: 40, y: 30 })
20
+ * code.anchor('token:4:Println') // where the word is
21
+ * code.edit('highlight', 'line:4', { at: 1200 })
22
+ * code.edit('fling', 'token:4:Println', { at: 2000 }) // knocked off the panel
23
+ * ```
24
+ */
25
+ export interface Surface {
26
+ /** What it is: 'code', 'board', 'chart'… */
27
+ readonly kind: string;
28
+ /** The canvas target that draws it; put it in the scene's targets */
29
+ readonly target: CustomTarget;
30
+ /** The whole surface */
31
+ readonly box: SurfaceBox;
32
+ /** Its anchors and edits, said as data (for the capability catalog and the checks) */
33
+ readonly about: SurfaceAbout;
34
+ /** The box at a named place (see `about.anchors`), at `time` (default: after every edit) */
35
+ anchor(name: string, time?: number): SurfaceBox;
36
+ /** Make the part at a named place a piece that can come loose (the same piece each time it is asked for) */
37
+ piece(anchor: string): SurfacePiece;
38
+ /** Change the surface at a time: `name` is one of `about.edits`, `anchor` one place or several */
39
+ edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Surface;
40
+ /** Carry a piece along a path of scene points (its centre follows them) */
41
+ follow(piece: SurfacePiece, path: TimedPoint[]): Surface;
42
+ /** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
43
+ fling(piece: SurfacePiece, options: FlingOptions): Surface;
44
+ /** Move a piece's centre to a scene point */
45
+ move(piece: SurfacePiece, options: EditOptions & {
46
+ to: {
47
+ x: number;
48
+ y: number;
49
+ };
50
+ }): Surface;
51
+ /** A figure's tracks with it carried along by what it stands on; `ground` is the script's `ground` */
52
+ ride(tracks: Track[], target: string, options: {
53
+ ground: number;
54
+ every?: number;
55
+ }): Track[];
56
+ /** The recorded edits as tracks on `target` (the surface's key in the scene) */
57
+ tracks(target: string): Track[];
58
+ }
59
+ /** An edit's options: when, plus what that edit takes (see `about.edits`). */
60
+ export type SurfaceEditOptions = EditOptions & Record<string, unknown>;
61
+ /** A surface's anchors and edits, as data. */
62
+ export interface SurfaceAbout {
63
+ kind: string;
64
+ /** How to make one */
65
+ create?: string;
66
+ /** Anchor patterns, such as `line:N`, and what each names */
67
+ anchors: Record<string, string>;
68
+ /** Edit names, with the anchors and options each takes */
69
+ edits: Record<string, string>;
70
+ }
71
+ /** An anchor name split into its kind and the rest: `token:7:Println` → `token`, `7:Println`. */
72
+ export declare function parseAnchor(name: string): {
73
+ kind: string;
74
+ rest: string;
75
+ };
76
+ /** The error for an anchor a surface does not have, naming the ones it does. */
77
+ export declare function anchorError(owner: string, name: string, about: SurfaceAbout, why?: string): Error;
78
+ /** The error for an edit a surface does not have. */
79
+ export declare function editError(owner: string, name: string, about: SurfaceAbout): Error;