Repository navigation
Releases
crates-v0.4.1
pencere-editor
Changed
- The decorations in a range are found from near it, and folded regions are matched to their folds by
line, instead of going through all that come before: an editor with thousands of decorations took
longer to draw the further down its text it was scrolled.
pencere-sandbox
Added
figure_key: whatdraw_figurewould give a figure, its bitmap'sidand size, without drawing it,
so that a host that holds the pixels does not draw them again with each frame. A canvas that fills a
good part of a screen takes tens of milliseconds to draw.
Released with no change of their own: pencere-wire, pencere-host, pencere-view, pencere, pencere-drive.
sdk-typescript-v0.4.0
Changed
-
The kinds are
0.1.WEB_VERSIONis"0.1", and aluaview is written at"0.1". While
the specification is a draft the versions ofluaandwebare0.x: a change an existing view
can notice moves the minor number (0.2after0.1), an addition does not, and a host opens one
version. A program whose version the host does not open is not opened, and says so in a sentence
that names both sides. The sentenceserveprints then ends withupdate the older of the two.
Breaking:hasFilestakes the kind alone: aluaview has files at any version, a page has
none. -
A view that fails is shown again, not the end of
serve. The host'sclosedwith
reasonerrorandcodeview(a page that trapped, went over a limit or made an error) no
longer ends the program:serveforgets the view and asks for it again with a newhello,
silently and with the terminal still the program's, so that the page starts from the beginning and
asks the program for where it was. It does so once inretryWindow(60 000 ms by default); a
second failure inside it, and a host that does not answer, refuses the view or opens none of the
program's kinds, endserveas before, with the failure the view fell with (byerror). An
error with anothercode, and a failure while a reopening or a closing is under way, are as they
were.
Added
- A Lua page's
printandwarnreach the program (specification §9.2). The router serves the
reserved methodpencere.logitself, never throughcalls: it answers{}at once and gives the
line to the newServeOptions.log(andRouterHandlers.logofcreateRouter) as aLogLine,
which has alevel,"warn"forwarnand"info"for anything else, and atext, in which
every control character but the tab and the line feed is written as\xNN, since the page is
untrusted. There is no default: nothing is printed while the view is up, and withoutlogthe
line is dropped (the page is answered{}all the same). Alogthat throws loses the line and
nothing more. - Names that begin with
pencere.are the protocol's.serve,serveWithandcreateRouter
refuse acallsor atopicswith such a key,pencere.logincluded, with aTypeErrorthat
names the key, before any view is asked for. ServeOptions.retryWindow: how long a view that fell is left alone before it is shown again.- Files beside the view's bundle (specification §8.8 to §8.10), for a view opened at
lua0.1:
ViewControl.attach(bytes)adds a file for the view to draw and resolves
with the name it draws it by (sha256:and the digest) once the host holds it, sending nothing
for a file the view has attached already or the host still holds;detach,read(handle, offset, length)of a file the person gave andwrite(handle, offset, bytes, end)to the place the person
chose in the Save panel are the messages themselves. A refusal is aFileErrorwith the host's
code;MAX_PIECEis the most a read asks for or a write carries. - The host's folder (specification §8.11), for a host that lists
stagein itswelcome:
WelcomeOffer.stagesays where it is.ViewControl.stageFolder()proves it (an absolute path; a
directory of the program's own user that the group and others cannot use; amarkerfile, opened
without following a link, that holds exactly the token) and returns aStageFolderwhose
openPipe(name, "read" | "write")opens a pipe the host named, without following a link and without
blocking, if it is a FIFO of the program's user.ViewControl.stage(handle, offset)and
ViewControl.fetch(handle, size, offset)send the file of a handle, or the program's file for the
place of a handle, through that pipe, and answer aTransfer: thepipeto open,donewith where
the file ended,unstage()to take it back. AFileErrorcarriesatwith therouteof a
fetch. The bytes cross no message; what the program asks and what it is told stay messages.
Removed
- The
wasmkind of view.ViewKindis"lua" | "web",VIEW_KINDSandENTRY_TYPESlose
wasm, andhasFilesis true forluaonly. AViewSpecwithkind: "wasm"
no longer type-checks.
crates-v0.4.0
pencere-wire
Added
- The host's folder on the program's machine (specification §8.11): the feature
FEATURE_STAGE
andmessage::StageDir(thestageof awelcome, which checks that a path is absolute and a
token 32 hex digits), the program's messagesStage,FetchandUnstage, and the host's answers
transfer_pipe,transfer_sent,transfer_savedandtransfer_failedforstagedandfetched.
The kinds are JSON and the control keys are the same. bundle::media_type_of: the media type a file of a bundle is given by its extension where its
program says none (a script of a page of the kit isLUA_MEDIA_TYPE). It was the program
library's; it is here so that a host that reads a view's files from a directory (a test's) gives
them the type the program would.link: which links a view may ask its host to open (is_openable,MAX_LINK; specification
§9.7, §9.8), a web page'slinkmessage or the link of a kit view's reply. The rule was the host
crate's; it is here so that the kit's sandbox and the host hold both kinds of view to one copy.- The messages of files beside a bundle (specification §8.8 to §8.10): the control keys
h,o,
endande(frame::FileParams,Message::handle,offset,end,error_code), the
payloadsmessage::Attach,DetachandRead, and the host's answersneed_refusing(aneed
withrefused) andwrote.bundle::Receiving::from_sizeswaits for files that are not a
manifest's, andgive_uplets go of those that did not come.
Changed
message::welcome_offertakesFeatures(the names, and thestagethat goes with the
feature of that name) where it took the list of names.frame::Outgoinghasfile, the keys of the messages of files;FileParams::NONEfor any
other message.bundle::Received::Failedsays how the file failed (Mismatch).
Removed
bundle::WASM_MEDIA_TYPE: thewasmkind of view is gone (specification §5.5), so no entry has
that type.media_type_ofstill gives a.wasmfile the typeapplication/wasm, for a page that
carries a WebAssembly module of its own.
pencere-host
Added
- The host's folder on the program's machine (specification §8.11): the bytes of a file may cross
through a pipe in a folder the terminal keeps there, instead of indataandwritemessages.
Session::offer_stagesays where the folder is and the token of itsmarkerfile, and lists
stagein thefeaturesof thewelcomes (StageDir). The program'sstageandfetchare
Action::StageFileandAction::FetchFile(the session names the pipe, from the terminal's
randomness), answered bySession::pipe_readyand thenSession::stagedorSession::fetched
(StageError,FetchError);unstageand the end of the view areAction::Unstage, with
Action::AbortWritefor the place afetchhad begun to write. At mostMAX_OPEN_TRANSFERS(2)
are out at once, and the third isbusy. - Files beside the bundle (specification §8.8 to §8.10), for a view opened at
lua0.1
(has_files). A program'sattachadds files to its view, verified as
the files of a bundle are and held to 8 MiB a file and 1024 files or 64 MiB a view; it is
answered with aneedthat lists what is missing and what isrefused, and once more when the
last of them has come.Session::attachedgives the bytes behind asha256:name
(attached_digest), anddetachlets them go (Action::ForgetFiles).grant_fileand
grant_savemake a handle of a file the person gave or of the place the person chose to save in;
the program'sreadisAction::ReadFile, answered withfile_read, and itswrites are
Action::WriteFile, answered withfile_written, withAction::AbortWritefor a save that is
not finished, also when the view ends.module_pickandmodule_saveask for the Open and the
Save panel (Action::Pick,Action::Save, one at a time,panel_closed). Thedatathat
answers a read is anAction::WriteView, held and dropped with what the view says. Session::attached_filesgives anAttachedFiles, a clone-able, thread-safe table of the files
the view that runs has attached, withgetby thesha256:name asSession::attachedhas it.
A terminal that reads a picture on another thread than the one that feeds the session no longer
has to copy what it was told about: a file is in the table once the session holds it, and gone with its
detachand when the view ends, by whatever path.Session::offer_dismiss(false)makes a host that does not close a view at the program's request:
dismissis left out of thefeaturesof itswelcomes, and adismissthat comes all the same
is ignored. (The stand-in terminal's--no-dismiss.)Session::module_link(specification §9.8): a view the terminal draws itself asks to open a
link in thelinkof its reply, not in a message, and the terminal hands it here. It is held to
the rule of a page'slink(§9.7) and put to the person the same way (Action::OpenLink,
answered withlink_decision, as many questions open at once as for a page); any other link, or
one with no such view open, is dropped and counted as ignored. The view is never answered.
Changed
-
The kinds are
0.1.WEB_BRIDGE_VERSIONis"0.1". While the specification is a draft the
versions ofluaandwebare0.x: a change an existing view can notice moves the minor number
(0.2after0.1), an addition does not, and a host opens one version. A program whose version
the host does not open is not opened, and says so in a sentence that names both sides.
Breaking:has_filestakes the kind alone (has_files(ViewKind::Lua)): aluaview has
files beside its bundle at any version, a page has none. -
sandbox::is_openable_linkispencere_wire::link::is_openable, the one copy of the rule the
kit's sandbox holds a kit view's links to as well.
Removed
- The
wasmkind of view.ViewKind::Wasmis gone,bundle::WASM_MEDIA_TYPEwith it, and a
hellothat listswasmfinds the kind unknown, as it does any name that is not in the table
(specification §5.5).has_filesis true forluaonly. The kit has one kind of
view of its own, a Lua script.
pencere-view
The engine of version 0.1 of the kit (pencere:view@0.1.0, lua 0.1).
Added
Menu::pastes_for(event)andMenu::for_event(event): whether a Paste line of a menu asked for in the
reply toeventis on (only a press of the right button, in an editor, a gutter or elsewhere), and the
menu with its Paste lines off, in their places, where it is not.- Files beside the bundle (specification §8.8 to §8.10):
Event::Filessays how the person gave
them (FileSource: a drop, a paste, a pick in the Open panel) and each file'sFileEntry(the
handle, the name, the size, the media type, the path where the host knows the program reads the
same files);Event::FilesOverandEvent::FilesLeftwhile files are dragged over the page;
Event::Savingfor the place the person chose in the Save panel;Reply::panel(Panel::Pick,
Panel::Save), shown only for a reply to what the person did (Panel::follows). Breaking:
Event::Fileshassourceandentries. - A press that opens a menu (
Pressing::Context,gestures = { ["right+press"] = "context" }):
outside every selection one caret is put there, inside one the selections stay; the press is told
the page as any, andPlacehasinside(the place was in a selection or at a caret before the
press moved the caret) andversion. - Breaking:
Placehasinsideandversion, andMenuEntryhasPaste(a match that names
every entry, a struct literal ofPlace, must say them). - Breaking: the page's key action that deletes to the start or the end of the line is
KeyAction::DeleteToLineStartandDeleteToLineEnd(they wereToLineStartandToLineEnd), as the
commands are;ColumnEvents::menuisColumnEvents::context, andGutterKindhasContext, the
press that opens a menu. EditCommand::CopyandEditCommand::Cut, as the editor's keys do them. There is no command that
pastes: a page cannot read the pasteboard.MenuEntry::Paste { title, enabled, editor }is a
line the host performs itself when it is picked; it has no keys, so that no key picks it.copy_key(key, mods): whether a key is the system's own copy or cut (⌘C, ⌘X and no other
modifier). A host that keeps programs from its pasteboard writes what a key copies only then;
Panel::followsis the rule for a menu as well as a panel.
Fixed
-
A shortcut of a character that has no case (
?,/, a digit) is done whether shift typed it or
not:?is shift and/on a US keyboard and/is shift and 7 on a Turkish one, and a command
bound to either was never done. Keys that name shift still want it, and a letter still tells its
case.Field::coveredsays that something the page draws after a field lies over it (a popover,
a dialog), so that a host, which draws its fields above the page, can leave it unshown. -
A pick is of the menu the host showed. A host shows one menu at a time and does not show one
asked for while another is up, so the page's latest menu is not always the one the person picked
from.Menuhas aserial(the page's number for it) andEvent::MenuPickis
MenuPick { serial, index }: the host hands back the number of the menu it showed. Breaking:
aMenuliteral says itsserial, and a match onEvent::MenuPick(index)names both fields. -
An inline widget keeps room outside its box, between it and the characters beside it
(WidgetGroup::margin, 3 points;Widget::margin_left/margin_rightsay another): the box of a
hint stood against the character after it. -
A gap kept open for the page (
Mark::Zone) is as tall as its `heig...
cli-v0.4.0
Changed
-
The kinds are
0.1. A Lua app is shown atlua0.1,pencere.versionis the string
"0.1", and a terminal that opensluaat another version is told so on standard error before
the app's fallback runs:pencere: this program is written for lua 0.1; this terminal opens lua 0.2; update the older of the two. While the specification is a draft the versions ofluaand
webare0.x: a change an existing view can notice moves the minor number (0.2after0.1),
an addition does not, and a host opens one version. A program whose version the host does not open
is not opened, and says so in a sentence that names both sides. -
pencere testcounts places as a script does:page:select,page:caret_toand the
anchorandheadofpage:editor(name).selectionsare bytes of the text from 1, as
layout.editor_textand an editor's events say them. -
A page that fails is shown again, and the app goes on.
pencere.serveshows a
page that made an error, trapped or went over a limit once more from the start, silently, once in
a minute (the page asks the app for where it was);ended = "error"now means that was given up
on, because the failure came twice inside the minute or the terminal did not bring the view back. -
A Lua app is shown at
lua0.1alone. The kit has one version of the page API while the
specification is a draft. A terminal that opens another finds no version in common.
Added
- What a page prints is in the app's log. A page's
printandwarnare written where the
app's ownprintgoes (the terminal,--log FILE,.pencere/logunderpencere dev), behind
view:(andview: warning:forwarn) so that the two are told apart. A failure of
pencere testshows them with what the program printed. A control character in a line is written
as\xNN. pencere.serverefuses acallsortopicsname that begins withpencere.: the names are the
protocol's.pencere.files.receivetakes thepathand thesizethe page was handed with a file, in its
options: where the page passes them on, the file is copied from there rather than read through
the terminal, which on the person's machine is as fast as the disk. Thefiles-luaexample's page
passes them on.
Fixed
-
pencere upgradeworks in a folder only the person can enter. It downloaded the release and
its sums intopencere-upgrade-<pid>in the temporary directory, made if it was not there, so that
a folder (or a link) another user had put there beforehand was written to and read back from. The
folder is now made bymkdtemp: a name made up by the system, never one that can be made beforehand,
new, with the mode0700; the temporary directory itself is made first whenTMPDIRnames a folder
that is not there. -
pencere devon a Cargo package leaves what its tools keep alone. It read every file of the
project four times a second, and a directory it did not know by name, such as a.cacheholding a
checkout and its build, was read with the rest: a quarter of a core for as long as the pane was
open. What is hidden, andtargetandnode_modulesat any depth, are now left out, so a save
there no longer builds and runs the program again either. -
pencere devis left with ⌃C, as it says, and ends with 0: while the program runs, while Cargo
builds it and while a change is waited for. It ended with the program's 130, or was killed by the
signal while it waited, somake devreported an error on every leaving. -
The calls and the subscriptions of a view start in the order the view made them. Each came in on a
thread of its own and raced the others to the app's loop, so that two edits the view sent one
after the other could be begun the other way round; they are now handed to the loop as the view
sends them (the program library's deferred handlers), and none waits for another's answer. -
page:wait_forinpencere testgoes on waiting when the page's view is over (the program closed
it, showed another, lent the terminal), as what it waits for may be what the program does next:
a program goes on after itsserveon its own time, and the wait raised the view's end before
the program had written what the test looked for. If the condition never comes the failure says
the view is over.
Changed
- The runner shows the views of the kit's page API at
lua0.1. pencere.handoffis thepencerelibrary's hand-off: the sameserveshows the view again
instead of a new one being started, the app's loop is no longer the one that waits for the view
to give the terminal back, and a hangup while the program has the terminal is passed on to it
and endsserveonce it has ended. A change to the view's files underpencere devwhile the
program has the terminal is the view that comes back.
Added
-
Files with the view (
pencere.files, a terminal that openslua0.1):attachand
attach_datagive the view a file to draw and return its name,detachlets it go,receive
takes a file the person gave the page by its handle (through a.pencere-partthat is deleted when
it is not finished),sendwrites a file to the place the person chose in the Save panel, and
safe_namemakes the person's name one a path can take. Each waits without holding the loop; a
failure is{ code =, message = }. Apps offerlua0.1.pencere testplays the
person's files:give_files,drag_files_over,drag_files_away,panel,choose_files,
choose_place, andtest.open{ attach = { bytes } }. The examplefiles-luashows them. -
pencere testsays how the host draws its terminal's cursor and selection (terminal_look,draws
oftest.open;page:set_terminal_look(table)changes it, and the page is told). -
pencere testcandwell(id, x, y)(the pointer rests over a word of an editor that hears of it,
as long as it takes to be told),hold("cmd"),release()andclick_holding(x, y, "cmd")(the modifiers a person holds) and say where a range the page named is (anchor_rect(editor, name)). -
PENCERE_CALL_MSforpencere test. The time, in milliseconds, a call of the page may take
in a test: the floor's 250 ms (the least a host gives a page) unless it is set. The limit is the wall
clock's, and a test of what a page shows and does should not fail for how quick a busy runner is;
a value that is not a whole number above zero is not read. -
pencere test. Runs the tests of an app, written in Lua (test/**/*_test.lua,
require("pencere.test")), against the page of the app under a host with no screen: its page
engine, editors and interpreter, with a clock the test moves. The page's program is a stand-in
made of calls the test answers, the app's own program (Lua, in the test's process, in an
environment of its own; a Cargo package, built once and run on a pty) or any program on a pty.
Things are found by their words and their role, the test looks withexpect, and a failure says
what the page showed and keeps its picture, its words and its messages. The files run on worker
processes (--jobs), a test is cut off at its timeout, and the report is pretty, TAP or JUnit.
The runner of tests,pencere-test, is a program of its own and a second file of the release:
the command runs the one beside it, or the release's of the same version (checked against its
SHA256SUMS, kept in the cache), or the onePENCERE_TESTnames.pencere newmakes the first
test (Lua and Rust projects; TypeScript with--page lua), and a simple-form app does not pack
test/(a program module of that form cannot live in a directory of that name). -
pencere new --lang ts --page lua. A TypeScript project whose view is a page of the kit,
the Lua project's page, with its first test. -
pencere upgrade. Replaces the command with the newest release of it, asinstall.shwould
install it: the release's file for this machine, checked against the release'sSHA256SUMS, put
in the place of the running file in one rename.--checkonly says whether there is a newer one,
--version X.Y.Ztakes that one (an older one too). A command Cargo installed is left to Cargo,
with the line that replaces it. -
pencere devandpencere buildfor a program in Rust. In a Cargo package,pencere dev
builds the program with Cargo and runs it in the pane: a change to the page or a picture shows
the view again without ending it (thepencerelibrary reads them from the project), and a
change to anything else builds and runs it again; the program's standard error goes to the log.
pencere buildbuilds it withcargo build --release(--targetpassed on, with what to install
when the toolchain lacks it) and copies it todist/<name>. -
pencere new --lang rustmakes a project whose build script carriessrc/view/and
src/assets/into the program (pencere::app!()), so the page can be split into files as a Lua
app's is. It needs thepencerecrate that hasApp: the release that ships this command sets
the version of the crate in the template to it.
crates-v0.3.1
pencere-wire
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
pencere-host
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
pencere-view
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
pencere-sandbox
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
pencere-page
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
pencere
Fixed
- 0.3.0 never reached crates.io: it was tagged and drafted, and the release workflow then skipped
its publishing. This is the same code, released.
cli-v0.2.2
Fixed
- 0.2.1 was never published: the release workflow stopped before it, because the crates it is
released after were not published. This is the same command, built with the crates 0.3.1.
sdk-typescript-v0.2.0
Added
.luauistext/x-luain a bundle made from a directory, as.luais: the scripts a Lua
view requires, by Luau's rules, are those of its bundle that are of that type.- A host that opens a kind of the program's in other versions is told in words. The
no-viewresult with the reasonno-common-viewcarries amessagethat names both sides, andservewrites it to standard error aspencere: …before thefallbackruns (specification §5.2, §5.3).WelcomeOffer.opensis the host's list;noVersionSentencemakes the sentence. Colorsof a page'scontexthascursor,selectionandansi(§9.5).- Deno and Bun, beside Node (20 and later): the same code on all three. What is Node's — the
tty's modes, the signals, the files,Buffer— sits behind a small layer that each runtime
answers in its own way; the rule of §4.9 is the same on all three (stty, ISIG on). Deno needs
--allow-read --allow-run; a program compiled withdeno compileworks, and thecontainers
example has the task. On Bun 1.0 afilterfinds no host (its stream for/dev/ttydelivers
nothing). @pencere/sdk/page: the bridge of a page (§9.4) as a browser ES module with no
dependency —call(withonProgressand anAbortSignalthat sendscancel),subscribe
(withonPush,onErrorandonEnd),onContextandcontext(),close,openLink, and
createBridgefor a channel of your own.bundleFromDirectorytakes afilesoption for the
module and anything else that is not in the directory.createRouter: the program's dispatch of the view'scall,subscribeandcancel
to the handlers, with the errors mapped asservemaps them, without a terminal, for tests and
development harnesses.serveuses it.- ⌃Z. SIGTSTP closes the view (
dismiss, orbyefor a host that does not list it), gives the
screen and the modes back, and stops the program; when it is continued the program takes the
modes again and asks for the view anew. Before, ⌃Z left the tty raw in the shell.
Fixed
- ⌃C ends the program every time, on Node.
sttyran with the tty as its standard input,
and Node turnsO_NONBLOCKoff on a child's standard streams: the flag belongs to the open
file, so the program's own reads of its input began to wait. ⌃C flushes the tty's input
(Appendix B), and when it emptied the queue between the moment the event loop learned of bytes
and its read, the read waited for a byte that never came; the SIGINT was never heard, nobye
went out and the program had to be killed.sttynow gets the tty as descriptor 3, which leaves
the flag alone. - A process that exits with its view up reads the host's last word before it leaves. The
exithandler saidbye, threw away what the tty held and restored the modes at once, so the
host'sclosedlanded in the shell as typed text; it now reads the tty itself, with no event
loop, until the answer to thebyeorbyeTimeout, as the signal path waits (§10.3). - A signal, or an abort, before the host has answered the
hellothrows away what the host and
the terminal still write: it waits for the terminal's answer toCSI c(byeTimeoutat most)
and empties the input. A latewelcomeand the reply no longer reach the shell (§5.3). The same
holds for a process that exits in that time. servechecks the list of views once, not twice.- The 1 MiB limit of a message the program writes to its view is counted as the host counts it
(specification §9.3): on the text before the escapes of the wire, in bytes. A call answered with
nearly 1 MiB of Turkish text went through the wire as 3 MiB of\uXXXXand was refused as too
long; it goes through now.
Changed
- Breaking:
FEATURE_BUNDLEis gone. Thewelcomeno longer listsbundle(§8.1). A message nested 128 levels deep or more is ignored (§4.5), as is one with anidabove 2^53 - 1. - Breaking: one protocol, with no MCP in it.
serveno longer takes an MCP server and a
program is no longer an MCP server on stdio: it lists the views it can show (views: kind,
versions, bundle and, for a page, itsaccess), answers the view's calls (calls), feeds its
subscriptions (topics) and learns how the run ended from the result (ServeResult:closed
with who ended it, orno-viewwith why).@modelcontextprotocol/*,ext-appsandzodare no
dependencies any more, and the bundle has nometa. The wire of the draft changed in place, and
there is no support for the previous draft.- The six messages. The view and the program talk in
call/response,subscribe/push,
cancelandprogress(specification §9); a handler gets aCallContext(signal,
progress) or aSubscription(push,signal), and ends in error with aViewError. A page
reaches the host through the bridge of §9.4, whichservedoes not read. - Kinds with versions.
hellolistsviews, the kinds the program can show with the
versions of their interface, in its order of preference; thewelcomeis read for the ones the
host opens, and a host that opens none of them endsserveat once with theno-viewreason
no-common-viewinstead of after the wait for an answer.opennames theviewand its
version, theprogram,title,iconsand a page'saccess. ViewControl.reopentakesviewswhere it took a bundle.- After a
byethe program waits for the host'sclosed, reading and throwing away the input,
so that nothing the host wrote is left in the tty for whatever reads it next
(specification §10.3;byeTimeout). A process that exits reads the tty itself. - The
closedof a view the host draws itself that failed carriesmessage, the words it
failed with (NoView.message,ServeResult.message, specification §8.8)..luafiles are
served astext/x-lua. - A message the host writes into the program's input may be up to 6 MiB on the wire (
LIMITS,
specification §4.6): the 1 MiB limit of a view's message is counted before the host escapes it,
and the escapes can make it six times as long.
- The six messages. The view and the program talk in
Added
- Views of the kinds
wasmandlua, which the terminal draws itself (specification §8.8), beside
web:ViewSpec.versionssays which versions of the kit's interface they are written against,
andViewSpec.bundlemay be a function of the version that was agreed.
crates-v0.2.0
pencere-wire
Added
- The crate itself, and its first release: the part of the host crate that reads and writes bytes
and does not decide what to do with them moves here, so that a program and a terminal share one
copy of the wire. It holdsframe,json,base64, the payloads ofmessage, the manifest,
digests and the verification of files ofbundle, and the six view messages of a program and its
view (messages), which a program and the module of its view in the terminal's sandbox both use.
bundle::Manifest::missingandis_heldtake a closure that says whether a digest is held, for
the store (the host crate'sStore) stays the terminal's. The pencere crates are released
together at one version, which began at 0.2.0: there is no 0.1.0 of this one. - A message is read as the specification says.
Message::parserefuses anidabove 2^53 - 1
(Refused::NoId), reads a number whose value is a whole number (1.0,1e3) as anid, and
refuses a text nested 128 levels deep or more;json::from_objectreads nothing that deep.
json::MAX_DEPTHandjson::too_deepgive the nesting at which no receiver takes a JSON text
(specification §4.5), andmessages::MAX_IDandMessage::has_usable_idthe range of anid: 1
to 2^53 - 1 (§9.2).message::welcome_offertakes theopensof thewelcome(§5.2).
pencere-host
Added
opensin thewelcome(specification §5.2): a kind the program listed that the host opens, but at none of the versions the program speaks, is named with the versions the host does open, so that the program can say which would have served.message::welcome_offertakes it.Action::WriteView,Session::backlogandsession::MAX_BACKLOG(§4.8). What a view says reaches the terminal asAction::WriteView(a terminal writes it asAction::Write, which stays the host's own words). Before it holds one, the terminal asksbacklog(waiting)with the bytes ofWriteViewthat wait for the tty, that one included; it answersfalsefor more than 16 MiB, closes the view witherrorview, and the terminal holds nothing of the view's words. A terminal that matchesActionmust handle the new variant: an arm that ignores what it does not know drops the view's words.cursorin a web page'scontext.colors, afteraccent(made up as the accent):Theme::cursorandRoles::cursor(§9.5, §11.2).selectionandansiin a web page'scontext.colors.theme::Themegainsselection
(made up as a third of the way from the background to the accent) andansi, the sixteen colours
of the palette (made up as xterm's:theme::XTERM_ANSI);Rolescarries both. The page is told
them afterinfo, the palette as an array of sixteen#rrggbbstrings (specification §9.5,
§11.2).
Changed
-
Breaking:
Config::bundleis gone and thewelcomeno longer listsbundleinfeatures. Every view arrives as a bundle, so there was nothing to ask;featuresis["dismiss"]. -
A message nested 128 levels deep or more is dropped in either direction (§4.5, §9.3), as is one that is not a complete JSON object; a
hello,open,byeordismissthat deep is not read either. -
The default policy of a page has
form-action 'none'(§12.1): a form could otherwise submit the page to any address. -
Breaking: the crate is
pencere-host(the library ispencere_host), and this is its first
release under that name, at the version the pencere crates share. The namepencereis the
program library's, the one a program's author adds to a project; nobody used the crate that was
published under it (0.1.0, below). -
The wire moved out to
pencere-wire, so that a program and a terminal share one copy of it:
frame,json,base64,messageand the manifest, digests and verification of files of
bundle. They are re-exported, sopencere_host::frameis still where a terminal finds them. What
stays here is what a terminal decides:session,sandbox,theme,icon,tokenand the
bundle::Storeit keeps files in.Manifest::missingandManifest::is_heldtake a closure that
says whether a digest is held, instead of a store;Manifest::check,RawBundle,RawFile,
message::probe_token,message::OpenBodyandjson::Objectare public, for the crate the
session lives in is no longer the one that defines them. -
Breaking: one protocol, with no MCP in it. Every kind of view speaks the same six view
messages (specification §9), and the host only carries them; awebpage additionally exchanges
the bridge messagescontext,closeandlinkwith the host (§9.4 to §9.7). The wire of the
draft changed in place, and there is no support for the previous draft.- Gone: the MCP client toward the program and the MCP Apps host toward the view (
jsonrpc,
session::mcp,session::view,ToolCall,ViewSource,UiMeta,Theme::variables,
Action::ViewLog,Config::logging), thetoolof anopen,bundle.meta,serverInfoand
resources/read: a view is always a bundle. So is the teardown round trip (State::Closing,
Session::requests_timed_out): closing a view is instant for every kind of view
(specification §10.2). - Kinds with versions.
hello.viewsandwelcome.viewslist the kinds of view with the
versions of their interface (message::ViewOffer;Config::viewsis aVec<Offer>,webat
WEB_BRIDGE_VERSIONby default). Thewelcomelists the kinds the host opens, at the
versions both speak, in the program's order.opennames theviewand itsversion, the
programandtitle,iconsand, for a page, theaccessit asks to reach
(sandbox::Access: connect, resources, frames, base, permissions); the answer to the person
and the content security policy are built from it as before. The host only eliminates: with no
kind in common it still answers, withviews: [], so that the program does not wait, and a
hellothat lists no kind is not answered. Anopenwithout aview, aversionor a
bundle, or whose entry is not of the kind's type (text/htmlforweb,application/wasmfor
wasm,text/x-luaforlua), is refused withmanifest; one of a kind or a version the
welcomedid not offer, withunsupported; and awasmorluaentry over
Config::native_entry_limit, withlimit. Thewelcomeof a restart (specification §10.7)
offers every kind the host opens, in the order ofConfig::views. - The page.
ViewStartcarries the page's firstcontextmessage, which the terminal
delivers when the page has loaded;Session::set_localeandSession::set_reduce_motionjoin
set_sizeandset_themein what a latercontexttells it. A page's{"context":{}}is
answered with the current one. Config::wasm_entry_limitisnative_entry_limit: it holds the entry of aluaview too.- A believed
byeis answered (specification §10.3): the host writes aclosedwithreset to
thebye's id andreasonprogram, the last frame it writes for the view and the only one
it writes for a program that has said it ended. A program that reads up to it has read
everything the host wrote before, so nothing the host had in flight when it learned of the
byeis left in the tty's queue for whatever reads the tty next.
- Gone: the MCP client toward the program and the MCP Apps host toward the view (
-
An
accessis bounded and read without a tree (specification §6.3). A list of origins has
at mostsandbox::MAX_ORIGINS_PER_LIST(32) entries and the lists at mostMAX_ORIGINS(64)
between them, counted as written whether or not an entry is an origin; anopenover a bound is
refused withlimit, whichAccess::from_json(new;Access::from_valuestays) reports as
AccessError::Limit.AccessErroris an enum now (Malformed,Limit), where it was a unit
struct. The text is read one entry at a time, a member the crate does not know is ignored, and
a fault of shape anywhere in it isMalformedeven when the bound was gone over first.
Csp,Grant::allow_domainandGrant::withinkeep their origins in a set beside the list, so
they are linear in the number of origins. -
An
openthat is malformed and too big is refused as malformed (§6.4 putsmanifestbefore
limit): the entry's type, the shape of theaccessand the shape of the manifest are all
checked before the bundle's limits, the native entry limit and the bound of theaccess. -
DEFAULT_POLICYlets a page read its own bundle.connect-srcandfont-srchave'self'
(a page'sfetch('./data.json')works without being allowed anything), and the policy names
frame-src 'none',object-src 'none'andbase-uri 'self', so that what a person allows adds
those origins to it and changes nothing else (§12.1). The network is as closed as it was. -
View messages. The 1 MiB limit (
session::MAX_VIEW_MESSAGE) is counted on the text before
the escapes of the wire, not on the escaped form, in both directions (a page's text as posted, a
program's payload with each escape counted as the character it stands for,
json::unescaped_len), and the message limit toward the program is now 6 MiB (Direction::ToProgram, specification §4.6) so that a message within 1 MiB is always
written, whatever its escapes make of its size;Diagnostics::unwritableno longer counts it.
A page's message (view_message) or a component's (module_message) over the limit ends the
view as a failure of the view (closedwithreasonerror,codeview), where it was
dropped and the page waited for ever; the program's own message over the limit is still dropped.
JSON whitespace between tokens is accepted and left out when the message is written
(json::to_frame). Amsgtoward a view the terminal draws itself, and that view's own messages,
have to be complete JSON objects, ...
cli-v0.2.0
Added
- The
pencerecommand, released for the first time. It makes apps for
pencere: programs that show a view in the pane of the
terminal they run in. An app is a Lua program and a page;pencere buildmakes one executable of
it, which runs on any machine of its kind with nothing installed, and the same executable, with
no app inside it, ispencere.pencere new <name> [--lang lua|ts|rust] [--page lua|web]starts a project: Lua with a page of
the kit or with a web page (HTML and JavaScript, no npm and no build step), TypeScript or Rust.
Every project has one layout: the program insrc/program/, the page insrc/view/and the
pictures insrc/assets/; builds go todist/, and nothing generated is undersrc/.pencere devruns the app in this pane and runs it again when a script changes; when the page
or a picture changes, the view is closed and shown again without ending the program.pencere buildmakesdist/<name>, one file.--targetmakes it for another machine (Apple
silicon and Intel Macs, Linux on arm64 and x86_64, static, so on any distribution) without the
toolchain of that machine; a Mac's executable is signed ad hoc.--web DIRpacks a page from
the directory a tool built it into (a React page, say),--namenames the executable and the
app in its own messages,-osays where it goes.- A built app runs by itself, and
app --log FILEsends what it prints, and its errors, to a
file, since the terminal is under the view while it is up.
- A page of the kit can be several files. The page,
src/view/page.lua, mayrequirethe
other.luaand.luaufiles ofsrc/view/by Luau's own rules (require("./screens/logs"),
require("../parts/table"), a directory with aninit.luau), and nothing outside the view: the
scripts go into the view's bundle with the paths the page writes them by, typed as scripts, in
pencere devand in a built app alike.pencere devshows the view again when one of them
changes, andpencere buildrefuses one that does not compile. - How to get it. One line installs the newest release in
~/.local/bin
(curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh: see the
README), after checking the file against theSHA256SUMSof its release. Each release carries
the four executables, namedpencere-<version>-<target>, with their sums; they are built by the
release workflow, which attests where each was built (gh attestation verify).
cargo install --git https://github.com/bateri/pencere pencere-cli --lockedbuilds it from the
source. - What an app can do, with
require("pencere")and nothing else to install:serveshows the
view (a page of the kit, a web page with anaccessfor what it may reach, or both in the order
the app prefers) and answers its calls and feeds its topics;process.spawnandprocess.run
start programs;handoffgives the terminal to a program, such as the person's shell, and shows
the view again when it ends;fs(withwatch, which polls nothing),json,hash.sha256,
text,regex,time,os,env,args,path,io.write,io.read_lineandexit.
There is one thread and one loop for the terminal, the timers and the pipes of the programs an
app starts;process.run,time.sleepandservewait without holding it. - For an app that is a filter in a pipeline, such as a picker:
serve{ filter = true }shows the
view on the controlling terminal whatever the standard streams are, so that stdin and stdout stay
the pipeline's;io.read_stdin(on_data[, on_end])reads standard input as it arrives, a piece at
a time and exactly as written, without holding the app (:stop(),:active(),:wait());
io.is_terminal("stdin" | "stdout" | "stderr");close_view()ends the view from the app's
side, so that what was chosen is written with the pane given back; andprocess.spawn/run
withsession = truestart a program with no controlling terminal, for a command that must not
reach the pane. - For an app that edits files, such as an editor:
fs.create(a new file, where nothing is: it
does not truncate a file or write through a link),fs.rename,fs.writable,linkin
fs.list;process.runwithraw(output that is not text, exactly as written) and
max_output;json.null;os.hostnameandos.username;text(names in the order people
read them, and a text counted in UTF-16 units);serve{ icons }(an icon for each background and
size).
Changed
cli-v0.1.0was not this command. That release was the TypeScript@pencere/cli, which
this replaces: a TypeScript program shows its view with@pencere/sdknow, and
pencere new --lang tsstarts one. The command's first release is 0.2.0.
Security
- A program that
process.spawnorprocess.runstarts runs in a group of its own, andkill, a
timeout,max_outputand the end of the app signal the whole group, so a shell's pipeline does
not outlive its shell.max_outputcounts the bytes as they are read, line ends included, and
keeps nothing past the limit. An app that shows nothing and is ended by ⌃C or a hangup asks the
programs it started to end first, andon_exitis told whether the program was ended for saying
too much. regexuses an engine that does not backtrack, so a pattern a person typed or a page sent cannot
hold the app. Back-references and look-ahead or look-behind are refused ("this pattern uses a
back-reference, which search does not support");whole_wordis checked in code around the
match.pencere buildrefuses a Mac runner without the room in its header for the app's section, and a
Mac's runner is linked with that room, so an app cannot be written over its first functions.
sdk-typescript-v0.1.1
Fixed
- A program run by a parent that forwards signals (
npm start, for one) is no longer ended by
⌃C before it has given the terminal back. The parent sends the interrupt the tty already sent a
moment later, andservehad put the signal's default action back before writingbyeand
leaving the alternate screen: the second interrupt ended the process between the two, and the
shell's prompt came back on the alternate screen. The listeners now go after the terminal is
given back.