From 2ac52ecc92c7d162379a348e7548cda05a40527f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 21 May 2026 20:08:40 +0000
Subject: [PATCH] Fix turtle-lib API docs and invariant wording

Agent-Logs-Url: https://github.com/enaut/turtlers/sessions/5fb2f5ed-163f-4c2d-8180-1e96150e7e46

Co-authored-by: enaut <290005+enaut@users.noreply.github.com>
---
 turtle-lib/src/builders.rs | 15 +++++++++++++--
 turtle-lib/src/commands.rs |  3 ++-
 turtle-lib/src/general.rs  |  6 +++++-
 turtle-lib/src/lib.rs      |  4 ++--
 4 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/turtle-lib/src/builders.rs b/turtle-lib/src/builders.rs
index 3088c78..1cc5ec8 100644
--- a/turtle-lib/src/builders.rs
+++ b/turtle-lib/src/builders.rs
@@ -349,6 +349,10 @@ impl TurtlePlan {
     /// - `180°` points left (west)
     /// - `270°` points down (south)
     ///
+    /// Internally, turtle heading is stored in radians in a Y-down render space.
+    /// This method converts from user-facing degrees (Y-up mental model) to that
+    /// internal representation.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -366,6 +370,8 @@ impl TurtlePlan {
     /// }
     /// ```
     pub fn set_heading<T: Into<Degrees>>(&mut self, heading: T) -> &mut Self {
+        // Convert user-facing turtle heading (degrees, Y-up mental model)
+        // to internal radians used by the render-space pipeline.
         self.queue
             .push(TurtleCommand::SetHeading(-heading.into().as_radians()));
         self
@@ -610,11 +616,14 @@ impl TurtlePlan {
     /// The turtle moves in a straight line to the specified coordinates.
     /// If the pen is down, a line is drawn. The turtle's heading is not changed.
     ///
-    /// Coordinates are in screen space:
+    /// Coordinates use turtle-style Cartesian space:
     /// - `(0, 0)` is at the center
     /// - Positive x goes right
     /// - Positive y goes up
     ///
+    /// Internally, Macroquad uses Y-down screen coordinates; this command
+    /// performs the Y-axis conversion when executed.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -677,7 +686,7 @@ impl TurtlePlan {
 
     /// Resets the turtle to its default state.
     ///
-    /// This clears all drawings, clears the animation queue, and resets all turtle parameters:
+    /// This clears all drawings, clears active fill state, and resets turtle parameters:
     /// - Position: (0, 0)
     /// - Heading: 0° (facing right)
     /// - Pen: down
@@ -688,6 +697,8 @@ impl TurtlePlan {
     /// - Shape: arrow
     /// - Speed: default
     ///
+    /// Note: queued commands are not removed; `reset()` itself is a command in the queue.
+    ///
     /// # Examples
     ///
     /// ```no_run
diff --git a/turtle-lib/src/commands.rs b/turtle-lib/src/commands.rs
index 10468bb..4e60d10 100644
--- a/turtle-lib/src/commands.rs
+++ b/turtle-lib/src/commands.rs
@@ -34,7 +34,8 @@ pub enum TurtleCommand {
 
     // Position
     Goto(Coordinate),
-    /// Heading stored as radians — already converted by the builder.
+    /// Heading stored as internal radians (Y-down render-space convention),
+    /// already converted by the builder from user-facing degrees.
     SetHeading(Radians),
 
     // Visibility
diff --git a/turtle-lib/src/general.rs b/turtle-lib/src/general.rs
index 4ad3133..b399104 100644
--- a/turtle-lib/src/general.rs
+++ b/turtle-lib/src/general.rs
@@ -13,7 +13,11 @@ pub use length::Length;
 /// Precision type for calculations
 pub type Precision = f32;
 
-/// 2D coordinate in screen space
+/// 2D coordinate value (`Vec2`) used by turtle commands and state.
+///
+/// Coordinate orientation depends on API context:
+/// - `go_to()` input uses turtle-style coordinates (Y+ is up)
+/// - internal render-space state uses Macroquad-style Y-down coordinates
 pub type Coordinate = Vec2;
 
 /// Visibility flag for turtle
diff --git a/turtle-lib/src/lib.rs b/turtle-lib/src/lib.rs
index d572f3e..a52a04e 100644
--- a/turtle-lib/src/lib.rs
+++ b/turtle-lib/src/lib.rs
@@ -215,7 +215,7 @@ impl TurtleApp {
     ///
     /// Speed is controlled by `SetSpeed` commands in the queue.
     /// Use `set_speed()` on the turtle plan to set animation speed.
-    /// Speed >= 999 = instant mode, speed < 999 = animated mode.
+    /// Speed >= 1000 = instant mode, speed < 1000 = animated mode.
     ///
     /// # Arguments
     /// * `queue` - The command queue to execute
@@ -228,7 +228,7 @@ impl TurtleApp {
     ///
     /// Speed is controlled by `SetSpeed` commands in the queue.
     /// Use `set_speed()` on the turtle plan to set animation speed.
-    /// Speed >= 999 = instant mode, speed < 999 = animated mode.
+    /// Speed >= 1000 = instant mode, speed < 1000 = animated mode.
     ///
     /// # Arguments
     /// * `turtle_id` - The ID of the turtle to control