fix(docs): isolate TypeScript compiler API

Author: ScriptedAlchemy

.github/dependabot.yml

@@ -12,17 +12,6 @@ updates:
       rspress:
         patterns:
           - '@rspress/*'
-    ignore:
-      # typescript@7.0.x is a native compiler: import('typescript') is only
-      # { version, versionMajorMinor }. website/rspress.config.ts,
-      # @rspress/plugin-twoslash@2.0.21 (peer ^6.0.3 -> twoslash@0.3.9 peer
-      # ^5.5.0 || ^6.0.0), and typedoc@0.28.20 (peer 5.0.x–6.0.x;
-      # TypeStrong/typedoc#3098 targets TS 7.1) all need the JS compiler API
-      # and crash on 7.0.2. Root tsc is already 7.0.2; website stays on
-      # 6.0.3. Drop this ignore when TypeDoc and twoslash support TS 7.
-      - dependency-name: typescript
-        update-types:
-          - version-update:semver-major
   - package-ecosystem: github-actions
     # `/` covers .github/workflows/*; the composite actions under
     # .github/actions/* (where pnpm/setup lives) are separate directories.

.pnpmfile.cjs

@@ -0,0 +1,22 @@
+const typescriptApiConsumers = new Set([
+  '@rspress/plugin-twoslash',
+  '@rspress/plugin-typedoc',
+  '@shikijs/twoslash',
+  'twoslash',
+  'typedoc',
+]);
+
+function readPackage(pkg) {
+  if (!typescriptApiConsumers.has(pkg.name)) {
+    return pkg;
+  }
+  // Keep JavaScript-API consumers isolated from the website's native TypeScript 7 peer.
+  pkg.dependencies ??= {};
+  pkg.dependencies.typescript = pkg.peerDependencies?.typescript ?? '*';
+  if (pkg.peerDependencies) {
+    delete pkg.peerDependencies.typescript;
+  }
+  return pkg;
+}
+
+module.exports = { hooks: { readPackage } };

docs/effect-conventions.md

@@ -11,7 +11,7 @@ docs, or examples' user code. The four-concept newcomer ledger is untouched.
 | --- | --- |
 | npm `effect` | **`4.0.0-rc.112`** (exact). Latest published `rc` dist-tag on 2026-09-01. The Wave 3.5 brief named `4.0.0-rc.113`; that version was not on the registry. Re-pin chores take the next published RC. |
 | Vendored tree | `repos/effect` via `git subtree` from [Effect-TS/effect](https://github.com/Effect-TS/effect.git) `main` (v4). Squash commit tracks `packages/effect` version **4.0.0-rc.112**. |
-| `website` `typescript` | **`6.0.3`**, behind the root's TypeScript 7, because `typedoc@0.28` peers on `<= 6.0.x`. TypeDoc compiles the built `packages/agent-bundle/dist` declarations with it, while Twoslash compiles documentation samples against package source. Re-pin chores check whether a newer `typedoc` lifts the ceiling. |
+| `website` TypeScript | Native **`7.0.2`** runs `tsc`; the `typescript-6` alias stays on **`6.0.3`** for TypeDoc, Twoslash, and `rspress.config.ts` compiler-API calls. `.pnpmfile.cjs` turns those plugins' TypeScript peers into dependencies, and the scoped overrides in `pnpm-workspace.yaml` isolate them from TypeScript 7. Re-pin chores update the alias and overrides together. |
 
 Application code imports the npm package. Never import from `repos/**`.
 

pnpm-lock.yaml

@@ -12,7 +12,12 @@ packages:
 # this checkout is about to publish.
 overrides:
   '@agent-bundle/runtime': workspace:*
+  '@rspress/plugin-twoslash>typescript': npm:typescript@6.0.3
+  '@rspress/plugin-typedoc>typescript': npm:typescript@6.0.3
+  '@shikijs/twoslash>typescript': npm:typescript@6.0.3
   rsc-markdown-stream: workspace:*
+  'twoslash>typescript': npm:typescript@6.0.3
+  'typedoc>typescript': npm:typescript@6.0.3
 allowBuilds:
   '@google/genai': false
   msgpackr-extract: false

pnpm-workspace.yaml

@@ -30,7 +30,8 @@
     "@types/react": "19.2.18",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "typescript": "6.0.3",
+    "typescript": "7.0.2",
+    "typescript-6": "npm:typescript@6.0.3",
     "zod": "4.5.4"
   }
 }

website/package.json

@@ -4,7 +4,7 @@ import { pluginLlms } from '@rspress/plugin-llms';
 import { pluginTwoslash } from '@rspress/plugin-twoslash';
 import { pluginTypeDoc } from '@rspress/plugin-typedoc';
 import { transformerNotationHighlight } from '@shikijs/transformers';
-import ts from 'typescript';
+import ts from 'typescript-6';
 import { generatedReference } from './plugins/generated-reference.ts';
 import { cleanGeneratedApiMarkdown, mirrorApiLocale } from './plugins/mirror-api-locale.ts';
 import { rehypeTableCellBreaks } from './plugins/rehype-table-cell-breaks.ts';
@@ -192,8 +192,8 @@ export default defineConfig({
   plugins: [
     // TypeDoc reads packages/agent-bundle/dist declarations produced by the
     // package build. Twoslash still compiles documentation samples against
-    // package sources. Both use the TypeScript 6 pin in website/package.json
-    // because typedoc 0.28 peers on `<= 6.0.x`.
+    // package sources. Both use the JavaScript compiler API from the
+    // `typescript-6` alias; the website's `typescript` dependency is native.
     pluginTypeDoc({
       entryPoints: publicApiEntryPoints,
       outDir: generatedApiDir,