loom-browser 0.0.1

package/dist/types/decode/bed.d.ts

@@ -0,0 +1,64 @@
+/**
+ * BED format decoders — BED (3-12 columns), narrowPeak, broadPeak, bedGraph, gappedPeak.
+ *
+ * Port of js/feature/decode/ucsc.ts (decodeBed, decodePeak, decodeNarrowPeak,
+ * decodeBedGraph, decodeGappedPeak).
+ *
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { BedFeature, PeakFeature, BedGraphFeature } from '../types';
+/** Header metadata extracted from track lines and column directives. */
+export interface BedHeader {
+    nameField?: string;
+    /** When true, column 4 may contain GFF-style key=value attributes. */
+    gffTags?: boolean;
+    /** Column index for color (from #columns directive). */
+    colorColumn?: number;
+    /** Column index for thickness (from #columns directive). */
+    thicknessColumn?: number;
+}
+/**
+ * Decode a BED format line (3-12 columns) into a BedFeature.
+ *
+ * Port of js/feature/decode/ucsc.ts::decodeBed().
+ * Preserves igv.js patterns:
+ * - Column count gating with maxColumnCount
+ * - GFF-style attribute parsing in col4 when contains `=` and `;`
+ * - Exon block validation (count < 1000, sizes.length === starts.length === count)
+ * - Early return on parse errors (partial feature returned, not rejected)
+ * - Color parsing for col8 (skip "." and "0")
+ */
+export declare function decodeBed(tokens: string[], header?: BedHeader, maxColumnCount?: number): BedFeature | undefined;
+/**
+ * Decode a broadPeak/regionPeak format line (BED6+3: signal, pValue, qValue).
+ *
+ * Port of js/feature/decode/ucsc.ts::decodePeak().
+ */
+export declare function decodeBroadPeak(tokens: string[], header?: BedHeader): PeakFeature | undefined;
+/**
+ * Decode a narrowPeak format line (BED6+4: signal, pValue, qValue, peak).
+ *
+ * Port of js/feature/decode/ucsc.ts::decodeNarrowPeak().
+ */
+export declare function decodeNarrowPeak(tokens: string[], header?: BedHeader): PeakFeature | undefined;
+/**
+ * Decode a gappedPeak format line (BED12+3: signal, pValue, qValue).
+ *
+ * Port of js/feature/decode/ucsc.ts::decodeGappedPeak().
+ */
+export declare function decodeGappedPeak(tokens: string[], header?: BedHeader): PeakFeature | undefined;
+/**
+ * Decode a BedGraph line (chr, start, end, value).
+ *
+ * Port of js/feature/decode/ucsc.ts::decodeBedGraph().
+ */
+export declare function decodeBedGraph(tokens: string[]): BedGraphFeature | undefined;
+/**
+ * Decode a refFlat format line.
+ *
+ * Format: geneName, name, chrom, strand, txStart, txEnd, cdsStart, cdsEnd,
+ *         exonCount, exonStarts, exonEnds
+ *
+ * Port of js/feature/decode/ucsc.ts::decodeReflat().
+ */
+export declare function decodeRefflat(tokens: string[]): BedFeature | undefined;

package/dist/types/decode/bedpe.d.ts

