api.ui

Interface: IUiApi

Implementation tier: T1 (panels, decorators, hovers, menus, notifications) / T2 (displayMode, statusBar, file picker)

Contribute UI elements: panels, verse decorators, hover providers, context menu items, display modes, status bar items, notifications, quick-picks, input boxes, confirm dialogs, and file pickers.

Permissions

• ui:contribute-pane
• ui:verse-decorator
• ui:verse-hover
• ui:context-menu
• ui:notification
• ui:status-bar
• fs:read-user (for pickFile)
• fs:write-user (for saveFile)

Methods

registerPanelType

registerPanelType(def: ExtensionPanelTypeDef): Promise<DisposableHandle>

Contribute a new panel/content type.

Parameters:

Name	Type	Required	Description
def	ExtensionPanelTypeDef	Yes

Returns: Promise<DisposableHandle>

---

registerVerseDecorator

registerVerseDecorator(d: VerseDecoratorDescriptor): Promise<DisposableHandle>

Contribute a verse decorator.

Parameters:

Name	Type	Required	Description
d	VerseDecoratorDescriptor	Yes

Returns: Promise<DisposableHandle>

---

updateVerseDecorations

updateVerseDecorations(
  groupId: string,
  decorations: DecorationDto[],
): Promise<void>

Update an existing decoration group (matched by groupId). Use this when data behind a decoration changes — e.g. a stemming overlay rebuilds.

Parameters:

Name	Type	Required	Description
groupId	string	Yes
decorations	DecorationDto[]	Yes

Returns: Promise<void>

---

registerVerseHover

registerVerseHover(h: VerseHoverProviderDescriptor): Promise<DisposableHandle>

Contribute hover content for verses.

Parameters:

Name	Type	Required	Description
h	VerseHoverProviderDescriptor	Yes

Returns: Promise<DisposableHandle>

---

registerContextMenu

registerContextMenu(
  target: ContextMenuTarget,
  item: ContextMenuItemDescriptor,
): Promise<DisposableHandle>

Add an item to a built-in context menu.

Parameters:

Name	Type	Required	Description
target	ContextMenuTarget	Yes
item	ContextMenuItemDescriptor	Yes

Returns: Promise<DisposableHandle>

---

registerDisplayMode

registerDisplayMode(def: DisplayModeDescriptor): Promise<DisposableHandle>

Contribute a custom verse display mode. Appears in the Bible pane's Display Mode picker alongside Simple/Standard/Study. The host calls renderEndpoint for each visible verse, and the extension returns either decorations to overlay on the standard rendering, or an iframe URL to fully replace the verse's rendering.

Parameters:

Name	Type	Required	Description
def	DisplayModeDescriptor	Yes

Returns: Promise<DisposableHandle>

---

registerStatusBarItem

registerStatusBarItem(item: StatusBarItemDescriptor): Promise<DisposableHandle>

Contribute a status bar item. Useful for "X items indexed", "Connected to logos.com", etc.

Parameters:

Name	Type	Required	Description
item	StatusBarItemDescriptor	Yes

Returns: Promise<DisposableHandle>

---

showNotification

showNotification(msg: LocalizedString, opts?: NotificationOpts): Promise<void>

Show a non-modal toast.

Parameters:

Name	Type	Required	Description
msg	LocalizedString	Yes
opts	NotificationOpts	No

Returns: Promise<void>

---

showQuickPick

showQuickPick<T>(
  items: QuickPickItemDescriptor<T>[],
  opts?: QuickPickOpts,
): Promise<T | undefined>

Show a quick-pick prompt. The promise resolves with the user's selection or undefined.

Parameters:

Name	Type	Required	Description
items	QuickPickItemDescriptor<T>[]	Yes
opts	QuickPickOpts	No

Returns: Promise<T | undefined>

---

showInputBox

showInputBox(opts: InputBoxOpts): Promise<string | undefined>

Show a single-line input prompt.

Parameters:

Name	Type	Required	Description
opts	InputBoxOpts	Yes

Returns: Promise<string | undefined>

---

showConfirm

showConfirm(opts: ConfirmOpts): Promise<boolean>

Show a modal confirm dialog.

Parameters:

Name	Type	Required	Description
opts	ConfirmOpts	Yes

Returns: Promise<boolean>

---

pickFile

pickFile(opts?: PickFileOpts): Promise<PickedFileDto | undefined>

Open the system file picker for the user to choose a file. Requires fs:read-user. The host returns the file contents (not the path) so the extension never sees absolute paths.

Parameters:

Name	Type	Required	Description
opts	PickFileOpts	No

Returns: Promise<PickedFileDto | undefined>

---

saveFile

saveFile(
  content: string | ArrayBuffer | Uint8Array,
  opts?: SaveFileOpts,
): Promise<boolean>

Open the system save picker. Requires fs:write-user.

Parameters:

Name	Type	Required	Description
content	string | ArrayBuffer | Uint8Array	Yes
opts	SaveFileOpts	No

Returns: Promise<boolean>

---