loom-browser 0.0.1

package/dist/types/intervalTree.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Augmented red-black interval tree for efficient overlap queries.
+ *
+ * Port of igv.js `js/intervalTree.ts` (CLR-based implementation).
+ * Typed generically — values stored in intervals are `T` instead of `unknown`.
+ *
+ * Each node stores augmented min/max for its subtree, enabling O(log n + k)
+ * overlap queries via subtree pruning.
+ *
+ * Layer 1 (Data + Layout) — pure data structure, no DOM, no canvas.
+ */
+/** An interval with an associated value. */
+export interface Interval<T = unknown> {
+    low: number;
+    high: number;
+    value: T;
+}
+interface TreeNode<T> {
+    color: number;
+    parent: TreeNode<T>;
+    left: TreeNode<T>;
+    right: TreeNode<T>;
+    interval: Interval<T>;
+    /** Augmented: maximum high value in this subtree. */
+    max: number;
+    /** Augmented: minimum low value in this subtree. */
+    min: number;
+}
+/**
+ * Augmented red-black interval tree.
+ *
+ * Public API:
+ * - `insert(start, end, value)` — O(log n) insertion
+ * - `findOverlapping(start, end)` — O(log n + k) query, returns sorted intervals
+ * - `mapIntervals(fn)` — apply function to every interval (in-order)
+ */
+export declare class IntervalTree<T = unknown> {
+    #private;
+    root: TreeNode<T>;
+    constructor();
+    /**
+     * Insert an interval [start, end] with associated value.
+     * Maintains red-black balance and augmented min/max.
+     */
+    insert(start: number, end: number, value: T): void;
+    /**
+     * Find all intervals overlapping [start, end].
+     * Returns intervals sorted by `low` value.
+     */
+    findOverlapping(start: number, end: number): Interval<T>[];
+    /**
+     * Apply a function to every interval in the tree.
+     */
+    mapIntervals(fn: (interval: Interval<T>) => void): void;
+}
+export {};

