feat: route app alerts through UI facade

Author: Pluze

+labkit/+ui/+app/showAlert.m

@@ -0,0 +1,59 @@
+function shown = showAlert(fig, message, titleText)
+%SHOWALERT Show an app alert, or record it during hidden GUI tests.
+%
+% App-facing contract:
+%   shown = labkit.ui.app.showAlert(fig, message, titleText)
+%
+% Inputs:
+%   fig - app uifigure that owns the alert.
+%   message - user-facing alert message owned by the calling app.
+%   titleText - user-facing alert title owned by the calling app.
+%
+% Output:
+%   shown - true when a modal alert was shown, false when hidden GUI test
+%       mode recorded the alert without opening a modal dialog.
+
+    if nargin < 3
+        titleText = "";
+    end
+    recordAlert(fig, message, titleText);
+    if isHiddenGuiTestMode()
+        traceAlert(fig, message, titleText, "skipped-hidden-gui");
+        shown = false;
+        return;
+    end
+    traceAlert(fig, message, titleText, "shown");
+    uialert(fig, message, titleText);
+    shown = true;
+end
+
+function tf = isHiddenGuiTestMode()
+    tf = string(getenv('LABKIT_GUI_TEST_MODE')) == "hidden";
+end
+
+function recordAlert(fig, message, titleText)
+    if isempty(fig) || ~isvalid(fig)
+        return;
+    end
+    alert = struct( ...
+        'title', string(titleText), ...
+        'message', string(message));
+    if isappdata(fig, 'labkitUiAlerts')
+        alerts = getappdata(fig, 'labkitUiAlerts');
+        alerts(end + 1, 1) = alert;
+    else
+        alerts = alert;
+    end
+    setappdata(fig, 'labkitUiAlerts', alerts);
+end
+
+function traceAlert(fig, message, titleText, reason)
+    if isempty(fig) || ~isvalid(fig) || ~isappdata(fig, 'labkitUiDebugContext')
+        return;
+    end
+    debug = getappdata(fig, 'labkitUiDebugContext');
+    if isstruct(debug) && isfield(debug, 'trace') && isa(debug.trace, 'function_handle')
+        debug.trace('alert', sprintf('%s: %s', char(string(titleText)), ...
+            char(string(message))), reason);
+    end
+end

+labkit/+ui/version.m

@@ -12,6 +12,6 @@
 %       compatible contract ranges implemented by this code, contract status,
 %       and a short maintainer note.
 
-    info = labkit.contract.versionInfo("ui", "3.2.7", ">=3.0 <4", ...
-        "stable", "UI 3.x app/spec/view/tool/diag contract with compact single-file panels, toolPanel file entry helpers, filePanel title context, debug trace, close guard, crash reports, output folder prompts, and default text fitting.");
+    info = labkit.contract.versionInfo("ui", "3.2.8", ">=3.0 <4", ...
+        "stable", "UI 3.x app/spec/view/tool/diag contract with compact single-file panels, toolPanel file entry helpers, filePanel title context, debug trace, hidden-test-safe alerts, close guard, crash reports, output folder prompts, and default text fitting.");
 end

.agents/migration_guide.md

@@ -46,10 +46,10 @@ GUI workflow acceptance validation migration
 Current facts:
 
 - MATLAB source inventory from tracked files:
-  - total: 695 `.m` files, 58,328 lines
+  - total: 696 `.m` files, 58,443 lines
   - `apps/`: 405 files, 23,817 lines, max 646 lines
-  - `+labkit/`: 173 files, 16,410 lines, max 647 lines
-  - `tests/`: 114 files, 15,824 lines, max 649 lines
+  - `+labkit/`: 174 files, 16,469 lines, max 647 lines
+  - `tests/`: 114 files, 15,880 lines, max 649 lines
   - `labkit_launcher.m`: 1,722 lines and intentionally exempt
 - Tracked files over the 650-line repository file budget:
   `labkit_launcher.m` only, by design, because it is the self-contained repair
@@ -97,6 +97,8 @@ Current facts:
 - App-owned save dialogs that need safe output-file handling use
   `labkit.ui.app.promptOutputFile`; app-owned output-folder dialogs now use
   `labkit.ui.app.promptOutputFolder`.
+- App-owned alerts use `labkit.ui.app.showAlert`, preserving normal modal
+  behavior while recording and skipping the modal in hidden GUI test mode.
 - Package-root app runners that catch `MException` and continue report through
   the framework debug context before alerts or recovery logs.
 - Image workflow apps keep run/export/measurement task snapshots and
@@ -253,8 +255,8 @@ Completion criteria:
 
 Objective:
 
