@effect-tui/core 0.1.0-alpha.1

package/src/render/buffer.ts

@@ -0,0 +1,200 @@
+/* buffer.ts — 2D cell buffer with drawing, clipping, and offsets */
+
+export type Wcwidth = (cp: number) => 0 | 1 | 2
+
+// basic ASCII/Latin fallback; plug a real wcwidth for CJK/emoji later
+export const defaultWcwidth: Wcwidth = (cp) => (cp === 0 ? 0 : cp < 32 ? 0 : cp === 0x7f ? 0 : 1)
+
+type ClipRect = { x: number; y: number; w: number; h: number }
+
+// Represents a single frame of cells (glyph + style + cell width)
+export class CellBuffer {
+  readonly w: number
+  readonly h: number
+
+  // cell data
+  readonly g: Uint32Array // glyph code points
+  readonly s: Uint32Array // style ids
+  readonly cw: Uint8Array // cell width: 0 (continuation), 1, 2
+
+  private wcwidth: Wcwidth
+  private clip: ClipRect
+  private clipStack: ClipRect[] = []
+  private offX = 0
+  private offY = 0
+  private offStack: { x: number; y: number }[] = []
+
+  constructor(width: number, height: number, wcwidth: Wcwidth = defaultWcwidth) {
+    this.w = Math.max(1, width | 0)
+    this.h = Math.max(1, height | 0)
+    const n = this.w * this.h
+    this.g = new Uint32Array(n)
+    this.s = new Uint32Array(n)
+    this.cw = new Uint8Array(n)
+    this.wcwidth = wcwidth
+    this.clip = { x: 0, y: 0, w: this.w, h: this.h }
+    this.clear(0)
+  }
+
+  /** Clear the buffer to spaces in the given style. */
+  clear(styleId = 0): void {
+    this.g.fill(32)
+    this.s.fill(styleId)
+    this.cw.fill(1)
+  }
+
+  /** Draw a single code point at (x,y). If width=2, marks following cell as continuation. */
+  drawCP(x: number, y: number, cp: number, styleId = 0): void {
+    const ax = x + this.offX
+    const ay = y + this.offY
+    if (ax < 0 || ay < 0 || ax >= this.w || ay >= this.h) return
+    if (ax < this.clip.x || ay < this.clip.y || ax >= this.clip.x + this.clip.w || ay >= this.clip.y + this.clip.h)
+      return
+    const idx = ay * this.w + ax
+    const w = this.wcwidth(cp)
+    this.g[idx] = cp
+    this.s[idx] = styleId
+    this.cw[idx] = w === 0 ? 1 : w // treat nonspacing as width 1 here
+
+    if (w === 2) {
+      // mark the continuation cell
+      if (x + 1 < this.w) {
+        const cidx = idx + 1
+        this.g[cidx] = 0 // not printed
+        this.s[cidx] = styleId
+        this.cw[cidx] = 0 // continuation slot
+      }
+    }
+  }
+
+  /** Draw plain text (no wrapping) clipped to width. Uses Intl.Segmenter if available. */
+  drawText(x: number, y: number, text: string, styleId = 0, maxWidth?: number): void {
+    const ax = x + this.offX
+    const ay = y + this.offY
+    if (ay < 0 || ay >= this.h) return
+    // vertical clip
+    if (ay < this.clip.y || ay >= this.clip.y + this.clip.h) return
+    const limit = Math.min(this.w - ax, maxWidth ?? this.w, this.clip.x + this.clip.w - ax)
+    if (limit <= 0) return
+
+    // iterate graphemes (so emoji / ZWJ don’t split). Fallback: naive code points.
+    // Use Intl.Segmenter if available without importing its types to satisfy TS in Node
+    type GraphemeSegmenter = {
+      segment(input: string): Iterable<{ segment: string }>
+    }
+    const SegCtor: { new (...args: any[]): GraphemeSegmenter } | undefined = (globalThis as any).Intl?.Segmenter
+    const seg: GraphemeSegmenter | null =
+      typeof SegCtor === "function"
+        ? (new (SegCtor as new (...args: any[]) => GraphemeSegmenter)(undefined, {
+            granularity: "grapheme",
+          }) as GraphemeSegmenter)
+        : null
+
+    let col = 0
+    if (seg) {
+      for (const { segment } of seg.segment(text)) {
+        const cp = segment.codePointAt(0) ?? 32 // first code point of grapheme
+        const w = this.wcwidth(cp) || 1 // nonspacing combining: treat as 1 (simple path)
+        if (col + w > limit) break
+        this.drawCP(x + col, y, cp, styleId)
+        col += w
+      }
+    } else {
+      for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 32
+        const w = this.wcwidth(cp) || 1
+        if (col + w > limit) break
+        this.drawCP(x + col, y, cp, styleId)
+        col += w
+      }
+    }
+
+    // pad remainder within the visible limit with spaces in the same style (erases leftovers)
+    for (; col < limit; col++) {
+      this.drawCP(x + col, y, 32, styleId)
+    }
+  }
+
+  /** Fill a rectangle with a code point + style. */
+  fillRect(x: number, y: number, w: number, h: number, cp = 32, styleId = 0): void {
+    const ax = x + this.offX
+    const ay = y + this.offY
+    let x0 = Math.max(0, ax | 0),
+      y0 = Math.max(0, ay | 0)
+    let x1 = Math.min(this.w, x0 + Math.max(0, w | 0))
+    let y1 = Math.min(this.h, y0 + Math.max(0, h | 0))
+    // intersect with current clip
+    x0 = Math.max(x0, this.clip.x)
+    y0 = Math.max(y0, this.clip.y)
+    x1 = Math.min(x1, this.clip.x + this.clip.w)
+    y1 = Math.min(y1, this.clip.y + this.clip.h)
+    const width = x1 - x0
+    if (width <= 0 || y1 <= y0) return
+    for (let yy = y0; yy < y1; yy++) {
+      const base = yy * this.w + x0
+      this.g.fill(cp, base, base + width)
+      this.s.fill(styleId, base, base + width)
+      this.cw.fill(1, base, base + width)
+    }
+  }
+
+  // Clipping API
+  pushClip(x: number, y: number, w: number, h: number): void {
+    const nx = Math.max(0, x | 0)
+    const ny = Math.max(0, y | 0)
+    const nw = Math.max(0, w | 0)
+    const nh = Math.max(0, h | 0)
+    const cur = this.clip
+    const ix = Math.max(cur.x, nx)
+    const iy = Math.max(cur.y, ny)
+    const ix2 = Math.min(cur.x + cur.w, nx + nw)
+    const iy2 = Math.min(cur.y + cur.h, ny + nh)
+    this.clipStack.push(cur)
+    this.clip = { x: ix, y: iy, w: Math.max(0, ix2 - ix), h: Math.max(0, iy2 - iy) }
+  }
+
+  popClip(): void {
+    if (this.clipStack.length > 0) {
+      const prev = this.clipStack.pop() as ClipRect
+      this.clip = prev
+    } else {
+      this.clip = { x: 0, y: 0, w: this.w, h: this.h }
+    }
+  }
+
+  withClip(x: number, y: number, w: number, h: number, fn: () => void): void {
+    this.pushClip(x, y, w, h)
+    try {
+      fn()
+    } finally {
+      this.popClip()
+    }
+  }
+
+  // Translation API
+  pushOffset(dx: number, dy: number): void {
+    this.offStack.push({ x: this.offX, y: this.offY })
+    this.offX += dx | 0
+    this.offY += dy | 0
+  }
+
+  popOffset(): void {
+    if (this.offStack.length > 0) {
+      const prev = this.offStack.pop() as { x: number; y: number }
+      this.offX = prev.x
+      this.offY = prev.y
+    } else {
+      this.offX = 0
+      this.offY = 0
+    }
+  }
+
+  withOffset(dx: number, dy: number, fn: () => void): void {
+    this.pushOffset(dx, dy)
+    try {
+      fn()
+    } finally {
+      this.popOffset()
+    }
+  }
+}

