loom-browser 0.0.8 → 0.0.10

package/dist/types/browser/dom/browserExport.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Browser export utilities — SVG and PNG export for the DOM GenomeBrowser.
+ *
+ * Pure functions that render the multi-track browser state to SVG/PNG,
+ * including axis columns and ROI overlays.
+ *
+ * Extracted from GenomeBrowser to isolate export logic.
+ *
+ * Layer 4 (DOM): requires DOM APIs (for PNG rendering via Image/Canvas).
+ */
+import type { Locus, ROI } from '../../types';
+import type { ManagedTrack } from '../headless/headlessGenomeBrowser';
+import type { RenderTheme } from '../../themes/renderTheme';
+/**
+ * Render the DOM browser view as an SVG string, including axis columns.
+ *
+ * Pure function — takes all needed state as parameters.
+ * Matches igv.js Browser.toSVG() which calls renderSVGAxis() for each TrackView.
+ */
+export declare function renderDOMBrowserSVG(managedTracks: readonly ManagedTrack[], locus: Locus, theme: RenderTheme, visibleROIs: ROI[], axisColumnWidth: number, options?: {
+    width?: number;
+    containerWidth?: number;
+    backdropColor?: string;
+}): string;
+/**
+ * Convert an SVG string to a PNG data URL.
+ *
+ * Pipeline: SVG string → Blob → object URL → Image → Canvas (DPR-scaled) → toDataURL.
+ */
+export declare function svgToPNG(svgString: string, width: number, height: number, dpr: number): Promise<string>;
+/** Trigger a file download via a temporary anchor element. */
+export declare function triggerDownload(filename: string, url: string): void;

package/dist/types/browser/dom/contextMenu.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Common context menu item factories.
+ *
+ * Stateless functions that return ContextMenuItem[] — no DOM, no side effects.
+ * The ContextMenuCallbacks interface decouples menu items from browser-level
+ * actions (removing tracks, showing dialogs).
+ *
+ * `numericDataMenuItems()` mirrors igv.js `TrackBase.numericDataMenuItems()`
+ * (js/trackBase.ts lines 510-552), which is shared by WigTrack, BAMTrack,
+ * QTLTrack, GCNVTrack, CNVPytorTrack, GWASTrack, InteractionTrack, and
+ * MergedTrack — any track with a Y-axis data range.
+ */
+import type { ContextMenuItem, NumericState, Track, ROI, Locus } from '../../types';
+/**
+ * Callback interface for common menu actions that require browser-level
+ * coordination. GenomeBrowser provides the implementation.
+ */
+export interface ContextMenuCallbacks {
+    /** Set the track's pixel height and re-render. */
+    setTrackHeight(track: Track, height: number): void;
+    /** Remove the track from the browser. */
+    removeTrack(track: Track): void;
+    /** Show an input dialog. Returns the entered value, or null if cancelled. */
+    promptInput(label: string, currentValue: string | number): Promise<string | null>;
+}
+/** Common menu items that apply to all tracks (set height, remove). */
+export declare function commonContextMenuItems(track: Track, callbacks: ContextMenuCallbacks): ContextMenuItem[];
+/**
+ * Menu items for quantitative/numeric tracks: set data range, log scale, autoscale.
+ *
+ * Mirrors igv.js `TrackBase.numericDataMenuItems()` (js/trackBase.ts lines 510-552).
+ * In igv.js this is a method on TrackBase used by 8 track classes. In our
+ * architecture it's a stateless factory that takes the track's NumericState
+ * (state + callbacks combined), matching our separation of data from DOM.
+ *
+ * Items produced:
+ * 1. "Set data range" — prompts for min/max, disables autoscale when set
+ *    (mirrors igv.js DataRangeDialog → TrackBase.setDataRange)
+ * 2. "Log scale" checkbox — only if logScale is supported (state.logScale !== undefined)
+ *    (mirrors igv.js conditional on this.logScale !== undefined)
+ * 3. "Autoscale" checkbox
+ *    (mirrors igv.js autoScaleHandler)
+ */
+export declare function numericDataMenuItems(state: NumericState, promptInput: ContextMenuCallbacks['promptInput']): ContextMenuItem[];
+/**
+ * Callback interface for ROI menu actions that require browser-level coordination.
+ */
+export interface ROIMenuCallbacks {
+    /** Navigate the browser to the ROI's genomic region. */
+    goToRegion(locus: Locus): void;
+    /** Update an ROI's properties. */
+    updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): void;
+    /** Remove an ROI by ID. */
+    removeROI(roiId: string): void;
+    /** Show an input dialog. Returns the entered value, or null if cancelled. */
+    promptInput(label: string, currentValue: string | number): Promise<string | null>;
+}
+/**
+ * Context menu items for an ROI region.
+ *
+ * Mirrors igv.js ROIMenu (js/roi/ROIMenu.ts) but with stateless factory pattern.
+ * Items: edit name, edit description, set color, separator, go to region, remove.
+ */
+export declare function roiContextMenuItems(roi: ROI, callbacks: ROIMenuCallbacks): ContextMenuItem[];

