one-os-dev-wayland-html5-compositor-mit-compositor-analysis/12-appendix.md

12 — Appendix: Glossary, File Index, References

Glossary

Wayland concepts

Same as Greenfield — see ../greenfield-analysis/12-appendix.md for the full Wayland glossary. Key terms: wl_display, wl_registry, wl_compositor, wl_surface, wl_seat, wl_keyboard, wl_pointer, wl_touch, wl_output, wl_shm, wl_buffer, wl_callback, wl_data_device_manager, wl_data_device, wl_data_source, wl_data_offer, wl_drm, wl_subcompositor, wl_subsurface, wl_region.

xdg-shell concepts

Same as Greenfield — xdg_wm_base, xdg_surface, xdg_toplevel, xdg_popup, xdg_positioner, configure, ack_configure.

MIT-approach-specific terms

Term	Meaning
Clean-room implementation	Software written by an engineer who has NOT read the source code of the original (AGPL) implementation. The engineer writes from a behavioral spec produced by a separate person who MAY have read the AGPL source. This protects against derivative-work claims.
Person A (spec author)	The engineer who writes the behavioral spec. MAY read AGPL source for reference. Does NOT write implementation code.
Person B (implementer)	The engineer who writes the implementation. MUST NOT read AGPL source. Implements from spec + MIT references only.
SPEC.md	The behavioral spec artifact (inputs/outputs/edge cases, NO code). Written by Person A.
CLEAN_ROOM_LOG.md	Legal-defensibility artifact documenting who read AGPL source, who didn't, when, what they referenced.
AFC test	Abstraction-Filtration-Comparison test, from Computer Associates v. Altai (1992). The legal test for derivative-work infringement in software. Even non-literal similarity (SSO: structure, sequence, organization) can be infringing.
AGPL §13	The network-use clause of AGPL-3.0. Requires offering source to all users interacting with the modified work over a network. The killer clause for proprietary web services.
GPL dynamic-linking exception	GPL applies to the entire combined work when statically linked. Dynamic linking is more permissive (LGPL allows it from proprietary code). FSF's strict interpretation says loading a GPL .so into a proprietary process contaminates it.
ProxyFD	JSON descriptor for a file descriptor sent over WebSocket: {handle, type, host}. Same as Greenfield — see ../greenfield-analysis/04-transport.md.

Python-specific terms

Term	Meaning
pywayland	Python bindings to libwayland-server, via cffi. Apache-2.0 licensed.
pywlroots	Python bindings to libwlroots. NCSA/UIUC license (BSD-like). NOT RECOMMENDED — operates above wire-dispatch layer, incompatible with Greenfield's architecture.
python-xkbcommon	The xkbcommon PyPI package. Python bindings to libxkbcommon. MIT licensed.
PyGObject	Python bindings to GLib/GObject. LGPL-2.1+. Provides gi.repository.Gst for GStreamer.
cffi	C Foreign Function Interface for Python. Used to call C functions from Python without writing a C extension.
asyncio	Python's async I/O framework, built into the standard library.
aiohttp	Async HTTP + WebSocket server framework for Python. Apache-2.0.
multiprocessing.Process	Python's process-spawning primitive. Used to fork one child per Odoo session.
multiprocessing.reduction.send_handle	Function to pass an open file descriptor from one Python process to another (uses SCM_RIGHTS on Linux).
GLib MainLoop	GLib's event loop, required by GStreamer. Runs in a separate Python thread.
asyncio.run_coroutine_threadsafe	Function to schedule a coroutine on an asyncio event loop from a different thread. Used to marshal GStreamer results back to asyncio.
bubblewrap (bwrap)	Unprivileged sandboxing tool. LGPL-2.0+. Used by Flatpak.
seccomp BPF	Linux kernel feature for filtering syscalls. Compiled to BPF bytecode, loaded via bwrap --seccomp <memfd>.
systemd-run --scope	systemd command to run a process in a transient cgroup. Used for memory/CPU/PID limits.
memfd_create	Linux syscall to create an anonymous in-memory file. Python 3.8+ has os.memfd_create(). Replaces Greenfield's createMemoryMappedFile native addon.

Browser-specific terms

