feat(network): search refinements — zoom on hit, address panel, location/staking on detail panels (#102)

- Node hash/name search zooms to the matched node + 1-hop neighbors
- 0x address search opens a dedicated panel with copyable address, link
  count, staking positions (CCNs + ALEPH per position), wallet link
- Address-driven spotlight: dim everything outside the wallet's footprint;
  highlightedIds now matches id (staker), owner, and reward
- CCN/CRN detail panels show a Location row (flag + country name);
  country attribution decoupled from the geo layer toggle
- Search: controlled component (q lifted to page), 280px to match the
  detail card, 28×28 info-icon button, gap-0.5 to the input;
  close-panel + close-address clear the search input
- Fix: --network-country OKLCH chroma was out of sRGB gamut at hue 200°
  and silently dropped by Lightning CSS — country nodes rendered black;
  lowered chroma to 0.13 (Decision #77)

Author: cpascariello

CLAUDE.md

@@ -18,6 +18,30 @@ Each entry includes:
 
 ---
 
+## Decision #79 - 2026-05-11
+**Context:** Country attribution on CCN/CRN nodes used to live inside the `if (layers.has("geo"))` block of `buildGraph`, so `n.country` was only populated when the geo layer was on. After adding a "Location" row to the CCN/CRN detail panels (showing `🇫🇷 France` etc.), the row was missing whenever Geo was off (the default).
+**Decision:** Split the geo block into two passes in `network-graph-model.ts`: (1) country *attribution* (set `n.country` on located CCN/CRN, build the `represented` set) always runs; (2) geo *layer artifacts* (the country hub nodes + geo edges) only run when `layers.has("geo")`. Detail panels read `node.country` regardless of layer state.
+**Rationale:** Country is a property of the node, not of a presentation layer. Coupling it to the layer toggle was a quirk of the original geo-layer commit (#74), not a design intent. The split is mechanical, doesn't change geo-layer visuals, and unlocks the Location row without forcing users to enable Geo to see where a node lives. The cost is one extra pass over `nodes` when Geo is off — negligible at ~500 nodes.
+**Alternatives considered:** Look up country directly in the panel from `node-locations.json` (rejected — duplicates the existing graph-model lookup; two sources of truth for the same data). Force the geo layer on by default (rejected — the layer affects the entire layout; turning it on just to show a country label is overkill). Add a separate `geo-attribute` non-visible layer that only sets `country` (rejected — adds a layer concept the user can never toggle, confusing).
+
+---
+
+## Decision #78 - 2026-05-11
+**Context:** Address deep-link (`?address=0x...`) previously highlighted matching nodes with a pulsing primary-color ring and auto-fit the camera to them, but otherwise nothing changed — no detail panel, no spotlight dim. After making `?selected=` open a node panel, search-by-address still felt like nothing happened: pulse rings were easy to miss against a busy graph and the user got no panel feedback. Separately, `highlightedIds` was computed only from `owner === address`, so a wallet that staked (id-match) or received rewards (reward-match) but didn't own any node showed zero highlights.
+**Decision:** Treat `?address=` as a first-class selection signal. (1) Open a dedicated `NetworkSearchAddressPanel` (right side, 280px, same chrome as the node panel) when address is set and no node is selected — showing the copyable address, link count, an "Open wallet view →" link, and a staking section listing every CCN where the address appears in `c.stakers` with per-position and total ALEPH. (2) Expand `highlightedIds` to match `id` (staker), `owner`, or `reward` so the on-graph pulse reflects the wallet's full footprint. (3) Extend the selection spotlight: when no node is selected but `highlightedIds.size > 0`, `relevantIds = highlightedIds ∪ 1-hop neighbors` and the existing dim path applies to nodes, labels, *and* edges (non-incident edges fade). Address-panel close clears `?address=` *and* the search input, matching the panel-close clears-search pattern.
+**Rationale:** The pulse-ring-only design assumed power users would notice the dim signal — in practice users searched an address and saw "nothing happen." Promoting the address to a real panel + spotlight reuses the same visual idiom users already know from node selection (dim everything else, panel on the right), so address search becomes discoverable without inventing a new pattern. Expanding `highlightedIds` to id/owner/reward matches the wallet's actual footprint, not just its ownership — a staker who doesn't own anything still gets visual presence. The edge-dim extension was a missing piece: previously only `selectedId` drove the `faded` flag, so address search left edges fully lit while nodes dimmed — visually inconsistent.
+**Alternatives considered:** Auto-select the first matching node instead of opening an address panel (rejected — the panel context would be "this node" rather than "this wallet"; misleading when the address owns multiple nodes). Treat the address as a virtual GraphNode and add `kind: "address"` (rejected — ripples through `RADIUS`, color tables, panel switch statements for a UI-only synthetic). Use a thicker pulse ring instead of dimming (rejected — pulse alone didn't read; the dim is what makes the spotlight feel intentional). Keep `highlightedIds` owner-only (rejected — a real-world staker without ownership is invisible, contradicts the new panel's "Linked to N nodes" copy).
+
+---
+
+## Decision #77 - 2026-05-11
+**Context:** Country nodes on `/network` rendered as flat black circles instead of cyan-teal. The CSS token `--network-country` declared in `globals.css` resolved to an empty string in the browser; SVG `fill="var(--network-country)"` then fell back to the SVG default (`black`). Sibling tokens (`--network-edge-owner`, `--network-edge-reward`) in the same `:root` block compiled fine. The compiled `_next/static/chunks/src_app_globals_*.css` literally did not contain `--network-country` — the property was being stripped at build time.
+**Decision:** Drop the chroma value on `--network-country` from `0.16` (light) / `0.14` (dark) to `0.13` for both, keeping hue `200°` and lightness `0.70` / `0.78`. The token now compiles through Lightning CSS as a valid `lab()` value with a hex fallback.
+**Rationale:** Lightning CSS (Tailwind v4's CSS engine) silently drops `oklch()` values that are out of sRGB gamut at the requested hue, instead of clamping. At hue ~200° (cyan), the in-gamut chroma ceiling is around `0.13` at these lightnesses — `0.16`/`0.14` overshot and got dropped silently. The other tokens used `230°` (blue), which has more headroom and stayed in gamut. The visual difference between chroma `0.13` and `0.14`/`0.16` is small enough to not warrant a different hue or a hex fallback, and keeping OKLCH preserves the codebase convention.
+**Alternatives considered:** Switch the token to a hex value (rejected — breaks the OKLCH convention used by the rest of `globals.css`; would also lose automatic light/dark inversion since hex doesn't communicate intent). Move to a different hue with more headroom (rejected — the cyan/teal hue was the entire point of the choice in Decision #74; would lose the distinct identity vs CCN purple, CRN green, staker amber). Add a hex fallback alongside the OKLCH (rejected — works but doesn't address the root cause of *why* the OKLCH dropped, and would mask the issue if anyone later swapped values back to out-of-gamut). Verified with browser-resolved computed styles after each chroma value.
+
+---
+
 ## Decision #76 - 2026-05-11
 **Context:** Decision #74's initial design treated geo edges as force-only — `network-graph.tsx` early-returned on `e.type === "geo"` so they never rendered, on the theory that proximity to the country dot would already convey "in this country." Real-world testing with Geo + Structural both on showed the cross-country CCN→CRN structural arrows visually muddled the geo grouping — each country dot was surrounded by its cluster but no edges connected them, so the eye couldn't tell which CCN belonged to which country at a glance.
 **Decision:** Render geo edges as a thin, country-tinted dashed tether — `STROKE.geo = var(--network-country)`, `DASH.geo = "1 2"`, `OPACITY.geo = 0.35`, `strokeWidth=0.5`, no arrowhead. The country becomes a visible hub-and-spoke hub. Wire country into the selection-incident-color path (`incidentColor` returns `var(--network-country)` when a country is selected) so picking a country brightens its tethers to `0.9` opacity via the existing `highlightColor` branch in `NetworkEdge`. Add a "Country tether" line swatch to the legend (also conditional on the geo layer).

docs/ARCHITECTURE.md

@@ -13,15 +13,15 @@
   --map-vignette: rgba(0, 0, 0, 0.05);
   --network-edge-owner: oklch(0.65 0.18 230);
   --network-edge-reward: var(--color-primary-400);
-  --network-country: oklch(0.70 0.16 200);
+  --network-country: oklch(0.70 0.13 200);
 }
 
 .theme-dark {
   --map-dot-color: rgba(255, 255, 255, 0.06);
   --map-vignette: rgba(0, 0, 0, 0.3);
   --network-edge-owner: oklch(0.72 0.16 230);
   --network-edge-reward: var(--color-primary-300);
-  --network-country: oklch(0.78 0.14 200);
+  --network-country: oklch(0.78 0.13 200);
 }
 
 html {

docs/DECISIONS.md

@@ -14,6 +14,7 @@ import { NetworkSearch } from "@/components/network/network-search";
 import { NetworkDetailPanel } from "@/components/network/network-detail-panel";
 import { NetworkFocusPill } from "@/components/network/network-focus-pill";
 import { NetworkLegend } from "@/components/network/network-legend";
+import { NetworkSearchAddressPanel } from "@/components/network/network-search-address-panel";
 
 const SETTLE_MS = 500;
 
@@ -30,6 +31,9 @@ function NetworkContent() {
   } = useNetworkGraph();
   const [resetKey, setResetKey] = useState(0);
   const [isSettling, setIsSettling] = useState(false);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [fitTargetId, setFitTargetId] = useState<string | null>(null);
+  const [fitNonce, setFitNonce] = useState(0);
 
   useEffect(() => {
     setIsSettling(true);
@@ -39,6 +43,12 @@ function NetworkContent() {
 
   const onResetView = useCallback(() => {
     setResetKey((k) => k + 1);
+    setFitTargetId(null);
+  }, []);
+
+  const onSearchFit = useCallback((id: string) => {
+    setFitTargetId(id);
+    setFitNonce((n) => n + 1);
   }, []);
 
   const selectedId = searchParams.get("selected");
@@ -50,7 +60,11 @@ function NetworkContent() {
     if (!address) return new Set<string>();
     return new Set(
       visibleGraph.nodes
-        .filter((n) => n.owner?.toLowerCase() === address)
+        .filter((n) =>
+          n.id.toLowerCase() === address ||
+          n.owner?.toLowerCase() === address ||
+          n.reward?.toLowerCase() === address,
+        )
         .map((n) => n.id),
     );
   }, [visibleGraph, address]);
@@ -65,6 +79,15 @@ function NetworkContent() {
     const params = new URLSearchParams(searchParams.toString());
     params.delete("selected");
     router.replace(`/network?${params.toString()}`, { scroll: false });
+    setSearchQuery("");
+    setFitTargetId(null);
+  }, [router, searchParams]);
+
+  const onCloseAddress = useCallback(() => {
+    const params = new URLSearchParams(searchParams.toString());
+    params.delete("address");
+    router.replace(`/network?${params.toString()}`, { scroll: false });
+    setSearchQuery("");
   }, [router, searchParams]);
 
   const onFocus = useCallback((id: string) => {
@@ -154,6 +177,8 @@ function NetworkContent() {
             selectedId={selectedId}
             highlightedIds={highlightedIds}
             refitKey={refitKey}
+            fitTargetId={fitTargetId}
+            fitNonce={fitNonce}
             onNodeClick={onNodeClick}
           />
         )}
@@ -195,7 +220,11 @@ function NetworkContent() {
               {isFetching ? "Fetching" : "Updating"}…
             </span>
           )}
-          <NetworkSearch />
+          <NetworkSearch
+            q={searchQuery}
+            onChange={setSearchQuery}
+            onSearchFit={onSearchFit}
+          />
         </div>
       </div>
 
@@ -214,6 +243,17 @@ function NetworkContent() {
           />
         </aside>
       )}
+
+      {address && !selectedNode && (
+        <aside className="pointer-events-auto absolute right-6 top-40 z-20 hidden w-[280px] max-h-[calc(100%-11rem)] overflow-hidden rounded-xl border border-foreground/[0.06] bg-muted/40 dark:bg-surface shadow-md md:block">
+          <NetworkSearchAddressPanel
+            address={address}
+            matchCount={highlightedIds.size}
+            nodeState={nodeState}
+            onClose={onCloseAddress}
+          />
+        </aside>
+      )}
     </div>
   );
 }

src/app/globals.css

@@ -11,9 +11,39 @@ export type VersionEntry = {
   changes: ChangeEntry[];
 };
 
-export const CURRENT_VERSION = "0.12.0";
+export const CURRENT_VERSION = "0.13.0";
 
 export const CHANGELOG: VersionEntry[] = [
+  {
+    version: "0.13.0",
+    date: "2026-05-11",
+    changes: [
+      {
+        type: "feature",
+        text: "Network graph search: pressing Enter on a node hash or name now zooms in on the matching node and its 1-hop neighborhood — no more squinting at the dot that just got selected. Country searches still focus the country's subgraph; address searches use their own fit path.",
+      },
+      {
+        type: "feature",
+        text: "Network graph address search: a 0x address now opens a dedicated panel (right side) listing the copyable wallet, link count, and a Staking section showing every CCN the address stakes on with per-position and total ALEPH. The spotlight dims everything outside the wallet's footprint — nodes where the address is the staker, owner, or reward target stay full opacity, the rest fade. Pulse rings still mark the matches.",
+      },
+      {
+        type: "feature",
+        text: "Network graph CCN/CRN cards: new Location row with flag emoji and country name (e.g. 🇫🇷 France) — visible regardless of whether the Geo layer is on, since country attribution is now independent of the layer toggle.",
+      },
+      {
+        type: "ui",
+        text: "Network graph search field: same width (280px) as the detail cards so the column reads as one stack, and the info-icon button shrunk to a 28×28 target tight against the input (was a chunky pill-shaped lozenge with extra padding).",
+      },
+      {
+        type: "ui",
+        text: "Network graph panels: closing the node detail panel (× button) now also clears the search input — previously you had to clear the field separately.",
+      },
+      {
+        type: "fix",
+        text: "Network graph country nodes rendered as flat black circles because the cyan CSS token's OKLCH chroma was out of sRGB gamut at hue 200° and got silently dropped by Lightning CSS. Lowered chroma to a safe value; country nodes now render in their intended cyan-teal.",
+      },
+    ],
+  },
   {
     version: "0.12.0",
     date: "2026-05-11",

src/app/network/page.tsx

@@ -15,15 +15,21 @@ const STAKER: GraphNode = {
 
 describe("NetworkDetailPanelAddress", () => {
   it("renders the address, degree summary, and wallet link when degree > 0", () => {
-    render(<NetworkDetailPanelAddress node={STAKER} degree={4} />);
+    render(<NetworkDetailPanelAddress node={STAKER} degree={4} nodeState={undefined} />);
     expect(screen.getByText(/Connected to 4 CCNs/i)).toBeInTheDocument();
     expect(
       screen.getByRole("link", { name: /Open wallet view/i }),
     ).toHaveAttribute("href", `/wallet?address=${STAKER.id}`);
   });
 
   it("hides the degree line when degree is 0", () => {
-    render(<NetworkDetailPanelAddress node={STAKER} degree={0} />);
+    render(
+      <NetworkDetailPanelAddress
+        node={STAKER}
+        degree={0}
+        nodeState={undefined}
+      />,
+    );
     expect(screen.queryByText(/Connected to/i)).not.toBeInTheDocument();
   });
 
@@ -32,6 +38,7 @@ describe("NetworkDetailPanelAddress", () => {
       <NetworkDetailPanelAddress
         node={{ ...STAKER, kind: "reward" }}
         degree={2}
+        nodeState={undefined}
       />,
     );
     expect(screen.getByText(/Connected to 2 nodes/i)).toBeInTheDocument();

src/changelog.ts

@@ -2,14 +2,17 @@
 
 import Link from "next/link";
 import { CopyableText } from "@aleph-front/ds/copyable-text";
+import type { NodeState } from "@/api/credit-types";
 import type { GraphNode } from "@/lib/network-graph-model";
+import { NetworkStakingSection } from "./network-staking-section";
 
 type Props = {
   node: GraphNode;
   degree: number;
+  nodeState: NodeState | undefined;
 };
 
-export function NetworkDetailPanelAddress({ node, degree }: Props) {
+export function NetworkDetailPanelAddress({ node, degree, nodeState }: Props) {
   const noun = node.kind === "staker" ? "CCNs" : "nodes";
 
   return (
@@ -28,6 +31,8 @@ export function NetworkDetailPanelAddress({ node, degree }: Props) {
         </p>
       )}
 
+      <NetworkStakingSection address={node.id} nodeState={nodeState} />
+
       <Link
         href={`/wallet?address=${node.id}`}
         className="block text-sm font-medium text-primary-300 hover:underline"

src/components/network/network-detail-panel-address.test.tsx

@@ -3,9 +3,12 @@
 import { Badge } from "@aleph-front/ds/badge";
 import { CopyableText } from "@aleph-front/ds/copyable-text";
 import type { CCNInfo } from "@/api/credit-types";
+import { countryFlag } from "@/lib/country-flag";
+import { countryName } from "@/lib/network-address-info";
 
 type Props = {
   info: CCNInfo;
+  country?: string | undefined;
 };
 
 const ALEPH_FMT = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
@@ -16,9 +19,11 @@ function ccnChipVariant(info: CCNInfo): "success" | "warning" | "default" {
   return "warning";
 }
 
-export function NetworkDetailPanelCCN({ info }: Props) {
+export function NetworkDetailPanelCCN({ info, country }: Props) {
   const crnCount = info.resourceNodes.length;
   const stakerCount = Object.keys(info.stakers).length;
+  const flag = country ? countryFlag(country) : null;
+  const land = country ? countryName(country) : null;
 
   return (
     <div className="space-y-4 px-4 py-3 text-sm">
@@ -39,6 +44,15 @@ export function NetworkDetailPanelCCN({ info }: Props) {
           <dt className="text-muted-foreground">Score</dt>
           <dd className="font-mono text-xs">{info.score.toFixed(2)}</dd>
         </div>
+        {land && (
+          <div className="flex justify-between">
+            <dt className="text-muted-foreground">Location</dt>
+            <dd className="flex items-center gap-1.5">
+              {flag && <span aria-hidden>{flag}</span>}
+              <span>{land}</span>
+            </dd>
+          </div>
+        )}
       </dl>
 
       <div className="grid grid-cols-2 gap-2">

src/components/network/network-detail-panel-address.tsx

@@ -6,10 +6,13 @@ import { Skeleton } from "@aleph-front/ds/ui/skeleton";
 import { ResourceBar } from "@/components/resource-bar";
 import { useNode } from "@/hooks/use-nodes";
 import type { CCNInfo, CRNInfo } from "@/api/credit-types";
+import { countryFlag } from "@/lib/country-flag";
+import { countryName } from "@/lib/network-address-info";
 
 type Props = {
   info: CRNInfo;
   parent: CCNInfo | null;
+  country?: string | undefined;
   onFocusParent: (parentId: string) => void;
 };
 
@@ -19,10 +22,12 @@ function crnChipVariant(info: CRNInfo): "success" | "warning" | "default" {
   return "warning";
 }
 
-export function NetworkDetailPanelCRN({ info, parent, onFocusParent }: Props) {
+export function NetworkDetailPanelCRN({ info, parent, country, onFocusParent }: Props) {
   const { data: node, isLoading } = useNode(info.hash);
   const showResources =
     isLoading || (node?.resources != null && node.resources.vcpusTotal > 0);
+  const flag = country ? countryFlag(country) : null;
+  const land = country ? countryName(country) : null;
 
   return (
     <div className="space-y-4 px-4 py-3 text-sm">
@@ -51,6 +56,15 @@ export function NetworkDetailPanelCRN({ info, parent, onFocusParent }: Props) {
             )}
           </dd>
         </div>
+        {land && (
+          <div className="flex justify-between">
+            <dt className="text-muted-foreground">Location</dt>
+            <dd className="flex items-center gap-1.5">
+              {flag && <span aria-hidden>{flag}</span>}
+              <span>{land}</span>
+            </dd>
+          </div>
+        )}
       </dl>
 
       <div className="space-y-1 border-t border-edge pt-3">