From 602e5eacd5e787ff230162717da1baa71b57060b Mon Sep 17 00:00:00 2001
From: lin onetwo <linonetwo012@gmail.com>
Date: Tue, 20 Aug 2024 21:23:13 +0800
Subject: [PATCH 01/16] feat: add example

---
 .../parsers/wikiparser/rules/codeblock.js     | 34 ++++++++++++++++++-
 core/modules/parsers/wikiparser/try.js        | 15 ++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 core/modules/parsers/wikiparser/try.js

diff --git a/core/modules/parsers/wikiparser/rules/codeblock.js b/core/modules/parsers/wikiparser/rules/codeblock.js
index 6c3480566b9..3dddba89421 100644
--- a/core/modules/parsers/wikiparser/rules/codeblock.js
+++ b/core/modules/parsers/wikiparser/rules/codeblock.js
@@ -1,4 +1,5 @@
-/*\
+// @ts-check
+/**
 title: $:/core/modules/parsers/wikiparser/rules/codeblock.js
 type: application/javascript
 module-type: wikirule
@@ -11,7 +12,28 @@ Wiki text rule for code blocks. For example:
 	```
 ```
 
+@module $:/core/modules/parsers/wikiparser/rules/codeblock.js
+
 \*/
+
+/**
+ * Represents the `codeblock` rule.
+ * 
+ * @typedef {Object} CodeblockNode
+ * @property {string} type - The type of the widget, which is "codeblock".
+ * @property {Object} attributes - The attributes of the codeblock.
+ * @property {Object} attributes.code - The code attribute object.
+ * @property {string} attributes.code.type - The type of the code attribute, which is "string".
+ * @property {string} attributes.code.value - The actual code content within the code block.
+ * @property {number} attributes.code.start - The start position of the code in the source text.
+ * @property {number} attributes.code.end - The end position of the code in the source text.
+ * @property {Object} attributes.language - The language attribute object.
+ * @property {string} attributes.language.type - The type of the language attribute, which is "string".
+ * @property {string} attributes.language.value - The language specified after the triple backticks, if any.
+ * @property {number} attributes.language.start - The start position of the language string in the source text.
+ * @property {number} attributes.language.end - The end position of the language string in the source text.
+ */
+
 (function(){
 
 /*jslint node: true, browser: true */
@@ -21,12 +43,22 @@ Wiki text rule for code blocks. For example:
 exports.name = "codeblock";
 exports.types = {block: true};
 
+/**
+ * Initializes the codeblock rule with the given parser.
+ * 
+ * @param {Object} parser - The parser object that manages the state of the parsing process.
+ */
 exports.init = function(parser) {
 	this.parser = parser;
 	// Regexp to match and get language if defined
 	this.matchRegExp = /```([\w-]*)\r?\n/mg;
 };
 
+/**
+ * Parses the code block and returns an array of `codeblock` widgets.
+ * 
+ * @returns {CodeblockNode[]} An array containing a single codeblock widget object.
+ */
 exports.parse = function() {
 	var reEnd = /(\r?\n```$)/mg;
 	var languageStart = this.parser.pos + 3,
diff --git a/core/modules/parsers/wikiparser/try.js b/core/modules/parsers/wikiparser/try.js
new file mode 100644
index 00000000000..f04bfe29687
--- /dev/null
+++ b/core/modules/parsers/wikiparser/try.js
@@ -0,0 +1,15 @@
+// @ts-check
+/**
+ * @typedef {import('./rules/codeblock').CodeblockNode} CodeblockNode
+ */
+
+/**
+ * A function that processes a code block.
+ * 
+ * @param {CodeblockNode[]} codeblocks - An array of codeblock rules.
+ */
+function processCodeblocks(codeblocks) {
+	codeblocks.forEach(function(cb) {
+			console.log(cb.attributes.code.value);
+	});
+}

From 270aeba8ff12653ab32583ebe2ef105c0848592a Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Wed, 4 Sep 2024 18:56:29 +0800
Subject: [PATCH 02/16] chore: add ts file so tsc --noEmit works

---
 core/globals.d.ts |  1 +
 tsconfig.json     | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 core/globals.d.ts
 create mode 100644 tsconfig.json

diff --git a/core/globals.d.ts b/core/globals.d.ts
new file mode 100644
index 00000000000..1c5abfbb1fc
--- /dev/null
+++ b/core/globals.d.ts
@@ -0,0 +1 @@
+declare var $tw: any;
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 00000000000..852b3049193
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "paths": {       // Add paths
+      "$:/core/*": ["./core/*"]
+    },
+    "noImplicitAny": false,
+    "strict": false,
+
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "checkJs": true,
+    "declaration": true,
+    "declarationDir": "types",
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "Node16",
+    "outDir": "silences wrong TS error, we don't compile, we only typecheck",
+    "rootDir": "core",
+    "skipLibCheck": true,
+    "target": "ESNext"
+  },
+  "include": ["./core/**/*.js", "**/*.d.ts"]
+}

From 492d812ce0bbbcea131f02ce93e323e1144706e8 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 10:24:11 +0800
Subject: [PATCH 03/16] refactor: remove // @ts-check

---
 core/modules/parsers/wikiparser/rules/codeblock.js | 1 -
 core/modules/parsers/wikiparser/try.js             | 1 -
 2 files changed, 2 deletions(-)

diff --git a/core/modules/parsers/wikiparser/rules/codeblock.js b/core/modules/parsers/wikiparser/rules/codeblock.js
index 3dddba89421..74b67e75187 100644
--- a/core/modules/parsers/wikiparser/rules/codeblock.js
+++ b/core/modules/parsers/wikiparser/rules/codeblock.js
@@ -1,4 +1,3 @@
-// @ts-check
 /**
 title: $:/core/modules/parsers/wikiparser/rules/codeblock.js
 type: application/javascript
diff --git a/core/modules/parsers/wikiparser/try.js b/core/modules/parsers/wikiparser/try.js
index f04bfe29687..459c7b074ed 100644
--- a/core/modules/parsers/wikiparser/try.js
+++ b/core/modules/parsers/wikiparser/try.js
@@ -1,4 +1,3 @@
-// @ts-check
 /**
  * @typedef {import('./rules/codeblock').CodeblockNode} CodeblockNode
  */

From ac308e0f899c92172e5dea54db228535b66cbd60 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 15:14:45 +0800
Subject: [PATCH 04/16] feat: Allow `import('$:/core/modules/...')` instead of
 `import('../../core/modules/...')`. Only works inside this project.

