@ttsc/graph 0.30.4 → 0.31.0

package/src/structures/TtscGraphDumpEdgeKind.ts

@@ -1,4 +1,18 @@
-/** Relationship kinds the native Go dump producer can write. */
+/**
+ * Relationship kinds the native Go dump producer can write.
+ *
+ * Memory-only containment and trace dispatch are absent because the native
+ * producer does not emit either relation.
+ *
+ * @evidence contracts/common.md#principled-implementation Literal variants describe only relationships emitted by the native wire producer.
+ * @evidence contracts/common.md#clear-and-simple-design A separate wire union keeps validation independent of memory-derived relation additions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Memory containment and inferred dispatch cannot be accepted as native compiler output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains why the wire vocabulary excludes the two later-layer relationships.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
 export type TtscGraphDumpEdgeKind =
   | "exports"
   | "calls"

package/src/structures/TtscGraphDumpNodeKind.ts

@@ -6,6 +6,15 @@
  * that the type system holds nothing for — and their ids are the address a
  * citation writes rather than the `path#name:kind` grammar, which is why an id
  * is parsed only after its kind says it can be.
+ *
+ * @evidence contracts/common.md#principled-implementation Native declaration and published artifact variants match the wire producer vocabulary before memory refinement.
+ * @evidence contracts/common.md#clear-and-simple-design The wire union is separate from memory kinds so module replacement does not weaken native validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Artifact addresses are not coerced into TypeScript symbol-id grammar.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation explains the artifact distinction and the gate required before parsing identities.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export type TtscGraphDumpNodeKind =
   | "module"

package/src/structures/TtscGraphEdgeKind.ts

@@ -3,10 +3,10 @@
  *
  * Structural `exports` edges come from the native declaration pass, while the
  * TypeScript memory layer synthesizes `contains` ownership. Value and type
- * edges (`calls`, `accesses`, `instantiates`, `type_ref`,
- * `extends`, `implements`, `overrides`, `renders`) are resolved by the checker
- * — `renders` is a JSX component use. Decorators are facts on their target node,
- * not edges.
+ * edges (`calls`, `accesses`, `instantiates`, `type_ref`, `extends`,
+ * `implements`, `overrides`, `renders`) are resolved by the checker — `renders`
+ * is a JSX component use. Decorators are facts on their target node, not
+ * edges.
  *
  * `doc_ref` is a declaration's own documentation naming a symbol through an
  * inline link. The checker resolves that name and counts it as a use, so it is
@@ -21,6 +21,15 @@
  * implementation. It carries the implementation's declaration span, and a
  * traversal that follows what executes emits it in place of the dead end. It is
  * trace-only and never appears in a native dump.
+ *
+ * @evidence contracts/common.md#principled-implementation The union distinguishes compiler relationships, memory containment and trace-only dispatch, each with a separate semantic role.
+ * @evidence contracts/common.md#clear-and-simple-design One shared relation vocabulary keeps producers and projections aligned without a second generic relation taxonomy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Documentation links remain compiler uses; dispatch follows actual implementation relations rather than guessing runtime calls.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain structural, documentation and dispatch relationships and their producer boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export type TtscGraphEdgeKind =
   | "contains"

package/src/structures/TtscGraphNodeKind.ts

@@ -7,6 +7,15 @@
  * leaf keeps its real declaration kind and sets `external: true`.
  *
  * Used as the `kind` discriminant on {@link ITtscGraphNode}.
+ *
+ * @evidence contracts/common.md#principled-implementation Literal variants distinguish memory-layer declaration containers, refined members and published artifacts.
+ * @evidence contracts/common.md#clear-and-simple-design A single kind union is shared by node records instead of independent untyped classification strings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Kinds express supported graph semantics, not fixture names or framework-specific categories.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain native-to-memory refinement and external leaves before the tags.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export type TtscGraphNodeKind =
   | "file"

package/src/structures/TtscGraphNodeModifier.ts

@@ -3,6 +3,15 @@
  * declaration pass records it. Used by projections that reason about visibility
  * and shape — e.g. a public-API overview filters on `export`, a class outline
  * separates `static` members.
+ *
+ * @evidence contracts/common.md#principled-implementation The literal union represents the declaration modifiers the native pass records, without assigning runtime behavior to absent modifiers.
+ * @evidence contracts/common.md#clear-and-simple-design Shared modifier values serve node presentation and projection decisions without separate visibility flags for each consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Visibility comes from compiler facts rather than naming conventions for private symbols.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains optional collection and the visibility/shape use cases.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export type TtscGraphNodeModifier =
   | "export"

package/src/structures/ViewerLink.ts

@@ -0,0 +1,22 @@
+/**
+ * Viewer edge joining two retained display identities.
+ *
+ * @evidence contracts/common.md#principled-implementation Source and target use the node rewrite policy while kind groups native relationships into supported visual families.
+ * @evidence contracts/common.md#clear-and-simple-design The display relation carries only endpoints and color-family category.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown relationship kinds pass through rather than being relabeled as a known family.
+ * @evidence contracts/common.md#meaningful-documentation Native members describe rewritten endpoints and display-family kind.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface ViewerLink {
+  /** Retained source viewer node id. */
+  source: string;
+
+  /** Retained target viewer node id. */
+  target: string;
+
+  /** Grouped display family, or an unchanged unknown native kind. */
+  kind: string;
+}

