Greenfield Architecture Analysis — for an Odoo 20 + JS/Python Wayland-to-HTML Compositor

Purpose of this bundle. A deep, source-level architectural analysis of the Greenfield repository (https://github.com/udevbe/greenfield, commit 6c578f4, 1.0.0-rc1) written specifically for an engineering team that is about to build its own Wayland-to-HTML compositor. The target stack is JavaScript (browser) + Python (host) + Odoo 20 addon shell. Greenfield is treated purely as a reference implementation; the actual Greenfield UI shell (packages/compositor-shell) is explicitly out of scope — the user will supply their own Odoo 20 OWL shell.

How to read this bundle

The bundle is split into 13 Markdown files. They are designed to be read in order, but each file is self-contained and can be read alone if you only need one layer. Files are organized from the highest-level view down to the implementation-level details, then the porting blueprint, then pitfalls.

#	File	What you'll find inside
0	00-overview.md	What Greenfield is, repo layout, package inventory, tech stack table, ASCII architecture diagram.
1	01-architecture.md	Layer-by-layer map from Wayland XML → generators → runtime → transport → rendering.
2	02-wayland-protocol.md	Protocol layer: 3 generators, wire format, object lifecycle, FD transport, custom web-bitmapbuf extension.
3	03-html5-rendering.md	Surface → canvas compositing pipeline: Surface state, damage, FrameLoop, WebGL shaders, multi-output.
4	04-transport.md	WebSocket + KCP-over-WebSocket, multi-channel design, message formats, FD virtualization, reconnection.
5	05-input-handling.md	Keyboard / pointer / touch / focus, xkbcommon WASM, keymap FD workaround, DOM → Wayland event mapping.
6	06-data-clipboard.md	wl_data_device, selection, drag-and-drop, MIME negotiation, XWayland bridge, primary-selection gap.
7	07-native-app-bridge.md	How real Linux apps get launched, the 3 native Node addons, XWayland bridge, app lifecycle & kill timers.
8	08-app-lifecycle.md	xdg-shell state machine, configure/ack round-trips, popup positioner math, subsurface sync, UserShellApi.
9	09-hardware-accel.md	GStreamer H.264 encoders, WASM FFmpeg fallback, WebCodecs preferred path, WebGL texture upload, alpha split.
10	10-porting-to-odoo-js-python.md	Concrete blueprint for porting each Greenfield layer to JS browser compositor + Python host proxy + Odoo 20 OWL shell.
11	11-pitfalls.md	21 catalogued pitfalls + 12 design wins, with file references and what-to-do-instead for each.
12	12-appendix.md	Glossary, file-to-feature index, external references.

Recommended reading order

• Architects / tech leads — read 00 → 01 → 11 → 10. You'll get the lay of the land, what to copy, what to avoid, and the porting blueprint.
• Browser-compositor engineers — read 02 → 03 → 04 → 05 → 08 → 09. The core engine chapters, in dependency order.
• Host-proxy engineers (Python) — read 07 → 04 → 09 → 02 (proxy generator section) → 10. Most of the porting work is on your side.
• Odoo 20 OWL shell engineers — read 08 (especially the UserShellApi section) → 01 → 10 (Odoo integration section). The shell is the integration seam where Greenfield stops and your work begins.
• Skip-it sections — 06 (clipboard) is only needed if you care about clipboard sync between browser and native apps.

Scope & exclusions

In scope — every Greenfield package, lib, generator, native addon, protocol file, transport channel, rendering path, encoding pipeline, and the UserShellApi integration seam.

Out of scope — the actual packages/compositor-shell Preact+Tailwind SPA. The user is building their own shell as an Odoo 20 addon. We only describe the protocol-level integration point (UserShellApi) so the Odoo shell knows what to consume.

Not covered in depth — the sdk/ (Emscripten-based WASM app SDK for browser-resident Wayland apps). Mentioned in 00-overview.md and 10-porting-to-odoo-js-python.md but not analyzed layer-by-layer, because the user's goal is running real Linux apps in the browser, not browser-resident WASM apps.

Conventions

• File paths are always relative to the repo root, e.g. packages/compositor/src/Surface.ts.
• ASCII diagrams are used throughout — they render correctly in any Markdown viewer, survive copy-paste, and work in code reviews.
• No code excerpts by user request. We describe algorithms in prose and reference file paths so you can read the source yourself.
• Cross-references look like (see §3 of 03-html5-rendering.md).

How this analysis was produced

This bundle was produced by 10 parallel research agents, each assigned to a single layer of the Greenfield codebase:

• Agent A — top-level architecture
• Agent B — Wayland protocol layer (generators + runtime)
• Agent C — HTML5 rendering pipeline
• Agent D — transport layer (WebSocket + KCP)
• Agent E — input handling (keyboard / pointer / touch / xkbcommon)
• Agent F — data device & clipboard
• Agent G — native app bridge (process model + native addons)
• Agent H — xdg-shell / app lifecycle / UserShellApi
• Agent I — hardware acceleration / encoding / WASM
• Agent J — pitfalls, anti-patterns, design wins

Each agent read the relevant source files end-to-end, produced a stage summary, and appended its findings to /home/z/my-project/worklog.md. This bundle is the synthesis of those findings into a single readable document set.

License of the source

Greenfield's runtime packages (compositor, compositor-proxy, compositor-proxy-cli, compositor-shell) are AGPL-3.0-or-later. The lower-level libs (generators, common, compositor-wasm, compositor-ffmpeg-h264, xtsb) are MIT or Apache-2.0. Anyone forking or building on the runtime packages must respect AGPL — see 11-pitfalls.md §License for implications.