yamlover 0.3.0

package/src/client/renderers/latex.tsx

@@ -0,0 +1,36 @@
+import katex from "katex";
+import "katex/dist/katex.min.css";
+import { NodeJson } from "../api";
+import { Chunk } from "./registry";
+
+/**
+ * The renderer for a `string`/`text/x-latex` node: LaTeX math typeset with KaTeX.
+ * Like the markdown/asciidoc renderers it works straight from the node's string
+ * value, so it serves both a whole formula node (`render`) and a single inline
+ * chunk (`renderChunk`).
+ *
+ * `renderMath` is the one place KaTeX is invoked, exported so **marklower** can
+ * reuse it for its inline `$$…$$` spans — math is rendered the same way whether it
+ * is a standalone `text/x-latex` string or embedded in marklower prose.
+ */
+export function renderMath(tex: unknown, displayMode: boolean): string {
+  // `throwOnError: false` makes KaTeX emit the offending source in red rather than
+  // throwing, so a typo in one formula never blanks the whole page.
+  return katex.renderToString(String(tex ?? ""), { displayMode, throwOnError: false });
+}
+
+export function LatexView({ node }: { node: NodeJson }) {
+  return (
+    <div className="text">
+      {node.title && <h1 className="chapter-title">{node.title}</h1>}
+      {node.description && <p className="chapter-subtitle">{node.description}</p>}
+      <div className="markup" dangerouslySetInnerHTML={{ __html: renderMath(node.value, true) }} />
+    </div>
+  );
+}
+
+/** A LaTeX chunk embedded inline in a chapter: the formula typeset as a display
+ *  block (the chapter supplies the surrounding number + anchor). */
+export function LatexChunk({ chunk }: { chunk: Chunk }) {
+  return <div className="markup" dangerouslySetInnerHTML={{ __html: renderMath(chunk.value, true) }} />;
+}

package/src/client/renderers/map.tsx

