@franzenzenhofer/asanakit 0.3.0 → 0.5.0

package/docs/AUTHORING.md

@@ -53,21 +53,47 @@ joints:
   shinR: 60             # knee bends 60° (backward - the only way a knee goes)
 ```
 
-The object form adds the other two anatomical axes:
+The object form speaks the full anatomical vocabulary - every axis by both of its names:
 
 ```yaml
 joints:
-  upperArmL: { abduct: 90 }              # arm straight out to the side
+  upperArmL: { abduct: 90 }                          # arm straight out to the side
   thighR:    { flex: 45, abduct: 30, twist: 20 }
+  upperArmR: { extend: 30 }                          # arm reaches behind the body
+  thighL:    { adduct: 15, internalRotation: 10 }
 ```
 
-- `flex` - forward bend for hips/arms/spine, backward for knees, toes-up for ankles.
-- `abduct` - away from the midline, on either side. Center bones lean toward the figure's left.
-- `twist` - about the bone: positive is **external rotation** (toes/palms turn outward);
-  for center bones, turning toward the figure's left.
-
-The signs are per-side anatomical, so a mirrored pose is literally the same numbers with
-L and R swapped - which is what `mirror: true` does.
+- `flex` / `extend` - flexion and extension. Flexion is forward bend for hips/arms/spine,
+  backward for knees, toes-up (dorsiflexion) for ankles; extension is its opposite.
+- `abduct` / `adduct` - away from / toward the midline, on either side. Center bones lean
+  toward the figure's left on positive `abduct` (lateral flexion).
+- `twist`, or `externalRotation` / `internalRotation` by name - rotation about the bone.
+  Positive `twist` is external rotation (toes/palms turn outward); for center bones,
+  turning toward the figure's left (axial rotation).
+
+Naming both directions of one axis (`flex` AND `extend`) is a contradiction and fails
+loudly. The signs are per-side anatomical, so a mirrored pose is literally the same
+numbers with L and R swapped - which is what `mirror: true` does.
+
+### How classic movement terms map onto the format
+
+| You say | You write |
+|---|---|
+| hip flexion / extension | `thighL: { flex: … }` / `{ extend: … }` |
+| knee flexion | `shinL: 60` (knees only flex; the validator rejects the other way) |
+| ankle dorsiflexion / plantarflexion | `footL: { flex: … }` / `{ extend: … }` |
+| foot turnout (out-toeing) | `footL: { abduct: … }` or `thighL: { externalRotation: … }` |
+| shoulder flexion (arm forward-up) | `upperArmL: { flex: … }` |
+| shoulder abduction (arm sideways-up) | `upperArmL: { abduct: … }` |
+| shoulder internal/external rotation | `upperArmL: { internalRotation: … }` / `{ externalRotation: … }` |
+| elbow flexion | `forearmL: 90` |
+| forearm pronation / supination | `forearmL: { internalRotation: … }` / `{ externalRotation: … }` |
+| scapular elevation (shrug) | `clavicleL: { abduct: … }` |
+| scapular protraction / retraction | `clavicleL: { flex: … }` / `{ extend: … }` |
+| spinal flexion (forward fold) / extension (backbend) | `spine: { flex: … }` / `{ extend: … }` |
+| spinal lateral flexion (side bend) | `spine: { abduct: … }` (positive = toward the figure's left) |
+| spinal / cervical rotation (twist) | `spine: { twist: … }`, `neck: { twist: … }` |
+| hip abduction / adduction | `thighL: { abduct: … }` / `{ adduct: … }` |
 
 ### The root
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@franzenzenhofer/asanakit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Programmatic stick-figure and body-posture visualization engine for yoga and surf. Declarative 3D pose format, deterministic any-angle SVG/PNG, interactive three.js viewer, GLB export, Rapier physics settling. CLI-first, AI-driveable.",
   "keywords": [
     "yoga",

package/poses/yoga/ashtanga/prasarita-padottanasana-a.pose.yaml

@@ -40,6 +40,7 @@ figure:
     handR: { azimuth: -90, elevation: -8 }
 props:
   - type: mat
+    yaw: 90
 muscles:
   engaged: [ quadriceps, rectusAbdominis, deltoid ]
   stretched: [ hamstrings, adductors, erectorSpinae, gastrocnemius ]

package/poses/yoga/ashtanga/prasarita-padottanasana-c.pose.yaml

@@ -40,6 +40,7 @@ figure:
     handR: { azimuth: 90, elevation: 75 }
 props:
   - type: mat
+    yaw: 90
 muscles:
   engaged: [ quadriceps, deltoid, trapezius ]
   stretched: [ hamstrings, adductors, pectoralis, deltoid ]

package/poses/yoga/ashtanga/utthita-parsvakonasana.pose.yaml

@@ -38,6 +38,7 @@ figure:
     handR: { azimuth: 90, elevation: 30 }
 props:
   - type: mat
+    yaw: 90
 muscles:
   engaged: [ quadriceps, gluteus, obliques, deltoid ]
   stretched: [ adductors, latissimus, obliques, hipFlexors ]

package/poses/yoga/ashtanga/utthita-trikonasana.pose.yaml

@@ -38,6 +38,7 @@ figure:
     handR: { azimuth: -90, elevation: 80 }
 props:
   - type: mat
+    yaw: 90
 muscles:
   engaged: [ quadriceps, obliques, deltoid, erectorSpinae ]
   stretched: [ hamstrings, adductors, obliques, latissimus ]

package/poses/yoga/ashtanga/virabhadrasana-b.pose.yaml

@@ -34,6 +34,7 @@ figure:
     handR: { azimuth: -90, elevation: 0 }
 props:
   - type: mat
+    yaw: 90
 muscles:
   engaged: [ quadriceps, gluteus, adductors, deltoid ]
   stretched: [ adductors, hipFlexors, pectoralis ]