loom-browser 0.0.1

package/dist/types/tabix/bgzf.d.ts

@@ -0,0 +1,43 @@
+/**
+ * BGZF (Block GZipped Format) detection and decompression.
+ *
+ * BGZF is a variant of gzip that stores data in independently compressed
+ * blocks, enabling random access. Each block has a standard gzip header
+ * with a BGZF-specific extra field encoding the block size.
+ *
+ * Uses pako.inflateRaw() for synchronous decompression — matching igv.js
+ * which uses the same library via igv-utils. No async overhead, no stream
+ * setup per block.
+ *
+ * Port of js/bam/bgzBlockLoader.ts inflateBlocks() and
+ * igv-utils/bgzf.js unbgzf().
+ *
+ * Layer 1 (Data + Layout): pure data, no DOM.
+ */
+/** Check if data starts with BGZF magic (gzip header + BGZF extra field). */
+export declare function isBgzf(data: ArrayBuffer | Uint8Array): boolean;
+/**
+ * Read BGZF block size from header bytes 16-17.
+ * Returns total block size in bytes (bsize field + 1).
+ */
+export declare function bgzBlockSize(data: ArrayBuffer | Uint8Array): number;
+/**
+ * Decompress all concatenated BGZF blocks in a buffer.
+ *
+ * Returns array of decompressed blocks (one Uint8Array per BGZF block).
+ * Optionally decompresses only blocks starting between startBlock and endBlock
+ * (byte offsets relative to beginning of data buffer).
+ *
+ * Uses synchronous pako.inflateRaw() per block — no async overhead.
+ * Matches igv.js inflateBlocks() which uses the same synchronous approach.
+ *
+ * Port of js/bam/bgzBlockLoader.ts inflateBlocks().
+ */
+export declare function inflateBgzfBlocks(data: ArrayBuffer, startBlock?: number, endBlock?: number): Uint8Array[];
+/**
+ * Decompress entire BGZF buffer into a single concatenated Uint8Array.
+ * Used for decompressing .tbi index files.
+ *
+ * Port of igv-utils/bgzf.js unbgzf().
+ */
+export declare function unbgzf(data: ArrayBuffer): Uint8Array;

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