@@ -0,0 +1,36 @@
+/**
+ * BEDPE format decoder — pairwise genomic interactions (Hi-C, ChIA-PET, SVs).
+ *
+ * Standard BEDPE: 10+ columns (chr1/start1/end1/chr2/start2/end2/name/score/strand1/strand2).
+ * Variants: 7-column (score in name column), hiccups (6 standard + extra columns).
+ *
+ * Port of js/feature/decode/bedpe.ts.
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { InteractionFeature } from '../types';
+/** Header metadata for BEDPE files. */
+export interface BedpeHeader {
+    /** Whether this is a hiccups-format file (auto-detected on first feature). */
+    hiccups?: boolean;
+    /** Column names from header line. */
+    columnNames?: string[];
+    /** Column index for per-feature color. */
+    colorColumn?: number;
+    /** Column index for per-feature line thickness. */
+    thicknessColumn?: number;
+}
+/**
+ * Decode a single BEDPE line into an InteractionFeature.
+ *
+ * Handles standard 10-column BEDPE and hiccups variants.
+ * Returns undefined for unparseable lines.
+ */
+export declare function decodeBedpe(tokens: string[], header?: BedpeHeader): InteractionFeature | undefined;
+/**
+ * Post-process BEDPE features:
+ * 1. Auto-detect score in name column (non-standard 7-col variant).
+ * 2. Duplicate inter-chromosome features so each chromosome has a copy.
+ */
+export declare function fixBedPE(features: InteractionFeature[]): void;
+/** Detect hiccups format from column headers. */
+export declare function isHiccups(columns: string[]): boolean;

package/dist/types/decode/exonUtils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared exon and feature utilities used by multiple decoders (BED, genePred, GFF).
+ *
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { Exon } from '../types';
+/**
+ * Mark UTR exons and partial UTR boundaries.
+ *
+ * For non-coding transcripts (cdStart === cdEnd), all exons are marked as UTR.
+ * For coding transcripts, exons entirely outside the CDS are marked as UTR,
+ * and exons overlapping CDS boundaries get cdStart/cdEnd set.
+ *
+ * Port of js/feature/decode/ucsc.ts::findUTRs.
+ */
+export declare function findUTRs(exons: Exon[], cdStart: number, cdEnd: number): void;
+/**
+ * Parse a color value from a BED column (comma-separated RGB or hex) into a CSS color string.
+ *
+ * Accepts:
+ * - "r,g,b" (e.g. "255,0,0" → "rgb(255,0,0)")
+ * - "#RRGGBB" or "#RGB" (returned as-is)
+ * - "." or "0" → returns undefined (no color)
+ *
+ * Port of igv.js IGVColor.createColorString() for the subset used by BED format.
+ */
+export declare function parseColorString(value: string): string | undefined;
+/** Parse a strand character to a typed strand value. */
+export declare function parseStrand(s: string): '+' | '-' | undefined;

package/dist/types/decode/gff.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GFF3/GTF format decoders and transcript assembly.
+ *
+ * Ports:
+ * - js/feature/gff/gff.ts (decodeGFF3, decodeGTF)
+ * - js/feature/gff/parseAttributeString.ts (parseAttributeString, decodeGFFAttribute)
+ * - js/feature/gff/gffHelper.ts (combineFeatures — transcript assembly)
+ * - js/feature/gff/so.ts (sequence ontology type checks)
+ *
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { GFFRecord, GFFFeature } from '../types';
+export declare function isTranscript(type: string): boolean;
+export declare function isTranscriptPart(type: string): boolean;
+export declare function isExon(type: string): boolean;
+export declare function isIntron(type: string): boolean;
+export declare function isCoding(type: string): boolean;
+export declare function isUTR(type: string): boolean;
+/** Decode GFF3 percent-encoded characters. */
+export declare function decodeGFFAttribute(str: string): string;
+/**
+ * Parse GFF/GTF attribute string (column 9) into key-value pairs.
+ *
+ * Returns an array (not a map) because attribute keys are not required to be unique.
+ * GFF3 uses `=` as key-value delimiter, GTF uses space.
+ *
+ * Port of js/feature/gff/parseAttributeString.ts::parseAttributeString().
+ */
+export declare function parseGFFAttributes(attributeString: string, keyValueDelim?: string): Array<[string, string]>;
+/**
+ * Decode a single GFF3 record line.
+ *
+ * Parses column 9 attributes with `=` delimiter, extracts ID, Parent, color.
+ */
+export declare function decodeGFF3(tokens: string[]): GFFRecord | undefined;
+/**
+ * Decode a single GTF record line.
+ *
+ * Parses column 9 attributes with space delimiter, infers ID/Parent from
+ * feature type (gene→gene_id, transcript→transcript_id, exon→transcript_id parent).
+ */
+export declare function decodeGTF(tokens: string[]): GFFRecord | undefined;
+interface AssemblyOptions {
+    /** Custom name field to use for feature names. */
+    nameField?: string;
+    /** Feature types to filter out (default: ['chromosome']). */
+    filterTypes?: string[];
+}
+/**
+ * Assemble flat GFFRecords into hierarchical GFFFeatures (transcripts with exon structure).
+ *
+ * Combines gene→transcript→exon/CDS records by parent/ID relationships.
+ * Handles both GFF3 (explicit ID/Parent) and GTF (inferred from feature type).
+ *
+ * Port of js/feature/gff/gffHelper.ts::combineFeatures().
+ */
+export declare function assembleGFFTranscripts(records: GFFRecord[], format: 'gff3' | 'gtf' | 'gff', options?: AssemblyOptions): GFFFeature[];
+export {};

