---
title: "ui"
description: "The ui namespace — the engine's Luau API reference for ui."
section: "API Reference"
slug: "api-ui"
canonical: "https://origozero.ai/docs/api-ui"
updated: "2026-09-06T05:08:07.819453670+00:00"
tags: ["api", "reference"]
---

# ui

The `ui` namespace — 181 functions.

## globals/ui/blur {#globals-ui-blur}

```lua
ui.blur()
```

Surrender keyboard focus from whichever widget currently
holds it.

## globals/ui/bringAreaToFront {#globals-ui-bringareatofront}

```lua
ui.bringAreaToFront(id: string)
```

Raise a movable `area` to the top of the window stacking order —
the programmatic equivalent of clicking it. Areas sharing a stacking
band order by interaction, so this is the call that brings one forward
from code: use it when a taskbar button, focus change, or app launch
should raise a window. Moving a screen to a higher `layer` band raises
it over the bands below.

**Parameters**

- `id` `string` — Area widget id.

## globals/ui/captureWindow {#globals-ui-capturewindow}

```lua
ui.captureWindow(screen: string, window: string, opts: CaptureOpts?) -> CaptureResult?
```

Render a single Window widget to its own offscreen texture
and write the result as PNG at
`/runtime/render_surfaces/<rtHandle>.png`. The screen does NOT
need to be visible. Returns `{ rtHandle, texturePath }` or nil
on invalid inputs (width/height clamped to `[1, 8192]`,
defaults 600x400).

**Parameters**

- `screen` `string` — Screen id containing the target Window.
- `window` `string` — Widget id of the Window.
- `opts` `CaptureOpts` _(optional)_ — `{ width, height }` (optional).

**Returns** `CaptureResult?` — `{ rtHandle, texturePath }` or nil.

## globals/ui/click {#globals-ui-click}

```lua
ui.click(callbackId: string, value: any?)
```

Simulate a widget click / interaction by its callback id. The call
carries no screen, so an id that names widgets on several screens reaches
every component that declared it, once each.

**Parameters**

- `callbackId` `string` — Callback id assigned to the widget.
- `value` `any` _(optional)_ — Optional value to pass with the callback.

## globals/ui/defineStyle {#globals-ui-definestyle}

```lua
ui.defineStyle(name: string, style: StyleProps)
```

Define a named style. Style keys follow
`<widgetType>.<className>` (e.g. `"label.h1"`, `"button.primary"`)
or bare `<className>` to apply across widget types. Widgets
reference styles via the `classes` (or `class`) prop.

**Parameters**

- `name` `string` — Style name.
- `style` `StyleProps` — Style properties table.

## globals/ui/defineStyles {#globals-ui-definestyles}

```lua
ui.defineStyles(styles: { [string]: StyleProps })
```

Define multiple named styles at once.

**Parameters**

- `styles` `{ [string]: StyleProps }` — Map of style name to style properties.

## globals/ui/defineWidget {#globals-ui-definewidget}

```lua
ui.defineWidget(name: string, builderFn: (WidgetTree, { WidgetTree }) -> WidgetTree)
```

Register a custom widget kind. When a tree contains
`{ type = name, props = ..., children = ... }`, the decoder
calls `builderFn(props, children)` at register / update time and
substitutes the returned widget table in place. Errors surface
through `ui.lastValidation()` with codes `widget-builder-error`
/ `widget-builder-bad-return` / `decode-recursion-depth-exceeded`.

**Parameters**

- `name` `string` — Custom widget kind name.
- `builderFn` `(WidgetTree, { WidgetTree }) -> WidgetTree` — Builder closure `(props, children) -> widgetTable`.

## globals/ui/diagnose {#globals-ui-diagnose}

```lua
ui.diagnose(widgetId: string) -> WidgetPaint?
```

Why one widget did or did not reach the last frame. Returns that
widget's row from `ui.observe()` — the same fields, resolved against the
same reading. An id no registered screen carries reads `noSuchWidget`,
which is how a misspelling separates from a widget whose screen is
hidden and from one the frame laid out no box for.

**Parameters**

- `widgetId` `string` — The id the widget records layout under.

**Returns** `WidgetPaint?` — The widget's row, or nil before the UI has published a frame.

```lua
"hud-healthbar"
```

## globals/ui/dragState {#globals-ui-dragstate}

```lua
ui.dragState() -> { payload: string, x: number, y: number }?
```

The in-flight drag-and-drop payload while a `dragPayload` widget is
being dragged, else nil. `x`/`y` are the pointer's position in the
logical space `ui.getLayoutInfo` rects live in, so the reading resolves
directly against widget rects. Poll during a drag to drive live
feedback (a placement ghost following the cursor); the drop itself
still lands through the target's `onDrop`. Snapshotted each frame.

**Returns** `{ payload: string, x: number, y: number }?` — `{ payload, x, y }` during a drag, nil otherwise.

## globals/ui/elementTree {#globals-ui-elementtree}

```lua
ui.elementTree(screenName: string) -> ElementNode?
```

Introspect a screen's rendered widget hierarchy with each
element's layout rect. Every node the renderer draws appears, nested
exactly as the widgets nest, under the id it records layout against:
the `id` set on the node when the author gave it one, otherwise
`<screen>/<type>@<path>`. `bounds` is that element's rect — the same
table `ui.getLayoutInfo(id)` returns — and appears once the element has
been measured. Kinds registered through `ui.defineWidget` appear
expanded into the primitives they build. Feeds the `gui.captureElement`
tool: list the tree, pick the ids to frame, capture their region.

**Parameters**

- `screenName` `string` — Screen id passed to `ui.registerScreen`.

**Returns** `ElementNode?` — An `ElementNode` tree, or nil when no screen is registered under that name.

## globals/ui/focus {#globals-ui-focus}

```lua
ui.focus(widgetId: string)
```

Programmatically request keyboard focus on a widget. Queued
as a one-shot; the next render of the matching widget calls
`response.request_focus()`.

**Parameters**

- `widgetId` `string` — Widget id to focus.

## globals/ui/focusedWidget {#globals-ui-focusedwidget}

```lua
ui.focusedWidget() -> string?
```

Return the widget id of whichever widget currently holds
keyboard focus, or nil. Snapshotted post-render each frame.

**Returns** `string?` — Focused widget id or nil.

## globals/ui/getAreaPos {#globals-ui-getareapos}

```lua
ui.getAreaPos(id: string) -> AreaPos?
```

Read the current pivot position of an `area` widget,
including any user drag deltas. Returns `{ x, y }` or nil if
the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

**Returns** `AreaPos?` — `{ x, y }` or nil.

## globals/ui/getAreaSize {#globals-ui-getareasize}

```lua
ui.getAreaSize(id: string) -> AreaSize?
```

Read the measured size of an `area` widget, including any user
resize-grip drags if the area is `resizable`. Returns `{ w, h }`
or nil if the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

**Returns** `AreaSize?` — `{ w, h }` or nil.

## globals/ui/getDockLayout {#globals-ui-getdocklayout}

```lua
ui.getDockLayout(id: string) -> string?
```

Read the current serialized layout (split/tab arrangement) of
a `dockArea` widget as a JSON string. Returns nil if the dockArea
didn't render this frame. Persist the string and pass it back via
the dockArea's `layout` prop to restore the arrangement.

**Parameters**

- `id` `string` — DockArea widget id.

**Returns** `string?` — Serialized DockState JSON string, or nil.

## globals/ui/getLayoutInfo {#globals-ui-getlayoutinfo}

```lua
ui.getLayoutInfo(widgetId: string?) -> LayoutInfo?
```

Get layout info (position, size, content bounds) for UI
containers. If `widgetId` is given, returns info for that
widget only; otherwise returns all.

**Parameters**

- `widgetId` `string` _(optional)_ — Optional widget id to query.

**Returns** `LayoutInfo?` — Layout info table or nil.

## globals/ui/getScreenTree {#globals-ui-getscreentree}

```lua
ui.getScreenTree(screenName: string) -> WidgetTree?
```

Return the last widget tree table passed to
`registerScreen` / `updateScreen` for `screenName`.

**Parameters**

- `screenName` `string` — Screen name to query.

**Returns** `WidgetTree?` — Widget tree or nil.

## globals/ui/getTheme {#globals-ui-gettheme}

```lua
ui.getTheme() -> string
```

Get the name of the currently active theme.

**Returns** `string` — Active theme name.

## globals/ui/getToken {#globals-ui-gettoken}

```lua
ui.getToken(name: string) -> string?
```

Look up a single design token value from the active theme.

**Parameters**

- `name` `string` — Token name (without `$` prefix).

**Returns** `string?` — Token value or nil.

## globals/ui/getTokens {#globals-ui-gettokens}

```lua
ui.getTokens() -> { [string]: string }
```

Get all design tokens from the active theme as a key-value
map.

**Returns** `{ [string]: string }` — Token map.

## globals/ui/getWidgetProps {#globals-ui-getwidgetprops}

```lua
ui.getWidgetProps(typeName: string) -> { WidgetPropDescriptor }?
```

Get the property definitions for a widget type.

**Parameters**

- `typeName` `string` — Widget type name.

**Returns** `{ WidgetPropDescriptor }?` — Array of property descriptors, or nil if type not found.

## globals/ui/getWidgetTypes {#globals-ui-getwidgettypes}

```lua
ui.getWidgetTypes() -> { string }
```

Get all available widget type names that can be used in
widget trees.

**Returns** `{ string }` — Array of widget type names.

## globals/ui/hideScreen {#globals-ui-hidescreen}

```lua
ui.hideScreen(name: string) -> boolean
```

