loom-browser 0.0.9 → 0.0.11

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;

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

@@ -0,0 +1,24 @@
+/**
+ * Ruler track render configuration.
+ *
+ * Controls rendering of the coordinate ruler track.
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+/** Configuration for ruler track rendering. */
+export interface RulerRenderConfig {
+    /** Total height in CSS pixels. Default: 40. */
+    height: number;
+    /** Font for tick labels. Default: 'bold 10px sans-serif'. */
+    font: string;
+    /** Tick line color. Default: 'rgb(150, 150, 150)'. */
+    tickColor: string;
+    /** Label text color. Default: 'rgb(0, 0, 0)'. */
+    labelColor: string;
+    /** Baseline (bottom rule) color. Default: 'rgb(150, 150, 150)'. */
+    baselineColor: string;
+    /** Background color. Default: 'white'. */
+    background: string;
+}
+/** Returns sensible defaults for ruler rendering. */
+export declare function defaultRulerRenderConfig(): RulerRenderConfig;

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

@@ -0,0 +1,56 @@
+/**
+ * Sequence track render configuration.
+ *
+ * Controls rendering of DNA sequence tracks with optional 3-frame translation.
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+/** Sequence type for the sequence track. */
+export type SequenceType = 'dna' | 'rna' | 'prot';
+/** Configuration controlling how sequence features are rendered. */
+export interface SequenceRenderConfig {
+    /** Sequence type (affects coloring). Default: 'dna'. */
+    sequenceType: SequenceType;
+    /** Show reverse complement. Default: false. */
+    reversed: boolean;
+    /** Show three-frame amino acid translation. Default: false. */
+    frameTranslate: boolean;
+    /** Override color for all bases. When set, ignores nucleotide color map. */
+    color?: string;
+    /** Background color. Default: '#ffffff'. */
+    background: string;
+    /** Nucleotide color mapping (A, C, G, T, N). Used when sequenceType is 'dna'. */
+    nucleotideColors: Record<string, string>;
+    /** Default color for RNA/protein bases. Default: 'rgb(0, 0, 150)'. */
+    nonDnaColor: string;
+    /** Track height without translation frames. Default: 25. */
+    defaultHeight: number;
+    /** Track height with translation frames. Default: 115. */
+    translatedHeight: number;
+    /** Height of the sequence row. Default: 15. */
+    sequenceHeight: number;
+    /** Height of each translation frame row. Default: 25. */
+    frameHeight: number;
+    /** Border/padding between elements. Default: 5. */
+    frameBorder: number;
+    /** Alternating background color 1 for translation frames. Default: 'rgb(160,160,160)'. */
+    frameColor1: string;
+    /** Alternating background color 2 for translation frames. Default: 'rgb(224,224,224)'. */
+    frameColor2: string;
+    /** Stop codon highlight color. Default: 'rgb(255, 0, 0)'. */
+    stopCodonColor: string;
+    /** Start codon (M) highlight color. Default: 'rgb(0, 153, 0)'. */
+    startCodonColor: string;
+    /** Use fillText instead of strokeText for base and amino acid labels. Default: false (strokeText, matching igv.js). */
+    useFillText: boolean;
+    /** Color for amino acid labels in translation frames. Default: '#000000'. */
+    frameLabelColor: string;
+    /** Color for amino acid labels on start/stop codon backgrounds. Default: same as frameLabelColor. */
+    codonLabelColor?: string;
+    /** Font for amino acid labels in translation frames. Default: 'bold 10px sans-serif'. */
+    frameFont: string;
+    /** Border radius for start/stop codon highlights (roundRect). 0 = sharp rectangles. Default: 0. */
+    codonBorderRadius: number;
+}
+/** Returns sensible defaults for sequence rendering. */
+export declare function defaultSequenceRenderConfig(): SequenceRenderConfig;

package/dist/types/tracks/sequence/sequenceTrackCanvas.d.ts