package/dist/types/decode/interact.d.ts

@@ -0,0 +1,19 @@
+/**
+ * UCSC interact format decoder — 18-column pairwise genomic interactions.
+ *
+ * See https://genome.ucsc.edu/goldenpath/help/interact.html
+ *
+ * Columns: chrom, chromStart, chromEnd, name, score, value, exp, color,
+ *          sourceChrom, sourceStart, sourceEnd, sourceName, sourceStrand,
+ *          targetChrom, targetStart, targetEnd, targetName, targetStrand
+ *
+ * Port of js/feature/decode/interact.ts.
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { InteractionFeature } from '../types';
+/**
+ * Decode a single UCSC interact format line into an InteractionFeature.
+ *
+ * Returns undefined for lines with fewer than 6 columns.
+ */
+export declare function decodeInteract(tokens: string[]): InteractionFeature | undefined;

package/dist/types/decode/ucsc.d.ts

@@ -0,0 +1,56 @@
+/**
+ * UCSC gene prediction format decoders.
+ *
+ * Ported from js/feature/decode/ucsc.ts — handles genePred, genePredExt,
+ * and refGene formats. These are the formats used by UCSC genome browser
+ * for gene annotations (ncbiRefSeq, knownGene, etc.).
+ */
+import type { AnnotationFeature } from '../types';
+/**
+ * Decode a UCSC "genePred" record (basic gene prediction format).
+ *
+ * Column layout (no bin): name, chrom, strand, txStart, txEnd, cdsStart, cdsEnd,
+ *                         exonCount, exonStarts, exonEnds
+ * Column layout (with bin): bin, name, chrom, strand, txStart, txEnd, cdsStart, cdsEnd,
+ *                           exonCount, exonStarts, exonEnds, score, name2
+ *
+ * @param tokens - Tab-split fields from a single line
+ * @param shift  - 1 if the record has a leading `bin` column (refGene), 0 otherwise
+ */
+export declare function decodeGenePred(tokens: string[], shift?: 0 | 1): AnnotationFeature | undefined;
+/**
+ * Decode a UCSC "genePredExt" record. refGene files are in this format.
+ *
+ * Same as genePred but with additional columns:
+ *   ..., score, name2, cdsStartStat, cdsEndStat, exonFrames
+ *
+ * @param tokens - Tab-split fields from a single line
+ * @param shift  - 1 if the record has a leading `bin` column (refGene), 0 otherwise
+ */
+export declare function decodeGenePredExt(tokens: string[], shift?: 0 | 1): AnnotationFeature | undefined;
+/**
+ * Decode a UCSC REST API JSON record into a AnnotationFeature.
+ *
+ * The UCSC API returns JSON objects with the same fields as the text format
+ * but as named properties instead of positional columns.
+ */
+export declare function decodeRefGeneJson(rec: RefGeneRecord): AnnotationFeature;
+/** Shape of a record returned by the UCSC REST API for ncbiRefSeq/refGene tracks. */
+export interface RefGeneRecord {
+    bin?: number;
+    name: string;
+    name2: string;
+    chrom: string;
+    strand: string;
+    txStart: number;
+    txEnd: number;
+    cdsStart: number;
+    cdsEnd: number;
+    exonCount: number;
+    exonStarts: string;
+    exonEnds: string;
+    score?: number;
+    cdsStartStat?: string;
+    cdsEndStat?: string;
+    exonFrames?: string;
+}