package/src/structures/ViewerNode.ts

@@ -0,0 +1,28 @@
+/**
+ * Connected viewer node with its degree in the final displayed subgraph.
+ *
+ * @evidence contracts/common.md#principled-implementation Rewritten identity and file coordinates remain paired; degree counts only final visible incident edges.
+ * @evidence contracts/common.md#clear-and-simple-design One compact display record omits native provenance and source spans unnecessary for drawing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Name is presentation, not a substitute identity that could merge distinct declarations.
+ * @evidence contracts/common.md#meaningful-documentation Native members identify display coordinates and final-subgraph degree.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface ViewerNode {
+  /** Identity rewritten with the same path policy as incident edges. */
+  id: string;
+
+  /** Producer declaration display name. */
+  name: string;
+
+  /** Node category used for viewer colors. */
+  kind: string;
+
+  /** Display path after optional legacy rerooting. */
+  file: string;
+
+  /** Incident edge count after final node selection. */
+  degree: number;
+}

package/src/structures/ViewerPayload.ts

@@ -0,0 +1,52 @@
+import { ViewerLink } from "./ViewerLink";
+import { ViewerNode } from "./ViewerNode";
+
+/**
+ * Reduced connected graph and the populations removed by its filters.
+ *
+ * @evidence contracts/common.md#principled-implementation Final nodes/links describe the drawn subgraph while counters retain raw totals and distinct boundary/cap omissions.
+ * @evidence contracts/common.md#clear-and-simple-design One payload carries drawing inputs and explanatory totals without preserving a second full raw graph.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection losses are exposed as counters rather than hidden to imply the full project was drawn.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments define each count's population and distinguish selected nodes from cap/boundary removals.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface ViewerPayload {
+  /** Display project label, empty when not supplied. */
+  project: string;
+
+  /** Input/output totals and disjoint removal categories. */
+  counts: {
+    /** Node count before viewer filtering. */
+    rawNodes: number;
+
+    /** Edge count before viewer filtering. */
+    rawEdges: number;
+
+    /** Connected nodes in the final payload. */
+    nodes: number;
+
+    /** Edges whose rewritten endpoints both survive. */
+    links: number;
+
+    /** External nodes omitted when boundary filtering is enabled. */
+    droppedExternal: number;
+
+    /** Nonexternal ignored nodes omitted when generated filtering is enabled. */
+    droppedIgnored: number;
+
+    /**
+     * Boundary-surviving nodes removed by the degree cap, before isolated-node
+     * removal.
+     */
+    droppedByCap: number;
+  };
+
+  /** Connected display nodes. */
+  nodes: ViewerNode[];
+
+  /** Directed display edges between retained nodes. */
+  links: ViewerLink[];
+}

package/src/view.ts

@@ -1,59 +1,33 @@
-import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import http from "node:http";
+import type { Socket } from "node:net";
 import path from "node:path";
 
-import {
-  nonNegativeIntegerOption,
-  parseLauncherOptions,
-  positiveIntegerOption,
-  projectOptions,
-} from "./launcherArgs";
-import { parseDump } from "./model/loadGraph";
+import { TtscGraphLauncherArguments } from "./TtscGraphLauncherArguments";
+import { TtscGraphViewSnapshot } from "./TtscGraphViewSnapshot";
+import { GraphProcessTrace } from "./internal/GraphProcessTrace";
 import { publishArtifacts } from "./model/publishedArtifacts";
 import { captureProcessOutput, ensureExecutable } from "./nativeExecutable";
 import { reduce } from "./reduce";
 import { resolveGraphBinary } from "./resolveGraphBinary";
 
