summaryrefslogtreecommitdiff
path: root/src/kinds
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 00:02:06 -0300
committerGabriel Schneider <[email protected]>2026-11-06 01:21:34 -0300
commit423440f25b4b23b56162008bba35218d438767fe (patch)
treea7b06a88c7a55308e7e906ff49fa264a1fd147cf /src/kinds
parent94ca47f225632fefc8f688c0c0822d25d6a5db1e (diff)
downloadpardes-423440f25b4b23b56162008bba35218d438767fe.tar.gz
pardes-423440f25b4b23b56162008bba35218d438767fe.zip
kinds #2, a pane of a kind is one slot and image is a kind compiled in: src/kinds/pardes_addon.h is the kinds' C ABI (the cell, the window a kind paints, placements and the tag prefix it hands back, keys, the mouse, pa_api of six functions over the pane's arena, words, the head and pa_ops of paint and sixteen optional functions), translated once by the build into the core's records, never mirrored; src/Kind.zig is the core's side: the kinds this process has (a registry with the checks a load makes: the head's size and abi major, a paint, a name, words, leaders and extensions none else has), a pane's Slot (the kind's state and arena, its path, the art bytes Petscii, Palette and Ascii set, its tick deadline and jobs) and the addon arm at the sites: Look and the initial file by extension, draw (cells into the grid, placements keyed by serial and the kind's key), the tag prefix from a paint over no cells, nextWake and the step (ticks, jobs' answers landing on the loop), close, Recent, paneDir, /index's kind word; a dump writes a slot by hand (kind name and version, path, where, art, the kind's own record) and loads it through the kind's open and load, or as a placeholder that keeps the record when the kind is not here; image.zig's pane is now a static pa_ops (open refuses what it cannot read, the decode a job whose answer lands at a step instead of a thread polled by draw, one placement fitted by the frontend, its record the file's bytes), Pane.image is Pane.addon, and the three art words act on the slot; no golden changes (images.snap and tagbottomimage.snap pass, the tag prefix and the placement key are the same bytes); tests: the image dump test, the Petscii/Palette/Ascii ctl tests, the image tag-prefix test and fs_namespace's decode test rewritten on the slot (the decode now lands at the step after the open), plus a registry test; gates: core-test 960/960 on both, unit-test 1487/1488 tui and 1531/1532 gui, behaviour-test 244/244, pane-test 171/172, snap all ok, process-test 0 of 37 failed on both
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/kinds')
-rw-r--r--src/kinds/pardes_addon.h261
1 files changed, 261 insertions, 0 deletions
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h
new file mode 100644
index 00000000..8a95d6d7
--- /dev/null
+++ b/src/kinds/pardes_addon.h
@@ -0,0 +1,261 @@
+/* pardes_addon.h: an addon, a shared library that brings pardes one
+ * kind of pane (a picture, a game, a plot).
+ *
+ * An addon exports one symbol, `pardes_addon`, a `pa_ops` whose `head`
+ * names its kind. pardes calls it on its own thread, one call at a time;
+ * it keeps no pointer pardes hands it past the call (but its `pa_api`),
+ * starts no threads (it has jobs), and reads no file, clock or
+ * environment (it is handed bytes and the time). Every function but
+ * `paint` is optional: leave it NULL and pardes does the default the
+ * comment beside it says.
+ *
+ * cc -shared -fPIC -o game.so game.c
+ * 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.
+ */
+#ifndef PARDES_ADDON_H
+#define PARDES_ADDON_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Major in the high half: an addon of another major is refused. */
+#define PA_ABI_MAJOR 1u
+#define PA_ABI_MINOR 0u
+#define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR)
+
+/* ---- the picture ---- */
+
+/* A cell's colour: the theme's own, one of its 256, or RGB. */
+#define PA_DEFAULT 0x01000000u
+#define PA_INDEX(n) (0x02000000u | (uint8_t)(n))
+#define PA_RGB(r, g, b) (((uint32_t)(uint8_t)(r) << 16) | ((uint32_t)(uint8_t)(g) << 8) | (uint32_t)(uint8_t)(b))
+
+#define PA_BOLD 0x01u
+#define PA_DIM 0x02u
+#define PA_ITALIC 0x04u
+#define PA_REVERSE 0x10u
+#define PA_UNDERLINE 0x100u
+
+/* A cell: one character, `len` bytes of UTF-8 (at most 7). */
+#define PA_UNPAINTED 0x01u /* flags: the pane's background, nothing drawn */
+typedef struct pa_cell {
+ uint8_t text[8];
+ uint32_t fg, bg;
+ uint16_t attrs;
+ uint8_t len;
+ uint8_t flags;
+} pa_cell;
+
+/* The pane's body, which `paint` writes: `rows` rows of `cols` cells,
+ * `stride` cells apart, every one PA_UNPAINTED when the call begins. */
+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;
+} 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. */
+typedef struct pa_placement {
+ const uint8_t *rgba;
+ uint32_t w, h, stride;
+ pa_rect src;
+ pa_cells dst;
+ pa_rect at;
+ uint64_t key;
+} 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). */
+typedef struct pa_paint {
+ pa_placement *placements;
+ uint32_t cap, n;
+ char prefix[96];
+ uint32_t prefix_len;
+} pa_paint;
+
+/* ---- input ---- */
+
+/* A key: a codepoint, or one of these. */
+#define PA_KEY_ENTER 0x0Du
+#define PA_KEY_TAB 0x09u
+#define PA_KEY_BACKSPACE 0x7Fu
+#define PA_KEY_UP 0xF0001u
+#define PA_KEY_DOWN 0xF0002u
+#define PA_KEY_LEFT 0xF0003u
+#define PA_KEY_RIGHT 0xF0004u
+#define PA_KEY_HOME 0xF0005u
+#define PA_KEY_END 0xF0006u
+#define PA_KEY_PAGE_UP 0xF0007u
+#define PA_KEY_PAGE_DOWN 0xF0008u
+#define PA_KEY_DELETE 0xF0009u
+typedef struct pa_key {
+ uint32_t cp;
+ uint8_t ctrl, alt, shift, pad;
+} pa_key;
+
+#define PA_LEFT 0
+#define PA_MIDDLE 1
+#define PA_RIGHT 2
+#define PA_WHEEL_UP 3
+#define PA_WHEEL_DOWN 4
+#define PA_PRESS 0
+#define PA_RELEASE 1
+#define PA_MOTION 2
+#define PA_DRAG 3
+/* A pointer event in the window's cells. */
+typedef struct pa_mouse {
+ uint8_t button, action, ctrl, shift, alt, pad;
+ uint16_t col, row;
+} pa_mouse;
+
+/* ---- what pardes does for an addon ---- */
+
+/* Valid during any call pardes makes for a pane, and about that pane. */
+typedef struct pa_api {
+ uint32_t size;
+ /* Zeroed memory from the pane's arena, which pardes frees at its close;
+ * NULL when the arena is full. */
+ void *(*alloc)(size_t n);
+ void (*free)(void *ptr, size_t n);
+ /* `job_run` over a copy of `in` on a worker; its answer comes to
+ * `job_done` with the token returned here (0: refused). */
+ uint32_t (*job)(const void *in, uint32_t n);
+ /* Look at `text` as a click would: a URL, `file:12`, a word. */
+ void (*look)(const char *text, uint32_t n);
+ /* A message on the pane, or an error (`err` 1: also refuses an `open`). */
+ void (*say)(const char *text, uint32_t n, int err);
+ /* A new text pane named `name` holding `bytes`; its serial, 0 if none. */
+ uint32_t (*text)(const char *name, uint32_t name_len, const char *bytes, uint32_t n);
+} pa_api;
+
+/* A job's answer buffer: `alloc` it once, write it, return its length. */
+typedef struct pa_out {
+ void *(*alloc)(struct pa_out *out, size_t n);
+ void *ctx;
+} pa_out;
+
+/* ---- the addon ---- */
+
+#define PA_ARG_NONE 0
+#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). */
+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];
+ const char *doc;
+} pa_word;
+
+typedef struct pa_head {
+ uint32_t size, abi;
+ /* The pane's kind word in /index, NUL-padded. */
+ char name[16];
+ uint32_t version;
+ /* The extensions it opens, space-separated (".png .jpg"), or "". */
+ const char *exts;
+ const pa_word *words;
+ uint32_t nwords;
+} pa_head;
+
+typedef struct pa_ops {
+ pa_head head;
+ /* Once, at load: nonzero refuses 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
+ * with no state; `say` an error to refuse it. */
+ 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);
+ /* 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. */
+ 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);
+ /* The pane's body as text (9P `body`). Absent: empty. */
+ uint64_t (*body_len)(void *st);
+ uint32_t (*body)(void *st, uint64_t off, char *buf, uint32_t n);
+ /* Go to `text` (`:12`, `12:0.33`); nonzero if it is a place here. And
+ * 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. */
+ 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. */
+ 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`. */
+ uint32_t (*dump)(void *st, uint8_t *buf, uint32_t n);
+ int (*load)(void *st, const uint8_t *buf, uint32_t n, uint32_t version);
+} pa_ops;
+
+/* ---- helpers ---- */
+
+static inline pa_cell *pa_at(const pa_window *w, unsigned row, unsigned col) {
+ return row < w->rows && col < w->cols ? &w->cells[row * w->stride + col] : 0;
+}
+
+/* `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) {
+ unsigned n = 0;
+ while (*text) {
+ pa_cell *c = pa_at(w, row, col + n);
+ unsigned len = 1;
+ while (len < 7 && (text[len] & 0xC0) == 0x80) len++;
+ if (c) {
+ for (unsigned i = 0; i < 8; i++) c->text[i] = i < len ? (uint8_t)text[i] : 0;
+ c->len = (uint8_t)len;
+ c->fg = fg;
+ c->bg = bg;
+ c->attrs = 0;
+ c->flags = 0;
+ n++;
+ }
+ text += len;
+ if (!c) break;
+ }
+ return n;
+}
+
+/* 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) \
+ { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .exts = (ex), .words = (ws), .nwords = (nws) }
+
+#endif