package/dist/types/dynseqRenderer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dynamic sequence (dynseq) renderer for wig tracks.
+ *
+ * Renders DNA base letters (A, C, G, T, N) as filled glyphs whose height
+ * is proportional to the wig signal value. Only activates at high zoom
+ * (bpPerPixel < 2) where individual bases are resolvable.
+ *
+ * Ported from js/feature/wigTrack.ts renderDynSeq/drawLetterGlyph/drawSVGPath.
+ */
+/** Default nucleotide color scheme matching igv.js. */
+export declare const defaultNucleotideColors: Readonly<Record<string, string>>;
+/**
+ * Draw a single DNA base letter as a filled glyph.
+ *
+ * @param ctx - Canvas context
+ * @param base - The base character (A, C, G, T, N)
+ * @param x - Left edge pixel position
+ * @param y - Top edge pixel position
+ * @param width - Glyph width in pixels
+ * @param height - Glyph height in pixels
+ * @param color - Fill color
+ * @param flipVertical - Flip the glyph vertically (for negative values)
+ */
+export declare function drawLetterGlyph(ctx: CanvasRenderingContext2D, base: string, x: number, y: number, width: number, height: number, color: string, flipVertical?: boolean): void;
+/**
+ * Render a single wig feature as dynseq (DNA base glyphs scaled by value).
+ *
+ * @param ctx - Canvas context
+ * @param sequence - DNA sequence string for this feature's region
+ * @param x - Left edge pixel position of the feature
+ * @param width - Pixel width of the feature
+ * @param y - Y pixel of the data value
+ * @param y0 - Y pixel of the zero line
+ * @param value - The wig data value (for determining negative/flip)
+ * @param colors - Nucleotide color map
+ */
+export declare function renderDynSeqFeature(ctx: CanvasRenderingContext2D, sequence: string, x: number, width: number, y: number, y0: number, value: number, colors?: Readonly<Record<string, string>>): void;

package/dist/types/events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lightweight typed event emitter.
+ *
+ * Usage:
+ *   type Events = { locuschange: { locus: Locus }; zoom: { factor: number } }
+ *   const emitter = new EventEmitter<Events>()
+ *   const unsub = emitter.on('locuschange', data => console.log(data.locus))
+ *   emitter.emit('locuschange', { locus: { chr: 'chr1', start: 0, end: 1000 } })
+ *   unsub()
+ */
+type Handler<T> = (data: T) => void;
+export declare class EventEmitter<EventMap extends object> {
+    private listeners;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): () => void;
+    /** Unsubscribe a specific handler, or all handlers for an event. */
+    off<K extends keyof EventMap>(event: K, handler?: Handler<EventMap[K]>): void;
+    /** Emit an event to all subscribers. */
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+    /** Remove all listeners for all events. */
+    removeAllListeners(): void;
+}
+export {};

