@jbrowse/capture 5.0.0-beta.10 → 5.0.0-beta.13

package/README.md

@@ -57,7 +57,9 @@ decides the answer:
 Then one check on what the frame shows, which the marker does not answer. The
 marker is about WORK, so it reads `ready` over a display whose fetch failed or
 that the user canceled. Capture names every display that is unpainted, canceled
-or showing an error banner, and fails.
+or showing an error banner, and fails. It fails too on an error toast or error
+box, which no display carries: a track whose config fails to load never becomes
+a display, so the frame lacks it while every display present has painted.
 
 **The instance has to be JBrowse v5 or later**, the first release to publish the
 marker. Capture reads the instance's `version.txt` before launching a browser
@@ -140,7 +142,9 @@ the frame as it stands.
 ```
 
 `allowUnsettled` (`--allowUnsettled`) takes the frame as it stands instead, and
-still tells you what did not settle.
+still tells you what did not settle. It does not cover the session gate: a
+trackId or assembly that never opens throws either way, since that frame lacks
+the thing you asked to capture.
 
 ## Reading the result
 
@@ -158,6 +162,52 @@ Three fields on a successful capture:
   asked. The capture still succeeds, since that is the app working as designed,
   and the CLI prints a warning naming them. Narrow the location to draw them.
 
+## Callouts
+
+`--annotations` draws arrows, boxes, labels, numbered badges, legends and
+lineage trapezoids over the view once it has settled, from a JSON array (inline,
+a path, or `-` for stdin). These are the callouts on the JBrowse documentation's
+figures, drawn by the same code, so a figure's **Open or rebuild this view**
+dialog hands you its callouts as a file to pass here.
+
+```bash
+cat > callouts.json <<'JSON'
+[
+  { "type": "box", "anchor": { "loc": "chr17:43,044,295-43,125,483" } },
+  {
+    "type": "text",
+    "text": "BRCA1",
+    "leader": true,
+    "anchor": { "trackId": "hg38-ncbiRefSeqCurated", "loc": "chr17:43,044,295", "fracY": 0.5 },
+    "dx": -60,
+    "dy": -30
+  }
+]
+JSON
+npx @jbrowse/capture --hub hg38 --loc BRCA1 --track hg38-ncbiRefSeqCurated \
+  --annotations callouts.json -o brca1.png
+```
+
+Each callout places itself through an `anchor` that resolves against the running
+session, so none of them is a pixel measured off an earlier capture:
+
+- `loc`, with an optional `trackId` and `fracY` (0 is the track's top, 1 its
+  bottom), lands on a genomic position in a linear genome view. A `view` index
+  picks the view, and an array (`[0, 1]`) descends into a synteny view's rows.
+- `graphNode` names a GFA segment in a graph view or graph track.
+- `hLoc` and `vLoc` name a dotplot's cell, as a whole chromosome (`chr4`) or a
+  span (`chr4:1-5,000,000`).
+- `selector` and `text` name an element of the page, such as a menu item.
+
+`dx` and `dy` nudge a callout off its anchor, and `fromAnchor` anchors an
+arrow's tail. The full vocabulary is `Annotation` in `annotationOverlay.ts`,
+exported as types from this package. An anchor that resolves to nothing, or a
+callout that lands outside the image, fails the run rather than writing a
+picture with the callout missing or parked in a corner.
+
+In a script, pass the same array as `annotations` to `captureJBrowse`, or call
+`drawAnnotations(page, annotations)` on the page `openJBrowse` returns.
+
 ## CLI
 
 `jb2capture --help` for the full list. Also:

package/esm/annotationOverlay.d.ts

@@ -0,0 +1,77 @@
+export interface AnnotationAnchor {
+    selector?: string;
+    text?: string;
+    graphNode?: string;
+    hLoc?: string;
+    vLoc?: string;
+    view?: number | number[];
+    trackId?: string;
+    loc?: string;
+    fracY?: number;
+    alignX?: 'left' | 'center' | 'right';
+    alignY?: 'top' | 'center' | 'bottom';
+    dx?: number;
+    dy?: number;
+    fracX?: [number, number];
+}
+export declare const ANNOTATION_TYPES: readonly ['arrow', 'box', 'text', 'circle', 'legend', 'trapezoid'];
+export interface Annotation {
+    type: (typeof ANNOTATION_TYPES)[number];
+    entries?: {
+        label: string;
+        color: string;
+    }[];
+    from?: {
+        x: number;
+        y: number;
+    };
+    to?: {
+        x: number;
+        y: number;
+    };
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    radius?: number;
+    pad?: number;
+    text?: string;
+    color?: string;
+    textColor?: string;
+    background?: string;
+    maxWidth?: number;
+    textAlign?: 'start' | 'end';
+    leader?: boolean;
+    fontSize?: number;
+    strokeWidth?: number;
+    fillOpacity?: number;
+    anchor?: AnnotationAnchor;
+    fromAnchor?: AnnotationAnchor;
+    dx?: number;
+    dy?: number;
+}
+export interface AnnotationRegion {
+    refName: string;
+    start: number;
+    end: number;
+}
+export type ResolvedAnnotationAnchor = AnnotationAnchor & {
+    region?: AnnotationRegion;
+    rect?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+export type PayloadAnnotation = Omit<Annotation, 'anchor' | 'fromAnchor'> & {
+    anchor?: ResolvedAnnotationAnchor;
+    fromAnchor?: ResolvedAnnotationAnchor;
+};
+export declare const ANNOTATION_OVERLAY_ID = "__screenshot_annotation_overlay";
+export declare function parseAnnotationLocus(locus: string, wrap?: boolean): AnnotationRegion;
+export interface AnnotationOverlayProblems {
+    unresolved: string[];
+    offFrame: string[];
+}
+export declare function drawAnnotationOverlay(items: PayloadAnnotation[], overlayId: string): AnnotationOverlayProblems;