yamlover 0.3.0

package/src/client/renderers/explorer.tsx

@@ -0,0 +1,209 @@
+import { useEffect, useState } from "react";
+import { NodeJson, fetchTagged } from "../api";
+import { asLink, Link } from "../render";
+import { typeIcon } from "../icons";
+import { TAG_FORMAT, tagLabel, tagBody, resolveTagColor } from "./tag";
+import { displayPath, displayKey } from "../paths";
+import { touchesYamlover, useDiffBump } from "../live";
+
+const ANNOTATION_FORMAT = "x-yamlover-annotation";
+const MIXED_KEY = "$yamloverMixed";
+
+// ---- the view mode: a URL parameter (`?view=`), so a view is a shareable link ---- //
+
+const VIEWS = ["large", "small"] as const;
+type ViewMode = (typeof VIEWS)[number];
+const DEFAULT_VIEW: ViewMode = "large";
+const params = () => new URLSearchParams(window.location.search);
+
+/** The grid view from the URL's `?view=`, or the default (an unknown value ignored). */
+export function explorerViewMode(): ViewMode {
+  const v = params().get("view");
+  return (VIEWS as readonly string[]).includes(v ?? "") ? (v as ViewMode) : DEFAULT_VIEW;
+}
+
+function writeViewMode(v: ViewMode): void {
+  const q = params();
+  if (v === DEFAULT_VIEW) q.delete("view");
+  else q.set("view", v);
+  const qs = q.toString();
+  window.history.replaceState({}, "", window.location.pathname + (qs ? "?" + qs : ""));
+}
+
+/** The view selector beside the explorer tab (the renderer's `config` hook) — writes
+ *  `?view=` and rerenders, like the plaintext encoding control. */
+export function ExplorerViewControl({ rerender }: { rerender: () => void }) {
+  return (
+    <label className="enc-control">
+      view{" "}
+      <select
+        value={explorerViewMode()}
+        onChange={(e) => {
+          writeViewMode(e.target.value as ViewMode);
+          rerender();
+        }}
+      >
+        <option value="large">large icons</option>
+        <option value="small">small icons</option>
+      </select>
+    </label>
+  );
+}
+
+/**
+ * The EXPLORER renderer — a directory (or a tag) as a desktop file manager:
+ * every member an icon + label, with the node's reverse UPLINKS (`relations`:
+ * the `..` parent and each upstream `*`/`~` source) leading the grid as
+ * visually distinct items. Two views, chosen by the `?view=` URL parameter
+ * (a renderer param, like the markup width or the CSV options): **large
+ * icons** (the default — tiles, the icon above the label) and **small icons**
+ * (rows, the icon beside the label).
+ *
+ * It claims two shapes:
+ *   - a node stored as a filesystem directory (`concrete` `dir`/`yamlover`,
+ *     the registry's concrete fallback) — ALL members show, not just files:
+ *     scalar members read `key: value`, containers and binaries link onward;
+ *   - a tag (`x-yamlover-tag`) — the members are the MATERIALS filed under it
+ *     (GET /api/tagged: annotations resolved to their `target`, deduped),
+ *     alongside its owned fields (subtags as colored badges); the mediating
+ *     annotation nodes themselves stay out of the grid.
+ */
+
+/** One grid item: a navigable link marker (or a defensive non-link member). */
+export interface ExplorerItem {
+  key: string; // the label source: a member key, `[i]`, or a relation key (`..`, `/eve`, …)
+  link: Link | null;
+  raw?: unknown; // the value when it is not a link marker (rendered inert)
+  up?: boolean; // an uplink (relations) item — shown first, styled distinct
+}
+
+/** The uplink items: the node's `relations` in server order (`..` always first). */
+export function uplinkItems(relations?: Record<string, unknown>): ExplorerItem[] {
+  return Object.entries(relations ?? {})
+    .map(([key, v]) => ({ key, link: asLink(v), up: true }))
+    .filter((it) => it.link != null);
+}
+
+/** The member items, from any depth-1 projection shape: a plain object's entries, an array's
+ *  items, or a `$yamloverMixed` marker's entries (the omni self-value is the BODY — shown in
+ *  the header, not the grid). At depth 1 every member arrives as a `$yamloverLink` marker;
+ *  a non-link value is kept defensively as an inert label. */
+export function memberItems(node: NodeJson): ExplorerItem[] {
+  const v = node.value;
+  if (Array.isArray(v)) return v.map((item, i) => ({ key: `[${i}]`, link: asLink(item), raw: item }));
+  if (!v || typeof v !== "object") return [];
+  const mixed = (v as Record<string, unknown>)[MIXED_KEY] as
+    | { entries?: { key: string | null; value: unknown }[] }
+    | undefined;
+  if (Object.keys(v).length === 1 && mixed?.entries) {
+    return mixed.entries.map((e, i) => ({ key: e.key ?? `[${i}]`, link: asLink(e.value), raw: e.value }));
+  }
+  return Object.entries(v as Record<string, unknown>).map(([key, val]) => ({ key, link: asLink(val), raw: val }));
+}
+
+/** A scalar member's value as a short label tail (`key: <this>`) — its first line,
+ *  capped (a long text would bloat the DOM; the CSS ellipsis only hides overflow). */
+function scalarText(v: unknown): string {
+  if (v === null || v === undefined) return "~";
+  const line = String(v).split("\n", 1)[0];
+  return line.length > 80 ? line.slice(0, 79) + "…" : line;
+}
+
+/** A scalar whose format marks it file-like CONTENT (a media type such as `text/markdown`,
+ *  or an `x-yamlover-…` shape) — its value is the whole document, not a datum: the grid
+ *  shows just the name (the icon already says what it is). A schema VALUE format (`date`,
+ *  `email`, …) keeps the `key: value` form. */
+function isDocFormat(f?: string | null): boolean {
+  return !!f && (f.includes("/") || f.startsWith("x-yamlover-"));
+}
+
+function Item({ it, onNavigate }: { it: ExplorerItem; onNavigate: (path: string) => void }) {
+  const link = it.link;
+  if (!link) {
+    // not a marker (unexpected at depth 1) — an inert label, no navigation
+    return (
+      <span className="dirview-item">
+        <span className="dirview-icon t-bin">•</span>
+        <span className="dirview-label">{it.key}: {scalarText(it.raw)}</span>
+      </span>
+    );
+  }
+  const g = typeIcon(link.type ?? link.kind, link.format ?? null, link.concrete);
+  // an uplink labels by its (decoded) relation key; a member by title, else its key
+  const name = it.up ? displayKey(it.key) : link.title ?? it.key;
+  const label =
+    link.format === TAG_FORMAT ? (
+      // a tag member (e.g. a subtag) keeps its badge color everywhere
+      <span className="tagtag" style={{ background: resolveTagColor({ name, color: link.color }) }}>{name}</span>
+    ) : link.kind === "scalar" && !isDocFormat(link.format) ? (
+      <>
+        {name}: <span className="val">{scalarText(link.value)}</span>
+      </>
+    ) : (
+      name
+    );
+  return (
+    <a
+      className={"dirview-item" + (it.up ? " dirview-up" : "")}
+      href={link.path}
+      title={displayPath(link.path)}
+      onClick={(e) => {
+        e.preventDefault();
+        onNavigate(link.path);
+      }}
+    >
+      <span className={"dirview-icon " + g.cls} title={g.title}>{g.glyph}</span>
+      <span className="dirview-label">{label}</span>
+    </a>
+  );
+}
+
+export function ExplorerView({ node, onNavigate }: { node: NodeJson; onNavigate: (path: string) => void }) {
+  const isTag = node.format === TAG_FORMAT;
+  // a tag's materials (annotations resolved to their targets) — fetched per tag page, refetched
+  // when a diff (live.ts) touches a `.yamlover` file (an annotation created/deleted anywhere)
+  const [tagged, setTagged] = useState<Link[]>([]);
+  const diffBump = useDiffBump(touchesYamlover);
+  useEffect(() => {
+    setTagged([]);
+    if (!isTag) return;
+    let cancelled = false;
+    fetchTagged(node.path)
+      .then((arr) => {
+        if (!cancelled) setTagged(arr.map(asLink).filter((l): l is Link => l != null));
+      })
+      .catch(() => {}); // the owned members still show
+    return () => {
+      cancelled = true;
+    };
+  }, [node.path, isTag, diffBump]);
+
+  const ups = uplinkItems(node.relations);
+  let members = memberItems(node);
+  if (isTag) {
+    // the raw back-edge members are the mediating ANNOTATION nodes — the grid shows the
+    // materials from /api/tagged instead (directly-tagged nodes are in both → dedup by path)
+    members = members.filter((m) => m.link?.format !== ANNOTATION_FORMAT);
+    const have = new Set(members.map((m) => m.link?.path).filter(Boolean));
+    for (const l of tagged) if (!have.has(l.path)) members.push({ key: tagLabel(l.path, l.title), link: l });
+  }
+  const items = [...ups, ...members];
+
+  // a tag page's description is its BODY (the header bar already names the node)
+  const desc = (isTag ? tagBody(node.value) : null) ?? node.description;
+  return (
+    <div className="explorerview">
+      {desc && (
+        <div className="dirhead">
+          <p className="tagdesc">{desc}</p>
+        </div>
+      )}
+      <div className={"dirview" + (explorerViewMode() === "large" ? " dirview-lg" : "")}>
+        {items.map((it, i) => (
+          <Item key={`${it.up ? "^" : ""}${it.link?.path ?? it.key}#${i}`} it={it} onNavigate={onNavigate} />
+        ))}
+        {items.length === 0 && <span className="dirview-empty">empty</span>}
+      </div>
+    </div>
+  );
+}

