fix(combobulate): make SetExternalRotation idempotent + diagnostic API

Root cause: every slider tick re-installed the composition expression
animation chain on _root.TransformMatrix and on the property-set buffer.
That re-install costs one composition tick before _root.TransformMatrix
shows the new value, but the auto-refresh sampler reads the property set
immediately and runs cull/sort with the new rotation. The result is a
one-frame transform-vs-cull desync. Tiny slider steps mask it; large
jumps make the prior-frame matrix grossly visible.

Fix: SetExternalRotation now no-ops when the same ExpressionAnimation
instance is reinstalled (in both Combobulate and CombobulateSceneVisual).
The property set is the only thing that needs updating per tick; the
expression already references it.

Also adds diagnostic API for future investigation: InvalidateRenderCaches,
GetRenderCacheSnapshot, GetActualChildrenOrder, GetLiveSpriteVisibility,
plus GetState/ForceRebuild/SetToggles rover actions and a per-rotation log.

Version 1.0.14.0 of sample MSIX.

Author: arcadiogarcia

src/Combobulate.Sample.WinUI3/MainWindow.Actions.cs

@@ -41,6 +41,24 @@ public sealed partial class MainWindow : zRover.Core.IActionableApp
             name: "ResetRotation",
             description: "Resets all three rotation axes to 0.",
             parameterSchema: @"{""type"":""object"",""properties"":{}}"),
+        new ActionDescriptor(
+            name: "GetState",
+            description: "Returns the current viewer state (rotation X/Y/Z degrees, zoom, external-rotation toggle, auto-refresh toggle, current Source) PLUS a snapshot of the sprite renderer's per-frame cull/order caches (visible[], order[]), the live _root.Children stack, and the live SpriteVisual.IsVisible flags. Returned via the ActionResult.Consequences string list as 'key=value' lines so a caller can correlate a screenshot with the exact internal state that produced it.",
+            parameterSchema: @"{""type"":""object"",""properties"":{}}"),
+        new ActionDescriptor(
+            name: "ForceRebuild",
+            description: "Diagnostic: invalidates the sprite renderer's per-frame cull/order skip caches (_lastVisible, _lastOrder) and triggers a full rebuild against the current rotation. Use this when the view looks broken: if it heals after this call, the bug is in the skip caches; if not, the bug is elsewhere (rotation matrix, expression animation, painter algorithm).",
+            parameterSchema: @"{""type"":""object"",""properties"":{}}"),
+        new ActionDescriptor(
+            name: "SetToggles",
+            description: "Sets the ExternalRotation and AutoRefresh toggle switches. Either or both may be omitted to keep current. Use this to script the exact mode used to reproduce a rotation-update bug.",
+            parameterSchema: @"{
+  ""type"": ""object"",
+  ""properties"": {
+    ""externalRotation"": { ""type"": ""boolean"" },
+    ""autoRefresh"": { ""type"": ""boolean"" }
+  }
+}"),
         new ActionDescriptor(
             name: "ResetCube",
             description: "Reloads the built-in cube model.",
@@ -79,6 +97,14 @@ public Task<ActionResult> DispatchAsync(string actionName, string parametersJson
             case "LoadObjFromPath": return DispatchLoadObjFromPathAsync(parametersJson);
             case "SetRotation": return DispatchSetRotationAsync(parametersJson);
             case "ResetRotation": return RunOnUi(() => { PitchSlider.Value = 0; YawSlider.Value = 0; RollSlider.Value = 0; });
+            case "GetState": return DispatchGetStateAsync();
+            case "ForceRebuild": return RunOnUi(() =>
+            {
+                combobulate.InvalidateRenderCaches();
+                var rot = new System.Numerics.Vector3((float)PitchSlider.Value, (float)YawSlider.Value, (float)RollSlider.Value);
+                combobulate.RebuildForExternalRotation(rot);
+            });
+            case "SetToggles": return DispatchSetTogglesAsync(parametersJson);
             case "ResetCube": return RunOnUi(LoadCube);
             case "SetZoom": return DispatchSetZoomAsync(parametersJson);
             case "SetMaterial": return DispatchSetMaterialAsync(parametersJson);
@@ -160,6 +186,74 @@ private Task<ActionResult> DispatchSetMaterialAsync(string parametersJson)
         });
     }
 
