loom-browser 0.0.1

package/dist/types/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { StateProjection } from './stateProjection';
+export type { ZoomLevel, TrackSummary, ProjectedState, StateDiff, TrackChangeDiff, GetStateOptions, } from './stateProjection';
+export { matchesSelector, selectTracks } from './trackSelector';
+export type { TrackSelector } from './trackSelector';

package/dist/types/agent/stateProjection.d.ts

@@ -0,0 +1,115 @@
+/**
+ * StateProjection — agent-friendly state snapshots with record/diff support.
+ *
+ * Wraps a HeadlessGenomeBrowser to produce concise, LLM-optimized state objects.
+ * Supports snapshotting (record) and incremental diffs against prior snapshots.
+ *
+ * Feature summarization reads from the browser's cache via getCachedFeatures(),
+ * filters to the visible viewport, and applies type-specific summarization.
+ *
+ * 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';
+/** 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. */
+export interface TrackSummary {
+    id: string;
+    type: string;
+    name?: string;
+    metadata?: Record<string, string>;
+    /** True when a data source exists but no cached data is available yet. */
+    loading?: boolean;
+    featureSummary?: TrackFeatureSummary;
+}
+/** Full projected state of the browser — concise, JSON-serializable. */
+export interface ProjectedState {
+    locus: Locus;
+    /** Formatted locus string, e.g. "chr17:7,668,421-7,687,490" */
+    locusString: string;
+    /** Viewport span in base pairs. */
+    span: number;
+    zoomLevel: ZoomLevel;
+    genome?: string;
+    tracks: TrackSummary[];
+    rois: ROISetConfig[];
+}
+/** Per-field [before, after] diff for a track whose feature summary changed. */
+export interface TrackChangeDiff {
+    id: string;
+    type: string;
+    featureCount?: [number, number];
+    signalRange?: [{
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }];
+    featureNames?: [string[], string[]];
+    packingDepth?: [number, number];
+    valueRange?: [{
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }];
+}
+/** Diff between two projected states — only includes what changed. */
+export interface StateDiff {
+    /** Present if locus changed. */
+    locus?: [Locus, Locus];
+    /** Present if zoom level changed. */
+    zoomLevel?: [ZoomLevel, ZoomLevel];
+    /** Tracks added since the snapshot. */
+    tracksAdded?: TrackSummary[];
+    /** Track IDs removed since the snapshot. */
+    tracksRemoved?: string[];
+    /** Tracks whose feature summary changed, with per-field [before, after] tuples. */
+    tracksChanged?: TrackChangeDiff[];
+    /** Present if ROIs changed. */
+    roisChanged?: boolean;
+    /** True if nothing changed. */
+    unchanged: boolean;
+}
+export interface GetStateOptions {
+    /** If provided, record the state under this key for future diff() calls. */
+    record?: string;
+}
+export declare class StateProjection {
+    private browser;
+    private snapshots;
+    constructor(browser: HeadlessGenomeBrowser);
+    /** Get the current projected state. Optionally record it under a key. */
+    getState(options?: GetStateOptions): ProjectedState;
+    /**
+     * Diff the current state against a named snapshot.
+     * Returns an object describing only what changed.
+     * Throws if the key doesn't exist.
+     */
+    diff(key: string): StateDiff;
+    /** Record the current state under a key without returning it. */
+    record(key: string): void;
+    /** Delete a snapshot by key. */
+    deleteSnapshot(key: string): boolean;
+    /** Get a previously recorded snapshot by key. */
+    getSnapshot(key: string): ProjectedState | undefined;
+    /** List all snapshot keys. */
+    snapshotKeys(): string[];
+    /** Clear all snapshots. */
+    clearSnapshots(): void;
+    private project;
+    private projectTrack;
+    /**
+     * Summarize cached features for a track, filtered to the visible viewport.
+     * Reads from the browser's cache via getCachedFeatures() and applies
+     * type-specific summarization. Override this method in subclasses for
+     * custom summary formats.
+     */
+    protected summarizeFeatures(mt: ManagedTrack, locus: Locus): TrackFeatureSummary | undefined;
+    private summarizeWig;
+    private summarizeAnnotation;
+    private summarizeInteraction;
+}

