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/keymap/addons.mdx

View on GitHub
---
title: Built-in Addons
description: Shipped universal and OpenTUI-specific keymap addons
order: 6
navTitle: Built-in Addons
---

# Built-in keymap addons

`@opentui/keymap` keeps the engine bare. The built-in addon packages install parser stages, field compilers, diagnostics, disambiguation and host-specific helpers on top of the public registration APIs.

If you want to build your own addon, see [Custom Addons](/docs/keymap/custom-addons).

Every addon returns a disposer.

```ts
import * as addons from "@opentui/keymap/addons"
import * as opentuiAddons from "@opentui/keymap/addons/opentui"
```

## Universal addons

### Defaults

| Export                                | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| `defaultBindingParser`                | Shared parser for string key syntax                   |
| `defaultEventMatchResolver`           | Shared event matcher for canonical normalized strokes |
| `registerDefaultBindingParser()`      | Appends `defaultBindingParser`                        |
| `registerDefaultEventMatchResolver()` | Appends `defaultEventMatchResolver`                   |
| `registerDefaultKeys()`               | Installs both default stages together                 |

The shared default parser accepts single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as a literal plus key, `<token>` aliases, and `{pattern}` runtime captures. It parses concatenated multi-stroke sequences such as `dd`, `<leader>s`, or `{count}j`.

If a parsed sequence references an unknown token, that expanded binding is skipped until the token is registered. This is a fail-closed behavior: `<leader>s` without a registered `leader` token does not become plain `s`.

Recognized modifier prefixes (case-insensitive, joined with `+`):

| Modifier | Aliases         |
| -------- | --------------- |
| `ctrl`   | `control`       |
| `shift`  | -               |
| `meta`   | `alt`, `option` |
| `super`  | -               |
| `hyper`  | -               |

### Field addons

| Export                       | Adds                                                                               |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `registerBindingOverrides()` | Layer-local `bindingOverrides` field for replacing bindings by string command name |
| `registerEnabledFields()`    | Layer and command `enabled` fields                                                 |
| `registerMetadataFields()`   | Binding `desc` / `group` and command `desc` / `title` / `category` metadata        |
| `registerAliasesField()`     | Layer-local `aliases` field for remapping single-key binding names                 |

`registerBindingOverrides()` expects `bindingOverrides` to already be a `Binding[]` array. It rewrites that layer's binding array once at registration time. Matching string commands are replaced by the override binding and unmatched bindings stay in place.

`registerEnabledFields()` accepts `boolean`, `() => boolean`, or `ReactiveMatcher` values. It applies to layers and commands, not bindings. It controls activation only; it does not publish attrs.

`registerMetadataFields()` validates and trims metadata fields before exposing them in projections. Binding `desc` / `group` become binding metadata. Command `desc` / `title` / `category` become command metadata in `commandAttrs`.

Layer metadata is app-specific. Register layer fields directly with `registerLayerFields()` and call `ctx.attr(...)` when graph/debug visualizations need layer labels or grouping metadata.

`registerAliasesField()` adds bindings instead of replacing the originals and aliases stay local to the layer that declared them.

### Syntax and sequence addons

| Export                                   | Description                                                             |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| `registerCommaBindings()`                | Expands `x, y` into multiple bindings                                   |
| `registerEmacsBindings()`                | Parses Emacs-style spaced chords such as `ctrl+x ctrl+s`                |
| `registerLeader()`                       | Defines a token such as `leader` that `<leader>` syntax expands through |
| `registerModBindings()`                  | Adds platform-aware `mod+...` bindings using host metadata              |
| `registerTimedLeader()`                  | Defines a leader token and clears it after a timeout                    |
| `registerBackspacePopsPendingSequence()` | Lets Backspace step back through the current pending sequence           |
| `registerEscapeClearsPendingSequence()`  | Lets Escape cancel the current pending sequence                         |
| `registerNeovimDisambiguation()`         | Timeout-based exact-vs-prefix disambiguation                            |

Options:

