pencere

The kit in a terminal

The pencere kit

What a terminal needs to show the views of kind lua of pencere in its own font and theme, and what a page is written with. A view of this kind is a Lua script that the kit’s interpreter runs in a sandbox that reaches nothing but what the page API gives it; the terminal lays out what it hands out and draws it. The one contract outside the kit is SPEC.md.

Directory Crate What it is
view pencere-view The page engine: elements, style, layout (flexbox and grid), the draw list. Depends on the layout crate only
editor pencere-editor The editor of text a host puts in an editor’s room: document, carets, undo, input method, layout and drawing
sandbox pencere-sandbox Runs a script under limits and hands out pages. The one door to the WebAssembly runtime the interpreter runs on
drive pencere-drive Drives a page as every host does: what the person does in, its frames, editors, scrolling, replies and wakes out
wit The interface between the interpreter and the sandbox that runs it: pencere:view, internal to the kit
SPEC.md What the kit’s views are written against: the Lua page API, the colours, the sandbox floors and the versions
luau The sources of the interpreter for scripts: Luau, the bridge to the interface and the Lua page API
sandbox/library The kit’s library: modules of Luau a page requires as @pencere/<name>
guest Another workspace: the tools that make the interpreter’s component (cbindgen, componentize)

The page language, the sandbox and the drive know nothing of a window, a font or a renderer. The drive does what the specification (Section 4) asks of every host but what only a host can do; a terminal measures text for the engine (pencere_view::Measure), resolves the colours of a page in its own theme (a role in the theme, a value in the form that goes with its brightness), keeps text readable against the grounds the draw list names under it, and turns the draw list into what it draws.

Where a part of the kit goes

The kit is made of four layers. Every part of it, and every part added to it later, takes its place by the rule of a layer, not by where its first user would like it to be.

Layer What it is What goes there
0. The host Rust: the wire, the engine (the layout and the draw list), the editor of text (pencere-editor), the sandbox, the drive (pencere-drive) What only a host can do. A change to it is a change to SPEC.md, the one contract outside the kit; the interface between the host and the interpreter (wit/view.wit) is the kit’s own link
1. The prelude (pencere.*, in every page) The thin binding of what the host can do, and the loop of a page: the elements, Element:editor, the events and the replies, pencere.time, pencere.json, what a page remembers Only what needs the bridge’s inner places (the prelude’s own, out of a script’s reach), or must be there before the page starts
2. The library (require("@pencere/<name>")) Pure Luau, written on the public API of the prelude alone, and loaded when a page asks for it (sandbox/library) What an app could have written itself on the page API. It comes with the kit, at the kit’s version, with tests of its own
3. The app (require("./…")) The app’s own scripts The app’s policy
  • What a layer uses is below it, never above. A module of the library may require another (a part that stands by an editor requires @pencere/keys), and never an app’s script. The prelude requires no module of the library, and the host knows none.
  • A part goes in the layer furthest from the host that can hold it. The library comes before the prelude, and the prelude before the host. A part goes lower only for the reason the lower layer’s rule gives: into the prelude only what cannot be written on its public API, into the host only what a page cannot do.
  • The editor of text is the host’s, and stays so. Its engine is Rust, and its element is the prelude’s (Element:editor). What is around it is the library’s: the languages it reads (@pencere/languages), the reader of a line at a time that colours it (@pencere/syntax), and the parts of a page that stand by it.
  • A part goes into the library when it is built of the kit’s own ideas (elements, an editor and its language, the roles of the theme, events), its interface carries no app’s policy, and the kit can keep it right better than each app can on its own. How many apps use it today only breaks a tie. What it costs is weighed alike for every part: the interface it adds, what it asks of the prelude, the interface and the interpreter, and its size.

The library

A page gets its host’s library, at the kit’s version, as it gets the prelude. The sandbox gives a script that asks for a module its source (pencere_sandbox::library), from the crate itself. A module is mended without a new interpreter, and a page that asks for none pays nothing for it. The library does not count toward the size of a page’s scripts (4 MiB); the crate is not built when its modules come to more than 1 MiB together. An error at a line of a module says the module and its line (@pencere/syntax:12: …); one a module raises for what its caller gave it says the caller’s line. The language server of Luau reads the requires where a .luaurc gives the alias pencere the directory sandbox/library.

Module What it is
@pencere/syntax A language that colours an editor as it changes, read a line at a time from a stream, as CodeMirror’s StreamLanguage reads one
@pencere/languages The languages an editor reads, as CodeMirror’s language-data knows them: a description of each (its names, how a file in it is told), and the language (its colours for @pencere/syntax and what an editor is told of it) built when a page loads it
@pencere/fuzzy What a person types found in texts as fzf and VS Code find it: scored and ordered, a list at once or a slice a frame, the matched characters as parts of a rich text
@pencere/keys Keys a page writes ("cmd+shift+k") as a Mac writes them (⇧⌘K) or another platform (Ctrl+Shift+K), as key caps, and matched against a key event as the host matches a command’s
@pencere/charts Area charts on a canvas: what a chart is (its model, in the points of its box) painted by the kit’s smooth painter or a page’s own, its drawing kept while only the pointer moves
@pencere/markdown Markdown (CommonMark and GitHub’s extensions) read into a tree and drawn as elements: a document kept for a text that changes is read again only where it changed, and a long one is drawn a view at a time

