docs: use mermaid on typedoc output (#32)

* Remove typedoc-plugin-mermaid and replace with a custom script
* Add an example tasks.json for vscode
* Add BUILDING.md as a shorter version of CONTRIBUTING.md
* Mention transitive dependencies in NOTICE.md
* Fix wording and broken links in doc/
* Also some refactoring that split some of longer classes

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
  * Added BUILDING guide and startup helpers for editor/session flow.

* **Documentation**
* README, FAQ, design, NOTICE, typedoc and rendering updates; badges and
changelog adjusted.

* **Refactor**
* Background/startup and editor/session orchestration reorganized for
clearer flows.

* **Chores**
* CI uploader upgraded; dependency and tooling updates; schema and
packaging/script adjustments.

* **Developer Experience**
  * VS Code task examples and standardized test output paths added.

* **Tests**
  * Improved test helpers and assertions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: snipsnipsnip

.github/workflows/doc.yml

@@ -51,7 +51,7 @@ jobs:
         uses: actions/configure-pages@v4
 
       - name: Upload pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: build/doc
 

.vscode/tasks.example.json

@@ -0,0 +1,71 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "tsc:once",
+      "type": "shell",
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "problemMatcher": "$tsc",
+      "isBackground": false,
+      "command": "corepack",
+      "args": [
+        "yarn",
+        "run",
+        "check-type"
+      ]
+    },
+    {
+      "label": "tsc:watch",
+      "type": "shell",
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "command": "corepack",
+      "args": [
+        "yarn",
+        "run",
+        "check-type",
+        "--watch"
+      ]
+    },
+    {
+      "label": "tsdown:once",
+      "type": "shell",
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "problemMatcher": "$tsc",
+      "isBackground": false,
+      "command": "corepack",
+      "args": [
+        "yarn",
+        "run",
+        "tsdown"
+      ]
+    },
+    {
+      "label": "tsdown:watch",
+      "type": "shell",
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "command": "corepack",
+      "args": [
+        "yarn",
+        "run",
+        "tsdown",
+        "--watch"
+      ]
+    }
+  ]
+}

.web-ext-config.example.mjs

