@cesarvenzac/closeup 0.0.0-stage → 0.1.0

package/dist/player.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Plays a script: the drawn cursor travels each curve at a hand's pace, then clicks, types or
+ * just rests, and the page is told about every move and press as if a mouse made them
+ * (`pointer.ts`). Each target is found when its move begins, on its element if that's still
+ * there, so a scene survives a layout that shifted since it was drawn.
+ */
+import type { DrawnCursor } from "./cursor.ts";
+import { type PathNode, type Point } from "./path.ts";
+import type { SyntheticPointer } from "./pointer.ts";
+import { type Script, type Target } from "./script.ts";
+/** A target found on screen, and the size of what it's on (for the pace of reaching it). */
+export type Place = Point & {
+    size: number;
+};
+export type PlayOptions = {
+    cursor: DrawnCursor;
+    pointer: SyntheticPointer;
+    /** Where a point of the page (as laid out) is drawn on screen now. */
+    toScreen: (p: Point) => Point;
+    /** How much the page is enlarged: handles are stored in page pixels. */
+    scale: number;
+    /** Each character typed, for its sound. */
+    onKey?: () => void;
+    /** Each step as it begins, for an editor's timeline. */
+    onStep?: (index: number) => void;
+    signal?: AbortSignal;
+    /** Seconds to wait where it starts before the first move. */
+    lead?: number;
+};
+/** Where `target` is on screen now: on its element if that's still in the page and drawn, else at its page point. */
+export declare function resolve(target: Target, toScreen: PlayOptions["toScreen"], scale: number): Place;
+export declare function play(script: Script, options: PlayOptions): Promise<void>;
+/**
+ * A move's curve on screen: the handles given (stored in page pixels, so enlarged by `scale`),
+ * else a gentle arc. The editor draws the same curve the player travels.
+ */
+export declare function curve(from: Point, to: Point, out: Point | undefined, into: Point | undefined, scale: number): PathNode[];
+/** About how long a script plays, as it would from here: the lead, every move at its pace, the actions, the rests, the tail. */
+export declare function estimate(script: Script, place: (target: Target) => Place, scale: number): number;

package/dist/player.js

