loom-browser 0.0.1

package/dist/types/src/ui/components/LoomBrowserShell.d.ts

@@ -0,0 +1,52 @@
+/**
+ * <loom-browser> — Top-level shell combining navbar + GenomeBrowser.
+ *
+ * Usage:
+ *   const shell = document.createElement('loom-browser')
+ *   shell.setAttribute('theme', 'modern')
+ *   container.appendChild(shell)
+ *   shell.initialize({ locus: { chr: 'chr17', start: 7668000, end: 7688000 } })
+ *   shell.addTrack(rulerTrack)
+ *   shell.addTrack(geneTrack)
+ *
+ * Or use the createShell() helper:
+ *   const shell = createShell(container, { locus, theme: 'modern' })
+ */
+import { GenomeBrowser } from '../../genomeBrowser';
+import type { GenomeBrowserOptions, BrowserEvents } from '../../genomeBrowser';
+import type { Locus, Track } from '../../types';
+import type { ShellTheme } from '../themes';
+export declare class LoomBrowserShell extends HTMLElement {
+    private navbar;
+    private trackContainer;
+    private themeStyle;
+    private _browser;
+    static get observedAttributes(): string[];
+    constructor();
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    private applyTheme;
+    connectedCallback(): void;
+    /** Initialize the GenomeBrowser inside this shell. */
+    initialize(options: GenomeBrowserOptions): GenomeBrowser;
+    /** Get the underlying GenomeBrowser instance. */
+    get browser(): GenomeBrowser | null;
+    /** Proxy: add a track to the browser. */
+    addTrack(track: Track): void;
+    /** Proxy: remove a track from the browser. */
+    removeTrack(track: Track): void;
+    /** Proxy: set the locus. */
+    setLocus(locus: Locus): void;
+    /** Proxy: subscribe to browser events. */
+    on<K extends keyof BrowserEvents>(event: K, handler: (data: BrowserEvents[K]) => void): (() => void) | undefined;
+    disconnectedCallback(): void;
+}
+/** Options for createShell(). */
+export interface CreateShellOptions extends GenomeBrowserOptions {
+    /** UI shell theme (CSS chrome). Separate from GenomeBrowserOptions.theme (render palette). */
+    shellTheme?: ShellTheme;
+}
+/**
+ * Convenience function to create an <loom-browser> shell and initialize it.
+ * Returns the shell element (with .browser for the underlying GenomeBrowser).
+ */
+export declare function createShell(container: HTMLElement, options: CreateShellOptions): LoomBrowserShell;

package/dist/types/src/ui/components/LoomChromosomeSelect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * <loom-chromosome-select> — Chromosome dropdown for quick navigation.
+ *
+ * Lists main chromosomes (chr1-22, X, Y, M) plus "All" for whole genome view.
+ * Updates automatically when the browser locus changes.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomChromosomeSelect extends HTMLElement {
+    private select;
+    private unsubscribe;
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+    private populate;
+    private updateSelection;
+    disconnectedCallback(): void;
+}

package/dist/types/src/ui/components/LoomContextMenu.d.ts

@@ -0,0 +1,39 @@
+/**
+ * <loom-context-menu> — Right-click context menu Web Component.
+ *
+ * Renders ContextMenuItem[] as a styled menu with action items, checkboxes,
+ * separators, and one level of submenu nesting.
+ *
+ * Also exports DefaultContextMenuProvider which wraps this component and
+ * implements the ContextMenuProvider interface.
+ *
+ * Customizable via CSS custom properties:
+ *   --loom-menu-bg, --loom-menu-border, --loom-menu-radius, --loom-menu-shadow,
+ *   --loom-menu-font, --loom-menu-color, --loom-menu-hover, --loom-menu-divider
+ */
+import type { ContextMenuItem } from '../../types';
+import type { ContextMenuProvider } from '../../contextMenuProvider';
+export declare class LoomContextMenu extends HTMLElement {
+    private menuDiv;
+    constructor();
+    connectedCallback(): void;
+    /** Populate the menu from typed ContextMenuItem data. */
+    setItems(items: ContextMenuItem[]): void;
+    private buildItems;
+    /** Position and show the menu, clamping to container bounds. */
+    showAt(x: number, y: number): void;
+    hide(): void;
+}
+/**
+ * Default ContextMenuProvider using the <loom-context-menu> Web Component.
+ * Lazily creates the element on first show() call (same pattern as DefaultPopupProvider).
+ */
+export declare class DefaultContextMenuProvider implements ContextMenuProvider {
+    private element;
+    show(items: ContextMenuItem[], position: {
+        x: number;
+        y: number;
+    }, container: HTMLElement): void;
+    hide(): void;
+    dispose(): void;
+}

