llm-wiki-compiler 0.7.0 → 0.8.0

package/dist/viewer/assets/viewer-search.js

@@ -84,19 +84,29 @@ export function wireSearch({ fetchJson }) {
 async function runSearchAndRender(query, results, fetchJson, stillCurrent) {
   try {
     const data = await fetchJson(`/api/search?q=${encodeURIComponent(query)}`);
-    if (!stillCurrent()) return;
-    renderSearchResults(data.results ?? [], results);
+    handleSearchSuccess(data, results, stillCurrent);
   } catch (err) {
-    if (!stillCurrent()) return;
-    results.innerHTML = "";
-    const li = document.createElement("li");
-    li.className = "empty";
-    li.textContent = `Search failed: ${err.message}`;
-    results.appendChild(li);
-    results.hidden = false;
+    handleSearchFailure(err, results, stillCurrent);
   }
 }
 
+/** Render the response rows when the user hasn't moved past this query yet. */
+function handleSearchSuccess(data, results, stillCurrent) {
+  if (!stillCurrent()) return;
+  renderSearchResults(data.results ?? [], results);
+}
+
+/** Show an inline error in the results panel when the search fetch threw. */
+function handleSearchFailure(err, results, stillCurrent) {
+  if (!stillCurrent()) return;
+  results.innerHTML = "";
+  const li = document.createElement("li");
+  li.className = "empty";
+  li.textContent = `Search failed: ${err.message}`;
+  results.appendChild(li);
+  results.hidden = false;
+}
+
 /** Render rows into the results <ul>; show an "empty" message for zero hits. */
 function renderSearchResults(rows, results) {
   results.innerHTML = "";
@@ -168,18 +178,40 @@ function onSearchInputKeydown(event, results) {
 /** ArrowUp/Down within results cycle focus; Escape returns focus to input. */
 function onSearchResultsKeydown(event, input) {
   if (event.key === "Escape") {
-    event.preventDefault();
-    input.focus();
+    handleSearchEscape(event, input);
     return;
   }
-  if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
-  const target = event.target instanceof HTMLAnchorElement ? event.target : null;
+  const direction = arrowDirection(event.key);
+  if (!direction) return;
+  const target = anchorTarget(event.target);
   if (!target) return;
   event.preventDefault();
+  focusNeighborAnchor(target, direction);
+}
+
+/** Bounce focus back to the search input on Escape. */
+function handleSearchEscape(event, input) {
+  event.preventDefault();
+  input.focus();
+}
+
+/** Map ArrowDown/ArrowUp to +1/-1; return 0 for any other key. */
+function arrowDirection(key) {
+  if (key === "ArrowDown") return 1;
+  if (key === "ArrowUp") return -1;
+  return 0;
+}
+
+/** Narrow an EventTarget to an HTMLAnchorElement, or null when it isn't one. */
+function anchorTarget(target) {
+  return target instanceof HTMLAnchorElement ? target : null;
+}
+
+/** Wrap focus across the result anchors by `direction` (+1 or -1). */
+function focusNeighborAnchor(target, direction) {
   const all = Array.from(target.closest("ul").querySelectorAll("a[data-search-result]"));
+  if (all.length === 0) return;
   const idx = all.indexOf(target);
-  const next = event.key === "ArrowDown"
-    ? all[(idx + 1) % all.length]
-    : all[(idx - 1 + all.length) % all.length];
+  const next = all[(idx + direction + all.length) % all.length];
   if (next) next.focus();
 }

package/dist/viewer/assets/viewer-sidebar.js

@@ -1,9 +1,9 @@
 /**
  * llmwiki viewer — sidebar renderer.
  *
- * Renders concept pages grouped by frontmatter `kind` (defaulting to
- * "concept" when absent — spec line 347), then a "Saved Queries"
- * group, then the standing "Health" entry. Groups use native
+ * Renders the standing project links first, then concept pages grouped
+ * by frontmatter `kind` (defaulting to "concept" when absent — spec
+ * line 347), then a "Saved Queries" group. Groups use native
  * `<details><summary>` so keyboard users get Enter/Space collapse for
  * free without bespoke ARIA wiring.
  *
@@ -15,29 +15,57 @@
 
 const SIDEBAR_SELECTOR = "[data-sidebar]";
 const DEFAULT_KIND = "concept";
+const EMPTY_PLACEHOLDER_TEXT = "No pages yet — run `llmwiki compile`.";
+
+/**
+ * Static (non-page) hash routes that have a dedicated sidebar link.
+ * `markActive` highlights the entry via `a[data-route="<route>"]`
+ * without needing to parse the route descriptor.
+ */
+const STATIC_ROUTE_LINK_SELECTORS = new Map([
+  ["#/graph", 'a[data-route="graph"]'],
+  ["#/health", 'a[data-route="health"]'],
+]);
 
 /** Render the sidebar groups + standing Health entry, then mark active. */
 export function renderSidebar(pages) {
   const sidebar = document.querySelector(SIDEBAR_SELECTOR);
   if (!sidebar) return;
   sidebar.innerHTML = "";
-  const concepts = pages.filter((p) => p.pageDirectory === "concepts");
-  const queries = pages.filter((p) => p.pageDirectory === "queries");
-  const conceptGroups = groupConceptsByKind(concepts);
-  for (const [kind, groupPages] of conceptGroups) {
+  sidebar.appendChild(buildProjectSection());
+  const concepts = filterByDirectory(pages, "concepts");
+  const queries = filterByDirectory(pages, "queries");
+  appendConceptGroups(sidebar, concepts);
+  appendQueryGroup(sidebar, queries);
+  appendEmptyPlaceholderIfNeeded(sidebar, concepts, queries);
+  markActive();
+}
+
+/** Filter pages to those whose `pageDirectory` matches the given bucket. */
+function filterByDirectory(pages, directory) {
+  return pages.filter((p) => p.pageDirectory === directory);
+}
+
+/** Append one collapsible `<details>` group per concept kind. */
+function appendConceptGroups(sidebar, concepts) {
+  for (const [kind, groupPages] of groupConceptsByKind(concepts)) {
     sidebar.appendChild(buildCollapsibleGroup(formatKindLabel(kind), groupPages, "kind", kind));
   }
-  if (queries.length > 0) {
-    sidebar.appendChild(buildCollapsibleGroup("Saved Queries", queries, "kind", "query"));
-  }
-  if (concepts.length === 0 && queries.length === 0) {
-    const empty = document.createElement("p");
-    empty.className = "placeholder";
-    empty.textContent = "No pages yet — run `llmwiki compile`.";
-    sidebar.appendChild(empty);
-  }
-  sidebar.appendChild(buildHealthEntry());
-  markActive();
+}
+
+/** Append the Saved Queries group when at least one query page exists. */
+function appendQueryGroup(sidebar, queries) {
+  if (queries.length === 0) return;
+  sidebar.appendChild(buildCollapsibleGroup("Saved Queries", queries, "kind", "query"));
+}
+
+/** Render the "No pages yet" placeholder when both buckets are empty. */
+function appendEmptyPlaceholderIfNeeded(sidebar, concepts, queries) {
+  if (concepts.length > 0 || queries.length > 0) return;
+  const empty = document.createElement("p");
+  empty.className = "placeholder";
+  empty.textContent = EMPTY_PLACEHOLDER_TEXT;
+  sidebar.appendChild(empty);
 }
 
 /**
@@ -49,9 +77,31 @@ export function renderSidebar(pages) {
  */
 export function markActive() {
   const hash = location.hash;
-  const expectedId = parseExpectedPageId(hash);
   const links = document.querySelectorAll(`${SIDEBAR_SELECTOR} a`);
+  clearCurrentAttribute(links);
+  if (markStaticRoute(hash)) return;
+  markPageRoute(links, parseExpectedPageId(hash));
+}
+
+/** Remove `aria-current` from every sidebar link in `links`. */
+function clearCurrentAttribute(links) {
   for (const link of links) link.removeAttribute("aria-current");
+}
+
+/**
+ * Apply `aria-current="page"` to the static-route link for `hash`,
+ * if the hash names a known static route. Returns true when handled
+ * so the page-route fallback can be skipped.
+ */
+function markStaticRoute(hash) {
+  const selector = STATIC_ROUTE_LINK_SELECTORS.get(hash);
+  if (!selector) return false;
+  document.querySelector(selector)?.setAttribute("aria-current", "page");
+  return true;
+}
+
+/** Apply `aria-current="page"` to the link whose pageId matches `expectedId`. */
+function markPageRoute(links, expectedId) {
   if (!expectedId) return;
   for (const link of links) {
     if (link.dataset.pageId === expectedId) {
@@ -70,18 +120,32 @@ export function markActive() {
 function groupConceptsByKind(concepts) {
   const byKind = new Map();
   for (const page of concepts) {
-    const kind = (typeof page.kind === "string" && page.kind.length > 0) ? page.kind : DEFAULT_KIND;
-    if (!byKind.has(kind)) byKind.set(kind, []);
-    byKind.get(kind).push(page);
+    addPageToKindBucket(byKind, page);
   }
-  const kinds = Array.from(byKind.keys()).sort((a, b) => {
-    if (a === DEFAULT_KIND) return -1;
-    if (b === DEFAULT_KIND) return 1;
-    return a.localeCompare(b);
-  });
+  const kinds = Array.from(byKind.keys()).sort(compareKinds);
   return kinds.map((kind) => /** @type {[string, Array]} */ ([kind, byKind.get(kind)]));
 }
 
+/** Push `page` onto the bucket for its resolved kind, creating it if needed. */
+function addPageToKindBucket(byKind, page) {
+  const kind = resolveKind(page);
+  if (!byKind.has(kind)) byKind.set(kind, []);
+  byKind.get(kind).push(page);
+}
+
+/** Read `page.kind` defensively, falling back to DEFAULT_KIND when absent. */
+function resolveKind(page) {
+  if (typeof page.kind === "string" && page.kind.length > 0) return page.kind;
+  return DEFAULT_KIND;
+}
+
+/** Sort comparator that floats DEFAULT_KIND first, then locale-orders the rest. */
+function compareKinds(a, b) {
+  if (a === DEFAULT_KIND) return -1;
+  if (b === DEFAULT_KIND) return 1;
+  return a.localeCompare(b);
+}
+
 /** Title-case a kind for the group heading. */
 function formatKindLabel(kind) {
   if (kind === DEFAULT_KIND) return "Concepts";
@@ -113,23 +177,29 @@ function buildPageListItem(page) {
   return li;
 }
 
-/** Build the standing "Health" sidebar entry that routes to #/health. */
-function buildHealthEntry() {
+/** Build the standing "Project" sidebar section with Health and Graph links. */
+function buildProjectSection() {
   const wrap = document.createElement("section");
   wrap.className = "sidebar-health";
   const heading = document.createElement("h2");
   heading.textContent = "Project";
   wrap.appendChild(heading);
   const list = document.createElement("ul");
+  list.appendChild(buildProjectRouteItem("#/health", "health", "Health"));
+  list.appendChild(buildProjectRouteItem("#/graph", "graph", "Graph"));
+  wrap.appendChild(list);
+  return wrap;
+}
+
+/** Build one `<li><a>` entry for the standing Project section. */
+function buildProjectRouteItem(href, route, label) {
   const item = document.createElement("li");
   const link = document.createElement("a");
-  link.href = "#/health";
-  link.dataset.healthLink = "true";
-  link.textContent = "Health";
+  link.href = href;
+  link.dataset.route = route;
+  link.textContent = label;
   item.appendChild(link);
-  list.appendChild(item);
-  wrap.appendChild(list);
-  return wrap;
+  return item;
 }
 
 /**

package/dist/viewer/assets/viewer.css

@@ -104,7 +104,8 @@ a:hover, a:focus-visible { text-decoration: underline; }
   fill: currentColor;
 }
 .github-stars {
-  font-size: 1.05em;
+  font-size: 0.82rem;
+  font-weight: 500;
   font-variant-numeric: tabular-nums;
 }
 
@@ -312,3 +313,69 @@ a:hover, a:focus-visible { text-decoration: underline; }
     padding: 1rem;
   }
 }
+
+/* Graph pane */
+.graph-pane {
+  width: 100%;
+  height: calc(100vh - 3rem);
+  min-height: 32rem;
+  padding: 0;
+  overflow: hidden;
+  position: relative;
+}
+.graph-pane svg { display: block; width: 100%; height: 100%; }
+.graph-tooltip {
+  position: absolute;
+  background: #1f2937;
+  border: 1px solid #374151;
+  border-radius: 6px;
+  padding: 8px 12px;
+  font-size: 12px;
+  pointer-events: none;
+  display: none;
+  z-index: 10;
+  max-width: 220px;
+}
+.graph-tooltip .tip-title { font-weight: 600; color: #e2e8f0; }
+.graph-tooltip .tip-meta  { font-size: 11px; color: #7a8fa6; margin-top: 2px; }
+.graph-tooltip .tip-hint  { font-size: 10px; color: #4a5568; margin-top: 4px; }
+.graph-legend {
+  position: absolute;
+  bottom: 16px;
+  left: 16px;
+  background: #111827;
+  border: 1px solid #1f2937;
+  border-radius: 6px;
+  padding: 8px 12px;
+  font-size: 11px;
+  pointer-events: none;
+  z-index: 5;
+}
+.graph-legend-heading {
+  color: #4a5568;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 10px;
+  margin-bottom: 6px;
+}
+.graph-legend-heading + .graph-legend-heading { margin-top: 8px; }
+.graph-legend-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  color: #7a8fa6;
+  margin-bottom: 3px;
+}
+.graph-legend-item:last-child { margin-bottom: 0; }
+.graph-legend-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.node-label {
+  fill: #e2e8f0;
+}
+@media (prefers-color-scheme: light) {
+  .node-label { fill: #1a202c; }
+}