M8.17: Edit envelopes on the canvas: Edit Contents, mesh points and handles, Control bar

- Edit Contents: while an envelope's contents are edited, clicks hit the
  content where it sits undistorted and the Selection tool selects it; the
  menu item reads Edit Envelope then. No default shortcut: the reference
  app's (Shift+Cmd+V) is Paste in Place here.
- A selected envelope shows its mesh (a warp's surface grid, a mesh's own,
  a top object's outline) instead of its content's outlines.
- Mesh envelope points get bezier handles (append-only; none stored is the
  smooth Catmull-Rom mesh, which the first handle edit fills in exactly
  along the grid lines). setMeshPoint takes `handle`; object.mesh.movePoint,
  addLine and deletePoint edit mesh envelopes too. The Mesh tool and Direct
  Selection drag points and the clicked point's handles (shared MeshEdit);
  the Mesh tool adds rows and columns inside mesh envelopes. Reset with
  Mesh keeps the shape along the grid with handles; Release returns the
  exact mesh.
- Control bar: Edit Envelope / Edit Contents, warp style, orientation,
  bend and distortions or mesh rows and columns, Reset, Envelope Options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/control-protocol.md

@@ -526,3 +526,9 @@ Perspective grid widgets: the Plane Switching Widget is fixed in a corner of the
 the grid shows. `ui.key` with `key` `"1"`…`"4"` picks the left, horizontal, right or no plane. Double-clicking the
 Perspective Grid tool (`tool.options {tool: "perspectiveGrid"}`) opens `perspectiveGridOptions` (fields `show`,
 `position`: `topLeft`, `topRight`, `bottomLeft`, `bottomRight`); `ui.dialog.confirm` runs `perspective.widget.options`.
+
+Envelopes on the canvas: `pointer_gesture` with the Mesh tool (`mesh`) or Direct Selection on a selected mesh envelope
+drags its points (a press on a point focuses it, and a press on one of the focused point's handle ends drags that
+handle); a Mesh tool click inside a mesh envelope adds a row and a column. While an envelope or its content is
+selected the Control bar shows its controls (Edit Envelope / Edit Contents, warp style, orientation, bend and
+distortions or mesh rows and columns, Reset, Envelope Options); each runs an `object.envelope.*` command.

docs/mcp.md

@@ -1960,7 +1960,6 @@ sits on; the first edit turns the spine into a path. Moving a key moves its end
 {"name":"run_command","arguments":{"command":"object.blend.spine.moveAnchor","params":{"id":40,"anchor":1,"x":150,"y":20}}}
 ```
 
-
 How blends interpolate: closed shapes start where they twist least unless `starts` picks the anchors; strokes
 interpolate weight, dashes (a solid stroke counts as the dashed one with its gaps closed), miter limit, arrowhead scale
 and width profiles, while caps, joins, alignment, arrowheads and brushes switch halfway; gradients of one kind with
@@ -1971,3 +1970,22 @@ symbol switch halfway). New blends are knockout groups (`object.setProps {knocko
 canvas as they export. `object.blend.expand` and `object.blend.release` keep the blend's name, transparency,
 opacity mask and appearance (Release on a group around the keys and spine when the blend has any), and
 `object.expand` with `object: true` expands the blends in the selection.
+
+## Editing envelopes
+
+`object.envelope.editContents {editing}` switches between editing the envelope and its contents (the menu item reads
+Edit Envelope while the contents are edited; it has no default shortcut, since the reference app's is Paste in Place
+here). While the contents are edited, clicks hit the content where it sits undistorted and the Selection tool selects
+it. A mesh envelope's points have bezier handles (`kind.handles`, offsets
+right/left/down/up; none stored means the smooth mesh through the points, as older files have):
+`object.envelope.setMeshPoint {id, index, x, y, handle?}` and `object.mesh.movePoint`, `object.mesh.addLine` and
+`object.mesh.deletePoint` edit them like a gradient mesh's (one undo step each). On the canvas a selected envelope
+shows its mesh; the Mesh tool and Direct Selection drag its points and the clicked point's handles, and the Mesh tool
+adds a row and a column where it clicks inside. The Control bar shows Edit Envelope / Edit Contents, the warp's
+style, orientation, bend and distortions (or the mesh's rows and columns), Reset (an unbent warp, a flat mesh) and
+Envelope Options.
+
+```json
+{"name":"run_command","arguments":{"command":"object.envelope.editContents","params":{"editing":true}}}
+{"name":"run_command","arguments":{"command":"object.mesh.movePoint","params":{"id":12,"index":4,"x":220,"y":140,"handle":0}}}
+```