toiljs 0.0.112 → 0.0.114

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.112",
+    "version": "0.0.114",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -124,10 +124,10 @@
         "@dacely/hyper-express": "6.17.4",
         "@dacely/noble-post-quantum": "^0.6.1",
         "@dacely/toilscript-loader": "^0.1.0",
-        "@eslint-react/eslint-plugin": "^5.10.1",
+        "@eslint-react/eslint-plugin": "^5.13.2",
         "@eslint/js": "^10.0.1",
         "@noble/curves": "^2.2.0",
-        "@typescript-eslint/utils": "^8.62.1",
+        "@typescript-eslint/utils": "^8.63.0",
         "@vitejs/plugin-react": "^6.0.3",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-react-refresh": "^0.5.3",
@@ -136,9 +136,9 @@
         "nodemailer": "^9.0.3",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.3",
-        "toilscript": "^0.1.56",
-        "typescript-eslint": "^8.62.1",
-        "vite": "^8.1.3",
+        "toilscript": "^0.1.60",
+        "typescript-eslint": "^8.63.0",
+        "vite": "^8.1.4",
         "vite-imagetools": "^10.0.1",
         "vite-plugin-node-polyfills": "^0.28.0"
     },
@@ -147,8 +147,8 @@
         "prettier": ">=3.0.0",
         "react": ">=18.0.0",
         "react-dom": ">=18.0.0",
-        "toilscript": ">=0.1.56",
-        "typescript": ">=6.0.0"
+        "toilscript": ">=0.1.60",
+        "typescript": ">=6.0.0 <7.0.0"
     },
     "overrides": {
         "elliptic": "file:./stubs/elliptic"
@@ -157,25 +157,25 @@
         "@babel/core": "^8.0.1",
         "@babel/preset-env": "^8.0.2",
         "@babel/preset-typescript": "^8.0.1",
-        "@clack/prompts": "^1.6.0",
+        "@clack/prompts": "^1.7.0",
         "@microsoft/api-extractor": "7.58.9",
         "@testing-library/dom": "^10.4.1",
         "@testing-library/react": "^16.3.2",
-        "@types/node": "^26.1.0",
+        "@types/node": "^26.1.1",
         "@types/nodemailer": "^8.0.1",
         "@types/react": "^19.2.17",
         "@types/react-dom": "^19.2.3",
-        "@vitest/coverage-v8": "^4.1.9",
-        "@vitest/ui": "^4.1.9",
+        "@vitest/coverage-v8": "^4.1.10",
+        "@vitest/ui": "^4.1.10",
         "esbuild": "^0.28.1",
         "eslint": "^10.6.0",
         "jsdom": "^29.1.1",
         "micromatch": "^4.0.8",
-        "prettier": "^3.9.4",
+        "prettier": "^3.9.5",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
-        "typedoc": "^0.28.19",
+        "typedoc": "^0.28.20",
         "typescript": "^6.0.3",
-        "vitest": "^4.1.9"
+        "vitest": "^4.1.10"
     }
 }

package/src/cli/create.ts

@@ -157,6 +157,7 @@ function scaffold(
         private: true,
         type: 'module',
         scripts: {
+            start: 'toiljs start',
             dev: 'toiljs dev',
             build: 'toiljs build',
             'build:server': 'toiljs build --server',

package/src/cli/diagnostics.ts

@@ -83,6 +83,80 @@ export function checkPeer(name: string, installed: string | null, range: string)
     };
 }
 
