registerSettings, Composer Menu & Messages: Extension Settings and Custom UIs

Aether Script Mod API v2 provides high-level APIs to integrate with Aether’s native UI:

registerSettings — add a native settings page to the Settings hub.
registerComposerMenuItem — add custom action items to the composer plus menu.
registerMessageType — define custom message renderers rendered natively in the chat timeline.

Settings pages (`registerSettings`)

registerSettings (aliased as registerSettingsPage) adds a settings page to the dedicated Extensions section in Aether’s Settings hub. The host renders the page using Aether’s built-in settings UI scaffold (cards, spacing, typography, and controls); extensions specify the data model only.

API signature

aether.registerSettings(definition: AetherSettingsDefinition): () => void;

Returns a cleanup function that removes the settings page.

Definition schema

interface AetherSettingsDefinition {
  id: string;
  title: string;
  subtitle?: string;
  icon?: string;
  order?: number;
  sections: AetherSettingsSection[];
}

interface AetherSettingsSection {
  id?: string;
  title?: string;
  description?: string;
  settings: AetherSettingDefinition[];
}

Supported control types

Each setting in sections[].settings can specify a control type:

Type	Description	Key Properties
`"text"`	Text input field	`placeholder`, `default`
`"password"`	Obfuscated password input	`placeholder`
`"textarea"`	Multi-line text input	`placeholder`, `multiline: true`
`"number"`	Numeric input field	`min`, `max`, `step`, `default`
`"toggle"`	On/off switch	`default: boolean`
`"select"` / `"dropdown"`	Native dropdown picker	`options: Array<{ value, label }>`
`"segmented"`	Segmented control buttons	`options: Array<{ value, label }>`
`"tab"` / `"tabs"`	Tab selection bar	`options: Array<{ value, label }>`
`"slider"`	Continuous or stepped slider	`min`, `max`, `step`, `default`
`"button"`	Action button	`action`, `args`, `tone: "primary" \| "neutral" \| "danger"`
`"link"`	External link or action link	`url`, `action`, `args`
`"label"`	Read-only informative label	`description`
`"divider"`	Visual divider line	—
`"spacer"`	Vertical spacing block	—

Automatic state persistence

Value controls (text, password, textarea, number, toggle, select, segmented, tab, slider) automatically persist their values in extension storage under settings:<pageId>:<settingId>.

Settings page example

aether.registerSettings({
  id: "preferences",
  icon: "settings",
  title: "Preferences",
  subtitle: "Extension behavior",
  sections: [{
    title: "General",
    description: "Configure extension behavior",
    settings: [
      { id: "endpoint", type: "text", label: "Endpoint", default: "https://example.com" },
      { id: "enabled", type: "toggle", label: "Enabled", default: true },
      {
        id: "mode",
        type: "select",
        label: "Mode",
        options: [
          { value: "fast", label: "Fast" },
          { value: "quality", label: "Quality" },
        ],
        default: "fast",
      },
    ],
  }],
});

registerComposerMenuItem (aliased as registerComposerMenu) adds a custom action entry to the composer plus menu.

API signature

aether.registerComposerMenuItem(definition: AetherComposerMenuItemDefinition): () => void;

Example

aether.registerComposerMenuItem({
  id: "insert-template",
  title: "Insert Code Template",
  subtitle: "Append boilerplate to prompt",
  icon: "code",
  action: "insert-template-action",
  args: { templateId: "react-component" },
});

Custom message types (`registerMessageType`)

registerMessageType (aliased as registerCustomMessage) registers a custom message renderer. When a message with matching type is appended to the conversation via aether.messages.append(type, payload, text), Aether renders it using your custom declarative UI tree.

API signature

aether.registerMessageType(definition: AetherMessageTypeDefinition): () => void;

Example

aether.registerMessageType({
  type: "status_card",
  title: "Status Card",
  icon: "info",
  render: ({ message }) =>
    ui.card([
      ui.text(String(message.title ?? "Status"), { style: "title" }),
      ui.text(String(message.body ?? ""), { style: "body" }),
    ]),
});

// Append a custom message to the active chat:
await aether.messages.append("status_card", {
  title: "Deployment Complete",
  body: "Build finished in 42s.",
});

Custom messages are persisted with the conversation and re-rendered whenever the chat is loaded.

Overview

Script Mod API

UI Reference

Native Mods

Pi Extensions

Examples

registerSettings, Composer Menu & Messages: Extension Settings and Custom UIs

Settings pages (`registerSettings`)

API signature

Definition schema

Supported control types

Automatic state persistence

Settings page example

Composer menu items (`registerComposerMenuItem`)

API signature

Example

Custom message types (`registerMessageType`)

API signature

Example

​Settings pages (registerSettings)

​API signature

​Definition schema

​Supported control types

​Automatic state persistence

​Settings page example

​Composer menu items (registerComposerMenuItem)

​API signature

​Example

​Custom message types (registerMessageType)

​API signature

​Example

Settings pages (`registerSettings`)

API signature

Definition schema

Supported control types

Automatic state persistence

Settings page example

Composer menu items (`registerComposerMenuItem`)

API signature

Example

Custom message types (`registerMessageType`)

API signature

Example