pencere

A program in TypeScript

@pencere/sdk

Show a view in the terminal pane your program runs in.

A program running in a terminal pane — on your machine, or on a server reached over plain ssh — can show a view of its own in that pane, the way a full-screen program takes the screen and gives it back when it ends. The view is a web page, or a Lua script the terminal draws itself; whichever it is, it and your program talk in six small messages, carried in the terminal’s own byte stream. This package is the program’s side of that, as the specification defines it.

npm install @pencere/sdk

pencere new <name> --lang ts starts a project that uses it, with a web page for its view, or with a page of the kit (--page lua): the pencere command.

import { bundleFromDirectory, serve } from "@pencere/sdk";

const result = await serve({
  views: [{ kind: "web", bundle: await bundleFromDirectory(new URL("./view/", import.meta.url)) }],
  program: "containers",
  title: "Containers",
  calls: { list: () => ({ containers: listContainers() }) },
  topics: {
    stats: (_params, subscription) => {
      const timer = setInterval(() => subscription.push(readStats()), 1000);
      return () => clearInterval(timer);
    },
  },
  fallback: () => console.log(table()),
});

serve does what the situation asks:

  • A terminal that hosts pencere. The terminal’s modes are set, the host is asked which kinds of view it opens, the alternate screen is taken, and the view is opened with the token the host gave. The files of the bundle the host does not already hold are sent, your handlers answer the view, and when the view closes the terminal is given back and serve resolves with { kind: "closed", by }. ⌃C ends the program as it always does: bye is sent, the screen and the modes are restored, and the signal goes on.
  • A terminal that does not, or no terminal at all. serve resolves with { kind: "no-view", reason } after the fallback, if there is one, has run: the program offers its own text interface. No frame of the protocol is sent when stdin or stdout is not a terminal.

Views

views lists the kinds of view the program can show, in the order it prefers them. The host opens the first kind it can, at the first version of that kind’s interface it speaks:

  • web is a page: HTML and JavaScript, with the files in a bundle (bundleFromDirectory, or bundleFromFiles), sent once and then served from the terminal’s store by content. A page that needs to reach a domain, or the camera, microphone, location or clipboard, says so in its access; the person is asked, once, and the page is told what they allowed.
  • lua is a view the terminal draws itself with the pencere kit. It says which versions of the kit’s interface it is written against, and bundle may be a function of the version that was agreed, for a view that has a build for each.

program, title and icons are what the terminal writes above the view and draws beside it. A terminal draws an icon only from the bytes it is given and never fetches one, so give it as a PNG, JPEG or WebP in a data: URI, small and not animated; an https: icon is left out in the pane. Make it square: a terminal draws it in its own frame, at its own size. On a clear background the icon stands on the terminal’s own face, as its marks do; filled to its edges, the icon’s ground becomes the face. A version for a light background and one for a dark one, each with its theme, let the terminal take the one that suits its theme.

Calls and topics

The view asks and the program answers. calls are the methods the view may call, each returning a result (or throwing a ViewError with a short code the view can act on and, if you like, words for the person); a method that is not there is answered not-found. topics are the subscriptions the view may make: a handler pushes values to the view with subscription.push until the view cancels it or ends, and returns a function that stops whatever feeds it. A call that takes a while reports how far it has got with call.progress, and stops when call.signal is aborted: the view gave it up. The view side of all this is a few lines of JavaScript posting JSON objects to its window’s parent (specification §9.4); the containers example has both halves.

What a Lua page prints with print and warn reaches the program too, as a call of the reserved method pencere.log that serve answers itself, at once, and hands to the log option as a line: { level, text }, where level is "warn" for warn and "info" for anything else. The text comes from a page the program does not trust and is meant for a log or a terminal, so every control character in it but the tab and the line feed is written as \xNN (an escape is \x1b). The library has no sink of its own and prints nothing while the view is up, because the terminal is the view’s: the program decides where the lines go. Without log they are dropped, and the page is answered all the same. A calls or topics with a name that begins with pencere. is refused when serve starts: that prefix is the protocol’s.

import { appendFileSync } from "node:fs";

await serve({
  views,
  calls,
  log: ({ level, text }) =>
    appendFileSync("app.log", `${level === "warn" ? "warning: " : ""}${text}\n`),
});

A program that wants to close its view and go on — to show its own interface for a while, or, while a program is developed, to show the view again with the files that changed — gives serve a ViewControl and calls it while serve runs. A host that lists dismiss in its welcome takes it; with another the view is left as it is and the call says unsupported.

const control = new ViewControl();
const served = serve({ views: [{ kind: "web", bundle }], calls, control });
// when the view's files changed:
await control.reopen({ views: [{ kind: "web", bundle: await bundleFromDirectory(directory) }] });
// or to leave the view and show the program's own interface:
await control.close(); // `serve` then resolves with `{ kind: "closed", by: "program" }`

