loom-browser 0.0.6 → 0.0.7

package/dist/loom-react.esm.js

@@ -1074,6 +1074,47 @@ class DOMCanvasProvider {
 /** Default CanvasProvider for browser environments. */
 const defaultCanvasProvider = new DOMCanvasProvider();
 
+/**
+ * WorkerDataSource — main-thread proxy that forwards DataSource.fetch() to a worker.
+ *
+ * Implements DataSource<F> so it's a drop-in replacement for any direct DataSource.
+ * The real DataSource instance lives inside a web worker; this proxy communicates
+ * via the DataSourceWorkerProvider.
+ *
+ * Non-serializable configuration (like chromosome name resolver functions) is
+ * stored locally on the proxy and applied before forwarding to the worker.
+ *
+ * Layer 1 (Data + Layout): no DOM.
+ */
+class WorkerDataSource {
+    constructor(provider, instanceId) {
+        this.provider = provider;
+        this.instanceId = instanceId;
+    }
+    async fetch(locus, bpPerPixel, signal) {
+        // Resolve chromosome name locally (functions can't cross postMessage boundary)
+        const resolvedLocus = this.resolver
+            ? { ...locus, chr: this.resolver(locus.chr) }
+            : locus;
+        return this.provider.fetch(this.instanceId, resolvedLocus, bpPerPixel, signal);
+    }
+    /**
+     * Set a chromosome name resolver. Stored locally — the proxy resolves
+     * chromosome names before forwarding the locus to the worker.
+     */
+    setChromNameResolver(resolver) {
+        this.resolver = resolver;
+    }
+    /** Forward cumulative offsets to the worker-resident DataSource. */
+    setCumulativeOffsets(offsets) {
+        this.provider.configure(this.instanceId, 'setCumulativeOffsets', offsets);
+    }
+    /** Forward window function change to the worker-resident DataSource. */
+    setWindowFunction(wf) {
+        this.provider.configure(this.instanceId, 'setWindowFunction', wf);
+    }
+}
+
 /**
  * Unified RenderTheme system — shadcn-style palette-driven theming.
  *
@@ -2212,6 +2253,9 @@ function createCachedSequence(provider) {
             currentQuery = null;
             return interval;
         });
+        // Clear stale currentQuery on failure (e.g. abort) so subsequent
+        // requests don't keep reusing the rejected promise via dedup.
+        promise.catch(() => { currentQuery = null; });
         currentQuery = { interval: queryLocus, promise };
         return promise;
     }
@@ -2447,6 +2491,14 @@ class BaseTrackCanvas {
     hitTest(_x, _y) {
         return [];
     }
+    /**
+     * Return feature bounding rectangles for the current render state.
+     * Used by SVG overlay system for hover/click interactivity.
+     * Default: empty (no overlay). Subclasses override for interactive tracks.
+     */
+    getFeatureRects() {
+        return [];
+    }
     /**
      * Return context menu items for a right-click at canvas-relative coordinates.
      * Default: undefined (no track-specific items). Subclasses override.
@@ -2568,6 +2620,47 @@ class BaseTrackCanvas {
     }
 }
 
+/**
+ * Shared track name overlay label — renders a horizontal label in the top-left
+ * corner of a track canvas with a semi-transparent background pill.
+ *
+ * Used by wig, annotation, and interaction tracks for consistent labeling.
+ * Layer 2 (Track Canvases): uses canvas API, no DOM.
+ */
+/**
+ * Render a track name as a horizontal overlay in the top-left corner.
+ * Draws a semi-transparent background pill behind the text for readability.
+ */
+function renderTrackNameLabel(ctx, options, pixelHeight) {
+    var _a, _b;
+    if (pixelHeight < 12)
+        return;
+    const pad = 4;
+    const vPad = 2;
+    const hPad = 4;
+    ctx.font = 'normal 10px sans-serif';
+    ctx.textBaseline = 'top';
+    ctx.textAlign = 'left';
+    const topOffset = pad + ((_a = options.topOffset) !== null && _a !== void 0 ? _a : 0);
+    const metrics = ctx.measureText(options.name);
+    const w = metrics.width + hPad * 2;
+    const h = ((_b = metrics.actualBoundingBoxDescent) !== null && _b !== void 0 ? _b : 10) + vPad * 2;
+    // Semi-transparent background
+    ctx.fillStyle = options.background;
+    ctx.globalAlpha = 0.75;
+    ctx.fillRect(pad, topOffset, w, h);
+    ctx.globalAlpha = 1.0;
+    // Border — use labelColor at reduced opacity for theme awareness
+    ctx.strokeStyle = options.labelColor;
+    ctx.globalAlpha = 0.3;
+    ctx.lineWidth = 0.5;
+    ctx.strokeRect(pad, topOffset, w, h);
+    ctx.globalAlpha = 1.0;
+    // Text
+    ctx.fillStyle = options.labelColor;
+    ctx.fillText(options.name, pad + hPad, topOffset + vPad);
+}
+
 /**
  * Dynamic sequence (dynseq) renderer for wig tracks.
  *
@@ -2950,50 +3043,30 @@ function renderDataRangeLabels(ctx, config, pixelHeight) {
 }
 // ─── Track name overlay label ────────────────────────────────────────────────
 /**
- * Render the track name as an igv.js-style overlay in the top-left corner.
- * Draws a semi-transparent background pill behind the text for readability.
- * When data range labels are also visible, positions below the max label.
+ * Wig-specific track name label: computes topOffset to clear data range labels,
+ * then delegates to the shared renderTrackNameLabel().
  */
-function renderTrackNameLabel(ctx, config, pixelHeight) {
-    var _a, _b;
+function renderWigTrackNameLabel(ctx, config, pixelHeight) {
+    var _a;
     if (!config.trackName)
         return;
-    if (pixelHeight < 12)
-        return;
-    const pad = 4;
-    const vPad = 2;
-    const hPad = 4;
-    ctx.font = 'normal 10px sans-serif';
-    ctx.textBaseline = 'top';
-    ctx.textAlign = 'left';
     // Compute vertical offset — push below data range max label when visible
-    let topOffset = pad;
+    let topOffset = 0;
     if (config.showDataRange) {
+        const vPad = 2;
         ctx.save();
         ctx.font = config.labelFont;
         const maxLabel = prettyPrint(config.flipAxis ? config.dataRange.min : config.dataRange.max);
         const maxH = ((_a = ctx.measureText(maxLabel).actualBoundingBoxDescent) !== null && _a !== void 0 ? _a : 10) + vPad * 2;
         ctx.restore();
-        ctx.font = 'normal 10px sans-serif';
-        topOffset = pad + maxH + 2;
+        topOffset = maxH + 2;
     }
-    const metrics = ctx.measureText(config.trackName);
-    const w = metrics.width + hPad * 2;
-    const h = ((_b = metrics.actualBoundingBoxDescent) !== null && _b !== void 0 ? _b : 10) + vPad * 2;
-    // Semi-transparent background
-    ctx.fillStyle = config.background;
-    ctx.globalAlpha = 0.75;
-    ctx.fillRect(pad, topOffset, w, h);
-    ctx.globalAlpha = 1.0;
-    // Border — use labelColor at reduced opacity for theme awareness
-    ctx.strokeStyle = config.labelColor;
-    ctx.globalAlpha = 0.3;
-    ctx.lineWidth = 0.5;
-    ctx.strokeRect(pad, topOffset, w, h);
-    ctx.globalAlpha = 1.0;
-    // Text
-    ctx.fillStyle = config.labelColor;
-    ctx.fillText(config.trackName, pad + hPad, topOffset + vPad);
+    renderTrackNameLabel(ctx, {
+        name: config.trackName,
+        background: config.background,
+        labelColor: config.labelColor,
+        topOffset,
+    }, pixelHeight);
 }
 // ─── Baseline and guide lines ───────────────────────────────────────────────
 function renderBaseline(ctx, config, pixelWidth, pixelHeight) {
@@ -3068,7 +3141,7 @@ function renderWigTrack(ctx, features, config, rc) {
     renderBaseline(ctx, config, rc.pixelWidth, pixelHeight);
     renderGuideLines(ctx, config, rc.pixelWidth, yScale);
     renderDataRangeLabels(ctx, config, pixelHeight);
-    renderTrackNameLabel(ctx, config, pixelHeight);
+    renderWigTrackNameLabel(ctx, config, pixelHeight);
 }
 
 /**
@@ -3235,11 +3308,17 @@ class WigTrackCanvas extends BaseTrackCanvas {
         this._lastDataRange = null;
         /** Abort controller for in-flight sequence fetch. */
         this._seqAbort = null;
+        /** User-set config overrides, re-applied on theme change. */
+        this._userOverrides = {};
         this.type = 'wig';
         this.features = options.features;
         this.fixedHeight = options.height;
         this._name = options.name;
         this._sequenceProvider = options.sequenceProvider;
+        if (options.config)
+            this._userOverrides = { ...options.config };
+        if (options.background !== undefined)
+            this._userOverrides.background = options.background;
     }
     /** Set a callback invoked when the user changes the windowing function via context menu. */
     set onWindowFunctionChange(cb) {
@@ -3267,6 +3346,7 @@ class WigTrackCanvas extends BaseTrackCanvas {
     }
     /** Merge partial config and re-render. Triggers sequence fetch when switching to dynseq. */
     setConfig(config) {
+        Object.assign(this._userOverrides, config);
         const wasDynseq = this._config.graphType === 'dynseq';
         super.setConfig(config);
         if (!wasDynseq && this._config.graphType === 'dynseq') {
@@ -3336,8 +3416,16 @@ class WigTrackCanvas extends BaseTrackCanvas {
         return this.config.background;
     }
     doRender(ctx, _width, height, rc) {
-        if (this.features.length === 0)
+        if (this.features.length === 0) {
+            if (this._name) {
+                renderTrackNameLabel(ctx, {
+                    name: this._name,
+                    background: this.config.background,
+                    labelColor: this.config.labelColor,
+                }, height);
+            }
             return;
+        }
         // Apply value scaling (normalize then scaleFactor), matching igv.js getFeatures() order.
         // Creates a scaled copy to avoid mutating the original features array.
         const needsScaling = (this.config.normalizationFactor != null && this.config.normalizationFactor !== 1)
@@ -3365,14 +3453,14 @@ class WigTrackCanvas extends BaseTrackCanvas {
             this._config = { ...this._config, dataRange: autoRange };
         }
         this._lastDataRange = effectiveConfig.dataRange;
-        console.log('[wig doRender]', { logScale: effectiveConfig.logScale, autoscale: effectiveConfig.autoscale, flipAxis: effectiveConfig.flipAxis, dataRange: effectiveConfig.dataRange, featureCount: features.length });
         renderWigTrack(ctx, features, effectiveConfig, rc);
     }
     getAxisInfo() {
-        if (!this._lastDataRange)
+        var _a;
+        if (!this._name && !this._lastDataRange)
             return undefined;
         return {
-            dataRange: this._lastDataRange,
+            dataRange: (_a = this._lastDataRange) !== null && _a !== void 0 ? _a : undefined,
             color: typeof this.config.color === 'string' ? this.config.color : undefined,
             label: this._name,
             flipAxis: this.config.flipAxis || undefined,
@@ -3450,7 +3538,7 @@ class WigTrackCanvas extends BaseTrackCanvas {
     }
     setTheme(theme) {
         const dataRange = this._config.dataRange;
-        this._config = { ...resolveWigConfig(theme), dataRange };
+        this._config = { ...resolveWigConfig(theme), ...this._userOverrides, dataRange };
         this.render();
     }
     serializeConfig(theme) {
@@ -3858,7 +3946,10 @@ function getUtrColorForFeature(feature, config) {
  * Features should already have `.row` assigned (via `pack()`).
  * The canvas should be sized and cleared before calling this.
  */
-function renderAnnotationTrack(ctx, features, config, rc) {
+function renderAnnotationTrack(ctx, features, config, rc, 
+/** Optional track name label overlay (top-left corner). */
+trackLabel) {
+    var _a;
     const rowLastLabelX = {};
     for (const feature of features) {
         if (feature.row === undefined)
@@ -3870,6 +3961,9 @@ function renderAnnotationTrack(ctx, features, config, rc) {
             continue;
         renderSingleFeature(ctx, feature, config, rc, rowLastLabelX);
     }
+    if (trackLabel) {
+        renderTrackNameLabel(ctx, trackLabel, ctx.canvas.height / ((_a = globalThis.devicePixelRatio) !== null && _a !== void 0 ? _a : 1));
+    }
 }
 
 /**
@@ -3890,6 +3984,8 @@ class AnnotationTrackCanvas extends BaseTrackCanvas {
         const theme = resolveTheme(options.theme);
         const config = resolveAnnotationConfig(theme, options.config);
         super(canvas, options.locus, config, options.canvasProvider);
+        /** User-set config overrides, re-applied on theme change. */
+        this._userOverrides = {};
         /** Most recently packed features, available after render(). */
         this.packedFeatures = [];
         /** Whether packedFeatures was pre-computed by async worker (skip sync pack in computeHeight). */
@@ -3899,30 +3995,20 @@ class AnnotationTrackCanvas extends BaseTrackCanvas {
         this.fixedHeight = options.height;
         this.background = (_a = options.background) !== null && _a !== void 0 ? _a : theme.palette.background;
         this._name = options.name;
-        this.workerProvider = options.workerProvider;
+        if (options.config)
+            this._userOverrides = { ...options.config };
+        this._userBackground = options.background;
     }
-    /** Update features and re-render. Dispatches async pack when workerProvider is set. */
+    /** Set or clear the fixed pixel height. When set, overrides auto-computed row-based height. */
+    setFixedHeight(height) {
+        this.fixedHeight = height;
+        this.render();
+    }
+    /** Update features and re-render. */
     setFeatures(features) {
         this.features = features;
-        if (this.workerProvider) {
-            // Deep-copy for worker, then render when done
-            const copies = features.map(f => ({ ...f }));
-            this.workerProvider.execute({ task: 'pack', features: copies })
-                .then(packed => {
-                this.packedFeatures = packed;
-                this.packedReady = true;
-                this.render();
-            })
-                .catch(() => {
-                // Fallback: render will use synchronous packing
-                this.packedReady = false;
-                this.render();
-            });
-        }
-        else {
-            this.packedReady = false;
-            this.render();
-        }
+        this.packedReady = false;
+        this.render();
     }
     computeHeight(_width) {
         var _a;
@@ -3941,10 +4027,20 @@ class AnnotationTrackCanvas extends BaseTrackCanvas {
         return this.background;
     }
     doRender(ctx, _width, _height, rc) {
-        renderAnnotationTrack(ctx, this.packedFeatures, this.config, rc);
+        var _a;
+        // Ensure label background matches track background so clearRect doesn't
+        // punch transparent holes (which show the underlying CSS background).
+        const config = this.config.labelBackground
+            ? this.config
+            : { ...this.config, labelBackground: this.background };
+        renderAnnotationTrack(ctx, this.packedFeatures, config, rc, this._name ? {
+            name: this._name,
+            background: this.background,
+            labelColor: (_a = config.labelColor) !== null && _a !== void 0 ? _a : '#333',
+        } : undefined);
     }
     getAxisInfo() {
-        return this._name ? { label: this._name } : undefined;
+        return undefined;
     }
     getContextMenuItems(_x, _y) {
         const modes = ['EXPANDED', 'SQUISHED', 'COLLAPSED'];
@@ -3958,6 +4054,43 @@ class AnnotationTrackCanvas extends BaseTrackCanvas {
                 })),
             }];
     }
+    getFeatureRects() {
+        var _a;
+        if (this.packedFeatures.length === 0)
+            return [];
+        const width = this._canvas.clientWidth;
+        if (width === 0)
+            return [];
+        const bpPerPixel = (this._locus.end - this._locus.start) / width;
+        const bpStart = this._locus.start;
+        const config = this._config;
+        const rowHeight = config.displayMode === 'SQUISHED'
+            ? config.squishedRowHeight
+            : config.expandedRowHeight;
+        const featureH = config.displayMode === 'SQUISHED'
+            ? config.featureHeight / 2
+            : config.featureHeight;
+        const rects = [];
+        for (const f of this.packedFeatures) {
+            if (f.row === undefined)
+                continue;
+            const pxStart = (f.start - bpStart) / bpPerPixel;
+            const pxEnd = (f.end - bpStart) / bpPerPixel;
+            if (pxEnd < 0 || pxStart > width)
+                continue;
+            const py = config.margin + rowHeight * f.row;
+            let px = pxStart;
+            let pw = pxEnd - pxStart;
+            if (pw < 3) {
+                px -= (3 - pw) / 2;
+                pw = 3;
+            }
+            // Resolve feature color (same logic as annotationRenderer's getColorForFeature)
+            const color = (_a = f.color) !== null && _a !== void 0 ? _a : (config.altColor && f.strand === '-' ? config.altColor : config.color);
+            rects.push({ feature: f, x: px, y: py, width: pw, height: featureH, color });
+        }
+        return rects;
+    }
     hitTest(x, y) {
         if (this.packedFeatures.length === 0)
             return [];
@@ -3982,9 +4115,14 @@ class AnnotationTrackCanvas extends BaseTrackCanvas {
         }
         return results;
     }
+    setConfig(config) {
+        Object.assign(this._userOverrides, config);
+        super.setConfig(config);
+    }
     setTheme(theme) {
-        this._config = resolveAnnotationConfig(theme);
-        this.background = theme.palette.background;
+        var _a;
+        this._config = resolveAnnotationConfig(theme, this._userOverrides);
+        this.background = (_a = this._userBackground) !== null && _a !== void 0 ? _a : theme.palette.background;
         this.render();
     }
     serializeConfig(theme) {
@@ -4747,7 +4885,7 @@ function featureToWig(f, chr, wf) {
  * Thin wrapper around @gmod/bbi BigWig that preserves the legacy API.
  */
 class BigWigReader {
-    constructor(url, _workerProvider) {
+    constructor(url) {
         this.bw = getGmodReader(url);
     }
     async loadHeader(signal) {
@@ -4818,7 +4956,7 @@ class BigWigReader {
  */
 async function fetchBigWigFeatures(url, locus, options = {}) {
     var _a;
-    const reader = new BigWigReader(url, options.workerProvider);
+    const reader = new BigWigReader(url);
     return reader.readFeatures(locus.chr, locus.start, locus.end, options.bpPerPixel, (_a = options.windowFunction) !== null && _a !== void 0 ? _a : 'mean', options.signal);
 }
 /**
@@ -4827,15 +4965,14 @@ async function fetchBigWigFeatures(url, locus, options = {}) {
  */
 async function fetchBigWigWGFeatures(url, chromNames, bpPerPixel, options = {}) {
     var _a;
-    const reader = new BigWigReader(url, options.workerProvider);
+    const reader = new BigWigReader(url);
     return reader.readWGFeatures(chromNames, bpPerPixel, (_a = options.windowFunction) !== null && _a !== void 0 ? _a : 'mean', options.signal);
 }
 
 class BigWigDataSource {
-    constructor(url, windowFunction = 'mean', workerProvider) {
+    constructor(url, windowFunction = 'mean') {
         this.url = url;
         this._windowFunction = windowFunction;
-        this.workerProvider = workerProvider;
     }
     get windowFunction() { return this._windowFunction; }
     /** Update the window function for future fetches. */
@@ -4861,20 +4998,10 @@ class BigWigDataSource {
         const features = await fetchBigWigFeatures(this.url, resolvedLocus, {
             bpPerPixel,
             windowFunction: this._windowFunction,
-            workerProvider: this.workerProvider,
             signal,
         });
         // Summarize to pixel resolution (matching igv.js wigTrack.getFeatures())
         if (bpPerPixel > 1 && this._windowFunction !== 'none' && features.length > 0) {
-            if (this.workerProvider) {
-                return this.workerProvider.execute({
-                    task: 'summarize',
-                    features,
-                    startBP: locus.start,
-                    bpPerPixel,
-                    windowFunction: this._windowFunction,
-                });
-            }
             return summarizeWigData(features, locus.start, bpPerPixel, this._windowFunction);
         }
         return features;
@@ -4885,7 +5012,7 @@ class BigWigDataSource {
      */
     async fetchWG(bpPerPixel, signal) {
         const offsets = this._cumulativeOffsets;
-        const features = await fetchBigWigWGFeatures(this.url, offsets.chromosomeNames, bpPerPixel, { windowFunction: this._windowFunction, workerProvider: this.workerProvider, signal });
+        const features = await fetchBigWigWGFeatures(this.url, offsets.chromosomeNames, bpPerPixel, { windowFunction: this._windowFunction, signal });
         // Transform to genome-wide coordinates
         const wgFeatures = [];
         for (const f of features) {
@@ -4902,15 +5029,6 @@ class BigWigDataSource {
         wgFeatures.sort((a, b) => a.start - b.start);
         // Summarize at genome-wide scale
         if (bpPerPixel > 1 && this._windowFunction !== 'none' && wgFeatures.length > 0) {
-            if (this.workerProvider) {
-                return this.workerProvider.execute({
-                    task: 'summarize',
-                    features: wgFeatures,
-                    startBP: 0,
-                    bpPerPixel,
-                    windowFunction: this._windowFunction,
-                });
-            }
             return summarizeWigData(wgFeatures, 0, bpPerPixel, this._windowFunction);
         }
         return wgFeatures;
@@ -5864,11 +5982,10 @@ function getReader(url) {
     return reader;
 }
 class GtxDataSource {
-    constructor(url, experimentId, windowFunction = 'mean', workerProvider) {
+    constructor(url, experimentId, windowFunction = 'mean') {
         this.url = url;
         this.experimentId = experimentId;
         this._windowFunction = windowFunction;
-        this.workerProvider = workerProvider;
         this.reader = getReader(url);
     }
     get windowFunction() { return this._windowFunction; }
@@ -5901,15 +6018,6 @@ class GtxDataSource {
         const features = await coordinator.request(this.experimentId, resolvedLocus, bpPerPixel, signal);
         // Summarize to pixel resolution
         if (bpPerPixel > 1 && this._windowFunction !== 'none' && features.length > 0) {
-            if (this.workerProvider) {
-                return this.workerProvider.execute({
-                    task: 'summarize',
-                    features,
-                    startBP: locus.start,
-                    bpPerPixel,
-                    windowFunction: this._windowFunction,
-                });
-            }
             return summarizeWigData(features, locus.start, bpPerPixel, this._windowFunction);
         }
         return features;
@@ -5936,15 +6044,6 @@ class GtxDataSource {
         wgFeatures.sort((a, b) => a.start - b.start);
         // Summarize at genome-wide scale
         if (bpPerPixel > 1 && this._windowFunction !== 'none' && wgFeatures.length > 0) {
-            if (this.workerProvider) {
-                return this.workerProvider.execute({
-                    task: 'summarize',
-                    features: wgFeatures,
-                    startBP: 0,
-                    bpPerPixel,
-                    windowFunction: this._windowFunction,
-                });
-            }
             return summarizeWigData(wgFeatures, 0, bpPerPixel, this._windowFunction);
         }
         return wgFeatures;
@@ -8019,7 +8118,6 @@ class TextFeatureSource {
         var _a, _b;
         this.allFeaturesLoaded = false;
         this.url = config.url;
-        this.workerProvider = config.workerProvider;
         // Detect format
         const detected = (_a = config.format) !== null && _a !== void 0 ? _a : inferFormatFromPath(config.url);
         this.format = detected !== null && detected !== void 0 ? detected : 'bed';
@@ -8037,7 +8135,7 @@ class TextFeatureSource {
         // Set up TabixReader for indexed files
         if (this._indexed) {
             const indexUrl = (_b = config.indexURL) !== null && _b !== void 0 ? _b : inferIndexURL(config.url);
-            this.tabixReader = new TabixReader(config.url, { indexUrl, workerProvider: this.workerProvider });
+            this.tabixReader = new TabixReader(config.url, { indexUrl });
         }
     }
     /** Whether this source is indexed (queryable by region). */
@@ -8123,19 +8221,11 @@ class TextFeatureSource {
         const lines = text.split(/\r?\n/);
         // Parse header
         this.header = parseHeader(lines, this.format);
-        // Parse features (offload to worker for large files)
-        const features = (this.workerProvider
-            ? await this.workerProvider.execute({
-                task: 'parseFeatures',
-                lines,
-                format: this.format,
-                header: this.header,
-                assembleGFF: this.assembleGFF,
-            })
-            : parseFeatures(lines, this.format, {
-                header: this.header,
-                assembleGFF: this.assembleGFF,
-            }));
+        // Parse features
+        const features = parseFeatures(lines, this.format, {
+            header: this.header,
+            assembleGFF: this.assembleGFF,
+        });
         // Sort by chr then start
         features.sort((a, b) => {
             if (a.chr === b.chr)
@@ -8316,18 +8406,26 @@ class MemoryDataSource {
  * Stateless: all state is passed in, no side effects beyond canvas drawing
  * and attaching drawState to features for hit-testing.
  */
-function renderInteractionTrack(ctx, features, config, rc) {
+function renderInteractionTrack(ctx, features, config, rc, 
+/** Optional track name label overlay (top-left corner). */
+trackLabel) {
     // Clear background
     ctx.fillStyle = config.background;
     ctx.fillRect(0, 0, rc.pixelWidth, config.height);
-    if (!features || features.length === 0)
+    if (!features || features.length === 0) {
+        if (trackLabel)
+            renderTrackNameLabel(ctx, trackLabel, config.height);
         return;
+    }
     if (config.displayMode === 'proportional') {
         drawProportional(ctx, features, config, rc);
     }
     else {
         drawNested(ctx, features, config, rc);
     }
+    if (trackLabel) {
+        renderTrackNameLabel(ctx, trackLabel, config.height);
+    }
 }
 // ─── Nested arcs ─────────────────────────────────────────────────────────────
 function drawNested(ctx, features, config, rc) {
@@ -8631,7 +8729,11 @@ class InteractionTrackCanvas extends BaseTrackCanvas {
         return this.config.background;
     }
     doRender(ctx, _width, _height, rc) {
-        renderInteractionTrack(ctx, this.features, this._config, rc);
+        renderInteractionTrack(ctx, this.features, this._config, rc, this._name ? {
+            name: this._name,
+            background: this._config.background,
+            labelColor: '#333',
+        } : undefined);
     }
     /** Hit-test: find features at canvas-relative pixel coordinates. */
     hitTest(x, y) {
@@ -8851,12 +8953,12 @@ function knownTrackTypes() {
     return types;
 }
 // ─── Built-in data source helpers ────────────────────────────────────────────
-function createDataSource(config, workerProvider) {
+function createDataSource(config) {
     switch (config.type) {
         case 'bigwig':
-            return new BigWigDataSource(config.url, config.windowFunction, workerProvider);
+            return new BigWigDataSource(config.url, config.windowFunction);
         case 'gtx':
-            return new GtxDataSource(config.url, config.experimentId, config.windowFunction, workerProvider);
+            return new GtxDataSource(config.url, config.experimentId, config.windowFunction);
         case 'ucsc':
             return new GeneDataSource({ genome: config.genome, track: config.track });
         case 'text':
@@ -8865,7 +8967,6 @@ function createDataSource(config, workerProvider) {
                 format: config.format,
                 indexURL: config.indexURL,
                 indexed: config.indexed,
-                workerProvider,
             });
         case 'memory':
             // Memory data sources are created directly with features by the caller.
@@ -8889,7 +8990,7 @@ function createWigTrack(trackConfig, ctx) {
     let dataSourceConfig = null;
     if (config.dataSource) {
         dataSourceConfig = config.dataSource;
-        dataSource = createDataSource(config.dataSource, ctx.workerProvider);
+        dataSource = createDataSource(config.dataSource);
     }
     return { track, dataSource, dataSourceConfig, name: config.name, order: config.order };
 }
@@ -8902,13 +9003,12 @@ function createAnnotationTrack(trackConfig, ctx) {
         config: config.config,
         theme: ctx.theme,
         canvasProvider: ctx.canvasProvider,
-        workerProvider: ctx.workerProvider,
     });
     let dataSource = null;
     let dataSourceConfig = null;
     if (config.dataSource) {
         dataSourceConfig = config.dataSource;
-        dataSource = createDataSource(config.dataSource, ctx.workerProvider);
+        dataSource = createDataSource(config.dataSource);
     }
     return { track, dataSource, dataSourceConfig, name: config.name, order: config.order };
 }
@@ -8954,7 +9054,7 @@ function createInteractionTrack(trackConfig, ctx) {
     let dataSourceConfig = null;
     if (config.dataSource) {
         dataSourceConfig = config.dataSource;
-        dataSource = createDataSource(config.dataSource, ctx.workerProvider);
+        dataSource = createDataSource(config.dataSource);
     }
     return { track, dataSource, dataSourceConfig, name: config.name, order: config.order };
 }
@@ -9000,7 +9100,6 @@ function createTrackFromConfig(trackConfig, locus, options = {}) {
     return creator(trackConfig, {
         locus,
         canvasProvider: (_a = options.canvasProvider) !== null && _a !== void 0 ? _a : defaultCanvasProvider,
-        workerProvider: options.workerProvider,
         theme: options.theme,
         sequenceProvider: options.sequenceProvider,
     });
@@ -9384,6 +9483,15 @@ function selectTracks(tracks, selector) {
  *   browser.setLocus({ chr: 'chr17', start: 7670000, end: 7680000 })
  *   browser.dispose()
  */
+/** Duck-type check: does this object implement DataSourceWorkerProvider? */
+function isDataSourceWorkerProvider(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const o = obj;
+    return typeof o.create === 'function'
+        && typeof o.fetch === 'function'
+        && typeof o.destroy === 'function';
+}
 const BrowserEvent = {
     LocusChange: 'locuschange',
     TrackAdded: 'trackadded',
@@ -9407,6 +9515,25 @@ let nextTrackId = 0;
 function generateTrackId(type) {
     return `${type !== null && type !== void 0 ? type : 'track'}-${nextTrackId++}`;
 }
+/**
+ * Track type sort priority — adapts the igv.js `reorderTracks()` two-level
+ * sort (js/browser.ts:1153-1172) to a single numeric priority.
+ *
+ * igv.js pins ideogram (1), ruler (2) to the top, then sorts by `track.order`.
+ * Loom uses positive priority for top-pinned tracks, 0 for user data tracks,
+ * and negative values to push tracks (e.g., gene reference) to the bottom.
+ *
+ * Each ManagedTrack can also set `order` which is added to the type priority,
+ * giving callers fine-grained control (e.g., addGeneTrack sets order=-1).
+ */
+const DEFAULT_TRACK_TYPE_PRIORITY = {
+    ruler: 2,
+    sequence: 1,
+};
+function trackTypePriority(type) {
+    var _a;
+    return (_a = DEFAULT_TRACK_TYPE_PRIORITY[type]) !== null && _a !== void 0 ? _a : 0;
+}
 class HeadlessGenomeBrowser {
     get theme() { return this._theme; }
     get locus() { return this._locus; }
@@ -9423,6 +9550,10 @@ class HeadlessGenomeBrowser {
         this.roiSets = [];
         /** Inflight fetch promises keyed by (cacheKey + fetchRegion + bpPerPixel) for deduplication. */
         this.inflightFetches = new Map();
+        /** Timer for debouncing data loads during rapid zoom/pan. */
+        this.loadDebounceTimer = null;
+        /** When true, sortTracks() is a no-op. Used for batch track additions (e.g. loadSession). */
+        this._deferSort = false;
         this.events = new EventEmitter();
         this.genome = options.genome === null ? undefined : ((_a = options.genome) !== null && _a !== void 0 ? _a : hg38Genome);
         this.chromSizes = (_b = this.genome) === null || _b === void 0 ? void 0 : _b.chromSizes;
@@ -9432,12 +9563,33 @@ class HeadlessGenomeBrowser {
         this._viewportWidth = (_e = options.viewportWidth) !== null && _e !== void 0 ? _e : 0;
         this.canvasProvider = (_f = options.canvasProvider) !== null && _f !== void 0 ? _f : defaultCanvasProvider;
         this.workerProvider = options.workerProvider;
+        // Auto-detect: if workerProvider also implements DataSourceWorkerProvider, use it for both
+        this.dataSourceWorkerProvider = isDataSourceWorkerProvider(options.workerProvider)
+            ? options.workerProvider : undefined;
         this.popupProvider = (_g = options.popupProvider) !== null && _g !== void 0 ? _g : undefined;
         this.contextMenuProvider = (_h = options.contextMenuProvider) !== null && _h !== void 0 ? _h : undefined;
         this._theme = resolveTheme(options.theme);
         if (options.stateProjection)
             this._state = options.stateProjection;
     }
+    /**
+     * Create a WorkerDataSource proxy for worker-eligible configs, or return null
+     * if dataSourceWorkerProvider is not set. Handles create + chrom alias + offsets wiring.
+     */
+    createWorkerDataSource(config) {
+        if (!this.dataSourceWorkerProvider)
+            return null;
+        const instanceId = `ds-${nextTrackId}-${Date.now()}`;
+        this.dataSourceWorkerProvider.create(instanceId, config);
+        const proxy = new WorkerDataSource(this.dataSourceWorkerProvider, instanceId);
+        if (this.genome) {
+            proxy.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+        }
+        if (this.cumulativeOffsets) {
+            proxy.setCumulativeOffsets(this.cumulativeOffsets);
+        }
+        return proxy;
+    }
     /** Clamp a locus to valid chromosome bounds. No-op if chromSizes is not set. */
     clamp(locus) {
         return this.chromSizes ? clampLocus(locus, this.chromSizes, this.cumulativeOffsets) : locus;
@@ -9461,7 +9613,7 @@ class HeadlessGenomeBrowser {
         this.loadAllTracksIfNeeded();
     }
     /** Add a track with an optional data source for automatic data management. */
-    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight) {
+    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight, order) {
         var _a;
         const id = generateTrackId(track.type);
         const mt = {
@@ -9472,8 +9624,10 @@ class HeadlessGenomeBrowser {
             cache: null,
             abortController: null,
             maxTrackHeight,
+            order,
         };
         this.managedTracks.push(mt);
+        this.sortTracks();
         track.setLocus(this._locus);
         this.events.emit(BrowserEvent.TrackAdded, { track });
         // Trigger initial data load if data source provided
@@ -9491,6 +9645,9 @@ class HeadlessGenomeBrowser {
             const mt = this.managedTracks[idx];
             if (mt.abortController)
                 mt.abortController.abort();
+            if (mt.dataSource instanceof WorkerDataSource && this.dataSourceWorkerProvider) {
+                this.dataSourceWorkerProvider.destroy(mt.dataSource.instanceId);
+            }
             this.managedTracks.splice(idx, 1);
             this.events.emit(BrowserEvent.TrackRemoved, { track: mt.track });
         }
@@ -9508,8 +9665,42 @@ class HeadlessGenomeBrowser {
             return;
         const [moved] = this.managedTracks.splice(fromIndex, 1);
         this.managedTracks.splice(clampedIndex, 0, moved);
+        this._assignOrderFromPosition();
         this.events.emit(BrowserEvent.TrackOrderChanged, { tracks: this.managedTracks.map(mt => mt.track) });
     }
+    /**
+     * Sort tracks by priority (descending): positive = top, 0 = middle, negative = bottom.
+     * Priority comes from the track type default + per-track `order` override.
+     * Within the same effective priority, insertion order is preserved (stable sort).
+     */
+    sortTracks() {
+        if (this._deferSort)
+            return;
+        this.managedTracks.sort((a, b) => {
+            var _a, _b;
+            const pa = ((_a = a.order) !== null && _a !== void 0 ? _a : 0) + trackTypePriority(a.track.type);
+            const pb = ((_b = b.order) !== null && _b !== void 0 ? _b : 0) + trackTypePriority(b.track.type);
+            return pb - pa; // descending: higher priority first
+        });
+        this.onTracksSorted();
+    }
+    /** Hook for subclasses to react to track order changes (e.g., DOM reorder). */
+    onTracksSorted() { }
+    /**
+     * Persist current array positions into mt.order so future sorts preserve
+     * manual reordering. Uses descending values (top track = highest) scaled
+     * above the type-priority range so explicit order dominates.
+     */
+    _assignOrderFromPosition() {
+        const n = this.managedTracks.length;
+        for (let i = 0; i < n; i++) {
+            this.managedTracks[i].order = (n - i) * 10;
+        }
+    }
+    /** Find the ManagedTrack entry for a given track canvas. */
+    findMT(track) {
+        return this.managedTracks.find(mt => mt.track === track);
+    }
     /** Get the current track order. */
     getTrackOrder() {
         return this.managedTracks.map(mt => mt.track);
@@ -9574,7 +9765,7 @@ class HeadlessGenomeBrowser {
         for (const mt of this.managedTracks) {
             mt.track.setLocus(this._locus);
         }
-        this.loadAllTracksIfNeeded();
+        this.debouncedLoad();
         this.events.emit(BrowserEvent.LocusChange, { locus: this._locus });
     }
     /**
@@ -9819,7 +10010,8 @@ class HeadlessGenomeBrowser {
                 serialized.order = mt.order;
             if (mt.metadata)
                 serialized.metadata = mt.metadata;
-            if (mt.dataSourceConfig && 'dataSource' in serialized) {
+            if (mt.dataSourceConfig
+                && serialized.type !== 'ruler' && serialized.type !== 'sequence') {
                 serialized.dataSource = mt.dataSourceConfig;
             }
             tracks.push(serialized);
@@ -9865,35 +10057,49 @@ class HeadlessGenomeBrowser {
         // Recreate tracks from session config
         const trackOptions = {
             canvasProvider: this.canvasProvider,
-            workerProvider: this.workerProvider,
             theme: options === null || options === void 0 ? void 0 : options.theme,
             sequenceProvider: this.sequenceProvider,
         };
-        for (const trackConfig of session.tracks) {
-            const created = createTrackFromSession(trackConfig, this._locus, trackOptions);
-            // Wire chromosome alias resolution for data sources that support it
-            if (this.genome && created.dataSource) {
-                if (created.dataSource instanceof BigWigDataSource || created.dataSource instanceof GtxDataSource) {
-                    created.dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+        this._deferSort = true;
+        try {
+            for (const trackConfig of session.tracks) {
+                const created = createTrackFromSession(trackConfig, this._locus, trackOptions);
+                // Use worker proxy for worker-eligible data sources
+                let dataSource = created.dataSource;
+                if (dataSource && created.dataSourceConfig && this.dataSourceWorkerProvider) {
+                    const dsType = created.dataSourceConfig.type;
+                    if (dsType === 'bigwig' || dsType === 'gtx' || dsType === 'text' || dsType === 'ucsc') {
+                        const workerDS = this.createWorkerDataSource(created.dataSourceConfig);
+                        if (workerDS)
+                            dataSource = workerDS;
+                    }
                 }
-                else if (created.dataSource instanceof TextFeatureSource) {
-                    created.dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-                    if (this.cumulativeOffsets) {
-                        created.dataSource.setCumulativeOffsets(this.cumulativeOffsets);
+                // Wire chromosome alias resolution for non-worker data sources
+                if (!this.dataSourceWorkerProvider && this.genome && dataSource) {
+                    if (dataSource instanceof BigWigDataSource || dataSource instanceof GtxDataSource) {
+                        dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+                    }
+                    else if (dataSource instanceof TextFeatureSource) {
+                        dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+                        if (this.cumulativeOffsets) {
+                            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
+                        }
                     }
                 }
+                this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, (_a = created.dataSourceConfig) !== null && _a !== void 0 ? _a : undefined, undefined, (_b = created.order) !== null && _b !== void 0 ? _b : undefined);
+                // Restore bookkeeping fields for round-trip serialization
+                const mt = this.findMT(created.track);
+                if (trackConfig.id)
+                    mt.id = trackConfig.id;
+                if (created.name)
+                    mt.name = created.name;
+                if (trackConfig.metadata)
+                    mt.metadata = trackConfig.metadata;
             }
-            this.addTrack(created.track, (_a = created.dataSource) !== null && _a !== void 0 ? _a : undefined, (_b = created.dataSourceConfig) !== null && _b !== void 0 ? _b : undefined);
-            // Restore bookkeeping fields for round-trip serialization
-            const mt = this.managedTracks[this.managedTracks.length - 1];
-            if (trackConfig.id)
-                mt.id = trackConfig.id;
-            if (created.name)
-                mt.name = created.name;
-            if (created.order != null)
-                mt.order = created.order;
-            if (trackConfig.metadata)
-                mt.metadata = trackConfig.metadata;
+        }
+        finally {
+            this._deferSort = false;
+            this.sortTracks();
         }
         // Restore ROI sets
         if (session.rois) {
@@ -9935,30 +10141,37 @@ class HeadlessGenomeBrowser {
         var _a, _b;
         const created = createTrackFromConfig(trackConfig, this._locus, {
             canvasProvider: this.canvasProvider,
-            workerProvider: this.workerProvider,
             theme: this.theme,
             sequenceProvider: this.sequenceProvider,
         });
-        // Wire chromosome alias resolution for data sources that support it
-        if (this.genome && created.dataSource) {
-            if (created.dataSource instanceof BigWigDataSource) {
-                created.dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-            }
-            else if (created.dataSource instanceof TextFeatureSource) {
-                created.dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+        // Use worker proxy for worker-eligible data sources
+        let dataSource = created.dataSource;
+        if (dataSource && created.dataSourceConfig && this.dataSourceWorkerProvider) {
+            const dsType = created.dataSourceConfig.type;
+            if (dsType === 'bigwig' || dsType === 'gtx' || dsType === 'text' || dsType === 'ucsc') {
+                const workerDS = this.createWorkerDataSource(created.dataSourceConfig);
+                if (workerDS)
+                    dataSource = workerDS;
+            }
+        }
+        // Wire chromosome alias resolution for non-worker data sources
+        if (!this.dataSourceWorkerProvider && this.genome && dataSource) {
+            if (dataSource instanceof BigWigDataSource) {
+                dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+            }
+            else if (dataSource instanceof TextFeatureSource) {
+                dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
                 if (this.cumulativeOffsets) {
-                    created.dataSource.setCumulativeOffsets(this.cumulativeOffsets);
+                    dataSource.setCumulativeOffsets(this.cumulativeOffsets);
                 }
             }
         }
-        this.addTrack(created.track, (_a = created.dataSource) !== null && _a !== void 0 ? _a : undefined, (_b = created.dataSourceConfig) !== null && _b !== void 0 ? _b : undefined);
-        const mt = this.managedTracks[this.managedTracks.length - 1];
+        this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, (_a = created.dataSourceConfig) !== null && _a !== void 0 ? _a : undefined, undefined, (_b = created.order) !== null && _b !== void 0 ? _b : undefined);
+        const mt = this.findMT(created.track);
         if (trackConfig.id)
             mt.id = trackConfig.id;
         if (created.name)
             mt.name = created.name;
-        if (created.order != null)
-            mt.order = created.order;
         if (trackConfig.metadata)
             mt.metadata = trackConfig.metadata;
         return created.track;
@@ -9994,22 +10207,29 @@ class HeadlessGenomeBrowser {
             name: options === null || options === void 0 ? void 0 : options.name,
             sequenceProvider: this.sequenceProvider,
         });
-        const dataSource = new BigWigDataSource(url, windowFunction, this.workerProvider);
-        if (this.cumulativeOffsets) {
-            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
-        }
-        if (this.genome) {
-            dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-        }
         const dataSourceConfig = {
             type: 'bigwig', url, windowFunction,
         };
+        const workerDS = this.createWorkerDataSource(dataSourceConfig);
+        const dataSource = workerDS !== null && workerDS !== void 0 ? workerDS : (() => {
+            const ds = new BigWigDataSource(url, windowFunction);
+            if (this.cumulativeOffsets)
+                ds.setCumulativeOffsets(this.cumulativeOffsets);
+            if (this.genome)
+                ds.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+            return ds;
+        })();
         this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         // Wire windowing function callback: update data source, invalidate cache, re-fetch
         track.onWindowFunctionChange = (wf) => {
-            dataSource.setWindowFunction(wf);
+            if (workerDS) {
+                workerDS.setWindowFunction(wf);
+            }
+            else {
+                dataSource.setWindowFunction(wf);
+            }
             const mt = this.managedTracks.find(m => m.track === track);
             if (mt) {
                 mt.cache = null;
@@ -10037,22 +10257,29 @@ class HeadlessGenomeBrowser {
             name: options.name,
             sequenceProvider: this.sequenceProvider,
         });
-        const dataSource = new GtxDataSource(url, options.experimentId, windowFunction, this.workerProvider);
-        if (this.cumulativeOffsets) {
-            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
-        }
-        if (this.genome) {
-            dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-        }
         const dataSourceConfig = {
             type: 'gtx', url, experimentId: options.experimentId, windowFunction,
         };
+        const workerDS = this.createWorkerDataSource(dataSourceConfig);
+        const dataSource = workerDS !== null && workerDS !== void 0 ? workerDS : (() => {
+            const ds = new GtxDataSource(url, options.experimentId, windowFunction);
+            if (this.cumulativeOffsets)
+                ds.setCumulativeOffsets(this.cumulativeOffsets);
+            if (this.genome)
+                ds.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+            return ds;
+        })();
         this.addTrack(track, dataSource, dataSourceConfig, options.maxTrackHeight);
         if (options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         // Wire windowing function callback
         track.onWindowFunctionChange = (wf) => {
-            dataSource.setWindowFunction(wf);
+            if (workerDS) {
+                workerDS.setWindowFunction(wf);
+            }
+            else {
+                dataSource.setWindowFunction(wf);
+            }
             const mt = this.managedTracks.find(m => m.track === track);
             if (mt) {
                 mt.cache = null;
@@ -10076,21 +10303,23 @@ class HeadlessGenomeBrowser {
             background: options === null || options === void 0 ? void 0 : options.background,
             theme: this.theme,
             canvasProvider: this.canvasProvider,
-            workerProvider: this.workerProvider,
             name: (_a = options === null || options === void 0 ? void 0 : options.name) !== null && _a !== void 0 ? _a : 'Genes',
         });
         const genome = options === null || options === void 0 ? void 0 : options.genome;
         const ucscTrack = options === null || options === void 0 ? void 0 : options.track;
-        const dataSource = new GeneDataSource({ genome, track: ucscTrack });
-        if (this.cumulativeOffsets) {
-            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
-        }
         const dataSourceConfig = {
             type: 'ucsc', genome, track: ucscTrack,
         };
-        this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight);
+        const workerDS = this.createWorkerDataSource(dataSourceConfig);
+        const dataSource = workerDS !== null && workerDS !== void 0 ? workerDS : (() => {
+            const ds = new GeneDataSource({ genome, track: ucscTrack });
+            if (this.cumulativeOffsets)
+                ds.setCumulativeOffsets(this.cumulativeOffsets);
+            return ds;
+        })();
+        this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight, -1);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         return track;
     }
     /** Add a BED/peak annotation track from a URL. Supports plain text and tabix-indexed files. */
@@ -10105,28 +10334,23 @@ class HeadlessGenomeBrowser {
             background: options === null || options === void 0 ? void 0 : options.background,
             theme: this.theme,
             canvasProvider: this.canvasProvider,
-            workerProvider: this.workerProvider,
             name: options === null || options === void 0 ? void 0 : options.name,
         });
-        const dataSource = new TextFeatureSource({
-            url,
-            format,
-            indexURL: options === null || options === void 0 ? void 0 : options.indexURL,
-            indexed: options === null || options === void 0 ? void 0 : options.indexed,
-            workerProvider: this.workerProvider,
-        });
-        if (this.genome) {
-            dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-        }
-        if (this.cumulativeOffsets) {
-            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
-        }
         const dataSourceConfig = {
             type: 'text', url, format, indexURL: options === null || options === void 0 ? void 0 : options.indexURL, indexed: options === null || options === void 0 ? void 0 : options.indexed,
         };
+        const workerDS = this.createWorkerDataSource(dataSourceConfig);
+        const dataSource = workerDS !== null && workerDS !== void 0 ? workerDS : (() => {
+            const ds = new TextFeatureSource({ url, format, indexURL: options === null || options === void 0 ? void 0 : options.indexURL, indexed: options === null || options === void 0 ? void 0 : options.indexed });
+            if (this.genome)
+                ds.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+            if (this.cumulativeOffsets)
+                ds.setCumulativeOffsets(this.cumulativeOffsets);
+            return ds;
+        })();
         this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         return track;
     }
     /** Add an interaction (arc/BEDPE) track from a URL. */
@@ -10142,25 +10366,21 @@ class HeadlessGenomeBrowser {
             canvasProvider: this.canvasProvider,
             name: options === null || options === void 0 ? void 0 : options.name,
         });
-        const dataSource = new TextFeatureSource({
-            url,
-            format,
-            indexURL: options === null || options === void 0 ? void 0 : options.indexURL,
-            indexed: options === null || options === void 0 ? void 0 : options.indexed,
-            workerProvider: this.workerProvider,
-        });
-        if (this.genome) {
-            dataSource.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
-        }
-        if (this.cumulativeOffsets) {
-            dataSource.setCumulativeOffsets(this.cumulativeOffsets);
-        }
         const dataSourceConfig = {
             type: 'text', url, format, indexURL: options === null || options === void 0 ? void 0 : options.indexURL, indexed: options === null || options === void 0 ? void 0 : options.indexed,
         };
+        const workerDS = this.createWorkerDataSource(dataSourceConfig);
+        const dataSource = workerDS !== null && workerDS !== void 0 ? workerDS : (() => {
+            const ds = new TextFeatureSource({ url, format, indexURL: options === null || options === void 0 ? void 0 : options.indexURL, indexed: options === null || options === void 0 ? void 0 : options.indexed });
+            if (this.genome)
+                ds.setChromNameResolver(alias => this.genome.getChromosomeName(alias));
+            if (this.cumulativeOffsets)
+                ds.setCumulativeOffsets(this.cumulativeOffsets);
+            return ds;
+        })();
         this.addTrack(track, dataSource, dataSourceConfig);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         return track;
     }
     /** Add a BigWig-style signal track backed by in-memory features (no URL required). */
@@ -10187,7 +10407,7 @@ class HeadlessGenomeBrowser {
         const dataSourceConfig = { type: 'memory' };
         this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         return track;
     }
     /** Add a BED/annotation track backed by in-memory features (no URL required). Features must include `chr`. */
@@ -10201,7 +10421,6 @@ class HeadlessGenomeBrowser {
             background: options === null || options === void 0 ? void 0 : options.background,
             theme: this.theme,
             canvasProvider: this.canvasProvider,
-            workerProvider: this.workerProvider,
             name: options === null || options === void 0 ? void 0 : options.name,
         });
         const dataSource = new MemoryDataSource(features);
@@ -10214,7 +10433,7 @@ class HeadlessGenomeBrowser {
         const dataSourceConfig = { type: 'memory' };
         this.addTrack(track, dataSource, dataSourceConfig, options === null || options === void 0 ? void 0 : options.maxTrackHeight);
         if (options === null || options === void 0 ? void 0 : options.metadata)
-            this.managedTracks[this.managedTracks.length - 1].metadata = options.metadata;
+            this.findMT(track).metadata = options.metadata;
         return track;
     }
     /** Add a DNA/RNA sequence track. Data fetching is handled automatically via the genome's sequence provider. */
@@ -10246,6 +10465,10 @@ class HeadlessGenomeBrowser {
         for (const mt of this.managedTracks) {
             if (mt.abortController)
                 mt.abortController.abort();
+            // Destroy worker-resident data sources
+            if (mt.dataSource instanceof WorkerDataSource && this.dataSourceWorkerProvider) {
+                this.dataSourceWorkerProvider.destroy(mt.dataSource.instanceId);
+            }
         }
         this.managedTracks = [];
         this.roiSets = [];
@@ -10273,6 +10496,30 @@ class HeadlessGenomeBrowser {
         };
     }
     // ─── Data lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Debounced wrapper around loadAllTracksIfNeeded.
+     * During rapid zoom/pan, this coalesces multiple setLocus() calls into a
+     * single data fetch cycle after the interaction settles (100ms quiet period).
+     * Abort in-flight requests immediately so they don't race with the eventual fetch.
+     */
+    debouncedLoad() {
+        // Immediately abort stale in-flight requests so cancelled fetches
+        // don't resolve after the debounce fires with a new locus.
+        for (const mt of this.managedTracks) {
+            if (mt.abortController) {
+                mt.abortController.abort();
+                mt.abortController = null;
+            }
+        }
+        this.inflightFetches.clear();
+        if (this.loadDebounceTimer !== null) {
+            clearTimeout(this.loadDebounceTimer);
+        }
+        this.loadDebounceTimer = setTimeout(() => {
+            this.loadDebounceTimer = null;
+            this.loadAllTracksIfNeeded();
+        }, 100);
+    }
     loadAllTracksIfNeeded() {
         // Clear stale inflight entries — navigation invalidates all pending fetches
         this.inflightFetches.clear();
@@ -10310,9 +10557,11 @@ class HeadlessGenomeBrowser {
         if (mt.cache && cacheCoversViewport(mt.cache, this._locus, bpPerPixel)) {
             return;
         }
-        // Cancel stale in-flight request for this track
+        // Cancel stale in-flight request for this track and clear any
+        // lingering error so it doesn't persist through the new fetch.
         if (mt.abortController)
             mt.abortController.abort();
+        mt.track.setError(null);
         const fetchRegion = bufferLocus(this._locus);
         const dsKey = mt.dataSourceConfig ? dataSourceCacheKey(mt.dataSourceConfig) : null;
         // Check if another track with the same data source already has a valid cache
@@ -10400,6 +10649,222 @@ class HeadlessGenomeBrowser {
     }
 }
 
+/**
+ * WebWorkerPool — single worker pool for both stateless tasks and stateful data sources.
+ *
+ * Implements both WorkerProvider (for CPU-intensive tasks like pack, summarize) and
+ * DataSourceWorkerProvider (for persistent DataSource instances in workers).
+ *
+ * Routing:
+ *   - Stateless tasks: round-robin across pool
+ *   - DataSource operations: sticky routing via URL hash (preserves reader caches)
+ *
+ * Usage:
+ *   const pool = new WebWorkerPool({
+ *       workerFactory: () => new Worker(new URL('./workerPoolScript.ts', import.meta.url)),
+ *       poolSize: 4,
+ *   })
+ *   const browser = new GenomeBrowser(container, { workerProvider: pool })
+ *   // browser auto-detects DataSourceWorkerProvider support
+ *   pool.dispose()
+ */
+// ─── Provider ────────────────────────────────────────────────────────────────
+class WebWorkerPool {
+    constructor(options) {
+        var _a;
+        // Stateless task tracking
+        this.nextId = 0;
+        this.nextWorker = 0;
+        this.pending = new Map();
+        // Stateful data source tracking
+        this.instanceToWorker = new Map();
+        this.pendingFetches = new Map();
+        this.nextFetchId = 0;
+        const count = Math.max(1, (_a = options.poolSize) !== null && _a !== void 0 ? _a : 1);
+        let createWorker;
+        if (options.workerFactory) {
+            createWorker = options.workerFactory;
+        }
+        else if (options.workerUrl) {
+            const url = options.workerUrl;
+            createWorker = () => new Worker(url, { type: 'module' });
+        }
+        else {
+            throw new Error('WebWorkerPoolOptions requires either workerUrl or workerFactory');
+        }
+        this.workers = [];
+        this.readyPromises = [];
+        for (let i = 0; i < count; i++) {
+            const worker = createWorker();
+            // Ready handshake
+            const readyPromise = new Promise((resolveReady) => {
+                const onReady = (e) => {
+                    if (e.data.type === 'ready') {
+                        resolveReady();
+                    }
+                };
+                worker.addEventListener('message', onReady, { once: true });
+            });
+            this.readyPromises.push(readyPromise);
+            worker.onmessage = (e) => {
+                const msg = e.data;
+                if (msg.type === 'ready')
+                    return; // handled by one-time listener
+                if (msg.type === 'taskResult') {
+                    const p = this.pending.get(msg.id);
+                    if (p) {
+                        this.pending.delete(msg.id);
+                        if (msg.error) {
+                            p.reject(new Error(msg.error));
+                        }
+                        else {
+                            p.resolve(msg.result);
+                        }
+                    }
+                }
+                else if (msg.type === 'fetchResult') {
+                    const p = this.pendingFetches.get(msg.fetchId);
+                    if (p) {
+                        this.pendingFetches.delete(msg.fetchId);
+                        p.resolve(msg.features);
+                    }
+                }
+                else if (msg.type === 'fetchError') {
+                    const p = this.pendingFetches.get(msg.fetchId);
+                    if (p) {
+                        this.pendingFetches.delete(msg.fetchId);
+                        if (msg.error === 'AbortError') {
+                            p.reject(new DOMException('Aborted', 'AbortError'));
+                        }
+                        else {
+                            p.reject(new Error(msg.error));
+                        }
+                    }
+                }
+            };
+            worker.onerror = (e) => {
+                const error = new Error(`Worker error: ${e.message}`);
+                for (const { reject } of this.pending.values())
+                    reject(error);
+                this.pending.clear();
+                for (const { reject } of this.pendingFetches.values())
+                    reject(error);
+                this.pendingFetches.clear();
+            };
+            this.workers.push(worker);
+        }
+    }
+    /** Number of workers in the pool. */
+    get poolSize() {
+        return this.workers.length;
+    }
+    // ─── WorkerProvider (stateless tasks) ────────────────────────────────────
+    execute(task, transfer) {
+        const id = this.nextId++;
+        const worker = this.workers[this.nextWorker % this.workers.length];
+        this.nextWorker++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            worker.postMessage({ type: 'task', id, task }, transfer !== null && transfer !== void 0 ? transfer : []);
+        });
+    }
+    // ─── DataSourceWorkerProvider (stateful data sources) ────────────────────
+    create(instanceId, config) {
+        const workerIdx = this.routeToWorker(config);
+        this.instanceToWorker.set(instanceId, workerIdx);
+        const worker = this.workers[workerIdx];
+        this.readyPromises[workerIdx].then(() => {
+            worker.postMessage({ type: 'create', instanceId, config });
+        });
+    }
+    async fetch(instanceId, locus, bpPerPixel, signal) {
+        const workerIdx = this.instanceToWorker.get(instanceId);
+        if (workerIdx === undefined) {
+            throw new Error(`No worker assigned for DataSource: ${instanceId}`);
+        }
+        await this.readyPromises[workerIdx];
+        const fetchId = this.nextFetchId++;
+        const worker = this.workers[workerIdx];
+        const onAbort = () => {
+            worker.postMessage({ type: 'cancel', fetchId });
+            const p = this.pendingFetches.get(fetchId);
+            if (p) {
+                this.pendingFetches.delete(fetchId);
+                p.reject(new DOMException('Aborted', 'AbortError'));
+            }
+        };
+        if (signal.aborted) {
+            throw new DOMException('Aborted', 'AbortError');
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            return await new Promise((resolve, reject) => {
+                this.pendingFetches.set(fetchId, {
+                    resolve: resolve,
+                    reject,
+                });
+                worker.postMessage({ type: 'fetch', instanceId, fetchId, locus, bpPerPixel });
+            });
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+    configure(instanceId, method, ...args) {
+        const workerIdx = this.instanceToWorker.get(instanceId);
+        if (workerIdx === undefined)
+            return;
+        const worker = this.workers[workerIdx];
+        this.readyPromises[workerIdx].then(() => {
+            worker.postMessage({ type: 'configure', instanceId, method, args });
+        });
+    }
+    destroy(instanceId) {
+        const workerIdx = this.instanceToWorker.get(instanceId);
+        if (workerIdx === undefined)
+            return;
+        const worker = this.workers[workerIdx];
+        worker.postMessage({ type: 'destroy', instanceId });
+        this.instanceToWorker.delete(instanceId);
+    }
+    // ─── Shared ──────────────────────────────────────────────────────────────
+    dispose() {
+        for (const worker of this.workers) {
+            worker.terminate();
+        }
+        for (const { reject } of this.pending.values()) {
+            reject(new Error('Worker terminated'));
+        }
+        this.pending.clear();
+        for (const { reject } of this.pendingFetches.values()) {
+            reject(new Error('Worker terminated'));
+        }
+        this.pendingFetches.clear();
+        this.instanceToWorker.clear();
+        this.workers = [];
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────
+    /**
+     * Sticky routing: deterministically assign a DataSourceConfig to a worker
+     * based on its URL. Preserves reader caches (BigWig headers, Tabix indices).
+     */
+    routeToWorker(config) {
+        const key = 'url' in config ? config.url : config.type;
+        return Math.abs(hashString(key)) % this.workers.length;
+    }
+}
+/** Simple string hash (djb2). */
+function hashString(s) {
+    let hash = 5381;
+    for (let i = 0; i < s.length; i++) {
+        hash = ((hash << 5) + hash + s.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+
 /**
  * CommandDispatcher — transport-agnostic command dispatch for HeadlessGenomeBrowser.
  *
@@ -10870,9 +11335,8 @@ class RemoteConnection {
  * These are pure canvas renderers — they take a 2D context, axis info, and
  * dimensions, and paint the axis. No DOM, no state, no side effects.
  *
- * Two variants:
- * - renderQuantitativeAxis: tick marks + data range labels for numeric tracks (wig)
- * - renderLabelAxis: centered rotated text label for annotation tracks (gene)
+ * renderQuantitativeAxis: background, color strip, track label, and
+ * tick marks + data range labels (when data is available) for numeric tracks.
  */
 /** Width of the color strip indicator on the right edge of the axis. */
 const COLOR_STRIP_WIDTH = 4;
@@ -10891,13 +11355,10 @@ function prettyPrintNumber(n) {
     return n.toExponential(1);
 }
 /**
- * Paint a quantitative axis with vertical line, tick marks, and data range labels.
+ * Paint a quantitative axis.
  *
- * Requires `info.dataRange` to be set. Renders:
- * - White background
- * - Color strip on right edge (if info.color is set)
- * - Vertical axis line with top/bottom ticks and labels (max/min)
- * - Middle tick at midpoint (if height > 60)
+ * Always renders: background and color strip (if info.color).
+ * When `info.dataRange` is set, also renders: vertical axis line, tick marks, and min/max/mid labels.
  */
 /** Transform a data value to log space, matching wigRenderer's computeYPixel logic. */
 function toLogValue(v) {
@@ -10921,19 +11382,10 @@ function valueToY(value, min, max, topY, bottomY, flip, logScale) {
 }
 function renderQuantitativeAxis(ctx, info, width, height) {
     var _a, _b, _c, _d;
-    if (!info.dataRange || height === 0)
+    if (height === 0)
         return;
-    const { min, max } = info.dataRange;
-    const flip = (_a = info.flipAxis) !== null && _a !== void 0 ? _a : false;
-    const logScale = (_b = info.logScale) !== null && _b !== void 0 ? _b : false;
-    const shim = 0.01;
-    const topY = shim * height;
-    const bottomY = (1.0 - shim) * height;
-    // When flipped, min is at top and max is at bottom (used by GWAS/QTL tracks)
-    const topValue = flip ? min : max;
-    const bottomValue = flip ? max : min;
-    const bg = (_c = info.backgroundColor) !== null && _c !== void 0 ? _c : 'white';
-    const fg = (_d = info.labelColor) !== null && _d !== void 0 ? _d : 'black';
+    const bg = (_a = info.backgroundColor) !== null && _a !== void 0 ? _a : 'white';
+    const fg = (_b = info.labelColor) !== null && _b !== void 0 ? _b : 'black';
     // Clear with background
     ctx.fillStyle = bg;
     ctx.fillRect(0, 0, width, height);
@@ -10942,6 +11394,9 @@ function renderQuantitativeAxis(ctx, info, width, height) {
         ctx.fillStyle = info.color;
         ctx.fillRect(width - COLOR_STRIP_WIDTH - 1, 0, COLOR_STRIP_WIDTH, height);
     }
+    const shim = 0.01;
+    const topY = shim * height;
+    const bottomY = (1.0 - shim) * height;
     const tickEnd = width - COLOR_STRIP_WIDTH - 3;
     const tickStart = tickEnd - 6;
     ctx.strokeStyle = fg;
@@ -10949,30 +11404,37 @@ function renderQuantitativeAxis(ctx, info, width, height) {
     ctx.font = 'normal 9px Arial';
     ctx.textAlign = 'right';
     ctx.lineWidth = 1;
-    // Vertical axis line
+    // Vertical axis line + top/bottom ticks (always drawn)
     ctx.beginPath();
     ctx.moveTo(tickEnd, topY);
     ctx.lineTo(tickEnd, bottomY);
     ctx.stroke();
-    // Top tick + label
     ctx.beginPath();
     ctx.moveTo(tickStart, topY);
     ctx.lineTo(tickEnd, topY);
     ctx.stroke();
-    ctx.textBaseline = 'top';
-    ctx.fillText(prettyPrintNumber(topValue), tickStart - 2, topY + 1);
-    // Bottom tick + label
     ctx.beginPath();
     ctx.moveTo(tickStart, bottomY);
     ctx.lineTo(tickEnd, bottomY);
     ctx.stroke();
+    // Data range labels — only when we have data
+    if (!info.dataRange)
+        return;
+    const { min, max } = info.dataRange;
+    const flip = (_c = info.flipAxis) !== null && _c !== void 0 ? _c : false;
+    const logScale = (_d = info.logScale) !== null && _d !== void 0 ? _d : false;
+    const topValue = flip ? min : max;
+    const bottomValue = flip ? max : min;
+    // Top label
+    ctx.textBaseline = 'top';
+    ctx.fillText(prettyPrintNumber(topValue), tickStart - 2, topY + 1);
+    // Bottom label
     ctx.textBaseline = 'bottom';
     ctx.fillText(prettyPrintNumber(bottomValue), tickStart - 2, bottomY - 1);
-    // Middle tick — linear midpoint or log-space midpoint
+    // Middle tick + label
     if (height > 60) {
         const midVal = logScale
             ? (() => {
-                // Midpoint in log space, converted back to data space
                 const logMid = (toLogValue(min) + toLogValue(max)) / 2;
                 return logMid >= 0 ? Math.pow(10, logMid) - 1 : -(Math.pow(10, -logMid) - 1);
             })()
@@ -10986,31 +11448,6 @@ function renderQuantitativeAxis(ctx, info, width, height) {
         ctx.fillText(prettyPrintNumber(midVal), tickStart + 1, midY);
     }
 }
-/**
- * Paint a label-only axis (e.g., gene track name).
- * Renders a vertically-rotated centered text label.
- */
-function renderLabelAxis(ctx, info, width, height) {
-    var _a, _b;
-    if (!info.label || height === 0)
-        return;
-    const bg = (_a = info.backgroundColor) !== null && _a !== void 0 ? _a : 'white';
-    const fg = (_b = info.labelColor) !== null && _b !== void 0 ? _b : '#333';
-    // Clear with background
-    ctx.fillStyle = bg;
-    ctx.fillRect(0, 0, width, height);
-    ctx.font = '10px sans-serif';
-    ctx.fillStyle = fg;
-    ctx.textAlign = 'center';
-    ctx.textBaseline = 'middle';
-    ctx.save();
-    ctx.translate(width / 2, height / 2);
-    ctx.rotate(-Math.PI / 2);
-    // Clip text to available height
-    const maxTextWidth = height - 10;
-    ctx.fillText(info.label, 0, 0, maxTextWidth);
-    ctx.restore();
-}
 
 /**
  * Common context menu item factories.
@@ -11145,6 +11582,157 @@ function roiContextMenuItems(roi, callbacks) {
     ];
 }
 
+/**
+ * SVG overlay for interactive feature highlighting.
+ *
+ * Positions transparent SVG `<rect>` elements on top of a track's canvas,
+ * providing native CSS `:hover` states and click targets without canvas repaints.
+ * Follows the same DOM-over-canvas pattern used by ROI overlays in GenomeBrowser.
+ *
+ * On hover, features get a tinted fill matching their own color plus a subtle
+ * glow/shadow effect, making the canvas-rendered feature feel highlighted.
+ */
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/** Default glow color when feature has no color. */
+const DEFAULT_GLOW_COLOR = 'rgb(0, 0, 150)';
+/** Padding (px) added around the feature rect for the glow area. */
+const GLOW_PADDING = 3;
+class SVGFeatureOverlay {
+    constructor(container) {
+        this.svg = document.createElementNS(SVG_NS, 'svg');
+        this.svg.classList.add('loom-feature-overlay');
+        this.svg.style.cssText = `
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            pointer-events: none;
+            overflow: visible;
+        `;
+        this.defs = document.createElementNS(SVG_NS, 'defs');
+        this.svg.appendChild(this.defs);
+        this.group = document.createElementNS(SVG_NS, 'g');
+        this.svg.appendChild(this.group);
+        container.style.position = 'relative';
+        container.appendChild(this.svg);
+    }
+    /** Rebuild SVG rects from feature geometry. */
+    update(rects) {
+        var _a;
+        this.group.textContent = '';
+        this.defs.textContent = '';
+        if (rects.length === 0 || rects.length > 500)
+            return;
+        const frag = document.createDocumentFragment();
+        for (let i = 0; i < rects.length; i++) {
+            const rect = rects[i];
+            const color = (_a = rect.color) !== null && _a !== void 0 ? _a : DEFAULT_GLOW_COLOR;
+            const filterId = `glow-${i}`;
+            this.defs.appendChild(this.createGlowFilter(filterId, color));
+            frag.appendChild(this.createRect(rect, filterId));
+        }
+        this.group.appendChild(frag);
+    }
+    /** Suppress pointer events on overlay rects (e.g., during drag). */
+    setSuppressed(suppressed) {
+        this.group.style.pointerEvents = suppressed ? 'none' : '';
+    }
+    dispose() {
+        this.svg.remove();
+    }
+    /** Create an SVG filter that produces a colored glow. */
+    createGlowFilter(id, color) {
+        const filter = document.createElementNS(SVG_NS, 'filter');
+        filter.setAttribute('id', id);
+        // Expand filter region to allow glow beyond rect bounds
+        filter.setAttribute('x', '-20%');
+        filter.setAttribute('y', '-40%');
+        filter.setAttribute('width', '140%');
+        filter.setAttribute('height', '180%');
+        // Flood with feature color
+        const flood = document.createElementNS(SVG_NS, 'feFlood');
+        flood.setAttribute('flood-color', color);
+        flood.setAttribute('flood-opacity', '0.4');
+        flood.setAttribute('result', 'color');
+        filter.appendChild(flood);
+        // Clip flood to rect shape
+        const composite = document.createElementNS(SVG_NS, 'feComposite');
+        composite.setAttribute('in', 'color');
+        composite.setAttribute('in2', 'SourceGraphic');
+        composite.setAttribute('operator', 'in');
+        composite.setAttribute('result', 'colored');
+        filter.appendChild(composite);
+        // Blur for glow
+        const blur = document.createElementNS(SVG_NS, 'feGaussianBlur');
+        blur.setAttribute('in', 'colored');
+        blur.setAttribute('stdDeviation', '3');
+        blur.setAttribute('result', 'glow');
+        filter.appendChild(blur);
+        // Layer: glow behind, then original rect on top
+        const merge = document.createElementNS(SVG_NS, 'feMerge');
+        const node1 = document.createElementNS(SVG_NS, 'feMergeNode');
+        node1.setAttribute('in', 'glow');
+        const node2 = document.createElementNS(SVG_NS, 'feMergeNode');
+        node2.setAttribute('in', 'SourceGraphic');
+        merge.appendChild(node1);
+        merge.appendChild(node2);
+        filter.appendChild(merge);
+        return filter;
+    }
+    createRect(rect, filterId) {
+        var _a;
+        const el = document.createElementNS(SVG_NS, 'rect');
+        // Expand the rect slightly so the hover target covers the full feature
+        // and the glow extends naturally beyond.
+        el.setAttribute('x', String(rect.x - GLOW_PADDING));
+        el.setAttribute('y', String(rect.y - GLOW_PADDING));
+        el.setAttribute('width', String(rect.width + GLOW_PADDING * 2));
+        el.setAttribute('height', String(rect.height + GLOW_PADDING * 2));
+        el.setAttribute('rx', '2');
+        const filterRef = `url(#${filterId})`;
+        const color = (_a = rect.color) !== null && _a !== void 0 ? _a : DEFAULT_GLOW_COLOR;
+        el.addEventListener('mouseenter', () => {
+            el.style.fill = toRGBA(color, 0.15);
+            el.style.filter = filterRef;
+        });
+        el.addEventListener('mouseleave', () => {
+            el.style.fill = 'transparent';
+            el.style.filter = '';
+        });
+        el.addEventListener('click', (e) => {
+            var _a;
+            e.stopPropagation();
+            (_a = this.onFeatureClick) === null || _a === void 0 ? void 0 : _a.call(this, rect, e);
+        });
+        return el;
+    }
+}
+/**
+ * Convert a CSS color string to rgba with the given alpha.
+ * Handles `rgb(r, g, b)`, `rgba(r, g, b, a)`, and hex formats.
+ */
+function toRGBA(color, alpha) {
+    // Already rgba — replace the alpha
+    const rgbaMatch = color.match(/^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/);
+    if (rgbaMatch) {
+        return `rgba(${rgbaMatch[1]}, ${rgbaMatch[2]}, ${rgbaMatch[3]}, ${alpha})`;
+    }
+    // Hex color
+    const hexMatch = color.match(/^#([0-9a-f]{3,8})$/i);
+    if (hexMatch) {
+        let hex = hexMatch[1];
+        if (hex.length === 3)
+            hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+        const r = parseInt(hex.slice(0, 2), 16);
+        const g = parseInt(hex.slice(2, 4), 16);
+        const b = parseInt(hex.slice(4, 6), 16);
+        return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    // Fallback: can't parse, just return with opacity
+    return color;
+}
+
 /**
  * DOM-attached GenomeBrowser — extends HeadlessGenomeBrowser with pointer events,
  * ResizeObserver, canvas stacking, and sweep-to-zoom.
@@ -11259,6 +11847,11 @@ function injectScrollStyles(container) {
     style.textContent = `
         .loom-track-scroll { scrollbar-width: none; }
         .loom-track-scroll::-webkit-scrollbar { display: none; }
+        .loom-feature-overlay rect {
+            fill: transparent;
+            pointer-events: auto;
+            cursor: pointer;
+        }
     `;
     if (root instanceof Document) {
         root.head.appendChild(style);
@@ -11269,7 +11862,7 @@ function injectScrollStyles(container) {
 }
 class GenomeBrowser extends HeadlessGenomeBrowser {
     constructor(container, options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         // Default-on: create providers unless explicitly set to null.
         const contextMenuProvider = options.contextMenuProvider === null
             ? undefined
@@ -11277,8 +11870,33 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         const popupProvider = options.popupProvider === null
             ? undefined
             : ((_b = options.popupProvider) !== null && _b !== void 0 ? _b : createDefaultPopupProvider());
+        // Auto-create worker pool when `workers` or `workerFactory` is set
+        // and no explicit workerProvider was passed.
+        let workerProvider = options.workerProvider;
+        let ownedProvider = null;
+        if (!workerProvider && (options.workers || options.workerFactory)) {
+            const poolSize = typeof options.workers === 'number'
+                ? options.workers
+                : Math.min((_c = navigator === null || navigator === void 0 ? void 0 : navigator.hardwareConcurrency) !== null && _c !== void 0 ? _c : 4, 4);
+            try {
+                ownedProvider = new WebWorkerPool({
+                    workerFactory: options.workerFactory,
+                    // webpackIgnore prevents webpack from statically resolving this URL at build time.
+                    // At runtime in the dist bundle, import.meta.url → dist/loom.esm.js,
+                    // and loom-worker.js is a sibling file in dist/.
+                    workerUrl: options.workerFactory ? undefined : new URL(/* webpackIgnore: true */ './loom-worker.js', import.meta.url),
+                    poolSize,
+                });
+                workerProvider = ownedProvider;
+            }
+            catch (_f) {
+                // Worker creation failed (CSP, bundler, etc.) — fall back to main thread
+                console.warn('[loom] Failed to create web workers, falling back to main-thread execution');
+            }
+        }
         super({
             ...options,
+            workerProvider,
             contextMenuProvider,
             popupProvider,
             viewportWidth: container.clientWidth,
@@ -11329,8 +11947,13 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         // ROI overlay state
         this.roiOverlayContainer = null;
         this.roiElements = new Map();
+        // Per-track SVG feature overlays for hover/click interactivity
+        this.featureOverlays = new Map();
+        /** Worker provider auto-created by `workers` option. Disposed on cleanup. */
+        this.ownedWorkerProvider = null;
+        this.ownedWorkerProvider = ownedProvider;
         this.container = container;
-        this.interactive = (_c = options.interactive) !== null && _c !== void 0 ? _c : true;
+        this.interactive = (_d = options.interactive) !== null && _d !== void 0 ? _d : true;
         injectScrollStyles(container);
         container.style.userSelect = "none";
         container.style.touchAction = "none";
@@ -11366,6 +11989,7 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         // This may repaint the axis twice on initial load (negligible for a 50px canvas).
         this.events.on(BrowserEvent.DataLoaded, ({ track }) => {
             this.updateAxisContent(track);
+            this.updateFeatureOverlay(track);
         });
         // Repaint axis canvases when theme changes (track canvases update via
         // track.setTheme(), but axis sidebar is managed here in GenomeBrowser).
@@ -11380,13 +12004,11 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         this.events.on(BrowserEvent.ROIChanged, () => this.renderROIOverlays());
         this.events.on(BrowserEvent.LocusChange, () => this.renderROIOverlays());
     }
-    /** Add a track and attach its canvas to the container. */
-    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight) {
-        const id = super.addTrack(track, dataSource, dataSourceConfig, maxTrackHeight);
+    /** Build a DOM row for a track (axis column + viewport wrapper). */
+    _buildTrackRow(track, maxTrackHeight) {
         const canvas = track.canvas;
         canvas.style.display = "block";
         canvas.style.width = "100%";
-        // Flex row: [axis (50px)] [viewport (flex: 1)]
         const row = document.createElement("div");
         row.style.display = "flex";
         row.style.width = "100%";
@@ -11401,10 +12023,8 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         const viewportWrapper = document.createElement("div");
         viewportWrapper.style.flex = "1";
         viewportWrapper.style.minWidth = "0";
-        // Apply maxTrackHeight if set — enables native scroll for tall tracks
-        const mt = this.managedTracks[this.managedTracks.length - 1];
-        if (mt.maxTrackHeight != null) {
-            viewportWrapper.style.maxHeight = `${mt.maxTrackHeight}px`;
+        if (maxTrackHeight != null) {
+            viewportWrapper.style.maxHeight = `${maxTrackHeight}px`;
             viewportWrapper.style.overflowY = "auto";
             viewportWrapper.style.overscrollBehaviorY = "none";
             viewportWrapper.style.backgroundColor =
@@ -11414,15 +12034,33 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         viewportWrapper.appendChild(canvas);
         row.appendChild(axisDiv);
         row.appendChild(viewportWrapper);
-        this.container.appendChild(row);
-        this.trackRows.set(track, {
-            row,
-            axisDiv,
-            axisCanvas: null,
-            viewportWrapper,
-        });
+        // Create SVG feature overlay for hover/click interactivity
+        if (this.interactive) {
+            const overlay = new SVGFeatureOverlay(viewportWrapper);
+            overlay.onFeatureClick = (rect, event) => {
+                // Resolve interaction using the rect center, then show popup
+                const cx = rect.x + rect.width / 2;
+                const cy = rect.y + rect.height / 2;
+                const interaction = this.resolveInteraction(track, cx, cy);
+                if (interaction) {
+                    this.events.emit(BrowserEvent.TrackClick, interaction);
+                    if (this.popupProvider && interaction.popupData.length > 0) {
+                        const containerRect = this.container.getBoundingClientRect();
+                        const canvasRect = track.canvas.getBoundingClientRect();
+                        this.popupProvider.show(interaction.popupData, {
+                            x: canvasRect.left - containerRect.left + event.offsetX,
+                            y: canvasRect.top - containerRect.top + event.offsetY,
+                        }, this.container);
+                    }
+                }
+            };
+            this.featureOverlays.set(track, overlay);
+        }
+        return { row, axisDiv, axisCanvas: null, viewportWrapper };
+    }
+    /** Post-registration UI setup for a track row (axis content, cursors, drag handlers). */
+    _setupTrackRowUI(track) {
         // Suppress on-canvas data range labels for wig tracks — the axis column handles it.
-        // This keeps showDataRange=true as the default for standalone WigTrackCanvas users.
         if (track.type === "wig") {
             track.setConfig({
                 showDataRange: false,
@@ -11431,24 +12069,38 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         this.updateAxisContent(track);
         // Ruler tracks: crosshair for sweep-to-zoom, pointer in WG mode (click to navigate)
         if (this.interactive && track.type === "ruler") {
-            canvas.style.cursor = isWholeGenomeView(this._locus)
+            track.canvas.style.cursor = isWholeGenomeView(this._locus)
                 ? "pointer"
                 : "crosshair";
         }
         // Enable drag-to-reorder on the axis column for non-ruler tracks
-        if (this.interactive && track.type !== "ruler") {
-            this.setupReorderHandlers(track, axisDiv);
+        const entry = this.trackRows.get(track);
+        if (this.interactive && track.type !== "ruler" && entry) {
+            this.setupReorderHandlers(track, entry.axisDiv);
         }
+    }
+    /** Add a track and attach its canvas to the container. */
+    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight, order) {
+        // Build and register DOM row BEFORE super.addTrack() so that
+        // syncDOMOrder() (called from sortTracks) can position it correctly.
+        const trackRow = this._buildTrackRow(track, maxTrackHeight);
+        this.container.appendChild(trackRow.row);
+        this.trackRows.set(track, trackRow);
+        const id = super.addTrack(track, dataSource, dataSourceConfig, maxTrackHeight, order);
+        this._setupTrackRowUI(track);
         return id;
     }
     /** Remove a track and its row from the container. */
     removeTrack(trackOrId) {
+        var _a;
         const track = typeof trackOrId === 'string'
             ? this.getTrack(trackOrId)
             : trackOrId;
         if (!track)
             return;
         this.teardownReorderHandlers(track);
+        (_a = this.featureOverlays.get(track)) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.featureOverlays.delete(track);
         const entry = this.trackRows.get(track);
         if (entry && entry.row.parentNode === this.container) {
             this.container.removeChild(entry.row);
@@ -11503,6 +12155,8 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         }
         // Re-render ROI overlays
         this.renderROIOverlays();
+        // Update feature overlays
+        this.updateFeatureOverlays();
     }
     /** Clean up event listeners, remove canvases, and dispose headless core. */
     // ─── Remote connection ────────────────────────────────────────────────
@@ -11552,6 +12206,9 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         }
         this.removeSweepOverlay();
         this.clearROIOverlay();
+        for (const overlay of this.featureOverlays.values())
+            overlay.dispose();
+        this.featureOverlays.clear();
         for (const mt of this.managedTracks) {
             this.teardownReorderHandlers(mt.track);
             const entry = this.trackRows.get(mt.track);
@@ -11562,6 +12219,10 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         this.reorderHandlers.clear();
         this.trackRows.clear();
         super.dispose();
+        if (this.ownedWorkerProvider) {
+            this.ownedWorkerProvider.dispose();
+            this.ownedWorkerProvider = null;
+        }
     }
     /**
      * Update the axis content for a track based on its getAxisInfo().
@@ -11596,12 +12257,7 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         const visibleHeight = (mt === null || mt === void 0 ? void 0 : mt.maxTrackHeight) != null
             ? Math.min(track.height, mt.maxTrackHeight)
             : track.height;
-        if (info.dataRange) {
-            this.paintAxisCanvas(entry, info, visibleHeight, renderQuantitativeAxis);
-        }
-        else if (info.label) {
-            this.paintAxisCanvas(entry, info, visibleHeight, renderLabelAxis);
-        }
+        this.paintAxisCanvas(entry, info, visibleHeight, renderQuantitativeAxis);
     }
     /**
      * Prepare an axis canvas at the correct size with DPR scaling,
@@ -11714,6 +12370,10 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
             this.lastPointerX = e.clientX;
             this.container.setPointerCapture(e.pointerId);
             this.container.style.cursor = "grabbing";
+            // Suppress feature overlay pointer events during drag
+            for (const overlay of this.featureOverlays.values()) {
+                overlay.setSuppressed(true);
+            }
         };
         this.handlePointerMove = (e) => {
             if (this.isSweeping && this.sweepOverlay && this.sweepRulerCanvas) {
@@ -11786,6 +12446,10 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
             const wasDragging = this.isDragging;
             this.isDragging = false;
             this.container.style.cursor = "grab";
+            // Restore feature overlay pointer events
+            for (const overlay of this.featureOverlays.values()) {
+                overlay.setSuppressed(false);
+            }
             // Click detection: pointer didn't move more than threshold
             const dx = e.clientX - this.pointerDownX;
             const dy = e.clientY - this.pointerDownY;
@@ -11961,7 +12625,10 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
             // Common items (set height, remove)
             const callbacks = {
                 setTrackHeight: (t, h) => {
-                    if (t instanceof BaseTrackCanvas) {
+                    if (t instanceof AnnotationTrackCanvas) {
+                        t.setFixedHeight(h);
+                    }
+                    else if (t instanceof BaseTrackCanvas) {
                         t.setConfig({ height: h });
                     }
                 },
@@ -12057,6 +12724,10 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
         }
     }
     // ─── Track reorder drag ─────────────────────────────────────────────
+    /** Sync DOM after any sort (addTrack, addGeneTrack, etc.). */
+    onTracksSorted() {
+        this.syncDOMOrder();
+    }
     /** Reorder DOM rows to match managedTracks order. */
     syncDOMOrder() {
         for (const mt of this.managedTracks) {
@@ -12133,6 +12804,8 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
                 if (dragEntry) {
                     dragEntry.axisDiv.style.cursor = "grab";
                 }
+                // Persist the drag result so future addTrack sorts don't revert positions.
+                this._assignOrderFromPosition();
                 // Emit the final order change event
                 this.events.emit(BrowserEvent.TrackOrderChanged, {
                     tracks: this.managedTracks.map((mt) => mt.track),
@@ -12255,6 +12928,21 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
      * DOM-based (not canvas) for easy hover/click interaction without
      * re-rendering track canvases.
      */
+    /** Update all feature overlays after render. */
+    updateFeatureOverlays() {
+        for (const mt of this.managedTracks) {
+            this.updateFeatureOverlay(mt.track);
+        }
+    }
+    /** Update the feature overlay for a single track. */
+    updateFeatureOverlay(track) {
+        const overlay = this.featureOverlays.get(track);
+        if (!overlay)
+            return;
+        if (track instanceof BaseTrackCanvas) {
+            overlay.update(track.getFeatureRects());
+        }
+    }
     renderROIOverlays() {
         var _a, _b;
         const visibleROIs = this.getVisibleROIs();
@@ -12501,9 +13189,6 @@ class GenomeBrowser extends HeadlessGenomeBrowser {
                 if (info.dataRange) {
                     renderQuantitativeAxis(ctx, info, axisWidth, h);
                 }
-                else if (info.label) {
-                    renderLabelAxis(ctx, info, axisWidth, h);
-                }
                 ctx.restore();
             }
             // Render track (right of axis)
@@ -12618,7 +13303,7 @@ function inferShellTheme(theme) {
     return luminance < 0.5 ? 'dark' : 'modern';
 }
 const LoomBrowser = forwardRef(function LoomBrowser(props, ref) {
-    const { defaultLocus, locus, onLocusChange, theme, genome, interactive, wheelZoom, workerProvider, popupProvider, contextMenuProvider, ruler, genes, sequence, session, tracks: trackConfigs, remoteSocket, className, style, children, } = props;
+    const { defaultLocus, locus, onLocusChange, theme, genome, interactive, wheelZoom, workers, workerFactory, workerProvider, popupProvider, contextMenuProvider, ruler, genes, sequence, session, tracks: trackConfigs, remoteSocket, className, style, children, } = props;
     const containerRef = useRef(null);
     const browserRef = useRef(null);
     const [browser, setBrowser] = useState(null);
@@ -12641,6 +13326,8 @@ const LoomBrowser = forwardRef(function LoomBrowser(props, ref) {
             locus: initialLocus,
             interactive,
             wheelZoom,
+            workers,
+            workerFactory,
             workerProvider,
             popupProvider,
             contextMenuProvider,