From 545a5aef663ef551bd8b2b2b794f47d9a74d7586 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Sat, 23 May 2026 15:04:51 -0700
Subject: [PATCH] libghostty: document selection snapshot lifetime

Clarify that GhosttySelection is a snapshot type whose endpoints are
untracked GhosttyGridRef values. The previous documentation described the
range shape but did not repeat the grid reference lifetime caveat, which
made it easy to keep selections across terminal mutations incorrectly.
---
 include/ghostty/vt/selection.h | 45 +++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 6 deletions(-)

diff --git a/include/ghostty/vt/selection.h b/include/ghostty/vt/selection.h
index 9f878fadc..3ba2f00db 100644
--- a/include/ghostty/vt/selection.h
+++ b/include/ghostty/vt/selection.h
@@ -17,14 +17,34 @@ extern "C" {
 
 /** @defgroup selection Selection
  *
- * A selection range defined by two grid references that identifies a
- * contiguous or rectangular region of terminal content.
+ * A snapshot selection range defined by two grid references that identifies
+ * a contiguous or rectangular region of terminal content.
+ *
+ * The start and end values are GhosttyGridRef values. They are therefore
+ * untracked grid references and inherit the same lifetime rules: they are
+ * only safe to use until the next mutating operation on the terminal that
+ * produced them, including freeing the terminal. To keep a selection valid
+ * across terminal mutations, callers must maintain tracked grid references
+ * for the endpoints and reconstruct a GhosttySelection from fresh snapshots
+ * when needed.
  *
  * @{
  */
 
 /**
- * A selection range defined by two grid references.
+ * A snapshot selection range defined by two grid references.
+ *
+ * Both endpoints are inclusive. The endpoints preserve selection direction
+ * and may be reversed; callers must not assume that start is the top-left
+ * endpoint or that end is the bottom-right endpoint.
+ *
+ * When rectangle is false, the endpoints describe a linear selection. When
+ * rectangle is true, the same endpoints are interpreted as opposite corners
+ * of a rectangular/block selection.
+ *
+ * The start and end values are untracked GhosttyGridRef snapshots and are
+ * only valid until the next mutating operation on the terminal that produced
+ * them unless the selection is reconstructed from tracked references.
  *
  * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
  *
@@ -34,13 +54,26 @@ typedef struct {
   /** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */
   size_t size;
 
-  /** Start of the selection range (inclusive). */
+  /**
+   * Start of the selection range (inclusive).
+   *
+   * This may be after end in terminal order. It is an untracked
+   * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
+   */
   GhosttyGridRef start;
 
-  /** End of the selection range (inclusive). */
+  /**
+   * End of the selection range (inclusive).
+   *
+   * This may be before start in terminal order. It is an untracked
+   * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
+   */
   GhosttyGridRef end;
 
-  /** Whether the selection is rectangular (block) rather than linear. */
+  /**
+   * Whether the endpoints are interpreted as a rectangular/block selection
+   * rather than a linear selection.
+   */
   bool rectangle;
 } GhosttySelection;