From 0bc92ab7d12b4cd27c48e76563363f239762d19c Mon Sep 17 00:00:00 2001
From: sudacode <suda@sudacode.com>
Date: Mon, 13 Jul 2026 01:26:32 -0700
Subject: [PATCH] fix(tsukihime): finish rename outside src and harden API base
 URL

CodeRabbit caught that the rename stopped at src/, leaving the mpv plugin
emitting the old CLI flag.

- plugin/subminer/session_bindings.lua: openTsukihime -> --open-tsukihime
  (the old flag no longer exists, so the overlay shortcut was a no-op)
- docs-site: rename the integration page, nav entry, and shortcuts row;
  rewrite the page for the TsukiHime API rather than find-and-replace
- changes/: rename the changeset and describe TsukiHime
- config.example.jsonc (+ docs-site copy): regenerated from definitions
- settings registry: route tsukihime.* to Integrations with the branded
  TsukiHime label (it was falling through to Advanced)
- tsukihimeFetchJson: apiBaseUrl is user config, so a malformed or
  non-HTTP(S) value now returns a structured error instead of throwing
---
 changes/animetosho-english-subtitles.md |  4 --
 changes/tsukihime-english-subtitles.md  |  4 ++
 config.example.jsonc                    | 16 ++---
 docs-site/.vitepress/config.ts          |  2 +-
 docs-site/animetosho-integration.md     | 73 -----------------------
 docs-site/public/config.example.jsonc   | 16 ++---
 docs-site/shortcuts.md                  |  2 +-
 docs-site/tsukihime-integration.md      | 77 +++++++++++++++++++++++++
 plugin/subminer/session_bindings.lua    |  4 +-
 src/config/settings/registry.test.ts    |  2 +
 src/config/settings/registry.ts         |  3 +-
 src/tsukihime/fetch-limits.test.ts      | 16 +++++
 src/tsukihime/utils.ts                  | 13 ++++-
 13 files changed, 133 insertions(+), 99 deletions(-)
 delete mode 100644 changes/animetosho-english-subtitles.md
 create mode 100644 changes/tsukihime-english-subtitles.md
 delete mode 100644 docs-site/animetosho-integration.md
 create mode 100644 docs-site/tsukihime-integration.md

diff --git a/changes/animetosho-english-subtitles.md b/changes/animetosho-english-subtitles.md
deleted file mode 100644
index 60907887..00000000
--- a/changes/animetosho-english-subtitles.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: added
-area: overlay
-
-- Added an Animetosho integration for downloading English (and Japanese) subtitles, mirroring the Jimaku flow: `Ctrl+Shift+T` (configurable via `shortcuts.openAnimetosho`) opens an in-overlay modal with two language tabs (the first follows `secondarySub.secondarySubLanguages`, defaulting to English; the second is Japanese) that parses the current video filename, searches Animetosho releases, lists extracted text subtitle tracks filtered by the active tab, then downloads the chosen track, decompresses it (requires the `xz` binary), saves it next to the video with a language suffix (`<video>.en.<ext>`, `.ja` for Japanese tracks, etc.), and loads it into mpv immediately - Japanese tracks as the primary subtitle, other languages as the secondary subtitle. No API key is required; also reachable via `subminer --open-animetosho`, the `__animetosho-open` keybinding command, and configurable under a new `animetosho` config section.
\ No newline at end of file
diff --git a/changes/tsukihime-english-subtitles.md b/changes/tsukihime-english-subtitles.md
new file mode 100644
index 00000000..b78c5e61
--- /dev/null
+++ b/changes/tsukihime-english-subtitles.md
@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- Added a TsukiHime integration for downloading English (and Japanese) subtitles, mirroring the Jimaku flow: `Ctrl+Shift+T` (configurable via `shortcuts.openTsukihime`) opens an in-overlay modal with two language tabs (the first follows `secondarySub.secondarySubLanguages`, defaulting to English; the second is Japanese) that parses the current video filename, searches TsukiHime releases, lists extracted text subtitle tracks filtered by the active tab, then downloads the chosen track, decompresses it (requires the `xz` binary), saves it next to the video with a language suffix (`<video>.en.<ext>`, `.ja` for Japanese tracks, etc.), and loads it into mpv immediately - Japanese tracks as the primary subtitle, other languages as the secondary subtitle. No API key is required; also reachable via `subminer --open-tsukihime`, the `__tsukihime-open` keybinding command, and configurable under a new `tsukihime` config section. TsukiHime is the successor to Animetosho, which stops processing new releases in May 2026; it imported the Animetosho index and mirrors its attachment storage, so older releases stay reachable.
diff --git a/config.example.jsonc b/config.example.jsonc
index 008f2290..617ba00e 100644
--- a/config.example.jsonc
+++ b/config.example.jsonc
@@ -205,7 +205,7 @@
     "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
     "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
