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/plugins/core.mdx

View on GitHub
---
title: Core
description: Framework-free slot hosting with BaseRenderable nodes
order: 2
---

# Core slots

This page shows the core host API for plugin slots.

Use slots when you want external modules to render `BaseRenderable` UI in host-defined layout regions without forking the app. The host keeps control of layout and slot typing; plugins only render through the APIs you expose.

If you have not read the shared model yet, start with [Plugin Slots](/docs/plugins/slots).

## What core adds

On top of `createSlotRegistry`, core provides:

- `createCoreSlotRegistry` — create a registry typed for `BaseRenderable` nodes
- `registerCorePlugin` — register a plugin using the core-specific `CorePlugin` interface
- `SlotRenderable` — a `Renderable` that mounts a slot into the renderable tree
- `resolveCoreSlot` — resolve slot entries without mounting
- `@opentui/core/runtime-plugin-support` / `createRuntimePlugin` — runtime module support for external plugin/module loading in Bun

Core slot renderers receive both the host context and slot data: `(ctx, data) => BaseRenderable`.

`createCoreSlotRegistry` accepts the same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.

## Runtime-loaded external plugins

If your app loads plugin modules from disk at runtime, import this once in your app entry:

```ts
import "@opentui/core/runtime-plugin-support"
```

This installs Bun runtime support for `@opentui/core` plus default core runtime entrypoints (`@opentui/core/testing`). Add first-party package runtime modules explicitly when a plugin imports them.

If you need additional host-resolved modules, configure runtime support before the side-effect import is loaded:

```ts
const { ensureRuntimePluginSupport } = await import("@opentui/core/runtime-plugin-support/configure")

ensureRuntimePluginSupport({
  additional: {
    "my-runtime-module": { marker: "ok" },
  },
})
```

For plugins that import `@opentui/three`, install `@opentui/three` in the host app and pass its runtime module map:

```ts
import { runtimeModules as threeRuntimeModules } from "@opentui/three/runtime-modules"
import { ensureRuntimePluginSupport } from "@opentui/core/runtime-plugin-support/configure"

ensureRuntimePluginSupport({
  additional: threeRuntimeModules,
})
```

The side-effect import and configurable entrypoint install the same runtime plugin. Late additions throw with a clear error instead of being ignored.

## `CorePlugin` interface

