loom-browser 0.0.1

package/dist/types/src/formats/formatDetection.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Format detection from URL/filename and track type inference.
+ *
+ * Port of js/util/fileFormatUtils.ts (inferFileFormatFromName, knownFileExtensions)
+ * and js/util/trackUtils.ts (inferTrackType).
+ *
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+/** Comprehensive set of known file extensions. Port of js/util/fileFormatUtils.ts. */
+export declare const knownFileExtensions: ReadonlySet<string>;
+/**
+ * Infer file format from a URL or filename.
+ *
+ * Strips compression extensions (.gz, .bgz), auxiliary extensions (.txt, .tab, .tsv),
+ * then checks the remaining extension against known formats.
+ *
+ * Port of js/util/fileFormatUtils.ts::inferFileFormatFromName().
+ */
+export declare function inferFormatFromPath(path: string): string | undefined;
+/** Check if a format string represents a binary (non-text) format. */
+export declare function isBinaryFormat(format: string): boolean;
+/** BigWig/BigBed format set — these use BWSource in igv.js. */
+export declare const bbFormats: Set<string>;
+/**
+ * Check if a URL is likely tabix-indexed.
+ *
+ * Only `.bgz` (bgzip-specific extension) is auto-detected as indexed.
+ * Plain `.gz` files may be either bgzipped+tabix-indexed or plain gzipped,
+ * so callers should explicitly set `indexed: true` or provide an `indexURL`
+ * for those. This matches igv.js behavior where indexURL must be configured
+ * for BED/GFF files to use tabix.
+ */
+export declare function isLikelyIndexed(url: string): boolean;
+/**
+ * Infer the tabix index URL from a data file URL.
+ * Appends '.tbi' to the URL (respecting query parameters).
+ *
+ * Port of js/util/fileFormatUtils.ts::inferIndexPath().
+ */
+export declare function inferIndexURL(url: string): string;
+/**
+ * Infer the track type from a file format.
+ *
+ * Port of js/util/trackUtils.ts::inferTrackType().
+ */
+export declare function inferTrackType(format: string | undefined): string | undefined;

package/dist/types/src/genome/chromAlias.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Default chromosome alias resolution.
+ *
+ * Computes NCBI↔UCSC mappings (chr1↔1, chrM↔MT) and case aliases from
+ * chromosome names. This covers the ~90% case where BigWig/BAM files use
+ * a different naming convention than the genome.
+ *
+ * Port of js/genome/chromAliasDefaults.ts. In our architecture this is
+ * Layer 1 (Data + Layout): pure data, no DOM.
+ *
+ * Extension points for file-based (ChromAliasFile) and BigBed-based
+ * (ChromAliasBB) alias sources can be added later by implementing the
+ * same interface and wiring into GenomeImpl.
+ */
+import type { ChromAliasRecord } from '../types';
+/**
+ * Add case-insensitivity and chr-prefix aliases to an alias record.
+ * Reusable by future ChromAliasFile/ChromAliasBB implementations.
+ *
+ * Mirrors igv.js ChromAliasDefaults.addCaseAliases (js/genome/chromAliasDefaults.ts).
+ */
+export declare function addCaseAliases(record: ChromAliasRecord): void;
+/**
+ * Default chromosome alias resolver.
+ *
+ * Builds a bidirectional alias cache from chromosome names at construction time.
+ * All lookups are synchronous (no network). Covers:
+ * - NCBI↔UCSC numeric mapping (chr1↔1, chrM↔MT)
+ * - Human sex chromosomes (23↔chrX, 24↔chrY) for hg, GRCh, b37 genomes
+ * - Mouse sex chromosomes (21↔chrX, 22↔chrY) for mm, GRCm, rheMac genomes
+ * - Case aliases (uppercase, lowercase, capitalized, chr-prefix-flipped)
+ * - NCBI gi| accession parsing
+ *
+ * Mirrors igv.js ChromAliasDefaults (js/genome/chromAliasDefaults.ts).
+ */
+export declare class ChromAliasDefaults {
+    private cache;
+    constructor(chromosomeNames: string[], genomeId?: string);
+    /** Resolve alias to canonical name. Returns undefined if not found. */
+    getChromosomeName(alias: string): string | undefined;
+    /** Get full alias record for a chromosome or alias. */
+    getAliasRecord(alias: string): ChromAliasRecord | undefined;
+    private buildAliases;
+    private addHumanSexAliases;
+    private addMouseSexAliases;
+}

