drawnui-react 0.1.0-preview.1 → 0.1.0-preview.10

package/dist/core/Canvas.d.ts

@@ -1,9 +1,9 @@
 import type { Surface } from "canvaskit-wasm";
-import type { SkiaControl } from "./SkiaControl";
+import type { DrawingContext, SkiaControl } from "./SkiaControl";
 import type { AnimatorBase } from "./Animators";
 import { SkiaAccessibilityManager } from "./Accessibility";
 import { type Color, type RenderingModeType } from "./Types";
-import { type GesturesMode, SkiaGesturesParameters, TouchActionEventArgs } from "./Gestures";
+import { ContextMenuEventArgs, type GesturesMode, SkiaGesturesParameters, TouchActionEventArgs } from "./Gestures";
 /**
  * Mirrors DrawnUi Canvas (DrawnView): hosts one Content control on an HTML canvas element,
  * owns RenderingScale (devicePixelRatio), the surface, the on-demand frame loop and raw input.
@@ -23,6 +23,18 @@ export declare class Canvas {
     /** Frames per second over the last second of drawn frames. */
     FPS: number;
     private frameTimes;
+    /** DrawnView.WasRendered: a frame has been drawn on a ready surface (set after the first one completes). */
+    WasRendered: boolean;
+    /** DrawnView.CanRender: the surface (and its GPU context when accelerated) is ready to draw. */
+    get CanRender(): boolean;
+    /**
+     * DrawnView.WillFirstTimeDraw: raised once, right before the first frame drawn on a ready surface, with that
+     * frame's drawing context. The engine draws its first frame while it is being constructed (so the page never shows
+     * an unpainted canvas): pass it through the constructor's `init` to receive that frame.
+     */
+    WillFirstTimeDraw?: (sender: Canvas, context: DrawingContext["Context"]) => void;
+    /** DrawnView.WasDrawn: raised after every frame has been drawn (the C# event passes no context). */
+    WasDrawn?: (sender: Canvas) => void;
     /** Registry + rate-limited snapshot of accessible controls, rendered by the DOM overlay (DrawnUi AccessibilityManager). */
     readonly AccessibilityManager: SkiaAccessibilityManager;
     private content?;
