@jbrowse/render-core 4.3.0

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@jbrowse/render-core",
+  "version": "4.3.0",
+  "type": "module",
+  "description": "GPU/Canvas2D rendering primitives for JBrowse displays: the HAL, the draw-lifecycle mixin, per-region/global backend bases, and the React backend hooks",
+  "keywords": [
+    "jbrowse",
+    "jbrowse2",
+    "webgl",
+    "webgpu",
+    "rendering"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://jbrowse.org",
+  "bugs": "https://github.com/GMOD/jbrowse-components/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GMOD/jbrowse-components.git",
+    "directory": "packages/render-core"
+  },
+  "author": "JBrowse Team",
+  "//files": "src/shaders ships the shared .slang modules (hpmath, antialias, capsule, colorPack, coverageBand, diagonalGrid, pointGlyph, rowRect, scoreScale) that any shader imports, plus the coverage-band entry-point passes drawn by two plugins. @jbrowse/shader-tools resolves its include path here, so an out-of-tree plugin can compile its own .slang against them.",
+  "files": [
+    "esm",
+    "src/shaders"
+  ],
+  "exports": {
+    "./RenderCanvas": "./esm/RenderCanvas.js",
+    "./RenderLifecycleMixin": "./esm/RenderLifecycleMixin.js",
+    "./blockClipUtils": "./esm/blockClipUtils.js",
+    "./canvas2dUtils": "./esm/canvas2dUtils.js",
+    "./canvasContext": "./esm/canvasContext.js",
+    "./colorRampLut": "./esm/colorRampLut.js",
+    "./coverageBand": "./esm/coverageBand.js",
+    "./coverageBandBuffers": "./esm/coverageBandBuffers.js",
+    "./createRenderingBackend": "./esm/createRenderingBackend.js",
+    "./displayPhase": "./esm/displayPhase.js",
+    "./globalRenderingBackend": "./esm/globalRenderingBackend.js",
+    "./gpuDevice": "./esm/gpuDevice.js",
+    "./graphicsCapabilities": "./esm/graphicsCapabilities.js",
+    "./hal": "./esm/hal/index.js",
+    "./installUpload": "./esm/installUpload.js",
+    "./instanceCache": "./esm/instanceCache.js",
+    "./instancePass": "./esm/instancePass.js",
+    "./keyedRenderingBackend": "./esm/keyedRenderingBackend.js",
+    "./namedReactions": "./esm/namedReactions.js",
+    "./OverlayCanvas": "./esm/OverlayCanvas.js",
+    "./perRegionRenderingBackend": "./esm/perRegionRenderingBackend.js",
+    "./regionDataMap": "./esm/regionDataMap.js",
+    "./renderBlock": "./esm/renderBlock.js",
+    "./renderingBackendBase": "./esm/renderingBackendBase.js",
+    "./ScrollLockedOverlay": "./esm/ScrollLockedOverlay.js",
+    "./shaders/antialias": "./esm/shaders/antialias.js.generated.js",
+    "./shaders/capsuleConsts": "./esm/shaders/capsule.generated.js",
+    "./shaders/colorRampLutConsts": "./esm/shaders/colorRampLut.generated.js",
+    "./shaders/coverageBar": "./esm/shaders/coverageBar.generated.js",
+    "./shaders/coverageIndicator": "./esm/shaders/coverageIndicator.generated.js",
+    "./shaders/coverageInterbase": "./esm/shaders/coverageInterbase.generated.js",
+    "./shaders/coverageMod": "./esm/shaders/coverageMod.generated.js",
+    "./shaders/coverageSnp": "./esm/shaders/coverageSnp.generated.js",
+    "./shaders/hpmath": "./esm/shaders/hpmath.js.generated.js",
+    "./shaders/pointGlyph": "./esm/shaders/pointGlyph.js.generated.js",
+    "./shaders/pointGlyphConsts": "./esm/shaders/pointGlyph.generated.js",
+    "./shaders/rowRect": "./esm/shaders/rowRect.js.generated.js",
+    "./shaders/rowRectConsts": "./esm/shaders/rowRect.generated.js",
+    "./shaders/scoreScale": "./esm/shaders/scoreScale.js.generated.js",
+    "./slangPass": "./esm/slangPass.js",
+    "./useGraphicsCapabilities": "./esm/useGraphicsCapabilities.js",
+    "./useRenderingBackend": "./esm/useRenderingBackend.js",
+    "./useTabVisibilityRerender": "./esm/useTabVisibilityRerender.js"
+  },
+  "dependencies": {
+    "@jbrowse/mobx-state-tree": "^6.5.1",
+    "mobx": "^7.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "//publishConfig": "Generated from `exports` above by scripts/generate-publish-exports.ts (`pnpm autogen`) — edit that map, never this one. The two describe the same subpaths against different trees, and only this one is what an installed consumer resolves, so drift between them is invisible until someone unpacks the tarball. It used to end in a `./*` wildcard, which served every emitted file including the ones src/index.ts withholds as internal.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build:esm": "node ../../node_modules/typescript7/bin/tsc --build tsconfig.build.esm.json",
+    "build": "pnpm build:esm",
+    "test": "cd ../..; jest --passWithNoTests packages/render-core",
+    "clean": "rimraf esm *.tsbuildinfo",
+    "prebuild": "pnpm clean"
+  }
+}

