From 33037ece5af9ae1c7048819bbbae3fc5e6fc4ade Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Fri, 6 Nov 2026 02:31:55 -0300 Subject: kinds #7, the docs: reference.typ's Addons section says ABI 2's contract (the tick rule and PA_FOCUSED, one paint a frame, the tag's prefix, art words and path, jobs across a reload, a client's Shadow), /addons as it is and --addon-test's words, and the changelog one entry Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge --- docs/typ/reference.typ | 44 +++++++++++++++++++++++++++++++++++--------- src/CHANGELOG.md | 7 +++++++ 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 205b0400..972d5794 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -978,9 +978,29 @@ game, a plot. It is written against one header, `src/kinds/pardes_addon.h`, in C or anything that speaks C, and links nothing of pardes: the records are the header's, and what pardes does for it (an allocation from the pane's arena, a job off the loop, a Look, a message, a new text pane) it is -handed at load. `addons/fake/fake.c` uses every function; a kind with only -a head and `paint` is a valid one. Image is a kind compiled in, through the -same records. +handed at load. `addons/fake/fake.c` uses every function and +`addons/snake/snake.c` is a game in it; a kind with only a head and `paint` +is a valid one. Image is a kind compiled in, through the same records. The +header is ABI 2: an addon built against another major is refused. + +- `tick(state, now, flags)` returns the absolute time of its next step + (0: none) on a monotonic clock. It is called when that time comes and + once after `open`, a key or click it took, a word, a job's answer, a + `load`, and whenever `PA_FOCUSED` (its pane has the keyboard in some + view, its window focused) changes: a kind that returned 0 is woken by + the next thing that happens to it, and one that steps only while focused + asks for nothing otherwise. `paint` is called once a frame and changes + nothing (a Debug build checks the kind's memory across it). +- The tag of its pane is the prefix its last frame gave (else its kind's + name), then, when that frame placed a picture, the core's own + `petscii:on palette:commodore ascii:off` (#word("Petscii"), + #word("Palette") and #word("Ascii") are the core's words), then its + path. +- Its jobs run on the host's workers; one asked before an + #word("Addon") `reload` answers into nothing, and the old library stays + until its last such job has answered. +- A client of the session runs no addon's code: a pane of a kind it lacks + shows the session's frames of it, and its keys go to the session. - #word("Addon") `load ` (relative to the pane's directory) loads one; `unload ` lets one go, refused while a pane of its kind is @@ -989,10 +1009,12 @@ same records. a library that fails any check leaves the old one running; bare, it says the kinds here. At start, every `*.so` of `$XDG_DATA_HOME/pardes/addons`, then of `/lib/pardes/addons`, is loaded. -- #file("/addons"): a line a kind, ` static|loaded - `, and a line an addon refused, with why: another ABI's major, no - `pardes_addon`, a word, leader path or extension already someone's (the - core's or another addon's: refused whole), words with no `ctl`. +- #file("/addons"): a line a kind, ` + static|loaded`, and a line an addon refused, with why: + another ABI's major, no `pardes_addon`, a word, leader path or extension + already someone's (the core's or another addon's: refused whole), words + for its panes with no `ctl`. Each session has its own: a library is + shared by the sessions of a process that loaded the same bytes. - Its words join #file("/commands") and Help, `(addon )` after each. Written to a pane of its kind they go to that kind; a word that opens its kind opens a pane of it from anywhere, its argument the path; any other @@ -1011,8 +1033,12 @@ same records. library, listed so, until #word("Addon") `load` asks for it again. A crash inside one says `in addon , ` in the crash record. - `pardes --addon-test