loom-browser 0.0.1

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

@@ -0,0 +1,51 @@
+/**
+ * WebWorkerProvider — browser Web Worker implementation of WorkerProvider.
+ *
+ * Creates a pool of worker threads and dispatches tasks via round-robin.
+ * Supports Transferable for zero-copy ArrayBuffer transfer.
+ *
+ * Usage:
+ *   const provider = new WebWorkerProvider({ workerUrl: '/loom-worker.js', poolSize: 4 })
+ *   const browser = new GenomeBrowser({ ..., workerProvider: provider })
+ *   // ...
+ *   provider.dispose()
+ */
+import type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+export interface WebWorkerProviderOptions {
+    /**
+     * URL to the worker script (built from workerScript.ts).
+     * Can be a blob URL, data URL, or path to a bundled worker script.
+     * Mutually exclusive with `workerFactory`.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Factory function that creates Worker instances.
+     * Use this with bundlers like webpack 5 that require `new Worker(new URL(...))` in
+     * the same expression for static analysis:
+     *
+     *   workerFactory: () => new Worker(new URL('./workerScript.ts', import.meta.url))
+     *
+     * Mutually exclusive with `workerUrl`.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Number of workers in the pool. Tasks are distributed round-robin.
+     * Default: 1.
+     */
+    poolSize?: number;
+}
+export declare class WebWorkerProvider implements WorkerProvider {
+    private workers;
+    private nextId;
+    private nextWorker;
+    private pending;
+    /**
+     * @param optionsOrUrl - Options object with workerUrl and poolSize,
+     *   or a URL string/URL for backward compatibility (single worker).
+     */
+    constructor(optionsOrUrl: WebWorkerProviderOptions | string | URL);
+    /** Number of workers in the pool. */
+    get poolSize(): number;
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    dispose(): void;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Web Worker entry point.
+ *
+ * This file is the script that runs inside the Web Worker. It listens
+ * for messages from the main thread, dispatches them to the task handler,
+ * and posts results back.
+ *
+ * Bundle this file as a standalone module (e.g. via Rollup/Vite worker plugin)
+ * and pass the resulting URL to WebWorkerProvider.
+ */
+export {};

package/dist/types/workerProvider.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WorkerProvider — environment abstraction for offloading CPU-intensive tasks.
+ *
+ * Follows the same injection pattern as CanvasProvider:
+ *   - Interface with minimal methods
+ *   - Concrete implementations for each environment
+ *   - Optional injection with a sensible default (MainThreadProvider)
+ *
+ * Implementations:
+ *   - MainThreadProvider  — synchronous fallback (runs tasks on main thread)
+ *   - WebWorkerProvider   — browser (Web Workers)
+ *   - NodeWorkerProvider  — Node.js (worker_threads)
+ */
+import type { AnnotationFeature, WigFeature, WindowFunction, TextFileFormat } from './types';
+import type { FeatureHeader } from './formats/featureParser';
+export interface PackTask {
+    task: 'pack';
+    features: AnnotationFeature[];
+    maxRows?: number;
+}
+export interface SummarizeWigTask {
+    task: 'summarize';
+    features: WigFeature[];
+    startBP: number;
+    bpPerPixel: number;
+    windowFunction: WindowFunction;
+}
+export interface ComputeWigRangeTask {
+    task: 'computeWigRange';
+    features: WigFeature[];
+}
+export interface ParseFeaturesTask {
+    task: 'parseFeatures';
+    /** Raw text lines to parse. */
+    lines: string[];
+    /** File format (bed, gff3, narrowpeak, etc.). */
+    format: TextFileFormat;
+    /** Pre-parsed header metadata. */
+    header?: FeatureHeader;
+    /** Whether to assemble GFF transcripts. Default: true. */
+    assembleGFF?: boolean;
+}
+export type WorkerTask = PackTask | SummarizeWigTask | ComputeWigRangeTask | ParseFeaturesTask;
+/** Maps task name → result type. */
+export interface WorkerTaskResultMap {
+    pack: AnnotationFeature[];
+    summarize: WigFeature[];
+    computeWigRange: {
+        min: number;
+        max: number;
+    };
+    parseFeatures: unknown[];
+}
+/**
+ * Execute CPU-intensive tasks, potentially in a worker thread.
+ *
+ * The `transfer` parameter accepts `Transferable` objects (e.g. `ArrayBuffer`)
+ * for zero-copy transfer to the worker. After transfer, the original buffer
+ * becomes detached on the sending side.
+ */
+export interface WorkerProvider {
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    /** Terminate worker threads and release resources. */
+    dispose(): void;
+}
+/**
+ * Runs all tasks on the main thread using direct function calls.
+ * This is the default when no WorkerProvider is supplied.
+ */
+export declare class MainThreadProvider implements WorkerProvider {
+    execute<T extends WorkerTask>(task: T): Promise<WorkerTaskResultMap[T['task']]>;
+    private dispatch;
+    dispose(): void;
+}
+/** Default worker provider: runs everything on the main thread. */
+export declare const mainThreadProvider: WorkerProvider;

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "loom-browser",
+  "version": "0.0.1",
+  "main": "dist/loom.esm.js",
+  "browser": "dist/loom.js",
+  "module": "dist/loom.esm.js",
+  "types": "dist/types/index.d.ts",
+  "type": "module",
+  "description": "A modular, headless-first genomic visualization engine built in TypeScript",
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "prepare": "npm run build",
+    "build": "npx rollup --config rollup.config.src.js",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage && npm run --prefix docs-site test:stories:coverage && node scripts/mergeCoverage.js",
+    "typecheck": "tsc --noEmit -p tsconfig.src.json",
+    "lint": "eslint src/",
+    "docs:start": "npm run --prefix docs-site start",
+    "docs:build": "npm run --prefix docs-site build",
+    "storybook": "npm run --prefix docs-site storybook",
+    "storybook:build": "npm run --prefix docs-site build-storybook",
+    "test:visual": "npm run --prefix docs-site test:visual",
+    "test:visual:update": "npm run --prefix docs-site test:visual:update",
+    "test:stories": "npm run --prefix docs-site test:stories",
+    "test:stories:coverage": "npm run --prefix docs-site test:stories:coverage"
+  },
+  "author": {
+    "name": "Riya Sinha",
+    "url": "https://github.com/riyavsinha"
+  },
+  "contributors": [
+    {
+      "name": "Jim Robinson",
+      "url": "https://github.com/jrobinso"
+    },
+    {
+      "name": "Douglass Turner"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/riyavsinha/loom/issues"
+  },
+  "homepage": "https://github.com/riyavsinha/loom",
+  "keywords": [
+    "genomics",
+    "visualization",
+    "bioinformatics",
+    "typescript",
+    "headless",
+    "canvas"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riyavsinha/loom.git"
+  },
+  "browserslist": "> 1%, not dead",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@gmod/cram": "^5.0.5",
+    "@rollup/plugin-strip": "^3.0.1",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/jsdom": "^28.0.1",
+    "@types/mocha": "^10.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@xmldom/xmldom": "^0.7.9",
+    "atob": "^2.1.2",
+    "btoa": "^1.2.1",
+    "chai": "^4.3.7",
+    "circular-view": "github:igvteam/circular-view#v0.2.4",
+    "dompurify": "^3.0.9",
+    "eslint": "^10.0.3",
+    "fs-extra": "^11.3.0",
+    "globals": "^17.4.0",
+    "hdf5-indexed-reader": "github:jrobinso/hdf5-indexed-reader#v1.0.2",
+    "hic-straw": "^2.1.3",
+    "igv-utils": "github:igvteam/igv-utils#v1.7.1",
+    "jsdom": "^29.0.0",
+    "mocha": "^11.1.0",
+    "rollup": "^2.66.0",
+    "rollup-plugin-copy": "^3.3.0",
+    "sass": "^1.45.1",
+    "tslib": "^2.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.1-rc",
+    "vanilla-picker": "^2.12.3",
+    "vitest": "^3.2.4",
+    "w3c-xmlhttprequest": "^3.0.0",
+    "ws": "^8.18.3"
+  },
+  "dependencies": {
+    "@gmod/bbi": "^9.0.0",
+    "@gmod/tabix": "^3.2.2",
+    "generic-filehandle2": "^2.0.18"
+  }
+}