loom-browser 0.0.6 → 0.0.7

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;

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.6",
+  "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",