feat(app): add MapPage with force-directed similarity graph

New /map page renders one image-thumbnail node per spec via
react-force-graph-2d, positioned by tag overlap: specs that share
many tags pull together, specs that share few drift apart.

Similarity is computed entirely client-side as pure functions:

- flattenTags() folds nested spec.tags + impl_tags into a single
  category-prefixed string set (e.g. plot_type:scatter), preventing
  collisions like "numeric" appearing in two categories.
- computeIDF() weights tags by log(N / df), so ubiquitous tags like
  data_type:numeric get ~zero weight and rare tags carry the signal.
- weightedJaccard() + buildKNNLinks() emit each spec's top-K most
  similar neighbors (K=5, min-sim=0.05), producing ~1.6k edges over
  ~327 specs — dense enough to cluster, sparse enough to avoid
  hairball rendering.

react-force-graph-2d's built-in d3-force engine handles the layout.
Thumbnails are eager-preloaded and attached to nodes as they resolve
so the canvas re-paints organically without restarting physics.

Hover highlights neighbors and dims the rest. Click navigates to the
spec page. A visually-hidden anchor list mirrors the canvas content
for screen-reader and keyboard users.

Refs #5646

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

app/package.json

@@ -22,9 +22,11 @@
     "@emotion/styled": "^11.14.1",
     "@mui/icons-material": "^9.0.0",
     "@mui/material": "^9.0.0",
+    "force-graph": "^1.51.4",
     "fuse.js": "^7.3.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
+    "react-force-graph-2d": "^1.29.1",
     "react-helmet-async": "^3.0.0",
     "react-router-dom": "^7.14.2",
     "react-syntax-highlighter": "^16.1.1",

