WEFT_OS/.agents/skills/weft-servo-rendering/SKILL.md
Marco Allegretti 39869a2a38
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

72 lines
4 KiB
Markdown

---
name: weft-servo-rendering
description: Use for the Servo embedders, painting and presentation, the Servo fork and Stylo overrides, the system UI and application pages.
---
# Servo rendering and the forks
Owners: `weft-servo-shell` renders trusted system chrome; `weft-app-shell`
renders one untrusted application document and its narrow bridge. Neither holds
session lifecycle. Read the blueprint's
[Servo host contract](../../../BLUEPRINT.md#71-servo-host-contract),
[system interface](../../../BLUEPRINT.md#8-system-interface-and-application-behavior)
and [build policy](../../../BLUEPRINT.md#101-one-reproducible-product-build).
## Where things live
| Concern | Source |
|---|---|
| System shell host and event loop | [weft-servo-shell embedder](../../../crates/weft-servo-shell/src/embedder.rs), [main.rs](../../../crates/weft-servo-shell/src/main.rs) |
| Application host, `resolve_weft_app_url` (app ID and `ui.entry` to a `file://` URL), injected bridge | [weft-app-shell embedder](../../../crates/weft-app-shell/src/embedder.rs), [main.rs](../../../crates/weft-app-shell/src/main.rs) |
| Key mapping | [servo-shell keyutils](../../../crates/weft-servo-shell/src/keyutils.rs), [app-shell keyutils](../../../crates/weft-app-shell/src/keyutils.rs) |
| Shell protocol clients | [servo-shell client](../../../crates/weft-servo-shell/src/shell_client.rs), [app-shell client](../../../crates/weft-app-shell/src/shell_client.rs) |
| System UI page and UI kit | [system-ui.html](../../../infra/shell/system-ui.html), [weft-ui-kit.js](../../../infra/shell/weft-ui-kit.js) |
| Pin notes (not authoritative for the selected revision) | [SERVO_PIN.md](../../../crates/weft-servo-shell/SERVO_PIN.md) |
## Selected revisions
The Servo and Stylo revisions are the ones `Cargo.lock` records for the `servo`
and `stylo` packages, not a branch name or `SERVO_PIN.md`. Servo comes from the
`marcoallegretti/servo` fork; Stylo currently comes from upstream `servo/stylo`,
because no root-level override selects the `marcoallegretti/stylo` fork. Inspect
them with:
```sh
grep -A2 'name = "servo"' Cargo.lock
grep -A2 'name = "stylo"' Cargo.lock
```
Read the `servo` crate (`components/servo`), shared embedder input types and
rendering contexts at that revision before using an API. Servo's own `[patch]`
tables do not apply to WEFT: a Stylo override that a Servo-fork feature depends
on must be declared in WEFT's root `Cargo.toml` and confirmed in the resolved
graph. Each fork patch keeps a purpose, upstream status and removal condition.
For cross-repository work, clone the forks next to WEFT and point Cargo at them
with local `[patch]` entries outside the repository. Those overrides rewrite
`Cargo.lock`; never commit that change, and rerun checks without the overrides
before reporting evidence for the committed graph.
## Working rules
- A frame exists only after `WebView::paint` and the backend's present
operation. Event-loop progress, a READY message or a softbuffer present of an
unpainted buffer is not a rendered frame. Readback follows painting.
- Handle zero-size and minimized windows, resize, output scale, first frame,
idle wakeup and shutdown without continuous unbounded repainting.
- Keep the trust distinction: system-control endpoints and credentials never
reach application documents. Policy for package resources, navigation,
downloads, file URLs and network requests is enforced in the engine or OS, not
in page JavaScript.
- Treat manifest names, descriptions and icons as untrusted in the launcher; no
unsafe HTML injection. Use one endpoint configuration and bridge.
- Extract common host, render and input code only after one working path exists
in both hosts.
## Evidence
`python .agents/scripts/verify.py servo-embed` type-checks both hosts with the
real renderer. Without `servo-embed` the shells build as stubs; their success is
not rendering evidence. Rendering, input and backdrop or transparency claims need
the deterministic page and pixel checks described in
[integration verification](../weft-integration-verification/SKILL.md).