# 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.