graphlin 0.1.1 → 0.1.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local architecture and activity viewer with passive, bounded event hooks.",
   "author": {
     "name": "Graphlin contributors"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local architecture and activity diagrams from observable coding-agent work.",
   "author": {
     "name": "Graphlin contributors"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Live architecture and activity diagrams from observable coding-agent work.",
   "private": false,
   "type": "module",
@@ -76,6 +76,7 @@
     "./runtime/core/tool-discovery.mjs",
     "./runtime/daemon/auth.mjs",
     "./runtime/daemon/connection-info.mjs",
+    "./runtime/daemon/dashboard-info.mjs",
     "./runtime/daemon/demo.mjs",
     "./runtime/daemon/diagnostics.mjs",
     "./runtime/daemon/export.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "graphlin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local architecture and activity diagrams from observable coding-agent work.",
   "extensions": {
     "com.openai": {

package/runtime/daemon/dashboard-info.mjs

@@ -0,0 +1,175 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const REGISTRY = 'https://registry.npmjs.org/graphlin/latest';
+const CACHE_MS = 30 * 60 * 1000;
+const MAX_REGISTRY_BYTES = 32 * 1024;
+const MAX_COMMAND_BYTES = 8192;
+const PACKAGE = new URL('../../package.json', import.meta.url);
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/;
+const INSTRUCTIONS = [
+  'Press Ctrl+C in the terminal running Graphlin to stop the viewer.',
+  'Run the update command to restart the viewer in this project with the same Graphlin data directory.',
+  'Start a new Claude Code or Codex agent session after the viewer restarts.',
+];
+const DEMO_INSTRUCTIONS = [
+  'Press Ctrl+C in the terminal running Graphlin to stop the demo viewer.',
+  'Run the update command to restart the offline demo with the same Graphlin data directory.',
+];
+
+const quote = value => `'${value.replaceAll("'", "'\"'\"'")}'`;
+function absolute(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) ||
+      Buffer.byteLength(value) > 4096 || CONTROLS.test(value)) throw new Error('dashboard_info_unavailable');
+  return path.resolve(value);
+}
+
+function stableVersion(value) {
+  if (typeof value !== 'string' || value.length > 80) return null;
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+  return match ? match.slice(1, 4).map(part => BigInt(part)) : null;
+}
+
+// null means unsupported/invalid, never "already latest". Build metadata does
+// not affect stable SemVer precedence; numeric components are not lexical.
+export function compareStableVersions(first, second) {
+  const a = stableVersion(first), b = stableVersion(second);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index++) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+async function runningVersion(read) {
+  try {
+    const text = await read(PACKAGE, 'utf8');
+    if (Buffer.byteLength(text) > 64 * 1024) return null;
+    const metadata = JSON.parse(text);
+    return metadata.name === 'graphlin' && stableVersion(metadata.version) ? metadata.version : null;
+  } catch { return null; }
+}
+
+function branchInfo(projectRoot, execute) {
+  return new Promise(resolve => {
+    const unavailable = () => resolve({ status: 'unavailable' });
+    try {
+      execute('git', ['-c', 'core.fsmonitor=false', 'symbolic-ref', '--quiet', '--short', 'HEAD'], {
+        cwd: projectRoot, shell: false, timeout: 750, killSignal: 'SIGKILL',
+        maxBuffer: 4096, encoding: 'utf8',
+        // Do not inherit credentials, Git overrides, or global config. This
+        // local ref lookup never runs a shell, hook, installer or remote.
+        env: {
+          PATH: process.env.PATH || '/usr/bin:/bin', LC_ALL: 'C',
+          GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+          GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0',
+        },
+      }, (error, stdout, stderr) => {
+        if (error) {
+          if (error.code === 1 && !error.killed) return resolve({ status: 'detached' });
+          if (error.code === 128 && !error.killed && typeof stderr === 'string' &&
+              stderr.includes('not a git repository')) return resolve({ status: 'not_git' });
+          return unavailable();
+        }
+        const name = typeof stdout === 'string' ? stdout.replace(/\r?\n$/, '') : '';
+        if (!name || Buffer.byteLength(name) > 1024 || CONTROLS.test(name)) return unavailable();
+        resolve({ status: 'branch', name });
+      });
+    } catch { unavailable(); }
+  });
+}
+
+async function registryVersion(fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      (async () => {
+        // Fixed destination and headers: project paths, branch names, daemon
+        // state, credentials and registry overrides never enter this request.
+        const response = await fetchImpl(REGISTRY, {
+          method: 'GET', headers: { Accept: 'application/json' },
+          redirect: 'error', credentials: 'omit', referrerPolicy: 'no-referrer',
+          signal: controller.signal,
+        });
+        if (!response.ok || Number(response.headers.get('content-length')) > MAX_REGISTRY_BYTES ||
+            !response.body) throw new Error('registry_unavailable');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            length += value.byteLength;
+            if (length > MAX_REGISTRY_BYTES) throw new Error('registry_unavailable');
+            chunks.push(Buffer.from(value));
+          }
+        } finally {
+          void reader.cancel().catch(() => {});
+          reader.releaseLock();
+        }
+        const metadata = JSON.parse(Buffer.concat(chunks, length).toString('utf8'));
+        if (metadata.name !== 'graphlin' || !stableVersion(metadata.version)) throw new Error('registry_unavailable');
+        return metadata.version;
+      })(),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new Error('registry_unavailable'));
+        }, timeoutMs);
+      }),
+    ]);
+  } catch {
+    // Raw network errors and response bodies may contain private content.
+    return null;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+// Trusted startup context only; dependencies are injectable for offline tests.
+// Creating the provider performs no registry request or Git subprocess.
+export function createDashboardInfoProvider({ projectRoot, dataDir, mode = 'live' }, {
+  fetch: fetchImpl = globalThis.fetch, execFile: execute = execFile,
+  readFile: read = readFile, now = Date.now, timeoutMs = 1500,
+} = {}) {
+  const version = runningVersion(read);
+  let cached, pending;
+  async function latestVersion() {
+    if (cached && now() < cached.expiresAt) return cached.latest;
+    if (!pending) {
+      pending = registryVersion(fetchImpl, timeoutMs).then(latest => {
+        cached = { latest, expiresAt: now() + CACHE_MS };
+        return latest;
+      }).finally(() => { pending = null; });
+    }
+    return pending;
+  }
+  return async () => {
+    // Metadata that cannot be displayed safely disables this optional endpoint,
+    // never startup, capture, or the rest of the viewer.
+    if (!['live', 'demo'].includes(mode)) throw new Error('dashboard_info_unavailable');
+    const root = absolute(projectRoot), directory = absolute(dataDir);
+    const demo = mode === 'demo';
+    const command = `${demo ? '' : `cd ${quote(root)} && `}GRAPHLIN_DATA_DIR=${quote(directory)} npx --yes graphlin@latest${demo ? ' demo' : ''}`;
+    // Never truncate a shell argument or offer instructions without a usable
+    // command. Quoting can expand otherwise valid paths beyond the UI limit.
+    const guide = Buffer.byteLength(command) <= MAX_COMMAND_BYTES
+      ? { command, instructions: [...(demo ? DEMO_INSTRUCTIONS : INSTRUCTIONS)] } : {};
+    const [current, branch, latest] = await Promise.all([
+      version, branchInfo(root, execute), latestVersion(),
+    ]);
+    if (!current) throw new Error('dashboard_info_unavailable');
+    const comparison = compareStableVersions(latest, current);
+    return {
+      projectRoot: root, mode, branch, version: current,
+      update: {
+        status: comparison === null ? 'unavailable' : comparison > 0 ? 'available' : 'current',
+        current, ...(latest ? { latest } : {}), ...guide,
+      },
+    };
+  };
+}

package/runtime/daemon/server.mjs

@@ -10,6 +10,7 @@ import { createAuth } from './auth.mjs';
 import { createPersistence } from './persistence.mjs';
 import { exportSnapshot } from './export.mjs';
 import { createDiagnostics } from './diagnostics.mjs';
+import { createDashboardInfoProvider } from './dashboard-info.mjs';
 
 const WEB = new URL('../web/', import.meta.url);
 const assets = new Map([
@@ -52,10 +53,13 @@ async function bodyJSON(req) {
 }
 
 export async function startServer({ projectRoot, dataDir, policy: policyOptions,
-  decisionService, apiKey: configuredKey, mode = 'live', port = 0 } = {}) {
+  decisionService, apiKey: configuredKey, mode = 'live', port = 0, dashboardInfoDependencies } = {}) {
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw runtimeError('invalid_port');
   if (!['live', 'demo'].includes(mode)) throw runtimeError('invalid_mode');
   const paths = await projectPaths(projectRoot, dataDir, { create: true });
+  const dashboardInfo = createDashboardInfoProvider({
+    projectRoot: paths.projectRoot, dataDir: paths.dataDir, mode,
+  }, dashboardInfoDependencies);
   const lock = await acquireLock(paths);
   let finished;
   const whenClosed = new Promise(resolve => { finished = resolve; });
@@ -157,6 +161,10 @@ export async function startServer({ projectRoot, dataDir, policy: policyOptions,
           return;
         }
         if (!auth.authorized(req)) return json(res, 401, { error: 'authentication_required' });
+        if (req.method === 'GET' && req.url === '/api/about') {
+          try { return json(res, 200, await dashboardInfo()); }
+          catch { return json(res, 503, { error: 'dashboard_info_unavailable' }); }
+        }
         if (req.method === 'GET' && req.url === '/api/diagnostics') {
           return json(res, 200, diagnostics.snapshot());
         }

package/runtime/web/app.js

@@ -157,6 +157,23 @@ export function liveNodeChanges(previous, next, eligible) {
   };
 }
 
+export function filterDiagram(graph, query) {
+  if (!query) return graph;
+  const needle = query.toLowerCase();
+  const nodes = graph.nodes.filter(node => node.label.toLowerCase().includes(needle));
+  const visible = new Set(nodes.map(node => node.id));
+  return { ...graph, nodes, edges: graph.edges.filter(edge => visible.has(edge.source) && visible.has(edge.target)) };
+}
+
+function isSearchTypingTarget(target) {
+  for (let element = target; element; element = element.parentElement) {
+    if (['input', 'textarea', 'select', 'dialog'].includes(element.tagName?.toLowerCase()) ||
+      element.isContentEditable || ['textbox', 'combobox', 'searchbox'].includes(element.getAttribute?.('role')) ||
+      ['true', '', 'plaintext-only'].includes(element.getAttribute?.('contenteditable'))) return true;
+  }
+  return false;
+}
+
 function nodeTitleWidth(shapeName) {
   return { queue: 132, component: 142, parallelogram: 144, diamond: 140 }[shapeName] || 158;
 }
@@ -816,6 +833,94 @@ export function friendlyProjectName(projectRoot) {
   return safeText(projectRoot, 4096).replace(/\/+$/, '').split('/').at(-1)?.slice(0, 120) || 'Local project';
 }
 
+export function startDashboardInfo({ load = signal => request('/api/about', { signal }) } = {}) {
+  const $ = id => document.getElementById(id);
+  let closed = false, controller = null, timer = null, pending = null, command = '';
+  function render(info) {
+    if (!record(info) || typeof info.projectRoot !== 'string' ||
+      !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?$/.test(info.version ?? '')) {
+      throw new Error('invalid_dashboard_info');
+    }
+    $('project-path').textContent = safeText(info.projectRoot, 4096) || 'Path unavailable';
+    $('graphlin-version').textContent = info.version;
+    $('version-update-steps').textContent = info.mode === 'demo'
+      ? 'Press Ctrl+C in the demo terminal, then run this command to restart the updated offline demo.'
+      : 'Press Ctrl+C in the viewer terminal, then run this command. Start a new Claude Code or Codex session after setup finishes.';
+    const branch = info.branch;
+    $('project-branch').textContent = branch?.status === 'branch'
+      ? safeText(branch.name, 1024) || 'Branch unavailable'
+      : branch?.status === 'detached' ? `Detached HEAD${branch.commit ? ` · ${safeText(branch.commit, 12)}` : ''}`
+      : branch?.status === 'not_git' ? 'Not a Git repository' : 'Branch unavailable';
+    const latest = typeof info.update?.latest === 'string' &&
+      /^\d+\.\d+\.\d+$/.test(info.update.latest) ? info.update.latest : null;
+    const available = info.update?.status === 'available' && latest;
+    $('version-update-status').textContent = available ? `Graphlin ${latest} is available`
+      : info.update?.status === 'current' ? 'No newer release found'
+      : 'Update check unavailable';
+    const nextCommand = info.update?.command;
+    command = available && typeof nextCommand === 'string' && nextCommand.trim() &&
+      nextCommand.length <= 8192 && !/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(nextCommand)
+      ? nextCommand : '';
+    $('version-update-guide').hidden = !command;
+    if ($('version-update-command').textContent !== command) {
+      $('version-update-command').textContent = command;
+      $('version-update-copy-status').textContent = '';
+    }
+  }
+  function refresh() {
+    if (closed) return Promise.resolve();
+    if (pending) return pending;
+    clearTimeout(timer);
+    controller = new AbortController();
+    pending = (async () => {
+      try {
+        await Promise.resolve();
+        if (closed) return;
+        const info = await load(controller.signal);
+        if (!closed) render(info);
+      } catch {
+        if (!closed) {
+          $('project-branch').textContent = 'Branch unavailable';
+          if ($('project-path').textContent === 'Checking…') $('project-path').textContent = 'Path unavailable';
+          if ($('graphlin-version').textContent === 'Checking…') $('graphlin-version').textContent = 'Version unavailable';
+          $('version-update-status').textContent = 'Update check unavailable';
+          $('version-update-guide').hidden = true;
+          $('version-update-command').textContent = '';
+          command = '';
+        }
+      } finally {
+        pending = null;
+        controller = null;
+        if (!closed) timer = setTimeout(() => { void refresh(); }, 30000);
+      }
+    })();
+    return pending;
+  }
+  const onCopy = async () => {
+    if (closed || !command) return;
+    const copied = command;
+    try {
+      await window.navigator.clipboard.writeText(copied);
+      if (!closed && command === copied) $('version-update-copy-status').textContent = 'Copied';
+    } catch {
+      if (!closed && command === copied) {
+        $('version-update-copy-status').textContent = 'Select the command and copy it manually.';
+        $('version-update-command').focus();
+      }
+    }
+  };
+  $('version-update-copy').addEventListener('click', onCopy);
+  return {
+    refresh,
+    close() {
+      closed = true;
+      controller?.abort();
+      clearTimeout(timer);
+      $('version-update-copy').removeEventListener('click', onCopy);
+    },
+  };
+}
+
 export const ORIENTATION_PROMPT = 'Orient yourself in this project: read its main files and explain how the components connect.';
 
 // Observations are not an installation or trust audit. Activity (including
@@ -1450,12 +1555,13 @@ export function startViewer() {
     connection: 'connecting', busy: false, exporting: false, epoch: 0, connectEpoch: 0,
     viewport: null, fitBounds: null, zoom: 1, followFit: true, lastGraphSignature: '', inspectorSignature: '',
     nodeElements: new Map(), edgeElements: new Map(), activityElements: new Map(),
-    views: new Map(), viewKey: null, view: null, displayGraph: null,
-    effects: new Map(), motionReady: false, movement: null, closed: false, projectName: '',
+    views: new Map(), viewKey: null, view: null, displayGraph: null, searchQuery: '',
+    effects: new Map(), liveReady: false, motionReady: false, movement: null, closed: false, projectName: '',
   };
   const motionPreference = window.matchMedia?.('(prefers-reduced-motion: reduce)');
   const sketches = createSketchCache();
   const detailSketches = createSketchCache(sketchDetails);
+  const dashboardInfo = startDashboardInfo();
   const connectionDialog = startConnectionDialog({ onInfo: info => {
     state.projectName = friendlyProjectName(info.projectRoot);
     renderStatus();
@@ -1524,7 +1630,7 @@ export function startViewer() {
     $('onboarding-action').dataset.action = progress.next.action;
     // Preserve a manual text selection while live snapshots arrive.
     if ($('orientation-prompt').textContent !== ORIENTATION_PROMPT) $('orientation-prompt').textContent = ORIENTATION_PROMPT;
-    $('orientation').hidden = Boolean(state.replayFrame || state.snapshot?.mode === 'demo' || state.snapshot?.mode === 'replay');
+    $('orientation').hidden = Boolean(state.searchQuery || state.replayFrame || state.snapshot?.mode === 'demo' || state.snapshot?.mode === 'replay');
   }
   function currentGraph() { return state.replayFrame?.graph || state.snapshot?.graph; }
   function applyTheme() {
@@ -1537,6 +1643,7 @@ export function startViewer() {
     if (state.viewKey !== key) {
       finishPan();
       clearMotion();
+      state.liveReady = false;
       state.motionReady = false;
       let view = state.views.get(key);
       if (!view) view = createPresentation();
@@ -1580,14 +1687,14 @@ export function startViewer() {
     state.effects.set(id, effect);
     target.addEventListener('animationend', finish);
   }
-  function cancelMovement() {
+  function cancelMovement({ fit = true } = {}) {
     const movement = state.movement;
     if (!movement) return;
     state.movement = null;
     window.cancelAnimationFrame?.(movement.frame);
     clearTimeout(movement.timer);
     if (state.displayGraph) paintGeometry(state.displayGraph);
-    if (movement.fitAfter) fitCamera(movement.fitAfter);
+    if (fit && movement.fitAfter) fitCamera(movement.fitAfter);
   }
   function clearMotion() {
     cancelMovement();
@@ -1595,10 +1702,11 @@ export function startViewer() {
   }
   function resetMotionBaseline() {
     finishPan();
+    state.liveReady = false;
     state.motionReady = false;
     clearMotion();
   }
-  function animateChanges(changes, before) {
+  function animateChanges(changes, before, focusNodeId) {
     // Re-addition always cancels a removal, even when motion is suppressed.
     for (const node of currentGraph().nodes) if (state.effects.get(node.id)?.element) finishEffect(node.id);
     if (!motionAllowed()) return;
@@ -1627,7 +1735,7 @@ export function startViewer() {
       removals.push(decoration);
     }
     if (removals.length) {
-      fitCamera(state.movement?.fitDuring || graphBounds(state.displayGraph));
+      if (!focusNodeId) fitCamera(state.movement?.fitDuring || graphBounds(state.displayGraph));
       $('empty-canvas').hidden = true;
       $('effects-layer').append(...removals);
     }
@@ -1677,15 +1785,21 @@ export function startViewer() {
     const eligible = streamed && state.motionReady && !switched && !state.replayFrame &&
       snapshot.mode !== 'replay' && state.snapshot?.mode !== 'replay' && motionAllowed();
     const changes = liveNodeChanges(state.snapshot?.graph, snapshot.graph, eligible);
+    // A live baseline is independent of animation preferences. Reconnects and
+    // initial/session snapshots establish it without focusing an old arrival.
+    const live = streamed && state.liveReady && !switched && !state.replayFrame &&
+      snapshot.mode !== 'replay' && state.snapshot?.mode !== 'replay';
+    const focusNodeId = liveNodeChanges(state.snapshot?.graph, snapshot.graph, live).added.at(-1);
     const before = state.displayGraph;
-    cancelMovement();
+    cancelMovement({ fit: !focusNodeId });
     if (switched) resetView();
     state.snapshot = snapshot;
     state.epoch += 1;
     state.frames = historyFrames(snapshot);
     state.replayFrame = reconcileReplayFrame(state.frames, state.replayFrame);
-    render();
-    animateChanges(changes, before);
+    render({ focusNodeId });
+    animateChanges(changes, before, focusNodeId);
+    state.liveReady = streamed && !state.replayFrame && snapshot.mode !== 'replay';
     state.motionReady = streamed && !state.replayFrame && snapshot.mode !== 'replay' && motionAllowed();
     $('updated-at').textContent = `Snapshot received ${formatTime(Date.now())}`;
   }
@@ -1869,6 +1983,23 @@ export function startViewer() {
     cancelMovement();
     fitCamera(graphBounds(graph));
   }
+  function focusNode(node, bounds) {
+    finishPan();
+    const zoom = Math.max(.5, state.zoom);
+    const scale = state.zoom / zoom;
+    const width = state.viewport.width * scale;
+    const height = state.viewport.height * scale;
+    state.viewport = {
+      x: node.x + NODE_WIDTH / 2 - width / 2,
+      y: node.y + NODE_HEIGHT / 2 - height / 2,
+      width, height,
+    };
+    state.zoom = zoom;
+    state.fitBounds = bounds;
+    // Removal cleanup must not replace arrival focus with a later fit-all.
+    state.followFit = false;
+    setViewBox();
+  }
   function zoom(factor, anchor = { x: .5, y: .5 }) {
     if (!state.viewport || !state.fitBounds) return;
     cancelMovement();
@@ -1885,20 +2016,23 @@ export function startViewer() {
     state.followFit = false;
     setViewBox();
   }
-  function renderGraph({ forceFit = false } = {}) {
+  function renderGraph({ forceFit = false, focusNodeId } = {}) {
     const canonical = currentGraph();
     if (!canonical) return;
     const view = presentation();
     applyTheme();
-    const graph = projectPresentation(canonical, view);
+    // Search only projects visibility; layout, evidence and live arrival
+    // detection retain the complete source graph.
+    const graph = filterDiagram(projectPresentation(canonical, view), state.searchQuery);
     state.displayGraph = graph;
     const routes = graphEdgeRoutes(graph);
     const bounds = graphBounds(graph, routes);
     const signature = cameraGraphSignature(graph, view.algorithm);
-    // Set the physical viewport before inserting newcomers or starting motion.
-    // A manual camera survives status updates, but the next diagram change fits
-    // the complete map, even with automatic arrangement disabled.
-    if (forceFit || !state.viewport || signature !== state.lastGraphSignature) fitCamera(bounds);
+    // Focus the final projected position before inserting newcomers. Other
+    // diagram changes retain fit-all; metadata-only updates keep the camera.
+    const newest = graph.nodes.find(node => node.id === focusNodeId);
+    if (newest && state.viewport && !forceFit) focusNode(newest, bounds);
+    else if (forceFit || !state.viewport || signature !== state.lastGraphSignature) fitCamera(bounds);
     state.lastGraphSignature = signature;
     $('layout').value = view.algorithm;
     $('auto-arrange').checked = view.auto;
@@ -1966,6 +2100,7 @@ export function startViewer() {
           center,
           svgElement('rect', { class: 'selection-ring', x: -7, y: -7, width: NODE_WIDTH + 14, height: NODE_HEIGHT + 14, rx: 14 }),
         );
+        group.setAttribute('transform', `translate(${node.x} ${node.y})`);
         state.nodeElements.set(node.id, group);
         $('node-layer').append(group);
       }
@@ -2009,6 +2144,9 @@ export function startViewer() {
     $('diagram-title').textContent = `${state.replayFrame ? 'Historical' : 'Live'} architecture, revision ${graph.revision}`;
     $('diagram-desc').textContent = `${graph.nodes.length} components and ${graph.edges.length} relationships. Code interpretation does not establish runtime connectivity. Use Tab and Enter to inspect a component or relationship. With the diagram focused, use plus and minus to zoom, arrow keys to pan, and 0 to fit.`;
     $('graph-count').textContent = `${graph.nodes.length} components · ${graph.edges.length} relationships`;
+    $('diagram-search-status').textContent = state.searchQuery
+      ? `${graph.nodes.length} of ${canonical.nodes.length} components shown` : '';
+    $('diagram-search-clear').hidden = !state.searchQuery;
     $('empty-canvas').hidden = graph.nodes.length > 0 || removalBounds().length > 0;
     const classifier = state.snapshot.paused ? 'paused' : state.snapshot.status.classifier;
     const emptyMessages = {
@@ -2018,7 +2156,9 @@ export function startViewer() {
       unavailable: ['Waiting for classification.', 'The classifier is unavailable. Safe activity continues below; supported architecture will appear when classification recovers.'],
       timeout: ['Evidence needs another moment.', 'Classification exceeded its deadline. Activity still appears below, and no unsupported components are added.'],
     };
-    const message = state.replayFrame
+    const message = state.searchQuery
+      ? ['No matching components.', `No labels contain “${state.searchQuery}”. Try another search or press Esc to restore the diagram.`]
+      : state.replayFrame
       ? ['No components in this revision.', 'Move through the recent revisions or return to Live to follow the current map.']
       : emptyMessages[classifier] || ['Your architecture starts here.', 'Work in a connected agent session. Components appear when approved evidence supports them; activity can arrive first.'];
     $('empty-title').textContent = message[0];
@@ -2305,10 +2445,10 @@ export function startViewer() {
     $('activity-empty').hidden = events.length > 0;
     $('activity-list').hidden = events.length === 0;
   }
-  function render() {
+  function render(graphOptions) {
     renderStatus();
     renderOnboarding();
-    renderGraph();
+    renderGraph(graphOptions);
     renderInspector();
     renderHistory();
     renderActivity();
@@ -2384,6 +2524,7 @@ export function startViewer() {
         connection('reconnecting');
         error('The live connection was lost. Displaying the last received snapshot while the viewer reconnects.');
       });
+      void dashboardInfo.refresh();
       // Optional authenticated metadata must not hold up the event stream or
       // turn an older server's missing endpoint into a connection failure.
       const controller = new AbortController();
@@ -2392,6 +2533,7 @@ export function startViewer() {
         const info = normalizeConnectionInfo(await request('/api/connection-info', { signal: controller.signal }));
         if (!state.closed && attempt === state.connectEpoch) {
           state.projectName = friendlyProjectName(info.projectRoot);
+          $('project-path').textContent = info.projectRoot;
           renderStatus();
         }
       } catch { /* The project ID remains a usable fallback. */ }
@@ -2455,6 +2597,37 @@ export function startViewer() {
   $('onboarding-action').addEventListener('click', onOnboardingAction);
   $('orientation-copy').addEventListener('click', onCopyOrientation);
   $('activity-toggle').addEventListener('click', onToggleActivity);
+  const onSearchInput = () => {
+    if (state.closed || state.searchQuery === $('diagram-search').value) return;
+    state.searchQuery = $('diagram-search').value;
+    // Filtering is not a source change: cancel existing decoration/movement
+    // and render directly, without changing the snapshot arrival baseline.
+    finishPan();
+    clearMotion();
+    renderOnboarding();
+    renderGraph({ forceFit: true });
+  };
+  const clearSearch = () => {
+    $('diagram-search').value = '';
+    onSearchInput();
+    $('diagram-search').focus({ preventScroll: true });
+  };
+  const onSearchKeyDown = event => {
+    if (state.closed || event.defaultPrevented || event.isComposing || event.ctrlKey || event.metaKey || event.altKey ||
+      $('diagnostics-dialog').open || $('connection-dialog').open || document.querySelector?.('dialog[open], [role="dialog"][aria-modal="true"]')) return;
+    const target = event.target || document.activeElement;
+    if (target !== $('diagram-search') && isSearchTypingTarget(target)) return;
+    if (event.key === '/' && target !== $('diagram-search')) {
+      event.preventDefault();
+      $('diagram-search').focus({ preventScroll: true });
+    } else if (event.key === 'Escape' && state.searchQuery) {
+      event.preventDefault();
+      clearSearch();
+    }
+  };
+  $('diagram-search').addEventListener('input', onSearchInput);
+  $('diagram-search-clear').addEventListener('click', clearSearch);
+  window.addEventListener('keydown', onSearchKeyDown);
   $('pause').addEventListener('click', () => control(state.snapshot?.paused ? 'resume' : 'pause'));
   $('session').addEventListener('change', () => control('session', $('session').value));
   $('export').addEventListener('click', exportJSON);
@@ -2595,9 +2768,13 @@ export function startViewer() {
       state.closed = true;
       projectController?.abort();
       projectController = null;
+      dashboardInfo.close();
       $('onboarding-action').removeEventListener('click', onOnboardingAction);
       $('orientation-copy').removeEventListener('click', onCopyOrientation);
       $('activity-toggle').removeEventListener('click', onToggleActivity);
+      $('diagram-search').removeEventListener('input', onSearchInput);
+      $('diagram-search-clear').removeEventListener('click', clearSearch);
+      window.removeEventListener?.('keydown', onSearchKeyDown);
       $('architecture').removeEventListener('wheel', onDiagramWheel);
       connectionDialog.dispose();
       diagnosticsDialog.dispose();

package/runtime/web/index.html

@@ -32,6 +32,22 @@
         <p id="project-label" class="project-label">Local project</p>
       </div>
 
+      <section class="project-details" aria-label="Project and Graphlin version">
+        <dl>
+          <div><dt>Branch</dt><dd id="project-branch">Checking…</dd></div>
+          <div class="project-path"><dt>Path</dt><dd id="project-path">Checking…</dd></div>
+          <div><dt>Graphlin</dt><dd id="graphlin-version">Checking…</dd></div>
+        </dl>
+        <p id="version-update-status" role="status">Checking for updates…</p>
+        <details id="version-update-guide" hidden>
+          <summary>How to update</summary>
+          <p id="version-update-steps">Press Ctrl+C in the viewer terminal, then run this command. Start a new Claude Code or Codex session after setup finishes.</p>
+          <pre id="version-update-command" tabindex="0"></pre>
+          <button id="version-update-copy" type="button">Copy update command</button>
+          <span id="version-update-copy-status" role="status"></span>
+        </details>
+      </section>
+
       <div id="demo-banner" class="notice demo-notice" role="status" hidden>
         <strong>Demo session</strong>
         <span>Generated project and fixture classifier answers. This is an offline illustration, not a live Jev evaluation.</span>
@@ -107,6 +123,13 @@
               <span class="screen-reader" id="theme-note">Colors follow component types. Themes change appearance only.</span>
               <span id="layout-note">Arranges when components or connections change.</span>
             </div>
+            <div class="diagram-search-bar" role="search" aria-label="Diagram search">
+              <label for="diagram-search">Find components</label>
+              <input id="diagram-search" type="search" maxlength="200" autocomplete="off" spellcheck="false" placeholder="Search labels…" aria-controls="architecture" aria-describedby="diagram-search-hint" aria-keyshortcuts="/">
+              <button id="diagram-search-clear" type="button" hidden>Clear search</button>
+              <span id="diagram-search-hint">/ to search · Esc to clear</span>
+              <span id="diagram-search-status" role="status" aria-live="polite" aria-atomic="true"></span>
+            </div>
             <div class="diagram-stage" id="diagram-stage">
               <svg id="architecture" viewBox="0 0 920 510" role="group" tabindex="0" aria-labelledby="diagram-title diagram-desc">
                 <title id="diagram-title">Architecture diagram</title>

package/runtime/web/style.css

@@ -171,6 +171,22 @@ h1 { font-size: clamp(27px, 2.3vw, 36px); letter-spacing: -1px; font-weight: 650
 .zoom-controls button { border: 0; background: transparent; min-width: 31px; min-height: 32px; padding: 2px 8px; font-size: 17px; }
 .zoom-controls #fit { border: 1px solid var(--line); font-size: 11px; margin-left: 5px; min-width: 39px; }
 .layout-toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; padding: 12px 21px 4px; font-size: 11px; }
+.project-details { margin: 0 0 18px; padding: 12px 16px; border: 1px solid var(--line); border-radius: 8px; background: var(--white); font-size: 12px; }
+.project-details dl { display: flex; flex-wrap: wrap; gap: 12px 24px; margin: 0; }
+.project-details dl > div { min-width: 0; }
+.project-details dt { color: var(--muted); font-size: 10px; margin-bottom: 4px; }
+.project-details dd { margin: 0; overflow-wrap: anywhere; }
+.project-details .project-path { flex: 1 1 240px; }
+.project-details > p { margin: 10px 0 0; color: var(--muted); font-size: 11px; }
+.project-details details { margin-top: 10px; }
+.project-details summary { cursor: pointer; font-weight: 600; }
+.project-details pre { white-space: pre-wrap; overflow-wrap: anywhere; padding: 10px; background: var(--paper); }
+.project-details button { min-height: 36px; font-size: 11px; }
+.diagram-search-bar { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; padding: 12px 21px 4px; font-size: 11px; color: var(--muted); }
+.diagram-search-bar input { flex: 1 1 160px; min-width: 0; min-height: 40px; padding: 8px 10px; border: 1px solid var(--line); border-radius: 5px; background: var(--white); color: var(--ink); }
+.diagram-search-bar input::placeholder { color: var(--muted); opacity: 1; }
+.diagram-search-bar button { min-height: 40px; font-size: 11px; }
+#diagram-search-status:empty { display: none; }
 .layout-toolbar label { display: flex; align-items: center; gap: 8px; color: var(--muted); }
 .layout-toolbar select, .shape-picker select { color: var(--ink); background: var(--white); border: 1px solid var(--line); border-radius: 5px; padding: 7px 25px 7px 9px; font: inherit; min-height: 34px; }
 .layout-toolbar button { font-size: 11px; min-height: 34px; padding: 5px 12px; }
@@ -490,6 +506,7 @@ footer span { margin: 0 8px; color: #91a7c3; }
   #replay-note { grid-column: 2; margin-top: -9px; text-align: left; }
   .drawing-toolbar { padding: 15px 15px 0; }
   .layout-toolbar { padding-right: 15px; padding-left: 15px; }
+  .diagram-search-bar { padding-right: 15px; padding-left: 15px; }
   .drawing-heading { gap: 3px 10px; }
   .drawing-footer { padding-right: 15px; padding-left: 15px; }
   .diagram-note { padding-left: 15px; }
@@ -558,6 +575,7 @@ footer span { margin: 0 8px; color: #91a7c3; }
   .coverage-status { flex-direction: row; text-align: left; gap: 5px 14px; font-size: 10px; max-width: none; }
   .drawing-toolbar { padding: 10px 10px 0; gap: 7px; align-items: start; }
   .layout-toolbar { padding: 10px 12px 3px; gap: 9px; }
+  .diagram-search-bar { padding: 10px 12px 3px; gap: 8px; }
   .layout-toolbar select, .layout-toolbar button { min-height: 40px; }
   .auto-arrange { min-height: 30px; }
   .shape-key { padding-right: 12px; padding-left: 12px; }

package/scripts/control.mjs

@@ -39,7 +39,7 @@ async function handle(line) {
     const supported = ['2024-11-05', '2025-03-26', '2025-06-18'];
     return result({ protocolVersion: supported.includes(message.params?.protocolVersion) ? message.params.protocolVersion : '2025-06-18',
       capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: 'graphlin', version: '0.1.1' },
+      serverInfo: { name: 'graphlin', version: '0.1.2' },
       instructions: 'Controls only. Passive host hooks provide observations when separately activated. No drawing calls after each action.' });
   }
   if (message.method === 'ping') return result({});