+/** The TypeScript range toiljs supports, and the range `doctor --fix` pins an unsupported one to. */
+export const TYPESCRIPT_SUPPORTED = '>=6.0.0 <7.0.0';
+export const TYPESCRIPT_FIX_RANGE = '^6.0.3';
+
+/** First TypeScript major that dropped the JavaScript compiler API (the native port). */
+const TYPESCRIPT_NATIVE_MAJOR = 7;
+
+/**
+ * The major a dependency range floats to: the first number in the range, once the comparators are
+ * stripped (`^7.0.2` -> 7, `>=6.0.0 <7.0.0` -> 6). Returns null for a range that names no version
+ * (`*`, `latest`), which is treated as "unpinned" rather than "unsupported".
+ */
+export function rangeMajor(range: string): number | null {
+    const m = /(\d+)/.exec(range.replace(/^[\s^~>=<v]*/, ''));
+    return m ? Number(m[1]) : null;
+}
+
+/**
+ * TypeScript 7 is the native (Go) port: it publishes `tsc` but no longer exports the JavaScript
+ * compiler API, whose main entry is now just `{ version, versionMajorMinor }`. toiljs reads each
+ * route's static `metadata` through that API to bake SEO tags into the built HTML, and the eslint
+ * and typedoc presets load it too. So a TS 7 install does not fail loudly, it silently stops baking
+ * metadata (and hard-crashes typescript-eslint), which is worth a `fail` rather than a warning.
+ *
+ * `installed` is the version resolved from node_modules (authoritative, it is what actually runs);
+ * `declared` is the project's package.json range, which is flagged when it *admits* 7 even if the
+ * currently-installed copy is older, since the next install would break.
+ */
+export function checkTypeScript(installed: string | null, declared: string | null): Check {
+    const id = 'peer:typescript';
+    const label = 'typescript';
+    const unsupported = (version: string, detail: string): Check => ({
+        id,
+        label,
+        status: 'fail',
+        detail,
+        fix:
+            `TypeScript ${version} removed the JavaScript compiler API (it moved to ` +
+            `'typescript/unstable/*'), which toiljs's route-metadata extractor, the eslint preset, ` +
+            `and typedoc all load. Pin typescript to "${TYPESCRIPT_FIX_RANGE}" and reinstall ` +
+            `(\`toiljs doctor --fix\` does this).`,
+    });
+
+    if (installed === null) {
+        return {
+            id,
+            label,
+            status: 'fail',
+            detail: `not installed (requires ${TYPESCRIPT_SUPPORTED})`,
+            fix: `Install typescript@"${TYPESCRIPT_FIX_RANGE}".`,
+        };
+    }
+
+    const installedMajor = rangeMajor(installed);
+    if (installedMajor !== null && installedMajor >= TYPESCRIPT_NATIVE_MAJOR) {
+        return unsupported(String(installedMajor), `${installed} installed, unsupported`);
+    }
+
+    // Installed copy is fine, but the declared range would pull an unsupported major next install.
+    const declaredMajor = declared === null ? null : rangeMajor(declared);
+    if (declaredMajor !== null && declaredMajor >= TYPESCRIPT_NATIVE_MAJOR) {
+        return unsupported(String(declaredMajor), `package.json declares ${declared ?? ''}`);
+    }
+
+    const ok = satisfiesMin(installed, TYPESCRIPT_SUPPORTED);
+    return {
+        id,
+        label,
+        status: ok ? 'pass' : 'warn',
+        detail: `${installed} (requires ${TYPESCRIPT_SUPPORTED})`,
+        fix: ok ? undefined : `Update typescript to ${TYPESCRIPT_SUPPORTED}.`,
+    };
+}
+
 export function checkPackageManager(lockfiles: readonly string[]): Check {
     if (lockfiles.length === 0) {
         return {

package/src/cli/doctor.ts

@@ -46,15 +46,18 @@ import {
     checkToilconfig,
     checkToiljsInstalled,
     checkToilscriptInstalled,
+    checkTypeScript,
     checkWasmBuilt,
     findRelativeAssets,
     hasFailures,
+    rangeMajor,
     type RestFacts,
     RPC_TOILSCRIPT_MIN,
     type RpcFacts,
     satisfiesMin,
     type SourceFile,
     summarize,
+    TYPESCRIPT_FIX_RANGE,
 } from './diagnostics.js';
 import {
     detectTailwind,
@@ -70,7 +73,7 @@ export interface DoctorOptions {
     readonly cwd: string;
     /** Emit machine-readable JSON instead of the human report. */
     readonly json?: boolean;
-    /** Auto-fix what can be fixed in place (currently the typed-RPC wiring). */
+    /** Auto-fix what can be fixed in place (the typed-RPC wiring, and an unsupported typescript). */
     readonly fix?: boolean;
 }
 
@@ -129,6 +132,72 @@ function isPackageInstalled(root: string, name: string): boolean {
     }
 }
 
+/**
+ * The version of `name` actually installed for the project at `root`, or null when absent. Reads the
+ * resolved package.json rather than trusting the declared range, since the installed copy is what
+ * the compiler API consumers load. Falls back to walking `node_modules` (see `isPackageInstalled`).
+ */
+function installedVersion(root: string, name: string): string | null {
+    const require = createRequire(path.join(root, 'package.json'));
+    let pkgPath: string | null = null;
+    try {
+        pkgPath = require.resolve(`${name}/package.json`);
+    } catch {
+        for (let dir = root; pkgPath === null; ) {
+            const candidate = path.join(dir, 'node_modules', name, 'package.json');
+            if (fs.existsSync(candidate)) pkgPath = candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir) break;
+            dir = parent;
+        }
+    }
+    if (pkgPath === null) return null;
+    const pkg = readJsonObject(pkgPath);
+    return pkg && typeof pkg.version === 'string' ? pkg.version : null;
+}
+
+/**
+ * Pins an unsupported TypeScript (the native 7.x, which ships no JavaScript compiler API) back to a
+ * range toiljs can drive. Rewrites whichever of `devDependencies`/`dependencies` declares it; a
+ * project with no declaration at all is left alone (nothing to pin), and the reinstall is left to
+ * the user since only they know their package manager.
+ */
+function applyTypeScriptFix(root: string): RpcFixResult {
+    const changed: string[] = [];
+    const skipped: string[] = [];
+
+    const pkgPath = path.join(root, 'package.json');
+    const pkg = readJsonObject(pkgPath);
+    if (pkg === null) return { changed, skipped };
+
+    const field = (['devDependencies', 'dependencies'] as const).find((f) => {
+        const deps = asRecord(pkg[f]);
+        return deps !== null && typeof deps.typescript === 'string';
+    });
+    if (field === undefined) {
+        // Nothing declares typescript: it is either absent or hoisted from a workspace root.
+        if (installedVersion(root, 'typescript') !== null) {
+            skipped.push('typescript (installed but not declared in package.json; pin it by hand)');
+        }
+        return { changed, skipped };
+    }
+
+    const deps = asRecord(pkg[field]);
+    if (deps === null) return { changed, skipped };
+    const declared = deps.typescript as string;
+    const declaredMajor = rangeMajor(declared);
+    const installedMajor = rangeMajor(installedVersion(root, 'typescript') ?? '');
+    const unsupported =
+        (declaredMajor !== null && declaredMajor >= 7) ||
+        (installedMajor !== null && installedMajor >= 7);
+    if (!unsupported) return { changed, skipped };
+
+    deps.typescript = TYPESCRIPT_FIX_RANGE;
+    writeFile(pkgPath, JSON.stringify(pkg, null, 4) + '\n');
+    changed.push(`package.json (typescript ${declared} -> ${TYPESCRIPT_FIX_RANGE})`);
+    return { changed, skipped };
+}
+
 /** Narrows a value to a plain (non-array) object, or null. */
 function asRecord(value: unknown): Record<string, unknown> | null {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -764,7 +833,26 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     }
 
     const peerName = (n: string): Check => checkPeer(n, deps[n] ?? null, meta.peers[n] ?? '*');
-    const peerChecks = Object.keys(meta.peers).map(peerName);
+    // typescript gets its own check: its peer range is the only one whose upper bound matters (7.x
+    // clears the `>=6.0.0` floor but ships no compiler API), and it is fixable in place.
+    const peerChecks = Object.keys(meta.peers)
+        .filter((n) => n !== 'typescript')
+        .map(peerName);
+    const typeScriptFix = opts.fix ? applyTypeScriptFix(root) : null;
+    // Re-read the declared range: `--fix` may have just rewritten it.
+    const declaredTypeScript = (() => {
+        const pkg = readJsonObject(path.join(root, 'package.json'));
+        if (pkg === null) return deps.typescript ?? null;
+        for (const field of ['devDependencies', 'dependencies'] as const) {
+            const range = asRecord(pkg[field])?.typescript;
+            if (typeof range === 'string') return range;
+        }
+        return null;
+    })();
+    const typeScriptCheck = checkTypeScript(
+        installedVersion(root, 'typescript'),
+        declaredTypeScript,
+    );
 
     // Server tooling (RPC wiring + the prettier plugin + the editor LS plugin): optionally fix in
     // place, then re-read.
@@ -784,19 +872,15 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     const serverTsParsed = serverTsPath ? readJsonObject(serverTsPath) : null;
     const serverTsPluginPresent =
         serverTsPath === null || serverTsParsed === null ? true : tsconfigHasToilPlugin(serverTsParsed);
+    // The typescript pin is fixable without a server; the rest only apply to one.
+    const applied = [typeScriptFix, rpcFix, prettierFix, editorFix].filter(
+        (fix): fix is RpcFixResult => fix !== null,
+    );
     const serverFix =
-        rpcFix || prettierFix || editorFix
+        applied.length > 0
             ? {
-                  changed: [
-                      ...(rpcFix?.changed ?? []),
-                      ...(prettierFix?.changed ?? []),
-                      ...(editorFix?.changed ?? []),
-                  ],
-                  skipped: [
-                      ...(rpcFix?.skipped ?? []),
-                      ...(prettierFix?.skipped ?? []),
-                      ...(editorFix?.skipped ?? []),
-                  ],
+                  changed: applied.flatMap((fix) => fix.changed),
+                  skipped: applied.flatMap((fix) => fix.skipped),
               }
             : null;
 
@@ -807,6 +891,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                 checkNode(process.versions.node, meta.node),
                 checkToiljsInstalled('toiljs' in deps ? version() : null),
                 ...peerChecks,
+                typeScriptCheck,
                 checkPackageManager(LOCKFILES.filter((f) => fs.existsSync(path.join(root, f)))),
             ],
         },
