✨ add pointer events and interactive hover to Clay render pipeline

Clay's pointer hit-testing is now wired through render() via RenderOptions,
returning pointerenter/pointerleave/pointerclick events by diffing
Clay_GetPointerOverIds() across frames. The demo keyboard shows hover
highlights on keys, semantic element IDs, and configurable event log filters.

Author: cowboyd

demo/keyboard.ts

@@ -265,13 +265,16 @@ export interface ResizeEvent {
   height: number;
 }
 
+import type { PointerEvent } from "./term.ts";
+
 export type InputEvent =
   | KeyEvent
   | MouseDownEvent
   | MouseUpEvent
   | MouseMoveEvent
   | WheelEvent
-  | ResizeEvent;
+  | ResizeEvent
+  | PointerEvent;
 
 /**
  * Result of a single scan() call.

input.ts

@@ -557,6 +557,22 @@ char *output(struct Clayterm *ct) { return ct->out.data; }
 
 int length(struct Clayterm *ct) { return ct->out.length; }
 
+int pointer_over_count(void) {
+  return Clay_GetPointerOverIds().length;
+}
+
+int pointer_over_id_string_length(int index) {
+  Clay_ElementIdArray ids = Clay_GetPointerOverIds();
+  if (index >= ids.length) return 0;
+  return ids.internalArray[index].stringId.length;
+}
+
+int pointer_over_id_string_ptr(int index) {
+  Clay_ElementIdArray ids = Clay_GetPointerOverIds();
+  if (index >= ids.length) return 0;
+  return (int)ids.internalArray[index].stringId.chars;
+}
+
 void measure(int ret, int txt) {
   /* Read Clay_StringSlice from txt address.
    * Clay_StringSlice layout: { int32_t length, const char *chars, ... }

src/clayterm.c

@@ -17,4 +17,8 @@ char *output(struct Clayterm *ct);
 int length(struct Clayterm *ct);
 void measure(int ret, int txt);
 
+int pointer_over_count(void);
+int pointer_over_id_string_length(int index);
+int pointer_over_id_string_ptr(int index);
+
 #endif

src/clayterm.h

@@ -5,6 +5,8 @@ export interface Native {
   reduce(ct: number, buf: number, len: number): void;
   output(ct: number): number;
   length(ct: number): number;
+  setPointer(x: number, y: number, down: boolean): void;
+  getPointerOverIds(): string[];
 }
 
 import { compiled } from "./wasm.ts";
@@ -45,6 +47,10 @@ export async function createTermNative(w: number, h: number): Promise<Native> {
     reduce(ct: number, buf: number, len: number): void;
     output(ct: number): number;
     length(ct: number): number;
+    Clay_SetPointerState(vec: number, down: number): void;
+    pointer_over_count(): number;
+    pointer_over_id_string_length(index: number): number;
+    pointer_over_id_string_ptr(index: number): number;
   };
 
   let heap = ct.__heap_base.value as number;
@@ -68,5 +74,23 @@ export async function createTermNative(w: number, h: number): Promise<Native> {
     reduce: ct.reduce,
     output: ct.output,
     length: ct.length,
+    setPointer(x: number, y: number, down: boolean) {
+      let view = new DataView(memory.buffer);
+      view.setFloat32(opsBuf, x, true);
+      view.setFloat32(opsBuf + 4, y, true);
+      ct.Clay_SetPointerState(opsBuf, down ? 1 : 0);
+    },
+    getPointerOverIds(): string[] {
+      let decoder = new TextDecoder();
+      let count = ct.pointer_over_count();
+      let ids: string[] = [];
+      for (let i = 0; i < count; i++) {
+        let len = ct.pointer_over_id_string_length(i);
+        if (len === 0) continue;
+        let ptr = ct.pointer_over_id_string_ptr(i);
+        ids.push(decoder.decode(new Uint8Array(memory.buffer, ptr, len)));
+      }
+      return ids;
+    },
   };
 }

term-native.ts

@@ -6,27 +6,89 @@ export interface TermOptions {
   width: number;
 }
 
+export interface RenderOptions {
+  pointer?: {
+    x: number;
+    y: number;
+    down: boolean;
+  };
+}
+
+export type PointerEvent =
+  | { type: "pointerenter"; id: string }
+  | { type: "pointerleave"; id: string }
+  | { type: "pointerclick"; id: string };
+
+export interface RenderResult {
+  output: Uint8Array;
+  events: PointerEvent[];
+}
+
 export interface Term {
-  render(ops: Op[]): Uint8Array;
+  render(ops: Op[], options?: RenderOptions): RenderResult;
 }
 
 export async function createTerm(options: TermOptions): Promise<Term> {
   let { width, height } = options;
-  let { memory, statePtr, opsBuf, reduce, output, length } =
-    await createTermNative(
-      width,
-      height,
-    );
+  let native = await createTermNative(width, height);
+  let { memory, statePtr, opsBuf } = native;
+
+  let prev = new Set<string>();
+  let pressed = new Set<string>();
+  let wasDown = false;
 
   return {
-    render(ops: Op[]): Uint8Array {
+    render(ops: Op[], options?: RenderOptions): RenderResult {
       let len = pack(ops, memory.buffer, opsBuf, memory.buffer.byteLength);
-      reduce(statePtr, opsBuf, len);
-      return new Uint8Array(
+      native.reduce(statePtr, opsBuf, len);
+
+      if (options?.pointer) {
+        let { x, y, down } = options.pointer;
+        native.setPointer(x, y, down);
+      }
+
+      let output = new Uint8Array(
         memory.buffer,
-        output(statePtr),
-        length(statePtr),
+        native.output(statePtr),
+        native.length(statePtr),
       );
+
+      let current = new Set(
+        options?.pointer ? native.getPointerOverIds() : [],
+      );
+      let down = options?.pointer?.down ?? false;
+      let events: PointerEvent[] = [];
+
+      for (let id of current) {
+        if (!prev.has(id)) {
+          events.push({ type: "pointerenter", id });
+        }
+      }
+
+      for (let id of prev) {
+        if (!current.has(id)) {
+          events.push({ type: "pointerleave", id });
+        }
+      }
+
+      if (wasDown && !down) {
+        for (let id of pressed) {
+          if (current.has(id)) {
+            events.push({ type: "pointerclick", id });
+          }
+        }
+      }
+
+      if (down && !wasDown) {
+        pressed = new Set(current);
+      } else if (!down) {
+        pressed.clear();
+      }
+
+      prev = current;
+      wasDown = down;
+
+      return { output, events };
     },
   };
 }

term.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it } from "./suite.ts";
+import { createTerm, type Term } from "../term.ts";
+import { close, fixed, grow, open, text } from "../ops.ts";
+
+function box(id: string, width: number, height: number) {
+  return open(id, {
+    layout: { width: fixed(width), height: fixed(height) },
+  });
+}
+
+// ┌─root (40x10, ltr)──────────────────┐
+// │┌─left (20x10)─┐┌─right (20x10)──┐│
+// ││L              ││R               ││
+// ││               ││                ││
+// ││               ││                ││
+// ││               ││                ││
+// ││               ││                ││
+// ││               ││                ││
+// ││               ││                ││
+// │└───────────────┘└────────────────┘│
+// └───────────────────────────────────┘
+function layout() {
+  return [
+    open("root", {
+      layout: { width: grow(), height: grow(), direction: "ltr" },
+    }),
+    box("left", 20, 10),
+    text("L"),
+    close(),
+    box("right", 20, 10),
+    text("R"),
+    close(),
+    close(),
+  ];
+}
+
+describe("pointer events", () => {
+  let term: Term;
+
+  beforeEach(async () => {
+    term = await createTerm({ width: 40, height: 10 });
+  });
+
+  it("returns no events when pointer is not provided", () => {
+    let result = term.render(layout());
+    expect(result.events).toEqual([]);
+  });
+
+  it("returns no events when pointer is outside all elements", () => {
+    let result = term.render(layout(), {
+      pointer: { x: 100, y: 100, down: false },
+    });
+    expect(result.events).toEqual([]);
+  });
+
+  it("fires pointerenter when pointer moves over an element", () => {
+    let result = term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let enters = result.events.filter((e) => e.type === "pointerenter");
+    expect(enters.some((e) => e.id === "left")).toBe(true);
+  });
+
+  it("does not fire pointerenter again on subsequent frames", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let result = term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let enters = result.events.filter((e) => e.type === "pointerenter");
+    expect(enters.some((e) => e.id === "left")).toBe(false);
+  });
+
+  it("fires pointerleave when pointer moves off an element", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let result = term.render(layout(), {
+      pointer: { x: 25, y: 5, down: false },
+    });
+    let leaves = result.events.filter((e) => e.type === "pointerleave");
+    expect(leaves.some((e) => e.id === "left")).toBe(true);
+  });
+
+  it("fires pointerenter and pointerleave when moving between elements", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let result = term.render(layout(), {
+      pointer: { x: 25, y: 5, down: false },
+    });
+    expect(result.events).toContainEqual({ type: "pointerleave", id: "left" });
+    expect(result.events).toContainEqual({ type: "pointerenter", id: "right" });
+  });
+
+  it("fires pointerclick on press then release over same element", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: true },
+    });
+    let result = term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    expect(result.events).toContainEqual({ type: "pointerclick", id: "left" });
+  });
+
+  it("does not fire pointerclick if released over a different element", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: true },
+    });
+    let result = term.render(layout(), {
+      pointer: { x: 25, y: 5, down: false },
+    });
+    let clicks = result.events.filter((e) => e.type === "pointerclick");
+    expect(clicks.some((e) => e.id === "left")).toBe(false);
+    expect(clicks.some((e) => e.id === "right")).toBe(false);
+  });
+
+  it("fires pointerleave for all hovered elements when pointer is removed", () => {
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let result = term.render(layout());
+    let leaves = result.events.filter((e) => e.type === "pointerleave");
+    expect(leaves.some((e) => e.id === "left")).toBe(true);
+  });
+
+  it("does not fire pointerleave on parent when moving to child", () => {
+    // pointer starts on root but outside both children (if layout allows),
+    // or we just verify that moving within a parent's bounds doesn't leave it
+    term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    // move to a different spot still inside "root" and "left"
+    let result = term.render(layout(), {
+      pointer: { x: 10, y: 5, down: false },
+    });
+    let leaves = result.events.filter((e) => e.type === "pointerleave");
+    expect(leaves.some((e) => e.id === "root")).toBe(false);
+    expect(leaves.some((e) => e.id === "left")).toBe(false);
+  });
+
+  it("includes parent element in enter/leave events", () => {
+    let result = term.render(layout(), {
+      pointer: { x: 5, y: 5, down: false },
+    });
+    let enters = result.events.filter((e) => e.type === "pointerenter");
+    expect(enters.some((e) => e.id === "root")).toBe(true);
+    expect(enters.some((e) => e.id === "left")).toBe(true);
+  });
+});

test/pointer.test.ts

@@ -20,7 +20,7 @@ describe("term", () => {
         }),
         text("Hello, World!"),
         close(),
-      ])),
+      ]).output),
       40,
       10,
     );
@@ -36,7 +36,7 @@ describe("term", () => {
       }),
       text("hi"),
       close(),
-    ]));
+    ]).output);
 
     // the SGR active when "h" is emitted should include the
     // parent's red background (48;2;255;0;0), not terminal default
@@ -65,7 +65,7 @@ describe("term", () => {
         }),
         text("padded"),
         close(),
-      ])),
+      ]).output),
       40,
       10,
     );

test/term.test.ts

@@ -1,7 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import type { Op } from "./ops.ts";
-import type { Term } from "./term.ts";
+import type { RenderOptions, RenderResult, Term } from "./term.ts";
 
 /* ── Range helpers (match bit-packing in pack()) ──────────────────── */
 
@@ -135,9 +135,9 @@ export function assert(ops: unknown): asserts ops is Op[] {
 
 export function validated(term: Term): Term {
   return {
-    render(ops: Op[]): Uint8Array {
+    render(ops: Op[], options?: RenderOptions): RenderResult {
       assert(ops);
-      return term.render(ops);
+      return term.render(ops, options);
     },
   };
 }