Hide a registered screen, and report whether a screen by that name
is registered. The engine applies the hide later in the frame;
`listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to hide.

**Returns** `boolean` — True when a screen by this name is registered.

## globals/ui/hitTest {#globals-ui-hittest}

```lua
ui.hitTest(x: number, y: number) -> PaintHitTest?
```

Which widget a pointer at `(x, y)` reaches, and the stack beneath it.
Coordinates are in the space `ui.screenSize()` reports — the same space
`getLayoutInfo` rects and `gui.clickAt` use.

**Parameters**

- `x` `number` — Logical X.
- `y` `number` — Logical Y.

**Returns** `PaintHitTest?` — `{ widget, screen, stack, x, y }` — `widget` nil when the point is over no UI — or nil before the UI has published a frame.

```lua
640, 360
```

## globals/ui/invisibilityReasons {#globals-ui-invisibilityreasons}

```lua
ui.invisibilityReasons() -> { string }
```

Every verdict `ui.diagnose` can report, as a closed list.

**Returns** `{ string }` — The reason names.

## globals/ui/lastRegistration {#globals-ui-lastregistration}

```lua
ui.lastRegistration() -> { name: string, layer: number? }?
```

The name and layer passed to the most recent `ui.registerScreen`
call, recorded synchronously at call time. A host that mounts a nested
app reads this immediately after the mount to learn which screen the
nested code registered, without intercepting the `ui` table.

**Returns** `{ name: string, layer: number? }?` — `{ name, layer }` for the last registration, or nil if none yet.

## globals/ui/lastValidation {#globals-ui-lastvalidation}

```lua
ui.lastValidation(screenName: string?) -> any
```

Validation diagnostics produced at the most recent
`registerScreen` / `updateScreen`, plus what the render stage
found while painting — `unknown-font-family` reports a
`style.fontFamily` that named no registered font family, once
per family per screen. With no args returns a
`{ [screen] = entry }` map; with a name returns that screen's
entry or nil. Validation gated by world setting
`ui.validation` = `"off" | "warn" | "strict"` (default `"warn"`).

**Parameters**

- `screenName` `string` _(optional)_ — Optional screen name.

**Returns** `any` — Validation entry, full map, or nil.

## globals/ui/listFonts {#globals-ui-listfonts}

```lua
ui.listFonts() -> { FontFamilyInfo }
```

Every font family a `style.fontFamily` can select. Read from
the registry the UI text renderer resolves a family token
through, so a family this returns is one a label renders in.
`family` and every name in `aliases` are accepted as a
`fontFamily`, case-insensitively; `aliases` carries the
web-font names, CSS generic families and face names that
select the same group. `faces` names the concrete face in each
weight/style slot, so a `fontWeight = 700` against a family
with no `bold` face gets a synthesised heavy. `system = true`
marks a family taken from the host OS — present on this
machine, absent on one without it, and absent on WASM — so a
UI that must look the same everywhere picks a family with
`system = false`. A `fontFamily` naming nothing in this list
is reported as an `unknown-font-family` warning through
`ui.lastValidation(screen)` once the screen paints, and the
text renders in the default proportional face.

**Returns** `{ FontFamilyInfo }` — Array of `{ family, aliases, faces, system }`, by family.

```lua
for _, f in ui.listFonts() do print(f.family) end
```

## globals/ui/listScreens {#globals-ui-listscreens}

```lua
ui.listScreens() -> { ScreenSummary }
```

List every registered screen with its current visibility,
layer, and whether the screen has a populated root widget tree,
including the register / show / hide / unregister calls the running
script has already made. Sorted by layer ascending, then name.

**Returns** `{ ScreenSummary }` — Array of screen summaries.

## globals/ui/listThemes {#globals-ui-listthemes}

```lua
ui.listThemes() -> { string }
```

List all registered theme names.

**Returns** `{ string }` — Array of theme names.

## globals/ui/observe {#globals-ui-observe}

```lua
ui.observe(screenName: string?) -> PaintObservation?
```

What the last UI frame painted. Returns
`{ generation, viewport, pointer, pointerOverUi, pointerWidget, widgets }`
with one `widgets` row per widget any registered screen holds — its
layout box, the clip chain it painted under, the part of that box which
reached the frame (`visible`), the order it painted in (`paintIndex`),
and its `reason` from the closed set `ui.invisibilityReasons()` lists.
`generation` advances once per re-rendered frame, so two calls reporting
the same number describe the same frame.

**Parameters**

- `screenName` `string` _(optional)_ — Narrow the rows to one screen. Omit for every screen.

**Returns** `PaintObservation?` — The reading; nil before the UI has published a frame, and nil for a `screenName` no registered screen answers to.

```lua
"hud"
```

## globals/ui/paintOrder {#globals-ui-paintorder}

```lua
ui.paintOrder(a: string, b: string) -> number?
```

Which of two widgets paints later: `-1` when `a` paints before `b`,
`1` when after, `0` when level. This is what separates two widgets whose
rects are identical.

**Parameters**

- `a` `string` — First widget id.
- `b` `string` — Second widget id.

**Returns** `number?` — -1, 0, 1, or nil when the reading holds no row for one of them.

```lua
"panel-a", "panel-b"
```

## globals/ui/pixelRatio {#globals-ui-pixelratio}

```lua
ui.pixelRatio() -> number
```

Physical pixels per logical point — the factor between the logical
space `ui.screenSize()` / `getLayoutInfo` rects live in and the physical
space `input.mousePosition`, the camera viewport rect and
`input.simulateMouse*` coordinates live in. Multiply a layout coordinate
by this to aim a simulated pointer at a widget.

**Returns** `number` — Physical pixels per logical point (1.0 when unscaled).

## globals/ui/pointerWidget {#globals-ui-pointerwidget}

```lua
ui.pointerWidget() -> PointerRead?
```

Whether the UI is consuming the pointer, and which widget holds it —
the pointer counterpart of `ui.focusedWidget()`.

**Returns** `PointerRead?` — `{ x, y, overUi, widget, screen }`, or nil before the UI has published a frame.

## globals/ui/registerBackgroundShader {#globals-ui-registerbackgroundshader}

```lua
ui.registerBackgroundShader(shaderHandle: any?, width: number?, height: number?)
```

Register a screen-domain `.shader` as a UI background, drawn
via the `backgroundShader` style. Takes the shader's asset handle
from `asset.resolve`.

**Parameters**

- `shaderHandle` `any` _(optional)_ — The screen `.shader`'s asset handle, from `asset.resolve`.
- `width` `number` _(optional)_ — Render target width (default 1280).
- `height` `number` _(optional)_ — Render target height (default 720).

## globals/ui/registerCallbackEnv {#globals-ui-registercallbackenv}

```lua
ui.registerCallbackEnv(key: string, env: { [string]: any })
```

Register an environment table to receive widget-callback
broadcasts: its global `onCallback(id, value)` fires for any widget
callback not owned by a specific component instance — the same
broadcast a component's `onCallback` receives. Keyed by `key`;
re-registering the same key replaces the previous env. A component
instance is folded into the callback dispatch automatically, so reach
for this from a non-component context that hosts a UI surface (a scene
entrypoint registering its own screen). Pair with
`ui.unregisterCallbackEnv(key)` so the ref is released.

**Parameters**

- `key` `string` — Stable identifier for this registration (re-register replaces).
- `env` `{ [string]: any }` — Environment table whose `onCallback` receives the broadcasts.

## globals/ui/registerScreen {#globals-ui-registerscreen}

```lua
ui.registerScreen(name: string, widgetTree: WidgetTree, layer: number?)
```

Register a named UI screen with a widget tree. Optional
`layer` controls z-ordering (higher = on top), in bands: below 0
behind everything, 0-99 ordinary app depth, 100-999 always-on-top
chrome, 1000+ menu and popup depth. A screen in a higher band
covers one in a lower band whatever their roots are; inside a band
a floating `area` or `window` root sits over ordinary content, and
a `modal` root sits over the whole stack. Tag-based
grouping lives in `Z.tags` (`Z.tags.set(name, { "editor" })`
after register).

**Parameters**

- `name` `string` — Unique screen identifier.
- `widgetTree` `WidgetTree` — Root widget table.
- `layer` `number` _(optional)_ — Z-order layer (optional).

```lua
ui.registerScreen("hud", tree)
```

## globals/ui/registerTheme {#globals-ui-registertheme}

```lua
ui.registerTheme(name: string, theme: ThemeDefinition)
```

Register a theme from a flat Luau table. Most callers
should use `Z.theme.register(name, table)` which runs the
cascade for them.

**Parameters**

- `name` `string` — Theme name to register.
- `theme` `ThemeDefinition` — Flat-resolved theme table.

## globals/ui/removeScreen {#globals-ui-removescreen}

```lua
ui.removeScreen(name: string) -> boolean
```

Alias for `ui.unregisterScreen`.

**Parameters**

- `name` `string` — Screen identifier to remove.

**Returns** `boolean` — True when a screen by this name was registered.

## globals/ui/resetAreaSize {#globals-ui-resetareasize}

```lua
ui.resetAreaSize(id: string)
```

Clear a `resizable` `area`'s remembered size (from a grip drag or
`ui.setAreaSize`) so its declared — or content — size takes over again.

**Parameters**

- `id` `string` — Area widget id.

## globals/ui/response {#globals-ui-response}

```lua
ui.response(widgetId: string) -> WidgetResponse?
```

Per-widget interaction snapshot for the most recent frame.
Returns `{ clicked, hovered, focused, changed, value }` where
`clicked` / `changed` mark transitions and `hovered` / `focused`
mark current state.

**Parameters**

- `widgetId` `string` — The widget id (NOT the onClick / onChange callback id).

**Returns** `WidgetResponse?` — WidgetResponse or nil.

## globals/ui/screen {#globals-ui-screen}

```lua
ui.screen(name: string) -> { [string]: any }?
```

Get a screen proxy with methods like `setResolution` and
`rasterize`.

**Parameters**

- `name` `string` — Screen name.

**Returns** `{ [string]: any }?` — Screen proxy table, or nil.

## globals/ui/screenSize {#globals-ui-screensize}

```lua
ui.screenSize() -> { width: number, height: number }
```

The UI coordinate space as `{ width, height }` (logical points). This is
the space `area` `pos`, anchors, and `getLayoutInfo` rects use — and it is
NOT the pixel size of a `capture` screenshot, which may be downscaled. Use
this for absolute `area` positioning (e.g. pinning a menu above a bottom
taskbar) instead of guessing the size from a capture image.

**Returns** `{ width: number, height: number }` — `{ width, height }` in logical UI points.

## globals/ui/scroll {#globals-ui-scroll}

```lua
ui.scroll(deltaX: number, deltaY: number)
```

Simulate a mouse-wheel scroll event on the UI.

**Parameters**

- `deltaX` `number` — Horizontal scroll delta.
- `deltaY` `number` — Vertical scroll delta.

## globals/ui/setAreaPos {#globals-ui-setareapos}

```lua
ui.setAreaPos(id: string, x: number, y: number)
```

Programmatically move a movable `area` widget to `(x, y)`.
Applied for one frame; subsequent frames let drag tracking
take over.

**Parameters**

- `id` `string` — Area widget id.
- `x` `number` — Target pivot x (screen coords).
- `y` `number` — Target pivot y (screen coords).

## globals/ui/setAreaSize {#globals-ui-setareasize}

```lua
ui.setAreaSize(id: string, w: number, h: number)
```

Programmatically set a `resizable` `area`'s size (the user-size
override) — for maximize / restore / tile. Persists until the area's
declared width/height changes or `ui.resetAreaSize(id)` clears it.

**Parameters**

- `id` `string` — Area widget id.
- `w` `number` — Target width (screen coords).
- `h` `number` — Target height (screen coords).

## globals/ui/setDockWindowRect {#globals-ui-setdockwindowrect}

```lua
ui.setDockWindowRect(dockId: string, panelId: string, x: number, y: number, width: number, height: number)
```

Place the floating window of a `dockArea` panel at `(x, y)` with
size `(width, height)`. Applies once the panel occupies a window —
a request made before then waits for it.

**Parameters**

- `dockId` `string` — DockArea widget id.
- `panelId` `string` — Id of the panel held by the window to place.
- `x` `number` — Window left edge (screen coords).
- `y` `number` — Window top edge (screen coords).
- `width` `number` — Window width (screen coords).
- `height` `number` — Window height (screen coords).

## globals/ui/setScreenRenderLayer {#globals-ui-setscreenrenderlayer}

```lua
ui.setScreenRenderLayer(name: string, mask: number)
```

Set a screen's render-layer membership bitmask. A screen draws into a
camera or capture only when this mask intersects the camera's include
mask — the same rule geometry follows. Content UI defaults to the `ui`
bit; the editor places its chrome on `EditorUI` so agent captures can
drop it. Masks come from `__renderLayers.bit(name)`.

**Parameters**

- `name` `string` — Screen identifier.
- `mask` `number` — Render-layer membership bitmask.

## globals/ui/setScrollPosition {#globals-ui-setscrollposition}

```lua
ui.setScrollPosition(widgetId: string, offsetY: number)
```

Set the scroll offset of a scrollArea widget.

**Parameters**

- `widgetId` `string` — Scroll area widget id.
- `offsetY` `number` — Vertical scroll offset in pixels.

## globals/ui/setShaderUniforms {#globals-ui-setshaderuniforms}

```lua
ui.setShaderUniforms(name: string, uniforms: { [string]: number })
```

Set uniform values on a registered background shader.

**Parameters**

- `name` `string` — Shader name identifier.
- `uniforms` `{ [string]: number }` — Map of uniform name to number value.

## globals/ui/setTheme {#globals-ui-settheme}

```lua
ui.setTheme(name: string)
```

Switch the active global theme by name.

**Parameters**

- `name` `string` — Theme name to activate.

## globals/ui/showScreen {#globals-ui-showscreen}

```lua
ui.showScreen(name: string) -> boolean
```

Make a registered screen visible, and report whether a screen by
that name is registered. The engine applies the show later in the
frame; `listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to show.

