loom-browser 0.0.6 → 0.0.8

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,18 @@ 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;
+    /** Set to true by dispose() to suppress post-dispose promise handlers. */
+    private _disposed;
+    /** 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 +304,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 +322,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 +330,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. */
@@ -390,6 +422,8 @@ export declare class HeadlessGenomeBrowser {
     removeROI(roiId: string): boolean;
     /** Update an ROI by ID. Returns the updated ROI, or undefined if not found. */
     updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
+    /** Remove a specific ROI set by instance. Returns true if found and removed. */
+    removeROISet(set: ROISet): boolean;
     /** Remove all ROI sets. */
     clearROIs(): void;
     /** Get all ROIs across all sets (flattened). */
@@ -478,6 +512,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;
@@ -67,6 +81,7 @@ export interface LoomBrowserHandle {
     reloadData(): void;
     addROI(roi: ROI, setName?: string): ROI;
     addROISet(config: ROISetConfig): ROISet;
+    removeROISet(set: ROISet): boolean;
     removeROI(roiId: string): boolean;
     updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
     clearROIs(): void;

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

@@ -0,0 +1,14 @@
+import type { ROI } from '../types';
+export interface ROISetProps {
+    /** ROI features to display. The set is recreated when this array changes. */
+    rois: ROI[];
+    /** Name for the ROI set. Default: 'Declarative'. */
+    name?: string;
+    /** Default color for ROIs in this set (individual ROI colors take precedence). */
+    color?: string;
+}
+/**
+ * Declarative ROI set component. Renders nothing — manages ROIs on the
+ * GenomeBrowser via context. Add/remove `<ROISet>` children to control ROIs.
+ */
+export declare function DeclarativeROISet({ rois, name, color }: ROISetProps): null;

package/dist/types/react/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export { useGenomeBrowser } from './useGenomeBrowser';
 export { useBrowserEvent } from './useBrowserEvent';
 export { useLocus } from './useLocus';
+export type { TrackClickEvent, TrackEventHandlers } from './useTrackManager';

package/dist/types/react/hooks/useTrackManager.d.ts

@@ -1,5 +1,16 @@
 import type { Track } from '../../types';
 import type { GenomeBrowser } from '../../genomeBrowser';
+/** Per-track click event with typed features. */
+export interface TrackClickEvent<F> {
+    features: F[];
+    genomicLocation: number;
+    x: number;
+    y: number;
+}
+export interface TrackEventHandlers<F> {
+    onClick?: (event: TrackClickEvent<F>) => void;
+    onContextMenu?: (event: TrackClickEvent<F>) => void;
+}
 /**
  * Internal hook that manages track add/remove/update lifecycle.
  *
@@ -7,5 +18,6 @@ import type { GenomeBrowser } from '../../genomeBrowser';
  * @param recreationDeps  When these change, the track is removed and re-added (new data source).
  * @param updateTrack  Called when only updateDeps change (in-place config update).
  * @param updateDeps  When these change (but recreationDeps don't), updateTrack is called.
+ * @param eventHandlers  Optional typed click/context-menu handlers scoped to this track.
  */
-export declare function useTrackManager<T extends Track>(addTrack: (browser: GenomeBrowser) => T, recreationDeps: unknown[], updateTrack?: (track: T, browser: GenomeBrowser) => void, updateDeps?: unknown[]): T | null;
+export declare function useTrackManager<T extends Track, F = unknown>(addTrack: (browser: GenomeBrowser) => T, recreationDeps: unknown[], updateTrack?: (track: T, browser: GenomeBrowser) => void, updateDeps?: unknown[], eventHandlers?: TrackEventHandlers<F>): T | null;

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

@@ -1,8 +1,11 @@
 export { LoomBrowser } from './LoomBrowser';
 export type { LoomBrowserProps, LoomBrowserHandle } from './LoomBrowser';
 export { useGenomeBrowser, useBrowserEvent, useLocus } from './hooks';
+export type { TrackClickEvent } from './hooks';
 export { RulerTrack, WigTrack, GeneTrack, BedTrack, SequenceTrack, InteractionTrack, GtxTrack, } from './tracks';
 export type { RulerTrackProps, WigTrackProps, GeneTrackProps, BedTrackProps, SequenceTrackProps, InteractionTrackProps, GtxTrackProps, } from './tracks';
+export { DeclarativeROISet as ROISet } from './ROISet';
+export type { ROISetProps } from './ROISet';
 export { ChromosomeSelect, LocusInput, ZoomControls, WindowSize, ExportControls, Navbar, } from './ui';
 export type { ChromosomeSelectProps, LocusInputProps, ZoomControlsProps, WindowSizeProps, ExportControlsProps, NavbarProps, } from './ui';
 export { GenomeBrowserContext } from './GenomeBrowserContext';

package/dist/types/react/tracks/BedTrack.d.ts

@@ -1,11 +1,13 @@
 import type { AnnotationFeature, AnnotationRenderConfig, TextFileFormat } from '../../types';
+import type { TrackClickEvent } from '../hooks/useTrackManager';
+type BedFeature = AnnotationFeature & {
+    chr: string;
+};
 export interface BedTrackProps {
     /** URL to a BED/peak file. Mutually exclusive with `features`. */
     url?: string;
     /** In-memory annotation features. Mutually exclusive with `url`. Features must include `chr`. */
-    features?: (AnnotationFeature & {
-        chr: string;
-    })[];
+    features?: BedFeature[];
     config?: Partial<AnnotationRenderConfig>;
     height?: number;
     background?: string;
@@ -15,5 +17,12 @@ export interface BedTrackProps {
     maxTrackHeight?: number;
     name?: string;
     metadata?: Record<string, string>;
+    /** Compute per-feature color. Applied to in-memory features before rendering. */
+    colorBy?: (feature: BedFeature) => string;
+    /** Called when this track is clicked. Features are typed as BedFeature. */
+    onClick?: (event: TrackClickEvent<BedFeature>) => void;
+    /** Called when this track is right-clicked. */
+    onContextMenu?: (event: TrackClickEvent<BedFeature>) => void;
 }
-export declare function BedTrack({ url, features, config, height, background, format, indexURL, indexed, maxTrackHeight, name, metadata }: BedTrackProps): null;
+export declare function BedTrack({ url, features, config, height, background, format, indexURL, indexed, maxTrackHeight, name, metadata, colorBy, onClick, onContextMenu }: BedTrackProps): null;
+export {};

package/dist/types/react/tracks/GeneTrack.d.ts

@@ -1,4 +1,5 @@
-import type { AnnotationRenderConfig } from '../../types';
+import type { AnnotationFeature, AnnotationRenderConfig } from '../../types';
+import type { TrackClickEvent } from '../hooks/useTrackManager';
 export interface GeneTrackProps {
     config?: Partial<AnnotationRenderConfig>;
     height?: number;
@@ -10,5 +11,9 @@ export interface GeneTrackProps {
     maxTrackHeight?: number;
     name?: string;
     metadata?: Record<string, string>;
+    /** Called when this track is clicked. Features are typed as AnnotationFeature. */
+    onClick?: (event: TrackClickEvent<AnnotationFeature>) => void;
+    /** Called when this track is right-clicked. */
+    onContextMenu?: (event: TrackClickEvent<AnnotationFeature>) => void;
 }
-export declare function GeneTrack({ config, height, background, genome, track, maxTrackHeight, name, metadata }: GeneTrackProps): null;
+export declare function GeneTrack({ config, height, background, genome, track, maxTrackHeight, name, metadata, onClick, onContextMenu }: GeneTrackProps): null;

package/dist/types/react/tracks/GtxTrack.d.ts

@@ -1,4 +1,5 @@
-import type { WigRenderConfig, WindowFunction } from '../../types';
+import type { WigFeature, WigRenderConfig, WindowFunction } from '../../types';
+import type { TrackClickEvent } from '../hooks/useTrackManager';
 export interface GtxTrackProps {
     url: string;
     experimentId: string;
@@ -9,5 +10,9 @@ export interface GtxTrackProps {
     maxTrackHeight?: number;
     name?: string;
     metadata?: Record<string, string>;
+    /** Called when this track is clicked. Features are typed as WigFeature. */
+    onClick?: (event: TrackClickEvent<WigFeature>) => void;
+    /** Called when this track is right-clicked. */
+    onContextMenu?: (event: TrackClickEvent<WigFeature>) => void;
 }
-export declare function GtxTrack({ url, experimentId, config, height, background, windowFunction, maxTrackHeight, name, metadata }: GtxTrackProps): null;
+export declare function GtxTrack({ url, experimentId, config, height, background, windowFunction, maxTrackHeight, name, metadata, onClick, onContextMenu }: GtxTrackProps): null;

package/dist/types/react/tracks/InteractionTrack.d.ts

@@ -1,4 +1,5 @@
 import type { InteractionRenderConfig, TextFileFormat } from '../../types';
+import type { TrackClickEvent } from '../hooks/useTrackManager';
 export interface InteractionTrackProps {
     url: string;
     config?: Partial<InteractionRenderConfig>;
@@ -8,5 +9,9 @@ export interface InteractionTrackProps {
     indexed?: boolean;
     name?: string;
     metadata?: Record<string, string>;
+    /** Called when this track is clicked. */
+    onClick?: (event: TrackClickEvent<unknown>) => void;
+    /** Called when this track is right-clicked. */
+    onContextMenu?: (event: TrackClickEvent<unknown>) => void;
 }
-export declare function InteractionTrack({ url, config, background, format, indexURL, indexed, name, metadata }: InteractionTrackProps): null;
+export declare function InteractionTrack({ url, config, background, format, indexURL, indexed, name, metadata, onClick, onContextMenu }: InteractionTrackProps): null;