Term	Meaning
WebGL2	Next-gen WebGL API. Uniform buffer objects, transform feedback, simplified shaders. 97%+ browser support.
WebCodecs	W3C standard for native video decode/encode in the browser. VideoDecoder, VideoEncoder, EncodedVideoChunk, VideoFrame. Replaces FFmpeg Wasm.
OffscreenCanvas	W3C standard for canvas rendering in a Web Worker. Allows WebGL to run off the main thread.
Web Workers	W3C standard for running JavaScript in background threads.
SharedArrayBuffer + Atomics	W3C standard for zero-copy shared memory between workers. Needs COOP/COEP headers.
ImageBitmap	W3C standard for a GPU-backed bitmap. Transferable between workers. Used by the web-bitmapbuf fast path.
WebTransport	W3C standard (in progress) for UDP-over-QUIC transport. Future replacement for WebSocket+KCP.
OpenH264	BSD-2-Clause H.264 codec. Cisco's binary release. Used as fallback when WebCodecs is unavailable.

File-to-feature index

Custom browser compositor (PROPRIETARY, clean-room TS)

File	Role
packages/compositor/src/index.ts	Public API: createCompositorSession()
packages/compositor/src/core/Session.ts	Top-level session
packages/compositor/src/core/Compositor.ts	wl_compositor global
packages/compositor/src/core/Globals.ts	Wayland globals registry
packages/compositor/src/surface/Surface.ts	wl_surface, double-buffered state
packages/compositor/src/surface/SurfaceRole.ts	Role abstraction
packages/compositor/src/surface/Subsurface.ts	wl_subsurface
packages/compositor/src/surface/Subcompositor.ts	wl_subcompositor global
packages/compositor/src/surface/Region.ts	wl_region (pixman-WASM)
packages/compositor/src/surface/FrameCallback.ts	wl_callback
packages/compositor/src/render/Renderer.ts	4-phase render pipeline (WebGL2 + OffscreenCanvas)
packages/compositor/src/render/Scene.ts	One per output
packages/compositor/src/render/View.ts	Positioned surface
packages/compositor/src/render/Output.ts	wl_output, OffscreenCanvas binding
packages/compositor/src/render/RenderState.ts	Per-view-per-scene texture + transform
packages/compositor/src/render/Texture.ts	WebGL2 texture wrapper
packages/compositor/src/render/Loop.ts	requestAnimationFrame integration
packages/compositor/src/render/shaders/YUVA2RGBA.glsl	BT.601 YUVA → RGBA
packages/compositor/src/render/shaders/RGBandA2RGBA.glsl	RGB+Alpha → RGBA
packages/compositor/src/render/shaders/SceneShader.glsl	Final pass: textured quads
packages/compositor/src/buffer/Shm.ts	wl_shm, BMP-header hack
packages/compositor/src/buffer/BufferContents.ts	Buffer abstraction (mimeType)
packages/compositor/src/buffer/ImageBitmapBuffer.ts	web-bitmapbuf fast path
packages/compositor/src/buffer/EncodedFrameBuffer.ts	H.264/PNG from proxy
packages/compositor/src/transport/Channel.ts	ARQChannel + SimpleChannel
packages/compositor/src/transport/kcp.ts	Ported fresh from MIT C ref (skywind3000/kcp)
packages/compositor/src/transport/ReconnectingWebSocket.ts	Vendored from pladaria (MIT)
packages/compositor/src/transport/BufferStream.ts	Serial → frame promise resolution
packages/compositor/src/transport/StreamingBuffer.ts	Per-surface encoded-frame buffer
packages/compositor/src/transport/EncodedFrame.ts	Wire format parser
packages/compositor/src/transport/EncoderFeedback.ts	4-byte decode feedback, 1 Hz
packages/compositor/src/transport/RemoteInputOutput.ts	FD-over-WebSocket for native apps
packages/compositor/src/transport/RemoteAppLauncher.ts	Channel setup per app
packages/compositor/src/transport/decoders/WebCodecsFrameDecoder.ts	WebCodecs VideoDecoder (HW-accelerated)
packages/compositor/src/transport/decoders/OpenH264FrameDecoder.ts	OpenH264 BSD Wasm fallback
packages/compositor/src/input/Seat.ts	wl_seat global
packages/compositor/src/input/Keyboard.ts	wl_keyboard
packages/compositor/src/input/Pointer.ts	wl_pointer
packages/compositor/src/input/Touch.ts	wl_touch (REAL implementation, not stub)
packages/compositor/src/input/Xkb.ts	@gfld/compositor-wasm wrapper (REUSED MIT)
packages/compositor/src/input/InputQueue.ts	Event coalescing
packages/compositor/src/input/InputOutput.ts	FD abstraction
packages/compositor/src/roles/XdgWmBase.ts	xdg_wm_base global
packages/compositor/src/roles/XdgSurface.ts	xdg_surface role
packages/compositor/src/roles/XdgToplevel.ts	xdg_toplevel role
packages/compositor/src/roles/XdgPopup.ts	xdg_popup role
packages/compositor/src/roles/XdgPositioner.ts	xdg_positioner
packages/compositor/src/roles/Shell.ts	wl_shell (legacy, optional)
packages/compositor/src/roles/ShellSurface.ts	wl_shell_surface (legacy, optional)
packages/compositor/src/data/DataDeviceManager.ts	wl_data_device_manager
packages/compositor/src/data/DataSource.ts	wl_data_source
packages/compositor/src/data/DataOffer.ts	wl_data_offer
packages/compositor/src/data/PrimarySelectionDeviceManager.ts	NEW: zwp_primary_selection_v1
packages/compositor/src/desktop/Desktop.ts	Floating vs AlwaysFullScreen
packages/compositor/src/desktop/FloatingDesktopSurface.ts	Default floating mode
packages/compositor/src/userapi/UserShellApi.ts	OWL shell integration seam
packages/compositor/src/browser/input.ts	DOM keyboard events
packages/compositor/src/browser/pointer.ts	DOM pointer events
packages/compositor/src/browser/touch.ts	DOM touch events (NEW)
packages/compositor/src/browser/dnd.ts	DnD bridge (NEW: native→DOM DnD)
packages/compositor/src/browser/selection.ts	Clipboard bridge
packages/compositor/src/math/Mat4.ts	4×4 matrix
packages/compositor/src/math/Rect.ts	Rectangle math

