Name the mods a modpack import is about to touch, and say what it will do to each

[Pixnop]

NekoJess exported a 200-mod pack for a friend and read an import table of nothing but modids, which is why she thought the launcher was pulling in a mod she had never installed. It was not: all 202 ids probe clean, 199 resolve to themselves and 3 are not on the database at all, but a table of th3dungeon, terraprety and thetruearchimedesscrew gives a player no way to see that, and the table said nothing about what each row was going to do to her folder until after it had done it.

Five commits, in order.

The export carries the local name. Each manifest entry now writes the display name from the installed copy's modinfo.json next to the modid and the version. The reader takes a manifest with names and one without, because every pack exported until now has none. The name is a label only, the modid is still the identifier, and building the manifest moved from the export hook into the mods adapter so a test can pin the shape.

The table labels each row with the best name it has. modpackRowLabel takes the mod database name once the lookup resolved it, then the name the pack was exported with, then the modid. A plan item that named itself after its own modid counts as unnamed, which is what makes the three unresolvable rows fall through to their local names instead of repeating the id twice. The modid stays as a second line whenever the label is not the modid itself, and the row key is still the modid.

The plan is visible before Import is clicked. planModpackImport already decided all of it, so modpackRowStatus reads a plan item back as the sentence its row shows: new install, update from one version to another, downgrade, already installed, not on the mod database, no release. The lookups moved from the Import click to the moment the manifest opens, since they cost the same either way and the import needs them regardless. Import waits on them and says so. Once an entry starts moving, what happened outranks what was going to happen, so the live status wins the row back.

The "not on the mod database" wording says what was checked. Her three ids resolve to nothing because the hub's Alloy Calculator listing declares alloycalculator while her copy declares alloycalculatorstuzzichino. The old "Not found on ModDB" read as if the mod did not exist, which is what sent her looking for it. A note under the table now says no listing there declares the mod id in any of its releases, so those copies are most likely forks or private builds and have to be installed by hand.

A copy the pack does not accept says so before it is replaced. satisfyingCopy accepts an installed copy only when it is enabled and at the exact version the manifest names, so a mod whose version string was edited by hand, or one the player had turned off, is re-downloaded over the top. Nothing changes about what gets installed. The row says the installed copy will be replaced and names both versions.

When the lookups run, and how many at once

Worth calling out on its own because it changes when the launcher talks to the mod database, not just what the table says.

Before this branch, the detail lookups happened on the Import click. They now happen when the manifest loads. That is the whole reason the table can name a mod and say what will happen to it before the player commits to anything: the plan needs those lookups, and running them on open costs exactly what running them on click cost. Only the entries the installed folder does not already satisfy are asked about, same as before.

What that changed is who triggers the fan-out. A 200-mod pack used to send 200 requests at the mod database when the player pressed a button; it now sends them off a file chooser. Nothing downstream bounded that. pathsHandlers.ts lanes downloads and archive work through ConcurrencyLimiter, but QUERY_URL had no ceiling of any kind, so the burst went out as one open socket per mod.

QUERY_URL now runs its request inside a six-slot limiter in the main process, declared and shut down the same way the download and archive lanes are, with before-quit wired to it alongside them. Six is the per-host connection cap Chrome and Firefox have used for years, so a burst from the launcher is no heavier on a community-run site than an ordinary visit to one of its pages, and 200 lookups in lanes of six is 34 rounds, seconds rather than minutes. The bound sits in the IPC layer rather than in the popup because every caller of the channel shares the one remote host and only the main process sees all of them at once: Manage Mods resolves one detail per installed mod and fans out the same way.

tests/ipc/netHandlersDispatch.test.ts pins it through the real handler with the transport stubbed. Forty requests go in, every one held open until the peak has been read, and the peak is asserted to be six with all forty answered. The expected peak is written out as a literal rather than read back from the constant, so raising the bound in the source fails the test instead of moving it.