package/src/shaders/antialias.js.generated.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from antialias.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of antialias.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+function _clamp(x: number, lo: number, hi: number) {
+  return _min(_max(x, lo), hi)
+}
+
+function _max(a: number, b: number) {
+  return b > a || Number.isNaN(a) ? b : a
+}
+
+function _min(a: number, b: number) {
+  return b < a || Number.isNaN(a) ? b : a
+}
+
+export function aaPx(dpr: number): number {
+  return (1.0 / _max(dpr, 1.0))
+}
+
+export function aaHalfPx(dpr: number): number {
+  return (0.5 * aaPx(dpr))
+}
+
+export function aaRamp(signedInk: number, widthPx: number): number {
+  return _clamp(((signedInk / widthPx) + 0.5), 0.0, 1.0)
+}
+
+export function edgeCoverage(signedInkCssPx: number, dpr: number): number {
+  return aaRamp(signedInkCssPx, aaPx(dpr))
+}

package/src/shaders/antialias.slang

@@ -0,0 +1,112 @@
+// Shared edge-antialiasing ramps.
+//
+// Every GPU mark in the tree fades its edge over one OUTPUT pixel. What differs
+// between shaders is how wide that is in the units the fragment measures in,
+// and there are exactly two answers:
+//
+//   - Analytic, when the fragment's distance is a true perpendicular distance
+//     in CSS px. The HAL sizes the backing store by getDpr() and sets the
+//     viewport to canvas.width/height (DEVICE px) while coordinates stay CSS
+//     px, so one output sample spans 1/dpr CSS px. `aaPx` is that number, and
+//     `edgeCoverage` is the only thing that should be spelling it.
+//   - Measured, when it is not — a quad-local SDF whose scale differs per
+//     shape, or a varying whose foreshortening the shader cannot state.
+//     `aaGradient` is that number.
+//
+// `aaGradient` is deliberately not `fwidth`. fwidth is |ddx| + |ddy|, which
+// overshoots a true gradient by up to sqrt(2), worst on the diagonals — where
+// a dotplot line, a synteny ribbon edge and a chevron arm all live. The dotplot
+// capsule, the synteny fill and the glyph SDFs each found that separately, in
+// three plugins, before this module existed.
+//
+// `aaRamp` — linear in the signed distance — is the shape every mark in the
+// tree fades on, and that is measured rather than preferred. Scored against
+// exact area coverage of a pixel by a straight edge, the linear ramp is closer
+// at EVERY angle: exact on an axis-aligned edge, where the cubic is up to 0.096
+// of full ink out, and 0.043 against 0.067 worst case at 45 degrees. A band
+// built as a difference of two ramps is exact at every width with the linear
+// one; the cubic over-inks a half-pixel band by 37% (0.688 where 0.500 is the
+// coverage). `scripts/aa_ramp_coverage_study.ts` is the measurement.
+//
+// There WAS a second shape here, `aaSmoothRamp` — `smoothstep(-h, h, d)` — and
+// it is gone rather than deprecated, because a shader function nothing calls is
+// dead-code-eliminated out of every compiled shader and the js-skip check says
+// so out loud. Four shaders took it: synteny's `perpCoverage` and
+// `vertCoverage`, the dotplot capsule, and `glyphEdgeAlpha`, and through it
+// every point glyph. It read softer on a curve, which is it carrying more ink
+// on both sides of the half-max contour rather than resolving the curve better.
+// Re-deriving that shape is the study's job, not this module's — it models both
+// in JS and scores them, so the comparison survives the deletion.
+//
+// If you reintroduce a smoothstep here, note the two forms take DIFFERENT
+// arguments: the smoothstep takes the HALF width where `aaRamp` takes the full.
+// A conversion either way is a factor of two, and dropping it compiles.
+//
+// The floor on `aaGradient` exists for an SDF that is a constant, such as
+// manhattan's SHAPE_BAR: zero gradient makes the ramp zero-wide and the
+// division 0/0. A degenerate ramp saturates to alpha 1, which is the solid fill
+// those shapes want.
+// A test modelling a shader's geometry needs the ramp's reach and its shape, so
+// both go to JS. Not for a Canvas2D twin — that side's rasterizer does its own
+// edge AA — but because the alternative is every pad test re-spelling `0.5/dpr`
+// and then agreeing with its own copy, which is what dotplotCapsulePad.test.ts
+// and syntenyFillPad.test.ts each did.
+//! js-export: aaPx, aaHalfPx, aaRamp, edgeCoverage
+module antialias;
+
+// Width of a ramp covering exactly one output pixel, in CSS px. THE conversion
+// between the two units in this file: a fragment measuring in CSS px against a
+// device-px grid asks for this and nothing else. `max(dpr, 1.0)` is defensive —
+// getDpr() never returns less — and keeps a bogus uniform from inverting the
+// ramp.
+public float aaPx(float dpr) {
+  return 1.0 / max(dpr, 1.0);
+}
+
+// Half of it: how far past the ink a ramp reaches, and so exactly how far a
+// vertex stage must pad its quad to hold one. A pad stated in CSS px instead
+// over-reaches by dpr — 2x on a plain monitor, 4x on a retina one — and every
+// fragment in the surplus shades to alpha 0.
+public float aaHalfPx(float dpr) {
+  return 0.5 * aaPx(dpr);
+}
+
+
+// One output pixel of `d`, in whatever units `d` is: the true gradient
+// magnitude per device pixel. Takes derivatives, so uniform control flow only.
+public float aaGradient(float d) {
+  return max(length(float2(ddx(d), ddy(d))), 1e-5);
+}
+
+// Linear coverage over a ramp `widthPx` wide, centred on the edge. `signedInk`
+// is positive inside the mark and zero on its boundary.
+public float aaRamp(float signedInk, float widthPx) {
+  return clamp(signedInk / widthPx + 0.5, 0.0, 1.0);
+}
+
+// Coverage of a mark's edge for a fragment whose distance is a TRUE
+// perpendicular distance in CSS px, so its gradient is analytically 1 and there
+// is nothing for `aaGradient` to discover. `signedInkCssPx` is how far inside
+// the ink the fragment is: positive within, zero on the boundary.
+//
+// One function, because there is one ramp. It carries no cap and no shape —
+// a capsule, a butt-capped segment, a synteny ribbon edge and a wiggle bar all
+// reduce to this once their own distance is in hand, and spelling the width
+// again beside each of them is how `2.0 * aaHalfPx(dpr)` and
+// `STROKE_AA_PX / max(dpr, 1.0)` came to be the same number under two
+// constants, one of which no test could see double.
+public float edgeCoverage(float signedInkCssPx, float dpr) {
+  return aaRamp(signedInkCssPx, aaPx(dpr));
+}
+
+// A glyph SDF's edge, measured. `coverage` is positive inside and zero on the
+// edge, in whatever units the SDF uses — the gradient supplies the conversion,
+// so one call covers a disc, an L1 diamond (whose gradient carries a sqrt(2)
+// the others don't) and a constant-SDF bar with no per-shape constant.
+//
+// Callers that select between several SDFs must pick their coverage in the
+// branch and call this once after it: WGSL rejects a derivative taken under a
+// branch on a varying.
+public float glyphEdgeAlpha(float coverage) {
+  return aaRamp(coverage, aaGradient(coverage));
+}

