🐛 fix(term): resolve caret cell during the render walk

Precompute the caret's byte offset within its text node at OP_TEXT
decode time, then place the caret cell as a side effect of render_text's
existing walk: at the top of each iteration, if the current pointer
matches the target byte offset, record the cell.

Two edge cases fall out of the same mechanism. A slice whose first byte
is already past the target (Clay dropped whitespace at the wrap seam)
snaps the caret to the slice's origin — the start of the next wrapped
line — rather than orphaning it off the end of the previous line. And
the trailing cell of the last walked caret slice is remembered as the
end-of-content fallback for offset == content-length.

Deletes locate_caret, which walked slices with a code-point accumulator
that diverged from the caller's original offset whenever the layout
engine's wrap pass either dropped or retained-off-screen the seam
whitespace.

Adds tests covering both wrap-boundary cases and tightens the
previously-lax "correct wrapped line" assertion to an exact cell.

Author: cowboyd

specs/renderer-spec.md

@@ -354,13 +354,13 @@ offset `N`:
 - If `N > [...content].length` or `N < 0`, behavior is unspecified; callers must
   keep offsets within bounds.
 
-When the layout engine consumes whitespace at a wrap boundary — dropping it
-from the rendered text so that neither wrapped line contains a display cell for
-those code points — the caret has no display position of its own for any offset
-that falls in that dropped run. In that case the caret's cell is the origin of
-the following wrapped line (the display position of the first code point on
-that line). This rule keeps the caret on-screen at the point where subsequent
-input will land, rather than orphaning it past the end of the previous line.
+When the layout engine consumes whitespace at a wrap boundary — dropping it from
+the rendered text so that neither wrapped line contains a display cell for those
+code points — the caret has no display position of its own for any offset that
+falls in that dropped run. In that case the caret's cell is the origin of the
+following wrapped line (the display position of the first code point on that
+line). This rule keeps the caret on-screen at the point where subsequent input
+will land, rather than orphaning it past the end of the previous line.
 
 When `content` is empty, the only in-range offset is `0`. In that case the
 caret's cell is the text element's origin — the cell at which the first code

src/clayterm.c

