# Dialogs

`win.dialogs()` and `wm.dialogs()` are the promise-based `alert` / `confirm` / `prompt` factory built into the SGApps window-manager, plus a `customPopup` escape hatch for dialogs that don't fit those three shapes. Every dialog is a real WM window — parented to the caller (for `win.dialogs()`) or floating at the manager root (for `wm.dialogs()`) — so it inherits the same focus cascade, close cascade, chrome, and styling as any other app window.

The API contract mirrors `electron.dialog.showMessageBox(browserWindow, opts)`, so an Electron adapter can later swap the DOM path for native OS dialogs without call-site changes.

Related: [Window Manager](window-manager.md) covers how to obtain a `wm`; [Window](window.md) covers the `win` object.

## Try it live

The buttons below drive a real window-manager loaded via `exporter.js` on this page — the same `wm` instance the code snippets use. First click boots the SDK (~1 s); subsequent clicks reuse it.

<script>
(function () {
    if (window.__docsWm) return;
    // Lazy-load exporter.js (only the first inline script in a docsify
    // page executes on route change, so both the loader and the boot
    // logic have to live inside a single script tag).
    if (!window.__docsWmExporterLoading) {
        window.__docsWmExporterLoading = true;
        var s = document.createElement("script");
        // Absolute URL matters — exporter.js infers the RootHost from
        // its own `<script src>` via a `//host` regex, and a same-origin
        // relative path fails that check, yielding a broken RootHost.
        s.src = location.origin + "/scripts/modules-webapp/exporter.js";
        document.head.appendChild(s);
    }
    window.__docsWmBoot = function (cb) {
        if (window.__docsDemoWm) return cb(window.__docsDemoWm);
        if (!window.__docsWmBooting) {
            window.__docsWmBooting = true;
            var waitApp = setInterval(function () {
                if (typeof Application !== "function") return;
                clearInterval(waitApp);
                Application(function (App) {
                    App["exporter:configuration:full"]().then(function () {
                        App.require(["wm :: sgapps-webapps.b2b.window-manager"]).then(function (libs) {
                            if (!document.querySelector(".windowManager")) {
                                document.body.appendChild(libs.wm.root());
                            }
                            window.__docsDemoWm = libs.wm;
                        });
                    });
                });
            }, 100);
        }
        var tries = 0;
        var t = setInterval(function () {
            tries++;
            if (window.__docsDemoWm) { clearInterval(t); cb(window.__docsDemoWm); }
            else if (tries > 300) { clearInterval(t); console.error("WM boot timed out"); }
        }, 50);
    };
    window.__docsWm = function (fn) { window.__docsWmBoot(fn); };
    // Handlers wired into the demo buttons below. Kept as named functions
    // so button onclick attributes stay simple — the docsify markdown
    // parser trips on `\\'`-style escapes inside inline attributes.
    var W = window.__docsWm;
    var setLog = function (id, txt) { var el = document.getElementById(id); if (el) el.textContent = txt; };
    window.__docsDemoAlertShort = function () { W(function (wm) { wm.dialogs().alert("File saved successfully."); }); };
    window.__docsDemoAlertLong = function () {
        W(function (wm) {
            wm.dialogs().alert(
                "This is a longer notification spanning multiple sentences. " +
                "Long content scrolls inside the body while OK stays pinned; " +
                "the dialog sizes to the JS-supplied width and height (defaults 380×200 when omitted).\n\n" +
                "Second paragraph — line breaks are preserved via pre-wrap."
            );
        });
    };
    window.__docsDemoAlertDetails = function () {
        W(function (wm) {
            wm.dialogs().alert("Could not load configuration:", {
                title:   "Error",
                icon:    "paper/icons/status/dialog-error",
                details: "Error: ENOENT — file not found\n    at readConfig (config.js:42:11)\n    at bootApp (main.js:17:5)"
            });
        });
    };
    window.__docsDemoAlertEl = function () {
        W(function (wm) {
            var el = document.createElement("div");
            el.innerHTML =
                "<h3>Backup done</h3>" +
                "<ul>" +
                    "<li><code>database</code> — 12.4 MB</li>" +
                    "<li><code>media/</code> — 380 files</li>" +
                    "<li><code>config/</code> — 8 files</li>" +
                "</ul><hr>" +
                "<p style=\"color:#666;font-size:11px;\">Duration: 4.2 s · Location: /var/backups/2026-07-15.tar.gz</p>";
            wm.dialogs().alert(el, { title: "Backup complete" });
        });
    };
    window.__docsDemoAlertHtml = function () {
        W(function (wm) {
            wm.dialogs().alert({
                html:
                    "<h2>Version 1.5.0</h2>" +
                    "<ul>" +
                        "<li>Window dialogs</li>" +
                        "<li>Large-controls toggle</li>" +
                    "</ul><hr>" +
                    "<p>See <a href=\"#/window-manager\">Window Manager</a>.</p>"
            }, { title: "What is new" });
        });
    };
    window.__docsDemoConfirmPlain = function () {
        W(function (wm) {
            wm.dialogs().confirm("Delete this file?").then(function (r) { setLog("demo-confirm-out", "result: " + r.result); });
        });
    };
    window.__docsDemoConfirmDanger = function () {
        W(function (wm) {
            wm.dialogs().confirm("This action cannot be undone. Revoke access for 2 devices and 5 sessions?", {
                title: "Confirm revoke", destructive: true, yesLabel: "Revoke", noLabel: "Cancel"
            }).then(function (r) { setLog("demo-confirm-out", "result: " + r.result); });
        });
    };
    window.__docsDemoConfirmRich = function () {
        W(function (wm) {
            var el = document.createElement("div");
            el.innerHTML = "<p><b>Not undoable.</b></p><ul><li>2 Android devices</li><li>1 API token</li><li>5 active sessions</li></ul><p>Continue?</p>";
            wm.dialogs().confirm(el, { title: "Confirm revoke", destructive: true, yesLabel: "Yes, revoke" })
                .then(function (r) { setLog("demo-confirm-out", "result: " + r.result); });
        });
    };
    window.__docsDemoPromptSingle = function () {
        W(function (wm) {
            wm.dialogs().prompt("New file name:", "report-2026.pdf", { placeholder: "name.ext" })
                .then(function (r) { setLog("demo-prompt-out", "result: " + JSON.stringify(r.result)); });
        });
    };
    window.__docsDemoPromptMulti = function () {
        W(function (wm) {
            wm.dialogs().prompt("Describe your changes (Ctrl+Enter to submit):", "", {
                multiline: true, rows: 5, placeholder: "what changed..."
            }).then(function (r) { setLog("demo-prompt-out", "result: " + JSON.stringify(r.result)); });
        });
    };
    window.__docsDemoPromptPwd = function () {
        W(function (wm) {
            wm.dialogs().prompt("Enter your password:", "", { inputType: "password", placeholder: "••••••••" })
                .then(function (r) {
                    setLog("demo-prompt-out", "result: " + (r.result === null ? "null (cancelled)" : "entered " + r.result.length + " chars"));
                });
        });
    };
    // customPopup — build the dialog body yourself, resolve manually.
    // Two demos: (1) an <input type="color"> that resolves the picked hex,
    // (2) a three-button "rating" panel that shows any DOM shape is fine.
    window.__docsDemoCustomColor = function () {
        W(function (wm) {
            var ctx = wm.dialogs().customPopup({
                title: "Pick a colour", icon: "paper/icons/actions/color-picker",
                width: 320, height: 180, escResult: null
            });
            var wrap = document.createElement("div");
            wrap.style.cssText = "padding:16px;display:flex;flex-direction:column;gap:10px;align-items:stretch;";
            var input = document.createElement("input");
            input.type = "color"; input.value = "#a6bb11";
            input.style.cssText = "width:100%;height:56px;cursor:pointer;border:1px solid #ccc;border-radius:4px;";
            var hint = document.createElement("div");
            hint.style.cssText = "font-size:12px;opacity:0.7;text-align:center;";
            hint.textContent = "change → resolve · ESC → cancel";
            wrap.appendChild(input); wrap.appendChild(hint);
            ctx.container.appendChild(wrap);
            input.addEventListener("change", function () { ctx.resolve(input.value); });
            ctx.focusFirst();
            ctx.promise.then(function (r) {
                setLog("demo-custom-out", "result: " + (r.result === null ? "null (cancelled)" : r.result));
            });
        });
    };
    window.__docsDemoCustomRating = function () {
        W(function (wm) {
            var ctx = wm.dialogs().customPopup({
                title: "Rate this feature", width: 340, height: 170, escResult: 0
            });
            var wrap = document.createElement("div");
            wrap.style.cssText = "padding:20px;display:flex;flex-direction:column;gap:14px;align-items:center;";
            var label = document.createElement("div");
            label.textContent = "How would you rate the docs?";
            label.style.cssText = "font-size:13px;";
            var row = document.createElement("div");
            row.style.cssText = "display:flex;gap:6px;";
            [1,2,3,4,5].forEach(function (n) {
                var b = document.createElement("button");
                b.textContent = "★".repeat(n);
                b.style.cssText = "padding:8px 12px;font-size:14px;cursor:pointer;border:1px solid #ccc;border-radius:4px;background:#fff;";
                b.addEventListener("click", function () { ctx.resolve(n); });
                row.appendChild(b);
            });
            wrap.appendChild(label); wrap.appendChild(row);
            ctx.container.appendChild(wrap);
            ctx.promise.then(function (r) {
                setLog("demo-custom-out", "result: " + (r.result || "0 (skipped)") + (r.result ? " ★".repeat(r.result) : ""));
            });
        });
    };
})();
</script>

