@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/ui/toggleMenuItems.d.ts

@@ -0,0 +1,44 @@
+import type { CheckboxMenuItem, MenuItem, RadioMenuItem } from './MenuTypes.ts';
+export interface SettingRowOptions {
+    helpText?: string;
+    disabled?: boolean;
+    disabledHelpText?: string;
+    keepMenuOpen?: boolean;
+}
+/** #menuBuilder checkboxItem | one checkbox setting row */
+export declare function checkboxItem(label: string, checked: boolean, onToggle: () => void, opts?: SettingRowOptions): CheckboxMenuItem;
+/**
+ * #menuBuilder toggleItem | a checkbox row whose setter takes the new value
+ *
+ * `checkboxItem` where the callback is handed the value rather than left to
+ * derive it. Prefer this: the derivation is `!` applied to the same expression
+ * the row is `checked` by, and writing it out per row is 38 chances to negate
+ * the wrong thing — which fails as a checkbox that ticks and does nothing, with
+ * nothing thrown.
+ *
+ * It is also the shape `radioItems` already takes (`setMode: (m: T) => void`),
+ * so the two group builders now agree about who computes the new value.
+ *
+ * MAF had this as a local wrapper, and it had already lost most of
+ * `SettingRowOptions` to a hand-narrowed one-field bag — the exact drift the
+ * comment on that interface warns about.
+ */
+export declare function toggleItem(label: string, value: boolean, setValue: (value: boolean) => void, opts?: SettingRowOptions): CheckboxMenuItem;
+/** #menuBuilder radioItem | one radio setting row; the singular of `radioItems` */
+export declare function radioItem(label: string, checked: boolean, onClick: () => void, opts?: SettingRowOptions): RadioMenuItem;
+export interface RadioOption<T extends string> {
+    value: T;
+    label: string;
+    helpText?: string;
+    keepMenuOpen?: boolean;
+}
+/** #menuBuilder radioItems | a radio group, one row per option */
+export declare function radioItems<T extends string>(options: readonly RadioOption<T>[], current: T | undefined, setMode: (m: T) => void): RadioMenuItem[];
+/**
+ * #menuBuilder withSubHeader | a section heading, present only if the section is
+ *
+ * Derived from the rows rather than from whatever gated them, so a heading
+ * cannot outlive its section — the rows are usually gated on data, and an empty
+ * section renders its heading directly above the next one's.
+ */
+export declare function withSubHeader(label: string, rows: MenuItem[]): MenuItem[];

package/esm/ui/toggleMenuItems.js

@@ -0,0 +1,60 @@
+/** #menuBuilder checkboxItem | one checkbox setting row */
+export function checkboxItem(label, checked, onToggle, opts) {
+    return {
+        label,
+        type: 'checkbox',
+        checked,
+        onClick: onToggle,
+        ...opts,
+    };
+}
+/**
+ * #menuBuilder toggleItem | a checkbox row whose setter takes the new value
+ *
+ * `checkboxItem` where the callback is handed the value rather than left to
+ * derive it. Prefer this: the derivation is `!` applied to the same expression
+ * the row is `checked` by, and writing it out per row is 38 chances to negate
+ * the wrong thing — which fails as a checkbox that ticks and does nothing, with
+ * nothing thrown.
+ *
+ * It is also the shape `radioItems` already takes (`setMode: (m: T) => void`),
+ * so the two group builders now agree about who computes the new value.
+ *
+ * MAF had this as a local wrapper, and it had already lost most of
+ * `SettingRowOptions` to a hand-narrowed one-field bag — the exact drift the
+ * comment on that interface warns about.
+ */
+export function toggleItem(label, value, setValue, opts) {
+    return checkboxItem(label, value, () => {
+        setValue(!value);
+    }, opts);
+}
+// One radio row. The singular of `radioItems`, and what
+// `promotableRadioItem` builds through, so a lone radio row and a member of a
+// group are the same object plus or minus its pin.
+/** #menuBuilder radioItem | one radio setting row; the singular of `radioItems` */
+export function radioItem(label, checked, onClick, opts) {
+    return {
+        label,
+        type: 'radio',
+        checked,
+        onClick,
+        ...opts,
+    };
+}
+/** #menuBuilder radioItems | a radio group, one row per option */
+export function radioItems(options, current, setMode) {
+    return options.map(({ value, label, ...opts }) => radioItem(label, current === value, () => {
+        setMode(value);
+    }, opts));
+}
+/**
+ * #menuBuilder withSubHeader | a section heading, present only if the section is
+ *
+ * Derived from the rows rather than from whatever gated them, so a heading
+ * cannot outlive its section — the rows are usually gated on data, and an empty
+ * section renders its heading directly above the next one's.
+ */
+export function withSubHeader(label, rows) {
+    return rows.length > 0 ? [{ type: 'subHeader', label }, ...rows] : [];
+}

