pencere

A web page

The page’s side

A web view reaches the program through the bridge of §9.4, which @pencere/sdk/page is, as functions: a browser ES module with no dependency that does nothing until it is used.

import { call, close, onContext, openLink, subscribe } from "@pencere/sdk/page";

onContext((context) => document.documentElement.setAttribute("data-theme", context.mode));

const { containers } = await call("list");

const abort = new AbortController();
await call(
  "pull",
  { image: "nginx" },
  {
    onProgress: ({ done, total, note }) => draw(done, total, note),
    signal: abort.signal, // aborting sends `cancel`, and the promise rejects
  },
);

const stop = subscribe(
  "stats",
  { every: 1000 },
  {
    onPush: (value) => draw(value),
    onError: (error) => console.warn(`the readings stopped: ${error.message}`),
    onEnd: () => hideSpinner(), // whoever ended it: the program, or `stop()`
  },
);
stop(); // or stop.cancel()
  • call(method, params?, { onProgress?, signal? }) resolves with the result, or rejects with a CallError (code, and message, which is the code when the program gave no words). A page that nothing embeds has no host: its calls are rejected with the code no-host.
  • subscribe(topic, params, handlers) takes a function in place of handlers when only the values matter. The program ends a subscription with an error, which onError hears; no push follows. The page ends it with the function that is returned (also called cancel).
  • onContext(listener) calls the listener with the terminal’s context now, when the page has it, and on each change: the mode, the roles of the theme, the font, the size, the locale and the time zone, reduceMotion and what the person allowed (§9.5). context() is the last one.
  • close() asks the host to close the view; the program is told, and decides. openLink(url) asks it to open an http: or https: link in the person’s browser.
  • createBridge(channel) is the same on a channel of your own, for a host that embeds the page in some other way, or for a test.

A page has no node_modules, so the module goes in the bundle beside the page, and an import map in the page’s HTML says where the name is. bundleFromDirectory takes the file with its files option:

const bridge = readFileSync(new URL(import.meta.resolve("@pencere/sdk/page")));
const bundle = await bundleFromDirectory(new URL("./view/", import.meta.url), {
  files: [{ path: "pencere-page.js", data: bridge }],
});
<script type="importmap">
  { "imports": { "@pencere/sdk/page": "./pencere-page.js" } }
</script>
<script type="module" src="app.js"></script>

A page that is built with a bundler imports the module like any other, and needs none of this.

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