A queued lookup looks to the renderer exactly like a slow one, which is what the "Checking the mod database..." state already renders, and Import stays disabled until the plan exists. Queueing cannot trip a request's own timeout either: requestBoundedText starts its wall clock inside the task, and the limiter does not run the task until a slot is free. The effect that fires the lookups cancels on cleanup, so a batch that comes back after the popup was closed and re-opened on another pack is dropped instead of landing on the new table.

One row, before and after:

Before                             After
------------------------------     -----------------------------------------------
th3dungeon   1.5.2   Pending       Ancient Dungeons   1.5.2   Update from 1.4.0 to 1.5.2
                                   th3dungeon

Review fixes

Zaldaryon's review on 0b661b6 caught two real gaps, both about a case this branch newly reaches. Four commits on top fix them and the two non-blocking follow-ups.

A mod name over 256 characters no longer fails Export Modpack. toModpackManifest copied mod.name verbatim, the scanner reads a modinfo.json name up to 4096 characters, and parseModpackManifest's assertString(entry.name, "mod name", 256) refused anything past 256, so one long-named installed mod failed the whole export. A label must never be the reason an export fails, so toModpackManifest now clamps the name through a new domain helper, clampModpackModName, cutting to the cap on a UTF-16 boundary that never splits a surrogate pair. The cap itself is one constant, MAX_MODPACK_MOD_NAME_LENGTH, read by both the writer and the reader, so the two cannot drift apart again. Covered in the domain (the clamp, including the surrogate-pair boundary), in the adapter (an over-length name comes out clamped), and at the IPC handler (a name at exactly the cap exports and re-imports cleanly).

A lookup that never answered no longer reads as "not on the mod database". useQueryMod caught every failure alike and returned undefined, so a transport failure was indistinguishable from a clean 404. With the database unreachable, every unresolved entry became not-on-moddb, and the note under the table told the player, before they had clicked anything, that those mods were forks or private builds to install by hand. useQueryMod now returns a discriminated outcome (found / not-found / failed), a 404 read off parseModDetailResponse's own envelope check is the only thing that counts as not-found, and everything else (a thrown network error, a timeout, an envelope that does not check out as a real 404) is failed. planModpackImport takes an optional set of modids whose lookup failed and gives those a new skip reason, lookup-failed, kept apart from not-on-moddb. The import popup renders it as "Couldn't reach the mod database" with its own note and a retry action, and swaps the whole table for an unreachable state, retry included, when every lookup in the batch failed. The two other callers of useQueryMod (the installed-mods update scan, the single-release catalog) still fold not-found and failed together, which is all they have ever needed.

Non-blocking, both done. text-orange-300 and text-blue-400 (the downgrade/replace and downloading/update row hues) are now pinned in tests/text-contrast.test.ts the way #366 pins the release-table verdicts, computing the ratio through the same paletteForeground/tailwindColor machinery rather than quoting Zaldaryon's measured 9.47:1 and 6.28:1. And #386 tracks his other note, quoting his reasoning: the single global QUERY_URL FIFO means Manage Mods' still-unbounded installed-mod fan-out can make a later catalog or filter fetch wait behind a full page scan, so bounding that fan-out at its own call site would keep one page's scan from starving another page's first request.

Mutants

Each applied alone against the committed tree, tests run, tree restored and checked clean before the next.

Mutant	Result
modpackRowLabel returns the modid instead of the local name	red, 4 tests, two domain and two on the popup
modpackRowStatus returns "new" where it returns "update"	red, 2 tests, the domain derivation and the Carry On row
the replaced-copy branch collapses into "update"	red, 3 tests, the disabled copy and the hand-edited one
the manifest reader requires a name on every entry	red, 2 tests, both of them older manifests with no names
the export drops the name from each entry	red, 4 tests, the adapter and the three export flows on the page
the limiter is removed and QUERY_URL calls the transport bare	red, peak 40 against an expected 6
the bound is raised from 6 to 12	red, peak 12 against an expected 6
the bound is lowered from 6 to 3	red, peak 3 against an expected 6
the import effect's cancelled flag is dropped	red, the stale pack's details land on the re-opened table
the writer stops clamping the name (toModpackManifest copies it verbatim again)	red, the over-length export test
a transport failure is folded back into not-on-moddb in useQueryMod	red, 4 tests: the mixed-failure note, the all-unreachable state, both retries
retry is made a no-op	red, 2 tests, both retry paths
either pinned hue (text-orange-300, text-blue-400) is regressed to text-red-700	red, 2.49:1 on the popup table backdrop, below the 4.5 floor