-    "openAnimetosho": "Ctrl+Shift+T", // Accelerator that opens the Animetosho subtitle search modal (English/Japanese tabs).
+    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (English/Japanese tabs).
     "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
     "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -614,14 +614,14 @@
   }, // Jimaku API configuration and defaults.
 
   // ==========================================
-  // Animetosho
-  // Animetosho subtitle search configuration (English and Japanese). No API key required.
-  // Hot-reload: Animetosho changes apply to the next Animetosho request.
+  // TsukiHime
+  // TsukiHime subtitle search configuration (English and Japanese). No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
   // ==========================================
-  "animetosho": {
-    "apiBaseUrl": "https://feed.animetosho.org", // Base URL of the Animetosho JSON feed API. No API key required.
-    "maxSearchResults": 10 // Maximum Animetosho search results returned.
-  }, // Animetosho subtitle search configuration (English and Japanese). No API key required.
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration (English and Japanese). No API key required.
 
   // ==========================================
   // YouTube Playback Settings
diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts
index c20fc4dd..e842aba8 100644
--- a/docs-site/.vitepress/config.ts
+++ b/docs-site/.vitepress/config.ts
@@ -327,7 +327,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Jellyfin', link: '/jellyfin-integration' },
       { text: 'YouTube', link: '/youtube-integration' },
       { text: 'Jimaku', link: '/jimaku-integration' },
-      { text: 'Animetosho', link: '/animetosho-integration' },
+      { text: 'TsukiHime', link: '/tsukihime-integration' },
       { text: 'AniList', link: '/anilist-integration' },
       { text: 'AniSkip', link: '/aniskip-integration' },
       { text: 'Character Dictionary', link: '/character-dictionary' },
