📝 add scroll specification and implementation

Introduces specs/scroll-spec.md (v0.2) defining clip configuration
with per-axis numeric offsets and wheel delta reporting via RenderInfo.
Clip API changes from { horizontal, vertical } to { x?, y? } with
numeric offsets. Adds RenderOptions.event for input event integration
and deprecates the manual pointer option. Includes scroll demo with
~10k lines of lorem markdown.

Author: cowboyd

AGENTS.md

@@ -14,6 +14,16 @@
 - The workflow is: propose the spec change, wait for approval, then implement.
   Do not combine spec changes with implementation in a single step.
 
+- During implementation, the spec is the sole authority. Do not add APIs,
+  exports, parameters, or architectural elements that are not described in the
+  spec — even if an implementation plan or subagent recommends them. If the spec
+  is insufficient, update the spec first.
+
+- If an implementation requires changing any API boundary — public TS exports,
+  WASM exports, function signatures, the command protocol, or any interface that
+  crosses a module boundary — stop and consult the user before proceeding. Do
+  not rationalize changes as "internal." If it has a signature, it's an API.
+
 - The renderer and input parser are specified separately (`renderer-spec.md` and
   `input-spec.md`). They are architecturally independent. Do not introduce
   dependencies between them.
@@ -26,6 +36,10 @@
 Do not include any agent marketing material (e.g. "Generated with...",
 "Co-Authored-By: \<agent>") in commits, pull requests, issues, or comments.
 
+Before every commit, run `deno fmt` and `deno lint` and fix any issues. For C
+files, also run `clang-format -i src/*.c src/*.h`. Do not commit unformatted
+code.
+
 ## Rendering invariants
 
 - The renderer MUST NOT perform IO. It produces bytes; the caller writes them.

demo/lorem.ts

