Document snapshot pointer lifetimes and make getters NULL-safe

The snapshot getters crashed on a NULL snapshot, unlike the rest of the
API. They now return NULL, an empty span, 0, or write nothing, as the
terminal functions do. term_snapshot_cluster writes nothing when cps is
NULL or cap is 0.

Document that the view and its palette keep their address for the life
of the snapshot, and that a row pointer lasts only until the next update
or free, since an update can realloc the cell array.

Rename the term_input.h include guard to TERM_INPUT_H to match the file.

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

2 files changed, 14 insertions, 6 deletions

diff --git a/include/term/term.h b/include/term/term.h
index dc41114..d413db5 100644
--- a/include/term/term.h
+++ b/include/term/term.h
@@ -408,11 +408,16 @@ struct term_view {
     const uint32_t *palette;    /* TERM_PALETTE_SIZE ARGB entries */
 };
 
+/* The view of s, NULL for a NULL s. The view and view->palette keep their
+ * address until term_snapshot_free(); their contents change on each update. */
 TERM_API const struct term_view *term_snapshot_view(const struct term_snapshot *s);
-/* The cells of viewport row y: view->size.x entries. */
+/* The cells of viewport row y: view->size.x entries. NULL when y is outside
+ * the viewport or s is NULL. An update can move the cells, so the pointer is
+ * valid only until the next term_snapshot_update() or term_snapshot_free() of s. */
 TERM_API const struct term_cell *term_snapshot_row(const struct term_snapshot *s, int y);
 /* An identity for the content of row y. Two rows with the same key hold the
- * same cells, also when the content moved to another row. */
+ * same cells, also when the content moved to another row. 0 when y is outside
+ * the viewport or s is NULL. */
 TERM_API uint64_t term_snapshot_row_key(const struct term_snapshot *s, int y);
 
 /* Number of rows in history above the screen. 0 if alternate screen or no history. */
@@ -423,10 +428,13 @@ TERM_API int term_history_rows(const struct term *t);
  * an empty string; NULL means allocation failed or t is NULL. Release the
  * result with term_text_free(). */
 TERM_API char *term_history_text(struct term *t, int max_rows);
+/* The selected columns of viewport row y, end exclusive. An empty span when y
+ * is outside the viewport or s is NULL. */
 TERM_API struct term_span term_snapshot_row_selection(const struct term_snapshot *s, int y);
 
 /* The code points of a cluster cell. Returns the number of code points and
- * writes at most cap of them. */
+ * writes at most cap of them. Writes nothing when cps is NULL or cap is 0.
+ * Returns 0 when s is NULL. */
 TERM_API int term_snapshot_cluster(const struct term_snapshot *s, uint32_t text, uint32_t *cps, int cap);
 
 /* The ARGB value of a color in a view. */
diff --git a/include/term/term_input.h b/include/term/term_input.h
index c317bea..19d9355 100644
--- a/include/term/term_input.h
+++ b/include/term/term_input.h
@@ -1,5 +1,5 @@
-#ifndef TERM_INPUT_TYPES_H
-#define TERM_INPUT_TYPES_H
+#ifndef TERM_INPUT_H
+#define TERM_INPUT_H
 
 #include <stdbool.h>
 #include <stddef.h>
@@ -199,4 +199,4 @@ struct term_input_result {
 }
 #endif
 
-#endif /* TERM_INPUT_TYPES_H */
+#endif /* TERM_INPUT_H */