app/src/pages/MapPage.helpers.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  flattenTags,
+  computeIDF,
+  weightedJaccard,
+  buildKNNLinks,
+  selectMapThumbUrl,
+  type SpecMapItem,
+} from './MapPage.helpers';
+
+
+function spec(id: string, tags: SpecMapItem['tags'], implTags: SpecMapItem['impl_tags'] = null): SpecMapItem {
+  return {
+    id,
+    title: id,
+    preview_url_light: `https://example.com/${id}-light.png`,
+    preview_url_dark: `https://example.com/${id}-dark.png`,
+    quality_score: 90,
+    tags,
+    impl_tags: implTags,
+  };
+}
+
+
+describe('flattenTags', () => {
+  it('prefixes values with their category', () => {
+    const s = spec('a', { plot_type: ['scatter'], features: ['basic', '2d'] });
+    expect(flattenTags(s).sort()).toEqual(['features:2d', 'features:basic', 'plot_type:scatter']);
+  });
+
+  it('merges spec.tags with impl_tags by default', () => {
+    const s = spec('a', { plot_type: ['scatter'] }, { dependencies: ['scipy'] });
+    expect(flattenTags(s).sort()).toEqual(['dependencies:scipy', 'plot_type:scatter']);
+  });
+
+  it('skips impl_tags when includeImpl=false', () => {
+    const s = spec('a', { plot_type: ['scatter'] }, { dependencies: ['scipy'] });
+    expect(flattenTags(s, false)).toEqual(['plot_type:scatter']);
+  });
+
+  it('handles missing dicts and empty arrays', () => {
+    expect(flattenTags(spec('a', null, null))).toEqual([]);
+    expect(flattenTags(spec('a', { plot_type: [] }, null))).toEqual([]);
+  });
+
+  it('deduplicates identical category:value pairs', () => {
+    const s = spec('a', { plot_type: ['scatter', 'scatter'] }, { plot_type: ['scatter'] });
+    expect(flattenTags(s)).toEqual(['plot_type:scatter']);
+  });
+});
+
+
+describe('computeIDF', () => {
+  it('assigns log(N / df) to every tag', () => {
+    const specs = [
+      spec('a', { plot_type: ['scatter'] }),
+      spec('b', { plot_type: ['scatter'] }),
+      spec('c', { plot_type: ['line'] }),
+    ];
+    const idf = computeIDF(specs);
+    expect(idf.get('plot_type:scatter')).toBeCloseTo(Math.log(3 / 2));
+    expect(idf.get('plot_type:line')).toBeCloseTo(Math.log(3 / 1));
+  });
+
+  it('gives ubiquitous tags weight ~0', () => {
+    const specs = [
+      spec('a', { data_type: ['numeric'] }),
+      spec('b', { data_type: ['numeric'] }),
+    ];
+    expect(computeIDF(specs).get('data_type:numeric')).toBeCloseTo(0);
+  });
+
+  it('survives empty input without dividing by zero', () => {
+    expect(computeIDF([]).size).toBe(0);
+  });
+});
+
+
+describe('weightedJaccard', () => {
+  const idf = new Map([
+    ['plot_type:scatter', 1.0],
+    ['plot_type:line', 1.0],
+    ['features:basic', 0.5],
+  ]);
+
+  it('returns 1 when sets are identical', () => {
+    expect(weightedJaccard(['plot_type:scatter'], ['plot_type:scatter'], idf)).toBeCloseTo(1);
+  });
+
+  it('returns 0 when sets are disjoint', () => {
+    expect(weightedJaccard(['plot_type:scatter'], ['plot_type:line'], idf)).toBe(0);
+  });
+
+  it('weights overlap by IDF (rare overlap > common overlap)', () => {
+    const rareIdf = new Map([['plot_type:scatter', 2], ['features:basic', 0.1]]);
+    const sharedRare = weightedJaccard(['plot_type:scatter'], ['plot_type:scatter', 'features:basic'], rareIdf);
+    const sharedCommon = weightedJaccard(['features:basic'], ['features:basic', 'plot_type:scatter'], rareIdf);
+    expect(sharedRare).toBeGreaterThan(sharedCommon);
+  });
+
+  it('returns 0 when either set is empty', () => {
+    expect(weightedJaccard([], ['plot_type:scatter'], idf)).toBe(0);
+    expect(weightedJaccard(['plot_type:scatter'], [], idf)).toBe(0);
+  });
+});
+
+
+describe('buildKNNLinks', () => {
+  it('keeps top-K neighbors above the similarity threshold', () => {
+    const specs = [
+      spec('scatter1', { plot_type: ['scatter'], features: ['basic'] }),
+      spec('scatter2', { plot_type: ['scatter'], features: ['basic'] }),
+      spec('line1', { plot_type: ['line'], features: ['basic'] }),
+      spec('bar1', { plot_type: ['bar'] }),
+    ];
+    const idf = computeIDF(specs);
+    const links = buildKNNLinks(specs, idf, 2, 0.0);
+    // scatter1 ↔ scatter2 should be linked (most similar pair)
+    const ids = links.map(l => `${l.source}-${l.target}`).sort();
+    expect(ids).toContain('scatter1-scatter2');
+  });
+
+  it('produces undirected links (no A→B and B→A duplicate)', () => {
+    // Need a 3-spec corpus so IDF gives non-zero weight to scatter (otherwise
+    // a universal tag has weight 0 and no link is emitted — correct behavior).
+    const specs = [
+      spec('a', { plot_type: ['scatter'] }),
+      spec('b', { plot_type: ['scatter'] }),
+      spec('c', { plot_type: ['line'] }),
+    ];
+    const links = buildKNNLinks(specs, computeIDF(specs), 5, 0.0);
+    const keys = links.map(l => `${l.source}|${l.target}`);
+    // a-b should appear exactly once, not twice
+    expect(keys.filter(k => k === 'a|b' || k === 'b|a').length).toBe(1);
+  });
+
+  it('drops links below minSim', () => {
+    const specs = [
+      spec('a', { plot_type: ['scatter'] }),
+      spec('b', { plot_type: ['line'] }),
+    ];
+    const links = buildKNNLinks(specs, computeIDF(specs), 5, 0.5);
+    expect(links).toHaveLength(0);
+  });
+
+  it('every link weight is in (0, 1]', () => {
+    const specs = [
+      spec('a', { plot_type: ['scatter'], features: ['basic'] }),
+      spec('b', { plot_type: ['scatter'], features: ['regression'] }),
+      spec('c', { plot_type: ['line'], features: ['basic'] }),
+    ];
+    const links = buildKNNLinks(specs, computeIDF(specs), 3, 0.0);
+    for (const l of links) {
+      expect(l.weight).toBeGreaterThan(0);
+      expect(l.weight).toBeLessThanOrEqual(1);
+    }
+  });
+});
+
+
+describe('selectMapThumbUrl', () => {
+  it('returns dark URL in dark mode, light in light mode', () => {
+    const s = spec('a', null);
+    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-dark.png');
+    expect(selectMapThumbUrl(s, false)).toBe('https://example.com/a-light.png');
+  });
+
+  it('falls back to the other theme when the preferred URL is missing', () => {
+    const s: SpecMapItem = { ...spec('a', null), preview_url_dark: null };
+    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-light.png');
+  });
+
+  it('returns null when no preview URLs at all', () => {
+    const s: SpecMapItem = { ...spec('a', null), preview_url_light: null, preview_url_dark: null };
+    expect(selectMapThumbUrl(s, false)).toBeNull();
+  });
+});