-interface ViewOptions {
-  cwd: string;
-  tsconfig: string;
-  port: number;
-  open: boolean;
-  maxNodes: number;
-}
-
-function parseViewArgs(argv: readonly string[]): ViewOptions {
-  const values = parseLauncherOptions(argv, [
-    { key: "cwd", flags: ["--cwd"], kind: "value" },
-    { key: "tsconfig", flags: ["--tsconfig", "-p"], kind: "value" },
-    { key: "port", flags: ["--port"], kind: "value" },
-    { key: "open", flags: ["--no-open"], kind: "flag" },
-    { key: "max_nodes", flags: ["--max-nodes"], kind: "value" },
-  ]);
-  const project = projectOptions(values);
-  return {
-    ...project,
-    port:
-      values.has("port") === true
-        ? nonNegativeIntegerOption(values, "port", 65_535)
-        : 0,
-    open: values.get("open") !== true,
-    maxNodes:
-      values.has("max_nodes") === true
-        ? positiveIntegerOption(values, "max_nodes", Number.MAX_SAFE_INTEGER)
-        : 1200,
-  };
-}
-
 /**
  * `ttsc-graph view`: build the project's code graph, reduce it, and serve a
  * self-contained 3D viewer on a localhost port, opening the browser. The native
  * binary produces the graph (the same `dump` the docs document); everything
  * else is local and offline. The process stays alive serving until Ctrl+C.
+ *
+ * @evidence contracts/common.md#principled-implementation Loopback binding must succeed before native preparation starts. Only a version-validated, reduced snapshot and bundled assets become ready; requests during preparation receive 503.
+ * @evidence contracts/common.md#clear-and-simple-design CLI parsing, native capture, reduction and loopback serving have explicit boundaries; browser opening is a best-effort convenience.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native failure remains a nonzero outcome and viewer absence remains an installation error rather than a fallback to fabricated graph data.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains offline operation, native producer responsibility and the process lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation Binary selection and Node paths/fs use native abstractions; browser opening isolates Windows start, macOS open and other-host xdg-open commands.
+ * @evidence contracts/performance.md#efficient-algorithms Native capture and reduction process the dump once; JSON and viewer assets are materialized once and reused by HTTP responses.
+ * @evidence contracts/performance.md#reuse-equivalent-work All requests to this one-shot viewer share the same reduced graph string and asset buffers; a new source snapshot requires another viewer invocation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Capture descriptors are disposed in finally. Signal cancellation cancels scheduled preparation or publication, drops the payload and closes owned sockets/server; bind failure releases signal listeners without starting native work. Synchronous native preparation cannot be interrupted by a queued JavaScript signal handler.
  */
 export function runView(argv: readonly string[]): number | void {
-  const opts = parseViewArgs(argv);
+  const opts = TtscGraphLauncherArguments.view(argv);
 
   // Anchor binary resolution at the project selected by `--cwd`, so `view` from
   // an unrelated directory still finds the `ttsc` installed under the target.
@@ -68,6 +42,173 @@ export function runView(argv: readonly string[]): number | void {
   }
   ensureExecutable(binary);
 
+  let prepared: Exclude<ReturnType<typeof prepareView>, number> | undefined;
+  let state: "binding" | "preparing" | "ready" | "closing" | "closed" =
+    "binding";
+  let pending: NodeJS.Immediate | undefined;
+  let closeRequested = false;
+  let endpoint = `127.0.0.1:${opts.port}`;
+  const connections = new Set<Socket>();
+  const server = http.createServer((req, res) => {
+    if (state !== "ready" || prepared === undefined) {
+      res.writeHead(503, {
+        "content-type": "text/plain; charset=utf-8",
+        connection: "close",
+      });
+      res.end("The graph viewer is not ready.\n");
+      return;
+    }
+    const url = (req.url ?? "/").split("?")[0];
+    if (url === "/graph.json") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(prepared.graphJson);
+    } else if (url === "/viewer.js") {
+      res.writeHead(200, {
+        "content-type": "application/javascript; charset=utf-8",
+      });
+      res.end(prepared.viewerJs);
+    } else {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(prepared.indexHtml);
+    }
+  });
+  const releaseSignals = (): void => {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", terminate);
+  };
+  const reportCloseFailure = (error: Error): void => {
+    process.exitCode = 1;
+    process.stderr.write(
+      `@ttsc/graph: could not close the 3D viewer at ${endpoint} (${error.message}).\n`,
+    );
+  };
+  const stop = (): void => {
+    if (state === "closed") return;
+    state = "closing";
+    if (pending !== undefined) {
+      clearImmediate(pending);
+      pending = undefined;
+    }
+    prepared = undefined;
+    for (const connection of connections) connection.destroy();
+    // If cancellation preceded the listening event, that event owns closure.
+    if (!server.listening || closeRequested) return;
+    closeRequested = true;
+    try {
+      server.close((error) => {
+        if (error) reportCloseFailure(error);
+      });
+    } catch (error) {
+      reportCloseFailure(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  };
+  const interrupt = (): void => {
+    process.exitCode = 130;
+    stop();
+  };
+  const terminate = (): void => {
+    process.exitCode = 143;
+    stop();
+  };
+  server.on("connection", (connection) => {
+    connections.add(connection);
+    connection.once("close", () => connections.delete(connection));
+    if (state === "closing" || state === "closed") connection.destroy();
+  });
+  server.once("close", () => {
+    if (pending !== undefined) {
+      clearImmediate(pending);
+      pending = undefined;
+    }
+    state = "closed";
+    prepared = undefined;
+    releaseSignals();
+  });
+  server.on("error", (error: NodeJS.ErrnoException) => {
+    const detail =
+      typeof error.code === "string"
+        ? `${error.code}: ${error.message}`
+        : error.message;
+    process.stderr.write(
+      `@ttsc/graph: could not serve the 3D viewer at ${endpoint} (${detail}).\n`,
+    );
+    process.exitCode = 1;
+    if (!server.listening && !closeRequested) {
+      state = "closed";
+      if (pending !== undefined) {
+        clearImmediate(pending);
+        pending = undefined;
+      }
+      prepared = undefined;
+      releaseSignals();
+    } else stop();
+  });
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", terminate);
+  try {
+    server.listen(opts.port, "127.0.0.1", () => {
+      if (state === "closing") {
+        stop();
+        return;
+      }
+      if (state !== "binding") return;
+      const address = server.address();
+      const port =
+        typeof address === "object" && address ? address.port : opts.port;
+      endpoint = `127.0.0.1:${port}`;
+      state = "preparing";
+      pending = setImmediate(() => {
+        pending = undefined;
+        if (state !== "preparing") return;
+        try {
+          const result = prepareView(opts, binary);
+          if (typeof result === "number") {
+            process.exitCode = result;
+            stop();
+            return;
+          }
+          // Yield after synchronous native preparation so queued cancellation
+          // and transport events are handled before publishing readiness.
+          pending = setImmediate(() => {
+            pending = undefined;
+            if (state !== "preparing") return;
+            prepared = result;
+            state = "ready";
+            const counts = result.payload.counts;
+            const url = `http://${endpoint}/`;
+            process.stderr.write(
+              `@ttsc/graph: ${counts.nodes.toLocaleString()} nodes / ${counts.links.toLocaleString()} edges` +
+                ` (from ${counts.rawNodes.toLocaleString()} / ${counts.rawEdges.toLocaleString()})\n`,
+            );
+            process.stderr.write(
+              `@ttsc/graph: serving the 3D viewer at ${url}\n`,
+            );
+            process.stderr.write("@ttsc/graph: press Ctrl+C to stop.\n");
+            if (opts.open) openBrowser(url);
+          });
+        } catch (error) {
+          process.stderr.write(
+            `@ttsc/graph: could not prepare the 3D viewer (${String(error)}).\n`,
+          );
+          process.exitCode = 1;
+          stop();
+        }
+      });
+    });
+  } catch (error) {
+    state = "closed";
+    releaseSignals();
+    throw error;
+  }
+}
+
+/** Prepare one validated native snapshot and its bundled viewer assets. */
+function prepareView(
+  opts: ReturnType<typeof TtscGraphLauncherArguments.view>,
+  binary: string,
+) {
   process.stderr.write(
     `@ttsc/graph: building the graph for ${opts.cwd} (${opts.tsconfig})...\n`,
   );
@@ -79,13 +220,13 @@ export function runView(argv: readonly string[]): number | void {
   try {
     // The same artifacts the dump, the loader, and the resident session ask
     // for. Without this the viewer draws a different graph from the one every
-    // other entry point answers with — and it already carries the colours for
+    // other entry point answers with, and it already carries the colours for
     // the nodes it would be missing.
     const artifacts = publishArtifacts({
       cwd: opts.cwd,
       tsconfig: opts.tsconfig,
     });
-    dump = spawnSync(
+    dump = GraphProcessTrace.spawnSync(
       binary,
       [
         "dump",
@@ -110,24 +251,17 @@ export function runView(argv: readonly string[]): number | void {
     return 1;
   }
   if (dump.status !== 0) {
-    process.stderr.write(dump.stderr || "@ttsc/graph: dump failed\n");
+    process.stderr.write(dumpStderr || "@ttsc/graph: dump failed\n");
     return dump.status ?? 1;
   }
 
-  let raw: ReturnType<typeof parseDump>;
-  try {
-    raw = parseDump(dumpStdout);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(
-      message.startsWith("@ttsc/graph:")
-        ? `${message}\n`
-        : `@ttsc/graph: could not validate the graph dump: ${message}\n`,
-    );
-    return 1;
+  const snapshot = TtscGraphViewSnapshot.decode(dumpStdout);
+  if (!snapshot.ok) {
+    process.stderr.write(snapshot.diagnostic);
+    return snapshot.code;
   }
 
-  const payload = reduce(raw, { maxNodes: opts.maxNodes });
+  const payload = reduce(snapshot.raw, { maxNodes: opts.maxNodes });
   payload.project = path.basename(path.resolve(opts.cwd));
   const graphJson = JSON.stringify(payload);
 
@@ -145,70 +279,34 @@ export function runView(argv: readonly string[]): number | void {
     return 1;
   }
 
-  const server = http.createServer((req, res) => {
-    const url = (req.url ?? "/").split("?")[0];
-    if (url === "/graph.json") {
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(graphJson);
-    } else if (url === "/viewer.js") {
-      res.writeHead(200, {
-        "content-type": "application/javascript; charset=utf-8",
-      });
-      res.end(viewerJs);
-    } else {
-      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-      res.end(indexHtml);
-    }
-  });
-
-  let endpoint = `127.0.0.1:${opts.port}`;
-  let failed = false;
-  server.on("error", (error: NodeJS.ErrnoException) => {
-    if (failed) return;
-    failed = true;
-    const detail =
-      typeof error.code === "string"
-        ? `${error.code}: ${error.message}`
-        : error.message;
-    process.stderr.write(
-      `@ttsc/graph: could not serve the 3D viewer at ${endpoint} (${detail}).\n`,
-    );
-    process.exitCode = 1;
-    if (server.listening) {
-      server.close();
-      server.closeAllConnections?.();
-    }
-  });
-  server.listen(opts.port, "127.0.0.1", () => {
-    if (failed) return;
-    const address = server.address();
-    const port =
-      typeof address === "object" && address ? address.port : opts.port;
-    endpoint = `127.0.0.1:${port}`;
-    const url = `http://127.0.0.1:${port}/`;
-    const counts = payload.counts;
-    process.stderr.write(
-      `@ttsc/graph: ${counts.nodes.toLocaleString()} nodes / ${counts.links.toLocaleString()} edges` +
-        ` (from ${counts.rawNodes.toLocaleString()} / ${counts.rawEdges.toLocaleString()})\n`,
-    );
-    process.stderr.write(`@ttsc/graph: serving the 3D viewer at ${url}\n`);
-    process.stderr.write("@ttsc/graph: press Ctrl+C to stop.\n");
-    if (opts.open) openBrowser(url);
-  });
-  // No return: the listening server keeps the process alive until Ctrl+C.
+  return { payload, graphJson, indexHtml, viewerJs };
 }
 
 /** Best-effort open the URL in the default browser; the URL is printed anyway. */
 function openBrowser(url: string): void {
   try {
     if (process.platform === "win32")
-      spawn("cmd", ["/c", "start", "", url], {
+      GraphProcessTrace.spawn("cmd", ["/c", "start", "", url], {
         stdio: "ignore",
         detached: true,
-      }).unref();
+        windowsHide: true,
+      })
+        .on("error", () => undefined)
+        .unref();
     else if (process.platform === "darwin")
-      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
-    else spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+      GraphProcessTrace.spawn("open", [url], {
+        stdio: "ignore",
+        detached: true,
+      })
+        .on("error", () => undefined)
+        .unref();
+    else
+      GraphProcessTrace.spawn("xdg-open", [url], {
+        stdio: "ignore",
+        detached: true,
+      })
+        .on("error", () => undefined)
+        .unref();
   } catch {
     /* the URL is printed; opening is a convenience */
   }