package/src/render/color-utils.ts

@@ -0,0 +1,60 @@
+// color-utils.ts - Shared color conversion utilities
+
+/**
+ * Clamp a number to the 0-255 range and convert to integer.
+ */
+export function clamp255(n: number): number {
+	return n < 0 ? 0 : n > 255 ? 255 : n | 0
+}
+
+/**
+ * Convert a 256-color index to RGB values (approximate xterm palette).
+ *
+ * The 256-color palette is divided into:
+ * - 0-15: Standard ANSI colors (system colors)
+ * - 16-231: 6x6x6 RGB cube
+ * - 232-255: Grayscale ramp (24 shades)
+ */
+export function idxToRGB(idx: number): { r: number; g: number; b: number } {
+	if (idx < 0) idx = 0
+	if (idx > 255) idx = 255
+
+	// Standard ANSI colors (0-15)
+	if (idx < 16) {
+		const base: Array<[number, number, number]> = [
+			[0x00, 0x00, 0x00], // 0: black
+			[0x80, 0x00, 0x00], // 1: red
+			[0x00, 0x80, 0x00], // 2: green
+			[0x80, 0x80, 0x00], // 3: yellow
+			[0x00, 0x00, 0x80], // 4: blue
+			[0x80, 0x00, 0x80], // 5: magenta
+			[0x00, 0x80, 0x80], // 6: cyan
+			[0xc0, 0xc0, 0xc0], // 7: white
+			[0x80, 0x80, 0x80], // 8: bright black (gray)
+			[0xff, 0x00, 0x00], // 9: bright red
+			[0x00, 0xff, 0x00], // 10: bright green
+			[0xff, 0xff, 0x00], // 11: bright yellow
+			[0x00, 0x00, 0xff], // 12: bright blue
+			[0xff, 0x00, 0xff], // 13: bright magenta
+			[0x00, 0xff, 0xff], // 14: bright cyan
+			[0xff, 0xff, 0xff], // 15: bright white
+		]
+		const [r, g, b] = base[idx] ?? [0, 0, 0]
+		return { r, g, b }
+	}
+
+	// Grayscale ramp (232-255)
+	if (idx >= 232) {
+		const n = idx - 232 // 0..23
+		const v = 8 + n * 10
+		return { r: v, g: v, b: v }
+	}
+
+	// 6x6x6 RGB cube (16-231)
+	const n = idx - 16 // 0..215
+	const r = Math.floor(n / 36) % 6
+	const g = Math.floor(n / 6) % 6
+	const b = n % 6
+	const steps = [0, 95, 135, 175, 215, 255]
+	return { r: steps[r] ?? 0, g: steps[g] ?? 0, b: steps[b] ?? 0 }
+}