| API                                      | Options                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| `registerLeader()`                       | `LeaderOptions`: `trigger`, optional semantic `name` (default `"leader"`)            |
| `registerTimedLeader()`                  | `TimedLeaderOptions`: `LeaderOptions` plus `timeoutMs`, `onArm`, `onDisarm`          |
| `registerBackspacePopsPendingSequence()` | `BackspacePopsPendingSequenceOptions`: `preventDefault` (default `true`), `priority` |
| `registerEscapeClearsPendingSequence()`  | `EscapeClearsPendingSequenceOptions`: `preventDefault` (default `true`), `priority`  |
| `registerNeovimDisambiguation()`         | `NeovimDisambiguationOptions`: `timeoutMs` (default `300`)                           |

Register disambiguation addons before registering same-layer exact/prefix bindings such as `g` and `gg`.

Leader `trigger` accepts a key string, key object, binding-like `{ key }`, or a single binding lookup result from `createBindingLookup().get(...)`. Empty lookup results are treated as disabled and return a no-op disposer; lookup results with more than one binding are rejected.

Apps that support disabling leader keys can omit the leader addon or pass an empty lookup result. Any `<leader>...` bindings will remain dormant because unresolved tokens are skipped.

### Diagnostics

| Export                                | Description                                                       |
| ------------------------------------- | ----------------------------------------------------------------- |
| `registerDeadBindingWarnings()`       | Warns when a binding has no command and no reachable continuation |
| `registerUnresolvedCommandWarnings()` | Warns when a string command cannot be resolved                    |

## Ex commands

`registerExCommands()` installs ex-command field compilers, a command transformer and a resolver for `:name ...args` strings. Register ex commands through normal keymap layers by using a colon-prefixed command name or `namespace: "excommands"`.

```ts
import { registerExCommands } from "@opentui/keymap/addons"

registerExCommands(keymap)

keymap.registerLayer({
  commands: [
    {
      name: "write",
      namespace: "excommands",
      aliases: ["w"],
      nargs: "1",
      desc: "Write file",
      run({ payload }) {
        // payload.raw === ":write session.log"
        // payload.args === ["session.log"]
      },
    },
  ],
})
```

`ExCommand` fields:

| Field        | Type                                                                        | Required | Description                                                      |
| ------------ | --------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `name`       | `string`                                                                    | yes      | Command name. `:name` and `name` both normalize to `:name`       |
| `aliases`    | `string[]`                                                                  | no       | Additional names                                                 |
| `nargs`      | `"0"`, `"1"`, `"?"`, `"*"`, `"+"`                                           | no       | Argument-count validation                                        |
| `run`        | `(ctx: CommandContext<TTarget, TEvent, ExCommandPayload>) => CommandResult` | yes      | `ctx.payload` contains the trimmed `raw` input and parsed `args` |
| extra fields | `unknown`                                                                   | no       | Added as top-level fields on the registered command              |

- Registered ex commands default `namespace` to `excommands`.
- Aliases produce additional registered commands, for example `:write` and `:w`.
- Extra fields are preserved on `getCommands()` / `getCommandEntries()` results and compiled through command-field addons.
- `runCommand(":write file.txt")` and `dispatchCommand(":write file.txt")` both go through the installed resolver.

## OpenTUI addons

`@opentui/keymap/addons/opentui` re-exports every universal addon and adds the OpenTUI-specific helpers below.

### `registerBaseLayoutFallback()`

Adds an event match resolver that falls back to `KeyEvent.baseCode` so bindings can ignore active keyboard layout changes when Kitty base-layout reporting is available. Direct stroke matches win before base-layout fallback matches, even across active layers.

### Edit buffer helpers

| Export                                | Description                                                                              |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `createTextareaBindings()`            | Returns generated textarea bindings with overrides prepended                             |
| `registerEditBufferCommands()`        | Registers the shared edit-buffer command set against `renderer.currentFocusedEditor`     |
| `registerTextareaMappingSuspension()` | Suspends focused `TextareaRenderable` mapped shortcuts while keeping plain typing intact |
| `registerManagedTextareaLayer()`      | High-level textarea integration: commands, suspension, default bindings and overrides    |

