@algorisys/tinyfly 0.74.1 → 0.76.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.
@@ -1,4 +1,5 @@
1
1
  import type { AnimationState, AnimatableValue } from '../../engine/types';
2
+ import { type SketchStyle } from './sketch';
2
3
  /** Gradient stop definition */
3
4
  export interface GradientStop {
4
5
  offset: number;
@@ -60,6 +61,16 @@ export interface CanvasTargetBase {
60
61
  shadowBlur?: number;
61
62
  shadowColor?: string;
62
63
  shine?: number;
64
+ /**
65
+ * Draw the outline in hand-drawn pencil strokes that boil (rect, circle, line
66
+ * and path targets). The fill stays clean underneath.
67
+ */
68
+ sketch?: SketchStyle;
69
+ /**
70
+ * How much of the outline is drawn, 0..1 (default 1), for drawing a shape on
71
+ * (rect, circle, line and path targets). The fill appears once it is complete.
72
+ */
73
+ drawOn?: number;
63
74
  }
64
75
  /** Rectangle target */
65
76
  export interface RectTarget extends CanvasTargetBase {
@@ -205,6 +216,13 @@ export declare class CanvasAdapter {
205
216
  * Get target bounding box for gradient calculations.
206
217
  */
207
218
  private getTargetBounds;
219
+ /** Whether a shape is drawn stroke by stroke: sketched, or only partly drawn on. */
220
+ private drawsOutline;
221
+ /**
222
+ * Draw a shape outline-first: the fill (clean) once the outline is complete,
223
+ * then the outline up to `drawOn`, in pencil strokes when sketched.
224
+ */
225
+ private renderOutlined;
208
226
  /**
209
227
  * Render a rectangle.
210
228
  */
@@ -1 +1,4 @@
1
1
  export * from './canvas-adapter';
2
+ export * from './sketch';
3
+ export * from './polyline';
4
+ export * from './outline';
@@ -0,0 +1,26 @@
1
+ import type { Point, SketchPen } from './sketch';
2
+ /**
3
+ * Shape outlines as strokes a pencil can draw: runs of straight segments, and
4
+ * curves sampled into points. The canvas adapter draws a shape this way when
5
+ * it is sketched or only partly drawn on (`drawOn` below 1).
6
+ */
7
+ export interface OutlineStroke {
8
+ /** `line`: straight segments between the points; `curve`: a smooth curve through them */
9
+ kind: 'line' | 'curve';
10
+ points: Point[];
11
+ /** Length along the shape, for sharing out `drawOn` */
12
+ length: number;
13
+ }
14
+ /**
15
+ * The outline of SVG path data: each run of straight segments is one stroke
16
+ * (so a polygon is drawn in one go), each curved segment another.
17
+ */
18
+ export declare function pathOutline(pathData: string): OutlineStroke[];
19
+ /** The outline of a rectangle, with rounded corners when `radius` is above 0. */
20
+ export declare function rectOutline(x: number, y: number, width: number, height: number, radius?: number): OutlineStroke[];
21
+ /**
22
+ * Stroke an outline up to `progress` (0..1) of its total length, in order:
23
+ * sketched with a pen, or clean. Every stroke is handed to the pen even when
24
+ * none of it is drawn yet, so each keeps its own wobble as the outline grows.
25
+ */
26
+ export declare function drawOutline(ctx: CanvasRenderingContext2D, strokes: OutlineStroke[], progress: number, pen?: SketchPen): void;
@@ -0,0 +1,12 @@
1
+ import type { Point } from './sketch';
2
+ /**
3
+ * Polyline helpers measured by length, so `progress` 0..1 means "this much of
4
+ * the way along", whatever the spacing of the points. Drawing on, erasing and
5
+ * the hand that follows a stroke all use them.
6
+ */
7
+ /** Total length of a polyline. */
8
+ export declare function pathLength(points: Point[]): number;
9
+ /** The start of a polyline, up to `progress` (0..1) of its length. */
10
+ export declare function partialPath(points: Point[], progress: number): Point[];
11
+ /** Where along a polyline `progress` (0..1) of its length is. */
12
+ export declare function pointAlong(points: Point[], progress: number): Point;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Hand-drawn strokes for canvas drawing: each line is drawn a few times, a
3
+ * little off and a little bowed, the way a pencil line is. "Line boil" redraws
4
+ * the wobble a few times a second, so a still drawing looks alive.
5
+ *
6
+ * The wobble comes from a seeded generator keyed to the seed, the boil frame
7
+ * and the stroke's place in the drawing order, never from Math.random, so the
8
+ * same time always draws the same lines: a frame rendered twice, in a browser
9
+ * or headless, is identical.
10
+ *
11
+ * Every stroke takes a `progress` (0..1) to draw it on, as a pencil would: the
12
+ * part drawn so far lies exactly on the finished stroke, so it grows without
13
+ * jumping.
14
+ */
15
+ export interface SketchStyle {
16
+ /** Largest wobble, px (default 2) */
17
+ roughness?: number;
18
+ /** Strokes per line: 1 is clean, 2 or 3 look sketched (default 2) */
19
+ passes?: number;
20
+ /** Redraws per second; 0 holds the wobble still (default 8, about "on threes" at 24 fps) */
21
+ boil?: number;
22
+ /** Seed for the wobble, so two drawings with the same style do not boil in step (default 1) */
23
+ seed?: number;
24
+ }
25
+ export interface Point {
26
+ x: number;
27
+ y: number;
28
+ }
29
+ /** Which redraw is showing at `time` ms. */
30
+ export declare function boilFrame(time: number, boil: number): number;
31
+ /**
32
+ * Strokes in the context's current stroke style and line width. Each stroke's
33
+ * wobble is seeded by its place in the drawing order, so draw them in the same
34
+ * order every frame; a stroke drawn on partway wobbles exactly as it will when
35
+ * it is finished, and does not disturb the strokes after it.
36
+ */
37
+ export interface SketchPen {
38
+ /** A line through the points, each segment slightly bowed; `progress` draws it on (default 1) */
39
+ line(points: Point[], progress?: number): void;
40
+ /**
41
+ * A smooth curve through the points (a limb drawn as a curve). The wobble
42
+ * is spread along the whole curve rather than added at every point, so a
43
+ * finely sampled curve stays smooth instead of turning lumpy.
44
+ */
45
+ curve(points: Point[], progress?: number): void;
46
+ /** A circle whose end overshoots its start, as a quick pencil circle does */
47
+ circle(cx: number, cy: number, r: number, progress?: number): void;
48
+ /** An ellipse drawn the same way as `circle` */
49
+ ellipse(cx: number, cy: number, rx: number, ry: number, progress?: number): void;
50
+ /** A small random offset, up to `scale` × roughness, for nudging details (a face) with the boil */
51
+ nudge(scale?: number): Point;
52
+ }
53
+ /** A pen whose wobble is fixed for the boil frame showing at `time` ms. */
54
+ export declare function sketchPen(ctx: CanvasRenderingContext2D, style: SketchStyle, time: number): SketchPen;
@@ -0,0 +1,31 @@
1
+ import type { CustomTarget } from '../adapters/canvas';
2
+ import type { Point } from '../adapters/canvas/sketch';
3
+ import { type EraserStyle, type HandStyle } from './hand';
4
+ /**
5
+ * A back-and-forth scrub that covers a box, the way an eraser rubs out an area:
6
+ * `strokes` passes from side to side, stepping down the box.
7
+ */
8
+ export declare function scrubPath(x: number, y: number, width: number, height: number, strokes?: number): Point[];
9
+ /**
10
+ * Clip the context so that drawing misses the swath an eraser `width` wide
11
+ * leaves along `path` up to `progress`. Wrap in save()/restore() to end it.
12
+ */
13
+ export declare function clipErased(ctx: CanvasRenderingContext2D, path: Point[], width: number, progress: number): void;
14
+ /** Run `draw` with the swath erased from it, for immediate-mode drawing. */
15
+ export declare function withErased(ctx: CanvasRenderingContext2D, path: Point[], width: number, progress: number, draw: () => void): void;
16
+ export interface ErasableOptions {
17
+ /** The eraser's path, in the target's own box (0, 0 is its top-left corner) */
18
+ path: Point[];
19
+ /** Eraser width, px (default 40) */
20
+ width?: number;
21
+ /** Draw the eraser while it is rubbing (default true); a style changes its look */
22
+ eraser?: boolean | EraserStyle;
23
+ /** Draw a hand holding the eraser, reaching in from off screen (default false) */
24
+ hand?: boolean | HandStyle;
25
+ }
26
+ /**
27
+ * `target`, erasable: it gains an `erase` prop (0..1, how far along `path` the
28
+ * eraser has rubbed), and what the eraser has covered stays erased. The path
29
+ * is in the target's own box, so the erased part moves with the target.
30
+ */
31
+ export declare function erasable(target: CustomTarget, options: ErasableOptions): CustomTarget;
@@ -0,0 +1,81 @@
1
+ import type { CustomTarget } from '../adapters/canvas';
2
+ import { type Point, type SketchPen, type SketchStyle } from '../adapters/canvas/sketch';
3
+ /**
4
+ * The animator's hand: a cartoon hand holding a pencil or an eraser, reaching
5
+ * in from off screen, with the tool's tip at a point. Put the point on the end
6
+ * of a stroke being drawn on (or erased) and the hand draws it.
7
+ *
8
+ * Shapes are drawn in the tool's frame: the tip at (0, 0) and the tool lying
9
+ * along +x, rotated by `angle`. Everything is plain Canvas 2D.
10
+ */
11
+ export interface PencilStyle {
12
+ /** Lean, degrees (default -30: the pencil up and to the right of its tip) */
13
+ angle?: number;
14
+ /** Pencil length, px (default 240) */
15
+ length?: number;
16
+ /** Body colour (default yellow) */
17
+ color?: string;
18
+ /** Outline colour (default graphite) */
19
+ outline?: string;
20
+ }
21
+ /** A pencil with its tip at `at`. Pass a pen to outline it in sketched strokes. */
22
+ export declare function drawPencil(ctx: CanvasRenderingContext2D, at: Point, style?: PencilStyle, pen?: SketchPen): void;
23
+ export interface EraserStyle {
24
+ /** Eraser length along its body, px (default 90) */
25
+ length?: number;
26
+ /** Eraser thickness, px (default 34) */
27
+ thickness?: number;
28
+ /** Lean, degrees (default -35: the body up and to the right of the tip) */
29
+ angle?: number;
30
+ /** Rubber colour (default pink) */
31
+ color?: string;
32
+ /** Outline colour (default graphite) */
33
+ outline?: string;
34
+ }
35
+ /**
36
+ * A rubber eraser whose rubbing end is at `at`. Pass a pen to outline it in
37
+ * sketched strokes; without one the outline is clean.
38
+ */
39
+ export declare function drawEraser(ctx: CanvasRenderingContext2D, at: Point, style?: EraserStyle, pen?: SketchPen): void;
40
+ export interface HandStyle {
41
+ /** What the hand holds (default pencil) */
42
+ tool?: 'pencil' | 'eraser';
43
+ /** Lean of the tool, degrees (default -30) */
44
+ angle?: number;
45
+ /** Size, 1 is a pencil 240 px long (default 1) */
46
+ scale?: number;
47
+ /** Skin colour */
48
+ skin?: string;
49
+ /** Sleeve colour */
50
+ sleeve?: string;
51
+ /** Outline colour (default graphite) */
52
+ outline?: string;
53
+ }
54
+ /**
55
+ * A hand holding a pencil or an eraser with the tool's tip at `at`, its arm
56
+ * reaching in from off screen. Pass a pen to sketch it: the tools are outlined
57
+ * in pencil strokes and the hand shifts with the boil.
58
+ */
59
+ export declare function drawHand(ctx: CanvasRenderingContext2D, at: Point, style?: HandStyle, pen?: SketchPen): void;
60
+ /** A circle as points, starting at the top and running a little past a full turn, to draw on. */
61
+ export declare function circlePath(cx: number, cy: number, r: number, overshoot?: number, segments?: number): Point[];
62
+ export interface DrawnPathOptions {
63
+ /** The stroke, in scene coordinates */
64
+ path: Point[];
65
+ /** A smooth curve through the points (true) or straight segments between them (default false) */
66
+ smooth?: boolean;
67
+ /** Line colour (default graphite) */
68
+ color?: string;
69
+ /** Line width (default 5) */
70
+ lineWidth?: number;
71
+ /** Draw in sketched pencil strokes; omit for clean lines */
72
+ sketch?: SketchStyle;
73
+ /** Show the hand drawing it (default true); a style changes it */
74
+ hand?: boolean | HandStyle;
75
+ }
76
+ /**
77
+ * A `custom` canvas target that draws a stroke on. Its `draw` prop (0..1) is
78
+ * how much of the path is drawn, so drawing on is a timeline track; while it is
79
+ * between 0 and 1, a hand holds the pencil at the end of the line.
80
+ */
81
+ export declare function drawnPathTarget(options: DrawnPathOptions): CustomTarget;
@@ -1,5 +1,11 @@
1
1
  /**
2
2
  * `@algorisys/tinyfly/characters`: drawable, poseable characters for canvas
3
- * scenes (browser or headless video).
3
+ * scenes (browser or headless video). The pencil pen and path helpers live
4
+ * with the canvas adapter (its shapes can be sketched too) and are re-exported
5
+ * here.
4
6
  */
5
7
  export * from './stick-figure';
8
+ export * from '../adapters/canvas/sketch';
9
+ export * from './erase';
10
+ export * from '../adapters/canvas/polyline';
11
+ export * from './hand';
@@ -0,0 +1,12 @@
1
+ import type { Point } from './sketch';
2
+ /**
3
+ * Polyline helpers measured by length, so `progress` 0..1 means "this much of
4
+ * the way along", whatever the spacing of the points. Drawing on, erasing and
5
+ * the hand that follows a stroke all use them.
6
+ */
7
+ /** Total length of a polyline. */
8
+ export declare function pathLength(points: Point[]): number;
9
+ /** The start of a polyline, up to `progress` (0..1) of its length. */
10
+ export declare function partialPath(points: Point[], progress: number): Point[];
11
+ /** Where along a polyline `progress` (0..1) of its length is. */
12
+ export declare function pointAlong(points: Point[], progress: number): Point;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Hand-drawn strokes for canvas drawing: each line is drawn a few times, a
3
+ * little off and a little bowed, the way a pencil line is. "Line boil" redraws
4
+ * the wobble a few times a second, so a still drawing looks alive.
5
+ *
6
+ * The wobble comes from a seeded generator keyed to the seed, the boil frame
7
+ * and the stroke's place in the drawing order, never from Math.random, so the
8
+ * same time always draws the same lines: a frame rendered twice, in a browser
9
+ * or headless, is identical.
10
+ *
11
+ * Every stroke takes a `progress` (0..1) to draw it on, as a pencil would: the
12
+ * part drawn so far lies exactly on the finished stroke, so it grows without
13
+ * jumping.
14
+ */
15
+ export interface SketchStyle {
16
+ /** Largest wobble, px (default 2) */
17
+ roughness?: number;
18
+ /** Strokes per line: 1 is clean, 2 or 3 look sketched (default 2) */
19
+ passes?: number;
20
+ /** Redraws per second; 0 holds the wobble still (default 8, about "on threes" at 24 fps) */
21
+ boil?: number;
22
+ /** Seed for the wobble, so two drawings with the same style do not boil in step (default 1) */
23
+ seed?: number;
24
+ }
25
+ export interface Point {
26
+ x: number;
27
+ y: number;
28
+ }
29
+ /** Which redraw is showing at `time` ms. */
30
+ export declare function boilFrame(time: number, boil: number): number;
31
+ /**
32
+ * Strokes in the context's current stroke style and line width. Each stroke's
33
+ * wobble is seeded by its place in the drawing order, so draw them in the same
34
+ * order every frame; a stroke drawn on partway wobbles exactly as it will when
35
+ * it is finished, and does not disturb the strokes after it.
36
+ */
37
+ export interface SketchPen {
38
+ /** A line through the points, each segment slightly bowed; `progress` draws it on (default 1) */
39
+ line(points: Point[], progress?: number): void;
40
+ /**
41
+ * A smooth curve through the points (a limb drawn as a curve). The wobble
42
+ * is spread along the whole curve rather than added at every point, so a
43
+ * finely sampled curve stays smooth instead of turning lumpy.
44
+ */
45
+ curve(points: Point[], progress?: number): void;
46
+ /** A circle whose end overshoots its start, as a quick pencil circle does */
47
+ circle(cx: number, cy: number, r: number, progress?: number): void;
48
+ /** An ellipse drawn the same way as `circle` */
49
+ ellipse(cx: number, cy: number, rx: number, ry: number, progress?: number): void;
50
+ /** A small random offset, up to `scale` × roughness, for nudging details (a face) with the boil */
51
+ nudge(scale?: number): Point;
52
+ }
53
+ /** A pen whose wobble is fixed for the boil frame showing at `time` ms. */
54
+ export declare function sketchPen(ctx: CanvasRenderingContext2D, style: SketchStyle, time: number): SketchPen;
@@ -1,5 +1,7 @@
1
1
  import type { CustomTarget } from '../adapters/canvas';
2
+ import type { FrameInfo } from '../headless/video-scene';
2
3
  import type { EasingType, Track } from '../engine/types';
4
+ import { type Point, type SketchPen, type SketchStyle } from '../adapters/canvas/sketch';
3
5
  /**
4
6
  * A stick-figure rig: a pose is a handful of numbers, so poses blend, walk
5
7
  * cycles are functions of a phase, and every joint can be a timeline track.
@@ -46,6 +48,24 @@ export interface StickPose {
46
48
  /** Where the eyes look: -1..1 across (+ is the way the figure faces) and down (+) */
47
49
  lookX: number;
48
50
  lookY: number;
51
+ /**
52
+ * Squash and stretch: 1 normal, above 1 taller (a jump), below 1 squashed (a landing).
53
+ * The body and legs scale by it, the arms by its square root, and the head
54
+ * becomes an ellipse of the same area.
55
+ */
56
+ stretch: number;
57
+ /**
58
+ * How far the figure turns toward the way it faces: 0 front-on, 1 in
59
+ * profile. The face slides toward the facing side and narrows, and
60
+ * shoulders (with a `shoulderWidth`) close up. Turn walkers toward where they go.
61
+ */
62
+ turn: number;
63
+ /**
64
+ * 0 standing, 1 seated: the thighs swing forward to level, the shins hang
65
+ * straight down, and the hips drop to {@link seatHeight} above the feet. From
66
+ * 0.25 on, the lower foot rests on the ground.
67
+ */
68
+ sit: number;
49
69
  }
50
70
  export declare const REST_POSE: StickPose;
51
71
  /** A full pose from the fields that differ from rest. */
@@ -90,6 +110,9 @@ export declare const POSES: {
90
110
  handsOnHips: StickPose;
91
111
  sad: StickPose;
92
112
  surprised: StickPose;
113
+ crouch: StickPose;
114
+ sit: StickPose;
115
+ jump: StickPose;
93
116
  };
94
117
  export type PoseName = keyof typeof POSES;
95
118
  /** Linear blend: `t` 0 is `from`, 1 is `to`. */
@@ -121,6 +144,11 @@ export interface StickStyle {
121
144
  color?: string;
122
145
  /** Line width (default 2.5% of the height) */
123
146
  lineWidth?: number;
147
+ /**
148
+ * Head diameter as a fraction of the height (default 0.24). A bigger head
149
+ * takes its room from the torso: the feet and hips stay where they are.
150
+ */
151
+ headSize?: number;
124
152
  /** Head fill; `none` leaves it see-through (default white) */
125
153
  headFill?: string;
126
154
  /** 1 faces right, -1 faces left: mirrors the figure and turns the eyes */
@@ -129,9 +157,164 @@ export interface StickStyle {
129
157
  label?: string;
130
158
  /** Name tag font (default bold, 11% of the height, sans-serif) */
131
159
  labelFont?: string;
160
+ /** Draw in hand-drawn pencil strokes that boil (see `sketchPen`); omit for clean lines */
161
+ sketch?: SketchStyle;
162
+ /** Limbs: 0 straight segments jointed at elbows and knees (default), 1 smooth rubber-hose curves */
163
+ rubber?: number;
164
+ /**
165
+ * Half the shoulder width, as a fraction of the height (default 0: both arms
166
+ * come from one point on the spine). The shoulders sit either side of the
167
+ * spine and square to it, so they tilt with `lean`; a line joins them.
168
+ */
169
+ shoulderWidth?: number;
170
+ /**
171
+ * The 0.75 look: even straight-stroked lines, sharp elbows and knees, no
172
+ * hands or feet, and the hips held at a fixed height (feet can float off the
173
+ * ground mid-stride). Off by default: limbs taper, elbows and knees are
174
+ * always a little rounded (as `rubber` 0.3), hands and feet are drawn, the
175
+ * lower foot always rests on the ground (so a walk bobs), and the body leans
176
+ * into sitting down and standing up.
177
+ */
178
+ classic?: boolean;
179
+ /** Drawing hooks that put costumes, hair and props inside the figure's z-order */
180
+ layers?: FigureLayers;
132
181
  }
133
- /** Draw a figure with its feet at (0, 0). */
134
- export declare function drawStickFigure(ctx: CanvasRenderingContext2D, figure: StickPose, style?: StickStyle): void;
182
+ export type StickSide = 'left' | 'right';
183
+ /**
184
+ * Draws part of a figure: a costume, hair, a held prop. The context is in the
185
+ * figure's own space (feet at 0, 0, not mirrored), saved and restored around
186
+ * the call, with the figure's line colour and width set. `joints` are already
187
+ * mirrored for facing, so the hook draws at them directly. `pen` is given when
188
+ * the figure is sketched, so a costume boils with the line work; it is not the
189
+ * figure's own pen, so adding a costume does not change how the figure wobbles.
190
+ */
191
+ export type FigureLayer = (ctx: CanvasRenderingContext2D, joints: StickJoints, time: number, pen?: SketchPen) => void;
192
+ /** A {@link FigureLayer} for one arm's sleeve. */
193
+ export type SleeveLayer = (ctx: CanvasRenderingContext2D, joints: StickJoints, side: StickSide, time: number, pen?: SketchPen) => void;
194
+ /**
195
+ * Hooks called while a figure draws, so what they draw sits at the right depth.
196
+ * The order is:
197
+ *
198
+ * behind → legs → torso → body → back arm → sleeve(back) → front arm →
199
+ * sleeve(front) → behindHead → head and face → overHead → front → label
200
+ *
201
+ * The left arm is always the back arm, drawn first. The figure faces the
202
+ * viewer and is mirrored as a whole for `facing`, so its left side is always
203
+ * the one away from the way it looks.
204
+ */
205
+ export interface FigureLayers {
206
+ /** Before anything: long hair at the back, a cape, a shadow */
207
+ behind?: FigureLayer;
208
+ /** After the legs and torso, before the arms: a shirt, kurta, sari or trousers */
209
+ body?: FigureLayer;
210
+ /** Right after each arm, so each arm comes out of its own sleeve */
211
+ sleeve?: SleeveLayer;
212
+ /** After the arms, before the head: a bun, the root of a ponytail */
213
+ behindHead?: FigureLayer;
214
+ /** After the head and face: a hair cap, turban, crown, glasses, moustache */
215
+ overHead?: FigureLayer;
216
+ /** Last, before the label: a held prop in front of everything */
217
+ front?: FigureLayer;
218
+ }
219
+ /** The head as drawn: an ellipse, turned with the lean and head tilt. */
220
+ export interface StickHead {
221
+ center: Point;
222
+ /** Radii across and along the head (they differ when the figure stretches) */
223
+ rx: number;
224
+ ry: number;
225
+ /** Rotation of the head, radians, as seen on screen (lean + head tilt, mirrored for facing) */
226
+ angle: number;
227
+ /**
228
+ * Face features in head units, for {@link headPoint}: 0 is the centre, -1
229
+ * the top, 1 the bottom. Hair fringes sit above `browTopY`, a moustache
230
+ * between `eyeY` and `mouthY`.
231
+ */
232
+ eyeY: number;
233
+ /** The highest point of either brow for this pose (brows rise with surprise) */
234
+ browTopY: number;
235
+ mouthY: number;
236
+ /** Across the head, where the face is centred: it sits toward the facing side */
237
+ faceX: number;
238
+ }
239
+ /**
240
+ * Where every part of a figure is, as {@link drawStickFigure} draws it. Points
241
+ * are in the figure's space (feet at 0, 0, up is -y) and already mirrored for
242
+ * facing, so no `ctx.scale(-1, 1)` is needed to draw at them (that would mirror
243
+ * text too). Use {@link jointsToScene} to move them to where the feet stand.
244
+ */
245
+ export interface StickJoints {
246
+ facing: 1 | -1;
247
+ /** The style's height */
248
+ height: number;
249
+ /** Squash and stretch as drawn (clamped to 0.3..3) */
250
+ stretch: number;
251
+ lineWidth: number;
252
+ /** The pelvis: legs hang from it and the body leans about it */
253
+ hip: Point;
254
+ /** Top of the spine, after the lean */
255
+ neck: Point;
256
+ /** Where the arms start: one point when `shoulderWidth` is 0 */
257
+ shoulders: Record<StickSide, Point>;
258
+ elbows: Record<StickSide, Point>;
259
+ hands: Record<StickSide, Point>;
260
+ knees: Record<StickSide, Point>;
261
+ feet: Record<StickSide, Point>;
262
+ /** Tips of the feet, pointing the way the figure faces (the ankles, in the classic look) */
263
+ toes: Record<StickSide, Point>;
264
+ /** The lower foot's y: where the ground is under a figure standing, walking or sitting */
265
+ feetY: number;
266
+ /** Which feet are on the ground: within 1% of the height of the lower foot */
267
+ grounded: Record<StickSide, boolean>;
268
+ /** Direction the hand points (the forearm, along its curve for rubber hose), radians: for holding props */
269
+ handAngle: Record<StickSide, number>;
270
+ /** Each limb as the polyline that is stroked (rubber-hose curves included), for sleeves and trousers */
271
+ limbs: {
272
+ leftArm: Point[];
273
+ rightArm: Point[];
274
+ leftLeg: Point[];
275
+ rightLeg: Point[];
276
+ spine: Point[];
277
+ };
278
+ head: StickHead;
279
+ }
280
+ /**
281
+ * Height of the hips above the feet when a figure `height` px tall is fully
282
+ * seated (`sit` 1): put the top of a bench, log or charpai here.
283
+ */
284
+ export declare function seatHeight(height: number, stretch?: number): number;
285
+ /**
286
+ * Points along a limb, blending the jointed shape (two straight segments) into
287
+ * a rubber-hose curve by `rubber` 0..1. The curve is the quadratic that passes
288
+ * through the joint halfway along, so a bent limb keeps its bend, rounded.
289
+ */
290
+ export declare function rubberLimb(root: Point, joint: Point, end: Point, rubber: number, samples?: number): Point[];
291
+ /**
292
+ * Where every joint of a figure is, without drawing it: the same numbers
293
+ * {@link drawStickFigure} draws with. `figure` is the pose as drawn (use
294
+ * {@link resolveStickPose} to fold a target's walk and talk in first).
295
+ */
296
+ export declare function stickFigureJoints(figure: StickPose, style?: StickStyle): StickJoints;
297
+ /**
298
+ * A point on the head from head units: (0, 0) is the centre and ±1 the edges,
299
+ * x to the right on screen and y down, both turned with the head. For
300
+ * example, `headPoint(head, head.faceX, head.browTopY - 0.1)` is just above
301
+ * the brows.
302
+ */
303
+ export declare function headPoint(head: StickHead, x: number, y: number): Point;
304
+ /** Joints moved from the figure's space to a scene where its feet stand at (x, y). */
305
+ export declare function jointsToScene(joints: StickJoints, x: number, y: number): StickJoints;
306
+ /**
307
+ * Fill a line through `points` whose width runs from `startWidth` to
308
+ * `endWidth`, with round ends: a limb that tapers, or a sleeve or trouser leg
309
+ * along a joint polyline. Uses the context's fill style.
310
+ */
311
+ export declare function taperedLine(ctx: CanvasRenderingContext2D, points: Point[], startWidth: number, endWidth: number): void;
312
+ /**
313
+ * Draw a figure with its feet at (0, 0). `time` (ms) matters for a sketched
314
+ * style (it picks which boil frame of the wobble shows) and is passed to any
315
+ * `layers` hooks.
316
+ */
317
+ export declare function drawStickFigure(ctx: CanvasRenderingContext2D, figure: StickPose, style?: StickStyle, time?: number): void;
135
318
  /** Values a stick-figure target's tracks can animate, besides x/y/opacity/…. */
136
319
  export interface StickFigureProps extends StickPose {
137
320
  /** Walk cycle phase, in strides (animate it 0 → n for n strides) */
@@ -140,7 +323,14 @@ export interface StickFigureProps extends StickPose {
140
323
  walking: number;
141
324
  /** How much the mouth chatters, 0..1 */
142
325
  talk: number;
326
+ /** Limbs from jointed (0) to rubber hose (1); starts at the style's `rubber` */
327
+ rubber: number;
143
328
  }
329
+ /**
330
+ * The pose a stick-figure target draws at `time` ms: its props with the walk
331
+ * cycle (by `walking`) and the chatter of `talk` folded in.
332
+ */
333
+ export declare function resolveStickPose(props: StickFigureProps, time: number): StickPose;
144
334
  export interface StickFigureTargetOptions {
145
335
  /** Where the feet stand */
146
336
  x: number;
@@ -149,12 +339,31 @@ export interface StickFigureTargetOptions {
149
339
  pose?: Partial<StickPose>;
150
340
  style?: StickStyle;
151
341
  }
342
+ /** A `custom` target made by {@link stickFigureTarget}. */
343
+ export interface StickFigureTarget extends CustomTarget {
344
+ /** The style it draws with, so {@link stickFigureAt} can find its joints */
345
+ readonly figureStyle: StickStyle;
346
+ }
152
347
  /**
153
348
  * A `custom` canvas target that draws a stick figure. Its props are the pose
154
- * plus `walk`, `walking` and `talk`, so the timeline can pose, walk and voice
155
- * it. `x`/`y` here are the feet; the target's own box sits above them.
349
+ * plus `walk`, `walking`, `talk` and `rubber`, so the timeline can pose, walk,
350
+ * voice and loosen it. `x`/`y` here are the feet; the target's own box sits
351
+ * above them (a stretched figure reaches above its box).
156
352
  */
157
- export declare function stickFigureTarget(options: StickFigureTargetOptions): CustomTarget;
353
+ export declare function stickFigureTarget(options: StickFigureTargetOptions): StickFigureTarget;
354
+ /**
355
+ * The pose and scene-space joints of a {@link stickFigureTarget} in a frame, for
356
+ * immediate-mode drawing that follows it (a speech-bubble tail at the head, a
357
+ * pot carried on it). `id` is the target's key in the scene's `targets`, which
358
+ * is how the timeline's tracks address it.
359
+ *
360
+ * The figure's `x`/`y` tracks are followed; a `rotate` or `scale` on the
361
+ * target itself is not.
362
+ */
363
+ export declare function stickFigureAt(target: CustomTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string): {
364
+ pose: StickPose;
365
+ joints: StickJoints;
366
+ };
158
367
  export interface PoseKey {
159
368
  time: number;
160
369
  /** The pose here: a name, or joints to change from the previous key (default: no change) */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.74.1",
3
+ "version": "0.76.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",