@@ -0,0 +1,48 @@
+/**
+ * Tabix/BGZF reader — public API.
+ *
+ * Thin wrapper around @gmod/tabix that preserves the existing public API.
+ * 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;
+    format: number;
+    colSeq: number;
+    colBeg: number;
+    colEnd: number;
+    meta: number;
+    skip: number;
+    sequenceNames: string[];
+}
+/**
+ * Thin wrapper around @gmod/tabix TabixIndexedFile that preserves the legacy API.
+ */
+export declare class TabixReader {
+    private readonly tabix;
+    constructor(url: string, options?: TabixReaderOptions);
+    /** Get the tabix header metadata. */
+    getHeader(signal?: AbortSignal): Promise<TabixHeader>;
+    /** Get sequence names from the index. */
+    getSequenceNames(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Read header lines from the beginning of the BGZF data file.
+     * Returns lines that start with the meta character (e.g. '#' for VCF).
+     */
+    readHeaderLines(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Read all text lines overlapping a genomic range.
+     *
+     * @param chr - Chromosome/sequence name
+     * @param start - Start position (0-based)
+     * @param end - End position (exclusive)
+     */
+    readLines(chr: string, start: number, end: number, signal?: AbortSignal): Promise<string[]>;
+}

package/dist/types/tabix/tabixIndex.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tabix (.tbi) index parser and range query engine.
+ *
+ * Parses the binary .tbi format (a BGZF-compressed index for tab-delimited
+ * genomic files) and provides efficient range queries via hierarchical binning.
+ *
+ * Port of js/bam/bamIndex.ts (tabix path) and js/bam/indexUtils.ts.
+ * Layer 1 (Data + Layout): pure data, no DOM.
+ */
+import type { VirtualOffset, Chunk } from './virtualOffset';
+/** Tabix format codes (from spec). */
+export declare const enum TabixFormat {
+    BED = 0,// 0-based half-open
+    SAM = 1,// 1-based
+    VCF = 2
+}
+/** Parsed tabix header metadata. */
+export interface TabixHeader {
+    /** Number of reference sequences. */
+    nref: number;
+    /** Format code: 0=BED, 1=SAM, 2=VCF/GFF. */
+    format: TabixFormat;
+    /** 1-based column index for sequence name. */
+    colSeq: number;
+    /** 1-based column index for start position. */
+    colBeg: number;
+    /** 1-based column index for end position (0 = compute from start). */
+    colEnd: number;
+    /** ASCII code of meta character (lines starting with this are skipped, e.g. 35='#'). */
+    meta: number;
+    /** Number of header lines to skip before data. */
+    skip: number;
+    /** Sequence names in index order. */
+    sequenceNames: string[];
+}
+interface BinIndex {
+    [binNumber: number]: Chunk[];
+}
+interface RefIndex {
+    binIndex: BinIndex;
+    linearIndex: (VirtualOffset | null)[];
+}
+/** Parsed tabix index with range query support. */
+export interface TabixIndex {
+    header: TabixHeader;
+    /** Map from sequence name to reference index (0-based). */
+    sequenceIndexMap: Record<string, number>;
+    /** Per-reference bin + linear indices. */
+    indices: (RefIndex | undefined)[];
+    /** Byte offset of first data block in the BGZF file. */
+    firstBlockPosition: number;
+    /** Byte offset of last data block in the BGZF file. */
+    lastBlockPosition: number;
+    /** Get chunks overlapping a genomic range. */
+    chunksForRange(refId: number, min: number, max: number): Chunk[];
+}
+/**
+ * Parse a decompressed .tbi binary buffer into a TabixIndex.
+ *
+ * The .tbi file is BGZF-compressed; caller must decompress with unbgzf() first.
+ * Binary format mirrors BAI but with an extra header for column metadata and
+ * sequence names.
+ *
+ * Port of js/bam/bamIndex.ts BamIndex.parse() with tabix=true.
+ */
+export declare function parseTabixIndex(data: ArrayBuffer): TabixIndex;
+/**
+ * Calculate the list of bin ranges that overlap with region [beg, end).
+ * Uses the standard 5-level hierarchical binning scheme (same as BAI).
+ *
+ * Returns array of [startBin, endBin] inclusive ranges.
+ *
+ * Port of js/bam/bamIndex.ts reg2bins().
+ */
+export declare function reg2bins(beg: number, end: number): number[][];
+/**
+ * Sort chunks by position, filter by linear index minimum, merge adjacent chunks.
+ *
+ * Merge criteria (from igv.js): gap between chunks < 65KB and total span < 5MB.
+ * This reduces the number of HTTP range requests.
+ *
+ * Port of js/bam/indexUtils.ts optimizeChunks().
+ */
+export declare function optimizeChunks(chunks: Chunk[], lowest?: VirtualOffset): Chunk[];
+export {};

package/dist/types/tabix/tabixReader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tabix file reader — top-level API for querying BGZF-compressed,
+ * tabix-indexed genomic files.
+ *
+ * Combines index loading, BGZF block fetching, and line extraction to
+ * return raw text lines for a genomic range. Format-specific parsing
+ * (BED→features, VCF→variants, GFF→annotations) is a separate concern
+ * (Infrastructure Gap #7).
+ *
+ * Port of js/feature/featureFileReader.ts (tabix path).
+ * Layer 1 (Data + Layout): pure data, no DOM.
+ */
+import type { TabixIndex, TabixHeader } from './tabixIndex';
+import type { WorkerProvider } from '../workerProvider';
+export interface TabixReaderOptions {
+    /** URL to the .tbi index file. Defaults to `url + '.tbi'`. */
+    indexUrl?: string;
+    /** Worker provider for offloading BGZF decompression. */
+    workerProvider?: WorkerProvider;
+}
+export declare class TabixReader {
+    private readonly url;
+    private readonly indexUrl;
+    private readonly blockLoader;
+    private readonly workerProvider?;
+    private _index;
+    constructor(url: string, options?: TabixReaderOptions);
+    /**
+     * Lazy-load and cache the tabix index.
+     * Fetches the entire .tbi file, decompresses (BGZF), and parses the binary index.
+     */
+    getIndex(signal?: AbortSignal): Promise<TabixIndex>;
+    /** Get the tabix header metadata (format, column indices, meta char, skip count). */
+    getHeader(signal?: AbortSignal): Promise<TabixHeader>;
+    /** Get sequence names from the index. */
+    getSequenceNames(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Read header lines from the beginning of the BGZF data file.
+     *
+     * Returns lines that start with the meta character (e.g. '#' for VCF)
+     * or are within the skip count declared in the index header.
+     */
+    readHeaderLines(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Read all text lines overlapping a genomic range.
+     *
+     * Returns raw tab-delimited lines (not parsed). The caller is responsible
+     * for format-specific parsing (BED, VCF, GFF, etc.).
+     *
+     * @param chr - Chromosome/sequence name (must match the name in the index)
+     * @param start - Start position (0-based)
+     * @param end - End position (exclusive)
+     */
+    readLines(chr: string, start: number, end: number, signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Parse a position value from a token array.
+     * BED format (format=0) is 0-based; VCF/GFF (format=2) and SAM (format=1) are 1-based.
+     */
+    private parsePosition;
+}

package/dist/types/tabix/virtualOffset.d.ts

@@ -0,0 +1,41 @@
+/**
+ * BGZF virtual file offsets.
+ *
+ * A virtual offset is a 64-bit value encoding both the position of a
+ * compressed BGZF block in the file and the byte offset within the
+ * decompressed block. Used by tabix (.tbi) and BAI (.bai) indices.
+ *
+ * Port of js/binary.ts VPointer class, reimplemented as plain interfaces
+ * + pure functions (matching src/ conventions).
+ */
+import type { BinaryParser } from '../bigwig/binaryParser';
+/** A BGZF virtual file offset: compressed block position + offset within decompressed block. */
+export interface VirtualOffset {
+    /** Byte offset of the BGZF block start in the compressed file. */
+    block: number;
+    /** Byte offset within the decompressed block. */
+    offset: number;
+}
+/** A span of data in a BGZF file between two virtual offsets. */
+export interface Chunk {
+    minv: VirtualOffset;
+    maxv: VirtualOffset;
+}
+export declare function createVirtualOffset(block: number, offset: number): VirtualOffset;
+export declare function isGreaterThan(a: VirtualOffset, b: VirtualOffset): boolean;
+export declare function isLessThan(a: VirtualOffset, b: VirtualOffset): boolean;
+export declare function isEqualTo(a: VirtualOffset, b: VirtualOffset): boolean;
+/**
+ * Read an 8-byte virtual offset from a BinaryParser.
+ *
+ * Byte layout (all little-endian):
+ *   bytes 0–1: within-block offset (uint16 LE)
+ *   bytes 2–6: compressed block file offset (5-byte uint, LE)
+ *   byte 7: unused
+ *
+ * Uses multiplication (not bitwise ops) for the upper bytes to avoid
+ * JavaScript's 32-bit integer limit on bitwise operations.
+ *
+ * Port of js/binary.ts BinaryParser.getVPointer().
+ */
+export declare function readVirtualOffset(parser: BinaryParser): VirtualOffset;

package/dist/types/test/src/mockCanvasProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Mock CanvasProvider for headless tests — no DOM required.
+ */
+import type { CanvasProvider, CanvasAndContext } from '../../src/canvasProvider';
+import type { Locus, Track, TrackSessionConfig } from '../../src/types';
+import type { RenderTheme } from '../../src/themes/renderTheme';
+export interface MockCanvasOptions {
+    width?: number;
+    height?: number;
+}
+/** Create a mock HTMLCanvasElement-like object. */
+export declare function createMockCanvas(options?: MockCanvasOptions): HTMLCanvasElement;
+export declare class MockCanvasProvider implements CanvasProvider {
+    readonly devicePixelRatio = 1;
+    createCanvas(width: number, height: number): CanvasAndContext;
+}
+export declare const mockCanvasProvider: MockCanvasProvider;
+export interface MockTrackOptions {
+    type?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Minimal Track implementation for browser tests.
+ * Records calls for assertion.
+ */
+export declare class MockTrack implements Track {
+    readonly type: string;
+    readonly canvas: HTMLCanvasElement;
+    private _locus;
+    private _height;
+    setLocusCalls: Locus[];
+    renderCalls: number;
+    features: unknown[] | null;
+    get locus(): Locus;
+    get height(): number;
+    constructor(options?: MockTrackOptions);
+    setLocus(locus: Locus): void;
+    render(): void;
+    attachTo(_container: HTMLElement): void;
+    detach(): void;
+    setFeatures(features: unknown[]): void;
+    suspendRendering(): void;
+    resumeRendering(): void;
+    setError(_error: Error | null): void;
+    hitTest(_x: number, _y: number): never[];
+    renderToContext(_ctx: CanvasRenderingContext2D, _width: number, _height: number): void;
+    serializeConfig(_theme: RenderTheme): TrackSessionConfig;
+}
+export interface MockDataSourceOptions<F = unknown> {
+    features?: F[];
+    /** If set, fetch will reject with this error. */
+    error?: Error;
+    /** Delay in ms before resolving. */
+    delay?: number;
+}
+export declare class MockDataSource<F = unknown> {
+    private features;
+    private error;
+    private delay;
+    fetchCalls: Array<{
+        locus: Locus;
+        bpPerPixel: number;
+    }>;
+    constructor(options?: MockDataSourceOptions<F>);
+    fetch(locus: Locus, bpPerPixel: number, signal?: AbortSignal): Promise<F[]>;
+}

package/dist/types/test/src/testBedDecode.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testCanvas2SVG.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for Canvas2SVG (src/export/canvas2svg.ts).
+ *
+ * Uses jsdom to provide DOM APIs (document.createElementNS, XMLSerializer)
+ * required by the Canvas2SVG context.
+ */
+export {};

package/dist/types/test/src/testChromAlias.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testCommandDispatcher.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testData.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for src/data/ — cachedSequence, ucscSequence, ucscApi.
+ *
+ * Achieves parity with legacy test/testCachedSequence.js (cache behavior)
+ * plus coverage for UCSC API clients.
+ */
+export {};

package/dist/types/test/src/testDataLifecycle.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testDataSourceCacheKey.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testDataSources.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for src/dataSources/ — SequenceDataSource, BigWigDataSource,
+ * GeneDataSource, TextFeatureSource, and featureSourceFactory.
+ */
+export {};

package/dist/types/test/src/testDecodeUcsc.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testEvents.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testFeatureCache.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testFeatureParser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testFormatDetection.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testGffDecode.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testHeadlessBrowser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testInteractionDecoder.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testIntervalTree.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testLocusUtils.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testPack.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testROI.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testRemoteProtocol.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testRenderTheme.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testSVGExport.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for SVG export integration:
+ * - HeadlessGenomeBrowser.toSVG()
+ */
+export {};

package/dist/types/test/src/testSequence.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testSession.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testTrackSelector.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testTrackSerialize.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testWigSummary.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/src/testWorkerDispatch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for worker task dispatch wiring.
+ *
+ * Verifies that:
+ * 1. MainThreadProvider correctly handles all task types (including new ones)
+ * 2. WorkerProvider is threaded through data sources and track canvases
+ * 3. Tasks are dispatched (not just executed synchronously) when workerProvider is set
+ */
+export {};

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

@@ -0,0 +1,3 @@
+export type { ThemePalette, RenderTheme } from './renderTheme';
+export { defaultRenderTheme, resolveTheme, resolveAnnotationConfig, resolveWigConfig, resolveRulerConfig } from './renderTheme';
+export { modernRenderTheme, darkRenderTheme } from './renderThemePresets';

package/dist/types/themes/renderTheme.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Unified RenderTheme system — shadcn-style palette-driven theming.
+ *
+ * Users define a global palette (primary, secondary, background, foreground, etc.)
+ * and each track type knows how to derive its specific config defaults from that
+ * palette. Everything is overridable at three levels:
+ *
+ *   1. Palette-derived defaults   (annotation.color = palette.primary)
+ *   2. Per-track-type overrides   (theme.annotation.borderRadius = 3)
+ *   3. Per-track instance overrides (options.config.color = 'red')
+ *
+ * Renderers never see RenderTheme directly — they still consume AnnotationRenderConfig,
+ * WigRenderConfig, etc. The theme system produces those configs.
+ */
+import type { AnnotationRenderConfig, WigRenderConfig, RulerRenderConfig, SequenceRenderConfig, InteractionRenderConfig } from '../types';
+/** Global color palette — the primary customization surface. */
+export interface ThemePalette {
+    /** Main track color (CDS exons, wig bars, signal fill). */
+    primary: string;
+    /** Alternate strand, negative values. */
+    secondary: string;
+    /** Highlights, selections, active states. */
+    accent: string;
+    /** Track canvas background. */
+    background: string;
+    /** Text, labels, tick marks. */
+    foreground: string;
+    /** Subtle elements: baselines, introns, borders. */
+    muted: string;
+}
+/**
+ * Unified render theme. Defines a global palette, typography, and nucleotide
+ * colors. Each track type derives its config defaults from the palette, with
+ * optional per-track-type overrides.
+ */
+export interface RenderTheme {
+    palette: ThemePalette;
+    /** CSS font-family string. Default: 'sans-serif'. */
+    fontFamily: string;
+    /** Base font size in pixels. Default: 10. */
+    fontSize: number;
+    /** Nucleotide color mapping (A, C, G, T, N). */
+    nucleotideColors: Record<string, string>;
+    annotation?: Partial<AnnotationRenderConfig>;
+    wig?: Partial<WigRenderConfig>;
+    ruler?: Partial<RulerRenderConfig>;
+    sequence?: Partial<SequenceRenderConfig>;
+    interaction?: Partial<InteractionRenderConfig>;
+}
+/** Returns the default render theme matching classic igv.js appearance. */
+export declare function defaultRenderTheme(): RenderTheme;
+/**
+ * Deep-merge a partial theme into the defaults.
+ * If no overrides provided, returns the default theme.
+ */
+export declare function resolveTheme(overrides?: Partial<RenderTheme>): RenderTheme;
+/**
+ * Resolve a full AnnotationRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.annotation overrides → per-track overrides.
+ */
+export declare function resolveAnnotationConfig(theme: RenderTheme, overrides?: Partial<AnnotationRenderConfig>): AnnotationRenderConfig;
+/**
+ * Resolve a full WigRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.wig overrides → per-track overrides.
+ */
+export declare function resolveWigConfig(theme: RenderTheme, overrides?: Partial<WigRenderConfig>): WigRenderConfig;
+/**
+ * Resolve a full RulerRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.ruler overrides → per-track overrides.
+ */
+export declare function resolveRulerConfig(theme: RenderTheme, overrides?: Partial<RulerRenderConfig>): RulerRenderConfig;
+/**
+ * Resolve a full SequenceRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.sequence overrides → per-track overrides.
+ */
+export declare function resolveSequenceConfig(theme: RenderTheme, overrides?: Partial<SequenceRenderConfig>): SequenceRenderConfig;
+/**
+ * Resolve a full InteractionRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.interaction overrides → per-track overrides.
+ */
+export declare function resolveInteractionConfig(theme: RenderTheme, overrides?: Partial<InteractionRenderConfig>): InteractionRenderConfig;

package/dist/types/themes/renderThemePresets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Built-in RenderTheme presets.
+ *
+ * These are Partial<RenderTheme> objects — pass them to resolveTheme() to get
+ * a fully resolved theme with defaults filled in.
+ *
+ * Usage:
+ *   import {resolveTheme} from './renderTheme'
+ *   import {modernRenderTheme} from './renderThemePresets'
+ *   const theme = resolveTheme(modernRenderTheme)
+ */
+import type { RenderTheme } from './renderTheme';
+/** Modern theme — blue/pink palette, rounded exons, system font. */
+export declare const modernRenderTheme: Partial<RenderTheme>;
+/** Dark theme — adapted for dark backgrounds, high contrast. */
+export declare const darkRenderTheme: Partial<RenderTheme>;

package/dist/types/trackRegistry.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Track registry — extensible factory for creating tracks from session configs.
+ *
+ * Mirrors igv.js `trackFactory.ts` (`js/trackFactory.ts`), which uses a
+ * `Map<string, TrackCreator>` with type alias resolution and runtime
+ * registration via `registerTrackClass()` / `registerTrackCreatorFunction()`.
+ *
+ * Our implementation follows the same pattern: a central `Map` of creators,
+ * type aliases, and public registration functions. The key difference is that
+ * igv.js creators take `(config, browser)` and return a Track, whereas ours
+ * take `(trackConfig, context)` and return a `CreatedTrack` (track + data
+ * source + metadata) since data sources are first-class in our architecture.
+ */
+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;
+}
+/** Result of creating a track — the track itself plus optional data source. */
+export interface CreatedTrack {
+    track: Track;
+    dataSource: DataSource | null;
+    dataSourceConfig: DataSourceConfig | null;
+    name?: string;
+    order?: number;
+}
+/**
+ * Factory function that creates a track + data source from a session config.
+ *
+ * Mirrors igv.js `TrackCreator = (config, browser) => Track` but returns
+ * a richer result since we separate track rendering from data sourcing.
+ */
+export type TrackCreator = (trackConfig: TrackSessionConfig, context: TrackCreatorContext) => CreatedTrack;
+/**
+ * Register a track creator for a given type string.
+ *
+ * Mirrors igv.js `registerTrackCreatorFunction()` (js/trackFactory.ts).
+ */
+export declare function registerTrackCreator(type: string, creator: TrackCreator): void;
+/**
+ * Register a type alias so that e.g. "gene" resolves to "annotation".
+ *
+ * Mirrors igv.js alias resolution in `getTrack()` (js/trackFactory.ts lines 78-96)
+ * where switch/case maps "annotation"→"feature", "genes"→"feature", etc.
+ */
+export declare function registerTypeAlias(alias: string, canonicalType: string): void;
+/**
+ * Look up a track creator by type (resolving aliases first).
+ *
+ * Mirrors igv.js `getTrack()` (js/trackFactory.ts) which resolves aliases
+ * then looks up in the `trackFunctions` Map.
+ */
+export declare function getTrackCreator(type: string): TrackCreator | undefined;
+/**
+ * Return all known track type strings (canonical + aliases).
+ *
+ * Mirrors igv.js `knownTrackTypes()` (js/trackFactory.ts).
+ */
+export declare function knownTrackTypes(): Set<string>;
+export declare function createDataSource(config: DataSourceConfig, workerProvider?: WorkerProvider): DataSource;
+/**
+ * Create a track from a session config using the registry.
+ *
+ * This replaces the switch/case in the old `createTrackFromSession()`.
+ * Unknown types throw an error (mirrors igv.js behavior where `getTrack()`
+ * returns undefined and the browser logs a warning).
+ */
+export declare function createTrackFromConfig(trackConfig: TrackSessionConfig, locus: Locus, options?: {
+    canvasProvider?: CanvasProvider;
+    workerProvider?: WorkerProvider;
+    theme?: Partial<RenderTheme>;
+    sequenceProvider?: SequenceProvider;
+}): CreatedTrack;