notex-companion 0.1.0 → 0.2.0

package/dist/cli.d.ts

@@ -3,8 +3,8 @@ export declare class CliUsageError extends Error {
 }
 export type ServeArgs = {
     port: number | undefined;
-    origins: string[];
+    origins: Array<string>;
     rotateToken: boolean;
 };
-export declare function parseServeArgs(args: string[]): ServeArgs;
-export declare function main(argv?: string[]): void;
+export declare function parseServeArgs(args: Array<string>): ServeArgs;
+export declare function main(argv?: Array<string>): void;

package/dist/cli.js

@@ -142,7 +142,7 @@ function loadGraph(checkoutPath) {
   const scoreIndex = doc.nodes.map((n) => ({
     id: n.id,
     labelTokens: new Set([...shatter(n.label), ...shatter(n.norm_label ?? "")]),
-    pathTokens: new Set(shatter(n.source_file ?? "")),
+    pathTokens: new Set(shatter(n.source_file)),
     labelLower: String(n.label).toLowerCase()
   }));
   const project = (n) => ({
@@ -286,7 +286,7 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
     for (const id of frontier) {
       for (const { other, edge } of adjacency.get(id) ?? []) {
         if (!kept.has(other))
-          candidates.push({ other, weight: edge.weight ?? 1 });
+          candidates.push({ other, weight: edge.weight });
       }
     }
     candidates.sort((a, b) => b.weight - a.weight);
@@ -324,8 +324,8 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
 }
 
 // src/ops.ts
-var API_VERSION = "0.1.0";
-var CAPABILITIES = ["search", "query", "path", "node"];
+var API_VERSION = "0.2.0";
+var CAPABILITIES = ["search", "query", "path", "node", "browse"];
 var MAX_NODES_CEILING = 1000;
 var MAX_DEPTH_CEILING = 3;
 var DEFAULT_DEPTH = 1;
@@ -333,6 +333,8 @@ var DEFAULT_MAX_NODES = 60;
 var DEFAULT_SEED_COUNT = 5;
 var DEFAULT_SEARCH_LIMIT = 20;
 var MAX_SEARCH_LIMIT = 100;
+var DEFAULT_BROWSE_GROUP_LIMIT = 8;
+var MAX_BROWSE_GROUP_LIMIT = 50;
 function status(index) {
   return {
     graph: index.stamp,
@@ -349,6 +351,21 @@ function search(index, req) {
     results: scored.map((s) => ({ ...index.project(index.nodesById.get(s.id)), score: s.score }))
   };
 }
+function browse(index, req) {
+  const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_BROWSE_GROUP_LIMIT, MAX_BROWSE_GROUP_LIMIT));
+  const byType = new Map;
+  for (const raw of index.nodesById.values()) {
+    const projected = index.project(raw);
+    if (!byType.has(projected.fileType))
+      byType.set(projected.fileType, []);
+    byType.get(projected.fileType).push(projected);
+  }
+  const groups = [...byType.entries()].map(([fileType, nodes]) => {
+    const sorted = [...nodes].sort((a, b) => a.label.localeCompare(b.label));
+    return { fileType, total: sorted.length, nodes: sorted.slice(0, limit) };
+  }).sort((a, b) => b.total - a.total || a.fileType.localeCompare(b.fileType));
+  return { graph: index.stamp, groups };
+}
 function query(index, req) {
   const depth = Math.min(req.depth ?? DEFAULT_DEPTH, MAX_DEPTH_CEILING);
   const maxNodes = Math.min(req.maxNodes ?? DEFAULT_MAX_NODES, MAX_NODES_CEILING);
@@ -517,6 +534,8 @@ async function dispatch(req, url, opts) {
   if (method === "GET" && pathname.startsWith("/v1/node/")) {
     return node(index, { id: decodeNodeId(pathname.slice("/v1/node/".length)) });
   }
+  if (method === "GET" && pathname === "/v1/browse")
+    return browse(index, parseBrowseRequest(url.searchParams));
   throw new OpError("not_found", `No such route: ${method} ${pathname}`);
 }
 function decodeNodeId(raw) {
@@ -610,6 +629,14 @@ function parseQueryRequest(body) {
 function parsePathRequest(body) {
   return { from: requireString(body, "from"), to: requireString(body, "to"), maxDepth: optionalCount(body, "maxDepth") };
 }
+function parseBrowseRequest(searchParams) {
+  const raw = searchParams.get("limit");
+  if (raw === null)
+    return {};
+  if (!/^\d+$/.test(raw))
+    throw new OpError("invalid_request", `"limit" must be a non-negative integer`);
+  return { limit: Number(raw) };
+}
 function errorBody(err) {
   const detail = err.detail instanceof Error ? { name: err.detail.name, message: err.detail.message } : err.detail;
   return { error: { code: err.code, message: err.message, ...detail !== undefined ? { detail } : {} } };

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./ops.js";

package/dist/client.js

@@ -0,0 +1,371 @@
+// src/types.ts
+var ERROR_CODES = {
+  unauthorized: "unauthorized",
+  notFound: "not_found",
+  graphUnreadable: "graph_unreadable",
+  invalidRequest: "invalid_request",
+  graphLoading: "graph_loading"
+};
+
+class OpError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "OpError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+// src/context.ts
+function buildContext(question, stamp, nodes, edges, opts = {}) {
+  const lines = [];
+  const builtDate = stamp.builtAt.slice(0, 10);
+  lines.push(`# ${question}`, "");
+  lines.push(`built ${builtDate} · ${nodes.length} nodes`, "");
+  const groups = new Map;
+  for (const n of nodes) {
+    const key = n.community?.name ? n.community.name : "Ungrouped";
+    if (!groups.has(key))
+      groups.set(key, []);
+    groups.get(key).push(n);
+  }
+  const groupNames = [...groups.keys()].sort((a, b) => a === "Ungrouped" ? 1 : b === "Ungrouped" ? -1 : a.localeCompare(b));
+  for (const name of groupNames) {
+    lines.push(`## ${name}`);
+    const members = [...groups.get(name)].sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
+    for (const n of members)
+      lines.push(`- ${n.label} — ${n.sourceFile}:${n.sourceLocation}`);
+    lines.push("");
+  }
+  if (edges.length > 0) {
+    const labelById = new Map(nodes.map((n) => [n.id, n.label]));
+    lines.push("## Relations");
+    for (const e of edges) {
+      const tag = e.confidence === "EXTRACTED" ? "" : ` [${e.confidence}]`;
+      lines.push(`- ${labelById.get(e.source) ?? e.source} —${e.relation}→ ${labelById.get(e.target) ?? e.target}${tag}`);
+    }
+    lines.push("");
+  }
+  if (opts.truncated) {
+    lines.push(`> Retrieval was truncated (${opts.truncated.reason}); ${opts.truncated.omittedCount} related nodes were omitted.`, "");
+  }
+  if (opts.degraded) {
+    lines.push("> Matched literally — no vocabulary expansion was applied to the question.", "");
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  return lines.join(`
+`);
+}
+
+// src/footer.ts
+function isoDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+function buildFooter(stamp, sources, opts = {}) {
+  const draftDate = opts.draftDate ?? isoDate(new Date);
+  const builtDate = stamp.builtAt.slice(0, 10);
+  const graphLine = stamp.headSha ? `Graph built ${builtDate} (${stamp.graphHash}) at commit ${stamp.headSha.slice(0, 7)}.` : `Graph built ${builtDate} (${stamp.graphHash}).`;
+  const noteClauses = [];
+  if (opts.truncated) {
+    noteClauses.push(`Retrieval was truncated (${opts.truncated.reason}); some related code may be missing.`);
+  }
+  if (opts.degraded) {
+    noteClauses.push("Retrieval matched literally; vocabulary was not expanded.");
+  }
+  const sortedSources = [...new Set(sources.map((s) => `${s.file}:${s.location}`))].sort();
+  const lines = [
+    "---",
+    `Drafted from the code graph on ${draftDate}.`,
+    graphLine,
+    ...noteClauses.length > 0 ? [noteClauses.join(" ")] : [],
+    "Sources:",
+    ...sortedSources.map((s) => `- ${s}`)
+  ];
+  return `
+` + lines.join(`
+`);
+}
+
+// src/scoring.ts
+var STOPWORDS = new Set(("a an the and or but if of to in on for with from by at as is are was were " + "do does did how what where when which who why can could should would we " + "our it its this that these those there here about into over under not no " + "you your i me my be been being have has had will shall may might must " + "get got make made use used using does happen happens work works").split(" "));
+function shatter(text) {
+  return String(text).replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).map((t) => t.toLowerCase()).filter(Boolean);
+}
+function terms(question) {
+  return [...new Set(shatter(question).filter((t) => t.length >= 3 && !STOPWORDS.has(t)))];
+}
+function scoreNodes(index, queryTerms) {
+  const scored = [];
+  for (const entry of index) {
+    let score = 0;
+    let exact = false;
+    for (const term of queryTerms) {
+      let best = 0;
+      if (entry.labelLower === term) {
+        best = 6;
+        exact = true;
+      } else if (entry.labelTokens.has(term)) {
+        best = 3;
+        exact = true;
+      } else {
+        for (const tok of entry.labelTokens) {
+          if (tok.length >= 4 && (tok.startsWith(term) || term.startsWith(tok))) {
+            best = Math.max(best, 1.5);
+          } else if (term.length >= 4 && tok.includes(term)) {
+            best = Math.max(best, 1);
+          }
+        }
+      }
+      if (best === 0) {
+        if (entry.pathTokens.has(term)) {
+          best = 1.2;
+        } else {
+          for (const tok of entry.pathTokens) {
+            if (tok.length >= 4 && term.length >= 4 && tok.startsWith(term))
+              best = 0.6;
+          }
+        }
+      }
+      score += best;
+    }
+    if (score > 0)
+      scored.push({ id: entry.id, score: Math.round(score * 100) / 100, exact });
+  }
+  return scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+// src/traversal.ts
+function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
+  const kept = new Set;
+  const overflow = new Set;
+  let frontier = [];
+  for (const s of seedIds) {
+    if (kept.size < maxNodes) {
+      kept.add(s);
+      frontier.push(s);
+    } else {
+      overflow.add(s);
+    }
+  }
+  let d = 0;
+  for (;d < depth; d++) {
+    const candidates = [];
+    for (const id of frontier) {
+      for (const { other, edge } of adjacency.get(id) ?? []) {
+        if (!kept.has(other))
+          candidates.push({ other, weight: edge.weight });
+      }
+    }
+    candidates.sort((a, b) => b.weight - a.weight);
+    const next = [];
+    for (const c of candidates) {
+      if (kept.has(c.other))
+        continue;
+      if (kept.size >= maxNodes) {
+        overflow.add(c.other);
+        continue;
+      }
+      kept.add(c.other);
+      next.push(c.other);
+    }
+    frontier = next;
+    if (frontier.length === 0)
+      break;
+  }
+  let truncated = null;
+  if (overflow.size > 0) {
+    truncated = { reason: "maxNodes", omittedCount: overflow.size };
+  } else if (d === depth && frontier.length > 0) {
+    const beyond = new Set;
+    for (const id of frontier) {
+      for (const { other } of adjacency.get(id) ?? []) {
+        if (!kept.has(other))
+          beyond.add(other);
+      }
+    }
+    if (beyond.size > 0)
+      truncated = { reason: "depth", omittedCount: beyond.size };
+  }
+  const edges = allEdges.filter((e) => kept.has(e.source) && kept.has(e.target));
+  return { nodeIds: [...kept], edges, truncated };
+}
+
+// src/ops.ts
+var API_VERSION = "0.2.0";
+var CAPABILITIES = ["search", "query", "path", "node", "browse"];
+var MAX_NODES_CEILING = 1000;
+var MAX_DEPTH_CEILING = 3;
+var DEFAULT_DEPTH = 1;
+var DEFAULT_MAX_NODES = 60;
+var DEFAULT_SEED_COUNT = 5;
+var DEFAULT_SEARCH_LIMIT = 20;
+var MAX_SEARCH_LIMIT = 100;
+var DEFAULT_BROWSE_GROUP_LIMIT = 8;
+var MAX_BROWSE_GROUP_LIMIT = 50;
+function status(index) {
+  return {
+    graph: index.stamp,
+    apiVersion: API_VERSION,
+    capabilities: [...CAPABILITIES],
+    limits: { maxNodes: MAX_NODES_CEILING, maxDepth: MAX_DEPTH_CEILING }
+  };
+}
+function search(index, req) {
+  const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT));
+  const scored = scoreNodes(index.scoreIndex, terms(req.q)).slice(0, limit);
+  return {
+    graph: index.stamp,
+    results: scored.map((s) => ({ ...index.project(index.nodesById.get(s.id)), score: s.score }))
+  };
+}
+function browse(index, req) {
+  const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_BROWSE_GROUP_LIMIT, MAX_BROWSE_GROUP_LIMIT));
+  const byType = new Map;
+  for (const raw of index.nodesById.values()) {
+    const projected = index.project(raw);
+    if (!byType.has(projected.fileType))
+      byType.set(projected.fileType, []);
+    byType.get(projected.fileType).push(projected);
+  }
+  const groups = [...byType.entries()].map(([fileType, nodes]) => {
+    const sorted = [...nodes].sort((a, b) => a.label.localeCompare(b.label));
+    return { fileType, total: sorted.length, nodes: sorted.slice(0, limit) };
+  }).sort((a, b) => b.total - a.total || a.fileType.localeCompare(b.fileType));
+  return { graph: index.stamp, groups };
+}
+function query(index, req) {
+  const depth = Math.min(req.depth ?? DEFAULT_DEPTH, MAX_DEPTH_CEILING);
+  const maxNodes = Math.min(req.maxNodes ?? DEFAULT_MAX_NODES, MAX_NODES_CEILING);
+  const seedCount = Math.max(0, req.seeds ?? DEFAULT_SEED_COUNT);
+  const include = req.include ?? ["subgraph"];
+  const queryTerms = req.terms?.length ? req.terms.map((t) => t.toLowerCase()) : terms(req.question);
+  const degraded = req.terms?.length ? undefined : { expansion: "none" };
+  const scored = scoreNodes(index.scoreIndex, queryTerms);
+  const scoredById = new Map(scored.map((s) => [s.id, s]));
+  const seedIds = scored.slice(0, seedCount).map((s) => s.id);
+  const topScore = scored[0]?.score ?? 0;
+  const clearsFloor = seedIds.some((id) => scoredById.get(id)?.exact);
+  const lowConfidence = clearsFloor ? undefined : { topScore };
+  if (seedIds.length === 0) {
+    const empty = {
+      graph: index.stamp,
+      ...degraded ? { degraded } : {},
+      ...lowConfidence ? { lowConfidence } : {},
+      subgraph: { nodes: [], edges: [], seeds: [] }
+    };
+    if (include.includes("context")) {
+      empty.context = { markdown: buildContext(req.question, index.stamp, [], [], { degraded }), sources: [] };
+    }
+    if (include.includes("footer")) {
+      empty.footer = buildFooter(index.stamp, [], { degraded });
+    }
+    return empty;
+  }
+  const { nodeIds, edges: rawEdges, truncated } = traverse(index.adjacency, index.edges, seedIds, depth, maxNodes);
+  const nodes = nodeIds.map((id) => index.project(index.nodesById.get(id)));
+  const edges = rawEdges.map((e) => index.projectEdge(e));
+  const response = {
+    graph: index.stamp,
+    ...degraded ? { degraded } : {},
+    ...truncated ? { truncated } : {},
+    ...lowConfidence ? { lowConfidence } : {},
+    subgraph: { nodes, edges, seeds: seedIds }
+  };
+  if (include.includes("context")) {
+    response.context = {
+      markdown: buildContext(req.question, index.stamp, nodes, edges, { truncated: truncated ?? undefined, degraded }),
+      sources: sourcesFrom(nodes)
+    };
+  }
+  if (include.includes("footer")) {
+    response.footer = buildFooter(index.stamp, sourcesFrom(nodes), { truncated: truncated ?? undefined, degraded });
+  }
+  return response;
+}
+function sourcesFrom(nodes) {
+  const keys = [...new Set(nodes.map((n) => `${n.sourceFile}:${n.sourceLocation}`))].sort();
+  return keys.map((k) => {
+    const i = k.lastIndexOf(":");
+    return { file: k.slice(0, i), location: k.slice(i + 1) };
+  });
+}
+function path(index, req) {
+  const { from, to, maxDepth } = req;
+  if (!index.nodesById.has(from))
+    throw new OpError("not_found", `Unknown node id: ${from}`);
+  if (!index.nodesById.has(to))
+    throw new OpError("not_found", `Unknown node id: ${to}`);
+  if (from === to) {
+    return {
+      graph: index.stamp,
+      found: true,
+      nodes: [index.project(index.nodesById.get(from))],
+      edges: []
+    };
+  }
+  const cameFrom = new Map;
+  const depthOf = new Map([[from, 0]]);
+  const queue = [from];
+  let qi = 0;
+  let found = false;
+  outer:
+    while (qi < queue.length) {
+      const id = queue[qi++];
+      const d = depthOf.get(id);
+      if (maxDepth !== undefined && d >= maxDepth)
+        continue;
+      for (const { other, edge } of index.adjacency.get(id) ?? []) {
+        if (depthOf.has(other))
+          continue;
+        depthOf.set(other, d + 1);
+        cameFrom.set(other, { prev: id, edge });
+        if (other === to) {
+          found = true;
+          break outer;
+        }
+        queue.push(other);
+      }
+    }
+  if (!found)
+    return { graph: index.stamp, found: false, nodes: [], edges: [] };
+  const nodeIds = [to];
+  const rawEdges = [];
+  let cur = to;
+  while (cur !== from) {
+    const step = cameFrom.get(cur);
+    rawEdges.push(step.edge);
+    cur = step.prev;
+    nodeIds.push(cur);
+  }
+  nodeIds.reverse();
+  rawEdges.reverse();
+  return {
+    graph: index.stamp,
+    found: true,
+    nodes: nodeIds.map((id) => index.project(index.nodesById.get(id))),
+    edges: rawEdges.map((e) => index.projectEdge(e))
+  };
+}
+function node(index, req) {
+  const raw = index.nodesById.get(req.id);
+  if (!raw)
+    throw new OpError("not_found", `Unknown node id: ${req.id}`);
+  const neighbours = (index.adjacency.get(req.id) ?? []).map(({ other, edge }) => ({
+    node: index.project(index.nodesById.get(other)),
+    edge: index.projectEdge(edge)
+  }));
+  return { graph: index.stamp, node: index.project(raw), neighbours };
+}
+export {
+  status,
+  search,
+  query,
+  path,
+  node,
+  browse,
+  OpError,
+  ERROR_CODES,
+  API_VERSION
+};

package/dist/context.d.ts

@@ -3,4 +3,4 @@ export type BuildContextOptions = {
     truncated?: Truncated;
     degraded?: Degraded;
 };
-export declare function buildContext(question: string, stamp: GraphStamp, nodes: GraphNode[], edges: GraphEdge[], opts?: BuildContextOptions): string;
+export declare function buildContext(question: string, stamp: GraphStamp, nodes: Array<GraphNode>, edges: Array<GraphEdge>, opts?: BuildContextOptions): string;

package/dist/cors.d.ts

@@ -2,8 +2,8 @@
  * `--origin` is repeatable, defaulting to the production Notex origin (companion-api.md §5);
  * `http://localhost:3000` is added on top of that only outside production.
  */
-export declare function resolveOrigins(configured: string[], nodeEnv: string | undefined, productionOrigin?: string): string[];
+export declare function resolveOrigins(configured: Array<string>, nodeEnv: string | undefined, productionOrigin?: string): Array<string>;
 /** Headers for a real (non-preflight) response. `{}` when the origin isn't an exact allowlist match. */
-export declare function corsHeaders(origins: string[], requestOrigin: string | undefined): Record<string, string>;
+export declare function corsHeaders(origins: Array<string>, requestOrigin: string | undefined): Record<string, string>;
 /** Full preflight header set (companion-api.md §5). `{}` when the origin isn't an exact allowlist match. */
-export declare function preflightHeaders(origins: string[], requestOrigin: string | undefined): Record<string, string>;
+export declare function preflightHeaders(origins: Array<string>, requestOrigin: string | undefined): Record<string, string>;

package/dist/footer.d.ts

@@ -9,4 +9,4 @@ export type BuildFooterOptions = {
     truncated?: Truncated;
     degraded?: Degraded;
 };
-export declare function buildFooter(stamp: GraphStamp, sources: FooterSource[], opts?: BuildFooterOptions): string;
+export declare function buildFooter(stamp: GraphStamp, sources: Array<FooterSource>, opts?: BuildFooterOptions): string;

package/dist/graph.d.ts

@@ -1,5 +1,5 @@
-import { type ScoreIndexEntry } from "./scoring.js";
-import { type GraphEdge, type GraphNode, type GraphStamp } from "./types.js";
+import type { ScoreIndexEntry } from "./scoring.js";
+import type { GraphEdge, GraphNode, GraphStamp } from "./types.js";
 type RawNode = {
     id: string;
     label: string;
@@ -26,10 +26,10 @@ export type AdjacencyEntry = {
 export type GraphIndex = {
     stamp: GraphStamp;
     nodesById: Map<string, RawNode>;
-    edges: RawEdge[];
+    edges: Array<RawEdge>;
     /** Undirected — the graph is `"directed": false` (companion-api.md §2.2). */
-    adjacency: Map<string, AdjacencyEntry[]>;
-    scoreIndex: ScoreIndexEntry[];
+    adjacency: Map<string, Array<AdjacencyEntry>>;
+    scoreIndex: Array<ScoreIndexEntry>;
     project: (n: RawNode) => GraphNode;
     projectEdge: (e: RawEdge) => GraphEdge;
 };

package/dist/http.d.ts

@@ -1,5 +1,5 @@
-import type { GraphIndex } from "./graph.js";
 import { OpError } from "./types.js";
+import type { GraphIndex } from "./graph.js";
 /**
  * The graph is loaded once into memory (companion-api.md §3); `loading` covers the window
  * before that finishes, `error` covers a permanently unreadable graph.json (never a crash).
@@ -15,7 +15,7 @@ export type GraphState = {
 };
 export type HandlerOptions = {
     token: string;
-    origins: string[];
+    origins: Array<string>;
     getGraphState: () => GraphState;
 };
 export declare function createHandler(opts: HandlerOptions): (req: Request) => Promise<Response>;

package/dist/index.js

@@ -155,7 +155,7 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
     for (const id of frontier) {
       for (const { other, edge } of adjacency.get(id) ?? []) {
         if (!kept.has(other))
-          candidates.push({ other, weight: edge.weight ?? 1 });
+          candidates.push({ other, weight: edge.weight });
       }
     }
     candidates.sort((a, b) => b.weight - a.weight);
@@ -193,8 +193,8 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
 }
 
 // src/ops.ts
-var API_VERSION = "0.1.0";
-var CAPABILITIES = ["search", "query", "path", "node"];
+var API_VERSION = "0.2.0";
+var CAPABILITIES = ["search", "query", "path", "node", "browse"];
 var MAX_NODES_CEILING = 1000;
 var MAX_DEPTH_CEILING = 3;
 var DEFAULT_DEPTH = 1;
@@ -202,6 +202,8 @@ var DEFAULT_MAX_NODES = 60;
 var DEFAULT_SEED_COUNT = 5;
 var DEFAULT_SEARCH_LIMIT = 20;
 var MAX_SEARCH_LIMIT = 100;
+var DEFAULT_BROWSE_GROUP_LIMIT = 8;
+var MAX_BROWSE_GROUP_LIMIT = 50;
 function status(index) {
   return {
     graph: index.stamp,
@@ -218,6 +220,21 @@ function search(index, req) {
     results: scored.map((s) => ({ ...index.project(index.nodesById.get(s.id)), score: s.score }))
   };
 }
+function browse(index, req) {
+  const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_BROWSE_GROUP_LIMIT, MAX_BROWSE_GROUP_LIMIT));
+  const byType = new Map;
+  for (const raw of index.nodesById.values()) {
+    const projected = index.project(raw);
+    if (!byType.has(projected.fileType))
+      byType.set(projected.fileType, []);
+    byType.get(projected.fileType).push(projected);
+  }
+  const groups = [...byType.entries()].map(([fileType, nodes]) => {
+    const sorted = [...nodes].sort((a, b) => a.label.localeCompare(b.label));
+    return { fileType, total: sorted.length, nodes: sorted.slice(0, limit) };
+  }).sort((a, b) => b.total - a.total || a.fileType.localeCompare(b.fileType));
+  return { graph: index.stamp, groups };
+}
 function query(index, req) {
   const depth = Math.min(req.depth ?? DEFAULT_DEPTH, MAX_DEPTH_CEILING);
   const maxNodes = Math.min(req.maxNodes ?? DEFAULT_MAX_NODES, MAX_NODES_CEILING);
@@ -409,7 +426,7 @@ function loadGraph(checkoutPath) {
   const scoreIndex = doc.nodes.map((n) => ({
     id: n.id,
     labelTokens: new Set([...shatter(n.label), ...shatter(n.norm_label ?? "")]),
-    pathTokens: new Set(shatter(n.source_file ?? "")),
+    pathTokens: new Set(shatter(n.source_file)),
     labelLower: String(n.label).toLowerCase()
   }));
   const project = (n) => ({
@@ -506,6 +523,8 @@ async function dispatch(req, url, opts) {
   if (method === "GET" && pathname.startsWith("/v1/node/")) {
     return node(index, { id: decodeNodeId(pathname.slice("/v1/node/".length)) });
   }
+  if (method === "GET" && pathname === "/v1/browse")
+    return browse(index, parseBrowseRequest(url.searchParams));
   throw new OpError("not_found", `No such route: ${method} ${pathname}`);
 }
 function decodeNodeId(raw) {
@@ -599,6 +618,14 @@ function parseQueryRequest(body) {
 function parsePathRequest(body) {
   return { from: requireString(body, "from"), to: requireString(body, "to"), maxDepth: optionalCount(body, "maxDepth") };
 }
+function parseBrowseRequest(searchParams) {
+  const raw = searchParams.get("limit");
+  if (raw === null)
+    return {};
+  if (!/^\d+$/.test(raw))
+    throw new OpError("invalid_request", `"limit" must be a non-negative integer`);
+  return { limit: Number(raw) };
+}
 function errorBody(err) {
   const detail = err.detail instanceof Error ? { name: err.detail.name, message: err.detail.message } : err.detail;
   return { error: { code: err.code, message: err.message, ...detail !== undefined ? { detail } : {} } };
@@ -763,6 +790,7 @@ export {
   node,
   loadGraph,
   createHandler,
+  browse,
   OpError,
   ERROR_CODES,
   API_VERSION

package/dist/net.d.ts

@@ -2,7 +2,7 @@ export type FetchHandler = (req: Request) => Promise<Response>;
 export type MinimalServer = {
     readonly hostname: string;
     readonly port: number;
-    stop(closeActiveConnections?: boolean): void;
+    stop: (closeActiveConnections?: boolean) => void;
 };
 export type StartServerOptions = {
     hostname: string;

package/dist/ops.d.ts

@@ -1,10 +1,10 @@
+import type { GraphEdge, GraphNode, OpResponse } from "./types.js";
 import type { GraphIndex } from "./graph.js";
-import { type GraphEdge, type GraphNode, type OpResponse } from "./types.js";
 /** Also the version /v1/ping reports (companion-api.md §4.1) — the two must never drift apart. */
-export declare const API_VERSION = "0.1.0";
+export declare const API_VERSION = "0.2.0";
 export type StatusResult = {
     apiVersion: string;
-    capabilities: string[];
+    capabilities: Array<string>;
     limits: {
         maxNodes: number;
         maxDepth: number;
@@ -21,9 +21,28 @@ export type SearchResult = {
     }>;
 };
 export declare function search(index: GraphIndex, req: SearchRequest): OpResponse<SearchResult>;
+export type BrowseRequest = {
+    limit?: number;
+};
+export type BrowseGroup = {
+    fileType: string;
+    total: number;
+    nodes: Array<GraphNode>;
+};
+export type BrowseResult = {
+    groups: Array<BrowseGroup>;
+};
+/**
+ * Lets the UI show what's in the graph before the user types anything (TBR-82) — `search`
+ * and `query` both require query terms and return nothing for an empty string. Groups by
+ * `fileType`, never `community`: community ids/names reshuffle across rebuilds (TBR-48),
+ * so graph-gui.md §4.1 rules out a community browser as a navigation structure that would
+ * silently change under the user. `fileType` is stable graphify-derived data instead.
+ */
+export declare function browse(index: GraphIndex, req: BrowseRequest): OpResponse<BrowseResult>;
 export type QueryRequest = {
     question: string;
-    terms?: string[];
+    terms?: Array<string>;
     depth?: number;
     maxNodes?: number;
     seeds?: number;
@@ -31,9 +50,9 @@ export type QueryRequest = {
 };
 export type QueryResult = {
     subgraph: {
-        nodes: GraphNode[];
-        edges: GraphEdge[];
-        seeds: string[];
+        nodes: Array<GraphNode>;
+        edges: Array<GraphEdge>;
+        seeds: Array<string>;
     };
     context?: {
         markdown: string;
@@ -57,8 +76,8 @@ export type PathRequest = {
 };
 export type PathResult = {
     found: boolean;
-    nodes: GraphNode[];
-    edges: GraphEdge[];
+    nodes: Array<GraphNode>;
+    edges: Array<GraphEdge>;
 };
 /** Fully deterministic, undirected, no scoring (companion-api.md §4.5) — plain BFS. */
 export declare function path(index: GraphIndex, req: PathRequest): OpResponse<PathResult>;

package/dist/scoring.d.ts

@@ -1,6 +1,6 @@
 /** camelCase / snake_case / path segments → discrete lowercase tokens. */
-export declare function shatter(text: string): string[];
-export declare function terms(question: string): string[];
+export declare function shatter(text: string): Array<string>;
+export declare function terms(question: string): Array<string>;
 export type ScoreIndexEntry = {
     id: string;
     labelTokens: Set<string>;
@@ -14,4 +14,4 @@ export type ScoredNode = {
     exact: boolean;
 };
 /** label tokens weigh full; path tokens weigh less — a path match is weaker evidence. */
-export declare function scoreNodes(index: ScoreIndexEntry[], queryTerms: string[]): ScoredNode[];
+export declare function scoreNodes(index: Array<ScoreIndexEntry>, queryTerms: Array<string>): Array<ScoredNode>;

package/dist/serve.d.ts

@@ -1,5 +1,5 @@
-import { type GraphState } from "./http.js";
-import { type MinimalServer } from "./net.js";
+import type { MinimalServer } from "./net.js";
+import type { GraphState } from "./http.js";
 export type ServeOptions = {
     /** Absolute path of the checkout to serve — where graphify-out/graph.json and .notex/ live. */
     checkoutPath: string;
@@ -11,7 +11,7 @@ export type ServeOptions = {
      */
     port?: number;
     /** Additional allowed origins beyond the dev default (companion-api.md §5). */
-    origins?: string[];
+    origins?: Array<string>;
     rotateToken?: boolean;
     nodeEnv?: string;
     /** Fires once the graph finishes loading (or fails to) — the CLI uses this for startup output. */

package/dist/traversal.d.ts

@@ -4,13 +4,13 @@ export type TraversalEdge = {
     target: string;
     weight: number;
 };
-export type AdjacencyMap<E> = Map<string, Array<{
+export type AdjacencyMap<TEdge> = Map<string, Array<{
     other: string;
-    edge: E;
+    edge: TEdge;
 }>>;
-export type TraversalResult<E> = {
-    nodeIds: string[];
-    edges: E[];
+export type TraversalResult<TEdge> = {
+    nodeIds: Array<string>;
+    edges: Array<TEdge>;
     truncated: Truncated | null;
 };
-export declare function traverse<E extends TraversalEdge>(adjacency: AdjacencyMap<E>, allEdges: E[], seedIds: string[], depth: number, maxNodes: number): TraversalResult<E>;
+export declare function traverse<TEdge extends TraversalEdge>(adjacency: AdjacencyMap<TEdge>, allEdges: Array<TEdge>, seedIds: Array<string>, depth: number, maxNodes: number): TraversalResult<TEdge>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notex-companion",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local retrieval companion for Notex — reads a checkout's graphify-out/graph.json and serves deterministic search/query/path/node lookups over loopback HTTP and (stub) MCP stdio. No LLM, no graph building, no network beyond 127.0.0.1.",
   "keywords": ["notex", "graphify", "mcp", "code-graph"],
   "license": "MIT",
@@ -21,6 +21,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
     "./package.json": "./package.json"
   },
   "files": ["dist", "README.md"],
@@ -32,7 +36,7 @@
     "typecheck": "tsc --noEmit",
     "build": "rm -rf dist && bun run build:cli && bun run build:lib && bun run build:types && chmod +x dist/cli.js",
     "build:cli": "bun build ./src/bin.ts --target=node --format=esm --outfile=dist/cli.js --banner=\"#!/usr/bin/env node\"",
-    "build:lib": "bun build ./src/index.ts --target=node --format=esm --outfile=dist/index.js",
+    "build:lib": "bun build ./src/index.ts --target=node --format=esm --outfile=dist/index.js && bun build ./src/client.ts --target=browser --format=esm --outfile=dist/client.js",
     "build:types": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
     "prepublishOnly": "bun run typecheck && bun test && bun run build"
   },