2026-03-10 17:47:06 +00:00
# WEFT OS
2026-03-12 14:41:33 +00:00
WEFT OS is a Wayland compositor and application runtime where every app is a WebAssembly component rendered in an isolated Servo WebView. No capability is granted by default; all resource access is declared in a per-app manifest and enforced at runtime.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
## What is implemented
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**Compositor** — `weft-compositor` is a Smithay-based Wayland compositor with DRM/KMS and winit backends. It implements the `zweft-shell-unstable-v1` protocol extension, which typed shell slots (panel, application) register against.
2026-03-10 17:47:06 +00:00
fix(shells): paint and present Servo frames and report readiness truthfully
With servo-embed, weft-servo-shell and weft-app-shell did not compile
against the selected Servo revision: the keyboard event shape, key and
mouse action variants, frame readback, shutdown, URL type and window
handle APIs had changed. The frame path never called WebView::paint; the
software path rebuilt its softbuffer surface every frame and read pixels
without painting, and the EGL path presented nothing. weft-app-shell
printed READY right after creating its WebView, before any frame, and its
feature-disabled build printed READY and parked. Servo also disables CSS
Grid by default, which the system UI uses.
Both hosts now build against the selected API. Each frame is painted with
WebView::paint and presented: the software path reads the painted frame
back, presents the context and copies it into a persistent softbuffer
surface; the EGL path presents its window context. Nothing is presented
before Servo's first repaint request. Shutdown drops the WebView and
Servo, whose drop completes the shutdown, and exits the event loop. Both
hosts enable layout_grid_enabled.
weft-app-shell prints READY on the first frame presented after the
document has loaded and Servo reports its rendering settled: on load
completion it requests WebView::take_screenshot, which completes only once
every frame has fired load, render-blocking resources, images and web
fonts are done and the rendering is up to date. Feature-disabled builds of
both hosts exit with an error instead of reporting readiness. weft-appd
does not consume the app shell's READY yet.
tests/frame/check_frame.py runs weft-compositor nested on Xvfb with the
winit backend, starts a host showing tests/frame/reference.html and checks
the presented pixels (four colour quadrants and text). For the app host
the page must be on screen within two seconds of READY; --slow-style
delays a render-blocking stylesheet that reveals the page, so premature
readiness fails.
Validation (Ubuntu 24.04, Mesa 25.2.8 llvmpipe, software path):
- check_frame.py --host system, --host app and --host app --slow-style 3:
5 of 5 runs pass each
- negative fixtures fail: page with red and green swapped; a fake host
printing READY without rendering; a local build printing READY on its
first presented frame (--slow-style 4, 3 of 3)
- cargo clippy -D warnings with and without servo-embed; cargo fmt --check
- unverified: EGL path, DRM, resize, output scale, idle wakeup, input
2026-10-09 01:02:26 +00:00
**System shell** — `weft-servo-shell` embeds Servo (feature-gated, `--features servo-embed` ) and renders `system-ui.html` as a Wayland panel. Without `servo-embed` , the binary exits with an error instead of rendering. Navigation gestures from the compositor are forwarded to `weft-appd` over WebSocket.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**App shell** — `weft-app-shell` is a per-process Servo host for application WebViews. It resolves `weft-app://<id>/ui/index.html` , injects a `weftIpc` WebSocket bridge into the page, and registers with the compositor as an application surface. Also feature-gated behind `servo-embed` .
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**App daemon** — `weft-appd` supervises sessions: spawns `weft-runtime` , waits for READY, spawns `weft-app-shell` , manages the per-session IPC relay between the Wasm component and the WebView, and handles session teardown. Wraps processes in systemd scopes (`CPUQuota=200%`, `MemoryMax=512M` ) when available.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**Runtime** — `weft-runtime` runs WASI Component Model binaries under Wasmtime 30 (`--features wasmtime-runtime`). Provides `weft:app/notify` , `weft:app/ipc` , `weft:app/fetch` , `weft:app/notifications` , and `weft:app/clipboard` host imports. Preopens filesystem paths according to declared capabilities.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**Package management** — `weft-pack` handles check, sign, verify, install, uninstall, list, build-image (EROFS dm-verity), and info. Validates capability strings at check time.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**File portal** — `weft-file-portal` is a per-session file proxy with a path allowlist and `..` blocking.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**Mount helper** — `weft-mount-helper` is a setuid helper for EROFS dm-verity mount/umount via `veritysetup` .
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
**Demo apps** — `examples/org.weft.demo.counter` and `examples/org.weft.demo.notes` are pre-built Wasm Component binaries (`wasm32-wasip2`, wit-bindgen 0.53) with HTML UIs, signed with a committed demo keypair.
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
## Repository layout
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
```
crates/ Rust workspace members
examples/ Demo app packages (wasm32-wasip2, not workspace members)
keys/ Demo Ed25519 keypair
protocol/ zweft-shell-unstable-v1 Wayland protocol XML
infra/
nixos/ NixOS VM configuration and package derivations
scripts/ check.ps1, check.sh
shell/ system-ui.html, weft-ui-kit.js
systemd/ service unit files
vm/ build.sh, run.sh (QEMU)
docs/
architecture.md Component map, IPC, capability table, env vars
2026-03-12 19:45:56 +00:00
security.md Capability model, process isolation, SpiderMonkey security boundary
2026-03-12 14:41:33 +00:00
building.md Build instructions for all targets
```
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
## Building
2026-03-11 11:59:24 +00:00
2026-03-12 19:48:17 +00:00
Linux system packages required (openSUSE):
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
```sh
2026-03-12 19:48:17 +00:00
sudo zypper install -y \
2026-03-12 19:52:34 +00:00
libwayland-devel libxkbcommon-devel libglvnd-devel \
libgbm-devel libdrm-devel libinput-devel seatd-devel libudev-devel \
2026-03-12 19:48:17 +00:00
systemd-devel pkg-config clang cmake python3
2026-03-12 14:41:33 +00:00
```
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
Build non-Servo crates:
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
```sh
cargo build --workspace --exclude weft-servo-shell --exclude weft-app-shell
```
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
Build Linux-only crates (no Servo):
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
```sh
cargo build -p weft-compositor -p weft-servo-shell -p weft-app-shell
```
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
Build with Servo embedding (30– 60 min, requires clang + python3):
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
```sh
cargo build -p weft-servo-shell --features servo-embed
cargo build -p weft-app-shell --features servo-embed
```
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
See `docs/building.md` for full instructions including Wasm component builds, NixOS VM, and signing.
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
## CI
2026-03-10 17:47:06 +00:00
2026-10-08 23:48:37 +00:00
Four jobs on every push to `main` and on pull requests:
2026-03-10 17:47:06 +00:00
2026-10-09 08:16:59 +00:00
- `portable` — fmt, clippy and tests for the crates that need no Linux system libraries
2026-03-12 14:41:33 +00:00
- `linux-only` — clippy and tests for compositor and shell crates
- `servo-embed-linux` — `cargo check --features servo-embed` for both servo crates
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
- `contributor-toolkit` — links, metadata and catalog of the contributor toolkit, and runner tests
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
## Security
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
See `docs/security.md` . Key points:
2026-03-10 17:47:06 +00:00
2026-03-12 14:41:33 +00:00
- Capabilities declared in `wapp.toml` , validated at install, enforced at runtime
- Per-app OS processes with systemd cgroup limits
- WASI filesystem isolation via preopened directories
- Ed25519 package signing; optional EROFS dm-verity
- Optional seccomp BPF blocklist in `weft-runtime`
2026-03-12 19:45:56 +00:00
- SpiderMonkey is not sandbox-isolated beyond process-level isolation (see `docs/security.md` )
2026-03-11 11:59:24 +00:00
2026-03-12 14:41:33 +00:00
## Servo fork
2026-03-10 17:47:06 +00:00
build: select compiling Servo and Stylo fork revisions
Both Servo hosts tracked the marcoallegretti/servo `servo-weft` branch,
which the lockfile resolved to 8e7dc40. That revision's servo-layout does
not compile (E0308 and E0716 in build_backdrop_filter). WEFT also resolved
upstream Stylo dca3934, where backdrop-filter is gated behind
layout.unimplemented, because the Servo fork's own [patch] for Stylo does
not apply to dependents.
Pin Servo by revision to f0bb1aa (8e7dc40 plus the build fix) and add a
root [patch."https://github.com/servo/stylo"] selecting the
marcoallegretti/stylo fork at f1ba496 for all eight Stylo crates Servo
uses. Cargo.lock changes only the 66 source lines of those packages.
Record both pins, their reachable branches, purpose and removal
conditions in SERVO_PIN.md, and restate its limitations against executed
evidence. Update the Nix outputHashes: the Stylo hash is recomputed for
f1ba496 with the method that reproduces the previous dca3934 value; the
Servo hash is not yet known for f0bb1aa and is left as lib.fakeHash, so
Nix builds report the expected value instead of using a stale one.
Validation:
- cargo metadata --locked: ok; no servo/stylo sources remain in the lock
- cargo check -p weft-servo-shell --features servo-embed --locked:
all of Servo, including servo-layout, compiles; the remaining errors are
in the shell's own embedder code
- cargo fmt --check; portable workspace tests: 78 passed
- Nix fetchgit could not run here (archive downloads and the sandbox's
TLS to the proxy fail), so the Servo hash remains unverified
2026-10-09 00:13:08 +00:00
- Servo: `https://github.com/marcoallegretti/servo` at `f0bb1aaf` , pinned by revision
- Stylo: `https://github.com/marcoallegretti/stylo` at `f1ba4969` , through the root `[patch]`
- Patches: `backdrop-filter` parsing (Stylo) and rendering (Servo)
2026-03-12 19:45:56 +00:00
- See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
## Contributing
See [CONTRIBUTING.md ](CONTRIBUTING.md ). [AGENTS.md ](AGENTS.md ) is the engineering contract and [BLUEPRINT.md ](BLUEPRINT.md ) the accepted direction toward `0.1.0` .