package/src/shaders/capsule.generated.ts

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from capsule.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const CAPSULE_MIN_LEN_PX = 0.0001

package/src/shaders/capsule.slang

@@ -0,0 +1,62 @@
+// A stroked segment's frame, its quad and its distance. The round cap lives in
+// `capsuleDist` and nowhere else: the edge ramp over that distance is
+// `antialias`'s one `edgeCoverage`, shared with every butt-capped stroke in the
+// tree. Consumers, and which half each takes:
+// agent-docs/reference/SHADER_SHAPE_LIBRARY.md.
+//
+// `capsuleQuadLocal` pads by exactly `aaHalfPx(dpr)` past the ink. Pad less and
+// the ramp is clipped at the quad edge — coverage falls to 0.5 at the boundary,
+// the rasterizer cuts it to 0, and the line reads a hard 50%-alpha edge about a
+// pixel narrower than `lineWidth` asked for. Pad more and the surplus fragments
+// shade to alpha 0.
+//
+// The distance is Euclidean in CSS px, so |grad d| = 1 at every angle and the
+// ramp is analytic rather than differentiated — which it has to be, since `d`
+// comes off a clamp and the 2x2 quads straddling the cap/body junction would be
+// differentiating a discontinuity.
+//! export-consts: CAPSULE_MIN_LEN_PX
+module capsule;
+
+import antialias;
+import hpmath;
+
+// Below this length a segment has no direction to speak of and `delta / len`
+// is 0/0. Any positive threshold under a visible fraction of a pixel behaves
+// the same (at that length the mark IS its cap); this was `1e-3` in dotplot
+// and `1e-4` in the two others, and takes the majority spelling, which is also
+// the one leaving the fallback the smallest reach.
+public static const float CAPSULE_MIN_LEN_PX = 1e-4;
+
+// The segment's own frame — x along it, y across it. Cap-agnostic, which is
+// what lets the butt-capped linkedReadLine orient its diagonal through it. The
+// degenerate guard exists only to keep a zero-length segment's 0/0 out of the
+// frame.
+public struct CapsuleFrame {
+  public float2 tangent;
+  public float2 normal;
+};
+
+public CapsuleFrame capsuleFrame(float2 delta, float len) {
+  CapsuleFrame f;
+  f.tangent = len > CAPSULE_MIN_LEN_PX ? delta / len : float2(1.0, 0.0);
+  f.normal = float2(-f.tangent.y, f.tangent.x);
+  return f;
+}
+
+// Quad corner `vid` in the segment's frame, for a capsule of half-length
+// `halfLenPx` and stroke half-width `halfWidthPx`, grown by the pad the module
+// header describes. Center-anchored: ±(halfLen + ext) along, ±ext across.
+public float2 capsuleQuadLocal(
+  uint vid, float halfLenPx, float halfWidthPx, float dpr
+) {
+  float ext = halfWidthPx + aaHalfPx(dpr);
+  float2 q = quadLocal(vid) * 2.0 - 1.0;
+  return float2(q.x * (halfLenPx + ext), q.y * ext);
+}
+
+// CSS-px distance from `local` (the segment's frame, center-anchored) to the
+// segment {(-halfLen,0)..(halfLen,0)}. Collapses to distance-from-origin for a
+// degenerate segment — the circular dot of radius halfWidth.
+public float capsuleDist(float2 local, float halfLenPx) {
+  return length(float2(max(abs(local.x) - halfLenPx, 0.0), local.y));
+}

