feat: add app version metadata guardrails (#24)

Author: Pluze

+labkit/+ui/+app/appVersionTitle.m

@@ -0,0 +1,53 @@
+function titleText = appVersionTitle(baseTitle, info)
+%APPVERSIONTITLE Format an app figure title with version metadata.
+%
+% App-facing contract:
+%   titleText = labkit.ui.app.appVersionTitle(baseTitle, info)
+%
+% Inputs:
+%   baseTitle - scalar text already used as the figure title.
+%   info - app version struct with version and updated scalar text fields.
+%
+% Outputs:
+%   titleText - string in the form "<baseTitle> v<version> (<updated>)".
+
+    baseTitle = normalizeTitle(baseTitle, info);
+    version = textField(info, 'version');
+    updated = textField(info, 'updated');
+    titleText = baseTitle + " v" + version + " (" + updated + ")";
+end
+
+function baseTitle = normalizeTitle(value, info)
+    if nargin > 0 && (ischar(value) || (isstring(value) && isscalar(value)))
+        baseTitle = strtrim(string(value));
+    else
+        baseTitle = "";
+    end
+    if strlength(baseTitle) == 0 && isstruct(info) && isfield(info, 'displayName')
+        baseTitle = textField(info, 'displayName');
+    end
+    if strlength(baseTitle) == 0 && isstruct(info) && isfield(info, 'name')
+        baseTitle = textField(info, 'name');
+    end
+    if strlength(baseTitle) == 0
+        error('labkit:ui:app:InvalidVersionInfo', ...
+            'App version title requires a base title, displayName, or name.');
+    end
+end
+
+function text = textField(info, fieldName)
+    if ~isstruct(info) || ~isscalar(info) || ~isfield(info, fieldName)
+        error('labkit:ui:app:InvalidVersionInfo', ...
+            'App version info must include scalar text field "%s".', fieldName);
+    end
+    value = info.(fieldName);
+    if ~(ischar(value) || (isstring(value) && isscalar(value)))
+        error('labkit:ui:app:InvalidVersionInfo', ...
+            'App version info field "%s" must be scalar text.', fieldName);
+    end
+    text = strtrim(string(value));
+    if strlength(text) == 0
+        error('labkit:ui:app:InvalidVersionInfo', ...
+            'App version info field "%s" cannot be empty.', fieldName);
+    end
+end

+labkit/+ui/+app/applyVersionTitle.m

@@ -0,0 +1,20 @@
+function titleText = applyVersionTitle(fig, info)
+%APPLYVERSIONTITLE Apply app version metadata to a figure title.
+%
+% App-facing contract:
+%   titleText = labkit.ui.app.applyVersionTitle(fig, info)
+%
+% Inputs:
+%   fig - scalar app figure handle with a Name property.
+%   info - app version struct with version and updated scalar text fields.
+%
+% Outputs:
+%   titleText - title written to fig.Name.
+
+    if isempty(fig) || ~isscalar(fig) || ~isvalid(fig) || ~isprop(fig, 'Name')
+        error('labkit:ui:app:InvalidFigure', ...
+            'Version title can only be applied to a valid scalar figure.');
+    end
+    titleText = labkit.ui.app.appVersionTitle(string(fig.Name), info);
+    fig.Name = char(titleText);
+end

+labkit/+ui/+app/dispatchRequest.m

@@ -6,19 +6,23 @@
 %       "labkit_Example_app", varargin, nargout);
 %   [handled, outputs, debug] = labkit.ui.app.dispatchRequest( ...
 %       "labkit_Example_app", varargin, nargout, "Requirements", req);
+%   [handled, outputs, debug] = labkit.ui.app.dispatchRequest( ...
+%       "labkit_Example_app", varargin, nargout, ...
+%       "Requirements", req, "Version", info);
 %
 % Inputs:
 %   appName - app entry-point name used to build app-scoped error IDs.
 %   args - input argument cell from the app entry point.
 %   nout - requested output count from the app entry point.
 %   Name-value options:
 %       Requirements - optional struct returned by app requirements().
+%       Version - optional struct returned by app version().
 %
 % Outputs:
-%   handled - true only when the lightweight "requirements" request is
-%       consumed; false for normal and debug launches.
-%   outputs - one-cell output containing the requirements struct for the
-%       "requirements" request; empty otherwise.
+%   handled - true only when a lightweight request such as "requirements" or
+%       "version" is consumed; false for normal and debug launches.
+%   outputs - one-cell output containing the requested app struct for handled
+%       lightweight requests; empty otherwise.
 %   debugContext - disabled for normal launches; enabled for "debug" launches.
 %       Debug launch requests do not consume app launch. Public app debug
 %       launches write a trace log under artifacts/debug so the last event is
@@ -54,6 +58,20 @@
         return;
     end
 
+    if request == "version"
+        if nout > 1
+            error(errorId(appName, 'TooManyOutputs'), ...
+                '%s version request returns at most one output.', appName);
+        end
+        if numel(args) > 1
+            error(errorId(appName, 'UnsupportedInput'), ...
+                '%s version request does not accept options.', appName);
+        end
+        handled = true;
+        outputs = {options.Version};
+        return;
+    end
+
     if isDebugRequest(request)
         if nout > 2
             error(errorId(appName, 'TooManyOutputs'), ...
@@ -79,7 +97,7 @@
 end
 
 function options = parseOptions(varargin)
-    options = struct('Requirements', []);
+    options = struct('Requirements', [], 'Version', []);
     if isempty(varargin)
         return;
     end
@@ -92,6 +110,8 @@
         switch name
             case "Requirements"
                 options.Requirements = varargin{k + 1};
+            case "Version"
+                options.Version = varargin{k + 1};
             otherwise
                 error('labkit:ui:app:InvalidDispatchOptions', ...
                     'Unsupported dispatch option "%s".', name);

+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", "2.1.0", ">=2.0 <3", ...
-        "stable", "UI 2.x app/spec/view/tool/diag contract with safe output prompts.");
+    info = labkit.contract.versionInfo("ui", "2.2.0", ">=2.0 <3", ...
+        "stable", "UI 2.x app/spec/view/tool/diag contract with app version title support.");
 end