package/dist/types/io/binaryParser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Binary data parser for reading structured binary data from a DataView.
+ * Port of js/binary.ts, simplified for BigWig reading (no VPointer).
+ */
+export declare class BinaryParser {
+    littleEndian: boolean;
+    position: number;
+    readonly view: DataView;
+    readonly length: number;
+    constructor(dataView: DataView, littleEndian?: boolean);
+    setPosition(position: number): void;
+    available(): number;
+    remLength(): number;
+    getByte(): number;
+    getShort(): number;
+    getUShort(): number;
+    getInt(): number;
+    getUInt(): number;
+    getLong(): number;
+    getString(len?: number): string;
+    getFixedLengthString(len: number): string;
+    getFloat(): number;
+    getDouble(): number;
+    skip(n: number): number;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Shared I/O utilities — binary parsing and HTTP range requests.
+ * Used by GTX reader and other format-specific code.
+ */
+export { BinaryParser } from './binaryParser';
+export { fetchRange, getContentLength, BufferedRangeReader } from './rangeReader';
+export type { ByteRange } from './rangeReader';

package/dist/types/io/rangeReader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HTTP range request reader using native fetch.
+ * Replaces igvxhr + BufferedReader for BigWig file reading.
+ *
+ * Handles cross-origin 307/302 redirects that strip the Range header.
+ * When a redirect causes the server to return 200 (full content) instead of
+ * 206 (partial), we either retry against the final URL or slice the correct
+ * bytes from the full response — matching igvxhr behavior.
+ */
+export interface ByteRange {
+    start: number;
+    size: number;
+}
+/**
+ * Fetch a byte range from a URL as an ArrayBuffer.
+ *
+ * Handles two redirect failure modes:
+ * 1. Cross-origin redirect strips Range header → server returns 200 (full file).
+ *    We retry directly against response.url (the final URL post-redirect).
+ * 2. If retry still returns 200, we slice the requested bytes from the full
+ *    response (matching igvxhr's fallback behavior).
+ *
+ * On HTTP 416 (Range Not Satisfiable), fetches the actual file size via HEAD
+ * and retries once with a clamped range.
+ */
+export declare function fetchRange(url: string, range: ByteRange, signal?: AbortSignal): Promise<ArrayBuffer>;
+/**
+ * Fetch the Content-Length of a URL via a HEAD request.
+ * If redirected and Content-Length is missing, retries against the final URL.
+ */
+export declare function getContentLength(url: string, signal?: AbortSignal): Promise<number>;
+/**
+ * Buffered reader that caches fetched data to minimize HTTP requests.
+ * When a requested range is within the cached buffer, no fetch is needed.
+ *
+ * On HTTP 416, recovers by fetching the file's Content-Length and retrying,
+ * matching js/bigwig/bufferedReader.ts behavior.
+ */
+export declare class BufferedRangeReader {
+    private readonly url;
+    private readonly bufferSize;
+    private cachedRange;
+    private cachedData;
+    private contentLength;
+    constructor(url: string, bufferSize?: number);
+    dataViewForRange(requestedRange: ByteRange, signal?: AbortSignal, retries?: number): Promise<DataView>;
+    loadArrayBuffer(range: ByteRange, signal?: AbortSignal): Promise<ArrayBuffer>;
+}

package/dist/types/locusUtils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Locus parsing, formatting, and clamping utilities.
+ */
+import type { Locus } from './types';
+import type { ChromSizes } from './genome/chromSizes';
+import type { CumulativeOffsets } from './genome/chromSizes';
+/** Check if a locus represents whole genome view. */
+export declare function isWholeGenomeView(locus: Locus): boolean;
+/**
+ * Parse a locus string like "chr17:7,668,000-7,688,000" into a Locus object.
+ * Accepts with or without commas. Also recognizes "all" / "*" for whole genome view
+ * (requires cumulative offsets to compute end position).
+ * Returns null if parsing fails.
+ */
+export declare function parseLocus(str: string, cumOffsets?: CumulativeOffsets): Locus | null;
+/**
+ * Format a Locus object as a human-readable string with thousands separators.
+ * e.g., { chr: 'chr17', start: 7668000, end: 7688000 } → "chr17:7,668,000-7,688,000"
+ */
+export declare function formatLocus(locus: Locus): string;
+/**
+ * Format a base pair length as a human-readable string.
+ * e.g., 20000 → "20 kb", 2500000 → "2.5 Mb", 500 → "500 bp"
+ */
+export declare function formatBpLength(bp: number): string;
+/**
+ * Clamp a locus to valid chromosome bounds.
+ *
+ * Enforces:
+ * - start >= 0
+ * - end <= chromLength (if known)
+ * - span <= chromLength (if known)
+ *
+ * Maintains viewport span when possible by shifting rather than shrinking.
+ * Matches the behavior of js/referenceFrame.ts clampStart().
+ */
+export declare function clampLocus(locus: Locus, chromSizes?: ChromSizes, cumOffsets?: CumulativeOffsets): Locus;

package/dist/types/pack.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Generic feature packing — greedy interval scheduling for row assignment.
+ *
+ * Assigns a `row` number to each feature so that no two features in the same
+ * row overlap. Features are sorted by start position, then placed in the first
+ * available row. This is used by every annotation-style track (genes, BED, GFF,
+ * VCF, interactions, etc.).
+ *
+ * Mirrors igv.js featurePacker.ts (js/feature/featurePacker.ts) which uses the
+ * same greedy algorithm with a generic {start, end, row} interface.
+ *
+ * @example
+ * ```ts
+ * const features = [{start: 100, end: 200}, {start: 150, end: 300}, {start: 250, end: 400}]
+ * packFeatures(features)
+ * // features[0].row === 0, features[1].row === 1, features[2].row === 0
+ * ```
+ */
+/**
+ * Minimal interface for packable features.
+ * Any object with start/end coordinates and a mutable row field.
+ * Mirrors igv.js PackableFeature (js/feature/featurePacker.ts).
+ */
+export interface Packable {
+    start: number;
+    end: number;
+    row?: number;
+}
+/**
+ * Assign row numbers to features using greedy interval scheduling.
+ * Features are sorted by start position, then placed in the first row
+ * where they don't overlap a previously placed feature.
+ *
+ * Mutates features in place by setting `.row`.
+ *
+ * @param features - Array of features to pack. Must have `start` and `end`.
+ * @param maxRows - Maximum number of rows. Features beyond this limit are
+ *   still assigned rows but pile up. Default: unlimited.
+ *   Matches igv.js behavior in featurePacker.ts and featureTrack.ts (default maxRows: 1000).
+ */
+export declare function packFeatures<T extends Packable>(features: T[], maxRows?: number): void;

package/dist/types/popupProvider.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PopupProvider — abstraction for popup/tooltip rendering.
+ *
+ * Follows the CanvasProvider / WorkerProvider pattern.
+ * Provide a custom implementation to replace the default `<loom-popup>` Web Component
+ * with your own React, Vue, or vanilla JS popup.
+ *
+ * When no popup provider is supplied, the browser still emits `trackclick` and
+ * `trackhover` events — consumers can handle interaction entirely via events.
+ */
+import type { PopupDataItem } from './types';
+export interface PopupProvider {
+    /** Show a popup with the given data, positioned relative to the container. */
+    show(data: PopupDataItem[], position: {
+        x: number;
+        y: number;
+    }, container: HTMLElement): void;
+    /** Hide the popup. */
+    hide(): void;
+    /** Clean up resources (remove DOM elements, etc). */
+    dispose(): void;
+}

package/dist/types/remoteProtocol.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RemoteProtocol — WebSocket message framing and event forwarding.
+ *
+ * Provides `RemoteConnection` which bridges a `HeadlessGenomeBrowser` to a
+ * WebSocket-like transport. Incoming command messages are dispatched via
+ * `CommandDispatcher`; browser events are forwarded as unsolicited messages.
+ *
+ * The `RemoteSocket` interface is minimal and testable — works with browser
+ * WebSocket, the `ws` npm package, or mock implementations.
+ */
+import type { HeadlessGenomeBrowser } from './headlessGenomeBrowser';
+import type { CommandDispatcherOptions } from './commandDispatcher';
+/** Inbound: agent/server sends a command request. */
+export interface RequestMessage {
+    id: string;
+    command: string;
+    args?: Record<string, unknown>;
+}
+/** Outbound: successful command result. */
+export interface ResponseMessage {
+    id: string;
+    result: unknown;
+}
+/** Outbound: command failed. */
+export interface ErrorMessage {
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Outbound: unsolicited browser event. */
+export interface EventMessage {
+    event: string;
+    data: unknown;
+}
+export type OutboundMessage = ResponseMessage | ErrorMessage | EventMessage;
+/**
+ * Minimal WebSocket-like interface.
+ * Works with browser WebSocket, Node `ws`, or test mocks.
+ */
+export interface RemoteSocket {
+    send(data: string): void;
+    addEventListener(type: 'message', handler: (event: {
+        data: string;
+    }) => void): void;
+    addEventListener(type: 'close', handler: () => void): void;
+    addEventListener(type: 'error', handler: (event: unknown) => void): void;
+    removeEventListener(type: string, handler: (...args: unknown[]) => void): void;
+    readonly readyState: number;
+}
+export declare const READY_STATE_OPEN = 1;
+export declare class RemoteConnection {
+    private dispatcher;
+    private socket;
+    private browser;
+    private unsubscribers;
+    private messageHandler;
+    private closeHandler;
+    private detached;
+    constructor(browser: HeadlessGenomeBrowser, socket: RemoteSocket, options?: CommandDispatcherOptions);
+    /** Disconnect: unsubscribe all event listeners and stop forwarding. */
+    detach(): void;
+    /** Whether this connection has been detached. */
+    get isDetached(): boolean;
+    private handleMessage;
+    private send;
+    private subscribeToEvents;
+    /**
+     * Convert non-serializable event payloads to plain JSON.
+     *
+     * Track references → { trackId, trackType, trackName }
+     * Error objects → string message
+     * ROISet objects → set name string
+     */
+    private sanitizeEventData;
+    private findManagedTrack;
+    private findTrackId;
+}

package/dist/types/renderTheme.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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   (gene.color = palette.primary)
+ *   2. Per-track-type overrides   (theme.gene.borderRadius = 3)
+ *   3. Per-track instance overrides (options.config.color = 'red')
+ *
+ * Renderers never see RenderTheme directly — they still consume GeneRenderConfig,
+ * WigRenderConfig, etc. The theme system produces those configs.
+ */
+import type { GeneRenderConfig, WigRenderConfig, RulerRenderConfig } 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>;
+    gene?: Partial<GeneRenderConfig>;
+    wig?: Partial<WigRenderConfig>;
+    ruler?: Partial<RulerRenderConfig>;
+}
+/** 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 GeneRenderConfig from a theme + optional per-track overrides.
+ *
+ * Resolution: palette-derived defaults → theme.gene overrides → per-track overrides.
+ */
+export declare function resolveGeneConfig(theme: RenderTheme, overrides?: Partial<GeneRenderConfig>): GeneRenderConfig;
+/**
+ * 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;

package/dist/types/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/roi/index.d.ts

@@ -0,0 +1,3 @@
+export { ROISet, ROI_DEFAULT_COLOR, ROI_USER_DEFINED_COLOR, generateROIId } from './roiSet';
+export { renderROIOverlays } from './roiRenderer';
+export type { ROIRenderOptions } from './roiRenderer';

package/dist/types/roi/roiRenderer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure stateless ROI overlay renderer — for SVG/PNG export.
+ *
+ * Layer 2: takes a CanvasRenderingContext2D, draws ROI overlays.
+ * No DOM, no state. Used by HeadlessGenomeBrowser.toSVG().
+ */
+import type { ROI, RenderContext } from '../types';
+export interface ROIRenderOptions {
+    /** Total height to render overlays across (sum of all track heights). */
+    totalHeight: number;
+    /** Height of the label chip at the top of each ROI. */
+    headerHeight?: number;
+    /** Font for ROI labels. */
+    font?: string;
+    /** Label text color. */
+    labelColor?: string;
+}
+/**
+ * Render ROI overlays onto a canvas context.
+ *
+ * Draws semi-transparent filled rectangles spanning the full track height,
+ * with a small label chip at the top showing the ROI name.
+ */
+export declare function renderROIOverlays(ctx: CanvasRenderingContext2D, rois: ROI[], rc: RenderContext, options: ROIRenderOptions): void;

package/dist/types/roi/roiSet.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ROISet — a named collection of Regions of Interest.
+ *
+ * Layer 1 (Data): pure data model, no DOM, no canvas.
+ * Mirrors igv.js ROISet (js/roi/ROISet.ts) but with typed interfaces
+ * and no feature source abstraction (features stored in-memory).
+ */
+import type { ROI, ROISetConfig } from '../types';
+/** Default fill color for loaded ROI sets — blue with low alpha. */
+export declare const ROI_DEFAULT_COLOR = "rgba(68, 134, 247, 0.15)";
+/** Default fill color for user-defined ROIs — green with low alpha. */
+export declare const ROI_USER_DEFINED_COLOR = "rgba(155, 185, 129, 0.2)";
+/** Generate a short unique ROI ID. */
+export declare function generateROIId(): string;
+/**
+ * A named collection of ROI features with a default color.
+ *
+ * Supports add/remove/update operations and spatial filtering.
+ * Serializable to ROISetConfig for session persistence.
+ */
+export declare class ROISet {
+    readonly name: string;
+    readonly isUserDefined: boolean;
+    color: string;
+    private _features;
+    constructor(config: ROISetConfig);
+    /** All features in this set. */
+    get features(): readonly ROI[];
+    /** Add a feature to this set. Assigns an ID if missing. */
+    addFeature(roi: ROI): ROI;
+    /** Remove a feature by ID. Returns the removed feature, or undefined. */
+    removeFeature(id: string): ROI | undefined;
+    /** Update a feature by ID. Returns the updated feature, or undefined. */
+    updateFeature(id: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
+    /** Find a feature by ID. */
+    findById(id: string): ROI | undefined;
+    /** Get features overlapping a genomic region. */
+    getFeatures(chr: string, start: number, end: number): ROI[];
+    /** Serialize to a JSON-safe config. */
+    toJSON(): ROISetConfig;
+}

package/dist/types/rulerRenderer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stateless ruler track renderer.
+ *
+ * Draws genomic coordinate tick marks and labels onto a canvas context.
+ * Ported from js/rulerTrack.ts but with no igv.js dependencies.
+ */
+import type { RulerRenderConfig, RenderContext } from './types';
+/**
+ * Render a genomic coordinate ruler onto a canvas context.
+ *
+ * Stateless — all state is passed as parameters.
+ * Draws tick marks, labels with SI-prefix units, and a baseline.
+ */
+export declare function renderRulerTrack(ctx: CanvasRenderingContext2D, config: RulerRenderConfig, rc: RenderContext): void;

package/dist/types/rulerTrackCanvas.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Canvas manager for rendering a genomic coordinate ruler.
+ *
+ * Extends BaseTrackCanvas — canvas lifecycle is handled by the base class.
+ * This class only implements ruler-specific rendering.
+ *
+ * Usage:
+ *   const canvas = document.createElement('canvas')
+ *   const ruler = new RulerTrackCanvas(canvas, { locus })
+ *   ruler.attachTo(containerDiv)
+ */
+import type { Locus, RulerRenderConfig, RenderContext, RulerTrackSessionConfig } from './types';
+import type { CanvasProvider } from './canvasProvider';
+import type { RenderTheme } from './renderTheme';
+import { BaseTrackCanvas } from './baseTrackCanvas';
+export interface RulerTrackCanvasOptions {
+    locus: Locus;
+    /** Per-track config overrides. Applied after theme-derived defaults. */
+    config?: Partial<RulerRenderConfig>;
+    /** Unified render theme. Palette drives default colors/fonts. */
+    theme?: Partial<RenderTheme>;
+    /** Canvas provider for environment abstraction. Default: DOMCanvasProvider. */
+    canvasProvider?: CanvasProvider;
+}
+export declare class RulerTrackCanvas extends BaseTrackCanvas<RulerRenderConfig> {
+    readonly type = "ruler";
+    constructor(canvas: HTMLCanvasElement, options: RulerTrackCanvasOptions);
+    protected computeHeight(_width: number): number;
+    protected getBackground(): string;
+    protected doRender(ctx: CanvasRenderingContext2D, _width: number, _height: number, rc: RenderContext): void;
+    serializeConfig(theme: RenderTheme): RulerTrackSessionConfig;
+}

package/dist/types/sequence/sequenceUtils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DNA/RNA sequence utilities — complement, reverse-complement, and codon translation.
+ *
+ * Layer 1 (Data + Layout): Pure functions, no DOM, no canvas. Can run in Node.js,
+ * workers, or any environment.
+ *
+ * Ported from:
+ * - js/util/sequenceUtils.ts (complement/reverseComplement)
+ * - js/util/translationDict.ts (codon table)
+ * - js/sequenceTrack.ts (complement table with IUPAC codes, translateSequence)
+ */
+/** Return the complement of a single base (identity if unknown). */
+export declare function complementBase(base: string): string;
+/** Return the complement of a DNA sequence (no reversal). */
+export declare function complementSequence(sequence: string): string;
+/** Return the reverse complement of a DNA sequence. */
+export declare function reverseComplementSequence(sequence: string): string;
+/**
+ * Standard genetic code: 64 codons → single-letter amino acid or 'STOP'.
+ *
+ * Direct port of js/util/translationDict.ts.
+ */
+export declare const translationDict: Readonly<Record<string, string>>;
+/** A single codon translation result. */
+export interface CodonTranslation {
+    /** The 3-base codon string. */
+    codons: string;
+    /** Single-letter amino acid code, 'STOP', or '' for unknown codons. */
+    aminoA: string;
+}
+/**
+ * Translate a DNA sequence into three reading frames.
+ *
+ * Returns an array of 3 frames (offset 0, 1, 2). Each frame is an array
+ * of codon translations.
+ *
+ * When `reversed` is true, each individual codon is reversed before lookup
+ * (matching igv.js SequenceTrack.translateSequence behavior — this is NOT
+ * the same as reverse-complement; the complement is applied separately
+ * to the display sequence).
+ *
+ * Port of js/sequenceTrack.ts translateSequence().
+ */
+export declare function translateSequence(seq: string, reversed?: boolean): CodonTranslation[][];

package/dist/types/session.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Session serialization and igv.js compatibility.
+ *
+ * Provides:
+ * - igv.js session import/export (fromIgvSession / toIgvSession)
+ * - Track creation via the track registry (createTrackFromSession)
+ *
+ * Track creation is delegated to the track registry (src/trackRegistry.ts),
+ * which provides an extensible Map-based factory. This module re-exports
+ * the registry's `createTrackFromConfig` under the legacy name for backward
+ * compatibility with existing session-loading code.
+ *
+ * Per-track config serialization is distributed to each track canvas class
+ * (WigTrackCanvas.serializeConfig, AnnotationTrackCanvas.serializeConfig, etc.)
+ */
+import type { SessionConfig, TrackSessionConfig, IgvSessionObject, Locus, SequenceProvider } from './types';
+import type { CanvasProvider } from './canvasProvider';
+import type { WorkerProvider } from './workerProvider';
+import type { RenderTheme } from './themes/renderTheme';
+export type { CreatedTrack } from './trackRegistry';
+export declare const SESSION_VERSION = "1.0";
+export interface CreateDataSourceOptions {
+    /** Worker provider for offloading CPU-intensive tasks in data sources. */
+    workerProvider?: WorkerProvider;
+}
+/**
+ * @deprecated Use the track registry (`createTrackFromConfig`) instead, which
+ * handles data source creation internally. Kept for direct data source creation
+ * in non-session contexts.
+ */
+export { createDataSource } from './trackRegistry';
+export interface CreateTrackFromSessionOptions extends CreateDataSourceOptions {
+    /** Canvas provider for creating track canvases. */
+    canvasProvider?: CanvasProvider;
+    /** Render theme for config resolution. */
+    theme?: Partial<RenderTheme>;
+    /** Sequence provider from the genome, used by sequence tracks. */
+    sequenceProvider?: SequenceProvider;
+}
+/**
+ * Create a track canvas + data source from a serialized TrackSessionConfig.
+ *
+ * Delegates to the track registry's `createTrackFromConfig()`, which uses
+ * the extensible Map-based factory instead of a switch/case.
+ */
+export declare function createTrackFromSession(trackConfig: TrackSessionConfig, locus: Locus, options?: CreateTrackFromSessionOptions): import("./trackRegistry").CreatedTrack;
+/**
+ * Convert an igv.js session object to our SessionConfig format.
+ * Unknown track types are skipped with a console warning.
+ */
+export declare function fromIgvSession(igvSession: IgvSessionObject): SessionConfig;
+/**
+ * Convert our SessionConfig to an igv.js-compatible session object.
+ */
+export declare function toIgvSession(session: SessionConfig): IgvSessionObject;