package/src/shaders/colorPack.slang

@@ -0,0 +1,26 @@
+// Shared color-packing helpers. A single `uint` holds an ABGR triplet as
+// packed bytes, letting every shader carry color data as one vertex
+// attribute instead of four floats. Pair with `cssColorToABGR` on the
+// CPU side (see packages/core/src/util/colorBits.ts).
+module colorPack;
+
+// Don't put a SCALAR array in a uniform block and unpack it with this.
+// slangc v2026.5.2's WGSL backend cannot compile it: a `uint palette[N]` member
+// becomes a `_Array_std140_uintN` wrapper (std140 pads each element to 16
+// bytes), and passing an element of one to a cross-module function SEGFAULTS the
+// compiler — signal 11, no diagnostic. `[ForceInline]` here dodges the crash and
+// then emits invalid WGSL (a bare `…data_0[i].x;` statement, which naga
+// rejects), so there is no version of it that works. GLSL compiles the same
+// source fine, so it is WGSL-specific.
+//
+// Declare such a palette as `float4[N]` instead — a vector element needs no
+// wrapper struct, lowers correctly, AND costs the same 16 bytes per slot that
+// std140 was padding the uint to anyway, so packing bought nothing here. Packing
+// still earns its keep in VERTEX ATTRIBUTES, which is what this is for.
+public float4 unpackRGBA(uint c) {
+  return float4(
+    float((c >>  0u) & 0xFFu),
+    float((c >>  8u) & 0xFFu),
+    float((c >> 16u) & 0xFFu),
+    float((c >> 24u) & 0xFFu)) / 255.0;
+}