package/dist/types/browser/dom/contextMenuManager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ContextMenuManager — handles right-click context menus for tracks and ROIs.
+ *
+ * Manages the contextmenu event listener, lazy input dialog creation,
+ * track-specific and common menu item assembly, and ROI context menus.
+ *
+ * Extracted from GenomeBrowser to isolate context menu lifecycle.
+ *
+ * Layer 4 (DOM): requires DOM APIs.
+ */
+import type { Track, TrackContextMenuEvent, ROI, Locus } from '../../types';
+import type { ContextMenuProvider } from '../../contextMenuProvider';
+import type { PopupProvider } from '../../popupProvider';
+/** Callback interface for context menu actions that require browser-level coordination. */
+export interface ContextMenuManagerCallbacks {
+    findTrackForTarget(target: EventTarget | null): Track | null;
+    getLocus(): Locus;
+    getViewportWidth(): number;
+    removeTrack(track: Track): void;
+    onAxisUpdate(track: Track): void;
+    updateROI(roiId: string, changes: Partial<Omit<ROI, 'id'>>): ROI | undefined;
+    removeROI(roiId: string): boolean;
+    setLocus(locus: Locus): void;
+    emitTrackContextMenu(event: TrackContextMenuEvent): void;
+    emitROIContextMenu(event: {
+        roi: ROI;
+        genomicLocation: number;
+        x: number;
+        y: number;
+    }): void;
+}
+export declare class ContextMenuManager {
+    private container;
+    private axisColumnWidth;
+    private contextMenuProvider;
+    private popupProvider;
+    private callbacks;
+    private handleContextMenu;
+    private inputDialog;
+    constructor(container: HTMLElement, axisColumnWidth: number, contextMenuProvider: ContextMenuProvider | undefined, popupProvider: PopupProvider | undefined, callbacks: ContextMenuManagerCallbacks);
+    /** Attach the contextmenu event listener to the container. */
+    setup(): void;
+    /** Show context menu for an ROI region. */
+    showROIContextMenu(roi: ROI, e: MouseEvent): void;
+    /** Remove context menu listener and dispose of input dialog. */
+    dispose(): void;
+    /** Lazy-create the input dialog element. Consolidates duplicated creation logic. */
+    private ensureInputDialog;
+}

package/dist/types/browser/dom/defaultProviders.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Default provider factories for GenomeBrowser.
+ *
+ * Creates lazy-loaded Web Component-based providers for popups and context menus.
+ * Separated to keep GenomeBrowser focused on browser orchestration.
+ *
+ * Layer 4 (DOM): requires DOM APIs.
+ */
+import type { ContextMenuProvider } from '../../contextMenuProvider';
+import type { PopupProvider } from '../../popupProvider';
+/**
+ * Create a default ContextMenuProvider using <loom-context-menu>.
+ * This avoids statically importing the Web Component class (which extends
+ * HTMLElement and breaks SSR). The custom element self-registers on first
+ * import of ui/components/LoomContextMenu, but GenomeBrowser is always
+ * DOM-attached so we can safely trigger registration here.
+ */
+export declare function createDefaultContextMenuProvider(): ContextMenuProvider;
+/**
+ * Create a default PopupProvider using <loom-popup>.
+ * Same lazy/SSR-safe pattern as createDefaultContextMenuProvider.
+ */
+export declare function createDefaultPopupProvider(): PopupProvider;

