@effect-tui/react 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@effect-tui/react",
+  "version": "0.1.0-alpha.1",
+  "description": "React bindings for @effect-tui/core",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./test": {
+      "import": "./dist/src/test/index.js",
+      "types": "./dist/src/test/index.d.ts"
+    },
+    "./visualize": {
+      "import": "./dist/src/visualize/index.js",
+      "types": "./dist/src/visualize/index.d.ts"
+    },
+    "./trace": {
+      "import": "./dist/src/trace/index.js",
+      "types": "./dist/src/trace/index.d.ts"
+    },
+    "./inline": {
+      "import": "./dist/src/inline/index.js",
+      "types": "./dist/src/inline/index.d.ts"
+    },
+    "./jsx-runtime": {
+      "import": "./dist/jsx-runtime.js",
+      "types": "./dist/jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "import": "./dist/jsx-dev-runtime.js",
+      "types": "./dist/jsx-dev-runtime.d.ts"
+    }
+  },
+  "types": "./dist/src/index.d.ts",
+  "keywords": [
+    "terminal",
+    "tui",
+    "effect",
+    "react",
+    "cli"
+  ],
+  "author": "Kit Langton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kitlangton/effect-tui.git",
+    "directory": "packages/effect-tui-react"
+  },
+  "homepage": "https://github.com/kitlangton/effect-tui",
+  "bugs": "https://github.com/kitlangton/effect-tui/issues",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "dependencies": {
+    "@effect/opentelemetry": "^0.59.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@effect-tui/core": "workspace:*",
+    "react-reconciler": "^0.33.0",
+    "shiki": "^3.17.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.27.0",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.0.0",
+    "@types/react-reconciler": "^0.32.3",
+    "effect": "^3.19.8",
+    "react": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  }
+}

package/src/codeblock.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react"
+import type { BundledLanguage, BundledTheme } from "shiki"
+import { highlightCode, toPlainLines, type HighlightLine } from "./highlight.js"
+import type { CodeBlockProps as HostCodeBlockProps } from "./hosts/codeblock.js"
+
+export interface CodeBlockProps extends Omit<HostCodeBlockProps, "lines"> {
+  code: string
+  language?: BundledLanguage
+  theme?: BundledTheme
+}
+
+export function CodeBlock({
+  code,
+  language = "ts",
+  theme = "nord",
+  lineNumbers = true,
+  padding = 1,
+  background,
+  ...rest
+}: CodeBlockProps) {
+  const [lines, setLines] = useState<HighlightLine[]>(() => toPlainLines(code))
+
+  useEffect(() => {
+    let cancelled = false
+    highlightCode(code, { lang: language, theme })
+      .then((result) => {
+        if (!cancelled) setLines(result)
+      })
+      .catch((err) => {
+        console.warn("CodeBlock: highlighting failed, falling back to plain text", err)
+        if (!cancelled) setLines(toPlainLines(code))
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [code, language, theme])
+
+  return (
+    <codeblock
+      {...(rest as Record<string, unknown>)}
+      lines={lines}
+      lineNumbers={lineNumbers as boolean}
+      padding={padding as HostCodeBlockProps["padding"]}
+      background={background as HostCodeBlockProps["background"]}
+    />
+  )
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** Default frames per second for renderer and animation loops */
+export const DEFAULT_FPS = 60

package/src/debug/DiagnosticsPanel.tsx

@@ -0,0 +1,38 @@
+import { Colors } from "@effect-tui/core"
+import { useFrameStats } from "../hooks/useFrameStats.js"
+import "../jsx.js"
+
+export interface DiagnosticsPanelProps {
+  sampleMs?: number
+  title?: string
+}
+
+export function DiagnosticsPanel({ sampleMs = 200, title = "Diagnostics" }: DiagnosticsPanelProps) {
+  const stats = useFrameStats(sampleMs)
+
+  const fps = stats ? (stats.frameMs > 0 ? (1000 / stats.frameMs).toFixed(1) : "∞") : "—"
+  const bytes = stats ? stats.bytes : 0
+  const h = stats ? stats.contentHeight : 0
+  const phases = stats?.phases
+
+  return (
+    <vstack spacing={1}>
+      <text fg={Colors.cyan} bold>
+        {title} ({stats?.mode ?? "?"})
+      </text>
+      {stats ? (
+        <>
+          <text fg={Colors.gray(12)}>
+            size {stats.width}×{stats.height} content {h} rows — {bytes} bytes/frame — {fps} fps
+          </text>
+          <text fg={Colors.gray(12)}>
+            clear {phases?.clear.toFixed(2)}ms · layout {phases?.layout.toFixed(2)}ms · render{" "}
+            {phases?.render.toFixed(2)}ms · diff {phases?.diffAnsi.toFixed(2)}ms · write {phases?.write.toFixed(2)}ms
+          </text>
+        </>
+      ) : (
+        <text fg={Colors.gray(10)}>Waiting for first frame…</text>
+      )}
+    </vstack>
+  )
+}

package/src/highlight.ts

@@ -0,0 +1,76 @@
+import { createHighlighter, type Highlighter, type BundledLanguage, type BundledTheme } from "shiki"
+import type { ColorLike } from "@effect-tui/core"
+
+export interface HighlightTokenStyle {
+  fg?: ColorLike
+  bg?: ColorLike
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+}
+
+export interface HighlightToken {
+  text: string
+  style?: HighlightTokenStyle
+}
+
+export type HighlightLine = HighlightToken[]
+
+const DEFAULT_LANGS: BundledLanguage[] = ["ts", "tsx", "js", "jsx", "json"]
+const DEFAULT_THEME: BundledTheme = "nord"
+
+const highlighterCache = new Map<string, Promise<Highlighter>>()
+
+async function getCachedHighlighter(theme: BundledTheme): Promise<Highlighter> {
+  const key = String(theme)
+  let cached = highlighterCache.get(key)
+  if (!cached) {
+    cached = createHighlighter({
+      themes: [theme],
+      langs: DEFAULT_LANGS,
+    })
+    highlighterCache.set(key, cached)
+  }
+  return cached
+}
+
+export async function highlightCode(
+  code: string,
+  opts?: { lang?: BundledLanguage; theme?: BundledTheme },
+): Promise<HighlightLine[]> {
+  const lang = opts?.lang ?? ("ts" satisfies BundledLanguage)
+  const theme = opts?.theme ?? DEFAULT_THEME
+
+  const highlighter = await getCachedHighlighter(theme)
+
+  if (!highlighter.getLoadedLanguages().includes(lang)) {
+    await highlighter.loadLanguage(lang)
+  }
+
+  const tokensResult = await highlighter.codeToTokens(code, { lang, theme })
+  const tokenLines = Array.isArray(tokensResult)
+    ? tokensResult
+    : // Shiki v3 returns { tokens, theme }
+      (tokensResult as any).tokens
+
+  if (!Array.isArray(tokenLines)) return toPlainLines(code)
+
+  return tokenLines.map((line: any[]) =>
+    line.map((token) => {
+      const style: HighlightTokenStyle = {}
+      if (token.color) style.fg = token.color
+      const fs = token.fontStyle ?? 0
+      // fontStyle bitmask is: 1 = Italic, 2 = Bold, 4 = Underline
+      if (fs & 2) style.bold = true
+      if (fs & 1) style.italic = true
+      if (fs & 4) style.underline = true
+
+      return Object.keys(style).length > 0 ? { text: token.content, style } : { text: token.content }
+    }),
+  )
+}
+
+export function toPlainLines(code: string): HighlightLine[] {
+  if (code.length === 0) return [[]]
+  return code.split(/\r?\n/).map((line) => [{ text: line }])
+}

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useKeyboard } from "./use-keyboard.js"
+export type { UseKeyboardOptions } from "./use-keyboard.js"
+export { usePaste } from "./use-paste.js"

package/src/hooks/use-keyboard.ts

@@ -0,0 +1,37 @@
+import { useEffect } from "react"
+import type { KeyMsg } from "@effect-tui/core"
+import { useRenderer } from "../renderer.js"
+
+export type UseKeyboardOptions = {
+  /** Which phase to listen for; defaults to "press" and treats missing phase as "press". */
+  phase?: "press" | "repeat" | "release" | "any"
+  /** Optional predicate to drop keys before they reach the handler. */
+  filter?: (key: KeyMsg) => boolean
+  /**
+   * If true, call preventDefault when available before invoking handler.
+   * This stops further renderer-level handlers (not a terminal effect).
+   */
+  stopPropagation?: boolean
+}
+
+/**
+ * Subscribe to keyboard events.
+ * Handler is called for every key press while mounted.
+ */
+export function useKeyboard(handler: (key: KeyMsg) => void, opts?: UseKeyboardOptions): void {
+  const renderer = useRenderer()
+  const phase = opts?.phase ?? "press"
+  const filter = opts?.filter
+  const stopPropagation = opts?.stopPropagation ?? false
+
+  useEffect(() => {
+    const wrapped = (key: KeyMsg) => {
+      const keyPhase = key.phase ?? "press"
+      if (phase !== "any" && phase !== keyPhase) return
+      if (filter && !filter(key)) return
+      if (stopPropagation && key.preventDefault) key.preventDefault()
+      handler(key)
+    }
+    return renderer.onKey(wrapped)
+  }, [renderer, handler, phase, filter, stopPropagation])
+}

package/src/hooks/use-paste.ts

@@ -0,0 +1,14 @@
+import { useEffect } from "react"
+import { useRenderer } from "../renderer.js"
+
+/**
+ * Subscribe to bracketed paste events (if supported by renderer/terminal).
+ */
+export function usePaste(handler: (text: string) => void): void {
+  const renderer = useRenderer()
+
+  useEffect(() => {
+    if (!renderer.onPaste) return
+    return renderer.onPaste(handler)
+  }, [renderer, handler])
+}

package/src/hooks/useFrameStats.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react"
+import { useRenderer } from "../renderer.js"
+import type { FrameStats } from "../renderer.js"
+
+/**
+ * Subscribe to per-frame renderer stats (if enabled).
+ * Falls back to null when the renderer does not support onFrameStats.
+ */
+export function useFrameStats(sampleMs = 200): FrameStats | null {
+  const renderer = useRenderer()
+  const [stats, setStats] = useState<FrameStats | null>(null)
+
+  useEffect(() => {
+    if (!renderer.onFrameStats) return
+
+    let last: FrameStats | null = null
+    const unsub = renderer.onFrameStats((s) => {
+      last = s
+    })
+
+    const id = setInterval(() => {
+      if (last) setStats(last)
+    }, sampleMs)
+
+    return () => {
+      clearInterval(id)
+      unsub?.()
+    }
+  }, [renderer, sampleMs])
+
+  return stats
+}

package/src/hosts/base.ts

@@ -0,0 +1,65 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostInstance, Rect, Size, HostContext, CommonProps } from "../reconciler/types.js"
+
+let idCounter = 0
+
+export abstract class BaseHost implements HostInstance {
+  id: string
+  type: string
+  parent: HostInstance | null = null
+  children: HostInstance[] = []
+  rect: Rect | null = null
+
+  // Common flex props
+  flexGrow = 0
+  flexShrink = 1
+
+  protected ctx: HostContext
+
+  constructor(type: string, props: CommonProps, ctx: HostContext) {
+    this.id = `${type}-${idCounter++}`
+    this.type = type
+    this.ctx = ctx
+    this.updateProps(props)
+  }
+
+  abstract measure(maxW: number, maxH: number): Size
+  abstract render(buffer: CellBuffer, palette: Palette): void
+
+  layout(rect: Rect): void {
+    this.rect = rect
+  }
+
+  updateProps(props: Record<string, unknown>): void {
+    if (props.flexGrow !== undefined) this.flexGrow = props.flexGrow as number
+    if (props.flexShrink !== undefined) this.flexShrink = props.flexShrink as number
+  }
+
+  destroy(): void {
+    // Override in subclasses if cleanup needed
+  }
+
+  // Child management helpers
+  appendChild(child: HostInstance): void {
+    this.children.push(child)
+    child.parent = this
+  }
+
+  removeChild(child: HostInstance): void {
+    const idx = this.children.indexOf(child)
+    if (idx >= 0) {
+      this.children.splice(idx, 1)
+      child.parent = null
+    }
+  }
+
+  insertBefore(child: HostInstance, before: HostInstance): void {
+    const idx = this.children.indexOf(before)
+    if (idx >= 0) {
+      this.children.splice(idx, 0, child)
+    } else {
+      this.children.push(child)
+    }
+    child.parent = this
+  }
+}

package/src/hosts/box.ts

@@ -0,0 +1,105 @@
+import type { CellBuffer, Palette, ColorValue } from "@effect-tui/core"
+import { Colors } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import { type BorderKind, borderChars, drawBorder, type Padding, type PaddingInput, resolvePadding } from "../utils/index.js"
+
+export type { BorderKind }
+
+export interface BoxProps extends CommonProps {
+  padding?: PaddingInput
+  border?: BorderKind
+  borderColor?: ColorValue
+  bg?: ColorValue
+}
+
+export class BoxHost extends BaseHost {
+  padding: Padding = { top: 0, right: 0, bottom: 0, left: 0 }
+  border: BorderKind = "none"
+  borderColor?: ColorValue
+  bg?: ColorValue
+
+  constructor(props: BoxProps, ctx: HostContext) {
+    super("box", props, ctx)
+    this.updateProps(props)
+  }
+
+  private get borderThickness(): number {
+    return this.border === "none" ? 0 : 1
+  }
+
+  private get insetX(): number {
+    return this.borderThickness + this.padding.left + this.padding.right + this.borderThickness
+  }
+
+  private get insetY(): number {
+    return this.borderThickness + this.padding.top + this.padding.bottom + this.borderThickness
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    const innerMaxW = Math.max(0, maxW - this.insetX)
+    const innerMaxH = Math.max(0, maxH - this.insetY)
+
+    // Measure single child (box should have at most one child)
+    let childW = 0
+    let childH = 0
+    if (this.children.length > 0) {
+      const childSize = this.children[0].measure(innerMaxW, innerMaxH)
+      childW = childSize.w
+      childH = childSize.h
+    }
+
+    return {
+      w: childW + this.insetX,
+      h: childH + this.insetY,
+    }
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+
+    const t = this.borderThickness
+    const innerRect: Rect = {
+      x: rect.x + t + this.padding.left,
+      y: rect.y + t + this.padding.top,
+      w: Math.max(0, rect.w - this.insetX),
+      h: Math.max(0, rect.h - this.insetY),
+    }
+
+    // Layout single child
+    if (this.children.length > 0) {
+      this.children[0].layout(innerRect)
+    }
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    if (!this.rect) return
+    const { x, y, w, h } = this.rect
+
+    // Draw background if set
+    if (this.bg !== undefined) {
+      const bgStyle = palette.id({ bg: this.bg })
+      buffer.fillRect(x, y, w, h, " ".codePointAt(0)!, bgStyle)
+    }
+
+    // Draw border
+    if (this.border !== "none" && w >= 2 && h >= 2) {
+      const chars = borderChars(this.border)
+      const borderStyle = palette.id({ fg: this.borderColor ?? Colors.gray(8) })
+      drawBorder(buffer, x, y, w, h, chars, borderStyle)
+    }
+
+    // Render children
+    for (const child of this.children) {
+      child.render(buffer, palette)
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.padding !== undefined) this.padding = resolvePadding(props.padding as BoxProps["padding"])
+    if (props.border !== undefined) this.border = props.border as BorderKind
+    if (props.borderColor !== undefined) this.borderColor = props.borderColor as ColorValue
+    if (props.bg !== undefined) this.bg = props.bg as ColorValue
+  }
+}

package/src/hosts/canvas.ts

@@ -0,0 +1,155 @@
+import type { CellBuffer, Palette, ColorValue } from "@effect-tui/core"
+import { Colors } from "@effect-tui/core"
+import type { HostContext, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import { type BorderKind, borderChars, drawBorder } from "../utils/index.js"
+
+export type { BorderKind }
+
+export interface DrawContext {
+  /** Canvas width in cells */
+  width: number
+  /** Canvas height in cells */
+  height: number
+
+  /** Draw text at position */
+  text(x: number, y: number, str: string, opts?: { fg?: ColorValue; bg?: ColorValue }): void
+
+  /** Fill rectangle with character */
+  fill(x: number, y: number, w: number, h: number, char?: string, opts?: { fg?: ColorValue; bg?: ColorValue }): void
+
+  /** Draw box with optional border */
+  box(
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    opts?: {
+      border?: BorderKind
+      borderColor?: ColorValue
+      bg?: ColorValue
+      fg?: ColorValue
+    },
+  ): void
+
+  /** Clear entire canvas */
+  clear(): void
+}
+
+export interface CanvasProps extends CommonProps {
+  /** Draw function called each render */
+  draw: (ctx: DrawContext) => void
+  /** Fixed width (default: fill available) */
+  width?: number
+  /** Fixed height (default: fill available) */
+  height?: number
+}
+
+export class CanvasHost extends BaseHost {
+  draw: CanvasProps["draw"] = () => {}
+  fixedWidth?: number
+  fixedHeight?: number
+
+  constructor(props: CanvasProps, ctx: HostContext) {
+    super("canvas", props, ctx)
+    this.updateProps(props)
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    return {
+      w: this.fixedWidth ?? maxW,
+      h: this.fixedHeight ?? maxH,
+    }
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    if (!this.rect) return
+    const { x: ox, y: oy, w, h } = this.rect
+
+    // Create draw context
+    const ctx: DrawContext = {
+      width: w,
+      height: h,
+
+      text: (x, y, str, opts) => {
+        const px = Math.round(ox + x)
+        const py = Math.round(oy + y)
+        if (py < oy || py >= oy + h) return
+        const style = palette.id({ fg: opts?.fg, bg: opts?.bg })
+        let col = px
+        for (const char of str) {
+          if (col >= ox + w) break
+          if (col >= ox) {
+            buffer.drawCP(col, py, char.codePointAt(0)!, style)
+          }
+          col++
+        }
+      },
+
+      fill: (x, y, fw, fh, char = " ", opts) => {
+        const px = Math.round(ox + x)
+        const py = Math.round(oy + y)
+        const cp = char.codePointAt(0)!
+        const style = palette.id({ fg: opts?.fg, bg: opts?.bg })
+        for (let row = 0; row < fh; row++) {
+          const yy = py + row
+          if (yy < oy || yy >= oy + h) continue
+          for (let col = 0; col < fw; col++) {
+            const xx = px + col
+            if (xx < ox || xx >= ox + w) continue
+            buffer.drawCP(xx, yy, cp, style)
+          }
+        }
+      },
+
+      box: (x, y, bw, bh, opts) => {
+        const px = Math.round(ox + x)
+        const py = Math.round(oy + y)
+        const border = opts?.border ?? "none"
+        const bgStyle = opts?.bg !== undefined ? palette.id({ bg: opts.bg }) : undefined
+
+        // Fill background (with clipping)
+        if (bgStyle !== undefined) {
+          for (let row = 0; row < bh; row++) {
+            const yy = py + row
+            if (yy < oy || yy >= oy + h) continue
+            for (let col = 0; col < bw; col++) {
+              const xx = px + col
+              if (xx < ox || xx >= ox + w) continue
+              buffer.drawCP(xx, yy, " ".codePointAt(0)!, bgStyle)
+            }
+          }
+        }
+
+        // Draw border (with clipping)
+        if (border !== "none" && bw >= 2 && bh >= 2) {
+          const chars = borderChars(border)
+          const borderStyle = palette.id({ fg: opts?.borderColor ?? opts?.fg ?? Colors.gray(8) })
+          drawBorder(buffer, px, py, bw, bh, chars, borderStyle, { ox, oy, w, h })
+        }
+      },
+
+      clear: () => {
+        const style = palette.id({})
+        for (let row = 0; row < h; row++) {
+          for (let col = 0; col < w; col++) {
+            buffer.drawCP(ox + col, oy + row, " ".codePointAt(0)!, style)
+          }
+        }
+      },
+    }
+
+    // Call user's draw function
+    this.draw(ctx)
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.draw !== undefined) {
+      this.draw = props.draw as CanvasProps["draw"]
+      this.ctx.requestRender() // trigger repaint when draw function changes
+    }
+    if (props.width !== undefined) this.fixedWidth = props.width as number
+    if (props.height !== undefined) this.fixedHeight = props.height as number
+  }
+}