package/src/shaders/colorRampLut.generated.ts

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from colorRampLut.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const RAMP_LUT_ENTRIES = 256

package/src/shaders/colorRampLut.slang

@@ -0,0 +1,51 @@
+// Sampling a 256×1 colour-ramp LUT texture by a [0,1] scalar — the mechanism
+// HiC's contact map and both LD heatmap variants reached independently, down to
+// the binding slot, and wiggle density's third spelling. The module owns ONLY
+// the sampling: each consumer keeps its own scale (`mapHicCount`, LD's signed
+// remap plus `ldValueComputed` sentinel gate, wiggle's `normalizeScore` +
+// `densityGradientT`) and declares its own `[[vk::binding(2, 0)]]
+// Sampler2D<float4> colorRamp;` — a module can take a sampler as a parameter
+// but not declare the binding for its importer. The TS half of the mechanism is
+// `uploadColorRampLut` (../colorRampLut.ts), which puts the 256-entry
+// `Uint8Array` behind these samplers; `buildColorRampLut`
+// (@jbrowse/core/util/colorRamp) is what builds it on both backends.
+//
+// Two entry points because premultiplication follows the consumer's declared
+// blend, and the `//! blend:` declaration stays per-shader: HiC and LD both
+// draw under `//! blend: premultiplied` and both multiplied the sample through
+// its own alpha, so that shared line lives here rather than surviving as a
+// copy in each fragment — while wiggle density draws opaque ramps under the
+// default straight-alpha blend, where a premultiplied return would be wrong
+// the day a translucent ramp entry appears. The function name carries the
+// contract, so a consumer picks the form that matches its blend declaration.
+//! export-consts: RAMP_LUT_ENTRIES
+module colorRampLut;
+
+// Entries in the ramp texture. Exported because `buildColorRampLut` sizes the
+// array by it and the mapping below divides by it: a table built to one number
+// and sampled by another is a half-shade of drift at every entry.
+public static const float RAMP_LUT_ENTRIES = 256.0;
+
+// The colour at `t` in [0, 1], straight (non-premultiplied) alpha. Sampled at
+// the texture's vertical center, mip level 0 — the ramp has no other row and no
+// other level.
+//
+// `t` is remapped into texel space rather than passed through. The builder
+// defines entry i as the colour at `i / (N - 1)`, while a linear-filtered
+// texture puts entry i's center at `(i + 0.5) / N`, so sampling at `t` returns
+// a blend of two neighbours at every entry but the ends — half a step off the
+// table the Canvas2D and SVG twins index. `clamp` lands an out-of-range scalar
+// on the end entry, which clamp-to-edge addressing also answers.
+public float4 rampColor(Sampler2D<float4> ramp, float t) {
+  float u = (clamp(t, 0.0, 1.0) * (RAMP_LUT_ENTRIES - 1.0) + 0.5) / RAMP_LUT_ENTRIES;
+  return ramp.SampleLevel(float2(u, 0.5), 0.0);
+}
+
+// The same sample with its colour multiplied through its alpha, for a fragment
+// returned under `//! blend: premultiplied`. Alpha itself is unchanged, so a
+// consumer's own alpha test (HiC's MIN_VISIBLE_ALPHA discard) reads the same
+// number either side of this call.
+public float4 rampColorPremultiplied(Sampler2D<float4> ramp, float t) {
+  float4 c = rampColor(ramp, t);
+  return float4(c.rgb * c.a, c.a);
+}

package/src/shaders/coverageBand.generated.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from coverageBand.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const TRIANGLE_HW = 3.5
+
+export const TRIANGLE_H = 4.5