Coming from blessed

controlroom is the burgee family's planned blessed alternative for full-screen, keyboard-driven terminal programs. It is reserved, not usable yet: the published version exports one constant, status = 'reserved', and every controlroom snippet on this page is marked Planned, not built. The page exists now so that a blessed program can be read against the spec before the code lands, and so that burgee migrate has somewhere to send you.

Only drawing inline output, with no keys? You want flagstaff, which you can use today: Which one do I need?

Migrate from blessed: not one importCopy Anchor Link

There will be no controlroom/blessed. blessed's surface is too large to reproduce honestly (spec R18), so moving is a rewrite of each screen, not of the import line. What does exist today is the report. burgee migrate finds the blessed sites in your project and names the section of this page that covers each one:

npx burgee migrate --dry-run --json

It reports and never rewrites. The API a rewrite would target is not built, and rewriting onto it would turn a program that runs into one that does not load. For this program:

const blessed = require('blessed');

const screen = blessed.screen({ smartCSR: true });
const list = blessed.list({ items: ['build', 'test'], keys: true });
screen.append(list);
screen.key(['q', 'C-c'], () => process.exit(0));
screen.render();

the report's guided list reads, one entry per site:

[
  { "file": "src/ui.js", "line": 1, "from": "blessed", "pattern": "import", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#the-mapping" },
  { "file": "src/ui.js", "line": 3, "from": "blessed", "pattern": "screen", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#screen" },
  { "file": "src/ui.js", "line": 4, "from": "blessed", "pattern": "list", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#list" },
  { "file": "src/ui.js", "line": 6, "from": "blessed", "pattern": "key", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#key-handling" },
  { "file": "src/ui.js", "line": 7, "from": "blessed", "pattern": "render", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#render-loop" }
]

A site is reported only when the receiver came from blessed in the same file: screen.key( on a screen from blessed.screen() is a key binding, and screen.key( on anything else is not. A screen passed in from another file is not followed, but that file's own require('blessed') still is. The exit code stays 0, because nothing was refused. The Migrate page has the whole report.

The mappingCopy Anchor Link

"On main today" is literal: a row that says no has no code behind it yet.

ScreenCopy Anchor Link

blessed.screen() takes over the terminal when it is constructed. controlroom's open(runtime, { screen: 'alternate' }) is specified to do the same only when roundel's output policy says tty and stdin can go raw (R4). In every other mode it opens a static session instead, so the same program runs in a pipe, in CI and under --json. runtime is the structural runtime the family's packages take instead of reading process.

// Planned, not built: open() is R4. controlroom exports none of this today.
import { open } from 'controlroom';

const screen = open(runtime, { screen: 'alternate' });
try {
  await runTheApp(screen);
} finally {
  screen.close();
}

R19 adds screen: 'inline', the default: a live region under the program's own output, which stays in the scrollback. blessed has no equivalent of that mode.

burgee migrate reports blessed.screen(), new blessed.Screen() and blessed.program() here. A program is blessed's lower-level handle on the terminal, and what it does for a blessed screen is what open() is specified to do for a controlroom one.

BoxCopy Anchor Link

A blessed box positions itself: top, left, width and height as cells, percentages or 'center'. In controlroom a pane does not position itself. One layout tree splits the screen into rows and columns of fixed, fractional ({ fr, min }) and fit-to-content sizes (R8), and a pane is a name in that tree. What a pane draws is a flagstaff component, so its border, padding and title come from flagstaff's boxComponent, which exists today.

// Planned, not built: layout() is R8, and it is not on main.
import { layout } from 'controlroom';

const tree = {
  direction: 'column',
  parts: [
    { content: { direction: 'row', parts: [{ size: { fr: 1, min: 20 }, content: 'learn' }, { size: { fr: 2 }, content: 'tasks' }] } },
    { size: 8, content: 'logs' },
  ],
};
layout(tree, { x: 0, y: 0, width: 100, height: 30 }).get('tasks');
// { x: 34, y: 0, width: 66, height: 22 }

There is no flexbox and no constraint solver: one pass hands out the fixed cells and the minimums, and a second shares the rest by fraction. A terminal too small for the minimums clips the later parts, never the first. How a pane is handed its component (R5, R10) is not designed in detail yet, so it is not shown.

burgee migrate reports box(), text(), element(), log() and layout() here. The last is blessed's own auto-positioning container, which the layout tree replaces outright.

ListCopy Anchor Link

A list you show, such as steps with a state each, is flagstaff's tasks in a pane. It exists today, and outside a terminal it prints one line per task that has settled. A list the user picks from, blessed's keys: true with a select event, has no planned pane component. A pick is a prompt, and prompts are caique's: select, asked before or after the screen, not inside it. listbar maps to a tab bar (R3, R9).

burgee migrate reports list(), listtable() and listbar() here.

Key handlingCopy Anchor Link

blessed binds a key to a function: screen.key(['q', 'C-c'], fn). controlroom binds a key to an action name, in a keymap that is plain data, and the screen's state moves through a reducer (R9). The hint line is generated from the same keymap, so it cannot advertise a key that is not bound.

// Planned, not built: initial(), reduce() and hints() are R9, and they are not on main.
import { hints, initial, reduce } from 'controlroom';

const keymap = { left: 'tab.prev', right: 'tab.next', s: 'toggle:status', q: 'quit', 'ctrl+c': 'quit' };
const labels = { 'tab.prev': 'switch tab', 'tab.next': 'switch tab', 'toggle:status': 'toggle status', quit: 'quit' };

let state = initial(['Status', 'Tail logs'], ['learn', 'tasks']);
state = reduce(state, keymap.right); // the second tab is active
hints(keymap, labels); // '←→ switch tab  s toggle status  q/^C quit'

An action the reducer does not know, such as quit here, leaves the state alone and is the program's own to handle. Key names change spelling, as the spec's examples write them:

The final spelling is caique's key decoder (R2), which is not built either. Raw mode is taken once for the screen's whole life and handed back by closeout. No API waits for a key unless there is a terminal to press it on (R7).

burgee migrate reports key(), onceKey(), unkey() and removeKey() here, on a screen, an element or a program, and every on() or once() whose event name starts with key: keypress, and blessed's key q form.

Render loopCopy Anchor Link

blessed draws nothing until you call screen.render(), so a blessed program calls it after every change. controlroom has no render call to make. A state change is drawn by the compositor (R5): it writes the whole frame through flagstaff's repaint loop, diffed line by line and wrapped in synchronized output, and lays it out again on resize. controlroom never writes to the terminal itself (R15). When you move a screen, delete its render() calls rather than translating them. burgee migrate reports each one, including box.screen.render().

Alternate screenCopy Anchor Link

blessed's screen switches to the alternate buffer itself, through its program's alternateBuffer(), and normalBuffer() switches back. controlroom's is the screen: 'alternate' option, and leaving it is registered with closeout, so Ctrl+C, SIGTERM, a throw and a normal return all hand the terminal back (R1, R4).

The mechanism open() is specified to use is on main today, in closeout:

import { alternateScreen, rawMode } from 'closeout';

const undo = [rawMode(process.stdin), alternateScreen(process.stdout)];
try {
  await runTheFullScreenApp();
} finally {
  for (const back of undo) back();
}

Each call makes its change and registers its undo, which runs once on whichever exit comes first. This has not been tested beside blessed, which manages the terminal itself, so it is shown as the mechanism and not as a step to add to a blessed program.

burgee migrate reports alternateBuffer() and normalBuffer() here, on a program or on screen.program.

What does not mapCopy Anchor Link

These are out of scope in controlroom's intent, so a program that depends on them should stay on blessed.

MouseCopy Anchor Link

Clicks, the wheel and drags (mouse: true, screen.enableMouse(), on('click')) have no controlroom equivalent, and none is planned. Mouse support is reopened only by an adopter's measured need. burgee migrate reports each mouse site it can see, so you know how many there are: enableMouse(), and on() with mouse, click, mousedown, mouseup, mousemove, mouseover, mouseout, wheeldown or wheelup.

Text editing in a paneCopy Anchor Link

textbox(), textarea() and form edit text inside the screen, and burgee migrate reports the first two here. controlroom does not edit text in a pane: prompts stay with caique, asked outside a pane. The one exception is planned for chat-shaped screens: caique's line editor hosted as the input line of an inline screen (R20). A text editor pane stays out.

Legacy Windows consolesCopy Anchor Link

controlroom handles no Windows legacy console quirks beyond what node:readline already does. If your blessed program relies on behaviour specific to an old Windows console, check that before you plan a move.

The rest of blessed's widget catalogue, including images, embedded terminals and forms, has no controlroom counterpart either. The mapping above is the whole of what is planned.

Is controlroom compatible with blessed?Copy Anchor Link

No, by design. There is no drop-in and nothing is graded: no blessed suite runs against controlroom, and none will, because the API is not being reproduced. The Compatibility page carries controlroom's planned grade against Ink, whose suite is to be vendored and run with a control (R13). It will not carry a blessed row.

What you gain over blessedCopy Anchor Link

All of this is what the spec commits controlroom to, not something it does today.

• Every caller gets an answer, not just a terminal. In pipe, ci and accessible mode a screen prints each pane's static projection, in the declared pane order and under its label. It writes no alternate screen, no cursor movement, no \r and no escape byte. Tabs hide nothing and no key hints are printed (R6).
• --json is an event stream. Under --json, stdout belongs to the result envelope and the screen's events go to stderr as NDJSON, { event, pane, state }, so an agent reads the same program a person watches (R6).
• It never hangs. No API waits for a key unless the mode is tty and stdin can go raw. A wait that cannot be satisfied resolves at once with the static result, or throws with a fix (R7).
• One render engine. The spinner in a pane is the same flagstaff component, drawn by the same frame loop, as the spinner in an ordinary CLI (R15).
• Nothing installed from outside the family. That is a rule every published package in this repository is held to by a lock, controlroom included.

This page does not say what blessed writes to a pipe or under CI, and makes no size or speed comparison: none has been measured here. The spec's conformance test, which spawns a screen in every mode and fails on an escape byte, a \r or a hang, is how these claims will be checked when the code exists.

When to switch from blessedCopy Anchor Link

Not yet. None of controlroom's screen API exists, and a blessed program has nothing to move onto. The spec's order is the core first (R4 to R7), then the native API (R8 to R10) with these guides' snippets. Watch the package page, which changes when a requirement ships.

When it exists, switch if your program's output has to work for a pipe, CI, a screen reader or an agent as well as for a person at a terminal. Stay on blessed if you depend on the mouse, on editing text inside a pane, or on widgets outside the mapping above.