package/esm/ui/useAssemblySelection.d.ts

@@ -0,0 +1,153 @@
+import type { AbstractSessionModel } from '../util/index.ts';
+export declare function instanceScopedKey(prefix: string, suffix: string): string;
+/**
+ * Tracks the assembly chosen in an import form and resolves the outcomes the
+ * form renders from: `assemblyError` (failed, or nothing configured), `regions`
+ * (ready), or neither (still loading). The user's choice is stored as an
+ * override and re-resolved against the live assembly list every render, so it
+ * always names a currently-configured assembly even as assemblies load in, get
+ * removed, or when a remembered choice is no longer valid. Passing a
+ * `localStorageKey` persists the choice across reloads. Shared by the LGV and
+ * circular-view import forms.
+ */
+export declare function useAssemblySelection(session: AbstractSessionModel, localStorageKey?: string): {
+    selectedAssemblyName: string | undefined;
+    setSelectedAssemblyName: (value: string | ((val: string | undefined) => string | undefined) | undefined) => void;
+    assembly: (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+        configuration: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>;
+    }> & {
+        error: unknown;
+        loadingP: Promise<void> | undefined;
+        adapterLoads: import("@jbrowse/quick-lru").default<string, Promise<import("../assemblyManager/refNameMaps.ts").RefNameAliases>>;
+        volatileRegions: import("../assemblyManager/assembly.ts").BasicRegion[] | undefined;
+        refNameAliases: import("../assemblyManager/refNameMaps.ts").RefNameAliases | undefined;
+        canonicalToSeqAdapterRefNames: Record<string, string> | undefined;
+        cytobands: import("../util/simpleFeature.ts").Feature[] | undefined;
+        loadedGeneticCodes: Record<string, number> | undefined;
+        lowerCaseRefNameAliases: import("../assemblyManager/refNameMaps.ts").RefNameAliases | undefined;
+        statusMessage: string | undefined;
+        statusProgress: number | undefined;
+        statusSource: string | undefined;
+        refNameMismatches: Map<string, import("../assemblyManager/refNameMismatch.ts").RefNameMismatch>;
+    } & {
+        getConf(arg: string): any;
+    } & {
+        readonly name: string;
+        readonly aliases: string[];
+        readonly displayName: string;
+        readonly refNameColors: string[];
+    } & {
+        readonly allAliases: string[];
+        hasName(name: string): boolean;
+    } & {
+        setStatus(status?: import("../util/progress.ts").RpcStatus): void;
+        setRefNameMismatch(adapterCacheKey: string, mismatch: import("../assemblyManager/refNameMismatch.ts").RefNameMismatch): void;
+    } & {
+        setLoaded({ regions, refNameAliases, lowerCaseRefNameAliases, canonicalToSeqAdapterRefNames, cytobands, geneticCodes, }: import("../assemblyManager/refNameMaps.ts").RefNameMaps & {
+            regions: import("../util/index.ts").Region[];
+            cytobands: import("../util/simpleFeature.ts").Feature[];
+            geneticCodes: Record<string, number>;
+        }): void;
+        setError(e: unknown): void;
+        setLoadingP(p?: Promise<void>): void;
+        loadPre(): Promise<void>;
+    } & {
+        load(): Promise<void>;
+    } & {
+        afterAttach(): void;
+    } & {
+        readonly initialized: boolean;
+        readonly regions: import("../assemblyManager/assembly.ts").BasicRegion[] | undefined;
+        readonly allRefNames: string[] | undefined;
+        readonly namesByCanonicalRefName: Map<string, string[]> | undefined;
+        readonly rpcManager: import("../rpc/RpcManager.ts").default;
+    } & {
+        readonly refNames: string[] | undefined;
+    } & {
+        readonly refNameToIndex: Map<string, number> | undefined;
+    } & {
+        getCanonicalRefName(refName: string): string | undefined;
+        getRefNameColor(refName: string): string | undefined;
+        getRegionForRefName(refName: string): import("../assemblyManager/assembly.ts").BasicRegion | undefined;
+        getGeneticCodeId(refName: string): number;
+        getSeqAdapterRefName(canonicalRefName: string): string;
+    } & {
+        getCanonicalRefName2(refName: string): string;
+        isValidRefName(refName: string): boolean;
+    } & {
+        getAliasesForRefName(refName: string): string[];
+        getRefNameMapForAdapter(adapterConf: {
+            [x: string]: unknown;
+        }, options: import("../data_adapters/BaseAdapter/types.ts").BaseOptions): Promise<import("../assemblyManager/refNameMaps.ts").RefNameAliases>;
+        getRefNameMismatch(adapterCacheKey: string): import("../assemblyManager/refNameMismatch.ts").RefNameMismatch | undefined;
+    } & import("@jbrowse/mobx-state-tree").IStateTreeNode<import("@jbrowse/mobx-state-tree").IModelType<{
+        configuration: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>;
+    }, {
+        error: unknown;
+        loadingP: Promise<void> | undefined;
+        adapterLoads: import("@jbrowse/quick-lru").default<string, Promise<import("../assemblyManager/refNameMaps.ts").RefNameAliases>>;
+        volatileRegions: import("../assemblyManager/assembly.ts").BasicRegion[] | undefined;
+        refNameAliases: import("../assemblyManager/refNameMaps.ts").RefNameAliases | undefined;
+        canonicalToSeqAdapterRefNames: Record<string, string> | undefined;
+        cytobands: import("../util/simpleFeature.ts").Feature[] | undefined;
+        loadedGeneticCodes: Record<string, number> | undefined;
+        lowerCaseRefNameAliases: import("../assemblyManager/refNameMaps.ts").RefNameAliases | undefined;
+        statusMessage: string | undefined;
+        statusProgress: number | undefined;
+        statusSource: string | undefined;
+        refNameMismatches: Map<string, import("../assemblyManager/refNameMismatch.ts").RefNameMismatch>;
+    } & {
+        getConf(arg: string): any;
+    } & {
+        readonly name: string;
+        readonly aliases: string[];
+        readonly displayName: string;
+        readonly refNameColors: string[];
+    } & {
+        readonly allAliases: string[];
+        hasName(name: string): boolean;
+    } & {
+        setStatus(status?: import("../util/progress.ts").RpcStatus): void;
+        setRefNameMismatch(adapterCacheKey: string, mismatch: import("../assemblyManager/refNameMismatch.ts").RefNameMismatch): void;
+    } & {
+        setLoaded({ regions, refNameAliases, lowerCaseRefNameAliases, canonicalToSeqAdapterRefNames, cytobands, geneticCodes, }: import("../assemblyManager/refNameMaps.ts").RefNameMaps & {
+            regions: import("../util/index.ts").Region[];
+            cytobands: import("../util/simpleFeature.ts").Feature[];
+            geneticCodes: Record<string, number>;
+        }): void;
+        setError(e: unknown): void;
+        setLoadingP(p?: Promise<void>): void;
+        loadPre(): Promise<void>;
+    } & {
+        load(): Promise<void>;
+    } & {
+        afterAttach(): void;
+    } & {
+        readonly initialized: boolean;
+        readonly regions: import("../assemblyManager/assembly.ts").BasicRegion[] | undefined;
+        readonly allRefNames: string[] | undefined;
+        readonly namesByCanonicalRefName: Map<string, string[]> | undefined;
+        readonly rpcManager: import("../rpc/RpcManager.ts").default;
+    } & {
+        readonly refNames: string[] | undefined;
+    } & {
+        readonly refNameToIndex: Map<string, number> | undefined;
+    } & {
+        getCanonicalRefName(refName: string): string | undefined;
+        getRefNameColor(refName: string): string | undefined;
+        getRegionForRefName(refName: string): import("../assemblyManager/assembly.ts").BasicRegion | undefined;
+        getGeneticCodeId(refName: string): number;
+        getSeqAdapterRefName(canonicalRefName: string): string;
+    } & {
+        getCanonicalRefName2(refName: string): string;
+        isValidRefName(refName: string): boolean;
+    } & {
+        getAliasesForRefName(refName: string): string[];
+        getRefNameMapForAdapter(adapterConf: {
+            [x: string]: unknown;
+        }, options: import("../data_adapters/BaseAdapter/types.ts").BaseOptions): Promise<import("../assemblyManager/refNameMaps.ts").RefNameAliases>;
+        getRefNameMismatch(adapterCacheKey: string): import("../assemblyManager/refNameMismatch.ts").RefNameMismatch | undefined;
+    }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>) | undefined;
+    assemblyError: unknown;
+    regions: import("../assemblyManager/assembly.ts").BasicRegion[] | undefined;
+};

