@unpunnyfuns/d3-blockmap 0.1.0 → 0.2.0

package/dist/{chunk-WIDC3EN2.js → chunk-6BBJWE5O.js}

@@ -5,53 +5,71 @@ import { tickStep } from "d3-array";
 var BITS_PER_BYTE = 8;
 var BYTE_SHIFT = 3;
 var BYTE_MASK = 7;
+var FULL_BYTE = 255;
 var BYTES_PER_PIXEL = 4;
 var OPAQUE_ALPHA = 255;
 var COLOR_TABLE_SIZE = 256;
+var CANVAS_ROWS = 1;
 var PERCENT = 100;
 var PERCENT_FRACTION_DIGITS = 1;
 var TOOLTIP_OFFSET_PX = 8;
-var CANVAS_ROWS = 1;
 var CSS_VAR_MISSING = "--blockmap-missing";
 var CSS_VAR_PARTIAL_LOW = "--blockmap-partial-low";
 var CSS_VAR_PARTIAL_HIGH = "--blockmap-partial-high";
 var CSS_VAR_PARTIAL = "--blockmap-partial";
 var CSS_VAR_COMPLETE = "--blockmap-complete";
 var CSS_VAR_HIGHLIGHT = "--blockmap-highlight";
-var REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
-var ZOOM_STEP = 1.25;
-var DRAG_THRESHOLD_PX = 3;
-var BLINK_INTERVAL_MS = 500;
-var MIN_VIEW_LENGTH = 1;
+var CSS_VAR_BRUSH = "--blockmap-brush";
 var DEFAULT_THEME = {
   missing: "#2b2b2b",
   partialLow: "#5b3a00",
   partialHigh: "#e0a500",
   partial: "#e0a500",
   complete: "#2ecc71",
-  highlight: "#ff4d4f"
+  highlight: "#ff4d4f",
+  brush: "#ffffff"
 };
+var BRUSH_FILL_OPACITY = 0.3;
 var THEME_ATTRIBUTES = ["class", "style", "data-theme"];
 var DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
-var RANGE_PAIR = 2;
-var FULL_BYTE = 255;
-var MAX_BLOCKS = 4294967295;
+var ZOOM_STEP = 1.25;
+var DRAG_THRESHOLD_PX = 3;
+var BLINK_INTERVAL_MS = 500;
+var REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+var MIN_VIEW_LENGTH = 1;
+var KEY_PAN_FRACTION = 0.1;
+var KEY_PAN_FRACTION_FAST = 0.5;
+var ARIA_LABEL_DEFAULT_PERCENT_DIGITS = 0;
+var ARIA_ROLEDESCRIPTION = "zoomable block map";
+var ARIA_KEYSHORTCUTS = "Plus - ArrowLeft ArrowRight Home";
 var CSS_VAR_AXIS_COLOR = "--blockmap-axis-color";
 var TICK_SPACING_PX = 80;
 var MIN_TICKS = 2;
 var EDGE_ANCHOR_RATIO = 0.5;
 var DECIMAL_BASE = 10;
+var RANGE_PAIR = 2;
+var MAX_BLOCKS = 4294967295;
 
 // src/dom.ts
 var ensureRelative = (container) => {
   const position = getComputedStyle(container).position;
   if (position === "static" || !position) container.style.position = "relative";
 };
+var canvasX = (canvas, event) => event.clientX - canvas.getBoundingClientRect().left;
 
 // src/view.ts
 var fullView = (totalBlocks) => ({ start: 0, end: totalBlocks });
 var viewLength = (view) => view.end - view.start;
 var sameView = (a, b) => a.start === b.start && a.end === b.end;