package/src/render/diff.ts

@@ -0,0 +1,95 @@
+import type { Surface } from "./surface.js"
+
+/**
+ * Writer that consumes style runs produced by diffing two frames.
+ * - Coordinates are 0-based: `row` in [0..rows), `col` in [0..cols).
+ * - `begin` is called once with the viewport size, then `run` zero or more times,
+ *   then `end`. Implementations may buffer and expose the result via `flush`.
+ */
+export interface RunWriter {
+  begin(viewport: { cols: number; rows: number }): void
+  run(row: number, col: number, styleId: number, text: string): void
+  end(): void
+  flush(): string
+}
+
+/**
+ * Stream a minimal set of style-runs for changes from prev → next.
+ *
+ * Algorithm (row-wise):
+ * - For each row, compute a tight change window [left, right]. Skip entirely if equal.
+ * - Within the window, emit contiguous runs grouped by style. A new run begins when:
+ *   - A cell changes, and
+ *   - Its style differs from the current run (or the run just started).
+ * - Wide glyph continuation cells (cw=0) are skipped so they are not reprinted.
+ *
+ * Assumes both Surfaces are same size and compares their back buffers (B).
+ */
+export function diffFrames(prev: Surface, next: Surface, w: RunWriter): void {
+  const width = next.w
+  const height = next.h
+  // Access back buffers (like Surface.flush does). B is private on Surface, so use `any`.
+  const gA = (prev as any).B.g as Uint32Array
+  const sA = (prev as any).B.s as Uint32Array
+  const gB = (next as any).B.g as Uint32Array
+  const sB = (next as any).B.s as Uint32Array
+  const cwB = (next as any).B.cw as Uint8Array
+
+  w.begin({ cols: width, rows: height })
+
+  for (let y = 0; y < height; y++) {
+    const row = y * width
+
+    // Fast skip window: [left..right] bounds that changed
+    let left = 0,
+      right = width - 1
+    while (left <= right) {
+      const i = row + left
+      if (gA[i] === gB[i] && sA[i] === sB[i]) left++
+      else break
+    }
+    if (left > right) continue
+
+    while (right >= left) {
+      const i = row + right
+      if (gA[i] === gB[i] && sA[i] === sB[i]) right--
+      else break
+    }
+
+    // Emit contiguous style runs within [left..right]
+    let x = left
+    while (x <= right) {
+      // Skip unchanged within window
+      while (x <= right) {
+        const i = row + x
+        if (gA[i] !== gB[i] || sA[i] !== sB[i]) break
+        x++
+      }
+      if (x > right) break
+
+      const style = sB[row + x]
+      const runX = x
+      let text = ""
+
+      while (x <= right) {
+        const i = row + x
+        if (sB[i] !== style) break
+        const cp = gB[i]
+        const ww = cwB[i]
+        if (ww !== 0) text += cp === 32 ? " " : String.fromCodePoint(cp)
+        x++
+        // skip continuation cells of wide glyphs from the next buffer
+        while (x <= right && cwB[row + x] === 0) x++
+
+        // Stop run if next cell is unchanged; diff window will reposition
+        if (x <= right) {
+          const j = row + x
+          if (gA[j] === gB[j] && sA[j] === sB[j]) break
+        }
+      }
+
+      if (text.length > 0) w.run(y, runX, style, text)
+    }
+  }
+  w.end()
+}

