fenestra: Instructions file for Codex

Building fenestra UIs as an agent

fenestra is designed so that an agent authoring a UI can see and verify its work without a display server. This file is the working manual.

The loop

1. Write a view (or a full App).
2. Drive it with the harness — semantic queries, not coordinates — and assert structure and messages.
3. Render it headlessly to a PNG. Open and look at the PNG. Layout bugs, clipped text, and bad spacing are visible; do not skip this.
4. Iterate until it looks right, then lock it with a golden test.

use fenestra::prelude::*;
use fenestra::shell::render_element;

let view: Element<()> = col().p(SP6).gap(SP4).children([
    text("Hello").size(TextSize::Xl2).weight(Weight::Semibold),
    button("Save").into(),
]);
let image = render_element(view, &Theme::light(), (480, 240));
image.save("preview.png").unwrap(); // now actually look at it

Headless rendering is deterministic: embedded Inter fonts, scale 1.0, reduced motion, in-memory clipboard. The same tree renders the same pixels on every machine of the same GPU class (cross-rasterizer runs use a small tolerance; see Golden tests).

Driving a real app: the harness

Harness runs the full Elm loop — dispatch, state, focus, editing — driven by semantic queries (find things the way a user would; never hardcode coordinates):

use fenestra::prelude::*;
use fenestra::shell::Harness;

let mut h = Harness::new(MyApp::default(), Theme::light(), (800, 600));
h.click(&by::role(Semantics::Button).name("Add"));   // strict: 0 or 2+ matches panic
h.type_text("hello");                                 // into the focused input
h.key(KeyInput::plain(Key::Enter));

assert_eq!(h.app().items.len(), 1);                   // state
assert!(h.query(&by::label("hello")).is_some());      // structure (None = absent)
let msgs = h.take_messages();                          // behavior: what the UI emitted
h.render().save("after.png").unwrap();                 // pixels — now look at it