@effect-tui/core 0.1.0 → 0.1.4

package/src/render/palette.ts

@@ -7,12 +7,32 @@ 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
+	fg?: ColorValue // foreground: 256 index or RGB
+	bg?: ColorValue // background: 256 index or RGB
+	bold?: boolean
+	italic?: boolean
+	underline?: boolean
+	inverse?: boolean
+}
+
+/**
+ * Create a canonical key for a StyleSpec that is order-independent.
+ * This ensures {fg: 1, bg: 2} and {bg: 2, fg: 1} produce the same cache key.
+ */
+function styleKey(spec: StyleSpec): string {
+	const parts: string[] = []
+	// Use fixed property order for deterministic keys
+	if (spec.fg !== undefined) {
+		parts.push(typeof spec.fg === "number" ? `f${spec.fg}` : `f${spec.fg.r},${spec.fg.g},${spec.fg.b}`)
+	}
+	if (spec.bg !== undefined) {
+		parts.push(typeof spec.bg === "number" ? `b${spec.bg}` : `b${spec.bg.r},${spec.bg.g},${spec.bg.b}`)
+	}
+	if (spec.bold) parts.push("B")
+	if (spec.italic) parts.push("I")
+	if (spec.underline) parts.push("U")
+	if (spec.inverse) parts.push("V")
+	return parts.join("|")
 }
 
 /**
@@ -20,56 +40,57 @@ export type StyleSpec = {
  * 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>()
+	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
-  }
+	/** Get or create a numeric style id for a given style spec. */
+	id(spec?: StyleSpec): number {
+		if (!spec) return 0
+		const key = styleKey(spec)
+		if (key === "") return 0 // empty object = default style
+		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`
-  }
+	/** 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")
+	/**
+	 * 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 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)
+		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`
-  }
+		return `${CSI}${parts.join(";")}m`
+	}
 }
 
 /**
@@ -77,37 +98,37 @@ export class Palette {
  * 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()
-  }
+	constructor(
+		private readonly base: Palette,
+		private readonly baseStyle?: StyleSpec,
+	) {
+		super()
+	}
 
-  override id(spec?: StyleSpec): number {
-    return this.base.id(mergeStyle(this.baseStyle, spec))
-  }
+	override id(spec?: StyleSpec): number {
+		return this.base.id(mergeStyle(this.baseStyle, spec))
+	}
 
-  override sgr(id: number): string {
-    return this.base.sgr(id)
-  }
+	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
+	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
 }

package/src/render/segmenter.ts

@@ -0,0 +1,27 @@
+/* segmenter.ts — Cached grapheme segmenter for text processing */
+
+export type GraphemeSegmenter = {
+	segment(input: string): Iterable<{ segment: string }>
+}
+
+// Cached segmenter instance (created once, reused for all calls)
+let cachedSegmenter: GraphemeSegmenter | null | undefined = undefined
+
+/** Get or create a cached grapheme segmenter. Returns null if Intl.Segmenter unavailable. */
+export function getGraphemeSegmenter(): GraphemeSegmenter | null {
+	if (cachedSegmenter !== undefined) return cachedSegmenter
+
+	const SegCtor: { new (...args: any[]): GraphemeSegmenter } | undefined = (globalThis as any).Intl?.Segmenter
+	if (typeof SegCtor === "function") {
+		try {
+			cachedSegmenter = new (SegCtor as new (...args: any[]) => GraphemeSegmenter)(undefined, {
+				granularity: "grapheme",
+			}) as GraphemeSegmenter
+			return cachedSegmenter
+		} catch {
+			// ignore and fall back
+		}
+	}
+	cachedSegmenter = null
+	return null
+}

package/src/render/surface.ts

@@ -1,238 +1,152 @@
 import { CellBuffer, type Wcwidth, defaultWcwidth } from "./buffer.js"
 import { Palette, ScopedPalette, type ColorValue, type StyleSpec, mergeStyle } from "./palette.js"
+import { Colors, parseColor, BASE_NAMES, type Color, type HexColor, type BaseColorName } from "../colors.js"
+import { emitRow } from "../output.js"
 
 // Re-export palette types for other modules
 export type { ColorValue, StyleSpec }
 export { Palette, mergeStyle }
 