package/src/render/measure.ts

@@ -0,0 +1,74 @@
+/* measure.ts — shared grapheme segmentation and display width helpers
+ *
+ * These helpers intentionally mirror CellBuffer.drawText semantics:
+ * - Prefer Intl.Segmenter('grapheme') when available; otherwise iterate code points.
+ * - Width is derived from wcwidth(first code point) with a minimum of 1.
+ */
+
+import type { Wcwidth } from "./buffer.js"
+import { defaultWcwidth } from "./buffer.js"
+
+type GraphemeSegmenter = {
+  segment(input: string): Iterable<{ segment: string }>
+}
+
+function getGraphemeSegmenter(): GraphemeSegmenter | null {
+  const SegCtor: { new (...args: any[]): GraphemeSegmenter } | undefined = (globalThis as any).Intl?.Segmenter
+  if (typeof SegCtor === "function") {
+    try {
+      return new (SegCtor as new (...args: any[]) => GraphemeSegmenter)(undefined, {
+        granularity: "grapheme",
+      }) as GraphemeSegmenter
+    } catch {
+      // ignore and fall back
+    }
+  }
+  return null
+}
+
+/** Split a string into grapheme clusters (ZWJ sequences kept together when supported). */
+export function graphemes(text: string): string[] {
+  const seg = getGraphemeSegmenter()
+  if (seg) {
+    const out: string[] = []
+    for (const { segment } of seg.segment(text)) out.push(segment)
+    return out
+  }
+  // Fallback: iterate code points (may split ZWJ sequences)
+  return Array.from(text)
+}
+
+/** Compute display width using wcwidth of the first code point of each grapheme. */
+export function displayWidth(text: string, wc: Wcwidth = defaultWcwidth): number {
+  let w = 0
+  const gs = graphemes(text)
+  for (const g of gs) {
+    const cp = g.codePointAt(0) ?? 32
+    const ww = wc(cp) || 1
+    w += ww
+  }
+  return w
+}
+
+/**
+ * Take as many graphemes as fit within maxWidth cells.
+ * Returns the substring, its display width, and whether the whole input fit.
+ */
+export function sliceByWidth(
+  text: string,
+  maxWidth: number,
+  wc: Wcwidth = defaultWcwidth,
+): { text: string; width: number; complete: boolean } {
+  if (maxWidth <= 0) return { text: "", width: 0, complete: text.length === 0 }
+  const gs = graphemes(text)
+  const out: string[] = []
+  let used = 0
+  for (const g of gs) {
+    const cp = g.codePointAt(0) ?? 32
+    const ww = wc(cp) || 1
+    if (used + ww > maxWidth) break
+    out.push(g)
+    used += ww
+  }
+  return { text: out.join(""), width: used, complete: out.length === gs.length }
+}

package/src/render/palette.ts

