fix(internal): fix broken builds with fresh checkout on both typecheck and api-check (tldraw#8249)

While working on tldraw#8194 I came upon
some issues with tldraw/driver, I threw Claude at it until I could
actually yarn typecheck and yarn api-check locally and it fixed the
issue on my branch.

### Commit 1: "Fix: internal typecheck"
This fixes the internal/scripts/typecheck.ts script, which runs tsgo
--build across all workspace packages.

The problem: On a fresh checkout, tsgo --build can't always resolve the
full project-reference graph correctly when all package tsconfigs are
passed in a single invocation. The previous workaround was to
"bootstrap" packages first, but it was passing them all at once — which
still left ordering issues if package A depends on package B but B
hadn't been built yet.

The fix: It adds a topoSortTsconfigs() function that reads each
tsconfig's references field and performs a topological sort
(depth-first). Then instead of one bulk tsgo --build ...all-packages, it
builds each package tsconfig one at a time in topological order — leaves
first, dependents after. This ensures each package's declaration outputs
exist before any package that depends on them is built.

### Commit 2: "fix(internal): api-check" 
This fixes the internal/scripts/api-check.ts script, which verifies that
the public API surface of published packages type-checks correctly
against their declared dependencies.

Two problems fixed:

Broken tiptap versions from npm. The script was doing a bare npm install
@tiptap/core which pulled the latest version from the registry (3.20.3),
which turned out to be a broken release missing its dist/ directory. The
fix introduces a getPinnedVersions() function that reads the actual
installed version from the workspace's node_modules and installs that
exact version (e.g. @tiptap/core@3.13.0). It also adds @tiptap/pm,
react, and react-dom as dependencies (previously missing), while
removing the old @tiptap/react and @tiptap/core entries from the
unpinned list.

Module resolution for tiptap subpath exports. Packages like @tiptap/pm
use subpath exports (@tiptap/pm/state, @tiptap/pm/model, etc.) which
only resolve when TypeScript's moduleResolution is set to "bundler". The
generated tsconfig had no explicit module settings, so tsc defaulted to
node10 resolution which ignores the exports field entirely. The fix adds
module: "esnext" and moduleResolution: "bundler" to the generated
tsconfig.

### Change type

- [x] `bugfix`
- [ ] `improvement`
- [ ] `feature`
- [x] `api`
- [x] `other`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches internal build/typecheck tooling and changes dependency
resolution/order; mistakes could break CI or local developer workflows
but does not affect runtime product behavior.
> 
> **Overview**
> Fixes fresh-checkout failures in internal TypeScript verification
scripts.
> 
> `internal/scripts/typecheck.ts` now topologically sorts package
`tsconfig.json` files by their `references` and bootstraps `tsgo
--build` one package at a time (leaves first) to ensure declarations
exist before dependents build.
> 
> `internal/scripts/api-check.ts` updates the generated `tsconfig` to
use `module: "esnext"` and `moduleResolution: "bundler"` and pins
`@tiptap/*` installs to the workspace-resolved versions (plus adds
`react`/`react-dom` deps) to avoid broken upstream releases and subpath
export resolution issues during the API typecheck.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d2f78eb. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Guillaume <guillaume@tldraw.com>

Author: kaneel

internal/scripts/api-check.ts

@@ -1,4 +1,4 @@
-import { writeFileSync } from 'fs'
+import { readFileSync, writeFileSync } from 'fs'
 import { join, resolve } from 'path'
 import { exec } from './lib/exec'
 import { readFileIfExists } from './lib/file'
@@ -14,17 +14,31 @@ const packagesOurTypesCanDependOn = [
 	'@types/react-dom',
 	'eventemitter3',
 	'nanoevents',
-	'@tiptap/react',
-	'@tiptap/core',
+	'react',
+	'react-dom',
 ]
 
+// These packages use subpath exports which require moduleResolution: "bundler".
+// We pin to the workspace's resolved versions to avoid installing broken releases.
+const pinnedPackages = ['@tiptap/core', '@tiptap/react', '@tiptap/pm']
+
+function getPinnedVersions(): string[] {
+	return pinnedPackages.map((pkg) => {
+		const pkgJsonPath = resolve(`./node_modules/${pkg}/package.json`)
+		const { version } = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+		return `${pkg}@${version}`
+	})
+}
+
 main()
 
 async function main() {
 	const tsconfig: any = {
 		compilerOptions: {
 			lib: ['esnext', 'dom'],
 			strict: true,
+			module: 'esnext',
+			moduleResolution: 'bundler',
 			rootDir: '.',
 			paths: {},
 			esModuleInterop: true,
@@ -61,7 +75,9 @@ async function main() {
 	writeFileSync(`${tempDir}/tsconfig.json`, JSON.stringify(tsconfig, null, '\t'), 'utf8')
 	writeFileSync(`${tempDir}/package.json`, JSON.stringify({ dependencies: {} }, null, '\t'), 'utf8')
 
-	await exec('npm', ['install', ...packagesOurTypesCanDependOn], { pwd: tempDir })
+	await exec('npm', ['install', ...packagesOurTypesCanDependOn, ...getPinnedVersions()], {
+		pwd: tempDir,
+	})
 	await exec(resolve('./node_modules/.bin/tsc'), [], { pwd: tempDir })
 
 	await exec('rm', ['-rf', tempDir])

internal/scripts/typecheck.ts

@@ -27,15 +27,19 @@ async function main() {
 
 	// tsgo currently struggles to resolve some workspace package imports on a fresh checkout
 	// when all projects are passed in a single --build invocation. Building package
-	// workspaces first produces the declaration outputs needed for the full graph.
+	// workspaces first in topological order (leaves before dependents) produces the
+	// declaration outputs needed for the full graph.
 	const packageTsconfigFiles = tsconfigFiles.filter((file) =>
 		file.includes(`${path.sep}packages${path.sep}`)
 	)
 	if (packageTsconfigFiles.length > 0) {
+		const sortedPackageTsconfigFiles = await topoSortTsconfigs(packageTsconfigFiles)
 		const bootstrapArgs = ['--build']
 		if (process.argv.includes('--force')) bootstrapArgs.push('--force')
 		nicelog('Bootstrapping tsgo package references')
-		execFileSync(compilerPath, [...bootstrapArgs, ...packageTsconfigFiles], { stdio: 'inherit' })
+		for (const tsconfigFile of sortedPackageTsconfigFiles) {
+			execFileSync(compilerPath, [...bootstrapArgs, tsconfigFile], { stdio: 'inherit' })
+		}
 	}
 
 	// In watch mode, use execFileSync with inherited stdio - it handles everything
@@ -103,6 +107,48 @@ async function main() {
 	})
 }
 
+/**
+ * Sort tsconfig files in topological order based on their `references` fields,
+ * so that leaf packages (no dependencies) come first and dependents come after
+ * all their dependencies. This is needed because tsgo --build doesn't always
+ * resolve the reference graph correctly on a fresh checkout.
+ */
+async function topoSortTsconfigs(tsconfigFiles: string[]): Promise<string[]> {
+	const dirToFile = new Map<string, string>()
+	const deps = new Map<string, string[]>()
+
+	for (const file of tsconfigFiles) {
+		const dir = path.dirname(file)
+		dirToFile.set(dir, file)
+		const tsconfig = await readJsonIfExists(file)
+		const refs: string[] = []
+		if (tsconfig?.references) {
+			for (const ref of tsconfig.references) {
+				refs.push(path.resolve(dir, ref.path))
+			}
+		}
+		deps.set(dir, refs)
+	}
+
+	const visited = new Set<string>()
+	const sorted: string[] = []
+
+	function visit(dir: string) {
+		if (visited.has(dir)) return
+		visited.add(dir)
+		for (const dep of deps.get(dir) ?? []) {
+			if (dirToFile.has(dep)) visit(dep)
+		}
+		sorted.push(dirToFile.get(dir)!)
+	}
+
+	for (const dir of dirToFile.keys()) {
+		visit(dir)
+	}
+
+	return sorted
+}
+
 main().catch((err) => {
 	console.error('Unexpected error:', err)
 	process.exit(1)