Let the CLI Resolve Presets on Installs That Ship Preset Caches Only

Release builds install each vendor as its preset cache alone. The
read-only preset load the CLI uses to resolve an inheriting user preset
passed allow_cache = false to keep caches from being written, which
also stopped them from being read, so every vendor fell back to JSONs
that are not installed and the CLI failed.

The flag now only gates writing: a read-only load reads caches and
writes none. The filament library is also read from its cache whenever
that is all that is installed, so a vendor updated over the air still
resolves against it.

.claude/skills/orca-wxwidgets/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: orca-wxwidgets
+description: Use when writing, modifying, reviewing or debugging any OrcaSlicer GUI code under src/slic3r/GUI, or when deciding how a wxWidgets API behaves in OrcaSlicer — dialogs, frames, panels, the sidebar, Preferences, device/monitor pages, custom widgets, popups and menus, sizers and layout, painting, DPI scaling, dark mode, colours, icons, fonts, translated strings, settings fields, keyboard shortcuts, mouse capture and focus, events, CallAfter, threads and timers, WebView, the OpenGL canvas, AUI docking, clipboard, drag and drop, file dialogs — and for platform-specific UI bugs on Windows, macOS or Linux GTK/X11/Wayland such as popups that close at once, a frozen or unclickable UI, collapsed or clipped dialogs, invisible dark-mode icons, or crashes on close, even when the task never mentions wxWidgets.
+---
+
+# OrcaSlicer wxWidgets GUI
+
+This skill is how OrcaSlicer's wxWidgets GUI is written, changed, fixed and reviewed. Its core is
+**wxWidgets 3.3.2 API usage** — the documented contracts, the per-platform behaviour and the known
+limitations of the wx version Orca pins — layered with the OrcaSlicer conventions, wrappers, custom
+widget library and stable component designs a contributor must follow. Every reference file opens
+with a numbered **Rules** checklist (what a diff is checked against), followed by sections that give
+the wx contract, the correct code shape, platform differences, the Orca layer, and pitfalls as
+wrong → right pairs with the commit that fixed each one.
+
+## Ground truth: the wx tree in deps/
+
+Orca pins **wxWidgets 3.3.2** from the fork `github.com/SoftFever/Orca-deps-wxWidgets` (tag `v3.3.2`,
+`deps/wxWidgets/wxWidgets.cmake`), built static (Flatpak: shared). Facts about this build that change
+how you read the wx docs:
+
+- **Linux builds against GTK3** (`DEP_WX_GTK3` defaults ON in `deps/CMakeLists.txt`). Target GTK3 on
+  both X11 and Wayland; GTK-guarded code must still compile on GTK2, an opt-out build Orca does not ship.
+- **wx asserts never fire.** wx is built with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with
+  `wxDEBUG_LEVEL=0`. Wherever the docs say a call "asserts", Orca silently ignores it, returns early or
+  corrupts state. Check preconditions yourself; do not expect a debug build to catch misuse.
+- **No SVG in wx** (`wxUSE_NANOSVG=OFF`): `wxBitmapBundle::FromSVG*` does not exist. Orca rasterises
+  its SVG icons itself (`BitmapCache`, `create_scaled_bitmap`, `ScalableBitmap`).
+
+Look things up in the source the app is built from — it beats memory, and 3.3 changed real behaviour:
+
+```bash
+WX=$(find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets' | head -1)
+# macOS: deps/build/<arch>/dep_wxWidgets-prefix/src/dep_wxWidgets   Linux: deps/build/dep_wxWidgets-prefix/...
+# If deps are not built: git clone --depth 1 -b v3.3.2 https://github.com/SoftFever/Orca-deps-wxWidgets
+grep -n "CaptureMouse" -A 30 $WX/interface/wx/window.h      # documented contract (doxygen source)
+grep -rn "@onlyfor\|not implemented" $WX/interface/wx/popupwin.h   # documented platform limits
+ls $WX/docs/doxygen/overviews/                               # eventhandling.h, sizer.h, high_dpi.md, windowdeletion.h, ...
+grep -n "IsDark" $WX/docs/changes.txt                         # what changed in 3.3 (changes_32.txt for 3.2)
+grep -n "NotifyCaptureLost" -r $WX/src/osx $WX/src/gtk $WX/src/msw   # what each port actually does
+```
+
+`interface/wx/<class>.h` is the documentation; `src/common` holds shared behaviour and
+`src/{msw,osx,gtk,unix,generic}` the per-port implementation. When the docs and the source disagree,
+the source is what runs — the references mark such facts **[source]**. Orca-side design docs live in
+`docs/HLSD/` (`keyboard-shortcuts.md`, `deferred-page-construction.md`, `design-tab.md`,
+`printer-agent.md`).
+
+## Golden rules
+
+1. **Interactive controls are Orca widgets** (`Button` + `SetStyle(...)`, `::CheckBox`, `::ComboBox`,
+   `::TextInput`, `SpinInput`, `SwitchButton`, `RadioGroup`, `TabCtrl`); the bottom row of every dialog is
+   `DialogButtons`. Never `wxButton`, `wxSpinCtrl`, `wxCheckBox`, `wxChoice` or a single-line `wxTextCtrl`
+   in new code; multi-line text is a raw `wxTextCtrl`. Inside `Slic3r::GUI` write `::CheckBox` etc. —
+   `Field.hpp` has classes with the same names. → `orca-widgets.md`
+2. **DPI.** Layout pixel values go through `FromDIP(n)` (or `n * em_unit()`); `wxBitmap` constructor
+   sizes, image-list sizes and GL viewports are physical and are not `FromDIP`'d (icon heights passed to
+   `create_scaled_bitmap`/`ScalableBitmap`/`Button` are DIP). Top-level windows are `DPIDialog`/
+   `DPIFrame`; `on_dpi_changed` re-rasterises bitmaps (and re-sets them on the controls showing them),
+   calls each widget's `Rescale()`, re-applies stored sizes and finishes with
+   `GetSizer()->SetSizeHints(this)`; it never runs on macOS. → `dpi-bitmaps-fonts.md`, `sizers-layout.md`
+3. **Dark mode.** Ask `wxGetApp().dark_mode()`, never `wxSystemSettings::GetAppearance().IsDark()`. Use
+   palette colours through `StateColor` (specific states first, `Normal` last) and pass a literal light
+   colour through `StateColor::darkModeColorFor()`; give every panel you create an explicit palette
+   background before creating widgets in it; end each dialog constructor with
+   `wxGetApp().UpdateDlgDarkUI(this)`; re-apply hand-picked colours and name-selected icons in
+   `on_sys_color_changed()` (a cached or long-lived window must also be reached from
+   `MainFrame::on_sys_color_changed`). → `colours-dark-mode.md`
+4. **Strings.** Mark user text with `_L` / `_u8L` / `L` (and the `_CONTEXT` / `_L_PLURAL` forms) — never
+   `_()`, which xgettext does not extract. Build messages with `format_wxstr(_L("… %1% …"), arg)`;
+   convert with `from_u8()` / `into_u8()` (`from_path()` / `into_path()` for paths), never `ToStdString()`
+   or an implicit `std::string` → `wxString`. → `strings-i18n-files.md`
+5. **Messages to the user** use the `MsgDialog` family (`MessageDialog`, `RichMessageDialog`,
+   `WarningDialog`, `ErrorDialog`, `InfoDialog`, `show_error`/`show_info`), never `wxMessageBox` once the
+   GUI exists. ESC and the close box return `wxID_CANCEL`, so test for the positive answer
+   (`== wxID_YES`); `show_error` is asynchronous. → `windows-dialogs.md`
+6. **Events.** `Bind()` with handlers taking the event **by reference**; no new static event tables.
+   `Skip()` every non-command event you do not fully replace (focus, size, key, DPI, colour change, mouse
+   on custom widgets), and any event — command events included, e.g. `::CheckBox`'s
+   `wxEVT_TOGGLEBUTTON` — bound on an Orca widget, wx control or window whose own class also handles it:
+   your later-bound handler runs first. Unbind lambdas bound on other objects. → `events.md`
+7. **Threads.** Only the main thread touches wx. Workers marshal with `wxGetApp().CallAfter([by-value
+   captures]{ … })` and the lambda re-checks liveness (a `std::shared_ptr<std::atomic<bool>>` alive flag,
+   `is_closing()`) before touching anything — `wxWeakRef` is main-thread only, never created, copied or
+   tested on a worker; never `wxPostEvent` from a worker. UI-initiated background work is a `Job` on a
+   `Worker`. → `threads-timers-app.md`, `events.md`
+8. **Lifetime.** Heap windows die by `Destroy()`, not `delete`; modal dialogs end with
+   `EndModal(wxID_*)` (an id, never a `wxOK`/`wxCANCEL` style bit); ESC and the close box never run an
+   Orca Cancel button's handler, so cancel cleanup goes where every path ends. No window work on the stack
+   of a mouse handler or a WebView script-message callback — `CallAfter` it. → `windows-dialogs.md`
+9. **Layout.** `SetSizerAndFit(sizer)` on top-level windows (AGENTS.md rule), plain `SetSizer` on child
+   panels; proportion is the second `Add` argument; a scrolled window needs `SetScrollRate` and
+   `FitInside()` after content changes; re-wrap a label with `Wrap(-1); Wrap(w);` or use `Label`. Never
+   commit a size or wrap from a width not laid out yet: a `wxDefaultSize` child is 20×20 on every port
+   until the first sizer layout. → `sizers-layout.md`
+10. **Mouse capture.** `if (!HasCapture()) CaptureMouse();` / `if (HasCapture()) ReleaseMouse();` at every
+    site; `wxEVT_MOUSE_CAPTURE_LOST` *cancels* the gesture (never commits); release before a modal, hide or
+    destroy. macOS never sends capture-lost, and a leaked capture there leaves the app alive but
+    unclickable (keyboard still works). → `mouse-keyboard-focus.md`
+11. **Popups.** Derive from Orca's `PopupWindow` and pass `wxPU_CONTAINS_CONTROLS` when it hosts
+    controls; size it before `Position()`; on macOS anchor a hover-driven popup flush to its opener; on
+    MSW call `BindUnfocusEvent()` when it must close with the frame; use a frameless
+    `wxDialog` for content that needs typing focus or hosts a WebView. → `popups-menus.md`
+12. **Painting.** Draw only in the `wxEVT_PAINT` handler, change state then `Refresh()`; never draw
+    through `wxClientDC` (no effect on macOS and Wayland). → `painting-custom-widgets.md`
+13. **Cross-platform.** Every change works on Windows, macOS and Linux GTK3 under X11 and Wayland. No
+    global pointer coordinates (`wxGetMousePosition()`) in logic that must work on Wayland; decide
+    X11/Wayland at runtime with `is_running_on_wayland()`. → `platforms.md`
+14. **Registration.** New sources go into `SLIC3R_GUI_SOURCES` in `src/slic3r/CMakeLists.txt` (platform-only
+    files into the `if (WIN32)` / `if (APPLE)` blocks, CAD UI into `if (SLIC3R_CAD)`, `GUI/DeviceCore` /
+    `GUI/DeviceTab` files into their own `CMakeLists.txt`), and a new file with translatable strings into
+    `localization/i18n/list.txt`. → `orca-architecture.md`, `strings-i18n-files.md`
+
+## The standard dialog
+
+Exemplars: `src/slic3r/GUI/CloneDialog.cpp` (minimal), `FilamentPickerDialog.cpp` (larger, `Create*()`
+helpers), `PurgeModeDialog.cpp` (custom-painted clickable cards). Full conventions, `DialogButtons` id
+semantics and the `MsgDialog` API are in `windows-dialogs.md` §8–§9.
+
+```cpp
+class MyDialog : public DPIDialog
+{
+public:
+    explicit MyDialog(wxWindow* parent)
+        : DPIDialog(parent ? parent : static_cast<wxWindow*>(wxGetApp().mainframe), wxID_ANY,
+                    _L("My Dialog"), wxDefaultPosition, wxDefaultSize,
+                    wxCAPTION | wxCLOSE_BOX)            // always pass a style: DPIAware's default is wxDEFAULT_FRAME_STYLE
+    {
+        SetBackgroundColour(*wxWHITE);                  // light palette colour, dark-mapped by UpdateDlgDarkUI
+        SetFont(Label::Body_14);
+
+        auto* sizer = new wxBoxSizer(wxVERTICAL);
+        // ... Orca widgets, sizes via FromDIP(n), text via _L() ...
+        sizer->Add(content_sizer, 1, wxEXPAND | wxALL, FromDIP(10));
+
+        auto* btns = new DialogButtons(this, {"OK", "Cancel"});   // untranslated: DialogButtons calls _L() and assigns wxID_OK/wxID_CANCEL
+        btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { /* apply */ EndModal(wxID_OK); });
+        btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { EndModal(wxID_CANCEL); });
+        sizer->Add(btns, 0, wxEXPAND);
+        // cancel cleanup that must also run on ESC / close box: after ShowModal() returns, or in wxEVT_CLOSE_WINDOW
+
+        SetSizerAndFit(sizer);
+        CenterOnParent();                               // after fitting: DPIAware centred the empty window
+        wxGetApp().UpdateDlgDarkUI(this);               // last, after every child exists
+    }
+
+protected:
+    void on_dpi_changed(const wxRect&) override
+    {
+        // msw_rescale() ScalableBitmaps and re-SetBitmap() them, Rescale() Orca widgets, re-apply FromDIP/em
+        // sizes (no msw_buttons_rescale(): it would override the DialogButtons' style height), then:
+        GetSizer()->SetSizeHints(this);
+        Refresh();
+    }
+};
+
+MyDialog dlg(this);                                     // modal on the caller's stack
+if (dlg.ShowModal() == wxID_OK) { /* read results */ }
+```
+
+## Orca widgets at a glance
+
+| Orca widget (`src/slic3r/GUI/Widgets/`) | Instead of | Must know |
+|---|---|---|
+| `Button` | `wxButton` | ctor `(parent, text, icon_name, style, iconSize, id)` — id is last; style with `SetStyle(ButtonStyle::…, ButtonType::…)`; emits `wxEVT_BUTTON`; not a `wxButton` (no dialog default/escape emulation) |
+| `::CheckBox` | `wxCheckBox` | no label parameter — pair with a `wxStaticText`/`Label`; emits `wxEVT_TOGGLEBUTTON` (never `wxEVT_CHECKBOX`), and a handler bound on it must `Skip()` or the bitmap is not refreshed |
+| `::ComboBox` (+ `DropDown`) | `wxComboBox`/`wxChoice` | `wxCB_READONLY` for choices; `SelectAndNotify(n)` fires the event; ignores the ctor id; `void*` client data only |
+| `::TextInput` | single-line `wxTextCtrl` | text via `GetTextCtrl()`; bind `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the widget, never on a parent |
+| `SpinInput` | `wxSpinCtrl` | non-negative integers only (`-` cannot be typed); commits on Enter, kill-focus and arrow steps with `wxEVT_SPINCTRL`, a plain `wxCommandEvent` — bind a `wxCommandEvent&` handler and read `GetValue()` |
+| `DialogButtons` | `wxStdDialogButtonSizer` | untranslated labels (custom ones written `L("…")`); OK/Cancel close by id, Yes/No/Apply/Confirm do not |
+| `Label` | `wxStaticText` | `LB_AUTO_WRAP`, `LB_HYPERLINK` (only through `SetWindowStyleFlag`); also hosts the font table `Label::Head_*`/`Label::Body_*` |
+| `SwitchButton`, `RadioGroup`, `TabCtrl`, `LabeledStaticBox`, `StaticLine`, `ProgressBar`, `PopupWindow` | toggle, `wxRadioBox`, notebook bar, `wxStaticBox`, `wxStaticLine`, `wxGauge`, `wxPopupTransientWindow` | quirks per widget in `orca-widgets.md` |
+
+Disabling a parent does not repaint Orca widgets as disabled — enable/disable them individually (`::CheckBox`, a native
+button, is the exception: it greys with its parent).
+Containers stay raw (`wxPanel`, `wxBoxSizer`, `wxScrolledWindow`, `wxSimplebook`).
+
+## Where to read next
+
+| You are … / the symptom is … | Read |
+|---|---|
+| creating or closing a dialog or frame, `Destroy`/`delete`, modal results, liveness of a window pointer, message boxes | `references/windows-dialogs.md` |
+| binding or emitting events, `Skip()`, propagation, custom events, `CallAfter`, `UPDATE_UI`, idle | `references/events.md` |
+| worker-thread callbacks, background jobs, timers, `wxYield`/nested loops, progress dialogs, startup/shutdown | `references/threads-timers-app.md` |
+| a sizer, a dialog that is collapsed, too big or clipped, a scrolled list, label wrapping, relayout after DPI change | `references/sizers-layout.md` |
+| a custom-drawn control or a new widget in `Widgets/`, flicker, paint/erase, `wxGCDC`, best size | `references/painting-custom-widgets.md` |
+| `FromDIP`/`em_unit`, rescale on DPI change, icons and bitmaps, image lists, fonts | `references/dpi-bitmaps-fonts.md` |
+| colours, dark mode, theme toggle, `StateColor`, icons invisible in dark mode | `references/colours-dark-mode.md` |
+| drag gestures and mouse capture, a frozen/unclickable UI on macOS, hover, wheel, keyboard shortcuts, focus, tooltips, cursors | `references/mouse-keyboard-focus.md` |
+| popups and dropdowns (closing at once, not closing), context menus, the menu bar, `MenuFactory` | `references/popups-menus.md` |
+| text/combo/check/radio/spin controls, book controls, `wxGrid`, `wxDataViewCtrl`, the object list | `references/controls-dataview.md` |
+| WebView pages and dialogs, JS ↔ C++ messages, the GL canvas, ImGui overlays, docking panes, the top bar, camera view | `references/webview-gl-aui-media.md` |
+| translations, string conversion and formatting, file/dir dialogs, clipboard, drag and drop, logging, `AppConfig` | `references/strings-i18n-files.md` |
+| where new code goes, `GUI_App`/`MainFrame`/`Plater` structure, lazy pages, Preferences, notifications | `references/orca-architecture.md` |
+| which Orca widget to use and its quirks | `references/orca-widgets.md` |
+| adding or changing a print/filament/printer setting, a settings field, per-object overrides | `references/orca-settings-ui.md` |
+| platform `#ifdef`s, wx build options, Wayland gaps, title bars, a bug on one platform only | `references/platforms.md` |
+| old code, a wx call that behaves differently than you remember, wx-version migration | `references/wx-33-changes.md` |
+
+**Reviewing a GUI diff:** for each area the diff touches, check it against that file's `## Rules`
+list. **Debugging a UI bug:** find the symptom in the table above; most recurring Orca UI bugs are a
+known class with a pitfall entry and a fixing commit.
+
+## Platform gotchas worth memorising
+
+- **macOS:** capture-lost is never sent (a leaked capture freezes all clicks); transient popups hover-
+  dismiss across a gap — anchor flush and re-verify the cursor; native modals (file/dir dialogs, native
+  message boxes) and generic progress dialogs re-activate the main window, so re-raise a secondary window
+  afterwards with a deferred, liveness-guarded `Raise()`; a live menu accelerator consumes the key before
+  any wx key event; Control+click arrives as a right-click.
+- **Windows:** `IsDark()` and `wxSYS_COLOUR_*` follow the system app mode, not Orca's theme — use
+  `dark_mode()`; menu bitmaps follow `check_dark_mode()`; windows are not double-buffered by default in
+  3.3.2; `ProcessLeftDown` is never called for popups; a popup that must close with the frame calls
+  `BindUnfocusEvent()`.
+- **Linux GTK3:** dialogs without size hints collapse (only sizer-fitting calls, not `Fit()`, are
+  replayed at the first `Show()`); command events from a popup's children are not stopped at the popup
+  (MSW/macOS stop them); chained popups need `transient_for` set to the mapped parent right before
+  showing; native borders leak through custom widgets (`RemoveButtonBorder`/`RemoveInputBorder`).
+- **Wayland:** no global pointer position, no window positioning, `wxClientDC`, `Update()` and `SetIcon`
+  do nothing, no floating AUI panes, GL is EGL only.
+
+## Editing this skill
+
+The skill describes how the pinned wxWidgets behaves and how Orca GUI code must be written, not what
+the GUI tree currently contains. State rules, contracts, mechanisms, stable component designs and code
+shapes; never usage counts, census lists, lists of today's offenders or dated measurements. Test each
+sentence: if a change to Orca code the sentence does not name, with the wx pin unchanged, could make it
+false, state the rule behind it or give a generic example instead, and cut it if there is no rule
+behind it. Example files named as models to copy, and commit hashes cited as the reason for a rule,
+are fine.
+
+Keep the skill in step with what it describes. A change that alters a contract the skill states (an
+Orca widget's API or quirk, a shared helper such as `DPIAware` or `UpdateDlgDarkUI`, the Shortcuts
+registry) updates the skill in the same change. Moving the wx pin (`GIT_TAG` in
+`deps/wxWidgets/wxWidgets.cmake`) means re-verifying every wx citation and **[source]** fact against
+the new tree, and adding that version's behaviour changes the way `wx-33-changes.md` records 3.3's.
+
+Cite wx by path relative to the wx tree root with line (`interface/wx/window.h:3805`), which stays
+valid because the version is pinned. Cite Orca by file and symbol, never by line, and commits as the
+rationale for a rule. Mark behaviour the wx docs don't state, or contradict, as **[source]**. Each
+concept lives in one reference file and the others point to it. Verify every new claim in the wx tree
+or the Orca code before adding it, and never drop a fact, qualifier or example to save words.
+`evals/evals.json` holds the regression tasks (planted-defect review patches in `evals/files/`); rerun
+them with and without the skill after substantial edits.

.claude/skills/orca-wxwidgets/evals/evals.json

@@ -0,0 +1,204 @@
+{
+  "skill_name": "orca-wxwidgets",
+  "evals": [
+    {
+      "id": 1,
+      "name": "report-issue-dialog",
+      "prompt": "In the OrcaSlicer repo, add a new dialog that opens from the Help menu called 'Report Issue'. It needs a dropdown to pick the issue type (Bug / Feature request / Question), a multiline text box for the description, a checkbox 'Include system info', and OK/Cancel buttons at the bottom. It has to look correct in dark mode and on high-DPI screens.",
+      "files": [],
+      "assertions": [
+        "The dialog class derives from DPIDialog and overrides on_dpi_changed(const wxRect&) with a body that rescales its custom widgets (Rescale()/msw_rescale) and re-lays out (Layout/Fit/Refresh or equivalent)",
+        "The dropdown is Orca's custom ComboBox (::ComboBox from Widgets/ComboBox.hpp), not wxComboBox/wxChoice",
+        "The checkbox is Orca's custom ::CheckBox (constructed without a label) paired with a separate wxStaticText/Label for the text",
+        "The bottom row is DialogButtons constructed with untranslated labels such as {\"OK\", \"Cancel\"} (not _L(\"OK\")), and handlers end the dialog with EndModal(wxID_OK/wxID_CANCEL), not Destroy()",
+        "The multiline description is a raw wxTextCtrl created with wxTE_MULTILINE, not TextInput (TextInput::DoSetSize keeps the inner control at its single-line height), explicitly made dark-safe (UpdateDarkUI/UpdateDlgDarkUI or StateColor::darkModeColorFor colours), and its text is read via GetValue()",
+        "Every hard-coded pixel size/padding goes through FromDIP(n) (or em_unit multiples); no raw pixel literals in sizes/borders",
+        "All user-visible strings are wrapped in _L(...)",
+        "The top-level sizer is installed with SetSizerAndFit (or SetSizer followed by SetSizeHints)",
+        "wxGetApp().UpdateDlgDarkUI(this) is called as the last step of the constructor, after all children exist",
+        "The new .cpp/.hpp are added to SLIC3R_GUI_SOURCES in src/slic3r/CMakeLists.txt",
+        "A Help-menu item is added in MainFrame's menu construction (append_menu_item or equivalent) that opens the dialog with ShowModal()"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "new-print-setting",
+      "prompt": "Add a new print setting to OrcaSlicer: 'seam_transition_gap', a float in mm, default 0.1, range 0-2, shown on the Quality page in the Seam group with a proper tooltip. It should be saved with process presets and searchable.",
+      "files": [],
+      "assertions": [
+        "A ConfigOptionDef is added in PrintConfig.cpp via this->add(\"seam_transition_gap\", coFloat) with label, tooltip, sidetext \"mm\", min 0, max 2, a mode, and default ConfigOptionFloat(0.1)",
+        "label/tooltip/sidetext in PrintConfig.cpp use the L(\"...\") extraction marker, not _L/_u8L",
+        "A ((ConfigOptionFloat, seam_transition_gap)) entry is added to the matching PRINT_CONFIG_CLASS_DEFINE block in PrintConfig.hpp",
+        "The key is appended to s_Preset_print_options in Preset.cpp",
+        "TabPrint::build() gets optgroup->append_single_option_line(\"seam_transition_gap\", ...) inside the Quality page's Seam option group",
+        "The answer states that search indexing comes automatically from get_option/append_single_option_line (no manual search registration)",
+        "Slicing invalidation is handled: the key is added to PrintObject::invalidate_state_by_config_options (or Print::invalidate_state_by_config_options) under an appropriate step"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "macos-hover-popup-dismiss",
+      "prompt": "OrcaSlicer bug in a feature branch: the sidebar's filament-sync button now opens a small hover menu (code below). On macOS the menu appears and then disappears before the user can click either item — moving the mouse from the button down into the menu closes it, and sometimes it closes while the cursor is already over it. It works on Windows. Find the causes and fix the code.\n\n```cpp\n// Widgets/FilamentSyncMenu.hpp/.cpp (new, opened when the cursor enters the sidebar's sync button)\nclass FilamentSyncMenu : public PopupWindow\n{\npublic:\n    explicit FilamentSyncMenu(wxWindow* parent) : PopupWindow(parent, wxBORDER_NONE)\n    {\n        auto* sizer = new wxBoxSizer(wxVERTICAL);\n        auto* colours = new Button(this, _L(\"Sync colours only\"));\n        auto* all     = new Button(this, _L(\"Sync colours and types\"));\n        colours->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Dismiss(); wxGetApp().sidebar().sync_ams_list(); });\n        all->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Dismiss(); wxGetApp().sidebar().sync_ams_list(true); });\n        sizer->Add(colours, 0, wxEXPAND | wxALL, FromDIP(4));\n        sizer->Add(all, 0, wxEXPAND | wxALL, FromDIP(4));\n        SetSizerAndFit(sizer);\n\n        m_timer.SetOwner(this);\n        Bind(wxEVT_TIMER, [this](wxTimerEvent&) { Dismiss(); });\n        Bind(wxEVT_LEAVE_WINDOW, [this](wxMouseEvent&) { m_timer.StartOnce(300); });\n        Bind(wxEVT_ENTER_WINDOW, [this](wxMouseEvent&) { m_timer.Stop(); });\n    }\n\n    void popup_under(wxWindow* btn)\n    {\n        wxPoint pos = btn->ClientToScreen(wxPoint(0, 0));\n        Position(pos, {0, btn->GetSize().y + FromDIP(6)});\n        Popup();\n    }\n\nprivate:\n    wxTimer m_timer;\n};\n\n// Sidebar constructor:\nm_sync_menu = new FilamentSyncMenu(ams_btn);\nams_btn->Bind(wxEVT_ENTER_WINDOW, [this](wxMouseEvent& e) { m_sync_menu->popup_under(ams_btn); e.Skip(); });\n```",
+      "files": [],
+      "assertions": [
+        "Identifies the opener-to-popup gap as a cause: the FromDIP(6) offset leaves a dead zone, and crossing it from the button into the menu ends the hover (LEAVE / hover-timer path) and dismisses the menu on macOS",
+        "Identifies that on macOS ENTER/LEAVE events around a wxPopupTransientWindow arrive spuriously or out of order (capture handling), so the hover timer must not trust them: re-verify the real cursor position with GetClientRect().Contains(ScreenToClient(wxGetMousePosition())) (or equivalent geometry) before starting/stopping the timer or dismissing",
+        "Fix anchors the menu flush with (or slightly overlapping) the button instead of leaving a gap, at least on macOS",
+        "Adds wxPU_CONTAINS_CONTROLS to the PopupWindow style because the menu hosts interactive Button children",
+        "Guards against calling Popup() again while the menu is already shown (re-entering the button) and/or debounces reopening right after a dismissal",
+        "The fix is gated to macOS where needed (#ifdef __WXOSX__/__APPLE__) or argued harmless elsewhere, and does not rely on unexplained SetFocus/CallAfter/Raise hacks"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "dark-mode-icons",
+      "prompt": "Users report that a couple of the AMS status icons in OrcaSlicer are nearly invisible when dark mode is on, but fine in light mode. What's going on and how do we fix it properly?",
+      "files": [],
+      "assertions": [
+        "Explains that BitmapCache::load_svg recolors dark-mode icons by literal substitution of a fixed palette (e.g. #262E30 -> #EFEFF0) and off-palette colors pass through unchanged",
+        "Offers the asset fix: re-author the SVG fills in palette colors (e.g. near-black line art as #262E30)",
+        "Offers the variant fix: a *_dark asset selected by name from wxGetApp().dark_mode()",
+        "States that name-selected variants must be re-picked/reloaded on a runtime theme switch (on_sys_color_changed / sys_color_changed / msw_rescale path)",
+        "Investigates the actual AMS icon code/assets (e.g. checks both branches of a dark_mode() ternary for a copy-paste _light/_light bug, or inspects the SVG fills)"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "custom-painted-drag-widget",
+      "prompt": "In OrcaSlicer, add a small owner-drawn widget for the filament area of the sidebar: a horizontal strip of colour swatches (one per filament) where the user can click-and-drag across swatches to select a contiguous range. Hovered swatches should highlight, it must emit an event with the selected range when the drag ends, and it must look right with high-DPI and dark mode. Write the widget.",
+      "files": [],
+      "assertions": [
+        "Paints only inside a wxEVT_PAINT handler using wxAutoBufferedPaintDC/wxBufferedPaintDC/wxPaintDC with SetBackgroundStyle(wxBG_STYLE_PAINT); never draws through wxClientDC; triggers repaint with Refresh()/RefreshRect()",
+        "CaptureMouse() on press is guarded (if (!HasCapture())) and ReleaseMouse() is guarded (if (HasCapture()))",
+        "Handles wxEVT_MOUSE_CAPTURE_LOST by ending the gesture: drag state reset and repaint, no recapture (cancelling rather than committing the selection is what the wx contract asks for)",
+        "Ensures capture cannot leak: release on every end-of-drag path regardless of drag flags (and/or in the destructor), mentioning the macOS consequence (UI unclickable) or the wx contract",
+        "Sizes use FromDIP (or em_unit) and the widget reports a size via DoGetBestSize/DoGetBestClientSize or SetMinSize, rescaled on DPI change (Rescale/msw_rescale/wxEVT_DPI_CHANGED)",
+        "Colours go through StateColor / StateColor::darkModeColorFor or are re-derived from wxGetApp().dark_mode() and re-applied on theme change (sys_color_changed/on_sys_color_changed)",
+        "Defines a custom event with wxDECLARE_EVENT/wxDEFINE_EVENT (e.g. a wxCommandEvent carrying the range) and uses Bind(), not a new static event table",
+        "Hover handling uses event-relative coordinates (evt.GetPosition()), not wxGetMousePosition(), and only refreshes when the hovered index actually changes"
+      ]
+    },
+    {
+      "id": 6,
+      "name": "worker-thread-progress",
+      "prompt": "In OrcaSlicer, we're adding a non-modal 'Firmware download' dialog. A network library calls our progress callback (int percent, std::string status) on its own worker thread, and a completion callback (bool ok, std::string error) at the end. The dialog shows a progress bar and status text and has a Cancel button; the user may also close the dialog at any time while the download continues. Implement the dialog and the callback wiring.",
+      "files": [],
+      "assertions": [
+        "No wx/GUI calls are made on the worker thread; callbacks marshal to the main thread via CallAfter (wxGetApp().CallAfter / window CallAfter) or wxQueueEvent",
+        "Deferred lambdas capture data by value (copies of percent/status strings), not references to worker-owned data",
+        "Deferred work re-checks the dialog's liveness inside the lambda (shared_ptr<atomic<bool>> alive flag, wxWeakRef, or registry lookup) because the dialog can be closed before the callback runs",
+        "If events are used across threads, they are heap-allocated/owned (wxQueueEvent with new/Clone, or wxThreadEvent) — not wxPostEvent/AddPendingEvent with wxString payload from the worker",
+        "Closing the dialog cancels or detaches the download callbacks and the non-modal dialog is destroyed with Destroy() (not delete), with any wxTimer stopped first",
+        "Uses Orca UI conventions: DPIDialog base, Orca ProgressBar or custom widgets, DialogButtons/Button for Cancel, _L strings, FromDIP sizes, UpdateDlgDarkUI",
+        "Strings crossing to the GUI are converted with from_u8() (UTF-8 std::string -> wxString), not implicit/ToStdString conversions"
+      ]
+    },
+    {
+      "id": 7,
+      "name": "scrolled-dynamic-layout",
+      "prompt": "OrcaSlicer bug on Linux: in a settings dialog, a wxScrolledWindow holds a list of rows that the user can add with a '+' button. After adding rows, the scrollbar doesn't appear/update and new rows are cut off; when the dialog first opens on GTK it's sometimes collapsed to a tiny size; and some German labels in the rows are clipped. Explain the causes and give the correct wx code patterns to fix all three.",
+      "files": [],
+      "assertions": [
+        "For the scroll issue: after adding rows, call FitInside() on the scrolled window (or SetVirtualSize/Layout so the virtual size updates), with SetScrollRate set so scrollbars are enabled",
+        "Explains that changing children doesn't change the scrolled window's size, so automatic layout doesn't run — Layout() (and FitInside) must be called explicitly after adding content",
+        "For the collapsed dialog: uses SetSizerAndFit on the top-level dialog or SetSizer + sizer->SetSizeHints(dialog) so the min size is set (GTK needs the min-size hint), and avoids an unconditional Fit() in on_dpi_changed/refresh paths",
+        "For clipped labels: avoids fixed widths/heights on wxStaticText (use -1 / best size) and re-Wrap()s after SetLabel or uses Label with LB_AUTO_WRAP; mentions translations being longer",
+        "Mentions InvalidateBestSize()/Layout() of the containing hierarchy (or parent->Layout()) after dynamic content changes, and/or Freeze()/Thaw() around bulk row creation",
+        "Notes GTK specifics: Linux builds wx against GTK3 by default (deps/CMakeLists.txt DEP_WX_GTK3 ON) and/or the first GTK size pass can run with a bogus tiny client width, so wrap/height calculations need a guard"
+      ]
+    },
+    {
+      "id": 8,
+      "name": "keyboard-shortcut",
+      "prompt": "Add a global keyboard shortcut Ctrl+Shift+E (Cmd+Shift+E on macOS) to OrcaSlicer that exports the current plate's G-code (same as the existing export action). It must work on all three platforms and show up wherever OrcaSlicer documents shortcuts.",
+      "files": [],
+      "assertions": [
+        "Explains that wxACCEL_CTRL / 'Ctrl' in menu accelerator strings maps to Cmd on macOS (and WXK_RAW_CONTROL / wxACCEL_RAW_CTRL is the real Control key)",
+        "Registers the shortcut through Orca's shortcut registry (Shortcut enum + shortcut_table in src/slic3r/GUI/Shortcuts.cpp, Global context dispatched from MainFrame's wxEVT_CHAR_HOOK) and/or the menu item whose accelerator text is derived from it, dispatching to the existing export handler",
+        "Checks for conflicts with existing shortcuts (registry defaults, GLCanvas3D/ObjectList contexts, menu items) before choosing the binding",
+        "The shortcut appears in KBShortcutsDialog by virtue of the registry (or is explicitly added there), and the answer checks/handles a conflict with an existing default chord",
+        "Accounts for platform differences in Orca's menus: native wxMenuBar on macOS vs BBLTopbar/custom menus on Windows/Linux, so the shortcut works where no native menubar exists"
+      ]
+    },
+    {
+      "id": 9,
+      "name": "webview-dialog",
+      "prompt": "Add a dialog to OrcaSlicer that shows a local HTML page from resources/web/ in a WebView. The page has a 'Done' button that posts a JS message; when it arrives the dialog must close and return a result to the caller. It must work on Windows (Edge), macOS (WKWebView) and Linux (WebKitGTK).",
+      "files": [],
+      "assertions": [
+        "Creates the browser through Orca's WebView wrapper (WebView::CreateWebView in Widgets/WebView.hpp), not wxWebView::New directly",
+        "Receives messages via wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED using the 'wx' handler the wrapper registers (window.wx.postMessage / postMessage), without adding a duplicate script message handler (which throws an uncatchable NSException on WKWebView)",
+        "Closing/ending the dialog from the script-message handler is deferred with CallAfter (not done synchronously inside the WebView callback stack)",
+        "Builds the local page URL from Orca's resources dir (resources_dir()/from_u8 + file:// URL or wxFileName::FileNameToURL), handling paths portably",
+        "Accounts for asynchronous backend creation (Edge): no script runs/calls before the page is loaded (wxEVT_WEBVIEW_LOADED) or the wrapper's deferral",
+        "Dialog follows Orca conventions: DPIDialog base, on_dpi_changed, UpdateDlgDarkUI/dark-mode handling, EndModal with a result id"
+      ]
+    },
+    {
+      "id": 10,
+      "name": "macos-frozen-ui",
+      "prompt": "On macOS, sometimes after dragging the handle of the new ratio bar widget inside a dialog in OrcaSlicer, the whole app stops responding to mouse clicks — even the window's close button — but Cmd+S still saves, timers keep running and the 3D view still repaints. Windows is fine. What is going on, how do we confirm it, and how should widget code like this be written?",
+      "files": [],
+      "assertions": [
+        "Identifies a leaked wx mouse capture (CaptureMouse without matching ReleaseMouse) as the cause, explicitly not a deadlock/hang",
+        "Explains why only the mouse is dead: on macOS wx routes all mouse events to the capturing window while key events are unaffected",
+        "Explains why macOS differs: wxEVT_MOUSE_CAPTURE_LOST is not delivered on macOS (wxOSX never generates it; the docs' @onlyfor{wxmsw} is stale, wxGTK sends it too) so nothing ever unwinds the leaked capture",
+        "Fix: guard CaptureMouse with !HasCapture() and ReleaseMouse with HasCapture(), release on every exit path (mouse-up independent of drag flags, capture-lost handler, before the dialog closes/destructor)",
+        "Handles wxEVT_MOUSE_CAPTURE_LOST (required by the wx contract wherever it can fire) without recapturing",
+        "Gives a way to confirm/locate it (e.g. sampling the process / checking GetCapture(), or auditing every CaptureMouse call site)"
+      ]
+    },
+    {
+      "id": 11,
+      "name": "review-planted-wx-defects",
+      "prompt": "Review this proposed OrcaSlicer change before it is merged: the patch at .claude/skills/orca-wxwidgets/evals/files/filament-notes.patch adds a non-modal 'Filament notes' dialog (src/slic3r/GUI/FilamentNotesDialog.hpp/.cpp). It is not applied to the tree; read it from that path and use the repository for context. Report every correctness, cross-platform (Windows/macOS/Linux GTK, X11 and Wayland), threading, lifetime, DPI, dark-mode and wxWidgets API-misuse problem you find, each with its consequence and the fix. Do not report style nits.",
+      "files": [
+        "files/filament-notes.patch"
+      ],
+      "assertions": [
+        "D1: Flags FromDIP() called on the SwatchPreview object inside its own base-class initializer (before wxPanel is constructed) as invalid/UB, and fixes it (parent->FromDIP / static wxWindow::FromDIP(sz, parent) / SetMinSize after construction)",
+        "D2: Flags the mouse-capture handling: CaptureMouse unguarded, ReleaseMouse gated on m_dragging rather than HasCapture(), and no wxEVT_MOUSE_CAPTURE_LOST handler — with the consequence (leaked capture freezes mouse input on macOS; wx's capture asserts are compiled out in Orca, so elsewhere the misuse fails silently) and the guarded pattern",
+        "D3: Flags hit-testing with ScreenToClient(wxGetMousePosition()) in the motion handler (unreliable on Wayland, stale vs the event) and fixes with e.GetPosition()",
+        "D4: Flags drawing the hover outline through wxClientDC outside the paint handler (no effect on macOS or GTK3 Wayland; on MSW and X11 it races and is overwritten by the next paint) and fixes by storing m_hover and Refresh()/RefreshRect() + drawing in the paint handler",
+        "D5: Flags the hard-coded wxColour(\"#009688\") pen as not dark-mode aware (should go through StateColor::darkModeColorFor or a dark-mode branch, re-derived on theme change)",
+        "D6: Flags SetValue() inside the wxEVT_TEXT handler (SetValue emits wxEVT_TEXT again: recursion/re-entrancy and caret reset) and fixes with ChangeValue() (plus an insertion-point restore or guard)",
+        "D7: Flags the wxEVT_KILL_FOCUS handler that does not call e.Skip() (breaks native focus handling of the text control)",
+        "D8: Flags that the wxStaticBoxSizer's child wxTextCtrl is created with the dialog as parent instead of box->GetStaticBox()",
+        "D9: Flags the raw pixel size wxSize(400, 160) (needs FromDIP)",
+        "D10: Flags m_notes->GetValue().ToStdString() as lossy for non-ASCII text and fixes with into_u8()/ToUTF8()",
+        "D11: Flags `delete this` in the wxEVT_CLOSE_WINDOW handler and fixes with Destroy() (deferred deletion after pending events)",
+        "D12: Flags SetSizer()+Layout() on the top-level dialog without SetSizerAndFit/SetSizeHints/Fit (no initial size / min size; GTK collapse) per the project rule",
+        "D13: Flags m_status->SetLabel() called on the worker thread (GUI call off the main thread)",
+        "D14: Flags the worker's wxPostEvent(this, evt) with a wxString payload: posting a wxString-carrying event from a worker thread is unsafe (use wxQueueEvent with a heap event / CallAfter), and `this` may be destroyed because the destructor detaches the thread — needs an alive flag/join/cancellation",
+        "D15: Flags that wxEVT_MENU is bound on m_more_btn although PopupMenu() is called on the dialog (menu events go to the invoking window and propagate up, never to a child), and that Bind runs on every popup (accumulating handlers); fix: bind on the dialog once or use GetPopupMenuSelectionFromUser",
+        "D16: Flags the heap wxTimer that is never stopped or deleted (leak; a pending tick can fire into the destroyed dialog) and fixes with Stop()+delete in the destructor or a by-value member",
+        "D17: Flags that start_sync() move-assigns m_sync_thread while the previous std::thread is still joinable (never joined or detached; a finished thread stays joinable), so the second sync ('Reload from cloud', live once the D15 routing is fixed) calls std::terminate; fix: no reassigned thread member (a detached worker per request behind the D14 alive flag) or detach/join the previous thread before reassigning, and/or refuse a reload while a sync is in flight",
+        "D18: Flags that SwatchPreview never releases the capture if it is destroyed while holding it (no guarded ReleaseMouse() in its destructor or on the dialog's close path): e.g. Esc, which DPIDialog maps to Close(), pressed with the button held on the strip destroys the panel while it is still on wx's capture stack (the 'Destroying window before releasing mouse capture' assert, or in Orca's assert-free build a dangling capture that freezes or crashes mouse input, notably on macOS); fix: drop the capture, or if (HasCapture()) ReleaseMouse() in the destructor / before close",
+        "Does not report false defects about correct code (e.g. DialogButtons' untranslated labels, wxBG_STYLE_PAINT + wxAutoBufferedPaintDC, Bind with lambdas)"
+      ]
+    },
+    {
+      "id": 12,
+      "name": "review-subtle-wx-defects",
+      "prompt": "Review this proposed OrcaSlicer change before it is merged: the patch at .claude/skills/orca-wxwidgets/evals/files/preset-note.patch adds a sidebar 'note chip' widget and a modal 'Preset note' editor dialog (src/slic3r/GUI/PresetNoteDialog.hpp/.cpp). It is not applied to the tree; read it from that path and use the repository and the wxWidgets source for context. Report every correctness, cross-platform, i18n, DPI, dark-mode, lifetime and wxWidgets/Orca API-misuse problem you find, each with its consequence and the fix. Do not report style nits.",
+      "files": [
+        "files/preset-note.patch"
+      ],
+      "assertions": [
+        "P1: Flags the StateColor built with the Normal entry first: colorForStates returns the first matching entry and Normal (mask 0) matches every state, so the Hovered/Pressed colours never show; fix: list Pressed, Hovered, then Normal last",
+        "P2: Flags the wxEVT_SIZE lambda taking wxSizeEvent by value: Skip() on the copy does not reach the original, so the event counts as handled and default/base size handling stops; fix: take the event by reference",
+        "P3: Flags that the capture-lost handler routes through on_left_up and therefore fires EVT_NOTE_CHIP_CLICKED (commits a click) when capture is lost; per the wx contract capture loss must cancel the operation: reset m_pressed/visual state without emitting the event and without recapturing",
+        "P4: Flags _(\"Preset note\") as never extracted for translation (Orca's xgettext keywords are L/_L/_u8L/..., not _), fix: _L",
+        "P5: Flags wxBitmapBundle::FromSVGFile as unavailable in Orca's wx build (NanoSVG off / no wxHAS_SVG — does not compile) and replaces it with Orca's ScalableBitmap/create_scaled_bitmap/ScalableButton icon loading by name",
+        "P6: Flags Bind(wxEVT_TEXT_ENTER, ..., m_input->GetId()) on the dialog as never firing: TextInput re-dispatches TEXT_ENTER only to the wrapper (ProcessEventLocally, no propagation to parents) and the inner control's handler does not Skip; fix: bind on m_input (the wrapper) or on GetTextCtrl()",
+        "P7: Flags RichMessageDialog::SetYesNoLabels as having no effect in Orca (labels are stored but never applied to the buttons), fix: MsgDialog::SetButtonLabel(wxID_YES/wxID_NO, ...) or a dialog with custom buttons",
+        "P8: Flags EndModal(wxCANCEL): wxCANCEL is a style flag, not the return code wxID_CANCEL, so ShowModal returns the wrong value; fix: EndModal(wxID_CANCEL)",
+        "P9: Flags that restore_original() runs only in the Cancel button handler: ESC (DPIDialog's char hook -> Close()) and the close box end the dialog with wxID_CANCEL without running the custom Button's handler, so the draft is not cleared; fix: do cleanup on every non-OK exit (after ShowModal returns, or in a close/EndModal path)",
+        "P10: Flags m_preview->SetLabel(...) followed by Wrap(FromDIP(360)) on every update: in wx 3.3.2 Wrap() is a no-op when the width equals the last wrap width, so updated labels stay unwrapped; fix: Wrap(-1) then Wrap(w), or wxST_WRAP / Orca Label with LB_AUTO_WRAP",
+        "P11 (not a defect): Does not claim that m_options->Enable(...) leaves the ::CheckBox or its wxStaticText label looking enabled: ::CheckBox is a native wxBitmapToggleButton, so the ancestor's disable greys it on every port without calling its Enable() override (MSW: NotifyWindowOnEnableChange -> DoEnable -> EnableWindow, and the owner-drawn button paints its SetBitmapDisabled art; GTK3: native insensitivity, and the button's wxGtkImage draws a greyed copy of its current bitmap while !IsEnabled(); macOS: setEnabled:NO, and AppKit dims the image), and wxStaticText greys natively. Suggesting pin->Enable() to get the designed disabled art on GTK is at most a nit",
+        "P12: Flags that the patch registers neither new file: they are not in SLIC3R_GUI_SOURCES in src/slic3r/CMakeLists.txt (never compiled), and PresetNoteDialog.cpp is not in localization/i18n/list.txt (run_gettext scans only the listed files, so its _L strings never reach OrcaSlicer.pot); fix: add both entries",
+        "Does not report false defects about correct code: the weak_ptr-guarded CallAfter is not a use-after-free (alive is checked before `this` is used), GetSizer()->SetSizeHints(this) in on_dpi_changed is fine, DialogButtons' untranslated labels are correct"
+      ]
+    }
+  ]
+}

.claude/skills/orca-wxwidgets/evals/files/filament-notes.patch

@@ -0,0 +1,252 @@
+diff --git a/src/slic3r/GUI/FilamentNotesDialog.hpp b/src/slic3r/GUI/FilamentNotesDialog.hpp
+new file mode 100644
+--- /dev/null
++++ b/src/slic3r/GUI/FilamentNotesDialog.hpp
+@@ -0,0 +1,56 @@
++#pragma once
++
++#include "GUI_Utils.hpp"
++
++#include <wx/timer.h>
++
++#include <string>
++#include <thread>
++#include <vector>
++
++class Button;
++class TextInput;
++
++namespace Slic3r { namespace GUI {
++
++// Strip of filament colour swatches; hovering a swatch outlines it.
++class SwatchPreview : public wxPanel
++{
++public:
++    SwatchPreview(wxWindow* parent);
++    void set_colours(const std::vector<wxColour>& colours);
++
++private:
++    void on_left_down(wxMouseEvent& e);
++    void on_left_up(wxMouseEvent& e);
++    void on_motion(wxMouseEvent& e);
++    void draw_hover(int index);
++
++    std::vector<wxColour> m_colours;
++    bool                  m_dragging{false};
++    int                   m_hover{-1};
++};
++
++// Non-modal editor for the user's notes on a filament, synced with the cloud.
++class FilamentNotesDialog : public DPIDialog
++{
++public:
++    FilamentNotesDialog(wxWindow* parent, const std::string& filament_id);
++    ~FilamentNotesDialog() override;
++
++protected:
++    void on_dpi_changed(const wxRect& suggested_rect) override;
++
++private:
++    void start_sync();
++    void on_sync_done(wxCommandEvent& e);
++    void show_more_menu();
++
++    std::string    m_filament_id;
++    TextInput*     m_name_input{nullptr};
++    wxTextCtrl*    m_notes{nullptr};
++    wxStaticText*  m_status{nullptr};
++    SwatchPreview* m_preview{nullptr};
++    Button*        m_more_btn{nullptr};
++    wxTimer*       m_autosave_timer{nullptr};
++    std::thread    m_sync_thread;
++};
++
++}} // namespace Slic3r::GUI
+diff --git a/src/slic3r/GUI/FilamentNotesDialog.cpp b/src/slic3r/GUI/FilamentNotesDialog.cpp
+new file mode 100644
+--- /dev/null
++++ b/src/slic3r/GUI/FilamentNotesDialog.cpp
+@@ -0,0 +1,170 @@
++#include "FilamentNotesDialog.hpp"
++
++#include "GUI_App.hpp"
++#include "I18N.hpp"
++#include "Widgets/Button.hpp"
++#include "Widgets/DialogButtons.hpp"
++#include "Widgets/TextInput.hpp"
++
++#include <wx/dcbuffer.h>
++#include <wx/dcclient.h>
++#include <wx/menu.h>
++#include <wx/statbox.h>
++
++namespace Slic3r {
++// Provided by the cloud layer; blocking network call.
++std::string fetch_remote_note(const std::string& filament_id);
++
++namespace GUI {
++
++wxDEFINE_EVENT(EVT_NOTES_SYNC_DONE, wxCommandEvent);
++
++SwatchPreview::SwatchPreview(wxWindow* parent)
++    : wxPanel(parent, wxID_ANY, wxDefaultPosition, wxSize(FromDIP(240), FromDIP(28)))
++{
++    SetBackgroundStyle(wxBG_STYLE_PAINT);
++    Bind(wxEVT_PAINT, [this](wxPaintEvent&) {
++        wxAutoBufferedPaintDC dc(this);
++        dc.SetBackground(wxBrush(GetBackgroundColour()));
++        dc.Clear();
++        const wxSize sz = GetClientSize();
++        const int    w  = sz.x / std::max<int>(1, m_colours.size());
++        dc.SetPen(*wxTRANSPARENT_PEN);
++        for (size_t i = 0; i < m_colours.size(); ++i) {
++            dc.SetBrush(wxBrush(m_colours[i]));
++            dc.DrawRectangle(int(i) * w, 0, w, sz.y);
++        }
++    });
++    Bind(wxEVT_LEFT_DOWN, &SwatchPreview::on_left_down, this);
++    Bind(wxEVT_LEFT_UP, &SwatchPreview::on_left_up, this);
++    Bind(wxEVT_MOTION, &SwatchPreview::on_motion, this);
++}
++
++void SwatchPreview::set_colours(const std::vector<wxColour>& colours)
++{
++    m_colours = colours;
++    Refresh();
++}
++
++void SwatchPreview::on_left_down(wxMouseEvent& e)
++{
++    m_dragging = true;
++    CaptureMouse();
++}
++
++void SwatchPreview::on_left_up(wxMouseEvent& e)
++{
++    if (m_dragging) {
++        m_dragging = false;
++        ReleaseMouse();
++    }
++}
++
++void SwatchPreview::on_motion(wxMouseEvent& e)
++{
++    const wxPoint p   = ScreenToClient(wxGetMousePosition());
++    const int     w   = GetClientSize().x / std::max<int>(1, m_colours.size());
++    const int     idx = w > 0 ? p.x / w : -1;
++    if (idx != m_hover) {
++        m_hover = idx;
++        draw_hover(idx);
++    }
++    e.Skip();
++}
++
++void SwatchPreview::draw_hover(int index)
++{
++    wxClientDC dc(this);
++    dc.SetPen(wxPen(wxColour("#009688"), 2));
++    dc.SetBrush(*wxTRANSPARENT_BRUSH);
++    const int w = GetClientSize().x / std::max<int>(1, m_colours.size());
++    dc.DrawRectangle(index * w, 0, w, GetClientSize().y);
++}
++
++FilamentNotesDialog::FilamentNotesDialog(wxWindow* parent, const std::string& filament_id)
++    : DPIDialog(parent, wxID_ANY, _L("Filament notes"), wxDefaultPosition, wxDefaultSize, wxDEFAULT_DIALOG_STYLE)
++    , m_filament_id(filament_id)
++{
++    SetBackgroundColour(*wxWHITE);
++    auto* sizer = new wxBoxSizer(wxVERTICAL);
++
++    m_name_input = new TextInput(this, wxEmptyString, wxEmptyString, wxEmptyString, wxDefaultPosition, wxSize(FromDIP(300), -1));
++    m_name_input->GetTextCtrl()->Bind(wxEVT_TEXT, [this](wxCommandEvent&) {
++        wxString v = m_name_input->GetTextCtrl()->GetValue();
++        v.Trim(false);
++        m_name_input->GetTextCtrl()->SetValue(v.Upper());
++        m_autosave_timer->StartOnce(1000);
++    });
++    m_name_input->GetTextCtrl()->Bind(wxEVT_KILL_FOCUS, [this](wxFocusEvent&) {
++        m_autosave_timer->StartOnce(1);
++    });
++    sizer->Add(m_name_input, 0, wxEXPAND | wxALL, FromDIP(10));
++
++    auto* box = new wxStaticBoxSizer(wxVERTICAL, this, _L("Notes"));
++    m_notes   = new wxTextCtrl(this, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(400, 160), wxTE_MULTILINE);
++    box->Add(m_notes, 1, wxEXPAND | wxALL, FromDIP(6));
++    sizer->Add(box, 1, wxEXPAND | wxLEFT | wxRIGHT, FromDIP(10));
++
++    m_preview = new SwatchPreview(this);
++    sizer->Add(m_preview, 0, wxEXPAND | wxALL, FromDIP(10));
++
++    m_status = new wxStaticText(this, wxID_ANY, wxEmptyString);
++    sizer->Add(m_status, 0, wxLEFT | wxRIGHT, FromDIP(10));
++
++    m_more_btn = new Button(this, _L("More..."));
++    m_more_btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { show_more_menu(); });
++    sizer->Add(m_more_btn, 0, wxALL, FromDIP(10));
++
++    auto* btns = new DialogButtons(this, {"OK", "Cancel"});
++    btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Close(); });
++    btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Close(); });
++    sizer->Add(btns, 0, wxEXPAND);
++
++    m_autosave_timer = new wxTimer(this);
++    Bind(wxEVT_TIMER, [this](wxTimerEvent&) {
++        wxGetApp().app_config->set("filament_note_" + m_filament_id, m_notes->GetValue().ToStdString());
++        wxGetApp().app_config->save();
++    });
++
++    Bind(EVT_NOTES_SYNC_DONE, &FilamentNotesDialog::on_sync_done, this);
++    Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent&) { delete this; });
++
++    SetSizer(sizer);
++    Layout();
++    wxGetApp().UpdateDlgDarkUI(this);
++
++    start_sync();
++}
++
++FilamentNotesDialog::~FilamentNotesDialog()
++{
++    if (m_sync_thread.joinable())
++        m_sync_thread.detach();
++}
++
++void FilamentNotesDialog::start_sync()
++{
++    m_sync_thread = std::thread([this]() {
++        m_status->SetLabel(_L("Syncing..."));
++        const std::string remote = fetch_remote_note(m_filament_id);
++        wxCommandEvent evt(EVT_NOTES_SYNC_DONE);
++        evt.SetString(wxString::FromUTF8(remote));
++        wxPostEvent(this, evt);
++    });
++}
++
++void FilamentNotesDialog::on_sync_done(wxCommandEvent& e)
++{
++    m_notes->SetValue(e.GetString());
++    m_status->SetLabel(_L("Synced"));
++}
++
++void FilamentNotesDialog::show_more_menu()
++{
++    wxMenu menu;
++    menu.Append(wxID_CLEAR, _L("Clear notes"));
++    menu.Append(wxID_REVERT, _L("Reload from cloud"));
++    m_more_btn->Bind(wxEVT_MENU, [this](wxCommandEvent& e) {
++        if (e.GetId() == wxID_CLEAR)
++            m_notes->Clear();
++        else
++            start_sync();
++    });
++    PopupMenu(&menu, m_more_btn->GetPosition() + wxPoint(0, m_more_btn->GetSize().y));
++}
++
++void FilamentNotesDialog::on_dpi_changed(const wxRect&)
++{
++    m_more_btn->Rescale();
++    Layout();
++    Refresh();
++}
++
++}} // namespace Slic3r::GUI

.claude/skills/orca-wxwidgets/evals/files/preset-note.patch

@@ -0,0 +1,242 @@
+diff --git a/src/slic3r/GUI/PresetNoteDialog.hpp b/src/slic3r/GUI/PresetNoteDialog.hpp
+new file mode 100644
+--- /dev/null
++++ b/src/slic3r/GUI/PresetNoteDialog.hpp
+@@ -0,0 +1,57 @@
++#pragma once
++
++#include "GUI_Utils.hpp"
++#include "Widgets/StaticBox.hpp"
++#include "Widgets/StateColor.hpp"
++
++#include <memory>
++
++class TextInput;
++
++namespace Slic3r { namespace GUI {
++
++wxDECLARE_EVENT(EVT_NOTE_CHIP_CLICKED, wxCommandEvent);
++
++// Rounded chip that shows a preset's note in the sidebar; clicking it opens the editor.
++class NoteChip : public StaticBox
++{
++public:
++    NoteChip(wxWindow* parent, const wxString& text);
++    void set_text(const wxString& text);
++    void Rescale();
++
++protected:
++    void doRender(wxDC& dc) override;
++
++private:
++    void on_left_down(wxMouseEvent& e);
++    void on_left_up(wxMouseEvent& e);
++    void on_capture_lost(wxMouseCaptureLostEvent& e);
++
++    wxString   m_text;
++    bool       m_pressed{false};
++    StateColor m_bg;
++};
++
++// Modal editor for the note attached to a preset.
++class PresetNoteDialog : public DPIDialog
++{
++public:
++    PresetNoteDialog(wxWindow* parent, const wxString& preset_name, const wxString& note);
++    wxString get_note() const;
++
++protected:
++    void on_dpi_changed(const wxRect& suggested_rect) override;
++
++private:
++    void update_preview();
++    void restore_original();
++
++    TextInput*    m_input{nullptr};
++    wxStaticText* m_preview{nullptr};
++    wxPanel*      m_options{nullptr};
++    wxString      m_original;
++    std::shared_ptr<bool> m_alive;
++};
++
++}} // namespace Slic3r::GUI
+diff --git a/src/slic3r/GUI/PresetNoteDialog.cpp b/src/slic3r/GUI/PresetNoteDialog.cpp
+new file mode 100644
+--- /dev/null
++++ b/src/slic3r/GUI/PresetNoteDialog.cpp
+@@ -0,0 +1,178 @@
++#include "PresetNoteDialog.hpp"
++
++#include "GUI_App.hpp"
++#include "I18N.hpp"
++#include "MsgDialog.hpp"
++#include "Widgets/CheckBox.hpp"
++#include "Widgets/DialogButtons.hpp"
++#include "Widgets/Label.hpp"
++#include "Widgets/TextInput.hpp"
++
++#include <wx/bmpbndl.h>
++#include <wx/statbmp.h>
++
++namespace Slic3r { namespace GUI {
++
++wxDEFINE_EVENT(EVT_NOTE_CHIP_CLICKED, wxCommandEvent);
++
++NoteChip::NoteChip(wxWindow* parent, const wxString& text)
++    : StaticBox(parent, wxID_ANY)
++    , m_text(text)
++{
++    m_bg = StateColor(std::pair{wxColour("#F1F1F1"), (int) StateColor::Normal},
++                      std::pair{wxColour("#DBDBDB"), (int) StateColor::Hovered},
++                      std::pair{wxColour("#CECECE"), (int) StateColor::Pressed});
++    SetBackgroundColor(m_bg);
++    SetCornerRadius(FromDIP(4));
++    SetMinSize(wxSize(-1, FromDIP(24)));
++
++    Bind(wxEVT_LEFT_DOWN, &NoteChip::on_left_down, this);
++    Bind(wxEVT_LEFT_UP, &NoteChip::on_left_up, this);
++    Bind(wxEVT_MOUSE_CAPTURE_LOST, &NoteChip::on_capture_lost, this);
++    Bind(wxEVT_SIZE, [this](wxSizeEvent e) {
++        Refresh();
++        e.Skip();
++    });
++}
++
++void NoteChip::set_text(const wxString& text)
++{
++    m_text = text;
++    Refresh();
++}
++
++void NoteChip::Rescale()
++{
++    SetMinSize(wxSize(-1, FromDIP(24)));
++    Refresh();
++}
++
++void NoteChip::doRender(wxDC& dc)
++{
++    StaticBox::doRender(dc);
++    dc.SetFont(Label::Body_12);
++    dc.SetTextForeground(StateColor::darkModeColorFor(wxColour("#262E30")));
++    const wxSize ext = dc.GetTextExtent(m_text);
++    dc.DrawText(m_text, FromDIP(8), (GetSize().y - ext.y) / 2);
++}
++
++void NoteChip::on_left_down(wxMouseEvent& e)
++{
++    m_pressed = true;
++    if (!HasCapture())
++        CaptureMouse();
++    Refresh();
++}
++
++void NoteChip::on_left_up(wxMouseEvent& e)
++{
++    if (HasCapture())
++        ReleaseMouse();
++    if (m_pressed) {
++        m_pressed = false;
++        wxCommandEvent evt(EVT_NOTE_CHIP_CLICKED, GetId());
++        evt.SetEventObject(this);
++        GetEventHandler()->ProcessEvent(evt);
++    }
++    Refresh();
++}
++
++void NoteChip::on_capture_lost(wxMouseCaptureLostEvent& e)
++{
++    wxMouseEvent up(wxEVT_LEFT_UP);
++    on_left_up(up);
++}
++
++PresetNoteDialog::PresetNoteDialog(wxWindow* parent, const wxString& preset_name, const wxString& note)
++    : DPIDialog(parent ? parent : static_cast<wxWindow*>(wxGetApp().mainframe), wxID_ANY,
++                _("Preset note"), wxDefaultPosition, wxDefaultSize, wxCAPTION | wxCLOSE_BOX)
++    , m_original(note)
++    , m_alive(std::make_shared<bool>(true))
++{
++    SetBackgroundColour(*wxWHITE);
++    SetFont(Label::Body_14);
++    auto* sizer = new wxBoxSizer(wxVERTICAL);
++
++    auto* icon = new wxStaticBitmap(this, wxID_ANY,
++        wxBitmapBundle::FromSVGFile(from_u8(resources_dir() + "/images/note.svg"), wxSize(16, 16)));
++    sizer->Add(icon, 0, wxALL, FromDIP(10));
++
++    m_input = new TextInput(this, note, wxEmptyString, wxEmptyString, wxDefaultPosition,
++                            wxSize(FromDIP(360), -1), wxTE_PROCESS_ENTER);
++    sizer->Add(m_input, 0, wxEXPAND | wxLEFT | wxRIGHT, FromDIP(10));
++    m_input->GetTextCtrl()->Bind(wxEVT_TEXT, [this](wxCommandEvent& e) {
++        update_preview();
++        e.Skip();
++    });
++    Bind(wxEVT_TEXT_ENTER, [this](wxCommandEvent&) { EndModal(wxID_OK); }, m_input->GetId());
++
++    m_preview = new wxStaticText(this, wxID_ANY, wxEmptyString);
++    sizer->Add(m_preview, 0, wxEXPAND | wxALL, FromDIP(10));
++
++    m_options = new wxPanel(this);
++    m_options->SetBackgroundColour(*wxWHITE);
++    auto* opt_sizer = new wxBoxSizer(wxHORIZONTAL);
++    auto* pin = new ::CheckBox(m_options);
++    opt_sizer->Add(pin, 0, wxALIGN_CENTER_VERTICAL);
++    opt_sizer->Add(new wxStaticText(m_options, wxID_ANY, _L("Pin note to sidebar")), 0,
++                   wxALIGN_CENTER_VERTICAL | wxLEFT, FromDIP(6));
++    m_options->SetSizer(opt_sizer);
++    m_options->Enable(!note.empty());
++    sizer->Add(m_options, 0, wxALL, FromDIP(10));
++
++    auto* btns = new DialogButtons(this, {"OK", "Cancel"});
++    btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) {
++        if (m_input->GetTextCtrl()->GetValue().length() > 500) {
++            RichMessageDialog dlg(this, _L("The note is very long. Keep it anyway?"), _L("Preset note"),
++                                  wxYES_NO | wxICON_QUESTION);
++            dlg.SetYesNoLabels(_L("Keep"), _L("Shorten"));
++            if (dlg.ShowModal() != wxID_YES)
++                return;
++        }
++        EndModal(wxID_OK);
++    });
++    btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) {
++        restore_original();
++        EndModal(wxCANCEL);
++    });
++    sizer->Add(btns, 0, wxEXPAND);
++
++    SetSizerAndFit(sizer);
++    update_preview();
++    CenterOnParent();
++    wxGetApp().UpdateDlgDarkUI(this);
++}
++
++wxString PresetNoteDialog::get_note() const { return m_input->GetTextCtrl()->GetValue(); }
++
++void PresetNoteDialog::update_preview()
++{
++    m_preview->SetLabel(wxString::Format(_L("Shown in the sidebar as: %s"), get_note()));
++    m_preview->Wrap(FromDIP(360));
++
++    // Persist the draft a moment later, once typing settles.
++    std::weak_ptr<bool> alive = m_alive;
++    wxGetApp().CallAfter([this, alive] {
++        if (alive.expired() || IsBeingDeleted())
++            return;
++        wxGetApp().app_config->set("preset_note_draft", into_u8(get_note()));
++    });
++}
++
++void PresetNoteDialog::restore_original()
++{
++    m_input->GetTextCtrl()->ChangeValue(m_original);
++    wxGetApp().app_config->set("preset_note_draft", "");
++}
++
++void PresetNoteDialog::on_dpi_changed(const wxRect&)
++{
++    m_input->Rescale();
++    GetSizer()->SetSizeHints(this);
++    Refresh();
++}
++
++}} // namespace Slic3r::GUI

.claude/skills/orca-wxwidgets/references/colours-dark-mode.md

@@ -0,0 +1,858 @@
+# Colours and dark mode
+
+Covers `wxColour`, system colours and the appearance API, `wxEVT_SYS_COLOUR_CHANGED`, wxMSW's own dark
+mode, colour inheritance and the places native controls ignore colours, `StateColor`, Orca's dark-mode
+machinery (the dark-mode state, the `Update*DarkUI` walk, NppDarkMode, the runtime switch per platform) and
+dark-mode icons. Read it before setting any colour, adding a dialog/panel, or debugging "wrong colour in
+dark (or light) mode".
+
+Contents: [Rules](#rules) · [wxColour](#wxcolour) · [System colours and appearance](#system-colours-and-appearance) ·
+[wxEVT_SYS_COLOUR_CHANGED](#wxevt_sys_colour_changed) · [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings) ·
+[Window colours and native-control limits](#window-colours-inheritance-and-native-control-limits) ·
+[StateColor](#statecolor) · [Orca dark-mode state](#orca-dark-mode-state) ·
+[The Update*DarkUI walk](#the-updatedarkui-walk) · [NppDarkMode](#nppdarkmode-windows) ·
+[Runtime theme switch](#runtime-theme-switch-and-re-applying-colours) · [Dark-mode icons](#dark-mode-icons)
+
+## Rules
+
+1. Ask Orca, not wx, whether the UI is dark: `wxGetApp().dark_mode()`. Never `wxSystemSettings::GetAppearance().IsDark()`
+   or `SelectLightDark()` in GUI code — on Windows they report the system app mode — and do not read the
+   `dark_color_mode` key directly (macOS `dark_mode()` ignores it). → [Orca state](#orca-dark-mode-state)
+2. Theme with palette colours, not `wxSYS_COLOUR_*`: on Windows wx serves its dark palette whenever the
+   system app mode is dark, and macOS system colours are dynamic so the dark map cannot key them. → [System colours](#system-colours-and-appearance)
+3. Write colours as `wxColour("#RRGGBB")` or `wxColour(r, g, b)`. A packed integer `wxColour(0xRRGGBB)` is
+   read as `0x00BBGGRR`; `StateColor` integers are the opposite (`0xRRGGBB`). → [wxColour](#wxcolour)
+4. Give every `wxPanel`/`wxScrolledWindow` you create an explicit palette background (`*wxWHITE`, `#F8F8F8`, …),
+   and set it **before** creating Orca widgets inside it. → [Window colours](#window-colours-inheritance-and-native-control-limits), [Update*DarkUI](#the-updatedarkui-walk)
+5. Background colour is never inherited; foreground only at creation, only from the immediate parent, only for
+   `wxControl`-like classes. Set colours on the window that shows them. → [Window colours](#window-colours-inheritance-and-native-control-limits)
+6. In a `StateColor`, list specific states first and `Normal` last; negate with `Not*`/`Disabled`, never `~X`. → [StateColor](#statecolor)
+7. A literal light colour given to `SetForegroundColour`/`SetBackgroundColour`/`wxPen`/`wxBrush` goes through
+   `StateColor::darkModeColorFor()` when it is a `gDarkColors` key, else branch on `dark_mode()`. → [Re-applying colours](#runtime-theme-switch-and-re-applying-colours)
+8. End every dialog constructor (after all children exist, before `ShowModal()`) with `wxGetApp().UpdateDlgDarkUI(this)`;
+   frames use `UpdateFrameDarkUI`; a subtree built after the app-wide pass ends with `UpdateDarkUIWin(this)`.
+   `UpdateDarkUI(win)` themes one window only. → [Update*DarkUI](#the-updatedarkui-walk)
+9. Apply deliberate non-palette colours **after** the walk, and again on theme change; the dark walk rewrites every
+   visited window's foreground. → [Update*DarkUI](#the-updatedarkui-walk)
+10. Re-apply every construction-time colour and every name-selected icon in `on_sys_color_changed()` (DPIDialog/DPIFrame)
+    or a `sys_color_changed()` chained from the owner, ending with `Refresh()`. A long-lived (cached, lazily built,
+    hidden) window must be reached from `MainFrame::on_sys_color_changed`. → [Runtime switch](#runtime-theme-switch-and-re-applying-colours)
+11. A `wxEVT_SYS_COLOUR_CHANGED` handler on a TLW or container calls `Skip()` and is idempotent. Do not rely on the
+    event reaching nested children in Orca. → [wxEVT_SYS_COLOUR_CHANGED](#wxevt_sys_colour_changed)
+12. Do not call `wxApp::SetAppearance()` or change the `MSWEnableDarkMode(DarkMode_Auto)` → `NppDarkMode::InitDarkMode()`
+    order in `GUI_App::on_init_inner`. → [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings)
+13. An explicit `dark_color_mode` ("0" or "1") wins in both directions; `check_dark_mode()` is only the fallback for an
+    unset key. → [Orca state](#orca-dark-mode-state)
+14. A new theme-switch path first sets the `dark_color_mode` key (Windows: `app_config->set` + `save()`; macOS/Linux:
+    `update_dark_config()`), then refreshes the state computed from `dark_mode()`: `m_is_dark_mode` (`Update_dark_mode_flag()`,
+    which `update_dark_config()` already calls), StateColor's `gDarkMode` and the label colours (`init_label_colours()`)
+    and, on Windows, NppDarkMode's `g_darkModeEnabled` (`force_colors_update()`). `dark_mode()` itself is live; wx's own
+    MSW mode follows the system and is not Orca's to set. → [Orca state](#orca-dark-mode-state)
+15. Author single-tone SVGs in the substitution palette (uppercase hex, `#262E30` for near-black line art); anything
+    else needs a `*_dark` asset chosen by name in code that re-runs on theme change. → [Icons](#dark-mode-icons)
+16. Never use a native `wxButton`'s `SetBackgroundColour` for styling (MSW turns it owner-drawn, macOS ignores it):
+    use Orca `Button` + `SetStyle()`. → [Window colours](#window-colours-inheritance-and-native-control-limits)
+17. Re-apply text-control colours after every `Enable()` (macOS resets them). → [Window colours](#window-colours-inheritance-and-native-control-limits)
+18. Windows menu bitmaps follow wx's menu state (`check_dark_mode()`), not `dark_mode()`. → [Icons](#dark-mode-icons)
+
+## wxColour
+
+**Contract.** Constructors: `()`, `(r, g, b, a = wxALPHA_OPAQUE)`, `(unsigned long|long|int|unsigned int)` ("A
+packed RGB value", `interface/wx/colour.h:98-101`), `(const wxString&|const char*|const wchar_t*)`;
+`wxColour(bool) = delete` (`include/wx/colour.h:225-240`; `docs/changes.txt:246-248`: code "unintentionally
+and mistakenly using wxColour ctor from bool … doesn't compile any longer").
+
+| Fact | Cite |
+|---|---|
+| Packed integers are `0x00BBGGRR` (`0xAABBGGRR` for `SetRGBA`): "Notice the right-to-left order of components!" `wxColour(0x009688)` is R=0x88 G=0x96 B=0x00, not Orca teal. Only symmetric greys (`0xEEEEEE`) read the same both ways. wx writes its own MSW dark palette this way (`wxColour(0x9e5315)` is a blue). | `interface/wx/colour.h:179-183`; `include/wx/colour.h:77-83`; `src/msw/darkmode.cpp` `wxDarkModeSettings::GetColour` |
+| `Set(const wxString&)` accepts colour-database names, CSS `rgb(r,g,b)`/`rgba(r,g,b,a)` (case-insensitive) and `#` + 6 hex digits; returns `false` on failure. **[source]** the parser also takes `#rgb`, `#rgba`, `#rrggbbaa`, but the documented form (and XRC, "but not "#rgb"") is `#RRGGBB` — write that. | `interface/wx/colour.h:288-301`; `src/common/colourcmn.cpp` `FromString`; `docs/doxygen/overviews/xrc_format.h:229` |
+| The string ctor is `{ Set(colourName); }`: a typo silently yields `IsOk() == false`. An invalid colour passed to `SetBackgroundColour`/`SetForegroundColour` means "reset to the default colour". | `include/wx/colour.h:235`; `interface/wx/colour.h:239-243`; `interface/wx/window.h:2438-2439` |
+| 3.3 changed `wxColourDatabase` to CSS values ("GREEN" is `#008000` in the CSS scheme, `#00ff00` traditionally; wxGTK already used CSS); `UseScheme()` reverts. **[source]** stock objects did not change: `*wxGREEN` is still (0,255,0), so `*wxGREEN != wxColour("green")`. | `docs/changes.txt:31-33`; `interface/wx/gdicmn.h:999-1013`; `src/common/gdicmn.cpp:516`, `:805-807` |
+| `wxTransparentColour` = `wxColour(0,0,0,wxALPHA_TRANSPARENT)`: valid, black, alpha 0. `IsTransparent()/IsOpaque()/IsTranslucent()` are new in 3.3.1. `Alpha()` returns `wxALPHA_OPAQUE` "on platforms where alpha is not yet supported". | `include/wx/colour.h:31`; `interface/wx/colour.h:110-114`, `:260-282` |
+| `GetLuminance()` = 0.299R + 0.587G + 0.114B on 0..1. | `interface/wx/colour.h:212-222` |
+| `ChangeLightness(ialpha)`: 0 = black, 100 = unchanged, 200 = white; returns a copy. **[source]** values are clamped to 0..200 and the result is built as `wxColour(r,g,b)` — alpha is dropped. | `interface/wx/colour.h:365-377`; `src/common/colourcmn.cpp` `wxColourBase::ChangeLightness` |
+| `MakeDisabled(brightness = 255)` "modifies the object in place and returns the object itself". **[source]** each channel becomes `brightness + 0.4·(c − brightness)` — it keeps 40% of the colour and moves 60% toward `brightness`, so on a dark background the default makes a "disabled" colour light. | `interface/wx/colour.h:336-342`; `src/common/colourcmn.cpp` `MakeDisabled`, `AlphaBlend` |
+
+Alpha in window colours: **[source]** MSW brushes are `CreateSolidBrush(COLORREF)` (alpha dropped) and pen/brush
+transparency is style-based, so a solid brush of a transparent colour paints **black** through GDI. Use
+`*wxTRANSPARENT_BRUSH` or `wxGCDC`/`wxGraphicsContext` (`src/msw/brush.cpp:187`; `include/wx/brush.h:60-68`).
+Background styles and transparent windows: see `references/painting-custom-widgets.md`.
+
+**OrcaSlicer.** Build colours from hex strings or RGB triples, never from names. Text over user/filament
+swatches is chosen by luminance (`clr.GetLuminance() < 0.51 ? *wxWHITE : *wxBLACK`, `wxExtensions.cpp` swatch
+helpers, `PresetComboBoxes.cpp`). A packed `wxColour(0x…)` literal is harmless only for a symmetric grey
+(`wxColour(0xEEEEEE)`); integer literals in `StateColor` contexts are RGB.
+
+**Pitfalls**
+
+- **Rule:** Never write a packed integer `wxColour`; keep `StateColor` integers as they are.
+  **Why:** `wxColour(unsigned long)` is BGR; `StateColor(unsigned long)`/`append(unsigned long, …)` byte-swap the value
+  so it is RGB (`Widgets/StateColor.cpp` `StateColor::append`). "Fixing" one to look like the other inverts R and B.
+  ```cpp
+  // Wrong: R=0x88 G=0x96 B=0x00 (olive), not #009688
+  label->SetForegroundColour(wxColour(0x009688));
+  // Right:
+  label->SetForegroundColour(wxColour("#009688"));
+  // Also right (StateColor integers are 0xRRGGBB, alpha byte 0 = opaque):
+  box->SetBorderColor(StateColor(std::make_pair(0x009688, (int) StateColor::Hovered),
+                                 std::make_pair(0xDBDBDB, (int) StateColor::Normal)));
+  ```
+  Cite: `interface/wx/colour.h:179-183`; `Widgets/StateColor.cpp` `StateColor::append(unsigned long, int)`.
+- **Rule:** Validate colours from external data with `Set()`.
+  **Why:** an invalid colour reaching a setter silently resets the window to its default colour.
+  ```cpp
+  // Wrong: wxColour c(user_str); win->SetBackgroundColour(c);
+  // Right:
+  wxColour c; if (!c.Set(user_str)) c = fallback; win->SetBackgroundColour(c);
+  ```
+  Cite: `include/wx/colour.h:235`; `interface/wx/window.h:2438-2439`.
+- **Rule:** `ChangeLightness(80)` darkens by 20%; there are no negative arguments. On dark backgrounds pass a dark
+  `brightness` to `MakeDisabled` or use a palette disabled colour (`#6B6B6B`/`#ACACAC`, mapped in dark).
+  Cite: `interface/wx/colour.h:365-377`, `:336-342`.
+
+## System colours and appearance
+
+**Contract.** `wxSystemSettings::GetColour(index)`: the values "map 1:1 the native values supported by the Windows'
+GetSysColor function. Note that other ports … usually map the same colour to various wxSYS_COLOUR_* values"; "The
+returned colour is always valid" (`interface/wx/settings.h:44-48`, `:398-407`). New in 3.3.2:
+`wxSYS_COLOUR_GRIDLINES`, `wxSYS_COLOUR_LISTBOXHIGHLIGHT` (`interface/wx/settings.h:120-141`). `wxSYS_COLOUR_FRAMEBK` = BTNFACE.
+
+`wxSystemSettings::GetAppearance()` returns `wxSystemAppearance` (`interface/wx/settings.h:288-371`):
+
+| Method | Contract |
+|---|---|
+| `IsDark()` | "checks the appearance of the current application and not the other applications on the system, so under MSW … will return false even if dark mode is used system-wide unless the application opted in using dark mode using wxApp::MSWEnableDarkMode()" (`:332-346`). An incompatible 3.3 change (`docs/changes.txt:71-73`). |
+| `AreAppsDark()` (3.3.0) | system-wide app dark mode "even if it's not enabled for this particular application"; same as `IsDark()` off MSW (`:308-321`). |
+| `IsSystemDark()` (3.3.0) | the "Windows mode", which can differ from the "app mode" (`:348-358`). |
+| `IsUsingDarkBackground()` | luminance fallback, "generally not very useful to call directly" (`:360-370`). |
+| `GetName()` | "only implemented for macOS", e.g. "NSAppearanceNameAqua"; empty elsewhere (`:323-330`). |
+| `wxSystemSettings::SelectLightDark(light, dark)` (3.3.0) | "just a convenient helper using wxSystemAppearance::IsDark()" (`:460-473`); literally `GetAppearance().IsDark() ? dark : light` (`include/wx/settings.h:234-237`). |
+
+**Platforms** (all **[source]**):
+
+| Port | `IsDark()` | `GetColour()` |
+|---|---|---|
+| MSW | `wxMSWDarkMode::IsActive()` ‖ luminance fallback (`src/msw/settings.cpp:431-442`). Under `DarkMode_Auto`, `IsActive()` is uxtheme's `ShouldAppsUseDarkMode()` (`src/msw/darkmode.cpp` `ShouldUseDarkMode`) — the **system app mode**, not the app's own choice. `AreAppsDark()/IsSystemDark()` read `AppsUseLightTheme`/`SystemUsesLightTheme` from the registry. | `GetSysColor`, except GRIDLINES→BTNFACE, LISTBOXTEXT→WINDOWTEXT, LISTBOXHIGHLIGHT→HIGHLIGHT, LISTBOX→WINDOW, MENUBAR→MENU unless flat menus (`src/msw/settings.cpp:99-148`). LISTBOXHIGHLIGHTTEXT maps only to a raw index `GetSysColor` does not define — use HIGHLIGHTTEXT. **When wx dark mode is active every index is answered by `wxDarkModeSettings::GetColour()` first**; indices it leaves invalid (GRAYTEXT, 3DLIGHT, borders, …) fall back to the light `GetSysColor` value. |
+| macOS | `[NSApp effectiveAppearance]` best match is DarkAqua (`src/osx/cocoa/settings.mm` `IsDark`). | WINDOW/LISTBOX = `controlBackgroundColor`, BTNFACE = `windowBackgroundColor` (≥10.14), caption/border/MENU/MENUBAR = `windowFrameColor`, BTNTEXT/WINDOWTEXT/MENUTEXT/CAPTIONTEXT/INACTIVECAPTIONTEXT/INFOTEXT/LISTBOXTEXT = `controlTextColor` (GRAYTEXT = `disabledControlTextColor`, HIGHLIGHTTEXT = `selectedTextColor`), GRIDLINES = `gridColor`, INFOBK/APPWORKSPACE = `windowBackgroundColor` (commented "bogus"), HOTLIGHT = `linkColor` (`src/osx/cocoa/settings.mm` `GetColour`). The result wraps a **dynamic NSColor**: components resolve at call time under the effective appearance (`src/osx/cocoa/colour.mm`), and as a view background it adapts by itself. |
+| GTK3 (the default Linux build) | `IsUsingDarkBackground()`: luminance(WINDOWTEXT) − luminance(WINDOW) > 0.2 (`src/common/settcmn.cpp:96-112`); `AreAppsDark()/IsSystemDark()` = `IsDark()` (`:71-84`). wxGTK3 follows the freedesktop portal `org.freedesktop.appearance` `color-scheme` (GNOME's dark style) by setting `gtk-application-prefer-dark-theme` and stripping a `-dark`/`-Dark` theme-name suffix; no portal when `GTK_THEME` is set (`src/gtk/settings.cpp:251-334`, `:369-400`, `:1426-1450`). | From synthetic `GtkStyleContext`s (button, textview, treeview, headerbar, tooltip, menu), **cached** in `gs_systemColorCache` until "notify::gtk-theme-name" or a colour-scheme change (`src/gtk/settings.cpp:728-880`). |
+| GTK2 (opt-out build, `-DDEP_WX_GTK3=OFF`) | as GTK3 (luminance of the GTK2 theme); no portal/colour-scheme support (`#ifdef __WXGTK3__`). | `GtkStyle` of helper widgets (`src/gtk/settings.cpp:913ff`). |
+| Wayland | no Wayland-specific branch in colour/appearance code. | — |
+
+MSW dark palette (`wxDarkModeSettings::GetColour`, `src/msw/darkmode.cpp:300-370`; "not documented and are subject
+to change", `interface/wx/msw/darkmode.h:74-84`): WINDOW/LISTBOX/INFOBK/APPWORKSPACE/ACTIVECAPTION `0x202020`;
+the *TEXT indices `0xe0e0e0` except INACTIVECAPTIONTEXT `0xaaaaaa` (GRAYTEXT is left invalid); BTNFACE/GRIDLINES `0x333333`; MENU/INACTIVECAPTION `0x2b2b2b`; MENUBAR/LISTBOXHIGHLIGHT
+`0x626262`; HIGHLIGHT/MENUHILIGHT `0x9e5315` (a blue — packed BGR); HOTLIGHT `0xe48435`.
+
+**OrcaSlicer.** Orca does not theme with system colours or with `wxVisualAttributes`/`GetClassDefaultAttributes()`
+(the stock advice for matching native controls): it uses a fixed palette with a hand-written dark twin map
+(`StateColor`), because the exact-match map needs deterministic RGB that dynamic macOS colours and the MSW dark
+palette do not give, and because Windows needs an app-level live toggle wx cannot do (see
+[wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings)). `GUI_App::init_label_colours`
+still reads `wxSYS_COLOUR_WINDOWTEXT`/`wxSYS_COLOUR_WINDOW` for two light-mode values — on Windows with a dark system
+and Orca light those come from wx's dark palette. macOS: Orca's wx is patched to read NSColor components in sRGB
+instead of `NSCalibratedRGBColorSpace` (`deps/wxWidgets/0001-macos-use-srgb-colour-components.patch`, commit
+a7775296b0 "Fix macOS custom color accuracy"), so RGB read back from native colours matches the expected hex.
+
+**Pitfalls**
+
+- **Rule:** Never branch on wx's appearance in Orca GUI code.
+  **Why:** Orca calls `MSWEnableDarkMode(DarkMode_Auto)`, so on Windows `IsDark()`/`SelectLightDark()` follow the
+  system app mode — Windows dark + Orca light reports dark.
+  ```cpp
+  // Wrong:
+  auto c = wxSystemSettings::SelectLightDark(wxColour("#FFFFFF"), wxColour("#2D2D31"));
+  // Right:
+  auto c = StateColor::darkModeColorFor(wxColour("#FFFFFF"));            // #FFFFFF is a gDarkColors key
+  auto d = wxGetApp().dark_mode() ? wxColour("#EFEFF0") : wxColour("#333333"); // unmapped colour
+  ```
+  Cite: `src/msw/settings.cpp:431-442`; `src/msw/darkmode.cpp` `ShouldUseDarkMode`; 7d7f26ed69.
+- **Rule:** Theme with palette colours, not `wxSystemSettings::GetColour(wxSYS_COLOUR_*)`.
+  **Why:** MSW returns wx's dark palette whenever the system app mode is dark, regardless of Orca's setting
+  (`src/msw/settings.cpp:99-107`); on macOS the value is a dynamic colour no `gDarkColors` key matches; on GTK it
+  is whatever the theme says. Do not cache macOS system-colour RGB across a theme change.
+- **Rule:** Raw `wxButton` code that branches on `__WXMAC__` to `wxSYS_COLOUR_BTNFACE`/`BTNTEXT` only keeps the text
+  in the system colour: NSButton ignores the background colour anyway (see
+  [native limits](#window-colours-inheritance-and-native-control-limits)). New code uses Orca `Button`.
+
+## wxEVT_SYS_COLOUR_CHANGED
+
+**Contract.** "generated when the user changes the colour settings or when the system theme changes (e.g. automatic
+dark mode switching on macOS)". "The default event handler for this event propagates the event to child windows,
+since the system events are only sent to top-level windows. If intercepting this event for a top-level window,
+remember to either call wxEvent::Skip() on the event, call the base class handler, or pass the event on to the
+window's children explicitly" (`interface/wx/event.h:1942-1966`). **[source]** the default handler
+(`wxWindowBase::OnSysColourChanged`, `src/common/wincmn.cpp:3011-3027`) sends a fresh event to every
+**non-top-level** child and calls `Refresh()`; a child whose own handler does not `Skip()` stops it for its subtree.
+
+**Who sends it** (all **[source]**):
+
+| Port | Trigger |
+|---|---|
+| MSW | `WM_SYSCOLORCHANGE`, and `WM_SETTINGCHANGE` with "ImmersiveColorSet" (light/dark/accent switch) → `HandleSysColorChange()` on each TLW (`src/msw/window.cpp:3542`, `:5092`, `:5197-5200`). The default MSW handler re-sends a real `WM_SYSCOLORCHANGE` to native children (`wxWindowMSW::OnSysColourChanged`, `:5269-5293`); `wxFrame` also resets its background to `wxSYS_COLOUR_APPWORKSPACE` if `!UseBgCol()` and re-themes the menubar (`src/msw/frame.cpp:476-503`). |
+| macOS | per-NSWindow KVO on `effectiveAppearance`, **and** `windowDidChangeBackingProperties` when the window's colour space changes (dragging to a display with another profile) — no theme change involved (`src/osx/cocoa/nonownedwnd.mm:684-740`). Popups are `wxNonOwnedWindow`s and get it too. No defined order across windows. |
+| GTK3 | every TLW connects "notify::gtk-theme-name" with `g_signal_connect_after` so the colour cache is cleared before user handlers run (`src/gtk/toplevel.cpp:555-563`, `:951-955`); the portal colour-scheme handler `DoUpdateColorScheme` also loops over `wxTopLevelWindows` (`src/gtk/settings.cpp:251-334`). A dark switch that also renames the theme delivers the event **twice** per TLW. |
+| GTK2 (opt-out build) | "notify::gtk-theme-name" only. |
+
+`wxDialogBase::OnSysColourChanged` exists (`src/common/dlgcmn.cpp:561`) but no event table references it.
+
+**Usage.**
+```cpp
+Bind(wxEVT_SYS_COLOUR_CHANGED, [this](wxSysColourChangedEvent& e) {
+    e.Skip();      // keep propagation to children (and the wxFrame/wxWindowMSW base work)
+    recolor();     // idempotent and cheap: may fire twice (GTK3) or without any theme change (macOS)
+});
+```
+
+**OrcaSlicer.** `DPIAware<P>` (`GUI_Utils.hpp`) binds the event on every platform:
+- macOS/Linux: `update_dark_config()` (writes `dark_color_mode` from `GetAppearance().IsDark()` and calls
+  `Update_dark_mode_flag()`), then the virtual `on_sys_color_changed()`, then `Skip()`.
+- Windows: the body is empty and deliberately does not `Skip()` ("Not calling Skip() is what stops the event
+  propagating on Windows"). That consumes the event at every DPIAware TLW, so wx's
+  `wxWindowMSW::OnSysColourChanged` and every child handler (Plater's included) never run there. On Windows the
+  theme switch comes only from Preferences ([runtime switch](#runtime-theme-switch-and-re-applying-colours)).
+
+Elsewhere containers that bind the event without `Skip()` stop it for their subtree (`ButtonsListCtrl` in
+`Notebook.cpp` binds an empty handler; `Plater::priv::on_apple_change_color_mode` updates the GL canvases and does
+not skip). Long-lived UI is therefore refreshed through the `MainFrame::on_sys_color_changed` fan-out, not by
+child handlers.
+
+**Pitfalls**
+
+- **Rule:** A TLW or container handler calls `Skip()`.
+  **Why:** without it wx's default handler never propagates to the children (`interface/wx/event.h:1951-1956`).
+  Cite: `src/common/wincmn.cpp:3011-3027`.
+- **Rule:** Make the handler idempotent and cheap; never assume one event per theme change.
+  **Why:** macOS fires on display colour-space changes; GTK3 can fire twice per TLW.
+- **Rule:** Never put Orca re-theming in a child's SYS_COLOUR handler; implement `on_sys_color_changed()` /
+  `sys_color_changed()` and make sure the owner calls it.
+  **Why:** on Windows the event never reaches children; elsewhere any non-skipping ancestor swallows it.
+
+## wxMSW dark mode: MSWEnableDarkMode, SetAppearance, wxDarkModeSettings
+
+**Contract.** `bool wxApp::MSWEnableDarkMode(int flags = 0, wxDarkModeSettings* settings = nullptr)` (3.3.0,
+`@onlyfor{wxmsw}`, `interface/wx/app.h:1418-1465`):
+- "experimental"; uses "undocumented, and unsupported by Microsoft, functions"; works on Windows 10 later than
+  v1809 (including LTSC 2019) and all Windows 11; testing before 20H1 (v2004) "has been limited".
+- Flags: default follows the system ("dark mode is only used if it is the default mode for the applications on
+  the current system"); `DarkMode_Always` forces dark. **[source]** `DarkMode_Auto = 0` exists in
+  `include/wx/msw/app.h:48` although only `DarkMode_Always` is documented.
+- Returns `true` if enabled, `false` "most likely because the system doesn't support dark mode".
+- Alternatives: the `msw.dark-mode` system option (1 = `MSWEnableDarkMode()`, 2 = `DarkMode_Always`, settable by
+  environment variable from outside the app, `interface/wx/sysopt.h:85-89`), or `SetAppearance(System|Dark)`.
+- Known limitations (`interface/wx/app.h:1434-1448`): anything `TaskDialog()`-based has no dark mode —
+  `wxMessageBox()`, `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`, simple `wxAboutBox()` (wx suggests
+  `wxGenericMessageDialog`/`wxGenericProgressDialog`); common-dialog wrappers `wxColourDialog`, `wxFindReplaceDialog`,
+  `wxFontDialog`, `wxPageSetupDialog`, `wxPrintDialog`; `wxTimePickerCtrl`, `wxDatePickerCtrl`, `wxCalendarCtrl`
+  stay light; toolbar items with `wxToolBar::SetDropdownMenu()` draw the drop-down "almost invisible".
+
+`AppearanceResult wxApp::SetAppearance(Appearance::System|Light|Dark)` (3.3.0, `interface/wx/app.h:1152-1190`):
+GTK/macOS follow the system by default and the call is immediate and "affects all the existing windows as well
+as any windows created after this call"; "Under MSW, the default appearance is always light" and an app that
+wants to follow the system must call it with `Appearance::System`; "the appearance can be only set before any
+windows are created and calling this function too late will return AppearanceResult::CannotChange" (only wxMSW
+returns it);
+`Failure` e.g. "because `GTK_THEME` is defined".
+
+`wxDarkModeSettings` (`interface/wx/msw/darkmode.h:30-111`), passed to `MSWEnableDarkMode()`: `GetColour(wxSystemColour)`
+(defaults "not documented and are subject to change"; the doc example names `0x202020` as the default background);
+`GetMenuColour(wxMenuColour)` — menu-bar colours match no `wxSystemColour`, affect top-level menus only (items use
+`wxOwnerDrawn::SetTextColour()`), "must be valid"; `GetBorderPen()` — invalid pen = system `wxStaticBox` border,
+which "doesn't look very well in dark mode"; the base returns grey.
+
+**[source] facts the docs do not state:**
+- `SetAppearance` on MSW returns `CannotChange` when any TLW exists **or `MSWEnableDarkMode` was already called**
+  (`gs_appMode != AppMode_Default`); `SetAppearance(Light)` returns `Ok` without doing anything
+  (`src/msw/darkmode.cpp` `wxApp::SetAppearance`). macOS `System` sets `NSApp.appearance` to
+  `[NSAppearance currentAppearance]` rather than nil, pinning the current look (`src/osx/cocoa/utils.mm:485-513`);
+  GTK3 maps to the portal colour-scheme machinery; GTK2 always returns `Failure` (`src/gtk/app.cpp:355-381`).
+- `MSWEnableDarkMode` may be called any time, but dark title bars are applied only to TLWs **created** afterwards
+  (`EnableForTLW` at the end of TLW creation, `src/msw/toplevel.cpp:513`) and controls are dark-enabled at creation
+  (`MSWCreateControl` → `AllowForWindow` and, for some controls, `SetForegroundColour(LISTBOXTEXT)`,
+  `src/msw/control.cpp:133-140`). wx cannot flip existing windows — the reason `SetAppearance` refuses late calls.
+- wx takes ownership of the settings pointer (`wxDarkModeModule::SetSettings`) — allocate it with `new`.
+- `msw.dark-mode` is read in `wxApp::Initialize` (`src/msw/app.cpp:492-494`): a user's `WX_MSW_DARK_MODE`
+  environment variable enables wx dark mode before Orca's own call.
+- wx's owner-drawn menu path keys on `wxMSWDarkMode::IsActive()` (`src/msw/menuitem.cpp` `wxMenuItem::OnDrawItem`,
+  `GetColourToUse`; `src/msw/menu.cpp`; menu-bar UAH drawing in `src/msw/darkmode.cpp`).
+
+3.3.x dark-mode fix log: 3.3.2 wxMSW (`docs/changes.txt:297-308`: checkbox accessibility in dark mode, rendering of
+several controls, toolbar, menus; also "Revert use of WS_EX_COMPOSITED"), 3.3.1 (`:358-372`: wxStaticBitmap-in-notebook
+crash, disabled wxButton bitmaps and wxStaticText, notebook high-contrast background, wxDataViewCtrl light-mode
+border regression, selected toolbar buttons, wxComboCtrl, wxTE_RICH wxTextCtrl), 3.3.0 (`:385` "Add experimental dark
+mode support to wxMSW"); XRC dark colour variants (`:494`).
+
+**OrcaSlicer.** `GUI_App::on_init_inner` (`#ifdef __WINDOWS__`) calls `MSWEnableDarkMode(DarkMode_Auto)` and then
+`NppDarkMode::InitDarkMode(init_dark_color_mode, init_sys_menu_enabled)`. wx's call exists only so that wx-drawn
+menus get dark borders; NppDarkMode does the theming (title bars, explorer theme, scrollbars, list headers) because
+it can switch live and wx cannot. The code comment "Orca: todo switch to native dark mode support in wxWidgets and
+remove NppDarkMode" records the intent; the blocker is that a live Preferences toggle would become restart-only
+(`SetAppearance` returns `CannotChange` after startup, existing windows cannot be restyled) and TaskDialog/common
+dialogs/pickers stay light anyway — which is also why Orca has its own `MsgDialog` family and `ProgressDialog`.
+**[source]** consequences of `DarkMode_Auto`: wx's internal "dark" stays `AllowDark` and follows the **system app
+mode**; NppDarkMode's later `SetPreferredAppMode` call does not touch wx's `gs_appMode`. So with Windows light +
+Orca dark, wx's dark machinery (menus, `GetColour()`, `IsDark()`) stays off; with Windows dark + Orca light it is
+on: `GetColour()` returns the dark palette, new native controls are dark-enabled at creation, `IsDark()` is true.
+
+**Pitfalls**
+
+- **Rule:** Call `MSWEnableDarkMode(DarkMode_Auto)` before `NppDarkMode::InitDarkMode(...)`.
+  **Why:** wx 3.3 draws some native chrome (context/file menus) itself; without wx dark mode those menus keep a
+  light white border in dark mode. **[source]** both calls end in the same undocumented uxtheme ordinal 135
+  (`SetPreferredAppMode`; wx `src/msw/darkmode.cpp` `InitDarkMode`, Orca `dark_mode/dark_mode.hpp`
+  `AllowDarkModeForApp`) and the last call wins at OS level: NppDarkMode then sets **ForceDark or ForceLight** per
+  Orca's setting, overriding wx's AllowDark in both directions. In the other order wx's AllowDark would replace
+  Orca's forced mode. wx's own state still follows the system apps-dark setting; the two coincide only when the
+  system theme matches what Orca forces.
+  ```cpp
+  // Wrong: only NppDarkMode knows about dark mode; wx-drawn menus stay light-bordered
+  NppDarkMode::InitDarkMode(init_dark, sys_menu);
+  // Right:
+  MSWEnableDarkMode(DarkMode_Auto);               // enable wx 3.3's dark machinery
+  NppDarkMode::InitDarkMode(init_dark, sys_menu); // then ForceDark/ForceLight overrides AllowDark
+  ```
+  Cite: bf397a0632 (`GUI_App.cpp`, `GUI_App::on_init_inner`).
+- **Rule:** Do not call `wxTheApp->SetAppearance(...)` in Orca.
+  **Why:** MSW returns `CannotChange` (Orca already called `MSWEnableDarkMode`), GTK2 fails, and macOS pins
+  `NSApp.appearance` while `GUI_App::dark_mode()` keeps reading the system `AppleInterfaceStyle` — the two would
+  disagree.
+- **Rule:** Do not show wx's TaskDialog-based or common dialogs where dark mode matters; use `MessageDialog` and
+  friends (`MsgDialog.hpp`, see `references/windows-dialogs.md`).
+
+## Window colours, inheritance and native-control limits
+
+**Contract** (`interface/wx/window.h`):
+
+| Call | Effect |
+|---|---|
+| `SetBackgroundColour(c)` | "may not affect the entire control and could be not supported at all depending on the control and platform"; does not refresh ("you may wish to call wxWindow::ClearBackground or wxWindow::Refresh"); "will disable attempts to use themes for this window"; returns `false` if the colour was already set (`:2427-2461`). |
+| `SetOwnBackgroundColour(c)` | same, "but prevents it from being inherited by the children" (`:2588-2593`). |
+| `SetForegroundColour(c)` | "not all native controls support changing their foreground colour so this method may change their colour only partially or even not at all" (`:2561-2585`). |
+| `SetOwnForegroundColour(c)` | non-inheritable foreground (`:2622-2627`). |
+| `UseBgCol()`/`UseBackgroundColour()`, `UseForegroundColour()` | whether a colour was set for this window (`:2600-2632`). |
+| `InheritsBackgroundColour()`/`InheritsForegroundColour()` | the inheritable flag (`:2595-2639`). |
+| `ShouldInheritColours()` | "base class version returns false, but … overridden in wxControl where it returns true" (`:2645-2653`). |
+| `InheritAttributes()` | called during creation; a child takes an attribute only if the parent set it explicitly (not via `SetOwn*`) and the child did not (`:4052-4075`). |
+| `GetClassDefaultAttributes(variant)` → `wxVisualAttributes{font, colFg, colBg}` | "colBg may be wxNullColour if the controls background colour is not solid"; "All of them may be invalid if it was not possible to determine the default control appearance" (`:135-150`, `:4245-4273`). |
+
+**[source] facts the docs do not spell out** (`src/common/wincmn.cpp`):
+- **Background is never inherited.** The background branch of `InheritAttributes()` is `#if 0` ("inheriting (solid)
+  background colour is wrong as it totally breaks any kind of themed backgrounds", `:1524-1553`). Only font and
+  foreground are copied, only at creation time (`InheritAttributes()` runs from the ports' creation code), only
+  from the **immediate** parent.
+- `ShouldInheritColours()` is false for `wxWindow`/`wxPanel` (`include/wx/window.h:1682`), `wxAnyButton`
+  (`include/wx/anybutton.h:105`), `wxTextCtrl` (`include/wx/textctrl.h:872`), `wxControlWithItems` (`wxChoice`,
+  `wxListBox`, …; `include/wx/ctrlsub.h:447`), `wxTreeCtrl` (`include/wx/treectrl.h:399`); true for other
+  `wxControl`s (`wxStaticText`, `wxCheckBox`, …; `include/wx/control.h:98`).
+  So `panel->SetForegroundColour(x)` reaches only static-text-like direct children created afterwards.
+- `GetBackgroundColour()`/`GetForegroundColour()` **never return an invalid colour**: unset, they return
+  `GetDefaultAttributes()`, falling back to `GetClassDefaultAttributes()` = `wxSYS_COLOUR_BTNFACE` /
+  `wxSYS_COLOUR_WINDOWTEXT` (`:1556-1605`). Test `UseBgCol()` to know whether a colour was really set.
+- `SetBackgroundColour`/`SetForegroundColour` call `SetThemeEnabled(!hasBg && !fg.IsOk())` /
+  `SetThemeEnabled(!hasFg && !bg.IsOk())`: once either colour is set, theming is off (`:1640-1661`).
+
+**How children still look like their parent** (visual inheritance ≠ `GetBackgroundColour()`; **[source]**):
+- MSW: a child without its own background paints the nearest ancestor's **explicit** brush while
+  `HasTransparentBackground()` holds (`src/msw/window.cpp` `wxWindowMSW::MSWGetBgBrush`). Containers (`wxPanel`)
+  report transparent if an ancestor has an inheritable background (`SetBackgroundColour`, not
+  `SetOwnBackgroundColour`; `src/common/containr.cpp:162-175`); `wxStaticText`, `wxCheckBox`, `wxStaticBox`,
+  `wxStaticBitmap`, `wxHyperlinkCtrl`, book controls, MSW `wxRadioButton`/`wxSlider` always do.
+- macOS: a bare window with the default `wxBG_STYLE_ERASE` is cleared with its **own** `GetBackgroundColour()`
+  (`wxWindowMac::MacDoRedraw`, `src/osx/window_osx.cpp:1950-1983`; the `wxWindowDC` background is
+  `GetBackgroundColour()`, `src/osx/carbon/dcclient.cpp:89`) — the class default `windowBackgroundColor`, a dynamic
+  system grey.
+- GTK3: a bare `wxPanel` is theme-enabled (`src/common/panelcmn.cpp:100`) and renders its own GTK style-context
+  background (`gtk_render_background` in `wxWindowGTK::GTKSendPaintEvents`, `src/gtk/window.cpp`), which depends on
+  the theme.
+
+This is why "dark-theme bugs that only show on macOS" exist: MSW hides an unset panel behind the ancestor's brush,
+macOS paints the system grey.
+
+**Native controls that ignore colours** (**[source]**):
+
+| Port | Behaviour |
+|---|---|
+| MSW | `wxButton`/`wxToggleButton` `SetBackgroundColour`/`SetForegroundColour` switch the native button to `BS_OWNERDRAW` (`src/msw/anybutton.cpp` `wxAnyButton::MakeOwnerDrawn`, `:1324-1390`) — the colour works but native theming is gone. `wxCheckBox`/`wxRadioButton` foreground makes them owner-drawn when themes are active (`src/msw/control.cpp` `MSWMakeOwnerDrawnIfNecessary`); 3.3.2 fixed checkbox accessibility in that mode (`docs/changes.txt:299-300`). Static-text-like children paint the ancestor brush only if that ancestor's background is inheritable. |
+| macOS | `SetBackgroundColour` reaches the NSView only if it `respondsToSelector:setBackgroundColor:` and the style is not `wxBG_STYLE_TRANSPARENT` (`src/osx/cocoa/window.mm:3514-3531`): **NSButton (`wxButton`) ignores the background colour**. Foreground uses `setTextColor:` when the view has it (`:3885-3887`); stock NSButton has none. `wxStaticText` is an NSTextField with `setDrawsBackground:NO` — its background is never painted (`src/osx/cocoa/stattext.mm:154`). `wxTextCtrl`'s `setEnabled:` resets the text colour: multi-line (`wxNSTextView`) always, to `controlTextColor`/`disabledControlTextColor`; single-line (`wxNSTextField`) when it does not draw its background, to `controlTextColor`/`secondarySelectedControlColor` (`src/osx/cocoa/textctrl.mm`). |
+| GTK3 | `SetBackgroundColour/SetForegroundColour/SetFont` install a per-widget CSS provider `*{color:..;background:..;font:..}` at `GTK_STYLE_PROVIDER_PRIORITY_APPLICATION` (`src/gtk/window.cpp` `wxWindowGTK::GTKApplyStyle`); `wxButton`/`wxCheckBox` apply it to their inner label too (`src/gtk/button.cpp:325-335`, `src/gtk/checkbox.cpp:233-237`). User CSS (priority USER) can still override. |
+| GTK2 | colours applied with `gtk_widget_modify_style` — pixmap-engine themes may ignore them. |
+
+**OrcaSlicer — `Utils/MacDarkMode.mm`** installs process-wide Objective-C categories/swizzles that affect *every*
+window, so stock-wx advice about NSTextField/NSButton colours differs in Orca:
+- every `NSTextField` is created with `drawsBackground = false` (category `NSTextField (drawsBackground)`), so with
+  the `textctrl.mm` rule above a custom text colour is lost on every `Enable()` and the background is not painted;
+- `NSButton (NSButton_Extended)` adds `textColor`/`setTextColor:` (via the attributed title), which is what makes
+  `wxButton`/`wxCheckBox` foreground colours work on macOS; `setBezelStyle:` forces bordered (except shadowless
+  square); focus rings are off for NSButton and NSTextField; `NSTableHeaderCell`'s font is forced to `Label::sysFont(13)`;
+- the main-frame title text colour is forced (`set_title_colour_after_set_title`; `NSTextField (textColor)` swizzle
+  for that one field), and `set_miniaturizable` makes the titlebar transparent over a dark NSWindow background.
+
+Orca's widgets work with these limits: `Label` sets keyed colours (`SetForegroundColour("#262E30")`, background =
+`StaticBox::GetParentBackgroundColor(parent)`) so the walk can map them — commit d408db2fde replaced `wxStaticText`
+with `Label` to fix Linux dark mode this way; `TextInput::Enable` re-applies the inner control's background and
+foreground from its `StateColor`s after enabling; `StaticBox::Create` copies the parent background into its own wx
+background (a `StaticBox` parent's `background_color.defaultColor()`, the midpoint of a gradient, else
+`parent->GetBackgroundColour()`), used for the corners outside the rounded rectangle.
+
+**Pitfalls**
+
+- **Rule:** Give every `wxPanel`/`wxScrolledWindow` you create an explicit palette background (typically
+  `SetBackgroundColour(*wxWHITE)`), even when white "already looks right".
+  **Why:** the walk re-keys a background only if it is a `gDarkColors` key. A bare panel paints its class default
+  (`wxSYS_COLOUR_BTNFACE`; on macOS the appearance-dependent `windowBackgroundColor`), which is never a key, so it
+  shows as a system-grey patch against Orca's palette in either theme. MSW hides this by painting the ancestor's
+  explicit brush, so it surfaces on macOS. An explicit palette colour is the key that lets the walk re-map it in
+  both directions.
+  ```cpp
+  wxPanel* p = new wxPanel(parent);   // Wrong: unkeyed; macOS shows system grey, not #2D2D31 / #FFFFFF
+  wxPanel* p = new wxPanel(parent);
+  p->SetBackgroundColour(*wxWHITE);   // Right: #FFFFFF is a key → #2D2D31 in dark
+  ```
+  Cite: f7f0c82abb / 90ecdb8f03 (`HMSPanel.cpp`, `StatusPanel.cpp`, `UpgradePanel.cpp`,
+  `DeviceTab/wgtDeviceNozzleRack*.cpp`, `SelectMachine.cpp`); `src/common/wincmn.cpp:1524-1553`.
+- **Rule:** Set the parent's background before creating Orca widgets in it.
+  **Why:** `StaticBox`, `Label`, `CheckBox`, `SwitchButton`, `RadioGroup` snapshot the parent background at construction; a later
+  change leaves wrong-coloured corners/label backgrounds.
+- **Rule:** Set colours on the control itself, not on an ancestor.
+  **Why:** background never inherits; foreground inherits only at creation, from the immediate parent, and not for
+  `wxPanel`, `wxTextCtrl`, buttons or item controls.
+  ```cpp
+  // Wrong: dlg->SetForegroundColour(c);   // after children exist, or on a wxPanel above them
+  // Right: label->SetForegroundColour(c);  // per control
+  ```
+- **Rule:** Re-apply text-control colours after every `Enable()`.
+  **Why:** macOS NSTextField/NSTextView reset their text colour in `setEnabled:`, and Orca's swizzle makes every
+  NSTextField non-background-drawing. `TextInput::Enable` is the model.
+- **Rule:** Never style a native `wxButton` with `SetBackgroundColour`; use `Button` + `SetStyle(...)`.
+  **Why:** MSW turns the native button owner-drawn (theming gone); macOS ignores the background colour.
+
+## StateColor
+
+`StateColor` (`Widgets/StateColor.hpp/.cpp`) is an ordered list of `(wxColour, int mask)` pairs plus the global
+light→dark map `gDarkColors`. Orca widgets (`StaticBox` and subclasses) take `StateColor`s and resolve them at paint
+time.
+
+**Contract** (from the code):
+- State bits: `Normal = 0`, `Enabled = 1`, `Checked = 2`, `Focused = 4`, `Hovered = 8`, `Pressed = 16`; the negations
+  `Disabled`, `NotChecked`, `NotFocused`, `NotHovered`, `NotPressed` are the same bits `<< 16` and mean "bit must be
+  off". Masks OR together (`StateColor::Checked | StateColor::Enabled`). The `(int)` cast on the enum is required
+  for `std::pair` deduction.
+- `colorForStates(states)` returns the **first** entry whose on-bits are all set and off-bits all clear;
+  `takeFocusedAsHovered_` (default true) lets a `Hovered` entry also match `Focused` (`setTakeFocusedAsHovered(false)`
+  to style focus separately). No match → `wxColour(0, 0, 0, 0)` (transparent black — black through GDI).
+- `colorForStates()` passes the result through the dark map when StateColor's `gDarkMode` is set, **at paint time**:
+  owner-drawn widgets switch theme on `Refresh()` with no extra code. `colorForStatesNoDark()` skips mapping;
+  `defaultColor()` = `colorForStates(0)`.
+- Single-colour ctors `StateColor(wxColour)`, `(wxString)`, `(unsigned long)` store a `Normal` entry. Integer forms
+  (`StateColor(unsigned long)`, `append(unsigned long, int)`, `std::make_pair(0x009688, …)`) are **`0xRRGGBB`**; an
+  alpha byte of 0 is treated as opaque — the opposite of `wxColour(unsigned long)`.
+- `gDarkColors` is a `std::map` ordered by `wxColour::GetRGBA()`: an **exact RGBA** match. Non-opaque or near-miss
+  colours never map. Examples: `#FFFFFF→#2D2D31`, `#009688→#00675b`, `#262E30→#EFEFF0`, `#DFDFDF→#3E3E45`,
+  `#D4D4D4→#4D4D54`, `#DBDBDB→#4A4A51`, `#000000→#FFFFFE`, `#F8F8F8→#36363C`, `#F1F1F1→#36363B`, `#EEEEEE→#4C4C55`,
+  `#6B6B6B→#818183`, `#ACACAC→#65656A`, `#363636→#B2B3B5`, `#F0F0F1→#333337`. Near-white variants (`#FFFFFE` as the
+  twin of `#000000`, `#FEFFFF`, `#FFFEFE`) exist so the reverse map stays usable. `#F0F0F0`, `#333333`, `#5C5C5C`
+  are not keys.
+- Static helpers: `SetDarkMode`, `darkModeColorFor` (returns its input unless `gDarkMode` is set), `lightModeColorFor`
+  (the reverse map, built once with `emplace` so the smallest `GetRGBA()` key wins; not gated by `gDarkMode` — it
+  maps in either mode), `GetDarkMap()`, LAB math
+  `GetLAB`, `GetLightness`, `SetLightness`, `LightenDarkenColor`, `GetColorDifference`/`LAB_Delta_E`.
+
+**Reverse-map and chaining hazards** (exact consequences of the table):
+- duplicate dark targets collapse: `#E8E8E8 → #3E3E45 → #DFDFDF`; `#EDFAF2 → #283232 → #E5F0EE`;
+- legitimate light colours that equal some dark twin are rewritten by the light walk: `#909090 → #6B6A6A`,
+  `#D9D9D9 → #FFFEFE`, `#808080 → #2B3436`, `#FFFFFE → #000000`;
+- the dark map chains when a value is also a key: a second dark pass takes `#FFFEFE → #D9D9D9 → #27272A`.
+
+**Usage.**
+```cpp
+StateColor bg(std::pair{wxColour("#DFDFDF"), (int) StateColor::Disabled},
+              std::pair{wxColour("#D4D4D4"), (int) StateColor::Pressed},
+              std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered},
+              std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal});   // Normal LAST
+box->SetBackgroundColor(bg);   // StaticBox API ("Color"), not wxWindow::SetBackgroundColour
+// in doRender(wxDC& dc): dc.SetBrush(background_color.colorForStates(state_handler.states()));
+```
+How a widget attaches and repaints its `StateColor`s (`StateHandler`, `doRender`) is in
+`references/painting-custom-widgets.md`; per-widget colour setters are in `references/orca-widgets.md`.
+
+**OrcaSlicer.** Pick existing keys for new UI. `HyperLink` deliberately uses `#009687` (not a key) so its teal is
+*not* mapped. `Button::SetStyle` detects dark mode with `darkModeColorFor("#FFFFFF") != "#FFFFFF"` for the focus
+border, and `Button::Rescale()` re-runs `SetStyle` (when a style was set), so calling `Rescale()` on a theme change
+refreshes it. A `Button` never given a style keeps its constructor colours, whose `*wxLIGHT_GREY` hover/disabled
+entries are not keys — always call `SetStyle()`.
+`DialogButtons` sets its own background with `darkModeColorFor(wxColour("#FFFFFF"))`. Widgets that take a plain
+`wxColour` (e.g. `ProgressBar`) paint it unmapped — map it yourself. `StaticLine` maps line/text colours at paint time.
+
+**Pitfalls**
+
+- **Rule:** Most specific entries first, `Normal` last.
+  **Why:** `Normal` (mask 0) matches every state, so entries after it are dead. Check the order of any table you copy;
+  existing tables are not guaranteed correct (an `Enabled` entry after `Normal` never matches).
+  ```cpp
+  // Wrong: hover never shows
+  StateColor c(std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal},
+               std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered});
+  // Right:
+  StateColor c(std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered},
+               std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal});
+  ```
+  Cite: `Widgets/StateColor.cpp` `StateColor::colorForStates`.
+- **Rule:** Negate with the `Not*` enumerators, never `~`.
+  **Why:** `(int) Hovered | NotFocused` = `0x40008` means "hovered and not focused"; `(int) Hovered | ~Focused` =
+  `0xFFFFFFFB` sets every on-bit and never matches.
+- **Rule:** Do not pass data colours (filament/extruder/user colours) through `darkModeColorFor` or leave them as
+  window backgrounds the walk visits; paint them in a paint handler or re-set them after the walk.
+  **Why:** a white filament `#FFFFFF` maps to `#2D2D31`.
+- **Rule:** Never use a dark-twin value as a light-mode colour (`#FFFFFE`, `#D9D9D9`, `#909090`, `#808080`, …).
+  **Why:** the light walk rewrites it through the reverse map.
+
+## Orca dark-mode state
+
+| State | Set by | Read by |
+|---|---|---|
+| app_config `dark_color_mode` ("1"/"0") | Windows: the Preferences checkbox (`PreferencesDialog::create_item_darkmode`, `#ifdef _WIN32`); `AppConfig::set_defaults` sets `"0"` when empty (`#ifdef _WIN32`). macOS/Linux: overwritten from `GetAppearance().IsDark()` at startup (`GUI_App::on_init_inner`, `#ifndef __WINDOWS__`) and by `update_dark_config()` on every SYS_COLOUR event. | `GUI_App::dark_mode()` (non-macOS); `Plater::priv::on_change_color_mode` and other GL/web code that reads the key directly — new code calls `dark_mode()` instead |
+| `GUI_App::m_is_dark_mode` | `GUI_App::Update_dark_mode_flag()` (= `dark_mode()`) | `GUI_App::UpdateDarkUI` (the walk) only |
+| `StateColor` file-static `gDarkMode` | `StateColor::SetDarkMode`, called only from `GUI_App::init_label_colours()` | `darkModeColorFor`, `colorForStates` |
+| NppDarkMode `g_darkModeEnabled` (Windows) | `NppDarkMode::InitDarkMode` / `SetDarkMode` | title bars, explorer theme, scrollbars, DVC header |
+| wx's own MSW mode | `MSWEnableDarkMode(DarkMode_Auto)` → follows the **system app mode** | wx internals, `IsDark()`, `GetColour()` |
+
+`GUI_App::dark_mode()` (static, recomputed every call) is the only query GUI code uses:
+- macOS: `wxPlatformInfo::Get().CheckOSVersion(10, 14) && mac_dark_mode()` (10.12/10.13 gave false positives);
+  `mac_dark_mode()` (`Utils/MacDarkMode.mm`) reads the `AppleInterfaceStyle` user default == "Dark" — the **system**
+  preference. The config key is ignored. wx's `IsDark()` (which feeds `update_dark_config()`) reads
+  `[NSApp effectiveAppearance]`; the two normally agree.
+- elsewhere: `"1"` → true, `"0"` → false, otherwise `check_dark_mode()` (`GUI_Utils.cpp`:
+  `wxSystemSettings::GetAppearance().IsDark()`). On Windows the default makes the fallback effectively unreachable;
+  on Linux the key is only empty before `on_init_inner` writes it, so "dark" means "the GTK theme's window colours
+  are dark".
+
+`check_dark_mode()` keeps `IsDark()` deliberately; switching it to `AreAppsDark()`/`IsSystemDark()` is not a required
+3.3 migration: off MSW the three are identical (`src/common/settcmn.cpp:71-84`), and on MSW it is reached only for an
+unset key and for Windows menu bitmaps, where matching wx's own menu state is the point.
+
+There is **no "follow system" setting and no in-app override on macOS/Linux**: the app mirrors the OS and re-syncs
+the config on each SYS_COLOUR event. `SUPPORT_DARK_MODE` is defined unconditionally in `libslic3r/AppConfig.hpp`, and
+`_MSW_DARK_MODE` is defined to 1 on every platform in `GUI_App.hpp` — neither is a platform gate. Windows-only code
+sits under `__WINDOWS__`/`_WIN32` (NppDarkMode sources are added only `if (WIN32)` in `src/slic3r/CMakeLists.txt`).
+The other theme-dependent `GUI_App` colours (`m_color_label_modified`, `m_color_label_sys` `#363636`/`#B2B3B5`,
+`m_color_label_default`, `m_color_highlight_default` `#F1F1F1`/`#36363B`, `m_color_window_default`, button
+label/background) are computed by `init_label_colours()`.
+
+**Pitfalls**
+
+- **Rule:** An explicit `dark_color_mode` wins in both directions; `check_dark_mode()` is a last-resort fallback for
+  an unset key.
+  **Why:** on Windows, once `MSWEnableDarkMode(DarkMode_Auto)` is active, `IsDark()` reports the system app mode, so
+  an explicit "0" falling through to it made dark → light switching silently fail.
+  ```cpp
+  // Wrong: explicit "0" falls through to the contaminated system query
+  return app_config->get("dark_color_mode") == "1" ? true : check_dark_mode();
+  // Right: explicit choice wins in both directions
+  const auto& val = app_config->get("dark_color_mode");
+  if (val == "1") return true;
+  if (val == "0") return false;
+  return check_dark_mode();   // unset key only
+  ```
+  Cite: 7d7f26ed69 (`GUI_App.cpp`, `GUI_App::dark_mode`, the non-Apple branch).
+- **Rule:** Any new code path that changes the theme first sets `dark_color_mode` (Windows: `app_config->set` +
+  `save()`; macOS/Linux: `update_dark_config()`), then refreshes the cached state: `wxGetApp().Update_dark_mode_flag()`
+  (`m_is_dark_mode`, read by the walk), `wxGetApp().init_label_colours()` (StateColor's `gDarkMode` and the label
+  colours) and, on Windows, `wxGetApp().force_colors_update()` (NppDarkMode's `g_darkModeEnabled` via
+  `NppDarkMode::SetDarkMode(dark_mode())`, the main frame's title bar, and the walk flag `update_ui_from_settings()`
+  consumes). `dark_mode()` itself is live; wx's own MSW mode follows the system and is not set by Orca.
+  **Why:** they are updated at different moments; `update_dark_config()` does not touch StateColor's flag — for the
+  main frame that happens in `MainFrame::on_sys_color_changed` — and after startup only `force_colors_update()` calls
+  `NppDarkMode::SetDarkMode`.
+
+## The Update*DarkUI walk
+
+`GUI_App` helpers (`GUI_App.hpp/.cpp`):
+
+| Helper | Does |
+|---|---|
+| `UpdateDarkUI(win, highlited = false, just_font = false)` | One window. `just_font` is unused. Skips `wxBU_AUTODRAW` buttons (`wxButton` or Orca `Button`). Windows only: a `wxButton` with id `wxID_OK`/`wxID_CANCEL` gets `wxNO_BORDER`, palette background/foreground (→ owner-drawn) and four hover/focus handlers **bound again on every call**. Then, using `m_is_dark_mode` (not `dark_mode()`): **dark** — `bg = darkModeColorFor(GetBackgroundColour())`, set only if it changed (exact key); `fg = darkModeColorFor(GetForegroundColour())`, then if ΔE(bg, fg) < 10 → LAB L = 90, if L(fg) < 45 → L = 70, and **fg is always set**; **light** — `lightModeColorFor` on background and foreground, each set only if changed. |
+| `update_dark_children_ui(win)` (file-static) | recursive over `GetChildren()` at call time: a `ScalableButton` gets `ScalableButton::UpdateDarkUI()` (= `msw_rescale()`: `UpdateDarkUI(this, m_has_border)` plus re-rasterized icons), anything else `UpdateDarkUI(child)`. `GetChildren()` includes owned TLWs, so dialogs parented to the window are walked too. |
+| `UpdateDarkUIWin(win)` | the walk. |
+| `UpdateDlgDarkUI(dlg)` / `UpdateFrameDarkUI(frame)` | Windows: `NppDarkMode::SetDarkExplorerTheme` + `SetDarkTitleBar` on the HWND (both follow Orca's mode in both directions); then the walk. |
+| `UpdateDVCDarkUI(dvc, highlited)` | **Windows-only body** (no-op on macOS/Linux): `UpdateDarkUI`, dark list header via `NppDarkMode::SetDarkListViewHeader`, header attr text colour `NppDarkMode::GetTextColor()`, `SetAlternateRowColour(m_color_highlight_default)` for `wxDV_ROW_LINES`, forces `wxBORDER_SIMPLE`. |
+| `UpdateAllStaticTextDarkUI(parent)` | **Windows-only body**: `UpdateDarkUI(parent)` and `m_color_label_default` on direct `wxStaticText` children. |
+
+Consequences: an unmapped background stays as it is; an unmapped dark foreground becomes grey (L≈70) instead of
+dark-on-dark; every visited window ends with an explicit foreground (on MSW that makes raw buttons/checkboxes
+owner-drawn); dark → light is lossy (lifted greys are not restored; shared twins collapse, see
+[StateColor](#statecolor)); the walk only calls `Set{Background,Foreground}Colour`, so `wxPaintDC` painting is
+unreachable by it. The source comment on `UpdateDarkUIWin` ("Don't use this function for Dialog contains
+ScalableButtons") is stale: all three entry points run the same `update_dark_children_ui`, which already handles
+`ScalableButton`; the only difference is the Windows HWND theming. Use `UpdateDlgDarkUI` for dialogs because of
+that theming.
+
+App-wide passes: `MainFrame`'s constructor ends with `UpdateDarkUIWin(this)` (on all platforms); a theme switch runs
+`update_dark_children_ui(mainframe)` from `GUI_App::update_ui_from_settings`; the lazily built main-window tabs re-run
+`UpdateDarkUIWin(this)` after insertion. Everything created later themes itself.
+
+Raw wx controls do not follow Orca's mode by themselves (on Windows wx themes native controls by the *system* app
+mode, see [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings)). When one cannot
+be replaced by an Orca widget, make it dark-safe through the walk (`UpdateDarkUI(ctrl)` for a single control created
+after the pass, `UpdateDlgDarkUI(dlg)` for its dialog) or with explicit `darkModeColorFor()` colours.
+
+**Pitfalls**
+
+- **Rule:** Theme a dialog with `UpdateDlgDarkUI`, not `UpdateDarkUI`.
+  **Why:** `UpdateDarkUI` touches one window; children keep light defaults and the Windows title bar stays light.
+  ```cpp
+  // Wrong:
+  wxGetApp().UpdateDarkUI(this);
+  // Right:
+  wxGetApp().UpdateDlgDarkUI(this);
+  ```
+  Cite: 465f634988 (`AMSMaterialsSetting.cpp` `AMSMaterialsSetting::Show`).
+- **Rule:** After building a runtime-created subtree (widgets constructed after the initial pass), end the
+  constructor with one `wxGetApp().UpdateDarkUIWin(this)`; for an ad-hoc `wxDialog`, call
+  `wxGetApp().UpdateDlgDarkUI(&dlg)` after all children exist and before `ShowModal()` (the order relative to `Fit()`
+  does not matter).
+  **Why:** the app-wide pass themes only windows that existed when it ran; HMS notify items, device
+  firmware/nozzle panels, one-off confirmation dialogs appear with light defaults in dark mode on every platform.
+  One subtree walk also themes child labels and beats sprinkling per-widget `darkModeColorFor` calls.
+  ```cpp
+  // Wrong: dialog built and shown with hard-coded light colours only
+  dlg.SetSizer(main_sizer); dlg.Fit(); dlg.ShowModal();
+  // Right:
+  dlg.SetSizer(main_sizer); dlg.Fit();
+  wxGetApp().UpdateDlgDarkUI(&dlg);
+  dlg.ShowModal();
+  ```
+  Cite: f7f0c82abb (`HMSPanel.cpp`, `DeviceTab/uiDeviceUpdateVersion.cpp`, `DeviceTab/wgtDeviceNozzleSelect.cpp`,
+  `SelectMachine.cpp` `SelectMachineDialog::show_timelapse_storage_dialog`).
+- **Rule:** Apply deliberate non-palette colours after the walk (and again on theme change).
+  **Why:** in dark mode the walk rewrites every visited window's foreground — white text on an accent chip becomes
+  mid-grey.
+  ```cpp
+  wxGetApp().UpdateDlgDarkUI(this);
+  m_badge->SetForegroundColour(*wxWHITE);   // after the walk
+  ```
+- **Rule:** Run the dialog walk once per theme state; do not call it from paint or size handlers.
+  **Why:** the map chains (`#FFFEFE → #D9D9D9 → #27272A`) and the Windows OK/Cancel branch stacks handlers per call.
+
+## NppDarkMode (Windows)
+
+Vendored Notepad++ dark-mode code in `src/slic3r/GUI/dark_mode.cpp/.hpp` and `src/slic3r/GUI/dark_mode/*.hpp`,
+compiled only on Windows. Namespace `NppDarkMode`:
+
+| Function | Does |
+|---|---|
+| `InitDarkMode(bool dark, bool sys_menu)` | loads the uxtheme entry points, records the system-menu setting, `SetDarkMode(dark)`. |
+| `SetDarkMode(bool)` | sets `g_darkModeEnabled`; `AllowDarkModeForApp(dark)` → `SetPreferredAppMode(ForceDark|ForceLight)` (Windows 1903+) or `AllowDarkModeForApp` (1809); flushes menu themes when the system-menu setting is on; scrollbar fix. |
+| `SetDarkTitleBar(HWND)` | allows dark for the window per `IsEnabled()`, refreshes the title-bar colour, applies the explorer theme. |
+| `SetDarkExplorerTheme(HWND)` | `SetWindowTheme(hwnd, IsEnabled() ? L"DarkMode_Explorer" : nullptr, nullptr)`. |
+| `SetDarkListViewHeader(HWND)` | dark `ItemsView` theme on a list header. |
+| `GetTextColor()` | `0xF0F0F0` when enabled, else `wxSYS_COLOUR_WINDOWTEXT` — which is wx's dark-palette `0xe0e0e0` when the Windows app mode is dark and Orca is light **[source]**. |
+
+Unlike wx's MSW dark mode it switches live: every function follows `g_darkModeEnabled` in both directions, so
+re-running them on existing HWNDs re-themes them. `GUI_App::force_colors_update()` re-arms it
+(`NppDarkMode::SetDarkMode(dark_mode())`, `SetDarkTitleBar(mainframe)`); `UpdateDlgDarkUI`/`UpdateFrameDarkUI`
+apply it per TLW. Its `#if wxVERSION_NUMBER < 3300` block that themed the tooltip window is dead:
+`wxToolTip::GetToolTipCtrl()` is private in 3.3 (`include/wx/msw/tooltip.h:92`), and wx dark-enables the
+tooltip window itself through `wxMSWDarkMode::AllowForWindow`, so tooltips follow wx's mode (the system app
+mode), not Orca's **[source]** (`src/msw/tooltip.cpp:321`). `update_dark_ui(wxWindow*)` (`GUI_Utils.cpp`, `_WIN32`), which `DPIAware`'s constructor and
+`force_color_changed()` call, has an empty body.
+
+## Runtime theme switch and re-applying colours
+
+```text
+Startup (GUI_App::on_init_inner): init_label_colours() [StateColor::SetDarkMode] → Update_dark_mode_flag()
+  → (non-Windows) dark_color_mode := GetAppearance().IsDark()
+  → (Windows) MSWEnableDarkMode(DarkMode_Auto); NppDarkMode::InitDarkMode(dark_mode(), sys_menu)
+  MainFrame ctor ends with UpdateDarkUIWin(this)
+
+Windows — Preferences "Enable dark Mode" (PreferencesDialog::create_item_darkmode, the only toggle):
+  1 set + save dark_color_mode   2 Update_dark_mode_flag()
+  3 force_colors_update(): NppDarkMode::SetDarkMode(dark_mode()), SetDarkTitleBar(mainframe), m_force_colors_update
+  4 update_ui_from_settings():
+       mainframe->force_color_changed() [_WIN32: update_dark_ui (empty) + MainFrame::on_sys_color_changed()]
+       update_scrolls(mainframe), update_scrolls(&m_settings_dialog)
+       update_dark_children_ui(mainframe)            (all platforms when m_force_colors_update)
+  5 PreferencesDialog::set_dark_mode() → UpdateDlgDarkUI(this)
+  6 wxPostEvent(plater, EVT_GLCANVAS_COLOR_MODE_CHANGED) → Plater::priv::on_change_color_mode (GL canvases, sidebar)
+
+macOS / Linux — system switch: wxEVT_SYS_COLOUR_CHANGED at every DPIAware TLW (order undefined)
+  → update_dark_config() [config + m_is_dark_mode] → on_sys_color_changed() → Skip()
+  MainFrame::on_sys_color_changed(): init_label_colours() → force_colors_update() → update_ui_from_settings()
+       [update_dark_children_ui(mainframe)] → fan-out below
+  Plater::priv::on_apple_change_color_mode → GL canvases
+```
+
+At startup `init_label_colours()` and `Update_dark_mode_flag()` run before the key is rewritten from the system, and
+the later re-check only fires when `dark_mode()` changes after that rewrite. On Linux (where `dark_mode()` reads the
+key) a start after the GTK theme changed while Orca was closed therefore leaves StateColor's flag and
+`m_is_dark_mode` on the previous session's value — including for the `MainFrame` constructor's walk — until the next
+`MainFrame::on_sys_color_changed`. **[source; consequence inferred from the call order in
+`GUI_App::on_init_inner`, not observed]**
+
+`MainFrame::on_sys_color_changed` is the **registry for long-lived UI**: `DiffPresetDialog::if_built()`,
+`m_tabpanel->Rescale()`, `m_param_panel->msw_rescale()`, `plater()->sys_color_changed()` (→ `Sidebar::sys_color_changed`
+→ …), `MonitorPanel::when_built`, `CalibrationPanel::when_built`, every `Tab::sys_color_changed()` (tabs, model tabs,
+plate tab), `MenuFactory::sys_color_changed(m_menubar)` (its body is compiled out with `#if 0`, so menu-bar item
+icons are not re-rasterized; the cached context menus are, via `Plater::sys_color_changed` →
+`MenuFactory::sys_color_changed()`), `WebView::RecreateAll()`, then `Refresh()`. A cached,
+hidden or lazily built window must be added here or chained from something here: the walk reaches dialogs parented
+to the main frame (they are in `GetChildren()`), but only their colours (and `ScalableButton` icons) — not their
+title bar, `ScalableBitmap`-based images or `on_sys_color_changed()`. Commit bab3c72e4f fixed the compare dialog keeping old row colours by calling
+`diff_dialog.on_sys_color_changed()` from this fan-out (the dialog is not destroyed on close).
+
+Who gets what on a switch:
+
+| Window | Windows (Preferences) | macOS/Linux (system) |
+|---|---|---|
+| MainFrame subtree | walk + fan-out | walk + fan-out |
+| Open dialog parented to the main frame | walk only (Preferences re-themes itself) | its own `on_sys_color_changed()` via the OS event + the walk |
+| Hidden cached dialog parented to the main frame | walk only, unless chained in the fan-out | walk + its own handler (the OS event reaches every TLW) |
+| Modal dialogs (`dialogStack`, via `DPIAware::ShowModal`) | cannot be open across a Preferences change | live |
+
+**What a dialog must do to survive a toggle:**
+1. Derive from `DPIDialog` (`DPIAware<wxDialog>`, `GUI_Utils.hpp`; `on_sys_color_changed()` is a protected virtual
+   no-op by default) and use palette colours / Orca widgets.
+2. End the constructor with `wxGetApp().UpdateDlgDarkUI(this)` — it also sets the Windows dark title bar and
+   explorer theme the children walk alone does not.
+3. Override `on_sys_color_changed()` to re-create `ScalableBitmap`s (`msw_rescale()` + re-`SetBitmap`), re-pick
+   `*_dark` icon names, re-apply construction-time and owner-drawn colours, call widget `Rescale()` where styles
+   depend on the theme, then `Refresh()`. It runs on macOS/Linux from the OS event; on Windows only if the main-frame
+   fan-out calls it.
+4. If it outlives a show (cached singleton, lazily built), register it in `MainFrame::on_sys_color_changed`.
+
+**Pitfalls**
+
+- **Rule:** Never hand a literal light-theme colour straight to `SetForegroundColour`/`SetBackgroundColour`/`wxPen`/`wxBrush`;
+  wrap it in `StateColor::darkModeColorFor(...)` when it is a `gDarkColors` key, or branch on
+  `wxGetApp().dark_mode()` with an explicit dark counterpart when it is not.
+  **Why:** `darkModeColorFor` is an exact RGBA lookup; an unmapped colour (`#F0F0F0`, `#333333`, `#5C5C5C`) passes
+  through unchanged and renders as a light patch, or — set directly with no walk after it — dark-on-dark text. This
+  also applies to owner-drawn `wxPaintDC` painting (popup borders/fills), which the walk cannot reach.
+  ```cpp
+  label->SetForegroundColour(wxColour("#009688"));                     // Wrong: stays light-theme teal
+  label->SetForegroundColour(StateColor::darkModeColorFor("#009688"));  // Right: → #00675b in dark
+  // unmapped colour: branch explicitly
+  msg->SetForegroundColour(wxGetApp().dark_mode() ? wxColour("#EFEFF0") : wxColour(0x33, 0x33, 0x33));
+  ```
+  Cite: f7f0c82abb (`SelectMachine.cpp` `SelectMachineDialog::Enable_Auto_Refill`, `show_timelapse_folder_popup`;
+  `Plater.cpp` `HoverLabel`).
+- **Rule:** Any colour chosen at construction time (chip backgrounds, per-state label colours, `dark_mode()`-dependent
+  picks) is re-applied on a live switch: override `on_sys_color_changed()` (DPIDialog/DPIFrame) or add a
+  `sys_color_changed()` method that the owner's `sys_color_changed()` chains to, ending with `Refresh()`.
+  **Why:** `dark_mode()` is live but a value computed once in a constructor is not; the walk fixes mapped colours only,
+  not unmapped colours or platform-conditional picks.
+  ```cpp
+  // Wrong: colours set once in the ctor, never again
+  HoverLabel(...) { SetBackgroundColour(extruder_group_chip_bg()); ... }
+  // Right: also re-apply on theme switch, chained from the parent
+  void HoverLabel::sys_color_changed()   { SetBackgroundColour(extruder_group_chip_bg()); /* label fg */ Refresh(); }
+  void ExtruderGroup::sys_color_changed() { if (hover_label) hover_label->sys_color_changed(); ...; Refresh(); }
+  void Sidebar::sys_color_changed()       { ...; for (auto* ext : extruders) ext->sys_color_changed(); }
+  ```
+  Cite: f7f0c82abb (`Plater.cpp`: `HoverLabel::sys_color_changed`, `ExtruderGroup::sys_color_changed`,
+  `Sidebar::sys_color_changed`).
+- **Rule:** In a dialog's `on_sys_color_changed()` that derives colours through `darkModeColorFor`/`StateColor`,
+  call `wxGetApp().init_label_colours()` first.
+  **Why:** `darkModeColorFor` uses StateColor's flag, which only `init_label_colours()` refreshes (startup and
+  `MainFrame::on_sys_color_changed`). On macOS each NSWindow delivers the event from its own KVO with no defined
+  order, so a dialog handler can run before the main frame's and see the old flag. **[source; the ordering risk is
+  inferred, not observed]**
+
+## Dark-mode icons
+
+Icons are SVGs in `resources/images/` (a PNG of the same name is only a fallback, with no dark substitution), named
+without extension, rasterized by Orca itself (wx has no SVG
+support in Orca's build — see `references/dpi-bitmaps-fonts.md` for sizing, `ScalableBitmap` and `BitmapCache`
+mechanics). Dark mode reaches icons in two regimes:
+
+1. **Palette substitution.** `create_scaled_bitmap()` (`wxExtensions.cpp`) passes `wxGetApp().dark_mode()` to
+   `BitmapCache::load_svg`, which text-replaces palette colours in the SVG before nanosvg parses it. An SVG drawn
+   purely in substitution colours is dark-correct automatically.
+2. **`*_dark` asset variants**, chosen by name in code, for everything else.
+
+**Substitution table** (`BitmapCache::load_svg`; replacement by `BitmapCache::nsvgParseFromFileWithReplace`):
+
+| Mode | Replacements |
+|---|---|
+| light | `"#00FF00"` → `"#52c7b8"`; unquoted `#949494` → `#7C8282` (icon line colour) |
+| dark | `"#262E30"` → `"#EFEFF0"` and unquoted `#262E30` → `#EFEFF0`; `"#323A3D"` → `"#B3B3B5"`; `"#808080"` → `"#818183"`; `"#CECECE"` → `"#54545B"`; `"#6B6B6B"` → `"#818182"`; `"#909090"` → `"#FFFFFF"`; `"#00FF00"` → `"#FF0000"`; `"#009688"` → `"#00675b"`; `"#F1F1F1"` → `"#36363B"`; unquoted `#DBDBDB` → `#4A4A51` (border), `#F0F0F1` → `#333337` (disabled background) |
+| dark, name contains `toggle_on` | additionally unquoted `#009688` → `#00675b` |
+| `new_color` argument | replaces the `"#009688"` slot in both modes (in dark mode it overrides the `#00675b` mapping too) |
+| name contains `printer_thumbnail` | no replacement at all |
+| both modes | the key `"#0x00AE42"` is malformed (contains `0x`) and matches nothing real — dead |
+
+Mechanics: literal, **case-sensitive** `boost::replace_all` over the raw file text, applied in `std::map` key order,
+so all quoted keys (`"` = 0x22) run before unquoted ones (`#` = 0x23). Quoted keys match only a full attribute value
+written `="#RRGGBB"` (`fill="#262E30"`, `stroke="…"`); they never match CSS `style="fill:#…"` or single quotes. Only the
+unquoted keys (`#262E30`, `#DBDBDB`, `#F0F0F1` in dark; `#949494` in light) reach style attributes. The cache key
+contains size, scale, `-dm`, `-gs` and the `new_color` string, so light and dark rasterizations are cached
+separately. This SVG map is separate from, and not identical to, `gDarkColors`.
+
+`create_scaled_bitmap` re-queries the mode on every call, with two exceptions: on Windows `menu_bitmap = true`
+(`create_menu_bitmap`) uses `check_dark_mode()`; `bitmap2 = true` routes to `create_scaled_bitmap2` →
+`BitmapCache::load_svg2`, which applies **no** palette substitution (only `#D9D9D9`/`fill-opacity` from
+`array_new_color`). Re-rasterizing is therefore the theme hook: `ScalableBitmap::msw_rescale()` and
+`ScalableButton::msw_rescale()` re-run `create_scaled_bitmap`, so the DPI path doubles as the theme path
+(`Tab::sys_color_changed` calls `msw_rescale()` on every cached button/bitmap and rebuilds its `wxImageList`). The
+walk reaches `ScalableButton`s (`ScalableButton::UpdateDarkUI` = `msw_rescale()`), but not `ScalableBitmap`
+members — they are not windows; their owner calls `msw_rescale()` and re-`SetBitmap`s. `ScalableBitmap::msw_rescale()`
+re-creates from name, size, grayscale and resize only: `new_color` and `bitmap2` are not re-applied.
+
+**When a `*_dark` variant + explicit re-pick is required:** whenever the icon's colours are not in the substitution
+table (multi-colour artwork, brand colours, off-palette greys like `#1F1F1F`), or the dark rendition is not a 1:1
+colour mapping of the light one. The code chooses the `_light`/`_dark` name from `wxGetApp().dark_mode()` **in code
+that re-runs on theme change**:
+```cpp
+// in the ctor AND in on_sys_color_changed():
+m_icon = ScalableBitmap(this, wxGetApp().dark_mode() ? "icon_dark" : "icon", 20);
+m_static_bmp->SetBitmap(m_icon.bmp());
+```
+The substitution still runs on whichever file is loaded, so variant files must use
+off-palette colours or the `_dark` asset is recoloured a second time (a `#262E30` in a `_dark` file still becomes
+`#EFEFF0`). Re-rasterizing a stored name (`ScalableBitmap::msw_rescale`) does **not** switch variants. Reference
+pattern: `AmsHumidityLevelList` (`AmsMappingPopup.cpp`) preloads both variants as `ScalableBitmap`s and picks
+`hum_level_img_dark`/`hum_level_img_light` by `dark_mode()` inside its render path, so a `Refresh()` re-picks.
+Alternatively re-run the name selection inside `on_sys_color_changed()`/`msw_rescale()`.
+
+**Menu bitmaps.** Menu items built with `append_menu_item(..., icon_name, ...)` use `create_menu_bitmap` (16 px,
+no window, `menu_bitmap = true`), and the icon name is remembered per item id (not on GTK). On Windows the SVG substitution
+then uses `check_dark_mode()` as its dark flag — wx's own answer,
+which is what wx uses to draw menus (its owner-drawn menu path keys on `wxMSWDarkMode::IsActive()`), so the icon
+matches the menu background even when Orca's mode differs from the Windows app mode. On a theme change Windows menu
+icons are re-rasterized by `msw_rescale_menu` (a no-op elsewhere) from the stored icon names;
+`MenuFactory::sys_color_changed()` does this for the cached context menus (the menu-bar overload is compiled out). Menus themselves are covered in
+`references/popups-menus.md`.
+
+**Pitfalls**
+
+- **Rule:** Author single-tone SVG icons in the colours `load_svg` substitutes — for near-black line art use
+  `#262E30` (uppercase), not an arbitrary near-black like `#1F1F1F` or `#333333`.
+  **Why:** recolouring is a literal, case-sensitive string replacement on a fixed palette; an off-palette fill (or
+  lowercase `#262e30`) passes through untouched and the icon disappears against the dark background. The fix is a
+  colour change in the asset; no code change.
+  ```xml
+  <path d="..." fill="#1F1F1F"/>   <!-- Wrong: not substituted, invisible in dark mode -->
+  <path d="..." fill="#262E30"/>   <!-- Right: → #EFEFF0 in dark mode -->
+  ```
+  Cite: f658aad7ca (`resources/images/ams_drying.svg`); `BitmapCache::load_svg`, `BitmapCache::nsvgParseFromFileWithReplace`.
+- **Rule:** When an icon exists as `*_light`/`*_dark` variants, select the variant matching the mode — `_dark` in
+  dark mode — and make the selection run inside code that re-executes on theme change, not once.
+  **Why:** the classic copy-paste bug returned the `_light` name in both branches, so dark mode showed
+  near-invisible light-theme humidity glyphs; nothing else corrects it because the variant files are authored
+  off-palette. A selection made only when the data changes keeps the old variant after a live switch until the data
+  changes again.
+  ```cpp
+  // Wrong: light asset in dark mode
+  if (wxGetApp().dark_mode()) return "hum_level" + std::to_string(hum_level) + "_no_num_light";
+  else                        return "hum_level" + std::to_string(hum_level) + "_no_num_light";
+  // Right:
+  if (wxGetApp().dark_mode()) return "hum_level" + std::to_string(hum_level) + "_no_num_dark";
+  else                        return "hum_level" + std::to_string(hum_level) + "_no_num_light";
+  ```
+  Cite: 668654da5f (`AMSDryControl.cpp` `get_humidity_level_img_path`); live-switch shape: `AmsHumidityLevelList`
+  (`AmsMappingPopup.cpp` `AmsHumidityLevelList::doRender`).
+- **Rule:** Do not "fix" a Windows menu icon by passing `wxGetApp().dark_mode()`.
+  **Why:** `create_menu_bitmap` deliberately follows `check_dark_mode()` (wx's menu state = the Windows app mode),
+  not Orca's setting; the icon must match the background wx draws.
+  Cite: `wxExtensions.cpp` `create_scaled_bitmap`, `create_menu_bitmap`.
+- **Rule:** Pass the real window to `create_scaled_bitmap`/`ScalableBitmap` and re-create bitmaps in
+  `on_sys_color_changed()` as well as `on_dpi_changed()`; a missing icon name throws `Slic3r::RuntimeError`.
+  Cite: `wxExtensions.cpp` `create_scaled_bitmap`.

.claude/skills/orca-wxwidgets/references/controls-dataview.md

@@ -0,0 +1,963 @@
+# Standard controls, data views and Orca's widget event contracts
+
+The value and event contracts of wx's standard controls (text, choice/combo, check/radio, spin, slider, gauge,
+static text, hyperlink, static bitmap, book controls, splitter, collapsible pane, list/tree/grid), the
+`wxDataViewCtrl` model/renderer machinery with its native-vs-generic limits, `wxVariant` and validators; then
+which events Orca's replacement widgets emit and where to bind them, and the `ObjectList` / `ObjectGrid` designs.
+Read it before writing or reviewing code that sets a control's value, reacts to its events, or touches a data view.
+
+Contents: [Rules](#rules) · [Native vs generic](#native-vs-generic-and-silent-asserts) ·
+[Programmatic changes](#events-from-programmatic-changes) · [wxTextCtrl](#wxtextctrl--wxtextentry) ·
+[wxStaticText](#wxstatictext-labels-mnemonics-markup) · [Item containers](#item-containers) ·
+[Check and radio](#check-boxes-and-radio-buttons) · [Spin, slider, gauge](#spin-controls-slider-gauge) ·
+[Book controls](#book-controls) · [Splitter, pane, hyperlink, bitmap](#splitter-collapsible-pane-hyperlink-static-bitmap) ·
+[List and tree](#wxlistctrl-wxtreectrl-image-lists) · [wxGrid](#wxgrid) · [Validators](#validators) ·
+[DVC per port](#wxdataviewctrl-native-vs-generic) · [DVC model](#wxdataviewmodel-contract) ·
+[DVC control API](#wxdataviewctrl-control-api) · [Renderers and editing](#custom-renderers-and-in-place-editing) ·
+[wxVariant](#wxvariant-with-custom-objects) · [Orca widgets](#orca-replacement-widgets-event-contracts) ·
+[ObjectList](#objectlist-objectdataviewmodel-extrarenderers) · [ObjectGrid](#objectgrid-gui_objecttable)
+
+## Rules
+
+1. Model→view refreshes use the quiet setters (`ChangeValue`, `ChangeSelection`). `wxTextEntry::SetValue`,
+   `wxBookCtrlBase::SetSelection`, `wxTreeCtrl::SelectItem` and macOS `wxDataViewCtrl::Select` *do* emit events.
+   → [Programmatic changes](#events-from-programmatic-changes)
+2. Never call `SetLabel`/`SetLabelText`/`GetLabel` on a `wxTextCtrl` to set or read its text; the setters are
+   silent no-ops in 3.3 and `GetLabel` returns the label, not the text. → [wxTextCtrl](#wxtextctrl--wxtextentry)
+3. To consume Enter, handle `wxEVT_TEXT_ENTER` (needs `wxTE_PROCESS_ENTER`) and do not `Skip()`; skipping lets
+   Enter activate the dialog's default button. → [wxTextCtrl](#wxtextctrl--wxtextentry)
+4. Call `OSXDisableAllSmartSubstitutions()` (wxOSX-only API, so inside `#ifdef __WXOSX__`) on every text control
+   that holds G-code, paths, URLs or code. → [wxTextCtrl](#wxtextctrl--wxtextentry)
+5. Do not rely on `SetHint`/`SetMaxLength` on multi-line controls (hints: MSW and GTK2 only; max length: MSW and
+   GTK only). → [wxTextCtrl](#wxtextctrl--wxtextentry)
+6. Show user data (preset, filament, file names) in labels and page titles with `SetLabelText` /
+   `wxControl::EscapeMnemonics`; quote it with `wxMarkupParser::Quote` inside markup.
+   → [wxStaticText](#wxstatictext-labels-mnemonics-markup)
+7. Typed `wxClientData` belongs to the control (never delete it); `::ComboBox` supports only untyped `void*`
+   data, which the caller owns. → [Item containers](#item-containers), [::ComboBox](#combobox)
+8. A 3-state checkbox is read with `Get3StateValue()`; every radio group starts with `wxRB_GROUP`.
+   → [Check and radio](#check-boxes-and-radio-buttons)
+9. Read spin values after the commit event (`wxEVT_SPINCTRL`), not from `wxEVT_TEXT`.
+   → [Spin](#spin-controls-slider-gauge)
+10. Book pages are created with the book as parent; in `PAGE_CHANGED` use `event.GetSelection()`.
+    → [Book controls](#book-controls)
+11. Pixel-valued setters take `FromDIP(n)` (`SetMinimumPaneSize`, `SetRowHeight`, column widths), and are
+    re-applied on rescale. → [Splitter](#splitter-collapsible-pane-hyperlink-static-bitmap), [DVC API](#wxdataviewctrl-control-api)
+12. Never dereference `begin()` of a wx selection range (`wxGrid::GetSelectedBlocks()`) without comparing it to
+    `end()`; never assume `wxDataViewCtrl::GetSelection()` is valid. → [wxGrid](#wxgrid)
+13. A `wxGridCellChoiceEditor` subclass whose `m_control` is not a `wxComboBox` overrides `Reset()`,
+    `GetValue()` and `SetParameters()` too. → [wxGrid](#wxgrid)
+14. Validators only filter keystrokes; parse and range-check values on commit. → [Validators](#validators)
+15. Never `delete` a `wxDataViewModel`; keep exactly the references you mean to own. → [DVC model](#wxdataviewmodel-contract)
+16. Change the model first, then notify (`ItemAdded`/`ItemDeleted`); after deletion use the pointer only as an
+    ID. Use `Cleared()` only when everything changed. → [DVC model](#wxdataviewmodel-contract)
+17. `GetValue` fills the variant type the column's renderer expects; a mismatch shows nothing.
+    → [DVC model](#wxdataviewmodel-contract)
+18. With `wxDV_MULTIPLE` use `GetSelections()`/`HasSelection()`; `event.GetItem()` of `SELECTION_CHANGED` may be
+    invalid on GTK and macOS. → [DVC API](#wxdataviewctrl-control-api)
+19. Bracket programmatic `Select`/`UnselectAll`/model mutations with a suppress flag that the
+    `SELECTION_CHANGED` handler checks. → [DVC API](#wxdataviewctrl-control-api)
+20. Give a data view with custom renderers an explicit `SetRowHeight` sized for the tallest content; repeat it
+    after `SetFont` and in the rescale handler. → [DVC API](#wxdataviewctrl-control-api)
+21. Never carry a `wxDataViewItem` across a deferred call without re-validating it against the model.
+    → [DVC model](#wxdataviewmodel-contract), [ObjectList](#objectlist-objectdataviewmodel-extrarenderers)
+22. Check `!v.IsNull() && v.GetType() == "<Class>"` before every `obj << variant`; `dynamic_cast` the editor in
+    `GetValueFromEditorCtrl`. → [wxVariant](#wxvariant-with-custom-objects), [Renderers](#custom-renderers-and-in-place-editing)
+23. A compound in-place editor (TextInput, `::ComboBox`) commits by calling the renderer's `FinishEditing()` /
+    `CancelEditing()` itself. → [Renderers](#custom-renderers-and-in-place-editing)
+24. On macOS, `CreateEditorCtrl` never runs natively: veto `START_EDITING`, `CallAfter` the renderer's own
+    `StartEditing`, then `SetCustomRendererPtr/Item`, all under `#ifdef __WXOSX__`.
+    → [Renderers](#custom-renderers-and-in-place-editing)
+25. Bind `::TextInput`/`::SpinInput` `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the widget itself (or its
+    `GetTextCtrl()`), never on a parent filtered by the widget's id. `::ComboBox` ignores the id passed to its
+    constructor, so bind on the combo (or `SetId()` after construction if an id filter is unavoidable).
+    → [Orca widgets](#orca-replacement-widgets-event-contracts)
+26. `::CheckBox`/`SwitchButton` emit `wxEVT_TOGGLEBUTTON`, and a handler bound on the widget itself must `Skip()`;
+    `RadioGroup::SetSelection` always emits; `SpinInput`'s `wxEVT_SPINCTRL` is a plain `wxCommandEvent`.
+    → [Orca widgets](#orca-replacement-widgets-event-contracts)
+27. Expect Orca's colours on every generic data view and `RenderText` on MSW: `ObjectList` installs a
+    process-global `wxRendererNative`. → [ObjectList](#objectlist-objectdataviewmodel-extrarenderers)
+
+## Native vs generic, and silent asserts
+
+Orca builds wx with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with `wxDEBUG_LEVEL=0`, so `wxASSERT`/`wxFAIL`
+vanish and `wxCHECK_*` returns early without a message (`include/wx/debug.h:229-231, 340-368`). Every "asserts" in
+the docs below means, in Orca, that the call silently does nothing (a `wxCHECK`) or carries on with bad state (a
+`wxASSERT`). Linux builds target GTK3 (GTK2 is only the `-DDEP_WX_GTK3=OFF` opt-out); GTK2-only behaviour is noted
+where it differs.
+
+Which implementation a control uses decides most platform differences:
+
+| Control | MSW | GTK | macOS | Cite |
+|---|---|---|---|---|
+| `wxDataViewCtrl` | generic | native `GtkTreeView` | native `NSOutlineView` | `include/wx/dataview.h:36-44` |
+| `wxBitmapComboBox` | native (owner-drawn CB) | native | generic `wxOwnerDrawnComboBox` | `include/wx/bmpcbox.h:27-28,112-119` |
+| `wxTreeCtrl` | native | generic | generic | `include/wx/treectrl.h:27-28` |
+| `wxListCtrl` | native | generic | generic | `include/wx/listctrl.h:29-34` |
+| `wxHyperlinkCtrl` | native | native | generic | `interface/wx/hyperlink.h:90` |
+| `wxGrid` | generic | generic | generic | `src/generic/grid.cpp` |
+
+## Events from programmatic changes
+
+The general wx rule is that setters do not send events. The exceptions are the bugs:
+
+| Call | Event emitted? | Cite |
+|---|---|---|
+| `wxTextEntry::SetValue(s)` | **yes**, one `wxEVT_TEXT`, even when `s` equals the current text | `interface/wx/textentry.h:539-542`; [source] `src/common/textentrycmn.cpp:236-254`, `src/msw/textctrl.cpp:1133-1145` |
+| `wxTextEntry::ChangeValue(s)` | no | `interface/wx/textentry.h:177-178` |
+| `wxTextEntry::Clear()` | yes (= `SetValue("")`) | `interface/wx/textentry.h:193-194` |
+| `wxTextCtrl::SetLabel/SetLabelText` | nothing at all (3.3) | `docs/changes.txt:111-113`; `src/common/textcmn.cpp:934-937` |
+| `SetSelection/SetStringSelection` on wxChoice, wxComboBox, wxListBox, wxRadioBox | no | `interface/wx/ctrlsub.h:102-103,126` |
+| `wxComboBox::SetValue` | `wxEVT_TEXT` if editable; none with `wxCB_READONLY` | `interface/wx/combobox.h:256-272` |
+| `wxComboBox::Popup()/Dismiss()` | DROPDOWN/CLOSEUP, except on wxOSX | `interface/wx/combobox.h:279-281,292-294` |
+| `wxCheckBox::SetValue/Set3StateValue`, `wxRadioButton::SetValue`, `wxCheckListBox::Check` | no | `interface/wx/checkbox.h:170-180`, `interface/wx/radiobut.h:117-118`, `interface/wx/checklst.h:135-137` |
+| `wxSpinCtrl[Double]::SetValue/SetRange` | no; `SetRange` may silently clamp the value | `interface/wx/spinctrl.h:186-197,220-231,432-441` |
+| `wxBookCtrlBase::SetSelection` | **yes**, PAGE_CHANGING (vetoable) + PAGE_CHANGED | `interface/wx/bookctrl.h:175-183` |
+| `wxBookCtrlBase::ChangeSelection` | no | `interface/wx/bookctrl.h:192-199` |
+| `AddPage/InsertPage(select=true)` | yes, except for the very first page | `interface/wx/bookctrl.h:256-259` |
+| `DeletePage/RemovePage` | yes if the selection shifts, except when deleting the last page | `interface/wx/bookctrl.h:286-295` |
+| `wxTreeCtrl::SelectItem` | **yes**, SEL_CHANGING (vetoable) + SEL_CHANGED | `interface/wx/treectrl.h:866-868` |
+| `wxDataViewCtrl::Select/SetSelections/UnselectAll` | generic: no; GTK: suppressed; **macOS: `SELECTION_CHANGED`** | [source] `src/generic/datavgen.cpp:6396-6412`; `src/gtk/dataview.cpp:5268-5282`; `src/osx/dataview_osx.cpp:687-738`, `src/osx/cocoa/dataview.mm:1824-1832` |
+| `wxDataViewModel::ItemChanged/ValueChanged/ChangeValue` | `wxEVT_DATAVIEW_ITEM_VALUE_CHANGED` | `interface/wx/dataview.h:116-117,331,392` |
+| generic `wxDataViewCtrl::Expand/Collapse` | EXPANDING/EXPANDED, COLLAPSING/COLLAPSED; `Collapse` can also send SELECTION_CHANGED when it hides selected rows | [source] `src/generic/datavgen.cpp:4110-4150` |
+
+Orca's widgets add their own rows; see [Orca widgets](#orca-replacement-widgets-event-contracts).
+
+Pitfalls:
+- **Rule:** A model→view refresh must not loop back through the view's change handler.
+  **Why:** `SetValue` and `SetSelection` on a book fire synchronously inside the refresh; the handler writes the
+  value back, marks the preset dirty, or rebuilds the page it is running in. On macOS a programmatic DVC
+  `Select` re-enters the selection handler.
+  ```cpp
+  // Wrong
+  text->SetValue(v);  book->SetSelection(i);  dvc->Select(item);
+  // Right
+  text->ChangeValue(v);  book->ChangeSelection(i);
+  m_suppress = true; dvc->Select(item); m_suppress = false;   // handler: if (m_suppress) return;
+  ```
+  Cite: the table above; `ObjectList` uses `m_prevent_list_events` for the same reason.
+
+## wxTextCtrl / wxTextEntry
+
+Contract:
+- `wxTE_PROCESS_ENTER` is required for `wxEVT_TEXT_ENTER` (`interface/wx/textctrl.h:1562-1564`). If no handler
+  exists, *or the handler calls `Skip()`*, Enter is processed internally or "used to activate the default button
+  of the dialog" (`interface/wx/textctrl.h:1324-1331`). `wxComboBox` has the same flag and semantics
+  (`interface/wx/combobox.h:42-48`); for `wxBitmapComboBox` it is documented as Windows-only
+  (`interface/wx/bmpcbox.h:29-33`).
+- `wxTE_PROCESS_TAB` has no effect on single-line controls under wxGTK (`interface/wx/textctrl.h:1332-1338`).
+- `wxEVT_TEXT` "is however not sent during the control creation" (`interface/wx/textctrl.h:1556-1560`). A
+  `SetValue` right after the constructor does send it, which is harmless only while nothing is bound.
+- `IsModified()` is true only after user edits; `SetValue`/`ChangeValue` reset it (`interface/wx/textentry.h:170-172`,
+  `interface/wx/textctrl.h:1880-1886`). Use it on commit to skip writing back untouched values.
+- Styles fixed at creation: `wxTE_READONLY`, `wxTE_PASSWORD` and the wrap styles can change later on GTK but not
+  on MSW; every other style except alignment is creation-time only (`interface/wx/textctrl.h:1398-1402`). Toggle
+  editability with `SetEditable(bool)`, not `SetWindowStyleFlag`.
+- Multi-line positions are not string indices on `\r\n` platforms: use `GetRange()`, not
+  `GetValue().Mid(GetInsertionPoint())` (`interface/wx/textctrl.h:1405-1418`).
+- `SetMaxLength(n)` works on single-line controls everywhere, on multi-line ones only in wxMSW and wxGTK; extra
+  input is discarded and `wxEVT_TEXT_MAXLEN` sent (`interface/wx/textentry.h:398-416`). It does not filter
+  `SetValue`.
+- `SetHint()` is native on MSW, macOS and GTK ≥ 3.2. Without native support (GTK2) wx's fallback requires you to
+  `Skip()` focus and `wxEVT_TEXT` events and avoid `WriteText`/`Replace` while the control is empty. Hints are
+  ignored with `wxTE_PASSWORD`, and on multi-line controls they work only on MSW and GTK2 — so not on macOS or on
+  Orca's GTK3 Linux build (`interface/wx/textentry.h:467-486`).
+- `wxTE_RICH` is MSW-only (prefer `wxTE_RICH2`); `wxTE_NOHIDESEL` is MSW-only (`interface/wx/textctrl.h:1347-1363`).
+
+Platforms — macOS: quote and dash smart substitution are "enabled by default" (`interface/wx/textctrl.h:2114-2134`);
+`OSXDisableAllSmartSubstitutions()` turns them off (`:2136-2144`). A single-line control also replaces pasted
+newlines with spaces unless `OSXEnableNewLineReplacement(false)` (`:2094-2113`). These `OSX*` methods are
+`@onlyfor{wxosx}` and declared only in `include/wx/osx/textctrl.h`, so calls must sit under `#ifdef __WXOSX__` or
+the MSW and GTK builds fail to compile.
+
+OrcaSlicer: interactive single-line text uses `::TextInput` ([below](#textinput)); raw `wxTextCtrl` remains for
+multi-line text. Field's `TextCtrl::BUILD` calls `OSXDisableAllSmartSubstitutions()` under `#ifdef __WXOSX__`; copy
+that for any G-code or path editor.
+
+Pitfalls:
+- **Rule:** Never use `SetLabel`, `SetLabelText` or `GetLabel` for a text control's content.
+  **Why:** `wxTextCtrlBase::SetLabel` is `wxFAIL_MSG("Use SetValue() or ChangeValue() instead.")` and nothing else
+  (`src/common/textcmn.cpp:934-937`); `SetLabelText` calls the virtual `SetLabel` (`include/wx/control.h:64-67`);
+  `GetLabel()` returns `m_labelOrig`, not the text (`include/wx/control.h:61`). The assert is compiled out, so the
+  control silently never updates, on every platform (3.3 made this consistent; MSW used to treat it as `SetValue`).
+  ```cpp
+  ctrl->GetTextCtrl()->SetLabel(s);        // Wrong: no-op
+  ctrl->GetTextCtrl()->ChangeValue(s);     // Right (or SetValue if listeners must react)
+  ```
+  Cite: `docs/changes.txt:111-113`.
+- **Rule:** Handle `wxEVT_TEXT_ENTER` without `Skip()` unless you want the default button activated as well.
+  **Why:** a skipped Enter falls through to the dialog's default button and closes it.
+  ```cpp
+  txt->Bind(wxEVT_TEXT_ENTER, [](wxCommandEvent& e) { commit(); e.Skip(); });  // Wrong in a dialog
+  txt->Bind(wxEVT_TEXT_ENTER, [](wxCommandEvent&)   { commit(); });           // Right
+  ```
+  Cite: `interface/wx/textctrl.h:1324-1331`.
+- **Rule:** Disable macOS smart substitutions on code, path and URL editors.
+  **Why:** typed `"` becomes `”` and `--` becomes `—`, silently corrupting G-code macros and paths.
+  ```cpp
+  auto* ed = new wxTextCtrl(this, wxID_ANY, gcode, wxDefaultPosition, sz, wxTE_MULTILINE);  // Wrong alone
+  #ifdef __WXOSX__                                                                          // Right: add this
+  ed->OSXDisableAllSmartSubstitutions();
+  #endif
+  ```
+  Cite: `interface/wx/textctrl.h:2114-2144`; `include/wx/osx/textctrl.h:154`; Field `TextCtrl::BUILD`.
+- **Rule:** Don't put the only explanation of a multi-line field in `SetHint()`, and don't count on
+  `SetMaxLength()` there.
+  **Why:** multi-line hints are ignored on macOS and GTK3; multi-line max length is ignored on macOS.
+  Cite: `interface/wx/textentry.h:414-415, 485-486`.
+
+## wxStaticText: labels, mnemonics, markup
+
+Contract:
+- `SetLabel` treats every `&` as a mnemonic marker; a literal ampersand must be `&&`. `SetLabelText()` shows text
+  verbatim, and `wxControl::EscapeMnemonics()` escapes it (`interface/wx/control.h:174-195, 379-387`). This applies
+  to `wxStaticText`, `wxCheckBox`, `wxRadioButton`, `wxButton` labels and to book page titles: all `wx*book`
+  classes interpret mnemonics in page text (`interface/wx/bookctrl.h:141-147`), and since 3.3 wxListbook and
+  wxChoicebook do too (`docs/changes.txt:128-130`).
+- `SetLabelMarkup()` needs well-formed markup or the label "won't be shown at all" (returns false, keeps the old
+  label). A bare `&` is still a mnemonic. Multi-line markup works only on GTK and macOS; the generic version used on
+  MSW handles single lines (`interface/wx/control.h:338-347`). Quote untrusted text with
+  `wxMarkupParser::Quote()` (`include/wx/private/markupparser.h:137-141`); the header is private, but Orca's wx
+  install copies `include/wx/private` (`deps/wxWidgets/wxWidgets.cmake`, `copy_private_headers`).
+- Without `wxST_NO_AUTORESIZE`, `SetLabel` resizes the control to its best size but never re-lays-out the parent;
+  call the parent's or sizer's `Layout()` after a size-changing label. `SetLabel` is a no-op when the text is
+  unchanged (`interface/wx/stattext.h:30-36, 107-117`; `src/common/stattextcmn.cpp:334-352`).
+- Ellipsizing (`wxST_ELLIPSIZE_START/MIDDLE/END`): the best size is the full text extent on every port (GTK even
+  switches ellipsizing off to measure, `src/gtk/stattext.cpp:239-295`), so a label ellipsizes only when something
+  constrains its width — an explicit min/initial width, or `wxST_NO_AUTORESIZE` plus a sizer-assigned size.
+- Wrapping (`Wrap(w)` caches its width in 3.3.2, so `SetLabel(new); Wrap(sameWidth)` leaves the new label
+  unwrapped — [source] `src/common/stattextcmn.cpp:259-264`; `wxST_WRAP`; Orca's `::Label`): see
+  `references/sizers-layout.md` §wxStaticText wrapping.
+
+Pitfalls:
+- **Rule:** User-provided names go through `SetLabelText` / `EscapeMnemonics`, and through
+  `wxMarkupParser::Quote` inside markup.
+  **Why:** an `&` in a preset or file name disappears or underlines the next character; a `<` makes the markup
+  invalid and the label shows nothing.
+  ```cpp
+  new wxStaticText(p, wxID_ANY, preset_name);                    // Wrong
+  auto* st = new wxStaticText(p, wxID_ANY, ""); st->SetLabelText(preset_name);   // Right
+  book->AddPage(pg, wxControl::EscapeMnemonics(filament_name));  // Right for page titles
+  lbl->SetLabelMarkup("<b>" + wxMarkupParser::Quote(name) + "</b>");             // Right for markup
+  ```
+  Cite: `interface/wx/control.h:174-195, 338-347`. Escaping translated strings: `references/strings-i18n-files.md`.
+
+## Item containers
+
+`wxChoice`, `wxComboBox`, `wxBitmapComboBox`, `wxListBox`, `wxCheckListBox`, and Orca's `::ComboBox` derive from
+`wxItemContainer`.
+
+Contract:
+- Client data: the control *owns* typed `wxClientData*` and deletes it in `Delete()`, `Clear()` and its destructor;
+  untyped `void*` is never touched. All items of one control use one kind, fixed by the first `Append(..., data)`
+  or `SetClient*` call (`interface/wx/ctrlsub.h:172-185, 466-480`). Asking for the other kind is a silent `wxCHECK`
+  returning `nullptr` (`src/common/ctrlsub.cpp:182-191, 221-230`); mixing kinds fails only a compiled-out
+  `wxASSERT` (`:213-214`).
+- `SetStringSelection` matches case-insensitively and takes the first hit (`interface/wx/ctrlsub.h:128-131`); MSW
+  wxComboBox "doesn't behave correctly" with items differing only in case (`interface/wx/combobox.h:24-28`).
+- While the dropdown is open only `GetCurrentSelection()` reflects the highlighted item
+  (`interface/wx/choice.h:148-161`, `interface/wx/combobox.h:200-208`). In a `wxEVT_COMBOBOX` handler `GetValue()`
+  already returns the new value (`interface/wx/combobox.h:53-56`).
+- `wxComboBox::IsEmpty()` is ambiguous and does not compile; use `IsListEmpty()` or `IsTextEmpty()`
+  (`interface/wx/combobox.h:219-249`).
+- With `wxCB_READONLY`, `SetValue(s)` requires `s` to be in the list (case-insensitive) (`interface/wx/combobox.h:264-267`).
+- `wxComboBox` DROPDOWN/CLOSEUP exist on wxMSW, GTK ≥ 2.10 and wxOSX/Cocoa (`interface/wx/combobox.h:64-73`), but
+  `Popup()`/`Dismiss()` never send them on wxOSX (`:279-281`).
+- `wxChoice::SetColumns` is GTK-only (`interface/wx/choice.h:164-172`). `wxLB_MULTIPLE` equals `wxLB_EXTENDED`
+  on GTK2 (`interface/wx/listbox.h:34`). In `wxEVT_CHECKLISTBOX`, `event.IsChecked()` is invalid; use `GetInt()`
+  with `wxCheckListBox::IsChecked(i)` (`interface/wx/checklst.h:18-23`).
+
+Platforms — macOS: `wxBitmapComboBox` is a `wxOwnerDrawnComboBox`; its `Select()` uses `ChangeValue` and sends no
+event (`src/generic/odcombo.cpp:1041-1060`), and all bitmaps must share one size (`interface/wx/bmpcbox.h:12-13`).
+
+OrcaSlicer: `Slic3r::GUI::BitmapComboBox` (`BitmapComboBox.hpp`) wraps `wxBitmapComboBox` where a native bitmap
+combo is still used (e.g. `apply_extruder_selector` in `wxExtensions.cpp`, `PrintHostDialogs`); on macOS it overrides `OnAddBitmap`/`OnDrawItem`
+because the generic owner-drawn base would size items from Retina-scaled bitmaps. Settings fields use
+`::ComboBox`, which has different client-data rules ([below](#combobox)).
+
+Pitfalls:
+- **Rule:** Never delete typed client data yourself; free `void*` data yourself (fetch the pointers before
+  `Clear()`/`Delete()`, which only drop them).
+  ```cpp
+  combo->Append(name, new wxStringClientData(id));      // typed: the control owns and deletes it
+  delete combo->GetClientObject(i);                     // Wrong: double free on Delete()/Clear()/destruction
+  auto* d = static_cast<wxStringClientData*>(combo->GetClientData(i));     // Wrong kind: silent nullptr
+  auto* d = static_cast<wxStringClientData*>(combo->GetClientObject(i));   // Right; never delete d
+  ```
+  Cite: `interface/wx/ctrlsub.h:172-185`; `src/common/ctrlsub.cpp:221-230`.
+
+## Check boxes and radio buttons
+
+Contract:
+- 3-state checkboxes need `wxCHK_3STATE`; users reach the third state only with `wxCHK_ALLOW_3RD_STATE_FOR_USER`
+  (`interface/wx/checkbox.h:50-56`). Read them with `Get3StateValue()`. `IsChecked()` asserts on a 3-state box
+  (`include/wx/checkbox.h:57-62`), so in Orca it silently returns `GetValue()`; `Set3StateValue(wxCHK_UNDETERMINED)`
+  on a 2-state box is likewise only an assert (`interface/wx/checkbox.h:179-185`).
+- Radio groups form from consecutive sibling buttons; `wxRB_GROUP` starts a new group and that button is the
+  initial selection (`interface/wx/radiobut.h:15-21`). `wxRB_SINGLE` takes a button out of any group, but only on
+  MSW and GTK (≥ 3.3.0); elsewhere such a button "can't be turned off" (`:31-39`). `SetValue(false)` on a grouped
+  button is invalid — select another. On MSW the focused radio button is always the selected one (`:120-130`).
+- `wxRadioBox::SetSelection(n)` needs a valid `n`, never `wxNOT_FOUND` (`interface/wx/radiobox.h:292-295`), and
+  sends no event.
+
+OrcaSlicer: interactive check boxes are `::CheckBox`/`SwitchButton`, radio rows are `::RadioGroup`; their event
+contracts differ from these ([below](#checkbox-and-switchbutton)).
+
+Pitfalls:
+- **Rule:** Put `wxRB_GROUP` on the first button of *every* group.
+  **Why:** without it, adjacent groups merge into one and selecting in one clears the other.
+  Cite: `interface/wx/radiobut.h:15-21`.
+
+## Spin controls, slider, gauge
+
+Contract:
+- Typed spin text "is not validated until the control loses focus"; it is then clamped and `wxEVT_SPINCTRL` is
+  sent only if the value differs from the last one sent. Raw typing produces `wxEVT_TEXT`
+  (`interface/wx/spinctrl.h:36-45`). `wxSpinCtrlDouble` sends `wxEVT_SPINCTRLDOUBLE` instead and also commits on
+  Enter (`:276-279`). Add `wxTE_PROCESS_ENTER` for `wxEVT_TEXT_ENTER` (`:18-22`).
+- `wxEVT_SPINCTRL` is declared with the `wxSpinEvent` class (`include/wx/spinctrl.h:22`); `wxSpinEvent::GetValue()`
+  and `GetPosition()` both return `GetInt()` (`include/wx/spinbutt.h:104-107`).
+- `wxSlider`: handle `wxEVT_SLIDER`. `wxEVT_SCROLL_CHANGED` exists on MSW only (`interface/wx/slider.h:35-38, 103`).
+  `wxSL_LEFT/TOP` work on Windows and GTK3 only; `wxSL_BOTH` and `wxSL_SELRANGE` on Windows only; tick marks
+  (`wxSL_AUTOTICKS`) need Windows or GTK ≥ 2.16 (`interface/wx/slider.h:32-66`).
+- `wxGauge`: `Pulse()` switches to indeterminate mode until the next `SetValue()`; under wxMSW `SetRange` in
+  indeterminate mode controls the bounce span (`interface/wx/gauge.h:141-161`).
+
+OrcaSlicer: integer spinners are `::SpinInput` ([below](#spininput)); progress bars are Orca's `ProgressBar`
+(`references/orca-widgets.md`). Raw `wxSlider` remains in Field's `SliderCtrl`.
+
+## Book controls
+
+Contract:
+- A page must be created with the book as its parent and added once; the book owns and deletes it
+  (`interface/wx/bookctrl.h:253-254, 273`). `RemovePage` detaches without deleting, and you then own it (`:324-330`).
+- `GetSelection()` inside a `PAGE_CHANGED` handler may return the old or the new page depending on the platform; use
+  `event.GetSelection()` (`interface/wx/bookctrl.h:160-166`).
+- `wxSimplebook` has no UI; switch with `ChangeSelection()`. `SetSelection()` sends PAGE_CHANGING/CHANGED
+  (`interface/wx/simplebook.h:17-31`); `ShowNewPage()` adds and selects (`:130-138`).
+- `wxNotebook`: `wxNB_LEFT/RIGHT/BOTTOM` are unsupported on themed MSW (`interface/wx/notebook.h:60-63`); the themed
+  MSW page background is disabled with `wxNB_NOPAGETHEME`, an explicit page `SetBackgroundColour`, or app-wide with
+  `wxSystemOptions::SetOption("msw.notebook.themed-background", 0)` (`:76-108`).
+
+OrcaSlicer: three tab mechanisms, not interchangeable —
+- `Notebook` (`Notebook.hpp`): a custom `wxBookCtrlBase` with a `ButtonsListCtrl` header, used for MainFrame's
+  Home/Prepare/Preview/Device tabs. Header clicks arrive internally as `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED`; the book
+  itself emits `wxEVT_BOOKCTRL_PAGE_CHANGING/CHANGED` from `SetSelection` and nothing from `ChangeSelection`,
+  matching wx.
+- `::TabCtrl` (`Widgets/TabCtrl`): a tab *bar* only; content switching is the caller's ([below](#radiogroup-tabctrl)).
+- `wxSimplebook`: headerless page stacks (e.g. `StatusPanel`, `SelectMachine`, `ReleaseNote`).
+
+Pitfalls:
+- **Rule:** Sync code uses `ChangeSelection`; a `PAGE_CHANGED` handler reads `event.GetSelection()`.
+  ```cpp
+  book->SetSelection(i);                     // Wrong in a sync routine whose PAGE_CHANGED handler rebuilds UI
+  book->ChangeSelection(i);                  // Right
+  int sel = book->GetSelection();            // Wrong inside PAGE_CHANGED
+  int sel = event.GetSelection();            // Right
+  auto* pg = new MyPage(dialog); book->AddPage(pg, t);   // Wrong: page must be the book's child
+  auto* pg = new MyPage(book);   book->AddPage(pg, t);   // Right
+  ```
+  Cite: `interface/wx/bookctrl.h:160-199, 253-254`.
+
+## Splitter, collapsible pane, hyperlink, static bitmap
+
+- `wxSplitterWindow`: the default minimum pane size is 0, so the user can drag a pane shut. `SetMinimumPaneSize()`
+  takes pixels — pass `FromDIP(n)` (`interface/wx/splitter.h:300-317`). `Unsplit()` only hides the removed pane
+  (`:452-466`). Sashes resize at idle time; `UpdateSize()` forces it before `Show` (`:468-479`).
+- `wxCollapsiblePane`: put children on `GetPane()`, not on the pane control; re-layout on
+  `wxEVT_COLLAPSIBLEPANE_CHANGED`; the pane resizes its top-level window unless `wxCP_NO_TLW_RESIZE`
+  (`interface/wx/collpane.h:54-96`).
+- `wxHyperlinkCtrl`: if the `wxEVT_HYPERLINK` handler `Skip()`s, or there is none, wx calls
+  `wxLaunchDefaultBrowser` (`interface/wx/hyperlink.h:55-58`). Orca's `Slic3r::GUI::HyperLink` and `::Label` with
+  `LB_HYPERLINK` are the styled alternatives (`references/orca-widgets.md`).
+- `wxStaticBitmap`: native versions are meant for small icons and only the generic one supports every
+  `SetScaleMode`; use `wxGenericStaticBitmap` for large images. MSW centres a smaller bitmap, other ports draw it at
+  the origin (`interface/wx/statbmp.h:11-23, 146-152`). `SetBitmap` takes a `wxBitmapBundle` (`:132`); Orca builds
+  bundles from its own SVG rasteriser (`references/dpi-bitmaps-fonts.md`).
+
+## wxListCtrl, wxTreeCtrl, image lists
+
+- Virtual list (`wxLC_REPORT|wxLC_VIRTUAL`): call `SetItemCount()` and override `OnGetItemText` (optionally
+  `OnGetItemImage`/`OnGetItemAttr`) (`interface/wx/listctrl.h:128-134`). `EditLabel()` asserts without
+  `wxLC_EDIT_LABELS` (`docs/changes.txt:68-69`).
+- Images: prefer `SetImages(std::vector<wxBitmapBundle>)`; `wxImageList` is discouraged
+  (`interface/wx/withimages.h:21-40`) and is measured in physical pixels in 3.3 (`docs/changes.txt:85-88`); calling
+  its methods on an invalid (unsized) list now asserts, i.e. fails silently in Orca (`docs/changes.txt:53-56`).
+  `Assign*` transfers ownership, `Set*ImageList` does not (`interface/wx/withimages.h:90-110`). Sizing:
+  `references/dpi-bitmaps-fonts.md`.
+- `wxTreeCtrl`: `SelectItem` emits events ([table](#events-from-programmatic-changes)).
+  `Delete/DeleteChildren/DeleteAllItems` send `wxEVT_TREE_DELETE_ITEM` for every item; `DeleteChildren` does not
+  clear `SetItemHasChildren` (`interface/wx/treectrl.h:318-344`). The tree owns `wxTreeItemData`.
+
+## wxGrid
+
+Contract:
+- `GetSelectedBlocks()` returns a range of unordered, possibly overlapping blocks (`interface/wx/grid.h:5090-5109`).
+  [source] It is empty when nothing is selected, and the grid cursor cell is not part of it
+  (`src/generic/grid.cpp:11295-11302` returns an empty `wxGridBlocks()` without a selection object, otherwise the
+  selection's blocks).
+- `FreezeTo(row, col)` returns false (an assert, silent in Orca) for out-of-range values, merged cells or the native
+  header (`interface/wx/grid.h:5747-5772`); [source] also when rows/columns were reordered or drag-moving is enabled
+  (`src/generic/grid.cpp:5742-5750`). In 3.3 it freezes even when the grid is too small (`docs/changes.txt:48-51`).
+- Editor contract: `EndEdit` must not modify the grid — it stores the value and returns true if it changed;
+  `ApplyEdit` writes it after `wxEVT_GRID_CELL_CHANGING` was not vetoed (`interface/wx/grid.h:610-638`). Editors,
+  renderers and attrs are ref-counted and the setters take ownership (`:1263-1305, 1739-1770, 2681-2701`).
+- A custom table sends `wxGridTableMessage` via `ProcessTableMessage()` whenever rows or columns are added or
+  removed (`interface/wx/grid.h:1832-1840`). `AssignTable()` takes ownership and may be called once (`:3088-3108`).
+- `wxGridCellChoiceEditor::Combo()` is a C-cast of `m_control` to `wxComboBox*`
+  (`include/wx/generic/grideditors.h:394`); `Reset()`, `GetValue()`, `EndEdit()` and `SetParameters()` use it
+  (`src/generic/grideditors.cpp:1538-1605`), and Esc in any editor calls `Reset()` (`:87-93`).
+
+Pitfalls:
+- **Rule:** Treat wx selection ranges as possibly empty: compare `begin()` with `end()` before dereferencing, and
+  fall back to the (row, col) that triggered the event.
+  **Why:** the docs never promised a non-empty range; with no selection 3.3 returns an empty range, and the
+  unchecked `begin()->GetLeftCol()` in `ObjectGrid` crashed on cell deselect after the 3.3 upgrade. The data-view
+  analogue: `wxDataViewCtrl::GetSelection()` is invalid with no selection *or* with more than one.
+  ```cpp
+  auto left = grid->GetSelectedBlocks().begin()->GetLeftCol();    // Wrong
+  auto blocks = grid->GetSelectedBlocks();                        // Right
+  auto it = blocks.begin();
+  int left = (it == blocks.end()) ? col : it->GetLeftCol();
+  ```
+  Cite: 46e47cec0a (`GUI_ObjectTable.cpp`, `GridCellSupportEditor::DoActivate`).
+- **Rule:** A `wxGridCellChoiceEditor` subclass that puts any other control (e.g. `::ComboBox`) in `m_control` must
+  also override `Reset()`, `GetValue()` and `SetParameters()` — or derive from `wxGridCellEditor` instead.
+  **Why:** shadowing the non-virtual `Combo()` does not change the base methods, which still C-cast `m_control` to
+  `wxComboBox*`; Esc calls `Reset()` on it.
+  Cite: `include/wx/generic/grideditors.h:394`, `src/generic/grideditors.cpp:87-93, 1561-1605`.
+- **Rule:** Clamp `FreezeTo` arguments to `[0, GetNumberRows()]` / `[0, GetNumberCols()]` and check its result.
+  Cite: `src/generic/grid.cpp:5742-5750`.
+
+## Validators
+
+- `SetValidator` stores a `Clone()` (`interface/wx/window.h:3369-3371`). `wxTextValidator` filters `wxEVT_CHAR` and
+  pasted text (`src/common/valtext.cpp:60-61, 277-301`) but never `SetValue`. `wxFILTER_DIGITS` rejects `-`, `.` and
+  `+`; `wxFILTER_NUMERIC` allows `.`, signs and `e/E` but "is not the same behaviour of wxString::IsNumber()"
+  (`interface/wx/valtext.h:43-52`).
+- Data transfer is automatic only for dialogs: `ShowModal()/Show()` → `InitDialog()` → `TransferDataToWindow()`;
+  the default `wxID_OK` handler runs `Validate() && TransferDataFromWindow()`. Panels must call `InitDialog()`
+  themselves (`docs/doxygen/overviews/validator.h:93-131`). A custom OK handler that calls `EndModal` skips
+  validation.
+
+OrcaSlicer: validators are keystroke filters only — a `wxTextValidator` with `wxFILTER_DIGITS`, `wxFILTER_NUMERIC` or
+`wxFILTER_INCLUDE_CHAR_LIST` set on `TextInput::GetTextCtrl()` (e.g. `Preferences.cpp`, `calib_dlg.cpp`) and inside
+`SpinInput`. `TransferDataTo/FromWindow` is not used: values are read, parsed and range-checked explicitly on commit.
+Keep that pattern.
+
+Pitfalls:
+- **Rule:** Pick the filter for the full value range, and still parse and range-check on commit.
+  ```cpp
+  ctrl->GetTextCtrl()->SetValidator(wxTextValidator(wxFILTER_DIGITS));   // Wrong if negatives are valid
+  ctrl->GetTextCtrl()->SetValidator(wxTextValidator(wxFILTER_NUMERIC));  // Right, plus ToDouble + range check
+  ```
+  Cite: `interface/wx/valtext.h:43-52`.
+
+## wxDataViewCtrl: native vs generic
+
+All cites `interface/wx/dataview.h`. MSW uses the generic implementation; wxGTK and wxOSX use native controls
+(915-917, 1039-1041, 3953-3955). Orca's macOS wx has `wxUSE_NATIVE_DATAVIEWCTRL 1`, so `ObjectList`,
+`DiffViewCtrl`, `ParamsViewCtrl` and the other subclasses are `NSOutlineView`s there.
+
+| Feature | Generic (MSW) | GTK | macOS | Cite |
+|---|---|---|---|---|
+| Multi-column sort (`AllowMultiColumnSort()` reports it) | yes | no | no | 915-926, 1039-1041 |
+| `wxDataViewVirtualListModel` truly virtual | yes | yes | no ("not supported by macOS") | 604-614 |
+| Item attr `SetBackgroundColour` | since 2.9.4 | since 3.1.1 | since 3.1.4 | 714-720 |
+| Item attr `SetStrikethrough` | yes | yes | ignored | 729-733 |
+| Current item | may be unselected | may be unselected | always selected; `SetCurrentItem` selects in multi-selection | 1456-1458, 1655-1665 |
+| `IsExpanded()` | correct | correct | may be true for leaves (documented bug) | 1597-1603 |
+| `CreateEditorCtrl()` | called | called | **never called** | 2626-2629 |
+| `wxDataViewRenderer::SetAlignment()` | yes | yes | ignored; aligns as the column header | 2079-2085 |
+| `IsEditCancelled()` / veto `EDITING_DONE` | yes | documented as unavailable; [source] text commits (`src/gtk/dataview.cpp:2240-2246`) and custom-editor commits (`src/common/datavcmn.cpp:791-853`) do go through `DoHandleEditingDone`, so veto works | documented as unavailable; [source] native text commit reaches the model before `EDITING_DONE` | 3942-3958 |
+| Icon+text markup (`EnableMarkup` on `wxDataViewIconTextRenderer`) | no | yes | no | 2215-2218 |
+| `EnableDropTargets` | full | first format only | full | 1377-1385 |
+| `SetDragFlags()` | honoured | ignored | ignored | 4012-4018 |
+| `GetDropEffect()` | real | `wxDragNone` | `wxDragNone` | 4030-4037 |
+| `GetProposedDropIndex()` from `ITEM_DROP_POSSIBLE` | yes | no | yes (all ports from `ITEM_DROP`) | 4052-4060 |
+| Generic mouse events (`wxEVT_LEFT_DOWN`…) | yes (bind on `GetMainWindow()`) | "notably it doesn't work in wxGTK" | not all | 994-997 |
+| Explorer theme (`wxSystemThemedControl`) | on by default since 3.1.0; `EnableSystemTheme(false)` disables it | — | — | 1000-1003 |
+| `GetMainWindow()` ≠ the control | yes | no | no | 1505-1513 |
+| `SetAlternateRowColour`, `SetHeaderAttr` | yes | no | no | 1636-1646, 1675-1689 |
+| `SetRowHeight` (uniform rows, raise only) | yes | yes | yes (3.1.1+) | 1715-1733 |
+| `GetCountPerPage()` | yes | needs ≥ 1 item | yes | 1746-1751 |
+| `GetTopItem()` | yes | may be unimplemented | may be unimplemented | 1755-1761 |
+| `wxEVT_DATAVIEW_COLUMN_REORDERED` | yes | not sent | yes | 3863-3866 |
+| `wxDataViewColumn::SetWidth()` | immediate | applied "only slightly later" (`GetWidth()` returns the old width, 0 initially; widths set before showing apply when visible) | immediate | 2793-2797 |
+
+Other per-port facts: editing starts on a slow double-click or a platform key — "F2 is typical on Windows, Space
+and/or Enter is common elsewhere" (2604-2607, 1915-1918); a custom renderer's `StartDrag()` is "Not yet supported"
+(2717-2719); `RenderText()` should be used inside `Render()` so text matches native renderers (2708-2714). Calling
+`Collapse()` from an event handler was fixed in 3.3.1 (`docs/changes.txt:346`; the generic re-check is described
+under [DVC control API](#wxdataviewctrl-control-api)).
+
+OrcaSlicer: `ParamsViewCtrl` (`EditGCodeDialog`) and `DiffViewCtrl` (`UnsavedChangesDialog`) use
+`wxDataViewIconTextRenderer::EnableMarkup` only under `#ifdef __linux__`, matching the GTK-only markup row; on MSW
+and macOS they use Orca's `BitmapTextRenderer(use_markup = true)`, which handles markup itself. `ObjectList`
+force-sets column widths on macOS because the column constructor's width is not applied on 4K/5K screens (see
+`ObjectList::create_objects_ctrl`).
+
+## wxDataViewModel contract
+
+**You implement** `IsContainer`, `GetParent`, `GetChildren`, `GetValue` and `SetValue`
+(`interface/wx/dataview.h:16-19, 383-385`).
+
+**Ownership.** The model is a `wxRefCounter` and "cannot be deleted directly" (its destructor is protected,
+`include/wx/dataview.h:291-294`). `AssociateModel` adds a reference (`interface/wx/dataview.h:1341-1345`;
+`src/common/datavcmn.cpp:1248-1263`), and the control drops it in its destructor or when another model (or
+`nullptr`) is associated. Either `DecRef()` once after associating, or hold it in `wxObjectDataPtr`
+(`interface/wx/dataview.h:68-92`), or keep one deliberate owning reference and `DecRef()` it in your destructor.
+Detaching with `AssociateModel(nullptr)` is safe only while you hold your own reference — with the
+DecRef-after-associate pattern it destroys the model.
+
+**`wxDataViewItem` is an opaque `void*`.** It must be unique and stable for the item's whole life; `nullptr` means
+both "invalid" and "the invisible root" (`interface/wx/dataview.h:788-800`). The ports keep the pointer: GTK stores
+it in `GtkTreeIter::user_data` (`src/gtk/dataview.cpp:1843-1845`), the generic control in its tree nodes, Cocoa in
+its buffers. Once the node is deleted every copy dangles — copies captured in lambdas and "last selected" members
+included — and a later allocation can reuse the address, so a liveness scan by pointer can be fooled.
+
+**Notification ordering (all ports):**
+```cpp
+// add: insert into the model first, so GetChildren(parent) already returns it
+parent_node->Append(node);  model->ItemAdded(wxDataViewItem(parent_node), wxDataViewItem(node));
+// delete: remove from the model first, then notify (pointer used only as an ID), then free
+parent_node->Remove(node);  model->ItemDeleted(wxDataViewItem(parent_node), wxDataViewItem(node));  delete node;
+// IsContainer(parent) must already be correct after the removal
+```
+Why each port needs it [source]:
+- Generic `ItemDeleted` scans its own nodes because the item "was already removed from the model by the time
+  ItemDeleted() is called", then asks `IsContainer(parent)` (`src/generic/datavgen.cpp:3260-3310`).
+- GTK `ItemAdded` looks the item up in `GetChildren(parent)` and silently returns ("adding non-existent item?") if
+  it is not there (`src/gtk/dataview.cpp:3995-4010`); GTK `ItemDeleted` checks `IsContainer(parent)` (`:1885-1895`).
+- macOS `ItemAdded/ItemDeleted` re-query the parent's children with `reloadItem:reloadChildren:`; for the root parent
+  they call `reloadData`, reloading the whole outline (`src/osx/cocoa/dataview.mm:2284-2300, 2393-2400`).
+- Notifications for an item the control never realised (collapsed parent) are ignored on purpose
+  (`src/generic/datavgen.cpp:3127-3147`, `src/gtk/dataview.cpp:1830-1838`).
+
+**`Cleared()`** means "everything changed", not "emptied" (`interface/wx/dataview.h:54-56, 141-151`). Every port
+discards its tree: generic resets selection and the current row (`src/generic/datavgen.cpp:3404-3425`), GTK does
+BeforeReset+AfterReset (`src/gtk/dataview.cpp:1998-2001`), macOS also scrolls to the top
+(`src/osx/cocoa/dataview.mm:2384-2391`). Save and restore expansion and selection around it. Re-associating a model
+on macOS likewise reloads the outline from scratch ([source] `wxCocoaDataViewControl::AssociateModel` replaces the
+data source).
+
+**ItemChanged vs ValueChanged.** Both end in `wxEVT_DATAVIEW_ITEM_VALUE_CHANGED` (`interface/wx/dataview.h:328-336,
+388-393`). `ChangeValue()` is `SetValue()` + `ValueChanged()` (`:116-117, 376-381`). On macOS `ValueChanged` calls
+`model->GetParent(item)` (`src/osx/dataview_osx.cpp:263-268`), so `GetParent` must work for any live item.
+
+**GetValue/HasValue types.** `GetValue` must fill the type the renderer expects; on a mismatch "nothing will be
+shown and a debug error message will be logged" (`interface/wx/dataview.h:258-267`) — concretely
+`CheckedGetValue` nulls the value when `!IsCompatibleVariantType()` (`src/common/datavcmn.cpp:854-885`). Container
+rows show only column 0 unless `HasContainerColumns()` returns true or `HasValue()` is overridden
+(`interface/wx/dataview.h:271-314`).
+
+Pitfalls:
+- **Rule:** Mutate the model, then notify; never notify about a node you have already freed or not yet inserted.
+  **Why:** GTK silently drops an `ItemAdded` the model does not report; generic and GTK call `IsContainer(parent)`
+  during `ItemDeleted`; a freed node read during notification is a use-after-free.
+  ```cpp
+  delete node; model->ItemDeleted(parent, wxDataViewItem(node));       // Wrong order (and any read is UAF)
+  model->ItemAdded(parent, wxDataViewItem(node)); parent_node->Append(node);   // Wrong order
+  ```
+  Cite: `src/gtk/dataview.cpp:3995-4010`, `src/generic/datavgen.cpp:3260-3310`.
+- **Rule:** Use `ItemAdded/ItemDeleted/ItemChanged` for local changes, not `Cleared()`.
+  **Why:** `Cleared()` drops selection and expansion on every port and scrolls to the top on macOS.
+- **Rule:** Moving a subtree is delete + re-add, and the re-add must announce every descendant again (see
+  `ObjectDataViewModel::AddAllChildren`).
+  **Why:** the control discarded the subtree with the deleted node; native GTK otherwise shows the moved node
+  childless ("just to add a deleted item is not enough on Linux").
+
+## wxDataViewCtrl control API
+
+Contract:
+- `GetSelection()` returns an invalid item when nothing *or more than one item* is selected
+  (`interface/wx/dataview.h:1532-1540`; `src/common/datavcmn.cpp:1329-1337`). With `wxDV_MULTIPLE` use
+  `HasSelection()`/`GetSelections()`. GTK and macOS build `SELECTION_CHANGED` from `dv->GetSelection()`
+  (`src/gtk/dataview.cpp:4507-4516`, `src/osx/cocoa/dataview.mm:1824-1832`), so in multi-selection
+  `event.GetItem()` can be invalid there; generic passes a concrete row — the clicked one, or the first selected
+  row of a Shift range (`src/generic/datavgen.cpp:4822-4827`).
+- `UnselectAll()` "only has effect if multiple selections are allowed" (`interface/wx/dataview.h:1709-1713`);
+  `SetSelections` silently ignores invalid items (`:1699`).
+- [source] `Select()` and `EnsureVisible()` expand ancestors themselves on every port
+  (`src/generic/datavgen.cpp:6396-6398, 6503-6505`, `src/gtk/dataview.cpp:5272, 5335`,
+  `src/osx/dataview_osx.cpp:584-591, 687-694`). On GTK calling them before `AssociateModel` is a silent
+  `wxCHECK_RET` (`src/gtk/dataview.cpp:5270, 5332`).
+- [source] Selection events differ: GTK suppresses them for programmatic selection
+  (`SelectionEventsSuppressor`, `src/gtk/dataview.cpp:5268-5322`) but deleting a selected row emits
+  `SELECTION_CHANGED` through GTK's "changed" signal (`:4507-4516`); macOS emits `SELECTION_CHANGED` for
+  `Select`/`SetSelections`/`UnselectAll` (`src/osx/cocoa/dataview.mm:2504-2540, 1824-1832`).
+- `SetRowHeight(h)` works on generic, GTK and macOS, only for uniform rows, and only *raises* the height above the
+  renderers' minimum (`interface/wx/dataview.h:1715-1733`). [source] On macOS the floor is the font's line height
+  and renderer `GetSize()` is not consulted (`src/osx/cocoa/dataview.mm:2615-2628`); per-item row height is
+  unsupported (`:2630-2633`); and the control's `SetFont` resets the row height to that default (`:2645-2651`).
+- `EditItem(item, col)` "doesn't do anything if the item or this column is not editable"
+  (`interface/wx/dataview.h:1361-1369`).
+- On MSW bind mouse and motion events on `GetMainWindow()`; generic mouse events do not work on wxGTK
+  (`interface/wx/dataview.h:994-997, 1505-1513`). Use a custom renderer's `ActivateCell` instead (`:2593`).
+- [source] The generic `Collapse` re-checks whether a `SELECTION_CHANGED` handler already collapsed the node
+  (`src/generic/datavgen.cpp:4119-4129`).
+
+Pitfalls:
+- **Rule:** With `wxDV_MULTIPLE`, never take `GetSelection()` or `event.GetItem()` as "the" selection.
+  ```cpp
+  auto it = dvc->GetSelection(); if (it.IsOk()) apply(it);       // Wrong: invalid once two are selected
+  wxDataViewItemArray sels; dvc->GetSelections(sels);            // Right
+  auto* node = (Node*)event.GetItem().GetID(); if (node) ...     // Right: tolerate a null item on GTK/macOS
+  ```
+  Cite: `interface/wx/dataview.h:1532-1540`.
+- **Rule:** Do not assume a native `wxDataViewCtrl` grows its rows to fit a custom renderer's `GetSize()` — set an
+  explicit `SetRowHeight` for the tallest custom content, on all platforms, after any `SetFont` on the control,
+  and again in the rescale handler with the new `em`.
+  **Why:** on macOS the native row is the font line height, so custom-drawn content (the filament colour badge)
+  overflows into adjacent rows; `SetRowHeight` can only raise it, a later `SetFont` resets it, and wx never
+  rescales a value passed to a setter, so after a DPI or theme change the badge stops fitting. Setting it on every
+  platform keeps spacing consistent (MSW is the generic control, Linux the native GTK one).
+  ```cpp
+  // create_objects_ctrl():  SetRowHeight(2 * em + FromDIP(2));
+  // msw_rescale():          SetRowHeight(2 * em + FromDIP(2));   // repeat with the new em
+  ```
+  Cite: d5638273c6 (`ObjectList::create_objects_ctrl`, `ObjectList::msw_rescale`). General rescale rule:
+  `references/dpi-bitmaps-fonts.md`.
+- **Rule:** Before moving a selected item (delete + re-add), `Unselect` it and re-`Select` it afterwards.
+  **Why:** the control's selection is not reliably updated by `ItemDeleted`; `ObjectList::update_plate_values_for_items`
+  does this ("hotfix for wxDataViewCtrl selection not updated after wxDataViewModel::ItemDeleted()").
+
+## Custom renderers and in-place editing
+
+**Renderer contract.** Implement `Render(rect, dc, state)`, `GetSize()`, `SetValue(variant)` and `GetValue(variant)`;
+call `RenderText()` inside `Render` (`interface/wx/dataview.h:2702-2718`). The constructor's `varianttype` is checked
+against model values by `IsCompatibleVariantType()` (`:1965-1980, 2063-2076`). Editing needs `HasEditorCtrl()` →
+true, `CreateEditorCtrl()` and `GetValueFromEditorCtrl()`.
+
+**Editing flow** (common code: generic, GTK custom renderers, and any explicit `renderer->StartEditing()`):
+1. `wxEVT_DATAVIEW_ITEM_START_EDITING` is sent; a veto aborts (`src/common/datavcmn.cpp:715-725`).
+2. `CreateEditorCtrl(GetMainWindow(), rect, CheckedGetValue(...))` runs; the value is **null** after a type
+   mismatch or when `HasValue(item, col)` is false (`:854-885`). The returned control is stored as `m_editorCtrl`
+   (`:733`); returning `nullptr` cancels.
+3. wx pushes a `wxDataViewEditorCtrlEvtHandler` onto *the returned control only* and focuses it — on native GTK on
+   idle (`:742-751`). That handler commits on Enter, cancels on Esc and commits on kill-focus unless focus moved to
+   a child of the editor (`src/common/datavcmn.cpp:1129-1198`). Key and focus events of a compound editor's children
+   never reach it.
+4. `FinishEditing()` calls `GetValueFromEditorCtrl(m_editorCtrl, value)` (`:799`), then hides the editor and deletes
+   it **later** via `wxPendingDelete` (`:765-785`). `Validate()` runs after the editor is gone
+   (`interface/wx/dataview.h:2125-2135`). `wxEVT_DATAVIEW_ITEM_EDITING_DONE` follows; if allowed,
+   `model->ChangeValue()` raises `VALUE_CHANGED` (`src/common/datavcmn.cpp:783-853`).
+
+**macOS (native).** `CreateEditorCtrl` "will be never called there" (`interface/wx/dataview.h:2626-2629`).
+[source] `EditItem` → `StartEditor` → `[NSOutlineView editColumn:row:…]` starts native text editing of the cell
+(`src/osx/dataview_osx.cpp:757-760`, `src/osx/cocoa/dataview.mm:2564-2566`); `START_EDITING` comes from
+`textShouldBeginEditing:`, and vetoing it returns NO to native editing (`src/osx/cocoa/dataview.mm:1885-1904`).
+`wxEVT_DATAVIEW_ITEM_EDITING_STARTED` follows from `textDidBeginEditing:` (`:1936`) and is not vetoable
+(`wxDataViewRendererBase::NotifyEditingStarted` never checks `IsAllowed()`, `src/common/datavcmn.cpp:756-763`).
+A custom cell's `objectValue` is a `wxCustomRendererObject` (`wxDataViewCustomRenderer::MacRender`,
+`src/osx/cocoa/dataview.mm:2926-2929`), so the field shows its description `wxCustomRendererObject: 0x…`
+(`src/osx/cocoa/dataview.mm:117-160, 1112-1123`). On commit `wxDataViewRenderer::OSXOnCellChanged` builds a
+**"string"** variant and calls `model->ChangeValue()` directly (`src/osx/cocoa/dataview.mm:2766-2797`), before
+`EDITING_DONE` is sent (`:1944-1955`) — the model's `SetValue` must type-check, and vetoing `EDITING_DONE` cannot
+stop it. `SetCustomRendererPtr`/`SetCustomRendererItem` are undocumented wxOSX-only members
+(`include/wx/osx/dataview.h:245-259`); `wxDataViewCtrl::FinishCustomItemEditing` reads them to close a custom
+editor when native editing starts (`src/osx/dataview_osx.cpp:779-786`, called from `src/osx/cocoa/dataview.mm:1930`).
+
+Pitfalls:
+- **Rule:** In `GetValueFromEditorCtrl()`, `dynamic_cast` the editor to the expected type and return `false` on
+  mismatch; in `CreateEditorCtrl()`, check the incoming variant before extracting.
+  **Why:** wx only ever passes the control your `CreateEditorCtrl` returned, so the cast is defence in depth against
+  app-side bookkeeping confusion — cheap insurance where a wrong `static_cast` reads garbage and crashes on commit.
+  It matters most on macOS, where native editing never calls `CreateEditorCtrl` at all and Orca's editor exists only
+  because `start_filament_editor` calls `StartEditing` directly.
+  ```cpp
+  auto* c = static_cast<::ComboBox*>(ctrl);          // Wrong
+  auto* c = dynamic_cast<::ComboBox*>(ctrl);         // Right
+  if (!c || c->GetSelection() < 0) return false;
+  ```
+  Cite: c965b2a5b3 (`ExtraRenderers.cpp`, `BitmapChoiceRenderer::GetValueFromEditorCtrl`;
+  `BitmapTextRenderer::GetValueFromEditorCtrl` uses `wxDynamicCast`); `src/common/datavcmn.cpp:733, 799`.
+- **Rule:** On macOS, do not open a custom-renderer column editor through `EditItem()` or let the native
+  start-editing path run: `Veto()` `wxEVT_DATAVIEW_ITEM_START_EDITING`, `CallAfter` a call to the renderer's own
+  `StartEditing(item, GetItemRect(item, column))`, then `SetCustomRendererPtr`/`SetCustomRendererItem`. Guard against
+  re-entry and an already-open editor (`renderer->GetEditorCtrl()`), re-validate the item inside the lambda, and keep
+  it all under `#ifdef __WXOSX__`.
+  **Why:** `EditItem()` on Cocoa enters native text editing of the `wxCustomRendererObject` instead of your editor,
+  glitching the cell and crashing on commit. The re-entry guard is needed because `StartEditing` itself sends
+  `START_EDITING` (`src/common/datavcmn.cpp:716-725`), which the same handler would otherwise veto.
+  ```cpp
+  void ObjectList::OnStartEditing(wxDataViewEvent& event) {
+  #ifdef __WXOSX__
+      if (event.GetColumn() == colFilament) {
+          if (m_starting_filament_editor) return;          // our own StartEditing re-entering
+          event.Veto();
+          CallAfter([this, item = event.GetItem()] {
+              if (!is_live_model_item(item)) return;
+              start_filament_editor(item);                 // StartEditing + SetCustomRendererPtr/Item
+          });
+          return;
+      }
+  #endif
+  ```
+  Cite: c965b2a5b3 (`ObjectList::OnStartEditing`, `ObjectList::start_filament_editor`).
+- **Rule:** A compound editor commits by calling the renderer's `FinishEditing()` (or `CancelEditing()`) from its
+  own commit event.
+  **Why:** wx's Enter/Esc/kill-focus handler sits only on the top editor window; a `::ComboBox` or TextInput editor's
+  inner controls never reach it, and kill-focus commit is unreliable on Linux.
+  ```cpp
+  c_editor->Bind(wxEVT_COMBOBOX, [this](wxCommandEvent& e) { e.StopPropagation(); FinishEditing(); });
+  ```
+  Cite: `BitmapChoiceRenderer::CreateEditorCtrl`; `src/common/datavcmn.cpp:742-751, 1129-1198`.
+- **Rule:** Do not touch the editor after `FinishEditing()`/`CancelEditing()`, and do not rely on vetoing
+  `EDITING_DONE` outside MSW.
+  **Why:** the editor is queued on `wxPendingDelete` and dies at the next idle or yield; on macOS the value is
+  already in the model when `EDITING_DONE` arrives.
+
+## wxVariant with custom objects
+
+`wxIMPLEMENT_VARIANT_OBJECT(T)` (and the older `IMPLEMENT_VARIANT_OBJECT`) generates `T& operator<<(T&, const
+wxVariant&)`, which only `wxASSERT`s the type and then C-casts `GetData()` (`include/wx/variant.h:525-532`). The
+custom type name is the wxObject class name (`GetType()` → `GetClassInfo()->GetClassName()`, `:515-518`); a null
+variant's type is `"null"` (`interface/wx/variant.h:420-425`). wx's own `wxBitmap << variant` extraction is generated
+the same way.
+
+Pitfalls:
+- **Rule:** Check `!v.IsNull() && v.GetType() == "<Class>"` before every `obj << v` extraction.
+  **Why:** the assert is compiled out of Orca in every configuration, so a wrong-typed variant is read as garbage and
+  a null one dereferences `nullptr`. Wrong types really happen: `CheckedGetValue` passes a null variant to
+  `CreateEditorCtrl` after a model/renderer type mismatch, and native macOS editing hands the model's `SetValue` a
+  `"string"` variant built from the field text (`src/osx/cocoa/dataview.mm:2766-2797`).
+  ```cpp
+  DataViewBitmapText data; data << variant;                                    // Wrong: blind extraction
+  if (variant.IsNull() || variant.GetType() != wxT("DataViewBitmapText"))      // Right
+      return false;
+  DataViewBitmapText data; data << variant;
+  ```
+  Cite: c965b2a5b3 (`ExtraRenderers.hpp`, `ObjectDataViewModelNode::SetValue`).
+  Note: `wxObject`'s default copy and assignment share ref-data with correct refcounting
+  (`include/wx/object.h:324-338`); `DataViewBitmapText`'s field-copying operators are harmless but not required.
+
+## Orca replacement widgets: event contracts
+
+Orca's interactive controls replace raw wx ones (catalog, constructors and quirks: `references/orca-widgets.md`).
+They emit the native event *types* through `GetEventHandler()->ProcessEvent`, so command events propagate to parents
+like native ones and stop at dialogs (`wxWS_EX_BLOCK_EVENTS`) and, on MSW and macOS, at popups (not on wxGTK,
+`references/events.md` §5) — but ids, event objects, event classes and setter side effects differ. "Ancestor" in the
+Bind column means an ancestor bound by event type; binding an ancestor by the widget's id is discouraged
+(`references/events.md` §10):
+
+| Widget | Replaces | Emits (user action) | Id / object | Setter side effects | Bind |
+|---|---|---|---|---|---|
+| `::TextInput` | `wxTextCtrl` | inner `wxEVT_TEXT` (propagates); `wxEVT_TEXT_ENTER`, `wxEVT_KILL_FOCUS` re-sent to the wrapper only | TEXT: inner ctrl's id/object; ENTER/KILL_FOCUS: wrapper's id, inner object | `GetTextCtrl()->SetValue` → `wxEVT_TEXT` | TEXT: wrapper or `GetTextCtrl()`; ENTER/KILL_FOCUS: wrapper or `GetTextCtrl()`, never a parent |
+| `::ComboBox` | `wxComboBox`/`wxChoice` | `wxEVT_COMBOBOX` (int = index, string = text); DROPDOWN/CLOSEUP | COMBOBOX: combo's auto-generated id (the ctor `id` is ignored) and object; DROPDOWN/CLOSEUP: id 0, no object | `SetSelection`/`SetValue` → `wxEVT_TEXT` when the text ctrl is shown or `CB_NO_TEXT`; `SelectAndNotify` → `wxEVT_COMBOBOX` | COMBOBOX on the combo (or an ancestor); DROPDOWN/CLOSEUP on the combo without id |
+| `::SpinInput` | `wxSpinCtrl` | `wxEVT_SPINCTRL` (a `wxCommandEvent`); `EVT_SPINCTRL_TEXT` per parsable keystroke; inner `wxEVT_TEXT` | SPINCTRL / SPINCTRL_TEXT: spinner id/object | `SetValue(int)` → `EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`, no `wxEVT_SPINCTRL` | SPINCTRL on the spinner or an ancestor, handler takes `wxCommandEvent&` |
+| `::CheckBox`, `SwitchButton` | `wxCheckBox` | `wxEVT_TOGGLEBUTTON` | native | `SetValue` silent | on the widget (with `Skip()`) or an ancestor; never `wxEVT_CHECKBOX` |
+| `::RadioGroup` | `wxRadioBox` | `wxEVT_COMMAND_RADIOBOX_SELECTED` | group id, no object | **every** `SetSelection` emits | on the group or an ancestor |
+| `::TabCtrl` | tab bar | `wxEVT_TAB_SEL_CHANGING` then `wxEVT_TAB_SEL_CHANGED` (plain `wxCommandEvent`) | tab ctrl id/object; CHANGING carries the old index | `SelectItem(i)` emits both when `i` changes | on the ctrl or an ancestor; cannot veto |
+| `Button` | `wxButton` | `wxEVT_BUTTON` | button id/object | — | on the button or an ancestor |
+
+### TextInput
+
+`::TextInput` (`Widgets/TextInput.cpp`, `TextInput::Create`; ctor `TextInput(parent, text, label = "", icon = "",
+pos, size, style)`) is a `StaticBox` frame around a real `wxTextCtrl` (on MSW the `TextCtrl` subclass in
+`Widgets/TextCtrl.h`). Style flags pass through to the inner control (alignment flags are stripped); tooltips forward.
+- It always ORs in `wxTE_PROCESS_ENTER`, and its `wxEVT_TEXT_ENTER` handler does not `Skip()`: Enter in a TextInput
+  never activates a dialog's default button and never propagates to parents.
+- The inner control's `wxEVT_TEXT_ENTER` and `wxEVT_KILL_FOCUS` are re-dispatched with the wrapper's id via
+  `ProcessEventLocally`, which runs the wrapper's own handlers but [source] never `TryAfter`, so never the parents
+  (`src/common/event.cpp:1582-1589`; the doc at `interface/wx/event.h:626-650` says otherwise).
+- `wxEVT_TEXT` is a command event from the inner control and propagates normally, carrying the inner control's id
+  and object. Key, char and focus-in events exist only on `GetTextCtrl()`.
+- The value API lives on `GetTextCtrl()`. `TextInput::SetLabel()` sets the painted side label, not the text.
+- A handler bound later on `GetTextCtrl()` for ENTER or KILL_FOCUS runs before the wrapper's internal one
+  (dynamic handlers run most-recently-bound first, `docs/doxygen/overviews/eventhandling.h:475-482`) and must
+  `Skip()` so `OnEdit()` and the re-dispatch still run.
+- `TextInput` has no id parameter: its `StaticBox` is created with `wxID_ANY`, so the wrapper id seen by
+  ENTER/KILL_FOCUS handlers is auto-generated.
+
+### ComboBox
+
+`::ComboBox` (`Widgets/ComboBox.cpp`) is `wxWindowWithItems<TextInput, wxItemContainer>` with an owned `DropDown`
+popup; ctor `ComboBox(parent, id, value = "", pos, size, n, choices[], style)`. The `id` argument is ignored:
+the constructor calls `TextInput::Create`, which creates the window with `wxID_ANY`, so `GetId()` is auto-generated
+and a parent bound with the id you passed never fires. `wxCB_READONLY` hides the text control and paints the value;
+`CB_NO_DROP_ICON`/`CB_NO_TEXT` are Orca style flags.
+- `SetSelection(n)` sends no `wxEVT_COMBOBOX` (matching wx) and returns early when `n` is already selected. When the
+  inner text control is shown (editable) or `CB_NO_TEXT` is set, it — and `SetValue` — go through
+  `GetTextCtrl()->SetValue()`, which sends a propagating `wxEVT_TEXT`. `SelectAndNotify(n)` selects and sends
+  `wxEVT_COMBOBOX`.
+- `SetLabel`/`GetLabel` are the displayed value; `SetTextLabel` writes the wrapper's painted label directly.
+- Only untyped `void*` client data is supported: every `Append` overload calls
+  `SetClientDataType(wxClientData_Void)`, and the caller owns and frees the data. `DeleteOneItem()` skips the base
+  class's client-object reset.
+- `Clear()`, `Insert()`, `Set()` and `Delete()` (via `DoClear`/`DoInsertItems`/`DoDeleteOneItem` →
+  `DropDown::Invalidate(true)`) reset the selection to -1 without clearing the shown text; call
+  `SetSelection`/`SetValue` afterwards.
+- Mouse-wheel selection is disabled. `GetDropDown()` exposes the popup (e.g. `SetUseContentWidth(true)`).
+
+### SpinInput
+
+`::SpinInput` (`Widgets/SpinInput.cpp`; ctor `SpinInput(parent, text, label = "", pos, size, style, min = 0,
+max = 100, initial = 0, step = 1)`) is integer-only: an inner `TextCtrl` with `wxTextValidator(wxFILTER_DIGITS)` plus
+two arrow `Button`s with key-repeat; `SetValue/GetValue/SetRange/SetStep`.
+- It commits — clamps, then sends `wxEVT_SPINCTRL` — on Enter, kill-focus and arrow keys only if the value changed,
+  but on every arrow-button press and key-repeat tick even when the value is pinned at `min`/`max`
+  (`SpinInput::createButton`, `onTimer`); mouse-wheel stepping is disabled (`EVT_MOUSEWHEEL` is commented out of
+  the event table, so `mouseWheelMoved` never runs). `EVT_SPINCTRL_TEXT` (int + string) is the live
+  per-keystroke event.
+- `wxEVT_SPINCTRL` is built as a `wxCommandEvent` with no `SetInt`: bind with a `wxCommandEvent&` handler and read
+  `GetValue()` from the spinner; a `wxSpinEvent&` handler would read `GetPosition()` == 0 from a mis-typed object.
+- `SetValue(int)` clamps and sends no `wxEVT_SPINCTRL`, but sends `EVT_SPINCTRL_TEXT` and a propagating `wxEVT_TEXT`
+  (it uses the inner `SetValue`). `SetRange` does not re-clamp the current value — set the range before the value.
+- Typing accepts digits only; `-` cannot be typed, so negative ranges need another control.
+- Enter and kill-focus are re-dispatched locally, as in TextInput. Dialogs sometimes `Disable()` a SpinInput to
+  force a commit before reading; that depends on the platform delivering `wxEVT_KILL_FOCUS` to the focused inner
+  control when it is disabled, which wx does not promise — read the inner text and commit explicitly when it matters.
+
+### CheckBox and SwitchButton
+
+`::CheckBox` (ctor `CheckBox(parent, id = wxID_ANY)`, no label — pair it with a `wxStaticText`/`Label`, as
+`CloneDialog` does) and `SwitchButton` are `wxBitmapToggleButton`s. They emit `wxEVT_TOGGLEBUTTON`, never
+`wxEVT_CHECKBOX`; `SetValue` sends nothing. The half state is drawn only (`SetHalfChecked`/`IsHalfChecked`); any click
+clears it via the widget's own `wxEVT_TOGGLEBUTTON` handler (bound in the constructor), which also swaps the on/off
+bitmap. Handlers bound later on the same widget run first, so they must `Skip()`, or the bitmap keeps showing the old
+state and the half state is never cleared (`PreferencesDialog::create_item_bambu_cloud` marks this with "let
+CheckBox::update() refresh the bitmap"). Inside `Slic3r::GUI` write `::CheckBox` — `Field.hpp` declares a `Slic3r::GUI::CheckBox` field class.
+
+### RadioGroup, TabCtrl
+
+- `::RadioGroup::SetSelection(i)` **always** sends `wxEVT_COMMAND_RADIOBOX_SELECTED` — for programmatic calls and
+  for an unchanged index too — the opposite of `wxRadioBox`. Guard the handler or set a flag around sync code.
+- `::TabCtrl::SelectItem(i)` sends `wxEVT_TAB_SEL_CHANGING` (cannot be vetoed; `sendTabCtrlEvent` always returns true)
+  then `wxEVT_TAB_SEL_CHANGED`; switching content is the caller's job. `TabCtrl::AssignImageList` is Orca's own
+  method, not `wxWithImages`. `SelectItem` also sends a synthetic `wxEVT_CHECKBOX` (id 0, object = the tab `Button`)
+  to the old and new tab buttons to toggle their `StateHandler` Checked state; the state handler `Skip()`s it, so it
+  propagates to the TabCtrl's ancestors — an ancestor bound to `wxEVT_CHECKBOX` without an id filter receives it.
+
+### Field widgets
+
+Settings fields (`Field.cpp`, built by `OptionsGroup::build_field`) wrap these widgets — `TextCtrl` → `::TextInput`
+(a raw multi-line `wxTextCtrl` when `opt.multiline`), `CheckBox` → `::CheckBox`, `SpinCtrl` → `::SpinInput`,
+`Choice` and `PrinterAgentChoice` → `::ComboBox` (`choice_ctrl`; a `Choice` is editable with `wxTE_PROCESS_ENTER`
+for open-enum GUI types without a dynamic list, `wxCB_READONLY` otherwise), `ColourPicker` → `wxColourPickerCtrl`,
+`PointCtrl` → two `::TextInput`, `StaticText` → `wxStaticText(wxST_ELLIPSIZE_MIDDLE)`, `SliderCtrl` → `wxSlider` +
+`wxTextCtrl`, `PluginConfigField` → `Button`. Programmatic field updates use the
+`m_disable_change_event` bracket around `SetValue`, which works because wx delivers `wxEVT_TEXT` synchronously. Field
+machinery, pooling and the bind-with-id rule: `references/orca-settings-ui.md`.
+
+Pitfalls:
+- **Rule:** Bind TextInput/SpinInput ENTER and KILL_FOCUS on the widget (or its `GetTextCtrl()`), never on a parent;
+  bind `::ComboBox` events on the combo, never by the id passed to its constructor.
+  ```cpp
+  dialog->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this, input->GetId());   // Wrong: never fires
+  input->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this);                    // Right
+  panel->Bind(wxEVT_TEXT, h, input->GetId());                             // Wrong: TEXT carries the inner id
+  input->Bind(wxEVT_TEXT, h);                                             // Right
+  auto* c = new ::ComboBox(this, ID_MODE); Bind(wxEVT_COMBOBOX, h, ID_MODE);    // Wrong: ID_MODE is ignored
+  c->Bind(wxEVT_COMBOBOX, h);                                             // Right
+  ```
+  Cite: `TextInput::Create`; `ComboBox::ComboBox`; `src/common/event.cpp:1582-1589`.
+- **Rule:** Bind `::CheckBox`/`SwitchButton` with `wxEVT_TOGGLEBUTTON` (and `Skip()` when bound on the widget itself),
+  and `SpinInput` with a `wxCommandEvent&` handler.
+  ```cpp
+  cb->Bind(wxEVT_CHECKBOX, h);                                            // Wrong: never sent
+  cb->Bind(wxEVT_TOGGLEBUTTON, [](wxCommandEvent& e) { apply(); });       // Wrong: stale bitmap
+  cb->Bind(wxEVT_TOGGLEBUTTON, [](wxCommandEvent& e) { apply(); e.Skip(); });  // Right
+  spin->Bind(wxEVT_SPINCTRL, [](wxSpinEvent& e) { use(e.GetPosition()); });     // Wrong
+  spin->Bind(wxEVT_SPINCTRL, [spin](wxCommandEvent&) { use(spin->GetValue()); });  // Right
+  ```
+  Cite: `CheckBox::CheckBox`, `SwitchButton::SwitchButton`; `SpinInput::sendSpinEvent`.
+- **Rule:** Treat an editable `::ComboBox`'s `SetSelection`/`SetValue` as emitting `wxEVT_TEXT`, and a
+  `RadioGroup::SetSelection` as emitting its selection event.
+  **Why:** both fire synchronously inside model→view refreshes and re-enter change handlers.
+
+## ObjectList, ObjectDataViewModel, ExtraRenderers
+
+`ObjectList` (`GUI_ObjectList.cpp/.hpp`) is the sidebar's `wxDataViewCtrl` (`wxDV_MULTIPLE | wxNO_BORDER |
+wxDV_NO_HEADER`) over `ObjectDataViewModel` (`ObjectDataViewModel.cpp/.hpp`), a custom `wxDataViewModel` of
+`ObjectDataViewModelNode`s typed by the `ItemType` bitmask (`itPlate, itObject, itVolume, itInstanceRoot, itInstance,
+itSettings, itLayerRoot, itLayer, itInfo`) with columns `ColumnNumber` (`colName, colHeight, colPrint, colFilament,
+colSupportPaint, colColorPaint, colSinking, colEditing`). Per-object, per-part and per-layer overrides appear as an
+`itSettings` child; selecting it opens the model-scope tabs (`TabPrintModel` → `TabPrintPlate/Object/Part/Layer`),
+which reuse the `OptionsGroup`/`Field` machinery bound to the items' `ModelConfig`s instead of a preset config. Which
+options are offered: `references/orca-settings-ui.md`.
+
+**Model design.**
+- Ownership: `ObjectList::create_objects_ctrl` does `new ObjectDataViewModel; AssociateModel(m_objects_model);`
+  without an immediate `DecRef`, and `ObjectList::~ObjectList` calls `m_objects_model->DecRef()` — ObjectList owns one
+  reference for its lifetime. That is what makes the macOS bulk-update pattern safe: `add_objects_to_list` and
+  `update_plate_values_for_items` detach with `AssociateModel(nullptr)` and reattach afterwards, so the outline
+  reloads once [source] instead of once per notification.
+- Each `ObjectDataViewModelNode*` *is* its `wxDataViewItem` ID; children live in the parent's pointer array.
+  `ObjectDataViewModel::Delete` removes the node from its parent (or from `m_plates`/`m_objects`), calls
+  `ItemDeleted(parent, item)`, then deletes it.
+- `HasContainerColumns()` returns true so container rows draw their icon columns; `IsContainer(invalid)` is true for
+  the root.
+- Re-parenting (`ReparentObject`, `ReorganizeChildren`, `ReorganizeObjects`) is remove → `ItemDeleted` → insert →
+  `ItemAdded`; `ReorganizeChildren` and `ReorganizeObjects` then call `AddAllChildren`, which re-announces the subtree
+  and expands the moved node. `ReparentObject` (plate change) does not; `ObjectList::update_plate_values_for_items`
+  re-expands and re-selects the item itself.
+- `GetColumnType` returns `"DataViewBitmapText"` for `colName`/`colFilament`, but wx 3.3 never calls it (deprecated,
+  `include/wx/dataview.h:285-289`); what wx checks is the renderer's `varianttype`, which both ExtraRenderers set to
+  `"DataViewBitmapText"`. `ObjectDataViewModelNode::SetValue` type-checks `"DataViewBitmapText"` for those columns.
+
+**Renderers** (`ExtraRenderers.cpp/.hpp`; `ENABLE_NONCUSTOM_DATA_VIEW_RENDERING` is 0, so both are
+`wxDataViewCustomRenderer`s):
+- `BitmapTextRenderer` (name column): editor is a `wxTextCtrl` with `wxTE_PROCESS_ENTER`; editing is gated by
+  `set_can_create_editor_ctrl_function`; `GetValueFromEditorCtrl` refuses names with illegal filename characters
+  and `ObjectList::OnEditingDone` reports `WasCanceled()` through a deferred warning.
+- `BitmapChoiceRenderer` (filament column): editor is a `::ComboBox` (`wxCB_READONLY | CB_NO_DROP_ICON |
+  CB_NO_TEXT`) filled from `get_extruder_color_icons()`. It force-opens the popup on focus — on GTK deferred with
+  `CallAfter` and an `IsShownOnScreen()` check, because the editor "may receive focus before its native window is
+  mapped" (popup parenting: `references/popups-menus.md`) — and calls `FinishEditing()` itself on `wxEVT_COMBOBOX`.
+
+**macOS editing.** The filament editor is opened by the veto + `CallAfter` + `start_filament_editor` pattern
+([above](#custom-renderers-and-in-place-editing)); `wxEVT_DATAVIEW_ITEM_ACTIVATED` on `colFilament` calls
+`start_filament_editor` on macOS and `EditItem` elsewhere. While starting, `m_filament_editor_item` tells the
+renderer's callbacks which item is being edited (selection may differ). The bitmap columns are created
+`wxDATAVIEW_CELL_EDITABLE` on macOS only, so a click starts native editing, and `ObjectList::OnEditingStarted`
+(non-MSW branch) treats the resulting `EDITING_STARTED` as a per-cell click and runs the column's action
+(printable toggle, paint gizmos, sinking, settings reset). Its `event.Veto()` there has no effect — only
+`START_EDITING` is vetoable ([above](#custom-renderers-and-in-place-editing)); stopping native editing needs a veto in
+`OnStartEditing`, as the filament column does.
+
+**Selection and events.**
+- `m_prevent_list_events` brackets programmatic `Select`/`UnselectAll`/model mutation; the `SELECTION_CHANGED`
+  handler returns early on macOS when it is set, and `ObjectList::selection_changed` checks it on every port —
+  covering GTK's selection events from drag-and-drop and row deletion.
+- With Shift held the handler recovers the last-clicked item from `GetSelections()`, because the event item is not
+  reliable in multi-selection; a null `event.GetItem()` is tolerated.
+- `is_live_model_item` (macOS only) re-validates a deferred item by scanning `GetAllChildren` for its pointer. It
+  cannot detect a freed node whose address was reused; prefer re-resolving from object/volume indices when you can.
+
+**Row height and fonts.** `SetRowHeight(2 * em + FromDIP(2))` in `create_objects_ctrl` and in `msw_rescale`
+(d5638273c6). `ObjectList::ObjectList` calls `SetFont(Label::sysFont(13))` on every platform, before
+`create_objects_ctrl` — necessary on macOS because the control's `SetFont` resets the row height. The macOS-only
+"don't `SetFont`" guard lives in `DPIAware`'s constructor and concerns only a top-level window's default font
+(`references/dpi-bitmaps-fonts.md`).
+
+**Global renderer on MSW.** `ObjectList::ObjectList` calls `wxRendererNative::Set(new wxRenderer)` — a
+`wxDelegateRendererNative` overriding `DrawItemSelectionRect`, `DrawFocusRect`, `DrawTreeItemButton` and
+`DrawItemText` with Orca colours (through `StateColor::darkModeColorFor`). `Set` replaces "the global renderer"
+(`interface/wx/renderer.h:651-657`): once `ObjectList` exists, every generic `wxDataViewCtrl` on MSW
+(`src/generic/datavgen.cpp:2735-2974`) and every `RenderText` call (`src/common/datavcmn.cpp:1102`) draws with them.
+`DrawItemText` draws at the rect's top-left without alignment or ellipsis. Expect this when a new MSW data view looks
+"wrong". Dark styling of data views (`UpdateDVCDarkUI`): `references/colours-dark-mode.md`.
+
+Pitfalls:
+- **Rule:** Every deferred lambda that holds a `wxDataViewItem` re-validates it before use.
+  **Why:** the model can be rebuilt between queueing and execution; the item is a raw node pointer.
+  ```cpp
+  CallAfter([this, item] { start_filament_editor(item); });              // Wrong
+  CallAfter([this, item] { if (!is_live_model_item(item)) return;        // Right (or re-resolve by index)
+                           start_filament_editor(item); });
+  ```
+  Cite: c965b2a5b3 (`ObjectList::is_live_model_item`). Liveness rules for deferred calls: `references/events.md`
+  §CallAfter.
+
+## ObjectGrid (GUI_ObjectTable)
+
+`ObjectTableDialog` (a `DPIDialog`, opened by `Plater::PopupObjectTable`) hosts `ObjectGrid` (a `wxGrid`) with
+`ObjectGridTable` (a `wxGridTableBase` set with `AssignTable`).
+- Per-cell editors and renderers are installed with `SetCellEditor`/`SetCellRenderer`, which take ownership.
+- `GridCellFilamentsEditor` and `GridCellChoiceEditor` derive from `wxGridCellChoiceEditor` but create a
+  `::ComboBox` as `m_control` and shadow `Combo()`; they override `BeginEdit`/`EndEdit`. Any change to them, or a new
+  editor of this shape, must account for the base `Reset()`/`GetValue()`/`SetParameters()` cast
+  ([wxGrid](#wxgrid)).
+- `GridCellSupportEditor::DoActivate`, the copy path in `ObjectGrid::OnKeyDown` and `ObjectGrid::paste_data` handle
+  an empty `GetSelectedBlocks()` (46e47cec0a).

.claude/skills/orca-wxwidgets/references/dpi-bitmaps-fonts.md

@@ -0,0 +1,958 @@
+# DPI, bitmaps and fonts
+
+How wx 3.3.2 maps DIP, logical and physical pixels on each platform, how DPI changes reach a window,
+and how OrcaSlicer sizes layout (`FromDIP`, `em_unit`), rescales (`DPIAware`), rasterizes icons
+(`BitmapCache`, `create_scaled_bitmap`, `ScalableBitmap`) and chooses fonts (`Label` table). Read it
+for any fixed size, icon, bitmap, image list, font, or `on_dpi_changed` work, and when a bug looks
+like "too small / too big / blurry / clipped on another monitor".
+
+Contents: [Rules](#rules) · [Pixel kinds per platform](#pixel-kinds-per-platform) ·
+[FromDIP / ToDIP / FromPhys](#fromdip--todip--fromphys--tophys) ·
+[Scale factors and GetDPI](#scale-factors-and-getdpi) ·
+[Choosing a size unit](#choosing-a-size-unit-fromdip-em_unit-text-metrics) ·
+[wxEVT_DPI_CHANGED](#wxevt_dpi_changed) · [DPIAware rescale path](#dpiaware-rescale-path-orca) ·
+[wxBitmap](#wxbitmap-physical-size-scale-factor-logical-size) ·
+[wxBitmapBundle](#wxbitmapbundle-and-its-limits-in-orcas-build) ·
+[Orca icon pipeline](#orca-icon-pipeline) ·
+[Image lists, art provider, wxImage](#image-lists-art-provider-wximage) ·
+[Window icons](#window-icons) · [Displays](#displays-and-ppi) · [wxFont](#wxfont) ·
+[Orca fonts](#orca-fonts-label-table-sysfont-initsysfont)
+
+## Rules
+
+1. Hard-coded layout pixel values (sizes, min sizes, borders, gaps, spacers) go through
+   `FromDIP(n)` (or `n * em_unit(this)` in em-based code), never raw ints. §Choosing a size unit
+2. Do not `FromDIP` values that are not logical pixels: `wxBitmap` ctor sizes and `GetSize()`,
+   `wxImageList` sizes and `wxBitmapBundle::GetBitmap(size)` are physical; bundle default sizes
+   and `wxArtProvider::GetBitmapBundle` sizes are DIP. §wxBitmap, §wxBitmapBundle
+3. On Linux, widths that must hold text come from text metrics, best sizes or `em_unit`, not
+   from a fixed `FromDIP` width. §Choosing a size unit
+4. Call `FromDIP` on a created window, or on `parent` in base-ctor arguments; when the window
+   may be null use the static `wxWindow::FromDIP(x, win)`, never `win->FromDIP(x)` (fd80ded5a8).
+   §FromDIP
+5. Pick bitmap resolution with `GetDPIScaleFactor()`; never with `GetContentScaleFactor()`
+   (always 1 on MSW) or `GetDPI().x / 96.0` (72-based on macOS). §Scale factors
+6. Every top-level window is a `DPIDialog`/`DPIFrame` whose `on_dpi_changed` re-rasterizes named
+   bitmaps and re-sets them on controls, calls each Orca widget's `Rescale()`, re-applies every
+   size stored from `em_unit`/`FromDIP`, then re-establishes the minimum and fits. An empty
+   override is acceptable only for a trivial dialog with no bitmaps and no stored sizes.
+   §DPIAware rescale path
+7. Every `wxEVT_DPI_CHANGED` handler you bind — on a child, a control, or on the TLW from a
+   component — calls `Skip()`; only DPIAware's own TLW handler deliberately does not.
+   §wxEVT_DPI_CHANGED
+8. In a DPIAware window, never rely on wx's MSW top-level auto-resize; size the window in
+   `on_dpi_changed`. §wxEVT_DPI_CHANGED, §DPIAware rescale path
+9. `DPIAware::scale_factor()` is the display scale only on MSW (Orca's `get_dpi_for_window` is a
+   96 stub elsewhere); use `GetDPIScaleFactor()`/`FromDIP` for anything else. §DPIAware
+10. On GTK `em_unit` is measured from the font, with the same formula in the ctor and the
+    rescale path (40eab797c6). §DPIAware
+11. Icons are SVG resource names (no path, no extension) passed to `create_scaled_bitmap`,
+    `ScalableBitmap` or `Button`, with the real window and an explicit size;
+    `wxBitmapBundle::FromSVG*` does not exist in Orca's wx. §Orca icon pipeline
+12. Layout that depends on a bitmap uses its logical size (`ScalableBitmap::GetBmpSize()`,
+    `wxBitmap::GetLogicalSize()`), not `GetSize()`/`GetWidth()`. §wxBitmap
+13. Owner-drawn offscreen bitmaps use `CreateWithDIPSize(sz, GetDPIScaleFactor())` or
+    `CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor())`, not `wxBitmap(FromDIP(sz))`.
+    §wxBitmap
+14. Draw a bundle with `GetBitmapFor(win)`, never `GetBitmap(GetDefaultSize())`; bundle size
+    queries take a created, non-null window. §wxBitmapBundle
+15. `wxImageList` sizes are physical and must equal the added bitmaps' sizes; prefer
+    `SetImages()` with bundles. §Image lists
+16. Fonts come from `Label::Head_*`/`Label::Body_*`; never literal point sizes. §Orca fonts
+17. After `wxFont::SetFaceName` check `IsOk()` and fall back. §wxFont
+18. Private fonts are registered only by `Label::initSysFont()`, early in
+    `GUI_App::on_init_inner`; never `AddPrivateFont` on macOS. §Orca fonts
+19. On MSW a `wxMemoryDC` sizes text for its bitmap's scale factor: give the bitmap the window's
+    `GetDPIScaleFactor()` before selecting it; any `Label` font then renders correctly. §wxFont
+20. Never index `wxDisplay` with an unchecked `GetFromWindow()` result. §Displays
+
+## Pixel kinds per platform
+
+Contract (`docs/doxygen/overviews/high_dpi.md:139-149`): "Under MSW, logical pixels are always
+the same as physical pixels, but are different from DIPs, while under all the other platforms
+with DPI scaling support (currently only GTK 3 and macOS), logical pixels are the same as DIP, but
+different from physical pixels." Conversions: DIP↔logical with `FromDIP/ToDIP`, physical↔logical
+with `FromPhys/ToPhys`, DIP↔physical by multiplying/dividing by `GetDPIScaleFactor()`.
+
+| | MSW | macOS | GTK3 (Linux default; X11 and Wayland) | GTK2 (opt-out build) |
+|---|---|---|---|---|
+| logical (all window/DC API) | = physical | = DIP (points) | = DIP | = physical |
+| `FromDIP(x)` | x·DPI/96, rounded | identity | identity | identity [source] |
+| `GetContentScaleFactor()` | always 1 | backing scale (1 or 2) | integer GDK scale | 1 |
+| `GetDPIScaleFactor()` | DPI/96 (1.25, 1.5, 1.75…) | = content scale | = content scale | 1 |
+| `GetDPI()` | per window, 96-based | 72 × scale | 96 × scale | 96 |
+| bitmap scale factor | stored; drives bundle selection and `wxMemoryDC` text size; never changes drawn size [source] | stored; drawn size = physical / scale | stored; drawn size = physical / scale | not stored |
+| `wxEVT_DPI_CHANGED` | PMv2 manifest + Win10 1703 | on backing-scale change [source] | GTK ≥ 3.10, wx ≥ 3.3.0 | never |
+| app-level HiDPI | per-monitor v2 manifest | `NSHighResolutionCapable`, `NSPrincipalClass` | automatic; fractional scales rounded to an integer | only global `GDK_SCALE`/`GDK_DPI_SCALE` |
+
+Platforms:
+- **MSW.** Orca ships its own manifest, `src/dev-utils/platform/msw/OrcaSlicer.manifest.in`:
+  `<dpiAware>true/pm</dpiAware>` and `<dpiAwareness>permonitorv2,permonitor</dpiAwareness>`. That
+  is the per-monitor v2 awareness wx needs to send DPI events (`interface/wx/event.h:3585-3590`).
+  On Windows versions that only honour the `permonitor` (v1) fallback, wx's
+  `IsPerMonitorDPIAware()` accepts only PMv2, so no DPI handling runs there [source]
+  `src/msw/nonownedwnd.cpp:IsPerMonitorDPIAware, wxNonOwnedWindow::HandleDPIChange`.
+- **macOS.** `src/dev-utils/platform/osx/Info.plist.in` (the template `src/CMakeLists.txt`
+  configures) sets `NSPrincipalClass=NSApplication` (the key `docs/doxygen/overviews/high_dpi.md:339-341` requires) and
+  `NSHighResolutionCapable=true`. Its standard PPI is 72, not 96 (`include/wx/display.h`
+  `wxDisplay::GetStdPPIValue`; documented `interface/wx/display.h:196-211`).
+- **GTK3** (the Linux build: `option(DEP_WX_GTK3 … ON)` in `deps/CMakeLists.txt`, Flatpak too).
+  "wxGTK only supports integer scaling factors currently and fractional scales are rounded to
+  the closest integer" (`docs/doxygen/overviews/high_dpi.md:348-351`). A Wayland compositor's fractional scale therefore
+  reaches wx as an integer GDK scale.
+- **GTK2** (only with `-DDEP_WX_GTK3=OFF`). `wxHAS_DPI_INDEPENDENT_PIXELS` is defined only for
+  `__WXGTK3__ || __WXMAC__ || __WXQT__` (`include/wx/features.h:115-120`), so GTK2 takes the
+  "real conversion" branch of `FromDIP`. But the GTK2 `wxDisplayImplGTK` does not override
+  `GetScaleFactor()` (only under `GTK_CHECK_VERSION(3,10,0)`, `src/gtk/display.cpp`), and the base
+  `GetPPI()` is `GetStdPPI()*GetScaleFactor()` = 96 (`include/wx/private/display.h:99-103`). Net
+  effect [source]: `FromDIP` is the identity on GTK2 too, and GTK2 HiDPI exists only through the
+  global env vars (`docs/doxygen/overviews/high_dpi.md:353-355`). Code guarded for GTK must still compile there.
+
+Exceptions to "every API takes logical pixels" (`docs/doxygen/overviews/high_dpi.md:169-183`): sizes passed to `wxBitmap`
+constructors and returned by `GetWidth/GetHeight/GetSize` are **physical**;
+`wxBitmapBundle::GetPreferredBitmapSizeFor()` is physical (`GetPreferredLogicalSizeFor()` is the
+logical twin); the bundle **default size** (`FromSVG` argument, `GetDefaultSize()`) is **DIP**.
+`wxGLCanvas` drawing is also physical (see `references/webview-gl-aui-media.md`).
+
+## FromDIP / ToDIP / FromPhys / ToPhys
+
+**Contract** (`interface/wx/window.h:1089-1121`): "A DPI-independent pixel is just a pixel at the
+standard 96 DPI resolution … this scaling may be already done by the underlying toolkit (GTK+,
+Cocoa, ...) automatically. This method performs the conversion only if it is not already done by
+the lower level toolkit." It "is only needed when using hard coded pixel values. It is not
+necessary if the sizes are already based on the DPI-independent units such as dialog units or if
+you are relying on the controls automatic best size determination and using sizers". A component
+equal to `-1` is returned unchanged, so `wxSize(FromDIP(490), -1)` keeps "unspecified"
+(`interface/wx/window.h:1113-1116`). `ToDIP` is the inverse; the doc's use case is persisting window geometry
+DPI-independently (`interface/wx/window.h:1166-1189`).
+
+**Static overloads** `FromDIP(sz|pt|d, const wxWindow* w)` (`interface/wx/window.h:1141-1163`) accept
+`w == nullptr`, but are "discouraged as passing NULL will prevent your application from correctly
+supporting monitors with different resolutions". [source] With null on MSW the DPI comes from
+`wxDisplay().GetPPI()`, the primary display (`src/common/wincmn.cpp` `GetDPIHelper`); on
+macOS/GTK the conversion is the identity regardless.
+
+**FromPhys/ToPhys** (`interface/wx/window.h:1233-1321`): physical↔logical; "does nothing under MSW, but divides
+the input value by the content scale factor under the other platforms", rounding to the closest
+integer ("15 physical pixels are translated to 8"). The static form with a null window uses "the
+content scale factor of the main screen if supported" (`interface/wx/window.h:1270-1282`); [source] that is
+macOS only, 1 elsewhere (`src/common/wincmn.cpp` `GetContentScaleFactorFor`). Use them for genuinely physical quantities only (bitmap pixel
+sizes, GL viewports), never for layout constants.
+
+**Platforms** [source]:
+- MSW rounds per call (`wxMulDivInt32`, `include/wx/private/rescale.h`), so
+  `FromDIP(a) + FromDIP(b)` can differ from `FromDIP(a + b)` by 1 px at 125 %/175 %. Convert the
+  sum when two values must line up.
+- MSW `GetDPI()` on a window without an HWND (two-step creation, or `this` inside a base-class
+  argument) falls back to the top-level parent's HWND, else to the screen DC — the primary
+  monitor (`src/msw/window.cpp` `wxWindowMSW::GetDPI`; the "possibly wrong DPI" log is compiled
+  out in Orca).
+- The `interface/wx/window.h:1101-1106` example `wxBitmap bmp(FromDIP(32, 32))` contradicts the physical-bitmap
+  rule (`docs/doxygen/overviews/high_dpi.md:173-178`) and gives a 1x bitmap on macOS/GTK3; use the `wxBitmap` creation helpers instead
+  (§wxBitmap).
+
+**OrcaSlicer.** `FromDIP(n)` is the convention for every fixed size in new code. Shared
+macros build on the member form and expand only inside a `wxWindow` member function:
+`ICON_SINGLE_SIZE`/`ICON_SIZE` (`GUI_Utils.hpp`, `FromDIP(16)`; their comment says not to change
+them and to define new sizes locally) and `MSG_DIALOG_BUTTON_SIZE` (`MsgDialog.hpp`).
+`create_scaled_bitmap` uses the static form because its `win` argument may be null.
+
+**Pitfalls**
+- **Rule:** Never call a member function through a `wxWindow*` that is allowed to be null; use
+  the static null-safe overload.
+  **Why:** `win->FromDIP()` on null is UB; clang assumes `this != nullptr` and deletes later
+  `win ? … : …` checks, turning the fallback into a call through a null vtable. This crashed
+  LLVM/clang-cl builds at startup while MSVC survived by luck. The static overload falls back to
+  the primary-display DPI on MSW and is the identity on macOS/GTK.
+  ```cpp
+  unsigned h = win->FromDIP(px_cnt);              // Wrong: UB when win == nullptr
+  unsigned h = wxWindow::FromDIP(px_cnt, win);    // Right: static, null-safe
+  ```
+  Cite: fd80ded5a8 (`src/slic3r/GUI/wxExtensions.cpp` `create_scaled_bitmap`).
+- **Rule:** In base-class constructor arguments convert through the parent, not `this`.
+  **Why:** `this` is not yet a constructed window there; on MSW (and GTK2) the member form calls
+  the virtual `GetDPI()` on it, which is UB, and even a constructed window without an HWND
+  reports the primary monitor's DPI. On macOS/GTK3 the member form is the identity, so the bug
+  shows only on Windows.
+  ```cpp
+  MyPanel(wxWindow* p) : wxPanel(p, wxID_ANY, wxDefaultPosition, wxSize(FromDIP(300), -1)) {}    // Wrong
+  MyPanel(wxWindow* p) : wxPanel(p, wxID_ANY, wxDefaultPosition, wxSize(p->FromDIP(300), -1)) {} // Right
+  ```
+  Cite: [source] `src/msw/window.cpp` `wxWindowMSW::GetDPI`.
+
+## Scale factors and GetDPI
+
+**Contract.**
+- `GetDPIScaleFactor()` (`interface/wx/window.h:1605-1626`): "1 for standard DPI screens or 2 for '200%
+  scaling' and, unlike for GetContentScaleFactor(), is the same under all platforms. This factor
+  should be used to increase the size of icons and similar windows whose best size is not based
+  on text metrics … should *not* be used for window sizes expressed in pixels, as they are
+  already scaled by this factor by the underlying toolkit under some platforms. Use FromDIP() for
+  anything window-related instead." It answers "how many physical pixels per DIP", i.e. which
+  raster resolution to produce.
+- `GetContentScaleFactor()` (`interface/wx/window.h:1576-1603`): "the factor mapping logical pixels of this
+  window to physical pixels"; on platforms without pixel mapping (MSW) it "always returns 1.0".
+  Note in the doc: it equalled `GetDPIScaleFactor()` in wx 3.1.0–3.1.3 only. Use it for physical
+  buffers (GL, `FromPhys`), not to choose icon sizes.
+- `GetDPI()` (`interface/wx/window.h:2285-2295`): per window, can differ between windows on Windows 10;
+  `wxSize(0,0)` if unavailable. On macOS it is 72-based: `wxWindowMac::GetDPI()` is
+  `MakeDPIFromScaleFactor(GetDPIScaleFactor())` = 72 × scale [source] `src/osx/window_osx.cpp`.
+
+**Platforms** [source]: macOS `GetContentScaleFactor()` is the `NSWindow`'s
+`backingScaleFactor`, or the main screen's when the view has no window yet
+(`src/osx/cocoa/window.mm` `wxWidgetCocoaImpl::GetContentScaleFactor`). GTK returns
+`gtk_widget_get_scale_factor` (an integer; 1 on GTK2), and `GetDPIScaleFactor()` is the same value
+(`src/gtk/window.cpp` `wxWindowGTK::GetContentScaleFactor/GetDPIScaleFactor`).
+
+**Pitfalls**
+- **Rule:** Derive a scale with `GetDPIScaleFactor()` or `wxDPIChangedEvent::Scale*`, never by
+  dividing a DPI by 96.
+  **Why:** macOS's standard PPI is 72 (`interface/wx/display.h:203-205`), so `GetDPI().x / 96.0`
+  is 1.5 on a 2x Retina screen and 0.75 on a 1x one.
+  ```cpp
+  double s = GetDPI().x / 96.0;          // Wrong on macOS
+  double s = GetDPIScaleFactor();        // Right
+  ```
+- **Rule:** Choose icon/raster resolution from `GetDPIScaleFactor()`, not
+  `GetContentScaleFactor()`.
+  **Why:** content scale is always 1 on MSW (`interface/wx/window.h:1587-1592`), so icons never grow there.
+
+## Choosing a size unit: FromDIP, em_unit, text metrics
+
+Two scaling currencies coexist in Orca, plus the text metrics wx recommends:
+
+| Unit | Use for | Value per platform |
+|---|---|---|
+| `FromDIP(n)` | fixed sizes in new code: icon sizes, borders, gaps, control heights, min sizes not driven by text | MSW n·DPI/96; macOS/GTK identity |
+| `em_unit` (`em_unit(this)`, `wxGetApp().em_unit()`, `DPIAware::em_unit()`) | the settings code (`Tab`, `OptionsGroup`, `Field`, `ObjectList` columns) and any size that must follow text on Linux; sizes written as multiples, `wxSize(65 * em, 30 * em)` | MSW `max(10, 10 × scale_factor)`; macOS always 10; GTK width of "m" in the window font − 1 (min 10) |
+| text metrics (`GetTextExtent`, best sizes, `ConvertDialogToPixels`) | widths that hold translated text | follow the font everywhere |
+
+The overview prefers text metrics or dialog units over pixel values and calls `FromDIP` "the
+simplest change" (`docs/doxygen/overviews/high_dpi.md:71-78`).
+
+**Platforms.** On GTK, text follows the font DPI and the desktop text-scaling factor (Xft DPI,
+`GDK_DPI_SCALE`) while `FromDIP` stays the identity at GDK scale 1, so a fixed `FromDIP` width
+that fits a label on MSW/macOS can clip it on Linux. That is why `DPIAware` measures `em_unit`
+from the font on GTK (§DPIAware rescale path).
+
+**OrcaSlicer.** `em_unit(wxWindow*)` (`wxExtensions.cpp`) walks to the top-level parent
+(`find_toplevel_parent`) and returns that `DPIDialog`'s or `DPIFrame`'s own `em_unit()`, else
+`wxGetApp().em_unit()`; the per-window value matters when windows sit on monitors with different
+DPI. `wxGetApp().em_unit()` is 10 until `GUI_App::update_fonts` copies the main frame's value
+(called from `MainFrame::on_dpi_changed` and at main-frame setup).
+
+**Pitfalls**
+- **Rule:** Size boxes that contain text from the text, not from a fixed `FromDIP` width.
+  ```cpp
+  label->SetMinSize(wxSize(FromDIP(120), -1));                       // Wrong: clips on GTK text scaling
+  label->SetMinSize(wxSize(label->GetTextExtent(text).x + FromDIP(8), -1)); // Right (or N * em, or -1 + sizer)
+  ```
+  Cite: `docs/doxygen/overviews/high_dpi.md:71-78`; [source] `DPIAware::update_em_unit` comment (`GUI_Utils.hpp`).
+
+## wxEVT_DPI_CHANGED
+
+**Contract** (`interface/wx/event.h:3560-3593`): sent "to each wxTopLevelWindow affected by the
+change, and all its children recursively (post-order traversal)" — on a move to a monitor with a
+different DPI or a system DPI change. "You should almost always call event.Skip() … as many
+controls rely on processing this event in order to update their appearance". The TLW's default
+handler "only sets the new window size, by scaling the current size by the DPI ratio … and also
+ensuring that the window is still bigger than its best size"; to prevent it, handle the event on
+the TLW, `SetSize()` there and do *not* Skip. Documented generators: wxMSW "if and only if" Windows
+10 1703+ with a PerMonitorV2 manifest; wxGTK "when using GTK 3.10 or later and only since
+wxWidgets version 3.3.0".
+
+Helpers (`interface/wx/event.h:3610-3660`): `GetOldDPI()`, `GetNewDPI()`, `Scale(wxSize)`, and since 3.3.0
+`Scale(wxPoint)`/`Scale(wxRect)`, `ScaleX/ScaleY` — old-DPI→new-DPI via `wxMulDivInt32`. Prefer
+them to `GetNewDPI()/96` (72-based on macOS).
+
+**Platforms** [source unless noted]:
+
+| Port | Who generates it | What wx itself rescales |
+|---|---|---|
+| MSW | `WM_DPICHANGED` → `wxNonOwnedWindow::HandleDPIChange` (`src/msw/nonownedwnd.cpp`), only for PMv2-aware windows | `wxWindowMSW::MSWUpdateOnDPIChange` (`src/msw/window.cpp`) recurses from the TLW through every non-TLW child; for each window it first rescales `m_min/maxWidth/Height`, invalidates best size, re-creates the window font at the new PPI (`MSWUpdateFontOnDPIChange`; the TLW's override `wxTopLevelWindowMSW::MSWUpdateFontOnDPIChange` only re-selects its icons and leaves the TLW font alone), rescales sizer borders, spacer sizes and nested-sizer min sizes (`UpdateSizerOnDPIChange`; window items keep their min size because each window scales its own), then recurses into its children, then sends the event to that window. If the TLW's event was **not processed**, wx `SetSize()`s the TLW to the suggested rect inflated to the sizer's min size |
+| macOS | `windowDidChangeBackingProperties` when the backing scale changes (`src/osx/cocoa/nonownedwnd.mm`), DPIs built from the 72-based std PPI (`wxWindowBase::WXNotifyDPIChange`). Undocumented. The same notification sends `wxSysColourChangedEvent` when the colour space changes | nothing (logical = DIP) |
+| GTK3 | TLW configure event when `GetContentScaleFactor()` changed (`src/gtk/toplevel.cpp` `wxTopLevelWindowGTK::GTKConfigureEvent`, `__WXGTK3__` only); the initial scale is captured at creation, so there is no event at startup; DPIs are 96 × integer scale | nothing (logical = DIP) |
+| GTK2 | never | — |
+
+The default TLW resize exists only on MSW; on macOS/GTK3 logical sizes do not change with DPI.
+
+Handler order: children receive the event before their TLW (post-order, documented; [source]
+`src/common/wincmn.cpp` `NotifyAboutDPIChange`; MSW recursion in `MSWUpdateOnDPIChange`).
+Dynamic handlers run most recently bound first, before static tables
+(`docs/doxygen/overviews/eventhandling.h:475-482`), so a handler you `Bind` on
+a control runs before the control's own (`wxBookCtrlBase`, `wxComboCtrlBase`, `wxTreeCtrlBase` bind
+one; wxMSW `wxStaticBitmap` uses a static table entry, `src/msw/statbmp.cpp`, and MSW button
+bitmaps bind one, `src/msw/anybutton.cpp`).
+
+**What wx rescales vs what Orca must re-apply:**
+
+| Item | MSW (done by wx before the event) | macOS / GTK3 | Orca's `on_dpi_changed` must |
+|---|---|---|---|
+| window min/max sizes | rescaled by the DPI ratio | unchanged (logical = DIP) | re-set only if it recomputes them anyway |
+| window font set by `SetFont` | re-created at the new PPI for non-TLW windows; the TLW keeps its old-PPI font [source] | unchanged (points) | nothing: a `wxFont` stores points and every window or DC `SetFont` re-adjusts it to its target's PPI; `DPIAware::rescale` re-reads it and updates `em_unit` |
+| sizer borders, spacers, nested-sizer min sizes | rescaled | unchanged | nothing |
+| TLW size | resized only if the TLW event is unprocessed — never for DPIAware windows | unchanged | re-establish min size, `Fit()`/`SetSize()` |
+| values given to setters (`SetRowHeight`, column widths, `SetItemMinSize`, custom-widget sizes, cached pixel members) | never | never | re-apply from `FromDIP`/`em_unit` |
+| bitmaps on native controls | reselected from the control's bundle; for Orca's single bitmaps that is the old raster, unscaled or integer-upscaled | GTK never; macOS from the bundle | `msw_rescale()` + `SetBitmap()` |
+| Orca widgets (cached measures, named icons) | never | never | call `Rescale()` |
+
+**Pitfalls**
+- **Rule:** Call `Skip()` in every `wxEVT_DPI_CHANGED` handler you bind, on a child, a control or
+  the TLW (DPIAware's own handler is the one exception).
+  **Why:** your dynamically bound handler runs first; without `Skip()` the control's own handler
+  (book controls, combo controls, MSW static bitmaps and button images) never runs and keeps its
+  old-DPI appearance. Bound on a `DPIDialog`/`DPIFrame` (as `m_parent` is here), it also starves
+  DPIAware's own handler, so `on_dpi_changed` never runs.
+  ```cpp
+  m_parent->Bind(wxEVT_DPI_CHANGED, [this](wxDPIChangedEvent& e) { UpdateButtons(); });             // Wrong
+  m_parent->Bind(wxEVT_DPI_CHANGED, [this](wxDPIChangedEvent& e) { UpdateButtons(); e.Skip(); });   // Right
+  ```
+  Cite: `interface/wx/event.h:3572-3575`; `src/slic3r/GUI/Widgets/DialogButtons.cpp`
+  `DialogButtons::on_dpi_changed`.
+- **Rule:** Do not add a second `wxEVT_DPI_CHANGED` handler on a `DPIDialog` expecting wx to
+  resize the dialog; put the sizing in `on_dpi_changed()`.
+  **Why:** DPIAware's TLW handler never Skips, so the event counts as processed and wxMSW skips
+  its "scale size / ensure ≥ best size" resize.
+  Cite: [source] `src/msw/nonownedwnd.cpp` `wxNonOwnedWindow::HandleDPIChange`.
+
+## DPIAware rescale path (Orca)
+
+`template<class P> DPIAware : public P` (`src/slic3r/GUI/GUI_Utils.hpp`) wraps `wxDialog`/`wxFrame`;
+`DPIFrame` (typedef) and `DPIDialog` (subclass) are the instantiations every Orca top-level window
+uses. Its modal, ESC and dark-mode parts are in `references/windows-dialogs.md` and
+`references/colours-dark-mode.md`; this section is the DPI part.
+
+**Constructor.**
+- `m_scale_factor = get_dpi_for_window(this) / 96` and `m_prev_scale_factor` = the same.
+  `get_dpi_for_window` (`GUI_Utils.cpp`) is real only on Windows (`GetDpiForWindow`, falling back
+  to `GetDpiForMonitor` or the DC); on Linux and macOS it is a `// TODO` stub returning
+  `DPI_DEFAULT` (96), so `m_scale_factor` starts at 1.0 there.
+- `m_normal_font = get_default_font_for_dpi(this, dpi)` (MSW: `SystemParametersInfoForDpi`
+  message font for that DPI; elsewhere `wxSYS_DEFAULT_GUI_FONT`), applied with `SetFont` except
+  on macOS (`#ifndef __WXOSX__`, comment "Don't call SetFont under OSX to avoid name cutting in
+  ObjectList"). The window font is set before `em_unit` is measured because the default window
+  font is the primary display's.
+- `update_em_unit()`:
+  ```cpp
+  #if !defined(__WXGTK__)
+      m_em_unit = std::max<size_t>(10, 10.0f * m_scale_factor);   // MSW: DPI-based; macOS: always 10
+  #else
+      m_em_unit = std::max<size_t>(10, this->GetTextExtent("m").x - 1);   // GTK: from the font
+  #endif
+  ```
+
+**Bindings.**
+- `wxEVT_DPI_CHANGED`, non-macOS only (`#ifndef __WXOSX__`): stores
+  `GetNewDPI().x / 96` in `m_scale_factor` and calls `rescale(wxRect())` if
+  `m_can_rescale && (m_force_rescale || is_new_scale_factor())`. It does **not** `Skip()`: the
+  dialog sizes itself, so wx's MSW TLW resize is suppressed. On GTK3 this handler fires (wx 3.3)
+  and sets a real integer scale from the 96-based DPI; on macOS it is not bound, so
+  `on_dpi_changed` never runs there; on GTK2 there is no event.
+- `wxEVT_MOVE_START`/`wxEVT_MOVE_END` (wxMSW-only events, `interface/wx/event.h:5006-5014`): START
+  clears `m_can_rescale`, so a DPI event during an interactive drag only records the new factor;
+  END rescales with the move rect if the factor changed, else re-arms `m_can_rescale`. The DPI
+  handler itself is what rescales; MOVE_END only performs a rescale that was deferred.
+- `enable_force_rescale()` makes the next DPI event rescale even if the factor is unchanged.
+
+**`rescale(suggested_rect)`**: `Freeze()` → `m_normal_font = GetFont()` (the TLW font, which wxMSW
+does not re-create on a DPI change; harmless, because a `wxFont` stores points and is re-adjusted
+to the PPI of whatever window or DC it is set on) → `update_em_unit()` → pure virtual `on_dpi_changed(suggested_rect)`
+→ `Layout()` → `Thaw()` → `m_prev_scale_factor = m_scale_factor`. `suggested_rect` is empty on the
+DPI-event path and the moved window rect on the MOVE_END path; do not rely on it.
+
+**What `on_dpi_changed` does** (the canonical shape):
+```cpp
+void MyDialog::on_dpi_changed(const wxRect&) {
+    m_logo.msw_rescale();                    // ScalableBitmap: new raster at the new DPI
+    m_logo_ctrl->SetBitmap(m_logo.bmp());    // the control holds its own copy
+    m_ok_btn->Rescale();                     // every Orca widget (Button, TextInput, ComboBox, ...)
+    const int em = em_unit();
+    msw_buttons_rescale(this, em, {wxID_CLOSE});   // native stock-id wxButtons only
+    m_list->SetMinSize(wxSize(-1, 16 * em));       // re-apply stored sizes
+    SetMinSize(wxSize(65 * em, 30 * em));          // explicit minimum + Fit(), or
+    Fit();                                         // GetSizer()->SetSizeHints(this) in place of both
+    Refresh();
+}
+```
+`AboutDialog::on_dpi_changed` is this shape (ScalableBitmap + `SetBitmap`, html fonts re-derived
+from `GetFont()`, `msw_buttons_rescale`, min sizes, `Fit()`, `Refresh()`).
+`PreferencesDialog::on_dpi_changed` shows the child walk: recurse `GetChildren()` and call
+`Rescale()` on each Orca widget found by `dynamic_cast`; inside `namespace Slic3r::GUI` write the
+types qualified (`::CheckBox`, whose method is `Rescale()`, not `msw_rescale()`), because
+unqualified `CheckBox` names the `Field` class there (`references/orca-widgets.md`). wx 3.3's
+`CallForEachChild(functor)` (`interface/wx/window.h:602-624`) does the same recursive walk, the
+window itself included; it also descends into owned top-level children ([source]
+`include/wx/window.h` `wxWindowBase::CallForEachChild`).
+
+**Cascade.** `MainFrame::on_dpi_changed` is the root for the main window: `update_fonts`, the
+tab panel / top bar / buttons `Rescale()`, `plater()->msw_rescale()`, the param panel, lazily
+built pages through `when_built`, then a `SetSize(sz + 1)`/`SetSize(sz)` jiggle (with
+un-maximize/re-maximize) to force a full redraw. Child panels expose `msw_rescale()`/`Rescale()`
+and are called from their owner; they do not get `on_dpi_changed`.
+
+**Self-rescaling components.** `DialogButtons` binds its parent's `wxEVT_DPI_CHANGED` in the ctor,
+unbinds in the dtor, restyles and `Skip()`s. Being bound after DPIAware's handler, it runs first.
+This is the model for a component that must rescale without its owner's help. Keep one-time
+`Bind` calls out of the restyle function such a handler runs: `Bind` does not deduplicate, so a
+handler bound there runs once more after every DPI change.
+
+**Helpers.**
+- `msw_buttons_rescale(dlg, em, ids)` (`wxExtensions.cpp`; all platforms despite the name) calls
+  `SetMinSize(wxSize(-1, 2.5 * em))` on whatever window has each id. Meant for native `wxButton`s;
+  an Orca `Button` with that id (every `DialogButtons` OK/Cancel) takes it too and loses its style
+  height through `Button::SetMinSize`, so leave it out for Orca buttons
+  (`references/sizers-layout.md` §Layout on DPI change).
+- `scale_factor()`/`prev_scale_factor()` are meaningful only on MSW (and on GTK3 after a DPI
+  event); `em_unit()`, `normal_font()` are the per-window values.
+
+**Pitfalls**
+- **Rule:** On GTK derive `em_unit` from the current font, and use the same computation in the
+  ctor and the rescale path (one helper).
+  **Why:** on GTK `DPIAware` starts with scale 1.0 because Orca's `get_dpi_for_window` is a stub
+  there; only the GTK3 `wxEVT_DPI_CHANGED` sets a real (integer) scale. The defect 40eab797c6 fixed: the ctor
+  measured the font while `rescale()` used `max(10, 10 × scale)` — e.g. 20 at 2× — so controls laid
+  out with a different em after a Linux DPI change than at construction.
+  ```cpp
+  m_em_unit = std::max<int>(10, 10.0f * m_scale_factor);   // Wrong: in rescale(), on every platform
+  update_em_unit();                                        // Right: same platform-branched helper as the ctor
+  ```
+  Cite: 40eab797c6 (`src/slic3r/GUI/GUI_Utils.hpp` `DPIAware::update_em_unit`).
+- **Rule:** In `on_dpi_changed`/`msw_rescale`, re-apply every size computed from `em_unit` or
+  `FromDIP` at construction (row heights, column widths, min sizes, cached pixel members).
+  **Why:** wx never rescales values passed to setters (`SetRowHeight`, column widths) on any
+  port; wxMSW only rescales stored min/max sizes and sizer spacers. Stale values clip or
+  overflow after a DPI or theme change (the object-list filament badge stopped fitting its row).
+  ```cpp
+  // ctor:           SetRowHeight(2 * em + FromDIP(2));
+  // msw_rescale():  SetRowHeight(2 * em + FromDIP(2));   // must repeat with the new em
+  //                 GetColumn(cn)->SetWidth(m_columns_width[cn] * em);
+  ```
+  Cite: d5638273c6 (`src/slic3r/GUI/GUI_ObjectList.cpp` `ObjectList::create_objects_ctrl`,
+  `ObjectList::msw_rescale`). Layout side: `references/sizers-layout.md`.
+- **Rule:** In `on_dpi_changed`, re-establish the minimum and resize: `GetSizer()->SetSizeHints(this)`
+  (does both), or `SetMinSize(...)` then `Fit()`/`SetSize()`; never leave a dialog without a
+  minimum that re-`Fit()`s on refresh paths.
+  **Why:** on MSW nothing else resizes a DPIAware dialog (wx's TLW resize is suppressed), so
+  `Refresh()` alone leaves it at its old physical size. A `Fit()` on a dialog without size hints
+  can collapse it on GTK when children are transiently zero-sized (after iconizing the main
+  window); with hints in place `Fit()` is safe. `wxSizer::SetSizeHints(win)` "first calls Fit()
+  and then wxTopLevelWindow::SetSizeHints()" (`interface/wx/sizer.h:937-970`), so a `Fit()` right
+  before it is redundant, and one after it re-applies the best size without the display clamp
+  (`references/sizers-layout.md` §Fitting functions); plain `Fit()` sets no minimum.
+  ```cpp
+  Layout(); Fit();                                   // Wrong: ctor, no enforced minimum
+  void on_dpi_changed(const wxRect&) override { Refresh(); Fit(); }
+  Layout(); Fit(); v_sizer->SetSizeHints(this);      // Right: ctor (the Fit() is redundant)
+  void on_dpi_changed(const wxRect&) override { GetSizer()->SetSizeHints(this); Refresh(); }
+  ```
+  Cite: f760f4e462 (`src/slic3r/GUI/calib_dlg.cpp` `FlowRateCalibrationDialog`; the GTK collapse
+  mechanism is from the commit message, not visible in source); mechanism in
+  `references/sizers-layout.md`.
+- **Rule:** Do not size anything from `scale_factor()`/`prev_scale_factor()` off MSW.
+  **Why:** `get_dpi_for_window()` returns a hard-coded 96 on Linux and macOS, so the factor is 1
+  at construction there (on GTK3 it can later jump to the event's integer scale; on macOS it
+  never changes).
+  ```cpp
+  int w = int(120 * scale_factor());   // Wrong: 120 px on a Retina Mac / 2x GTK3 at startup
+  int w = FromDIP(120);                // Right
+  ```
+
+## wxBitmap: physical size, scale factor, logical size
+
+**Contract.**
+- Size arguments of `wxBitmap` constructors and `GetWidth/GetHeight/GetSize` are physical
+  (`docs/doxygen/overviews/high_dpi.md:173-178`, `interface/wx/bitmap.h:788-800`).
+- `CreateWithDIPSize(size, scale)` (`interface/wx/bitmap.h:486-521`): physical size = `size × scale`, rounded;
+  afterwards `GetDIPSize() == size`, `GetScaleFactor() == scale`. For fixed (compile-time) sizes.
+  `CreateScaled` is its older synonym (`interface/wx/bitmap.h:579`).
+- `CreateWithLogicalSize(size, scale)` (since 3.3.0, `interface/wx/bitmap.h:523-558`): for sizes from
+  `GetClientSize()` etc. with `scale = GetDPIScaleFactor()`; physical = `size` on MSW,
+  `size × scale` where `wxHAS_DPI_INDEPENDENT_PIXELS` is defined.
+- `GetLogicalSize()` (`interface/wx/bitmap.h:685-706`): physical / scale factor on DPI-independent ports,
+  `GetSize()` elsewhere; "must be used in any computations involving the sizes expressed in
+  logical units" (`docs/doxygen/overviews/high_dpi.md:176-178`). `GetScaledSize/Width/Height` are its older synonyms.
+  `GetDIPSize()` (`interface/wx/bitmap.h:645-659`) is the same value on all platforms and "should not be used
+  as window or device context coordinates".
+- `SetScaleFactor(scale)` (`interface/wx/bitmap.h:951-966`) changes no pixels, only the apparent drawn size,
+  "in the ports in which logical and physical pixels differ (i.e. wxOSX and wxGTK3, but not
+  wxMSW)". The doc of `GetScaleFactor()` says it "always returns 1 under the other platforms"
+  (`interface/wx/bitmap.h:744-751`) — **[source] contradicted on MSW**: `wxGDIImage` stores the factor "to use
+  the correct sizes in the code which uses it to decide on the bitmap size to use"
+  (`src/msw/gdiimage.cpp` `wxGDIImage::SetScaleFactor`, `GetDIPSize`); bundle selection reads
+  it (§wxBitmapBundle) and the MSW memory DC sizes text by it (§wxFont). GTK2 has no scale storage (`include/wx/gtk/bitmap.h`, `__WXGTK3__` only).
+- `wxBitmap(const wxImage&, int depth, double scale)` exists on all three ports [source], but the
+  MSW one ignores `scale` (`double WXUNUSED(scale)`, `include/wx/msw/bitmap.h:68`); call
+  `SetScaleFactor()` afterwards on MSW. The `scale` argument does not resize: it declares that
+  the image is already sized for that backing scale (Orca's comments in `BitmapCache.cpp`
+  `wxImage_to_wxBitmap_with_alpha` and `BitmapComboBox.cpp` say the same). `wxBitmap(img, dc)`
+  inherits the DC's scale (`interface/wx/bitmap.h:370-385`).
+- `wxBitmap(const wxCursor&)` is invalid on GTK under Wayland (`interface/wx/bitmap.h:388-401`).
+- wxMSW `wxBitmap::Create(size, dc)` no longer multiplies by the DC's content scale
+  (`docs/changes.txt:94-96`).
+
+**Offscreen drawing.** "The scaling factor of the bitmap determines the scaling factor used by
+this device context" (`interface/wx/dcmemory.h:41-58`); `wxMemoryDC(wxDC*)` does **not** inherit
+the DC's scaling (`interface/wx/dcmemory.h:80-89`). The cross-platform shape needs no `#ifdef`:
+```cpp
+wxBitmap bmp;
+bmp.CreateWithDIPSize(wxSize(24, 24), GetDPIScaleFactor());   // fixed-size art
+{ wxMemoryDC mdc(bmp); mdc.SetFont(GetFont()); /* draw in logical coords: FromDIP() values */ }
+dc.DrawBitmap(bmp, pos);                                       // 24 DIP, sharp on Retina/GTK3
+// back buffer: bmp.CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor());
+```
+[source] On MSW the memory DC does not scale coordinates (logical = physical there, so a
+`CreateWithDIPSize` bitmap is drawn with `FromDIP` coordinates), but it does size text by the
+bitmap: `wxMemoryDCImpl::DoSelect` records the selected bitmap's scale factor and
+`wxMemoryDCImpl::SetFont` adjusts every font to `GetPPI()` = 96 × that factor
+(`src/msw/dcmemory.cpp`). The macOS memory DC applies the bitmap scale to its graphics context
+(`src/osx/core/dcmemory.cpp`). Back-buffering and DC coordinates are in
+`references/painting-custom-widgets.md`.
+
+**OrcaSlicer.** `SwitchButton::Rescale` is the legacy manual HiDPI pattern: on macOS it measures
+with `dc.GetFont().Scaled(scale)`, draws into a `scale ×` image and wraps it with
+`wxBitmap(img, -1, scale)`, using `mac_max_scaling_factor()`; on MSW it draws into a scale-1
+bitmap with `GetFont().Scaled(GetDPIScaleFactor())` (compensating the memory DC's 96-PPI text) and
+tags the result with `SetScaleFactor` afterwards. New owner-drawn caches use `CreateWithDIPSize`/`CreateWithLogicalSize` +
+`wxMemoryDC` instead.
+
+**Pitfalls**
+- **Rule:** Create drawn bitmaps with a DIP size and the window's scale.
+  **Why:** bitmap sizes are physical and `FromDIP` is the identity on macOS/GTK3, so the first
+  form is a 1x bitmap upscaled (blurry) on Retina and 2x GTK3; on MSW its scale factor stays 1, so
+  text drawn into it through a `wxMemoryDC` comes out at 100 % size.
+  ```cpp
+  wxBitmap bmp(FromDIP(wxSize(32, 32)));                                    // Wrong
+  wxBitmap bmp; bmp.CreateWithDIPSize(wxSize(32, 32), GetDPIScaleFactor()); // Right
+  ```
+  Cite: `docs/doxygen/overviews/high_dpi.md:173-178`, `interface/wx/dcmemory.h:41-56`.
+- **Rule:** Lay out from logical bitmap sizes.
+  **Why:** physical ≠ logical off MSW; `GetSize()` of a 2x bitmap is twice its drawn size.
+  ```cpp
+  int w = bmp.GetWidth() + FromDIP(4);          // Wrong: double width on Retina
+  int w = bmp.GetLogicalSize().x + FromDIP(4);  // Right (ScalableBitmap::GetBmpWidth() for Orca icons)
+  ```
+  Cite: `interface/wx/bitmap.h:685-706`.
+
+## wxBitmapBundle and its limits in Orca's build
+
+**Contract.**
+- Any API taking `const wxBitmapBundle&` accepts a `wxBitmap` through the implicit converting
+  constructor (`interface/wx/bmpbndl.h:110-116`). This is how every Orca bitmap reaches wx
+  controls: Orca code does not build bundles itself.
+- Selection (`docs/doxygen/overviews/high_dpi.md:245-255`, `interface/wx/bmpbndl.h:52-62`): use the closest existing bitmap without
+  scaling; scale only when the mismatch is large. The overview says "equal or greater than 1.5";
+  **[source]** the code scales only when the target scale is **greater than** 1.5 × the largest
+  available, and then by an integer factor (or rounds the target scale)
+  (`src/common/bmpbndl.cpp` `wxBitmapBundleImpl::DoGetPreferredSize`).
+- Single-bitmap bundle [source] (`bmpbndl.cpp` `wxBitmapBundleImplSet::Init`,
+  `GetNextAvailableScale`): default size = `GetDIPSize()` of the smallest bitmap; its available
+  scale = (DIP size / default size) × `GetScaleFactor()`. Consequences: a 16 px bitmap with
+  scale 1 is shown unscaled at 150 % and upscaled to 32 px at 175 %/200 %; a 24 px bitmap tagged
+  `SetScaleFactor(1.5)` has DIP size 16 and is used as-is at 150 %.
+- `GetBitmap(size)` (`interface/wx/bmpbndl.h:415-428`): size "in physical pixels"; dynamically created sizes
+  are cached until exit ("avoid calling it for many different sizes"). [source] the result gets
+  `SetScaleFactor(size.y / GetDefaultSize().y)` (`bmpbndl.cpp` `wxBitmapBundle::GetBitmap`), so
+  `GetBitmap(GetDefaultSize())` always yields a scale-1 bitmap at the DIP size — a downscaled 1x
+  bitmap on HiDPI.
+- `GetBitmapFor(win)`, `GetPreferredBitmapSizeFor(win)` (physical),
+  `GetPreferredLogicalSizeFor(win)` (logical) take a "Non-null and fully created window"
+  (`interface/wx/bmpbndl.h:392-441`); null hits a `wxCHECK` and returns `wxDefaultSize` silently in Orca.
+- `FromBitmaps(vec)` / `FromBitmaps(b1, b2)` (`interface/wx/bmpbndl.h:158-169`): all bitmaps valid, sizes
+  physical, the smallest defines the default size. `FromImpl(new MyImpl)` takes ownership ("must
+  not call DecRef()", `interface/wx/bmpbndl.h:200-212`). `FromFiles` also looks in a `2.0x` subdirectory since
+  3.3.2 (`interface/wx/bmpbndl.h:231-247`). A custom `wxBitmapBundleImpl` implements `GetDefaultSize()` (DIP),
+  `GetPreferredBitmapSizeAtScale()` (physical; may defer to `DoGetPreferredSize()` when
+  `GetNextAvailableScale()` is overridden) and non-const `GetBitmap(size)` (`interface/wx/bmpbndl.h:522-560`).
+- Auto-update on DPI change happens only on MSW and macOS (`docs/doxygen/overviews/high_dpi.md:205-209`); GTK controls
+  keep the bitmap chosen at set time.
+- The overview asks for art usable unscaled at least at 100 % and 200 % (or a single SVG), and
+  advises against shipping only a high-resolution version to be downscaled on 1x displays
+  ("contours become more blurry", `docs/doxygen/overviews/high_dpi.md:189-197`). In Orca the SVG
+  route is `BitmapCache`, not a bundle (below).
+
+**Orca's build.** `deps/wxWidgets/wxWidgets.cmake` passes `-DwxUSE_NANOSVG=OFF` (7658cf9076,
+duplicate symbols with Orca's own nanosvg) and LunaSVG stays off, so `wxHAS_SVG` — defined only for
+`wxHAS_RAW_BITMAP && (wxUSE_NANOSVG || wxUSE_LUNASVG)` (`include/wx/features.h:96-98`) — is
+undefined. `wxBitmapBundle::FromSVG`, `FromSVGFile` and `FromSVGResource` do not exist (compile
+error; `interface/wx/bmpbndl.h:272-275` says to check `wxHAS_SVG`). Knock-on effects [source]: the Tango art
+provider returns empty bundles (`src/common/arttango.cpp`, `!wxHAS_SVG` branch), the std
+provider's SVG logo is absent (`src/common/artstd.cpp`), and wxAUI tab/dock buttons fall back to
+1-bit XBM art (`src/aui/tabart.cpp`, `src/aui/dockart.cpp`). Orca rasterizes SVG itself
+(`BitmapCache::load_svg`) and recolours it for dark mode, which a stock bundle could not do.
+
+**Why Orca keeps single bitmaps + explicit rescale** rather than bundles: no SVG bundles in this
+build; GTK does not auto-update bundles anyway; owner-drawn widgets must re-measure on DPI change;
+and the icon raster must also change on a theme switch. The MSW `SetScaleFactor` tagging in
+`create_scaled_bitmap` makes the implicit single-bitmap bundle report the intended DIP size
+(§Orca icon pipeline).
+
+If a stock wx control ever needs auto-updating multi-resolution art, the Orca-compatible shape
+is a bundle implementation backed by `BitmapCache` (not existing Orca code; a sketch):
+```cpp
+struct OrcaSvgBundleImpl : wxBitmapBundleImpl {
+    std::string name; wxSize def;                                  // def in DIP
+    wxSize GetDefaultSize() const override { return def; }
+    wxSize GetPreferredBitmapSizeAtScale(double s) const override { return def * s; }
+    wxBitmap GetBitmap(const wxSize& sz) override {                // sz is physical
+        static Slic3r::GUI::BitmapCache cache;
+        wxBitmap* b = cache.load_svg(name, 0, sz.y, false, wxGetApp().dark_mode());
+        return b ? *b : wxBitmap();
+    }
+};
+// wxBitmapBundle::FromImpl(new OrcaSvgBundleImpl{...});   // takes ownership
+```
+On macOS `BitmapCache` already multiplies by its own `m_scale`; such an impl would need a cache
+whose scale is 1.
+
+**Pitfalls**
+- **Rule:** Never call `wxBitmapBundle::FromSVG*` in Orca.
+  ```cpp
+  auto b = wxBitmapBundle::FromSVGFile(path, wxSize(16, 16));   // Wrong: does not compile here
+  ScalableBitmap icon(this, "cog", 16);                         // Right (or create_scaled_bitmap("cog", this, 16))
+  ```
+  Cite: `include/wx/features.h:96-98`, `deps/wxWidgets/wxWidgets.cmake`.
+- **Rule:** Draw a bundle at the bitmap the window needs.
+  **Why:** the size argument of `GetBitmap` is physical and the result is forced to scale 1.
+  ```cpp
+  wxBitmap b = bundle.GetBitmap(bundle.GetDefaultSize());   // Wrong: 1x, downscaled on HiDPI
+  wxBitmap b = bundle.GetBitmapFor(this);                   // Right; draw at b.GetLogicalSize()
+  ```
+  Cite: [source] `src/common/bmpbndl.cpp` `wxBitmapBundle::GetBitmap`; `interface/wx/bmpbndl.h:425`.
+- **Rule:** Pass a created, non-null window to bundle size queries.
+  ```cpp
+  bundle.GetPreferredBitmapSizeFor(nullptr);   // Wrong: wxDefaultSize, silently
+  bundle.GetPreferredBitmapSizeFor(this);      // Right, after Create()
+  ```
+  Cite: `interface/wx/bmpbndl.h:399`.
+
+## Orca icon pipeline
+
+Icons are SVG files in `resources/images/`, referenced by **name string without extension**
+(`BitmapCache` resolves `Slic3r::var(name + ".svg")`, then `".png"`). The entry points live in
+`src/slic3r/GUI/wxExtensions.hpp/.cpp` and `BitmapCache.hpp/.cpp`.
+
+**`create_scaled_bitmap(name, win = nullptr, px_cnt = 16, grayscale, new_color, menu_bitmap,
+resize, bitmap2, array_new_color)`**:
+```cpp
+static BitmapCache cache;                                     // process-wide, never cleared
+unsigned h = wxWindow::FromDIP(px_cnt, win) + 0.5f;           // static overload: win may be null
+bool dark = menu_bitmap (MSW only) ? check_dark_mode() : wxGetApp().dark_mode();
+wxBitmap* b = cache.load_svg(name, 0, h, grayscale, dark, new_color, resize ? em_unit(win) * 0.1f : 0);
+if (!b) b = cache.load_png(name, 0, h, grayscale, ...);       // neither found: throws Slic3r::RuntimeError
+#ifdef __WXMSW__
+b->SetScaleFactor(win ? win->GetDPIScaleFactor() : wxWindow::FromDIP(100, nullptr) / 100.0);
+#endif
+return *b;
+```
+`px_cnt` is the icon height in DIP. A missing icon name throws. `bitmap2 = true` routes to
+`create_scaled_bitmap2`/`load_svg2` (semi-transparent filament art, no dark recolour).
+
+Raster per platform [source]:
+
+| Platform | Physical height | Scale factor | Drawn (logical) size |
+|---|---|---|---|
+| MSW | `FromDIP(px, win)` | `win->GetDPIScaleFactor()` (primary-display ratio when `win` is null) | `FromDIP(px)` px; the tag makes the implicit bundle's DIP size `px`, so wx uses it unscaled |
+| macOS | `px × BitmapCache::m_scale` (SVG) | `m_scale`, via `wxBitmap(image, -1, m_scale)` | `px` points |
+| GTK3 | `px` | 1 | `px`; at GDK scale 2 it is drawn upscaled (no HiDPI raster on GTK3) |
+| GTK2 | `px`, round-tripped through PNG to fix broken alpha (`wxImage_to_wxBitmap_with_alpha`) | — | `px` |
+
+Why the MSW tag matters: at 200 % `FromDIP(16)` is a 32 px raster; untagged (scale 1) its
+implicit bundle has a 32-DIP default size and wx doubles it again to 64 px, while tagged 2.0 its
+DIP size is 16 and it is used as-is. A raster kept from an older DPI is reselected by the same
+rule after a DPI change: a 16 px / scale-1 bitmap stays 16 px at 150 % and is upscaled to 32 px
+at 200 % — hence the re-`SetBitmap` in `on_dpi_changed` (§wxBitmapBundle selection).
+
+`BitmapCache` [source]:
+- `m_scale` (macOS only) is `mac_max_scaling_factor()` read when the cache is constructed — for
+  the static cache in `create_scaled_bitmap`, at the first icon load. Despite its name,
+  `mac_max_scaling_factor()` (`src/slic3r/Utils/MacDarkMode.mm`) loops over the screens but
+  reads `objectAtIndex:0` each time, i.e. it returns the backing factor of the first screen (the
+  one with the menu bar). Icons are therefore rasterized once for that screen: 1x on a Retina
+  laptop whose primary display is a 1x external monitor, with no re-rasterization when windows
+  move.
+- `load_svg` keys the cache by name, height, `m_scale`, `-dm` (dark), `-gs` (grayscale) and
+  `new_color`; dark-mode recolouring by palette substitution is in
+  `references/colours-dark-mode.md`.
+- `load_png` never applies the Retina factor (`wxImage_to_wxBitmap_with_alpha(image)` with scale
+  1; resized with `wxIMAGE_QUALITY_BILINEAR`) and gets no dark recolour.
+
+**`ScalableBitmap(parent, icon_name = "", px_cnt = 16, grayscale, resize, bitmap2, new_color)`**
+holds `{m_parent, m_icon_name, m_px_cnt, m_grayscale, m_resize, m_bmp}`.
+- `msw_rescale()` re-runs `create_scaled_bitmap(m_icon_name, m_parent, m_px_cnt, m_grayscale,
+  "", false, m_resize)` — it is the DPI path on every platform and also the theme-switch path,
+  because it re-reads the dark flag. It does **not** re-apply `new_color` or `bitmap2`.
+- `m_parent` is a raw pointer; the parent must outlive the `ScalableBitmap`.
+- `GetBmpSize()/GetBmpWidth()/GetBmpHeight()` return the scaled (logical) size on Apple and
+  `GetSize()` elsewhere — equivalent to `GetLogicalSize()` given the scales above.
+- `bmp()` returns the bitmap; wx controls that were given it keep their own copy.
+
+**`ScalableButton(parent, id, icon_name, label, size, pos, style = wxBU_EXACTFIT | wxNO_BORDER,
+use_default_disabled_bitmap, bmp_px_cnt = 16)`** is a native `wxButton` with a scaled bitmap. An
+explicit `size` is stored in em/10 units (`size * 10 / em`) and re-applied as `m * em / 10` in
+`msw_rescale()`; `UpdateDarkUI()` is `msw_rescale()`; on GTK it calls `RemoveButtonBorder`. New
+code uses `Widgets/Button` instead.
+
+**Orca widgets.** `Button(parent, text, icon = "", style = 0, iconSize = 0, id)` keeps its icon
+as a `ScalableBitmap` (20 px when `iconSize <= 0`). `Button::Rescale()` re-rasterizes a **named**
+icon, re-measures and re-applies the style; an icon set through `SetIcon(const wxBitmap&)` has no
+name and cannot be re-rasterized, so prefer `SetIcon(const wxString&)`. Other widgets' `Rescale()`
+follow the same idea (`references/orca-widgets.md`, `references/painting-custom-widgets.md`).
+
+**Menu icons.** `create_menu_bitmap(name)` = `create_scaled_bitmap(name, nullptr, 16, false, "",
+true)`: created without a window, so at primary-display DPI on MSW, and on MSW the dark variant
+follows `check_dark_mode()`. `msw_rescale_menu` exists only on MSW. Menus
+are in `references/popups-menus.md`.
+
+**Pitfalls**
+- **Rule:** Pass the real window (not `nullptr`) and re-create the bitmap in `on_dpi_changed`.
+  **Why:** a null window means primary-display DPI on MSW (wrong raster and wrong scale tag on a
+  secondary monitor); `em_unit(nullptr)` falls back to the main frame's em for `resize`.
+  ```cpp
+  m_icon = ScalableBitmap(nullptr, "cog", 16);   // Wrong
+  m_icon = ScalableBitmap(this, "cog", 16);      // Right; m_icon.msw_rescale() in on_dpi_changed
+  ```
+- **Rule:** After `msw_rescale()`, hand the new bitmap to every control that displays it.
+  **Why:** `msw_rescale()` replaces only the `ScalableBitmap`'s own `m_bmp`; a `wxStaticBitmap` or
+  native button keeps the old copy (on MSW wx merely rescales that old raster).
+  ```cpp
+  m_icon.msw_rescale();                                   // Wrong alone
+  m_icon.msw_rescale(); m_bmp_ctrl->SetBitmap(m_icon.bmp()); // Right
+  ```
+  Cite: `src/slic3r/GUI/AboutDialog.cpp` `AboutDialog::on_dpi_changed`.
+- **Rule:** Pass a bare resource name and an explicit DIP height.
+  **Why:** the third argument is `px_cnt`, not a bitmap type, and the name is resolved as
+  `var(name + ".svg"|".png")`. `px_cnt = 0` means "the asset's own height": it dereferences
+  `parent`, and on Retina macOS it stores the physical height, which doubles the icon [source]
+  `ScalableBitmap::ScalableBitmap`.
+  ```cpp
+  ScalableBitmap(this, Slic3r::var("logo.png"), wxBITMAP_TYPE_PNG);   // Wrong: path + type as px_cnt
+  ScalableBitmap(this, "logo", 16);                                   // Right
+  ```
+- **Rule:** Author new icons as SVG.
+  **Why:** `load_png` is never Retina-scaled and never dark-recoloured.
+- **Rule:** Re-apply `new_color`/`bitmap2` art yourself on rescale.
+  **Why:** `ScalableBitmap::msw_rescale()` drops both, so a recoloured icon reverts to its default
+  colours after a DPI or theme change. Keep the colour and rebuild with the full constructor.
+
+## Image lists, art provider, wxImage
+
+**`wxImageList`** (`interface/wx/imaglist.h:37-39, 60-63`): "Use of this class is not recommended
+in the new code as it doesn't support showing DPI-dependent bitmaps. Please use
+wxWithImages::SetImages() instead"; "the size is specified in physical pixels and must correspond
+to the size of bitmaps … that will be added". 3.3 made the size physical and makes calls on an
+invalid list assert (`docs/changes.txt:53-56, 85-88`) — silently in Orca's assert-free build.
+When a list is unavoidable, `wxBitmapBundle::CreateImageList(win, bundles)` builds one at the
+consensus size (public but undocumented, [source] `include/wx/bmpbndl.h`).
+```cpp
+auto* il = new wxImageList(FromDIP(16), FromDIP(16)); il->Add(bmp_of_other_size);  // Wrong
+auto sz = bmps[0].GetSize(); auto* il = new wxImageList(sz.x, sz.y);                 // Right (or SetImages(bundles))
+```
+
+**`wxArtProvider`** (`interface/wx/artprov.h:285-330`): `GetBitmap(id, client, size)` returns
+that physical size; "applications using wxWidgets 3.1.6 or later should prefer calling
+GetBitmapBundle()". `GetBitmapBundle(id, client, size)` takes the DIP default size — "this
+implies that wxWindow::FromDIP() must not be used with it". The provider stack is native → Tango
+→ std [source] `src/common/artprov.cpp`; in Orca's build Tango contributes nothing (no SVG), so
+non-native ids come from low-resolution XPMs. `GetBitmap(id, client, FromDIP(wxSize(16, 16)))` is a
+16-physical-pixel bitmap on Retina/GTK3 (drawn upscaled); hand the bundle to the control instead.
+```cpp
+wxArtProvider::GetBitmapBundle(wxART_WARNING, wxART_OTHER, FromDIP(wxSize(16, 16)));  // Wrong: double-scaled on MSW
+wxArtProvider::GetBitmapBundle(wxART_WARNING, wxART_OTHER, wxSize(16, 16));           // Right; give the bundle to the control
+```
+
+**`wxImage`** resizing (`interface/wx/image.h:28-89`): `wxIMAGE_QUALITY_NEAREST` is no longer an
+alias of `NORMAL` since 3.3.0 (`docs/changes.txt:98-99`; `wxIMAGE_QUALITY_FAST` is the speed
+synonym). `NORMAL` (default) = bilinear down to an integer multiple, then box average; `HIGH` =
+box average when shrinking, bicubic when enlarging; `BILINEAR`, `BICUBIC`, `BOX_AVERAGE` explicit.
+High-quality scaling "may not work as expected when using a single mask colour for
+transparency" — use alpha (`interface/wx/image.h:1016-1019`). `Rescale` mutates and returns `*this`; `Scale`
+returns a copy. `wxInitAllImageHandlers()` registers the compiled handlers: in Orca there is no
+TIFF (`wxUSE_LIBTIFF=OFF`), WebP is built in, and SVG is not an image handler.
+`wxImage::SetDefaultLoadFlags(0)` drops `Load_Verbose` warnings for images created afterwards
+(`interface/wx/image.h:1825-1838`). For pixel-exact glyphs choose `NEAREST`; for icons `BILINEAR` (what
+`load_png` uses) or `HIGH`; for photos `HIGH`.
+
+## Window icons
+
+`wxTopLevelWindow::SetIcon` (`interface/wx/toplevel.h:505-525`): "In wxMSW, icon must be either
+16x16 or 32x32"; under Wayland it "doesn't do anything … create a `.desktop` file".
+`SetIcons(wxIconBundle)` (`interface/wx/toplevel.h:527-546`): MSW wants 16 and 32, "preferably both"; also a
+no-op on Wayland, where the icon comes from the desktop file matched by app id
+(`wxApp::SetClassName`, `interface/wx/app.h:761-768`). [source] wxMSW picks the small and big
+icon from the bundle at the window's DPI-aware system-metric sizes with `FALLBACK_NEAREST_LARGER`
+and re-picks them on every DPI change (`src/msw/toplevel.cpp` `wxTopLevelWindowMSW::DoSetIcons`,
+`MSWUpdateFontOnDPIChange`), so a bundle with 16/20/24/32/48 px entries stays sharp at any
+scale; `SetIcon` is a one-icon bundle. `wxIconBundle(file,
+type)` loads every icon in the file (`interface/wx/iconbndl.h:53`); `GetIcon(size, flags)` falls
+back per `FALLBACK_SYSTEM` (default), `FALLBACK_NEAREST_LARGER` or `FALLBACK_NONE`
+(`interface/wx/iconbndl.h:29-42, 141-158`).
+
+Orca: the main frame takes its icon from the executable's resource on MSW and from
+`OrcaSlicer_128px.png` elsewhere (`MainFrame.cpp` `main_frame_icon`).
+```cpp
+SetIcon(wxIcon(path_to_multi_size_ico, wxBITMAP_TYPE_ICO));            // Wrong: one size, scaled for both slots
+SetIcons(wxIconBundle(path_to_multi_size_ico, wxBITMAP_TYPE_ICO));     // Right
+```
+
+## Displays and PPI
+
+Window placement on displays is in `references/windows-dialogs.md`; the resolution side:
+- `wxDisplay(const wxWindow*)` (since 3.1.2) is the display showing the window, "falling back to
+  the default display if it is not shown at all or positioned outside of any display"
+  (`interface/wx/display.h:35-50`). `GetFromWindow(win)` returns `wxNOT_FOUND` when the window is
+  on no display (`interface/wx/display.h:115-126`). [source] on macOS it picks an intersecting display with the
+  same backing scale as the window, else `wxNOT_FOUND` (`src/osx/core/display.cpp`
+  `wxDisplayFactoryMacOSX::GetFromWindow`).
+- `GetPPI()` is the scaled resolution, `wxSize(0,0)` if unknown (`interface/wx/display.h:158-168`);
+  `GetRawPPI()` is unscaled, new in 3.3.2 (`interface/wx/display.h:170-181`); `GetScaleFactor()` = PPI / std
+  PPI (`interface/wx/display.h:183-194`); `GetStdPPIValue()` is 96, 72 on Apple (`interface/wx/display.h:196-221`).
+- `IsConnected()` (3.3.0): objects go stale after a display configuration change; recreate them on
+  `wxEVT_DISPLAY_CHANGED`, do not cache `wxDisplay` (`interface/wx/display.h:223-241`).
+- [source] `wxDisplay(unsigned n)` only `wxASSERT`s the index and then indexes a vector
+  (`src/common/dpycmn.cpp`), so `(unsigned)wxNOT_FOUND` reads out of bounds in Orca's
+  assert-free build. `GUI_App::window_pos_sanitize`/`window_pos_center` show the checked pattern.
+```cpp
+wxDisplay(wxDisplay::GetFromWindow(win)).GetClientArea();   // Wrong: wxNOT_FOUND → out of bounds
+wxDisplay(win).GetClientArea();                              // Right (or check != wxNOT_FOUND first)
+```
+
+## wxFont
+
+**Contract.**
+- Sizes are points (1/72 in): `wxFontInfo(double pointSize)` (fractional since 3.1.2,
+  `interface/wx/font.h:323-330`), or pixels via `wxFontInfo(wxSize)` / `SetPixelSize`, which is
+  "directly supported only under wxMSW and wxGTK currently; under other platforms a font with the
+  closest size … is found using binary search" (`interface/wx/font.h:1124-1138`). Prefer
+  `SetFractionalPointSize` to the legacy integer `SetPointSize` (`interface/wx/font.h:1100-1123`).
+- `MakeBold/MakeLarger/MakeSmaller/Scale` mutate; `Bold/Larger/Smaller/Scaled` return copies
+  (`interface/wx/font.h:853-999`); Larger/Smaller use a factor of 1.2.
+- `SetFaceName(face)` (`interface/wx/font.h:1021-1036`): if the face does not exist "the font is invalidated (so
+  that IsOk() will return false) and false is returned" ([source] `src/common/fontcmn.cpp`
+  `wxFontBase::SetFaceName` → `UnRef()`; the check is `wxFontEnumerator::IsValidFacename`, which
+  caches the face list on first use for the session (`src/common/fontenumcmn.cpp`); only the
+  Unix `AddPrivateFont` invalidates that cache).
+- `wxFont::AddPrivateFont(path)` (`interface/wx/font.h:719-751`):
+  - macOS: does nothing but check that the file exists inside `Resources/Fonts` of the bundle;
+    the app must ship it there and set `ATSApplicationFontsPath`. [source] it compares the path
+    with `GetResourcesDir() + "/Fonts"` and `wxLogError`s otherwise (`src/osx/fontutil.cpp`).
+  - MSW: "must be called before any wxGraphicsContext objects have been created";
+    [source] `AddFontResourceEx(FR_PRIVATE)`, remembered for GDI+ (`src/msw/font.cpp`).
+  - Unix: needs Pango ≥ 1.38, else returns false and logs. [source] creates one fontconfig config
+    on the first call, then on **every** call adds the file, re-installs the config into Pango's
+    font map (`pango_fc_font_map_set_config`) and invalidates the face-name cache
+    (`src/gtk/font.cpp` `wxFontBase::AddPrivateFont`).
+
+**DPI** [source]:
+- On MSW a `wxFont` stores points; `SetFractionalPointSize` computes `lfHeight` at the primary
+  screen PPI and relies on `WXAdjustToPPI()` later (`src/msw/font.cpp`
+  `wxNativeFontInfo::SetFractionalPointSize`).
+- `wxWindow::SetFont/GetFont` adjust the window's copy to its own PPI
+  (`src/common/wincmn.cpp` `wxWindowBase::SetFont/GetFont` → `WXAdjustFontToOwnPPI`), and
+  non-TLW window fonts are re-adjusted on DPI change (`src/msw/window.cpp`
+  `MSWUpdateFontOnDPIChange`; `src/msw/toplevel.cpp` overrides it for TLWs to re-select icons
+  only).
+- `wxMSWDCImpl::SetFont` adjusts to the DC's window PPI when it has a window (`src/msw/dc.cpp`).
+  A `wxMemoryDC` has none; `wxMemoryDCImpl` overrides `SetFont`/`GetPPI` instead and adjusts every
+  font to 96 × the scale factor of the bitmap selected into it, re-applied at each `SelectObject`
+  (`src/msw/dcmemory.cpp` `wxMemoryDCImpl::DoSelect/SetFont/GetPPI`). With a scale-1 bitmap text is
+  laid out at 100 % whatever the monitor and whatever font object is passed: `GetFont()` of a
+  150 % window is re-adjusted down to 96 PPI too. A `wxGCDC`/`wxGraphicsContext` created from that
+  memory DC follows the same rule: the GDI+ context has no window, and its DPI is 96 × the bitmap's
+  scale factor (`src/msw/graphics.cpp` `wxGDIPlusRenderer::CreateContext(const wxMemoryDC&)`,
+  `wxGDIPlusContext::GetDPI`) — which is what `StaticBox::render`'s MSW anti-aliasing block hands to
+  `doRender` (`references/painting-custom-widgets.md`).
+- So a global `wxFont` such as `Label::Body_14` is DPI-correct on any monitor when set on a window,
+  a window DC, or a memory DC whose bitmap was given the window's `GetDPIScaleFactor()` before it
+  was selected (`CreateWithDIPSize`/`CreateWithLogicalSize`, or `SetScaleFactor` then
+  `SelectObject`, as `get_extruder_color_icon` in `wxExtensions.cpp` does).
+- On macOS and GTK a point is a fixed number of logical pixels (1 on macOS, 4/3 at 96 DPI on
+  GTK), so fonts need no DPI handling.
+
+**Pitfalls**
+- **Rule:** Check `IsOk()` after `SetFaceName` and fall back.
+  ```cpp
+  font.SetFaceName("X"); dc.SetFont(font);                              // Wrong: invalid font if X is missing
+  if (!font.SetFaceName("X")) font = wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT);  // Right (Label::sysFont pattern)
+  ```
+  Cite: `interface/wx/font.h:1030-1032`.
+- **Rule:** On MSW, give a memory-DC bitmap the window's scale factor before selecting it; the
+  font object does not fix memory-DC text size.
+  **Why:** the MSW memory DC sizes text for 96 × the selected bitmap's scale factor, so text drawn
+  into a scale-1 `FromDIP`-sized bitmap comes out at 100 % size, too small at 125–200 %, even with
+  the window's own `GetFont()`.
+  ```cpp
+  wxBitmap bmp(FromDIP(wxSize(24, 24)));                   // Wrong: scale 1
+  wxMemoryDC mdc(bmp); mdc.SetFont(GetFont());             //        text at 96 PPI on a 150 % monitor
+  wxBitmap bmp; bmp.CreateWithDIPSize(wxSize(24, 24), GetDPIScaleFactor());   // Right
+  wxMemoryDC mdc(bmp); mdc.SetFont(Label::Body_12);        //        text at 144 PPI
+  ```
+  Cite: [source] `src/msw/dcmemory.cpp` `wxMemoryDCImpl::DoSelect`, `wxMemoryDCImpl::SetFont`;
+  `src/slic3r/GUI/wxExtensions.cpp` `get_extruder_color_icon` (`SetScaleFactor` before
+  `SelectObject`).
+
+## Orca fonts: Label table, sysFont, initSysFont
+
+**The table** (`src/slic3r/GUI/Widgets/Label.hpp/.cpp`): static fonts `Label::Head_48, 32, 24, 20,
+18, 16, 15, 14, 13, 12, 11, 10` (bold) and `Label::Body_16, 15, 14, 13, 12, 11, 10, 9, 8` (regular),
+built by `Label::initSysFont()`. Convention: `Head_*` for titles and section headers, `Body_*` for
+content; `Body_14` is the dialog workhorse (`SetFont(Label::Body_14)` on dialogs and controls),
+`Body_12`/`Body_13` for dense secondary text. `Label` widgets default to `Body_14`.
+
+**`Label::sysFont(size, bold)`**:
+```cpp
+#ifndef __APPLE__
+    size = size * 4 / 5;                           // integer arithmetic
+#endif
+wxString face = "HarmonyOS Sans SC";
+if (wxLocale::GetSystemLanguage() == wxLANGUAGE_KOREAN) face = "NanumGothic";
+wxFont font{size, wxFONTFAMILY_SWISS, wxFONTSTYLE_NORMAL, bold ? wxFONTWEIGHT_BOLD : wxFONTWEIGHT_NORMAL, false, face};
+font.SetFaceName(face);
+if (!font.IsOk()) { font = wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT); if (bold) font.MakeBold(); font.SetPointSize(size); }
+```
+- The 4/5 factor approximates the 72-vs-96 PPI difference (a point is 1 logical px on macOS,
+  4/3 px at 96 DPI elsewhere), so the same `Body_N` looks alike on macOS and MSW/Linux. That is
+  why literal point sizes are wrong: 12 pt is 12 logical px on macOS but 16 px at 100 % on MSW, so
+  `wxFont(12, …)` looks a third larger there.
+- Integer truncation makes some entries identical on MSW/Linux: `Body_16`/`Body_15` and
+  `Head_16`/`Head_15` are 12 pt, `Body_11`/`Body_10` and `Head_11`/`Head_10` are 8 pt. Pick the
+  next step down when a visible difference matters.
+- The Korean face is keyed on the **system** language (`wxLocale::GetSystemLanguage()`), not on
+  Orca's UI language.
+- The statics are created once and stay DPI-correct on MSW because wx adjusts fonts per window,
+  window DC and memory-DC bitmap scale (§wxFont).
+
+**`Label::initSysFont()`** runs near the start of `GUI_App::on_init_inner()` (after the log
+target and the macOS deep-link handler), before any window or `wxGraphicsContext` exists, which
+satisfies the MSW `AddPrivateFont` rule. On MSW and Linux it registers
+`resources/fonts/HarmonyOS_Sans_SC_{Bold,Regular}.ttf` and `NanumGothic-{Regular,Bold}.ttf`
+with `wxFont::AddPrivateFont` (`wxUSE_PRIVATE_FONTS=ON` in `deps/wxWidgets/wxWidgets.cmake`). On
+Linux it skips all four calls when fontconfig already knows both families (e.g. installed
+system-wide in a Flatpak): Orca's comment records that `AddPrivateFont` triggers a Pango crash in
+`ensure_faces()` on Pango ≥ 1.48 because `FcConfigAppFontAddFile` invalidates Pango's cached font
+map. macOS never calls it: the bundle plist sets `ATSApplicationFontsPath = fonts/`, and wx's
+macOS `AddPrivateFont` would reject any path outside `Resources/Fonts`.
+
+**App fonts.** `GUI_App::init_fonts()`/`update_fonts()` derive `normal_font()`, `small_font()`,
+`bold_font()`, `link_font()` and `code_font()` from the `Label` statics (`update_fonts` uses
+`Body_14`; `init_fonts` overrides small/bold sizes on macOS; the code font is
+`wxFONTFAMILY_TELETYPE` at the small size). The splash screen's `scale_font` works around MSW
+`SetFractionalPointSize` using the primary PPI by computing `lfHeight` for the splash's own DPI.
+
+**macOS notes.** `DPIAware` and the main frame skip their default-font `SetFont` on macOS ("name
+cutting in ObjectList"); that is about the window default font, not a ban — dialogs set
+`Label::Body_14` normally. `OG_CustomCtrl` draws a focused URL label underlined but not bold on
+macOS (workaround for a Big Sur bold-font rendering issue).
+
+**Pitfalls**
+- **Rule:** Use the `Label` table, never hard-coded point sizes or ad-hoc faces.
+  ```cpp
+  title->SetFont(wxFont(12, wxFONTFAMILY_SWISS, wxFONTSTYLE_NORMAL, wxFONTWEIGHT_BOLD));  // Wrong
+  title->SetFont(Label::Head_12);                                                         // Right
+  ```
+  Cite: `src/slic3r/GUI/Widgets/Label.cpp` `Label::sysFont`.
+- **Rule:** Do not call `wxFont::AddPrivateFont` for Orca's fonts outside `Label::initSysFont`.
+  **Why:** macOS rejects paths outside `Resources/Fonts` (fonts load through the plist); MSW
+  requires the call before any graphics context, and [source] does not invalidate the
+  session-cached face list, so a `SetFaceName` check made before registration keeps rejecting the
+  private face; on Linux every call re-installs Pango's fontconfig map, which crashes Pango ≥ 1.48.
+  Cite: `interface/wx/font.h:719-751`; `Label::initSysFont`.

.claude/skills/orca-wxwidgets/references/events.md

@@ -0,0 +1,958 @@
+# Events: binding, dispatch, posting and deferred calls
+
+How wx 3.3.2 finds, runs, propagates, queues and drops event handlers, and how OrcaSlicer code
+binds, emits and defers. Read it before writing any `Bind`/`Unbind`, `Skip()`, `ProcessEvent`,
+`wxPostEvent`/`wxQueueEvent` or `CallAfter`, before defining a custom event, and when debugging a
+handler that never runs, runs twice, runs on a dead object, or swallows a widget's own behaviour.
+
+Contents: [Rules](#rules) · [1 Dispatch order](#1-dispatch-order) ·
+[2 Bind and Unbind](#2-bind-and-unbind) · [3 Static event tables](#3-static-event-tables) ·
+[4 Skip discipline](#4-skip-discipline) · [5 Propagation](#5-propagation) ·
+[6 Emitting events synchronously](#6-emitting-events-synchronously) ·
+[7 Posting and queueing](#7-posting-and-queueing) · [8 CallAfter](#8-callafter-and-the-liveness-rule) ·
+[9 Custom events and payloads](#9-custom-events-and-payload-ownership) · [10 Ids](#10-window-and-event-ids) ·
+[11 UPDATE_UI](#11-wxevt_update_ui) · [12 Idle events](#12-idle-events) ·
+[13 Event filters](#13-event-filters) · [14 Pushed handlers and blockers](#14-pushed-handlers-wxeventblocker-setevthandlerenabled) ·
+[15 Exceptions](#15-exceptions-in-handlers) · [16 How Orca widgets emit events](#16-how-orca-widgets-emit-events)
+
+Build fact that shapes every pitfall below: OrcaSlicer builds wx with `-DwxBUILD_DEBUG_LEVEL=0`
+(`deps/wxWidgets/wxWidgets.cmake`) and `libslic3r_gui` with `-DwxDEBUG_LEVEL=0`
+(`src/slic3r/CMakeLists.txt`). `wxASSERT`/`wxFAIL` compile to nothing and `wxCHECK_*` return silently
+(`include/wx/debug.h:314-324, 356-382`). Every event misuse wx would assert on in a debug build
+(pushed handler not popped, `Unbind` of an unknown entry, `RemoveFilter` of an unknown filter,
+out-of-range window id, bad `FilterEvent` return) is a silent no-op or a later crash in Orca.
+
+## Rules
+
+1. New code binds dynamically (`Bind` with a lambda or method + handler); never add a static event
+   table (existing widget-internal tables stay where they are). Take the event by reference (`auto&`,
+   `wxXxxEvent&`). → §2, §3, §4
+2. Later-bound handlers run first, and every dynamic handler runs before the static table. A handler
+   you bind on an Orca widget, a wx control or a window whose base class already bound the same
+   event must `Skip()` or the internal handler never runs. → §4, §16
+3. `Skip()` every non-command event you do not fully replace: focus, size, key-down, unhandled
+   `wxEVT_CHAR_HOOK` keys, DPI and system-colour changes, TLW activation, mouse events on custom
+   widgets. Command events are normally not skipped. → §4
+4. A binding on an object other than `this` (parent, TLW, canvas, app) must not outlive the handler:
+   method + `wxEvtHandler` sink is removed automatically but late; lambdas and non-`wxEvtHandler`
+   sinks are never removed. Unbind in the destructor, or use `EventGuard`. → §2
+5. `Unbind` with the same emitter, event type, id range and the same functor object (or the same
+   method + handler). A lambda literal never matches. → §2
+6. `Bind`/`Unbind` on the main thread only; binding twice registers twice. → §2
+7. Only command events, `wxEVT_CHAR_HOOK` and Orca's `SimpleEvent`/`Event<T>` family propagate; they
+   stop at dialogs, and at popups on MSW and macOS but not on wxGTK. Bind on the emitting control, or
+   on the dialog/popup itself. → §5
+8. `wxEVT_DESTROY` bubbles from children: compare `GetEventObject()` with the window. A TLW's destroy
+   event arrives after its derived members are destroyed. → §5
+9. Emit a window's event with `ProcessWindowEvent()` (or `HandleWindowEvent()` from native
+   callbacks), never `win->ProcessEvent()`; forward to another handler with `ProcessEventLocally()`. → §6
+10. Construct the event class declared for the type, and set the event object and id. → §6, §9
+11. A handler may destroy the emitter: never touch `this` after a synchronous emit that can lead to
+    destruction; defer destruction instead. → §6
+12. `AddPendingEvent`/`wxPostEvent` only on the main thread; `QueueEvent`/`wxQueueEvent` with a heap
+    event from any thread. A posted event is dispatched on the object you posted to, bypassing its
+    pushed handlers. → §7
+13. Events and `CallAfter`s queued on a handler are deleted with it. A worker must only post to a
+    target that outlives the worker (in Orca: `wxGetApp()`), or be stopped first. → §7
+14. Order is FIFO only per target; a `CallAfter` that re-queues itself starves the UI. Use `wxTimer`
+    for retries and polling. → §7
+15. Deferred work runs inside any nested loop (`ShowModal`, `wxYield`) and is held back by some
+    native modal loops; design for reentrancy. → §7
+16. Every deferred lambda re-checks the liveness of everything it touches, except the handler it was
+    queued on. Never capture a bare `this` or `wxDataViewItem` and trust it. → §8
+17. `CallAfter` captures are copied: capture by value, `shared_ptr` for move-only state; by-reference
+    captures only in a blocking marshal. → §8
+18. Window work requested from a mouse handler or a webview script-message callback goes through
+    `CallAfter`. → §8
+19. `wxDECLARE_EVENT` in the header, `wxDEFINE_EVENT` in exactly one `.cpp`. → §9
+20. A custom event class derived from a concrete wx event overrides `Clone()` and copies every
+    payload member. Client objects on a `wxCommandEvent` are not owned by the event. → §9
+21. Use `wxID_ANY` for controls and bind on the control; do not filter by id on an ancestor. → §10
+22. `wxEVT_UPDATE_UI` handlers run every idle pass for every window: keep them trivial. → §11
+23. Do not use idle events for periodic work; hidden panels still receive them. → §12
+24. `FilterEvent` runs for every event: return `Event_Skip` fast. → §13
+25. Pop or remove every pushed handler before its window dies; nest `wxEventBlocker` scopes and push
+    nothing else inside one. → §14
+26. Catch exceptions inside handlers; one that escapes ends the session. → §15
+
+---
+
+## 1. Dispatch order
+
+**Contract.** `wxEvtHandler::ProcessEvent()` searches in this order (`interface/wx/event.h:567-625`,
+`docs/doxygen/overviews/eventhandling.h:451-515`):
+
+| Step | What runs | Notes |
+|---|---|---|
+| 0 | `wxApp::FilterEvent()` and other `wxEventFilter`s (LIFO) | Anything but `Event_Skip` (-1) stops here. Called once per event, not again as it propagates ([source] `src/common/event.cpp:1537-1552`) |
+| 1 | `TryBefore()` | Validators on windows |
+| 2 | — | If `SetEvtHandlerEnabled(false)`, skip to step 5 (the overview's wording; the interface doc's "skips to step (7)" is inaccurate — [source] `TryHereOnly` returns `false` and `DoTryChain` still runs, `src/common/event.cpp:1582-1591, 1644-1648`) |
+| 3 | Dynamic table (`Bind`) | **Most recently bound first**, before the static table (`docs/doxygen/overviews/eventhandling.h:474-483`) |
+| 4 | Static event table | Macro order, derived class before base class |
+| 4a | Implicit `CallAfter` entry | Runs a queued `wxAsyncMethodCallEvent` only when its event object is this handler ([source] `src/common/event.cpp:1644-1667` `TryHereOnly`) |
+| 5 | Next handlers in the chain | For windows: the pushed-handler stack (§14) |
+| 6 | `TryAfter()` | Windows propagate to the parent (§5); finally `wxTheApp->ProcessEvent()` |
+
+`ProcessEvent` returns `true` iff some handler ran and did not call `Skip()` (`interface/wx/event.h:619-622`).
+Before each handler call wx resets the flag with `event.Skip(false)` ([source]
+`src/common/event.cpp:1443-1475` `ProcessEventIfMatchesId`), so a skip in one handler does not carry over to the
+next: every handler that wants processing to continue must call `Skip()` itself.
+
+A handler entry matches when the event type matches and the bound id is `wxID_ANY`, or equals the
+event id, or the event id falls in `[id, lastId]` (`src/common/event.cpp:1443-1475`).
+
+---
+
+## 2. Bind and Unbind
+
+**Contract.**
+- Forms: `Bind(tag, functor, id = wxID_ANY, lastId = wxID_ANY, userData = nullptr)` and
+  `Bind(tag, &Class::method, handlerPtr, id, lastId, userData)` (`interface/wx/event.h:876-957`). The
+  method form accepts "an arbitrary method (doesn't need to be from a wxEvtHandler derived class)";
+  the handler pointer "must always be specified". `userData`: "wxWidgets will take ownership of
+  this pointer" — deleted when the handler is unbound or at program termination.
+- Handlers can be bound at any time and removed with `Unbind`
+  (`docs/doxygen/overviews/eventhandling.h:237-252`). `Connect()` is the legacy form: "please use
+  [Bind] in any new code" (`interface/wx/event.h:705-706`).
+- Lifetime (`docs/doxygen/overviews/eventhandling.h:332-335`), for a handler object not derived from `wxEvtHandler`: "the
+  lifetime of `myFrameHandler` must be greater than that of `MyFrame` object -- or at least it needs
+  to be unbound before being destroyed".
+- `Unbind` "can only unbind functions, functors or methods which have been added using the Bind<>()
+  method. There is no way to unbind functions bound using the (static) event tables." Its note:
+  "functors are compared by their address which, unfortunately, doesn't work correctly if the same
+  address is reused for two different functor objects. Because of this, using Unbind() is not
+  recommended if there are multiple functors using the same eventType and id and lastId as a wrong
+  one could be unbound" (`interface/wx/event.h:958-997`).
+
+**Mechanics** [source]:
+- `Bind` takes `const Functor&`, stores a **copy** of the functor and records the **address of the
+  object you passed** (`include/wx/event.h:524-570` `wxEventFunctorFunctor`, `:3951-3961`). `Unbind`
+  matches on that address plus the functor type. So a lambda is unbindable when the same lvalue
+  (a member `std::function`, a named lambda that stays at one address, heap storage) is passed to
+  both calls; an inline lambda literal never matches. Method + handler pairs match by value and
+  always work. Captures must be copyable.
+- `DoUnbind` requires `entry->m_id == id`; only `lastId == wxID_ANY` and `eventType == wxEVT_NULL`
+  act as wildcards (`src/common/event.cpp:1806-1824`). A handler bound with `ctrl->GetId()` is not
+  removed by `Unbind(evt, fn)` (id defaults to `wxID_ANY`), and vice versa. `Unbind` on a different
+  emitter than the one you bound on returns `false` silently.
+- `DoBind` always appends (`src/common/event.cpp:1769-1803`): binding the same handler twice runs it twice.
+- No locking in `DoBind`/`DoUnbind`: main thread only.
+
+**Lifetime by handler kind** [source]:
+
+| Handler | Removed automatically when the handler object dies? |
+|---|---|
+| `src->Bind(evt, &C::m, sink)` where `sink` is a `wxEvtHandler` (any window) other than `src` | Yes. `DoBind` registers a `wxEventConnectionRef` on the sink (`src/common/event.cpp:1793-1802`); the sink's `~wxTrackable` calls `OnSinkDestroyed`, which deletes the entries (`include/wx/event.h:4184-4200`, `src/common/event.cpp:2022-2042`) |
+| Lambda or functor (`[this]{…}`), free function | No. `GetEvtHandler()` is null for functors |
+| Method of a class not derived from `wxEvtHandler` (`GLCanvas3D`, `Plater::priv`) | No |
+| Handlers bound on `this` itself | Deleted with `this` (`~wxEvtHandler`, `src/common/event.cpp:1204-1245`) |
+
+The automatic removal runs **late**: `wxEvtHandler` derives from `wxObject, wxTrackable`
+(`include/wx/event.h:3705-3706`), so `~wxTrackable` runs after the derived destructor, after member
+destruction, and after the port destructor has destroyed the native window and the children
+(`src/osx/window_osx.cpp` `~wxWindowMac`, `src/msw/window.cpp` `~wxWindowMSW`). Events the source
+emits during that teardown (activation, focus, size, show) still reach the half-destroyed sink.
+Unbind explicitly in the sink's destructor whenever the source can fire while the sink dies.
+
+**Usage.**
+```cpp
+// Method + wxEvtHandler sink on another window: removed on sink death (late) — unbind early anyway
+m_parent->Bind(wxEVT_DPI_CHANGED, &DialogButtons::on_dpi_changed, this);
+DialogButtons::~DialogButtons() { m_parent->Unbind(wxEVT_DPI_CHANGED, &DialogButtons::on_dpi_changed, this); }
+
+// Lambda on another object: unbindable only through the same stored object
+std::function<void(wxShowEvent&)> m_on_show = [this](wxShowEvent& e) { e.Skip(); /* ... */ };
+top->Bind(wxEVT_SHOW, m_on_show);
+top->Unbind(wxEVT_SHOW, m_on_show);   // same object → matches
+```
+
+**OrcaSlicer.**
+- `EventGuard` (`src/slic3r/GUI/GUI_Utils.hpp`) is the RAII form: it stores the functor (or method +
+  handler) on the heap, so its address is stable and the destructor's `Unbind` matches. Use it when
+  the emitter outlives the handler object, or to drop a binding before the owner's base destructor
+  runs. The emitter must still be alive when the guard dies.
+  ```cpp
+  EventGuard on_idle_evt;   // member of PlaterWorker (src/slic3r/GUI/Jobs/PlaterWorker.hpp)
+  , on_idle_evt(plater, wxEVT_IDLE, [this](wxIdleEvent&) { process_events(); })
+  EventGuard on_progress_evt;   // PrintHostQueueDialog binds on itself, unbinds during member destruction
+  , on_progress_evt(this, EVT_PRINTHOST_PROGRESS, &PrintHostQueueDialog::on_progress, this)
+  ```
+- `GLCanvas3D` is not a `wxEvtHandler`: its method bindings on its `wxGLCanvas` are never removed
+  automatically, so `GLCanvas3D::bind_event_handlers`/`unbind_event_handlers` are a mandatory pair,
+  and `Plater::priv::set_current_panel` unbinds the canvas of the panel being left before binding
+  the active one.
+- **Binding on another window (popups and child widgets).** When an object binds on a window other
+  than itself — typically the top-level parent — unbind in its destructor.
+  `PopupWindow::Create` binds `wxEVT_ACTIVATE` on its top parent (wxGTK), `BindUnfocusEvent()` binds
+  `wxEVT_ACTIVATE`/`wxEVT_ICONIZE`/`wxEVT_SHOW` (wxMSW), and `PopupWindow::~PopupWindow` unbinds them
+  (`src/slic3r/GUI/Widgets/PopupWindow.cpp`). The static `GetTopParent` there returns the first
+  `wxNonOwnedWindow` strictly above its argument (or the root), so for a popup inside another popup
+  the handlers sit on the outer popup. Because `Create` passes `parent` and the destructor passes
+  `this`, the two calls resolve to different windows when `parent` is itself a TLW or popup that has a
+  parent: the wxGTK `Unbind` then misses silently (§2 Mechanics). These method + `this` bindings
+  would be removed by wx when the popup dies, but only after the teardown window described above; a
+  lambda binding would never be removed. Popup dismissal itself: see `references/popups-menus.md`.
+
+**Pitfalls.**
+- **Rule:** A lambda that captures `this` and is bound on a longer-lived object must be unbound
+  before `this` dies.
+  **Why:** functor bindings are not tracked; the emitter later calls into freed memory.
+  ```cpp
+  // Wrong: dangles after this panel is destroyed
+  GetParent()->Bind(wxEVT_SHOW, [this](wxShowEvent& e) { e.Skip(); refresh(); });
+  // Right: method + wxEvtHandler sink, and unbind in the destructor
+  GetParent()->Bind(wxEVT_SHOW, &MyPanel::on_parent_show, this);
+  MyPanel::~MyPanel() { GetParent()->Unbind(wxEVT_SHOW, &MyPanel::on_parent_show, this); }
+  ```
+  Cite: `src/common/event.cpp:1793-1802, 2022-2042`; `docs/doxygen/overviews/eventhandling.h:332-335`.
+- **Rule:** Unbind with the same object, id and emitter you bound with.
+  **Why:** a temporary lambda has a new address; a missing id does not match an id-bound entry. Both
+  return `false` and leave the handler bound — silently.
+  ```cpp
+  // Wrong
+  btn->Bind(wxEVT_BUTTON, fn, btn->GetId());   btn->Unbind(wxEVT_BUTTON, fn);
+  win->Unbind(wxEVT_SIZE, [this](wxSizeEvent& e) { e.Skip(); });
+  // Right
+  btn->Unbind(wxEVT_BUTTON, fn, btn->GetId());
+  ```
+  Cite: `include/wx/event.h:524-570`; `src/common/event.cpp:1806-1824`.
+- **Rule:** Move-only captures do not compile in `Bind` or `CallAfter`; use `std::shared_ptr`.
+  Cite: `include/wx/event.h:524-570` (functor stored by copy).
+
+---
+
+## 3. Static event tables
+
+**Contract.** `wxDECLARE_EVENT_TABLE()` in the class, `wxBEGIN_EVENT_TABLE(Class, Base)` …
+`wxEND_EVENT_TABLE()` in the `.cpp`; entries are searched in macro order, then the base class table
+(`interface/wx/event.h:567-625` step 5). They run **after** every dynamic handler for the same event.
+
+**Multiple inheritance.** "it is imperative that the wxEvtHandler(-derived) class is the first class
+inherited such that the `this` pointer for the overall object will be identical to the `this`
+pointer of the wxEvtHandler portion" (`interface/wx/event.h:376-380`). Put the wx base first in
+`class X : public wxPanel, public Other`.
+
+**OrcaSlicer.** New code binds with lambdas (`[this](auto& e)`) or method + `this`. The core widgets
+keep their internal handlers in static tables (`DECLARE_EVENT_TABLE()` in `Widgets/StaticBox.hpp`,
+`Widgets/Button.hpp`; tables in `Button.cpp`, `TextInput.cpp`, `SpinInput.cpp`, `ComboBox.cpp`,
+`DropDown.cpp`, `TabCtrl.cpp`). That is why `Skip()` in user handlers matters (§4): a user `Bind` on
+`Button` for `wxEVT_LEFT_DOWN` runs before `Button::mouseDown`. Do not add new static tables; when
+changing such a widget, keep its internal handlers where they are.
+
+---
+
+## 4. Skip discipline
+
+**Contract.** `wxEvent::Skip` (`interface/wx/event.h:238-252`): "Without Skip() (or equivalently if
+Skip(false) is used), the event will not be processed any more. If Skip(true) is called, the event
+processing system continues searching for a further handler function for this event, even though it
+has been processed already in the current handler. In general, it is recommended to skip all
+non-command events to allow the default handling to take place. The command events are, however,
+normally not skipped as usually a single command such as a button click or menu item selection must
+only be processed by one handler."
+
+| Event | Rule | Cite |
+|---|---|---|
+| `wxEVT_SET_FOCUS` / `wxEVT_KILL_FOCUS` | "should almost invariably call wxEvent::Skip()"; a KILL_FOCUS handler "must not call wxWindow::SetFocus()" — defer it (`CallAfter`) | `interface/wx/event.h:3410-3416` |
+| `wxEVT_SIZE` | "Sizers … rely on size events to function correctly … call Skip on all size events you catch" | `interface/wx/event.h:5058-5060` |
+| `wxEVT_KEY_DOWN` | Not skipping suppresses `wxEVT_CHAR` for that key and "may also prevent accelerators … from working" | `interface/wx/event.h:1454-1461` |
+| `wxEVT_CHAR_HOOK` | Propagates upward; handled (not skipped) → no `KEY_DOWN`/`CHAR`. Skip every key you do not handle | `interface/wx/event.h:1485-1508`; keyboard order: `references/mouse-keyboard-focus.md` |
+| `wxEVT_PAINT` | The handler "must create a wxPaintDC"; skip only if default painting must also run | `interface/wx/event.h:2274-2285`; `references/painting-custom-widgets.md` |
+| `wxEVT_DPI_CHANGED` | "should almost always call event.Skip() … as many controls rely on processing this event"; a TLW handler may deliberately not skip to suppress the default resize | `interface/wx/event.h:3571-3583` |
+| `wxEVT_SYS_COLOUR_CHANGED` | The default handler propagates it to children; a TLW handler must Skip, call the base, or forward | `interface/wx/event.h:1950-1955` |
+| `wxEVT_ACTIVATE` on a TLW | MSW: `wxTopLevelWindowMSW::OnActivate` (static table) saves and restores the last focused child; macOS: `wxFrame::OnActivate` (static table) installs the frame's menubar. A non-skipping dynamic handler disables both | [source] `src/msw/toplevel.cpp` `wxTopLevelWindowMSW::OnActivate`, `src/osx/carbon/frame.cpp` `wxFrame::OnActivate`; `references/popups-menus.md` §15 |
+| Mouse/key events on custom widgets | Dynamic handlers run before the widget's static table: not skipping disables the widget's own press/release/capture logic | [source] `src/common/event.cpp:1644-1667` |
+| Command events | Normally not skipped; `Skip()` lets the event continue to the static table, the next handler, then the parent | `interface/wx/event.h:247-251` |
+
+wx's own controls bind some internals dynamically in their constructors — e.g.
+`wxBookCtrlBase`, `wxComboCtrlBase` and `wxTreeCtrlBase` bind `wxEVT_DPI_CHANGED`
+(`src/common/bookctrl.cpp:60`, `src/common/combocmn.cpp:839`, `src/common/treebase.cpp:172`) — so a
+non-skipping handler you bind on
+such a control later starves its rescale. DPI propagation order: `references/dpi-bitmaps-fonts.md`.
+
+**OrcaSlicer — deliberate deviations.**
+- `DPIAware<P>` (`src/slic3r/GUI/GUI_Utils.hpp`) binds `wxEVT_DPI_CHANGED` on the TLW (not on macOS)
+  **without** Skip: Orca rescales itself in `rescale()` and suppresses wx's default TLW resize, which
+  the doc allows. Its `wxEVT_SYS_COLOUR_CHANGED` handler Skips on macOS and Linux but not on Windows,
+  where the theme is app-forced.
+- Because `DPIAware` binds in its own constructor, everything a derived dialog binds on itself later
+  runs first. `DialogButtons` binds the parent's `wxEVT_DPI_CHANGED` and calls `Skip()`, so it runs
+  before `DPIAware`'s handler and lets it run. Likewise `DPIAware` maps Esc to `Close()` in a
+  `wxEVT_CHAR_HOOK` handler on every `DPIDialog`: a derived dialog's own `wxEVT_CHAR_HOOK` handler must
+  `Skip()` every key it does not consume, or Esc stops closing the dialog (`CloneDialog`'s Enter→OK
+  hook is the model).
+
+**Pitfalls.**
+- **Rule:** Take the event parameter by reference.
+  **Why:** the functor form compiles with a by-value parameter; the lambda then receives a copy
+  (`include/wx/event.h:534-545` calls `m_handler(static_cast<EventArg&>(event))`), and `Skip()` on the
+  copy does nothing — the original counts as handled.
+  ```cpp
+  // Wrong
+  ctrl->Bind(wxEVT_KILL_FOCUS, [](wxFocusEvent e) { e.Skip(); commit(); });
+  // Right
+  ctrl->Bind(wxEVT_KILL_FOCUS, [](wxFocusEvent& e) { e.Skip(); commit(); });
+  ```
+- **Rule:** A handler you add to an Orca widget, for any event the widget handles internally, calls
+  `Skip()`.
+  **Why:** your later `Bind` runs first (LIFO, dynamic before static); without Skip the widget's own
+  handler never runs.
+  ```cpp
+  // Wrong: CheckBox's internal toggle handler never runs, the bitmap and half-state go stale
+  cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent&) { save(); });
+  // Right
+  cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { e.Skip(); save(); });
+  ```
+  The same applies to `GetTextCtrl()->Bind(wxEVT_TEXT_ENTER / wxEVT_KILL_FOCUS / wxEVT_TEXT, …)` on
+  `TextInput`/`SpinInput`/`ComboBox`, and to raw mouse/key binds on `Button` and other `StaticBox`
+  widgets. Cite: `src/slic3r/GUI/Widgets/CheckBox.cpp` `CheckBox::CheckBox`;
+  `src/slic3r/GUI/Preferences.cpp` ("let CheckBox::update() refresh the bitmap").
+- **Rule:** Never call `Skip()` (or touch members) after the handler deleted `this` (§6).
+
+---
+
+## 5. Propagation
+
+**Contract** (`docs/doxygen/overviews/eventhandling.h:536-568`):
+- "the events of the classes deriving from wxCommandEvent are propagated by default to the parent
+  window if they are not processed in this window itself … all event classes not deriving from
+  wxCommandEvent … do not propagate upward." Mouse, motion, enter/leave, size, paint and key events
+  stay at the window — except `wxEVT_CHAR_HOOK`, which propagates (`interface/wx/event.h:1485-1494`).
+- "the event propagation stops when it reaches the parent dialog, if any … The events do propagate
+  beyond the frames, however." `SetExtraStyle(wxWS_EX_BLOCK_EVENTS)` blocks at any window, or clears
+  the default on a dialog (`interface/wx/window.h:264-270`).
+- The mechanism is `m_propagationLevel` (`interface/wx/event.h:263-279`): `wxEVENT_PROPAGATE_NONE` by default,
+  `wxEVENT_PROPAGATE_MAX` for command events; any event class may set it in its constructor.
+  `StopPropagation()` returns the old level for `ResumePropagation()` (`interface/wx/event.h:255-260`);
+  `wxPropagationDisabler` and `wxPropagateOnce` are RAII helpers (`interface/wx/event.h:346-367`).
+
+**Source facts** [source]:
+- **Popups block propagation on MSW and macOS, not on wxGTK.** `wxPopupWindowBase::Create` sets
+  `wxWS_EX_BLOCK_EVENTS` (`src/common/popupcmn.cpp:129-138`; not in the overview). The MSW and macOS
+  `wxPopupWindow::Create` call it (`src/msw/popupwin.cpp`, `src/osx/carbon/popupwin.cpp`, which the
+  Cocoa build uses); the wxGTK one never does (`src/gtk/popupwin.cpp` `wxPopupWindow::Create`). So a
+  `wxEVT_BUTTON` from a control inside a popup (`wxPopupTransientWindow`, Orca `PopupWindow`,
+  `DropDown`) that no handler inside consumes stops at the popup on MSW/macOS but bubbles on to the
+  popup's parent and its ancestors on GTK.
+- `wxWindowBase::TryAfter` does not propagate to a parent that `IsBeingDeleted()`
+  (`src/common/wincmn.cpp:3499-3522`). After a block or the top of the chain, the event still goes
+  to `wxTheApp` — except `wxEVT_IDLE` (`src/common/event.cpp:1483-1498` `DoTryApp`).
+- `wxWindowDestroyEvent` and `wxWindowCreateEvent` derive from `wxCommandEvent`
+  (`interface/wx/event.h:4554, 2255`): a `wxEVT_DESTROY` handler on a dialog also receives every
+  child's destroy event (unless the dialog itself is being deleted).
+- `wxUpdateUIEvent` is a command event: every unhandled update-UI event walks the parent chain up to
+  the first blocking window (a dialog; a popup on MSW/macOS) or the root, and then `wxApp` (§11).
+
+**Destroy-event timing** [source]. `wxWindowBase::Destroy()` of a child sends `wxEVT_DESTROY` before
+`delete this` (`src/common/wincmn.cpp:559-573`). For a TLW, and for any `delete`, the event is sent
+from a base destructor (`src/common/framecmn.cpp` `~wxFrameBase`, `src/msw/toplevel.cpp`
+`~wxTopLevelWindowMSW`, `src/gtk/toplevel.cpp` `~wxTopLevelWindowGTK`, `src/osx/dialog_osx.cpp`
+`~wxDialog`, `src/osx/nonownedwnd_osx.cpp` `~wxNonOwnedWindow`, `src/osx/window_osx.cpp` `~wxWindowMac`)
+— after the derived class destructor and its members are gone. A `wxEVT_DESTROY` handler may clear
+an outside pointer to the window, but must not call into the derived object. Cleanup that needs the derived members belongs in the
+derived destructor (`WebDialog::~WebDialog` in `src/slic3r/GUI/WebDialog.cpp` documents this choice).
+
+**OrcaSlicer.** The payload events in `src/slic3r/GUI/Event.hpp` — `SimpleEvent`, `IntEvent`,
+`Event<T>`, `ArrayEvent<T, N>` — derive from `wxEvent` but set
+`m_propagationLevel = wxEVENT_PROPAGATE_MAX`, so they bubble like command events and, like them,
+stop at dialogs and (on MSW/macOS) popups.
+
+**Pitfalls.**
+- **Rule:** In a `wxEVT_DESTROY` handler bound on a window with children, check the event object.
+  ```cpp
+  // Wrong: the first child destroyed clears the pointer
+  m_plugins_dlg->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent&) { m_plugins_dlg = nullptr; });
+  // Right (GUI_App::open_plugins_dialog)
+  m_plugins_dlg->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent& e) {
+      if (e.GetEventObject() == m_plugins_dlg) m_plugins_dlg = nullptr;
+      e.Skip();
+  });
+  ```
+- **Rule:** Do not expect events from inside a dialog or popup at its opener — and do not rely on
+  popup events *not* arriving there either.
+  **Why:** `wxWS_EX_BLOCK_EVENTS` (`src/common/dlgcmn.cpp` `wxDialogBase::wxDialogBase`,
+  `src/common/popupcmn.cpp`) blocks at every dialog, but at popups only on MSW/macOS; on wxGTK an
+  unconsumed command event from inside a popup reaches the opener's ancestors and any unfiltered
+  handler there. Bind on the dialog/popup or on the control, consume the event there, or re-emit
+  explicitly.
+- **Rule:** An ancestor that binds a command event without an id filter receives that event from
+  every descendant control of that type.
+
+---
+
+## 6. Emitting events synchronously
+
+| Call | Use for | Note |
+|---|---|---|
+| `win->ProcessWindowEvent(e)` = `win->GetEventHandler()->ProcessEvent(e)` | Emitting a window's own event | "ProcessEvent() itself can't be called for wxWindow objects as it ignores the event handlers associated with the window; use this function instead" (`interface/wx/window.h:2736-2744`) |
+| `win->HandleWindowEvent(e)` = `GetEventHandler()->SafelyProcessEvent(e)` | Same, from code that must not leak exceptions (native callbacks) | `interface/wx/window.h:2726-2734` |
+| `win->ProcessWindowEventLocally(e)` | This window and its pushed handlers only, no propagation | `interface/wx/window.h:2746-2757` |
+| `handler->ProcessEventLocally(e)` | Forwarding an event to another handler | "should, be called to forward an event to another handler instead of ProcessEvent() which would result in a duplicate call to TryAfter()" (`interface/wx/event.h:627-651`) |
+| `handler->SafelyProcessEvent(e)` | Catches exceptions → `wxApp::OnExceptionInMainLoop` | `interface/wx/event.h:653-666` |
+| `handler->ProcessEvent(e)` | Non-window handlers | On a window object it bypasses pushed handlers (Orca `StateHandler`) |
+
+**Emitting shape** (`docs/doxygen/overviews/eventhandling.h:660-671`): construct the event with the
+type and `GetId()`, `SetEventObject(this)`, fill the payload, `ProcessWindowEvent(event)`.
+
+**Programmatic changes.** wx controls normally send command events only for user actions. The
+documented exceptions include `wxNotebook::AddPage/AdvanceSelection/DeletePage/SetSelection`,
+`wxTreeCtrl::Delete/DeleteAllItems/EditLabel` and "All wxTextCtrl methods" — use
+`wxTextCtrl::ChangeValue` instead of `SetValue`; `Replace`/`WriteText` have no event-free form
+(`docs/doxygen/overviews/eventhandling.h:796-815`). `wxBitmapToggleButton::SetValue` "does not cause a EVT_TOGGLEBUTTON event
+to be emitted" (`interface/wx/tglbtn.h:169`). Orca widget setters: §16.
+
+**Reentrancy.** A synchronous emit runs every handler before it returns. If a handler destroys the
+emitter, the emitter's code after `ProcessEvent` runs on freed memory. Non-TLW `Destroy()` deletes
+immediately (`src/common/wincmn.cpp:559-573`).
+
+**OrcaSlicer models.** `Button::sendButtonEvent` (`Widgets/Button.cpp`): `wxCommandEvent` of
+`wxEVT_BUTTON` with `GetId()`, `SetEventObject(this)`, `GetEventHandler()->ProcessEvent`.
+`MsgDialog::show_dsa_button` (`MsgDialog.cpp`) makes a label click behave like a checkbox click:
+`SetValue(!GetValue())`, then emits `wxEVT_TOGGLEBUTTON` with the checkbox's id and object through its
+`GetEventHandler()`. `CloneDialog` (`CloneDialog.cpp`) turns Enter in its spin box into an OK click
+from its `wxEVT_CHAR_HOOK` handler by emitting `wxEVT_BUTTON` with `ok_btn->GetId()` through
+`ok_btn->GetEventHandler()`, and Skips other keys.
+
+**Pitfalls.**
+- **Rule:** Never emit a window's event with `win->ProcessEvent()`.
+  ```cpp
+  // Wrong: skips handlers pushed on the window (StateHandler, wxEventBlocker)
+  wxCommandEvent e(wxEVT_BUTTON, GetId()); e.SetEventObject(this); this->ProcessEvent(e);
+  // Right
+  wxCommandEvent e(wxEVT_BUTTON, GetId()); e.SetEventObject(this); ProcessWindowEvent(e);
+  ```
+  Cite: `interface/wx/window.h:2736-2744`.
+- **Rule:** Construct the event class the type was declared with.
+  **Why:** the `Bind` tag ties type and class at compile time, but nothing checks the object you
+  construct. `wxCommandEvent e(wxEVT_LEFT_DOWN, id)` compiles; handlers then `static_cast` it to
+  `wxMouseEvent&` (undefined behaviour), and it propagates to parents like a command event. To make
+  a whole card clickable, call the action directly or emit a semantic event.
+  ```cpp
+  // Wrong: a "mouse" event that is a wxCommandEvent, emitted past the handler stack
+  auto forward = [this](wxMouseEvent&) {
+      wxCommandEvent click(wxEVT_LEFT_DOWN, GetId()); click.SetEventObject(this); this->ProcessEvent(click);
+  };
+  // Right: a semantic command event through the handler stack (or call select() directly)
+  auto forward = [this](wxMouseEvent&) {
+      wxCommandEvent click(wxEVT_BUTTON, GetId()); click.SetEventObject(this); ProcessWindowEvent(click);
+  };
+  child->Bind(wxEVT_LEFT_DOWN, forward);
+  ```
+  Cite: `src/slic3r/GUI/PurgeModeDialog.cpp` `PurgeModeBtnPanel` (re-dispatches child clicks; not a
+  model to copy).
+- **Rule:** Defer destroying the emitter out of its own handler.
+  **Why:** `Button::mouseReleased` is still on the stack when your `wxEVT_BUTTON` handler runs.
+  ```cpp
+  // Wrong
+  btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { m_panel->Destroy(); });   // m_panel contains btn
+  // Right
+  btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) {
+      CallAfter([w = wxWeakRef<wxWindow>(m_panel)] { if (w) w->Destroy(); });
+  });
+  ```
+  Alternative: `wxTheApp->ScheduleForDestruction(win)` (`interface/wx/app.h:191-212`). Deletion
+  rules: `references/windows-dialogs.md`.
+
+---
+
+## 7. Posting and queueing
+
+**Contract.**
+- `QueueEvent(wxEvent*)` is asynchronous and "takes ownership of the event parameter, i.e. it will
+  delete it itself … the pointer can't be used any more after the function returns". It "can be used
+  for inter-thread communication from the worker threads to the main thread. It is safe in the sense
+  that it uses locking internally", and wakes the idle loop via `wxWakeUpIdle()`
+  (`interface/wx/event.h:409-466`). `wxQueueEvent(dest, evt)` wraps it (`interface/wx/event.h:5368-5382`).
+- `AddPendingEvent(const wxEvent&)` copies the event via `Clone()`, so the original may be on the
+  stack, but it "can't be used to post events from worker threads for the event objects with
+  wxString fields (i.e. in practice most of them)"; "Use QueueEvent() to avoid this"
+  (`interface/wx/event.h:468-488`). The overview adds that you "will need to use the latter [QueueEvent] when
+  doing inter-thread communication; when you use only the main thread you can also safely use the
+  former" (`docs/doxygen/overviews/eventhandling.h:618-620`). `wxPostEvent(dest, evt)` = `dest->AddPendingEvent(evt)`, "not
+  thread-safe for event objects having wxString fields, use wxQueueEvent() instead"
+  (`interface/wx/event.h:5355-5366`).
+- Every posted event class "must implement" `Clone()` (`interface/wx/event.h:125-146`).
+- `wxThreadEvent`: `Clone()` unshares the string; its category is `wxEVT_CATEGORY_THREAD`, which
+  keeps it out of `YieldFor()` calls that do not ask for that category; `SetPayload<T>` needs a
+  copy constructor that is thread-safe, "i.e. create a copy that doesn't share anything with the
+  original" (`interface/wx/event.h:3733-3790`). [source] Plain `wxYield()` is `YieldFor(wxEVT_CATEGORY_ALL)`, which
+  includes `THREAD`; the protection applies to masked yields such as the generic `wxProgressDialog`'s
+  `YieldFor(wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT)` (`src/generic/progdlgg.cpp`).
+
+**Source facts** [source]:
+- `AddPendingEvent` is literally `QueueEvent(event.Clone())` (`include/wx/event.h:3780-3789`). wxString
+  is always a deep-copy `std::wstring` in 3.3 (`include/wx/string.h:121-132`), so the copy-on-write
+  rationale is historical; follow the documented rule anyway.
+- **Where** a posted event is dispatched: the queue belongs to the handler you posted to, and
+  `ProcessPendingEvents` calls `SafelyProcessEvent` on that object (`src/common/event.cpp:1368-1440`).
+  Posting to a `wxWindow*` processes it on the window object itself, **bypassing pushed handlers**
+  (`StateHandler`, `wxEventBlocker`). Post to `win->GetEventHandler()` if they must see it.
+- **When**: pending events run before idle (`src/common/evtloopcmn.cpp:258-330`
+  `wxEventLoopManual::DoRunLoop`, the MSW loop; per-port table below); a nested loop (`ShowModal()`,
+  `wxYield()`) processes them too (`src/common/evtloopcmn.cpp:172-192` `DoYieldFor`). An exiting loop
+  drains them before it returns on MSW (`DoRunLoop` tail) and in macOS modal loops
+  (`src/osx/core/evtloop_cf.cpp` `wxCFEventLoop::OSXDoRun`, run by `wxModalEventLoop::OSXDoRun` in
+  `src/osx/cocoa/evtloop.mm`), but not on wxGTK (`src/gtk/evtloop.cpp` `wxGUIEventLoop::DoRun` just
+  leaves `gtk_main()`), where they run in the enclosing loop's next idle pass. A callback can run inside any
+  `ShowModal()` or `wxYield()` reached from your code. Nested loops: `references/threads-timers-app.md`.
+- **Order**: FIFO only per target handler. The app keeps a list of handlers with pending events and
+  drains `handler[0]` completely — including events added to it meanwhile — before the next
+  (`src/common/appbase.cpp:561-603`, `src/common/event.cpp:1368-1440`). `A->CallAfter(f1); B->CallAfter(f2);
+  A->CallAfter(f3);` runs f1, f3, f2. A callback that keeps queueing new work on any handler keeps
+  `ProcessPendingEvents` looping and native input and paint starve.
+- **Destruction**: `~wxEvtHandler` removes itself from the app's list and deletes its queued events
+  (`src/common/event.cpp:1234-1238`) — events posted to a destroyed handler are dropped, not delivered.
+  `DeletePendingEvents` does not take `m_pendingEventsLock` (`src/common/event.cpp:1361-1366`): a worker
+  posting to an object being destroyed races its destructor, and a worker holding a raw pointer to a
+  dead target is undefined behaviour.
+
+**Platforms** [source]:
+
+| Port | Pending events (`CallAfter`, posted) | Idle events (`wxEVT_IDLE`, update-UI, deferred TLW deletes) |
+|---|---|---|
+| MSW | Keep running inside native modal loops (menu tracking, window move/size, `MessageBox`, common dialogs) through a `WH_GETMESSAGE` hook (`src/msw/window.cpp` `wxIdleWakeUpModule::MsgHookProc` → `wxApp::MSWProcessPendingEventsIfNeeded`, `src/msw/app.cpp:717-730`) | Not processed inside those native loops — do not defer repaint/layout to idle if it must happen during a live resize |
+| macOS | Processed by a run-loop observer at `kCFRunLoopBeforeTimers` in common modes (`src/osx/core/evtloop_cf.cpp:86-112`) | At `kCFRunLoopBeforeWaiting`. While a native `wxMessageDialog`, `wxFileDialog` or `wxDirDialog` is modal, `wxCFEventLoopPauseIdleEvents` stops **both** (`src/osx/cocoa/msgdlg.mm:62`, `src/osx/cocoa/filedlg.mm:601`, `src/osx/cocoa/dirdlg.mm:123`, `src/osx/core/evtloop_cf.cpp:362-379`): a `CallAfter` queued before or during such a dialog runs only after it closes |
+| GTK3 (default build, X11 and Wayland) / opt-out GTK2 | Pending events and idle run from one GLib idle source at `G_PRIORITY_LOW` (`src/gtk/app.cpp:102-153, 631`, `wxApp::DoIdle`): they starve while higher-priority sources (timers, redraw, input floods) are busy; a masked `YieldFor` removes that source before each iteration, so nothing queued runs inside it (`references/threads-timers-app.md` §Event categories and yields) | same source; `RequestMore()` or remaining pending events keep it installed — a busy loop |
+
+**OrcaSlicer.** `GLCanvas3D::post_event` sets the event object and `wxPostEvent(m_canvas, …)` —
+asynchronous, dispatched on the `wxGLCanvas`, where `Plater::priv` binds the canvas events.
+`BackgroundSlicingProcess` posts with `wxQueueEvent(wxGetApp().mainframe->m_plater, evt.Clone())` and
+`new wxCommandEvent(...)`; `SlicingProcessCompletedEvent` carries the worker's exception as a
+`std::exception_ptr`. Worker → GUI patterns, `set_queue_on_main_fn`, Jobs:
+`references/threads-timers-app.md`.
+
+**Pitfalls.**
+- **Rule:** From a worker, post only to an object that outlives the worker.
+  ```cpp
+  // Wrong: races ~wxEvtHandler, or uses a dangling pointer
+  std::thread([panel] { wxQueueEvent(panel, new wxThreadEvent(EVT_DONE)); }).detach();
+  // Right: post to the app and re-validate on the main thread
+  std::thread([this, alive = m_alive] {
+      wxGetApp().CallAfter([this, alive] { if (alive->load()) on_done(); });
+  }).detach();
+  ```
+  Cite: `src/common/event.cpp:1234-1238, 1361-1366`.
+- **Rule:** Use one target for steps that must run in order.
+  **Why:** `this->CallAfter(a); wxGetApp().CallAfter(b);` gives no order between `a`'s handler queue
+  and the app's.
+- **Rule:** Retry and polling go through `wxTimer` (`StartOnce`), not a self-re-queuing `CallAfter`
+  or `RequestMore()` (§12). Timers: `references/threads-timers-app.md`.
+
+---
+
+## 8. CallAfter and the liveness rule
+
+**Contract** (`interface/wx/event.h:490-564`). `CallAfter(&T::method, args…)` — 0, 1 or 2 arguments;
+"The method being called must be the method of the object on which CallAfter() itself is called" —
+and `CallAfter(functor)`. "it is safe to use CallAfter() from other, non-GUI, threads, but … the
+method will be always called in the main, GUI, thread context." Its documented purpose: actions that
+"can't be performed inside their handlers, e.g. you shouldn't show a modal dialog from a mouse click
+event handler as this would break the mouse capture state". The overview adds the alternative of
+breaking the capture with `dialog.CaptureMouse(); dialog.ReleaseMouse();` when a dialog really must
+be shown from such a handler (`docs/doxygen/overviews/eventhandling.h:878-901`). [source] That pair does not
+break a capture taken through wx's capture stack: `ReleaseMouse` re-captures the previous holder
+(`src/common/wincmn.cpp:3412-3416`), so release your own capture and `CallAfter` the dialog instead. Capture
+rules: `references/mouse-keyboard-focus.md` §Mouse capture.
+
+**Mechanics** [source]. Every overload is `QueueEvent(new wxAsyncMethodCallEvent…(this, …))` on the
+object it is called on (`include/wx/event.h:3815-3855`), executed by the implicit entry in
+`TryHereOnly` only when the event object is that handler (`src/common/event.cpp:1644-1667`).
+Consequences:
+- The functor is copied; method-form arguments are stored by value. Captures must be copyable.
+- **Target destroyed first → the call is silently dropped**, and its captures are destroyed in
+  `DeletePendingEvents` (`src/common/event.cpp:1234-1238`). A `CallAfter` queued from the main thread on a window
+  needs no guard for that window itself.
+- **`SetEvtHandlerEnabled(false)` drops pending calls**: `TryHereOnly` returns before the implicit
+  entry (`src/common/event.cpp:1646-1648`), and the event is consumed.
+- Pushed handlers and `wxEventBlocker` do not block `CallAfter` (it is dispatched on the object).
+- A TLW after `Destroy()` is not deleted yet: it is put on `wxPendingDelete` and hidden (off macOS, unless
+  it is the last visible TLW) (`src/common/toplvcmn.cpp:102-142`; wxOSX `src/osx/toplevel_osx.cpp`); pending events run before
+  the idle-time delete, so `CallAfter`s queued on it still execute on the hidden window.
+  `IsBeingDeleted()` is documented to cover "scheduled for destruction" (`interface/wx/window.h:3620-3633`)
+  but stays `false` until the real delete, because `m_isBeingDeleted` is set only by
+  `SendDestroyEvent` (`src/common/wincmn.cpp:535-557`). Use `wxTheApp->IsScheduledForDestruction(w)`
+  (`interface/wx/app.h:221`) or an alive flag.
+- `wxApp::CallAfter` (Orca: `wxGetApp().CallAfter`) always runs — the app outlives every window — so
+  every object captured by pointer must be re-validated inside.
+
+**The liveness rule.** Every `CallAfter` or other deferred lambda that touches a window, a model item
+or any object other than the handler it was queued on must re-check liveness **inside** the lambda:
+capture a `std::shared_ptr<std::atomic<bool>>` alive flag (set to `false` in the destructor), a
+`std::weak_ptr` token or a `wxWeakRef`, or re-validate the target (registry lookup, model-item scan)
+before touching it. Never capture a bare `this` or `wxDataViewItem` and trust it.
+**Why:** the window or item can die between queueing and execution — dialog closed, plugin unloaded,
+model rebuilt — and the deferred body then dereferences freed memory. Three fixes independently
+added this guard. Self-queued work is the exception: `window->CallAfter(...)` is discarded unexecuted
+when that window is destroyed, so the check is needed only for `wxGetApp().CallAfter(...)` and for
+objects other than the window it was queued on. When a lambda touches only one window, queuing it on
+that window gives the guard for free.
+```cpp
+// Wrong
+CallAfter([this, item] { start_filament_editor(item); });
+
+// Right — re-validate inside the lambda
+CallAfter([this, item] {
+    if (!is_live_model_item(item)) return;      // or: if (!alive->load()) return;
+    start_filament_editor(item);
+});
+
+// Right — app-queued work with an alive flag
+wxGetApp().CallAfter([this, alive = m_alive, payload]() {
+    if (alive->load(std::memory_order_acquire))
+        handle_web_command(payload);
+});
+```
+Cite: 0a0d59b76b (`src/slic3r/GUI/PluginsDialog.cpp/.hpp`, `PluginsDialog::m_alive`,
+`PluginsDialog::on_script_message`), c965b2a5b3 (`src/slic3r/GUI/GUI_ObjectList.cpp`,
+`ObjectList::is_live_model_item`), b779a7bfed (`src/slic3r/plugin/host/PluginHostUi.cpp`, the
+`UiRegistry::is_open` re-check in `ui_create_window`).
+
+**Liveness tools.**
+
+| Tool | Use when | Limits |
+|---|---|---|
+| Queue on the target itself (`win->CallAfter`) | The lambda touches only `win` | Main thread; still runs for a `Destroy()`ed TLW until the idle delete |
+| `std::shared_ptr<std::atomic<bool>>` alive flag (`PluginsDialog::m_alive`) | App-queued work, any thread | Flips at the start of the derived destructor |
+| `std::weak_ptr` token (`MachineObject::add_command_error_code_dlg` with `m_token`, `DeviceManager.cpp`) | Non-window objects | — |
+| `wxWeakRef<T>` (`interface/wx/weakref.h`) | Main-thread checks of a `wxEvtHandler`/window | Reset in `~wxTrackable`, i.e. after the derived destructor and `DestroyChildren`; tracker list unsynchronised (`include/wx/tracker.h`) — create and test on the main thread only |
+| Registry / model re-validation (`UiRegistry::is_open`, `ObjectList::is_live_model_item` in macOS-only code) | Ids or items that may be rebuilt | `is_live_model_item` compares node pointers, so it cannot detect a freed node whose address was reused |
+| `wxTheApp->IsScheduledForDestruction(w)` | Detect a `Destroy()`ed TLW still in `wxPendingDelete` | — |
+| `GUI_App::is_closing()` | Callbacks during shutdown | Check before posting and again inside the lambda |
+
+Deletion and `wxWeakRef` details: `references/windows-dialogs.md`.
+
+**OrcaSlicer.**
+- `run_on_ui_blocking` (`src/slic3r/plugin/host/PluginHostUi.cpp`) captures `fn` and the promise **by
+  reference** in `wxGetApp().CallAfter` and runs `fn` inline when `wxIsMainThread()` (a `CallAfter` +
+  `future.get()` on the main thread would deadlock). It is safe only because the caller blocks until
+  the lambda has run; never copy by-reference captures into a fire-and-forget `CallAfter`.
+- Webview script messages arrive synchronously inside the native callback on WebKitGTK and WKWebView;
+  defer window work from them with `CallAfter` plus an alive check, and in a `WebViewHostDialog`
+  subclass do it in your own `on_script_message`, because the base dispatches synchronously. Details
+  and cites (b779a7bfed, f2ccbfc8b5, 0a0d59b76b): `references/webview-gl-aui-media.md`.
+
+**Pitfalls.**
+- **Rule:** Do not use `IsBeingDeleted()` to detect a `Destroy()`ed TLW. Use an alive flag or
+  `IsScheduledForDestruction`.
+- **Rule:** Do not disable a handler with `SetEvtHandlerEnabled(false)` while it still has
+  `CallAfter`s it needs (§14).
+
+---
+
+## 9. Custom events and payload ownership
+
+**Declaring.** `wxDECLARE_EVENT(NAME, Class)` in the header, `wxDEFINE_EVENT(NAME, Class)` in exactly
+one `.cpp` — "this is a definition so can't be in a header" (`docs/doxygen/overviews/eventhandling.h:634-640`).
+[source] `wxDEFINE_EVENT` expands to `const wxEventTypeTag<T> NAME(wxNewEventType())`
+(`include/wx/event.h:105-106`). A namespace-scope `const` has internal linkage unless an `extern`
+declaration (`wxDECLARE_EVENT`) precedes it, so a header definition alone gives every translation unit
+a **different** event type: binds and posts silently never meet, and nothing fails to link.
+`wxDECLARE_EXPORTED_EVENT` exists only for DLL export (`include/wx/event.h:110-115`).
+
+**Choosing the class** (`docs/doxygen/overviews/eventhandling.h:600-613`): `wxEvent` (no payload, no propagation) or
+`wxCommandEvent` (int, long, string, client data; propagates). For richer payloads derive a class,
+add members and implement `Clone() { return new MyEvent(*this); }` (`docs/doxygen/overviews/eventhandling.h:686-741`);
+event-table macros need extra boilerplate, `Bind` does not. `wxEvent::Clone()` is pure virtual
+(`include/wx/event.h:1009`), so a direct `wxEvent` subclass without `Clone` does not compile — but
+a subclass of a concrete event (`wxCommandEvent::Clone` returns `new wxCommandEvent(*this)`,
+`include/wx/event.h:1655`) silently inherits a slicing `Clone`.
+
+**Payload ownership.**
+
+| Payload | Ownership | Cite |
+|---|---|---|
+| `wxCommandEvent::SetString/SetInt/SetExtraLong` | Copied / by value | `interface/wx/event.h` wxCommandEvent |
+| `wxCommandEvent::SetClientData(void*)` | Raw pointer, never owned | — |
+| `wxCommandEvent::SetClientObject(wxClientData*)` | "not owned by the event … must be owned and deleted by another object (e.g. a control) that has longer life time than the event object" | `interface/wx/event.h:2210-2216` |
+| `wxEvtHandler::SetClientObject(wxClientData*)` | Owned by the handler: "Any previous object will be deleted"; deleted in `~wxEvtHandler`; do not mix with `SetClientData` on the same handler | `interface/wx/event.h:1062-1074`; [source] `src/common/event.cpp:1240-1242` |
+| `Bind(…, userData)` | Owned by the binding, deleted on unbind or at exit | `interface/wx/event.h:900-905` |
+| `wxThreadEvent::SetPayload<T>` | Copied; T's copy must not share state | `interface/wx/event.h:3775-3790` |
+
+[source] For a `wxEVT_TEXT` event whose event object is a text-entry window,
+`wxCommandEvent::GetString()` always returns the control's **current** value and ignores the stored
+string (`src/common/event.cpp:430-447`). The copy constructor materialises the stored string
+(`include/wx/event.h:1622-1632`), but a queued or cloned copy still has the event object, so its
+`GetString()` reads the control live at handling time. If the value at emit time matters, capture it
+yourself.
+
+**OrcaSlicer.**
+- Custom event types are declared in headers (`GLCanvas3D.hpp` and `Plater.hpp` in
+  `Slic3r::GUI`; widget events such as `EVT_SPINCTRL_TEXT`, `wxEVT_TAB_SEL_CHANGED` at global scope)
+  and defined once in the matching `.cpp`.
+- Payload classes in `src/slic3r/GUI/Event.hpp`: `SimpleEvent`, `IntEvent` (`get_data()`),
+  `Event<T>` (`.data`), `ArrayEvent<T, N>` (`.data`). All derive from `wxEvent`, propagate (§5), and
+  their `Clone()` copies type, data and event object (not the id). `LoadPrinterViewEvent` there shows
+  the `wxCommandEvent`-derived shape: a copy constructor that copies the extra member, and
+  `Clone() { return new LoadPrinterViewEvent(*this); }`.
+  ```cpp
+  wxDECLARE_EVENT(EVT_GLCANVAS_INCREASE_INSTANCES, Event<int>);   // GLCanvas3D.hpp
+  wxDEFINE_EVENT(EVT_GLCANVAS_INCREASE_INSTANCES, Event<int>);    // GLCanvas3D.cpp
+  post_event(Event<int>(EVT_GLCANVAS_INCREASE_INSTANCES, +1));    // GLCanvas3D, posts on m_canvas
+  view3D_canvas->Bind(EVT_GLCANVAS_INCREASE_INSTANCES, [this](Event<int>& e) { /* e.data */ });
+  ```
+- Simple dialog-level events use `wxCommandEvent` with `SetInt`/`SetString`/`SetEventObject`
+  (`ReleaseNote.cpp` `EVT_SECONDARY_CHECK_*`; `MsgDialog::show_dsa_button` posts
+  `EVT_CHECKBOX_CHANGE` with `wxPostEvent(this, event)`).
+
+**Pitfalls.**
+- **Rule:** Never put `wxDEFINE_EVENT` in a header.
+  ```cpp
+  // Wrong (header): one event type per .cpp that includes it
+  wxDEFINE_EVENT(EVT_MY_THING, wxCommandEvent);
+  // Right
+  wxDECLARE_EVENT(EVT_MY_THING, wxCommandEvent);   // header
+  wxDEFINE_EVENT(EVT_MY_THING, wxCommandEvent);    // one .cpp
+  ```
+- **Rule:** A posted custom event class overrides `Clone()` and copies every payload member.
+  **Why:** `wxPostEvent`/`wxQueueEvent(evt.Clone())`/`AddPendingEvent` clone the event; an inherited
+  `Clone` slices it to the base class, and the handler's cast to the derived type reads garbage.
+
+---
+
+## 10. Window and event ids
+
+**Contract.**
+- `wxID_ANY` in a constructor asks wx for an id; automatic ids "are always negative and so will never
+  conflict with the user-specified identifiers which must be always positive". Custom ids belong
+  above `wxID_HIGHEST` or below `wxID_LOWEST` (`docs/doxygen/overviews/eventhandling.h:863-875`),
+  "should not have values 0 or 1", and "they are not needed when using wxEvtHandler::Bind()" if you
+  bind on the control (`docs/doxygen/overviews/windowids.h:32-42`). Stock ids span `wxID_LOWEST`
+  (5000) to `wxID_HIGHEST` (6000) (`include/wx/defs.h:1786-1787, 1943`).
+- `wxNewId()`: "@deprecated Ids generated by it can conflict with the Ids defined by the user code,
+  use wxID_ANY …" (`interface/wx/utils.h:433-444`). The header does not mark it deprecated, so there is
+  no compiler warning. [source] It starts at 100, skips the stock range and never reuses an id
+  (`src/common/utilscmn.cpp:654-663`).
+- `wxWindow::NewControlId(count)` reserves auto ids (`interface/wx/window.h:4348-4376`; main thread).
+
+**Platforms** [source]. `wxUSE_AUTOID_MANAGEMENT` defaults ON for Windows builds and OFF elsewhere
+(`build/cmake/options.cmake:520-528`). With it (MSW), auto ids are reference-counted in
+`-32000..-2000`, handed out upward from -32000, and once that range has been used up the allocator
+scans for ids whose window or menu item is gone and **reuses** them — contradicting
+`docs/doxygen/overviews/windowids.h:28-30` ("an ID that had never been returned by this function
+before"); without it (macOS, GTK) they count down from -2000 to -1000000 and then wrap unchecked
+(`src/common/windowid.cpp:187-251`, `include/wx/defs.h:1755-1772`). `wxMenuItem` holds its id as a `wxWindowIDRef`
+(`include/wx/menuitem.h`). MSW native ids are 16-bit: `CreateBase` accepts `wxID_ANY`, `0..32766` or
+the auto range (`src/common/wincmn.cpp:369-375`; the assert is compiled out in Orca, so an
+out-of-range id fails silently).
+
+**OrcaSlicer.**
+- `append_menu_item`/`append_submenu` (`src/slic3r/GUI/wxExtensions.cpp`) assign `wxNewId()` for
+  `wxID_ANY` and bind handlers filtered by that id: `append_menu_item` binds `wxEVT_MENU` on the menu
+  (dies with it; on MSW on a non-null `event_handler` instead), and with a non-null `parent` both helpers bind `wxEVT_UPDATE_UI` on `parent`, never
+  unbound. That is safe only because `wxNewId` ids are never reused and the menus are built once; switching them
+  to `NewControlId` (recycled on MSW) would let stale handlers fire for new items. Menu event routing:
+  `references/popups-menus.md`.
+- **Field window pools** (`src/slic3r/GUI/Field.cpp`, `Builder::build`, `free_window`; not on GTK,
+  where windows are deleted): option widgets are reused across page rebuilds, and `free_window`
+  unbinds every dynamic entry that was bound with an explicit id (on the widget and its inner
+  `wxTextCtrl`). Convention: `Field` handlers on pooled widgets pass the control id as the `Bind` id
+  (`…, temp->GetId())`); a handler bound without an id survives into the next `Field` that reuses the
+  widget and dangles. Widget-internal handlers use `wxID_ANY` and survive by design.
+  `GUI_App::recreate_GUI` releases the old pools through a `wxClientData` it hands to the old
+  `MainFrame` with `SetClientObject`, so they are freed when that frame's `~wxEvtHandler` runs (§9).
+
+**Pitfalls.**
+- **Rule:** Bind on the emitting control, not on an ancestor filtered by id.
+  **Why:** with recycled ids (MSW) a stale ancestor binding fires for an unrelated new control; an
+  unfiltered ancestor binding catches every descendant.
+  ```cpp
+  // Wrong
+  panel->Bind(wxEVT_BUTTON, &MyPanel::on_ok, this, ok_btn->GetId());
+  // Right
+  ok_btn->Bind(wxEVT_BUTTON, &MyPanel::on_ok, this);
+  ```
+
+---
+
+## 11. wxEVT_UPDATE_UI
+
+**Contract** (`interface/wx/event.h:2444-2523`). Update-UI pseudo-events are sent "in idle time" from
+`wxWindow::OnInternalIdle`; handlers call `evt.Enable/Check/Show/SetText`. Popup menus are updated
+just before showing (`wxMenu::UpdateUI`). "On Windows and GTK+, events for menubar items are only
+sent when the menu is about to be shown, and not in idle time." Default mode
+`wxUPDATE_UI_PROCESS_ALL`, interval 0. Throttle with `wxUpdateUIEvent::SetMode(wxUPDATE_UI_PROCESS_SPECIFIED)`
+plus `wxWS_EX_PROCESS_UI_UPDATES` on the windows that need it, or `SetUpdateInterval(ms)` with
+`UpdateWindowUI()` at critical points (`interface/wx/event.h:2470-2479`; `interface/wx/window.h:286-288`).
+
+**Source facts** [source].
+- Each idle pass calls `UpdateWindowUI` for every window whose parent is shown on screen
+  (`src/common/wincmn.cpp:2810-2814`, `src/common/event.cpp:499-530` `wxUpdateUIEvent::CanUpdate`).
+  The event is a command event: unhandled, it bubbles to the TLW and `wxApp`, and every hop scans
+  that handler's whole dynamic table. Many `parent->Bind(wxEVT_UPDATE_UI, …, id)` entries on a frame
+  tax every idle pass.
+- Menubar update-on-open applies to macOS too: `wxUSE_IDLEMENUUPDATES` is 0 for MSW, GTK and OSX
+  (`include/wx/platform.h:535-545`), except wxGTK with a global menu bar, which falls back to idle
+  updates (`src/common/framecmn.cpp:66-79`).
+
+**Pitfall.**
+- **Rule:** Keep update-UI handlers to cheap state reads; never do layout, I/O or model scans in them.
+
+---
+
+## 12. Idle events
+
+**Contract** (`interface/wx/event.h:4383-4441`). Idle events are sent once when the loop becomes idle;
+a continuous stream needs `RequestMore()` or `wxWakeUpIdle()`, and "both of these approaches (and
+especially the first one) increase the system load". `wxIdleEvent::SetMode(wxIDLE_PROCESS_SPECIFIED)`
+plus `wxWS_EX_PROCESS_IDLE` limits recipients. Documented: "The children of hidden windows do not
+receive idle events". The "delayed action" idiom binds an idle handler that unbinds itself;
+`CallAfter` is simpler.
+
+**Source facts** [source].
+- **Contradicts the doc:** `wxWindowBase::SendIdleEvents` recurses into every child without a
+  visibility check (`src/common/wincmn.cpp:2783-2808`); only update-UI skips children of hidden
+  windows (`src/common/event.cpp:508-513`). Idle handlers on hidden panels run.
+- One `wxIdleEvent` object is reused for all windows in a pass; TLWs pending deletion are skipped,
+  and `DeletePendingObjects` runs from the app's idle processing (`src/common/appcmn.cpp:408-429`,
+  `src/common/appbase.cpp:442-462`). `wxYield()` runs pending events and one idle pass
+  (`src/common/evtloopcmn.cpp:172-192`) — so it can delete `Destroy()`ed TLWs under your feet.
+
+**OrcaSlicer.** `DropDown::Create` binds an empty, non-skipping `wxEVT_IDLE` handler on macOS.
+Because dynamic handlers run before the static table, this shadows `wxPopupTransientWindow::OnIdle`
+(static table, `src/common/popupcmn.cpp:108-112, 439-471`) and its idle-time capture juggling, so the
+capture taken in `Show` is held until the drop-down hides. `FanControlPopupNew` binds the same no-op,
+but it is a `wxDialog`, which has no such idle handler to shadow. Popup mechanics:
+`references/popups-menus.md`.
+
+**Pitfall.**
+- **Rule:** Use `wxTimer` (`StartOnce`) or `CallAfter` instead of idle handlers for periodic or
+  delayed work.
+  **Why:** idle fires once per wake-up, does not run inside MSW native modal loops (§7), runs for
+  hidden panels, and `RequestMore()` busy-loops a core.
+
+---
+
+## 13. Event filters
+
+**Contract.** `wxApp::FilterEvent` and any `wxEventFilter` registered with
+`wxEvtHandler::AddFilter` run for every event before anything else, in LIFO order, with wxApp
+registered by default (`interface/wx/event.h:1195-1214`). Return `Event_Skip` (-1) to continue,
+`Event_Ignore` (0) or `Event_Processed` (1) to stop (`interface/wx/eventfilter.h:85-93`). "having event
+filters adds additional overhead to every event … return as quickly as possible"
+(`interface/wx/eventfilter.h:18-20`). A standalone filter must be removed with `RemoveFilter` before it is
+destroyed (`interface/wx/eventfilter.h:108-114`; misuse is silent in Orca).
+
+**OrcaSlicer.**
+- `GUI_App::FilterEvent` only timestamps user input (non-command `wxEVT_CATEGORY_USER_INPUT` events
+  and main-frame size events) and always returns `Event_Skip` — keep it that cheap.
+- `SplashScreen::FilterEvent` (in `GUI_App.cpp`) returns `wxEventFilter::Event_Skip` to disable
+  `wxSplashScreen`'s own filter, which `Close()`s (and so `Destroy()`s) the splash on any key or mouse
+  press (`src/generic/splash.cpp:40-45, 105-126`) while `GUI_App::on_init_inner` still holds it
+  (as a `wxWeakRef<SplashScreen>`). Cite: 4088a36095.
+
+---
+
+## 14. Pushed handlers, wxEventBlocker, SetEvtHandlerEnabled
+
+**Contract.**
+- `PushEventHandler(h)`: `h` must not be part of another chain; events reach the most recently pushed
+  handler first and the window last (`interface/wx/window.h:2779-2809`). `PopEventHandler(deleteHandler
+  = false)` — an error with nothing pushed (`interface/wx/window.h:2759-2777`); `RemoveEventHandler(h)` removes from
+  the middle (`interface/wx/window.h:2811-2827`). `SetNextHandler` on a window is not supported — windows use the
+  stack (`interface/wx/window.h:2843-2851`).
+- `wxEventBlocker(win, type = wxEVT_ANY)` discards events of the given types directed to `win`; `win`
+  "must remain alive until the wxEventBlocker object destruction" (`interface/wx/event.h:287-337`).
+- `SetEvtHandlerEnabled(false)`: the handler's dynamic and static tables are skipped, processing
+  resumes at the chain step (`docs/doxygen/overviews/eventhandling.h:466-471`).
+
+**Source facts** [source].
+- **Pop before destroy.** `~wxWindowBase` asserts "any pushed event handlers must have been removed"
+  (`src/common/wincmn.cpp:468-472`) — compiled out in Orca, so a forgotten pushed handler is a
+  dangling pointer, not an assert.
+- `wxEventBlocker` is a pushed handler whose `ProcessEvent` returns `true` for blocked types
+  (`src/common/event.cpp:2075-2103`). Its destructor pops whatever is on top; pushing another handler
+  inside its scope corrupts the stack. It only sees events dispatched through `GetEventHandler()` —
+  not posted events, `CallAfter`, or a direct `win->ProcessEvent`. Blocked command events count as
+  processed and do not propagate.
+- `SetEvtHandlerEnabled(false)` does not affect handlers bound on other objects for this window's
+  events, validators, the chain, or propagation — and it drops queued `CallAfter`s (§8).
+  `wxWindow::Enable(false)` only stops native input; posted and synthetic events still reach the
+  handlers (`src/common/event.cpp:1644-1648` checks only the handler flag).
+
+**OrcaSlicer.**
+- `StateHandler` (`src/slic3r/GUI/Widgets/StateHandler.cpp`) is a `wxEvtHandler` pushed on every
+  `StaticBox`-based widget (member `StaticBox::state_handler`) and on attached children
+  (`attach_child`). It binds on itself, tracks enabled/checked/focused/hovered/pressed, always
+  Skips, and removes itself with `RemoveEventHandler` in its destructor. Member destruction runs
+  before `~wxWindowBase`, so it is gone in time. Call `remove_child(child)` before destroying an
+  attached child separately. Emitting through `GetEventHandler()` (§6) is what lets it see
+  synthesized events such as `EVT_ENABLE_CHANGED`.
+- `PrinterWebView::~PrinterWebView` (`PrinterWebView.cpp`) and `WebViewPanel::~WebViewPanel`
+  (`WebViewDialog.cpp`) call
+  `SetEvtHandlerEnabled(false)` first, so events raised while the webview and members are torn down
+  do not reach handlers that touch freed members.
+
+**Pitfall.**
+- **Rule:** Pop pushed handlers in reverse push order, before the window dies.
+  ```cpp
+  // Wrong: blocker2 pops blocker1's entry (or a foreign handler) — stack corrupted, no assert in Orca
+  auto* b1 = new wxEventBlocker(win); wxEventBlocker b2(win); delete b1;
+  // Right: nested scopes
+  { wxEventBlocker b1(win); { wxEventBlocker b2(win, wxEVT_TEXT); /* … */ } }
+  ```
+
+---
+
+## 15. Exceptions in handlers
+
+**Contract.** `wxApp::OnExceptionInMainLoop` returns `true` to continue the loop or `false` to exit;
+the default is to exit "in all ports except under Windows where a dialog is shown"; if it rethrows and
+the exception cannot be stored, the program terminates (`interface/wx/app.h:465-480`). Since 3.3.0 the
+system option `catch-unhandled-exceptions` set to 0 (environment variable
+`wx_catch_unhandled_exceptions=0`) stops wx from catching unhandled exceptions, so the default abort
+happens and the backtrace or crash dump is more likely to show where the exception came from
+(`interface/wx/sysopt.h:17-23, 40-49`).
+
+[source] If `OnExceptionInMainLoop` throws, `wxEvtHandler::WXConsumeException` exits the current loop
+and stores the exception or aborts; the wx comment explains that exceptions "can't propagate through
+the C GTK+ code and corrupt the stack" (`src/common/event.cpp:1688-1749`).
+
+**OrcaSlicer.** `GUI_App::OnExceptionInMainLoop` calls `generic_exception_handle()`, whose every
+path terminates or rethrows, so its `return false` is never reached: `std::bad_alloc` and
+`boost::io::bad_format_string` show a message box and terminate; other `std::exception`s are logged,
+reported with `wxLogError` and rethrown (non-`std` exceptions escape unlogged), so the main loop exits
+and `wxEntry` ends with the fatal exit code. An exception that escapes any handler ends the session.
+Unwinding order and exit code: `references/threads-timers-app.md` §Exceptions in the main loop.
+
+**Pitfall.**
+- **Rule:** Catch inside any handler (and any `CallAfter` lambda) that can throw — file, network,
+  JSON, config parsing — and report the error there; never let an exception cross a native callback.
+
+---
+
+## 16. How Orca widgets emit events
+
+The per-widget table (event types, ids and event objects, which setters emit, where to bind) is
+`references/orca-widgets.md` §Event semantics, with per-widget binding pitfalls in
+`references/controls-dataview.md` §Orca replacement widgets. The event mechanics behind them:
+
+- **Synchronous, through the handler stack.** Orca widgets emit with `GetEventHandler()->ProcessEvent` (§6), so
+  the pushed `StateHandler` (§14) sees the event and command events propagate to ancestors (§5). Exceptions:
+  `SwitchBoard` posts `wxCUSTOMEVT_SWITCH_POS` with `wxPostEvent(this, …)` from `SwitchBoard::on_left_down`
+  (asynchronous: the handler runs after the click handler returns; no event object, id 0), and `TempInput` posts
+  `wxCUSTOMEVT_SET_TEMP_FINISH` to its parent (`TempInput::SetFinish`).
+- **Local re-dispatch.** `TextInput` and `SpinInput` catch the inner control's `wxEVT_TEXT_ENTER`/
+  `wxEVT_KILL_FOCUS` and re-send them with the wrapper's id through `ProcessEventLocally` (§6): the wrapper's
+  handlers run, its parents never see them. The inner `wxEVT_TEXT` propagates normally, with the inner control's id
+  and object, so bind it on the wrapper with `wxID_ANY`, not the wrapper's id.
+- **Internal handlers run after yours** (§4). `Button` keeps LEFT_DOWN/LEFT_UP/MOUSE_CAPTURE_LOST/KEY_DOWN/KEY_UP/
+  PAINT in its static table (`wxEVT_BUTTON` comes from `Button::mouseReleased`; Space/Enter synthesize LEFT_DOWN/UP
+  in `Button::keyDownUp`); `::CheckBox` and `SwitchButton` bind their own `wxEVT_TOGGLEBUTTON` handler in the
+  constructor (clears the half state, refreshes the bitmap, Skips); `TextInput`'s handlers on the inner control run
+  `OnEdit` and the re-dispatch. A user handler bound on the widget (or on `GetTextCtrl()`) for those events must
+  `Skip()`. Capture-lost handling: `references/mouse-keyboard-focus.md`.
+- **`EVT_ENABLE_CHANGED`** (`StateHandler.hpp`, a `wxCommandEvent` with id 0) comes from the `Enable` overrides of
+  `Button`, `SpinInput`, `RadioGroup` and the other `StateHandler` widgets. `StateHandler` Skips it, so it
+  propagates to ancestors like any command event.
+- **Id-less events still propagate.** `ComboBox`'s `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` (id 0, no event object),
+  `RadioGroup`'s `wxEVT_RADIOBOX` (`wxEVT_COMMAND_RADIOBOX_SELECTED` is an alias, `include/wx/event.h:4910`; no
+  event object) and `EVT_ENABLE_CHANGED` reach every ancestor bound by type. Bind on the specific widget, never on
+  an ancestor filtered by its id (§10).
+- **Popup relay.** `DropDown` emits `wxEVT_COMBOBOX` on itself (`sendDropDownEvent`, its own id and object); as a
+  `PopupWindow` it stops an unconsumed event on MSW/macOS only (§5). `ComboBox` binds it on the `DropDown`,
+  consumes it and re-emits it with its own id and object.
+- **Emitting setters.** `RadioGroup::SetSelection` (every call, same index included), `MultiSwitchButton::SetSelection`,
+  `TabCtrl::SelectItem` (CHANGING carries the old index and cannot veto: `sendTabCtrlEvent` always returns `true`),
+  `SpinInput::SetValue` (`EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`), `Notebook::SetSelection` (PAGE_CHANGING/CHANGED, as in
+  wx) and, in an editable or `CB_NO_TEXT` combo, `ComboBox::SetSelection`/`SetValue` (`wxEVT_TEXT` through
+  `ComboBox::SetLabel`) emit synchronously. Guard model→view refreshes (`references/controls-dataview.md` §Events from programmatic changes).

.claude/skills/orca-wxwidgets/references/mouse-keyboard-focus.md

@@ -0,0 +1,968 @@
+# Mouse, keyboard and focus
+
+How input reaches wx windows in the wxWidgets 3.3.2 build Orca ships, and the Orca conventions on
+top: mouse capture, mouse and key events, accelerators and Orca's shortcut registry, focus,
+tooltips and cursors. Read it when a widget captures the mouse or tracks hover, when adding or
+changing a keyboard shortcut, when touching focus, tooltip or cursor code, and when debugging an
+"alive but unclickable" UI, lost or phantom clicks, or shortcuts that fire while typing.
+
+wx asserts are compiled out in Orca (`wxDEBUG_LEVEL=0`), so every misuse below that wx documents as
+an assert fails silently. "GTK" means wxGTK3, Orca's Linux default (X11 and Wayland); GTK2 is only
+an opt-out build (`-DDEP_WX_GTK3=OFF`), noted where it differs. Paths starting `interface/`,
+`include/`, `src/`, `docs/` are in the wx tree
+(`find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets'`); Orca paths are
+relative to `src/slic3r/GUI/`.
+
+Contents: [Rules](#rules) · [Mouse capture](#mouse-capture) · [Mouse events](#mouse-events) ·
+[Global pointer position and Wayland](#global-pointer-position-and-wayland) ·
+[Hover handlers and enter/leave feedback loops](#hover-handlers-and-enterleave-feedback-loops) ·
+[Keyboard events](#keyboard-events) · [Accelerators and menu shortcuts](#accelerators-and-menu-shortcuts) ·
+[Orca's shortcut registry](#orcas-shortcut-registry) · [Focus](#focus) · [Tooltips](#tooltips) ·
+[Cursors](#cursors)
+
+## Rules
+
+1. Capture only with `if (!HasCapture()) CaptureMouse();` and release only with
+   `if (HasCapture()) ReleaseMouse();`, at every site. → [Capture stack](#the-capture-stack)
+2. On button-up, release whenever `HasCapture()` is true, never gated on a gesture flag that other
+   code can clear; decide whether to *commit* separately. → [Cancel-on-lost pattern](#the-cancel-on-lost-pattern)
+3. Every window that captures handles `wxEVT_MOUSE_CAPTURE_LOST` by *cancelling*: reset state and
+   `Refresh()`. No commit, no `Skip()`, no `CaptureMouse()`, no unguarded `ReleaseMouse()`. Never route it
+   through the mouse-up/commit path. → [Cancel-on-lost pattern](#the-cancel-on-lost-pattern)
+4. Release capture before `Hide()`, `Destroy()`/`delete` and in the destructor. →
+   [While captured](#modal-dialogs-popups-and-destruction-while-captured)
+5. Never show a modal dialog, popup or message box from a handler that runs while the mouse is
+   captured: release your own capture, then `CallAfter` the dialog. →
+   [While captured](#modal-dialogs-popups-and-destruction-while-captured)
+6. Write capture code as if `wxEVT_MOUSE_CAPTURE_LOST` did not exist on macOS (it is never sent there);
+   a leaked capture freezes every click in the app. → [macOS](#macos-rerouting-and-the-frozen-ui-diagnosis)
+7. Mouse handlers take `wxMouseEvent&` (never by value) and `Skip()` `wxEVT_LEFT_DOWN` so focus still
+   moves. → [Button state and clicks](#button-state-and-clicks)
+8. A handler that counts presses binds `wxEVT_LEFT_DCLICK` too: the second press of a double click
+   is a DCLICK, not a DOWN, on every port. → [Button state and clicks](#button-state-and-clicks)
+9. Wheel: divide `GetWheelRotation()` by `GetWheelDelta()`, filter `GetWheelAxis()`, accumulate for
+   discrete steps. → [Wheel](#wheel)
+10. On macOS, read button state on non-button events (motion, enter/leave, up, wheel) from
+    `wxGetMouseState()`, not the event. → [Button state and clicks](#button-state-and-clicks)
+11. No global screen coordinates in logic that must work on Linux: no `wxGetMousePosition()`,
+    `wxFindWindowAtPoint()` or cross-window screen-rect tests. Use the event's client position,
+    `GetClientRect()` and focus tracking; guard unavoidable uses with `is_running_on_wayland()`. →
+    [Global pointer](#global-pointer-position-and-wayland)
+12. Never use `wxGetKeyState()` for non-modifier keys (always false on Wayland); track
+    `wxEVT_KEY_DOWN`/`wxEVT_KEY_UP`. → [Global pointer](#global-pointer-position-and-wayland)
+13. Enter/leave handlers only record hover state, per child window. Apply `Show()`/`Hide()` +
+    `Layout()` from `wxEVT_IDLE` or `CallAfter`, only when the state differs. No `wxFindWindowAtPoint()`
+    there, and no `IsShownOnScreen()` as a guard. → [Hover](#hover-handlers-and-enterleave-feedback-loops)
+14. To see a child's keys, bind `wxEVT_CHAR_HOOK` on the parent and `Skip()` everything not
+    handled; `wxEVT_KEY_DOWN`/`wxEVT_CHAR` do not propagate. → [wxEVT_CHAR_HOOK](#wxevt_char_hook)
+15. A top-level `wxEVT_CHAR_HOOK` must not consume printable keys, Space or text-editing chords
+    (Ctrl+A/C/V/X/Z, Delete, Backspace, Home/End, arrows) while a text entry has focus. →
+    [wxEVT_CHAR_HOOK](#wxevt_char_hook)
+16. Test modifiers with `GetModifiers() == wxMOD_…`, not `ControlDown()`; on macOS `wxMOD_CONTROL` is
+    Cmd and `wxMOD_RAW_CONTROL` is the Control key. → [Modifiers](#modifiers-and-the-cmd-mapping)
+17. Match letters, digits and special keys on `wxEVT_KEY_DOWN` and punctuation on `wxEVT_CHAR`;
+    build chords with `KeyChord::from_event`. → [Key codes](#key-codes)
+18. New user-facing shortcuts go through the registry (`Shortcut` enum + `shortcut_table` row + a case in
+    the context's dispatcher). No raw `wxAcceleratorTable`, hard-coded key test or literal key name in a
+    label. → [Registry](#orcas-shortcut-registry)
+19. Global chords need Ctrl/Alt or a key that types nothing. On macOS a live menu accelerator is
+    consumed by the menu bar before any wx key event, so the menu handler and the dispatcher case
+    must do the same thing. → [Accelerators](#accelerators-and-menu-shortcuts)
+20. `SetAcceleratorTable()` replaces the window's table; build one table per window. It fires only
+    while focus is inside that window and stops at the top-level window. → [Accelerators](#accelerators-and-menu-shortcuts)
+21. `SetFocus()` only on a user action or when the top-level window `IsActive()`; never from hover or
+    timers unconditionally, never inside `wxEVT_KILL_FOCUS` (defer with `CallAfter`). Focus handlers
+    `Skip()`. → [Focus](#focus)
+22. Clear a tooltip with `UnsetToolTip()`, not `SetToolTip("")`. A composite that forwards tooltips
+    overrides `DoSetToolTip` as well as `DoSetToolTipText`. → [Tooltips](#tooltips)
+23. Tooltips on disabled controls only through the MSW-gated parent-motion hack
+    (`Button::EnableTooltipEvenDisabled`); never install parent-motion forwarding on macOS. →
+    [Tooltips](#tooltips-on-disabled-controls)
+24. Set a window cursor once with `SetCursor()`, reset with `wxNullCursor`, never toggle it on
+    enter/leave. Busy cursors via `wxBusyCursor` RAII, on the main thread. → [Cursors](#cursors)
+
+## Mouse capture
+
+### Contract
+
+`CaptureMouse()` "Directs all mouse input to this window". wx "maintains the stack of windows having
+captured the mouse … you must release the mouse as many times as you capture it, unless the window
+receives the wxMouseCaptureLostEvent event. Any application which captures the mouse in the
+beginning of some operation must handle wxMouseCaptureLostEvent and cancel this operation when it
+receives the event. The event handler must not recapture mouse." (`interface/wx/window.h:3805-3819`)
+
+`wxMouseCaptureLostEvent` goes to **all windows on the capture stack** when capture is lost to an
+"external" event (a dialog box shown, another application capturing the mouse). It is "not sent if
+the capture changes because of a call to CaptureMouse or ReleaseMouse"
+(`interface/wx/event.h:3496-3514`). The doc's "currently emitted under Windows only" /
+`@onlyfor{wxmsw}` is stale: wxGTK sends it too, wxOSX never does (table below).
+`wxMouseCaptureChangedEvent` is MSW-only and is sent to a window that loses capture "even if
+wxWindow::ReleaseMouse was called by the application code"; the doc's purpose: "allows an application
+to cater for unexpected capture releases" (`interface/wx/event.h:4659-4680`; only `src/msw/window.cpp`
+`wxWindowMSW::HandleCaptureChanged` builds it).
+
+### The capture stack
+
+[source] `src/common/wincmn.cpp:3322-3456` (namespace `wxMouseCapture`; the stack is a
+`wxVector`, i.e. `std::vector`):
+
+| Call | Behaviour |
+|---|---|
+| `CaptureMouse()` (:3352) | Asserts (compiled out) if `this` is already anywhere on the stack. Natively releases the current holder, `DoCaptureMouse()`, pushes `this`. A second call on the same window pushes it **twice**. |
+| `ReleaseMouse()` (:3371) | Calls `DoReleaseMouse()` **first**, dropping the native capture whoever owns it. Then `wxCHECK_RET(stack.back() == this)` returns silently if this window is not on top. Pops, and if the stack is non-empty **re-captures the new top** (:3412-3416). |
+| `HasCapture()` | `AsWindow() == GetCapture()` (`include/wx/window.h:1125`): true only for the top of the stack. |
+| `NotifyCaptureLost()` (:3438) | Does nothing while a wx `Capture/ReleaseMouse` is in progress. Otherwise sends the lost event to each stacked window, top first, popping each. The stack ends empty, so no `ReleaseMouse()` is owed afterwards. A handler that leaves the event unprocessed (`Skip()`) hits a compiled-out `wxFAIL` (:3423-3436). |
+| `~wxWindowBase` (:452) | Asserts (compiled out) if the window is still on the stack, and does **not** remove it: the stack keeps a dangling pointer. |
+
+Consequences:
+- Double capture followed by one release leaves the **same window captured** (the restore step
+  re-captures it). That is a leaked capture.
+- An unguarded `ReleaseMouse()` from a window that is not on top frees the real owner's native
+  capture and leaves the stack out of step; a later release can re-capture a stale window.
+- An unguarded `ReleaseMouse()` inside the lost handler pops the stack while `NotifyCaptureLost`
+  is iterating it. The loop then pops an entry it never notified, or calls `pop_back()` on an
+  empty vector (undefined behaviour). A `HasCapture()`-guarded release is a harmless no-op there
+  (next table).
+- The documented way to break capture before a modal, `dialog.CaptureMouse(); dialog.ReleaseMouse();`
+  (`docs/doxygen/overviews/eventhandling.h:878-901`), is undone by the restore step when the
+  current holder captured through wx: the release re-captures the previous holder. It only breaks
+  a capture taken natively, outside wx's stack.
+
+### Per-port delivery
+
+| | MSW | GTK3 / GTK2 | macOS |
+|---|---|---|---|
+| Native capture | `SetCapture` | `gdk_seat_grab` (GTK ≥ 3.20) or `gdk_pointer_grab`. On an unrealized window `DoCaptureMouse` fails a silent `wxCHECK_RET`, but `wincmn` still pushes it (`src/gtk/window.cpp:6732-6765`) | None. `DoCaptureMouse` sets `wxApp::s_captureWindow` and wx reroutes events (`src/osx/window_osx.cpp:596-612`) |
+| Capture-lost sent | `WM_CAPTURECHANGED` → `HandleCaptureChanged` → `NotifyCaptureLost`, then `wxEVT_MOUSE_CAPTURE_CHANGED` (`src/msw/window.cpp:5176-5192`) | GTK `grab-broken-event` (`src/gtk/window.cpp:2636-2646`). `wxDialog::ShowModal` and `wxMessageDialog::ShowModal` release the grab and notify (`src/gtk/dialog.cpp:137`, `src/gtk/msgdlg.cpp:285` → `GTKReleaseMouseAndNotify`) | **Never.** `src/osx` has no `NotifyCaptureLost` call |
+| `HasCapture()` inside the lost handler | false: `GetCapture()` returns null while `gs_insideCaptureChanged` (`src/msw/window.cpp:757-768`) | false: `g_captureWindow` is cleared before notifying (`src/gtk/window.cpp:6794-6815`) | n/a |
+| Modal dialog shown while captured | Lost event only if something takes the native capture (`WM_CAPTURECHANGED`) | Capture released, lost event sent | Capture kept; the dialog cannot be clicked (`src/osx/dialog_osx.cpp` `ShowModal` has no capture code) |
+| Captor destroyed | wx stack dangles | `g_captureWindow` cleared (`src/gtk/window.cpp:3088-3089`); wx stack dangles | `s_captureWindow` dangles; the next mouse event dereferences it |
+| `wxEVT_CHAR_HOOK` while captured | Not generated (any native `::GetCapture()`) | Not generated | Generated |
+| Enter/leave while captured | Synthesized for the captor only (`src/msw/window.cpp:6019-6074`) | Synthesized for the captor only; grab crossings ignored (`src/gtk/window.cpp:2073-2117, 2384-2456`) | Other views' enter/exit events are rerouted to the captor |
+
+### The cancel-on-lost pattern
+
+```cpp
+// EVT_MOUSE_CAPTURE_LOST(MyWidget::mouseCaptureLost) in the event table, or Bind(...)
+void MyWidget::mouseDown(wxMouseEvent& e)
+{
+    e.Skip();                               // let focus move
+    m_pressed = true;
+    if (!HasCapture()) CaptureMouse();      // a second button mid-press must not push twice
+    Refresh();
+}
+void MyWidget::mouseReleased(wxMouseEvent& e)
+{
+    e.Skip();
+    if (HasCapture()) ReleaseMouse();       // always, not only when m_pressed
+    if (!m_pressed) return;
+    m_pressed = false;
+    Refresh();
+    if (GetClientRect().Contains(e.GetPosition()))
+        sendButtonEvent();                  // commit only on a real button-up inside
+}
+void MyWidget::mouseCaptureLost(wxMouseCaptureLostEvent&)
+{
+    m_pressed = false;                      // cancel: no commit, no Skip(),
+    Refresh();                              // no CaptureMouse(), no unguarded ReleaseMouse()
+}
+MyWidget::~MyWidget() { if (HasCapture()) ReleaseMouse(); }
+```
+
+Copy the `HasCapture()` guards from `Widgets/Button.cpp` `Button::mouseDown`/`Button::mouseReleased`,
+but not the rest of that class's shape: `Button::mouseReleased` releases only inside its
+`pressedDown` branch, and `Button::mouseCaptureLost` routes through `mouseReleased` (the commit
+path, see Pitfalls). Take the cancel shape from `Widgets/SwitchButton.cpp`
+`ModeSwitchButton::mouseCaptureLost`, minus its `Skip()`.
+`Widgets/SpinInput.cpp` `SpinInput::createButton` shows the guards on `Bind` lambdas, with
+`wxEVT_LEFT_DCLICK` bound next to `wxEVT_LEFT_DOWN`.
+
+macOS never sends the lost event, so a widget that must survive an interrupted gesture there needs
+stand-ins. Cancel and release when the top-level window reports `wxEVT_ACTIVATE` with
+`GetActive() == false`, or when a `wxEVT_MOTION` arrives during the gesture while
+`!wxGetMouseState().LeftIsDown()`.
+
+### Modal dialogs, popups and destruction while captured
+
+- "you shouldn't show a modal dialog from a mouse click event handler as this would break the mouse
+  capture state" (`interface/wx/event.h:490-499`). The overview adds that a modal shown while
+  captured "won't receive any mouse input and appear unresponsive"
+  (`docs/doxygen/overviews/eventhandling.h:878-901`). Release your own capture, then
+  `CallAfter([…]{ dlg.ShowModal(); })`. The same applies to events a capturing control emits mid-drag
+  (sash moves, list selection), and to `wxPopupTransientWindow::Popup()`, which takes capture itself on
+  macOS (see `references/popups-menus.md`).
+- `Destroy()` or `delete` of a capturing window leaves a dangling stack entry (`~wxWindowBase`
+  never removes it), and on macOS a dangling `s_captureWindow`. `Hide()` leaves the hidden window
+  holding capture; on macOS every click then goes to it. Release first.
+- Moving a top-level window from a custom title bar: prefer the window manager's drag over capture.
+  `BBLTopbar::OnMouseLeftDown` (`BBLTopbar.cpp`) posts `WM_NCLBUTTONDOWN`/`HTCAPTION` on MSW after a
+  `CaptureMouse(); ReleaseMouse();` pair and calls `gtk_window_begin_move_drag` on GTK. Its fallback
+  branch (capture, then `Move()` the frame from `OnMouseMotion`) never runs, because `MainFrame`
+  creates `BBLTopbar` only off macOS (`#ifndef __APPLE__` in the `MainFrame` ctor).
+
+### macOS rerouting and the frozen-UI diagnosis
+
+[source] `wxNSWindow`/`wxNSPanel` `sendEvent:` calls `WX_filterSendEvent:` first
+(`src/osx/cocoa/nonownedwnd.mm:141-165`, called at :188 and :293). While `wxWindow::GetCapture()` is
+non-null, every NSEvent of type `NSLeftMouseDown` … `NSMouseExited` goes straight to the capture
+window's `wxWidgetCocoaImpl::DoHandleMouseEvent`, and `[super sendEvent:]` never runs. That covers
+left/right down/up, moved, left/right dragged, entered and exited (types 1–9), on any wx window. AppKit
+does no hit-testing at all, not even for the title-bar buttons. Scroll-wheel and other-button
+(middle) events are not rerouted. Key events (type ≥ 10) never are.
+
+Symptom of a leaked capture: the app repaints, logs and runs timers, but no click works anywhere,
+including the window's own traffic-light buttons and any modal dialog. The keyboard still works:
+Cmd+S and Cmd+Q still save and quit, so nothing needs to be force-killed. The capture is permanent,
+because nothing on macOS unwinds the stack.
+
+Diagnosis: run `sample <pid> 3` while moving the mouse over the window.
+`WX_filterSendEvent:` → `wxWidgetCocoaImpl::DoHandleMouseEvent` on the main thread is the proof,
+because that path is only reachable while a capture is held. Otherwise the main thread idles in
+`mach_msg` with all threads clean, so do not hunt for a deadlock. Then audit every `CaptureMouse()`
+site:
+- the capture is guarded by `HasCapture()`;
+- it is released whenever held, never behind a drag flag something else can clear;
+- the window has a lost handler, plus macOS stand-ins where gestures can be interrupted;
+- the window releases before hide/destroy and in its destructor.
+
+Typical causes: an unguarded capture pushed twice (a second button, or a re-entered DOWN path);
+a dialog opened mid-press; a stack-allocated dialog or popup destroyed while a child holds capture.
+
+### OrcaSlicer
+
+- `Button`, `DropDown` and `StepCtrl` in `Widgets/` capture in their own mouse handlers and declare
+  `EVT_MOUSE_CAPTURE_LOST` in their event tables, but their lost handlers share the
+  route-through-mouse-up shape the Pitfalls below call wrong; follow the cancel pattern above, not
+  them.
+- `GLCanvas3D` guards every capture with `has_mouse_capture()` and releases in
+  `GLCanvas3D::mouse_up_cleanup()` (`if (m_canvas->HasCapture())`). `GLCanvas3D` is not a
+  `wxEvtHandler`: it binds on `m_canvas` in `bind_event_handlers()` and must unbind in
+  `unbind_event_handlers()`.
+
+### Pitfalls
+
+- **Rule:** Guard both calls.
+  **Why:** An unguarded `ReleaseMouse()` drops whichever window holds the native capture, then
+  silently skips the stack bookkeeping. An unguarded `CaptureMouse()` in a second DOWN branch pushes
+  the window twice, and the single release restores it: a leak, which on macOS is the frozen UI.
+  ```cpp
+  // Wrong:
+  void up(wxMouseEvent&)   { ReleaseMouse(); }
+  void down(wxMouseEvent&) { CaptureMouse(); }          // in each of LEFT/RIGHT/MIDDLE_DOWN
+  // Right:
+  void up(wxMouseEvent& e)   { e.Skip(); if (HasCapture()) ReleaseMouse(); }
+  void down(wxMouseEvent& e) { e.Skip(); if (!HasCapture()) CaptureMouse(); }
+  ```
+  Cite: `src/common/wincmn.cpp:3352-3421`.
+- **Rule:** Cancel on capture-lost; never commit.
+  **Why:** A default `wxMouseEvent` is at (0,0) (`src/common/event.cpp:576-581`), which is inside
+  `wxRect({0,0}, GetSize())`. Routing the lost event through mouse-up therefore fires `wxEVT_BUTTON`
+  when capture is lost mid-press (any `wxDialog::ShowModal` on GTK, an external capture change on
+  MSW), and in a list or dropdown it commits the hovered item.
+  ```cpp
+  // Wrong: the lost event runs the commit path
+  void W::mouseCaptureLost(wxMouseCaptureLostEvent&) { wxMouseEvent e; mouseReleased(e); }
+  // Right:
+  void W::mouseCaptureLost(wxMouseCaptureLostEvent&) { pressedDown = false; Refresh(); }
+  ```
+  Cite: `interface/wx/window.h:3814-3817`.
+- **Rule:** Never `Skip()` in a lost handler.
+  **Why:** The event then counts as unprocessed, which is the case wx asserts on in debug builds
+  (`src/common/wincmn.cpp:3423-3436`).
+- **Rule:** Never assume the lost handler will run.
+  **Why:** macOS never sends it. The `HasCapture()` guards and the up handler carry the whole release
+  logic there.
+
+## Mouse events
+
+### Coordinates
+
+The position is in client coordinates "of the window which generated the event". Convert with
+`ClientToScreen()` and then the other window's `ScreenToClient()` (`interface/wx/event.h:2782-2786`). While a window holds
+capture, positions are relative to the capturing window and can be negative or outside its client
+rectangle. On macOS they are converted from the event's NSWindow (`src/osx/cocoa/window.mm`
+`wxSetupCoordinates`). `GetLogicalPosition(dc)` applies the DC's device origin, e.g. scrolling
+(`interface/wx/event.h:3003`). A `wxGLCanvas` works in physical pixels, so `GLCanvas3D::on_mouse`
+multiplies by the retina scale under `ENABLE_RETINA_GL`; see `references/webview-gl-aui-media.md`.
+
+### Enter and leave
+
+"the mouse is considered to be inside the window if it is over the window and not inside one of its
+children … the parent window receives wxEVT_LEAVE_WINDOW event not only when the mouse leaves the
+window entirely but also when it enters one of its children" (`interface/wx/event.h:2776-2780`).
+Per port [source]:
+- **MSW:** ENTER is synthesized on the first `WM_MOUSEMOVE`, so a click can arrive with no prior
+  ENTER; LEAVE comes from `TrackMouseEvent` (`src/msw/window.cpp:6019-6074`). Orca's
+  `GLCanvas3D::on_mouse` handles this as "Workaround for SPE-832" (`on_enter_workaround`): on MSW, a
+  non-enter event while the cached position is invalid is treated as the enter.
+- **GTK:** crossing events with a grab/ungrab mode are ignored; outside capture wx re-derives the
+  window under the pointer on each motion (`src/gtk/window.cpp:2073-2117, 2384-2456`; fixes #24339
+  and #24931–#24933 are in this release, `docs/changes.txt:537, 547`).
+- **macOS:** each view's `NSTrackingArea` uses `NSTrackingInVisibleRect`
+  (`src/osx/cocoa/window.mm:3924`) and covers its children, so do not rely on the parent getting
+  LEAVE when the pointer moves onto a child. `NSMouseMoved` is delivered only to the deepest view
+  under the pointer (`src/osx/cocoa/window.mm:1508-1517`).
+
+A composite's hover state must therefore track its children. Orca's `StateHandler`
+(`Widgets/StateHandler.cpp`, `StateHandler::attach_child`) keeps per-child state for this; see
+`references/painting-custom-widgets.md`. Inside a `wxPopupTransientWindow` on macOS, Orca's
+`PopupWindow` (created with `wxPU_CONTAINS_CONTROLS`) synthesizes ENTER/LEAVE itself; re-check geometry there
+(`references/popups-menus.md` §6).
+
+### Button state and clicks
+
+- `LeftDown()` means "this event is the press"; `LeftIsDown()` means "the button is held now"; "if
+  wxMouseEvent::LeftDown returns true, wxMouseEvent::LeftIsDown will also"
+  (`interface/wx/event.h:2788-2799`). `Dragging()` is MOTION with any button down
+  (`include/wx/event.h:1850-1853`).
+- **macOS:** button flags are filled only for Down/Dragged NSEvents (`mouseChord`,
+  `src/osx/cocoa/window.mm:645-700`). ENTER/LEAVE, plain motion, UP and wheel events report every
+  button as up. Use `wxGetMouseState()`, which reads `[NSEvent pressedMouseButtons]`
+  (`src/osx/cocoa/utils.mm` `wxGetMouseState`). `GLCanvas3D::on_mouse` back-fills the event from
+  `wxGetMouseState()` only when the event carries no button, "to preserve wx's synthetic right button
+  for Ctrl+left".
+- **macOS Ctrl+click is a right click:** button 0 with `NSControlKeyMask` becomes the right button for
+  the whole down/drag/up sequence (`src/osx/cocoa/window.mm:664-686`; documented as an emulation hint at
+  `interface/wx/event.h:2772-2774`). `RawControlDown()` stays true on that `wxEVT_RIGHT_DOWN`, so a
+  `GetModifiers() == wxMOD_NONE` test fails on it.
+- `wxEVT_LEFT_DOWN` handlers "should normally call event.Skip() … otherwise the window under mouse
+  wouldn't get the focus" (`interface/wx/event.h:2803-2805`). `Skip()` on a by-value copy is lost,
+  because dispatch checks the original event (`src/common/event.cpp:1459-1477`; see
+  `references/events.md`).
+- **Double click:** on every port the second press arrives as `wxEVT_LEFT_DCLICK` **instead of**
+  `wxEVT_LEFT_DOWN`, giving DOWN, UP, DCLICK, UP. MSW maps `WM_LBUTTONDBLCLK` (window classes use
+  `CS_DBLCLKS`, `src/msw/app.cpp:584`). GTK drops the surplus press before `GDK_2BUTTON_PRESS`
+  (`src/gtk/window.cpp:1798-1817`), and GTK2 also suppresses triple clicks (`:1818-1829`). On wxOSX the
+  third press of a triple click is a DOWN again, as on MSW (`src/osx/cocoa/window.mm:4105-4140`;
+  #25886, `docs/changes.txt:316`). `GetClickCount()` is "implemented only in wxMac and returns -1
+  for the other platforms" (`interface/wx/event.h:2965-2974`).
+- **Context menu:** "under MSW the context menu event is generated after EVT_RIGHT_UP … but under
+  GTK … after EVT_RIGHT_DOWN", so a window handling `wxEVT_CONTEXT_MENU` must not handle (or must
+  `Skip()`) both right-button DOWN and UP (`interface/wx/event.h:3306-3312`).
+
+### Wheel
+
+`GetWheelDelta()` is "normally 120", and "you shouldn't assume that one event is equal to 1 line"
+(`interface/wx/event.h:3020-3055`). [source]:
+
+| Port | `GetWheelDelta()` | `GetWheelRotation()` |
+|---|---|---|
+| MSW | `WHEEL_DELTA` | raw (`src/msw/window.cpp:6117-6118`) |
+| GTK3 | 120 | `120 × delta` from `GDK_SCROLL_SMOOTH`, fractional streams (`src/gtk/window.cpp:2177, 2207-2241`) |
+| GTK2 | 120 | ±120 per notch |
+| macOS | **10** | precise scrolling deltas from trackpads; non-precise wheels ×10 (`src/osx/cocoa/window.mm:800-850`) |
+
+A diagonal trackpad scroll on macOS sends two events, vertical first, then one with
+`GetWheelAxis() == wxMOUSE_WHEEL_HORIZONTAL`. GTK3 smooth scrolling splits it too, horizontal first
+(`src/gtk/window.cpp:2207-2241`).
+
+### Pitfalls
+
+- **Rule:** Take mouse events by reference.
+  **Why:** `Skip()` on a copy does not reach the dispatcher, so the event counts as handled; focus
+  and default processing stop.
+  ```cpp
+  // Wrong:
+  w->Bind(wxEVT_LEFT_DOWN, [](wxMouseEvent e) { /*...*/ e.Skip(); });
+  // Right:
+  w->Bind(wxEVT_LEFT_DOWN, [](wxMouseEvent& e) { /*...*/ e.Skip(); });
+  ```
+- **Rule:** Bind DCLICK wherever presses are counted (spin arrows, steppers, toggles).
+  **Why:** every second press of a fast pair is a DCLICK; a DOWN-only handler loses it.
+  Cite: `Widgets/SpinInput.cpp` `SpinInput::createButton`.
+- **Rule:** Don't use `evt.LeftIsDown()` in LEAVE, plain MOTION or UP handlers on macOS.
+  **Why:** the flags are only filled for Down/Dragged NSEvents.
+  ```cpp
+  // Wrong:  if (evt.Leaving() && evt.LeftIsDown()) keep_drag();
+  // Right:  if (evt.Leaving() && wxGetMouseState().LeftIsDown()) keep_drag();
+  ```
+- **Rule:** Normalise wheel steps.
+  **Why:** the macOS delta is 10, and GTK3/trackpads send fractional streams. Dividing by a
+  hard-coded 120 makes a macOS wheel notch (rotation 10) 12× too slow; a fixed step per event races
+  or jitters on trackpad streams.
+  ```cpp
+  // Wrong:
+  zoom += evt.GetWheelRotation() / 120.0;   // or: rot > 0 ? step : -step per event
+  // Right:
+  if (evt.GetWheelAxis() != wxMOUSE_WHEEL_VERTICAL) return evt.Skip();
+  m_acc += double(evt.GetWheelRotation()) / evt.GetWheelDelta();
+  while (std::abs(m_acc) >= 1.0) { step(m_acc > 0 ? 1 : -1); m_acc -= (m_acc > 0 ? 1 : -1); }
+  ```
+
+## Global pointer position and Wayland
+
+| API | Contract | GTK on Wayland [source] |
+|---|---|---|
+| `wxGetMousePosition()` | screen coordinates (`interface/wx/utils.h:360-365`) | `gdk_device_get_position` with no Wayland handling (`src/gtk/window.cpp:7026-7042`). Wayland exposes no global pointer position to clients [external]; Orca's comments record (0,0) |
+| `wxGetMouseState()` | position, buttons and modifiers (`interface/wx/utils.h:367-375`) | position unreliable, same path (`src/gtk/window.cpp:2827-2867`) |
+| `ClientToScreen()`, `ScreenToClient()`, `GetScreenRect()` | — | add the top-level window's `gdk_window_get_origin()` (`src/gtk/window.cpp:4630-4698`). Without a global origin the result is only meaningful relative to the same top-level window: fine for deltas and hit tests inside one window, wrong across windows or for absolute placement |
+| `wxFindWindowAtPoint(pt)` | deepest window at a screen point; disabled children count, hidden ones are skipped (`interface/wx/utils.h:385-394`) | built on screen rectangles, so unreliable. On GTK it is `wxGenericFindWindowAtPoint`, a walk over every top-level window and child (`src/gtk/utilsgtk.cpp:98-101`, `src/common/utilscmn.cpp:1294-1345`) |
+| `wxGetKeyState(key)` | "In wxGTK, this function can be only used with modifier keys … when not using X11 backend" (`interface/wx/utils.h:352-358`) | Ctrl/Alt/Shift and Caps/Num/Scroll Lock only; any other key returns false (`src/unix/utilsx11.cpp:2596-2662`) |
+| `WarpPointer()` | Apple's HIG forbids it; on Wayland it works only with a compositor implementing the pointer-warp protocol, and mutter also needs a pressed button (`interface/wx/window.h:3895-3914`; `docs/changes.txt:294`) | — |
+| `wxUIActionSimulator` | "doesn't work when using Wayland" (`interface/wx/uiaction.h:20`) | — |
+| `PopupMenu(x, y)` | — | GTK ≥ 3.22 positions it relative to the window (`gtk_menu_popup_at_rect`, `src/gtk/window.cpp:6520-6565`), so it is safe |
+
+On wxOSX `WarpPointer` synthesizes a `wxEVT_MOTION` to the window (`src/osx/window_osx.cpp:1370-1398`),
+so warping from a motion handler recurses. On GTK2, pointer queries and warps go straight to X11.
+
+**OrcaSlicer.** Detect the backend with `Slic3r::GUI::is_running_on_wayland()` / `is_running_on_x11()`
+(`LinuxDisplayBackend.hpp`), never with environment variables (`references/platforms.md`). Models:
+- `SearchDialog` (`Search.cpp`) dismisses by focus on Wayland (`focus_left_popup`) instead of
+  comparing `wxGetMousePosition()` with its screen rectangle.
+- `BBLTopbar::FindToolByCurrentPosition` (`BBLTopbar.cpp`) uses the last event position and returns
+  null on Wayland rather than query the global pointer.
+- `BBLTopbar::OnMouseMotion` and `Button::OnParentMotion` use `ClientToScreen(event.GetPosition())`
+  within one window ("wxGetMousePosition() … returns (0,0) on Wayland").
+
+### Pitfalls
+
+- **Rule:** On Linux, never rely on global screen coordinates.
+  **Why:** wx delegates straight to GDK and does not compensate on Wayland, so hit tests against
+  `wxGetMousePosition()` silently fail or misfire.
+  ```cpp
+  // Wrong:
+  if (!GetScreenRect().Contains(wxGetMousePosition())) Dismiss();
+  if (wxFindWindowAtPoint(wxGetMousePosition()) != this) /* ... */;
+  // Right: event-relative, same window (convert through the event's GetEventObject() window)
+  if (!GetClientRect().Contains(evt.GetPosition())) Dismiss();
+  // or, for popups and dialogs, focus tracking (focus_left_popup is file-local to Search.cpp):
+  if (focus_left_popup(this, wxWindow::FindFocus(), related)) Dismiss();
+  ```
+- **Rule:** Track held keys with KEY_DOWN/KEY_UP, not `wxGetKeyState(letter)`.
+  **Why:** it is always false for letters on Wayland, so held-key and repeat detection built on it
+  (including pruning a held-key record with it) breaks there. Clear such a record from KEY_UP.
+
+## Hover handlers and enter/leave feedback loops
+
+**Rule.** In `wxEVT_ENTER_WINDOW`/`wxEVT_LEAVE_WINDOW` handlers, only record hover state, per child
+window, because enter and leave fire per window. Apply `Show()`/`Hide()` + `Layout()` from
+`wxEVT_IDLE` or `CallAfter`, and only when the desired state differs from the current one.
+`Skip()` the events.
+
+**Why.** A layout change inside the handler moves windows under the pointer, which re-fires
+enter/leave. On Wayland compositors that keep hidden-workspace surfaces mapped (Hyprland), GTK
+delivers a stream of synthetic leave events, and a handler that re-layouts pegs a CPU core
+(69e16cd7ef). The fix that moved show/hide out of the handlers removed the freeze caused by the
+dynamically hidden printer edit button (e87625e023). Two wx facts block the obvious guards:
+- `wxFindWindowAtPoint()` is a full window-tree walk on GTK and unreliable on Wayland (table above).
+- `IsShownOnScreen()` is not a visibility test on any platform. It only checks `IsShown()` up the
+  parent chain (`src/common/wincmn.cpp:1205-1212`, `interface/wx/window.h:3101-3102`), plus "surface
+  exists" for `wxGLCanvas` on Unix. It never reflects minimised, occluded or other-workspace state,
+  which is why `Plater::priv::set_current_panel` says "wxWidgets IsShownOnScreen() is buggy and
+  cannot be used reliably".
+
+**OrcaSlicer.** The Sidebar printer, nozzle and bed panels (`Plater.cpp`, `Sidebar` ctor) follow
+this design:
+- each child's ENTER/LEAVE lambda inserts or erases the window in a per-group
+  `std::shared_ptr<std::unordered_set<wxWindow*>>` (e.g. `printer_preset_hovered`) and sets the border
+  colour;
+- a `wxEVT_IDLE` handler compares `!hovered->empty()` with `btn_edit_printer->IsShown()` and calls
+  `Show()`/`Hide()` + `Layout()` only on a difference (keep such a handler a cheap comparison: it runs on every
+  idle pass, hidden panels included, `references/events.md` §12);
+- clicking the edit button clears the set inside `CallAfter`, because opening the preset tab sends
+  no LEAVE (ff4147ede3), and because hiding a button from inside its own event handler crashed on
+  wxGTK.
+
+```cpp
+// Wrong: walks the tree and re-layouts inside the event (feedback loop)
+w->Bind(wxEVT_LEAVE_WINDOW, [=](wxMouseEvent& e) {
+    if (!hit(wxFindWindowAtPoint(wxGetMousePosition()))) { btn->Hide(); panel->Layout(); }
+    e.Skip(); });
+// Right: record, then apply once from idle
+w->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) { hovered->insert(w); e.Skip(); });
+w->Bind(wxEVT_LEAVE_WINDOW, [=](wxMouseEvent& e) { hovered->erase(w);  e.Skip(); });
+Bind(wxEVT_IDLE, [=](wxIdleEvent& e) {
+    if (btn->IsShown() != !hovered->empty()) { btn->Show(!hovered->empty()); panel->Layout(); }
+    e.Skip(); });
+```
+Cite: 69e16cd7ef, e87625e023, ff4147ede3 (`Plater.cpp`).
+
+## Keyboard events
+
+### Event order per port
+
+[source] One key press, in order:
+
+| Port | Sequence |
+|---|---|
+| MSW | thread keyboard hook `wxKeyboardHook` → `wxEVT_CHAR_HOOK` to the focus window (or the active window) — skipped while any native `::GetCapture()` exists or a non-wx modal (IME) is open; with IME open a handled hook does not stop the key reaching the IME (`src/msw/window.cpp:7320-7395`) → `wxGUIEventLoop::PreProcessMessage`: accelerator walk from the focus up to the first `IsTopNavigationDomain(Navigation_Accel)` window, with the text-entry exemption (`src/msw/evtloop.cpp:62-119`) → `IsDialogMessage`, which is never given `VK_ESCAPE` (`src/msw/window.cpp:2769-2778`) → `wxEVT_KEY_DOWN` → `wxEVT_CHAR` |
+| GTK | `wxEVT_CHAR_HOOK`, skipped while `g_captureWindow` is set → accelerator walk to the top-level window, no text-entry exemption → `wxEVT_KEY_DOWN` → input method → `wxEVT_CHAR` (`src/gtk/window.cpp:1266-1420`) |
+| macOS | the main menu's `performKeyEquivalent:`: a menu-bar key equivalent consumes the key before wx sees it (`src/osx/cocoa/window.mm:1611-1644`) → `wxEVT_CHAR_HOOK`, also during capture → accelerator walk, only if no `wxEVT_CHAR_HOOK` handler processed the event (`src/osx/window_osx.cpp:2547-2590`) → Tab navigation by the first `wxTAB_TRAVERSAL` ancestor unless the window has `wxWANTS_CHARS` (`src/osx/cocoa/window.mm:4009-4046`) → `interpretKeyEvents` (IME) → `wxEVT_KEY_DOWN` → `wxEVT_CHAR` (`:4048-4101`). A disabled window gets no key events (`:1616-1617`) |
+
+### wxEVT_CHAR_HOOK
+
+Contract (`interface/wx/event.h:1487-1508`): "Unlike all the other key events, this event is
+propagated upwards the window hierarchy … generated before any other key events". If a handler
+processes it without `Skip()`, "neither wxEVT_KEY_DOWN nor wxEVT_CHAR events will be generated
+(although wxEVT_KEY_UP still will be)". `DoAllowNextEvent()` handles it and still lets normal events
+through (`:1683-1702`). It "is not generated when the mouse is captured". [source] Exceptions and
+details:
+- **macOS** has no capture check, so the hook fires during drags.
+- **wxGTK** reads the allow flag from the original event rather than the hook event, so
+  `DoAllowNextEvent()` has no effect there (`src/gtk/window.cpp:1266-1282`).
+- Propagation stops only at windows with `wxWS_EX_BLOCK_EVENTS` (`src/common/wincmn.cpp:3498-3522`).
+  `wxDialog` sets it (`src/common/dlgcmn.cpp:127`), and so does `wxPopupWindow` on MSW and macOS
+  (`wxPopupWindowBase::Create`, `src/common/popupcmn.cpp:135`). wxGTK's `wxPopupWindow::Create`
+  never calls the base, so a GTK popup does not block (`src/gtk/popupwin.cpp`). Frames do not
+  either: keys typed in a modeless frame (or a GTK popup) parented to `MainFrame` reach
+  `MainFrame`'s hook.
+
+`wxEVT_KEY_DOWN`/`wxEVT_CHAR` are not command events and do not propagate
+(`docs/doxygen/overviews/eventhandling.h:536-544`). If `wxEVT_KEY_DOWN` is handled without `Skip()`, "the
+corresponding char event … will not happen … Not doing may also prevent accelerators defined using
+this key from working" (`interface/wx/event.h:1456-1463`).
+
+**OrcaSlicer — dialog keys.** `DPIAware<wxDialog>` (`GUI_Utils.hpp`) binds `wxEVT_CHAR_HOOK`: Esc
+calls `Close()`, everything else is skipped. A dialog that needs Esc or Enter itself binds its own
+hook. Later `Bind`s run first (`docs/doxygen/overviews/eventhandling.h:474-482`), so the dialog's
+hook runs before `DPIAware`'s. Orca's `::Button` is not a `wxButton`, so wx's default-button and
+Esc emulation (`EmulateButtonClickIfPresent`) never finds it. Dialogs synthesize the click instead,
+as the `CloneDialog` ctor does for Enter in its count field:
+```cpp
+Bind(wxEVT_CHAR_HOOK, [this, ok_btn](wxKeyEvent& e) {
+    const int key = e.GetKeyCode();
+    if ((key == WXK_RETURN || key == WXK_NUMPAD_ENTER) && m_count_spin->GetTextCtrl()->HasFocus()) {
+        wxCommandEvent evt(wxEVT_BUTTON, ok_btn->GetId());
+        ok_btn->GetEventHandler()->ProcessEvent(evt);
+    } else
+        e.Skip();
+});
+```
+The full Esc/close path is in `references/windows-dialogs.md`.
+
+### Key codes
+
+- Use `GetUnicodeKey()` for printable characters and `GetKeyCode()` for `WXK_*` specials
+  (`interface/wx/event.h:1329-1346`).
+- `wxEVT_KEY_DOWN`/`UP`: ASCII letters are their upper-case code; other Latin-1 characters (`ù`,
+  `ö`, `²`) are the character itself, not upper-cased; keys producing non-Latin printable characters
+  report "the ASCII code of the character the same key would produce in the standard US keyboard
+  layout"; specials are their `WXK_*` (`:1371-1394`). A Cyrillic `ц` gives `'W'`, so Ctrl+letter
+  shortcuts work across layouts, but an AZERTY key reports its own label (`$` where US has `]`), so
+  `Ctrl-;`-style punctuation accelerators may be untypeable on some layouts (`:1396-1407`). wxGTK
+  got the non-Latin mapping in 3.3.0 (#23379, `docs/changes.txt:540`).
+- `wxEVT_CHAR` reflects Shift and the layout. Ctrl+letter gives 1..26 (`WXK_CONTROL_A` …,
+  `:1409-1421`). Exception: on macOS Cmd+letter's CHAR is the letter itself (`'a'`/`'A'`); only the
+  physical Control key yields 1..26 (`src/osx/cocoa/window.mm:304-307`).
+- Documented inconsistencies: Ctrl-Backspace, Ctrl-Enter, and on GTK no CHAR for Ctrl + a letter
+  mapped to a non-Latin one (`:1423-1433`). Modifier keys generate no CHAR (`:1435`).
+- `IsAutoRepeat()` is `@onlyfor{wxosx,wxmsw,wxQt}`, not GTK (`:1595-1601`).
+
+`KeyChord::from_event` (`KeyChord.cpp`) normalises all of this: it up-cases letters, folds numpad
+keys onto the main keyboard, maps CHAR control codes 1..26 back to letters, and drops Shift from
+CHAR punctuation, because the character already reflects it. Use it rather than testing raw codes.
+
+### Modifiers and the Cmd mapping
+
+| Query | MSW / GTK | macOS |
+|---|---|---|
+| `ControlDown()`, `wxMOD_CONTROL`, `wxACCEL_CTRL`, `"Ctrl+"` in accelerator strings | Ctrl | **Cmd** |
+| `RawControlDown()`, `wxMOD_RAW_CONTROL`, `WXK_RAW_CONTROL`, `wxACCEL_RAW_CTRL`, `"RawCtrl+"` | Ctrl (same value as the above) | the physical Control key (a distinct bit) |
+| `CmdDown()`, `wxMOD_CMD`, `wxACCEL_CMD` | deprecated aliases of `ControlDown()`/`wxMOD_CONTROL`/`wxACCEL_CTRL` | same |
+
+Sources: `interface/wx/kbdstate.h:38-130`, `interface/wx/accel.h:15-30`, `include/wx/defs.h:2372-2388`,
+`include/wx/accel.h:29-41`.
+`interface/wx/kbdstate.h:45` claims `wxMOD_CMD` is `wxMOD_META` on Mac; the code defines `wxMOD_CMD = wxMOD_CONTROL`
+everywhere [source]. Prefer `GetModifiers() == wxMOD_CONTROL`: `ControlDown()` alone is also true for
+Ctrl+Shift, and for AltGr, which reports as Ctrl+Alt (`interface/wx/kbdstate.h:38-70`).
+
+### wxWANTS_CHARS and navigation
+
+- `wxWANTS_CHARS`: the window "get[s] all char/key events for all keys — even for keys like TAB or
+  ENTER"; call `Navigate()` yourself for Tab (`interface/wx/window.h:225-232`). On macOS wx's Tab
+  navigation is skipped for such windows, and otherwise Tab is consumed by the first
+  `wxTAB_TRAVERSAL` ancestor before `wxEVT_KEY_DOWN` (`src/osx/cocoa/window.mm:4009-4046`). The GL
+  canvas is created with it (`OpenGLManager::create_wxglcanvas`), so Tab and arrows arrive.
+  `GLCanvas3D::on_key` does not `Skip()` Tab and arrows and skips everything else "to have EVT_CHAR
+  generated".
+- `wxTAB_TRAVERSAL` "should almost never be used in the application code"
+  (`interface/wx/window.h:221-224`). A composite with focusable children derives from
+  `wxNavigationEnabled<Base>` (`interface/wx/containr.h:10-46`).
+- `Navigate(flags)` "is equivalent to calling NavigateIn() method on the parent"
+  (`interface/wx/window.h:2968-2988`). `HandleAsNavigationKey(evt)` (`:2715-2724`) and
+  `MoveAfterInTabOrder`/`MoveBeforeInTabOrder` (`:2949-2966`) complete the set.
+- `DisableFocusFromKeyboard()` removes a window from the Tab chain but keeps click focus
+  (`interface/wx/window.h:497-506`). `SpinInput`'s arrow buttons use it.
+
+**OrcaSlicer — `::Button`.** `Button::keyDownUp` turns Space/Return into LEFT_DOWN/UP and passes Tab
+and arrows to `HandleAsNavigationKey`. The synthesized LEFT_DOWN runs `Button::mouseDown`, so a held
+Space/Return holds the mouse capture until its KEY_UP reaches the button. On MSW
+`Button::MSWWindowProc` answers `WM_GETDLGCODE` with `DLGC_WANTMESSAGE`.
+
+### Pitfalls
+
+- **Rule:** Catch children's keys with `wxEVT_CHAR_HOOK` on the parent.
+  ```cpp
+  // Wrong: never sees keys typed in child controls
+  panel->Bind(wxEVT_KEY_DOWN, &P::on_key, this);
+  // Right:
+  panel->Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) { if (!handle(e)) e.Skip(); });
+  ```
+- **Rule:** A top-level hook lets text-editing keys through to a focused text entry.
+  **Why:** the hook runs before the text control and before MSW's text-entry accelerator
+  exemption. Eating bare printable keys, Space, Ctrl+C/V/X/A/Z, Delete, Home/End or arrows breaks
+  them in every field of the window.
+  ```cpp
+  // Wrong:
+  Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) { if (e.GetKeyCode() == WXK_DELETE) delete_selection(); else e.Skip(); });
+  // Right:
+  Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) {
+      if (e.GetKeyCode() == WXK_DELETE && !dynamic_cast<wxTextEntryBase*>(wxWindow::FindFocus())) delete_selection();
+      else e.Skip(); });
+  ```
+  Cite: `MainFrame.cpp` `focus_keeps_space` (text entries, `wxWebView`, `::Button`, `StaticBox`
+  composites and `wxControl`s keep Space).
+- **Rule:** Don't expect hook-based shortcuts during a drag on MSW/GTK, and guard drag state on
+  macOS, where they do fire.
+- **Rule:** Ctrl+letter in `wxEVT_CHAR` is a control code.
+  ```cpp
+  // Wrong:  if (e.GetEventType() == wxEVT_CHAR && e.ControlDown() && e.GetKeyCode() == 'a')
+  // Right:  if (KeyChord::from_event(e) == KeyChord{'A', wxMOD_CONTROL})   // or match on KEY_DOWN
+  ```
+- **Rule:** Modifier tests are exact.
+  ```cpp
+  // Wrong:  if (e.ControlDown() && e.GetKeyCode() == 'C')      // also AltGr+C, Ctrl+Shift+C
+  // Right:  if (e.GetModifiers() == wxMOD_CONTROL && e.GetKeyCode() == 'C')
+  ```
+
+## Accelerators and menu shortcuts
+
+### Contract
+
+- "An accelerator takes precedence over normal processing" (`interface/wx/accel.h:178`), but it
+  runs after `wxEVT_CHAR_HOOK` on every port (table above).
+- [source] On GTK and macOS a hit is sent as `wxEVT_MENU` with the entry's id and, if unprocessed,
+  retried as `wxEVT_BUTTON`; macOS treats the key as consumed either way
+  (`src/gtk/window.cpp:1340-1366`, `src/osx/window_osx.cpp:2563-2590`). On MSW the `WM_COMMAND` goes to
+  a child window with that id if one exists (a `wxButton` clicks), otherwise it becomes `wxEVT_MENU`
+  (`src/msw/window.cpp` `wxWindowMSW::HandleCommand`).
+- Matching up-cases a–z (`src/generic/accel.cpp:86-88`, `src/osx/accel.cpp:59`) and needs an
+  **exact** modifier match (`src/generic/accel.cpp:155-180`; `src/osx/accel.cpp:69-84`, which also
+  matches RawCtrl). Ctrl+Shift+Z needs its own entry.
+- `SetAcceleratorTable()` **replaces** the window's single table; nothing merges. The walk runs from
+  the focused window up to the top-level window, so a table works only while focus is inside its
+  window, and a dialog never sees its parent frame's table [source].
+- Menu strings take `"Label\tCtrl+X"`: modifiers `CTRL`/`RAWCTRL`/`ALT`/`SHIFT` joined by `+` or `-`,
+  plus the special key names listed in `interface/wx/menuitem.h:469-555`.
+  `wxAcceleratorEntry::FromString` accepts the bare accelerator or the legacy `"Label\tAccel"`.
+  `ToRawString()` is untranslated, for config files (`interface/wx/accel.h:124-146`).
+  `AddExtraAccel` is `@onlyfor{wxmsw,wxgtk}` (`interface/wx/menuitem.h:643-647`).
+
+### Platforms
+
+- **Menu accelerators exist only for menus attached to a frame's `wxMenuBar`** [source]. MSW merges
+  them in `wxMenuBar::RebuildAccelTable` (`src/msw/menu.cpp:1264-1292`); GTK adds the menu's accel
+  group to the top-level window in `AttachToFrame` (`src/gtk/menu.cpp:239-247`). A menu shown with
+  `PopupMenu` treats `"\tCtrl+X"` as display text.
+- **MSW:** accelerators are not translated while a `wxTextCtrl`/`wxComboBox`/`wxSpinCtrl` has focus and
+  the key is a text-editing key: Ctrl+A/C/V/X/Ins/Del/Home/End/Left/Right, Shift+those navigation
+  keys, bare Del/Home/End, Alt+Backspace (`src/msw/textentry.cpp:1073-1150`). Multi-line controls also
+  keep Enter (`src/msw/textctrl.cpp:2110-2135`).
+- **GTK:** the accelerator walk has no such exemption (`src/gtk/window.cpp:1340-1366`). As menu
+  accelerators, Shift with non-alphabetic keys does not work, bare arrow keys do not work, and the
+  listed keys (Tab, the modifiers, locks …) are unsupported (`interface/wx/menuitem.h:562-575`).
+- **macOS:** menu-bar items become `NSMenuItem` key equivalents
+  (`src/osx/cocoa/menuitem.mm` `wxMacCocoaMenuItemSetAccelerator`). They run before any wx key event,
+  including while a text field has focus. A menu-bar accelerator on a printable key without a
+  modifier, or on a text-editing chord such as Cmd+C, takes that key from typing.
+
+### OrcaSlicer menus
+
+The native `wxMenuBar` exists only on macOS (`MainFrame::init_menubar_as_editor`, Preferences under
+`OSXGetAppleMenu()`). On Windows and Linux the same `wxMenu`s hang off `BBLTopbar`
+(`GetTopMenu()`, `SetFileMenu`, `AddDropDownSubMenu`), so their labels are display-only and the keys
+are dispatched by the registry (`MainFrame`'s hook, the canvases). Add shortcut-bearing items with
+`MainFrame::append_shortcut_item(menu, Shortcut::X, accelerator, label, …)`:
+- `accelerator == true` and the binding is menu-safe (`ShortcutRegistry::accelerator()` is non-empty,
+  i.e. `KeyChord::is_menu_accelerator()`): the label is `label + "\t" + accel`, a live key equivalent
+  on macOS.
+- Otherwise the binding is appended as text. The separator is `" - "` on Apple, so the macOS menu bar
+  does not take it as a key equivalent, and `"\t"` elsewhere (`MainFrame::shortcut_label`). The source
+  comment cites #8152: the macOS menu bar "handles the key accelerators automatically and breaks key
+  handling in normal typing". The macOS Edit menu shows clipboard and undo this way, so that Cmd+C in
+  a text field copies text rather than objects.
+- `MainFrame::update_shortcut_labels()` rewrites every tracked item after a rebinding
+  (`GUI_App::on_shortcuts_changed`).
+
+On Apple `MainFrame`'s hook keeps Cmd+H (consumed; the app menu hides), Cmd+M (`Iconize()`), Cmd+Q
+(posts `wxEVT_CLOSE_WINDOW`) and Cmd+Ctrl+F (`EnableFullScreenView(true)` + `ShowFullScreen`
+toggle). Preferences (Cmd+, / Ctrl+P) is a Global registry shortcut.
+
+### Pitfalls
+
+- **Rule:** One table per window, built once from all entries.
+  ```cpp
+  // Wrong: the second call discards the first table
+  SetAcceleratorTable(wxAcceleratorTable(1, &copy));  SetAcceleratorTable(wxAcceleratorTable(1, &paste));
+  // Right:
+  wxAcceleratorEntry e[] = { copy, paste };  SetAcceleratorTable(wxAcceleratorTable(2, e));
+  ```
+- **Rule:** Don't expect `MainFrame`'s keys inside a dialog: each top-level window needs its own
+  handling (dialogs block `wxEVT_CHAR_HOOK` propagation and the accelerator walk stops at them).
+
+## Orca's shortcut registry
+
+The registry is the one table every key dispatcher, menu label, tooltip and the shortcuts dialog
+reads; the design is in `docs/HLSD/keyboard-shortcuts.md`.
+
+**Data model.**
+- `KeyChord` (`KeyChord.hpp`) is `{key, modifiers}`: the key as `wxEVT_KEY_DOWN` reports it, plus
+  `wxMOD_*` limited to CONTROL|SHIFT|ALT|RAW_CONTROL. Its canonical text (`to_string()`, e.g.
+  `Ctrl+Shift+S`) is platform-neutral and doubles as the wx accelerator string and the config format.
+  `display()` uses translated modifier names and the macOS glyphs. Predicates:
+  - `needs_char_event()`: a printable non-alphanumeric key with at most Shift, resolvable only from
+    the CHAR that follows.
+  - `is_punctuation()`: such a key with no modifier.
+  - `is_menu_accelerator()`: Ctrl, Alt or RawCtrl held, or a non-printable key other than Space.
+  - `is_system_shortcut()`: Alt+F4 and Alt+Space on Windows.
+  - `to_accelerator_entry()` maps RawCtrl to `wxACCEL_RAW_CTRL` on Apple.
+- `Shortcut` (enum) and `shortcut_table` (`Shortcuts.cpp`): each row, written with
+  `SHORTCUT`/`REPEATING`/`STEPPING`, holds a config key, description, context mask, default chord, and
+  the `repeatable`/`modifier_variants` flags. `static_assert`s keep the table in enum order and
+  `section_table` ascending.
+- `ShortcutRegistry` (`wxGetApp().shortcuts()`) overlays user overrides from the AppConfig section
+  `shortcuts`; only overrides are stored, and `none` records an unbound shortcut.
+  `ShortcutRegistry::load()` drops a Global override that fails `is_menu_accelerator()` ("A Global
+  chord is seen before any text field").
+- Lookups: `lookup(context, chord)` matches exactly. `match()` falls back to `modifier_variants`
+  shortcuts with Shift/Ctrl added, which are reserved steps (`step_owner()`). `conflicts()` treats
+  Global as sharing every context.
+
+**Contexts and dispatch.**
+
+| Context | Dispatcher | Event |
+|---|---|---|
+| `Global` | `MainFrame::handle_global_shortcut`, from `MainFrame`'s `wxEVT_CHAR_HOOK`, before the focused child gets KEY_DOWN/CHAR (a child's own CHAR_HOOK handler still runs first); `Skip()` otherwise | CHAR_HOOK |
+| `Plater`, `Preview` | `GLCanvas3D::handle_shortcut` (→ `ShortcutRegistry::match`) from `GLCanvas3D::on_key`; punctuation retried from `GLCanvas3D::on_char` | KEY_DOWN, CHAR |
+| `ObjectList` | `ObjectList::dispatch_shortcut`, from `ObjectList::key_event` on CHAR (non-macOS); on macOS from a `wxAcceleratorTable` built by `ObjectList::update_shortcut_accelerators()` (ids from `wxWindow::NewControlId`), because the native data view delivers no keys there | CHAR / accelerator |
+| `Painting` | a painting gizmo's `on_tool_shortcut` (`GLGizmosManager`) | KEY_DOWN |
+
+- A Global chord needs Ctrl/Alt or a non-typing key, because it is seen before any text field. Space
+  counts as typing: the speed dial's bare-Space default is skipped when `focus_keeps_space(FindFocus())`.
+- Shortcuts in other contexts may share a chord when their contexts do not overlap.
+- The macOS ObjectList table is swapped to `wxNullAcceleratorTable` while a name is being edited and
+  restored in `ObjectList::OnEditingDone`.
+- wxGTK reports no auto-repeat, so the canvases keep one shared record of keys seen going down
+  (`key_repeats`/`key_released`) and swallow repeats of non-`repeatable` shortcuts.
+
+**Adding a shortcut.**
+1. Add the `Shortcut` value and its row in `shortcut_table`, in dialog order (a new section also needs a
+   `section_table` entry). Pick a default that does not collide inside its contexts; the `[Shortcuts]`
+   tests check every default.
+2. Handle it in the context's dispatcher: `MainFrame::handle_global_shortcut`,
+   `GLCanvas3D::handle_shortcut`, `ObjectList::dispatch_shortcut`, or a gizmo's `on_tool_shortcut`. A
+   gizmo opened by a key sets `m_shortcut` in its `on_init()` (e.g. `GLGizmoMove3D::on_init`).
+3. Where the UI shows the key, ask the registry: `display()` for tooltips, `accelerator()` (via
+   `append_shortcut_item`) for menus. Never write a literal key name.
+
+`KBShortcutsDialog::fill_pages` lists registry entries automatically. Only non-rebindable keys and
+mouse actions are added there by hand (`fixed(...)`, `mouse(...)`). Edits go through
+`GUI_App::on_shortcuts_changed()`, which saves and pushes to menus, canvas tooltips and the macOS
+ObjectList table.
+
+**Model for capturing raw chords:** `ShortcutCaptureDialog` (`KBShortcutsDialog.cpp`).
+- A `wxWANTS_CHARS` `StaticBox` keeps focus, so the buttons never get the keys; focus is set by
+  `capture->CallAfter(... SetFocus())` after construction.
+- `wxEVT_CHAR_HOOK` on the dialog handles Esc/Enter, records KEY_DOWN chords and `Skip()`s
+  `needs_char_event()` chords.
+- A `wxEVT_CHAR` handler on the box records punctuation.
+- Its comment notes that the hook runs before the window procedure, so Windows does not open its
+  window menu on Alt+Space.
+
+```cpp
+// Wrong: ad-hoc key test plus a hand-written label
+if (evt.GetKeyCode() == 'E' && evt.ControlDown()) export_gcode();
+append_menu_item(menu, wxID_ANY, _L("Export") + "\tCtrl+E", ...);
+// Right: registry row + dispatcher case + registry-derived label
+case Shortcut::ExportSlicedFile: if (can_export_gcode()) wxPostEvent(m_plater, SimpleEvent(EVT_GLTOOLBAR_EXPORT_SLICED_FILE)); return false;
+append_shortcut_item(export_menu, Shortcut::ExportSlicedFile, true, _L("Export plate sliced file") + dots, ...);
+```
+
+## Focus
+
+### Contract
+
+- `SetFocus()` "sets the window to receive keyboard input" (`interface/wx/window.h:567-572`).
+  `FindFocus()` is static (`:4274-4283`). `HasFocus()` also covers a composite's main child
+  (`:529-536`).
+- `AcceptsFocus()` returning false means the control "doesn't accept input at all" (`:472-480`).
+  `AcceptsFocusFromKeyboard()` controls Tab-chain membership (`:482-488`). `CanAcceptFocus()` is
+  `AcceptsFocusRecursively() && IsShown() && IsEnabled()` (`include/wx/window.h:751-766`).
+- `SetCanFocus()` "is only implemented by ports which have support for native TAB traversal … A call
+  to this does not disable or change the effect of programmatically calling SetFocus()"
+  (`interface/wx/window.h:538-548`).
+- Focus handlers "should almost invariably call wxEvent::Skip() … wxEVT_KILL_FOCUS handler must not
+  call wxWindow::SetFocus()" (`interface/wx/event.h:3405-3416`). The event's `GetWindow()` "may be
+  NULL" (`:3438-3445`). `wxEVT_CHILD_FOCUS` derives from `wxCommandEvent` and propagates, and its
+  window is the *direct* child (`:3453-3491`).
+- `wxPanel::SetFocus` focuses the first child if "the control has at least one child";
+  `SetFocusIgnoringChildren()` focuses the panel itself (`interface/wx/panel.h:125-142`).
+- `wxGetActiveWindow()` "always returns NULL in the other ports", i.e. on everything but MSW and GTK
+  (`interface/wx/window.h:4545-4551`).
+
+### Platforms
+
+[source]
+- **GTK:** `SetFocus()` calls `gtk_window_present()` on a visible, inactive top-level window, i.e. it
+  **raises and activates** the window (`src/gtk/window.cpp:5137-5162`). On a not-yet-shown widget the
+  focus becomes "pending", and `FindFocus()` returns the pending window at once (`:5141-5155,
+  2777-2791`). While a popup menu is open, `FindFocus()` returns the invoking window.
+- **MSW:** disabling the focused control first `Navigate()`s forward (`src/msw/window.cpp`
+  `MSWEnableHWND`). Any `WM_SETFOCUS`, `WM_KILLFOCUS` or button-down in a window outside
+  `wxCurrentPopupWindow` dismisses a transient popup that lacks `wxPU_CONTAINS_CONTROLS`
+  (`src/msw/window.cpp:3018-3033` → `MSWDismissUnfocusedPopup`, `src/msw/popupwin.cpp:218-229`).
+- **Modeless windows:** focus requested right after `Show()` can be dropped while activation is still
+  in flight (Orca comment in `SpeedDialWebDialog`'s ctor). Set it from `CallAfter` or on
+  `wxEVT_ACTIVATE` (`SpeedDialWebDialog`'s activate handler, see `references/popups-menus.md`); the
+  modal `ShortcutCaptureDialog` likewise defers its first `SetFocus()` with `CallAfter`.
+
+### OrcaSlicer
+
+- `::Button` overrides `SetCanFocus` to store `canFocus`, which drives `Button::AcceptsFocus()` and
+  whether `Button::mouseDown` calls `SetFocus()`. In Orca `SetCanFocus(false)` therefore means "never
+  take focus", unlike the stock GTK-only hint.
+- `GLCanvas3D::on_mouse` focuses the canvas on any button-down. On ENTER it focuses the canvas only if
+  the top-level window `IsActive()` and focus is not in a `wxTextCtrl`, and on MSW only while
+  `wxCurrentPopupWindow` is null. Stealing focus would trigger `MSWDismissUnfocusedPopup` and close
+  the search dropdown.
+
+### Pitfalls
+
+- **Rule:** No unconditional `SetFocus()` on hover, ENTER or timers.
+  **Why:** on GTK it raises and activates the window over whatever the user is doing; on MSW it
+  dismisses open transient popups; anywhere it steals the caret from a text field.
+  ```cpp
+  // Wrong:
+  canvas->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) { canvas->SetFocus(); e.Skip(); });
+  // Right (wxCurrentPopupWindow is in no wx header: declare
+  //        extern wxPopupWindow* wxCurrentPopupWindow; as GLCanvas3D.cpp does):
+  canvas->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) {
+      auto* tlw = dynamic_cast<wxTopLevelWindow*>(wxGetTopLevelParent(canvas));
+      if (tlw && tlw->IsActive() && !dynamic_cast<wxTextCtrl*>(wxWindow::FindFocus())
+  #ifdef __WXMSW__
+          && !wxCurrentPopupWindow
+  #endif
+      ) canvas->SetFocus();
+      e.Skip(); });
+  ```
+  Cite: `GLCanvas3D::on_mouse`.
+- **Rule:** Defer focus changes out of `wxEVT_KILL_FOCUS`, and always `Skip()` focus events.
+  ```cpp
+  // Wrong:  ctrl->Bind(wxEVT_KILL_FOCUS, [=](wxFocusEvent&) { other->SetFocus(); });
+  // Right:  ctrl->Bind(wxEVT_KILL_FOCUS, [=](wxFocusEvent& e) { e.Skip(); other->CallAfter([other] { other->SetFocus(); }); });
+  ```
+
+## Tooltips
+
+### Contract
+
+- `SetToolTip(const wxString&)`, `SetToolTip(wxToolTip*)` and `UnsetToolTip()`
+  (`interface/wx/window.h:3238-3273`). Setting an **empty string does not remove** the tooltip; the
+  code says "use SetToolTip(nullptr)" (`src/common/wincmn.cpp:2245-2259`) [source].
+- The string overload reaches the virtual `DoSetToolTipText`; the pointer overload and `UnsetToolTip`
+  reach `DoSetToolTip` (`include/wx/window.h:1484-1489`).
+- Statics (`interface/wx/tooltip.h:26-85`): `Enable` "may not be supported on all platforms";
+  `SetAutoPop`/`SetReshow` "May not be supported (eg. wxCocoa, GTK)"; `SetMaxWidth` is wxMSW-only.
+- `wxTipWindow::New()` (3.3.2) returns a `wxTipWindow::Ref` that becomes null when the tip closes
+  itself; never keep a raw pointer (`interface/wx/tipwin.h:20-110`).
+- `wxRichToolTip` is not a window: each `ShowFor()` creates a new one, and the native MSW version
+  only applies to text controls (`interface/wx/richtooltip.h:70-192`).
+
+| Static [source] | MSW | GTK | macOS |
+|---|---|---|---|
+| `Enable` | works | sets `GtkSettings` `gtk-enable-tooltips` | no-op |
+| `SetDelay` | works | sets `gtk-tooltip-timeout` (`src/gtk/tooltip.cpp:74-128`) | writes `NSInitialToolTipDelay` into `[NSUserDefaults standardUserDefaults]`, the app's persistent defaults (`src/osx/cocoa/tooltip.mm:66-72`) |
+| `SetAutoPop`, `SetReshow` | work; Orca's `MainFrame` ctor uses `SetAutoPop(32767)` because larger values fail | no-op | no-op |
+
+### Tooltips on disabled controls
+
+MSW tooltips subclass the tool's HWND (`TTF_SUBCLASS`, `src/msw/tooltip.cpp:131-135`), and a
+disabled HWND receives no mouse messages [external], so a disabled control shows no tooltip.
+`Button::EnableTooltipEvenDisabled()` (`Widgets/Button.cpp`) works around this:
+- it binds the **parent's** `wxEVT_MOTION`/`wxEVT_LEAVE_WINDOW` (`Button::OnParentMotion`/
+  `Button::OnParentLeave`);
+- it pops a `wxTipWindow::Ref` when the pointer is over the disabled button;
+- it positions the tip from `ClientToScreen(wxPoint(0, 0))` rather than `wxGetMousePosition()`, which
+  returns (0,0) on Wayland;
+- it is compiled only under `#if defined(_MSC_VER) || defined(_WIN32)`.
+
+- **Rule:** Install parent-window mouse-tracking handlers that simulate tooltips on disabled controls
+  only on Windows; gate them with `#if defined(_WIN32)`.
+  **Why:** the hack froze the UI on macOS. The commit records only the symptom. Likely mechanism
+  [source]: `wxTipWindow` is a `wxPopupTransientWindow`. On wxOSX its `Show(true)` captures the mouse
+  on its child without a guard, and `OnIdle` keeps capture while the pointer is outside the popup
+  (`src/common/popupcmn.cpp:335-430, 439-471`). A tip popped from parent MOTION, beside the pointer,
+  therefore takes every click (see the macOS capture section), and a re-`Popup()` while shown
+  pushes the capture twice.
+  ```cpp
+  // Wrong: unconditional
+  parent->Bind(wxEVT_MOTION, &Button::OnParentMotion, this);
+  // Right:
+  #if defined(_MSC_VER) || defined(_WIN32)
+  parent->Bind(wxEVT_MOTION, &Button::OnParentMotion, this);
+  parent->Bind(wxEVT_LEAVE_WINDOW, &Button::OnParentLeave, this);
+  #endif
+  ```
+  Cite: d0cc4b35ee (`Widgets/Button.cpp` `Button::EnableTooltipEvenDisabled`).
+
+### OrcaSlicer
+
+- `TextInput`, `SpinInput` and `TempInput` override `DoSetToolTipText` to forward the text to the
+  inner `wxTextCtrl`. Only the string overload forwards; `UnsetToolTip()` and
+  `SetToolTip(wxToolTip*)` do not reach the inner control.
+- `Sidebar::priv::show_rich_tip` (`Plater.cpp`, `_WIN32` only) uses `wxRichToolTip` and recolours
+  the shown popup's first child for dark mode.
+- Option tooltips for settings are assembled by the `Field` machinery (`references/orca-settings-ui.md`).
+
+### Pitfalls
+
+- **Rule:** `UnsetToolTip()` to clear.
+  ```cpp
+  // Wrong:  btn->SetToolTip("");      // keeps an empty tooltip object
+  // Right:  btn->UnsetToolTip();
+  ```
+- **Rule:** A composite forwarding tooltips overrides both virtuals, so `UnsetToolTip()` and the
+  `wxToolTip*` overload reach the inner children.
+- **Rule:** Don't call `wxToolTip::SetDelay` on macOS casually: it persists in the user's defaults for
+  the app.
+
+## Cursors
+
+### Contract
+
+- `SetCursor(c)` "also sets it for the children of the window implicitly"; `wxNullCursor` resets it to
+  the default (`interface/wx/window.h:3866-3882`). The system shows the window cursor whenever the
+  pointer is over the window, so set it **once**.
+- For high DPI, use `SetCursorBundle()` (3.3.0) (`interface/wx/window.h:3884-3892`). A default `wxCursorBundle()` is
+  empty and means "no custom cursor", not a blank cursor (`interface/wx/cursor.h:305-317`).
+- `wxSetCursor(bundle)` "Globally sets the cursor … overrides any cursor set for the individual
+  windows … until this function is called again with an empty cursor bundle"
+  (`interface/wx/gdicmn.h:1371-1389`). `wxSetCursor(wxNullCursor)` is that reset, through the implicit
+  `wxCursorBundle(const wxCursor&)` (`src/common/curbndl.cpp:174`) [source].
+- `wxBusyCursor` is RAII around the nested `wxBeginBusyCursor`/`wxEndBusyCursor` counter, with
+  `wxIsBusy()` (`interface/wx/busycursor.h`). These are main-thread GUI calls.
+- `wxBitmap(wxCursor)` is invalid on GTK/Wayland (`interface/wx/bitmap.h:393-395`).
+
+### OrcaSlicer
+
+- Dialog work uses `wxBusyCursor` RAII (e.g. `PhysicalPrinterDialog.cpp`).
+- Jobs wrap their `process()` in `BusyCursored<Job>` (`Jobs/BusyCursorJob.hpp`). Its
+  `CursorSetterRAII` marshals `wxBeginBusyCursor`/`wxEndBusyCursor` to the main thread through
+  `ctl.call_on_main_thread`.
+- Web dialogs bracket blocking work with `wxSetCursor(wxCURSOR_ARROWWAIT)` …
+  `wxSetCursor(wxNullCursor)` (`WebViewDialog.cpp`).
+
+### Pitfalls
+
+- **Rule:** Set the hover cursor once and reset with `wxNullCursor`.
+  **Why:** the system already switches cursors on enter/leave. Toggling by hand fights it, and an
+  explicit `wxCURSOR_ARROW` overrides the cursor inherited from the parent.
+  ```cpp
+  // Wrong:
+  w->Bind(wxEVT_ENTER_WINDOW, [w](wxMouseEvent& e) { w->SetCursor(wxCURSOR_HAND);  e.Skip(); });
+  w->Bind(wxEVT_LEAVE_WINDOW, [w](wxMouseEvent& e) { w->SetCursor(wxCURSOR_ARROW); e.Skip(); });
+  // Right:
+  w->SetCursor(wxCURSOR_HAND);          // once; w->SetCursor(wxNullCursor) to drop it
+  ```
+- **Rule:** Busy cursors from worker threads go through the main thread
+  (`ctl.call_on_main_thread`, `CallAfter`); never call `wxBeginBusyCursor` from a worker.

.claude/skills/orca-wxwidgets/references/orca-architecture.md

@@ -0,0 +1,948 @@
+# OrcaSlicer GUI architecture
+
+The map of OrcaSlicer's GUI: which object owns what, how the app starts, rebuilds and shuts down,
+how pages are built lazily, and where a new dialog, panel, sidebar control, setting, notification,
+menu item or source file belongs. Read it before adding a component or when code has to reach
+another part of the GUI; the API detail of each area lives in the file the section points to.
+
+Contents: [The stack](#the-stack-orcas-gui-is-built-on) ·
+[Component map](#component-map) · [GUI_App](#gui_app) ·
+[Close and shutdown](#close-and-shutdown-sequence) · [MainFrame](#mainframe) ·
+[Deferred construction](#deferred-construction-lazy-lazypage-stagedbuild-idlescheduler) ·
+[Plater and Sidebar](#plater-and-sidebar) · [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs) ·
+[ObjectList](#objectlist) · [3D canvas and ImGui](#3d-canvas-imgui-layer-and-notificationmanager) ·
+[Background work](#background-work) · [Device pages](#device-and-monitor-pages) ·
+[Web UI](#web-based-ui) · [Preferences](#preferences) · [AppConfig](#appconfig) ·
+[Where new code goes](#where-new-code-goes) · [Build registration](#build-registration) ·
+[Design docs](#design-docs-docshlsd)
+
+## Rules
+
+1. Reach app-wide objects through `wxGetApp()`. `app_config` is non-null for the whole GUI
+   lifetime; `plater()` and `mainframe` can be null, and `sidebar()`, `obj_list()`, `model()`
+   dereference the plater unchecked — test `plater()` first on any path that can run before the
+   main frame exists or after it closes. → [Accessors](#accessors)
+2. Deferred code (CallAfter bodies, agent callbacks, timers) that can run during shutdown checks
+   `!wxTheApp || wxGetApp().is_closing()` before touching the GUI. → [Close and shutdown](#close-and-shutdown-sequence)
+3. Never keep a raw pointer to a `MainFrame` child, a `Tab`, a lazy panel or a cached dialog across
+   `GUI_App::recreate_GUI` (language switch); `is_closing()` stays false during it. → [recreate_GUI](#recreate_gui-language-switch)
+4. A new top-level tab is a `LazyPage<Panel>` with a `LazyInstance<Panel>` panel; a heavy dialog
+   owned by the main frame is a `Lazy<Dlg>` member. Only the start page and the Prepare plater are
+   built before the first frame. → [Deferred construction](#deferred-construction-lazy-lazypage-stagedbuild-idlescheduler)
+5. Outside `MainFrame`, reach a lazy object only through its statics: `if_built()` for work it can
+   live without, `ensure()` only to show or navigate to it, `when_built()` for state it would not
+   pull for itself (and for rescale/recolour of staged panels). → [Reaching a lazy object](#reaching-a-lazy-object)
+6. In a `StagedBuild` panel, step-built members start null; timers, handlers and the destructor
+   check `built()` first; nothing takes focus while off screen. → [Staged construction](#staged-construction-stagedbuild)
+7. Background UI construction is a prebuild task run by `IdleScheduler`, never a `wxEVT_IDLE` +
+   `RequestMore()` loop or a chain of posted events. → [The idle scheduler](#the-idle-scheduler-idlescheduler-prebuildqueue)
+8. A component with Orca rescale / recolour hooks must be reached by the explicit fan-out
+   (`MainFrame::on_dpi_changed` / `on_sys_color_changed`, `Plater::msw_rescale` /
+   `sys_color_changed`, `Sidebar::msw_rescale` / `sys_color_changed`); nothing calls it otherwise. → [DPI and colour fan-out](#dpi-and-colour-fan-out)
+9. Process and model-scope settings are in `ParamsPanel` inside the sidebar; filament and printer
+   settings are in the modeless `ParamsDialog`. `get_tab()` returns null until the tab is complete. → [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs)
+10. `Plater` and `Sidebar` are pimpl'd: new state goes into `Plater::priv` / `Sidebar::priv`. New
+    events are declared next to their emitter with the `Event.hpp` types; a short-lived listener on
+    the plater binds through `EventGuard`. → [Plater and Sidebar](#plater-and-sidebar)
+11. Docked panes go through `Plater::add_dock_pane` with a stable, untranslated, delimiter-free name;
+    the window must be a child of the plater. → [Docking](#docking)
+12. UI drawn over the 3D view is ImGui inside `GLCanvas3D`, never a wx child window over the GL
+    canvas; ask for a redraw with `set_as_dirty()` / `request_extra_frame()`. → [3D canvas](#3d-canvas-imgui-layer-and-notificationmanager)
+13. `NotificationManager` is called on the UI thread only, and its notifications are visible only
+    while the plater is shown. → [NotificationManager](#notificationmanager)
+14. UI-initiated background work is a `Job` on a `Worker`; slicing is `BackgroundSlicingProcess`;
+    network agents call back through `wxGetApp().CallAfter`. UI is touched only on the main thread. → [Background work](#background-work)
+15. Device UI pulls state from `DeviceManager` on its own timer and mutates `MachineObject` only on
+    the UI thread. → [Device pages](#device-and-monitor-pages)
+16. Web UI goes through Orca's hosts (`WebView::CreateWebView`, `WebViewHostDialog`, `WebPanel`,
+    `DockPanel`); window operations requested from a script message are deferred and liveness-checked. → [Web UI](#web-based-ui)
+17. A preference is a `create_item_*` row in `PreferencesDialog::create_items` that writes
+    `app_config` and saves at once; its default goes in `AppConfig::set_defaults`; effects needed
+    after the dialog closes go in `GUI_App::open_preferences`. → [Preferences](#preferences)
+18. `AppConfig` values are strings: match the key's own convention (`"true"/"false"` or `"1"/"0"`);
+    `save()` and every write run on the main thread. → [AppConfig](#appconfig)
+19. Every new source file is registered in `src/slic3r/CMakeLists.txt`: `SLIC3R_GUI_SOURCES`, or the
+    `if (WIN32)` / `if (APPLE)` / `if (SLIC3R_CAD)` blocks, or the `GUI/DeviceCore` / `GUI/DeviceTab`
+    lists. → [Build registration](#build-registration)
+20. A new subsystem whose design is not evident from the code gets `docs/HLSD/<subsystem>.md`; a
+    change that invalidates an existing HLSD doc updates it in the same PR. → [Design docs](#design-docs-docshlsd)
+
+## The stack Orca's GUI is built on
+
+- **wxWidgets 3.3.2, SoftFever fork.** `deps/wxWidgets/wxWidgets.cmake` fetches
+  `https://github.com/SoftFever/Orca-deps-wxWidgets` at tag `v3.3.2` and builds it static
+  (`-DwxBUILD_SHARED=OFF`); Flatpak builds build it shared. Linux builds against **GTK3** by default
+  (`option(DEP_WX_GTK3 "Build wxWidgets against GTK3" ON)` in `deps/CMakeLists.txt`, `SLIC3R_GTK`
+  default `"3"`, Flatpak uses gtk3). GTK2 exists only as an opt-out (`-DDEP_WX_GTK3=OFF`) and loses
+  EGL, WebKit2 and DIP pixels. Code guarded for GTK should still compile on GTK2, but GTK3 under X11
+  and Wayland is the target. Toolkit and build-option detail: `references/platforms.md`.
+- **Asserts are compiled out.** wx is built with `-DwxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` adds
+  `wxDEBUG_LEVEL=0` (under `SLIC3R_STATIC`, `src/slic3r/CMakeLists.txt`). `wxASSERT`/`wxFAIL` vanish
+  and `wxCHECK*` return silently, so API misuse shows up as wrong pixels, dropped calls or corrupted
+  state, never as an assert dialog.
+- **No wx SVG.** `-DwxUSE_NANOSVG=OFF`: `wxBitmapBundle::FromSVG*` does not exist; Orca rasterises
+  SVG itself (`BitmapCache`, `create_scaled_bitmap`) — `references/dpi-bitmaps-fonts.md`.
+- **Orca's own widget library.** New UI code largely does not use raw wx controls: the owner-drawn
+  widgets in `src/slic3r/GUI/Widgets/` (`Button`, `CheckBox`, `ComboBox`, `TextInput`, `SpinInput`,
+  `SwitchButton`, `RadioGroup`, `Label`, `DialogButtons`, …) replace them. Reasons: native controls
+  cannot follow Orca's look or its app-level dark-mode toggle; on Windows wx's native dark mode does
+  not reach anything built on `TaskDialog()` (`wxMessageBox`, `wxMessageDialog`, `wxRichMessageDialog`,
+  `wxProgressDialog`) nor the wrapped common dialogs (`wxColourDialog`, `wxFontDialog`, …)
+  (`interface/wx/app.h:1434-1443`), so Orca shows the `MsgDialog` family and its own generic
+  `Widgets/ProgressDialog` instead; and on GTK the theme's borders bleed through wrapped native
+  controls (the widgets call `RemoveButtonBorder` / `RemoveInputBorder` under `__WXGTK__`).
+  Plain containers stay raw (`wxPanel`, `wxBoxSizer`, `wxScrolledWindow`).
+- **Namespaces.** Most widgets are in the global namespace; a few (`DialogButtons`, `HyperLink`,
+  `ProgressDialog`, `RadioBox`, `WebViewHostDialog`, the AMS/device composites) are in
+  `Slic3r::GUI`. GUI code inside `Slic3r::GUI` writes `::CheckBox` because `Field.hpp` declares the
+  settings-field classes `Slic3r::GUI::CheckBox`, `TextCtrl`, `SpinCtrl`, `Choice`, `StaticText`,
+  which an unqualified name finds first once `Field.hpp` is reachable; `::TextInput` and
+  `::ComboBox` are qualified the same way by convention (no `Slic3r::GUI` class shadows them).
+  Catalog and quirks: `references/orca-widgets.md`.
+
+## Component map
+
+| Component | Type, file | Owns / does | Reach it with |
+|---|---|---|---|
+| `GUI_App` | `wxApp`; `GUI/GUI_App.hpp/.cpp` | process singletons, startup, `post_init`, app idle handler, dark-mode entry points, `recreate_GUI` | `wxGetApp()` |
+| `MainFrame` | `DPIFrame`; `GUI/MainFrame.hpp/.cpp` | borderless main window, top bar / menu bar, tab book, preset tabs, idle prebuild, DPI/colour fan-out | `wxGetApp().mainframe` |
+| `Plater` | `wxPanel`, pimpl `Plater::priv`; `GUI/Plater.hpp/.cpp` | the Prepare and Preview page: model, three canvases, AUI docking, slicing, job worker, notifications, context menus | `wxGetApp().plater()` |
+| `Sidebar` | `wxPanel`, pimpl `Sidebar::priv`; `GUI/Plater.hpp/.cpp` | printer and filament blocks, `ParamsPanel`, object search + `ObjectList`, settings index | `wxGetApp().sidebar()` (unchecked) / `plater()->sidebar()` |
+| `ParamsPanel` | `wxPanel`; `GUI/ParamsPanel.hpp` | process and model-scope `Tab`s, reparented into the sidebar | `wxGetApp().params_panel()` (null-safe) |
+| `ParamsDialog` | `DPIDialog`; `GUI/ParamsDialog.hpp` | its own `ParamsPanel` with the filament and printer `Tab`s; modeless | `wxGetApp().params_dialog()` (null-safe) |
+| `Tab` family | `GUI/Tab.hpp/.cpp` | preset editors (`TabPrint`, `TabPrintPlate/Object/Part/Layer`, `TabFilament`, `TabPrinter`) | `get_tab(Preset::Type)`, `get_plate_tab()`, `get_model_tab(part)`, `get_layer_tab()` |
+| `ObjectList` | `wxDataViewCtrl`; `GUI/GUI_ObjectList.hpp` | plate/object/part tree | `wxGetApp().obj_list()` (unchecked) |
+| `GLCanvas3D` | wraps a `wxGLCanvas`; `GUI/GLCanvas3D.hpp` | 3D, preview and assemble rendering, gizmos, ImGui overlays | `plater()->canvas3D()`, `get_current_canvas3D()` |
+| `NotificationManager` | `GUI/NotificationManager.hpp` | ImGui notifications drawn in the canvas | `wxGetApp().notification_manager()` (null-safe) |
+| Jobs | `GUI/Jobs/` | UI-initiated background tasks | `plater()->get_ui_job_worker()` |
+| `MonitorPanel` / `StatusPanel` | `GUI/Monitor.hpp`, `GUI/StatusPanel.hpp` | Device tab | `MonitorPanel::if_built()` / `ensure()` |
+| `DeviceManager` / `MachineObject` | `GUI/DeviceCore/DevManager.h` (`DeviceManager`), `GUI/DeviceManager.hpp` (`MachineObject`), parts in `GUI/DeviceCore/Dev*` | device state | `wxGetApp().getDeviceManager()` |
+| `NetworkAgent` | `Utils/NetworkAgent.hpp` | printer agent + cloud agents façade | `wxGetApp().getAgent()` |
+| Web hosts | `Widgets/WebView`, `Widgets/WebViewHostDialog`, `WebViewDialog.hpp` (`WebViewPanel`), `PrinterWebView`, `WebPanel`, `DockPanel`, `WebDialog` | HTML UI | per class |
+| `PreferencesDialog` | `DPIDialog`; `GUI/Preferences.hpp` | app settings | `wxGetApp().open_preferences(tab, highlight)` |
+| `AppConfig` | `libslic3r/AppConfig.hpp` | persisted app settings | `wxGetApp().app_config` |
+| `PresetBundle` | `libslic3r/PresetBundle.hpp` | presets | `wxGetApp().preset_bundle` |
+| `ShortcutRegistry` | `GUI/Shortcuts.hpp` | key bindings | `wxGetApp().shortcuts()` |
+| `ActionRegistry` | `GUI/ActionRegistry.hpp` | Speed Dial actions | `wxGetApp().action_registry()` |
+| `ImGuiWrapper` | `GUI/ImGuiWrapper.hpp` | the app's ImGui context | `wxGetApp().imgui()` |
+
+## GUI_App
+
+### Entry and construction
+
+`GUI_Run` (`GUI/GUI_Init.cpp`) creates the app by hand: `new GUI_App()`, then
+`Slic3r::instance_check(argc, argv, single_instance)` using `app_config`, then
+`GUI_App::SetInstance(gui)`, `gui->init_params = &params`, and `wxEntry`. When there are command-line
+arguments it passes **only `argv[0]`** to `wxEntry`, because wx reports errors for some file names; the real
+arguments travel in `GUI_App::init_params` (`GUI_InitParams`). `IMPLEMENT_APP(GUI_App)` is in
+`GUI_App.cpp` and `DECLARE_APP(GUI_App)` in `GUI_App.hpp` inside `Slic3r::GUI`, so `wxGetApp()` is
+`Slic3r::GUI::wxGetApp()` — write `GUI::wxGetApp()` from `Slic3r` scope outside `GUI`. It expands to
+`*static_cast<GUI_App*>(wxApp::GetInstance())` (`include/wx/app.h:941` **[source]**), so it is valid from
+`SetInstance` until wx cleanup nulls the instance.
+
+The constructor (`GUI_App::GUI_App`) runs before `wxEntry`, i.e. before wx is initialised. It creates
+the `ImGuiWrapper`, `RemovableDriveManager`, `Downloader`, `OtherInstanceMessageHandler`, then calls
+`init_app_config()` early (instance checking needs it) and loads the `ShortcutRegistry` from it.
+Nothing that needs a running wx (timers, windows, modal prompts, WebView runtime checks) may go in
+the constructor; those belong in `on_init_inner` or `post_init`.
+
+### Startup sequence
+
+`GUI_App::OnInit` wraps `on_init_inner()` in a try/catch (`generic_exception_handle`, then a `return false`
+that is never reached because the handler terminates or rethrows — `references/threads-timers-app.md` §Startup).
+The order inside `on_init_inner` that contributors depend on:
+
+1. Log target, `::Label::initSysFont()` (the `Label::Head_*/Body_*` font table every widget uses),
+   wxInspector plugin registration, `wxInitAllImageHandlers()`, GTK menu-image and log-filter tweaks.
+2. `wxEVT_QUERY_END_SESSION` bound on the app: it sends the main frame a vetoable `wxCloseEvent`
+   (so the save prompts run), vetoes the session end if that close was vetoed, then calls
+   `EndModal(wxID_ABORT)` on every dialog in the global `dialogStack`.
+3. `init_label_colours()`, `init_fonts()`, `Update_dark_mode_flag()`; the editor's TLS
+   certificate prompt.
+4. `load_language()` — language, colour mode and fonts must be initialised before the first UI
+   action; the app exits if loading the language fails.
+5. Dark-mode initialisation (non-Windows writes `dark_color_mode` from the system appearance;
+   Windows calls `MSWEnableDarkMode(DarkMode_Auto)` before `NppDarkMode::InitDarkMode`) —
+   `references/colours-dark-mode.md`.
+6. `SplashScreen` (if `show_splash_screen`), held in a `wxWeakRef` and advanced with
+   `SetText(text, progress)` + `wxYield()` — `references/threads-timers-app.md`.
+7. `new PresetBundle`, `new PresetUpdater` and their event bindings; plugin GUI wiring
+   (`init_plugin_gui_wiring`); networking (`on_init_network`).
+8. GTK with EGL: `wxGLCanvas::PreferGLX()` on X11, before any GL canvas exists —
+   `references/webview-gl-aui-media.md`.
+9. `mainframe = new MainFrame()` (creates the plater, the tab book, the preset tabs and the lazy
+   pages), then `select_tab(TAB_ID_PREPARE or TAB_ID_HOME)` per `starts_on_prepare()`
+   (`default_page == "1"`).
+10. `obj_list()->init()`, `SetTopWindow(mainframe)`, `plater_->init_notification_manager()`,
+    `load_current_presets()`, `mainframe->Show(true)`; the splash is destroyed; `update_mode()`.
+11. The app-level `wxEVT_IDLE` handler is bound.
+
+### post_init and the app idle handler
+
+The idle handler bound at the end of `on_init_inner` runs `post_init()` exactly once (guarded by
+`m_post_initialized`, and postponed while a WebView script handler is being added), then on every
+idle **saves `app_config` if it is `dirty()`**. `post_init` initialises the WebView2 runtime on
+Windows (`init_webview_runtime`, before the first WebView), opens command-line files, loads the GL
+resources on the Prepare canvas when the app starts on Prepare (when it starts on Home they load
+later as an idle task, so Home paints first), starts the idle prebuild
+(`MainFrame::prebuild_pages_when_idle`), and `CallAfter`s the config wizard and update checks — the
+code comment: on Mac this is "the only way to popup a modal dialog on start without screwing combo
+boxes". If the GL context cannot be made current yet, Linux resets `m_post_initialized` so the next
+idle retries (a Wayland surface commits late).
+
+### Accessors
+
+| Accessor | Null? |
+|---|---|
+| `app_config`, `preset_bundle`, `imgui()`, `shortcuts()`, `action_registry()` | created in the constructor or before `MainFrame`; non-null for the GUI lifetime (`preset_updater` is null in the G-code viewer) |
+| `mainframe`, `plater()` | null before `MainFrame` exists |
+| `sidebar()`, `obj_list()`, `model()` | dereference `plater_` **without a check** |
+| `params_panel()`, `params_dialog()`, `notification_manager()` | null-safe (return null without a main frame / plater) |
+| `get_tab(Preset::Type)` | null for a tab not found **or not yet `completed()`**; `tabs_list` / `model_tabs_list` are cleared by `MainFrame::shutdown` |
+| `get_model_tab(part)`, `get_layer_tab()` | index `model_tabs_list` **without a bounds check** — undefined once `MainFrame::shutdown` has cleared it |
+| `getDeviceManager()`, `getAgent()` | may be null; check before use |
+| `em_unit()` | app-wide; per-window value via the free `em_unit(wxWindow*)` — `references/dpi-bitmaps-fonts.md` |
+| `dark_mode()` | static, recomputed per call — `references/colours-dark-mode.md` |
+| `is_closing()`, `is_recreating_gui()`, `input_idle_ms()` | state flags; `input_idle_ms` is fed by `GUI_App::FilterEvent` |
+
+### recreate_GUI (language switch)
+
+`GUI_App::recreate_GUI` sets `m_is_recreating_gui`, destroys the cached Speed Dial dialog (its
+translated strings are injected once), calls `mainframe->shutdown()`, swaps the `Field` control pools
+(`switch_window_pools()`; the old pools are released only when the old frame is destroyed), creates a
+**new `MainFrame`**, `Destroy()`s the old one, reloads presets, shows the new frame and calls
+`prebuild_pages_when_idle()` again. `GUI_App::shutdown` returns early while recreating, so
+`is_closing()` never becomes true during a language switch.
+
+Consequences: every `MainFrame` child, `Tab`, lazy panel and cached dialog is a new object afterwards.
+The `LazyInstance` statics follow automatically (the new frame's holders replace the old ones); raw
+pointers do not. Settings fields are recycled through pools: `references/orca-settings-ui.md`.
+
+### Pitfalls
+
+- **Rule:** On startup and shutdown paths, test `plater()` before `sidebar()` / `obj_list()` / `model()`.
+  **Why:** those accessors dereference `plater_` unchecked; before `MainFrame` exists they crash.
+  ```cpp
+  // Wrong: reachable before the main frame exists
+  wxGetApp().sidebar().update_presets(Preset::TYPE_PRINTER);
+  // Right
+  if (Plater* plater = wxGetApp().plater())
+      plater->sidebar().update_presets(Preset::TYPE_PRINTER);
+  ```
+  Cite: `GUI_App::sidebar`, `GUI_App::obj_list`, `GUI_App::model`.
+- **Rule:** Do not null-check `app_config` inside the GUI; do keep it on the main thread.
+  **Why:** it is created in the `GUI_App` constructor, before `wxEntry`, so it exists for the whole GUI
+  lifetime; the hazard is threading ([AppConfig](#appconfig)), not null. Cite: `GUI_App::GUI_App`.
+- **Rule:** Do not cache a pointer to a `MainFrame` child or lazy panel in a static or a long-lived
+  object. **Why:** `recreate_GUI` destroys the old frame; the cached pointer dangles and `is_closing()`
+  does not warn you.
+  ```cpp
+  // Wrong
+  static MonitorPanel* s_monitor = MonitorPanel::ensure();
+  // Right: ask each time; the statics follow the new frame's holder
+  if (MonitorPanel* monitor = MonitorPanel::if_built()) monitor->jump_to_HMS();
+  ```
+  Cite: `GUI_App::recreate_GUI`, `LazyInstance` (`Lazy.hpp`).
+
+## Close and shutdown sequence
+
+Orca's side of shutdown, in order:
+
+1. `MainFrame`'s `wxEVT_CLOSE_WINDOW` handler (bound in the constructor) vetoes, when the event can
+   be vetoed, if a gizmo is in editing mode, if `Plater::close_with_confirm` (project and preset save
+   prompts) is cancelled, or if `GUI_App::check_print_host_queue` refuses.
+2. Otherwise: `MarkdownTip::ExitTip()`, `wxGetApp().set_closing(true)` (so queued work is inert during
+   the reset), `m_plater->reset()` (which also saves the AUI perspective to the `window_layout` key),
+   `MainFrame::shutdown()`, `event.Skip()` (wx's default handler then `Destroy()`s the frame, or — for a
+   vetoable close while a modal dialog is open — vetoes it after this teardown, `references/windows-dialogs.md` §2).
+3. `MainFrame::shutdown()`: stops the idle scheduler (`m_idle.stop()`), shuts down the built Project
+   panel and plugin pages, removes dock panes, clears the backup callback, cancels all UI jobs
+   (`get_ui_job_worker().cancel_all()`), unbinds the canvases' handlers (on macOS Cmd+Q delivers a mouse
+   event after the close handler), resets canvas volumes, **hides the frame** (paint messages into
+   dying windows crashed), stops the 3D-mouse controller and saves its config, shuts down the
+   other-instance listener, saves `app_config` if dirty, clears `tabs_list` / `model_tabs_list`, and
+   calls `GUI_App::shutdown()`.
+4. `GUI_App::shutdown()`: removable-drive manager shutdown, login dialog deleted, then (unless
+   recreating the GUI) stop the HTTP server, `set_closing(true)`, plugin manager shutting down,
+   printer agent detached and the agent cache cleared.
+5. wx deletes all remaining top-level windows, then calls `GUI_App::OnExit`, which stops the HTTP server
+   and preset sync, deletes `DeviceManager`, `UserManager` and the network agent.
+
+`m_is_closing` is a `std::atomic<bool>`. There is no drain of queued `CallAfter`s at shutdown: queued
+app calls are discarded with the app object, and those that still run see `is_closing()`. (The bounded
+`drain_pending_events` belongs to `GUI_App::hot_reload_network_plugin`.) The wx side — windows deleted
+before `OnExit` (`interface/wx/app.h:358-371`), `wxTheApp` null in `~GUI_App`, exception policy — is in
+`references/threads-timers-app.md`.
+
+- **Rule:** Guard deferred GUI work with `!wxTheApp || wxGetApp().is_closing()`.
+  **Why:** after wx cleanup `wxGetApp()` dereferences a null instance (`wxEntryCleanup` resets the
+  instance before deleting the app, `src/common/init.cpp:472-487` **[source]**); between the close
+  handler and `OnExit` the plater has been reset and windows are dying.
+  ```cpp
+  // Wrong
+  wxGetApp().CallAfter([this, msg] { handle(msg); });
+  // Right (as ActionRegistry::init)
+  if (!wxTheApp || wxGetApp().is_closing()) return;
+  wxGetApp().CallAfter([this, msg] { if (wxGetApp().is_closing()) return; handle(msg); });
+  ```
+  Cite: `ActionRegistry::init` (plugin source callbacks), `NetworkAgentFactory.cpp`
+  (`reject_conflicting_capability`); `GUI_App::init_networking_callbacks` (`message_arrive_fn`) runs
+  inside `GUI_App`, so it tests its own `is_closing()` before and inside the `CallAfter`.
+- **Rule:** A component that owns a thread, timer, socket or dock pane stops it from
+  `MainFrame::shutdown()` (or its own `shutdown()` called from there), not from its destructor alone.
+  **Why:** by the time destructors run, the frame is hidden and the plater reset; a timer or thread that
+  fires in between touches half-destroyed state. `MainFrame::shutdown` is the one place that runs before
+  any window is deleted, both on exit and on a language switch.
+
+## MainFrame
+
+### Frame, top bar and menu bar
+
+`MainFrame : DPIFrame` uses `BORDERLESS_FRAME_STYLE` (no `wxCAPTION`; no `wxRESIZE_BORDER` on macOS)
+and draws its own title bar. Each platform restores the missing decoration differently (MSW strips
+`WS_CAPTION` and handles non-client messages in `MainFrame::MSWWindowProc`; GTK adds
+`ResizeEdgePanel`s that start a resize drag; macOS `set_miniaturizable` in `Utils/MacDarkMode.mm`) —
+`references/platforms.md`.
+
+Off macOS the title bar is `BBLTopbar` (a `wxAuiToolBar` in the frame's sizer, not an AUI pane) that
+hosts the File menu, the Edit/View/Help drop-down submenus, the Calibration menu and undo/redo. On
+macOS the same menus are attached to a native `wxMenuBar` (`m_menubar`), with Preferences under
+`OSXGetAppleMenu()`. `MainFrame::init_menubar_as_editor` builds the `wxMenu`s once and branches only
+where they are attached; `generate_help_menu` builds Help. Menu mechanics, `append_menu_item`,
+`MenuFactory` and `BBLTopbar` events: `references/popups-menus.md`.
+
+### The tab book
+
+`m_tabpanel` is Orca's `Notebook` (`GUI/Notebook.hpp`, a `wxBookCtrlBase` with a `ButtonsListCtrl`
+header that sends `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED`). Pages are addressed by **string ids**, the
+`TAB_ID_*` macros in `MainFrame.hpp` (`TAB_ID_HOME`, `TAB_ID_DESIGN`, `TAB_ID_PREPARE`,
+`TAB_ID_PREVIEW`, `TAB_ID_MONITOR`, `TAB_ID_MONITOR_WEB`, `TAB_ID_MULTI_DEVICE`, `TAB_ID_PROJECT`,
+`TAB_ID_CALIBRATION`): `AddPage(id, page, text, bmp_name)`, `InsertPage(n, id, …)`,
+`FindPageByName`, `SelectPageByName`, `GetSelectedPageName`, `PositionAfter({ids})`. Use the ids, not
+indices: pages come and go per printer and per feature flag.
+
+- The **same `Plater` window is inserted twice**, as Prepare and Preview (`MainFrame::update_layout`).
+  The page-changed handler posts `EVT_GLVIEWTOOLBAR_3D` / `EVT_GLVIEWTOOLBAR_PREVIEW` to the plater, so
+  "which page" is resolved by id, never by `GetName()` of the window (`MainFrame::select_tab(wxPanel*)`).
+- Every other page is a `LazyPage<…>` created in `MainFrame::init_tabpanel`: Home
+  (`WebViewPanel`), Device (`MonitorPanel`), web Device (`PrinterWebView`), Multi-device
+  (`MultiMachinePage`), Project (`ProjectPanel`), Calibration (`CalibrationPanel`), and Design
+  (`DesignPanel`, only under `SLIC3R_CAD` with the feature enabled, order −1 so it is never prebuilt).
+- `MainFrame::show_device` inserts and removes the Device, web Device, Multi-device and Calibration
+  pages depending on the printer and on `use_printer_agents`; a removed page stays registered but is
+  not prebuilt (its `LazyPage::in_book()` is false).
+- Plugin pages are appended by `PluginPages::initialize` (`plugin/host/PluginPages.hpp`) with
+  namespaced ids (`plugin.<plugin_key>.<name>`) that cannot collide with `TAB_ID_*`.
+
+### Preset tabs
+
+`MainFrame::create_preset_tabs` creates `TabPrint`, `TabPrintPlate`, `TabPrintObject`, `TabPrintPart`,
+`TabPrintLayer` on `m_param_panel`, and `TabFilament`, `TabPrinter` on `m_param_dialog->panel()`.
+`add_created_tab` moves the plate tab out of `tabs_list` into `plate_tab`, and the model tabs into
+`model_tabs_list`, so `tabs_list` holds print, filament and printer. Placement and the settings
+pipeline: [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs),
+`references/orca-settings-ui.md`.
+
+### DPI and colour fan-out
+
+`MainFrame::on_dpi_changed` and `MainFrame::on_sys_color_changed` call each component they own
+explicitly: the tab book and top bar `Rescale()`, the action buttons, `plater()->msw_rescale()` /
+`sys_color_changed()` (which go on to the preview, canvas, sidebar, `MenuFactory` and the cached
+select-machine dialog), `m_param_panel->msw_rescale()`, every tab's `sys_color_changed()`,
+`MenuFactory::sys_color_changed(m_menubar)`, `WebView::RecreateAll()`; lazy panels only through
+`X::when_built(...)` and built dialogs through `X::if_built()` (`DiffPresetDialog`). A panel or cached
+dialog that is not reached from this chain never runs its `msw_rescale` / `sys_color_changed`. The
+DPI mechanics are in `references/dpi-bitmaps-fonts.md`; the colour path (and why Windows reaches it
+through `force_color_changed`) is in `references/colours-dark-mode.md`.
+
+- **Rule:** When you add a panel with `msw_rescale()` / `on_sys_color_changed()` hooks, add it to the
+  fan-out of its owner in the same change.
+  **Why:** child panels are not top-level windows and get no DPI handling of their own from
+  `DPIAware`; on Windows the dark-mode toggle reaches components only through this chain.
+  ```cpp
+  // Right (MainFrame::on_dpi_changed): lazy panels through the statics
+  CalibrationPanel::when_built([](CalibrationPanel& calibration) { calibration.msw_rescale(); });
+  // Right (MainFrame::on_sys_color_changed): a lazily built dialog
+  if (DiffPresetDialog* dialog = DiffPresetDialog::if_built())
+      dialog->on_sys_color_changed();
+  ```
+  Cite: `MainFrame::on_dpi_changed`, `MainFrame::on_sys_color_changed`, `Plater::msw_rescale`.
+
+## Deferred construction (Lazy, LazyPage, StagedBuild, IdleScheduler)
+
+Design doc: `docs/HLSD/deferred-page-construction.md`. Startup pays only for what the first frame
+shows (the start page and the Prepare plater); every other tab, and heavy dialogs and GL resources,
+build on first show or in small units while the user is idle. A click during the idle build waits for
+one unit at most. The parts are independent and wx-free where possible (`Lazy`, `StagedBuild`,
+`PrebuildQueue` are unit-tested in `tests/slic3rutils`: `test_lazy.cpp`, `test_staged_build.cpp`,
+`test_prebuild_queue.cpp`).
+
+### The holder: `Lazy<T>` and `LazyInstance<T>`
+
+`Lazy<T>` (`GUI/Lazy.hpp`) holds a factory and the object it makes: `Lazy(name, order, factory)`.
+
+| Member | Contract |
+|---|---|
+| `get()` | the object, **null until completely built** (a staged object mid-build is null) |
+| `ensure()` | builds whatever is left now (busy cursor + log line) and returns the object; null if the factory returned null or a nested call finds it mid-build |
+| `when_built(fn)` | runs `fn` now if built, otherwise once the build completes |
+| `build_step()` | one unit: the factory first, then one `StagedBuild` step per call; a nested call (a unit that pumps the loop) does nothing |
+| `prebuild_order()` | position in the idle queue; lower first; **negative = never prebuilt** |
+
+The holder does not own the object — its wx parent does. A factory that returns null or a unit that
+throws leaves the holder and scheduler able to carry on. `LazyInstance<Self>` is a mixin that gives a
+type with one instance app-wide the statics `Self::if_built()`, `Self::ensure()`,
+`Self::when_built(fn)`; the `Lazy<Self>` constructor registers itself, and a recreated `MainFrame`'s
+holder replaces the old one. All statics are harmless (null / no-op) while no holder exists —
+including `when_built`, which then drops `fn`.
+
+### The placeholder page: `LazyPage<Panel>`
+
+`LazyPage<Panel> : wxPanel, Lazy<Panel>` (`GUI/LazyPage.hpp`) is the notebook page (the book needs a
+page object to insert and remove by pointer). `LazyPage(parent, name, order, factory)`; the default
+factory is `new Panel(parent)`. Its `Show(true)` builds the panel the first time (only once the
+top-level frame is shown — `MainFrame::Show` completes the start page on the frame's first show) and
+forwards later shows/hides to the panel, so the panel's own `Show()` override stays its activation
+hook. A panel built while its page is hidden stays hidden, and `when_built` gives it the dark-UI pass
+the frame ran before it existed (`apply_dark_ui_to_lazy_panel`). `pending()` is true only while the page
+is in the book.
+
+### Staged construction: StagedBuild
+
+`StagedBuild` (`GUI/StagedBuild.hpp`) splits a constructor too big for one unit: the constructor builds
+a skeleton and queues the rest with `add_build_step(fn)`; `add_build_steps_of(child)` forwards a child
+panel's steps, and the parent is `built()` only once every child is. Constraints, all from the design:
+
+- members created in steps start null, so a partly built panel can be destroyed;
+- timers, event handlers and the destructor that touch step content check `built()` first;
+- nothing takes focus while off screen (a unit may run while the user types elsewhere);
+- a widget added by a step keeps its place through an empty sizer slot the skeleton creates.
+
+### The idle scheduler: IdleScheduler, PrebuildQueue
+
+`PrebuildQueue` (`GUI/PrebuildQueue.hpp`) orders `LazyBase` tasks by `prebuild_order()` (equal order:
+insertion order) and runs one slice of units of the first pending task. `IdleScheduler`
+(`GUI/IdleScheduler.hpp/.cpp`, `MainFrame::m_idle`) drives it from a self-owned `wxTimer`:
+
+- it ticks every 250 ms and runs a slice only after 500 ms without user input (`GUI_App::input_idle_ms`,
+  stamped by `GUI_App::FilterEvent` for non-command user-input events and main-frame resizes);
+- a slice spends at most 40 ms, then the next slice is `StartOnce(5)` — a separate timer message, so
+  paint, timers and input queued meanwhile run first. Posting slices as pending events would not do
+  that, because wx drains every pending event, including ones posted meanwhile, before the next
+  native message (`src/common/appbase.cpp` `wxAppConsoleBase::ProcessPendingEvents` loops until the
+  list is empty **[source]**);
+- it skips while `wxEventLoopBase::GetActive()->IsYielding()` (a slice inside a `wxYield()` would build
+  pages in the middle of the code that yielded) and guards re-entry with `m_in_slice`;
+- it stops its timer when nothing is pending, so it costs nothing afterwards.
+
+`MainFrame::prebuild_pages_when_idle` (called from `post_init` and `recreate_GUI`) clears the queue
+and registers the GL resources (`GLResourcesPrebuild`), the Prepare settings page one option group at
+a time (`ParamsPanel::settings_page_prebuild`), the Prepare layout at the book's page size
+(`m_prepare_layout_prebuild`), every lazy page with a non-negative order, and the lazily built
+dialogs (`m_diff_dialog`); the queue then runs them by `prebuild_order()`. `MainFrame::shutdown`
+stops it. Units should fit in one slice on a fast machine; a constructor over that is staged.
+
+**Platforms.** GTK: a timer that is always due (`g_timeout_add`, default priority,
+`src/gtk/timer.cpp`) runs ahead of the lower-priority GLib sources that repaint and that deliver
+posted events and idle (wx's single `G_PRIORITY_LOW` idle source, `src/gtk/app.cpp`
+`wxApp::WakeUpIdle` **[source]**) — hence the 5 ms gap rather than 0. macOS: wxOSX rejects a 0 ms
+timer (`src/osx/core/timer.cpp:74` `wxCHECK_MSG(m_milli > 0, …)` **[source]**; with asserts compiled
+out, `StartOnce(0)` silently never fires). Windows: a slice also waits while the native queue holds input
+(`GetQueueStatus`), not counting mouse moves, which Windows synthesises when a window appears under the
+cursor. GTK GL resources: the prebuild task `gtk_widget_realize`s the hidden canvas before making the
+context current, since GTK creates the surface only on realize.
+
+### Reaching a lazy object
+
+| Need | Use |
+|---|---|
+| work the object can live without (refresh, status update) | `if (X* x = X::if_built()) x->…;` |
+| navigating to it or showing it | `X::ensure()->…` (as `MainFrame::jump_to_monitor`) |
+| state it would not fetch for itself when constructed; rescale/recolour of a staged panel (null from `if_built()` while mid-build) | `X::when_built([](X& x) { … });` |
+
+A panel that pulls its own state in its constructor only ever needs `if_built()`.
+
+### Usage
+
+The shape to copy for a new tab (`MainFrame::init_tabpanel`):
+
+```cpp
+// Panel: one instance app-wide; heavy constructors also derive StagedBuild
+class CalibrationPanel : public wxPanel, public StagedBuild, public LazyInstance<CalibrationPanel> { … };
+
+// MainFrame::init_tabpanel: id, order (gaps leave room between neighbours; <0 = never prebuilt)
+m_calibration_page = new LazyPage<CalibrationPanel>(m_tabpanel, TAB_ID_CALIBRATION, 30);
+m_lazy_pages.push_back(m_calibration_page);
+m_tabpanel->AddPage(TAB_ID_CALIBRATION, m_calibration_page, _L("Calibration"), "tab_calibration_active");
+
+// MainFrame::on_dpi_changed / on_sys_color_changed
+CalibrationPanel::when_built([](CalibrationPanel& calibration) { calibration.msw_rescale(); });
+```
+
+A lazily built dialog is a `Lazy<Dlg>` member of `MainFrame` with `Dlg : DPIDialog,
+LazyInstance<Dlg>`, e.g. `m_diff_dialog("compare_presets", 100, [this] { return make_diff_dialog(); })`,
+added to the queue in `prebuild_pages_when_idle` if it should prebuild. The panel's constructor must
+cope with the main frame already existing and the user being busy elsewhere, and do all its own setup:
+the main frame does nothing to a panel after creating it.
+
+### Pitfalls
+
+- **Rule:** Do not `ensure()` a lazy object for optional work.
+  **Why:** `ensure()` builds the whole object now under a busy cursor, defeating the deferral for a
+  page the user may never open.
+  ```cpp
+  // Wrong: a DPI change builds the Device tab
+  MonitorPanel::ensure()->msw_rescale();
+  // Right
+  MonitorPanel::when_built([](MonitorPanel& monitor) { monitor.msw_rescale(); });
+  ```
+  Cite: `MainFrame::on_dpi_changed`.
+- **Rule:** In a staged panel, timer and event handlers return early until `built()`.
+  **Why:** a step-built member is null until its step runs; the timer can fire, or the book can select
+  the page, in between.
+  ```cpp
+  // Right (MonitorPanel::update_all)
+  if (!built())
+      return;
+  ```
+  Cite: `MonitorPanel::update_all`, `MonitorPanel::init_tabpanel` (steps queued before the page is
+  added, "where built() must already be false").
+- **Rule:** Never take focus while built off screen.
+  **Why:** a unit can run while the user is typing in another control; `SetFocus` steals the
+  keystrokes.
+  ```cpp
+  // Wrong
+  page->SetFocus();
+  // Right (MonitorPanel page-changed handler)
+  if (page->IsShownOnScreen())
+      page->SetFocus();
+  ```
+- **Rule:** Put background UI construction into the prebuild queue, not into idle events.
+  **Why:** an `wxEVT_IDLE` + `RequestMore()` loop busy-loops the CPU (wxGTK keeps its idle source
+  installed while more is requested, `src/gtk/app.cpp` `wxApp::DoIdle` **[source]**), runs inside
+  every `wxYield()` (a full yield calls `ProcessIdle()`, `src/common/evtloopcmn.cpp:182-191`
+  **[source]**), and builds even while the user is clicking or typing, so the input waits behind it.
+  ```cpp
+  // Wrong
+  Bind(wxEVT_IDLE, [this](wxIdleEvent& e) { /* build the next part */ e.RequestMore(); });
+  // Right: a Lazy<…> holder (or a LazyBase task) registered in MainFrame::prebuild_pages_when_idle
+  m_idle.add(m_diff_dialog);
+  ```
+  Cite: `IdleScheduler::tick`, `docs/HLSD/deferred-page-construction.md`.
+
+## Plater and Sidebar
+
+### Structure
+
+`Plater` and `Sidebar` (`GUI/Plater.hpp/.cpp`) are pimpl'd (`std::unique_ptr<priv> p`); public methods
+forward to `p->`. `Plater::priv` owns the model, `PartPlateList`, the three canvases (`view3D`,
+`preview`, `assemble_view` in one sizer inside `panel_3d`), `BackgroundSlicingProcess
+background_process`, `PlaterWorker<BoostThreadWorker> m_worker` (`Plater::get_ui_job_worker()`), the
+`NotificationManager`, `Mouse3DController`, `MenuFactory menus` and the AUI manager. New private state
+and helpers go into `priv` in `Plater.cpp`; the header changes only for a public entry point.
+
+### Event hub and custom events
+
+`Plater::priv::priv` is the hub: it binds Orca events on the canvases (`EVT_GLCANVAS_OBJECT_SELECT`,
+`EVT_GLCANVAS_RIGHT_CLICK`, `EVT_GLCANVAS_ARRANGE`, …, posted by `GLCanvas3D::post_event`, which does
+`wxPostEvent(m_canvas, …)`) and on the plater itself (`EVT_SLICING_UPDATE`, `EVT_SLICING_COMPLETED`,
+`EVT_PROCESS_COMPLETED`, `EVT_EXPORT_BEGAN`, `EVT_GLCANVAS_COLOR_MODE_CHANGED`, …). Events are declared
+in the header of the class that emits them (`GLCanvas3D.hpp`, `Plater.hpp`, `NotificationManager.hpp`,
+`ParamsDialog.hpp`); `BackgroundSlicingProcess` is handed the ids to post (`set_finished_event`,
+`set_export_began_event`).
+
+Payload types are in `GUI/Event.hpp`: `SimpleEvent`, `IntEvent`, `Event<T>`, `ArrayEvent<T,N>`. They
+derive from `wxEvent` but set `m_propagationLevel = wxEVENT_PROPAGATE_MAX` (a plain `wxEvent` does not
+propagate, a command event does — `interface/wx/event.h:270-273`) and implement `Clone()`, so they can
+be posted or queued and travel up to the plater.
+
+```cpp
+wxDECLARE_EVENT(EVT_GLCANVAS_ARRANGE, SimpleEvent);   // GLCanvas3D.hpp, next to the emitter
+wxDEFINE_EVENT(EVT_GLCANVAS_ARRANGE, SimpleEvent);    // GLCanvas3D.cpp
+post_event(SimpleEvent(EVT_GLCANVAS_ARRANGE));        // GLCanvas3D: wxPostEvent on the wxGLCanvas
+view3D_canvas->Bind(EVT_GLCANVAS_ARRANGE, [this](SimpleEvent& evt) { … });   // Plater::priv::priv
+wxQueueEvent(wxGetApp().plater(), new SimpleEvent(EVT_MODIFY_FILAMENT, filament_info)); // heap, owned (ParamsDialog)
+```
+
+Binding, `Skip`, `CallAfter` and cross-thread rules are in `references/events.md` and
+`references/threads-timers-app.md`.
+
+- **Rule:** A short-lived object that listens to plater (or canvas) events binds through `EventGuard`
+  (`GUI_Utils.hpp`) or unbinds in its destructor, and `Skip()`s.
+  **Why:** the plater outlives the listener; a handler left bound runs on a freed object. Dynamic
+  handlers run most recently bound first, so a handler that does not `Skip()` hides the event from the
+  plater's own handler (dynamically bound handlers are searched in reverse order of registration,
+  `docs/doxygen/overviews/eventhandling.h:480`). `EventGuard` stores the functor at a stable
+  address, which is what functor `Unbind` matches on (`interface/wx/event.h:967-970`).
+  ```cpp
+  // Wrong
+  wxGetApp().plater()->Bind(EVT_SLICING_UPDATE, [this](SlicingStatusEvent& e) { refresh(); });
+  // Right: member EventGuard unbinds when the dialog dies
+  m_slicing_guard = EventGuard(wxGetApp().plater(), EVT_SLICING_UPDATE,
+                               [this](SlicingStatusEvent& e) { refresh(); e.Skip(); });
+  ```
+  Cite: `EventGuard` (`GUI_Utils.hpp`), `PlaterWorker` (binds the plater's idle/paint through it).
+
+### Sidebar content
+
+`Sidebar::Sidebar` builds, inside `p->scrolled` (a `wxPanel`; the sidebar is itself the AUI pane
+`"sidebar"`):
+
+1. the printer block — title bar, `PlaterPresetComboBox* combo_printer`, bed type
+   (`combo_printer_bed`), nozzle/extruder cards (`ExtruderGroup`), sync and connect buttons;
+2. the filament block ("Project Filaments") — `combos_filament`, add / delete / edit, purge mode,
+   flushing volumes, AMS sync;
+3. the **`ParamsPanel` top bar reparented in** (`params_panel->get_top_panel()->Reparent(p->scrolled)`:
+   "Process" title, global/object switch, mode view);
+4. `p->sizer_params` (proportion 2): the object search box, `ObjectList` and the `ObjectLayers`
+   sizer (`ObjectSettings` is created on `p->scrolled`, but its sizer is added only in the
+   `#if !NEW_OBJECT_SETTING` branch);
+5. the **`ParamsPanel` itself reparented in** with proportion 3.
+
+So the process settings are the full `ParamsPanel` in the sidebar, not a summary group; the process
+preset combo is the `TabPrint` page's own `TabPresetComboBox`. `Sidebar::update_presets(type)` refreshes
+the combos after a preset change; `Sidebar::jump_to_option(...)` activates a tab row and blinks it;
+`Sidebar::settings_index()` (`Search::SettingsIndex`) and `Sidebar::get_searcher()`
+(`Search::OptionsSearcher`) are the settings search — `references/orca-settings-ui.md`.
+`Sidebar::load_ams_list(obj)` is how device data reaches the filament block.
+
+Spacing constants come from `SidebarProps` (`Plater.hpp`): `TitlebarMargin()`, `ContentMargin()`,
+`ContentMarginV()`, `IconSpacing()`, `WideSpacing()`, `ElementSpacing()`, used as
+`FromDIP(SidebarProps::ContentMargin())`. A new sidebar control uses them and is added to
+`Sidebar::msw_rescale`, `Sidebar::sys_color_changed` and, if mode-dependent, `Sidebar::update_mode`.
+
+### Docking
+
+`Plater::priv` owns `AuiMgr m_aui_mgr` (a `wxAuiManager` subclass whose `CreateFloatingFrame` returns a
+themed `FloatFrame : wxAuiFloatingFrame`), managing the plater. Panes: `"sidebar"` (left, no close
+button, not top/bottom dockable), `"main"` (`CenterPane()`, the `panel_3d`), `"uv_editor"` (right,
+hidden until the texture-displacement gizmo shows it), plus dynamic dock panes. The default perspective
+is saved right after `AddPane`; the app-config `window_layout` is applied with
+`LoadPerspective(layout, false)` and falls back to the default on failure; `Plater::priv::reset` saves
+it back. On Wayland floating is disabled (`wxAUI_MGR_ALLOW_FLOATING` cleared,
+`sanitize_window_layout_for_wayland` strips floating state). wx AUI contracts (`Update()` batching,
+perspective semantics, floating-frame lifetime): `references/webview-gl-aui-media.md`.
+
+`Plater::add_dock_pane(window, name, caption, dock, size, on_close)` adds a pane: `window` must be a
+child of the plater; `dock` is `"left"`, `"right"`, `"bottom"` or `"float"`; `size` is in DIPs; the
+name is made unique with `#2`, `#3`…; a saved per-pane layout entry restores its last place. A pane
+closed by its own close button is destroyed after `on_close` runs; `remove_dock_pane(window)` destroys
+it **without** calling `on_close`; `remove_dock_panes()` runs from `MainFrame::shutdown`.
+`show_dock_pane(window, show)` toggles it. `DockPanel : WebPanel` is the plugin pane, named with
+`plugin_pane_name(plugin_key, title)` ("stable across sessions … free of wxAuiManager layout
+delimiters").
+
+- **Rule:** Name a dock pane with a stable, untranslated identifier free of `|`, `;`, `=` and `\`.
+  **Why:** `LoadPerspective` restores only panes whose names match, and wx's own parser hides every
+  pane it does not find (`src/aui/framemanager.cpp:1906-1912` **[source]**, contrary to `interface/wx/aui/framemanager.h:562-565`).
+  A translated or reused name loses its layout after a language switch or collides.
+  ```cpp
+  // Wrong
+  plater->add_dock_pane(panel, into_u8(caption), caption, "right", size, on_close);
+  // Right
+  plater->add_dock_pane(panel, plugin_pane_name(plugin_key, title), caption, "right", size, on_close);
+  ```
+  Cite: `Plater::priv::add_dock_pane`, `DockPanel.hpp`.
+
+### Context menus
+
+Right-click menus are built and cached by `MenuFactory` (`GUI/GUI_Factories.hpp`, `Plater::priv::menus`)
+and shown with `Plater::PopupMenu`, which suppresses background-processing updates while the menu tracks
+and defers slicing error dialogs (`m_tracking_popup_menu`) to a `CallAfter` after the menu closes. Detail:
+`references/popups-menus.md`.
+
+## Settings placement: ParamsPanel, ParamsDialog, Tabs
+
+- `m_param_panel` (a `ParamsPanel`) is created as a `m_tabpanel` child in `MainFrame::init_tabpanel`
+  and reparented into the sidebar by `Sidebar::Sidebar` (top bar and body separately). It hosts the
+  process tab and the model-scope tabs; `ParamsPanel::switch_to_object` / `switch_to_global` flip the
+  sidebar between object and global settings.
+- `m_param_dialog` (a `ParamsDialog : DPIDialog`, parented to the plater) owns a second `ParamsPanel`
+  with the filament and printer tabs. It is **modeless with emulated modality** (a `wxWindowDisabler`
+  while shown); `Popup()`, the close/validation path and where post-edit work goes:
+  `references/orca-settings-ui.md` §Where the tabs live; the modality mechanics:
+  `references/windows-dialogs.md` §6.
+
+The pipeline from `PrintConfigDef` to `Field`, adding a setting, toggles, search and per-object
+overrides: `references/orca-settings-ui.md`.
+
+- **Rule:** Null-check `get_tab()`.
+  **Why:** tabs complete after construction, and `MainFrame::shutdown` clears `tabs_list`.
+  ```cpp
+  // Wrong
+  wxGetApp().get_tab(Preset::TYPE_PRINTER)->reload_config();
+  // Right
+  if (Tab* tab = wxGetApp().get_tab(Preset::TYPE_PRINTER)) tab->reload_config();
+  ```
+
+## ObjectList
+
+`ObjectList : wxDataViewCtrl` (`GUI/GUI_ObjectList.hpp`) over `ObjectDataViewModel : wxDataViewModel`
+(`GUI/ObjectDataViewModel.hpp`), whose nodes are typed by the `ItemType` bitmask (`itPlate`,
+`itObject`, `itVolume`, `itInstanceRoot`, `itInstance`, `itSettings`, `itLayerRoot`, `itLayer`,
+`itInfo`). It lives in the sidebar, is initialised by `obj_list()->init()` after the main frame is
+created, gets keys through the shortcut registry (`ObjectList::dispatch_shortcut`; on macOS a
+`wxAcceleratorTable` regenerated by `update_shortcut_accelerators`, because the native control
+delivers no key events), and shows context menus through `MenuFactory` + `Plater::PopupMenu`. Per-object
+overrides appear as `itSettings` children that open the model-scope tabs. Model ownership, renderers,
+drag and drop, native-vs-generic data view: `references/controls-dataview.md`.
+
+## 3D canvas, ImGui layer and NotificationManager
+
+### GLCanvas3D
+
+`GLCanvas3D` is **not a window**: it wraps a `wxGLCanvas* m_canvas` (`get_wxglcanvas()`) created by
+`OpenGLManager`, binds its size/idle/key/mouse/paint/focus/timer handlers in `bind_event_handlers`, and
+must be unbound before teardown (`Plater::unbind_canvas_event_handlers`, from `MainFrame::shutdown`).
+Rendering is idle-driven: handlers mark `set_as_dirty()`, `request_extra_frame()` or
+`schedule_extra_frame(ms)`, and `on_idle` renders. Outgoing events go through `GLCanvas3D::post_event`.
+The view, preview and assemble canvases and the UV editor share one `wxGLContext`. Paint/idle/swap
+details, the shared-context attribute rule and EGL/GLX: `references/webview-gl-aui-media.md`.
+
+### What is ImGui and what is wx
+
+| Drawn with ImGui inside the canvas | wx windows |
+|---|---|
+| gizmo panels (`GLGizmoBase::on_render_input_window`), `NotificationManager` and its hint / slicing-progress notifications, the preview layer slider (`IMSlider`), `IMToolbar`, the G-code legend (`GCodeViewer`), plate labels (`PartPlate`), and the overlays in `GLCanvas3D::_render_overlays` (plate-select toolbar, variable-layer-height dialog, 3D navigator, toolbar item windows) | everything outside the canvas: sidebar, tabs, dialogs, top bar, Home/Device/Project pages |
+
+`GLToolbar` is not ImGui: its icons are OpenGL-textured quads; only its item option windows are
+ImGui callbacks. ImGui input arrives only through the canvas's own handlers (`ImGuiWrapper::update_mouse_data` /
+`update_key_data`), so text entry needs canvas focus; ImGui sizes are physical pixels (scale by
+`GLCanvas3D::get_scale()`); ImGui strings are UTF-8 (`_u8L`). wx theming, `DPIDialog`, sizers and
+`Widgets/` do not apply there.
+
+- **Rule:** Never place a wx child window over the GL canvas; draw the overlay in ImGui or put a wx
+  window beside the canvas.
+  **Why:** on GTK the GL canvas is a native child window or, on Wayland, a subsurface drawn outside
+  GTK, and a wx child over it does not reliably stack above the GL content.
+  ```cpp
+  // Wrong
+  auto* banner = new wxPanel(canvas->get_wxglcanvas());
+  // Right: ImGui from the gizmo / overlay pass, or a sibling of the canvas in the plater layout
+  void on_render_input_window(float x, float y, float bottom_limit) override;   // GLGizmoBase
+  ```
+  Cite: `docs/HLSD/design-tab.md` (sketch banner "a sibling of the canvas, not a child over it").
+
+### NotificationManager
+
+`NotificationManager` (`GUI/NotificationManager.hpp`) is owned by `Plater::priv` and initialised after
+the canvas exists (`Plater::init_notification_manager`; notifications pushed before `init()` are
+neither shown nor updated). Push with
+`push_notification(NotificationType, NotificationLevel, text, hypertext, callback)`;
+`NotificationType::CustomNotification` covers one-offs, and a new `NotificationType` is needed only
+when the notification must be closed or updated by type (`close_notification_of_type`). Levels order
+importance and fading (`RegularNotificationLevel` fades, `ErrorNotificationLevel` never does). It has
+no locking, and it draws only while the plater's canvas renders.
+
+- **Rule:** Push notifications from the UI thread, and use a dialog for messages that must be seen
+  while Home or Device is shown.
+  **Why:** the manager's containers are unsynchronised; a notification pushed while the plater is
+  hidden is not drawn until the user returns to Prepare/Preview.
+  ```cpp
+  // Wrong: inside Job::process or an agent callback
+  wxGetApp().notification_manager()->push_notification(text);
+  // Right
+  wxGetApp().CallAfter([text] {
+      if (wxGetApp().is_closing()) return;
+      if (NotificationManager* nm = wxGetApp().notification_manager())
+          nm->push_notification(NotificationType::CustomNotification,
+                                NotificationManager::NotificationLevel::RegularNotificationLevel, text);
+  });
+  ```
+
+## Background work
+
+| Kind | Mechanism | Back to the UI |
+|---|---|---|
+| UI-initiated task (arrange, orient, fill bed, send) | `Job` subclass in `GUI/Jobs/`; `replace_job(plater->get_ui_job_worker(), std::make_unique<OrientJob>())`, or a dialog-owned `PlaterWorker<BoostThreadWorker>` | `Job::finalize` and `Ctl::call_on_main_thread`, delivered from the owner window's idle/paint |
+| slicing and export | `BackgroundSlicingProcess` (`Plater::priv::background_process`) | `wxQueueEvent(plater, evt.Clone())`; `execute_ui_task` for a synchronous UI call |
+| network agents, HTTP, preset sync | agent / io threads | `wxGetApp().CallAfter` + `is_closing()`; agents get `set_queue_on_main_fn` |
+| geometry | TBB | no wx calls inside |
+
+The contracts (which side runs what, cancellation, the `eptr` rethrow, deadlock rules, platform stalls)
+are in `references/threads-timers-app.md`.
+
+## Device and Monitor pages
+
+Design doc: `docs/HLSD/printer-agent.md`; implementing a printer agent: the `orca-printer-communication`
+skill. Data flow:
+
+1. `NetworkAgent` (façade over the active `IPrinterAgent` and the cloud agents) calls the callbacks
+   installed by `GUI_App::init_networking_callbacks` (`set_on_message_fn`, `set_on_local_message_fn`,
+   `set_on_printer_connected_fn`, `set_queue_on_main_fn`, …) and by `GUI_App::post_init` /
+   `restart_networking` (`set_on_ssdp_msg_fn`) on its own threads.
+2. Each callback returns if `is_closing()`, then `CallAfter`s a by-value lambda that re-checks
+   `is_closing()` and, on the UI thread, updates the `MachineObject` (`parse_json`), refreshes
+   `Sidebar::load_ams_list` and `Plater::update_machine_sync_status`. `MachineObject` and
+   `DeviceManager` state is main-thread-only.
+3. The Device UI is **pull-based**: `MonitorPanel : wxPanel, StagedBuild, LazyInstance<MonitorPanel>`
+   (`GUI/Monitor.hpp`) starts its refresh `wxTimer` in its `Show(true)` override, stops it on hide, and
+   `on_timer` → `update_all()` reads `DeviceManager::get_selected_machine()` and pushes it into the
+   `StatusPanel` (`StatusBasePanel : wxScrolledWindow, StagedBuild`), HMS and media pages inside a
+   `Tabbook`. `DeviceManager::start_refresher` / `stop_refresher` follow the main frame's `wxEVT_SHOW`.
+4. Camera playback: `MediaPlayCtrl` selects and tears down the stream backend; the wx parent owns the
+   rendering window.
+
+New device UI goes inside `MonitorPanel` / `StatusPanel`, reads state on the timer, makes no network
+call on the UI path, and stops its timers on hide.
+
+## Web-based UI
+
+| Host | Use |
+|---|---|
+| `WebView::CreateWebView(parent, url)` (`Widgets/WebView.hpp`) | the sanctioned way to make a browser: backend choice, handlers, user agent, `"wx"` script handler once per view, registration for `WebView::RecreateAll()` theming, a `FakeWebView` stub instead of null on failure. A raw `wxWebView::New` view gets none of these (no theming on colour change, no null safety) |
+| `WebViewPanel` (`WebViewDialog.hpp`, `LazyInstance`) | the Home tab |
+| `PrinterWebView` (`LazyInstance`) | the web Device tab (Fluidd/Mainsail/printer UIs) |
+| `WebViewHostDialog : DPIDialog` (`Widgets/WebViewHostDialog.hpp`) | local-HTML dialogs: `create_webview(resource_path, …)`, pure-virtual `on_script_message(json)`, `handle_common_script_command`, theme user scripts registered once, `apply_theme_live`, `call_web_handler` (C++ → JS). Subclasses include `WebDialog`, `PluginsDialog`, `PluginsConfigDialog`, `SpeedDialWebDialog`, `TerminalDialog`, `PresetBundleDialog`, `ExportPresetBundleDialog` |
+| `WebPanel`, `DockPanel : WebPanel` | plugin pages and docked plugin panes |
+| `GuideFrame` (`WebGuideDialog.hpp`) | setup wizard |
+
+Script messages arrive synchronously inside the native WebKit delegate / GTK signal on macOS and Linux
+(**[source]**; Edge queues them), so a subclass defers every window operation (show, close, create, `EndModal`) with `CallAfter` and
+re-checks liveness inside; `handle_common_script_command`'s `close_page` ends the dialog directly and
+`call_web_handler` captures `this` in an app `CallAfter`, so a subclass whose lifetime can end first
+adds its own guard. Backend rules, creation order, `RunScript` re-entrancy: `references/webview-gl-aui-media.md`.
+
+## Preferences
+
+`PreferencesDialog : DPIDialog` (`GUI/Preferences.hpp`) is a `TabCtrl m_pref_tabs` over the
+`PreferencesTab` pages (`General`, `Control`, `Graphics`, `Online`) plus the Associate and Developer pages,
+each a `wxFlexGridSizer` of rows built in `PreferencesDialog::create_items` with the
+`create_item_title / label / checkbox / combobox / input / spinctrl / decimal_input / button / …`
+helpers (title, tooltip, app-config key, …, `wiki_url`). Window focus follows creation order, so rows are
+created in display order; an empty tooltip is filled from the title.
+
+- Rows **write `app_config` and `save()` immediately** in their handler; side effects are `param == "…"`
+  branches inside the row's handler (`create_item_checkbox`).
+- The dialog is opened only through `GUI_App::open_preferences(tab, highlight_option)`, which shows it
+  modally in an inner scope (it must be destroyed before `recreate_GUI`), then handles what must happen
+  after it closes: canvas focus, reloading the print when sequence options changed, file associations
+  on Windows, redraw when a render setting changed, a pending language switch (`load_language`,
+  `ActionRegistry::relocalize_builtins`, `recreate_GUI`).
+- The Windows-only dark-mode row (`create_item_darkmode`) is described in
+  `references/colours-dark-mode.md`.
+
+```cpp
+// PreferencesDialog::create_items — a checkbox row bound to an app_config key
+auto item_show_splash_scr = create_item_checkbox(_L("Show splash screen"),
+                                                 _L("Show the splash screen during startup."), "show_splash_screen");
+g_sizer->Add(item_show_splash_scr);
+// AppConfig::set_defaults — the default for a fresh config
+if (get("show_splash_screen").empty())
+    set_bool("show_splash_screen", true);
+```
+
+- **Rule:** Put a preference's runtime effect where it belongs: immediate effects in the row handler,
+  effects that need the dialog gone (rebuilding the GUI, reloading the print) in
+  `GUI_App::open_preferences`.
+  **Why:** `recreate_GUI` while the dialog is alive crashed in `~wxDialogBase` (the inner-scope comment
+  in `open_preferences`); work done from the row handler runs under the modal loop.
+
+## AppConfig
+
+`AppConfig` (`libslic3r/AppConfig.hpp`) is Orca's own string store, saved as JSON, not `wxConfig`
+(comparison with `wxConfig`: `references/strings-i18n-files.md`). Keys live in sections (`"app"` by
+default).
+
+| Call | Behaviour |
+|---|---|
+| `get(key)` / `get(section, key)` | the string, `""` if missing |
+| `get_bool(key)` | `get("app", key) == "true" \|\| get("app", key) == "1"` |
+| `get_bool(section, key)` | `get(section, key) == "true" \|\| get("app", key) == "1"` — the `"1"` is read from **`"app"`** |
+| `set(key, value)`, `set(section, key, value)`, `set_str(section, key, value)`, `set(section, key, bool)` | marks dirty only when the value changes; the `bool` overload writes `"true"`/`"false"`, and a bare `const char*` value selects it — pass a `std::string` or use `set_str` (`references/strings-i18n-files.md` §AppConfig) |
+| `set_bool(key, value)` | `"true"`/`"false"` in `"app"` |
+| `has(section, key)`, `dirty()`, `save()` | `save()` throws `CriticalException` off the main thread |
+| `set_defaults()` | fills missing keys at load (`if (get("k").empty()) set…`) |
+
+Persistence: the app idle handler saves whenever `dirty()` after `post_init`, and `MainFrame::shutdown`
+saves if dirty, so a `set` persists on its own; an explicit `save()` is for immediate persistence
+(Preferences rows, dark-mode init). Keys use both conventions — `set_bool` keys hold `"true"/"false"`,
+others hold `"1"/"0"` (`dark_color_mode`, `default_page`, `sys_menu_enabled`) — so compare with the
+key's own convention.
+
+- **Rule:** Read a non-`"app"` boolean with `get(section, key)` and an explicit comparison.
+  **Why:** `get_bool(section, key)` accepts `"1"` only from the `"app"` section.
+  ```cpp
+  // Wrong: false when section/key holds "1"
+  bool on = app_config->get_bool("section", "key");
+  // Right
+  bool on = app_config->get("section", "key") == "1";
+  ```
+- **Rule:** Write `app_config` on the main thread only.
+  **Why:** the storage map is unsynchronised and `save()` throws off the main thread.
+  ```cpp
+  // Wrong: on a worker or agent thread
+  wxGetApp().app_config->set("key", value);
+  // Right
+  wxGetApp().CallAfter([value] { if (!wxGetApp().is_closing()) wxGetApp().app_config->set("key", value); });
+  ```
+  Cite: `AppConfig::save`.
+
+## Where new code goes
+
+| You add | Put it | Must also |
+|---|---|---|
+| Modal dialog | `GUI/<Name>Dialog.hpp/.cpp`, `class X : public DPIDialog` | follow the dialog recipe in `references/windows-dialogs.md` (parent fallback `wxGetApp().mainframe`, `on_dpi_changed`, `SetSizerAndFit`, `UpdateDlgDarkUI` last) |
+| Message / confirm box | `MessageDialog`, `RichMessageDialog`, `WarningDialog`, `ErrorDialog`, `InfoDialog` (`MsgDialog.hpp`), or `show_error` / `show_info` (`GUI.hpp`) | never `wxMessageBox`; `show_error` is asynchronous (an app `CallAfter` around an `ErrorDialog`), so pass a parent that outlives the call or none; `show_info` is a synchronous modal `MessageDialog` — `references/windows-dialogs.md` |
+| Local-HTML dialog | subclass `WebViewHostDialog` | implement `on_script_message`; reuse `handle_common_script_command`; defer window operations; register user scripts once ([Web UI](#web-based-ui)) |
+| Top-level tab | `LazyPage<Panel>` + `TAB_ID_*` in `MainFrame::init_tabpanel` | panel derives `LazyInstance<Panel>` (+ `StagedBuild` if heavy); fan-out hooks with `when_built`; statics outside `MainFrame`; no focus off screen |
+| Heavy dialog owned by the frame | `Lazy<Dlg>` member of `MainFrame`, `Dlg : LazyInstance<Dlg>` | register in `prebuild_pages_when_idle` to prebuild; `if_built()` in the colour fan-out |
+| Sidebar control | `Sidebar::Sidebar`, state in `Sidebar::priv` | `SidebarProps` spacing; add to `Sidebar::msw_rescale`, `sys_color_changed`, `update_mode` |
+| Docked pane | `Plater::add_dock_pane` | window is a plater child; stable name; know that `remove_dock_pane` skips `on_close` |
+| Print / filament / printer setting | def in `PrintConfig.cpp`, row in `Tab*::build` | the full checklist in `references/orca-settings-ui.md` |
+| Per-object setting | `SettingsFactory::OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS` | `references/orca-settings-ui.md` |
+| Overlay or tool UI in the 3D view | gizmo `on_render_input_window` or `GLCanvas3D::_render_overlays` | ImGui + `_u8L`; redraw via `set_as_dirty()` / `request_extra_frame()`; GL only in the canvas's current context |
+| Transient message about the 3D view | `NotificationManager::push_notification` | UI thread; new `NotificationType` only to close/update by type |
+| Main-menu item | the shared `wxMenu` in `MainFrame::init_menubar_as_editor` / `generate_help_menu` | `append_menu_item`, or `append_shortcut_item` when it has a shortcut — `references/popups-menus.md` |
+| Context-menu item | `MenuFactory` (`GUI_Factories.cpp`) | show with `Plater::PopupMenu` |
+| Speed Dial command | the `NativeCommands` catalog (`NativeCommands.cpp`, `NativeCommand{key, title, group, input, icon, runner}`) | `ActionRegistry` stores and dispatches it |
+| Keyboard shortcut | `Shortcut` enum + `shortcut_table` (`Shortcuts.cpp`) | handle in the context's dispatcher; labels from the registry — `references/mouse-keyboard-focus.md`, `docs/HLSD/keyboard-shortcuts.md` |
+| Preference | a `create_item_*` row in `PreferencesDialog::create_items`; default in `AppConfig::set_defaults` | effects in the row handler; post-close effects in `GUI_App::open_preferences` |
+| Background task | `Job` subclass in `GUI/Jobs/` | UI only in `finalize` / `call_on_main_thread`; poll `was_canceled()` — `references/threads-timers-app.md` |
+| Device UI | inside `MonitorPanel` / `StatusPanel` | pull from `DeviceManager::get_selected_machine()` on the timer; no network calls on the UI path |
+| Reusable control | `GUI/Widgets/` | `references/orca-widgets.md`, `references/painting-custom-widgets.md` |
+| Source files | `src/slic3r/CMakeLists.txt` | [Build registration](#build-registration) |
+| Tests for wx-free GUI logic | `tests/slic3rutils/test_<subsystem>.cpp` (as `test_lazy.cpp`, `test_shortcuts.cpp`) | list the file in that suite's `CMakeLists.txt` (`tests/AGENTS.md`) |
+
+## Build registration
+
+`src/slic3r/CMakeLists.txt` defines `SLIC3R_GUI_SOURCES`, the list compiled into `libslic3r_gui`. It
+covers everything under `src/slic3r` (`GUI/`, `GUI/Widgets/`, `GUI/Jobs/`, `Utils/`, `Config/`,
+`plugin/`), with paths relative to `src/slic3r`. Add a new `.cpp`/`.hpp` pair on consecutive lines
+(the list is only roughly alphabetical). Additional places:
+
+| File kind | Where |
+|---|---|
+| Windows-only sources | `if (WIN32) list(APPEND SLIC3R_GUI_SOURCES …)` (the vendored `GUI/dark_mode/` code lives there) |
+| macOS Objective-C++ (`.mm`) and their headers | `if (APPLE) list(APPEND SLIC3R_GUI_SOURCES …)` |
+| Design/CAD UI | the `if (SLIC3R_CAD) list(APPEND …)` block; shared code that references it is guarded with `#ifdef SLIC3R_CAD` (the root `CMakeLists.txt` adds the definition) |
+| `GUI/DeviceCore/`, `GUI/DeviceTab/` | their own `CMakeLists.txt`, included with `add_subdirectory`, which `list(APPEND SLIC3R_GUI_SOURCES …)` and re-export it with `PARENT_SCOPE` |
+
+- **Rule:** Keep platform-only sources out of the shared list.
+  **Why:** an `.mm` file or a Win32-only header in the shared list breaks the other platforms' builds.
+  ```cmake
+  # Wrong: in the shared set(SLIC3R_GUI_SOURCES …) list
+      GUI/GUI_UtilsMac.mm
+  # Right
+  if (APPLE)
+      list(APPEND SLIC3R_GUI_SOURCES
+              GUI/GUI_UtilsMac.mm
+          )
+  endif ()
+  ```
+
+## Design docs (docs/HLSD)
+
+Per `AGENTS.md`, the high-level design of a subsystem goes in `docs/HLSD/<subsystem>.md`, describes
+the design as it stands (no phases or before/after framing), and is updated in the same PR when a change
+invalidates it. Planning output stays in the gitignored `docs/superpowers/`. GUI-relevant documents:
+
+| Doc | Covers |
+|---|---|
+| `docs/HLSD/deferred-page-construction.md` | `Lazy`, `LazyPage`, `StagedBuild`, `IdleScheduler`, `PrebuildQueue`, GL-resource prebuild; rules for reaching lazy objects, unit size, order |
+| `docs/HLSD/keyboard-shortcuts.md` | `KeyChord`, `Shortcut` / `shortcut_table`, `ShortcutRegistry`, contexts and dispatchers, labels, the shortcuts dialog, "Adding a shortcut" |
+| `docs/HLSD/design-tab.md` | the Design (CAD) tab: `SLIC3R_CAD` gate, null-guarded hooks in `GLCanvas3D`, Esc-level contract, generated offer table, project persistence |
+| `docs/HLSD/printer-agent.md` | `NetworkAgent`, `IPrinterAgent`, `ICloudServiceAgent`, `DeviceManager` / `MachineObject` ownership, camera playback boundary |
+
+The other HLSD documents cover slicing features and profile data (for example `preset-cache.md`, which
+explains how system presets load at startup).

.claude/skills/orca-wxwidgets/references/orca-settings-ui.md

@@ -0,0 +1,707 @@
+# OrcaSlicer settings UI: PrintConfig → Tab
+
+How a `ConfigOptionDef` becomes a row in a settings tab, how edits flow back into the config, and everything
+a print/filament/printer setting must touch to load, save, show, search, translate, toggle and override.
+Read it before adding or changing a setting, writing a `Field` type or custom row widget, adding dependency
+rules, or debugging a settings row that does not show, save, search, revert or translate.
+
+Contents: [Rules](#rules) · [Pipeline](#pipeline-at-a-glance) · [ConfigOptionDef](#configoptiondef-the-data-side) ·
+[Config classes and preset lists](#config-classes-preset-lists-and-variants) · [Tabs and placement](#tabs-pages-and-where-they-live) ·
+[Groups, options, lines](#optionsgroup-option-and-line) · [build_field](#optionsgroupbuild_field) ·
+[Field and value flow](#field-and-the-value-flow) · [Control pooling](#field-control-pooling) ·
+[Lazy building and OG_CustomCtrl](#lazy-building-and-og_customctrl) · [ConfigManipulation](#configmanipulation-toggles-and-fix-ups) ·
+[Search index](#search-index-registration) · [Localization](#localization-of-option-definitions) ·
+[Per-object overrides](#per-object-part-layer-and-plate-overrides) · [Checklist](#checklist-adding-a-setting)
+
+## Rules
+
+1. Declare a setting once, in `PrintConfigDef::init_*_params()`, with `label`, `category`, `tooltip`, `sidetext`,
+   `mode`, limits and a default; mark every user-visible string with `L()`, never `_L()`. → [ConfigOptionDef](#configoptiondef-the-data-side)
+2. Put the member in the `PRINT_CONFIG_CLASS_DEFINE` block of the scope it belongs to; the class decides whether
+   the setting can be overridden per object, part or layer range. → [Config classes](#config-classes-preset-lists-and-variants), [Overrides](#per-object-part-layer-and-plate-overrides)
+3. List the key in the `Preset` option list of its preset type; without it the key is absent from the tab's
+   config and the row cannot be built. → [Config classes](#config-classes-preset-lists-and-variants)
+4. A per-variant key is a vector option listed in the matching `*_options_with_variant` set, appended with index
+   `0`, and toggled with the variant index. → [Variants](#per-extruder-variant-options)
+5. Add the row with `optgroup->append_single_option_line(key, wiki_path)` in `TabX::build()`; widget, tooltip,
+   undo/system icons, dirty tracking and search all come from the def. → [Groups](#optionsgroup-option-and-line)
+6. Page titles, group titles, `Line` labels and tooltips are English `L()` strings; translation happens at
+   display time. → [Localization](#localization-of-option-definitions)
+7. Do not rely on `L_CONTEXT` in a def: the display path translates without context. → [Localization](#localization-of-option-definitions)
+8. A row built from a custom widget has no `Field`; give its key name branches in `Tab::decorate`,
+   `Tab::on_roll_back_value` and `ConfigOptionsGroup::back_to_config_value` (plus `Tab::options_list_storage_key`
+   for a vector key). → [Custom widgets](#custom-widgets-on-a-line)
+9. In a `Field::BUILD()`, create controls through a `static Builder<T>` per construction style, re-set every
+   property, and bind every handler with the control's id. → [Pooling](#field-control-pooling)
+10. Bind with an id only events the widget emits with its id; `::ComboBox` sends `wxEVT_COMBOBOX_DROPDOWN/CLOSEUP`
+    with id 0. → [Pooling](#field-control-pooling)
+11. Fields exist only for the active page: null-check `get_field()`, and use `toggle_line` (not field state) for
+    anything that must hold on every page. → [Lazy building](#lazy-building-and-og_customctrl)
+12. Dependent enable/hide rules go in `ConfigManipulation::toggle_*_options`; value fix-ups go in
+    `ConfigManipulation::update_*_config` through `apply()` under the `is_msg_dlg_already_exist` guard.
+    → [ConfigManipulation](#configmanipulation-toggles-and-fix-ups)
+13. Set field values from code with `set_value(value, false)`; the `boost::any` must hold the display type that
+    `ConfigOptionsGroup::get_config_value` produces for the option type. → [Field](#field-and-the-value-flow)
+14. Teach `Print::invalidate_state_by_config_options` / `PrintObject::invalidate_state_by_config_options` which
+    steps the key invalidates; an unknown key reslices everything. → [Checklist](#checklist-adding-a-setting)
+15. A setting is searchable, offered by the Speed Dial and listed in the unsaved-changes/compare dialogs only if a
+    settings tab registers it in a titled group and it has a label. → [Search index](#search-index-registration)
+16. Filament and printer tabs live in the modeless `ParamsDialog`; code that must run after editing hooks its
+    close path, not the line after `Popup()`. → [Placement](#where-the-tabs-live)
+17. Renaming or removing a key needs `PrintConfigDef::handle_legacy`, and a new key's default must reproduce the
+    old behaviour for existing profiles and projects. → [Checklist](#checklist-adding-a-setting)
+
+## Pipeline at a glance
+
+```
+PrintConfigDef::init_*_params()      def = this->add(key, coX) ...           libslic3r/PrintConfig.cpp
+PRINT_CONFIG_CLASS_DEFINE(...)       ((ConfigOptionX, key))                  libslic3r/PrintConfig.hpp
+s_Preset_*_options                   key saved/loaded/diffed per preset      libslic3r/Preset.cpp
+TabX::build()                        add_options_page → Page::new_optgroup   slic3r/GUI/Tab.cpp
+  ConfigOptionsGroup::append_single_option_line(key, wiki, idx)
+    get_option(): m_opt_map["key#idx"], settings_index().add_key(...)       slic3r/GUI/OptionsGroup.cpp
+    create_single_option_line(): Line{label, formatted tooltip}
+    append_line(): index.set_path / set_line_label
+page shown → Page::activate → OptionsGroup::activate → activate_line
+    → OptionsGroup::build_field → Field::Create<T> → T::BUILD()             slic3r/GUI/Field.cpp
+    → OG_CustomCtrl paints labels, sidetext, undo icons                      slic3r/GUI/OG_CustomCtrl.cpp
+edit → Field::on_change_field → OptionsGroup::on_change_OG → ConfigOptionsGroup::on_change_OG
+    → change_opt_value(config) → group m_on_change (Page::new_optgroup)
+    → Tab::update_dirty() + Tab::on_value_change() → TabX::update()
+    → ConfigManipulation::update_*_config → toggle_options() → MainFrame::on_config_changed
+```
+
+## ConfigOptionDef: the data side
+
+**Contract.** `ConfigOptionDef` (`src/libslic3r/Config.hpp`) is the static description of one key: type,
+default, GUI presentation, limits and legacy names. Defs are registered with `ConfigDef::add(key, type)` (or
+`add_nullable`) inside `PrintConfigDef::init_common_params` / `init_fff_params` / `init_sla_params`
+(`src/libslic3r/PrintConfig.cpp`); the def map owns the default value object.
+
+```cpp
+def = this->add("brim_width", coFloat);
+def->label    = L("Brim width");          // row label; L() is an extraction marker (no-op)
+def->category = L("Support");             // per-object settings grouping (not the tab page)
+def->tooltip  = L("This is the distance from the model to the outermost brim line.");
+def->sidetext = L("mm");                  // unit
+def->min = 0; def->max = 100;             // Field clamps to these
+def->mode = comSimple;                    // visibility gate
+def->set_default_value(new ConfigOptionFloat(0.));
+```
+
+Enums need three parts: the `enum class` plus `CONFIG_OPTION_ENUM_DECLARE_STATIC_MAPS(Name)` in `PrintConfig.hpp`,
+a `static t_config_enum_values s_keys_map_Name` plus `CONFIG_OPTION_ENUM_DEFINE_STATIC_MAPS(Name)` in
+`PrintConfig.cpp`, and in the def `enum_keys_map = &ConfigOptionEnum<Name>::get_enum_values()` with parallel
+`enum_values` (serialized keys) and `enum_labels` (`L()` display labels) — see `wall_generator`
+(`PerimeterGeneratorType`).
+
+| Field | Meaning for the GUI |
+|---|---|
+| `type` | `coFloat/coFloats/coInt/coInts/coString/coStrings/coPercent(s)/coFloatOrPercent(s)/coBool(s)/coEnum(s)/coPoint(s)/…`; picks the `Field` when `gui_type` is `undefined`. |
+| `gui_type` | `GUIType {undefined, i_enum_open, f_enum_open, color, select_open, slider, legend, one_string, plugin_picker, plugin_config, printer_agent_select}`; checked first by `build_field`. `slider` is marked "currently unused" in `Config.hpp`. |
+| `gui_flags` | `"serialized"`: a vector edited as one `;`-separated string; `"show_value"`: show the value even when enum labels exist. |
+| `label` / `full_label` | `label` is the short row label (a sub-label inside a multi-option row). `full_label`, when set, names the setting on its own: sidebar search titles, the per-object "Add Settings" menu, the compare dialogs. The Speed Dial titles a setting with the label its row draws and keeps `full_label`/`label` only as a search alias (`ActionRegistry`). |
+| `category` | English group name for per-object settings (`SettingsFactory::get_bundle`, the settings menus, the ObjectList settings item) and the transfer view's fallback in `UnsavedChangesDialog`. Empty = left out of the ObjectList settings item and the "Add Settings" menus (the model tabs still show the key). Search uses the tab page title instead. |
+| `tooltip`, `sidetext` | Translated at display; `sidetext` is drawn inside most inputs (see [Field](#field-and-the-value-flow)). |
+| `min`, `max`, `max_literal` | `Field` clamps to `[min, max]` with "Value is out of range."; `max_literal` bounds the absolute (non-%) value of `coFloatOrPercent` keys whose `sidetext` contains `"mm "`. Both `min`/`max` bounded → "Range:" line in the tooltip. |
+| `mode` | `comSimple < comAdvanced < comExpert < comDevelop`; a row shows when its **first** option's mode ≤ the tab's mode. |
+| `nullable` | Vector values may hold nil ("N/A"); used by model-scope overrides. |
+| `multiline`, `full_width`, `is_code`, `height`, `width`, `readonly` | Text box shape (in em units for `height`/`width`); `is_code` sets `normal_font()` (not a monospace font, despite the `Config.hpp` comment) and adds the "Edit Custom G-code" button when the group has `edit_custom_gcode`; disabled control (`readonly`). |
+| `ratio_over` | For `coFloatOrPercent`: the key a percentage refers to. |
+| `aliases`, `shortcut` | Legacy names; one value expanding to several keys. |
+| `plugin_type` | Makes the option plugin-backed (`is_plugin_backed()`). |
+
+An unadorned `coBool` def becomes a checkbox with no GUI code at all.
+
+Pitfalls:
+- **Rule:** Give `coFloatOrPercent` defs a `sidetext` of the form `"mm or %"` / `"mm/s or %"` and a sensible
+  `max_literal`.
+  **Why:** `Field::get_value_by_opt_type` asks "Is it N% or N mm?" by matching the English `sidetext`: a unitless
+  value above `max` when it contains `"mm/s"`, above `max_literal` when it contains `"mm "` (only that form also
+  clamps literal values to `max_literal`); another unit text skips the check.
+  Cite: `Field::get_value_by_opt_type`.
+- **Rule:** Give every key that can be overridden per object a non-empty `category`.
+  **Why:** `is_improper_category` (`GUI_Factories.cpp`) drops empty categories (and `"Extruders"`/`"Wipe options"`
+  with one filament, `"Support material"` for parts), so the override never appears in the ObjectList settings item
+  and does not light the Objects switch (`ParamsPanel::notify_object_config_changed`).
+  Cite: `SettingsFactory::get_bundle`.
+
+## Config classes, preset lists and variants
+
+**Static config classes.** Every key that the slicing core reads is a member of a `PRINT_CONFIG_CLASS_DEFINE`
+block in `src/libslic3r/PrintConfig.hpp`:
+
+| Class | Scope | Overridable in model tabs |
+|---|---|---|
+| `PrintObjectConfig` | per object | object (`TabPrintObject`) |
+| `PrintRegionConfig` | per region | object, part (`TabPrintPart`), layer range (`TabPrintLayer`) |
+| `MachineEnvelopeConfig`, `GCodeConfig`, `PrintConfig` (derives from both) | global | no |
+| `SLA*Config` | SLA | — |
+
+`layer_height` is added for layer ranges, and the plate tab offers the fixed `plate_keys` list in `Tab.cpp`.
+
+**Preset option lists.** `src/libslic3r/Preset.cpp` lists which keys each preset type owns: `s_Preset_print_options`,
+`s_Preset_filament_options`, `s_Preset_printer_options` (+ `s_Preset_machine_limits_options` and the nozzle-sized
+`PrintConfigDef::extruder_option_keys()`, joined in `Preset::printer_options()`). `PresetBundle` builds each
+collection's default config from its list (`prints(Preset::TYPE_PRINT, Preset::print_options(), …)`), so the list
+decides what is saved, loaded, diffed, inherited and shown in the tab.
+
+### Per-extruder variant options
+
+Multi-extruder printers store some vectors once per extruder variant. A key joins one of the sets in
+`src/libslic3r/PrintConfig.cpp`: `print_options_with_variant`, `filament_options_with_variant`,
+`printer_options_with_variant_1` (one value per variant) or `printer_options_with_variant_2` (a normal/silent pair
+per variant, stride 2). Printer per-extruder keys sized to `nozzle_diameter` go in
+`PrintConfigDef::init_extruder_option_keys` (`m_extruder_option_keys`; a retract key also joins
+`m_extruder_retract_keys`, which is asserted sorted).
+
+GUI mechanics: the row is appended with index 0 (`append_single_option_line("outer_wall_speed", wiki, 0)`, field id
+`outer_wall_speed#0`). `Tab::switch_excluder` rewrites each group's `m_opt_map` index to the selected variant, so
+edits write `values[variant]`, and fills `Page::m_opt_id_map` (`"key#<variant>"` → shown field id).
+`Tab::get_config_manipulation` passes a variant index to `toggle_option`/`toggle_line`/`set_option_label` as
+`index + 256`; `Page::get_field`/`Page::get_line` see `>= 256` and translate through `m_opt_id_map`. The print-side
+variant speeds are nullable vectors (`nullable = true`, `ConfigOptionFloatsNullable`) so a model override can set
+one variant's element and leave the others nil (`TabPrintModel::on_value_change`); copy the declaration of an
+existing key in the same set.
+
+Pitfalls:
+- **Rule:** Add the key to the `Preset` list together with the def and the class member.
+  **Why:** the tab's config lacks the key, so `ConfigOptionsGroup::get_option` only prints
+  `No <key> in ConfigOptionsGroup config.` to stderr and the row's value read (`get_config_value`) dereferences a
+  missing option when the page builds [source].
+  Cite: `ConfigOptionsGroup::get_option`, `ConfigOptionsGroup::get_config_value`.
+- **Rule:** In `ConfigManipulation`, toggle variant keys with the variant index.
+  ```cpp
+  toggle_field("outer_wall_speed", have_perimeters);                 // Wrong: finds no field (the row's id is key#0)
+  toggle_field("outer_wall_speed", have_perimeters, variant_index);  // Right
+  ```
+  Cite: `ConfigManipulation::toggle_print_fff_options`, `Page::get_field`.
+
+## Tabs, pages and where they live
+
+**Classes.** `Tab : wxPanel` (`src/slic3r/GUI/Tab.hpp`) owns a `PresetCollection* m_presets`, the edited
+`DynamicPrintConfig* m_config`, its `Page`s and a `ConfigManipulation`. Concrete tabs: `TabPrint`, `TabFilament`,
+`TabPrinter`, and the model-scope `TabPrintModel` → `TabPrintPlate`, `TabPrintObject`, `TabPrintPart`,
+`TabPrintLayer`. `MainFrame::create_preset_tabs` creates them and `MainFrame::add_created_tab` calls
+`Tab::create_preset_tab()` (top bar + `build()`). `GUI_App::get_tab(type)` returns null until a tab is
+`completed()`; `get_plate_tab()`, `get_model_tab(part)`, `get_layer_tab()` reach the model tabs.
+
+**Declaring pages.** `TabX::build()` is declarative:
+
+```cpp
+auto page = add_options_page(L("Quality"), "custom-gcode_quality");      // English title, page icon
+auto optgroup = page->new_optgroup(L("Layer height"), L"param_layer_height");  // L"..." is a wide literal, not L()
+optgroup->append_single_option_line("layer_height", "quality_settings_layer_height");
+```
+
+`Page::new_optgroup(title, icon, noncommon_label_width, is_extruder_og)` creates a tab group
+(`ConfigOptionsGroup(..., is_tab_opt = true)`, or `ExtruderOptionsGroup`), records the page title and preset type
+for search (`set_config_category_and_type`), and installs the callbacks: `m_on_change` →
+`Tab::update_dirty()` + `Tab::on_value_change()` (called directly; deferring it re-runs `update()`),
+`m_get_initial_config` (selected preset), `m_get_sys_config` / `have_sys_config` (parent system preset). On
+`TabPrint` pages (model tabs included) `m_split_multi_line` stacks a multi-option row's fields vertically and `m_option_label_at_right`
+makes `OG_CustomCtrl` draw sub-labels to the right of the fields. `TabPrinter` creates its "Motion ability",
+"Multimaterial" and `"Extruder N"` pages with `add_options_page(..., is_extruder_pages = true)`, which does not
+append them to `m_pages`; the caller inserts each at its position.
+
+### Where the tabs live
+
+- **Process.** `TabPrint` and the model tabs sit on `MainFrame::m_param_panel`, a `ParamsPanel` whose top bar
+  (`get_top_panel()`) and body are reparented into the sidebar's scrolled panel in `Sidebar::Sidebar`: the top bar
+  above the object list, the body (the tab with its own `TabPresetComboBox`, `Tab::get_combo_box()`) below it.
+  Print parameters are therefore in the sidebar. `ParamsPanel::switch_to_global` / `switch_to_object` flip its
+  Global/Objects switch (`m_mode_region`).
+- **Filament and printer.** `TabFilament` and `TabPrinter` live on `ParamsDialog::panel()`, a second
+  `ParamsPanel` inside `ParamsDialog : DPIDialog`, created once with the plater as parent. `ParamsDialog::Popup()`
+  applies `UpdateDlgDarkUI`, reparents to the main frame on MSW, centres and `Show()`s it — modeless. A
+  `wxWindowDisabler(this)` created in its `wxEVT_SHOW` handler disables every other shown top-level window while it
+  is visible and is deleted on hide; the close handler validates (`Tab::validate_filament_temperature_pairs`, may
+  veto), hides, queues `EVT_MODIFY_FILAMENT` when a filament was being edited, and calls
+  `Sidebar::finish_param_edit()`. It never destroys the dialog, so the panel and its tabs are reused across opens.
+  `MainFrame::select_tab(wxPanel*)` given a `ParamsPanel` other than `m_param_panel` opens the dialog.
+  Modality mechanics: `references/windows-dialogs.md` §6.
+- **Sidebar map.** `Sidebar` (pimpl `Sidebar::priv`, `Plater.cpp`) holds the printer block (`combo_printer`,
+  nozzle/bed-type combos, `ExtruderGroup`s, sync buttons), the filament block (`combos_filament`, add/delete/edit,
+  flushing-volume button), the `ParamsPanel` top bar, the object-list block (the plate/object/part search bar,
+  `ObjectList`, `ObjectLayers`; `ObjectSettings` is created but not laid out under `NEW_OBJECT_SETTING`) and the
+  process `ParamsPanel`. There is no separate process combo
+  (`Sidebar::priv::combo_print` is never created). It owns the `Search::OptionsSearcher`.
+  `Sidebar::update_presets(type)` refreshes the combos after a preset change. Full component map:
+  `references/orca-architecture.md`.
+- **No quick-settings group.** `Sidebar::og_freq_chng_params()` returns null in Orca (the frequently-changed
+  parameters group is compiled out); the process tab itself is the sidebar's settings UI.
+
+Showing the tab of a preset type follows `PlaterPresetComboBox::switch_to_tab`:
+
+```cpp
+if (tab->GetParent() == wxGetApp().params_panel())
+    wxGetApp().mainframe->select_tab(TAB_ID_PREPARE);   // process: it is in the sidebar
+else {
+    wxGetApp().params_dialog()->Popup();                // filament/printer
+    tab->OnActivate();
+}
+```
+
+**Contract (wx).** `wxWindowDisabler` disables all top-level windows except the skipped one in its constructor and
+re-enables them in its destructor; it affects only windows shown and not already disabled at construction
+(`interface/wx/utils.h:59-69`, `:87-110`).
+
+Pitfalls:
+- **Rule:** Run post-edit work from the `ParamsDialog` close path (or the tab's value-change path), never after
+  `Popup()`.
+  ```cpp
+  wxGetApp().params_dialog()->Popup(); refresh_after_edit();   // Wrong: Popup() returns at once
+  // Right: react in the dialog's close handler / Sidebar::finish_param_edit / EVT_MODIFY_FILAMENT
+  ```
+  **Why:** the dialog is shown modeless and only emulates modality with `wxWindowDisabler`; the main frame stays
+  disabled until it hides.
+
+## OptionsGroup, Option and Line
+
+**`Option`** (`OptionsGroup.hpp`) is a *copy* of the def plus the field id (`opt_id`, `"key"` or `"key#idx"`) and
+an optional `side_widget`. **`Line`** holds `label`, `label_tooltip`, `label_path` (wiki path), one or more
+`Option`s, and optional widgets: `widget` (replaces the fields), `append_widget` extras, `near_label_widget`, plus
+`full_width`, `toggle_visible`, `undo_to_sys`. `Line(label, tooltip)` applies `_()` to both, so pass English `L()`
+strings. `Line()` is a separator (`OptionsGroup::append_separator()`).
+
+`ConfigOptionsGroup` binds a group to a `DynamicPrintConfig` (or a `ModelConfig`, then `ModelConfig::touch()` runs
+after each change). Its API:
+
+- `get_option(key, idx = -1)` → `Option` with id `key` or `key#idx`; records `m_opt_map[id] = {key, idx}`; for tab
+  groups registers the key in the search index (see [Search](#search-index-registration)).
+- `append_single_option_line(key, wiki_path = "", idx = -1)` = `get_option` + `create_single_option_line` (label
+  `_(label)`, tooltip from `get_formatted_tooltip_text`) + `append_line`.
+- `append_single_option_line(const Option&, wiki_path)` appends a modified copy:
+
+```cpp
+Option option = optgroup->get_option("small_area_infill_flow_compensation_model");
+option.opt.full_width = true; option.opt.is_code = true; option.opt.height = 15;   // changes this row only
+optgroup->append_single_option_line(option, "quality_settings_wall_and_surfaces#small-area-flow-compensation");
+```
+
+**Multi-option rows** build the `Line` by hand (as the "Overhang speed" and "Bridge" rows in `TabPrint::build` and
+"Recommended nozzle temperature" in `TabFilament::build`):
+
+```cpp
+Line line = { L("Bridge"), L("Set speed for external and internal bridges") };
+line.append_option(optgroup->get_option("bridge_speed", 0));
+line.append_option(optgroup->get_option("internal_bridge_speed", 0));
+optgroup->append_line(line);
+```
+
+The row's mode is its first option's `mode`; each field gets a sub-label from its own `label`.
+
+**Wiki link.** A non-empty `label_path` makes the row label a link: hovering highlights it and a click calls
+`OptionsGroup::launch_browser` → `https://www.orcaslicer.com/wiki/<path>` with the path appended verbatim, so write
+anchors as the wiki slugs them (`page#lowercase-hyphenated`). `append_line` also records the path for the Speed
+Dial's "open wiki" action.
+
+**Groups outside tabs.** A `ConfigOptionsGroup` created without `is_tab_opt` (`PhysicalPrinterDialog`,
+`BedShapeDialog`) draws a `LabeledStaticBox` with a `wxFlexGridSizer` of `wxStaticText` labels and plain sizer
+layout, no `OG_CustomCtrl`, no search registration. The owner calls `activate()`, adds `optgroup->sizer`, sets
+`m_on_change`, and loads values (`reload_config()` / `set_value`).
+
+### Custom widgets on a line
+
+`Tab::create_line_with_widget(optgroup, key, wiki_path, widget)` makes a row whose `widget` (a
+`std::function<wxSizer*(wxWindow*)>`) replaces the field — bed shape (`printable_area`), `compatible_printers`,
+`compatible_prints`, `filament_ramming_parameters`. It presets white-bullet undo icons and the default label colour.
+`Line::full_width` with `widget`/extra widgets builds a description row that `append_line` does not register as
+options. `near_label_widget` draws a window before the label (in tab groups `activate_line` creates it as a child of
+the `OG_CustomCtrl`, which positions it); the group's `rescale_near_label_widget` / `rescale_extra_column_item`
+callbacks rescale them on DPI change.
+
+Pitfalls:
+- **Rule:** When a key is edited by a custom widget, add it to the name branches in `Tab::decorate` (the
+  `option_without_field` keys), `Tab::on_roll_back_value` (keyed by group title, then `load_key_value` to refresh
+  the widget), `ConfigOptionsGroup::back_to_config_value` and, for a vector key stored whole,
+  `Tab::options_list_storage_key`.
+  **Why:** `decorate` looks the key up with `get_field()` and skips it when there is none, so the row's modified
+  colour and undo/lock icons never update; the revert paths have no field to push the restored value into, so the
+  widget keeps showing the old value [source].
+  Cite: `Tab::decorate`, `Tab::on_roll_back_value` (`printable_area`, `compatible_prints`, `compatible_printers`).
+
+## OptionsGroup::build_field
+
+`OptionsGroup::build_field(id, def)` switches on `gui_type` first, then on `type`:
+
+| `gui_type` | Field |
+|---|---|
+| `select_open` | `Choice` (read-only) |
+| `i_enum_open`, `f_enum_open` | `Choice` (editable: any value, enum entries as presets) |
+| `color` | `ColourPicker` |
+| `slider` | `SliderCtrl` |
+| `legend` | `StaticText` |
+| `one_string` | `TextCtrl` (vector edited as one string) |
+| `plugin_picker` / `plugin_config` / `printer_agent_select` | `PluginField` / `PluginConfigField` / `PrinterAgentChoice` (Orca) |
+
+| `type` (when `gui_type` is `undefined`) | Field → widget |
+|---|---|
+| `coFloat(s)`, `coPercent(s)`, `coFloatOrPercent(s)`, `coString(s)` | `TextCtrl` → `::TextInput` (raw `wxTextCtrl` when `multiline`) |
+| `coBool(s)` | `CheckBox` → `::CheckBox` |
+| `coInt(s)` | `SpinCtrl` → `SpinInput` |
+| `coEnum(s)` | `Choice` → `::ComboBox` (`choice_ctrl`) |
+| `coPoint(s)` | `PointCtrl` → two `::TextInput` |
+| `coNone` | nothing |
+| anything else (`coPoint3`, `coIntsGroups`, …) | throws `Slic3r::LogicError("This control doesn't exist till now")` |
+
+It then wires the field: `m_on_change` / `m_on_kill_focus` → the group (ignored while the group is `m_disabled`),
+`m_back_to_initial_value` / `m_back_to_sys_value`, the edit button for `is_code` options when the group has
+`edit_custom_gcode`, the plugin picker and the preset type of a `PluginConfigField`. Widget event contracts
+(`wxEVT_TOGGLEBUTTON` for `::CheckBox`, commit events of `SpinInput`): `references/controls-dataview.md`
+§Field widgets, `references/orca-widgets.md`.
+
+**`Choice` specifics** (`Choice::BUILD`): read-only for plain enums, `select_open` and keys with a registered
+`DynamicList`, editable (`wxTE_PROCESS_ENTER`) for open enums; entries are `_(enum_labels[i])`, or untranslated `enum_values` when there are
+no labels; an entry gets an icon when `resources/images/param_<enum_value>.svg` exists. Lists computed at runtime
+(filament pickers) register a `DynamicList` with `Choice::register_dynamic_list(key, list)` (done in
+`Sidebar::Sidebar` for `support_filament`, `sparse_infill_filament_id`, …). A tab may narrow the offered entries per
+state by rewriting the field's `m_opt.enum_values/enum_labels` and the combo items, as `TabPrint::toggle_options`
+does for `support_style`.
+
+Pitfall:
+- **Rule:** A new option type or presentation needs a `gui_type` (or a custom-widget line), not a new `type` case
+  left unmapped.
+  **Why:** an unmapped type throws from `build_field` when the page activates, aborting the page build.
+
+## Field and the value flow
+
+`Field` (`src/slic3r/GUI/Field.hpp`, abstract, `Slic3r::GUI`) keeps a copy of the def (`m_opt`), the id
+(`m_opt_id`), the vector index (`m_opt_idx`, parsed from `#idx` in `PostInitialize` for most vector types) and the
+current `boost::any m_value`. Virtuals: `BUILD()`, `set_value(any, change_event)`, `get_value()`, `enable()`,
+`disable()`, `msw_rescale()`, `sys_color_changed()` (MSW only: `UpdateDarkUI` on the window), `propagate_value()`;
+`toggle(en)` enables only when not `readonly`. Subclasses: `TextCtrl`, `CheckBox`, `SpinCtrl`, `Choice`,
+`ColourPicker`, `PointCtrl`, `StaticText`, `SliderCtrl`, `PrinterAgentChoice`, `PluginField`,
+`PluginConfigField`. `Field::Create<T>(parent, def, id)` constructs, runs `PostInitialize()` (em unit,
+`parent_is_custom_ctrl`, `BUILD()`, readonly → `disable()`, Ctrl+1..4 tab shortcuts on the window) and returns a
+`std::unique_ptr<Field>` owned by `OptionsGroup::m_fields`. The subclass `CheckBox` shadows the global `::CheckBox`
+widget inside `Slic3r::GUI` wherever `Field.hpp` is visible, which is why widget code there writes `::CheckBox`
+(and qualifies `::TextInput` / `::ComboBox` the same way) (`references/orca-widgets.md`).
+
+`Field` and `Line` derive from `UndoValueUIManager`: the per-row "revert to system" (lock) and "revert to saved"
+(undo arrow) icons, their tooltips and the modified label colour (`#F1754E` by default, `label_clr_modified` in
+app config) come for free; `Tab::update_changed_ui` / `Tab::decorate` set them from the option status.
+
+**Value types in the `boost::any`** (`Slic3r::GUI::change_opt_value`, `GUI.cpp`):
+
+These are the config-side values that `Field::get_value()`, `on_change_OG` and `Tab::on_value_change` carry.
+`Field::set_value` takes the display form that `ConfigOptionsGroup::get_config_value` produces instead: a
+`wxString` for float, percent, float-or-percent and string fields, `bool`/`unsigned char` for checkboxes, `int` for
+ints and enums, `Vec2d` for points.
+
+| Option type | `any` holds |
+|---|---|
+| `coFloat(s)`, `coPercent(s)` | `double` |
+| `coFloatOrPercent(s)`, `coString`, single `coStrings` element | `std::string` (`"serialized"` `coStrings`: the whole `;`-joined string; `compatible_printers`/`compatible_prints`: `std::vector<std::string>`) |
+| `coInt(s)`, `coEnum(s)` | `int` |
+| `coBool` | `bool` |
+| `coBools` (incl. nullable) | `unsigned char` (`ConfigOptionBoolsNullable::nil_value()` = nil) |
+| `coPoint` / `coPoints` element | `Vec2d`; whole `printable_area`-style lists: `std::vector<Vec2d>` |
+
+A wrong type throws `boost::bad_any_cast` inside `change_opt_value`, which logs "Internal error when changing value
+for <key>" and leaves the config unchanged.
+
+**Commit points.** Text fields commit on Enter or kill focus (`propagate_value`), not per keystroke; `TextCtrl`
+ignores a kill focus raised while its Enter commit is still running (`EnterPressed` guard, e.g. a dialog the commit
+opens). `Choice` commits on `wxEVT_COMBOBOX` (editable: also Enter/kill focus); `CheckBox` on `wxEVT_TOGGLEBUTTON`;
+`SpinCtrl` on `wxEVT_SPINCTRL`, Enter and kill focus (skipping the first kill focus after an Enter). Validation
+(`Field::get_value_by_opt_type`) clamps to the def's limits and reports through `show_error` (asynchronous).
+
+**Flow after a commit.** `Field::on_change_field` (no-op while `m_disable_change_event`) → `OptionsGroup::on_change_OG`
+→ `ConfigOptionsGroup::on_change_OG` (resolves `key#idx` through `m_opt_map`, `change_opt_value` on the group's
+config, `ModelConfig::touch()` for model configs) → group `m_on_change` → `Tab::update_dirty()` +
+`Tab::on_value_change()` (key-specific branches, then `update()`, `Page::update_visibility`, `Layout()`) →
+`TabX::update()` (in `TabPrint::update`: `ConfigManipulation::update_print_fff_config`, then, when the update counter
+`m_update_cnt` returns to zero, `toggle_options()`, the ObjectList settings refresh and `MainFrame::on_config_changed`
+→ `Plater::on_config_change`).
+Revert clicks go `OG_CustomCtrl::OnLeftDown` → `ConfigOptionsGroup::back_to_initial_value` / `back_to_sys_value`.
+
+Pitfalls:
+- **Rule:** Update a field from code with `set_value(value, false)`; to push a programmatic value into the config,
+  follow it with `field_changed()` (or `propagate_value()`).
+  **Why:** `set_value` only brackets the widget update with `m_disable_change_event = !change_event`, so the flag
+  decides whether events the setter itself emits (e.g. the `wxEVT_TEXT` of `SliderCtrl`'s text box) reach
+  `on_change_field`; where a setter does emit, `true` re-enters `on_value_change` → `update()`. Most Orca widget
+  setters emit nothing (`::ComboBox::SetValue`/`SetSelection`, `::CheckBox::SetValue`), so `set_value(v, true)`
+  alone usually leaves the config unchanged [source].
+  ```cpp
+  m_optgroup->set_value("print_host", new_url, true);     // Wrong: the widget shows it, the config is unchanged
+  m_optgroup->set_value("print_host", new_url, false);    // Right: show it ...
+  m_optgroup->get_field("print_host")->field_changed();   // ... then commit through the group
+  ```
+  Cite: `PhysicalPrinterDialog::build_printhost_settings`, `Tab::on_value_change` (`set_value` + `propagate_value`).
+- **Rule:** Implement `msw_rescale()` in a new `Field` by calling `Field::msw_rescale()` first (refreshes
+  `m_em_unit`), then rescaling the widget (`Rescale()`), and size controls in em units. DPI fan-out:
+  `references/dpi-bitmaps-fonts.md`.
+
+## Field control pooling
+
+Field controls are recycled, not destroyed. `Builder<T>::build(parent, args...)` (`Field.cpp`) takes a window from
+its pool when one exists (`Reparent(parent)`, `Enable()`, `Show()`) and otherwise constructs `T(parent, args...)` and
+stores the pool pointer in the window's client data. When a page is cleared (`OptionsGroup::clear`), each field
+window goes to `free_window`:
+
+- non-GTK: unbind every dynamic handler whose id is a single explicit id (`m_id != wxID_ANY && m_lastId ==
+  wxID_ANY`) on the window and on its `wxTextCtrl` children, hide, clear the containing sizer, reparent to the main
+  frame, push back into the pool named by the client data;
+- GTK: `delete` the window.
+
+`GUI_App::recreate_GUI` calls `switch_window_pools()` (fresh pools for the new frame) and releases the old pools
+when the old frame is destroyed (`release_window_pools()` from a client object on the old frame).
+
+The unbinding walks `wxEvtHandler::GetFirstDynamicEntry/GetNextDynamicEntry`, which wx marks "for internal use
+only" (`include/wx/event.h:4027-4033`), and unbinds each entry by its stored functor pointer, which sidesteps
+"functors are compared by their address" (`interface/wx/event.h:967-970`) [source]. `Bind`'s `id` defaults to
+`wxID_ANY` (`interface/wx/event.h:913-916`); the widgets' own internal handlers are bound that way, which is what
+keeps them alive across reuse.
+
+```cpp
+// Right: shape of a Field::BUILD
+static Builder<::CheckBox> builder;                  // one static builder per construction style
+auto temp = builder.build(m_parent);                 // may be a reused window
+temp->SetValue(check_value);                         // re-set every property you rely on
+temp->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { on_change_field(); e.Skip(); },
+           temp->GetId());                           // explicit id: unbound by free_window
+temp->SetToolTip(get_tooltip_text(check_value ? "true" : "false"));
+window = temp;
+```
+
+Pitfalls:
+- **Rule:** Bind every `Field` handler with the control's id.
+  **Why:** an id-less `Bind` survives `free_window`; when the pooled control is reused by another field, the old
+  lambda still fires with a dangling `this` (the old `Field` is gone) — a use-after-free on MSW/macOS — and one more
+  copy of the handler accumulates per reuse. GTK deletes instead, so the bug does not reproduce there.
+  ```cpp
+  temp->Bind(wxEVT_TOGGLEBUTTON, [this](auto& e) { on_change_field(); });                 // Wrong
+  temp->Bind(wxEVT_TOGGLEBUTTON, [this](auto& e) { on_change_field(); }, temp->GetId());  // Right
+  ```
+  Cite: `free_window`, `CheckBox::BUILD`.
+- **Rule:** Bind with the id only events the widget sends with its id.
+  **Why:** the id filter must match the event id. `::ComboBox` sends `wxEVT_COMBOBOX` with its id, and `::TextInput`
+  re-sends `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` with the wrapper's id, but `wxEVT_COMBOBOX_DROPDOWN/CLOSEUP` are
+  built as `wxCommandEvent e(type)` (id 0: `interface/wx/event.h:2137`), and an entry bound with one id matches
+  only an equal event id (`src/common/event.cpp:1454-1457`) [source], so an id-filtered bind never fires — and an
+  unfiltered one is never unbound. `Choice::BUILD`'s own `m_is_dropped` binds are such dead binds. Query
+  `ComboBox::is_drop_down()` instead of tracking those events.
+  Cite: `ComboBox::ComboBox` (`EVT_DISMISS` lambda), `ComboBox::mouseDown`, `ComboBox::keyDown`,
+  `ComboBox::ForceDropdownOpen`, `Choice::BUILD`.
+- **Rule:** Keep one `static Builder<T>` per distinct constructor style, and re-apply size, label, value, colours
+  and tooltip in `BUILD()`.
+  **Why:** a reused window ignores the new constructor arguments (style, size, id, label) — `Choice::BUILD` keeps
+  separate builders for editable and `wxCB_READONLY` combos for this reason.
+- **Rule:** Do not use `SetClientData` on a pooled control; it holds the pool pointer.
+
+**Contract (wx).** `Reparent` removes the window from its parent and inserts it into another; a notebook page must be
+removed from its book first (`interface/wx/window.h:731-742`).
+
+## Lazy building and OG_CustomCtrl
+
+**Lazy fields.** Rows are declared at tab build time; controls are created only when a page activates.
+`Tab::activate_selected_page` → `Page::activate` → `Page::activate_group` per group (`OptionsGroup::activate` →
+`activate_line` → `build_field`; then `update_visibility`, `reload_config`), followed by `update_changed_ui()`,
+`toggle_options()` and `update_visibility()`. Switching pages clears the other pages' controls back to the pool
+(`Tab::update_current_page_in_background` → `Page::clear`). The idle prebuild builds the selected settings page one
+option group per slice (`Page::build_step`, `Tab::page_build_step`, `ParamsPanel::settings_page_prebuild()`; design
+in `docs/HLSD/deferred-page-construction.md`, mechanics in `references/orca-architecture.md`). On GTK the page view is
+hidden while a page builds, because GTK crashes when it desensitizes a multi-line text view built on screen and hidden
+before its first size allocation (`Tab::activate_selected_page`). Building can be cancelled: `activate(throw_if_canceled)`
+throws `UIBuildCanceled`, and the group clears itself.
+
+Consequences: `Tab::get_field` / `Page::get_field` return null for any key not on the built active page;
+`Tab::toggle_option` acts only on `m_active_page`; `Tab::toggle_line` and `Tab::set_option_label` write
+`Line::toggle_visible` / `Line::label` on **every** page, so they persist and reach the search titles before a page
+is ever shown.
+
+**`OG_CustomCtrl`** (`OG_CustomCtrl.hpp/.cpp`, a `wxPanel`) hosts the fields of a tab group (`m_use_custom_ctrl`):
+`activate_line` creates it with the first line and fields are parented to it. It paints labels (with the label
+colour and blinking search highlight), sub-labels, sidetext of fields that do not combine it, the separator lines and
+the undo/lock/edit icons in `OnPaint` (`CtrlLine::render`), positions field windows itself
+(`correct_window_position`, `CtrlLine::correct_items_positions`; MSW re-fixes positions in a `CallAfter` after
+`Page::activate`), shows/hides fields per line in `CtrlLine::update_visibility` (`toggle_visible && first option mode
+<= mode`), and handles clicks (`OnLeftDown`: wiki link, revert to saved, revert to system, edit button).
+
+Pitfall:
+- **Rule:** Null-check every `get_field()` and never cache `Field*` across page switches.
+  ```cpp
+  m_active_page->get_field("support_style")->m_opt;             // Wrong: null when not on this page
+  if (auto f = dynamic_cast<Choice*>(m_active_page->get_field("support_style"))) { /* … */ }  // Right
+  ```
+  **Why:** the field object is destroyed with its page's controls; the window behind it is pooled for another key.
+
+## ConfigManipulation: toggles and fix-ups
+
+`ConfigManipulation` (`ConfigManipulation.hpp/.cpp`) is UI-agnostic dependency logic with two roles:
+
+1. **Value fix-ups** — `update_print_fff_config(config, is_global_config, is_plate_config)` (and the filament/printer
+   `check_*` helpers) detect invalid combinations, warn with `MessageDialog`, and write corrections through
+   `apply(config, &new_conf)`, which copies the diff and calls the tab's `load_config` callback (`update_dirty()`,
+   `reload_config()`, `update()`).
+2. **Visibility** — `toggle_print_fff_options(config, variant_index, is_global_config)` calls `toggle_field` (grey
+   out, → `Tab::toggle_option` → `Field::toggle`), `toggle_line` (hide the row, → `Tab::toggle_line`) and
+   `set_option_label` (rename a row at runtime, e.g. `brim_width` → "Brim ear radius").
+
+`Tab::get_config_manipulation()` builds the callbacks (variant index → `+256`, see [Variants](#per-extruder-variant-options));
+`TabX::toggle_options()` calls the `toggle_*` function and adds tab-local tweaks. They run on every page activation,
+after every `update()`, and after a variant switch.
+
+```cpp
+// fix-up shape (update_print_fff_config)
+if (config->opt_float("layer_height") < EPSILON) {
+    MessageDialog dialog(m_msg_dlg_parent, _L("Layer height too small\nIt has been reset to 0.2"), "", wxICON_WARNING | wxOK);
+    DynamicPrintConfig new_conf = *config;
+    is_msg_dlg_already_exist = true;           // ShowModal's loop re-enters update() (field kill focus)
+    dialog.ShowModal();
+    new_conf.set_key_value("layer_height", new ConfigOptionFloat(0.2));
+    apply(config, &new_conf);
+    is_msg_dlg_already_exist = false;
+}
+// toggle shape (toggle_print_fff_options)
+bool have_infill = config->option<ConfigOptionPercent>("sparse_infill_density")->value > 0;
+toggle_line("infill_combination_max_layer_height", config->opt_bool("infill_combination") && have_infill);
+```
+
+Pitfalls:
+- **Rule:** Guard every modal fix-up with `is_msg_dlg_already_exist` and write values only through `apply()`.
+  **Why:** `ShowModal` runs a nested event loop; focus leaving the edited field commits it again
+  (`propagate_value` on kill focus) and re-enters `update()` — the guard exists "to except the duplicate call of
+  the update() after dialog->ShowModal()". Without it the dialog repeats; a direct `set_key_value` on the tab config
+  skips `load_config`, leaving fields and dirty state stale. Modality rules: `references/windows-dialogs.md`.
+- **Rule:** Hide with `toggle_line`, grey out with `toggle_field`; do not call `Show()` on field windows.
+  **Why:** `OG_CustomCtrl` re-applies `toggle_visible` and mode on every `update_visibility`, and only `Line` state
+  survives page rebuilds and feeds the Speed Dial (`Tab::setting_row_state`).
+- **Rule:** Gate rules that only make sense for the global preset on `is_global_config`.
+  **Why:** the model tabs run the same `update_print_fff_config` / `toggle_print_fff_options` on an object's config
+  with `is_global_config == false` (`m_type < Preset::TYPE_COUNT` in `TabPrint`); see
+  `toggle_line("flush_into_objects", !is_global_config)` and the global-only support checks.
+
+## Search index registration
+
+`Sidebar` owns `Search::OptionsSearcher searcher`; its `Search::SettingsIndex` (`SettingsIndex.hpp`) is reached as
+`wxGetApp().sidebar().settings_index()`. Registration is automatic for tab rows:
+
+- `ConfigOptionsGroup::get_option` → `settings_index().add_key(opt_id, type, group title, page title, group icon)`
+  — **only when `m_use_custom_ctrl`** (tab groups);
+- `OptionsGroup::append_line` → `set_path(opt_id, type, label_path)` and `set_line_label(...)` with the label the
+  row draws (`Search::compose_display_label`: row label, or "row – sub-label" for multi-option rows).
+
+`SettingsIndex::apply/init` → `append_options` then builds two views from the tab config: `options()` filtered by
+mode (sidebar search, `SearchDialog`) and `all_options()` for every mode (the Speed Dial, `ActionRegistry`). An
+option enters only if its group and category are non-empty and it has a label (`full_label`, else `label`); vector
+keys of print/printer presets get one entry per element (`key#i`), filament variant keys `key#0`. Each entry stores the
+English and translated label/group/category, so search matches either. `UnsavedChangesDialog` and `DiffPresetDialog`
+name settings from the same index and skip a changed key the index lacks; only the extruder-transfer view
+(`UnsavedChangesDialog::update_tree(type, config, from, to)`) falls back to the def's label/category, then "Others".
+
+`Sidebar::jump_to_option(key, type, category)` → (model tab if it has the key, else switch to global) →
+`Tab::activate_option`, which selects the page by translated category, focuses the field and blinks it
+(`get_custom_ctrl_with_blinking_ptr`). `Tab::apply_searcher()` refreshes the index for one tab.
+
+Pitfalls:
+- **Rule:** Create tab groups with a non-empty English title; a key that should be findable must be on a tab.
+  **Why:** `append_options` skips entries with an empty group or category, so `page->new_optgroup("")` rows and
+  dialog-only keys are invisible to search and the Speed Dial, and their changes are left out of the unsaved-changes
+  and compare dialogs.
+- **Rule:** Keep `is_tab_opt = false` (the default) for `ConfigOptionsGroup`s outside tabs; the one-argument
+  `ConfigOptionsGroup(parent)` constructor sets it to `true`.
+  **Why:** a custom-ctrl group registers its keys with the index under its `config_type()`; outside a tab that type
+  and category are not set up.
+
+## Localization of option definitions
+
+In `PrintConfig.cpp`, `L(s)` is `(s)` and `L_CONTEXT(s, ctx)` returns `s` (`libslic3r/I18N.hpp`): they only mark the
+string for xgettext. The defs live in the static `print_config_def`, built before the GUI installs its translate
+callback (`Slic3r::I18N::set_translate_callback`) and reused across language switches, so defs, page titles and group
+titles hold English and the GUI translates at display time:
+
+| String | Translated in |
+|---|---|
+| Row label | `OptionsGroup::create_single_option_line` (`_(label)`) and `Line`'s constructor |
+| Sub-labels of multi-option rows | `OG_CustomCtrl` / `activate_line` (`_(label)`; labels exactly `"Top"`/`"Bottom"` in the `"Layers"` context) |
+| Tooltip | `get_formatted_tooltip_text` (`Field.cpp`): `_(tooltip)` + "parameter name: `key[idx]`" + for keys in the selected print preset's parent, "Default: value+sidetext" and, when `min`/`max` are both bounded, "Range: [min, max]" |
+| Sidetext | `Field::BUILD` (`_L(sidetext)`, drawn inside the input when `m_combine_side_text`) or `OG_CustomCtrl::CtrlLine::render` / `activate_line` (`_(sidetext)`) |
+| Enum labels | `Choice::BUILD` (`_(enum_labels[i])`) |
+| Page titles | `Tab::translate_category` (`"Extruder N"` composed as `_("Extruder")` + N, or "Left/Right Extruder" on BBL printers) |
+| Group titles | `OptionsGroup::activate` (`_(title)`) |
+| Category (per object) | ObjectList settings item and menus (`_(category)`) |
+
+Translator workflow and catalog rules: `references/strings-i18n-files.md` and the AGENTS.md localization section.
+
+**Contract (wx).** A message with `msgctxt` is found only when the lookup passes the same context
+(`interface/wx/translation.h:594-603`); the catalog keys context entries as `context + '\x04' + msgid`, so a
+context-less lookup never sees them (`src/common/translation.cpp:1154-1157`) [source].
+
+Pitfalls:
+- **Rule:** Mark def strings with `L()`; never `_L()`/`_()` in `PrintConfig.cpp` or in tab titles.
+  ```cpp
+  def->label = _L("Brim width");   // Wrong: _L is GUI-only; a def is built once, before any language is set
+  def->label = L("Brim width");    // Right: English marker, translated where it is displayed
+  ```
+  **Why:** a translated tab or group title also breaks the English keys below (`translate_category`, the search
+  index); `PrintConfig.cpp`'s `_()` (`Slic3r::I18N::translate`) runs at static init with no callback installed.
+- **Rule:** Do not expect `L_CONTEXT` in a def to select a context translation.
+  **Why:** the display paths call `_()`/`_L()` without context, so `L_CONTEXT("s", "second")` sidetext shows the
+  context-less `"s"` entry and the translator's context entry is never used; only the hard-coded `"Top"`/`"Bottom"`
+  `"Layers"` labels are looked up with context. To disambiguate, use a distinct English string or add a context
+  lookup in the GUI.
+- **Rule:** Keep `category`, page and group titles in English and stable.
+  **Why:** they are keys: page titles match tab items through `translate_category`, categories key
+  `SettingsFactory::CATEGORY_ICON` (unknown → no icon) and the `*_CATEGORY_SETTINGS` maps, and the index stores the
+  English form for search.
+
+## Per-object, part, layer and plate overrides
+
+The model tabs reuse the process tab: `TabPrintModel::build()` runs `TabPrint::build()`, inserts a "Frequent" page
+(`layer_height`, `sparse_infill_density`, `wall_loops`, `enable_support`), removes every option not in `m_keys`
+(`remove_option_if`), and drops empty groups and pages. `m_keys` is `Preset::print_options()` ∩:
+
+| Tab | Keys |
+|---|---|
+| `TabPrintObject` | `PrintObjectConfig().keys()` ∪ `PrintRegionConfig().keys()` |
+| `TabPrintPart` | `PrintRegionConfig().keys()` |
+| `TabPrintLayer` | `layer_height` + `PrintRegionConfig().keys()` |
+| `TabPrintPlate` | `plate_keys` (`Tab.cpp`), appended whole, so plate-only keys such as `curr_bed_type` survive the intersection |
+
+So any print setting added to `TabPrint::build()` and to `PrintObjectConfig`/`PrintRegionConfig` is overridable
+with no extra GUI code. Selecting an object, part, layer range or plate in `ObjectList` runs
+`ObjectSettings::update_settings_list` (`GUI_ObjectSettings.cpp`, `NEW_OBJECT_SETTING` path), which hands the
+selected `ModelConfig`s to the tabs with `TabPrintModel::set_model_config`; `TabPrintModel::on_value_change` writes
+only the edited key into each `ModelConfig` (nil elements for untouched variants) after a `take_snapshot`. The
+`ObjectList` shows an `itSettings` child grouped by `def->category` (`SettingsFactory::get_bundle`), and
+`ParamsPanel::notify_object_config_changed` highlights the Objects switch when any object or part has overrides.
+ObjectList and its data model: `references/controls-dataview.md`.
+
+`SettingsFactory` (`GUI_Factories.hpp/.cpp`):
+- `get_options(is_part)` — `PrintRegionConfig` keys, plus `PrintObjectConfig` keys for objects (SLA: object keys
+  minus `layer_height`); feeds the "Add Settings" menus (`MenuFactory::append_menu_item_settings`) and
+  `get_bundle`.
+- `OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS` — curated category → `std::vector<SimpleSettingData>`
+  (`{name, label, priority}`, `name` = the option key) lists for
+  the Object Table dialog (`ObjectTableDialog`, `ObjectTableSettings` via `get_visible_options` /
+  `get_all_visible_options`). They do not decide whether a key can be overridden.
+- `CATEGORY_ICON` — category → icon name.
+
+## Checklist: adding a setting
+
+1. **`src/libslic3r/PrintConfig.cpp`** — the `def = this->add("my_option", coX)` block in the right
+   `init_*_params()` (label, category, tooltip, sidetext, min/max, mode, default; `L()` strings; enum maps if an enum).
+2. **`src/libslic3r/PrintConfig.hpp`** — `((ConfigOptionX, my_option))` in the `PRINT_CONFIG_CLASS_DEFINE` block of
+   its scope (`PrintObjectConfig` / `PrintRegionConfig` / `PrintConfig` / `GCodeConfig` / `MachineEnvelopeConfig`).
+3. **`src/libslic3r/Preset.cpp`** — append the key to `s_Preset_print_options` / `s_Preset_filament_options` /
+   `s_Preset_printer_options` / `s_Preset_machine_limits_options`. Per-variant keys also go into the
+   `*_options_with_variant` sets in `PrintConfig.cpp`; nozzle-sized printer keys into
+   `PrintConfigDef::init_extruder_option_keys`.
+4. **`src/slic3r/GUI/Tab.cpp`** — `optgroup->append_single_option_line("my_option", "wiki_page#anchor")` on the right
+   page and group of `TabPrint::build` / `TabFilament::build` / `TabPrinter::build_fff` (index `0` for variant keys).
+   That alone yields the widget, tooltip, undo/system decoration, dirty tracking, search and Speed Dial entries, and
+   (for object/region keys) the model-tab rows.
+5. **Slicing invalidation** — add the key to the right step list in `Print::invalidate_state_by_config_options` or
+   `PrintObject::invalidate_state_by_config_options`; a key in neither falls through to `invalidate_all_steps()`
+   (correct, but every edit reslices everything).
+6. **Optional GUI:** dependencies in `ConfigManipulation::toggle_*_options` / `update_*_config` (+ `TabX::toggle_options`);
+   Object Table exposure in `SettingsFactory::OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS`; a runtime list
+   via `Choice::register_dynamic_list`; enum icons `resources/images/param_<value>.svg`; a custom widget row via
+   `Tab::create_line_with_widget` plus the name branches in [Custom widgets](#custom-widgets-on-a-line).
+7. **Compatibility** — a renamed or removed key needs `PrintConfigDef::handle_legacy` (old key/value → new;
+   `PrintConfigDef::handle_legacy_composite` when the migration needs other keys of the loaded config); the
+   default must keep existing profiles and 3MF projects slicing as before; profile edits follow the `orca-profiles`
+   skill (vendor `version` bump).

.claude/skills/orca-wxwidgets/references/orca-widgets.md

@@ -0,0 +1,858 @@
+# Orca widget library
+
+The owner-drawn widgets in `src/slic3r/GUI/Widgets/`: which raw wx control each replaces, constructors, the events
+each emits and where to bind them, style APIs, and the per-widget quirks behind real bugs. Read it before adding or
+changing a control in Orca UI, or when a widget event "never fires", fires twice, or a widget looks wrong after a
+DPI or theme change. Writing a *new* widget (StaticBox/StateHandler/render/Rescale) is in
+`references/painting-custom-widgets.md`; `StateColor` semantics and the dark map in
+`references/colours-dark-mode.md §StateColor`; the `Label` font table in `references/dpi-bitmaps-fonts.md`; raw wx
+controls in `references/controls-dataview.md`.
+
+Contents: [Rules](#rules) · [Why the library exists](#why-the-library-exists) ·
+[Namespaces](#namespaces-and-the-checkbox-clash) · [Catalog](#catalog) · [Event semantics](#event-semantics) ·
+[Custom vs raw](#custom-vs-raw) · [Shared lifecycle rules](#shared-lifecycle-rules) · [Button](#button) ·
+[DialogButtons](#dialogbuttons) · [Label and HyperLink](#label-and-hyperlink) · [CheckBox](#checkbox-and-radiobox) ·
+[SwitchButton family](#switchbutton-family) · [RadioGroup](#radiogroup) · [TextInput](#textinput) ·
+[ComboBox and DropDown](#combobox-and-dropdown) · [SpinInput](#spininput-and-tempinput) · [Tab systems](#tab-systems) ·
+[StaticBox, LabeledStaticBox, StaticLine](#staticbox-labeledstaticbox-staticline) · [ProgressBar](#progressbar) ·
+[ScrolledWindow](#scrolledwindow) · [PopupWindow](#popupwindow) ·
+[ProgressDialog, WebView, device composites](#progressdialog-webview-and-device-page-composites) ·
+[Debugging widgets](#debugging-widgets)
+
+## Rules
+
+1. Interactive controls in new or modified UI are Orca widgets (`Button`, `::CheckBox`, `::ComboBox`, `::TextInput`,
+   `SpinInput`, `SwitchButton`, `RadioGroup`, `TabCtrl`); never `wxButton`, `wxSpinCtrl`, `wxCheckBox`, `wxChoice` or
+   a single-line `wxTextCtrl` in new code. → §Custom vs raw
+2. Every dialog's bottom button row is `DialogButtons`. → §DialogButtons
+3. Inside `namespace Slic3r::GUI` write `::CheckBox`, `::TextInput`, `::ComboBox` (also in `dynamic_cast` and
+   forward declarations, which go at global scope). → §Namespaces
+4. Call `Button::SetStyle(ButtonStyle, ButtonType)` on every `Button` you create; re-apply size/font overrides after
+   `Rescale()`. → §Button
+5. User handlers bound on a widget run **before** the widget's own handlers: `Skip()` in `wxEVT_TOGGLEBUTTON`
+   handlers on `::CheckBox`/`SwitchButton`, in mouse handlers on `Button`, and in ENTER/KILL_FOCUS handlers on
+   `GetTextCtrl()`, and take events by reference. → §Event semantics
+6. Bind widget events on the widget itself (or by event type on an ancestor), not on an ancestor filtered by the
+   widget's id: `ComboBox` ignores the id you pass, `TextInput`/`SpinInput` take none, and several events carry id 0
+   or another window's id. → §Event semantics
+7. Know which setters emit: `RadioGroup::SetSelection`, `MultiSwitchButton::SetSelection`, `TabCtrl::SelectItem`,
+   `Notebook::SetSelection`, an editable `ComboBox::SetSelection` (as `wxEVT_TEXT`) and `SpinInput::SetValue` (as
+   `wxEVT_TEXT` + `EVT_SPINCTRL_TEXT`) do. → §Event semantics
+8. `::CheckBox` and `SwitchButton` emit `wxEVT_TOGGLEBUTTON`, never `wxEVT_CHECKBOX`. → §CheckBox and RadioBox
+9. Set a container's background colour before creating widgets in it. → §Shared lifecycle rules
+10. Enable/disable custom widgets individually; disabling an ancestor leaves them painted enabled (`::CheckBox`, a native button, greys with it). → §Shared lifecycle
+    rules
+11. Call each widget's `Rescale()` from `on_dpi_changed` (types qualified); `RadioGroup`, `Label`, `HyperLink` and
+    `LabeledStaticBox` have none and `ProgressBar::Rescale()` does nothing. → §Shared lifecycle rules
+12. Read and write `TextInput` text through `GetTextCtrl()` (`ChangeValue` for a silent update); bind
+    `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the TextInput or its `GetTextCtrl()`, never on a parent. → §TextInput
+13. Multi-line text is a raw `wxTextCtrl` with `wxTE_MULTILINE`, not `TextInput`. → §TextInput
+14. `ComboBox`: `wxCB_READONLY` for choice semantics, `SelectAndNotify(n)` when listeners must react, `void*` client
+    data only. → §ComboBox and DropDown
+15. `SpinInput` is integer-only and cannot type `-`; set the range before the value; read `GetValue()` after the
+    commit; bind `wxEVT_SPINCTRL` with a `wxCommandEvent&` handler. → §SpinInput and TempInput
+16. `TabCtrl`'s `wxEVT_TAB_SEL_CHANGING` cannot veto; switching content is your job. → §Tab systems
+17. Custom `DialogButtons` labels must exist in the translation catalog (write them as `L("…")`). → §DialogButtons
+18. `ProgressBar` colours are painted unmapped and its colour-setter names are swapped; use `SetHeight` for thin bars.
+    → §ProgressBar
+19. Transient popups derive from `PopupWindow`; on MSW call `BindUnfocusEvent()` when the popup must close with the
+    frame. → §PopupWindow
+20. Children of a `LabeledStaticBox` are created with the box as parent; its label is fixed at `Create()`.
+    → §StaticBox, LabeledStaticBox, StaticLine
+21. Links are `HyperLink`, or a `Label` given `LB_HYPERLINK` through `SetWindowStyleFlag` (the constructor ignores it).
+    → §Label and HyperLink
+
+## Why the library exists
+
+Native controls cannot carry Orca's flat, rounded, palette-coloured look, and they cannot follow all of Orca's
+theming:
+- On Windows the theme is an app-level setting (Preferences "Enable dark Mode", Windows-only) layered on
+  `MSWEnableDarkMode`, and wx's MSW dark mode does not reach `TaskDialog()`-based dialogs (`wxMessageBox`,
+  `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`), the common dialogs or the date/time pickers
+  (`interface/wx/app.h:1436-1445`). Hence the `MsgDialog` family (`references/windows-dialogs.md`) and Orca's own
+  `ProgressDialog`.
+- On macOS and Linux Orca follows the system appearance; native controls are themed by the toolkit, but any
+  light palette colour set on them still needs the `UpdateDarkUI` pass (`references/colours-dark-mode.md`).
+- GTK theme borders bleed through native controls wrapped inside an owner-drawn frame, so wrappers strip them with
+  `Slic3r::GUI::RemoveInputBorder` (`TextInput`, `SpinInput`, `ComboBox`) or `RemoveButtonBorder` (`::CheckBox`,
+  `SwitchButton`) under `__WXGTK__` (`GUI_Utils.cpp`, a CSS provider on GTK3).
+
+Design that every widget shares:
+- **Colours are data.** Most widgets derive from `StaticBox` (a `wxWindow` painting a rounded rect, border, optional
+  vertical gradient and badge) whose colours are `StateColor`s resolved at paint time from state bits tracked by a
+  pushed `StateHandler` and from the current dark flag, so painted colours follow a theme switch on the next
+  `Refresh()`. `StaticBox::SetBackgroundColor(StateColor)` is the owner-drawn fill and is **not** wx's
+  `SetBackgroundColour`. Details: `references/painting-custom-widgets.md`, `references/colours-dark-mode.md §StateColor`.
+- **Events mirror wx.** Widgets emit the native event types (`wxEVT_BUTTON`, `wxEVT_TOGGLEBUTTON`, `wxEVT_COMBOBOX`,
+  `wxEVT_SPINCTRL`, `wxEVT_RADIOBOX`) through `GetEventHandler()->ProcessEvent`, so command events propagate to
+  parents like native ones (`docs/doxygen/overviews/eventhandling.h:536-552`) and stop at dialogs
+  (`wxWS_EX_BLOCK_EVENTS`, `interface/wx/window.h:264-270`) and, on MSW and macOS, at popups ([source]
+  `src/common/popupcmn.cpp:135` sets the same flag; wxGTK's `wxPopupWindow::Create` never calls it,
+  `src/gtk/popupwin.cpp`). Propagation still works with the `StateHandler` pushed in front because the window's
+  `TryAfter` forwards to the parent ([source] `src/common/wincmn.cpp:3499-3522`). The differences from native
+  controls (ids, event objects, setter side effects) are in §Event semantics.
+
+## Namespaces and the ::CheckBox clash
+
+Widgets are in the **global namespace**, except these, which are in `Slic3r::GUI`: `DialogButtons`, `HyperLink`,
+`ProgressDialog`, `RadioBox`, the `AMSControl`/`AMSItem` family, the `FanControl` family, `FilamentLoad`, the
+`MultiNozzleSync` dialogs/tables, `SideTools`/`SideToolsPanel`, `WebViewHostDialog`, and the non-widget helpers of
+`WebHosting.hpp` (namespace `Slic3r::GUI::web_hosting`) (check the header).
+
+The `::` prefix matters because `Field.hpp` declares settings-field classes `Slic3r::GUI::CheckBox`, `TextCtrl`,
+`SpinCtrl`, `Choice`, `StaticText` (plus `ColourPicker`, `PointCtrl`, `SliderCtrl`). Inside `namespace Slic3r::GUI`,
+once `Field.hpp` is reachable (through `OptionsGroup.hpp`, `Tab.hpp`, …), unqualified `CheckBox` names the Field
+class, which is not a `wxWindow`. `TextCtrl` also names the MSW `wxTextCtrl` subclass/typedef in
+`Widgets/TextCtrl.h`.
+
+- **Rule:** Qualify global widget types inside `Slic3r::GUI`, especially in `dynamic_cast`.
+  **Why:** `dynamic_cast<CheckBox*>(child)` compiles (the Field class has `msw_rescale()`), but never matches a
+  window, so the walk silently skips every `::CheckBox`. `PreferencesDialog::on_dpi_changed` has this shape — copy
+  its child walk, not its unqualified casts.
+  ```cpp
+  // Wrong (in namespace Slic3r::GUI):
+  else if (auto* chk = dynamic_cast<CheckBox*>(child)) chk->msw_rescale();   // Field class: never matches
+  // Right:
+  else if (auto* chk = dynamic_cast<::CheckBox*>(child)) chk->Rescale();
+  ```
+- **Rule:** Forward-declare global widgets at global scope, before `namespace Slic3r {`.
+  **Why:** `class Button;` inside `namespace Slic3r::GUI` declares a distinct, never-defined `Slic3r::GUI::Button`;
+  members of that type cannot hold a `::Button*` and calls on them do not compile.
+  ```cpp
+  class Button; class ComboBox;            // Right: global, as MultiNozzleSync.hpp does
+  namespace Slic3r { namespace GUI {
+  class MyPanel : public wxPanel { ::Button* m_ok{nullptr}; ::ComboBox* m_combo{nullptr}; };
+  }}
+  ```
+
+## Catalog
+
+| Widget (header) | Replaces | Base | Constructor | Must-know |
+|---|---|---|---|---|
+| `Button` | `wxButton`, `wxBitmapButton`, `ScalableButton` | `StaticBox` | `Button(parent, text, icon = "", style = 0, iconSize = 0, id = wxID_ANY)` | icon = SVG **name** from `resources/images/` (no path/extension), default 20 px; **id is last**; style with `SetStyle(...)`; emits `wxEVT_BUTTON`. §Button |
+| `DialogButtons` (`Slic3r::GUI`) | `wxStdDialogButtonSizer`, `CreateStdDialogButtonSizer` | `wxPanel` | `DialogButtons(parent, {non-translated labels}, primary_translated_label = "", left_aligned_count = 0)` | labels → stock ids; styles primary/alert; self-rescales. §DialogButtons |
+| `Label` | `wxStaticText` | `wxStaticText` | `Label(parent, text = "", style = 0, size)` (font `Body_14`), `Label(parent, font, text, style, size)` | `LB_AUTO_WRAP`, `LB_PROPAGATE_MOUSE_EVENT`, `LB_HYPERLINK` (via `SetWindowStyleFlag`); hosts the font table. §Label |
+| `HyperLink` (`Slic3r::GUI`) | `wxHyperlinkCtrl` | `wxStaticText` | `HyperLink(parent, label = "", url = "", style = 0)` | opens `url` with `wxLaunchDefaultBrowser` on left-down. §Label |
+| `::CheckBox` | `wxCheckBox` | `wxBitmapToggleButton` | `CheckBox(parent, id = wxID_ANY)` — **no label** | emits `wxEVT_TOGGLEBUTTON`; `SetHalfChecked`; `Rescale()`. §CheckBox |
+| `SwitchButton` | on/off `wxCheckBox`, `wxToggleButton` | `wxBitmapToggleButton` | `SwitchButton(parent = nullptr, id = wxID_ANY)` | `SetLabels(on, off)`; track/thumb/text `StateColor`s; emits `wxEVT_TOGGLEBUTTON`. §SwitchButton family |
+| `MultiSwitchButton` | segmented `wxRadioBox` | `StaticBox` | `MultiSwitchButton(parent, id, pos, size, style)` | emits `wxCUSTOMEVT_MULTISWITCH_SELECTION`, also from `SetSelection`. §SwitchButton family |
+| `RadioGroup` | `wxRadioBox`, `wxRadioButton` rows | `wxPanel` | `RadioGroup(parent, std::vector<wxString> labels, wxHORIZONTAL/wxVERTICAL, row_col_limit = -1)` | emits `wxEVT_RADIOBOX` from **every** `SetSelection`. §RadioGroup |
+| `::TextInput` | single-line `wxTextCtrl` | `wxNavigationEnabled<StaticBox>` | `TextInput(parent, text, label = "", icon = "", pos, size, style)` | value API on `GetTextCtrl()`; `label` is a painted side label. §TextInput |
+| `::ComboBox` | `wxComboBox`, `wxChoice`, `wxBitmapComboBox` | `wxWindowWithItems<TextInput, wxItemContainer>` | `ComboBox(parent, id, value = "", pos, size, n = 0, choices = NULL, style = 0)` | `wxCB_READONLY` = choice; `SelectAndNotify`; `void*` client data only. §ComboBox |
+| `DropDown` | native combo popup, menu used as a list | `PopupWindow` | `DropDown(parent, std::vector<Item>& items, style = 0)` | holds `items` **by reference**; `Invalidate()` after edits. §ComboBox |
+| `SpinInput` | `wxSpinCtrl` | `wxNavigationEnabled<StaticBox>` | `SpinInput(parent, text, label = "", pos, size, style, min = 0, max = 100, initial = 0, step = 1)` | integer, non-negative typing; commits on Enter/kill-focus. §SpinInput |
+| `TempInput` | temperature `wxTextCtrl` (device pages) | `wxNavigationEnabled<StaticBox>` | `TempInput(parent, type, text, TempInputType, label, normal_icon, active_icon, pos, size, style)` | warning icon + too-high/too-low states; posts `wxCUSTOMEVT_SET_TEMP_FINISH` to its **parent**. §SpinInput |
+| `TabCtrl` | `wxNotebook` tab strip | `StaticBox` | `TabCtrl(parent, id, pos, size, style)` | one `Button` per tab; you switch the content. §Tab systems |
+| `Notebook` (`GUI/Notebook.hpp`) | `wxNotebook` | `wxBookCtrlBase` | `Notebook(parent, id, pos, size, side_tools = NULL, style = 0)` | MainFrame's main tabs; pages addressed by name. §Tab systems |
+| `LabeledStaticBox` | `wxStaticBox` | `wxStaticBox` | `LabeledStaticBox(parent, label = "", pos, size, style)` | usable as a `wxStaticBoxSizer` box; label fixed at `Create()`. §StaticBox… |
+| `StaticBox` | plain bordered `wxPanel` | `wxWindow` | `StaticBox(parent, id, pos, size, style)` | rounded group frame; base of most widgets; `ShowBadge(bool)`. §StaticBox… |
+| `StaticLine` | `wxStaticLine` | `wxWindow` | `StaticLine(parent, vertical = false, label = {}, icon = {})` | H/V separator with optional label + icon; `SetLineColour`. Avoid `wxStaticLine`. §StaticBox… |
+| `ProgressBar` | `wxGauge` | `wxWindow` | `ProgressBar(parent, id = wxID_ANY, max = 100, pos, size, shown = false)` | plain `wxColour`s, unmapped; `Disable(wxString)`. §ProgressBar |
+| `ScrolledWindow` + `MyScrollbar` | `wxScrolledWindow` with slim bars | `wxScrolled<wxWindow>` | `ScrolledWindow(parent, id, pos, size, style, marginWidth = 0, scrollbarWidth = 4, tipLength = 0)` | content on `GetPanel()`; vertical use. §ScrolledWindow |
+| `PopupWindow` | `wxPopupTransientWindow` | `wxPopupTransientWindow` | `PopupWindow(parent, style = wxBORDER_NONE)` | per-platform dismissal hooks; MSW part opt-in. §PopupWindow |
+| `ProgressDialog` (`Slic3r::GUI`) | `wxProgressDialog` | `wxDialog` | `ProgressDialog(title, message, maximum = 100, parent = NULL, style = wxPD_APP_MODAL \| wxPD_AUTO_HIDE, adaptive = false)` | styled copy of the generic dialog. §ProgressDialog… |
+| `WebView` | `wxWebView::New` | static helpers | `WebView::CreateWebView(parent, url)` | see `references/webview-gl-aui-media.md`. §ProgressDialog… |
+| `CheckList` | `wxCheckListBox` | `wxWindow` | `CheckList(parent, choices, scroll_style = wxVSCROLL)` | filterable multi-select list (`MultiChoiceDialog`). |
+
+Field classes (`Field.cpp`) build their editors from these widgets (`TextCtrl` → `::TextInput`, `CheckBox` →
+`::CheckBox`, `SpinCtrl` → `SpinInput`, `Choice` → `::ComboBox`); the field machinery is in
+`references/orca-settings-ui.md`.
+
+## Event semantics
+
+| Widget | Emits on user action | Id / event object | Programmatic setters | Bind |
+|---|---|---|---|---|
+| `Button` | `wxEVT_BUTTON` (on release inside, Space/Enter) | button id / button | `SetValue(bool)` (Checked look) silent | on the button (Rule 6) |
+| `::CheckBox`, `SwitchButton` | `wxEVT_TOGGLEBUTTON` | native id / widget | `SetValue`, `SetHalfChecked` silent (`interface/wx/tglbtn.h:98`) | on the widget; never `wxEVT_CHECKBOX` |
+| `::ComboBox` | `wxEVT_COMBOBOX` (int = index, string = text) from popup pick, arrow keys (read-only combo), `SelectAndNotify`; `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` | COMBOBOX: combo's auto id / combo; DROPDOWN/CLOSEUP: **id 0, no object** | `SetSelection`, `SetValue` silent for COMBOBOX; editable or `CB_NO_TEXT`: they send `wxEVT_TEXT` | on the combo |
+| `::TextInput` | inner `wxEVT_TEXT` (propagates); `wxEVT_TEXT_ENTER`, `wxEVT_KILL_FOCUS` re-sent to the wrapper only | TEXT: **inner** id/object; ENTER/KILL_FOCUS: wrapper id, inner object | `GetTextCtrl()->SetValue` sends `wxEVT_TEXT`; `ChangeValue` silent | TEXT: wrapper, inner, or ancestor by type; ENTER/KILL_FOCUS: wrapper or inner |
+| `SpinInput` | `wxEVT_SPINCTRL` (a plain `wxCommandEvent`, no int) on commit; `EVT_SPINCTRL_TEXT` (int + string) per parseable keystroke; inner `wxEVT_TEXT` | spinner id / spinner | `SetValue` sends `EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`, no `wxEVT_SPINCTRL` | on the spinner; handler takes `wxCommandEvent&` |
+| `RadioGroup` | `wxEVT_RADIOBOX` (int, string) | group id / **no object** | **every** `SetSelection(i)` emits, same index included | on the group |
+| `TabCtrl` | `wxEVT_TAB_SEL_CHANGING` (int = old index, not vetoable), then `wxEVT_TAB_SEL_CHANGED` (int = new) | ctrl id / ctrl | `SelectItem(i)` emits both when `i` changes | on the ctrl |
+| `Notebook` | tab click posts `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` (id = page index), then `wxEVT_NOTEBOOK_PAGE_CHANGING`/`_CHANGED` | — | `SetSelection` emits PAGE_*; `ChangeSelection` silent | on the notebook |
+| `MultiSwitchButton` | `wxCUSTOMEVT_MULTISWITCH_SELECTION` (int, string) | id / widget | `SetSelection` emits when the index changes | on the widget |
+| `SwitchBoard` | `wxCUSTOMEVT_SWITCH_POS` (int: 1 = left half, 0 = right half), **posted** | id 0 / none | — | on the board |
+| `ModeSwitchButton` | none — writes the app mode (`wxGetApp().save_mode`) | — | `SetSelection` silent | — |
+| `DropDown` (standalone) | `wxEVT_COMBOBOX` (int, string), `EVT_DISMISS` | COMBOBOX: popup id / popup; EVT_DISMISS: id 0, no object | — | on the DropDown (popups block propagation on MSW/macOS, not on GTK) |
+| `TempInput` | `wxCUSTOMEVT_SET_TEMP_FINISH` on commit, **posted to the parent** (int = the ctor's `type`, string = the `TempInputType` number) | id 0 / none | — | on the **parent**; tell inputs apart by the int |
+
+Consequences that recur:
+- **Ids.** `ComboBox` calls `TextInput::Create`, which takes no id and creates the window with `wxID_ANY`, so the
+  combo's `id` argument is ignored; `TextInput` and
+  `SpinInput` have no id parameter. `parent->Bind(wxEVT_COMBOBOX, h, ID_MY_COMBO)` never fires. Bind on the widget,
+  or call `SetId()` after construction if an id filter is unavoidable.
+- **Handler order.** Dynamic handlers run most-recently-bound first, before static event tables
+  (`interface/wx/event.h:592-593`). Widgets bind their internal handlers in the constructor (or use event tables),
+  so yours run first: a handler that does not `Skip()` cuts off the widget's own behaviour (bitmap refresh, commit,
+  click). A handler taking the event **by value** cannot `Skip()` the real event (`references/events.md §Skip
+  discipline`).
+- **Setters vs wx.** wx's rule is that setters are silent (`interface/wx/ctrlsub.h:102-103`); `wxTextEntry::SetValue`
+  and `wxBookCtrlBase::SetSelection` are the documented exceptions (`references/controls-dataview.md §Events from
+  programmatic changes`). The table's emitting setters re-enter change handlers synchronously inside model→view
+  refreshes: guard with a flag or use the silent variant.
+
+## Custom vs raw
+
+Rules:
+1. Interactive controls in new or modified UI: Orca widgets, always. Bottom button rows: `DialogButtons`. When you
+   modify an older dialog built from raw controls, convert the controls you touch; untouched raw controls are not a
+   model.
+2. Static text: plain `wxStaticText` with a `Label::Body_*` font is fine; use `Label` for auto-wrap and the hyperlink
+   look, `HyperLink` for a link that opens a URL. Fonts come from the `Label` statics (`Head_10…Head_48` bold for
+   titles, `Body_8…Body_16` for content, `Body_14` the dialog default); never hardcode point sizes, because
+   `Label::sysFont` already scales them per platform (`references/dpi-bitmaps-fonts.md`).
+3. Containers stay raw: `wxPanel`, `wxBoxSizer`, `wxScrolledWindow`, `wxSimplebook`. `StaticBox`/`LabeledStaticBox`
+   only for the rounded-border group look; `ScrolledWindow` only for the slim-scrollbar look.
+4. If a raw control is unavoidable, make it dark-safe: `wxGetApp().UpdateDarkUI(ctrl)` / `UpdateDlgDarkUI(dlg)` or
+   explicit `StateColor::darkModeColorFor()` (`references/colours-dark-mode.md`).
+5. Every custom widget inside a `DPIDialog`/`DPIFrame` gets its `Rescale()` called from `on_dpi_changed`
+   (§Shared lifecycle rules).
+
+Mixed is normal: `CloneDialog::CloneDialog` pairs raw `wxStaticText` labels with `SpinInput`, `::CheckBox`,
+`ProgressBar` and `DialogButtons` (copy its layout, not its OK handler, which runs a `wxYield()` loop inside a frozen
+plater).
+
+No Orca replacement exists — use raw wx (`references/controls-dataview.md`) for: multi-line text (`wxTextCtrl` +
+`wxTE_MULTILINE`, as Field does for multi-line options), headerless page stacks (`wxSimplebook`), data views and grids
+(`wxDataViewCtrl`, `wxGrid`), `wxSlider`, `wxColourPickerCtrl`, `wxSplitterWindow`, `wxStaticBitmap`, and the
+`Slic3r::GUI::BitmapComboBox` wrapper where a `wxBitmapComboBox` is required.
+
+## Shared lifecycle rules
+
+**Background snapshot.** `StaticBox::Create`, `Label`, `SwitchButton` (through `StaticBox::GetParentBackgroundColor`:
+a parent `StaticBox`'s default fill — the midpoint for a gradient — else `parent->GetBackgroundColour()`), and
+`::CheckBox`, `RadioGroup` (`parent->GetBackgroundColour()`) copy the parent's background colour at construction;
+wx itself never inherits a background colour ([source] `src/common/wincmn.cpp:1543-1552`).
+- **Rule:** Set the container's background before creating widgets in it.
+  ```cpp
+  auto* panel = new wxPanel(this);
+  auto* cb = new ::CheckBox(panel);          // Wrong: snapshots the panel's default colour
+  panel->SetBackgroundColour(*wxWHITE);
+  // Right: SetBackgroundColour first, then create children
+  ```
+
+**Enable state.** A parent's `Enable()`/`Disable()` never calls a child's virtual `Enable()`: on MSW and macOS it
+reaches children through `NotifyWindowOnEnableChange` → `DoEnable()`, on GTK the toolkit propagates sensitivity
+natively ([source] `src/common/wincmn.cpp:1147-1201`). Orca widgets update their `Enabled` state bit only from
+`EVT_ENABLE_CHANGED`, which their `Enable()` override emits — so after `panel->Disable()` they ignore input
+(`IsEnabled()` is false, `interface/wx/window.h:3060-3069`) but the `StateColor`-painted ones (`Button`, `TextInput`,
+`ComboBox`, `SpinInput`, `RadioGroup`'s labels, …) still paint enabled colours. [source] `::CheckBox`, a native
+`wxBitmapToggleButton`, greys with its parent on every port: MSW `EnableWindow`s it and the owner-drawn button paints
+its disabled bitmap (`src/msw/window.cpp:576-593`, `src/msw/anybutton.cpp:846-871`, `:969-972`, `:1502`); GTK3's
+button image draws a greyed copy of the current bitmap while `!IsEnabled()` (`src/gtk/image_gtk.cpp:37-42`), though
+the disabled bitmap itself needs `IsThisEnabled()` false (`src/gtk/anybutton.cpp:140-146`); macOS sends
+`setEnabled:NO` (`src/osx/cocoa/window.mm:3784-3791`) and AppKit dims the image (`NSButtonCell`
+`imageDimsWhenDisabled`, default YES).
+- **Rule:** Enable/disable each custom widget directly (`RadioGroup::Enable` does this for its own buttons).
+  ```cpp
+  m_options_panel->Enable(on);                                                // Wrong: widgets keep the enabled look
+  for (wxWindow* w : std::initializer_list<wxWindow*>{m_combo, m_spin, m_check})
+      w->Enable(on);                                                          // Right: virtual Enable() per widget
+  ```
+
+**DPI.** Widgets size themselves from `FromDIP` values and cached bitmaps; after a DPI change the owning
+`DPIDialog::on_dpi_changed` must call `Rescale()` on each (`Button`, `::CheckBox`, `::TextInput`, `::ComboBox`
+(also rescales its `DropDown`), `SpinInput`, `SwitchButton`, `MultiSwitchButton`, `TabCtrl`, `StaticLine`,
+`ModeSwitchButton`). Exceptions: `RadioGroup`, `Label`, `HyperLink` and `LabeledStaticBox` (its scale is fixed in
+`Create()`) have no `Rescale()`; `ProgressBar::Rescale()` is empty; `DialogButtons` rescales itself. Pass sizes through
+`FromDIP` (`references/dpi-bitmaps-fonts.md`).
+```cpp
+void MyDialog::on_dpi_changed(const wxRect&) {
+    m_ok_btn->Rescale();  m_combo->Rescale();  m_check->Rescale();   // ::CheckBox has Rescale(), not msw_rescale()
+    m_combo->SetMinSize(wxSize(FromDIP(160), -1));                    // re-apply explicit sizes
+    GetSizer()->SetSizeHints(this); Refresh();                        // resize + new minimum (sizers-layout.md)
+}
+```
+
+**Theme switch.** `StateColor`s follow the dark flag at paint time. What was captured once does not: the wx
+background copied at construction, colours baked into bitmaps (`SwitchButton` labels, `::CheckBox`/`RadioGroup`
+SVGs), `ProgressBar` colours, `Label` foreground. The `Update*DarkUI` walk re-maps the wx colours among them that
+are `gDarkColors` keys (`Label`'s `#262E30`, a palette background) when it reaches the widget, nothing else.
+Re-apply them in `on_sys_color_changed()` (call `Rescale()` where
+it re-reads colours, e.g. `SwitchButton`), and keep `UpdateDlgDarkUI(this)` as the last constructor line
+(`references/colours-dark-mode.md §Runtime theme switch and re-applying colours`).
+
+**Sizing.** No widget implements `DoGetBestSize`: the text/icon widgets set their min size in `messureSize()` whenever
+a label, font, icon, style or DPI changes, and the bitmap toggles (`::CheckBox`, `SwitchButton`) size themselves
+to their bitmap in `Rescale()`.
+Nothing re-lays out the parent: call `Layout()` on the container after changing a widget's content at runtime
+(`references/sizers-layout.md`).
+
+**Mouse capture.** `Button`, `DropDown`, `SpinInput`'s arrows, `ModeSwitchButton`, `MyScrollbar`, `StepCtrl` and the
+device-page `SideButton`, `ImageSwitchButton` and `AxisCtrlButton` capture the mouse while pressed; a capture leak
+shows on macOS as a UI that is alive but unclickable (`references/mouse-keyboard-focus.md §Mouse capture`).
+
+## Button
+
+`Button` (`Widgets/Button.cpp`) is a `StaticBox` with label, optional icon (`ScalableBitmap` from an SVG name), focus
+ring and an optional toggle look. `Create` sets `Label::Body_14` and measures; `messureSize()` sets the min size from
+text + icon + padding, capped in width by `SetMaxSize` (the label then becomes the tooltip if none is set); a size
+given to `Button::SetMinSize` is stored, floors the width and, when its height is > 0, replaces the measured height.
+
+`SetStyle(ButtonStyle, ButtonType)` is the one call that makes it look like an Orca button — don't hand-roll button
+colours in new code:
+
+| `ButtonType` | Padding / min size / radius | Font | Use |
+|---|---|---|---|
+| `Compact` | padding 8×3, radius 8 | `Body_10` | tight spaces |
+| `Window` | size and min 58×24, radius 12 | `Body_12` | buttons in windows, away from parameter boxes |
+| `Choice` | min 100×32, padding 12×8, radius 4 | `Body_14` | dialog/window choice buttons (`DialogButtons` uses it) |
+| `Parameter` | size and min 120×26, radius 4 | `Body_14` | buttons next to parameter boxes |
+| `Icon` | padding 5×5, size and min 26×26, radius 4 | — | icon-only; create with `iconSize = 16` and a 16 px icon |
+| `Expanded` | min height 32, padding 12×8, radius 4 | `Body_14` | full-width buttons, e.g. inside a static box |
+
+All values go through `FromDIP`. `ButtonStyle::{Regular, Confirm, Alert, Disabled}` picks the background, border and
+text `StateColor`s from the `btn_regular/btn_confirm/btn_alert/btn_disabled` tables in `Button.cpp` (palette colours
+where the dark map should apply; the focus-border colour is chosen per theme when `SetStyle` runs). `ButtonStyle::Disabled` is a **look**; it does not call `Enable(false)`.
+
+```cpp
+auto* export_btn = new Button(this, _L("Export"));
+export_btn->SetStyle(ButtonStyle::Confirm, ButtonType::Choice);
+export_btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { on_export(); });
+
+auto* reload_btn = new Button(parent, wxEmptyString, "refresh", 0, 16);   // icon-only (PreferencesDialog)
+reload_btn->SetStyle(ButtonStyle::Regular, ButtonType::Icon);
+```
+
+Behaviour (`Button::mouseDown`, `Button::mouseReleased`, `Button::keyDownUp`):
+- Left-down focuses (if focusable) and captures; left-up releases and sends `wxEVT_BUTTON` (id = window id, event
+  object = button) when the pointer is inside. Space/Enter synthesise down/up, so a focused Button clicks on key-up;
+  on MSW it claims `WM_GETDLGCODE` so Enter reaches it instead of the dialog's default-button logic.
+- Tab is turned into navigation; arrow keys are swallowed (`HandleAsNavigationKey` handles only Tab, [source]
+  `src/common/wincmn.cpp:3566-3583`), which is why `DialogButtons` adds its own arrow handler.
+- `SetValue(bool)`/`GetValue()` drive the `Checked` state bit (used by `TabCtrl` and `MultiSwitchButton`); it is
+  visible only with `StateColor`s that have `Checked` entries — the `SetStyle` tables have none, the unstyled default
+  does. Clicks do not toggle it.
+- `SetCanFocus(false)` keeps it out of focus (`AcceptsFocus()` returns the flag). `EnableTooltipEvenDisabled()` shows
+  the tooltip on a disabled button by watching the parent's motion — MSW only (elsewhere a no-op).
+- `SetIndicator(bool)` draws a small dot after the label (TabCtrl uses it); `SetVertical`, `SetCenter`,
+  `SetPaddingSize`, `SetIconSpacing`, `SetTextColor(StateColor)`, `SetIcon(name | wxBitmap)`.
+- `Rescale()` re-rasterises a **named** icon (one set from a `wxBitmap` has no source and stays as is), re-measures and
+  re-runs `SetStyle` with the stored style/type.
+
+Pitfalls:
+- **Rule:** Call `SetStyle` on every Button you create.
+  **Why:** the unstyled defaults are wx stock colours (`*wxLIGHT_GREY` hover, `*wxBLACK` text) chosen for no Orca
+  design and partly off the dark map, with generic metrics (padding 10×8, `StaticBox` radius 8, `Body_14`) instead of
+  a `ButtonType`'s, and no focus border.
+- **Rule:** Re-apply your own min size, size or font after `Rescale()`.
+  **Why:** `Rescale()` re-runs `SetStyle`, which resets min size, padding, radius and font for the type.
+  ```cpp
+  btn->SetStyle(ButtonStyle::Regular, ButtonType::Choice);
+  btn->SetMinSize(wxSize(FromDIP(160), FromDIP(32)));     // lost on the next Rescale()…
+  // Right: in on_dpi_changed: btn->Rescale(); btn->SetMinSize(wxSize(FromDIP(160), FromDIP(32)));
+  ```
+- **Rule:** A `wxEVT_LEFT_DOWN`/`_UP` handler bound on a Button must `Skip()`.
+  **Why:** the click logic lives in the Button's static event table, which runs after dynamic handlers.
+- **Rule:** Do not rely on Button's capture-lost handling to cancel a press.
+  **Why:** `Button::mouseCaptureLost` replays release with a default `wxMouseEvent` at (0,0), which is inside the
+  button, so losing capture mid-press **sends `wxEVT_BUTTON`**. The lost event comes on MSW and GTK and never on
+  macOS ([source] `src/msw/window.cpp:5186`, `src/gtk/window.cpp:6808-6814`; `interface/wx/event.h:3507` says
+  Windows only — `references/mouse-keyboard-focus.md §Per-port delivery`). wx's contract is to cancel the
+  operation (`interface/wx/window.h:3815-3817`). `ModeSwitchButton::mouseCaptureLost` is the correct shape (clear
+  the pressed flag, no action), minus its `Skip()` (a lost handler must not skip).
+
+## DialogButtons
+
+`Slic3r::GUI::DialogButtons` (`Widgets/DialogButtons.cpp`) is a `wxPanel` that builds the standard bottom row: one
+`Button` per label, all `ButtonStyle::Regular` + `ButtonType::Choice`, gaps of `ButtonProps::ChoiceButtonGap()`.
+
+```cpp
+auto* dlg_btns = new DialogButtons(this, {"OK", "Cancel"});   // NOT pre-translated
+dlg_btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { apply(); EndModal(wxID_OK); });  // no Skip()
+sizer->Add(dlg_btns, 0, wxEXPAND);
+```
+The full dialog recipe (DPIDialog, `SetSizerAndFit`, `CenterOnParent`, `UpdateDlgDarkUI`) is in
+`references/windows-dialogs.md`.
+
+Constructor contract:
+- **Labels** are untranslated; the constructor shows `_L(label)` and matches `label` lower-cased against a stock-id
+  map: `ok`→`wxID_OK`, `yes`→`wxID_YES`, `apply` and `confirm`→`wxID_APPLY`, `no`→`wxID_NO`, `cancel`→`wxID_CANCEL`,
+  `open`→`wxID_PRINT` (the map's first `"open"` entry wins), `add`, `copy`, `new`, `save`, `save as`, `refresh`,
+  `retry`, `ignore`, `help`, `clone`/`duplicate`→`wxID_DUPLICATE`, `select all`, `replace`, `replace all`,
+  `return`→`wxID_BACKWARD`, `next`→`wxID_FORWARD`, `remove`, `delete`, `abort`, `stop`, `reset`, `clear`,
+  `exit`/`quit`→`wxID_EXIT`. Other labels keep an auto id.
+- **Primary** (`ButtonStyle::Confirm`): the 2nd argument is a *translated* label (`_L("Create")`) naming it;
+  empty → the only button if there is one, else the first present of `{wxID_OK, wxID_YES, wxID_APPLY, wxID_SAVE,
+  wxID_PRINT}` in **numeric id order** (a `std::set`: `wxID_SAVE` < `wxID_PRINT` < `wxID_OK` < `wxID_APPLY` <
+  `wxID_YES`), so `{"Save", "OK"}` makes Save primary. A label that matches no button means no primary. The primary
+  takes focus only when nothing in the app has focus.
+- **Alert** (`ButtonStyle::Alert`): only with ≥ 2 buttons, the first present (numeric order) of `wxID_EXIT`,
+  `wxID_CLEAR`, `wxID_DELETE`, `wxID_RESET`, `wxID_ABORT`, `wxID_REMOVE`, `wxID_STOP`; `SetAlertButton(translated)`
+  picks another.
+- **`left_aligned_count`** pins the first N buttons to the left (`SetLeftAlignedButtonsCount` later).
+- Getters: `GetOK/GetYES/GetAPPLY/GetCONFIRM (= wxID_APPLY)/GetNO/GetCANCEL/GetRETURN/GetNEXT/GetFIRST/GetLAST`,
+  `GetButtonFromID`, `GetButtonFromLabel(translated)`, `GetButtonFromIndex`.
+
+How clicks close the dialog: a click sends `wxEVT_BUTTON` with the stock id; unhandled, it propagates to
+`wxDialogBase::OnButton` (`src/common/dlgcmn.cpp:105,455-478`): the affirmative id (`wxID_OK` by default) runs
+`AcceptAndClose()` = `Validate()` + `TransferDataFromWindow()` then `EndDialog(wxID_OK)` (:369-375); `wxID_APPLY`
+validates and transfers without closing; `wxID_CANCEL` → `EndDialog(wxID_CANCEL)`; any other id is skipped. So
+OK/Cancel close by themselves; Yes, No, Confirm/Apply and custom labels do nothing until you bind them. wx's
+ESC→button emulation looks for a real `wxButton` (`EmulateButtonClickIfPresent`, :387-404) and never finds an Orca
+`Button`; ESC handling is in `references/windows-dialogs.md`.
+
+DPI: the constructor binds the **parent's** `wxEVT_DPI_CHANGED` (unbound in the destructor) and `Skip()`s it; being
+bound after `DPIAware`'s handler it runs first, then the dialog's `on_dpi_changed` — the dialog does not rescale
+DialogButtons itself.
+
+Pitfalls:
+- **Rule:** A handler that calls `EndModal` must not `Skip()`; bind every button whose default handling is not what
+  you want.
+  **Why:** `Skip()` lets the event reach `wxDialogBase::OnButton`, which validates and transfers again and ends the
+  dialog a second time with its own code (`EndDialog(affirmative id)` / `EndDialog(wxID_CANCEL)`). `EndDialog` only
+  hides a dialog that no longer reports `IsModal()` (GTK, macOS reset it in the first `EndModal`), but on MSW
+  `IsModal()` stays true until `ShowModal` returns, so `EndModal` runs again and replaces the return code you passed
+  ([source] `src/common/dlgcmn.cpp` `wxDialogBase::EndDialog`, `include/wx/msw/dialog.h` `IsModal`;
+  `references/windows-dialogs.md`). Yes/No/Confirm/custom buttons never close on their own.
+- **Rule:** Every custom label must be in the translation catalog: write it as `L("Skip for Now")` in the vector, or
+  make sure the same string appears in a `_L()` elsewhere.
+  **Why:** the constructor's `_L(label)` translates a variable, which xgettext cannot see, so a label used only there
+  never reaches `OrcaSlicer.pot` and always shows in English. `L()` is a no-op marker that xgettext extracts
+  (`references/strings-i18n-files.md`).
+  ```cpp
+  new DialogButtons(this, {"Download and Install", "Skip for Now"});        // Wrong: untranslatable
+  new DialogButtons(this, {L("Download and Install"), L("Skip for Now")});  // Right
+  ```
+- **Rule:** Don't call `UpdateButtons()` (or `SetLeftAlignedButtonsCount`) repeatedly in your code.
+  **Why:** each call re-binds `wxEVT_KEY_DOWN` on every button (wx `Bind` does not de-duplicate) and the handler
+  `Skip()`s, so arrow-key focus moves repeat once per accumulated binding; DPI changes already add one each.
+- **Rule:** Don't expect the row to take the dialog's background.
+  **Why:** the panel paints `darkModeColorFor("#FFFFFF")`, re-applied on every `UpdateButtons()` (DPI change); on a
+  non-white dialog the row stands out.
+
+## Label and HyperLink
+
+`Label` (`Widgets/Label.cpp`) is a `wxStaticText` with font `Body_14` (or the font passed), foreground `#262E30` and
+the parent's background. Style bits (no clash with `wxST_*`):
+
+| Bit | Value | Effect |
+|---|---|---|
+| `LB_HYPERLINK` | `0x20` | underlined font, `#009688`, hand cursor — **only** when set through `SetWindowStyleFlag` |
+| `LB_PROPAGATE_MOUSE_EVENT` | `0x40` | left-down/up are forwarded to the parent's handler with `ProcessEventLocally` (label-relative position, label as event object) and consumed |
+| `LB_AUTO_WRAP` | `0x80` | `Label::Wrap(GetSize().x)` on every `wxEVT_SIZE` |
+
+`Label::Wrap(width)` is Orca's own wrapper over the stored text and has no width cache, unlike 3.3.2's
+`wxStaticText::Wrap` (`references/controls-dataview.md §wxStaticText`). `Label::split_lines(dc, width, text, out,
+max_count)` wraps text for owner-drawn code. The static fonts (`Head_*`, `Body_*`) are built by
+`Label::initSysFont()` from `GUI_App::on_init_inner` (`references/dpi-bitmaps-fonts.md`).
+
+`Slic3r::GUI::HyperLink` (`Widgets/HyperLink.cpp`) is a `wxStaticText` with `Head_14` (kept underlined by its
+`SetFont`), colour `#009687` — deliberately one off the palette `#009688` so the dark map leaves it alone — hover
+`#26A69A`, hand cursor, the URL as tooltip, and `wxLaunchDefaultBrowser(url)` on left-down when the URL is non-empty.
+Its `style` argument is unused.
+
+Pitfalls:
+- **Rule:** Apply `LB_HYPERLINK` through `SetWindowStyleFlag`, not the constructor; it is a look, not a link.
+  **Why:** the constructor only stores the bit, and `SetWindowStyleFlag` returns early when the style is unchanged,
+  so a label created with the bit never gets the look by re-applying it. Clicks still need your handler (or use
+  `HyperLink`).
+  On macOS the hyperlink label is set with `SetLabelMarkup`, so quote user text (`wxMarkupParser::Quote`).
+  ```cpp
+  new Label(this, _L("Learn more"), LB_HYPERLINK);                  // Wrong: stays plain text
+  auto* lbl = new Label(this, _L("Learn more"));                    // Right
+  lbl->SetWindowStyleFlag(lbl->GetWindowStyle() | LB_HYPERLINK);
+  lbl->Bind(wxEVT_LEFT_DOWN, [url](wxMouseEvent&) { wxLaunchDefaultBrowser(url); });
+  ```
+- **Rule:** For a `HyperLink` with a custom action, leave the URL empty and bind `wxEVT_LEFT_DOWN`.
+  **Why:** with a URL its own handler opens the browser; your later-bound handler runs first and would have to
+  `Skip()` to keep it.
+
+## CheckBox and RadioBox
+
+`::CheckBox` (`Widgets/CheckBox.cpp`) is a `wxBitmapToggleButton` (`wxBORDER_NONE`) showing 18 px SVGs
+`check_{on,half,off}`, `…_disabled`, `…_focused`. It has **no label**: pair it with a `wxStaticText`/`Label`
+(as `CloneDialog::CloneDialog` does). `GetValue()` is a 2-state `bool`.
+- Emits `wxEVT_TOGGLEBUTTON` on click (native). `SetValue` emits nothing (`interface/wx/tglbtn.h:98`).
+- `SetHalfChecked(true)` is a drawn-only third state (`IsHalfChecked()` exists for the inspector only); the widget's own toggle handler
+  clears it on any click. `SetValue` does **not** clear it — call `SetHalfChecked(false)` before showing a definite
+  state.
+- `Rescale()` (no `msw_rescale()`) re-rasterises all nine bitmaps and resets size/min size.
+- Platform paths: macOS emulates the disabled/focused/hover bitmaps (`CheckBox::Enable` override,
+  `DoGetBitmap`, `updateBitmap`), but wxOSX hands the `NSButton` `m_bitmaps[State_Current]`/`m_bitmaps[State_Normal]`
+  directly and calls `DoGetBitmap` only for an `IsOk()` test ([source] `src/osx/anybutton_osx.cpp:84-94`), so only
+  the hover (`_focused`) art shows and a disabled box shows its normal art dimmed by AppKit; MSW sets a focus bitmap;
+  GTK strips the theme border.
+
+`Slic3r::GUI::RadioBox` is an older single bitmap radio (`wxBitmapToggleButton`); use `RadioGroup` for new radio
+sets.
+
+Pitfalls:
+- **Rule:** Bind `wxEVT_TOGGLEBUTTON`, never `wxEVT_CHECKBOX`, and `Skip()` in the handler.
+  **Why:** `wxEVT_CHECKBOX` is never sent. The widget's own `wxEVT_TOGGLEBUTTON` handler (bound in the constructor)
+  runs **after** yours and is what swaps the bitmap (`CheckBox::update`); without `Skip()` the value changes but the
+  box keeps showing the old state.
+  ```cpp
+  cb->Bind(wxEVT_CHECKBOX, h);                                                   // Wrong: never fires
+  cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { apply(); });          // Wrong: bitmap not refreshed
+  cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { e.Skip(); apply(); }); // Right
+  ```
+
+## SwitchButton family
+
+All in `Widgets/SwitchButton.hpp/.cpp`:
+- **`SwitchButton`** — `wxBitmapToggleButton` (`wxBORDER_NONE | wxBU_EXACTFIT`), font `Body_12`. Without labels it
+  shows the `toggle_on`/`toggle_off` SVGs; `SetLabels(on, off)` switches to a two-segment pill drawn into bitmaps from
+  the track/thumb/text `StateColor`s (`SetTrackColor`, `SetThumbColor`, `SetTextColor`, `SetTextColor2`), narrowed
+  to `GetMaxWidth()` by shrinking the font. Emits `wxEVT_TOGGLEBUTTON`; `SetValue` is silent; its own toggle handler
+  (refreshes the bitmap) runs after yours — `Skip()`, as for `::CheckBox`. Every colour/label setter and
+  `SetBackgroundColour` call `Rescale()`, which re-rasterises the SVGs or, with labels, re-reads the parent background
+  and re-bakes the pill bitmaps with the current dark mapping: call it on DPI **and** theme change.
+- **`ModeSwitchButton`** — the 3-position Simple/Advanced/Expert control (`StaticBox`, `doRender`), plus `SetDevMode`.
+  It sends no event: a click calls `SelectAndNotify`, which writes the app mode through `wxGetApp().save_mode()` and
+  is ignored in dev mode or when disabled. `SetSelection` is silent and clamps to 0..2.
+- **`MultiSwitchButton`** — a segmented control of `Button`s in an internal `wxScrolledWindow` (scrolls instead of
+  clipping when squeezed; `SetFitToOptions`). `AppendOption/SetOptions/DeleteAllOptions`, per-option text/client data,
+  `GetButton(i)`. Emits `wxCUSTOMEVT_MULTISWITCH_SELECTION` (int = index, string = text) whenever the selection
+  changes — **including programmatic `SetSelection`**.
+- **`SwitchBoard`** — a two-label device-page switch (a plain `wxWindow`). It **posts** `wxCUSTOMEVT_SWITCH_POS`
+  (int = 1 for a click on the left half, 0 for the right half; no id, no event object). Its `Enable()` only flips a
+  private flag and repaints, and its non-virtual `IsEnabled()` hides the base one: the window stays enabled for wx.
+  `SetAutoDisableWhenSwitch()` makes a click set that flag off until you re-enable it.
+
+## RadioGroup
+
+`RadioGroup` (`Widgets/RadioGroup.cpp`) is a `wxPanel` of `wxStaticBitmap` radio icons plus `Button` labels in a
+`wxFlexGridSizer`; `row_col_limit` (−1 = one row for `wxHORIZONTAL`, one column for `wxVERTICAL`) wraps the items
+into a grid — check the row/column arithmetic in `RadioGroup::Create` before relying on a layout. Keyboard:
+Right/Down and Left/Up on the focused label move the selection with wrap-around (`SelectNext`/`SelectPrevious`);
+only the selected label button is focusable, so Tab enters the group once.
+`SetRadioTooltip(i, tip)`, `Enable()` (also enables the label buttons and emits `EVT_ENABLE_CHANGED`). There is no
+`Rescale()`.
+
+- **Rule:** Treat every `SetSelection(i)` as an event source.
+  **Why:** it always sends `wxEVT_COMMAND_RADIOBOX_SELECTED` (= `wxEVT_RADIOBOX`), for programmatic calls and for the
+  current index too — the opposite of `wxRadioBox::SetSelection` (`interface/wx/ctrlsub.h:102-103`). The constructor
+  fires one before anyone can bind.
+  ```cpp
+  m_group->SetSelection(cfg.mode);                                            // Wrong: re-enters on_mode_changed
+  { m_syncing = true; m_group->SetSelection(cfg.mode); m_syncing = false; }  // Right: handler returns if m_syncing
+  ```
+- **Rule:** Don't read `GetEventObject()` in its handler.
+  **Why:** the event carries the group's id but no event object (null).
+
+## TextInput
+
+`::TextInput` (`Widgets/TextInput.cpp`, `TextInput::Create`) is a `wxNavigationEnabled<StaticBox>` frame around a
+real `wxTextCtrl` (on MSW the `TextCtrl` subclass in `Widgets/TextCtrl.h`, which overrides `DoMSWControlColor`).
+- `text` is the initial value; `label` is a **painted side label** (`Body_12`), `icon` a 16 px SVG name
+  (`SetIcon`, `SetIcon_1` for a second icon, `SetStaticTips` for a grey hint line under the label).
+- `style` goes to the inner control with `wxTE_PROCESS_ENTER | wxBORDER_NONE` added and alignment bits stripped;
+  the wrapper keeps the alignment bits and uses them to place label and icons, so typed text is left-aligned unless
+  you set `wxTE_RIGHT`/`wxTE_CENTRE` on `GetTextCtrl()` afterwards (alignment can change after creation on MSW, GTK
+  and macOS, `interface/wx/textctrl.h:1398-1399`).
+- Inner font `Body_14`, inner context menu disabled (empty `wxEVT_RIGHT_DOWN` handler), tooltips forwarded
+  (`DoSetToolTipText`), `Enable()` also enables the inner control and recolours it.
+- `TextInput::SetLabel()` changes the side label, not the text. The value API is `GetTextCtrl()->GetValue()/
+  SetValue()/ChangeValue()`; `SetHint`, validators and `SetMaxLength` also go on `GetTextCtrl()`.
+
+Event routing:
+- `wxEVT_TEXT` is a command event from the inner control; it propagates to the wrapper and beyond, carrying the
+  **inner** control's id and event object.
+- `wxEVT_TEXT_ENTER` and `wxEVT_KILL_FOCUS` are caught on the inner control, `OnEdit()` runs (ComboBox resolves the
+  typed text there), then they are re-sent with the wrapper's id via `ProcessEventLocally`, which runs the wrapper's
+  own handlers but [source] never `TryAfter`, so never the parents (`src/common/event.cpp:1582-1589`; the
+  `interface/wx/event.h:626-651` text says it calls `TryAfter`). The event object stays the inner control.
+- The internal ENTER handler does not `Skip()`: Enter in a TextInput never activates a dialog's default button
+  (`interface/wx/textctrl.h:1324-1331`).
+- Key, char and focus-in events exist only on `GetTextCtrl()`.
+
+Pitfalls:
+- **Rule:** Bind ENTER and KILL_FOCUS on the TextInput (or `GetTextCtrl()`), never on a parent; bind TEXT on the
+  input without an id filter.
+  ```cpp
+  dialog->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this, input->GetId());   // Wrong: never reaches the dialog
+  input->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this);                    // Right
+  panel->Bind(wxEVT_TEXT, h, input->GetId());                             // Wrong: TEXT carries the inner id
+  input->Bind(wxEVT_TEXT, h);                                             // Right
+  ```
+  Cite: `TextInput::Create`; `src/common/event.cpp:1582-1589`.
+- **Rule:** A handler bound on `GetTextCtrl()` for ENTER or KILL_FOCUS must `Skip()`.
+  **Why:** it runs before the internal handler (most-recently-bound first), which does `OnEdit()` and the re-dispatch.
+- **Rule:** Don't `static_cast` the event object to `TextInput*`.
+  **Why:** every TextInput event's object is the inner `wxTextCtrl`.
+- **Rule:** Use `ChangeValue` for model→view updates.
+  **Why:** `wxTextEntry::SetValue` sends `wxEVT_TEXT` (`interface/wx/textentry.h:539-542`), [source] even for
+  identical text (`src/common/textentrycmn.cpp:236-254`).
+- **Rule:** Use a raw `wxTextCtrl` with `wxTE_MULTILINE` for multi-line text.
+  **Why:** `TextInput::DoSetSize` sets only the inner control's width and keeps it vertically centred at the height
+  it got at creation (its initial best size), so a multi-line TextInput never grows its text area. Hints on
+  multi-line controls are ignored except on MSW and GTK2 (`interface/wx/textentry.h:485-486`), so not on macOS or
+  GTK3; on macOS call `OSXDisableAllSmartSubstitutions()`
+  on any control holding G-code, paths or URLs (`references/controls-dataview.md §wxTextCtrl`).
+
+## ComboBox and DropDown
+
+`::ComboBox` (`Widgets/ComboBox.cpp`) is `wxWindowWithItems<TextInput, wxItemContainer>` plus an owned `DropDown drop`
+over its `std::vector<DropDown::Item> items`, so the `wxItemContainer` API (`Append/Insert/Set/Clear/Delete/
+GetCount/GetString/FindString/GetSelection/SetSelection/GetStringSelection`) works, and `GetValue/SetValue` mirror the
+wxTextEntry side of `wxComboBox`. `ComboBox::SetLabel/GetLabel` are the displayed value — the opposite of
+`TextInput::SetLabel` — and `SetTextLabel/GetTextLabel` reach the painted side label.
+- `wxCB_READONLY` hides the text control and paints the value (font `Body_14`, focused background `#E5F0EE`): choice
+  semantics. Without it the combo is editable.
+- Orca style flags: `CB_NO_DROP_ICON` (no arrow), `CB_NO_TEXT` (icon-only items).
+- Per-item data (`DropDown::Item`): text, `icon` (list), `icon_textctrl` (shown in the closed combo),
+  `text_static_tips`, `data` (`void*`), `group_key`/`group_label` (a group opens a sub-dropdown), `alias`, `tip`,
+  `flag`, `style` = `DD_ITEM_STYLE_SPLIT_ITEM` (separator-style header), `DD_ITEM_STYLE_DISABLED` (not selectable by
+  click), `DD_ITEM_STYLE_DIMMED` (grey, selectable). `Append(text, bitmap, group, clientData, item_style)` overloads,
+  `SetItems(std::vector<DropDown::Item>)`, `SetItemTooltip/Alias/Bitmap`, `SetFlag`.
+- `GetDropDown()` exposes the popup (`SetUseContentWidth(true[, limit])`, `SetAlignIcon`, colours).
+  `SetKeepDropArrow(true)` keeps the arrow and shows the item icon as a second icon. `ForceDropdownOpen()` opens it
+  programmatically (data-view editors use this).
+- Opening: click (debounced by `DropDown::HasDismissLongTime()`, ≥ 20 ms since the last dismissal, so the click that
+  dismissed the popup does not reopen it), Enter/Space. Up/Down/Left/Right on a focused read-only combo step the
+  selection and send `wxEVT_COMBOBOX` (in an editable combo the keys go to the inner text control). Mouse-wheel selection is disabled (handler commented out of the event table). Scrolling an
+  ancestor `wxScrollHelper` hides the popup.
+
+Events: see §Event semantics. Picking an item sends `wxEVT_COMBOBOX` even when it is already selected. Typing into
+an editable combo sends `wxEVT_TEXT` per keystroke and **no** `wxEVT_COMBOBOX`: the commit is `wxEVT_TEXT_ENTER`/
+`wxEVT_KILL_FOCUS` on the combo, after `OnEdit()` has matched the text to an item (exact, case-sensitive) and re-set
+it (one more `wxEVT_TEXT`).
+
+Pitfalls:
+- **Rule:** Use `SelectAndNotify(n)` when listeners must react; `SetSelection(n)` is silent for `wxEVT_COMBOBOX` and
+  returns early when `n` is already selected.
+  **Why:** matches wx (`interface/wx/ctrlsub.h:102-103`), but in an **editable** combo (or one with `CB_NO_TEXT`)
+  `SetSelection`/`SetValue` go through `GetTextCtrl()->SetValue()` and send a propagating `wxEVT_TEXT`; guard
+  `wxEVT_TEXT` handlers during sync.
+- **Rule:** Store only untyped `void*` client data and free it yourself.
+  **Why:** every `Append` overload calls `SetClientDataType(wxClientData_Void)`, and declaring them hides every base
+  `wxItemContainer::Append` (the `wxClientData*` and `wxArrayString` ones included); `DeleteOneItem()` bypasses the
+  base client-object reset. Typed `wxClientData` ownership (`references/controls-dataview.md §Item containers`) does
+  not apply.
+- **Rule:** After `Clear()`, `Insert()`, `Set()` or `Delete()`, call `SetSelection`/`SetValue`.
+  **Why:** they reset the selection to -1 (`DropDown::Invalidate(true)`) but leave the shown text.
+- **Rule:** Bind `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` on the combo without an id filter.
+  **Why:** they are created with id 0 and no event object; any ancestor bound without a filter receives them from
+  every combo below it.
+
+`DropDown` (`Widgets/DropDown.cpp`) standalone: a `PopupWindow` (`wxPU_CONTAINS_CONTROLS`, `wxBG_STYLE_PAINT`,
+`wxBufferedPaintDC`) drawing `items`, which it holds **by reference** — the vector must outlive the popup, and
+`Invalidate()` must follow any edit of it. `Popup()` on GTK sets the toplevel as transient parent explicitly (a
+data-view editor can get focus before wxGTK infers one); `Dismiss()` refuses while its sub-dropdown is shown;
+`OnDismiss()` sends `EVT_DISMISS` and stamps the dismissal time; `ShouldDismissOnTopWindowDeactivate()` keeps chained
+dropdowns open on Wayland, where mapping a grabbing child popup deactivates the toplevel; on macOS it binds an empty
+`wxEVT_IDLE` handler to stop wx's idle-time capture release/re-capture ([source] `src/common/popupcmn.cpp:108-111,
+439-472`). It captures without a `HasCapture()` guard, and its capture-lost handler replays release, which can commit
+the hovered item. Popup mechanics: `references/popups-menus.md`.
+
+## SpinInput and TempInput
+
+`SpinInput` (`Widgets/SpinInput.cpp`) is a `wxNavigationEnabled<StaticBox>` with an inner `TextCtrl` validated by
+`wxTextValidator(wxFILTER_DIGITS)`, two arrow `Button`s (not keyboard-focusable) and a repeat `wxTimer`.
+- `text` (if it parses) overrides `initial`; `label` is a painted side label; `style` goes to the inner control
+  (`wxTE_PROCESS_ENTER` added).
+- `SetValue(int|wxString)` clamps to `[min, max]` and stores; `GetValue()` returns the **last committed** value, not
+  the text being typed; `SetRange(min, max)` stores the bounds without re-clamping; `SetStep`.
+- Commits — parse, clamp, `wxEVT_SPINCTRL` — on Enter, on kill-focus and on Up/Down keys (which do not step past a
+  bound) only if the value changed, but on **every** arrow-button press and auto-repeat tick (while held), even when
+  the value is pinned at `min`/`max` (`SpinInput::createButton`, `SpinInput::onTimer`). Mouse-wheel stepping is
+  disabled (handler commented out of the event table).
+- `EVT_SPINCTRL_TEXT` (int + string) fires on every keystroke that leaves a parseable integer.
+- Enter and kill-focus are re-dispatched to the spinner with `ProcessEventLocally`, as in TextInput. Unlike
+  TextInput, `SpinInput::onTextLostFocus` never `Skip()`s the inner control's `wxEVT_KILL_FOCUS` (it skips a local
+  copy), although focus handlers should (`interface/wx/event.h:3410-3412`); a `KILL_FOCUS` handler bound on
+  `GetTextCtrl()` runs before it and must `Skip()` to keep the commit.
+
+Pitfalls:
+- **Rule:** Bind `wxEVT_SPINCTRL` with a `wxCommandEvent&` handler and read `GetValue()` from the spinner.
+  **Why:** `wxEVT_SPINCTRL` is declared with `wxSpinEvent` (`include/wx/spinctrl.h:22`) but `SpinInput::sendSpinEvent`
+  sends a plain `wxCommandEvent` without `SetInt`; a `wxSpinEvent&` handler reads `GetPosition()` == 0 from an object
+  of the wrong type.
+  ```cpp
+  spin->Bind(wxEVT_SPINCTRL, [](wxSpinEvent& e) { use(e.GetPosition()); });           // Wrong
+  spin->Bind(wxEVT_SPINCTRL, [spin](wxCommandEvent&) { use(spin->GetValue()); });     // Right
+  ```
+- **Rule:** Use `SpinInput` only for non-negative integer ranges.
+  **Why:** `wxFILTER_DIGITS` rejects `-` (and `.`, `+`) (`interface/wx/valtext.h:43-52`); a negative minimum can be
+  reached only with the arrow buttons or Up/Down keys.
+- **Rule:** Set the range before the value.
+  **Why:** `SetRange` does not re-clamp an existing value.
+- **Rule:** Commit explicitly before reading when the user may still be typing.
+  **Why:** `GetValue()` is the last committed value. Dialogs sometimes call `Disable()` to force the kill-focus
+  commit (`CloneDialog`), which depends on the platform delivering `wxEVT_KILL_FOCUS` to the disabled focused child
+  — not a wx contract. Parse `GetTextCtrl()->GetValue()` and call `SetValue` yourself when it matters.
+- **Rule:** Expect `SetValue` to emit `EVT_SPINCTRL_TEXT` and a propagating `wxEVT_TEXT`.
+  **Why:** it writes through the inner `wxTextCtrl::SetValue`.
+
+`TempInput` (`Widgets/TempInput.cpp`, device pages) is a separate `wxNavigationEnabled<StaticBox>` with normal/active
+icons, target and current temperatures (`SetTagTemp`, `SetCurrTemp`) and a warning state (`Warning(bool,
+WARNING_TOO_HIGH | WARNING_TOO_LOW | WARNING_UNKNOWN)`); on commit it **posts** `wxCUSTOMEVT_SET_TEMP_FINISH` to its
+**parent** (`TempInput::SetFinish`; int = the constructor's `type`, no id, no event object), so bind it on the parent
+and tell inputs apart by the int. It guards re-entry with `m_on_changing`, because a handler that opens a dialog
+moves focus and re-triggers the kill-focus commit — copy that guard for any commit-on-kill-focus widget whose
+handler can show UI.
+
+## Tab systems
+
+Three distinct mechanisms; don't confuse them:
+
+| | `TabCtrl` (`Widgets/TabCtrl.cpp`) | `Notebook` (`GUI/Notebook.hpp`) | `wxSimplebook` |
+|---|---|---|---|
+| What | a bare tab **bar**: one `Button` per tab in a `StaticBox` | `wxBookCtrlBase` with a `ButtonsListCtrl` header (one `Button` per tab) | standard stacked-page container, no UI |
+| Content | **caller** shows/hides it | owns pages | owns pages |
+| Events | `wxEVT_TAB_SEL_CHANGING` (int = old) → `wxEVT_TAB_SEL_CHANGED` (int = new), plain `wxCommandEvent`s | posted `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` (id = page) → `wxEVT_NOTEBOOK_PAGE_CHANGING`/`_CHANGED` | PAGE_CHANGING/CHANGED from `SetSelection` only (`interface/wx/simplebook.h:28-31`) |
+| Use | settings-style category strips (Preferences) | MainFrame's main tabs (Home, Prepare, Preview, Device, …) | headerless page switching (`SelectMachine.hpp`, `ReleaseNote.cpp`, `StatusPanel`) |
+
+`TabCtrl`: `AppendItem(text[, image, selImage, clientData])`, `AppendItem(text, bitmap)`, `DeleteItem`,
+`DeleteAllItems`, `SelectItem(i)`/`Unselect()`, `GetSelection`, `SetItemText/Bitmap/Data`, `SetItemBold(i, bool)`,
+`SetItemTextColour(i, StateColor)`, `SetItemIndicator(i, bool)` (dot after the label), `SetFont`, `Rescale()`.
+`AssignImageList` is Orca's own method (takes ownership), not `wxWithImages`, and nothing draws from that list:
+`AppendItem` ignores its `image`, `selImage` and `clientData` arguments — give icons with `AppendItem(text, bitmap)`/
+`SetItemBitmap` and data with `SetItemData`. Call `SetFont` before `SetItemBold`: it derives the bold font that
+`SetItemBold` applies. Selecting a tab flips the tab Buttons'
+`Checked` state by sending them `wxEVT_CHECKBOX` command events (id 0, object = the tab `Button`); those propagate up
+the parent chain, so an ancestor bound to `wxEVT_CHECKBOX` without an id/object filter sees them. `PreferencesDialog::
+create` is the canonical usage:
+
+```cpp
+m_pref_tabs = new TabCtrl(this, wxID_ANY, wxDefaultPosition, wxDefaultSize, wxBORDER_NONE | wxWANTS_CHARS);
+m_pref_tabs->SetFont(Label::Body_14);                       // before SetItemBold
+m_pref_tabs->AppendItem(_L("General"));                     // one per page (create_items)
+m_pref_tabs->Bind(wxEVT_TAB_SEL_CHANGED, [this](wxCommandEvent& e) {
+    Freeze();
+    const int sel = e.GetSelection();                       // GetInt()
+    for (size_t i = 0; i < m_pref_tabs->GetCount(); ++i) {
+        m_pref_tabs->SetItemBold(i, int(i) == sel);
+        f_sizers[i]->Show(int(i) == sel);                   // the caller switches content
+    }
+    Layout(); Thaw();
+});
+StateColor item_color(std::make_pair(wxColour("#6B6B6C"), (int) StateColor::NotChecked),
+                      std::make_pair(wxColour("#363636"), (int) StateColor::Normal));
+for (size_t i = 0; i < m_pref_tabs->GetCount(); ++i) m_pref_tabs->SetItemTextColour(i, item_color);
+m_pref_tabs->SelectItem(0);
+```
+
+- **Rule:** Don't try to veto a TabCtrl switch from `wxEVT_TAB_SEL_CHANGING`.
+  **Why:** it is a plain `wxCommandEvent` and `TabCtrl::sendTabCtrlEvent` always returns true; `SelectItem` continues.
+
+`Notebook`: pages are inserted and addressed by a stable id (`AddPage(id, page, text, bmp_name)`,
+`InsertPage(n, id, page, text, bmp_name, bSelect)`, `FindPageByName(id)`, `SelectPageByName(id)`, `GetPageName(n)`,
+`GetSelectedPageName()`); a page inserted unselected is hidden at once; one window may sit under two tabs (Prepare
+and Preview share the `Plater`). A header click posts `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` to the notebook, whose own handler calls
+`SetSelection(page)`; a handler bound later (MainFrame) runs first and must `Skip()` to let the switch happen.
+`SetSelection` sends the vetoable PAGE_CHANGING and PAGE_CHANGED (`interface/wx/bookctrl.h:177-178`) and hides all
+other pages; `ChangeSelection` is silent (`:194-195`). `wxEVT_BOOKCTRL_PAGE_CHANGED` is the same event type as
+`wxEVT_NOTEBOOK_PAGE_CHANGED` in Orca's build (`include/wx/bookctrl.h:433-434`); `Notebook` sends the
+`wxEVT_BOOKCTRL_*` names.
+
+`wxSimplebook`: switch with `ChangeSelection()` (silent) or `SetSelection()` (events); pages must be created with
+the book as parent; page titles are mnemonic-interpreted (`references/controls-dataview.md §Book controls`).
+
+## StaticBox, LabeledStaticBox, StaticLine
+
+`StaticBox` (`Widgets/StaticBox.cpp`) as a container: a rounded, bordered group frame. API: `SetCornerRadius`,
+`SetBorderWidth`, `SetBorderColor(StateColor)`/`SetBorderColorNormal`, `SetBorderStyle(wxPenStyle)`,
+`SetBackgroundColor(StateColor)`/`SetBackgroundColorNormal`, `SetBackgroundColor2` (vertical gradient),
+`SetTopMargin`, `ShowBadge(bool)` (corner badge bitmap), static `GetParentBackgroundColor(parent)`. `wxBORDER_NONE`
+makes the border 0. Its children inherit its fill through `GetParentBackgroundColor`. Authoring widgets on it:
+`references/painting-custom-widgets.md`.
+
+`LabeledStaticBox` (`Widgets/LabeledStaticBox.cpp`) is a real `wxStaticBox` subclass, so it works as the box of a
+`wxStaticBoxSizer`; it paints a rounded border (`Head_14` label in the border gap, `#DBDBDB` border, white fill)
+itself (`wxBG_STYLE_PAINT` except on macOS, where `staticbox_remove_margin` is applied and the
+`GetBordersForSizer` override sets the side padding other platforms use). It is not focusable. `SetCornerRadius`, `SetBorderWidth`,
+`SetBorderColor(StateColor)`, `SetFont`, `Enable`. There is no `StaticGroup` class.
+
+- **Rule:** Create the controls inside the box as children of the box.
+  **Why:** since 2.9.1 wx "strongly recommends" box children over siblings to avoid repaint problems
+  (`interface/wx/statbox.h:16-24`); `sizer->GetStaticBox()` is the parent to use.
+  ```cpp
+  auto* box   = new LabeledStaticBox(this, _L("Network"));
+  auto* sizer = new wxStaticBoxSizer(box, wxVERTICAL);
+  sizer->Add(new ::CheckBox(box), 0, wxALL, FromDIP(5));      // parent = box
+  ```
+- **Rule:** To change the label, recreate the box.
+  **Why:** the label is captured and measured in `Create()`; there is no `SetLabel` override, so `SetLabel` changes the
+  native text the widget never paints.
+- **Rule:** Don't expect a disabled look.
+  **Why:** its `StateColor`s list `Normal` before `Disabled`, and the first match wins
+  (`references/colours-dark-mode.md §StateColor`), so the disabled colours never apply.
+
+`StaticLine` (`Widgets/StaticLine.cpp`): horizontal or vertical separator with optional label and icon;
+`SetLineColour(wxColour)`, `SetLabel`, `SetIcon`, `Rescale()`; line and text colours go through `darkModeColorFor` at
+paint time. Use it instead of `wxStaticLine`.
+
+## ProgressBar
+
+`ProgressBar` (`Widgets/ProgressBar.cpp`) is a `wxWindow` with a rounded track and fill (MSW draws through a memory
+DC + `wxGCDC` for anti-aliasing). `SetValue(step)` (re-enables after `Disable(text)`), `SetProgress(step)` (ignores
+negatives), `Reset()`, `ShowNumber(bool)`, `SetRadius`, `SetHeight(h)` (sets min height and radius `h/2`), and
+`Disable(wxString text)`, which draws an orange "disabled" bar with `text` and hides `wxWindow::Disable()` (name
+hiding: `bar->Disable()` does not compile).
+
+Pitfalls:
+- **Rule:** Pass dark-mapped colours and re-set them on theme change.
+  **Why:** track, fill and text are plain `wxColour`s painted as given; nothing maps them.
+  ```cpp
+  bar->SetProgressBackgroundColour(StateColor::darkModeColorFor(wxColour("#009688")));   // sets the FILL
+  ```
+- **Rule:** Mind the swapped setter names.
+  **Why:** `SetProgressForedColour` sets the **track** (`m_progress_background_colour`) and
+  `SetProgressBackgroundColour` sets the **fill** (`m_progress_colour`).
+- **Rule:** Use `SetHeight(FromDIP(h))` for a bar thinner than 14 px.
+  **Why:** `ProgressBar::SetMinSize` returns without doing anything (width included) when the height is below its
+  `miniHeight` of 14 — so `SetMinSize(wxSize(w, -1))` is ignored too.
+- **Rule:** Use `ShowNumber` only with `max == 100`.
+  **Why:** it draws the raw step followed by `%`.
+- `Rescale()` is empty: re-set the height in `on_dpi_changed`.
+
+## ScrolledWindow
+
+`ScrolledWindow` (`Widgets/ScrolledWindow.cpp`) is a `wxScrolled<wxWindow>` that hides the native scrollbars and
+draws `MyScrollbar`s (`Widgets/Scrollbar.cpp`) of `scrollbarWidth` in a `marginWidth` strip; content goes on
+`GetPanel()` (the scroll target). Its internal panels are sized from the constructor `size`, so pass a real size
+(`FromDIP`/`em`-based, as `Search.cpp` does). Use raw `wxScrolledWindow` for ordinary scrolling.
+
+- **Rule:** Create it with `wxVSCROLL`.
+  **Why:** the mouse-wheel handler forwards to the vertical bar unconditionally and `SetBackgroundColour` touches the
+  vertical-bar panels unconditionally, so a `wxHSCROLL`-only instance dereferences null pointers; with neither flag
+  `GetPanel()` is null. With both flags only the vertical bar is built.
+- `MyScrollbar` paints on a `wxClientDC` and forces `Refresh(); Update();` — do not copy its painting
+  (`references/painting-custom-widgets.md`).
+
+## PopupWindow
+
+`PopupWindow` (`Widgets/PopupWindow.cpp`) derives `wxPopupTransientWindow` and adds per-platform dismissal hooks.
+Use it for every transient popup, knowing which parts are automatic:
+
+| Port | Added behaviour |
+|---|---|
+| GTK (X11 and Wayland) | `Create` binds `wxEVT_ACTIVATE` on the first top-level window strictly above the parent (`GetTopParent` starts at the parent's parent, so a popup parented directly to a dialog watches the dialog's own parent); deactivation → `DismissAndNotify()` unless `ShouldDismissOnTopWindowDeactivate()` (virtual) returns false — `DropDown` uses that to keep chained popups open on Wayland |
+| MSW | dismissal on toplevel deactivate/iconize/hide is **opt-in**: call `BindUnfocusEvent()` (MSW-only member); the destructor unbinds. Its activate handler does not `Skip()`, so while the popup exists the toplevel's earlier-bound `wxEVT_ACTIVATE` handlers and wx's focus save/restore (`wxTopLevelWindowMSW::OnActivate`, `src/msw/toplevel.cpp:1326`) do not run [source] |
+| macOS | with `wxPU_CONTAINS_CONTROLS` it hit-tests and forwards mouse and enter/leave events to child controls (`OnMouseEvent2`); wx documents the flag as MSW focus behaviour only (`interface/wx/popupwin.h:17-26`) |
+
+Command events from controls inside the popup stop at the popup on MSW and macOS ([source]
+`src/common/popupcmn.cpp:135`) but bubble on to the popup's parent on GTK, whose `wxPopupWindow::Create` never sets
+`wxWS_EX_BLOCK_EVENTS` (`src/gtk/popupwin.cpp`; `references/events.md §5`); bind them on the popup or its children,
+as `ComboBox` binds `drop`'s `wxEVT_COMBOBOX`, and don't let an ancestor's unfiltered handler also act on them. When a click on the opener both
+dismisses and reopens the popup, gate the reopen on `DropDown::HasDismissLongTime()` or an equivalent timestamp.
+Dismissal contracts, per-port mechanics and parenting rules: `references/popups-menus.md`.
+
+## ProgressDialog, WebView and device-page composites
+
+- **`Slic3r::GUI::ProgressDialog`** (`Widgets/ProgressDialog.cpp`): a `wxDialog` copy of wx's generic progress dialog
+  with Orca styling and a `Button` for Cancel; wx-compatible API (`Update(value, msg, &skip)`, `Pulse`,
+  `WasCancelled`, `WasSkipped`, `Resume`, `SetRange`). `Update` yields to the event loop
+  (`YieldFor(wxEVT_CATEGORY_UI | wxEVT_CATEGORY_USER_INPUT)`), so handlers can re-enter; usage rules and the Jobs
+  alternative: `references/threads-timers-app.md`.
+- **`WebView`** (`Widgets/WebView.cpp`): static helpers `CreateWebView(parent, url)`, `LoadUrl`, `RunScript`,
+  `CheckWebViewRuntime`, `RecreateAll()` + `EVT_WEBVIEW_RECREATED`; `WebViewHostDialog` (`Slic3r::GUI`) is the base of
+  Orca's web dialogs: `references/webview-gl-aui-media.md`.
+- **Device-page composites** (Monitor/Device UI; reuse inside those pages, don't copy their painting as a model):
+  `SideButton`, `SideTools`/`SideToolsPanel` (`Slic3r::GUI`), `SidePopup` (`SideMenuPopup.hpp`), `StepCtrl`/
+  `StepIndicator` (`EVT_STEP_CHANGING`/`EVT_STEP_CHANGED`), `TempInput`, `ImageSwitchButton`/`FanSwitchButton`,
+  `AxisCtrlButton`, `FanControl` family, `AMSControl`/`AMSItem` family/`FilamentLoad`, `MultiNozzleSync` tables
+  (`Slic3r::GUI`), `CheckList`, `ErrorMsgStaticText`, `AnimaIcon` (`AnimaController.hpp`), `RoundedRectangle`.
+
+## Debugging widgets
+
+wxInspector is compiled into Debug/RelWithDebInfo builds (the top-level `CMakeLists.txt` defines
+`WXINSPECTOR_DISABLE` when `BBL_RELEASE_TO_PUBLIC` is set true or, when that variable is undefined, for the Release
+configuration; `references/platforms.md §wxInspector`). Every `DPIAware` window installs its accelerator
+(`SetupInspectorAccelerator`, Ctrl+Shift+I, Cmd+Shift+I on macOS); the plugins in `src/slic3r/Utils/wxInspectorPlugins/`
+(`CustomWidgetsPlugin`) show Button style/type, CheckBox half state, TextInput, SwitchButton, ProgressBar, Label and
+LabeledStaticBox properties. The accessors commented "only meant to be used by inspector" (`Button::GetStyle`,
+`CheckBox::IsHalfChecked`, `TextInput::GetCornerRadius`, `LabeledStaticBox::GetBorderColor`, …) exist for it — don't
+build features on them. A later `SetAcceleratorTable` on a DPIAware window replaces the inspector's table.

.claude/skills/orca-wxwidgets/references/platforms.md

@@ -0,0 +1,931 @@
+# Platforms, the wx build, and platform-specific code
+
+Read this when code has to differ per platform, when a bug shows up on only one OS, toolkit or display
+server, or when you need to know how Orca's wxWidgets is built. It covers the wx fork and its build
+options, platform macros, per-platform summaries that point into the topic files, and where
+platform-specific code lives. It also owns runtime X11/Wayland detection, the Wayland gap list, custom
+title bars and window decoration, GTK native-chrome removal, and the cross-platform test checklist.
+
+Contents: [Rules](#rules) · [The wx build Orca uses](#the-wx-build-orca-uses) ·
+[Platform macros and native handles](#platform-macros-and-native-handles) ·
+[Per-platform summaries](#per-platform-summaries) · [The ifdef landscape](#the-ifdef-landscape) ·
+[Runtime X11/Wayland detection](#runtime-x11wayland-detection) · [Wayland gaps](#wayland-gaps) ·
+[Window decoration and custom title bars](#window-decoration-and-custom-title-bars) ·
+[GTK native chrome and GTK size calls](#gtk-native-chrome-and-gtk-size-calls) ·
+[wx 3.3 migration notes](#wx-33-migration-notes) ·
+[Cross-platform testing checklist](#cross-platform-testing-checklist)
+
+## Rules
+
+1. Every GUI change must work on Windows (wxMSW), macOS (wxOSX/Cocoa) and Linux wxGTK3, under both
+   X11 and Wayland. GTK-guarded code must still compile against GTK2, but GTK2 is an opt-out build and
+   not something Orca ships. → [The wx build](#the-wx-build-orca-uses), [Testing](#cross-platform-testing-checklist)
+2. Use the wx toolkit macros (`__WXMSW__`, `__WXOSX__`, `__WXGTK__`, `__WXGTK3__`) when the behaviour
+   comes from wx. Use `_WIN32` / `__APPLE__` / `__linux__` only for OS APIs and in code that is not
+   built against wx (`src/libslic3r`). → [Platform macros](#platform-macros-and-native-handles)
+3. Guard a declaration in the header exactly as its definition is guarded in the `.cpp`, and call a
+   guarded helper only under the same guard. → [Platform macros](#platform-macros-and-native-handles)
+4. Decide X11 vs Wayland at runtime with `is_running_on_wayland()` / `is_running_on_x11()`, and only
+   after GTK is initialised. Read `WAYLAND_DISPLAY` / `DISPLAY` / `GDK_BACKEND` only before GTK starts
+   (`CLI::run`). → [Runtime detection](#runtime-x11wayland-detection)
+5. On Wayland, none of these work: global pointer coordinates, positioning top-level windows,
+   drawing through `wxClientDC`, `Update()`, `SetIcon`, `WarpPointer` (outside narrow conditions),
+   AUI floating panes, `wxUIActionSimulator`. → [Wayland gaps](#wayland-gaps)
+6. Orca's wx has no SVG support and no asserts. Never call `wxBitmapBundle::FromSVG*`. Wherever the
+   wx docs say a call "asserts", expect a silent failure in Orca and check the precondition yourself.
+   → [The wx build](#the-wx-build-orca-uses)
+7. Change wx build options or patches only in `deps/wxWidgets/wxWidgets.cmake`, and make the same
+   change in the wxWidgets module of the Flatpak manifest. → [The wx build](#the-wx-build-orca-uses)
+8. On MSW, `MainFrame` draws its own non-client area. Mask `WS_CAPTION` out of every non-client
+   computation, and handle `WM_NCCALCSIZE` for the maximised case yourself.
+   → [MSW title bar](#msw-the-mainframe-custom-title-bar)
+9. On Linux, move and resize the borderless main frame through the window manager
+   (`gtk_window_begin_move_drag` / `gtk_window_begin_resize_drag`). Never call `Move()` or `SetSize()`
+   from mouse coordinates. → [GTK frame](#linux-gtk-the-borderless-mainframe)
+10. To show an undecorated top-level window on Wayland, install an empty client-side titlebar and then
+    call `gtk_window_set_decorated(false)`, both in the constructor, before control returns to the
+    event loop.
+    → [Undecorated windows on Wayland](#wayland-undecorated-top-level-windows-splash)
+11. Remove GTK theme borders from custom-drawn controls with `RemoveButtonBorder` / `RemoveInputBorder`
+    (`__WXGTK__` only). Call raw GTK size functions only with strictly positive sizes.
+    → [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls)
+12. Put platform glue where it already lives: Cocoa code in `.mm` files listed in the `APPLE` block of
+    `src/slic3r/CMakeLists.txt`, Win32 messages in `MSWWindowProc` overrides, and GDK/GTK calls behind
+    `__WXGTK__` with the GTK header included under the same guard. → [Ifdef landscape](#the-ifdef-landscape)
+13. Before fixing something "for platform X", find the wx mechanism that differs there (the
+    per-platform summaries point to it) and check whether the same bug class exists on the other
+    platforms. → [Per-platform summaries](#per-platform-summaries)
+
+## The wx build Orca uses
+
+### Source, pin and local patch
+
+- `deps/wxWidgets/wxWidgets.cmake` builds `https://github.com/SoftFever/Orca-deps-wxWidgets` at tag
+  **`v3.3.2`** (`GIT_SHALLOW ON`, submodules `3rdparty/catch`, `3rdparty/pcre` and `3rdparty/libwebp`
+  only). The fork carries Orca's build fixes, the clang-cl fix among them; do not duplicate
+  a fork fix as a local patch under `deps/wxWidgets/` (cc390f11ee removed the local
+  `0001-Clang-CL-fix.patch` once the fork carried the fix). The fork's clang-cl fix is the MSVC lib-dir
+  selection in the installed `wxWidgetsConfig.cmake`: it looks for `<prefix>_<arch>_lib` (or `_dll`)
+  under the consuming compiler's prefix first and then the sibling one (`clang` ↔ `vc`), because cl
+  and clang-cl share an ABI and either can consume either build
+  (`build/cmake/wxWidgetsConfig.cmake.in:53-73`).
+- **The one local patch** is `deps/wxWidgets/0001-macos-use-srgb-colour-components.patch`, applied
+  only `if (APPLE)`. The `PATCH_COMMAND` first runs `git checkout -f -- src/osx/cocoa/colour.mm` and
+  then `git apply`, so the step can run again safely (a7775296b0). The patch makes the wxOSX
+  `wxColour` component getters (`wxNSColorRefData::Red/Green/Blue/Alpha` and `IsSolid`) convert the
+  `NSColor` with `[NSColorSpace sRGBColorSpace]` instead of `NSCalibratedRGBColorSpace`, so colours
+  read back on macOS match their sRGB values (custom-colour accuracy). Colour usage:
+  `references/colours-dark-mode.md`.
+- The checked-out source is the tree that every wx citation in this skill refers to:
+  `deps/build/<arch>/dep_wxWidgets-prefix/src/dep_wxWidgets` on macOS and
+  `deps/build/dep_wxWidgets-prefix/src/dep_wxWidgets` on Linux. Find it with
+  `find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets'`. On macOS its
+  `src/osx/cocoa/colour.mm` already has the patch applied.
+- **Flatpak builds wx separately.** `deps/CMakeLists.txt` leaves `dep_wxWidgets` out of the deps
+  target when `FLATPAK` is set. Instead, `scripts/flatpak/com.orcaslicer.OrcaSlicer.yml` has its own
+  `wxWidgets` module whose config-opts "mirror deps/wxWidgets/wxWidgets.cmake with FLATPAK=ON,
+  DEP_WX_GTK3=ON": `-DwxBUILD_TOOLKIT=gtk3`, a shared build (`wxBUILD_SHARED=ON`,
+  `BUILD_SHARED_LIBS=ON`, `d` debug postfix), and `wxUSE_LIBWEBP=sys`, because the builtin webp
+  libraries are installed only by static builds. It links with lld and pins the fork's tag
+  `orca-3.3.2` at a fixed commit. Option and version changes must be made in both files.
+
+### Toolkit per platform
+
+| Platform | wx port | How it is selected |
+|---|---|---|
+| Windows | wxMSW | default port; the Edge WebView backend is built only for MSVC-family compilers |
+| macOS | wxOSX/Cocoa | default port; wx's exported targets add `__WXOSX_COCOA__;__WXMAC__;__WXOSX__` |
+| Linux | **wxGTK3** | `deps/CMakeLists.txt` declares `option(DEP_WX_GTK3 "Build wxWidgets against GTK3" ON)` (default ON since 026499c5b7, #10294), which gives `-DwxBUILD_TOOLKIT=gtk3`. The root `CMakeLists.txt` sets `SLIC3R_GTK "3"`, so `src/CMakeLists.txt` finds wx through `wx-config --toolkit=gtk${SLIC3R_GTK}` and `src/slic3r/CMakeLists.txt` links `GTK${SLIC3R_GTK}`. Flatpak uses gtk3 too. |
+
+**GTK2 is an opt-out, not a default.** `wxWidgets.cmake` starts from `_gtk_ver 2` and switches to 3
+when `DEP_WX_GTK3` is on, so you get GTK2 only by passing `-DDEP_WX_GTK3=OFF` (and `SLIC3R_GTK=2`).
+A GTK2 build loses the following (wx `build/cmake/init.cmake`, `include/wx/features.h`):
+- EGL: `wxUSE_GLCANVAS_EGL` is forced OFF unless GTK3 and EGL are both found (init.cmake:559-561), and
+  `wxHAS_EGL` is set only on GTK3 (:531-540). No EGL means no native Wayland GL.
+- WebKit2: GTK2 gets WebKit1 (init.cmake:568-569); GTK3 uses webkit2gtk-4.1 and falls back to 4.0
+  (:571-577).
+- DIP pixels: `wxHAS_DPI_INDEPENDENT_PIXELS` is defined only for `__WXGTK3__ || __WXMAC__ || __WXQT__`
+  (`include/wx/features.h:115-120`), so GTK2 uses physical pixels and gets no `wxEVT_DPI_CHANGED`.
+- Backend detection: Orca's `wxHAVE_GDK_*` macros are not defined, so `get_linux_display_backend()`
+  always returns `Unknown` ([Runtime detection](#runtime-x11wayland-detection)).
+- Border removal: `RemoveButtonBorder` / `RemoveInputBorder` fall back to a global `gtk_rc` style.
+
+`src/slic3r/CMakeLists.txt` also requires `webkit2gtk-4.1`, a GTK3 library, so a GTK2 GUI would load
+GTK2 and GTK3 into one process. Treat GTK2 as a compile-compatibility target only.
+
+wx is linked statically (`wxBUILD_SHARED=OFF`) everywhere except Flatpak. On Windows and macOS,
+`src/CMakeLists.txt` uses `find_package(wxWidgets 3.3 CONFIG … propgrid)` (`propgrid` is needed by
+wxInspector). On Linux it uses the `wx-config` module mode.
+
+### Build options
+
+The options `deps/wxWidgets/wxWidgets.cmake` passes, with the consequence each one has for GUI code:
+
+| Option | Value | Consequence for GUI code |
+|---|---|---|
+| `wxBUILD_DEBUG_LEVEL` | `0` | wx asserts are compiled out; see [Debug level 0](#debug-level-0-no-wx-asserts) |
+| `wxBUILD_SHARED` | `OFF` (Flatpak: `ON`) | static; private wx globals such as `wxCurrentPopupWindow` can be reached with `extern` |
+| `wxBUILD_PRECOMP` / `wxBUILD_SAMPLES` | `ON` / `OFF` | build speed only |
+| `wxUSE_NANOSVG` | `OFF` | no SVG in wx; see [No SVG](#no-svg-in-orcas-wx). It was disabled to avoid duplicate symbols with Orca's own NanoSVG, which carries an `nsvgRasterizeXY` extension (7658cf9076) |
+| `wxUSE_GLCANVAS_EGL` | `ON` | takes effect only on GTK3 with EGL found; with both EGL and GLX built, wx picks EGL even on X11 unless `PreferGLX()` is called → `references/webview-gl-aui-media.md` §EGL vs GLX |
+| `wxUSE_OPENGL` | `ON` | `wxGLCanvas` |
+| `wxUSE_WEBVIEW` / `wxUSE_WEBVIEW_EDGE` / `wxUSE_WEBVIEW_IE` | `ON` / `ON` only `if (MSVC)` / `OFF` | Edge (WebView2) on Windows, WKWebView on macOS, WebKit2GTK on Linux. `wxUSE_WEBVIEW_CHROMIUM` keeps its default `OFF` (`build/cmake/options.cmake:303`), so Chromium-backend notes never apply. `wxUSE_WEBVIEW_EDGE_STATIC` keeps its default `OFF` (`build/cmake/options.cmake:514`), so the root `CMakeLists.txt` ships `WebView2Loader.dll` from `deps/WebView2/lib/win-<arch>` next to the executable → `references/webview-gl-aui-media.md` §wxWebView backends |
+| `wxUSE_WEBREQUEST` | `ON` | `wxWebSession`/`wxWebRequest` are available (used only for a few image downloads) |
+| `wxUSE_MEDIACTRL` | `ON` | kept for `wxMediaState`; the camera view is Orca's `wxMediaCtrl3`, not a `wxMediaCtrl` |
+| `wxUSE_PRIVATE_FONTS` | `ON` | `wxFont::AddPrivateFont` for the bundled fonts → `references/dpi-bitmaps-fonts.md` |
+| `wxUSE_AUI` | `ON` | Plater docking and `BBLTopbar` (a `wxAuiToolBar`) |
+| `wxUSE_STC` | `OFF` | no `wxStyledTextCtrl` |
+| `wxUSE_DETECT_SM` | `OFF` | no X11 session-manager detection |
+| `wxUSE_REGEX` | `builtin` | — |
+| `wxUSE_LIBPNG` / `ZLIB` / `LIBJPEG` / `EXPAT` | `sys` (from the deps tree) | — |
+| `wxUSE_LIBTIFF` | `OFF` | no TIFF image handler |
+| `wxUSE_LIBWEBP` | `builtin` (Flatpak: `sys`) | WebP image handler is available |
+| `wxUSE_LIBSDL` / `wxUSE_XTEST` | `OFF` | no SDL audio backend; `wxUIActionSimulator` on X11 uses its non-XTest path (`src/unix/uiactionx11.cpp`) |
+
+Options left at wx defaults that matter: LunaSVG is off (`wxUSE_LUNASVG 0` in the installed
+`setup.h`), `wxUSE_STD_CONTAINERS 1`, `WXWIN_COMPATIBILITY_3_0 0`, and `WXWIN_COMPATIBILITY_3_2 1`.
+On macOS `wxUSE_NATIVE_DATAVIEWCTRL` is 1 (`references/controls-dataview.md`).
+
+### Debug level 0: no wx asserts
+
+wx is built with `-DwxBUILD_DEBUG_LEVEL=0`, which `build/cmake/init.cmake:245-246` turns into
+`-DwxDEBUG_LEVEL=0`. `src/slic3r/CMakeLists.txt` also adds `wxDEBUG_LEVEL=0` to `libslic3r_gui` when
+`SLIC3R_STATIC`. The Flatpak module and wxInspector use level 0 as well. At level 0, `wxASSERT`,
+`wxFAIL` and `wxTrap` "do nothing at all", while "wxCHECK macros always check their conditions,
+setting debug level to 0 only makes them silent in case of failure" (`include/wx/debug.h:229-231`,
+`:342-382`).
+
+In practice, misuse that a debug wx would report shows up in Orca as a silent no-op, an early return
+or a wrong result: for example a second `ReleaseMouse`, a late `PreferGLX()`, a second `Destroy()` on
+a transient popup, a window added to a second sizer, `SetCurrent` on a hidden GL canvas, or a
+duplicate AUI pane name. Write "wx would assert in a debug build; in Orca it silently …". When the
+wx docs state a precondition, check it in your own code.
+
+### No SVG in Orca's wx
+
+`wxHAS_SVG` is defined only when `wxHAS_RAW_BITMAP && (wxUSE_NANOSVG || wxUSE_LUNASVG)`
+(`include/wx/features.h:96-97`), and Orca builds with both off. So `wxBitmapBundle::FromSVG`,
+`FromSVGFile` and `FromSVGResource` do not exist (`include/wx/bmpbndl.h:81-101`), using them is a
+compile error, the Tango art provider returns empty bundles (`src/common/arttango.cpp`, `!wxHAS_SVG`
+branch), and wx's AUI tab and dock-art buttons use their non-SVG bitmap fallbacks
+(`src/aui/tabart.cpp:92-137`, `src/aui/dockart.cpp:87-128`) [source]. Orca rasterises SVG with its own
+NanoSVG in `BitmapCache::load_svg` (through `create_scaled_bitmap` / `ScalableBitmap`) →
+`references/dpi-bitmaps-fonts.md`.
+
+### Private headers
+
+The wx 3.3 CMake install does not copy `wx/private`. The `copy_private_headers` step in
+`wxWidgets.cmake` runs after install and copies `include/wx/private`, `include/wx/generic/private`
+and `include/wx/gtk/private` to `include/wx` (MSVC) or `include/wx-3.3/wx` (elsewhere). The cmake
+comment calls this "for accessibility support". The actual consumers are:
+- `Widgets/WebView.cpp`: `wx/private/jsscriptwrapper.h` (Windows and macOS only).
+- `ExtraRenderers.cpp`: `wx/generic/private/{markuptext,rowheightcache,widthcalc}.h`, under
+  `wxHAS_GENERIC_DATAVIEWCTRL`, so MSW only.
+- `ExtraRenderers.cpp`: `wx/private/markupparser.h`, under `wxUSE_ACCESSIBILITY`.
+
+Its `wx/gtk/private*` includes are commented out. The per-port headers outside those directories,
+`wx/msw/private.h` (`BitmapComboBox.cpp`, `PresetComboBoxes.cpp`, Windows-guarded) and
+`wx/osx/private.h` (`Utils/MacDarkMode.mm`), come with the regular wx install. Private headers are
+port-specific and unversioned. Include one only under the same macro wx uses for that port or
+feature, and re-check it whenever the fork is bumped.
+
+### wxInspector
+
+The deps also build wxInspector (`deps/wxInspector/wxInspector.cmake`, compiled with
+`-DwxDEBUG_LEVEL=0`). `DPIAware<P>` derives from `wxInspector::wxInspectable`, and its constructor
+calls `SetupInspectorAccelerator(this)`. That calls `SetAcceleratorTable` on the window with
+`wxACCEL_CTRL | wxACCEL_SHIFT` + `I` (Cmd+Shift+I on macOS), which toggles an inspection frame showing
+the window tree (`src/inspector.cpp` in the wxInspector tree); a later `SetAcceleratorTable` call on a
+`DPIAware` window replaces the inspector shortcut. `GUI_App::on_init_inner` registers Orca plugins for it
+(`RegisterOrcaInspectorPlugins`, `Utils/wxInspectorPlugins/`). The root `CMakeLists.txt` defines
+`WXINSPECTOR_DISABLE` when `BBL_RELEASE_TO_PUBLIC` is set true, or, when that variable is not defined,
+for the Release configuration; this turns the whole API into no-op stubs. Use it in
+Debug/RelWithDebInfo builds to inspect layouts on each platform.
+
+## Platform macros and native handles
+
+| Macro | Defined when | Use for |
+|---|---|---|
+| `__WXMSW__` | wxMSW build | wx behaviour on Windows, `MSWWindowProc`, MSW-only wx API |
+| `__WXOSX__` (also `__WXMAC__`, `__WXOSX_COCOA__`) | wxOSX build | Cocoa-specific wx behaviour |
+| `__WXGTK__` | any wxGTK build | GTK/GDK calls, Linux toolkit behaviour |
+| `__WXGTK3__` | GTK ≥ 3.0 | GTK3-only API (CSS providers, DPI events, Wayland) |
+| `__WXGTK20__` | GTK ≥ 2.0, **also defined in GTK3 builds** (`build/cmake/setup.cmake:61-72` defines every version macro up to the toolkit version) | `defined(__WXGTK20__) \|\| defined(__WXGTK3__)` in `GUI_App.cpp` is the same as `__WXGTK__` |
+| `__WINDOWS__` | defined by wx when `_WIN32`, `__WIN32__` or `__WXMSW__` is defined (`include/wx/platform.h:87-91`) | wx's own Windows checks; Orca's dark-mode code uses it |
+| `_WIN32`, `__APPLE__`, `__linux__` | compiler | OS APIs (Win32, Cocoa frameworks, `/proc`), and all of `src/libslic3r` |
+| `wxHAS_EGL`, `wxHAS_GLX` | wx `setup.h` (`build/cmake/setup.h.in:1144-1147`) when built with EGL / GLX | GL backend code; test them only after a wx header is included |
+| `wxHAVE_GDK_WAYLAND`, `wxHAVE_GDK_X11` | Orca's `cmake/modules/FindGTK3.cmake` (`check_symbol_exists(GDK_WINDOWING_WAYLAND/X11 "gdk/gdk.h" …)`), passed by `src/slic3r/CMakeLists.txt` as PRIVATE definitions of `libslic3r_gui` | only `LinuxDisplayBackend.cpp` needs them; wx headers do not define them |
+| `GTK_CHECK_VERSION(a,b,c)` | GTK headers, compile time | branching on GTK API version. `gtk_check_version()` and wx's internal `wx_is_at_least_gtk3(n)` check the runtime version |
+
+The toolkit macros come from wx's compile definitions: `wxTOOLKIT_DEFINITIONS` in
+`build/cmake/toolkit.cmake:57-87,157`, exported through the CMake targets and through
+`wx-config --cxxflags`. They are therefore defined in every `libslic3r_gui` source, even before the
+first wx include; `LinuxDisplayBackend.hpp` relies on this. `src/libslic3r` does not link wx and uses
+none of them. Prefer the toolkit macro whenever the difference comes from wx: a later toolkit change
+(for example wxGTK on another OS) then keeps the right branch.
+
+**Native handles.** `wxWindow::GetHandle()` returns `WXWidget`:
+- wxMSW: the `HWND` (`include/wx/msw/window.h:169`).
+- wxOSX: the peer's `NSView*`. Reach the `NSWindow` with `[view window]`, as
+  `set_miniaturizable(GetHandle())` does.
+- wxGTK: `m_widget` (`include/wx/gtk/window.h:140`). For a top-level window this is the `GtkWindow`.
+  `MainFrame`, `BBLTopbar` and `DropDown` also use `m_widget` directly; wxGTK declares it in a
+  `public:` implementation block (`include/wx/gtk/window.h:291`), so other classes can read another
+  window's `m_widget` (`m_frame->m_widget`).
+
+Native calls on these handles bypass wx's bookkeeping. Keep them minimal, guard them with the toolkit
+macro, and prefer an existing helper (`GUI_Utils`, `MacDarkMode.mm`, `GUI_UtilsMac.mm`) over new
+inline native code.
+
+- **Rule:** Keep the guard on a declaration identical to the guard on its definition (one toolkit
+  guard, version branches with `GTK_CHECK_VERSION` inside the definition), and include GTK headers
+  under the same guard as the code that uses them.
+  **Why:** a header declaring under `__WXGTK3__` while the `.cpp` defines under `__WXGTK__` (or the
+  reverse) breaks the build on the other GTK configuration or leaves an undefined symbol. The
+  wrong → right shape is under [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls).
+  Cite: 477208a969 (`GUI_Utils.hpp` / `GUI_Utils.cpp`).
+
+## Per-platform summaries
+
+Each bullet names the mechanism and the file that owns it.
+
+### MSW (wxMSW)
+
+- **Pixels and DPI:** logical pixels equal physical pixels and `FromDIP` really scales. Per-monitor
+  DPI change events need the PMv2 manifest (`src/dev-utils/platform/msw/OrcaSlicer.manifest.in`
+  declares `permonitorv2,permonitor`); under the `permonitor` (V1) fallback on older Windows wx
+  generates no DPI events, because it accepts only PMv2 [source: `src/msw/nonownedwnd.cpp`
+  `IsPerMonitorDPIAware`]. wx rescales min sizes, fonts and sizer borders before
+  `wxEVT_DPI_CHANGED` [source], and `DPIAware` does not `Skip()` it. `wxEVT_MOVE_START/END` exist only on MSW
+  (DPIAware uses them to defer rescaling while a window is dragged) → `references/dpi-bitmaps-fonts.md`.
+- **Dark mode:** `MSWEnableDarkMode(DarkMode_Auto)` runs before `NppDarkMode::InitDarkMode()`. After
+  that, `IsDark()` reports the OS apps setting, so `dark_color_mode` is consulted first. The runtime
+  dark-mode toggle is Windows-only. Menu bitmaps choose dark variants through `check_dark_mode()` →
+  `references/colours-dark-mode.md`.
+- **Popups:** the current popup is the wx-internal global `wxCurrentPopupWindow`. Focus changes and
+  clicks outside dismiss popups that lack `wxPU_CONTAINS_CONTROLS` (`MSWDismissUnfocusedPopup`);
+  popups with it are dismissed on deactivation, deferred through `CallAfter`. No key dismisses a
+  popup, and `ProcessLeftDown` is never called. `PopupWindow::BindUnfocusEvent` is MSW-only →
+  `references/popups-menus.md` §5.
+- **Painting:** in 3.3.2 windows are not double-buffered by default (the 3.3.0 global
+  `WS_EX_COMPOSITED` was reverted, `docs/changes.txt:308`). Custom widgets buffer by hand →
+  `references/painting-custom-widgets.md`.
+- **Modal loops:** idle events do not run inside the Windows sizing/moving modal loop, so the 3D
+  canvas renders from `on_paint` on MSW (c06a0223a7) → `references/webview-gl-aui-media.md` §GLCanvas3D rendering.
+- **Mouse capture:** `wxEVT_MOUSE_CAPTURE_LOST` and `wxEVT_MOUSE_CAPTURE_CHANGED` are delivered →
+  `references/mouse-keyboard-focus.md`.
+- **Controls:** `wxDataViewCtrl` is the generic implementation (`references/controls-dataview.md`).
+  TaskDialog-based dialogs and common dialogs stay light in wx dark mode
+  (`interface/wx/app.h:1434-1448`); Orca's `MsgDialog` family is owner-drawn →
+  `references/windows-dialogs.md`.
+- **WebView:** Edge (WebView2). It needs the runtime (checked by `GUI_App::init_webview_runtime`),
+  creates asynchronously, serves custom schemes as `https://<scheme>.wxsite`, and allows one script
+  handler → `references/webview-gl-aui-media.md`.
+- **Window frame:** custom title bar and non-client handling → [MSW title bar](#msw-the-mainframe-custom-title-bar).
+
+### macOS (wxOSX/Cocoa)
+
+- **Pixels and DPI:** logical pixel = DIP = point. The standard PPI is 72, so `GetDPI()` and
+  `GetNewDPI()` are 72-based. `wxEVT_DPI_CHANGED` is generated on backing-scale changes even though
+  the docs don't say so [source: `src/osx/cocoa/nonownedwnd.mm` `windowDidChangeBackingProperties`],
+  but `DPIAware` binds it only off macOS. `DPIAware` and
+  `MainFrame::init_tabpanel` skip `SetFont` on macOS ("name cutting in ObjectList") →
+  `references/dpi-bitmaps-fonts.md`.
+- **Menus and keys:** there is a native `wxMenuBar`, and Preferences goes into `OSXGetAppleMenu()`.
+  Menu key equivalents run before `wxEVT_CHAR_HOOK`, display-only shortcut text uses `" - "`,
+  `wxMOD_CONTROL` means Cmd, Ctrl+click arrives as a right click [source], and Cmd+letter char events
+  carry the plain letter [source] → `references/mouse-keyboard-focus.md`, `references/popups-menus.md`.
+- **Mouse capture:** capture is a wx-level redirect of every left/right button, motion and
+  enter/exit event (not wheel or middle-button events), and capture-lost is never sent [source]. A
+  leaked capture looks like a frozen UI whose keyboard still works →
+  `references/mouse-keyboard-focus.md`.
+- **Popups:** a transient popup toggles mouse capture on idle (since 3.1.7) and dismisses on an
+  outside click [source]. Since the 3.3 upgrade a hover-opened popup anchored with a gap below its
+  opener was dismissed as the cursor crossed the gap (#12936); the wx mechanism was not established,
+  and the fix is to anchor flush → `references/popups-menus.md` §3.
+- **Controls:** the native `wxDataViewCtrl` (NSOutlineView) never calls `CreateEditorCtrl`, and the
+  current item is always selected (`references/controls-dataview.md`). `wxClientDC` cannot draw
+  (`references/painting-custom-widgets.md`).
+- **Colours:** Orca's sRGB `wxColour` patch. Dark mode follows the system only (`mac_dark_mode()`) →
+  `references/colours-dark-mode.md`.
+- **WebView:** WKWebView. Handlers must be registered before `Create`, and adding the same script
+  handler twice raises an uncatchable NSException → `references/webview-gl-aui-media.md`.
+- **Window frame:** a native titled window with a transparent titlebar →
+  [macOS frame](#macos-a-native-titled-window).
+
+### GTK3 (X11 and Wayland)
+
+- **Pixels and DPI:** logical pixel = DIP, and the scale is an integer ("fractional scales are rounded
+  to the closest integer"). `wxEVT_DPI_CHANGED` needs GTK ≥ 3.10 and wx ≥ 3.3.0, so `DPIAware`'s
+  rescale path runs on Linux. `get_dpi_for_window()` is a fixed-96 stub on Linux (and macOS), so
+  `em_unit` is measured from the font (`DPIAware::update_em_unit`) →
+  `references/dpi-bitmaps-fonts.md`.
+- **Dark mode:** follows the system appearance. `GUI_App::on_init_inner` (non-Windows) and
+  `update_dark_config` (called from `DPIAware`'s `wxEVT_SYS_COLOUR_CHANGED` handler off Windows)
+  overwrite `dark_color_mode` from `wxSystemSettings::GetAppearance().IsDark()` →
+  `references/colours-dark-mode.md`.
+- **Sizing:** sizer-fitting calls made on a top-level window that is not yet shown are replayed at
+  `Show()` (`wxWindow::Fit()` is not), and dialogs collapse without size hints →
+  `references/sizers-layout.md`.
+- **Native chrome:** GTK theme borders and padding show through custom-drawn controls →
+  [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls).
+- **Popups:** `Show()` grabs the pointer (`gdk_seat_grab`) [source]. `PopupWindow` dismisses when the
+  top-level window is deactivated, and popups are created with `GDK_WINDOW_TYPE_HINT_COMBO` [source] →
+  `references/popups-menus.md`.
+- **Mouse capture:** a grab-broken event or a modal dialog delivers `wxEVT_MOUSE_CAPTURE_LOST`
+  [source; the docs mark the event MSW-only] → `references/mouse-keyboard-focus.md`.
+- **Controls:** `wxDataViewCtrl` is the native GtkTreeView (`references/controls-dataview.md`). `Field`
+  control pools delete windows on GTK instead of recycling them (`references/orca-settings-ui.md`).
+- **WebView:** WebKit2GTK delivers script messages synchronously, with an empty handler name and no
+  event object, and navigation events synchronously too [source] → `references/webview-gl-aui-media.md`.
+- **GL:** EGL or GLX. Orca calls `PreferGLX()` on X11 → `references/webview-gl-aui-media.md` §EGL vs GLX.
+- **App init:** `GUI_App::on_init_inner` sets `gtk-menu-images` to TRUE so menu icons show, and
+  installs a `g_log_set_handler("Gtk", G_LOG_LEVEL_CRITICAL, …)` filter. The filter drops known
+  harmless criticals (allocation on hidden widgets, events on unrealised widgets, style-context calls
+  before realisation), so GTK criticals not on that list still reach the log.
+- **Window frame:** borderless with WM-driven move and resize → [GTK frame](#linux-gtk-the-borderless-mainframe).
+
+### GTK2 (opt-out build)
+
+Compile-compatibility only. See [Toolkit per platform](#toolkit-per-platform) for what it loses: EGL,
+WebKit2, DIP pixels, DPI events and backend detection. GTK-guarded code must still compile here:
+use `GTK_CHECK_VERSION` branches as `RemoveButtonBorder` does. No GTK2 runtime behaviour is supported.
+
+### Wayland (GTK3 native backend)
+
+The protocol gives clients no global pointer or window positions, and the compositor places
+top-level windows. GL is EGL only, drawn into a subsurface. Popups are `xdg_popup` surfaces and must
+form a chain of parents. Window icons come from the `.desktop` file. The full list is under
+[Wayland gaps](#wayland-gaps). These Wayland rules are owned by other files:
+- hover handlers must short-circuit, because on compositors that keep hidden-workspace surfaces
+  mapped (e.g. Hyprland) GTK sends a stream of synthetic leave events and `IsShownOnScreen()` stays
+  true there (69e16cd7ef) →
+  `references/mouse-keyboard-focus.md`;
+- GL blending must keep destination alpha at 1 (d8369e5f75);
+- GL post-init must retry until the surface is committed (d2c24fdabb) →
+  `references/webview-gl-aui-media.md`.
+
+### XWayland (GTK3 X11 backend inside a Wayland session)
+
+Users opt in with `GDK_BACKEND=x11…`. GTK then talks X11, so `is_running_on_x11()` is true and Orca
+uses GLX through `PreferGLX()`. `CLI::run` prepares this path before GTK starts (PRIME variables,
+`XInitThreads()`, no WebKit compositing workaround; the source comment says multi-monitor handling
+is compromised there) → [Runtime detection](#runtime-x11wayland-detection),
+`references/webview-gl-aui-media.md` §WebKitGTK on Linux sessions. Intel's XWayland GL exposes a
+smaller `GL_MAX_TEXTURE_SIZE`, so the ImGui font atlas is re-packed to fit (22e121f4e4) →
+`references/webview-gl-aui-media.md`.
+
+## The ifdef landscape
+
+Platform-specific GUI code falls into recurring categories. Most of it sits in `MainFrame`,
+`GUI_App`, `GLCanvas3D`, `GUI_ObjectList`, `Plater`, `wxExtensions`, `Field` and `Widgets/AMSItem`;
+start there when looking for prior art. The sites below are exemplars, cited by symbol.
+
+**Focus, capture and popup dismissal** (the largest category) → `references/popups-menus.md`,
+`references/mouse-keyboard-focus.md`
+- `StatusPanel::on_switch_speed`: on `__WXOSX__` the speed popup gets a `nullptr` parent (the source
+  comment says "MacOS has focus problem"); elsewhere the parent is the control.
+  `popUp->BindUnfocusEvent()` runs only under `__WXMSW__` and binds the top parent's
+  `wxEVT_ACTIVATE` / `wxEVT_ICONIZE` / `wxEVT_SHOW` to `Dismiss()`.
+- `GLCanvas3D::on_mouse`, `evt.Entering()` branch: on MSW the canvas does not `SetFocus()` while
+  `wxCurrentPopupWindow` is non-null. Stealing focus would trigger `MSWDismissUnfocusedPopup` and
+  close the search dropdown. `wxCurrentPopupWindow` is a wx-internal global (`src/msw/popupwin.cpp`)
+  that `GLCanvas3D.cpp` declares `extern` itself, which works only because wx is linked statically.
+  `SearchDialog` and `SearchObjectDialog` override the virtual `MSWDismissUnfocusedPopup`.
+- `GLCanvas3D::on_mouse`: the MSW "on_enter workaround" (comment "SPE-832") handles a spurious mouse
+  event that arrives before `evt.Entering()`; `m_mouse.position` is reset at the end of the function.
+- `SearchObjectDialog::Popup`: on `__WXOSX__`, focus moves to `m_object_list` before
+  `PopupWindow::Popup`, otherwise the text input becomes unusable.
+- `SearchDialog::Dismiss`, `SearchObjectDialog::Dismiss`: on Wayland they dismiss by focus tracking
+  (`focus_left_popup(...)`) instead of hit-testing `wxGetMousePosition()`.
+- `PopupWindow::Create`: on GTK it binds the top-level `wxEVT_ACTIVATE` to `topWindowActiavate` →
+  `DismissAndNotify()`, gated by the virtual `ShouldDismissOnTopWindowDeactivate()`, which `DropDown`
+  overrides for Wayland popup chains. On `__WXOSX__` with `wxPU_CONTAINS_CONTROLS`,
+  `PopupWindow::OnMouseEvent2` hit-tests children, re-dispatches mouse events and synthesises
+  enter/leave.
+- `SidePopup::Popup` (`Widgets/SideMenuPopup.cpp`): on `__APPLE__` the menu is anchored flush against
+  the button with a slight overlap. Since the wx 3.3 upgrade, the transient popup was dismissed as
+  soon as the cursor entered the gap (#12936, 9a053f15eb). The wx mechanism was not established
+  (`references/popups-menus.md` §3): [source] `wxPopupTransientWindow::OnIdle` captures the mouse
+  whenever the cursor is outside the popup rect and releases it inside
+  (`src/common/popupcmn.cpp:438-471`, a 3.1.7 addition), and `wxPopupWindowHandler::OnLeftDown`
+  dismisses only on an outside click (`popupcmn.cpp:536+`), so neither explains a dismissal on hover.
+
+**Menu bar and accelerators** → `references/mouse-keyboard-focus.md`, `references/popups-menus.md`
+- `MainFrame::MainFrame`: `#ifndef __APPLE__` creates `m_topbar = new BBLTopbar(this)`, a
+  `wxAuiToolBar` with `BBLTopbarArt : wxAuiDefaultToolBarArt`. macOS gets a plain `wxPanel` top area
+  plus the native `wxMenuBar` that `MainFrame::init_menubar_as_editor` sets with `SetMenuBar`.
+  Preferences is added with `append_shortcut_item(..., Shortcut::Preferences, ...)` into
+  `OSXGetAppleMenu()` on macOS and into `m_topbar->GetTopMenu()` elsewhere.
+- `MainFrame::shortcut_label`: items registered with `accelerator=true` whose binding is menu-safe
+  (`ShortcutRegistry::accelerator()` non-empty) get `"\t" + accelerator`. That is a live key
+  equivalent only in the macOS `wxMenuBar`; the Windows/Linux menus are popped up from `BBLTopbar`,
+  where accelerators are display-only and the registry dispatches the keys. Display-only shortcut
+  text uses the static `sep`, which is `" - "` on macOS and `"\t"` elsewhere, because the native menu
+  bar would otherwise grab keys that must reach text fields (#8152).
+- `KeyChord::from_event` normalises char events: control codes 1–26 with `ControlDown()` become
+  `'A'..'Z'`, and lowercase becomes uppercase. Match shortcuts through it, never through raw char
+  codes for Ctrl/Cmd+letter. [source] `wxOSXTranslateCocoaKey` produces `WXK_CONTROL_A+n` only when
+  the physical Ctrl is held (`src/osx/cocoa/window.mm:305-307`), so a Cmd+letter char event carries
+  the plain letter. Control-code translation is documented at `interface/wx/event.h:1408-1421`.
+- `MainFrame::MainFrame`, `wxEVT_CHAR_HOOK` lambda under `__APPLE__`: Cmd+H is swallowed, Cmd+M calls
+  `Iconize()`, Cmd+Q posts `wxEVT_CLOSE_WINDOW`, and Cmd+Ctrl+F calls `EnableFullScreenView(true)` and
+  toggles `ShowFullScreen` (`interface/wx/toplevel.h:700-728`, OSX only). Everything else goes to
+  `handle_global_shortcut(KeyChord::from_event(evt))`. Cmd+, is the registry's
+  `Shortcut::Preferences`, not part of the hook.
+- `ObjectList::update_shortcut_accelerators`: the native macOS data view gets no key events, so on
+  macOS a `wxAcceleratorTable` is generated from the shortcut registry.
+
+**Window decoration / custom title bar** → [Window decoration](#window-decoration-and-custom-title-bars)
+- `MainFrame::MainFrame`: `set_miniaturizable` (OSX); `m_gdkDecor = 0` and three `ResizeEdgePanel`s
+  (GTK); the `WS_CAPTION` strip (MSW). `MainFrame::MSWWindowProc` and `AdjustWorkingAreaForAutoHide`
+  (MSW). `BBLTopbar::OnMouseLeftDown`, `BBLTopbar::OnFullScreen`, `BBLTopbar::MSWWindowProc`.
+  `SplashScreen::SplashScreen` (Wayland).
+
+**Fonts, sizes, Retina** → `references/dpi-bitmaps-fonts.md`
+- The `DPIAware` constructor and `MainFrame::init_tabpanel`: `#ifndef __WXOSX__` around `SetFont`,
+  "to avoid name cutting in ObjectList".
+- `OG_CustomCtrl::CtrlLine::draw_text`: works around the Big Sur bold-font issue. Focused URL labels
+  are drawn underlined instead of bold and underlined.
+- `SwitchButton::Rescale`: on `__WXOSX__` the measuring font is scaled by `mac_max_scaling_factor()`.
+  That helper reads screen 0's backing factor (`[[NSScreen screens] objectAtIndex:0]`, the menu-bar
+  screen) on every loop iteration, so despite its name it returns that screen's factor (at least 1),
+  not the maximum over all screens.
+- `BitmapComboBox` (comment block under `#ifdef __APPLE__` in `BitmapComboBox.hpp`): the bitmap
+  `scale` argument means "the image is already sized for that backing scale". The `scale` parameter
+  of `wxBitmap(const wxImage&, int depth, double scale)` is not in the interface docs. It exists on
+  every port (`include/wx/osx/bitmap.h:115`, `include/wx/gtk/bitmap.h:77`), but wxMSW ignores it
+  (`include/wx/msw/bitmap.h:68`). The portable APIs are `CreateWithDIPSize` and `SetScaleFactor`
+  (`interface/wx/bitmap.h:491-520, 966`).
+
+**GTK / Wayland** → this file, `references/webview-gl-aui-media.md`, `references/popups-menus.md`
+- `CLI::run` (`src/OrcaSlicer.cpp`): sets backend-related environment variables before GTK starts.
+- `GUI_App::on_init_inner`: calls `wxGLCanvas::PreferGLX()` when `is_running_on_x11()`, under
+  `#if defined(__WXGTK__) && wxHAS_EGL`.
+- `OpenGLManager::detect_multisample`: on Wayland without `wxHAS_EGL` it skips `IsDisplaySupported()`,
+  which would go through GLX and crash on a missing X11 display. Multisampling is also off on ChromeOS
+  (`PlatformFlavor::LinuxOnChromium`).
+- `OpenGLManager::init_gl`: loads GLAD through `eglGetProcAddress` on Wayland.
+- `DropDown::messureSize`: positive-size `gtk_window_resize` on the GTK wrapper window, plus an idle
+  poll that synthesises `mouseMove` on the main dropdown while a submenu holds the grab (Mutter drops
+  motion events outside the grabbing surface). `DropDown::mouseMove` sets the submenu
+  `gtk_window_set_transient_for` to the mapped main popup at show time. `DropDown::Popup` gives
+  data-view cell editors an explicit top-level transient parent.
+  `DropDown::ShouldDismissOnTopWindowDeactivate` handles Wayland chains.
+- `CheckBox::CheckBox`, `SwitchButton`, `RadioBox`, `ScalableButton` (`wxExtensions.cpp`),
+  `ObjColorDialog`, `PresetComboBoxes` call `RemoveButtonBorder`; `TextInput` and `SpinInput` call
+  `RemoveInputBorder` on their inner `wxTextCtrl`.
+- `Plater::priv::priv` together with `sanitize_window_layout_for_wayland`: AUI floating is disabled on
+  Wayland.
+- `GUI_App::window_pos_restore`: skips `SetPosition` on Wayland.
+- `BBLTopbar::OnMouseLeftDown` / `OnMouseMotion` convert event coordinates with `ClientToScreen`
+  instead of calling `wxGetMousePosition()`. `BBLTopbar::FindToolByCurrentPosition` returns null on
+  Wayland when the last event position is unknown or outside the bar.
+- `LinuxDisplayBackend.{hpp,cpp}`: runtime X11/Wayland detection.
+
+**Windows rendering and dark mode** → `references/colours-dark-mode.md`,
+`references/painting-custom-widgets.md`
+- `_MSW_DARK_MODE` is `#define`d to 1 **on every platform** (`GUI_App.hpp`), so it is not a platform
+  gate. The MSW-only calls inside those blocks sit under `__WINDOWS__` / `_WIN32`.
+  `dark_mode.cpp/.hpp` and `dark_mode/{dark_mode,IatHook,UAHMenuBar}.hpp` (the vendored Notepad++
+  dark mode, `NppDarkMode`) are compiled only under `if (WIN32)` in `src/slic3r/CMakeLists.txt`.
+  `SUPPORT_DARK_MODE` (`libslic3r/AppConfig.hpp`) gates `GUI_App::dark_mode`.
+- `AMSExtText::render`: on `__WXMSW__` it blits the paint DC into a bitmap and renders through a
+  `wxGCDC` over the `wxMemoryDC` (GDI+ anti-aliasing), then `DrawBitmap`s the result. Other ports call
+  `doRender(dc)` directly. `StaticBox::render` uses a variant (rounded boxes only) that clears the
+  bitmap with the background colour instead of blitting. This is the recurring MSW pattern in custom
+  widgets.
+- `GLCanvas3D::on_paint`: renders immediately on MSW (c06a0223a7).
+
+**Native data view** → `references/controls-dataview.md`
+- `GUI_ObjectList.cpp` has `__WXOSX__` editing and model paths, because the native macOS control never
+  calls a custom renderer's `CreateEditorCtrl`.
+
+**macOS Objective-C++ glue** — `.mm` files listed in the `APPLE` block of `src/slic3r/CMakeLists.txt`,
+for example:
+- `Utils/MacDarkMode.mm`: `mac_dark_mode`, `mac_max_scaling_factor`, `set_miniaturizable`,
+  `set_title_colour_after_set_title`, the `WKWebView_*` helpers, `initGestures`.
+- `GUI/GUI_UtilsMac.mm`: `dataview_remove_insets`, `staticbox_remove_margin`,
+  `set_window_corner_radius`, declared under `__WXOSX__` in `GUI_Utils.hpp`.
+- `GUI/DeepLinkHandlerMac.mm`, `GUI/InstanceCheckMac.mm`, `GUI/Mouse3DHandlerMac.mm`,
+  `GUI/RemovableDriveManagerMM.mm`, `Utils/RetinaHelperImpl.mm`. (`libslic3r/MacUtils.mm` is registered
+  in `src/libslic3r/CMakeLists.txt` instead.)
+
+Trackpad gestures: `GLCanvas3D::bind_event_handlers` calls the portable
+`EnableTouchEvents(wxTOUCH_ZOOM_GESTURE | wxTOUCH_ROTATE_GESTURE)` plus
+`initGestures(m_canvas->GetHandle(), m_canvas)` for the pan recogniser, and `unbind_event_handlers`
+calls `initGestures(..., nullptr)`. Deep links: `GUI_App::on_init_inner` → `register_mac_deep_link_handler()`
+re-registers the `kAEGetURL` handler after wx installs its own (1f2ed70288, #13119).
+
+**WebView and media** → `references/webview-gl-aui-media.md`
+- `WebView::CreateWebView`: `WebViewEdge` on Windows, `WebViewWebKit` on macOS, `wxWebView::New()` on
+  Linux.
+- Camera: `wxMediaCtrl3`, a plain `wxWindow` that decodes on a worker thread and paints a `wxBitmap`
+  frame on Win32 and a `wxImage` frame elsewhere. No per-platform native player sits
+  behind it; new camera sources implement `IMediaController` (97955dbab8 and 7e3724b5f3 removed the
+  `wxMediaCtrl2.cpp/.mm` players).
+
+## Runtime X11/Wayland detection
+
+**API** (`src/slic3r/GUI/LinuxDisplayBackend.hpp`, declared only `#if defined(__WXGTK__)`, namespace
+`Slic3r::GUI`):
+
+```cpp
+enum class LinuxDisplayBackend { X11, Wayland, Unknown };
+LinuxDisplayBackend get_linux_display_backend();   // "Must be called after gtk_init() / wxWidgets initialization."
+bool is_running_on_wayland();
+bool is_running_on_x11();
+```
+
+**Mechanism.** `get_linux_display_backend()` tests `gdk_display_get_default()` with
+`GDK_IS_WAYLAND_DISPLAY` and then `GDK_IS_X11_DISPLAY`. Each test is compiled only when
+`wxHAVE_GDK_WAYLAND` / `wxHAVE_GDK_X11` is defined. The result is cached in a function-local static
+on the **first** call. So:
+- Called before GTK has a display, it caches `Unknown` for the rest of the process.
+- In a GTK2 build neither macro is defined, so it always returns `Unknown`.
+- `Unknown` makes both predicates false. Write every branch so that "neither" is safe. For example,
+  `GUI_App::on_init_inner` logs "Unknown display backend, defaulting to EGL" and does not call
+  `PreferGLX()`.
+
+**Usage.**
+```cpp
+#ifdef __WXGTK__
+#include "LinuxDisplayBackend.hpp"
+#endif
+...
+#if defined(__WXGTK__)
+    if (Slic3r::GUI::is_running_on_wayland()) {
+        // Wayland-only path
+    }
+#endif
+```
+
+**Before GTK starts**, only the environment exists. `CLI::run` (`src/OrcaSlicer.cpp`) branches on
+`GDK_BACKEND` (an `x11` prefix means the X11 opt-in). On the default path it forces `GDK_BACKEND=x11`
+when wx lacks EGL and `WAYLAND_DISPLAY` is set. It sets `WEBKIT_DISABLE_COMPOSITING_MODE=1`
+(non-replacing) only when both `DISPLAY` and `WAYLAND_DISPLAY` are set, and calls `XInitThreads()`
+only when `DISPLAY` is set. With neither variable set, the GUI refuses to start ("Neither DISPLAY nor
+WAYLAND_DISPLAY set"). The details and the WebKit rule (c12912e0df) are in
+`references/webview-gl-aui-media.md` §WebKitGTK on Linux sessions.
+
+**wx's own detectors**, for reference:
+- `wxGetDisplayInfo()` (`include/wx/utils.h:731-750`, public header but not in the interface docs)
+  returns `wxDisplayX11` / `wxDisplayWayland` / `wxDisplayNone` and the native display.
+- `wxGTKImpl::IsWayland` / `IsX11` (`include/wx/gtk/private/backend.h`, GTK3 only) are private, and
+  each caches the answer of its first call.
+
+Orca standardises on `LinuxDisplayBackend`, which keeps GDK headers out of callers.
+
+**Pitfalls**
+- **Rule:** Decide the backend with the GDK type check (`is_running_on_wayland()` /
+  `is_running_on_x11()`), not with `WAYLAND_DISPLAY` / `GDK_BACKEND` in GUI code. Environment
+  variables are appropriate only before GTK initialises.
+  **Why:** environment variables describe the session, not the backend GTK actually picked. An
+  XWayland run has both `DISPLAY` and `WAYLAND_DISPLAY` set while GTK talks X11, and a native Wayland
+  run usually has `DISPLAY` set too (XWayland available). GUI decisions keyed on the environment
+  misfire in both cases.
+  ```cpp
+  // Wrong: GUI code reading the session environment
+  if (getenv("WAYLAND_DISPLAY"))
+      m_aui_mgr.SetFlags(m_aui_mgr.GetFlags() & ~wxAUI_MGR_ALLOW_FLOATING);
+  // Right (shape of Plater::priv::priv)
+  #if defined(__WXGTK__)
+  if (Slic3r::GUI::is_running_on_wayland())
+      m_aui_mgr.SetFlags(m_aui_mgr.GetFlags() & ~wxAUI_MGR_ALLOW_FLOATING);
+  #endif
+  ```
+  Cite: 1b71835337 (`GUI_App.cpp`), `src/slic3r/GUI/LinuxDisplayBackend.cpp`.
+- **Rule:** Never call the detectors from static initialisers or before `wxEntry` has initialised GTK.
+  **Why:** `gdk_display_get_default()` is null then, and the function-local cache keeps `Unknown`
+  forever, which silently disables every Wayland or X11 branch.
+
+## Wayland gaps
+
+wx has no dedicated Wayland document; the documented limits are scattered across the interface
+headers. Rows marked [source] or "protocol" come from the implementation or from Wayland itself.
+
+| Area | What happens on Wayland | Cite | Orca handling / owner |
+|---|---|---|---|
+| Global pointer position | `wxGetMousePosition()` / `wxGetMouseState()` call `gdk_device_get_position` [source], but Wayland gives clients no global pointer position, so the result is not a screen position | `src/gtk/window.cpp` `wxGetMousePosition` | use event coordinates + `ClientToScreen` (`BBLTopbar`); dismiss popups by focus tracking (`SearchDialog::Dismiss`) → `references/mouse-keyboard-focus.md` |
+| Top-level position | the compositor places windows, and `SetPosition()` / `Move()` on a TLW have no effect (protocol) | — | `GUI_App::window_pos_restore` restores only size and maximised state; moves go through `gtk_window_begin_move_drag` |
+| Window icon | `SetIcon()` / `SetIcons()` "doesn't do anything when using Wayland … create a `.desktop` file" | `interface/wx/toplevel.h:517-521, 538-542` | `src/dev-utils/platform/unix/com.orcaslicer.OrcaSlicer.desktop` (`Icon=OrcaSlicer`, `StartupWMClass=orca-slicer`) |
+| App id | `wxAppConsole::SetClassName()` is the xdg `app_id` with GTK ≥ 3.24.22 (and the AUMID on Windows); it must be set before any TLW. wx applies it when a TLW is mapped, and only if it is non-empty [source: `wxTopLevelWindowGTK::GTKHandleMapped`] | `interface/wx/app.h:765-812` | Orca calls only `SetAppName(SLIC3R_APP_KEY)`, so GTK's default applies. On Windows, `SetClassName` would also change shell behaviour (MRU, Shift+middle-click) |
+| `wxClientDC` | deprecated in 3.3 ("please use wxInfoDC instead for obtaining information", `interface/wx/dcclient.h:43-46`). Drawing through it "simply doesn't have any effect" on GTK3/Wayland or wxOSX. `CanBeUsedForDrawing()` [source]: false on Wayland only for wxGTK (`src/gtk/dc.cpp`), always false on wxOSX, always true on wxMSW (`include/wx/{osx,msw}/dcclient.h`), although its doc also lists "wxMSW when using double buffering" | `interface/wx/dcclient.h:48-53, 80-88` | draw only in `wxPaintDC` after `Refresh()`/`RefreshRect()` → `references/painting-custom-widgets.md` |
+| `wxWindow::Update()` | "doesn't do anything in wxGTK port when using Wayland". [source] wx skips the GDK update calls there because they broke later updates (#25036) | `interface/wx/window.h:2405-2407` | never rely on `Update()` to paint synchronously |
+| `WarpPointer()` | works only if the compositor implements the pointer-warp protocol; mutter also needs a mouse button held | `interface/wx/window.h:3902-3907`; `docs/changes.txt:294` | Orca never warps the pointer |
+| `wxUIActionSimulator` | "currently doesn't work when using Wayland with wxGTK" | `interface/wx/uiaction.h:20` | not used; Orca also builds `wxUSE_XTEST=OFF` |
+| `wxBitmap(const wxCursor&)` | creates an invalid bitmap | `interface/wx/bitmap.h:393-395` | — |
+| OpenGL | only EGL; `PreferGLX()` has no effect. Without EGL in the build, wxGTK's `wxGLCanvas` shows a fatal message and refuses to work [source: `src/gtk/glcanvas.cpp` `IsAvailable`]. The EGL surface is a subsurface over the canvas, ready only after map and a frame callback [source: `src/unix/glegl.cpp`] | `interface/wx/glcanvas.h:1094-1095` | `CLI::run` forces X11 when wx lacks EGL; overlays are drawn in GL/ImGui, never as wx children over the canvas → `references/webview-gl-aui-media.md` |
+| AUI | the doc note "live resize is always used … for wxOSX and wxGTK3 when using Wayland" is obsolete: "As of wxWidgets 3.3.0 this function always returns false", and `wxAUI_MGR_LIVE_RESIZE` is in the default flags. Floating panes need global positions | `interface/wx/aui/framemanager.h:336-345` | `Plater::priv::priv` clears `wxAUI_MGR_ALLOW_FLOATING`; `sanitize_window_layout_for_wayland` strips floating state from the saved layout → `references/webview-gl-aui-media.md` §wxAuiManager |
+| Popups | a GTK popup is an `xdg_popup` only for COMBO/DROPDOWN/POPUP_MENU hints, so wx creates popups with `GDK_WINDOW_TYPE_HINT_COMBO` [source]. A chained popup's parent must be the mapped popup, and mapping it with a grab deactivates the toplevel (Orca's comments in `DropDown::mouseMove`, `DropDown::ShouldDismissOnTopWindowDeactivate`) | `src/gtk/popupwin.cpp:110-114` | `DropDown` transient-for chain, `ShouldDismissOnTopWindowDeactivate` → `references/popups-menus.md` |
+| Fractional scale | arrives as an integer GDK scale | `docs/doxygen/overviews/high_dpi.md:348-351` | → `references/dpi-bitmaps-fonts.md` |
+| Window decorations | some desktop environments draw a title bar on undecorated windows anyway | — | [Undecorated windows](#wayland-undecorated-top-level-windows-splash) |
+| `wxWebViewChromium` | X11 only | `interface/wx/webview_chromium.h:133-146` | not built (`wxUSE_WEBVIEW_CHROMIUM` OFF) |
+
+Wayland history in the change logs (`docs/changes_32.txt`): already in 3.1.5, Orca's previous wx,
+were two-finger scrolling (703, 3.1.3), the EGL-based `wxGLCanvas` for Wayland (497) and `wxMediaCtrl`
+support (498, both 3.1.5). New with the upgrade: "Many bug fixes for Wayland-specific problem" (397)
+and a `wxMediaCtrl` fix (402) in 3.1.6, GDK errors from `PopupMenu()` avoided (317, 3.1.7),
+`wxCURSOR_SIZING` fixed (261, 3.2.0). In 3.3, `WarpPointer()` on supported compositors
+(`docs/changes.txt:294`) and the EGL/Wayland high-DPI scale fix (`changes.txt:538`).
+
+## Window decoration and custom title bars
+
+Only `MainFrame` replaces the native title bar. Dialogs keep native decorations, chosen through their
+style flags (`references/windows-dialogs.md`). `MainFrame` is created with
+
+```cpp
+#ifndef __APPLE__
+#define BORDERLESS_FRAME_STYLE (wxRESIZE_BORDER | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX)
+#else
+#define BORDERLESS_FRAME_STYLE (wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX)
+#endif
+```
+
+There is no `wxCAPTION` on any platform; each port then needs its own handling.
+
+### MSW: the MainFrame custom title bar
+
+**Contract** [source + documented]. Since wx **3.3.0**, `wxTopLevelWindowMSW::MSWGetStyle` adds
+`WS_CAPTION` whenever any of `wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX` is set
+(`src/msw/toplevel.cpp:133-135`). The 3.3.0 wxMSW change list says "Turn wxCAPTION on automatically if
+required by other styles (#23575)" (`docs/changes.txt:581`). Commit eefdabcd98 attributes this to
+3.3.2, but it is a 3.3.0 change. `SetWindowStyleFlag()` recomputes the native style through
+`MSWGetStyle` and turns the bits back on (`src/msw/window.cpp` `wxWindowMSW::MSWUpdateStyle`).
+
+**OrcaSlicer design** (`MainFrame.cpp`, all under `__WXMSW__`):
+- `MainFrame::MainFrame` strips `WS_CAPTION` with `SetWindowLongPtr` and applies it with
+  `SetWindowPos(..., SWP_FRAMECHANGED | SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE)`.
+  Without it Windows 10 showed the native frame behind the custom title bar, a "double window"
+  (f70d30bf79, #13074).
+- `MainFrame::MainFrame` also binds `wxEVT_MAXIMIZE`: the handler clamps the frame to the display's
+  client area plus the border overshoot (`AdjustWindowRectEx`), moves it there and `Skip()`s, so a
+  maximised frame does not overlap the taskbar (restored by f70d30bf79).
+- `MainFrame::MSWWindowProc`:
+  - `WM_NCACTIVATE`: sets `lParam = -1` so `DefWindowProc` does not repaint the non-client area, while
+    the window still receives activation.
+  - `WM_NCCALCSIZE` with `wParam` TRUE: computes the border with
+    `AdjustWindowRectEx(&r, GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION, FALSE, 0)` and insets
+    left, right and bottom by it. When not maximised, the top grows by 1 px so the window can be
+    resized from its top edge. When maximised, the top is inset by the full border, because Windows
+    extends a maximised window beyond the screen by the border thickness. Then it returns 0.
+  - `WM_NCHITTEST`: returns `HTCAPTION` when maximised. Otherwise, over the top bar, points within the
+    border thickness give `HTTOP` / `HTTOPLEFT` / `HTTOPRIGHT` / `HTLEFT` / `HTRIGHT`, and the rest of
+    the bar gives `HTCAPTION`.
+  - `WM_GETMINMAXINFO`: `HandleGetMinMaxInfo` + `AdjustWorkingAreaForAutoHide`, which keeps a
+    maximised window off an auto-hide taskbar (#8085) and also masks `WS_CAPTION`.
+- `BBLTopbar::MSWWindowProc` returns `HTTRANSPARENT` for `WM_NCHITTEST` over empty bar areas and the
+  title, and `CenteredTitle::MSWWindowProc` always returns it. The frame's `HTCAPTION` answer then
+  provides native dragging, double-click maximise and Snap. `BBLTopbar::OnMouseLeftDown` does
+  `CaptureMouse(); ReleaseMouse();` and posts `WM_NCLBUTTONDOWN` with `HTCAPTION`.
+
+**Pitfall**
+- **Rule:** For a Windows frame with a custom title bar, handle `WM_NCCALCSIZE` yourself. Mask
+  `WS_CAPTION` out of the style passed to every `AdjustWindowRectEx`
+  (`GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION`). In the maximised branch, strip the full border
+  overshoot on all four sides instead of returning early.
+  **Why:** wx adds `WS_CAPTION` whenever a min/max/close box is requested, and puts it back when the
+  style is recomputed. Letting `DefWindowProc` (or an unmasked `AdjustWindowRectEx`) compute the
+  non-client area subtracts a caption you draw yourself, so a maximised window leaves a gap above the
+  taskbar.
+  ```cpp
+  // Wrong: caption height included; maximised case left to DefWindowProc
+  AdjustWindowRectEx(&b, GetWindowLongPtr(hWnd, GWL_STYLE), FALSE, 0);
+  if (wPos.showCmd == SW_SHOWMAXIMIZED) break;
+  // Right
+  AdjustWindowRectEx(&b, GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION, FALSE, 0);
+  b.left *= -1; b.top *= -1;
+  sz->rgrc[0].top += (wPos.showCmd == SW_SHOWMAXIMIZED) ? b.top : 1;
+  sz->rgrc[0].left += b.left; sz->rgrc[0].right -= b.right; sz->rgrc[0].bottom -= b.bottom;
+  return 0;
+  ```
+  Cite: eefdabcd98 (`MainFrame::MSWWindowProc`).
+
+### Linux (GTK): the borderless MainFrame
+
+**wx mechanism** [source, `src/gtk/toplevel.cpp`]:
+- At creation, wx turns the style into WM hints (`m_gdkDecor`, `m_gdkFunc`, :880-925).
+  `wxBORDER_NONE` / `wxSIMPLE_BORDER` call `gtk_window_set_decorated(false)`.
+- On Wayland with GTK ≥ 3.10, a bordered window without `wxCAPTION` gets a `gtk_header_bar_new()`
+  titlebar (:900-906); `BORDERLESS_FRAME_STYLE` is such a style.
+- On realise, `GTKHandleRealized` calls `gdk_window_set_decorations(window, m_gdkDecor)` (:400-444).
+  When a client-side titlebar exists it first sets `m_gdkDecor = 0`, because "Don't set WM
+  decorations when GTK is using Client Side Decorations".
+
+**OrcaSlicer design:**
+- **No WM decorations.** `MainFrame::MainFrame` sets `m_gdkDecor = 0` (a `public:` implementation
+  member of `wxTopLevelWindowGTK`, `include/wx/gtk/toplevel.h:108-109`) before the frame is
+  realised, so the window manager draws no title bar, while `m_gdkFunc` keeps move, resize, minimise,
+  maximise and close. `BBLTopbar` is the only title bar (d50b4cbf3d, #12600 "No more double title
+  bar").
+- **Move.** `BBLTopbar::OnMouseLeftDown`, on empty bar areas and the title, calls
+  `gtk_window_begin_move_drag(GTK_WINDOW(m_frame->m_widget), 1, x, y, gtk_get_current_event_time())`
+  with `x, y` taken from `ClientToScreen(event.GetPosition())`. This is a compositor-driven move, and
+  on Wayland it is the only way a client can move its window.
+- **Maximise.** `BBLTopbar::OnFullScreen`, which also handles a double-click on the title, uses
+  `gtk_window_is_maximized` / `gtk_window_maximize` / `gtk_window_unmaximize` on GTK.
+- **Resize.** Three `ResizeEdgePanel`s (bottom, left, right; `BORDER_PX` = 5): transparent `wxPanel`s
+  (`wxBG_STYLE_TRANSPARENT`, empty `wxPaintDC` paint) that are `Raise()`d above all siblings, so their
+  GDK windows receive pointer events even over WebKit2GTK or GL surfaces. On motion they set a named
+  cursor (`gdk_cursor_new_from_name`, `"s-resize"`, `"sw-resize"`, …). On left-down they call
+  `gtk_window_begin_resize_drag` with the matching `GdkWindowEdge`, unless the frame is maximised or
+  fullscreen. `MainFrame::update_edge_panels` hides them while maximised or fullscreen, lays them out
+  along the client edges and raises them again. `MainFrame::shutdown` clears the pointers; wx
+  destroys the panels as children. They use event-relative coordinates, not a global event filter
+  keyed on `wxGetMousePosition()`, which cannot work on Wayland (6049c6e234, #12705).
+
+**Pitfall**
+- **Rule:** Move and resize the borderless frame through `gtk_window_begin_move_drag` /
+  `gtk_window_begin_resize_drag` with the current event time. Do not capture the mouse and call
+  `Move()` / `SetSize()` from global coordinates.
+  **Why:** on Wayland, clients cannot position top-level windows and get no global pointer position,
+  so a manual drag does nothing or jumps. On X11, the WM-driven drag also gives edge snapping and
+  correct multi-monitor behaviour.
+  ```cpp
+  // Wrong (GTK): manual drag
+  CaptureMouse(); /* on motion: */ m_frame->Move(::wxGetMousePosition() - m_delta);
+  // Right (GTK)
+  wxPoint p = ClientToScreen(event.GetPosition());
+  gtk_window_begin_move_drag(GTK_WINDOW(m_frame->m_widget), 1, p.x, p.y, gtk_get_current_event_time());
+  ```
+  Cite: `BBLTopbar::OnMouseLeftDown`; `ResizeEdgePanel::OnLeftDown` (`MainFrame.cpp`).
+
+### macOS: a native titled window
+
+- [source] wxOSX gives a window `NSTitledWindowMask` as soon as any of `wxMINIMIZE_BOX`,
+  `wxMAXIMIZE_BOX`, `wxCLOSE_BOX`, `wxSYSTEM_MENU` or `wxCAPTION` is set, and adds the
+  miniaturizable, resizable and closable masks for the matching boxes
+  (`src/osx/cocoa/nonownedwnd.mm:816-831`). `BORDERLESS_FRAME_STYLE` therefore still produces a titled
+  window with the standard window buttons. `wxRESIZE_BORDER` is left out on Apple, and the window is
+  still resizable because `wxMAXIMIZE_BOX` already adds `NSResizableWindowMask`.
+- `set_miniaturizable(GetHandle())` (`Utils/MacDarkMode.mm`, called in `MainFrame::MainFrame` under
+  `__WXOSX__`) sets `titlebarAppearsTransparent`, sets a dark window background colour, ORs in
+  `NSMiniaturizableWindowMask`, and remembers the title `NSTextField`.
+  `set_title_colour_after_set_title` re-colours that field white after the title changes.
+- There is no `BBLTopbar` on macOS: the top area is a plain `wxPanel`, and the menus live in the
+  native `wxMenuBar`.
+- Fullscreen: Cmd+Ctrl+F calls `EnableFullScreenView(true)` and toggles `ShowFullScreen()`.
+  `EnableFullScreenView` is OSX-only, and the full-screen button is needed for the animated
+  fullscreen space (`interface/wx/toplevel.h:700-728`).
+
+### Wayland: undecorated top-level windows (splash)
+
+- **Rule:** To show a truly undecorated top-level window (the splash screen) on Wayland, don't rely on
+  wx style flags or window-type hints. Install an empty client-side titlebar and disable decoration
+  on the GTK window in the constructor, before control returns to the event loop. [source] The
+  `wxSplashScreen` base constructor has already called `Show(true)` (`src/generic/splash.cpp`), so in
+  `SplashScreen` these calls land right after the show request and before any event is processed; in
+  a window you show yourself, make them before `Show()`:
+  ```cpp
+  #if defined(__WXGTK__)
+  if (Slic3r::GUI::is_running_on_wayland()) {
+      GtkWidget* empty = gtk_fixed_new();
+      gtk_widget_set_size_request(empty, 0, 0);
+      gtk_window_set_titlebar(GTK_WINDOW(GetHandle()), empty);
+      gtk_window_set_decorated(GTK_WINDOW(GetHandle()), false);
+  }
+  #endif
+  ```
+  **Why:** some Wayland desktop environments ignore splash-typed window properties (wxGTK's
+  `wxSplashScreen` sets `GDK_WINDOW_TYPE_HINT_SPLASHSCREEN`) and draw a title bar anyway. This
+  happens even though `wxBORDER_NONE` already makes wx call `gtk_window_set_decorated(false)`. Forcing an empty client-side titlebar removes it on every
+  desktop environment.
+  Cite: 1b71835337 (`SplashScreen::SplashScreen` in `GUI_App.cpp`; the splash style is
+  `wxBORDER_NONE | wxFRAME_NO_TASKBAR`, plus `wxSTAY_ON_TOP` on Apple).
+
+## GTK native chrome and GTK size calls
+
+**Helpers** (`GUI_Utils.hpp`, declared under `__WXGTK__`):
+- `RemoveButtonBorder(wxWindow*)` is "for wxButton/wxBitmapToggleButton based controls (SwitchButton,
+  CheckBox)".
+- `RemoveInputBorder(wxWindow*)` is "for TextCtrl based controls (TextInput, ComboBox, SpinInput..)".
+
+Both return immediately if `GetHandle()` is null, so call them after the control is created; the
+widgets do it in their constructors.
+- **GTK3** (and the GTK4 branch): a `GtkCssProvider` is added to the widget's own style context at
+  `GTK_STYLE_PROVIDER_PRIORITY_USER`, then released with `g_object_unref` (the context keeps its
+  reference). The CSS covers `button, button:hover, button:active, button:focus`, or
+  `entry, entry text, entry undershoot` for inputs, and zeroes `border`, `outline`, `box-shadow`,
+  `padding`, `margin`, `min-height` and `min-width`, with `background: none`.
+- **GTK2**: `gtk_rc_parse_string` installs a **global** rc style keyed by widget path or class
+  (`"*.GtkBitmapToggleButton"`, class `"GtkEntry"`). The first call changes every matching widget in
+  the process, not just the one passed in.
+
+**Callers:** `CheckBox::CheckBox`, `SwitchButton`, `RadioBox`, `ScalableButton`, `ObjColorDialog` and
+`PresetComboBoxes` (`RemoveButtonBorder`); the inner `wxTextCtrl` of `TextInput` and `SpinInput`
+(`RemoveInputBorder`). A new owner-drawn control built on a native GTK widget needs the same call.
+
+**Sizing a bitmap button on GTK.** A `wxBitmapToggleButton`/`wxButton`-based widget sized to exactly its
+bitmap leaves no room for the theme's CSS padding, and GTK logs "negative content width" criticals.
+Either strip the button CSS with `RemoveButtonBorder` and size to the bitmap (`CheckBox::Rescale`), or
+size to `GetBestSize()` grown to the bitmap (`IncTo`; `RadioBox::Rescale` and `SwitchButton::Rescale`
+do both). Cite: 6148ba16b3, 988b500f33.
+
+**Pitfalls**
+- **Rule:** To strip native GTK control chrome (entry and button borders, padding), attach a
+  `GtkCssProvider` at `GTK_STYLE_PROVIDER_PRIORITY_USER` to the widget's style context, and include the
+  pseudo-class states (`button, button:hover, button:active, button:focus { ... }`), plus the inner
+  subnodes for entries (`entry, entry text, entry undershoot`). Guard the code with `#ifdef __WXGTK__`,
+  branch GTK2/3/4 with `GTK_CHECK_VERSION`, and keep the `.hpp` declaration guard identical to the
+  `.cpp` definition guard.
+  **Why:** wx border-style flags don't remove GTK theme borders or padding, which show up as black
+  borders on Linux. CSS without `:hover` / `:focus` lets the border come back on interaction. Guards
+  that differ between header and implementation (`__WXGTK3__` vs `__WXGTK__`) break the build on other
+  GTK versions.
+  ```cpp
+  // Wrong: wx flags alone, border reappears / theme padding stays
+  text_ctrl = new wxTextCtrl(this, wxID_ANY, text, pos, size, style | wxBORDER_NONE);
+  // Right
+  text_ctrl = new wxTextCtrl(this, wxID_ANY, text, pos, size, style | wxBORDER_NONE);
+  #ifdef __WXGTK__
+  Slic3r::GUI::RemoveInputBorder(text_ctrl);
+  #endif
+  ```
+  Cite: 477208a969 (`GUI_Utils.cpp` `RemoveButtonBorder` / `RemoveInputBorder`, `GUI_Utils.hpp`).
+- **Rule:** Guard direct `gtk_window_resize()` calls (and similar GTK size calls) so they run only with
+  strictly positive width and height.
+  **Why:** GTK checks the arguments (`gtk_window_resize: assertion 'width > 0'`) when a popup is
+  measured before it has content. This spams assertion errors on Linux and aborts when GTK criticals
+  are made fatal. `DropDown` resizes the GTK wrapper window itself (source comment: "Gtk has a
+  wrapper window for popup widget"), so its size can be zero before the items exist.
+  ```cpp
+  // Wrong
+  gtk_window_resize(GTK_WINDOW(m_widget), szContent.x, szContent.y);
+  // Right
+  if (szContent.x > 0 && szContent.y > 0)
+      gtk_window_resize(GTK_WINDOW(m_widget), szContent.x, szContent.y);
+  ```
+  Cite: dc12126b78 (`DropDown::messureSize`, `Widgets/DropDown.cpp`).
+
+## wx 3.3 migration notes
+
+Orca moved from **3.1.5** to 3.3.2 in 8248b06337 ("Updated wxWidgets to 3.3.2", #12941; build system
+in 2d7e26292b), so the 3.1.6–3.2.0 incompatible changes (`docs/changes_32.txt`) apply as well as
+`docs/changes.txt`. The version digest, every migration commit as a rule for new code, and the
+post-upgrade regressions to watch are owned by `references/wx-33-changes.md` (§8). The
+platform-specific ones are described in this file: the `MainFrame` `WS_CAPTION` handling
+([MSW title bar](#msw-the-mainframe-custom-title-bar)), the macOS `kAEGetURL` re-registration and the
+`SidePopup` anchoring ([ifdef landscape](#the-ifdef-landscape)), and the GTK criticals filter
+([GTK3 summary](#gtk3-x11-and-wayland)).
+
+## Cross-platform testing checklist
+
+Because wx asserts are compiled out, a platform bug usually shows up as wrong pixels, a dropped
+event or a frozen interaction, not a dialog. Exercise the change; a successful build proves little.
+Say in the PR which platforms you exercised.
+
+**Build**
+- [ ] Every toolkit branch compiles: `__WXMSW__`, `__WXOSX__`, `__WXGTK__`. GTK code also compiles with
+      the GTK2 branch of any `GTK_CHECK_VERSION`, and header/implementation guards match.
+- [ ] New Cocoa code is in a `.mm` file registered in the `APPLE` block, and new sources are added to
+      `src/slic3r/CMakeLists.txt`.
+- [ ] No `FromSVG*`, no new wx private header without the matching port macro, no reliance on a wx
+      assert.
+
+**Windows**
+- [ ] 100 %, 125 %, 150 % and 175 % scaling, plus moving the window between monitors with different
+      scaling (PMv2 `wxEVT_DPI_CHANGED`, `DPIAware` rescale, `on_dpi_changed`).
+- [ ] Light and dark, including switching dark mode at runtime from Preferences.
+- [ ] `MainFrame` maximise/restore, maximise with an auto-hide taskbar, Snap, drag from the top bar,
+      resize from the top edge.
+- [ ] Popups: open, then click elsewhere, Alt+Tab, minimise the main window; the popup must close
+      exactly once.
+- [ ] Live window resize with the 3D view visible (no blank canvas); custom-painted widgets don't
+      flicker.
+
+**macOS**
+- [ ] A Retina and a non-Retina display, and moving windows between them.
+- [ ] Switching system appearance while the app runs.
+- [ ] Menu-bar shortcuts vs text fields (typing in a field must not trigger a menu shortcut), and
+      Cmd+H / Cmd+M / Cmd+Q / Cmd+Ctrl+F.
+- [ ] Popups and dropdown menus: move the cursor from the anchor into the menu without it
+      dismissing; nothing stays captured after a drag (the UI must stay clickable).
+- [ ] `ObjectList` editing and keyboard shortcuts (native data view).
+
+**Linux, GTK3 on X11** (`GDK_BACKEND=x11` on a Wayland session, or an X11 session)
+- [ ] Scale 1 and 2 (`GDK_SCALE=2`), light and dark GTK themes, large font settings (text-driven
+      sizes, `em_unit`).
+- [ ] No native borders or padding around custom widgets; dialogs open at their fitted size and don't
+      collapse after minimising the main window.
+- [ ] The GL views render (GLX path), and WebView pages load.
+
+**Linux, GTK3 on native Wayland**: at least GNOME (mutter) and one wlroots compositor (Sway or
+Hyprland); KDE is worth a run for decoration differences.
+- [ ] Moving and resizing the main window through the top bar and the edges; maximise/restore; no
+      second title bar; the splash has no title bar.
+- [ ] Popups, chained dropdown submenus and search dropdowns open in the right place, track hover and
+      dismiss correctly.
+- [ ] Nothing depends on `wxGetMousePosition()`, `SetPosition()` on a top-level window, or
+      `wxClientDC` drawing. No CPU spin with the window on an inactive workspace.
+- [ ] GL views render after startup (EGL post-init retry), and overlay icons are not translucent.
+- [ ] Dock panes cannot float, and a layout saved on X11 loads.
+
+**Packaging**
+- [ ] The Flatpak build (shared wx, GTK3, sandbox) if the change touches wx options, file dialogs,
+      WebView or desktop integration.
+
+**Debugging aids**
+- [ ] In a Debug or RelWithDebInfo build, Ctrl+Shift+I (Cmd+Shift+I on macOS) on any `DPIAware` window
+      opens wxInspector to check the window tree, sizes and styles per platform.
+- [ ] On Linux, remember that `GUI_App::on_init_inner` filters some GTK criticals. Check the terminal
+      output for the rest.

.claude/skills/orca-wxwidgets/references/sizers-layout.md

@@ -0,0 +1,822 @@
+# Sizers and layout
+
+How wx 3.3.2 computes window sizes and lays out children, and how OrcaSlicer builds layouts on top of
+that: sizers and flags, best/min size, the fitting functions (`SetSizerAndFit`, `SetSizeHints`, `Fit`,
+`Layout`, `FitInside`) per platform, show/hide relayout, Freeze/Thaw, scrolled windows, `wxStaticText`
+wrapping, layout on DPI change, and Orca's layout idioms. Read it when building or reviewing any dialog
+or panel layout, or when debugging a window that is collapsed, clipped, too large or not re-laid out.
+
+Contents: [Rules](#rules) · [Build facts](#build-facts-that-change-how-layout-bugs-present) ·
+[Size model](#the-size-model-best-min-effective-min-initial-virtual) ·
+[Fitting functions](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout) ·
+[Re-layout](#re-layout-after-content-or-visibility-changes) · [Adding items](#adding-items-proportion-flags-wxsizerflags) ·
+[Ownership](#ownership-and-removal) · [Specific sizers](#specific-sizers) ·
+[Size events](#wxevt_size-handlers) · [Freeze/Thaw](#freeze--thaw) ·
+[Scrolled windows](#scrolled-windows) · [Static text wrapping](#wxstatictext-wrapping-and-ellipsizing) ·
+[Layout on DPI change](#layout-on-dpi-change) · [Platform summary](#platform-summary) ·
+[Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions)
+
+## Rules
+
+1. On a top-level window, attach the finished sizer with `SetSizerAndFit(sizer)`. If `SetSizer` must
+   come before the content exists, call `GetSizer()->SetSizeHints(this)` once the content is built, and
+   again after rebuilding content. Never rely on `Fit()` alone. → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout)
+2. Child panels use plain `SetSizer`; never `SetSizerAndFit` or `sizer->SetSizeHints(panel)` on a
+   non-top-level window (it pins the panel's min size). → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout)
+3. Keep a dialog's content within any `SetMaxSize` (cap a scrolled region), or the min > max hints are
+   silently dropped. → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout)
+4. Proportion is the second argument: `Add(w, 0, wxEXPAND | wxALL, FromDIP(n))`, never `Add(w, wxEXPAND)`.
+   → [Adding items](#adding-items-proportion-flags-wxsizerflags)
+5. In a box sizer, alignment and `wxEXPAND` act only across the sizer's direction, and `wxEXPAND`
+   overrides alignment; contradictory flags are silently ignored in Orca. → [Adding items](#adding-items-proportion-flags-wxsizerflags)
+6. Give `proportion > 0` only to items that must stretch; proportions inflate the sizer's min size.
+   → [Adding items](#adding-items-proportion-flags-wxsizerflags)
+7. A window managed by a sizer is a child of the sizer's containing window (or of the `wxStaticBox` of a
+   `wxStaticBoxSizer`), and sits in exactly one sizer; `Detach` before re-adding.
+   → [Adding items](#adding-items-proportion-flags-wxsizerflags), [Ownership](#ownership-and-removal)
+8. When rebuilding content, destroy the old windows; deleting, clearing or replacing a sizer leaves them
+   alive and visible. → [Ownership](#ownership-and-removal)
+9. After changing content or visibility, `Layout()` the nearest ancestor whose allocation must change;
+   resize a top-level window with `GetSizer()->SetSizeHints(tlw)`. `Hide()` is always followed by a
+   `Layout()`. → [Re-layout](#re-layout-after-content-or-visibility-changes)
+10. A `wxEVT_SIZE` handler calls `Skip()` and never `SetSize`s its own window. → [Size events](#wxevt_size-handlers)
+11. `Freeze()`/`Thaw()` must balance on every path; use `wxWindowUpdateLocker`. → [Freeze/Thaw](#freeze--thaw)
+12. A scrolled window needs a non-zero `SetScrollRate`, `FitInside()` after its content changes, and an
+   explicit min size or proportion + `wxEXPAND` in its parent. → [Scrolled windows](#scrolled-windows)
+13. To re-wrap a `wxStaticText` after `SetLabel`, call `Wrap(-1); Wrap(w);`, or use `Label` with
+   `LB_AUTO_WRAP`; use `Label` for CJK text. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing)
+14. Never compute or commit a size from a width that has not been laid out yet. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing)
+15. Give wrapping labels a fixed width and `-1` height, never a fixed height. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing)
+16. In `on_dpi_changed`, re-apply what wx does not rescale, then resize with
+   `GetSizer()->SetSizeHints(this)`; never multiply existing min sizes or borders by a DPI ratio.
+   → [Layout on DPI change](#layout-on-dpi-change)
+17. A custom widget reports its size through its min size (Orca widgets) or `DoGetBestClientSize()`, and
+   invalidates it when content, label or font change. → [Size model](#the-size-model-best-min-effective-min-initial-virtual)
+18. Pixel values are `FromDIP(n)` or `n * em_unit()`; borders are explicit `FromDIP(n)`; dialog button
+   rows are `DialogButtons`. → [Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions)
+
+## Build facts that change how layout bugs present
+
+- **Every wx layout assert is silent in Orca.** wx is built with `wxBUILD_DEBUG_LEVEL=0` and
+  `libslic3r_gui` with `wxDEBUG_LEVEL=0`, so `wxASSERT`/`wxFAIL` compile to nothing and `wxCHECK_*` return
+  early without a message (`include/wx/debug.h:314-324, 342-382`). The checks that would flag layout
+  mistakes in a debug wx therefore do nothing, and the review has to catch them by reading the code:
+  - flag consistency in box sizers (`wxBoxSizer::DoInsert`, `src/common/sizer.cpp:2295`);
+  - "window managed by the sizer must have the containing window as parent" (`wxSizer::DoInsert`,
+    `sizer.cpp:904, 947`);
+  - mixed parents in one `wxStaticBoxSizer` (`wxStaticBoxSizer::RepositionChildren`, `sizer.cpp:2888`);
+  - duplicate or out-of-range `AddGrowableCol/Row` (`sizer.cpp:2235, 2250`);
+  - `Thaw()` without `Freeze()` (`src/common/wincmn.cpp:1247`);
+  - a window added to a second sizer (`wxWindowBase::SetContainingSizer`, `wincmn.cpp:2421`): the
+    `wxCHECK_RET` refuses the bookkeeping, but the item is still inserted;
+  - top-level `SetSizeHints` with min > max (`wxWindowBase::DoSetSizeHints`, `wincmn.cpp:1041`): the
+    whole call is dropped.
+- **Linux is GTK3** (`DEP_WX_GTK3` ON, `SLIC3R_GTK` "3"); GTK2 is an opt-out build. GTK-only facts below
+  are GTK3 unless marked.
+- **DIP model.** `wxHAS_DPI_INDEPENDENT_PIXELS` is defined for wxGTK3 and wxOSX
+  (`include/wx/features.h:115`): logical pixels are DIPs and `FromDIP` is the identity. On MSW `FromDIP`
+  scales by the window's DPI (`wincmn.cpp` `wxWindowBase::FromDIP`); GTK2 takes the same conversion path,
+  but its display PPI is always 96, so `FromDIP` is the identity there too **[source]**. DIP conversion
+  itself: see `references/dpi-bitmaps-fonts.md`.
+
+## The size model: best, min, effective min, initial, virtual
+
+**Contract** (`docs/doxygen/overviews/windowsizing.h:23-100`):
+- *Best size* is derived from content. *Min size* is "normally explicitly set by the programmer"; most
+  controls also take it from a non-default ctor size. *Initial size* is the ctor size; a partly specified
+  size such as `wxSize(150, -1)` is completed from the best size. *Virtual size* is the scrollable extent.
+- `GetEffectiveMinSize()` merges the best size into the min size: "This is the value used by sizers to
+  determine the appropriate amount of space to allocate for the widget" (`interface/wx/window.h:1393-1402`). It is the min size with unspecified components filled
+  from the best size (`wincmn.cpp:868`). Once `SetMinSize(wxSize(w, h))` sets both components, the
+  content no longer affects the sizer allocation; pass `-1` for the component that must follow content.
+- "The best size respects the minimal and maximal size explicitly set for the window" (`window.h:1342-1350`;
+  `wincmn.cpp:879`: raised to min, lowered to max). It is **cached only when the window has no sizer**
+  **[source]** (`wincmn.cpp:881`). Containers with sizers recompute every time; leaf controls and custom
+  widgets return the cache until `InvalidateBestSize()` (`window.h:1645-1651`; the cache is documented for
+  `DoGetBestClientSize`, `window.h:4432-4435`).
+- `InvalidateBestSize()` also invalidates the parent chain, stopping at a top-level window **[source]**
+  (`wincmn.cpp:636`). It does not lay anything out (see [Re-layout](#re-layout-after-content-or-visibility-changes)).
+- The default `DoGetBestSize()` uses the sizer's min size; without a sizer, the bounding box of visible
+  children; with no children, the min size or (1,1) (`wincmn.cpp:649`).
+- `SetInitialSize(size)` sets the min size to `size`, merges it with the best size and resizes
+  (`window.h:1742-1757`, `wincmn.cpp:937`). A ctor size therefore becomes the min size: a fixed height
+  pins the minimum height.
+- `SetMinSize` "doesn't prevent the program from making the window explicitly smaller … by calling
+  SetSize(), it just ensures that it won't become smaller than this size during the automatic layout"
+  (`window.h:1808-1815`). Top-level windows are the documented exception: their size hints also stop the
+  program's own `SetSize()` (`interface/wx/toplevel.h:576-603`). **[source]** On GTK, top-level windows and
+  `wxPopupWindow` clamp `SetSize` to min/max (`src/gtk/toplevel.cpp:1365` `ConstrainSize`,
+  `src/gtk/popupwin.cpp:171`).
+- On a top-level window, `SetMinSize`/`SetMaxSize` go through `SetSizeHints(min, max)`
+  (`src/common/toplvcmn.cpp:197-205`), so a min larger than the current max (or the reverse) is dropped
+  silently.
+- `wxWindow::SetSizeHints` on a non-top-level window "is discouraged. Please use SetMinSize() and
+  SetMaxSize() instead" (`window.h:1885-1891`).
+- **Height-for-width (3.3.2).** `GetMinSizeFromKnownDirection(direction, size, availableOtherDir)`
+  (`window.h:1404-1444`) lets a control report its min size once the layout fixes one dimension; box and
+  flex-grid sizers feed the known width to their items during layout, and `wxSizer::CalcMinSizeFromKnownDirection`
+  is the sizer side (`interface/wx/sizer.h:339-377`). `InformFirstDirection` is the deprecated
+  compatibility path. `wxST_WRAP` and `wxWrapSizer` rely on this negotiation. `DoGetBestClientHeight()`/
+  `DoGetBestClientWidth()` are "not used by wxWidgets yet" (`window.h:4453-4455`): overriding them changes
+  no sizer layout.
+
+**Writing a custom control (wx way).** Override `DoGetBestClientSize()` and let `DoGetBestSize()` add the
+borders (`windowsizing.h:46-51`, `window.h:4421-4441`); the default returns `wxDefaultSize` and the best
+size is then arbitrary. Call `SetInitialSize()` at the end of `Create()`, and `InvalidateBestSize()`
+whenever content, label or font change.
+
+**OrcaSlicer.** The `StaticBox`-based widgets (`Button`, `TextInput`, `SpinInput`, `ComboBox`) do not
+override `DoGetBestClientSize`. Each has (or inherits) a `messureSize()` that measures its content and calls
+`wxWindow::SetMinSize(...)`, and they override `SetMinSize` to merge a caller's request with the content
+size: `Button::SetMinSize` stores the request (its height overrides, its width is a floor), and
+`TextInput::SetMinSize` fills a `-1` height from the current size. Re-measuring happens inside their
+`SetLabel`/`SetFont`/`Rescale` overrides, so callers only re-lay out the parent. A min size is honoured
+identically by every sizer and has no cache to invalidate, so this design never needs `InvalidateBestSize()`.
+Writing a new Orca widget: see `references/painting-custom-widgets.md`.
+
+For owner-drawn text whose height depends on width, follow `WikiLabel` (`src/slic3r/GUI/Preferences.cpp`):
+re-wrap on width change, then `SetMinSize(wxSize(-1, totalH))` + `InvalidateBestSize()`; override
+`DoGetBestSize()`; guard `GetCharHeight()` against 0 before the window is realized on GTK (Orca comment).
+
+## Fitting functions: SetSizer, SetSizerAndFit, SetSizeHints, Fit, Layout
+
+**Contract.**
+- `SetSizer(s, deleteOld = true)`: "The window will then own the object, and will take care of its
+  deletion"; `deleteOld` deletes a previous sizer (pass `false` only if you delete it yourself). It "will
+  also call SetAutoLayout() implicitly with true … so that the sizer will be effectively used to layout
+  the window children whenever it is resized" (`window.h:3693-3715`).
+- `SetSizerAndFit(s)` "calls SetSizer() and then wxSizer::SetSizeHints() which sets the initial window
+  size to the size needed to accommodate all sizer elements and sets the minimal size to the same size,
+  this preventing the user from resizing this window to be less than this minimal size (if it's a
+  top-level window …)" (`window.h:3717-3728`; `wincmn.cpp:2414`).
+- `wxSizer::SetSizeHints(win)` is documented as "first calls Fit() and then
+  wxTopLevelWindow::SetSizeHints() … It does nothing in normal windows or controls", with the idiom of
+  calling the panel's sizer's `SetSizeHints(frame)` to size the frame to fit the panel
+  (`interface/wx/sizer.h:937-970`). **[source]** The doc is outdated: it calls
+  `WXSetInitialFittingClientSize(wxSIZE_SET_CURRENT | wxSIZE_SET_MIN)` (`sizer.cpp:1284`), which calls
+  `SetMinClientSize()` then `SetClientSize()` on **any** window (`wincmn.cpp:974`). On a child panel it
+  freezes the panel's min size at its current content.
+- `wxSizer::Fit(win)` resizes the window so its client area matches the sizer's min size
+  (`sizer.h:454-463`; `sizer.cpp:1243`: `wxSIZE_SET_CURRENT` only).
+- `wxWindow::Fit()` "only changes the current window size and doesn't change its minimal size"
+  (`window.h:1066-1077`); it is `SetSize(GetBestSize())` (`wincmn.cpp:625`), except that a top-level window
+  without a sizer and with exactly one child sets its client size to that child's best size
+  (`toplvcmn.cpp:508`).
+- `Layout()` "doesn't do anything" without a sizer unless the window is top-level; it "is called
+  automatically when the window size changes if it has the associated sizer" (`window.h:3753-3769`). It
+  positions children inside the current virtual size (`wincmn.cpp:2469`). A top-level window without a
+  sizer and with exactly one child resizes that child to fill the client area (`toplvcmn.cpp:475`).
+
+| Call | Sets current size | Sets min size | Clamped to display (TLW) | GTK3: replayed at `Show()` if called while hidden |
+|---|---|---|---|---|
+| `win->SetSizer(s)` | no | no | – | – |
+| `win->SetSizerAndFit(s)` | yes (client) | yes (client) | yes | yes |
+| `s->SetSizeHints(win)` | yes | yes | yes | yes (with the window's own sizer) |
+| `s->Fit(win)` | yes | **no** | yes | yes |
+| `win->Fit()` | yes | **no** | **no** | **no** |
+| `win->Layout()` | no (positions children) | no | – | – |
+
+**[source]** `ComputeFittingClientSize` (`sizer.cpp:1194`) clamps a **top-level** window only to the
+display client area; the doc's "maximum window size if previously set" applies to child windows only. If
+a dialog's `SetMaxSize` is smaller than its content, `SetSizeHints` computes min > max,
+`DoSetSizeHints` drops the hints, and on GTK the following `SetClientSize` is clamped to the max: the
+dialog ends up with no enforced minimum.
+
+**GTK3 hidden-window replay [source]** (`src/gtk/toplevel.cpp`). `wxTopLevelWindowGTK::WXSetInitialFittingClientSize`
+(`:1726`) applies the fit at once and, if the window is still hidden, stores the flags because the "GTK
+style cache hasn't been updated yet"; `Show()` (`:1262-1266`) and `GTKDoAfterShow()` (`:1687`) replay them
+through `GTKUpdateClientSizeIfNecessary()` (`:1702`), which re-fits with the window's **own** sizer (a
+`panel_sizer->SetSizeHints(frame)` on a sizer-less frame is not replayed). An explicit `SetMinSize()`
+cancels the pending minimum (`:1715-1723`); an explicit size change cancels the pending current size but
+keeps the pending minimum (`:1384-1396`). `wxWindow::Fit()` never takes this path, so a hint-less GTK3
+dialog keeps whatever was measured with the stale style cache.
+
+**GTK size hints [source].** WM min/max geometry hints are set only for `wxRESIZE_BORDER` windows; a
+non-resizable dialog is sized through `gtk_widget_set_size_request` in `DoSetSize`
+(`toplevel.cpp:1485-1503, 1399-1407`). Either way the min comes from `SetSizeHints`.
+
+**Usage — the three canonical shapes:**
+```cpp
+// (a) content built before the sizer is attached
+SetSizerAndFit(main_sizer);                // size + min, display-clamped, GTK3-safe
+CenterOnParent();
+
+// (b) sizer attached early, content added later (MsgDialog::finalize)
+SetSizer(main_sizer);  /* ... add content ... */
+GetSizer()->SetSizeHints(this); Layout(); CenterOnParent();
+
+// (c) content changed after the dialog exists (PrinterPartsDialog::Show)
+/* ... show/hide/add rows ... */
+GetSizer()->SetSizeHints(this);            // not Fit(): Fit() leaves the old minimum
+```
+`SetSizeHints` already sets the current size, so a `Fit()` before it is redundant, and a `Fit()` after it
+only re-applies the best size without the display clamp.
+
+**OrcaSlicer.** The project rule (`AGENTS.md`): "Always use `SetSizerAndFit(sizer)` instead of
+`SetSizer(sizer)` on top level window. Unless `SetSizer` must be called before the full layout is built,
+call `sizer->SetSizeHints(window)` afterwards in this case." Models: `CloneDialog` ctor (shape a);
+`MsgDialog` (its ctor calls `SetSizer(main_sizer)`, subclasses add content, `MsgDialog::finalize` runs
+`GetSizer()->SetSizeHints(this); Layout(); Fit(); CenterOnParent(); wxGetApp().UpdateDlgDarkUI(this);`);
+`NetworkPluginDownloadDialog` ctor (`main_sizer->SetSizeHints(this)` after building the mode-specific UI);
+`PrinterPartsDialog::Show` (shows/hides its panels and rows, then `GetSizer()->SetSizeHints(this)` before
+`DPIDialog::Show`); the calibration dialogs in `calib_dlg.cpp` (`Layout(); Fit(); v_sizer->SetSizeHints(this);`).
+
+**Pitfalls**
+- **Rule:** Top-level dialogs get their minimum from `SetSizerAndFit` or `sizer->SetSizeHints(this)`,
+  never from `Fit()` alone.
+  **Why:** `Fit()` sets no minimum, is not display-clamped and is not replayed at GTK3 show; a dialog
+  whose minimum was never propagated from its children renders collapsed or mis-sized on GTK3 and can be
+  shrunk below its content anywhere.
+  ```cpp
+  // Wrong
+  SetSizer(main_sizer); Layout(); main_sizer->Fit(this);
+  // Right (layout fully built)
+  SetSizerAndFit(main_sizer); Layout();
+  // Right (sizer set early, content built later, e.g. MsgDialog::finalize; its trailing Fit() is redundant)
+  GetSizer()->SetSizeHints(this); Layout(); Fit();
+  ```
+  Cite: 5ede9711f5 (`MsgDialog::finalize`, `UnsavedChangesDialog::build`, `PrinterPartsDialog::Show`,
+  `CloneDialog` ctor and other dialog ctors; added the `AGENTS.md` rule).
+- **Rule:** Lock in the minimum in the constructor, before the dialog can receive iconize, refresh or DPI
+  events.
+  **Why:** Per f760f4e462's message, on wxGTK iconizing the main window while a hint-less dialog is open
+  re-ran `Fit()` with transient zero-sized children and collapsed the dialog (OK button clipped); the
+  WM then honoured the small geometry, so the user could not resize it back. The trigger chain is not
+  visible in wx source; what is verified is that `Fit()` never updates the minimum and that a minimized
+  top-level window reports a (0,0) client size (`window.h:1375-1376`; GTK `toplevel.cpp:1463`).
+  ```cpp
+  Layout(); Fit();                                  // Wrong: no enforced minimum
+  Layout(); Fit(); v_sizer->SetSizeHints(this);     // Right (the Fit() is redundant)
+  ```
+  Cite: f760f4e462 (`FlowRateCalibrationDialog` ctor, `calib_dlg.cpp`).
+- **Rule:** Child panels use `SetSizer`, not `SetSizerAndFit`.
+  **Why:** `SetSizeHints` pins the panel's min client size at its current content **[source]**. A fully
+  specified min size replaces the best size in `GetEffectiveMinSize()`, so the parent sizer stops tracking
+  the panel's content: it no longer shrinks when content is removed or translations get shorter, nor grows
+  when content is added.
+  ```cpp
+  panel->SetSizerAndFit(s);   // Wrong
+  panel->SetSizer(s);         // Right
+  ```
+  Cite: `wincmn.cpp:974` `WXSetInitialFittingClientSize`.
+- **Rule:** After content added to a shown dialog, call `GetSizer()->SetSizeHints(this)`, not `Fit()`.
+  **Why:** `Fit()` grows the window but keeps the old minimum, so the WM can shrink it below the new
+  content; after removing content `Fit()` cannot shrink below the stale minimum either.
+  ```cpp
+  add_extra_row(); Fit();                       // Wrong: stale minimum
+  add_extra_row(); GetSizer()->SetSizeHints(this);   // Right
+  ```
+  Cite: `PrinterPartsDialog::Show` (re-hints after showing/hiding its rows).
+- **Rule:** Keep content within a dialog's `SetMaxSize` by capping a scrolled region.
+  **Why:** min > max hints are silently rejected (`wincmn.cpp:1041`) and the dialog has no minimum.
+  Cite: `MsgDialog` (`MSG_DLG_MAX_SIZE` caps height only, "ban setting the maximum width value") with
+  `add_msg_content` capping the scrolled text.
+
+## Re-layout after content or visibility changes
+
+**Contract.**
+- `wxSizer::Layout()` recomputes min sizes and repositions items inside the sizer's **current**
+  rectangle (`sizer.h:705-710`, `sizer.cpp:1272`); `wxWindow::Layout()` does the same within the window's
+  size. Neither propagates upward. If a change alters a container's min size, `Layout()` the nearest
+  ancestor whose allocation must change; if the top-level window itself must grow or shrink, call
+  `GetSizer()->SetSizeHints(tlw)`. Manual `Layout()` is needed only after a content change that does not
+  come with a size change; a resize lays out automatically.
+- "To make a sizer item disappear, use Hide() followed by Layout()" (`sizer.h:569-603`). `wxWindow::Show`
+  only flips the flag; the ports do not re-lay out the parent (`wincmn.cpp:1128`). A window item is shown
+  exactly when the window `IsShown()` (`sizer.cpp:863`) unless it carries `wxRESERVE_SPACE_EVEN_IF_HIDDEN`
+  (next item), so `win->Hide()` and `sizer->Hide(win)` are
+  equivalent for layout. `sizer->Show(win, …)` with `recursive = false` returns false and does nothing when
+  `win` sits in a nested sizer. Hiding is honoured only by `wxBoxSizer` and `wxFlexGridSizer`
+  (`docs/doxygen/overviews/sizer.h:134`).
+- `wxRESERVE_SPACE_EVEN_IF_HIDDEN` (`wxSizerFlags::ReserveSpaceEvenIfHidden()`) makes `wxSizerItem::IsShown()`
+  return true whatever the window's state (`sizer.cpp:863-865`; doc `interface/wx/sizer.h:94-99, 1343-1345`).
+  The hidden item keeps its min size and position, since `wxBoxSizer::CalcMin` and `RepositionChildren` skip
+  only `!IsShown()` items (`sizer.cpp:2745, 2428`), and its `wxFlexGridSizer` row or column does not collapse
+  (`sizer.cpp:1957`): showing or hiding it moves no neighbour and resizes no parent. `sizer->IsShown(win)`
+  then reports true for a hidden window (`sizer.cpp:1562`); ask `win->IsShown()`. On a sizer item the flag
+  reserves only the nested sizer's min size, which still skips that sizer's hidden children
+  (`wxSizerItem::CalcMin`, `sizer.cpp:680-682`), so a nested sizer whose children are all hidden collapses to
+  the item's border (or the nested sizer's `SetMinSize`); put the flag on the window items.
+- `wxStaticText::SetLabel` resizes the control itself (unless `wxST_NO_AUTORESIZE`) but never re-lays out
+  the parent (`src/common/stattextcmn.cpp` `AutoResizeIfNecessary`).
+- `SendSizeEvent()`: "if the frame is using either sizers or constraints … it is enough to call
+  wxWindow::Layout() directly and this function should not be used in this case" (`window.h:1668-1686`).
+  `PostSizeEvent()` queues it instead (`window.h:1653-1658`), which defers a relayout past the current
+  handler and the GTK allocation.
+
+**Usage.**
+```cpp
+row->Show(enabled);                 // or sizer->Show(row_sizer, enabled)
+GetParent()->Layout();              // or the ancestor whose min size changed
+// top-level window must change size too:
+GetSizer()->SetSizeHints(this);
+```
+
+**OrcaSlicer.** Page switching by sizer visibility: the `wxEVT_TAB_SEL_CHANGED` handler in
+`PreferencesDialog` runs `Freeze(); f_sizers[i]->Show(i == selection); Layout(); Thaw();`.
+`PreferencesDialog::UpdateSidebarLayout` re-lays out the sidebar inside `Freeze()/Thaw()` and then calls
+`plater->PostSizeEvent()` so the plater re-lays out after GTK has allocated. Show/hide driven by hover
+must not run inside enter/leave handlers (it re-fires them); see `references/mouse-keyboard-focus.md`.
+Reserved space: `KBShortcutsDialog::create_page` adds each editable row's reset button with
+`wxALIGN_CENTRE_VERTICAL | wxRESERVE_SPACE_EVEN_IF_HIDDEN`, so `KBShortcutsDialog::apply_bindings` toggles
+`reset->Show(is_customized)` without the buttons column changing width.
+
+## Adding items: proportion, flags, wxSizerFlags
+
+**Contract.**
+- `Add(win, int proportion = 0, int flag = 0, int border = 0, userData = nullptr)`
+  (`interface/wx/sizer.h:186`). Proportion is the **second** argument; `Add(w, wxEXPAND)` passes
+  `0x2000` as a proportion.
+- Proportion acts only along the sizer's direction; `wxEXPAND` and alignment act only across it. Default
+  alignment is left/top.
+- **Proportion inflates the min size [source].** `wxBoxSizer::CalcMin` (`sizer.cpp:2728`) sizes the main
+  direction as `max_i(min_i / prop_i) × Σprop + Σ(fixed items)`. Two `proportion = 1` items with min
+  widths 100 and 300 make the sizer at least 600 wide, which also widens a `SetSizerAndFit` dialog. The
+  overview's "half the extra space each" (`overviews/sizer.h:114`) is outdated: 3.x distributes the
+  total space by proportion with min-size floors (`wxBoxSizer::RepositionChildren`, `sizer.cpp:2402`).
+- Box-sizer flag rules, checked only by compiled-out asserts in `wxBoxSizer::DoInsert` (`sizer.cpp:2295`):
+  a vertical box ignores `wxALIGN_BOTTOM` and `wxALIGN_CENTRE_VERTICAL` (unless combined with
+  `wxALIGN_CENTRE_HORIZONTAL`, i.e. `wxALIGN_CENTRE`); a horizontal box ignores `wxALIGN_RIGHT` and
+  `wxALIGN_CENTRE_HORIZONTAL` (unless with `wxALIGN_CENTRE_VERTICAL`); `wxEXPAND` without `wxSHAPED`
+  overrides every alignment. In `wxGridSizer`, `wxEXPAND | wxALIGN_CENTRE_VERTICAL` means "expand
+  horizontally, centre vertically". `DisableConsistencyChecks()` (`sizer.h:1609`) is irrelevant in Orca.
+- Parent rule: windows managed by a sizer must be children of the sizer's containing window, or of a
+  `wxStaticBox` inside it (`sizer.cpp` `CheckExpectedParentIs`); otherwise they are positioned in the
+  wrong coordinate space, silently.
+- `wxSizerFlags` (`include/wx/sizer.h:40-240`): `Align()`/`Centre()` **replace** all alignment bits,
+  while `Left/Right/Top/Bottom/CentreHorizontal/CentreVertical` set one axis (`:60-75`).
+  `Border(dir, px)` takes raw pixels and the doc prefers the default border "to avoid too small borders
+  … with high DPI" (`interface/wx/sizer.h:1502-1519`). The default border is 6 on GTK and 5 on macOS (not
+  scaled); on MSW it is `5 × GetDPIScaleFactor()` of **`wxApp::GetMainTopWindow()`**, not of the window
+  being laid out (`include/wx/sizer.h:125-141`, `sizer.cpp:172` **[source]**; doc `sizer.h:1652-1661`).
+  `FixedMinSize()` (`wxFIXED_MINSIZE`) copies the window's current size into its min size when added
+  (`sizer.cpp:395-409`). `Shaped()` keeps the aspect ratio. `ReserveSpaceEvenIfHidden()` keeps a hidden
+  item's space (`wxRESERVE_SPACE_EVEN_IF_HIDDEN`, `sizer.h:1641-1650`; see
+  [Re-layout](#re-layout-after-content-or-visibility-changes)).
+- `AddSpacer(n)`: in `wxSizer` it adds `n × n` (a whole cell in grid sizers); in `wxBoxSizer` only along
+  the main direction. `AddStretchSpacer(p)` is `Add(0, 0, p)` (`sizer.h:300-331`).
+
+**OrcaSlicer.** Orca uses int flags with explicit DIP borders,
+`Add(w, 0, wxEXPAND | wxALL, FromDIP(10))`, rather than `wxSizerFlags::Border()` defaults, so spacing is
+identical on every port instead of 5/6 px (and main-window DPI on MSW).
+
+**Pitfalls**
+- **Rule:** Pass the proportion before the flags.
+  ```cpp
+  sizer->Add(ctrl, wxEXPAND);                        // Wrong: proportion 0x2000, no flags
+  sizer->Add(ctrl, 0, wxEXPAND);                     // Right
+  sizer->Add(ctrl, wxSizerFlags(1).Expand().Border(wxALL, FromDIP(5)));  // Right
+  ```
+- **Rule:** Do not combine `wxEXPAND` with an alignment in a box sizer, and align only across the sizer.
+  **Why:** EXPAND wins; a main-direction alignment is ignored. The assert that names the conflict is
+  compiled out, so the flag silently does nothing.
+  ```cpp
+  vbox->Add(x, 0, wxEXPAND | wxALIGN_CENTER_VERTICAL);   // Wrong: alignment ignored
+  vbox->Add(x, 0, wxALIGN_CENTER_VERTICAL);              // Wrong: main-direction alignment
+  vbox->Add(x, 0, wxALIGN_CENTER_HORIZONTAL);            // Right
+  ```
+- **Rule:** A fixed-size neighbour of a stretching item gets proportion 0.
+  **Why:** proportions inflate `CalcMin`, widening the fitted dialog.
+
+## Ownership and removal
+
+**Contract.**
+- "Sizers, like child windows, are owned by the library and will be deleted by it which implies that
+  they must be allocated on the heap. However if you create a sizer and do not add it to another sizer or
+  window, the library wouldn't be able to delete such an orphan sizer and in this, and only this, case it
+  should be deleted explicitly" (`interface/wx/sizer.h:45-49`). Sizers own child sizers and spacers, not
+  child windows; a sizer has exactly one owner: a parent sizer or one `SetSizer`.
+- `Detach(win|sizer|index)` never destroys and "does not cause any layout or resizing to take place, call
+  Layout() to update the layout 'on screen'" (`sizer.h:416-451`). `Remove(wxSizer*)`/`Remove(index)`
+  destroy sizers and spacers; `Remove(wxWindow*)` is deprecated and does **not** destroy the window
+  despite its name (`sizer.h:789-835`). `Clear(delete_windows = false)` always deletes child sizers and
+  destroys child windows (via `Destroy()`) only with `true` (`sizer.h:378-389`, `sizer.cpp:1169`).
+  `Replace(oldwin, newwin)` neither hides nor destroys `oldwin`, which stays on screen at its last
+  position; `Replace(oldsizer, newsizer)` deletes the old sizer (`sizer.h:836-882`).
+- A destroyed window detaches itself from its containing sizer (`wincmn.cpp:510`). Deleting or replacing
+  a sizer, including `SetSizer(new)` with `deleteOld`, only clears its windows' containing-sizer pointers
+  (`sizer.cpp:519` `wxSizerItem::Free`): the old controls stay alive and visible as unmanaged ghosts.
+- A window belongs to one sizer: "Adding a window already in a sizer, detach it first!"
+  (`wincmn.cpp:2421`). In Orca the check is silent and the item is still appended, so the second sizer
+  holds a dangling pointer once the window dies.
+- `wxStaticBoxSizer` owns its box; its destructor destroys the box with `WXDestroyWithoutChildren`, which
+  reparents the box's children to the box's parent instead of destroying them (`sizer.cpp:2822`).
+
+**Pitfalls**
+- **Rule:** Destroy old windows when rebuilding a panel.
+  ```cpp
+  panel->SetSizer(build_rows());                      // Wrong: old rows stay as ghosts
+  panel->DestroyChildren(); panel->SetSizer(build_rows()); panel->Layout();   // Right
+  // or: old_sizer->Clear(true) before refilling it
+  ```
+- **Rule:** `Detach` a window before adding it to another sizer.
+  **Why:** the silent `wxCHECK` leaves both sizers pointing at it.
+- **Rule:** After `Replace(old, neu)`, `old->Destroy()` (or `Hide()`) and `Layout()`.
+  **Why:** `Replace` leaves `old` drawn at its last position.
+
+## Specific sizers
+
+**`wxStaticBoxSizer`** — "strongly encouraged to create the windows which are added … as children of
+wxStaticBox itself … creating them using the static box parent as parent still works too (but note that
+items using different parents can't be used inside the same sizer" (`interface/wx/sizer.h:2036-2045`).
+Use `sz->GetStaticBox()` as the parent. **[source]** Box-children are positioned box-relative: (0,0) on
+GTK, a fixed 10 px inset on macOS, the static borders on MSW (`wxStaticBoxSizer::RepositionChildren`,
+`sizer.cpp:2888`); mixing the two parents mispositions one group. Orca: `LabeledStaticBox`
+(`Widgets/LabeledStaticBox.hpp`, a `wxStaticBox`) is the box to use (`new wxStaticBoxSizer(stb, wxVERTICAL)`
+in `OptionsGroup` and `calib_dlg.cpp`); those layouts parent all items to the dialog, which is valid as long
+as no item in that sizer is parented to the box.
+
+**`wxGridSizer`** — every cell gets the size of the largest item; `cols` alone lets rows grow; with both
+`rows` and `cols` given, at most `rows × cols` items are allowed (`sizer.h:1897-1944`). **[source]** Adding
+more is an assert in a debug wx; in Orca `wxGridSizer::DoInsert` silently forgets the row count and lets rows
+grow (`sizer.cpp:1642-1670`). Hidden items still occupy their cells (`wxGridSizer::RepositionChildren`,
+`sizer.cpp:1711`, has no `IsShown` check).
+
+**`wxFlexGridSizer`** — per-row heights and per-column widths; growables via `AddGrowableCol(idx, prop)`;
+if all proportions are 0, all growables share equally; re-adding an index requires `RemoveGrowableCol`
+first (`sizer.h:1770-1792`). Indices are checked only against fixed ctor counts (`sizer.cpp:2235-2262`).
+`SetFlexibleDirection`/`SetNonFlexibleGrowMode` "do not trigger relayout" (`sizer.h:1859-1878`). **[source]**
+Hidden items keep their cell; a row or column (gap included) collapses only when all its items are hidden
+(`wxFlexGridSizer::FindWidthsAndHeights`, `SumArraySizes`). A growable
+column grows the cell, not the control: the item also needs `wxEXPAND`.
+```cpp
+if (!flex->IsColGrowable(1)) flex->AddGrowableCol(1, 1);   // rebuild-safe
+flex->Add(value_ctrl, 0, wxEXPAND);                         // fill the grown cell
+```
+
+**`wxGridBagSizer`** — `Add(win, wxGBPosition, wxGBSpan, flag, border)` returns `nullptr` when the cell is
+occupied (`interface/wx/gbsizer.h:82-95`) and the window stays unmanaged: check the result.
+`SetEmptyCellSize` sets the size of empty rows and columns (`gbsizer.h:195`).
+
+**`wxWrapSizer`** — lays items out along the primary direction and wraps to new lines;
+`wxEXTEND_LAST_ON_EACH_LINE | wxREMOVE_LEADING_SPACES` is the default (`interface/wx/wrapsizer.h`).
+**[source]** Before it has been given a width its min size is the largest single item
+(`wxWrapSizer::CalcMin` → `CalcMaxSingleItemSize`, `src/common/wrapsizer.cpp:182, 243`), so a dialog fitted
+before the first layout is sized for one item per line. Put it where it receives a definite width
+(`wxEXPAND` in a vertical box under a container with a known width) and re-fit after the first `Layout()`.
+
+**`wxStdDialogButtonSizer`** — `AddButton` accepts only the stock ids (`wxID_OK/YES/SAVE/APPLY/CLOSE/NO/
+CANCEL/HELP/CONTEXT_HELP`); other ids go through `SetAffirmativeButton`/`SetNegativeButton`/`SetCancelButton`;
+`Realize()` must be called to order and space the buttons; order follows the platform, and on macOS a
+`wxID_SAVE` button is relabelled "Save" and `wxID_NO` "Don't Save" (`sizer.h:1030-1151`). Orca uses
+`DialogButtons` instead
+([Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions)).
+
+**Books and splitters** (other API: `references/controls-dataview.md`). **[source]** A book control's best
+size is the **max over all pages** unless the protected `SetFitToCurrentPage(true)` was called
+(`wxBookCtrlBase::DoGetBestSize`, `src/common/bookctrl.cpp:125-148`), so a large hidden page enlarges a fitted
+dialog. `wxSplitterWindow::SetMinimumPaneSize` takes pixels: pass `FromDIP(n)`.
+
+## wxEVT_SIZE handlers
+
+**Contract.** "Sizers rely on size events … in a sizer-based layout, do not forget to call Skip on all
+size events you catch" (`interface/wx/event.h:5058-5060`). Automatic layout is the static-table handler
+`wxWindowBase::InternalOnSize` (`wincmn.cpp:124, 2489`) and `wxTopLevelWindowBase::OnSize`
+(`toplvcmn.cpp:40`). `Bind()` handlers run before static tables, so a bound handler that does not
+`Skip()` suppresses auto-layout (handler order: `references/events.md`). **[source]** `wxScrolled<>` always
+runs its own size handling after user handlers, skipped or not (`src/generic/scrlwing.cpp:203-214`).
+
+**Pitfalls**
+- **Rule:** Skip, don't `Layout()` (it runs anyway) and never `SetSize` the same window inside its size
+  handler; defer other relayouts with `CallAfter` or `PostSizeEvent`.
+  ```cpp
+  Bind(wxEVT_SIZE, [this](wxSizeEvent&) { recompute(); });               // Wrong: no auto-layout
+  Bind(wxEVT_SIZE, [this](wxSizeEvent& e) { recompute(); e.Skip(); });   // Right
+  ```
+  Cite: `Label::OnSize`, `CenteredMultiLinePanel::OnSize` (both skip).
+
+New code binds with `Bind()` and lambdas; no new static event tables (`references/events.md`).
+
+## Freeze / Thaw
+
+**Contract** (`window.h:2203-2232`). `Freeze()` suppresses painting of the window and, recursively, its
+non-top-level children; calls nest and must balance; it is "mostly just a hint". **[source]** Children
+added while frozen are frozen too, removed ones are thawed (`wxWindowBase::AddChild`/`RemoveChild`).
+Freezing does **not** stop layout or size events. RAII: `wxWindowUpdateLocker` (`include/wx/wupdlock.h:19`).
+
+**Platforms [source].** MSW: `Freeze()` on a hidden window only counts; the native redraw lock is skipped
+(`wxWindowMSW::DoFreeze`, `src/msw/window.cpp:1659`) and applied by a later `Show()` while still frozen
+(`wxWindowMSW::Show`). macOS: `Refresh()` returns early while `IsFrozen()` or not shown
+(`src/osx/window_osx.cpp:1340-1346`).
+
+**Pitfalls**
+- **Rule:** Balance on every path; prefer `wxWindowUpdateLocker`.
+  **Why:** an unmatched `Freeze()` leaves the window and its children unpainted. An unmatched `Thaw()`
+  is worse: `m_freezeCount` is `unsigned` (`include/wx/window.h:2063`) and the "Thaw() without matching
+  Freeze()" assert is compiled out, so the count wraps to `UINT_MAX`, `IsFrozen()` stays true from then on
+  (a later balanced pair only drops it to 0 between its `Freeze()` and `Thaw()`), and on macOS the window
+  stops repainting.
+  ```cpp
+  Freeze(); if (!rebuild()) return; Thaw();          // Wrong: early return leaves it frozen
+  wxWindowUpdateLocker lock(this); if (!rebuild()) return;   // Right
+  ```
+
+**OrcaSlicer.** `wxWindowUpdateLocker` brackets bulk rebuilds in `Tab.cpp`, `ParamsPanel.cpp`,
+`PresetComboBoxes.cpp`, `GUI_ObjectSettings.cpp`; `DPIAware::rescale` wraps `on_dpi_changed` in
+`Freeze()`/`Thaw()`.
+
+## Scrolled windows
+
+**Contract** (`interface/wx/scrolwin.h`).
+- `wxScrolledWindow` (`wxScrolled<wxPanel>`) hosts child controls; `wxScrolledCanvas`
+  (`wxScrolled<wxWindow>`) is for drawn content; `wxScrolled<wxControl>` is not advised (`:24-40`).
+- **Scrolling is off until a rate is set**: "scrolling is only enabled in orientations with a non-zero
+  increment" (`:57-66`); both rates start at 0. Vertical-only: `SetScrollRate(0, FromDIP(n))`.
+- With a sizer, the virtual size follows the sizer; "if you add or remove any elements to the sizer, you
+  need to call wxSizer::FitInside() to adjust the virtual size" (`:66-68`). `wxWindow::FitInside()` =
+  `SetVirtualSize(GetBestVirtualSize())` (`wincmn.cpp:631`); `wxSizer::FitInside(win)` "will not alter the
+  on screen size" (`sizer.h:465-473`). **[source]** A size event re-derives the virtual size
+  (`wxScrollHelperBase::HandleOnSize`, `scrlwing.cpp:924`).
+- **Best size ignores content in a scrolling direction [source]**: with a sizer, in each direction with a
+  non-zero rate the best size is `GetMinSize() + scrollbar thickness` (`wxScrolledT_Helper::FilterBestSize`,
+  `scrlwing.cpp:1594-1634`: "If the app needs some minimal size for its scrolled window, it should set it
+  and put the window into sizer as expandable"). Without `SetMinSize` and proportion/`wxEXPAND` it
+  collapses to about the scrollbar width.
+- `EnableScrolling(x, y)` toggles **physical** (blit) scrolling; it does not enable or disable a
+  direction (`:338-356`). Direction is chosen by the scroll rate and the `wxHSCROLL`/`wxVSCROLL` style.
+- `ShowScrollbars(horz, vert)` (`wxSHOW_SB_NEVER/DEFAULT/ALWAYS`) works only after creation; the
+  `wxALWAYS_SHOW_SB` style is the ctor-time equivalent for both directions (`:358-384`).
+- Children report physical positions: a child at (10,10) reports (10,-90) after scrolling 100 px
+  (`:90-96`). `GetViewStart()` is in scroll units; `GetViewStartPixels()` is new in 3.3.2 (`:405-458`).
+- `SetTargetWindow(w)` requires overriding `GetSizeAvailableForScrollTarget()` (`:602-617, 719-731`).
+- A focused child is scrolled into view; override `ShouldScrollToChildOnFocus` to opt out (`:705-717`).
+  Mouse-drag autoscroll is configurable with `EnableAutoScrollInside`/`DisableAutoScrollOutside` (new in
+  3.3.2, `:628-661`).
+- Drawing in a scrolled window (`OnDraw`, `DoPrepareDC`, `DoPrepareReadOnlyDC`): see
+  `references/painting-custom-widgets.md §DC coordinates and scale under DPI`.
+
+**Usage — "shrink to content, scroll beyond a cap":**
+```cpp
+auto sw = new wxScrolledWindow(parent, wxID_ANY, wxDefaultPosition, wxDefaultSize, wxVSCROLL);
+sw->SetScrollRate(0, FromDIP(20));
+sw->SetSizer(content);
+// after every content change:
+int h = std::min(content->GetMinSize().y, cap);
+sw->SetMinSize(wxSize(-1, h));
+sw->FitInside();
+parent->Layout();
+```
+Orca: `Sidebar::update_filaments_area_height` (`SetMaxSize` from a preferred row count, then
+`SetMinSize({-1, min(sizer min, max)})` on `m_panel_filament_content`, with `FitInside()` after rebuilds);
+`add_msg_content` in `MsgDialog.cpp` (a `wxScrolledWindow(wxVSCROLL)` with `SetScrollRate(0, FromDIP(20))`, a
+`Label(…, LB_AUTO_WRAP)` with min = max width, the window's min = max size set to
+`(info_width, min(content, 48 * em))`, then `FitInside()`), which keeps the message within the dialog max.
+
+**Orca `ScrolledWindow`** (`Widgets/ScrolledWindow.hpp`) — a `wxScrolled<wxWindow>` that hides the native
+bars (`ShowScrollbars(NEVER, NEVER)`) and draws slim `MyScrollbar`s in a margin strip:
+- content goes on `GetPanel()`, the `SetTargetWindow` target (`GetSizeAvailableForScrollTarget` is not
+  overridden);
+- the ctor builds its inner windows from the passed `size`, so pass a real size;
+- the virtual size is set manually in pixels: `SetScrollbars(1, 1, w, h)` or its own `SetVirtualSize`,
+  which only **hides** the non-virtual `wxWindow::SetVirtualSize` — `FitInside()` and calls through a
+  `wxWindow*` bypass the custom bars;
+- its size handler resizes the inner panels and calls `Layout(); AdjustScrollbars();`;
+- use it with `wxVSCROLL` only: `SetBackgroundColour` dereferences the vertical-only members.
+```cpp
+// SearchDialog::SearchDialog (Search.cpp)
+auto sw   = new ScrolledWindow(parent, wxID_ANY, wxDefaultPosition, wxSize(W, H), wxVSCROLL, 6, 6);
+auto list = new wxWindow(sw->GetPanel(), wxID_ANY);
+list->SetSizer(s); list->Fit();
+sw->SetScrollbars(1, 1, 0, list->GetSize().GetHeight());
+```
+Ordinary dialogs and the sidebar use plain `wxScrolledWindow`.
+
+**Pitfalls**
+- **Rule:** A scrolled area that "doesn't scroll" lacks `SetScrollRate` or a `FitInside()` after the
+  content changed; one that collapses lacks a min size or proportion + `wxEXPAND`.
+- **Rule:** Forbid horizontal scrolling with `SetScrollRate(0, y)` and/or a `wxVSCROLL`-only style.
+  ```cpp
+  sw->EnableScrolling(false, true);       // Wrong: only disables blit scrolling
+  sw->SetScrollRate(0, FromDIP(20));      // Right
+  ```
+
+## wxStaticText wrapping and ellipsizing
+
+**Contract.**
+- `Wrap(width)` breaks lines at word boundaries and **modifies the label** (`interface/wx/stattext.h:119-130`,
+  `include/wx/stattext.h:37-40`). `width < 0` means no wrapping; the width is not exact because of borders.
+  `Wrap` is not virtual.
+- **3.3.2 wrap cache [source].** `wxStaticTextBase::Wrap` returns at once when `width == m_currentWrap`
+  (`src/common/stattextcmn.cpp:259-263`); `SetLabel` → `UpdateLabelOrig` clears the saved unwrapped
+  label but **not** `m_currentWrap` (`:354-365`). So `SetLabel(new); Wrap(sameWidth);` leaves the new
+  text unwrapped. `Wrap(-1); Wrap(w);` resets the cache.
+- wx breaks only at whitespace and outputs an unbreakable run whole (`stattextcmn.cpp:184-215`): CJK text
+  without spaces never wraps with `wxStaticText::Wrap`.
+- `wxST_WRAP` (new in 3.3.2): "Wrap label text on multiple lines if necessary, using the available
+  horizontal space. This style only works when the control is used inside a sizer"
+  (`interface/wx/stattext.h:46-49`; `docs/changes.txt:280`). It is opt-in; labels without it are
+  unaffected. It is implemented with `GetMinSizeFromKnownDirection` (`stattextcmn.cpp:285-312`).
+  **[source]** The initial `CalcMin` still uses the unwrapped best size, so a fitted dialog grows to the
+  full one-line width and nothing wraps; constrain the width another way (a fixed or min width on the
+  container, `SetMaxSize`).
+- `SetLabel` resizes the control to its best size unless `wxST_NO_AUTORESIZE`, which right- or
+  centre-aligned labels whose width the sizer sets need (`stattext.h:30-36`); it never re-lays out the
+  parent; it does nothing when the text is unchanged (`stattext.h:107-117`).
+- `wxST_ELLIPSIZE_*` ellipsize only when the control is narrower than its text (`stattext.h:37-45`); the
+  best size is always the full text, so the sizer allots the full width unless something limits it: a
+  width cap (`SetMaxSize(wxSize(w, -1))`), or an explicit min width plus `wxST_NO_AUTORESIZE`. **[source]**
+  The generic ellipsizer does nothing while the client width or height is < 2 px
+  (`wxStaticTextBase::Ellipsize`).
+- Mnemonics, markup and `SetLabelText`: `references/controls-dataview.md`.
+
+**Platforms [source].** GTK: `GtkLabel` always has line wrap on, so a `wxStaticText` given less width
+than its text wraps natively, while MSW and macOS clip it; best width adds 1 px to avoid spurious wraps
+(`src/gtk/stattext.cpp:126, 239-296`). `SetFont` on a hidden label makes wx measure the text itself
+because the GTK style cache is stale (`gtk/stattext.cpp:178-190`). GTK2 only: a centre/right-aligned label
+silently gets `ELLIPSIZE_MIDDLE`/`START` (`gtk/stattext.cpp:63-90`). MSW uses native end-ellipsis only for
+single-line `wxST_ELLIPSIZE_END` labels; other modes are generic (`src/msw/stattext.cpp:233-256`).
+
+**OrcaSlicer `Label`** (`Widgets/Label.hpp`, `: wxStaticText`):
+- keeps the original text in `m_text`; `Label::Wrap(int)` **hides** the non-virtual `wxStaticText::Wrap`,
+  wraps `m_text` with Orca's `wxTextWrapper2` (breaks between ideographs above U+4E00 and hard-breaks
+  space-less runs) and sets the result through the base `SetLabel` with `m_skip_size_evt` set; it has no
+  width cache;
+- `LB_AUTO_WRAP` binds `wxEVT_SIZE` (with `Skip()`) and re-wraps at the new width; `Label::SetLabel`
+  re-wraps at `GetSize().x` under `LB_AUTO_WRAP` and returns early when the text is unchanged;
+- the label needs a real width: a ctor size `wxSize(FromDIP(w), -1)`, min = max width, or `wxEXPAND` in a
+  vertical sizer whose container width is fixed;
+- `Label::split_lines(dc, width, text, out, max_count)` exposes the same wrapper for owner-drawn text.
+Orca's wrapping is preferred over `wxST_WRAP` for CJK text.
+
+**Pitfalls**
+- **Rule:** Re-wrapping after `SetLabel` must defeat the wrap cache.
+  ```cpp
+  st->SetLabel(msg); st->Wrap(w);                        // Wrong when w is unchanged: stays unwrapped
+  st->SetLabel(msg); st->Wrap(-1); st->Wrap(w);          // Right
+  // or: Label with LB_AUTO_WRAP / label->Wrap(w) through a Label*
+  ```
+- **Rule:** Call `Wrap` through a `Label*`, never through a `wxStaticText*` that points at a `Label`.
+  **Why:** the base `Wrap` sets the wrapped text through the virtual `Label::SetLabel`, which overwrites
+  `m_text` with the wrapped copy (and re-wraps it under `LB_AUTO_WRAP`).
+- **Rule:** Never compute or commit a size or wrap from a width that has not been laid out; guard with a
+  sanity check on the client width.
+  **Why:** a plain `wxWindow`/`wxPanel` child created with `wxDefaultSize` is wx's 20×20 placeholder on
+  every port until the first sizer layout **[source]** (`include/wx/window.h:1914-1915` `WidthDefault`/
+  `HeightDefault`; native controls instead take their best size through `SetInitialSize` in `Create()`),
+  and a minimized top-level window reports a (0,0) client size. Wrapping against that width commits a garbage min size, which `SetSizeHints` then locks in.
+  ```cpp
+  void UpdateMinSize() {
+      int cWidth = GetClientSize().GetWidth();
+      if (cWidth < 50) return;                 // not laid out yet: don't commit a size
+      /* wrap at cWidth, SetMinSize(wxSize(-1, h)), GetParent()->Layout() */
+  }
+  ```
+  Cite: 5ede9711f5 (`CenteredMultiLinePanel::UpdateMinSize` and `::OnPaint` in `TroubleshootDialog.hpp`).
+- **Rule:** Give a wrapping label a fixed width and `-1` height, then wrap.
+  **Why:** the ctor size becomes the min size (`SetInitialSize`), so a fixed height clips the text when a
+  translation is longer.
+  ```cpp
+  new wxStaticText(this, wxID_ANY, txt, wxDefaultPosition, wxSize(FromDIP(490), FromDIP(40)));  // Wrong
+  m_action_line = new wxStaticText(this, wxID_ANY, wxEmptyString, wxDefaultPosition,
+                                   wxSize(FromDIP(490), -1));                                    // Right
+  m_action_line->Wrap(width);
+  ```
+  Cite: 5ede9711f5 (`UnsavedChangesDialog`, `UNSAVE_CHANGE_DIALOG_ACTION_LINE_SIZE`, `m_action_line`).
+- **Rule:** An ellipsized label needs a width limit.
+  **Why:** its best size is the full text, so the sizer gives it the full width and nothing ellipsizes.
+
+## Layout on DPI change
+
+**What wx does per platform.**
+
+| Platform | When `DPIAware::on_dpi_changed` runs | What wx already rescaled |
+|---|---|---|
+| MSW (per-monitor v2 manifest) | `wxEVT_DPI_CHANGED`; also `wxEVT_MOVE_END` when the scale differs | **[source]** before the event, `MSWUpdateOnDPIChange` rescales every window's min/max size, the fonts of non-top-level windows (the TLW keeps its font), every sizer item's border, spacer and nested-sizer min sizes, and invalidates best sizes (`src/msw/window.cpp:5002-5085`; detail in `references/dpi-bitmaps-fonts.md` §wxEVT_DPI_CHANGED) |
+| GTK3 | `wxEVT_DPI_CHANGED` when the integer GDK scale changes (GTK ≥ 3.10, `src/gtk/toplevel.cpp:336-350`) | nothing; logical pixels are DIPs, so DIP sizes stay valid |
+| macOS | never: wx does send `wxEVT_DPI_CHANGED` on backing-scale changes **[source]** (`src/osx/cocoa/nonownedwnd.mm` `windowDidChangeBackingProperties`), but `DPIAware` binds it only `#ifndef __WXOSX__` | nothing needed; Cocoa scales |
+
+A top-level window's default `wxEVT_DPI_CHANGED` handler resizes it, and a handler that does not `Skip()`
+suppresses that (`interface/wx/event.h:3572-3584`). `DPIAware`'s handler does not `Skip()`, so on MSW wx
+skips its own resize of the top-level window (`src/msw/nonownedwnd.cpp:284-318` `HandleDPIChange`): on MSW
+the dialog must resize itself in `on_dpi_changed`. `DPIAware::rescale` (`src/slic3r/GUI/GUI_Utils.hpp`) runs
+`Freeze(); update_em_unit(); on_dpi_changed(rect); Layout(); Thaw();`. The em machinery: see
+`references/dpi-bitmaps-fonts.md`.
+
+`em_unit` per platform (`DPIAware::update_em_unit`): MSW `max(10, 10 × dpi/96)`; macOS always 10 (Orca's
+`get_dpi_for_window` returns 96 there); GTK `max(10, GetTextExtent("m").x − 1)`, i.e. from the font. So
+on GTK an `n * em` size tracks the system font size while `FromDIP(n)` does not; pick one consistently
+for related sizes.
+
+**What `on_dpi_changed` re-applies.** Everything wx does not own:
+- sizes set with `SetSize` or computed into members (cached metrics, wrap widths);
+- `wxDataViewCtrl::SetRowHeight`, column widths and other setter-held values (`references/controls-dataview.md`);
+- bitmaps and `ScalableBitmap`s (`references/dpi-bitmaps-fonts.md`);
+- each Orca widget's `Rescale()` (and `msw_rescale()` where that is its name);
+- min sizes expressed in em, recomputed from the new em (a ratio-free recompute is safe on MSW even
+  though wx already rescaled the stored value);
+- then the top-level resize.
+
+**Usage — the reconciled body:**
+```cpp
+void MyDialog::on_dpi_changed(const wxRect&)          // MyDialog : DPIDialog; members illustrative
+{
+    const int em = em_unit();
+    msw_buttons_rescale(this, em, {wxID_OK, wxID_CANCEL});  // raw wxButtons only: min height 2.5 em (omit with DialogButtons, below)
+    m_apply_btn->Rescale();                                 // Button / TextInput / ComboBox / SpinInput
+    m_logo.msw_rescale();                                   // ScalableBitmap
+    m_logo_ctrl->SetBitmap(m_logo.bmp());                   // the control holds its own copy
+    m_list->SetMinSize(wxSize(40 * em, -1));                // recompute from em, never multiply
+    GetSizer()->SetSizeHints(this);                         // resize + new minimum
+    Refresh();
+}   // DPIAware::rescale then calls Layout() and Thaw()
+```
+`SetSizeHints` both resizes and re-derives the minimum, which a bare `Fit()` does not. A `Fit()` is
+acceptable only when a correct minimum already exists (`PurgeModeDialog::on_dpi_changed` sets
+`SetMinSize(wxSize(70 * em, 32 * em))` and then `Fit(); Refresh();`). **[source]** A `Refresh()`-only
+body (`FlowRateCalibrationDialog::on_dpi_changed`) leaves the dialog at its old pixel size on MSW, so
+content is clipped until the user resizes it; on GTK3 it is harmless. An empty override (`CloneDialog`)
+is accepted only for trivially simple dialogs, with the same MSW caveat. Code placed only in
+`on_dpi_changed` never runs on macOS.
+
+Larger dialogs walk their widgets: `PreferencesDialog::on_dpi_changed` `dynamic_cast`s each child and
+calls `Rescale()` on every `Button`, `TextInput`, `ComboBox`, `SpinInput` and `WikiLabel`, then re-runs its
+tab switch. In such a walk, qualify `::CheckBox`: inside `Slic3r::GUI` an unqualified `CheckBox` names the
+`Field` subclass from `Field.hpp`, which is not a `wxWindow`, so the cast never matches (namespaces:
+`references/orca-widgets.md`). `DialogButtons` rescales itself: it binds its parent's `wxEVT_DPI_CHANGED`,
+rebuilds its row and `Skip()`s. `msw_buttons_rescale` (`wxExtensions.cpp`) calls
+`SetMinSize(wxSize(-1, 2.5 * em))` on whatever window has each id; `DialogButtons` gives its Orca
+`Button`s stock ids, so on a dialog with a `DialogButtons` row it would override their style height
+through `Button::SetMinSize`; leave it out there.
+
+**Pitfalls**
+- **Rule:** Every dialog has an enforced minimum before any DPI/refresh path can resize it, and
+  `on_dpi_changed` resizes with `GetSizer()->SetSizeHints(this)` rather than an unconditional bare `Fit()`.
+  **Why:** a `Fit()` on a dialog without a minimum is the f760f4e462 collapse; a `Fit()` with a stale
+  minimum keeps the old floor; and on MSW a body that does not resize leaves content clipped because
+  `DPIAware` suppresses wx's own resize.
+  ```cpp
+  // Wrong
+  Layout(); Fit();                                      // ctor: no minimum
+  void on_dpi_changed(const wxRect&) override { Refresh(); Fit(); }
+  // Right
+  Layout(); v_sizer->SetSizeHints(this);                // ctor
+  void on_dpi_changed(const wxRect&) override { /* rescale content */ GetSizer()->SetSizeHints(this); Refresh(); }
+  ```
+  Cite: f760f4e462 (`calib_dlg.cpp`), 5ede9711f5; `src/msw/nonownedwnd.cpp` `HandleDPIChange`.
+- **Rule:** Re-apply sizes that wx does not rescale with the same expression as the constructor;
+  never scale an existing value by a DPI ratio.
+  **Why:** setter-held values (row heights, column widths, `SetSize` sizes) never rescale on any port,
+  and stale pixels clip or overflow content (the object-list filament badge no longer fitting its row).
+  On MSW, wx already rescaled stored min/max sizes and sizer borders, so `SetMinSize(GetMinSize() * ratio)`
+  scales twice. On GTK3 and macOS, DIP values need no rescale at all.
+  ```cpp
+  // ObjectList::create_objects_ctrl and again in ObjectList::msw_rescale
+  SetRowHeight(2 * em + FromDIP(2));           // same expression, new em
+  SetMinSize(GetMinSize() * new_scale / old);  // Wrong: double scaling on MSW
+  ```
+  Cite: d5638273c6 (`ObjectList::create_objects_ctrl`, `ObjectList::msw_rescale`).
+
+## Platform summary
+
+- **MSW.** DPI change rescales min/max sizes, non-top-level fonts, sizer borders, spacer and nested-sizer min sizes before
+  `wxEVT_DPI_CHANGED`; Orca must resize the top-level window itself. The default `wxSizerFlags` border
+  follows the main window's DPI. `Freeze()` on a hidden window skips the native redraw lock until the window
+  is shown. A minimized top-level window reports client size (0,0).
+- **macOS.** `FromDIP` is the identity and `em_unit` is 10. Default sizer border 5. `wxStaticBoxSizer`
+  box-children sit at a 10 px inset. `Refresh()` is a no-op while frozen or not shown.
+- **GTK3.** Sizer-fitting calls on a hidden top-level window are replayed at `Show()`; `wxWindow::Fit()` is
+  not. **[source]** `SetFont` before the top-level window is shown queues best-size revalidation at show
+  (`GTKSizeRevalidate`, `src/gtk/window.cpp:6651-6725`), so best sizes measured in a ctor can be wrong
+  until then; re-measure on show or DPI change, or let sizers do it. Top-level and popup `SetSize` are
+  clamped to min/max. WM geometry hints only for `wxRESIZE_BORDER`. `GtkLabel` wraps natively when given
+  less width. Default sizer border 6. A minimized top-level window reports client size (0,0)
+  (`toplevel.cpp:1463`). On X11 the first `Show()` of a top-level window may be deferred until
+  `_NET_FRAME_EXTENTS` arrives (`toplevel.cpp:1140-1240`), so geometry is not final right after `Show()`
+  (window showing: `references/windows-dialogs.md`). em follows the font.
+- **GTK2** (opt-out build). `FromDIP` is the identity in effect (fixed 96 PPI); centre/right-aligned labels
+  are implicitly ellipsized.
+- **Wayland.** `wxWindow::Update()` "doesn't do anything in wxGTK port when using Wayland"
+  (`window.h:2405-2407`): `Layout(); Update();` does not force a synchronous repaint. No deferred first show;
+  with client-side decorations the decoration size counts as 0 for hints (`toplevel.cpp:1519-1523`).
+
+## OrcaSlicer layout idioms and spacing conventions
+
+- **Units.** Every pixel value is `FromDIP(n)` or `n * em_unit()` (`em_unit()` on a `DPIDialog`/`DPIFrame`;
+  the free `em_unit(wxWindow*)` in `wxExtensions.cpp` returns the enclosing `DPIDialog`/`DPIFrame`'s em,
+  else `wxGetApp().em_unit()`). Never raw ints, never `wxSizerFlags::Border()` defaults.
+- **Spacing conventions.** Outer dialog padding `FromDIP(10)`–`FromDIP(20)` with `wxEXPAND | wxALL`;
+  inter-widget gaps `FromDIP(4)`–`FromDIP(12)`; `FromDIP(1)` separators; `sizer->AddSpacer(FromDIP(n))`
+  for vertical rhythm; `AddStretchSpacer()` to push a group to the far side.
+- **Separators.** A 1 px `wxPanel` with a light grey background (`FilamentPickerDialog::CreateSeparatorLine`)
+  or the `StaticLine` widget; avoid `wxStaticLine`.
+- **Button rows.** `DialogButtons` (`Widgets/DialogButtons.hpp`, `Slic3r::GUI`) is a `wxPanel` with its own
+  horizontal `wxBoxSizer`, not a `wxStdDialogButtonSizer`; add it with `main_sizer->Add(dlg_btns, 0, wxEXPAND)`.
+  `UpdateButtons()` rebuilds the row with `m_sizer->Clear()` (the buttons are the panel's children and
+  survive), adds a leading gap when no button is left-aligned, a stretch spacer before the right-aligned
+  group, each button with
+  `wxRIGHT`/`wxLEFT | wxTOP | wxBOTTOM | wxALIGN_CENTER_VERTICAL` and a `FromDIP(ButtonProps::ChoiceButtonGap())`
+  border, then `Layout(); Fit();`. The order is the same on every platform, deliberately unlike wx's
+  per-platform ordering. Older dialogs hand-roll the row with `Button` + `AddStretchSpacer()`;
+  `DialogButtons` is the form for new code. Construction and labels: `references/orca-widgets.md §DialogButtons`;
+its place in a dialog: `references/windows-dialogs.md §8`.
+- **Long static text.** Fixed-width `wxStaticText` + `Wrap(FromDIP(w))` once, or `Label` with
+  `LB_AUTO_WRAP` when the text changes or must wrap CJK ([Wrapping](#wxstatictext-wrapping-and-ellipsizing)).
+- **Bulk rebuilds.** `wxWindowUpdateLocker` (or a balanced `Freeze()`/`Thaw()`), rebuild, `Layout()` the
+  owning ancestor, `SetSizeHints` if the top-level size must change; `PostSizeEvent()` on the plater when
+  the sidebar's height changed.
+- **Size clamps.** Dialogs may clamp with `SetMinSize/SetMaxSize(FromDIP(…))`; keep content within the
+  max ([Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout)).
+- **Exemplars.** `CloneDialog.cpp` (minimal `SetSizerAndFit` dialog), `MsgDialog.cpp` (late content,
+  capped scrolled text), `PrintOptionsDialog.cpp` `PrinterPartsDialog::Show` (show/hide rows + re-hint),
+  `Preferences.cpp` (sizer-visibility pages, height-for-width `WikiLabel`), `Plater.cpp`
+  `Sidebar::update_filaments_area_height` (capped scrolled list).

.claude/skills/orca-wxwidgets/references/strings-i18n-files.md

@@ -0,0 +1,883 @@
+# Strings, translation, files and app services
+
+How text moves between UTF-8 `std::string` and `wxString` under Orca's build flags, how to format
+and translate it, and the wx services that carry text or files in and out of the app: file and
+directory dialogs, paths, browser/app launching, clipboard, drag and drop, logging, native message
+boxes, settings storage, secrets and single-instance handling. Read it before touching any
+user-visible string, any file path or any of those services, and when debugging mojibake, empty
+strings, untranslated text or a lost `&`.
+
+Contents: [Rules](#rules) · [Build facts](#build-facts-that-decide-string-behaviour) ·
+[wxString conversions](#wxstring-encodings-and-conversions) · [Formatting](#formatting) ·
+[Translation](#translation) · [Language switching](#language-switching-and-the-translation-lifecycle) ·
+[Labels & mnemonics](#labels-mnemonics-and-markup) · [Paths](#paths-and-standard-locations) ·
+[File & dir dialogs](#file-and-directory-dialogs) · [Launching](#launching-the-browser-files-and-programs) ·
+[Clipboard](#clipboard) · [Drag & drop](#drag-and-drop) · [Logging](#logging-wxlog-vs-boost-log) ·
+[Message boxes](#native-message-boxes) · [AppConfig](#settings-appconfig-not-wxconfig) ·
+[Secrets](#secrets-wxsecretstore) · [Single instance](#single-instance)
+
+## Rules
+
+1. `std::string` is UTF-8 everywhere outside wx; `wxString` exists only at the wx boundary. Convert
+   with `from_u8`/`into_u8`, paths with `from_path`/`into_path`. → §wxString conversions
+2. Never let a UTF-8 `std::string`/`const char*` reach a `wxString` parameter implicitly (default dir
+   of a file dialog, `SetLabel`, `wxString::Format("%s", …)`): it is decoded with the C-locale
+   encoding, the ANSI code page on Windows. → §wxString conversions
+3. Never take narrow text out of a `wxString` with `ToStdString()`, `mb_str()` or `c_str()`; use
+   `into_u8(w)` or `w.utf8_string()`. → §wxString conversions
+4. Never keep the pointer from `ToUTF8().data()`, `utf8_str()`, `mb_str()` or `c_str()` beyond the
+   full-expression; own a `std::string`. → §Pointer lifetime
+5. Non-ASCII text in source only through `_L(...)`, `wxString::FromUTF8(u8"…")` or `L"…"`, never
+   `wxString("°C")`. → §Source literals
+6. Build user-visible strings with `format_wxstr`/`GUI::format` and `%1%` placeholders; pass
+   `std::string` arguments as they are; write a literal percent as `%%`. → §Formatting
+7. With `wxString::Format`/`Printf`, match every specifier to its argument type yourself (`%zu`,
+   casts); Orca compiles the check out. → §Formatting
+8. Serialise numbers locale-independently; only display goes through the UI locale. → §Numbers
+9. Mark every user-visible literal with an extracted keyword (`L`, `_L`, `_u8L`, `L_CONTEXT`,
+   `_L_CONTEXT`, `_u8L_CONTEXT`, `_L_PLURAL`); never `_()`, `_utf8()`, `_CHB()` for a new string.
+   → §Extraction
+10. A new source file with translatable strings is added to `localization/i18n/list.txt`.
+    → §Extraction
+11. Translate at construction/display time; never cache translated text in a static, namespace-scope
+    variable or long-lived singleton without a re-localise hook. → §Language switching
+12. One complete sentence per msgid, placeholders instead of concatenated fragments, the number
+    placeholder in both plural forms, `// TRN` for ambiguous strings, a context for homonyms.
+    → §Plurals and contexts
+13. A wrapper around `wxGetTranslation` returns `wxString` by value. → §Translation
+14. User-supplied text (preset, filament, file, printer names) in a mnemonic-interpreting label
+    goes through `SetLabelText` or `wxControl::EscapeMnemonics`. → §Labels
+15. File dialogs: filters from `file_wildcards(FT_*)`, default dir `from_u8(app_config->get_last_dir())`,
+    results through `GetPaths`/`GetPath` + `into_path`, never `wxFD_CHANGE_DIR`/`wxDD_CHANGE_DIR`,
+    a real parent window. → §File and directory dialogs
+16. Pass only the dialog's own style flags; `wxDD_NEW_DIR_BUTTON` is 0, use `wxDD_DEFAULT_STYLE`.
+    → §File and directory dialogs
+17. Folders open through `desktop_open_any_folder`/`desktop_open_datadir_folder`; a file that came
+    from a project is launched only after `is_safe_to_open_file_name`. → §Launching
+18. Clipboard access goes through a checked `wxClipboardLocker`; use `SetText`/`wxTextDataObject(text)`,
+    not `wxTextDataObject::SetData`. → §Clipboard
+19. Start `DoDragDrop` from the mouse handler; never replace a drop target from inside its own
+    callbacks. → §Drag and drop
+20. wxLog never reaches the user in Orca; tell the user with `show_error` or a MsgDialog, log with
+    `BOOST_LOG_TRIVIAL` and stream UTF-8. → §Logging
+21. `wxMessageBox` returns `wxYES/wxNO/wxCANCEL/wxOK/wxHELP`, `ShowModal` returns `wxID_*`; UI code
+    uses the MsgDialog family. → §Native message boxes
+22. AppConfig values are set with a `std::string`, never a bare `const char*` third argument, and only
+    on the main thread; no wxConfig. → §AppConfig
+23. Never touch `wxSecretStore` from a timer, poll or other per-tick UI path. → §Secrets
+24. Cross-instance requests go through `instance_check` and `OtherInstanceMessageHandler`; do not add
+    another checker or a wxIPC server. → §Single instance
+
+## Build facts that decide string behaviour
+
+Generic wx advice is often wrong for Orca because of these settings. The installed `setup.h` is
+`<wx install>/lib/wx/include/<port>-unicode-static-3.3/wx/setup.h`.
+
+| Setting | Value in Orca | Where |
+|---|---|---|
+| `wxString` storage | `std::wstring` (`wxUSE_UNICODE_UTF8 0`, `wxUSE_UTF8_LOCALE_ONLY 0`), deep copy, never copy-on-write | installed setup.h; `include/wx/string.h:121-132` |
+| implicit `wxString` → `const char*` / `const void*` | **off**: the app defines `wxNO_UNSAFE_WXSTRING_CONV` | top-level `CMakeLists.txt` (`add_definitions(-DwxNO_UNSAFE_WXSTRING_CONV)`, comment "This implicit conversion breaks the UTF-8 encoding quite often"); `include/wx/string.h:1631-1637` |
+| implicit `wxString` → `std::string` | **off** (`wxUSE_STD_STRING_CONV_IN_WXSTRING 0`) | installed setup.h; `include/wx/string.h:1376-1385` |
+| implicit `std::string` / `const char*` → `wxString` | **on**, decoded with the current locale (`wxNO_IMPLICIT_WXSTRING_ENCODING` is not defined) | `include/wx/string.h:1215-1217, 1323-1325` |
+| wx's own `_()` macro | not defined (`-DWXINTL_NO_GETTEXT_MACRO`); Orca defines its own | `CMakeLists.txt`; `include/wx/translation.h:47-49`; `src/slic3r/GUI/I18N.hpp` |
+| debug level | wx built with `wxBUILD_DEBUG_LEVEL=0`; `libslic3r_gui` gets `wxDEBUG_LEVEL=0` under `SLIC3R_STATIC` (default ON): `wxASSERT`, `Format` type checks, `wxLogDebug`, `wxLogTrace` compile out; `wxCHECK*` still return, silently | `deps/wxWidgets/wxWidgets.cmake`, `src/slic3r/CMakeLists.txt`; `include/wx/log.h:62-77` |
+| printf positional parameters | on (`wxUSE_PRINTF_POS_PARAMS 1`) | installed setup.h |
+| MSVC source charset | `/utf-8`, so narrow literals hold UTF-8 bytes | `CMakeLists.txt` (`add_compile_options(... /utf-8)`) |
+| clipboard, DnD, secret store, config, single-instance checker, IPC | compiled in (all `wxUSE_* 1`); Orca uses its own config and messaging, and the wx checker only on Windows | installed setup.h |
+
+Because asserts are compiled out, every misuse described below fails silently in Orca: wrong or
+empty text, a dropped call, a leaked object. wx would assert in a debug build; Orca never shows it.
+
+## wxString encodings and conversions
+
+**Contract.** A narrow `char*`, `std::string` or `std::string_view` given to wxString "supposes that
+the string contains data in the current locale encoding, use FromUTF8() if the string contains
+UTF-8-encoded data instead"; the implicit constructors are "dangerous … the resulting string will be
+empty if the conversion from the current locale encoding fails" (`interface/wx/string.h:58-89`).
+In the other direction `c_str()`/`mb_str()` are "potentially destructive … an empty string is
+returned if the conversion fails", and `ToStdString()` loses data unless given `wxConvUTF8`; use
+`utf8_string()` (`interface/wx/string.h:108-120, 843-863`). `FromUTF8`: "If s is not a valid UTF-8
+string, an empty string is returned" (`interface/wx/string.h:2037`). The Unicode overview calls
+`FromUTF8()` followed by `c_str()` "a recipe for disaster … may work perfectly well during testing on
+Unix systems using UTF-8 locale but completely fail under Windows" (`docs/doxygen/overviews/unicode.h:314-320`).
+
+**What "current locale encoding" is** (`wxConvLibc`, `src/common/strconv.cpp:3403-3409`) [source]:
+
+| Platform | Narrow ↔ wide conversion | Consequence for UTF-8 data |
+|---|---|---|
+| MSW | `wxMBConv_win32` with `CP_ACP`, the system ANSI code page (`src/common/strconv.cpp:2600-2607`), independent of the UI language Orca picks; Orca's manifest does not opt into a UTF-8 active code page | non-ASCII text becomes mojibake (single-byte code pages) or an empty string (DBCS code pages). A developer machine with Windows' system-wide "Use Unicode UTF-8" option hides the bug |
+| macOS | `wxMBConvLibc` (`mbstowcs`, follows `LC_CTYPE`) | the C runtime stays in the `"C"` locale until `GUI_App::load_language` calls `wxLocale::Init`; in `"C"` macOS maps each byte to one character (mojibake) [tested]; region locales afterwards decode UTF-8 [tested] |
+| GTK | `wxMBConvLibc` | wxGTK calls `gtk_disable_setlocale()` (`src/gtk/app.cpp:526-537`), so the locale is `"C"` until `load_language`; `wxUILocale` then prefers a UTF-8 codeset (`src/unix/uilocale.cpp` `TryCreateLocaleWithUTF8`, `wxSetlocaleTryUTF8`) |
+
+The implicit conversions therefore work on macOS and Linux after startup and break on Windows, so a
+bug of this class survives testing on a Mac.
+
+**What compiles in Orca and what it does:**
+
+| Expression | Compiles? | Encoding |
+|---|---|---|
+| `wxString w = s;` or `f(const wxString&)` called with `std::string`/`const char*` | yes | locale (CP_ACP on MSW): mojibake or empty for UTF-8 |
+| `wxString w(sv)` from `std::string_view` | only explicitly: the ctor is `explicit` (`include/wx/string.h:1327-1328`) although `interface/wx/string.h:71` calls it implicit | locale |
+| `std::string s = w;`, `const char* p = w;` | **no** | — |
+| `w.ToStdString()`, `w.mb_str()`, `(const char*)w.c_str()` | yes | locale; `""` on failure (`wxCStrData::AsChar`, `include/wx/string.h:4292-4303`) |
+| `w.utf8_string()`, `w.ToUTF8()`/`w.utf8_str()`, `into_u8(w)` | yes | UTF-8, never fails |
+| `wxString::FromUTF8(s)`, `from_u8(s)` | yes | UTF-8; `""` on invalid input |
+| `w.ToStdWstring()`, `w.wc_str()`, `wxString(L"…")` | yes | lossless |
+
+**OrcaSlicer helpers** (`src/slic3r/GUI/GUI.hpp`/`GUI.cpp`):
+
+| Helper | Does | Note |
+|---|---|---|
+| `from_u8(const std::string&)` | `wxString::FromUTF8(str.c_str())` | stops at an embedded NUL, `""` on invalid UTF-8; for binary-safe input use `wxString::FromUTF8(s)` (the `std::string` overload passes the length, `include/wx/string.h:1782-1783`) |
+| `into_u8(const wxString&)` | `std::string(str.utf8_str().data())` | owning copy |
+| `from_path(const boost::filesystem::path&)` | `wstring` on Windows, `from_u8(path.string())` elsewhere | |
+| `into_path(const wxString&)` | `boost::filesystem::path(str.wx_str())` | wide on every platform |
+| `file_url_from_path(path)` | `wxFileSystem::FileNameToURL(wxFileName(from_path(path)))` | |
+| `I18N::translate*`, `L_str(std::string)` | decode their narrow input with `wxConvUTF8` | UTF-8 msgids are safe |
+
+ImGui takes UTF-8 `const char*`: `ImGuiWrapper::text(const wxString&)` converts with `into_u8`; raw
+`ImGui::` calls take `_u8L(...)`/`into_u8(...)` (see `references/webview-gl-aui-media.md` for the
+ImGui layer).
+
+### Source literals
+
+MSVC compiles with `/utf-8`, so `"°C"` is a UTF-8 byte string on every compiler, and
+`wxString("°C")` decodes it with the locale like any other narrow string ("never use 8-bit
+characters directly in the program source", `docs/doxygen/overviews/unicode.h:145-160`). Non-ASCII
+text goes through `_L("…")` (decodes UTF-8), `wxString::FromUTF8(u8"\u2103")` (the
+`AMSDryControl.cpp` style for `℃`) or a wide literal `L"…"`. In C++20 `u8"…"` becomes `char8_t`,
+which `FromUTF8` does not accept; Orca builds C++17. Mixing plain ASCII literals with a `wxString`
+(`_L("Version") + " " + v`) is fine.
+
+### Pointer lifetime
+
+`utf8_str()`/`ToUTF8()` return a `wxScopedCharBuffer` and `mb_str()` a `wxCharBuffer` by value
+(`interface/wx/string.h:745-755, 884-886`); each dies at the end of the full-expression. `c_str()`
+returns a `wxCStrData` proxy whose narrow pointer points into a conversion buffer owned by the
+`wxString` itself (`m_convertedToChar`, `src/common/string.cpp` `wxString::AsChar`) [source]: it
+stays valid only until that string is modified, converted again or destroyed, so `_L("…").c_str()`
+dangles at the end of the statement. Note that `wxCStrData` still converts implicitly to
+`const char*` under `wxNO_UNSAFE_WXSTRING_CONV` (`include/wx/string.h:210-217`), so
+`const char* p = w.c_str();` compiles.
+
+- **Rule:** never keep a pointer into a temporary conversion buffer beyond the statement that
+  created it.
+  **Why:** the pointer dangles once the buffer is destroyed; the read returns garbage or crashes
+  later, intermittently, on every platform.
+  ```cpp
+  // Wrong:
+  const char* p = name.ToUTF8().data();
+  use(p);
+  // Right:
+  std::string s = into_u8(name);          // or name.utf8_string()
+  use(s.c_str());
+  ```
+  Cite: `ImGuiWrapper::clipboard_get` keeps the converted text in the member
+  `m_clipboard_text` so the `const char*` it returns stays valid.
+
+Passing a temporary such as `_L("…") + dots` straight into a `const wxString&` parameter is safe,
+even if the callee yields or repaints: the temporary lives until the end of the full-expression and
+`wxString` is a deep-copy `std::wstring`. (The Linux splash crash once blamed on such a temporary
+was the splash screen's event filter, fixed in 4088a36095; see `references/threads-timers-app.md`.)
+
+### Other traps
+
+- `s[n]` returns a `wxUniCharRef` proxy: it cannot be `switch`ed on, and `auto c = s[0]; c = 'x';`
+  **modifies the string**. Use `s[n].GetValue()` or an explicit `int`/`wchar_t` type
+  (`interface/wx/string.h:171-226`).
+- Since 3.3 `wxstr = {"Hello", 2}` is ambiguous (the `string_view` constructor); write
+  `wxString{"Hello", 2}` (`docs/changes.txt:191-194`).
+- Never pass a `wxString`, `c_str()` or `mb_str()` to a real C vararg function (`printf`); use
+  `wxString::Format`/`wxPrintf` or convert explicitly (`interface/wx/string.h:262-300`).
+- `wxUSE_STL` no longer exists; wx 3.3 re-enables implicit `wxString` → `std::string` only through
+  `wxUSE_STD_STRING_CONV_IN_WXSTRING=1` (`docs/changes.txt:163-166`). Orca keeps it 0 and adds
+  `wxNO_UNSAFE_WXSTRING_CONV`; do not enable either conversion, the compile error is the guard.
+
+### Pitfalls
+
+- **Rule:** wrap every UTF-8 `std::string` in `from_u8()` (or pass it to a helper that takes
+  `std::string`) before it reaches a wx API.
+  **Why:** the implicit constructor decodes with CP_ACP on MSW, so a non-ASCII preset name, path or
+  translated `_u8L` string turns into mojibake or `""`; macOS/Linux look correct.
+  ```cpp
+  // Wrong:
+  label->SetLabel(preset.name);
+  wxFileDialog dlg(this, title, app_config->get_last_dir(), "", file_wildcards(FT_3MF), wxFD_OPEN);
+  // Right:
+  label->SetLabel(from_u8(preset.name));
+  wxFileDialog dlg(this, title, from_u8(app_config->get_last_dir()), "", file_wildcards(FT_3MF), wxFD_OPEN);
+  ```
+  Cite: `GUI_App::import_model` (model opener with `from_u8` default dir); `CMakeLists.txt`
+  `wxNO_UNSAFE_WXSTRING_CONV` comment.
+- **Rule:** get UTF-8 out of a `wxString` with `into_u8`/`utf8_string()`.
+  **Why:** `ToStdString()`, `mb_str()` and `c_str()` use `wxConvLibc` and return `""` when a character
+  is not representable in the ANSI code page (`include/wx/string.h:4292-4303`).
+  ```cpp
+  // Wrong:
+  std::string path = dlg.GetPath().ToStdString();
+  // Right:
+  boost::filesystem::path path = into_path(dlg.GetPath());   // or into_u8(dlg.GetPath())
+  ```
+
+## Formatting
+
+**`wxString::Format`/`Printf` contract.** Variadic templates that normalise each argument; positional
+`%2$d %1$d` is supported because `wxUSE_PRINTF_POS_PARAMS` is 1 (`interface/wx/string.h:1533-1546`).
+The specifier/argument type check is a `wxASSERT_MSG` (`include/wx/strvararg.h:336-347`), so at
+debug level 0 nothing checks it: `%d` with `size_t`, `%s` with an `int` or a missing argument is
+silent undefined behaviour. `const char*`, `std::string` and `std::string_view` arguments are
+decoded with `wxConvLibc` (`wxArgNormalizerWchar<const char*>`, `include/wx/strvararg.h:612-624,
+772-781`), so UTF-8 data garbles on MSW exactly as in the table above.
+
+**OrcaSlicer: `format_wxstr` and `GUI::format`** (`src/slic3r/GUI/format.hpp`, on top of
+`Slic3r::format` in `src/libslic3r/format.hpp`) wrap `boost::format`:
+
+| Helper | Returns | Arguments |
+|---|---|---|
+| `format_wxstr(fmt, args...)` | `wxString`, built with `wxString::FromUTF8(result)` | `fmt` as `const char*`, `std::string` (UTF-8) or `wxString`; args of any streamable type |
+| `GUI::format(fmt, args...)` | UTF-8 `std::string` | same |
+| `Slic3r::format(fmt, args...)` (libslic3r) | UTF-8 `std::string` | narrow only |
+
+- Placeholders: boost's `%1%` (preferred: position-independent, checked by `xgettext --boost`),
+  printf-style `%s`/`%d` and positional `%1$s`/`%1$d` all work.
+- `std::string`/`const char*` arguments are inserted as raw bytes, i.e. as UTF-8; pass them directly
+  instead of converting to `wxString` first.
+- `boost::format` throws `boost::io::too_many_args`/`too_few_args` on a placeholder/argument count
+  mismatch, and a stray `%` throws too (Orca's helpers keep boost's default "all errors throw"):
+  `bad_format_string` when it cannot start a directive (`"50%"`, `"5%/s"`), `too_few_args` when it
+  happens to parse as one (`"50% done"` reads `% d`, a space-flag `%d`) [tested]. A literal percent
+  is `%%`. A string that never reaches a formatter but contains `%` needs
+  `// xgettext:no-c-format, no-boost-format` above it, otherwise `msgfmt --check-format` fails
+  (AGENTS.md; e.g. `ConfigManipulation.cpp`).
+- `wxString` arguments [source + tested]: the `cook(const wxString&)` overloads that convert to
+  UTF-8 live in `Slic3r::internal::format` in `slic3r/GUI/format.hpp`, declared after the
+  `format_recursive` template in `libslic3r/format.hpp`. Under two-phase lookup (clang, GCC) a
+  dependent call only finds later overloads through ADL, and `wxString`'s namespace is the global
+  one, so the generic `cook` is chosen and the `wxString` reaches boost through wx's
+  `operator<<(std::ostream&, const wxString&)` → `wxConvWhateverWorks` (C locale first, UTF-8
+  fallback; `src/common/string.cpp:158-170`, `src/common/strconv.cpp:3354-3363`). That is correct
+  while the C locale is UTF-8 (macOS and Linux after `load_language`); MSVC without `/permissive-`
+  finds the overloads. `into_u8(w)` as the argument is exact everywhere.
+
+**Choosing.** New user-visible strings use `format_wxstr(_L("… %1% …"), args)` or
+`GUI::format(_u8L(...), args)`: translators can reorder `%1%`/`%2%`, while plain `%s %d` order is
+fixed (a reordered c-format translation fails `msgfmt --check-format`; never reorder positional
+arguments in a c-format string). `wxString::Format` with printf specifiers is accepted in existing
+code; plural strings often use `%1$d` with `GUI::format` (`NotificationManager.cpp`).
+
+```cpp
+wxString msg = format_wxstr(_L("The file %1% was loaded"), filename);   // filename: UTF-8 std::string
+wxString pl  = wxString::Format(_L_PLURAL("%d object", "%d objects", n), n);  // n: int/unsigned, not size_t
+```
+
+### Numbers
+
+`wxLocale::Init` "changes the application locale … this will affect many of standard C library
+functions such as printf()" (`interface/wx/intl.h:584-590`). Orca deliberately leaves `LC_NUMERIC`
+localised (the `wxSetlocale(LC_NUMERIC, "C")` in `GUI_App::load_language` is commented out), so in
+the GUI thread `wxString::Format("%.2f")`, `wxString::ToDouble` and `std::to_string` use the UI
+language's decimal separator; `wxString::ToCDouble`/`FromCDouble` do not.
+
+- Display: `double_to_string(value, precision)` (`Field.cpp`, `wxNumberFormatter` plus the locale
+  separator from `is_decimal_separator_point()`); parse user input by replacing the other separator
+  with the locale's and then calling the locale-aware `wxString::ToDouble` (`Field::get_value_by_opt_type`
+  style in `Field.cpp`), not `ToCDouble`.
+- Data (config values, G-code, project files, URLs): `CNumericLocalesSetter` (RAII `LC_NUMERIC="C"`),
+  `float_to_string_decimal_point`, `string_to_double_decimal_point` (`libslic3r/LocalesUtils.hpp`).
+  TBB worker threads set `"C"` per thread (`libslic3r/Thread.cpp`); the GUI thread does not.
+
+### Pitfalls
+
+- **Rule:** pass UTF-8 `std::string` values to `format_wxstr`, or `from_u8` them for
+  `wxString::Format`.
+  **Why:** a `std::string` `%s` argument to `wxString::Format` is decoded with CP_ACP on MSW.
+  ```cpp
+  // Wrong:
+  wxString::Format(_L("Preset %s not found"), preset_name);          // std::string
+  // Right:
+  format_wxstr(_L("Preset %1% not found"), preset_name);
+  ```
+  Cite: `include/wx/strvararg.h:772-781`.
+- **Rule:** escape literal percent signs in strings that go through `format_wxstr`/`GUI::format`.
+  **Why:** a stray `%` throws at runtime (`boost::io::too_few_args` here, because `% d` parses as a
+  directive; `bad_format_string` for `"50%"` at the end), in whatever handler builds the message.
+  ```cpp
+  // Wrong:
+  format_wxstr(_L("Progress: 50% done"));
+  // Right:
+  format_wxstr(_L("Progress: 50%% done"));
+  ```
+- **Rule:** use `%zu` or cast for `size_t` in `wxString::Format`.
+  **Why:** the type check is compiled out; `%d` with a 64-bit `size_t` is undefined behaviour that
+  truncates the value or misreads the following arguments, depending on the ABI.
+  ```cpp
+  // Wrong:
+  wxString::Format("%d items", vec.size());
+  // Right:
+  wxString::Format("%d items", static_cast<int>(vec.size()));
+  ```
+
+## Translation
+
+**wx contract** (`interface/wx/translation.h:577-640`): `wxGetTranslation(string, domain = "",
+context = "")` returns the original string when no catalog has it; a non-empty context needs a
+matching `msgctxt` in the catalog; the plural overload returns `string` for `n == 1` and `plural`
+otherwise when no catalog is found; "This function is thread-safe". Since 3.3 it returns
+**`wxString` by value**, not a const reference: "please change the return type of the function to
+wxString" (`docs/changes.txt:139-142`). Orca's `I18N::translate` overloads already return by value;
+keep any new wrapper that way, a `const wxString&` return now dangles.
+
+**OrcaSlicer macros** (`src/slic3r/GUI/I18N.hpp`):
+
+| Macro | Returns | Extracted by xgettext? |
+|---|---|---|
+| `_L(s)` | translated `wxString` | yes |
+| `_u8L(s)` | translated UTF-8 `std::string` | yes |
+| `_L_CONTEXT(s, ctx)` / `_u8L_CONTEXT(s, ctx)` | `msgctxt`-disambiguated `wxString` / `std::string` | yes (`1,2c`) |
+| `_L_PLURAL(s, plural, n)` | plural-aware `wxString` (`n` is `unsigned int`) | yes (`1,2`) |
+| `L(s)` / `L_CONTEXT(s, ctx)` | the literal unchanged: a **marker** for xgettext, translated later at display time | yes |
+| `_(s)`, `_utf8(s)` | same as `_L`/`_u8L` | **no** |
+| `_CHB(s)` | translated `wxScopedCharBuffer` (a temporary, see §Pointer lifetime) | **no** |
+| `_devL(s)` | `wxString(s)`, untranslated and locale-decoded | **no** |
+| `_omitL(s)` | `""` | **no** |
+
+There is no `_CTX` macro and no plural-with-context macro. All overloads decode `const char*` and
+`std::string` input with `wxConvUTF8`, and accept `wxString`/`std::wstring` too, so `_L(var)` works
+for a runtime string, but only finds a translation if that exact string was marked with `L()`
+somewhere. `L_str(std::string)` (`I18N.cpp`) is the function form of `_L` for a UTF-8 string.
+
+libslic3r has its own `src/libslic3r/I18N.hpp`: `L`/`L_CONTEXT` markers (functions returning the
+literal) and `_u8L`, which calls a callback that `GUI_App` installs
+(`Slic3r::I18N::set_translate_callback(libslic3r_translate_callback)`); `#error` guards stop either
+header being included in the other module.
+
+### Extraction
+
+`scripts/run_gettext.sh --full` (and `.bat`) run xgettext with exactly these keywords
+`--keyword=L --keyword=_L --keyword=_u8L --keyword=L_CONTEXT:1,2c --keyword=_L_CONTEXT:1,2c
+--keyword=_u8L_CONTEXT:1,2c --keyword=_L_PLURAL:1,2`, plus `--add-comments=TRN --from-code=UTF-8 --boost`
+(among other flags), over the files listed in `localization/i18n/list.txt`, then `scripts/HintsToPot.py` appends the
+strings of `resources/data/hints.ini`, and `msgfmt --check-format` compiles each catalog into
+`resources/i18n/<lang>/OrcaSlicer.mo`. Consequences:
+
+- A string inside `_()`/`_utf8()`/`_CHB()`/`_devL()` never reaches the `.pot`, so it stays English.
+  `_()` is fine only around a value that was already marked with `L()`.
+- xgettext extracts only string literals (wx states the same for its own `_()`,
+  `interface/wx/translation.h:590-592`); a variable inside `_L()` is translated at runtime only if its
+  value was marked elsewhere.
+- A file missing from `list.txt` is not scanned at all.
+- `// TRN …` immediately above the line carries a translator comment into the catalog
+  (`//TRN To be shown in the main menu View->Top` in `MainFrame.cpp`, `// TRN %1% = file path` in
+  `DownloaderFileGet.cpp`).
+- `--boost` marks `%1%` strings as boost-format, and `msgfmt --check-format` then rejects a
+  translation that drops or changes a placeholder.
+- Only `OrcaSlicer.mo` ships; there is no `wxstd` catalog, so wx's own internal strings (standard
+  dialog buttons it creates, wx error messages) stay English.
+
+### Deferred translation
+
+Static tables, option definitions and enum labels hold `L("…")`-marked literals and are translated
+where they are shown: `file_wildcards_by_type` stores `L("STL files")` titles and `file_wildcards()`
+calls `I18N::translate(data.title_id)`; option labels marked `L_CONTEXT("Top", "Layers")` are shown
+with `_L_CONTEXT(option.label, "Layers")` (`OG_CustomCtrl.cpp`) — only those hard-coded `"Top"`/`"Bottom"`
+labels: every other def string is translated without context, so an `L_CONTEXT` in a def is ignored at
+display. The settings side of this pattern is in `references/orca-settings-ui.md` §Localization of option
+definitions.
+
+### Plurals and contexts
+
+```cpp
+wxString s = wxString::Format(_L_PLURAL("%d object", "%d objects", n), n);
+text += GUI::format(_L_PLURAL("%1$d Object has custom supports.", "%1$d Objects have custom supports.", cnt), cnt);
+wxString top = _L_CONTEXT("Top", "Camera View");   // msgctxt "Camera View" (MainFrame.cpp)
+```
+
+- **Rule:** keep the number placeholder in both forms and give the full sentence to one msgid.
+  **Why:** the catalog's `Plural-Forms` decides which form applies (Russian uses the "singular" form
+  for 21, 31, …; ja/ko/zh have one form), so "One object" without `%d` is wrong for 21 objects;
+  glued fragments (`_L("Delete") + " " + _L("object")`) cannot be reordered or inflected.
+- **Rule:** disambiguate homonyms with a context in the source (`_L_CONTEXT`/`_u8L_CONTEXT`), never
+  by tweaking a translation; the context string must match exactly at the marker and the call site.
+
+## Language switching and the translation lifecycle
+
+**OrcaSlicer design** (`GUI_App::load_language(wxString language, bool initial)`):
+
+1. Initial call only: `wxFileTranslationsLoader::AddCatalogLookupPathPrefix(from_u8(localization_dir()))`
+   (a static wx list), then the language from AppConfig key `language`, else the system language
+   (MSW: `LCIDToLocaleName`), else `wxTranslations::GetBestTranslation(SLIC3R_APP_KEY, wxLANGUAGE_ENGLISH)`.
+   RTL languages are not supported and fall back.
+2. The dictionary language and the C-runtime locale are chosen separately: Slovak uses the Czech
+   dictionary; when the locale is not available the code tries `linux_get_existing_locale_language`
+   (Linux), the base language (`en` from `en_IL`), then a fallback chain (current, system, best,
+   en_US, en_GB) while keeping the requested dictionary. If nothing is available it shows a
+   `wxMessageBox` and, on the initial call, exits.
+3. `m_wxLocale.release()` (deliberate leak: "wxWidgets cause havoc if the current locale is
+   deleted"), `m_wxLocale = make_unique<wxLocale>()`, `m_wxLocale->Init(lang)`,
+   `wxTranslations::Get()->SetLanguage(language_dict)`, `m_wxLocale->AddCatalog(SLIC3R_APP_KEY)`,
+   `m_imgui->set_language(...)`, then rebuilds two caches: `Preset::update_suffix_modified(...)` and
+   `HintDatabase::get_instance().reinit()`.
+
+Changing the language at runtime (`GUI_App::open_preferences` with a pending language) calls
+`load_language(..., false)`, rebuilds the action-registry titles (`m_action_registry.relocalize_builtins()`)
+and then `GUI_App::recreate_GUI`, which destroys and rebuilds `MainFrame` (and drops the cached
+Speed Dial dialog). Everything constructed under the new `MainFrame` re-translates by construction;
+anything that outlives it does not.
+
+**wx caveats.** On macOS "it is impossible to change the application UI locale after launching it …
+using this class doesn't affect the native controls and dialogs", and on macOS 11.0–12.2 changing the
+C locale can break the menus (`interface/wx/intl.h:282-292`): native file dialogs, the app menu and
+standard buttons follow the system language. `wxLocale::IsAvailable` builds a region tag and asks
+`wxUILocale(...).IsSupported()` (`src/common/intl.cpp` `wxLocale::IsAvailable`), which on Unix no
+longer falls back to another region of the same language (`docs/changes.txt:75-79`); keep the
+fallbacks in `load_language`.
+
+- **Rule:** translate at use; never store a translated string in a namespace-scope or function-local
+  `static`, or in a singleton/registry, unless it has a re-localise hook wired into the language
+  switch.
+  **Why:** a namespace-scope static is initialised before `load_language`, so it is English forever;
+  a function-local static captures the language of its first call and survives `recreate_GUI`.
+  ```cpp
+  // Wrong:
+  static const wxString NA_STR = _L("N/A");
+  // Right:
+  m_label->SetLabel(_L("N/A"));       // or keep L("N/A") in the table and translate when shown
+  ```
+  Cite: `ActionRegistry::relocalize_builtins`, `HintDatabase::reinit`, `Preset::update_suffix_modified`
+  are the existing hooks.
+
+## Labels, mnemonics and markup
+
+**Contract** (`interface/wx/control.h:173-195, 380-398`): in `SetLabel` "All "&" characters … indicate
+that the following character is a mnemonic … To insert a literal ampersand character, you need to
+double it"; `SetLabelText` shows the text exactly (implemented as `SetLabel(EscapeMnemonics(text))`,
+`include/wx/control.h:63-67`); `EscapeMnemonics()` is for a label combining program mnemonics with
+user text. Constructor labels are interpreted like `SetLabel` (the ports' `wxStaticText::Create`
+call `SetLabel(label)`) [source]. `SetLabelMarkup` also treats an
+unescaped `&` as a mnemonic, needs `&amp;`/`&lt;` for literal characters, strips the markup where it
+is unsupported, and leaves the label unchanged (returns false) when the string is not well-formed
+(`interface/wx/control.h:200-360`); user text inside markup must be XML-escaped.
+Since 3.3 wxListbook/wxChoicebook also interpret mnemonics in page titles (`docs/changes.txt:128-130`);
+Orca uses neither, but the rule is the same for every book control.
+
+**OrcaSlicer.** `Label` (`Widgets/Label.cpp`) derives from `wxStaticText`; `Label::SetLabel` stores
+the text and goes through `wxStaticText::SetLabel` (or `Wrap` for `LB_AUTO_WRAP`, `SetLabelMarkup` for
+`LB_HYPERLINK` on macOS), so `&` is a mnemonic in every `Label` too. The inherited `SetLabelText`
+escapes and then calls `Label::SetLabel`, so it works for `Label`. Menu labels use `&File`-style
+mnemonics plus `"\t" + accelerator`, and translations must keep the `&`. A plain-text MsgDialog
+message is rendered by a `Label` (mnemonics interpreted); a message with a link, `is_marked_msg`,
+code excerpts or a `<tr>` table goes to `wxHtmlWindow` through `xml_escape` instead (see
+`references/windows-dialogs.md` §MsgDialog family).
+
+- **Rule:** user-supplied text goes through `SetLabelText` or `wxControl::EscapeMnemonics`.
+  **Why:** the `&` disappears and the next character becomes a mnemonic: `PLA & PETG` shows as
+  `PLA  PETG` on every port.
+  ```cpp
+  // Wrong:
+  label->SetLabel(from_u8(preset.name));
+  menu->Append(id, from_u8(printer_name));
+  // Right:
+  label->SetLabelText(from_u8(preset.name));
+  menu->Append(id, wxControl::EscapeMnemonics(from_u8(printer_name)));
+  ```
+
+## Paths and standard locations
+
+**OrcaSlicer path model.** Paths live as `boost::filesystem::path` or UTF-8 `std::string`.
+`OrcaSlicer.cpp` calls `boost::nowide::nowide_filesystem()` at startup, which imbues boost paths with a
+UTF-8 codecvt, so on Windows `boost::filesystem::path(utf8_string)` and `path.string()` are UTF-8.
+`std::filesystem::path` is not imbued: on Windows a narrow `std::string` is read in the ANSI code page,
+so build it from the wide form (`into_path(w).wstring()`) or stay with boost. At the wx boundary use
+`from_path`/`into_path`.
+
+**`wxFileName`** (`interface/wx/filename.h`): `Normalize()` without flags is deprecated
+(`include/wx/filename.h:358-364`) because `wxPATH_NORM_ALL` includes `wxPATH_NORM_ENV_VARS` and
+expands `$VAR`/`%VAR%` inside file names (`interface/wx/filename.h:90-103`); use `MakeAbsolute()` or
+explicit `wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE`. 3.3 adds `IsMSWExtendedLengthPath()` for `\\?\`
+paths "avoiding the 260 character path length restriction" (`interface/wx/filename.h:1040-1051`,
+`docs/changes.txt:551`). `wxFileSystem::FileNameToURL`/`URLToFileName` convert to and from `file:`
+URLs (`interface/wx/filesys.h:96-103, 175-180`).
+
+**`wxStandardPaths`** (`interface/wx/stdpaths.h`): the directories "may or may not exist"
+(`:39`); `GetUserDataDir()` is `~/.appinfo` on Unix, `%APPDATA%\appinfo` on Windows and
+`~/Library/Application Support/appinfo` on macOS, and on Unix ignores `FileLayout_XDG` (`:406-420`);
+`GetUserDir()` always follows XDG on Unix (`:422-433`).
+
+**OrcaSlicer data dir** (`GUI_App::init_app_config`): a `data_dir` folder next to the executable if it
+exists (portable mode), else `GetUserDataDir()` on MSW/macOS, or `$XDG_CONFIG_HOME/OrcaSlicer`
+(default `~/.config/OrcaSlicer`) built by hand on Linux; then the process **chdirs to
+`data_dir()/log`**. Relative paths therefore resolve into the log folder, and anything that changes the
+working directory (`wxFD_CHANGE_DIR`, `wxDD_CHANGE_DIR`, `chdir`) breaks code that relies on it. Use
+absolute paths built from `data_dir()`, `resources_dir()`, `localization_dir()`.
+
+## File and directory dialogs
+
+**Usage:**
+
+```cpp
+wxFileDialog dlg(this, _L("Choose one or more files (3MF/STEP/STL/SVG/OBJ/AMF):"),
+                 from_u8(wxGetApp().app_config->get_last_dir()), wxEmptyString,
+                 file_wildcards(FT_MODEL), wxFD_OPEN | wxFD_MULTIPLE | wxFD_FILE_MUST_EXIST);
+if (dlg.ShowModal() != wxID_OK)
+    return;
+wxArrayString paths;
+dlg.GetPaths(paths);                         // GetPath() returns "" with wxFD_MULTIPLE
+for (const wxString& p : paths)
+    load(into_path(p));
+```
+
+**Contract** (`interface/wx/filedlg.h`):
+
+- `wxFD_OPEN` and `wxFD_SAVE` are exclusive; `wxFD_MULTIPLE`/`wxFD_FILE_MUST_EXIST` are open-only,
+  `wxFD_OVERWRITE_PROMPT` save-only (`:163-200`). Contradictory styles are only asserted
+  (`src/common/fldlgcmn.cpp:776-787`), i.e. ignored silently in Orca.
+- Style bits are reused between classes: `wxPD_APP_MODAL` (0x0002) equals `wxFD_SAVE`
+  (`include/wx/progdlg.h:21`, `include/wx/filedlg.h:45-46`), so a foreign flag can change the dialog
+  type. Pass only `wxFD_*`.
+- `GetPath()`/`GetFilename()` "can't be used with dialogs which have the `wxFD_MULTIPLE` style"
+  (`:343-347, 380-384`); they return `""` there (`docs/changes_32.txt:119-120`). Use
+  `GetPaths()`/`GetFilenames()`.
+- Wildcard format `"Desc (*.a;*.b)|*.a;*.b|Desc2 (*.c)|*.c"` (`:106-115`); the default wildcard is
+  `"*.*"` on MSW and `"*"` elsewhere (`:31-36`).
+- `SetFilename()` in wxGTK has "little effect unless a default directory has previously been set"
+  (`:452-456`).
+- `SetExtraControlCreator()` forces old XP-style dialogs on MSW; `SetCustomizeHook()` is native
+  (`:131-155`). New-style MSW dialogs need a single-threaded COM apartment (`:157-161`).
+- `wxDirDialog`: `wxDD_NEW_DIR_BUTTON` is `0` ("deprecated, on by default now",
+  `interface/wx/dirdlg.h:14`); the "Create new directory" button is shown exactly when
+  `wxDD_DIR_MUST_EXIST` is absent (`interface/wx/dirdlg.h:42-46`); on macOS 10.11+ there is no title
+  bar, the `message` argument is what the user sees (`interface/wx/dirdlg.h:59-62`).
+
+**Platforms:**
+
+| | Behaviour |
+|---|---|
+| MSW | New-style `IFileDialog`: wx calls `SetDefaultExtension` with the selected filter's first extension and no longer calls `AppendExtension` itself (`src/msw/filedlg.cpp:1644-1656, 1738-1740`; `docs/changes.txt:556`). `SetExtraControlCreator` → XP-style dialog. |
+| macOS | Open dialogs show **no filter choice** and apply all wildcards at once unless `wxSystemOptions::SetOption(wxOSX_FILEDIALOG_ALWAYS_SHOW_TYPES, 1)`, and even then non-matching files are only greyed (`interface/wx/filedlg.h:117-128`). Matching compares the lower-cased last path extension (`wxOpenSavePanelDelegate panel:shouldEnableURL:`, `src/osx/cocoa/filedlg.mm:58-88`) [source]: case-insensitive, and a multi-dot pattern such as `*.gcode.3mf` or `*.zip.amf` never matches by itself. `wxFD_OVERWRITE_PROMPT` is always on (`:172-175`); `wxFD_OPEN` always behaves as `wxFD_FILE_MUST_EXIST` (`:184-189`). The save panel replaces the initial file name's extension with the first one in the wildcard (Orca's comment on `file_wildcards`). The native panel runs `runModal` and does not re-raise the parent dialog afterwards (`src/osx/cocoa/filedlg.mm` `ShowModal`); see `references/windows-dialogs.md` for the deferred re-raise. |
+| GTK3 | `GtkFileChooserNative` (portal-capable, e.g. Flatpak) when GTK ≥ 3.20 at runtime and neither `wxFD_PREVIEW` nor an extra control/customize hook is used (`src/gtk/filedlg.cpp:265-274, 437-443`; `src/gtk/dirdlg.cpp:122-130`; `docs/changes.txt:393`). It runs through `gtk_native_dialog_run`: there is no wx window, so size/position calls do nothing (`wxFileDialog::DoSetSize` is empty). Patterns go to `gtk_file_filter_add_pattern` per token and are **case-sensitive** (`src/gtk/filectrl.cpp:169`). The chooser is transient for the parent left after `GetParentForModalDialog`, which replaces a null (or hidden, dying or `wxWS_EX_TRANSIENT`) parent with the active top-level window, else the app's main top window (`src/gtk/filedlg.cpp:206, 223-225`; `src/common/dlgcmn.cpp:180-203` `DoGetParentForDialog`) [source]. `wxFD_PREVIEW` is GTK-only (`interface/wx/filedlg.h:195-197`). |
+| GTK2 (opt-out build) | never uses the native chooser; patterns case-sensitive. |
+
+**OrcaSlicer:**
+
+- `file_wildcards(FileType, custom_extension)` (`GUI_App.cpp`) builds every filter from
+  `file_wildcards_by_type`: translated title, and an upper-case twin of every extension
+  (`*.stl;*.STL`) because GTK patterns are case-sensitive. A `custom_extension` is put first because
+  the macOS save panel substitutes the first extension into the initial file name.
+- Openers to copy: `GUI_App::import_model`, `GUI_App::import_zip` (default dir `from_u8(...)`).
+  Last directories come from `AppConfig::get_last_dir()`/`get_last_output_dir()`; the app stores
+  them itself (`update_config_dir`, `update_last_output_dir`) instead of using `wxFD_CHANGE_DIR`.
+- `Plater::priv::get_export_file` appends the expected extension on `__WXMSW__` when the returned name
+  lacks it and then asks its own overwrite question, because the native overwrite prompt only checked
+  the name the user typed.
+- `CheckboxFileDialog` (`GUI_Utils.hpp/.cpp`) uses `SetExtraControlCreator`, which costs the native
+  dialog on MSW and GTK3; prefer `SetCustomizeHook` for new extra controls.
+
+**Pitfalls:**
+
+- **Rule:** give file and directory dialogs the top-level window they belong to as parent.
+  **Why:** with `nullptr`, wxGTK (`wxFileDialog::Create`, `wxDirDialog::Create`) and wxMSW
+  (`wxFileDialog::ShowModal`) substitute whatever top-level window is active at that moment, else
+  the app's main top window (`wxDialogBase::DoGetParentForDialog`, `src/common/dlgcmn.cpp:180-203`)
+  [source], so the chooser becomes transient for and modal over an arbitrary window (a modeless
+  dialog or web window that happened to be active), or gets no parent when none qualifies. Gizmo
+  code has no `this` window to hand, which is where `nullptr` creeps in.
+  ```cpp
+  // Wrong:
+  wxFileDialog dialog(nullptr, _L("Choose SVG file"), ...);
+  // Right:
+  wxFileDialog dialog(wxGetApp().mainframe, _L("Choose SVG file"), ...);   // or GetTopWindow()
+  ```
+  Cite: `src/gtk/filedlg.cpp` `wxFileDialog::Create` (`GetParentForModalDialog`, then `gtk_parent`).
+- **Rule:** use `wxDD_DEFAULT_STYLE` for directory dialogs; add `wxDD_DIR_MUST_EXIST` only when the
+  user must not create a folder.
+  **Why:** `wxDD_NEW_DIR_BUTTON` is 0, so passing it alone means style 0: no
+  `wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER` (the generic dialog loses its frame). It does not control
+  the new-folder button either: that appears whenever `wxDD_DIR_MUST_EXIST` is absent, so adding
+  `wxDD_DIR_MUST_EXIST` removes it (and restricts the choice to existing folders).
+  ```cpp
+  // Wrong:
+  wxDirDialog dlg(this, msg, path, wxDD_NEW_DIR_BUTTON);
+  // Right:
+  wxDirDialog dlg(this, msg, path, wxDD_DEFAULT_STYLE);   // | wxDD_DIR_MUST_EXIST: existing folders only, no new-folder button
+  ```
+  Cite: `include/wx/dirdlg.h:45-47`; `interface/wx/dirdlg.h:42-46`.
+- **Rule:** never pass `wxFD_CHANGE_DIR`/`wxDD_CHANGE_DIR`.
+  **Why:** Orca's working directory is `data_dir()/log`; the native GTK path even `chdir`s directly
+  (`src/gtk/filedlg.cpp:449-458`).
+
+## Launching the browser, files and programs
+
+**Contract** (`interface/wx/utils.h`):
+
+- `wxLaunchDefaultBrowser(url, flags)`: `wxBROWSER_NEW_WINDOW` is honoured only on Windows; a URL
+  without a scheme is tested as a local file/dir (then prefixed with `file:`), otherwise `http:` is
+  prepended; returns false on failure (`:468-490`). wxGTK tries `gtk_show_uri` and then `xdg-open`
+  (`src/unix/utilsx11.cpp:2674-2737`).
+- `wxLaunchDefaultApplication(document, flags)` opens the file in its associated application; `flags`
+  is unused (`:454-462`).
+- `wxExecute`: `wxEXEC_ASYNC` returns the pid; `wxEXEC_SYNC` "will call wxYield()" and disables all
+  windows unless `wxEXEC_NODISABLE` (`:1196-1212`), so a synchronous call re-enters your handlers;
+  main thread only (`:1250-1252`).
+
+**OrcaSlicer:**
+
+- Links: `wxGetApp().open_browser_with_warning_dialog(url, flags)` is the app-level entry point (it
+  forwards to `wxLaunchDefaultBrowser`, so a direct `wxLaunchDefaultBrowser` call behaves the same).
+- Folders: `desktop_open_any_folder(path)` / `desktop_open_datadir_folder()` (`GUI.cpp`): `explorer`
+  on Windows (`explorer /select,<path>` for `desktop_open_any_folder`), `openFolderForFile`
+  (any folder) or `open` (data dir) on macOS, `xdg-open` on Linux (of the containing folder when
+  `path` is a file) with the AppImage variables (`APPIMAGE`, `APPDIR`, `LD_LIBRARY_PATH`,
+  `LD_PRELOAD`, `UNION_PRELOAD`) removed and `OWD` as the working directory. A bare `wxExecute("xdg-open …")` or
+  `wxLaunchDefaultApplication` from an AppImage passes Orca's bundled libraries to the file manager.
+- Project attachments: `desktop_open_project_attachment` accepts only a regular file inside the
+  project's auxiliary temp folder (`is_absolute_path_within_root`) and asks before opening anything
+  `is_safe_to_open_file_name` (`libslic3r/utils.cpp`) does not allow-list, because the desktop would
+  run a script or executable without a download warning. Reuse it for any file that arrived inside a
+  project or from the network.
+
+## Clipboard
+
+**Contract** (`interface/wx/clipbrd.h`): `Open()` "should be tested"; keep the clipboard open "only
+momentarily" (`:24-29, 145-155`). `SetData` replaces any previously set object, so several formats
+need one composite object; "After this function has been called, the clipboard owns the data"
+(`:157-170`). `Flush()` keeps the data after exit; implemented on MSW and GTK only, on GTK only for
+the CLIPBOARD selection and with a clipboard manager running (`:56-61, 100-115`).
+`UsePrimarySelection(true)` makes every operation fail on platforms without a PRIMARY selection
+(`:172-187`). `wxClipboardLocker` (`include/wx/clipbrd.h:167-191`) opens in its ctor, closes in its
+dtor, and `!lock` tests `IsOpened()`.
+
+**Platforms** [source]:
+
+| | Behaviour |
+|---|---|
+| MSW | `SetData`/`GetData` do not check `Open()` (`src/msw/clipbrd.cpp` `wxClipboard::SetData`), so code that forgets it works here only. `wxTextDataObject::SetData()` size must now include the 2-byte NUL (`docs/changes.txt:62-66`); use `SetText()` or the ctor. |
+| macOS | without `Open()`, `SetData`/`AddData`/`GetData` return false through `wxCHECK_MSG(m_open, …)` without taking the object (`src/osx/carbon/clipbrd.cpp:84-105, 140-147`); a successful write is flushed to the pasteboard immediately (`:110-114`). |
+| GTK | same `wxCHECK_MSG(m_open, …)` early return (`src/gtk/clipbrd.cpp:643-647, 775`). `GetData`/`IsSupported` are asynchronous underneath: `wxClipboardSync` spins `YieldFor(wxEVT_CATEGORY_CLIPBOARD)` until GTK answers and forbids re-entrancy (`src/gtk/clipbrd.cpp:68-92`). PRIMARY selection exists. Under Wayland, Wayland MIME types are advertised next to the X11 atoms (`src/gtk/clipbrd.cpp:655-700`). |
+
+```cpp
+wxClipboardLocker lock;
+if (!lock)
+    return;
+wxTheClipboard->SetData(new wxTextDataObject(text));   // clipboard owns it on success
+```
+
+**OrcaSlicer.** Models: the copy button in `TroubleshootDialog` (`wxClipboardLocker`) and
+`ImGuiWrapper::clipboard_set`/`clipboard_get` (tested `Open()`, UTF-8 via `wxString::FromUTF8`/
+`into_u8`). The 3D scene's copy/paste is an internal clipboard (`Selection::Clipboard`,
+`Selection::copy_to_clipboard`/`paste_from_clipboard`), not the wx one.
+
+- **Rule:** open the clipboard through a checked `wxClipboardLocker` before `SetData`/`GetData`, and
+  test the result.
+  **Why:** on GTK and macOS an unopened clipboard makes `SetData` return false without taking the
+  object (leak, nothing copied) and `GetData` return false (nothing pasted); MSW does not check, so
+  the bug passes Windows testing.
+  ```cpp
+  // Wrong:
+  wxTheClipboard->Open();
+  wxTheClipboard->SetData(new wxTextDataObject(t));
+  wxTheClipboard->Close();
+  // Right:
+  wxClipboardLocker lock;
+  if (lock)
+      wxTheClipboard->SetData(new wxTextDataObject(t));
+  ```
+
+## Drag and drop
+
+**Contract.** `SetDropTarget`: "If the window already has a drop target, it is deleted"
+(`interface/wx/window.h:3651-3657`); the window also deletes its target in its destructor
+(`src/common/wincmn.cpp:515`), so the window owns it. `DragAcceptFiles` "Cannot be used together
+with SetDropTarget() on non-Windows platforms" (`interface/wx/window.h:3659-3672`). The
+`wxDropTarget` destructor deletes its data object and `SetDataObject` deletes the previous one
+(`interface/wx/dnd.h:59-62, 138-146`). Call sequence: `OnEnter` → `OnDragOver`* → `OnDrop` (return
+false to refuse) → `OnData` (`interface/wx/dnd.h:44-45, 75-127`). `wxFileDropTarget::OnDropFiles(x, y,
+filenames)` returns true to accept (`interface/wx/dnd.h:395-422`). `wxDropSource::SetData` "will not
+delete any previously associated data", i.e. the source does not own it (`interface/wx/dnd.h:335-338`).
+`DoDragDrop(flags)` "blocks the program until the user releases the mouse button", and the target
+cannot change the result code the source gets (`docs/doxygen/overviews/dnd.h:44-50, 84-90`).
+`wxDragMove` is reported on MSW only (`interface/wx/dnd.h:26`).
+
+**Platforms** [source]:
+
+| | Behaviour |
+|---|---|
+| MSW | `SetDropTarget` revokes and deletes the old target immediately (`src/msw/window.cpp:1753-1761`). `wxDropTarget::MSWUpdateDragImageOnLeave()` (undocumented, `include/wx/msw/ole/droptgt.h:73`) hides the shell drag image. |
+| GTK | `SetDropTarget` unregisters and deletes immediately (`src/gtk/window.cpp:6605-6616`). `DoDragDrop` returns `wxDragNone` unless a mouse button is down after a mouse event (`src/gtk/dnd.cpp:835-850`), then runs a nested `gtk_main_iteration` loop with `g_blockEventsOnDrag` set (`:906-916`). Under Wayland it also hooks button/motion events because "drag-end" may never arrive (`:945-955`). |
+| macOS | `SetDropTarget` deletes the old target immediately (`src/osx/window_osx.cpp:616-622`). |
+
+**wxDataViewCtrl DnD** (`interface/wx/dataview.h`): `EnableDropTargets` is fully implemented in the
+generic and native macOS versions, wxGTK uses only the first format (`:1376-1386`); `SetDragFlags` is
+honoured only by the generic control (MSW), not native GTK/macOS (`:4010-4024`); `GetDropEffect`
+returns `wxDragNone` on native GTK and macOS (`:4026-4041`); `GetProposedDropIndex` works from
+`ITEM_DROP` everywhere and from `ITEM_DROP_POSSIBLE` except native GTK (`:4053-4064`). The control
+itself is in `references/controls-dataview.md`.
+
+**OrcaSlicer:**
+
+- Model-file drops: `PlaterDropTarget : wxFileDropTarget` (`Plater.cpp`), installed with
+  `q->SetDropTarget(new PlaterDropTarget(...))` (the window takes ownership); `SetDefaultAction(wxDragCopy)`.
+  `OnDropFiles` calls `MSWUpdateDragImageOnLeave()` under `WIN32` before showing UI, raises the main
+  frame, switches to the Prepare tab, routes a single `.svg` to the SVG gizmo (`GLGizmoSVG::create_volume`
+  at the drop point) and otherwise calls `Plater::load_files`. `Preview::set_drop_target(target)` is
+  the helper for putting a target on the preview window.
+- Custom payload: `DragDropPanel.cpp` (filament-group dragging). `ColorDataObject : wxCustomDataObject`
+  with `wxDataFormat("application/customize_format")` and fixed-size POD data; `ColorDropSource` keeps
+  the data object as a member and is constructed on the stack in `DragDropPanel::DoDragDrop`, which
+  `ColorPanel::OnLeftDown` calls (satisfying the GTK button-down rule); `ColorDropTarget` owns its
+  `ColorDataObject` through `SetDataObject`.
+- ObjectList row reordering (`GUI_ObjectList.cpp`): `ObjectList::OnBeginDrag` keeps the real payload in
+  `m_dragged_data`, gives wx a dummy `wxTextDataObject` with non-empty text ("needed for GTK") and
+  `SetDragFlags(wxDrag_DefaultMove)`; `m_prevent_list_events` suppresses the selection events GTK fires
+  because it drops *between* rows where MSW/macOS drop *on* a row.
+
+**Pitfalls:**
+
+- **Rule:** call `wxDropSource::DoDragDrop` synchronously from the mouse-down/drag handler.
+  **Why:** wxGTK refuses (returns `wxDragNone`) without a current button press after a mouse event; a
+  `CallAfter` or timer loses it.
+  ```cpp
+  // Wrong:
+  CallAfter([this] { wxDropSource src(this); src.SetData(m_obj); src.DoDragDrop(); });
+  // Right:
+  void ColorPanel::OnLeftDown(wxMouseEvent&) { m_parent->DoDragDrop(this, ...); }
+  ```
+- **Rule:** never call `SetDropTarget` on a window from inside that window's current target
+  (`OnDrop`/`OnData`/`OnDropFiles`); defer it with `CallAfter`.
+  **Why:** every port deletes the old target immediately, so the callback returns into a freed object.
+
+## Logging: wxLog vs boost log
+
+**Contract** (`docs/doxygen/overviews/log.h`): with the default `wxLogGui`, `wxLogError`/`wxLogWarning`/
+`wxLogMessage` pop up a message box (`:31-38`); messages from other threads are buffered until the main
+thread flushes (`:228-240`); `wxLogNull`/`EnableLogging(false)` affect only the current thread
+(`:242-244`). `wxLog::SetActiveTarget` takes ownership of the new target and the caller must delete the
+returned old one (`interface/wx/log.h:326-340`). `wxLogNull` suppresses **all** messages, not only the
+one you expect (`interface/wx/log.h:1026-1035`).
+
+**OrcaSlicer.** `GUI_App::on_init_inner` first calls `wxLog::SetActiveTarget(new wxBoostLog())`;
+`wxBoostLog::DoLogText` writes every wx message to `BOOST_LOG_TRIVIAL(warning)` as UTF-8, and its
+destructor flushes pending thread messages into itself so they never reach a `wxLogGui`. Release builds
+(`BBL_RELEASE_TO_PUBLIC`) also `wxLog::SetLogLevel(wxLOG_Message)`. `wxLogDebug`/`wxLogTrace` compile to
+nothing at debug level 0 (`include/wx/log.h:62-77`). So **wxLog never shows UI in Orca**, including
+the errors wx itself logs (failed file operations, image loading), which end up only in the log file.
+Use `wxLogNull` around a probing call whose failure wx would log (`OpenGLManager.cpp`), and still check
+the return value.
+
+Write diagnostics with `BOOST_LOG_TRIVIAL(level) << __FUNCTION__ << …` (or
+`boost::format("%1%: …") % …`) and stream UTF-8: `into_u8(w)` or `w.ToUTF8().data()` inside the
+statement. Streaming a `wxString` directly goes through `wxConvWhateverWorks` (locale first;
+`src/common/string.cpp:158-170`) and writes ANSI bytes into the UTF-8 log on MSW.
+
+User-facing errors go through `show_error(parent, msg)` (`GUI.hpp`), which is **asynchronous**: it
+queues an `ErrorDialog` with `wxGetApp().CallAfter` and captures the raw `parent`, so pass a parent that
+outlives the call. `show_info` and `warning_catcher` are synchronous MsgDialogs; the `const char*`/
+`std::string` overloads decode UTF-8. The dialogs themselves are in `references/windows-dialogs.md`
+§MsgDialog family.
+
+- **Rule:** never use `wxLogError`/`wxLogWarning`/`wxLogMessage` to inform the user.
+  **Why:** `wxBoostLog` sends them to the log file only; the user sees nothing.
+  ```cpp
+  // Wrong:
+  wxLogError(_L("Export failed"));
+  // Right:
+  show_error(this, _L("Export failed"));
+  BOOST_LOG_TRIVIAL(error) << __FUNCTION__ << ": export failed: " << into_u8(path);
+  ```
+
+## Native message boxes
+
+**Contract** (`interface/wx/msgdlg.h`): `wxCANCEL` "Must be combined with either wxOK or wxYES_NO"
+(`:30`); `wxYES_NO` without `wxCANCEL` has no close button on MSW (`:31-35`); `wxHELP` is unsupported
+from a non-main thread on wxOSX (`:39-40`); `wxCANCEL_DEFAULT` is ignored on wxOSX (`:44-46`);
+`wxSTAY_ON_TOP` works only on MSW and GTK (`:89-91`). `wxMessageDialog::ShowModal()` returns
+`wxID_OK/wxID_CANCEL/wxID_YES/wxID_NO/wxID_HELP` (`:269-275`), but **`wxMessageBox()` returns
+`wxYES/wxNO/wxCANCEL/wxOK/wxHELP`** (`:308-312`). `wxRichMessageDialog` is native only on MSW and
+generic elsewhere (`interface/wx/richmsgdlg.h:18-23`). On MSW every `TaskDialog`-based dialog
+(`wxMessageBox`, `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`) ignores dark mode
+(`interface/wx/app.h:1436-1440`).
+
+**OrcaSlicer.** UI code uses the MsgDialog family (`MessageDialog`, `RichMessageDialog`,
+`WarningDialog`, `ErrorDialog`, `InfoDialog`; `references/windows-dialogs.md` §MsgDialog family) for
+dark mode, DPI and a consistent look; its `ShowModal()` returns `wxID_*`. Native boxes are for code that
+runs before the GUI exists (`wxMessageBox` in `GUI_App::load_language`, `MessageBoxA` in `OrcaSlicer.cpp`).
+
+- **Rule:** compare each API's result with its own constants.
+  **Why:** `wxYES` (0x2) is not `wxID_YES` (5103); the comparison is always false and the "Yes" branch
+  never runs.
+  ```cpp
+  // Wrong:
+  if (wxMessageBox(msg, title, wxYES_NO) == wxID_YES) ...
+  // Right:
+  if (MessageDialog(this, msg, title, wxYES_NO).ShowModal() == wxID_YES) ...   // or wxMessageBox(...) == wxYES
+  ```
+
+## Settings: AppConfig, not wxConfig
+
+Orca does not use `wxConfig`/`wxFileConfig` (so the 3.3 change of the Unix default location to XDG,
+`docs/changes.txt:25-29`, does not affect it). Settings live in `AppConfig`
+(`src/libslic3r/AppConfig.hpp`), a JSON file `OrcaSlicer.conf` under `data_dir()`
+(`AppConfig::config_path`), reached through `wxGetApp().app_config` (the object map is in
+`references/orca-architecture.md`).
+
+- String-typed API: `get(key)`/`get(section, key)` return `std::string` (UTF-8) and `""` when absent;
+  `set(key, value)`, `set(section, key, value)`, `set_str(section, key, value)`, `set_bool(key, bool)`;
+  `has`, `erase`. `get_bool(section, key)` is `get(section, key) == "true" || get(key) == "1"` (the
+  `"1"` test reads the `app` section). Some keys hold `"true"`/`"false"` (what `set(section, key, bool)`
+  writes), others `"1"`/`"0"`; check how a key is written before testing it.
+- `set` marks the config dirty when the value changes; `GUI_App`'s idle handler saves a dirty config
+  after post-init. Call `app_config->save()` explicitly only when the value must be on disk before control
+  returns to the event loop (before a restart, exit or launching another instance); Preferences rows also
+  `save()` at once by convention (`references/orca-architecture.md` §Preferences).
+- `AppConfig::save()` throws `CriticalException` off the main thread, and nothing in `AppConfig` is
+  locked: read and write it on the main thread only.
+- Values are UTF-8: `from_u8(app_config->get(...))` at the wx boundary, `into_u8(w)` going back.
+
+- **Rule:** pass a `std::string` (or use `set_str`) when setting a string value with a section.
+  **Why:** for `set("app", "key", "value")` the `const char*` → `bool` conversion is a standard
+  conversion and beats the user-defined `std::string` one, so `set(section, key, bool)` wins and stores
+  `"true"` [tested with clang].
+  ```cpp
+  // Wrong:
+  app_config->set("app", "theme", "dark");          // stores "true"
+  // Right:
+  app_config->set_str("app", "theme", "dark");      // or std::string("dark"), or set("theme", "dark")
+  ```
+  Cite: `AppConfig::set` overloads in `AppConfig.hpp`.
+
+## Secrets: wxSecretStore
+
+**Contract** (`interface/wx/secretstore.h`): on Unix it needs libsecret and a running secret service, so
+always check `IsOk(&errmsg)` (`:193-210, 257`); libsecret is no longer required at run time
+(`docs/changes.txt:533`), so a missing library or service shows up only as `IsOk()` false.
+`GetDefault()` "may show a dialog to the user under some platforms, so it can take an arbitrarily long
+time to return" (`:243-246`). One username per service (`:260-268`).
+
+**OrcaSlicer** (`OrcaCloudServiceAgent`): AppConfig `SETTING_USE_ENCRYPTED_TOKEN_FILE` selects either an
+AES-GCM encrypted token file in the data dir or the system store; `secret_stored` records whether this
+process read or wrote a secret, and `clear_user_secret` touches the store only then (or on an explicit
+all-backends logout).
+
+- **Rule:** never call `wxSecretStore::GetDefault()`, `Load`, `Save` or `Delete` from a timer, poll or
+  repeated UI path; touch the store on explicit login/logout and cache the state.
+  **Why:** each call is a blocking keychain/D-Bus round trip on the UI thread; an unresponsive keychain
+  froze the UI for 25 s per poll, and the delete also removed a login another instance had just saved.
+  Cite: 1a5bc8982d (`OrcaCloudServiceAgent::clear_user_secret`).
+
+## Single instance
+
+**Contract** (`interface/wx/snglinst.h`): `wxSingleInstanceChecker::Create(name, path)`: `name` "is used
+as the mutex name under Win32 and the lock file name under Unix", and `path` "is ignored under Win32"
+(`:97-103`); the default name includes the user id, so different users may run concurrently (`:49-53`).
+
+**OrcaSlicer** (`instance_check(argc, argv, app_config_single_instance)`, `InstanceCheck.cpp`), run at
+startup from `GUI_Init.cpp` before the GUI: the executable path (the AppImage file on Linux) is hashed into a lock name.
+Windows checks it with a `wxSingleInstanceChecker` (`GUI_App::init_single_instance_checker`, name
+`<hash>.lock`); macOS and Linux use Orca's own lock file `data_dir()/cache/<hash>.lock`
+(`instance_check_internal::get_lock`). When another instance holds the lock and single-instance mode
+applies (command line, else AppConfig), the command line is forwarded and this process exits: Windows
+`WM_COPYDATA` to the other instance's window, macOS `NSDistributedNotificationCenter`
+(`InstanceCheckMac.mm`, `send_message_mac`), Linux D-Bus. No wxIPC is involved. The receiving
+`OtherInstanceMessageHandler` turns messages into `EVT_LOAD_MODEL_OTHER_INSTANCE`,
+`EVT_START_DOWNLOAD_OTHER_INSTANCE` and `EVT_INSTANCE_GO_TO_FRONT` for the main frame. A new kind of
+cross-instance request extends this message path on all three transports rather than adding a second
+checker or a wxIPC server.

.claude/skills/orca-wxwidgets/references/windows-dialogs.md

@@ -0,0 +1,991 @@
+# Windows, dialogs and window lifetime
+
+How windows are created, parented, closed and destroyed; how to tell whether a window is still
+alive; how top-level windows show, raise and persist; how modal and modeless dialogs work on each
+port; what Orca's `DPIDialog`/`DPIFrame` add; the Orca dialog recipe; and the `MsgDialog` family.
+Read it before writing or reviewing any dialog, frame, close handler, `Destroy()`/`delete`, or code
+that keeps a pointer to a window across an event, a `CallAfter` or a modal loop.
+
+wx cites are relative to the pinned wx 3.3.2 tree (`find deps -maxdepth 5 -type d -path
+'*dep_wxWidgets-prefix/src/dep_wxWidgets'`). wx is built with `wxBUILD_DEBUG_LEVEL=0` and
+`libslic3r_gui` with `wxDEBUG_LEVEL=0`: every wx assert quoted below is compiled out, so misuse
+fails silently (dropped call, stuck loop, freed memory), never with an assert dialog. "GTK" below
+means wxGTK as Orca builds it on Linux: GTK3 by default (X11 or Wayland); GTK2 is only an opt-out.
+
+Contents: [Rules](#rules) · [1 Creating and parenting](#1-creating-and-parenting-windows) ·
+[2 Destroy, delete, Close](#2-destroying-windows-destroy-delete-close-and-the-close-event) ·
+[3 Liveness](#3-liveness-is-this-window-still-alive) ·
+[4 Top-level windows](#4-top-level-windows-show-raise-enable-state-geometry) ·
+[5 Window styles](#5-window-styles) · [6 Dialogs and modality](#6-dialogs-and-modality) ·
+[7 DPIDialog and DPIFrame](#7-dpidialog-and-dpiframe) ·
+[8 The Orca dialog recipe](#8-the-orca-dialog-recipe) ·
+[9 MsgDialog family](#9-message-boxes-the-msgdialog-family) ·
+[10 Overlay frames](#10-overlay-frames-basetransparentdpiframe)
+
+## Rules
+
+1. Free heap-allocated windows with `Destroy()`, never `delete`; a modal dialog on the stack is freed by its scope and must never be `Destroy()`ed. §2
+2. Never `Destroy()` a child window (or an ancestor of it) from inside that child's own event handler: child `Destroy()` is a synchronous `delete this`. Defer with `wxTheApp->ScheduleForDestruction(w)` or a guarded `CallAfter`. §2
+3. A close handler either vetoes or destroys/ends the window; prompts and vetoes only when `CanVeto()`; when `!CanVeto()` it must not veto. §2
+4. Do irreversible teardown in a close handler only once every veto is decided — the default top-level handler still vetoes a vetoable close while any modal dialog is open. §2
+5. Give every dialog and frame a live top-level parent (`parent ? parent : wxGetApp().mainframe`); a parentless window that only hides on close keeps the process alive. §1, §2
+6. Never construct a window to reach computation; make the logic `static` or free. §1
+7. To ask "is this top-level window still alive", check `wxTheApp->IsScheduledForDestruction(w)` as well as `IsBeingDeleted()`; `wxWeakRef` nulls only at the very end of destruction; cross-thread code uses a `std::shared_ptr<std::atomic<bool>>` alive flag. Re-check after every nested event loop. §3
+8. A `wxEVT_DESTROY` handler on a parent fires for every descendant: compare `GetEventObject()` and `Skip()`. For a top-level window it runs after the derived destructor — do derived cleanup in the destructor. §3
+9. Accessors reachable from teardown-time events return `nullptr` instead of dereferencing a pimpl or child; the real fix is still to stop the events first. §3
+10. Bring a top-level window forward with `if (!w->IsShown()) w->Show(); w->Raise();` — `Raise()` never shows, and a redundant `Show()` is not inert on GTK3. §4
+11. On macOS, after a native modal (file/dir dialog, native message box) or a generic progress dialog opened from a secondary top-level window, re-raise that window with a deferred, liveness-guarded `Raise()`. §4
+12. Remove style bits with `& ~flag`, never `!flag`. §5
+13. Always pass the style to a `DPIDialog`: the `DPIAware` default is `wxDEFAULT_FRAME_STYLE` (resizable, min/max boxes). §5, §7
+14. A `wxFRAME_FLOAT_ON_PARENT` frame takes a non-null top-level parent (parent to `mainframe`, not to a panel). §5
+15. End a modal dialog with `EndModal(wxID_*)` (or `EndDialog` from inside the class); never with `Hide()`, `Show(false)` or `Destroy()` while its loop runs. A heap modal is `Destroy()`ed after `EndModal()` — normally by the caller once `ShowModal()` returns. §6
+16. Return codes are `wxID_*` ids, never the `wxOK/wxCANCEL/wxYES/wxNO/wxCLOSE` style bits (the `MsgDialog` "Go to" button's `wxFORWARD` is the one deliberate exception). §6, §9
+17. Nested modal dialogs end innermost first; `DPIDialog::EndModal` refuses (logs, leaves the dialog open) on a dialog that is not the innermost `DPIDialog`. §6, §7
+18. Never call `EndModal()` on a modeless dialog; use `Hide()`, `Close()`, `Destroy()`, or `EndDialog(rc)` inside the class. §6
+19. Never show a modal dialog directly from a mouse-button or motion handler; defer with `CallAfter`. §6
+20. Run cancel cleanup on every close path: ESC and the title-bar close box go through `Close()` and `wxID_CANCEL`, never through an Orca `Button`'s handler. §6, §8
+21. Dialogs derive `DPIDialog`, implement `on_dpi_changed`, call `CenterOnParent()` after fitting, and call `wxGetApp().UpdateDlgDarkUI(this)` last; an override of `ShowModal()` calls `DPIDialog::ShowModal()`. §7, §8
+22. The bottom row is `DialogButtons` with untranslated labels; bind every button whose default wx handling is not what you want — Yes/No/Confirm/custom buttons never close the dialog by themselves. §8
+23. Messages to the user go through the `MsgDialog` family (`MessageDialog`, `RichMessageDialog`, `WarningDialog`, `ErrorDialog`, `InfoDialog`, `show_error`/`show_info`), never `wxMessageBox`/`wxMessageDialog` once the GUI exists; treat `wxID_CANCEL` (ESC/close box) as "no". §9
+24. `show_error` is asynchronous and captures its parent pointer; pass a long-lived parent or `nullptr`. §9
+
+---
+
+## 1 Creating and parenting windows
+
+**Contract.**
+- Child windows are created shown; top-level windows (frames, dialogs) are created hidden "to allow
+  you to create their contents without flicker" (`interface/wx/window.h:3140-3158`).
+- "Child windows are deleted from within the parent destructor. This includes any children that are
+  themselves frames or dialogs, so you may wish to close these child frame or dialog windows explicitly
+  from within the parent close handler" (`docs/doxygen/overviews/windowdeletion.h:96-100`).
+- `wxDialog` with a NULL parent "will be owned by the application's top window, if any. Use
+  `wxDIALOG_NO_PARENT` style to really make dialog not owned by any window" (`interface/wx/dialog.h:166-172`).
+  The style doc adds: orphan dialogs are "not recommended for modal dialogs" (`interface/wx/dialog.h:122-126`).
+- **[source]** Only the *native* owner is substituted; `GetParent()` stays NULL. Owner resolution
+  (`wxDialogBase::DoGetParentForDialog`, `src/common/dlgcmn.cpp:180-204`): the given parent's
+  top-level parent → the active window's top-level parent → `wxApp::GetMainTopWindow()`, each
+  rejected if it is pending delete, being deleted, has `wxWS_EX_TRANSIENT`, or — for modal use — is
+  not `IsShownOnScreen()` (`CheckIfCanBeUsedAsParent`, `src/common/dlgcmn.cpp:130-178`).
+
+**Two-step creation.** "the underlying window must be created exactly once… if you use the default
+constructor… you *must* call Create() before using the window and if you use the non-default
+constructor, you can *not* call Create()" (`interface/wx/window.h:411-417`). Methods may be called
+between the C++ constructor and `Create()` — `Hide()` to build invisibly, `Enable(false)`,
+`SetExtraStyle()` for create-time extra styles (`interface/wx/window.h:419-428, 3120-3126`; `interface/wx/dialog.h:127-133`).
+```cpp
+auto* panel = new wxPanel();          // C++ object only
+panel->Hide();                        // legal before Create
+panel->Create(parent, wxID_ANY);      // native window, still hidden
+/* build children */  panel->Show();
+```
+**[source]** `Destroy()` on a never-created window skips `wxEVT_DESTROY` (`src/common/wincmn.cpp:559-573`),
+and a never-created top-level window is deleted immediately (`src/common/toplvcmn.cpp:102-112`; not on
+macOS, whose `Destroy()` always defers, §2 table).
+Orca's widgets (`StaticBox`, `Button`, `TextInput`, `SpinInput`) follow the layering:
+default constructor + `Create(...)`, the convenience constructor delegates to both, and each
+`Create` calls its base `Create` first, then attaches `state_handler`. `ComboBox` has only the
+convenience constructor, which default-constructs its `TextInput` base and calls `TextInput::Create`.
+Subclasses keep that layering.
+
+**Reparent.** `Reparent(newParent)` moves the window between children lists (and between
+`wxTopLevelWindows` and a parent); "you need to explicitly call wxNotebook::RemovePage() before
+reparenting a notebook page" (`interface/wx/window.h:730-742`). **[source]** It does not touch
+sizers (`src/common/wincmn.cpp:1339-1377`); GTK hides the widget and re-shows it on idle if the new parent is
+visible (`src/gtk/window.cpp:5195-5230`); MSW just calls `::SetParent`.
+
+**Platforms.**
+- MSW fixes a dialog's native owner at `Create` time (`wxTopLevelWindowMSW::CreateDialog` →
+  `GetParentForModalDialog`, `src/msw/toplevel.cpp:337-352`). A dialog created while its parent is
+  not on screen (e.g. inside the parent frame's constructor) is owned by the active window, the main
+  top window, or nothing — wrong z-order and taskbar grouping.
+- GTK sets `transient_for` for modal dialogs in `ShowModal()` (`src/gtk/dialog.cpp:139-144`), and for
+  dialogs/float-on-parent/stay-on-top frames with a top-level parent in `Create`
+  (`src/gtk/toplevel.cpp:774-782`).
+- Wayland: the compositor places top-level windows (see §4); dialog placement comes from
+  `transient_for`, so a real parent is the only positioning control there is.
+
+**OrcaSlicer.** Dialogs take `parent ? parent : wxGetApp().mainframe` — never orphan a dialog (the
+`MsgDialog` constructor does this substitution itself). Passing a child panel as parent is legal:
+the dialog dies with that panel (§2) and `CenterOnParent()` centres on the panel's screen rect
+(`wxTopLevelWindowBase::DoCentre`, `src/common/toplvcmn.cpp:239-279`); with no wx parent it centres on the display.
+
+**Pitfalls.**
+- **Rule:** Never construct a window — especially one hosting a `wxWebView` — just to call one of
+  its computation methods; make the computation `static` or a free function.
+  **Why:** window construction has heavy native side effects (native handles, webview processes,
+  event bindings). `is_flush_config_modified()` built a full `WipingDialog` (with a WebView) only to
+  call `CalcFlushingVolumes()`; it runs on the UI-rebuild path (`Sidebar::msw_rescale`,
+  `Sidebar::sys_color_changed`), and on macOS the language switch froze the app.
+  ```cpp
+  // Wrong
+  WipingDialog dlg(wxGetApp().mainframe, extra_flush_volumes);
+  auto m = dlg.CalcFlushingVolumes(i);
+  // Right
+  static VolumeMatrix CalcFlushingVolumes(int extruder_id);   // no window needed
+  auto m = WipingDialog::CalcFlushingVolumes(i);
+  ```
+  Cite: 80f4a7a40f (`WipingDialog::CalcFlushingVolumes`/`CalcFlushingVolume` in `src/slic3r/GUI/WipeTowerDialog.hpp`).
+- **Rule:** Create a dialog lazily, after its parent is on screen, when MSW ownership matters.
+  **Why:** the native owner is chosen at `Create` and a hidden parent is rejected (above).
+- **Rule:** `Reparent()` does not move sizer membership.
+  ```cpp
+  // Wrong: w->Reparent(p);
+  // Right:
+  old_sizer->Detach(w); w->Reparent(p); new_sizer->Add(w, 0, wxEXPAND); p->Layout();
+  ```
+- **Rule:** Call `Create()` exactly once; never on an object built with the non-default constructor.
+
+---
+
+## 2 Destroying windows: Destroy, delete, Close and the close event
+
+**Contract.**
+- `Destroy()`: "Use this function instead of the delete operator, since different window classes can
+  be destroyed differently. Frames and dialogs are not destroyed immediately when this function is
+  called -- they are added to a list of windows to be deleted on idle time, when all the window's
+  events have been processed. This prevents problems with events being sent to non-existent windows."
+  Returns true "if the window has either been successfully deleted, or it has been added to the list of
+  windows pending real deletion" (`interface/wx/window.h:3607-3618`).
+- Destructor: "Deletes all sub-windows, then deletes itself. Instead of using the delete operator
+  explicitly, you should normally use Destroy() so that wxWidgets can delete a window only when it is
+  safe to do so, in idle time" (`interface/wx/window.h:389-394`). `DestroyChildren()` is called automatically by the
+  destructor (`interface/wx/window.h:626`).
+- "Windows with parents, such as controls, don't have delayed destruction… For consistency, continue
+  to use the wxWindow::Destroy function instead of the delete operator when deleting these kinds of
+  windows explicitly" (`docs/doxygen/overviews/windowdeletion.h:103-109`).
+- `Close(force)` "simply generates a wxCloseEvent whose handler usually tries to close the window. It
+  doesn't close the window itself"; `force=true` means the handler cannot veto; returns "true if the
+  event was handled and not vetoed" — a handler that hides instead of destroying still makes it return
+  true. "Calling Close does not guarantee that the window will be destroyed… To guarantee that the
+  window will be destroyed, call wxWindow::Destroy instead" (`interface/wx/window.h:3574-3605`).
+- Close handler: "If [CanVeto()] is false, you *must* destroy the window using wxWindow::Destroy… If you
+  don't destroy the window, you should call wxCloseEvent::Veto" (`interface/wx/event.h:4708-4717`).
+  "The wxCloseEvent handler should only call wxWindow::Destroy to delete the window, and not use the
+  delete operator" (`docs/doxygen/overviews/windowdeletion.h:38-42`).
+- Defaults (`docs/doxygen/overviews/windowdeletion.h:63-73`): wxDialog's close handler simulates `wxID_CANCEL`; the cancel
+  handler hides a modeless dialog or `EndModal(wxID_CANCEL)`s a modal one — "the dialog *is not*
+  destroyed (it might have been created on the stack)". wxFrame's default close handler calls `Destroy()`.
+  **[source]** The top-level default (`wxTopLevelWindowBase::OnCloseWindow`, `src/common/toplvcmn.cpp:535-546`)
+  **vetoes** a vetoable close while `wxModalDialogHook::GetOpenCount() > 0` (any app-modal wx or native
+  dialog open), otherwise calls `Destroy()`.
+- Deleting from inside a handler: "it may be unsafe for an event handler to delete the object which
+  generated the event because more events may be still pending for the same object. In this case the
+  handler may call ScheduleForDestruction() instead" (`interface/wx/app.h:191-212`); without an event
+  loop it deletes immediately.
+
+**When does `Destroy()` actually free the window?** **[source]**
+
+| Window | `Destroy()` does | Cite |
+|---|---|---|
+| Child (control, panel) | sends `wxEVT_DESTROY`, then `delete this` **synchronously**; the window detaches from its containing sizer in `~wxWindowBase` | `src/common/wincmn.cpp:559-573` |
+| Top-level, normal case | appends to `wxPendingDelete`, hides unless it is the last visible top-level window; deleted by `DeletePendingObjects()` at the next idle — which also runs inside full yields and modal loops (`wxYield`, `ShowModal`), not inside a masked `YieldFor` (progress-dialog `Update`) | `src/common/toplvcmn.cpp:102-142`; `src/common/appbase.cpp:643-662` |
+| Top-level, parent already being deleted, or never created (not macOS) | deleted immediately | `src/common/toplvcmn.cpp:102-112` |
+| Top-level, macOS | always deferred and always `Hide()`n | `src/osx/toplevel_osx.cpp:96-105` |
+| Top-level, MSW | base behaviour plus `wxWakeUpIdle()` so iconized windows still get deleted | `src/msw/toplevel.cpp:771-784` |
+| Any child of a dying parent, top-level children included | `DestroyChildren` calls the non-virtual `wxWindowBase::Destroy()`: deleted **immediately**, not queued | `src/common/wincmn.cpp:586-607` |
+| `wxPopupTransientWindow` | deferred to idle (not hidden); a second `Destroy()` fails a `wxCHECK` — see `references/popups-menus.md` | `src/common/popupcmn.cpp` `wxPopupTransientWindowBase::Destroy` |
+
+**Close-handler shapes** (pick one per window, never mix; `confirm_discard`/`cleanup` stand for your code):
+```cpp
+// destroy-on-close (a frame, or a modeless dialog the user owns)
+Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent& e) {
+    if (e.CanVeto() && !confirm_discard()) { e.Veto(); return; }
+    cleanup();             // members still alive here
+    e.Skip();              // frame: default Destroy() (vetoed while a modal is open, Rule 4)
+    // modeless dialog: call Destroy() instead -- its default only EndDialog(wxID_CANCEL)s = hides it
+});
+// hide-on-close (a reusable window someone else owns) — TextureProjectorFrame's shape
+Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent& e) {
+    if (e.CanVeto()) { e.Veto(); Hide(); } else e.Skip();   // a forced close must still destroy
+});
+// usable both modal and modeless — WebDialog::on_close_window's shape
+void on_close(wxCloseEvent&) { if (IsModal()) EndModal(wxID_CANCEL); else Destroy(); }
+```
+A dialog's `e.Skip()` reaches `wxDialogBase::OnCloseWindow`, which **ends** the dialog
+(`EndDialog(wxID_CANCEL)` = `EndModal` or `Hide`) but never destroys it: a modeless dialog closed
+with the close box is only hidden (`src/common/dlgcmn.cpp:525-559`).
+
+**Application exit.** The app exits when the last top-level window is destroyed
+(`docs/doxygen/overviews/windowdeletion.h:89-93`; `SetExitOnFrameDelete(false)` disables it, `interface/wx/app.h:1195-1207`). "By default,
+the application stays alive as long as there are any open top level windows" — hidden ones count;
+override `ShouldPreventAppExit()` to return false for unimportant windows (`interface/wx/toplevel.h:650-657`).
+**[source]** `IsLastBeforeExit` runs from `~wxTopLevelWindowBase` (`src/common/toplvcmn.cpp:93-97, 144-189`);
+`GetTopWindow()` skips windows pending delete (`src/common/appcmn.cpp:185-208`).
+
+**OrcaSlicer — shapes to follow.**
+- *Modeless singleton owned by `GUI_App`* (`GUI_App::open_terminal_dialog`, `GUI_App::open_speed_dial`):
+  ```cpp
+  if (!m_dlg) {
+      m_dlg = new TerminalDialog(mainframe, wxID_ANY, _L("Plugin Terminal"));
+      m_dlg->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent& e) {
+          if (e.GetEventObject() == m_dlg) m_dlg = nullptr;   // the event also arrives from children
+          e.Skip();
+      });
+  }
+  if (!m_dlg->IsShown()) m_dlg->Show();
+  m_dlg->Raise();
+  ```
+  These dialogs bind no close handler, so the close box only hides them (the wx default for a modeless
+  dialog, below) and the reopen path re-shows the same window; they die with their parent `mainframe`
+  (or an explicit `Destroy()`, as `GUI_App::recreate_GUI` does for the speed dial), and the
+  `wxEVT_DESTROY` reset clears the pointer then. A reset that does not compare `GetEventObject()` clears
+  the pointer when any child of the dialog is destroyed. `open_terminal_dialog` also wraps all of this in
+  `CallAfter` because it is reached from a webview script message (§6).
+- *Dual-mode dialog* (`WebDialog`): close handler `IsModal() ? EndModal(wxID_CANCEL) : Destroy()`;
+  forced teardown (`WebDialog::destroy_silently`) calls `EndModal` first, then `Destroy()`, because
+  destroying a modal "can leave ShowModal() running". Registry cleanup runs in `~WebDialog`, explicitly
+  not in a `wxEVT_DESTROY` handler (comment there: the event comes from the base `~wxDialog`, after the
+  members died).
+- *Hide-on-close reusable frame* (`TextureProjectorFrame`): veto + `Hide()` when `CanVeto()`, else
+  `Skip()`. The owner (the texture gizmo) holds the pointer; it is parented to `mainframe` because
+  `wxFRAME_FLOAT_ON_PARENT` needs a real top-level parent.
+- *Pseudo-modal modeless dialog* (`ParamsDialog`): see §6 "Modality helpers".
+- *By-value top-level member*: `MainFrame::m_settings_dialog` is a `SettingsDialog` (a `DPIDialog`)
+  stored by value with a NULL parent; its close handler only `Hide()`s. Such a window must never be
+  `Destroy()`ed or `delete`d — it dies in member destruction, before the frame's base destructors.
+  Prefer a heap child for new code.
+- *Main-frame replacement* (`GUI_App::recreate_GUI`): `mainframe->shutdown()`, create the new
+  `MainFrame`, `SetTopWindow(new_frame)`, then `old->Destroy()` — new frame first, so wx never sees
+  "last top-level window gone" and exits.
+- *Main-frame close* (`MainFrame` constructor's `wxEVT_CLOSE_WINDOW` lambda): every prompt and veto is
+  gated by `event.CanVeto()` (gizmo editing, `Plater::close_with_confirm`, print-host queue); then
+  `set_closing(true)`, `m_plater->reset()`, `shutdown()`, `event.Skip()` → default `Destroy()`. Cmd+Q on
+  macOS posts a vetoable close (`wxPostEvent(this, wxCloseEvent(wxEVT_CLOSE_WINDOW))`); updater paths use
+  `Close(true)` to force. Its teardown runs before `Skip()`, so a vetoable close that arrives while a
+  modal is open (the `wxEVT_QUERY_END_SESSION` handler in `GUI_App::on_init_inner` sends exactly that) is
+  vetoed by the default handler after teardown — the hazard of Rule 4; don't copy that ordering into new
+  handlers. Sequence detail: `references/orca-architecture.md`.
+- *Lifetime-tied cleanup*: `GUI_App::recreate_GUI` attaches a `wxClientData` subclass with
+  `SetClientObject`; its destructor runs in `~wxEvtHandler`, after all children are gone.
+- *Lazily built window* (`Lazy<T>` / `LazyInstance<T>` in `Lazy.hpp`, e.g. `MainFrame::m_diff_dialog`, a
+  `Lazy<DiffPresetDialog>`): the holder builds the window on demand or at idle, but the window's parent
+  owns it; code that only needs an already-built instance asks `T::if_built()` instead of forcing a
+  build. Design: `docs/HLSD/deferred-page-construction.md`, `references/orca-architecture.md`.
+
+**Pitfalls.**
+- **Rule:** Destroy heap-allocated top-level windows with `Destroy()`, never `delete`; stack-allocated
+  modal dialogs are destroyed by scope.
+  **Why:** `delete` skips the pending-delete queue, and for a top-level window `wxEVT_DESTROY` is then
+  sent only from the base destructor. `Destroy()` *delays* deletion; it does not stop events: queued
+  events and `CallAfter`s of a window sitting in `wxPendingDelete` still run (§3), so deferred code
+  still needs liveness checks.
+  ```cpp
+  // Wrong: auto* dlg = new MyDialog(this); dlg->ShowModal(); delete dlg;
+  // Right: auto* dlg = new MyDialog(this); dlg->ShowModal(); dlg->Destroy();
+  // Right: MyDialog dlg(this); dlg.ShowModal();
+  ```
+  Cite: 0a0d59b76b (`detail::run_off_thread_with_progress` in `src/slic3r/GUI/PluginsDialog.hpp`: the
+  worker body in `try/catch`, then one main-thread `CallAfter` that does `timer->Stop(); delete timer;`
+  and `progress->Destroy()` only while the host's alive flag is set, or when the caller passed no flag —
+  the progress dialog is a child of the host and has already died with it otherwise, §2 table). Older code that `delete`s a dialog
+  after `ShowModal()` is legacy; don't extend it.
+- **Rule:** Never `Destroy()` a control (or its ancestor panel) from inside that control's own handler.
+  ```cpp
+  // Wrong: m_btn->Bind(wxEVT_BUTTON, [this](auto&) { m_panel->Destroy(); });  // m_btn is inside m_panel
+  // Right:
+  m_btn->Bind(wxEVT_BUTTON, [this](auto&) { wxTheApp->ScheduleForDestruction(m_panel); m_panel = nullptr; });
+  ```
+  **Why:** child `Destroy()` deletes synchronously; the dispatcher then returns into freed memory.
+- **Rule:** A close handler that neither destroys nor vetoes, or that vetoes without checking
+  `CanVeto()`, is wrong.
+  **Why:** `Close(true)`, session end and the default top-level handler rely on a non-vetoable close
+  destroying the window; a hide-only handler leaks the window, and a parentless leaked window keeps the
+  process alive after the main frame is gone. Parent it to `mainframe`, `Destroy()` it, or override
+  `ShouldPreventAppExit()`.
+- **Rule:** Do irreversible teardown only when the close is certain.
+  **Why:** a handler that tears down and then `Skip()`s can still be vetoed by
+  `wxTopLevelWindowBase::OnCloseWindow` when the close is vetoable and any modal dialog is open (for
+  example a vetoable close sent while a dialog is up, as the `wxEVT_QUERY_END_SESSION` path does): the
+  window survives, half torn down.
+  ```cpp
+  // Wrong
+  Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent& e) { shutdown(); e.Skip(); });
+  // Right
+  Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent& e) {
+      if (e.CanVeto() && wxModalDialogHook::GetOpenCount() > 0) { e.Veto(); return; }
+      shutdown(); e.Skip();
+  });
+  ```
+- **Rule:** A `wxTimer` must not outlive the handler that receives its events — make it a member
+  (`wxTimer m_timer{this}`) or delete it before the owner dies. Detail in `references/threads-timers-app.md` §wxTimer.
+
+---
+
+## 3 Liveness: is this window still alive?
+
+**`IsBeingDeleted()`.** Doc: true "if this window, or one of its parent windows, is scheduled for
+destruction and can be useful to avoid manipulating it as it's usually useless to do something with a
+window which is at the point of disappearing anyhow" (`interface/wx/window.h:3620-3633`). **[source]** Wrong for top-level windows: the flag is
+set only by `SendDestroyEvent()`, i.e. when deletion actually starts (`src/common/wincmn.cpp:541-557`);
+`wxTopLevelWindowBase::Destroy()` only queues and hides, so **after `tlw->Destroy()` returns,
+`tlw->IsBeingDeleted()` is false until idle**. The parent walk also stops at a top-level window
+(`m_isBeingDeleted || (!IsTopLevel() && m_parent->IsBeingDeleted())`, `src/common/wincmn.cpp:535-539`): a dialog
+does not report its parent frame's deletion.
+
+**`wxApp::IsScheduledForDestruction(obj)` / `ScheduleForDestruction(obj)`** (`interface/wx/app.h:191-221`):
+the first answers "has `Destroy()` (or `ScheduleForDestruction`) already been called"; both share
+`wxPendingDelete` (`src/common/appbase.cpp:624-641`). `ScheduleForDestruction` defers deletion of *any*
+`wxObject`, children included; **[source]** it deletes with plain `delete` at idle (`src/common/appbase.cpp:643-662`).
+
+| After… | `IsBeingDeleted()` | `IsScheduledForDestruction()` | `wxWeakRef` |
+|---|---|---|---|
+| `child->Destroy()` returned | object gone | object gone | null |
+| `tlw->Destroy()` returned, before idle | **false** | true | **non-null** |
+| inside `wxEVT_DESTROY` handlers and the wx base destructors | true | false (already removed) | **non-null** until `~wxTrackable` |
+| inside a top-level window's own derived destructor (deleted at idle or by `delete`) | **false** — `SendDestroyEvent()` runs later, in `~wxFrameBase` or the port's top-level/dialog destructor (`src/common/framecmn.cpp:200`, `src/msw/toplevel.cpp:522`, `src/gtk/toplevel.cpp:975`, `src/osx/dialog_osx.cpp:90`) | false | non-null |
+
+**`wxWeakRef<T>`** auto-resets "when the object pointed is destroyed"; works for `wxEvtHandler`/`wxWindow`
+(`interface/wx/weakref.h:40-99`). **[source]** The reset happens in `~wxTrackable`, the last base
+destructor (`include/wx/tracker.h`) — non-null throughout the destroy sequence and while a top-level window
+sits in the pending list. The tracker list is unlocked: main thread only. Orca uses it for the splash
+(`wxWeakRef<SplashScreen> scrn` in `GUI_App::on_init_inner`), `g_delay_webviews` (`Widgets/WebView.cpp`),
+`DockPanel`, `GuideFrame`.
+
+**`wxWindowPtr<T>`** is a shared pointer that calls `Destroy()` at refcount 0
+(`interface/wx/windowptr.h:10-26`). It does not track: if the window dies another way (parent deletion,
+default frame close) the last release calls `Destroy()` on freed memory. Use it only for parentless,
+self-owned top-level windows — the documented `ShowWindowModalThenDo` idiom (§6).
+
+**`wxEVT_DESTROY`** (`wxWindowDestroyEvent`, `interface/wx/event.h:4525-4553`): for top-level windows it
+is sent "by wxFrame or wxDialog destructor, i.e. after the destructor of the derived class was executed";
+for children "just before deleting the window from wxWindow::Destroy()… or from the window destructor if
+operator delete was used directly". **[source]** It derives from `wxCommandEvent` and **propagates to the
+parent** unless the parent is being deleted (`wxWindowBase::TryAfter`, `src/common/wincmn.cpp:3499-3522`), so a
+parent's handler fires for every descendant destroyed before it. Derived-class code that must run at
+destruction goes in the derived destructor (or call `SendDestroyEvent()` there).
+
+**Pending events and nested loops.** **[source]** `ProcessPendingEvents` runs queued events and
+`CallAfter`s of a top-level window that is already in `wxPendingDelete` (`src/common/appbase.cpp:561-601`); only the
+actual deletion discards them (`~wxEvtHandler` → `DeletePendingEvents`, `src/common/event.cpp`). Idle
+events are skipped for pending-delete windows (`src/common/appcmn.cpp:405-428`). "Deferred" does not mean "after the
+current handler returns": `ShowModal()`, `wxYield()` and `wxSafeYield()` run pending events *and*
+`DeletePendingObjects()` (`src/common/evtloopcmn.cpp:172-192`), so a raw pointer to a `Destroy()`ed
+window dies across any of them, and a lambda queued before a modal opens can run while the caller is
+still inside `ShowModal()`. A masked `YieldFor` — `wxProgressDialog::Update`/`Pulse` — runs no idle pass
+and only the queued events its categories allow (none on GTK): `references/threads-timers-app.md`
+§Event categories and yields. `CallAfter` liveness mechanics (self-queued calls are dropped
+with their handler; `wxGetApp().CallAfter` calls are not): `references/events.md` §CallAfter. Yields:
+`references/threads-timers-app.md`.
+
+**OrcaSlicer.**
+- Alive flag for anything that may run after the window died, including worker threads:
+  `std::shared_ptr<std::atomic<bool>> m_alive = std::make_shared<std::atomic<bool>>(true);`, set false in the
+  destructor (`PluginsDialog::~PluginsDialog`), captured by value, checked inside the lambda. Unlike
+  `wxWeakRef` it flips at the *start* of the derived destructor and is thread-safe.
+- App shutdown gate: `wxGetApp().is_closing()`; background-to-UI callbacks check it before posting and
+  again inside the `CallAfter` lambda (`references/threads-timers-app.md`).
+
+**Pitfalls.**
+- **Rule:** For a top-level window that something may have `Destroy()`ed, test both flags.
+  ```cpp
+  // Wrong: if (!tlw->IsBeingDeleted()) use(tlw);
+  // Right: if (!wxTheApp->IsScheduledForDestruction(tlw) && !tlw->IsBeingDeleted()) use(tlw);
+  ```
+- **Rule:** Don't trust `wxWeakRef` inside teardown code; combine it with `IsBeingDeleted()` /
+  `IsScheduledForDestruction()` or an alive flag.
+- **Rule:** In a `wxEVT_DESTROY` handler bound on a parent, compare the event object and `Skip()`.
+  ```cpp
+  // Wrong: parent->Bind(wxEVT_DESTROY, [this](auto&) { m_child = nullptr; });
+  // Right:
+  parent->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent& e) {
+      if (e.GetEventObject() == m_child) m_child = nullptr;
+      e.Skip();
+  });
+  ```
+- **Rule:** After `ShowModal()` returns, re-validate anything the modal loop could have destroyed (a
+  popup, a panel rebuilt on a language or preset change) — hold a `wxWeakRef` or alive flag and re-check.
+- **Rule:** Make accessors that are reachable from teardown-time events null-safe: guard the pimpl or
+  child pointer and return `nullptr` instead of dereferencing.
+  **Why:** on macOS, close and shutdown still deliver events (render, idle, focus) that call back into
+  widget accessors after internals are gone; `Plater::get_view3D_canvas3D()` crashed on app close until it
+  checked its pimpl. `Plater::~Plater() = default` destroys `std::unique_ptr<priv> p` *before* the base
+  `wxWindow` destructor runs `DestroyChildren()` (`src/osx/window_osx.cpp:248`, `src/gtk/window.cpp:3105`,
+  `src/msw/window.cpp:421`; `src/common/wincmn.cpp:586-609`), so events raised while children die see a dead pimpl.
+  The null check works only because libc++'s `~unique_ptr` resets before deleting; the standard does not
+  require that, and touching a member after its destructor ran is UB. Treat the guard as a last line of
+  defence; the real fix is to stop the events (unbind, `is_closing()`) before teardown.
+  ```cpp
+  return p->view3D->get_canvas3d();                  // Wrong: crash on close
+  return p ? p->view3D->get_canvas3d() : nullptr;    // Right
+  ```
+  Cite: a162e3f031 (`Plater::get_view3D_canvas3D` in `src/slic3r/GUI/Plater.cpp`).
+
+---
+
+## 4 Top-level windows: show, raise, enable, state, geometry
+
+**Show / Hide.** `Show()` returns false when nothing changed (`interface/wx/window.h:3140-3158`).
+`IsShownOnScreen()` = shown and every parent up to the top-level window shown (`interface/wx/window.h:3100-3106`).
+**[source]** GTK3: `wxTopLevelWindowGTK::Show` calls `GTKSendSizeEventIfNeeded()` even when nothing
+changes, so a redundant `Show(true)` can flush a pending size event into layout handlers
+(`src/gtk/toplevel.cpp:1258-1268`). X11 (GTK2/GTK3 without client-side decorations): the first `Show()`
+may be deferred until `_NET_FRAME_EXTENTS` arrives — `IsShown()` is already true but the window is not
+mapped (`src/gtk/toplevel.cpp:1141-1243`).
+
+**Raise.** "only requests the window manager to raise this window… If the window is currently hidden,
+this function does *not* show it", top-level windows only (`interface/wx/window.h:3013-3033`); true on all ports
+since 3.3 (`docs/changes.txt:144-146`). **[source]** MSW = `::SetForegroundWindow`, subject to the
+foreground lock — Windows may only flash the taskbar button (`src/msw/toplevel.cpp:650-655`); GTK =
+`gtk_window_present` only if shown (`src/gtk/toplevel.cpp:1301-1310`; during a deferred X11 first show it
+already counts as shown); macOS = `makeKeyAndOrderFront` only if shown (`src/osx/nonownedwnd_osx.cpp:289-295`, `src/osx/cocoa/nonownedwnd.mm:896-899`).
+
+**Enable.** `Enable(false)` on a parent disables children logically: `IsEnabled()` reflects ancestors,
+`IsThisEnabled()` the window's own flag (`interface/wx/window.h:3060-3070, 3116-3138`). **[source]** On MSW/macOS wx
+propagates through `NotifyWindowOnEnableChange` → `DoEnable` on non-top-level children — not through the
+virtual `Enable()` — and skips children entirely when a top-level window is disabled, so a modal dialog
+does not grey the frame (`src/common/wincmn.cpp:1150-1191`); GTK relies on native sensitivity. Orca widgets update
+their painted state only from their own `Enable()` override, so disabling an ancestor leaves them
+looking enabled: `references/orca-widgets.md`.
+
+**State and geometry** (`interface/wx/toplevel.h`):
+
+| API | Contract / platform note |
+|---|---|
+| `Iconize()`, `Maximize()` | on wxGTK "the change… is not immediate" (`:260-274, 335-346`); **[source]** MSW on a hidden window only records the state for the next show (`src/msw/toplevel.cpp:661-735`) |
+| `Restore()` | on wxGTK does not unmaximize — call `Maximize(false)` (`:394-404`) |
+| `ShowFullScreen(show, style)` | also shows a hidden window (`:730-750`) |
+| `EnableFullScreenView()` | wxOSX only; then `ShowFullScreen` uses the native Spaces API and only `wxFULLSCREEN_NOTOOLBAR|NOMENUBAR` apply (`:697-728`); `wxEVT_FULLSCREEN` is macOS-only, only with it, and not generated by `ShowFullScreen()` (`interface/wx/event.h:2391-2412`) |
+| `RequestUserAttention()` | documented for Win32 (taskbar flash) and wxGTK (`:375-392`); **[source]** macOS bounces the dock icon (`src/osx/cocoa/nonownedwnd.mm:1306`) |
+| `SetIcon/SetIcons` | MSW needs a 16×16 or 32×32 icon; no effect on Wayland — ship a `.desktop` file (`:506-546`); **[source]** no macOS override: stored, never shown |
+| `SetSizeHints/SetMinSize/SetMaxSize` | on a top-level window they also constrain programmatic `SetSize()` (`:576-603`) |
+| `SetTransparent()` | on wxGTK call it before the first show (`:632-648`) |
+| `EnableMaximizeButton/EnableMinimizeButton` | MSW and macOS only (`:172-203`) |
+| `EnableCloseButton` | all ports, but its result is unreliable on X11, GTK included (`:160-170`) |
+| `wxEVT_MOVE_START/END` | wxMSW only (`:80-87`) |
+| `wxEVT_SHOW` | not sent for iconize/restore on MSW (`interface/wx/event.h:4905-4914`) |
+| `SaveGeometry/RestoreToGeometry`, `wxPersistentTLW` | serializer-based persistence (`:406-492`; `interface/wx/persist/toplevel.h`) — not used by Orca |
+
+**Wayland.** `SetIcon(s)` do nothing (`interface/wx/toplevel.h:518-521, 539-542`); the app id comes from
+`SetClassName` with GTK ≥ 3.24.22 (`interface/wx/app.h:765-771`). `SetPosition()`/`Move()` on a
+top-level window is a no-op (the compositor places windows), so `CentreOnParent` and saved positions are
+ignored (observed; recorded in `GUI_App::window_pos_restore`, not documented by wx). Detection: `Slic3r::GUI::is_running_on_wayland()`; see `references/platforms.md`.
+
+**OrcaSlicer geometry persistence.** Orca uses `AppConfig`, not `wxPersistentTLW`:
+`GUI_App::window_pos_save` / `window_pos_restore` / `window_pos_sanitize` / `window_pos_center` (key
+`window_<name>`, a `WindowMetrics` = screen rect + maximized; restore skips `SetPosition` on Wayland), and
+`on_window_geometry(tlw, callback)` (`GUI_Utils.cpp`) to run the callback when geometry is real — MSW
+immediately (no `wxEVT_SHOW` for windows created maximized), Linux on `wxEVT_SHOW` + `CallAfter`, macOS on
+`wxEVT_SHOW`. `GUI_App::persist_window_geometry(window, default_maximized)` saves on
+`wxEVT_CLOSE_WINDOW` (then `Skip()`) but always uses the key `window_mainframe`, whatever the window's
+name — for any other window call `window_pos_save/restore` with its own name.
+
+**Pitfalls.**
+- **Rule:** When restoring a top-level window (the main frame after hiding a popup or overlay frame, or a
+  singleton dialog being re-opened), call `Show()` only if `!IsShown()`, and call `Raise()` unconditionally.
+  **Why:** `Raise()` never shows a hidden window (3.3 on all ports); on GTK3 a redundant `Show(true)` runs
+  `GTKSendSizeEventIfNeeded()`, flushing a pending size event into layout handlers — in Orca this froze the
+  app permanently after hiding the filament-sync popup.
+  ```cpp
+  // Wrong
+  mainframe->Show(); mainframe->Raise();
+  // Right
+  if (!mainframe->IsShown()) mainframe->Show();
+  mainframe->Raise();
+  ```
+  Cite: dd8cb89f6d (`BaseTransparentDPIFrame::on_hide`); the same guard in `GUI_App::open_terminal_dialog`.
+- **Rule:** On macOS, after any native modal (`wxFileDialog`/`wxDirDialog`, `wxMessageBox`/`wxMessageDialog`)
+  or a generic `wxProgressDialog` opened from a secondary top-level dialog, re-raise that dialog with a
+  deferred, liveness-guarded `Raise()` (`CallAfter` + alive flag + `IsShown()`).
+  **Why:** when the native panel closes, macOS re-activates the app's main window instead of the dialog
+  that opened it, burying the dialog behind the main frame (observed; not documented by wx). wx compensates
+  only for its own `wxDialog` modals — `EndModal` raises the parent (`src/osx/dialog_osx.cpp:191-202`) —
+  while `wxFileDialog::ShowModal` runs `[panel runModal]` with no such step (`src/osx/cocoa/filedlg.mm:597-620`),
+  and on macOS `wxProgressDialog` is the generic dialog (only MSW has a native one,
+  `include/wx/progdlg.h:30-37`), normally shown modeless behind a disabler and destroyed, never ended
+  through `EndModal`. The `Raise()` is deferred to run after the modal has fully torn down, and guarded
+  because the dialog may be destroyed while queued.
+  ```cpp
+  void PluginsDialog::restore_z_order()
+  {
+      wxGetApp().CallAfter([this, alive = m_alive]() {
+          if (alive->load(std::memory_order_acquire) && IsShown())
+              Raise();
+      });
+  }
+  ```
+  Cite: 0a0d59b76b (`PluginsDialog::restore_z_order`; also passed as the `restore` callback of
+  `detail::run_off_thread_with_progress`).
+- **Rule:** Never position windows by absolute coordinates on Wayland, and never expect `SetIcon` to show on
+  macOS or Wayland.
+
+---
+
+## 5 Window styles
+
+**Contract.**
+- `wxDEFAULT_FRAME_STYLE` = `wxSYSTEM_MENU | wxRESIZE_BORDER | wxMINIMIZE_BOX | wxMAXIMIZE_BOX |
+  wxCLOSE_BOX | wxCAPTION | wxCLIP_CHILDREN` (`interface/wx/toplevel.h:55-61`); `wxDEFAULT_DIALOG_STYLE`
+  = `wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX`, `wxSYSTEM_MENU` unused under Unix (`interface/wx/dialog.h:20, 99-101`).
+  Non-resizable frame: `wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxMAXIMIZE_BOX)`.
+- `wxMINIMIZE_BOX`, `wxMAXIMIZE_BOX`, `wxCLOSE_BOX` implicitly enable `wxCAPTION` "on most systems"
+  (`interface/wx/dialog.h:94-114`, `interface/wx/frame.h:61-80`). `wxMAXIMIZE_BOX` is ignored on wxGTK without
+  `wxRESIZE_BORDER` (`interface/wx/frame.h:75-78`). The `wxMAXIMIZE` style works on Windows and GTK only; `wxICONIZE`/
+  `wxMINIMIZE` on Windows only (`interface/wx/frame.h:59-74`).
+- `wxSTAY_ON_TOP`: above all other windows. `wxFRAME_FLOAT_ON_PARENT`: above its parent only, "must have a
+  non-null parent". `wxFRAME_NO_TASKBAR`: no taskbar button on Windows/GTK (GTK only with
+  `_NET_WM_STATE_SKIP_TASKBAR` support). `wxFRAME_TOOL_WINDOW`: small title bar, no taskbar button
+  (`interface/wx/frame.h:82-106`).
+- Borders: `wxBORDER_NONE/SIMPLE/SUNKEN/RAISED/STATIC(MSW)/THEME`; `wxTRANSPARENT_WINDOW` is obsolete and
+  does nothing (`interface/wx/window.h:191-220`).
+- Extra styles (`SetExtraStyle`, some must precede two-step `Create`): `wxWS_EX_BLOCK_EVENTS`,
+  `wxWS_EX_TRANSIENT` ("Don't use this window as an implicit parent… risk of creating a dialog/frame with
+  this window as a parent, which would lead to a crash"), `wxWS_EX_PROCESS_IDLE`,
+  `wxWS_EX_PROCESS_UI_UPDATES` (`interface/wx/window.h:262-290`). Dialogs set `wxWS_EX_BLOCK_EVENTS` by default
+  (`src/common/dlgcmn.cpp:124-127`): command events from inside a dialog never reach its parent frame;
+  frames do not block.
+
+**Platforms. [source]**
+
+| Style | MSW | macOS | GTK |
+|---|---|---|---|
+| MIN/MAX/CLOSE_BOX | force `WS_CAPTION` (`src/msw/toplevel.cpp:132-137`) — a custom title bar must strip it | — | — |
+| frame with a parent, no `FLOAT_ON_PARENT` | unowned; gets its own taskbar button (`WS_EX_APPWINDOW`) unless `wxFRAME_NO_TASKBAR` (`src/msw/toplevel.cpp:193-244`) | — | — |
+| `wxFRAME_FLOAT_ON_PARENT` | native owner = `GetHwndOf(parent)` as given (`MSWGetParent`, `src/msw/toplevel.cpp:212-240`) — pass a top-level window | `NSFloatingWindowLevel`, a *global* level: floats above other apps' windows too (`src/osx/cocoa/nonownedwnd.mm:835-876`) | `transient_for` the parent's top-level window, set only in `Create` (`src/gtk/toplevel.cpp:774-782`) |
+| `wxFRAME_TOOL_WINDOW` | small caption, no taskbar | `NSFloatingWindowLevel` | no taskbar |
+| `wxSTAY_ON_TOP` | `WS_EX_TOPMOST` | `NSModalPanelWindowLevel` | keep-above + `transient_for` in `Create` (`src/gtk/toplevel.cpp:774-791`); runtime change honoured |
+| runtime `SetWindowStyleFlag` | — | re-levels the window (`src/osx/cocoa/nonownedwnd.mm:1038-1056`) | updates only `STAY_ON_TOP` and `NO_TASKBAR` (`src/gtk/toplevel.cpp:1943-1968`) |
+
+macOS dialogs are not attached as Cocoa child windows (no `addChildWindow`, `src/osx/cocoa/nonownedwnd.mm:947-991`),
+so they do not move with their parent; non-tool windows get `setHidesOnDeactivate:NO`.
+
+**OrcaSlicer.**
+- `DPIAware`'s constructor defaults `style = wxDEFAULT_FRAME_STYLE` and `name = wxFrameNameStr` for
+  dialogs too: `DPIDialog(parent, id, title)` without a style is resizable with min/max boxes. Pass
+  `wxCAPTION | wxCLOSE_BOX` or `wxDEFAULT_DIALOG_STYLE` (§7).
+- `MainFrame` uses `BORDERLESS_FRAME_STYLE` (`MainFrame.cpp`: min/max/close boxes, plus `wxRESIZE_BORDER`
+  off Apple, no `wxCAPTION`) and paints its own title bar: MSW strips the `WS_CAPTION` that wx adds,
+  macOS calls `set_miniaturizable`, GTK adds `ResizeEdgePanel`s. Custom titlebar rules:
+  `references/platforms.md`.
+- `TextureProjectorFrame` is the model for a tool frame floating above the main window:
+  `wxCAPTION | wxRESIZE_BORDER | wxCLOSE_BOX | wxFRAME_NO_TASKBAR | wxFRAME_FLOAT_ON_PARENT`, parented to
+  `mainframe`, `SetTransparent` before the first show.
+
+**Pitfalls.**
+- **Rule:** Remove style bits with `& ~flag`; `!flag` is 0.
+  ```cpp
+  // Wrong: !wxCAPTION | !wxCLOSE_BOX | wxBORDER_NONE      // == wxBORDER_NONE by accident
+  // Right: wxBORDER_NONE                                   // or: wxDEFAULT_FRAME_STYLE & ~wxCAPTION
+  ```
+- **Rule:** Parent a `wxFRAME_FLOAT_ON_PARENT` frame to a top-level window, never to a panel or NULL.
+  **Why:** with NULL wx asserts (silently in Orca) and ignores the flag (`wxTopLevelWindowMSW::MSWGetParent`).
+  With a panel, the ports disagree on the owner — MSW passes the panel's own HWND (`GetHwndOf(parent)`),
+  GTK resolves `wxGetTopLevelParent(parent)` (`src/gtk/toplevel.cpp:774-782`) — and the frame is deleted
+  with the panel (§2). A top-level parent gives every port the same owner and lifetime.
+- **Rule:** Don't use `wxSTAY_ON_TOP` or `wxFRAME_FLOAT_ON_PARENT` to keep a tool window "above the app" on
+  macOS without accepting that it also floats above other applications.
+
+---
+
+## 6 Dialogs and modality
+
+**Contract** (`interface/wx/dialog.h`).
+- Stack allocation is the sanctioned form for a modal dialog: "the modal dialog is one of the very few
+  examples of wxWindow-derived objects which may be created on the stack… no need to call Destroy()";
+  heap form `ShowModal()` then `dlg->Destroy()` (`interface/wx/dialog.h:61-88`).
+- `ShowModal()`: "Program flow does not return until the dialog has been dismissed with EndModal()…
+  ShowModal() can't be called twice without intervening EndModal() calls… creates a temporary event loop…
+  also results in a call to wxApp::ProcessPendingEvents()" (`interface/wx/dialog.h:597-618`). Timers, `CallAfter`s,
+  idle-time deletion, socket and worker events all run inside it.
+- `EndModal(retCode)` sets the value `ShowModal()` returns (`interface/wx/dialog.h:340-349`). `Show(false)`: "The preferred
+  way of dismissing a modal dialog is to use EndModal()" (`interface/wx/dialog.h:586-595`).
+- `ShowWindowModal()` is "only fully implemented in wxOSX… under the other platforms it behaves like
+  ShowModal()" (`interface/wx/dialog.h:620-638`). `ShowWindowModalThenDo(functor)`: the dialog must outlive the functor —
+  hold it in a `wxWindowPtr` captured by value (`interface/wx/dialog.h:640-678`).
+- "you shouldn't show a modal dialog from a mouse click event handler as this would break the mouse capture
+  state" — defer with `CallAfter` (`interface/wx/event.h:490-497`). **[source]** GTK's `ShowModal` releases
+  any mouse capture first (`GTKReleaseMouseAndNotify`, `src/gtk/dialog.cpp:137`). Capture rules:
+  `references/mouse-keyboard-focus.md`.
+
+**[source] facts.**
+- `wxDialogBase::EndDialog(rc)` (protected, `src/common/dlgcmn.cpp:361-367`) = `IsModal() ? EndModal(rc) : Hide()`:
+  ends either kind from inside the class.
+- Modal loops nest and unwind LIFO on every port: MSW `wxEventLoopManual::DoStop` only wakes the loop
+  (`src/common/evtloopcmn.cpp:388-401`), GTK re-enters `gtk_main()` until its own `m_shouldExit`
+  (`src/gtk/evtloop.cpp:58-90`), macOS keeps a LIFO `s_modalStack` (`src/osx/dialog_osx.cpp:47-60`) and
+  stops via `[NSApp abortModal]`, which hits the innermost session (`src/osx/cocoa/evtloop.mm:453-456`).
+  Every port's `EndModal` stops its loop through `wxEventLoopBase::Exit()`, whose
+  `wxCHECK_RET(IsRunning())` returns silently unless that loop is the active (innermost) one
+  (`src/common/evtloopcmn.cpp:91-96`; MSW via `Hide()` → `wxDialogModalData::ExitLoop`,
+  `src/msw/dialog.cpp:64-67, 199-207, 261-268`; macOS `src/osx/dialog_osx.cpp:191-194`; GTK's `EndModal` tests
+  `IsRunning()` itself, `src/gtk/dialog.cpp:199-202`). Ending a lower dialog first therefore hides it
+  but never tells its loop to exit: its `ShowModal()` does not return even after every dialog above it
+  has ended. On MSW its `wxWindowDisabler` (owned by the generic `wxModalEventLoop` that MSW's
+  `ShowModal` runs, deleted only in its `OnExit()`, `include/wx/evtloop.h:377-396`) stays alive too,
+  so the other top-level windows remain disabled. GTK uses no disabler: modality is each dialog's own
+  `gtk_window_set_modal` grab (`src/gtk/dialog.cpp:158`). The same silent `Exit()` no-op applies to
+  nested `wxEventLoop`s: `references/threads-timers-app.md` §Nested event loops.
+- Return codes are ids: `wxID_OK = 5100`, `wxID_CANCEL`, `wxID_APPLY`, `wxID_YES`, `wxID_NO`, …
+  (`include/wx/defs.h:1847`). `wxYES 0x2`, `wxOK 0x4`, `wxNO 0x8`, `wxCANCEL 0x10`, `wxAPPLY 0x20`,
+  `wxCLOSE 0x40` are style bits (`include/wx/defs.h:1665-1672`) — `EndModal(wxCANCEL)` makes `ShowModal() == wxID_CANCEL` false.
+- Whichever `EndModal` runs last before `ShowModal()` returns sets the result: every port's `EndModal`
+  calls `SetReturnCode` unconditionally and `ShowModal()` returns `GetReturnCode()`.
+
+**Per-port modal behaviour. [source]**
+
+| | MSW (`src/msw/dialog.cpp:195-268`) | macOS (`src/osx/dialog_osx.cpp:106-202`) | GTK (`src/gtk/dialog.cpp:60-205`) |
+|---|---|---|---|
+| `Hide()`/`Show(false)` on a modal dialog | exits the loop; `ShowModal()` returns the current code (0 if none set) | **does not exit**: clears the modality, orders the window out; `ShowModal()` stays blocked behind an invisible dialog, and wx's `EndDialog` path then takes the `Hide()` branch | calls the virtual `EndModal(wxID_CANCEL)`, overwriting any code |
+| `EndModal()` on a modeless dialog | sets the code and hides (assert compiled out) | sets the code, hides, raises the parent | sets the code, then `wxFAIL` + return: the dialog stays visible |
+| `IsModal()` between `EndModal()` and the return of `ShowModal()` | true (`m_modalData`, `include/wx/msw/dialog.h:48`) | false | false |
+| `EndModal()` raises the parent | no | yes ("Prevent app frame from taking z-order precedence") | no |
+| native owner / transient | fixed at `Create` (§1) | none (not a child window) | `transient_for` set in `ShowModal()` |
+| how other windows are blocked | `wxWindowDisabler` in a generic `wxModalEventLoop` (`src/msw/dialog.cpp:70`) | Cocoa modal session (`src/osx/cocoa/evtloop.mm:424-456`) | `gtk_window_set_modal` grab; mouse capture released first |
+
+**Buttons, ESC and the close box. [source]**
+- `SetAffirmativeId(id)` (default `wxID_OK`): that button runs `Validate()` + `TransferDataFromWindow()` and
+  closes with the id (`interface/wx/dialog.h:480-494`). `SetEscapeId(id)`: default `wxID_ANY` = the `wxID_CANCEL`
+  button if present, else the affirmative one; `wxID_NONE` = ignore ESC; native dialogs cannot be
+  customized (`interface/wx/dialog.h:496-515`). `CreateStdDialogButtonSizer` makes `wxButton`s and sets the affirmative
+  id (`interface/wx/dialog.h:291-304`) — Orca uses `DialogButtons` instead (§8).
+- Routing is by **id**, not type: `wxDialogBase::OnButton` (static table, `src/common/dlgcmn.cpp:455-480`) handles any
+  `wxEVT_BUTTON` that propagates to the dialog — affirmative id → `AcceptAndClose()` (`Validate()` +
+  `TransferDataFromWindow()` then `EndDialog(id)`), `wxID_APPLY` → validate + transfer, no close, escape id
+  or `wxID_CANCEL` → `EndDialog(wxID_CANCEL)`, anything else skipped. An Orca `Button` with `wxID_OK` or
+  `wxID_CANCEL` and no handler (or a handler that `Skip()`s) closes the dialog by itself; a handler bound
+  on the button that does not `Skip()` suppresses it.
+- ESC → `wxDialogBase::OnCharHook` → `SendCloseButtonClickEvent()`: tries the escape id (`wxID_CANCEL`), then
+  the affirmative id, through `EmulateButtonClickIfPresent`, which does
+  `wxDynamicCast(FindWindow(id), wxButton)` and requires the button enabled and shown
+  (`src/common/dlgcmn.cpp:387-453`). Orca's `Button` derives from `StaticBox : wxWindow`, so emulation finds nothing:
+  in a plain `wxDialog` with Orca buttons ESC does nothing; in a `DPIDialog`, `DPIAware`'s own char hook
+  turns ESC into `Close()` first (§7).
+- Close box (and `Close()`) → `wxDialogBase::OnCloseWindow` (`src/common/dlgcmn.cpp:525-559`): if shown, try
+  `SendCloseButtonClickEvent()`; when that finds no `wxButton`, `EndDialog(wxID_CANCEL)`. The Cancel
+  button's own handler never runs on this path.
+
+**Modeless dialogs.** `Show()`; the close box only hides them (above). Long-lived modeless windows (monitor
+pages, progress dialogs, plugin dialogs) either destroy themselves in a close handler or are deliberately
+hide-on-close and reused (§2 shapes).
+
+**Modality helpers.**
+- `wxWindowDisabler(winToSkip, winToSkip2)` disables all *shown and enabled* top-level windows except the
+  skipped ones and re-enables them in its destructor (`interface/wx/utils.h:58-111`). MSW: a skipped window
+  that appears in the taskbar lets the user close the whole app from the taskbar (`interface/wx/utils.h:93-99`).
+  **[source]** The destructor re-enables every top-level window not recorded as skipped — including ones
+  created after the disabler (`src/common/utilscmn.cpp:1527-1546`); on macOS the constructor begins a Cocoa
+  modal session and **shows** `winToSkip` if it is not on screen (`src/osx/cocoa/evtloop.mm:458-514, 573-584`).
+  Keep disablers scoped and strictly nested.
+- `wxModalDialogHook::GetOpenCount()` (since 3.3.0, `interface/wx/modalhook.h:118-126`) counts every open
+  modal — generic and native message/file/colour/font/print dialogs all use `WX_HOOK_MODAL_DIALOG`. Use it
+  for "is any modal open" in new code.
+- `wxFrame::SetWindowModality(wxWindowMode)` (new in 3.3.2): call before showing; `AppModal`/`WindowModal`
+  (`interface/wx/frame.h:318-329`). **[source]** Applies immediately in the call, ends at the first hide, adds
+  `wxFRAME_NO_TASKBAR` and removes `wxMINIMIZE_BOX` (`src/common/framecmn.cpp:159-195, 304-339`); it does not
+  block — the caller keeps running.
+- Orca's pseudo-modal `ParamsDialog` (filament/printer settings): shown modeless with `Popup()` →
+  `Show()`, creates a heap `wxWindowDisabler(this)` in its `wxEVT_SHOW` handler and deletes it on hide; its
+  close handler validates (vetoes when validation fails and `CanVeto()`), hides, and never destroys, so the
+  hosted tabs stay reusable; `ParamsDialog::Popup()` calls `Reparent(mainframe)` on Windows before showing.
+
+**Pitfalls.**
+- **Rule:** Use `wxID_*` codes with `EndModal`.
+  ```cpp
+  // Wrong: EndModal(wxCANCEL);  EndModal(wxCLOSE);  EndModal(wxOK);
+  // Right: EndModal(wxID_CANCEL); EndModal(wxID_CLOSE); EndModal(wxID_OK);
+  ```
+- **Rule:** Dismiss a modal dialog with `EndModal(rc)`, not `Hide()`/`Show(false)`.
+  **Why:** macOS keeps `ShowModal()` blocked behind an invisible dialog; GTK forces `wxID_CANCEL`; MSW
+  returns whatever code was last set.
+- **Rule:** `EndModal()` only on a modal dialog; a modeless one is hidden/closed/destroyed (or `EndDialog`).
+  **Why:** GTK ignores `EndModal` on a modeless dialog — it stays on screen there and only there.
+- **Rule:** Never `Destroy()` a modal dialog whose loop is still running; `EndModal(rc)` first, then
+  `Destroy()` (heap) — from the caller once `ShowModal()` has returned, or straight after `EndModal()`
+  as forced teardown does, relying on a top-level `Destroy()` only queuing the deletion. Never `Destroy()`
+  a stack dialog.
+  Cite: `WebDialog::destroy_silently` (`EndModal(wxID_CANCEL)` then `Destroy()`).
+- **Rule:** Close nested modal dialogs innermost-first.
+  **Why:** ending a lower one hides it but leaves its `ShowModal()` stranded (and, on MSW, its disabler
+  alive) on every port — see the LIFO bullet above.
+- **Rule:** Show a modal from a mouse handler only through `CallAfter`.
+  ```cpp
+  // Wrong: m_btn->Bind(wxEVT_LEFT_DOWN, [this](wxMouseEvent&) { MyDialog dlg(this); dlg.ShowModal(); });
+  // Right:
+  m_btn->Bind(wxEVT_LEFT_DOWN, [this](wxMouseEvent& e) {
+      e.Skip();
+      CallAfter([this] { MyDialog dlg(this); dlg.ShowModal(); });
+  });
+  ```
+  The same applies to `EndModal` bound to `wxEVT_LEFT_DOWN`; bind `wxEVT_BUTTON` on an Orca `Button` instead.
+- **Rule:** No window work (create, show, raise, destroy, modal dialogs) on the stack of a
+  `wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED` handler — WebKitGTK and WKWebView deliver it synchronously. Detail
+  and the `WebViewHostDialog` contract: `references/webview-gl-aui-media.md`.
+- **Rule:** Scope a `wxWindowDisabler` on the stack or tie it strictly to show/hide; never let heap
+  disablers outlive their window or end out of order (on macOS each one is a modal session).
+
+---
+
+## 7 DPIDialog and DPIFrame
+
+`template<class P> class DPIAware : public P, public wxInspector::wxInspectable` (`GUI_Utils.hpp`);
+`typedef DPIAware<wxFrame> DPIFrame;` `class DPIDialog : public DPIAware<wxDialog>`. New Orca dialogs and
+frames derive one of them. Public API: `scale_factor()`, `prev_scale_factor()`, `em_unit()`,
+`normal_font()`, `enable_force_rescale()`; on Windows `force_color_changed()`. Subclasses implement the pure
+virtual `on_dpi_changed(const wxRect&)` and may override `on_sys_color_changed()`.
+
+**What the constructor does** (one-step construction only; signature
+`(parent, id, title, pos = wxDefaultPosition, size = wxDefaultSize, style = wxDEFAULT_FRAME_STYLE,
+name = wxFrameNameStr)`):
+
+| Step | Detail | Owner of the topic |
+|---|---|---|
+| scale factor, normal font | from `get_dpi_for_window(this)`; `SetFont(m_normal_font)` **except on macOS** (`#ifndef __WXOSX__`, avoids name cutting in `ObjectList`) | `references/dpi-bitmaps-fonts.md` |
+| `CenterOnParent()` | runs **before any content exists** — re-centre after fitting | §8 |
+| `SetupInspectorAccelerator(this)` | wxInspector toggle (Ctrl+Shift+I) in builds without `WXINSPECTOR_DISABLE`; a later `SetAcceleratorTable()` on the window replaces it | `references/orca-widgets.md` |
+| MSW `update_dark_ui(this)` | no-op (its body only reads the dark flag) | `references/colours-dark-mode.md` |
+| `update_em_unit()` | non-GTK `max(10, 10·scale)`; GTK `max(10, GetTextExtent("m").x - 1)` | `references/dpi-bitmaps-fonts.md` |
+| bind `wxEVT_DPI_CHANGED` (not macOS) | rescales (`Freeze` → font/em → `on_dpi_changed` → `Layout` → `Thaw`) when the scale changed and no monitor drag is in progress, and does **not** `Skip()` — so wx's default top-level handler (scale the window size by the DPI ratio) never runs (`interface/wx/event.h:3572-3583`) | `references/dpi-bitmaps-fonts.md` |
+| bind `wxEVT_MOVE_START/END` (MSW-only events) | defer rescale while the window is dragged between monitors | `references/dpi-bitmaps-fonts.md` |
+| bind `wxEVT_SYS_COLOUR_CHANGED` | non-Windows: `update_dark_config()` + `on_sys_color_changed()` + `Skip()`; Windows: swallowed | `references/colours-dark-mode.md` |
+| dialogs only: bind `wxEVT_CHAR_HOOK` | `WXK_ESCAPE` → `this->Close()`, never skipped; other keys skipped | below |
+
+**ESC in a `DPIDialog`.** ESC = the close box: your `wxEVT_CLOSE_WINDOW` handler if any, else
+`wxDialogBase::OnCloseWindow` → `EndDialog(wxID_CANCEL)` (modal: `ShowModal()` returns `wxID_CANCEL`;
+modeless: hidden). The dynamic `DPIAware` hook runs before wx's static `wxDialogBase::OnCharHook`, so
+`SetEscapeId()` has no effect on ESC. A `MessageDialog` with only Yes/No buttons therefore returns
+`wxID_CANCEL` on ESC or the close box — callers must treat anything but `wxID_YES` as "no".
+
+**`dialogStack` and the `EndModal` guard.** `DPIAware::ShowModal()` (same signature as the virtual
+`wxDialog::ShowModal`, so it overrides it) pushes `this` on the global `std::deque<wxDialog*> dialogStack`
+(`GUI_Utils.cpp`) and pops it after the loop. `DPIDialog::EndModal(retCode)` **refuses** — logs
+"DPIAware::EndModal Error…", returns, the dialog stays open and modal — when the stack is non-empty and
+`this` is not `dialogStack.front()`. It is a guard for the LIFO rule of §6, not a fix for a wx bug: wx
+cannot end a lower loop first on any port (the dialog would be hidden with its `ShowModal()` stranded),
+and the guard turns that into a no-op. It only knows
+`DPIDialog`s that went through `DPIAware::ShowModal()`; native and plain-wx modals are not on the stack.
+Consumers: `GUI_App::ShowDownNetPluginDlg` (searches the stack to avoid a second instance) and the
+`wxEVT_QUERY_END_SESSION` handler in `GUI_App::on_init_inner` (sends a vetoable close to `mainframe`, then
+`EndModal(wxID_ABORT)` on every stacked dialog — with the guard only the innermost actually ends). For "is
+any modal open" in new code prefer `wxModalDialogHook::GetOpenCount()`.
+
+There is no `Destroy()` override: heap `DPIDialog`s follow the stock `ShowModal(); Destroy();` or the
+stack form.
+
+**Pitfalls.**
+- **Rule:** Pass the style explicitly.
+  ```cpp
+  // Wrong: MyDialog(wxWindow* p) : DPIDialog(p, wxID_ANY, _L("Title")) {}   // resizable, min/max boxes
+  // Right: MyDialog(wxWindow* p) : DPIDialog(p, wxID_ANY, _L("Title"), wxDefaultPosition,
+  //                                          wxDefaultSize, wxCAPTION | wxCLOSE_BOX) {}
+  ```
+- **Rule:** Call `CenterOnParent()` again after `SetSizerAndFit()` (`MsgDialog::finalize` does).
+  **Why:** the `DPIAware` constructor centred the empty, default-sized window.
+- **Rule:** An override of `ShowModal()` must call `DPIDialog::ShowModal()` (as
+  `RichMessageDialog::ShowModal` → `MsgDialog::ShowModal()`, `UnsavedChangesDialog`, `TextureImportDialog`
+  do), never `wxDialog::ShowModal()`.
+  **Why:** a dialog that bypasses the push is not on `dialogStack`; when it is opened above another
+  `DPIDialog`, its own `EndModal` is refused and it cannot close.
+- **Rule:** To keep ESC from closing a `DPIDialog`, veto in the close handler or bind your own
+  `wxEVT_CHAR_HOOK` that swallows `WXK_ESCAPE`; `SetEscapeId(wxID_NONE)` does nothing here.
+  ```cpp
+  // Right: bound in the subclass constructor, i.e. after DPIAware's hook, so it runs first
+  Bind(wxEVT_CHAR_HOOK, [](wxKeyEvent& e) { if (e.GetKeyCode() != WXK_ESCAPE) e.Skip(); });
+  ```
+- **Rule:** A child that binds the dialog's `wxEVT_DPI_CHANGED` must be bound after `DPIAware` (any child
+  created in the subclass constructor is) and must `Skip()`.
+  **Why:** dynamic handlers run most-recently-bound first (`interface/wx/event.h:592-593`) and `DPIAware`'s
+  handler does not skip; `DialogButtons` binds its parent's event in its constructor and calls `Skip()`,
+  so it runs and then `DPIAware` rescales. It unbinds in its destructor — the model for any widget that
+  binds an event on another window.
+
+---
+
+## 8 The Orca dialog recipe
+
+Exemplars: `src/slic3r/GUI/CloneDialog.cpp` (minimal; `DialogButtons` with a left-aligned extra button,
+an Enter-key `wxEVT_CHAR_HOOK` that synthesizes the OK `wxEVT_BUTTON`; its OK handler's `wxYield()` loop
+inside a frozen plater is not a pattern to copy), `PurgeModeDialog.cpp` (custom-painted clickable card
+panels; OK/Cancel `Button`s that close purely by id through `wxDialogBase::OnButton`;
+`on_dpi_changed` with min size + `Fit()`/`Refresh()`; its `msw_buttons_rescale` call also resizes those
+Orca `Button`s, so leave it out when copying), `FilamentPickerDialog.cpp`
+(larger; helper `Create*()` methods returning sizers; positions itself next to the sidebar).
+
+```cpp
+class MyDialog : public DPIDialog
+{
+public:
+    explicit MyDialog(wxWindow* parent)
+        : DPIDialog(parent ? parent : static_cast<wxWindow*>(wxGetApp().mainframe), wxID_ANY,
+                    _L("My Dialog"), wxDefaultPosition, wxDefaultSize,
+                    wxCAPTION | wxCLOSE_BOX)              // or wxDEFAULT_DIALOG_STYLE; never omit
+    {
+        SetBackgroundColour(*wxWHITE);                    // light design colour, dark-mapped at the end
+        SetFont(Label::Body_14);
+
+        auto* sizer = new wxBoxSizer(wxVERTICAL);
+        // ... children: Orca widgets, sizes via FromDIP(n), labels via _L() ...
+        sizer->Add(content_sizer, 1, wxEXPAND | wxALL, FromDIP(10));
+
+        auto* dlg_btns = new DialogButtons(this, {"OK", "Cancel"});   // NOT pre-translated
+        dlg_btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { /* apply */ EndModal(wxID_OK); });
+        dlg_btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { /* cancel work */ EndModal(wxID_CANCEL); });
+        Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent& e) { /* same cancel work */ e.Skip(); });  // ESC, close box
+        sizer->Add(dlg_btns, 0, wxEXPAND);
+
+        SetSizerAndFit(sizer);
+        CenterOnParent();                                 // DPIAware centred the empty window
+        wxGetApp().UpdateDlgDarkUI(this);                 // always last, after all children exist
+    }
+
+protected:
+    void on_dpi_changed(const wxRect&) override;          // rescale bitmaps/widgets, min sizes, GetSizer()->SetSizeHints(this), Refresh()
+};
+
+// caller
+MyDialog dlg(this);
+if (dlg.ShowModal() == wxID_OK) { /* read results */ }
+```
+
+**Conventions and why.**
+- `DPIDialog` supplies `scale_factor()`, `em_unit()`, DPI-change handling and ESC handling, and requires
+  `on_dpi_changed(const wxRect&)`. Typical body: `Rescale()` on Orca widgets, `msw_rescale()` (+
+  `SetBitmap()` on the displaying control) on `ScalableBitmap`s, min sizes reset in em units or `FromDIP`,
+  then `GetSizer()->SetSizeHints(this)` (or a dialog `SetMinSize` + `Fit()`) and `Refresh()`.
+  `msw_buttons_rescale(this, em_unit(), ids)` (min height 2.5 em on the windows with those ids) is for raw
+  `wxButton`s only: it also overrides the style height of Orca `Button`s carrying those ids, including the
+  `DialogButtons` OK/Cancel. An empty override is acceptable only for trivially simple dialogs
+  (`CloneDialog`; on MSW it then keeps its old pixel size). Detail: `references/dpi-bitmaps-fonts.md`
+  §DPIAware rescale path, `references/sizers-layout.md` §Layout on DPI change.
+- Parent fallback `parent ? parent : wxGetApp().mainframe` — never orphan a dialog (§1).
+- Title and labels through `_L()` (`references/strings-i18n-files.md`).
+- `SetBackgroundColour(*wxWHITE)` and `SetFont(Label::Body_14)` at the top. Setting a font on a dialog is
+  fine on every platform; the macOS "no `SetFont`" concern is `DPIAware`'s per-DPI default font
+  (ObjectList name cutting), which `DPIAware` already skips there.
+- Light design colours everywhere; `wxGetApp().UpdateDlgDarkUI(this)` as the last line maps them for dark
+  mode and themes the native parts on Windows; child panels built later use `UpdateDarkUIWin`. Hand-picked
+  colours go through `StateColor::darkModeColorFor(wxColour("#..."))`. Detail: `references/colours-dark-mode.md`.
+- `SetSizerAndFit(sizer)` on the dialog (AGENTS.md rule); where `SetSizer` must come first, follow with
+  `sizer->SetSizeHints(this)` (`MsgDialog::finalize` does `GetSizer()->SetSizeHints(this)`). Child panels use
+  plain `SetSizer`. Detail: `references/sizers-layout.md`.
+- `CenterOnParent()` after sizing. Dialogs may set the app icon
+  (`SetIcon(wxIcon(encode_path(icon_path.c_str()), wxBITMAP_TYPE_ICO))` with
+  `resources_dir()/images/OrcaSlicerTitle.ico`, as `PurgeModeDialog` does — no effect on macOS or
+  Wayland, §4) and
+  clamp their size with `SetMinSize/SetMaxSize(FromDIP(...))`.
+- Modality: construct on the caller's stack, `ShowModal()`, read the `wxID_*` result. Heap form:
+  `auto* dlg = new MyDialog(this); dlg->ShowModal(); dlg->Destroy();`. `Show()` is for modeless,
+  long-lived windows (monitor pages, progress dialogs, plugin dialogs), with a close shape from §2.
+
+**`DialogButtons` and how its buttons close the dialog.** `Slic3r::GUI::DialogButtons(parent,
+non_translated_labels, primary_btn_translated_label = "", left_aligned_buttons_count = 0)` is a `wxPanel`
+of Orca `Button`s. It calls `_L()` on each label itself and assigns a stock id by matching the lower-cased
+label (catalogue: `references/orca-widgets.md`).
+
+| Label | Id | Closes the dialog with no handler bound? |
+|---|---|---|
+| OK | `wxID_OK` | yes — `AcceptAndClose()` → `EndDialog(wxID_OK)` (affirmative id) |
+| Cancel | `wxID_CANCEL` | yes — `EndDialog(wxID_CANCEL)` |
+| Apply, Confirm | `wxID_APPLY` (both) | no — `Validate()` + `TransferDataFromWindow()` only |
+| Yes, No, Save, Delete, … | `wxID_YES`, `wxID_NO`, `wxID_SAVE`, `wxID_DELETE`, … | no |
+| anything unknown | auto id | no — fetch with `GetButtonFromLabel(_L("…"))` or `GetButtonFromIndex(i)` |
+
+Getters (`GetOK`, `GetCANCEL`, …), the full label → id map, and how the primary (Confirm-styled) and alert
+buttons are chosen — in numeric id order, so `{"Save", "OK"}` makes Save primary — are in
+`references/orca-widgets.md §DialogButtons`.
+
+**Pitfalls.**
+- **Rule:** Run cancel cleanup on every close path — the Cancel handler *and* `wxEVT_CLOSE_WINDOW` (or after
+  `ShowModal()` returns, where every path ends).
+  **Why:** ESC (via `DPIAware` → `Close()`) and the close box go through `wxDialogBase::OnCloseWindow` →
+  `EndDialog(wxID_CANCEL)`; wx's button emulation needs a real `wxButton`, so an Orca Cancel button's
+  handler never runs on those paths (§6).
+- **Rule:** Bind every button whose default handling is not what you want; Yes/No/Apply/Confirm/custom
+  buttons never close by themselves, and an OK handler that does real work ends the dialog itself
+  (`EndModal(wxID_OK)`) or `Skip()`s to the default `AcceptAndClose()`.
+- **Rule:** Pass untranslated labels to `DialogButtons`.
+  ```cpp
+  // Wrong: new DialogButtons(this, {_L("OK"), _L("Cancel")});   // double translation; no stock ids in non-English UIs
+  // Right: new DialogButtons(this, {"OK", "Cancel"});
+  ```
+- **Rule:** `UpdateDlgDarkUI(this)` runs once, after every child exists; children added later are themed with
+  `UpdateDarkUIWin(child)`.
+- **Rule:** Don't create dialogs in a constructor of their parent or before the main frame is shown when MSW
+  ownership matters (§1); don't keep `CloneDialog`'s `wxYield()` loop pattern — long work goes to a job
+  (`references/threads-timers-app.md`).
+
+---
+
+## 9 Message boxes: the MsgDialog family
+
+**Rule.** Never `wxMessageBox`/`wxMessageDialog`/`wxRichMessageDialog` once the GUI exists; use the themed
+replacements in `src/slic3r/GUI/MsgDialog.hpp` (`Slic3r::GUI`), rooted in `MsgDialog : DPIDialog` (logo on the
+left, content on the right, `Button` row underneath, dark-mode and DPI aware). Why: on MSW the TaskDialog-based
+native boxes (`wxMessageBox`, `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`) ignore dark mode
+(`interface/wx/app.h:1436-1446`), and native boxes cannot match Orca's look. `wxMessageBox` remains only for
+failures before the GUI exists (e.g. `GUI_App::load_language`). Native message-box style limits:
+`references/strings-i18n-files.md`. Return-value trap when reading old code: `wxMessageBox()` returns
+`wxYES/wxNO/wxCANCEL/wxOK/wxHELP`, while `ShowModal()` returns `wxID_YES/…` (`interface/wx/msgdlg.h:269-276` vs `309-311`).
+
+| Class | Constructor | Notes |
+|---|---|---|
+| `MessageDialog` | `(parent, message, caption = "", style = wxOK, forward_str = "", link_text = "", link_callback = nullptr)` | default choice; first four parameters match `wxMessageDialog` (style `wxOK`, `wxCANCEL`, `wxYES_NO`, `wxICON_*`); empty caption → "<app> info" |
+| `RichMessageDialog` | `(parent, message, caption = "", style = wxOK)` | adds `ShowCheckBox(text, checked)` / `IsCheckBoxChecked()` (a "Don't show again" check box added in its `ShowModal()`); its `SetYesNoLabels`/`SetYesNoCancelLabels`/`SetOKLabel`/`SetOKCancelLabels`/`SetHelpLabel` only store strings and never relabel a button |
+| `WarningDialog` | `(parent, message, caption = "", style = wxOK)` | empty caption → "<app> warning" |
+| `ErrorDialog` | `(parent, msg, has_code_excerpts)` | caption "<app> error"; `has_code_excerpts` renders source/caret line pairs monospaced (placeholder-parser errors) |
+| `InfoDialog` | `(parent, title, msg, is_marked = false, style = wxOK | wxICON_INFORMATION)` | caption is always "<app> information"; `title` is passed as the base's headline, which is not displayed |
+| `DeleteConfirmDialog` | `(parent, title, msg)` | a plain `DPIDialog`, not a `MsgDialog`: Delete → `wxID_OK`, Cancel → `wxID_CANCEL` |
+
+`DownloadDialog` and `FilamentWarningDialog` are single-purpose `MsgDialog` subclasses; read their
+constructors before reusing them.
+
+**Behaviour** (`MsgDialog.cpp`):
+- Window style is always `wxDEFAULT_DIALOG_STYLE`; the `style` argument only selects buttons and icon. A NULL
+  parent becomes `wxGetApp().mainframe`.
+- `MsgDialog::apply_style`: `wxOK` → OK, `wxYES` → Yes, `wxNO` → No, `wxCANCEL` → Cancel; Orca's use of
+  `wxFORWARD` adds a "Go to <forward_str>" button and turns OK into "Later" (`wxID_CANCEL`). Every button's
+  handler is `EndModal(btn_id)`, so compare with `wxID_OK/wxID_YES/wxID_NO/wxID_CANCEL` — and with
+  `wxFORWARD` (the style bit `0x2000`, used as the button id) for "Go to". OK/Yes/Go-to are Confirm-styled and
+  focused; `wxNO_DEFAULT`, `wxCANCEL_DEFAULT`, `wxHELP` and `wxSTAY_ON_TOP` are ignored.
+- Icon from the style: `wxAPPLY` → "completed", `wxICON_WARNING` → "exclamation", `wxICON_INFORMATION` →
+  "info", `wxICON_QUESTION` → "question", otherwise the app logo; `wxICON_ERROR` greys it.
+- ESC and the close box return `wxID_CANCEL` whatever the buttons (§7).
+- Content (`add_msg_content`): plain text → a wrapped `Label` in a scrolled window, so `&` is a mnemonic —
+  escape user text (`references/strings-i18n-files.md`); with `link_text`/`link_callback`, `is_marked`,
+  code excerpts, or a message containing `<tr>` → a `wxHtmlWindow` with the text `xml_escape`d (`is_marked`
+  keeps `<`/`>` so markup works) and `\n` → `<br>`.
+- Base helpers: `SetButtonLabel(wxID_*, label, set_focus = false)` relabels a created button;
+  `AddButton(id, label, set_focus = false)` appends a choice button that also ends with `EndModal(id)`;
+  `show_dsa_button(title = {})` adds a "Don't show again" `CheckBox` that posts `EVT_CHECKBOX_CHANGE`
+  (int = checked) to the dialog; `get_checkbox_state()`.
+- `finalize()` (called by each subclass constructor): `SetSizeHints`, `Layout`, `Fit`, `CenterOnParent`,
+  `UpdateDlgDarkUI` — the recipe of §8 in one call; a custom `MsgDialog` subclass ends its constructor with it.
+
+**Free helpers** (`GUI.hpp`): `show_error(parent, msg, has_code_excerpts = false)` is **asynchronous** — it
+shows an `ErrorDialog` from `wxGetApp().CallAfter`, capturing the raw `parent`; `show_info(parent, msg,
+title)` and `warning_catcher(parent, msg)` are synchronous `MessageDialog`s. The `const char*`/`std::string`
+overloads decode UTF-8.
+
+**Pitfalls.**
+- **Rule:** Relabel buttons with `SetButtonLabel`, not the `RichMessageDialog::Set*Labels` methods.
+  ```cpp
+  // Wrong: dlg.SetYesNoLabels(_L("Discard"), _L("Keep"));        // stored, never shown
+  // Right: dlg.SetButtonLabel(wxID_YES, _L("Discard")); dlg.SetButtonLabel(wxID_NO, _L("Keep"));
+  ```
+- **Rule:** Test for the positive answer; everything else (No, Cancel, ESC, close box) is "no".
+  ```cpp
+  // Wrong: if (dlg.ShowModal() != wxID_NO) discard();
+  // Right: if (dlg.ShowModal() == wxID_YES) discard();
+  ```
+- **Rule:** Never compare a `MsgDialog` result with `wxYES`/`wxOK` (style bits), except `wxFORWARD` for "Go to".
+- **Rule:** Give `show_error` a parent that outlives the deferred call (the main frame, or `nullptr`, which
+  `MsgDialog` maps to it), not a dialog that may close first; don't rely on the error being visible when
+  `show_error` returns.
+
+---
+
+## 10 Overlay frames: BaseTransparentDPIFrame
+
+`BaseTransparentDPIFrame : DPIFrame` (`BaseTransparentDPIFrame.hpp/.cpp`) is the base for small
+semi-transparent prompt frames (text, OK/Cancel `Button`s, optional timed fade-out via
+`DisappearanceMode::TimedDisappearance`). Its lifetime design:
+- Parent is always `wxGetApp().mainframe`; borderless.
+- `wxEVT_CLOSE_WINDOW` → `on_hide()` on every close, forced or not (it neither vetoes nor destroys): stop
+  the refresh timer, `Hide()`, then restore the main frame with
+  `if (!mainframe->IsShown()) mainframe->Show(); mainframe->Raise();` (§4, dd8cb89f6d). The frame is reused;
+  it is destroyed only through `on_close()` → `Destroy()`, or with the main frame.
+- `Show(bool)` override starts/stops the refresh timer; `on_full_screen` adds `wxSTAY_ON_TOP` on macOS so the
+  overlay stays above a full-screen main window.
+
+When writing a similar overlay: keep the restore rule; give a close handler that respects `CanVeto()` if the
+frame can outlive its owner; own the timer as a member (`wxTimer m_timer{this}`) rather than a heap
+`new wxTimer()` that is never deleted; write the style as `wxBORDER_NONE` (not `!wxCAPTION | …`, §5).

.claude/skills/orca-wxwidgets/references/wx-33-changes.md

@@ -0,0 +1,675 @@
+# wx 3.1.5 → 3.3.2: changes Orca code can trip on
+
+OrcaSlicer moved from wxWidgets **3.1.5** to **3.3.2** (8248b06337, #12941). This file digests the
+changes between those versions that matter to GUI code — the 3.1.6–3.2.0 incompatible changes, the
+3.3 incompatible changes, and the notable 3.3.0/3.3.1/3.3.2 changes — each with what it means for
+Orca, plus the migration already done in Orca as rules for new code. Read it when code written
+from older wx knowledge behaves oddly, when a wx doc says "since 3.3", or when reviewing code near
+the workarounds in §8. Where this file and prior wx knowledge disagree, this file wins.
+
+Contents: [Rules](#rules) · [1 Reading the change logs](#1-reading-the-change-logs) ·
+[2 3.1.6 → 3.2.0](#2-changes-from-316-to-320) · [3 3.3 behaviour changes](#3-33-behaviour-changes-that-compile) ·
+[4 3.3 build changes](#4-33-changes-that-break-the-build) · [5 3.3.0](#5-330-notable-changes) ·
+[6 3.3.1](#6-331-notable-fixes) · [7 3.3.2](#7-332-notable-changes) ·
+[8 Migration done in Orca](#8-migration-already-done-in-orca)
+
+All `docs/`, `interface/`, `include/`, `src/`, `build/` cites are relative to the pinned wx tree
+(`find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets'`), except paths
+explicitly called Orca's (`deps/…`, Orca's `src/CMakeLists.txt`) and bare Orca file + symbol cites.
+
+## Rules
+
+1. Read every "now asserts" in the change logs as "now silently returns or does nothing" in Orca:
+   wx asserts are compiled out. Validate arguments yourself. → [§1](#1-reading-the-change-logs)
+2. Target 3.3.2 only. Do not add `wxCHECK_VERSION` / `wxVERSION_NUMBER` /
+   `wxVERSION_EQUAL_OR_GREATER_THAN` branches for older wx. → [§8](#8-migration-already-done-in-orca)
+3. Mark every override of a wx virtual `override`. 3.2/3.3 changed parameter types (`wxBitmapBundle`,
+   `wxReadOnlyDC`, `wxWindowBase*`, `wxVersionContext`); a stale signature must fail to compile, not
+   become a silent overload. → [§4](#4-33-changes-that-break-the-build)
+4. Call `Show()` before `Raise()` on a window that may be hidden, guarded by `!IsShown()` (a redundant
+   `Show()` is not inert on GTK3). → [§3](#3-33-behaviour-changes-that-compile)
+5. Never call `SetLabel`/`SetLabelText` on a `wxTextCtrl`; use `ChangeValue` (quiet) or `SetValue`.
+   → [§3](#3-33-behaviour-changes-that-compile)
+6. Do not use `wxTRANSPARENT_WINDOW` (it is `0`). Give the panel an explicit background colour, or set
+   `wxBG_STYLE_TRANSPARENT` before `Create()`. → [§3](#3-33-behaviour-changes-that-compile)
+7. Decide Orca's theme with `GUI_App::dark_mode()`, never `wxSystemAppearance::IsDark()` or
+   `SelectLightDark()` (on MSW they report the OS app mode); ask about the OS with `AreAppsDark()` /
+   `IsSystemDark()`. → [§3](#3-33-behaviour-changes-that-compile)
+8. Request multisampling explicitly (`.SampleBuffers(1).Samplers(4)` or `WX_GL_SAMPLE_BUFFERS` +
+   `WX_GL_SAMPLES`); `wxGLAttributes::Defaults()` no longer includes it. → [§3](#3-33-behaviour-changes-that-compile)
+9. Size a `wxImageList` in physical pixels (the bitmaps' `GetSize()`), or use the `wxBitmapBundle`
+   image APIs. → [§3](#3-33-behaviour-changes-that-compile)
+10. Return translated strings as `wxString` by value. → [§3](#3-33-behaviour-changes-that-compile)
+11. Escape `&` in user text used as a control label or book page title. → [§3](#3-33-behaviour-changes-that-compile)
+12. `wxDynamicCast` only on a pointer whose static type derives from `wxObject`; use `dynamic_cast`
+    for mixin interfaces (`wxComboPopup`, `wxItemContainer`, `wxTextEntry`). → [§4](#4-33-changes-that-break-the-build)
+13. Build a `wxArrayString` with `Add()` or an initializer list, walk wx lists with
+    `compatibility_iterator` or range-for, and make a `wxString` the first operand of a mixed
+    `+` chain. → [§4](#4-33-changes-that-break-the-build)
+14. MSW windows are not double-buffered by default in 3.3.2; a custom-painted control buffers itself.
+    → [§5](#5-330-notable-changes)
+15. `wxEVT_DPI_CHANGED` now fires on GTK3 too; such handlers must be correct on GTK, and every handler
+    you bind calls `Skip()` (`DPIAware`'s own is the one exception). → [§5](#5-330-notable-changes)
+16. wx MSW dark mode cannot be switched at runtime; do not replace Orca's NppDarkMode with it without
+    keeping live theme switching. → [§5](#5-330-notable-changes)
+17. After `wxStaticText::SetLabel`, re-wrap with `Wrap(-1); Wrap(w);` (or use `Label`); `wxST_WRAP`
+    is opt-in and works only inside a sizer. → [§7](#7-332-notable-changes)
+18. On Linux/X11 call `wxGLCanvas::PreferGLX()` before any GL use; on Unix set a swap interval explicitly
+    if frame pacing matters (wx forces 0). → [§7](#7-332-notable-changes)
+19. Compare `wxGrid::GetSelectedBlocks()` `begin()` with `end()` before dereferencing.
+    → [§8](#8-migration-already-done-in-orca)
+20. Keep the post-upgrade workarounds (MainFrame `WS_CAPTION` masking, macOS deep-link handler,
+    `MSWEnableDarkMode` ordering, `SidePopup` anchoring, MSW `GLCanvas3D::on_paint` render) when
+    touching that code. → [§8](#8-migration-already-done-in-orca)
+
+## 1 Reading the change logs
+
+**Sources.** `docs/changes.txt` lists changes since 3.2: incompatible behaviour changes :11-146,
+build-breaking changes :149-252, 3.3.2 :255-330, 3.3.1 :333-377, 3.3.0 :380-622.
+`docs/changes_32.txt` covers 3.x → 3.2.0: the cumulative "INCOMPATIBLE CHANGES SINCE 3.0.x" list
+:9-233, 3.2.0 :235-276, 3.1.7 :279-340, 3.1.6 :343-444. wxQt, wxiOS, wxUniv, wxMotif and wxGTK1
+items are left out here.
+
+**Coverage gaps.**
+- The "since 3.0.x" list in `changes_32.txt` is cumulative over all of 3.1.x. Most of it was already
+  in force in 3.1.5; §2.1 lists only what was added after 3.1.5, §2.3 the older items worth knowing.
+- `changes_32.txt` in this tree stops at 3.2.0. The 3.2.1–3.2.10 maintenance fixes are not listed
+  anywhere in the tree.
+- 3.3.0's list is relative to 3.2.8 (`changes.txt:383`). 3.3.2's list is relative to 3.2.10, and the
+  full set of changes since 3.3.1 *also includes* the 3.2.9 and 3.2.10 fixes, which are **not**
+  listed in this file (`changes.txt:258-259`).
+
+**"Asserts" mean silence in Orca.** wx is built with `-DwxBUILD_DEBUG_LEVEL=0`
+(`deps/wxWidgets/wxWidgets.cmake` → `build/cmake/init.cmake:245-246`), and `libslic3r_gui` gets
+`-DwxDEBUG_LEVEL=0` when `SLIC3R_STATIC` (Orca's `src/slic3r/CMakeLists.txt`). At level 0 `wxASSERT`,
+`wxASSERT_MSG`, `wxFAIL` and `wxFAIL_MSG` expand to nothing (`include/wx/debug.h:314-324`), while
+`wxCHECK*` still test the condition and return early, but silently (`include/wx/debug.h:342-368`).
+Every "now asserts" item below is, in Orca, either a silent early return (`wxCHECK`) or carrying on
+with bad state (`wxASSERT`). Nothing ever shows a dialog.
+
+**Build configuration that decides which changes bite** (generated `wx/setup.h` in the wx build
+directory, `dep_wxWidgets-build/lib/wx/include/<toolkit>-unicode-static-3.3/wx/setup.h`, plus
+`deps/wxWidgets/wxWidgets.cmake`):
+
+| Setting | Orca value | Consequence |
+|---|---|---|
+| Linux toolkit | GTK3 (`option(DEP_WX_GTK3 … ON)` in Orca's `deps/CMakeLists.txt`, `SLIC3R_GTK` "3"; Flatpak gtk3) | GTK3 items apply; GTK2 is only the `-DDEP_WX_GTK3=OFF` opt-out |
+| `WXWIN_COMPATIBILITY_3_0` / `_3_2` | `0` / `1` | 3.0-deprecated API is gone, 3.2-deprecated still compiles |
+| `wxUSE_STD_CONTAINERS` | `1` | wx containers are std-like; `wxList::Node` and `wxArrayString(n, s)` are gone (§4) |
+| `wxUSE_STD_STRING_CONV_IN_WXSTRING` / `wxUSE_UNSAFE_WXSTRING_CONV` | `0` / `1` | no implicit `wxString` → `std::string`; use `into_u8` / `ToStdString` |
+| `wxUSE_NANOSVG` / `wxUSE_LUNASVG` | `0` / `0` | `wxHAS_SVG` undefined: no `wxBitmapBundle::FromSVG*`; Orca rasterises SVG itself |
+| `wxUSE_STC` | `OFF` | Scintilla items do not apply |
+| `wxUSE_LIBWEBP` | `builtin` (Flatpak: `sys`) | WebP decodes through `wxImage` (§5) |
+| `wxUSE_WEBVIEW_EDGE` | MSVC only, IE off | Edge items apply on Windows only; Chromium backend not built |
+| `wxUSE_GLCANVAS_EGL` | `ON` | effective only on GTK3 with EGL found |
+
+## 2 Changes from 3.1.6 to 3.2.0
+
+### 2.1 Incompatible changes new since 3.1.5
+
+These entries of `changes_32.txt` "INCOMPATIBLE CHANGES SINCE 3.0.x" were not in 3.1.5's list, plus
+the 3.1.7-specific section.
+
+| Change | Cite (`changes_32.txt`) | Orca relevance |
+|---|---|---|
+| `wxRegEx` uses PCRE; `wxRE_ADVANCED` syntax is now PCRE syntax, `wxRE_BASIC` is deprecated, POSIX classes `[:XXXX:]` fail to compile | :15-17; `interface/wx/regex.h:95, 148-201` | Orca uses `wxRegEx` for simple patterns (e.g. `TroubleshootDialog`); write new patterns in PCRE syntax |
+| `wxSpinCtrlDouble::SetValue(wxString)` with invalid text resets to `GetMin()` | :126-127 | raw spin controls only; Orca's `SpinInput` is custom |
+| `wxSpinCtrl::SetValue(wxString)` sends no events on MSW (as documented) | :129-130 | do not rely on setter events (`controls-dataview.md`) |
+| `wxButton::GetBitmap{Current,Disabled,Focus,Pressed}()` return a valid bitmap on MSW only if set | :132-134 | check `IsOk()` |
+| `wxFileName::GetVolume()` returns `\\share` for UNC paths and `\\?\Volume{GUID}` for GUID paths | :136-140 | path code comparing volumes |
+| `wxBitmapComboBoxBase::SetItemBitmap()` takes `wxBitmapBundle` | :152-153 | the bundle change also retyped `OnAddBitmap` (5f365b5c6b, §8) |
+| MSW also links `oleacc` (3.1.5 already needed `shlwapi`, `uxtheme`, `version`) | :158-163 | automatic with MSVC |
+| Xcode projects drop i386, add arm64 | :205-207 | none (CMake build) |
+| `wxImage` ctor from XPM data is `explicit` | :225-226 | write `wxImage(xpm)` |
+| `wxWindow::DoGetBorderSize()` removed | :228-229 | use `GetWindowBorderSize()` |
+| MSVC 7 unsupported | :231-232 | none |
+| 3.1.7: `wxImageFileProperty` members and internal `wxPropertyGridPageState` functions removed | :282-290 | no propgrid in Orca's own code (only the `wxInspector` dev dependency links it, on MSW/macOS) |
+
+### 2.2 New APIs and behaviour in 3.1.6–3.2.0
+
+| Change | Cite | Orca relevance |
+|---|---|---|
+| `wxBitmapBundle` added and used "throughout the entire API" (3.1.6) | `changes_32.txt:366` | setters take bundles (`wxBitmap` converts implicitly); **overrides** of virtuals that took `wxBitmap` break (5f365b5c6b). Bundles and sizing: `dpi-bitmaps-fonts.md` |
+| Bitmap logical/DIP API: `CreateWithDIPSize` (3.1.6), `CreateWithLogicalSize` (3.3.0), `GetLogicalSize`; `CreateScaled` and `GetScaledSize/Width/Height` are "older synonyms … use the new function in the new code" | `interface/wx/bitmap.h:514, 551, 563-579, 706, 770-787` | new code uses the new names; Orca's older call sites (`BitmapCache`, `ScalableBitmap`) still compile |
+| `wxDC::GetContentScaleFactor()` returns the effective DPI factor for window DCs (e.g. 1.5 on MSW), unlike `wxWindow::GetContentScaleFactor()` (always 1 on MSW), "since wxWidgets 3.1.6" | `interface/wx/dc.h:153-168` | do not divide bitmap sizes by the DC scale (`painting-custom-widgets.md`) |
+| `wxDPIChangedEvent::Scale()` (3.1.6) | `changes_32.txt:372` | convenience for rescaling stored sizes |
+| MSW: TLW resizing on DPI change improved and overridable — a handler that sizes the TLW itself does not `Skip()` (3.2.0) | `changes_32.txt:269`; `interface/wx/event.h` (`wxDPIChangedEvent`) | Orca's `DPIAware` handler does not `Skip()` (`dpi-bitmaps-fonts.md`) |
+| `wxUILocale` (3.1.6); `wxLocale::IsAvailable` is now implemented through it | `changes_32.txt:348`; `src/common/intl.cpp:740-781` | see `wxUILocale::IsSupported` in §3 |
+| `wxWebView::RunScriptAsync()` (3.1.6) | `changes_32.txt:382` | `webview-gl-aui-media.md` |
+| wxOSX: "Allow user input in `wxPopupTransientWindow`" (3.1.7) — the popup's child holds mouse capture while the cursor is outside it and releases it inside, toggled from `OnIdle` [source] | `changes_32.txt:334`; `src/common/popupcmn.cpp:438-471` | how wxOSX transient popups track the mouse; the macOS gap-dismissal worked around in `SidePopup::Popup` is not traced to a specific wx change (§8; `popups-menus.md`) |
+| wxGTK: Wayland fixes (3.1.6), no GDK errors from `PopupMenu()` on Wayland (3.1.7), `wxCURSOR_SIZING` on Wayland (3.2.0) | `changes_32.txt:397, 317, 261` | `platforms.md` |
+| MSW: all native modal dialogs are app-modal (3.1.6) | `changes_32.txt:409` | `windows-dialogs.md` |
+| Also new: `wxKeyEvent::IsAutoRepeat()`, `wxSpinCtrl::GetTextValue()/SetIncrement()`, `wxTopLevelWindow::SetContentProtection()`, `wxEVT_SPLITTER_SASH_POS_RESIZE`, OSX full-screen view options, OSX `wxEVT_CHAR` from `wxDataViewCtrl` | `changes_32.txt:364-436` | available API |
+
+### 2.3 Older 3.x changes that still trip prior knowledge
+
+These were already in force in 3.1.5, so the upgrade did not change them, but code written from
+3.0-era knowledge gets them wrong (`changes_32.txt` line):
+
+| Contract | Line |
+|---|---|
+| MSW `wxYield()` generates `wxEVT_IDLE` (idle handlers can run inside a yield) | :25-27 |
+| A 0-width or 0-height `wxBitmap` fails on every port | :29-30 |
+| Invalid sizer flags assert (silent in Orca; `sizers-layout.md`) | :32-37 |
+| `Validate()`/`TransferData*Window()` recurse into children by default (`wxWS_EX_VALIDATE_RECURSIVELY`) | :39-41 |
+| MSW: call `Skip()` in `wxEVT_KEY_DOWN`/`wxEVT_CHAR` handlers, or system keys such as Alt+Space and Alt+F4 stop working | :54-57 |
+| MSW dotted/dashed pens are high quality and slow; `wxPenInfo::LowQuality()` | :59-62 |
+| `wxEVT_AUINOTEBOOK_PAGE_CHANGED` comes after the change | :68-69 |
+| Generic `wxDataViewCtrl` stretches its last column | :76-77 |
+| GTK `wxNotebook::AddPage()` sends no event for the first page; GTK `wxTextCtrl` sends no `wxEVT_TEXT` at creation | :79-83 |
+| `wxDC::GetTextExtent("")` height is 0 on every port | :85-86 |
+| `wxTE_PROCESS_ENTER` is required for `wxEVT_TEXT_ENTER`, even multi-line | :96-99 |
+| `wxGLCanvas` uses physical pixels on GTK3/macOS: multiply `GetSize()` by `GetContentScaleFactor()` (Orca: `RetinaHelper::get_scale_factor`, GTK3 variant in `GLCanvas3D.cpp`) | :101-104 |
+| `wxSizer::RecalcSizes()` is not to be called; call `Layout()` | :116-117 |
+| `wxFileDialog::GetPath()/GetFilename()` assert and return empty with `wxFD_MULTIPLE` | :119-120 |
+| `wxChoice::GetString()` asserts on an invalid index | :124 |
+| Application code cannot construct `wxPaintEvent` | :165-167 |
+
+## 3 3.3 behaviour changes that compile
+
+`changes.txt` "Changes in behaviour not resulting in compilation errors" (:11-146). Each row: the
+change, its line, and what it means for Orca.
+
+| Change | Line | Orca relevance |
+|---|---|---|
+| wxMSW needs Windows 7+ | :14-15 | drop XP/Vista assumptions (they need wx 3.2) |
+| Fatal-error exit code is 255 everywhere (was 127 with MSVC); `wxApp::SetErrorExitCode()` (virtual, `interface/wx/app.h:886`), static `SetFatalErrorExitCode()` (:922) | :17-19 | update anything (CI, crash reporting, wrapper scripts) that matches the old code |
+| `wxGLCanvas` no longer multisamples by default | :21-23 | pitfall below |
+| `wxFileConfig` on Unix defaults to XDG `~/.config/appname.conf` (old file still used; `wxCONFIG_USE_XDG`/`wxCONFIG_USE_HOME`, `MigrateLocalFile()`) | :25-29 | none: Orca uses `AppConfig`, no `wxConfig` (`strings-i18n-files.md`) |
+| `wxColourDatabase` uses CSS values; `UseScheme()` restores the old ones (`interface/wx/gdicmn.h:845, 973-996`) | :31-33 | none: stock colours (`*wxGREEN`, …) are fixed RGB (`src/common/gdicmn.cpp:789-830`) and Orca builds colours from hex/RGB. Do not build colours from names |
+| `wxAuiNotebook` default art is the new flat art; `wxAuiNativeTabArt` (or `"native"` in XRC) keeps the old look | :35-37 | none: no `wxAuiNotebook` in Orca |
+| `wxTHREAD_WAIT_DEFAULT` is `wxTHREAD_WAIT_BLOCK`: `wxThread::Delete()/Wait()` no longer pump events | :39-41 | Orca uses std/boost threads (`wxThread` only for `IsMain()`); a new `wxThread` whose exit needs the main loop would deadlock |
+| `wxDocument::OnCloseDocument()` runs once, after the views are destroyed (it used to run twice when the document was closed from the menu); an override must not rely on any view existing | :43-46 | none: no doc/view |
+| `wxGrid::FreezeTo()` asserts on out-of-range counts, and freezes even when the grid is too small | :48-51 | silent `false` in Orca; it also refuses reordered or drag-movable rows/columns [source] (`src/generic/grid.cpp:5742-5750`). Clamp arguments (`controls-dataview.md`) |
+| Invalid `wxImageList` calls assert | :53-56 | silent in Orca; `wxCHECK` returns (generic `Add` → -1). Create the list with a valid size before use |
+| `wxTRANSPARENT_WINDOW` does nothing (`#define wxTRANSPARENT_WINDOW 0`, `include/wx/defs.h:1449`); MSW code that needs it can set `WS_EX_TRANSPARENT` | :58-60 | pitfall below; 026b105dcb |
+| MSW `wxTextDataObject::SetData()` size includes the 2-byte NUL (consistent with `GetDataSize()`); an old-style size chops the last character | :62-66 | none: Orca uses the `wxTextDataObject(text)` ctor; use `SetText()`, never `SetData()` |
+| `wxListCtrl::EditLabel()` asserts without `wxLC_EDIT_LABELS` | :68-69 | silent no-op in Orca; add the style where editing is intended |
+| MSW `wxSystemAppearance::IsDark()` reports the app's own mode; `AreAppsDark()`/`IsSystemDark()` report the OS | :71-73 | pitfall below |
+| Unix `wxUILocale::IsSupported()` no longer falls back to another region of the same language; pass just `"fr"` to accept any `fr_XX` | :75-79 | `wxLocale::IsAvailable` builds the region-qualified tag (`GetCanonicalWithRegion()`) and calls `IsSupported()` [source] (`src/common/intl.cpp:740-781`); `GUI_App::load_language` relies on it, so on Linux a language whose canonical locale (e.g. `fr_FR`) is not installed reports unavailable. Keep the fallbacks in `load_language` |
+| Deprecated `wxPGCellRenderer::DrawCaptionSelectionRect()` overload not called; override the overload taking `wxWindow*`, or enable 3.0 compatibility | :81-83 | none: no propgrid in Orca's own code |
+| `wxImageList` size is in physical pixels | :85-88 | pitfall below |
+| Mac `wxWebRequest` no longer uses persistent storage. The entry names `wxWebRequest::EnablePersistentStorage()`; the real API is `wxWebSession::EnablePersistentStorage(bool)` (`interface/wx/webrequest.h:1612-1629`; also `wxWebSessionSync`, :1835), macOS-only, before the first request | :90-92 | none: Orca uses `wxWebRequest` only for image downloads (`wxWebSession::GetDefault().CreateRequest` in `StatusPanel`, `SliceInfoPanel`, `ReleaseNote`, `DeviceErrorDialog`); network and login agents use libcurl (`Slic3r::Http`) |
+| MSW `wxBitmap::Create(size, dc)` no longer multiplies by the DC's content scale; the size is physical | :94-96 | remove compensating scaling; use `CreateWithLogicalSize` for logical sizes |
+| `wxIMAGE_QUALITY_NEAREST` has a new value and is no longer `wxIMAGE_QUALITY_NORMAL`; `NORMAL` (the `Scale`/`Rescale` default) is bilinear + box average (`interface/wx/image.h:31-67`) | :98-99 | never store or compare the enum numerically; default-quality thumbnails and icons look smoother than under 3.1.5; pass `wxIMAGE_QUALITY_NEAREST` for pixel-exact scaling |
+| `wxTextCtrl::{Save,Load}File()` treat `.rtf` as RTF | :101-104 | pass `wxTEXT_TYPE_PLAIN` to keep plain text |
+| `wxClientDC`/`wxPaintDC` offset their origin by a `wxFrame` toolbar on every port | :106-109 | none: Orca frames have no native toolbar (`BBLTopbar` is a child `wxAuiToolBar`) |
+| `wxTextCtrl::SetLabel()` does nothing and asserts on every port (MSW used to act as `SetValue`) | :111-113 | pitfall below |
+| `wxAuiGenericTabArt` subclasses (also via `wxAuiMSWTabArt`) override `DrawPageTab()`/`GetPageTabSize()` instead of `DrawTab()`/`GetTabSize()`; direct `wxAuiTabArt` subclasses still work | :115-120 | none: no Orca tab art |
+| `wxAuiNotebook` page index is logical (reorder-independent); `GetPagePosition()` gives the screen position | :122-126 | none; index math under `wxAUI_NB_TAB_MOVE` is what breaks |
+| `wxListbook`/`wxChoicebook` interpret mnemonics in page titles "just as the other wx*book classes already did" | :128-130 | Orca uses neither (`BedShapeDialog` uses `wxSimplebook` + a combo); every book interprets `&` (`interface/wx/bookctrl.h:141-147`) → rule 11 |
+| `wxAUI_MGR_HINT_FADE` is not in the default `wxAuiManager` style | :132-133 | Plater's `AuiMgr` keeps the default flags (minus `wxAUI_MGR_ALLOW_FLOATING` on Wayland, `Plater::priv::priv`), so the docking hint no longer fades; add the flag if wanted |
+| `wxPrintDialogData::SetAllPages(false)`/`SetSelection(false)` changed meaning | :135-137 | none |
+| `wxGetTranslation()` returns `wxString` by value | :139-142 | pitfall below |
+| `wxWindow::Raise()` no longer shows a hidden window on any port | :144-146 | pitfall below; ba867cc534 |
+
+**Pitfalls**
+
+- **Rule:** Request multisampling explicitly; never rely on `wxGLAttributes::Defaults()` or a null
+  attribute list for MSAA.
+  **Why:** 3.1.5's `Defaults()` was RGBA, double buffer, depth 16 plus `SampleBuffers(1).Samplers(4)`
+  on every port; 3.3's is `RGBA().Depth(16).DoubleBuffer()` (`include/wx/glcanvas.h:175-178`), also used for a null
+  attribute list (`src/common/glcmn.cpp:159-165`). The change-log line has the arguments swapped:
+  `SampleBuffers(n)` is "number of sample buffers, usually 1" and `Samplers(n)` the samples per pixel
+  (`interface/wx/glcanvas.h:233-246`). The plater canvas is unaffected:
+  `OpenGLManager::create_wxglcanvas` passes `WX_GL_SAMPLE_BUFFERS`/`WX_GL_SAMPLES` explicitly (from
+  the anti-aliasing setting). A canvas built with `.Defaults()` — the `SkipPartCanvas` that
+  `PartSkipDialog` creates — renders without MSAA.
+  ```cpp
+  // Wrong: attrs.PlatformDefaults().Defaults().Stencil(8).EndList();                 // no MSAA in 3.3
+  // Right: attrs.PlatformDefaults().Defaults().SampleBuffers(1).Samplers(4).Stencil(8).EndList();
+  ```
+  Cite: `docs/changes.txt:21-23`; `OpenGLManager::create_wxglcanvas`.
+
+- **Rule:** Use `GUI_App::dark_mode()` for "is Orca dark", and `AreAppsDark()`/`IsSystemDark()` for
+  "is the OS dark"; never `GetAppearance().IsDark()` in GUI code (it breaks on MSW, see below;
+  `colours-dark-mode.md` rule 1 forbids it on every port).
+  **Why:** `IsDark()` returns true whenever wx's own dark mode is active, else it falls back to
+  `IsUsingDarkBackground()` (`src/msw/settings.cpp:431-441`). Orca calls
+  `MSWEnableDarkMode(DarkMode_Auto)` (`DarkMode_Auto = 0`, `include/wx/msw/app.h:48`), which puts wx
+  in `AppMode_AllowDark` (`src/msw/darkmode.cpp:235-252`); from then on `IsDark()` follows the OS
+  apps setting (`ShouldUseDarkMode()`, :205-227), whatever theme the user picked in Orca.
+  `AreAppsDark()` reads `AppsUseLightTheme`, `IsSystemDark()` reads `SystemUsesLightTheme`
+  (`src/msw/settings.cpp:444-452`; `interface/wx/settings.h:307-358`). On other ports the three agree.
+  `GUI_App::dark_mode()` honours the `dark_color_mode` app-config value first and only then calls
+  `check_dark_mode()`, which still uses `IsDark()`.
+  ```cpp
+  // Wrong: bool dark = wxSystemSettings::GetAppearance().IsDark();   // OS apps setting on MSW
+  // Right: bool dark = wxGetApp().dark_mode();
+  ```
+  Cite: 8248b06337; `GUI_App::dark_mode`, `check_dark_mode` (`GUI_Utils.cpp`); `colours-dark-mode.md`.
+
+- **Rule:** `Show()` before `Raise()`, and `Show()` only if the window is hidden.
+  **Why:** "If the window is currently hidden, this function does *not* show it automatically"
+  (`interface/wx/window.h:3015-3033`). MSW already behaved so; GTK and macOS used to show it, so a
+  bring-to-front path that only raises leaves a hidden frame hidden on those ports. On GTK3 a
+  redundant `Show(true)` still runs `GTKSendSizeEventIfNeeded()` [source]
+  (`src/gtk/toplevel.cpp:1259-1269`), which froze Orca once (dd8cb89f6d), so guard it.
+  ```cpp
+  // Wrong: wxGetApp().mainframe->Raise();
+  // Right: auto* mf = wxGetApp().mainframe; if (!mf->IsShown()) mf->Show(); mf->Raise();
+  ```
+  Cite: ba867cc534 (the other-instance handlers in `Plater::priv::priv`,
+  `Plater::priv::bring_instance_forward`); `windows-dialogs.md` §4.
+
+- **Rule:** Do not use `wxTRANSPARENT_WINDOW`; give the panel the background it must blend with, or
+  set `wxBG_STYLE_TRANSPARENT` **before** `Create()`.
+  **Why:** the flag is `0`. Under 3.1.5 it set `WS_EX_TRANSPARENT` on MSW; now the panel paints its
+  own background. A `SetBackgroundStyle(wxBG_STYLE_TRANSPARENT)` call after the window exists is a
+  `wxCHECK_MSG` that returns `false` silently (`src/common/wincmn.cpp:1616-1625`), so it is no
+  replacement for the flag — 026b105dcb assumed it was.
+  ```cpp
+  // Wrong: new wxPanel(this, wxID_ANY, wxDefaultPosition, wxDefaultSize, wxTRANSPARENT_WINDOW);
+  // Right: auto p = new wxPanel(this, wxID_ANY);
+  //        p->SetBackgroundColour(StateColor::darkModeColorFor(wxColour("#3B4446")));
+  ```
+  Cite: 026b105dcb, 8248b06337 (`MainFrame::create_side_tools`, `MainFrame::update_side_button_style`
+  re-apply the colour on theme change); `painting-custom-widgets.md`.
+
+- **Rule:** Never `SetLabel`/`SetLabelText`/`GetLabel` on a `wxTextCtrl` to show or read its value.
+  **Why:** `wxTextCtrlBase::SetLabel` is only `wxFAIL_MSG("Use SetValue() or ChangeValue()
+  instead.")` (`src/common/textcmn.cpp:933-936`); `SetLabelText` calls the virtual `SetLabel`
+  (`include/wx/control.h:64-67`), and `GetLabel()` returns `m_labelOrig`, not the text
+  (`include/wx/control.h:61`). Orca compiles the assert out, so the call is a complete no-op: the
+  field never updates. Under 3.1.5 MSW it acted as `SetValue`, so code written then looked fine on
+  Windows.
+  ```cpp
+  // Wrong: m_input_ip->GetTextCtrl()->SetLabelText(m_obj->get_dev_ip());
+  // Right: m_input_ip->GetTextCtrl()->ChangeValue(m_obj->get_dev_ip());   // no wxEVT_TEXT
+  ```
+  Cite: `docs/changes.txt:111-113`; `controls-dataview.md`.
+
+- **Rule:** Size a `wxImageList` from the bitmaps' physical size, or use
+  `SetImages(std::vector<wxBitmapBundle>)`.
+  **Why:** "the size is specified in physical pixels and must correspond to the size of bitmaps, in
+  pixels" (`interface/wx/imaglist.h:62-63`). An Orca icon from `create_scaled_bitmap(name, win, 16)`
+  is larger than 16 px on HiDPI MSW, where `Add()` hands it to the native `ImageList_Add`
+  (`src/msw/imaglist.cpp:299-313`), which splits a wider bitmap into list-width images. The generic
+  list (GTK, macOS) keeps a bitmap whose scale factor is not 1 intact, but returns -1 for a narrower
+  1×-scale bitmap and chops a wider one into several list-width images [source]
+  (`src/generic/imaglist.cpp:126-160`).
+  ```cpp
+  // Wrong: m_images = new wxImageList(16, 16); m_images->Add(create_scaled_bitmap("icon", this, 16));
+  // Right: wxBitmap bmp = create_scaled_bitmap("icon", this, 16);
+  //        m_images = new wxImageList(bmp.GetWidth(), bmp.GetHeight(), false);
+  ```
+  Cite: `docs/changes.txt:85-88`; `Tab` builds its list from `bmp().GetWidth()/GetHeight()`;
+  `dpi-bitmaps-fonts.md`.
+
+- **Rule:** A function that returns a translation returns `wxString` by value.
+  **Why:** `wxGetTranslation()` returns by value now (`include/wx/translation.h:278-321`); returning
+  it as `const wxString&` dangles. Orca's `I18N::translate` overloads and `_L` already return by
+  value.
+  ```cpp
+  // Wrong: const wxString& title() { return _L("Printer"); }
+  // Right: wxString title() { return _L("Printer"); }
+  ```
+  Cite: `docs/changes.txt:139-142`; `I18N.hpp`.
+
+- **Rule:** Escape `&` in user data (preset, filament, printer, file names) shown as a control label or
+  book page title.
+  **Why:** labels and page titles interpret `&` as a mnemonic; an unescaped `&` disappears or
+  underlines the next character. 3.3 extended this to `wxListbook`/`wxChoicebook`.
+  ```cpp
+  // Wrong: book->AddPage(page, preset_name);
+  // Right: book->AddPage(page, wxControl::EscapeMnemonics(preset_name));   // or label->SetLabelText(name)
+  ```
+  Cite: `docs/changes.txt:128-130`; `interface/wx/bookctrl.h:141-147`; `controls-dataview.md`.
+
+## 4 3.3 changes that break the build
+
+`changes.txt` "Changes in behaviour which may result in build errors" (:149-252).
+
+| Change | Line | Orca relevance |
+|---|---|---|
+| 3.0-deprecated symbols disabled by default (`WXWIN_COMPATIBILITY_3_0=1` at wx build time re-enables them), 2.8-deprecated removed | :152-154 | Orca builds `WXWIN_COMPATIBILITY_3_0 0`, `_3_2 1`: port off 3.0-deprecated API |
+| `wxUSE_UNICODE=0` unsupported | :156 | none |
+| `wxUSE_STD_CONTAINERS=1` by default ("Container Classes" overview); building wx with 0 keeps the old containers | :158-161 | Orca builds with 1 → pitfall below |
+| `wxUSE_STL` gone; implicit `wxString` → `std::[w]string` only with `wxUSE_STD_STRING_CONV_IN_WXSTRING=1` at wx build time | :163-166 | Orca builds 0: convert explicitly (`into_u8`, `ToStdString`, `ToUTF8()`) |
+| MSW links `gdiplus.lib`, `msimg32.lib` | :168-172 | automatic with MSVC/wx-config; only static non-MSVC builds add them |
+| wxMotif, wxGTK1 removed | :174-175 | none |
+| Private containers (e.g. `wxSimpleDataObjectList`) removed; object arrays (`wxImageArray`) compare values in `Index()` | :177-183 | use `std::vector`/`std::list` |
+| Operators on wx types are hidden (not global) | :185-189 | pitfall below |
+| `wxString` from `std::string_view` makes `wxstr = {"Hello", 2}` ambiguous | :191-194 | write `wxString{"Hello", 2}` |
+| Generic `wxSearchCtrl` lost multi-line-only methods | :196-197 | none |
+| Wide-filename `wxOnAssert()` overload removed | :199-200 | none |
+| 64-bit DLLs carry an `x64` suffix in all build systems | :202-204 | packaging scripts matching DLL names; Orca links wx statically (Flatpak builds it shared in its own manifest) |
+| CMake config installs to `lib/cmake/wxWidgets-3.3`; plain `find_package(wxWidgets)` is unaffected, hard-coded paths break | :206-211 | Orca: `find_package(wxWidgets 3.3 CONFIG …)` on Windows/macOS, `wx-config --toolkit=gtk${SLIC3R_GTK}` on Linux (Orca's `src/CMakeLists.txt`) |
+| Memory-tracing options removed | :213-216 | use ASan |
+| `wxTEST_DIALOG()` needs a trailing `;` | :218-219 | none |
+| `wxWindow::GetDefaultBorderForControl()` not virtual | :221-223 | do not override; use `wxBORDER_THEME` |
+| GTK `wxDirButton::Create()` lost `wildcard` | :225-226 | none |
+| Several virtuals take `wxReadOnlyDC` | :228-231 | pitfall below |
+| `wxSizer::Detach()` takes `wxWindowBase*` | :233-236 | only custom sizer subclasses |
+| `wx/cursor.h` no longer includes `wx/utils.h` | :238-240 | include `<wx/utils.h>` explicitly (8248b06337 added it to `GLCanvas3D.cpp`) |
+| `wxStyledTextCtrl::AddSelection()` returns void | :242-244 | none: `wxUSE_STC=OFF` |
+| `wxColour` from `bool` no longer compiles | :246-248 | use the RGB or string ctor explicitly |
+| `wxGLCanvas::CreateSurface()` removed from EGL builds | :250-252 | none: wx chooses EGL or GLX itself (§7) |
+
+**Pitfalls**
+
+- **Rule:** Override wx measuring virtuals with `wxReadOnlyDC&` and mark them `override`.
+  **Why:** these virtuals now take `wxReadOnlyDC&` (the non-drawing base of `wxDC`, since 3.3.0,
+  `interface/wx/dc.h:115-127`): `wxRendererNative::GetCollapseButtonSize`
+  (`interface/wx/renderer.h:477`), the AUI tab and toolbar art size getters (`GetTabSize`,
+  `GetLabelSize`, `GetToolSize`, …; `interface/wx/aui/auibook.h:1186+`, `interface/wx/aui/auibar.h:648-664, 887-903`),
+  the `wxGridCellRenderer::GetPreferred{Size,Height,Width}`/`GetMaxSize` virtuals that 3.3 added
+  beside the old `wxDC&` `GetBestSize` family (`include/wx/generic/grid.h:203-251`), the new `wxScrolled::PrepareReadOnlyDC`
+  (`interface/wx/scrolwin.h:519`), and richtext/ribbon art. Nothing near `DoGetBestSize`, which takes
+  no DC. Without `override` an old `wxDC&` signature silently becomes an overload that is never
+  called; with `override` it fails to compile, which is what you want. Orca's `Widgets/` override
+  none of them; `BBLTopbarArt` overrides only `DrawBackground`/`DrawButton` (still `wxDC&`); the
+  `ObjectTable` grid renderers override the compatibility `GetBestSize(…, wxDC&, …)`, which "are the
+  ones actually called by wxGrid" (`include/wx/generic/grid.h:253-271`). Callers are unaffected; a
+  helper taking `wxDC&` cannot accept a `wxInfoDC`.
+  ```cpp
+  // Wrong: wxSize GetToolSize(wxDC& dc, wxWindow* w, const wxAuiToolBarItem& it);       // never called
+  // Right: wxSize GetToolSize(wxReadOnlyDC& dc, wxWindow* w, const wxAuiToolBarItem& it) override;
+  ```
+  Cite: `docs/changes.txt:228-231`; `painting-custom-widgets.md`.
+
+- **Rule:** With `wxUSE_STD_CONTAINERS=1`, build a `wxArrayString` with `Add()` or an initializer
+  list, and walk `WX_DECLARE_LIST` lists with `compatibility_iterator` or range-for.
+  **Why:** the std-container `wxArrayString` has no `(count, value)` ctor
+  (`include/wx/arrstr.h:64-84`), and `List::Node` no longer exists. Convert Orca's UTF-8
+  `std::string` explicitly: the implicit `wxString(const std::string&)` uses the current locale
+  (`include/wx/string.h:1323-1326`).
+  ```cpp
+  // Wrong: load_files(wxArrayString(1, wxString::FromUTF8(target_path.string())));
+  //        AmsRadioSelectorList::Node* node = m_radio_group.GetFirst();
+  // Right: wxArrayString arr; arr.Add(wxString::FromUTF8(target_path.string())); load_files(arr);
+  //        for (AmsRadioSelector* rs : m_radio_group) { ... }   // or ::compatibility_iterator
+  ```
+  Cite: 1765d296a8 (`Plater::import_model_id`, `SendMultiMachinePage::request_params`); `strings-i18n-files.md`.
+
+- **Rule:** In a concatenation, make a `wxString` the first operand when the others are `char`,
+  `wchar_t`, `std::string` or `std::wstring`.
+  **Why:** wx operators are hidden friends now, found only by argument-dependent lookup on a wx type;
+  "preventing them from implicitly being used with types convertible to wx types"
+  (`changes.txt:185-189`). `char + std::wstring + …` compiled under 3.1.5 through the global
+  `operator+(char, const wxString&)`, converting the `std::wstring` implicitly; under 3.3 that
+  operator is a hidden friend (`include/wx/string.h:2150`) and no operand is a `wxString`, so it
+  does not.
+  ```cpp
+  // Wrong: return marker_by_type(opt.type, printer_technology) + opt.category_local + sep + opt.label_local;
+  // Right: return wxString(marker_by_type(opt.type, printer_technology)) + opt.category_local + sep + opt.label_local;
+  ```
+  (`marker_by_type` returns `char`, the `*_local` labels are `std::wstring`.) Making only `sep` a
+  `wxString` (1765d296a8) did not help, because the leading `char + std::wstring` is evaluated first.
+  Cite: 1765d296a8, 2b3328c2b2 (`OptionsSearcher::search` `get_tooltip`, `Search.cpp`).
+
+- **Rule:** Use `wxDynamicCast` only on a pointer whose static type derives from `wxObject`; for
+  mixin interfaces use `dynamic_cast`.
+  **Why:** 3.3's macro casts its argument straight to `const wxObject*` [source]
+  (`include/wx/object.h:118-121`); 3.1.5 first `static_cast` it to the target class, so a
+  `wxComboPopup*` → `wxCheckListBoxComboPopup` cast used to compile. `wxComboPopup` has no `wxObject`
+  base (`include/wx/combo.h:748`), so the 3.3 cast does not compile. The same holds for
+  `wxItemContainer`, `wxTextEntry` and other non-`wxObject` mixins.
+  ```cpp
+  // Wrong: auto* p = wxDynamicCast(combo->GetPopupControl(), wxCheckListBoxComboPopup);
+  // Right: auto* p = dynamic_cast<wxCheckListBoxComboPopup*>(combo->GetPopupControl());
+  ```
+  Cite: 7ea69199fd (`combochecklist_get_flags`, `combochecklist_set_flags`, `GUI.cpp`).
+
+## 5 3.3.0 notable changes
+
+`changes.txt:380-592` (relative to 3.2.8).
+
+**Major changes** (:385-394)
+
+| Change | Orca relevance |
+|---|---|
+| Experimental MSW dark mode (#23028), with `wxApp::SetAppearance()` (#24461) | pitfall below; Orca kept NppDarkMode and only calls `MSWEnableDarkMode(DarkMode_Auto)` |
+| Chromium `wxWebView` backend (#706) and `wxEVT_WEBVIEW_CREATED` | Chromium is not built; `wxEVT_WEBVIEW_CREATED` is the documented ready signal for Edge (`webview-gl-aui-media.md`) |
+| WebP images (#25205) | Orca builds `wxUSE_LIBWEBP=builtin` and calls `wxInitAllImageHandlers()` (`GUI_App::on_init_inner`), so `wxImage` decodes WebP (e.g. downloaded thumbnails) |
+| Pinned and multi-row AUI tabs (#25187, #25076) | none: no `wxAuiNotebook` |
+| Synchronous `wxWebRequest` (#24760) | available (`wxWebSessionSync`); "must not be used from the main thread of GUI applications" (`interface/wx/webrequest.h:614-615`) |
+| Raw touch events (#17077); wxGrid accessibility (#24368) | available |
+| Unix power events and blockers (#22396, #23717) | could keep a Linux system awake during long work; Linux covers only `wxPOWER_RESOURCE_SYSTEM` and needs systemd ≥ 183 (`interface/wx/power.h:163-171`); not used by Orca |
+| Native GTK file dialogs when possible (#24486, #25104) | the portal dialog is used only with GTK ≥ 3.20 at runtime, without `wxFD_PREVIEW` and without an extra control [source] (`src/gtk/filedlg.cpp:265-273, 438-443`); Orca's `CheckboxFileDialog` (`SetExtraControlCreator`, `GUI_Utils.hpp`) therefore gets the non-native GTK dialog |
+| Native `wxTextCtrl` contents / RTF (#24626, #24912) | available (`GetRTFValue`, `SearchText`) |
+
+**All** (:398-442)
+
+| Change | Orca relevance |
+|---|---|
+| `wxWebRequest`: base URL (#24769), proxy (#24762), repeated headers (#24878); `wxWebSession::EnablePersistentStorage()` (#23743) | see §3 for storage |
+| `wxString`: move operations (#23215), `std::string_view` ctor (#23711), faster and more robust `To/FromCDouble()` (#23287), `errno` preserved (#23113), `wc_string()` (#23463), `wxWARN_UNUSED` on the class (#24833, unused-variable warnings for `wxString` locals) | settings fields do **not** parse through `ToCDouble`: `Field` normalises the decimal separator and calls `wxString::ToDouble`, and `double_to_string` uses `wxNumberFormatter::ToString`; `ToCDouble`/`FromCDouble` appear only in a few helpers (e.g. `PreferencesDialog::create_camera_orbit_mult_input`). The `wxNumberFormatter` changes (3.3.1, 3.3.2) matter more for `Field` |
+| Lambdas with `Bind()` without RTTI (#14850); move-only `wxMessageQueue` (#25026); `wxLogXXX(string)` safe with a single string (#25414) | available |
+| Environment variables use UTF-8 (#25101) | check round-tripping of non-ASCII paths through `wxGetEnv`/`wxSetEnv` |
+| Improved locale matching (#24855); thread-safe `wxPlatformInfo::Get()` (#25459); `wxXmlParseError` from `wxXmlDocument::Load()` (#24215); customisable error exit code (#24770) | available |
+
+**All (GUI)** (:444-500)
+
+| Change | Orca relevance |
+|---|---|
+| High-DPI wave: `wxCursorBundle` (#25374), animations (#23817), generic `wxListCtrl` (#22916), print preview (#24666), AUI dock art after DPI change (#23420), `wxBusyInfo` bitmaps (#23813) | AUI dock-art size metrics are DIP-like now: `wxAuiManager` reads them through `GetMetricForWindow()` (since 3.3.0), which scales them by the window DPI. The docs exempt `wxAUI_DOCKART_SASH_SIZE` and `wxAUI_DOCKART_PANE_BORDER_SIZE` (`interface/wx/aui/dockart.h:274-294`), but the default implementation exempts only `wxAUI_DOCKART_PANE_BORDER_SIZE` (and the non-pixel gradient type) and does scale the sash size [source] (`src/aui/dockart.cpp:199-226`). Pass DIP values to `SetMetric` (Plater's `SetMetric(wxAUI_DOCKART_CAPTION_SIZE, 18)`), never `FromDIP(…)` |
+| Dark-mode colours in XRC (#23571); CSS colour names (#23518) | none: no XRC, no colour names |
+| `wxTextCtrl::SearchText()` (#24756) and RTF (#24626); locale-aware date/time pickers (#23965, display format changes); `wxSearchCtrl` derives from `wxTextEntry` on all ports (#23686) | available |
+| Scintilla 5.0 / Lexilla 5.3 (#23117, #24369); nanosvg crash fixes (#24213) | none: `wxUSE_STC=OFF`, `wxUSE_NANOSVG=OFF` |
+| Better `wxImage` resizing (#25252) | default-quality scaling output differs from 3.1.5 (§3) |
+| `wxAuiManager::{Save,Load}Layout()` (#24235); `wxAuiNotebook` layout save/restore (#24950) | Orca persists docking with `SavePerspective`/`LoadPerspective` (Plater, `AuiPaneLayout`) |
+| Non-live resize restored in wxAUI and `wxSplitterWindow` (#24193) | `wxAUI_MGR_LIVE_RESIZE` is in `wxAUI_MGR_DEFAULT` since 3.3.0 (`interface/wx/aui/framemanager.h:59-66`). The style table's "always enabled in wxGTK3 and wxOSX ports as non-live resizing is not implemented in them" (:199-206) is as stale as the `AlwaysUsesLiveResize()` note: that function "always returns false" as of 3.3.0 (:345; `src/aui/framemanager.cpp:711-714`), and the flag decides on every port [source] (`HasLiveResize`, :716-719). See `webview-gl-aui-media.md` §AUI docking |
+| `wxInfoBar::ShowCheckBox()` (#25394); printing multiple page ranges (#25030); `wxGrid::CopySelection()` (#24124); new default flat AUI tab art (#25316); `wxApp::SetAppearance()` (#24461) | available |
+
+**All (WebView)** (:510-525) — `wxWebViewConfiguration` + `GetNativeConfiguration()`, `SetProxy()`,
+`ShowDevTools()`, `EnablePersistentStorage()`, `EnableBrowserAcceleratorKeys()`, clearing browsing
+data, advanced requests, child-window handling, `IsTargetMainFrame()`, Edge user agent settable after
+creation, and **Edge events queued** (#22744, #19075): Edge handlers run later than on the other
+backends. Edge posts its events with `AddPendingEvent` (script messages: `src/msw/webview_edge.cpp:811`)
+except the vetoable ones, `wxEVT_WEBVIEW_NAVIGATING` (:599) and `wxEVT_WEBVIEW_NEWWINDOW` with its
+`NEWWINDOW_FEATURES` follow-up (:723, :737), which stay synchronous; WebKit and
+WebKit2GTK deliver script messages synchronously (`src/osx/webview_webkit.mm:1360`,
+`src/gtk/webview_webkit2.cpp:408`) [source]. `webview-gl-aui-media.md` owns the details.
+
+**wxGTK** (:527-547)
+
+| Change | Orca relevance |
+|---|---|
+| `wxDPIChangedEvent` generated (#19290, #24040), GTK ≥ 3.10 (`interface/wx/event.h:3592-3593`) | pitfall below |
+| `wxGLCanvas` scale fixed with EGL/Wayland in high DPI (#23733) | Orca has no compensating hack: GTK3 `RetinaHelper::get_scale_factor` returns `GetContentScaleFactor()` |
+| `wxKeyEvent::GetKeyCode()` fixed for non-US layouts (#23379) | shortcuts match through `KeyChord::from_event` (`mouse-keyboard-focus.md`) |
+| Missing enter/leave events fixed (#24339); mouse event generation fixes (#24931-#24933) | hover logic (`StateHandler`) gets enter/leave reliably |
+| Total window size with GNOME on X11 (#25348) | TLW geometry |
+| `libwebkit2gtk-4.1` support (#23633) | wx's CMake build prefers 4.1 and falls back to 4.0 (`build/cmake/init.cmake:571-577`) |
+| `libsecret` not required at runtime (#25355) | `wxSecretStore` loads it on demand: always check `IsOk()` (`interface/wx/secretstore.h:197-201`), as `OrcaCloudServiceAgent` does |
+| Multi-line `wxTextCtrl` max length (#24751); `wxRB_SINGLE` (#23652); `GTKSetPangoMarkup()` (#24912) | `controls-dataview.md` |
+| `wxDC::DrawRoundedRectangle()` radius limited to half the smaller side (#24327) | the clamp is in the GTK2 GDK DC (`src/gtk/dcclient.cpp:874-875`, built only in the GTK2 opt-out, `GTK2_LOWLEVEL_SRC` in `build/files`) and also in the common `wxGraphicsPathData::AddRoundedRectangle` (`src/common/graphcmn.cpp:439-440`, absent in 3.1.5) that `wxGraphicsContext::DrawRoundedRectangle` uses, so every `wxGCDC` clamps: GTK3 (Cairo) and macOS window DCs, and Orca's memory-DC + `wxGCDC` paint paths on all ports [source]. A radius larger than half the smaller side is now clamped instead of drawing overlapping arcs |
+| Read-only `wxBitmapComboBox` height fixed (#25468) | `Slic3r::GUI::BitmapComboBox` on GTK |
+
+**wxMSW** (:549-583)
+
+| Change | Orca relevance |
+|---|---|
+| "Enable double buffering for all windows" (#22851) | **reverted in 3.3.2** (#25808) → pitfall below |
+| `wxOverlay` reimplemented with layered windows (#23261) | none: no `wxOverlay` |
+| `wxBG_STYLE_TRANSPARENT` implemented (#23412) | as `WS_EX_TRANSPARENT` on non-TLW children [source] (`src/msw/window.cpp:1581-1582`); set before `Create()` (`painting-custom-widgets.md`) |
+| `wxCAPTION` turned on when min/max/close boxes are set (#23575) | `WS_CAPTION` is added to the style (`src/msw/toplevel.cpp:132-135`); origin of the MainFrame workaround (§8) |
+| `wxButton` default size larger in high DPI (#25297) | raw `wxButton` layouts may grow; Orca dialogs use `Button`/`DialogButtons` |
+| Markup in `wxStaticText` (#25000); `wxHyperlinkCtrl` colour changeable (#23549) | `SetLabelMarkup` now works on MSW (single line) |
+| Extended-length paths (#25033); `wxFileDialog` no unwanted extension (#24949); UTF-8 build fixes (#23313); non-BMP strings (#25128) | available |
+| `wxDisplay` invalidated on display change (#25396); TLW with one child resized on DPI change (#22983); Aero-snapped geometry saved | multi-monitor geometry |
+| Modern default `wxTreeCtrl` look (#23844); RTL fixes for `wxOverlay`/`wxScrolled` (#25413) and GDI+ (#25431); `wxBitmap::UseAlpha()` returns `bool` (#23919) | available |
+
+**wxOSX** (:585-592) — `wxEventLoop::OnExit()` is always called (#25409); TLW cursor setting fixed
+(#25131); Cmd-C no longer activates a "Close" button (#25346); `wxCursor` loadable from resources
+(#24374); `wxUIActionSimulator` works (#23692), usable for GUI tests.
+
+**Pitfalls**
+
+- **Rule:** Do not replace Orca's MSW dark mode with wx's (`SetAppearance`/`MSWEnableDarkMode`)
+  unless live theme switching is kept.
+  **Why:** wx's MSW dark mode cannot change once any top-level window exists or a mode was chosen:
+  `SetAppearance` returns `CannotChange` (`src/msw/darkmode.cpp:263-270`;
+  `interface/wx/app.h:1166-1173`). TaskDialog-based dialogs (`wxMessageDialog`, `wxProgressDialog`,
+  simple `wxAboutBox`), the common dialogs (colour, find/replace, font, page setup, print) and the
+  date/time/calendar controls stay light (`interface/wx/app.h:1434-1448`). Orca switches themes at
+  runtime, which is why 8248b06337 kept NppDarkMode and only informs wx with
+  `MSWEnableDarkMode(DarkMode_Auto)` (§8).
+  Cite: 8248b06337 (PR text); `colours-dark-mode.md`.
+
+- **Rule:** On MSW, a custom-painted control buffers its own drawing (`wxAutoBufferedPaintDC`/
+  `wxBufferedPaintDC` with `wxBG_STYLE_PAINT`, or the Orca memory-DC + `wxGCDC` path), or calls
+  `SetDoubleBuffered(true)` after creation.
+  **Why:** 3.3.0's global `WS_EX_COMPOSITED` was reverted in 3.3.2 (`changes.txt:308`). In 3.3.2
+  nothing sets it except an explicit `SetDoubleBuffered(true)` [source] (`src/msw/window.cpp:4704-4721`;
+  the only other use is `MSWDisableComposited`, :1643-1652), so MSW windows are not double-buffered by
+  default, exactly as in 3.1.5. `wxAutoBufferedPaintDC` is a `wxBufferedPaintDC` on MSW at compile
+  time (`include/wx/dcbuffer.h:18-23, 215-221`). Nothing tuned against 3.3.0/3.3.1 applies.
+  Cite: `docs/changes.txt:308, 557`; `painting-custom-widgets.md`.
+
+- **Rule:** A `wxEVT_DPI_CHANGED` handler must be correct on GTK3, and every handler you bind — on a
+  child, a control or a `DPIDialog`/`DPIFrame` — calls `Skip()`.
+  **Why:** wxGTK3 now emits the event from `wxTopLevelWindowGTK::GTKConfigureEvent` when the integer
+  content scale changes, with DPI = 96 × scale [source] (`src/gtk/toplevel.cpp:336-351`;
+  `src/common/wincmn.cpp:2828-2830`). The event reaches each top-level window and its children
+  recursively, and the docs say handlers "should almost always call `event.Skip()`"
+  (`interface/wx/event.h:3564-3582`). Orca's `DPIAware` binds it on every non-macOS port and does
+  not `Skip()`; it sets `m_scale_factor` from that DPI although GTK3 pixels are already DIPs (the
+  ctor starts at 1 because `get_dpi_for_window` returns 96 on Linux). Double scaling when a window moves between monitors of
+  different scale is a risk that has not been verified at runtime; test DPI changes on GTK when
+  touching `DPIAware::rescale` paths.
+  Cite: `docs/changes.txt:541`; `dpi-bitmaps-fonts.md` §wxEVT_DPI_CHANGED.
+
+## 6 3.3.1 notable fixes
+
+`changes.txt:333-377`.
+
+| Port | Change | Orca relevance |
+|---|---|---|
+| All | Persistence for `wxCheckBox` (#25515) and `wxRadioButton` groups (#25530); `wxAuiPaneInfo::FloatingClientSize()` (#25483); PNG "Description" chunk (#25556) | available |
+| All | Settable app id (#25548): `wxAppConsole::SetClassName()` — the Windows AppUserModelID and the Wayland `app_id` (wxGTK ≥ 3.24.22), unused elsewhere; call it before any TLW, typically in the app ctor; on Windows it also changes shell behaviour (shift-middle-click new instance, shell MRU) (`interface/wx/app.h:760-812`) | Orca calls only `SetAppName`; setting a class name would change Windows taskbar grouping and jump lists |
+| All | `wxDataViewCtrl::Collapse()` safe from event handlers (#25631); no `wxEVT_GRID_SELECT_CELL` at `wxGrid` creation (#25498); empty `wxGridSizer` no longer asserts (#25641); `wxPropertyGrid` compatibility (#25627); `wxNumberFormatter` (#25614, #25635); reproducible static Unix builds (#25502) | `ObjectList`/`ObjectGrid` event handlers; `Field` number formatting |
+| wxGTK | Crash sorting a `wxDataViewCtrl` with a single leaf (#25625); `wxListCtrl` contents lost after `AppendColumn()` (#25519) | native GTK `wxDataViewCtrl` |
+| wxMSW | Dark-mode fixes: disabled `wxButton` bitmaps (#25575), disabled `wxStaticText` (#25574), `wxComboCtrl` (#23766), `wxTE_RICH` `wxTextCtrl` (#25602), selected toolbar buttons (#25616), `wxStaticBitmap` in `wxNotebook` crash (#25499), notebook background in high-contrast (#25542) | apply only where wx's own dark mode is active (`wxMSWDarkMode::IsActive()`; with Orca's `DarkMode_Auto`, whenever `ShouldAppsUseDarkMode()` reports dark, `src/msw/darkmode.cpp:205-227, 414-417`) |
+| wxMSW | `wxDataViewCtrl` border in light mode (#25532); `wxTreeCtrl::EnsureVisible()` while frozen (#18435); preferred-languages buffer overrun (#25612); `wxAcceleratorTable` with 0 entries (#25517); date/time pickers on non-English Windows (#25511); per-window menu MDI crash (#25522) | available |
+| wxOSX | Border look of `wxDataViewCtrl`, `wxListBox`, `wxTextCtrl` (#25570); startup crash with Farsi system language (#25561) | native macOS controls |
+
+## 7 3.3.2 notable changes
+
+`changes.txt:255-318`, relative to 3.2.10 (see §1 for the unlisted 3.2.9/3.2.10 fixes).
+
+| Port | Change | Orca relevance |
+|---|---|---|
+| All | `wxWebRequestDebugLogger` (#26086); configurable `wxWebRequest` timeouts (#25673); number/currency formatting (#25765); 3rd-party libraries updated (#26010); `wxSOCKET_NOWAIT_READ\|wxSOCKET_WAITALL_WRITE` (#17114) | image downloads; `Field` formatting |
+| All | `wxDC::DrawLabel()` bitmap position fixed in high DPI (#25888) | available |
+| GUI | `wxGLContext::ClearCurrent()` (#25958) and `wxGLContext::GetProcAddress()` (#9215) — static members of `wxGLContext`, not `wxGLCanvas` as the change log says; `GetProcAddress` "is currently not implemented under macOS and always returns NULL" (`interface/wx/glcanvas.h:550-599`) | Orca loads GL with GLAD (through `eglGetProcAddress` on Wayland, `OpenGLManager::init_gl`) |
+| GUI | `wxGLCanvas::SetSwapInterval()` (#25449) returning `SwapInterval::{NotSet, Set, NonAdaptive}`, `GetSwapInterval()`, `DefaultSwapInterval` (`interface/wx/glcanvas.h:866-893, 1036-1154`) | pitfall below |
+| GUI | Automatic `wxStaticText` wrapping (#25753) | pitfall below |
+| GUI | `wxDisplay::GetRawPPI()` (#26082); configurable `wxScrolled<>` autoscroll (#25978, `EnableAutoScrollInside`/`DisableAutoScrollOutside`); `wxScrolled::GetViewStartPixels()`; `wxWindow::GetMinSizeFromKnownDirection()` | `sizers-layout.md` |
+| GUI | `wxPersistentDVC` restores column positions (#26222); safer `wxTipWindow` close detection (#26070); wxDC-derived objects movable (#25726) | available |
+| GUI | AUI: pane minimising (#23986), crash on hover after closing a notebook tab (#25959), notebook splitting (#26081) | Plater docking |
+| GUI | LunaSVG option (#25902); `wxSVGFileDC` improvements (#25723); generic `wxCalendarCtrl` DPI-aware (#25713); `wxTextEntryDialog::SetHint()` (#26176); `wxStyledTextCtrlMiniMap` (#25887) | LunaSVG and STC are off in Orca's build |
+| GUI | Many RTL layout fixes in wxMSW and wxGTK (#25426) | RTL languages |
+| wxGTK | GLX and EGL in the same program (#26023): wx defaults to EGL even on X11 unless `PreferGLX()` or `wx_opengl_egl=0`; Wayland is always EGL [source] (`src/unix/glcanvas.cpp:218-245`; `interface/wx/glcanvas.h:1082-1102`) | pitfall below |
+| wxGTK | `WarpPointer()` on Wayland compositors with the pointer-warp protocol (#23778); mutter moves the pointer only while a button is pressed (`interface/wx/window.h:3895-3914`) | Orca does not call `WarpPointer` |
+| wxGTK | Gesture handling fixes (#26241); `wxDIRP_DIR_MUST_EXIST` | `GLCanvas3D::bind_event_handlers` binds `wxEVT_GESTURE_PAN/ZOOM/ROTATE` |
+| wxMSW | `WS_EX_COMPOSITED` use from earlier 3.3 reverted (#25808) | §5 pitfall |
+| wxMSW | Dark-mode rendering of several controls (#25835), toolbar (#25892), menus (#26182); accessibility: `wxCheckBox` in dark mode (#26184), full `wxCheckListBox` (#25948) and `wxStyledTextCtrl` (#25956), basic `wxRichTextCtrl` (#26202) | wx dark mode only |
+| wxMSW | `wxNO_WIN32_W` (#25965); MSVS 2026 project files (#26131); `wxString` debug visualiser (#25684) | none |
+| wxOSX | Visual fixes for macOS 26 Tahoe (#25766, #25743, #25767); dark-mode grid lines (#25783); nested markup attributes (#25864); suspend/resume events (#25778); threaded `wxGA_SMOOTH` animation (#25906); more joystick axes (#26216) | native look on Tahoe |
+| wxOSX | Click events consistent with wxMSW (#25886) | pitfall below |
+
+**Pitfalls**
+
+- **Rule:** After `SetLabel` on a `wxStaticText`, re-wrap with `Wrap(-1); Wrap(w);`, or use Orca's
+  `Label` (`LB_AUTO_WRAP`, `Label::Wrap`); use `wxST_WRAP` only inside a sizer that constrains the
+  width.
+  **Why:** "Automatic wrapping" is the opt-in `wxST_WRAP` style, which "only works when the control is
+  used inside a sizer" (`interface/wx/stattext.h:46-49`); labels without it lay out as before, and
+  Orca uses no `wxST_WRAP`. What does change existing code is the rewritten `Wrap()`: it returns
+  immediately when `width == m_currentWrap` (`src/common/stattextcmn.cpp:259-263`), and `SetLabel`
+  clears the saved unwrapped text but not `m_currentWrap` (`UpdateLabelOrig`, :354-365) [source].
+  So `SetLabel(new); Wrap(sameWidth);` — correct under 3.1.5, whose `Wrap()` always re-wrapped —
+  leaves the new label unwrapped. `wxST_WRAP` wraps at the width the sizer offers via
+  `GetMinSizeFromKnownDirection` (:285-316), but the first `CalcMin` still uses the unwrapped best
+  size, so a fitted dialog grows to the full line [source]; constrain the width another way (a fixed
+  or max width on the container). `Label::Wrap` re-wraps from its stored text and has no cache.
+  ```cpp
+  // Wrong: m_static_valid->SetLabel(info_line); m_static_valid->Wrap(FromDIP(300));
+  // Right: m_static_valid->SetLabel(info_line); m_static_valid->Wrap(-1); m_static_valid->Wrap(FromDIP(300));
+  ```
+  Cite: `docs/changes.txt:280`; `sizers-layout.md` §wxStaticText wrapping.
+
+- **Rule:** On Linux/X11, call `wxGLCanvas::PreferGLX()` before any GL use, attribute objects
+  included; set a swap interval explicitly if the canvas needs VSync.
+  **Why:** `PreferGLX()` called late "will trigger an assert failure and have no other effect" (silent
+  in Orca) and has no effect on Wayland (`interface/wx/glcanvas.h:1082-1102`). Orca calls it when
+  `is_running_on_x11()` early in `GUI_App::on_init_inner`. On Unix wx sets the swap interval to **0**
+  (VSync off) at the first `SwapBuffers` unless `SetSwapInterval` was called, so that
+  `eglSwapBuffers`/`glXSwapBuffers` never block on an occluded window [source]
+  (`include/wx/unix/private/glcanvas.h:96`; `src/unix/glegl.cpp:897-915`; `src/unix/glx11.cpp:940-950`).
+  `SetSwapInterval(DefaultSwapInterval)` keeps the driver's default. macOS and MSW leave the default
+  unless asked. `OpenGLManager` sets no swap interval, so on Linux the 3D view's buffer swaps are
+  not synchronised to VSync.
+  ```cpp
+  // Right (if frame pacing is wanted): canvas->SetSwapInterval(1);   // before the first SwapBuffers
+  ```
+  Cite: `docs/changes.txt:275-276, 292`; `webview-gl-aui-media.md` §EGL vs GLX.
+
+- **Rule:** Do not count clicks from `wxEVT_LEFT_DCLICK` alone on macOS; handle `DOWN` and `DCLICK`
+  as on MSW.
+  **Why:** `wxWidgetCocoaImpl::DoHandleMouseEvent` turns every second `DCLICK` back into a `DOWN`
+  (left and right buttons), so a triple click gives `DOWN, DCLICK, DOWN` as on MSW; previously every
+  click with `clickCount > 1` was a `DCLICK` [source] (`src/osx/cocoa/window.mm:4103-4150`). Per-platform click-count ifdefs
+  written for 3.1.5 need rechecking.
+  Cite: `docs/changes.txt:316`; `mouse-keyboard-focus.md`.
+
+## 8 Migration already done in Orca
+
+The upgrade landed as 8248b06337 ("Updated wxWidgets to 3.3.2", #12941; build system 2d7e26292b).
+Its PR kept Orca's own MSW dark mode to avoid broader changes and because wx's needs an app restart to
+switch. Each row is a rule for new code; the owning file has the detail.
+
+| Commit | Rule for new code | Where | Owner |
+|---|---|---|---|
+| 8248b06337 | No version-conditional code for wx < 3.3: the upgrade deleted the pre-3.1.3 DPI-event shim (`DpiChangedEvent`, `EVT_DPI_CHANGED_SLICER`), the luma fallback in `check_dark_mode`, the `wxCHECK_VERSION` guards in `I18N.hpp`/`GUI_App.hpp`, and the macOS 10.9.5 `wxGLContext` hack | `GUI_Utils.hpp` `DPIAware`, `OpenGLManager` | this file |
+| 8248b06337 | `MSWEnableDarkMode(DarkMode_Auto)` runs before `NppDarkMode::InitDarkMode()`, so NppDarkMode's `SetPreferredAppMode(ForceDark` or `ForceLight`, per Orca's setting) overrides wx's `AllowDark` at OS level in both directions; `GUI_App::dark_mode()` honours `dark_color_mode` before `check_dark_mode()` | `GUI_App::on_init_inner`, `GUI_App::dark_mode` | `colours-dark-mode.md` |
+| 8248b06337 | `wxToolTip::GetToolTipCtrl()` is private in 3.3 (`include/wx/msw/tooltip.h:92`); wx applies dark mode to the tooltip window itself through `wxMSWDarkMode::AllowForWindow`, which follows wx's mode [source] (`src/msw/tooltip.cpp:321`; `src/msw/darkmode.cpp:454-457`) | `GUI_App::force_colors_update` (the `#if wxVERSION_NUMBER < 3300` block is dead under 3.3) | `colours-dark-mode.md` |
+| 8248b06337 | Backend webview factories override `GetVersionInfo(wxVersionContext)` without a default argument (`include/wx/msw/webview_edge.h:150`); pass `wxVersionContext::RunTime` when calling through the concrete factory | `WebView::CheckWebViewRuntime` | `webview-gl-aui-media.md` |
+| 8248b06337 | The GL canvas gets `wxBG_STYLE_PAINT`; on MSW `GLCanvas3D::on_paint` renders immediately because idle events are not dispatched inside the modal resize loop (c06a0223a7) | `OpenGLManager::create_wxglcanvas`, `GLCanvas3D::on_paint` | `webview-gl-aui-media.md` |
+| 8248b06337 | On MSW, do not `SetFocus()` the GL canvas while `wxCurrentPopupWindow` is set: the focus change makes wx call `MSWDismissUnfocusedPopup` and closes the search dropdown. `wxCurrentPopupWindow` is a wx-internal global (`src/msw/popupwin.cpp`) that Orca declares `extern` itself, usable only because wx is linked statically | `GLCanvas3D::on_mouse` (`evt.Entering()` branch) | `popups-menus.md` |
+| 6148ba16b3 (in 8248b06337), 988b500f33 | On GTK a `wxBitmapToggleButton`/`wxButton`-based widget sized to exactly its bitmap leaves no room for the theme's CSS padding (GTK "negative content width" criticals). Either strip the native button CSS with `Slic3r::GUI::RemoveButtonBorder` and size to the bitmap (`CheckBox`), or size to `GetBestSize()` grown to the bitmap (`IncTo`; `RadioBox` and `SwitchButton` do both) | `RemoveButtonBorder` (`GUI_Utils.cpp`), `CheckBox::Rescale`, `RadioBox::Rescale`, `SwitchButton::Rescale` | `platforms.md` §GTK native chrome |
+| 8248b06337 | The macOS-only vertical text nudges in `Button::render` and `SideButton::dorender` were removed; do not re-add per-OS baseline offsets | `Button::render`, `SideButton::dorender` | `painting-custom-widgets.md` |
+| 8248b06337 | `wxEXPAND` combined with `wxALIGN_*` in a box sizer was cleaned up; the combination is ignored | `Sidebar::priv::layout_printer`, `AMSControl::createAmsPanel` | `sizers-layout.md` |
+| 8248b06337 | `GUI_App::on_init_inner` filters known-harmless GTK criticals (allocation on hidden widgets, events on unrealised widgets, style-context calls from `SetBackgroundColour` before realisation); check that filter before chasing such a message | `GUI_App::on_init_inner` | `platforms.md` |
+| 5f365b5c6b | `wxBitmapComboBox` overrides take `wxBitmapBundle` (`OnAddBitmap(const wxBitmapBundle&)`, `include/wx/bmpcbox.h:89`); `m_bitmaps` became `m_bitmapbundles`; get a bitmap with `GetBitmap(GetDefaultSize())` | `BitmapComboBox::OnAddBitmap`, `BitmapComboBox::OnDrawItem` (both macOS-only overrides) | `dpi-bitmaps-fonts.md` |
+| ed88cbe3f5 → d62aa42e61 | 3.3's `wxWebViewWebKit` has neither the default ctor nor the creating `(parent, id, url, …)` ctor of 3.1.5; its only ctor is `explicit wxWebViewWebKit(const wxWebViewConfiguration&, WX_NSObject request = nullptr)` (`include/wx/osx/webview_webkit.h:36`). ed88cbe3f5 switched macOS to `wxWebView::New()`, which bypassed the subclass destructor that calls `RemoveScriptMessageHandler("wx")`; d62aa42e61 restored `WebViewWebKit` via `wxWebView::NewConfiguration(wxWebViewBackendWebKit)`. Only Linux uses `wxWebView::New()` | `WebView::CreateWebView`, `WebViewWebKit` | `webview-gl-aui-media.md` |
+| 1765d296a8, 2b3328c2b2 | `wxArrayString` via `Add()`; `wxString` first in mixed concatenation; `compatibility_iterator` for wx lists (§4) | `Plater::import_model_id`, `OptionsSearcher::search`, `SendMultiMachinePage` | this file |
+| 7ea69199fd | `dynamic_cast`, not `wxDynamicCast`, on `wxComboPopup` (§4) | `combochecklist_get_flags`/`_set_flags` (`GUI.cpp`) | this file |
+| ba867cc534 | `Show()` (only if `!IsShown()`) before `Raise()` (§3) | `Plater::priv::priv` handlers, `Plater::priv::bring_instance_forward` | `windows-dialogs.md` |
+| 026b105dcb | No `wxTRANSPARENT_WINDOW` (§3); it is a no-op `0`, so this was cleanup, not a build fix | `MainFrame` (`ResizeEdgePanel`, side-tool panels) | this file |
+| eefdabcd98, f70d30bf79 (#13074) | The auto-added `WS_CAPTION` (3.3.0, #23575; eefdabcd98's message says 3.3.2) made `DefWindowProc` subtract a caption from the maximised client area, and on Windows 10 left the native frame visible behind the custom title bar ("double window"). The `MainFrame` ctor strips `WS_CAPTION` from `GWL_STYLE` right after creation (`SetWindowPos(… SWP_FRAMECHANGED)`); `WM_NCCALCSIZE` computes border thickness with `GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION` and strips the border overshoot itself when maximised; f70d30bf79 restored the `wxEVT_MAXIMIZE` handler that clamps the maximised frame to the display client area | `MainFrame::MainFrame`, `MainFrame::MSWWindowProc` (`WM_NCCALCSIZE`), `AdjustWorkingAreaForAutoHide` | `platforms.md` §MSW title bar |
+| 46e47cec0a | `wxGrid::GetSelectedBlocks()` (unordered, possibly overlapping, `interface/wx/grid.h:5091-5109`) is an empty range after the user deselects; compare `begin()` with `end()` and fall back to the activating cell | `GridCellSupportEditor::DoActivate` (`GUI_ObjectTable.cpp`) | `controls-dataview.md` |
+| 9a053f15eb (#12936) | Since the upgrade, on macOS the Slice/Print split-button's transient popup was dismissed the moment the cursor entered the gap between button and menu; on macOS anchor transient popups flush with (slightly overlapping, 2 px) their button | `SidePopup::Popup` (`__APPLE__` branch) | `popups-menus.md` |
+| 1f2ed70288 (#13119) | Orca registers its own `kAEGetURL` handler so `orcaslicer://` links reach `MacOpenURL` | `register_mac_deep_link_handler` (`DeepLinkHandlerMac.mm`), called from `GUI_App::on_init_inner` | this file |
+
+These post-upgrade regressions were fixed: 46e47cec0a (ObjectTable crash on cell deselect),
+1f2ed70288 (macOS deep links), d62aa42e61 (WebView script-handler cleanup), eefdabcd98 (maximised
+window not filling the desktop), f70d30bf79 (Windows 10 double window frame), c06a0223a7 (blank 3D
+canvas during MSW resize). Watch for them to
+recur when touching the same code.
+
+**Pitfalls**
+
+- **Rule:** Keep Orca's own `kAEGetURL` registration in `GUI_App::on_init_inner`; do not rely on
+  wx's handler for `orcaslicer://` links.
+  **Why:** wx installs its handler in `applicationWillFinishLaunching:`
+  (`src/osx/cocoa/utils.mm:46-57`); it forwards to `MacOpenURL` only once `OSXInitWasCalled()` is
+  true and otherwise stores the URL with `OSXStoreOpenURL` (:191-200) [source]. After the upgrade
+  the wx handler stopped delivering deep links on macOS (#13119, reported on macOS 26): links from
+  Printables/Thingiverse opened a blank project. `NSAppleEventManager` keeps the last registration, so Orca's later registration wins
+  and routes straight to `MacOpenURL` → `start_download`. Removing it, or registering before wx does,
+  brings the regression back.
+  ```cpp
+  // Right (GUI_App::on_init_inner, __APPLE__): register_mac_deep_link_handler();
+  ```
+  Cite: 1f2ed70288; `DeepLinkHandlerMac.mm`.
+
+- **Rule:** Do not reintroduce `wxTRANSPARENT_WINDOW` or a post-creation
+  `SetBackgroundStyle(wxBG_STYLE_TRANSPARENT)` to make a panel blend in; set its background colour,
+  dark-mode mapped, and re-apply it on theme change.
+  **Why:** see §3. The side-tool panels lost MSW transparency with the upgrade, and 8248b06337
+  (b9952b39ad) fixed them by giving them `StateColor::darkModeColorFor(wxColour("#3B4446"))`,
+  re-applied in `MainFrame::update_side_button_style`.
+  Cite: 026b105dcb, 8248b06337 (b9952b39ad).

.github/workflows/build_all.yml

@@ -56,7 +56,9 @@ on:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
+  # Pushes don't cancel a running build, because only a finished branch build
+  # saves caches every pull request can restore.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
   
 
 jobs:

CMakeLists.txt

@@ -1301,54 +1301,6 @@ if (WIN32)
     endif()
     set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP TRUE)
     include(InstallRequiredSystemLibraries)
-
-    # CMake 3.31 does not recognize the v145 toolset shipped with VS 2026.
-    # The Windows ARM64 build is pinned to CMake 3.31 for its assembler
-    # support, so the runtime collector can leave this list without the CRT.
-    # Pick up the target-architecture redistributable directly in that case.
-    if (CMAKE_SYSTEM_PROCESSOR STREQUAL "ARM64")
-        set(_orca_has_msvcp140 FALSE)
-        set(_orca_has_vcruntime140 FALSE)
-        foreach (_runtime IN LISTS CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS)
-            get_filename_component(_runtime_name "${_runtime}" NAME)
-            if (_runtime_name STREQUAL "msvcp140.dll")
-                set(_orca_has_msvcp140 TRUE)
-            elseif (_runtime_name STREQUAL "vcruntime140.dll")
-                set(_orca_has_vcruntime140 TRUE)
-            endif ()
-        endforeach ()
-
-        if (NOT _orca_has_msvcp140 OR NOT _orca_has_vcruntime140)
-            file(GLOB _orca_arm64_crt_dirs
-                "$ENV{ProgramFiles}/Microsoft Visual Studio/*/*/VC/Redist/MSVC/*/arm64/Microsoft.VC*.CRT")
-            if (NOT _orca_arm64_crt_dirs)
-                message(FATAL_ERROR
-                    "CMake did not collect the ARM64 MSVC runtime, and no ARM64 CRT redistributable directory was found.")
-            endif ()
-            # Multiple Visual Studio servicing versions can coexist; take the
-            # newest matching redistributable directory.
-            list(SORT _orca_arm64_crt_dirs ORDER DESCENDING)
-            list(GET _orca_arm64_crt_dirs 0 _orca_arm64_crt_dir)
-            file(GLOB _orca_arm64_crt_dlls "${_orca_arm64_crt_dir}/*.dll")
-            list(APPEND CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS ${_orca_arm64_crt_dlls})
-        endif ()
-
-        # Catch a bad VS layout or an incomplete redistributable before CPack
-        # can silently emit an installer that fails on a clean ARM64 machine.
-        set(_orca_has_msvcp140 FALSE)
-        set(_orca_has_vcruntime140 FALSE)
-        foreach (_runtime IN LISTS CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS)
-            get_filename_component(_runtime_name "${_runtime}" NAME)
-            if (_runtime_name STREQUAL "msvcp140.dll")
-                set(_orca_has_msvcp140 TRUE)
-            elseif (_runtime_name STREQUAL "vcruntime140.dll")
-                set(_orca_has_vcruntime140 TRUE)
-            endif ()
-        endforeach ()
-        if (NOT _orca_has_msvcp140 OR NOT _orca_has_vcruntime140)
-            message(FATAL_ERROR "The ARM64 installer must contain msvcp140.dll and vcruntime140.dll.")
-        endif ()
-    endif ()
     install (PROGRAMS ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS} DESTINATION ".")
 elseif (SLIC3R_FHS)
     # CMAKE_INSTALL_FULL_DATAROOTDIR: read-only architecture-independent data root (share)

TEXTURE_DISPLACEMENT.md

@@ -1,581 +0,0 @@
-# Texture Displacement - Technical Notes
-
-Branch: `feature/texture_displacement`. Reference for the feature as it stands: what it does, how the
-algorithms work, and where the code lives.
-
-## What it does
-
-A paint-style gizmo (`GLGizmoTextureDisplacement`) that lets you:
-- Paint one or more "layers" onto a model's surface, each a height-map texture with its own
-  depth/tiling/rotation/offset/invert/tile-mode/projection-mode/blend-mode.
-- Pick a texture from a shipped library (`resources/textures/displacement/`) or import your own
-  (saved into `<data_dir>/textures/displacement/`, kept separate so app updates can't clobber it).
-- Combine overlapping layers with image-editor-style blend modes (Add/Subtract/Multiply/Divide).
-- Preview the true displaced result live, before baking (background job, not on the UI thread).
-- Preview via a fast GPU shader instead (no real geometry movement) for a lighter-weight alternative.
-- Bake into real mesh geometry on demand, restricted to the painted area only.
-- Remesh and subdivide so a low-poly model has enough vertices to show fine detail.
-- Unwrap a painted patch with a real CGAL LSCM parameterization and view it in a dedicated,
-  dockable 2D "UV Editor" pane.
-
-## Standard vs Pro mode
-
-A two-position slider in the panel header, right of the Dock/Undock button.
-
-**Pro** shows every mesh-preparation control; Remesh, Subdivide and Bake are run separately by the user,
-in whatever order they like.
-
-**Standard** hides all of it and folds one fixed recipe into the Bake button, because a height map only
-ever *moves vertices that already exist* - painting onto an imported 12-triangle box and pressing Bake
-would otherwise do nothing visible. Standard's Bake is:
-
-1. `plan_remesh()` + `replace_mesh_keep_all_paint()` - isotropic remesh to 1 mm, sharp edges above 40
-   degrees protected. Gives the subdivider an even starting density whatever the input looked like.
-2. `plan_adaptive_subdivision()` + `apply_adaptive_subdivision()` - feature-adaptive refinement, max
-   edge 20 mm, detail 0.02 mm, min edge 0.02 mm.
-3. `bake()` - the ordinary background displacement job.
-
-Both preparation stages are *planned* before the undo snapshot and *applied* after it, so a stage with
-nothing to do is skipped without leaving an empty undo step. The standalone Pro buttons share the same
-plan/apply split.
-
-**All three stages sit under one undo step.** `Plater::take_snapshot()` records the state *before* the
-change, so a single snapshot taken at the top of `bake_standard()` means one Undo returns the mesh to
-exactly what was imported. `TextureDisplacementBakeInput::take_snapshot` lets the caller say who owns
-the undo step - true for the Pro-mode button, false for the pipeline, whose background job commits long
-after that snapshot's scope has closed.
-
-The presets live in one place (`STD_*` constants) and `apply_standard_mode_presets()` pins the hidden
-controls to them every frame while Standard is active, so the live preview cannot disagree with what
-Bake will do. Switching to Standard also closes the subdivision preview, whose controls have just gone.
-
-One control survives into Standard: **"Added triangles (k)"**, the subdivision budget. It is deliberately
-*not* pinned - pinning would fight the user's own slider every frame - because unlike the rest of the
-recipe its right value depends on the part rather than on the method (a big model, or a fine texture,
-simply needs more triangles). Default 1500. The widget is one lambda shared by both layouts.
-
-Standard remeshes *after* painting, so the remesh has to preserve paint: `ModelVolume::restore_painting()`
-only remaps the four standard channels, so `replace_mesh_keep_all_paint()` additionally runs
-`TriangleSelector::remap_painting()` over the eight texture-displacement masks. The Pro Remesh button
-goes through the same helper. If the remap comes back empty the pipeline stops with a message rather
-than baking a flat mesh.
-
-## Architecture
-
-### Data model (per `ModelVolume`)
-
-Each of up to `TEXTURE_DISPLACEMENT_MAX_LAYERS` (8) layers gets its **own independent
-`FacetsAnnotation`** paint mask - the same `TriangleSelector`/`FacetsAnnotation` machinery every other
-paint gizmo (FdmSupports, Seam, MMU, FuzzySkin) already uses, just one full instance per layer slot
-instead of one per volume. This is what makes layered/blended painting work for free: the same triangle
-can be `ENFORCER` in layer 2's mask and layer 5's mask simultaneously, and at bake/preview time each
-layer displaces the surface left by the previous one (image-editor-layer semantics).
-
-Whole-stack settings (border handling, post-process smoothing) live beside the layers in
-`texture_displacement_options` (`TextureDisplacementOptions`), since they belong to no single layer.
-
-### Bake algorithm (`libslic3r/TextureDisplacement.cpp`)
-
-`build_texture_displacement(base_mesh, layers, facets_data, options)` is **accumulate-then-displace,
-and topology-preserving**: the returned mesh has exactly the input's vertices and triangles, in the
-same order - only the positions of displaced vertices differ.
-
-1. `its_compactify_vertices()` on a copy of the input. In practice a no-op (it only drops
-   *unreferenced* vertices, and preserves the order and indices of the rest). It is there to
-   guarantee the index alignment step 3 depends on.
-2. Area-weighted vertex normals of the **undisplaced** mesh, computed once. Every layer both projects
-   and displaces along these, so a vertex covered by several layers moves along one single well-defined
-   direction. Where the paint does *not* cover every triangle around a vertex, the normal is recomputed
-   from the painted triangles alone (the union over all layers, so it stays one direction per vertex):
-   on the rim of a fully painted top face the whole-mesh normal is the 45-degree bisector it shares with
-   the side wall, and displacing along that flares the rim outwards instead of raising it. Interior
-   vertices are unaffected - all their triangles are painted, so the two normals coincide. Paint
-   coverage per original triangle comes straight off `TriangleSplittingData::triangles_to_split`.
-3. For each layer in slot order: deserialize its stored paint mask into a `TriangleSelector` against
-   the **base mesh** (never against a previous layer's output), then
-   `selector.get_facets_strict(ENFORCER)` -> the painted patch. Two facts are exploited:
-   - `get_facets_strict()` returns the mesh's **entire** referenced vertex array regardless of which
-     state was asked for - only `.indices` is filtered by state. So `get_facets_strict(ENFORCER)`
-     and `get_facets_strict(NONE)` share identical vertex indexing, which is what lets boundary
-     detection be a plain index check instead of a position-hash lookup.
-   - The selector's vertex array *starts with* the mesh's own vertices (extra ones created where a
-     brush stroke split a triangle are appended after them), and `get_facets_strict()` emits the
-     referenced ones in order. Combined with step 1, **selector vertex index `i` is our vertex `i`**.
-     Split vertices live past the end of our array and are simply skipped - they sit on the paint
-     boundary anyway (splitting only happens at partial coverage).
-4. A vertex used by at least one **unpainted** triangle is a border vertex. Whether it moves is
-   `TextureDisplacementOptions::displace_border`, and it does by default. Nothing can tear: the bake is
-   topology-preserving, so a border vertex is *one* vertex shared by both regions and moving it simply
-   tilts the unpainted triangles that use it. Pinning it instead clamps the outermost ring of relief to
-   zero, which on a fully painted face collapses the pattern into a ring of steep ramps at the edge; it
-   is kept as an option for when the relief must not spill past the paint at all. Either way the border
-   drives the `edge_smoothing` falloff.
-5. Per interior vertex: sample the height texture (`sample_layer_height()`, see Projection methods)
-   and fold `height * depth_mm * (invert ? -1 : 1)` into that vertex's running total via the layer's
-   `TextureBlendMode` (see Blend modes). A `visited` set makes each layer fold in exactly **once**
-   per vertex, no matter how many of the patch's triangles share it - otherwise a Multiply/Subtract
-   layer would apply two or three times over depending on local triangle fan-out.
-6. Move each touched vertex along its (step 2) normal by its accumulated total.
-7. Optionally (`TextureDisplacementOptions::smooth_*`) relax the result - see Post-process smoothing.
-
-### Post-process smoothing
-
-`smooth_mesh_vertices(mesh, movable, strength, iterations)` - Laplacian relaxation, run after all layers
-have been folded in, restricted to the vertices flagged in `movable`. Each pass moves a movable vertex a
-`strength` fraction of the way to the average of its one-ring, read from a **snapshot** of the previous
-pass so the result does not depend on vertex order (a Gauss-Seidel sweep would smooth several times as
-hard at the end of the array as at the start). Neighbours come from a CSR-style adjacency built once per
-call. Topology-preserving, like the bake.
-
-Its job is to round off the hard steps a bitmap height map leaves behind - a different knob from
-`TextureDisplacementLayer::smoothing`, which blurs the *height map* before it is ever sampled.
-
-Two ways in, sharing one set of settings on the volume:
-- The **"Smooth result"** checkbox + "Smoothing (%)" / "Passes" ride along with Preview and Bake.
-  `movable` is exactly the set of vertices the displacement moved, so the untouched part of the model
-  keeps its exact geometry and the ring just outside the displaced set anchors the relaxation (the
-  relief cannot creep outward).
-- **"Smooth baked mesh now"** (`GLGizmoTextureDisplacement::smooth_model()`) applies the same settings to
-  the volume's *committed* geometry, for relief that is already baked in. `movable` there is the painted
-  triangles' vertices. Because smoothing never touches the triangle list, this is the one geometry
-  operation in the gizmo that keeps **every** paint channel verbatim - it saves and restores the eight
-  texture-displacement masks around `set_mesh()` rather than remapping or dropping them.
-
-**"Ignore outer ring"** (`smooth_skip_border`, on by default) drops the patch's own outermost ring of
-vertices from `movable`. That ring's neighbours *outside* the paint never move, so relaxing it drags the
-rim of the relief down toward the flat surface and the pattern comes out half-melted where it meets the
-edge. Held out, the border keeps the full depth the texture asked for and only the interior relaxes.
-Turning it off softens the outer edge deliberately (a blunter version of the per-layer edge-smoothing
-falloff). This is the *smoothing* rim, independent of whether that rim is displaced at all
-(`displace_border`, step 4 above); both default to keeping the border sharp.
-
-### Blend modes
-
-`TextureBlendMode` {Add, Subtract, Multiply, Divide}, per layer, applied per vertex against the
-total accumulated by the layers **below** it (lower slots). The quantity blended is a signed
-displacement in **mm**, not a pixel value.
-
-Add/Subtract are self-explanatory. Multiply/Divide are *scaling* operations and so need a unit
-convention: they treat the layer's own value as a **factor relative to 1 mm**. That makes `depth_mm`
-a gain, and - the property that makes a Multiply layer usable as a mask - a layer with depth 1 mm
-sampling a white (1.0) texel multiplies by exactly 1, i.e. leaves the layers below unchanged.
-Divide floors its divisor's magnitude at 0.05: a black texel samples to *exactly* zero, so the divisor
-really does hit zero in ordinary use, and an unbounded `1/0` would fling vertices thousands of mm away
-and poison the mesh's bounding box (and every plate/print-volume check downstream). The floor doubles as
-a cap on how far Divide can amplify the relief beneath it: at most 20x.
-
-The **lowest painted layer ignores its blend mode**: it has nothing beneath it, and Multiply/Divide
-against an implicit zero base would annihilate (or blow up) it. Enforced in
-`build_texture_displacement()` (the first layer to reach a given vertex always folds in additively) and
-surfaced in the UI, which labels that layer "Base layer" instead of offering a control that does nothing.
-
-### Projection methods
-
-Five choices per layer (`TextureProjectionMethod`), all funneling through `apply_uv_transform()`
-(scale by `1/tiling_scale`, rotate by `rotation_deg`, add `offset`). They are dispatched by
-`sample_layer_height()`, which returns a **height**, not a UV - because Triplanar takes three
-texture samples per vertex and so has no single UV that represents it.
-
-- **Triplanar** (default) - samples the texture on all three world planes (`(y,z)`, `(x,z)`, `(x,y)`)
-  and blends the three by the vertex's own normal raised to `TRIPLANAR_BLEND_SHARPNESS` (4). Hard-picking
-  the single axis most aligned with the normal instead is discontinuous wherever that dominant axis
-  flips: on a +X face the planar coordinate is `(y, z)`, on a -Y face it is `(x, z)`, so at the shared
-  edge `u` jumps. A weighted blend is continuous across the transition by construction, since the weight
-  of the axis being left behind falls smoothly to zero. This removes the hard *seam*; some cross-fade
-  blurring in the band right at a 90° edge is inherent to triplanar mapping. A genuinely seam-free wrap
-  around a box needs a real unwrap - that is what the LSCM mode is for.
-- **Cylindrical** - wraps around an axis through the patch centroid, axis auto-picked as the world
-  axis *least* aligned with the average normal (perpendicular to the outward radial normal, as a
-  cylinder's own axis would be). `u = angle * local_radius` (arc length in mm), `v = distance along
-  axis`. An approximation, not an exact fit for arbitrary geometry, and the axis/centre are not
-  user-overridable.
-- **Spherical** - longitude/latitude around the centroid, scaled by local radius. Same caveat.
-- **LSCM** - real UV unwrap via `MeshBoolean::cgal::parameterize_lscm()` (CGAL's
-  `Surface_mesh_parameterization` package, LSCM algorithm). Computed **once per patch** (not
-  per-vertex like the others - it's a single global least-squares solve), then each vertex looks up
-  its precomputed UV. Requires the patch to be a single topological disk (one connected component,
-  one boundary loop) - `compute_lscm_uvs()` returns empty and the layer falls back to Triplanar if not
-  (e.g. multiple disconnected painted islands, or a fully closed patch). CGAL's parameterizer needs a
-  mesh with no isolated/unreferenced vertices, but `get_facets_strict()` returns the *whole* mesh's
-  vertex array - so `compact_patch_with_map()` builds a clean sub-mesh plus an index map back to the
-  original vertex numbering, purely local to this file.
-- **ViewProjected** ("From view") - a flat projection along a fixed direction captured from the 3D
-  camera, like a slide projector. `capture_view_projection()` takes the camera's right/up axes,
-  transforms them into the volume's *local* frame (so the projection rides along if the part is later
-  moved), and stores them as `TextureDisplacementLayer::view_project_right/up` (unit vectors, so the
-  projected coordinate stays in mm and `tiling_scale` keeps meaning mm). `sample_layer_height()`
-  projects `Vec2f(dot(pos, right), dot(pos, up))`. Single-valued per point, so - like LSCM but unlike
-  blended Triplanar - the fast preview and UV-check overlay precompute it per vertex
-  (`compute_layer_vertex_uvs()`) and drive the shader's `use_vertex_uv` path. Faces angled away from
-  the projector smear; that is inherent to view projection.
-
-  Two companions to this mode:
-  - **Projection frame overlay** (`TextureProjectorFrame`, see below) - a semi-transparent window
-    dragged over the 3D view whose border becomes the projection's edge. Applying it stores an exact
-    **projective** map in `view_project_matrix`, which supersedes the affine `right`/`up` axes above
-    for that layer (`view_project_projective`).
-  - **"Project only on visible"** (`select_visible_faces()`) - repaints the layer with exactly the
-    facets the camera can see, so the projected area matches the viewpoint the projector was captured
-    from. Two tests: a facing test (normal vs. view direction, per triangle - under perspective the
-    view direction varies across the model, so it is taken from the eye to each centroid), then
-    `MeshRaycaster::get_unobscured_idxs()` on the survivors to drop facets hidden behind other
-    geometry, so a concave part's far inner wall is correctly excluded. One ray query per front-facing
-    facet, hence click-driven (on the checkbox and on each "Capture current view"), never per frame.
-    It **replaces** the layer's paint rather than adding to it - "project onto what I can see" would
-    otherwise accumulate every angle the user had ever looked from.
-
-### Manual seams and island cutting
-
-`TextureDisplacementLayer::lscm_seam_edges` - undirected mesh-vertex-index edge pairs the unwrap is
-forced to cut along, on top of the dihedral-angle seams. `segment_into_charts()` takes a set of these
-(translated from mesh -> compacted-patch numbering inside `compute_patch_unwrap()`) and refuses to
-union two triangles across a marked edge whatever their angle. Both the unwrap cache key and the
-gizmo's `UVEditorState` include the seam list, so marking a seam (which leaves the paint mask
-untouched) still forces a re-solve. Like the paint masks, seams are mesh-index-space and so dropped on
-any topology change.
-
-Two ways to write to it:
-- **Mark seam (manual)** - a "Mark seams" click mode (`m_seam_edit_mode`) that suppresses painting. A
-  click raycasts the volume (`m_c->raycaster()->raycasters()[idx]->unproject_on_mesh()`, `idx` = the
-  volume's slot among model-part volumes), finds the facet's edge nearest the hit point, and toggles it.
-  Marked edges render as a red overlay (`render_seam_overlay()`), pulled toward the camera so they read
-  on top. This is the Blender mark-seam workflow.
-- **Cut island (auto)** - `cut_island()` takes the selected chart's triangles (back-mapped from the
-  unwrap via `source_vertex`), finds their 3D bounding box, and marks every edge that straddles the
-  mid-plane perpendicular to the longest axis. The re-unwrap then splits the chart across its narrow
-  waist. Exposed as the UV pane's **Cut** button.
-
-### UV-check overlays (checker / distortion)
-
-`resources/shaders/{110,140}/texture_displacement_uvcheck.{vs,fs}`, one shader with a `mode` uniform,
-drawn over the painted patch (`rebuild_uvcheck_mesh()`/`render_uvcheck_mesh()`, P3N3T2: `normal.x` =
-distortion, `tex_coord` = uv), pulled forward with a polygon offset. **Checker** samples a procedural
-checkerboard at the layer's uv (per-vertex for LSCM/ViewProjected, in-shader triplanar otherwise) -
-squares that stay square mean low distortion. **Distortion** colours each triangle blue->green->red by
-`log2(uv_area / surface_area)` centred on the patch's *median* stretch (so a globally-scaled unwrap
-reads as uniformly ideal and only relative stretch shows), averaged to vertices. A separate **Show mesh
-wireframe** toggle draws the whole volume's triangle edges, rebuilt only when the vertex count changes
-(not per stroke).
-
-### Tiling
-
-`DecodedHeightTexture::sample(uv, tile_enabled, tile_method)`. Two tile methods when enabled
-(Repeat, MirroredRepeat). **When `tile_enabled` is false, sampling outside `[0,1)` returns `0`
-directly** rather than clamping the *coordinate* into range, which would smear the border row/column of
-pixels outward to infinity in every direction (streaky lines radiating out from the painted patch).
-
-### Subdivision - two modes
-
-**Uniform (`subdivide_mesh_uniform()`)** - whole-mesh, 1-to-4 split. Recursive edge-midpoint split with
-a shared per-pass midpoint cache (keyed by sorted vertex-index pair) so triangles sharing an edge get
-the *same* new vertex - capped at `max_iterations` (default 6). Whole-mesh so it never leaves a
-T-junction, at the cost of densifying everywhere. Wired as a "Subdivide steps" slider (**0-5**, 0 =
-no subdivision), Apply snaps back to 0. Drops texture-displacement paint (no remap) via the standard
-`save_painting()`/`set_mesh()`/`restore_painting()` dance; the other four channels are remapped.
-
-**Adaptive (`subdivide_mesh_adaptive()`)** - refine **only the painted area**, by **Rivara longest-edge
-bisection**, which is *conformal by construction*. Only **terminal** edges are ever bisected - an edge
-that is the longest edge of *every* triangle sharing it - which splits both those triangles along one
-shared midpoint at once, so a hanging node is never created. The edge to split for a triangle that wants
-refining is found by **longest-edge propagation (LEPP)**: walk to the longest edge of ever-longer-edged
-neighbours until a terminal one is reached, and bisect that. Edge length strictly increases along the
-path (ties broken by mesh-vertex key, which both sides of an edge compute identically), so the walk
-cannot cycle, and Rivara's result is that repeating it refines the original triangle in a bounded number
-of bisections. The transition triangles it pulls in just outside the painted patch are the graded band
-that makes the size change conformal.
-
-The win: a small decal on a big model no longer quadruples the *whole* model's triangle count.
-
-**Run to completion, worst-first, against a triangle budget.** The refinement loop is not a fixed number
-of sweeps: it holds every triangle that is over its criteria in a max-heap keyed by *how many times over*
-it is, pops the worst, walks its LEPP, bisects, and re-scores. Edge adjacency (`nb[e]`, the triangle
-across each edge) is built **once** and maintained incrementally through each bisection, so the cost
-scales with the refined region rather than with the whole model. `max_triangles` is the only bound;
-stopping on it leaves a perfectly valid, still-conformal mesh that spent its budget on the largest
-errors. A fixed sweep count instead spends itself grading the *coarse surroundings* - whose edges are
-the longest, so they win every terminal-edge contest - and never reaches the painted patch.
-
-**It carries the paint forward**, which is what makes it usable (uniform subdivide drops paint). Because
-the refinement is *driven by* the paint, the remap is trivial: `subdivide_mesh_adaptive()` fills an
-`out_source[new_tri] = input_tri` map (children inherit their parent), and the gizmo rebuilds each
-layer's mask on the new mesh - a new triangle is painted iff its source was fully painted in that
-layer. `collect_paint_region()` derives both:
-- the union refine-region: **exactly** the original triangles the brush touched, read straight off
-  `TriangleSplittingData::triangles_to_split` (`serialize()` records an entry per original triangle that
-  is either split - i.e. partially painted, the patch boundary - or carries a non-default state). No
-  dilation: marking every triangle that shares a *vertex* with the patch drags in a whole fan of huge
-  unpainted neighbours and refines *those* down to the resolution floor, since the height field the
-  detail test samples is not restricted to the painted area. The conformal closure already grades the
-  size change outward on its own.
-- the per-layer fully-painted-triangle sets (a `get_facets_strict(ENFORCER)` sub-triangle with all three
-  *original* vertex indices == a whole, fully-painted original triangle; a partial stroke's sub-triangles
-  always carry a split vertex).
-
-The other four channels ride the normal `restore_painting()` remap.
-
-Both modes share the gizmo's Preview/Apply/Done flow; the **"Only painted area (adaptive)"** checkbox
-picks the mode, and the adaptive preview follows the paint live (`rebuild_preview()` refreshes the
-wireframe while the subdivide preview is open in adaptive mode). The panel shows the previewed triangle
-count.
-
-**Feature-adaptive (follow texture detail).** A sub-mode of adaptive (the **"Follow texture detail"**
-checkbox) that puts triangles where the *displaced surface actually bends*, not evenly. A flat region or
-a linear **ramp** needs no extra vertices (linear interpolation is exact for a ramp); what needs them is
-**curvature** - the *second* derivative, not the gradient. So the extra predicate is a **chord-error**
-test: sample the combined displacement at the triangle's three edge midpoints *and its centroid*
-(sampling the interior is what catches a hill sitting inside a triangle, the blind spot of an edge-only
-test) and take the largest departure from the flat triangle's barycentric interpolation. Refine while
-that exceeds `chord_tolerance_mm` ("Detail (mm)"). Zero chord error on a ramp => untouched; high on a
-hill/ridge/noise => refined until captured. Same conformal machinery, so still crack-free. The
-per-triangle error is cached and recomputed only for the children of a split.
-
-Four knobs bracket it, and all four matter:
-- **"Max edge (mm)"** (`target_edge_length_mm`) is a **baseline that applies in feature mode too**.
-  Without it the chord test aliases: a big triangle over a fine pattern can sample four points that all
-  land at similar heights, report no error, and stall before refinement ever starts. The baseline
-  guarantees a sampling density fine enough for the curvature test to see the texture at all.
-- **"Detail (mm)"** is the chord tolerance above.
-- **"Min edge (mm)"** is a hard floor under both, and is what guarantees termination across a sharp
-  texture *step*, where the error never falls however fine the mesh gets.
-- **"Added triangles (k)"** is the budget, passed as `max_triangles` (the model's own triangle count plus
-  the slider, so the control still means something on an already-dense model).
-
-The height field is `make_combined_displacement_sampler()` - it mirrors `build_texture_displacement()`'s
-per-layer setup (decode, patch centroid, cylinder axis, blend order, "lowest layer folds additively")
-but evaluated per point. Two deliberate simplifications, both erring toward *more* detail (safe -
-over-refinement is never a crack): every sampleable layer is sampled at every point (no per-point paint
-test), and edge-smoothing falloff is ignored. The first is *why* the refine region must not be dilated -
-outside the paint the sampler still reports full relief. **LSCM layers are skipped** (no per-point UV); a
-purely LSCM stack yields a null sampler and the code falls back to the length baseline alone. Per-vertex
-heights are sampled lazily, so a small patch on a huge model never pays for the rest of it.
-
-### Fast preview (GPU-only, no CPU meshing)
-
-`resources/shaders/{110,140}/texture_displacement_shaded.{vs,fs}`, registered as
-`"texture_displacement_shaded"`. Shades the *displaced* surface without moving geometry - active-layer
-only, selected from the View row, and the default when the gizmo opens (`m_use_shaded_preview = true`).
-Vertex format is `GLModel::Geometry::EVertexLayout::P3N3T2`: `normal.x` carries the per-vertex paint
-weight (0/1), `normal.y` flags the UV island currently being dragged, and `tex_coord` carries a
-precomputed texture UV, so it can use `GLModel` normally instead of a hand-rolled VBO/VAO manager.
-
-The mesh is **flat** (vertices not shared between triangles): every corner of a painted triangle gets
-weight 1, every corner of an unpainted one weight 0. A coarse mesh needs that - one painted face of a raw
-cube has no strictly-interior vertex, so per-vertex weighting would either bleed onto the neighbours or
-vanish outright. Duplicating vertices costs no shading quality here because the shader takes its surface
-normal from screen-space derivatives of position, not from a per-vertex normal.
-
-**Both preview meshes work in the patch's vertex space, not the mesh's.** Those agree only until a
-*brush* stroke splits a triangle: `get_facets_strict()` then appends the split vertices, so the patch
-array is longer. `rebuild_shaded_preview_mesh()` and `rebuild_uvcheck_mesh()` therefore index
-`patch.vertices` throughout. The weight buffer is rebuilt at the same cadence as the true-displacement
-preview (stroke-end/slider-release) but from the **live** `TriangleSelector` state, not the flushed model
-facets, so it does not lag by a full model round-trip.
-
-The perturbed normal is the analytic one for a height field `H = +/-depth_mm - h(uv)` displaced along
-`N` over any orthonormal surface tangent pair `T`/`B`:
-
-    N' = normalize(N - (dH/da)-T - (dH/db)-B),   a = dot(p,T), b = dot(p,B)
-
-The two slopes have to be genuine **mm-per-mm** derivatives for the preview's apparent depth to match
-the bake's.
-
-**Two projection paths (`use_vertex_uv` uniform):**
-- **Triplanar (`use_vertex_uv = 0`)** - `uv` and the `T`/`B` axes are both derived in-shader from
-  the dominant normal component, mirroring `project_planar()`/`apply_uv_transform()`, and the slope is
-  formed analytically. `T`/`B` are the projection's axis-aligned pair, exact only when the face is
-  axis-aligned; the shader drops the along-normal component to keep the gradient in the surface. Here
-  one `uv` unit is exactly `tiling_scale` mm, so the `1/tiling_scale` gradient factor is right.
-- **Precomputed UV (`use_vertex_uv = 1`, used for LSCM and ViewProjected)** - `uv` comes per-vertex from
-  the CPU (`compute_layer_vertex_uvs()`, so island placement + tiling/rotation/offset are already folded
-  in), and the perturbed normal is built with **Mikkelsen's method** ("Bump Mapping Unparametrized
-  Surfaces on the GPU"): the surface gradient taken directly from the screen-space derivatives of the
-  *sampled height* and position. **This makes no uv->mm scale assumption**, which is essential, because an
-  LSCM map is **conformal, not isometric**: it is globally area-scaled but the *local* mm-per-uv varies
-  across the chart, so a single global `1/tiling_scale` factor gets the apparent depth wrong. `dFdx(h)`
-  captures the true on-screen rate of change however the chart is stretched. This path is also what makes
-  the fast preview follow the UV editor: move an island and its uv - hence its shading - moves with it
-  (the mesh rebuilds on drag-end, `on_island_edited(finished)` -> `rebuild_preview()` ->
-  `rebuild_shaded_preview_mesh()`). The branch is uniform and the paint weight gates by multiply, so the
-  texture derivatives stay well defined. A triangle straddling a seam has a discontinuous uv -> the
-  `det~0` guard skips it (a localised preview-only artifact, never in the bake).
-
-**Parallax (triplanar path).** Perturbing the shading normal alone welds the pattern to the base surface:
-it does not slide as the camera orbits, and does not get deeper as `depth_mm` grows. The triplanar path
-therefore shades at the point the *displaced* surface would show at this pixel, found by **ray marching**
-(parallax occlusion mapping). A point at ray parameter `s`, i.e. `P + V-s` (`P` the base point, `V` the
-unit direction to the eye), sits at height `s-dot(V,n)` above the undisplaced surface. The displaced
-surface lives in a shell between the extreme values of `amp-(h - midlevel)` - taken from both ends of
-`h  in  [0,1]`, so it holds for an inverted layer and a raised midlevel too, where the surface sits *below*
-the undisplaced one. The march starts at the top of that shell, where the ray is outside the surface by
-construction, and steps inward until the ray height drops below the sampled height. That crossing *is*
-the visible point.
-
-Solving `Q = P + V-(H(Q)/dot(V,n))` by fixed-point iteration instead is geometrically exact but the
-divisor goes to zero edge-on; the sample then lands a large fraction of a tile away and the iteration
-oscillates, which reads as a second, flat copy of the pattern ghosted over the real one. Clamping the
-step to one tile does not help - a tile-sized shift lands on the neighbouring tile, the same pattern
-again. Offset limiting (stepping along the tangential part of `V`) is stable but understates parallax
-enough that the relief still flattens as soon as the camera tilts. Marching has neither problem.
-
-The hit is interpolated between the last two samples, which keeps `PARALLAX_STEPS` (24) affordable, and
-the whole march is skipped when sweeping the shell would move the sample point less than half a texel -
-the head-on case, so the common view pays almost nothing. The 140 variant samples with
-`textureLod(..., 0.0)` inside the loop, since implicit derivatives are undefined in non-uniform control
-flow. Two uniforms exist for this: `midlevel` (parallax needs the real height, not just its derivative)
-and `eye_model_pos` (the camera in the volume's local frame).
-
-Parallax cannot change the model's silhouette or cast shadows; the View row's Normal mode is one click
-away for that. The LSCM path stays plain Mikkelsen normal perturbation - it has no closed-form uv, so there is no cheap
-way to re-project a marched position. One further approximation: the GPU sampler's wrap mode stands in
-for `tile_enabled`/`tile_method`, so with tiling *off* the GPU repeats where the CPU returns 0 outside
-`[0,1)`.
-
-### On-canvas "Adjust Texture" gizmo
-
-A per-active-layer toggle ("Adjust placement") that disables painting and shows a flat pan panel (free
-2D drag on both axes) plus two arrows along the patch's own U/V axes (constrained single-axis drag).
-Anchored to the painted patch's centroid/average-normal (`compute_layer_paint_anchor()`). Hit-testing is
-screen-space distance/point-to-segment, not real 3D ray intersection against the handle geometry - simple
-and good enough at this handle size.
-
-### Projection frame overlay (ViewProjected)
-
-`src/slic3r/GUI/TextureProjectorFrame.hpp/.cpp` - a semi-transparent, resizable `wxFrame` the user
-drags **over the 3D view**, like a slide projector's gate. Whatever the model shows through it is what
-the texture is projected onto, and the window's border becomes the hard edge of the displacement.
-Press **Apply projection frame** and the gizmo reads the window's rectangle and commits it.
-
-The window is deliberately **dumb**: it owns no placement state and reports nothing continuously. Its
-position and size *are* the placement, read on demand at Apply - which is also when the expensive
-visible-facet raycast runs. So dragging it is free and nothing recomputes until asked.
-
-Plain 2D (`wxPaintDC`), not a `wxGLCanvas`: a second GL canvas would have to share the app's one real
-`wxGLContext`. It only ever draws a bitmap and a border.
-
-**The projective mapping (`apply_projection_frame()`)**. The frame defines a **screen-space** rectangle,
-but the bake samples from a **local-space** position, so the two have to be reconciled.
-`view_project_right/up` can only express an *affine* projection - exact under an orthographic camera, but
-wrong under perspective, where the near end of a part projects larger than the far end and no pair of
-axes reproduces that. So the layer instead stores a full projective map (`view_project_matrix`, row-major
-3x4, `uv = (row0-p/row2-p, row1-p/row2-p)`), built like this:
-
-- `K = projection - view - (instance - volume)`, i.e. local -> clip, the same product the renderer uses.
-  Note `Camera::get_projection_matrix()` is typed `Transform3d` (nominally affine) but its perspective
-  form explicitly writes a `(0, 0, -1, 0)` bottom row into the underlying 4x4, so `clip.w = -z_eye` is
-  genuinely carried. The build therefore multiplies **`.matrix()` products** (plain `Matrix4d`), never
-  `Transform3d` products, which would not compose that row correctly.
-- Window coordinates follow `igl::project`'s convention (as `CameraUtils::project` does), with y
-  measured downward. Writing `uv = (win - rect_origin) / rect_size` makes u and v affine in
-  `ndc = clip.xyz / clip.w`; multiplying through by `clip.w` leaves a plain linear combination of `K`'s
-  rows, which is exactly the 3x4 matrix - the perspective divide survives intact.
-- `w > 0` is checked rather than divided blindly. A point behind the projector has `w < 0` and divides
-  to a plausible-looking but **mirrored** uv - the classic way a projected decal reappears on the back
-  of a model. `project_uv_projective()` returns false there and the caller treats it as no height.
-
-The map already includes placement, so `apply_uv_transform()` is **not** applied on top of it - the
-window's own position and size are the placement, and the tiling/rotation/offset sliders would shove
-the result off the frame the user just aligned. A "Clear" button drops back to the affine path where
-those controls mean something again.
-
-Apply also sets `tile_enabled = false`, so `DecodedHeightTexture::sample()` returns 0 outside `[0,1)`
-and the border is a hard edge rather than the first seam of an endless repeat, and repaints the layer
-via `select_visible_faces(&matrix)` - the frame's uv square clips the selection, which both matches the
-paint to the border and keeps the ray queries proportional to the framed area instead of the model.
-
-Owned by the gizmo and **destroyed** (not just hidden) in `on_shutdown()`. Closing it only hides it, so
-reopening keeps it where it was left.
-
-### UV Editor pane
-
-`UVEditorCanvas` (`src/slic3r/GUI/UVEditorCanvas.hpp/.cpp`) - a standalone `wxGLCanvas` rendering the
-flattened LSCM islands (per-island wireframe + outline + fill) over the height texture (background
-quad tiled across the whole unwrap), with mouse pan/zoom. It is wrapped in a **`UVEditorPanel`**
-(same file) that adds a button row (Frame / Snap / Avg scale / Cut / Join / Unjoin) and a status line
-along the bottom naming the current gesture and the shortcuts in play. The *panel* is what is
-registered as a `wxAuiPaneInfo` pane on `Plater`'s `m_aui_mgr`; `Plater::show_uv_editor(bool)`
-shows/hides it (deferred via `CallAfter`, since the gizmo calls it mid-3D-frame), and
-`get_uv_editor_canvas()` returns the inner canvas the gizmo talks to.
-
-Deliberately **shares the app's one real `wxGLContext`** (`wxGetApp().init_glcontext(*this)`, the
-same call `View3D`/`Preview`/`AssembleView` make) rather than creating an independent context like
-`SkipPartCanvas` does elsewhere in this codebase - this is what lets it reuse the already-registered
-`"flat"`/`"flat_texture"` shaders and `GLModel` as-is, instead of needing its own shader
-compilation/VBO management.
-
-**Geometry is uploaded once, in the unwrap's own (raw, mm) coordinates**, one `GLModel` set per island;
-each island is then drawn through its own 2x3 affine (`island_transform_matrix()` composed with the
-layer's tiling/rotation/offset) passed as the `flat` shader's `view_model_matrix`. A drag updates one
-matrix per island and touches no vertex buffer - `on_island_edited(!finished)` calls only
-`set_island_transforms()`, and the full `set_islands()` rebuild happens solely when the unwrap itself
-changes (`unwrap_changed` in `update_uv_editor()`).
-
-**Gestures** (canvas-owned, reported to the gizmo as incremental deltas via `IslandEditFn`): left-drag
-= move, right-drag or **R** = rotate (hold **Shift** to snap to 15° steps - quantised on the
-*cumulative* rotation, not each delta, so it doesn't judder, and accumulated incrementally so it
-survives crossing +/-180°), **S** = scale (R/S modal, click/Enter to confirm, Esc to cancel), wheel =
-zoom about the cursor, middle-drag = pan, **Home**/**F** = frame all. Scale writes
-`TextureIsland::scale`; "Avg scale" (`average_island_scales()`) sets every island to the mean, so
-one island scaled by hand can be matched back to its neighbours' texel density. **Snap** (canvas-owned
-`m_snap_enabled`, toggled from the toolbar) sticks a dragged island's nearest boundary vertex onto a
-neighbouring island's at drag-*end* only - a magnet that re-applies mid-drag is very hard to pull out
-of. Toolbar commands the canvas can't service itself (Avg scale, Cut, Join, Unjoin) are forwarded to the
-gizmo via `CommandFn`; view-only ones (Frame, Snap) it handles directly.
-
-## File map
-
-**libslic3r (core, no GUI dependency):**
-- `src/libslic3r/TextureDisplacement.hpp/.cpp` - data model, bake algorithm, projection methods,
-  tiling, subdivision (uniform + adaptive longest-edge bisection), post-process smoothing
-  (`smooth_mesh_vertices()`), and `TextureDisplacementOptions` (the whole-stack settings). See doc
-  comments throughout, they're kept accurate and up to date.
-- `src/libslic3r/MeshBoolean.hpp/.cpp` - `parameterize_lscm()` and `remesh_isotropic()` in the `cgal`
-  sub-namespace, reusing the existing `CGALMesh`/`_EpicMesh`/conversion-helper infrastructure already
-  there for mesh boolean ops. CGAL includes: `Polygon_mesh_processing/border.h`,
-  `Polygon_mesh_processing/connected_components.h`, `Surface_mesh_parameterization/{Error_code,
-  LSCM_parameterizer_3, parameterize}.h`. No new dependency - CGAL 5.6.3 is already vendored and the
-  `Surface_mesh_parameterization` package headers were already present.
-- `src/libslic3r/Model.hpp/.cpp` - the 8 named `FacetsAnnotation` fields + accessor,
-  `texture_displacement_layers`, `texture_displacement_options`, and all the mirrored touch points
-  (see Data model above).
-
-**GUI:**
-- `src/slic3r/GUI/Gizmos/GLGizmoTextureDisplacement.hpp/.cpp` - the gizmo and its whole panel.
-- `src/slic3r/GUI/TextureLibrary.hpp/.cpp` - scans the shipped + user texture folders, imports an
-  arbitrary image into the user folder (converting it to the 8-bit grayscale PNG libslic3r decodes),
-  and loads a library file's bytes for a layer. The image->grayscale-PNG conversion lives here, on the
-  GUI side, because libslic3r has no image toolkit; both the import path and the "pick a shipped
-  texture" path go through the same one function.
-- `resources/textures/displacement/*.png` - the 10 shipped height maps (Bricks, Grid, Hexagons,
-  Knurl, Noise, Quilt, Studs, Waves, Weave, Wood Grain). All 512x512 8-bit grayscale and **seamless**
-  (each is periodic over the full image in both axes, so tiling shows no seam). Generated
-  procedurally; the whole `resources/` tree is installed recursively by CMake, so a new folder under
-  it ships with no build-system change.
-- `src/slic3r/GUI/Jobs/TextureDisplacementBakeJob.hpp/.cpp` - background bake commit.
-- `src/slic3r/GUI/Jobs/TextureDisplacementPreviewJob.hpp/.cpp` - background preview compute
-  (mirrors the bake job's shape but commits nothing to the Model).
-- `src/slic3r/GUI/TextureProjectorFrame.hpp/.cpp` - the semi-transparent projection-frame overlay for
-  ViewProjected layers (plain 2D `wxPaintDC`, no GL context - see its section above).
-- `src/slic3r/GUI/UVEditorCanvas.hpp/.cpp` - the 2D UV unwrap viewer widget.
-- `src/slic3r/GUI/Plater.hpp/.cpp` - `uv_editor_canvas` member, AUI pane registration,
-  `get_uv_editor_canvas()`/`show_uv_editor()`.
-- `src/slic3r/GUI/GLShadersManager.cpp` - registers `"texture_displacement_shaded"`.
-- `resources/shaders/{110,140}/texture_displacement_shaded.{vs,fs}` - the fast-preview shader.
-- `src/slic3r/GUI/Gizmos/GLGizmoPainterBase.hpp` - `PainterGizmoType::TEXTURE_DISPLACEMENT`.
-- `src/slic3r/GUI/Gizmos/GLGizmosManager.hpp/.cpp` - `EType::TextureDisplacement` registration.
-
-## Tests
-
-`tests/libslic3r/test_texture_displacement.cpp`. Covers `decode_height_texture` round-trip, empty-layer
-no-op, full-cube uniform displacement, a second layer over the same area contributing, all four blend
-modes (table-driven), the lowest layer ignoring its blend mode, border displace/pin, post-process
-smoothing and its mask guarantees, and adaptive subdivision: conformality (`every_edge_used_twice` on a
-partially-refined cube - an exact crack detector for a closed mesh), the target edge length actually
-being reached, the triangle budget capping the result without opening a crack, curvature-driven
-refinement (a Gaussian hill refines at its centre, a linear ramp adds nothing), and the max-edge
-baseline.
-
-`BUILD_TESTS` is `OFF` in the checked-in build cache; flip it on to run them:
-
-    cmake -S . -B build -DBUILD_TESTS=ON
-    cmake --build build --config Release --target libslic3r_tests -- -m
-    ./build/tests/libslic3r/Release/libslic3r_tests.exe "[TextureDisplacement]" --order rand

TEXTURE_DISPLACEMENT_GUIDE.md

@@ -1,326 +0,0 @@
-# Texture Displacement - Feature & Controls Guide
-
-Texture Displacement is a paint-style gizmo that stamps height-map textures onto a model's surface
-and turns them into real relief - engraved or embossed detail - either as a live preview or baked
-into actual mesh geometry. You paint where the texture applies, stack multiple textures as blended
-layers, choose how each is projected onto the surface, and (for the unwrap projection) lay the result
-out by hand in a dedicated 2D **UV Editor** pane.
-
-This document describes every feature and control. For the internal architecture and algorithms, see
-`TEXTURE_DISPLACEMENT.md`.
-
----
-
-## Table of contents
-
-1. [Quick start](#quick-start)
-2. [Entering the tool](#entering-the-tool)
-3. [Selection modes](#selection-modes)
-4. [View modes](#view-modes)
-5. [Auto update](#auto-update)
-6. [Texture layers](#texture-layers)
-7. [Per-layer settings](#per-layer-settings)
-8. [Projection methods](#projection-methods)
-9. [The UV Editor](#the-uv-editor)
-10. [Seams](#seams)
-11. [Adjust placement (on-model)](#adjust-placement-on-model)
-12. [Preparing the mesh: Subdivide & Remesh](#preparing-the-mesh-subdivide--remesh)
-13. [Baking & resetting](#baking--resetting)
-14. [Controls reference](#controls-reference)
-15. [Tips & limitations](#tips--limitations)
-
----
-
-## Quick start
-
-1. Select an object and open the **Texture displacement** gizmo from the left toolbar.
-2. A texture layer is added automatically. Pick a texture from the layer's picker, or import your own.
-3. **Paint** the area you want the texture to affect (or press **Select whole model**).
-4. The relief appears live on the model. Tune **Depth**, **Tile size**, **Rotation**, etc.
-5. If the model is low-poly, use **Subdivide** or **Remesh** so there are enough vertices for detail.
-6. Press **Bake** to convert the preview into real geometry, or leave it as a live preview.
-
-> The tool only ever affects the **painted** area. Everything you don't paint keeps its original
-> surface, and bake blends the relief seamlessly into it.
-
----
-
-## Entering the tool
-
-The gizmo lives on the left gizmo toolbar (icon: `toolbar_texture_displacement.svg`). Its settings
-panel opens beside the toolbar. You can **Dock panel / Undock panel** (top of the panel) to pin it or
-float it freely over the 3D view, and **Close** at the bottom exits the gizmo.
-
-When you first open the tool on a never-textured object it starts with **one texture layer already
-added**, so you can paint straight away.
-
----
-
-## Selection modes
-
-Choose *how* you paint. All three write into the **active layer's** mask.
-
-| Mode | What it does |
-|------|--------------|
-| **Brush** | Free-hand painting with a round brush. Shows a **Brush size** slider and a **Circle / Sphere** choice (circle = surface disc, sphere = 3D ball that also paints around curves). |
-| **Face** | Click a single triangle to paint it. |
-| **Connected area** | Click to flood-fill a region; the **Angle threshold** slider limits how far the fill spreads across changes in surface angle. |
-
-- **Select whole model** - marks the entire model as painted for the active layer, instead of
-  brushing it by hand.
-
----
-
-## View modes
-
-A row of icon buttons labelled **View** controls how the painted area is shown. The first four are a
-radio group; **Wireframe** is an independent toggle. Hover any icon for its tooltip.
-
-| View | Meaning |
-|------|---------|
-| **Normal** | The true displaced geometry - exactly what **Bake** produces. Rebuilt in the background. |
-| **Fast** | A GPU shaded approximation of the *active layer only*. No real geometry movement - quick to update, not exact. Best while tuning or dragging islands. |
-| **Checker** | A test grid painted over the unwrap so you can see stretching (squares stay square where the map isn't distorted). |
-| **Distortion** | A blue->green->red heatmap of how much each area is compressed or stretched in UV space. Needs the **Unwrap (LSCM)** projection. |
-| **Wireframe** | Overlays the mesh edges (white). Independent of the view above; in **Normal** view it sits on the displaced surface. |
-
----
-
-## Auto update
-
-**Auto update** (on by default) rebuilds the true displaced geometry as soon as *anything* changes -
-painting, swapping textures, moving sliders. Turn it off on very heavy models to only rebuild when you
-release a slider (painting still updates on stroke end).
-
----
-
-## Texture layers
-
-You can stack up to **8** texture layers. Each has its own independent paint mask, its own texture,
-and its own parameters, and they combine in slot order like layers in an image editor.
-
-- **Add a layer** - the **+ icon** to the right of the *Texture layers* heading (reuses the tool icon
-  for now).
-- **Remove** - the button on each layer's header row.
-- **Active layer** - click a layer's header (or anywhere in its block) to make it active. The active
-  layer is the one you paint into and the one whose block is tinted. Only one layer is active at a time.
-- **Erase all** - clears the active layer's paint.
-
-Each layer shows a texture **picker** (large preview + name). Open it to choose from the shipped
-library or import your own image (any png/jpg/bmp; it's converted to an 8-bit grayscale height map and
-copied into your user texture folder so app updates can't overwrite it).
-
----
-
-## Per-layer settings
-
-| Control | Range / options | What it does |
-|---------|-----------------|--------------|
-| **Depth (mm)** | 0.01-10 (log) | Maximum displacement along the surface normal. |
-| **Tile size (mm)** | 0.2-200 (log) | Physical size of one texture tile on the surface. |
-| **Rotation** | 0-360° | Rotates the texture on the surface. |
-| **Midlevel** | 0-10 | The grey level that means "don't move". At 0 the texture only pushes outward; raise it and darker texels cut *inward* (one map both embosses and engraves). 0.5 makes mid-grey neutral. |
-| **Smoothing** | 0-1 | Blurs the height texture before it displaces - rounds hard edges and removes speckle without needing a softer source image. |
-| **Edge smoothing** | checkbox + **Edge amount** 0-1 | Fades the relief to flat toward the *edge of the painted area*, so it blends into the surrounding surface. A small amount softens only a thin band at the very edge; the maximum flattens the whole painted face. |
-| **Invert** | checkbox | Flips the height map (peaks become valleys). |
-| **Blend** | Add / Subtract / Multiply / Divide | How this layer combines with the layers **below** it where they overlap. Add/Subtract pile relief on or carve it away; Multiply/Divide scale the relief underneath (a mask). The lowest painted layer is the **Base** and always behaves additively. |
-| **Tile** | checkbox + **Repeat / Mirrored repeat** | When off, the texture is placed once (a decal) instead of repeating. Mirrored repeat flips every other tile to hide seams. |
-| **Projection** | see below | How the texture is mapped onto the painted surface. |
-
-> **Midlevel warning:** cutting inward can fold the surface through itself in sharp concave corners or
-> thin walls. Keep Depth small relative to the feature you're cutting into; the panel warns when a deep
-> inward setting is risky.
-
----
-
-## Projection methods
-
-How the 2D texture is wrapped onto the 3D painted area.
-
-| Method | Best for | Notes |
-|--------|----------|-------|
-| **Triplanar (blended)** | Patches wrapping around edges | Projects from all three axes at once and blends, so there's no seam across a sharp edge. |
-| **Cylindrical** | Round, tube-like selections | Wraps the texture around the patch's own centre/axis. |
-| **Spherical** | Ball-like selections | Longitude/latitude wrap around the patch centre. |
-| **Unwrap (LSCM)** | Flat, controlled layout | A real conformal unwrap. Cuts the area into pieces at sharp edges (see **Seam angle**), flattens each, and lets you lay them out by hand in the **UV Editor**. Unlocks Checker/Distortion, seams, and island editing. |
-| **From view** | Decals / slide-projector look | Projects straight onto the surface from the current camera direction. Use **Capture current view** to re-lay it from wherever you're looking. |
-
-### LSCM-only controls
-
-These appear when a layer uses **Unwrap (LSCM)**:
-
-- **Seam angle** (5-90°) - edges sharper than this are cut so each piece lies flat. Lower cuts more
-  (less stretching, more seams); raise to keep more in one piece. A box's 90° corners are cut by
-  default. *Ignored once you've marked any seam by hand* (your seams then define the pieces).
-- **Connect islands** (on by default) - lays the unwrap out as a **connected net**: pieces that share
-  an edge are unfolded next to each other (a cube becomes a joined net instead of six loose squares).
-  They stay separate islands, so you can still move any of them by hand. Turn off for the classic
-  packed-grid layout.
-- **Open UV editor** - shows the flattened unwrap in a side pane (see below). Opens *only* when you
-  turn this on - it never pops up on its own.
-- **Mark seams** / **Path** / **Clear seams** - see [Seams](#seams).
-- An **Unwrap: N islands, F faces, V verts** read-out tells you what the unwrap actually produced.
-
----
-
-## The UV Editor
-
-A dockable 2D pane (enable **Open UV editor** on an LSCM layer) showing the flattened unwrap over the
-height texture. Islands are the flattened pieces; you can rearrange them freely - nothing re-packs them
-behind your back. Moving an island updates the model **live** (in Fast view it tracks the cursor
-smoothly, via a shader uniform - no rebuild until you release).
-
-### Navigation
-
-| Action | Control |
-|--------|---------|
-| Pan | Middle-drag |
-| Zoom | Mouse wheel (zooms about the cursor) |
-| Frame everything | **Home** or **F**, or the **Frame** toolbar button |
-
-### Editing an island
-
-| Action | Control |
-|--------|---------|
-| Select | Left-click an island |
-| Move | Left-drag |
-| Rotate | Right-drag, or press **R** then move the mouse (click/Enter to confirm, Esc to cancel) |
-| Rotate snapped | Hold **Shift** while rotating - snaps to **global** 15° marks (0/15/30...). A protractor dial with tick marks and the current angle is shown. |
-| Scale | Press **S** then move the mouse (click/Enter to confirm, Esc to cancel) |
-| Undo / Redo | **Ctrl+Z** / **Ctrl+Shift+Z** or **Ctrl+Y** |
-
-The **selected** island gets a bold light-green outline and a brighter wireframe; unselected islands
-are a translucent light-green wash. The texture underneath repeats exactly as it will when baked.
-A **status line** along the bottom always names the current gesture and the shortcuts in play.
-
-### Toolbar
-
-| Button | Action |
-|--------|--------|
-| **Frame** | Frame all islands (same as Home). |
-| **Snap** | Toggle magnetic snapping - a dragged island sticks its boundary to a neighbour's when they come close. |
-| **Avg scale** | Give every island the same texel density (Blender's "Average Islands Scale"). |
-| **Cut** | Split the selected island across its long axis (useful for very long islands). |
-| **Join** | Unfold the selected island onto its nearest neighbour along their shared edge - keeps both as separate islands with their own borders. |
-| **Unjoin** | Send the selected island back to its own packed position. |
-
-> **Checker / Distortion in the UV editor:** selecting those View modes also colours the UV pane - a
-> checker background, or a per-island distortion heatmap - so you can judge stretch in 2D as well as
-> on the model.
-
----
-
-## Seams
-
-Seams are edges the unwrap is forced to cut along, on top of whatever the Seam angle cuts - the
-Blender "mark seam" workflow. They let you control exactly where the unwrap splits.
-
-Enable **Mark seams** on an active LSCM layer, then:
-
-- **Click an edge** on the model to mark it (it turns **red**); click a red edge again to unmark it.
-  The edge under the cursor is highlighted **yellow** so you can see what a click will toggle.
-- **Path mode** (the **Path** checkbox) - for dense meshes where clicking each edge is tedious: click a
-  start point, then an end point, and the whole **shortest path** between them is seamed at once. It
-  chains (each click extends from the last point); the start vertex is shown in **green**.
-- **Ctrl+drag** rotates/pans the camera while in seam mode.
-- **Clear seams** removes them all.
-
-Once any seam is marked, the automatic Seam-angle cutting is disabled so *your* seams define the
-islands - pieces you leave un-seamed merge together.
-
----
-
-## Adjust placement (on-model)
-
-**Adjust placement** (on an active layer) lets you position the texture by dragging a handle on the
-model instead of nudging the Rotation/offset numbers. The handle is a flat panel in the patch's
-tangent plane (drag anywhere on it to move freely) plus U/V arrows for single-axis nudges. It's
-anchored to the painted patch, so paint something first.
-
----
-
-## Preparing the mesh: Subdivide & Remesh
-
-Displacement can only move vertices that exist, so a coarse model needs more of them first.
-
-### Subdivide
-
-Splits every triangle into four, **1-5 times** (each step roughly quadruples the triangle count).
-
-- **Subdivide steps** (1-5) - how many times to split.
-- **Preview subdivision** - shows the result as a **cyan wireframe** without changing the model.
-- **Apply** - commits the subdivision to the geometry.
-- **Done** - ends the preview and leaves the model as it is.
-
-### Remesh
-
-Rebuilds the whole model with triangles close to a target edge length - evens out a mesh with wildly
-varying triangle sizes (CGAL isotropic remeshing).
-
-- **Target edge (mm)** - desired triangle edge length (seeded to the model's current average).
-- **Remesh** - splits the big triangles and merges the small ones to that size.
-
-> Both Subdivide-Apply and Remesh **replace the geometry** and clear any *not-yet-baked* paint on it
-> (already-baked relief is kept). If you had the mesh **Wireframe** on before, it stays on afterward.
-
----
-
-## Baking & resetting
-
-- **Bake** - converts the current preview into real, permanent mesh geometry, restricted to the
-  painted area. Runs in the background; the button shows *Baking...* while it works.
-- **Erase all** - clears the active layer's paint.
-
-Baking is the exact same algorithm as the **Normal** preview, so what you see is what you get.
-
----
-
-## Controls reference
-
-### Mouse - 3D view (while painting)
-
-| Input | Action |
-|-------|--------|
-| Left-drag | Paint the active layer |
-| Ctrl + drag | Rotate / pan the camera (works in seam mode too) |
-| Wheel | Zoom |
-
-### Mouse & keys - UV Editor
-
-| Input | Action |
-|-------|--------|
-| Left-click | Select island |
-| Left-drag | Move island |
-| Right-drag | Rotate island |
-| **R** / **S** | Modal rotate / scale (mouse drives it, click or Enter confirms, Esc cancels) |
-| **Shift** (while rotating) | Snap to global 15° marks |
-| Middle-drag | Pan |
-| Wheel | Zoom about cursor |
-| **Home** / **F** | Frame all islands |
-| **Ctrl+Z** / **Ctrl+Shift+Z** / **Ctrl+Y** | Undo / redo |
-
-### Seam mode
-
-| Input | Action |
-|-------|--------|
-| Click edge | Mark / unmark a seam (yellow = hover, red = marked) |
-| Click (Path mode) | Set start, then seam the shortest path to the next click |
-| Ctrl + drag | Rotate / pan camera |
-
----
-
-## Tips & limitations
-
-- **Paint first, then bake.** The preview is free to explore; only Bake changes the real mesh.
-- **Not enough detail?** Subdivide or Remesh before painting fine textures.
-- **Inward cuts** (high Midlevel + big Depth) can self-intersect on thin walls or sharp concave
-  corners - keep Depth modest there.
-- **Fast vs Normal:** Fast preview only shades the relief and shows only the active layer; use it for quick
-  tuning and smooth UV dragging, but trust **Normal**/**Bake** for the exact result.
-- **Topology changes drop unbaked paint.** Subdivide-Apply, Remesh, and Simplify replace the mesh, and
-  texture-displacement paint isn't remapped across that change (already-baked relief is unaffected).
-- **Island placements** are tied to the current unwrap. Re-painting or changing the Seam angle can
-  re-segment the charts and renumber them, so a re-unwrap re-lays the connected net and discards
-  hand placements made before it.
-- **Connect islands** is on by default; turn it off (per layer) for the classic packed-grid layout, or
-  if an unfold looks wrong on an unusual mesh.

src/libslic3r/Color.hpp

@@ -6,6 +6,8 @@
 #include <array>
 #include <algorithm>
 
+#include <cassert>
+
 namespace Slic3r {
 using RGB = std::array<float, 3>;
 using RGBA = std::array<float, 4>;

src/libslic3r/GCode.cpp

@@ -7310,12 +7310,12 @@ static std::unique_ptr<EdgeGrid::Grid> calculate_layer_edge_grid(const Layer& la
     return out;
 }
 
-std::string GCode::extrude_loop(const ExtrusionLoop&        loop_ref,
-                                const std::string&          description,
-                                double                      speed,
-                                const ExtrusionEntitiesPtr& region_perimeters,
-                                const Point*                start_point,
-                                const WipeInwardSupport*     wipe_support)
+std::string GCode::extrude_loop(const ExtrusionLoop&                       loop_ref,
+                                const std::string&                         description,
+                                double                                     speed,
+                                const std::vector<const ExtrusionEntity*>& region_perimeters,
+                                const Point*                               start_point,
+                                const WipeInwardSupport*                   wipe_support)
 {
     // get a copy; don't modify the orientation of the original loop object otherwise
     // next copies (if any) would not detect the correct orientation
@@ -7659,11 +7659,11 @@ std::string GCode::extrude_multi_path(const ExtrusionMultiPath& multipath, const
     return gcode;
 }
 
-std::string GCode::extrude_entity(const ExtrusionEntity&      entity,
-                                  const std::string&          description,
-                                  double                      speed,
-                                  const ExtrusionEntitiesPtr& region_perimeters,
-                                  const WipeInwardSupport*     wipe_support)
+std::string GCode::extrude_entity(const ExtrusionEntity&                     entity,
+                                  const std::string&                         description,
+                                  double                                     speed,
+                                  const std::vector<const ExtrusionEntity*>& region_perimeters,
+                                  const WipeInwardSupport*                   wipe_support)
 {
     if (const ExtrusionPath* path = dynamic_cast<const ExtrusionPath*>(&entity))
         return this->extrude_path(*path, description, speed);
@@ -7754,23 +7754,32 @@ std::string GCode::extrude_perimeters(const Print &print, const std::vector<Obje
 // Chain the paths hierarchically by a greedy algorithm to minimize a travel distance.
 std::string GCode::extrude_infill(const Print &print, const std::vector<ObjectByExtruder::Island::Region> &by_region, bool ironing)
 {
-    std::string 		 gcode;
-    ExtrusionEntitiesPtr extrusions;
-    const char*          extrusion_name = ironing ? "ironing" : "infill";
+    std::string                                   gcode;
+    std::vector<const ExtrusionEntity*>           extrusions;
+    std::vector<std::unique_ptr<ExtrusionEntity>> reversed;
+    const char*                                   extrusion_name = ironing ? "ironing" : "infill";
     for (const ObjectByExtruder::Island::Region &region : by_region)
         if (! region.infills.empty()) {
             extrusions.clear();
             extrusions.reserve(region.infills.size());
-            for (ExtrusionEntity *ee : region.infills)
+            for (const ExtrusionEntity *ee : region.infills)
                 if ((ee->role() == erIroning) == ironing)
                     extrusions.emplace_back(ee);
             if (! extrusions.empty()) {
                 m_config.apply(print.get_print_region(&region - &by_region.front()).config());
-                chain_and_reorder_extrusion_entities(extrusions, m_last_pos.to_point());
+                reversed.clear();
+                chain_and_reorder_extrusion_entities(extrusions, m_last_pos.to_point(), reversed);
+                // The reversed copies are in chain order.
+                auto next_reversed = reversed.begin();
                 for (const ExtrusionEntity *fill : extrusions) {
+                    ExtrusionEntity *own_copy = next_reversed != reversed.end() && next_reversed->get() == fill ? (next_reversed++)->get() : nullptr;
                     auto *eec = dynamic_cast<const ExtrusionEntityCollection*>(fill);
                     if (eec) {
-                        for (ExtrusionEntity *ee : eec->chained_path_from(m_last_pos.to_point()).entities)
+                        // A reversed copy is owned here and can be moved from.
+                        ExtrusionEntityCollection chained = own_copy ? std::move(static_cast<ExtrusionEntityCollection&>(*own_copy)) : ExtrusionEntityCollection(*eec);
+                        if (!chained.no_sort)
+                            chain_and_reorder_extrusion_entities(chained.entities, m_last_pos.to_point());
+                        for (ExtrusionEntity *ee : chained.entities)
                             gcode += this->extrude_entity(*ee, extrusion_name);
                     } else
                         gcode += this->extrude_entity(*fill, extrusion_name);
@@ -7808,9 +7817,9 @@ std::string GCode::extrude_support(const ExtrusionEntityCollection &support_fill
     std::string gcode;
     if (!support_fills.entities.empty()) {
 
-        ExtrusionEntitiesPtr extrusions;
+        std::vector<const ExtrusionEntity*> extrusions;
         extrusions.reserve(support_fills.entities.size());
-        for (ExtrusionEntity* ee : support_fills.entities) {
+        for (const ExtrusionEntity* ee : support_fills.entities) {
             const auto role = ee->role();
             if ((role == support_extrusion_role) || (support_extrusion_role == erMixed && role != erIroning)) {
                 extrusions.emplace_back(ee);
@@ -7819,9 +7828,10 @@ std::string GCode::extrude_support(const ExtrusionEntityCollection &support_fill
         if (extrusions.empty())
             return gcode;
 
+        std::vector<std::unique_ptr<ExtrusionEntity>> reversed;
         //ORCA: Respect no_sort to preserve support base outline->fill order.
         if (!support_fills.no_sort)
-            chain_and_reorder_extrusion_entities(extrusions, m_last_pos.to_point());
+            chain_and_reorder_extrusion_entities(extrusions, m_last_pos.to_point(), reversed);
 
         for (const ExtrusionEntity *ee : extrusions) {
             ExtrusionRole role = ee->role();
@@ -10054,8 +10064,8 @@ const std::vector<GCode::ObjectByExtruder::Island::Region>& GCode::ObjectByExtru
         // Now we are going to iterate through perimeters and infills and pick ones that are supposed to be printed
         // References are used so that we don't have to repeat the same code
         for (int iter = 0; iter < 2; ++iter) {
-            const ExtrusionEntitiesPtr&										entities    = (iter ? reg.infills : reg.perimeters);
-            ExtrusionEntitiesPtr&   										target_eec  = (iter ? by_region_per_copy_cache.back().infills : by_region_per_copy_cache.back().perimeters);
+            const std::vector<const ExtrusionEntity*>&						entities    = (iter ? reg.infills : reg.perimeters);
+            std::vector<const ExtrusionEntity*>&							target_eec  = (iter ? by_region_per_copy_cache.back().infills : by_region_per_copy_cache.back().perimeters);
             const std::vector<const WipingExtrusions::ExtruderPerCopy*>& 	overrides   = (iter ? reg.infills_overrides : reg.perimeters_overrides);
 
             // Now the most important thing - which extrusion should we print.
@@ -10090,7 +10100,7 @@ const std::vector<GCode::ObjectByExtruder::Island::Region>& GCode::ObjectByExtru
 void GCode::ObjectByExtruder::Island::Region::append(const Type type, const ExtrusionEntityCollection* eec, const WipingExtrusions::ExtruderPerCopy* copies_extruder)
 {
     // We are going to manipulate either perimeters or infills, exactly in the same way. Let's create pointers to the proper structure to not repeat ourselves:
-    ExtrusionEntitiesPtr*									perimeters_or_infills;
+    std::vector<const ExtrusionEntity*>*					perimeters_or_infills;
     std::vector<const WipingExtrusions::ExtruderPerCopy*>* 	perimeters_or_infills_overrides;
 
     switch (type) {
@@ -10114,7 +10124,7 @@ void GCode::ObjectByExtruder::Island::Region::append(const Type type, const Extr
         for (auto* ee : eec->entities)
             perimeters_or_infills->emplace_back(ee);
     } else
-        perimeters_or_infills->emplace_back(const_cast<ExtrusionEntityCollection*>(eec));
+        perimeters_or_infills->emplace_back(eec);
 
     if (copies_extruder != nullptr) {
         // Don't reallocate overrides if not needed.

src/libslic3r/GCode.hpp

@@ -450,19 +450,19 @@ private:
                                                            double &y_acceleration_limit_res, double &accumulated_mass_res);
     // Orca: pass the complete collection of region perimeters to the extrude loop to check whether the wipe before external loop
     // should be executed
-    std::string extrude_entity(const ExtrusionEntity&      entity,
-                               const std::string&          description       = "",
-                               double                      speed             = -1.,
-                               const ExtrusionEntitiesPtr& region_perimeters = ExtrusionEntitiesPtr(),
-                               const WipeInwardSupport*     wipe_support      = nullptr);
+    std::string extrude_entity(const ExtrusionEntity&                     entity,
+                               const std::string&                         description       = "",
+                               double                                     speed             = -1.,
+                               const std::vector<const ExtrusionEntity*>& region_perimeters = {},
+                               const WipeInwardSupport*                   wipe_support      = nullptr);
     // Orca: pass the complete collection of region perimeters to the extrude loop to check whether the wipe before external loop
     // should be executed
-    std::string extrude_loop(const ExtrusionLoop&        loop,
-                             const std::string&          description,
-                             double                      speed             = -1.,
-                             const ExtrusionEntitiesPtr& region_perimeters = ExtrusionEntitiesPtr(),
-                             const Point*                start_point       = nullptr,
-                             const WipeInwardSupport*     wipe_support      = nullptr);
+    std::string extrude_loop(const ExtrusionLoop&                       loop,
+                             const std::string&                         description,
+                             double                                     speed             = -1.,
+                             const std::vector<const ExtrusionEntity*>& region_perimeters = {},
+                             const Point*                               start_point       = nullptr,
+                             const WipeInwardSupport*                   wipe_support      = nullptr);
     std::string extrude_multi_path(const ExtrusionMultiPath& multipath, const std::string& description = "", double speed = -1.);
     std::string extrude_path(const ExtrusionPath& path, const std::string& description = "", double speed = -1.);
 
@@ -493,10 +493,9 @@ private:
         {
             struct Region {
             	// Non-owned references to LayerRegion::perimeters::entities
-            	// std::vector<const ExtrusionEntity*> would be better here, but there is no way in C++ to convert from std::vector<T*> std::vector<const T*> without copying.
-                ExtrusionEntitiesPtr perimeters;
+                std::vector<const ExtrusionEntity*> perimeters;
             	// Non-owned references to LayerRegion::fills::entities
-                ExtrusionEntitiesPtr infills;
+                std::vector<const ExtrusionEntity*> infills;
 
                 std::vector<const WipingExtrusions::ExtruderPerCopy*> infills_overrides;
                 std::vector<const WipingExtrusions::ExtruderPerCopy*> perimeters_overrides;

src/libslic3r/PresetBundle.cpp

@@ -588,13 +588,15 @@ const PresetBundle *PresetBundle::load_source_vendor(const boost::filesystem::pa
         return it->second.get();
 
     // The library loads with no base of its own, so the tree a vendor inherits from
-    // is the same one that resolves the library's own presets.
-    const std::string   library_file = std::string(ORCA_FILAMENT_LIBRARY);
-    const PresetBundle *library      = nullptr;
-    if (vendor_id != ORCA_FILAMENT_LIBRARY &&
-        (boost::filesystem::is_regular_file(root_dir / (library_file + ".json")) ||
-         (allow_cache && boost::filesystem::is_regular_file(root_dir / (library_file + ".opc"))))) {
-        library = load_source_vendor(root_dir, ORCA_FILAMENT_LIBRARY, compatibility_rule, error, allow_cache);
+    // is the same one that resolves the library's own presets. It is only a base, so
+    // it comes from its cache whenever that is all that is installed, even when the
+    // vendor itself is parsed (a vendor updated over the air).
+    const std::string   library_file       = std::string(ORCA_FILAMENT_LIBRARY);
+    const bool          library_json       = boost::filesystem::is_regular_file(root_dir / (library_file + ".json"));
+    const bool          library_cache_only = !library_json && boost::filesystem::is_regular_file(root_dir / (library_file + ".opc"));
+    const PresetBundle *library            = nullptr;
+    if (vendor_id != ORCA_FILAMENT_LIBRARY && (library_json || library_cache_only)) {
+        library = load_source_vendor(root_dir, ORCA_FILAMENT_LIBRARY, compatibility_rule, error, allow_cache || library_cache_only);
         if (library == nullptr) {
             error = "OrcaFilamentLibrary contains invalid presets";
             return nullptr;
@@ -2527,7 +2529,7 @@ void PresetBundle::clear_printer_hold_aliases()
 
 //BBS: add json related logic, load system presets from json
 std::pair<PresetsConfigSubstitutions, std::string> PresetBundle::load_system_presets_from_json(
-    ForwardCompatibilitySubstitutionRule compatibility_rule, bool allow_cache)
+    ForwardCompatibilitySubstitutionRule compatibility_rule, bool write_caches)
 {
     //BBS: add config related logs
     BOOST_LOG_TRIVIAL(debug) << __FUNCTION__ << boost::format(" enter, compatibility_rule %1%")%compatibility_rule;
@@ -2547,14 +2549,14 @@ std::pair<PresetsConfigSubstitutions, std::string> PresetBundle::load_system_pre
     // The vendors below are loaded whole and against each other — the filament
     // library first, then every other vendor with it as the base — so each parse
     // is complete enough to be worth caching.
-    m_generate_vendor_caches = allow_cache && (m_generate_vendor_caches || !validation_mode);
+    m_generate_vendor_caches = write_caches && (m_generate_vendor_caches || !validation_mode);
 
     // Sorted, so any duplicate-preset warning comes out in the same order on every run.
     std::vector<VendorSource> vendors;
     for (const std::string& name : vendor_names_in(dir))
         if (name == ORCA_FILAMENT_LIBRARY || !(validation_mode && !vendor_to_validate.empty() && name != vendor_to_validate))
             vendors.push_back({ name, dir });
-    auto result = this->load_vendors(vendors, compatibility_rule, allow_cache);
+    auto result = this->load_vendors(vendors, compatibility_rule, true);
 
 	this->update_system_maps();
 

src/libslic3r/PresetBundle.hpp

@@ -839,7 +839,9 @@ private:
 
     //std::pair<PresetsConfigSubstitutions, std::string> load_system_presets(ForwardCompatibilitySubstitutionRule compatibility_rule);
     //BBS: add json related logic
-    std::pair<PresetsConfigSubstitutions, std::string> load_system_presets_from_json(ForwardCompatibilitySubstitutionRule compatibility_rule, bool allow_cache = true);
+    // Reads each vendor from its preset cache where one covers the profile, as every load does.
+    // write_caches = false keeps a read-only load from writing caches into the data directory.
+    std::pair<PresetsConfigSubstitutions, std::string> load_system_presets_from_json(ForwardCompatibilitySubstitutionRule compatibility_rule, bool write_caches = true);
     // Update the multicolor information for filaments.
     void update_filament_multi_color();
     // Update renamed_from and alias maps of system profiles.

src/libslic3r/ShortestPath.cpp

@@ -1024,13 +1024,14 @@ std::vector<std::pair<size_t, bool>> chain_segments_greedy2(SegmentEndPointFunc
 	return chain_segments_greedy_constrained_reversals2_<PointType, SegmentEndPointFunc, false, decltype(could_reverse_func)>(end_point_func, could_reverse_func, num_segments, start_near);
 }
 
-std::vector<std::pair<size_t, bool>> chain_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const Point *start_near)
+template<typename EntityPtr>
+static std::vector<std::pair<size_t, bool>> chain_extrusion_entities_impl(const std::vector<EntityPtr> &entities, const Point *start_near)
 {
 	auto segment_end_point = [&entities](size_t idx, bool first_point) -> Point { return first_point ? entities[idx]->first_point() : entities[idx]->last_point(); };
 	auto could_reverse = [&entities](size_t idx) { const ExtrusionEntity *ee = entities[idx]; return ee->is_loop() || ee->can_reverse(); };
 	std::vector<std::pair<size_t, bool>> out = chain_segments_greedy_constrained_reversals<Point, decltype(segment_end_point), decltype(could_reverse)>(segment_end_point, could_reverse, entities.size(), start_near);
 	for (std::pair<size_t, bool> &segment : out) {
-		ExtrusionEntity *ee = entities[segment.first];
+		const ExtrusionEntity *ee = entities[segment.first];
 		if (ee->is_loop())
 			// Ignore reversals for loops, as the start point equals the end point.
 			segment.second = false;
@@ -1040,6 +1041,20 @@ std::vector<std::pair<size_t, bool>> chain_extrusion_entities(std::vector<Extrus
 	return out;
 }
 
+std::vector<std::pair<size_t, bool>> chain_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const Point *start_near)
+{
+	return chain_extrusion_entities_impl(entities, start_near);
+}
+
+// Orca: Reordering queries first_point() / last_point(); drop entities that cannot provide valid endpoints.
+template<typename EntityPtr>
+static void remove_entities_without_endpoints(std::vector<EntityPtr> &entities)
+{
+    entities.erase(std::remove_if(entities.begin(), entities.end(),
+                                  [](const ExtrusionEntity *entity) { return !extrusion_entity_has_endpoints(entity); }),
+                   entities.end());
+}
+
 void reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const std::vector<std::pair<size_t, bool>> &chain)
 {
 	assert(entities.size() == chain.size());
@@ -1061,14 +1076,27 @@ void chain_and_reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entitie
 
 void chain_and_reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const Point *start_near)
 {
-    // Orca: Reordering queries first_point() / last_point(); drop entities that cannot provide valid endpoints.
-    entities.erase(std::remove_if(entities.begin(), entities.end(), [](ExtrusionEntity *entity) {
-        return !extrusion_entity_has_endpoints(entity);
-    }),
-                   entities.end());
+    remove_entities_without_endpoints(entities);
 	reorder_extrusion_entities(entities, chain_extrusion_entities(entities, start_near));
 }
 
+void chain_and_reorder_extrusion_entities(std::vector<const ExtrusionEntity*> &entities, const Point &start_near,
+                                          std::vector<std::unique_ptr<ExtrusionEntity>> &reversed_clones)
+{
+    remove_entities_without_endpoints(entities);
+    std::vector<const ExtrusionEntity*> out;
+    out.reserve(entities.size());
+    for (const auto &[idx, reverse] : chain_extrusion_entities_impl(entities, &start_near)) {
+        if (reverse) {
+            ExtrusionEntity *clone = reversed_clones.emplace_back(entities[idx]->clone()).get();
+            clone->reverse();
+            out.emplace_back(clone);
+        } else
+            out.emplace_back(entities[idx]);
+    }
+    entities.swap(out);
+}
+
 std::vector<std::pair<size_t, bool>> chain_extrusion_paths(std::vector<ExtrusionPath> &extrusion_paths, const Point *start_near)
 {
 	auto segment_end_point = [&extrusion_paths](size_t idx, bool first_point) -> Point { return first_point ? extrusion_paths[idx].first_point() : extrusion_paths[idx].last_point(); };

src/libslic3r/ShortestPath.hpp

@@ -5,6 +5,7 @@
 #include "ExtrusionEntity.hpp"
 #include "Point.hpp"
 
+#include <memory>
 #include <utility>
 #include <vector>
 
@@ -24,6 +25,9 @@ std::vector<std::pair<size_t, bool>> chain_extrusion_entities(std::vector<Extrus
 void                                 reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const std::vector<std::pair<size_t, bool>> &chain);
 void                                 chain_and_reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const Point &start_near);
 void                                 chain_and_reorder_extrusion_entities(std::vector<ExtrusionEntity*> &entities, const Point *start_near = nullptr);
+// Each entity the chain reverses is replaced by a reversed clone that reversed_clones owns, so the originals stay unchanged.
+void                                 chain_and_reorder_extrusion_entities(std::vector<const ExtrusionEntity*> &entities, const Point &start_near,
+                                                                          std::vector<std::unique_ptr<ExtrusionEntity>> &reversed_clones);
 
 std::vector<std::pair<size_t, bool>> chain_extrusion_paths(std::vector<ExtrusionPath> &extrusion_paths, const Point *start_near = nullptr);
 void                                 reorder_extrusion_paths(std::vector<ExtrusionPath> &extrusion_paths, std::vector<std::pair<size_t, bool>> &chain);

tests/fff_print/test_helpers.cpp

@@ -225,7 +225,7 @@ DynamicPrintConfig multifilament_config(unsigned int filaments, std::initializer
 }
 
 void init_print(std::vector<TriangleMesh> &&meshes, Slic3r::Print &print, Slic3r::Model &model, const DynamicPrintConfig &config_in,
-                const std::vector<std::vector<ConfigBase::SetDeserializeItem>> *per_object_overrides, bool arrange)
+                const std::vector<std::vector<ConfigBase::SetDeserializeItem>> *per_object_overrides, bool arrange, size_t instances)
 {
 	DynamicPrintConfig config = DynamicPrintConfig::full_print_config();
     config.apply(config_in);
@@ -236,7 +236,8 @@ void init_print(std::vector<TriangleMesh> &&meshes, Slic3r::Print &print, Slic3r
 		ModelObject *object = model.add_object();
 		object->name += "object.stl";
 		object->add_volume(std::move(t));
-		object->add_instance();
+		for (size_t i = 0; i < instances; ++i)
+			object->add_instance();
 
 		if (per_object_overrides && object_idx < per_object_overrides->size() && !(*per_object_overrides)[object_idx].empty()) {
 			DynamicPrintConfig oc;

tests/fff_print/test_helpers.hpp

@@ -72,9 +72,11 @@ Slic3r::Model model(const std::string& model_name, TriangleMesh&& _mesh);
 DynamicPrintConfig multifilament_config(unsigned int filaments,
     std::initializer_list<Slic3r::ConfigBase::SetDeserializeItem> extra = {});
 
-// Apply `meshes` and config to `print`/`model`; optional per-object overrides, auto-arranged unless `arrange` is false.
+// Apply `meshes` and config to `print`/`model`, each object with `instances` copies; optional per-object overrides,
+// auto-arranged unless `arrange` is false.
 void init_print(std::vector<TriangleMesh> &&meshes, Slic3r::Print &print, Slic3r::Model &model, const DynamicPrintConfig &config_in,
-    const std::vector<std::vector<Slic3r::ConfigBase::SetDeserializeItem>> *per_object_overrides = nullptr, bool arrange = true);
+    const std::vector<std::vector<Slic3r::ConfigBase::SetDeserializeItem>> *per_object_overrides = nullptr, bool arrange = true,
+    size_t instances = 1);
 void init_print(std::initializer_list<TestMesh> meshes, Slic3r::Print &print, Slic3r::Model &model, const Slic3r::DynamicPrintConfig &config_in = Slic3r::DynamicPrintConfig::full_print_config());
 void init_print(std::initializer_list<TriangleMesh> meshes, Slic3r::Print &print, Slic3r::Model &model, const Slic3r::DynamicPrintConfig &config_in = Slic3r::DynamicPrintConfig::full_print_config());
 void init_print(std::initializer_list<TestMesh> meshes, Slic3r::Print &print, Slic3r::Model &model, std::initializer_list<Slic3r::ConfigBase::SetDeserializeItem> config_items);

tests/fff_print/test_print.cpp

@@ -561,6 +561,40 @@ TEST_CASE("export_gcode writes G-code without a result pointer", "[Print][export
     REQUIRE_FALSE(gcode.empty());
 }
 
+TEST_CASE("Exporting a sliced print again gives the same G-code", "[Print][export_gcode][Regression]")
+{
+    const int instances = GENERATE(1, 3);
+    CAPTURE(instances);
+    DynamicPrintConfig config = DynamicPrintConfig::full_print_config();
+    TestMesh           mesh   = TestMesh::ipadstand;
+    SECTION("infill reversed by chaining") { config.set_deserialize_strict({{"sparse_infill_pattern", "gyroid"}}); }
+    SECTION("support reversed by chaining") {
+        mesh = TestMesh::overhang;
+        config.set_deserialize_strict({{"enable_support", true}, {"support_interface_pattern", "concentric"}});
+    }
+    Print print;
+    Model model;
+    Slic3r::Test::init_print({Slic3r::Test::mesh(mesh)}, print, model, config, nullptr, true, instances);
+
+    const auto export_without_timestamp = [&print]() {
+        std::string gcode = Slic3r::Test::gcode(print);
+        const size_t line = gcode.find("; generated by ");
+        REQUIRE(line != std::string::npos);
+        gcode.erase(line, gcode.find('\n', line) - line);
+        return gcode;
+    };
+    const std::string first  = export_without_timestamp();
+    const std::string second = export_without_timestamp();
+
+    // Shows the first differing line on failure.
+    const size_t diff       = std::mismatch(first.begin(), first.end(), second.begin(), second.end()).first - first.begin();
+    const size_t line_start = diff == 0 ? 0 : first.rfind('\n', diff - 1) + 1;
+    INFO("first export:  " << first.substr(line_start, first.find('\n', diff) - line_start));
+    INFO("second export: " << second.substr(line_start, second.find('\n', diff) - line_start));
+    CHECK(diff == first.size());
+    CHECK(first.size() == second.size());
+}
+
 TEST_CASE("Sequential printing follows model order", "[Print]")
 {
     // Two objects of different heights, taller one added first. Orca prints

tests/libslic3r/test_preset_bundle_loading.cpp

@@ -5788,6 +5788,131 @@ TEST_CASE("A system preset no vendor lists is not resolved", "[Preset][Bundle]")
 
 namespace {
 
+// Writes each vendor's preset cache into dir, then deletes its profile JSONs: what a release build installs.
+void reduce_vendors_to_caches(const fs::path &dir, const std::vector<std::string> &vendor_ids)
+{
+    const std::string lib(PresetBundle::ORCA_FILAMENT_LIBRARY);
+    PresetBundle      library;
+    if (fs::exists(dir / (lib + ".json"))) {
+        library.set_generate_vendor_caches(true);
+        library.load_vendor_configs_from_json(dir.string(), lib, PresetBundle::LoadSystem,
+                                              ForwardCompatibilitySubstitutionRule::EnableSilent);
+    }
+    for (const std::string &vendor_id : vendor_ids) {
+        if (vendor_id == lib)
+            continue;
+        PresetBundle writer;
+        writer.set_generate_vendor_caches(true);
+        writer.load_vendor_configs_from_json(dir.string(), vendor_id, PresetBundle::LoadSystem,
+                                             ForwardCompatibilitySubstitutionRule::EnableSilent, &library);
+    }
+    for (const std::string &vendor_id : vendor_ids) {
+        REQUIRE(fs::exists(dir / (vendor_id + ".opc")));
+        fs::remove(dir / (vendor_id + ".json"));
+        fs::remove_all(dir / vendor_id);
+    }
+}
+
+// The filament library with one abstract base filament, and an "Acme" vendor whose one filament inherits it.
+void write_library_and_acme_filament(const fs::path &root)
+{
+    const std::string lib(PresetBundle::ORCA_FILAMENT_LIBRARY);
+    fs::create_directories(root / lib / "filament");
+    std::ofstream((root / (lib + ".json")).string())
+        << R"({"version":"1.0.0","name":")" << lib << R"(",)"
+        << R"("filament_list":[{"name":"Generic PLA","sub_path":"filament/generic_pla.json"}]})";
+    std::ofstream((root / lib / "filament" / "generic_pla.json").string())
+        << R"({"type":"filament","name":"Generic PLA","from":"system","instantiation":"false","filament_id":"GFL99","filament_cost":"27"})";
+    fs::create_directories(root / "Acme" / "filament");
+    std::ofstream((root / "Acme.json").string())
+        << R"({"version":"1.0.0","name":"Acme","filament_list":[{"name":"Acme PLA","sub_path":"filament/pla.json"}]})";
+    std::ofstream((root / "Acme" / "filament" / "pla.json").string())
+        << R"({"type":"filament","name":"Acme PLA","from":"system","instantiation":"true","inherits":"Generic PLA"})";
+}
+
+} // namespace
+
+TEST_CASE("A read-only load resolves a user preset against vendors installed as their cache alone", "[Preset][Bundle][Regression]")
+{
+    ScopedTemporaryDir temp_dir;
+    const fs::path     data   = temp_dir.path() / "data";
+    const fs::path     system = data / PRESET_SYSTEM_DIR;
+    ScopedDataDir      scoped_data(data);
+    ScopedResourcesDir scoped_resources(temp_dir.path() / "resources");
+    write_acme_printer_vendor(system, 33.);
+    reduce_vendors_to_caches(system, {"Acme"});
+
+    fs::create_directories(data / PRESET_USER_DIR / DEFAULT_USER_FOLDER_NAME / PRESET_PRINTER_NAME);
+    std::ofstream((data / PRESET_USER_DIR / DEFAULT_USER_FOLDER_NAME / PRESET_PRINTER_NAME / "My Acme.json").string())
+        << R"({"type":"machine","name":"My Acme","from":"User","version":"2.3.0.0","inherits":"Acme Printer","printable_height":"123"})";
+
+    AppConfig    app_config;
+    PresetBundle bundle;
+    std::string  errors;
+    bundle.load_presets(app_config, ForwardCompatibilitySubstitutionRule::EnableSilent, PresetBundle::PresetPreferences(),
+                        &errors, true);
+    CHECK(errors.empty());
+    const Preset *preset = bundle.printers.find_preset("My Acme");
+    REQUIRE(preset != nullptr);
+    CHECK_THAT(preset->config.opt_float("printable_height"), Catch::Matchers::WithinAbs(123., 1e-6));
+    CHECK_THAT(preset->config.opt_float("extruder_clearance_dist_to_rod"), Catch::Matchers::WithinAbs(33., 1e-6));
+}
+
+TEST_CASE("A read-only load writes no preset cache", "[Preset][Bundle][Regression]")
+{
+    ScopedTemporaryDir temp_dir;
+    const fs::path     system = temp_dir.path() / "data" / PRESET_SYSTEM_DIR;
+    ScopedDataDir      scoped_data(temp_dir.path() / "data");
+    ScopedResourcesDir scoped_resources(temp_dir.path() / "resources");
+    write_acme_printer_vendor(system, 33.);
+
+    AppConfig    app_config;
+    PresetBundle bundle;
+    std::string  errors;
+    bundle.load_presets(app_config, ForwardCompatibilitySubstitutionRule::EnableSilent, PresetBundle::PresetPreferences(),
+                        &errors, true);
+    CHECK(errors.empty());
+    CHECK(bundle.printers.find_preset("Acme Printer") != nullptr);
+    CHECK_FALSE(fs::exists(system / "Acme.opc"));
+}
+
+TEST_CASE("A vendor updated over the air resolves against the library installed as its cache alone", "[Preset][Bundle][Regression]")
+{
+    ScopedTemporaryDir temp_dir;
+    const fs::path     system = temp_dir.path() / "data" / PRESET_SYSTEM_DIR;
+    ScopedDataDir      scoped_data(temp_dir.path() / "data");
+    ScopedResourcesDir scoped_resources(temp_dir.path() / "resources");
+    // System presets are found by name through the bundled profiles.
+    write_library_and_acme_filament(temp_dir.path() / "resources" / PRESET_PROFILES_DIR);
+    // The release install, then an update that brings Acme back as JSONs while the library stays a cache.
+    write_library_and_acme_filament(system);
+    reduce_vendors_to_caches(system, {PresetBundle::ORCA_FILAMENT_LIBRARY, "Acme"});
+    write_library_and_acme_filament(temp_dir.path() / "update");
+    fs::copy_file(temp_dir.path() / "update" / "Acme.json", system / "Acme.json");
+    fs::create_directories(system / "Acme" / "filament");
+    fs::copy_file(temp_dir.path() / "update" / "Acme" / "filament" / "pla.json", system / "Acme" / "filament" / "pla.json");
+
+    SECTION("by name") {
+        PresetBundle       bundle;
+        DynamicPrintConfig config;
+        std::string        error;
+        REQUIRE(bundle.resolve_system_preset(config, Preset::TYPE_FILAMENT, "Acme PLA",
+                                             ForwardCompatibilitySubstitutionRule::EnableSilent, error));
+        CHECK_THAT(config.opt<ConfigOptionFloats>("filament_cost")->values.front(), Catch::Matchers::WithinAbs(27., 1e-6));
+    }
+    SECTION("by its source file") {
+        PresetBundle       bundle;
+        DynamicPrintConfig config;
+        config.option<ConfigOptionString>(BBL_JSON_KEY_INHERITS, true)->value = "Generic PLA";
+        std::string error;
+        REQUIRE(bundle.resolve_preset_config(config, Preset::TYPE_FILAMENT, (system / "Acme" / "filament" / "pla.json").string(),
+                                             ForwardCompatibilitySubstitutionRule::EnableSilent, error));
+        CHECK_THAT(config.opt<ConfigOptionFloats>("filament_cost")->values.front(), Catch::Matchers::WithinAbs(27., 1e-6));
+    }
+}
+
+namespace {
+
 // A default preset config for type, built the way PresetBundle builds its default presets.
 DynamicPrintConfig external_default_config(Preset::Type type)
 {

tests/slic3rutils/slic3rutils_tests_main.cpp

@@ -1,39 +1,6 @@
 #include <catch2/catch_all.hpp>
 
 #include "slic3r/Utils/Http.hpp"
-#include "slic3r/Utils/OrcaCloudServiceAgent.hpp"
-
-namespace {
-
-nlohmann::json flat_session_json(const nlohmann::json& fields)
-{
-    nlohmann::json session = {
-        {"access_token", "test-token"},
-        {"user_id", "test-user-id"}
-    };
-    session.update(fields);
-    return session;
-}
-
-nlohmann::json nested_session_json(const nlohmann::json& metadata)
-{
-    return {
-        {"access_token", "test-token"},
-        {"user", {
-            {"id", "test-user-id"},
-            {"user_metadata", metadata}
-        }}
-    };
-}
-
-std::string resolved_display_name(const nlohmann::json& session)
-{
-    Slic3r::OrcaCloudServiceAgent agent("");
-    REQUIRE(agent.set_user_session(session, false));
-    return agent.get_user_nickname();
-}
-
-} // namespace
 
 TEST_CASE("Check SSL certificates paths", "[Http][NotWorking]") {
     
@@ -53,62 +20,6 @@ TEST_CASE("Check SSL certificates paths", "[Http][NotWorking]") {
     REQUIRE(status == 200);
 }
 
-TEST_CASE("Orca cloud flat session resolves display name consistently", "[OrcaCloudServiceAgent]")
-{
-    CHECK(resolved_display_name(flat_session_json({
-        {"username", "orca_username"},
-        {"display_name", "Display Name"},
-        {"nickname", "Nickname"}
-    })) == "Display Name");
-
-    CHECK(resolved_display_name(flat_session_json({
-        {"username", "orca_username"},
-        {"nickname", "Nickname"}
-    })) == "Nickname");
-
-    CHECK(resolved_display_name(flat_session_json({
-        {"username", "orca_username"},
-        {"full_name", "Full Name"}
-    })) == "Full Name");
-
-    CHECK(resolved_display_name(flat_session_json({
-        {"username", "orca_username"},
-        {"name", "Provider Name"}
-    })) == "Provider Name");
-
-    CHECK(resolved_display_name(flat_session_json({
-        {"username", "orca_username"}
-    })) == "orca_username");
-}
-
-TEST_CASE("Orca cloud nested session resolves display name consistently", "[OrcaCloudServiceAgent]")
-{
-    CHECK(resolved_display_name(nested_session_json({
-        {"username", "orca_username"},
-        {"display_name", "Display Name"},
-        {"nickname", "Nickname"}
-    })) == "Display Name");
-
-    CHECK(resolved_display_name(nested_session_json({
-        {"username", "orca_username"},
-        {"nickname", "Nickname"}
-    })) == "Nickname");
-
-    CHECK(resolved_display_name(nested_session_json({
-        {"username", "orca_username"},
-        {"full_name", "Full Name"}
-    })) == "Full Name");
-
-    CHECK(resolved_display_name(nested_session_json({
-        {"username", "orca_username"},
-        {"name", "Provider Name"}
-    })) == "Provider Name");
-
-    CHECK(resolved_display_name(nested_session_json({
-        {"username", "orca_username"}
-    })) == "orca_username");
-}
-
 TEST_CASE("Http digest authentication", "[Http][NotWorking]") {
     Slic3r::Http g = Slic3r::Http::get("https://httpbingo.org/digest-auth/auth/guest/guest");
 

tests/slic3rutils/test_orca_cloud_agent.cpp

@@ -27,6 +27,37 @@ std::unique_ptr<OrcaCloudServiceAgent> make_file_backed_agent(const fs::path& di
 
 fs::path secret_file(const fs::path& dir) { return dir / secret_constants::USER_SECRET_FILENAME; }
 
+nlohmann::json flat_session_json(const nlohmann::json& fields)
+{
+    nlohmann::json session = {
+        {"access_token", "test-token"},
+        {"user_id", "test-user-id"}
+    };
+    session.update(fields);
+    return session;
+}
+
+nlohmann::json nested_session_json(const nlohmann::json& metadata)
+{
+    return {
+        {"access_token", "test-token"},
+        {"user", {
+            {"id", "test-user-id"},
+            {"user_metadata", metadata}
+        }}
+    };
+}
+
+// set_user_session() persists the session, so it goes to a throwaway token file rather than the
+// system keychain of whoever runs the tests.
+std::string resolved_display_name(const nlohmann::json& session)
+{
+    ScopedTemporaryDir dir("orca-secret");
+    auto               agent = make_file_backed_agent(dir.path());
+    REQUIRE(agent->set_user_session(session, false));
+    return agent->get_user_nickname();
+}
+
 } // namespace
 
 TEST_CASE("Logging out removes the secret this instance saved", "[OrcaCloudServiceAgent]")
@@ -84,3 +115,59 @@ TEST_CASE("Logging out leaves a secret this instance could not read alone", "[Or
     agent->user_logout(false);
     CHECK(fs::exists(secret_file(dir.path())));
 }
+
+TEST_CASE("Orca cloud flat session resolves display name consistently", "[OrcaCloudServiceAgent]")
+{
+    CHECK(resolved_display_name(flat_session_json({
+        {"username", "orca_username"},
+        {"display_name", "Display Name"},
+        {"nickname", "Nickname"}
+    })) == "Display Name");
+
+    CHECK(resolved_display_name(flat_session_json({
+        {"username", "orca_username"},
+        {"nickname", "Nickname"}
+    })) == "Nickname");
+
+    CHECK(resolved_display_name(flat_session_json({
+        {"username", "orca_username"},
+        {"full_name", "Full Name"}
+    })) == "Full Name");
+
+    CHECK(resolved_display_name(flat_session_json({
+        {"username", "orca_username"},
+        {"name", "Provider Name"}
+    })) == "Provider Name");
+
+    CHECK(resolved_display_name(flat_session_json({
+        {"username", "orca_username"}
+    })) == "orca_username");
+}
+
+TEST_CASE("Orca cloud nested session resolves display name consistently", "[OrcaCloudServiceAgent]")
+{
+    CHECK(resolved_display_name(nested_session_json({
+        {"username", "orca_username"},
+        {"display_name", "Display Name"},
+        {"nickname", "Nickname"}
+    })) == "Display Name");
+
+    CHECK(resolved_display_name(nested_session_json({
+        {"username", "orca_username"},
+        {"nickname", "Nickname"}
+    })) == "Nickname");
+
+    CHECK(resolved_display_name(nested_session_json({
+        {"username", "orca_username"},
+        {"full_name", "Full Name"}
+    })) == "Full Name");
+
+    CHECK(resolved_display_name(nested_session_json({
+        {"username", "orca_username"},
+        {"name", "Provider Name"}
+    })) == "Provider Name");
+
+    CHECK(resolved_display_name(nested_session_json({
+        {"username", "orca_username"}
+    })) == "orca_username");
+}