| Field     | Type                                              | Required | Description                                                                                |
| --------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `id`      | `string`                                          | yes      | Unique identifier. Duplicate ids throw.                                                    |
| `order`   | `number`                                          | no       | Sort priority (ascending). Defaults to `0`.                                                |
| `setup`   | `(ctx, renderer) => void`                         | no       | Called once at registration time. If it throws, the plugin is not registered.              |
| `dispose` | `() => void`                                      | no       | Called when the plugin is unregistered or the registry is cleared.                         |
| `slots`   | `Partial<Record<SlotName, CoreSlotContribution>>` | yes      | Each value is a renderer function or a [managed slot object](#managed-slot-contributions). |

A `CoreSlotContribution` is either a plain renderer `(ctx, data) => BaseRenderable` or a `CoreManagedSlot` with lifecycle hooks.

## Basic usage

A `SlotRenderable` extends `Renderable`, so it can be added to any parent like a `BoxRenderable`. It resolves plugins from the registry, manages their lifecycle, and reconciles their output as its children.

```typescript
import {
  BoxRenderable,
  createCliRenderer,
  createCoreSlotRegistry,
  registerCorePlugin,
  SlotRenderable,
  TextRenderable,
} from "@opentui/core"

type Slots = "statusbar"
type SlotData = { label: string }
const context = { appName: "core-app", version: "1.0.0" }

const renderer = await createCliRenderer()

const registry = createCoreSlotRegistry<Slots, typeof context, SlotData>(renderer, context)

const unregister = registerCorePlugin(registry, {
  id: "clock-plugin",
  order: 0,
  slots: {
    statusbar(_ctx, data) {
      return new TextRenderable(renderer, {
        id: "clock-status",
        content: `clock: ${data.label}`,
      })
    },
  },
})

const slot = new SlotRenderable(renderer, {
  id: "statusbar-slot",
  registry,
  name: "statusbar",
  data: { label: "ok" },
  mode: "append",
  width: "100%",
  height: 3,
  flexDirection: "row",
  fallback: () =>
    new TextRenderable(renderer, {
      id: "statusbar-fallback",
      content: "fallback",
    }),
})

renderer.root.add(slot)

// later
slot.mode = "replace"
slot.data = { label: "updated" }
slot.refresh()
slot.destroy()
```

`registerCorePlugin` returns an unregister function (`() => void`). Calling it removes the plugin and invokes its `dispose` hook.

Because `SlotRenderable` extends `Renderable`, it accepts all standard layout options (`width`, `height`, `flexDirection`, `padding`, etc.) alongside the slot-specific options.

## `SlotRenderable` options

| Option                     | Type                                                                | Required | Description                                                                                                |
| -------------------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                       | `string`                                                            | yes      | Unique renderable identifier (inherited from `RenderableOptions`)                                          |
| `registry`                 | `CoreSlotRegistry`                                                  | yes      | The registry to read plugins from                                                                          |
| `name`                     | slot name                                                           | yes      | Which slot to mount                                                                                        |
| `data`                     | object                                                              | no       | Slot data passed to plugin renderers as the second argument                                                |
| `mode`                     | `SlotMode`                                                          | no       | `"append"` (default), `"replace"`, or `"single_winner"`. See [slot modes](/docs/plugins/slots#slot-modes). |
| `fallback`                 | `BaseRenderable \| BaseRenderable[] \| () => ...`                   | no       | Fallback nodes or a factory that creates them                                                              |
| `pluginFailurePlaceholder` | `(failure, ctx) => BaseRenderable \| BaseRenderable[] \| undefined` | no       | Creates placeholder UI when a plugin throws                                                                |
| _...layout options_        | `RenderableOptions`                                                 | no       | Standard layout props: `width`, `height`, `flexDirection`, `padding`, etc.                                 |

## Instance API

| Member      | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`      | Getter/setter. Changing the mode automatically refreshes the slot.                                                                                                                                                                                                                                                                                                                           |
| `refresh()` | Re-resolve plugins and reconcile mounted children.                                                                                                                                                                                                                                                                                                                                           |
| `destroy()` | Inherits from `Renderable`. In addition to the standard cleanup, `SlotRenderable` unsubscribes from the registry, calls `onDeactivate` on active managed slots, then calls `onDispose` on all managed slots. Host-owned nodes (plain function contributions) are destroyed; plugin-owned nodes (managed slot contributions) are detached but left for the plugin to clean up in `onDispose`. |

## `resolveCoreSlot`

Resolve slot entries without mounting them. Useful when you need to inspect or render plugin output manually.

```typescript
import { createCliRenderer, createCoreSlotRegistry, resolveCoreSlot } from "@opentui/core"

const renderer = await createCliRenderer()
const registry = createCoreSlotRegistry<"statusbar">(renderer, {
  appName: "core-app",
  version: "1.0.0",
})

const entries = resolveCoreSlot(registry, "statusbar")
// Array<{ id: string, renderer: (ctx, data) => BaseRenderable }>
```

## Plugin failure placeholders

If a plugin throws during slot render, you can provide host-controlled fallback UI for that plugin failure:

```typescript
const slot = new SlotRenderable(renderer, {
  registry,
  name: "statusbar",
  fallback: () => new TextRenderable(renderer, { id: "fallback", content: "fallback" }),
  pluginFailurePlaceholder(failure, ctx) {
    return new TextRenderable(renderer, {
      id: `error-${failure.pluginId}`,
      content: `plugin error: ${failure.pluginId}`,
    })
  },
})
```

## Managed slot contributions

A core slot contribution can be a plain function or a managed slot object with lifecycle hooks:

```typescript
registerCorePlugin(registry, {
  id: "managed-plugin",
  slots: {
    statusbar: {
      render(_ctx, data) {
        return new TextRenderable(renderer, { id: "managed", content: "managed" })
      },
      onActivate(ctx) {
        // plugin became active in this slot (visible)
      },
      onDeactivate(ctx) {
        // plugin is no longer active (e.g. mode changed to single_winner and this plugin lost)
      },
      onDispose(ctx) {
        // plugin is removed/disposed for this slot
      },
    },
  },
})
```

### `CoreManagedSlot` interface

| Field          | Type                            | Required | Description                                                          |
| -------------- | ------------------------------- | -------- | -------------------------------------------------------------------- |
| `render`       | `(ctx, data) => BaseRenderable` | yes      | Creates the renderable node for this slot                            |
| `onActivate`   | `(ctx) => void`                 | no       | Called when the plugin becomes active (visible) in the slot          |
| `onDeactivate` | `(ctx) => void`                 | no       | Called when the plugin is no longer active (e.g. lost single_winner) |
| `onDispose`    | `(ctx) => void`                 | no       | Called when the plugin is removed or the slot is destroyed           |

### Node ownership

When a slot contribution is a **plain function**, the host owns the returned nodes. On deactivation or disposal, the host detaches and destroys them.

When a slot contribution is a **managed slot object**, the plugin owns the nodes. On deactivation the host detaches them but does _not_ destroy them — the plugin can reuse them if it becomes active again. On disposal, `onDispose` is called so the plugin can clean up.

## Observability

```typescript
registry.onPluginError((event) => {
  console.error(event.pluginId, event.phase, event.source, event.error.message)
})
```

Example: `packages/examples/src/core-plugin-slots-demo.ts`
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