Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/reference/native-span-feed.mdx

View on GitHub
---
title: NativeSpanFeed
description: Low-level native-to-JavaScript byte transport used for custom renderer output
order: 6
skill:
  intents: [native-span-feed, custom-stdout, output-transport, backpressure]
---

# NativeSpanFeed

`NativeSpanFeed` is a zero-copy wrapper around a native Zig byte feed. `CliRenderer` uses it internally to deliver native frame bytes to a custom `stdout` while respecting asynchronous `Writable` callbacks.

Most applications should not create a feed directly. Pass streams to [`createCliRenderer()`](/docs/core-concepts/renderer#custom-streams) instead:

```typescript
const renderer = await createCliRenderer({
  stdin,
  stdout,
  width: cols,
  height: rows,
  exitOnCtrlC: false,
  exitSignals: [],
})
```

When `stdout` is not `process.stdout` and `bufferedOutput` is not `"memory"`, the renderer creates the feed, forwards each borrowed byte view to the original `stdout.write`, and keeps the native chunk pinned until the write callback runs. The renderer also drains and closes the feed during destruction.

## Low-level use

Direct use is intended for native integrations that already produce data through a native span-feed pointer. `NativeSpanFeed` is not a Node stream and does not expose `read()`, `write()`, or `pipe()`.

```typescript
import { NativeSpanFeed } from "@opentui/core"

const feed = NativeSpanFeed.create({
  chunkSize: 64 * 1024,
  initialChunks: 2,
})

const chunks: Uint8Array[] = []
const offData = feed.onData((bytes) => {
  // Copy data that must outlive this synchronous handler.
  chunks.push(bytes.slice())
})

try {
  // A native producer that accepts NativeSpanFeed uses feed.streamPtr.
  await feed.idle()
} finally {
  offData()
  feed.close()
}
```

The wrapper owns the attached feed after `create()` or `attach()` succeeds. Calling `close()` unregisters the callback and destroys the native feed. Do not use `streamPtr` or previously received views afterward.

## Public API

```typescript
type DataHandler = (data: Uint8Array) => void | Promise<void>

class NativeSpanFeed {
  static create(options?: NativeSpanFeedOptions): NativeSpanFeed
  static attach(streamPtr: Pointer, options?: NativeSpanFeedOptions): NativeSpanFeed

  readonly streamPtr: Pointer

  onData(handler: DataHandler): () => void
  onError(handler: (code: number) => void): () => void
  isBackpressured(): boolean
  drainAll(): void
  idle(): Promise<void>
  close(): void
}
```

`attach()` wraps an existing native feed pointer and registers the JavaScript callback. Its current `options` parameter is accepted but not applied; configure the native feed when it is created.

`onData()` and `onError()` return unsubscribe functions. If committed data arrives before a data handler exists, the feed marks it pending and drains it when the first handler is added.

`drainAll()` synchronously drains all currently queued spans in batches. Data-available callbacks normally invoke it automatically when handlers are registered.

## Options

```typescript
type GrowthPolicy = "grow" | "block"

type NativeSpanFeedOptions = {
  chunkSize?: number
  initialChunks?: number
  maxBytes?: bigint
  growthPolicy?: GrowthPolicy
  autoCommitOnFull?: boolean
  spanQueueCapacity?: number
}
```

| Option              | Default     | Description                                                                                           |
| ------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `chunkSize`         | `64 * 1024` | Bytes allocated for each native chunk                                                                 |
| `initialChunks`     | `2`         | Chunks allocated at creation                                                                          |
| `maxBytes`          | `0n`        | Allocation cap; `0n` means no cap                                                                     |
| `growthPolicy`      | `"grow"`    | Add capacity when all available chunks or span slots are occupied; `"block"` reports no space instead |
| `autoCommitOnFull`  | `true`      | Let the native producer commit a chunk automatically when it fills                                    |
| `spanQueueCapacity` | `0`         | Native default sentinel, normalized to `4096` span entries                                            |

An explicit `chunkSize: 0` normalizes to 64 KiB. An explicit `initialChunks: 0` normalizes to one chunk. An explicit `spanQueueCapacity: 0` selects the native capacity of 4096.

## Borrowed data and backpressure

Each `onData` argument is a `Uint8Array` view into native chunk memory, not an owned copy.

- A synchronous handler must copy the bytes if it retains them after returning.
- If a handler returns a promise, the chunk remains pinned until all promises returned for that span settle.
- Promise rejection still releases the native chunk; it is not delivered to `onError` by this wrapper.
- `isBackpressured()` is true while async handlers are pending, committed data is waiting for a handler, or native chunks remain pinned.
- `idle()` resolves when no callback or drain is active, no async handlers or pending data remain, and no chunks are pinned.
- `close()` is idempotent after destruction. If called during a callback, drain, or async handler, final destruction is deferred until that work settles.

Renderer-managed custom output uses these rules to turn the `stdout.write(..., callback)` lifetime into feed backpressure. During `renderer.destroy()`, OpenTUI drains existing frames, destroys the native renderer so it can commit shutdown bytes, drains those bytes, detaches handlers, and closes the feed. If an application immediately destroys its underlying transport after `renderer.destroy()`, allow a microtask for pending asynchronous write callbacks to finish.

## Stats type

`@opentui/core` exports the native data shape:

```typescript
type NativeSpanFeedStats = {
  bytesWritten: bigint
  spansCommitted: bigint
  chunks: number
  pendingSpans: number
}
```

`NativeSpanFeed` itself has no public stats method. Do not call a nonexistent `feed.getStats()` or `feed.stats` property.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall