@effect-tui/react 0.1.0-alpha.1

package/src/trace/tui-logger.ts

@@ -0,0 +1,72 @@
+// Custom Effect logger that feeds logs into SpanTreeState for TUI visualization
+
+import { Logger, FiberRef, FiberRefs, Cause, Context, Tracer } from "effect"
+import type { LogLevel, SourceLocation, SpanTreeState } from "./span-state.js"
+import { captureAppLocation, parseStackLine, pickBestLocation } from "./location.js"
+
+function captureCallerLocation(): SourceLocation | undefined {
+  const err = new Error()
+  const stack = err.stack
+  if (!stack) return
+
+  const lines = stack.split("\n").slice(1)
+  const parsed: SourceLocation[] = []
+  for (const line of lines) {
+    if (line.includes("tui-logger") || line.includes("makeTuiLogger")) continue
+    const loc = parseStackLine(line)
+    if (loc) parsed.push(loc)
+  }
+
+  const best = pickBestLocation(parsed)
+  if (best) return best
+  return captureAppLocation([/tui-logger/, /makeTuiLogger/])
+}
+
+/**
+ * Create a Logger that feeds log entries into SpanTreeState.
+ * Logs are associated with the current span and displayed in the TUI.
+ */
+export function makeTuiLogger(state: SpanTreeState, onUpdate: () => void): Logger.Logger<unknown, void> {
+  return Logger.make(({ logLevel, message, cause, context }) => {
+    const debugStacks = process.env.EFFECT_TUI_DEBUG_STACKS === "1"
+    // Get current context from fiber refs
+    const ctx = FiberRefs.getOrDefault(context, FiberRef.currentContext)
+
+    // Get current span from context
+    const spanOption = Context.getOption(ctx, Tracer.ParentSpan)
+    if (spanOption._tag !== "Some") return
+
+    const span = spanOption.value
+    if (!span || typeof span !== "object") return
+
+    // Get span ID - Effect spans have spanContext() method
+    const anySpan = span as any
+    const spanId = typeof anySpan.spanContext === "function" ? anySpan.spanContext().spanId : anySpan.spanId
+    if (!spanId) return
+
+    // Map Effect log level to our level
+    let level: LogLevel = "INFO"
+    const levelLabel = logLevel.label.toUpperCase()
+    if (levelLabel === "ERROR" || levelLabel === "FATAL") level = "ERROR"
+    else if (levelLabel === "WARNING" || levelLabel === "WARN") level = "WARN"
+    else if (levelLabel === "DEBUG") level = "DEBUG"
+    else if (levelLabel === "TRACE") level = "TRACE"
+
+    // Format message
+    let text = String(message)
+
+    // Add cause if present
+    if (cause && !Cause.isEmpty(cause)) {
+      text += ` ${Cause.pretty(cause)}`
+    }
+
+    const location = captureCallerLocation()
+
+    state.addLog(spanId, level, text, location)
+    if (!location && debugStacks) {
+      // eslint-disable-next-line no-console
+      console.error("[effect-tui] no location for log; stack:", new Error().stack)
+    }
+    onUpdate()
+  })
+}

package/src/utils/border.ts

