loom-browser 0.0.8 → 0.0.10

package/dist/types/browser/headless/headlessGenomeBrowser.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Headless GenomeBrowser — pure data/navigation/caching core with zero DOM dependencies.
+ *
+ * Manages locus state, track coordination, data lifecycle, events, and theming.
+ * Can run in Node.js, workers, or any environment.
+ *
+ * Delegates to focused single-responsibility modules:
+ * - ROIManager: Region of Interest CRUD and spatial queries
+ * - TrackDataManager: fetch dedup, caching, abort, debounce
+ * - Track factories: convenience track creation (trackFactories.ts)
+ *
+ * The DOM-attached `GenomeBrowser` extends this class to add pointer events,
+ * ResizeObserver, canvas stacking, and sweep-to-zoom.
+ *
+ * Usage (headless):
+ *   const browser = new HeadlessGenomeBrowser({
+ *       locus: { chr: 'chr17', start: 7668000, end: 7688000 },
+ *       viewportWidth: 800,
+ *   })
+ *   browser.addTrack(track, dataSource)
+ *   browser.setLocus({ chr: 'chr17', start: 7670000, end: 7680000 })
+ *   browser.dispose()
+ */
+import type { Locus, Track, DataSource, FeatureCacheEntry, SessionConfig, TrackSessionConfig, DataSourceConfig, TrackInteractionEvent, TrackContextMenuEvent, WigFeature, BedFeature, SequenceProvider, Genome, ROI, ROISetConfig, ROIInteractionEvent } from '../../types';
+import { ROISet } from '../../roi/roiSet';
+import type { CanvasProvider } from '../../canvasProvider';
+import type { WorkerProvider } from '../../workerProvider';
+import type { DataSourceWorkerProvider } from '../../dataSourceWorkerProvider';
+import type { PopupProvider } from '../../popupProvider';
+import type { ContextMenuProvider } from '../../contextMenuProvider';
+import type { RenderTheme } from '../../themes/renderTheme';
+import { EventEmitter } from '../../events';
+import type { ChromSizes, CumulativeOffsets } from '../../genome/chromSizes';
+import { type CreateTrackFromSessionOptions } from './session';
+import { SequenceTrackCanvas } from '../../tracks/sequence/sequenceTrackCanvas';
+import { StateProjection } from '../../stateProjection';
+import type { TrackSelector } from '../../trackSelector';
+import type { UndoEntry, UndoEntryType } from '../../undoManager';
+import { ROIManager } from './roiManager';
+import { TrackDataManager } from './trackDataManager';
+export type { AddRulerOptions, AddWigTrackOptions, AddGtxTrackOptions, AddSequenceTrackOptions, AddBedTrackOptions, AddInteractionTrackOptions, AddAnnotationTrackOptions, AddWigTrackWithFeaturesOptions, AddBedTrackWithFeaturesOptions, } from './trackFactories';
+import type { RulerTrackCanvas } from '../../tracks/ruler/rulerTrackCanvas';
+import type { WigTrackCanvas } from '../../tracks/wig/wigTrackCanvas';
+import type { AnnotationTrackCanvas } from '../../tracks/annotation/annotationTrackCanvas';
+import type { InteractionTrackCanvas } from '../../tracks/interaction/interactionTrackCanvas';
+export declare const BrowserEvent: {
+    readonly LocusChange: "locuschange";
+    readonly TrackAdded: "trackadded";
+    readonly TrackRemoved: "trackremoved";
+    readonly TrackOrderChanged: "trackorderchanged";
+    readonly DataLoaded: "dataloaded";
+    readonly DataError: "dataerror";
+    readonly RenderError: "rendererror";
+    readonly TrackClick: "trackclick";
+    readonly TrackHover: "trackhover";
+    readonly TrackContextMenu: "trackcontextmenu";
+    readonly ROIAdded: "roiadded";
+    readonly ROIRemoved: "roiremoved";
+    readonly ROIChanged: "roichanged";
+    readonly ROIClick: "roiclick";
+    readonly ROIContextMenu: "roicontextmenu";
+    readonly ThemeChanged: "themechange";
+    readonly TrackConfigChanged: "trackconfigchanged";
+    readonly Undo: "undo";
+    readonly Redo: "redo";
+    readonly UndoStackChanged: "undostackchanged";
+};
+export interface BrowserEvents {
+    [BrowserEvent.LocusChange]: {
+        locus: Locus;
+    };
+    [BrowserEvent.TrackAdded]: {
+        track: Track;
+    };
+    [BrowserEvent.TrackRemoved]: {
+        track: Track;
+    };
+    [BrowserEvent.TrackOrderChanged]: {
+        tracks: Track[];
+    };
+    [BrowserEvent.DataLoaded]: {
+        track: Track;
+    };
+    [BrowserEvent.DataError]: {
+        track: Track;
+        error: Error;
+    };
+    [BrowserEvent.RenderError]: {
+        track: Track;
+        error: Error;
+    };
+    [BrowserEvent.TrackClick]: TrackInteractionEvent;
+    [BrowserEvent.TrackHover]: TrackInteractionEvent;
+    [BrowserEvent.TrackContextMenu]: TrackContextMenuEvent;
+    [BrowserEvent.ROIAdded]: {
+        roi: ROI;
+        set: ROISet;
+    };
+    [BrowserEvent.ROIRemoved]: {
+        roi: ROI;
+        set: ROISet;
+    };
+    [BrowserEvent.ROIChanged]: {
+        roi: ROI;
+        changes: Partial<ROI>;
+        set: ROISet;
+    };
+    [BrowserEvent.ROIClick]: ROIInteractionEvent;
+    [BrowserEvent.ROIContextMenu]: ROIInteractionEvent;
+    [BrowserEvent.ThemeChanged]: {
+        theme: RenderTheme;
+    };
+    [BrowserEvent.TrackConfigChanged]: {
+        track: Track;
+    };
+    [BrowserEvent.Undo]: {
+        entry: UndoEntry;
+    };
+    [BrowserEvent.Redo]: {
+        entry: UndoEntry;
+    };
+    [BrowserEvent.UndoStackChanged]: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+}
+/** Internal bookkeeping for a track + optional data source. */
+export interface ManagedTrack {
+    /** Stable string identifier. Auto-generated on addTrack if not provided. */
+    id: string;
+    track: Track;
+    dataSource: DataSource | null;
+    /** Serializable data source config — stored for session save/restore. */
+    dataSourceConfig: DataSourceConfig | null;
+    /** Track name for session serialization. */
+    name?: string;
+    /** Track ordering for session serialization. */
+    order?: number;
+    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
+    metadata?: Record<string, string>;
+    cache: FeatureCacheEntry | null;
+    abortController: AbortController | null;
+    /** Max visible height in pixels — enables scrollable container in DOM browser. */
+    maxTrackHeight?: number;
+}
+export interface HeadlessGenomeBrowserOptions {
+    locus: Locus;
+    /** Viewport width in CSS pixels. Required for headless; DOM browser reads from container. */
+    viewportWidth?: number;
+    /** Canvas provider for environment abstraction. Default: DOMCanvasProvider. */
+    canvasProvider?: CanvasProvider;
+    /** Worker provider for offloading CPU-intensive tasks. Default: main-thread execution.
+     *  If this also implements DataSourceWorkerProvider (e.g. WebWorkerPool),
+     *  it will be used for data fetching automatically. */
+    workerProvider?: WorkerProvider;
+    /** Popup provider for rendering feature popups on click/hover. Default in GenomeBrowser: DefaultPopupProvider. Pass null to disable. */
+    popupProvider?: PopupProvider | null;
+    /** Context menu provider for right-click menus. Default: DefaultContextMenuProvider. Pass null to disable. */
+    contextMenuProvider?: ContextMenuProvider | null;
+    /** Unified render theme. Palette drives default colors/fonts for all tracks. */
+    theme?: Partial<RenderTheme>;
+    /**
+     * Genome assembly. Provides chromosome sizes, cumulative offsets, and sequence.
+     * Default: hg38Genome. Pass null to disable clamping/sequence.
+     */
+    genome?: Genome | null;
+    /** Custom StateProjection subclass instance. Default: lazily created StateProjection. */
+    stateProjection?: StateProjection;
+}
+export declare class HeadlessGenomeBrowser {
+    protected _locus: Locus;
+    protected _viewportWidth: number;
+    protected managedTracks: ManagedTrack[];
+    /** When true, sortTracks() is a no-op. Used for batch track additions (e.g. loadSession). */
+    private _deferSort;
+    /** Canvas provider for environment abstraction. Available for convenience API / future use. */
+    readonly canvasProvider: CanvasProvider;
+    /** Worker provider for offloading CPU-intensive tasks. */
+    readonly workerProvider?: WorkerProvider;
+    /** Data source worker provider for running DataSources in web workers. */
+    readonly dataSourceWorkerProvider?: DataSourceWorkerProvider;
+    /** Popup provider for rendering feature popups on click/hover. */
+    readonly popupProvider?: PopupProvider;
+    /** Context menu provider for right-click menus. */
+    readonly contextMenuProvider?: ContextMenuProvider;
+    /** Resolved render theme. Available for track creation in convenience API. */
+    private _theme;
+    /**
+     * Genome assembly. Provides chromosome sizes, cumulative offsets, and optional sequence.
+     * Undefined when genome/clamping is disabled (null was passed).
+     */
+    readonly genome?: Genome;
+    /** Chromosome sizes for locus clamping. Derived from genome. Undefined when clamping is disabled. */
+    readonly chromSizes?: ChromSizes;
+    /** Precomputed cumulative offsets for whole genome view. Derived from genome. Undefined when chromSizes is not set. */
+    readonly cumulativeOffsets?: CumulativeOffsets;
+    /** Sequence provider for dynseq rendering on wig tracks. Derived from genome.sequence unless overridden. */
+    readonly sequenceProvider?: SequenceProvider;
+    readonly events: EventEmitter<BrowserEvents>;
+    private _state?;
+    private readonly _undoManager;
+    /** ROI management — owns all ROI sets and operations. */
+    protected readonly roiManager: ROIManager;
+    /** Data lifecycle — owns fetch dedup, caching, abort, debounce. */
+    protected readonly dataManager: TrackDataManager;
+    get theme(): RenderTheme;
+    get locus(): Locus;
+    get viewportWidth(): number;
+    /** Whether undo is available. Accepts optional skip predicate for filtering entry types. */
+    canUndo(skip?: (e: UndoEntry) => boolean): boolean;
+    /** Whether redo is available. Accepts optional skip predicate for filtering entry types. */
+    canRedo(skip?: (e: UndoEntry) => boolean): boolean;
+    /** Agent-friendly state projection manager. Lazily created on first access. */
+    get state(): StateProjection;
+    constructor(options: HeadlessGenomeBrowserOptions);
+    /** Build the factory context from current browser state. */
+    private factoryContext;
+    /** Clamp a locus to valid chromosome bounds. No-op if chromSizes is not set. */
+    protected clamp(locus: Locus): Locus;
+    /** Subscribe to a browser event. Returns an unsubscribe function. */
+    on<K extends keyof BrowserEvents>(event: K, handler: (data: BrowserEvents[K]) => void): () => void;
+    /** Unsubscribe from a browser event. */
+    off<K extends keyof BrowserEvents>(event: K, handler?: (data: BrowserEvents[K]) => void): void;
+    /**
+     * Snapshot the current state before a mutation.
+     * No-op while paused (e.g., during loadSession restoration from undo/redo).
+     */
+    protected _snapshotForUndo(type: UndoEntryType): void;
+    /**
+     * Undo the last mutation. Restores the previous session state.
+     * Optionally skip entries matching a predicate (e.g., skip navigation-only entries).
+     */
+    undo(skip?: (e: UndoEntry) => boolean): boolean;
+    /**
+     * Redo the last undone mutation.
+     * Optionally skip entries matching a predicate.
+     */
+    redo(skip?: (e: UndoEntry) => boolean): boolean;
+    /** Clear all undo/redo history. */
+    clearUndoHistory(): void;
+    /**
+     * Update the viewport width and re-render.
+     * In headless mode, call this when the logical viewport size changes.
+     * The DOM browser calls this automatically from ResizeObserver.
+     */
+    setViewportWidth(width: number): void;
+    /** Add a track with an optional data source for automatic data management. */
+    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number, order?: number): string;
+    /** Remove a track by reference or by stable string ID. */
+    removeTrack(trackOrId: Track | string): void;
+    /**
+     * Move a track to a new position in the track list.
+     * Emits BrowserEvent.TrackOrderChanged with the new track order.
+     */
+    moveTrack(track: Track, toIndex: number): void;
+    /**
+     * Sort tracks by priority (descending): positive = top, 0 = middle, negative = bottom.
+     */
+    private sortTracks;
+    /** Hook for subclasses to react to track order changes (e.g., DOM reorder). */
+    protected onTracksSorted(): void;
+    /**
+     * Persist current array positions into mt.order so future sorts preserve
+     * manual reordering.
+     */
+    protected _assignOrderFromPosition(): void;
+    /** Find the ManagedTrack entry for a given track canvas. */
+    private findMT;
+    /** Get the current track order. */
+    getTrackOrder(): Track[];
+    /** Find a managed track by its stable string ID. Returns undefined if not found. */
+    getManagedTrack(id: string): ManagedTrack | undefined;
+    /** Find a Track by its stable string ID. Returns undefined if not found. */
+    getTrack(id: string): Track | undefined;
+    /** Get all managed tracks (read-only snapshot). */
+    getManagedTracks(): readonly ManagedTrack[];
+    /** Find all managed tracks matching a selector. */
+    findTracks(selector: TrackSelector): ManagedTrack[];
+    /** Remove all tracks matching a selector. Returns the number of tracks removed. */
+    removeTracks(selector: TrackSelector): number;
+    /** Merge metadata into all tracks matching a selector. Returns the number of tracks updated. */
+    updateTrackMetadata(selector: TrackSelector, metadata: Record<string, string>): number;
+    /** Update the locus and re-render all tracks. Clamped to chromosome bounds. */
+    setLocus(locus: Locus): void;
+    /**
+     * Parse a locus string or gene name and navigate to it.
+     *
+     * Search order (matches igv.js js/search.ts):
+     * 1. Coordinate string: "chr17:7,668,000-7,688,000"
+     * 2. Whole genome: "all" / "*"
+     * 3. Bare chromosome name: "chr17", "chrX"
+     * 4. Gene/feature name via web service: "BRCA1", "TP53"
+     */
+    search(query: string): Promise<boolean>;
+    /** Zoom in by a factor (default 2x) around the center. */
+    zoomIn(factor?: number): void;
+    /** Zoom out by a factor (default 2x) around the center. */
+    zoomOut(factor?: number): void;
+    private zoomByFactor;
+    /**
+     * Zoom by a scale factor around an optional genomic coordinate.
+     *
+     * If `centerBP` is omitted, zooms around the viewport center (default).
+     * When provided, the zoom keeps `centerBP` at the same relative position
+     * in the viewport — e.g. for pointer-anchored pinch/wheel zoom.
+     *
+     * @param factor - Scale factor. <1 = zoom in, >1 = zoom out.
+     * @param centerBP - Optional genomic coordinate to anchor the zoom on.
+     */
+    zoomAroundCenter(factor: number, centerBP?: number): void;
+    /** Force a data reload for all managed tracks (e.g., after config change). */
+    reloadData(): void;
+    /** Get the cached features for a track, if available. */
+    getCachedFeatures<F>(track: Track): F[] | undefined;
+    /** Re-render all tracks at current locus. */
+    render(): void;
+    /** Add a single ROI to a named set. Creates a user-defined set if it doesn't exist. */
+    addROI(roi: ROI, setName?: string): ROI;
+    /** Add a full ROI set from config. Returns the created ROISet. */
+    addROISet(config: ROISetConfig): ROISet;
+    /** Remove an ROI by ID (searches all sets). Returns true if found and removed. */
+    removeROI(roiId: string): boolean;
+    /** Update an ROI by ID. Returns the updated ROI, or undefined if not found. */
+    updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
+    /** Remove a specific ROI set by instance. Returns true if found and removed. */
+    removeROISet(set: ROISet): boolean;
+    /** Remove all ROI sets. */
+    clearROIs(): void;
+    /** Get all ROIs across all sets (flattened). */
+    getROIs(): ROI[];
+    /** Get all ROI sets. */
+    getROISets(): readonly ROISet[];
+    /** Find ROIs overlapping a genomic region (searches all sets). */
+    findROIsAtLocus(chr: string, start: number, end: number): ROI[];
+    /** Get ROIs visible in the current viewport. */
+    getVisibleROIs(): ROI[];
+    /**
+     * Export the current view as an SVG string.
+     */
+    toSVG(options?: {
+        width?: number;
+        backdropColor?: string;
+    }): string;
+    /**
+     * Serialize browser state to a SessionConfig.
+     */
+    toJSON(): SessionConfig;
+    /**
+     * Load a session, replacing all current tracks.
+     * Disposes existing state, sets locus, and recreates tracks + data sources.
+     */
+    loadSession(session: SessionConfig, options?: CreateTrackFromSessionOptions): void;
+    /**
+     * Create a new HeadlessGenomeBrowser from a session config.
+     */
+    static fromSession(session: SessionConfig, options?: HeadlessGenomeBrowserOptions & CreateTrackFromSessionOptions): HeadlessGenomeBrowser;
+    /**
+     * Add a track from a session config using the track registry.
+     */
+    addTrackFromConfig(trackConfig: TrackSessionConfig): Track;
+    /** Register a factory result: addTrack + wire metadata + post-registration callback. */
+    private registerFactory;
+    /** Add a ruler track. */
+    addRuler(options?: import('./trackFactories').AddRulerOptions): RulerTrackCanvas;
+    /** Add a BigWig signal track. */
+    addWigTrack(url: string, options?: import('./trackFactories').AddWigTrackOptions): WigTrackCanvas;
+    /** Add a GTX signal track (single experiment from a multi-experiment GTX file). */
+    addGtxTrack(url: string, options: import('./trackFactories').AddGtxTrackOptions): WigTrackCanvas;
+    /** Add a UCSC gene annotation track. */
+    addGeneTrack(options?: import('./trackFactories').AddAnnotationTrackOptions): AnnotationTrackCanvas;
+    /** Add a BED/peak annotation track from a URL. */
+    addBedTrack(url: string, options?: import('./trackFactories').AddBedTrackOptions): AnnotationTrackCanvas;
+    /** Add an interaction (arc/BEDPE) track from a URL. */
+    addInteractionTrack(url: string, options?: import('./trackFactories').AddInteractionTrackOptions): InteractionTrackCanvas;
+    /** Add a BigWig-style signal track backed by in-memory features (no URL required). */
+    addWigTrackWithFeatures(features: WigFeature[], options?: import('./trackFactories').AddWigTrackWithFeaturesOptions): WigTrackCanvas;
+    /** Add a BED/annotation track backed by in-memory features (no URL required). */
+    addBedTrackWithFeatures(features: BedFeature[], options?: import('./trackFactories').AddBedTrackWithFeaturesOptions): AnnotationTrackCanvas;
+    /** Add a DNA/RNA sequence track. */
+    addSequenceTrack(options?: import('./trackFactories').AddSequenceTrackOptions): SequenceTrackCanvas;
+    /** Apply a new render theme to the browser and all existing tracks. */
+    setTheme(theme: Partial<RenderTheme>): void;
+    /** Clean up event listeners, abort in-flight requests, clear tracks and ROIs. */
+    dispose(): void;
+    /**
+     * Resolve pixel coordinates on a track canvas to interaction data.
+     * Used by GenomeBrowser to build event payloads from pointer events.
+     */
+    protected resolveInteraction(track: Track, x: number, y: number): TrackInteractionEvent | null;
+    protected loadAllTracksIfNeeded(): void;
+}

package/dist/types/browser/headless/roiManager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ROIManager — manages Region of Interest sets for a genome browser.
+ *
+ * Extracted from HeadlessGenomeBrowser to isolate ROI CRUD operations
+ * into a single-responsibility module. Owns the `roiSets` array and
+ * emits events through a callback interface.
+ *
+ * Layer 3 (Headless): no DOM dependencies.
+ */
+import type { ROI, ROISetConfig, Locus } from '../../types';
+import { ROISet } from '../../roi/roiSet';
+/** Callback interface for ROI events — wired by HeadlessGenomeBrowser to its EventEmitter. */
+export interface ROIEventCallbacks {
+    onROIAdded(roi: ROI, set: ROISet): void;
+    onROIRemoved(roi: ROI, set: ROISet): void;
+    onROIChanged(roi: ROI, changes: Partial<ROI>, set: ROISet): void;
+}
+export declare class ROIManager {
+    private roiSets;
+    private callbacks;
+    constructor(callbacks: ROIEventCallbacks);
+    /**
+     * Add a single ROI to a named set. Creates a user-defined set if it doesn't exist.
+     * Returns the ROI (with generated ID if none provided).
+     */
+    addROI(roi: ROI, setName?: string): ROI;
+    /** Add a full ROI set from config. Returns the created ROISet. */
+    addROISet(config: ROISetConfig): ROISet;
+    /** Remove an ROI by ID (searches all sets). Returns true if found and removed. */
+    removeROI(roiId: string): boolean;
+    /** Update an ROI by ID. Returns the updated ROI, or undefined if not found. */
+    updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
+    /** Remove a specific ROI set by instance. Returns true if found and removed. */
+    removeROISet(set: ROISet): boolean;
+    /** Remove all ROI sets. */
+    clear(): void;
+    /** Get all ROIs across all sets (flattened). */
+    getROIs(): ROI[];
+    /** Get all ROI sets. */
+    getROISets(): readonly ROISet[];
+    /** Find ROIs overlapping a genomic region (searches all sets). */
+    findROIsAtLocus(chr: string, start: number, end: number): ROI[];
+    /** Get ROIs visible in the given viewport locus. */
+    getVisibleROIs(locus: Locus): ROI[];
+    /** Serialize all ROI sets for session persistence. Returns undefined if empty. */
+    serialize(): ROISetConfig[] | undefined;
+}