Testing

On head 677bb06:

• npm run typecheck: passed (node, web, tests).
• npm run lint:ci: 0 errors, 15 pre-existing React Hooks warnings.
• npm run format:check: passed.
• npm run test:coverage: 169 files, 2195 passed, 2 skipped; 93.57% statements, 90.37% branches, 93.25% functions, 95.15% lines locally, floors 87 / 85 / 85 / 89.
• npm run build:unpack: passed, Electron 44.1.1 Linux.
• npx vitest run tests/domain/mods/importModpack.test.ts: 43 passed.
• npx vitest run tests/renderer-dom/importModpackPopup.test.tsx: 15 passed, one row of every kind read before Import is clicked, the close/re-open mid-lookup, and the mixed/all-failed/retry lookup-failure cases.
• npx vitest run tests/ipc/modsHandlers.test.ts: 20 passed, including the name-clamp boundary on export and import.
• npx vitest run tests/renderer/importModpackAdapter.test.ts: 4 passed, including the clamp.
• npx vitest run tests/text-contrast.test.ts: 21 passed, including the two new hue pins.
• npx vitest run tests/ipc/netHandlersDispatch.test.ts: 5 passed, including the concurrency bound.

Related issues

• Modpack import lists mods by modid only, so players cannot tell what is being installed #379
• More mod management options: enable and disable mods, plus per-installation profiles #287, which is why a disabled copy is reinstalled rather than reported as already present
• fix(mods): stop Manage Mods going blank on a null tag from the mod database #371, the same table's other reader

Closes #379

Type

• Bug fix
• Feature
• Performance
• Refactor or cleanup
• Tests only
• Docs or build

Checklist

• Targets dev, not main.
• npm run typecheck passes.
• npm run lint:ci passes.
• npm run format:check passes.
• npm run test:coverage passes, coverage at or above the floor in vitest.config.ts.
• npm run build:unpack passes.

[Zaldaryon]

The table this adds is the right feature and most of it holds up. Two things block it, both about a case the change now reaches that it did not before.

A mod name over 256 characters now fails Export Modpack entirely. parseModpackManifest in src/ipc/handlers/modsHandlers.ts validates both directions: IMPORT_MODPACK at line 231 and EXPORT_MODPACK at line 177. toModpackManifest now copies mod.name verbatim into every entry, and the mod scanner reads a modinfo.json name through readText with its default MAX_TEXT_LENGTH of 4096, while the new assertString(entry.name, "mod name", 256) refuses anything over 256. So one installed mod whose declared name is longer than 256 characters makes the whole export fail with { success: false } and a generic notification, no partial result, on an action that could not fail this way before this PR. Raise the cap to the 4096 the scanner already allows, or clamp or omit an over-length name in toModpackManifest rather than failing the export, and add a test with an over-length name.

The "not on the mod database" note states a cause it cannot know, and now shows it eagerly. useQueryMod catches every failure, logs it, and returns undefined, so a transport failure is indistinguishable from a real 404. With the mod database unreachable, every unresolved entry becomes not-on-moddb, and the new note under the table states as fact: "N mod(s) are not on the mod database: no listing there declares the mod id in any of its releases. Those are most likely forks or private builds, and have to be installed by hand." On a transient outage that is wrong, and wrong in a way that sends the player toward a manual install they do not need. Unlike the pre-PR behaviour it now appears on manifest open, before the player has clicked anything. Have the effect tell a lookup that failed from one that answered 404, by reporting the failure out of queryMod or counting failures in the effect, and show a "couldn't reach the mod database" state instead. At minimum, soften the note so it does not assert a cause.