---
 core/modules/parsers/wikiparser/rules/codeblock.js | 4 +---
 core/modules/parsers/wikiparser/try.js             | 2 +-
 tsconfig.json                                      | 7 ++++---
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/core/modules/parsers/wikiparser/rules/codeblock.js b/core/modules/parsers/wikiparser/rules/codeblock.js
index 74b67e75187..507ca424ffb 100644
--- a/core/modules/parsers/wikiparser/rules/codeblock.js
+++ b/core/modules/parsers/wikiparser/rules/codeblock.js
@@ -1,4 +1,4 @@
-/**
+/*\
 title: $:/core/modules/parsers/wikiparser/rules/codeblock.js
 type: application/javascript
 module-type: wikirule
@@ -11,8 +11,6 @@ Wiki text rule for code blocks. For example:
 	```
 ```
 
-@module $:/core/modules/parsers/wikiparser/rules/codeblock.js
-
 \*/
 
 /**
diff --git a/core/modules/parsers/wikiparser/try.js b/core/modules/parsers/wikiparser/try.js
index 459c7b074ed..535cc959850 100644
--- a/core/modules/parsers/wikiparser/try.js
+++ b/core/modules/parsers/wikiparser/try.js
@@ -1,5 +1,5 @@
 /**
- * @typedef {import('./rules/codeblock').CodeblockNode} CodeblockNode
+ * @typedef {import('$:/core/modules/parsers/wikiparser/rules/codeblock.js').CodeblockNode} CodeblockNode
  */
 
 /**
diff --git a/tsconfig.json b/tsconfig.json
index 852b3049193..37824723195 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
-    "paths": {       // Add paths
+    "paths": {
+      // Allow `import('$:/core/modules/...')` instead of `import('../../core/modules/...')`. Only works inside this project.
       "$:/core/*": ["./core/*"]
     },
     "noImplicitAny": false,
@@ -12,10 +13,10 @@
     "declaration": true,
     "declarationDir": "types",
     "declarationMap": true,
-    "emitDeclarationOnly": false,
+    "emitDeclarationOnly": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "Node16",
-    "outDir": "silences wrong TS error, we don't compile, we only typecheck",
+    "outDir": "types",
     "rootDir": "core",
     "skipLibCheck": true,
     "target": "ESNext"

From b6f219aa82b4c934ea6817e8d4893eabbc1c55b9 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 16:13:59 +0800
Subject: [PATCH 05/16] feat: make $tw.wiki globally available

---
 .gitignore           | 1 +
 core/globals.d.ts    | 1 -
 core/modules/wiki.js | 7 +++++++
 package.json         | 1 +
 tsconfig.json        | 9 +++++----
 types/tw.d.ts        | 7 +++++++
 6 files changed, 21 insertions(+), 5 deletions(-)
 delete mode 100644 core/globals.d.ts
 create mode 100644 types/tw.d.ts

diff --git a/.gitignore b/.gitignore
index 412759161ed..07f080e2654 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ node_modules/
 /playwright-report/
 /playwright/.cache/
 $__StoryList.tid
+types/generated/
diff --git a/core/globals.d.ts b/core/globals.d.ts
deleted file mode 100644
index 1c5abfbb1fc..00000000000
--- a/core/globals.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-declare var $tw: any;
diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index 5673c9e3baa..587ca8cadc0 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -22,6 +22,13 @@ Adds the following properties to the wiki object:
 /*global $tw: false */
 "use strict";
 
+/**
+ * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
+ */
+
+/**
+ * @type {Widget}
+ */
 var widget = require("$:/core/modules/widgets/widget.js");
 
 var USER_NAME_TITLE = "$:/status/UserName",
diff --git a/package.json b/package.json
index 4dbd390878c..5be4b5799be 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
   "bin": {
     "tiddlywiki": "./tiddlywiki.js"
   },
+  "types": "./types",
   "main": "./boot/boot.js",
   "repository": {
     "type": "git",
diff --git a/tsconfig.json b/tsconfig.json
index 37824723195..0988bf8aa27 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,15 +11,16 @@
     "allowSyntheticDefaultImports": true,
     "checkJs": true,
     "declaration": true,
-    "declarationDir": "types",
+    "declarationDir": "types/generated",
     "declarationMap": true,
     "emitDeclarationOnly": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "Node16",
-    "outDir": "types",
-    "rootDir": "core",
+    "outDir": "types/generated",
+    "rootDir": ".",
     "skipLibCheck": true,
     "target": "ESNext"
   },
-  "include": ["./core/**/*.js", "**/*.d.ts"]
+  "include": ["./core/**/*.js", "./core/**/*.d.ts", "types/tw.d.ts"],
+  "exclude": ["types/generated"]
 }
diff --git a/types/tw.d.ts b/types/tw.d.ts
new file mode 100644
index 00000000000..b0477dde30c
--- /dev/null
+++ b/types/tw.d.ts
@@ -0,0 +1,7 @@
+import * as Wiki from '../core/modules/wiki';
+
+declare global {
+  var $tw: {
+    wiki: typeof Wiki;
+  };
+}

From a5feb38496c2598a5ee64ae4dde2c8261ddd711e Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 16:15:35 +0800
Subject: [PATCH 06/16] feat: add an example jsdoc to $tw.wiki.getTiddlerText

---
 core/modules/wiki.js | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index 587ca8cadc0..e6765ebf8ce 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1494,9 +1494,13 @@ exports.search = function(text,options) {
 	return results;
 };
 