-Remove OS-dialog and callback edges that block hidden workflow acceptance tests
-while preserving normal public app behavior.
+Remove callback edges that block hidden workflow acceptance tests while
+preserving normal public app behavior.
 
 Target shape:
 
@@ -266,6 +268,8 @@ Target shape:
   `labkit.ui.app.promptOutputFolder(titleText, defaultFolder, "Chooser", f)`.
 - App-specific filenames, filters, export schemas, and user-facing messages
   stay app-owned.
+- App-specific alert titles and messages stay app-owned while modal mechanics
+  route through `labkit.ui.app.showAlert`.
 - Caught callback exceptions that continue must reach the framework debug
   context before alerts or recovery logs are shown.
 - UI numeric control values must be normalized to finite scalar app state or
@@ -275,27 +279,19 @@ Target shape:
 
 Current problem edges:
 
-- Modal `uialert` is app-owned and expected, but workflow tests need an
-  injectable or traceable way to avoid stalls where the path can be reached
-  noninteractively.
 - Broad direct numeric UI control assignment audits still belong to app-local
   runner cleanup when those callbacks are touched.
 
 Workstreams:
 
-1. Audit modal alert paths that hidden workflow tests can reach. Add test hooks
-   only where a real hidden GUI test would otherwise block; do not add fake app
-   APIs that ordinary users can see or need.
-2. Continue auditing direct numeric UI control assignments during runner
+1. Continue auditing direct numeric UI control assignments during runner
    cleanup; promote only if multiple apps prove the same domain-neutral API is
    needed.
-3. Use the Route A helper rubric while doing this work. Do not solve a dialog
+2. Use the Route A helper rubric while doing this work. Do not solve a dialog
    migration by adding many single-use one-line wrappers.
 
 Completion criteria:
 
-- Hidden GUI workflow tests can avoid modal alert stalls without changing
-  normal public app behavior.
 - Remaining direct numeric UI state assignments found during runner cleanup are
   finite-scalar normalized before reaching app state or task structs.
 
@@ -311,8 +307,9 @@ proof. Correctness stays in app-owned GUI-free unit tests.
 Dependency:
 
 Do not broadly roll out this route before Route B has a working folder-prompt
-hook and a clear modal-edge policy. Otherwise workflow tests will either stall
-on OS dialogs or grow app-specific test shims that later need removal.
+hook, hidden-test-safe alert helper, and a clear remaining-modal-edge policy.
+Otherwise workflow tests will either stall on OS dialogs or grow app-specific
+test shims that later need removal.
 
 Target shape:
 

apps/AGENTS.md

@@ -13,11 +13,11 @@ Apps are first-class deliverables. Do not treat them as examples for a hidden pl
 
 ## App Ownership
 
-- Keep domain formulas, thresholds, integration rules, option defaults, plot labels, result fields, export columns, failed-row behavior, alerts, and log wording app-local unless the user explicitly approves a boundary change.
+- Keep domain formulas, thresholds, integration rules, option defaults, plot labels, result fields, export columns, failed-row behavior, alert wording/trigger decisions, and log wording app-local unless the user explicitly approves a boundary change.
 - For a new app cold start, create the standard app shape directly and use the
   smallest genuinely similar app as a reference. Keep the first version focused
   on the real workflow rather than placeholder behavior.
-- When a documented UI tool owns app-neutral controls or interaction mechanics, consume it instead of reimplementing widget state or normalization. Keep app calculations, summaries, alerts, and exports local.
+- When a documented UI tool owns app-neutral controls or interaction mechanics, consume it instead of reimplementing widget state or normalization. Keep app calculations, summaries, alert text, and exports local.
 - Use `labkit.ui.app.create` with `labkit.ui.spec.*` for app GUIs. Do not
   reintroduce the removed `labkit.ui.app.createShell` or legacy view helpers.
 - Use `labkit.ui.app.dispatchRequest` for debug launch routing and `labkit.ui.diag.createContext` only when an app has an app-specific nonstandard request path.
@@ -33,6 +33,9 @@ Apps are first-class deliverables. Do not treat them as examples for a hidden pl
   `debug.reportException(component, event, ME)` before showing an alert,
   logging a recovery message, or returning. Do not swallow import, export,
   preview, or tool errors without a framework debug/crash report.
+- App alerts must call `labkit.ui.app.showAlert(fig, message, titleText)`
+  instead of raw `uialert`. Apps still own the title, message, and decision to
+  alert; the framework owns hidden-test-safe modal mechanics.
 - Apps with custom preview scroll, drawing, ROI, scale-bar, or other axes interaction should create a `labkit.ui.tool.createRuntime` and pass that runtime into reusable tools. Do not set preview-tool `WindowScrollWheelFcn`, `WindowButtonMotionFcn`, `WindowButtonUpFcn`, or axes `ButtonDownFcn` directly in app code.
 - DTA-backed apps use `labkit.dta.*` for discovery, loading, pulse detection, and parsed curve/table access. Task queues, duplicate policy, current selection, analysis state, and export workflow stay app-owned.
 - RHS-backed apps use `labkit.rhs.*` for discovery, header inspection,
