loom-browser 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-2025 Broad Institute of MIT and Harvard, Regents of the University of California
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+<p align="center">
+  <img src="docs-site/static/img/logo.svg" alt="Loom" width="200" />
+</p>
+
+<h1 align="center">Loom</h1>
+
+<p align="center">A modular, headless-first genomic visualization engine built in TypeScript.</p>
+
+[![npm](https://img.shields.io/npm/v/loom-browser.svg)](https://www.npmjs.com/package/loom-browser)
+[![license](https://img.shields.io/npm/l/loom-browser.svg)](LICENSE)
+
+Loom renders genomic tracks (genes, signal, sequence, interactions) to Canvas or SVG. It works headlessly in Node for server-side rendering, in web workers, and in the browser with full interactivity.
+
+## Quick Start
+
+```
+npm install loom-browser
+```
+
+### Interactive browser (DOM)
+
+```ts
+import { GenomeBrowser } from 'loom-browser'
+
+const browser = new GenomeBrowser(document.getElementById('container')!, {
+  locus: { chr: 'chr17', start: 7_668_000, end: 7_688_000 },
+})
+
+browser.addRuler()
+browser.addGeneTrack()                                          // UCSC RefSeq genes
+browser.addWigTrack('https://example.com/signal.bigWig', {
+  config: { color: '#4A90D9', height: 80 },
+})
+browser.addBedTrack('https://example.com/peaks.bed.gz')
+browser.addInteractionTrack('https://example.com/loops.bedpe')
+browser.addSequenceTrack()                                      // visible at base-level zoom
+```
+
+Built-in drag-to-pan, sweep-to-zoom on the ruler, pinch-to-zoom, and responsive resizing — no setup needed.
+
+### Headless (Node / SSR)
+
+```ts
+import { HeadlessGenomeBrowser } from 'loom-browser'
+
+const browser = new HeadlessGenomeBrowser({
+  locus: { chr: 'chr17', start: 7_668_000, end: 7_688_000 },
+  viewportWidth: 1200,
+})
+
+browser.addRuler()
+browser.addGeneTrack()
+browser.addWigTrack('https://example.com/signal.bigWig')
+
+// Wait for data, then export
+browser.on('dataloaded', () => {
+  const svg = browser.toSVG({ width: 1200, backdropColor: '#fff' })
+  fs.writeFileSync('output.svg', svg)
+})
+```
+
+### UI Shell (web components)
+
+Drop in a full browser shell with navbar, locus search, zoom controls, and export buttons:
+
+```ts
+import { createShell } from 'loom-browser'
+
+const shell = createShell(document.getElementById('container')!, {
+  locus: { chr: 'chr17', start: 7_668_000, end: 7_688_000 },
+  shellTheme: 'modern', // 'classic' | 'modern' | 'dark'
+})
+
+shell.browser.addRuler()
+shell.browser.addGeneTrack()
+```
+
+Or use the custom element directly:
+
+```html
+<loom-browser theme="modern" id="my-browser"></loom-browser>
+```
+
+## Track Types
+
+| Type | Method | Formats | Description |
+|------|--------|---------|-------------|
+| **Ruler** | `addRuler()` | — | Genomic coordinate axis with tick marks |
+| **Gene / Annotation** | `addGeneTrack()`, `addBedTrack(url)` | BED, GFF3, GTF, GenePred, RefFlat, NarrowPeak, BroadPeak | Gene models with exons, UTR, strand arrows, labels |
+| **Signal** | `addWigTrack(url)` | BigWig, BedGraph | Bar, line, points, or dynamic-sequence graphs with autoscale |
+| **Sequence** | `addSequenceTrack()` | UCSC API | DNA bases with optional 3-frame translation |
+| **Interaction** | `addInteractionTrack(url)` | BEDPE, UCSC interact | Arc diagrams for chromatin loops and contacts |
+
+## Navigation
+
+```ts
+browser.search('TP53')                          // gene name lookup
+browser.search('chr17:7,668,000-7,688,000')     // locus string
+browser.setLocus({ chr: 'chr17', start: 7_668_000, end: 7_688_000 })
+browser.zoomIn()                                // 2x
+browser.zoomOut(4)                              // 4x
+```
+
+## Events
+
+```ts
+browser.on('locuschange', ({ locus }) => { /* navigation happened */ })
+browser.on('dataloaded',  ({ track }) => { /* track finished loading */ })
+browser.on('trackclick',  ({ track, feature, x, y }) => { /* feature clicked */ })
+browser.on('trackcontextmenu', ({ track, feature, x, y }) => { /* right-click */ })
+```
+
+Full list: `locuschange`, `trackadded`, `trackremoved`, `trackorderchanged`, `dataloaded`, `dataerror`, `rendererror`, `trackclick`, `trackhover`, `trackcontextmenu`, `roiadded`, `roiremoved`, `roichanged`, `roiclick`, `roicontextmenu`.
+
+## Themes
+
+Three built-in render themes control colors for all track types:
+
+```ts
+import { defaultRenderTheme, modernRenderTheme, darkRenderTheme } from 'loom-browser'
+
+const browser = new GenomeBrowser(container, {
+  locus,
+  theme: darkRenderTheme,
+})
+```
+
+Override individual properties or provide per-track overrides:
+
+```ts
+browser.addWigTrack(url, {
+  config: { color: '#E74C3C', graphType: 'line', height: 60 },
+})
+```
+
+## Export
+
+```ts
+// SVG string
+const svg = browser.toSVG({ width: 1200, backdropColor: '#ffffff' })
+
+// PNG data URL (DOM browser only)
+const png = await browser.toPNG()
+
+// Download files
+browser.saveSVGtoFile('my-region.svg')
+await browser.savePNGtoFile('my-region.png')
+```
+
+## Regions of Interest (ROIs)
+
+```ts
+browser.addROI({
+  chr: 'chr17', start: 7_674_000, end: 7_676_000,
+  color: 'rgba(255, 0, 0, 0.15)',
+  label: 'Exon 7',
+})
+
+const rois = browser.getVisibleROIs()
+browser.removeROI(rois[0].id)
+```
+
+## Sessions
+
+Save and restore browser state:
+
+```ts
+const session = browser.toJSON()           // serialize
+browser.loadSession(session)               // restore
+
+// Import from igv.js session format
+import { fromIgvSession } from 'loom-browser'
+const loomSession = fromIgvSession(igvSessionObject)
+```
+
+## Remote Control (WebSocket)
+
+Let an LLM or agent control the browser over WebSocket:
+
+```ts
+const ws = new WebSocket('wss://your-server/browser')
+browser.attachRemote(ws)
+```
+
+Or use `CommandDispatcher` in-process:
+
+```ts
+import { CommandDispatcher } from 'loom-browser'
+
+const dispatcher = new CommandDispatcher(browser)
+const state = await dispatcher.dispatch({ command: 'get_browser_state' })
+await dispatcher.dispatch({ command: 'navigate', locus: 'BRCA1' })
+await dispatcher.dispatch({
+  command: 'modify_tracks',
+  actions: [{ action: 'add', type: 'wig', url: 'https://example.com/signal.bigWig' }],
+})
+```
+
+Commands: `get_browser_state`, `navigate`, `modify_tracks`, `query_features`, `set_layout`, `export_view`, `manage_rois`, `subscribe_events`.
+
+## State Projection
+
+Inspect browser state programmatically (useful for agents/LLMs):
+
+```ts
+const state = browser.state.getState()
+// { locus, locusString, span, zoomLevel, tracks: [...], rois: [...] }
+
+// Diff workflow
+browser.state.getState({ record: 'before' })
+browser.search('chr1:1,000,000-2,000,000')
+const diff = browser.state.diff('before')
+// { locus: { from, to }, zoomLevel: { from, to }, ... }
+```
+
+## Web Workers
+
+Offload BigWig decoding and feature packing to a worker thread:
+
+```ts
+import { GenomeBrowser, WebWorkerProvider } from 'loom-browser'
+
+const browser = new GenomeBrowser(container, {
+  locus,
+  workerProvider: new WebWorkerProvider('/loom-worker.js'),
+})
+```
+
+In Node:
+
+```ts
+import { NodeWorkerProvider } from 'loom-browser'
+const browser = new HeadlessGenomeBrowser({
+  locus,
+  viewportWidth: 1200,
+  workerProvider: new NodeWorkerProvider(),
+})
+```
+
+## Low-Level Renderer API
+
+Use standalone renderers and track canvases directly — no browser instance needed:
+
+```ts
+import { AnnotationTrackCanvas, fetchGeneFeatures } from 'loom-browser'
+
+const canvas = document.createElement('canvas')
+const track = new AnnotationTrackCanvas(canvas, {
+  locus: { chr: 'chr17', start: 7_668_000, end: 7_688_000 },
+  features: [],
+  config: { displayMode: 'EXPANDED', featureHeight: 14, drawLabels: true },
+})
+track.attachTo(document.getElementById('track-container')!)
+
+const features = await fetchGeneFeatures(track.locus)
+track.setFeatures(features)
+```
+
+## Architecture
+
+Loom uses a four-layer architecture. Each layer has zero dependencies on the layers above it:
+
+1. **Data + Layout** — Types, decoders, data sources, feature packing. No DOM, no canvas. Safe for Node and workers.
+2. **Renderers** — Stateless pure functions: `(ctx, features, config, viewport) → pixels`. Takes `CanvasRenderingContext2D`, no DOM.
+3. **Headless Browser** — Track orchestration, data lifecycle, navigation, session serialization, SVG export. No DOM.
+4. **DOM Shell** — `GenomeBrowser` adds pointer events, drag/pan/zoom, axis columns, ResizeObserver. Web components for UI.
+
+## Development
+
+```
+git clone https://github.com/riyavsinha/loom.git
+cd loom
+npm install
+npm run build
+```
+
+```
+npm test                                    # unit tests (Vitest)
+npm run typecheck                           # type check src/
+npx tsc --noEmit                            # type check js/ (legacy)
+npm run storybook                           # component stories
+npm run test:visual                         # Playwright screenshot tests
+```
+
+## License
+
+[MIT](LICENSE)