@pie-players/pie-players-shared 0.3.73 → 0.3.74

package/dist/ui/content-styles.js

@@ -23,9 +23,8 @@
 const MARKER_ATTRIBUTE = "data-pie-content-styles";
 /**
  * Declared by `components.css` itself, so it is observable no matter how the
- * stylesheet arrived — our injection or a host import. Diagnostics only: it
- * tells a host that opted out and then shipped nothing, and it spots a host copy
- * sitting alongside ours.
+ * stylesheet arrived — our injection or a host import. A host copy carrying it
+ * makes the player stand down, and an opted-out host with no copy is warned.
  */
 const SENTINEL_PROPERTY = "--pie-content-styles";
 // Svelte's dev-mode custom-element reset expands `all: unset` into individual
@@ -100,7 +99,16 @@ export function contentStylesPresent() {
     return countContentStyleSheets({ excludeInstalled: false }) > 0;
 }
 /**
- * Installs `cssText` as a document-level stylesheet, once per document.
+ * Installs `cssText` as a document-level stylesheet, once per document, unless
+ * the host already supplies one.
+ *
+ * A host copy is recognised by the sentinel wherever it sits, including one
+ * confined to the host's player subtree with `@scope`. Such a host scoped its
+ * copy because the stylesheet's bare element selectors would otherwise reach
+ * its own UI, so a global copy from the player would reintroduce exactly that.
+ * A host copy can also land after this runs — a lazily injected `<style>`, a
+ * `<link>` still loading — so the installed copy keeps watching and removes
+ * itself when one appears, as it does when the host sets the opt-out late.
  *
  * The stylesheet is **prepended** to `<head>` and deliberately left out of a
  * cascade layer. Prepending reproduces the placement hosts were told to use by
@@ -126,14 +134,58 @@ export function installContentStyles(cssText, source) {
         // the same stylesheet. Duplicating it would be harmless but pointless.
         return "already-installed";
     }
+    if (countHostContentStyleSheets() > 0)
+        return "host-supplied";
     if (!cssText)
         return "no-document";
     const style = document.createElement("style");
     style.setAttribute(MARKER_ATTRIBUTE, source);
     style.textContent = cssText;
     document.head.prepend(style);
+    watchForHostOwnership(style);
     return "installed";
 }
+let stopWatchingHostOwnership = null;
+const watchForHostOwnership = (installed) => {
+    stopWatchingHostOwnership?.();
+    if (typeof MutationObserver === "undefined")
+        return;
+    const stop = () => {
+        observer.disconnect();
+        document.removeEventListener("load", onLoad, true);
+        if (stopWatchingHostOwnership === stop)
+            stopWatchingHostOwnership = null;
+    };
+    const reconcile = () => {
+        if (!installed.isConnected) {
+            stop();
+            return;
+        }
+        if (contentStylesOptedOut() || countHostContentStyleSheets() > 0) {
+            installed.remove();
+            stop();
+        }
+    };
+    const observer = new MutationObserver((records) => {
+        const relevant = records.some((record) => record.type === "attributes" ||
+            Array.from(record.addedNodes).some((node) => node.nodeName === "STYLE" || node.nodeName === "LINK"));
+        if (relevant)
+            reconcile();
+    });
+    // `load` does not bubble, so a capturing listener is what sees a host
+    // `<link>` finish, including one already in flight when this runs.
+    const onLoad = (event) => {
+        if (event.target?.nodeName === "LINK")
+            reconcile();
+    };
+    observer.observe(document.head, { childList: true });
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: [OPT_OUT_ATTRIBUTE],
+    });
+    document.addEventListener("load", onLoad, true);
+    stopWatchingHostOwnership = stop;
+};
 /**
  * Counts content stylesheets in the document, detected by the sentinel property
  * rather than by URL, so a copy arriving as a `<link>`, a bundler-injected
@@ -141,8 +193,8 @@ export function installContentStyles(cssText, source) {
  * count to copies the host loaded itself.
  *
  * Cross-origin sheets throw on `cssRules` access and are skipped; a host copy
- * served from another origin therefore reads as absent. That only costs a
- * diagnostic, never correctness.
+ * served from another origin therefore reads as absent, and the player installs
+ * its own copy alongside it. Such a host sets the opt-out attribute instead.
  */
 const countContentStyleSheets = ({ excludeInstalled, }) => {
     // Walks the owning elements rather than document.styleSheets: the marker
@@ -176,18 +228,10 @@ const countHostContentStyleSheets = () => countContentStyleSheets({ excludeInsta
 let auditWarningIssued = false;
 const pendingChecks = [];
 /**
- * Reports, once per page, the two ways content styling can go wrong. Neither is
- * detectable synchronously — a host copy may still be in flight as an async
- * `<link>` — so the check is deferred.
- *
- * - **Missing**: the host opted out and then loaded nothing, so authored content
- *   renders unstyled. This is the failure the old host-import contract produced
- *   silently.
- * - **Duplicated**: the host still imports `components.css` itself *and* the
- *   player installed a copy. Rendering is correct while the two agree, but the
- *   host's copy loads later and therefore wins ties at equal specificity — so a
- *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
- *   player's newer rules. Harmless today, a confusing override tomorrow.
+ * Reports, once per page, a host that opted out and then loaded no content
+ * stylesheet, so authored content renders unstyled — the failure the old
+ * host-import contract produced silently. Not detectable synchronously — a host
+ * copy may still be in flight as an async `<link>` — so the check is deferred.
  */
 export function auditContentStyles(source) {
     if (!isBrowser() || auditWarningIssued)
@@ -195,9 +239,7 @@ export function auditContentStyles(source) {
     const check = () => {
         if (auditWarningIssued)
             return;
-        if (contentStylesOptedOut()) {
-            if (contentStylesPresent())
-                return;
+        if (contentStylesOptedOut() && !contentStylesPresent()) {
             auditWarningIssued = true;
             console.warn(`[${source}] No PIE content stylesheet found. This document sets ` +
                 `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}", so ${source} did not install ` +
@@ -206,19 +248,6 @@ export function auditContentStyles(source) {
                 `families, answer-eliminator styles) will render unstyled. Either ` +
                 `import "@pie-players/pie-theme/components.css" in the host app, or ` +
                 `drop the ${OPT_OUT_ATTRIBUTE} attribute to let the player install it.`);
-            return;
-        }
-        if (countHostContentStyleSheets() > 0) {
-            auditWarningIssued = true;
-            console.warn(`[${source}] The PIE content stylesheet is loaded twice: ${source} ` +
-                `installs it, and this host also imports ` +
-                `"@pie-players/pie-theme/components.css". Rendering is unaffected ` +
-                `while both copies match, but the host copy loads later and wins ` +
-                `ties at equal specificity, so a copy pinned to an older ` +
-                `@pie-players/pie-theme will silently override newer player styles. ` +
-                `Remove the host import, or set ` +
-                `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}" on <html> to own the ` +
-                `stylesheet deliberately.`);
         }
     };
     // A host stylesheet can land well after the module graph evaluates, and a
@@ -240,10 +269,12 @@ export function auditContentStyles(source) {
     }
 }
 /**
- * Test-only: clears the once-per-page warning latch and cancels any pending
- * deferred check, so a timer scheduled by one test cannot warn during the next.
+ * Test-only: clears the once-per-page warning latch, cancels any pending
+ * deferred check and stops watching for a host copy, so state from one test
+ * cannot act during the next.
  */
 export function resetContentStylesWarningForTesting() {
+    stopWatchingHostOwnership?.();
     auditWarningIssued = false;
     for (const handle of pendingChecks)
         clearTimeout(handle);

package/dist/ui/overlay-containment.d.ts

@@ -36,6 +36,37 @@ export declare function resolveContainingBlockRect(element: HTMLElement | undefi
  * than clamping to an inverted range.
  */
 export declare function clampOffsetWithinBlock(offset: Point, box: Size, block: Size, gutter?: number): Point;
+/**
+ * Clamps a translate offset applied to a box centred in its containing block so
+ * that at least `visible` pixels of the box stay inside the block on each axis.
+ *
+ * For an overlay that has to overhang its block to be useful — a ruler lined up
+ * against content near a card's edge — without ever being dragged out of reach
+ * behind that edge. A box or block narrower than `visible` keeps all of the
+ * smaller extent.
+ */
+export declare function clampOffsetOverlappingBlock(offset: Point, box: Size, block: Size, visible: number): Point;
+/** The axis-aligned extent of a `size` box turned by `degrees` about its centre. */
+export declare function rotatedExtent(size: Size, degrees: number): Size;
+/**
+ * How far a `size` box's centre moves when the box turns by `degrees` about
+ * `origin`, given in the box's own coordinates from its top-left corner.
+ *
+ * Zero for a box turned about its centre. An overlay turned about another
+ * point adds this to its translate offset to get the offset of its rotated
+ * extent's centre, which is what the centred clamps above bound.
+ */
+export declare function rotationCentreShift(size: Size, origin: Point, degrees: number): Point;
+/**
+ * Where to centre a control strip docked past the bottom edge of a `box`
+ * turned by `degrees`, in the box's own coordinates from its top-left corner.
+ *
+ * The strip is drawn counter-rotated so it stays level on screen. Its reach
+ * along the box's downward normal is its projection onto that normal, which
+ * grows from its height at no turn to its width at a quarter turn, so a strip
+ * placed that far out clears the box at any rotation.
+ */
+export declare function uprightDockCentre(box: Size, strip: Size, degrees: number, gap: number): Point;
 /**
  * Clamps an absolute centre point, in containing-block coordinates, so the box
  * it positions stays inside that block.

package/dist/ui/overlay-containment.js

@@ -49,6 +49,69 @@ export function clampOffsetWithinBlock(offset, box, block, gutter = DEFAULT_CONT
         y: clampAxis(offset.y, box.height, block.height),
     };
 }
+/**
+ * Clamps a translate offset applied to a box centred in its containing block so
+ * that at least `visible` pixels of the box stay inside the block on each axis.
+ *
+ * For an overlay that has to overhang its block to be useful — a ruler lined up
+ * against content near a card's edge — without ever being dragged out of reach
+ * behind that edge. A box or block narrower than `visible` keeps all of the
+ * smaller extent.
+ */
+export function clampOffsetOverlappingBlock(offset, box, block, visible) {
+    const clampAxis = (value, boxExtent, blockExtent) => {
+        const keep = Math.min(visible, boxExtent, blockExtent);
+        const travel = blockExtent / 2 + boxExtent / 2 - keep;
+        return Math.max(-travel, Math.min(travel, value));
+    };
+    return {
+        x: clampAxis(offset.x, box.width, block.width),
+        y: clampAxis(offset.y, box.height, block.height),
+    };
+}
+/** The axis-aligned extent of a `size` box turned by `degrees` about its centre. */
+export function rotatedExtent(size, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    const cos = Math.abs(Math.cos(radians));
+    const sin = Math.abs(Math.sin(radians));
+    return {
+        width: size.width * cos + size.height * sin,
+        height: size.width * sin + size.height * cos,
+    };
+}
+/**
+ * How far a `size` box's centre moves when the box turns by `degrees` about
+ * `origin`, given in the box's own coordinates from its top-left corner.
+ *
+ * Zero for a box turned about its centre. An overlay turned about another
+ * point adds this to its translate offset to get the offset of its rotated
+ * extent's centre, which is what the centred clamps above bound.
+ */
+export function rotationCentreShift(size, origin, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    const dx = size.width / 2 - origin.x;
+    const dy = size.height / 2 - origin.y;
+    return {
+        x: dx * cos - dy * sin - dx,
+        y: dx * sin + dy * cos - dy,
+    };
+}
+/**
+ * Where to centre a control strip docked past the bottom edge of a `box`
+ * turned by `degrees`, in the box's own coordinates from its top-left corner.
+ *
+ * The strip is drawn counter-rotated so it stays level on screen. Its reach
+ * along the box's downward normal is its projection onto that normal, which
+ * grows from its height at no turn to its width at a quarter turn, so a strip
+ * placed that far out clears the box at any rotation.
+ */
+export function uprightDockCentre(box, strip, degrees, gap) {
+    const radians = (degrees * Math.PI) / 180;
+    const reach = strip.width * Math.abs(Math.sin(radians)) + strip.height * Math.abs(Math.cos(radians));
+    return { x: box.width / 2, y: box.height + gap + reach / 2 };
+}
 /**
  * Clamps an absolute centre point, in containing-block coordinates, so the box
  * it positions stays inside that block.

package/dist/ui/overlay-placement.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Placement of a tool overlay the learner moves and turns: the ruler and the
+ * protractor. One controller holds where the tool sits and is the only writer of
+ * its `style.transform`, so a drag, an arrow key and a tap control always agree
+ * about where the tool is.
+ */
+import { type Point, type Size } from "./overlay-containment.js";
+/** An offset from the tool's centred position, and its turn about its pivot. */
+export interface OverlayPlacement {
+    x: number;
+    y: number;
+    rotation: number;
+}
+/** Pixels an arrow key or move button shifts the tool. */
+export declare const OVERLAY_PLACEMENT_MOVE_STEP = 10;
+/** Degrees Shift+arrow turns the tool. */
+export declare const OVERLAY_PLACEMENT_ROTATE_STEP = 5;
+/** Degrees Page Up/Down turns the tool. */
+export declare const OVERLAY_PLACEMENT_FINE_ROTATE_STEP = 1;
+/** Each move, with its tap control's glyph and label and its announcement. */
+export declare const OVERLAY_PLACEMENT_NUDGES: {
+    readonly left: {
+        readonly dx: -1;
+        readonly dy: 0;
+        readonly glyph: "←";
+        readonly labelKey: "toolkit.window.moveLeftA11y";
+        readonly announceKey: "toolkit.announce.movedLeft";
+    };
+    readonly up: {
+        readonly dx: 0;
+        readonly dy: -1;
+        readonly glyph: "↑";
+        readonly labelKey: "toolkit.window.moveUpA11y";
+        readonly announceKey: "toolkit.announce.movedUp";
+    };
+    readonly down: {
+        readonly dx: 0;
+        readonly dy: 1;
+        readonly glyph: "↓";
+        readonly labelKey: "toolkit.window.moveDownA11y";
+        readonly announceKey: "toolkit.announce.movedDown";
+    };
+    readonly right: {
+        readonly dx: 1;
+        readonly dy: 0;
+        readonly glyph: "→";
+        readonly labelKey: "toolkit.window.moveRightA11y";
+        readonly announceKey: "toolkit.announce.movedRight";
+    };
+};
+export type OverlayPlacementNudge = keyof typeof OVERLAY_PLACEMENT_NUDGES;
+/** The interface-catalog keys a move or turn is announced with. */
+export type OverlayPlacementAnnouncement = (typeof OVERLAY_PLACEMENT_NUDGES)[OverlayPlacementNudge]["announceKey"] | "toolkit.announce.rotatedTo";
+/** The tap controls' rotations, the keyboard's two steps each way. */
+export declare const OVERLAY_PLACEMENT_ROTATIONS: readonly [number, number, 1, 5];
+export interface OverlayPlacementOptions {
+    /** The tool's positioned element, which receives the transform. */
+    getElement: () => HTMLElement | undefined;
+    /** The tap controls, docked level past the tool's bottom edge. */
+    getControls: () => HTMLElement | undefined;
+    /**
+     * The point the tool turns about, from its top-left corner at no turn.
+     * Defaults to its centre, and must match the stylesheet's `transform-origin`.
+     */
+    pivot?: (size: Size) => Point;
+    /**
+     * That pivot on screen when a pointer rotation starts, or `undefined` to
+     * decline it. Defaults to the centre of the tool's bounding box, which a turn
+     * about the centre leaves in place.
+     */
+    getScreenPivot?: () => Point | undefined;
+    /** Raises the tool above its peers when a gesture starts or it is shown. */
+    bringToFront?: (element: HTMLElement) => void;
+    /** Speaks a move or turn; the tool resolves the key in its interface catalog. */
+    announce: (key: OverlayPlacementAnnouncement, params: Record<string, number>) => void;
+}
+export interface OverlayPlacementController {
+    readonly placement: OverlayPlacement;
+    /**
+     * Writes `next` to `style.transform`, first keeping part of the turned tool
+     * inside the box it is positioned against. The bound lets the tool overhang:
+     * an item card is barely wider than a ruler, and full containment would pin
+     * its zero mark to the card's edge. The card clips what overhangs, and 100px
+     * stays in view to grab it back.
+     */
+    apply: (next: OverlayPlacement) => void;
+    /** Raises the tool and re-applies its placement, as a fresh reveal does. */
+    show: () => void;
+    /** Ends any gesture and returns the tool to its centred, upright position. */
+    reset: () => void;
+    /** Starts a drag from a press on the tool. */
+    startDrag: (event: PointerEvent) => void;
+    /** Starts a turn from a press on `handle`, which must not also start a drag. */
+    startRotate: (event: PointerEvent, handle: HTMLElement) => void;
+    /** Moves the tool one step, as an arrow key or a move button does. */
+    nudge: (direction: OverlayPlacementNudge) => void;
+    /** Turns the tool by `degrees`, clockwise when positive, to a whole degree. */
+    rotateBy: (degrees: number) => void;
+    /**
+     * Arrows move, Shift+arrows turn 5°, Page Up/Down turn 1°. Returns whether
+     * it handled the key, having prevented its default.
+     */
+    handleKeyDown: (event: KeyboardEvent) => boolean;
+    /**
+     * Re-applies the placement on window resize, which can leave the tool outside
+     * its shrunken containing block. Returns a cleanup that also ends any gesture.
+     */
+    connect: () => () => void;
+}
+export declare function createOverlayPlacement(options: OverlayPlacementOptions): OverlayPlacementController;

package/dist/ui/overlay-placement.js

@@ -0,0 +1,222 @@
+/**
+ * Placement of a tool overlay the learner moves and turns: the ruler and the
+ * protractor. One controller holds where the tool sits and is the only writer of
+ * its `style.transform`, so a drag, an arrow key and a tap control always agree
+ * about where the tool is.
+ */
+import { clampOffsetOverlappingBlock, resolveContainingBlockRect, rotatedExtent, rotationCentreShift, uprightDockCentre, } from "./overlay-containment.js";
+import { createPointerDragController } from "./pointer-drag.js";
+import { createPointerGesture } from "./pointer-gesture.js";
+import { createPointerRotateController } from "./pointer-rotate.js";
+/** Pixels an arrow key or move button shifts the tool. */
+export const OVERLAY_PLACEMENT_MOVE_STEP = 10;
+/** Degrees Shift+arrow turns the tool. */
+export const OVERLAY_PLACEMENT_ROTATE_STEP = 5;
+/** Degrees Page Up/Down turns the tool. */
+export const OVERLAY_PLACEMENT_FINE_ROTATE_STEP = 1;
+/** Each move, with its tap control's glyph and label and its announcement. */
+export const OVERLAY_PLACEMENT_NUDGES = {
+    left: {
+        dx: -1,
+        dy: 0,
+        glyph: "←",
+        labelKey: "toolkit.window.moveLeftA11y",
+        announceKey: "toolkit.announce.movedLeft",
+    },
+    up: {
+        dx: 0,
+        dy: -1,
+        glyph: "↑",
+        labelKey: "toolkit.window.moveUpA11y",
+        announceKey: "toolkit.announce.movedUp",
+    },
+    down: {
+        dx: 0,
+        dy: 1,
+        glyph: "↓",
+        labelKey: "toolkit.window.moveDownA11y",
+        announceKey: "toolkit.announce.movedDown",
+    },
+    right: {
+        dx: 1,
+        dy: 0,
+        glyph: "→",
+        labelKey: "toolkit.window.moveRightA11y",
+        announceKey: "toolkit.announce.movedRight",
+    },
+};
+/** The tap controls' rotations, the keyboard's two steps each way. */
+export const OVERLAY_PLACEMENT_ROTATIONS = [
+    -OVERLAY_PLACEMENT_ROTATE_STEP,
+    -OVERLAY_PLACEMENT_FINE_ROTATE_STEP,
+    OVERLAY_PLACEMENT_FINE_ROTATE_STEP,
+    OVERLAY_PLACEMENT_ROTATE_STEP,
+];
+const ARROW_KEYS = {
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    ArrowRight: "right",
+};
+/** Pixels of the tool kept inside its containing block on each axis. */
+const MIN_VISIBLE = 100;
+/** Space between the tool's bottom edge and its tap controls. */
+const CONTROLS_GAP = 8;
+export function createOverlayPlacement(options) {
+    let placement = { x: 0, y: 0, rotation: 0 };
+    const sizeOf = (element) => ({
+        width: element.offsetWidth,
+        height: element.offsetHeight,
+    });
+    function dockControls(element) {
+        const controls = options.getControls();
+        if (!controls)
+            return;
+        // Counter-rotated, so each arrow points the way its button moves the tool.
+        const centre = uprightDockCentre(sizeOf(element), sizeOf(controls), placement.rotation, CONTROLS_GAP);
+        controls.style.transform = `translate(${centre.x}px, ${centre.y}px) translate(-50%, -50%) rotate(${-placement.rotation}deg)`;
+    }
+    function apply(next) {
+        const element = options.getElement();
+        if (!element)
+            return;
+        const block = resolveContainingBlockRect(element);
+        const size = sizeOf(element);
+        // A tool turning off its centre has its turned extent centred off its
+        // translate offset by this shift; the clamp bounds that centre.
+        const shift = options.pivot
+            ? rotationCentreShift(size, options.pivot(size), next.rotation)
+            : { x: 0, y: 0 };
+        const centre = { x: next.x + shift.x, y: next.y + shift.y };
+        const bounded = block
+            ? clampOffsetOverlappingBlock(centre, rotatedExtent(size, next.rotation), block, MIN_VISIBLE)
+            : centre;
+        placement = {
+            x: bounded.x - shift.x,
+            y: bounded.y - shift.y,
+            rotation: next.rotation,
+        };
+        element.style.transform = `translate(-50%, -50%) translate(${placement.x}px, ${placement.y}px) rotate(${placement.rotation}deg)`;
+        dockControls(element);
+    }
+    const dragController = createPointerDragController({
+        getPosition: () => ({ x: placement.x, y: placement.y }),
+        setPosition: (next) => apply({ ...placement, ...next }),
+    });
+    const rotateController = createPointerRotateController({
+        getRotation: () => placement.rotation,
+        setRotation: (rotation) => apply({ ...placement, rotation }),
+    });
+    const gesture = createPointerGesture({
+        onMove: (event) => {
+            dragController.handlePointerMove(event);
+            rotateController.handlePointerMove(event);
+        },
+        onEnd: () => {
+            dragController.endDragging();
+            rotateController.endRotating();
+        },
+    });
+    /**
+     * Claims a press for a drag or turn. The claim's `preventDefault` suppresses
+     * the press's default focus, so focus the tool here: the arrow-key
+     * alternatives act on it.
+     */
+    function claim(event, element, target) {
+        if (!gesture.begin(event, target))
+            return false;
+        element.focus({ preventScroll: true });
+        return true;
+    }
+    const screenPivot = () => {
+        if (options.getScreenPivot)
+            return options.getScreenPivot();
+        const rect = options.getElement()?.getBoundingClientRect();
+        return (rect && { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 });
+    };
+    function nudge(direction) {
+        const { dx, dy, announceKey } = OVERLAY_PLACEMENT_NUDGES[direction];
+        apply({
+            x: placement.x + dx * OVERLAY_PLACEMENT_MOVE_STEP,
+            y: placement.y + dy * OVERLAY_PLACEMENT_MOVE_STEP,
+            rotation: placement.rotation,
+        });
+        options.announce(announceKey, {
+            position: Math.round(dx ? placement.x : placement.y),
+        });
+    }
+    function rotateBy(degrees) {
+        const rotation = (((Math.round(placement.rotation) + degrees) % 360) + 360) % 360;
+        apply({ ...placement, rotation });
+        options.announce("toolkit.announce.rotatedTo", { degrees: rotation });
+    }
+    const reapply = () => apply(placement);
+    return {
+        get placement() {
+            return placement;
+        },
+        apply,
+        show() {
+            const element = options.getElement();
+            if (!element)
+                return;
+            options.bringToFront?.(element);
+            reapply();
+        },
+        reset() {
+            gesture.release();
+            placement = { x: 0, y: 0, rotation: 0 };
+        },
+        startDrag(event) {
+            const element = options.getElement();
+            if (!element)
+                return;
+            options.bringToFront?.(element);
+            if (!claim(event, element, element))
+                return;
+            dragController.startDragging(event, element);
+        },
+        startRotate(event, handle) {
+            event.stopPropagation();
+            const element = options.getElement();
+            const pivot = screenPivot();
+            if (!element || !pivot)
+                return;
+            options.bringToFront?.(element);
+            if (!claim(event, element, handle))
+                return;
+            rotateController.startRotating(event, handle, pivot);
+        },
+        nudge,
+        rotateBy,
+        handleKeyDown(event) {
+            const direction = ARROW_KEYS[event.key];
+            if (direction && event.shiftKey) {
+                rotateBy(direction === "up" || direction === "left"
+                    ? -OVERLAY_PLACEMENT_ROTATE_STEP
+                    : OVERLAY_PLACEMENT_ROTATE_STEP);
+            }
+            else if (direction) {
+                nudge(direction);
+            }
+            else if (event.key === "PageUp") {
+                rotateBy(-OVERLAY_PLACEMENT_FINE_ROTATE_STEP);
+            }
+            else if (event.key === "PageDown") {
+                rotateBy(OVERLAY_PLACEMENT_FINE_ROTATE_STEP);
+            }
+            else {
+                return false;
+            }
+            event.preventDefault();
+            return true;
+        },
+        connect() {
+            window.addEventListener("resize", reapply);
+            return () => {
+                gesture.release();
+                window.removeEventListener("resize", reapply);
+            };
+        },
+    };
+}

package/dist/ui/pointer-gesture.d.ts

@@ -0,0 +1,32 @@
+export interface PointerGestureArgs {
+    /** Receives every move of the pointer that began the gesture. */
+    onMove: (event: PointerEvent) => void;
+    /** Called once when the gesture ends, however it ends. */
+    onEnd: () => void;
+}
+export interface PointerGesture {
+    isActive: () => boolean;
+    /**
+     * Claims a pointerdown for a gesture on `target`, returning whether it did.
+     * Declines a non-primary button, and any pointer while another gesture is
+     * active, so a second finger landing mid-drag neither moves nor pinches.
+     * The caller starts its drag or rotate controller after a claim, which
+     * takes the pointer capture this listens on.
+     */
+    begin: (event: PointerEvent, target: HTMLElement) => boolean;
+    /** Ends the active gesture, if any, and releases its pointer capture. */
+    release: () => void;
+}
+/**
+ * The lifecycle of one pointer gesture on a tool overlay: which pointer drives
+ * it, the listeners on the element that captured it, and every way it can end.
+ * `pointercancel` and `lostpointercapture` end it as well as `pointerup`,
+ * because iPadOS cancels a touch it takes over for a system gesture, and a
+ * gesture that waited for `pointerup` would stay stuck to the next touch.
+ *
+ * The claim calls `preventDefault`, which keeps a touch from scrolling or
+ * zooming the page and a mouse press from selecting text, and also suppresses
+ * the press's default focus: a caller whose keyboard alternatives act on a
+ * focused element focuses it itself.
+ */
+export declare function createPointerGesture(args: PointerGestureArgs): PointerGesture;