@@ -28,11 +28,14 @@ export interface SequenceTrackCanvasOptions {
     config?: Partial<SequenceRenderConfig>;
     theme?: Partial<RenderTheme>;
     canvasProvider?: CanvasProvider;
+    /** bpPerPixel threshold above which sequence data is not loaded. Default: 10. */
+    bppSequenceThreshold?: number;
 }
 export declare class SequenceTrackCanvas extends BaseTrackCanvas<SequenceRenderConfig> {
     readonly type = "sequence";
     private _sequence;
     private _theme;
+    private _bppThreshold;
     constructor(canvas: HTMLCanvasElement, options: SequenceTrackCanvasOptions);
     /**
      * Whether the current viewport is zoomed in enough to fetch/render sequence.

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

@@ -0,0 +1,77 @@
+/**
+ * Wig track render configuration.
+ *
+ * Controls rendering of quantitative signal tracks (BigWig, GTX).
+ *
+ * Layer 2 (Track Canvases): no DOM.
+ */
+import type { WindowFunction } from '../../types';
+/** Graph type for wig track rendering. */
+export type WigGraphType = 'bar' | 'line' | 'points' | 'dynseq';
+/** A horizontal guide line drawn at a specific data value. */
+export interface WigGuideLine {
+    /** The data value at which to draw the line. */
+    y: number;
+    /** Line color. */
+    color: string;
+    /** Whether to draw a dashed line. */
+    dotted: boolean;
+}
+/** Color value for wig features: a static CSS color string or a function mapping value → color. */
+export type WigColorValue = string | ((value: number) => string);
+/** Configuration controlling how wig features are rendered. */
+export interface WigRenderConfig {
+    /** Track height in CSS pixels. Default: 50. */
+    height: number;
+    /** Graph rendering style. Default: 'bar'. */
+    graphType: WigGraphType;
+    /** Data aggregation when zoomed out. Default: 'mean'. */
+    windowFunction: WindowFunction;
+    /** Y-axis data range. Features are scaled to this range. */
+    dataRange: {
+        min: number;
+        max: number;
+    };
+    /** Whether to auto-compute dataRange from features. Default: true. */
+    autoscale: boolean;
+    /** Fill/stroke color for positive values. String or (value) => color function. Default: 'rgb(150, 150, 150)'. */
+    color: WigColorValue;
+    /** Fill/stroke color for negative values. String or (value) => color function. Uses `color` when undefined. */
+    altColor?: WigColorValue;
+    /** Alpha transparency for feature colors (0–1). Applied on top of resolved color. Default: undefined (fully opaque). */
+    alpha?: number;
+    /** Flip the y-axis (values grow downward). Default: false. */
+    flipAxis: boolean;
+    /** Use logarithmic scale for the y-axis. Default: false. */
+    logScale: boolean;
+    /** Color for the zero-line baseline. Default: 'lightGray'. */
+    baselineColor: string;
+    /** Color for out-of-range value indicators. Default: 'rgb(255, 32, 255)'. */
+    overflowColor: string;
+    /** Point diameter in pixels (for 'points' graphType). Default: 3. */
+    pointSize: number;
+    /** Background color. Default: '#ffffff'. */
+    background: string;
+    /** Optional horizontal guide lines. */
+    guideLines?: WigGuideLine[];
+    /** Nucleotide colors for dynseq rendering. Keys: A, C, G, T, N. */
+    nucleotideColors?: Record<string, string>;
+    /** Multiply all feature values by this factor before rendering. Default: undefined (no scaling). */
+    scaleFactor?: number;
+    /**
+     * Normalization factor applied to all feature values (e.g. reads-per-million from TDF).
+     * When set, all values are multiplied by this factor before scaleFactor is applied.
+     * Typically provided by the data source rather than set manually.
+     */
+    normalizationFactor?: number;
+    /** Whether to draw min/max data range labels on the track. Default: true. */
+    showDataRange: boolean;
+    /** Color for data range label text. Default: palette.foreground. */
+    labelColor: string;
+    /** Font for data range labels. Default: 'bold 9px sans-serif'. */
+    labelFont: string;
+    /** Track name to display as an overlay label (igv.js style, top-left). */
+    trackName?: string;
+}
+/** Returns sensible defaults for wig rendering. */
+export declare function defaultWigRenderConfig(): WigRenderConfig;

package/dist/types/types/igvCompat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * IGV.js compatibility types.
+ *
+ * Minimal type definitions for igv.js session import/export.
+ * Used only by session serialization — not part of the core Loom type system.
+ */
+/** Minimal igv.js session shape — just enough to parse/produce sessions. */
+export interface IgvSessionObject {
+    version?: string;
+    reference?: IgvReferenceConfig;
+    genome?: string;
+    locus?: string | string[];
+    tracks?: IgvTrackConfig[];
+}
+export interface IgvReferenceConfig {
+    id?: string;
+    fastaURL?: string;
+    indexURL?: string;
+}
+export interface IgvTrackConfig {
+    type?: string;
+    format?: string;
+    url?: string;
+    indexURL?: string;
+    name?: string;
+    color?: string;
+    altColor?: string;
+    height?: number;
+    min?: number;
+    max?: number;
+    autoscale?: boolean;
+    displayMode?: string;
+    order?: number;
+    visibilityWindow?: number;
+    windowFunction?: string;
+}