@@ -50,7 +53,7 @@ Apps are first-class deliverables. Do not treat them as examples for a hidden pl
   shared `+app` package name creates MATLAB package-resolution ambiguity.
 - Apps put the ordinary data-only spec in `+<app_slug>/+ui/buildSpec.m`.
   The public app entry point delegates to package-root `run.m`; that runner
-  owns state, callback closures, alerts, log wording, and refresh order.
+  owns state, callback closures, alert wording, log wording, and refresh order.
   `buildSpec.m` describes controls, sections, workspace, initial text/defaults,
   and callback handles only.
 - Package-root `run.m` files are allowed to contain app lifecycle

apps/dic/dic_postprocess/+dic_postprocess/run.m

@@ -117,12 +117,12 @@ function onMaskCleared()
 
     function onGenerate(~, ~)
         if strlength(S.matPath) == 0 || isempty(S.referenceImage) || isempty(S.maskImage)
-            uialert(fig, 'Load the DIC MAT file, reference image, and mask image first.', ...
+            labkit.ui.app.showAlert(fig, 'Load the DIC MAT file, reference image, and mask image first.', ...
                 'Missing inputs');
             return;
         end
         if edMax.Value <= edMin.Value
-            uialert(fig, 'Color max must be greater than color min.', 'Invalid color range');
+            labkit.ui.app.showAlert(fig, 'Color max must be greater than color min.', 'Invalid color range');
             return;
         end
 
@@ -132,14 +132,14 @@ function onGenerate(~, ~)
             addLog('Generated EXX/EYY overlays and ROI summary.');
         catch ME
             debugLog.reportException('dicPostprocess', 'Generate failed', ME);
-            uialert(fig, ME.message, 'DIC postprocess error');
+            labkit.ui.app.showAlert(fig, ME.message, 'DIC postprocess error');
             addLog(sprintf('Generate failed: %s', ME.message));
         end
     end
 
     function onSaveOverlays(~, ~)
         if isempty(S.overlayExx) || isempty(S.overlayEyy)
-            uialert(fig, 'Generate overlays before saving.', 'Save overlays');
+            labkit.ui.app.showAlert(fig, 'Generate overlays before saving.', 'Save overlays');
             return;
         end
 
@@ -160,7 +160,7 @@ function onSaveOverlays(~, ~)
 
     function onExportSummary(~, ~)
         if isempty(S.summaryTable) || height(S.summaryTable) == 0
-            uialert(fig, 'Generate a summary before exporting.', 'Export summary');
+            labkit.ui.app.showAlert(fig, 'Generate a summary before exporting.', 'Export summary');
             return;
         end
 
@@ -192,7 +192,7 @@ function onOptionsChanged(~, ~)
     function renderOverlays(showAlerts)
         if edMax.Value <= edMin.Value
             if showAlerts
-                uialert(fig, 'Color max must be greater than color min.', 'Invalid color range');
+                labkit.ui.app.showAlert(fig, 'Color max must be greater than color min.', 'Invalid color range');
             end
             return;
         end

apps/dic/dic_postprocess/+dic_postprocess/version.m

@@ -8,6 +8,6 @@
         "name", "labkit_DICPostprocess_app", ...
         "displayName", "DIC Postprocess", ...
         "family", "DIC", ...
-        "version", "1.2.2", ...
+        "version", "1.2.3", ...
         "updated", "2026-06-30");
 end

apps/dic/dic_preprocess/+dic_preprocess/+ui/alertIfMissingImagePair.m

@@ -7,6 +7,6 @@
 
     shown = ~dic_preprocess.state.hasImagePair(S);
     if shown
-        uialert(fig, messageText, titleText);
+        labkit.ui.app.showAlert(fig, messageText, titleText);
     end
 end

apps/dic/dic_preprocess/+dic_preprocess/run.m

@@ -110,7 +110,7 @@ function onAlign(~, ~)
         addLog('Opening point selector. Choose matching points, then accept.');
         [movingPoints, fixedPoints] = cpselect(S.currentMovingImage, S.currentReferenceImage, 'Wait', true);
         if size(movingPoints, 1) < 2
-            uialert(fig, 'Rigid registration requires at least two point pairs.', 'Not enough points');
+            labkit.ui.app.showAlert(fig, 'Rigid registration requires at least two point pairs.', 'Not enough points');
             addLog('Alignment cancelled: fewer than two point pairs.');
             return;
         end