Custom Python proxy (PROPRIETARY, ~2880 LOC)

File	Role
compositor_proxy/main.py	HTTP + WS hub, forks per session
compositor_proxy/session.py	Top-level proxy session
compositor_proxy/session_controller.py	aiohttp WS server with 9 endpoints
compositor_proxy/jwt_auth.py	JWT validation (pyjwt)
compositor_proxy/native_app_context.py	Per-app state, signaling WS, kill timers, bwrap spawn
compositor_proxy/native_wayland_client_session.py	Per-client message dispatcher
compositor_proxy/native_wayland_compositor_session.py	Display creation, initShm, initDrm
compositor_proxy/channel.py	ARQChannel + SimpleChannel (clean-room)
compositor_proxy/kcp_adapter.py	kcp PyPI package integration
compositor_proxy/frame_feedback.py	Receives 4-byte decode feedback
compositor_proxy/proxy_buffer.py	Proxy-side buffer representation
compositor_proxy/surface_buffer_encoding.py	Encoding pipeline orchestration
compositor_proxy/xwayland_session.py	XWayland spawn + bridge
compositor_proxy/wayland_server.py	pywayland wrapper + cffi shim
compositor_proxy/io/	WebSocket server glue
compositor_proxy/encoding/gst_encoder.py	GStreamer H.264/PNG encoder (~700 LOC)
compositor_proxy/encoding/adaptive_bitrate.py	Adaptive bitrate controller (NEW)
compositor_proxy/encoding/glib_thread.py	GLib MainLoop in separate thread
compositor_proxy/sandbox.py	bubblewrap + seccomp + systemd-run wrappers

Reused from Greenfield (MIT/Apache)

Path	Role
greenfield/protocol/wayland.xml	Upstream Wayland core (MIT)
greenfield/protocol/xdg-shell.xml	Stable xdg-shell (MIT)
greenfield/protocol/wayland-drm.xml	Legacy wl_drm (MIT)
greenfield/protocol/web-bitmapbuf-unstable-v1.xml	Greenfield's custom extension (MIT)
greenfield/libs/common/src/Connection.ts	Wire format codec (REUSED)
greenfield/libs/compositor-protocol/src/	Server-side runtime + generated bindings (REUSED)
greenfield/libs/client-protocol/src/	Client-side runtime + generated bindings (REUSED)
greenfield/libs/compositor-wasm/src/	pixman + xkbcommon WASM (REUSED)
greenfield/libs/xtsb/	X11 TypeScript bindings (REUSED, only if XWayland)
greenfield/libs/client-generator/	Browser client bindings generator (REUSED)
greenfield/libs/compositor-generator/	Browser server bindings generator (REUSED)
greenfield/packages/compositor-proxy/native/wayland/src/westfield-buffer.c	Buffer helpers (REUSED, MIT)
greenfield/packages/compositor-proxy/native/wayland/src/westfield-dmabuf.c	DMA-BUF import (REUSED, MIT)
greenfield/packages/compositor-proxy/native/wayland/src/westfield-egl.c	EGL zero-copy setup (REUSED, MIT)
greenfield/packages/compositor-proxy/native/wayland/src/westfield-xwayland.c	XWayland bridge (REUSED as reference, ported to Python)
greenfield/packages/compositor-proxy/native/wayland/src/wlr_drm.c	wl_drm global impl (REUSED, MIT, vendored from wlroots)
greenfield/packages/compositor-proxy/native/wayland/src/wlr_linux_dmabuf_v1.c	zwp_linux_dmabuf_v1 global impl (REUSED, MIT, vendored from wlroots)
greenfield/packages/compositor-proxy/native/wayland/src/drm_format_set.c	DRM format helpers (REUSED, MIT, vendored from wlroots)
greenfield/packages/compositor-proxy/native/wayland/src/wayland-server/changes.diff	Patches to libwayland-server (REUSED, MIT, optional for fast-sync)