@@ -0,0 +1,205 @@
+import { useEffect, useRef, useState } from "react";
+import L from "leaflet";
+import "leaflet/dist/leaflet.css";
+import { NodeJson, blobUrl } from "../api";
+import { Chunk } from "./registry";
+import { bytesToGeoJSON, GeoJSON } from "./kml";
+import { Annotation } from "../api";
+import { DEFAULT_COLOR, colorOf, editable, useAnnotationMenu, useMaterialAnnotations } from "./annotate";
+import { wireGestures } from "./panzoom";
+
+/**
+ * Renderer for geographic overlays — `.kml` and `.kmz` (zipped KML). The file is
+ * served as bytes; we convert it to GeoJSON (see `kml.ts`) and draw it on a
+ * Leaflet slippy map over OpenStreetMap tiles, fitting the view to the data.
+ * Points become circle markers, lines/polygons keep their KML colours, and a
+ * feature's name/description show in a popup.
+ *
+ * Gestures follow the unified model (see {@link wireGestures} / the UI guide): plain drag selects a
+ * geographic region to annotate, ctrl/alt-drag pans, plain wheel pans vertically, ctrl/alt-wheel
+ * zooms.
+ *
+ * **Network note:** the vector overlay and KML/KMZ parsing are fully local, but the
+ * *map tiles* are fetched from a tile server — by default OpenStreetMap. Point
+ * `VITE_MAP_TILE_URL` (and optionally `VITE_MAP_TILE_ATTRIBUTION`) at a self-hosted
+ * tile server to keep map traffic off the public one. Leaflet is heavy and
+ * browser-only, so the registry loads this module lazily.
+ */
+const TILE_URL =
+  ((import.meta as any).env?.VITE_MAP_TILE_URL as string | undefined) ??
+  "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png";
+const TILE_ATTRIBUTION =
+  ((import.meta as any).env?.VITE_MAP_TILE_ATTRIBUTION as string | undefined) ??
+  '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors';
+
+/** A rectangular annotation region on the map, in geographic edges (degrees). `ann` is the source
+ *  annotation when it is a real saved one (→ clickable to edit); absent for the live preview. */
+interface MapRegion { n: number; s: number; e: number; w: number; title?: string; color?: string; ann?: Annotation }
+const num = (v: unknown): number => Number(v) || 0;
+
+/** The `map`-type annotations, as geographic rectangles to overlay. */
+function mapRegions(anns: Annotation[]): MapRegion[] {
+  return anns
+    .filter((a) => a.selector?.type === "map")
+    .map((a) => ({ n: num(a.selector!.n), s: num(a.selector!.s), e: num(a.selector!.e), w: num(a.selector!.w), title: a.description, color: colorOf(a), ann: editable(a) ? a : undefined }));
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** A feature's description as popup HTML. togeojson returns a plain-text KML
+ *  description as a string (escaped here) and an HTML/CDATA one as
+ *  `{ "@type": "html", value }` — authored markup, kept as-is (this is a local
+ *  viewer of the user's own files). */
+function descriptionHtml(description: unknown): string {
+  if (!description) return "";
+  if (typeof description === "string") return escapeHtml(description);
+  if (typeof description === "object" && (description as any)["@type"] === "html") {
+    return String((description as any).value ?? "");
+  }
+  return "";
+}
+
+/** Draw `geo` onto a fresh Leaflet map in `el`, fit to the data, and return the map
+ *  (so the caller can dispose it). */
+function drawMap(el: HTMLElement, geo: GeoJSON): L.Map {
+  const map = L.map(el);
+  L.tileLayer(TILE_URL, { maxZoom: 19, attribution: TILE_ATTRIBUTION }).addTo(map);
+  const layer = L.geoJSON(geo as any, {
+    // honour KML styling that togeojson surfaces as simplestyle properties
+    style: (f) => {
+      const p = (f?.properties ?? {}) as Record<string, unknown>;
+      return {
+        color: (p["stroke"] as string) || "#3388ff",
+        weight: (p["stroke-width"] as number) || 2,
+        opacity: (p["stroke-opacity"] as number) ?? 1,
+        fillColor: (p["fill"] as string) || "#3388ff",
+        fillOpacity: (p["fill-opacity"] as number) ?? 0.2,
+      };
+    },
+    pointToLayer: (_f, latlng) => L.circleMarker(latlng, { radius: 5, color: "#e23", weight: 2, fillOpacity: 0.8 }),
+    onEachFeature: (f, lyr) => {
+      const p = (f.properties ?? {}) as { name?: string; description?: unknown };
+      const name = p.name ? `<strong>${escapeHtml(p.name)}</strong>` : "";
+      const body = descriptionHtml(p.description);
+      const desc = body ? `<div class="map-popup-desc">${body}</div>` : "";
+      if (name || desc) lyr.bindPopup(`${name}${desc}`);
+    },
+  }).addTo(map);
+
+  const bounds = layer.getBounds();
+  if (bounds.isValid()) map.fitBounds(bounds, { padding: [24, 24], maxZoom: 16 });
+  else map.setView([0, 0], 2); // nothing geocoded — show the whole world
+  return map;
+}
+
+/** Fetch the file, convert to GeoJSON, and render a Leaflet map into `className`.
+ *  Shared by the full page and the inline chunk (which only differ in height/CSS + annotation). */
+function MapBody({
+  path, className, regions, onSelectRegion, onRegionClick, selectColor,
+}: {
+  path: string;
+  className: string;
+  regions?: MapRegion[];
+  onSelectRegion?: (selector: Record<string, unknown>, screen: { x: number; y: number }) => void;
+  onRegionClick?: (ann: Annotation, screen: { x: number; y: number }) => void;
+  selectColor?: () => string;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<L.Map | null>(null);
+  const layerRef = useRef<L.LayerGroup | null>(null);
+  const onSelectRef = useRef(onSelectRegion);
+  const onRegionClickRef = useRef(onRegionClick);
+  const colorRef = useRef(selectColor);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [ready, setReady] = useState(0);
+  const regionsKey = JSON.stringify(regions ?? []);
+  const selectable = !!onSelectRegion;
+
+  useEffect(() => { onSelectRef.current = onSelectRegion; onRegionClickRef.current = onRegionClick; colorRef.current = selectColor; });
+
+  useEffect(() => {
+    let cancelled = false;
+    let dispose: (() => void) | null = null;
+    setError(null);
+    setLoading(true);
+    fetch(blobUrl(path))
+      .then((r) => r.arrayBuffer())
+      .then((buf) => {
+        if (cancelled || !ref.current) return;
+        const map = drawMap(ref.current, bytesToGeoJSON(new Uint8Array(buf)));
+        layerRef.current = L.layerGroup().addTo(map);
+        mapRef.current = map;
+        dispose = wireGestures(map, {
+          color: () => colorRef.current?.() ?? DEFAULT_COLOR,
+          onSelect: selectable
+            ? (b, screen) => onSelectRef.current?.({ type: "map", n: b.getNorth(), s: b.getSouth(), e: b.getEast(), w: b.getWest() }, screen)
+            : undefined,
+        });
+        setReady((x) => x + 1);
+        setLoading(false);
+      })
+      .catch((e) => {
+        if (!cancelled) {
+          setError(String((e as Error).message || e));
+          setLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+      dispose?.();
+      mapRef.current?.remove();
+      mapRef.current = null;
+      layerRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [path]);
+
+  // Draw region rectangles into the overlay layer — in place, so creating one keeps the view.
+  useEffect(() => {
+    const lg = layerRef.current;
+    if (!lg) return;
+    lg.clearLayers();
+    for (const r of regions ?? []) {
+      const c = r.color || DEFAULT_COLOR;
+      const rect = L.rectangle([[r.s, r.w], [r.n, r.e]], { className: "yo-region", color: c, weight: 3, fillColor: c, fillOpacity: 0.25 });
+      if (r.title) rect.bindTooltip(r.title);
+      if (r.ann) {
+        const ann = r.ann;
+        rect.on("click", (ev) => { L.DomEvent.stop(ev); onRegionClickRef.current?.(ann, { x: ev.originalEvent.clientX, y: ev.originalEvent.clientY }); });
+      }
+      rect.addTo(lg);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [regionsKey, ready]);
+
+  return (
+    <>
+      {error && <div className="error">map: {error}</div>}
+      <div ref={ref} className={className + (selectable ? " yo-selectable" : "")} />
+      {loading && !error && <div className="loading">loading map…</div>}
+    </>
+  );
+}
+
+export function MapView({ node }: { node: NodeJson }) {
+  const material = useMaterialAnnotations(node.path);
+  const { openCreate, openEdit, palette, preview, color } = useAnnotationMenu(material);
+  const shown = preview
+    ? [...material.annotations, { path: "(preview)", selector: preview.selector, tag: preview.tag } as Annotation]
+    : material.annotations;
+  return (
+    <div className="text">
+      {node.title && <h1 className="chapter-title">{node.title}</h1>}
+      {node.description && <p className="chapter-subtitle">{node.description}</p>}
+      <MapBody path={node.path} regions={mapRegions(shown)} onSelectRegion={openCreate} onRegionClick={openEdit} selectColor={() => color} className="filemap" />
+      {palette}
+    </div>
+  );
+}
+
+export function MapChunk({ chunk }: { chunk: Chunk }) {
+  return <MapBody path={chunk.path} className="filemap chunk-map" />;
+}

package/src/client/renderers/marklower.tsx

@@ -0,0 +1,119 @@
+import { ReactNode } from "react";
+import { NodeJson } from "../api";
+import { Chunk } from "./registry";
+import { renderMath } from "./latex";
+import { NavLink } from "../links";
+
+/**
+ * The renderer for a bare `string` with no explicit format — `(string, null)` —
+ * our own lightweight markup language, **marklower**: deliberately a notch below
+ * Markdown ("downshifted" from it). It is the *default* format for prose strings
+ * inside a chapter: a chunk that declares no format routes here rather than to the
+ * plain-paragraph fallback.
+ *
+ * The language is meant to cover inline concerns only — font styling, hyperlinks,
+ * images, math, and (perhaps) embedded code — but deliberately **no** chapter
+ * structure: no headings/subheadings, since chapters are modeled by the chapter
+ * renderer's `children`, not by markup.
+ *
+ * The syntax so far is all inline:
+ *
+ *   - **atomic tokens**, whose contents are *not* re-interpreted as markup:
+ *     `$$…$$` math (typeset with KaTeX via the shared {@link renderMath}, the same
+ *     path the `text/x-latex` renderer uses) and `` `code` `` spans;
+ *   - **links**: `[text](target)`, where `target` is a path in the app's JSON
+ *     instance space (the same space the whole app navigates). Resolved and made
+ *     clickable through the shared {@link NavLink} — the one link concept that refs
+ *     and rels are expected to adopt later;
+ *   - **text styling** on the plain runs between those: `**bold**`/`__bold__`,
+ *     `*italic*`/`_italic_`, and `~~strikethrough~~`.
+ *
+ * Anything else is passed through verbatim. `parse` is the single seam every entry
+ * point goes through, so there is one place to teach the grammar.
+ */
+
+/** Escape a plain-text run so it can be dropped into HTML (`parse` emits HTML now
+ *  that some tokens — math, code, emphasis — render to markup). */
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** Style a plain-text run (one of the stretches between the atomic tokens): escape
+ *  it, then apply emphasis. Bold (`**`/`__`) runs before italic (`*`/`_`) so a
+ *  double marker isn't mistaken for two single ones; non-greedy so neighbours don't
+ *  merge. The markers (`* _ ~`) survive `escapeHtml`, so styling the escaped text
+ *  is safe. */
+function styleText(text: string): string {
+  return escapeHtml(text)
+    .replace(/~~(.+?)~~/g, "<del>$1</del>")
+    .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
+    .replace(/__(.+?)__/g, "<strong>$1</strong>")
+    .replace(/\*(.+?)\*/g, "<em>$1</em>")
+    .replace(/_(.+?)_/g, "<em>$1</em>");
+}
+
+/** The non-text tokens, in one alternation matched in source order: `$$…$$` math
+ *  (group 1; `[\s\S]` so a formula may span lines), a `` `code` `` span (group 2),
+ *  or a `[label](target)` link (groups 3 = label, 4 = target). Non-greedy so
+ *  adjacent tokens don't merge. The label may contain a balanced `[…]` (so a path
+ *  used as its own label — `[/children[0]](/children[0])` — works), but a stray `]`
+ *  is not a label, so a non-link `[a]` in prose is left alone. */
+const TOKEN = /\$\$([\s\S]+?)\$\$|`([^`]+?)`|\[((?:[^\[\]]|\[[^\]]*\])*?)\]\(([^)]+?)\)/g;
+
+/** Parse marklower into React nodes. Most syntax renders to an HTML string (math,
+ *  code, emphasis), accumulated and flushed into `<span>`s; a link must be a real
+ *  element so it navigates in-app (an HTML `<a href>` would reload), so the result
+ *  is a node list, not one HTML string. `documentPath` anchors a link's `/…`
+ *  (document-relative) target. */
+function parse(value: unknown, onNavigate: (path: string) => void, documentPath?: string): ReactNode[] {
+  const src = String(value ?? "");
+  const nodes: ReactNode[] = [];
+  let html = ""; // buffer of HTML-rendered runs between links
+  let key = 0;
+  const flush = () => {
+    if (!html) return;
+    nodes.push(<span key={key++} dangerouslySetInnerHTML={{ __html: html }} />);
+    html = "";
+  };
+  let last = 0;
+  for (const m of src.matchAll(TOKEN)) {
+    html += styleText(src.slice(last, m.index)); // plain run before this token
+    if (m[1] !== undefined) {
+      html += renderMath(m[1], false); // $$ inline math $$
+    } else if (m[2] !== undefined) {
+      html += `<code>${escapeHtml(m[2])}</code>`; // `code` — contents literal
+    } else {
+      // [label](target) — a real anchor so it navigates in JSON instance space; the
+      // label keeps its own inline styling.
+      flush();
+      nodes.push(
+        <NavLink key={key++} target={m[4]} documentPath={documentPath} onNavigate={onNavigate}>
+          <span dangerouslySetInnerHTML={{ __html: styleText(m[3]) }} />
+        </NavLink>,
+      );
+    }
+    last = m.index + m[0].length;
+  }
+  html += styleText(src.slice(last));
+  flush();
+  return nodes;
+}
+
+export function MarklowerView({ node, onNavigate }: { node: NodeJson; onNavigate: (path: string) => void }) {
+  return (
+    <div className="marklower">
+      {node.title && <h1 className="chapter-title">{node.title}</h1>}
+      {node.description && <p className="chapter-subtitle">{node.description}</p>}
+      <p className="chapter-prose">{parse(node.value, onNavigate, node.documentPath)}</p>
+    </div>
+  );
+}
+
+/** A marklower chunk embedded inline in a chapter (the chapter supplies the
+ *  surrounding number + anchor). */
+export function MarklowerChunk({ chunk, onNavigate }: { chunk: Chunk; onNavigate: (path: string) => void }) {
+  return <p className="chapter-prose">{parse(chunk.value, onNavigate, chunk.documentPath)}</p>;
+}

package/src/client/renderers/markup.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useState } from "react";
+
+/**
+ * The rendered-HTML body for the markdown/asciidoc page views, plus the control that sets its
+ * line-wrap measure. The **reading width is a URL parameter** — `?width=<ch>`, alongside
+ * `?format=` — so a particular width is a shareable link (the CSV renderer keeps its options in
+ * the query the same way). Default 72ch. The control lives in the tab bar next to the renderer
+ * button (see NodeView), not in the body. Chapter *chunks* render plain `.markup`, unaffected.
+ */
+const DEFAULT_WIDTH_CH = 72;
+const MIN_CH = 20;
+const MAX_CH = 400;
+const params = () => new URLSearchParams(window.location.search);
+
+/** The reading width in `ch` from the URL's `?width=`, or the default (out-of-range ignored). */
+export function markupWidthCh(): number {
+  const w = Number(params().get("width"));
+  return Number.isFinite(w) && w >= MIN_CH && w <= MAX_CH ? w : DEFAULT_WIDTH_CH;
+}
+
+function writeWidth(ch: number): void {
+  const q = params();
+  if (ch === DEFAULT_WIDTH_CH) q.delete("width");
+  else q.set("width", String(ch));
+  const qs = q.toString();
+  window.history.replaceState({}, "", window.location.pathname + (qs ? "?" + qs : ""));
+}
+
+/** The markdown/asciidoc body at the URL-configured reading width. */
+export function Markup({ html }: { html: string }) {
+  return <div className="markup" style={{ maxWidth: `${markupWidthCh()}ch` }} dangerouslySetInnerHTML={{ __html: html }} />;
+}
+
+/**
+ * The width control beside the markdown/asciidoc renderer button (in the tab bar). It accepts
+ * ANY input — a valid measure (20–400 ch) is applied to the URL and `rerender()` re-wraps the
+ * body; an impossible/half-typed value is simply left unapplied and the field turns red (no
+ * editing is blocked). No visible label: the hover title reads "width, ch".
+ */
+export function MarkupWidthControl({ rerender }: { rerender: () => void }) {
+  const urlWidth = markupWidthCh();
+  const [text, setText] = useState(String(urlWidth));
+  useEffect(() => setText(String(urlWidth)), [urlWidth]); // resync when the URL changes (nav / apply)
+  const n = Number(text);
+  const valid = text.trim() !== "" && Number.isInteger(n) && n >= MIN_CH && n <= MAX_CH;
+  return (
+    <input
+      className={"markup-width" + (valid ? "" : " invalid")}
+      type="text"
+      inputMode="numeric"
+      title="width, ch"
+      value={text}
+      onChange={(e) => {
+        const v = e.target.value;
+        setText(v);
+        const num = Number(v);
+        if (v.trim() !== "" && Number.isInteger(num) && num >= MIN_CH && num <= MAX_CH) {
+          writeWidth(num);
+          rerender();
+        }
+      }}
+    />
+  );
+}

package/src/client/renderers/media.tsx

@@ -0,0 +1,19 @@
+import { NodeJson, blobUrl } from "../api";
+
+/**
+ * Renderer for a file-backed HTML document (`<iframe>`), pointing at the server's `/api/blob`
+ * endpoint, which streams the file's raw bytes with its inferred Content-Type — so there is no
+ * base64 round-trip through the JSON API. (Images live in `imagemap.tsx`: a pan/zoom viewer.)
+ */
+export function HtmlView({ node }: { node: NodeJson }) {
+  // sandboxed: same-origin so the page's own CSS/images (served from /api/blob)
+  // load, but no scripts run — a saved web page renders without taking over.
+  return (
+    <iframe
+      className="filehtml"
+      src={blobUrl(node.path)}
+      sandbox="allow-same-origin"
+      title={node.title ?? node.path}
+    />
+  );
+}

package/src/client/renderers/panzoom.ts

@@ -0,0 +1,101 @@
+import L from "leaflet";
+
+/**
+ * The unified pan/zoom/select gesture model for a Leaflet map (shared by the image viewer and the
+ * KML map, see the UI guide). It overrides Leaflet's defaults so SELECTING is the primary gesture:
+ *
+ *   - plain DRAG    → rubber-band a selection rectangle (→ `onSelect`, to annotate the region)
+ *   - ctrl/alt DRAG → pan (grab-and-drag the canvas)
+ *   - plain WHEEL   → pan vertically (scroll the canvas, like scrolling text)
+ *   - ctrl/alt WHEEL→ zoom around the cursor
+ *
+ * When `onSelect` is omitted (e.g. an inline chapter chunk, which has no annotation target), plain
+ * drag PANS instead (Leaflet's default) and the plain wheel is left alone so the page keeps
+ * scrolling — only ctrl/alt-wheel zoom is added. Returns a disposer to unwire everything.
+ */
+export interface GestureOptions {
+  /** A plain-drag rectangle finished. `bounds` is in the map's coordinate space (CRS.Simple pixels
+   *  for an image, lat/lng for a map); `screen` is the viewport point to anchor the menu at. */
+  onSelect?: (bounds: L.LatLngBounds, screen: { x: number; y: number }) => void;
+  /** The live rubber-band color (the current highlight color). */
+  color?: () => string;
+}
+
+const hasMod = (e: MouseEvent | WheelEvent): boolean => e.ctrlKey || e.altKey || e.metaKey;
+
+export function wireGestures(map: L.Map, opts: GestureOptions): () => void {
+  const container = map.getContainer();
+  const selectable = !!opts.onSelect;
+
+  // Selecting needs drag free for the rubber-band; without it, keep Leaflet's drag-to-pan.
+  if (selectable) map.dragging.disable();
+  map.scrollWheelZoom.disable(); // we drive the wheel ourselves (pan vs. zoom by modifier)
+  map.doubleClickZoom.disable();
+  map.boxZoom.disable();
+
+  let band: L.Rectangle | null = null;
+  let start: L.LatLng | null = null;
+  let startPt: L.Point | null = null;
+  let panning = false;
+  let panPrev: L.Point | null = null;
+
+  const onDown = (e: L.LeafletMouseEvent) => {
+    if (e.originalEvent.button !== 0) return; // left button only — right/middle never select or pan
+    if (hasMod(e.originalEvent)) {
+      if (!selectable) return; // dragging still enabled → Leaflet pans natively
+      panning = true; // modifier-drag → manual pan
+      panPrev = e.containerPoint;
+      L.DomUtil.disableTextSelection();
+    } else if (selectable) {
+      start = e.latlng; // plain drag → rubber-band a selection
+      startPt = e.containerPoint;
+      const c = opts.color?.() ?? "#f9e2af";
+      // a bold dashed "marching ants" rubber-band so the selection is clearly visible over a busy map
+      band = L.rectangle(L.latLngBounds(e.latlng, e.latlng), { className: "yo-band", color: c, weight: 3, dashArray: "6 4", fillColor: c, fillOpacity: 0.25, interactive: false }).addTo(map);
+      L.DomUtil.disableTextSelection();
+    }
+  };
+  const onMove = (e: L.LeafletMouseEvent) => {
+    if (panning && panPrev) {
+      map.panBy(panPrev.subtract(e.containerPoint), { animate: false });
+      panPrev = e.containerPoint;
+    } else if (band && start) {
+      band.setBounds(L.latLngBounds(start, e.latlng));
+    }
+  };
+  const onUp = (e: L.LeafletMouseEvent) => {
+    L.DomUtil.enableTextSelection();
+    if (panning) { panning = false; panPrev = null; return; }
+    if (band && start && startPt) {
+      const bounds = L.latLngBounds(start, e.latlng);
+      const moved = startPt.distanceTo(e.containerPoint) >= 4; // ignore a click (zero-size drag)
+      band.remove();
+      band = null; start = null; startPt = null;
+      const oe = e.originalEvent;
+      if (moved) opts.onSelect!(bounds, { x: oe.clientX, y: oe.clientY });
+    }
+  };
+  map.on("mousedown", onDown);
+  map.on("mousemove", onMove);
+  map.on("mouseup", onUp);
+
+  const onWheel = (ev: WheelEvent) => {
+    if (hasMod(ev)) {
+      ev.preventDefault();
+      map.setZoomAround(map.mouseEventToLatLng(ev), map.getZoom() + (ev.deltaY < 0 ? 1 : -1));
+    } else if (selectable) {
+      ev.preventDefault(); // a full image/map view pans vertically on a plain wheel
+      map.panBy([0, ev.deltaY], { animate: false });
+    }
+    // else (chunk, plain wheel): let the event bubble so the page scrolls
+  };
+  container.addEventListener("wheel", onWheel, { passive: false });
+
+  return () => {
+    map.off("mousedown", onDown);
+    map.off("mousemove", onMove);
+    map.off("mouseup", onUp);
+    container.removeEventListener("wheel", onWheel);
+    band?.remove();
+  };
+}