The terminal’s modes are set with stty, not with process.stdin.setRawMode or Deno’s setRaw: raw mode also turns off ISIG, and ⌃C would arrive as a byte instead of a SIGINT. A system with no stty, such as Windows, has no host as far as this library is concerned.

Files

For a lua view, ViewControl moves files between the person’s machine and the program: attach(bytes) adds a file for the view to draw, read(handle, offset, length) reads a file the person gave the view (dropped on it, pasted, chosen in the Open panel) and write(handle, offset, bytes, end) writes to the place the person chose in the Save panel. Each is one message, a piece of at most 1 MiB in base64 through the terminal’s stream.

When the program runs on another machine, behind a remote shell, that stream is the slow way. A host that has a way of its own to the program’s machine keeps a folder there and lists stage in its welcome; the bytes then cross through a pipe in it, and only the bytes. The steps are yours to drive:

const folder = control.stageFolder(); // undefined unless the program has proved the folder is the host's
if (folder !== undefined) {
  const transfer = await control.stage(handle, 0); // or control.fetch(handle, size, 0) for a Save panel's place
  const fd = folder.openPipe(await transfer.pipe, "read"); // a descriptor of a FIFO of your own user
  // read fd until the end of the file, writing it to a part of your own...
  const end = await transfer.done; // the offset of the end of the file; the part must be that long
}

stageFolder() checks that the folder is an absolute path, a directory of your user that the group and others cannot use, with a marker file whose content is exactly the token of the welcome; anything less and it is undefined, and read and write do the work. openPipe opens without following a link and without blocking, and only a FIFO of your user. A pipe that stays silent is yours to give up on: transfer.unstage() takes it back, the place is as it was before, and read and write go on from there. After a route (transfer.done rejects with code route; a fetch also says at, how long a file the host holds) a new stage starts at the length of your part and a new fetch at at.

Runtimes

The same code runs on Node (20 and later), Deno (2) and Bun, with nothing to configure. The terminal’s modes, the signals and the files are each reached the way the runtime allows; the rule is the same on all three (specification §4.9): the tty is not canonical and does not echo, ISIG stays on so that ⌃C is a SIGINT, and every mode is given back on every way out.

  • Node needs nothing.
  • Deno needs permission to read the view’s files and to run programs (stty, and the signal the program sends itself): deno run --allow-read --allow-run main.js. Install the package with npm:@pencere/sdk. A program that is not allowed to run programs ends with the status a shell reports for a signal (130, 143) instead of being ended by the signal. A filter asks for the terminal it opens itself, which Deno lets a program write to only with --allow-all.
  • Bun needs nothing. A filter does not work on Bun 1.0, the version this was tried on: its stream for a tty does not deliver what the terminal writes to /dev/tty, so a filter finds no host.

deno compile makes one executable of the program, its view and the Deno runtime. A view the program reads from a directory at run time is put in with --include; see the containers example for the task, which keeps the executable down to what the program needs.

deno compile --allow-read --allow-run --no-prompt --include view --output containers main.js

The program leaves the terminal as it found it when it ends in any way it can run code in:

  • ⌃C and SIGTERM send bye and wait for the answer, reading the input and throwing it away (byeTimeout, 500 ms by default), then give the screen and the modes back and let the signal go on. A signal before the host has answered the hello waits, in the same way, for the terminal’s answer to CSI c, so that a late welcome does not reach the shell as typed text.
  • process.exit (the exit event) cannot wait for the event loop. The program says bye, and reads the tty itself, with no loop, until the answer to it or byeTimeout.
  • ⌃Z closes the view (with dismiss, or bye for a host that does not list it), gives the screen and the modes back, and stops; when it is continued it takes the modes again and asks for the view anew, as the first time. A runtime that cannot catch SIGTSTP leaves ⌃Z to the system.

The router

serve hands the view’s call, subscribe and cancel to a router, which finds the handler by name, runs it, and writes the response, push and progress back, with the errors turned into the view’s words (ViewError as its code and message, anything else as internal). createRouter is that router with no terminal: the handlers of an app can be tested, or driven by a development harness, through it. It takes log as well, and refuses the names that begin with pencere. as serve does.

import { createRouter } from "@pencere/sdk";

const sent: unknown[] = [];
const router = createRouter({ calls, topics }, (payload) => {
  sent.push(JSON.parse(payload)); // the program's side of what the view hears
  return true;
});
router.handle({ call: { id: 1, method: "list" } });
// ... later, `sent` holds { response: { id: 1, result: { ... } } }
router.end(); // the view is over: calls are cancelled, subscriptions stop

Versions

This release speaks version 1 of the pencere wire, which is still a draft: until the specification publishes a dated version, a 0.x release of this package may change the wire along with it. The package follows semantic versioning; CHANGELOG.md says what each release changed.

License

Apache-2.0 — see LICENSE.

This page is a part of sdk/typescript/README.md of the repository.