registerSurface: Add UI Content to Aether Chat and Settings

Surfaces let your extension add UI content to predefined locations in the Aether interface without replacing built-in components. Each surface registration targets a named slot and contributes a declarative UI tree that Aether renders in that location alongside any other registered content.

API signature

aether.registerSurface(slot: string, definition: SurfaceDefinition): () => void;

registerSurface returns a cleanup function. Call it to remove the surface registration and trigger a re-render.

Available slots

Slot	Location
`app.overlay`	Full application overlay
`chat.top`	Under the chat top bar
`chat.empty`	Empty-conversation surface
`chat.list.start`	Before committed messages
`chat.list.end`	After messages and pending work
`chat.composer.top`	Directly above the composer
`settings.hub`	Top of the settings hub
`drawer.header`	Fixed below the drawer title and search controls
`drawer.footer`	Fixed full-width content above the floating new-chat action
`drawer.list.end`	After the conversation list
`drawer`	Legacy conversation-drawer list content

Drawer slots and ordering

The drawer.header and drawer.footer slots remain fixed while the conversation list scrolls. The legacy drawer slot remains supported and renders at the tail of the conversation list in this order:

drawer
drawer.list.end
Built-in extension page launchers

Drawer opened event

Listen to drawer.opened to trigger logic when the conversation drawer opens:

aether.on("drawer.opened", (_data, context) => {
  aether.notify(`Drawer opened on ${context.screen}`);
});

On mobile, drawer.opened fires once for each closed-to-open transition, including swipe gestures. On tablet, it fires once when the permanent drawer enters composition (stable-open recompositions do not re-trigger it).

SurfaceDefinition fields

string

Unique identifier for this surface registration. Aether uses this to track and de-duplicate registrations from the same extension. If omitted, Aether generates one from the slot and registration order.

number

Controls the rendering order when multiple extensions register the same slot. Lower values render first. Defaults to 0 when omitted.

function

A factory function that receives a render context and returns a ui node tree. The function may be synchronous or async. Use either render or tree.

render: (context: RenderContext) => ui node | Promise<ui node>

object

A static ui node tree used when render is omitted.

Render context

Aether passes fields including the following to your render function on every render cycle:

Field	Type	Description
`is_running`	boolean	Whether the agent is currently generating a response
`draft_input`	string	The current text in the composer input
`storage`	object	A snapshot of your extension’s persisted storage at render time

Example

index.ts

aether.registerSurface("chat.composer.top", {
  id: "status",
  order: 10,
  render: ({ is_running, draft_input, storage }) =>
    ui.row([
      ui.text(is_running ? "Agent running" : "Ready"),
      ui.text(`${String(draft_input).length} chars`),
      ui.text(`Count: ${storage.count ?? 0}`),
    ]),
});

Call aether.invalidate() to force a re-render of all surfaces when your extension’s internal state changes. Aether does not automatically re-render surfaces on arbitrary extension-side mutations — only on storage writes, action invocations, and explicit invalidation.

Use order to ensure your surface renders in the right position when multiple extensions contribute to the same slot. Registrations with the same order value are sorted by their scoped ID as a stable tiebreaker.

Overview

Script Mod API

UI Reference

Native Mods

Pi Extensions

Examples

registerSurface: Add UI Content to Aether Chat and Settings

API signature

Available slots

Drawer slots and ordering

Drawer opened event

SurfaceDefinition fields

Render context

Example

​API signature

​Available slots

​Drawer slots and ordering

​Drawer opened event

​SurfaceDefinition fields

​Render context

​Example

API signature

Available slots

Drawer slots and ordering

Drawer opened event

SurfaceDefinition fields

Render context

Example