servicemap 0.1.28 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "servicemap",
-  "version": "0.1.28",
+  "version": "0.1.34",
   "description": "Generate an internal service map page or desktop app for a software project.",
   "type": "module",
   "bin": {

package/servicemap/scripts/generate-page.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
 
 const defaultInput = '.servicemap/internal-servicemap.json';
 
@@ -21,6 +22,14 @@ async function readJson(path) {
   return JSON.parse(await readFile(path, 'utf8'));
 }
 
+async function readJsonOrNull(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 function routeFor(root, framework) {
   if (framework === 'next-app-router') {
     const base = existsSync(join(root, 'src/app')) ? 'src/app' : 'app';
@@ -56,6 +65,7 @@ function pageCss() {
     .servicemap-topbar { height: 88px; display: flex; align-items: center; justify-content: space-between; gap: 18px; padding: 0 28px; border-bottom: 1px solid rgba(255,255,255,0.08); background: #222823; }
     .brand { display: flex; align-items: center; gap: 16px; min-width: 0; }
     .brand-mark { width: 48px; height: 48px; border-radius: 10px; border: 1px solid #2a7958; background: #164d39; color: #7cf1b5; display: grid; place-items: center; box-shadow: 0 0 26px rgba(82,255,166,0.16); font-size: 22px; }
+    .brand-mark img, .hub-inner img, .three-core img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
     .brand h1 { margin: 0; font-size: 20px; line-height: 1; letter-spacing: 0; }
     .brand p, .top-meta { margin: 6px 0 0; color: #8aa097; font-size: 14px; }
     .top-actions { display: flex; align-items: center; gap: 12px; color: #8da59a; font-size: 14px; white-space: nowrap; }
@@ -63,15 +73,20 @@ function pageCss() {
     .mode-button { min-height: 36px; border: 0; border-radius: 8px; background: transparent; color: #789086; padding: 0 12px; cursor: pointer; font: inherit; font-weight: 800; }
     .mode-button.is-active { background: #276f53; color: #c9f9df; box-shadow: 0 0 18px rgba(101,240,173,0.16); }
     .map { position: relative; height: calc(100vh - 88px); min-height: 760px; background: radial-gradient(circle at 50% 52%, rgba(41, 96, 69, 0.22), transparent 24%), radial-gradient(circle at 1px 1px, rgba(88, 160, 120, 0.2) 1px, transparent 1px), #020806; background-size: auto, 28px 28px, auto; }
+    .map-plane { position: absolute; inset: 0; transform: scale(var(--zoom, 1)); transform-origin: 50% 50%; transition: transform 160ms ease; }
     .intro { position: absolute; left: 32px; top: 32px; z-index: 20; }
     .intro strong { display: block; color: #779286; font-size: 12px; letter-spacing: 0.22em; text-transform: uppercase; }
     .intro span { display: block; margin-top: 8px; color: #53665d; font-size: 14px; }
-    .edges { position: absolute; inset: 0; width: 100%; height: 100%; }
+    .edges { position: absolute; inset: 0; z-index: 26; width: 100%; height: 100%; pointer-events: none; }
+    .edge-line { transition: opacity 180ms ease, stroke 180ms ease; }
+    .edge-line.is-active { stroke: #65f0ad !important; stroke-width: 0.28; stroke-linecap: round; stroke-dasharray: 0.72 0.58; animation: servicemapDash 1.1s linear infinite; filter: drop-shadow(0 0 6px rgba(101,240,173,0.72)); opacity: 1; }
+    .edge-line.is-muted { opacity: 0.24; }
     .hub { position: absolute; left: 50%; top: 50%; z-index: 20; width: 132px; height: 132px; transform: translate(-50%, -50%); border-radius: 24px; border: 1px solid #315c47; background: #09120d; display: grid; place-items: center; box-shadow: 0 0 0 9px rgba(79,183,128,0.12), 0 0 42px rgba(100,255,174,0.16); }
     .hub-inner { width: 92px; height: 92px; border-radius: 18px; background: #fbfbf7; color: #111612; display: grid; place-items: center; font-size: 40px; box-shadow: inset 0 0 0 1px rgba(0,0,0,0.08); }
     .service-node { position: absolute; z-index: 10; width: 250px; height: 74px; transform: translate(-50%, -50%); display: flex; align-items: center; gap: 16px; padding: 0 16px; border-radius: 8px; border: 1px solid #274036; background: rgba(16,24,19,0.95); box-shadow: 0 0 0 1px rgba(140,255,190,0.05), 0 18px 44px rgba(0,0,0,0.38); }
     button.service-node { cursor: pointer; color: inherit; font: inherit; text-align: left; }
     .service-node:hover, .service-node.is-selected { border-color: #66efae; box-shadow: 0 0 0 2px rgba(101,240,173,0.42), 0 18px 44px rgba(0,0,0,0.38); }
+    .service-node.is-selected { z-index: 27; }
     .logo { width: 48px; height: 48px; flex: 0 0 auto; border-radius: 8px; display: grid; place-items: center; overflow: hidden; color: #fff; font-weight: 700; }
     .logo img { width: 28px; height: 28px; object-fit: contain; filter: invert(1); }
     .service-copy { min-width: 0; }
@@ -82,6 +97,11 @@ function pageCss() {
     .status-medium, .status-low { color: #f1c85b; background: #f1c85b; }
     .legend { position: absolute; left: 50%; bottom: 32px; z-index: 20; transform: translateX(-50%); display: flex; align-items: center; gap: 20px; border: 1px solid rgba(255,255,255,0.1); border-radius: 999px; background: rgba(11,20,15,0.9); color: #789086; padding: 8px 20px; font-size: 12px; }
     .legend i { display: inline-block; width: 8px; height: 8px; margin-right: 8px; border-radius: 999px; }
+    .zoom-controls { position: absolute; left: 28px; bottom: 26px; z-index: 29; display: grid; overflow: hidden; border: 1px solid rgba(255,255,255,0.12); border-radius: 10px; background: rgba(7,14,10,0.9); box-shadow: 0 12px 32px rgba(0,0,0,0.34); }
+    .zoom-button { width: 38px; height: 36px; border: 0; border-bottom: 1px solid rgba(255,255,255,0.1); background: transparent; color: #a8bbb2; cursor: pointer; font: inherit; font-size: 22px; line-height: 1; }
+    .zoom-button:last-child { border-bottom: 0; font-size: 18px; }
+    .zoom-button:hover { background: rgba(101,240,173,0.1); color: #d8f8e8; }
+    .fit-icon { display: inline-block; width: 15px; height: 15px; border: 2px solid currentColor; border-radius: 3px; }
     .scan-foot { position: absolute; right: 32px; bottom: 32px; z-index: 20; color: #53665d; text-align: right; font-size: 12px; line-height: 1.6; }
     .access-warning { position: absolute; left: 32px; right: 32px; bottom: 88px; z-index: 25; max-width: 720px; border: 1px solid rgba(241,200,91,0.42); border-radius: 8px; background: rgba(31,27,12,0.92); color: #f7daa0; padding: 12px 14px; font-size: 14px; line-height: 1.45; }
     .drawer-scrim { position: absolute; inset: 0; z-index: 24; background: rgba(0,0,0,0.58); pointer-events: none; }
@@ -109,16 +129,21 @@ function pageCss() {
     .delete-button { color: #ff6b57; background: transparent; font-weight: 800; }
     .save-button { min-height: 48px; border-radius: 10px; background: #287a5a; color: #effbf5; padding: 0 18px; font-weight: 800; box-shadow: 0 10px 30px rgba(54,180,126,0.18); }
     .helper-text { margin: 10px 0 0; color: #687c72; font-size: 12px; line-height: 1.45; }
-    .three-scene { position: absolute; inset: 0; perspective: 920px; overflow: hidden; cursor: grab; touch-action: none; }
-    .three-scene:active { cursor: grabbing; }
-    .three-space { position: absolute; left: 50%; top: 50%; width: 620px; height: 620px; transform-style: preserve-3d; transform: translate(-50%, -50%) rotateX(var(--rx, 58deg)) rotateZ(var(--rz, -28deg)); transition: transform 140ms ease; pointer-events: none; }
-    .three-link { position: absolute; left: 50%; top: 50%; width: var(--length); height: 1px; transform-origin: 0 0; transform: translate3d(0, 0, 0) rotateZ(var(--angle)) translateY(var(--z)); background: linear-gradient(90deg, rgba(101,240,173,0.42), rgba(101,240,173,0.05)); }
-    .three-node { position: absolute; left: 50%; top: 50%; width: 82px; height: 82px; transform: translate3d(var(--x), var(--y), var(--z)) translate(-50%, -50%) rotateZ(28deg) rotateX(-58deg); border: 0; border-radius: 999px; background: transparent; color: #eaf8f1; cursor: pointer; font: inherit; text-align: center; pointer-events: auto; }
-    .three-orb { display: grid; place-items: center; width: 38px; height: 38px; margin: 0 auto 7px; border-radius: 999px; background: var(--color); color: #fff; box-shadow: 0 0 28px color-mix(in srgb, var(--color), transparent 44%); font-size: 12px; font-weight: 900; }
-    .three-node span { display: block; font-size: 10px; line-height: 1.15; text-shadow: 0 2px 8px #000; }
-    .three-node.is-selected .three-orb { outline: 2px solid #65f0ad; outline-offset: 4px; }
-    .three-core { position: absolute; left: 50%; top: 50%; display: grid; place-items: center; width: 72px; height: 72px; transform: translate(-50%, -50%); border-radius: 999px; background: #f7faf7; color: #101611; font-size: 30px; box-shadow: 0 0 0 10px rgba(101,240,173,0.14), 0 0 46px rgba(101,240,173,0.22); }
-    .three-hint { position: absolute; left: 50%; bottom: 30px; z-index: 21; transform: translateX(-50%); border: 1px solid rgba(255,255,255,0.1); border-radius: 999px; background: rgba(11,20,15,0.9); color: #789086; padding: 10px 18px; font-size: 12px; }
+    .graph-3d { position: absolute; inset: 0; overflow: hidden; }
+    .graph-3d::before { content: ''; position: absolute; z-index: 1; inset: 0; pointer-events: none; background: radial-gradient(circle at 50% 50%, transparent 38%, rgba(2,5,4,.46) 100%); }
+    .graph-3d canvas { display: block; cursor: grab; }
+    .graph-3d canvas:active { cursor: grabbing; }
+    .graph-3d__help, .graph-3d__focus { position: absolute; z-index: 3; bottom: 20px; border: 1px solid rgba(255,255,255,.07); background: rgba(9,14,11,.74); color: #718078; font-size: 8px; backdrop-filter: blur(14px); pointer-events: none; }
+    .graph-3d__help { left: 50%; transform: translateX(-50%); display: flex; align-items: center; gap: 8px; padding: 8px 12px; border-radius: 999px; white-space: nowrap; }
+    .graph-3d__help span { width: 3px; height: 3px; border-radius: 50%; background: #4a5a52; }
+    .graph-3d__focus { left: 22px; padding: 8px 10px; border-radius: 8px; color: #91bba7; }
+    .graph-3d__zoom { position: absolute; z-index: 4; right: 22px; bottom: 20px; display: flex; flex-direction: column; overflow: hidden; border: 1px solid rgba(255,255,255,.1); border-radius: 10px; background: rgba(9,14,11,.82); box-shadow: 0 10px 28px rgba(0,0,0,.3); backdrop-filter: blur(14px); }
+    .graph-3d__zoom button { width: 36px; height: 34px; padding: 0; border: 0; display: grid; place-items: center; background: transparent; color: #aebbb4; cursor: pointer; transition: color .18s ease, background .18s ease; font-size: 20px; }
+    .graph-3d__zoom button + button { border-top: 1px solid rgba(255,255,255,.08); }
+    .graph-3d__zoom button:hover { color: #fff; background: rgba(255,255,255,.08); }
+    .graph-3d__loading { position: absolute; inset: 0; display: grid; place-items: center; color: #75857c; font-size: 9px; }
+    @keyframes servicemapDash { to { stroke-dashoffset: -1.3; } }
+    @keyframes servicemapLinkFlow { to { background-position: 22px 0; } }
     @media (max-width: 920px) {
       .map { min-height: 1120px; }
       .service-node { width: 220px; }
@@ -147,6 +172,11 @@ function initials(name) {
   return name.split(/\s+/).filter(Boolean).slice(0, 2).map((part) => part[0]).join('').toUpperCase();
 }
 
+function projectMarkHtml(graph) {
+  const logoUrl = graph.project?.logoUrl;
+  return logoUrl ? `<img src="${escapeHtml(logoUrl)}" alt="${escapeHtml(graph.project?.name ?? 'Project')} logo">` : '⌘';
+}
+
 function htmlBody(graph) {
   const services = graph.services ?? [];
   const access = graph.access ?? {};
@@ -160,6 +190,7 @@ function htmlBody(graph) {
     color: palette[index % palette.length],
   }));
   const edges = nodes.map((node) => `<path d="${edgePath(node)}" fill="none" stroke="rgba(103, 130, 118, 0.48)" stroke-width="0.16" vector-effect="non-scaling-stroke"></path>`).join('');
+  const projectMark = projectMarkHtml(graph);
   const serviceNodes = nodes.map((service) => `
     <article class="service-node" style="left:${service.x}%;top:${service.y}%">
       <div class="logo" style="background:${service.color}">${service.iconUrl ? `<img src="${escapeHtml(service.iconUrl)}" alt="">` : escapeHtml(initials(service.name))}</div>
@@ -175,7 +206,7 @@ function htmlBody(graph) {
     <main class="servicemap-shell">
       <header class="servicemap-topbar">
         <div class="brand">
-          <div class="brand-mark">⌘</div>
+          <div class="brand-mark">${projectMark}</div>
           <div>
             <h1>servicemap</h1>
             <p>${escapeHtml(graph.project?.name ?? 'Project')} command center</p>
@@ -195,7 +226,7 @@ function htmlBody(graph) {
           <span>Select a service to trace its dependencies</span>
         </div>
         <svg class="edges" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">${edges}</svg>
-        <div class="hub"><div class="hub-inner">⌘</div></div>
+        <div class="hub"><div class="hub-inner">${projectMark}</div></div>
         ${serviceNodes || '<div class="intro"><span>No external services were detected yet.</span></div>'}
         ${accessNotice}
         <div class="legend">
@@ -231,7 +262,11 @@ ${htmlBody(graph)}
 function interactiveTsxPage(graph) {
   return `'use client';
 
-import { useMemo, useState, type CSSProperties } from 'react';
+import dynamic from 'next/dynamic';
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
+import type { ForceGraphMethods, NodeObject } from 'react-force-graph-3d';
+import * as THREE from 'three';
+import SpriteText from 'three-spritetext';
 
 const css = ${JSON.stringify(pageCss())};
 type Evidence = { type?: string; value?: string; confidence?: string };
@@ -239,10 +274,15 @@ type RawService = { id: string; name: string; key?: string; category?: string; c
 type ServiceNode = RawService & { color: string; x: number; y: number };
 type DraftDetails = { subtitle: string; use: string; account: string; passwordLocation: string };
 type ServiceLink = { label: string; url: string };
+type GraphNode3D = { id: string; name: string; category: string; color: string; iconUrl?: string | null; monogram: string; isProduct: boolean; x?: number; y?: number; z?: number };
+type GraphLink3D = { id: string; source: string | GraphNode3D; target: string | GraphNode3D; label: string };
+type AdjustableForce = { strength?: (value: number) => unknown; distance?: (value: number) => unknown };
+type OrbitControlsLike = { target?: THREE.Vector3 };
 
-const graph = ${JSON.stringify(graph)} as { generatedAt: string; project?: { name?: string }; services?: RawService[] };
+const graph = ${JSON.stringify(graph)} as { generatedAt: string; project?: { name?: string; logoUrl?: string }; services?: RawService[] };
 const palette = ${JSON.stringify(palette)} as string[];
 const layout = ${JSON.stringify(layout)} as Array<{ x: number; y: number }>;
+const ForceGraph3D = dynamic(() => import('react-force-graph-3d'), { ssr: false });
 
 function categoryLabel(value?: string | null) {
   return String(value ?? 'service').replace(/-/g, ' ');
@@ -260,41 +300,85 @@ function edgePath(node: ServiceNode) {
   return \`M \${fromX} \${node.y} H \${midX} V 50 H \${endX}\`;
 }
 
-function threePosition(index: number, count: number) {
-  const angle = (index / Math.max(count, 1)) * Math.PI * 2 - Math.PI / 2;
-  const radius = index % 3 === 0 ? 270 : index % 3 === 1 ? 215 : 320;
-  const z = ((index % 5) - 2) * 32;
-  return {
-    x: Math.cos(angle) * radius,
-    y: Math.sin(angle) * radius,
-    z,
-    angle: (angle * 180) / Math.PI,
-    length: radius,
-  };
+function primaryEvidence(service: RawService) {
+  const evidence = service.evidence?.[0];
+  return evidence ? \`\${evidence.type}: \${evidence.value}\` : 'No evidence captured yet.';
 }
 
-function threeNodeStyle(index: number, count: number, color: string): CSSProperties {
-  const position = threePosition(index, count);
-  return {
-    '--x': \`\${position.x}px\`,
-    '--y': \`\${position.y}px\`,
-    '--z': \`\${position.z}px\`,
-    '--color': color,
-  } as CSSProperties;
+function endpointId(endpoint: string | number | GraphNode3D) {
+  return typeof endpoint === 'object' ? endpoint.id : String(endpoint);
 }
 
-function threeLinkStyle(index: number, count: number): CSSProperties {
-  const position = threePosition(index, count);
-  return {
-    '--angle': \`\${position.angle}deg\`,
-    '--length': \`\${position.length}px\`,
-    '--z': \`\${position.z}px\`,
-  } as CSSProperties;
+function graphNode(node: NodeObject) {
+  return node as GraphNode3D;
 }
 
-function primaryEvidence(service: RawService) {
-  const evidence = service.evidence?.[0];
-  return evidence ? \`\${evidence.type}: \${evidence.value}\` : 'No evidence captured yet.';
+function graphLink(link: GraphLink3D) {
+  return link;
+}
+
+function iconObject(node: GraphNode3D, selected: boolean) {
+  const group = new THREE.Group();
+  const radius = node.isProduct ? 10 : 7;
+  const shell = new THREE.Mesh(
+    new THREE.SphereGeometry(radius, 32, 32),
+    new THREE.MeshStandardMaterial({
+      color: new THREE.Color(node.color),
+      emissive: new THREE.Color(node.color),
+      emissiveIntensity: selected ? 0.65 : 0.23,
+      metalness: 0.18,
+      roughness: 0.48,
+    }),
+  );
+  group.add(shell);
+
+  const halo = new THREE.Mesh(
+    new THREE.SphereGeometry(radius + (selected ? 2.2 : 1.25), 24, 24),
+    new THREE.MeshBasicMaterial({ color: selected ? '#9ff0cb' : node.color, transparent: true, opacity: selected ? 0.18 : 0.07, side: THREE.BackSide }),
+  );
+  group.add(halo);
+
+  const fallback = new SpriteText(node.monogram.slice(0, 3));
+  fallback.color = '#ffffff';
+  fallback.textHeight = node.isProduct ? 4.2 : 3.2;
+  fallback.fontSize = 180;
+  fallback.fontWeight = '700';
+  fallback.renderOrder = 10;
+  fallback.material.depthTest = false;
+  fallback.material.depthWrite = false;
+  group.add(fallback);
+
+  if (node.iconUrl) {
+    new THREE.TextureLoader().load(node.iconUrl, (texture) => {
+      texture.colorSpace = THREE.SRGBColorSpace;
+      texture.anisotropy = 16;
+      texture.minFilter = THREE.LinearMipmapLinearFilter;
+      texture.magFilter = THREE.LinearFilter;
+      texture.generateMipmaps = true;
+      texture.needsUpdate = true;
+      const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false, depthWrite: false, alphaTest: 0.015 }));
+      const size = node.isProduct ? 12 : 8.5;
+      sprite.scale.set(size, size, 1);
+      sprite.renderOrder = 10;
+      group.add(sprite);
+      fallback.visible = false;
+    });
+  }
+
+  const label = new SpriteText(node.name);
+  label.color = selected ? '#b9f6da' : '#dfeae4';
+  label.textHeight = selected ? 5.4 : 4.7;
+  label.fontSize = 220;
+  label.fontWeight = selected ? '700' : '600';
+  label.backgroundColor = 'rgba(5, 8, 7, .72)';
+  label.padding = 1.5;
+  label.borderRadius = 2;
+  label.position.y = -(radius + 6.8);
+  label.renderOrder = 11;
+  label.material.depthTest = false;
+  label.material.depthWrite = false;
+  group.add(label);
+  return group;
 }
 
 function serviceLinks(service: RawService): ServiceLink[] {
@@ -325,6 +409,15 @@ function ServiceLogo({ service }: { service: RawService & { color: string } }) {
   );
 }
 
+function ProjectMark() {
+  return graph.project?.logoUrl ? (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img src={graph.project.logoUrl} alt={\`\${graph.project?.name ?? 'Project'} logo\`} />
+  ) : (
+    <>⌘</>
+  );
+}
+
 function DetailsPanel({
   service,
   details,
@@ -418,6 +511,170 @@ function DetailsPanel({
   );
 }
 
+function ServiceGraph3D({
+  nodes,
+  selectedId,
+  onSelect,
+}: {
+  nodes: ServiceNode[];
+  selectedId: string | null;
+  onSelect: (id: string | null) => void;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const graphRef = useRef<ForceGraphMethods<GraphNode3D, GraphLink3D> | undefined>(undefined);
+  const [size, setSize] = useState({ width: 900, height: 700 });
+  const hasFramed = useRef(false);
+  const graphData = useMemo(() => ({
+    nodes: [{
+      id: 'project',
+      name: graph.project?.name ?? 'Project',
+      category: 'product',
+      color: '#8be4b2',
+      iconUrl: graph.project?.logoUrl,
+      monogram: initials(graph.project?.name ?? 'Project'),
+      isProduct: true,
+    }, ...nodes.map((node): GraphNode3D => ({
+      id: node.id,
+      name: node.name,
+      category: categoryLabel(node.category),
+      color: node.color,
+      iconUrl: node.iconUrl,
+      monogram: initials(node.name),
+      isProduct: node.category === 'product',
+    }))],
+    links: nodes.map((node): GraphLink3D => ({
+      id: \`project-\${node.id}\`,
+      source: 'project',
+      target: node.id,
+      label: node.confidence === 'high' ? 'uses' : 'may use',
+    })),
+  }), [nodes]);
+
+  const activeIds = useMemo(() => {
+    const ids = new Set<string>();
+    if (!selectedId) return ids;
+    ids.add(selectedId);
+    graphData.links.forEach((link) => {
+      const source = endpointId(link.source);
+      const target = endpointId(link.target);
+      if (source === selectedId) ids.add(target);
+      if (target === selectedId) ids.add(source);
+    });
+    return ids;
+  }, [graphData.links, selectedId]);
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+    const observer = new ResizeObserver(([entry]) => {
+      setSize({ width: Math.max(1, entry.contentRect.width), height: Math.max(1, entry.contentRect.height) });
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    const graphInstance = graphRef.current;
+    if (!graphInstance) return;
+    const charge = graphInstance.d3Force('charge') as AdjustableForce | undefined;
+    const link = graphInstance.d3Force('link') as AdjustableForce | undefined;
+    graphInstance.renderer().setPixelRatio(Math.min(window.devicePixelRatio * 1.5, 3));
+    charge?.strength?.(-230);
+    link?.distance?.(92);
+    graphInstance.d3ReheatSimulation();
+    hasFramed.current = false;
+  }, [graphData.nodes.length, graphData.links.length]);
+
+  const focusNode = useCallback((node: NodeObject) => {
+    const serviceNode = graphNode(node);
+    onSelect(serviceNode.id);
+    if (serviceNode.x === undefined || serviceNode.y === undefined || serviceNode.z === undefined) return;
+    const distance = Math.hypot(serviceNode.x, serviceNode.y, serviceNode.z) || 1;
+    const ratio = 1 + 105 / distance;
+    graphRef.current?.cameraPosition(
+      { x: serviceNode.x * ratio, y: serviceNode.y * ratio, z: serviceNode.z * ratio },
+      { x: serviceNode.x, y: serviceNode.y, z: serviceNode.z },
+      850,
+    );
+  }, [onSelect]);
+
+  const zoom = useCallback((factor: number) => {
+    const graphInstance = graphRef.current;
+    if (!graphInstance) return;
+    const camera = graphInstance.camera();
+    const controls = graphInstance.controls() as OrbitControlsLike;
+    const target = controls.target?.clone() ?? new THREE.Vector3();
+    const offset = camera.position.clone().sub(target);
+    const currentDistance = offset.length();
+    if (currentDistance === 0) return;
+    const nextDistance = THREE.MathUtils.clamp(currentDistance * factor, 35, 1200);
+    const nextPosition = target.clone().add(offset.multiplyScalar(nextDistance / currentDistance));
+    graphInstance.cameraPosition(nextPosition, target, 240);
+  }, []);
+
+  return (
+    <div className="graph-3d" ref={containerRef}>
+      <ForceGraph3D
+        ref={graphRef as never}
+        width={size.width}
+        height={size.height}
+        graphData={graphData}
+        backgroundColor="rgba(0,0,0,0)"
+        showNavInfo={false}
+        nodeThreeObject={(node) => {
+          const serviceNode = graphNode(node);
+          return iconObject(serviceNode, serviceNode.id === selectedId);
+        }}
+        nodeLabel={(node) => {
+          const serviceNode = graphNode(node);
+          return \`\${serviceNode.name} · \${serviceNode.category}\`;
+        }}
+        linkLabel={(link) => graphLink(link as GraphLink3D).label}
+        linkColor={(link) => {
+          const serviceLink = graphLink(link as GraphLink3D);
+          if (!selectedId) return '#415149';
+          return endpointId(serviceLink.source) === selectedId || endpointId(serviceLink.target) === selectedId ? '#7ee2b8' : '#17211c';
+        }}
+        linkWidth={(link) => {
+          const serviceLink = graphLink(link as GraphLink3D);
+          return endpointId(serviceLink.source) === selectedId || endpointId(serviceLink.target) === selectedId ? 2.2 : selectedId ? 0.35 : 0.8;
+        }}
+        linkOpacity={0.8}
+        linkDirectionalArrowLength={3.5}
+        linkDirectionalArrowRelPos={0.8}
+        linkDirectionalArrowColor={(link) => {
+          const serviceLink = graphLink(link as GraphLink3D);
+          return endpointId(serviceLink.source) === selectedId || endpointId(serviceLink.target) === selectedId ? '#9ff0cb' : '#506158';
+        }}
+        linkDirectionalParticles={(link) => {
+          const serviceLink = graphLink(link as GraphLink3D);
+          return endpointId(serviceLink.source) === selectedId || endpointId(serviceLink.target) === selectedId ? 3 : 0;
+        }}
+        linkDirectionalParticleWidth={1.8}
+        linkDirectionalParticleSpeed={0.006}
+        linkDirectionalParticleColor={() => '#b9f6da'}
+        d3AlphaDecay={0.035}
+        d3VelocityDecay={0.24}
+        warmupTicks={50}
+        cooldownTicks={160}
+        onNodeClick={focusNode}
+        onBackgroundClick={() => onSelect(null)}
+        onEngineStop={() => {
+          if (hasFramed.current) return;
+          hasFramed.current = true;
+          graphRef.current?.zoomToFit(700, 72);
+        }}
+      />
+      <div className="graph-3d__zoom" aria-label="3D zoom controls">
+        <button type="button" onClick={() => zoom(0.78)} title="Zoom in" aria-label="Zoom in">+</button>
+        <button type="button" onClick={() => zoom(1.28)} title="Zoom out" aria-label="Zoom out">−</button>
+      </div>
+      <div className="graph-3d__help" aria-hidden="true">Drag to rotate <span /> Scroll to zoom <span /> Click a service</div>
+      {selectedId && <div className="graph-3d__focus" aria-hidden="true">{Math.max(activeIds.size - 1, 0)} direct connections highlighted</div>}
+    </div>
+  );
+}
+
 export default function InternalServiceMapPage() {
   const nodes = useMemo<ServiceNode[]>(() => (graph.services ?? []).slice(0, layout.length).map((service, index) => ({
     ...service,
@@ -425,7 +682,7 @@ export default function InternalServiceMapPage() {
     color: palette[index % palette.length],
   })), []);
   const [mode, setMode] = useState<'2d' | '3d'>('2d');
-  const [rotation, setRotation] = useState({ x: 58, z: -28 });
+  const [zoom, setZoom] = useState(1);
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [drafts, setDrafts] = useState<Record<string, DraftDetails>>(() => Object.fromEntries(nodes.map((service) => [
     service.id,
@@ -437,13 +694,16 @@ export default function InternalServiceMapPage() {
     },
   ])));
   const selected = nodes.find((service) => service.id === selectedId) ?? null;
+  const zoomIn = () => setZoom((current) => Math.min(1.45, Number((current + 0.12).toFixed(2))));
+  const zoomOut = () => setZoom((current) => Math.max(0.7, Number((current - 0.12).toFixed(2))));
+  const resetZoom = () => setZoom(1);
 
   return (
     <main className="servicemap-shell">
       <style dangerouslySetInnerHTML={{ __html: css }} />
       <header className="servicemap-topbar">
         <div className="brand">
-          <div className="brand-mark">⌘</div>
+          <div className="brand-mark"><ProjectMark /></div>
           <div>
             <h1>servicemap</h1>
             <p>{graph.project?.name ?? 'Project'} command center</p>
@@ -465,64 +725,54 @@ export default function InternalServiceMapPage() {
         </div>
         {mode === '2d' ? (
           <>
-            <svg className="edges" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
+            <div className="map-plane" style={{ '--zoom': zoom } as CSSProperties}>
+              <svg className="edges" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
+                {nodes.map((service) => (
+                  <path
+                    key={service.id}
+                    className={\`edge-line \${selectedId === service.id ? 'is-active' : selectedId ? 'is-muted' : ''}\`}
+                    d={edgePath(service)}
+                    fill="none"
+                    stroke={selectedId === service.id ? '#65f0ad' : 'rgba(103, 130, 118, 0.48)'}
+                    strokeWidth={selectedId === service.id ? '0.28' : '0.16'}
+                    strokeDasharray={selectedId === service.id ? '0.72 0.58' : undefined}
+                    strokeLinecap={selectedId === service.id ? 'round' : undefined}
+                    vectorEffect="non-scaling-stroke"
+                  />
+                ))}
+              </svg>
+              <div className="hub"><div className="hub-inner"><ProjectMark /></div></div>
               {nodes.map((service) => (
-                <path key={service.id} d={edgePath(service)} fill="none" stroke="rgba(103, 130, 118, 0.48)" strokeWidth="0.16" vectorEffect="non-scaling-stroke" />
-              ))}
-            </svg>
-            <div className="hub"><div className="hub-inner">⌘</div></div>
-            {nodes.map((service) => (
-              <button
-                type="button"
-                key={service.id}
-                className={\`service-node \${selectedId === service.id ? 'is-selected' : ''}\`}
-                style={{ left: \`\${service.x}%\`, top: \`\${service.y}%\` }}
-                onClick={() => setSelectedId(service.id)}
-              >
-                <ServiceLogo service={service} />
-                <div className="service-copy">
-                  <strong>{service.name}</strong>
-                  <span>{categoryLabel(service.category)}</span>
-                </div>
-                <i className={\`status-dot status-\${service.confidence}\`} />
-              </button>
-            ))}
-            <div className="legend">
-              <span><i style={{ background: '#4a7cff' }} />Cloud</span>
-              <span><i style={{ background: '#8be4b2' }} />Product</span>
-              <span><i style={{ background: '#65f0ad' }} />Active path</span>
-            </div>
-          </>
-        ) : (
-          <div className="three-scene" aria-label="3D service graph">
-            <div className="three-space" style={{ '--rx': \`\${rotation.x}deg\`, '--rz': \`\${rotation.z}deg\` } as CSSProperties}>
-              {nodes.map((service, index) => (
-                <span key={\`\${service.id}-link\`} className="three-link" style={threeLinkStyle(index, nodes.length)} />
-              ))}
-              <div className="three-core">⌘</div>
-              {nodes.map((service, index) => (
                 <button
                   type="button"
                   key={service.id}
-                  className={\`three-node \${selectedId === service.id ? 'is-selected' : ''}\`}
-                  style={threeNodeStyle(index, nodes.length, service.color)}
-                  onPointerMove={(event) => {
-                    if (event.buttons !== 1) return;
-                    setRotation((current) => ({
-                      x: Math.max(24, Math.min(72, current.x - event.movementY * 0.25)),
-                      z: current.z + event.movementX * 0.25,
-                    }));
-                  }}
+                  className={\`service-node \${selectedId === service.id ? 'is-selected' : ''}\`}
+                  style={{ left: \`\${service.x}%\`, top: \`\${service.y}%\` }}
                   onClick={() => setSelectedId(service.id)}
                 >
-                  <span className="three-orb">{initials(service.name)}</span>
-                  <span>{service.name}</span>
+                  <ServiceLogo service={service} />
+                  <div className="service-copy">
+                    <strong>{service.name}</strong>
+                    <span>{categoryLabel(service.category)}</span>
+                  </div>
+                  <i className={\`status-dot status-\${service.confidence}\`} />
                 </button>
               ))}
             </div>
-            <div className="three-hint">Drag to rotate / Scroll to zoom / Click a service</div>
-          </div>
+            <div className="legend">
+              <span><i style={{ background: '#4a7cff' }} />Cloud</span>
+              <span><i style={{ background: '#8be4b2' }} />Product</span>
+              <span><i style={{ background: '#65f0ad' }} />Active path</span>
+            </div>
+          </>
+        ) : (
+          <ServiceGraph3D nodes={nodes} selectedId={selectedId} onSelect={setSelectedId} />
         )}
+        <div className="zoom-controls" aria-label="Map zoom controls">
+          <button type="button" className="zoom-button" onClick={zoomIn} aria-label="Zoom in">+</button>
+          <button type="button" className="zoom-button" onClick={zoomOut} aria-label="Zoom out">−</button>
+          <button type="button" className="zoom-button" onClick={resetZoom} aria-label="Reset zoom"><span className="fit-icon" aria-hidden="true" /></button>
+        </div>
         <footer className="scan-foot">
           <div>Generated {new Date(graph.generatedAt).toLocaleString()}</div>
           <div>{nodes.length} services detected</div>
@@ -594,14 +844,81 @@ const html = ${JSON.stringify(htmlBody(graph))};
 `;
 }
 
+async function prepareProjectLogo(graph, outputRoot) {
+  const logoPath = graph.project?.logo?.path;
+  if (!logoPath) return;
+
+  const sourceRoot = graph.project?.root ? resolve(graph.project.root) : outputRoot;
+  const sourcePath = isAbsolute(logoPath) ? logoPath : resolve(sourceRoot, logoPath);
+  if (!existsSync(sourcePath)) return;
+
+  const extension = extname(sourcePath) || '.png';
+  const assetDir = join(outputRoot, 'public', 'internalservicemap-assets');
+  const assetPath = join(assetDir, `project-logo${extension}`);
+  await mkdir(assetDir, { recursive: true });
+  await copyFile(sourcePath, assetPath);
+
+  graph.project.logoUrl = `/internalservicemap-assets/project-logo${extension}`;
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', ...options });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`${command} ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+async function ensureInteractivePageDependencies(root, routeKind) {
+  if (routeKind === 'static' || routeKind === 'astro') return;
+  const packageJsonPath = join(root, 'package.json');
+  const packageJson = await readJsonOrNull(packageJsonPath);
+  if (!packageJson) return;
+
+  const dependencies = {
+    'react-force-graph-3d': '^1.29.1',
+    three: '^0.185.1',
+    'three-spritetext': '^1.10.0',
+  };
+  const devDependencies = {
+    '@types/three': '^0.185.4',
+  };
+  let changed = false;
+
+  packageJson.dependencies ??= {};
+  for (const [name, version] of Object.entries(dependencies)) {
+    if (packageJson.dependencies[name] || packageJson.devDependencies?.[name]) continue;
+    packageJson.dependencies[name] = version;
+    changed = true;
+  }
+
+  packageJson.devDependencies ??= {};
+  for (const [name, version] of Object.entries(devDependencies)) {
+    if (packageJson.dependencies?.[name] || packageJson.devDependencies[name]) continue;
+    packageJson.devDependencies[name] = version;
+    changed = true;
+  }
+
+  if (!changed) return;
+  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+  if (existsSync(join(root, 'package-lock.json'))) {
+    await run('npm', ['install'], { cwd: root });
+  }
+}
+
 async function main() {
   const options = parseArgs();
   const graph = await readJson(options.input);
+  await prepareProjectLogo(graph, options.root);
   const route = routeFor(options.root, graph.project?.framework);
   const contents = route.kind === 'astro' ? astroPage(graph) : route.kind === 'static' ? staticHtml(graph) : tsxPage(graph);
 
   await mkdir(dirname(route.path), { recursive: true });
   await writeFile(route.path, contents);
+  await ensureInteractivePageDependencies(options.root, route.kind);
   console.log(`Wrote /internalservicemap page to ${route.path}`);
 }
 

package/servicemap/scripts/scan-project.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -194,6 +194,36 @@ function buildGeneratedRules(database) {
   }));
 }
 
+function normalizeLookup(value) {
+  return String(value ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+
+function buildDatabaseLookup(database) {
+  const lookup = new Map();
+  for (const entry of database) {
+    const values = [entry.key, entry.name, ...(entry.aliases ?? [])];
+    for (const value of values) {
+      const normalized = normalizeLookup(value);
+      if (normalized && !lookup.has(normalized)) lookup.set(normalized, entry);
+    }
+  }
+  return lookup;
+}
+
+function enrichDetectedServices(services, database) {
+  const lookup = buildDatabaseLookup(database);
+  return services.map((service) => {
+    const databaseEntry = lookup.get(normalizeLookup(service.key)) ?? lookup.get(normalizeLookup(service.name));
+    if (!databaseEntry) return service;
+    return {
+      ...service,
+      key: service.key ?? databaseEntry.key,
+      category: service.category ?? databaseEntry.category,
+      iconUrl: service.iconUrl ?? databaseEntry.iconUrl ?? null,
+    };
+  });
+}
+
 function matchServices({ dependencies, imports, envNames, hosts, configFiles, database }) {
   const serviceMap = new Map();
   const databaseByKey = new Map(database.map((entry) => [entry.key, entry]));
@@ -226,7 +256,7 @@ function matchServices({ dependencies, imports, envNames, hosts, configFiles, da
   if (configFiles.includes('vercel.json')) addEvidence(serviceMap, 'vercel', enrichedManualRules.find((rule) => rule.key === 'vercel'), { type: 'config-file', value: 'vercel.json', confidence: 'high' });
   if (configFiles.includes('wrangler.toml')) addEvidence(serviceMap, 'cloudflare', enrichedManualRules.find((rule) => rule.key === 'cloudflare'), { type: 'config-file', value: 'wrangler.toml', confidence: 'high' });
 
-  return [...serviceMap.values()].map((service) => ({
+  return enrichDetectedServices([...serviceMap.values()], database).map((service) => ({
     ...service,
     evidence: service.evidence.slice(0, 8),
   })).sort((a, b) => a.name.localeCompare(b.name));
@@ -240,6 +270,59 @@ function buildEdges(projectName, services) {
   }));
 }
 
+async function findProjectLogo(root, files) {
+  const appIconManifests = files
+    .filter((file) => file.endsWith('AppIcon.appiconset/Contents.json'))
+    .sort((a, b) => scoreLogoManifest(b) - scoreLogoManifest(a));
+
+  for (const manifestPath of appIconManifests) {
+    const manifest = await readJson(manifestPath);
+    const images = Array.isArray(manifest?.images) ? manifest.images : [];
+    const candidates = images
+      .filter((image) => image?.filename)
+      .map((image) => ({
+        file: join(dirname(manifestPath), image.filename),
+        score: scoreAppIconImage(image),
+      }))
+      .filter((candidate) => existsSync(candidate.file))
+      .sort((a, b) => b.score - a.score);
+
+    if (candidates[0]) {
+      return {
+        path: relative(root, candidates[0].file),
+        source: 'asset-catalog-app-icon',
+      };
+    }
+  }
+
+  const namedLogo = files.find((file) => /(^|[/\\])(app-?icon|logo|favicon)\.(png|jpg|jpeg|webp|svg|ico)$/i.test(file));
+  if (namedLogo) {
+    return {
+      path: relative(root, namedLogo),
+      source: 'named-image-file',
+    };
+  }
+
+  return null;
+}
+
+function scoreLogoManifest(path) {
+  let score = 0;
+  if (/Assets\.xcassets[/\\]AppIcon\.appiconset/i.test(path)) score += 10;
+  if (/Assets 2\.xcassets/i.test(path)) score += 20;
+  return score;
+}
+
+function scoreAppIconImage(image) {
+  const size = Number.parseInt(String(image.size ?? '0').split('x')[0], 10) || 0;
+  let score = size;
+  const filename = String(image.filename ?? '').toLowerCase();
+  if (filename.includes('dark') || filename.includes('darker')) score += 100;
+  if (filename.includes('tinted')) score -= 50;
+  if (image.platform === 'ios') score += 25;
+  return score;
+}
+
 async function main() {
   const options = parseArgs();
   const packageJsonPath = join(options.root, 'package.json');
@@ -273,6 +356,7 @@ async function main() {
     configFiles: configFiles.map((file) => basename(file)),
     database,
   });
+  const logo = await findProjectLogo(options.root, files);
 
   const graph = {
     generatedAt: new Date().toISOString(),
@@ -280,6 +364,7 @@ async function main() {
       name: projectName,
       root: options.root,
       framework: detectFramework(options.root, packageJson, files),
+      logo,
     },
     access: {
       allowedEmails: options.allowedEmails,