package/dist/types/src/ui/components/LoomExportControls.d.ts

@@ -0,0 +1,13 @@
+/**
+ * <loom-export-controls> — SVG/PNG export buttons.
+ *
+ * Adds "Save SVG" and "Save PNG" buttons to the shell navbar.
+ * Calls GenomeBrowser.saveSVGtoFile() and savePNGtoFile() respectively.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomExportControls extends HTMLElement {
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+}

package/dist/types/src/ui/components/LoomInputDialog.d.ts

@@ -0,0 +1,27 @@
+/**
+ * <loom-input-dialog> — Simple modal input dialog Web Component.
+ *
+ * Shows a label, text input, and OK/Cancel buttons. Returns the entered
+ * value via a Promise. Used by the context menu's "Set track height" action.
+ *
+ * Customizable via CSS custom properties:
+ *   --loom-dialog-bg, --loom-dialog-border, --loom-dialog-shadow,
+ *   --loom-dialog-font, --loom-dialog-color, --loom-dialog-radius,
+ *   --loom-dialog-btn-bg, --loom-dialog-btn-color
+ */
+export declare class LoomInputDialog extends HTMLElement {
+    private labelEl;
+    private inputEl;
+    private okBtn;
+    private cancelBtn;
+    private resolve;
+    constructor();
+    connectedCallback(): void;
+    /**
+     * Show the dialog and return a Promise that resolves with the input value
+     * (on OK/Enter) or null (on Cancel/Escape).
+     */
+    prompt(label: string, currentValue: string | number): Promise<string | null>;
+    private confirm;
+    private cancel;
+}

package/dist/types/src/ui/components/LoomLocusInput.d.ts

@@ -0,0 +1,18 @@
+/**
+ * <loom-locus-input> — Locus search/display input.
+ *
+ * Shows the current locus as a formatted string. User can type a new locus
+ * and press Enter to navigate. Updates automatically on locuschange events.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomLocusInput extends HTMLElement {
+    private input;
+    private unsubscribe;
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+    private updateDisplay;
+    private doSearch;
+    disconnectedCallback(): void;
+}

package/dist/types/src/ui/components/LoomNavbar.d.ts

@@ -0,0 +1,15 @@
+/**
+ * <loom-navbar> — Horizontal navigation bar composing locus input, window size, and zoom controls.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomNavbar extends HTMLElement {
+    private chromSelect;
+    private locusInput;
+    private zoomControls;
+    private windowSize;
+    private exportControls;
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+}

package/dist/types/src/ui/components/LoomPopup.d.ts

@@ -0,0 +1,32 @@
+/**
+ * <loom-popup> — Feature popup / tooltip Web Component.
+ *
+ * Renders PopupDataItem[] as a name/value table. Positioned as a floating
+ * element near the pointer, clamped to stay within the viewport.
+ *
+ * Also exports DefaultPopupProvider which wraps this component and
+ * implements the PopupProvider interface.
+ */
+import type { PopupDataItem } from '../../types';
+import type { PopupProvider } from '../../popupProvider';
+export declare class LoomPopup extends HTMLElement {
+    constructor();
+    /** Populate popup with data items and show it. */
+    setData(data: PopupDataItem[]): void;
+    /** Position relative to a parent container and show. */
+    showAt(x: number, y: number): void;
+    hide(): void;
+}
+/**
+ * Default PopupProvider implementation using the <loom-popup> Web Component.
+ * Creates and manages a single popup element within the browser container.
+ */
+export declare class DefaultPopupProvider implements PopupProvider {
+    private element;
+    show(data: PopupDataItem[], position: {
+        x: number;
+        y: number;
+    }, container: HTMLElement): void;
+    hide(): void;
+    dispose(): void;
+}