@@ -0,0 +1,140 @@
+/**
+ * Plays a script: the drawn cursor travels each curve at a hand's pace, then clicks, types or
+ * just rests, and the page is told about every move and press as if a mouse made them
+ * (`pointer.ts`). Each target is found when its move begins, on its element if that's still
+ * there, so a scene survives a layout that shifted since it was drawn.
+ */
+import { measure, pointAt } from "./path.js";
+import { actionDuration, autoHandles, LEAD, minimumJerk, moveDuration, PRESS, TAIL, typingDelays } from "./script.js";
+/** Where `target` is on screen now: on its element if that's still in the page and drawn, else at its page point. */
+export function resolve(target, toScreen, scale) {
+    if (target.on) {
+        let element = null;
+        try {
+            element = document.querySelector(target.on.selector);
+        }
+        catch {
+            // A selector this browser can't read: fall back to the point.
+        }
+        const box = element?.getBoundingClientRect();
+        if (box && (box.width || box.height)) {
+            return { x: box.left + target.on.u * box.width, y: box.top + target.on.v * box.height, size: Math.max(4, Math.min(box.width, box.height)) };
+        }
+    }
+    return { ...toScreen(target), size: 24 * scale };
+}
+const rest = (seconds, signal) => new Promise((done) => {
+    if (signal?.aborted || seconds <= 0)
+        return done();
+    const timer = setTimeout(done, seconds * 1000);
+    signal?.addEventListener("abort", () => (clearTimeout(timer), done()), { once: true });
+});
+/** Calls `frame` with 0→1 over `seconds`, once per animation frame, ending on 1 exactly. */
+const animate = (seconds, frame, signal) => new Promise((done) => {
+    if (seconds <= 0)
+        return (frame(1), done());
+    const start = performance.now();
+    const tick = (now) => {
+        if (signal?.aborted)
+            return done();
+        const t = Math.min(1, (now - start) / (seconds * 1000));
+        frame(t);
+        if (t < 1)
+            requestAnimationFrame(tick);
+        else
+            done();
+    };
+    requestAnimationFrame(tick);
+});
+export async function play(script, options) {
+    const { cursor, pointer, signal, scale } = options;
+    const go = (p) => {
+        cursor.place(p.x, p.y);
+        pointer.moveTo(p.x, p.y);
+    };
+    let at = resolve(script.start, options.toScreen, scale);
+    let out = script.out;
+    go(at);
+    await rest(options.lead ?? LEAD, signal);
+    for (const [k, step] of script.steps.entries()) {
+        if (signal?.aborted)
+            return;
+        options.onStep?.(k);
+        const to = resolve(step.to, options.toScreen, scale);
+        await travel(at, to, out, step, go, options);
+        if (signal?.aborted)
+            return;
+        if (step.action !== "move")
+            await rest(step.hover ?? 0, signal);
+        if (step.action === "click" || step.action === "type")
+            await press(options);
+        if (step.action === "type")
+            await type(step.text ?? "", options);
+        await rest(step.wait, signal);
+        at = to;
+        out = step.out;
+    }
+}
+/**
+ * A move's curve on screen: the handles given (stored in page pixels, so enlarged by `scale`),
+ * else a gentle arc. The editor draws the same curve the player travels.
+ */
+export function curve(from, to, out, into, scale) {
+    const arc = autoHandles(from, to);
+    const enlarge = (p) => ({ x: p.x * scale, y: p.y * scale });
+    return [
+        { at: from, out: out ? enlarge(out) : arc.out },
+        { at: to, in: into ? enlarge(into) : arc.in },
+    ];
+}
+/** About how long a script plays, as it would from here: the lead, every move at its pace, the actions, the rests, the tail. */
+export function estimate(script, place, scale) {
+    let total = LEAD + TAIL;
+    let at = place(script.start);
+    let out = script.out;
+    for (const step of script.steps) {
+        const to = place(step.to);
+        total += moveDuration(step, measure(curve(at, to, out, step.in, scale)).total, to.size) + actionDuration(step) + step.wait;
+        at = to;
+        out = step.out;
+    }
+    return total;
+}
+/** One move, along its curve, at a hand's pace. */
+function travel(from, to, out, step, go, { scale, signal }) {
+    const path = measure(curve(from, to, out, step.in, scale));
+    return animate(moveDuration(step, path.total, to.size), (t) => go(pointAt(path, minimumJerk(t) * path.total)), signal);
+}
+async function press({ cursor, pointer, signal }) {
+    pointer.down();
+    cursor.press(true);
+    await rest(PRESS, signal);
+    pointer.up();
+    cursor.press(false);
+}
+/** Types into whatever has focus, a character at a time, as the browser would insert them. */
+async function type(text, { signal, onKey }) {
+    const delays = typingDelays(text);
+    for (const [k, character] of [...text].entries()) {
+        await rest(delays[k], signal);
+        if (signal?.aborted)
+            return;
+        const field = document.activeElement;
+        const key = character === "\n" ? "Enter" : character;
+        field?.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, composed: true }));
+        if (character === "\n") {
+            if (field instanceof HTMLInputElement)
+                field.form?.requestSubmit();
+            else
+                document.execCommand("insertLineBreak");
+        }
+        else if (!document.execCommand("insertText", false, character) && (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement)) {
+            // Where insertText isn't honoured: set the value as a framework's input would see it.
+            const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(field), "value")?.set;
+            setter?.call(field, field.value + character);
+            field.dispatchEvent(new InputEvent("input", { bubbles: true, data: character, inputType: "insertText" }));
+        }
+        field?.dispatchEvent(new KeyboardEvent("keyup", { key, bubbles: true, cancelable: true, composed: true }));
+        onKey?.();
+    }
+}