package/esm/ui/useAssemblySelection.js

@@ -0,0 +1,54 @@
+import { useLocalStorage } from '../util/hooks.js';
+// scope a localStorage key to this host/path/config so reloads (and embedded
+// apps sharing a host) see their own value. Shared by the remembered-assembly
+// and recent-locations persistence
+//
+// The near-twin is data-management's `configScopedKey`, and the two must NOT be
+// merged even though they are the same idea. They disagree on every detail that
+// reaches the output: this one includes the host, joins unfiltered (so a page
+// with no `?config=` genuinely stores a literal `null` segment) and assumes a
+// browser; that one omits the host, filters empty parts out, and answers
+// `'empty'` off-window. So a "cleanup" that unified them would re-key every
+// stored setting on both sides at once — remembered assembly and recent
+// locations here, hidden columns and widths there — and every user would find
+// their settings silently back at the defaults. Touch either spelling only as a
+// deliberate migration.
+export function instanceScopedKey(prefix, suffix) {
+    const config = new URLSearchParams(window.location.search).get('config');
+    return [
+        prefix,
+        window.location.host + window.location.pathname,
+        config,
+        suffix,
+    ].join('-');
+}
+/**
+ * Tracks the assembly chosen in an import form and resolves the outcomes the
+ * form renders from: `assemblyError` (failed, or nothing configured), `regions`
+ * (ready), or neither (still loading). The user's choice is stored as an
+ * override and re-resolved against the live assembly list every render, so it
+ * always names a currently-configured assembly even as assemblies load in, get
+ * removed, or when a remembered choice is no longer valid. Passing a
+ * `localStorageKey` persists the choice across reloads. Shared by the LGV and
+ * circular-view import forms.
+ */
+export function useAssemblySelection(session, localStorageKey) {
+    const { assemblyNames, assemblyManager } = session;
+    const [override, setOverride] = useLocalStorage(instanceScopedKey('lastAssembly', localStorageKey ?? ''), undefined, Boolean(localStorageKey));
+    const selectedAssemblyName = assemblyNames.includes(override ?? '')
+        ? override
+        : assemblyNames[0];
+    const assembly = selectedAssemblyName
+        ? assemblyManager.get(selectedAssemblyName)
+        : undefined;
+    const assemblyError = assemblyNames.length
+        ? assembly?.error
+        : 'No configured assemblies';
+    return {
+        selectedAssemblyName,
+        setSelectedAssemblyName: setOverride,
+        assembly,
+        assemblyError,
+        regions: assembly?.regions,
+    };
+}