Odoo 20 backend addon

Path	Role
compositor_shell/__manifest__.py	Addon manifest
compositor_shell/models/compositor_app.py	App catalog model
compositor_shell/models/compositor_session.py	Session model (mail.thread)
compositor_shell/models/compositor_audit_log.py	Append-only audit log
compositor_shell/controllers/main.py	HTTP controllers (token, apps, launch, audit)
compositor_shell/security/compositor_security.xml	Groups + rules
compositor_shell/security/ir.model.access.csv	ACLs
compositor_shell/views/compositor_app_views.xml	App management views
compositor_shell/views/compositor_session_views.xml	Session views
compositor_shell/views/ir_actions_client_views.xml	OWL action registration
compositor_shell/static/src/components/compositor_shell.js	OWL shell component
compositor_shell/static/src/components/compositor_shell.xml	OWL template
compositor_shell/static/src/components/compositor_shell.scss	Styles
compositor_shell/static/src/lib/compositor_lib/	Custom browser compositor library (clean-room TS)

External references

Wayland protocol

• Wayland documentation: https://wayland.freedesktop.org/docs/html/
• Wayland protocol XML: https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/protocol/wayland.xml
• xdg-shell protocol: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/stable/xdg-shell/xdg-shell.xml
• wayland-drm protocol: https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/protocol/wayland.xml
• linux-dmabuf-unstable-v1: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml

libwayland + pywayland

• libwayland source: https://gitlab.freedesktop.org/wayland/wayland
• Wayland book: https://wayland-book.com/
• pywayland docs: https://pywayland.readthedocs.io/
• pywayland source: https://github.com/flacjacket/pywayland
• pywayland on PyPI: https://pypi.org/project/pywayland/

wlroots + pywlroots

• wlroots source: https://gitlab.freedesktop.org/wlroots/wlroots
• wlroots mirror: https://github.com/swaywm/wlroots
• pywlroots source: https://github.com/flacjacket/pywlroots
• Smithay (Rust alternative): https://github.com/Smithay/smithay

xkbcommon + python-xkbcommon

• xkbcommon homepage: https://xkbcommon.org/
• xkbcommon source: https://github.com/xkbcommon/libxkbcommon
• xkbcommon on PyPI: https://pypi.org/project/xkbcommon/

GStreamer + PyGObject

• GStreamer homepage: https://gstreamer.freedesktop.org/
• GStreamer Python bindings (gst-python): https://github.com/GStreamer/gst-python
• PyGObject docs: https://pygobject.readthedocs.io/
• GStreamer tutorials: https://gstreamer.freedesktop.org/documentation/tutorials/index.html
• GStreamer GL plugins: https://gstreamer.freedesktop.org/documentation/opengl/index.html
• vaapih264enc docs: https://gstreamer.freedesktop.org/documentation/vaapi/index.html
• nvh264enc docs: https://gstreamer.freedesktop.org/documentation/nvcodec/index.html
• openh264enc docs: https://gstreamer.freedesktop.org/documentation/openh264/index.html

OpenH264 (BSD fallback decoder)

• OpenH264 source: https://github.com/cisco/openh264
• Cisco binary releases: https://github.com/cisco/openh264/releases

WebCodecs + WebGL2 + OffscreenCanvas