<style>
.docs-demo-row { display: flex; flex-wrap: wrap; gap: 8px; margin: 10px 0 18px; }
.docs-demo-row button {
    padding: 6px 12px; border: 1px solid rgba(45,108,223,0.5); border-radius: 4px;
    background: rgba(45,108,223,0.08); color: inherit; font-size: 13px; cursor: pointer;
    font-family: inherit;
}
.docs-demo-row button:hover { background: rgba(45,108,223,0.18); }
.docs-demo-row button:active { transform: translateY(1px); }
.docs-demo-log {
    display: block; margin: 4px 0 14px; padding: 6px 10px;
    background: rgba(0,0,0,0.05); border-left: 3px solid #2d6cdf; border-radius: 3px;
    font-family: "Fira Mono", "SFMono-Regular", Consolas, monospace; font-size: 11px;
    min-height: 18px; white-space: pre-wrap; word-break: break-word;
}
</style>

**Alerts:**

<div class="docs-demo-row">
<button onclick="__docsDemoAlertShort()">▶ alert · short text</button>
<button onclick="__docsDemoAlertLong()">▶ alert · long text</button>
<button onclick="__docsDemoAlertDetails()">▶ alert · with details</button>
<button onclick="__docsDemoAlertEl()">▶ alert · HTMLElement</button>
<button onclick="__docsDemoAlertHtml()">▶ alert · {html} shortcut</button>
</div>