@@ -85,17 +85,22 @@ struct Clayterm {
   int error_count;
   int animating_count;
   /* Caret state for hardware-cursor management. The renderer records the
-   * first text node carrying a caret declaration per frame, then locates
-   * the corresponding cell after Clay layout. had_caret_last_frame is the
-   * only cross-frame bit retained. */
+   * first text node carrying a caret declaration per frame, precomputes the
+   * caret's byte offset into that node's content, then places the cell as
+   * a side effect of render_text's walk. had_caret_last_frame is the only
+   * cross-frame bit retained. */
   const char
       *caret_text_chars; /* start of caret-bearing text node's bytes, or NULL */
   int caret_text_length; /* byte length of that text node */
-  uint32_t caret_offset; /* code-point offset within that text node */
-  int caret_x, caret_y;  /* resolved cell (column, row), valid only when
-                            caret_text_chars != NULL */
-  int has_caret;         /* 1 when the current frame placed a caret */
-  int had_caret_last_frame; /* 1 when the previous frame placed a caret */
+  uint32_t caret_offset_bytes; /* target byte offset within that text node */
+  int caret_placed;            /* 1 once the render walk has recorded a cell */
+  int caret_tail_valid;        /* 1 when caret_tail_x/y hold a fallback cell */
+  int caret_tail_x,
+      caret_tail_y; /* trailing cell of the most recently walked caret slice */
+  int caret_x,
+      caret_y;   /* resolved cell (column, row); -1 sentinel until placed */
+  int has_caret; /* 1 when the current frame will emit a cursor */
+  int had_caret_last_frame; /* 1 when the previous frame emitted a cursor */
 };
 
 /* Memory layout inside the arena provided by the host:
@@ -324,70 +329,28 @@ static void render_rect(struct Clayterm *ct, int x0, int y0, int x1, int y1,
       setcell(ct, x, y, ' ', ATTR_DEFAULT, bg);
 }
 
-/**
- * Locate the cell where the caret should be rendered given the per-line
- * text commands produced by Clay's wrap pass. Iterates render commands
- * in order, accumulating code points consumed across slices that belong
- * to the caret text node, until the caret's code-point offset is reached.
- */
-static void locate_caret(struct Clayterm *ct, Clay_RenderCommandArray *cmds) {
-  if (ct->caret_text_chars == NULL) {
-    return;
-  }
-  const char *node_start = ct->caret_text_chars;
-  const char *node_end = node_start + ct->caret_text_length;
-  uint32_t target = ct->caret_offset;
-  uint32_t accumulated = 0;
-
-  for (int32_t j = 0; j < cmds->length; j++) {
-    Clay_RenderCommand *cmd = Clay_RenderCommandArray_Get(cmds, j);
-    if (cmd->commandType != CLAY_RENDER_COMMAND_TYPE_TEXT) {
-      continue;
-    }
-    Clay_TextRenderData *t = &cmd->renderData.text;
-    const char *slice = t->stringContents.chars;
-    int slice_len = t->stringContents.length;
-    if (slice < node_start || slice >= node_end) {
-      continue;
-    }
-    /* count code points in this slice */
-    uint32_t slice_cps = 0;
-    int x_cells = 0;
-    const char *p = slice;
-    int rem = slice_len;
-    while (rem > 0) {
-      uint32_t cp;
-      int n = utf8_decode(&cp, p);
-      if (n <= 0) {
-        n = 1;
-        cp = 0xfffd;
-      }
-      if (accumulated + slice_cps == target) {
-        ct->caret_x = (int)cmd->boundingBox.x + x_cells;
-        ct->caret_y = (int)cmd->boundingBox.y;
-        return;
-      }
-      int cw = wcwidth(cp);
-      if (cw < 0) {
-        cw = 1;
-      }
-      x_cells += cw;
-      slice_cps++;
-      p += n;
-      rem -= n;
+/* Return the byte length of the first `cps` code points of `start`,
+ * clamped to at most `max_bytes`. Used at decode time to convert the
+ * caller's code-point caret offset into a stable byte offset. */
+static uint32_t utf8_bytes_for_cps(const char *start, uint32_t cps,
+                                   uint32_t max_bytes) {
+  uint32_t consumed = 0;
+  const char *p = start;
+  int rem = (int)max_bytes;
+  for (uint32_t k = 0; k < cps && rem > 0; k++) {
+    uint32_t cp;
+    int n = utf8_decode(&cp, p);
+    if (n <= 0) {
+      n = 1;
     }
-    if (accumulated + slice_cps == target) {
-      /* caret sits just after this slice's last code point */
-      ct->caret_x = (int)cmd->boundingBox.x + x_cells;
-      ct->caret_y = (int)cmd->boundingBox.y;
-      return;
+    if (n > rem) {
+      n = rem;
     }
-    accumulated += slice_cps;
+    consumed += (uint32_t)n;
+    p += n;
+    rem -= n;
   }
-  /* offset out of range: behavior is unspecified by the spec; leave
-   * caret_x/caret_y at their sentinel -1 values and let the emission
-   * step suppress visibility. */
-  ct->has_caret = 0;
+  return consumed;
 }
 
 static void render_text(struct Clayterm *ct, int x0, int y0,
@@ -401,11 +364,46 @@ static void render_text(struct Clayterm *ct, int x0, int y0,
   uint32_t attrs = ((uint32_t)(uint8_t)t->textColor.a) << 24;
   fg |= attrs;
 
-  const char *p = t->stringContents.chars;
-  int rem = t->stringContents.length;
+  const char *slice = t->stringContents.chars;
+  int slice_len = t->stringContents.length;
+
+  /* Determine whether this slice belongs to the caret's text node and
+   * whether the caret still needs to be placed. If so, resolve the cell
+   * as a side effect of the walk instead of doing a separate pass. */
+  const char *node_start = ct->caret_text_chars;
+  const char *node_end = node_start ? node_start + ct->caret_text_length : NULL;
+  int caret_relevant = (node_start != NULL && !ct->caret_placed &&
+                        slice >= node_start && slice < node_end);
+
+  /* Pre-check: if the slice's first byte is already past the target,
+   * whitespace at the wrap seam was dropped by the layout engine. Snap
+   * the caret to this slice's origin. */
+  if (caret_relevant) {
+    uint32_t slice_start_bytes = (uint32_t)(slice - node_start);
+    if (slice_start_bytes > ct->caret_offset_bytes) {
+      ct->caret_x = x0;
+      ct->caret_y = y0;
+      ct->caret_placed = 1;
+      caret_relevant = 0;
+    }
+  }
+
+  const char *p = slice;
+  int rem = slice_len;
   int x = x0;
 
   while (rem > 0) {
+    /* Check at the top of each iteration: if the pointer we are about to
+     * consume matches the target byte offset, the caret sits at the
+     * current cell — right before this code point. */
+    if (caret_relevant &&
+        (uint32_t)(p - node_start) == ct->caret_offset_bytes) {
+      ct->caret_x = x;
+      ct->caret_y = y0;
+      ct->caret_placed = 1;
+      caret_relevant = 0;
+    }
+
     uint32_t cp;
     int n = utf8_decode(&cp, p);
     if (n <= 0) {
@@ -422,6 +420,16 @@ static void render_text(struct Clayterm *ct, int x0, int y0,
     p += n;
     rem -= n;
   }
+
+  /* Remember the trailing cell of this slice as the end-of-content
+   * fallback. If no later slice claims the target and the caret still
+   * hasn't been placed by the end of the render command loop, this cell
+   * is where a caret at offset == content-length lands. */
+  if (caret_relevant) {
+    ct->caret_tail_x = x;
+    ct->caret_tail_y = y0;
+    ct->caret_tail_valid = 1;
+  }
 }
 
 static void render_border(struct Clayterm *ct, int x0, int y0, int x1, int y1,
@@ -646,7 +654,11 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row,
   ct->animating_count = 0;
   ct->caret_text_chars = NULL;
   ct->caret_text_length = 0;
-  ct->caret_offset = 0;
+  ct->caret_offset_bytes = 0;
+  ct->caret_placed = 0;
+  ct->caret_tail_valid = 0;
+  ct->caret_tail_x = -1;
+  ct->caret_tail_y = -1;
   ct->caret_x = -1;
   ct->caret_y = -1;
   ct->has_caret = 0;
@@ -777,7 +789,7 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row,
       i += str_words;
 
       /* A caret on empty content is a rendering commitment the layout
-       * engine cannot satisfy on its own — zero cells give locate_caret
+       * engine cannot satisfy on its own — zero cells give render_text
        * nothing to attach the cursor to. Substitute a single space so
        * the caret lands at the text element's origin, per the spec's
        * "as if the content were a single space" outcome. */
@@ -788,11 +800,15 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row,
 
       /* Record the FIRST caret declaration per frame for the
        * single-hardware-cursor contract; later declarations are
-       * intentionally ignored (multi-cursor is unspecified). */
+       * intentionally ignored (multi-cursor is unspecified).
+       *
+       * Convert the caller's code-point offset into a byte offset once
+       * here so the render walk can identify the caret cell by simple
+       * pointer arithmetic against the slice's chars pointer. */
       if (caret != 0xFFFFFFFF && ct->caret_text_chars == NULL) {
         ct->caret_text_chars = str_chars;
         ct->caret_text_length = (int)str_len;
-        ct->caret_offset = caret;
+        ct->caret_offset_bytes = utf8_bytes_for_cps(str_chars, caret, str_len);
         ct->has_caret = 1;
       }
 
@@ -822,9 +838,6 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row,
 
   Clay_RenderCommandArray cmds = Clay_EndLayout(deltaTime);
 
-  /* resolve caret cell from this frame's text commands */
-  locate_caret(ct, &cmds);
-
   /* reset output state */
   ct->out.length = 0;
   ct->lastfg = ct->lastbg = 0xffffffff;
@@ -917,6 +930,22 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row,
     }
   }
 
+  /* End-of-content fallback: if a caret was declared and its target byte
+   * offset is one past the last byte of the caret text node, the trailing
+   * cell of the last walked caret slice is where it lands. */
+  if (ct->has_caret && !ct->caret_placed) {
+    if (ct->caret_tail_valid &&
+        ct->caret_offset_bytes == (uint32_t)ct->caret_text_length) {
+      ct->caret_x = ct->caret_tail_x;
+      ct->caret_y = ct->caret_tail_y;
+      ct->caret_placed = 1;
+    } else {
+      /* Offset out of range or otherwise unresolvable. Suppress the
+       * cursor for this frame. */
+      ct->has_caret = 0;
+    }
+  }
+
   if (mode == 1) {
     present_lines(ct);
   } else {

test/term.test.ts

@@ -394,15 +394,45 @@ describe("term", () => {
         close(),
       ]).output,
     );
-    // Caret at code-point 7 of "hello world" → after "hello w" → between
-    // "w" and "o" on the second wrapped line. Exact column depends on Clay's
-    // wrap point: assert row 2 and column at least 2.
-    let cupMatch = ansi.match(/\x1b\[(\d+);(\d+)H\x1b\[\?25h$/);
-    expect(cupMatch).not.toBeNull();
-    let row = parseInt(cupMatch![1], 10);
-    let col = parseInt(cupMatch![2], 10);
-    expect(row).toBe(2);
-    expect(col).toBeGreaterThanOrEqual(2);
+    // "hello world" wraps to "hello" / "world" at width 5. Code-point 7 is
+    // the second 'o' of "world" (h=0,e=1,l=2,l=3,o=4,' '=5,w=6,o=7). The
+    // caret sits before that 'o' on the second wrapped line — row 2, col 2.
+    expect(ansi).toMatch(/\x1b\[2;2H\x1b\[\?25h$/);
+  });
+
+  it("snaps to the next wrapped line for a caret at the wrap seam", async () => {
+    let narrow = await createTerm({ width: 5, height: 4 });
+    let ansi = decode(
+      narrow.render([
+        open("root", {
+          layout: { width: grow(), height: grow(), direction: "ttb" },
+        }),
+        // "hello world" wraps to "hello" / "world" at width 5. The space
+        // between them sits on the wrap seam. Code-point 6 is 'w' at the
+        // start of the second wrapped line; the caret must appear at row 2,
+        // col 1 rather than off-screen past "hello".
+        text("hello world", { caret: 6 }),
+        close(),
+      ]).output,
+    );
+    expect(ansi).toMatch(/\x1b\[2;1H\x1b\[\?25h$/);
+  });
+
+  it("places the caret at the start of a wrapped line when whitespace is consumed", async () => {
+    let term2 = await createTerm({ width: 6, height: 3 });
+    let ansi = decode(
+      term2.render([
+        open("root", {
+          layout: { width: grow(), height: grow(), direction: "ttb" },
+        }),
+        // "abc def" wraps to "abc" / "def" at width 6 — the space between
+        // words is dropped by the wrap pass. Code-point 4 is 'd' at the
+        // start of the second wrapped line; caret lands at row 2, col 1.
+        text("abc def", { caret: 4 }),
+        close(),
+      ]).output,
+    );
+    expect(ansi).toMatch(/\x1b\[2;1H\x1b\[\?25h$/);
   });
 
   it("places the caret one cell past the last character when offset == length", () => {