synabun 1.3.0 → 2.0.0

package/neural-interface/public/variant/3d/map-controls.js

@@ -0,0 +1,144 @@
+// ── Memory map input ──
+//
+// Hover → tooltip, click → open the memory, ⌘/Ctrl-click → multi-select,
+// click a label → fly to that island, double-click empty space → frame all,
+// Esc → clear the search, then the selection. Orbit / pan / zoom and the
+// arrow keys belong to OrbitControls (arrows only while the map has focus, so
+// the app's single-key shortcuts keep working everywhere else).
+
+import { isGraphPointerActivity } from '../../shared/graph-activity.js';
+import { clearSearch } from '../../shared/ui-search.js';
+import { escapeHtml } from '../../shared/utils.js';
+
+const CLICK_SLOP = 5; // px a press may move and still count as a click
+
+export function initMapControls({ renderer, view, labels }) {
+  const canvas = renderer.canvas;
+  const tip = document.getElementById('tooltip');
+  const tipCategory = document.getElementById('tooltip-category');
+  const tipPreview = document.getElementById('tooltip-preview');
+  const tipImportance = document.getElementById('tooltip-importance');
+  let down = null;
+  let canvasDown = false;
+  let pickRaf = 0;
+  let lastMove = null;
+  let tipFor = -1;
+
+  const local = (e) => {
+    const r = canvas.getBoundingClientRect();
+    return [e.clientX - r.left, e.clientY - r.top];
+  };
+
+  // What is under the cursor: a memory right under it beats a label (island
+  // labels sit over their island), a label beats a memory a little further off.
+  function resolve(x, y) {
+    const close = view.pickAt(x, y, 6);
+    if (close >= 0) return { i: close, label: null };
+    const label = labels.hitTest(x, y);
+    if (label?.type === 'memory') return { i: label.index, label: null };
+    if (label) return { i: -1, label };
+    return { i: view.pickAt(x, y, 12), label: null };
+  }
+
+  function hideTip() {
+    tip?.classList.remove('visible');
+    tipFor = -1;
+  }
+
+  function showTip(i, e) {
+    if (!tip) return;
+    if (tipFor !== i) {
+      const d = view.describe(i);
+      if (!d) { hideTip(); return; }
+      tipCategory.textContent = d.project ? `${d.category} · ${d.project}` : d.category;
+      tipCategory.style.color = d.color;
+      tipPreview.innerHTML = d.title ? escapeHtml(d.title) : '<span style="opacity:.55">Loading…</span>';
+      tipImportance.textContent = `★ ${d.importance} · ${d.when}`;
+      tipFor = i;
+    }
+    const pad = 16;
+    const w = tip.offsetWidth || 260, h = tip.offsetHeight || 80;
+    const x = Math.min(e.clientX + pad, window.innerWidth - w - 8);
+    const y = e.clientY + pad + h > window.innerHeight ? e.clientY - h - pad : e.clientY + pad;
+    tip.style.left = `${Math.max(8, x)}px`;
+    tip.style.top = `${Math.max(8, y)}px`;
+    tip.classList.add('visible');
+  }
+
+  function hover(e) {
+    if (!isGraphPointerActivity(e, canvas, canvasDown) || e.buttons) {
+      view.setHover(-1);
+      hideTip();
+      canvas.style.cursor = '';
+      return;
+    }
+    const [x, y] = local(e);
+    const { i, label } = resolve(x, y);
+    if (i < 0 && label) {
+      view.setHover(-1);
+      hideTip();
+      canvas.style.cursor = 'pointer';
+      return;
+    }
+    view.setHover(i);
+    canvas.style.cursor = i >= 0 ? 'pointer' : '';
+    if (i >= 0) showTip(i, e);
+    else hideTip();
+  }
+
+  const onPointerMove = (e) => {
+    lastMove = e;
+    if (pickRaf) return;
+    pickRaf = requestAnimationFrame(() => { pickRaf = 0; if (lastMove) hover(lastMove); });
+  };
+
+  canvas.addEventListener('pointermove', onPointerMove);
+  canvas.addEventListener('pointerleave', () => { view.setHover(-1); hideTip(); canvas.style.cursor = ''; });
+  canvas.addEventListener('pointerdown', (e) => {
+    canvasDown = true;
+    down = { x: e.clientX, y: e.clientY, button: e.button };
+    hideTip();
+    canvas.focus({ preventScroll: true });
+  });
+  canvas.addEventListener('wheel', hideTip, { passive: true });
+
+  const onPointerUp = (e) => {
+    const d = down;
+    const wasDown = canvasDown;
+    down = null;
+    canvasDown = false;
+    if (!d || !wasDown || d.button !== 0 || e.button !== 0) return;
+    if (Math.hypot(e.clientX - d.x, e.clientY - d.y) > CLICK_SLOP) return; // a drag, not a click
+    const [x, y] = local(e);
+    const { i, label } = resolve(x, y);
+    if (i >= 0) view.clickPoint(i, { additive: e.metaKey || e.ctrlKey });
+    else if (label) view.clickLabel(label);
+  };
+  window.addEventListener('pointerup', onPointerUp);
+
+  canvas.addEventListener('dblclick', (e) => {
+    const [x, y] = local(e);
+    if (labels.hitTest(x, y) || view.pickAt(x, y) >= 0) return;
+    view.frameAll();
+  });
+
+  // Esc: search first, then selection. Backs off whenever something else owns it.
+  const onKeyDown = (e) => {
+    if (e.key !== 'Escape' || e.defaultPrevented) return;
+    const active = document.activeElement;
+    const owned = active && active !== document.body && active !== canvas;
+    if (owned || document.querySelector('.menubar-item.open, .modal-overlay.open, .settings-modal.open')) return;
+    if (view.searching) { clearSearch(); return; }
+    if (view.selectedId) view.clearSelection();
+  };
+  window.addEventListener('keydown', onKeyDown, true);
+
+  return {
+    hideTip,
+    dispose() {
+      window.removeEventListener('pointerup', onPointerUp);
+      window.removeEventListener('keydown', onKeyDown, true);
+      if (pickRaf) cancelAnimationFrame(pickRaf);
+    },
+  };
+}

