pen pressure

lib/doc.md

@@ -105,14 +105,26 @@ Scales **Test** preview waits only. Plot is paced by Marlin (`ok` + `M400`).
 
 Clear the path buffer. Returns `this`.
 
-### `move(x, y)`
+### `move(x, y, pressure?)`
 
 Queue pen-up travel to `(x, y)` mm. Returns `this`.
 
-### `draw(x, y)`
+- `pressure` (number, optional): **0–100**. Mapped linearly onto the `S` values of `penUpGcode` (0) and `penDownGcode` (100). Default **0** (pen fully up).
+
+### `draw(x, y, pressure?)`
 
 Queue pen-down stroke to `(x, y)` mm. Returns `this`.
 
+- `pressure` (number, optional): **0–100**, same mapping as `move`. Default **100** (pen fully down). Use values in between for lighter contact.
+
+```javascript
+wp.startPath();
+wp.move(-200, -200);
+wp.draw(200, -200, 40);  // light
+wp.draw(200, 200, 100);  // full down
+await wp.runPath(false);
+```
+
 ### `wait(ms)`
 
 Queue a pause. `ms` is milliseconds. On Plot, sends `G4 P<ms>`. Returns `this`.
@@ -182,7 +194,11 @@ Write one G-code line and wait for Marlin `ok`.
 
 ### `penUp(force?)` / `penDown(force?)`
 
-Send pen G-code and wait the pen delay. By default, no-op if already in that state. Pass `true` to always send (used by `P` and on connect) so you can test the configured angles.
+Send pen G-code and wait the pen delay. By default, no-op if already at that pressure. Pass `true` to always send (used by `P` and on connect) so you can test the configured angles. `penUp` is pressure **0**, `penDown` is pressure **100**.
+
+### `setPressure(pressure)`
+
+Set servo pressure immediately (**0–100**). Same mapping as `move`/`draw`: **0** = `penUpGcode` `S`, **100** = `penDownGcode` `S`. Waits the pen delay.
 
 ### `screenToPlot(px, py, options?)`
 
@@ -192,13 +208,17 @@ Convert canvas pixel coordinates to plot coordinates in mm.
 - `options.clamp` (boolean, default `true`): clamp result to bounds.
 - `options.useDisplayBounds` (boolean, default `false`): use current display bounds (preview when disconnected) instead of machine bounds.
 
-### `moveTo(x, y)`
+### `moveTo(x, y, pressure?)`
 
-Pen up, travel to `(x, y)` mm immediately (not queued), then wait for motion completion (`M400`). Requires home.
+Pen up (or optional pressure), travel to `(x, y)` mm immediately (not queued), then wait for motion completion (`M400`). Requires home.
 
-### `drawTo(x, y)`
+- `pressure` (number, optional): **0–100**. Default **0**.
 
-Pen down, draw to `(x, y)` mm immediately, then wait for motion completion (`M400`). Requires home.
+### `drawTo(x, y, pressure?)`
+
+Pen down (or optional pressure), draw to `(x, y)` mm immediately, then wait for motion completion (`M400`). Requires home.
+
+- `pressure` (number, optional): **0–100**. Default **100**.
 
 ### `goToZero()`
 
@@ -224,7 +244,8 @@ Relative move in mm.
 | `connected` | Serial open |
 | `homeSet` | Home was set with `H` / `setHomeHere()` |
 | `x`, `y` | Current position, mm |
-| `isPenDown` | Pen state |
+| `isPenDown` | Pen is below fully-up (pressure > 0) |
+| `penPressure` | Last servo pressure, **0–100** |
 | `isPlotting` | `runPath` in progress |
 | `isPaused` | `runPath` is paused |
 | `feedRateTravel` / `feedRateDraw` | Current speeds, mm/min |