@jbrowse/render-core 4.3.0

package/src/shaders/glyphEdgeAlpha.test.ts

@@ -0,0 +1,241 @@
+// `glyphEdgeAlpha` (antialias.slang) sizes the antialiasing ramp on a glyph's
+// edge from the SDF's own gradient, so that one ramp covers one output pixel for
+// every shape the Manhattan and wiggle point modes draw. Two things have to hold
+// for that, and neither is checked by the compiler:
+//
+//   1. The gradient really is what the reasoning assumes. Unit for the disc and
+//      for each of the triangle's three edges — but NOT for the diamond, whose
+//      `1 - (|x| + |y|)` is the L1 norm and therefore sqrt(2) times the true
+//      perpendicular distance to its edge. That sqrt(2) is exactly why the ramp
+//      is measured rather than assumed, and a shape added later with its own
+//      scaling would be silently mis-sized by any constant.
+//
+//   2. The ramp fits in the pad the quad leaves it. `discExpand` grows the quad
+//      by aaHalfPx(dpr) CSS px past the glyph edge; a ramp reaching further is
+//      clipped by the rasterizer and the fade ends on a hard edge. This is what
+//      the previous `fwidth`-as-half-width spelling got wrong, and it got it
+//      wrong worst on the diagonals, where fwidth overshoots most.
+//
+// The shader isn't unit-testable, so this models it. Same approach, and same
+// reason, as LinearSyntenyDisplay/shaders/syntenyFillPad.test.ts and
+// DotplotDisplay/shaders/dotplotCapsulePad.test.ts.
+// SYNC: keep in step with antialias.slang's glyphEdgeAlpha and with the SDFs
+// in manhattan.slang.
+import { aaHalfPx } from './antialias.js.generated.ts'
+
+const INV_SQRT5 = 1 / Math.sqrt(5)
+
+// The four SDFs manhattan.slang selects between, over quad-local `p`. Positive
+// inside, zero on the edge. SHAPE_BAR's constant 1 is the degenerate case the
+// ramp's floor exists for.
+const SDFS = {
+  disc: (x: number, y: number) => 1 - Math.hypot(x, y),
+  diamond: (x: number, y: number) => 1 - (Math.abs(x) + Math.abs(y)),
+  triangle: (x: number, y: number) =>
+    Math.min(1 - y, (2 * x + y + 1) * INV_SQRT5, (-2 * x + y + 1) * INV_SQRT5),
+  bar: () => 1,
+} as const
+
+// |grad sdf| per unit of p, centrally differenced. Away from creases this is the
+// exact analytic gradient.
+function gradMag(sdf: (x: number, y: number) => number, x: number, y: number) {
+  const h = 1e-6
+  return Math.hypot(
+    (sdf(x + h, y) - sdf(x - h, y)) / (2 * h),
+    (sdf(x, y + h) - sdf(x, y - h)) / (2 * h),
+  )
+}
+
+// Points ON each shape's edge, parameterised so the sweep covers every facing —
+// including the diagonals, which is where fwidth overshot and where the disc's
+// quad has least room to spare.
+function edgePoints(shape: keyof typeof SDFS, n = 64): [number, number][] {
+  const out: [number, number][] = []
+  for (let i = 0; i < n; i++) {
+    // Half-offset so no sample lands on an axis, i.e. on one of the diamond's
+    // four corners — `|y|` has a kink at y = 0, so a central difference there
+    // reports a gradient of 1 rather than the facet's sqrt(2). The corners are a
+    // property of the shape, not of the ramp, and the shader meets them on 1-2
+    // pixels per glyph.
+    const a = ((i + 0.5) / n) * Math.PI * 2
+    const c = Math.cos(a)
+    const s = Math.sin(a)
+    if (shape === 'disc') {
+      out.push([c, s])
+    } else if (shape === 'diamond') {
+      // scale the ray to the L1 unit ball
+      const k = 1 / (Math.abs(c) + Math.abs(s))
+      out.push([c * k, s * k])
+    } else if (shape === 'triangle') {
+      // walk the three edges rather than a ray, so corners are approached but
+      // the samples themselves stay on a single facet
+      const t = (i / n) * 3
+      const seg = Math.floor(t)
+      const f = 0.08 + (t - seg) * 0.84 // keep clear of the creases
+      const verts: [number, number][] = [
+        [-1, 1],
+        [1, 1],
+        [0, -1],
+      ]
+      const [ax, ay] = verts[seg]!
+      const [bx, by] = verts[(seg + 1) % 3]!
+      out.push([ax + (bx - ax) * f, ay + (by - ay) * f])
+    }
+  }
+  return out
+}
+
+const RADII_PX = [1.5, 2, 4, 10]
+const DPRS = [1, 2]
+
+describe('glyph SDF gradients', () => {
+  test('the disc and the triangle carry unit gradients', () => {
+    for (const [x, y] of edgePoints('disc')) {
+      expect(gradMag(SDFS.disc, x, y)).toBeCloseTo(1, 5)
+    }
+    for (const [x, y] of edgePoints('triangle')) {
+      expect(gradMag(SDFS.triangle, x, y)).toBeCloseTo(1, 5)
+    }
+  })
+
+  test('the diamond does not — its L1 norm carries sqrt(2)', () => {
+    // The trap a hard-coded ramp width would fall into: this SDF reports a
+    // distance sqrt(2) times the true perpendicular one, so a constant sized for
+    // the disc would make the diamond's edge sqrt(2) too soft.
+    for (const [x, y] of edgePoints('diamond')) {
+      expect(gradMag(SDFS.diamond, x, y)).toBeCloseTo(Math.SQRT2, 5)
+    }
+  })
+
+  test('the bar is constant, which is what the ramp floor is for', () => {
+    expect(gradMag(SDFS.bar, 0.3, -0.4)).toBe(0)
+    // max(0, 1e-5) is a positive ramp width, and a coverage of 1 over a ramp
+    // that narrow clamps to 1 — the solid fill SHAPE_BAR wants.
+    expect(Math.max(0, 1e-5)).toBeGreaterThan(0)
+  })
+})
+
+// The screen-space width of the ramp glyphEdgeAlpha produces, in DEVICE px, and
+// how far it reaches outside the glyph edge in CSS px.
+//
+// `p` units relate to pixels through the glyph's radius: |p| = 1 sits at
+// radiusPx CSS px from the center, so one device px is 1/(radiusPx*dpr) of p.
+function rampGeometry(
+  sdf: (x: number, y: number) => number,
+  x: number,
+  y: number,
+  radiusPx: number,
+  dpr: number,
+  // how the shader turns its measured derivative into the ramp's half-width.
+  // `aaRamp` takes the measurement as the FULL ramp width, so the half is half
+  // of it; the retired spelling used fwidth's overshooting value as the half.
+  halfRampOf = (measuredPerDevicePx: number) => 0.5 * measuredPerDevicePx,
+  // what the shader differentiates WITH. These are two separate quantities and
+  // conflating them is what hides the bug: the ramp's width in coverage units
+  // comes from whatever the shader measured, but converting that back to a
+  // screen distance is the TRUE gradient's job. Divide by the measured value and
+  // fwidth's overshoot cancels itself out and looks correct.
+  measure = gradMag,
+) {
+  const trueG = gradMag(sdf, x, y)
+  const pPerDevicePx = 1 / (radiusPx * dpr)
+  const halfRamp = halfRampOf(measure(sdf, x, y) * pPerDevicePx)
+  // Back to screen distance: coverage changes by trueG per unit of p, so the
+  // half-ramp spans halfRamp/trueG of p, i.e. that times radiusPx CSS px.
+  const halfRampCssPx = (halfRamp / trueG) * radiusPx
+  return { widthDevicePx: 2 * halfRampCssPx * dpr, reachCssPx: halfRampCssPx }
+}
+
+// fwidth = |ddx| + |ddy|, which is what the retired spelling measured with.
+function fwidthMag(
+  sdf: (x: number, y: number) => number,
+  x: number,
+  y: number,
+) {
+  const h = 1e-6
+  return (
+    Math.abs((sdf(x + h, y) - sdf(x - h, y)) / (2 * h)) +
+    Math.abs((sdf(x, y + h) - sdf(x, y - h)) / (2 * h))
+  )
+}
+
+describe('glyphEdgeAlpha ramp', () => {
+  test.each(['disc', 'diamond', 'triangle'] as const)(
+    'is exactly one output pixel wide all the way round: %s',
+    shape => {
+      for (const [x, y] of edgePoints(shape)) {
+        for (const radiusPx of RADII_PX) {
+          for (const dpr of DPRS) {
+            const { widthDevicePx } = rampGeometry(
+              SDFS[shape],
+              x,
+              y,
+              radiusPx,
+              dpr,
+            )
+            expect(widthDevicePx).toBeCloseTo(1, 6)
+          }
+        }
+      }
+    },
+  )
+
+  // EQUALS, not "fits inside". The measured ramp reaches exactly half an output
+  // pixel past the edge whatever the shape — that is what taking the gradient
+  // buys — so the pad `discExpand` leaves is knowable exactly, and a pad merely
+  // big enough is one nobody can tell from a pad four times too big. `<=` held
+  // for any constant at or above 0.5 and is how a flat 1.0 CSS px survived.
+  test.each(['disc', 'diamond', 'triangle'] as const)(
+    'the pad discExpand leaves is exactly the ramp reach: %s',
+    shape => {
+      for (const [x, y] of edgePoints(shape)) {
+        for (const radiusPx of RADII_PX) {
+          for (const dpr of DPRS) {
+            const { reachCssPx } = rampGeometry(
+              SDFS[shape],
+              x,
+              y,
+              radiusPx,
+              dpr,
+            )
+            expect(reachCssPx).toBeCloseTo(aaHalfPx(dpr), 9)
+          }
+        }
+      }
+    },
+  )
+
+  test('fwidth as a half-width was both too wide and clipped (do not reintroduce)', () => {
+    // The retired spelling, on the worst facing it has: a disc's 45-degree
+    // point, at dpr 1. fwidth reads sqrt(2) there instead of 1, and was then
+    // used whole as the half-width.
+    const diag = Math.SQRT1_2
+    const retired = rampGeometry(
+      SDFS.disc,
+      diag,
+      diag,
+      4,
+      1,
+      g => g, // used whole, not halved
+      fwidthMag,
+    )
+    expect(retired.widthDevicePx).toBeCloseTo(2 * Math.SQRT2, 6)
+    expect(retired.reachCssPx).toBeGreaterThan(aaHalfPx(1))
+
+    // and on an axis-aligned facing it was merely 2x too wide, which is what
+    // made the fade vary with position around one circle.
+    const axis = rampGeometry(SDFS.disc, 1, 0, 4, 1, g => g, fwidthMag)
+    expect(axis.widthDevicePx).toBeCloseTo(2, 6)
+    expect(retired.widthDevicePx / axis.widthDevicePx).toBeCloseTo(
+      Math.SQRT2,
+      6,
+    )
+
+    // both are one pixel now, at every facing
+    expect(rampGeometry(SDFS.disc, diag, diag, 4, 1).widthDevicePx).toBeCloseTo(
+      1,
+      6,
+    )
+    expect(rampGeometry(SDFS.disc, 1, 0, 4, 1).widthDevicePx).toBeCloseTo(1, 6)
+  })
+})

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

