@algorisys/tinyfly 0.91.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 (63) 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 +2785 -1794
  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 +6575 -5454
  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 +4 -0
  54. package/lib/types/characters/species/human-motion.d.ts +45 -0
  55. package/lib/types/characters/species/human.d.ts +2 -0
  56. package/lib/types/characters/stick-figure.d.ts +2 -0
  57. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  58. package/lib/types/engine/authoring/index.d.ts +1 -0
  59. package/llms-full.txt +12548 -0
  60. package/llms.txt +57 -0
  61. package/package.json +6 -2
  62. package/skills/tinyfly/SKILL.md +64 -0
  63. package/lib/addons/camera-C7bZOWMB.js +0 -33
package/docs/camera.md ADDED
@@ -0,0 +1,94 @@
1
+ # Camera — Phase B design
2
+
3
+ **Status:** In progress (foundation landed)
4
+ **Date:** 2026-07-22
5
+ **Roadmap:** [2d-animation-roadmap.md](2d-animation-roadmap.md) → Phase B
6
+
7
+ A **camera** animates a pan / zoom / rotate over the whole stage — cinematic
8
+ moves without touching your elements. True to tinyfly's "animation = a transform"
9
+ ethos, the camera is **just an animated element**: a reserved layer named
10
+ `Camera` that wraps the stage, driven by ordinary keyframe tracks.
11
+
12
+ ---
13
+
14
+ ## Model
15
+
16
+ No new data model. The camera is a set of tracks targeting the reserved name
17
+ **`Camera`** with the existing animatable properties:
18
+
19
+ | Track property | Effect on the stage |
20
+ |----------------|---------------------|
21
+ | `x`, `y` | Pan (translate the whole stage) |
22
+ | `scale` | Zoom (around the stage centre) |
23
+ | `rotate` | Rotate (around the stage centre) |
24
+
25
+ The preview wraps all elements in a `Camera` layer
26
+ (`<div data-tinyfly="Camera">`) registered with the DOM adapter, so those tracks
27
+ transform everything at once. With no `Camera` tracks the layer is identity —
28
+ completely inert — so nothing changes until you add a camera.
29
+
30
+ Because it's ordinary tracks + a named layer, the camera **serializes for free**
31
+ (it's in the timeline JSON), keyframes like any track, and — once the layer is
32
+ emitted — flows through export and embeds via the same adapters.
33
+
34
+ ---
35
+
36
+ ## Store API
37
+
38
+ ```ts
39
+ addCamera() // add x/y/scale/rotate tracks on "Camera", seeded at identity
40
+ removeCamera() // drop all Camera tracks
41
+ hasCamera() // is a camera present?
42
+ getCameraValue(prop) // current pan/zoom/rotate at the playhead
43
+ setCameraValue(prop, value) // keyframe a camera prop at the playhead (upsert)
44
+ ```
45
+
46
+ `addCamera` seeds each track with a keyframe at `0` and at the timeline's end, so
47
+ it's ready to keyframe. Keyframe the camera like any track (select a Camera
48
+ track, add/drag keyframes, edit values in the Property Panel).
49
+
50
+ **Camera inspector.** With a camera present and nothing selected, the Property
51
+ Panel shows a 🎥 **Camera** section with Pan X / Pan Y / Zoom / Rotation inputs.
52
+ Editing a field calls `setCameraValue`, which upserts a keyframe **at the
53
+ playhead** — so you scrub to a time, dial in the framing, and the pan/zoom is
54
+ recorded. "Reset to identity" and "Remove camera" live there too.
55
+
56
+ ---
57
+
58
+ ## Implementation slices
59
+
60
+ 1. **Foundation (this slice):** `Camera` layer in the **DOM preview** + store
61
+ `addCamera` / `removeCamera` / `hasCamera` + a **🎥 Camera** toggle in the
62
+ preview header. Camera animation plays in the DOM preview. Unit-tested.
63
+ 2. **Everywhere else (done):** the camera applies in the **Canvas** and **SVG**
64
+ previews, **raster export** (GIF/WebP/MP4), and **embeds** (single-scene via a
65
+ `Camera` wrapper the player animates; multi-scene via a per-scene camera layer
66
+ in the sequencer). `src/editor/utils/camera.ts` holds the shared transform math.
67
+ 3. **Camera inspector (done):** a 🎥 **Camera** section in the Property Panel
68
+ (shown when a camera exists and nothing is selected) with Pan X/Y, Zoom, and
69
+ Rotation inputs that keyframe at the playhead via `setCameraValue`, plus
70
+ "Reset to identity" / "Remove camera". Unit-tested.
71
+ 3b. **On-stage pan + timeline camera lane (done):** a **✋ Pan** toggle in the DOM
72
+ preview drops a drag overlay on the stage — dragging pans the camera 1:1 (its
73
+ pan is added in stage space after scale/rotate, so no inverse transform is
74
+ needed), writing x/y keyframes at the playhead via `setCameraValue`. The
75
+ timeline floats the Camera tracks to the top as a distinct 🎥 lane. Corner-zoom
76
+ and a rotate handle stay numeric in the inspector (they need the inverse
77
+ transform); a full draggable frame with those is a later refinement.
78
+ 4. **Edit-in-camera correctness:** element drag/resize math accounts for the
79
+ current camera transform (today, edit at the camera's start/identity frame).
80
+
81
+ ---
82
+
83
+ ## Known limitations (foundation)
84
+
85
+ - Editing elements while the playhead sits on a **camera-transformed** frame is
86
+ approximate — the drag math assumes identity. Set up your scene first, then
87
+ keyframe the camera (slice 4 fixes this).
88
+
89
+ ---
90
+
91
+ ## Non-goals
92
+
93
+ - Multiple cameras / camera switching (one camera per scene).
94
+ - Depth / parallax layers (possible later via per-layer camera influence).
@@ -0,0 +1,96 @@
1
+ # Cartoon hands
2
+
3
+ A hand you can pose: a palm and five fingers built in the hand's own 3D space,
4
+ posed by a flat record of numbers, turned and drawn flat in any look (clean,
5
+ pencil, silhouette). Because the hand is 3D, turning the wrist needs no extra
6
+ drawing code: fingers behind the palm are drawn behind it, and nails show only
7
+ where they face you.
8
+
9
+ ![Every hand shape, turned and in every look](model-sheet/hand-shapes.png)
10
+
11
+ The sheet is `examples/headless-video/hand-shapes.mjs`.
12
+
13
+ ```js
14
+ import { drawCartoonHand, HAND_SHAPES, mixHandPoses } from '@algorisys/tinyfly/characters'
15
+
16
+ // The wrist at (200, 300), fingers pointing up, 120 px from wrist to fingertip.
17
+ drawCartoonHand(ctx, { x: 200, y: 300 }, HAND_SHAPES.point, { size: 120 })
18
+
19
+ // A left hand in pencil, palm toward us, pointing up and to the right.
20
+ drawCartoonHand(ctx, { x: 400, y: 300 }, { ...HAND_SHAPES.wave, turn: 2 }, { side: 'left', look: 'pencil', angle: 30 }, time)
21
+
22
+ // Halfway from a fist to an open hand.
23
+ drawCartoonHand(ctx, at, mixHandPoses(HAND_SHAPES.fist, HAND_SHAPES.open, 0.5))
24
+ ```
25
+
26
+ ## The pose
27
+
28
+ Every field is a number, so two poses blend and any field can be a timeline track.
29
+
30
+ | Field | Meaning |
31
+ |---|---|
32
+ | `index.curl`, `middle.curl`, `ring.curl`, `pinky.curl` | 0 straight, 1 curled into the palm |
33
+ | `thumb.curl` | 0 straight, 1 bent at both knuckles |
34
+ | `thumb.across` | 0 out to the side, 1 across the palm |
35
+ | `spread` | 0 fingers together, 1 fanned wide |
36
+ | `turn` | Wrist turn: 0 back of the hand toward you, 1 thumb side, 2 palm, -1 little-finger side |
37
+ | `bend` | Wrist bend, degrees: + toward the palm |
38
+ | `tilt` | Wrist tilt, degrees: + toward the little finger |
39
+ | `roll` | The whole hand turned in the picture, degrees clockwise (a left hand turns the mirror way) |
40
+
41
+ `handPose(changes)` gives a full pose from the fields that differ from rest
42
+ (`HAND_REST`, a relaxed hand).
43
+
44
+ ### Shapes
45
+
46
+ `HAND_SHAPES`: `relaxed`, `open`, `spread`, `flat`, `fist`, `point`,
47
+ `thumbsUp`, `peace`, `ok`, `pinch`, `cupped`, `wave`, `pencilGrip` (thumb and
48
+ middle finger pinch, index on top) and `hold` (every finger wrapped round a
49
+ handle). Change single fields on top: `{ ...HAND_SHAPES.point, turn: 2 }`.
50
+
51
+ ## The style
52
+
53
+ | Option | Meaning |
54
+ |---|---|
55
+ | `size` | Wrist to the tip of the middle finger, px (default 100) |
56
+ | `side` | `'right'` (default) or `'left'`: the left hand is the right mirrored |
57
+ | `angle` | Which way the fingers point, degrees clockwise from straight up |
58
+ | `fingers` | `5` (default) or `4`: a thumb and three, the classic cartoon glove |
59
+ | `plump` | 1 a natural hand (default); 1.5 a fat cartoon glove |
60
+ | `skin`, `ink`, `lineWidth` | Fill, outline colour and outline width; a glove is just another skin |
61
+ | `look`, `seed`, `pencil` | The look, when no `pen` is given |
62
+ | `pen` | Draw with a character's pen, so the hand matches and boils with it |
63
+ | `nails` | Nails on fingertips that face you (default true) |
64
+ | `prop` | `{ depth, draw(pen) }`: something held, drawn among the fingers at its depth |
65
+
66
+ ## Joints, for props and attachments
67
+
68
+ `handJoints(pose, style)` returns where everything is with the wrist at (0, 0)
69
+ (`handJointsAt` moves it): each finger's joints, depths and widths, the palm
70
+ outline, which way the palm faces, and the hand's own axes on screen.
71
+ `drawCartoonHand` returns the same, as drawn. Use the fingertips to place a
72
+ prop, or the depths to slot it between fingers.
73
+
74
+ ## Where hands are used
75
+
76
+ - **The animator's hand.** `drawHand(ctx, tip, { tool, lift })` is this hand
77
+ in its `pencilGrip`, holding a pencil or an eraser between the thumb and
78
+ fingers, with a forearm whose sleeve fades out. `handAt(strokes, time)` moves
79
+ one hand through a whole scene: it follows each stroke, lifts and glides to
80
+ the next, and comes in and leaves the page.
81
+ - **Characters.** `character({ hands: 'cartoon' })` puts gloved hands on the
82
+ fluid figure (four fingers, plump, `handSize` 0.17 of the height). Each hand
83
+ takes its pose from `hand.left.*` / `hand.right.*` fields in the character's
84
+ pose (`'hand.right.index.curl': 0`), so hands are tracks like everything
85
+ else. `hand.<side>.turn` is relative to how a hand hangs at the side (thumb
86
+ forward); `characterHandPose(pose, side)` shows what a hand will get.
87
+ `handStyle: 'natural'` draws five slimmer fingers instead of the glove
88
+ (`handSize` 0.14), so shapes like mudras read finger by finger.
89
+
90
+ ## Not yet
91
+
92
+ - The editor's Character element takes hand shapes from dances (Hands: Cartoon
93
+ gloves or Natural); there is no hand-shape picker for single poses yet.
94
+ - A forearm pointing straight at the viewer does not foreshorten the hand.
95
+ - The v1 stick figure draws these hands with `style.hands`; see
96
+ [Dance and Flips](dance.md).
@@ -0,0 +1,218 @@
1
+ # Character System — Milestone 1: rig core (design)
2
+
3
+ **Status:** Built on `feat/character-v2`, for review (core and the editor's character element)
4
+
5
+ ![Human turnaround sheet](model-sheet/human-turnaround.png)
6
+
7
+ ## Built so far
8
+
9
+ | Piece | Where |
10
+ |---|---|
11
+ | Body plans, chains, bone angles | `src/characters/rig/body-plan.ts` |
12
+ | Skeleton: 3D bones, turn, roll, contact, lift | `src/characters/rig/skeleton.ts` |
13
+ | Reaching (two-bone, exact) | `src/characters/rig/reach.ts` |
14
+ | The human plan, rest pose, 10 named poses | `src/characters/species/human.ts` |
15
+ | Pen: clean, pencil (boil, pressure, construction lines, rubbed-out attempts), silhouette | `src/characters/look/pen.ts` |
16
+ | Face on the head, sliding round with the turn | `src/characters/head/face.ts` |
17
+ | `character()`, `drawCharacter()`, `characterJoints()`, `characterTarget()`, `characterAt()`, `reachCharacter()`, `mixPoses()` | `src/characters/character.ts` |
18
+ | Tests (joints vs drawing, turn invariants, depth order, contact, reach, determinism, looks) | `src/characters/character.test.ts` |
19
+ | Model sheet | `examples/headless-video/human-turnaround.mjs` → `docs/model-sheet/human-turnaround.png` |
20
+
21
+ `taperedLine` and `rubberLimb` moved to `src/characters/look/` (re-exported
22
+ from the v1 module unchanged) so v2 does not depend on v1. v1's tests and
23
+ golden frames pass unchanged.
24
+
25
+ ### The editor's character element
26
+
27
+ | Piece | Where |
28
+ |---|---|
29
+ | `character` element type (figure, look, colours, outfit, pose) | `src/editor/stores/scene-store.ts` |
30
+ | Element → character, pose at a time, canvas target, DOM canvas | `src/editor/utils/character-element.ts` |
31
+ | 🧍 Character in the Elements panel (centred, sized to the canvas) | `src/editor/components/element-panel.tsx` |
32
+ | DOM preview canvas, repainted with the animated pose | `src/editor/components/preview-panel.tsx` |
33
+ | Canvas preview and GIF / MP4 export | `src/editor/utils/scene-to-canvas.ts` |
34
+ | Character section: figure, look, colours, clothes, view, body, face, ◆ keyframe | `src/editor/components/property-panel.tsx` |
35
+ | Key a pose at the playhead in one undo step | `keyValuesAtPlayhead` in `src/editor/stores/editor-store.ts` |
36
+ | Plain-language track names | `trackPropertyLabel` (timeline, track list, curves) |
37
+
38
+ The library gained `characterPoseTracks()` (timed poses to tracks),
39
+ `humanFieldLabel()`, `HUMAN_EXPRESSIONS` and `basicOutfit()` (a T-shirt and
40
+ trousers whose sleeves grow out of the shoulders), and the whole-figure roll
41
+ field is `roll` (not `rotate`, which turns an element's box).
42
+
43
+ Not yet: characters in exported HTML / embeds and in the SVG preview.
44
+
45
+ ### Not done yet in milestone 1
46
+
47
+ - **Faces in profile** use a cartoon mapping (the face shifts toward the side
48
+ it faces) rather than the true sphere, so a profile keeps an eye and a mouth;
49
+ noses and profile mouths come with milestone 3.
50
+ - **Reaching** is exact for two-bone limbs; long chains come with the animals.
51
+ **Plan:** [character-system-plan.md](character-system-plan.md)
52
+
53
+ Milestone 1 builds the skeleton every later character uses, and a human on it,
54
+ drawn in three looks (clean, pencil, silhouette) and two figure styles (stick,
55
+ fluid). It ends with a turnaround model sheet.
56
+
57
+ ---
58
+
59
+ ## Space and turning
60
+
61
+ A character is built in its own 3D space, measured from the ground under its
62
+ hips:
63
+
64
+ - **+x** is the character's **left**, **+y** is up, **+z** is the way it faces.
65
+ - `turn` spins it about the vertical axis by `turn × 90°`: **0** faces the
66
+ viewer, **1** faces screen-right (profile), **2** shows its back, **3** faces
67
+ screen-left. Any value works (0.5 is a 3/4 view; -1 is the same as 3).
68
+ - The view is orthographic: screen x = x·cos θ + z·sin θ, screen y = −y, and
69
+ **depth** (toward the viewer) = −x·sin θ + z·cos θ.
70
+
71
+ With +x as the character's left, its left arm is on screen-right in the front
72
+ view (as a real person facing you) and is the far arm when it faces right.
73
+
74
+ ## Body plans, chains and bones
75
+
76
+ ```ts
77
+ interface BoneSpec { length: number; width: [number, number] } // fractions of height
78
+ interface ChainSpec {
79
+ id: string // 'spine', 'neck', 'arm.left', 'leg.right'
80
+ parent: string | null // chain it hangs from (null: the hips)
81
+ at?: number // parent joint index (default: its end)
82
+ offset?: [number, number, number] // from that joint, fractions of height
83
+ rest: [number, number, number] // direction of the first bone at rest
84
+ bones: BoneSpec[]
85
+ side?: -1 | 1 // right (-1) or left (+1): sets which way "spread" goes
86
+ }
87
+ interface BodyPlan { id: string; chains: ChainSpec[]; head: HeadSpec; contacts: ContactSpec[] }
88
+ ```
89
+
90
+ ### Bone angles
91
+
92
+ Each bone's direction comes from its chain's rest direction, turned by two
93
+ angles in degrees:
94
+
95
+ - **swing**: forward (+) and back (−), about the character's x axis;
96
+ - **spread**: away from the body (+) and across it (−), about its z axis.
97
+
98
+ A bone's angles add to its parent bone's, as v1's elbow adds to its shoulder.
99
+ Direction = Rz(spread · side) · Rx(swing) · rest. Seen from the front only the
100
+ spread shows; seen from the side only the swing. This is what fixes the
101
+ "arms forward and back in profile" problem.
102
+
103
+ ## Pose
104
+
105
+ A pose is a flat record of numbers, so poses blend and every field can be a
106
+ timeline track. The human's fields:
107
+
108
+ | Field | Meaning |
109
+ |---|---|
110
+ | `turn` | View, as above |
111
+ | `lean`, `side` | Upper body: forward/back and sideways bend, degrees |
112
+ | `head.turn`, `head.nod`, `head.tilt` | Head yaw on the body, pitch, roll |
113
+ | `arm.left.swing`, `arm.left.spread`, `arm.left.elbow` | Upper arm, and the elbow (forearm swings forward) |
114
+ | `leg.left.swing`, `leg.left.spread`, `leg.left.knee` | Thigh, and the knee (shin swings back) |
115
+ | `leg.left.ankle`, `leg.left.toeOut` | Foot tilt (toes up +), and the foot turned out (+) or in (−) from its natural angle |
116
+ | `leg.left.rotate` | The whole leg turned out at the hip, degrees: at 90 a bent knee points sideways (a turned-out plié) |
117
+ | `stretch` | Squash and stretch, as v1 |
118
+ | `lift` | Height above the surface, fraction of height (a jump) |
119
+ | `roll` | Whole-figure roll in the picture plane, degrees (falling, lying). Not `rotate`, which turns an element's box |
120
+ | `mouth`, `smile`, `mouthWidth`, `blink`, `eye.left`, `eye.right`, `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` | Face, as v1 |
121
+
122
+ (`.right` fields as `.left`.)
123
+
124
+ ## Placing on a surface
125
+
126
+ After the pose is projected and rolled by `roll` (about the hips), the
127
+ lowest **contact point** rests on the ground (y = 0): toes and heels, knees,
128
+ hands, elbows, hips, the head. Lying down, kneeling and crawling are then just
129
+ poses. `lift` raises the figure above that. `contact: 'none'` turns placement
130
+ off (a figure in the air keeps its hips at standing height).
131
+
132
+ ## Reaching
133
+
134
+ `reachPose(character, pose, 'arm.left', target)` returns the pose with that
135
+ limb's angles solved so its end touches `target` (a point in character space,
136
+ or a screen point given a depth). Two-bone limbs are solved exactly, bending
137
+ the elbow down and back and the knee forward; out of reach, the limb points
138
+ straight at the target. Long chains (tails, trunks) come with the animals.
139
+
140
+ ## Drawing
141
+
142
+ 1. Solve the bones (forward kinematics), project, roll, place.
143
+ 2. Build **parts**: each chain is one part with a depth (its average); the head
144
+ is a part. Sort far to near; ties keep the plan's order (legs, torso, arms,
145
+ head), so arms in front of the chest stay in front.
146
+ 3. Draw each part with the figure style and the pen, calling layer hooks:
147
+ `layers: { [partId]: { under?, over? } }`, plus `behind` and `front` for
148
+ the whole figure. A sleeve on the far arm is behind the body because the
149
+ arm is.
150
+
151
+ ### Figure styles
152
+
153
+ - **`stick`**: the traditional (Pencilmation) stick figure: even lines, a
154
+ circle head, one point for the shoulders and hips, no hands or feet.
155
+ - **`fluid`**: tapered limbs, small hands, feet, rounded shoulders. Clothes
156
+ and hair are layers on top (wardrobe is milestone 4).
157
+
158
+ ### Looks: the Pen
159
+
160
+ ```ts
161
+ interface Pen {
162
+ readonly look: 'clean' | 'pencil' | 'silhouette'
163
+ limb(points: Point[], from: number, to: number): void // tapered stroke
164
+ line(points: Point[], width?: number): void // even stroke
165
+ shape(points: Point[], fill: string): void // closed, filled, outlined
166
+ ellipse(cx: number, cy: number, rx: number, ry: number, angle: number, fill?: string): void
167
+ dot(x: number, y: number, r: number): void
168
+ }
169
+ ```
170
+
171
+ Every part, and every layer hook, draws through the pen it is handed:
172
+
173
+ - **clean**: filled tapered shapes and canvas strokes.
174
+ - **pencil**: graphite strokes in passes that boil (the existing `sketchPen`
175
+ wobble), **pressure variation** along each stroke (seeded, so a stroke is the
176
+ same every frame of its boil), **construction lines** (the skeleton's guide
177
+ shapes, faint, under the final line: the head circle with its centre lines, a
178
+ torso line, joint circles), and **rubbed-out lines** (a few earlier attempts,
179
+ faint and smudged, offset from the final line). All seeded by the
180
+ character's seed, the boil frame and the stroke's order.
181
+ - **silhouette**: everything filled in the ink colour, for the readability
182
+ check.
183
+
184
+ ### Head
185
+
186
+ The head is an ellipsoid (a sphere stretched by `stretch`). Face features
187
+ (eyes, brows, mouth) have a position on its surface, an angle around from the
188
+ front and an angle up. They are drawn where the head's yaw (`turn` plus
189
+ `head.turn`) puts them, narrowed as they turn away, and hidden on the far side,
190
+ so the face slides round in 3/4, shows one eye in profile and disappears at the
191
+ back. Eye, brow and nose styles, ears and lip-sync shapes are milestone 3.
192
+
193
+ ## Public API (milestone 1)
194
+
195
+ ```ts
196
+ const hero = character({ figure: 'fluid', look: 'clean', height: 400, ink: '#2b1d16', skin: '#f2c49b', layers })
197
+ drawCharacter(ctx, hero, pose, time) // feet at (0, 0)
198
+ characterJoints(hero, pose) // every point, part and depth, as drawn
199
+ characterTarget({ x, y, character: hero, pose }) // a canvas custom target; pose fields are props
200
+ characterAt(target, frame, id) // its joints in a frame, for draw()
201
+ humanPose(changes) // a full pose from the fields that differ from rest
202
+ mixPoses(a, b, t) // blend
203
+ reachPose(hero, pose, chain, target) // IK
204
+ ```
205
+
206
+ Defaults are the bold look: head 30% of the height, line 4.5% of the height.
207
+ `proportions: 'thin'` gives the reference sheets' lighter line and 24% head.
208
+
209
+ ## Tests
210
+
211
+ - Joints match drawing (recorded canvas calls vs `characterJoints`).
212
+ - Turn invariants: `turn` 2 is `turn` 0 mirrored with the face hidden; `turn`
213
+ 1 and 3 mirror each other; arms spread sideways vanish edge-on in profile.
214
+ - Contact: the lowest contact point is at y = 0 for every pose.
215
+ - Reach: within 0.5 px when in reach.
216
+ - Determinism: the pencil look draws identically twice for the same time, and
217
+ changes between boil frames.
218
+ - v1's golden frames and tests are untouched.