package/src/client/renderers/fb2.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useState } from "react";
+import { NodeJson, blobUrl } from "../api";
+
+const XLINK = "http://www.w3.org/1999/xlink";
+// Characters illegal in XML 1.0 (control codes other than tab/newline/cr). FB2
+// generators frequently leave these in; strict parsing rejects them, so drop.
+// Built from an escaped string to keep literal control bytes out of the source.
+const BAD_XML = new RegExp("[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F]", "g");
+
+/** Decode the file's bytes using the encoding named in its XML declaration —
+ *  FB2 is frequently windows-1251 (Cyrillic), not UTF-8 — then strip the stray
+ *  control characters that would otherwise fail strict XML parsing. */
+function decodeXml(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  const head = new TextDecoder("latin1").decode(bytes.subarray(0, 256));
+  const enc = (head.match(/encoding=["']([^"']+)["']/i)?.[1] || "utf-8").toLowerCase();
+  let text: string;
+  try {
+    text = new TextDecoder(enc).decode(bytes);
+  } catch {
+    text = new TextDecoder("utf-8").decode(bytes);
+  }
+  return text.replace(BAD_XML, "");
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Recursively turn an FB2 body element into HTML. `images` maps a `<binary>`
+ *  id to a data URL. Switches on `localName`, so the FB2 namespace is ignored. */
+function toHtml(node: Node, images: Map<string, string>): string {
+  if (node.nodeType === 3) return esc(node.textContent || ""); // text
+  if (node.nodeType !== 1) return "";
+  const el = node as Element;
+  const kids = () => Array.from(el.childNodes).map((n) => toHtml(n, images)).join("");
+  switch (el.localName) {
+    case "section": return `<section class="fb2-section">${kids()}</section>`;
+    case "title": return `<div class="fb2-title">${kids()}</div>`;
+    case "subtitle": return `<p class="fb2-subtitle">${kids()}</p>`;
+    case "p": return `<p>${kids()}</p>`;
+    case "empty-line": return "<br/>";
+    case "emphasis": return `<em>${kids()}</em>`;
+    case "strong": return `<strong>${kids()}</strong>`;
+    case "strikethrough": return `<s>${kids()}</s>`;
+    case "sub": return `<sub>${kids()}</sub>`;
+    case "sup": return `<sup>${kids()}</sup>`;
+    case "code": return `<code>${kids()}</code>`;
+    case "epigraph":
+    case "cite": return `<blockquote class="fb2-cite">${kids()}</blockquote>`;
+    case "text-author": return `<p class="fb2-text-author">${kids()}</p>`;
+    case "poem": return `<div class="fb2-poem">${kids()}</div>`;
+    case "stanza": return `<div class="fb2-stanza">${kids()}</div>`;
+    case "v": return `<div class="fb2-v">${kids()}</div>`;
+    case "a": return `<span class="fb2-a">${kids()}</span>`; // FB2 links are intra-doc
+    case "image": {
+      const href =
+        el.getAttributeNS(XLINK, "href") || el.getAttribute("l:href") || el.getAttribute("href") || "";
+      const src = images.get(href.replace(/^#/, ""));
+      return src ? `<img class="fb2-img" src="${src}" alt=""/>` : "";
+    }
+    case "title-info":
+    case "description":
+    case "binary":
+      return ""; // metadata / payload, not body prose
+    default: return kids();
+  }
+}
+
+interface Book {
+  title?: string;
+  author?: string;
+  cover?: string;
+  html: string;
+}
+
+/**
+ * Renderer for an `application/x-fictionbook+xml` (`.fb2`) ebook. The file is
+ * served as bytes; here we decode it (honoring its declared encoding), parse the
+ * FictionBook XML, and present the book — cover, title, author, then the body
+ * with its sections/paragraphs/poems and embedded images inlined.
+ */
+export function Fb2View({ node }: { node: NodeJson }) {
+  const [book, setBook] = useState<Book | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setBook(null);
+    setError(null);
+    fetch(blobUrl(node.path))
+      .then((r) => r.arrayBuffer())
+      .then((buf) => {
+        if (cancelled) return;
+        const doc = new DOMParser().parseFromString(decodeXml(buf), "application/xml");
+        const perr = doc.getElementsByTagName("parsererror")[0];
+        if (perr) throw new Error(perr.textContent?.trim().split("\n")[0] || "invalid FB2 XML");
+
+        const images = new Map<string, string>();
+        for (const b of Array.from(doc.getElementsByTagNameNS("*", "binary"))) {
+          const id = b.getAttribute("id");
+          if (id) {
+            const ct = b.getAttribute("content-type") || "image/jpeg";
+            images.set(id, `data:${ct};base64,${(b.textContent || "").replace(/\s+/g, "")}`);
+          }
+        }
+
+        const ti = doc.getElementsByTagNameNS("*", "title-info")[0] as Element | undefined;
+        const at = (e: Element | undefined, name: string) =>
+          e?.getElementsByTagNameNS("*", name)[0]?.textContent?.trim() || "";
+        const title = at(ti, "book-title") || undefined;
+        const author =
+          ti &&
+          Array.from(ti.getElementsByTagNameNS("*", "author"))
+            .map((a) =>
+              [at(a, "first-name"), at(a, "middle-name"), at(a, "last-name")]
+                .filter(Boolean)
+                .join(" ") || at(a, "nickname"),
+            )
+            .filter(Boolean)
+            .join(", ");
+        const coverImg = ti?.getElementsByTagNameNS("*", "coverpage")[0]?.getElementsByTagNameNS("*", "image")[0];
+        const coverId = (
+          coverImg?.getAttributeNS(XLINK, "href") || coverImg?.getAttribute("l:href") || ""
+        ).replace(/^#/, "");
+
+        const bodies = Array.from(doc.getElementsByTagNameNS("*", "body"));
+        const main = bodies.find((b) => b.getAttribute("name") !== "notes") || bodies[0];
+        const html = main ? Array.from(main.childNodes).map((n) => toHtml(n, images)).join("") : "";
+
+        setBook({ title, author: author || undefined, cover: coverId ? images.get(coverId) : undefined, html });
+      })
+      .catch((e) => !cancelled && setError(String((e as Error).message || e)));
+    return () => {
+      cancelled = true;
+    };
+  }, [node.path]);
+
+  if (error) return <div className="error">fb2: {error}</div>;
+  if (!book) return <div className="loading">loading FB2…</div>;
+  return (
+    <div className="text fb2">
+      {book.cover && <img className="fb2-cover" src={book.cover} alt="" />}
+      {book.title && <h1 className="chapter-title">{book.title}</h1>}
+      {book.author && <p className="chapter-subtitle">{book.author}</p>}
+      <div className="markup fb2-body" dangerouslySetInnerHTML={{ __html: book.html }} />
+    </div>
+  );
+}

package/src/client/renderers/headings.ts

@@ -0,0 +1,69 @@
+import { useEffect } from "react";
+
+/**
+ * Shared heading machinery for the rendered-markup formats (Markdown and AsciiDoc).
+ *
+ * A `.md`/`.adoc` page is a single HTML blob dumped via `dangerouslySetInnerHTML`,
+ * so on its own a heading is not addressable. {@link anchorizeHeadings} gives every
+ * heading a stable `id` and a small `§` link to it, mirroring the way GitHub renders
+ * the same documents — so a deep link like `<page>#<slug>` lands on, and scrolls to,
+ * one section. This is the prose-document counterpart of the chapter renderer's `§N`
+ * chunk anchors (see `chapter.tsx`): there the locator is the chunk's path; here it
+ * is the heading's slug.
+ */
+
+/** GitHub-style slug of a heading's text: lowercase, punctuation dropped, runs of
+ *  whitespace collapsed to single hyphens. Unicode letters/numbers are kept. */
+function slugify(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .replace(/\s+/g, "-");
+}
+
+/** `base`, suffixed `-2`, `-3`, … until it is not already in `used` (which it is
+ *  then added to). Empty `base` (a heading with no sluggable text) yields "". */
+function uniqueId(base: string, used: Set<string>): string {
+  if (!base) return "";
+  let id = base;
+  for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+  used.add(id);
+  return id;
+}
+
+/** Give every heading in a block of rendered markup an `id` and a leading `§`
+ *  anchor link to it (placed first so it sits in the left gutter, like a chapter
+ *  chunk's `§N` index). An id already present (Asciidoctor stamps section ids) is
+ *  kept — so its anchor matches the document's own cross-references — otherwise a
+ *  de-duplicated slug of the heading text is assigned. Returns the rewritten HTML.
+ *  Runs in the browser/jsdom; with no `DOMParser` (or no headings) it is a no-op. */
+export function anchorizeHeadings(html: string): string {
+  if (typeof DOMParser === "undefined" || !html.includes("<h")) return html;
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const used = new Set<string>();
+  for (const h of doc.querySelectorAll("h1, h2, h3, h4, h5, h6")) {
+    // slug from the text before inserting the anchor, so the `§` is not part of it
+    const id = uniqueId(h.id || slugify(h.textContent ?? ""), used);
+    if (!id) continue;
+    h.id = id;
+    const a = doc.createElement("a");
+    a.className = "header-anchor";
+    a.href = `#${id}`;
+    a.setAttribute("aria-label", "Link to this section");
+    a.textContent = "§";
+    h.insertBefore(a, h.firstChild);
+  }
+  return doc.body.innerHTML;
+}
+
+/** Scroll to the element named by the URL hash once `dep` (the rendered node)
+ *  settles. A deep link `<page>#<slug>` lands on the page, but the value is fetched
+ *  async — after the browser's own one-shot scroll — so re-scroll when it arrives.
+ *  The same pattern the chapter renderer uses for `#/chunks[n]`. */
+export function useHashScroll(dep: unknown): void {
+  useEffect(() => {
+    const id = decodeURIComponent(window.location.hash.slice(1));
+    if (id) document.getElementById(id)?.scrollIntoView?.(); // optional-call: absent in jsdom
+  }, [dep]);
+}

package/src/client/renderers/heic.tsx

@@ -0,0 +1,23 @@
+import heic2any from "heic2any";
+import { NodeJson } from "../api";
+import { DecodedImageView } from "./decoded";
+
+/**
+ * Renders an HEIC/HEIF image (`image/heic`, `.heic`/`.heif`) — the format iPhones
+ * shoot. It's HEVC-encoded and patent-encumbered, with no browser support, so we
+ * decode it with `heic2any` (libheif compiled to wasm), which converts the bytes
+ * to a PNG blob. An HEIC may hold an image *sequence* (burst/Live Photo); when it
+ * does, `heic2any` returns several blobs and we show each.
+ */
+export function HeicView({ node }: { node: NodeJson }) {
+  return (
+    <DecodedImageView
+      node={node}
+      label="heic"
+      decode={async (buf) => {
+        const out = await heic2any({ blob: new Blob([buf]), toType: "image/png" });
+        return Array.isArray(out) ? out : [out];
+      }}
+    />
+  );
+}

package/src/client/renderers/imagemap.tsx

@@ -0,0 +1,157 @@
+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 { Annotation } from "../api";
+import { DEFAULT_COLOR, colorOf, editable, useAnnotationMenu, useMaterialAnnotations } from "./annotate";
+import { wireGestures } from "./panzoom";
+
+/** A rectangular annotation region in the image's own pixel space (origin top-left). `ann` is the
+ *  source annotation when it is a real saved one (→ clickable to edit); absent for the live preview. */
+export interface ImageRegion { x: number; y: number; w: number; h: number; title?: string; color?: string; ann?: Annotation }
+
+const num = (v: unknown): number => Number(v) || 0;
+
+/** The `rect`-type annotations, as pixel regions to overlay on the image. */
+function imageRegions(anns: Annotation[]): ImageRegion[] {
+  return anns
+    .filter((a) => a.selector?.type === "rect")
+    .map((a) => ({ x: num(a.selector!.x), y: num(a.selector!.y), w: num(a.selector!.w), h: num(a.selector!.h), title: a.description, color: colorOf(a), ann: editable(a) ? a : undefined }));
+}
+
+/**
+ * Pan/zoom image viewer — the same widget the KML map uses, over a flat picture. The image is an
+ * `imageOverlay` on a `CRS.Simple` map sized to its natural pixels; the view fits it initially.
+ * Gestures follow the unified model (see {@link wireGestures} / the UI guide): plain drag selects a
+ * region (when `onSelectRegion` is set), ctrl/alt-drag pans, plain wheel pans vertically, ctrl/alt-
+ * wheel zooms. The map is built once (per `src`); regions redraw in place without resetting the view.
+ */
+export function PanZoomImage({
+  src, className, regions, onSelectRegion, onRegionClick, selectColor,
+}: {
+  src: string;
+  className: string;
+  regions?: ImageRegion[];
+  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 sizeRef = useRef({ w: 1, h: 1 });
+  const onSelectRef = useRef(onSelectRegion);
+  const onRegionClickRef = useRef(onRegionClick);
+  const colorRef = useRef(selectColor);
+  const [error, setError] = useState<string | null>(null);
+  const [ready, setReady] = useState(0); // bumps once the map (and its overlay layer) exist
+  const regionsKey = JSON.stringify(regions ?? []);
+  const selectable = !!onSelectRegion; // fixed per instance: full view annotates, chunk doesn't
+
+  useEffect(() => { onSelectRef.current = onSelectRegion; onRegionClickRef.current = onRegionClick; colorRef.current = selectColor; });
+
+  // Build the map once per src; gestures + the overlay layer live with it.
+  useEffect(() => {
+    let cancelled = false;
+    let dispose: (() => void) | null = null;
+    setError(null);
+    const img = new Image();
+    img.onload = () => {
+      if (cancelled || !ref.current) return;
+      const w = img.naturalWidth || 1;
+      const h = img.naturalHeight || 1;
+      sizeRef.current = { w, h };
+      // CRS.Simple: coordinates are raw pixels (y, x); negative minZoom allows zooming far out.
+      const map = L.map(ref.current, { crs: L.CRS.Simple, minZoom: -8, attributionControl: false, zoomSnap: 0 });
+      const bounds: L.LatLngBoundsExpression = [[0, 0], [h, w]];
+      L.imageOverlay(src, bounds).addTo(map);
+      map.fitBounds(bounds); // initial view frames the whole image
+      layerRef.current = L.layerGroup().addTo(map);
+      mapRef.current = map;
+      dispose = wireGestures(map, {
+        color: () => colorRef.current?.() ?? DEFAULT_COLOR,
+        onSelect: selectable
+          ? (b, screen) => {
+              // image pixels have y from the top; CRS.Simple lat is from the bottom → flip.
+              const { h: ih } = sizeRef.current;
+              const west = b.getWest(), east = b.getEast(), south = b.getSouth(), north = b.getNorth();
+              onSelectRef.current?.(
+                { type: "rect", x: Math.round(west), y: Math.round(ih - north), w: Math.round(east - west), h: Math.round(north - south) },
+                screen,
+              );
+            }
+          : undefined,
+      });
+      setReady((r) => r + 1);
+    };
+    img.onerror = () => { if (!cancelled) setError("could not load image"); };
+    img.src = src;
+    return () => {
+      cancelled = true;
+      dispose?.();
+      mapRef.current?.remove();
+      mapRef.current = null;
+      layerRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [src]);
+
+  // Draw the region rectangles into the overlay layer — in place, so creating one keeps the view.
+  useEffect(() => {
+    const lg = layerRef.current;
+    if (!lg) return;
+    lg.clearLayers();
+    const { h } = sizeRef.current;
+    for (const r of regions ?? []) {
+      const c = r.color || DEFAULT_COLOR;
+      // image y is from the top; CRS.Simple lat from the bottom, so flip y
+      const rect = L.rectangle([[h - r.y, r.x], [h - (r.y + r.h), r.x + r.w]], {
+        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">image: {error}</div>}
+      <div ref={ref} className={className + (selectable ? " yo-selectable" : "")} />
+    </>
+  );
+}
+
+export function ImageView({ node }: { node: NodeJson }) {
+  const material = useMaterialAnnotations(node.path);
+  const { openCreate, openEdit, palette, preview, color } = useAnnotationMenu(material);
+  // include the live PREVIEW selector so the rectangle stays drawn while the menu is open
+  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>}
+      <PanZoomImage
+        src={blobUrl(node.path)}
+        regions={imageRegions(shown)}
+        onSelectRegion={openCreate}
+        onRegionClick={openEdit}
+        selectColor={() => color}
+        className="filemap fileimagemap"
+      />
+      {palette}
+    </div>
+  );
+}
+
+/** An image embedded inline in a chapter — pan/zoom only (no annotation target → plain drag pans). */
+export function ImageChunk({ chunk }: { chunk: Chunk }) {
+  return <PanZoomImage src={blobUrl(chunk.path)} className="filemap chunk-map fileimagemap" />;
+}

package/src/client/renderers/kml.ts

@@ -0,0 +1,46 @@
+import { kml as kmlDomToGeoJSON } from "@tmcw/togeojson";
+import { unzipSync, strFromU8 } from "fflate";
+
+/**
+ * The pure (Leaflet-free) half of the map renderer: turn the bytes of a `.kml` or
+ * `.kmz` file into GeoJSON. Kept apart from `map.tsx` so it can be unit-tested
+ * without importing Leaflet (a browser-only library with CSS side effects).
+ *
+ *   - **KML** is XML — decoded as text, parsed to a DOM, then converted with
+ *     `@tmcw/togeojson`.
+ *   - **KMZ** is a ZIP — unzipped (with the already-bundled `fflate`); its first
+ *     `.kml` entry is the document, then the same KML path.
+ */
+
+/** A GeoJSON FeatureCollection (the shape togeojson returns). Loosely typed — the
+ *  map renderer only hands it to Leaflet's `L.geoJSON`. */
+export interface GeoJSON {
+  type: "FeatureCollection";
+  features: unknown[];
+}
+
+/** Whether `bytes` begin with the ZIP local-file signature `PK\x03\x04` — i.e. a
+ *  KMZ rather than a bare KML. Robust regardless of the file's extension. */
+export function isZip(bytes: Uint8Array): boolean {
+  return bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04;
+}
+
+/** Parse a KML XML string into GeoJSON via a DOM (available in the browser and in
+ *  jsdom tests). */
+export function kmlStringToGeoJSON(xml: string): GeoJSON {
+  const dom = new DOMParser().parseFromString(xml, "application/xml");
+  if (dom.getElementsByTagName("parsererror").length) throw new Error("malformed KML XML");
+  return kmlDomToGeoJSON(dom) as unknown as GeoJSON;
+}
+
+/** Parse `.kml`/`.kmz` bytes into GeoJSON. KMZ is detected by its ZIP signature
+ *  (not just the extension); the first `.kml` entry inside is the document. */
+export function bytesToGeoJSON(bytes: Uint8Array): GeoJSON {
+  if (isZip(bytes)) {
+    const files = unzipSync(bytes);
+    const name = Object.keys(files).find((n) => n.toLowerCase().endsWith(".kml"));
+    if (!name) throw new Error("no .kml document inside the KMZ archive");
+    return kmlStringToGeoJSON(strFromU8(files[name]));
+  }
+  return kmlStringToGeoJSON(new TextDecoder().decode(bytes));
+}