feat: improve app workflows and sdk diagnostics

+labkit/+app/+dialog/Choice.m

@@ -36,7 +36,7 @@
 
     methods
         function obj = Choice(value, varargin)
-            options = labkit.app.internal.OptionParser.parse( ...
+            options = labkit.app.internal.contract.OptionParser.parse( ...
                 "labkit.app.dialog.Choice", "Cancelled", varargin{:});
             cancelled = false;
             if isfield(options, "Cancelled")

+labkit/+app/+event/IntervalScroll.m

@@ -34,7 +34,7 @@
 
     methods
         function obj = IntervalScroll(varargin)
-            options = labkit.app.internal.OptionParser.parse( ...
+            options = labkit.app.internal.contract.OptionParser.parse( ...
                 "labkit.app.event.IntervalScroll", ...
                 ["Anchor", "Count"], varargin{:});
             for name = ["Anchor", "Count"]

+labkit/+app/+event/ListSelection.m

@@ -37,7 +37,7 @@
 
     methods
         function obj = ListSelection(varargin)
-            options = labkit.app.internal.OptionParser.parse( ...
+            options = labkit.app.internal.contract.OptionParser.parse( ...
                 "labkit.app.event.ListSelection", ["Ids", "Indices"], varargin{:});
             obj.Ids = ids(optionValue(options, "Ids", strings(1, 0)));
             obj.Indices = indices( ...

+labkit/+app/+event/TableCellEdit.m

@@ -52,7 +52,7 @@
         function obj = TableCellEdit(varargin)
             names = ["RowId", "RowIndex", "ColumnId", "ColumnIndex", ...
                 "PreviousValue", "NewValue", "Data"];
-            options = labkit.app.internal.OptionParser.parse( ...
+            options = labkit.app.internal.contract.OptionParser.parse( ...
                 "labkit.app.event.TableCellEdit", names, varargin{:});
             for name = ["RowIndex", "ColumnIndex", ...
                     "PreviousValue", "NewValue"]

+labkit/+app/+interaction/anchorPath.m

@@ -7,6 +7,10 @@
 % Description:
 %   Creates the semantic declaration for a managed multi-anchor path editor;
 %   the runtime owns native graphics, viewport preservation, and dispatch.
+%   On an open path, a point placed beyond the visible start is prepended, a
+%   point beyond the visible end is appended, and all other points are inserted
+%   after the nearest visible curve segment. This ordering is independent of
+%   the current axes zoom.
 %
 % Inputs:
 %   id - Unique MATLAB identifier for this interaction.
@@ -34,7 +38,7 @@
 end
 
 function spec = makeSpec(kind, id, callback, names, varargin)
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction." + kind, names, varargin{:});
-spec = labkit.app.internal.InteractionSpec(kind, id, callback, options);
+spec = labkit.app.internal.interaction.InteractionSpec(kind, id, callback, options);
 end

+labkit/+app/+interaction/interval.m

@@ -31,9 +31,9 @@
 %
 % See also labkit.app.layout.plotArea,
 %   labkit.app.event.IntervalScroll
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.interval", ...
     ["Axis", "Style", "Instruction", "ViewportPolicy", "OnScrolled"], ...
     varargin{:});
-spec = labkit.app.internal.InteractionSpec("interval",id,onChanged,options);
+spec = labkit.app.internal.interaction.InteractionSpec("interval",id,onChanged,options);
 end

+labkit/+app/+interaction/pairedAnchors.m

@@ -28,13 +28,13 @@
 %   spec = labkit.app.interaction.pairedAnchors("matches",@changeMatches);
 %
 % See also labkit.app.layout.plotArea
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.pairedAnchors", ...
     ["Axes", "Style", "Instruction", "ViewportPolicy"], varargin{:});
 if ~isfield(options, "Axes")
     error("labkit:app:contract:UnknownArgument", ...
         "labkit.app.interaction.pairedAnchors requires Axes.");
 end
-spec = labkit.app.internal.InteractionSpec( ...
+spec = labkit.app.internal.interaction.InteractionSpec( ...
     "pairedAnchors", id, onChanged, options);
 end

+labkit/+app/+interaction/pointSlots.m

@@ -28,8 +28,8 @@
 %   spec = labkit.app.interaction.pointSlots("markers",@changeMarkers);
 %
 % See also labkit.app.layout.plotArea
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.pointSlots", ...
     ["Axis", "Style", "Instruction", "ViewportPolicy"], varargin{:});
-spec = labkit.app.internal.InteractionSpec("pointSlots",id,onChanged,options);
+spec = labkit.app.internal.interaction.InteractionSpec("pointSlots",id,onChanged,options);
 end

+labkit/+app/+interaction/rectangle.m

@@ -32,9 +32,9 @@
 %   spec = labkit.app.interaction.rectangle("crop",@moveCrop);
 %
 % See also labkit.app.layout.plotArea
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.rectangle", ...
     ["Axis", "Style", "Instruction", "ViewportPolicy", ...
      "OnBackgroundPressed"], varargin{:});
-spec = labkit.app.internal.InteractionSpec("rectangle",id,onChanged,options);
+spec = labkit.app.internal.interaction.InteractionSpec("rectangle",id,onChanged,options);
 end

+labkit/+app/+interaction/regionSelection.m

@@ -31,10 +31,10 @@
 %       OnBackgroundPressed=@measurePoint);
 %
 % See also labkit.app.layout.plotArea
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.regionSelection", ...
     ["Axis", "Style", "Instruction", "ViewportPolicy", ...
      "OnBackgroundPressed"], varargin{:});