diff --git a/docs-site/animetosho-integration.md b/docs-site/animetosho-integration.md
deleted file mode 100644
index b7e56919..00000000
--- a/docs-site/animetosho-integration.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Animetosho Integration
-
-[Animetosho](https://animetosho.org) mirrors anime torrent releases and extracts every attachment - including embedded subtitle tracks - from the release files, hosting them for direct download. SubMiner integrates with the Animetosho JSON feed API so you can pull English subtitles for the currently playing episode straight from the overlay, no torrent client involved. Downloaded subtitles are decompressed, saved next to the video, and loaded into mpv immediately.
-
-This is the English-side companion to the [Jimaku integration](/jimaku-integration): Jimaku covers Japanese subtitles, Animetosho covers your secondary language (English by default). Releases that ship multiple languages (e.g. Netflix `[MultiSub]` rips) expose them all; the modal's tabs pick which ones you see, and each download is saved with its own language suffix.
-
-::: tip No API key required
-Unlike Jimaku, Animetosho needs no account or API key. The only requirement is the `xz` binary on your `PATH` - Animetosho serves extracted subtitles xz-compressed, and SubMiner shells out to `xz` to decompress them. Most Linux distributions ship it by default (package `xz` or `xz-utils`).
-:::
-
-## How It Works
-
-The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by language: the first tab follows your `secondarySub.secondarySubLanguages` config (defaults to English when unset, and the tab is labeled accordingly - e.g. "German" if you configure `["de"]`), and the second tab is always **Japanese**. Tracks with no language tag stay visible on the first tab.
-
-When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.
-
-From there:
-
-1. **Search** - SubMiner queries the Animetosho feed with `<title> <episode>`. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), with size and file count.
-2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
-3. **Download** - Selecting a track downloads the xz-compressed subtitle from Animetosho's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as the **primary** subtitle; any other language loads as the **secondary** subtitle, so your Japanese primary track stays in place. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.
-
-Because releases on Animetosho are the same files circulating as torrents, picking the release that matches your local file (same group, same version) gives you subtitles with exact timing - no resync needed. If your file is a raw or from a different group, pick any release of the same episode and adjust timing with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`) if necessary.
-
-### Modal Keyboard Shortcuts
-
-| Key                       | Action                          |
-| ------------------------- | ------------------------------- |
-| `Enter` (in text field)      | Search                             |
-| `Enter` (in list)            | Select release / download track    |
-| `Arrow Up` / `Arrow Down`    | Navigate releases or tracks        |
-| `Arrow Left` / `Arrow Right` | Switch English / Japanese tab      |
-| `Escape`                     | Close modal                        |
-
-## Configuration
-
-The integration works out of the box. An optional `animetosho` section in `config.jsonc` tunes it:
-
-```jsonc
-{
-  "animetosho": {
-    "apiBaseUrl": "https://feed.animetosho.org",
-    "maxSearchResults": 10,
-  },
-}
-```
-
-| Option                        | Type     | Default                         | Description                                                                   |
-| ----------------------------- | -------- | ------------------------------- | ----------------------------------------------------------------------------- |
-| `animetosho.apiBaseUrl`       | `string` | `"https://feed.animetosho.org"` | Base URL of the Animetosho JSON feed API. Only change this if using a mirror. |
-| `animetosho.maxSearchResults` | `number` | `10`                            | Maximum number of releases returned per search.                               |
-
-The keyboard shortcut is configured separately under `shortcuts`:
-
-```jsonc
-{
-  "shortcuts": {
-    "openAnimetosho": "Ctrl+Shift+T", // default; set to null to disable
-  },
-}
-```
-
-## Other Ways to Open It
-
-- CLI: `subminer --open-animetosho`
-- Keybinding command: bind any key to `["__animetosho-open"]` in the `keybindings` array
-
-## Troubleshooting
-
-- **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
-- **"Batch releases are not supported"** - the Animetosho feed API only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
-- **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
-- **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.
diff --git a/docs-site/public/config.example.jsonc b/docs-site/public/config.example.jsonc
index 008f2290..617ba00e 100644
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -205,7 +205,7 @@
     "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
     "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
-    "openAnimetosho": "Ctrl+Shift+T", // Accelerator that opens the Animetosho subtitle search modal (English/Japanese tabs).
+    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (English/Japanese tabs).
     "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
     "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -614,14 +614,14 @@
   }, // Jimaku API configuration and defaults.
 
   // ==========================================
-  // Animetosho
-  // Animetosho subtitle search configuration (English and Japanese). No API key required.
-  // Hot-reload: Animetosho changes apply to the next Animetosho request.
+  // TsukiHime
+  // TsukiHime subtitle search configuration (English and Japanese). No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
   // ==========================================
-  "animetosho": {
-    "apiBaseUrl": "https://feed.animetosho.org", // Base URL of the Animetosho JSON feed API. No API key required.
-    "maxSearchResults": 10 // Maximum Animetosho search results returned.
-  }, // Animetosho subtitle search configuration (English and Japanese). No API key required.
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration (English and Japanese). No API key required.
 
   // ==========================================
   // YouTube Playback Settings
diff --git a/docs-site/shortcuts.md b/docs-site/shortcuts.md
index f7ac467b..521c9c54 100644
--- a/docs-site/shortcuts.md
+++ b/docs-site/shortcuts.md
@@ -82,7 +82,7 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 | `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`             |
 | `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                |
 | `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                     |
-| `Ctrl+Shift+T`     | Open Animetosho subtitle search modal (EN/JA tabs)       | `shortcuts.openAnimetosho`                 |
+| `Ctrl+Shift+T`     | Open TsukiHime subtitle search modal (EN/JA tabs)       | `shortcuts.openTsukihime`                 |
 | `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`      |
 | `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                              |
 | `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                 |
diff --git a/docs-site/tsukihime-integration.md b/docs-site/tsukihime-integration.md
new file mode 100644
index 00000000..3a434fdb
--- /dev/null
+++ b/docs-site/tsukihime-integration.md
@@ -0,0 +1,77 @@
+# TsukiHime Integration
+
+[TsukiHime](https://tsukihime.org) tracks anime torrent releases and extracts every attachment - including embedded subtitle tracks - from the release files, hosting them for direct download. SubMiner integrates with the TsukiHime API so you can pull English subtitles for the currently playing episode straight from the overlay, no torrent client involved. Downloaded subtitles are decompressed, saved next to the video, and loaded into mpv immediately.
+
+This is the English-side companion to the [Jimaku integration](/jimaku-integration): Jimaku covers Japanese subtitles, TsukiHime covers your secondary language (English by default). Releases that ship multiple languages (e.g. Netflix `[MultiSub]` rips) expose them all; the modal's tabs pick which ones you see, and each download is saved with its own language suffix.
+
+::: tip Successor to Animetosho
+TsukiHime replaces [Animetosho](https://animetosho.org), which stops processing new releases in May 2026. TsukiHime imported the Animetosho index and mirrors its attachment storage, so older releases stay reachable alongside new ones.
+:::
+
+::: tip No API key required
+Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is the `xz` binary on your `PATH` - TsukiHime serves extracted subtitles xz-compressed, and SubMiner shells out to `xz` to decompress them. Most Linux distributions ship it by default (package `xz` or `xz-utils`).
+:::
+
+## How It Works
+
+The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by language: the first tab follows your `secondarySub.secondarySubLanguages` config (defaults to English when unset, and the tab is labeled accordingly - e.g. "German" if you configure `["de"]`), and the second tab is always **Japanese**. Tracks with no language tag stay visible on the first tab.
+
+When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.
+
+From there:
+
+1. **Search** - SubMiner queries TsukiHime with `<title> <episode>`. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), each showing size, file count, and the subtitle languages the release carries.
+2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
+3. **Download** - Selecting a track downloads the xz-compressed subtitle from TsukiHime's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as the **primary** subtitle; any other language loads as the **secondary** subtitle, so your Japanese primary track stays in place. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.
+
+Because releases on TsukiHime are the same files circulating as torrents, picking the release that matches your local file (same group, same version) gives you subtitles with exact timing - no resync needed. If your file is a raw or from a different group, pick any release of the same episode and adjust timing with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`) if necessary.
+
+### Modal Keyboard Shortcuts
+
+| Key                          | Action                          |
+| ---------------------------- | ------------------------------- |
+| `Enter` (in text field)      | Search                          |
+| `Enter` (in list)            | Select release / download track |
+| `Arrow Up` / `Arrow Down`    | Navigate releases or tracks     |
+| `Arrow Left` / `Arrow Right` | Switch English / Japanese tab   |
+| `Escape`                     | Close modal                     |
+
+## Configuration
+
+The integration works out of the box. An optional `tsukihime` section in `config.jsonc` tunes it:
+
+```jsonc
+{
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1",
+    "maxSearchResults": 10,
+  },
+}
+```
+
+| Option                       | Type     | Default                          | Description                                                                |
+| ---------------------------- | -------- | -------------------------------- | -------------------------------------------------------------------------- |
+| `tsukihime.apiBaseUrl`       | `string` | `"https://api.tsukihime.org/v1"` | Base URL of the TsukiHime API. Only change this if using a mirror.         |
+| `tsukihime.maxSearchResults` | `number` | `10`                             | Maximum number of releases returned per search (the API caps this at 100). |
+
+The keyboard shortcut is configured separately under `shortcuts`:
+
+```jsonc
+{
+  "shortcuts": {
+    "openTsukihime": "Ctrl+Shift+T", // default; set to null to disable
+  },
+}
+```
+
+## Other Ways to Open It
+
+- CLI: `subminer --open-tsukihime`
+- Keybinding command: bind any key to `["__tsukihime-open"]` in the `keybindings` array
+
+## Troubleshooting
+
+- **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
+- **"Batch releases are not supported"** - TsukiHime only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
+- **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
+- **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.
diff --git a/plugin/subminer/session_bindings.lua b/plugin/subminer/session_bindings.lua
index 7bc8ef02..51aa7c7c 100644
--- a/plugin/subminer/session_bindings.lua
+++ b/plugin/subminer/session_bindings.lua
@@ -254,8 +254,8 @@ function M.create(ctx)
 			return { "--open-runtime-options" }
 		elseif action_id == "openJimaku" then
 			return { "--open-jimaku" }
