drawnui-react 0.1.0-preview.2 → 0.1.0-preview.20

package/dist/core/SkiaControl.js

@@ -1,4 +1,5 @@
 import { Super } from "./Super";
+import { SkiaStyles } from "./Styles";
 import { Colors, SKRect, ScaledSize, Thickness } from "./Types";
 import { RippleAnimator, SkiaValueAnimator } from "./Animators";
 import { Easing } from "./Easing";
@@ -21,12 +22,29 @@ export class CachedObject {
         this.Picture = Picture;
         this.Image = Image;
     }
-    /** Replays the cache with its top-left moved to (left, top). */
-    Draw(canvas, left, top) {
+    /** Canvas.GpuEpoch it was made in: after a WebGL context restore it is remade (a picture may replay old GPU images). */
+    Epoch = 0;
+    /** A picture recorded to be drawn distorted: the images in it sample smoothly (C# CachedObject.PlaybackDistorted). */
+    PlaybackDistorted = false;
+    /** A picture holding image blits, whose sampling was fixed when it was recorded (C# CachedObject.HasImageBlits). */
+    HasImageBlits = false;
+    /** C# PaintRenderObject: the blit paint is antialiased (else a turned bitmap keeps stair steps along its own border), dithered when distorted. */
+    static blitPaint;
+    static blitPaintDithered;
+    static BlitPaint(dither) {
+        const CK = Super.CK;
+        const make = () => { const p = new CK.Paint(); p.setAntiAlias(true); p.setDither(dither); return p; };
+        return dither ? (CachedObject.blitPaintDithered ??= make()) : (CachedObject.blitPaint ??= make());
+    }
+    /** Replays the cache with its top-left moved to (left, top); `smooth` = an image drawn distorted (linear + mipmaps). */
+    Draw(canvas, left, top, smooth = false) {
         const CK = Super.CK;
         if (this.Image) {
-            // Nearest sampling: a cached bitmap is blitted 1:1, never resampled.
-            canvas.drawImageOptions(this.Image, left, top, CK.FilterMode.Nearest, CK.MipmapMode.None, null);
+            // nearest keeps a bitmap blitted 1:1 sharp; once scaled, turned or projected it needs smooth sampling (C# 1e4610f6)
+            if (smooth)
+                canvas.drawImageOptions(this.Image, left, top, CK.FilterMode.Linear, CK.MipmapMode.Linear, CachedObject.BlitPaint(true));
+            else
+                canvas.drawImageOptions(this.Image, left, top, CK.FilterMode.Nearest, CK.MipmapMode.None, CachedObject.BlitPaint(false));
         }
         else if (this.Picture) {
             const saved = canvas.save();
@@ -86,6 +104,14 @@ export class SkiaControl {
     /** Degrees. */
     SkewX = 0;
     SkewY = 0;
+    /** Degrees, a 3D turn around the horizontal axis through the pivot, seen with perspective (C# RotationX). */
+    RotationX = 0;
+    /** Degrees, a 3D turn around the vertical axis through the pivot (C# RotationY). */
+    RotationY = 0;
+    /** Degrees, a 3D turn around the axis facing the viewer, after RotationX and RotationY (C# RotationZ). */
+    RotationZ = 0;
+    /** Depth: toward the viewer (+, bigger) or away (−, smaller), turned or flat; draws at 576 / (576 − TranslationZ) (C# TranslationZ). */
+    TranslationZ = 0;
     /** Pivot for Rotation/Scale/Skew as a fraction of the box (MAUI default 0.5). */
     AnchorX = 0.5;
     AnchorY = 0.5;
@@ -113,8 +139,9 @@ export class SkiaControl {
     get Scale() { return this.ScaleX; }
     set Scale(v) { this.ScaleX = v; this.ScaleY = v; }
     get HasTransform() {
-        return this.TranslationX !== 0 || this.TranslationY !== 0 || this.Left !== 0 || this.Top !== 0 || this.Rotation !== 0 || this.ScaleX !== 1 || this.ScaleY !== 1 || this.SkewX !== 0 || this.SkewY !== 0;
+        return this.TranslationX !== 0 || this.TranslationY !== 0 || this.Left !== 0 || this.Top !== 0 || this.Rotation !== 0 || this.ScaleX !== 1 || this.ScaleY !== 1 || this.SkewX !== 0 || this.SkewY !== 0 || this.Has3d;
     }
+    get Has3d() { return this.RotationX !== 0 || this.RotationY !== 0 || this.RotationZ !== 0 || this.TranslationZ !== 0; }
     /** Matrix applied at the last render (canvas space), undefined when none; gestures map through its inverse. */
     RenderTransformMatrix;
     /** Generic numeric parameters (DrawnUi Value1/Value2): SkiaShape Arc uses start angle / sweep angle in degrees. */
@@ -131,6 +158,7 @@ export class SkiaControl {
             return;
         this.bindingContext = value;
         this.OnBindingContextChanged();
+        this.Superview?.Hover?.RequestCheck(); // a recycled cell under a still mouse now shows another item
     }
     /** Index of the bound item inside its ItemsSource, -1 when not templated. */
     ContextIndex = -1;
@@ -163,15 +191,52 @@ export class SkiaControl {
     compositeSurface;
     /** Own content or structure changed: the next composite record is a full one. */
     compositeFull = true;
+    /** Where the kept composite surface starts relative to DrawingRect (the effects margin it was laid out with). */
+    compositeInsetX = 0;
+    compositeInsetY = 0;
     /** Canvas-pixel bounds this control covered when its parent last recorded it (composite erase region). */
     lastCompositeBounds;
-    /** What the last composite record did (diagnostics): "full" or "partial", the number of children re-recorded and which ones. */
-    LastCompositeRecord = { Mode: "full", Children: 0, Dirty: [] };
+    /**
+     * What the last composite record did (diagnostics): "full" or "partial", the number of children re-recorded and which
+     * ones; Areas: the pixels erased and drawn again for changes deeper than a child (C# Areas), Changed: the controls
+     * those areas belong to (C# Changed).
+     */
+    LastCompositeRecord = { Mode: "full", Children: 0, Dirty: [], Areas: [], Changed: [] };
+    /** C# MaxCompositionAreas: more areas than this in one composite record draw it whole instead. */
+    static MaxCompositionAreas = 16;
+    /** C# MaxCompositionShare: areas covering more than this share of a composite draw it whole instead. */
+    static MaxCompositionShare = 0.5;
+    /**
+     * Changes deeper than a direct child since the last composite record (drawnui-cross 6m): the control, the direct child
+     * it is in, where it was drawn before the change (its own drawn bounds, as drawn) and its rect then.
+     */
+    compositeDeep;
+    /** Set while an UpdateDraw climbs: the ancestors re-measure but an ImageComposite among them keeps its partial record. */
+    static drawOrigin = null;
     /** The children a composite record can re-record individually; layouts return their views. */
     GetCompositeChildren() { return []; }
     /** C# TrackChildAsDirty (DirtyChildrenTracker): the child changed without a remeasure of this control. */
     TrackChildAsDirty(child) { if (this.IsCacheComposite)
         this.DirtyChildrenInternal.add(child); }
+    static rejectRect = new Float32Array(4);
+    /** Its cache must be recorded before it can be drawn (none, dirty, another type, scale, size or GPU context). */
+    CacheStale(scale) {
+        const cacheType = this.UsingCacheType;
+        if (cacheType === "None")
+            return false;
+        const o = this.RenderObject, r = cacheType === "Operations" ? this.ExpandedCacheRect(scale) : this.AlignedCacheRect(scale);
+        return this.cacheDirty || !o || o.Type !== cacheType || o.Epoch !== (this.Superview?.GpuEpoch ?? 0) || o.Scale !== scale
+            || Math.round(o.Bounds.Width) !== Math.round(r.Width) || Math.round(o.Bounds.Height) !== Math.round(r.Height);
+    }
+    /** Its rect grown by its effects margin, through the matrix it is drawn with, lies outside the canvas clip. */
+    OutsideClip(canvas, scale) {
+        const b = SkiaControl.MapRect(this.RenderTransformMatrix, this.ExpandedCacheRect(scale)), q = SkiaControl.rejectRect;
+        q[0] = b.Left;
+        q[1] = b.Top;
+        q[2] = b.Right;
+        q[3] = b.Bottom;
+        return canvas.quickReject(q);
+    }
     /** Drawn bounds in canvas pixels including transforms and effects margins (C# GetTransformedDirtyBounds). */
     GetTransformedDirtyBounds() {
         const r = this.ExpandedCacheRect(this.RenderingScale), m = this.RenderTransformMatrix;
@@ -190,6 +255,57 @@ export class SkiaControl {
     /** Consume every gesture that lands on this control so nothing below (z-order) receives it. */
     BlockGesturesBelow = false;
     LockChildrenGestures = "Disabled";
+    // ---- hover (drawnui-cross 6m, C# ReceivesHover / IsHovered / HoverChanged) ----
+    receivesHover;
+    /**
+     * Whether this control takes mouse hover: the canvas sets IsHovered while the mouse is over it. Opt-in: false by
+     * default, true by default only in the controls that always had hover (SkiaButton, SkiaSlider, the toggles,
+     * SkiaRadioButton, SkiaCarousel, SkiaDrawer), never because a control has a tap handler. A HoverChanged handler turns
+     * it on (C# fluent OnHovered) unless it is set.
+     */
+    get ReceivesHover() { return this.receivesHover ?? (this.HoverChanged ? true : this.ReceivesHoverByDefault()); }
+    set ReceivesHover(value) { this.receivesHover = value; }
+    /** The value of ReceivesHover until it is set. */
+    ReceivesHoverByDefault() { return false; }
+    isHovered = false;
+    /**
+     * True while the mouse is over this control and it takes hover. Every such control under the pointer is hovered at
+     * once (a card and the button inside it, as CSS :hover); it stays as it is while content moves under the pointer and
+     * is checked again when that stops. Touch never hovers.
+     */
+    get IsHovered() { return this.isHovered; }
+    /** IsHovered changed: true when the mouse came over this control, false when it left (C# HoverChanged / OnHovered). */
+    HoverChanged;
+    /** Set by the canvas's HoverManager. */
+    ApplyHover(on) {
+        if (this.isHovered === on)
+            return;
+        this.isHovered = on;
+        this.HoverChanged?.(this, on);
+    }
+    /** A scroll, carousel or drawer moving its content right now: hover waits until it stops (C# IsScrolling / InTransition). */
+    MovesContent() { return false; }
+    /**
+     * Hover hit path (HoverManager): this control is under the point (in its own space), its children under it follow,
+     * top-most first, by the routing rules of ProcessGestures. True when this subtree blocks gestures below it, so the
+     * controls under it get no hover (a popup over a list).
+     */
+    CollectHovered(point, into, xs, ys) {
+        into.push(this);
+        xs?.push(point.X);
+        ys?.push(point.Y);
+        if (!this.CheckChildrenGesturesLocked("Pointer")) {
+            const listeners = this.GetGestureListeners();
+            for (let i = listeners.length - 1; i >= 0; i--) {
+                const child = listeners[i];
+                if (!child.IsVisible || child.InputTransparent || !this.IsGestureForChild(child, point))
+                    continue;
+                if (child.CollectHovered(child.TransformPointToLocalSpace(point), into, xs, ys))
+                    return true;
+            }
+        }
+        return this.BlockGesturesBelow;
+    }
     // ---- touch feedback (same names as DrawnUi) ----
     TouchEffectColor = Colors.White;
     /** Plays a ripple (from the tap point) when Tapped fires. */
@@ -198,6 +314,11 @@ export class SkiaControl {
     AnimationTappedSpeed = 0;
     /** Overlay effects drawn above this control's content every frame (ripple etc). */
     PostAnimators = [];
+    /**
+     * C# PendingUnattachedAnimators: animators started while no Canvas was above this control yet (e.g. a game loop
+     * started in a constructor). They start on the control's first arrange, where C# starts them in SuperViewChanged.
+     */
+    PendingUnattachedAnimators;
     // ---- visual effects (C# VisualEffects: attached SkiaEffect objects) ----
     visualEffects = [];
     /** Post-renderer effects among VisualEffects (C# EffectPostRenderers). */
@@ -229,10 +350,18 @@ export class SkiaControl {
             return [];
         return this.EffectPostRenderers.filter((e) => e.NeedApply);
     }
-    /** C# CachedImage: the cached texture and the canvas rect it was rasterized over (Image caches only). */
+    /**
+     * C# CachedImage: the cached texture (Image caches only) and the canvas rect it covers NOW. Scrolled content is
+     * re-arranged here, not drawn through a translated canvas, so a cache recorded before its control moved is blitted
+     * at the control's current aligned rect (RenderContent) and its record-time Bounds are stale: an effect sampling it
+     * there (the slides of a SkiaShaderCarousel after the page scrolled) was off by the scroll amount.
+     */
     get CachedImage() {
         const c = this.RenderObject;
-        return c?.Image ? { Image: c.Image, Bounds: c.Bounds } : undefined;
+        if (!c?.Image)
+            return undefined;
+        const r = this.AlignedCacheRect(c.Scale);
+        return { Image: c.Image, Bounds: SKRect.Create(r.Left, r.Top, c.Bounds.Width, c.Bounds.Height) };
     }
     /** Clip overlay effects to the control's shape (CreateClip). */
     ClipEffects = true;
@@ -250,6 +379,22 @@ export class SkiaControl {
     // ---- tree ----
     Parent;
     /** Containers override; a leaf control cannot host children. */
+    styledInitially = false;
+    /**
+     * C# ApplyInitialStyles: takes the property defaults registered with `ConfigureStyles` for this control's class.
+     * The reconciler calls it with `atConstruction` right after `new`, before the JSX props, so props win; a control
+     * built in code-behind is styled on its first measure and keeps whatever the code already set.
+     */
+    ApplyInitialStyles(atConstruction = false) {
+        this.styledInitially = true;
+        if (!SkiaStyles.IsEmpty)
+            SkiaStyles.Apply(this, atConstruction);
+    }
+    /**
+     * C# IsChildrenItem: added by the app (JSX children or the `Children` list), not a part the control made itself. A new
+     * `Children` list drops only these, so a control's own parts keep their place.
+     */
+    IsChildrenItem = false;
     AddSubView(_control) { throw new Error(`DrawnUi: ${this.constructor.name} cannot host children`); }
     InsertSubView(_index, control) { this.AddSubView(control); }
     RemoveSubView(_control) { }
@@ -271,6 +416,8 @@ export class SkiaControl {
      * this is what keeps a cached tree from re-measuring text every frame.
      */
     Measure(widthConstraint, heightConstraint, scale) {
+        if (!this.styledInitially)
+            this.ApplyInitialStyles(false);
         if (!this.NeedMeasure && this.RenderingScale === scale
             && Object.is(this.lastWidthConstraint, widthConstraint) && Object.is(this.lastHeightConstraint, heightConstraint)) {
             return this.MeasuredSize;
@@ -347,12 +494,37 @@ export class SkiaControl {
         const fullW = destination.Width - m.HorizontalThickness * scale, fullH = destination.Height - m.VerticalThickness * scale;
         const x = availL + SkiaControl.Align(this.HorizontalOptions, fullW, w);
         const y = availT + SkiaControl.Align(this.VerticalOptions, fullH, h);
+        const old = this.DrawingRect;
         this.DrawingRect = SKRect.Create(x, y, w, h);
+        this.FollowMatrix(old);
         this.OnLayoutChanged();
+        if (this.PendingUnattachedAnimators)
+            this.StartPendingAnimators();
         // DrawnUi OnLayoutReady: an accessible control registers itself on its first layout
         if (!this.registeredWithAccessibility && this.IsAccessibilityElement)
             this.NotifyAccessibility();
     }
+    /**
+     * A cached ancestor replays its picture where a re-arrange moved it (a scroll) without rendering this control again,
+     * so the matrix made at its last Render moves with its rect: taps, hover and the accessibility rect stay on what is
+     * drawn (C# offsets the cached render tree instead). A control that renders again gets a fresh matrix there.
+     */
+    FollowMatrix(old) {
+        const m = this.RenderTransformMatrix, r = this.DrawingRect;
+        if (!m || (old.Left === r.Left && old.Top === r.Top))
+            return;
+        const M = Super.CK.Matrix, dx = r.Left - old.Left, dy = r.Top - old.Top;
+        this.RenderTransformMatrix = M.multiply(M.translated(dx, dy), m, M.translated(-dx, -dy));
+    }
+    /** C# SuperViewChanged: starts the animators queued before this control was attached. */
+    StartPendingAnimators() {
+        if (!this.Superview)
+            return;
+        const pending = this.PendingUnattachedAnimators;
+        this.PendingUnattachedAnimators = undefined;
+        for (const animator of pending)
+            animator.Start();
+    }
     // ---- accessibility (DrawnUi ISkiaAccessibilityNode) ----
     static nextAccessibilityId = 1;
     /** Stable identity for the DOM overlay. */
@@ -387,8 +559,12 @@ export class SkiaControl {
         this.accessibilityHint = v;
         this.AccessibilityChanged();
     } }
-    /** Tab stop + activation; unset = true when the control handles Tapped. */
-    get AccessibilityCanInteract() { return this.accessibilityCanInteract ?? this.DefaultAccessibilityCanInteract(); }
+    /**
+     * Whether keyboard navigation and assistive technology may focus and use this node: the explicit value, else the class
+     * default (true when the control handles Tapped), and in both cases only while a tap could reach the control
+     * (CanReceiveGesture), so Tab, Enter / Space and screen-reader activation never use a control the pointer cannot.
+     */
+    get AccessibilityCanInteract() { return (this.accessibilityCanInteract ?? this.DefaultAccessibilityCanInteract()) && this.CanReceiveGesture("Tapped"); }
     set AccessibilityCanInteract(v) { if (this.accessibilityCanInteract !== v) {
         this.accessibilityCanInteract = v;
         this.AccessibilityChanged();
@@ -399,6 +575,8 @@ export class SkiaControl {
      * host's pointer cursor. Default: the control as a whole (AccessibilityCanInteract); SkiaLabel adds its tappable spans.
      */
     WantsPointerCursor(_x, _y) { return this.AccessibilityCanInteract; }
+    /** A range control's value for screen readers (slider, progress); undefined for everything else (drawnui-cross 6c). */
+    get AccessibilityValue() { return undefined; }
     /** aria-pressed for toggles; undefined = not a toggle. */
     get AccessibilityIsPressed() { return this.accessibilityIsPressed; }
     set AccessibilityIsPressed(v) { if (this.accessibilityIsPressed !== v) {
@@ -473,6 +651,39 @@ export class SkiaControl {
     }
     /** Overlay focus arrives on / leaves this node (inputs may activate their sink here). */
     OnAccessibilityFocused(_focused) { }
+    /**
+     * Keyboard navigation hands this control the keys it may use while it holds keyboard focus (ArrowLeft / Right / Up /
+     * Down, Home, End, PageUp, PageDown, DOM `event.code` names). Return true when the key was used; the default uses none,
+     * so the key moves focus inside the arrow-key group around the control.
+     */
+    OnAccessibilityKey(_key) { return false; }
+    /**
+     * Whether a pointer gesture of this kind would reach this control, by the rules the gesture dispatch applies: the
+     * control and every ancestor draw, none of them is InputTransparent, no ancestor keeps this gesture from its children
+     * (LockChildrenGestures, PassNone included) and the control accepts input (AcceptsInput). Opacity does not count, as
+     * for the pointer. Keyboard navigation uses it: Tapped for Tab and Enter / Space, Panning for the arrow keys.
+     */
+    CanReceiveGesture(gesture) {
+        if (!this.IsVisible || this.IsDisposed || this.InputTransparent || !this.AcceptsInput())
+            return false;
+        for (let p = this.Parent; p; p = p.Parent)
+            if (!p.IsVisible || p.IsDisposed || p.InputTransparent || p.CheckChildrenGesturesLocked(gesture))
+                return false;
+        return true;
+    }
+    /**
+     * False while the control ignores input itself: RespondsToGestures = false on a button, toggle, slider, scroll...
+     * Taps, keyboard and the accessibility state (reported disabled) all follow it (drawnui-cross 6w). Default true.
+     */
+    AcceptsInput() { return true; }
+    /**
+     * What a control that takes no input returns for a gesture that reached it (C# BlockedGestureResult): it keeps a
+     * press, tap or long press, so nothing under it reacts to them, and lets moves and wheel go on to the controls around
+     * it (a scroll behind it still scrolls).
+     */
+    BlockedGestureResult(args) {
+        return args.Type === "Down" || args.Type === "Tapped" || args.Type === "LongPressing" ? this : null;
+    }
     NotifyAccessibilityFocused(focused) { this.Superview?.AccessibilityManager.NotifyFocused(focused ? this : undefined); }
     /** DrawnUi SmartMax: larger of two sizes, an infinite one loses. */
     static SmartMax(a, b) {
@@ -538,8 +749,25 @@ export class SkiaControl {
         const applyOpacity = this.Opacity < 1;
         // C# Left/Top: a cached control is blitted at an offset, no matrix and no save/restore around the subtree
         const offsetOnly = (this.Left !== 0 || this.Top !== 0) && this.UsingCacheType !== "None" && this.TranslationX === 0 && this.TranslationY === 0
-            && this.Rotation === 0 && this.ScaleX === 1 && this.ScaleY === 1 && this.SkewX === 0 && this.SkewY === 0;
+            && this.Rotation === 0 && this.ScaleX === 1 && this.ScaleY === 1 && this.SkewX === 0 && this.SkewY === 0 && !this.Has3d;
         const needTransform = this.HasTransform && !offsetOnly;
+        let dx = 0, dy = 0;
+        if (needTransform) {
+            this.RenderTransformMatrix = this.CreateRenderTransformMatrix(this.DrawingRect, ctx.Scale);
+        }
+        else if (offsetOnly) {
+            dx = this.Left * ctx.Scale;
+            dy = this.Top * ctx.Scale;
+            this.RenderTransformMatrix = Super.CK.Matrix.translated(dx, dy); // gestures / accessibility still map through it
+        }
+        else {
+            this.RenderTransformMatrix = undefined;
+        }
+        // drawn entirely outside the clip: skipped with its subtree (C# layout Virtualisation, DrawnUi.Rust); the matrix
+        // above stays current for hit tests. A cache that must be recorded is still recorded here, as before, so its cost
+        // does not move into the frame where the control scrolls in (DrawnUi.Rust records it then)
+        if (this.OutsideClip(canvas, ctx.Scale) && !this.CacheStale(ctx.Scale))
+            return;
         let saved = false;
         // same as DrawnUi: opacity = a layer with alpha, transforms = canvas matrix around the whole subtree (cache included)
         if (applyOpacity) {
@@ -553,19 +781,8 @@ export class SkiaControl {
             canvas.save();
             saved = true;
         }
-        let dx = 0, dy = 0;
-        if (needTransform) {
-            this.RenderTransformMatrix = this.CreateRenderTransformMatrix(this.DrawingRect, ctx.Scale);
+        if (needTransform)
             canvas.concat(this.RenderTransformMatrix);
-        }
-        else if (offsetOnly) {
-            dx = this.Left * ctx.Scale;
-            dy = this.Top * ctx.Scale;
-            this.RenderTransformMatrix = Super.CK.Matrix.translated(dx, dy); // gestures / accessibility still map through it
-        }
-        else {
-            this.RenderTransformMatrix = undefined;
-        }
         if (this.IsClippedToBounds) {
             if (!saved) {
                 canvas.save();
@@ -578,11 +795,12 @@ export class SkiaControl {
         if (saved)
             canvas.restore();
     }
-    /** Port of DrawnUi ApplyTransforms: T(-pivot) · rotation · scale/skew · T(pivot) · translation, in canvas pixels. */
+    /** Port of DrawnUi ApplyTransforms: T(-pivot) · rotation · scale/skew · 3D · T(pivot) · translation, in canvas pixels. */
     CreateRenderTransformMatrix(destination, scale) {
         const M = Super.CK.Matrix;
         const moveX = (this.TranslationX + this.Left) * scale, moveY = (this.TranslationY + this.Top) * scale;
-        if (this.Rotation === 0 && this.ScaleX === 1 && this.ScaleY === 1 && this.SkewX === 0 && this.SkewY === 0)
+        const has3d = this.Has3d;
+        if (this.Rotation === 0 && this.ScaleX === 1 && this.ScaleY === 1 && this.SkewX === 0 && this.SkewY === 0 && !has3d)
             return M.translated(moveX, moveY);
         const px = destination.Left + destination.Width * this.AnchorX;
         const py = destination.Top + destination.Height * this.AnchorY;
@@ -591,7 +809,36 @@ export class SkiaControl {
         const scaleSkew = [this.ScaleX, kx, 0, ky, this.ScaleY, 0, 0, 0, 1];
         const rotation = this.Rotation !== 0 ? M.rotated((Math.PI * this.Rotation) / 180) : M.identity();
         // multiply(a, b, c) = a·b·c, the right-most applies first
-        return M.multiply(M.translated(px + moveX, py + moveY), scaleSkew, rotation, M.translated(-px, -py));
+        if (!has3d)
+            return M.multiply(M.translated(px + moveX, py + moveY), scaleSkew, rotation, M.translated(-px, -py));
+        return M.multiply(M.translated(px + moveX, py + moveY), SkiaControl.Create3dMatrix(this.RotationX, this.RotationY, this.RotationZ, this.TranslationZ), scaleSkew, rotation, M.translated(-px, -py));
+    }
+    /** C# camera distance of the 3D transforms (Sk3dView.CameraDistance): 8 inches at 72 dpi, in canvas pixels. */
+    static CameraDistance = 576;
+    /**
+     * C# Create3dMatrix (Sk3dView): RotationX, then RotationY, then RotationZ (negated) around the pivot, projected from
+     * the camera; TranslationZ is depth, a flat control at depth z draws at camera / (camera − z).
+     */
+    static Create3dMatrix(rotationX, rotationY, rotationZ, translationZ) {
+        const d = Math.PI / 180, camera = SkiaControl.CameraDistance;
+        const sx = Math.sin(rotationX * d), cx = Math.cos(rotationX * d), sy = Math.sin(rotationY * d), cy = Math.cos(rotationY * d);
+        const sz = Math.sin(-rotationZ * d), cz = Math.cos(-rotationZ * d);
+        return [
+            cy * cz, cy * sz, 0,
+            sx * sy * cz - cx * sz, sx * sy * sz + cx * cz, 0,
+            (cx * sy * cz + sx * sz) / camera, (cx * sy * sz - sx * cz) / camera, Math.max(camera - translationZ, 1) / camera,
+        ];
+    }
+    /** C# SkiaSamplingOptions.IsMoveOnly: the matrix only moves (or mirrors), so a bitmap keeps its pixels 1:1. */
+    static IsMoveOnly(m) {
+        return m[1] === 0 && m[3] === 0 && m[6] === 0 && m[7] === 0 && m[8] === 1 && Math.abs(m[0]) === 1 && Math.abs(m[4]) === 1;
+    }
+    /**
+     * C# WillDrawDistorted: what this control draws here ends up scaled, turned, skewed or projected, by its own transforms
+     * or a live ancestor's (both in the canvas matrix) or by the picture it is recorded into. Images then sample smoothly.
+     */
+    WillDrawDistorted(ctx) {
+        return !!ctx.Context.PlaybackDistorted || !SkiaControl.IsMoveOnly(ctx.Context.Canvas.getTotalMatrix());
     }
     /** Maps a point given in the parent's space into this control's untransformed space (DrawnUi TransformPointToLocalSpace). */
     TransformPointToLocalSpace(point) {
@@ -627,26 +874,35 @@ export class SkiaControl {
         }
         else {
             const r = cacheType === "Operations" ? this.ExpandedCacheRect(ctx.Scale) : this.AlignedCacheRect(ctx.Scale);
-            const stale = this.cacheDirty || !this.RenderObject || this.RenderObject.Type !== cacheType
-                || this.RenderObject.Scale !== ctx.Scale
-                || Math.round(this.RenderObject.Bounds.Width) !== Math.round(r.Width) || Math.round(this.RenderObject.Bounds.Height) !== Math.round(r.Height);
-            if (stale)
+            const epoch = this.Superview?.GpuEpoch ?? 0;
+            if (this.RenderObjectPrevious && this.RenderObjectPrevious.Epoch !== epoch)
+                this.DisposePrevious(); // made on a lost GPU context
+            // a picture replays its image blits with the sampling chosen when it was recorded: recorded again once its
+            // playback turns distorted or straight (C# SamplingMismatch), else a cached child of a turning card stays jagged
+            const o = this.RenderObject;
+            if (this.CacheStale(ctx.Scale) || (o?.Picture && o.HasImageBlits && o.PlaybackDistorted !== this.WillDrawDistorted(ctx)))
                 this.CreateRenderingObject({ ...ctx, Destination: this.DrawingRect }, cacheType);
             if (this.RenderObject) {
                 // C# DrawRenderObject: with post renderers an Image cache is not blitted, the effects sample it (CachedImage)
                 // and paint the result; a picture cache has no texture, so it is replayed first and snapshotted by the effect
                 if (post.length === 0 || !this.RenderObject.Image)
-                    this.RenderObject.Draw(ctx.Context.Canvas, r.Left + dx, r.Top + dy);
+                    this.DrawCache(this.RenderObject, ctx, r.Left + dx, r.Top + dy);
                 for (const e of post)
                     e.Render(own);
             }
             else if (this.RenderObjectPrevious)
-                this.RenderObjectPrevious.Draw(ctx.Context.Canvas, r.Left + dx, r.Top + dy); // double buffer: last good frame
+                this.DrawCache(this.RenderObjectPrevious, ctx, r.Left + dx, r.Top + dy); // double buffer: last good frame
             else
                 this.DrawPlaceholder(own);
         }
         this.ExecutePostAnimators(own);
     }
+    /** Blits a cache: an image samples smoothly when drawn distorted; a picture being recorded learns it holds image blits. */
+    DrawCache(cache, ctx, left, top) {
+        if (cache.Image || cache.HasImageBlits)
+            ctx.Context.HasImageBlits = true;
+        cache.Draw(ctx.Context.Canvas, left, top, !!cache.Image && this.WillDrawDistorted(ctx));
+    }
     /** Background + Paint(): the part of the control that a cache captures. */
     PaintContent(ctx) {
         if (this.BackgroundColor || (this.FillGradient && this.FillGradientPaintsBackground()) || this.PaintsBackgroundWithoutColor())
@@ -681,11 +937,16 @@ export class SkiaControl {
         }
         if (cacheType === "Operations") {
             const recorder = new CK.PictureRecorder();
+            const playbackDistorted = this.WillDrawDistorted(ctx);
             const canvas = recorder.beginRecording(CK.LTRBRect(r.Left, r.Top, r.Right, r.Bottom));
-            this.PaintContent({ ...ctx, Context: { ...ctx.Context, Canvas: canvas, Recording: true } });
+            const recording = { ...ctx.Context, Canvas: canvas, Recording: true, PlaybackDistorted: playbackDistorted, HasImageBlits: false };
+            this.PaintContent({ ...ctx, Context: recording });
             const picture = recorder.finishRecordingAsPicture();
             recorder.delete();
             this.RenderObject = new CachedObject("Operations", r, ctx.Scale, picture);
+            this.RenderObject.Epoch = this.Superview?.GpuEpoch ?? 0;
+            this.RenderObject.PlaybackDistorted = playbackDistorted;
+            this.RenderObject.HasImageBlits = recording.HasImageBlits;
         }
         else if (cacheType === "ImageComposite") {
             this.CreateCompositeRenderingObject(ctx, r, w, h);
@@ -709,6 +970,7 @@ export class SkiaControl {
             const image = offscreen.makeImageSnapshot();
             offscreen.delete();
             this.RenderObject = new CachedObject(cacheType, r, ctx.Scale, undefined, image);
+            this.RenderObject.Epoch = this.Superview?.GpuEpoch ?? 0;
         }
         this.cacheDirty = false;
     }
@@ -727,7 +989,9 @@ export class SkiaControl {
         }
         let surface = this.compositeSurface;
         const prev = this.RenderObject;
-        const sameGeometry = !!surface && !!prev && prev.Type === "ImageComposite" && prev.Scale === ctx.Scale
+        const epoch = this.Superview?.GpuEpoch ?? 0;
+        // the kept surface belongs to the GPU context it was made on: after a context restore it is made again
+        const sameGeometry = !!surface && !!prev && prev.Type === "ImageComposite" && prev.Scale === ctx.Scale && prev.Epoch === epoch
             && Math.round(prev.Bounds.Width) === w && Math.round(prev.Bounds.Height) === h;
         if (!sameGeometry) {
             surface?.delete();
@@ -740,14 +1004,46 @@ export class SkiaControl {
         }
         const canvas = surface.getCanvas();
         const children = this.GetCompositeChildren();
-        const partial = sameGeometry && !this.compositeFull && this.DirtyChildrenInternal.size > 0 && children.length > 0;
+        const deep = this.compositeDeep;
+        // the same size with another effects margin moves the content inside the surface: record whole (C# 97683f19)
+        const insetX = r.Left - this.DrawingRect.Left, insetY = r.Top - this.DrawingRect.Top;
+        const sameInset = insetX === this.compositeInsetX && insetY === this.compositeInsetY;
+        this.compositeInsetX = insetX;
+        this.compositeInsetY = insetY;
+        let partial = sameGeometry && sameInset && !this.compositeFull && children.length > 0 && (this.DirtyChildrenInternal.size > 0 || !!deep?.length);
+        // changes deeper than a child: only their areas, the child they are in drawn clipped to them (drawnui-cross 6m)
+        const areas = [], changed = [], inside = new Set();
+        if (partial && deep?.length) {
+            let covered = 0;
+            for (const d of deep) {
+                if (!children.includes(d.Child) || this.DirtyChildrenInternal.has(d.Child))
+                    continue;
+                const area = SkiaControl.DeepArea(d, this, ctx.Scale);
+                if (area === null) {
+                    partial = false;
+                    break;
+                }
+                if (!area) {
+                    this.DirtyChildrenInternal.add(d.Child);
+                    continue;
+                }
+                areas.push(area);
+                changed.push(d.Origin);
+                inside.add(d.Child);
+                covered += area.Width * area.Height;
+            }
+            if (areas.length > SkiaControl.MaxCompositionAreas || covered > r.Width * r.Height * SkiaControl.MaxCompositionShare)
+                partial = false;
+        }
+        if (deep)
+            deep.length = 0;
         const offset = prev && sameGeometry ? { X: r.Left - prev.Bounds.Left, Y: r.Top - prev.Bounds.Top } : { X: 0, Y: 0 };
         const saved = canvas.save();
         canvas.translate(-r.Left, -r.Top);
         if (partial) {
             // dirty = reported children + siblings intersecting their old or new bounds (C# makes intersecting children dirty too)
             const dirty = new Set();
-            const rects = [];
+            const rects = [...areas];
             const boundsOf = (c) => {
                 const out = [c.GetTransformedDirtyBounds()];
                 if (c.lastCompositeBounds)
@@ -763,7 +1059,7 @@ export class SkiaControl {
             while (grew) {
                 grew = false;
                 for (const c of children) {
-                    if (dirty.has(c) || !c.IsVisible)
+                    if (dirty.has(c) || inside.has(c) || !c.IsVisible)
                         continue;
                     const own = boundsOf(c);
                     if (rects.some((d) => own.some((o) => o.Left < d.Right && d.Left < o.Right && o.Top < d.Bottom && d.Top < o.Bottom))) {
@@ -790,14 +1086,18 @@ export class SkiaControl {
             this.DirtyChildrenInternal.clear();
             for (const c of dirty)
                 this.DirtyChildrenInternal.add(c);
+            for (const c of inside)
+                this.DirtyChildrenInternal.add(c);
+            // children entirely outside the redrawn areas are skipped by their own clip check (Render)
             this.PaintContent({ ...ctx, Context: { Canvas: canvas, Surface: surface, Origin: { X: r.Left, Y: r.Top } } });
             this.IsRenderingWithComposition = false;
-            this.LastCompositeRecord = { Mode: "partial", Children: dirty.size, Dirty: [...dirty] };
+            const redrawn = children.filter((c) => this.DirtyChildrenInternal.has(c));
+            this.LastCompositeRecord = { Mode: "partial", Children: redrawn.length, Dirty: redrawn, Areas: areas, Changed: changed };
         }
         else {
             canvas.clear(CK.TRANSPARENT);
             this.PaintContent({ ...ctx, Context: { Canvas: canvas, Surface: surface, Origin: { X: r.Left, Y: r.Top } } });
-            this.LastCompositeRecord = { Mode: "full", Children: children.length, Dirty: children };
+            this.LastCompositeRecord = { Mode: "full", Children: children.length, Dirty: children, Areas: [], Changed: [] };
         }
         canvas.restoreToCount(saved);
         for (const c of children)
@@ -807,6 +1107,7 @@ export class SkiaControl {
         const image = surface.makeImageSnapshot();
         const old = this.RenderObject;
         this.RenderObject = new CachedObject("ImageComposite", r, ctx.Scale, undefined, image);
+        this.RenderObject.Epoch = epoch;
         if (old) {
             const sv = this.Superview;
             if (sv)
@@ -842,7 +1143,11 @@ export class SkiaControl {
     /** Marks the cache stale; re-recorded on the next frame (a composite records fully: its own content changed). */
     InvalidateCache() { this.cacheDirty = true; this.compositeFull = true; }
     /** Effects margin recomputed on the next use (C# InvalidateEffectsMargin). */
-    InvalidateEffectsMargin() { this.effectsMarginCache = undefined; }
+    InvalidateEffectsMargin() {
+        // a layout's margin aggregates what its children paint outside it: every ancestor recomputes too (C# 97683f19)
+        for (let c = this; c; c = c.Parent)
+            c.effectsMarginCache = undefined;
+    }
     /** Draws PostAnimators above content; an effect returning true asks for another frame. */
     ExecutePostAnimators(ctx) {
         if (this.PostAnimators.length === 0)
@@ -1024,6 +1329,7 @@ export class SkiaControl {
         this.ownAnimations.clear();
         for (const e of [...this.PostAnimators])
             e.Stop?.();
+        this.PendingUnattachedAnimators = undefined;
         this.PostAnimators.length = 0;
         this.DestroyRenderingObject();
         this.compositeSurface?.delete();
@@ -1052,32 +1358,134 @@ export class SkiaControl {
     }
     /** Redraw without remeasure and WITHOUT dropping caches (position/overlay changes). */
     Repaint() {
-        this.Superview?.Update();
+        if (!this.UnderHiddenParent())
+            this.Superview?.Update();
+    }
+    /**
+     * A parent (not the control itself) is hidden: a change here asks for no frame and the latest state shows when the
+     * parent is shown again (C# 329f6c44 HiddenUpdateTests, DrawnUi.Rust hidden_updates). The control's own visibility
+     * change still draws: it is the one that hides or shows it.
+     */
+    UnderHiddenParent() {
+        for (let p = this.Parent; p; p = p.Parent)
+            if (!p.IsVisible)
+                return true;
+        return false;
     }
+    /** The control or a parent is hidden: its animators pause until it shows again. */
+    HiddenInTree() { return !this.IsVisible || this.UnderHiddenParent(); }
+    /** The control an invalidation started at while it climbs (InvalidateMeasure): a hidden parent of it wakes no frame. */
+    static invalidateOrigin = null;
     /**
      * Transform / Opacity changed: this control's own cache is still valid (content unchanged) but every ancestor
      * cache holds its composited output, so those are staled before redrawing (DrawnUi RedrawCanvas + parent invalidation).
      */
     RepaintComposition() {
-        let child = this, p = this.Parent;
-        while (p) {
+        this.ReportToComposites();
+        for (let p = this.Parent; p; p = p.Parent)
             p.cacheDirty = true;
-            p.TrackChildAsDirty(child);
-            child = p;
-            p = p.Parent;
-        }
         this.Repaint();
     }
+    /**
+     * Update() for a change of how this control looks, not of its size (a color set through props, C# NeedDraw): the same
+     * re-measure and cache invalidation, but an ImageComposite above redraws only this control's area instead of
+     * recording whole (drawnui-cross 6m). The record still goes whole when the control's rect changed after all.
+     */
+    UpdateDraw() {
+        this.ReportToComposites();
+        const outer = SkiaControl.drawOrigin;
+        SkiaControl.drawOrigin = this;
+        try {
+            this.InvalidateMeasure();
+        }
+        finally {
+            SkiaControl.drawOrigin = outer;
+        }
+    }
+    /**
+     * A change of this control that keeps its layout, to every ImageComposite above: a direct child is drawn again whole
+     * (C# TrackChildAsDirty), a deeper control by its area, read now as it was drawn (its last matrix and effects margin).
+     */
+    ReportToComposites() {
+        let before;
+        let child = this;
+        for (let p = this.Parent; p; child = p, p = p.Parent) {
+            if (!p.IsCacheComposite)
+                continue;
+            if (child === this) {
+                p.TrackChildAsDirty(child);
+                continue;
+            }
+            const deep = p.compositeDeep ??= [];
+            if (deep.some((d) => d.Origin === this))
+                continue;
+            before ??= this.GetTransformedDirtyBounds();
+            const r = this.DrawingRect;
+            deep.push({ Origin: this, Child: child, Before: before, Rect: new SKRect(r.Left, r.Top, r.Right, r.Bottom) });
+        }
+    }
+    /** The matrix this control will be drawn with (Render), from its current properties; undefined when none. */
+    CurrentMatrix(scale) {
+        return this.HasTransform ? this.CreateRenderTransformMatrix(this.DrawingRect, scale) : undefined;
+    }
+    /** Where this control will be drawn: its rect grown by its effects margin, through its current matrix. */
+    DrawnBoundsNow(scale) { return SkiaControl.MapRect(this.CurrentMatrix(scale), this.ExpandedCacheRect(scale)); }
+    static MapRect(m, r) {
+        if (!m)
+            return r;
+        const pts = Super.CK.Matrix.mapPoints(m, [r.Left, r.Top, r.Right, r.Top, r.Right, r.Bottom, r.Left, r.Bottom]);
+        return new SKRect(Math.min(pts[0], pts[2], pts[4], pts[6]), Math.min(pts[1], pts[3], pts[5], pts[7]), Math.max(pts[0], pts[2], pts[4], pts[6]), Math.max(pts[1], pts[3], pts[5], pts[7]));
+    }
+    /** Its output depends on all of its content (a visual effect; a backdrop samples below): a change inside redraws it whole. */
+    get SamplesContent() { return !this.DisableEffects && this.visualEffects.length > 0; }
+    /**
+     * Where a deep change shows inside the composite (drawnui-cross 6m rule b): the control as drawn before and as drawn
+     * now, then through the transform of every ancestor up to the composite. undefined: draw the child whole (an effect
+     * or a backdrop on the way, the control gone from the child); null: the layout changed, record whole.
+     */
+    static DeepArea(d, composite, scale) {
+        const o = d.Origin, r = o.DrawingRect;
+        if (r.Left !== d.Rect.Left || r.Top !== d.Rect.Top || r.Right !== d.Rect.Right || r.Bottom !== d.Rect.Bottom)
+            return null;
+        if (!o.IsVisible)
+            return undefined;
+        const now = o.DrawnBoundsNow(scale);
+        let area = new SKRect(Math.min(now.Left, d.Before.Left), Math.min(now.Top, d.Before.Top), Math.max(now.Right, d.Before.Right), Math.max(now.Bottom, d.Before.Bottom));
+        let p = o.Parent, child = o;
+        for (; p && p !== composite; child = p, p = p.Parent) {
+            if (p.SamplesContent || !p.IsVisible)
+                return undefined;
+            area = SkiaControl.MapRect(p.CurrentMatrix(scale), area);
+        }
+        return p === composite && child === d.Child ? area : undefined;
+    }
+    /**
+     * DrawnUi IsParentIndependent: this control's size never changes the layout around it, so its own invalidation
+     * stops here (ancestors composite again, nothing above re-measures). The parent re-measures it on draw when
+     * NeedMeasure is set. Used by SkiaScroll for its scroll bars.
+     */
+    IsParentIndependent = false;
     /** Size or content may have changed: this control and all ancestors remeasure and re-record. */
     InvalidateMeasure() {
         this.NeedMeasure = true;
         this.cacheDirty = true;
-        this.compositeFull = true; // structure may change: a composite cannot patch it
+        // structure may change: a composite cannot patch it; a draw-only change (UpdateDraw) reported its area instead
+        if (SkiaControl.drawOrigin === null || SkiaControl.drawOrigin === this)
+            this.compositeFull = true;
         this.effectsMarginCache = undefined;
-        if (this.Parent)
-            this.Parent.InvalidateMeasure();
-        else
-            this.Superview?.Update();
+        const outer = SkiaControl.invalidateOrigin;
+        SkiaControl.invalidateOrigin ??= this;
+        try {
+            if (this.Parent && this.IsParentIndependent)
+                this.RepaintComposition();
+            else if (this.Parent)
+                this.Parent.InvalidateMeasure();
+            else if (!SkiaControl.invalidateOrigin.UnderHiddenParent())
+                this.Superview?.Update();
+        }
+        finally {
+            SkiaControl.invalidateOrigin = outer;
+        }
     }
     // ---- gestures (same names as DrawnUi) ----
     /** Hit rect in pixels (no transforms in this port, so it is DrawingRect). */
@@ -1136,15 +1544,19 @@ export class SkiaControl {
         if (this.ConsumeGestures) {
             const sent = new SkiaGesturesInfo(args, apply);
             this.ConsumeGestures(this, sent);
-            if (args.Type !== "Up" && sent.Consumed)
+            if (args.Type !== "Up" && sent.Consumed) {
+                args.Event.Handled = true;
                 return this;
+            }
         }
         // C# EffectsGestureProcessors: attached effects that process gestures (ISkiaGestureProcessor) see them first
         if (!this.DisableEffects)
             for (const e of this.visualEffects) {
                 const p = e.ProcessGestures;
-                if (typeof p === "function" && p.call(e, args, apply) && args.Type !== "Up")
+                if (typeof p === "function" && p.call(e, args, apply) && args.Type !== "Up") {
+                    args.Event.Handled = true;
                     return this;
+                }
             }
         if (this.CheckChildrenGesturesLocked(args.Type))
             return consumedDefault;