**Confirms:**

<div class="docs-demo-row">
<button onclick="__docsDemoConfirmPlain()">▶ confirm · plain</button>
<button onclick="__docsDemoConfirmDanger()">▶ confirm · destructive</button>
<button onclick="__docsDemoConfirmRich()">▶ confirm · rich content</button>
</div>

<span id="demo-confirm-out" class="docs-demo-log">Result appears here…</span>

**Prompts:**

<div class="docs-demo-row">
<button onclick="__docsDemoPromptSingle()">▶ prompt · single line</button>
<button onclick="__docsDemoPromptMulti()">▶ prompt · multi-line</button>
<button onclick="__docsDemoPromptPwd()">▶ prompt · password</button>
</div>

<span id="demo-prompt-out" class="docs-demo-log">Result appears here…</span>

**Custom popups:**

<div class="docs-demo-row">
<button onclick="__docsDemoCustomColor()">▶ customPopup · colour picker</button>
<button onclick="__docsDemoCustomRating()">▶ customPopup · rating (1–5)</button>
</div>

<span id="demo-custom-out" class="docs-demo-log">Result appears here…</span>

## Two entry points

```js
// Parented to a specific window — closes when that window closes,
// raises on top when that window is focused
this.window().dialogs().alert("File saved");

// Rooted at the manager — no owning parent, no cascade.
// Use for global flows (session expired, logout confirm, app-level errors).
wm.dialogs().alert("Session expired", {
    icon: "paper/icons/status/dialog-warning"
});
```