+    private Task<ActionResult> DispatchSetTogglesAsync(string parametersJson)
+    {
+        JObject p;
+        try { p = JObject.Parse(parametersJson); }
+        catch { return Task.FromResult(ActionResult.Fail("validation_error", "params is not valid JSON.")); }
+
+        return RunOnUi(() =>
+        {
+            if (p["externalRotation"] != null && ExternalRotationToggle != null)
+                ExternalRotationToggle.IsOn = p["externalRotation"]!.Value<bool>();
+            if (p["autoRefresh"] != null && AutoRefreshToggle != null)
+                AutoRefreshToggle.IsOn = p["autoRefresh"]!.Value<bool>();
+        });
+    }
+
+    private Task<ActionResult> DispatchGetStateAsync()
+    {
+        var tcs = new TaskCompletionSource<ActionResult>();
+        var dq = this.DispatcherQueue;
+        if (!dq.TryEnqueue(DispatcherQueuePriority.Normal, () =>
+        {
+            try
+            {
+                var (cacheVisible, cacheOrder) = combobulate.GetRenderCacheSnapshot();
+                var actualOrder = combobulate.GetActualChildrenOrder();
+                var liveVisible = combobulate.GetLiveSpriteVisibility();
+                var lines = new List<string>
+                {
+                    $"rotationX={PitchSlider.Value:F3}",
+                    $"rotationY={YawSlider.Value:F3}",
+                    $"rotationZ={RollSlider.Value:F3}",
+                    $"zoom={combobulate.ModelScale:F3}",
+                    $"externalRotation={(ExternalRotationToggle?.IsOn == true)}",
+                    $"autoRefresh={(AutoRefreshToggle?.IsOn == true)}",
+                    $"perspective={combobulate.EnablePerspective}",
+                    $"source={combobulate.Source ?? "(null)"}",
+                    $"cache.visible={string.Join(",", cacheVisible)}",
+                    $"cache.order={string.Join(",", cacheOrder)}",
+                    $"children.actual={string.Join(",", actualOrder)}",
+                    $"sprite.visible={string.Join(",", liveVisible)}",
+                };
+                tcs.SetResult(ActionResult.Ok(lines));
+            }
+            catch (Exception ex) { tcs.SetResult(ActionResult.Fail("execution_error", ex.Message)); }
+        }))
+        {
+            tcs.SetResult(ActionResult.Fail("execution_error", "Failed to enqueue UI work."));
+        }
+        return tcs.Task;
+    }
+
+    /// <summary>
+    /// Continuous diagnostic log: writes the current rotation triple to the rover
+    /// log every time ApplyRotation runs so a tail of the diagnostic log shows
+    /// the live angle history.
+    /// </summary>
+    internal void LogCurrentRotation()
+    {
+        try
+        {
+            zRover.WinUI.RoverMcp.Log(
+                "Combobulate",
+                $"rotation x={PitchSlider.Value:F2} y={YawSlider.Value:F2} z={RollSlider.Value:F2} " +
+                $"external={ExternalRotationToggle?.IsOn == true} auto={AutoRefreshToggle?.IsOn == true}");
+        }
+        catch { /* logger is best-effort */ }
+    }
+
     private Task<ActionResult> RunOnUi(Action action)
     {
         var tcs = new TaskCompletionSource<ActionResult>();

src/Combobulate.Sample.WinUI3/MainWindow.xaml.cs

@@ -156,6 +156,9 @@ private void ApplyRotation()
             combobulate.RotationZ = z;
             // combobulateSceneVisual mirrors combobulate's rotation via x:Bind.
         }
+#if DEBUG
+        LogCurrentRotation();
+#endif
     }
 
     private async void LoadObjButton_Click(object sender, RoutedEventArgs e)

src/Combobulate.Sample.WinUI3/Package.appxmanifest

@@ -9,7 +9,7 @@
   <Identity
     Name="Combobulate.Sample.WinUI3"
     Publisher="CN=Dev"
-    Version="1.0.9.0" />
+    Version="1.0.14.0" />
 
   <mp:PhoneIdentity PhoneProductId="b0b0b0b0-b0b0-b0b0-b0b0-b0b0b0b0b001" PhonePublisherId="00000000-0000-0000-0000-000000000000"/>
 

src/Combobulate/Combobulate.cs

@@ -311,6 +311,13 @@ private void TryAttachVisuals()
     public void SetExternalRotation(ExpressionAnimation rotationDegrees)
     {
         if (rotationDegrees is null) throw new ArgumentNullException(nameof(rotationDegrees));
+        // Idempotent: re-installing the same expression every slider tick was
+        // tearing down and rebuilding the composition animation chain on the
+        // root, which causes a one-frame lag where _root.TransformMatrix is
+        // still showing the previous matrix while the cull/sort run on the
+        // freshly-pushed property-set value. The visible symptom is a quad
+        // jump that looks "wrong" until the next slider tick recovers.
+        if (ReferenceEquals(_externalRotationExpression, rotationDegrees)) return;
         _externalRotationExpression = rotationDegrees;
         TryStartExternalRotationAnimation();
     }
@@ -656,6 +663,75 @@ public void EnableAutoRefresh(Func<Vector3> rotationSampler)
 #endif
     }
 
