OpenTUI 渲染流程深度解析：React 代码如何显示到终端

// 用户编写的代码
import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return (
    <box alignItems="center" justifyContent="center" flexGrow={1}>
      <box justifyContent="center" alignItems="flex-end">
        <ascii-font font="tiny" text="OpenTUI" />
        <text attributes={TextAttributes.DIM}>What will you build?</text>
        <text>Hello World</text>
      </box>
    </box>
  )
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

// 编译后的等效代码
React.createElement(
  "box",
  { alignItems: "center", justifyContent: "center", flexGrow: 1 },
  React.createElement(
    "box",
    { justifyContent: "center", alignItems: "flex-end" },
    React.createElement("ascii-font", { font: "tiny", text: "OpenTUI" }),
    React.createElement("text", { attributes: TextAttributes.DIM }, "What will you build?"),
    React.createElement("text", null, "Hello World"),
  ),
)

{
  "compilerOptions": {
    "lib": ["ESNext", "DOM"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "@opentui/react",
    "strict": true,
    "skipLibCheck": true
  }
}

// packages/react/src/index.ts
import { CliRenderer, CliRenderEvents, engine } from "@opentui/core"
import React, { type ReactNode } from "react"
import type { OpaqueRoot } from "react-reconciler"
import { AppContext } from "../components/app"
import { ErrorBoundary } from "../components/error-boundary"
import { _render, reconciler } from "./reconciler"

// flushSync 用于同步刷新
const _r = reconciler as typeof reconciler & { flushSyncFromReconciler?: typeof reconciler.flushSync }
const flushSync = _r.flushSyncFromReconciler ?? _r.flushSync
const { createPortal } = reconciler

export type Root = {
  render: (node: ReactNode) => void
  unmount: () => void
}

/**
 * Creates a root for rendering a React tree with the given CLI renderer.
 */
export function createRoot(renderer: CliRenderer): Root {
  let container: OpaqueRoot | null = null

  const cleanup = () => {
    if (container) {
      reconciler.updateContainer(null, container, null, () => {})
      reconciler.flushSyncWork()
      container = null
    }
  }

  renderer.once(CliRenderEvents.DESTROY, cleanup)

  return {
    render: (node: ReactNode) => {
      // 将渲染器附加到引擎
      engine.attach(renderer)

      // 创建 React Element 树并传递给 reconciler
      container = _render(
        React.createElement(
          AppContext.Provider,
          { value: { keyHandler: renderer.keyInput, renderer } },
          React.createElement(ErrorBoundary, null, node),
        ),
        renderer.root,
      )
    },

    unmount: cleanup,
  }
}

export { createPortal, flushSync }

// packages/react/src/components/app.tsx
import type { CliRenderer, KeyHandler } from "@opentui/core"
import { createContext, useContext } from "react"

interface AppContext {
  keyHandler: KeyHandler | null
  renderer: CliRenderer | null
}

export const AppContext = createContext<AppContext>({
  keyHandler: null,
  renderer: null,
})

export const useAppContext = () => {
  return useContext(AppContext)
}

// packages/react/src/reconciler/reconciler.ts
import type { RootRenderable } from "@opentui/core"
import React from "react"
import ReactReconciler from "react-reconciler"
import { ConcurrentRoot } from "react-reconciler/constants"
import { hostConfig } from "./host-config"

export const reconciler = ReactReconciler(hostConfig)

// 开发模式下启用 React DevTools
if (process.env["DEV"] === "true") {
  try {
    await import("./devtools")
  } catch (error: any) {
    if (error.code === "ERR_MODULE_NOT_FOUND") {
      console.warn(
        `
The environment variable DEV is set to true, so opentui tried to import \`react-devtools-core\`,
but this failed as it was not installed. Debugging with React DevTools requires it.

To install use this command:

$ bun add react-devtools-core@7 -d
      `.trim() + "\n",
      )
    } else {
      throw error
    }
  }
}

// 注入到 DevTools
reconciler.injectIntoDevTools()

export function _render(element: React.ReactNode, root: RootRenderable) {
  // 创建容器
  const container = reconciler.createContainer(
    root,
    ConcurrentRoot,
    null,
    false,
    null,
    "",
    console.error,
    console.error,
    console.error,
    console.error,
    null,
  )

  // 将元素渲染到容器
  reconciler.updateContainer(element, container, null, () => {})

  return container
}

// packages/react/src/reconciler/host-config.ts
import { TextNodeRenderable, TextRenderable, type Renderable } from "@opentui/core"
import pkgJson from "../../package.json"
import { createContext } from "react"
import type { HostConfig, ReactContext } from "react-reconciler"
import { DefaultEventPriority, NoEventPriority } from "react-reconciler/constants"
import { getComponentCatalogue } from "../components"
import { textNodeKeys, type TextNodeKey } from "../components/text"
import type { Container, HostContext, Instance, Props, PublicInstance, TextInstance, Type } from "../types/host"
import { getNextId } from "../utils/id"
import { setInitialProperties, updateProperties } from "../utils/index"

// 当前更新优先级
let currentUpdatePriority = NoEventPriority

export const hostConfig: HostConfig<...> = {
  // 支持突变模式（更简单直接）
  supportsMutation: true,
  supportsPersistence: false,
  supportsHydration: false,

  // 创建组件实例
  createInstance(type: Type, props: Props, rootContainerInstance: Container, hostContext: HostContext) {
    // 文本节点必须在 text 组件内部
    if (textNodeKeys.includes(type as TextNodeKey) && !hostContext.isInsideText) {
      throw new Error(`Component of type "${type}" must be created inside of a text node`)
    }

    const id = getNextId(type)
    const components = getComponentCatalogue()

    if (!components[type]) {
      throw new Error(`Unknown component type: ${type}`)
    }

    // 核心：创建对应的 Renderable 实例
    return new components[type](rootContainerInstance.ctx, {
      id,
      ...props,
    })
  },

  // 添加子元素
  appendChild(parent: Instance, child: Instance) {
    parent.add(child)
  },

  // 移除子元素
  removeChild(parent: Instance, child: Instance) {
    parent.remove(child.id)
  },

  // 在指定位置插入子元素
  insertBefore(parent: Instance, child: Instance, beforeChild: Instance) {
    parent.insertBefore(child, beforeChild)
  },

  // 准备提交
  prepareForCommit(containerInfo: Container) {
    return null
  },

  // 提交完成后触发渲染
  resetAfterCommit(containerInfo: Container) {
    containerInfo.requestRender()
  },

  // 获取根容器上下文
  getRootHostContext(rootContainerInstance: Container) {
    return { isInsideText: false }
  },

  // 获取子容器上下文
  getChildHostContext(parentHostContext: HostContext, type: Type, rootContainerInstance: Container) {
    const isInsideText = ["text", ...textNodeKeys].includes(type)
    return { ...parentHostContext, isInsideText }
  },

  // 不设置文本内容（由 TextRenderable 处理）
  shouldSetTextContent(type: Type, props: Props) {
    return false
  },

  // 创建文本实例
  createTextInstance(text: string, rootContainerInstance: Container, hostContext: HostContext) {
    if (!hostContext.isInsideText) {
      throw new Error("Text must be created inside of a text node")
    }

    return TextNodeRenderable.fromString(text)
  },

  // 初始化属性
  finalizeInitialChildren(instance: Instance, type: Type, props: Props, rootContainerInstance: Container, hostContext: HostContext) {
    setInitialProperties(instance, type, props)
    return false
  },

  // 提交挂载
  commitMount(instance: Instance, type: Type, props: Props, internalInstanceHandle: any) {
    // 焦点处理在 setInitialProperties 中完成
  },

  // 提交更新
  commitUpdate(instance: Instance, type: Type, oldProps: Props, newProps: Props, internalInstanceHandle: any) {
    updateProperties(instance, type, oldProps, newProps)
    instance.requestRender()
  },

  // 提交文本更新
  commitTextUpdate(textInstance: TextInstance, oldText: string, newText: string) {
    textInstance.children = [newText]
    textInstance.requestRender()
  },

  // 隐藏/显示实例
  hideInstance(instance: Instance) {
    instance.visible = false
    instance.requestRender()
  },

  unhideInstance(instance: Instance, props: Props) {
    instance.visible = true
    instance.requestRender()
  },

  // 清空容器
  clearContainer(container: Container) {
    const children = container.getChildren()
    children.forEach((child) => container.remove(child.id))
  },

  // ... 其他配置
}

// packages/react/src/components/index.ts
import {
  ASCIIFontRenderable,
  BoxRenderable,
  CodeRenderable,
  DiffRenderable,
  InputRenderable,
  LineNumberRenderable,
  ScrollBoxRenderable,
  SelectRenderable,
  TabSelectRenderable,
  TextareaRenderable,
  TextRenderable,
} from "@opentui/core"
import {
  BoldSpanRenderable,
  ItalicSpanRenderable,
  LineBreakRenderable,
  LinkRenderable,
  SpanRenderable,
  UnderlineSpanRenderable,
} from "./text"

export const baseComponents = {
  // 布局组件
  box: BoxRenderable,
  text: TextRenderable,

  // 代码相关组件
  code: CodeRenderable,
  diff: DiffRenderable,
  "line-number": LineNumberRenderable,

  // 输入组件
  input: InputRenderable,
  select: SelectRenderable,
  textarea: TextareaRenderable,
  "tab-select": TabSelectRenderable,

  // 特殊组件
  scrollbox: ScrollBoxRenderable,
  "ascii-font": ASCIIFontRenderable,

  // 文本修饰符（必须在 text 内部使用）
  span: SpanRenderable,
  br: LineBreakRenderable,
  b: BoldSpanRenderable,
  strong: BoldSpanRenderable,
  i: ItalicSpanRenderable,
  em: ItalicSpanRenderable,
  u: UnderlineSpanRenderable,
  a: LinkRenderable,
}

type ComponentCatalogue = Record<string, RenderableConstructor>

export const componentCatalogue: ComponentCatalogue = { ...baseComponents }

// 扩展组件 API
export function extend<T extends ComponentCatalogue>(objects: T): void {
  Object.assign(componentCatalogue, objects)
}

export function getComponentCatalogue(): ComponentCatalogue {
  return componentCatalogue
}

// packages/react/src/types/host.ts
import type { BaseRenderable, RootRenderable, TextNodeRenderable } from "@opentui/core"
import { baseComponents } from "../components"

export type Type = keyof typeof baseComponents
export type Props = Record<string, any>
export type Container = RootRenderable
export type Instance = BaseRenderable
export type TextInstance = TextNodeRenderable
export type PublicInstance = Instance
export type HostContext = Record<string, any> & { isInsideText?: boolean }

reconciler.createContainer(root, ConcurrentRoot, ...)

reconciler.updateContainer(element, container, ...)

resetAfterCommit(containerInfo: Container) {
  containerInfo.requestRender()
}

// packages/core/src/Renderable.ts

const BrandedRenderable: unique symbol = Symbol.for("@opentui/core/Renderable")

export abstract class BaseRenderable extends EventEmitter {
  [BrandedRenderable] = true

  private static renderableNumber = 1
  protected _id: string
  public readonly num: number
  protected _dirty: boolean = false
  public parent: BaseRenderable | null = null
  protected _visible: boolean = true

  constructor(options: BaseRenderableOptions) {
    super()
    this.num = BaseRenderable.renderableNumber++
    this._id = options.id ?? `renderable-${this.num}`
  }

  public abstract add(obj: BaseRenderable | unknown, index?: number): number
  public abstract remove(id: string): void
  public abstract insertBefore(obj: BaseRenderable | unknown, anchor: BaseRenderable | unknown): void
  public abstract getChildren(): BaseRenderable[]
  public abstract getChildrenCount(): number
  public abstract getRenderable(id: string): BaseRenderable | undefined
  public abstract requestRender(): void
  public abstract findDescendantById(id: string): BaseRenderable | undefined
}

export abstract class Renderable extends BaseRenderable {
  static renderablesByNumber: Map<number, Renderable> = new Map()

  protected _isDestroyed: boolean = false
  protected _ctx: RenderContext
  protected _translateX: number = 0
  protected _translateY: number = 0
  protected _x: number = 0
  protected _y: number = 0
  protected _width: number | "auto" | `${number}%`
  protected _height: number | "auto" | `${number}%`
  protected _widthValue: number = 0
  protected _heightValue: number = 0
  private _zIndex: number
  public selectable: boolean = false
  protected buffered: boolean
  protected frameBuffer: OptimizedBuffer | null = null

  protected _focusable: boolean = false
  protected _focused: boolean = false
  protected keypressHandler: ((key: KeyEvent) => void) | null = null
  protected pasteHandler: ((event: PasteEvent) => void) | null = null

  private _live: boolean = false
  protected _liveCount: number = 0

  protected yogaNode: YogaNode
  protected _positionType: PositionTypeString = "relative"
  protected _overflow: OverflowString = "visible"
  protected _position: Position = {}
  protected _opacity: number = 1.0
  private _flexShrink: number = 1

  private renderableMapById: Map<string, Renderable> = new Map()
  protected _childrenInLayoutOrder: Renderable[] = []
  protected _childrenInZIndexOrder: Renderable[] = []
  private needsZIndexSort: boolean = false

  constructor(ctx: RenderContext, options: RenderableOptions<any>) {
    super(options)

    this._ctx = ctx
    Renderable.renderablesByNumber.set(this.num, this)

    // 初始化尺寸
    this._width = options.width ?? "auto"
    this._height = options.height ?? "auto"

    if (typeof this._width === "number") {
      this._widthValue = this._width
    }
    if (typeof this._height === "number") {
      this._heightValue = this._height
    }

    this._zIndex = options.zIndex ?? 0
    this._visible = options.visible !== false
    this.buffered = options.buffered ?? false
    this._live = options.live ?? false
    this._liveCount = this._live && this._visible ? 1 : 0
    this._opacity = options.opacity !== undefined ? Math.max(0, Math.min(1, options.opacity)) : 1.0

    // 创建 Yoga 节点
    this.yogaNode = Yoga.Node.create(yogaConfig)
    this.yogaNode.setDisplay(this._visible ? Display.Flex : Display.None)
    this.setupYogaProperties(options)
    this.applyEventOptions(options)

    if (this.buffered) {
      this.createFrameBuffer()
    }
  }

  // 添加子元素
  public add(obj: Renderable | VNode<any, any[]> | unknown, index?: number): number {
    if (!obj) {
      return -1
    }

    const renderable = maybeMakeRenderable(this._ctx, obj)
    if (!renderable) {
      return -1
    }

    if (renderable.isDestroyed) {
      return -1
    }

    const anchorRenderable = index !== undefined ? this._childrenInLayoutOrder[index] : undefined

    if (anchorRenderable) {
      return this.insertBefore(renderable, anchorRenderable)
    }

    if (renderable.parent === this) {
      this.yogaNode.removeChild(renderable.getLayoutNode())
      this._childrenInLayoutOrder.splice(this._childrenInLayoutOrder.indexOf(renderable), 1)
    } else {
      this.replaceParent(renderable)
      this.needsZIndexSort = true
      this.renderableMapById.set(renderable.id, renderable)
      this._childrenInZIndexOrder.push(renderable)
    }

    const childLayoutNode = renderable.getLayoutNode()
    const insertedIndex = this._childrenInLayoutOrder.length
    this._childrenInLayoutOrder.push(renderable)
    this.yogaNode.insertChild(childLayoutNode, insertedIndex)

    this.childrenPrimarySortDirty = true
    this._shouldUpdateBefore.add(renderable)

    this.requestRender()

    return insertedIndex
  }

  // 请求渲染
  public requestRender() {
    this.markDirty()
    this._ctx.requestRender()
  }

  // 渲染自身（子类重写）
  protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void {
    // 默认实现：不做任何渲染
    // 子类（如 TextRenderable、BoxRenderable）会重写此方法
  }

  // 完整渲染
  public render(buffer: OptimizedBuffer, deltaTime: number): void {
    let renderBuffer = buffer
    if (this.buffered && this.frameBuffer) {
      renderBuffer = this.frameBuffer
    }

    if (this.renderBefore) {
      this.renderBefore.call(this, renderBuffer, deltaTime)
    }

    this.renderSelf(renderBuffer, deltaTime)

    if (this.renderAfter) {
      this.renderAfter.call(this, renderBuffer, deltaTime)
    }

    this.markClean()
    this._ctx.addToHitGrid(this.x, this.y, this.width, this.height, this.num)

    // 如果使用离屏缓冲，复制到主缓冲
    if (this.buffered && this.frameBuffer) {
      buffer.drawFrameBuffer(this.x, this.y, this.frameBuffer)
    }
  }
}

// host-config.ts
appendChild(parent: Instance, child: Instance) {
  parent.add(child)
}

// Renderable.ts
public add(obj: Renderable | VNode | unknown, index?: number): number {
  const renderable = maybeMakeRenderable(this._ctx, obj)
  if (!renderable) return -1

  // 设置父子关系
  this.replaceParent(renderable)
  renderable.parent = this

  // 添加到 Yoga 布局树
  this.yogaNode.insertChild(renderable.getLayoutNode(), index)

  // 请求重新渲染
  this.requestRender()
  return index
}

<box alignItems="center" justifyContent="center">
  <text>Hello</text>
  <text>World</text>
</box>

// packages/core/src/Renderable.ts

const yogaConfig: Config = Yoga.Config.create()
yogaConfig.setUseWebDefaults(false)
yogaConfig.setPointScaleFactor(1)

private setupYogaProperties(options: RenderableOptions<Renderable>): void {
  const node = this.yogaNode

  // 基础尺寸
  if (isDimensionType(options.width)) {
    this._width = options.width
    this.yogaNode.setWidth(options.width)
  }
  if (isDimensionType(options.height)) {
    this._height = options.height
    this.yogaNode.setHeight(options.height)
  }

  // Flex 布局属性
  if (options.flexGrow !== undefined) {
    node.setFlexGrow(options.flexGrow)
  } else {
    node.setFlexGrow(0)
  }

  if (options.flexShrink !== undefined) {
    this._flexShrink = options.flexShrink
    node.setFlexShrink(options.flexShrink)
  }

  // 布局方向
  node.setFlexDirection(parseFlexDirection(options.flexDirection))
  node.setFlexWrap(parseWrap(options.flexWrap))

  // 对齐方式
  node.setAlignItems(parseAlignItems(options.alignItems))
  node.setJustifyContent(parseJustify(options.justifyContent))
  node.setAlignSelf(parseAlign(options.alignSelf))

  // 位置
  this._positionType = options.position === "absolute" ? "absolute" : "relative"
  if (this._positionType !== "relative") {
    node.setPositionType(parsePositionType(this._positionType))
  }

  // 溢出处理
  this._overflow = options.overflow === "hidden" ? "hidden" : options.overflow === "scroll" ? "scroll" : "visible"
  if (this._overflow !== "visible") {
    node.setOverflow(parseOverflow(this._overflow))
  }

  // 间距
  this.setupMarginAndPadding(options)
}

private setupMarginAndPadding(options: RenderableOptions<Renderable>): void {
  const node = this.yogaNode

  // Margin
  if (isMarginType(options.margin)) {
    node.setMargin(Edge.Top, options.margin)
    node.setMargin(Edge.Right, options.margin)
    node.setMargin(Edge.Bottom, options.margin)
    node.setMargin(Edge.Left, options.margin)
  }

  // Padding
  if (isPaddingType(options.padding)) {
    node.setPadding(Edge.Top, options.padding)
    node.setPadding(Edge.Right, options.padding)
    node.setPadding(Edge.Bottom, options.padding)
    node.setPadding(Edge.Left, options.padding)
  }
}

// packages/core/src/Renderable.ts

public calculateLayout(): void {
  this.yogaNode.calculateLayout(this.width, this.height, Direction.LTR)
  this.emit(LayoutEvents.LAYOUT_CHANGED)
}

public updateFromLayout(): void {
  const layout = this.yogaNode.getComputedLayout()

  const oldX = this._x
  const oldY = this._y

  // 从 Yoga 获取计算后的布局
  this._x = layout.left
  this._y = layout.top

  const newWidth = Math.max(layout.width, 1)
  const newHeight = Math.max(layout.height, 1)
  const sizeChanged = this.width !== newWidth || this.height !== newHeight

  this._widthValue = newWidth
  this._heightValue = newHeight

  if (sizeChanged) {
    this.onLayoutResize(newWidth, newHeight)
  }

  if (oldX !== this._x || oldY !== this._y) {
    if (this.parent) this.parent.childrenPrimarySortDirty = true
  }
}

protected onLayoutResize(width: number, height: number): void {
  if (this._visible) {
    this.handleFrameBufferResize(width, height)
    this.onResize(width, height)
    this.requestRender()
  }
}

public updateLayout(deltaTime: number, renderList: RenderCommand[] = []): void {
  if (!this.visible) return

  this.onUpdate(deltaTime)
  if (this._isDestroyed) return

  // 更新布局
  this.updateFromLayout()

  // 更新需要先更新的子元素
  if (this._shouldUpdateBefore.size > 0) {
    for (const child of this._shouldUpdateBefore) {
      if (!child.isDestroyed) {
        child.updateFromLayout()
      }
    }
    this._shouldUpdateBefore.clear()
  }

  // 推送透明度
  const shouldPushOpacity = this._opacity < 1.0
  if (shouldPushOpacity) {
    renderList.push({ action: "pushOpacity", opacity: this._opacity })
  }

  renderList.push({ action: "render", renderable: this })

  // 排序
  this.ensureZIndexSorted()

  // 裁剪区域
  const shouldPushScissor = this._overflow !== "visible" && this.width > 0 && this.height > 0
  if (shouldPushScissor) {
    const scissorRect = this.getScissorRect()
    renderList.push({
      action: "pushScissorRect",
      x: scissorRect.x,
      y: scissorRect.y,
      width: scissorRect.width,
      height: scissorRect.height,
      screenX: this.x,
      screenY: this.y,
    })
  }

  // 递归处理子元素
  const visibleChildren = this._getVisibleChildren()
  for (const child of this._childrenInZIndexOrder) {
    if (!visibleChildren.includes(child.num)) {
      child.updateFromLayout()
      continue
    }
    child.updateLayout(deltaTime, renderList)
  }

  // 弹出裁剪和透明度
  if (shouldPushScissor) {
    renderList.push({ action: "popScissorRect" })
  }
  if (shouldPushOpacity) {
    renderList.push({ action: "popOpacity" })
  }
}

// packages/core/src/buffer.ts

export class OptimizedBuffer {
  private static fbIdCounter = 0
  public id: string
  public lib: RenderLib
  private bufferPtr: Pointer
  private _width: number
  private _height: number
  private _widthMethod: WidthMethod
  public respectAlpha: boolean = false
  private _rawBuffers: {
    char: Uint32Array // 字符缓冲区（Unicode 码点）
    fg: Float32Array // 前景色 (R, G, B, A)
    bg: Float32Array // 背景色 (R, G, B, A)
    attributes: Uint32Array // 属性位（粗体、下划线等）
  } | null = null
  private _destroyed: boolean = false

  constructor(
    lib: RenderLib,
    ptr: Pointer,
    width: number,
    height: number,
    options: { respectAlpha?: boolean; id?: string; widthMethod?: WidthMethod },
  ) {
    this.id = options.id || `fb_${OptimizedBuffer.fbIdCounter++}`
    this.lib = lib
    this.respectAlpha = options.respectAlpha || false
    this._width = width
    this._height = height
    this._widthMethod = options.widthMethod || "unicode"
    this.bufferPtr = ptr
  }

  static create(
    width: number,
    height: number,
    widthMethod: WidthMethod,
    options: { respectAlpha?: boolean; id?: string } = {},
  ): OptimizedBuffer {
    const lib = resolveRenderLib()
    const buffer = lib.createOptimizedBuffer(width, height, widthMethod, options.respectAlpha || false, options.id)
    return buffer
  }

  // 绘制文本
  public drawText(
    text: string,
    x: number,
    y: number,
    fg: RGBA,
    bg?: RGBA,
    attributes: number = 0,
    selection?: { start: number; end: number; bgColor?: RGBA; fgColor?: RGBA } | null,
  ): void {
    if (!selection) {
      this.lib.bufferDrawText(this.bufferPtr, text, x, y, fg, bg, attributes)
      return
    }

    // 处理选中状态
    const { start, end } = selection
    // ... 分段绘制
  }

  // 绘制边框
  public drawBox(options: {
    x: number
    y: number
    width: number
    height: number
    borderStyle?: BorderStyle
    customBorderChars?: Uint32Array
    border: boolean | BorderSides[]
    borderColor: RGBA
    backgroundColor: RGBA
    shouldFill?: boolean
    title?: string
    titleAlignment?: "left" | "center" | "right"
  }): void {
    const style = options.borderStyle || "single"
    const borderChars: Uint32Array = options.customBorderChars ?? BorderCharArrays[style]
    const packedOptions = packDrawOptions(options.border, options.shouldFill ?? false, options.titleAlignment || "left")

    this.lib.bufferDrawBox(
      this.bufferPtr,
      options.x,
      options.y,
      options.width,
      options.height,
      borderChars,
      packedOptions,
      options.borderColor,
      options.backgroundColor,
      options.title ?? null,
    )
  }

  // 填充矩形
  public fillRect(x: number, y: number, width: number, height: number, bg: RGBA): void {
    this.lib.bufferFillRect(this.bufferPtr, x, y, width, height, bg)
  }

  // 获取最终输出字节
  public getRealCharBytes(addLineBreaks: boolean = false): Uint8Array {
    const realSize = this.lib.bufferGetRealCharSize(this.bufferPtr)
    const outputBuffer = new Uint8Array(realSize)
    const bytesWritten = this.lib.bufferWriteResolvedChars(this.bufferPtr, outputBuffer, addLineBreaks)
    return outputBuffer.slice(0, bytesWritten)
  }

  // 裁剪区域管理
  public pushScissorRect(x: number, y: number, width: number, height: number): void {
    this.lib.bufferPushScissorRect(this.bufferPtr, x, y, width, height)
  }

  public popScissorRect(): void {
    this.lib.bufferPopScissorRect(this.bufferPtr)
  }

  // 透明度管理
  public pushOpacity(opacity: number): void {
    this.lib.bufferPushOpacity(this.bufferPtr, Math.max(0, Math.min(1, opacity)))
  }

  public popOpacity(): void {
    this.lib.bufferPopOpacity(this.bufferPtr)
  }

  // 清空缓冲区
  public clear(bg: RGBA = RGBA.fromValues(0, 0, 0, 1)): void {
    this.lib.bufferClear(this.bufferPtr, bg)
  }
}

// packages/core/src/lib/RGBA.ts

export class RGBA {
  public readonly r: number
  public readonly g: number
  public readonly b: number
  public readonly a: number

  static fromValues(r: number, g: number, b: number, a: number = 1): RGBA
  static fromHex(hex: string): RGBA // "#RRGGBB" 或 "#RRGGBBAA"
  static fromInts(r: number, g: number, b: number, a: number = 255): RGBA
  // ...
}

// 伪代码示例
protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void {
  buffer.drawText(
    this.content,
    this.x,
    this.y,
    this.fg,
    this.bg,
    this.attributes
  )
}

// 伪代码示例
protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void {
  // 绘制背景
  if (this.backgroundColor) {
    buffer.fillRect(this.x, this.y, this.width, this.height, this.backgroundColor)
  }

  // 绘制边框
  if (this.border) {
    buffer.drawBox({
      x: this.x,
      y: this.y,
      width: this.width,
      height: this.height,
      border: this.border,
      borderStyle: this.borderStyle,
      borderColor: this.borderColor,
      backgroundColor: this.backgroundColor,
      shouldFill: this.shouldFill,
      title: this.title,
      titleAlignment: this.titleAlignment,
    })
  }
}

// packages/core/src/Renderable.ts

export class RootRenderable extends Renderable {
  private renderList: RenderCommand[] = []

  public render(buffer: OptimizedBuffer, deltaTime: number): void {
    if (!this.visible) return

    // 0. 运行生命周期回调
    for (const renderable of this._ctx.getLifecyclePasses()) {
      renderable.onLifecyclePass?.call(renderable)
    }

    // 1. 从根节点计算布局
    if (this.yogaNode.isDirty()) {
      this.calculateLayout()
    }

    // 2. 更新整个树的布局并收集渲染命令
    this.renderList.length = 0
    this.updateLayout(deltaTime, this.renderList)

    // 3. 执行所有渲染命令
    this._ctx.clearHitGridScissorRects()
    for (let i = 1; i < this.renderList.length; i++) {
      const command = this.renderList[i]
      switch (command.action) {
        case "render":
          if (!command.renderable.isDestroyed) {
            command.renderable.render(buffer, deltaTime)
          }
          break
        case "pushScissorRect":
          buffer.pushScissorRect(command.x, command.y, command.width, command.height)
          this._ctx.pushHitGridScissorRect(command.screenX, command.screenY, command.width, command.height)
          break
        case "popScissorRect":
          buffer.popScissorRect()
          this._ctx.popHitGridScissorRect()
          break
        case "pushOpacity":
          buffer.pushOpacity(command.opacity)
          break
        case "popOpacity":
          buffer.popOpacity()
          break
      }
    }
  }

  protected propagateLiveCount(delta: number): void {
    const oldCount = this._liveCount
    this._liveCount += delta

    if (oldCount === 0 && this._liveCount > 0) {
      this._ctx.requestLive()
    } else if (oldCount > 0 && this._liveCount === 0) {
      this._ctx.dropLive()
    }
  }
}

// packages/core/src/Renderable.ts

interface RenderCommandBase {
  action: "render" | "pushScissorRect" | "popScissorRect" | "pushOpacity" | "popOpacity"
}

interface RenderCommandPushScissorRect extends RenderCommandBase {
  action: "pushScissorRect"
  x: number
  y: number
  width: number
  height: number
  screenX: number
  screenY: number
}

interface RenderCommandRender extends RenderCommandBase {
  action: "render"
  renderable: Renderable
}

interface RenderCommandPushOpacity extends RenderCommandBase {
  action: "pushOpacity"
  opacity: number
}

export type RenderCommand =
  | RenderCommandPushScissorRect
  | RenderCommandPopScissorRect
  | RenderCommandRender
  | RenderCommandPushOpacity
  | RenderCommandPopOpacity

// packages/core/src/renderer.ts

export class CliRenderer extends EventEmitter implements RenderContext {
  private renderTimeout: Timer | null = null
  private lastTime: number = 0

  private async loop(): Promise<void> {
    if (this.rendering || this._isDestroyed) return
    this.renderTimeout = null

    this.rendering = true
    try {
      const now = Date.now()
      const elapsed = now - this.lastTime
      const deltaTime = elapsed
      this.lastTime = now

      // 1. 执行动画回调
      const frameRequests = Array.from(this.animationRequest.values())
      this.animationRequest.clear()
      for (const callback of frameRequests) {
        callback(deltaTime)
        this.dropLive()
      }

      // 2. 执行帧回调
      for (const frameCallback of this.frameCallbacks) {
        try {
          await frameCallback(deltaTime)
        } catch (error) {
          console.error("Error in frame callback:", error)
        }
      }

      // 3. 渲染整个组件树
      this.root.render(this.nextRenderBuffer, deltaTime)

      // 4. 后处理
      for (const postProcessFn of this.postProcessFns) {
        postProcessFn(this.nextRenderBuffer, deltaTime)
      }

      // 5. 控制台渲染
      this._console.renderToBuffer(this.nextRenderBuffer)

      // 6. 原生渲染（写入终端）
      if (!this._isDestroyed) {
        this.renderNative()

        // 调度下一帧
        if (this._isRunning || this.immediateRerenderRequested) {
          const targetFrameTime = this.immediateRerenderRequested ? this.minTargetFrameTime : this.targetFrameTime
          const delay = Math.max(1, targetFrameTime - Math.floor(performance.now() - now))
          this.immediateRerenderRequested = false
          this.renderTimeout = setTimeout(() => {
            this.renderTimeout = null
            this.loop()
          }, delay)
        }
      }
    } finally {
      this.rendering = false
      if (this._destroyPending) {
        this.finalizeDestroy()
      }
      this.resolveIdleIfNeeded()
    }
  }

  private renderNative(): void {
    if (this.renderingNative) {
      throw new Error("Rendering called concurrently")
    }

    this.renderingNative = true
    // 调用 Zig 层的 render 函数
    this.lib.render(this.rendererPtr, force)
    this.renderingNative = false
  }
}

// packages/core/src/zig/renderer.zig (伪代码)

pub fn render(renderer: *Renderer, force: bool) void {
  // 1. 获取当前和下一个缓冲区
  const nextBuffer = renderer.getNextBuffer()
  const currentBuffer = renderer.getCurrentBuffer()

  // 2. 计算差异（增量渲染优化）
  const diff = calculateDiff(currentBuffer, nextBuffer)

  // 3. 生成 ANSI 输出
  var output = std.ArrayList(u8).init(allocator)
  defer output.deinit()

  var lastX: usize = 0
  var lastY: usize = 0

  for (diff.items) |cell| {
    // 如果位置变化，移动光标
    if (cell.x != lastX or cell.y != lastY) {
      output.appendSlice(ANSI.moveCursor(cell.y + 1, cell.x + 1))  // ANSI 位置是 1 基址
      lastX = cell.x
      lastY = cell.y
    }

    // 如果前景色变化，设置前景色
    if (cell.fgChanged) {
      output.appendSlice(ANSI.setForeground(cell.fg))
    }

    // 如果背景色变化，设置背景色
    if (cell.bgChanged) {
      output.appendSlice(ANSI.setBackground(cell.bg))
    }

    // 如果属性变化，设置属性
    if (cell.attrsChanged) {
      output.appendSlice(ANSI.setAttributes(cell.attrs))
    }

    // 写入字符
    output.appendSlice(cell.charBytes)
  }

  // 4. 重置属性
  output.appendSlice(ANSI.reset)

  // 5. 写入 stdout
  stdout.writeAll(output.items)

  // 6. 交换缓冲区
  renderer.swapBuffers()
}

// packages/core/src/ansi.ts

export const ANSI = {
  // 重置
  reset: "\x1b[0m",

  // 光标移动
  moveCursor: (row: number, col: number) => `\x1b[${row};${col}H`,
  moveCursorUp: (n: number) => `\x1b[${n}A`,
  moveCursorDown: (n: number) => `\x1b[${n}B`,
  moveCursorRight: (n: number) => `\x1b[${n}C`,
  moveCursorLeft: (n: number) => `\x1b[${n}D`,
  cursorToHome: () => "\x1b[H",

  // 清除
  clearScreen: () => "\x1b[2J",
  clearLine: () => "\x1b[2K",
  clearToLineEnd: () => "\x1b[0K",
  clearToLineStart: () => "\x1b[1K",

  // 滚动
  scrollUp: (n: number) => `\x1b[${n}S`,
  scrollDown: (n: number) => `\x1b[${n}T`,

  // 前景色 (3/4 bit)
  black: "\x1b[30m",
  red: "\x1b[31m",
  green: "\x1b[32m",
  yellow: "\x1b[33m",
  blue: "\x1b[34m",
  magenta: "\x1b[35m",
  cyan: "\x1b[36m",
  white: "\x1b[37m",

  // 背景色 (3/4 bit)
  bgBlack: "\x1b[40m",
  bgRed: "\x1b[41m",
  // ...

  // 前景色 (8 bit / 24 bit)
  setForeground: (r: number, g: number, b: number) => `\x1b[38;2;${r};${g};${b}m`,
  setBackground: (r: number, g: number, b: number) => `\x1b[48;2;${r};${g};${b}m`,

  // 文本属性
  bold: "\x1b[1m",
  dim: "\x1b[2m",
  italic: "\x1b[3m",
  underline: "\x1b[4m",
  blink: "\x1b[5m",
  reverse: "\x1b[7m",
  hidden: "\x1b[8m",

  // 隐藏/显示光标
  hideCursor: () => "\x1b[?25l",
  showCursor: () => "\x1b[?25h",
}

// index.tsx
import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return (
    <box alignItems="center" justifyContent="center" width={40} height={10} border>
      <text>Hello World</text>
    </box>
  )
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

// 编译后的代码
React.createElement(
  "box",
  { alignItems: "center", justifyContent: "center", width: 40, height: 10, border: true },
  React.createElement("text", null, "Hello World"),
)

createRoot(renderer).render(<App />)
// 内部执行：
// 1. 创建 React Element
// 2. 调用 _render(element, renderer.root)

// hostConfig.createInstance("box", {...})
const boxInstance = new BoxRenderable(renderer.root.ctx, {
  id: "box-1",
  alignItems: "center",
  justifyContent: "center",
  width: 40,
  height: 10,
  border: true,
})

// hostConfig.createInstance("text", {})
const textInstance = new TextRenderable(renderer.root.ctx, {
  id: "text-1",
  content: "Hello World",
})

// hostConfig.appendChild(boxInstance, textInstance)
boxInstance.add(textInstance)

# 生成的 ANSI 序列（简化）
\x1b[0;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m┌────────────────────────────────────────┐\x1b[0m
\x1b[1;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[2;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[3;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[4;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│              Hello World               │\x1b[0m
\x1b[5;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[6;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[7;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[8;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m│                                        │\x1b[0m
\x1b[9;0H                    \x1b[48;2;0;0;0m\x1b[38;2;255;255;255m└────────────────────────────────────────┘\x1b[0m