loom-browser 0.0.13 → 0.0.15

package/dist/loom-react.esm.js

@@ -5759,15 +5759,15 @@ class TwoBitFile {
  */
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 // Cache TwoBitFile instances by URL to reuse parsed headers and indices.
-const readerCache$4 = new Map();
+const readerCache$5 = new Map();
 // Parallel filehandle cache for direct batched reads (bypasses @gmod/twobit).
 const filehandleCache = new Map();
-function getReader$3(url, fetchImpl) {
-    let reader = readerCache$4.get(url);
+function getReader$4(url, fetchImpl) {
+    let reader = readerCache$5.get(url);
     if (!reader) {
         const filehandle = getFilehandle(url, fetchImpl);
         reader = new TwoBitFile({ filehandle });
-        readerCache$4.set(url, reader);
+        readerCache$5.set(url, reader);
     }
     return reader;
 }
@@ -5796,14 +5796,14 @@ function getFilehandle(url, fetchImpl) {
 function createTwoBitSequenceProvider(url, fetchImpl) {
     return async (locus) => {
         var _a;
-        const reader = getReader$3(url, fetchImpl);
+        const reader = getReader$4(url, fetchImpl);
         try {
             const sequence = await reader.getSequence(locus.chr, locus.start, locus.end);
             return sequence !== null && sequence !== void 0 ? sequence : '';
         }
         catch (err) {
             if (err instanceof Error && (err.name === 'AbortError' || ((_a = err.message) === null || _a === void 0 ? void 0 : _a.includes('aborted')))) {
-                readerCache$4.delete(url);
+                readerCache$5.delete(url);
                 filehandleCache.delete(url);
             }
             throw err;
@@ -9703,10 +9703,10 @@ class BgzipIndexedFasta extends IndexedFasta {
  */
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 // Cache reader instances by URL to reuse parsed indices.
-const readerCache$3 = new Map();
-function getReader$2(fastaURL, indexURL, compressedIndexURL, fetchImpl) {
+const readerCache$4 = new Map();
+function getReader$3(fastaURL, indexURL, compressedIndexURL, fetchImpl) {
     const cacheKey = fastaURL;
-    let reader = readerCache$3.get(cacheKey);
+    let reader = readerCache$4.get(cacheKey);
     if (!reader) {
         const fileOpts = fetchImpl ? { fetch: fetchImpl } : undefined;
         if (compressedIndexURL) {
@@ -9722,7 +9722,7 @@ function getReader$2(fastaURL, indexURL, compressedIndexURL, fetchImpl) {
                 fai: new RemoteFile(indexURL, fileOpts),
             });
         }
-        readerCache$3.set(cacheKey, reader);
+        readerCache$4.set(cacheKey, reader);
     }
     return reader;
 }
@@ -9742,14 +9742,14 @@ function createFastaSequenceProvider(fastaURL, indexURL, compressedIndexURL, fet
     const faiURL = indexURL !== null && indexURL !== void 0 ? indexURL : fastaURL + '.fai';
     return async (locus, signal) => {
         var _a;
-        const reader = getReader$2(fastaURL, faiURL, compressedIndexURL, fetchImpl);
+        const reader = getReader$3(fastaURL, faiURL, compressedIndexURL, fetchImpl);
         try {
             const sequence = await reader.getSequence(locus.chr, locus.start, locus.end, { signal });
             return sequence !== null && sequence !== void 0 ? sequence : '';
         }
         catch (err) {
             if (err instanceof Error && (err.name === 'AbortError' || ((_a = err.message) === null || _a === void 0 ? void 0 : _a.includes('aborted')))) {
-                readerCache$3.delete(fastaURL);
+                readerCache$4.delete(fastaURL);
             }
             throw err;
         }
@@ -9877,15 +9877,49 @@ function createGenomeSync(config) {
     return new GenomeImpl(id, config.chromSizes, { name, sequence, cytobands: config.cytobands, nameSet: config.nameSet });
 }
 // ─── Sequence resolution ────��─────────────────────────────────���──────────────
+/**
+ * Wrap a primary SequenceProvider with a fallback.
+ *
+ * On each request, tries `primary` first. If it throws (and the signal was
+ * not aborted), tries `fallback`. If both fail, the primary error is thrown
+ * so the caller sees the error from their configured source.
+ *
+ * The caching layer (createCachedSequence) wraps the combined provider,
+ * so successful fallback results are cached normally — subsequent requests
+ * for the same region won't re-attempt the primary.
+ */
+function createFallbackProvider(primary, fallback) {
+    return async (locus, signal) => {
+        try {
+            return await primary(locus, signal);
+        }
+        catch (primaryErr) {
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                throw primaryErr;
+            console.warn('[loom] Primary sequence source failed, trying fallback:', primaryErr.message);
+            try {
+                return await fallback(locus, signal);
+            }
+            catch (_a) {
+                // Both failed — throw the primary error (more relevant to the user's config)
+                throw primaryErr;
+            }
+        }
+    };
+}
 /**
  * Resolve a sequence provider from config.
  *
  * Exactly one sequence source must be set. Throws if multiple are provided.
  * Sources: sequenceProvider, twoBitURL, fastaURL, ucscGenome.
  * When none is set, falls back to UCSC API via `id` if available.
+ *
+ * When twoBitURL is used and a genome ID is available, the UCSC REST API is
+ * automatically added as a fallback — if the 2-bit server is unreachable,
+ * the API is tried instead.
  */
 function resolveSequenceProvider(config) {
-    var _a;
+    var _a, _b;
     const sources = [
         config.sequenceProvider && 'sequenceProvider',
         config.twoBitURL && 'twoBitURL',
@@ -9900,13 +9934,20 @@ function resolveSequenceProvider(config) {
         return config.sequenceProvider;
     }
     if (config.twoBitURL) {
-        return createCachedSequence(createTwoBitSequenceProvider(config.twoBitURL, config.fetchImpl));
+        const primary = createTwoBitSequenceProvider(config.twoBitURL, config.fetchImpl);
+        // Add UCSC REST API fallback when a genome ID is known
+        const genomeId = (_a = config.ucscGenome) !== null && _a !== void 0 ? _a : config.id;
+        if (genomeId) {
+            const fallback = (locus, signal) => fetchSequence(locus, { genome: genomeId }, signal);
+            return createCachedSequence(createFallbackProvider(primary, fallback));
+        }
+        return createCachedSequence(primary);
     }
     if (config.fastaURL) {
         return createCachedSequence(createFastaSequenceProvider(config.fastaURL, config.indexURL, config.compressedIndexURL, config.fetchImpl));
     }
     // UCSC API — explicit ucscGenome, or implicit via id
-    const ucscGenome = (_a = config.ucscGenome) !== null && _a !== void 0 ? _a : config.id;
+    const ucscGenome = (_b = config.ucscGenome) !== null && _b !== void 0 ? _b : config.id;
     if (ucscGenome) {
         return createCachedSequence((locus, signal) => fetchSequence(locus, { genome: ucscGenome }, signal));
     }
@@ -9914,13 +9955,15 @@ function resolveSequenceProvider(config) {
 }
 // ─── Pre-built singletons ��─────────��─────────────────────────────────────────
 /**
- * Pre-built hg38 genome with UCSC sequence API.
+ * Pre-built hg38 genome with 2-bit sequence (UCSC API fallback).
  *
  * This is the default genome used by HeadlessGenomeBrowser when no genome
- * is specified. Equivalent to igv.js's default behavior of loading hg38.
+ * is specified. Matches igv.js's default behavior: 2-bit file as primary
+ * sequence source, with UCSC REST API as automatic fallback for resilience.
  */
 const hg38Genome = createGenomeSync({
     id: 'hg38',
+    twoBitURL: 'https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.2bit',
     chromSizes: hg38ChromSizes,
 });
 
@@ -10011,6 +10054,12 @@ const binaryFormats = new Set(['bigwig', 'bw', 'bigbed', 'bb', 'biginteract', 'b
 function isBinaryFormat(format) {
     return binaryFormats.has(format.toLowerCase());
 }
+/** BigBed-specific formats (annotation data, not quantitative). */
+const bigBedFormats = new Set(['bigbed', 'bb', 'biginteract', 'biggenepred', 'bignarrowpeak']);
+/** Check if a format string represents a BigBed (annotation) format vs BigWig (quantitative). */
+function isBigBedFormat(format) {
+    return bigBedFormats.has(format.toLowerCase());
+}
 /**
  * Check if a URL is likely tabix-indexed.
  *
@@ -10050,7 +10099,7 @@ function inferIndexURL(url) {
  * Layer 1 (Data): no DOM, no canvas.
  */
 /** Known data source config types. */
-const KNOWN_DS_TYPES = new Set(['bigwig', 'gtx', 'ucsc', 'text', 'memory']);
+const KNOWN_DS_TYPES = new Set(['bigwig', 'bigbed', 'gtx', 'ucsc', 'text', 'memory']);
 /** Check whether a data source config type is one of the known concrete types. */
 function isKnownDataSourceType(type) {
     return KNOWN_DS_TYPES.has(type);
@@ -10084,7 +10133,16 @@ function resolveDataSourceConfig(config) {
         auth.headers = config.headers;
     if (config.withCredentials)
         auth.withCredentials = config.withCredentials;
-    // BigWig / BigBed binary formats
+    // BigBed binary formats (annotation data)
+    if (format && isBigBedFormat(format)) {
+        log.warn(`Unknown data source type "${type}", inferred "bigbed" from URL: ${url}`);
+        return {
+            type: 'bigbed',
+            url,
+            ...auth,
+        };
+    }
+    // BigWig / other binary formats (quantitative data)
     if (format && (format === 'bigwig' || format === 'bw' || isBinaryFormat(format))) {
         log.warn(`Unknown data source type "${type}", inferred "bigwig" from URL: ${url}`);
         return {
@@ -13384,14 +13442,14 @@ class BinaryParser {
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 // Cache BigWig instances by URL to reuse parsed headers and trees.
 // Auth-aware readers share the cache key (URL) — the fetchImpl is bound at creation.
-const readerCache$2 = new Map();
+const readerCache$3 = new Map();
 function getGmodReader(url, fetchImpl) {
     const resolvedUrl = normalizeGoogleURL(url);
-    let reader = readerCache$2.get(resolvedUrl);
+    let reader = readerCache$3.get(resolvedUrl);
     if (!reader) {
         const fileOpts = fetchImpl ? { fetch: fetchImpl } : undefined;
         reader = new BigWig({ filehandle: new RemoteFile(resolvedUrl, fileOpts) });
-        readerCache$2.set(resolvedUrl, reader);
+        readerCache$3.set(resolvedUrl, reader);
     }
     return reader;
 }
@@ -13512,7 +13570,7 @@ async function fetchBigWigFeatures(url, locus, options = {}) {
         // Evict the cached reader so the next fetch gets a fresh one.
         // @gmod/bbi caches the header promise; an aborted parse poisons it permanently.
         if (err instanceof Error && (err.name === 'AbortError' || ((_b = err.message) === null || _b === void 0 ? void 0 : _b.includes('aborted')))) {
-            readerCache$2.delete(url);
+            readerCache$3.delete(url);
         }
         throw err;
     }
@@ -13640,6 +13698,102 @@ class BigWigDataSource {
     }
 }
 
+/**
+ * BigBed data source — fetches BED features from BigBed binary files.
+ *
+ * Uses @gmod/bbi's BigBed class for binary parsing and range queries.
+ * Returns BedFeature[] suitable for annotation track rendering.
+ *
+ * Mirrors igv.js BWSource behavior for bigbed format:
+ * - Features are decoded from BED rest fields via decodeBed()
+ * - No zoom-level summarization (unlike BigWig)
+ * - Feature density estimation from header dataCount
+ *
+ * Layer 1 (Data + Layout): no DOM.
+ */
+// Cache BigBed instances by URL to reuse parsed headers and index trees.
+const readerCache$2 = new Map();
+function getReader$2(url, fetchImpl) {
+    const resolvedUrl = normalizeGoogleURL(url);
+    let reader = readerCache$2.get(resolvedUrl);
+    if (!reader) {
+        const fileOpts = fetchImpl ? { fetch: fetchImpl } : undefined;
+        reader = new BigBed({ filehandle: new RemoteFile(resolvedUrl, fileOpts) });
+        readerCache$2.set(resolvedUrl, reader);
+    }
+    return reader;
+}
+class BigBedDataSource {
+    constructor(url, fetchImpl) {
+        this.url = url;
+        this.fetchImpl = fetchImpl;
+        this.bb = getReader$2(url, fetchImpl);
+    }
+    /** Set a chromosome name resolver for alias resolution (e.g., "1" → "chr1"). */
+    setChromNameResolver(resolver) {
+        this._resolveChromName = resolver;
+    }
+    async fetch(locus, _bpPerPixel, signal) {
+        var _a;
+        const chr = this._resolveChromName
+            ? this._resolveChromName(locus.chr)
+            : locus.chr;
+        try {
+            const rawFeatures = await this.bb.getFeatures(chr, locus.start, locus.end, { signal });
+            const result = [];
+            for (const f of rawFeatures) {
+                const parsed = parseBigBedFeature(chr, f.start, f.end, f.rest);
+                if (parsed)
+                    result.push(parsed);
+            }
+            return result;
+        }
+        catch (err) {
+            // Evict poisoned reader on abort (same pattern as BigWig)
+            if (err instanceof Error && (err.name === 'AbortError' || ((_a = err.message) === null || _a === void 0 ? void 0 : _a.includes('aborted')))) {
+                readerCache$2.delete(normalizeGoogleURL(this.url));
+            }
+            throw err;
+        }
+    }
+    /**
+     * Search for a feature by name via BigBed extra index.
+     * Returns matching features, or empty array if not found or not indexed.
+     */
+    async search(name) {
+        const header = await this.bb.getHeader();
+        const results = await this.bb.searchExtraIndex(name);
+        if (results.length === 0)
+            return [];
+        const refsByNumber = header.refsByNumber;
+        const features = [];
+        for (const r of results) {
+            const chromId = r.chromId;
+            if (chromId == null || !(refsByNumber === null || refsByNumber === void 0 ? void 0 : refsByNumber[chromId]))
+                continue;
+            const chr = refsByNumber[chromId].name;
+            const parsed = parseBigBedFeature(chr, r.start, r.end, r.rest);
+            if (parsed)
+                features.push(parsed);
+        }
+        return features;
+    }
+    dispose() {
+        readerCache$2.delete(normalizeGoogleURL(this.url));
+    }
+}
+/**
+ * Parse a BigBed feature's rest field into a BedFeature.
+ * Reconstructs BED tokens from chr/start/end + tab-delimited rest, then uses decodeBed().
+ */
+function parseBigBedFeature(chr, start, end, rest) {
+    const tokens = [chr, String(start), String(end)];
+    if (rest) {
+        tokens.push(...rest.split('\t'));
+    }
+    return decodeBed(tokens);
+}
+
 /**
  * HTTP range request reader using native fetch.
  * Replaces igvxhr + BufferedReader for BigWig file reading.
@@ -20551,6 +20705,8 @@ function createDataSource(config) {
     switch (config.type) {
         case 'bigwig':
             return new BigWigDataSource(config.url, config.windowFunction);
+        case 'bigbed':
+            return new BigBedDataSource(config.url);
         case 'gtx':
             return new GtxDataSource(config.url, config.experimentId, config.windowFunction);
         case 'ucsc':
@@ -20832,6 +20988,11 @@ registerTypeAlias('broadpeak', 'annotation');
 registerTypeAlias('genepred', 'annotation');
 registerTypeAlias('genepredext', 'annotation');
 registerTypeAlias('refflat', 'annotation');
+// BigBed format → annotation track type aliases
+registerTypeAlias('bigbed', 'annotation');
+registerTypeAlias('bedtype', 'annotation');
+registerTypeAlias('biggenepred', 'annotation');
+registerTypeAlias('bignarrowpeak', 'annotation');
 // Merged/overlay aliases
 registerTypeAlias('overlay', 'merged');
 // Interaction format aliases
@@ -21984,10 +22145,12 @@ function isZoomAware(track) {
  * tracks point to the same URL/region.
  */
 function dataSourceCacheKey(config) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     switch (config.type) {
         case 'bigwig':
             return `bigwig:${config.url}:${(_a = config.windowFunction) !== null && _a !== void 0 ? _a : 'mean'}`;
+        case 'bigbed':
+            return `bigbed:${config.url}`;
         case 'gtx':
             return `gtx:${config.url}:${config.experimentId}`;
         case 'ucsc':
@@ -21995,13 +22158,9 @@ function dataSourceCacheKey(config) {
         case 'text':
             return `text:${config.url}:${(_d = config.format) !== null && _d !== void 0 ? _d : ''}:${(_e = config.indexURL) !== null && _e !== void 0 ? _e : ''}`;
         case 'memory':
-            // Each memory data source is unique — no deduplication.
             return `memory:${Math.random()}`;
-        default: {
-            // Unknown type — resolve via URL inference, then compute key from resolved config
-            const resolved = resolveDataSourceConfig(config);
-            return dataSourceCacheKey(resolved);
-        }
+        default:
+            return `unknown:${config.type}:${(_f = config.url) !== null && _f !== void 0 ? _f : Math.random()}`;
     }
 }
 
@@ -22670,6 +22829,9 @@ function wireDataSource(ds, ctx) {
         if (ds instanceof BigWigDataSource || ds instanceof GtxDataSource) {
             ds.setChromNameResolver(alias => ctx.genome.getChromosomeName(alias));
         }
+        else if (ds instanceof BigBedDataSource) {
+            ds.setChromNameResolver(alias => ctx.genome.getChromosomeName(alias));
+        }
         else if (ds instanceof TextFeatureSource) {
             ds.setChromNameResolver(alias => ctx.genome.getChromosomeName(alias));
             if (ctx.cumulativeOffsets) {
@@ -22857,6 +23019,30 @@ function createBedTrack(ctx, url, options) {
         searchableFields: options === null || options === void 0 ? void 0 : options.searchableFields,
     };
 }
+function createBigBedTrack(ctx, url, options) {
+    var _a;
+    const { canvas } = ctx.canvasProvider.createCanvas(0, 0);
+    const track = new AnnotationTrackCanvas(canvas, {
+        locus: ctx.locus,
+        features: [],
+        config: options === null || options === void 0 ? void 0 : options.config,
+        theme: ctx.theme,
+        canvasProvider: ctx.canvasProvider,
+        name: options === null || options === void 0 ? void 0 : options.name,
+    });
+    const dataSourceConfig = { type: 'bigbed', url, ...options === null || options === void 0 ? void 0 : options.auth };
+    const fetchImpl = resolveTrackFetchImpl(ctx, options);
+    const { dataSource } = getOrCreateDataSource(dataSourceConfig, () => new BigBedDataSource(url, fetchImpl), ctx);
+    return {
+        track,
+        dataSource,
+        dataSourceConfig,
+        maxTrackHeight: options === null || options === void 0 ? void 0 : options.maxTrackHeight,
+        metadata: options === null || options === void 0 ? void 0 : options.metadata,
+        searchable: (_a = options === null || options === void 0 ? void 0 : options.searchable) !== null && _a !== void 0 ? _a : true,
+        searchableFields: options === null || options === void 0 ? void 0 : options.searchableFields,
+    };
+}
 function createInteractionTrack(ctx, url, options) {
     var _a;
     const { canvas } = ctx.canvasProvider.createCanvas(0, 0);
@@ -23206,10 +23392,10 @@ class HeadlessGenomeBrowser {
     }
     // ─── Track lifecycle ─────────────────────────────────────────────────────
     /** Add a track with an optional data source for automatic data management. */
-    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight, order) {
+    addTrack(track, dataSource, dataSourceConfig, maxTrackHeight, order, id) {
         var _a;
         this._snapshotForUndo('track-add');
-        const id = generateTrackId(track.type);
+        id !== null && id !== void 0 ? id : (id = generateTrackId(track.type));
         const mt = {
             id,
             track,
@@ -24086,11 +24272,9 @@ class HeadlessGenomeBrowser {
                 if (!this.dataSourceWorkerProvider && dataSource) {
                     wireDataSource(dataSource, ctx);
                 }
-                this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, (_a = created.dataSourceConfig) !== null && _a !== void 0 ? _a : undefined, undefined, (_b = created.order) !== null && _b !== void 0 ? _b : undefined);
+                this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, (_a = created.dataSourceConfig) !== null && _a !== void 0 ? _a : undefined, undefined, (_b = created.order) !== null && _b !== void 0 ? _b : undefined, trackConfig.id);
                 // Restore bookkeeping fields for round-trip serialization
                 const mt = this.findMT(created.track);
-                if (trackConfig.id)
-                    mt.id = trackConfig.id;
                 if (created.name)
                     mt.name = created.name;
                 if (trackConfig.metadata)
@@ -24176,10 +24360,8 @@ class HeadlessGenomeBrowser {
                 wireDataSource(dataSource, ctx);
             }
         }
-        this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, dataSourceConfig !== null && dataSourceConfig !== void 0 ? dataSourceConfig : undefined, undefined, (_a = created.order) !== null && _a !== void 0 ? _a : undefined);
+        this.addTrack(created.track, dataSource !== null && dataSource !== void 0 ? dataSource : undefined, dataSourceConfig !== null && dataSourceConfig !== void 0 ? dataSourceConfig : undefined, undefined, (_a = created.order) !== null && _a !== void 0 ? _a : undefined, trackConfig.id);
         const mt = this.findMT(created.track);
-        if (trackConfig.id)
-            mt.id = trackConfig.id;
         if (created.name)
             mt.name = created.name;
         if (trackConfig.metadata)
@@ -24238,6 +24420,10 @@ class HeadlessGenomeBrowser {
     addBedTrack(url, options) {
         return this.registerFactory(createBedTrack(this.factoryContext(), url, options));
     }
+    /** Add a BigBed annotation track from a URL. */
+    addBigBedTrack(url, options) {
+        return this.registerFactory(createBigBedTrack(this.factoryContext(), url, options));
+    }
     /** Add an interaction (arc/BEDPE) track from a URL. */
     addInteractionTrack(url, options) {
         return this.registerFactory(createInteractionTrack(this.factoryContext(), url, options));
@@ -28436,23 +28622,26 @@ const LoomBrowser = forwardRef(function LoomBrowser(props, ref) {
             options.genome = genome;
         const b = new GenomeBrowser(container, options);
         browserRef.current = b;
-        // Load session tracks if provided
+        // Load session tracks if provided — a session is a complete state
+        // snapshot, so skip default tracks to avoid duplicates.
         if (session) {
             b.loadSession(session);
         }
+        else {
+            // Convenience default tracks (default: true)
+            if (ruler !== false)
+                b.addRuler();
+            if (genes !== false)
+                b.addGeneTrack();
+            if (sequence !== false)
+                b.addSequenceTrack();
+        }
         // Add config-driven tracks
         if (trackConfigs) {
             for (const tc of trackConfigs) {
                 b.addTrackFromConfig(tc);
             }
         }
-        // Convenience default tracks (default: true)
-        if (ruler !== false)
-            b.addRuler();
-        if (genes !== false)
-            b.addGeneTrack();
-        if (sequence !== false)
-            b.addSequenceTrack();
         // Forward locus changes to onLocusChange / onFrameChange (for controlled mode)
         b.on(BrowserEvent.LocusChange, (event) => {
             var _a, _b;