@@ -0,0 +1,47 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from hpmath.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of hpmath.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+export function snapBoxHeightPx(heightPx: number): number {
+  let hPx = Math.floor((heightPx + 0.5))
+  let _t0: boolean
+  if (((hPx - (2.0 * Math.floor((hPx * 0.5)))) == 0.0)) {
+    _t0 = (hPx >= 2.0)
+  } else {
+    _t0 = false
+  }
+  if (_t0) {
+    _t0 = (hPx <= 4.0)
+  } else {
+    _t0 = false
+  }
+  let _t1: number
+  if (_t0) {
+    _t1 = (hPx + 1.0)
+  } else {
+    _t1 = hPx
+  }
+  return _t1
+}
+
+export function snapBoxCenterYPx(centerY: number, heightPx: number, scrollY: number): number {
+  return ((Math.floor((((centerY - (heightPx * 0.5)) - scrollY) + 0.5)) + Math.floor((snapBoxHeightPx(heightPx) * 0.5))) + 0.5)
+}
+
+export function extendToMinWidthPx(x1: number, x2: number, minWidth: number): number {
+  let dx = (x2 - x1)
+  let _t0: number
+  if ((Math.abs(dx) < minWidth)) {
+    if ((dx < 0.0)) {
+      _t0 = -minWidth
+    } else {
+      _t0 = minWidth
+    }
+    _t0 = (x1 + _t0)
+  } else {
+    _t0 = x2
+  }
+  return _t0
+}