The two entry points return an object with the same four methods. `alert` / `confirm` / `prompt` share the same promise-based contract; `customPopup` is the escape hatch for dialogs that don't fit those three shapes (see [customPopup](#custompopup-opts) below). Only the parent binding differs.

## Methods

`alert` / `confirm` / `prompt` each return `Promise<{ window, result }>`:
- `window` — the dialog's `WindowApplication` instance (already closed by the time the promise resolves; useful only for logging or subclass extensions)
- `result` — the user's answer; type depends on the method

`customPopup` returns a **context object synchronously** instead of a promise — see its own section for the contract.

### `alert(message, opts?)`

One message, one OK button. Escape and Enter both resolve with `undefined`.

```js
win.dialogs().alert("Backup complete.").then(function (r) {
    // r.result === undefined
});
```

### `confirm(message, opts?)`

One message, Yes/No buttons. Enter → `true`, Escape → `false`. Pass `opts.destructive: true` to turn the Yes button red.

```js
win.dialogs().confirm("Delete file?", {
    destructive: true,
    yesLabel:  "Delete",
    noLabel:   "Cancel"
}).then(function (r) {
    if (r.result) doDelete();
});
```

### `prompt(message, defaultValue?, opts?)`

One message, one input, OK/Cancel. Enter (single-line) or Ctrl/Cmd+Enter (multiline) submits the value. Escape resolves `null` — matches native `window.prompt`.

```js
win.dialogs().prompt("New file name:", "untitled.txt", {
    placeholder: "name.ext"
}).then(function (r) {
    if (r.result !== null) rename(r.result);
});

// Multiline
win.dialogs().prompt("Describe the change:", "", {
    multiline: true,
    rows: 5,
    placeholder: "what changed…"
}).then(function (r) {
    if (r.result !== null) commitWithMessage(r.result);
});
```

### `.prompt(message, opts)` — signature tolerance

If the second argument is an options object (not a string default), it's treated as `opts` and `opts.defaultValue` fills in:

```js
win.dialogs().prompt("Your name?", { placeholder: "type here…" });
// same as .prompt("Your name?", undefined, { placeholder: "type here…" })
```

### `customPopup(opts?)`

Escape hatch for dialogs that don't fit `alert` / `confirm` / `prompt`. Opens a window pre-wired with all the shared plumbing (parent-child focus / close cascade, ESC → resolve, default geometry centred on parent), then hands back a **context object** so the caller owns the body.

**Contract differences vs the other three methods**

| | `alert / confirm / prompt` | `customPopup` |
|---|---|---|
| **Returns** | `Promise<{window, result}>` | `{ dlg, promise, resolve, container, focusFirst }` synchronously |
| **Message arg** | Required (string / HTMLElement / `{html}`) | None — you populate `container` yourself |
| **Buttons** | Built-in (OK / Yes-No / OK-Cancel) | None — you add whatever you want |
| **ESC → resolve** | Method-specific default (`undefined` / `false` / `null`) | `opts.escResult`, defaults to `undefined` |
| **Sizing** | JS defaults 380×200 (opts.width/height override); body scrolls when content overflows | JS defaults 380×200 (opts.width/height override); caller owns the body, so overflow behaviour is whatever they build |

**Returned context**

