@ttsc/graph 0.30.4 → 0.31.1

package/lib/structures/TtscGraphArtifactNodeKind.js

@@ -30,6 +30,15 @@ exports.TTSC_GRAPH_ARTIFACT_NODE_KINDS = [
  * {@link TtscGraphNodeId} assumes: a Prisma address carries no path because a
  * model name is unique across the schema folder, and an operation has no file
  * at all.
+ *
+ * @evidence contracts/common.md#principled-implementation Membership in the declared artifact-kind vocabulary distinguishes non-TypeScript addresses before symbol-id parsing.
+ * @evidence contracts/common.md#clear-and-simple-design The predicate shares the exported kind list instead of maintaining a second classification switch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The check concerns semantic kinds, not heuristics about address punctuation or fixture paths.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why artifact identities cannot use the TypeScript id parser.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one includes test over six constant kinds.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation tests a kind name, which is not a path.
  */
 function isArtifactNodeKind(kind) {
     return exports.TTSC_GRAPH_ARTIFACT_NODE_KINDS.includes(kind);

package/lib/structures/TtscGraphArtifactNodeKind.js.map

@@ -1 +1 @@
-{"version":3,"file":"TtscGraphArtifactNodeKind.js","sourceRoot":"","sources":["../../src/structures/TtscGraphArtifactNodeKind.ts"],"names":[],"mappings":";;;;AAEA;;;;;;;;;;GAUG;AACU,QAAA,8BAA8B,GAAG;IAC5C,mBAAmB;IACnB,kBAAkB;IAClB,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,mBAAmB;CAC4B,CAAC;AAElD;;;;;;;;;GASG;AACH,4BAAmC,IAAY;IAC7C,OAAQ,QAAA,8BAAoD,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"TtscGraphArtifactNodeKind.js","sourceRoot":"","sources":["../../src/structures/TtscGraphArtifactNodeKind.ts"],"names":[],"mappings":";;;;AAEA;;;;;;;;;;GAUG;AACU,QAAA,8BAA8B,GAAG;IAC5C,mBAAmB;IACnB,kBAAkB;IAClB,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,mBAAmB;CAC4B,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,4BAAmC,IAAY;IAC7C,OAAQ,QAAA,8BAAoD,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC"}

package/lib/structures/TtscGraphDumpEdgeKind.d.ts

@@ -1,2 +1,16 @@
-/** 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" | "accesses" | "instantiates" | "type_ref" | "doc_ref" | "extends" | "implements" | "overrides" | "renders";

package/lib/structures/TtscGraphDumpNodeKind.d.ts

@@ -6,5 +6,14 @@
  * 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" | "function" | "class" | "interface" | "type" | "enum" | "variable" | "method" | "markdown_document" | "markdown_section" | "prisma_model" | "prisma_column" | "prisma_relation" | "swagger_operation";

package/lib/structures/TtscGraphEdgeKind.d.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,5 +21,14 @@
  * 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" | "exports" | "calls" | "accesses" | "instantiates" | "type_ref" | "doc_ref" | "extends" | "implements" | "overrides" | "dispatches" | "renders";

package/lib/structures/TtscGraphNodeKind.d.ts

@@ -7,5 +7,14 @@
  * 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" | "function" | "class" | "interface" | "type" | "enum" | "variable" | "method" | "property" | "markdown_document" | "markdown_section" | "prisma_model" | "prisma_column" | "prisma_relation" | "swagger_operation";

package/lib/structures/TtscGraphNodeModifier.d.ts

@@ -3,5 +3,14 @@
  * 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" | "default" | "declare" | "abstract" | "static" | "readonly" | "async" | "const" | "public" | "private" | "protected";

package/lib/structures/ViewerLink.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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/lib/structures/ViewerLink.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ViewerLink.js.map

package/lib/structures/ViewerLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewerLink.js","sourceRoot":"","sources":["../../src/structures/ViewerLink.ts"],"names":[],"mappings":""}

package/lib/structures/ViewerNode.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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/lib/structures/ViewerNode.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ViewerNode.js.map

package/lib/structures/ViewerNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewerNode.js","sourceRoot":"","sources":["../../src/structures/ViewerNode.ts"],"names":[],"mappings":""}

package/lib/structures/ViewerPayload.d.ts

@@ -0,0 +1,42 @@
+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/lib/structures/ViewerPayload.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ViewerPayload.js.map

package/lib/structures/ViewerPayload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewerPayload.js","sourceRoot":"","sources":["../../src/structures/ViewerPayload.ts"],"names":[],"mappings":""}

package/lib/view.d.ts

@@ -3,5 +3,14 @@
  * 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 declare function runView(argv: readonly string[]): number | void;

package/lib/view.js

@@ -4,44 +4,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runView = runView;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_http_1 = __importDefault(require("node:http"));
 const node_path_1 = __importDefault(require("node:path"));
-const launcherArgs_1 = require("./launcherArgs");
-const loadGraph_1 = require("./model/loadGraph");
+const TtscGraphLauncherArguments_1 = require("./TtscGraphLauncherArguments");
+const TtscGraphViewSnapshot_1 = require("./TtscGraphViewSnapshot");
+const GraphProcessTrace_1 = require("./internal/GraphProcessTrace");
 const publishedArtifacts_1 = require("./model/publishedArtifacts");
 const nativeExecutable_1 = require("./nativeExecutable");
 const reduce_1 = require("./reduce");
 const resolveGraphBinary_1 = require("./resolveGraphBinary");
-function parseViewArgs(argv) {
-    const values = (0, launcherArgs_1.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 = (0, launcherArgs_1.projectOptions)(values);
-    return {
-        ...project,
-        port: values.has("port") === true
-            ? (0, launcherArgs_1.nonNegativeIntegerOption)(values, "port", 65_535)
-            : 0,
-        open: values.get("open") !== true,
-        maxNodes: values.has("max_nodes") === true
-            ? (0, launcherArgs_1.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.
  */
 function runView(argv) {
-    const opts = parseViewArgs(argv);
+    const opts = TtscGraphLauncherArguments_1.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.
     const binary = (0, resolveGraphBinary_1.resolveGraphBinary)(process.env, opts.cwd);
@@ -52,6 +41,170 @@ function runView(argv) {
         return 1;
     }
     (0, nativeExecutable_1.ensureExecutable)(binary);
+    let prepared;
+    let state = "binding";
+    let pending;
+    let closeRequested = false;
+    let endpoint = `127.0.0.1:${opts.port}`;
+    const connections = new Set();
+    const server = node_http_1.default.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 = () => {
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", terminate);
+    };
+    const reportCloseFailure = (error) => {
+        process.exitCode = 1;
+        process.stderr.write(`@ttsc/graph: could not close the 3D viewer at ${endpoint} (${error.message}).\n`);
+    };
+    const stop = () => {
+        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 = () => {
+        process.exitCode = 130;
+        stop();
+    };
+    const terminate = () => {
+        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) => {
+        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, binary) {
     process.stderr.write(`@ttsc/graph: building the graph for ${opts.cwd} (${opts.tsconfig})...\n`);
     // The dump goes to a file rather than a pipe, so no output ceiling applies.
     const capture = (0, nativeExecutable_1.captureProcessOutput)();
@@ -61,13 +214,13 @@ function runView(argv) {
     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 = (0, publishedArtifacts_1.publishArtifacts)({
             cwd: opts.cwd,
             tsconfig: opts.tsconfig,
         });
-        dump = (0, node_child_process_1.spawnSync)(binary, [
+        dump = GraphProcessTrace_1.GraphProcessTrace.spawnSync(binary, [
             "dump",
             "--cwd",
             opts.cwd,
@@ -89,21 +242,15 @@ function runView(argv) {
         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;
-    try {
-        raw = (0, loadGraph_1.parseDump)(dumpStdout);
+    const snapshot = TtscGraphViewSnapshot_1.TtscGraphViewSnapshot.decode(dumpStdout);
+    if (!snapshot.ok) {
+        process.stderr.write(snapshot.diagnostic);
+        return snapshot.code;
     }
-    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 payload = (0, reduce_1.reduce)(raw, { maxNodes: opts.maxNodes });
+    const payload = (0, reduce_1.reduce)(snapshot.raw, { maxNodes: opts.maxNodes });
     payload.project = node_path_1.default.basename(node_path_1.default.resolve(opts.cwd));
     const graphJson = JSON.stringify(payload);
     const viewerDir = node_path_1.default.join(__dirname, "viewer");
@@ -118,68 +265,33 @@ function runView(argv) {
             "Reinstall @ttsc/graph.\n");
         return 1;
     }
-    const server = node_http_1.default.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) => {
-        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) {
     try {
         if (process.platform === "win32")
-            (0, node_child_process_1.spawn)("cmd", ["/c", "start", "", url], {
+            GraphProcessTrace_1.GraphProcessTrace.spawn("cmd", ["/c", "start", "", url], {
                 stdio: "ignore",
                 detached: true,
-            }).unref();
+                windowsHide: true,
+            })
+                .on("error", () => undefined)
+                .unref();
         else if (process.platform === "darwin")
-            (0, node_child_process_1.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
+            GraphProcessTrace_1.GraphProcessTrace.spawn("open", [url], {
+                stdio: "ignore",
+                detached: true,
+            })
+                .on("error", () => undefined)
+                .unref();
         else
-            (0, node_child_process_1.spawn)("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+            GraphProcessTrace_1.GraphProcessTrace.spawn("xdg-open", [url], {
+                stdio: "ignore",
+                detached: true,
+            })
+                .on("error", () => undefined)
+                .unref();
     }
     catch {
         /* the URL is printed; opening is a convenience */