feat: clarify link strength and search activity

Author: StoneHub

AGENTS.md

@@ -16,6 +16,7 @@
 - Read the existing code and docs before changing behavior.
 - Prefer minimal, local changes over broad rewrites.
 - If a task spans multiple files, the most likely hotspots are `src/App.tsx`, `src/GraphManager.ts`, `src/components/*`, `src/features/structured-view/*`, `src/hooks/useGraphState.ts`, and matching tests under `src/`.
+- Search/pathfinding UX work most often lands in `src/components/SearchStatusOverlay.tsx`, `src/components/ConnectionStatusBar.tsx`, and the path/queue orchestration inside `src/App.tsx`.
 - Do not commit generated local artifacts such as `.preview.*` or `.playwright-cli/`.
 - If instructions or release steps seem stale, call that out explicitly in the handoff.
 - For graph-layout changes, sanity-check first-load behavior with at least two root topics in `web` mode before calling the UX done.

README.md

@@ -45,6 +45,7 @@ GitHub: `https://github.com/StoneHub/WikiWebMap`
 - Drag canvas to pan; scroll to zoom.
 - Click a node to open details and actions.
 - Select up to 2 nodes to search for connections. On desktop you can Shift+Click nodes; on touch devices you can use the node details panel.
+- Queued bridge searches run automatically, and the `Search Activity` panel shows progress, pause/resume controls, and whether alternate-bridge search is enabled.
 - Alt/Option+Drag box-selects nodes for bulk actions on desktop.
 
 ## License

docs/development-plan.md

@@ -12,6 +12,8 @@ This repo is now in a safer release-ready state than it was at clone time:
 - `web` mode now seeds root topics from root-count-aware positions instead of total-node-count drift, which keeps first-load layouts more balanced.
 - Project attribution and external links now live with the bottom-left graph tools on desktop, with matching ownership/Wikimedia notice language in the UI and docs.
 - Neutral placeholder art now avoids leaning on Wikimedia-looking fallback branding when a topic has no thumbnail.
+- Link-strength cues are now surfaced in both the legend and connection drawer, so “strong ties” are no longer hidden inside rendering math alone.
+- The old green `Search Terminal` is now a calmer `Search Activity` panel with automatic queue messaging, optional detail logs, and duplicate-search prevention.
 
 Renderer planning note:
 - The next radically different visualization experiment is a React Flow-based `Structured View`; see `docs/react-flow-structured-view-plan.md`.
@@ -121,8 +123,9 @@ Recommended order:
 ## Immediate next improvements
 
 1. Add a one-click `Spread Roots` action so users can quickly recreate the “pull major topics apart, let the inner nodes congregate” layout they naturally discovered.
-2. Turn current link-strength scoring into clearer visual language with a legend entry for strong ties, shared-neighbor ties, and cross-branch bridges.
-3. Add a small server-side or edge cache/proxy layer for Wikipedia requests so abuse control, request budgets, and API identification are no longer purely client-enforced.
+2. Add a small server-side or edge cache/proxy layer for Wikipedia requests so abuse control, request budgets, and API identification are no longer purely client-enforced.
+3. Let users pin a `search recipe` from the activity panel, such as “find alternate bridges” or “pause after first result,” so repeated exploration sessions feel more intentional.
+4. Add a `connection lens` mode that temporarily brightens only the strongest ties around a focused topic.
 
 ## Branch strategy
 

docs/ux-effects-plan.md

@@ -47,6 +47,10 @@ Core principles:
 - Nodes now have softer halos and better root emphasis, but the graph still does not fully communicate connection importance at a glance.
 - Link weight and branch significance are still more present in the data than in the visuals.
 
+### 3b. Search activity should feel like product guidance, not a debug console
+- The old terminal look is gone, but the activity panel can still get smarter about when to stay quiet, when to summarize, and when to reveal deeper detail.
+- Search controls should feel integrated with discovery, not like a separate developer tool floating above it.
+
 ### 4. Motion is mostly utilitarian
 - The graph has energy, but UI transitions and contextual reveals are still basic.
 - There is room for effects that make cause-and-effect easier to understand.
@@ -126,6 +130,7 @@ Suggested effects:
 - Search panel fade/slide on first load
 - Node details sheet spring-in on mobile
 - Context drawer expand/collapse animation
+- Search Activity panel state transitions that gracefully collapse from active search to standby summary
 - Path result pulse or trace effect in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts)
 - Softer background parallax or light-field drift in [LensingGridBackground.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/LensingGridBackground.tsx)
 
