Host Bridge

The host hands your plugin a RBrowserHost in activate / render. It is capability-scoped — only the methods your manifest permissions grant will do anything. Never construct a host yourself; always use the one passed in (or, in React, useRBrowserHost()).

interface RBrowserHost {
  readonly info: HostInfo
  getState(): RBrowserState
  subscribe<K>(key: K, callback: (value: RBrowserState[K]) => void): Unsubscribe
  subscribeAll(callback: (state: RBrowserState) => void): Unsubscribe
  navigate(target: NavigateTarget): void
  highlight: HighlightApi
  storage: PluginStorage
}

API	Permission required
info, getState, subscribe, subscribeAll	state:read
navigate	navigation:write
highlight.*	highlight:write
storage.*	storage:write

---

info

property

host.info: HostInfo

Identity and capability metadata for this bridge.

interface HostInfo {
  pluginId: string         // the plugin id this bridge is scoped to
  permissions: Permission[] // granted permissions (copy of the manifest)
  version: string          // host application version (semver)
  apiVersion: ApiVersion   // API protocol version, currently '1'
}

getState

method

host.getState(): RBrowserState

Returns a snapshot of all read-only state keys. For live updates, prefer subscribe or the React hooks.

subscribe

method

host.subscribe<K>(key: K, callback: (value: RBrowserState[K]) => void): Unsubscribe

Subscribe to a single state key. Returns an unsubscribe function.

const off = host.subscribe('selectedRNA', (rna) => {
  console.log('selection changed:', rna?.transcriptName)
})
off() // stop listening

subscribeAll

method

host.subscribeAll(callback: (state: RBrowserState) => void): Unsubscribe

Subscribe to every state-key change at once. Returns an unsubscribe function.

---

State surface

type RBrowserState

The read-only keys every plugin can observe via getState / subscribe / hooks.

Key	Type	Description
species	Species	Current organism + reference (e.g. human / GRCh38)
selectedRNA	SelectedRNA \| null	Transcript currently selected by the user
channels	ChannelSnapshot[]	All visible data channels (plot / level / url)
favorites	FavoriteEntry[]	User's saved regions
history	HistoryEntry[]	Recently-visited regions (region + timestamp)
highlightRegions	HighlightRegionList	Named highlight regions per coordinate level

Domain types

interface Species {
  name: 'human' | 'mouse' | (string & {})
  assembly: 'GRCh38' | 'GRCm38' | (string & {})
}

interface SelectedRNA {
  transcriptId?: string
  transcriptName?: string
  geneId?: string
  geneName?: string
  transcriptType?: string
  features?: TranscriptFeatures // exons / introns / utr5 / utr3 / cds / start|stopCodon
}

interface ChannelSnapshot {
  name: string
  plot?: string    // 'line' | 'bar' | 'diamond' | 'bigwig' | ...
  level?: string   // 'RNA' | 'DNA' | 'CDS' | ...
  group?: string
  url?: string
  format?: string  // 'bigwig' | 'bam' | 'bed' | ...
}

interface FavoriteEntry { region: string }                 // e.g. "chr1:100-200" / "VAMP3-201:5000"
interface HistoryEntry { region: string; timestamp: number } // unix ms of last visit

interface HighlightRegion { name: string; start: number; end: number; color?: string }
interface HighlightRegionList { DNA: HighlightRegion[]; RNA: HighlightRegion[]; mRNA: HighlightRegion[]; CDS: HighlightRegion[] }

---

navigate

method · requires navigation:write

host.navigate(target: NavigateTarget): void

Move the host to a genomic region or a transcript.

// by region
host.navigate({ chr: 'chr1', start: 7766295, end: 7786432 })

// by transcript (optional bp padding on each side)
host.navigate({ transcriptId: 'ENST00000409539', padding: 1000 })

type NavigateTarget =
  | { chr: string; start: number; end: number }
  | { transcriptId: string; padding?: number }

highlight

property · requires highlight:write

host.highlight: HighlightApi

Name-keyed regions overlaid on the renderer (mRNA / spliced coordinates).

host.highlight.add({ name: 'binding-site', start: 100, end: 150, color: '#ff8800' })
host.highlight.remove(0) // by index in the mRNA list
host.highlight.clear()

interface HighlightApi {
  add(region: HighlightRegion): void
  remove(index: number): void
  clear(): void
}

storage

property · requires storage:write

host.storage: PluginStorage

Per-plugin namespaced key/value store, backed by localStorage. Keys are isolated per plugin id.

host.storage.set('lastQuery', 'BRCA1')
host.storage.get('lastQuery') // 'BRCA1' | null
host.storage.keys()           // string[]
host.storage.remove('lastQuery')
host.storage.clear()

interface PluginStorage {
  get(key: string): string | null
  set(key: string, value: string): void
  remove(key: string): void
  keys(): string[]
  clear(): void
}

In React, the same store is available as the useRBrowserStorage hook.