joplin-plugin-harper 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pmslava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# Harper for Joplin
+
+Grammar and spell checking for [Joplin](https://joplinapp.org)'s Markdown editor, powered by
+[Harper](https://writewithharper.com) — the fast, private grammar checker from Automattic.
+
+Harper runs **entirely on your machine**. There is no cloud service, no account, and no network
+request: your notes never leave your computer. The whole checker (a compiled WebAssembly engine)
+ships inside the plugin, so it works fully offline.
+
+As you type in the Markdown editor, Harper underlines spelling and grammar issues with a coloured
+squiggle, and hovering over one opens a small card with the problem, one-click fixes, and follow-up
+actions.
+
+![The Harper suggestion card and coloured underlines in the Joplin Markdown editor](https://raw.githubusercontent.com/pmslava/joplin-plugin-harper/main/docs/screenshots/card-light.png)
+
+![The suggestion card in Joplin's dark theme](https://raw.githubusercontent.com/pmslava/joplin-plugin-harper/main/docs/screenshots/card-dark.png)
+
+Per-kind coloured underlines — a red spelling squiggle, an orange typo, a green word-choice
+suggestion:
+
+![Close-up of the per-kind coloured underlines](https://raw.githubusercontent.com/pmslava/joplin-plugin-harper/main/docs/screenshots/underlines-dark.png)
+
+## Features
+
+- **Coloured underlines, one colour per issue type.** Harper sorts every finding into one of its
+  lint kinds — Spelling, Grammar, Punctuation, Word Choice, Repetition, Redundancy, Style, and more
+  (21 in all) — and each kind gets its own squiggle colour, so you can tell a misspelling from a
+  style nudge at a glance. The colours are Harper's own and work in both light and dark themes.
+- **A suggestion card.** Hover over an underline to open a card that shows the issue type, Harper's
+  explanation with the flagged word highlighted, and the available fixes.
+- **Apply a fix in one click.** Each suggestion is a pill; clicking it rewrites the text (replace,
+  remove, or insert) directly in the editor.
+- **Add to dictionary.** Spelling cards include an add-to-dictionary button, so a name or term you
+  use often stops being flagged (see [External dictionary](#external-dictionary) below).
+- **Ignore a single finding.** *Dismiss* hides just that one underline and remembers the choice
+  between sessions, without disabling the rule everywhere.
+- **Disable a rule.** The toggle in the card header turns off the rule that produced the finding,
+  everywhere, from then on.
+- **Dialects.** Check against American, British, Australian, or Canadian English.
+
+## External dictionary
+
+By default, words you add via *Add to dictionary* are stored in the plugin's own private word list.
+
+You can instead point Harper at a **plain-text dictionary file of your own** — one word per line —
+by setting **External dictionary file** to its absolute path. When that path is set:
+
+- Every word in the file is treated as correctly spelled.
+- *Add to dictionary* **appends** the new word to that same file (one word per line).
+- The file is re-read automatically about every 60 seconds, so changes made outside Joplin are
+  picked up without a restart.
+
+This is deliberately just a flat text file with no special format. That makes it easy to keep the
+file wherever you like and sync it between machines with your own tooling (a synced folder, a
+version-controlled dotfile, `rsync`/`rclone`, and so on) — or to share the same word list with
+another tool that reads a plain word-per-line dictionary. Harper only ever reads and appends lines;
+it never rewrites or reorders the file.
+
+## Settings
+
+Open **Tools → Options → Harper** (desktop).
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| **Enable Harper grammar checking** | On | Master switch. When off, no underlines are shown. |
+| **English dialect** | American | Which English variety Harper checks against: American, British, Australian, or Canadian. |
+| **Lint debounce (ms)** | `500` | How long the editor waits after you stop typing before re-checking, in milliseconds (0–10000). Reopen the note to apply a change to this value. |
+| **External dictionary file** | *(empty)* | Absolute path to a plain-text dictionary (one word per line). Empty means the plugin uses its own private word list. See [External dictionary](#external-dictionary). |
+| **Rule overrides (JSON)** | *(empty)* | *Advanced.* A JSON object of `{"RuleName": true \| false}` applied on top of the defaults, e.g. `{"SpelledNumbers": false}`. Invalid JSON is ignored. |
+
+## Installation
+
+### From the Joplin plugin marketplace
+
+Once the plugin is listed: in Joplin desktop, go to **Tools → Options → Plugins**, search for
+**Harper**, and click **Install**. Restart Joplin when prompted.
+
+### Manually (.jpl from GitHub releases)
+
+1. Download `io.github.pmslava.harper.jpl` from the
+   [latest release](https://github.com/pmslava/joplin-plugin-harper/releases).
+2. In Joplin desktop, go to **Tools → Options → Plugins**.
+3. Under **Manage your plugins**, use the gear/⋮ menu → **Install from file**, and select the
+   downloaded `.jpl`.
+4. Restart Joplin when prompted.
+
+## Requirements and limits
+
+- **Joplin desktop, version 3.1 or newer.** The plugin uses Joplin's CodeMirror 6 editor
+  integration, which requires 3.1+.
+- **Markdown editor only.** Harper checks the Markdown (CodeMirror) editor. It does **not** work in
+  the Rich Text (WYSIWYG) editor, which offers no hook for this kind of decoration.
+- **Desktop only.** There is no mobile build.
+- **About 16 MB.** The plugin bundles Harper's WebAssembly engine so it can run offline, which makes
+  the `.jpl` roughly 16 MB — larger than a typical plugin, but that is the whole checker, downloaded
+  once.
+- **Startup warm-up.** The first check after you open a note takes a second or two while the engine
+  loads and warms up. After that, re-checking a typical note is fast — on the order of ~50 ms for a
+  few kilobytes of text.
+
+## Privacy
+
+Harper runs locally and makes **no network calls**. Your note text is passed to the bundled
+WebAssembly engine inside Joplin and nowhere else — nothing is uploaded, and there is no telemetry.
+The external dictionary, if you use one, is a file on your own disk.
+
+## Development
+
+```bash
+npm install
+npm test          # builds the plugin and runs the harness suite (incl. performance budgets)
+npm run test:e2e  # full end-to-end suite: launches a real Joplin desktop under Xvfb (Linux)
+npm run dist      # build only -> publish/io.github.pmslava.harper.jpl
+```
+
+**Architecture in one line:** the grammar checker (harper.js `LocalLinter`, WASM) runs in the
+plugin main process, and a CodeMirror 6 content script draws the underlines and the suggestion card,
+talking to it over Joplin's `postMessage` bridge.
+
+For the full design, the WASM loading approach, the UI spec, and the research behind the plugin, see
+[`docs/`](docs/) — in particular [`docs/SPEC.md`](docs/SPEC.md).
+
+## License
+
+The plugin is licensed under the [MIT License](LICENSE).
+
+It embeds and is powered by [Harper](https://github.com/automattic/harper) (via the
+[`harper.js`](https://www.npmjs.com/package/harper.js) package), which is developed by **Automattic**
+and licensed under the **Apache License 2.0**. All credit for the grammar-checking engine goes to the
+Harper project — this plugin only integrates it into Joplin.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "joplin-plugin-harper",
+  "version": "1.0.0",
+  "description": "Fast, offline, private grammar and spelling checking for the Joplin desktop Markdown editor, powered by Harper.",
+  "author": "pmslava",
+  "homepage": "https://github.com/pmslava/joplin-plugin-harper#readme",
+  "bugs": {
+    "url": "https://github.com/pmslava/joplin-plugin-harper/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pmslava/joplin-plugin-harper.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dist": "webpack --env joplin-plugin-config=buildMain && webpack --env joplin-plugin-config=buildExtraScripts && webpack --env joplin-plugin-config=createArchive",
+    "test": "npm run dist && node test/run.js",
+    "setup:e2e": "bash scripts/setup-e2e.sh",
+    "test:e2e": "npm run dist && npm run setup:e2e && xvfb-run -a --server-args=\"-screen 0 1920x1080x24\" playwright test",
+    "prepare": "npm run dist",
+    "update": "npm install -g generator-joplin && yo joplin --node-package-manager npm --update --force",
+    "updateVersion": "webpack --env joplin-plugin-config=updateVersion"
+  },
+  "license": "MIT",
+  "keywords": [
+    "joplin-plugin",
+    "joplin",
+    "harper",
+    "grammar",
+    "spelling",
+    "spell-check",
+    "linter",
+    "proofreading",
+    "writing"
+  ],
+  "devDependencies": {
+    "@codemirror/lint": "^6.8.0",
+    "@codemirror/state": "^6.4.0",
+    "@codemirror/view": "^6.26.0",
+    "@joplin/lib": "~2.9",
+    "@playwright/test": "^1.62.0",
+    "@types/node": "^18.7.13",
+    "chalk": "^4.1.0",
+    "copy-webpack-plugin": "^11.0.0",
+    "fs-extra": "^10.1.0",
+    "glob": "^8.0.3",
+    "playwright": "^1.62.0",
+    "tar": "^6.1.11",
+    "ts-loader": "^9.3.1",
+    "typescript": "^5.4.5",
+    "webpack": "^5.74.0",
+    "webpack-cli": "^4.10.0"
+  },
+  "dependencies": {
+    "harper.js": "2.7.0"
+  },
+  "files": [
+    "publish"
+  ]
+}

package/publish/io.github.pmslava.harper.json

@@ -0,0 +1,44 @@
+{
+	"manifest_version": 1,
+	"id": "io.github.pmslava.harper",
+	"app_min_version": "3.1",
+	"platforms": [
+		"desktop"
+	],
+	"version": "1.0.0",
+	"name": "Harper",
+	"description": "Fast, offline, private grammar and spelling checking for the Joplin desktop Markdown editor, powered by Harper. Per-kind coloured underlines, a suggestion card with one-click fixes, add-to-dictionary, ignore and disable-rule, plus American, British, Australian and Canadian dialects.",
+	"author": "pmslava",
+	"homepage_url": "https://github.com/pmslava/joplin-plugin-harper",
+	"repository_url": "https://github.com/pmslava/joplin-plugin-harper",
+	"keywords": [
+		"harper",
+		"grammar",
+		"spelling",
+		"spell-check",
+		"linter",
+		"proofreading",
+		"writing",
+		"editor"
+	],
+	"categories": [
+		"editor",
+		"productivity"
+	],
+	"screenshots": [
+		{
+			"src": "docs/screenshots/card-light.png",
+			"label": "The Harper suggestion card in the Markdown editor: the lint kind, the message with the flagged word, one-click suggestion pills, add-to-dictionary and dismiss, next to the coloured underlines in the text"
+		},
+		{
+			"src": "docs/screenshots/card-dark.png",
+			"label": "The same suggestion card in Joplin's dark theme, showing a spelling lint with correction pills and the add-to-dictionary action"
+		},
+		{
+			"src": "docs/screenshots/underlines-light.png",
+			"label": "Close-up of the per-kind coloured squiggly underlines: a red spelling underline and a green word-choice underline"
+		}
+	],
+	"_publish_hash": "sha256:99b54a0c8bd600ca46cc585fe9b030937e42e6f8b0366f0b9b5cd80bd1bea390",
+	"_publish_commit": "main:78fa2d759308fc08feef00f6895df5e4bf460bc7"
+}