-		elseif action_id == "openAnimetosho" then
-			return { "--open-animetosho" }
+		elseif action_id == "openTsukihime" then
+			return { "--open-tsukihime" }
 		elseif action_id == "openYoutubePicker" then
 			return { "--open-youtube-picker" }
 		elseif action_id == "openSessionHelp" then
diff --git a/src/config/settings/registry.test.ts b/src/config/settings/registry.test.ts
index a806d993..e8390dba 100644
--- a/src/config/settings/registry.test.ts
+++ b/src/config/settings/registry.test.ts
@@ -247,6 +247,8 @@ test('settings registry routes playback-related integrations into integrations',
   assert.equal(field('jimaku.apiBaseUrl').section, 'Jimaku');
   assert.equal(field('subsync.replace').category, 'integrations');
   assert.equal(field('subsync.replace').section, 'Subtitle Sync');
+  assert.equal(field('tsukihime.apiBaseUrl').category, 'integrations');
+  assert.equal(field('tsukihime.apiBaseUrl').section, 'TsukiHime');
 });
 
 test('settings registry puts feature toggles first, then other toggles alphabetically', () => {
diff --git a/src/config/settings/registry.ts b/src/config/settings/registry.ts
index 423b0780..980b9145 100644
--- a/src/config/settings/registry.ts
+++ b/src/config/settings/registry.ts
@@ -422,7 +422,7 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
   if (path.startsWith('mpv.') || path.startsWith('youtube.')) {
     return { category: 'behavior', section: topSection(path) };
   }
-  if (path.startsWith('jimaku.')) {
+  if (path.startsWith('jimaku.') || path.startsWith('tsukihime.')) {
     return { category: 'integrations', section: topSection(path) };
   }
   if (path.startsWith('subsync.')) {
@@ -486,6 +486,7 @@ function topSection(path: string): string {
     notifications: 'Notifications',
     subsync: 'Subtitle Sync',
     texthooker: 'Texthooker',
+    tsukihime: 'TsukiHime',
     updates: 'Updates',
     websocket: 'WebSocket server',
     yomitan: 'Yomitan',
diff --git a/src/tsukihime/fetch-limits.test.ts b/src/tsukihime/fetch-limits.test.ts
index 0d78cad1..28f4f5c4 100644
--- a/src/tsukihime/fetch-limits.test.ts
+++ b/src/tsukihime/fetch-limits.test.ts
@@ -117,3 +117,19 @@ test('tsukihimeFetchJson still parses a normal response', async () => {
     await server.close();
   }
 });
+
+test('tsukihimeFetchJson reports a structured error for a malformed base URL', async () => {
+  const result = await tsukihimeFetchJson('/search/torrents', {}, { baseUrl: 'not a url' });
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.match(result.error.error, /base url/i);
+  }
+});
+
+test('tsukihimeFetchJson rejects non-HTTP(S) base URLs', async () => {
+  const result = await tsukihimeFetchJson('/search/torrents', {}, { baseUrl: 'file:///etc' });
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.match(result.error.error, /http/i);
+  }
+});
diff --git a/src/tsukihime/utils.ts b/src/tsukihime/utils.ts
index 5b01f7af..05f10f43 100644
--- a/src/tsukihime/utils.ts
+++ b/src/tsukihime/utils.ts
@@ -215,7 +215,18 @@ export async function tsukihimeFetchJson<T>(
 ): Promise<TsukihimeApiResponse<T>> {
   // Concatenate instead of new URL(endpoint, base): the API base ends in a
   // path segment (/v1) that URL resolution would drop for absolute endpoints.
-  const url = new URL(`${options.baseUrl.replace(/\/+$/, '')}${endpoint}`);
+  // baseUrl comes from user config, so a bad value must not throw here.
+  let url: URL;
+  try {
+    url = new URL(`${options.baseUrl.replace(/\/+$/, '')}${endpoint}`);
+  } catch {
+    logger.error(`Invalid TsukiHime API base URL: ${options.baseUrl}`);
+    return { ok: false, error: { error: 'Invalid TsukiHime API base URL.' } };
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    logger.error(`Unsupported TsukiHime API protocol: ${url.protocol}`);
+    return { ok: false, error: { error: 'TsukiHime API URL must use HTTP or HTTPS.' } };
+  }
   for (const [key, value] of Object.entries(query)) {
     if (value === null || value === undefined) continue;
     url.searchParams.set(key, String(value));