The rest checks out, so a re-review does not need to redo it. The manifest reader is backward compatible with a nameless pack and refuses a wrong-typed name. The eager effect cannot loop: queryMod is useCallback([])-stable and installedMods is component state, so the installed memo identity is stable, and the cancelled flag covers close, reopen and unmount. The QUERY_URL limiter is declared and shut down on before-quit exactly the way the pathsHandlers.ts download and archive lanes are, and queueing cannot burn a request's own timeout because requestBoundedText starts its wall clock inside the task the limiter runs. modpackRowStatus agrees with the planner's own downgrade comparison and handles every skip and install shape, including the #287 disabled copy and a hand-edited version string both landing on replace. modpackRowLabel's resolved-name-equals-modid guard matches the planner's not-on-moddb arm, and the label is a plain JSX text child with no injection surface. I measured the two new hues against the popup table backdrop: text-orange-300 at 9.47:1 and text-blue-400 at 6.28:1, both well over the 4.5 floor.

Two non-blocking follow-ups. The single global FIFO means Manage Mods' still-unbounded installed-mod fan-out can make a later catalog or filter fetch wait behind a full page scan; bounding that fan-out at its own call site would keep one page's scan from starving another page's first request, and a follow-up issue is enough. And text-orange-300 and text-blue-400 should be pinned in tests/text-contrast.test.ts the way #366 pinned the release-table verdicts, since text-red-700 shipped at 2.18:1 precisely because nothing measured it.

Full local gate on 0b661b6 is green: typecheck, lint:ci (0 errors, 15 pre-existing hook warnings), format:check, test:coverage at 93.48% statements and 90.29% branches above the 87/85 floors, build:unpack. The findings above are behaviour, not gate failures.

[Pixnop]

Both blockers were right, fixed on top at 677bb06.

The over-length name. You were right that toModpackManifest copying mod.name verbatim past the reader's 256-character cap could fail a whole export over one label. Fixed by clamping in toModpackManifest through a new domain helper, clampModpackModName, rather than raising the reader's cap: both now read the same MAX_MODPACK_MOD_NAME_LENGTH constant, so they can't drift apart again. Tests: tests/domain/mods/importModpack.test.ts (the clamp itself, including the surrogate-pair boundary so an emoji at the cut isn't split), tests/renderer/importModpackAdapter.test.ts (an over-length name comes out of the adapter clamped), tests/ipc/modsHandlers.test.ts (a name at exactly the cap exports and re-imports cleanly).

The eager "not on the mod database" note. You were right that folding a transport failure into the same bucket as a 404 turns an outage into a false claim about forks and private builds. Fixed by having useQueryMod return a discriminated outcome (found / not-found / failed), with only a genuine 404 off parseModDetailResponse's envelope check counting as not-found. planModpackImport takes the failed modids and gives them their own skip reason, lookup-failed, rendered as "Couldn't reach the mod database" with a retry action, and the whole table is replaced by an unreachable state when every lookup in the batch failed. Tests: tests/renderer-dom/importModpackPopup.test.tsx, all-fail, a mix of a real 404 and a transport failure, and both retry paths re-running the lookups.

Non-blocking: text-orange-300 and text-blue-400 are pinned in tests/text-contrast.test.ts, computed the same way the release-table verdicts are rather than quoted. The QUERY_URL fan-out note is #386.

[Pixnop]