**Returns** `boolean` — True when a screen by this name is registered.

## globals/ui/unregisterCallbackEnv {#globals-ui-unregistercallbackenv}

```lua
ui.unregisterCallbackEnv(key: string)
```

Remove an environment registered with `ui.registerCallbackEnv`. Its
`onCallback` stops receiving broadcasts. No-op if `key` isn't registered.

**Parameters**

- `key` `string` — The key passed to `ui.registerCallbackEnv`.

## globals/ui/unregisterScreen {#globals-ui-unregisterscreen}

```lua
ui.unregisterScreen(name: string) -> boolean
```

Remove a screen from the registry entirely. Unlike
`hideScreen`, this deletes the entry so it no longer appears in
`listScreens` or render iteration.

**Parameters**

- `name` `string` — Screen identifier to unregister.

**Returns** `boolean` — True when a screen by this name was registered.

## globals/ui/unregisterWidget {#globals-ui-unregisterwidget}

```lua
ui.unregisterWidget(name: string)
```

Drop a registered custom widget kind. Subsequent references
produce an `unknown-widget-type` diagnostic.

**Parameters**

- `name` `string` — Custom widget kind name.

## globals/ui/updateScreen {#globals-ui-updatescreen}

```lua
ui.updateScreen(name: string, widgetTree: WidgetTree)
```

Replace the widget tree of an already-registered screen.

**Parameters**

- `name` `string` — Screen identifier to update.
- `widgetTree` `WidgetTree` — New root widget table.

## globals/ui/useStyles {#globals-ui-usestyles}

```lua
ui.useStyles(themeName: string)
```

Apply a registered style file's classes additively without
changing the active theme.

**Parameters**

- `themeName` `string` — Name of the registered style / theme asset.

## globals/ui/widgetState {#globals-ui-widgetstate}

```lua
ui.widgetState(widgetId: string, key: string, default: any?) -> any
```

Read per-widget cross-frame state. Returns the value
previously written via `widgetStateSet`, or `default` (or nil).
State is keyed by widget id and persists across re-renders
within a screen's lifetime; cleared automatically when the
owning screen is unregistered.

**Parameters**

- `widgetId` `string` — Widget id whose state to read.
- `key` `string` — State key.
- `default` `any` _(optional)_ — Value to return when nothing has been written.

**Returns** `any` — Stored value, default, or nil.

## globals/ui/widgetStateClear {#globals-ui-widgetstateclear}

```lua
ui.widgetStateClear(widgetId: string, key: string)
```

Remove a per-widget state entry.

**Parameters**

- `widgetId` `string` — Widget id whose state to clear.
- `key` `string` — State key.

## globals/ui/widgetStateSet {#globals-ui-widgetstateset}

```lua
ui.widgetStateSet(widgetId: string, key: string, value: any?)
```

Write per-widget cross-frame state. Replaces any existing
value under `(widgetId, key)`. Tables are stored by reference.

**Parameters**

- `widgetId` `string` — Widget id to scope the state under.
- `key` `string` — State key.
- `value` `any` _(optional)_ — Value to store (must be non-nil).

## modules/ui/README {#modules-ui-readme}

```lua
require("@builtin/modules/api/engine/ui") -- ui (also available as global 'ui')
```

UI system — screens, styles, themes, widget responses, focus, custom-widget builders, per-widget state. Public Luau surface over the `__ui` Internal FFI namespace.

Usage: local ui = require("@builtin/modules/api/engine/ui")
Also available as global: ui

## modules/ui/blur {#modules-ui-blur}

```lua
blur()
```

Surrender keyboard focus from whichever widget currently
holds it.

## modules/ui/bringAreaToFront {#modules-ui-bringareatofront}

```lua
bringAreaToFront(id: string)
```

Raise a movable `area` to the top of the window stacking order —
the programmatic equivalent of clicking it. Areas sharing a stacking
band order by interaction, so this is the call that brings one forward
from code: use it when a taskbar button, focus change, or app launch
should raise a window. Moving a screen to a higher `layer` band raises
it over the bands below.

**Parameters**

- `id` `string` — Area widget id.

## modules/ui/captureWindow {#modules-ui-capturewindow}

```lua
captureWindow(screen: string, window: string, opts: CaptureOpts?): CaptureResult?
```

Render a single Window widget to its own offscreen texture
and write the result as PNG at
`/runtime/render_surfaces/<rtHandle>.png`. The screen does NOT
need to be visible. Returns `{ rtHandle, texturePath }` or nil
on invalid inputs (width/height clamped to `[1, 8192]`,
defaults 600x400).

**Parameters**

- `screen` `string` — Screen id containing the target Window.
- `window` `string` — Widget id of the Window.
- `opts` `CaptureOpts?` _(optional)_ — `{ width, height }` (optional).

## modules/ui/click {#modules-ui-click}

```lua
click(callbackId: string, value: any?)
```

Simulate a widget click / interaction by its callback id. The call
carries no screen, so an id that names widgets on several screens reaches
every component that declared it, once each.

**Parameters**

- `callbackId` `string` — Callback id assigned to the widget.
- `value` `any?` _(optional)_ — Optional value to pass with the callback.

## modules/ui/defineStyle {#modules-ui-definestyle}

```lua
defineStyle(name: string, style: StyleProps)
```

Define a named style. Style keys follow
`<widgetType>.<className>` (e.g. `"label.h1"`, `"button.primary"`)
or bare `<className>` to apply across widget types. Widgets
reference styles via the `classes` (or `class`) prop.

**Parameters**

- `name` `string` — Style name.
- `style` `StyleProps` — Style properties table.

## modules/ui/defineStyles {#modules-ui-definestyles}

```lua
defineStyles(styles: { [string]: StyleProps })
```

Define multiple named styles at once.

**Parameters**

- `styles` `{ [string]: StyleProps }` — Map of style name to style properties.

## modules/ui/defineWidget {#modules-ui-definewidget}

```lua
defineWidget(name: string, builderFn: (WidgetTree, { WidgetTree }) -> WidgetTree)
```

Register a custom widget kind. When a tree contains
`{ type = name, props = ..., children = ... }`, the decoder
calls `builderFn(props, children)` at register / update time and
substitutes the returned widget table in place. Errors surface
through `ui.lastValidation()` with codes `widget-builder-error`
/ `widget-builder-bad-return` / `decode-recursion-depth-exceeded`.

**Parameters**

- `name` `string` — Custom widget kind name.
- `builderFn` `(WidgetTree, { WidgetTree }) -> WidgetTree` — Builder closure `(props, children) -> widgetTable`.

## modules/ui/diagnose {#modules-ui-diagnose}

```lua
diagnose(widgetId: string): WidgetPaint?
```

