From dc74102551fe8861b18fe8a30116745e72a52370 Mon Sep 17 00:00:00 2001
From: Ian Boyes <igboyes@gmail.com>
Date: Thu, 2 Jul 2026 14:00:44 -0700
Subject: [PATCH 1/3] chore: split browser and server TypeScript environments
 in apps/web

The single apps/web tsconfig pulled @types/node into global scope for the
whole program, so browser code type-checked against Node's ambient types
instead of the DOM.

Introduce two type-check projects:

- tsconfig.server.json emits declarations for src/server (and the server
  entry files) with Node types.
- tsconfig.app.json checks browser code with a DOM lib and no Node types,
  resolving @server/* to the emitted declarations so server source no
  longer enters the browser program.

start.ts is reachable from the client via routeTree.gen.ts, so it must be
browser-safe: switch its relative ./server/* imports to the @server alias
(resolved to declarations in the browser project) and replace node:crypto
with the Web Crypto API.

The upload @ts-expect-error stays: superagent's .attach types are
Node-flavored and its deps force @types/node globals into the browser
program via `reference types="node"`. This split does not remove that; it
goes away when superagent is dropped for server functions.
---
 .gitignore                       |  2 ++
 apps/web/package.json            |  2 +-
 apps/web/src/start.ts            | 22 +++++++++----------
 apps/web/src/uploads/uploader.ts |  9 +++++---
 apps/web/tsconfig.app.json       | 37 ++++++++++++++++++++++++++++++++
 apps/web/tsconfig.server.json    | 23 ++++++++++++++++++++
 6 files changed, 80 insertions(+), 15 deletions(-)
 create mode 100644 apps/web/tsconfig.app.json
 create mode 100644 apps/web/tsconfig.server.json

diff --git a/.gitignore b/.gitignore
index 0076a3a3e..e5d3327c6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,8 @@ __pycache__
 /build
 node_modules
 dist
+dist-types
+*.tsbuildinfo
 .output
 .nitro
 doc
diff --git a/apps/web/package.json b/apps/web/package.json
index e9503ff91..d92648f68 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -9,7 +9,7 @@
 		"develop": "vite",
 		"start": "node scripts/check-api.mjs && node .output/server/index.mjs",
 		"test": "TZ=UTC vitest",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc -p tsconfig.server.json && tsc -p tsconfig.app.json"
 	},
 	"dependencies": {
 		"@hookform/resolvers": "^5.4.0",
diff --git a/apps/web/src/start.ts b/apps/web/src/start.ts
index f8d980bc9..0598e38cf 100644
--- a/apps/web/src/start.ts
+++ b/apps/web/src/start.ts
@@ -1,22 +1,20 @@
-import { randomBytes } from "node:crypto";
 import {
 	sentryGlobalFunctionMiddleware,
 	sentryGlobalRequestMiddleware,
 } from "@sentry/tanstackstart-react";
-import {
-	createCsrfMiddleware,
-	createMiddleware,
-	createStart,
-} from "@tanstack/react-start";
-
 import {
 	createFirstUserFn,
 	loginFn,
 	logoutFn,
 	resetPasswordFn,
-} from "./server/auth/functions";
-import { createAuthenticationMiddleware } from "./server/auth/middleware";
-import { errorLoggingMiddleware } from "./server/error-logging";
+} from "@server/auth/functions";
+import { createAuthenticationMiddleware } from "@server/auth/middleware";
+import { errorLoggingMiddleware } from "@server/error-logging";
+import {
+	createCsrfMiddleware,
+	createMiddleware,
+	createStart,
+} from "@tanstack/react-start";
 
 // logoutFn must be exempt so stale or missing cookies can still be cleared.
 // createFirstUserFn runs before any user or session exists.
@@ -83,7 +81,9 @@ const documentHeadersMiddleware = createMiddleware().server(
 		}
 
 		const html = await response.text();
-		const nonce = randomBytes(16).toString("base64");
+		const nonce = btoa(
+			String.fromCharCode(...crypto.getRandomValues(new Uint8Array(16))),
+		);
 		const body = html.replace(/<script(?=[\s>])/g, `<script nonce="${nonce}"`);
 		const headers = new Headers(response.headers);
 		for (const build of documentHeaders) {
diff --git a/apps/web/src/uploads/uploader.ts b/apps/web/src/uploads/uploader.ts
index 41ad922b6..3acf4c1c9 100644
--- a/apps/web/src/uploads/uploader.ts
+++ b/apps/web/src/uploads/uploader.ts
@@ -101,9 +101,12 @@ export function upload(file: File, fileType: UploadType) {
 	apiClient
 		.post("/uploads")
 		.query({ name: file.name, type: fileType })
-		// @ts-expect-error A browser File is a valid multipart value at runtime; superagent's
-		// Node-flavored types (Blob from node:buffer) reject the DOM File. Remove once browser
-		// code no longer resolves @types/node globals.
+		// @ts-expect-error A browser File is a valid multipart value at runtime, but
+		// superagent's `.attach` types are Node-flavored (Blob/Buffer/ReadStream) and its
+		// deps (form-data, undici-types) pull @types/node globals into the browser program
+		// via `/// <reference types="node" />`, so the DOM File is rejected. The browser/server
+		// tsconfig split does not remove this; it goes away when superagent is dropped in favour
+		// of server functions. Remove this directive then.
 		.attach("file", file)
 		.on("progress", onProgress)
 		.then(() => useUploaderStore.getState().removeUpload(localId))
diff --git a/apps/web/tsconfig.app.json b/apps/web/tsconfig.app.json
new file mode 100644
index 000000000..c83239308
--- /dev/null
+++ b/apps/web/tsconfig.app.json
@@ -0,0 +1,37 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"types": [],
+		"lib": ["DOM", "DOM.Iterable", "ESNext"],
+		"paths": {
+			"@/*": ["./src/*"],
+			"@account/*": ["./src/account/*"],
+			"@administration/*": ["./src/administration/*"],
+			"@analyses/*": ["./src/analyses/*"],
+			"@app/*": ["./src/app/*"],
+			"@base/*": ["./src/base/*"],
+			"@forms/*": ["./src/forms/*"],
+			"@groups/*": ["./src/groups/*"],
+			"@hmm/*": ["./src/hmm/*"],
+			"@indexes/*": ["./src/indexes/*"],
+			"@jobs/*": ["./src/jobs/*"],
+			"@banner/*": ["./src/banner/*"],
+			"@labels/*": ["./src/labels/*"],
+			"@nav/*": ["./src/nav/*"],
+			"@otus/*": ["./src/otus/*"],
+			"@quality/*": ["./src/quality/*"],
+			"@references/*": ["./src/references/*"],
+			"@samples/*": ["./src/samples/*"],
+			"@sequences/*": ["./src/sequences/*"],
+			"@server/*": ["./dist-types/server/*"],
+			"@subtraction/*": ["./src/subtraction/*"],
+			"@tasks/*": ["./src/tasks/*"],
+			"@tests/*": ["./src/tests/*"],
+			"@uploads/*": ["./src/uploads/*"],
+			"@users/*": ["./src/users/*"],
+			"@wall/*": ["./src/wall/*"]
+		}
+	},
+	"include": ["src/**/*"],
+	"exclude": ["src/server/**", "src/server.ts", "src/instrument.server.ts"]
+}
diff --git a/apps/web/tsconfig.server.json b/apps/web/tsconfig.server.json
new file mode 100644
index 000000000..92dabf568
--- /dev/null
+++ b/apps/web/tsconfig.server.json
@@ -0,0 +1,23 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"noEmit": false,
+		"outDir": "./dist-types",
+		"rootDir": "./src",
+		"lib": ["DOM", "DOM.Iterable", "ESNext"],
+		"typeRoots": [
+			"../../node_modules/@types",
+			"node_modules/@types",
+			"./src/types"
+		],
+		"types": ["node"]
+	},
+	"include": [
+		"src/server/**/*",
+		"src/server.ts",
+		"src/start.ts",
+		"src/instrument.server.ts"
+	]
+}