package/dist/types/browser/dom/genomeBrowser.d.ts

@@ -0,0 +1,171 @@
+/**
+ * DOM-attached GenomeBrowser — extends HeadlessGenomeBrowser with pointer events,
+ * ResizeObserver, canvas stacking, and sweep-to-zoom.
+ *
+ * Coordinates multiple Track instances, stacking them vertically in a container.
+ * Static rendering is the base — interactivity (drag-to-pan) is enabled by default
+ * but can be disabled via `interactive: false`.
+ *
+ * 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 },
+ *   })
+ *   browser.addTrack(rulerTrack)
+ *   browser.addTrack(geneTrack)
+ *   // Drag to pan — works out of the box.
+ *   // Drag on ruler — sweep to zoom.
+ *   // Cleanup:
+ *   browser.dispose()
+ */
+import type { Track, DataSource, SessionConfig, DataSourceConfig } from "../../types";
+import { HeadlessGenomeBrowser } from "../headless/headlessGenomeBrowser";
+import type { HeadlessGenomeBrowserOptions } from "../headless/headlessGenomeBrowser";
+import type { RemoteSocket } from "../../remoteProtocol";
+import type { CreateTrackFromSessionOptions } from "../headless/session";
+export { BrowserEvent } from "../headless/headlessGenomeBrowser";
+export type { BrowserEvents } from "../headless/headlessGenomeBrowser";
+export interface GenomeBrowserOptions extends HeadlessGenomeBrowserOptions {
+    /** Enable mouse/touch drag to pan. Default: true. */
+    interactive?: boolean;
+    /** Enable trackpad pinch and scroll-wheel zoom. Default: true when interactive. */
+    wheelZoom?: boolean;
+    /**
+     * Auto-create a unified web worker pool for off-main-thread tasks and data fetching.
+     * - `true`: create a pool with `navigator.hardwareConcurrency` workers (capped at 4)
+     * - `number`: create a pool with that many workers
+     * - `false` / `undefined`: no auto-created workers (main-thread fallback)
+     *
+     * Ignored when `workerProvider` is explicitly passed.
+     *
+     * Uses `import.meta.url` to resolve the worker script. If worker creation
+     * fails (e.g. due to CSP or bundler issues), falls back silently to
+     * main-thread execution.
+     *
+     * For bundler users who need custom worker instantiation, pass
+     * `workerFactory` instead (see example below).
+     *
+     * @example
+     * ```ts
+     * // Simple — auto-detect pool size:
+     * new GenomeBrowser(container, { locus, workers: true })
+     *
+     * // Explicit pool size:
+     * new GenomeBrowser(container, { locus, workers: 2 })
+     *
+     * // Bundler users (webpack 5, Vite) — custom factory:
+     * new GenomeBrowser(container, {
+     *     locus,
+     *     workerFactory: () => new Worker(
+     *         new URL('loom/dist/loom-worker.js', import.meta.url)
+     *     ),
+     * })
+     * ```
+     */
+    workers?: boolean | number;
+    /**
+     * Factory function that creates Worker instances for the worker pool.
+     * Use this with bundlers (webpack 5, Vite) that require the
+     * `new Worker(new URL(...))` pattern.
+     *
+     * Ignored when `workerProvider` is explicitly passed.
+     * When set, `workers` defaults to `true` (pool size = hardwareConcurrency, capped at 4).
+     */
+    workerFactory?: () => Worker;
+}
+export declare class GenomeBrowser extends HeadlessGenomeBrowser {
+    private container;
+    private interactive;
+    private resizeObserver;
+    private trackRows;
+    private remoteConnection;
+    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;
+    /** Post-registration UI setup for a track row (axis content, cursors, drag handlers). */
+    private _setupTrackRowUI;
+    /** Add a track and attach its canvas to the container. */
+    addTrack<F>(track: Track, dataSource?: DataSource<F>, dataSourceConfig?: DataSourceConfig, maxTrackHeight?: number, order?: number): string;
+    /** Remove a track and its row from the container. */
+    removeTrack(trackOrId: Track | string): void;
+    /** Move a track and reorder the DOM rows to match. */
+    moveTrack(track: Track, toIndex: number): void;
+    /**
+     * Load a session, replacing all current tracks.
+     * Removes existing canvases from the DOM, then delegates to the headless
+     * implementation which recreates tracks. New canvases are attached via addTrack().
+     */
+    loadSession(session: SessionConfig, options?: CreateTrackFromSessionOptions): void;
+    /** Re-render all tracks, reading width from the DOM container. */
+    render(): void;
+    /**
+     * Attach a remote WebSocket connection.
+     * Incoming command messages are automatically dispatched.
+     * Browser events are automatically forwarded.
+     */
+    attachRemote(socket: RemoteSocket): void;
+    /** Detach the remote connection and stop forwarding events. */
+    detachRemote(): void;
+    dispose(): void;
+    /**
+     * Update the axis content for a track based on its getAxisInfo().
+     * Uses a canvas for quantitative axes (tick marks + labels) matching igv.js paintAxis,
+     * and a DOM label for annotation tracks (e.g., gene track name).
+     */
+    private updateAxisContent;
+    /**
+     * Prepare an axis canvas at the correct size with DPR scaling,
+     * then delegate to the stateless render function.
+     */
+    private paintAxisCanvas;
+    /** Check if a pointer event target is a ruler track canvas. */
+    private isRulerCanvas;
+    /** 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;
+    /** Sync DOM after any sort (addTrack, addGeneTrack, etc.). */
+    protected onTracksSorted(): void;
+    /** Reorder DOM rows to match managedTracks order. */
+    private syncDOMOrder;
+    private setupUndoKeyboardHandler;
+    private teardownUndoKeyboardHandler;
+    private renderROIOverlays;
+    /** Update all feature overlays after render. */
+    private updateFeatureOverlays;
+    /** Update the feature overlay for a single track. */
+    private updateFeatureOverlay;
+    /**
+     * Export the current view as an SVG string, including axis columns.
+     * Overrides HeadlessGenomeBrowser.toSVG() to add axis rendering.
+     */
+    toSVG(options?: {
+        width?: number;
+        backdropColor?: string;
+    }): string;
+    /**
+     * Export the current view as a PNG data URL.
+     * Pipeline: toSVG() → Blob → Image → Canvas (DPR-scaled) → toDataURL.
+     */
+    toPNG(): Promise<string>;
+    /** Download the current view as an SVG file. */
+    saveSVGtoFile(filename?: string): void;
+    /** Download the current view as a PNG file. */
+    savePNGtoFile(filename?: string): Promise<void>;
+}