@@ -35,7 +47,8 @@ export declare class Canvas {
     private frameId;
     private disposed;
     private readonly observer;
-    constructor(Element: HTMLCanvasElement);
+    /** `init` runs before the first frame is drawn: the place to attach `WillFirstTimeDraw` / `WasDrawn` for that frame. */
+    constructor(Element: HTMLCanvasElement, init?: (canvas: Canvas) => void);
     /** Request a redraw (full measure + arrange + render) on the next animation frame. */
     Update(): void;
     /** Deletes the current surface; a pending frame on it is cancelled first (drawing on a deleted surface faults). */
@@ -66,6 +79,18 @@ export declare class Canvas {
     FrameIndex: number;
     /** On-screen surface (SkiaBackdrop snapshots it). */
     get Surface(): Surface | undefined;
+    /**
+     * A picture of what is on screen right now, as PNG bytes (C# DrawnView.TakeScreenShot).
+     *
+     * The on-screen canvas cannot simply be read: an accelerated surface lives in a WebGL drawing
+     * buffer the browser clears after compositing, so both `canvas.toDataURL()` and a snapshot of
+     * the live surface come back blank. The content is therefore drawn once more into an offscreen
+     * RASTER surface, which can be read back anywhere.
+     *
+     * This is a still picture, not a frame of the loop: animators are not ticked and the frame
+     * counters do not move, so taking one never changes what the next real frame shows.
+     */
+    TakeScreenShot(): Uint8Array | null;
     Dispose(): void;
     private gestures;
     get Gestures(): GesturesMode;
@@ -76,14 +101,67 @@ export declare class Canvas {
     private readonly pendingGestures;
     private readonly onPointer;
     private readonly preventTouch;
-    /** Mouse wheel -> TouchActionResult.Wheel (page scroll suppressed while gestures are enabled). */
+    /** Gestures="Enabled": touch / pen pointers whose Down a control used (see OnTouchAction). */
+    private readonly claimedTouches;
+    /** Gestures="Enabled": while a claimed touch is down the page may not take its drag. */
+    private readonly preventClaimedTouch;
+    /** Called when no control handled a context-menu request; return true to suppress the browser's canvas menu. */
+    ContextMenu?: (sender: Canvas, e: ContextMenuEventArgs) => boolean | void;
+    /** DOM contextmenu (right click / long press / Menu key) -> ContextMenuEventArgs routed through the tree like a tap. */
+    private readonly onContextMenu;
+    private cursorPointer;
+    /**
+     * DrawnUi.Blazor shows `cursor: pointer` over interactive controls through its overlay elements; here the overlay
+     * is pointer-events:none, so the mouse position is tested against the accessibility snapshot (the accessible
+     * controls' rects in points, already sorted and rate-limited), each hit control answering WantsPointerCursor
+     * (itself tappable, or a tappable span of a label), and the canvas element's cursor is switched only when the
+     * answer changes. Mouse moves only, no work without a mouse and none in the frame loop.
+     */
+    private UpdateCursor;
+    /**
+     * Mouse wheel -> TouchActionResult.Wheel.
+     * Lock keeps every wheel on the canvas. Enabled shares it with the page, like DrawnUi.Blazor's
+     * TouchHandlingStyle.Manual: the page scrolls unless a control consumed this wheel. The browser needs that answer
+     * inside this handler, so the wheel is processed now instead of at the next frame (Blazor does the same, for the
+     * same reason); pending gestures are flushed first so the event order is kept.
+     */
     private readonly onWheel;
+    /**
+     * Processes one gesture immediately (after whatever is queued) and reports whether a control USED it: a consumer
+     * that marked the event Handled, or any consumer that is not a `BlockGesturesBelow` layer. A blocker returns itself
+     * for every gesture it keeps from the controls below (a shell page, a popup backdrop), which is not a use: counting
+     * it would block the page wheel over every shell app.
+     */
+    private ProcessGestureNow;
+    /**
+     * The page axes a touch pan over the canvas hands to the browser: "pan-y" when the page (or a scrolling ancestor) can
+     * scroll vertically, "pan-x" horizontally, both, or "none". Mirrors MAUI's Gestures="Enabled" inside a native scroll
+     * view, where the parent takes the pans it scrolls in.
+     */
+    private static PageScrollAxes;
+    /**
+     * Gestures="Enabled" shares touch pans with the page like MAUI's Enabled inside a native scroll view: along an axis
+     * the page can scroll, the browser takes the pan (and sends pointercancel), taps and the other axis stay on the
+     * canvas. A page that cannot scroll, and Lock, keep every touch. The browser reads touch-action when a touch starts,
+     * so it is kept current ahead of time: on attach, when the window / html / body resize, and after every touch.
+     */
+    private readonly UpdateTouchAction;
+    private pageObserver?;
     private AttachInput;
     private DetachInput;
     /** Port of DrawnUi.Blazor Canvas.OnTouchAction: per-pointer state machine producing Down / Panning / Tapped / Up. */
     OnTouchAction(args: TouchActionEventArgs): void;
     private OnGestureEvent;
     private ProcessPendingGestures;
+    /**
+     * The control that consumed the current gesture keeps it until it lets go (DrawnUi Canvas.HadInput). Without this a
+     * gesture is re-routed by the pointer position on every event, so anything the finger drags away from — a drag
+     * handle, a slider thumb, a button being held — stops receiving Panning the moment the pointer leaves its box.
+     * Single pointer, which is what the web gives us here; C# keeps a set for multi-touch.
+     */
+    private gestureOwner;
+    /** DrawnUi IsSavedGesture: the types replayed to the owner instead of being routed again. */
+    private static IsSavedGesture;
     /** Entry into the control tree, same shape as DrawnUi Canvas.ProcessGestures. */
     protected ProcessGestures(root: SkiaControl, args: SkiaGesturesParameters): SkiaControl | null;
 }

package/dist/core/Canvas.js

@@ -1,7 +1,7 @@
 import { Super } from "./Super";
 import { SkiaAccessibilityManager } from "./Accessibility";
 import { Colors, SKRect } from "./Types";
-import { GestureEventProcessingInfo, SKPoint, SkiaGesturesParameters, TouchActionEventArgs, } from "./Gestures";
+import { ContextMenuEventArgs, GestureEventProcessingInfo, PointerData, SKPoint, SkiaGesturesParameters, TouchActionEventArgs, } from "./Gestures";
 /**
  * Mirrors DrawnUi Canvas (DrawnView): hosts one Content control on an HTML canvas element,
  * owns RenderingScale (devicePixelRatio), the surface, the on-demand frame loop and raw input.
@@ -21,6 +21,18 @@ export class Canvas {
     /** Frames per second over the last second of drawn frames. */
     FPS = 0;
     frameTimes = [];
+    /** DrawnView.WasRendered: a frame has been drawn on a ready surface (set after the first one completes). */
+    WasRendered = false;
+    /** DrawnView.CanRender: the surface (and its GPU context when accelerated) is ready to draw. */
+    get CanRender() { return !!this.surface && !this.disposed; }
+    /**
+     * DrawnView.WillFirstTimeDraw: raised once, right before the first frame drawn on a ready surface, with that
+     * frame's drawing context. The engine draws its first frame while it is being constructed (so the page never shows
+     * an unpainted canvas): pass it through the constructor's `init` to receive that frame.
+     */
+    WillFirstTimeDraw;
+    /** DrawnView.WasDrawn: raised after every frame has been drawn (the C# event passes no context). */
+    WasDrawn;
     /** Registry + rate-limited snapshot of accessible controls, rendered by the DOM overlay (DrawnUi AccessibilityManager). */
     AccessibilityManager = new SkiaAccessibilityManager();
     content;
@@ -42,10 +54,12 @@ export class Canvas {
     frameId = 0;
     disposed = false;
     observer;
-    constructor(Element) {
+    /** `init` runs before the first frame is drawn: the place to attach `WillFirstTimeDraw` / `WasDrawn` for that frame. */
+    constructor(Element, init) {
         this.Element = Element;
         if (!Super.CK)
             throw new Error("DrawnUi: call Super.UseDrawnUi()...BuildAsync() before creating a Canvas");
+        init?.(this);
         this.observer = new ResizeObserver(() => this.OnResized());
         this.observer.observe(Element);
         this.OnResized();
@@ -122,6 +136,9 @@ export class Canvas {
         const started = performance.now();
         this.ProcessPendingGestures();
         const executed = this.ExecuteAnimators(Math.round(started * 1_000_000));
+        const canRender = this.CanRender;
+        if (canRender && !this.WasRendered)
+            this.WillFirstTimeDraw?.(this, { Canvas: canvas, Surface: this.surface });
         canvas.clear(Super.ParseColor(this.BackgroundColor));
         const root = this.content;
         if (root) {
@@ -141,6 +158,10 @@ export class Canvas {
         this.FPS = this.frameTimes.length;
         if (executed > 0)
             this.Update(); // animators running: keep frames coming
+        // C# order: WasDrawn at the end of the frame, then the frame counts as rendered
+        this.WasDrawn?.(this);
+        if (!this.WasRendered && canRender)
+            this.WasRendered = true;
     }
     // ---- deferred disposal (DrawnUi DisposeObject: never delete Skia objects mid-frame) ----
     disposeQueue = [];
@@ -179,6 +200,50 @@ export class Canvas {
     FrameIndex = 0;
     /** On-screen surface (SkiaBackdrop snapshots it). */
     get Surface() { return this.surface; }
+    /**
+     * A picture of what is on screen right now, as PNG bytes (C# DrawnView.TakeScreenShot).
+     *
+     * The on-screen canvas cannot simply be read: an accelerated surface lives in a WebGL drawing
+     * buffer the browser clears after compositing, so both `canvas.toDataURL()` and a snapshot of
+     * the live surface come back blank. The content is therefore drawn once more into an offscreen
+     * RASTER surface, which can be read back anywhere.
+     *
+     * This is a still picture, not a frame of the loop: animators are not ticked and the frame
+     * counters do not move, so taking one never changes what the next real frame shows.
+     */
+    TakeScreenShot() {
+        const CK = Super.CK;
+        const w = this.Element.width, h = this.Element.height;
+        if (!CK || !w || !h)
+            return null;
+        const surface = CK.MakeSurface(w, h);
+        if (!surface)
+            return null;
+        try {
+            const canvas = surface.getCanvas();
+            canvas.clear(Super.ParseColor(this.BackgroundColor));
+            const root = this.content;
+            if (root) {
+                const scale = this.RenderingScale;
+                root.Measure(w, h, scale);
+                root.Arrange(new SKRect(0, 0, w, h), root.WidthRequest, root.HeightRequest, scale);
+                root.Render({ Context: { Canvas: canvas, Surface: surface }, Destination: new SKRect(0, 0, w, h), Scale: scale });
+            }
+            surface.flush();
+            const image = surface.makeImageSnapshot();
+            if (!image)
+                return null;
+            try {
+                return image.encodeToBytes();
+            }
+            finally {
+                image.delete();
+            }
+        }
+        finally {
+            surface.delete();
+        }
+    }
     Dispose() {
         this.disposed = true;
         this.Gestures = "Disabled";
@@ -216,8 +281,13 @@ export class Canvas {
                     e.type === "pointercancel" ? "Cancelled" : undefined;
         if (!type)
             return;
-        if (type === "Moved" && !this.activeTouchIds.has(e.pointerId))
-            return; // hover not ported (TouchActionResult.Pointer)
+        if (type === "Moved" && !this.activeTouchIds.has(e.pointerId)) {
+            if (e.pointerType === "mouse")
+                this.UpdateCursor(e.offsetX, e.offsetY);
+            return;
+        } // hover not ported (TouchActionResult.Pointer)
+        if ((type === "Released" || type === "Cancelled") && !this.activeTouchIds.has(e.pointerId))
+            return; // Up of a pointer that never pressed here
         // Capture so Up outside the element still arrives; throws for synthetic events (tests) — harmless.
         if (type === "Pressed") {
             try {
@@ -231,12 +301,76 @@ export class Canvas {
         args.Type = type;
         args.Scale = this.RenderingScale;
         args.Location = new SKPoint((e.clientX - rect.left) * this.RenderingScale, (e.clientY - rect.top) * this.RenderingScale);
+        // every mouse button is delivered with its PointerData (AppoMobi.Gestures): a right click is a Down / Up / Tapped
+        // with Button "Right" for games and custom controls, and a ContextMenu on top
+        const pd = new PointerData();
+        pd.Button = e.button === 0 ? "Left" : e.button === 1 ? "Middle" : e.button === 2 ? "Right" : e.button === 3 ? "XButton1" : e.button === 4 ? "XButton2" : "Extended";
+        pd.ButtonNumber = e.button === 1 ? 3 : e.button === 2 ? 2 : e.button + 1;
+        pd.DeviceType = e.pointerType === "touch" ? "Touch" : e.pointerType === "pen" ? "Pen" : "Mouse";
+        pd.PressedButtons = e.buttons;
+        args.Pointer = pd;
         this.OnTouchAction(args);
+        if (type === "Released" || type === "Cancelled") {
+            this.claimedTouches.delete(e.pointerId);
+            this.UpdateTouchAction();
+        }
     };
     preventTouch = (e) => e.preventDefault();
-    /** Mouse wheel -> TouchActionResult.Wheel (page scroll suppressed while gestures are enabled). */
+    /** Gestures="Enabled": touch / pen pointers whose Down a control used (see OnTouchAction). */
+    claimedTouches = new Set();
+    /** Gestures="Enabled": while a claimed touch is down the page may not take its drag. */
+    preventClaimedTouch = (e) => { if (this.claimedTouches.size > 0 && e.cancelable)
+        e.preventDefault(); };
+    /** Called when no control handled a context-menu request; return true to suppress the browser's canvas menu. */
+    ContextMenu;
+    /** DOM contextmenu (right click / long press / Menu key) -> ContextMenuEventArgs routed through the tree like a tap. */
+    onContextMenu = (e) => {
+        const rect = this.Element.getBoundingClientRect();
+        const scale = this.RenderingScale;
+        const x = e.clientX - rect.left, y = e.clientY - rect.top;
+        const pointerType = e.pointerType;
+        const source = pointerType === "touch" || pointerType === "pen" ? "touch" : pointerType === "mouse" || e.button === 2 ? "mouse" : "keyboard";
+        const args = new ContextMenuEventArgs(new SKPoint(x, y), new SKPoint(x * scale, y * scale), source, e);
+        let handled = this.content?.ProcessContextMenu(args.Pixels, args) ?? false;
+        if (!handled && this.ContextMenu)
+            handled = this.ContextMenu(this, args) === true;
+        if (handled)
+            e.preventDefault();
+    };
+    cursorPointer = false;
+    /**
+     * DrawnUi.Blazor shows `cursor: pointer` over interactive controls through its overlay elements; here the overlay
+     * is pointer-events:none, so the mouse position is tested against the accessibility snapshot (the accessible
+     * controls' rects in points, already sorted and rate-limited), each hit control answering WantsPointerCursor
+     * (itself tappable, or a tappable span of a label), and the canvas element's cursor is switched only when the
+     * answer changes. Mouse moves only, no work without a mouse and none in the frame loop.
+     */
+    UpdateCursor(x, y) {
+        let hit = false;
+        const scale = this.RenderingScale;
+        for (const n of this.AccessibilityManager.Snapshot) {
+            if (x < n.Rect.Left || x >= n.Rect.Right || y < n.Rect.Top || y >= n.Rect.Bottom)
+                continue;
+            // the control decides (whole control, or a tappable span of a label); point in pixels relative to the control's
+            // origin, taken from the snapshot rect (already carries the scroll / cache offset; a rotated control gets its bbox)
+            if (n.Source.WantsPointerCursor((x - n.Rect.Left) * scale, (y - n.Rect.Top) * scale)) {
+                hit = true;
+                break;
+            }
+        }
+        if (hit !== this.cursorPointer) {
+            this.cursorPointer = hit;
+            this.Element.style.cursor = hit ? "pointer" : "";
+        }
+    }
+    /**
+     * Mouse wheel -> TouchActionResult.Wheel.
+     * Lock keeps every wheel on the canvas. Enabled shares it with the page, like DrawnUi.Blazor's
+     * TouchHandlingStyle.Manual: the page scrolls unless a control consumed this wheel. The browser needs that answer
+     * inside this handler, so the wheel is processed now instead of at the next frame (Blazor does the same, for the
+     * same reason); pending gestures are flushed first so the event order is kept.
+     */
     onWheel = (e) => {
-        e.preventDefault();
         const rect = this.Element.getBoundingClientRect();
         const args = new TouchActionEventArgs();
         args.Id = -1;
@@ -245,26 +379,101 @@ export class Canvas {
         args.Location = new SKPoint((e.clientX - rect.left) * this.RenderingScale, (e.clientY - rect.top) * this.RenderingScale);
         args.StartingLocation = args.Location;
         args.Wheel = { Delta: e.deltaY !== 0 ? e.deltaY : e.deltaX };
-        this.OnGestureEvent(args, "Wheel");
+        if (this.gestures === "Lock") {
+            e.preventDefault();
+            this.OnGestureEvent(args, "Wheel");
+            return;
+        }
+        if (this.ProcessGestureNow(args, "Wheel"))
+            e.preventDefault();
+    };
+    /**
+     * Processes one gesture immediately (after whatever is queued) and reports whether a control USED it: a consumer
+     * that marked the event Handled, or any consumer that is not a `BlockGesturesBelow` layer. A blocker returns itself
+     * for every gesture it keeps from the controls below (a shell page, a popup backdrop), which is not a use: counting
+     * it would block the page wheel over every shell app.
+     */
+    ProcessGestureNow(args, result) {
+        this.ProcessPendingGestures();
+        const root = this.content;
+        const consumed = root ? this.ProcessGestures(root, SkiaGesturesParameters.Create(result, args)) : null;
+        this.Update();
+        return !!consumed && (args.Handled || !consumed.BlockGesturesBelow);
+    }
+    /**
+     * The page axes a touch pan over the canvas hands to the browser: "pan-y" when the page (or a scrolling ancestor) can
+     * scroll vertically, "pan-x" horizontally, both, or "none". Mirrors MAUI's Gestures="Enabled" inside a native scroll
+     * view, where the parent takes the pans it scrolls in.
+     */
+    static PageScrollAxes(el) {
+        const scrolls = (v) => v === "auto" || v === "scroll" || v === "overlay";
+        const clips = (v) => v === "hidden" || v === "clip";
+        let x = false, y = false;
+        for (let n = el.parentElement; n && n !== document.body && n !== document.documentElement; n = n.parentElement) {
+            const st = getComputedStyle(n);
+            if (!y && scrolls(st.overflowY) && n.scrollHeight > n.clientHeight + 1)
+                y = true;
+            if (!x && scrolls(st.overflowX) && n.scrollWidth > n.clientWidth + 1)
+                x = true;
+        }
+        // the viewport scrolls unless html or body clips it
+        const root = document.scrollingElement ?? document.documentElement;
+        const hs = getComputedStyle(document.documentElement), bs = getComputedStyle(document.body);
+        if (!y && !clips(hs.overflowY) && !clips(bs.overflowY) && root.scrollHeight > root.clientHeight + 1)
+            y = true;
+        if (!x && !clips(hs.overflowX) && !clips(bs.overflowX) && root.scrollWidth > root.clientWidth + 1)
+            x = true;
+        // a canvas filling a framed document (a widget in an iframe): the page that scrolls is the parent, which a
+        // cross-origin frame cannot inspect, so assume it scrolls vertically; horizontal pans and taps stay on the canvas
+        if (!y && window.self !== window.top)
+            y = true;
+        return x && y ? "pan-x pan-y" : y ? "pan-y" : x ? "pan-x" : "none";
+    }
+    /**
+     * Gestures="Enabled" shares touch pans with the page like MAUI's Enabled inside a native scroll view: along an axis
+     * the page can scroll, the browser takes the pan (and sends pointercancel), taps and the other axis stay on the
+     * canvas. A page that cannot scroll, and Lock, keep every touch. The browser reads touch-action when a touch starts,
+     * so it is kept current ahead of time: on attach, when the window / html / body resize, and after every touch.
+     */
+    UpdateTouchAction = () => {
+        if (this.gestures === "Disabled")
+            return;
+        const pan = this.gestures === "Enabled" ? Canvas.PageScrollAxes(this.Element) : "none";
+        if (this.Element.style.touchAction !== pan)
+            this.Element.style.touchAction = pan;
     };
+    pageObserver;
     AttachInput() {
         const el = this.Element;
-        el.style.touchAction = "none";
+        this.UpdateTouchAction();
+        window.addEventListener("resize", this.UpdateTouchAction);
+        this.pageObserver = new ResizeObserver(this.UpdateTouchAction);
+        this.pageObserver.observe(document.documentElement);
+        this.pageObserver.observe(document.body);
         el.style.userSelect = "none";
         for (const t of ["pointerdown", "pointermove", "pointerup", "pointercancel"])
             el.addEventListener(t, this.onPointer);
+        el.addEventListener("contextmenu", this.onContextMenu);
         el.addEventListener("wheel", this.onWheel, { passive: false });
         if (this.gestures === "Lock")
             el.addEventListener("touchmove", this.preventTouch, { passive: false });
+        else if (this.gestures === "Enabled")
+            el.addEventListener("touchmove", this.preventClaimedTouch, { passive: false });
     }
     DetachInput() {
         const el = this.Element;
         el.style.touchAction = "";
+        window.removeEventListener("resize", this.UpdateTouchAction);
+        this.pageObserver?.disconnect();
+        this.pageObserver = undefined;
         el.style.userSelect = "";
         for (const t of ["pointerdown", "pointermove", "pointerup", "pointercancel"])
             el.removeEventListener(t, this.onPointer);
+        el.removeEventListener("contextmenu", this.onContextMenu);
         el.removeEventListener("wheel", this.onWheel);
         el.removeEventListener("touchmove", this.preventTouch);
+        el.removeEventListener("touchmove", this.preventClaimedTouch);
+        this.claimedTouches.clear();
         this.activeTouchIds.clear();
         this.pointerDownArgs.clear();
         this.previousTouchArgs.clear();
@@ -281,6 +490,16 @@ export class Canvas {
             args.IsInContact = true;
             this.pointerDownArgs.set(id, args);
             this.previousTouchArgs.set(id, args);
+            // Gestures="Enabled", touch or pen: page scrolling was left to touch-action alone, and iOS Safari still takes an
+            // off-axis drag from the page axis (pointercancel mid-gesture, w3c/pointerevents#303). So the Down is processed
+            // now, like the wheel (queued gestures first, same "used" rule): when a control used it the touch is claimed and
+            // its touchmoves are default-prevented until it ends. It is not queued as well, so it is processed exactly once and
+            // the Panning / Up that follow keep their order. An unclaimed touch shares the page as before.
+            if (this.gestures === "Enabled" && args.Pointer && args.Pointer.DeviceType !== "Mouse") {
+                if (this.ProcessGestureNow(args, "Down"))
+                    this.claimedTouches.add(id);
+                return;
+            }
             this.OnGestureEvent(args, "Down");
             return;
         }
@@ -321,8 +540,35 @@ export class Canvas {
         for (const args of batch)
             this.ProcessGestures(root, args);
     }
+    /**
+     * The control that consumed the current gesture keeps it until it lets go (DrawnUi Canvas.HadInput). Without this a
+     * gesture is re-routed by the pointer position on every event, so anything the finger drags away from — a drag
+     * handle, a slider thumb, a button being held — stops receiving Panning the moment the pointer leaves its box.
+     * Single pointer, which is what the web gives us here; C# keeps a set for multi-touch.
+     */
+    gestureOwner = null;
+    /** DrawnUi IsSavedGesture: the types replayed to the owner instead of being routed again. */
+    static IsSavedGesture(type) {
+        return type === "Panning" || type === "Wheel" || type === "Up";
+    }
     /** Entry into the control tree, same shape as DrawnUi Canvas.ProcessGestures. */
     ProcessGestures(root, args) {
-        return root.ProcessGestures(args, new GestureEventProcessingInfo(args.Event.Location, SKPoint.Empty, SKPoint.Empty, null));
+        const info = () => new GestureEventProcessingInfo(args.Event.Location, SKPoint.Empty, SKPoint.Empty, null);
+        if (args.Type === "Down")
+            this.gestureOwner = null;
+        else if (this.gestureOwner && Canvas.IsSavedGesture(args.Type)) {
+            const owner = this.gestureOwner;
+            const alive = !!owner.Superview && owner.IsVisible && !owner.InputTransparent;
+            const consumed = alive ? owner.OnSkiaGestureEvent(args, info()) : null;
+            if (consumed) {
+                // it still wants the gesture: nobody else sees this one (C# skips the tree pass for a saved gesture)
+                this.gestureOwner = args.Type === "Up" ? null : consumed;
+                return consumed;
+            }
+            this.gestureOwner = null; // it let go (a button whose press turned into a pan): route normally again
+        }
+        const consumed = root.ProcessGestures(args, info());
+        this.gestureOwner = consumed && args.Type !== "Up" ? consumed : null;
+        return consumed;
     }
 }

package/dist/core/Gestures.d.ts

@@ -9,7 +9,7 @@ export declare class SKPoint {
 }
 /** Raw platform action (subset of TouchActionType). */
 export type TouchActionType = "Pressed" | "Moved" | "Released" | "Cancelled" | "Wheel" | "Pointer";
-/** Recognized gesture (TouchActionResult). LongPressing/Wheel/Pointer/Touch declared for parity, not produced yet. */
+/** Recognized gesture (TouchActionResult). LongPressing/Pointer/Touch declared for parity, not produced yet. */
 export type TouchActionResult = "Touch" | "Down" | "Up" | "Tapped" | "LongPressing" | "Panning" | "Wheel" | "Pointer";
 export type GesturesMode = "Disabled" | "Enabled" | "Lock";
 export type LockTouch = "Disabled" | "Enabled" | "PassNone" | "PassTap" | "PassTapAndLongPress";
@@ -21,9 +21,23 @@ export declare class DistanceInfo {
     Total: SKPoint;
     Velocity: SKPoint;
 }
+/** AppoMobi.Gestures MouseButton: which button pressed / released (DOM button 0..4). */
+export type MouseButton = "Left" | "Middle" | "Right" | "XButton1" | "XButton2" | "Extended";
+export type PointerDeviceType = "Mouse" | "Touch" | "Pen";
+/** AppoMobi.Gestures PointerData: the device and button behind a Down / Up / Tapped (every button is delivered). */
+export declare class PointerData {
+    Button: MouseButton;
+    /** 1 = Left, 2 = Right, 3 = Middle, 4+ = extended, like AppoMobi.Gestures. */
+    ButtonNumber: number;
+    DeviceType: PointerDeviceType;
+    /** DOM `buttons` bitmask of the buttons held (1 left, 2 right, 4 middle, 8 back, 16 forward). */
+    PressedButtons: number;
+}
 /** AppoMobi.Gestures TouchActionEventArgs. */
 export declare class TouchActionEventArgs {
     Id: number;
+    /** Device and button of this event (mouse, pen, touch); undefined for wheel. */
+    Pointer?: PointerData;
     Type: TouchActionType;
     /** Pixels. */
     Location: SKPoint;
@@ -39,6 +53,11 @@ export declare class TouchActionEventArgs {
     Wheel: {
         Delta: number;
     };
+    /**
+     * AppoMobi TouchActionEventArgs.Handled: set by a control that actually used the event. The canvas prevents the
+     * browser default (the page scrolling under the wheel) only for a Handled event in `Gestures="Enabled"`.
+     */
+    Handled: boolean;
     /** Same as the .NET helper: derives Start/End/Delta/Total from the previous event of the same pointer. */
     static FillDistanceInfo(current: TouchActionEventArgs, previous: TouchActionEventArgs | undefined): void;
 }
@@ -66,6 +85,33 @@ export declare class SkiaGesturesInfo {
     constructor(Args: SkiaGesturesParameters, Info: GestureEventProcessingInfo);
 }
 /** DrawnUi ControlTappedEventArgs. */
+/** Where a context-menu request came from: right click, long press (Android fires contextmenu), or the keyboard Menu key. */
+export type ContextMenuSource = "mouse" | "touch" | "keyboard";
+/**
+ * Arguments of SkiaControl.ContextMenu / Canvas.ContextMenu: a browser `contextmenu` request on the canvas (right
+ * click, long press on touch, the Menu key). Handlers return true to take it: the browser's own menu ("Save image")
+ * is then suppressed; otherwise it shows as usual.
+ */
+export declare class ContextMenuEventArgs {
+    /** Point on the canvas, in points (CSS px). */
+    Location: SKPoint;
+    /** Same point in pixels (canvas space). */
+    Pixels: SKPoint;
+    Source: ContextMenuSource;
+    /** The DOM event: modifiers, target, preventDefault if you need it yourself. */
+    Native: MouseEvent;
+    /** Deepest control under the point that had a ContextMenu handler (set while routing). */
+    Control?: SkiaControl;
+    /** Point inside Control, in pixels relative to its DrawingRect origin (set while routing). */
+    Local: SKPoint;
+    constructor(
+    /** Point on the canvas, in points (CSS px). */
+    Location: SKPoint, 
+    /** Same point in pixels (canvas space). */
+    Pixels: SKPoint, Source: ContextMenuSource, 
+    /** The DOM event: modifiers, target, preventDefault if you need it yourself. */
+    Native: MouseEvent);
+}
 export declare class ControlTappedEventArgs {
     Control: SkiaControl;
     Parameters: SkiaGesturesParameters;

package/dist/core/Gestures.js

@@ -18,9 +18,20 @@ export class DistanceInfo {
     Total = SKPoint.Empty;
     Velocity = SKPoint.Empty;
 }
+/** AppoMobi.Gestures PointerData: the device and button behind a Down / Up / Tapped (every button is delivered). */
+export class PointerData {
+    Button = "Left";
+    /** 1 = Left, 2 = Right, 3 = Middle, 4+ = extended, like AppoMobi.Gestures. */
+    ButtonNumber = 1;
+    DeviceType = "Mouse";
+    /** DOM `buttons` bitmask of the buttons held (1 left, 2 right, 4 middle, 8 back, 16 forward). */
+    PressedButtons = 0;
+}
 /** AppoMobi.Gestures TouchActionEventArgs. */
 export class TouchActionEventArgs {
     Id = 0;
+    /** Device and button of this event (mouse, pen, touch); undefined for wheel. */
+    Pointer;
     Type = "Pressed";
     /** Pixels. */
     Location = SKPoint.Empty;
@@ -34,6 +45,11 @@ export class TouchActionEventArgs {
     DeltaTimeMs = 0;
     /** Mouse wheel: Delta > 0 = wheel down (browser deltaY sign). */
     Wheel = { Delta: 0 };
+    /**
+     * AppoMobi TouchActionEventArgs.Handled: set by a control that actually used the event. The canvas prevents the
+     * browser default (the page scrolling under the wheel) only for a Handled event in `Gestures="Enabled"`.
+     */
+    Handled = false;
     /** Same as the .NET helper: derives Start/End/Delta/Total from the previous event of the same pointer. */
     static FillDistanceInfo(current, previous) {
         if (!previous) {
@@ -91,7 +107,33 @@ export class SkiaGesturesInfo {
         this.Info = Info;
     }
 }
-/** DrawnUi ControlTappedEventArgs. */
+/**
+ * Arguments of SkiaControl.ContextMenu / Canvas.ContextMenu: a browser `contextmenu` request on the canvas (right
+ * click, long press on touch, the Menu key). Handlers return true to take it: the browser's own menu ("Save image")
+ * is then suppressed; otherwise it shows as usual.
+ */
+export class ContextMenuEventArgs {
+    Location;
+    Pixels;
+    Source;
+    Native;
+    /** Deepest control under the point that had a ContextMenu handler (set while routing). */
+    Control;
+    /** Point inside Control, in pixels relative to its DrawingRect origin (set while routing). */
+    Local = SKPoint.Empty;
+    constructor(
+    /** Point on the canvas, in points (CSS px). */
+    Location, 
+    /** Same point in pixels (canvas space). */
+    Pixels, Source, 
+    /** The DOM event: modifiers, target, preventDefault if you need it yourself. */
+    Native) {
+        this.Location = Location;
+        this.Pixels = Pixels;
+        this.Source = Source;
+        this.Native = Native;
+    }
+}
 export class ControlTappedEventArgs {
     Control;
     Parameters;