package/dist/types/export/canvas2svg.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Canvas2SVG — A Canvas-to-SVG rendering context.
+ *
+ * Implements the CanvasRenderingContext2D interface but builds an SVG document
+ * instead of rasterizing to pixels. Drop-in replacement for Canvas2D context
+ * in our stateless renderers.
+ *
+ * Port of Canvas 2 SVG v1.0.19 (MIT license, Kerry Liu / Gliffy Inc. 2014)
+ * from js/canvas2svg.ts with full TypeScript typing.
+ *
+ * Layer 1 utility — no DOM attachment, no track logic.
+ */
+/** Configuration for creating a Canvas2SVG context. */
+export interface C2SConfig {
+    width?: number;
+    height?: number;
+    enableMirroring?: boolean;
+    ctx?: CanvasRenderingContext2D;
+    viewbox?: ViewBox;
+    backdropColor?: string;
+}
+interface ViewBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Extra methods provided by Canvas2SVG beyond the standard CanvasRenderingContext2D API. */
+export interface C2SVGExtensions {
+    /** Flag indicating this is an SVG rendering context. */
+    isSVG: boolean;
+    /** Create a clipped, translated group (used for per-track viewport rendering). */
+    saveWithTranslationAndClipRect(id: string, tx: number, ty: number, width: number, height: number, clipYOffset: number): void;
+    /** Update the SVG document height and viewBox. */
+    setHeight(height: number): void;
+    /** Serialize the SVG DOM tree to an XML string. */
+    getSerializedSvg(fixNamedEntities: boolean): string;
+    /** Stroke an ellipse element (SVG native, not path-based). */
+    strokeEllipse(cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle: number, endAngle: number, isCCW?: boolean): void;
+    /** Fill an ellipse element (SVG native, not path-based). */
+    fillEllipse(cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle: number, endAngle: number, isCCW?: boolean): void;
+}
+/** A Canvas2SVG context: implements CanvasRenderingContext2D plus SVG-specific extensions. */
+export type C2SContext = CanvasRenderingContext2D & C2SVGExtensions;
+declare class SVGCanvasGradient {
+    __root: SVGElement;
+    __ctx: C2S;
+    constructor(gradientNode: SVGElement, ctx: C2S);
+    addColorStop(offset: number, color: string): void;
+}
+declare class SVGCanvasPattern {
+    __root: SVGElement;
+    __ctx: C2S;
+    constructor(pattern: SVGElement, ctx: C2S);
+}
+/**
+ * Canvas2SVG rendering context.
+ *
+ * Implements the subset of CanvasRenderingContext2D that our renderers use,
+ * plus SVG-specific extensions (saveWithTranslationAndClipRect, setHeight,
+ * getSerializedSvg, stroke/fillEllipse).
+ *
+ * Usage:
+ *   const ctx = new C2S({ width: 800, height: 600 })
+ *   // ... draw using standard Canvas2D API ...
+ *   const svgString = ctx.getSerializedSvg(true)
+ */
+export declare class C2S {
+    readonly isSVG = true;
+    width: number;
+    height: number;
+    canvas: C2S;
+    private config;
+    private enableMirroring;
+    private viewbox;
+    private __canvas;
+    private __ctx;
+    private __document;
+    __root: SVGElement;
+    private __defs;
+    private __rootGroup;
+    private __currentElement;
+    private __currentElementsToStyle;
+    private __ids;
+    private __stack;
+    private __groupStack;
+    private __currentDefaultPath;
+    private __currentPosition;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    miterLimit: number;
+    lineWidth: number;
+    globalAlpha: number;
+    font: string;
+    shadowColor: string;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowBlur: number;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    lineDash: string | null;
+    private __fontUnderline;
+    private __fontHref;
+    constructor(config?: C2SConfig);
+    setWidth(width: number): void;
+    setHeight(height: number): void;
+    __createElement(elementName: string, properties?: Record<string, string | number>, resetFill?: boolean): SVGElement;
+    private __setDefaultStyles;
+    private __applyStyleState;
+    private __getStyleState;
+    private __applyStyleToCurrentElement;
+    private __closestGroupOrSvg;
+    getSerializedSvg(fixNamedEntities: boolean): string;
+    getSvg(): SVGElement;
+    saveWithTranslationAndClipRect(id: string, tx: number, ty: number, width: number, height: number, clipYOffset: number): void;
+    save(): void;
+    restore(): void;
+    private __addTransform;
+    scale(x: number, y?: number): void;
+    rotate(angle: number): void;
+    translate(x: number, y: number): void;
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    beginPath(): void;
+    private __applyCurrentDefaultPath;
+    private __addPathCommand;
+    moveTo(x: number, y: number): void;
+    closePath(): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | number[]): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    stroke(): void;
+    fill(): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    fillRect(x: number, y: number, width: number, height: number): void;
+    strokeRect(x: number, y: number, width: number, height: number): void;
+    strokeEllipse(cx: number, cy: number, rx: number, ry: number, _rotation: number, _startAngle: number, _endAngle: number, _isCCW?: boolean): void;
+    fillEllipse(cx: number, cy: number, rx: number, ry: number, _rotation: number, _startAngle: number, _endAngle: number, _isCCW?: boolean): void;
+    private __ellipse;
+    private __clearCanvas;
+    clearRect(x: number, y: number, width: number, height: number): void;
+    createLinearGradient(x1: number, y1: number, x2: number, y2: number): SVGCanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): SVGCanvasGradient;
+    private __parseFont;
+    private __wrapTextLink;
+    private __applyText;
+    fillText(text: string, x: number, y: number): void;
+    strokeText(text: string, x: number, y: number): void;
+    measureText(text: string): TextMetrics;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterClockwise?: boolean): void;
+    clip(): void;
+    drawImage(image: CanvasImageSource | C2S, ...args: number[]): void;
+    createPattern(image: HTMLCanvasElement | HTMLImageElement | C2S, _repetition: string | null): SVGCanvasPattern;
+    setLineDash(dashArray: number[]): void;
+    getLineDash(): number[];
+    drawFocusIfNeeded(): void;
+    createImageData(): ImageData;
+    getImageData(): ImageData;
+    putImageData(): void;
+    setTransform(): void;
+    globalCompositeOperation: GlobalCompositeOperation;
+}
+export {};

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