package/dist/types/browser/dom/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 '../headless/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/browser/dom/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/browser/dom/svgFeatureOverlay.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SVG overlay for interactive feature highlighting.
+ *
+ * Positions transparent SVG `<rect>` elements on top of a track's canvas,
+ * providing native CSS `:hover` states and click targets without canvas repaints.
+ * Follows the same DOM-over-canvas pattern used by ROI overlays in GenomeBrowser.
+ *
+ * On hover, features get a tinted fill matching their own color plus a subtle
+ * glow/shadow effect, making the canvas-rendered feature feel highlighted.
+ */
+import type { FeatureRect } from '../../types';
+export declare class SVGFeatureOverlay {
+    private svg;
+    private group;
+    private defs;
+    /** Callback fired when a feature rect is clicked. */
+    onFeatureClick?: (rect: FeatureRect, event: MouseEvent) => void;
+    constructor(container: HTMLElement);
+    /** Rebuild SVG rects from feature geometry. */
+    update(rects: FeatureRect[]): void;
+    /** Suppress pointer events on overlay rects (e.g., during drag). */
+    setSuppressed(suppressed: boolean): void;
+    dispose(): void;
+    /** Create an SVG filter that produces a colored glow. */
+    private createGlowFilter;
+    private createRect;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Shared error utilities for the Loom genome browser.
+ *
+ * Consolidates error classification and normalization patterns
+ * previously scattered across multiple modules.
+ */
+/** Check if an error is an AbortError (from fetch abort, signal abort, or worker abort). */
+export declare function isAbortError(err: unknown): boolean;
+/** Normalize an unknown thrown value into an Error instance. */
+export declare function normalizeError(err: unknown): Error;