| Property | Type | Purpose |
|---|---|---|
| `dlg` | `WindowApplication` | The dialog window handle — same surface as any WM window. Getter/setter accessors `dlg.title(str?)`, `dlg.width(px?)`, `dlg.height(px?)`, `dlg.left(px?)`, `dlg.top(px?)`, `dlg.icon(id?)`; lifecycle `dlg.close(force)`, `dlg.focus()`, `dlg.maximize / minimize / restore()`; events `dlg.on(evt, fn)` / `dlg.once` / `dlg.off`; DOM `dlg.container()` / `dlg.node()`; class helpers `dlg.addClass / removeClass`. Note there is no `dlg.resize(w, h)` — set width and height with the individual accessors. |
| `promise` | `Promise<{window, result}>` | Resolves when `resolve(v)` is called or the dialog closes by another path (ESC, parent cascade, external close). On non-resolve close, `result === opts.escResult` |
| `resolve(value)` | `function` | Close the dialog and resolve `promise` with `value`. Idempotent — safe to bind to multiple events |
| `container` | `HTMLElement` | The dialog's inner container. Cleared before return — populate with any DOM (buttons, inputs, canvas, iframe, …) |
| `focusFirst()` | `function` | Focus the first `button.is-primary` / `button` / `input` / `textarea` inside `container`. Call it after populating |

**Example — colour picker**

```js
var ctx = win.dialogs().customPopup({
    title: "Pick a colour",
    width: 320, height: 180,
    escResult: null                            // ESC → cancelled
});

var input = document.createElement("input");
input.type = "color";
input.value = "#a6bb11";
ctx.container.appendChild(input);

input.addEventListener("change", function () {
    ctx.resolve(input.value);                  // close + settle with hex
});

ctx.focusFirst();

ctx.promise.then(function (r) {
    if (r.result !== null) applyBrandColour(r.result);
});
```

**When to reach for `customPopup`**

- The dialog has more than one input, or an input the built-in `prompt` doesn't cover (radio group, colour, file, date range, canvas signature pad, …).
- The dialog is a multi-step wizard whose result depends on which "Next" branch the user takes.
- You need an embedded iframe, video, or third-party widget as the dialog body.
- You want a dialog whose body updates over time (progress bar, live log stream) and closes on a specific event rather than an OK click.

**When NOT to reach for `customPopup`**

- A single message + OK / Yes-No / one input covers your case — `alert` / `confirm` / `prompt` are shorter, keyboard-mapped by default, and match the Electron adapter surface.
- You just need rich HTML content inside a standard OK dialog — pass an `HTMLElement` or `{html: "..."}` as the message to `alert` / `confirm` and skip the manual wiring.

**Scrolling — `scrollable: true`**

The dialog window's inner `<section>` has `overflow: hidden` by default. That is intentional for the standard shell: `.windowManager--dialog-body` owns the scroll region, buttons stay pinned to the bottom via a flex column, and hiding the section prevents phantom scrollbars from 1-pixel rounding drift.

When you build a **custom** body that does **not** follow that shell (`.windowManager--dialog` > `.windowManager--dialog-body` + `.windowManager--dialog-buttons`), the section-level `overflow: hidden` clips anything that overruns the viewport — on small screens the operator can't reach content past the bottom of the section. Pass `scrollable: true` to opt out.

```js
// Long form that doesn't use the standard shell — let the section scroll.
var ctx = win.dialogs().customPopup({
    title: "Edit user",
    width: 560, height: 480,
    escResult: "cancel",
    scrollable: true               // <-- section can scroll now
});

// Fill ctx.container directly, no .dialog-body wrapper needed.
```

Rule of thumb:

- **Standard shell** (you mount `.windowManager--dialog` + `.dialog-body` + `.dialog-buttons`): leave `scrollable` **off**. The body scrolls in place while buttons stay pinned.
- **Free-form container** (you paint straight into `ctx.container` with no body/button separation): turn `scrollable` **on**. Otherwise a body taller than the viewport is unreachable.

Under the hood the option toggles the `windowManager--window-class--dialog-scroll` class on the dialog window; the CSS rule that reacts to it lives next to the base dialog section rule in `window-manager/style.css`.

## Content — string, HTMLElement, or `{html}`

The first argument accepts three shapes. Everything else in the API is unchanged.

### 1. Plain text

Pre-wrap + word-break so long content stays readable at any dialog width.

```js
win.dialogs().alert("File saved successfully.");
```

### 2. HTMLElement

Appended directly. You control the structure; the WM stylesheet provides sensible defaults for `h1-h4`, `p`, `ul/ol`, `code`, `pre`, `table`, `a`, `hr`, and media elements.