@@ -0,0 +1,2 @@
+export { C2S } from './canvas2svg';
+export type { C2SConfig, C2SContext, C2SVGExtensions } from './canvas2svg';

package/dist/types/featureCache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Feature cache with interval-tree-backed spatial queries.
+ *
+ * Port of igv.js `js/feature/featureCache.ts`. Features are grouped by
+ * chromosome, sorted, chunked, and indexed via IntervalTree for O(log n + k)
+ * range queries.
+ *
+ * Layer 1 (Data + Layout) — pure data structure, no DOM, no canvas.
+ */
+import { IntervalTree } from './intervalTree';
+/** Minimal interface for features stored in the cache. */
+export interface CacheableFeature {
+    chr: string;
+    start: number;
+    end: number;
+}
+/**
+ * Range metadata describing what genomic region is fully cached.
+ * When present, `containsRange()` delegates to this; when absent,
+ * the cache is assumed to contain all features (e.g., whole-file load).
+ */
+export interface CacheRange {
+    contains(chr: string, start: number, end: number): boolean;
+}
+/** Index range pointing into the sorted allFeatures[chr] array. */
+interface IndexRange {
+    start: number;
+    end: number;
+}
+/**
+ * Spatial feature cache backed by per-chromosome interval trees.
+ *
+ * Features are chunked (max(10, len/10) per chunk) to reduce tree size
+ * while maintaining fast overlap queries. Matches igv.js FeatureCache.
+ *
+ * @typeParam F - Feature type, must have chr/start/end at minimum.
+ */
+export declare class FeatureCache<F extends CacheableFeature> {
+    /** Per-chromosome interval trees indexing feature chunks. */
+    readonly treeMap: Record<string, IntervalTree<IndexRange>>;
+    /** Optional range metadata for partial-cache validation. */
+    readonly range: CacheRange | undefined;
+    /** Total number of cached features across all chromosomes. */
+    readonly count: number;
+    /** All features grouped by chromosome, sorted by start. */
+    readonly allFeatures: Record<string, F[]>;
+    constructor(featureList?: F[], range?: CacheRange);
+    /**
+     * Check if the cache covers a genomic range.
+     * Returns true when no range metadata is set (cache assumed complete)
+     * or when the range metadata confirms coverage.
+     */
+    containsRange(chr: string, start: number, end: number): boolean;
+    /**
+     * Query features overlapping [start, end] on the given chromosome.
+     * Returns features sorted by start position. O(log n + k) via interval tree.
+     */
+    queryFeatures(chr: string, start: number, end: number): F[];
+    /**
+     * Search all cached features matching a predicate.
+     * Scans every feature across all chromosomes — O(n).
+     */
+    findFeatures(fn: (f: F) => boolean): F[];
+    /**
+     * Returns all features grouped by chromosome.
+     */
+    getAllFeatures(): Record<string, F[]>;
+}
+export {};