`registerManagedTextareaLayer()` accepts a global `Layer` shape plus optional `bindings`, but it intentionally excludes `target` and `targetMode`. The helper is global and follows `renderer.currentFocusedEditor`.

`EditBufferCommandOptions`:

| Field              | Type                                             | Description                                                                     |
| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `category`         | `string`                                         | Override generated command category, defaulting to `Text Editing`               |
| `group`            | `string`                                         | Override generated binding group, defaulting to `Text Editing`                  |
| `includeFineGroup` | `boolean`                                        | Include hard-coded binding `fineGroup` fields for apps that register that field |
| `commandNames`     | `Partial<Record<EditBufferCommandName, string>>` | Override generated command names                                                |
| `descriptions`     | `Partial<Record<EditBufferCommandName, string>>` | Override generated command descriptions                                         |

`registerEditBufferCommands()` and `registerTextareaMappingSuspension()` are reference-counted per keymap, so multiple integrations can safely share them.

### `EditBufferCommandName`

| Action                    | Default command                 | Default description         |
| ------------------------- | ------------------------------- | --------------------------- |
| `move-left`               | `input.move.left`               | Cursor left                 |
| `move-right`              | `input.move.right`              | Cursor right                |
| `move-up`                 | `input.move.up`                 | Cursor up                   |
| `move-down`               | `input.move.down`               | Cursor down                 |
| `select-left`             | `input.select.left`             | Select left                 |
| `select-right`            | `input.select.right`            | Select right                |
| `select-up`               | `input.select.up`               | Select up                   |
| `select-down`             | `input.select.down`             | Select down                 |
| `line-home`               | `input.line.home`               | Line start                  |
| `line-end`                | `input.line.end`                | Line end                    |
| `select-line-home`        | `input.select.line.home`        | Select to line start        |
| `select-line-end`         | `input.select.line.end`         | Select to line end          |
| `visual-line-home`        | `input.visual.line.home`        | Visual line start           |
| `visual-line-end`         | `input.visual.line.end`         | Visual line end             |
| `select-visual-line-home` | `input.select.visual.line.home` | Select to visual line start |
| `select-visual-line-end`  | `input.select.visual.line.end`  | Select to visual line end   |
| `buffer-home`             | `input.buffer.home`             | Buffer start                |
| `buffer-end`              | `input.buffer.end`              | Buffer end                  |
| `select-buffer-home`      | `input.select.buffer.home`      | Select to buffer start      |
| `select-buffer-end`       | `input.select.buffer.end`       | Select to buffer end        |
| `delete-line`             | `input.delete.line`             | Delete line                 |
| `delete-to-line-end`      | `input.delete.to.line.end`      | Delete to line end          |
| `delete-to-line-start`    | `input.delete.to.line.start`    | Delete to line start        |
| `backspace`               | `input.backspace`               | Delete backward             |
| `delete`                  | `input.delete`                  | Delete forward              |
| `newline`                 | `input.newline`                 | New line                    |
| `undo`                    | `input.undo`                    | Undo                        |
| `redo`                    | `input.redo`                    | Redo                        |
| `word-forward`            | `input.word.forward`            | Next word                   |
| `word-backward`           | `input.word.backward`           | Previous word               |
| `select-word-forward`     | `input.select.word.forward`     | Select next word            |
| `select-word-backward`    | `input.select.word.backward`    | Select previous word        |
| `delete-word-forward`     | `input.delete.word.forward`     | Delete next word            |
| `delete-word-backward`    | `input.delete.word.backward`    | Delete previous word        |
| `select-all`              | `input.select.all`              | Select all                  |
| `submit`                  | `input.submit`                  | Submit                      |

The generated textarea bindings come from the shared `defaultTextareaKeyBindings` in `@opentui/core`. `createTextareaBindings()` prepends overrides before those defaults so custom bindings win by order.

See [Custom Addons](/docs/keymap/custom-addons) for the public addon-authoring APIs, lifecycle rules, callback contexts and extension-point quirks.
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