```js
var el = document.createElement("div");
el.innerHTML =
    '<h3>Backup done</h3>' +
    '<ul>' +
        '<li><code>database</code> — 12.4 MB</li>' +
        '<li><code>media/</code> — 380 files</li>' +
    '</ul>';
win.dialogs().alert(el, { title: "Backup complete" });
```

### 3. `{ html: "..." }` shortcut

For static HTML you'd otherwise stringify. Semantically identical to option 2 but skips the `createElement + innerHTML` boilerplate.

```js
win.dialogs().confirm({
    html:
        '<p><b>Not undoable.</b></p>' +
        '<p>Revoke access for 2 devices and 5 sessions?</p>'
}, { title: "Confirm revoke", destructive: true, yesLabel: "Revoke" });
```

## Options

Everything is optional. Only sensible defaults apply when omitted.

```js
opts = {
    title,          // window title (defaults: "Notification" / "Confirm" / "Input" / "Dialog")
    icon,           // e.g. "paper/icons/status/dialog-warning"
    okLabel,        // default "OK"     — alert / prompt
    cancelLabel,    // default "Cancel" — prompt
    yesLabel,       // default "Yes"    — confirm (also accepts okLabel)
    noLabel,        // default "No"     — confirm (also accepts cancelLabel)
    details,        // string | HTMLElement | {html} — collapsible info block under the message
    destructive,    // confirm only — Yes button turns red ("is-danger" style)
    multiline,      // prompt only — <textarea> instead of <input>; Ctrl/Cmd+Enter submits
    rows,           // prompt multiline — visible rows in the textarea
    placeholder,    // prompt only — input placeholder
    inputType,      // prompt only — "text" | "password" | "email" | "number"
    escResult,      // customPopup only — value settled into `result` when the
                    //                    dialog is closed without an explicit
                    //                    resolve() call (ESC / parent cascade /
                    //                    external close). Defaults to `undefined`
    scrollable,     // customPopup only — when true, the window's <section>
                    //                    scrolls on its own. Use when the body
                    //                    you mount doesn't follow the standard
                    //                    .windowManager--dialog shell (see the
                    //                    "Scrolling" note under customPopup).
                    //                    Off by default.
    width,          // dialog width in px; honoured as-is, clamped only by defaultGeometry
                    //   to viewport-20px as a safety net. Default 380.
    height          // dialog height in px; same rules as width. Default 200.
}
```

## Cascade behavior (window-scoped only)

When you use `win.dialogs()` — not `wm.dialogs()` — the dialog is a **modal child** of `win`. That parenthood drives four cascades:

| Trigger | Effect |
|---|---|
| Parent `focus` | Every child dialog is raised on top; the most-recently-opened one gets input focus. Users can never lose a dialog behind its parent. |
| Parent soft `close(false)` | Each child receives `close(false)` — their own `closeRequest` subscribers may still abort |
| Parent force `close(true)` | Each child is force-closed. Any pending `closeRequest` abort is bypassed |
| Dialog `closed` | The promise resolves; parent regains focus |

`wm.dialogs()` (parent = `null`) skips all of this — the dialog stands alone at manager root, closes only when the user acts on it.

## Keyboard

| Key | Action |
|---|---|
| **Escape** | Cancel — `alert` resolves `undefined`, `confirm` resolves `false`, `prompt` resolves `null` |
| **Enter** | Default action — OK for `alert`, Yes for `confirm`, submit input for `prompt` (single-line) |
| **Ctrl / Cmd + Enter** | Submit input for `prompt` when `multiline: true` (plain Enter inserts a newline in the textarea) |

## Sizing

Dialogs use the JS defaults (`380 × 200`) when `opts.width` / `opts.height` are omitted, and honour caller-supplied values as-is when provided. Long content scrolls inside the body — `.windowManager--dialog-body` has `overflow: auto` and takes whatever space is left after the (fixed-size) button bar, so buttons stay pinned to the bottom regardless of content length.

Only safety net: `defaultGeometry` in `dialogs.js` clamps a caller-supplied width/height to viewport minus 20px, keeping the dialog on-screen when someone passes an oversize value. Nothing in CSS caps the dialog dimensions.

