summaryrefslogtreecommitdiff
path: root/src/kinds/pardes_addon.h
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 02:31:55 -0300
committerGabriel Schneider <[email protected]>2026-11-06 04:04:25 -0300
commit9c66cdc9049b49f128336dcf5046e2bb1321e281 (patch)
tree7ff664677eb7291558f71a8f824d0ce6a922779a /src/kinds/pardes_addon.h
parenta6f294ef5b50aeb5b69e486838378654e318ed04 (diff)
downloadpardes-9c66cdc9049b49f128336dcf5046e2bb1321e281.tar.gz
pardes-9c66cdc9049b49f128336dcf5046e2bb1321e281.zip
kinds #5, ABI 2 and the seam: src/kinds/pardes_addon.h is ABI 2 as architecture §16.9 has it (pa_window 24 bytes and no art bytes, pa_placement 80 with at, from and dirty_y/dirty_h and no stride, pa_word 32 with no size and PA_WORD, tick(st, now_ns, flags) with PA_FOCUSED, PA_OK and the conventions, the dump and load rules, pa_put with attrs, pa_copy and PA_POD, whose fragment gcc -Werror refused as written and is ternaries here) and fake.c and image's table speak it; tick is called at its deadline and once after open, a taken key or click, a word, a job's answer, a load and a change of PA_FOCUSED (the pane has the keyboard in some view, its window focused), nextWake folds the deadlines, and a Debug build hashes the kind's allocations across paint and panics naming it; paint runs once a frame, the slot keeps its prefix and whether it placed a picture, the tag is that prefix, the core's art words when it did and the path, and a frame that changes it owes a step to lay the tag out again; Addon load and reload are an addon effect the host performs (memfd, BLAKE3, dlopen, the head checks and init, the bytes a process holds shared and counted) answered by an addon event carrying what the library brings as data, whose update does the collisions, the reload's validate-then-swap at a new generation and the waiting panes deterministically, while unload is the update's alone and lets the library go by effect; a kind's job is Effect.job run on the host's workers (host_io.KindJob: tui and gui on Io.concurrent, macOS and tests on the loop) answered by Event.job, stale generations dropped and a library closed after its last job; each core has its own Registry (16 kinds, their words, leaders and extensions, digested and dumped; their code a local side array a replica has none of), so a test session no longer unloads the world and Restore and -l keep the process's kinds; every call into a kind whose answer the core acts on is taped as an Outcome (its answer, refusal, message, Look, text pane) and the prefix a step reads is taped too, so a replica's core, which runs no kind's code, steps alike; a pane of a kind on a replica is a Shadow drawn from the authority's frames, painted for the peer's view and sent by Screens as row hashes with the rows that changed and each raster once a key (screen_state.Shadow), its keys going to the authority; the tail, reload and the Addon word and event are Addon.zig's, the slot's record dump.zig's, a tail word's run exec.zig's; --addon-test gains focus, blur, dump, body, ctl and the window line, its jobs done as a host does them; fake.out gains its window line, loses a body row once the tag carries the art words and lands FakeJob at once; tests rewritten: the image dump test (the replica-style load keeps the record), the Petscii/Palette/Ascii tag test in ctl.zig and test/panes.zig's image tag test (a picture decoded and shown first), fs_namespace's decode test (the job performed as a host would), Kind.zig's registry test and Addon.zig's crash-mark test, the addons suite's ABI numbers; new: a job under way across a reload (T1), a Shadow's frame codec, and a replica with no code for a kind showing its pane and passing its keys; gates: core-test 958/958 and behaviour-test 249/249 on both, unit-test 1490/1491 tui and 1533/1534 gui, pane-test 171/172, snap all 105 ok, process-test 0 of 37 failed on both, addon-test ok, hxdiff 19 and hxparity 6 mismatches by the base's names, hxgolf 0, replicas, gui-golden, monkey-gui, daemon.py main and window-clients, soak local pass, perf medium within 1% of the base
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/kinds/pardes_addon.h')
-rw-r--r--src/kinds/pardes_addon.h117
1 files changed, 81 insertions, 36 deletions
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h
index c3fbc097..c6aa448b 100644
--- a/src/kinds/pardes_addon.h
+++ b/src/kinds/pardes_addon.h
@@ -13,18 +13,26 @@
* echo 'Addon load ./game.so' > $PARDES_MOUNT/ctl
* pardes --addon-test ./game.so game.script a test, as a script
*
- * addons/fake/fake.c implements every function; it is the template.
+ * Conventions: init, ctl and load return PA_OK (0), or nonzero to refuse;
+ * key, mouse and address return nonzero when the event or text was theirs.
+ * The pa_api pointer handed to init is kept by the addon; it is about the
+ * pane of the current call.
+ *
+ * addons/fake/fake.c implements every function; it is the template, and
+ * addons/snake/snake.c a game in it.
*/
#ifndef PARDES_ADDON_H
#define PARDES_ADDON_H
#include <stddef.h>
#include <stdint.h>
+#include <string.h> /* memcpy, for pa_copy and PA_POD */
/* Major in the high half: an addon of another major is refused. */
-#define PA_ABI_MAJOR 1u
+#define PA_ABI_MAJOR 2u
#define PA_ABI_MINOR 0u
#define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR)
+#define PA_OK 0
/* ---- the picture ---- */
@@ -52,42 +60,48 @@ typedef struct pa_cell {
} pa_cell;
/* The pane's body, which `paint` writes: `rows` rows of `cols` cells,
- * `stride` cells apart, every one zero (unpainted) when the call begins. */
+ * `stride` cells apart, every one zero (unpainted) when the call begins.
+ * How a frontend shows the placements (glyph art, its palette) is the
+ * core's words' (Petscii, Palette, Ascii), never the addon's. */
typedef struct pa_window {
pa_cell *cells;
uint32_t stride;
uint16_t rows, cols;
/* A cell's size in pixels, as the frontend draws it. */
uint16_t cell_w, cell_h;
- /* The pane has the keyboard. */
- uint8_t focused;
- /* How the frontend shows this pane's placements, which the core words
- * Petscii, Palette and Ascii set: as glyph art (Petscii on, or a frontend
- * with no pixels), in the commodore (0) or the terminal's (1) palette,
- * with letters among the glyphs. An addon may say so in its prefix. */
- uint8_t glyphs, palette, ascii;
+ /* The pane has the keyboard in some view: for the picture ("paused"). */
+ uint8_t focused, pad[3];
} pa_window;
typedef struct pa_rect { uint32_t x, y, w, h; } pa_rect; /* pixels */
typedef struct pa_cells { uint16_t x, y, w, h; } pa_cells; /* cells of the window */
/* A picture over the cells: the `src` part of an RGBA raster (straight
- * alpha, `stride` bytes a row), over the `dst` cells; at `at` pixels in
- * them, or fitted there (no larger than it is) when `at.w` is 0. The
- * raster is the addon's and must stay as it is until the pane's next paint
- * or close. `key` is the pixels' identity in the pane: one key, one
- * picture, so a frontend keeps what it uploaded under it. */
+ * alpha, packed rows of w*4 bytes), over the `dst` cells, at `at` pixels in
+ * them, or fitted there (no larger than it is) when at.w is 0. The raster
+ * is the addon's and must stay as it is until the pane's next paint or
+ * close. `key` names the pixels in this pane: one key, one picture, so a
+ * frontend keeps what it uploaded under it. `from` is 0, or the key of a
+ * picture a frontend may still hold of which rows dirty_y .. dirty_y +
+ * dirty_h of this one alone differ (a frontend that holds it may patch
+ * those rows; any other uploads the whole). */
typedef struct pa_placement {
const uint8_t *rgba;
- uint32_t w, h, stride;
+ uint32_t w, h;
pa_rect src;
pa_cells dst;
pa_rect at;
uint64_t key;
+ uint64_t from;
+ uint32_t dirty_y, dirty_h;
} pa_placement;
/* What `paint` hands back beside the cells: placements (room for `cap`,
- * lowest first) and the start of the pane's tag (empty: the pane's path). */
+ * at least 64, lowest first) and the start of the pane's tag, which the
+ * core follows with one space, its own words for a picture shown
+ * (`petscii:on palette:commodore ascii:off`, when this frame placed one),
+ * and the pane's path; empty, the kind's name. paint is called once a
+ * frame, body and prefix together, never over no cells. */
typedef struct pa_paint {
pa_placement *placements;
uint32_t cap, n;
@@ -165,17 +179,22 @@ typedef struct pa_out {
#define PA_ARG_OPTIONAL 1
#define PA_ARG_REQUIRED 2
-/* A word the addon brings. Written to a pane of its kind, it goes to `ctl`;
- * one that `opens` it, run anywhere else, opens a pane of the kind
- * (`open` with its argument as the path, or none). */
+/* A word the addon brings. An `opens` word opens a pane of the kind
+ * wherever it runs (`open` with its argument as the path, or none); any
+ * other goes to `ctl` of the pane of its kind it is written to, refused
+ * elsewhere. The core checks `arg` before the call; ctl is required when a
+ * word has opens 0. */
typedef struct pa_word {
- uint32_t size;
const char *name;
/* The keys after the leader (Space) that run it, "ng" for SPC n g, or NULL. */
const char *leader;
- uint8_t arg, opens, pad[2];
+ uint8_t arg, opens, pad[6];
const char *doc;
} pa_word;
+#define PA_WORD(nm, ld, a, op, dc) { .name = (nm), .leader = (ld), .arg = (a), .opens = (op), .doc = (dc) }
+
+/* tick's flags: the pane has the keyboard in some view. */
+#define PA_FOCUSED 0x1u
typedef struct pa_head {
uint32_t size, abi;
@@ -190,7 +209,7 @@ typedef struct pa_head {
typedef struct pa_ops {
pa_head head;
- /* Once, at load: nonzero refuses the addon. */
+ /* Once, at load: PA_OK, or nonzero to refuse the addon. */
int (*init)(const pa_api *api);
/* A new pane (path and bytes NULL for one a word opened): its state,
* which every call below is handed. NULL with nothing said is a pane
@@ -198,12 +217,17 @@ typedef struct pa_ops {
void *(*open)(const char *path, const uint8_t *bytes, uint64_t len);
/* The pane closes; its arena is freed after. */
void (*close)(void *st);
- /* Time has come to `now_ns`: step, and say when next (0: never). Absent,
- * the pane repaints when the core repaints. */
- uint64_t (*tick)(void *st, uint64_t now_ns);
+ /* Time has come to now_ns (monotonic, any origin; --addon-test's starts
+ * at 1 s): step, and return the absolute time of the next step, 0 for
+ * none. Called when that time comes and once after open, a taken key or
+ * mouse, ctl, job_done, load, and a change of PA_FOCUSED in `flags`: a
+ * kind that returned 0 is woken by the next thing that happens to it.
+ * Absent, the pane repaints when the core repaints. */
+ uint64_t (*tick)(void *st, uint64_t now_ns, uint32_t flags);
/* Required. Pure: the same state paints the same, and changes nothing. */
void (*paint)(void *st, const pa_window *win, pa_paint *out);
- /* Every key but Esc, which leaves; nonzero if taken. Absent: no keys. */
+ /* Every key but Esc, which leaves; nonzero if taken. A key not taken goes
+ * to the editor's own navigation. Absent: no keys. */
int (*key)(void *st, const pa_key *k);
/* Nonzero if taken. Absent: a click focuses the pane. */
int (*mouse)(void *st, const pa_mouse *m);
@@ -214,18 +238,23 @@ typedef struct pa_ops {
* where the pane is now, as such a text (jumps, Recent, a Restore). */
int (*address)(void *st, const char *text, uint32_t n);
uint32_t (*where)(void *st, char *buf, uint32_t n);
- /* One of the addon's words, as written (`Fit width`): 0 taken, else
- * refused with `reply`. Required with words. */
+ /* One of the addon's words, as written (`Fit width`): PA_OK, else
+ * refused with `reply`. Required when a word has opens 0. */
int (*ctl)(void *st, const char *line, uint32_t n, char *reply, uint32_t cap);
- /* What the pane's ctl file reads after the core's fields. */
+ /* What the pane's ctl file reads after the core's fields: `name value`
+ * lines. */
uint32_t (*ctl_read)(void *st, char *buf, uint32_t n);
/* On a worker thread, pure over `in`: the answer's length. */
uint32_t (*job_run)(const uint8_t *in, uint32_t n, pa_out *out);
/* Back on pardes's thread; `out` is gone after the call. */
void (*job_done)(void *st, uint32_t token, const uint8_t *out, uint32_t n);
- /* The pane's record for a dump (its length; at most `n`), and back. With
- * none, a Restore reopens the pane from its path and its `where`. */
+ /* The pane's record for a dump: at most `n` bytes, n at least 1 MiB; 0 is
+ * no record (load is not called and the pane reopens from its path, its
+ * `where` and its words' last values), and so is having no dump. */
uint32_t (*dump)(void *st, uint8_t *buf, uint32_t n);
+ /* On the state open(path, bytes, len) returned, with the writer's
+ * head.version: PA_OK, or nonzero to refuse (the pane waits as a
+ * placeholder, its record kept). */
int (*load)(void *st, const uint8_t *buf, uint32_t n, uint32_t version);
} pa_ops;
@@ -235,11 +264,11 @@ typedef struct pa_ops {
_Static_assert(sizeof(pa_cell) == 20, "pa_cell");
_Static_assert(sizeof(pa_window) == 24, "pa_window");
_Static_assert(sizeof(pa_rect) == 16 && sizeof(pa_cells) == 8, "pa_rect");
-_Static_assert(sizeof(pa_placement) == 72, "pa_placement");
+_Static_assert(sizeof(pa_placement) == 80, "pa_placement");
_Static_assert(sizeof(pa_paint) == 120, "pa_paint");
_Static_assert(sizeof(pa_key) == 8 && sizeof(pa_mouse) == 10, "pa_key");
_Static_assert(sizeof(pa_api) == 64 && sizeof(pa_out) == 16, "pa_api");
-_Static_assert(sizeof(pa_word) == 40 && sizeof(pa_head) == 56, "pa_head");
+_Static_assert(sizeof(pa_word) == 32 && sizeof(pa_head) == 56, "pa_head");
_Static_assert(sizeof(pa_ops) == 192, "pa_ops");
#endif
@@ -251,7 +280,7 @@ static inline pa_cell *pa_at(const pa_window *w, unsigned row, unsigned col) {
/* `text` (UTF-8) from (row, col) on, a character a cell, cut at the edge;
* the cells written. */
-static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, const char *text, uint32_t fg, uint32_t bg) {
+static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, const char *text, uint32_t fg, uint32_t bg, uint16_t attrs) {
unsigned n = 0;
while (*text) {
pa_cell *c = pa_at(w, row, col + n);
@@ -262,7 +291,7 @@ static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, co
c->len = (uint8_t)len;
c->fg = fg;
c->bg = bg;
- c->attrs = 0;
+ c->attrs = attrs;
c->flags = PA_PAINTED;
n++;
}
@@ -272,6 +301,22 @@ static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, co
return n;
}
+/* `n` bytes of src[off..len] into buf: the body of a kind whose text is small. */
+static inline uint32_t pa_copy(const void *src, uint64_t len, uint64_t off, void *buf, uint32_t n) {
+ if (off >= len) return 0;
+ if (n > len - off) n = (uint32_t)(len - off);
+ memcpy(buf, (const uint8_t *)src + off, n);
+ return n;
+}
+
+/* dump and load as a byte copy of a plain struct `type`, refused across
+ * versions: PA_POD(snake, VERSION) then .dump = snake_dump, .load = snake_load */
+#define PA_POD(type, ver) \
+ static uint32_t type##_dump(void *st, uint8_t *buf, uint32_t n) { \
+ return n < sizeof(type) ? 0 : (memcpy(buf, st, sizeof(type)), (uint32_t)sizeof(type)); } \
+ static int type##_load(void *st, const uint8_t *buf, uint32_t n, uint32_t version) { \
+ return version != (ver) || n != sizeof(type) ? 1 : (memcpy(st, buf, sizeof(type)), PA_OK); }
+
/* An addon's head, its size and ABI filled:
* const pa_ops pardes_addon = { .head = PA_ADDON("game", 1, "", words, 1), .paint = paint }; */
#define PA_ADDON(nm, ver, ex, ws, nws) \