From 27849d2be70705991d39731212b263c8f2e8fcbc Mon Sep 17 00:00:00 2001
From: Ian Boyes <igboyes@gmail.com>
Date: Thu, 2 Jul 2026 14:01:45 -0700
Subject: [PATCH 2/3] docs: require @server alias for client-reachable server
 imports

Client-reachable files bypass the browser/server tsconfig split's declaration remap when they use relative ./server/* imports, dragging @types/node globals back into the browser program. Document the @server/* alias rule alongside the two-project type-check setup.
---
 AGENTS.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index a733bb19a..c74b3246e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -229,6 +229,20 @@ invariant in full, the labels (minimal) and auth (carve-out) shapes,
 the pure-policy-vs-framework-shell principle, and when to introduce
 `service.ts`.
 
+### Client-reachable files import server modules via `@server/*`
+
+`apps/web` type-checks as two projects (`pnpm typecheck` runs both):
+`tsconfig.server.json` (Node types) for `src/server`, and
+`tsconfig.app.json` (DOM lib, no Node types) for browser code, which
+resolves `@server/*` to the server project's emitted declarations.
+
+Any file reachable from the browser program — including framework
+entries pulled in by `routeTree.gen.ts`, like `start.ts` — must import
+server modules through the `@server/*` alias, never a relative
+`./server/*` path. A relative import bypasses the declaration remap and
+drags the server source graph (and `@types/node` globals) back into the
+browser program.
+
 ### Authentication is enforced by global middleware
 
 Every TanStack Start server function is authenticated by default.

