1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
# unbox — Constitution (root AGENTS.md)
> Loaded every session. Non-obvious, project-specific rules only — if a fresh
> frontier model could infer it from the code, it does NOT belong here.
> Full design + rationale: `notes/plan.md`. Workflow: `ORCHESTRATOR.md`.
## What this project is
An experimental Wayland desktop environment for the Panasonic CF-AX3
(touchscreen, 4-core i5-4300U Haswell, 3.7 GiB RAM, Artix Linux + s6).
A **monolithic kernel + in-process extensions**: ONE process containing the
wlroots compositor core and an embedded RMLUi UI substrate; every feature
(taskbar, launcher, tiling, OSK, …) is an extension. Tiers:
**kernel → core → standard**. Ergonomic for touch AND keyboard AND mouse.
## Stack
C++23 (gcc), Meson + Ninja (+ ccache), wlroots **0.20** (system, pinned,
`WLR_USE_UNSTABLE`), `wlr_scene` + wlr GLES2 renderer for compositing,
RMLUi (vendored Meson subproject via the cmake module) on a sibling
**GLES 3.2** EGL context (hardware-verified native), toml++ config
(`unbox.toml`), doctest for pure-core tests, wlr headless backend for
integration tests. Development runs NESTED under the live labwc session.
## The non-negotiable architecture rules
- **The kernel names NO concrete feature.** It owns: contracts (the ABI),
the extension host, the event/hook/service bus, backend/output/seat/scene
glue, and the UI substrate. Policies (tiling, bar contents, focus rules)
are extensions.
- **Contracts are the only cross-unit surface.** A unit's contract is its
PUBLIC headers: `packages/<unit>/include/unbox/<unit>/`. Private headers
live in `src/` and are invisible to everyone else. If you must read
another unit's `src/` to do your job, the contract is incomplete — report
up, never peek.
- **One owner per unit.** You may ONLY edit files in the unit you were
assigned. Cross-unit changes are change-requests reported up.
- **Lifetime is part of the contract type system.** `unique_ptr` = ownership
transfer; raw pointer/reference = non-owning borrow valid only for the
call; every hook subscription returns an RAII handle that unsubscribes on
destruction. Never a bare `wl_listener` across units.
- **Effects at the edges, pure decision cores.** Layout math, gesture
recognition, config parsing: pure input→output, heavily unit-tested.
Only thin glue touches wlroots/GL.
- **Hooks are error-isolated.** Events: fire-and-forget, N listeners,
exceptions caught at the boundary (a throwing extension gets disabled,
never the session). Filters: ordered value-in→value-out chains.
- **Cross-extension coupling anchors to exported TYPED symbols** (hook
descriptors, service handles). String-keyed lookups are forbidden — a
missing dependency must be a compile/link error.
- **Never block the event loop.** Single-threaded `wl_event_loop`; anything
slow is deferred/async. Frame budget on this GPU is precious.
## Commands
- `meson setup build` (once) · `ninja -C build` — build everything
- `ninja -C build <unit-target>` — build ONE unit (prefer this; the i5 is slow)
- `meson test -C build --suite <unit>` — that unit's tests
- Sanitizer dev build lives in `build-asan/` (separate dir, don't thrash ccache)
## Don'ts (each is a settled decision — see notes/plan.md §2)
- NO ANGLE, NO Vulkan, no GL translation layers (native GLES 3.2 verified).
- NO direct `#include <wlr/...>` — only via the kernel's extern-"C" wrapper.
- NO new third-party deps without surfacing to the user first.
- NO synonym coinage: check `GLOSSARY.md`; new terms need user sign-off.
## Testing (asymmetric — strict core, lenient shell)
Pure cores: doctest, zero mocks of our own modules (mocking `unbox::` is a
design bug — inject the effect instead). Glue/shell: a few integration tests
on the wlr headless backend; do not chase unit coverage there.
## Reports
Finish a task → write `reports/<unit>.md`: what you built, the public
surface, test output, contract gaps / change-requests. Reply tiny.
## Vocabulary
`GLOSSARY.md` is canonical (wlroots' own names preferred). Never invent a
synonym for an existing concept.
|