package/dist/types/agent/trackSelector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TrackSelector — SQL-ish WHERE clause for matching tracks by metadata.
+ *
+ * Selectors support matching on track ID, name (string or RegExp), type,
+ * and arbitrary metadata key-value pairs. All provided fields use AND semantics:
+ * a track must match every specified criterion.
+ *
+ * ```ts
+ * // Remove all ATAC-seq tracks
+ * browser.removeTracks({ where: { assay: 'ATAC-seq' } })
+ *
+ * // Find wig tracks from K562
+ * browser.findTracks({ type: 'wig', where: { biosample: 'K562' } })
+ * ```
+ */
+import type { ManagedTrack } from '../headlessGenomeBrowser';
+/** Selector for matching tracks by ID, name, type, and/or metadata. */
+export interface TrackSelector {
+    /** Exact match against track ID. */
+    id?: string;
+    /** String: case-insensitive substring match. RegExp: test against track name. */
+    name?: string | RegExp;
+    /** Exact match against track type (e.g. 'wig', 'annotation', 'interact'). */
+    type?: string;
+    /** Metadata key-value matching. Every entry must match (AND semantics). */
+    where?: Record<string, string>;
+}
+/** Test whether a single managed track matches all criteria in a selector. */
+export declare function matchesSelector(mt: ManagedTrack, selector: TrackSelector): boolean;
+/** Select all managed tracks matching a selector. */
+export declare function selectTracks(tracks: readonly ManagedTrack[], selector: TrackSelector): ManagedTrack[];