package/esm/ui/useCoalescedPointer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Run a pointer handler at most once per frame, on the latest position.
+ *
+ * `mousemove` arrives far faster than a frame on any modern pointer, so a
+ * handler doing real work per raw event is spending most of it on positions the
+ * user never sees. The pileup's hit test measured 3.3ms of listener time per
+ * event on a 150px canvas — five events into a frame the frame is already gone —
+ * and it was the most expensive hover of any display.
+ *
+ * **Coalescing is only safe because nothing decides anything from a hover.**
+ * Click and right-click re-run their own hit test from their own event, which is
+ * already the rule (a hover recorded a frame ago must not act), so a hover
+ * landing one frame after the cursor is by construction invisible. A gesture
+ * that reads the stored hover instead would see this as a lost frame.
+ *
+ * The **first** scheduled frame is kept and the latest payload read inside it,
+ * rather than cancelling and rescheduling per event: both deliver one call per
+ * frame, and this one does no cancel churn. (`useMouseTracking` reschedules
+ * because it also publishes to a store that a mid-frame leave must be able to
+ * clear.)
+ *
+ * `cancel` is the other half, and it is not optional. A frame queued just before
+ * the pointer leaves lands *after* it has gone and re-lights the hover the leave
+ * handler just cleared, so a `mouseleave` cancels before clearing. Unmount
+ * cancels too — a display is detached from the MST tree before React unmounts
+ * it, so a frame landing in between writes onto a dead node.
+ *
+ * The payload is whatever the caller reads off the event, because where a
+ * display's coordinates come from is its own business: a borderless leaf canvas
+ * takes `offsetX`/`offsetY`, one with overlays measures a rect. Read it at event
+ * time — a React event's fields are gone by the frame.
+ */
+export declare function useCoalescedPointer<T>(onFrame: (payload: T) => void): {
+    queue: (payload: T) => void;
+    cancel: () => void;
+};

