Schcom v0: a compositor that actually composites

Clients connect over a Unix socket, are handed a shared buffer, draw into
it and commit; Schcom composites and presents. Both of the hard blockers
its README listed -- unix domain sockets and raw input events -- have been
done for a while, so nothing was in the way.

The model is Wayland's, on purpose. A surface is not a window: it is a
rectangle of pixels with no policy attached, because placement belongs to
SchWM and the moment this program starts deciding where windows go the
split has failed. Nothing is shown until COMMIT, so a client halfway
through drawing is never presented. The compositor tells clients when to
draw rather than letting them render frames nobody sees.

Wayland is MIT-licensed and supporting it later is intended, so the
divergences are the ones that are cheap to undo: a buffer handle is a
System V shm id rather than an fd over SCM_RIGHTS, and the message
carries a handle_kind field so switching is a new value rather than a
protocol break. Every message carries its own length, so an unknown
message is skipped instead of desynchronising the stream -- which is what
lets a v0 compositor survive a v1 client.

The compositor owns the shm segment, not the client: it has to survive a
client crashing mid-frame, and it must not be something a client can
resize underneath it. A dropped connection takes its surfaces and their
segments with it.

Composites into a back buffer and copies once, because compositing
straight into the framebuffer shows every intermediate state -- the
flicker would be the whole desktop being repainted under the user's eyes.

projects/ gets build glue for the first time: `make projects` builds
against the sysroot's libc and stages into sysroot/bin. It is not a
dependency of anything above it, and `make` never descends there.

Verified by `make schcom-test`, which boots SchOS, runs the compositor and
a client, screendumps the framebuffer and asserts the pixels on the host.
That last part is the point -- the compositor reporting that it
composited something proves nothing, and a screenshot nobody inspects
proves less. It checks the client's colour mid-surface, the compositor's
background, and the white border exactly at the requested origin, so
"arrived" and "arrived at the wrong offset" cannot pass for each other.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

projects/schcom/proto.h

@@ -0,0 +1,128 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/*
+ * The Schcom wire protocol.
+ *
+ * Versioned from the first commit, because SchWM and SchDE are separate
+ * programs: the protocol is a real compatibility surface on day one, not after
+ * the fact. A client sends SCHCOM_OP_HELLO with the version it speaks and the
+ * compositor either acknowledges it or closes the connection. Nothing else is
+ * accepted before the handshake.
+ *
+ * The shape is deliberately Wayland's, because Wayland support is intended
+ * later and it is MIT-licensed, so it can be linked (see the licensing note in
+ * the README). Borrowed, specifically:
+ *
+ *   - a surface is not a window. It is a rectangle of pixels with no policy
+ *     attached; placement belongs to SchWM.
+ *   - a buffer is attached to a surface and nothing appears until COMMIT.
+ *     Atomicity is the whole point: a client that is halfway through drawing
+ *     must never be shown.
+ *   - the compositor tells the client when to draw again (FRAME), rather than
+ *     the client drawing whenever it likes. That is what stops a fast client
+ *     from burning the machine rendering frames nobody sees.
+ *
+ * Where it deliberately differs, for now: a buffer is a System V shared memory
+ * id passed as an integer, not a file descriptor passed over SCM_RIGHTS.
+ * SCM_RIGHTS is the Wayland-compatible route and the kernel supports it, but an
+ * integer needs no ancillary-data handling on either side and this is v0. The
+ * message carries a `handle_kind` field so the switch does not become a
+ * protocol break.
+ */
+#ifndef SCHCOM_PROTO_H
+#define SCHCOM_PROTO_H
+
+#include <stdint.h>
+
+#define SCHCOM_SOCKET_PATH "/tmp/schcom.sock"
+
+/* Bumped on any incompatible change. v0 is provisional in the SchAPI sense:
+ * nothing here is frozen until 1.0. */
+#define SCHCOM_VERSION 0u
+
+enum schcom_op {
+    /* client -> compositor */
+    SCHCOM_OP_HELLO          = 1,
+    SCHCOM_OP_CREATE_SURFACE = 2,
+    SCHCOM_OP_COMMIT         = 3,
+    SCHCOM_OP_DESTROY        = 4,
+
+    /* compositor -> client */
+    SCHCOM_OP_HELLO_ACK      = 128,
+    SCHCOM_OP_SURFACE        = 129,  /* the buffer for a CREATE_SURFACE */
+    SCHCOM_OP_FRAME          = 130,  /* draw again now */
+    SCHCOM_OP_INPUT          = 131,
+    SCHCOM_OP_ERROR          = 132,
+};
+
+/* How the pixels are shared. Only SHMID exists today; the field exists so that
+ * adding SCM_RIGHTS later is a new value rather than a new protocol. */
+enum schcom_handle_kind {
+    SCHCOM_HANDLE_SHMID = 1,
+    SCHCOM_HANDLE_FD    = 2,   /* reserved: passed over SCM_RIGHTS */
+};
+
+/* Every message begins with this. `length` counts the header itself, so a
+ * reader can skip a message it does not understand instead of losing sync --
+ * which is what lets an old compositor talk to a newer client at all. */
+struct schcom_header {
+    uint32_t op;
+    uint32_t length;
+    uint32_t serial;    /* echoed in the reply, 0 for events */
+    uint32_t surface;   /* surface id, 0 where not applicable */
+};
+
+struct schcom_hello {
+    struct schcom_header hdr;
+    uint32_t version;
+    uint32_t pad;
+};
+
+struct schcom_create_surface {
+    struct schcom_header hdr;
+    uint32_t width;
+    uint32_t height;
+    int32_t  x;         /* v0: the client asks. SchWM will own this later. */
+    int32_t  y;
+};
+
+/* The compositor's answer: here is your surface id and where its pixels live.
+ * Always 32-bit XRGB8888, stride in bytes, because a client that has to
+ * negotiate a format before it can draw a rectangle is a client that cannot be
+ * written in an afternoon. Format negotiation is a v1 problem. */
+struct schcom_surface {
+    struct schcom_header hdr;
+    uint32_t handle_kind;
+    uint32_t handle;        /* shm id when handle_kind == SHMID */
+    uint32_t width;
+    uint32_t height;
+    uint32_t stride;
+    uint32_t size;
+};
+
+/* Nothing is shown until this arrives. The damage rectangle is advisory: the
+ * compositor may repaint more, never less. */
+struct schcom_commit {
+    struct schcom_header hdr;
+    int32_t  x, y;
+    uint32_t width, height;
+};
+
+/* Raw-ish input, already routed to the surface that should have it. Codes are
+ * the Linux input event codes the kernel's /dev/input/eventN already speaks --
+ * translating them here would mean inventing a second table to disagree with
+ * the first. */
+struct schcom_input {
+    struct schcom_header hdr;
+    uint32_t type;      /* EV_KEY, EV_REL, ... */
+    uint32_t code;
+    int32_t  value;
+    int32_t  x, y;      /* pointer position at the time of the event */
+};
+
+struct schcom_error {
+    struct schcom_header hdr;
+    uint32_t code;
+    uint32_t pad;
+};
+
+#endif /* SCHCOM_PROTO_H */