loom-browser 0.0.5 → 0.0.7

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';

package/dist/types/tracks/baseTrackCanvas.d.ts

@@ -12,7 +12,7 @@
  *
  * This eliminates ~80 lines of identical boilerplate per track type.
  */
-import type { Locus, RenderContext, Track, TrackSessionConfig, HitTestResult, ContextMenuItem } from '../types';
+import type { Locus, RenderContext, Track, TrackSessionConfig, HitTestResult, ContextMenuItem, FeatureRect } from '../types';
 import type { RenderTheme } from '../themes/renderTheme';
 import type { CanvasProvider } from '../canvasProvider';
 export declare abstract class BaseTrackCanvas<TConfig> implements Track {
@@ -66,6 +66,12 @@ export declare abstract class BaseTrackCanvas<TConfig> implements Track {
      * Default: empty (no interactive features). Subclasses override.
      */
     hitTest(_x: number, _y: number): HitTestResult[];
+    /**
+     * 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(): FeatureRect[];
     /**
      * Return context menu items for a right-click at canvas-relative coordinates.
      * Default: undefined (no track-specific items). Subclasses override.

package/dist/types/tracks/interaction/interactionRenderer.d.ts

@@ -12,6 +12,7 @@
  * Layer 2 (Track Canvas): uses CanvasRenderingContext2D, no DOM.
  */
 import type { InteractionFeature, InteractionRenderConfig, RenderContext } from '../../types';
+import type { TrackNameLabelOptions } from '../trackLabel';
 /** Draw state stored on features during rendering for hit-testing. */
 export type InteractionDrawState = NestedDrawState | ProportionalDrawState | RectDrawState;
 interface NestedDrawState {
@@ -44,7 +45,9 @@ export interface DrawnInteractionFeature extends InteractionFeature {
  * Stateless: all state is passed in, no side effects beyond canvas drawing
  * and attaching drawState to features for hit-testing.
  */
-export declare function renderInteractionTrack(ctx: CanvasRenderingContext2D, features: DrawnInteractionFeature[], config: InteractionRenderConfig, rc: RenderContext): void;
+export declare function renderInteractionTrack(ctx: CanvasRenderingContext2D, features: DrawnInteractionFeature[], config: InteractionRenderConfig, rc: RenderContext, 
+/** Optional track name label overlay (top-left corner). */
+trackLabel?: TrackNameLabelOptions): void;
 /**
  * Format a genomic position for popup display.
  */

package/dist/types/tracks/trackLabel.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export interface TrackNameLabelOptions {
+    /** Track name to display. */
+    name: string;
+    /** Background color for the pill (usually matches track background). */
+    background: string;
+    /** Text and border color. */
+    labelColor: string;
+    /** Extra vertical offset from top in pixels (e.g., to clear data range labels). Default: 0. */
+    topOffset?: number;
+}
+/**
+ * Render a track name as a horizontal overlay in the top-left corner.
+ * Draws a semi-transparent background pill behind the text for readability.
+ */
+export declare function renderTrackNameLabel(ctx: CanvasRenderingContext2D, options: TrackNameLabelOptions, pixelHeight: number): void;

package/dist/types/tracks/wig/wigTrackCanvas.d.ts

@@ -52,6 +52,8 @@ export declare class WigTrackCanvas extends BaseTrackCanvas<WigRenderConfig> {
     private _seqAbort;
     /** Callback invoked when the user changes the windowing function via context menu. */
     private _onWindowFunctionChange?;
+    /** User-set config overrides, re-applied on theme change. */
+    private _userOverrides;
     readonly type = "wig";
     constructor(canvas: HTMLCanvasElement, options: WigTrackCanvasOptions);
     /** Set a callback invoked when the user changes the windowing function via context menu. */

package/dist/types/types.d.ts

@@ -541,6 +541,24 @@ export interface HitTestResult<F = unknown> {
     feature: F;
     popupData: PopupDataItem[];
 }
+/**
+ * A feature's visual bounding box in CSS pixel coordinates.
+ * Used by SVG overlay system for hover/click interactivity.
+ */
+export interface FeatureRect {
+    /** Reference to the source feature. */
+    feature: unknown;
+    /** Left edge in CSS pixels. */
+    x: number;
+    /** Top edge in CSS pixels. */
+    y: number;
+    /** Width in CSS pixels. */
+    width: number;
+    /** Height in CSS pixels. */
+    height: number;
+    /** Resolved feature color (used for highlight tint). */
+    color?: string;
+}
 /** Payload for trackclick / trackhover browser events. */
 export interface TrackInteractionEvent {
     track: Track;
@@ -736,7 +754,7 @@ export type SequenceSessionOverrides = Partial<SequenceRenderConfig>;
 /** Serializable subset of InteractionRenderConfig (all fields are already serializable). */
 export type InteractionSessionOverrides = Partial<InteractionRenderConfig>;
 /** Discriminated union for data source reconstruction. */
-export type DataSourceConfig = BigWigDataSourceConfig | GtxDataSourceConfig | UCSCDataSourceConfig | TextDataSourceConfig;
+export type DataSourceConfig = BigWigDataSourceConfig | GtxDataSourceConfig | UCSCDataSourceConfig | TextDataSourceConfig | MemoryDataSourceConfig;
 export interface BigWigDataSourceConfig {
     type: 'bigwig';
     url: string;
@@ -763,6 +781,9 @@ export interface TextDataSourceConfig {
     /** Whether the file is indexed (tabix). When absent, auto-detected from indexURL presence. */
     indexed?: boolean;
 }
+export interface MemoryDataSourceConfig {
+    type: 'memory';
+}
 /** Strand value for genomic features. */
 export type Strand = '+' | '-' | '.';
 /** Known text genomic file formats supported by the format detection system. */

package/dist/types/worker/dataSourceRegistry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DataSourceRegistry — manages long-lived DataSource instances inside a worker.
+ *
+ * Creates DataSource instances from serializable DataSourceConfig, caches them
+ * by instanceId, and manages per-fetch AbortControllers for cancellation.
+ *
+ * Runs inside a web worker or Node worker_threads context.
+ * Layer 1 (Data + Layout): no DOM.
+ */
+import type { DataSourceConfig, Locus } from '../types';
+export declare class DataSourceRegistry {
+    private readonly instances;
+    private readonly inflightAborts;
+    /**
+     * Create a DataSource from a serializable config and register it.
+     * The DataSource persists until destroy() is called.
+     */
+    create(instanceId: string, config: DataSourceConfig): void;
+    /**
+     * Fetch features from a registered DataSource.
+     * Creates an internal AbortController for cancellation via cancel().
+     */
+    fetch(instanceId: string, fetchId: number, locus: Locus, bpPerPixel: number): Promise<unknown[]>;
+    /** Abort an in-flight fetch by its fetchId. */
+    cancel(fetchId: number): void;
+    /**
+     * Call a setter method on a registered DataSource.
+     * Used for serializable configuration updates (setCumulativeOffsets, setWindowFunction, etc.).
+     */
+    configure(instanceId: string, method: string, args: unknown[]): void;
+    /** Destroy a DataSource instance and clean up. */
+    destroy(instanceId: string): void;
+}

package/dist/types/worker/dataSourceWorkerScript.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Web Worker entry point for DataSource-based data fetching.
+ *
+ * Hosts persistent DataSource instances that handle the full pipeline:
+ * network I/O → binary parsing → feature decoding → summarization.
+ *
+ * Communicates with the main thread via the DataSourceWorkerProvider protocol:
+ * create, fetch, configure, cancel, destroy messages.
+ *
+ * Signals readiness via postMessage({type: 'ready'}) after module initialization,
+ * following JBrowse 2's async worker init pattern (PR #2798).
+ */
+export {};

package/dist/types/worker/unifiedWorkerScript.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified Web Worker entry point — handles both stateless tasks and stateful data sources.
+ *
+ * Stateless tasks (pack, summarize, parseFeatures, etc.) are dispatched via handleTask().
+ * Stateful data sources (BigWig, Tabix, UCSC) are managed via DataSourceRegistry.
+ *
+ * Message protocol uses a discriminated union on the `type` field:
+ *   - 'task'      → stateless task dispatch (round-robin from main thread)
+ *   - 'create'    → create a persistent DataSource instance
+ *   - 'fetch'     → fetch features from a DataSource
+ *   - 'configure' → call a setter on a DataSource
+ *   - 'cancel'    → abort an in-flight fetch
+ *   - 'destroy'   → remove a DataSource instance
+ *
+ * Signals readiness via postMessage({type: 'ready'}) after module initialization.
+ */
+export {};

package/dist/types/worker/webDataSourceWorkerProvider.d.ts

@@ -0,0 +1,59 @@
+/**
+ * WebDataSourceWorkerProvider — browser implementation of DataSourceWorkerProvider.
+ *
+ * Creates a pool of web workers that host persistent DataSource instances.
+ * Uses sticky routing (URL hash → worker index) to preserve reader caches.
+ * Supports cancellation via cancel messages and async worker initialization.
+ *
+ * Usage:
+ *   const provider = new WebDataSourceWorkerProvider({
+ *       workerFactory: () => new Worker(new URL('./dataSourceWorkerScript.ts', import.meta.url)),
+ *       poolSize: 4,
+ *   })
+ *   const browser = new HeadlessGenomeBrowser({ ..., dataSourceWorkerProvider: provider })
+ *   // ...
+ *   provider.dispose()
+ */
+import type { DataSourceWorkerProvider } from '../dataSourceWorkerProvider';
+import type { DataSourceConfig, Locus } from '../types';
+export interface WebDataSourceWorkerProviderOptions {
+    /**
+     * URL to the data source worker script.
+     * Mutually exclusive with `workerFactory`.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Factory function that creates Worker instances.
+     * Recommended for bundlers (webpack 5, Vite):
+     *   workerFactory: () => new Worker(new URL('./dataSourceWorkerScript.ts', import.meta.url))
+     * Mutually exclusive with `workerUrl`.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Number of workers in the pool. DataSources are distributed via sticky routing.
+     * Default: 1.
+     */
+    poolSize?: number;
+}
+export declare class WebDataSourceWorkerProvider implements DataSourceWorkerProvider {
+    private workers;
+    private readyPromises;
+    private instanceToWorker;
+    private pendingFetches;
+    private nextFetchId;
+    constructor(options: WebDataSourceWorkerProviderOptions);
+    /** Number of workers in the pool. */
+    get poolSize(): number;
+    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;
+    /**
+     * Sticky routing: deterministically assign a DataSourceConfig to a worker
+     * based on its URL. All DataSources for the same URL go to the same worker,
+     * preserving reader caches (BigWig headers, Tabix indices).
+     */
+    private routeToWorker;
+    private send;
+}

package/dist/types/worker/webUnifiedWorkerProvider.d.ts

@@ -0,0 +1,64 @@
+/**
+ * WebUnifiedWorkerProvider — 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 provider = new WebUnifiedWorkerProvider({
+ *       workerFactory: () => new Worker(new URL('./unifiedWorkerScript.ts', import.meta.url)),
+ *       poolSize: 4,
+ *   })
+ *   const browser = new GenomeBrowser(container, { workerProvider: provider })
+ *   // browser auto-detects DataSourceWorkerProvider support
+ *   provider.dispose()
+ */
+import type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+import type { DataSourceWorkerProvider } from '../dataSourceWorkerProvider';
+import type { DataSourceConfig, Locus } from '../types';
+export interface WebUnifiedWorkerProviderOptions {
+    /**
+     * URL to the unified worker script.
+     * Mutually exclusive with `workerFactory`.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Factory function that creates Worker instances.
+     * Recommended for bundlers (webpack 5, Vite):
+     *   workerFactory: () => new Worker(new URL('./unifiedWorkerScript.ts', import.meta.url))
+     * Mutually exclusive with `workerUrl`.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Number of workers in the pool. Default: 1.
+     */
+    poolSize?: number;
+}
+export declare class WebUnifiedWorkerProvider implements WorkerProvider, DataSourceWorkerProvider {
+    private workers;
+    private readyPromises;
+    private nextId;
+    private nextWorker;
+    private pending;
+    private instanceToWorker;
+    private pendingFetches;
+    private nextFetchId;
+    constructor(options: WebUnifiedWorkerProviderOptions);
+    /** Number of workers in the pool. */
+    get poolSize(): number;
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    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;
+    /**
+     * Sticky routing: deterministically assign a DataSourceConfig to a worker
+     * based on its URL. Preserves reader caches (BigWig headers, Tabix indices).
+     */
+    private routeToWorker;
+}

package/dist/types/worker/webWorkerPool.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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()
+ */
+import type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+import type { DataSourceWorkerProvider } from '../dataSourceWorkerProvider';
+import type { DataSourceConfig, Locus } from '../types';
+export interface WebWorkerPoolOptions {
+    /**
+     * URL to the worker pool script.
+     * Mutually exclusive with `workerFactory`.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Factory function that creates Worker instances.
+     * Recommended for bundlers (webpack 5, Vite):
+     *   workerFactory: () => new Worker(new URL('./workerPoolScript.ts', import.meta.url))
+     * Mutually exclusive with `workerUrl`.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Number of workers in the pool. Default: 1.
+     */
+    poolSize?: number;
+}
+export declare class WebWorkerPool implements WorkerProvider, DataSourceWorkerProvider {
+    private workers;
+    private readyPromises;
+    private nextId;
+    private nextWorker;
+    private pending;
+    private instanceToWorker;
+    private pendingFetches;
+    private nextFetchId;
+    constructor(options: WebWorkerPoolOptions);
+    /** Number of workers in the pool. */
+    get poolSize(): number;
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    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;
+    /**
+     * Sticky routing: deterministically assign a DataSourceConfig to a worker
+     * based on its URL. Preserves reader caches (BigWig headers, Tabix indices).
+     */
+    private routeToWorker;
+}

package/dist/types/worker/workerPoolScript.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified Web Worker entry point — handles both stateless tasks and stateful data sources.
+ *
+ * Stateless tasks (pack, summarize, parseFeatures, etc.) are dispatched via handleTask().
+ * Stateful data sources (BigWig, Tabix, UCSC) are managed via DataSourceRegistry.
+ *
+ * Message protocol uses a discriminated union on the `type` field:
+ *   - 'task'      → stateless task dispatch (round-robin from main thread)
+ *   - 'create'    → create a persistent DataSource instance
+ *   - 'fetch'     → fetch features from a DataSource
+ *   - 'configure' → call a setter on a DataSource
+ *   - 'cancel'    → abort an in-flight fetch
+ *   - 'destroy'   → remove a DataSource instance
+ *
+ * Signals readiness via postMessage({type: 'ready'}) after module initialization.
+ */
+export {};

package/dist/types/workerDataSource.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+import type { DataSource, Locus } from './types';
+import type { CumulativeOffsets } from './genome/chromSizes';
+import type { DataSourceWorkerProvider } from './dataSourceWorkerProvider';
+import type { WindowFunction } from './types';
+export declare class WorkerDataSource<F = unknown> implements DataSource<F> {
+    private readonly provider;
+    readonly instanceId: string;
+    private resolver?;
+    constructor(provider: DataSourceWorkerProvider, instanceId: string);
+    fetch(locus: Locus, bpPerPixel: number, signal: AbortSignal): Promise<F[]>;
+    /**
+     * Set a chromosome name resolver. Stored locally — the proxy resolves
+     * chromosome names before forwarding the locus to the worker.
+     */
+    setChromNameResolver(resolver: (chr: string) => string): void;
+    /** Forward cumulative offsets to the worker-resident DataSource. */
+    setCumulativeOffsets(offsets: CumulativeOffsets): void;
+    /** Forward window function change to the worker-resident DataSource. */
+    setWindowFunction(wf: WindowFunction): void;
+}

package/dist/types/workerProvider.d.ts

@@ -11,8 +11,9 @@
  *   - WebWorkerProvider   — browser (Web Workers)
  *   - NodeWorkerProvider  — Node.js (worker_threads)
  */
-import type { AnnotationFeature, WigFeature, WindowFunction, TextFileFormat } from './types';
+import type { AnnotationFeature, WigFeature, WindowFunction, TextFileFormat, DataSourceConfig, Locus } from './types';
 import type { FeatureHeader } from './formats/featureParser';
+import type { DataSourceWorkerProvider } from './dataSourceWorkerProvider';
 export interface PackTask {
     task: 'pack';
     features: AnnotationFeature[];
@@ -65,11 +66,17 @@ export interface WorkerProvider {
 }
 /**
  * Runs all tasks on the main thread using direct function calls.
- * This is the default when no WorkerProvider is supplied.
+ * Implements both WorkerProvider (stateless tasks) and DataSourceWorkerProvider
+ * (stateful data sources) as the default fallback when no worker pool is available.
  */
-export declare class MainThreadProvider implements WorkerProvider {
+export declare class MainThreadProvider implements WorkerProvider, DataSourceWorkerProvider {
+    private readonly dsInstances;
     execute<T extends WorkerTask>(task: T): Promise<WorkerTaskResultMap[T['task']]>;
     private dispatch;
+    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;
 }
 /** Default worker provider: runs everything on the main thread. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loom-browser",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "main": "dist/loom.esm.js",
   "module": "dist/loom.esm.js",
   "types": "dist/types/index.d.ts",
@@ -83,6 +83,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@gmod/cram": "^5.0.5",
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-strip": "^3.0.1",
     "@rollup/plugin-terser": "^0.4.0",
     "@rollup/plugin-typescript": "^12.3.0",