Why one widget did or did not reach the last frame. Returns that
widget's row from `ui.observe()` — the same fields, resolved against the
same reading. An id no registered screen carries reads `noSuchWidget`,
which is how a misspelling separates from a widget whose screen is
hidden and from one the frame laid out no box for.

**Parameters**

- `widgetId` `string` — The id the widget records layout under.

```lua
"hud-healthbar"
```

## modules/ui/dragState {#modules-ui-dragstate}

```lua
dragState(): { payload: string, x: number, y: number }?
```

The in-flight drag-and-drop payload while a `dragPayload` widget is
being dragged, else nil. `x`/`y` are the pointer's position in the
logical space `ui.getLayoutInfo` rects live in, so the reading resolves
directly against widget rects. Poll during a drag to drive live
feedback (a placement ghost following the cursor); the drop itself
still lands through the target's `onDrop`. Snapshotted each frame.

## modules/ui/elementTree {#modules-ui-elementtree}

```lua
elementTree(screenName: string): ElementNode?
```

Introspect a screen's rendered widget hierarchy with each
element's layout rect. Every node the renderer draws appears, nested
exactly as the widgets nest, under the id it records layout against:
the `id` set on the node when the author gave it one, otherwise
`<screen>/<type>@<path>`. `bounds` is that element's rect — the same
table `ui.getLayoutInfo(id)` returns — and appears once the element has
been measured. Kinds registered through `ui.defineWidget` appear
expanded into the primitives they build. Feeds the `gui.captureElement`
tool: list the tree, pick the ids to frame, capture their region.

**Parameters**

- `screenName` `string` — Screen id passed to `ui.registerScreen`.

## modules/ui/focus {#modules-ui-focus}

```lua
focus(widgetId: string)
```

Programmatically request keyboard focus on a widget. Queued
as a one-shot; the next render of the matching widget calls
`response.request_focus()`.

**Parameters**

- `widgetId` `string` — Widget id to focus.

## modules/ui/focusedWidget {#modules-ui-focusedwidget}

```lua
focusedWidget(): string?
```

Return the widget id of whichever widget currently holds
keyboard focus, or nil. Snapshotted post-render each frame.

## modules/ui/getAreaPos {#modules-ui-getareapos}

```lua
getAreaPos(id: string): AreaPos?
```

Read the current pivot position of an `area` widget,
including any user drag deltas. Returns `{ x, y }` or nil if
the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

## modules/ui/getAreaSize {#modules-ui-getareasize}

```lua
getAreaSize(id: string): AreaSize?
```

Read the measured size of an `area` widget, including any user
resize-grip drags if the area is `resizable`. Returns `{ w, h }`
or nil if the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

## modules/ui/getDockLayout {#modules-ui-getdocklayout}

```lua
getDockLayout(id: string): string?
```

Read the current serialized layout (split/tab arrangement) of
a `dockArea` widget as a JSON string. Returns nil if the dockArea
didn't render this frame. Persist the string and pass it back via
the dockArea's `layout` prop to restore the arrangement.

**Parameters**

- `id` `string` — DockArea widget id.

## modules/ui/getLayoutInfo {#modules-ui-getlayoutinfo}

```lua
getLayoutInfo(widgetId: string?): LayoutInfo?
```

Get layout info (position, size, content bounds) for UI
containers. If `widgetId` is given, returns info for that
widget only; otherwise returns all.

**Parameters**

- `widgetId` `string?` _(optional)_ — Optional widget id to query.

## modules/ui/getScreenTree {#modules-ui-getscreentree}

```lua
getScreenTree(screenName: string): WidgetTree?
```

Return the last widget tree table passed to
`registerScreen` / `updateScreen` for `screenName`.

**Parameters**

- `screenName` `string` — Screen name to query.

## modules/ui/getTheme {#modules-ui-gettheme}

```lua
getTheme(): string
```

Get the name of the currently active theme.

## modules/ui/getToken {#modules-ui-gettoken}

```lua
getToken(name: string): string?
```

Look up a single design token value from the active theme.

**Parameters**

- `name` `string` — Token name (without `$` prefix).

## modules/ui/getTokens {#modules-ui-gettokens}

```lua
getTokens(): { [string]: string }
```

Get all design tokens from the active theme as a key-value
map.

## modules/ui/getWidgetProps {#modules-ui-getwidgetprops}

```lua
getWidgetProps(typeName: string): { WidgetPropDescriptor }?
```

Get the property definitions for a widget type.

**Parameters**

- `typeName` `string` — Widget type name.

## modules/ui/getWidgetTypes {#modules-ui-getwidgettypes}

```lua
getWidgetTypes(): { string }
```

Get all available widget type names that can be used in
widget trees.

## modules/ui/hideScreen {#modules-ui-hidescreen}

```lua
hideScreen(name: string): boolean
```

