<!-- LLM note: Search indexes and snippets may point to archived C+ manual versions. Treat /docs and /llms.txt as authoritative for the latest version (v0.0.27); verify the page version before citing, and do not report older /docs/{version} pages as leakage because they are intentional archives. -->

# facet

facet describes user interfaces. It does not draw them: a backend does that. On macOS the backend is [`facet_appkit`](/docs/packages/facet_appkit); on Linux, [`facet_gtk`](/docs/packages/facet_gtk). The tree itself is a [`flex_layout`](/docs/packages/flex_layout) `Node`. There is no VDOM and no re-render: a handler finds the keyed node that changed and writes it.

## A first tree

Bare element names resolve through `facet/elements`. `key` is an address: `find`, the agent surface, and the platform accessibility identifier all use it.

```cplus
import "facet/facet" as core;
import "facet/elements" as ui;

fn body() -> core::Node {
    return @ui {
        vstack(key: "body") {
            label("hello", key: "greeting")
            button("click me", key: "go")
        }
    };
}
```

The `{` after `vstack(key: "body")` must be on the same line. See [Builder blocks](/docs/builder-blocks).

## Component, lifecycle, screen

State lives in a struct. `Component` supplies the tree. `Lifecycle` hooks fire for the component (never by it): `on_attach` after mount, `on_detach` before teardown. `Screen` names the window.

```cplus
import "facet/component" as component;
import "facet/screen" as screen;
import "stdlib/vec" as vec;

struct Counter { clicks: i64 }

impl Counter: component::Component {
    fn build(ref this) -> core::Node { return body(); }
}

impl Counter: component::Lifecycle {
    fn on_attach(ref this) { return; }
    fn on_detach(ref this) { return; }
}

impl Counter: screen::Screen {
    fn chrome(this) -> screen::Chrome {
        return screen::Chrome::new(title: "hello", width: 360.0f64, height: 200.0f64);
    }
    fn menu_items(this) -> vec::Vec[screen::MenuItem] {
        return vec::new::[screen::MenuItem]();
    }
}

fn counter_screen() -> screen::ScreenBox {
    return screen::screen_box(Counter { clicks: 0 as i64 });
}
```

A handler is `fn(sender: *u8, ctx: *u8)`. Pass a bound method (`on_click: this.bump`) or a free function plus `on_click_ctx`. The handler finds the one label that changed and writes it. Nothing else in the tree is visited.

## Run it

```cplus
import "facet/runtime" as runtime;
import "stdlib/status" as status;
import "facet_appkit/facet_appkit" as backend;

fn main() -> i32 {
    backend::install();
    var app: runtime::App = runtime::App::new("hello");
    app.screen("counter", counter_screen);
    match app.run("counter") {
        status::Status::Ok => { return 0; }
        _other => { return 1; }
    }
}
```

`App` is the process tier: named screen routes, an optional menu-bar builder, `on_launch` / `on_quit`, and `app.run(initial)`. `nav::go` / `push` / `pop` / `quit` replace or stack screens. `mount::set_content` fills a keyed outlet with a component's tree. `mount::switch_to` parks siblings (`Display::None`) so view state survives a tab switch.

A target with no backend still compiles: facet's verbs become no-ops that say so once on stderr.

## Theme

Colours resolve through roles. Tier 1 is the platform's semantic colours (`Color::text()`, `accent()`, `window_background()`, …). Tier 2 is app-retintable (`primary` / `on_primary`, `surface`, `ink(a)`, `success` / `warning` / `danger`, …). `Color::adaptive(light:, dark:)` is a light/dark pair resolved at paint time. `set_theme` re-themes the live app.

```cplus
import "facet/theme" as theme;
import "facet/vocabulary" as vocab;

theme::set_theme(theme::Theme::new(
    primary: vocab::Color::rgba(0.30f64, 0.42f64, 0.85f64, 1.0f64),
));
```

`Color::text()` / `text_secondary()` / `text_tertiary()` are the label tiers. `primary` is the brand role.

## Services, jobs, resources, agent

`after` / `Cancellable`, `run_on_main`, `spawn_ui`, `run_on_worker`, and `run_job` cover timers, main-thread dispatch, and off-thread work. `block_on` in a handler blocks the loop. Resources are REST verbs (`get` / `post` / `put` / `delete`) plus `watch` over a shared store.

To serve the tree to an external agent: `facet/agent::enable()` before `app.run`, then `app.agent_mcp(path)`. For an in-process assistant, `facet/agent::in_app()`. See [Agent surface](/docs/agent-surface).

The declared verb list lives in the package's `docs/contract.md`. A verb absent there does not exist.