package/esm/ui/useCoalescedPointer.js

@@ -0,0 +1,60 @@
+import { useEffect, useRef } from 'react';
+import { useEventCallback } from '../util/useEventCallback.js';
+/**
+ * Run a pointer handler at most once per frame, on the latest position.
+ *
+ * `mousemove` arrives far faster than a frame on any modern pointer, so a
+ * handler doing real work per raw event is spending most of it on positions the
+ * user never sees. The pileup's hit test measured 3.3ms of listener time per
+ * event on a 150px canvas — five events into a frame the frame is already gone —
+ * and it was the most expensive hover of any display.
+ *
+ * **Coalescing is only safe because nothing decides anything from a hover.**
+ * Click and right-click re-run their own hit test from their own event, which is
+ * already the rule (a hover recorded a frame ago must not act), so a hover
+ * landing one frame after the cursor is by construction invisible. A gesture
+ * that reads the stored hover instead would see this as a lost frame.
+ *
+ * The **first** scheduled frame is kept and the latest payload read inside it,
+ * rather than cancelling and rescheduling per event: both deliver one call per
+ * frame, and this one does no cancel churn. (`useMouseTracking` reschedules
+ * because it also publishes to a store that a mid-frame leave must be able to
+ * clear.)
+ *
+ * `cancel` is the other half, and it is not optional. A frame queued just before
+ * the pointer leaves lands *after* it has gone and re-lights the hover the leave
+ * handler just cleared, so a `mouseleave` cancels before clearing. Unmount
+ * cancels too — a display is detached from the MST tree before React unmounts
+ * it, so a frame landing in between writes onto a dead node.
+ *
+ * The payload is whatever the caller reads off the event, because where a
+ * display's coordinates come from is its own business: a borderless leaf canvas
+ * takes `offsetX`/`offsetY`, one with overlays measures a rect. Read it at event
+ * time — a React event's fields are gone by the frame.
+ */
+export function useCoalescedPointer(onFrame) {
+    const rafRef = useRef(undefined);
+    const payloadRef = useRef(undefined);
+    const runFrame = useEventCallback(onFrame);
+    const cancel = useEventCallback(() => {
+        if (rafRef.current !== undefined) {
+            cancelAnimationFrame(rafRef.current);
+            rafRef.current = undefined;
+        }
+        payloadRef.current = undefined;
+    });
+    useEffect(() => cancel, [cancel]);
+    const queue = useEventCallback((payload) => {
+        payloadRef.current = payload;
+        if (rafRef.current === undefined) {
+            rafRef.current = requestAnimationFrame(() => {
+                rafRef.current = undefined;
+                const latest = payloadRef.current;
+                if (latest !== undefined) {
+                    runFrame(latest);
+                }
+            });
+        }
+    });
+    return { queue, cancel };
+}

package/esm/ui/useCopyToClipboard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copy to the clipboard and briefly flash a "copied" confirmation. Returns the
+ * flag to render that confirmation from and the copy function to call from a
+ * click handler.
+ *
+ * The timer is what this exists for: it has to be reset on each copy, so a
+ * second click doesn't revert the label early, and cleared on unmount, so a
+ * panel closed mid-flash leaves nothing pending. `CopyToClipboardButton` and the
+ * feature-details `Formatter` had each grown a version of it, one of them
+ * without the unmount cleanup.
+ */
+export declare function useCopyToClipboard(durationMs?: number): {
+    copied: boolean;
+    copy: (text: string) => Promise<void>;
+};

package/esm/ui/useCopyToClipboard.js

@@ -0,0 +1,41 @@
+import { useEffect, useRef, useState } from 'react';
+import copyToClipboard from '../util/copyToClipboard.js';
+/**
+ * Copy to the clipboard and briefly flash a "copied" confirmation. Returns the
+ * flag to render that confirmation from and the copy function to call from a
+ * click handler.
+ *
+ * The timer is what this exists for: it has to be reset on each copy, so a
+ * second click doesn't revert the label early, and cleared on unmount, so a
+ * panel closed mid-flash leaves nothing pending. `CopyToClipboardButton` and the
+ * feature-details `Formatter` had each grown a version of it, one of them
+ * without the unmount cleanup.
+ */
+export function useCopyToClipboard(durationMs = 1000) {
+    const [copied, setCopied] = useState(false);
+    const timerRef = useRef(undefined);
+    useEffect(() => () => {
+        clearTimeout(timerRef.current);
+    }, []);
+    return {
+        copied,
+        // plain text only: a rich `text/html` copy is a menu action with no label to
+        // flash, so it calls copyToClipboard directly.
+        // The confirmation is flashed only once the write has actually landed —
+        // there is no session to notify from an inline button, so a failure leaves
+        // the label alone rather than claiming a copy that didn't happen.
+        copy: async (text) => {
+            try {
+                await copyToClipboard(text);
+                setCopied(true);
+                clearTimeout(timerRef.current);
+                timerRef.current = setTimeout(() => {
+                    setCopied(false);
+                }, durationMs);
+            }
+            catch (e) {
+                console.error(e);
+            }
+        },
+    };
+}