package/dist/types/formats/featureParser.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Feature parser — lines → typed features.
+ *
+ * Dispatches to format-specific decoders based on format string. Handles
+ * header parsing, comment skipping, delimiter selection, and GFF assembly.
+ *
+ * Port of js/feature/featureParser.ts.
+ *
+ * Layer 1 (Data + Layout): pure functions, no I/O, no DOM.
+ */
+import type { BedFeature, PeakFeature, BedGraphFeature, GFFRecord, GFFFeature, InteractionFeature, TextFileFormat } from '../types';
+/** Decoder function type — takes tokens from a split line, returns a feature or undefined. */
+export type DecoderFunction = (tokens: string[], header?: Record<string, unknown>) => unknown | undefined;
+/** Header metadata extracted from track lines, column directives, and format directives. */
+export interface FeatureHeader {
+    format?: string;
+    nameField?: string;
+    gffTags?: boolean;
+    columnNames?: string[];
+    colorColumn?: number;
+    thicknessColumn?: number;
+    /** Properties parsed from track lines. */
+    properties?: Record<string, string>;
+    /** Wig step/span directive state (for fixedStep/variableStep). */
+    wig?: WigDirective;
+    /** Column shift (1 for refgene/ensgene formats). */
+    shift?: number;
+}
+interface WigDirective {
+    format: string;
+    chrom: string;
+    start?: number;
+    step?: number;
+    span: number;
+    index?: number;
+}
+interface DecoderInfo {
+    decode: (tokens: string[], header: FeatureHeader) => unknown | undefined;
+    delimiter: string | RegExp;
+    /** Whether parsed features need GFF transcript assembly. */
+    requiresAssembly: boolean;
+    /** Optional post-processing of all decoded features (e.g., BEDPE fixup). */
+    postProcess?: (features: any[]) => void;
+}
+/**
+ * Get the appropriate decoder function and delimiter for a format string.
+ *
+ * Port of js/feature/featureParser.ts::setDecoder().
+ */
+export declare function getDecoder(format: TextFileFormat, _header?: FeatureHeader): DecoderInfo;
+/**
+ * Parse header information from text lines.
+ *
+ * Extracts track line properties, column names, format directives
+ * (#gffTags, ##gff-version 3, etc.).
+ *
+ * Port of js/feature/featureParser.ts::parseHeader().
+ */
+export declare function parseHeader(lines: string[], format: TextFileFormat): FeatureHeader;
+/**
+ * Parse text lines into features for a given format.
+ *
+ * Handles: comment/header skipping, delimiter-based tokenization,
+ * WIG directive parsing, GFF transcript assembly.
+ *
+ * Port of js/feature/featureParser.ts::parseFeatures().
+ */
+export declare function parseFeatures(lines: string[], format: TextFileFormat, options?: {
+    header?: FeatureHeader;
+    assembleGFF?: boolean;
+}): Array<BedFeature | PeakFeature | BedGraphFeature | GFFFeature | GFFRecord | InteractionFeature>;
+export {};