loom-browser 0.0.6 → 0.0.7

package/dist/types/bigwig/index.d.ts

@@ -6,15 +6,12 @@
  * by @gmod/bbi internally.
  */
 import type { WigFeature, WindowFunction, Locus } from '../types';
-import type { WorkerProvider } from '../workerProvider';
 export { BinaryParser } from '../io/binaryParser';
 export interface FetchBigWigOptions {
     /** Resolution in base pairs per pixel. Used to select an appropriate zoom level. */
     bpPerPixel?: number;
     /** Aggregation function for zoom-level data. Default: 'mean'. */
     windowFunction?: WindowFunction;
-    /** @deprecated Worker dispatch is handled internally by @gmod/bbi. */
-    workerProvider?: WorkerProvider;
     /** AbortSignal for cancelling in-flight HTTP requests. */
     signal?: AbortSignal;
 }
@@ -47,7 +44,7 @@ export interface BigWigTotalSummary {
  */
 export declare class BigWigReader {
     private readonly bw;
-    constructor(url: string, _workerProvider?: WorkerProvider);
+    constructor(url: string);
     loadHeader(signal?: AbortSignal): Promise<BigWigHeader>;
     getTotalSummary(signal?: AbortSignal): Promise<BigWigTotalSummary | undefined>;
     readFeatures(chr: string, bpStart: number, bpEnd: number, bpPerPixel?: number, windowFunction?: WindowFunction, signal?: AbortSignal): Promise<WigFeature[]>;
@@ -61,6 +58,6 @@ export declare function fetchBigWigFeatures(url: string, locus: Locus, options?:
  * Fetch BigWig features across all specified chromosomes for whole genome view.
  * Returns features with per-chromosome coordinates (caller transforms to genome-wide).
  */
-export declare function fetchBigWigWGFeatures(url: string, chromNames: string[], bpPerPixel: number, options?: Pick<FetchBigWigOptions, 'windowFunction' | 'workerProvider' | 'signal'>): Promise<WigFeature[]>;
+export declare function fetchBigWigWGFeatures(url: string, chromNames: string[], bpPerPixel: number, options?: Pick<FetchBigWigOptions, 'windowFunction' | 'signal'>): Promise<WigFeature[]>;
 /** Clear the BigWig reader cache (useful for testing or memory management). */
 export declare function clearBigWigCache(): void;

package/dist/types/dataSourceWorkerProvider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * DataSourceWorkerProvider — manages long-lived DataSource instances inside workers.
+ *
+ * Unlike the stateless WorkerProvider (fire-and-forget tasks), this provider
+ * creates persistent DataSource instances in workers that cache parsed headers,
+ * indices, and reader state across fetch calls.
+ *
+ * Inspired by JBrowse 2's RPC adapter system (GMOD/jbrowse-components).
+ *
+ * Layer 1 (Data + Layout): no DOM.
+ */
+import type { DataSourceConfig, Locus } from './types';
+/** Main thread → Worker messages. */
+export type DataSourceWorkerRequest = {
+    type: 'create';
+    instanceId: string;
+    config: DataSourceConfig;
+} | {
+    type: 'fetch';
+    instanceId: string;
+    fetchId: number;
+    locus: Locus;
+    bpPerPixel: number;
+} | {
+    type: 'configure';
+    instanceId: string;
+    method: string;
+    args: unknown[];
+} | {
+    type: 'cancel';
+    fetchId: number;
+} | {
+    type: 'destroy';
+    instanceId: string;
+};
+/** Worker → Main thread messages. */
+export type DataSourceWorkerResponse = {
+    type: 'ready';
+} | {
+    type: 'fetchResult';
+    fetchId: number;
+    features: unknown[];
+} | {
+    type: 'fetchError';
+    fetchId: number;
+    error: string;
+};
+/**
+ * Manages DataSource instances that live inside web workers.
+ *
+ * Each DataSource is identified by a unique `instanceId` (assigned by the caller).
+ * The provider routes messages to the correct worker using sticky routing
+ * (same URL → same worker) to preserve reader caches.
+ */
+export interface DataSourceWorkerProvider {
+    /**
+     * Create a DataSource instance inside a worker.
+     * The instance persists until `destroy()` is called.
+     */
+    create(instanceId: string, config: DataSourceConfig): void;
+    /**
+     * Fetch features from a worker-resident DataSource.
+     * Supports cancellation via AbortSignal → cancel message.
+     */
+    fetch<F>(instanceId: string, locus: Locus, bpPerPixel: number, signal: AbortSignal): Promise<F[]>;
+    /**
+     * Send a configuration update to a worker-resident DataSource.
+     * Used for serializable setter calls like setCumulativeOffsets, setWindowFunction.
+     */
+    configure(instanceId: string, method: string, ...args: unknown[]): void;
+    /**
+     * Destroy a worker-resident DataSource instance.
+     */
+    destroy(instanceId: string): void;
+    /**
+     * Shut down all workers and release resources.
+     */
+    dispose(): void;
+}

package/dist/types/dataSources/bigWigDataSource.d.ts

@@ -1,13 +1,11 @@
 import type { DataSource, Locus, WigFeature, WindowFunction } from '../types';
-import type { WorkerProvider } from '../workerProvider';
 import type { CumulativeOffsets } from '../genome/chromSizes';
 export declare class BigWigDataSource implements DataSource<WigFeature> {
     private url;
     private _windowFunction;
-    private workerProvider?;
     private _cumulativeOffsets?;
     private _resolveChromName?;
-    constructor(url: string, windowFunction?: WindowFunction, workerProvider?: WorkerProvider);
+    constructor(url: string, windowFunction?: WindowFunction);
     get windowFunction(): WindowFunction;
     /** Update the window function for future fetches. */
     setWindowFunction(wf: WindowFunction): void;

package/dist/types/dataSources/featureSourceFactory.d.ts

@@ -10,7 +10,6 @@
  * Layer 1 (Data + Layout): no DOM.
  */
 import type { DataSource } from '../types';
-import type { WorkerProvider } from '../workerProvider';
 export interface FeatureSourceConfig {
     /** URL to the data file. */
     url: string;
@@ -43,4 +42,4 @@ export interface FeatureSourceResult {
  *
  * Port of js/feature/featureSource.ts factory routing logic.
  */
-export declare function createFeatureSource(config: FeatureSourceConfig, workerProvider?: WorkerProvider): FeatureSourceResult;
+export declare function createFeatureSource(config: FeatureSourceConfig): FeatureSourceResult;

package/dist/types/dataSources/gtxDataSource.d.ts

@@ -16,17 +16,15 @@
  * Layer 1 (Data + Layout): no DOM, no canvas.
  */
 import type { DataSource, Locus, WigFeature, WindowFunction } from '../types';
-import type { WorkerProvider } from '../workerProvider';
 import type { CumulativeOffsets } from '../genome/chromSizes';
 export declare class GtxDataSource implements DataSource<WigFeature> {
     private url;
     private experimentId;
     private _windowFunction;
-    private workerProvider?;
     private _cumulativeOffsets?;
     private _resolveChromName?;
     private reader;
-    constructor(url: string, experimentId: string, windowFunction?: WindowFunction, workerProvider?: WorkerProvider);
+    constructor(url: string, experimentId: string, windowFunction?: WindowFunction);
     get windowFunction(): WindowFunction;
     /** Update the window function for future fetches. */
     setWindowFunction(wf: WindowFunction): void;

package/dist/types/dataSources/textFeatureSource.d.ts

@@ -13,7 +13,6 @@
 import type { DataSource, Locus, TextFileFormat } from '../types';
 import type { CacheableFeature } from '../featureCache';
 import type { CumulativeOffsets } from '../genome/chromSizes';
-import type { WorkerProvider } from '../workerProvider';
 export interface TextFeatureSourceConfig {
     /** URL to the data file. */
     url: string;
@@ -25,8 +24,6 @@ export interface TextFeatureSourceConfig {
     indexed?: boolean;
     /** For GFF: whether to assemble transcript models. Default: true. */
     assembleGFF?: boolean;
-    /** Worker provider for offloading CPU-intensive tasks. */
-    workerProvider?: WorkerProvider;
 }
 /**
  * DataSource for text-based genomic feature files.
@@ -39,7 +36,6 @@ export declare class TextFeatureSource<F extends CacheableFeature = CacheableFea
     private readonly format;
     private readonly assembleGFF;
     private readonly _indexed;
-    private readonly workerProvider?;
     private _resolveChromName?;
     private _cumulativeOffsets?;
     private tabixReader?;

package/dist/types/genomeBrowser.d.ts

@@ -32,6 +32,48 @@ export interface GenomeBrowserOptions extends HeadlessGenomeBrowserOptions {
     interactive?: boolean;
     /** Enable trackpad pinch and scroll-wheel zoom. Default: true when interactive. */
     wheelZoom?: boolean;
+    /**
+     * Auto-create a unified web worker pool for off-main-thread tasks and data fetching.
+     * - `true`: create a pool with `navigator.hardwareConcurrency` workers (capped at 4)
+     * - `number`: create a pool with that many workers
+     * - `false` / `undefined`: no auto-created workers (main-thread fallback)
+     *
+     * Ignored when `workerProvider` is explicitly passed.
+     *
+     * Uses `import.meta.url` to resolve the worker script. If worker creation
+     * fails (e.g. due to CSP or bundler issues), falls back silently to
+     * main-thread execution.
+     *
+     * For bundler users who need custom worker instantiation, pass
+     * `workerFactory` instead (see example below).
+     *
+     * @example
+     * ```ts
+     * // Simple — auto-detect pool size:
+     * new GenomeBrowser(container, { locus, workers: true })
+     *
+     * // Explicit pool size:
+     * new GenomeBrowser(container, { locus, workers: 2 })
+     *
+     * // Bundler users (webpack 5, Vite) — custom factory:
+     * new GenomeBrowser(container, {
+     *     locus,
+     *     workerFactory: () => new Worker(
+     *         new URL('loom/dist/loom-worker.js', import.meta.url)
+     *     ),
+     * })
+     * ```
+     */
+    workers?: boolean | number;
+    /**
+     * Factory function that creates Worker instances for the worker pool.
+     * Use this with bundlers (webpack 5, Vite) that require the
+     * `new Worker(new URL(...))` pattern.
+     *
+     * Ignored when `workerProvider` is explicitly passed.
+     * When set, `workers` defaults to `true` (pool size = hardwareConcurrency, capped at 4).
+     */
+    workerFactory?: () => Worker;
 }
 export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     private container;
@@ -69,9 +111,16 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     private wheelRafId;
     private roiOverlayContainer;
     private roiElements;
+    private featureOverlays;
+    /** Worker provider auto-created by `workers` option. Disposed on cleanup. */
+    private ownedWorkerProvider;
     constructor(container: HTMLElement, options: GenomeBrowserOptions);
+    /** Build a DOM row for a track (axis column + viewport wrapper). */
+    private _buildTrackRow;
+    /** Post-registration UI setup for a track row (axis content, cursors, drag handlers). */
+    private _setupTrackRowUI;
     /** Add a track and attach its canvas to the container. */
-    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number): string;
+    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number, order?: number): string;
     /** Remove a track and its row from the container. */
     removeTrack(trackOrId: Track | string): void;
     /** Move a track and reorder the DOM rows to match. */
@@ -121,6 +170,8 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     private teardownHoverHandlers;
     private setupContextMenuHandler;
     private teardownContextMenuHandler;
+    /** Sync DOM after any sort (addTrack, addGeneTrack, etc.). */
+    protected onTracksSorted(): void;
     /** Reorder DOM rows to match managedTracks order. */
     private syncDOMOrder;
     /** Set up drag-to-reorder pointer handlers on an axis div. */
@@ -147,6 +198,10 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
      * DOM-based (not canvas) for easy hover/click interaction without
      * re-rendering track canvases.
      */
+    /** Update all feature overlays after render. */
+    private updateFeatureOverlays;
+    /** Update the feature overlay for a single track. */
+    private updateFeatureOverlay;
     private renderROIOverlays;
     /** Create a styled DOM element for an ROI region. */
     private createROIElement;

package/dist/types/gtx/index.d.ts

@@ -11,14 +11,11 @@
 export { GtxReader } from './gtxReader';
 export type { GtxHeader, ChromEntry, ExperimentEntry } from './gtxReader';
 import type { WigFeature, WindowFunction, Locus } from '../types';
-import type { WorkerProvider } from '../workerProvider';
 export interface FetchGtxOptions {
     /** Resolution in base pairs per pixel. Used to select an appropriate zoom level. */
     bpPerPixel?: number;
     /** Aggregation function for zoom-level data. Default: 'mean'. */
     windowFunction?: WindowFunction;
-    /** Worker provider for offloading decode work (reserved for future use). */
-    workerProvider?: WorkerProvider;
     /** AbortSignal for cancelling in-flight HTTP requests. */
     signal?: AbortSignal;
 }
@@ -30,7 +27,7 @@ export declare function fetchGtxFeatures(url: string, experimentId: string, locu
  * Fetch GTX features across all specified chromosomes for whole genome view.
  * Returns features with per-chromosome coordinates (caller transforms to genome-wide).
  */
-export declare function fetchGtxWGFeatures(url: string, experimentId: string, chromNames: string[], bpPerPixel: number, options?: Pick<FetchGtxOptions, 'windowFunction' | 'workerProvider' | 'signal'>): Promise<WigFeature[]>;
+export declare function fetchGtxWGFeatures(url: string, experimentId: string, chromNames: string[], bpPerPixel: number, options?: Pick<FetchGtxOptions, 'windowFunction' | 'signal'>): Promise<WigFeature[]>;
 /**
  * Fetch GTX features for multiple experiments simultaneously.
  * Optimizes network by merging byte ranges for experiments in the same tiles.

package/dist/types/headlessGenomeBrowser.d.ts

@@ -20,6 +20,7 @@ import type { Locus, Track, DataSource, FeatureCacheEntry, SessionConfig, TrackS
 import { ROISet } from './roi/roiSet';
 import type { CanvasProvider } from './canvasProvider';
 import type { WorkerProvider } from './workerProvider';
+import type { DataSourceWorkerProvider } from './dataSourceWorkerProvider';
 import type { PopupProvider } from './popupProvider';
 import type { ContextMenuProvider } from './contextMenuProvider';
 import type { RenderTheme } from './themes/renderTheme';
@@ -122,7 +123,9 @@ export interface HeadlessGenomeBrowserOptions {
     viewportWidth?: number;
     /** Canvas provider for environment abstraction. Default: DOMCanvasProvider. */
     canvasProvider?: CanvasProvider;
-    /** Worker provider for offloading CPU-intensive tasks. Default: main-thread execution. */
+    /** Worker provider for offloading CPU-intensive tasks. Default: main-thread execution.
+     *  If this also implements DataSourceWorkerProvider (e.g. WebWorkerPool),
+     *  it will be used for data fetching automatically. */
     workerProvider?: WorkerProvider;
     /** Popup provider for rendering feature popups on click/hover. Default in GenomeBrowser: DefaultPopupProvider. Pass null to disable. */
     popupProvider?: PopupProvider | null;
@@ -264,10 +267,16 @@ export declare class HeadlessGenomeBrowser {
     protected roiSets: ROISet[];
     /** Inflight fetch promises keyed by (cacheKey + fetchRegion + bpPerPixel) for deduplication. */
     private inflightFetches;
+    /** Timer for debouncing data loads during rapid zoom/pan. */
+    private loadDebounceTimer;
+    /** When true, sortTracks() is a no-op. Used for batch track additions (e.g. loadSession). */
+    private _deferSort;
     /** Canvas provider for environment abstraction. Available for convenience API / future use. */
     readonly canvasProvider: CanvasProvider;
     /** Worker provider for offloading CPU-intensive tasks. */
     readonly workerProvider?: WorkerProvider;
+    /** Data source worker provider for running DataSources in web workers. */
+    readonly dataSourceWorkerProvider?: DataSourceWorkerProvider;
     /** Popup provider for rendering feature popups on click/hover. */
     readonly popupProvider?: PopupProvider;
     /** Context menu provider for right-click menus. */
@@ -293,6 +302,11 @@ export declare class HeadlessGenomeBrowser {
     /** Agent-friendly state projection manager. Lazily created on first access. */
     get state(): StateProjection;
     constructor(options: HeadlessGenomeBrowserOptions);
+    /**
+     * Create a WorkerDataSource proxy for worker-eligible configs, or return null
+     * if dataSourceWorkerProvider is not set. Handles create + chrom alias + offsets wiring.
+     */
+    private createWorkerDataSource;
     /** Clamp a locus to valid chromosome bounds. No-op if chromSizes is not set. */
     protected clamp(locus: Locus): Locus;
     /** Subscribe to a browser event. Returns an unsubscribe function. */
@@ -306,7 +320,7 @@ export declare class HeadlessGenomeBrowser {
      */
     setViewportWidth(width: number): void;
     /** Add a track with an optional data source for automatic data management. */
-    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number): string;
+    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number, order?: number): string;
     /** Remove a track by reference or by stable string ID. */
     removeTrack(trackOrId: Track | string): void;
     /**
@@ -314,6 +328,22 @@ export declare class HeadlessGenomeBrowser {
      * Emits BrowserEvent.TrackOrderChanged with the new track order.
      */
     moveTrack(track: Track, toIndex: number): void;
+    /**
+     * 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).
+     */
+    private sortTracks;
+    /** Hook for subclasses to react to track order changes (e.g., DOM reorder). */
+    protected onTracksSorted(): void;
+    /**
+     * 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.
+     */
+    protected _assignOrderFromPosition(): void;
+    /** Find the ManagedTrack entry for a given track canvas. */
+    private findMT;
     /** Get the current track order. */
     getTrackOrder(): Track[];
     /** Find a managed track by its stable string ID. Returns undefined if not found. */
@@ -478,6 +508,13 @@ export declare class HeadlessGenomeBrowser {
      * Returns null if the track has no features at the given point.
      */
     protected resolveInteraction(track: Track, x: number, y: number): TrackInteractionEvent | null;
+    /**
+     * 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.
+     */
+    private debouncedLoad;
     protected loadAllTracksIfNeeded(): void;
     /**
      * Load data for a single track, deduplicating against inflight fetches

package/dist/types/index.d.ts

@@ -10,7 +10,13 @@ export { MainThreadProvider, mainThreadProvider } from './workerProvider';
 export { WebWorkerProvider } from './worker/webWorkerProvider';
 export type { WebWorkerProviderOptions } from './worker/webWorkerProvider';
 export { NodeWorkerProvider } from './worker/nodeWorkerProvider';
+export type { DataSourceWorkerProvider, DataSourceWorkerRequest, DataSourceWorkerResponse } from './dataSourceWorkerProvider';
+export { WorkerDataSource } from './workerDataSource';
+export { WebWorkerPool } from './worker/webWorkerPool';
+export type { WebWorkerPoolOptions } from './worker/webWorkerPool';
 export { BaseTrackCanvas } from './tracks/baseTrackCanvas';
+export { renderTrackNameLabel } from './tracks/trackLabel';
+export type { TrackNameLabelOptions } from './tracks/trackLabel';
 export type { AnnotationFeature, Exon, AnnotationRenderConfig, RenderContext, DisplayMode, Locus, Track, RulerRenderConfig, AxisInfo, TrackFeatureSummary, WigFeatureSummary, AnnotationFeatureSummary, InteractionFeatureSummary } from './types';
 export type { WigFeature, WigRenderConfig, WigColorValue, WigGraphType, WindowFunction, WigGuideLine } from './types';
 export type { SequenceRenderConfig, SequenceType, SequenceTrackSessionConfig, SequenceSessionOverrides } from './types';
@@ -18,7 +24,7 @@ export { defaultSequenceRenderConfig } from './types';
 export type { InteractionFeature, InteractionRenderConfig, ArcOrientation, ArcDisplayMode, InteractionTrackSessionConfig, InteractionSessionOverrides } from './types';
 export { defaultInteractionRenderConfig } from './types';
 export type { DataSource, FeatureCacheEntry, DataDrivenTrack } from './types';
-export type { PopupDataItem, HitTestResult, TrackInteractionEvent, ContextMenuItem, TrackContextMenuEvent, NumericState, ROI, ROISetConfig, ROIInteractionEvent } from './types';
+export type { PopupDataItem, HitTestResult, TrackInteractionEvent, ContextMenuItem, TrackContextMenuEvent, NumericState, ROI, ROISetConfig, ROIInteractionEvent, FeatureRect } from './types';
 export type { SessionConfig, TrackSessionConfig, WigTrackSessionConfig, AnnotationTrackSessionConfig, RulerTrackSessionConfig, WigSessionOverrides, AnnotationSessionOverrides, RulerSessionOverrides, DataSourceConfig, BigWigDataSourceConfig, GtxDataSourceConfig, UCSCDataSourceConfig, TextDataSourceConfig, MemoryDataSourceConfig, SequenceProvider, IgvSessionObject, IgvReferenceConfig, IgvTrackConfig, Chromosome, Genome, GenomeConfig, ChromAliasRecord, Strand, TextFileFormat, BedFeature, PeakFeature, BedGraphFeature, GFFRecord, GFFFeature, TextFeature, } from './types';
 export { defaultAnnotationRenderConfig, defaultRulerRenderConfig, defaultWigRenderConfig } from './types';
 export type { Packable } from './pack';
@@ -30,7 +36,7 @@ export { renderRulerTrack, renderWholeGenomeRuler } from './tracks/ruler/rulerRe
 export type { WholeGenomeRulerContext } from './tracks/ruler/rulerRenderer';
 export { RulerTrackCanvas } from './tracks/ruler/rulerTrackCanvas';
 export type { RulerTrackCanvasOptions } from './tracks/ruler/rulerTrackCanvas';
-export { renderQuantitativeAxis, renderLabelAxis, prettyPrintNumber } from './tracks/axis/axisRenderer';
+export { renderQuantitativeAxis, prettyPrintNumber } from './tracks/axis/axisRenderer';
 export { renderWigTrack } from './tracks/wig/wigRenderer';
 export { WigTrackCanvas } from './tracks/wig/wigTrackCanvas';
 export type { WigTrackCanvasOptions } from './tracks/wig/wigTrackCanvas';

package/dist/types/mainThreadDataSourceProvider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MainThreadDataSourceProvider — fallback DataSourceWorkerProvider that runs
+ * DataSources directly on the main thread with no serialization overhead.
+ *
+ * Analogous to JBrowse 2's MainThreadRpcDriver.
+ * Used when web workers are unavailable or for debugging.
+ *
+ * Layer 1 (Data + Layout): no DOM.
+ */
+import type { DataSourceWorkerProvider } from './dataSourceWorkerProvider';
+import type { DataSourceConfig, Locus } from './types';
+export declare class MainThreadDataSourceProvider implements DataSourceWorkerProvider {
+    private readonly instances;
+    create(instanceId: string, config: DataSourceConfig): void;
+    fetch<F>(instanceId: string, locus: Locus, bpPerPixel: number, signal: AbortSignal): Promise<F[]>;
+    configure(instanceId: string, method: string, ...args: unknown[]): void;
+    destroy(instanceId: string): void;
+    dispose(): void;
+}

package/dist/types/react/LoomBrowser.d.ts

@@ -25,7 +25,21 @@ export interface LoomBrowserProps {
     interactive?: boolean;
     /** Enable wheel zoom. Default: true. */
     wheelZoom?: boolean;
-    /** Worker provider for off-main-thread tasks. */
+    /**
+     * Auto-create a unified web worker pool. `true` for auto pool size,
+     * or a number for explicit pool size. See GenomeBrowserOptions.workers.
+     */
+    workers?: boolean | number;
+    /**
+     * Factory for custom worker instantiation (webpack 5, Vite).
+     * See GenomeBrowserOptions.workerFactory.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Worker provider for off-main-thread tasks.
+     * If this also implements DataSourceWorkerProvider (e.g. WebWorkerPool),
+     * it will be used for data fetching automatically.
+     */
     workerProvider?: WorkerProvider;
     /** Popup provider. Pass null to disable. */
     popupProvider?: PopupProvider | null;

package/dist/types/session.d.ts

@@ -15,13 +15,10 @@
  */
 import type { SessionConfig, TrackSessionConfig, IgvSessionObject, Locus, SequenceProvider } from './types';
 import type { CanvasProvider } from './canvasProvider';
-import type { WorkerProvider } from './workerProvider';
 import type { RenderTheme } from './themes/renderTheme';
 export type { CreatedTrack } from './trackRegistry';
 export declare const SESSION_VERSION = "1.0";
 export interface CreateDataSourceOptions {
-    /** Worker provider for offloading CPU-intensive tasks in data sources. */
-    workerProvider?: WorkerProvider;
 }
 /**
  * @deprecated Use the track registry (`createTrackFromConfig`) instead, which

package/dist/types/svgFeatureOverlay.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+import type { FeatureRect } from './types';
+export declare class SVGFeatureOverlay {
+    private svg;
+    private group;
+    private defs;
+    /** Callback fired when a feature rect is clicked. */
+    onFeatureClick?: (rect: FeatureRect, event: MouseEvent) => void;
+    constructor(container: HTMLElement);
+    /** Rebuild SVG rects from feature geometry. */
+    update(rects: FeatureRect[]): void;
+    /** Suppress pointer events on overlay rects (e.g., during drag). */
+    setSuppressed(suppressed: boolean): void;
+    dispose(): void;
+    /** Create an SVG filter that produces a colored glow. */
+    private createGlowFilter;
+    private createRect;
+}

package/dist/types/tabix/index.d.ts

@@ -5,12 +5,9 @@
  * All BGZF decompression, index parsing, and block fetching is handled
  * by @gmod/tabix internally.
  */
-import type { WorkerProvider } from '../workerProvider';
 export interface TabixReaderOptions {
     /** URL to the .tbi index file. Defaults to `url + '.tbi'`. */
     indexUrl?: string;
-    /** @deprecated Worker dispatch is handled internally by @gmod/tabix. */
-    workerProvider?: WorkerProvider;
 }
 export interface TabixHeader {
     nref: number;

package/dist/types/trackRegistry.d.ts

@@ -13,13 +13,11 @@
  */
 import type { Locus, Track, DataSource, DataSourceConfig, TrackSessionConfig, SequenceProvider } from './types';
 import type { CanvasProvider } from './canvasProvider';
-import type { WorkerProvider } from './workerProvider';
 import type { RenderTheme } from './themes/renderTheme';
 /** Context passed to every track creator function. */
 export interface TrackCreatorContext {
     locus: Locus;
     canvasProvider: CanvasProvider;
-    workerProvider?: WorkerProvider;
     theme?: Partial<RenderTheme>;
     /** Sequence provider from the genome, used by sequence tracks. */
     sequenceProvider?: SequenceProvider;
@@ -65,7 +63,7 @@ export declare function getTrackCreator(type: string): TrackCreator | undefined;
  * Mirrors igv.js `knownTrackTypes()` (js/trackFactory.ts).
  */
 export declare function knownTrackTypes(): Set<string>;
-export declare function createDataSource(config: DataSourceConfig, workerProvider?: WorkerProvider): DataSource;
+export declare function createDataSource(config: DataSourceConfig): DataSource;
 /**
  * Create a track from a session config using the registry.
  *
@@ -75,7 +73,6 @@ export declare function createDataSource(config: DataSourceConfig, workerProvide
  */
 export declare function createTrackFromConfig(trackConfig: TrackSessionConfig, locus: Locus, options?: {
     canvasProvider?: CanvasProvider;
-    workerProvider?: WorkerProvider;
     theme?: Partial<RenderTheme>;
     sequenceProvider?: SequenceProvider;
 }): CreatedTrack;

package/dist/types/tracks/annotation/annotationRenderer.d.ts

@@ -8,10 +8,13 @@
  * intron lines, strand arrows, labels, and per-feature colors.
  */
 import type { AnnotationFeature, AnnotationRenderConfig, RenderContext } from '../../types';
+import type { TrackNameLabelOptions } from '../trackLabel';
 /**
  * Render a set of annotation features onto a canvas context.
  *
  * Features should already have `.row` assigned (via `pack()`).
  * The canvas should be sized and cleared before calling this.
  */
-export declare function renderAnnotationTrack(ctx: CanvasRenderingContext2D, features: AnnotationFeature[], config: AnnotationRenderConfig, rc: RenderContext): void;
+export declare function renderAnnotationTrack(ctx: CanvasRenderingContext2D, features: AnnotationFeature[], config: AnnotationRenderConfig, rc: RenderContext, 
+/** Optional track name label overlay (top-left corner). */
+trackLabel?: TrackNameLabelOptions): void;

package/dist/types/tracks/annotation/annotationTrackCanvas.d.ts

@@ -10,9 +10,8 @@
  *   const track = new AnnotationTrackCanvas(canvas, { locus, features })
  *   track.attachTo(containerDiv)
  */
-import type { AnnotationFeature, AnnotationRenderConfig, Locus, RenderContext, AnnotationTrackSessionConfig, HitTestResult, AxisInfo, ContextMenuItem } from '../../types';
+import type { AnnotationFeature, AnnotationRenderConfig, Locus, RenderContext, AnnotationTrackSessionConfig, HitTestResult, AxisInfo, ContextMenuItem, FeatureRect } from '../../types';
 import type { CanvasProvider } from '../../canvasProvider';
-import type { WorkerProvider } from '../../workerProvider';
 import type { RenderTheme } from '../../themes/renderTheme';
 import { BaseTrackCanvas } from '../baseTrackCanvas';
 export type { Locus } from '../../types';
@@ -29,8 +28,6 @@ export interface AnnotationTrackCanvasOptions {
     background?: string;
     /** Canvas provider for environment abstraction. Default: DOMCanvasProvider. */
     canvasProvider?: CanvasProvider;
-    /** Worker provider for offloading CPU-intensive tasks (packing). */
-    workerProvider?: WorkerProvider;
     /** Track name for axis label. */
     name?: string;
 }
@@ -39,21 +36,27 @@ export declare class AnnotationTrackCanvas extends BaseTrackCanvas<AnnotationRen
     private fixedHeight;
     private background;
     private _name;
-    private workerProvider?;
+    /** User-set config overrides, re-applied on theme change. */
+    private _userOverrides;
+    private _userBackground;
     /** Most recently packed features, available after render(). */
     private packedFeatures;
     /** Whether packedFeatures was pre-computed by async worker (skip sync pack in computeHeight). */
     private packedReady;
     readonly type = "annotation";
     constructor(canvas: HTMLCanvasElement, options: AnnotationTrackCanvasOptions);
-    /** 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: number | undefined): void;
+    /** Update features and re-render. */
     setFeatures(features: AnnotationFeature[]): void;
     protected computeHeight(_width: number): number;
     protected getBackground(): string;
     protected doRender(ctx: CanvasRenderingContext2D, _width: number, _height: number, rc: RenderContext): void;
     getAxisInfo(): AxisInfo | undefined;
     getContextMenuItems(_x: number, _y: number): ContextMenuItem[];
+    getFeatureRects(): FeatureRect[];
     hitTest(x: number, y: number): HitTestResult<AnnotationFeature>[];
+    setConfig(config: Partial<AnnotationRenderConfig>): void;
     setTheme(theme: RenderTheme): void;
     serializeConfig(theme: RenderTheme): AnnotationTrackSessionConfig;
 }

package/dist/types/tracks/axis/axisRenderer.d.ts

@@ -4,16 +4,10 @@
  * 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.
  */
 import type { AxisInfo } from '../../types';
 /** Format a number for axis labels (ported from igv.js paintAxis.ts). */
 export declare function prettyPrintNumber(n: number): string;
 export declare function renderQuantitativeAxis(ctx: CanvasRenderingContext2D, info: AxisInfo, width: number, height: number): void;
-/**
- * Paint a label-only axis (e.g., gene track name).
- * Renders a vertically-rotated centered text label.
- */
-export declare function renderLabelAxis(ctx: CanvasRenderingContext2D, info: AxisInfo, width: number, height: number): void;

package/dist/types/tracks/axis/index.d.ts

@@ -1 +1 @@
-export { renderQuantitativeAxis, renderLabelAxis, prettyPrintNumber } from './axisRenderer';
+export { renderQuantitativeAxis, prettyPrintNumber } from './axisRenderer';