# 1B Space Compositor Core (`one_os_compositor`)

> The foundation of the 1B Space Wayland-to-HTML5 compositor. Provides
> reusable OWL library components + Odoo backend models for running real
> Linux applications and displaying them natively inside the Odoo web client.

## What this addon provides

### Backend (Python)

- **`compositor.app`** — Application catalog (one record per Linux app you can
  launch, e.g. `gnome-calculator`, `xterm`, `kwrite`).
- **`compositor.session`** — Per-browser-tab compositor session (one per active
  OWL shell instance). Inherits `mail.thread` for tracking.
- **`compositor.audit.log`** — Append-only audit log (launch, terminate, crash
  events). Cannot be modified or deleted via the UI.
- **Controllers**:
  - `POST /web/compositor/token` — Issue a 15-min JWT (HS256) for the proxy.
  - `GET  /web/compositor/apps` — List apps the current user is allowed to launch.
  - `POST /web/compositor/launch` — Tell the proxy to spawn a sandboxed app.
  - `POST /web/compositor/terminate` — Tell the proxy to kill an app.
  - `POST /web/compositor/audit` — Ingestest endpoint called by the proxy.
- **Security**: groups `Compositor / User` and `Compositor / Manager`, with
  `ir.rule` so users only see their own sessions.

### Frontend (OWL library)

- **`@one_os_compositor/services/compositor_service`** — Reusable OWL service
  that wraps the WebSocket connection to the compositor proxy, manages JWT
  refresh, and exposes a clean API for embedding surfaces anywhere.
- **`@one_os_compositor/components/compositor_canvas`** — Reusable OWL
  component that creates a `<canvas>` element and binds it to a compositor
  session. Drop it anywhere in Odoo (action, form view, dashboard widget).
- **`@one_os_compositor/components/compositor_surface`** — Wraps a single
  Wayland surface as an embeddable component (e.g. "show calculator here").

Other addons can `import` these and use them like any other OWL service/component.

## Quick start (dev)

1. Install the addon:

   ```bash
   # Start Odoo dev server (auto-reload on save)
   cd /home/z/my-project/odoo-dev
   ./start-odoo.sh
   ```

2. Open http://localhost:8069, log in as `admin` / `admin`.

3. Go to **Apps → Update Apps List** (activate developer mode first).

4. Search for "1B Space Compositor Core", click **Install**.

5. Go to **1B OS → Compositor** — you'll see the app catalog. Click any app
   to launch it (currently stubbed — the Python proxy is in the sister addon
   `one_os_compositor_proxy`).

## Architecture

See `../../greenfield-analysis/` and `../../mit-compositor-analysis/` for the
full architectural analysis that informed this addon's design.

### Three-addon family

```
one_os_compositor            ← this addon (core OWL library + backend models)
  └─ one_os_compositor_shell ← full-screen desktop shell (taskbar, launcher)
  └─ one_os_compositor_proxy ← Python proxy bridge (aiohttp + pywayland + GStreamer)
```

### Reusability

Other 1B OS addons can use the compositor like this:

```js
import { compositorService } from "@one_os_compositor/services/compositor_service";

export class MyDashboard extends Component {
    setup() {
        this.compositor = useService("compositor");
    }

    async launchApp(appId) {
        // Spawns a sandboxed Linux app and embeds it as a Wayland surface
        const surface = await this.compositor.launchApp(appId);
        surface.attachTo(this.canvasRef.el);
    }
}
```

## License

Proprietary — 1B Space internal use only.

- **Author**: 1bspace.com
- **Parent company**: 1B Global
- **Maintainer**: dev@1bspace.com