Declarative UI Nodes for Aether Extension Surfaces

Aether’s ui factory provides a set of declarative node types that render as native Android Compose views inside surfaces, components, and pages. Each factory call returns a plain node descriptor object; Aether’s Android renderer resolves these descriptors into Compose components at display time.

Import

import { ui } from "@aether/extension-api";

You can also access ui directly from the aether parameter passed to your extension factory:

export const activateAether = defineAetherExtension((aether) => {
  const { ui } = aether; // equivalent to the named import
});

Node types reference

Layout

`ui.column(children, opts?)`

Stacks its children vertically.

ui.column([
  ui.text("Line 1"),
  ui.text("Line 2"),
])

`ui.row(children, opts?)`

Arranges children horizontally. By default the row fills the available width and keeps all children on one line.

Option	Type	Description
`wrap`	`boolean`	Allow children to wrap onto multiple lines. Useful for narrow Android layouts.
`rowSpacing`	`number`	Spacing between wrapped lines.
`maxItemsInEachRow`	`number`	Cap the number of items per line when wrapping is enabled.

A direct child may set weight to consume the remaining horizontal space while sibling controls keep their intrinsic size.

ui.row([
  ui.text("Label"),
  ui.button("Action", "my-action", { weight: 1 }),
])

`ui.box(children, opts?)`

An overlay/stack container that draws children on top of each other.

ui.box([
  ui.text("Background layer"),
  ui.text("Foreground layer"),
])

`ui.scroll(children, opts?)`

Wraps its children in a scrollable container.

ui.scroll([
  ui.text("Item 1"),
  ui.text("Item 2"),
  // ... many more items
])

`ui.spacer(size?, opts?)`

Inserts flexible space. The size parameter sets the spacing in dp (default: 8).

ui.row([
  ui.text("Left"),
  ui.spacer(16),
  ui.text("Right"),
])

Text

`ui.text(content, opts?)`

Renders a text string. Use opts.style to apply a typographic role:

Style	Description
`"headline"`	Large display heading
`"title"`	Section or card title
`"body"`	Default body copy
`"caption"`	Small supplementary text
`"code"`	Inline monospace text

ui.text("Hello Aether", { style: "headline" })

`ui.code(content, opts?)`

Renders content as a monospace code block.

ui.code("const x = 42;")

Interactive

`ui.button(label, actionId, opts?)`

A tappable button that fires a registered action when pressed.

Option	Type	Description
`args`	`object`	Arguments forwarded to the action handler.
`weight`	`number`	Consume remaining horizontal space inside a row.
`width`	`number`	Explicit width override in dp.

ui.button("Run", "run-action", { args: { verbose: true } })

Button labels always render on a single line. Providing weight or an explicit width overrides the default fill behavior.

`ui.iconButton(icon, actionId, opts?)`

An icon-only button. Use this to conserve horizontal space when a text label isn’t needed.

ui.iconButton("refresh", "reload-data")

`ui.switch(label, checked, actionId, opts?)`

A labeled toggle switch. Pass the current boolean state as checked.

ui.switch("Enable feature", storage.featureEnabled ?? false, "toggle-feature")

The switch factory signature is ui.switch(label, checked, actionId, opts?). Unlike button, the current state is a positional argument — not an option — so the action handler always receives an up-to-date value.

`ui.input(value, actionId, opts?)`

A text input field. Pass the current string value as the first argument.

Option	Type	Description
`multiline`	`boolean`	Allow the input to expand to multiple lines.

ui.input(storage.query ?? "", "update-query", { multiline: false })

`ui.card(children, opts?)`

An elevated card container that groups related content.

ui.card([
  ui.text("Card title", { style: "title" }),
  ui.text("Card body"),
])

`ui.node("pageButton", opts)`

A navigation button that opens the registered page with the given id when tapped. Use ui.node("pageButton", { page, label?, icon?, width? }) — there is no dedicated ui.pageButton factory function.

Option	Type	Description
`page`	`string`	The `id` of the page registered with `registerPage`.
`label`	`string`	Button label text.
`icon`	`string`	Optional icon name.
`width`	`string \| number`	Width override, e.g. `"fill"` to expand the button.

ui.node("pageButton", {
  page: "dashboard",
  label: "Dashboard",
  icon: "code",
  width: "fill",
})

Progress and composition

`ui.progress(value?, opts?)`

Renders a progress indicator. Omit value for an indeterminate (spinning) state; pass a number between 0 and 1 for a determinate bar.

ui.progress()          // indeterminate
ui.progress(0.65)      // 65 % complete

`ui.core()`

A placeholder that marks where the wrapped native or replacement content should render inside a wrap-mode component registration. Use it inside registerComponent calls with mode: "wrap".

aether.registerComponent("chat.composer.actionTray", {
  id: "my-wrapper",
  mode: "wrap",
  render: () =>
    ui.column([
      ui.text("Above the original"),
      ui.core(),
      ui.text("Below the original"),
    ]),
});

Combining nodes — full surface example

The example below registers an action that increments a persistent counter and a surface that renders it above the chat composer.

import { defineAetherExtension, ui } from "@aether/extension-api";

export const activateAether = defineAetherExtension((aether) => {
  aether.registerAction("increment", ({ amount = 1 }) => {
    const count = aether.storage.get("count", 0) + Number(amount);
    aether.storage.set("count", count);
    aether.invalidate();
  });

  aether.registerSurface("chat.composer.top", {
    id: "counter-surface",
    render: ({ is_running, storage }) =>
      ui.card([
        ui.row([
          ui.text(`Count: ${storage.count ?? 0}`, { style: "title" }),
          ui.button("+1", "increment", { args: { amount: 1 } }),
        ]),
        is_running
          ? ui.text("Agent is running...", { style: "caption" })
          : ui.progress(),
      ]),
  });
});

All ui.* factories return a plain JavaScript object — the node descriptor. Aether’s Android renderer resolves these objects to Compose components when the surface or page is displayed.

Row children fill available width by default. Set weight on one child to let it expand while sibling controls keep their intrinsic size. For example, placing { weight: 1 } on a button stretches it to fill the remaining row space alongside a fixed-width label.

​Import

​Node types reference

​Layout

​ui.column(children, opts?)

​ui.row(children, opts?)

​ui.box(children, opts?)

​ui.scroll(children, opts?)

​ui.spacer(size?, opts?)

​Text

​ui.text(content, opts?)

​ui.code(content, opts?)

​Interactive

​ui.button(label, actionId, opts?)

​ui.iconButton(icon, actionId, opts?)

​ui.switch(label, checked, actionId, opts?)

​ui.input(value, actionId, opts?)

​Cards and navigation

​ui.card(children, opts?)

​ui.node("pageButton", opts)

​Progress and composition

​ui.progress(value?, opts?)

​ui.core()

​Combining nodes — full surface example

Import

Node types reference

Layout

`ui.column(children, opts?)`

`ui.row(children, opts?)`

`ui.box(children, opts?)`

`ui.scroll(children, opts?)`

`ui.spacer(size?, opts?)`

Text

`ui.text(content, opts?)`

`ui.code(content, opts?)`

Interactive

`ui.button(label, actionId, opts?)`

`ui.iconButton(icon, actionId, opts?)`

`ui.switch(label, checked, actionId, opts?)`

`ui.input(value, actionId, opts?)`

Cards and navigation

`ui.card(children, opts?)`

`ui.node("pageButton", opts)`

Progress and composition

`ui.progress(value?, opts?)`

`ui.core()`

Combining nodes — full surface example