package/dist/pointer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A pointer the page believes in: the events a mouse would send as the drawn cursor moves and
+ * presses (pointer events, then the mouse events browsers send after them), so the page's own
+ * code reacts as it would to a hand: hover effects, a cloud turning to look, a button pressed.
+ * Over and out carry the element left or entered, as React builds its enter and leave events
+ * from them; enter and leave go to each element crossed. Hover and press are also marked for
+ * CSS (`hover.ts`). The events aren't trusted, so a page that checks `isTrusted` ignores them.
+ */
+type Hit = (x: number, y: number) => Element | null;
+export declare class SyntheticPointer {
+    private readonly hit;
+    private over;
+    private pressed;
+    private x;
+    private y;
+    private buttons;
+    /** `hit` finds the page's element at a point, Closeup's own layers left out. */
+    constructor(hit: Hit);
+    /** Moves to a point on screen: over, out, enter and leave where the element under it changes, then a move. */
+    moveTo(x: number, y: number): void;
+    /** The button goes down here: the press, focus to what takes it, and :active on the way up the tree. */
+    down(): void;
+    /** The button comes up: the release, and a click if it's still over what it pressed. */
+    up(): void;
+    /** Leaves the page: out and leave to everything under the pointer, as when the mouse goes off the window. */
+    leave(): void;
+    private cross;
+    private send;
+}
+export {};

package/dist/pointer.js

@@ -0,0 +1,134 @@
+/**
+ * A pointer the page believes in: the events a mouse would send as the drawn cursor moves and
+ * presses (pointer events, then the mouse events browsers send after them), so the page's own
+ * code reacts as it would to a hand: hover effects, a cloud turning to look, a button pressed.
+ * Over and out carry the element left or entered, as React builds its enter and leave events
+ * from them; enter and leave go to each element crossed. Hover and press are also marked for
+ * CSS (`hover.ts`). The events aren't trusted, so a page that checks `isTrusted` ignores them.
+ */
+import { ACTIVE, HOVER } from "./hover.js";
+const FOCUSABLE = "a[href], button, input, select, textarea, summary, [tabindex], [contenteditable]:not([contenteditable='false'])";
+/** An element and its ancestors, nearest first. */
+function chain(element) {
+    const out = [];
+    for (let e = element; e; e = e.parentElement)
+        out.push(e);
+    return out;
+}
+export class SyntheticPointer {
+    hit;
+    over = null;
+    pressed = null;
+    x = 0;
+    y = 0;
+    buttons = 0;
+    /** `hit` finds the page's element at a point, Closeup's own layers left out. */
+    constructor(hit) {
+        this.hit = hit;
+    }
+    /** Moves to a point on screen: over, out, enter and leave where the element under it changes, then a move. */
+    moveTo(x, y) {
+        const target = this.hit(x, y) ?? document.documentElement;
+        const moved = { x: x - this.x, y: y - this.y };
+        this.x = x;
+        this.y = y;
+        if (target !== this.over)
+            this.cross(target);
+        this.send(target, "pointermove", { movementX: moved.x, movementY: moved.y });
+        this.send(target, "mousemove", { movementX: moved.x, movementY: moved.y });
+    }
+    /** The button goes down here: the press, focus to what takes it, and :active on the way up the tree. */
+    down() {
+        const target = this.over ?? document.documentElement;
+        this.buttons = 1;
+        this.pressed = target;
+        this.send(target, "pointerdown");
+        this.send(target, "mousedown");
+        const focusable = target.closest(FOCUSABLE);
+        if (focusable)
+            focusable.focus({ preventScroll: true });
+        else if (document.activeElement instanceof HTMLElement && document.activeElement !== document.body)
+            document.activeElement.blur();
+        for (const element of chain(focusable ?? target))
+            element.setAttribute(ACTIVE, "");
+    }
+    /** The button comes up: the release, and a click if it's still over what it pressed. */
+    up() {
+        const target = this.over ?? document.documentElement;
+        this.buttons = 0;
+        this.send(target, "pointerup");
+        this.send(target, "mouseup");
+        for (const element of document.querySelectorAll(`[${ACTIVE}]`))
+            element.removeAttribute(ACTIVE);
+        const pressed = this.pressed;
+        this.pressed = null;
+        if (!pressed)
+            return;
+        // As browsers do: the click goes to the nearest element holding both the press and the release.
+        const common = chain(pressed).find((element) => element.contains(target));
+        if (common)
+            this.send(common, "click", { detail: 1 });
+    }
+    /** Leaves the page: out and leave to everything under the pointer, as when the mouse goes off the window. */
+    leave() {
+        this.cross(null);
+    }
+    cross(target) {
+        const from = this.over;
+        const left = chain(from);
+        const entered = chain(target);
+        const stays = new Set(left.filter((element) => entered.includes(element)));
+        if (from) {
+            this.send(from, "pointerout", { relatedTarget: target });
+            for (const element of left)
+                if (!stays.has(element))
+                    this.send(element, "pointerleave", { relatedTarget: target, bubbles: false });
+            this.send(from, "mouseout", { relatedTarget: target });
+            for (const element of left)
+                if (!stays.has(element))
+                    this.send(element, "mouseleave", { relatedTarget: target, bubbles: false });
+        }
+        for (const element of left)
+            if (!stays.has(element))
+                element.removeAttribute(HOVER);
+        if (target) {
+            this.send(target, "pointerover", { relatedTarget: from });
+            for (const element of [...entered].reverse())
+                if (!stays.has(element))
+                    this.send(element, "pointerenter", { relatedTarget: from, bubbles: false });
+            this.send(target, "mouseover", { relatedTarget: from });
+            for (const element of [...entered].reverse())
+                if (!stays.has(element))
+                    this.send(element, "mouseenter", { relatedTarget: from, bubbles: false });
+        }
+        for (const element of entered)
+            element.setAttribute(HOVER, "");
+        this.over = target;
+    }
+    send(target, type, extra = {}) {
+        const init = {
+            bubbles: extra.bubbles ?? true,
+            cancelable: true,
+            composed: true,
+            view: window,
+            clientX: this.x,
+            clientY: this.y,
+            screenX: this.x + window.screenX,
+            screenY: this.y + window.screenY,
+            button: type.endsWith("down") || type.endsWith("up") || type === "click" ? 0 : -1,
+            buttons: this.buttons,
+            relatedTarget: extra.relatedTarget ?? null,
+            detail: extra.detail ?? 0,
+            movementX: extra.movementX ?? 0,
+            movementY: extra.movementY ?? 0,
+            pointerId: 1,
+            pointerType: "mouse",
+            isPrimary: true,
+            width: 1,
+            height: 1,
+            pressure: this.buttons ? 0.5 : 0,
+        };
+        const event = type.startsWith("pointer") ? new PointerEvent(type, init) : new MouseEvent(type, { ...init, button: Math.max(0, init.button ?? 0) });
+        target.dispatchEvent(event);
+    }
+}