SPEC.md, Section 2.6, says what each module does.

Images

A page shows pictures with image(src, fit) (in Lua, pencere.image(src):fit(…):tint(…):opacity(…)): src is the path of a file of the view’s own bundle, as its manifest names it, or a file beside the bundle: sha256: and the digest of one its program attached, file: and the handle of one the person gave the page; nothing else is reachable (no network, no file system). PNG, JPEG, SVG and PDF (:page(n) is the page of a PDF shown); at most 4096 × 4096 pixels an image and 64 MiB of pixels a view holds (a PNG or a JPEG is kept at the size it is drawn at, not the file’s; a large SVG or page of a PDF is drawn only where it is seen, so a page larger than 4096 pixels is sharp at every zoom and the pixels held are those of the screen; one that has no room at its size is drawn smaller until it has, and a picture scrolled out of view holds none); contain (all of it, centred) or cover (the box filled, the rest cut off); tint paints the image’s opacity in a colour, so that an icon of one colour follows the theme. The size is the element’s, and where it says a side only the image’s proportions give the other; where it says neither the image’s own size in pixels, a point to a pixel.

Give the size in points and send twice the pixels: a 64-pixel PNG shown at 32 points is sharp on a display with two pixels to the point, and shown at its own size (64 points) it is blurry. An SVG is drawn at the size it comes to on the display and needs nothing of the kind.

The sandbox crate does the decoding, so that every terminal takes the same formats and the same limits. A terminal gives it the files (Assets, a path to bytes: its store of the bundle), makes one Images for a view, and uses three of its calls:

  • Measure::image of the engine is Images::size: the size of an image in pixels, None while it is not known. The first ask starts the decoding on a thread of its own; the layout goes on without it. It is asked with the page of the file (Measure::image(src, page): from 1, and 1 for a file that has no pages, which is everything but a PDF).
  • Paint::Image of the draw list is drawn with Images::picture(&picture): premultiplied RGBA with an id to key the texture by, and Bitmap::part, what of the whole image the pixels hold (all of it for a PNG, a JPEG or a small SVG; for a large SVG or a page of a PDF the part that is seen, Picture::shown, and a margin: the picture’s rectangle is drawn with Bitmap::crop_of(&picture) for the texture’s crop, which reaches past the pixels only where the clip cuts the rectangle). An SVG or a page of a PDF is drawn at the size asked, again for every other, and a large one in steps of it. A terminal that draws the pictures of its draw list asks for no other (Images::bitmap is the whole image at a size).
  • The wake given to Images::new is called when something arrived. The terminal then calls Images::poll: relayout says a size is known and the page is to be laid out again (once), redraw that pixels are there, and diagnostics why an image was refused. Nothing is polled and nothing woken at rest.

A terminal that opens lua answers Assets::read for a sha256: name from the files the program attached to the view (Session::attached of the host crate, or AttachedFiles::get from a thread that has no session: Session::attached_files gives one table for the life of the session, which the view’s end empties) and for a file: name from its own table of the handles it made, never from a path, and calls Images::forget with the names the program let go of (Action::ForgetFiles). The panels a page asks for are the drive’s Host::panel, which the terminal hands the session (Session::module_pick, module_save) before it shows one.

Versions

The kit’s version is the one a view names in its open (specification Sections 5.4 and 5.5): lua 0.1, the page API whose pencere.version is the string "0.1". While the specification is a draft the versions of lua are 0.x: a change an existing view can notice moves the minor number (0.2 after 0.1), and an addition does not. A terminal opens one version, and a program written for another is not opened and says so in a sentence. (The rules the versions follow from the first general release on are in SPEC.md, Section 1.) The interface pencere:view has no version of the kit’s: it is the link between the interpreter and the sandbox, and a change of it is a new build of the interpreter (make luau).

From the first general release on:

  • An addition that no existing view can notice is a new minor version (1.1): a new element or a new colour role in the page API. A host opens every published minor version of a major.
  • A change to something a view already uses is a new major version (2.0), and comes only when a function has to mean something else and a new name cannot do it. A host opens the newest major and the one before it; an older view is refused in words that name both sides.
  • The interpreter is the terminal’s, so a new element or a new role is an addition for a script. What breaks a script is a function of the page API that means something else.
  • The library is a part of the page API. A new module, or a new function of a module, is an addition; a function of a module that means something else is a change.

Building

make check        # the gate: needs no toolchain for WebAssembly
make check-heavy  # what runs the interpreter against the sandbox, the drive and the examples
make luau         # rebuilds the interpreter in Docker (pinned wasi-sdk and Luau); `make check` fails when it is due

make luau builds the tools that make the component (kit/guest) with rustup’s stable toolchain.

This page is kit/README.md of the repository.