package/dist/types/baseTrackCanvas.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Base class for canvas-based genomic track renderers.
+ *
+ * Handles all shared canvas lifecycle: DPR scaling, sizing, resize observation,
+ * attach/detach, background fill, and RenderContext construction.
+ *
+ * Subclasses implement:
+ *   - type (track type identifier)
+ *   - computeHeight(width) — return CSS pixel height for current state
+ *   - getBackground() — return background fill color
+ *   - doRender(ctx, width, height, rc) — the actual drawing logic
+ *
+ * This eliminates ~80 lines of identical boilerplate per track type.
+ */
+import type { Locus, RenderContext, Track, TrackSessionConfig } from './types';
+import type { RenderTheme } from './renderTheme';
+import type { CanvasProvider } from './canvasProvider';
+export declare abstract class BaseTrackCanvas<TConfig> implements Track {
+    protected _canvas: HTMLCanvasElement;
+    protected _locus: Locus;
+    protected _config: TConfig;
+    protected _height: number;
+    protected canvasProvider: CanvasProvider;
+    private resizeObserver;
+    private container;
+    abstract readonly type: string;
+    get canvas(): HTMLCanvasElement;
+    get locus(): Locus;
+    get height(): number;
+    /** Current track config (read-only). Use setConfig() to update. */
+    get config(): TConfig;
+    constructor(canvas: HTMLCanvasElement, locus: Locus, config: TConfig, canvasProvider?: CanvasProvider);
+    /** Update locus and re-render. */
+    setLocus(locus: Locus): void;
+    /** Merge partial config and re-render. */
+    setConfig(config: Partial<TConfig>): void;
+    /**
+     * Attach the canvas to a container element.
+     * Appends the canvas and sets up a ResizeObserver for automatic re-renders.
+     */
+    attachTo(container: HTMLElement): void;
+    /** Detach from container and stop observing resizes. */
+    detach(): void;
+    /** Render the track. Handles DPR, sizing, background, then delegates to doRender(). */
+    render(): void;
+    /**
+     * Compute the track height in CSS pixels for the current state.
+     * Called at the start of each render(). The width parameter is provided
+     * in case height depends on layout (e.g., gene packing).
+     */
+    protected abstract computeHeight(width: number): number;
+    /** Return the background fill color for the canvas. */
+    protected abstract getBackground(): string;
+    /** Perform the actual track-specific rendering onto the prepared canvas. */
+    protected abstract doRender(ctx: CanvasRenderingContext2D, width: number, height: number, rc: RenderContext): void;
+    /**
+     * Serialize this track's config for session save/restore.
+     * Each subclass diffs its config against theme defaults and returns
+     * a typed TrackSessionConfig with only overridden fields.
+     */
+    abstract serializeConfig(theme: RenderTheme): TrackSessionConfig;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Binary data parser for reading structured binary data from a DataView.
+ * Port of js/binary.ts, simplified for BigWig reading (no VPointer).
+ */
+export declare class BinaryParser {
+    littleEndian: boolean;
+    position: number;
+    readonly view: DataView;
+    readonly length: number;
+    constructor(dataView: DataView, littleEndian?: boolean);
+    setPosition(position: number): void;
+    available(): number;
+    remLength(): number;
+    getByte(): number;
+    getShort(): number;
+    getUShort(): number;
+    getInt(): number;
+    getUInt(): number;
+    getLong(): number;
+    getString(len?: number): string;
+    getFixedLengthString(len: number): string;
+    getFloat(): number;
+    getDouble(): number;
+    skip(n: number): number;
+}

package/dist/types/bigwig/bpTree.d.ts

@@ -0,0 +1,40 @@
+/**
+ * B+ tree implementation for BigWig/BigBed chromosome name lookup.
+ * Port of js/bigwig/bpTree.ts, simplified:
+ * - Only supports 'BPChromTree' type (for chromosome ID lookup)
+ * - Uses native fetch via rangeReader
+ * - Strict types, no `any`
+ */
+export interface ChromLeafValue {
+    id: number;
+    size: number;
+}
+interface LeafItem {
+    key: string;
+    value: ChromLeafValue;
+}
+interface NonLeafItem {
+    key: string;
+    offset: number;
+}
+type BPTreeItem = LeafItem | NonLeafItem;
+interface BPTreeNode {
+    type: number;
+    count: number;
+    items: BPTreeItem[];
+}
+export declare class BPTree {
+    private littleEndian;
+    private readonly nodeCache;
+    private readonly url;
+    private header;
+    private readonly startOffset;
+    constructor(url: string, startOffset: number);
+    init(signal?: AbortSignal): Promise<void>;
+    getItemCount(): number;
+    search(term: string, signal?: AbortSignal): Promise<ChromLeafValue | undefined>;
+    private walkTreeNode;
+    readTreeNode(offset: number, signal?: AbortSignal): Promise<BPTreeNode>;
+    private getParserFor;
+}
+export {};

package/dist/types/bigwig/bwReader.d.ts

@@ -0,0 +1,69 @@
+/**
+ * BigWig file reader.
+ * Port of js/bigwig/bwReader.ts, simplified for BigWig only (no BigBed).
+ *
+ * Reads a BigWig file via HTTP range requests, parses the binary header,
+ * zoom level headers, total summary, chromosome tree, and data sections.
+ */
+import type { WigFeature, WindowFunction } from '../types';
+import type { WorkerProvider } from '../workerProvider';
+export interface BigWigHeader {
+    bwVersion: number;
+    nZoomLevels: number;
+    chromTreeOffset: number;
+    fullDataOffset: number;
+    fullIndexOffset: number;
+    fieldCount: number;
+    definedFieldCount: number;
+    autoSqlOffset: number;
+    totalSummaryOffset: number;
+    uncompressBuffSize: number;
+    extensionOffset: number;
+}
+export interface BigWigTotalSummary {
+    basesCovered: number;
+    minVal: number;
+    maxVal: number;
+    sumData: number;
+    sumSquares: number;
+    mean: number;
+    stddev: number;
+}
+export declare class BigWigReader {
+    private readonly url;
+    private littleEndian;
+    private header;
+    private chromTree;
+    private zoomLevelHeaders;
+    private totalSummary;
+    private readonly rpTreeCache;
+    /** Optional worker provider for offloading CPU-intensive decode work. */
+    private readonly workerProvider?;
+    constructor(url: string, workerProvider?: WorkerProvider);
+    /** Load and parse the BigWig header. Idempotent. */
+    loadHeader(signal?: AbortSignal): Promise<BigWigHeader>;
+    /** Get the total summary statistics (if available). */
+    getTotalSummary(): Promise<BigWigTotalSummary | undefined>;
+    /**
+     * Read BigWig features for a genomic range.
+     *
+     * @param chr - Chromosome name (e.g., 'chr17')
+     * @param bpStart - Start position (0-based)
+     * @param bpEnd - End position
+     * @param bpPerPixel - Resolution (used to select zoom level)
+     * @param windowFunction - Aggregation function for zoom data ('mean', 'min', 'max')
+     */
+    readFeatures(chr: string, bpStart: number, bpEnd: number, bpPerPixel?: number, windowFunction?: WindowFunction, signal?: AbortSignal): Promise<WigFeature[]>;
+    /**
+     * Read features across all main chromosomes for whole genome view.
+     * Resolves chromosome IDs, finds min/max range, and does a cross-chromosome R-tree query.
+     * Port of js/bigwig/bwReader.ts readWGFeatures().
+     */
+    readWGFeatures(chromNames: string[], bpPerPixel: number, windowFunction?: WindowFunction, signal?: AbortSignal): Promise<WigFeature[]>;
+    /**
+     * Internal: read features for a range that may span multiple chromosomes.
+     */
+    private readFeaturesRange;
+    private zoomLevelForScale;
+    private loadRPTree;
+}

package/dist/types/bigwig/chromTree.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Chromosome name ↔ ID mapping backed by a B+ tree.
+ * Port of js/bigwig/chromTree.ts.
+ */
+export declare class ChromTree {
+    private readonly nameToId;
+    private readonly idToName;
+    private readonly bpTree;
+    private readonly startOffset;
+    constructor(url: string, startOffset: number);
+    init(signal?: AbortSignal): Promise<void>;
+    getItemCount(): number;
+    /** Return the chromosome ID for the given name, or undefined if not found. */
+    getIdForName(chr: string, signal?: AbortSignal): Promise<number | undefined>;
+    /** Return all cached chromosome ID → name mappings. */
+    getAllNames(): Map<number, string>;
+    /**
+     * Pre-resolve a list of chromosome names to IDs, populating the cache.
+     * Returns a map of name → ID for successfully resolved chromosomes.
+     */
+    resolveAll(names: string[], signal?: AbortSignal): Promise<Map<string, number>>;
+    /**
+     * Return the chromosome name for the given ID.
+     * Potentially expensive — walks the tree until the matching leaf is found.
+     */
+    getNameForId(id: number, signal?: AbortSignal): Promise<string | undefined>;
+    private reverseSearch;
+}

package/dist/types/bigwig/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * BigWig reader — public API.
+ *
+ * Thin wrapper around @gmod/bbi that preserves the existing public API.
+ * All binary parsing, decompression, and zoom level selection is handled
+ * by @gmod/bbi internally.
+ */
+import type { WigFeature, WindowFunction, Locus } from '../types';
+import type { WorkerProvider } from '../workerProvider';
+export { BinaryParser } from '../io/binaryParser';
+export interface FetchBigWigOptions {
+    /** Resolution in base pairs per pixel. Used to select an appropriate zoom level. */
+    bpPerPixel?: number;
+    /** Aggregation function for zoom-level data. Default: 'mean'. */
+    windowFunction?: WindowFunction;
+    /** @deprecated Worker dispatch is handled internally by @gmod/bbi. */
+    workerProvider?: WorkerProvider;
+    /** AbortSignal for cancelling in-flight HTTP requests. */
+    signal?: AbortSignal;
+}
+/** Header metadata from a BigWig file. */
+export interface BigWigHeader {
+    bwVersion: number;
+    nZoomLevels: number;
+    chromTreeOffset: number;
+    fullDataOffset: number;
+    fullIndexOffset: number;
+    fieldCount: number;
+    definedFieldCount: number;
+    autoSqlOffset: number;
+    totalSummaryOffset: number;
+    uncompressBuffSize: number;
+    extensionOffset: number;
+}
+/** Summary statistics for the entire BigWig file. */
+export interface BigWigTotalSummary {
+    basesCovered: number;
+    minVal: number;
+    maxVal: number;
+    sumData: number;
+    sumSquares: number;
+    mean: number;
+    stddev: number;
+}
+/**
+ * Thin wrapper around @gmod/bbi BigWig that preserves the legacy API.
+ */
+export declare class BigWigReader {
+    private readonly bw;
+    constructor(url: string, _workerProvider?: WorkerProvider);
+    loadHeader(signal?: AbortSignal): Promise<BigWigHeader>;
+    getTotalSummary(signal?: AbortSignal): Promise<BigWigTotalSummary | undefined>;
+    readFeatures(chr: string, bpStart: number, bpEnd: number, bpPerPixel?: number, windowFunction?: WindowFunction, signal?: AbortSignal): Promise<WigFeature[]>;
+    readWGFeatures(chromNames: string[], bpPerPixel: number, windowFunction?: WindowFunction, signal?: AbortSignal): Promise<WigFeature[]>;
+}
+/**
+ * Fetch BigWig features for a genomic locus.
+ */
+export declare function fetchBigWigFeatures(url: string, locus: Locus, options?: FetchBigWigOptions): Promise<WigFeature[]>;
+/**
+ * Fetch BigWig features across all specified chromosomes for whole genome view.
+ * Returns features with per-chromosome coordinates (caller transforms to genome-wide).
+ */
+export declare function fetchBigWigWGFeatures(url: string, chromNames: string[], bpPerPixel: number, options?: Pick<FetchBigWigOptions, 'windowFunction' | 'workerProvider' | 'signal'>): Promise<WigFeature[]>;
+/** Clear the BigWig reader cache (useful for testing or memory management). */
+export declare function clearBigWigCache(): void;

package/dist/types/bigwig/inflate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Zlib inflate (decompress) utility.
+ *
+ * Uses the Web Streams API DecompressionStream when available (all modern
+ * browsers), with a manual raw-deflate fallback for environments that only
+ * support 'deflate' format (the BigWig format stores raw deflate data without
+ * a zlib header, but some implementations add the header).
+ */
+export declare function inflate(compressedData: Uint8Array): Promise<Uint8Array>;

package/dist/types/bigwig/rangeReader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HTTP range request reader using native fetch.
+ * Replaces igvxhr + BufferedReader for BigWig file reading.
+ *
+ * Handles cross-origin 307/302 redirects that strip the Range header.
+ * When a redirect causes the server to return 200 (full content) instead of
+ * 206 (partial), we either retry against the final URL or slice the correct
+ * bytes from the full response — matching igvxhr behavior.
+ */
+export interface ByteRange {
+    start: number;
+    size: number;
+}
+/**
+ * Fetch a byte range from a URL as an ArrayBuffer.
+ *
+ * Handles two redirect failure modes:
+ * 1. Cross-origin redirect strips Range header → server returns 200 (full file).
+ *    We retry directly against response.url (the final URL post-redirect).
+ * 2. If retry still returns 200, we slice the requested bytes from the full
+ *    response (matching igvxhr's fallback behavior).
+ *
+ * On HTTP 416 (Range Not Satisfiable), fetches the actual file size via HEAD
+ * and retries once with a clamped range.
+ */
+export declare function fetchRange(url: string, range: ByteRange, signal?: AbortSignal): Promise<ArrayBuffer>;
+/**
+ * Fetch the Content-Length of a URL via a HEAD request.
+ * If redirected and Content-Length is missing, retries against the final URL.
+ */
+export declare function getContentLength(url: string, signal?: AbortSignal): Promise<number>;
+/**
+ * Buffered reader that caches fetched data to minimize HTTP requests.
+ * When a requested range is within the cached buffer, no fetch is needed.
+ *
+ * On HTTP 416, recovers by fetching the file's Content-Length and retrying,
+ * matching js/bigwig/bufferedReader.ts behavior.
+ */
+export declare class BufferedRangeReader {
+    private readonly url;
+    private readonly bufferSize;
+    private cachedRange;
+    private cachedData;
+    private contentLength;
+    constructor(url: string, bufferSize?: number);
+    dataViewForRange(requestedRange: ByteRange, signal?: AbortSignal, retries?: number): Promise<DataView>;
+    loadArrayBuffer(range: ByteRange, signal?: AbortSignal): Promise<ArrayBuffer>;
+}

package/dist/types/bigwig/rpTree.d.ts

@@ -0,0 +1,27 @@
+/**
+ * R-tree implementation for BigWig spatial range queries.
+ * Port of js/bigwig/rpTree.ts.
+ */
+export interface RPTreeLeafItem {
+    isLeaf: boolean;
+    startChrom: number;
+    startBase: number;
+    endChrom: number;
+    endBase: number;
+    childOffset: number;
+    dataSize: number;
+    dataOffset: number;
+}
+export declare class RPTree {
+    private littleEndian;
+    private readonly nodeCache;
+    private readonly url;
+    private readonly startOffset;
+    private header;
+    constructor(url: string, startOffset: number);
+    init(signal?: AbortSignal): Promise<void>;
+    /** Find all leaf items that overlap the given genomic range. */
+    findLeafItemsOverlapping(chrIdx1: number, startBase: number, chrIdx2: number, endBase: number, signal?: AbortSignal): Promise<RPTreeLeafItem[]>;
+    private readNode;
+    private getParserFor;
+}

package/dist/types/canvasProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CanvasProvider — environment abstraction for canvas creation and DPR.
+ *
+ * Decouples track rendering from browser globals (document, window).
+ * DOMCanvasProvider is the default for browser environments.
+ * Future: NodeCanvasProvider (wrapping node-canvas) for server-side rendering,
+ * MockCanvasProvider for tests.
+ *
+ * Reference: ai_docs/modernization/headless-v2.md (Phase 1)
+ */
+/** A canvas and its 2D rendering context, returned by CanvasProvider.createCanvas(). */
+export interface CanvasAndContext {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+}
+/**
+ * Abstraction over canvas creation and device pixel ratio.
+ *
+ * Implementations:
+ *   - DOMCanvasProvider — browser (default)
+ *   - Future: NodeCanvasProvider — server-side (wraps node-canvas)
+ *   - Future: MockCanvasProvider — tests
+ */
+export interface CanvasProvider {
+    /** Create a canvas element with the given logical (CSS) dimensions. */
+    createCanvas(width: number, height: number): CanvasAndContext;
+    /** Device pixel ratio for sharp rendering on high-DPI displays. */
+    readonly devicePixelRatio: number;
+}
+/** Browser-based CanvasProvider using DOM APIs. */
+export declare class DOMCanvasProvider implements CanvasProvider {
+    createCanvas(width: number, height: number): CanvasAndContext;
+    get devicePixelRatio(): number;
+}
+/** Default CanvasProvider for browser environments. */
+export declare const defaultCanvasProvider: CanvasProvider;