pencere
A display on the wall of a dark room. The warm light of a window lies across the wall and across the display, with the shadows of the window's bars and of leaves in it, and moves slowly across them. In the shade the display shows a terminal's text; in the light, a program's interface.

pencere is an open protocol for terminals.

Let some light into your terminal.

It lets a program show a real interface in the pane it runs in, on your machine or on a server over plain ssh.

In the shade htop, a terminal's textgit diff, a terminal's text
In the light toppen, the same job with an interfacetextpen, the same job with an interface

A program takes its pane, and gives it back.

The way a full-screen program like vim takes the screen. But what it puts there is a real interface, not a grid of characters.

  1. It starts like any command.

    At a prompt, on your machine or on a server over plain ssh.

  2. Its view takes the pane.

    The program does not draw it. It hands the terminal the view's files, and the terminal draws them, on your machine.

  3. It ends, and the shell is back.

    What was on the screen is there again, as after any full-screen program.

While the view is up, the program and the view talk in six small messages. The view sends call, subscribe and cancel; the program sends response, push and progress. That is the whole protocol, and it is the same for every kind of view.

Programs made with it.

Each is one file, and shows a real interface in the pane it runs in, on your machine or on a server over plain ssh, in the font and the theme of your terminal.

Write one.

The same program: a view, one call it answers, and one topic it feeds. Whichever you write it in, it is one file to hand to someone, and pencere new <name> --lang lua|ts|rust starts it for you.

Run by the pencere command (pencere build makes one executable of it).

local pencere = require("pencere")

pencere.serve { -- shows src/view/: page.lua, a script of the kit's page API, drawn by the terminal
  calls = { hello = function(params) return { message = "Hello, " .. params.name .. "!" } end },
  topics = {
    clock = function(_, sub)
      local timer = pencere.time.every(1, function() sub:push({ now = pencere.time.now() }) end)
      sub:on_end(function() timer:cancel() end)
    end,
  },
  fallback = function() print("This terminal shows no views.") end,
}

Start

The pencere command makes, runs and packs an app. It installs with one line, on macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh

A program in TypeScript or Rust takes the library instead: npm install @pencere/sdk, cargo add pencere.

Start an app, step by step

The kit

What a view the terminal draws is written with: elements and their layout, an editor of text, and a library of components.

See the kit

Any terminal can host it.

bateri is the first terminal that hosts pencere. The specification, the libraries and the tools are all under Apache-2.0, so any terminal or program, open or closed, can implement the protocol or embed this code.