package/dist/types/src/genome/chromSizes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Chromosome size data and utilities.
+ *
+ * Provides a lightweight ChromSizes type (chr → bp length), a default
+ * hg38 dataset, and genome coordinate system utilities for whole genome view.
+ */
+/** Mapping of chromosome names to their lengths in base pairs. */
+export type ChromSizes = Record<string, number>;
+/**
+ * Look up the length of a chromosome. Returns undefined if not found.
+ */
+export declare function getChromLength(chr: string, chromSizes?: ChromSizes): number | undefined;
+/** Precomputed genome-wide coordinate system for whole genome view. */
+export interface CumulativeOffsets {
+    /** Chromosome name → genome-wide start position. */
+    offsets: Record<string, number>;
+    /** Total length of all main chromosomes. */
+    totalLength: number;
+    /** Ordered chromosome names used in the WG view. */
+    chromosomeNames: string[];
+}
+/** Check if a chromosome name is a "main" chromosome (chr1-22, X, Y, M). */
+export declare function isMainChromosome(name: string): boolean;
+/**
+ * Return ordered list of main chromosome names from chromSizes.
+ * Order: chr1-22 (numeric), chrX, chrY, chrM.
+ */
+export declare function mainChromosomeNames(chromSizes: ChromSizes): string[];
+/**
+ * Compute cumulative genome-wide offsets for main chromosomes.
+ * Used to map per-chromosome coordinates to a linear genome-wide space.
+ */
+export declare function computeCumulativeOffsets(chromSizes: ChromSizes): CumulativeOffsets;
+/**
+ * Convert a genome-wide coordinate back to chromosome-relative coordinates.
+ * Returns the chromosome and position within it.
+ */
+export declare function genomeToChromCoord(genomePos: number, cumOffsets: CumulativeOffsets): {
+    chr: string;
+    position: number;
+};
+/**
+ * Parse a tab-separated chrom.sizes file into a ChromSizes record.
+ * Format: one line per chromosome, `name\tlength`, with optional comments (#).
+ * Mirrors the UCSC chrom.sizes file format.
+ */
+export declare function parseChromSizes(text: string): ChromSizes;
+/**
+ * GRCh38/hg38 chromosome sizes.
+ * Includes main chromosomes (chr1-22, X, Y, M) plus all contigs and alts.
+ * Source: UCSC hg38.chrom.sizes
+ */
+export declare const hg38ChromSizes: ChromSizes;