Multiple concurrent dialogs open on the same parent stagger their positions so they don't stack on the same pixel.

## Common patterns

### 1. Confirm before close

```js
var dirty = false;
// ... some listener toggles `dirty` on content change ...

win.on("closeRequest", function (abort) {
    if (!dirty) return;               // clean → allow soft-close
    abort();                          // hold the pending close
    win.dialogs().confirm("Discard unsaved changes?", {
        destructive: true,
        yesLabel:    "Discard",
        noLabel:     "Keep editing"
    }).then(function (r) {
        if (r.result) win.close(true); // force this time to bypass this handler
    });
});
```

### 2. Prompt for rename

```js
win.dialogs().prompt("Rename to:", currentName, {
    placeholder: "new-name.ext"
}).then(function (r) {
    if (r.result !== null && r.result.trim() !== currentName) {
        rename(r.result.trim());
    }
});
```

### 3. Show an error with the stack trace

```js
try {
    doDangerousThing();
} catch (err) {
    win.dialogs().alert(err.message || String(err), {
        title:   "Something went wrong",
        icon:    "paper/icons/status/dialog-error",
        details: err.stack     // shown in a collapsible fixed-font block
    });
}
```

### 4. Global logout confirmation via `wm.dialogs()`

```js
wm.dialogs().confirm("Log out from all sessions?", {
    title:       "Sign out",
    destructive: true,
    yesLabel:    "Sign out"
}).then(function (r) {
    if (r.result) location.assign("/logout");
});
```

### 5. Rich content — release notes dialog

```js
win.dialogs().alert({
    html:
        '<h2>Version 1.5.0</h2>' +
        '<h3>New</h3>' +
        '<ul>' +
            '<li>Window dialogs — <code>win.dialogs()</code></li>' +
            '<li>Large-controls toggle in the taskbar</li>' +
        '</ul>' +
        '<h3>Fixed</h3>' +
        '<ul>' +
            '<li>Phantom scrollbar on small dialogs</li>' +
            '<li>Context-menu positioning on scrolled pages</li>' +
        '</ul>' +
        '<hr>' +
        '<p><a href="/changelog">Full changelog →</a></p>'
}, { title: "What's new" });
```

## Return-value details

Every method resolves with `{ window, result }`. The two fields exist for slightly different reasons:

- `window` — the closed dialog's `WindowApplication`. Rarely needed at the call site; useful if a wrapper needs to inspect what was rendered, or if a subclass wants to reach into the dialog's `container()` post-close for analytics.
- `result` — the answer:
  - `alert` → always `undefined`
  - `confirm` → `true` (Yes / Enter) or `false` (No / Escape / dialog closed by cascade)
  - `prompt` → the input value on submit, or `null` on Cancel / Escape / cascade close

The promise **never rejects** — cascade closures resolve with the escape-key value so downstream `.then` chains stay simple.

## Electron parity

The parameter surface intentionally mirrors `electron.dialog.showMessageBox(browserWindow, opts)`:

| SGApps | Electron |
|---|---|
| `win.dialogs().alert(msg, {title, icon, details})` | `dialog.showMessageBox(browserWindow, {type: 'info', message, detail, title})` |
| `win.dialogs().confirm(msg, {yesLabel, noLabel, destructive})` | `dialog.showMessageBox(browserWindow, {type: 'question', buttons, defaultId, cancelId})` |
| `win.dialogs().prompt(msg, dflt, {placeholder, multiline})` | Not built-in in Electron; typically implemented as a small custom BrowserWindow |

An Electron-runtime adapter can wrap `require('electron').dialog.*` and expose the same `win.dialogs()` factory — call sites don't change.

## Related

- [Window Manager](window-manager.md) — how to obtain a `wm` and open windows
- [Window](window.md) — the `win` object each dialog is a child of
- [Building Custom Apps](building-custom-apps.md) — write your own app that uses dialogs internally
- [Embedding Apps](embedding.md) — single-app iframe embed (dialogs work inside that too, using the embedded window's `.dialogs()`)