package/src/shaders/hpmath.slang

@@ -0,0 +1,226 @@
+// Shared high-precision genome-coordinate math. HP technique from genome-spy
+// (MIT): https://github.com/genome-spy/genome-spy
+//
+// Imported via `import hpmath;` from shaders that need sub-pixel-accurate
+// conversion of base-pair positions to clip space when zoomed far in.
+//
+// The `js-export` set is the px-space *decisions* the Canvas2D and SVG paths
+// must make identically to the GPU — which pixel row a glyph centers on, how a
+// sub-pixel span is widened. `pnpm gen:shaders` transliterates them into
+// hpmath.js.generated.ts; nothing downstream re-derives them by hand.
+//! js-export: snapBoxHeightPx, snapBoxCenterYPx, extendToMinWidthPx
+//! js-skip: hpSplitUint — the hi/lo float32 precision split exists because a GPU has no float64; the Canvas2D path just uses a number
+//! js-skip: quadLocal — maps a vertex id to a quad corner — Canvas2D has no vertices, it calls fillRect
+//! js-skip: yPxToClipY — clip space is the GPU coordinate system; the px-space decision it wraps is what gets exported (snapBoxCenterYPx and friends)
+//! js-skip: clipXToPx — the x half of the same clip-space conversion, and the reason a px decision can be written once — nothing outside a shader is in clip space
+//! js-skip: pxToClipX — the inverse of clipXToPx, same reason
+//! js-skip: pxToClipLen — the length half of the same conversion; a px dimension is already in px on the Canvas2D side, so there is nothing to convert
+//! js-skip: clipLenToPx — the inverse of pxToClipLen, same reason
+//! js-skip: extendToMinWidthX — clip-space wrapper over the exported extendToMinWidthPx, which is the decision
+//! js-skip: expandToMinWidthPx — the midpoint rule has no Canvas2D counterpart: the pileup floors a cell width one-sidedly and adds a seam fudge the shader deliberately omits (rendererTypes.ts pileupCellWidth), and the variant matrix floors in physical px against a canvas the Canvas2D twin sizes itself. A different rule, not a twin
+//! js-skip: expandToMinWidthX — clip-space wrapper over expandToMinWidthPx, same reason as extendToMinWidthX
+//! js-skip: snapToPixelX — clip in, clip out; its px core is `floor(x + 0.5)`, which is Math.round and needs no twin
+//! js-skip: snapBoxCenterY — clip-space wrapper over the exported snapBoxCenterYPx
+module hpmath;
+
+public static const uint HP_LOW_MASK = 0xFFFu;
+
+public float2 hpSplitUint(uint value) {
+  uint lo = value & HP_LOW_MASK;
+  uint hi = value - lo;
+  return float2(float(hi), float(lo));
+}
+
+// `max(-inf)` and `dot()` exist to thwart the compiler — without them it
+// collapses (hi_a+lo_a)-(hi_b+lo_b) into one large subtraction and the
+// float32 precision the hi/lo split exists to preserve is gone. `hpZero` is
+// a tiny CPU-supplied number; `-1/hpZero` is smaller than any real diff.
+public float hpToClipX(float2 splitPos, float3 bpRange, float hpZero) {
+  float inf = 1.0 / hpZero;
+  float step = 2.0 / bpRange.z;
+  float hi = max(splitPos.x - bpRange.x, -inf);
+  float lo = max(splitPos.y - bpRange.y, -inf);
+  return dot(float3(-1.0, hi, lo), float3(1.0, step, step));
+}
+
+public float hpScaleLinear(float2 splitPos, float3 bpRange, float hpZero) {
+  float inf = 1.0 / hpZero;
+  float step = 1.0 / bpRange.z;
+  float hi = max(splitPos.x - bpRange.x, -inf);
+  float lo = max(splitPos.y - bpRange.y, -inf);
+  return dot(float2(hi, lo), float2(step, step));
+}
+
+// Exact-as-possible bp offset from a split position to the viewport start
+// stored in bpRange.xy. Subtracts the hi/lo components separately (same
+// ordering as hpToClipX) so the result stays precise at high genomic
+// coordinates — recombining bpStartHi+bpStartLo first would lose ~256bp near
+// 3e9. Unlike hpToClipX this returns bp, not clip space.
+public float hpViewportOffsetBp(float2 splitPos, float3 bpRange) {
+  return (bpRange.x - splitPos.x) + (bpRange.y - splitPos.y);
+}
+
+public float snapToPixelX(float clipX, float canvasWidth) {
+  float px = (clipX + 1.0) * 0.5 * canvasWidth;
+  return floor(px + 0.5) / canvasWidth * 2.0 - 1.0;
+}
+
+public float yPxToClipY(float yPx, float canvasHeight) {
+  return 1.0 - (yPx / canvasHeight) * 2.0;
+}
+
+// Tallest box that gets the odd-height nudge below. Above this a half-pixel of
+// asymmetry is a small fraction of the box and invisible; at 2px it is half of
+// it, so the exons appear to float above their intron line.
+public static const float THIN_BOX_PX = 4.0;
+
+// The pixel height a box is drawn at: its rounded height, except that a THIN box
+// with an EVEN height is nudged up to the next odd one. A box spanning an even
+// number of rows has no middle ROW — its center falls on the seam between two —
+// so the 1px glyphs that ride on it (intron line, chevrons, strand arrow) can
+// only ever sit half a pixel off center, which at the 2px bodies fit mode
+// squeezes down to reads as the exons sitting above the intron line. An odd
+// height gives the box a true center row for them to land on. The extra pixel
+// can't reach the row below: the packer quantizes row tops to a pitch of at
+// least twice the body height at these sizes (see layout.ts pitchY).
+// A height that rounds to 0 is left at 0: it draws nothing, and nothing is what
+// a caller asking for a zero-height box wants.
+public float snapBoxHeightPx(float heightPx) {
+  float hPx = floor(heightPx + 0.5);
+  bool even = hPx - 2.0 * floor(hPx * 0.5) == 0.0;
+  return even && hPx >= 2.0 && hPx <= THIN_BOX_PX ? hPx + 1.0 : hPx;
+}
+
+// Center a thin glyph on the *drawn* middle row of the box it annotates, given
+// the box's real center `centerY` and height `heightPx`. The box is rasterized
+// with the rect shader's edge snapping (top = floor(top+0.5), height =
+// snapBoxHeightPx(h)); reproducing that here lands the line/chevron exactly on
+// the box's center row instead of the ~1px bias a plain pixel-center snap
+// (`floor(centerY - scrollY + 0.5) + 0.5`) gives. Thin boxes are drawn at an odd
+// height precisely so that center row exists; a taller even box still has none,
+// and stays consistent (just below the seam).
+//
+// Split in two on purpose. The decision — which pixel row is the center — is
+// resolution math the Canvas2D and SVG paths need in *screen px*; only the
+// clip-space conversion is GPU-specific. `//! js-export` lifts the px half into
+// TypeScript, so the two backends share the rule instead of the Canvas2D twin
+// re-deriving it (see adr-051). Keep new shared decisions in this shape: pure
+// px-in/px-out below, the `yPxToClipY` wrapper above it.
+public float snapBoxCenterYPx(float centerY, float heightPx, float scrollY) {
+  float topPx = floor(centerY - heightPx * 0.5 - scrollY + 0.5);
+  return topPx + floor(snapBoxHeightPx(heightPx) * 0.5) + 0.5;
+}
+
+public float snapBoxCenterY(
+  float centerY, float heightPx, float scrollY, float canvasHeight
+) {
+  return yPxToClipY(snapBoxCenterYPx(centerY, heightPx, scrollY), canvasHeight);
+}
+
+// Extend the free edge `x2` away from the anchor `x1` so the span is at least
+// `minWidthPx` CSS px wide, returning the new x2. Sub-pixel-narrow features (a
+// 1bp rect, a zoomed-out coverage bin) still paint instead of vanishing.
+//
+// Orientation-preserving on purpose: reversal is baked into bpRangeX (negated
+// length), so x2 < x1 on reversed blocks and the span must grow in the sign
+// direction of dx. Widening toward +x would flip the quad on reversed regions.
+// Contrast `expandToMinWidthPx` below, which moves both edges about the
+// midpoint — that one is for spans with no anchored edge.
+// Unit-agnostic core: `minWidth` is in whatever space x1/x2 are. Canvas2D calls
+// this directly in screen px (paired with `spanLeft`, which owns the fill-x
+// pivot); the clip-space wrapper below converts the px floor first. Same split
+// as snapBoxCenterYPx — the rule is shared, the coordinate space is not.
+public float extendToMinWidthPx(float x1, float x2, float minWidth) {
+  float dx = x2 - x1;
+  return abs(dx) < minWidth ? x1 + (dx < 0.0 ? -minWidth : minWidth) : x2;
+}
+
+public float extendToMinWidthX(
+  float x1, float x2, float minWidthPx, float canvasWidth
+) {
+  return extendToMinWidthPx(x1, x2, minWidthPx * 2.0 / canvasWidth);
+}
+
+// The other min-width rule: widen a [x1, x2] span about its MIDPOINT, so both
+// edges move. For a span with no anchored edge — a coverage bin, a gap, an
+// insertion bar, a variant-matrix column — where growing off one side would
+// slide the mark away from the coordinate it reports.
+//
+// Not orientation-preserving, and deliberately not: the callers here hand it an
+// already-ordered span. `x2 - x1 < minWidth` rather than `abs(...)` means a
+// span given backwards is always widened and comes back forwards.
+//
+// Same px-core/clip-wrapper split as `extendToMinWidthPx` above, and here it is
+// what lets the alignments passes (clip space, a 1 CSS px floor) and the variant
+// matrix (physical px, its own MIN_COL_PX) run one rule instead of two spellings
+// of it.
+public float2 expandToMinWidthPx(float x1, float x2, float minWidth) {
+  if (x2 - x1 < minWidth) {
+    float mid = (x1 + x2) * 0.5;
+    return float2(mid - minWidth * 0.5, mid + minWidth * 0.5);
+  }
+  return float2(x1, x2);
+}
+
+public float2 expandToMinWidthX(
+  float x1, float x2, float minWidthPx, float canvasWidth
+) {
+  return expandToMinWidthPx(x1, x2, minWidthPx * 2.0 / canvasWidth);
+}
+
+// vid%6: 0→(0,0)  1→(1,0)  2→(0,1)  3→(0,1)  4→(1,0)  5→(1,1)
+public float2 quadLocal(uint vid) {
+  uint v = vid % 6u;
+  return float2(
+    (v == 0u || v == 2u || v == 3u) ? 0.0 : 1.0,
+    (v == 0u || v == 1u || v == 4u) ? 0.0 : 1.0
+  );
+}
+
+// Screen-space (CSS px, top-left origin) → clip space, with the Y flip. Shared
+// by the synteny/dotplot/hic renderers, whose 2D marks all map a screen-px
+// point onto the viewport this way; keeps the flip sign from drifting between
+// the plugins that previously open-coded it. (Appended after quadLocal on
+// purpose: inserting earlier reshuffles every importer's debug #line numbers.)
+public float4 screenToClip(float2 screen, float2 resolution) {
+  float2 clip = screen / resolution * 2.0 - 1.0;
+  return float4(clip.x, -clip.y, 0.0, 1.0);
+}
+
+// The x pair of `yPxToClipY`/its inverse: clip x ↔ screen px across the span
+// clip [-1,1] covers. `canvasWidth` is whatever width that span means for the
+// caller — for the LGV glyph passes it is the block's scissored width, not the
+// canvas (see FeatureGlyphUniforms.canvasWidth).
+//
+// These exist so a horizontal decision can be written once in px and used from
+// clip space, the way `snapBoxCenterYPx` already is vertically:
+// `pxToClipX(decide(clipXToPx(a), clipXToPx(b)), w)`. `snapToPixelX` above is
+// that sandwich with `floor(x + 0.5)` in the middle — the round trip is
+// arithmetic it was already doing internally, so spelling a decision this way
+// costs no precision. (Appended, per the note on screenToClip.)
+public float clipXToPx(float clipX, float canvasWidth) {
+  return (clipX + 1.0) * 0.5 * canvasWidth;
+}
+
+public float pxToClipX(float xPx, float canvasWidth) {
+  return xPx / canvasWidth * 2.0 - 1.0;
+}
+
+// The LENGTH pair, as against the POSITION pair above: clip spans 2 units
+// across `size`, so a px span is `px * 2 / size` with no origin term. `size` is
+// the canvas width or height, or whatever span clip [-1,1] covers for the
+// caller — the same argument `clipXToPx` and `yPxToClipY` take.
+//
+// Spell every px dimension through these. Writing `HALF_W_PX / u.canvasWidth`
+// gives the same number but folds the /2 into the conversion, so the constant
+// reads as a full width while meaning a half one; and `TRIANGLE_HW * 2.0 * 2.0
+// / u.canvasW` (indicator.slang, before this existed) leaves a reader to work
+// out which 2.0 doubles the half-width and which one is the clip span.
+// (Appended, per the note on screenToClip.)
+public float pxToClipLen(float px, float size) {
+  return px * 2.0 / size;
+}
+
+public float clipLenToPx(float clipLen, float size) {
+  return clipLen * 0.5 * size;
+}