@@ -178,7 +183,7 @@ Risk:
 ### Top 5 to do next
 1. Add a “root spread” assist in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts) so major topics land in cleaner perimeter positions before the user drags them
 2. Convert connection context into a more deliberate mobile/desktop drawer pattern in [ConnectionStatusBar.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/ConnectionStatusBar.tsx)
-3. Add weighted link styling and legend language so strong/shared-topic bridges read immediately in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts) and [GraphControls.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/GraphControls.tsx)
+3. Make the `Search Activity` panel smarter about automatic collapse, session presets, and result summaries in [SearchStatusOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchStatusOverlay.tsx)
 4. Polish the node details sheet in [NodeDetailsPanel.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/NodeDetailsPanel.tsx)
 5. Add motion rules and shared transitions in [index.css](/C:/Users/monro/Codex/WikiWebMap/src/index.css)
 

src/App.tsx

@@ -702,8 +702,8 @@ const WikiWebExplorer = () => {
     keepSearchingRef.current = keepSearching;
   }, [keepSearching]);
 
-  const findPath = (startInput: string, endInput: string) =>
-    runPathfinder({
+  const findPath = (startInput: string, endInput: string) =>
+    runPathfinder({
       startInput,
       endInput,
       maxDepth: recursionDepth * 2,
@@ -720,19 +720,36 @@ const WikiWebExplorer = () => {
       onFoundPath: (found) => {
         setFoundPaths(prev => [...prev, found]);
         setSearchDockLinkId(prev => prev ?? found.triggerLinkId);
-      },
-    });
-
-  const enqueueSearch = async (from: string, to: string, source: 'suggested' | 'shift') => {
-    const passedVerification = await RecaptchaService.verify('pathfinding');
-    if (!passedVerification) {
-      setError('Bot verification failed. Please try again.');
-      return;
-    }
-    setSearchQueue(prev => {
-      if (prev.length >= 3 || searchQueueRef.current.length >= 3) {
-        setError('Search queue full (max 3).');
-        return prev;
+      },
+    });
+
+  const getSearchKey = (from: string, to: string) =>
+    `${from.trim().toLowerCase()}→${to.trim().toLowerCase()}`;
+
+  const enqueueSearch = async (from: string, to: string, source: 'suggested' | 'shift') => {
+    const passedVerification = await RecaptchaService.verify('pathfinding');
+    if (!passedVerification) {
+      setError('Bot verification failed. Please try again.');
+      return;
+    }
+
+    const requestedKey = getSearchKey(from, to);
+    const activeKey = activeSearch ? getSearchKey(activeSearch.from, activeSearch.to) : null;
+    const duplicateQueued = searchQueueRef.current.some((job) => getSearchKey(job.from, job.to) === requestedKey);
+    if (activeKey === requestedKey || duplicateQueued) {
+      setError('That search is already running or queued.');
+      setSearchTerminalMinimized(false);
+      return;
+    }
+
+    setSearchQueue(prev => {
+      if (prev.some((job) => getSearchKey(job.from, job.to) === requestedKey)) {
+        setError('That search is already queued.');
+        return prev;
+      }
+      if (prev.length >= 3 || searchQueueRef.current.length >= 3) {
+        setError('Search queue full (max 3).');
+        return prev;
       }
       const id = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
       const next = [...prev, { id, from, to, source }];
@@ -824,6 +841,9 @@ const WikiWebExplorer = () => {
   const pinnedLinks = pinnedState.ids
     .map(id => graphManagerRef.current?.getLinkById(id))
     .filter((x): x is Link => Boolean(x));
+  const displayedLinkInsight = displayedLinkId
+    ? graphManagerRef.current?.getLinkInsightSummary(displayedLinkId)
+    : undefined;
   const clickedNodeMeta = clickedNode
     ? graphManagerRef.current?.getNodeMetadata(clickedNode.id)
     : undefined;
@@ -973,6 +993,7 @@ const WikiWebExplorer = () => {
 
       <ConnectionStatusBar
         link={displayedLink}
+        linkInsight={displayedLinkInsight}
         pinnedLinks={pinnedLinks}
         selectedPinnedLinkId={pinnedState.selectedId}
         isTouchDevice={isTouchDevice}

src/GraphManager.ts

@@ -116,6 +116,15 @@ type LinkInsight = {
   strength: number;
 };
 
+export type LinkInsightSummary = {
+  role: 'primary' | 'cross' | 'backlink' | 'path';
+  tier: 'light' | 'moderate' | 'strong';
+  sharedNeighbors: number;
+  sharedNeighborRatio: number;
+  isReciprocal: boolean;
+  strength: number;
+};
+
 /**
  * GraphManager - Imperative D3 graph management
  * Owns the simulation and DOM, provides methods for incremental updates
@@ -1948,6 +1957,40 @@ export class GraphManager {
     return this.links.find(l => l.id === linkId);
   }
 
+  getLinkInsightSummary(linkId: string): LinkInsightSummary | undefined {
+    const link = this.getLinkById(linkId);
+    if (!link) return undefined;
+
+    const insight = this.getLinkInsight(link);
+    const sourceId = typeof link.source === 'object' ? link.source.id : link.source;
+    const targetId = typeof link.target === 'object' ? link.target.id : link.target;
+    const sourceMeta = this.nodeMetadata.get(sourceId);
+    const targetMeta = this.nodeMetadata.get(targetId);
+    const isPathLink = Boolean(sourceMeta?.isInPath && targetMeta?.isInPath);
+    const isBacklink = typeof link.type === 'string' && link.type.includes('backlink');
+    const role: LinkInsightSummary['role'] = isPathLink
+      ? 'path'
+      : isBacklink
+        ? 'backlink'
+        : link.layoutRole === 'cross'
+          ? 'cross'
+          : 'primary';
+    const tier: LinkInsightSummary['tier'] = insight.strength >= 0.72 || insight.sharedNeighbors >= 3
+      ? 'strong'
+      : insight.strength >= 0.46 || insight.sharedNeighbors >= 1
+        ? 'moderate'
+        : 'light';
+
+    return {
+      role,
+      tier,
+      sharedNeighbors: insight.sharedNeighbors,
+      sharedNeighborRatio: insight.sharedNeighborRatio,
+      isReciprocal: insight.isReciprocal,
+      strength: insight.strength,
+    };
+  }
+
   getLensingNodes(): Array<{ x: number; y: number; mass: number }> {
     const transform = d3.zoomTransform(this.svg.node()!);
 

src/components/ConnectionStatusBar.tsx

@@ -1,8 +1,9 @@
 import { useEffect, useState } from 'react';
-import type { Link } from '../GraphManager';
+import type { Link, LinkInsightSummary } from '../GraphManager';
 
 export function ConnectionStatusBar(props: {
   link: Link | null;
+  linkInsight?: LinkInsightSummary;
   pinnedLinks: Link[];
   selectedPinnedLinkId: string | null;
   isTouchDevice: boolean;
@@ -53,13 +54,47 @@ export function ConnectionStatusBar(props: {
 
   const isPinned = Boolean(link && props.pinnedLinks.some(l => l.id === link.id));
   const hasLongContext = Boolean(link?.context && link.context.length > 180);
+  const linkInsight = props.linkInsight;
   const wrapperClassName = props.isTouchDevice
     ? 'fixed inset-x-3 bottom-[6.8rem] z-30 pointer-events-none'
     : 'fixed left-3 right-3 bottom-3 sm:left-1/2 sm:right-auto sm:-translate-x-1/2 z-40 sm:w-[min(720px,calc(100vw-1.5rem))] pointer-events-none';
   const panelClassName = props.isTouchDevice
     ? 'pointer-events-auto rounded-[1.75rem] border border-gray-700/60 bg-gray-900/90 px-4 py-4 shadow-[0_20px_60px_rgba(2,6,23,0.55)] backdrop-blur-md'
     : 'pointer-events-auto bg-gray-900/85 backdrop-blur-md border border-gray-700/60 rounded-2xl shadow-2xl px-4 py-3';
 
+  const relationshipLabel = (() => {
+    if (!linkInsight) return null;
+    if (linkInsight.role === 'path') return 'Path bridge';
+    if (linkInsight.role === 'backlink') return linkInsight.isReciprocal ? 'Mutual backlink' : 'Incoming reference';
+    if (linkInsight.role === 'cross') {
+      return linkInsight.tier === 'strong' ? 'Strong bridge' : 'Bridge link';
+    }
+    return linkInsight.tier === 'strong'
+      ? 'Strong tie'
+      : linkInsight.tier === 'moderate'
+        ? 'Related topics'
+        : 'Light tie';
+  })();
+
+  const relationshipCopy = (() => {
+    if (!linkInsight) return null;
+    if (linkInsight.role === 'path') {
+      return 'This highlighted edge is part of the active bridge the pathfinder reconstructed.';
+    }
+    if (linkInsight.role === 'cross') {
+      return linkInsight.sharedNeighbors > 0
+        ? `This bridge jumps between branches and still shares ${linkInsight.sharedNeighbors} nearby topic${linkInsight.sharedNeighbors === 1 ? '' : 's'}.`
+        : 'This bridge jumps between branches even though the local neighborhoods stay fairly distinct.';
+    }
+    if (linkInsight.sharedNeighbors > 0) {
+      return `These topics share ${linkInsight.sharedNeighbors} nearby Wikipedia topic${linkInsight.sharedNeighbors === 1 ? '' : 's'}, which is why this connection renders more strongly.`;
+    }
+    if (linkInsight.isReciprocal) {
+      return 'These articles point back to each other, so the relationship gets a stronger visual treatment.';
+    }
+    return 'This is a lighter connection with less local overlap than the stronger highlighted ties.';
+  })();
+
   return (
     <div className={wrapperClassName}>
       <div className={panelClassName}>
@@ -124,23 +159,42 @@ export function ConnectionStatusBar(props: {
               )}
             </div>
             {link ? (
-              <div className="mt-2 text-sm font-semibold text-white leading-relaxed">
-                <button
-                  onClick={() => props.onFocusNode(source)}
-                  className="underline decoration-white/20 hover:decoration-white/60"
-                  title="Focus this topic in the map"
-                >
-                  {source}
-                </button>{' '}
-                <span className="text-gray-300">{direction}</span>{' '}
-                <button
-                  onClick={() => props.onFocusNode(target)}
-                  className="underline decoration-white/20 hover:decoration-white/60"
-                  title="Focus this topic in the map"
-                >
-                  {target}
-                </button>
-              </div>
+              <>
+                <div className="mt-2 text-sm font-semibold text-white leading-relaxed">
+                  <button
+                    onClick={() => props.onFocusNode(source)}
+                    className="underline decoration-white/20 hover:decoration-white/60"
+                    title="Focus this topic in the map"
+                  >
+                    {source}
+                  </button>{' '}
+                  <span className="text-gray-300">{direction}</span>{' '}
+                  <button
+                    onClick={() => props.onFocusNode(target)}
+                    className="underline decoration-white/20 hover:decoration-white/60"
+                    title="Focus this topic in the map"
+                  >
+                    {target}
+                  </button>
+                </div>
+                {relationshipLabel && (
+                  <div className="mt-2 flex flex-wrap gap-2 text-[11px] text-slate-200">
+                    <span className="rounded-full border border-cyan-400/20 bg-cyan-400/10 px-2.5 py-1 text-cyan-100">
+                      {relationshipLabel}
+                    </span>
+                    {linkInsight && linkInsight.sharedNeighbors > 0 && (
+                      <span className="rounded-full border border-slate-700/70 bg-black/20 px-2.5 py-1 text-slate-200">
+                        Shared neighbors: {linkInsight.sharedNeighbors}
+                      </span>
+                    )}
+                    {linkInsight?.isReciprocal && (
+                      <span className="rounded-full border border-amber-400/20 bg-amber-400/10 px-2.5 py-1 text-amber-100">
+                        Mutual references
+                      </span>
+                    )}
+                  </div>
+                )}
+              </>
             ) : (
               <div className="mt-2 text-sm font-semibold text-white">
                 Select a pinned connection.
@@ -170,7 +224,7 @@ export function ConnectionStatusBar(props: {
         <div className="mt-3 bg-black/30 rounded-2xl border border-gray-700/50 px-3 py-3">
           <div className="mb-2 flex items-center justify-between gap-3">
             <div className="text-[10px] uppercase tracking-[0.22em] text-gray-400">
-              Article Snippet
+              Why These Topics Connect
             </div>
             {hasLongContext && !isLoading && (
               <button
@@ -195,8 +249,15 @@ export function ConnectionStatusBar(props: {
               </div>
             </div>
           ) : (
-            <div className={`text-[12px] text-gray-200 leading-relaxed italic ${showFullContext ? '' : 'line-clamp-3'}`}>
-              “{link?.context}”
+            <div className="space-y-3">
+              {relationshipCopy && (
+                <div className="rounded-xl border border-cyan-400/15 bg-cyan-400/5 px-3 py-2 text-[11px] leading-relaxed text-slate-200">
+                  {relationshipCopy}
+                </div>
+              )}
+              <div className={`text-[12px] text-gray-200 leading-relaxed italic ${showFullContext ? '' : 'line-clamp-3'}`}>
+                “{link?.context}”
+              </div>
             </div>
           )}
         </div>