Skip to content

feat(core): add embedded terminal renderable - #1340

Draft
jlongster wants to merge 4 commits into
embedded-terminal-runtimefrom
embedded-terminal-renderable
Draft

feat(core): add embedded terminal renderable#1340
jlongster wants to merge 4 commits into
embedded-terminal-runtimefrom
embedded-terminal-renderable

Conversation

@jlongster

@jlongster jlongster commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Problem

The runtime layer in #1338 owns Ghostty terminal state and input semantics, but it cannot render into OpenTUI or participate in layout, focus, cursor, mouse, and portable TypeScript FFI. The previous renderable PR (#1308) proved this behavior against a dynamic C loader and an older OpenTUI native surface.

This PR ports that user-facing layer onto the pinned Ghostty Zig module and current OpenTUI handle/Node/Bun architecture.

Changes

  • Translate Ghostty RenderState dirty rows, colors, styles, graphemes, wide cells, and cursor state directly into OptimizedBuffer.
  • Preserve Ghostty’s authoritative terminal-cell widths through a native drawGrapheme operation.
  • Recover from partial render-state allocation failures by discarding incomplete retained state and forcing a rebuild.
  • Add kind-11 embedded-terminal handles with stale, wrong-kind, and idempotent-destroy coverage.
  • Export a fixed-width native ABI for lifecycle, composition, cursor, scrolling, input encoding, and PTY responses.
  • Keep exported symbols available on unsupported custom targets while returning an explicit unsupported status.
  • Add portable Bun/Node FFI with direct borrowed typed-array arguments, bounds validation, and required-size key output retry.
  • Add EmbeddedTerminalRenderable with focus, Kitty releases, paste, mouse forwarding, scrollback fallback, resize propagation, hardware cursor ownership, and cleanup.
  • Use Ghostty’s W3C physical-key mapping instead of copied enum numbers.
  • Suppress SGR-pixel reports because OpenTUI currently has terminal-cell rather than physical-pixel coordinates.

Scope

This is the second layer of native GitHub Stack #1341 and targets #1338. It excludes PTY/process ownership, screen snapshots/change notifications, benchmarks, examples, selection/search, and child-terminal graphics.

Testing

  • Focused native embedded-terminal suite (10 passed)
  • Focused Bun renderable and native-handle suites (18 passed)
  • Full native suite (1878 passed, 6 skipped)
  • Embedded-terminal Node suite (8 passed)
  • Packed Node/Bun distribution smoke passed
  • Unsupported x86_64-freebsd custom-target build passed
  • bun run fmt:check
  • bun run lint

The full Node lane reached one unrelated ALSA audio-device failure after all embedded-terminal tests passed. The full Bun lane reached the embedded-terminal tests successfully before an unrelated Bun runtime crash in the existing diff suite.

@jlongster
jlongster force-pushed the embedded-terminal-renderable branch 2 times, most recently from 66dd0de to 15a31ab Compare August 5, 2026 20:22
@jlongster
jlongster force-pushed the embedded-terminal-renderable branch from 15a31ab to 69878ca Compare August 5, 2026 20:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant