loom-browser 0.0.9 → 0.0.11

package/dist/types/genomeBrowser.d.ts

@@ -9,6 +9,12 @@
  * Ruler tracks get special treatment: dragging on a ruler creates a selection
  * overlay (sweep-to-zoom) instead of panning.
  *
+ * Delegates to focused single-responsibility modules:
+ * - PointerEventManager: drag/pan/sweep/click/hover/wheel/reorder
+ * - ROIOverlayManager: DOM-based ROI region rendering
+ * - ContextMenuManager: right-click context menus for tracks and ROIs
+ * - browserExport: SVG/PNG export utilities
+ *
  * Usage:
  *   const browser = new GenomeBrowser(container, {
  *       locus: { chr: 'chr17', start: 7668000, end: 7688000 },
@@ -78,42 +84,17 @@ export interface GenomeBrowserOptions extends HeadlessGenomeBrowserOptions {
 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;
     private featureOverlays;
     /** Worker provider auto-created by `workers` option. Disposed on cleanup. */
     private ownedWorkerProvider;
+    private handleKeyDown;
+    private handleDocMouseDown;
+    private pointerManager;
+    private roiOverlayManager;
+    private contextMenuManager;
     constructor(container: HTMLElement, options: GenomeBrowserOptions);
     /** Build a DOM row for a track (axis column + viewport wrapper). */
     private _buildTrackRow;
@@ -133,7 +114,6 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     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.
@@ -151,70 +131,29 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     private updateAxisContent;
     /**
      * Prepare an axis canvas at the correct size with DPR scaling,
-     * then delegate to the given stateless render function.
+     * then delegate to the 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;
     /** Sync DOM after any sort (addTrack, addGeneTrack, etc.). */
     protected onTracksSorted(): void;
     /** 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 setupUndoKeyboardHandler;
+    private teardownUndoKeyboardHandler;
+    private renderROIOverlays;
     /** Update all feature overlays after render. */
     private updateFeatureOverlays;
     /** Update the feature overlay for a single track. */
     private updateFeatureOverlay;
-    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).
+     * Overrides HeadlessGenomeBrowser.toSVG() to add axis rendering.
      */
     toSVG(options?: {
         width?: number;
@@ -222,23 +161,11 @@ export declare class GenomeBrowser extends HeadlessGenomeBrowser {
     }): 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).
-     */
+    /** Download the current view as an SVG file. */
     saveSVGtoFile(filename?: string): void;
-    /**
-     * Download the current view as a PNG file.
-     * Matches igv.js Browser.savePNGtoFile() (js/browser.ts lines 407-440).
-     */
+    /** Download the current view as a PNG file. */
     savePNGtoFile(filename?: string): Promise<void>;
-    /** Trigger a file download via a temporary anchor element. */
-    private downloadURL;
 }

package/dist/types/headlessGenomeBrowser.d.ts

@@ -1,8 +1,13 @@
 /**
  * Headless GenomeBrowser — pure data/navigation/caching core with zero DOM dependencies.
  *
- * Manages locus state, track coordination, data lifecycle (buffered fetch, caching,
- * abort), events, and theming. Can run in Node.js, workers, or any environment.
+ * 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.
@@ -16,7 +21,7 @@
  *   browser.setLocus({ chr: 'chr17', start: 7670000, end: 7680000 })
  *   browser.dispose()
  */
-import type { Locus, Track, DataSource, FeatureCacheEntry, SessionConfig, TrackSessionConfig, DataSourceConfig, TrackInteractionEvent, TrackContextMenuEvent, WindowFunction, WigFeature, BedFeature, WigRenderConfig, AnnotationRenderConfig, RulerRenderConfig, SequenceRenderConfig, InteractionRenderConfig, TextFileFormat, SequenceProvider, Genome, ROI, ROISetConfig, ROIInteractionEvent } from './types';
+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';
@@ -27,13 +32,17 @@ import type { RenderTheme } from './themes/renderTheme';
 import { EventEmitter } from './events';
 import type { ChromSizes, CumulativeOffsets } from './genome/chromSizes';
 import { type CreateTrackFromSessionOptions } from './session';
-import { RulerTrackCanvas } from './tracks/ruler/rulerTrackCanvas';
-import { WigTrackCanvas } from './tracks/wig/wigTrackCanvas';
-import { AnnotationTrackCanvas } from './tracks/annotation/annotationTrackCanvas';
 import { SequenceTrackCanvas } from './tracks/sequence/sequenceTrackCanvas';
-import { InteractionTrackCanvas } from './tracks/interaction/interactionTrackCanvas';
 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";
@@ -51,6 +60,10 @@ export declare const BrowserEvent: {
     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]: {
@@ -97,6 +110,19 @@ export interface BrowserEvents {
     [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 {
@@ -141,136 +167,10 @@ export interface HeadlessGenomeBrowserOptions {
     /** Custom StateProjection subclass instance. Default: lazily created StateProjection. */
     stateProjection?: StateProjection;
 }
-export interface AddRulerOptions {
-    config?: Partial<RulerRenderConfig>;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-}
-export interface AddWigTrackOptions {
-    config?: Partial<WigRenderConfig>;
-    /** Fixed pixel height (overrides config.height). */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Window function for BigWig summarization. Default: 'mean'. */
-    windowFunction?: WindowFunction;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddGtxTrackOptions {
-    /** Experiment ID within the GTX file. */
-    experimentId: string;
-    config?: Partial<WigRenderConfig>;
-    /** Fixed pixel height (overrides config.height). */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Window function for summarization. Default: 'mean'. */
-    windowFunction?: WindowFunction;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddSequenceTrackOptions {
-    config?: Partial<SequenceRenderConfig>;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-}
-export interface AddBedTrackOptions {
-    config?: Partial<AnnotationRenderConfig>;
-    /** Fixed pixel height. */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Explicit format override. When absent, inferred from URL. */
-    format?: TextFileFormat;
-    /** Index URL override for tabix-indexed files. */
-    indexURL?: string;
-    /** Whether the file is tabix-indexed. Auto-detected if absent. */
-    indexed?: boolean;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddInteractionTrackOptions {
-    config?: Partial<InteractionRenderConfig>;
-    /** Background color. */
-    background?: string;
-    /** Explicit format override (e.g., 'bedpe', 'interact'). Inferred from URL if absent. */
-    format?: TextFileFormat;
-    /** Index URL override for tabix-indexed files. */
-    indexURL?: string;
-    /** Whether the file is tabix-indexed. Auto-detected if absent. */
-    indexed?: boolean;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddAnnotationTrackOptions {
-    config?: Partial<AnnotationRenderConfig>;
-    /** Fixed pixel height. */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Genome assembly for UCSC API. Default: 'hg38'. */
-    genome?: string;
-    /** UCSC track name. Default: 'ncbiRefSeq'. */
-    track?: string;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. Default: 'Genes'. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddWigTrackWithFeaturesOptions {
-    config?: Partial<WigRenderConfig>;
-    /** Fixed pixel height (overrides config.height). */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
-export interface AddBedTrackWithFeaturesOptions {
-    config?: Partial<AnnotationRenderConfig>;
-    /** Fixed pixel height. */
-    height?: number;
-    /** Background color. */
-    background?: string;
-    /** Max visible height — enables scrollable container in DOM browser. */
-    maxTrackHeight?: number;
-    /** Track name for axis label. */
-    name?: string;
-    /** Arbitrary key-value metadata (e.g., assay, biosample, tissue). */
-    metadata?: Record<string, string>;
-}
 export declare class HeadlessGenomeBrowser {
     protected _locus: Locus;
     protected _viewportWidth: number;
     protected managedTracks: ManagedTrack[];
-    protected roiSets: ROISet[];
-    /** 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;
     /** 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. */
@@ -298,23 +198,46 @@ export declare class HeadlessGenomeBrowser {
     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);
-    /**
-     * Create a WorkerDataSource proxy for worker-eligible configs, or return null
-     * if dataSourceWorkerProvider is not set. Handles create + chrom alias + offsets wiring.
-     */
-    private createWorkerDataSource;
+    /** 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.
@@ -332,16 +255,13 @@ export declare class HeadlessGenomeBrowser {
     moveTrack(track: Track, toIndex: number): void;
     /**
      * Sort tracks by priority (descending): positive = top, 0 = middle, negative = bottom.
-     * Priority comes from the track type default + per-track `order` override.
-     * Within the same effective priority, insertion order is preserved (stable sort).
      */
     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. Uses descending values (top track = highest) scaled
-     * above the type-priority range so explicit order dominates.
+     * manual reordering.
      */
     protected _assignOrderFromPosition(): void;
     /** Find the ManagedTrack entry for a given track canvas. */
@@ -354,41 +274,24 @@ export declare class HeadlessGenomeBrowser {
     getTrack(id: string): Track | undefined;
     /** Get all managed tracks (read-only snapshot). */
     getManagedTracks(): readonly ManagedTrack[];
-    /**
-     * Find all managed tracks matching a selector.
-     *
-     * ```ts
-     * browser.findTracks({ type: 'wig', where: { biosample: 'K562' } })
-     * browser.findTracks({ name: 'H3K27ac' })
-     * ```
-     */
+    /** Find all managed tracks matching a selector. */
     findTracks(selector: TrackSelector): ManagedTrack[];
-    /**
-     * Remove all tracks matching a selector. Returns the number of tracks removed.
-     *
-     * ```ts
-     * browser.removeTracks({ where: { assay: 'ATAC-seq' } })  // remove all ATAC-seq tracks
-     * browser.removeTracks({ type: 'wig' })                    // remove all wig tracks
-     * ```
-     */
+    /** 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.
-     * New keys are added; existing keys are overwritten.
-     *
-     * ```ts
-     * browser.updateTrackMetadata({ type: 'wig' }, { project: 'ENCODE' })
-     * ```
-     */
+    /** 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 and navigate to it.
-     * e.g., "chr17:7,668,000-7,688,000"
-     * Returns true if navigation succeeded.
+     * 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): boolean;
+    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. */
@@ -411,10 +314,7 @@ export declare class HeadlessGenomeBrowser {
     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.
-     * Returns the ROI (with generated ID if none provided).
-     */
+    /** 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;
@@ -436,15 +336,6 @@ export declare class HeadlessGenomeBrowser {
     getVisibleROIs(): ROI[];
     /**
      * Export the current view as an SVG string.
-     *
-     * Creates a Canvas2SVG context, renders each track with clipped groups and
-     * vertical offsets, and returns the serialized SVG. Named entities are
-     * replaced with numeric equivalents for standalone SVG compatibility.
-     *
-     * Mirrors igv.js Browser.toSVG() (js/browser.ts lines 352-388).
-     *
-     * @param options.width — Override viewport width (defaults to current viewportWidth).
-     * @param options.backdropColor — Background color (defaults to 'white').
      */
     toSVG(options?: {
         width?: number;
@@ -452,54 +343,41 @@ export declare class HeadlessGenomeBrowser {
     }): string;
     /**
      * Serialize browser state to a SessionConfig.
-     * Track configs are serialized via per-type serializers that drop
-     * non-serializable values (functions, Promises) and only include
-     * fields that differ from theme defaults.
      */
     toJSON(): SessionConfig;
     /**
      * Load a session, replacing all current tracks.
      * Disposes existing state, sets locus, and recreates tracks + data sources.
-     *
-     * Tracks are created headlessly (not attached to the DOM). Subclasses like
-     * GenomeBrowser can override this to also attach track canvases to the DOM.
      */
     loadSession(session: SessionConfig, options?: CreateTrackFromSessionOptions): void;
     /**
      * Create a new HeadlessGenomeBrowser from a session config.
-     * Creates the browser and loads all tracks from the session.
      */
     static fromSession(session: SessionConfig, options?: HeadlessGenomeBrowserOptions & CreateTrackFromSessionOptions): HeadlessGenomeBrowser;
     /**
      * Add a track from a session config using the track registry.
-     *
-     * Mirrors igv.js `Browser.createTrack(config)` (js/browser.ts lines 1074-1151)
-     * which resolves type aliases via `getTrack()` and instantiates through the
-     * track factory. Our version delegates to `createTrackFromConfig()` in the
-     * registry, then registers the created track with this browser's data lifecycle.
-     *
-     * This is the generic entry point — the convenience methods below
-     * (addRuler, addWigTrack, addGeneTrack) are sugar for common cases.
      */
     addTrackFromConfig(trackConfig: TrackSessionConfig): Track;
+    /** Register a factory result: addTrack + wire metadata + post-registration callback. */
+    private registerFactory;
     /** Add a ruler track. */
-    addRuler(options?: AddRulerOptions): RulerTrackCanvas;
+    addRuler(options?: import('./trackFactories').AddRulerOptions): RulerTrackCanvas;
     /** Add a BigWig signal track. */
-    addWigTrack(url: string, options?: AddWigTrackOptions): WigTrackCanvas;
+    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: AddGtxTrackOptions): WigTrackCanvas;
+    addGtxTrack(url: string, options: import('./trackFactories').AddGtxTrackOptions): WigTrackCanvas;
     /** Add a UCSC gene annotation track. */
-    addGeneTrack(options?: AddAnnotationTrackOptions): AnnotationTrackCanvas;
-    /** Add a BED/peak annotation track from a URL. Supports plain text and tabix-indexed files. */
-    addBedTrack(url: string, options?: AddBedTrackOptions): AnnotationTrackCanvas;
+    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?: AddInteractionTrackOptions): InteractionTrackCanvas;
+    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?: AddWigTrackWithFeaturesOptions): WigTrackCanvas;
-    /** Add a BED/annotation track backed by in-memory features (no URL required). Features must include `chr`. */
-    addBedTrackWithFeatures(features: BedFeature[], options?: AddBedTrackWithFeaturesOptions): AnnotationTrackCanvas;
-    /** Add a DNA/RNA sequence track. Data fetching is handled automatically via the genome's sequence provider. */
-    addSequenceTrack(options?: AddSequenceTrackOptions): SequenceTrackCanvas;
+    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. */
@@ -507,22 +385,7 @@ export declare class HeadlessGenomeBrowser {
     /**
      * Resolve pixel coordinates on a track canvas to interaction data.
      * Used by GenomeBrowser to build event payloads from pointer events.
-     * Returns null if the track has no features at the given point.
      */
     protected resolveInteraction(track: Track, x: number, y: number): TrackInteractionEvent | null;
-    /**
-     * 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.
-     */
-    private debouncedLoad;
     protected loadAllTracksIfNeeded(): void;
-    /**
-     * Load data for a single track, deduplicating against inflight fetches
-     * from other tracks with the same data source identity.
-     *
-     * Works for both initial addTrack() loads and bulk loadAllTracksIfNeeded() calls.
-     */
-    private loadTrackWithDedup;
 }