Rebased onto the current dev tip (22b167c, which now carries #380). No source change beyond the review fixes already described; the required checks are re-running on the new head.

[Pixnop]

Correction to the line above: the head did not move, 677bb06 was already on top of the dev tip that carries #380, so no new push happened and the green checks on this head are the current ones.

[Zaldaryon]

Re-review, head 677bb06.

Both blockers are fixed. I ran the full local gate on 677bb06 and it is green: typecheck, lint:ci (0 errors; the 15 hook warnings are all pre-existing and none are in the files this PR touches), format:check, test:coverage (2195 passed, 2 skipped, 93.57% statements and 90.37% branches against the 87 and 85 floors), and build:unpack. Every required CI context passes on this head.

The over-length name. clampModpackModName in src/domain/mods/importModpack.ts cuts to MAX_MODPACK_MOD_NAME_LENGTH, and both the writer (toModpackManifest) and the reader (parseModpackManifest) now read that one constant, so they cannot drift. The boundary is right: assertString rejects only length > maxLength and length === 0, a name at exactly 256 passes both directions, and the clamp can never return an empty string because it only runs on input longer than the cap. The surrogate guard holds, a prefix cut can only orphan a high surrogate at the tail and the regex drops it. useExportModpack is the only caller of toModpackManifest and both the plain and the (Server) export buttons route through it, so nothing sends an unclamped name into the reader anymore. A hand-crafted file with a 300-character name is still a clean refusal through the existing try/catch, not a crash. Tests cover export at the cap, export one character over the cap refused, and the export-then-import round trip.

The eager "not on the mod database" note. useQueryMod now returns found | not-found | failed, and only a real 404 (api-error with statusCode "404", which is how the v1 envelope reports a missing mod) counts as not-found. A thrown transport error, a non-2xx HTTP status, and a payload that does not parse all land on failed. planModpackImport takes the failed set and gives those entries their own lookup-failed reason, the popup renders it as "Couldn't reach the mod database" with a retry, and a batch where every lookup failed replaces the table with the unreachable panel instead of a page of wrong "not on the mod database" rows. The fix does not flip the bug the other way: a genuine 404 still reads as not-found. The retry effect resets details and failedModids before it re-runs, so a retry shows the checking state again, and the close-mid-lookup path is still covered by its test. The two other useQueryMod callers keep their old behaviour; folding not-found and failed together is all a compatibility scan or a single-release catalog has ever needed.

Non-blocking, for a follow-up:

Opening a second, different pack in the same session without the popup unmounting renders one frame of the new pack's rows scored against the previous pack's details and failedModids, with Import enabled on that stale plan, before the effect resets and re-resolves. useModReleaseCatalog handles the same shape by resetting in the !manifest branch rather than bailing out of it. modStatuses has the same one-frame staleness and predates this PR.

The retry button and the allLookupsFailed panel have no !importing guard, so a retry click during an import starts a fresh round of lookups that cannot change the plan already running, and if the database is down by then it swaps the table and the progress bar for the unreachable panel while downloads continue. Gate both on !importing.

allLookupsFailed is computed over modpackEntriesToResolve, which excludes entries already satisfied on disk, so a pack that is 39 mods already installed and 1 mod a failed lookup shows "none of these mods could be checked yet" and hides the 39. Wording the panel in terms of the entries that needed a lookup, or requiring the whole manifest to be unresolved, would fix it.

A lookup-failed row falls through statusColor and StatusIcon to the red "prohibited" treatment, the same as not-on-moddb, while the note right below it is orange with a warning icon. It reads as a hard failure in the table and a transient one everywhere else. text-red-400 on the popup table row is also still unpinned in tests/text-contrast.test.ts, the same gap that shipped text-red-700 at 2.18:1.

malformed-response folds into failed silently. A page that exists but whose body does not parse now offers a retry that cannot succeed and logs nothing, while useQueryMods logs the reason on the same failure. One debug line on the !parsed.ok branch would make it diagnosable.

The QUERY_URL limiter is one 6-wide lane shared by every caller of the channel, so a 200-entry manifest queues the browse-mods catalog and the tag and version fetches behind up to 200 detail lookups. The bound is the right call. A per-path-kind lane, or one reserved slot for non-/mod/ paths, would keep the other screens responsive. This overlaps #386.

Approving. The non-blocking items are worth a follow-up, none of them block this.