-spec = labkit.app.internal.InteractionSpec( ...
+spec = labkit.app.internal.interaction.InteractionSpec( ...
     "regionSelection",id,onSelected,options);
 end

+labkit/+app/+interaction/scaleReference.m

@@ -28,9 +28,9 @@
 %   spec = labkit.app.interaction.scaleReference("scale",@changeScale);
 %
 % See also labkit.app.layout.plotArea
-options = labkit.app.internal.OptionParser.parse( ...
+options = labkit.app.internal.contract.OptionParser.parse( ...
     "labkit.app.interaction.scaleReference", ...
     ["Axis", "Style", "Instruction", "ViewportPolicy"], varargin{:});
-spec = labkit.app.internal.InteractionSpec( ...
+spec = labkit.app.internal.interaction.InteractionSpec( ...
     "scaleReference",id,onChanged,options);
 end

+labkit/+app/+internal/+artifact/Store.m

@@ -0,0 +1,63 @@
+classdef (Hidden, Sealed) Store
+    % Own App-specific artifact naming and repository scratch destinations.
+    % Caller: RuntimeKernel. Inputs are domain-neutral artifact tokens; output
+    % paths always remain below the checkout's ignored artifacts directory.
+
+    properties (Access = private)
+        AppId (1, 1) string
+    end
+
+    methods
+        function obj = Store(appId)
+            obj.AppId = artifactToken(appId, "App ID");
+        end
+
+        function destination = destination(obj, category, stem, extension)
+            category = artifactToken(category, "category");
+            filename = obj.filename(stem, extension);
+            folder = artifactFolder(category);
+            if exist(char(folder), "dir") ~= 7
+                [created, message] = mkdir(char(folder));
+                if ~created
+                    error("labkit:app:runtime:ArtifactWriteFailed", ...
+                        "Could not create the LabKit artifacts folder: %s", ...
+                        message);
+                end
+            end
+            destination = fullfile(folder, filename);
+        end
+
+        function filename = filename(obj, stem, extension)
+            stem = artifactToken(stem, "stem");
+            extension = string(extension);
+            if ~isscalar(extension) || ...
+                    isempty(regexp(char(extension), ...
+                    '^\.[a-z0-9]+$', "once"))
+                error("labkit:app:runtime:InvariantFailure", ...
+                    "Artifact extension must be a lowercase file extension.");
+            end
+            timestamp = string(datetime("now", TimeZone="UTC", ...
+                Format="yyyyMMdd-HHmmss"));
+            nonce = extractBefore( ...
+                string(java.util.UUID.randomUUID()), 9);
+            filename = "labkit-" + stem + "-" + obj.AppId + "-" + ...
+                timestamp + "-" + nonce + extension;
+        end
+    end
+end
+
+function folder = artifactFolder(category)
+versionPath = string(which("labkit.app.version"));
+root = string(fileparts(fileparts(fileparts(versionPath))));
+folder = fullfile(root, "artifacts", category);
+end
+
+function value = artifactToken(value, label)
+value = lower(strip(string(value)));
+value = regexprep(value, "[^a-z0-9]+", "-");
+value = regexprep(value, "(^-+|-+$)", "");
+if ~isscalar(value) || strlength(value) == 0
+    error("labkit:app:runtime:InvariantFailure", ...
+        "Artifact %s must contain letters or digits.", label);
+end
+end

+labkit/+app/+internal/CompiledDefinition.m → +labkit/+app/+internal/+contract/CompiledDefinition.m

@@ -14,14 +14,14 @@
 
     methods (Access = ?labkit.app.Definition)
         function obj = CompiledDefinition(layout, startCallback)
-            if ~isa(layout, "labkit.app.internal.LayoutNode") || ...
+            if ~isa(layout, "labkit.app.internal.contract.LayoutNode") || ...
                     layout.Kind ~= "workbench"
                 error("labkit:app:contract:InvalidValue", ...
                     "Definition Workbench must be a workbench Layout value.");
             end
             onStart = [];
             if ~isempty(startCallback)
-                onStart = labkit.app.internal.SignalBinding( ...
+                onStart = labkit.app.internal.contract.SignalBinding( ...
                     "application", "started", startCallback);
             end
             nodes = layout.flattenForCompiler();