Initial commit: Greenfield architectural analysis (14 files, ~80 pages, 10 parallel research agents)

README.md

@@ -0,0 +1,103 @@
+# 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.