package/dist/types/src/genome/genome.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Genome assembly abstraction.
+ *
+ * Provides a unified `Genome` object that encapsulates chromosome metadata,
+ * cumulative offsets for whole genome view, and optional sequence access.
+ *
+ * Mirrors igv.js `Genome` class (js/genome/genome.ts) which provides:
+ * - Chromosome sizes and metadata
+ * - Sequence access via CachedSequence wrapping FASTA/2bit/UCSC API
+ * - Cumulative offsets for genome-wide coordinate conversion
+ * - Chromosome alias resolution via ChromAliasDefaults (Gap #6)
+ *
+ * In our architecture this is Layer 1 (Data + Layout): pure data, no DOM.
+ * The HeadlessGenomeBrowser (Layer 3) takes a Genome and derives chromSizes,
+ * cumulativeOffsets, and sequenceProvider from it.
+ *
+ * Factory functions:
+ * - `createGenomeSync()` — synchronous, requires inline chromSizes
+ * - `createGenome()` — async, can fetch chromSizes from URL
+ * - `hg38Genome` — pre-built singleton for the default human genome
+ */
+import type { Genome, GenomeConfig } from '../types';
+import type { ChromSizes } from './chromSizes';
+/**
+ * Create a Genome synchronously from inline chromosome sizes.
+ *
+ * Use when chromSizes are already available (e.g., built-in genomes,
+ * or after fetching from a URL yourself).
+ */
+export declare function createGenomeSync(config: GenomeConfig & {
+    chromSizes: ChromSizes;
+}): Genome;
+/**
+ * Create a Genome asynchronously.
+ *
+ * Supports:
+ * - Built-in genome IDs (e.g., "hg38") — uses hardcoded chromSizes
+ * - Inline chromSizes — same as createGenomeSync
+ * - chromSizesURL — fetches and parses tab-separated chrom.sizes file
+ *
+ * Mirrors igv.js `Genome.createGenome(config, browser)` (js/genome/genome.ts)
+ * which loads sequence, cytobands, and chromosomes asynchronously.
+ */
+export declare function createGenome(config: GenomeConfig): Promise<Genome>;
+/**
+ * Pre-built hg38 genome with UCSC sequence API.
+ *
+ * This is the default genome used by HeadlessGenomeBrowser when no genome
+ * is specified. Equivalent to igv.js's default behavior of loading hg38.
+ */
+export declare const hg38Genome: Genome;

package/dist/types/src/genomeBrowser.d.ts

@@ -0,0 +1,189 @@
+/**
+ * DOM-attached GenomeBrowser — extends HeadlessGenomeBrowser with pointer events,
+ * ResizeObserver, canvas stacking, and sweep-to-zoom.
+ *
+ * Coordinates multiple Track instances, stacking them vertically in a container.
+ * Static rendering is the base — interactivity (drag-to-pan) is enabled by default
+ * but can be disabled via `interactive: false`.
+ *
+ * Ruler tracks get special treatment: dragging on a ruler creates a selection
+ * overlay (sweep-to-zoom) instead of panning.
+ *
+ * Usage:
+ *   const browser = new GenomeBrowser(container, {
+ *       locus: { chr: 'chr17', start: 7668000, end: 7688000 },
+ *   })
+ *   browser.addTrack(rulerTrack)
+ *   browser.addTrack(geneTrack)
+ *   // Drag to pan — works out of the box.
+ *   // Drag on ruler — sweep to zoom.
+ *   // Cleanup:
+ *   browser.dispose()
+ */
+import type { Track, DataSource, SessionConfig, DataSourceConfig } from "./types";
+import { HeadlessGenomeBrowser } from "./headlessGenomeBrowser";
+import type { HeadlessGenomeBrowserOptions } from "./headlessGenomeBrowser";
+import type { RemoteSocket } from "./remoteProtocol";
+import type { CreateTrackFromSessionOptions } from "./session";
+export { BrowserEvent } from "./headlessGenomeBrowser";
+export type { BrowserEvents } from "./headlessGenomeBrowser";
+export interface GenomeBrowserOptions extends HeadlessGenomeBrowserOptions {
+    /** Enable mouse/touch drag to pan. Default: true. */
+    interactive?: boolean;
+    /** Enable trackpad pinch and scroll-wheel zoom. Default: true when interactive. */
+    wheelZoom?: boolean;
+}
+export declare class GenomeBrowser extends HeadlessGenomeBrowser {
+    private container;
+    private interactive;
+    private isDragging;
+    private lastPointerX;
+    private isSweeping;
+    private sweepStartX;
+    private sweepOverlay;
+    private sweepRulerCanvas;
+    private pointerDownX;
+    private pointerDownY;
+    private pointerDownTarget;
+    private lastClickTime;
+    private lastClickX;
+    private lastClickY;
+    private singleClickTimer;
+    private hoverThrottleId;
+    private _rafId;
+    private resizeObserver;
+    private trackRows;
+    private handleContextMenu;
+    private inputDialog;
+    private remoteConnection;
+    private reorderDragTrack;
+    private reorderDragRow;
+    private reorderHandlers;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleMouseMove;
+    private handleMouseLeave;
+    private handleDocMouseDown;
+    private handleWheel;
+    private wheelRafId;
+    private roiOverlayContainer;
+    private roiElements;
+    constructor(container: HTMLElement, options: GenomeBrowserOptions);
+    /** Add a track and attach its canvas to the container. */
+    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: 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. */
+    moveTrack(track: Track, toIndex: number): void;
+    /**
+     * Load a session, replacing all current tracks.
+     * Removes existing canvases from the DOM, then delegates to the headless
+     * implementation which recreates tracks. New canvases are attached via addTrack().
+     */
+    loadSession(session: SessionConfig, options?: CreateTrackFromSessionOptions): void;
+    /** Re-render all tracks, reading width from the DOM container. */
+    render(): void;
+    /** Clean up event listeners, remove canvases, and dispose headless core. */
+    /**
+     * Attach a remote WebSocket connection.
+     * Incoming command messages are automatically dispatched.
+     * Browser events are automatically forwarded.
+     */
+    attachRemote(socket: RemoteSocket): void;
+    /** Detach the remote connection and stop forwarding events. */
+    detachRemote(): void;
+    dispose(): void;
+    /**
+     * Update the axis content for a track based on its getAxisInfo().
+     * Uses a canvas for quantitative axes (tick marks + labels) matching igv.js paintAxis,
+     * and a DOM label for annotation tracks (e.g., gene track name).
+     */
+    private updateAxisContent;
+    /**
+     * Prepare an axis canvas at the correct size with DPR scaling,
+     * then delegate to the given stateless render function.
+     */
+    private paintAxisCanvas;
+    /** Check if a pointer event target is a ruler track canvas. */
+    private isRulerCanvas;
+    private createSweepOverlay;
+    private removeSweepOverlay;
+    private setupDragHandlers;
+    /** Check if an event originated inside an overlay UI component (Shadow DOM) or ROI element. */
+    private isOverlayTarget;
+    /** Find the track whose canvas contains the given event target. */
+    private findTrackForTarget;
+    /** Canvas-relative coordinates from a mouse/pointer event. */
+    private canvasCoords;
+    private handleClick;
+    private setupHoverHandlers;
+    private teardownHoverHandlers;
+    private setupContextMenuHandler;
+    private teardownContextMenuHandler;
+    /** Reorder DOM rows to match managedTracks order. */
+    private syncDOMOrder;
+    /** Set up drag-to-reorder pointer handlers on an axis div. */
+    private setupReorderHandlers;
+    /** Remove reorder handlers for a track. */
+    private teardownReorderHandlers;
+    private teardownDragHandlers;
+    /**
+     * Set up wheel event handling for trackpad pinch-to-zoom and scroll-wheel zoom.
+     *
+     * Trackpad pinch gestures on macOS/Chrome are reported as `wheel` events with
+     * `ctrlKey: true` and `deltaY` indicating zoom direction. Regular scroll-wheel
+     * events (ctrl+scroll) use the same mechanism. Both zoom around the pointer
+     * position for natural, cursor-anchored zoom behavior.
+     */
+    private setupWheelHandler;
+    private teardownWheelHandler;
+    /** Ensure the ROI overlay container exists and is sized correctly. */
+    private ensureROIOverlayContainer;
+    /**
+     * Render ROI overlays as DOM elements positioned over the track viewport.
+     *
+     * Creates/updates/removes DOM elements for each visible ROI.
+     * DOM-based (not canvas) for easy hover/click interaction without
+     * re-rendering track canvases.
+     */
+    private renderROIOverlays;
+    /** Create a styled DOM element for an ROI region. */
+    private createROIElement;
+    /** Show context menu for an ROI. */
+    private showROIContextMenu;
+    /** Clean up ROI overlay elements. */
+    private clearROIOverlay;
+    /**
+     * Export the current view as an SVG string, including axis columns.
+     *
+     * Overrides HeadlessGenomeBrowser.toSVG() to add axis rendering on the
+     * left side of each track, matching igv.js Browser.toSVG() which calls
+     * renderSVGAxis() for each TrackView (js/browser.ts lines 352-388).
+     */
+    toSVG(options?: {
+        width?: number;
+        backdropColor?: string;
+    }): string;
+    /**
+     * Export the current view as a PNG data URL.
+     *
+     * Pipeline: toSVG() → Blob → Image → Canvas (DPR-scaled) → toDataURL.
+     * Matches igv.js Browser.savePNGtoFile() (js/browser.ts lines 407-440).
+     *
+     * Returns a promise that resolves to a `data:image/png;base64,...` string.
+     */
+    toPNG(): Promise<string>;
+    /**
+     * Download the current view as an SVG file.
+     * Matches igv.js Browser.saveSVGtoFile() (js/browser.ts lines 390-405).
+     */
+    saveSVGtoFile(filename?: string): void;
+    /**
+     * Download the current view as a PNG file.
+     * Matches igv.js Browser.savePNGtoFile() (js/browser.ts lines 407-440).
+     */
+    savePNGtoFile(filename?: string): Promise<void>;
+    /** Trigger a file download via a temporary anchor element. */
+    private downloadURL;
+}

package/dist/types/src/gtx/fetchCoordinator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GTX fetch coordinator — batches requests from multiple GtxDataSource
+ * instances into a single readFeatures() call.
+ *
+ * When loadAllTracksIfNeeded fires for 5 GTX tracks, all 5
+ * GtxDataSource.fetch() calls run synchronously in the same tick.
+ * Each calls coordinator.request() which is synchronous — no awaits
+ * before the batching logic. Requests are collected, then flushed
+ * on the next microtask as a single readFeatures() call with all
+ * experiment indexes, merging byte ranges across experiments.
+ *
+ * Layer 1 (Data + Layout): no DOM, no canvas.
+ */
+import { GtxReader } from './gtxReader';
+import type { WigFeature, Locus } from '../types';
+export declare function getCoordinator(url: string, reader: GtxReader): GtxFetchCoordinator;
+export declare function clearCoordinators(): void;
+export declare class GtxFetchCoordinator {
+    private url;
+    private reader;
+    private pending;
+    constructor(url: string, reader: GtxReader);
+    /**
+     * Request features for one experiment. Fully synchronous — collects the
+     * request and returns a promise that resolves when the batch flushes.
+     *
+     * The flush handles reader.init() internally, so callers do NOT need
+     * to await init() before calling this. This is critical: if callers
+     * awaited init(), the await would yield and each continuation would
+     * resume in a separate microtask, defeating batching.
+     */
+    request(experimentId: string, locus: Locus, bpPerPixel: number, signal?: AbortSignal): Promise<WigFeature[]>;
+    private flush;
+}

package/dist/types/src/gtx/gtxReader.d.ts

@@ -0,0 +1,144 @@
+/**
+ * GTX file reader — binary format for bundled genomic signal data.
+ *
+ * A GTX file packs multiple experiments (BigWig-equivalent signal tracks) into
+ * a single file with:
+ * - Tile-based indexing (flat arrays, not R-trees)
+ * - zstd dictionary compression for small chunk sizes
+ * - Per-experiment metadata
+ * - Multi-resolution zoom levels
+ *
+ * Uses HTTP Range Requests for selective remote access — never downloads
+ * the full file.
+ *
+ * Layer 1 (Data + Layout): no DOM, no canvas.
+ */
+import type { WigFeature } from '../types';
+export interface GtxHeader {
+    version: number;
+    genome: string;
+    nExperiments: number;
+    resolution: number;
+    payloadEncoding: number;
+    nZoomLevels: number;
+    chromDirectoryOffset: number;
+    experimentMetadataOffset: number;
+    dictionaryOffset: number;
+    dictionarySize: number;
+    zoomDirectoryOffset: number;
+    groupStatsDirectoryOffset: number;
+}
+export interface ChromEntry {
+    name: string;
+    length: number;
+    tileIndexOffset: number;
+    tileIndexLength: number;
+    nTiles: number;
+}
+export interface ExperimentEntry {
+    id: string;
+    experimentIndex: number;
+    metadata: Map<string, string>;
+}
+export interface ExperimentPointer {
+    offset: number;
+    size: number;
+}
+export interface TileEntry {
+    positionsOffset: number;
+    positionsSize: number;
+    experimentPointers: ExperimentPointer[];
+}
+export interface ZoomLevel {
+    reductionLevel: number;
+    chromTileIndexes: Map<string, ZoomChromEntry>;
+}
+export interface ZoomChromEntry {
+    tileIndexOffset: number;
+    tileIndexLength: number;
+    nTiles: number;
+}
+export declare class GtxReader {
+    private readonly url;
+    private header?;
+    private dictionary?;
+    private dctx?;
+    private experiments;
+    private experimentIdToIndex;
+    private chromosomes;
+    private chromOrder;
+    private tileIndexCache;
+    private zoomLevels;
+    private zoomTileIndexCache;
+    private initialized;
+    private initPromise?;
+    constructor(url: string);
+    /**
+     * Initialize the reader: fetch header, dictionary, experiment metadata,
+     * and chromosome directory. Idempotent — safe to call multiple times.
+     *
+     * Note: init does NOT forward the caller's AbortSignal to avoid a race
+     * condition where aborting one track's fetch would leave the shared reader
+     * half-initialized (header set but metadata empty), permanently broken
+     * for all subsequent callers.
+     */
+    init(_signal?: AbortSignal): Promise<void>;
+    private _doInit;
+    private parseHeader;
+    private parseExperimentMetadata;
+    private parseChromDirectory;
+    private parseZoomDirectory;
+    /**
+     * Lazily fetch and parse the tile index for a chromosome.
+     * Cached after first load.
+     */
+    loadTileIndex(chrom: string, signal?: AbortSignal): Promise<TileEntry[]>;
+    private loadZoomTileIndex;
+    private parseTileIndex;
+    /**
+     * Read signal data for one or more experiments in a genomic region.
+     * Multiple experiments from the same tile are fetched with merged byte ranges.
+     *
+     * @returns Map from experiment index to WigFeature array
+     */
+    readFeatures(chrom: string, start: number, end: number, experimentIndexes: number[], bpPerPixel?: number, signal?: AbortSignal): Promise<Map<number, WigFeature[]>>;
+    /**
+     * Read zoom-level data for one or more experiments.
+     */
+    private readZoomFeatures;
+    /** Returns all experiment IDs in this GTX file. */
+    getExperimentIds(): string[];
+    /** Returns metadata key-value pairs for an experiment, or undefined if not found. */
+    getExperimentMetadata(id: string): Map<string, string> | undefined;
+    /** Resolve an experiment ID to its numeric index. */
+    resolveExperimentIndex(id: string): number | undefined;
+    /** Get the parsed header (must call init() first). */
+    getHeader(): GtxHeader | undefined;
+    /** Get all chromosome entries. */
+    getChromosomes(): Map<string, ChromEntry>;
+    /**
+     * Compute the fetch size for the chrom + zoom directory region.
+     *
+     * The directories sit at the end of the file, followed only by an 8-byte
+     * xxHash64 checksum. We compute the span from known offsets, and the
+     * trailing checksum bytes won't affect parsing since directory parsers
+     * read a known structure and stop.
+     */
+    private computeDirFetchSize;
+    /**
+     * Select the best zoom level for a given bp/pixel resolution.
+     * Returns undefined if full resolution should be used.
+     */
+    private selectZoomLevel;
+    /**
+     * Merge adjacent/nearby byte ranges and fetch, then split back to
+     * per-experiment chunks.
+     */
+    private fetchMergedRanges;
+    /** Decompress a zstd-compressed chunk using the cached dictionary. */
+    private decompress;
+    /** Read a u64 from BinaryParser (as JavaScript number). */
+    private readU64;
+    /** Clean up the decompression context. */
+    dispose(): void;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * GTX reader — public API.
+ *
+ * Reads GTX binary files via HTTP range requests and returns
+ * WigFeature[] arrays ready for rendering. A single GTX file
+ * bundles multiple experiments; the reader is cached per URL
+ * and shared across all experiments from the same file.
+ *
+ * Layer 1 (Data + Layout): no DOM, no canvas.
+ */
+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;
+}
+/**
+ * Fetch GTX features for a single experiment at a genomic locus.
+ */
+export declare function fetchGtxFeatures(url: string, experimentId: string, locus: Locus, options?: FetchGtxOptions): Promise<WigFeature[]>;
+/**
+ * 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[]>;
+/**
+ * Fetch GTX features for multiple experiments simultaneously.
+ * Optimizes network by merging byte ranges for experiments in the same tiles.
+ */
+export declare function fetchGtxMultiFeatures(url: string, experimentIds: string[], locus: Locus, options?: FetchGtxOptions): Promise<Map<string, WigFeature[]>>;
+/** Clear the GTX reader cache (useful for testing or memory management). */
+export declare function clearGtxCache(): void;

package/dist/types/src/gtx/zstdWasm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * First-party zstd WASM decompression module.
+ *
+ * Directly instantiates the zstd WASM binary (from @bokuweb/zstd-wasm, MIT license)
+ * without the Emscripten glue code that breaks webpack bundling.
+ *
+ * Only exposes decompression with dictionary — the minimum needed for GTX.
+ */
+/**
+ * Initialize the zstd WASM module. Idempotent — safe to call multiple times.
+ * Loads the WASM binary from the same directory as this module.
+ */
+export declare function initZstd(): Promise<void>;
+/** Create a decompression context. Returns an opaque handle. */
+export declare function createDCtx(): number;
+/** Free a decompression context. */
+export declare function freeDCtx(dctx: number): void;
+/**
+ * Decompress a zstd-compressed buffer using a dictionary.
+ * Returns a newly allocated Uint8Array with the decompressed data.
+ */
+export declare function decompressUsingDict(dctx: number, compressed: Uint8Array, dictionary: Uint8Array): Uint8Array;