@@ -0,0 +1,108 @@
+/**
+ * Border utilities shared between box and canvas hosts.
+ */
+
+import type { CellBuffer } from "@effect-tui/core"
+
+export type BorderKind = "none" | "rounded" | "square" | "ascii"
+
+export interface BorderChars {
+  tl: string // top-left
+  tr: string // top-right
+  bl: string // bottom-left
+  br: string // bottom-right
+  h: string // horizontal
+  v: string // vertical
+}
+
+/**
+ * Get border characters for a given border style.
+ * Returns empty strings for "none" (drawing code should skip when border is "none").
+ */
+export function borderChars(kind: BorderKind): BorderChars {
+  switch (kind) {
+    case "rounded":
+      return { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│" }
+    case "square":
+      return { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│" }
+    case "ascii":
+      return { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|" }
+    default:
+      return { tl: "", tr: "", bl: "", br: "", h: "", v: "" }
+  }
+}
+
+export interface ClipRect {
+  ox: number
+  oy: number
+  w: number
+  h: number
+}
+
+/**
+ * Draw a border around a rectangle.
+ * If clip is provided, only draws within the clip bounds (for canvas).
+ * If clip is not provided, draws the full border (for box).
+ */
+export function drawBorder(
+  buffer: CellBuffer,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  chars: BorderChars,
+  style: number,
+  clip?: ClipRect,
+): void {
+  if (w < 2 || h < 2) return
+
+  const tlcp = chars.tl.codePointAt(0)!
+  const trcp = chars.tr.codePointAt(0)!
+  const blcp = chars.bl.codePointAt(0)!
+  const brcp = chars.br.codePointAt(0)!
+  const hcp = chars.h.codePointAt(0)!
+  const vcp = chars.v.codePointAt(0)!
+
+  if (clip) {
+    // Clipped drawing (for canvas)
+    const { ox, oy, w: cw, h: ch } = clip
+    const inBounds = (px: number, py: number) => px >= ox && px < ox + cw && py >= oy && py < oy + ch
+
+    // Corners
+    if (inBounds(x, y)) buffer.drawCP(x, y, tlcp, style)
+    if (inBounds(x + w - 1, y)) buffer.drawCP(x + w - 1, y, trcp, style)
+    if (inBounds(x, y + h - 1)) buffer.drawCP(x, y + h - 1, blcp, style)
+    if (inBounds(x + w - 1, y + h - 1)) buffer.drawCP(x + w - 1, y + h - 1, brcp, style)
+
+    // Horizontal lines
+    for (let col = 1; col < w - 1; col++) {
+      const xx = x + col
+      if (inBounds(xx, y)) buffer.drawCP(xx, y, hcp, style)
+      if (inBounds(xx, y + h - 1)) buffer.drawCP(xx, y + h - 1, hcp, style)
+    }
+
+    // Vertical lines
+    for (let row = 1; row < h - 1; row++) {
+      const yy = y + row
+      if (inBounds(x, yy)) buffer.drawCP(x, yy, vcp, style)
+      if (inBounds(x + w - 1, yy)) buffer.drawCP(x + w - 1, yy, vcp, style)
+    }
+  } else {
+    // Full drawing (for box)
+    // Corners
+    buffer.drawCP(x, y, tlcp, style)
+    buffer.drawCP(x + w - 1, y, trcp, style)
+    buffer.drawCP(x, y + h - 1, blcp, style)
+    buffer.drawCP(x + w - 1, y + h - 1, brcp, style)
+
+    // Horizontal lines
+    buffer.fillRect(x + 1, y, w - 2, 1, hcp, style)
+    buffer.fillRect(x + 1, y + h - 1, w - 2, 1, hcp, style)
+
+    // Vertical lines
+    for (let yy = y + 1; yy < y + h - 1; yy++) {
+      buffer.drawCP(x, yy, vcp, style)
+      buffer.drawCP(x + w - 1, yy, vcp, style)
+    }
+  }
+}

package/src/utils/flex-layout.ts

@@ -0,0 +1,125 @@
+/**
+ * Generic flex layout algorithm for VStack and HStack.
+ */
+
+import type { HostInstance, Rect, Size } from "../reconciler/types.js"
+import type { BaseHost } from "../hosts/base.js"
+
+export type FlexAxis = "vertical" | "horizontal"
+export type FlexAlignment = "start" | "center" | "end"
+
+export interface FlexMeasureResult {
+  sizes: Size[]
+  totalSize: Size
+}
+
+/**
+ * Measure children along a flex axis.
+ * Returns cached sizes and total size.
+ */
+export function measureFlex(
+  axis: FlexAxis,
+  children: HostInstance[],
+  spacing: number,
+  maxMain: number,
+  maxCross: number,
+): FlexMeasureResult {
+  const sizes: Size[] = []
+  let totalMain = 0
+  let maxChildCross = 0
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    const remainingMain = Math.max(0, maxMain - totalMain)
+
+    // For vertical: maxW=maxCross, maxH=remainingMain
+    // For horizontal: maxW=remainingMain, maxH=maxCross
+    const [childMaxW, childMaxH] = axis === "vertical" ? [maxCross, remainingMain] : [remainingMain, maxCross]
+
+    const size = child.measure(childMaxW, childMaxH)
+    sizes.push(size)
+
+    const childMain = axis === "vertical" ? size.h : size.w
+    const childCross = axis === "vertical" ? size.w : size.h
+
+    totalMain += childMain
+    if (i < children.length - 1) totalMain += spacing
+    maxChildCross = Math.max(maxChildCross, childCross)
+  }
+
+  const totalSize: Size = axis === "vertical" ? { w: maxChildCross, h: totalMain } : { w: totalMain, h: maxChildCross }
+
+  return { sizes, totalSize }
+}
+
+/**
+ * Layout children along a flex axis using cached sizes.
+ */
+export function layoutFlex(
+  axis: FlexAxis,
+  children: HostInstance[],
+  cachedSizes: Size[],
+  rect: Rect,
+  spacing: number,
+  alignment: FlexAlignment,
+  stretchCross: boolean,
+): void {
+  // Calculate totals
+  let totalNaturalMain = 0
+  let totalFlexGrow = 0
+  const totalSpacing = Math.max(0, (children.length - 1) * spacing)
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    const size = cachedSizes[i] ?? child.measure(rect.w, rect.h)
+    const childMain = axis === "vertical" ? size.h : size.w
+    totalNaturalMain += childMain
+    totalFlexGrow += (child as BaseHost).flexGrow ?? 0
+  }
+
+  // Calculate extra space to distribute
+  const availableMain = axis === "vertical" ? rect.h : rect.w
+  const extraSpace = Math.max(0, availableMain - totalNaturalMain - totalSpacing)
+
+  // Layout children
+  let mainPos = axis === "vertical" ? rect.y : rect.x
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    const size = cachedSizes[i] ?? { w: 0, h: 0 }
+    const flexGrow = (child as BaseHost).flexGrow ?? 0
+    const flexExtra = totalFlexGrow > 0 ? (extraSpace * flexGrow) / totalFlexGrow : 0
+
+    const childMain = (axis === "vertical" ? size.h : size.w) + flexExtra
+    const childCross = axis === "vertical" ? size.w : size.h
+    const crossSize = axis === "vertical" ? rect.w : rect.h
+    const crossStart = axis === "vertical" ? rect.x : rect.y
+
+    // Calculate cross position based on alignment
+    let crossPos = crossStart
+    if (alignment === "center") {
+      crossPos = crossStart + Math.floor((crossSize - childCross) / 2)
+    } else if (alignment === "end") {
+      crossPos = crossStart + crossSize - childCross
+    }
+
+    // Build child rect
+    const childRect: Rect =
+      axis === "vertical"
+        ? {
+            x: crossPos,
+            y: mainPos,
+            w: stretchCross ? crossSize : childCross,
+            h: childMain,
+          }
+        : {
+            x: mainPos,
+            y: crossPos,
+            w: childMain,
+            h: stretchCross ? crossSize : childCross,
+          }
+
+    child.layout(childRect)
+    mainPos += childMain + spacing
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export { type BorderKind, type BorderChars, borderChars, type ClipRect, drawBorder } from "./border.js"
+export { type Padding, type PaddingInput, resolvePadding } from "./padding.js"
+export { type StyleOptions } from "./styles.js"
+export { type FlexAxis, type FlexAlignment, type FlexMeasureResult, measureFlex, layoutFlex } from "./flex-layout.js"

package/src/utils/padding.ts

@@ -0,0 +1,45 @@
+/**
+ * Padding utilities shared between box, canvas, and codeblock hosts.
+ */
+
+export interface Padding {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+export type PaddingInput =
+  | number
+  | { x?: number; y?: number; top?: number; right?: number; bottom?: number; left?: number }
+
+/**
+ * Resolve padding input to a normalized Padding object.
+ * Supports:
+ * - number: uniform padding on all sides
+ * - { x, y }: horizontal and vertical padding
+ * - { top, right, bottom, left }: individual sides
+ */
+export function resolvePadding(p?: PaddingInput): Padding {
+  if (p === undefined) {
+    return { top: 0, right: 0, bottom: 0, left: 0 }
+  }
+  if (typeof p === "number") {
+    return { top: p, right: p, bottom: p, left: p }
+  }
+  // x/y shorthand takes precedence if specified
+  if (p.x !== undefined || p.y !== undefined) {
+    return {
+      top: p.y ?? 0,
+      bottom: p.y ?? 0,
+      left: p.x ?? 0,
+      right: p.x ?? 0,
+    }
+  }
+  return {
+    top: p.top ?? 0,
+    right: p.right ?? 0,
+    bottom: p.bottom ?? 0,
+    left: p.left ?? 0,
+  }
+}

package/src/utils/styles.ts

@@ -0,0 +1,14 @@
+/**
+ * Style utilities for building palette-compatible style objects.
+ */
+
+import type { ColorValue } from "@effect-tui/core"
+
+export interface StyleOptions {
+  fg?: ColorValue
+  bg?: ColorValue
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  inverse?: boolean
+}

package/src/visualize/index.tsx

@@ -0,0 +1,305 @@
+// Effect visualization wrapper using React
+// Uses Effect Layer for proper terminal state management across multiple calls
+
+import { useState, useEffect } from "react"
+import { Cause, Context, Duration, Effect, Exit, Fiber, Layer, Option } from "effect"
+import { Colors } from "@effect-tui/core"
+import { createRenderer, createRoot } from "../renderer.js"
+import { ANSI } from "../terminal.js"
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠸", "⠴", "⠦", "⠇"] as const
+const SPIN_INTERVAL_MS = 80
+const ELAPSED_INTERVAL_MS = 16
+const COMPLETION_DELAY_MS = 360
+
+type VisualizerStatus = "pending" | "success" | "failure"
+
+interface VisualizeOptions {
+  /** Show the result value below completion status */
+  showResult?: boolean
+}
+
+// Bridges Effect execution with React rendering
+class VisualizerState {
+  status: VisualizerStatus = "pending"
+  spinnerIndex = 0
+  elapsedMs = 0
+  errorSummary?: string
+  result?: unknown
+  showResult = false
+  private listeners = new Set<() => void>()
+
+  update(
+    patch: Partial<
+      Pick<VisualizerState, "status" | "spinnerIndex" | "elapsedMs" | "errorSummary" | "result" | "showResult">
+    >,
+  ) {
+    Object.assign(this, patch)
+    this.listeners.forEach((l) => l())
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+}
+
+const formatDuration = (ms: number): string => Duration.format(Duration.millis(Math.max(0, Math.round(ms))))
+
+const formatResult = (value: unknown): string => {
+  if (value === undefined) return "undefined"
+  if (value === null) return "null"
+  if (typeof value === "string") return JSON.stringify(value)
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+const summarizeCause = (cause: Cause.Cause<unknown>): string => {
+  const failure = Cause.failureOption(cause)
+  if (Option.isSome(failure)) {
+    const error = failure.value
+    if (error && typeof error === "object" && "_tag" in error && "message" in error) {
+      const message = String((error as any).message).trim()
+      return message ? `${(error as any)._tag}: ${message}` : String((error as any)._tag)
+    }
+    if (error && typeof error === "object" && "message" in error) {
+      return String((error as any).message)
+    }
+    return String(error)
+  }
+  const pretty = Cause.pretty(cause, { renderErrorCause: false })
+  const firstLine = pretty.split("\n").find((line: string) => line.trim().length > 0)
+  return firstLine ?? "Unknown failure"
+}
+
+function Visualizer({ state, label }: { state: VisualizerState; label: string }) {
+  const [, forceUpdate] = useState(0)
+
+  useEffect(() => {
+    return state.subscribe(() => forceUpdate((n) => n + 1))
+  }, [state])
+
+  const elapsed = formatDuration(state.elapsedMs)
+
+  if (state.status === "pending") {
+    return (
+      <vstack>
+        <hstack spacing={1}>
+          <text fg={Colors.brightCyan}>{SPINNER_FRAMES[state.spinnerIndex]}</text>
+          <text bold fg={Colors.brightWhite}>
+            {label}
+          </text>
+        </hstack>
+        <text fg={Colors.gray(10)}>└ Running… {elapsed}</text>
+      </vstack>
+    )
+  }
+
+  if (state.status === "success") {
+    const showingResult = state.showResult && state.result !== undefined
+    return (
+      <vstack>
+        <hstack spacing={1}>
+          <text bold fg={Colors.brightGreen}>
+            ✓
+          </text>
+          <text bold fg={Colors.brightGreen}>
+            {label}
+          </text>
+        </hstack>
+        {showingResult && <text fg={Colors.gray(20)}>├ {formatResult(state.result)}</text>}
+        <text fg={Colors.green}>
+          {showingResult ? "└" : "└"} Completed in {elapsed}
+        </text>
+      </vstack>
+    )
+  }
+
+  // failure
+  return (
+    <vstack>
+      <hstack spacing={1}>
+        <text bold fg={Colors.brightRed}>
+          ✗
+        </text>
+        <text bold fg={Colors.brightRed}>
+          {label}
+        </text>
+      </hstack>
+      <text fg={Colors.red}>├ {state.errorSummary ?? "Failed"}</text>
+      <text fg={Colors.red}>└ Failed after {elapsed}</text>
+    </vstack>
+  )
+}
+
+// ============================================================================
+// InlineRenderer Service - manages terminal state across multiple visualize()
+// ============================================================================
+
+interface InlineRendererService {
+  readonly stdout: NodeJS.WriteStream
+  readonly stdin: NodeJS.ReadStream
+}
+
+/**
+ * Service that manages terminal state for inline rendering.
+ * Hides cursor on acquire, shows cursor on release.
+ */
+export class InlineRenderer extends Context.Tag("@effect-tui/react/InlineRenderer")<
+  InlineRenderer,
+  InlineRendererService
+>() {}
+
+/**
+ * Layer that provides InlineRenderer service.
+ * Manages terminal state: hides cursor on start, restores on finalize.
+ */
+export const InlineRendererLive: Layer.Layer<InlineRenderer> = Layer.scoped(
+  InlineRenderer,
+  Effect.gen(function* () {
+    const stdout = process.stdout
+    const stdin = process.stdin
+
+    // Setup: hide cursor, enable raw mode
+    stdout.write(ANSI.cursor.hide)
+    if (stdin.isTTY && stdin.setRawMode) {
+      stdin.setRawMode(true)
+      stdin.resume()
+    }
+
+    // Teardown on scope close: show cursor, disable raw mode, pause stdin
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        stdout.write(ANSI.cursor.show)
+        if (stdin.isTTY && stdin.setRawMode) {
+          stdin.setRawMode(false)
+        }
+        // Pause stdin so Node can exit
+        stdin.pause()
+      }),
+    )
+
+    return { stdout, stdin }
+  }),
+)
+
+// ============================================================================
+// visualize() - uses InlineRenderer service
+// ============================================================================
+
+/**
+ * Wrap an Effect with inline visualization.
+ * Shows a spinner while running, then success/failure status.
+ * Returns the effect's result or propagates its error.
+ *
+ * Requires InlineRenderer service (use InlineRendererLive layer).
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const result = yield* visualize("Fetching data", fetchData)
+ *   yield* visualize("Processing", processData(result))
+ * }).pipe(Effect.provide(InlineRendererLive))
+ * ```
+ */
+export const visualize = <A, E, R>(
+  label: string,
+  effect: Effect.Effect<A, E, R>,
+  options?: VisualizeOptions,
+): Effect.Effect<A, E, R | InlineRenderer> =>
+  Effect.gen(function* () {
+    const { stdout, stdin } = yield* InlineRenderer
+
+    // Create renderer with skipTerminalSetup (Layer manages terminal state)
+    const renderer = createRenderer({
+      mode: "inline",
+      stdout,
+      stdin,
+      skipTerminalSetup: true,
+    })
+    const root = createRoot(renderer)
+
+    const state = new VisualizerState()
+    state.showResult = options?.showResult ?? false
+
+    // Mount React component
+    root.render(<Visualizer state={state} label={label} />)
+
+    // Spinner tick fiber
+    const startTime = Date.now()
+    const spinnerFiber = yield* Effect.fork(
+      Effect.forever(
+        Effect.gen(function* () {
+          yield* Effect.sleep(SPIN_INTERVAL_MS)
+          state.update({
+            spinnerIndex: (state.spinnerIndex + 1) % SPINNER_FRAMES.length,
+          })
+          renderer.requestRender()
+        }),
+      ),
+    )
+
+    // High-frequency elapsed timer so duration display stays smooth
+    const elapsedFiber = yield* Effect.fork(
+      Effect.forever(
+        Effect.gen(function* () {
+          yield* Effect.sleep(ELAPSED_INTERVAL_MS)
+          state.update({ elapsedMs: Date.now() - startTime })
+          renderer.requestRender()
+        }),
+      ),
+    )
+
+    // Run the actual effect
+    const exit = yield* Effect.exit(effect)
+
+    // Stop spinner, update state to final
+    yield* Fiber.interrupt(spinnerFiber)
+    yield* Fiber.interrupt(elapsedFiber)
+    const isSuccess = Exit.isSuccess(exit)
+    state.update(
+      isSuccess
+        ? { status: "success", elapsedMs: Date.now() - startTime, result: exit.value }
+        : { status: "failure", elapsedMs: Date.now() - startTime, errorSummary: summarizeCause(exit.cause) },
+    )
+    renderer.requestRender()
+    renderer.flush() // Ensure final state is rendered
+
+    // Wait for completion animation
+    yield* Effect.sleep(COMPLETION_DELAY_MS)
+
+    // Stop renderer (doesn't touch terminal state since skipTerminalSetup)
+    renderer.stop()
+
+    // Write newline to advance cursor past the output
+    stdout.write("\n")
+
+    // Return result or propagate failure
+    if (Exit.isSuccess(exit)) return exit.value
+    return yield* Effect.failCause(exit.cause)
+  })
+
+// ============================================================================
+// Convenience: self-contained visualize that provides its own layer
+// ============================================================================
+
+/**
+ * Self-contained visualize that manages its own terminal state.
+ * Use this for single visualize() calls. For multiple sequential calls,
+ * use visualize() with InlineRendererLive layer for better cursor handling.
+ *
+ * @example
+ * ```ts
+ * const result = yield* visualizeSingle("Fetching data", fetchData)
+ * ```
+ */
+export const visualizeSingle = <A, E, R>(
+  label: string,
+  effect: Effect.Effect<A, E, R>,
+  options?: VisualizeOptions,
+): Effect.Effect<A, E, R> =>
+  Effect.scoped(visualize(label, effect, options).pipe(Effect.provide(InlineRendererLive))) as Effect.Effect<A, E, R>