From bea9aa0f8b20215cf60ac9960646c6c6a4a84fbc Mon Sep 17 00:00:00 2001
From: Ian Boyes <igboyes@gmail.com>
Date: Thu, 2 Jul 2026 14:58:53 -0700
Subject: [PATCH 3/3] refactor: extract generateNonce helper in start.ts

Document why the nonce uses Web Crypto + btoa rather than node:crypto/Buffer: start.ts is reachable from the browser program and must type-check without Node types. Both globals exist in the Node runtime, so the server middleware is safe.
---
 apps/web/src/start.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/start.ts b/apps/web/src/start.ts
index 0598e38cf..3f79e4703 100644
--- a/apps/web/src/start.ts
+++ b/apps/web/src/start.ts
@@ -71,6 +71,16 @@ const documentHeaders: DocumentHeader[] = [
 	buildCacheControl,
 ];
 
+// Per-request CSP nonce. Deliberately uses the Web Crypto and `btoa` globals
+// rather than node:crypto/Buffer: this file is reachable from the browser
+// program (routeTree.gen.ts imports it) and must type-check without Node types.
+// Both globals exist in our Node runtime, so the server middleware is safe.
+function generateNonce(): string {
+	return btoa(
+		String.fromCharCode(...crypto.getRandomValues(new Uint8Array(16))),
+	);
+}
+
 const documentHeadersMiddleware = createMiddleware().server(
 	async ({ next }) => {
 		const result = await next();
@@ -81,9 +91,7 @@ const documentHeadersMiddleware = createMiddleware().server(
 		}
 
 		const html = await response.text();
-		const nonce = btoa(
-			String.fromCharCode(...crypto.getRandomValues(new Uint8Array(16))),
-		);
+		const nonce = generateNonce();
 		const body = html.replace(/<script(?=[\s>])/g, `<script nonce="${nonce}"`);
 		const headers = new Headers(response.headers);
 		for (const build of documentHeaders) {