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

4 KiB

name description
weft-servo-rendering 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, system interface and build policy.

Where things live

Concern Source
System shell host and event loop weft-servo-shell embedder, main.rs
Application host, resolve_weft_app_url (app ID and ui.entry to a file:// URL), injected bridge weft-app-shell embedder, main.rs
Key mapping servo-shell keyutils, app-shell keyutils
Shell protocol clients servo-shell client, app-shell client
System UI page and UI kit system-ui.html, weft-ui-kit.js
Pin notes (not authoritative for the selected revision) 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:

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.