@@ -0,0 +1,113 @@
+const ESC = "\x1b["
+const CSI = ESC // alias for clarity
+
+// Style palette: intern style specs -> small numeric ids -> prebuilt SGR strings
+// Color can be an xterm-256 index (0..255) or a truecolor triplet.
+export type ColorValue = number | { r: number; g: number; b: number }
+
+// Minimal set of attributes we support. Additional flags can be added as needed.
+export type StyleSpec = {
+  fg?: ColorValue // foreground: 256 index or RGB
+  bg?: ColorValue // background: 256 index or RGB
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  inverse?: boolean
+}
+
+/**
+ * Palette interns "style specs" into small numeric ids and caches their
+ * ANSI SGR escape strings. Id 0 always represents the default terminal style.
+ */
+export class Palette {
+  private nextId = 1 // 0 = default terminal style
+  private idByKey = new Map<string, number>()
+  private sgrById = new Map<number, string>()
+
+  /** Get or create a numeric style id for a given style spec. */
+  id(spec?: StyleSpec): number {
+    if (!spec) return 0
+    const key = JSON.stringify(spec)
+    let id = this.idByKey.get(key)
+    if (id) return id
+    id = this.nextId++
+    this.idByKey.set(key, id)
+    this.sgrById.set(id, this.buildSGR(spec))
+    return id
+  }
+
+  /** Look up the ANSI SGR sequence for a style id. Id 0 resets attributes. */
+  sgr(id: number): string {
+    if (id === 0) return `${ESC}0m`
+    const s = this.sgrById.get(id)
+    return s ?? `${ESC}0m`
+  }
+
+  /**
+   * Build an ANSI SGR sequence for a style spec.
+   * We always begin with reset (0) to avoid style drift across runs,
+   * then add only the requested attributes.
+   */
+  private buildSGR(spec: StyleSpec): string {
+    const parts: string[] = []
+    parts.push("0") // reset, then set exact attrs to avoid drift
+    if (spec.bold) parts.push("1")
+    if (spec.italic) parts.push("3")
+    if (spec.underline) parts.push("4")
+    if (spec.inverse) parts.push("7")
+
+    const colorToCodes = (c: ColorValue | undefined, isBg: boolean): string | undefined => {
+      if (c == null) return undefined
+      if (typeof c === "number") return (isBg ? "48;5;" : "38;5;") + String(c | 0)
+      const clamp = (n: number) => (n < 0 ? 0 : n > 255 ? 255 : n | 0)
+      return `${isBg ? "48;2;" : "38;2;"}${clamp(c.r)};${clamp(c.g)};${clamp(c.b)}`
+    }
+
+    const fgc = colorToCodes(spec.fg, false)
+    const bgc = colorToCodes(spec.bg, true)
+    if (fgc) parts.push(fgc)
+    if (bgc) parts.push(bgc)
+
+    return `${CSI}${parts.join(";")}m`
+  }
+}
+
+/**
+ * ScopedPalette provides style scoping: it merges a base style with any
+ * requested style, while delegating id/sgr generation to a shared Palette.
+ */
+export class ScopedPalette extends Palette {
+  constructor(
+    private readonly base: Palette,
+    private readonly baseStyle?: StyleSpec,
+  ) {
+    super()
+  }
+
+  override id(spec?: StyleSpec): number {
+    return this.base.id(mergeStyle(this.baseStyle, spec))
+  }
+
+  override sgr(id: number): string {
+    return this.base.sgr(id)
+  }
+}
+
+/** Merge two style specs (b overrides a). Returns undefined if nothing to set. */
+export function mergeStyle(a?: StyleSpec, b?: StyleSpec): StyleSpec | undefined {
+  if (!a && !b) return undefined
+  const merged: StyleSpec = {}
+  const fg = b?.fg ?? a?.fg
+  const bg = b?.bg ?? a?.bg
+  const bold = b?.bold ?? a?.bold
+  const italic = b?.italic ?? a?.italic
+  const underline = b?.underline ?? a?.underline
+  const inverse = b?.inverse ?? a?.inverse
+  if (fg !== undefined) merged.fg = fg
+  if (bg !== undefined) merged.bg = bg
+  if (bold !== undefined) merged.bold = bold
+  if (italic !== undefined) merged.italic = italic
+  if (underline !== undefined) merged.underline = underline
+  if (inverse !== undefined) merged.inverse = inverse
+  return Object.keys(merged).length > 0 ? merged : undefined
+}