loom-browser 0.0.9 → 0.0.11

package/dist/types/index.d.ts

@@ -2,8 +2,8 @@ export type { CanvasProvider, CanvasAndContext } from './canvasProvider';
 export { DOMCanvasProvider, defaultCanvasProvider } from './canvasProvider';
 export type { PopupProvider } from './popupProvider';
 export type { ContextMenuProvider } from './contextMenuProvider';
-export type { ContextMenuCallbacks, ROIMenuCallbacks } from './contextMenu';
-export { commonContextMenuItems, numericDataMenuItems, roiContextMenuItems } from './contextMenu';
+export type { ContextMenuCallbacks, ROIMenuCallbacks } from './browser/dom/contextMenu';
+export { commonContextMenuItems, numericDataMenuItems, roiContextMenuItems } from './browser/dom/contextMenu';
 export type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from './workerProvider';
 export type { PackTask, SummarizeWigTask, ComputeWigRangeTask, ParseFeaturesTask, } from './workerProvider';
 export { MainThreadProvider, mainThreadProvider } from './workerProvider';
@@ -23,10 +23,12 @@ export type { SequenceRenderConfig, SequenceType, SequenceTrackSessionConfig, Se
 export { defaultSequenceRenderConfig } from './types';
 export type { InteractionFeature, InteractionRenderConfig, ArcOrientation, ArcDisplayMode, InteractionTrackSessionConfig, InteractionSessionOverrides } from './types';
 export { defaultInteractionRenderConfig } from './types';
-export type { DataSource, FeatureCacheEntry, DataDrivenTrack } from './types';
+export type { DataSource, ConfigurableDataSource, DataSourceConfigMethod, FeatureCacheEntry, DataDrivenTrack, ZoomAwareTrack } from './types';
+export { isZoomAware } from './types';
 export type { PopupDataItem, HitTestResult, TrackInteractionEvent, ContextMenuItem, TrackContextMenuEvent, NumericState, ROI, ROISetConfig, ROIInteractionEvent, FeatureRect } from './types';
-export type { SessionConfig, TrackSessionConfig, WigTrackSessionConfig, AnnotationTrackSessionConfig, RulerTrackSessionConfig, WigSessionOverrides, AnnotationSessionOverrides, RulerSessionOverrides, DataSourceConfig, BigWigDataSourceConfig, GtxDataSourceConfig, UCSCDataSourceConfig, TextDataSourceConfig, MemoryDataSourceConfig, SequenceProvider, IgvSessionObject, IgvReferenceConfig, IgvTrackConfig, Chromosome, Genome, GenomeConfig, ChromAliasRecord, Strand, TextFileFormat, BedFeature, PeakFeature, BedGraphFeature, GFFRecord, GFFFeature, TextFeature, } from './types';
+export type { SessionConfig, TrackSessionConfig, WigTrackSessionConfig, AnnotationTrackSessionConfig, RulerTrackSessionConfig, WigSessionOverrides, AnnotationSessionOverrides, RulerSessionOverrides, DataSourceConfig, BigWigDataSourceConfig, GtxDataSourceConfig, UCSCDataSourceConfig, TextDataSourceConfig, MemoryDataSourceConfig, SequenceProvider, Chromosome, Genome, GenomeConfig, ChromAliasRecord, Strand, TextFileFormat, BedFeature, PeakFeature, BedGraphFeature, GFFRecord, GFFFeature, TextFeature, } from './types';
 export { defaultAnnotationRenderConfig, defaultRulerRenderConfig, defaultWigRenderConfig } from './types';
+export type { IgvSessionObject, IgvReferenceConfig, IgvTrackConfig } from './types/igvCompat';
 export type { Packable } from './pack';
 export { packFeatures } from './pack';
 export { renderAnnotationTrack } from './tracks/annotation/annotationRenderer';
@@ -41,14 +43,20 @@ export { renderWigTrack } from './tracks/wig/wigRenderer';
 export { WigTrackCanvas } from './tracks/wig/wigTrackCanvas';
 export type { WigTrackCanvasOptions } from './tracks/wig/wigTrackCanvas';
 export { summarizeWigData, computeWigDataRange } from './tracks/wig/wigSummary';
-export { HeadlessGenomeBrowser, BrowserEvent } from './headlessGenomeBrowser';
-export type { HeadlessGenomeBrowserOptions, ManagedTrack, AddRulerOptions, AddWigTrackOptions, AddGtxTrackOptions, AddBedTrackOptions, AddAnnotationTrackOptions, AddInteractionTrackOptions, AddSequenceTrackOptions, AddWigTrackWithFeaturesOptions, AddBedTrackWithFeaturesOptions } from './headlessGenomeBrowser';
-export { GenomeBrowser } from './genomeBrowser';
-export type { GenomeBrowserOptions, BrowserEvents } from './genomeBrowser';
+export { HeadlessGenomeBrowser, BrowserEvent } from './browser/headless/headlessGenomeBrowser';
+export type { HeadlessGenomeBrowserOptions, ManagedTrack, AddRulerOptions, AddWigTrackOptions, AddGtxTrackOptions, AddBedTrackOptions, AddAnnotationTrackOptions, AddInteractionTrackOptions, AddSequenceTrackOptions, AddWigTrackWithFeaturesOptions, AddBedTrackWithFeaturesOptions } from './browser/headless/headlessGenomeBrowser';
+export { GenomeBrowser } from './browser/dom/genomeBrowser';
+export type { GenomeBrowserOptions, BrowserEvents } from './browser/dom/genomeBrowser';
+export { createDefaultContextMenuProvider, createDefaultPopupProvider } from './browser/dom/defaultProviders';
+export { renderDOMBrowserSVG, svgToPNG, triggerDownload } from './browser/dom/browserExport';
 export type { ChromSizes, CumulativeOffsets } from './genome/chromSizes';
 export { hg38ChromSizes, getChromLength, isMainChromosome, mainChromosomeNames, computeCumulativeOffsets, genomeToChromCoord, parseChromSizes } from './genome/chromSizes';
 export { hg38Genome, createGenome, createGenomeSync } from './genome/genome';
 export { ChromAliasDefaults, addCaseAliases } from './genome/chromAlias';
+export { UndoManager } from './undoManager';
+export type { UndoEntry, UndoEntryType } from './undoManager';
+export type { LogLevel } from './logger';
+export { setLogLevel, getLogLevel } from './logger';
 export { EventEmitter } from './events';
 export { parseLocus, formatLocus, formatBpLength, clampLocus, isWholeGenomeView } from './locusUtils';
 export { LoomChromosomeSelect, LoomLocusInput, LoomZoomControls, LoomWindowSize, LoomExportControls, LoomNavbar, LoomBrowserShell, createShell, classicThemeCSS, modernThemeCSS, getThemeCSS, LoomPopup, DefaultPopupProvider, LoomContextMenu, DefaultContextMenuProvider, LoomInputDialog, } from './ui';
@@ -83,21 +91,20 @@ export type { FetchGenesOptions } from './data/ucscApi';
 export { fetchSequence } from './data/ucscSequence';
 export type { FetchSequenceOptions } from './data/ucscSequence';
 export { createCachedSequence } from './data/cachedSequence';
+export { searchWebService, parseSearchResults } from './data/searchService';
+export type { SearchResult } from './data/searchService';
 export { fetchBigWigFeatures, fetchBigWigWGFeatures, clearBigWigCache, BigWigReader } from './bigwig';
 export type { FetchBigWigOptions, BigWigHeader, BigWigTotalSummary } from './bigwig';
 export { fetchGtxFeatures, fetchGtxWGFeatures, fetchGtxMultiFeatures, clearGtxCache, GtxReader } from './gtx';
 export type { FetchGtxOptions, GtxHeader, ChromEntry, ExperimentEntry } from './gtx';
 export { TabixReader } from './tabix';
 export type { TabixReaderOptions, TabixHeader } from './tabix';
-export { BinaryParser } from './io/binaryParser';
-export { fetchRange, BufferedRangeReader } from './io/rangeReader';
-export type { ByteRange } from './io/rangeReader';
 export { BigWigDataSource } from './dataSources/bigWigDataSource';
 export { GtxDataSource } from './dataSources/gtxDataSource';
 export { GeneDataSource } from './dataSources/geneDataSource';
 export { TextFeatureSource } from './dataSources/textFeatureSource';
 export type { TextFeatureSourceConfig } from './dataSources/textFeatureSource';
-export { SequenceDataSource } from './dataSources/sequenceDataSource';
+export { SequenceDataSource, DEFAULT_BPP_SEQUENCE_THRESHOLD } from './dataSources/sequenceDataSource';
 export { MemoryDataSource } from './dataSources/memoryDataSource';
 export { createFeatureSource } from './dataSources/featureSourceFactory';
 export type { FeatureSourceConfig, FeatureSourceResult } from './dataSources/featureSourceFactory';
@@ -117,8 +124,8 @@ export { renderROIOverlays } from './roi';
 export type { ROIRenderOptions } from './roi';
 export { registerTrackCreator, registerTypeAlias, getTrackCreator, knownTrackTypes, createTrackFromConfig, } from './trackRegistry';
 export type { TrackCreatorContext, TrackCreator, CreatedTrack } from './trackRegistry';
-export { SESSION_VERSION, createDataSource, createTrackFromSession, fromIgvSession, toIgvSession, } from './session';
-export type { CreateDataSourceOptions, CreateTrackFromSessionOptions } from './session';
+export { SESSION_VERSION, createTrackFromSession, fromIgvSession, toIgvSession, } from './browser/headless/session';
+export type { CreateTrackFromSessionOptions } from './browser/headless/session';
 export { StateProjection } from './stateProjection';
 export type { ZoomLevel, TrackSummary, ProjectedState, StateDiff, TrackChangeDiff, GetStateOptions } from './stateProjection';
 export { matchesSelector, selectTracks } from './trackSelector';

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

@@ -10,7 +10,6 @@ export declare class BinaryParser {
     constructor(dataView: DataView, littleEndian?: boolean);
     setPosition(position: number): void;
     available(): number;
-    remLength(): number;
     getByte(): number;
     getShort(): number;
     getUShort(): number;

package/dist/types/logger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Structured logger for the Loom genome browser.
+ *
+ * Replaces scattered `console.log/warn/error` calls with a level-gated logger
+ * that can be silenced or redirected by consumers.
+ *
+ * Default level: 'warn' — only warnings and errors are logged.
+ * Call `setLogLevel('silent')` to suppress all output in production.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Set the minimum log level. Messages below this level are suppressed. */
+export declare function setLogLevel(level: LogLevel): void;
+/** Get the current log level. */
+export declare function getLogLevel(): LogLevel;
+export declare const log: {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};

package/dist/types/pointerEventManager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * PointerEventManager — pointer interaction state machine for GenomeBrowser.
+ *
+ * Owns all pointer-driven interaction state and handlers:
+ * - Drag-to-pan (pointer capture + rAF batching)
+ * - Sweep-to-zoom (ruler drag → selection overlay)
+ * - Click / double-click detection
+ * - Hover throttling
+ * - Scroll-wheel / trackpad pinch-to-zoom
+ * - Drag-to-reorder tracks
+ *
+ * Extracted from GenomeBrowser to isolate the complex pointer state machine
+ * from DOM layout and track lifecycle management.
+ *
+ * Layer 4 (DOM): requires DOM APIs.
+ */
+import type { Track, Locus, TrackInteractionEvent, PopupDataItem } from './types';
+import type { ManagedTrack } from './headlessGenomeBrowser';
+import type { CumulativeOffsets, ChromSizes } from './genome/chromSizes';
+import type { UndoEntryType } from './undoManager';
+/** Callback interface for browser operations — wired by GenomeBrowser. */
+export interface PointerBrowserAccess {
+    getLocus(): Locus;
+    /** Set locus directly without triggering data load (used during drag). */
+    setLocusDirect(locus: Locus): void;
+    clampLocus(locus: Locus): Locus;
+    /** Set locus with full data lifecycle (used for sweep zoom, WG click). */
+    setLocus(locus: Locus): void;
+    getViewportWidth(): number;
+    getManagedTracks(): readonly ManagedTrack[];
+    loadAllTracksIfNeeded(): void;
+    zoomAroundCenter(factor: number, centerBP: number): void;
+    resolveInteraction(track: Track, x: number, y: number): TrackInteractionEvent | null;
+    findTrackForTarget(target: EventTarget | null): Track | null;
+    isRulerCanvas(target: EventTarget | null): boolean;
+    showPopup(data: PopupDataItem[], position: {
+        x: number;
+        y: number;
+    }): void;
+    hidePopup(): void;
+    hideContextMenu(): void;
+    isOverlayTarget(e: Event): boolean;
+    setFeatureOverlaysSuppressed(suppressed: boolean): void;
+    emitLocusChange(locus: Locus): void;
+    emitTrackClick(event: TrackInteractionEvent): void;
+    emitTrackHover(event: TrackInteractionEvent): void;
+    emitTrackOrderChanged(tracks: Track[]): void;
+    snapshotForUndo(type: UndoEntryType): void;
+    getCumulativeOffsets(): CumulativeOffsets | undefined;
+    getChromSizes(): ChromSizes | undefined;
+    getTrackAxisDiv(track: Track): HTMLDivElement | undefined;
+    moveTrackInArray(fromIndex: number, toIndex: number): void;
+    syncDOMOrder(): void;
+    finalizeReorder(): void;
+}
+export declare class PointerEventManager {
+    private options;
+    private container;
+    private browser;
+    private axisColumnWidth;
+    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 _preNavLocus;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleMouseMove;
+    private handleMouseLeave;
+    private handleWheel;
+    private wheelRafId;
+    private reorderDragTrack;
+    private reorderDragRow;
+    private reorderHandlers;
+    constructor(container: HTMLElement, browser: PointerBrowserAccess, axisColumnWidth: number, options: {
+        wheelZoom?: boolean;
+    });
+    /** Set up all pointer event handlers. */
+    setup(): void;
+    /** Tear down all pointer event handlers and clean up state. */
+    dispose(): void;
+    /** Set up drag-to-reorder pointer handlers on a track's axis div. */
+    setupReorderForTrack(track: Track, axisDiv: HTMLDivElement): void;
+    /** Remove reorder handlers for a track. */
+    teardownReorderForTrack(track: Track): void;
+    private createSweepOverlay;
+    private removeSweepOverlay;
+    private setupDragHandlers;
+    private handleClick;
+    private teardownDragHandlers;
+    private setupHoverHandlers;
+    private teardownHoverHandlers;
+    private setupWheelHandler;
+    private teardownWheelHandler;
+    /** Get the DOM row element for a track (via browser). */
+    private getTrackRow;
+}

package/dist/types/react/GenomeBrowserContext.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../genomeBrowser';
+import type { GenomeBrowser } from '../browser/dom/genomeBrowser';
 import type { ShellTheme } from '../ui/themes';
 export interface GenomeBrowserContextValue {
     /** The underlying GenomeBrowser instance. null before initialization or during SSR. */

package/dist/types/react/LoomBrowser.d.ts

@@ -5,9 +5,9 @@ import type { WorkerProvider } from '../workerProvider';
 import type { PopupProvider } from '../popupProvider';
 import type { ContextMenuProvider } from '../contextMenuProvider';
 import type { RemoteSocket } from '../remoteProtocol';
-import { GenomeBrowser } from '../genomeBrowser';
-import type { ManagedTrack } from '../headlessGenomeBrowser';
-import type { CreateTrackFromSessionOptions } from '../session';
+import { GenomeBrowser } from '../browser/dom/genomeBrowser';
+import type { ManagedTrack } from '../browser/headless/headlessGenomeBrowser';
+import type { CreateTrackFromSessionOptions } from '../browser/headless/session';
 import type { TrackSelector } from '../trackSelector';
 import { ROISet } from '../roi/roiSet';
 export interface LoomBrowserProps {
@@ -67,7 +67,7 @@ export interface LoomBrowserProps {
 export interface LoomBrowserHandle {
     /** The underlying GenomeBrowser instance. null during SSR. */
     readonly browser: GenomeBrowser | null;
-    search(query: string): boolean;
+    search(query: string): Promise<boolean>;
     zoomIn(factor?: number): void;
     zoomOut(factor?: number): void;
     addTrackFromConfig(config: TrackSessionConfig): Track;

package/dist/types/react/hooks/useBrowserEvent.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserEvents } from '../../headlessGenomeBrowser';
+import type { BrowserEvents } from '../../browser/headless/headlessGenomeBrowser';
 /**
  * Subscribe to a typed browser event. Automatically subscribes/unsubscribes
  * with the browser lifecycle. Uses a stable ref for the handler to avoid

package/dist/types/react/hooks/useGenomeBrowser.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 /**
  * Access the GenomeBrowser instance from context.
  * Returns null before the browser initializes (SSR or first render).

package/dist/types/react/hooks/useTrackManager.d.ts

@@ -1,5 +1,5 @@
 import type { Track } from '../../types';
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 /** Per-track click event with typed features. */
 export interface TrackClickEvent<F> {
     features: F[];

package/dist/types/react/tracks/BedTrack.d.ts

@@ -1,10 +1,10 @@
 import type { BedFeature, AnnotationRenderConfig, TextFileFormat } from '../../types';
 import type { TrackClickEvent } from '../hooks/useTrackManager';
-export interface BedTrackProps {
+export interface BedTrackProps<F extends BedFeature = BedFeature> {
     /** URL to a BED/peak file. Mutually exclusive with `features`. */
     url?: string;
     /** In-memory annotation features. Mutually exclusive with `url`. Features must include `chr`. */
-    features?: BedFeature[];
+    features?: F[];
     config?: Partial<AnnotationRenderConfig>;
     height?: number;
     background?: string;
@@ -15,10 +15,10 @@ export interface BedTrackProps {
     name?: string;
     metadata?: Record<string, string>;
     /** Compute per-feature color. Applied to in-memory features before rendering. */
-    colorBy?: (feature: BedFeature) => string;
-    /** Called when this track is clicked. Features are typed as BedFeature. */
-    onClick?: (event: TrackClickEvent<BedFeature>) => void;
+    colorBy?: (feature: F) => string;
+    /** Called when this track is clicked. */
+    onClick?: (event: TrackClickEvent<F>) => void;
     /** Called when this track is right-clicked. */
-    onContextMenu?: (event: TrackClickEvent<BedFeature>) => void;
+    onContextMenu?: (event: TrackClickEvent<F>) => void;
 }
-export declare function BedTrack({ url, features, config, height, background, format, indexURL, indexed, maxTrackHeight, name, metadata, colorBy, onClick, onContextMenu }: BedTrackProps): null;
+export declare function BedTrack<F extends BedFeature = BedFeature>({ url, features, config, height, background, format, indexURL, indexed, maxTrackHeight, name, metadata, colorBy, onClick, onContextMenu }: BedTrackProps<F>): null;

package/dist/types/react/ui/ChromosomeSelect.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import './types';
 export interface ChromosomeSelectProps {
     /** Override the browser from context. */

package/dist/types/react/ui/ExportControls.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import './types';
 export interface ExportControlsProps {
     /** Override the browser from context. */

package/dist/types/react/ui/LocusInput.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import './types';
 export interface LocusInputProps {
     /** Override the browser from context. */

package/dist/types/react/ui/Navbar.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import type { ShellTheme } from '../../ui/themes';
 import './types';
 export interface NavbarProps {

package/dist/types/react/ui/WindowSize.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import './types';
 export interface WindowSizeProps {
     /** Override the browser from context. */

package/dist/types/react/ui/ZoomControls.d.ts

@@ -1,4 +1,4 @@
-import type { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowser } from '../../browser/dom/genomeBrowser';
 import './types';
 export interface ZoomControlsProps {
     /** Override the browser from context. */

package/dist/types/remoteProtocol.d.ts

@@ -8,7 +8,7 @@
  * 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 { HeadlessGenomeBrowser } from './browser/headless/headlessGenomeBrowser';
 import type { CommandDispatcherOptions } from './commandDispatcher';
 /** Inbound: agent/server sends a command request. */
 export interface RequestMessage {

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

@@ -0,0 +1,38 @@
+/**
+ * ROIOverlayManager — DOM-based Region of Interest overlay rendering.
+ *
+ * Manages ROI region elements (colored overlays with labels) positioned
+ * over the track viewport. Uses DOM elements (not canvas) for easy
+ * hover/click interaction without re-rendering track canvases.
+ *
+ * Extracted from GenomeBrowser to isolate ROI DOM lifecycle management.
+ *
+ * Layer 4 (DOM): requires DOM APIs.
+ */
+import type { ROI, Locus } from './types';
+/** Callback interface for ROI overlay events — wired by GenomeBrowser. */
+export interface ROIOverlayCallbacks {
+    onROIClick(roiId: string, e: MouseEvent): void;
+    onROIContextMenu(roiId: string, e: MouseEvent): void;
+}
+export declare class ROIOverlayManager {
+    private container;
+    private axisColumnWidth;
+    private overlayContainer;
+    private roiElements;
+    private callbacks;
+    constructor(container: HTMLElement, axisColumnWidth: number, callbacks: ROIOverlayCallbacks);
+    /**
+     * Render ROI overlays for the given visible ROIs.
+     * Creates/updates/removes DOM elements to match the current viewport.
+     */
+    render(visibleROIs: ROI[], locus: Locus, viewportWidth: number): void;
+    /** Remove all ROI elements and the overlay container. */
+    clear(): void;
+    /** Alias for clear — clean up all ROI overlay resources. */
+    dispose(): void;
+    /** Ensure the ROI overlay container exists and is sized correctly. */
+    private ensureContainer;
+    /** Create a styled DOM element for an ROI region. */
+    private createElement;
+}

package/dist/types/stateProjection.d.ts

@@ -10,7 +10,7 @@
  * Swappable: consumers can extend or replace this class for custom projection logic.
  */
 import type { Locus, TrackFeatureSummary, ROISetConfig } from './types';
-import type { HeadlessGenomeBrowser, ManagedTrack } from './headlessGenomeBrowser';
+import type { HeadlessGenomeBrowser, ManagedTrack } from './browser/headless/headlessGenomeBrowser';
 /** Zoom level classification based on viewport span. */
 export type ZoomLevel = 'base' | 'element' | 'gene' | 'region' | 'chromosome' | 'genome';
 /** Concise summary of a single track, suitable for LLM consumption. */

package/dist/types/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;
+}