package/dist/types/src/ui/components/LoomWindowSize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * <loom-window-size> — Read-only display of current viewport bp range.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomWindowSize extends HTMLElement {
+    private label;
+    private unsubscribe;
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+    private update;
+    disconnectedCallback(): void;
+}

package/dist/types/src/ui/components/LoomZoomControls.d.ts

@@ -0,0 +1,10 @@
+/**
+ * <loom-zoom-controls> — Zoom in/out buttons.
+ */
+import type { GenomeBrowser } from '../../genomeBrowser';
+export declare class LoomZoomControls extends HTMLElement {
+    private _browser;
+    constructor();
+    set browser(b: GenomeBrowser | null);
+    get browser(): GenomeBrowser | null;
+}

package/dist/types/src/ui/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * UI Shell — Web components for interacting with the headless GenomeBrowser.
+ *
+ * Importing this module auto-registers all custom elements:
+ *   <loom-browser>, <loom-navbar>, <loom-chromosome-select>, <loom-locus-input>, <loom-zoom-controls>, <loom-window-size>, <loom-export-controls>
+ */
+export { EventEmitter } from '../events';
+export { parseLocus, formatLocus, formatBpLength } from '../locusUtils';
+export { classicThemeCSS, modernThemeCSS, getThemeCSS } from './themes';
+export type { ShellTheme } from './themes';
+export { LoomChromosomeSelect } from './components/LoomChromosomeSelect';
+export { LoomLocusInput } from './components/LoomLocusInput';
+export { LoomZoomControls } from './components/LoomZoomControls';
+export { LoomWindowSize } from './components/LoomWindowSize';
+export { LoomExportControls } from './components/LoomExportControls';
+export { LoomNavbar } from './components/LoomNavbar';
+export { LoomBrowserShell, createShell } from './components/LoomBrowserShell';
+export type { CreateShellOptions } from './components/LoomBrowserShell';
+export { LoomPopup, DefaultPopupProvider } from './components/LoomPopup';
+export { LoomContextMenu, DefaultContextMenuProvider } from './components/LoomContextMenu';
+export { LoomInputDialog } from './components/LoomInputDialog';

