docs: update tw5-typed setup guidance

Author: linonetwo

README.md

@@ -35,4 +35,24 @@ Don't worry, even if you are not good at programming, it doesn't matter, Modern.
 
 There's a lot of work here, but it's just Out-of-the-Box for you. Use it and get started on your modern TiddlyWiki plugin development journey!
 
+## TypeScript Setup
+
+Modern.TiddlyDev now loads [tw5-typed](https://github.com/tiddly-gittly/TW5-Typed) in the supported way:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "tw5-typed"]
+  }
+}
+```
+
+And the template keeps a project ambient entry in `src/global.d.ts`:
+
+```typescript
+/// <reference types="tw5-typed" />
+```
+
+This makes both `import type { ... } from 'tiddlywiki'` and the global `$tw` available to TypeScript and VS Code. Do not put `tw5-typed` into `typeRoots`; it is a normal package with its own `types` entry, and using `typeRoots` there can stop the editor from resolving the declarations correctly.
+
 ![](src/doc/wysiwyg-demo.gif)

package.json

@@ -47,7 +47,7 @@
     "postcss": "^8.5.6",
     "rimraf": "^6.1.0",
     "ts-node": "^10.9.2",
-    "tw5-typed": "^0.6.8",
+    "tw5-typed": "^1.1.4",
     "typescript": "^5.9.3"
   },
   "dependencies": {

pnpm-lock.yaml

@@ -13,6 +13,24 @@ A widget is a rendering unit for <$text text="TiddlyWiki" />, which is what you
 
 We want to create a wdiget that displays a random number and re-randomizes it when clicked, and we name this widget <$text text="RandomNumber" />. To achieve this, we add a `RandomNumberWidget.ts` file and a `RandomNumberWidget.ts.meta` file to the plugin development directory.
 
+Before writing widget code, make sure the project loads [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]] in the supported way. In `tsconfig.json`, use:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "tw5-typed"]
+  }
+}
+```
+
+And in `src/global.d.ts`, keep an ambient entry like:
+
+```typescript
+/// <reference types="tw5-typed" />
+```
+
+This gives you both `import type { ... } from 'tiddlywiki'` and the global `$tw` in VS Code. Do not use `typeRoots` for `tw5-typed`; that can cause the editor to lose the `tiddlywiki` module declaration.
+
 First write the following in `RandomNumberWidget.ts.meta`;
 
 ```yaml
@@ -55,7 +73,7 @@ Execute `pnpm run dev` to compile the source file, open a browser, create a tidd
 
 Note: The framework also supports compilation of cjs, mjs, jsx, tsx files.
 
-Note: The related <$text text="TypeScript" /> type support is done by [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]], which is not very complete, so some manual type annotations are needed as above. I welcome your help to improve tw5-typed!
+Note: The related <$text text="TypeScript" /> type support is done by [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]]. It already provides the `tiddlywiki` module and global `$tw`, but TiddlyWiki's API surface is huge, so you will still occasionally need explicit annotations in your own code. Improvements to tw5-typed are always welcome.
 
 ! Importing other resources in <$text text="TypeScript" /> scripts
 

src/doc/tutorials/en/003-typescript-dev.tid

@@ -15,6 +15,24 @@ widget 是 <$text text="TiddlyWiki" /> 的渲染单位，也就是你看到的
 
 我们希望创建这样一个 wdiget：其显示一个随机数字，并在点击其时重新随机，我们把这个 widget 其名为 <$text text="RandomNumber" />。为了达到这样的目的，我们在插件开发目录下添加一个 `RandomNumberWidget.ts` 文件和 `RandomNumberWidget.ts.meta` 文件。
 
+在写 Widget 代码前，先确保项目用正确方式加载了 [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]]。在 `tsconfig.json` 里应当使用：
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "tw5-typed"]
+  }
+}
+```
+
+并且在 `src/global.d.ts` 里保留一个环境声明入口：
+
+```typescript
+/// <reference types="tw5-typed" />
+```
+
+这样 VS Code 才能稳定拿到 `import type { ... } from 'tiddlywiki'` 以及全局 `$tw` 的类型。不要把 `tw5-typed` 写进 `typeRoots`，否则编辑器有可能反而丢失 `tiddlywiki` 的模块声明。
+
 首先在 `RandomNumberWidget.ts.meta` 中写如下内容;
 
 ```yaml
@@ -57,7 +75,7 @@ exports.random = RandomNumber;
 
 注：框架同时也支持对 cjs、mjs、jsx、tsx 文件的编译。
 
-注：相关 <$text text="TypeScript" /> 类型支持是由 [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]] 完成的，由于完成度不高，所以需要像上面一样，做一些手动的类型注解。欢迎各位大佬帮忙完善 tw5-typed ！
+注：相关 <$text text="TypeScript" /> 类型支持由 [[tw5-typed|https://github.com/tiddly-gittly/TW5-Typed]] 提供。它已经提供了 `tiddlywiki` 模块和全局 `$tw`，但 TiddlyWiki 的 API 面很大，所以在自己的代码里偶尔仍然需要补一些显式类型注解。也欢迎继续完善 tw5-typed。
 
 ! 在 <$text text="TypeScript" /> 脚本中导入其他资源
 

src/doc/tutorials/zh/003-typescript-dev.tid

@@ -1,3 +1,5 @@
+/// <reference types="tw5-typed" />
+
 declare module '*.css' {
   const content: string;
   export default content;

src/global.d.ts

@@ -5,7 +5,7 @@
     "jsx": "react-jsx",
     "baseUrl": "./",
     "noEmit": true,
-    "typeRoots": ["node_modules/@types", "node_modules/tw5-typed"],
+    "types": ["node", "tw5-typed"],
     "lib": ["DOM", "ESNext"]
   },
   "include": ["src", "*.json", "wiki/*.info", "*.mjs", "*.js", "src/**/*.d.ts"]