ink-cartridge - A terminal application framework built on Ink

[BAIGAOa]

Introduction

I'm aigao. To address the missing capabilities in Ink, I've open-sourced a framework built on top of it, enabling developers to build their tools more comfortably. Here, I'd like to share what it is and what it does.

What It Is

It is a framework built on top of Ink, designed to fill the gaps in page management, keyboard event handling, and mouse support, while also providing additional tooling such as i18n and theming. It helps you quickly build well-structured Ink applications without having to write spaghetti code full of if-else and switch statements for keyboard events and page navigation.

Why You Need It

Ink only provides you with basic hooks and rendering capabilities; it lacks the essential infrastructure needed for building complex applications. As a result, the Ink community has produced numerous component libraries and wheels, but these solutions are fragmented and mostly focused solely on UI components. Nearly every Ink application ends up building its own custom infrastructure to handle multi-page navigation, dense interactions, popups, modals, and mouse support. ink-cartridge provides a complete, integrated solution for all of these challenges.

What It Offers

Screen System

Ink itself is only responsible for rendering and does not solve the problem of "how to navigate between different pages." While you could certainly write a bunch of conditional renders in the root component, as the number of pages grows, state becomes scattered and difficult to maintain.

ink-cartridge's Screen System provides tree-based navigation: declare parent-child relationships when registering components, then use skip to navigate downward, back to return, and gotoScreen to jump across branches. On top of this, a Layer System is overlaid—floating panels, modals, and notification bars can all be rendered as independent layers, each with its own z-index and keyboard priority, and they support cross-page persistence.

Keyboard System

This is the core of the framework. Ink's useInput works well for simple scenarios, but in complex applications, you need to handle requirements like "when a Modal is open, shortcuts on the underlying page should not respond."

ink-cartridge implements a 9-stage pipeline where keyboard events flow through each stage in order of priority: Modal Layer → Regular Layers → Global Shortcuts → Screen Stack. Each layer can consume the event, let it pass through, or block it. You can bind key sequences (e.g., gg, ctrl+w q) or allow specific keys to penetrate the current layer.

The keyboard engine also includes a CompositionEngine, which implements key combination parsing based on flags and needs—each key declares its own identity (flag) and prerequisites (needs), and the engine resolves whether a key combination is valid by matching the flag chain. This mechanism supports Vim-style multi-key sequences and context-sensitive bindings.

The keyboard engine is a framework-agnostic, pure TypeScript module with zero dependencies. It can be used independently in any JavaScript runtime, though it is best integrated with React Ink.

Mouse Support

With useMouseRegion, any <Box> can be transformed into an interactive region, supporting clicks, hover, drag, and scrolling. Mouse events follow the same priority as keyboard events—Modals take precedence over Layers, and Layers take precedence over the underlying page. Dragging floating panels, hovering over buttons, and scrolling in scrollable areas can all be accomplished with the same unified API.

ink-cartridge relies on these capabilities to enable Ink to build much more powerful applications.

Where to Learn More

GitHub Repository: https://github.com/BAIGAOa/ink-cartridge
ink-cartridge Documentation: https://baigaoa.github.io/ink-cartridge/