@@ -139,7 +139,7 @@ function onAutoAlign(~, ~)
             [alignedImage, tform, method] = dic_preprocess.ops.autoAlignMovingToReference( ...
                 S.currentReferenceImage, S.currentMovingImage);
         catch err
-            uialert(fig, sprintf('Automatic alignment failed:\n%s', err.message), 'Auto align failed');
+            labkit.ui.app.showAlert(fig, sprintf('Automatic alignment failed:\n%s', err.message), 'Auto align failed');
             addLog(sprintf('Automatic alignment failed: %s', err.message));
             return;
         end
@@ -183,7 +183,7 @@ function onStartCropRoi(~, ~)
 
     function onApplyCropRoi(~, ~)
         if isempty(S.cropRoiTop) || ~isvalid(S.cropRoiTop)
-            uialert(fig, 'Start a crop ROI before applying the crop.', 'No active ROI');
+            labkit.ui.app.showAlert(fig, 'Start a crop ROI before applying the crop.', 'No active ROI');
             return;
         end
 
@@ -227,7 +227,7 @@ function onCropRoiMoved(~, evt)
 
     function onUndoEdit(~, ~)
         if isempty(S.history)
-            uialert(fig, 'No align or crop operation is available to undo.', 'Undo');
+            labkit.ui.app.showAlert(fig, 'No align or crop operation is available to undo.', 'Undo');
             return;
         end
 
@@ -245,7 +245,7 @@ function onUndoEdit(~, ~)
 
     function onResetToOriginals(~, ~)
         if isempty(S.referenceImage) || isempty(S.movingImage)
-            uialert(fig, 'Load both images before resetting the working pair.', 'Reset');
+            labkit.ui.app.showAlert(fig, 'Load both images before resetting the working pair.', 'Reset');
             return;
         end
         pushHistory('reset to originals');
@@ -280,7 +280,7 @@ function onSaveCurrentImages(~, ~)
 
     function onStartMaskEdit(~, ~)
         if isempty(S.currentReferenceImage)
-            uialert(fig, 'Load a reference image before drawing an ROI mask.', 'Missing image');
+            labkit.ui.app.showAlert(fig, 'Load a reference image before drawing an ROI mask.', 'Missing image');
             return;
         end
 
@@ -403,7 +403,7 @@ function onSaveMask(~, ~)
         if isempty(S.maskImage)
             [boundaryMask, ok] = currentBoundaryMask(false);
             if ~ok
-                uialert(fig, 'Draw a mask ROI or add a boundary to the mask canvas before saving.', 'Save ROI mask');
+                labkit.ui.app.showAlert(fig, 'Draw a mask ROI or add a boundary to the mask canvas before saving.', 'Save ROI mask');
                 return;
             end
             S.maskImage = boundaryMask;
@@ -445,7 +445,7 @@ function onSaveMask(~, ~)
             S.maskPoints, size(S.currentReferenceImage), ...
             S.maskBoundaryStyle, S.maskEditor);
         if ~ok && showAlert
-            uialert(fig, 'Mask ROI needs at least three anchors.', 'Not enough anchors');
+            labkit.ui.app.showAlert(fig, 'Mask ROI needs at least three anchors.', 'Not enough anchors');
         end
     end
 

apps/dic/dic_preprocess/+dic_preprocess/version.m

@@ -8,6 +8,6 @@
         "name", "labkit_DICPreprocess_app", ...
         "displayName", "DIC Preprocess", ...
         "family", "DIC", ...
-        "version", "1.2.1", ...
+        "version", "1.2.2", ...
         "updated", "2026-06-30");
 end

apps/electrochem/chrono_overlay/+chrono_overlay/run.m

@@ -76,7 +76,7 @@ function loadFiles(filepaths)
 
         if ~isempty(failed)
             firstError = failed(1);
-            uialert(fig, sprintf('Failed to load:\n%s\n\n%s', firstError.filepath, firstError.message), 'Load error');
+            labkit.ui.app.showAlert(fig, sprintf('Failed to load:\n%s\n\n%s', firstError.filepath, firstError.message), 'Load error');
         end
     end
 
@@ -131,13 +131,13 @@ function refreshPlots()
 
     function onExportCSV(~, ~)
         if isempty(S.items)
-            uialert(fig, 'No files loaded.', 'Export');
+            labkit.ui.app.showAlert(fig, 'No files loaded.', 'Export');
             return;
         end
 
         items = selectedItems();
         if isempty(items)
-            uialert(fig, 'No files selected for export.', 'Export');
+            labkit.ui.app.showAlert(fig, 'No files selected for export.', 'Export');
             return;
         end