@@ -5,7 +5,7 @@ export default {
   run: {
     // You can use flatpak by specifying "flatpak:org.mozilla.Thunderbird"
     firefox: "/usr/bin/thunderbird",
-    firefoxProfile: "/home/your/.config/your-testing-thunderbird-profile",
+    firefoxProfile: import.meta.dirname + "/.cache/thunderbird-testing-profile/",
     profileCreateIfMissing: true,
     // keepProfileChanges: true,
   },

BUILDING.md

@@ -0,0 +1,7 @@
+# Building
+
+* Ensure that you have Node.js LTS (v22+) and corepack installed.
+* Basically, running `make` will do, which is roughly equivalent to `yarn install && yarn build`.
+  * A XPI file will appear in `dist/`.
+* See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on tools and steps.
+* See [building.md](./doc/building.md) for details on build script internals.

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing
 
 * Feel free to open issues and submit pull requests.
+* See [Open source etiquette](https://developer.mozilla.org/docs/MDN/Community/Open_source_etiquette) for general guidelines.
 * By contributing, you agree that your contributions will be [dual-licensed under MPL-2.0 OR GPL-3.0-or-later](./LICENSE).
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/exteditor/ghostbird?quickstart=1)

README.md

@@ -1,9 +1,9 @@
 # Ghostbird: GhostText for Thunderbird :nest_with_eggs::mailbox::ghost:
 
-[![Supports Thunderbird ESR](https://img.shields.io/badge/supports-Thunderbird_140_ESR-0a84ff?logo=thunderbird&logoSize=auto)][tb]<br>
-[![Status: Beta](https://img.shields.io/badge/project_status-beta-f1b802)][rels]
-[![Latest release](https://img.shields.io/github/v/release/exteditor/ghostbird?include_prereleases&logo=refinedgithub&logoColor=white&logoSize=auto)][rels]<br>
+[![Supports Thunderbird ESR](https://img.shields.io/badge/supports-Thunderbird_140_ESR-0a84ff?logo=thunderbird&logoSize=auto)][tb]
 [![Github Actions Status](https://github.com/exteditor/ghostbird/actions/workflows/build.yml/badge.svg)](https://github.com/exteditor/ghostbird/actions/workflows/build.yml)
+[![Status: Beta](https://img.shields.io/badge/project_status-beta-cce165)][rels]
+[![Latest release](https://img.shields.io/github/v/release/exteditor/ghostbird?include_prereleases&logo=refinedgithub&logoColor=white&logoSize=auto)][rels]
 
 [![Download on AMO](https://raw.githubusercontent.com/thunderbird/webext-support/refs/heads/master/images/get-the-addon.svg)](#installation)
 
@@ -13,14 +13,14 @@ This repo contains an in-development Thunderbird add-on that works as a [GhostTe
 
 ## Requirements
 
-* [Thunderbird 140][tb] (We will mainly support ESR releases)
+* [Thunderbird 140][tb] (We will mainly support the latest ESR)
 * A text editor that has a GhostText server add-on installed and running:
 
   [![Sublime Text][sublimetext-svg]](https://sublime.wbond.net/packages/GhostText)
   [<img width="48" height="48" alt="VSCodium" title="VSCodium" src="https://raw.githubusercontent.com/VSCodium/vscodium.github.io/refs/heads/master/img/codium_cnl.svg" >](https://open-vsx.org/extension/fregante/ghost-text)
   [![Visual Studio Code][vscode-svg]](https://marketplace.visualstudio.com/items?itemName=fregante.ghost-text)
   [![GNU Emacs][emacs-svg]](https://melpa.org/#/atomic-chrome)
-  [![Vim][vim-svg]](https://github.com/raghur/vim-ghost)
+  [![Vim][vim-svg]][vimghost]
   [![Neovim][nvim-svg]](https://github.com/subnut/nvim-ghost.nvim)
   [<img src="https://9fans.github.io/plan9port/dist/spaceglenda100.png" width="48" height="48" alt="Acme" title="Acme">](https://github.com/fhs/Ghost)
   [<img src="https://github.com/user-attachments/assets/b0ca34ed-5508-458f-b7af-2642824bf7f7" width="48" height="48" alt="Helix" title="Helix">][helix]
@@ -56,7 +56,7 @@ Alternatively, you can:
 
 ### Build from source
 
-* Basically, `make` will do, which internally calls `yarn install && yarn build`.
+* Basically, running `make` will do, which is roughly equivalent to `yarn install && yarn build`.
 * See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
 
 ## Usage
@@ -69,6 +69,10 @@ Alternatively, you can:
 4. Write your email in the text editor.
 5. Close your text editor to stop Ghostbird.
 
+* Example using [Vim-Ghost][vimghost]
+
+  [vimghost.webm](https://github.com/user-attachments/assets/150ef991-10b8-45e2-bb2c-690f1b45a7ea)
+
 * Example using Notepad++ via GhostText-Any
 
   <img width="600" height="302" alt="Screenshot using Notepad++ with GhostText-Any" src="https://github.com/user-attachments/assets/a4f92beb-a6f2-4a67-ae94-aa02af64539e" />
@@ -133,7 +137,10 @@ gtClient -->|Updates| mailCompose
 
 ### v0.2.1 (Beta) - Current
 
-* :construction: [Fix empty host field being sent to the server](https://github.com/exteditor/ghostbird/issues/22)
+* :nest_with_eggs: [Fix empty host field being sent to the server](https://github.com/exteditor/ghostbird/issues/22)
+
+### v0.3.0 (Beta) - 2025 Q4
+
 * :construction: [Show notifications](https://github.com/exteditor/ghostbird/issues/24)
 
 ### v0.x.x (Beta) - 2025 Q4
@@ -180,14 +187,15 @@ If you like the idea, please:
 
 We need help with:
 
-* [Website](https://exteditor.github.io/ghostbird/) and materials (Please post [screenshots to the wiki](https://github.com/exteditor/ghostbird/wiki/Screenshots))
+* [Website](https://exteditor.github.io/ghostbird/) and materials (please post [screenshots to the wiki](https://github.com/exteditor/ghostbird/wiki/Screenshots))
+* Translations (check [`locales.toml`](./locales.toml) and let us know of any issues)
 * [Testing with various text editors](https://github.com/exteditor/ghostbird/wiki/TextEditorsKnownToWorkWith)
 * [Testing with various OSes](https://github.com/exteditor/ghostbird/wiki/OSesKnownToWorkWith)
 * Wiki pages for [user guides](https://github.com/exteditor/ghostbird/wiki/HowTo) and [troubleshooting](https://github.com/exteditor/ghostbird/wiki/Troubleshooting)
-* Developing the server counterpart so that this can be used as an External Editor replacement ([GhostText-Any](https://github.com/newsch/GhostText-Any/) or [Helix-Ghost][helix] can be a good starting point)
-* Creating a testing checklist for testing and debugging ([This page](https://github.com/exteditor/exteditor/wiki/Things-to-test) can be a good starting point)
-* Automating tests with the real Thunderbird (See [Testing](./doc/testing.md))
-* Organization members (I want to increase [the bus factor](https://en.wikipedia.org/wiki/Bus_factor) of [the organization](https://github.com/exteditor/))
+* Developing the server counterpart so that this can be used as a replacement for External Editor ([GhostText-Any](https://github.com/newsch/GhostText-Any/) or [Helix-Ghost][helix] can be a good starting point)
+* Creating a checklist for testing and debugging ([This page](https://github.com/exteditor/exteditor/wiki/Things-to-test) can be a good starting point)
+* Automating tests with the actual Thunderbird (See [Testing](./doc/testing.md))
+* Organization members (we want to increase [the organization](https://github.com/exteditor/)'s [bus factor](https://en.wikipedia.org/wiki/Bus_factor))
 
 ## FAQ
 
@@ -260,3 +268,4 @@ Ghostbird is [dual-licensed under (MPL-2.0 OR GPL-3.0-or-later)](./LICENSE). See
 [bird]: https://en.wikipedia.org/wiki/Grey-headed_bushshrike
 [protocol]: https://github.com/fregante/GhostText/blob/refs/heads/main/PROTOCOL.md
 [amo]: https://addons.thunderbird.net/addon/ghostbird/
+[vimghost]: https://github.com/raghur/vim-ghost

biome.jsonc

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.2.5/schema.json",
   "files": {
     "includes": [
       "**/*.json",

doc/design.md

@@ -39,7 +39,7 @@ subgraph "Background Script"
     bg_router -->|fwd onCommand| notifier --> gtclient --> email_editor
     option_holder -.- gtclient
     gtclient --> connector
-    websocket <--> connector
+    websocket <-.-> connector
 end
 
 subgraph "Compose Window Script"
@@ -51,10 +51,10 @@ subgraph "Compose Window Script"
 end
 
 composeeditor -..->|read/write| compose_dom
-ghost_server <-----> websocket
+ghost_server <-....-> websocket
 thunderbird -- Open --> option
 thunderbird -- Load --> background
-connector <--> Port <--> port_handler
+connector <-.-> Port <-.-> port_handler
 ```
 
 ### Sequence diagram
@@ -158,9 +158,11 @@ This is how user actions are handled:
 
 ### Quirks and limitations
 
-* Because of [MV3 limitations][so], `background.js` may occasionally be suspended (all variables including WebSockets are unloaded, so it's effectively terminated). We do our best to prevent it, but ultimately it's up to Thunderbird.
+* Because of [MV3 limitations][so], `background.js` may occasionally be suspended (all variables including WebSockets are unloaded, so it's effectively terminated).
+  * We do our best to prevent it, but ultimately it's up to Thunderbird.
 * We don't implement reconnecting the WebSocket connection when it is closed abnormally. The user has to click the Ghostbird button again to reconnect.
-* Connections will also closes when the user updates the add-on. It will be handled similarly to `(b)`.
+* Connections will also close when the user updates the add-on.
+  * It will be handled similarly to the case `(b)`.
 * Initially, we don't support edits made in the compose window. We aim to support it in v2.0.0, but copying what the original GhostText add-on does might work well enough. We'll see.
 
 ## Tooling
@@ -170,7 +172,7 @@ This is how user actions are handled:
   * See [CONTRIBUTING.md](../CONTRIBUTING.md#code-style) for the code style.
 
 * [Barrelsby](https://github.com/bencoveney/barrelsby)  generates `index.ts`.
-  * See [`tools/tsdown_config.ts`](../tools/tsdown_config.ts).
+  * See [building.md](./building.md) for details on build script internals.
 
 ## Structure of the code<a name="structure"></a>
 
@@ -314,7 +316,7 @@ TL;DR: `root` module contains entry point and the [Composition Root][ploeh].
   * If `false`, `undefined`, or the property is missing, each argument to the constructor will be an instance of the class that has the name uniquely.
 * A class may define `static aliases: string[] | string` to have the other name.
   * Name clashes will result in error at startup, except ones passed to classes with `wantArray = true`.
-* Use of automatic instantiation must be restricted to `root/*.ts` to make the code easier to follow.
+* Use of automatic instantiation must be restricted to `root/` to make the code easier to follow.
 * `test/startup.test.ts` contains tests to verify that all classes registered can be instantiated successfully.
 * See [FAQ](./faq-architectural.md) for some design decisions and justification.
 

doc/faq.md

@@ -14,7 +14,7 @@
 
 ### Which Thunderbird versions are supported?
 
-* Thunderbird 128+ (We will mainly support ESR)
+* Thunderbird 128+ (We will mainly support the latest ESR)
 * Testing with newer versions is welcomed. Please report any issues you notice in newer Thunderbird versions.
 
 ### What text editors are supported?
@@ -126,7 +126,7 @@
 ### What are these `api.ts` files? They seem to only contain interfaces that aren't implemented.
 
 * Implementations are in other modules, mostly in `thunderbird/*.ts`.
-* See [Callgraphs](./design.md#callgraph) for details.
+* See [Callgraphs](./design.md#callgraphs) for details.
 * See [Module Dependencies](./design.md#module-dependencies) for relations.
 
 ### Why do some classes have `static isSingleton` property?
@@ -149,7 +149,7 @@
 [wiki]: https://github.com/exteditor/ghostbird/wiki
 [issue]: https://github.com/exteditor/ghostbird/issues
 [discussion]: https://github.com/exteditor/ghostbird/discussions
-[startup]: ../src/root/startup.ts
+[startup]: ../src/root/startup/startup_compose.ts
 [protocol]: https://github.com/fregante/GhostText/blob/main/PROTOCOL.md
 [gt]: https://ghosttext.fregante.com/
 [chooseicon]: https://github.com/exteditor/ghostbird/issues/7

doc/res/typedoc.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+let nodes = document.querySelectorAll('code.mermaid');
+let mermaidPromise = nodes.length ? import('https://cdn.jsdelivr.net/npm/mermaid@11.12.0/dist/mermaid.esm.min.mjs') : null;
+
+mermaidPromise?.then(({ default: mermaid }) => {
+  mermaid.run({ nodes });
+}).catch((error) => {
+  console.warn('Failed to load or run Mermaid:', error);
+});