package/dist/types/src/ui/themes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CSS custom property themes for UI shell web components.
+ *
+ * Themes are injected as <style> blocks into Shadow DOM roots.
+ * Components reference CSS custom properties (--loom-*) for all visual styling.
+ */
+export type ShellTheme = 'classic' | 'modern' | 'dark';
+/** Classic theme — matches igv.js navbar look. */
+export declare const classicThemeCSS = "\n:host {\n    --loom-navbar-bg: #f3f3f3;\n    --loom-navbar-height: 32px;\n    --loom-navbar-padding: 0 8px;\n    --loom-font: 12px Arial, sans-serif;\n    --loom-font-small: 11px Arial, sans-serif;\n    --loom-text-color: #333;\n    --loom-text-muted: #737373;\n    --loom-border: 1px solid #ccc;\n    --loom-border-radius: 4px;\n    --loom-button-bg: white;\n    --loom-button-hover: #e8e8e8;\n    --loom-button-border: 1px solid #b0b0b0;\n    --loom-button-size: 24px;\n    --loom-input-bg: white;\n    --loom-input-border: 1px solid #b0b0b0;\n    --loom-input-focus-border: 1px solid #4A90D9;\n    --loom-input-width: 220px;\n    --loom-input-height: 22px;\n    --loom-accent: #4A90D9;\n    --loom-icon-color: #555;\n    --loom-icon-size: 14px;\n    --loom-gap: 8px;\n}\n";
+/** Modern theme — softer colors, rounded corners, taller navbar. */
+export declare const modernThemeCSS = "\n:host {\n    --loom-navbar-bg: #fafbfc;\n    --loom-navbar-height: 40px;\n    --loom-navbar-padding: 0 12px;\n    --loom-font: 13px Inter, system-ui, -apple-system, sans-serif;\n    --loom-font-small: 11px Inter, system-ui, -apple-system, sans-serif;\n    --loom-text-color: #1a1a1a;\n    --loom-text-muted: #6b7280;\n    --loom-border: 1px solid rgba(0, 0, 0, 0.08);\n    --loom-border-radius: 8px;\n    --loom-button-bg: white;\n    --loom-button-hover: #f0f4ff;\n    --loom-button-border: 1px solid rgba(0, 0, 0, 0.1);\n    --loom-button-size: 28px;\n    --loom-input-bg: white;\n    --loom-input-border: 1px solid rgba(0, 0, 0, 0.12);\n    --loom-input-focus-border: 1px solid #4A90D9;\n    --loom-input-width: 260px;\n    --loom-input-height: 28px;\n    --loom-accent: #4A90D9;\n    --loom-icon-color: #6b7280;\n    --loom-icon-size: 16px;\n    --loom-gap: 10px;\n}\n";
+/** Dark theme — dark backgrounds, light text, high contrast. */
+export declare const darkThemeCSS = "\n:host {\n    --loom-shell-bg: #16162a;\n    --loom-navbar-bg: #1a1a2e;\n    --loom-navbar-height: 36px;\n    --loom-navbar-padding: 0 10px;\n    --loom-font: 12px Arial, sans-serif;\n    --loom-font-small: 11px Arial, sans-serif;\n    --loom-text-color: #e0e0e0;\n    --loom-text-muted: #888;\n    --loom-border: 1px solid #333;\n    --loom-border-radius: 4px;\n    --loom-button-bg: #2a2a3e;\n    --loom-button-hover: #3a3a50;\n    --loom-button-border: 1px solid #444;\n    --loom-button-size: 24px;\n    --loom-input-bg: #2a2a3e;\n    --loom-input-border: 1px solid #444;\n    --loom-input-focus-border: 1px solid #6a9fd9;\n    --loom-input-width: 220px;\n    --loom-input-height: 22px;\n    --loom-accent: #6a9fd9;\n    --loom-icon-color: #b0b0b0;\n    --loom-icon-size: 14px;\n    --loom-gap: 8px;\n}\n";
+export declare function getThemeCSS(theme: ShellTheme): string;

package/dist/types/src/worker/nodeWorkerProvider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NodeWorkerProvider — Node.js worker_threads implementation of WorkerProvider.
+ *
+ * Same RPC pattern as WebWorkerProvider but uses Node.js worker_threads API.
+ * All worker_threads references use dynamic import() to avoid requiring
+ * @types/node in browser-targeted builds.
+ *
+ * Usage:
+ *   import { NodeWorkerProvider } from './worker/nodeWorkerProvider'
+ *   const provider = new NodeWorkerProvider(new URL('./nodeWorkerScript.js', import.meta.url))
+ *   const browser = new HeadlessGenomeBrowser({ ..., workerProvider: provider })
+ *   // ...
+ *   provider.dispose()
+ */
+import type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+export declare class NodeWorkerProvider implements WorkerProvider {
+    private worker;
+    private nextId;
+    private pending;
+    private initPromise;
+    /**
+     * @param workerPath - Path or URL to the Node.js worker script.
+     */
+    constructor(workerPath: string | URL);
+    private init;
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    dispose(): void;
+}