-/** Color inputs accepted by helpers: numeric, rgb object, or string (hex/name/grayN). */
-export type ColorLike = ColorValue | string
-
-export const BASE_NAMES = {
-  black: 0,
-  red: 1,
-  green: 2,
-  yellow: 3,
-  blue: 4,
-  magenta: 5,
-  cyan: 6,
-  white: 7,
-  brightBlack: 8,
-  brightRed: 9,
-  brightGreen: 10,
-  brightYellow: 11,
-  brightBlue: 12,
-  brightMagenta: 13,
-  brightCyan: 14,
-  brightWhite: 15,
-} as const
-
-/**
- * Parse flexible color inputs into a ColorValue.
- * Supports: number (0..255), {r,g,b}, "#rrggbb", base names, and gray0..gray23.
- */
-export function parseColor(c: ColorLike): ColorValue {
-  if (typeof c === "number") return c
-  if (typeof c === "object") return { r: c.r | 0, g: c.g | 0, b: c.b | 0 }
-  const s = String(c).trim()
-
-  if (s.startsWith("#")) {
-    const hex = s.slice(1)
-    if (hex.length === 6) {
-      const r = parseInt(hex.slice(0, 2), 16)
-      const g = parseInt(hex.slice(2, 4), 16)
-      const b = parseInt(hex.slice(4, 6), 16)
-      return { r, g, b }
-    }
-  }
-
-  if (s in BASE_NAMES) return BASE_NAMES[s as keyof typeof BASE_NAMES]
-
-  const m = /^(?:gray|grey)(\d{1,2})$/.exec(s)
-  if (m?.[1]) {
-    const n = Math.max(0, Math.min(23, parseInt(m[1], 10)))
-    return 232 + n
-  }
-
-  return 7 // default to white if unrecognized
-}
-
-type ColorsApi = typeof BASE_NAMES & {
-  rgb(r: number, g: number, b: number): ColorValue
-  hex(hex: string): ColorValue
-  gray(level: number): number
-}
-
-export const Colors: ColorsApi = Object.assign(
-  {
-    rgb(r: number, g: number, b: number): ColorValue {
-      return { r, g, b }
-    },
-    hex(hex: string): ColorValue {
-      return parseColor(hex)
-    },
-    gray(level: number): number {
-      const n = Math.max(0, Math.min(23, level | 0))
-      return 232 + n
-    },
-  },
-  BASE_NAMES,
-) as ColorsApi
+// Re-export color utilities from colors.ts
+export { Colors, parseColor, BASE_NAMES }
+export type { Color, HexColor, BaseColorName }
 
 export function derivePalette(p: Palette, base?: StyleSpec): Palette {
-  return new ScopedPalette(p, base)
+	return new ScopedPalette(p, base)
 }
 
 export class Surface {
-  readonly w: number
-  readonly h: number
-  private B: CellBuffer
-  private palette: Palette
-
-  constructor(width: number, height: number, opts?: { palette?: Palette; wcwidth?: Wcwidth }) {
-    this.w = Math.max(1, width | 0)
-    this.h = Math.max(1, height | 0)
-
-    const wc = opts?.wcwidth ?? defaultWcwidth
-    this.B = new CellBuffer(this.w, this.h, wc)
-    this.palette = opts?.palette ?? new Palette()
-
-    this.B.clear(0)
-  }
-
-  /** Clear the back buffer (B) to spaces in the given style. */
-  clear(styleId = 0): void {
-    this.B.clear(styleId)
-  }
-
-  /** Draw a single code point at (x,y). If width=2, marks the following cell as continuation (w=0). */
-  drawCP(x: number, y: number, cp: number, styleId = 0): void {
-    this.B.drawCP(x, y, cp, styleId)
-  }
-
-  /** 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 {
-    this.B.drawText(x, y, text, styleId, maxWidth)
-  }
-
-  /** Fill a rectangle with a code point + style. */
-  fillRect(x: number, y: number, w: number, h: number, cp = 32, styleId = 0): void {
-    this.B.fillRect(x, y, w, h, cp, styleId)
-  }
-
-  // --- Clipping helpers (forwarded to back buffer) ---
-
-  pushClip(x: number, y: number, w: number, h: number): void {
-    this.B.pushClip(x, y, w, h)
-  }
-
-  popClip(): void {
-    this.B.popClip()
-  }
-
-  withClip(x: number, y: number, w: number, h: number, fn: () => void): void {
-    this.B.withClip(x, y, w, h, fn)
-  }
-
-  // --- Offset helpers (forwarded to back buffer) ---
-
-  pushOffset(dx: number, dy: number): void {
-    this.B.pushOffset(dx, dy)
-  }
-
-  popOffset(): void {
-    this.B.popOffset()
-  }
-
-  withOffset(dx: number, dy: number, fn: () => void): void {
-    this.B.withOffset(dx, dy, fn)
-  }
-
-  /** Convert surface to plain text (for testing). */
-  toString(): string {
-    const lines: string[] = []
-    for (let y = 0; y < this.h; y++) {
-      const row = y * this.w
-      let line = ""
-      for (let x = 0; x < this.w; x++) {
-        const i = row + x
-        const cp = this.B.g[i]
-        const w = this.B.cw[i]
-        if (w !== 0) line += cp === 32 ? " " : String.fromCodePoint(cp)
-      }
-      // trim right spaces
-      line = line.replace(/\s+$/, "")
-      lines.push(line)
-    }
-    return lines.join("\n")
-  }
-
-  /** Compute tight bounding box of content in back buffer: any non-space glyph or non-default style. */
-  contentBounds(): { x: number; y: number; w: number; h: number } {
-    const W = this.w
-    const H = this.h
-    const g = this.B.g
-    const s = this.B.s
-    const cw = this.B.cw
-    let minX = W,
-      minY = H,
-      maxX = -1,
-      maxY = -1
-    for (let y = 0; y < H; y++) {
-      const row = y * W
-      for (let x = 0; x < W; x++) {
-        const i = row + x
-        if (cw[i] === 0) continue
-        if (g[i] !== 32 || s[i] !== 0) {
-          if (x < minX) minX = x
-          if (y < minY) minY = y
-          if (x > maxX) maxX = x
-          if (y > maxY) maxY = y
-        }
-      }
-    }
-    if (maxX < minX || maxY < minY) return { x: 0, y: 0, w: 0, h: 0 }
-    return { x: minX, y: minY, w: maxX - minX + 1, h: maxY - minY + 1 }
-  }
-
-  /** Build styled text lines for a given bounds region of the back buffer (without trailing newlines). */
-  buildStyledLines(bounds: { x: number; y: number; w: number; h: number }, palette: Palette = this.palette): string[] {
-    const W = this.w
-    const g = this.B.g
-    const s = this.B.s
-    const cw = this.B.cw
-    const lines: string[] = []
-    const { x: bx, y: by, w: bw, h: bh } = bounds
-    const endY = Math.min(by + bh, this.h)
-    const endX = Math.min(bx + bw, W)
-
-    for (let y = Math.max(0, by); y < endY; y++) {
-      const row = y * W
-      let line = ""
-      let currentStyle = -1
-
-      for (let x = Math.max(0, bx); x < endX; x++) {
-        const i = row + x
-        if (cw[i] === 0) continue // skip continuation cells
-
-        const styleId = s[i]
-        if (styleId !== currentStyle) {
-          line += palette.sgr(styleId)
-          currentStyle = styleId
-        }
-
-        const cp = g[i]
-        line += cp === 32 ? " " : String.fromCodePoint(cp)
-      }
-
-      // reset style at end of line
-      if (currentStyle !== 0) {
-        line += palette.sgr(0)
-      }
-
-      lines.push(line)
-    }
-
-    return lines
-  }
+	readonly w: number
+	readonly h: number
+	private B: CellBuffer
+	private palette: Palette
+
+	/** Access the underlying CellBuffer for diffing or inspection. */
+	get buffer(): CellBuffer {
+		return this.B
+	}
+
+	constructor(width: number, height: number, opts?: { palette?: Palette; wcwidth?: Wcwidth }) {
+		this.w = Math.max(1, width | 0)
+		this.h = Math.max(1, height | 0)
+
+		const wc = opts?.wcwidth ?? defaultWcwidth
+		this.B = new CellBuffer(this.w, this.h, wc)
+		this.palette = opts?.palette ?? new Palette()
+
+		this.B.clear(0)
+	}
+
+	/** Clear the back buffer (B) to spaces in the given style. */
+	clear(styleId = 0): void {
+		this.B.clear(styleId)
+	}
+
+	/** Draw a single code point at (x,y). If width=2, marks the following cell as continuation (w=0). */
+	drawCP(x: number, y: number, cp: number, styleId = 0): void {
+		this.B.drawCP(x, y, cp, styleId)
+	}
+
+	/** 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 {
+		this.B.drawText(x, y, text, styleId, maxWidth)
+	}
+
+	/** Fill a rectangle with a code point + style. */
+	fillRect(x: number, y: number, w: number, h: number, cp = 32, styleId = 0): void {
+		this.B.fillRect(x, y, w, h, cp, styleId)
+	}
+
+	// --- Clipping helpers (forwarded to back buffer) ---
+
+	pushClip(x: number, y: number, w: number, h: number): void {
+		this.B.pushClip(x, y, w, h)
+	}
+
+	popClip(): void {
+		this.B.popClip()
+	}
+
+	withClip(x: number, y: number, w: number, h: number, fn: () => void): void {
+		this.B.withClip(x, y, w, h, fn)
+	}
+
+	// --- Offset helpers (forwarded to back buffer) ---
+
+	pushOffset(dx: number, dy: number): void {
+		this.B.pushOffset(dx, dy)
+	}
+
+	popOffset(): void {
+		this.B.popOffset()
+	}
+
+	withOffset(dx: number, dy: number, fn: () => void): void {
+		this.B.withOffset(dx, dy, fn)
+	}
+
+	/** Convert surface to plain text (for testing). */
+	toString(): string {
+		const lines: string[] = []
+		for (let y = 0; y < this.h; y++) {
+			const row = y * this.w
+			let line = ""
+			for (let x = 0; x < this.w; x++) {
+				const i = row + x
+				const cp = this.B.g[i]
+				const w = this.B.cw[i]
+				if (w !== 0) line += cp === 32 ? " " : String.fromCodePoint(cp)
+			}
+			// trim right spaces
+			line = line.replace(/\s+$/, "")
+			lines.push(line)
+		}
+		return lines.join("\n")
+	}
+
+	/** Compute tight bounding box of content in back buffer: any non-space glyph or non-default style. */
+	contentBounds(): { x: number; y: number; w: number; h: number } {
+		const W = this.w
+		const H = this.h
+		const g = this.B.g
+		const s = this.B.s
+		const cw = this.B.cw
+		let minX = W,
+			minY = H,
+			maxX = -1,
+			maxY = -1
+		for (let y = 0; y < H; y++) {
+			const row = y * W
+			for (let x = 0; x < W; x++) {
+				const i = row + x
+				if (cw[i] === 0) continue
+				if (g[i] !== 32 || s[i] !== 0) {
+					if (x < minX) minX = x
+					if (y < minY) minY = y
+					if (x > maxX) maxX = x
+					if (y > maxY) maxY = y
+				}
+			}
+		}
+		if (maxX < minX || maxY < minY) return { x: 0, y: 0, w: 0, h: 0 }
+		return { x: minX, y: minY, w: maxX - minX + 1, h: maxY - minY + 1 }
+	}
+
+	/** Build styled text lines for a given bounds region of the back buffer (without trailing newlines). */
+	buildStyledLines(bounds: { x: number; y: number; w: number; h: number }, palette: Palette = this.palette): string[] {
+		const W = this.w
+		const lines: string[] = []
+		const { x: bx, y: by, w: bw, h: bh } = bounds
+		const endY = Math.min(by + bh, this.h)
+		const endX = Math.min(bx + bw, W)
+		const startX = Math.max(0, bx)
+
+		for (let y = Math.max(0, by); y < endY; y++) {
+			const { output, lastStyle } = emitRow(this.B, palette, y, W, startX, endX)
+			const line = lastStyle !== 0 ? output + palette.sgr(0) : output
+			lines.push(line)
+		}
+
+		return lines
+	}
 }