package/neural-interface/public/variant/3d/map-data.js

@@ -0,0 +1,251 @@
+// ── Memory map data ──
+//
+// Everything the map needs that is neither DOM nor three.js: parsing
+// `/api/map`, colours, recency, titles, visibility and the camera maths for
+// framing. Kept pure so tests can run it in Node.
+
+export const DIMMED = 0.1;             // aVis of a point outside the search / focus
+export const RECENCY_HALF_LIFE = 30;   // days
+export const DAY_MS = 86_400_000;
+
+/**
+ * `/api/map` JSON → typed arrays and lookups.
+ * Points arrive grouped by island (`island.start … start + count`).
+ */
+export function parseMap(json) {
+  const ids = Array.isArray(json?.ids) ? json.ids : [];
+  const n = ids.length;
+  const islands = Array.isArray(json?.islands) ? json.islands : [];
+  const positions = new Float32Array(3 * n);
+  for (let i = 0; i < 3 * n; i++) positions[i] = Number(json.pos?.[i]) || 0;
+  const importance = new Uint8Array(n);
+  const day = new Int32Array(n);
+  for (let i = 0; i < n; i++) {
+    importance[i] = Math.max(1, Math.min(10, Number(json.imp?.[i]) || 5));
+    day[i] = Number(json.day?.[i]) || 0;
+  }
+  const islandOf = new Uint16Array(n);
+  islands.forEach((isl, k) => islandOf.fill(k, isl.start, Math.min(n, isl.start + isl.count)));
+  const indexOf = new Map();
+  ids.forEach((id, i) => indexOf.set(id, i));
+  const islandIndex = new Map(islands.map((isl, k) => [isl.name, k]));
+  return {
+    rev: String(json?.rev ?? ''),
+    status: json?.status === 'computing' ? 'computing' : 'ready',
+    progress: json?.progress || null,
+    bounds: { radius: Number(json?.bounds?.radius) || 0, height: Number(json?.bounds?.height) || 0 },
+    continents: Array.isArray(json?.continents) ? json.continents : [],
+    islands, islandIndex, ids, n, positions, importance, day, islandOf, indexOf,
+  };
+}
+
+// ── Colour ──
+
+/** '#RRGGBB' or '#RGB' → [r, g, b] in 0..1, sRGB as written (never linearised). */
+export function hexToRgb(hex) {
+  let h = String(hex || '').trim().replace(/^#/, '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  const v = parseInt(h.slice(0, 6), 16);
+  if (!Number.isFinite(v) || h.length < 6) return [0.7, 0.7, 0.75];
+  return [((v >> 16) & 255) / 255, ((v >> 8) & 255) / 255, (v & 255) / 255];
+}
+
+function rgbToHsl([r, g, b]) {
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h / 6, s, l];
+}
+
+function hslToRgb([h, s, l]) {
+  if (s === 0) return [l, l, l];
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const f = (t) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  return [f(h + 1 / 3), f(h), f(h - 1 / 3)];
+}
+
+/** A category colour calmed for the star chart: saturation ≤ 0.55, lightness 0.55–0.72. */
+export function softColor(hex) {
+  const [h, s, l] = rgbToHsl(hexToRgb(hex));
+  return hslToRgb([h, Math.min(s, 0.55), Math.min(0.72, Math.max(0.55, l))]);
+}
+
+export function rgbCss([r, g, b], alpha = 1) {
+  return `rgba(${Math.round(r * 255)},${Math.round(g * 255)},${Math.round(b * 255)},${alpha})`;
+}
+
+// ── Per-point attributes ──
+
+/** 1 for today, halving every RECENCY_HALF_LIFE days, never below 0.35. */
+export function recencyOf(dayNumber, today = Math.floor(Date.now() / DAY_MS)) {
+  const age = Math.max(0, today - dayNumber);
+  return 0.35 + 0.65 * Math.pow(2, -age / RECENCY_HALF_LIFE);
+}
+
+export const sizeOf = (importance) => 0.75 + 0.075 * importance;
+
+/** Build the colour / size / recency attribute arrays for a parsed map. */
+export function pointAttributes(map, colorOfIsland, today) {
+  const color = new Float32Array(3 * map.n);
+  const size = new Float32Array(map.n);
+  const recency = new Float32Array(map.n);
+  const islandColors = map.islands.map((isl) => colorOfIsland(isl.name));
+  for (let i = 0; i < map.n; i++) {
+    const c = islandColors[map.islandOf[i]] || [0.7, 0.7, 0.75];
+    color[3 * i] = c[0]; color[3 * i + 1] = c[1]; color[3 * i + 2] = c[2];
+    size[i] = sizeOf(map.importance[i]);
+    recency[i] = recencyOf(map.day[i], today);
+  }
+  return { color, size, recency, islandColors };
+}
+
+/**
+ * 0 hidden (category off, or deleted here before the server map caught up),
+ * DIMMED (outside the search or the card spotlight), 1 normal. Hidden wins.
+ * @returns {{vis: Float32Array, hidden: number, dimmed: number, islandShown: boolean[]}}
+ */
+export function computeVisibility(map, { activeCategories = null, searchIds = null, focusIds = null, removedIds = null } = {}, out = null) {
+  const vis = out && out.length === map.n ? out : new Float32Array(map.n);
+  const shown = map.islands.map((isl) => !activeCategories || activeCategories.has(isl.name));
+  let hidden = 0, dimmed = 0;
+  for (let i = 0; i < map.n; i++) {
+    const id = map.ids[i];
+    if (!shown[map.islandOf[i]] || (removedIds && removedIds.has(id))) { vis[i] = 0; hidden++; continue; }
+    if ((searchIds && !searchIds.has(id)) || (focusIds && !focusIds.has(id))) { vis[i] = DIMMED; dimmed++; continue; }
+    vis[i] = 1;
+  }
+  return { vis, hidden, dimmed, islandShown: shown };
+}
+
+/**
+ * Start positions for a morph from `oldMap` to `newMap`, in the new order.
+ * Points that are new keep their own position (they fade in rather than fly).
+ */
+export function remapForMorph(oldMap, newMap) {
+  const from = new Float32Array(3 * newMap.n);
+  for (let i = 0; i < newMap.n; i++) {
+    const j = oldMap ? oldMap.indexOf.get(newMap.ids[i]) : undefined;
+    const src = j === undefined ? newMap.positions : oldMap.positions;
+    const k = j === undefined ? i : j;
+    from[3 * i] = src[3 * k]; from[3 * i + 1] = src[3 * k + 1]; from[3 * i + 2] = src[3 * k + 2];
+  }
+  return from;
+}
+
+/** Largest distance any point travels between two position arrays of the same order. */
+export function maxDisplacement(from, to) {
+  let max = 0;
+  for (let i = 0; i + 2 < to.length; i += 3) {
+    const d = Math.hypot(to[i] - from[i], to[i + 1] - from[i + 1], to[i + 2] - from[i + 2]);
+    if (d > max) max = d;
+  }
+  return max;
+}
+
+/** Did anything actually move between two maps (same ids in the same order and same positions)? */
+export function samePositions(a, b) {
+  if (!a || !b || a.n !== b.n) return false;
+  for (let i = 0; i < a.n; i++) if (a.ids[i] !== b.ids[i]) return false;
+  for (let i = 0; i < 3 * a.n; i++) if (a.positions[i] !== b.positions[i]) return false;
+  return true;
+}
+
+// ── Text ──
+
+/** First meaningful line of a memory, without markdown noise. */
+export function titleFromContent(content, max = 90) {
+  const lines = String(content || '').split('\n');
+  let line = '';
+  for (const raw of lines) {
+    const s = raw.replace(/^[\s#>*\-+`|]+/, '').replace(/[*_`~]+/g, '').replace(/\s+/g, ' ').trim();
+    if (s.length >= 3) { line = s; break; }
+  }
+  if (!line) return '';
+  return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}
+
+export function relativeDay(dayNumber, today = Math.floor(Date.now() / DAY_MS)) {
+  const d = today - dayNumber;
+  if (d <= 0) return 'today';
+  if (d === 1) return 'yesterday';
+  if (d < 30) return `${d} days ago`;
+  const date = new Date(dayNumber * DAY_MS);
+  return date.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+}
+
+// ── Framing ──
+
+/** Bounding sphere of a set of point indices (all points when omitted). */
+export function boundsSphere(positions, indices = null) {
+  const count = indices ? indices.length : positions.length / 3;
+  if (!count) return null;
+  let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+  for (let q = 0; q < count; q++) {
+    const i = indices ? indices[q] : q;
+    const x = positions[3 * i], y = positions[3 * i + 1], z = positions[3 * i + 2];
+    if (x < minX) minX = x; if (x > maxX) maxX = x;
+    if (y < minY) minY = y; if (y > maxY) maxY = y;
+    if (z < minZ) minZ = z; if (z > maxZ) maxZ = z;
+  }
+  const cx = (minX + maxX) / 2, cy = (minY + maxY) / 2, cz = (minZ + maxZ) / 2;
+  let r = 0;
+  for (let q = 0; q < count; q++) {
+    const i = indices ? indices[q] : q;
+    r = Math.max(r, Math.hypot(positions[3 * i] - cx, positions[3 * i + 1] - cy, positions[3 * i + 2] - cz));
+  }
+  return { x: cx, y: cy, z: cz, r };
+}
+
+/** Camera distance that fits a sphere of radius r (vertical fov in degrees, aspect w/h). */
+export function fitDistance(r, fovDeg, aspect) {
+  const vfov = (fovDeg * Math.PI) / 180;
+  const hfov = 2 * Math.atan(Math.tan(vfov / 2) * aspect);
+  const half = Math.min(vfov, hfov) / 2;
+  return Math.max(r, 1) / Math.sin(half);
+}
+
+// ── Server calls ──
+
+/** GET /api/map. Returns null on 304 (unchanged) and throws on errors. */
+export async function fetchMap(etag = null) {
+  const res = await fetch('/api/map', { headers: etag ? { 'If-None-Match': etag } : {} });
+  if (res.status === 304) return null;
+  if (!res.ok) throw new Error(`map: HTTP ${res.status}`);
+  const json = await res.json();
+  json._etag = res.headers.get('ETag');
+  return json;
+}
+
+const _neighborCache = new Map();
+export async function fetchNeighbors(id, k = 8) {
+  const key = `${id}|${k}`;
+  if (_neighborCache.has(key)) return _neighborCache.get(key);
+  const p = fetch(`/api/map/neighbors/${encodeURIComponent(id)}?k=${k}`)
+    .then((r) => (r.ok ? r.json() : { id, neighbors: [] }))
+    .then((j) => (Array.isArray(j?.neighbors) ? j.neighbors : []))
+    .catch(() => []);
+  _neighborCache.set(key, p);
+  if (_neighborCache.size > 200) _neighborCache.delete(_neighborCache.keys().next().value);
+  return p;
+}
+export function clearNeighborCache() { _neighborCache.clear(); }
+
+export async function requestRebuild() {
+  const res = await fetch('/api/map/rebuild', { method: 'POST' });
+  if (!res.ok) throw new Error(`rebuild: HTTP ${res.status}`);
+  return res.json();
+}

package/neural-interface/public/variant/3d/map-labels.js

@@ -0,0 +1,241 @@
+// ── Memory map labels ──
+//
+// One 2D canvas over the WebGL canvas. Which labels show depends on how big
+// their island is on screen (semantic zoom): continents from far away,
+// islands at mid range, region names once an island fills the view, and a few
+// memory titles up close. Labels are placed greedily by priority and never
+// overlap; they fade in and out. Clicks are hit-tested against what was drawn.
+
+const FONT = "Inter, 'SF Pro Text', system-ui, sans-serif";
+const FADE_MS = 120;
+
+// On-screen island radius (px) at which each tier is shown.
+const TIERS = {
+  continent: [40, 900],
+  island: [18, 1400],
+  region: 260,
+  memory: 320,
+};
+
+export function createLabelLayer(container) {
+  const canvas = document.createElement('canvas');
+  canvas.id = 'map-labels';
+  canvas.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none;z-index:2;';
+  container.appendChild(canvas);
+  const ctx = canvas.getContext('2d');
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  let W = 1, H = 1;
+
+  let map = null;
+  let islandCss = [];
+  let islandShown = [];
+  let titles = [];   // [{ i, text }]
+  let pinned = [];   // [{ i, text, kind: 'selected' | 'search' }]
+  let options = { visible: true, scale: 1 };
+  const alphaOf = new Map(); // label key → current alpha
+  let lastNow = 0;
+  let hits = [];
+  const widths = new Map();
+
+  function resize(w, h) {
+    W = w; H = h;
+    canvas.width = Math.max(1, Math.round(w * dpr));
+    canvas.height = Math.max(1, Math.round(h * dpr));
+  }
+
+  function measure(font, text, spacing = 0) {
+    const key = `${font}|${spacing}|${text}`;
+    let w = widths.get(key);
+    if (w === undefined) {
+      ctx.font = font;
+      w = ctx.measureText(text).width + spacing * Math.max(0, text.length - 1);
+      if (widths.size > 4000) widths.clear();
+      widths.set(key, w);
+    }
+    return w;
+  }
+
+  const project = (m, x, y, z) => {
+    const cw = m[3] * x + m[7] * y + m[11] * z + m[15];
+    if (cw <= 1e-6) return null;
+    return [((m[0] * x + m[4] * y + m[8] * z + m[12]) / cw * 0.5 + 0.5) * W, (0.5 - (m[1] * x + m[5] * y + m[9] * z + m[13]) / cw * 0.5) * H, cw];
+  };
+
+  /** Build this frame's candidates (in priority order) from the camera. */
+  function candidates(view) {
+    const out = [];
+    if (!map) return out;
+    // Out of its tier: still offered (hidden) while it fades, dropped once gone.
+    const offer = (item, inTier) => {
+      if (inTier) out.push(item);
+      else if (alphaOf.has(item.key)) out.push({ ...item, hide: true });
+    };
+    const m = view.viewProj;
+    const s = options.scale;
+    const islandPx = new Float32Array(map.islands.length);
+    map.islands.forEach((isl, k) => {
+      const p = project(m, isl.x, isl.h, isl.z);
+      if (!p) { islandPx[k] = 0; return; }
+      islandPx[k] = isl.r * view.pxPerUnit(p[2]);
+      const px = islandPx[k];
+      const shownIsland = !!islandShown[k];
+      offer({
+        key: `i:${isl.name}`, type: 'island', name: isl.name, x: p[0], y: p[1] - 10, anchor: 'center',
+        text: isl.name, sub: isl.count.toLocaleString(), font: `500 ${Math.round(12 * s)}px ${FONT}`,
+        subFont: `400 ${Math.round(10 * s)}px ${FONT}`, color: islandCss[k] || 'rgba(230,235,245,0.9)',
+        priority: 200 + Math.log10(isl.count + 1),
+      }, shownIsland && px >= TIERS.island[0] && px <= TIERS.island[1]);
+      if (Array.isArray(isl.regions)) {
+        for (const g of isl.regions) {
+          const q = project(m, g.x, isl.h * 0.5, g.z);
+          if (!q) continue;
+          offer({
+            key: `r:${isl.name}:${g.label}`, type: 'region', name: isl.name, x: q[0], y: q[1], anchor: 'center',
+            text: g.label, font: `italic 400 ${Math.round(11 * s)}px ${FONT}`, color: 'rgba(214,222,240,0.62)',
+            priority: 100 + Math.log10(g.count + 1),
+          }, shownIsland && px >= TIERS.region);
+        }
+      }
+    });
+    const islandsOfContinent = new Map();
+    map.islands.forEach((isl, k) => {
+      if (!islandsOfContinent.has(isl.continent)) islandsOfContinent.set(isl.continent, []);
+      islandsOfContinent.get(isl.continent).push(k);
+    });
+    map.continents.forEach((c, ci) => {
+      const members = islandsOfContinent.get(ci) || [];
+      if (members.length < 2) return; // a one-island continent is just its island
+      const p = project(m, c.x, 0, c.z);
+      if (!p) return;
+      const px = c.r * view.pxPerUnit(p[2]);
+      const total = members.reduce((sum, k) => sum + map.islands[k].count, 0);
+      offer({
+        key: `c:${c.name}`, type: 'continent', name: c.name, x: p[0], y: p[1], anchor: 'center',
+        text: c.name.toUpperCase(), spacing: 2.2 * s, font: `600 ${Math.round(13 * s)}px ${FONT}`,
+        color: 'rgba(236,241,255,0.5)', priority: 300 + Math.log10(total + 1),
+      }, members.some((k) => islandShown[k]) && px >= TIERS.continent[0] && px <= TIERS.continent[1]);
+    });
+    for (const t of titles) {
+      const k = map.islandOf[t.i];
+      const p = project(m, map.positions[3 * t.i], map.positions[3 * t.i + 1], map.positions[3 * t.i + 2]);
+      if (!p) continue;
+      offer({
+        key: `m:${t.i}`, type: 'memory', index: t.i, x: p[0] + 9, y: p[1] + 4, anchor: 'left',
+        text: t.text, font: `400 ${Math.round(11 * s)}px ${FONT}`, color: 'rgba(236,239,246,0.82)',
+        priority: 10 + (t.score || 0),
+      }, !!islandShown[k] && islandPx[k] >= TIERS.memory);
+    }
+    for (const t of pinned) {
+      const p = project(m, map.positions[3 * t.i], map.positions[3 * t.i + 1], map.positions[3 * t.i + 2]);
+      if (!p) continue;
+      out.push({
+        key: `p:${t.kind}:${t.i}`, type: 'memory', index: t.i, x: p[0] + 12, y: p[1] + 4, anchor: 'left',
+        text: t.text, font: `${t.kind === 'selected' ? 600 : 500} ${Math.round(12 * s)}px ${FONT}`,
+        color: t.kind === 'selected' ? 'rgba(255,255,255,0.98)' : 'rgba(255,236,190,0.95)',
+        pill: t.kind === 'selected', priority: t.kind === 'selected' ? 10_000 : 5_000 - pinned.indexOf(t),
+      });
+    }
+    out.sort((a, b) => b.priority - a.priority);
+    return out;
+  }
+
+  /**
+   * Draw one frame. `view` = { viewProj, pxPerUnit(depth) }.
+   * @returns {boolean} true while any label is still fading
+   */
+  function draw(now, view) {
+    const dt = lastNow ? Math.min(100, now - lastNow) : 16;
+    lastNow = now;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, W, H);
+    hits = [];
+    if (!map || !options.visible || !view) {
+      alphaOf.clear();
+      return false;
+    }
+    const list = candidates(view);
+    const placed = [];
+    const shown = new Set();
+    let busy = false;
+    ctx.textBaseline = 'middle';
+    for (const c of list) {
+      const w = measure(c.font, c.text, c.spacing || 0) + (c.sub ? measure(c.subFont, c.sub) + 6 : 0);
+      const h = parseInt(c.font.match(/(\d+)px/)[1], 10) + 4;
+      const x0 = c.anchor === 'left' ? c.x : c.x - w / 2;
+      const rect = [x0 - 3, c.y - h / 2 - 2, x0 + w + 3, c.y + h / 2 + 2];
+      const inView = rect[2] > 0 && rect[0] < W && rect[3] > 0 && rect[1] < H;
+      const free = !c.hide && inView && !placed.some((r) => rect[0] < r[2] && rect[2] > r[0] && rect[1] < r[3] && rect[3] > r[1]);
+      const target = free ? 1 : 0;
+      let a = alphaOf.get(c.key) ?? 0;
+      if (free) placed.push(rect);
+      a += Math.sign(target - a) * (dt / FADE_MS);
+      a = Math.min(1, Math.max(0, a));
+      if (a !== target) busy = true;
+      if (a <= 0.01) { alphaOf.delete(c.key); continue; }
+      alphaOf.set(c.key, a);
+      shown.add(c.key);
+      paint(c, x0, w, h, a);
+      if (a > 0.5 && free) hits.push({ rect, item: c });
+    }
+    for (const key of alphaOf.keys()) if (!shown.has(key)) { alphaOf.delete(key); }
+    return busy;
+  }
+
+  function paint(c, x0, w, h, a) {
+    ctx.globalAlpha = a;
+    if (c.pill) {
+      ctx.fillStyle = 'rgba(12,14,20,0.78)';
+      roundRect(x0 - 6, c.y - h / 2 - 1, w + 12, h + 2, 6);
+      ctx.fill();
+    }
+    ctx.font = c.font;
+    ctx.fillStyle = c.color;
+    ctx.shadowColor = 'rgba(0,0,0,0.85)';
+    ctx.shadowBlur = c.pill ? 0 : 4;
+    if ('letterSpacing' in ctx) ctx.letterSpacing = c.spacing ? `${c.spacing}px` : '0px';
+    ctx.textAlign = 'left';
+    ctx.fillText(c.text, x0, c.y);
+    if (c.sub) {
+      const tw = measure(c.font, c.text, c.spacing || 0);
+      if ('letterSpacing' in ctx) ctx.letterSpacing = '0px';
+      ctx.font = c.subFont;
+      ctx.fillStyle = 'rgba(200,206,220,0.45)';
+      ctx.fillText(c.sub, x0 + tw + 6, c.y + 0.5);
+    }
+    ctx.shadowBlur = 0;
+    ctx.globalAlpha = 1;
+  }
+
+  function roundRect(x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.arcTo(x + w, y, x + w, y + h, r);
+    ctx.arcTo(x + w, y + h, x, y + h, r);
+    ctx.arcTo(x, y + h, x, y, r);
+    ctx.arcTo(x, y, x + w, y, r);
+    ctx.closePath();
+  }
+
+  /** The label under (x, y) — pinned and bigger labels first. */
+  function hitTest(x, y) {
+    for (const h of hits) {
+      const [x0, y0, x1, y1] = h.rect;
+      if (x >= x0 && x <= x1 && y >= y0 && y <= y1) return h.item;
+    }
+    return null;
+  }
+
+  return {
+    canvas,
+    resize,
+    draw,
+    hitTest,
+    setMap(next, css, shown) { map = next; islandCss = css || []; islandShown = shown || []; titles = []; pinned = []; },
+    setShown(shown) { islandShown = shown || []; },
+    setColors(css) { islandCss = css || []; },
+    setTitles(list) { titles = list || []; },
+    setPinned(list) { pinned = list || []; },
+    setOptions(next) { options = { ...options, ...next }; },
+    get count() { return hits.length; },
+  };
+}