package/dist/types/src/worker/taskHandler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure task dispatcher for worker threads.
+ *
+ * Maps WorkerTask → result using existing pure functions. No DOM, no
+ * environment-specific APIs. Imported by both the Web Worker script
+ * and the Node.js worker_threads script.
+ */
+import type { WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+/**
+ * Handle a worker task and return the result.
+ *
+ * Each task is dispatched to the appropriate pure function. The return
+ * value must be structured-clone-safe (or Transferable for ArrayBuffers).
+ */
+export declare function handleTask(task: WorkerTask): Promise<WorkerTaskResultMap[WorkerTask['task']]>;

package/dist/types/src/worker/webWorkerProvider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WebWorkerProvider — browser Web Worker implementation of WorkerProvider.
+ *
+ * Creates a pool of worker threads and dispatches tasks via round-robin.
+ * Supports Transferable for zero-copy ArrayBuffer transfer.
+ *
+ * Usage:
+ *   const provider = new WebWorkerProvider({ workerUrl: '/loom-worker.js', poolSize: 4 })
+ *   const browser = new GenomeBrowser({ ..., workerProvider: provider })
+ *   // ...
+ *   provider.dispose()
+ */
+import type { WorkerProvider, WorkerTask, WorkerTaskResultMap } from '../workerProvider';
+export interface WebWorkerProviderOptions {
+    /**
+     * URL to the worker script (built from workerScript.ts).
+     * Can be a blob URL, data URL, or path to a bundled worker script.
+     * Mutually exclusive with `workerFactory`.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Factory function that creates Worker instances.
+     * Use this with bundlers like webpack 5 that require `new Worker(new URL(...))` in
+     * the same expression for static analysis:
+     *
+     *   workerFactory: () => new Worker(new URL('./workerScript.ts', import.meta.url))
+     *
+     * Mutually exclusive with `workerUrl`.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * Number of workers in the pool. Tasks are distributed round-robin.
+     * Default: 1.
+     */
+    poolSize?: number;
+}
+export declare class WebWorkerProvider implements WorkerProvider {
+    private workers;
+    private nextId;
+    private nextWorker;
+    private pending;
+    /**
+     * @param optionsOrUrl - Options object with workerUrl and poolSize,
+     *   or a URL string/URL for backward compatibility (single worker).
+     */
+    constructor(optionsOrUrl: WebWorkerProviderOptions | string | URL);
+    /** Number of workers in the pool. */
+    get poolSize(): number;
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    dispose(): void;
+}

package/dist/types/src/worker/workerScript.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Web Worker entry point.
+ *
+ * This file is the script that runs inside the Web Worker. It listens
+ * for messages from the main thread, dispatches them to the task handler,
+ * and posts results back.
+ *
+ * Bundle this file as a standalone module (e.g. via Rollup/Vite worker plugin)
+ * and pass the resulting URL to WebWorkerProvider.
+ */
+export {};

package/dist/types/src/workerProvider.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WorkerProvider — environment abstraction for offloading CPU-intensive tasks.
+ *
+ * Follows the same injection pattern as CanvasProvider:
+ *   - Interface with minimal methods
+ *   - Concrete implementations for each environment
+ *   - Optional injection with a sensible default (MainThreadProvider)
+ *
+ * Implementations:
+ *   - MainThreadProvider  — synchronous fallback (runs tasks on main thread)
+ *   - WebWorkerProvider   — browser (Web Workers)
+ *   - NodeWorkerProvider  — Node.js (worker_threads)
+ */
+import type { AnnotationFeature, WigFeature, WindowFunction, TextFileFormat } from './types';
+import type { FeatureHeader } from './formats/featureParser';
+export interface PackTask {
+    task: 'pack';
+    features: AnnotationFeature[];
+    maxRows?: number;
+}
+export interface SummarizeWigTask {
+    task: 'summarize';
+    features: WigFeature[];
+    startBP: number;
+    bpPerPixel: number;
+    windowFunction: WindowFunction;
+}
+export interface ComputeWigRangeTask {
+    task: 'computeWigRange';
+    features: WigFeature[];
+}
+export interface ParseFeaturesTask {
+    task: 'parseFeatures';
+    /** Raw text lines to parse. */
+    lines: string[];
+    /** File format (bed, gff3, narrowpeak, etc.). */
+    format: TextFileFormat;
+    /** Pre-parsed header metadata. */
+    header?: FeatureHeader;
+    /** Whether to assemble GFF transcripts. Default: true. */
+    assembleGFF?: boolean;
+}
+export type WorkerTask = PackTask | SummarizeWigTask | ComputeWigRangeTask | ParseFeaturesTask;
+/** Maps task name → result type. */
+export interface WorkerTaskResultMap {
+    pack: AnnotationFeature[];
+    summarize: WigFeature[];
+    computeWigRange: {
+        min: number;
+        max: number;
+    };
+    parseFeatures: unknown[];
+}
+/**
+ * Execute CPU-intensive tasks, potentially in a worker thread.
+ *
+ * The `transfer` parameter accepts `Transferable` objects (e.g. `ArrayBuffer`)
+ * for zero-copy transfer to the worker. After transfer, the original buffer
+ * becomes detached on the sending side.
+ */
+export interface WorkerProvider {
+    execute<T extends WorkerTask>(task: T, transfer?: Transferable[]): Promise<WorkerTaskResultMap[T['task']]>;
+    /** Terminate worker threads and release resources. */
+    dispose(): void;
+}
+/**
+ * Runs all tasks on the main thread using direct function calls.
+ * This is the default when no WorkerProvider is supplied.
+ */
+export declare class MainThreadProvider implements WorkerProvider {
+    execute<T extends WorkerTask>(task: T): Promise<WorkerTaskResultMap[T['task']]>;
+    private dispatch;
+    dispose(): void;
+}
+/** Default worker provider: runs everything on the main thread. */
+export declare const mainThreadProvider: WorkerProvider;

package/dist/types/stateProjection.d.ts

@@ -0,0 +1,115 @@
+/**
+ * StateProjection — concise state snapshots with record/diff support.
+ *
+ * Wraps a HeadlessGenomeBrowser to produce compact, serializable 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/tabix/bgzBlockLoader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * BGZF block loader — fetches and decompresses BGZF blocks via HTTP range requests.
+ *
+ * Given two virtual offsets (from a tabix index), fetches the compressed bytes
+ * covering those blocks, decompresses them, and returns the data between the
+ * virtual offset boundaries.
+ *
+ * Caches the most recent compressed byte range so sequential/overlapping queries
+ * (common when iterating through tabix chunks) avoid redundant HTTP requests.
+ *
+ * Port of js/bam/bgzBlockLoader.ts BGZBlockLoader.
+ * Layer 1 (Data + Layout): pure data, no DOM.
+ */
+import type { VirtualOffset } from './virtualOffset';
+import type { WorkerProvider } from '../workerProvider';
+export interface BgzBlockLoaderOptions {
+    /**
+     * Cache compressed blocks for sequential/overlapping queries.
+     * Default: true. Disable for memory-constrained environments.
+     * Matches igv.js BGZBlockLoader.cacheBlocks config.
+     */
+    cacheBlocks?: boolean;
+    /** Worker provider for offloading BGZF decompression. */
+    workerProvider?: WorkerProvider;
+}
+export declare class BgzBlockLoader {
+    private readonly url;
+    private readonly cacheEnabled;
+    private readonly workerProvider?;
+    private cache;
+    constructor(url: string, options?: BgzBlockLoaderOptions);
+    /**
+     * Fetch and decompress data between two virtual offsets.
+     *
+     * Uses a single-entry cache of compressed bytes. When the requested range
+     * overlaps or falls within the cached range, only the missing portions are
+     * fetched. This matches the igv.js pattern where sequential tabix chunks
+     * often share or overlap compressed block ranges.
+     *
+     * Port of js/bam/bgzBlockLoader.ts BGZBlockLoader.getData().
+     */
+    getData(minv: VirtualOffset, maxv: VirtualOffset, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * Return inflated blocks for the given compressed block range.
+     * Manages the compressed-data cache to minimize HTTP requests.
+     *
+     * Port of js/bam/bgzBlockLoader.ts BGZBlockLoader.getInflatedBlocks().
+     */
+    private getInflatedBlocks;
+    /**
+     * Decompress BGZF blocks, delegating to worker when available.
+     */
+    private inflate;
+    /**
+     * Fetch compressed block data from the remote file.
+     *
+     * Port of js/bam/bgzBlockLoader.ts BGZBlockLoader.loadBLockData().
+     */
+    private loadBlockData;
+}