package/dist/types/browser/headless/session.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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, Locus, SequenceProvider } from '../../types';
+import type { IgvSessionObject } from '../../types/igvCompat';
+import type { CanvasProvider } from '../../canvasProvider';
+import type { RenderTheme } from '../../themes/renderTheme';
+export type { CreatedTrack } from '../../trackRegistry';
+export declare const SESSION_VERSION = "1.0";
+export interface CreateTrackFromSessionOptions {
+    /** 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("./session").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;

package/dist/types/browser/headless/trackDataManager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * TrackDataManager — data lifecycle management for genome browser tracks.
+ *
+ * Extracted from HeadlessGenomeBrowser to isolate data fetching concerns:
+ * - Debounced loading during rapid zoom/pan
+ * - Cache validation and coverage checks
+ * - Fetch deduplication across tracks sharing the same data source
+ * - Inflight request tracking and abort management
+ * - Visibility window enforcement
+ *
+ * Layer 3 (Headless): no DOM dependencies.
+ */
+import type { Locus, Track, DataSource } from '../../types';
+import type { ManagedTrack } from './headlessGenomeBrowser';
+import type { DataSourceWorkerProvider } from '../../dataSourceWorkerProvider';
+/** Callback interface for data lifecycle events — wired by HeadlessGenomeBrowser. */
+export interface DataEventCallbacks {
+    onDataLoaded(track: Track): void;
+    onDataError(track: Track, error: Error): void;
+}
+export declare class TrackDataManager {
+    /** Inflight fetch promises keyed by (cacheKey + fetchRegion + bpPerPixel) for deduplication. */
+    private inflightFetches;
+    /** Timer for debouncing data loads during rapid zoom/pan. */
+    private loadDebounceTimer;
+    /** Set to true by dispose() to suppress post-dispose promise handlers. */
+    private _disposed;
+    private callbacks;
+    private dataSourceWorkerProvider?;
+    constructor(callbacks: DataEventCallbacks, dataSourceWorkerProvider?: DataSourceWorkerProvider);
+    /**
+     * Debounced wrapper around loadAllTracksIfNeeded.
+     * During rapid zoom/pan, this coalesces multiple setLocus() calls into a
+     * single data fetch cycle after the interaction settles (100ms quiet period).
+     * Abort in-flight requests immediately so they don't race with the eventual fetch.
+     */
+    debouncedLoad(managedTracks: ManagedTrack[], locus: Locus, viewportWidth: number): void;
+    loadAllTracksIfNeeded(managedTracks: ManagedTrack[], locus: Locus, viewportWidth: number): void;
+    /**
+     * Load data for a single track, deduplicating against inflight fetches
+     * from other tracks with the same data source identity.
+     */
+    loadTrackWithDedup(mt: ManagedTrack, managedTracks: ManagedTrack[], locus: Locus, viewportWidth: number): void;
+    /** Clean up: cancel debounce timer, mark as disposed. */
+    dispose(): void;
+    /** Destroy a worker-resident data source. */
+    destroyWorkerDataSource(dataSource: DataSource): void;
+}

package/dist/types/browser/headless/trackFactories.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Track convenience factories — create and wire tracks with data sources.
+ *
+ * Extracted from HeadlessGenomeBrowser to isolate repetitive track creation
+ * boilerplate. Each factory:
+ * 1. Creates a canvas via CanvasProvider
+ * 2. Creates a TrackCanvas instance
+ * 3. Builds a DataSourceConfig
+ * 4. Creates a worker proxy or direct data source
+ * 5. Wires chromosome alias resolution + cumulative offsets
+ * 6. Returns the track + data source + config for the browser to register
+ *
+ * Layer 3 (Headless): no DOM dependencies.
+ */
+import type { Locus, DataSource, DataSourceConfig, WindowFunction, WigFeature, BedFeature, WigRenderConfig, AnnotationRenderConfig, RulerRenderConfig, SequenceRenderConfig, InteractionRenderConfig, TextFileFormat, SequenceProvider, Genome } from '../../types';
+import type { CanvasProvider } from '../../canvasProvider';
+import type { DataSourceWorkerProvider } from '../../dataSourceWorkerProvider';
+import type { RenderTheme } from '../../themes/renderTheme';
+import type { ChromSizes, CumulativeOffsets } from '../../genome/chromSizes';
+import { WorkerDataSource } from '../../workerDataSource';
+import { RulerTrackCanvas } from '../../tracks/ruler/rulerTrackCanvas';
+import { WigTrackCanvas } from '../../tracks/wig/wigTrackCanvas';
+import { AnnotationTrackCanvas } from '../../tracks/annotation/annotationTrackCanvas';
+import { InteractionTrackCanvas } from '../../tracks/interaction/interactionTrackCanvas';
+export interface AddRulerOptions {
+    config?: Partial<RulerRenderConfig>;
+    maxTrackHeight?: number;
+}
+export interface AddWigTrackOptions {
+    config?: Partial<WigRenderConfig>;
+    height?: number;
+    background?: string;
+    windowFunction?: WindowFunction;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddGtxTrackOptions {
+    experimentId: string;
+    config?: Partial<WigRenderConfig>;
+    height?: number;
+    background?: string;
+    windowFunction?: WindowFunction;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddSequenceTrackOptions {
+    config?: Partial<SequenceRenderConfig>;
+    maxTrackHeight?: number;
+}
+export interface AddBedTrackOptions {
+    config?: Partial<AnnotationRenderConfig>;
+    height?: number;
+    background?: string;
+    format?: TextFileFormat;
+    indexURL?: string;
+    indexed?: boolean;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddInteractionTrackOptions {
+    config?: Partial<InteractionRenderConfig>;
+    background?: string;
+    format?: TextFileFormat;
+    indexURL?: string;
+    indexed?: boolean;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddAnnotationTrackOptions {
+    config?: Partial<AnnotationRenderConfig>;
+    height?: number;
+    background?: string;
+    genome?: string;
+    track?: string;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddWigTrackWithFeaturesOptions {
+    config?: Partial<WigRenderConfig>;
+    height?: number;
+    background?: string;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface AddBedTrackWithFeaturesOptions {
+    config?: Partial<AnnotationRenderConfig>;
+    height?: number;
+    background?: string;
+    maxTrackHeight?: number;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+/** Context needed by all factories — passed from HeadlessGenomeBrowser. */
+export interface TrackFactoryContext {
+    locus: Locus;
+    canvasProvider: CanvasProvider;
+    theme: RenderTheme;
+    genome?: Genome;
+    chromSizes?: ChromSizes;
+    cumulativeOffsets?: CumulativeOffsets;
+    sequenceProvider?: SequenceProvider;
+    dataSourceWorkerProvider?: DataSourceWorkerProvider;
+}
+/** Result of a factory — the browser registers this via addTrack(). */
+export interface FactoryResult<T> {
+    track: T;
+    dataSource?: DataSource;
+    dataSourceConfig?: DataSourceConfig;
+    maxTrackHeight?: number;
+    metadata?: Record<string, string>;
+    order?: number;
+    /** Post-registration callback (e.g., wiring onWindowFunctionChange). */
+    onRegistered?: (findMT: () => {
+        cache: null | unknown;
+        dataSourceConfig: DataSourceConfig | null;
+    }) => void;
+}
+/**
+ * Create a WorkerDataSource proxy for worker-eligible configs, or return null
+ * if dataSourceWorkerProvider is not set. Handles create + chrom alias + offsets wiring.
+ */
+export declare function createWorkerDataSource<F>(config: DataSourceConfig, ctx: Pick<TrackFactoryContext, 'dataSourceWorkerProvider' | 'genome' | 'cumulativeOffsets'>): WorkerDataSource<F> | null;
+/**
+ * Wire chromosome alias resolution and cumulative offsets on a direct (non-worker) data source.
+ * Consolidates the pattern repeated 7+ times in the old HeadlessGenomeBrowser.
+ */
+export declare function wireDataSource(ds: DataSource, ctx: Pick<TrackFactoryContext, 'genome' | 'cumulativeOffsets'>): void;
+/**
+ * Wire a WigTrackCanvas's window function change callback to trigger a data reload.
+ * Wraps the existing callback (set by the factory) so the original still fires.
+ */
+export declare function wireWindowFunctionReload(track: WigTrackCanvas, reloadFn: () => void): void;
+export declare function createRuler(ctx: TrackFactoryContext, options?: AddRulerOptions): FactoryResult<RulerTrackCanvas>;
+export declare function createWigTrack(ctx: TrackFactoryContext, url: string, options?: AddWigTrackOptions): FactoryResult<WigTrackCanvas>;
+export declare function createGtxTrack(ctx: TrackFactoryContext, url: string, options: AddGtxTrackOptions): FactoryResult<WigTrackCanvas>;
+export declare function createGeneTrack(ctx: TrackFactoryContext, options?: AddAnnotationTrackOptions): FactoryResult<AnnotationTrackCanvas>;
+export declare function createBedTrack(ctx: TrackFactoryContext, url: string, options?: AddBedTrackOptions): FactoryResult<AnnotationTrackCanvas>;
+export declare function createInteractionTrack(ctx: TrackFactoryContext, url: string, options?: AddInteractionTrackOptions): FactoryResult<InteractionTrackCanvas>;
+export declare function createWigTrackWithFeatures(ctx: TrackFactoryContext, features: WigFeature[], options?: AddWigTrackWithFeaturesOptions): FactoryResult<WigTrackCanvas>;
+export declare function createBedTrackWithFeatures(ctx: TrackFactoryContext, features: BedFeature[], options?: AddBedTrackWithFeaturesOptions): FactoryResult<AnnotationTrackCanvas>;