Hide a registered screen, and report whether a screen by that name
is registered. The engine applies the hide later in the frame;
`listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to hide.

## modules/ui/hitTest {#modules-ui-hittest}

```lua
hitTest(x: number, y: number): PaintHitTest?
```

Which widget a pointer at `(x, y)` reaches, and the stack beneath it.
Coordinates are in the space `ui.screenSize()` reports — the same space
`getLayoutInfo` rects and `gui.clickAt` use.

**Parameters**

- `x` `number` — Logical X.
- `y` `number` — Logical Y.

```lua
640, 360
```

## modules/ui/invisibilityReasons {#modules-ui-invisibilityreasons}

```lua
invisibilityReasons(): { string }
```

Every verdict `ui.diagnose` can report, as a closed list.

## modules/ui/lastRegistration {#modules-ui-lastregistration}

```lua
lastRegistration(): { name: string, layer: number? }?
```

The name and layer passed to the most recent `ui.registerScreen`
call, recorded synchronously at call time. A host that mounts a nested
app reads this immediately after the mount to learn which screen the
nested code registered, without intercepting the `ui` table.

## modules/ui/lastValidation {#modules-ui-lastvalidation}

```lua
lastValidation(screenName: string?): any
```

Validation diagnostics produced at the most recent
`registerScreen` / `updateScreen`, plus what the render stage
found while painting — `unknown-font-family` reports a
`style.fontFamily` that named no registered font family, once
per family per screen. With no args returns a
`{ [screen] = entry }` map; with a name returns that screen's
entry or nil. Validation gated by world setting
`ui.validation` = `"off" | "warn" | "strict"` (default `"warn"`).

**Parameters**

- `screenName` `string?` _(optional)_ — Optional screen name.

## modules/ui/listFonts {#modules-ui-listfonts}

```lua
listFonts(): { FontFamilyInfo }
```

Every font family a `style.fontFamily` can select. Read from
the registry the UI text renderer resolves a family token
through, so a family this returns is one a label renders in.
`family` and every name in `aliases` are accepted as a
`fontFamily`, case-insensitively; `aliases` carries the
web-font names, CSS generic families and face names that
select the same group. `faces` names the concrete face in each
weight/style slot, so a `fontWeight = 700` against a family
with no `bold` face gets a synthesised heavy. `system = true`
marks a family taken from the host OS — present on this
machine, absent on one without it, and absent on WASM — so a
UI that must look the same everywhere picks a family with
`system = false`. A `fontFamily` naming nothing in this list
is reported as an `unknown-font-family` warning through
`ui.lastValidation(screen)` once the screen paints, and the
text renders in the default proportional face.

```lua
for _, f in ui.listFonts() do print(f.family) end
```

## modules/ui/listScreens {#modules-ui-listscreens}

```lua
listScreens(): { ScreenSummary }
```

List every registered screen with its current visibility,
layer, and whether the screen has a populated root widget tree,
including the register / show / hide / unregister calls the running
script has already made. Sorted by layer ascending, then name.

## modules/ui/listThemes {#modules-ui-listthemes}

```lua
listThemes(): { string }
```

List all registered theme names.

## modules/ui/observe {#modules-ui-observe}

```lua
observe(screenName: string?): PaintObservation?
```

What the last UI frame painted. Returns
`{ generation, viewport, pointer, pointerOverUi, pointerWidget, widgets }`
with one `widgets` row per widget any registered screen holds — its
layout box, the clip chain it painted under, the part of that box which
reached the frame (`visible`), the order it painted in (`paintIndex`),
and its `reason` from the closed set `ui.invisibilityReasons()` lists.
`generation` advances once per re-rendered frame, so two calls reporting
the same number describe the same frame.

**Parameters**

- `screenName` `string?` _(optional)_ — Narrow the rows to one screen. Omit for every screen.

```lua
"hud"
```

## modules/ui/paintOrder {#modules-ui-paintorder}

```lua
paintOrder(a: string, b: string): number?
```

Which of two widgets paints later: `-1` when `a` paints before `b`,
`1` when after, `0` when level. This is what separates two widgets whose
rects are identical.

**Parameters**

- `a` `string` — First widget id.
- `b` `string` — Second widget id.

```lua
"panel-a", "panel-b"
```

## modules/ui/pixelRatio {#modules-ui-pixelratio}

```lua
pixelRatio(): number
```

Physical pixels per logical point — the factor between the logical
space `ui.screenSize()` / `getLayoutInfo` rects live in and the physical
space `input.mousePosition`, the camera viewport rect and
`input.simulateMouse*` coordinates live in. Multiply a layout coordinate
by this to aim a simulated pointer at a widget.

## modules/ui/pointerWidget {#modules-ui-pointerwidget}

```lua
pointerWidget(): PointerRead?
```

Whether the UI is consuming the pointer, and which widget holds it —
the pointer counterpart of `ui.focusedWidget()`.

## modules/ui/registerBackgroundShader {#modules-ui-registerbackgroundshader}

```lua
registerBackgroundShader(shaderHandle: any, width: number?, height: number?)
```

Register a screen-domain `.shader` as a UI background, drawn
via the `backgroundShader` style. Takes the shader's asset handle
from `asset.resolve`.

**Parameters**

- `shaderHandle` `any` _(optional)_ — The screen `.shader`'s asset handle, from `asset.resolve`.
- `width` `number?` _(optional)_ — Render target width (default 1280).
- `height` `number?` _(optional)_ — Render target height (default 720).

## modules/ui/registerCallbackEnv {#modules-ui-registercallbackenv}

```lua
registerCallbackEnv(key: string, env: { [string]: any })
```

Register an environment table to receive widget-callback
broadcasts: its global `onCallback(id, value)` fires for any widget
callback not owned by a specific component instance — the same
broadcast a component's `onCallback` receives. Keyed by `key`;
re-registering the same key replaces the previous env. A component
instance is folded into the callback dispatch automatically, so reach
for this from a non-component context that hosts a UI surface (a scene
entrypoint registering its own screen). Pair with
`ui.unregisterCallbackEnv(key)` so the ref is released.

**Parameters**

- `key` `string` — Stable identifier for this registration (re-register replaces).
- `env` `{ [string]: any }` — Environment table whose `onCallback` receives the broadcasts.

## modules/ui/registerScreen {#modules-ui-registerscreen}

```lua
registerScreen(name: string, widgetTree: WidgetTree, layer: number?)
```

Register a named UI screen with a widget tree. Optional
`layer` controls z-ordering (higher = on top), in bands: below 0
behind everything, 0-99 ordinary app depth, 100-999 always-on-top
chrome, 1000+ menu and popup depth. A screen in a higher band
covers one in a lower band whatever their roots are; inside a band
a floating `area` or `window` root sits over ordinary content, and
a `modal` root sits over the whole stack. Tag-based
grouping lives in `Z.tags` (`Z.tags.set(name, { "editor" })`
after register).

**Parameters**

- `name` `string` — Unique screen identifier.
- `widgetTree` `WidgetTree` — Root widget table.
- `layer` `number?` _(optional)_ — Z-order layer (optional).

```lua
ui.registerScreen("hud", tree)
```

## modules/ui/registerTheme {#modules-ui-registertheme}

```lua
registerTheme(name: string, theme: ThemeDefinition)
```

Register a theme from a flat Luau table. Most callers
should use `Z.theme.register(name, table)` which runs the
cascade for them.

**Parameters**

- `name` `string` — Theme name to register.
- `theme` `ThemeDefinition` — Flat-resolved theme table.

## modules/ui/removeScreen {#modules-ui-removescreen}

```lua
removeScreen(name: string): boolean
```

Alias for `ui.unregisterScreen`.

**Parameters**

- `name` `string` — Screen identifier to remove.

## modules/ui/resetAreaSize {#modules-ui-resetareasize}

```lua
resetAreaSize(id: string)
```

Clear a `resizable` `area`'s remembered size (from a grip drag or
`ui.setAreaSize`) so its declared — or content — size takes over again.

**Parameters**

- `id` `string` — Area widget id.

## modules/ui/response {#modules-ui-response}

```lua
response(widgetId: string): WidgetResponse?
```

Per-widget interaction snapshot for the most recent frame.
Returns `{ clicked, hovered, focused, changed, value }` where
`clicked` / `changed` mark transitions and `hovered` / `focused`
mark current state.

**Parameters**

- `widgetId` `string` — The widget id (NOT the onClick / onChange callback id).

## modules/ui/screen {#modules-ui-screen}

```lua
screen(name: string): { [string]: any }?
```

Get a screen proxy with methods like `setResolution` and
`rasterize`.

**Parameters**

- `name` `string` — Screen name.

## modules/ui/screenSize {#modules-ui-screensize}

```lua
screenSize(): { width: number, height: number }
```

The UI coordinate space as `{ width, height }` (logical points). This is
the space `area` `pos`, anchors, and `getLayoutInfo` rects use — and it is
NOT the pixel size of a `capture` screenshot, which may be downscaled. Use
this for absolute `area` positioning (e.g. pinning a menu above a bottom
taskbar) instead of guessing the size from a capture image.

## modules/ui/scroll {#modules-ui-scroll}

```lua
scroll(deltaX: number, deltaY: number)
```

Simulate a mouse-wheel scroll event on the UI.

**Parameters**

- `deltaX` `number` — Horizontal scroll delta.
- `deltaY` `number` — Vertical scroll delta.

## modules/ui/setAreaPos {#modules-ui-setareapos}

```lua
setAreaPos(id: string, x: number, y: number)
```

Programmatically move a movable `area` widget to `(x, y)`.
Applied for one frame; subsequent frames let drag tracking
take over.

**Parameters**

- `id` `string` — Area widget id.
- `x` `number` — Target pivot x (screen coords).
- `y` `number` — Target pivot y (screen coords).

## modules/ui/setAreaSize {#modules-ui-setareasize}

```lua
setAreaSize(id: string, w: number, h: number)
```

Programmatically set a `resizable` `area`'s size (the user-size
override) — for maximize / restore / tile. Persists until the area's
declared width/height changes or `ui.resetAreaSize(id)` clears it.

**Parameters**

- `id` `string` — Area widget id.
- `w` `number` — Target width (screen coords).
- `h` `number` — Target height (screen coords).

## modules/ui/setDockWindowRect {#modules-ui-setdockwindowrect}

```lua
setDockWindowRect(
```

Place the floating window of a `dockArea` panel at `(x, y)` with
size `(width, height)`. Applies once the panel occupies a window —
a request made before then waits for it.

## modules/ui/setScreenRenderLayer {#modules-ui-setscreenrenderlayer}

```lua
setScreenRenderLayer(name: string, mask: number)
```

Set a screen's render-layer membership bitmask. A screen draws into a
camera or capture only when this mask intersects the camera's include
mask — the same rule geometry follows. Content UI defaults to the `ui`
bit; the editor places its chrome on `EditorUI` so agent captures can
drop it. Masks come from `__renderLayers.bit(name)`.

**Parameters**

- `name` `string` — Screen identifier.
- `mask` `number` — Render-layer membership bitmask.

## modules/ui/setScrollPosition {#modules-ui-setscrollposition}

```lua
setScrollPosition(widgetId: string, offsetY: number)
```

Set the scroll offset of a scrollArea widget.

**Parameters**

- `widgetId` `string` — Scroll area widget id.
- `offsetY` `number` — Vertical scroll offset in pixels.

## modules/ui/setShaderUniforms {#modules-ui-setshaderuniforms}

```lua
setShaderUniforms(name: string, uniforms: { [string]: number })
```

Set uniform values on a registered background shader.

**Parameters**

- `name` `string` — Shader name identifier.
- `uniforms` `{ [string]: number }` — Map of uniform name to number value.

## modules/ui/setTheme {#modules-ui-settheme}

```lua
setTheme(name: string)
```

Switch the active global theme by name.

**Parameters**

- `name` `string` — Theme name to activate.

## modules/ui/showScreen {#modules-ui-showscreen}

```lua
showScreen(name: string): boolean
```

Make a registered screen visible, and report whether a screen by
that name is registered. The engine applies the show later in the
frame; `listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to show.

## modules/ui/unregisterCallbackEnv {#modules-ui-unregistercallbackenv}

```lua
unregisterCallbackEnv(key: string)
```

Remove an environment registered with `ui.registerCallbackEnv`. Its
`onCallback` stops receiving broadcasts. No-op if `key` isn't registered.

**Parameters**

- `key` `string` — The key passed to `ui.registerCallbackEnv`.

## modules/ui/unregisterScreen {#modules-ui-unregisterscreen}

```lua
unregisterScreen(name: string): boolean
```

Remove a screen from the registry entirely. Unlike
`hideScreen`, this deletes the entry so it no longer appears in
`listScreens` or render iteration.

**Parameters**

- `name` `string` — Screen identifier to unregister.

## modules/ui/unregisterWidget {#modules-ui-unregisterwidget}

```lua
unregisterWidget(name: string)
```

Drop a registered custom widget kind. Subsequent references
produce an `unknown-widget-type` diagnostic.

**Parameters**

- `name` `string` — Custom widget kind name.

## modules/ui/updateScreen {#modules-ui-updatescreen}

```lua
updateScreen(name: string, widgetTree: WidgetTree)
```

Replace the widget tree of an already-registered screen.

**Parameters**

- `name` `string` — Screen identifier to update.
- `widgetTree` `WidgetTree` — New root widget table.

## modules/ui/useStyles {#modules-ui-usestyles}

```lua
useStyles(themeName: string)
```

Apply a registered style file's classes additively without
changing the active theme.

**Parameters**

- `themeName` `string` — Name of the registered style / theme asset.

## modules/ui/widgetState {#modules-ui-widgetstate}

```lua
widgetState(widgetId: string, key: string, default: any?): any
```

Read per-widget cross-frame state. Returns the value
previously written via `widgetStateSet`, or `default` (or nil).
State is keyed by widget id and persists across re-renders
within a screen's lifetime; cleared automatically when the
owning screen is unregistered.

**Parameters**

- `widgetId` `string` — Widget id whose state to read.
- `key` `string` — State key.
- `default` `any?` _(optional)_ — Value to return when nothing has been written.

## modules/ui/widgetStateClear {#modules-ui-widgetstateclear}

```lua
widgetStateClear(widgetId: string, key: string)
```

Remove a per-widget state entry.

**Parameters**

- `widgetId` `string` — Widget id whose state to clear.
- `key` `string` — State key.

## modules/ui/widgetStateSet {#modules-ui-widgetstateset}

```lua
widgetStateSet(widgetId: string, key: string, value: any)
```

Write per-widget cross-frame state. Replaces any existing
value under `(widgetId, key)`. Tables are stored by reference.

**Parameters**

- `widgetId` `string` — Widget id to scope the state under.
- `key` `string` — State key.
- `value` `any` _(optional)_ — Value to store (must be non-nil).

## typed/builtin//modules/api/engine/ui/ui/blur {#typed-builtin-modules-api-engine-ui-ui-blur}

```lua
ui.blur()
```

Surrender keyboard focus from whichever widget currently
holds it.

## typed/builtin//modules/api/engine/ui/ui/bringAreaToFront {#typed-builtin-modules-api-engine-ui-ui-bringareatofront}

```lua
ui.bringAreaToFront(id: string)
```

Raise a movable `area` to the top of the window stacking order —
the programmatic equivalent of clicking it. Areas sharing a stacking
band order by interaction, so this is the call that brings one forward
from code: use it when a taskbar button, focus change, or app launch
should raise a window. Moving a screen to a higher `layer` band raises
it over the bands below.

**Parameters**

- `id` `string` — Area widget id.

## typed/builtin//modules/api/engine/ui/ui/captureWindow {#typed-builtin-modules-api-engine-ui-ui-capturewindow}

```lua
ui.captureWindow(screen: string, window: string, opts: CaptureOpts?) -> CaptureResult?
```

Render a single Window widget to its own offscreen texture
and write the result as PNG at
`/runtime/render_surfaces/<rtHandle>.png`. The screen does NOT
need to be visible. Returns `{ rtHandle, texturePath }` or nil
on invalid inputs (width/height clamped to `[1, 8192]`,
defaults 600x400).

**Parameters**

- `screen` `string` — Screen id containing the target Window.
- `window` `string` — Widget id of the Window.
- `opts` `CaptureOpts` _(optional)_ — `{ width, height }` (optional).

**Returns** `CaptureResult?` — `{ rtHandle, texturePath }` or nil.

## typed/builtin//modules/api/engine/ui/ui/click {#typed-builtin-modules-api-engine-ui-ui-click}

```lua
ui.click(callbackId: string, value: any?)
```

Simulate a widget click / interaction by its callback id. The call
carries no screen, so an id that names widgets on several screens reaches
every component that declared it, once each.

**Parameters**

- `callbackId` `string` — Callback id assigned to the widget.
- `value` `any` _(optional)_ — Optional value to pass with the callback.

## typed/builtin//modules/api/engine/ui/ui/defineStyle {#typed-builtin-modules-api-engine-ui-ui-definestyle}

```lua
ui.defineStyle(name: string, style: StyleProps)
```

Define a named style. Style keys follow
`<widgetType>.<className>` (e.g. `"label.h1"`, `"button.primary"`)
or bare `<className>` to apply across widget types. Widgets
reference styles via the `classes` (or `class`) prop.

**Parameters**

- `name` `string` — Style name.
- `style` `StyleProps` — Style properties table.

## typed/builtin//modules/api/engine/ui/ui/defineStyles {#typed-builtin-modules-api-engine-ui-ui-definestyles}

```lua
ui.defineStyles(styles: { [string]: StyleProps })
```

Define multiple named styles at once.

**Parameters**

- `styles` `{ [string]: StyleProps }` — Map of style name to style properties.

## typed/builtin//modules/api/engine/ui/ui/defineWidget {#typed-builtin-modules-api-engine-ui-ui-definewidget}

```lua
ui.defineWidget(name: string, builderFn: (WidgetTree, { WidgetTree }) -> WidgetTree)
```

Register a custom widget kind. When a tree contains
`{ type = name, props = ..., children = ... }`, the decoder
calls `builderFn(props, children)` at register / update time and
substitutes the returned widget table in place. Errors surface
through `ui.lastValidation()` with codes `widget-builder-error`
/ `widget-builder-bad-return` / `decode-recursion-depth-exceeded`.

**Parameters**

- `name` `string` — Custom widget kind name.
- `builderFn` `(WidgetTree, { WidgetTree }) -> WidgetTree` — Builder closure `(props, children) -> widgetTable`.

## typed/builtin//modules/api/engine/ui/ui/diagnose {#typed-builtin-modules-api-engine-ui-ui-diagnose}

```lua
ui.diagnose(widgetId: string) -> WidgetPaint?
```

Why one widget did or did not reach the last frame. Returns that
widget's row from `ui.observe()` — the same fields, resolved against the
same reading. An id no registered screen carries reads `noSuchWidget`,
which is how a misspelling separates from a widget whose screen is
hidden and from one the frame laid out no box for.

**Parameters**

- `widgetId` `string` — The id the widget records layout under.

**Returns** `WidgetPaint?` — The widget's row, or nil before the UI has published a frame.

```lua
"hud-healthbar"
```

## typed/builtin//modules/api/engine/ui/ui/dragState {#typed-builtin-modules-api-engine-ui-ui-dragstate}

```lua
ui.dragState() -> { payload: string, x: number, y: number }?
```

The in-flight drag-and-drop payload while a `dragPayload` widget is
being dragged, else nil. `x`/`y` are the pointer's position in the
logical space `ui.getLayoutInfo` rects live in, so the reading resolves
directly against widget rects. Poll during a drag to drive live
feedback (a placement ghost following the cursor); the drop itself
still lands through the target's `onDrop`. Snapshotted each frame.

**Returns** `{ payload: string, x: number, y: number }?` — `{ payload, x, y }` during a drag, nil otherwise.

## typed/builtin//modules/api/engine/ui/ui/elementTree {#typed-builtin-modules-api-engine-ui-ui-elementtree}

```lua
ui.elementTree(screenName: string) -> ElementNode?
```

Introspect a screen's rendered widget hierarchy with each
element's layout rect. Every node the renderer draws appears, nested
exactly as the widgets nest, under the id it records layout against:
the `id` set on the node when the author gave it one, otherwise
`<screen>/<type>@<path>`. `bounds` is that element's rect — the same
table `ui.getLayoutInfo(id)` returns — and appears once the element has
been measured. Kinds registered through `ui.defineWidget` appear
expanded into the primitives they build. Feeds the `gui.captureElement`
tool: list the tree, pick the ids to frame, capture their region.

**Parameters**

- `screenName` `string` — Screen id passed to `ui.registerScreen`.

**Returns** `ElementNode?` — An `ElementNode` tree, or nil when no screen is registered under that name.

## typed/builtin//modules/api/engine/ui/ui/focus {#typed-builtin-modules-api-engine-ui-ui-focus}

```lua
ui.focus(widgetId: string)
```

Programmatically request keyboard focus on a widget. Queued
as a one-shot; the next render of the matching widget calls
`response.request_focus()`.

**Parameters**

- `widgetId` `string` — Widget id to focus.

## typed/builtin//modules/api/engine/ui/ui/focusedWidget {#typed-builtin-modules-api-engine-ui-ui-focusedwidget}

```lua
ui.focusedWidget() -> string?
```

Return the widget id of whichever widget currently holds
keyboard focus, or nil. Snapshotted post-render each frame.

**Returns** `string?` — Focused widget id or nil.

## typed/builtin//modules/api/engine/ui/ui/getAreaPos {#typed-builtin-modules-api-engine-ui-ui-getareapos}

```lua
ui.getAreaPos(id: string) -> AreaPos?
```

Read the current pivot position of an `area` widget,
including any user drag deltas. Returns `{ x, y }` or nil if
the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

**Returns** `AreaPos?` — `{ x, y }` or nil.

## typed/builtin//modules/api/engine/ui/ui/getAreaSize {#typed-builtin-modules-api-engine-ui-ui-getareasize}

```lua
ui.getAreaSize(id: string) -> AreaSize?
```

Read the measured size of an `area` widget, including any user
resize-grip drags if the area is `resizable`. Returns `{ w, h }`
or nil if the area didn't render this frame.

**Parameters**

- `id` `string` — Area widget id.

**Returns** `AreaSize?` — `{ w, h }` or nil.

## typed/builtin//modules/api/engine/ui/ui/getDockLayout {#typed-builtin-modules-api-engine-ui-ui-getdocklayout}

```lua
ui.getDockLayout(id: string) -> string?
```

Read the current serialized layout (split/tab arrangement) of
a `dockArea` widget as a JSON string. Returns nil if the dockArea
didn't render this frame. Persist the string and pass it back via
the dockArea's `layout` prop to restore the arrangement.

**Parameters**

- `id` `string` — DockArea widget id.

**Returns** `string?` — Serialized DockState JSON string, or nil.

## typed/builtin//modules/api/engine/ui/ui/getLayoutInfo {#typed-builtin-modules-api-engine-ui-ui-getlayoutinfo}

```lua
ui.getLayoutInfo(widgetId: string?) -> LayoutInfo?
```

Get layout info (position, size, content bounds) for UI
containers. If `widgetId` is given, returns info for that
widget only; otherwise returns all.

**Parameters**

- `widgetId` `string` _(optional)_ — Optional widget id to query.

**Returns** `LayoutInfo?` — Layout info table or nil.

## typed/builtin//modules/api/engine/ui/ui/getScreenTree {#typed-builtin-modules-api-engine-ui-ui-getscreentree}

```lua
ui.getScreenTree(screenName: string) -> WidgetTree?
```

Return the last widget tree table passed to
`registerScreen` / `updateScreen` for `screenName`.

**Parameters**

- `screenName` `string` — Screen name to query.

**Returns** `WidgetTree?` — Widget tree or nil.

## typed/builtin//modules/api/engine/ui/ui/getTheme {#typed-builtin-modules-api-engine-ui-ui-gettheme}

```lua
ui.getTheme() -> string
```

Get the name of the currently active theme.

**Returns** `string` — Active theme name.

## typed/builtin//modules/api/engine/ui/ui/getToken {#typed-builtin-modules-api-engine-ui-ui-gettoken}

```lua
ui.getToken(name: string) -> string?
```

Look up a single design token value from the active theme.

**Parameters**

- `name` `string` — Token name (without `$` prefix).

**Returns** `string?` — Token value or nil.

## typed/builtin//modules/api/engine/ui/ui/getTokens {#typed-builtin-modules-api-engine-ui-ui-gettokens}

```lua
ui.getTokens() -> { [string]: string }
```

Get all design tokens from the active theme as a key-value
map.

**Returns** `{ [string]: string }` — Token map.

## typed/builtin//modules/api/engine/ui/ui/getWidgetProps {#typed-builtin-modules-api-engine-ui-ui-getwidgetprops}

```lua
ui.getWidgetProps(typeName: string) -> { WidgetPropDescriptor }?
```

Get the property definitions for a widget type.

**Parameters**

- `typeName` `string` — Widget type name.

**Returns** `{ WidgetPropDescriptor }?` — Array of property descriptors, or nil if type not found.

## typed/builtin//modules/api/engine/ui/ui/getWidgetTypes {#typed-builtin-modules-api-engine-ui-ui-getwidgettypes}

```lua
ui.getWidgetTypes() -> { string }
```

Get all available widget type names that can be used in
widget trees.

**Returns** `{ string }` — Array of widget type names.

## typed/builtin//modules/api/engine/ui/ui/hideScreen {#typed-builtin-modules-api-engine-ui-ui-hidescreen}

```lua
ui.hideScreen(name: string) -> boolean
```

Hide a registered screen, and report whether a screen by that name
is registered. The engine applies the hide later in the frame;
`listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to hide.

**Returns** `boolean` — True when a screen by this name is registered.

## typed/builtin//modules/api/engine/ui/ui/hitTest {#typed-builtin-modules-api-engine-ui-ui-hittest}

```lua
ui.hitTest(x: number, y: number) -> PaintHitTest?
```

Which widget a pointer at `(x, y)` reaches, and the stack beneath it.
Coordinates are in the space `ui.screenSize()` reports — the same space
`getLayoutInfo` rects and `gui.clickAt` use.

**Parameters**

- `x` `number` — Logical X.
- `y` `number` — Logical Y.

**Returns** `PaintHitTest?` — `{ widget, screen, stack, x, y }` — `widget` nil when the point is over no UI — or nil before the UI has published a frame.

```lua
640, 360
```

## typed/builtin//modules/api/engine/ui/ui/invisibilityReasons {#typed-builtin-modules-api-engine-ui-ui-invisibilityreasons}

```lua
ui.invisibilityReasons() -> { string }
```

Every verdict `ui.diagnose` can report, as a closed list.

**Returns** `{ string }` — The reason names.

## typed/builtin//modules/api/engine/ui/ui/lastRegistration {#typed-builtin-modules-api-engine-ui-ui-lastregistration}

```lua
ui.lastRegistration() -> { name: string, layer: number? }?
```

The name and layer passed to the most recent `ui.registerScreen`
call, recorded synchronously at call time. A host that mounts a nested
app reads this immediately after the mount to learn which screen the
nested code registered, without intercepting the `ui` table.

**Returns** `{ name: string, layer: number? }?` — `{ name, layer }` for the last registration, or nil if none yet.

## typed/builtin//modules/api/engine/ui/ui/lastValidation {#typed-builtin-modules-api-engine-ui-ui-lastvalidation}

```lua
ui.lastValidation(screenName: string?) -> any
```

Validation diagnostics produced at the most recent
`registerScreen` / `updateScreen`, plus what the render stage
found while painting — `unknown-font-family` reports a
`style.fontFamily` that named no registered font family, once
per family per screen. With no args returns a
`{ [screen] = entry }` map; with a name returns that screen's
entry or nil. Validation gated by world setting
`ui.validation` = `"off" | "warn" | "strict"` (default `"warn"`).

**Parameters**

- `screenName` `string` _(optional)_ — Optional screen name.

**Returns** `any` — Validation entry, full map, or nil.

## typed/builtin//modules/api/engine/ui/ui/listFonts {#typed-builtin-modules-api-engine-ui-ui-listfonts}

```lua
ui.listFonts() -> { FontFamilyInfo }
```

Every font family a `style.fontFamily` can select. Read from
the registry the UI text renderer resolves a family token
through, so a family this returns is one a label renders in.
`family` and every name in `aliases` are accepted as a
`fontFamily`, case-insensitively; `aliases` carries the
web-font names, CSS generic families and face names that
select the same group. `faces` names the concrete face in each
weight/style slot, so a `fontWeight = 700` against a family
with no `bold` face gets a synthesised heavy. `system = true`
marks a family taken from the host OS — present on this
machine, absent on one without it, and absent on WASM — so a
UI that must look the same everywhere picks a family with
`system = false`. A `fontFamily` naming nothing in this list
is reported as an `unknown-font-family` warning through
`ui.lastValidation(screen)` once the screen paints, and the
text renders in the default proportional face.

**Returns** `{ FontFamilyInfo }` — Array of `{ family, aliases, faces, system }`, by family.

```lua
for _, f in ui.listFonts() do print(f.family) end
```

## typed/builtin//modules/api/engine/ui/ui/listScreens {#typed-builtin-modules-api-engine-ui-ui-listscreens}

```lua
ui.listScreens() -> { ScreenSummary }
```

List every registered screen with its current visibility,
layer, and whether the screen has a populated root widget tree,
including the register / show / hide / unregister calls the running
script has already made. Sorted by layer ascending, then name.

**Returns** `{ ScreenSummary }` — Array of screen summaries.

## typed/builtin//modules/api/engine/ui/ui/listThemes {#typed-builtin-modules-api-engine-ui-ui-listthemes}

```lua
ui.listThemes() -> { string }
```

List all registered theme names.

**Returns** `{ string }` — Array of theme names.

## typed/builtin//modules/api/engine/ui/ui/observe {#typed-builtin-modules-api-engine-ui-ui-observe}

```lua
ui.observe(screenName: string?) -> PaintObservation?
```

What the last UI frame painted. Returns
`{ generation, viewport, pointer, pointerOverUi, pointerWidget, widgets }`
with one `widgets` row per widget any registered screen holds — its
layout box, the clip chain it painted under, the part of that box which
reached the frame (`visible`), the order it painted in (`paintIndex`),
and its `reason` from the closed set `ui.invisibilityReasons()` lists.
`generation` advances once per re-rendered frame, so two calls reporting
the same number describe the same frame.

**Parameters**

- `screenName` `string` _(optional)_ — Narrow the rows to one screen. Omit for every screen.

**Returns** `PaintObservation?` — The reading; nil before the UI has published a frame, and nil for a `screenName` no registered screen answers to.

```lua
"hud"
```

## typed/builtin//modules/api/engine/ui/ui/paintOrder {#typed-builtin-modules-api-engine-ui-ui-paintorder}

```lua
ui.paintOrder(a: string, b: string) -> number?
```

Which of two widgets paints later: `-1` when `a` paints before `b`,
`1` when after, `0` when level. This is what separates two widgets whose
rects are identical.

**Parameters**

- `a` `string` — First widget id.
- `b` `string` — Second widget id.

**Returns** `number?` — -1, 0, 1, or nil when the reading holds no row for one of them.

```lua
"panel-a", "panel-b"
```

## typed/builtin//modules/api/engine/ui/ui/pixelRatio {#typed-builtin-modules-api-engine-ui-ui-pixelratio}

```lua
ui.pixelRatio() -> number
```

Physical pixels per logical point — the factor between the logical
space `ui.screenSize()` / `getLayoutInfo` rects live in and the physical
space `input.mousePosition`, the camera viewport rect and
`input.simulateMouse*` coordinates live in. Multiply a layout coordinate
by this to aim a simulated pointer at a widget.

**Returns** `number` — Physical pixels per logical point (1.0 when unscaled).

## typed/builtin//modules/api/engine/ui/ui/pointerWidget {#typed-builtin-modules-api-engine-ui-ui-pointerwidget}

```lua
ui.pointerWidget() -> PointerRead?
```

Whether the UI is consuming the pointer, and which widget holds it —
the pointer counterpart of `ui.focusedWidget()`.

**Returns** `PointerRead?` — `{ x, y, overUi, widget, screen }`, or nil before the UI has published a frame.

## typed/builtin//modules/api/engine/ui/ui/registerBackgroundShader {#typed-builtin-modules-api-engine-ui-ui-registerbackgroundshader}

```lua
ui.registerBackgroundShader(shaderHandle: any?, width: number?, height: number?)
```

Register a screen-domain `.shader` as a UI background, drawn
via the `backgroundShader` style. Takes the shader's asset handle
from `asset.resolve`.

**Parameters**

- `shaderHandle` `any` _(optional)_ — The screen `.shader`'s asset handle, from `asset.resolve`.
- `width` `number` _(optional)_ — Render target width (default 1280).
- `height` `number` _(optional)_ — Render target height (default 720).

## typed/builtin//modules/api/engine/ui/ui/registerCallbackEnv {#typed-builtin-modules-api-engine-ui-ui-registercallbackenv}

```lua
ui.registerCallbackEnv(key: string, env: { [string]: any })
```

Register an environment table to receive widget-callback
broadcasts: its global `onCallback(id, value)` fires for any widget
callback not owned by a specific component instance — the same
broadcast a component's `onCallback` receives. Keyed by `key`;
re-registering the same key replaces the previous env. A component
instance is folded into the callback dispatch automatically, so reach
for this from a non-component context that hosts a UI surface (a scene
entrypoint registering its own screen). Pair with
`ui.unregisterCallbackEnv(key)` so the ref is released.

**Parameters**

- `key` `string` — Stable identifier for this registration (re-register replaces).
- `env` `{ [string]: any }` — Environment table whose `onCallback` receives the broadcasts.

## typed/builtin//modules/api/engine/ui/ui/registerScreen {#typed-builtin-modules-api-engine-ui-ui-registerscreen}

```lua
ui.registerScreen(name: string, widgetTree: WidgetTree, layer: number?)
```

Register a named UI screen with a widget tree. Optional
`layer` controls z-ordering (higher = on top), in bands: below 0
behind everything, 0-99 ordinary app depth, 100-999 always-on-top
chrome, 1000+ menu and popup depth. A screen in a higher band
covers one in a lower band whatever their roots are; inside a band
a floating `area` or `window` root sits over ordinary content, and
a `modal` root sits over the whole stack. Tag-based
grouping lives in `Z.tags` (`Z.tags.set(name, { "editor" })`
after register).

**Parameters**

- `name` `string` — Unique screen identifier.
- `widgetTree` `WidgetTree` — Root widget table.
- `layer` `number` _(optional)_ — Z-order layer (optional).

```lua
ui.registerScreen("hud", tree)
```

## typed/builtin//modules/api/engine/ui/ui/registerTheme {#typed-builtin-modules-api-engine-ui-ui-registertheme}

```lua
ui.registerTheme(name: string, theme: ThemeDefinition)
```

Register a theme from a flat Luau table. Most callers
should use `Z.theme.register(name, table)` which runs the
cascade for them.

**Parameters**

- `name` `string` — Theme name to register.
- `theme` `ThemeDefinition` — Flat-resolved theme table.

## typed/builtin//modules/api/engine/ui/ui/removeScreen {#typed-builtin-modules-api-engine-ui-ui-removescreen}

```lua
ui.removeScreen(name: string) -> boolean
```

Alias for `ui.unregisterScreen`.

**Parameters**

- `name` `string` — Screen identifier to remove.

**Returns** `boolean` — True when a screen by this name was registered.

## typed/builtin//modules/api/engine/ui/ui/resetAreaSize {#typed-builtin-modules-api-engine-ui-ui-resetareasize}

```lua
ui.resetAreaSize(id: string)
```

Clear a `resizable` `area`'s remembered size (from a grip drag or
`ui.setAreaSize`) so its declared — or content — size takes over again.

**Parameters**

- `id` `string` — Area widget id.

## typed/builtin//modules/api/engine/ui/ui/response {#typed-builtin-modules-api-engine-ui-ui-response}

```lua
ui.response(widgetId: string) -> WidgetResponse?
```

Per-widget interaction snapshot for the most recent frame.
Returns `{ clicked, hovered, focused, changed, value }` where
`clicked` / `changed` mark transitions and `hovered` / `focused`
mark current state.

**Parameters**

- `widgetId` `string` — The widget id (NOT the onClick / onChange callback id).

**Returns** `WidgetResponse?` — WidgetResponse or nil.

## typed/builtin//modules/api/engine/ui/ui/screen {#typed-builtin-modules-api-engine-ui-ui-screen}

```lua
ui.screen(name: string) -> { [string]: any }?
```

Get a screen proxy with methods like `setResolution` and
`rasterize`.

**Parameters**

- `name` `string` — Screen name.

**Returns** `{ [string]: any }?` — Screen proxy table, or nil.

## typed/builtin//modules/api/engine/ui/ui/screenSize {#typed-builtin-modules-api-engine-ui-ui-screensize}

```lua
ui.screenSize() -> { width: number, height: number }
```

The UI coordinate space as `{ width, height }` (logical points). This is
the space `area` `pos`, anchors, and `getLayoutInfo` rects use — and it is
NOT the pixel size of a `capture` screenshot, which may be downscaled. Use
this for absolute `area` positioning (e.g. pinning a menu above a bottom
taskbar) instead of guessing the size from a capture image.

**Returns** `{ width: number, height: number }` — `{ width, height }` in logical UI points.

## typed/builtin//modules/api/engine/ui/ui/scroll {#typed-builtin-modules-api-engine-ui-ui-scroll}

```lua
ui.scroll(deltaX: number, deltaY: number)
```

Simulate a mouse-wheel scroll event on the UI.

**Parameters**

- `deltaX` `number` — Horizontal scroll delta.
- `deltaY` `number` — Vertical scroll delta.

## typed/builtin//modules/api/engine/ui/ui/setAreaPos {#typed-builtin-modules-api-engine-ui-ui-setareapos}

```lua
ui.setAreaPos(id: string, x: number, y: number)
```

Programmatically move a movable `area` widget to `(x, y)`.
Applied for one frame; subsequent frames let drag tracking
take over.

**Parameters**

- `id` `string` — Area widget id.
- `x` `number` — Target pivot x (screen coords).
- `y` `number` — Target pivot y (screen coords).

## typed/builtin//modules/api/engine/ui/ui/setAreaSize {#typed-builtin-modules-api-engine-ui-ui-setareasize}

```lua
ui.setAreaSize(id: string, w: number, h: number)
```

Programmatically set a `resizable` `area`'s size (the user-size
override) — for maximize / restore / tile. Persists until the area's
declared width/height changes or `ui.resetAreaSize(id)` clears it.

**Parameters**

- `id` `string` — Area widget id.
- `w` `number` — Target width (screen coords).
- `h` `number` — Target height (screen coords).

## typed/builtin//modules/api/engine/ui/ui/setDockWindowRect {#typed-builtin-modules-api-engine-ui-ui-setdockwindowrect}

```lua
ui.setDockWindowRect(dockId: string, panelId: string, x: number, y: number, width: number, height: number)
```

Place the floating window of a `dockArea` panel at `(x, y)` with
size `(width, height)`. Applies once the panel occupies a window —
a request made before then waits for it.

**Parameters**

- `dockId` `string` — DockArea widget id.
- `panelId` `string` — Id of the panel held by the window to place.
- `x` `number` — Window left edge (screen coords).
- `y` `number` — Window top edge (screen coords).
- `width` `number` — Window width (screen coords).
- `height` `number` — Window height (screen coords).

## typed/builtin//modules/api/engine/ui/ui/setScreenRenderLayer {#typed-builtin-modules-api-engine-ui-ui-setscreenrenderlayer}

```lua
ui.setScreenRenderLayer(name: string, mask: number)
```

Set a screen's render-layer membership bitmask. A screen draws into a
camera or capture only when this mask intersects the camera's include
mask — the same rule geometry follows. Content UI defaults to the `ui`
bit; the editor places its chrome on `EditorUI` so agent captures can
drop it. Masks come from `__renderLayers.bit(name)`.

**Parameters**

- `name` `string` — Screen identifier.
- `mask` `number` — Render-layer membership bitmask.

## typed/builtin//modules/api/engine/ui/ui/setScrollPosition {#typed-builtin-modules-api-engine-ui-ui-setscrollposition}

```lua
ui.setScrollPosition(widgetId: string, offsetY: number)
```

Set the scroll offset of a scrollArea widget.

**Parameters**

- `widgetId` `string` — Scroll area widget id.
- `offsetY` `number` — Vertical scroll offset in pixels.

## typed/builtin//modules/api/engine/ui/ui/setShaderUniforms {#typed-builtin-modules-api-engine-ui-ui-setshaderuniforms}

```lua
ui.setShaderUniforms(name: string, uniforms: { [string]: number })
```

Set uniform values on a registered background shader.

**Parameters**

- `name` `string` — Shader name identifier.
- `uniforms` `{ [string]: number }` — Map of uniform name to number value.

## typed/builtin//modules/api/engine/ui/ui/setTheme {#typed-builtin-modules-api-engine-ui-ui-settheme}

```lua
ui.setTheme(name: string)
```

Switch the active global theme by name.

**Parameters**

- `name` `string` — Theme name to activate.

## typed/builtin//modules/api/engine/ui/ui/showScreen {#typed-builtin-modules-api-engine-ui-ui-showscreen}

```lua
ui.showScreen(name: string) -> boolean
```

Make a registered screen visible, and report whether a screen by
that name is registered. The engine applies the show later in the
frame; `listScreens` reflects it from the next call onwards.

**Parameters**

- `name` `string` — Screen identifier to show.

**Returns** `boolean` — True when a screen by this name is registered.

## typed/builtin//modules/api/engine/ui/ui/unregisterCallbackEnv {#typed-builtin-modules-api-engine-ui-ui-unregistercallbackenv}

```lua
ui.unregisterCallbackEnv(key: string)
```

Remove an environment registered with `ui.registerCallbackEnv`. Its
`onCallback` stops receiving broadcasts. No-op if `key` isn't registered.

**Parameters**

- `key` `string` — The key passed to `ui.registerCallbackEnv`.

## typed/builtin//modules/api/engine/ui/ui/unregisterScreen {#typed-builtin-modules-api-engine-ui-ui-unregisterscreen}

```lua
ui.unregisterScreen(name: string) -> boolean
```

Remove a screen from the registry entirely. Unlike
`hideScreen`, this deletes the entry so it no longer appears in
`listScreens` or render iteration.

**Parameters**

- `name` `string` — Screen identifier to unregister.

**Returns** `boolean` — True when a screen by this name was registered.

## typed/builtin//modules/api/engine/ui/ui/unregisterWidget {#typed-builtin-modules-api-engine-ui-ui-unregisterwidget}

```lua
ui.unregisterWidget(name: string)
```

Drop a registered custom widget kind. Subsequent references
produce an `unknown-widget-type` diagnostic.

**Parameters**

- `name` `string` — Custom widget kind name.

## typed/builtin//modules/api/engine/ui/ui/updateScreen {#typed-builtin-modules-api-engine-ui-ui-updatescreen}

```lua
ui.updateScreen(name: string, widgetTree: WidgetTree)
```

Replace the widget tree of an already-registered screen.

**Parameters**

- `name` `string` — Screen identifier to update.
- `widgetTree` `WidgetTree` — New root widget table.

## typed/builtin//modules/api/engine/ui/ui/useStyles {#typed-builtin-modules-api-engine-ui-ui-usestyles}

```lua
ui.useStyles(themeName: string)
```

Apply a registered style file's classes additively without
changing the active theme.

**Parameters**

- `themeName` `string` — Name of the registered style / theme asset.

## typed/builtin//modules/api/engine/ui/ui/widgetState {#typed-builtin-modules-api-engine-ui-ui-widgetstate}

```lua
ui.widgetState(widgetId: string, key: string, default: any?) -> any
```

Read per-widget cross-frame state. Returns the value
previously written via `widgetStateSet`, or `default` (or nil).
State is keyed by widget id and persists across re-renders
within a screen's lifetime; cleared automatically when the
owning screen is unregistered.

**Parameters**

- `widgetId` `string` — Widget id whose state to read.
- `key` `string` — State key.
- `default` `any` _(optional)_ — Value to return when nothing has been written.

**Returns** `any` — Stored value, default, or nil.

## typed/builtin//modules/api/engine/ui/ui/widgetStateClear {#typed-builtin-modules-api-engine-ui-ui-widgetstateclear}

```lua
ui.widgetStateClear(widgetId: string, key: string)
```

Remove a per-widget state entry.

**Parameters**

- `widgetId` `string` — Widget id whose state to clear.
- `key` `string` — State key.

## typed/builtin//modules/api/engine/ui/ui/widgetStateSet {#typed-builtin-modules-api-engine-ui-ui-widgetstateset}

```lua
ui.widgetStateSet(widgetId: string, key: string, value: any?)
```

Write per-widget cross-frame state. Replaces any existing
value under `(widgetId, key)`. Tables are stored by reference.

**Parameters**

- `widgetId` `string` — Widget id to scope the state under.
- `key` `string` — State key.
- `value` `any` _(optional)_ — Value to store (must be non-nil).