package/src/shaders/pointGlyph.generated.ts

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

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

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from pointGlyph.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of pointGlyph.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+export function crispSquareTopLeftPx(centerPx: number, diameterPx: number): number {
+  return Math.floor(((centerPx - (diameterPx * 0.5)) + 0.5))
+}

package/src/shaders/pointGlyph.slang

@@ -0,0 +1,93 @@
+// Shared scatter-point glyph math for the wiggle and Manhattan renderers, whose
+// point mode draws the same antialiased disc. Factored here so the disc SDF and
+// the "small point → crisp square" / AA-pad thresholds can't drift between the
+// two shaders (they previously redeclared identical consts with "must match"
+// comments pointing at each other).
+//
+// The CPU side keeps no copy of either the threshold or the snap:
+// `export-consts` emits the constant and `js-export` emits the snap, both
+// consumed by `pointMarker.ts` (adr-051).
+//! export-consts: SMALL_POINT_MAX_DIAMETER
+//! js-export: crispSquareTopLeftPx
+//! js-skip: discExpand — expands a quad so the fragment AA ramp is not clipped; Canvas2D draws ctx.arc and has no quad to expand
+module pointGlyph;
+
+import antialias;
+import hpmath;
+
+// A disc's edge is ramped by `glyphEdgeAlpha`, whose width is one OUTPUT pixel
+// measured in the SDF's own units — so in CSS px the ramp reaches `aaHalfPx`
+// past the boundary and the quad has to grow by exactly that.
+//
+// This was a flat 1.0 under a comment calling it device px while both consumers
+// added it in CSS px: 2x the reach at dpr 1 and 4x at dpr 2, every surplus
+// fragment shading to alpha 0. A pad is the one place the two units cannot be
+// swapped without anyone seeing.
+
+// At/below this diameter an AA disc reads as a muddy blob, so callers draw a
+// crisp filled square instead.
+public static const float SMALL_POINT_MAX_DIAMETER = 3.0;
+
+// Quad scale factor that grows the disc's bounding quad by the ramp's reach so
+// its faded edge isn't clipped. localPos is scaled by the same factor so the
+// disc boundary stays at distance 1 (see discAlpha). `max(radiusPx, 0.5)` keeps
+// sub-pixel points from exploding the expansion.
+public float discExpand(float radiusPx, float dpr) {
+  return (radiusPx + aaHalfPx(dpr)) / max(radiusPx, 0.5);
+}
+
+// Pixel-grid-snapped top-left of the crisp small-point square, on one axis. The
+// snap (round-half-up) is what makes the square's fill land on whole pixels
+// instead of AA-blurring across columns/rows — it is SHAPE_SOLID with no
+// fragment-side AA, so an unsnapped center reads as a fuzzy blob.
+//
+// Per-axis and scalar so `//! js-export` can lift it: Canvas2D's
+// `appendPointMarker` calls this for x and y rather than re-deriving the snap
+// (adr-051). The float2 wrapper below keeps the shader's call site unchanged.
+public float crispSquareTopLeftPx(float centerPx, float diameterPx) {
+  return floor(centerPx - diameterPx * 0.5 + 0.5);
+}
+
+// Screen-px position of quad corner `q` (each component 0 or 1) for the crisp
+// small-point square, given the marker center and diameter in px.
+public float2 crispSquareCornerPx(float2 centerPx, float diameterPx, float2 q) {
+  float2 topLeft = float2(
+    crispSquareTopLeftPx(centerPx.x, diameterPx),
+    crispSquareTopLeftPx(centerPx.y, diameterPx)
+  );
+  return topLeft + q * diameterPx;
+}
+
+// The same corner in clip space, for a marker whose centre arrives as a clip x
+// and a screen y — which is how both callers hold it, since x comes off the hp
+// bp conversion and y off a score scale.
+//
+// The round trip is the point: the snap has to happen in px, so the caller
+// converts out and back, and doing that in each of the two shaders is two
+// chances to convert one of the four edges differently. `viewportWidth` and
+// `canvasHeight` are whatever spans clip [-1,1] covers for the caller.
+public float4 crispSquareCornerClip(
+  float centerClipX, float centerYPx, float diameterPx, float2 q,
+  float viewportWidth, float canvasHeight
+) {
+  float2 centerPx = float2(clipXToPx(centerClipX, viewportWidth), centerYPx);
+  float2 vPx = crispSquareCornerPx(centerPx, diameterPx, q);
+  return float4(pxToClipX(vPx.x, viewportWidth),
+                yPxToClipY(vPx.y, canvasHeight), 0.0, 1.0);
+}
+
+// Disc SDF, positive inside. localPos is the expanded quad-local coord
+// (-expand..expand); the disc boundary sits at distance 1, so the SDF is
+// `1 - length`. Exposed separately for shaders that select between several
+// glyph SDFs and take the AA derivative once afterwards — WGSL only allows
+// derivatives in uniform control flow, so they can't call discAlpha inside a
+// branch on a varying.
+public float discCoverage(float2 localPos) {
+  return 1.0 - length(localPos);
+}
+
+// Antialiased disc coverage → alpha, for callers that draw only a disc and can
+// take the derivative inline. Only call from uniform control flow.
+public float discAlpha(float2 localPos) {
+  return glyphEdgeAlpha(discCoverage(localPos));
+}

package/src/shaders/rowRect.generated.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from rowRect.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const MIN_DRAWN_ROW_PX = 1
+
+export const MIN_DRAWN_CELL_PX = 1
+
+export const MULTI_ROW_MIN_CELL_PX = 2

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

@@ -0,0 +1,17 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from rowRect.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of rowRect.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+function _max(a: number, b: number) {
+  return b > a || Number.isNaN(a) ? b : a
+}
+
+export function drawnRowHeightPx(rowHeight: number, rowProportion: number): number {
+  return _max((rowHeight * rowProportion), 1.0)
+}
+
+export function rowBandOffsetPx(rowHeight: number, rowProportion: number): number {
+  return ((rowHeight - drawnRowHeightPx(rowHeight, rowProportion)) * 0.5)
+}