loom-browser 0.0.9 → 0.0.10

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

package/dist/types/trackFactories.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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;
+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>;

package/dist/types/trackSelector.d.ts

@@ -13,7 +13,7 @@
  * browser.findTracks({ type: 'wig', where: { biosample: 'K562' } })
  * ```
  */
-import type { ManagedTrack } from './headlessGenomeBrowser';
+import type { ManagedTrack } from './browser/headless/headlessGenomeBrowser';
 /** Selector for matching tracks by ID, name, type, and/or metadata. */
 export interface TrackSelector {
     /** Exact match against track ID. */

package/dist/types/tracks/annotation/annotationTrackCanvas.d.ts

@@ -14,7 +14,6 @@ import type { AnnotationFeature, AnnotationRenderConfig, Locus, RenderContext, A
 import type { CanvasProvider } from '../../canvasProvider';
 import type { RenderTheme } from '../../themes/renderTheme';
 import { BaseTrackCanvas } from '../baseTrackCanvas';
-export type { Locus } from '../../types';
 export interface AnnotationTrackCanvasOptions {
     locus: Locus;
     features: AnnotationFeature[];

package/dist/types/tracks/annotation/config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Annotation track render configuration.
+ *
+ * Controls rendering of gene, BED, GFF, and peak features.
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+/** Display mode for gene features. */
+export type DisplayMode = 'COLLAPSED' | 'SQUISHED' | 'EXPANDED';
+/** Configuration controlling how annotation features (gene, BED, GFF, peaks) are rendered. */
+export interface AnnotationRenderConfig {
+    displayMode: DisplayMode;
+    featureHeight: number;
+    margin: number;
+    /** Row height in EXPANDED mode (featureHeight + label space + padding). */
+    expandedRowHeight: number;
+    /** Row height in SQUISHED mode. */
+    squishedRowHeight: number;
+    /** Pixel spacing between strand-direction arrows. */
+    arrowSpacing: number;
+    /** Default fill color for CDS exons. */
+    color: string;
+    /** Color for features on the opposite strand (if desired). */
+    altColor?: string;
+    /** Which feature property to use as the label. */
+    labelField: string;
+    /** CSS font string for labels, e.g. "10px sans-serif". */
+    font: string;
+    /** Whether to draw labels. */
+    drawLabels: boolean;
+    /** Label display mode — "SLANT" rotates labels 45°. */
+    labelDisplayMode?: 'SLANT';
+    /** UTR fill color. Defaults to main color. */
+    utrColor?: string;
+    /** Alt UTR color (for - strand when altColor is set). */
+    altUtrColor?: string;
+    /** Exon stroke outline color. No outline when undefined. */
+    borderColor?: string;
+    /** Exon outline width. Default: 0 (no outline). */
+    borderWidth?: number;
+    /** Rounded corner radius for exon rects. Default: 0 (square). */
+    borderRadius?: number;
+    /** Intron line color. Defaults to main color. */
+    intronColor?: string;
+    /** Intron line width. Default: 1. */
+    intronLineWidth?: number;
+    /** Dash pattern for intron lines, e.g. [3, 3]. Default: [] (solid). */
+    intronDash?: number[];
+    /** Strand arrow color on intron lines. Defaults to current stroke color. */
+    arrowColor?: string;
+    /** Strand arrow color inside exons. Default: 'white'. */
+    arrowInExonColor?: string;
+    /** Label text color. Defaults to feature color. */
+    labelColor?: string;
+    /** Background color behind labels. When set, fills behind labels instead of clearing to transparent. */
+    labelBackground?: string;
+    /** Separate CSS font string for labels. Defaults to `font`. */
+    labelFont?: string;
+}
+/** Returns sensible defaults for annotation feature rendering. */
+export declare function defaultAnnotationRenderConfig(): AnnotationRenderConfig;

package/dist/types/tracks/baseTrackCanvas.d.ts

@@ -35,6 +35,16 @@ export declare abstract class BaseTrackCanvas<TConfig> implements Track {
      * Set to undefined or 0 to disable (always fetch). Set > 0 to enable.
      */
     visibilityWindow?: number;
+    /**
+     * Callback invoked just before setConfig() applies changes.
+     * The browser registers this to snapshot state for undo (capturing pre-mutation state).
+     */
+    onBeforeConfigChange?: () => void;
+    /**
+     * Callback invoked after setConfig() merges new config and re-renders.
+     * The browser registers this to emit TrackConfigChanged.
+     */
+    onConfigChanged?: () => void;
     abstract readonly type: string;
     get canvas(): HTMLCanvasElement;
     get locus(): Locus;

package/dist/types/tracks/configDiff.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed config diff utility for track session serialization.
+ *
+ * Compares a track's current config against theme defaults and returns
+ * only the fields that differ. Eliminates the `as Record<string, unknown>`
+ * casts previously duplicated across track canvas serializeConfig() methods.
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+/**
+ * Compute the diff between a config object and its defaults.
+ * Returns a Partial containing only changed fields, or undefined if no changes.
+ */
+export declare function diffConfig<T extends object>(config: T, defaults: T): Partial<T> | undefined;

package/dist/types/tracks/interaction/config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Interaction track render configuration.
+ *
+ * Controls rendering of chromatin interaction arcs (Hi-C, ChIA-PET, BEDPE).
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+/** Arc orientation: arcs open upward or downward. */
+export type ArcOrientation = 'UP' | 'DOWN';
+/** Display mode for interaction arcs. */
+export type ArcDisplayMode = 'nested' | 'proportional';
+/** Configuration controlling how interaction features are rendered as arcs. */
+export interface InteractionRenderConfig {
+    /** Track height in CSS pixels. Default: 250. */
+    height: number;
+    /** Arc direction. Default: 'UP'. */
+    arcOrientation: ArcOrientation;
+    /** Display mode. Default: 'nested'. */
+    displayMode: ArcDisplayMode;
+    /** Show small rectangles at feature endpoints. Default: true. */
+    showBlocks: boolean;
+    /** Height of endpoint rectangles in pixels. Default: 3. */
+    blockHeight: number;
+    /** Arc stroke width in pixels. Default: 1. */
+    thickness: number;
+    /** Default arc color. Default: 'rgb(180,25,137)'. */
+    color: string;
+    /** Fill alpha for arcs. Default: 0.02. */
+    alpha: number;
+    /** Use log scale for proportional arc heights. Default: true. */
+    logScale: boolean;
+    /** Background color. Default: '#ffffff'. */
+    background: string;
+    /** Font for inter-chromosome labels. Default: '8px sans-serif'. */
+    font: string;
+    /** Whether to use score-based shading. Default: false. */
+    useScore: boolean;
+}
+/** Returns sensible defaults for interaction rendering. */
+export declare function defaultInteractionRenderConfig(): InteractionRenderConfig;