@algorisys/tinyfly 0.92.0 → 0.93.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 (61) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2694 -1809
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6498 -5483
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +3 -0
  54. package/lib/types/characters/stick-figure.d.ts +2 -0
  55. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  56. package/lib/types/engine/authoring/index.d.ts +1 -0
  57. package/llms-full.txt +12548 -0
  58. package/llms.txt +57 -0
  59. package/package.json +6 -2
  60. package/skills/tinyfly/SKILL.md +64 -0
  61. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,50 @@
1
+ import { type PropertyInfo } from '../adapters/canvas/target-properties';
2
+ export interface Capabilities {
3
+ version?: string;
4
+ timing: string;
5
+ easings: {
6
+ named: string[];
7
+ parametric: Record<string, string>;
8
+ };
9
+ trackKinds: Record<string, string>;
10
+ canvasProperties: Record<string, PropertyInfo & {
11
+ types: readonly string[];
12
+ }>;
13
+ stickFigure: {
14
+ poseFields: Record<string, PropertyInfo>;
15
+ props: Record<string, PropertyInfo>;
16
+ handFields: Record<string, PropertyInfo>;
17
+ poses: string[];
18
+ expressions: string[];
19
+ gags: Record<string, number>;
20
+ gaits: string[];
21
+ actingStyles: string[];
22
+ beatFields: readonly string[];
23
+ actions: Record<string, {
24
+ summary: string;
25
+ needs?: string[];
26
+ uses?: string[];
27
+ }>;
28
+ dances: Record<string, string[]>;
29
+ flips: Record<string, string>;
30
+ handShapes: string[];
31
+ mudras: string[];
32
+ };
33
+ character: {
34
+ poses: string[];
35
+ expressions: string[];
36
+ gags: string[];
37
+ };
38
+ codePanel: {
39
+ languages: readonly string[];
40
+ removeStyles: readonly string[];
41
+ anchors: Record<string, string>;
42
+ edits: Record<string, string>;
43
+ };
44
+ cameraShots: Record<string, string>;
45
+ teach: Record<string, string>;
46
+ cli: Record<string, string>;
47
+ }
48
+ export declare function capabilities(version?: string): Capabilities;
49
+ /** The catalog as markdown, for people and language models. */
50
+ export declare function capabilitiesMarkdown(version?: string): string;
@@ -0,0 +1,201 @@
1
+ import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
2
+ import type { EasingType, Track } from '../engine/types';
3
+ /**
4
+ * A code listing as a scene object characters can act on: they stand on its
5
+ * lines, point at its tokens and swipe lines away.
6
+ *
7
+ * ```ts
8
+ * const code = codePanel({ code: source, language: 'go', x: 40, y: 30 })
9
+ * const line = code.line(7) // where line 7 is: stand on line.top, point at its centre
10
+ * const word = code.token(7, 'Println') // where a word on it is
11
+ * code.highlight(7, { at: 1200 }) // timed edits, in ms
12
+ * code.remove(7, { at: 2400, duration: 300, from: 'right' })
13
+ * const scene = { targets: { code: code.target, hero }, tracks: [...code.tracks('code'), ...script.tracks] }
14
+ * ```
15
+ *
16
+ * Layout is fixed-width arithmetic (characters are `charWidth` em wide, lines
17
+ * `lineHeight` em apart), never measured from a font, so anchors are the same
18
+ * in a browser, a worker or a build script. Lines are numbered from 1, as an
19
+ * editor numbers them. Edits are recorded on the panel and written out by
20
+ * `tracks()` as plain keyframes on the panel's props: `line.N.highlight`,
21
+ * `line.N.strike`, `line.N.wipe`, `line.N.reveal` and `line.N.shift`.
22
+ *
23
+ * Words can come loose: `piece(n, text)` makes a word a piece that can be
24
+ * carried (`follow` a path, such as a hand's), thrown or kicked away
25
+ * (`fling`), moved (`move`), and replaced by typing new text into its place
26
+ * (`write`), or dropped into another line (`drop`). Pieces animate
27
+ * `piece.K.x`, `.y` (offsets from home), `.rotate`, `.opacity`, `.write` and
28
+ * `.away` (its old place closing). New text can be typed into a line
29
+ * (`insert`); an insert or a drop opens room in its line (`insert.K.open`,
30
+ * `insert.K.type`).
31
+ */
32
+ export type CodeLanguage = 'go' | 'rust' | 'csharp' | 'javascript' | 'typescript' | 'python' | 'plain';
33
+ export interface CodeTheme {
34
+ background: string;
35
+ gutter: string;
36
+ text: string;
37
+ keyword: string;
38
+ string: string;
39
+ number: string;
40
+ comment: string;
41
+ highlight: string;
42
+ strike: string;
43
+ font: string;
44
+ }
45
+ export declare const CODE_THEME: CodeTheme;
46
+ export interface CodePanelOptions {
47
+ code: string;
48
+ language?: CodeLanguage;
49
+ /** Top-left corner of the panel, scene px */
50
+ x: number;
51
+ y: number;
52
+ /** px (default 16) */
53
+ fontSize?: number;
54
+ /** Line spacing, em (default 1.6) */
55
+ lineHeight?: number;
56
+ /** Width of a character, em (default 0.6, which most monospace fonts are) */
57
+ charWidth?: number;
58
+ /** Inside the panel's edge, px (default 12) */
59
+ padding?: number;
60
+ /** Show line numbers (default true) */
61
+ lineNumbers?: boolean;
62
+ /** Panel width, px (default: fits the longest line) */
63
+ width?: number;
64
+ /** Lines that start hidden, to be typed in with `type()` */
65
+ hidden?: number[];
66
+ theme?: Partial<CodeTheme>;
67
+ }
68
+ /** 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
+ }
86
+ /** How a removed line goes: wiped away, knocked off the panel, or out of focus. */
87
+ export type CodeRemoveStyle = 'wipe' | 'fly' | 'blur';
88
+ export declare const REMOVE_STYLES: readonly CodeRemoveStyle[];
89
+ export interface CodeRemoveOptions extends CodeEditOptions {
90
+ /** `wipe` (default) erases it from one side; `fly` knocks it off the panel, blurring as it goes; `blur` fades it out of focus where it is */
91
+ style?: CodeRemoveStyle;
92
+ /** The side the wipe starts from, or the side `fly` knocks it from (default left: it flies right) */
93
+ from?: 'left' | 'right';
94
+ /** How long the lines below take to close the gap, ms (default 250) */
95
+ close?: number;
96
+ }
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;
101
+ readonly line: number;
102
+ readonly column: number;
103
+ 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
+ }
128
+ export interface CodePanel {
129
+ /** The canvas target that draws the panel; put it in the scene's targets */
130
+ readonly target: CustomTarget;
131
+ readonly lines: readonly string[];
132
+ /** The whole panel */
133
+ readonly box: CodeBox;
134
+ /** Where line `n`'s text is (its width is the text's, at least one character). At `time`, after the gaps of removed lines have closed. */
135
+ line(n: number, time?: number): CodeBox;
136
+ /** Where the `occurrence`th `text` on line `n` is (default the first) */
137
+ token(n: number, text: string, occurrence?: number, time?: number): CodeBox;
138
+ /** Tint a line, or clear it with `on: false` */
139
+ highlight(n: number | number[], options: CodeEditOptions & {
140
+ on?: boolean;
141
+ }): CodePanel;
142
+ /** Strike a line through, left to right */
143
+ strike(n: number | number[], options: CodeEditOptions): CodePanel;
144
+ /** Wipe lines away, then close the gap: the lines below move up */
145
+ remove(n: number | number[], options: CodeRemoveOptions): CodePanel;
146
+ /** Type a hidden line in, character by character */
147
+ type(n: number, options: CodeEditOptions): CodePanel;
148
+ /** Make the `occurrence`th `text` on line `n` a piece that can come loose */
149
+ piece(n: number, text: string, occurrence?: number): CodePiece;
150
+ /** Carry a piece along a path of scene points (its centre follows them) */
151
+ follow(piece: CodePiece, path: TimedPoint[]): CodePanel;
152
+ /** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
153
+ fling(piece: CodePiece, options: CodeFlingOptions): CodePanel;
154
+ /** Move a piece's centre to a scene point (back home: its `home` centre) */
155
+ move(piece: CodePiece, options: CodeEditOptions & {
156
+ to: {
157
+ x: number;
158
+ y: number;
159
+ };
160
+ }): CodePanel;
161
+ /** Type new text into a piece's place in its line; the rest of the line makes room */
162
+ write(piece: CodePiece, text: string, options: CodeEditOptions): CodePanel;
163
+ /**
164
+ * A place in line `n`: `width` characters (default 1) starting at `column`
165
+ * (0 is before its first character, its length just past its end), after
166
+ * any room inserts before it have opened. Aim a `put` or a `write` here.
167
+ */
168
+ spot(n: number, column: number, width?: number, time?: number): CodeBox;
169
+ /** Type new text into line `n` before `column`; the rest of the line makes room as it is typed */
170
+ insert(n: number, column: number, text: string, options: CodeEditOptions): CodePanel;
171
+ /**
172
+ * Put a piece into line `n` before `column`: it moves there as the line
173
+ * opens room for it, and its old place closes. Into its own line, it slides
174
+ * along (linear by default) and the text it passes closes up behind it.
175
+ */
176
+ drop(piece: CodePiece, n: number, column: number, options: CodeEditOptions): CodePanel;
177
+ /** Where a piece dropped into line `n` before `column` would land (its own line closes up behind it) */
178
+ landing(piece: CodePiece, n: number, column: number, time?: number): CodeBox;
179
+ /**
180
+ * A figure's tracks with it carried along by the line it stands on: while
181
+ * its feet are on a line's top (as laid out, before any gaps closed), its
182
+ * `y` moves with that line. `ground` is the script's `ground`.
183
+ */
184
+ ride(tracks: Track[], target: string, options: {
185
+ ground: number;
186
+ every?: number;
187
+ }): Track[];
188
+ /** The recorded edits as tracks on `target` (the panel's key in the scene) */
189
+ tracks(target: string): Track[];
190
+ }
191
+ export declare function codePanel(options: CodePanelOptions): CodePanel;
192
+ /** What a code panel's methods do, for its `about` and the capability catalog. */
193
+ export declare const CODE_PANEL_EDITS: Record<string, string>;
194
+ export interface CodeToken {
195
+ text: string;
196
+ kind: 'text' | 'keyword' | 'string' | 'number' | 'comment';
197
+ }
198
+ /** The languages a code panel colours. */
199
+ export declare const CODE_LANGUAGES: CodeLanguage[];
200
+ /** Split one line into coloured runs: strings, line comments, numbers, keywords and the rest. */
201
+ export declare function codeTokens(line: string, language: CodeLanguage): CodeToken[];
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Where the stick figure finds the list of actions it can be given. The list
3
+ * comes from the beat scripts (gaits, poses, gags and acting beats), which
4
+ * are built on the figure, so the figure cannot import them without a cycle.
5
+ * The acting module registers the list here when it loads (the characters
6
+ * entry always loads it), and the figure's `about.actions` reads it then.
7
+ */
8
+ /** Called once by the acting module. */
9
+ export declare function provideFigureActions(list: () => Record<string, string>): void;
10
+ /** The actions a stick figure can be given, with a line each (empty until the acting module has loaded). */
11
+ export declare function figureActions(): Record<string, string>;
@@ -0,0 +1,87 @@
1
+ import type { PropertyInfo } from '../adapters/canvas/target-properties';
2
+ /** Every pose field (`StickPose`). */
3
+ export declare const STICK_POSE_FIELDS: {
4
+ lean: PropertyInfo;
5
+ bend: PropertyInfo;
6
+ headTilt: PropertyInfo;
7
+ leftShoulder: PropertyInfo;
8
+ rightShoulder: PropertyInfo;
9
+ leftElbow: PropertyInfo;
10
+ rightElbow: PropertyInfo;
11
+ leftHip: PropertyInfo;
12
+ rightHip: PropertyInfo;
13
+ leftKnee: PropertyInfo;
14
+ rightKnee: PropertyInfo;
15
+ leftWrist: PropertyInfo;
16
+ rightWrist: PropertyInfo;
17
+ leftAnkle: PropertyInfo;
18
+ rightAnkle: PropertyInfo;
19
+ leftFootOut: PropertyInfo;
20
+ rightFootOut: PropertyInfo;
21
+ mouth: PropertyInfo;
22
+ smile: PropertyInfo;
23
+ mouthWidth: {
24
+ description: string;
25
+ unit: string;
26
+ min: number;
27
+ max: number;
28
+ };
29
+ blink: PropertyInfo;
30
+ leftEye: {
31
+ description: string;
32
+ unit: string;
33
+ min: number;
34
+ max: number;
35
+ };
36
+ rightEye: {
37
+ description: string;
38
+ unit: string;
39
+ min: number;
40
+ max: number;
41
+ };
42
+ leftBrow: PropertyInfo;
43
+ rightBrow: PropertyInfo;
44
+ browTilt: PropertyInfo;
45
+ lookX: PropertyInfo;
46
+ lookY: PropertyInfo;
47
+ stretch: {
48
+ description: string;
49
+ unit: string;
50
+ min: number;
51
+ max: number;
52
+ };
53
+ turn: PropertyInfo;
54
+ sit: PropertyInfo;
55
+ spin: PropertyInfo;
56
+ rise: {
57
+ description: string;
58
+ unit: string;
59
+ };
60
+ };
61
+ /** The figure target's props besides the pose. */
62
+ export declare const STICK_FIGURE_EXTRAS: {
63
+ walk: {
64
+ description: string;
65
+ unit: string;
66
+ };
67
+ walking: PropertyInfo;
68
+ gait: {
69
+ description: string;
70
+ kind: "string";
71
+ };
72
+ talk: PropertyInfo;
73
+ rubber: PropertyInfo;
74
+ facing: {
75
+ description: string;
76
+ unit: string;
77
+ min: number;
78
+ max: number;
79
+ };
80
+ beat: {
81
+ description: string;
82
+ unit: string;
83
+ };
84
+ dancing: PropertyInfo;
85
+ };
86
+ /** A cartoon hand's pose fields (`hand.left.<field>` / `hand.right.<field>` props when the style has hands). */
87
+ export declare const HAND_FIELDS: Record<string, PropertyInfo>;
@@ -51,6 +51,7 @@ export interface Gait {
51
51
  * - `strut`: chest out, head high, a swagger.
52
52
  * - `tired`: slumped, dragging, arms hanging.
53
53
  * - `run`: leaning in, knees high, arms pumping, off the ground between steps.
54
+ * - `shove`: short steady steps that leave the body and arms alone, for pushing something along.
54
55
  */
55
56
  export declare const GAITS: {
56
57
  walk: {
@@ -124,6 +125,13 @@ export declare const GAITS: {
124
125
  bounce: number;
125
126
  squash: number;
126
127
  };
128
+ shove: {
129
+ swing: number;
130
+ knee: number;
131
+ arm: number;
132
+ elbow: number;
133
+ lean: number;
134
+ };
127
135
  };
128
136
  export type GaitName = keyof typeof GAITS;
129
137
  /** A gait by name or as data; an unknown name is the plain walk. */
@@ -14,6 +14,7 @@ export { characterObjects } from './scene-objects';
14
14
  export * from '../adapters/canvas/sketch';
15
15
  export * from '../adapters/canvas/camera';
16
16
  export * from './erase';
17
+ export * from './code-panel';
17
18
  export * from '../adapters/canvas/polyline';
18
19
  export * from './hand';
19
20
  export * from './character';
@@ -24,3 +25,5 @@ export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type
24
25
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
25
26
  export * from './hands';
26
27
  export * from './acting';
28
+ export * from './capabilities';
29
+ export { describeTarget, checkTracks, animatableProperties, CANVAS_PROPERTIES, type PropertyInfo, type TargetAbout, type TargetDescription, type TrackProblem } from '../adapters/canvas/target-properties';
@@ -149,6 +149,8 @@ export declare const POSES: {
149
149
  crouch: StickPose;
150
150
  sit: StickPose;
151
151
  jump: StickPose;
152
+ duck: StickPose;
153
+ lie: StickPose;
152
154
  sideSplit: StickPose;
153
155
  frontSplit: StickPose;
154
156
  };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Name checking for data written by hand or by a language model: when a name
3
+ * is not one of the known ones, say which known name it most likely meant,
4
+ * and list them all, so the mistake can be fixed from the message alone.
5
+ */
6
+ /** Edit distance between two strings (insertions, deletions, substitutions), ignoring case. */
7
+ export declare function editDistance(a: string, b: string): number;
8
+ /**
9
+ * The known name `word` most likely meant: one that contains it (or it
10
+ * contains), else the nearest by edit distance when that is close enough.
11
+ */
12
+ export declare function closestName(word: string, known: readonly string[]): string | undefined;
13
+ /** "Unknown mood "excited": did you mean "joyful"? Known: happy, joyful, …" */
14
+ export declare function unknownName(what: string, word: unknown, known: readonly string[], hint?: string): string;
@@ -4,3 +4,4 @@ export * from './custom-ease';
4
4
  export * from './narration';
5
5
  export * from './beats';
6
6
  export * from './camera-shots';
7
+ export * from './did-you-mean';