package/esm/ui/useExportSvgPreference.d.ts

@@ -0,0 +1 @@
+export declare function useExportSvgPreference<T>(key: string, val: T): readonly [T, (value: T | ((val: T) => T)) => void];

package/esm/ui/useExportSvgPreference.js

@@ -0,0 +1,4 @@
+import { useLocalStorage } from '../util/hooks.js';
+export function useExportSvgPreference(key, val) {
+    return useLocalStorage(`svg-${key}`, val);
+}

package/esm/ui/useMouseTracking.d.ts

@@ -0,0 +1,71 @@
+export interface MouseState {
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+}
+/**
+ * The pointer position, as something to read rather than something you hold.
+ *
+ * `useMouseTracking` hands this back instead of the position itself, and that
+ * indirection is the entire point — see there.
+ */
+export interface MouseTracker {
+    subscribe: (onStoreChange: () => void) => () => void;
+    getSnapshot: () => MouseState | undefined;
+}
+export declare const ClearTrackedPointerProvider: import("react").Provider<() => void>;
+export declare function useClearTrackedPointer(): () => void;
+/**
+ * Container-relative mouse position for the overlays that follow the pointer
+ * (`Crosshairs`, tooltips), coalesced to one update per frame.
+ *
+ * The position is measured against the box of whatever element the handlers are
+ * bound to, which is what the overlays are positioned in — off `currentTarget`,
+ * so there is no ref to pass and no way to bind the two to different elements.
+ * A display that also hit-tests takes `onMove`, so its hit and its guides come
+ * off one measurement in one frame instead of two pointer paths that have to
+ * agree.
+ *
+ * **It returns a `mouseTracker` rather than the position, and that is the
+ * load-bearing part.** Its one caller is `DisplayChromeBase`, which owns the
+ * container the handlers bind to — so if the position were state here, every
+ * mouse move would re-render the chrome itself (re-running
+ * `useRenderingBackend`), the status container with a fresh inline `style`
+ * object, all three overlays, and only then the body that actually wanted the
+ * coordinate. That is a whole display's chrome repainting because the cursor
+ * moved a pixel over it; it cost a full document `Layout` plus three `Paint`s
+ * per mousemove on the wiggle displays, back when each display called this hook
+ * itself and every one of them had it.
+ *
+ * So the position is published instead, and whoever wants it calls
+ * `useMouseState(mouseTracker)` — from inside the chrome's body, where the
+ * overlays live. Re-rendering then starts at the component that reads it.
+ * Passing the tracker down a prop is free; passing `mouseState` down is the bug.
+ */
+export declare function useMouseTracking(onMove?: (state?: MouseState) => void): {
+    mouseTracker: MouseTracker;
+    handleMouseMove: (event: React.MouseEvent) => void;
+    handleMouseLeave: () => void;
+};
+/**
+ * Read something derived from the tracked pointer, re-rendering only when the
+ * derived value changes.
+ *
+ * `useMouseState` renders once per frame the pointer moves, which is what a
+ * thing drawn *at* the cursor wants. A consumer that only asks a question of the
+ * position — "is the pointer inside this band?" — renders once per answer
+ * instead, because `useSyncExternalStore` compares snapshots and a boolean
+ * compares equal to the last one.
+ *
+ * The tracker is optional so a component can sit outside whatever bound the
+ * handlers (a highlight band rendered in a test, say) and read a pointer that is
+ * simply never there.
+ */
+export declare function useMouseSelector<T>(tracker: MouseTracker | undefined, selector: (state: MouseState | undefined) => T): T;
+/**
+ * Read the tracked pointer position. Call this in the component that draws the
+ * cursor-following thing, not in the one that bound the handlers — see
+ * `useMouseTracking`.
+ */
+export declare function useMouseState(tracker: MouseTracker): MouseState | undefined;