+labkit/AGENTS.md

@@ -26,6 +26,12 @@
 - `labkit.contract` owns only MATLAB-native facade contract structs, simple range
   checks, and app requirement assertions. It must stay domain-neutral and must
   not become a package manager, plugin registry, or app metadata store.
+- App version display belongs to app-owned `version.m` files plus
+  `labkit.ui.app` title formatting; do not move app metadata into
+  `labkit.contract` or a central registry.
+- When app-facing facade code changes under `+labkit/+ui`, `+dta`, `+rhs`, or
+  `+biosignal`, update the owning facade `version()` contract in the same
+  change. Facade versions use `X.Y.Z` semantic format and must only increase.
 - Reusable UI tools may own domain-neutral interaction workflows such as image scale-bar controls, reference editing, unit normalization, and overlay placement. Keep those tools independent from app result schemas, scientific formulas, file formats, and workflow wording.
 - App-facing UI APIs live under `labkit.ui.app.*`, `labkit.ui.spec.*`, `labkit.ui.view.*`, `labkit.ui.tool.*`, and `labkit.ui.diag.*`. Do not reintroduce flat `labkit.ui.*` helper files.
 - Preview-axis tools that need pointer, drag, scroll, or hit-test ownership must use `labkit.ui.tool.createRuntime` sessions instead of each helper managing figure/axes callbacks independently.

.agents/skills/labkit-app-builder/SKILL.md

@@ -118,15 +118,17 @@ results, exports, and usage text should be specific to the new app.
 
 Keep app discovery source-based through `apps/**/labkit_*_app.m`; app
 manifests, registries, per-app build tasks, and governance apps are outside
-the current app model.
+the current app model. App-owned `version.m` files provide visible version and
+update-date metadata without becoming dependency manifests.
 
 ## Implementation Pattern
 
 Build the app in this order:
 
-1. Add or update the public app entry point as a thin dispatch wrapper, then
-   create the GUI from package-root `run.m` with `labkit.ui.app.create` and
-   `labkit.ui.spec.*`.
+1. Add or update app-local `requirements.m` and `version.m`, then keep the
+   public app entry point as a thin dispatch wrapper. It should pass both
+   structs to `labkit.ui.app.dispatchRequest`, create the GUI from package-root
+   `run.m`, and apply the app version title to the returned figure.
 2. Put the data-only spec in `+<app_slug>/+ui/buildSpec.m`; package-root
    `run.m` should create callback handles, call
    `<app_slug>.ui.buildSpec(...)`, then call `labkit.ui.app.create(...)`.

.agents/skills/labkit-boundary-guard/SKILL.md

@@ -48,7 +48,10 @@ If this is not proven, keep the code app-local.
 For UI boundary work, prefer `labkit.ui.app.create`,
 `labkit.ui.spec.*`, named `labkit.ui.view.*` helpers,
 `labkit.ui.app.dispatchRequest`, `labkit.ui.diag.createContext`, and
-`labkit.ui.tool.createRuntime`. Keep primitive builders private; do not expose
+`labkit.ui.tool.createRuntime`. App version metadata stays in app-owned
+`version.m` files; reusable UI may format or apply that title, but
+`labkit.contract` should not become an app metadata registry. Keep primitive
+builders private; do not expose
 public `labkit.ui.spec.button`, `dropdown`, `slider`, `listbox`, `table`,
 `axes`, or similar MATLAB primitive constructors. Do not reintroduce
 `createShell` or legacy `view.section/form/panel/axes/draw/update/place` APIs.

apps/AGENTS.md

@@ -21,9 +21,13 @@ Apps are first-class deliverables. Do not treat them as examples for a hidden pl
 - 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.
-- Each public app entrypoint should call an app package `requirements.m` and
-  pass it to `labkit.ui.app.dispatchRequest`. The only lightweight non-GUI
-  request is `"requirements"`.
+- Each public app entrypoint should call app package `requirements.m` and
+  `version.m`, pass both structs to `labkit.ui.app.dispatchRequest`, and apply
+  the version title after `run.m` returns the figure. Lightweight non-GUI
+  requests are `"requirements"` and `"version"`.
+- When app source, app-owned package code, or app-facing behavior changes,
+  update that app's `version.m` version metadata in the same change. App
+  versions use `X.Y.Z` semantic format and must only increase.
 - Debug launches should attach the Log tab text area, emit a startup trace line, and instrument high-level component callbacks after controls are built.
 - 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, sessions, pulse detection, and parsed curve/table access.

apps/dic/dic_postprocess/+dic_postprocess/requirements.m

@@ -3,5 +3,5 @@
 
 function req = requirements()
 
-    req = labkit.contract.requirements("ui", ">=2.1 <3");
+    req = labkit.contract.requirements("ui", ">=2.2 <3");
 end

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

@@ -0,0 +1,13 @@
+%VERSION App version metadata for labkit_DICPostprocess_app.
+% Expected caller: labkit_DICPostprocess_app and launcher/catalog guardrails.
+% Inputs: none.
+% Outputs: struct with name, displayName, family, version, and updated fields.
+% Side effects: none.
+function info = version()
+    info = struct( ...
+        "name", "labkit_DICPostprocess_app", ...
+        "displayName", "DIC Postprocess", ...
+        "family", "DIC", ...
+        "version", "1.0.0", ...
+        "updated", "2026-06-23");
+end