app/src/pages/MapPage.helpers.ts

@@ -0,0 +1,183 @@
+/**
+ * Pure helpers for the /map page: tag flattening, IDF weighting,
+ * weighted Jaccard similarity, and sparse KNN edge construction.
+ *
+ * Kept side-effect-free so the math is exhaustively unit-testable
+ * in MapPage.helpers.test.ts. The page component imports these and
+ * feeds the result into react-force-graph-2d.
+ */
+
+import { selectPreviewUrl } from '../utils/themedPreview';
+
+
+/** Backend response shape from GET /api/specs/map. Mirrors api/schemas.py::SpecMapItem. */
+export interface SpecMapItem {
+  id: string;
+  title: string;
+  preview_url_light: string | null;
+  preview_url_dark: string | null;
+  quality_score: number | null;
+  tags: Record<string, string[]> | null;
+  impl_tags: Record<string, string[]> | null;
+}
+
+/** Node shape passed to ForceGraph2D. `img` populated lazily as thumbnails resolve. */
+export interface MapNode {
+  id: string;
+  title: string;
+  tags: string[];
+  thumbUrl: string | null;
+  img?: HTMLImageElement;
+}
+
+/** Link shape passed to ForceGraph2D. `weight` = weighted-Jaccard sim ∈ (0, 1]. */
+export interface MapLink {
+  source: string;
+  target: string;
+  weight: number;
+}
+
+/**
+ * Flatten a spec's nested tag dicts to a single `category:value` string set.
+ * Prefixing prevents collisions like `numeric` appearing in both `data_type`
+ * and `dataprep` and gives the IDF/Jaccard math distinct tokens to weigh.
+ */
+export function flattenTags(spec: SpecMapItem, includeImpl = true): string[] {
+  const out: string[] = [];
+  const push = (dict: Record<string, string[]> | null | undefined) => {
+    if (!dict) return;
+    for (const [category, values] of Object.entries(dict)) {
+      if (!Array.isArray(values)) continue;
+      for (const v of values) {
+        if (typeof v === 'string' && v.length > 0) out.push(`${category}:${v}`);
+      }
+    }
+  };
+  push(spec.tags);
+  if (includeImpl) push(spec.impl_tags);
+  return Array.from(new Set(out));
+}
+
+/**
+ * Inverse-document-frequency weights: w_t = log(N / df_t).
+ * Down-weights ubiquitous tags (`data_type:numeric` is in nearly every spec)
+ * and amplifies rare ones. Returns weight ≥ 0; tags absent from the corpus
+ * default to 0 when looked up.
+ */
+export function computeIDF(specs: SpecMapItem[]): Map<string, number> {
+  const N = specs.length || 1;
+  const df = new Map<string, number>();
+  for (const spec of specs) {
+    for (const tag of flattenTags(spec)) {
+      df.set(tag, (df.get(tag) ?? 0) + 1);
+    }
+  }
+  const idf = new Map<string, number>();
+  for (const [tag, count] of df) {
+    idf.set(tag, Math.log(N / count));
+  }
+  return idf;
+}
+
+/**
+ * Weighted Jaccard similarity over two tag sets.
+ *   sim = Σ w_t for t∈a∩b / Σ w_t for t∈a∪b
+ * Returns 0 when both sets are empty (no signal) or denominator collapses.
+ */
+export function weightedJaccard(a: string[], b: string[], idf: Map<string, number>): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const setA = new Set(a);
+  const setB = new Set(b);
+  let num = 0;
+  let denom = 0;
+  const seen = new Set<string>();
+  for (const t of setA) {
+    seen.add(t);
+    const w = idf.get(t) ?? 0;
+    denom += w;
+    if (setB.has(t)) num += w;
+  }
+  for (const t of setB) {
+    if (seen.has(t)) continue;
+    denom += idf.get(t) ?? 0;
+  }
+  return denom > 0 ? num / denom : 0;
+}
+
+/**
+ * Build a sparse KNN link list: each spec keeps its top-K most similar
+ * neighbors above `minSim`. Output is deduplicated (no A→B + B→A pair) and
+ * symmetric — the link with the higher weight wins on tie.
+ *
+ * With ~327 specs × K=5 the result is ~1.6k edges: dense enough for
+ * cohesive clustering, sparse enough to avoid hairball rendering.
+ */
+export function buildKNNLinks(
+  specs: SpecMapItem[],
+  idf: Map<string, number>,
+  k = 5,
+  minSim = 0.05
+): MapLink[] {
+  const tagsByIdx = specs.map(s => flattenTags(s));
+  const linkSet = new Map<string, MapLink>();
+  for (let i = 0; i < specs.length; i++) {
+    const sims: { j: number; sim: number }[] = [];
+    for (let j = 0; j < specs.length; j++) {
+      if (i === j) continue;
+      const sim = weightedJaccard(tagsByIdx[i], tagsByIdx[j], idf);
+      // sim > 0 drops zero-weight links (no shared tags or all-zero IDF) — pure visual noise.
+      if (sim > 0 && sim >= minSim) sims.push({ j, sim });
+    }
+    sims.sort((x, y) => y.sim - x.sim);
+    for (const { j, sim } of sims.slice(0, k)) {
+      const a = specs[i].id;
+      const b = specs[j].id;
+      const key = a < b ? `${a}|${b}` : `${b}|${a}`;
+      const existing = linkSet.get(key);
+      if (!existing || sim > existing.weight) {
+        linkSet.set(key, { source: a < b ? a : b, target: a < b ? b : a, weight: sim });
+      }
+    }
+  }
+  return Array.from(linkSet.values());
+}
+
+/** Pick the best thumbnail URL for the current theme. Wraps selectPreviewUrl. */
+export function selectMapThumbUrl(spec: SpecMapItem, isDark: boolean): string | null {
+  return selectPreviewUrl(spec, isDark);
+}
+
+/**
+ * Eager-preload every node's thumbnail. Resolves once all images either
+ * loaded or errored — failures are swallowed (image stays undefined and
+ * the node renders as a plain dot in nodeCanvasObject's fallback path).
+ *
+ * `onLoad` fires per-image so the page can call fgRef.refresh() to re-paint
+ * without re-running the simulation. This is what produces the "thumbnails
+ * pop in organically" UX rather than a blocking wait.
+ */
+export async function preloadImages(
+  items: { id: string; thumbUrl: string | null }[],
+  onLoad?: (id: string, img: HTMLImageElement) => void
+): Promise<Map<string, HTMLImageElement>> {
+  const out = new Map<string, HTMLImageElement>();
+  await Promise.all(
+    items.map(({ id, thumbUrl }) => {
+      if (!thumbUrl) return Promise.resolve();
+      return new Promise<void>(resolve => {
+        // document.createElement is preferred over `new Image()` here only because
+        // some lint configs don't surface browser globals on plain .ts files.
+        const img = document.createElement('img');
+        img.crossOrigin = 'anonymous';
+        img.onload = () => {
+          out.set(id, img);
+          onLoad?.(id, img);
+          resolve();
+        };
+        img.onerror = () => resolve();
+        img.src = thumbUrl;
+      });
+    })
+  );
+  return out;
+}