Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Docs: joint flip needs x for point origins; checkpoints are single use, 16 kept (#9746) (#9844)

thocsmith3b77567932f8
diff --git a/crates/engine/src/cmd/edit.rs b/crates/engine/src/cmd/edit.rs
index 5aa3bb6e7f..886d40b3a5 100644
--- a/crates/engine/src/cmd/edit.rs
+++ b/crates/engine/src/cmd/edit.rs
@@ -23,11 +23,11 @@ pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("edit.checkpoint", "Checkpoint", checkpoint).icon("checkpoint")
.noundo()
.doc_only()
- .params("→ {checkpoint: id}: remember the design, active sketch and undo history (restore with edit.restore_checkpoint)"),
+ .params("→ {checkpoint: id}: remember the design, active sketch and undo history (restore with edit.restore_checkpoint; the last 16 are kept, the oldest dropped first)"),
CommandSpec::new("edit.restore_checkpoint", "Restore Checkpoint", restore_checkpoint).icon("restore")
.noundo()
.doc_only()
- .params("checkpoint: id; forget?: bool (true = drop it without going back). Goes back to it, undo history included"),
+ .params("checkpoint: id; forget?: bool (true = drop it without going back). Goes back to it, undo history included. Restoring or forgetting uses it and every later checkpoint up: take a new one to go back again"),
CommandSpec::new("timeline.compute_all", "Compute All", compute_all).at("SOLID", "MODIFY").icon("compute").noundo(),
CommandSpec::new("timeline.play", "Play History", crate::checked!("timeline.play", play))
.at("INSPECT", "HISTORY")
diff --git a/crates/engine/src/cmd/joints.rs b/crates/engine/src/cmd/joints.rs
index 11568023ee..c738472745 100644
--- a/crates/engine/src/cmd/joints.rs
+++ b/crates/engine/src/cmd/joints.rs
@@ -30,7 +30,8 @@ pub static COMMANDS: &[CommandSpec] = &[
"type: rigid|revolute|slider|cylindrical|pin_slot|planar|ball, or a relation: parallel|perpendicular|angle|point_on_plane|point_on_line|line_on_plane \
(ties only some directions or points, made where the parts are; several between two parts add up); a, b: joint origins ({occurrence, face|circle|edge|point: [x,y,z] in world, or face|circle: \"<face name>\"; z? for a point, end?, x? as joint.origin} | origin name); \
values?: [angles in deg or expressions, distances]; limits?: [[min, max] | null…]; flip?: bool (default false: the origins are mated, \
- b's z against a's as two faces meet; true: b's z along a's, so two origins given at one point with the same z stay as they are); \
+ b's z against a's as two faces meet; true: b's z along a's, so two origins given at one point with the same z and x stay as they are; \
+ a point origin without x takes its x from z, so give x on both, or use joint.as_built, to keep a turned part where it is); \
offset?: mm or an expression; angle?: deg or an expression (an angle relation's tilt from mated; for other joints the default \
is none, or a half turn where that turns b less, so faces that already meet stay as they are); name?; quiet?: bool (leave \
out dof and fixed). An expression (text) is \
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 64ef16a918..47d76e0573 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -1486,8 +1486,13 @@ impl Session {
/// Go back to checkpoint `id` as if nothing since had happened (the undo history too). It
/// and later checkpoints are used up.
pub fn restore_checkpoint(&mut self, id: u64) -> Result<()> {
- let i = self.checkpoints.iter().position(|c| c.id == id).ok_or_else(|| EngineError::Other(format!("no checkpoint {id}")))?;
- let Some(c) = self.checkpoints.drain(i..).next() else { return Err(EngineError::Other(format!("no checkpoint {id}"))) };
+ let missing = || {
+ EngineError::Other(format!(
+ "no checkpoint {id} (used up by restoring or forgetting it or an earlier one, or dropped: only the last {MAX_CHECKPOINTS} are kept)"
+ ))
+ };
+ let i = self.checkpoints.iter().position(|c| c.id == id).ok_or_else(missing)?;
+ let Some(c) = self.checkpoints.drain(i..).next() else { return Err(missing()) };
let before = Snapshot {
label: String::new(),
doc: self.doc.clone(),
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index a3c374c8cd..ab64553fb6 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -1930,6 +1930,24 @@ fn checkpoint_restores_with_a_full_undo_history() {
assert!(s.execute("edit.restore_checkpoint", &json!({"checkpoint": id})).is_err());
}
+/// Regression (#9746): a checkpoint restored already, or one of more than the 16 kept, was
+/// refused with only "no checkpoint N", so a script that restores twice could not tell why.
+#[test]
+fn a_used_up_or_dropped_checkpoint_says_why() {
+ let mut s = Session::default();
+ let id = run(&mut s, "edit.checkpoint", json!({}))["checkpoint"].as_u64().unwrap();
+ run(&mut s, "edit.restore_checkpoint", json!({"checkpoint": id}));
+ let used = s.execute("edit.restore_checkpoint", &json!({"checkpoint": id})).unwrap_err().to_string();
+ assert!(used.contains("used up") && used.contains("16"), "{used}");
+ let first = run(&mut s, "edit.checkpoint", json!({}))["checkpoint"].as_u64().unwrap();
+ for _ in 0..MAX_CHECKPOINTS {
+ run(&mut s, "edit.checkpoint", json!({}));
+ }
+ let dropped = s.execute("edit.restore_checkpoint", &json!({"checkpoint": first})).unwrap_err().to_string();
+ assert!(dropped.contains("16"), "{dropped}");
+ run(&mut s, "edit.restore_checkpoint", json!({"checkpoint": first + 1}));
+}
+
/// Regression (#3242): `file.new` replaced the session and its checkpoints with it, so a
/// batch that failed after `file.new` could not go back to the design it began in.
#[test]
diff --git a/docs/book/src/guide/assemblies.md b/docs/book/src/guide/assemblies.md
index 04027a98eb..52cf578626 100644
--- a/docs/book/src/guide/assemblies.md
+++ b/docs/book/src/guide/assemblies.md
@@ -259,7 +259,9 @@ it where it is), and it moves.
`joint.drive` answers the joint's values as `joint.list` gives them, in degrees and millimetres
with their units and limits, and `moved` says whether any part moved. A joint's origins are mated
by default: B's z axis is turned against A's, as two faces meet. `flip: true` lines them up
-instead, so two origins given at one point with the same z stay as they are. Without an
+instead, so two origins given at one point with the same z and x stay as they are. A point origin
+without `x` takes its x from z alone, so a part turned about z turns back when it is joined: give
+`x` on both origins, or use `joint.as_built`, to keep it where it is. Without an
`angle`, a new joint (other than a relation, which starts where its parts are) takes no turn or a half turn about its axis, whichever turns B less: two
faces that already meet, a plate under a panel, stay as they are instead of B spinning about
their shared normal. For scripts that drive many steps, `quiet: true` leaves the per-part
diff --git a/skills/solidcraft-editing/SKILL.md b/skills/solidcraft-editing/SKILL.md
index 8cd40f9cbd..590a32bf82 100644
--- a/skills/solidcraft-editing/SKILL.md
+++ b/skills/solidcraft-editing/SKILL.md
@@ -34,7 +34,7 @@ Inspect one feature of each kind, not every copy.
3. `timeline.roll_to {}` to return to the end.
Everything after the insert recomputes, and a feature that worked can now fail. Seen: a corner fillet after an inserted chamfer.
-- **Risky or multi-step edits:** take `edit.checkpoint` in its own call first. `edit.restore_checkpoint {checkpoint}` goes back exactly. A `batch` rolls itself back; separate `execute` calls do not.
+- **Risky or multi-step edits:** take `edit.checkpoint` in its own call first. `edit.restore_checkpoint {checkpoint}` goes back exactly. Restoring uses the checkpoint up (and any later ones): take a new one to go back again. Only the last 16 are kept. A `batch` rolls itself back; separate `execute` calls do not.
- **Deleting:** `timeline.dependents {feature}` first. It lists what is deleted with it and what would fail.
- **Ambiguous wording:** "2 mm higher" on a value written as `wall + 6` can be relative (`wall + 8`) or absolute.
- Keep the design's intent, which is the relative reading.
@@ -45,7 +45,7 @@ Inspect one feature of each kind, not every copy.
1. **Predict, then measure once.** Send the independent changes in one batch, predict the total volume change, then run `measure` once.
- A move does not change the volume. To confirm a moved sketch, read its points' world coordinates with `sketch.inspect`. You can also predict the COM shift, `Δcom = V_moved · Δz / V_body`, but only when nothing else in that batch changes the volume.
- If it matches to about 0.01%, you are done.
- - If not, restore the checkpoint, then apply the changes one at a time, measuring after each.
+ - If not, restore the checkpoint, take a new one, then apply the changes one at a time, measuring after each.
- A cut or chamfer that leaves the volume unchanged has missed.
2. **Timeline health:** run `inspect_design {"measure":false,"sketches":false}`. Every `error` and `warning` must be null. If something broke, restore or `undo` before you try anything else.
3. **Interior features:** take one top-view screenshot, `{"source":"model","view":"top","width":480,"height":320}`. When the server is bridged, `view` also turns the user's camera. The iso view hides standoffs behind the walls.
diff --git a/skills/solidcraft-mechanisms/SKILL.md b/skills/solidcraft-mechanisms/SKILL.md
index 53b7e3894c..35a806445d 100644
--- a/skills/solidcraft-mechanisms/SKILL.md
+++ b/skills/solidcraft-mechanisms/SKILL.md
@@ -14,7 +14,7 @@ Written against SolidCraft `main` after 0.11.1, which counts the degrees of free
1. In SolidCraft's own chat or any MCP client, call `skill_reference {"skill":"solidcraft-mechanisms"}`. Elsewhere, read `reference.md`.
2. **Open:** if the design is not open yet, run `open {path}`. When the server is bridged to the app and the current design is `dirty`, ask before opening anything.
3. **Map it:** run `inspect_design {"measure":false,"sketches":false}`, then `execute joint.list`. `joint.list` shows `fixed` (the grounded occurrences, always with the root, 0), `dof` per occurrence, `conflicts`, the joints, links and named origins, at about 0.5 KB per joint. `execute motion.list` lists the motion studies.
-4. **Existing design:** take `edit.checkpoint` in its own call before you move bodies into components. `edit.restore_checkpoint {checkpoint}` goes back exactly.
+4. **Existing design:** take `edit.checkpoint` in its own call before you move bodies into components. `edit.restore_checkpoint {checkpoint}` goes back exactly, once: restoring uses the checkpoint up, so take a new one to go back again.
5. **Write the plan:**
- the components, and which one is grounded
- each joint: type, the two occurrences, its world point and axis, limits