Extension Dialogs

Native macOS sheets an extension can present on the main window: a multi-button confirm dialog, an alert, a single-field prompt, and a folder picker (pickFolder). Each renders as a real NSAlert/NSOpenPanel sheet attached to the Muxy window — they look identical to the app's own prompts and block until the user responds.

dialog is available on all three surfaces: webview pages (tabs, panels, popovers) via window.muxy, runScript palette-command scripts via muxy, and the background script muxy global. It needs no permission — the user has to dismiss every dialog themselves, so there is nothing to gate (what permissions don't gate).

On webview pages confirm/alert return a Promise — use await. In runScript and background scripts they are synchronous and return the result directly; await is harmless but not required. In every case the call blocks until the user responds.

confirm

Shows a dialog with up to your supplied buttons and resolves with the label of the button the user clicked, or null if they cancelled (Esc, or the cancel button).

const choice = await muxy.dialog.confirm({
  title: 'Delete branch?',
  message: 'This permanently removes feature/login and cannot be undone.',
  buttons: ['Delete', 'Cancel'],
  default: 'Cancel',   // the focused (Return) button
  cancel: 'Cancel',    // Esc maps here; clicking it resolves null
  style: 'warning',    // 'info' (default) | 'warning' | 'critical'
});

if (choice === 'Delete') { /* … */ }

The resolved value is always the exact label string you passed (or null), so compare against your own labels rather than an index.

alert

Shows an OK dialog and resolves once the user dismisses it. Alerts with a non-empty message also include Copy with the Command-C shortcut; it copies the complete message even when the displayed text is truncated.

await muxy.dialog.alert({
  title: 'Build finished',
  message: 'All 42 tests passed.',
  style: 'info',
});

prompt

Shows a dialog with a single text field and resolves with the entered string, or null if the user cancelled (Esc or the cancel button).

const name = await muxy.dialog.prompt({
  title: 'Rename worktree',
  message: 'Enter a new branch name.',
  default: 'feature/login',   // pre-filled text
  placeholder: 'branch name', // shown when empty
  confirm: 'Rename',          // confirm button label (default 'OK')
  cancel: 'Cancel',           // cancel button label (default 'Cancel')
});

if (name !== null) { /* … */ }

pickFolder

Opens a native folder picker and resolves with the absolute path of the chosen directory, or null if cancelled.

const folder = await muxy.dialog.pickFolder({
  title: 'Choose a project folder',
  message: 'Add',           // the panel's confirm button label
  default: '~/Projects',    // initial directory (tilde expanded)
});

if (folder !== null) { /* … */ }

Notes

• The call blocks the caller until the user responds. From a background script this pauses that script's event loop the same way exec does, so don't open a dialog from a hot event path.
• Only one dialog per extension can be open at a time; a second call while one is showing rejects rather than stacking sheets.
• title, displayed message text, and each button label are capped at 2000 characters, and buttons is limited to the first 3. An alert's Copy action preserves the complete message.
• Dialogs present as a sheet on the main Muxy window; if no window is available the call rejects rather than presenting a blocking dialog.
• A popover stays open while its dialog is showing, so the resolved result reaches the popover page.