@@ -0,0 +1,238 @@
+import { each, ensure, main, until } from "effection";
+import {
+  close,
+  createTerm,
+  fixed,
+  grow,
+  type InputEvent,
+  type Op,
+  open,
+  rgba,
+  text,
+} from "../mod.ts";
+import {
+  alternateBuffer,
+  cursor,
+  mouseTracking,
+  settings,
+} from "../settings.ts";
+import { useInput } from "./use-input.ts";
+import { useStdin } from "./use-stdin.ts";
+import content from "./lorem.ts";
+
+let FG = rgba(204, 204, 204);
+let DIM = rgba(100, 100, 110);
+let GUTTER_FG = rgba(100, 120, 160);
+let STATUS_BG = rgba(30, 30, 40);
+let STATUS_FG = rgba(180, 180, 190);
+let THUMB = rgba(120, 120, 140);
+let TRACK = rgba(40, 40, 50);
+
+let lines = content.split("\n");
+
+function gutter(lineNum: number, width: number): string {
+  let num = String(lineNum);
+  let pad = width - 2 - num.length;
+  return " ".repeat(Math.max(0, pad)) + num + " \u2502";
+}
+
+function gutterWidth(): number {
+  let digits = Math.max(1, Math.floor(Math.log10(lines.length)) + 1);
+  return Math.max(4, digits + 2);
+}
+
+function thumbGeometry(
+  scrollY: number,
+  totalLines: number,
+  viewportHeight: number,
+): { pos: number; size: number } {
+  let size = totalLines > viewportHeight
+    ? Math.max(1, Math.round(viewportHeight * viewportHeight / totalLines))
+    : viewportHeight;
+  let maxScroll = Math.max(totalLines - viewportHeight, 1);
+  let pos = Math.round((scrollY / maxScroll) * (viewportHeight - size));
+  return { pos, size };
+}
+
+function build(
+  scrollY: number,
+  rows: number,
+): Op[] {
+  let ops: Op[] = [];
+  let gw = gutterWidth();
+  let viewHeight = rows - 1;
+  let { pos, size } = thumbGeometry(scrollY, lines.length, viewHeight);
+
+  ops.push(open("root", {
+    layout: { width: grow(), height: grow(), direction: "ttb" },
+  }));
+
+  for (let row = 0; row < viewHeight; row++) {
+    let lineIdx = scrollY + row;
+    let hasLine = lineIdx < lines.length;
+    let lineNum = hasLine ? lineIdx + 1 : 0;
+    let lineText = hasLine ? lines[lineIdx] : "";
+
+    let inThumb = row >= pos && row < pos + size;
+    let scrollChar = inThumb ? "\u2588" : "\u2502";
+    let scrollColor = inThumb ? THUMB : TRACK;
+
+    ops.push(
+      open(`r${row}`, {
+        layout: { direction: "ltr", height: fixed(1), width: grow() },
+      }),
+      open("", { layout: { width: fixed(gw), height: fixed(1) } }),
+      text(hasLine ? gutter(lineNum, gw) : " ".repeat(gw - 1) + "\u2502", {
+        color: hasLine ? GUTTER_FG : DIM,
+      }),
+      close(),
+      open("", { layout: { width: grow(), height: fixed(1) } }),
+      text(lineText || " ", { color: hasLine ? FG : DIM }),
+      close(),
+      open("", { layout: { width: fixed(1), height: fixed(1) } }),
+      text(scrollChar, { color: scrollColor }),
+      close(),
+      close(),
+    );
+  }
+
+  let status = ` ${
+    scrollY + 1
+  }/${lines.length}  n/p:line  j/k:scroll  g/G:top/bottom  q:quit`;
+  ops.push(
+    open("status", {
+      layout: {
+        width: grow(),
+        height: fixed(1),
+        direction: "ltr",
+        padding: { left: 1 },
+      },
+      bg: STATUS_BG,
+    }),
+    text(status, { color: STATUS_FG }),
+    close(),
+  );
+
+  ops.push(close());
+  return ops;
+}
+
+function clamp(v: number, min: number, max: number): number {
+  if (v < min) {
+    return min;
+  } else {
+    return v > max ? max : v;
+  }
+}
+
+await main(function* () {
+  let { columns, rows } = Deno.stdout.isTerminal()
+    ? Deno.consoleSize()
+    : { columns: 80, rows: 24 };
+
+  Deno.stdin.setRaw(true);
+
+  let stdin = yield* useStdin();
+  let input = useInput(stdin);
+
+  let term = yield* until(createTerm({ width: columns, height: rows }));
+
+  let tty = settings(alternateBuffer(), cursor(false), mouseTracking());
+  Deno.stdout.writeSync(tty.apply);
+
+  yield* ensure(() => {
+    Deno.stdout.writeSync(tty.revert);
+  });
+
+  let scrollY = 0;
+  let viewHeight = rows - 1;
+  let maxScroll = Math.max(lines.length - viewHeight, 0);
+  let drag = { active: false, offset: 0 };
+
+  Deno.stdout.writeSync(term.render(build(scrollY, rows)).output);
+
+  for (let event of yield* each(input)) {
+    if (event.type === "keydown" && event.ctrl && event.key === "c") break;
+    if (event.type === "keydown" && event.key === "q") break;
+
+    if (event.type === "keydown") {
+      switch (event.code) {
+        case "n":
+        case "j":
+        case "ArrowDown":
+          scrollY = clamp(scrollY + 1, 0, maxScroll);
+          break;
+        case "p":
+        case "k":
+        case "ArrowUp":
+          scrollY = clamp(scrollY - 1, 0, maxScroll);
+          break;
+        case "d":
+        case "PageDown":
+          scrollY = clamp(scrollY + Math.floor(viewHeight / 2), 0, maxScroll);
+          break;
+        case "u":
+        case "PageUp":
+          scrollY = clamp(scrollY - Math.floor(viewHeight / 2), 0, maxScroll);
+          break;
+        case "g":
+        case "Home":
+          scrollY = 0;
+          break;
+        case "End":
+          scrollY = maxScroll;
+          break;
+      }
+      if ((event as InputEvent & { key: string }).key === "G") {
+        scrollY = maxScroll;
+      }
+    }
+
+    if (event.type === "wheel") {
+      let delta = event.direction === "down" ? 3 : -3;
+      scrollY = clamp(scrollY + delta, 0, maxScroll);
+    }
+
+    if (
+      event.type === "mousedown" &&
+      event.button === "left" &&
+      event.x === columns - 1 &&
+      event.y < viewHeight
+    ) {
+      let { pos, size } = thumbGeometry(scrollY, lines.length, viewHeight);
+      if (event.y >= pos && event.y < pos + size) {
+        drag.active = true;
+        drag.offset = event.y - pos;
+      } else {
+        let fraction = event.y / Math.max(viewHeight - 1, 1);
+        scrollY = clamp(Math.round(fraction * maxScroll), 0, maxScroll);
+      }
+    }
+
+    if (event.type === "mousemove" && drag.active) {
+      let { size } = thumbGeometry(scrollY, lines.length, viewHeight);
+      let fraction = (event.y - drag.offset) /
+        Math.max(viewHeight - size, 1);
+      scrollY = clamp(Math.round(fraction * maxScroll), 0, maxScroll);
+    }
+
+    if (event.type === "mouseup") {
+      drag.active = false;
+    }
+
+    if (event.type === "resize") {
+      columns = event.width;
+      rows = event.height;
+      viewHeight = rows - 1;
+      maxScroll = Math.max(lines.length - viewHeight, 0);
+      scrollY = clamp(scrollY, 0, maxScroll);
+      term = yield* until(createTerm({ width: columns, height: rows }));
+    }
+
+    Deno.stdout.writeSync(
+      term.render(build(scrollY, rows)).output,
+    );
+
+    yield* each.next();
+  }
+});