package/dist/script.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A scripted take: where the drawn cursor starts, where it goes, by which curves, and what it
+ * does on arriving (click, type, or nothing but rest there, which is hovering). Plain data,
+ * saved as JSON, so a scene can be played again after the page changes. Pure: the player
+ * (`player.ts`) reads it, the editor writes it.
+ */
+import { type Point } from "./path.ts";
+/**
+ * Where the cursor goes: a point in the page as laid out (document CSS pixels, not enlarged),
+ * and the element it was put on, if any, with where in that element's box (0 to 1 across and
+ * down), so the point follows the element when the layout moves.
+ */
+export type Target = {
+    x: number;
+    y: number;
+    on?: {
+        selector: string;
+        u: number;
+        v: number;
+    };
+};
+export type Action = "move" | "click" | "type";
+export type Step = {
+    to: Target;
+    /** The curve's handle arriving here, relative to the point, in page pixels; none for a gentle arc. */
+    in?: Point;
+    /** The handle leaving here toward the next step. */
+    out?: Point;
+    /** What happens on arriving: "move" only rests there, which is hovering. */
+    action: Action;
+    /** What "type" types. */
+    text?: string;
+    /** Seconds resting on arrival before clicking or typing, to show what hovering does. */
+    hover?: number;
+    /** Seconds the move here takes; none for a hand's pace (Fitts's law). */
+    duration?: number;
+    /** Seconds to rest after arriving and acting. */
+    wait: number;
+};
+export type Script = {
+    version: 1;
+    start: Target;
+    /** The handle leaving the start. */
+    out?: Point;
+    steps: Step[];
+};
+/** How far a move without handles bows, as a share of its length: a wrist turns, so hands don't move in lines. */
+export declare const BEND = 0.12;
+/** Seconds the cursor waits where it starts before moving, and lingers after the last step, while filming. */
+export declare const LEAD = 0.6;
+export declare const TAIL = 0.8;
+/** A click: the button held this long. */
+export declare const PRESS = 0.075;
+/**
+ * Minimum jerk: how a hand covers a reach, slow to start, quickest midway, slow to arrive
+ * (Flash and Hogan, 1985). Smoother than a cubic ease: its acceleration starts and ends at zero.
+ */
+export declare const minimumJerk: (t: number) => number;
+/**
+ * Handles for a move from `a` to `b` that wasn't given any: a third of the way along each end,
+ * pushed to the left of the direction of travel by `bend` of the length, so the move bows
+ * gently, as a wrist pivoting does. Relative to their points, as a script stores them.
+ */
+export declare function autoHandles(a: Point, b: Point, bend?: number): {
+    out: Point;
+    in: Point;
+};
+/** How long a move takes: as given, or a hand's pace for its length and the size of what it reaches for. */
+export declare const moveDuration: (step: Pick<Step, "duration">, distance: number, size: number) => number;
+/** Seconds between typed characters: a person's uneven rhythm, the same every time for the same text. */
+export declare function typingDelays(text: string): number[];
+/** How long a step's action lasts once there: a press, or the press and the typing. */
+export declare const actionDuration: (step: Step) => number;
+/** A script read back from storage or a file, or null if it isn't one; anything unknown is dropped. */
+export declare function parseScript(value: unknown): Script | null;