-/*
-Trigger a load for a tiddler if it is skinny. Returns the text, or undefined if the tiddler is missing, null if the tiddler is being lazily loaded.
-*/
+/**
+ * Trigger a load for a tiddler if it is skinny. Returns the text, or undefined if the tiddler is missing, null if the tiddler is being lazily loaded.
+ *
+ * @param {string} title - The title of the tiddler.
+ * @param {string} [defaultText] - The default text to return if the tiddler is missing.
+ * @returns {string | null | undefined} - The text of the tiddler, undefined if the tiddler is missing, or null if the tiddler is being lazily loaded.
+ */
 exports.getTiddlerText = function(title,defaultText) {
 	var tiddler = this.getTiddler(title);
 	// Return undefined if the tiddler isn't found

From c5304b4be660c385700d44df249f1474f9d6a552 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 18:44:18 +0800
Subject: [PATCH 07/16] fix: Declaration emit for this file requires using
 private name 'Widget'. An explicit type annotation may unblock declaration
 emit.

---
 core/modules/parsers/wikiparser/try.js        | 14 -----
 core/modules/parsers/wikiparser/wikiparser.js | 31 ++++++-----
 core/modules/widgets/widget.js                | 43 +++++++++------
 core/modules/wiki.js                          | 54 +++++++++++--------
 package.json                                  |  2 +-
 5 files changed, 79 insertions(+), 65 deletions(-)
 delete mode 100644 core/modules/parsers/wikiparser/try.js

diff --git a/core/modules/parsers/wikiparser/try.js b/core/modules/parsers/wikiparser/try.js
deleted file mode 100644
index 535cc959850..00000000000
--- a/core/modules/parsers/wikiparser/try.js
+++ /dev/null
@@ -1,14 +0,0 @@
-/**
- * @typedef {import('$:/core/modules/parsers/wikiparser/rules/codeblock.js').CodeblockNode} CodeblockNode
- */
-
-/**
- * A function that processes a code block.
- * 
- * @param {CodeblockNode[]} codeblocks - An array of codeblock rules.
- */
-function processCodeblocks(codeblocks) {
-	codeblocks.forEach(function(cb) {
-			console.log(cb.attributes.code.value);
-	});
-}
diff --git a/core/modules/parsers/wikiparser/wikiparser.js b/core/modules/parsers/wikiparser/wikiparser.js
index 854171d197f..fe4d8f8f75f 100644
--- a/core/modules/parsers/wikiparser/wikiparser.js
+++ b/core/modules/parsers/wikiparser/wikiparser.js
@@ -25,16 +25,20 @@ Attributes are stored as hashmaps of the following objects:
 /*global $tw: false */
 "use strict";
 
-/*
-type: content type of text
-text: text to be parsed
-options: see below:
-	parseAsInline: true to parse text as inline instead of block
-	wiki: reference to wiki to use
-	_canonical_uri: optional URI of content if text is missing or empty
-	configTrimWhiteSpace: true to trim whitespace
-*/
-var WikiParser = function(type,text,options) {
+/**
+ * WikiParser class for parsing text of a specified MIME type.
+ * 
+ * @class
+ * @constructor
+ * @param {string} type - The content type of the text to be parsed.
+ * @param {string} text - The text to be parsed.
+ * @param {Object} options - Options for parsing.
+ * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
+ * @param {Object} options.wiki - Reference to the wiki to use.
+ * @param {string} [options._canonical_uri] - Optional URI of the content if the text is missing or empty.
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ */
+function WikiParser(type,text,options) {
 	this.wiki = options.wiki;
 	var self = this;
 	// Check for an externally linked tiddler
@@ -99,8 +103,11 @@ var WikiParser = function(type,text,options) {
 	// Return the parse tree
 };
 
-/*
-*/
+/**
+ * Load a remote tiddler from a given URL.
+ * 
+ * @param {string} url - The URL of the remote tiddler to load.
+ */
 WikiParser.prototype.loadRemoteTiddler = function(url) {
 	var self = this;
 	$tw.utils.httpRequest({
diff --git a/core/modules/widgets/widget.js b/core/modules/widgets/widget.js
index eb84fab4a8e..5759312c76d 100755
--- a/core/modules/widgets/widget.js
+++ b/core/modules/widgets/widget.js
@@ -12,22 +12,30 @@ Widget base class
 /*global $tw: false */
 "use strict";
 
-/*
-Create a widget object for a parse tree node
-	parseTreeNode: reference to the parse tree node to be rendered
-	options: see below
-Options include:
-	wiki: mandatory reference to wiki associated with this render tree
-	parentWidget: optional reference to a parent renderer node for the context chain
-	document: optional document object to use instead of global document
-*/
-var Widget = function(parseTreeNode,options) {
+/**
+ * Widget class for creating a widget object for a parse tree node.
+ * 
+ * @class
+ * @constructor
+ * @param {Object} parseTreeNode - Reference to the parse tree node to be rendered.
+ * @param {Object} options - Options for the widget.
+ * @param {Object} options.wiki - Mandatory reference to the wiki associated with this render tree.
+ * @param {Widget} [options.parentWidget] - Optional reference to a parent renderer node for the context chain.
+ * @param {Document} [options.document] - Optional document object to use instead of the global document.
+ */
+function Widget(parseTreeNode,options) {
 	this.initialise(parseTreeNode,options);
 };
 
-/*
-Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses
-*/
+/**
+ * Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses.
+ * 
+ * @param {Object} parseTreeNode - Reference to the parse tree node to be rendered.
+ * @param {Object} options - Options for the widget.
+ * @param {Object} options.wiki - Mandatory reference to the wiki associated with this render tree.
+ * @param {Widget} [options.parentWidget] - Optional reference to a parent renderer node for the context chain.
+ * @param {Document} [options.document] - Optional document object to use instead of the global document.
+ */
 Widget.prototype.initialise = function(parseTreeNode,options) {
 	// Bail if parseTreeNode is undefined, meaning  that the widget constructor was called without any arguments so that it can be subclassed
 	if(parseTreeNode === undefined) {
@@ -64,9 +72,12 @@ Widget.prototype.initialise = function(parseTreeNode,options) {
 	}
 };
 
-/*
-Render this widget into the DOM
-*/
+/**
+ * Render this widget into the DOM.
+ * 
+ * @param {Element} parent - The parent DOM node to render into.
+ * @param {Element} nextSibling - The next sibling DOM node to render before.
+ */
 Widget.prototype.render = function(parent,nextSibling) {
 	this.parentDomNode = parent;
 	this.execute();
diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index e6765ebf8ce..e530011c809 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
+ * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
+ */
+
 /*\
 title: $:/core/modules/wiki.js
 type: application/javascript
@@ -22,10 +27,6 @@ Adds the following properties to the wiki object:
 /*global $tw: false */
 "use strict";
 
-/**
- * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
- */
-
 /**
  * @type {Widget}
  */
@@ -1048,19 +1049,26 @@ exports.initParsers = function(moduleType) {
 	}
 };
 
-/*
-Parse a block of text of a specified MIME type
-	type: content type of text to be parsed
-	text: text
-	options: see below
-Options include:
-	parseAsInline: if true, the text of the tiddler will be parsed as an inline run
-	_canonical_uri: optional string of the canonical URI of this content
-*/
+/**
+ * Parse a block of text of a specified MIME type.
+ * 
+ * @param {string} type - The content type of the text to be parsed.
+ * @param {string} text - The text to be parsed.
+ * @param {Object} [options] - Options for parsing.
+ * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
+ * @param {string} [options._canonical_uri] - Optional string of the canonical URI of this content.
+ * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - The default type to use if no parser is found for the specified type.
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ * 
+ * @returns {WikiParser|null} The parser instance or null if no parser is found.
+ */
 exports.parseText = function(type,text,options) {
 	text = text || "";
 	options = options || {};
-	// Select a parser
+	/**
+	 * @type WikiParser
+	 * Select a parser
+	 */
 	var Parser = $tw.Wiki.parsers[type];
 	if(!Parser && $tw.utils.getFileExtensionInfo(type)) {
 		Parser = $tw.Wiki.parsers[$tw.utils.getFileExtensionInfo(type).type];
@@ -1150,14 +1158,16 @@ exports.getTextReferenceParserInfo = function(title,field,index,options) {
 	return parserInfo;
 }
 
-/*
-Parse a block of text of a specified MIME type
-	text: text on which to perform substitutions
-	widget
-	options: see below
-Options include:
-	substitutions: an optional array of substitutions
-*/
+/**
+ * Parse a block of text of a specified MIME type and perform substitutions.
+ * 
+ * @param {string} text - The text on which to perform substitutions.
+ * @param {Widget} widget - The widget context used for variable substitution.
+ * @param {Object} [options] - Options for substitutions.
+ * @param {Array<{name: string, value: string}>} [options.substitutions] - An optional array of substitutions.
+ * 
+ * @returns {string} The text with substitutions applied.
+ */
 exports.getSubstitutedText = function(text,widget,options) {
 	options = options || {};
 	text = text || "";
diff --git a/package.json b/package.json
index 5be4b5799be..d036a46c66c 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
   "bin": {
     "tiddlywiki": "./tiddlywiki.js"
   },
-  "types": "./types",
+  "types": "./types/tw.d.ts",
   "main": "./boot/boot.js",
   "repository": {
     "type": "git",

From 43eff4eb3a55a7b962ad61de45f810210a427d1b Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Tue, 10 Sep 2024 19:32:38 +0800
Subject: [PATCH 08/16] fix: duplication of types

---
 core/modules/wiki.js | 43 +++++++++++++++++--------------------------
 1 file changed, 17 insertions(+), 26 deletions(-)

diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index e530011c809..4f48c252c49 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1,8 +1,3 @@
-/**
- * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
- * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
- */
-
 /*\
 title: $:/core/modules/wiki.js
 type: application/javascript
@@ -21,16 +16,8 @@ Adds the following properties to the wiki object:
 * `globalCache` is a hashmap by cache name of cache objects that are cleared whenever any tiddler change occurs
 
 \*/
-(function(){
 
-/*jslint node: true, browser: true */
-/*global $tw: false */
-"use strict";
-
-/**
- * @type {Widget}
- */
-var widget = require("$:/core/modules/widgets/widget.js");
+var Widget = require("$:/core/modules/widgets/widget.js").widget;
 
 var USER_NAME_TITLE = "$:/status/UserName",
 	TIMESTAMP_DISABLE_TITLE = "$:/config/TimestampDisable";
@@ -1049,6 +1036,10 @@ exports.initParsers = function(moduleType) {
 	}
 };
 
+/**
+ * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
+ */
+
 /**
  * Parse a block of text of a specified MIME type.
  * 
@@ -1188,15 +1179,17 @@ exports.getSubstitutedText = function(text,widget,options) {
 	});
 };
 
-/*
-Make a widget tree for a parse tree
-parser: parser object
-options: see below
-Options include:
-document: optional document to use
-variables: hashmap of variables to set
-parentWidget: optional parent widget for the root node
-*/
+/**
+ * Create a widget tree for a parse tree.
+ * 
+ * @param {Object} parser - The parser object containing the parse tree.
+ * @param {Object} [options] - Options for creating the widget tree.
+ * @param {Document} [options.document] - Optional document to use.
+ * @param {Object} [options.variables] - Hashmap of variables to set.
+ * @param {Widget} [options.parentWidget] - Optional parent widget for the root node.
+ * 
+ * @returns {Widget} The root widget of the created widget tree.
+ */
 exports.makeWidget = function(parser,options) {
 	options = options || {};
 	var widgetNode = {
@@ -1221,7 +1214,7 @@ exports.makeWidget = function(parser,options) {
 	// Add in the supplied parse tree nodes
 	currWidgetNode.children = parser ? parser.tree : [];
 	// Create the widget
-	return new widget.widget(widgetNode,{
+	return new Widget(widgetNode,{
 		wiki: this,
 		document: options.document || $tw.fakeDocument,
 		parentWidget: options.parentWidget
@@ -1802,5 +1795,3 @@ exports.slugify = function(title,options) {
 	}
 	return slug;
 };
-
-})();

From cdceeddddb713bf67e68602593d3f8935676d673 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 11:47:02 +0800
Subject: [PATCH 09/16] docs: shorten JSDoc comment as requsted

---
 core/modules/parsers/wikiparser/wikiparser.js | 14 +++++++-------
 core/modules/wiki.js                          | 18 +++++++++---------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/core/modules/parsers/wikiparser/wikiparser.js b/core/modules/parsers/wikiparser/wikiparser.js
index fe4d8f8f75f..582f18c767c 100644
--- a/core/modules/parsers/wikiparser/wikiparser.js
+++ b/core/modules/parsers/wikiparser/wikiparser.js
@@ -30,13 +30,13 @@ Attributes are stored as hashmaps of the following objects:
  * 
  * @class
  * @constructor
- * @param {string} type - The content type of the text to be parsed.
- * @param {string} text - The text to be parsed.
- * @param {Object} options - Options for parsing.
- * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
- * @param {Object} options.wiki - Reference to the wiki to use.
- * @param {string} [options._canonical_uri] - Optional URI of the content if the text is missing or empty.
- * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ * @param {string} type - Content type of the text to be parsed
+ * @param {string} text - Text to be parsed
+ * @param {Object} options - Parser options
+ * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run
+ * @param {Object} options.wiki - Reference to the wiki store in use
+ * @param {string} [options._canonical_uri] - Optional URI of the content if text is missing or empty
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, the parser trims white space
  */
 function WikiParser(type,text,options) {
 	this.wiki = options.wiki;
diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index 4f48c252c49..cb43a6253f4 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1041,17 +1041,17 @@ exports.initParsers = function(moduleType) {
  */
 
 /**
- * Parse a block of text of a specified MIME type.
+ * Parse a block of text of a specified MIME type
  * 
- * @param {string} type - The content type of the text to be parsed.
- * @param {string} text - The text to be parsed.
- * @param {Object} [options] - Options for parsing.
- * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
- * @param {string} [options._canonical_uri] - Optional string of the canonical URI of this content.
- * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - The default type to use if no parser is found for the specified type.
- * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ * @param {string} type - Content type of text to be parsed
+ * @param {string} text - Text to be parsed
+ * @param {Object} [options] - Options for parsing
+ * @param {boolean} [options.parseAsInline=false] - If true, text will be parsed as an inline run
+ * @param {string} [options._canonical_uri] - Optional string of canonical URI of this content
+ * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - Default type to use if no parser is found for specified type
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration
  * 
- * @returns {WikiParser|null} The parser instance or null if no parser is found.
+ * @returns {WikiParser|null} Parser instance or null if no parser is found
  */
 exports.parseText = function(type,text,options) {
 	text = text || "";

From 8f0d37e24c9ba91dd3c42c1f5c684558cbcca196 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 13:17:03 +0800
Subject: [PATCH 10/16] refactor: move some type to base class

---
 core/modules/parsers/base.js                  | 42 +++++++++++++++++++
 core/modules/parsers/wikiparser/wikiparser.js | 12 +++---
 core/modules/wiki.js                          |  5 +--
 3 files changed, 49 insertions(+), 10 deletions(-)
 create mode 100644 core/modules/parsers/base.js

diff --git a/core/modules/parsers/base.js b/core/modules/parsers/base.js
new file mode 100644
index 00000000000..d1f2b428c56
--- /dev/null
+++ b/core/modules/parsers/base.js
@@ -0,0 +1,42 @@
+/**
+ * Base structure for a parse node
+ * 
+ * @typedef {Object} ParseTreeNode
+ * @property {string} type - Type of widget
+ * @property {Object} [attributes] - Attributes of widget
+ * @property {ParseTreeNode[]} [children] - Array of child parse nodes
+ */
+
+/**
+ * Base class for parsers. This only provides typing
+ * 
+ * @class
+ * @param {string} type - Content type of text to be parsed
+ * @param {string} text - Text to be parsed
+ * @param {Object} options - Parser options
+ * @param {boolean} [options.parseAsInline=false] - If true, text will be parsed as an inline run
+ * @param {Object} options.wiki - Reference to wiki store in use
+ * @param {string} [options._canonical_uri] - Optional URI of content if text is missing or empty
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, parser trims white space
+ */
+function Parser(type, text, options) {
+  /**
+   * Result AST
+   * @type {ParseTreeNode[]}
+   */
+  this.tree = [];
+
+  /**
+   * Original text without modifications
+   * @type {string}
+   */
+  this.source = text;
+
+  /**
+   * Source content type in MIME format
+   * @type {string}
+   */
+  this.type = type;
+}
+
+exports.Parser = Parser;
diff --git a/core/modules/parsers/wikiparser/wikiparser.js b/core/modules/parsers/wikiparser/wikiparser.js
index 582f18c767c..653481670ef 100644
--- a/core/modules/parsers/wikiparser/wikiparser.js
+++ b/core/modules/parsers/wikiparser/wikiparser.js
@@ -25,18 +25,16 @@ Attributes are stored as hashmaps of the following objects:
 /*global $tw: false */
 "use strict";
 
+/**
+ * @typedef {import('../base').Parser} Parser
+ */
+
 /**
  * WikiParser class for parsing text of a specified MIME type.
  * 
  * @class
+ * @extends {Parser}
  * @constructor
- * @param {string} type - Content type of the text to be parsed
- * @param {string} text - Text to be parsed
- * @param {Object} options - Parser options
- * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run
- * @param {Object} options.wiki - Reference to the wiki store in use
- * @param {string} [options._canonical_uri] - Optional URI of the content if text is missing or empty
- * @param {boolean} [options.configTrimWhiteSpace=false] - If true, the parser trims white space
  */
 function WikiParser(type,text,options) {
 	this.wiki = options.wiki;
diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index cb43a6253f4..e189231ed2f 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1037,7 +1037,7 @@ exports.initParsers = function(moduleType) {
 };
 
 /**
- * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
+ * @typedef {import('$:/core/modules/parsers/base.js').Parser} Parser
  */
 
 /**
@@ -1051,13 +1051,12 @@ exports.initParsers = function(moduleType) {
  * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - Default type to use if no parser is found for specified type
  * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration
  * 
- * @returns {WikiParser|null} Parser instance or null if no parser is found
+ * @returns {Parser|null} Parser instance or null if no parser is found
  */
 exports.parseText = function(type,text,options) {
 	text = text || "";
 	options = options || {};
 	/**
-	 * @type WikiParser
 	 * Select a parser
 	 */
 	var Parser = $tw.Wiki.parsers[type];

From 24279cca6a449c53d875d8aaa9127c4480dc3a2e Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 13:17:38 +0800
Subject: [PATCH 11/16] feat: allow type in /generated to work

---
 tsconfig.json       |  8 ++++----
 types/tsconfig.json | 20 ++++++++++++++++++++
 2 files changed, 24 insertions(+), 4 deletions(-)
 create mode 100644 types/tsconfig.json

diff --git a/tsconfig.json b/tsconfig.json
index 0988bf8aa27..4ec0bfc310f 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -2,14 +2,15 @@
   "compilerOptions": {
     "paths": {
       // Allow `import('$:/core/modules/...')` instead of `import('../../core/modules/...')`. Only works inside this project.
-      "$:/core/*": ["./core/*"]
+      "$:/core/*": ["core/*"]
     },
+    "baseUrl": ".",
+    "rootDir": ".",
     "noImplicitAny": false,
     "strict": false,
-
     "allowJs": true,
-    "allowSyntheticDefaultImports": true,
     "checkJs": true,
+    "allowSyntheticDefaultImports": true,
     "declaration": true,
     "declarationDir": "types/generated",
     "declarationMap": true,
@@ -17,7 +18,6 @@
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "Node16",
     "outDir": "types/generated",
-    "rootDir": ".",
     "skipLibCheck": true,
     "target": "ESNext"
   },
diff --git a/types/tsconfig.json b/types/tsconfig.json
new file mode 100644
index 00000000000..b98460aff7b
--- /dev/null
+++ b/types/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "paths": {
+      // Allow `import('$:/core/modules/...')` instead of `import('../../core/modules/...')`. Only works inside this project.
+      "$:/core/*": ["core/*"]
+    },
+    "baseUrl": "./generated",
+    "rootDir": "./generated",
+    "noEmit": true,
+    "noImplicitAny": false,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "declarationDir": "types/generated",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "Node16",
+    "skipLibCheck": true,
+    "target": "ESNext"
+  },
+  "include": ["./generated/**/*.d.ts"]
+}

From e3fc9b4d33c300023d019fb87396f7f3023df885 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 13:57:44 +0800
Subject: [PATCH 12/16] feat: import base type

---
 core/modules/parsers/base.js | 6 ++++++
 core/modules/wiki.js         | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/core/modules/parsers/base.js b/core/modules/parsers/base.js
index d1f2b428c56..dbdb769f7f0 100644
--- a/core/modules/parsers/base.js
+++ b/core/modules/parsers/base.js
@@ -1,3 +1,9 @@
+/*\
+title: $:/core/modules/parsers/base.js
+type: application/javascript
+module-type: library
+\*/
+
 /**
  * Base structure for a parse node
  * 
diff --git a/core/modules/wiki.js b/core/modules/wiki.js
index e189231ed2f..2ca84906d54 100755
--- a/core/modules/wiki.js
+++ b/core/modules/wiki.js
@@ -1051,7 +1051,7 @@ exports.initParsers = function(moduleType) {
  * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - Default type to use if no parser is found for specified type
  * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration
  * 
- * @returns {Parser|null} Parser instance or null if no parser is found
+ * @returns {Parser | null} Parser instance or null if no parser is found
  */
 exports.parseText = function(type,text,options) {
 	text = text || "";

From 18517b67c060005e31d05c4729803d0b87599217 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 15:05:09 +0800
Subject: [PATCH 13/16] refactor: generate types to /types/core instead for
 simplicity

---
 .gitignore          | 2 +-
 tsconfig.json       | 9 +++++----
 types/tsconfig.json | 7 +++----
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.gitignore b/.gitignore
index 07f080e2654..9a5b85c4556 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,4 +9,4 @@ node_modules/
 /playwright-report/
 /playwright/.cache/
 $__StoryList.tid
-types/generated/
+types/core/
diff --git a/tsconfig.json b/tsconfig.json
index 4ec0bfc310f..5398d26ba2b 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -12,15 +12,16 @@
     "checkJs": true,
     "allowSyntheticDefaultImports": true,
     "declaration": true,
-    "declarationDir": "types/generated",
+    "declarationDir": "types/",
     "declarationMap": true,
     "emitDeclarationOnly": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "Node16",
-    "outDir": "types/generated",
+    "outDir": "types/",
     "skipLibCheck": true,
     "target": "ESNext"
   },
-  "include": ["./core/**/*.js", "./core/**/*.d.ts", "types/tw.d.ts"],
-  "exclude": ["types/generated"]
+  "include": ["./core/**/*.js", "./core/**/*.d.ts", "types/*.d.ts"],
+  // Exclude the generated types from the core folder
+  "exclude": ["types/core",]
 }
diff --git a/types/tsconfig.json b/types/tsconfig.json
index b98460aff7b..04a2433755d 100644
--- a/types/tsconfig.json
+++ b/types/tsconfig.json
@@ -4,17 +4,16 @@
       // Allow `import('$:/core/modules/...')` instead of `import('../../core/modules/...')`. Only works inside this project.
       "$:/core/*": ["core/*"]
     },
-    "baseUrl": "./generated",
-    "rootDir": "./generated",
+    "baseUrl": "./",
+    "rootDir": "./",
     "noEmit": true,
     "noImplicitAny": false,
     "allowSyntheticDefaultImports": true,
     "declaration": true,
-    "declarationDir": "types/generated",
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "Node16",
     "skipLibCheck": true,
     "target": "ESNext"
   },
-  "include": ["./generated/**/*.d.ts"]
+  "include": ["./core/**/*.d.ts"]
 }

From c56afea741eff02b44d6ef7077390042777643be Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 17:04:16 +0800
Subject: [PATCH 14/16] feat: add ast type that wikiast is using

---
 core/modules/parsers/base.js                  | 18 ++++++++-
 .../parsers/wikiparser/rules/codeblock.js     | 32 +++++++---------
 core/modules/parsers/wikiparser/rules/html.js | 38 +++++++++++++++++--
 types/ast.d.ts                                |  6 +++
 4 files changed, 69 insertions(+), 25 deletions(-)
 create mode 100644 types/ast.d.ts

diff --git a/core/modules/parsers/base.js b/core/modules/parsers/base.js
index dbdb769f7f0..49bb5e36040 100644
--- a/core/modules/parsers/base.js
+++ b/core/modules/parsers/base.js
@@ -4,12 +4,26 @@ type: application/javascript
 module-type: library
 \*/
 
+/**
+ * Represents an attribute in a parse tree node
+ * 
+ * @typedef {Object} ParseTreeAttribute
+ * @property {number} [end] - End position of attribute in source text
+ * @property {string} [name] - Name of attribute
+ * @property {number} [start] - Start position of attribute in source text
+ * @property {'string' | 'number' | 'bigint' | 'boolean' | 'macro' | 'macro-parameter'} type - Type of attribute
+ * @property {string | IMacroCallParseTreeNode} value - Actual value of attribute
+ */
+
 /**
  * Base structure for a parse node
  * 
  * @typedef {Object} ParseTreeNode
- * @property {string} type - Type of widget
- * @property {Object} [attributes] - Attributes of widget
+ * @property {string} type - Type of widget that will render this node
+ * @property {string} rule - Parse rule that generated this node. One rule can generate multiple types of nodes
+ * @property {number} start - Rule start marker in source text
+ * @property {number} end - Rule end marker in source text
+ * @property {Record<string,ParseTreeAttribute>} [attributes] - Attributes of widget
  * @property {ParseTreeNode[]} [children] - Array of child parse nodes
  */
 
diff --git a/core/modules/parsers/wikiparser/rules/codeblock.js b/core/modules/parsers/wikiparser/rules/codeblock.js
index 507ca424ffb..d5a7ca9ad1a 100644
--- a/core/modules/parsers/wikiparser/rules/codeblock.js
+++ b/core/modules/parsers/wikiparser/rules/codeblock.js
@@ -13,22 +13,21 @@ Wiki text rule for code blocks. For example:
 
 \*/
 
+/**
+ * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ */
+
 /**
  * Represents the `codeblock` rule.
  * 
- * @typedef {Object} CodeblockNode
- * @property {string} type - The type of the widget, which is "codeblock".
- * @property {Object} attributes - The attributes of the codeblock.
- * @property {Object} attributes.code - The code attribute object.
- * @property {string} attributes.code.type - The type of the code attribute, which is "string".
- * @property {string} attributes.code.value - The actual code content within the code block.
- * @property {number} attributes.code.start - The start position of the code in the source text.
- * @property {number} attributes.code.end - The end position of the code in the source text.
- * @property {Object} attributes.language - The language attribute object.
- * @property {string} attributes.language.type - The type of the language attribute, which is "string".
- * @property {string} attributes.language.value - The language specified after the triple backticks, if any.
- * @property {number} attributes.language.start - The start position of the language string in the source text.
- * @property {number} attributes.language.end - The end position of the language string in the source text.
+ * @typedef {Object} ParseTreeCodeblockNode
+ * @property {"codeblock"} rule
+ * @property {"codeblock"} type
+ * @property {number} start
+ * @property {number} end
+ * @property {Object} attributes
+ * @property {ParseTreeAttribute} attributes.code
+ * @property {ParseTreeAttribute} attributes.language
  */
 
 (function(){
@@ -40,11 +39,6 @@ Wiki text rule for code blocks. For example:
 exports.name = "codeblock";
 exports.types = {block: true};
 
-/**
- * Initializes the codeblock rule with the given parser.
- * 
- * @param {Object} parser - The parser object that manages the state of the parsing process.
- */
 exports.init = function(parser) {
 	this.parser = parser;
 	// Regexp to match and get language if defined
@@ -54,7 +48,7 @@ exports.init = function(parser) {
 /**
  * Parses the code block and returns an array of `codeblock` widgets.
  * 
- * @returns {CodeblockNode[]} An array containing a single codeblock widget object.
+ * @returns {ParseTreeCodeblockNode[]} An array containing a single codeblock widget object.
  */
 exports.parse = function() {
 	var reEnd = /(\r?\n```$)/mg;
diff --git a/core/modules/parsers/wikiparser/rules/html.js b/core/modules/parsers/wikiparser/rules/html.js
index 61c4ad9e1ec..2c5d7bceece 100644
--- a/core/modules/parsers/wikiparser/rules/html.js
+++ b/core/modules/parsers/wikiparser/rules/html.js
@@ -17,6 +17,31 @@ This is a widget invocation
 }}}
 
 \*/
+
+
+/**
+ * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ */
+
+/**
+ * Represents the parser `html` rule
+ * 
+ * @typedef {Object} ParseTreeHtmlNode
+ * @property {"html"} rule
+ * @property {"element"} type
+ * @property {keyof HTMLElementTagNameMap} tag
+ * @property {number} start
+ * @property {number} end
+ * @property {Record<string,ParseTreeAttribute>} attributes - Contains attributes of HTML element
+ * @property {boolean} isSelfClosing - If tag is self-closing
+ * @property {boolean} isBlock - If tag is a block element
+ * @property {number} openTagStart
+ * @property {number} openTagEnd
+ * @property {number} closeTagStart
+ * @property {number} closeTagEnd
+ * @property {ParseTreeHtmlNode[]} [children]
+ */
+
 (function(){
 
 /*jslint node: true, browser: true */
@@ -38,11 +63,16 @@ exports.findNextMatch = function(startPos) {
 	return this.nextTag ? this.nextTag.start : undefined;
 };
 
-/*
-Parse the most recent match
-*/
+/**
+ * Parse most recent match
+ * 
+ * @returns {ParseTreeHtmlNode[]} Array containing parsed HTML tag object
+ */
 exports.parse = function() {
-	// Retrieve the most recent match so that recursive calls don't overwrite it
+	/**
+	 * @type {ParseTreeHtmlNode}
+	 * Retrieve the most recent match so that recursive calls don't overwrite it
+	 */
 	var tag = this.nextTag;
 	if (!tag.isSelfClosing) {
 		tag.openTagStart = tag.start;
diff --git a/types/ast.d.ts b/types/ast.d.ts
new file mode 100644
index 00000000000..f5d3bbe75ff
--- /dev/null
+++ b/types/ast.d.ts
@@ -0,0 +1,6 @@
+import { ParseTreeCodeblockNode } from './core/modules/parsers/wikiparser/rules/codeblock';
+export { ParseTreeCodeblockNode } from './core/modules/parsers/wikiparser/rules/codeblock';
+import { ParseTreeHtmlNode } from './core/modules/parsers/wikiparser/rules/html';
+export { ParseTreeHtmlNode } from './core/modules/parsers/wikiparser/rules/html';
+
+export type WikiASTNode = ParseTreeCodeblockNode | ParseTreeHtmlNode;

From 06204b15800688cf85cfca08dc26def4c95e5398 Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 17:49:18 +0800
Subject: [PATCH 15/16] feat: refine the ast type

---
 .../parsers/wikiparser/rules/codeblock.js     |  4 ++
 core/modules/parsers/wikiparser/rules/html.js | 22 +++++++++-
 .../parsers/wikiparser/wikirulebase.js        | 44 ++++++++++++++-----
 types/ast.d.ts                                |  8 ++--
 4 files changed, 63 insertions(+), 15 deletions(-)

diff --git a/core/modules/parsers/wikiparser/rules/codeblock.js b/core/modules/parsers/wikiparser/rules/codeblock.js
index d5a7ca9ad1a..f6e9463f3e5 100644
--- a/core/modules/parsers/wikiparser/rules/codeblock.js
+++ b/core/modules/parsers/wikiparser/rules/codeblock.js
@@ -15,6 +15,9 @@ Wiki text rule for code blocks. For example:
 
 /**
  * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ * @typedef {import('../wikirulebase.js').WikiRuleBase} WikiRuleBase
+ * @typedef {import('../../base.js').Parser} Parser
+ * @typedef {typeof exports & WikiRuleBase} ThisRule
  */
 
 /**
@@ -48,6 +51,7 @@ exports.init = function(parser) {
 /**
  * Parses the code block and returns an array of `codeblock` widgets.
  * 
+ * @this {ThisRule}
  * @returns {ParseTreeCodeblockNode[]} An array containing a single codeblock widget object.
  */
 exports.parse = function() {
diff --git a/core/modules/parsers/wikiparser/rules/html.js b/core/modules/parsers/wikiparser/rules/html.js
index 2c5d7bceece..b553515136b 100644
--- a/core/modules/parsers/wikiparser/rules/html.js
+++ b/core/modules/parsers/wikiparser/rules/html.js
@@ -21,6 +21,9 @@ This is a widget invocation
 
 /**
  * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ * @typedef {import('../wikirulebase.js').WikiRuleBase} WikiRuleBase
+ * @typedef {import('../../base.js').Parser} Parser
+ * @typedef {typeof exports & WikiRuleBase & {nextTag?:ParseTreeHtmlNode;}} ThisRule
  */
 
 /**
@@ -51,10 +54,18 @@ This is a widget invocation
 exports.name = "html";
 exports.types = {inline: true, block: true};
 
+/**
+ * @param {Parser} parser 
+ */
 exports.init = function(parser) {
 	this.parser = parser;
 };
 
+/**
+ * @this {ThisRule}
+ * @param {number} startPos 
+ * @returns {number | undefined} Start position of next HTML tag
+ */
 exports.findNextMatch = function(startPos) {
 	// Find the next tag
 	this.nextTag = this.findNextTag(this.parser.source,startPos,{
@@ -65,7 +76,7 @@ exports.findNextMatch = function(startPos) {
 
 /**
  * Parse most recent match
- * 
+ * @this {ThisRule}
  * @returns {ParseTreeHtmlNode[]} Array containing parsed HTML tag object
  */
 exports.parse = function() {
@@ -191,6 +202,15 @@ exports.parseTag = function(source,pos,options) {
 	return node;
 };
 
+/**
+ * Find the next HTML tag in the source
+ * 
+ * @this {ThisRule}
+ * @param {string} source
+ * @param {number} pos - Position to start searching from
+ * @param {Object} options
+ * @returns {Object|null} Parsed tag object or null if no valid tag is found
+ */
 exports.findNextTag = function(source,pos,options) {
 	// A regexp for finding candidate HTML tags
 	var reLookahead = /<([a-zA-Z\-\$\.]+)/g;
diff --git a/core/modules/parsers/wikiparser/wikirulebase.js b/core/modules/parsers/wikiparser/wikirulebase.js
index 8aa960ef790..f2a319942e1 100644
--- a/core/modules/parsers/wikiparser/wikirulebase.js
+++ b/core/modules/parsers/wikiparser/wikirulebase.js
@@ -12,22 +12,46 @@ Base class for wiki parser rules
 /*global $tw: false */
 "use strict";
 
-/*
-This constructor is always overridden with a blank constructor, and so shouldn't be used
-*/
-var WikiRuleBase = function() {
+/**
+ * @typedef {import('../base').Parser} Parser
+ */
+
+/**
+ * Base class for wiki rules.
+ * This constructor is always overridden with a blank constructor, and so shouldn't be used
+ * 
+ * @class
+ * @constructor
+ */
+function WikiRuleBase() {
+	/**
+	 * Inject by parser
+	 * @type {Record<"pragma"|"block"|"inline", boolean>}
+	 */
+	this.is = {};
+	/**
+	 * @type {RegExp}
+	 */
+	this.matchRegExp;
 };
 
-/*
-To be overridden by individual rules
-*/
+/**
+ * Initialize rule with given parser instance
+ * To be overridden by individual rules
+ * 
+ * @param {Parser} parser - Parser instance to initialize with
+ */
 WikiRuleBase.prototype.init = function(parser) {
 	this.parser = parser;
 };
 
-/*
-Default implementation of findNextMatch uses RegExp matching
-*/
+/**
+ * Default implementation of findNextMatch uses RegExp matching
+ * Find next match in source starting from given position using RegExp matching
+ * 
+ * @param {number} startPos - Position to start searching from
+ * @returns {number|undefined} Index of next match or undefined if no match is found
+ */
 WikiRuleBase.prototype.findNextMatch = function(startPos) {
 	this.matchRegExp.lastIndex = startPos;
 	this.match = this.matchRegExp.exec(this.parser.source);
diff --git a/types/ast.d.ts b/types/ast.d.ts
index f5d3bbe75ff..ca8fdc90b5e 100644
--- a/types/ast.d.ts
+++ b/types/ast.d.ts
@@ -1,6 +1,6 @@
-import { ParseTreeCodeblockNode } from './core/modules/parsers/wikiparser/rules/codeblock';
-export { ParseTreeCodeblockNode } from './core/modules/parsers/wikiparser/rules/codeblock';
-import { ParseTreeHtmlNode } from './core/modules/parsers/wikiparser/rules/html';
-export { ParseTreeHtmlNode } from './core/modules/parsers/wikiparser/rules/html';
+import { ParseTreeCodeblockNode } from '$:/core/modules/parsers/wikiparser/rules/codeblock.js';
+export { ParseTreeCodeblockNode } from '$:/core/modules/parsers/wikiparser/rules/codeblock.js';
+import { ParseTreeHtmlNode } from '$:/core/modules/parsers/wikiparser/rules/html.js';
+export { ParseTreeHtmlNode } from '$:/core/modules/parsers/wikiparser/rules/html.js';
 
 export type WikiASTNode = ParseTreeCodeblockNode | ParseTreeHtmlNode;

From 0c92f1bb400118e5a8327501b350731485dcf72e Mon Sep 17 00:00:00 2001
From: linonetwo <linonetwo012@gmail.com>
Date: Thu, 12 Sep 2024 17:52:38 +0800
Subject: [PATCH 16/16] Update tw.d.ts

---
 types/tw.d.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/types/tw.d.ts b/types/tw.d.ts
index b0477dde30c..17d7c0b274f 100644
--- a/types/tw.d.ts
+++ b/types/tw.d.ts
@@ -1,4 +1,4 @@
-import * as Wiki from '../core/modules/wiki';
+import * as Wiki from '$:/core/modules/wiki';
 
 declare global {
   var $tw: {