opentui-core-skilld

name	opentui-core-skilld
description	ALWAYS use when writing code importing "@opentui/core". Consult for debugging, best practices, or modifying @opentui/core, opentui/core, opentui core, opentui.
metadata	{"version":"0.4.3","generated_by":"Anthropic · Haiku 4.5","generated_at":"2026-07-06T00:00:00.000Z"}

anomalyco/opentui @opentui/core@0.4.3

Tags: latest: 0.4.3, snapshot: 0.0.0-20260705-2dee9667

References: package.json • README • Docs • Issues • Releases

Search

Use skilld search "query" -p @opentui/core instead of grepping .skilld/ directories. Run skilld search --guide -p @opentui/core for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes — prioritise recent major/minor releases.

• NEW: NativeSpanFeed — v0.3.0 introduced routing of renderer output through NativeSpanFeed for custom stdout handling, allowing custom output streams and handlers source

• NEW: DiffRenderable.getHunkRowOffsets() — v0.3.2 added this method for hunk navigation in diff renderables source

• NEW: Code block renderer helper — v0.3.2 introduced markdown code block rendering helper for custom code block styling source

• NEW: box.titleColor prop — v0.3.3 added custom title colour property for box components, allowing separate styling from border colour source

• NEW: @opentui/ssh package — v0.4.1 introduced new package for SSH terminal integration support source

• NEW: Native yoga-layout — v0.4.1 switched to native yoga-layout integration for improved performance and layout correctness source

• NEW: Clipboard OSC 52 support — v0.4.2 added terminal clipboard access via OSC 52 sequence with automatic protocol detection source

• NEW: Render backpressure handling — v0.4.1 added native render backpressure and failure handling for threaded rendering source

• NEW: Node.js 26 support — v0.4.0 extended platform support to Node.js 26 alongside Bun source

Also changed: InputRenderable.minLength new v0.2.16 · QRCode component new v0.2.15 · renderer.split-footer replay reset new v0.3.1 · Text-buffer style preservation on listener failure improved v0.4.0 · Link retirement after generation exhaustion v0.4.0 · Scroll position and selection fixes v0.4.2

Best Practices

• Always use createCliRenderer() to initialize the renderer instead of directly instantiating CliRenderer, which automatically handles terminal setup, capability detection, and proper stream configuration source

• Enable live mode on renderables that require continuous updates or respond to real-time events — omitting it prevents unnecessary frame scheduling and improves performance when components are static source

• Use scrollViewportCulling in ScrollBoxRenderable to automatically hide children outside the viewport, dramatically improving performance with large scrollable lists without manual visibility management source

• Prefer BoxRenderable with Yoga flex layout over manual positioning — it handles responsive layouts, automatic spacing, and child constraints without the complexity of manual coordinate management source

• Route renderer output through NativeSpanFeed when implementing custom stdout pipelines — zero-copy architecture and backpressure handling prevent buffering issues in high-throughput scenarios source

• Use TestRecorder for behaviour-driven testing of TUI components — captures frame sequences during interactions, enabling assertions on visual state across render cycles source

• Set OPENTUI_FORCE_EXPLICIT_WIDTH=false if your terminal doesn't support OSC 66 (GNOME Terminal, older Konsole/xterm) before creating the renderer to avoid character width detection artifacts source

• Use buffered: true on renderables with expensive render operations or complex nested children — frameBuffer caching defers full re-renders until the renderable is marked dirty source

• Implement focus management with focusable and focus() methods rather than relying on tab order alone — manually routing focus enables complex interactions like modals and focus traps source

• Use renderBefore() and renderAfter() callbacks for post-processing effects and overlays on specific renderables without creating full wrapper components source

• Always call createTestRenderer() instead of CliRenderer in tests to use the in-memory renderer with mock input/output — allows synchronous testing and frame capture without terminal I/O source

• Compose interactive renderables by registering onMouseDown, onMouseMove, and onMouseDragEnd handlers separately instead of a catch-all onMouse handler — improves event routing clarity and allows different handlers to coexist source

• Use TextRenderable with StyledText for rich text rendering rather than plain strings — enables per-span colors, attributes, and composition without custom buffer management source

• Detect terminal capabilities before rendering heavy components by checking TerminalCapabilities (e.g., kitty_graphics, sixel) — avoids rendering unsupported features that degrade gracefully but waste CPU source