package/dist/script.js

@@ -0,0 +1,94 @@
+/**
+ * A scripted take: where the drawn cursor starts, where it goes, by which curves, and what it
+ * does on arriving (click, type, or nothing but rest there, which is hovering). Plain data,
+ * saved as JSON, so a scene can be played again after the page changes. Pure: the player
+ * (`player.ts`) reads it, the editor writes it.
+ */
+import { reachTime } from "./path.js";
+/** How far a move without handles bows, as a share of its length: a wrist turns, so hands don't move in lines. */
+export const BEND = 0.12;
+/** Seconds the cursor waits where it starts before moving, and lingers after the last step, while filming. */
+export const LEAD = 0.6;
+export const TAIL = 0.8;
+/** A click: the button held this long. */
+export const PRESS = 0.075;
+/**
+ * Minimum jerk: how a hand covers a reach, slow to start, quickest midway, slow to arrive
+ * (Flash and Hogan, 1985). Smoother than a cubic ease: its acceleration starts and ends at zero.
+ */
+export const minimumJerk = (t) => {
+    const u = Math.max(0, Math.min(1, t));
+    return u * u * u * (10 + u * (-15 + 6 * u));
+};
+/**
+ * Handles for a move from `a` to `b` that wasn't given any: a third of the way along each end,
+ * pushed to the left of the direction of travel by `bend` of the length, so the move bows
+ * gently, as a wrist pivoting does. Relative to their points, as a script stores them.
+ */
+export function autoHandles(a, b, bend = BEND) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    // Left of travel on screen (y grows down): (dy, -dx).
+    const nx = dy * bend;
+    const ny = -dx * bend;
+    return { out: { x: dx / 3 + nx, y: dy / 3 + ny }, in: { x: -dx / 3 + nx, y: -dy / 3 + ny } };
+}
+/** How long a move takes: as given, or a hand's pace for its length and the size of what it reaches for. */
+export const moveDuration = (step, distance, size) => step.duration ?? (distance < 1 ? 0 : reachTime(distance, size));
+/** Seconds between typed characters: a person's uneven rhythm, the same every time for the same text. */
+export function typingDelays(text) {
+    return [...text].map((character, k) => {
+        // A small hash of the character and its place, for an even spread in 0–1.
+        const h = Math.sin((character.codePointAt(0) ?? 0) * 12.9898 + k * 78.233) * 43758.5453;
+        const spread = h - Math.floor(h);
+        // Spaces come a little slower, as the next word is reached for.
+        return (character === " " ? 0.11 : 0.06) + spread * 0.07;
+    });
+}
+/** How long a step's action lasts once there: a press, or the press and the typing. */
+export const actionDuration = (step) => step.action === "click"
+    ? (step.hover ?? 0) + PRESS
+    : step.action === "type"
+        ? (step.hover ?? 0) + PRESS + typingDelays(step.text ?? "").reduce((a, b) => a + b, 0)
+        : 0;
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const pointOf = (value) => {
+    const p = value;
+    return p && isNumber(p.x) && isNumber(p.y) ? { x: p.x, y: p.y } : undefined;
+};
+function targetOf(value) {
+    const t = value;
+    if (!t || !isNumber(t.x) || !isNumber(t.y))
+        return undefined;
+    const on = t.on;
+    const anchored = on && typeof on.selector === "string" && on.selector && isNumber(on.u) && isNumber(on.v);
+    return { x: t.x, y: t.y, ...(anchored ? { on: { selector: on.selector, u: on.u, v: on.v } } : {}) };
+}
+/** A script read back from storage or a file, or null if it isn't one; anything unknown is dropped. */
+export function parseScript(value) {
+    const raw = value;
+    if (!raw || raw.version !== 1 || !Array.isArray(raw.steps))
+        return null;
+    const start = targetOf(raw.start);
+    if (!start)
+        return null;
+    const steps = [];
+    for (const item of raw.steps) {
+        const s = item;
+        const to = targetOf(s?.to);
+        if (!to)
+            return null;
+        const action = s.action === "click" || s.action === "type" ? s.action : "move";
+        steps.push({
+            to,
+            ...(pointOf(s.in) ? { in: pointOf(s.in) } : {}),
+            ...(pointOf(s.out) ? { out: pointOf(s.out) } : {}),
+            action,
+            ...(action === "type" ? { text: typeof s.text === "string" ? s.text : "" } : {}),
+            ...(action !== "move" && isNumber(s.hover) && s.hover > 0 ? { hover: s.hover } : {}),
+            ...(isNumber(s.duration) && s.duration >= 0 ? { duration: s.duration } : {}),
+            wait: isNumber(s.wait) && s.wait >= 0 ? s.wait : 0,
+        });
+    }
+    return { version: 1, start, ...(pointOf(raw.out) ? { out: pointOf(raw.out) } : {}), steps };
+}