• WebCodecs API (MDN): https://developer.mozilla.org/en-US/docs/Web/API/WebCodecs_API
• VideoDecoder (MDN): https://developer.mozilla.org/en-US/docs/Web/API/VideoDecoder
• WebGL2 (MDN): https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext
• OffscreenCanvas (MDN): https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
• Web Workers (MDN): https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API
• SharedArrayBuffer (MDN): https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
• WebTransport (MDN): https://developer.mozilla.org/en-US/docs/Web/API/WebTransport
• WebCodecs samples: https://w3c.github.io/webcodecs/samples/

KCP

• KCP protocol (skywind3000): https://github.com/skywind3000/kcp
• KCP documentation: https://skywind3000.github.io/kcp/
• kcp on PyPI (RealistikDash): https://pypi.org/project/kcp/

asyncio + aiohttp

• asyncio docs: https://docs.python.org/3/library/asyncio.html
• aiohttp docs: https://docs.aiohttp.org/
• aiohttp WebSocket: https://docs.aiohttp.org/en/stable/web_advanced.html#websockets

JWT

• PyJWT docs: https://pyjwt.readthedocs.io/
• JWT.io: https://jwt.io/
• RFC 7519 (JWT): https://datatracker.ietf.org/doc/html/rfc7519

Sandboxing

• bubblewrap docs: https://github.com/containers/bubblewrap
• libseccomp: https://github.com/seccomp/libseccomp
• Flatpak sandboxing: https://docs.flatpak.org/en/latest/sandbox-permissions.html
• cgroups v2: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html
• systemd-run: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Odoo 20

• Odoo 20 documentation: https://www.odoo.com/documentation/20.0/
• Odoo OWL framework: https://github.com/odoo/owl
• Odoo OWL migration guide (Odoo 19→20): https://www.odoo.com/documentation/20.0/developer/howtos/owl_migration.html
• Odoo controller patterns: https://www.odoo.com/documentation/20.0/developer/howtos/routing.html
• Odoo security: https://www.odoo.com/documentation/20.0/developer/howtos/security.html

Greenfield (for reference, NOT for clean-room implementers)

• Greenfield homepage: https://www.greenfield.app
• Greenfield source: https://github.com/udevbe/greenfield
• Greenfield design docs: https://github.com/udevbe/greenfield/blob/master/docs/pages/design/index.md
• Greenfield MIT libs (REUSABLE): https://github.com/udevbe/greenfield/tree/master/libs
• Greenfield AGPL packages (DO NOT READ for clean-room): https://github.com/udevbe/greenfield/tree/master/packages

Westfield (Greenfield's predecessor, MIT)

• Westfield source: https://github.com/udevbe/westfield
• Note: Contains ONLY the protocol infrastructure (same as Greenfield's MIT libs). NEVER had the in-browser compositor logic.

Reference Wayland compositors (MIT, for clean-room spec authors)

• wlroots (C, MIT): https://gitlab.freedesktop.org/wlroots/wlroots — reference for compositor patterns
• Weston (C, MIT): https://gitlab.freedesktop.org/wayland/weston — reference Wayland compositor
• Smithay (Rust, MIT): https://github.com/Smithay/smithay — Rust compositor library
• wprs (Rust, MIT): https://github.com/Smithay/wprs — Rust wayland-xpra, mirrors Greenfield's architecture almost exactly

Pointers to the user's next steps

1. Read the comparison document: ../Greenfield-vs-MIT-Comparison.md for the head-to-head analysis and final recommendation.

2. If you choose the MIT approach (recommended):

   • Phase 0: Spike (1 week) — validate libwayland ↔ asyncio integration
   • Phase 1: Browser compositor MVP (25 weeks, clean-room TS)
   • Phase 2: Python proxy MVP (3.5 weeks, aiohttp + pywayland + GStreamer)
   • Phase 3: Odoo integration (3.5 weeks, OWL shell + backend addon + JWT)
   • Phase 4: Sandboxing v1 (1.5 weeks, bubblewrap + seccomp)
   • Phase 5: Polish & testing (3 weeks)

3. Critical first step: Set up the clean-room process.

   • Designate Person A (spec author) and Person B (implementer)
   • Person A reads Greenfield AGPL source + writes SPEC.md
   • Person B implements from SPEC.md + MIT references only
   • Maintain CLEAN_ROOM_LOG.md as a legal-defensibility artifact

4. CI/CD license hygiene gates: Add the 4 license checks to your CI pipeline from day one. See 11-pitfalls.md for the commands.

5. Engage legal counsel before starting the clean-room process. This bundle is engineering analysis, not legal advice.