@genome-spy/core 0.68.0 → 0.69.0

package/dist/src/tooltip/tooltipContext.js

@@ -0,0 +1,543 @@
+/**
+ * @typedef {import("./tooltipHandler.js").TooltipContext} TooltipContext
+ * @typedef {import("./tooltipHandler.js").TooltipGenomicDisplayMode} TooltipGenomicDisplayMode
+ * @typedef {import("./tooltipHandler.js").TooltipRow} TooltipRow
+ */
+
+import { asArray } from "../utils/arrayUtils.js";
+import { flattenDatumRows } from "./flattenDatumRows.js";
+
+/** @type {Record<"x" | "y", "x2" | "y2">} */
+const SECONDARY_AXIS = {
+    x: "x2",
+    y: "y2",
+};
+
+/** @type {Set<string>} */
+const GENOMIC_MODES = new Set([
+    "auto",
+    "locus",
+    "interval",
+    "endpoints",
+    "disabled",
+]);
+
+/** @type {WeakMap<object, Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>>} */
+const linearizationMappingCache = new WeakMap();
+
+/**
+ * Creates a stable context object for tooltip handlers.
+ *
+ * @param {Record<string, any>} datum
+ * @param {import("../marks/mark.js").default} mark
+ * @param {import("./tooltipHandler.js").TooltipHandlerParams} [params]
+ * @returns {TooltipContext}
+ */
+export default function createTooltipContext(datum, mark, params) {
+    const mappingByLinearizedField = getLinearizationMappings(mark);
+
+    const xGenomic = buildGenomicRowsForAxis(
+        "x",
+        datum,
+        mark,
+        mappingByLinearizedField,
+        getConfiguredMode(params, "x")
+    );
+    const yGenomic = buildGenomicRowsForAxis(
+        "y",
+        datum,
+        mark,
+        mappingByLinearizedField,
+        getConfiguredMode(params, "y")
+    );
+
+    const useAxisPrefixes =
+        xGenomic.rows.length > 0 && yGenomic.rows.length > 0;
+
+    /** @type {TooltipRow[]} */
+    const genomicRows = [
+        ...(useAxisPrefixes
+            ? prefixGenomicRows("x", xGenomic.rows)
+            : xGenomic.rows),
+        ...(useAxisPrefixes
+            ? prefixGenomicRows("y", yGenomic.rows)
+            : yGenomic.rows),
+    ];
+
+    /** @type {Set<string>} */
+    const hiddenRowKeys = new Set();
+    for (const axisGenomic of [xGenomic, yGenomic]) {
+        for (const field of axisGenomic.usedLinearizedFields) {
+            const mapping = mappingByLinearizedField.get(field);
+            if (!mapping || mapping.ambiguous) {
+                continue;
+            }
+
+            const verified = verifyLinearizationMapping(
+                datum,
+                field,
+                mapping,
+                mark
+            );
+            if (verified) {
+                hiddenRowKeys.add(mapping.chrom);
+                hiddenRowKeys.add(mapping.pos);
+            }
+        }
+    }
+
+    return {
+        hiddenRowKeys: [...hiddenRowKeys],
+        genomicRows,
+        flattenDatumRows: () => flattenDatumRows(datum),
+        formatGenomicLocus: (axis, continuousPos) =>
+            formatGenomicLocus(mark, axis, continuousPos),
+        formatGenomicInterval: (axis, interval) =>
+            formatGenomicInterval(mark, axis, interval),
+    };
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @returns {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>}
+ */
+function getLinearizationMappings(mark) {
+    const cached = linearizationMappingCache.get(mark);
+    if (cached) {
+        return cached;
+    }
+
+    const collected = collectLinearizationMappings(mark);
+    linearizationMappingCache.set(mark, collected);
+    return collected;
+}
+
+/**
+ * @param {"x" | "y"} axis
+ * @param {TooltipRow[]} rows
+ * @returns {TooltipRow[]}
+ */
+function prefixGenomicRows(axis, rows) {
+    const axisPrefix = axis.toUpperCase() + " ";
+    return rows.map((row) => ({
+        key: axisPrefix + row.key,
+        value: row.value,
+    }));
+}
+
+/**
+ * @param {"x" | "y"} axis
+ * @param {Record<string, any>} datum
+ * @param {import("../marks/mark.js").default} mark
+ * @param {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} mappingByLinearizedField
+ * @param {TooltipGenomicDisplayMode} mode
+ * @returns {{ rows: TooltipRow[], usedLinearizedFields: Set<string> }}
+ */
+function buildGenomicRowsForAxis(
+    axis,
+    datum,
+    mark,
+    mappingByLinearizedField,
+    mode
+) {
+    /** @type {Set<string>} */
+    const usedLinearizedFields = new Set();
+
+    if (mode === "disabled") {
+        return {
+            rows: [],
+            usedLinearizedFields,
+        };
+    }
+
+    const primary = readLocusCoordinate(mark, axis, datum);
+    if (!primary) {
+        return {
+            rows: [],
+            usedLinearizedFields,
+        };
+    }
+    if (primary.field) {
+        usedLinearizedFields.add(primary.field);
+    }
+
+    const secondary = readLocusCoordinate(mark, SECONDARY_AXIS[axis], datum);
+    if (secondary?.field) {
+        usedLinearizedFields.add(secondary.field);
+    }
+
+    /** @type {TooltipGenomicDisplayMode} */
+    const effectiveMode =
+        mode === "auto"
+            ? resolveAutoMode(primary, secondary, mappingByLinearizedField)
+            : mode;
+
+    if (effectiveMode === "endpoints" && secondary) {
+        const [endpoint1, endpoint2] = orderEndpointsByFieldHints(
+            primary,
+            secondary,
+            mappingByLinearizedField
+        );
+
+        return {
+            rows: [
+                {
+                    key: "Endpoint 1",
+                    value:
+                        formatGenomicLocus(mark, axis, endpoint1.value) ??
+                        String(endpoint1.value),
+                },
+                {
+                    key: "Endpoint 2",
+                    value:
+                        formatGenomicLocus(mark, axis, endpoint2.value) ??
+                        String(endpoint2.value),
+                },
+            ],
+            usedLinearizedFields,
+        };
+    }
+
+    if (effectiveMode === "interval" && secondary) {
+        return {
+            rows: [
+                {
+                    key: "Interval",
+                    value:
+                        formatGenomicInterval(mark, axis, [
+                            primary.value,
+                            secondary.value,
+                        ]) ?? primary.value + " - " + secondary.value,
+                },
+            ],
+            usedLinearizedFields,
+        };
+    }
+
+    return {
+        rows: [
+            {
+                key: "Coordinate",
+                value:
+                    formatGenomicLocus(mark, axis, primary.value) ??
+                    String(primary.value),
+            },
+        ],
+        usedLinearizedFields,
+    };
+}
+
+/**
+ * @param {{ field?: string }} primary
+ * @param {{ field?: string } | undefined} secondary
+ * @param {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} mappingByLinearizedField
+ * @returns {TooltipGenomicDisplayMode}
+ */
+function resolveAutoMode(primary, secondary, mappingByLinearizedField) {
+    if (!secondary) {
+        return "locus";
+    }
+
+    const primaryGroup = getMappingGroup(
+        primary.field,
+        mappingByLinearizedField
+    );
+    const secondaryGroup = getMappingGroup(
+        secondary.field,
+        mappingByLinearizedField
+    );
+
+    if (primaryGroup && secondaryGroup && primaryGroup !== secondaryGroup) {
+        return "endpoints";
+    }
+
+    // Default to interval when grouping cannot be inferred.
+    return "interval";
+}
+
+/**
+ * @param {string | undefined} field
+ * @param {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} mappingByLinearizedField
+ */
+function getMappingGroup(field, mappingByLinearizedField) {
+    const mapping = field ? mappingByLinearizedField.get(field) : undefined;
+    return mapping && !mapping.ambiguous ? mapping.groupId : undefined;
+}
+
+/**
+ * Heuristically preserves endpoint numbering from source fields. If one
+ * endpoint is recognized as "2" (or the other as "1"), swap display order.
+ *
+ * @param {{ value: number, field?: string }} primary
+ * @param {{ value: number, field?: string }} secondary
+ * @param {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} mappingByLinearizedField
+ */
+function orderEndpointsByFieldHints(
+    primary,
+    secondary,
+    mappingByLinearizedField
+) {
+    const firstHint = inferEndpointOrdinal(
+        primary.field,
+        mappingByLinearizedField
+    );
+    const secondHint = inferEndpointOrdinal(
+        secondary.field,
+        mappingByLinearizedField
+    );
+
+    if (firstHint === 2 && secondHint !== 2) {
+        return [secondary, primary];
+    }
+
+    if (secondHint === 1 && firstHint !== 1) {
+        return [secondary, primary];
+    }
+
+    if (firstHint === 2 && secondHint === 1) {
+        return [secondary, primary];
+    }
+
+    return [primary, secondary];
+}
+
+/**
+ * @param {string | undefined} linearizedField
+ * @param {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} mappingByLinearizedField
+ * @returns {1 | 2 | undefined}
+ */
+function inferEndpointOrdinal(linearizedField, mappingByLinearizedField) {
+    const mapping = linearizedField
+        ? mappingByLinearizedField.get(linearizedField)
+        : undefined;
+    /** @type {(string | undefined)[]} */
+    const candidates = [mapping?.pos, mapping?.chrom, linearizedField];
+
+    /** @type {1 | 2 | undefined} */
+    let ordinal;
+    for (const candidate of candidates) {
+        const detected = detectEndpointOrdinal(candidate);
+        if (detected === undefined) {
+            continue;
+        }
+        if (ordinal === undefined) {
+            ordinal = detected;
+        } else if (ordinal !== detected) {
+            return undefined;
+        }
+    }
+
+    return ordinal;
+}
+
+/**
+ * @param {string | undefined} fieldName
+ * @returns {1 | 2 | undefined}
+ */
+function detectEndpointOrdinal(fieldName) {
+    if (!fieldName) {
+        return undefined;
+    }
+
+    const normalized = fieldName.toLowerCase();
+
+    const trailing = normalized.match(/(?:^|[^0-9])(1|2)$/);
+    if (trailing) {
+        return trailing[1] === "1" ? 1 : 2;
+    }
+
+    const word = normalized.match(/(?:^|[_-])(first|second)(?:[_-]|$)/);
+    if (word) {
+        return word[1] === "first" ? 1 : 2;
+    }
+
+    return undefined;
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @param {"x" | "x2" | "y" | "y2"} channel
+ * @param {Record<string, any>} datum
+ * @returns {{ value: number, field?: string } | undefined}
+ */
+function readLocusCoordinate(mark, channel, datum) {
+    const encoder = mark.encoders?.[channel];
+    if (encoder?.scale?.type !== "locus") {
+        return;
+    }
+
+    const accessor = encoder.dataAccessor;
+    if (!accessor) {
+        return;
+    }
+
+    const value = +accessor(datum);
+    if (!Number.isFinite(value)) {
+        return;
+    }
+
+    return {
+        value,
+        field: accessor.fields?.length === 1 ? accessor.fields[0] : undefined,
+    };
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @returns {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>}
+ */
+function collectLinearizationMappings(mark) {
+    /** @type {Map<string, {groupId: string, chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean}>} */
+    const mappingByField = new Map();
+
+    let group = 0;
+    const collector = mark.unitView?.getCollector?.();
+    let current = collector?.parent;
+    while (current) {
+        const params = /** @type {any} */ (current).params;
+        if (params?.type === "linearizeGenomicCoordinate") {
+            const as = asArray(params.as);
+            const pos = asArray(params.pos);
+            const offsets = normalizeOffsets(params.offset, pos.length);
+            const groupId = "g" + group++;
+            const channel = params.channel === "y" ? "y" : "x";
+
+            for (let i = 0; i < as.length; i++) {
+                if (i >= pos.length) {
+                    continue;
+                }
+
+                const existing = mappingByField.get(as[i]);
+                if (existing) {
+                    existing.ambiguous = true;
+                } else {
+                    mappingByField.set(as[i], {
+                        groupId,
+                        chrom: params.chrom,
+                        pos: pos[i],
+                        offset: offsets[i],
+                        channel,
+                        ambiguous: false,
+                    });
+                }
+            }
+        }
+        current = current.parent;
+    }
+
+    return mappingByField;
+}
+
+/**
+ * @param {number | number[] | undefined} offset
+ * @param {number} count
+ * @returns {number[]}
+ */
+function normalizeOffsets(offset, count) {
+    const offsets = asArray(offset);
+
+    if (offsets.length === 0) {
+        return new Array(count).fill(0);
+    }
+    if (offsets.length === 1) {
+        return new Array(count).fill(offsets[0]);
+    }
+    if (offsets.length === count) {
+        return offsets;
+    }
+
+    return new Array(count).fill(0);
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @param {"x" | "y"} axis
+ * @param {number} continuousPos
+ * @returns {string | undefined}
+ */
+function formatGenomicLocus(mark, axis, continuousPos) {
+    const genome = getGenome(mark, axis);
+    return genome?.formatLocus(continuousPos);
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @param {"x" | "y"} axis
+ * @param {[number, number]} interval
+ * @returns {string | undefined}
+ */
+function formatGenomicInterval(mark, axis, interval) {
+    const genome = getGenome(mark, axis);
+    return genome?.formatInterval(interval);
+}
+
+/**
+ * @param {import("../marks/mark.js").default} mark
+ * @param {"x" | "y"} axis
+ */
+function getGenome(mark, axis) {
+    const scale = mark.encoders?.[axis]?.scale;
+    return scale?.type === "locus" && "genome" in scale
+        ? scale.genome()
+        : undefined;
+}
+
+/**
+ * @param {import("./tooltipHandler.js").TooltipHandlerParams | undefined} params
+ * @param {"x" | "y"} axis
+ * @returns {TooltipGenomicDisplayMode}
+ */
+function getConfiguredMode(params, axis) {
+    const configured = params?.genomicCoordinates?.[axis];
+    const mode =
+        typeof configured === "string"
+            ? configured
+            : (configured?.mode ?? "auto");
+
+    if (!GENOMIC_MODES.has(mode)) {
+        throw new Error(
+            'Unknown genomic coordinate display mode: "' + mode + '"'
+        );
+    }
+
+    return /** @type {TooltipGenomicDisplayMode} */ (mode);
+}
+
+/**
+ * @param {Record<string, any>} datum
+ * @param {string} linearizedField
+ * @param {{ chrom: string, pos: string, offset: number, channel: "x" | "y", ambiguous: boolean }} mapping
+ * @param {import("../marks/mark.js").default} mark
+ */
+function verifyLinearizationMapping(datum, linearizedField, mapping, mark) {
+    // TODO: This picks a genome by transform channel. In mixed-axis or
+    // mixed-assembly cases, verify against both active genomic axes.
+    const genome = getGenome(mark, mapping.channel);
+    if (!genome) {
+        return false;
+    }
+
+    const chrom = datum[mapping.chrom];
+    const pos = datum[mapping.pos];
+    const linearized = datum[linearizedField];
+
+    if (chrom === undefined || pos === undefined || linearized === undefined) {
+        return false;
+    }
+
+    const numericPos = +pos;
+    const numericLinearized = +linearized;
+
+    if (!Number.isFinite(numericPos) || !Number.isFinite(numericLinearized)) {
+        return false;
+    }
+
+    let expected;
+    try {
+        expected = genome.toContinuous(chrom, numericPos - mapping.offset);
+    } catch (_error) {
+        return false;
+    }
+
+    return Math.abs(expected - numericLinearized) < 1e-6;
+}

package/dist/src/tooltip/tooltipContext.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tooltipContext.test.d.ts.map

package/dist/src/tooltip/tooltipContext.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltipContext.test.d.ts","sourceRoot":"","sources":["../../../src/tooltip/tooltipContext.test.js"],"names":[],"mappings":""}

package/dist/src/tooltip/tooltipHandler.d.ts

@@ -1,9 +1,48 @@
 import { TemplateResult } from "lit";
 import Mark from "../marks/mark.js";
+export type TooltipGenomicDisplayMode = "auto" | "locus" | "interval" | "endpoints" | "disabled";
+export interface TooltipGenomicAxisConfig {
+    mode?: TooltipGenomicDisplayMode;
+}
+export interface TooltipHandlerParams {
+    genomicCoordinates?: Partial<Record<"x" | "y", TooltipGenomicAxisConfig | TooltipGenomicDisplayMode>>;
+    [key: string]: any;
+}
+export interface TooltipRow {
+    key: string;
+    value: any;
+}
+export interface TooltipContext {
+    /**
+     * A list of row keys that should be hidden from the default tooltip table.
+     */
+    hiddenRowKeys?: string[];
+    /**
+     * Derived genomic rows to render before raw data rows.
+     */
+    genomicRows?: TooltipRow[];
+    /**
+     * Utility for flattening datum fields into tooltip rows.
+     */
+    flattenDatumRows?: () => TooltipRow[];
+    /**
+     * Utility for formatting a continuous genomic position.
+     */
+    formatGenomicLocus?: (axis: "x" | "y", continuousPos: number) => string | undefined;
+    /**
+     * Utility for formatting a continuous genomic interval.
+     */
+    formatGenomicInterval?: (axis: "x" | "y", interval: [number, number]) => string | undefined;
+}
 /**
  * Converts a datum to tooltip (HTMLElement or lit's TemplateResult).
+ *
+ * TODO: `mark` leaks internals. Keep it for compatibility in this major
+ * version and replace with a stable tooltip context in the next major.
  */
 export type TooltipHandler = (datum: Record<string, any>, mark: Mark, 
 /** Optional parameters from the view specification */
-params?: Record<string, any>) => Promise<string | TemplateResult | HTMLElement>;
+params?: TooltipHandlerParams, 
+/** Optional precomputed context from GenomeSpy internals */
+context?: TooltipContext) => Promise<string | TemplateResult | HTMLElement>;
 //# sourceMappingURL=tooltipHandler.d.ts.map

package/dist/src/tooltip/tooltipHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltipHandler.d.ts","sourceRoot":"","sources":["../../../src/tooltip/tooltipHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,IAAI,MAAM,kBAAkB,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,IAAI,EAAE,IAAI;AACV,sDAAsD;AACtD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,OAAO,CAAC,MAAM,GAAG,cAAc,GAAG,WAAW,CAAC,CAAC"}
+{"version":3,"file":"tooltipHandler.d.ts","sourceRoot":"","sources":["../../../src/tooltip/tooltipHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,IAAI,MAAM,kBAAkB,CAAC;AAEpC,MAAM,MAAM,yBAAyB,GAC/B,MAAM,GACN,OAAO,GACP,UAAU,GACV,WAAW,GACX,UAAU,CAAC;AAEjB,MAAM,WAAW,wBAAwB;IACrC,IAAI,CAAC,EAAE,yBAAyB,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACjC,kBAAkB,CAAC,EAAE,OAAO,CACxB,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE,wBAAwB,GAAG,yBAAyB,CAAC,CAC1E,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,GAAG,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAE3B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,UAAU,EAAE,CAAC;IAEtC;;OAEG;IACH,kBAAkB,CAAC,EAAE,CACjB,IAAI,EAAE,GAAG,GAAG,GAAG,EACf,aAAa,EAAE,MAAM,KACpB,MAAM,GAAG,SAAS,CAAC;IAExB;;OAEG;IACH,qBAAqB,CAAC,EAAE,CACpB,IAAI,EAAE,GAAG,GAAG,GAAG,EACf,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,KACzB,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,IAAI,EAAE,IAAI;AACV,sDAAsD;AACtD,MAAM,CAAC,EAAE,oBAAoB;AAC7B,4DAA4D;AAC5D,OAAO,CAAC,EAAE,cAAc,KACvB,OAAO,CAAC,MAAM,GAAG,cAAc,GAAG,WAAW,CAAC,CAAC"}

package/dist/src/tooltip/tooltipHandler.ts

@@ -1,12 +1,73 @@
 import { TemplateResult } from "lit";
 import Mark from "../marks/mark.js";
 
+export type TooltipGenomicDisplayMode =
+    | "auto"
+    | "locus"
+    | "interval"
+    | "endpoints"
+    | "disabled";
+
+export interface TooltipGenomicAxisConfig {
+    mode?: TooltipGenomicDisplayMode;
+}
+
+export interface TooltipHandlerParams {
+    genomicCoordinates?: Partial<
+        Record<"x" | "y", TooltipGenomicAxisConfig | TooltipGenomicDisplayMode>
+    >;
+    [key: string]: any;
+}
+
+export interface TooltipRow {
+    key: string;
+    value: any;
+}
+
+export interface TooltipContext {
+    /**
+     * A list of row keys that should be hidden from the default tooltip table.
+     */
+    hiddenRowKeys?: string[];
+
+    /**
+     * Derived genomic rows to render before raw data rows.
+     */
+    genomicRows?: TooltipRow[];
+
+    /**
+     * Utility for flattening datum fields into tooltip rows.
+     */
+    flattenDatumRows?: () => TooltipRow[];
+
+    /**
+     * Utility for formatting a continuous genomic position.
+     */
+    formatGenomicLocus?: (
+        axis: "x" | "y",
+        continuousPos: number
+    ) => string | undefined;
+
+    /**
+     * Utility for formatting a continuous genomic interval.
+     */
+    formatGenomicInterval?: (
+        axis: "x" | "y",
+        interval: [number, number]
+    ) => string | undefined;
+}
+
 /**
  * Converts a datum to tooltip (HTMLElement or lit's TemplateResult).
+ *
+ * TODO: `mark` leaks internals. Keep it for compatibility in this major
+ * version and replace with a stable tooltip context in the next major.
  */
 export type TooltipHandler = (
     datum: Record<string, any>,
     mark: Mark,
     /** Optional parameters from the view specification */
-    params?: Record<string, any>
+    params?: TooltipHandlerParams,
+    /** Optional precomputed context from GenomeSpy internals */
+    context?: TooltipContext
 ) => Promise<string | TemplateResult | HTMLElement>;

package/dist/src/types/encoder.d.ts

@@ -25,7 +25,7 @@ import { ScaleLocus } from "../genome/scaleLocus.js";
 import { ScaleIndex } from "../genome/scaleIndex.js";
 import { Scalar } from "../spec/channel.js";
 import { Datum } from "../data/flowNode.js";
-import { ExprRefFunction } from "../view/paramMediator.js";
+import { ExprRefFunction } from "../paramRuntime/types.js";
 
 export interface Accessor<T = Scalar> {
     (datum: Datum): T;