package/dist/selector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Naming elements so a script can find them again: what a placed point is on, as a CSS
+ * selector that still finds that element after a reload. Classes that only style (Tailwind's
+ * and the like) and ids a framework makes up per render are passed over: they change between
+ * builds, or say nothing about what the element is.
+ */
+export declare const isUtility: (name: string) => boolean;
+/** Ids that frameworks generate per render (React's useId, Radix, Headless UI, MUI), or that carry a counter. */
+export declare const isStableId: (id: string) => boolean;
+/** The classes worth naming an element by. */
+export declare const meaningfulClasses: (element: Element) => string[];
+/** "div.mascot-body", "button Ask the cloud": enough to know what's outlined. */
+export declare function describe(element: Element): string;
+/** A selector that finds `element` alone in the document: by name if it has one, else by its place under the nearest named ancestor. */
+export declare function selectorFor(element: Element): string;
+/**
+ * What a point placed on `element` should follow: the nearest thing with a name of its own
+ * between it and what you'd click (a link, a button), else that clickable thing, else the
+ * element itself once it's big enough to be a thing. None for the page itself or a container
+ * nearly as big as the window: a point there is only a place.
+ */
+export declare function anchorFor(element: Element | null): Element | null;

package/dist/selector.js

@@ -0,0 +1,83 @@
+/**
+ * Naming elements so a script can find them again: what a placed point is on, as a CSS
+ * selector that still finds that element after a reload. Classes that only style (Tailwind's
+ * and the like) and ids a framework makes up per render are passed over: they change between
+ * builds, or say nothing about what the element is.
+ */
+/** Utility classes say how something looks, not what it is. */
+const UTILITY = /[[\]:/.]|^-?(?:[mp][xytrbl]?|w|h|min|max|gap|text|bg|border|rounded|items|justify|self|place|font|leading|tracking|basis|col|row|z|top|left|right|bottom|inset|opacity|duration|ease|delay|translate|scale|rotate|cursor|select|pointer|size|space|divide|whitespace|break|aspect|object|fill|stroke|decoration|origin|animate)-|^(?:flex|grid|block|inline|hidden|contents|relative|absolute|fixed|sticky|static|shrink|grow|overflow|shadow|ring|outline|transition|truncate|sr-only|isolate|group|peer|italic|uppercase|lowercase|capitalize|antialiased)/;
+export const isUtility = (name) => UTILITY.test(name);
+/** Ids that frameworks generate per render (React's useId, Radix, Headless UI, MUI), or that carry a counter. */
+export const isStableId = (id) => !!id && !/^(?:_R_|:r|«r|radix-|headlessui-|mui-|react-aria)|[:«»]|\d{3,}/.test(id);
+/** The classes worth naming an element by. */
+export const meaningfulClasses = (element) => [...element.classList].filter((name) => !isUtility(name));
+/** "div.mascot-body", "button Ask the cloud": enough to know what's outlined. */
+export function describe(element) {
+    const name = element.getAttribute("aria-label") || (element.id && isStableId(element.id) ? `#${element.id}` : "") || meaningfulClasses(element).slice(0, 2).map((c) => `.${c}`).join("");
+    return `${element.tagName.toLowerCase()}${name ? (name.startsWith("#") || name.startsWith(".") ? name : ` ${name}`) : ""}`;
+}
+const quoted = (value) => `"${value.replace(/["\\]/g, "\\$&")}"`;
+/** A selector that finds `element` alone in the document: by name if it has one, else by its place under the nearest named ancestor. */
+export function selectorFor(element) {
+    const only = (selector) => {
+        try {
+            const found = document.querySelectorAll(selector);
+            return found.length === 1 && found[0] === element;
+        }
+        catch {
+            return false;
+        }
+    };
+    const tag = element.tagName.toLowerCase();
+    if (element === document.body || element === document.documentElement)
+        return tag;
+    if (element.id && isStableId(element.id) && only(`#${CSS.escape(element.id)}`))
+        return `#${CSS.escape(element.id)}`;
+    for (const attribute of ["data-testid", "data-test", "data-cy", "name"]) {
+        const value = element.getAttribute(attribute);
+        if (value && only(`${tag}[${attribute}=${quoted(value)}]`))
+            return `${tag}[${attribute}=${quoted(value)}]`;
+    }
+    const href = element instanceof HTMLAnchorElement ? element.getAttribute("href") : null;
+    if (href && only(`a[href=${quoted(href)}]`))
+        return `a[href=${quoted(href)}]`;
+    for (const name of meaningfulClasses(element)) {
+        const selector = `${tag}.${CSS.escape(name)}`;
+        if (only(selector))
+            return selector;
+    }
+    const parent = element.parentElement;
+    if (!parent)
+        return tag;
+    const place = `${tag}:nth-child(${[...parent.children].indexOf(element) + 1})`;
+    return `${selectorFor(parent)} > ${place}`;
+}
+const INTERACTIVE = "a[href], button, input, select, textarea, label, summary, [role='button'], [role='link'], [role='tab'], [role='menuitem'], [role='option'], [role='switch'], [role='checkbox'], [tabindex]:not([tabindex='-1'])";
+/** Under this, both ways, an element is a part (a glyph, a stroke) rather than a thing to aim at. */
+const SMALLEST = 16;
+/**
+ * What a point placed on `element` should follow: the nearest thing with a name of its own
+ * between it and what you'd click (a link, a button), else that clickable thing, else the
+ * element itself once it's big enough to be a thing. None for the page itself or a container
+ * nearly as big as the window: a point there is only a place.
+ */
+export function anchorFor(element) {
+    if (!element || element === document.body || element === document.documentElement)
+        return null;
+    const clickable = element.closest(INTERACTIVE);
+    const top = clickable ?? element.parentElement?.parentElement ?? element;
+    for (let e = element; e; e = e.parentElement) {
+        const box = e.getBoundingClientRect();
+        const big = box.width >= SMALLEST || box.height >= SMALLEST;
+        if (big && !selectorFor(e).includes(":nth-child"))
+            return within(e);
+        if (e === top)
+            break;
+    }
+    return within(clickable ?? element);
+}
+/** The element, unless it's nearly the whole window. */
+function within(element) {
+    const box = element.getBoundingClientRect();
+    return box.width * box.height > innerWidth * innerHeight * 0.5 ? null : element;
+}