+var createScale = (view, cssWidth) => {
+  const length = viewLength(view);
+  return {
+    domain: [view.start, view.end],
+    range: [0, cssWidth],
+    x: (block) => cssWidth === 0 ? 0 : (block - view.start) / length * cssWidth,
+    block: (x) => cssWidth === 0 ? view.start : view.start + x / cssWidth * length
+  };
+};
 var clampView = (view, totalBlocks) => {
   let start = Math.round(Math.min(view.start, view.end));
   let end = Math.round(Math.max(view.start, view.end));
@@ -60,6 +78,7 @@ var clampView = (view, totalBlocks) => {
   start = Math.max(0, Math.min(start, totalBlocks - length));
   return { start, end: start + length };
 };
+var legalView = (view, totalBlocks) => Number.isFinite(view.start) && Number.isFinite(view.end) ? clampView(view, totalBlocks) : void 0;
 var zoomView = (view, anchor, factor, totalBlocks) => {
   const length = viewLength(view);
   const scaled = length * factor;
@@ -107,15 +126,6 @@ var defaultFormat = (block, step = 1) => {
   if (digits > MAX_COMPACT_FRACTION_DIGITS) return groupedFormat.format(block);
   return compactFormatterFor(digits).format(block);
 };
-var createScale = (view, cssWidth) => {
-  const length = viewLength(view);
-  return {
-    domain: [view.start, view.end],
-    range: [0, cssWidth],
-    x: (block) => cssWidth === 0 ? 0 : (block - view.start) / length * cssWidth,
-    block: (x) => cssWidth === 0 ? view.start : view.start + x / cssWidth * length
-  };
-};
 var computeTicks = (view, cssWidth, tickCount) => {
   if (cssWidth <= 0) return [];
   const count = tickCount ?? Math.max(MIN_TICKS, Math.floor(cssWidth / TICK_SPACING_PX));
@@ -155,6 +165,9 @@ var createAxis = (container, options) => {
   });
   container.append(root);
   return {
+    // Rebuilds every label on each update. There are only a handful of ticks,
+    // so a single replaceChildren beats diffing, and it cannot leave stale
+    // labels behind after a zoom.
     update: (view, cssWidth) => {
       const spans = computeTicks(view, cssWidth, options.tickCount).map((tick) => {
         const span = document.createElement("span");
@@ -179,6 +192,208 @@ var createAxis = (container, options) => {
   };
 };
 
+// src/bins.ts
+var discreteColumn = (block, length, binCount) => Math.floor(block * binCount / length);
+var discreteBlock = (column, length, binCount) => Math.ceil((column + 1) * length / binCount) - 1;
+var clipToView = (rawStart, rawEnd, viewStart, viewEnd) => [Math.max(rawStart, viewStart), Math.min(rawEnd, viewEnd)];
+var createBins = (view, binCount) => {
+  const { start: viewStart, end: viewEnd } = view;
+  const length = viewEnd - viewStart;
+  const counts = new Uint32Array(binCount);
+  const binOf = (index) => Math.floor((index - viewStart) * binCount / length);
+  const rangeOf = (bin) => [
+    viewStart + Math.ceil(bin * length / binCount),
+    viewStart + Math.ceil((bin + 1) * length / binCount)
+  ];
+  const sizeOf = (bin) => {
+    const [start, end] = rangeOf(bin);
+    return end - start;
+  };
+  return {
+    binCount,
+    counts,
+    binOf,
+    rangeOf,
+    sizeOf,
+    // Full recount from the bitset, used after a resize or a view change.
+    rebuild: (countInRange) => {
+      counts.fill(0);
+      if (binCount === 0) return;
+      for (let bin = 0; bin < binCount; bin += 1) {
+        const [start, end] = rangeOf(bin);
+        counts[bin] = countInRange(start, end);
+      }
+    },
+    /**
+     * Adds a wholly-new range's blocks to the bin counts without consulting
+     * the bitset: the first and last bins get the part of themselves the
+     * range covers, the bins between get their full size.
+     */
+    addRange: (rawStart, rawEnd) => {
+      const [start, end] = clipToView(rawStart, rawEnd, viewStart, viewEnd);
+      if (binCount === 0 || end <= start) return;
+      const first = binOf(start);
+      const last = binOf(end - 1);
+      if (first === last) {
+        counts[first] += end - start;
+        return;
+      }
+      counts[first] += rangeOf(first)[1] - start;
+      for (let bin = first + 1; bin < last; bin += 1) counts[bin] += sizeOf(bin);
+      counts[last] += end - rangeOf(last)[0];
+    },
+    // Which bins a range overlaps, so callers can mark exactly those dirty.
+    binsTouching: (rawStart, rawEnd) => {
+      const [start, end] = clipToView(rawStart, rawEnd, viewStart, viewEnd);
+      if (binCount === 0 || end <= start) return [];
+      const first = binOf(start);
+      const last = binOf(end - 1);
+      const touched = [];
+      for (let bin = first; bin <= last; bin += 1) touched.push(bin);
+      return touched;
+    },
+    recountBins: (bins, countInRange) => {
+      for (const bin of bins) {
+        const [start, end] = rangeOf(bin);
+        counts[bin] = countInRange(start, end);
+      }
+    }
+  };
+};
+
+// src/brush.ts
+import { brushX } from "d3-brush";
+import { select } from "d3-selection";
+var BRUSH_ATTRIBUTE = "data-blockmap-brush";
+var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+var SELECTION_CLASS = ".selection";
+var GESTURE_LISTENERS = "mousemove.brush mouseup.brush keydown.brush keyup.brush dragstart.drag selectstart.drag";
+var clamp = (value, max) => Math.max(0, Math.min(max, value));
+var toPixels = (selection, view, cssWidth) => {
+  if (cssWidth === 0) return null;
+  if (selection[1] <= view.start || selection[0] >= view.end) return null;
+  const scale = createScale(view, cssWidth);
+  return [clamp(scale.x(selection[0]), cssWidth), clamp(scale.x(selection[1]), cssWidth)];
+};
+var toBlocks = (pixels, view, cssWidth, totalBlocks) => {
+  const scale = createScale(view, cssWidth);
+  const start = clamp(Math.round(scale.block(pixels[0])), totalBlocks);
+  let end = clamp(Math.round(scale.block(pixels[1])), totalBlocks);
+  if (end <= start) {
+    end = Math.min(start + 1, totalBlocks);
+    if (end <= start) return [Math.max(0, end - 1), end];
+  }
+  return [start, end];
+};
+var normalize = (selection, totalBlocks) => {
+  if (!selection) return null;
+  const start = clamp(Math.round(selection[0]), totalBlocks);
+  const end = clamp(Math.round(selection[1]), totalBlocks);
+  return end > start ? [start, end] : null;
+};
+var xSpan = (selection) => {
+  if (!selection) return null;
+  const [x0, x1] = selection;
+  if (typeof x0 !== "number" || typeof x1 !== "number") return null;
+  return [x0, x1];
+};
+var sameRange = (a, b) => a === b || a !== null && b !== null && a[0] === b[0] && a[1] === b[1];
+var createBrushOverlay = (container, deps) => {
+  ensureRelative(container);
+  const svg = document.createElementNS(SVG_NAMESPACE, "svg");
+  svg.setAttribute(BRUSH_ATTRIBUTE, "");
+  Object.assign(svg.style, {
+    position: "absolute",
+    inset: "0",
+    width: "100%",
+    height: "100%",
+    touchAction: "none",
+    overflow: "visible",
+    display: "block"
+  });
+  container.append(svg);
+  const g = select(svg).append("g");
+  const onMouseDown = (event) => {
+    event.preventDefault();
+  };
+  svg.addEventListener("mousedown", onMouseDown, true);
+  const brush = brushX().touchable(() => false).filter(
+    (event) => !event.ctrlKey && !event.metaKey && !event.shiftKey && !event.button
+  );
+  let selection = null;
+  let color = DEFAULT_THEME.brush;
+  let silent = false;
+  let active = false;
+  const paint = () => {
+    g.select(SELECTION_CLASS).attr("fill", color).attr("stroke", color).attr("fill-opacity", BRUSH_FILL_OPACITY);
+  };
+  const update = () => {
+    const width = deps.getWidth();
+    brush.extent([
+      [0, 0],
+      [width, deps.getHeight()]
+    ]);
+    g.call(brush);
+    paint();
+    silent = true;
+    try {
+      g.call(brush.move, selection ? toPixels(selection, deps.getView(), width) : null);
+    } finally {
+      silent = false;
+    }
+  };
+  const blocksFrom = (pixels) => {
+    const span = xSpan(pixels);
+    if (!span) return null;
+    return toBlocks(span, deps.getView(), deps.getWidth(), deps.getTotalBlocks());
+  };
+  brush.on("start", (event) => {
+    if (!event.sourceEvent || silent) return;
+    active = true;
+  });
+  brush.on("brush", (event) => {
+    if (!event.sourceEvent || silent) return;
+    deps.onBrush(blocksFrom(event.selection));
+  });
+  brush.on("end", (event) => {
+    if (!event.sourceEvent || silent) return;
+    active = false;
+    const next = normalize(blocksFrom(event.selection), deps.getTotalBlocks());
+    const changed = !sameRange(selection, next);
+    selection = next;
+    update();
+    if (changed) deps.onBrushEnd(selection);
+  });
+  update();
+  return {
+    update,
+    setSelection: (next) => {
+      selection = normalize(next, deps.getTotalBlocks());
+      update();
+    },
+    getSelection: () => selection ? [selection[0], selection[1]] : null,
+    setColor: (next) => {
+      color = next;
+      paint();
+    },
+    // d3-brush only drops its window listeners and re-enables dragging from
+    // inside its own gesture end, so destroying mid-drag has to do it by
+    // hand or they outlive the map. Every targeted browser has
+    // onselectstart, so d3-drag suppresses selection with a listener rather
+    // than an inline style and removing the listeners is the whole cleanup.
+    // Those listeners are removed by name, which would take another
+    // component's brush or drag down with them, so this only runs for a
+    // gesture that is actually in flight.
+    destroy: () => {
+      brush.on("start", null).on("brush", null).on("end", null);
+      g.on(".brush", null);
+      svg.removeEventListener("mousedown", onMouseDown, true);
+      if (active) select(window).on(GESTURE_LISTENERS, null);
+      svg.remove();
+    }
+  };
+};
+
 // src/colors.ts
 import { rgb } from "d3-color";
 import { interpolateRgb, piecewise } from "d3-interpolate";
@@ -188,7 +403,8 @@ var THEME_VARS = {
   partialHigh: CSS_VAR_PARTIAL_HIGH,
   partial: CSS_VAR_PARTIAL,
   complete: CSS_VAR_COMPLETE,
-  highlight: CSS_VAR_HIGHLIGHT
+  highlight: CSS_VAR_HIGHLIGHT,
+  brush: CSS_VAR_BRUSH
 };
 var LAST_INDEX = COLOR_TABLE_SIZE - 1;
 var FIRST_PARTIAL_INDEX = 1;
@@ -214,7 +430,8 @@ var readTheme = (el) => {
     partialHigh: read("partialHigh"),
     partial: read("partial"),
     complete: read("complete"),
-    highlight: read("highlight")
+    highlight: read("highlight"),
+    brush: read("brush")
   };
 };
 var createColorScale = (theme, partial = "coverage") => {
@@ -262,9 +479,14 @@ var watchTheme = (onChange) => {
 
 // src/interaction.ts
 var PRIMARY_BUTTON = 0;
+var TOUCH_POINTER = "touch";
 var GRABBING = "grabbing";
 var NO_POINTER = -1;
-var attachInteraction = (canvas, deps) => {
+var HALF = 2;
+var ZOOM_IN_KEYS = /* @__PURE__ */ new Set(["+", "="]);
+var ZOOM_OUT_KEYS = /* @__PURE__ */ new Set(["-", "_"]);
+var RESET_KEYS = /* @__PURE__ */ new Set(["0", "Home"]);
+var attachInteraction = (surface, canvas, deps) => {
   let drag;
   const columnsToBlocks = (px, view) => px * deps.getDpr() / deps.getBinCount() * viewLength(view);
   const onWheel = (event) => {
@@ -273,14 +495,18 @@ var attachInteraction = (canvas, deps) => {
     if (deps.getBinCount() === 0) return;
     event.preventDefault();
     const view = deps.getView();
-    const anchor = view.start + columnsToBlocks(event.offsetX, view);
+    const anchor = view.start + columnsToBlocks(canvasX(canvas, event), view);
     const factor = event.deltaY > 0 ? ZOOM_STEP : 1 / ZOOM_STEP;
     deps.setView(zoomView(view, anchor, factor, deps.getTotalBlocks()));
   };
   const onPointerDown = (event) => {
     if (event.button !== PRIMARY_BUTTON) return;
+    if (document.activeElement !== canvas && typeof canvas.focus === "function") {
+      canvas.focus({ preventScroll: true });
+    }
+    if (deps.panRequiresShift() && event.pointerType !== TOUCH_POINTER && !event.shiftKey) return;
     drag = {
-      downX: event.offsetX,
+      downX: canvasX(canvas, event),
       view: deps.getView(),
       pointerId: event.pointerId ?? NO_POINTER,
       active: false
@@ -288,14 +514,14 @@ var attachInteraction = (canvas, deps) => {
   };
   const onPointerMove = (event) => {
     if (!drag) return;
-    const dx = event.offsetX - drag.downX;
+    const dx = canvasX(canvas, event) - drag.downX;
     if (!drag.active) {
       if (Math.abs(dx) < DRAG_THRESHOLD_PX) return;
       drag.active = true;
-      if (typeof canvas.setPointerCapture === "function" && drag.pointerId !== NO_POINTER) {
-        canvas.setPointerCapture(drag.pointerId);
+      if (typeof surface.setPointerCapture === "function" && drag.pointerId !== NO_POINTER) {
+        surface.setPointerCapture(drag.pointerId);
       }
-      canvas.style.cursor = GRABBING;
+      surface.style.cursor = GRABBING;
       deps.onDragStart();
     }
     if (deps.getBinCount() === 0) return;
@@ -304,30 +530,54 @@ var attachInteraction = (canvas, deps) => {
   const endDrag = () => {
     if (!drag) return;
     if (drag.active) {
-      const hasCapture = drag.pointerId !== NO_POINTER && (canvas.hasPointerCapture?.(drag.pointerId) ?? true);
-      if (typeof canvas.releasePointerCapture === "function" && hasCapture) {
-        canvas.releasePointerCapture(drag.pointerId);
+      const hasCapture = drag.pointerId !== NO_POINTER && (surface.hasPointerCapture?.(drag.pointerId) ?? true);
+      if (typeof surface.releasePointerCapture === "function" && hasCapture) {
+        surface.releasePointerCapture(drag.pointerId);
       }
-      canvas.style.cursor = "";
+      surface.style.cursor = "";
       deps.onDragEnd();
     }
     drag = void 0;
   };
   const onDblClick = () => deps.resetView();
-  canvas.addEventListener("wheel", onWheel, { passive: false });
-  canvas.addEventListener("pointerdown", onPointerDown);
-  canvas.addEventListener("pointermove", onPointerMove);
-  canvas.addEventListener("pointerup", endDrag);
-  canvas.addEventListener("pointercancel", endDrag);
-  canvas.addEventListener("dblclick", onDblClick);
+  const onKeyDown = (event) => {
+    if (event.ctrlKey || event.metaKey || event.altKey) return;
+    if (drag?.active) return;
+    const view = deps.getView();
+    const length = viewLength(view);
+    const centre = view.start + length / HALF;
+    const total = deps.getTotalBlocks();
+    if (ZOOM_IN_KEYS.has(event.key)) {
+      deps.setView(zoomView(view, centre, 1 / ZOOM_STEP, total));
+    } else if (ZOOM_OUT_KEYS.has(event.key)) {
+      deps.setView(zoomView(view, centre, ZOOM_STEP, total));
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+      const fraction = event.shiftKey ? KEY_PAN_FRACTION_FAST : KEY_PAN_FRACTION;
+      const delta = length * fraction * (event.key === "ArrowLeft" ? -1 : 1);
+      deps.setView(panView(view, delta, total));
+    } else if (RESET_KEYS.has(event.key)) {
+      deps.resetView();
+    } else {
+      return;
+    }
+    event.preventDefault();
+  };
+  surface.addEventListener("wheel", onWheel, { passive: false });
+  surface.addEventListener("pointerdown", onPointerDown);
+  surface.addEventListener("pointermove", onPointerMove);
+  surface.addEventListener("pointerup", endDrag);
+  surface.addEventListener("pointercancel", endDrag);
+  surface.addEventListener("dblclick", onDblClick);
+  canvas.addEventListener("keydown", onKeyDown);
   return () => {
     endDrag();
-    canvas.removeEventListener("wheel", onWheel);
-    canvas.removeEventListener("pointerdown", onPointerDown);
-    canvas.removeEventListener("pointermove", onPointerMove);
-    canvas.removeEventListener("pointerup", endDrag);
-    canvas.removeEventListener("pointercancel", endDrag);
-    canvas.removeEventListener("dblclick", onDblClick);
+    surface.removeEventListener("wheel", onWheel);
+    surface.removeEventListener("pointerdown", onPointerDown);
+    surface.removeEventListener("pointermove", onPointerMove);
+    surface.removeEventListener("pointerup", endDrag);
+    surface.removeEventListener("pointercancel", endDrag);
+    surface.removeEventListener("dblclick", onDblClick);
+    canvas.removeEventListener("keydown", onKeyDown);
   };
 };
 
@@ -347,7 +597,6 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
   let image;
   let scale;
   let frame = NO_FRAME;
-  let scheduled = false;
   let allDirty = false;
   let highlight;
   let phase = false;
@@ -367,12 +616,13 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
     target.data.set(color, column * BYTES_PER_PIXEL);
   };
   const paintDiscrete = (target, colors) => {
-    const { view, binCount } = source;
+    const { binCount } = source;
+    const view = source.getView();
     const length = viewLength(view);
     for (let block = 0; block < length; block += 1) {
       const color = colorFor(colors, source.has(view.start + block) ? COMPLETE : 0);
-      const start = Math.floor(block * binCount / length);
-      const end = Math.floor((block + 1) * binCount / length);
+      const start = discreteColumn(block, length, binCount);
+      const end = discreteColumn(block + 1, length, binCount);
       for (let column = start; column < end; column += 1) writeColumn(target, column, color);
     }
   };
@@ -388,7 +638,6 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
     }
   };
   const paint = () => {
-    scheduled = false;
     frame = NO_FRAME;
     const target = ensureImage();
     if (!target || !scale) {
@@ -396,15 +645,14 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
       allDirty = false;
       return;
     }
-    if (viewLength(source.view) < source.binCount) paintDiscrete(target, scale);
+    if (viewLength(source.getView()) < source.binCount) paintDiscrete(target, scale);
     else paintBins(target, scale);
     ctx.putImageData(target, 0, 0);
     dirty.clear();
     allDirty = false;
   };
   const schedule = () => {
-    if (scheduled) return;
-    scheduled = true;
+    if (frame !== NO_FRAME) return;
     frame = scheduler.request(paint);
   };
   const markAllDirty = () => {
@@ -420,6 +668,9 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
       scale = next;
       markAllDirty();
     },
+    // Restarts cleanly on every call: the old interval is always cleared, so
+    // repeated enables cannot stack up blink timers. Turning the highlight
+    // off when it was never on is a no-op, avoiding a pointless repaint.
     setHighlight: (on, color, blink) => {
       if (!on && highlight === void 0) return;
       stopBlink();
@@ -433,6 +684,7 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
       }
       markAllDirty();
     },
+    // Theme changed mid-highlight; the blink phase keeps running untouched.
     setHighlightColor: (color) => {
       if (highlight === void 0) return;
       highlight = color;
@@ -445,8 +697,7 @@ var createRenderer = (ctx, source, scheduler = RAF_SCHEDULER, timer = WINDOW_TIM
     markAllDirty,
     destroy: () => {
       stopBlink();
-      if (scheduled) scheduler.cancel(frame);
-      scheduled = false;
+      if (frame !== NO_FRAME) scheduler.cancel(frame);
       frame = NO_FRAME;
       dirty.clear();
     }
@@ -464,6 +715,10 @@ var createBitset = (size) => {
   let count = 0;
   return {
     has: (index) => (bytes[index >>> BYTE_SHIFT] & 1 << (index & BYTE_MASK)) !== 0,
+    /**
+     * Returns false when the bit was already set, so callers can skip the
+     * dirty-marking work for blocks that did not actually change.
+     */
     set: (index) => {
       const byte = index >>> BYTE_SHIFT;
       const mask = 1 << (index & BYTE_MASK);
@@ -472,6 +727,11 @@ var createBitset = (size) => {
       count += 1;
       return true;
     },
+    /**
+     * Head/middle/tail: OR a partial mask into the first byte, memset the
+     * whole bytes in between, OR a partial mask into the last. `end - 1` is
+     * the last included bit, so `toBit` is its offset plus one.
+     */
     fill: (start, end) => {
       if (end <= start) return;
       const firstByte = start >>> BYTE_SHIFT;
@@ -486,6 +746,7 @@ var createBitset = (size) => {
       bytes.fill(FULL_BYTE, firstByte + 1, lastByte);
       bytes[lastByte] |= maskRange(0, toBit);
     },
+    // Same head/middle/tail shape as fill, with the masks inverted.
     clearRange: (start, end) => {
       if (end <= start) return;
       const firstByte = start >>> BYTE_SHIFT;
@@ -500,6 +761,8 @@ var createBitset = (size) => {
       bytes.fill(0, firstByte + 1, lastByte);
       bytes[lastByte] &= ~maskRange(0, toBit);
     },
+    // Head and tail are masked before counting; the middle bytes are counted
+    // whole, one table lookup each.
     countRange: (start, end) => {
       if (end <= start) return 0;
       const firstByte = start >>> BYTE_SHIFT;
@@ -518,6 +781,11 @@ var createBitset = (size) => {
       bytes.fill(0);
       count = 0;
     },
+    /**
+     * fill and clearRange do not maintain `count`, because recounting a
+     * million-bit span per call would defeat the point. Callers that use them
+     * compute the delta themselves and write the total back here.
+     */
     setCount: (next) => {
       count = next;
     },
@@ -527,70 +795,6 @@ var createBitset = (size) => {
   };
 };
 
-// src/bins.ts
-var clipToView = (rawStart, rawEnd, viewStart, viewEnd) => ({
-  start: Math.max(rawStart, viewStart),
-  end: Math.min(rawEnd, viewEnd)
-});
-var createBins = (view, binCount) => {
-  const { start: viewStart, end: viewEnd } = view;
-  const length = viewEnd - viewStart;
-  const counts = new Uint32Array(binCount);
-  const binOf = (index) => Math.floor((index - viewStart) * binCount / length);
-  const rangeOf = (bin) => ({
-    start: viewStart + Math.ceil(bin * length / binCount),
-    end: viewStart + Math.ceil((bin + 1) * length / binCount)
-  });
-  const sizeOf = (bin) => {
-    const { start, end } = rangeOf(bin);
-    return end - start;
-  };
-  return {
-    view,
-    binCount,
-    counts,
-    binOf,
-    rangeOf,
-    sizeOf,
-    rebuild: (countInRange) => {
-      counts.fill(0);
-      if (binCount === 0) return;
-      for (let bin = 0; bin < binCount; bin += 1) {
-        const { start, end } = rangeOf(bin);
-        counts[bin] = countInRange(start, end);
-      }
-    },
-    addRange: (rawStart, rawEnd) => {
-      const { start, end } = clipToView(rawStart, rawEnd, viewStart, viewEnd);
-      if (binCount === 0 || end <= start) return;
-      const first = binOf(start);
-      const last = binOf(end - 1);
-      if (first === last) {
-        counts[first] += end - start;
-        return;
-      }
-      counts[first] += rangeOf(first).end - start;
-      for (let bin = first + 1; bin < last; bin += 1) counts[bin] += sizeOf(bin);
-      counts[last] += end - rangeOf(last).start;
-    },
-    binsTouching: (rawStart, rawEnd) => {
-      const { start, end } = clipToView(rawStart, rawEnd, viewStart, viewEnd);
-      if (binCount === 0 || end <= start) return [];
-      const first = binOf(start);
-      const last = binOf(end - 1);
-      const touched = [];
-      for (let bin = first; bin <= last; bin += 1) touched.push(bin);
-      return touched;
-    },
-    recountBins: (bins, countInRange) => {
-      for (const bin of bins) {
-        const range = rangeOf(bin);
-        counts[bin] = countInRange(range.start, range.end);
-      }
-    }
-  };
-};
-
 // src/ranges.ts
 var isFlatPairs = (input) => ArrayBuffer.isView(input) || typeof input[0] === "number";
 var readPairs = (input) => {
@@ -689,22 +893,23 @@ var createBlockState = (totalBlocks) => {
     get binCount() {
       return bins.binCount;
     },
-    get view() {
-      return view;
-    },
+    // Column count changed: the bin boundaries move, so rebuild from the
+    // bitset rather than trying to redistribute the old counts.
     resize: (binCount) => {
       bins = createBins(view, binCount);
       bins.rebuild(bitset.countRange);
     },
+    // Takes a view legalView has already checked, so the façade validates once
+    // per request rather than again at commit. Returns whether anything moved,
+    // so callers can skip a repaint.
     setView: (next) => {
-      if (!Number.isFinite(next.start) || !Number.isFinite(next.end)) return false;
-      const clamped = clampView(next, totalBlocks);
-      if (sameView(clamped, view)) return false;
-      view = clamped;
+      if (sameView(next, view)) return false;
+      view = { ...next };
       bins = createBins(view, bins.binCount);
       bins.rebuild(bitset.countRange);
       return true;
     },
+    // A copy, because `view` is live and handed to external callbacks.
     getView: () => ({ ...view }),
     add,
     replace: (indices) => {
@@ -712,6 +917,11 @@ var createBlockState = (totalBlocks) => {
       bins.counts.fill(0);
       add(indices);
     },
+    /**
+     * Ranges are already merged and disjoint, so each one's blocks are new to
+     * the bitset: bins.addRange can add sizes arithmetically and the total is
+     * just the summed range lengths, with no counting pass.
+     */
     replaceRanges: (input) => {
       const flat = normalizeRanges(input, totalBlocks);
       bitset.clear();
@@ -725,12 +935,12 @@ var createBlockState = (totalBlocks) => {
     addRanges: (input) => applyRanges(input, true),
     removeRanges: (input) => applyRanges(input, false),
     has: bitset.has,
+    // Coverage in [0, 1], which is what the colour scale is indexed by.
     fraction: (bin) => {
       const size = bins.sizeOf(bin);
       return size === 0 ? 0 : bins.counts[bin] / size;
     },
     countOf: (bin) => bins.counts[bin],
-    sizeOf: (bin) => bins.sizeOf(bin),
     rangeOf: (bin) => bins.rangeOf(bin),
     progress: () => ({ completed: bitset.count, total: totalBlocks })
   };
@@ -760,9 +970,9 @@ var formatPercent = (count, size) => {
   }
   return `${text}%`;
 };
-var formatBinTooltip = (range, count) => {
-  const size = range.end - range.start;
-  const label = size === 1 ? `Block ${countFormat.format(range.start)}` : `Blocks ${countFormat.format(range.start)}${EN_DASH}${countFormat.format(range.end - 1)}`;
+var formatBinTooltip = ([start, end], count) => {
+  const size = end - start;
+  const label = size === 1 ? `Block ${countFormat.format(start)}` : `Blocks ${countFormat.format(start)}${EN_DASH}${countFormat.format(end - 1)}`;
   return `${label}${SEPARATOR}${countFormat.format(count)} / ${countFormat.format(size)} (${formatPercent(count, size)})`;
 };
 var formatBlockTooltip = (index, complete) => `Block ${countFormat.format(index)}${SEPARATOR}${complete ? "complete" : "missing"}`;
@@ -781,6 +991,8 @@ var createTooltip = (container) => {
   ensureRelative(container);
   container.append(el);
   return {
+    // x is in container-relative CSS pixels; the offset keeps the label from
+    // sitting directly under the cursor.
     show: (x, text) => {
       el.textContent = text;
       el.style.left = `${x + TOOLTIP_OFFSET_PX}px`;
@@ -799,11 +1011,20 @@ var createTooltip = (container) => {
 var FULL2 = "100%";
 var CONTEXT_ID = "2d";
 var NO_FRAME2 = 0;
+var LOCALE2 = "en-US";
+var ARIA_LABEL_ATTRIBUTE = "aria-label";
+var numberFormat = new Intl.NumberFormat(LOCALE2);
+var defaultLabel = (progress) => {
+  const percent = Math.floor(progress.completed / progress.total * PERCENT).toFixed(
+    ARIA_LABEL_DEFAULT_PERCENT_DIGITS
+  );
+  return `Download progress: ${numberFormat.format(progress.completed)} of ${numberFormat.format(progress.total)} blocks (${percent}%)`;
+};
 var dprQuery = (dpr) => `(resolution: ${dpr}dppx)`;
-var discreteBlock = (column, length, binCount, start) => start + Math.ceil((column + 1) * length / binCount) - 1;
 var createBlockMap = (container, options) => {
   const state = createBlockState(options.totalBlocks);
-  if (options.view) state.setView(options.view);
+  const initialView = options.view && legalView(options.view, state.totalBlocks);
+  if (initialView) state.setView(initialView);
   const canvas = document.createElement("canvas");
   Object.assign(canvas.style, {
     display: "block",
@@ -812,6 +1033,12 @@ var createBlockMap = (container, options) => {
     touchAction: "none"
   });
   canvas.height = CANVAS_ROWS;
+  canvas.setAttribute("role", "img");
+  canvas.setAttribute("aria-roledescription", ARIA_ROLEDESCRIPTION);
+  if (options.interactive !== false) {
+    canvas.tabIndex = 0;
+    canvas.setAttribute("aria-keyshortcuts", ARIA_KEYSHORTCUTS);
+  }
   container.append(canvas);
   const ctx = canvas.getContext(CONTEXT_ID);
   if (!ctx) {
@@ -819,53 +1046,77 @@ var createBlockMap = (container, options) => {
     throw new Error(`Could not acquire a ${CONTEXT_ID} canvas context`);
   }
   const renderer = createRenderer(ctx, state);
-  const tooltip = createTooltip(container);
-  const axisOptions = options.axis === true ? {} : options.axis === false || options.axis === void 0 ? void 0 : options.axis;
-  const axis = axisOptions ? createAxis(container, axisOptions) : void 0;
   let destroyed = false;
   let cssWidth = 0;
+  let cssHeight = 0;
   let dpr = devicePixelRatio;
   let dprMedia;
   let theme = readTheme(container);
   let highlightOn = false;
   let dragging = false;
-  const blinkAllowed = () => !matchMedia(REDUCED_MOTION_QUERY).matches;
+  let downX = Number.NaN;
+  const overlay = options.brush === true ? createBrushOverlay(container, {
+    getView: () => state.getView(),
+    getWidth: () => cssWidth,
+    getHeight: () => cssHeight,
+    getTotalBlocks: () => state.totalBlocks,
+    onBrush: (selection) => options.onBrush?.(selection),
+    onBrushEnd: (selection) => options.onBrushEnd?.(selection)
+  }) : void 0;
+  const tooltip = createTooltip(container);
+  const axisOptions = options.axis === true ? {} : options.axis === false || options.axis === void 0 ? void 0 : options.axis;
+  const axis = axisOptions ? createAxis(container, axisOptions) : void 0;
+  const motionMedia = matchMedia(REDUCED_MOTION_QUERY);
+  const blinkAllowed = () => !motionMedia.matches;
   const applyHighlight = () => {
     renderer.setHighlight(highlightOn, highlightColor(theme), blinkAllowed());
   };
+  const onMotionChange = () => {
+    if (highlightOn) applyHighlight();
+  };
+  motionMedia.addEventListener("change", onMotionChange);
   const applyTheme = () => {
     theme = readTheme(container);
     renderer.setColors(createColorScale(theme, options.partial));
     if (highlightOn) renderer.setHighlightColor(highlightColor(theme));
+    overlay?.setColor(theme.brush);
+  };
+  const writeLabel = () => {
+    canvas.setAttribute(ARIA_LABEL_ATTRIBUTE, (options.label ?? defaultLabel)(state.progress()));
+  };
+  const updateChrome = () => {
+    axis?.update(state.getView(), cssWidth);
+    overlay?.update();
   };
   let pendingView;
   let viewFrame = NO_FRAME2;
-  const getView = () => ({ ...pendingView ?? state.view });
+  const getView = () => ({ ...pendingView ?? state.getView() });
   const commitView = () => {
     viewFrame = NO_FRAME2;
     const next = pendingView;
     pendingView = void 0;
     if (!next || !state.setView(next)) return;
     renderer.markAllDirty();
-    axis?.update(state.view, cssWidth);
+    updateChrome();
     options.onViewChange?.(state.getView());
   };
   const setView = (view) => {
-    if (!Number.isFinite(view.start) || !Number.isFinite(view.end)) return;
-    const clamped = clampView(view, state.totalBlocks);
-    if (sameView(clamped, pendingView ?? state.view)) return;
-    const hasPendingFrame = pendingView !== void 0;
-    pendingView = clamped;
-    if (!hasPendingFrame) viewFrame = requestAnimationFrame(commitView);
+    const legal = legalView(view, state.totalBlocks);
+    if (!legal || sameView(legal, pendingView ?? state.getView())) return;
+    pendingView = legal;
+    if (viewFrame !== NO_FRAME2) return;
+    viewFrame = requestAnimationFrame(commitView);
   };
   const resetView = () => setView(fullView(state.totalBlocks));
   const layout = () => {
+    if (cssWidth === 0) return;
     const binCount = Math.round(cssWidth * dpr);
-    if (binCount === state.binCount) return;
-    canvas.width = binCount;
-    state.resize(binCount);
-    renderer.markAllDirty();
-    axis?.update(state.view, cssWidth);
+    if (binCount !== state.binCount) {
+      canvas.width = binCount;
+      state.resize(binCount);
+      renderer.markAllDirty();
+    }
+    updateChrome();
   };
   const onDprChange = () => {
     dpr = devicePixelRatio;
@@ -881,34 +1132,70 @@ var createBlockMap = (container, options) => {
     const entry = entries[0];
     if (!entry) return;
     cssWidth = entry.contentRect.width;
+    cssHeight = entry.contentRect.height;
     layout();
   });
   resizeObserver.observe(container);
-  const onPointerMove = (event) => {
-    if (dragging) return;
-    const { binCount, view } = state;
-    if (binCount === 0) return;
-    const column = Math.min(binCount - 1, Math.max(0, Math.floor(event.offsetX * dpr)));
+  const locate = (x) => {
+    const { binCount } = state;
+    if (binCount === 0) return void 0;
+    if (x < 0 || x >= cssWidth) return void 0;
+    const column = Math.min(binCount - 1, Math.max(0, Math.floor(x * dpr)));
+    const view = state.getView();
     const length = viewLength(view);
-    let text;
     if (length < binCount) {
-      const block = discreteBlock(column, length, binCount, view.start);
-      text = formatBlockTooltip(block, state.has(block));
-    } else {
-      text = formatBinTooltip(state.rangeOf(column), state.countOf(column));
+      const block = view.start + discreteBlock(column, length, binCount);
+      return {
+        block,
+        range: [block, block + 1],
+        completed: state.has(block) ? 1 : 0,
+        total: 1
+      };
     }
-    tooltip.show(event.offsetX, text);
+    const [start, end] = state.rangeOf(column);
+    return {
+      block: start,
+      range: [start, end],
+      completed: state.countOf(column),
+      total: end - start
+    };
+  };
+  const onPointerMove = (event) => {
+    if (dragging) return;
+    const x = canvasX(canvas, event);
+    const hit = locate(x);
+    if (!hit) {
+      tooltip.hide();
+      return;
+    }
+    const text = viewLength(state.getView()) < state.binCount ? formatBlockTooltip(hit.block, hit.completed === 1) : formatBinTooltip(hit.range, hit.completed);
+    tooltip.show(x, text);
   };
   const onPointerLeave = () => tooltip.hide();
-  canvas.addEventListener("pointermove", onPointerMove);
-  canvas.addEventListener("pointerleave", onPointerLeave);
-  const detachInteraction = options.interactive === false ? void 0 : attachInteraction(canvas, {
+  const onPointerDown = (event) => {
+    downX = event.clientX;
+  };
+  const onClick = (event) => {
+    const travelled = Math.abs(event.clientX - downX);
+    downX = Number.NaN;
+    if (travelled >= DRAG_THRESHOLD_PX) return;
+    if (!options.onBlockClick) return;
+    const hit = locate(canvasX(canvas, event));
+    if (!hit) return;
+    options.onBlockClick({ ...hit, originalEvent: event });
+  };
+  container.addEventListener("pointermove", onPointerMove);
+  container.addEventListener("pointerleave", onPointerLeave);
+  container.addEventListener("pointerdown", onPointerDown);
+  container.addEventListener("click", onClick);
+  const detachInteraction = options.interactive === false ? void 0 : attachInteraction(container, canvas, {
     getView,
     setView,
     resetView,
     getBinCount: () => state.binCount,
     getDpr: () => dpr,
     getTotalBlocks: () => state.totalBlocks,
+    panRequiresShift: () => overlay !== void 0,
     onDragStart: () => {
       dragging = true;
       tooltip.hide();
@@ -922,47 +1209,54 @@ var createBlockMap = (container, options) => {
   applyTheme();
   if (options.initialRanges) state.replaceRanges(options.initialRanges);
   if (options.initialBlocks) renderer.markDirty(state.add(options.initialBlocks));
+  writeLabel();
+  const live = (method) => (...args) => {
+    if (!destroyed) method(...args);
+  };
   return {
-    setBlocks: (indices) => {
-      if (destroyed) return;
+    setBlocks: live((indices) => {
       state.replace(indices);
       renderer.markAllDirty();
-    },
-    setRanges: (ranges) => {
-      if (destroyed) return;
+      writeLabel();
+    }),
+    setRanges: live((ranges) => {
       state.replaceRanges(ranges);
       renderer.markAllDirty();
-    },
-    addBlocks: (indices) => {
-      if (destroyed) return;
+      writeLabel();
+    }),
+    // The incremental paths repaint only the bins the state reports changed.
+    addBlocks: live((indices) => {
       renderer.markDirty(state.add(indices));
-    },
-    addRanges: (ranges) => {
-      if (destroyed) return;
+      writeLabel();
+    }),
+    addRanges: live((ranges) => {
       renderer.markDirty(state.addRanges(ranges));
-    },
-    removeRanges: (ranges) => {
-      if (destroyed) return;
+      writeLabel();
+    }),
+    removeRanges: live((ranges) => {
       renderer.markDirty(state.removeRanges(ranges));
-    },
-    setView: (view) => {
-      if (destroyed) return;
-      setView(view);
-    },
-    resetView: () => {
-      if (destroyed) return;
-      resetView();
-    },
+      writeLabel();
+    }),
+    setView: live(setView),
+    resetView: live(resetView),
     getView,
+    // Built from the committed view, so the scale always matches what is on
+    // screen rather than a change still waiting for its frame.
     getScale: () => createScale(state.getView(), cssWidth),
-    setHighlight: (on) => {
-      if (destroyed) return;
+    // Selections are only meaningful while there is an overlay to draw them:
+    // without one setBrush has nothing to store and getBrush nothing to
+    // report. A destroyed map reports none either, rather than whatever the
+    // detached overlay was last holding.
+    setBrush: live((selection) => overlay?.setSelection(selection)),
+    getBrush: () => destroyed ? null : overlay?.getSelection() ?? null,
+    setHighlight: live((on) => {
       highlightOn = on;
       applyHighlight();
-    },
+    }),
     getProgress: () => destroyed ? { completed: 0, total: state.totalBlocks } : state.progress(),
-    destroy: () => {
-      if (destroyed) return;
+    // Idempotent, and unwinds in the reverse order of construction: pending
+    // frame, observers, listeners, owned children, then the canvas itself.
+    destroy: live(() => {
       destroyed = true;
       if (viewFrame !== NO_FRAME2) cancelAnimationFrame(viewFrame);
       viewFrame = NO_FRAME2;
@@ -970,18 +1264,25 @@ var createBlockMap = (container, options) => {
       resizeObserver.disconnect();
       unwatchTheme();
       dprMedia?.removeEventListener("change", onDprChange);
-      canvas.removeEventListener("pointermove", onPointerMove);
-      canvas.removeEventListener("pointerleave", onPointerLeave);
+      motionMedia.removeEventListener("change", onMotionChange);
+      container.removeEventListener("pointermove", onPointerMove);
+      container.removeEventListener("pointerleave", onPointerLeave);
+      container.removeEventListener("pointerdown", onPointerDown);
+      container.removeEventListener("click", onClick);
       detachInteraction?.();
       renderer.destroy();
       tooltip.destroy();
       axis?.destroy();
+      overlay?.destroy();
       canvas.remove();
-    }
+    })
   };
 };
 
 export {
+  fullView,
+  createScale,
+  defaultLabel,
   createBlockMap
 };
-//# sourceMappingURL=chunk-WIDC3EN2.js.map
+//# sourceMappingURL=chunk-6BBJWE5O.js.map