@@ -876,28 +961,21 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     } else {
         process.stdout.write('\n' + accent('  Doctor') + dim(`  ${root}`) + '\n\n');
         renderHuman(groups);
-        if (serverFix) renderRpcFix(serverFix);
-        else if (opts.fix && !serverPresent) {
-            process.stdout.write(
-                '  ' + dim('--fix: no server (toilconfig.json) found, nothing to wire.') + '\n\n',
-            );
-        }
+        if (serverFix) renderFix(serverFix);
     }
     if (hasFailures(summary)) process.exitCode = 1;
 }
 
-/** Prints the result of `--fix`, and whether a reinstall is needed (toilscript bump). */
-function renderRpcFix(result: RpcFixResult): void {
+/** Prints the result of `--fix`, and whether a reinstall is needed (a changed dependency range). */
+function renderFix(result: RpcFixResult): void {
     const out: string[] = [];
     if (result.changed.length > 0) {
-        out.push('  ' + success('fixed server wiring') + dim(`  ${result.changed.join(', ')}`));
-        if (result.changed.includes('package.json')) {
-            out.push(
-                '  ' + dim('run your installer (npm/pnpm/yarn) if the toilscript version changed.'),
-            );
+        out.push('  ' + success('fixed') + dim(`  ${result.changed.join(', ')}`));
+        if (result.changed.some((entry) => entry.startsWith('package.json'))) {
+            out.push('  ' + dim('run your installer (npm/pnpm/yarn) to apply the version changes.'));
         }
     } else {
-        out.push('  ' + dim('server wiring already in place, nothing to fix.'));
+        out.push('  ' + dim('nothing to fix.'));
     }
     for (const item of result.skipped) out.push('  ' + warn('skipped') + dim(`  ${item}`));
     process.stdout.write(out.join('\n') + '\n\n');

package/src/cli/update.ts

@@ -11,7 +11,7 @@ import { cancel, intro, isCancel, multiselect, note, outro, spinner } from '@cla
 
 import { MIGRATIONS_README } from './create.js';
 import { capture, run } from './proc.js';
-import { buildRows, type Bump, parseNcuJson, type UpdateRow } from './updates.js';
+import { buildRows, type Bump, parseNcuJson, type UpdateRow, withheldUpgrades } from './updates.js';
 import { accent, danger, dim, success, warn } from './ui.js';
 
 export interface UpdateOptions {
@@ -109,6 +109,20 @@ function rowLine(row: UpdateRow): string {
     return `${row.name}  ${dim(row.from)} ${dim('->')} ${bumpColor(row.bump, row.to)}`;
 }
 
+/** Tells the user which upgrades were held back, and why they are not simply missing. */
+function noteWithheld(names: readonly string[]): void {
+    note(
+        names.map((n) => `${dim('-')} ${n}`).join('\n') +
+            '\n\n' +
+            dim(
+                'Held back: this major is not supported by toiljs yet. TypeScript 7 is the native\n' +
+                    'port and ships no JavaScript compiler API, so route metadata would stop being\n' +
+                    'baked into the built HTML and typescript-eslint would not load.',
+            ),
+        warn('Not upgraded'),
+    );
+}
+
 const TARGETS = new Set(['latest', 'minor', 'patch', 'newest', 'greatest']);
 
 export async function runUpdate(opts: UpdateOptions): Promise<void> {
@@ -152,13 +166,21 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
         process.exitCode = 1;
         return;
     }
-    const rows = buildRows(parseNcuJson(res.stdout), currentDeps);
+    // Hold back upgrades into a major toiljs cannot run on (typescript 7), so neither the picker nor
+    // a `-y` run can install one. `--reject` keeps ncu from applying them during `-u` below.
+    const upgraded = parseNcuJson(res.stdout);
+    const withheld = withheldUpgrades(upgraded);
+    for (const name of withheld) delete upgraded[name];
+
+    const rows = buildRows(upgraded, currentDeps);
     if (rows.length === 0) {
         s.stop('Everything is up to date');
+        if (withheld.length > 0) noteWithheld(withheld);
         outro(success('Nothing to update.'));
         return;
     }
     s.stop(`${String(rows.length)} update${rows.length === 1 ? '' : 's'} available`);
+    if (withheld.length > 0) noteWithheld(withheld);
 
     const counts = { major: 0, minor: 0, patch: 0, other: 0 };
     for (const r of rows) counts[r.bump]++;
@@ -195,7 +217,12 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
 
     s.start('Updating package.json');
     const applyAll = selected.length === rows.length;
-    await run('npx', ncuArgs(applyAll ? ['-u'] : ['-u', '--filter', selected.join(' ')]), root);
+    const reject = withheld.length > 0 ? ['--reject', withheld.join(' ')] : [];
+    await run(
+        'npx',
+        ncuArgs(applyAll ? ['-u', ...reject] : ['-u', '--filter', selected.join(' '), ...reject]),
+        root,
+    );
     s.stop('package.json updated');
 
     // Run the install with VISIBLE output (so a failure is diagnosable — npm

package/src/cli/updates.ts

@@ -50,6 +50,29 @@ export function parseNcuJson(stdout: string): Record<string, string> {
     }
 }
 
+/**
+ * Majors `toiljs update` refuses to upgrade into, by package. TypeScript 7 is the native (Go) port:
+ * it ships `tsc` but no JavaScript compiler API, which toiljs's route-metadata extractor, the eslint
+ * preset, and typedoc all load. Upgrading into it silently stops SEO metadata being baked into the
+ * built HTML and hard-crashes typescript-eslint, so the upgrade is withheld until the ecosystem
+ * catches up. Bumps *within* the supported major are still offered.
+ */
+export const UNSUPPORTED_MAJOR: Readonly<Record<string, number>> = { typescript: 7 };
+
+/**
+ * The names ncu wants to upgrade into a major toiljs does not support (see {@link UNSUPPORTED_MAJOR}).
+ * These are dropped from the picker and passed to ncu's `--reject`, so `-u` cannot apply them either.
+ */
+export function withheldUpgrades(upgraded: Record<string, string>): string[] {
+    return Object.entries(upgraded)
+        .filter(([name, to]) => {
+            const ceiling = UNSUPPORTED_MAJOR[name];
+            return ceiling !== undefined && parseVersion(to)[0] >= ceiling;
+        })
+        .map(([name]) => name)
+        .sort();
+}
+
 const SEVERITY: Record<Bump, number> = { major: 0, minor: 1, patch: 2, other: 3 };
 
 /**

package/src/compiler/index.ts

@@ -308,9 +308,18 @@ export async function buildServer(root: string, auth: boolean = false): Promise<
         return;
     }
 
-    // Default request-only single-artifact path (no daemon/stream surface).
+    // Default request-only single-artifact path (no daemon/stream surface). Declare `hot` rather
+    // than leaving --targetMode off: with no explicit mode toilscript treats a source tree that
+    // declares no surface decorator as a plain AssemblyScript compile and omits `toil.surface`
+    // (to keep an ordinary AS build byte-identical). A toiljs server IS a Toil request artifact
+    // even before it grows its first `@rest`/`@data`, and the host refuses to load an artifact
+    // without that section, so a freshly scaffolded app would never deploy. `hot` is the mode the
+    // section already records for the default request artifact, so the bytes are unchanged for a
+    // project that has a surface; it only stops the section from going missing for one that
+    // doesn't. (`@daemon`/`@scheduled` are the only decorators `hot` rejects, and this branch runs
+    // exactly when the tree has neither.)
     await runToilscriptPass(root, binJs, files, {
-        mode: null,
+        mode: 'hot',
         outFile: null,
         withRpc: true,
         authUser: authOn,

package/src/compiler/pages.ts

@@ -1,13 +1,6 @@
-import { createRequire } from 'node:module';
-import path from 'node:path';
-
-import type * as TS from 'typescript';
-
-import { extractStaticExports } from './prerender.js';
+import { extractStaticExports, loadTypeScriptSync } from './prerender.js';
 import type { ScannedRoute } from './routes.js';
 
-type Ts = typeof TS;
-
 /**
  * A page in the build-time search index: its URL pattern, whether it's dynamic, and the
  * statically-extracted `metadata` literal (the searchable subset; dynamic `generateMetadata` and
@@ -20,20 +13,6 @@ export interface PageIndexEntry {
     readonly metadata: Record<string, unknown>;
 }
 
-/**
- * Loads the project's TypeScript synchronously (so {@link buildPageIndex} can run inside the sync
- * `generate()`), or `null` if it isn't installed, in which case pages are indexed by path only.
- */
-function loadTypeScriptSync(root: string): Ts | null {
-    try {
-        const require = createRequire(path.join(root, 'package.json'));
-        const mod = require('typescript') as { default?: Ts } & Ts;
-        return mod.default ?? mod;
-    } catch {
-        return null;
-    }
-}
-
 /** True when a route pattern has dynamic (`:param` / `*catch-all`) segments. */
 function isDynamic(pattern: string): boolean {
     return /[:*]/.test(pattern);

package/src/compiler/prerender.ts

@@ -12,15 +12,69 @@ import { injectSeoHtml, routeSeo } from './seo.js';
 
 type Ts = typeof TS;
 
-/** Loads the project's TypeScript (used to read each route's static `metadata`), or `null` if absent. */
+/**
+ * True when `mod` exposes the classic TypeScript compiler API the static extractor drives.
+ *
+ * Resolving `typescript` is not enough to know it can parse: TypeScript 7 (the native port) moved
+ * the compiler API off the package's main entry, which now exports only `version`. That module is a
+ * perfectly good object, so a truthy check passes and the first `ts.ScriptTarget.Latest` then dies
+ * with `Cannot read properties of undefined (reading 'Latest')`. Probe the members we actually use.
+ */
+function isCompilerApi(mod: unknown): mod is Ts {
+    const ts = mod as Partial<Ts> | null | undefined;
+    return (
+        typeof ts?.createSourceFile === 'function' &&
+        typeof ts.isVariableStatement === 'function' &&
+        typeof ts.ScriptTarget === 'object' &&
+        typeof ts.ScriptKind === 'object' &&
+        typeof ts.SyntaxKind === 'object'
+    );
+}
+
+/** Warn once per process: an unusable TypeScript silently costs baked metadata, so say so. */
+let warnedUnusable = false;
+function warnUnusableTypeScript(mod: unknown): void {
+    if (warnedUnusable) return;
+    warnedUnusable = true;
+    const version = (mod as { version?: string } | null)?.version;
+    process.stderr.write(
+        `  toil: typescript${version ? `@${version}` : ''} does not expose the compiler API ` +
+            `(TypeScript 7 moved it to 'typescript/unstable/*').\n` +
+            `  toil: route metadata will NOT be baked into the built HTML. Install typescript ^6 to restore it.\n`,
+    );
+}
+
+/**
+ * Resolves the project's TypeScript, used to read each route's static `metadata`. Returns `null`
+ * when it isn't installed (callers then index pages by path only) *or* when the resolved version
+ * doesn't expose the compiler API, which is warned about rather than crashing the build.
+ */
 export async function loadTypeScript(root: string): Promise<Ts | null> {
+    let mod: unknown;
     try {
         const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
-        const mod = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
-        return mod.default ?? mod;
+        const ns = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
+        mod = ns.default ?? ns;
+    } catch {
+        return null;
+    }
+    if (isCompilerApi(mod)) return mod;
+    warnUnusableTypeScript(mod);
+    return null;
+}
+
+/** The sync twin of {@link loadTypeScript}, for callers that can't await (e.g. `buildPageIndex`). */
+export function loadTypeScriptSync(root: string): Ts | null {
+    let mod: unknown;
+    try {
+        mod = createRequire(path.join(root, 'package.json'))('typescript');
     } catch {
         return null;
     }
+    const ts = (mod as { default?: Ts })?.default ?? mod;
+    if (isCompilerApi(ts)) return ts;
+    warnUnusableTypeScript(ts);
+    return null;
 }
 
 /** Marks an AST node that isn't a static literal (so its value can't be baked at build). */