demo/scroll.ts

@@ -7,7 +7,8 @@
     "fmt:check": "deno fmt --check && clang-format --dry-run --Werror src/*.c src/*.h",
     "build:npm": "deno run -A tasks/build-npm.ts",
     "build:jsr": "deno run -A tasks/build-jsr.ts",
-    "demo": "deno run demo/keyboard.ts"
+    "demo": "deno run demo/keyboard.ts",
+    "demo:scroll": "deno run demo/scroll.ts"
   },
   "imports": {
     "@std/testing": "jsr:@std/testing@1",

deno.json

@@ -149,12 +149,18 @@ export function pack(
         }
 
         if (op.clip) {
-          view.setUint32(
-            o,
-            (op.clip.horizontal ? 1 : 0) | ((op.clip.vertical ? 1 : 0) << 8),
-            true,
-          );
+          let xm = op.clip.x !== undefined ? 1 : 0;
+          let ym = op.clip.y !== undefined ? 1 : 0;
+          view.setUint32(o, xm | (ym << 8), true);
           o += 4;
+          if (xm) {
+            view.setFloat32(o, op.clip.x!, true);
+            o += 4;
+          }
+          if (ym) {
+            view.setFloat32(o, op.clip.y!, true);
+            o += 4;
+          }
         }
 
         if (op.floating) {
@@ -260,7 +266,7 @@ export interface OpenElement {
     top?: number;
     bottom?: number;
   };
-  clip?: { horizontal?: boolean; vertical?: boolean };
+  clip?: { x?: number; y?: number };
   floating?: {
     x?: number;
     y?: number;

ops.ts

@@ -135,7 +135,22 @@ has already been extended with fields that are not yet mapped to the TS types).
 
 ---
 
-## 6. Deferred / Future Areas
+## 6. Integration with Rendering
+
+Input events produced by the parser can be passed directly to the renderer via
+`RenderOptions.event`. The renderer extracts pointer state from mouse events and
+scroll deltas from wheel events, removing the need for the caller to manually
+decompose input events into renderer-specific structures.
+
+See the [Scroll Specification](scroll-spec.md), Section 5 for details.
+
+This integration does not create an architectural dependency between the input
+parser and the renderer. The `InputEvent` type is the shared contract; neither
+module imports the other.
+
+---
+
+## 7. Deferred / Future Areas
 
 _These topics are explicitly excluded from this specification. Their omission is
 intentional, not an oversight._
@@ -153,7 +168,7 @@ decision is open.
 
 ---
 
-## Open Decisions
+## 8. Open Decisions
 
 1. **What are the normative Kitty progressive enhancement event types?** The
    C-side struct has been extended. The TypeScript types have not been updated.