+    /// <summary>
+    /// Diagnostic helper: forces the next rebuild to re-emit IsVisible flags and
+    /// child-order updates for every quad, regardless of the per-frame skip
+    /// optimisations (<c>_lastVisible</c> / <c>_lastOrder</c>). If a known-broken
+    /// view heals after calling this, the bug lives in the skip caches.
+    /// </summary>
+    public void InvalidateRenderCaches()
+    {
+        if (_lastVisible != null)
+            for (int i = 0; i < _lastVisible.Length; i++) _lastVisible[i] = false;
+        _lastOrder = Array.Empty<int>();
+    }
+
+    /// <summary>
+    /// Diagnostic snapshot of the per-frame skip caches. Returns the visible
+    /// flag for every quad (in cached-quad index order) and the painter order
+    /// (sequence of cached-quad indices, back to front). UI thread only.
+    /// </summary>
+    public (bool[] visible, int[] order) GetRenderCacheSnapshot()
+    {
+        var v = _lastVisible == null ? Array.Empty<bool>() : (bool[])_lastVisible.Clone();
+        var o = (int[])_lastOrder.Clone();
+        return (v, o);
+    }
+
+    /// <summary>
+    /// Diagnostic: returns the actual <c>_root.Children</c> stack as cached-quad
+    /// indices, bottom to top. This is the ground truth of what compositor will
+    /// render and includes hidden sprites still parented in the collection.
+    /// Compare against <see cref="GetRenderCacheSnapshot"/>.order to confirm the
+    /// visible subset's relative ordering matches what the painter sort decided.
+    /// </summary>
+    public int[] GetActualChildrenOrder()
+    {
+        if (_root == null || _spritePool == null) return Array.Empty<int>();
+        var children = _root.Children;
+        var pool = _spritePool;
+        var result = new int[children.Count];
+        int k = 0;
+        foreach (var child in children)
+        {
+            int idx = -1;
+            for (int i = 0; i < pool.Length; i++)
+            {
+                if (ReferenceEquals(pool[i], child)) { idx = i; break; }
+            }
+            result[k++] = idx;
+        }
+        return result;
+    }
+
+    /// <summary>
+    /// Diagnostic: returns the LIVE <c>SpriteVisual.IsVisible</c> for every pooled
+    /// sprite (in cached-quad index order). Compare against
+    /// <see cref="GetRenderCacheSnapshot"/>.visible to detect a divergence between
+    /// what the cull code thinks it pushed and what the sprite property actually holds.
+    /// </summary>
+    public bool[] GetLiveSpriteVisibility()
+    {
+        if (_spritePool == null) return Array.Empty<bool>();
+        var result = new bool[_spritePool.Length];
+        for (int i = 0; i < _spritePool.Length; i++)
+        {
+            var s = _spritePool[i];
+            result[i] = s != null && s.IsVisible;
+        }
+        return result;
+    }
+
     /// <summary>Stops the auto-refresh loop installed by <see cref="EnableAutoRefresh"/>.</summary>
     public void DisableAutoRefresh()
     {

src/Combobulate/CombobulateSceneVisual.cs

@@ -381,6 +381,10 @@ private void UpdateRootLayout()
     public void SetExternalRotation(ExpressionAnimation rotationDegrees)
     {
         if (rotationDegrees is null) throw new ArgumentNullException(nameof(rotationDegrees));
+        // See Combobulate.SetExternalRotation: re-installing the same expression
+        // every slider tick re-creates the composition animation chain and
+        // produces a one-frame transform lag. Idempotent install fixes that.
+        if (ReferenceEquals(_externalRotationExpression, rotationDegrees)) return;
         _externalRotationExpression = rotationDegrees;
         TryStartExternalRotationAnimation();
     }
@@ -515,6 +519,20 @@ private void DisposeSceneTree()
     public void RebuildForExternalRotation(Vector3 rotationDegrees)
     {
         RebuildMesh(rotationDegrees);
+        // The mesh now has the full rotation baked into its vertices. If
+        // SetExternalRotation also installed a 2D affine TransformMatrix
+        // animation against the rasterised surface, that animation would
+        // double-apply on top of the baked rotation (visually: the right-
+        // hand SceneVisual gets rotated/skewed twice). Stop the surface
+        // animation and reset to identity so the baked mesh is the sole
+        // source of truth. The expression buffer ("R") is left running
+        // so callers can still drive the next rebake through the same
+        // property set without re-installing.
+        if (_surfaceSprite != null && _externalRotationExpression != null)
+        {
+            _surfaceSprite.StopAnimation("TransformMatrix");
+            _surfaceSprite.TransformMatrix = Matrix4x4.Identity;
+        }
     }
 
     private void RebuildMesh() => RebuildMesh(rotationOverride: null);