diff --git a/.Rbuildignore b/.Rbuildignore
index 87b9f63c..a373fd95 100755
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -38,9 +38,9 @@
 ^refCheck\.R$
 ^\.Rproj\.user$
 ^local_validation$
-^R/hypeR_examples\.R$
 ^testing_manuscripts$
 ^artifacts$
 ^sigs_in_repo\.csv$
 ^\.lintr$
 ^CONTRIBUTING\.md$
+^\.superpowers$
diff --git a/.claude/skills/connect-sigrepo-mcp/SKILL.md b/.claude/skills/connect-sigrepo-mcp/SKILL.md
index f7ff92ec..9d8594be 100644
--- a/.claude/skills/connect-sigrepo-mcp/SKILL.md
+++ b/.claude/skills/connect-sigrepo-mcp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: connect-sigrepo-mcp
-description: Registers SigRepo's MCP server (https://sigrepo.org/mcp/) with Claude Code if it isn't already added, asks the user for their SigRepo api_key, and carries it forward for the rest of the session so every MCP tool call (search_signatures, run_enrichment, etc.) includes it automatically. Use this whenever the user asks to "connect to SigRepo's MCP," "set up SigRepo MCP," "use the SigRepo MCP tools," or wants to start querying/searching SigRepo signatures, collections, gene sets, or run enrichment via MCP but hasn't already supplied an api_key this session.
+description: Registers SigRepo's MCP server (https://sigrepo.org/mcp/) with Claude Code if it isn't already added, asks the user for their SigRepo api_key, and carries it forward for the rest of the session so every MCP tool call (search_signatures, compare_signatures, etc.) includes it automatically. Use this whenever the user asks to "connect to SigRepo's MCP," "set up SigRepo MCP," "use the SigRepo MCP tools," or wants to start querying/searching SigRepo signatures, collections, gene sets, or run enrichment via MCP but hasn't already supplied an api_key this session.
 ---
 
 # Connect to SigRepo's MCP server
@@ -53,7 +53,7 @@ it to a file, and don't echo it back after this point.
 The registered server exposes 9 tools: `list_vocabulary`,
 `search_signatures`, `get_signature_context`, `compare_signatures`,
 `search_collections`, `search_geneset_resources`, `search_geneset_entries`,
-`search_features`, and `run_enrichment`. A reasonable starting point if the
+`search_features`, and `rummagene_enrich`. A reasonable starting point if the
 person hasn't said what they want yet: call `list_vocabulary` to show what
 organisms/phenotypes/assay types actually have data, then `search_signatures`
 from there.
diff --git a/.github/workflows/R-CMD-CHECK.yaml b/.github/workflows/R-CMD-CHECK.yaml
index 239d9beb..25d6cdfd 100755
--- a/.github/workflows/R-CMD-CHECK.yaml
+++ b/.github/workflows/R-CMD-CHECK.yaml
@@ -2,7 +2,7 @@
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
-    branches: [master]
+    branches: [master, dev]
     paths-ignore:
       - '.github/workflows/document.yaml'
       - '.github/workflows/gh-pages-pkgdown.yaml'
@@ -12,7 +12,7 @@ on:
       - '**.Rmd'
       - '.gitignore'
   pull_request:
-    branches: [master]
+    branches: [master, dev]
   release:
     types: [published]
   workflow_dispatch:
@@ -43,6 +43,13 @@ jobs:
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       R_KEEP_PKG_SOURCE: yes
+      # test_conn_handler defaults host to sigrepo.org and api_host to the
+      # production IP. Nothing here reaches production today: this check supplies
+      # no SIGREPO_TEST_DB_USER or _PASSWORD, runs with --no-tests --no-examples,
+      # and every @examples block is wrapped in \dontrun. Pin the hosts anyway, so
+      # that stays true if credentials are ever added to this workflow.
+      SIGREPO_TEST_DB_HOST: 127.0.0.1
+      SIGREPO_TEST_API_HOST: http://127.0.0.1
 
     steps:
       - uses: actions/checkout@v4
diff --git a/.github/workflows/close-linked-issues.yml b/.github/workflows/close-linked-issues.yml
new file mode 100644
index 00000000..bebc3127
--- /dev/null
+++ b/.github/workflows/close-linked-issues.yml
@@ -0,0 +1,72 @@
+name: close-linked-issues
+
+on:
+  # pull_request_target, not pull_request: the job needs a token that can close
+  # issues, and it never checks out or runs the pull request's code, so the
+  # usual risk of that trigger does not apply.
+  pull_request_target:
+    types: [closed]
+    # GitHub honours `Closes #NNN` only when a pull request merges into the
+    # default branch, which is master. Pull requests target dev, so without
+    # this job the keyword does nothing until a release carries dev into
+    # master, and every issue resolved in between sits open on the board.
+    branches: [dev]
+
+permissions:
+  issues: write
+
+jobs:
+  close:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const { owner, repo } = context.repo;
+
+            // Keywords inside HTML comments and code are not instructions.
+            const body = (pr.body || '')
+              .replace(/<!--[\s\S]*?-->/g, '')
+              .replace(/```[\s\S]*?```/g, '')
+              .replace(/`[^`\n]*`/g, '');
+
+            // The same keywords GitHub recognises, followed by #N, owner/repo#N
+            // or an issue URL.
+            const pattern = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\s+(?:([\w.-]+\/[\w.-]+)?#(\d+)|https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/(\d+))/gi;
+
+            const numbers = new Set();
+            for (const m of body.matchAll(pattern)) {
+              const target = (m[1] || m[3] || `${owner}/${repo}`).toLowerCase();
+              const number = Number(m[2] || m[4]);
+              if (target !== `${owner}/${repo}`.toLowerCase()) {
+                // This job's token reaches this repository only.
+                core.warning(`${target}#${number} is in another repository; close it by hand.`);
+                continue;
+              }
+              numbers.add(number);
+            }
+
+            if (numbers.size === 0) {
+              core.info(`#${pr.number} names no issue to close.`);
+              return;
+            }
+
+            for (const issue_number of numbers) {
+              const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number });
+              if (issue.pull_request || issue.state === 'closed') {
+                core.info(`#${issue_number} skipped: ${issue.pull_request ? 'a pull request' : 'already closed'}.`);
+                continue;
+              }
+              await github.rest.issues.createComment({
+                owner, repo, issue_number,
+                body: `Closed by #${pr.number}, merged into \`${pr.base.ref}\`.`,
+              });
+              await github.rest.issues.update({
+                owner, repo, issue_number,
+                state: 'closed',
+                state_reason: 'completed',
+              });
+              core.info(`#${issue_number} closed.`);
+            }
diff --git a/.github/workflows/notify-staging-image.yml b/.github/workflows/notify-staging-image.yml
new file mode 100644
index 00000000..a6683cab
--- /dev/null
+++ b/.github/workflows/notify-staging-image.yml
@@ -0,0 +1,77 @@
+name: notify staging image
+
+# Tell SigRepo_Server to rebuild the staging image when this package changes on
+# dev.
+#
+# Why this is needed at all: the server calls SigRepo:: by namespace, which
+# resolves from the installed library, not from the /SigRepo bind mount --
+# inside the container find.package("SigRepo") returns
+# /usr/local/lib/R/site-library/SigRepo, and nothing calls pkgload::load_all()
+# on that path. So this package reaches the server ONLY through the Docker
+# image. SigRepo_Server's build watches only its own files, so without this
+# workflow a push here triggers nothing and montilab.bu.edu quietly keeps
+# running whatever client was baked in last.
+#
+# That gap matters most for R/sqlFunctions.R: lookup_table_sql is called 21
+# times across 5 of the server's API files and twice in its Shiny app, and its
+# query shape is what made getSignature take 4.6 seconds before the index fix.
+# Only the staging replica has enough rows for a regression to show.
+
+on:
+  push:
+    branches: [dev]
+    # Only what changes the INSTALLED package. A vignette or README push does
+    # not need a nine minute image build.
+    paths:
+      - "R/**"
+      - "src/**"
+      - "inst/**"
+      - "DESCRIPTION"
+      - "NAMESPACE"
+      - ".github/workflows/notify-staging-image.yml"
+  workflow_dispatch:
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ask SigRepo_Server to rebuild montilab/sigrepo:dev
+        env:
+          # secrets.GITHUB_TOKEN cannot reach another repository. GH_DOCS is the
+          # cross-repo token this project already uses; it needs access to
+          # montilab/SigRepo_Server for this to work.
+          TOKEN: ${{ secrets.GH_DOCS }}
+          SHA: ${{ github.sha }}
+          REF: ${{ github.ref_name }}
+        run: |
+          set -uo pipefail
+
+          if [ -z "${TOKEN:-}" ]; then
+            echo "::error::GH_DOCS is not set, so the staging image cannot be rebuilt."
+            echo "::error::Staging would silently keep running an older client."
+            exit 1
+          fi
+
+          code=$(curl -s -o /tmp/dispatch.out -w '%{http_code}' -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/montilab/SigRepo_Server/dispatches \
+            -d "{\"event_type\":\"sigrepo-client-updated\",\"client_payload\":{\"ref\":\"$REF\",\"sha\":\"$SHA\"}}")
+
+          if [ "$code" = "204" ]; then
+            echo "Asked SigRepo_Server to rebuild montilab/sigrepo:dev for $REF@${SHA:0:8}"
+            exit 0
+          fi
+
+          # 404 rather than 403 is the usual failure here: GitHub will not
+          # confirm the existence of a repository the token cannot see, so an
+          # under-scoped token looks exactly like a missing one. Say so, because
+          # failing quietly means staging goes stale while looking healthy.
+          echo "::error::Dispatch to montilab/SigRepo_Server failed with HTTP $code."
+          if [ "$code" = "404" ]; then
+            echo "::error::404 here usually means GH_DOCS cannot see SigRepo_Server,"
+            echo "::error::not that the repository is missing. Check the token's scope."
+          fi
+          cat /tmp/dispatch.out
+          exit 1
diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml
index 9b2f0500..861e2e73 100644
--- a/.github/workflows/pkgdown.yaml
+++ b/.github/workflows/pkgdown.yaml
@@ -28,6 +28,14 @@ jobs:
       # the site shows the example code without output.
       SIGREPO_TEST_DB_USER: ${{ secrets.SIGREPO_TEST_DB_USER }}
       SIGREPO_TEST_DB_PASSWORD: ${{ secrets.SIGREPO_TEST_DB_PASSWORD }}
+      # These two are the reason this matters. test_conn_handler still DEFAULTS
+      # host to sigrepo.org and api_host to the production IP, and the vignettes
+      # gate evaluation on the credentials alone, not on the host. So the moment
+      # the secrets above are set, an unpinned build would run addSignature()
+      # and deleteSignature() against PRODUCTION, which is read-only for
+      # signatures by policy. Point them at a stack that is safe to write to.
+      SIGREPO_TEST_DB_HOST: 127.0.0.1
+      SIGREPO_TEST_API_HOST: http://127.0.0.1
     steps:
       - uses: actions/checkout@v4
 
diff --git a/.github/workflows/validation.yaml b/.github/workflows/validation.yaml
index 53b0b55e..447b80e1 100644
--- a/.github/workflows/validation.yaml
+++ b/.github/workflows/validation.yaml
@@ -2,9 +2,9 @@ name: validation
 
 on:
   pull_request:
-    branches: [master]
+    branches: [master, dev]
   push:
-    branches: [master]
+    branches: [master, dev]
     paths:
       - "R/**"
       - "tests/**"
@@ -133,8 +133,10 @@ jobs:
       #
       # /init_db is schema + reference tables + a full MSigDB gene set build,
       # and msigdbr downloads that data from zenodo.org on first use. No test in
-      # this package uses MSigDB: the hypeR and hypeR-GEM tests construct their
-      # own gene sets inline and pass them to runHypeR(). So the download bought
+      # this package needs the database's MSigDB gene sets: the hypeR and
+      # hypeR-GEM client tests construct their own gene sets inline, and the one
+      # MSigDB test, test_hypeR_genesets.R, does a live Hallmark fetch through
+      # msigdbr on the client side that skips on error. So the download bought
       # this suite nothing and made every run depend on a third-party service
       # staying up -- which is how a zenodo 504 turned into a red build here.
       - name: Initialize schema and reference data
diff --git a/.gitignore b/.gitignore
index 53e124ac..b2dfd4b0 100755
--- a/.gitignore
+++ b/.gitignore
@@ -21,7 +21,7 @@
 
 # Ignore folders
 .Rproj.user/
-docs/
+docs/*
 
 # Local-only validation harness: runs against a developer's own MySQL/API
 # stack via local_validation/.env.local-validation. Never belongs on a remote.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 53b5eeac..4c08de9c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,16 +15,40 @@ are linked before any code is written:
 
 ```sh
 gh issue create --repo montilab/SigRepo --title "..." --body "..."
-gh issue develop <number> --base master --checkout
+gh issue develop <number> --base dev --checkout
 ```
 
 Branch names carry no type prefix — not `fix/`, not `feat/`, not `chore/`. The
 default `<number>-<title-slug>` that `gh` produces is what we want.
 
+**`dev` is what gets worked on; `master` is what is live.** Branches come off
+`dev` and pull requests go into `dev`. `dev` is deployed to the staging instance
+at montilab.bu.edu, where a change is exercised against a full replica of the
+data before anyone outside sees it.
+
+`master` is production: it is what sigrepo.org runs. It gains commits only
+through a release pull request from `dev`, and direct pushes to it are blocked.
+If something ever has to be hotfixed straight onto `master`, merge `master` back
+into `dev` the same day. That one rule is what stops the two branches drifting
+apart, which is how this arrangement usually goes wrong.
+
+A change that spans both repositories is released from both or from neither.
+Otherwise production runs a client and a server from different lines, and the
+resulting bug report makes no sense to anyone.
+
 **Every pull request closes its issue.** Put `Closes #NNN` in the description.
 This is the rule the rest depends on: it is what lets the board move by itself and
 what leaves the reason for a change next to the change.
 
+Note what closes it. GitHub itself honours `Closes #NNN` only when a pull request
+merges into the repository's default branch, which is `master`, and pull requests
+target `dev`. The `close-linked-issues` workflow covers the gap: when a pull
+request merges into `dev`, it closes each issue the description names and leaves
+a comment naming the pull request. So a closed issue means merged into `dev`, not
+live; what is live is whatever the last release carried into `master`. The
+workflow reaches its own repository only, so an issue in the other repository
+that your pull request resolves has to be closed by hand.
+
 **Ideas and work are different things.** An idea states a goal, is labelled `idea`,
 and is never closed by a pull request. A task or bug is real work: it links to the
 idea it serves, and it is closed by the pull request that resolves it. An idea is
@@ -56,6 +80,30 @@ in the issue, or label it `needs-decision` and say what the decision is.
 nobody answers. Closing is not a judgement on the idea; reopen it when it matters
 again.
 
+## Reaching the staging instance
+
+montilab.bu.edu keeps every port bound to `127.0.0.1`. It is a shared,
+BU-managed host, the lab has already been warned once about an exposed port, and
+the staging database holds real signatures behind accounts that can edit them.
+So nothing there is published to the network, and reaching it means your own SSH
+tunnel with your own BU account:
+
+```sh
+ssh -N -o ExitOnForwardFailure=yes \
+  -L 9051:127.0.0.1:8051 -L 9050:127.0.0.1:8050 -L 9020:127.0.0.1:8020 montilab
+```
+
+with `Host montilab` proxying through `scc4.bu.edu` — not scc2, which has no
+route to the BUMC network. Local ports are offset by 1000 so they do not collide
+with a stack running on your own machine. If you already have a ControlMaster
+session open, that command returns immediately and the master process holds the
+forwards: the tunnel is live even though it looks like the command exited.
+
+Then open <http://127.0.0.1:9051>.
+
+This needs SCC access. If you do not have it, ask for a walkthrough rather than
+a port.
+
 ## Labels
 
 Exactly one type label, and exactly one status label.
diff --git a/DESCRIPTION b/DESCRIPTION
index 999f0980..ffa94046 100755
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: SigRepo
 Type: Package
 Title: Storing and processing omic signatures and collections
-Version: 1.0.0
+Version: 1.1.0
 Authors@R: 
   c(person(given="Reina", family="Chau", role=c("aut","cre"), 
            email="rchau88@bu.edu", comment=c(ORCID="0000-0003-3012-1404")), 
@@ -23,10 +23,16 @@ Imports:
   DBI,
   digest,
   dplyr,
+  fgsea,
+  ggplot2,
   httr,
+  hypeR (>= 2.0.0),
+  hypeR.GEM,
   jsonlite,
   methods,
+  msigdbr,
   OmicSignature (>= 1.4.1),
+  openxlsx,
   purrr,
   readr,
   rlang,
@@ -37,9 +43,6 @@ Remotes:
 Suggests:
   BiocManager,
   devtools,
-  fgsea,
-  hypeR,
-  hypeR.GEM,
   knitr,
   pkgdown,
   rmarkdown,
diff --git a/NAMESPACE b/NAMESPACE
index 752de258..aef0c679 100755
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -50,17 +50,27 @@ export(delete_table_sql)
 export(getAPIKey)
 export(getCollection)
 export(getDBColNames)
+export(getHypeRDifexp)
+export(getHypeRGenesets)
 export(getNumOfObs)
 export(getSignature)
 export(getSignatureFeatureSet)
 export(getVariableID)
 export(get_api_handle)
 export(get_handle)
+export(hypeRDotData)
+export(hypeREnrichmentData)
+export(hypeRSignatureKey)
+export(hypeRToExcel)
 export(inActivateUser)
 export(init_handle)
 export(insert_table_sql)
 export(lookup_table_sql)
+export(mergeDifexp)
 export(newConnHandler)
+export(plotHypeRDots)
+export(plotHypeREnrichment)
+export(plotHypeRMap)
 export(prepareHypeRSignatures)
 export(print_messages)
 export(protTransform)
@@ -70,6 +80,7 @@ export(runHypeR)
 export(runHyperGEM)
 export(searchAssayType)
 export(searchCollection)
+export(searchExternal)
 export(searchGenesetEntry)
 export(searchGenesetResource)
 export(searchGeneticVariantsFeatureSet)
@@ -102,9 +113,11 @@ export(updateTranscriptomicsFeatureSet)
 export(updateUser)
 export(user_grant_statements)
 export(verbose)
+export(writeSignatureSearchScript)
 import(DBI)
 import(OmicSignature)
 import(RMySQL)
 import(biomaRt)
 import(digest)
 import(readr)
+importFrom(rlang,.data)
diff --git a/NEWS.Rmd b/NEWS.Rmd
index 7ad14192..35e155ea 100644
--- a/NEWS.Rmd
+++ b/NEWS.Rmd
@@ -3,10 +3,252 @@
 output: rmarkdown::github_document
 ---
 
+# SigRepo 1.1.0
+
+## Breaking changes
+
+`runHypeR()` and `prepareHypeRSignatures()` now follow hypeR's own interface.
+
+- `runHypeR()` requires `organism` and `test`, with no default for either:
+  `runHypeR(omic_signature = sig, organism = "Homo sapiens", test = "hypergeometric", genesets = ...)`.
+  `organism` replaces `msigdb_species` (it is the MSigDB species with
+  `genesets = "msigdb"`), and a SigRepo signature whose `metadata$organism` is
+  different (ignoring case), or missing, is an error, so human and mouse
+  signatures run in separate calls. Before, the species silently defaulted to
+  `"Homo sapiens"` and mixed organisms were not detected.
+- hypeR, msigdbr, fgsea, ggplot2, openxlsx and hypeR.GEM are now imported
+  rather than suggested, so they install with SigRepo.
+
+- `runHypeR()` returns hypeR's `hyp` or `multihyp` instead of
+  `list(result, signatures, metadata)`, and hypeR's functions (`hyp_dots()`,
+  `hyp_emap()`, `hyp_to_rmd()`, ...) work on it directly. The type follows the
+  input, as in hypeR: a `hyp` for a single signature (one `OmicSignature`, id
+  or name) with hypergeometric `split = FALSE`, otherwise a `multihyp`, even
+  when only one query is left. `hyp_show()` takes a single
+  `hyp`, e.g. `hyp_show(res$data[[1]])`.
+- Each `hyp$info` ends with SigRepo provenance in a fixed order:
+  `SigRepo Signature ID`, `SigRepo Signature Name`, `Group Label`,
+  `Symbol Source`, `SigRepo Direction`, `SigRepo Ranked Table`,
+  `SigRepo Score Column`, `SigRepo Split`, `SigRepo Background Source`,
+  `SigRepo Features Unmapped`, `SigRepo Query Genes Removed`,
+  `SigRepo Genesets Dropped`, `SigRepo Genesets Dropped List`, `SigRepo FDR Scope`.
+- `method` is now `test = c("hypergeometric", "kstest")`. The `"hypergeo"`,
+  `"ks"` and `"gsea"` aliases are gone; use `test = "kstest"` for a ranked test.
+  `power` changes only the kstest `score`: `1`, the default, weights hits by
+  |score|; `0` runs hypeR's ranked (unweighted) signature, so its `score` and
+  `Signature Type = "ranked"` match hypeR's documentation. The p-value and FDR
+  come from hypeR's unweighted, one-sided KS test and do not depend on `power`;
+  it finds genesets enriched toward the top of the ranking, which is why every
+  kstest also runs a `| down` query on the negated scores.
+- kstest and fgsea always test both ends of the ranking; there is no
+  `direction` argument. kstest returns `"<label> | up"` (the scores) and
+  `"<label> | down"` (the negated scores) for every ranking, with the FDR
+  adjusted across both (`fdr_scope = "run"`); fgsea returns its ES > 0 and
+  ES < 0 pathways as `"<label> | up"` and `"<label> | down"`. Both rank the
+  whole difexp as one list, not split by `group_label` (categorical signatures
+  are ranked per category). A single signature therefore gives a `multihyp`
+  for both tests, and hypeR-native `signature` input for kstest is tested as
+  given and reversed.
+- `absolute` is removed from `runHypeR()`. hypeR marks it as not implemented,
+  and every run now uses `absolute = FALSE`.
+- `fdr = 1` (was 0.05) and `pval = 1` (new) match `hypeR::hypeR()`.
+- Hypergeometric runs follow the BS831 `hyperEnrichment()` conventions
+  (montilab.github.io/BS831), which differ from plain hypeR:
+  - `background = NULL` (the default) uses each signature's measured genes from
+    its difexp, "the number of annotated genes in the dataset". It uses 23467
+    instead when there is no difexp (silently) or when the difexp looks filtered
+    (with a warning): a transcriptomics difexp under 10,000 rows, a difexp no
+    more than twice its signature, or every `p_value`/`pvalue`/`adj_p` at most
+    0.05. kstest keeps 23467, since the ranked list is its universe. Pass
+    `background = 23467` for hypeR's behaviour or `"difexp"` to force the difexp.
+  - `min_query_genes = 4` skips, with a warning, a query with fewer than 4 genes
+    found in the genesets (`min.drawsize`).
+  - `fdr_scope = "run"` adjusts p-values across every query and geneset in the
+    call (`mht = TRUE`); `fdr_scope = "query"` adjusts within each query, as
+    hypeR does. `pval`/`fdr` filter on the chosen FDR.
+  With a gene-vector or `"difexp"` background, a hypergeometric query is first
+  reduced to the background genes (hypeR reduces only the genesets), with a
+  warning, so a gene-vector background can give different p-values than a
+  plain `hypeR::hypeR()` call on the unreduced query.
+- `genesets` is required: `genesets = "msigdb"` with `msigdb_collection`
+  (and optional `msigdb_species`, `msigdb_subcollection`), or your own named
+  list / `hypeR::gsets` / `hypeR::rgsets`. `msigdb_*` without `"msigdb"` is an error.
+- `split_by_group` is now `split` and defaults to `TRUE` (one hypergeometric
+  vector per `group_label`). Categorical signatures with scores are split by
+  category and score sign (`"<label> | <group> | up"`/`"| down"`), and kstest
+  ranks each category's own difexp rows; a single categorical signature
+  therefore returns a `multihyp` for kstest.
+- kstest skips a ranking whose scores are all equal (`constant_score`) or all
+  one sign (`unsigned_score`), per category for categorical signatures: such a
+  ranking cannot say which class a geneset is enriched in. `split_by_direction`, `feature_col` and `...` are removed.
+- `prepareHypeRSignatures()` returns `list(signatures, info, skipped)`.
+- Signatures that cannot produce a query are skipped with a warning instead of
+  aborting the run.
+
+## New
+
+- `mergeDifexp()` merges the difexp tables of several signatures into one
+  numeric matrix, one row per feature and one column per signature, the shape
+  that signature-by-signature correlation, clustering, PCA and reference
+  databases for tools such as `signatureSearch` expect. Signatures are given by
+  id, by name or as `OmicSignature` objects, as in `compareSignatures()`.
+  `value_col` picks the difexp column that fills the matrix (`"score"` by
+  default; `"logfc"`, `"p_value"`, `"adj_p"` or any other column work),
+  `features` keeps the union or the intersection of features, and `collapse`
+  reduces a feature's several probe rows to one value: `"max_abs"` (default),
+  `"min"` for p-value columns, `"mean"` or `"first"`.
+
+- `searchExternal()` asks the public signature search engines what looks like
+  a SigRepo signature. Give it a signature by id, name or `OmicSignature`, and
+  it translates the features to gene symbols (reference table first, then
+  biomaRt for Ensembl IDs), picks the organism, and queries Rummagene (gene
+  sets mined from PMC supplementary tables), RummaGEO (up/down gene sets
+  computed from GEO RNA-seq) and CORESH (GEO datasets ranked by how strongly
+  the genes are coregulated), one, two or all three in one call. Every result
+  is a data frame with the same first twelve columns, so the sources compare
+  side by side; `direction = "both"` sends the up and down features
+  separately. CORESH results carry the shareable results page as
+  `attr(x, "job_url")`. Human and mouse only for RummaGEO and CORESH, at most
+  500 genes (#265, serves #82).
+
+- `writeSignatureSearchScript()` writes an R script that runs a LINCS
+  connectivity search for one signature with Bioconductor's `signatureSearch`:
+  which perturbations produce the signature's expression pattern, and which
+  reverse it. SigRepo does not run the search or depend on `signatureSearch`,
+  whose reference database is about 2.5 GB; the script is run wherever
+  `signatureSearch` is installed, and saves the result table as a CSV and a
+  plot of the strongest hits as a PDF. The query is the signature's features by
+  the sign of `score`, strongest first. Only human transcriptomics signatures
+  with at least 10 features in each direction can be searched (#252).
+
+- `runHypeR()`, `prepareHypeRSignatures()` and `getHypeRGenesets()` document
+  which arguments are required (the signatures and genesets, plus `organism` and
+  `test` for `runHypeR()`) and which are
+  optional with a default, including what `NULL` means for `background`,
+  `query_names` and `seed`. `getHypeRDifexp()`, `hypeRToExcel()`,
+  `hypeRDotData()`, `hypeREnrichmentData()`, `hypeRSignatureKey()`,
+  `plotHypeRDots()`, `plotHypeREnrichment()` and `plotHypeRMap()` have the same
+  section; most need only the result object, and the enrichment functions also
+  need `geneset` (and `query` for a result with several queries). The error for
+  a call with no signatures now names `signature` alongside
+  `signature_id`, `signature_name` and `omic_signature`.
+
+- The annotation tutorial (`vignette("annotation-tutorial")`) walks through
+  searching SigRepo for signatures, running `runHypeR()` and plotting the
+  results.
+
+- Plotting for `runHypeR()` results, drawn from the result objects:
+  `plotHypeRDots()` (one column per query with the same top genesets for every
+  query, a readable -log10 significance scale, one-query results supported, and
+  `color_by = "score"` for NES/score), `plotHypeREnrichment()` (running
+  enrichment score with the leading edge for kstest and fgsea, Venn diagram for
+  hypergeometric, for any geneset without `plotting = TRUE`) and
+  `plotHypeRMap()` (hypeR's enrichment/hierarchy maps, returning `NULL` with a
+  warning where hypeR would error). Every plot is titled with the test that was
+  run ("Hypergeometric test", "KS test", "GSEA (fgsea)") unless `title` is
+  given. Dot plots of several signatures group each signature's columns under
+  a short code (`S1`, `S2`, ...) labelled by group or direction, with the full
+  names in the caption (`hypeRSignatureKey()` returns that key); a single
+  signature is named in the subtitle. `signature_key = FALSE` draws full query
+  names at 45 degrees instead, without clipping. For fgsea,
+  `plotHypeREnrichment()` and `hypeREnrichmentData()` take the signature name
+  as `query` and name the whole ranking rather than its up/down side
+  (`summary$ranking`).
+  `hypeRDotData()` and `hypeREnrichmentData()` return the underlying data.
+  A kstest `| down` query ranks the negated scores, so its `score` is negated
+  back onto the original ranking and `color_by = "score"` shows genesets
+  enriched at the bottom as negative, as fgsea's NES does.
+  `ggplot2` is in Suggests.
+
+- `runHypeR(test = "fgsea")` runs GSEA with `fgsea::fgseaMultilevel()`, ported
+  from hypeR's fgsea vignette wrapper. Unlike hypeR's kstest, whose p-values
+  ignore the score weights and test only the top of the ranking, fgsea gives
+  weighted permutation p-values, NES and the leading edge for both tails in one
+  run. Pathways are split by the sign of their enrichment score into
+  `"<query> | up"` and `"<query> | down"` hyps. `seed = 1` makes the p-values reproducible without touching the
+  session's random-number state; `fgsea_args` passes fgsea options such as
+  `minSize`/`maxSize`. The results work with `hyp_dots()`, `hyp_emap()`,
+  `rctbl_build()`, `hyp_to_rmd()` and `hypeRToExcel()`.
+
+- `getHypeRGenesets()` returns a named, versioned `hypeR::gsets` for MSigDB.
+  Mouse requests for human collections (e.g. C2, C5) now use ortholog mapping.
+- `hypeRToExcel()` writes a `hyp`/`multihyp` with Excel-safe, unique sheet
+  names (hypeR's `hyp_to_excel()` fails on names over 31 characters, which
+  most SigRepo signature names are) and an `index` sheet mapping each sheet to
+  its query and signature.
+- kstest `ks_source = c("difexp", "signature")`: `"signature"` ranks the
+  signature table, for signatures stored without a difexp.
+- `query_names`: a function of the query info table that returns the query
+  names, e.g. `function(info) paste(info$signature_id, info$group_label, sep = "_")`.
+- `prepareHypeRSignatures()$info` gains a `direction` column.
+- `signature =` takes hypeR-native input (a character vector, a named numeric
+  vector, or a named list of those) instead of SigRepo signatures, and still
+  gets backgrounds, the kstest guards, provenance and the return-type rule.
+- `getHypeRDifexp()` returns each signature's difexp with `resolved_symbol`,
+  so you can apply your own cutoffs and pass the genes to `signature =`.
+- `background` can be a named list giving each signature its own background
+  (number, gene vector or `"difexp"`), keyed by signature label or ID.
+- `hypeR (>= 2.0.0)` in Imports.
+
+## Fixes
+
+- A kstest query with a single geneset (passed that way, or left after the
+  zero-weight and full-coverage drops) now runs instead of failing with hypeR's
+  "dim(X) must have a positive length"; its FDR equals its p-value.
+- A gene-vector or `"difexp"` background now reduces kstest and fgsea rankings
+  to the background genes as well as the genesets, as it already did for
+  hypergeometric gene lists, with the same warning and
+  `SigRepo Query Genes Removed` count. A ranking left with no genes is skipped.
+
+- Gene symbols resolve from the table's symbol column, then (hypergeometric)
+  difexp symbols joined on `probe_id`, then the reference table by
+  `feature_name` and organism. `probe_id` is no longer read as an identifier,
+  and one signature's symbol column no longer leaks into the next.
+- The `probe_id` join to difexp symbols matches on (`probe_id`, `feature_name`),
+  so a `probe_id` repeated in difexp no longer hands a row another feature's
+  symbol. Without `feature_name` it joins on `probe_id` only when that is unique.
+- Query names are always unique (`"X | Up"`, `"X | Up (2)"`).
+- The kstest ranked list keeps the positive score when a gene's scores tie on
+  `|score|` with opposite signs, so it no longer depends on difexp row order.
+- `runHypeR()` errors on an invalid `background` (e.g. `"Difexp"`); both
+  functions error on a `split` that is not `TRUE`/`FALSE` and on
+  `omic_signature` supplied together with `signature_id`/`signature_name`.
+- kstest drops, with a warning, genesets hypeR cannot score: those whose hits
+  all have score 0 (`power != 0`) and those containing every query gene (any
+  power). hypeR would otherwise error or put scores on the wrong genesets.
+  Dropped genesets are also left out of the FDR adjustment, and are listed in
+  each `hyp$info`.
+- With `plotting = FALSE`, the empty placeholder plots hypeR stores for every
+  geneset are removed. They were most of the object's size (about 46 MB for a
+  Hallmark `hyp`).
+- A signature's gene symbols are resolved once per call, so a kstest with
+  `background = "difexp"` no longer looks up the reference table twice.
+- With `background = "difexp"`, a hypergeometric query is reduced to the genes
+  its difexp measured, with a warning; hypeR reduces only the genesets.
+- A query left with no genesets or no genes is skipped with a warning instead of
+  aborting the whole run.
+
+## Process
+
+- R CMD check and the validation workflow run on `dev` and on pull
+  requests into it, not only on `master`, so a change is checked before
+  it reaches the staging instance (#235).
+- CONTRIBUTING describes the dev model: `dev` is what gets worked on and
+  what staging runs, `master` is what sigrepo.org runs and gains commits
+  only through a release pull request, and a hotfix on `master` is merged
+  back into `dev` the same day. It also says that `Closes #NNN` on a pull
+  request into `dev` fires only when the release pull request carries the
+  change into `master` (#237, #239).
+- The `connect-sigrepo-mcp` skill no longer lists the withdrawn
+  `run_enrichment` MCP tool and now names `rummagene_enrich`, so its count
+  of nine tools is right (#251).
+
 # SigRepo 1.0.0
 * Documentation: https://montilab.github.io/SigRepo/
 * GitHub: https://github.com/montilab/SigRepo/
 * Uni-directional signatures may omit scores: the four `add*SignatureSet()` functions no longer require a non-empty `score`, which is stored as NULL and comes back as NA. `addSignature()` now rolls back and errors if the feature step stored no rows, instead of returning a signature id for an empty signature. Needs OmicSignature >= 1.4.1, which keeps NA-score rows (#258, montilab/SigRepo_Server#89).
+* `searchSignature()` searches instead of matching exactly: a term matches a field exactly when an exact match exists anywhere in that column, otherwise as a substring, so `signature_name = "M005"` finds every name containing it while `sample_type = "liver"` still returns only liver. Numbers match exactly, blank terms are ignored, and terms are literal (no regular expressions; LIKE wildcards are escaped). `type`, `assay_type`, `keywords`, `PMID`, `year`, `has_difexp`, `description` and `covariates` are new filters, and `type` and `assay_type` are validated against their declared members (#233, #230, #231).
+* `R/hypeR_examples.R`, a Shiny UI module left over from prototyping the server's Annotate tab, is removed from the package source along with its `.Rbuildignore` line. It was never built, exported or referenced (#248).
 * `addUser()` and `updateUser()` now grant privileges on the database the connection is on instead of a hard-coded `sigrepo` schema, and `checkDBTable()` reads `SHOW TABLES` by position, so seeding and lookups work on a database with any name (#245, montilab/SigRepo_Server#130).
 
 
diff --git a/NEWS.md b/NEWS.md
index b4a38fe0..e6b6602d 100755
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,309 @@
+# SigRepo 1.1.0
+
+## Breaking changes
+
+`runHypeR()` and `prepareHypeRSignatures()` now follow hypeR’s own
+interface.
+
+- `runHypeR()` requires `organism` and `test`, with no default for
+  either:
+  `runHypeR(omic_signature = sig, organism = "Homo sapiens", test = "hypergeometric", genesets = ...)`.
+  `organism` replaces `msigdb_species` (it is the MSigDB species with
+  `genesets = "msigdb"`), and a SigRepo signature whose
+  `metadata$organism` is different (ignoring case), or missing, is an
+  error, so human and mouse signatures run in separate calls. Before,
+  the species silently defaulted to `"Homo sapiens"` and mixed organisms
+  were not detected.
+
+- hypeR, msigdbr, fgsea, ggplot2, openxlsx and hypeR.GEM are now
+  imported rather than suggested, so they install with SigRepo.
+
+- `runHypeR()` returns hypeR’s `hyp` or `multihyp` instead of
+  `list(result, signatures, metadata)`, and hypeR’s functions
+  (`hyp_dots()`, `hyp_emap()`, `hyp_to_rmd()`, …) work on it directly.
+  The type follows the input, as in hypeR: a `hyp` for a single
+  signature (one `OmicSignature`, id or name) with hypergeometric
+  `split = FALSE`, otherwise a `multihyp`, even when only one query is
+  left. `hyp_show()` takes a single `hyp`,
+  e.g. `hyp_show(res$data[[1]])`.
+
+- Each `hyp$info` ends with SigRepo provenance in a fixed order:
+  `SigRepo Signature ID`, `SigRepo Signature Name`, `Group Label`,
+  `Symbol Source`, `SigRepo Direction`, `SigRepo Ranked Table`,
+  `SigRepo Score Column`, `SigRepo Split`, `SigRepo Background Source`,
+  `SigRepo Features Unmapped`, `SigRepo Query Genes Removed`,
+  `SigRepo Genesets Dropped`, `SigRepo Genesets Dropped List`,
+  `SigRepo FDR Scope`.
+
+- `method` is now `test = c("hypergeometric", "kstest")`. The
+  `"hypergeo"`, `"ks"` and `"gsea"` aliases are gone; use
+  `test = "kstest"` for a ranked test. `power` changes only the kstest
+  `score`: `1`, the default, weights hits by |score|; `0` runs hypeR’s
+  ranked (unweighted) signature, so its `score` and
+  `Signature Type = "ranked"` match hypeR’s documentation. The p-value
+  and FDR come from hypeR’s unweighted, one-sided KS test and do not
+  depend on `power`; it finds genesets enriched toward the top of the
+  ranking, which is why every kstest also runs a `| down` query on the
+  negated scores.
+
+- kstest and fgsea always test both ends of the ranking; there is no
+  `direction` argument. kstest returns `"<label> | up"` (the scores) and
+  `"<label> | down"` (the negated scores) for every ranking, with the
+  FDR adjusted across both (`fdr_scope = "run"`); fgsea returns its ES
+  &gt; 0 and ES &lt; 0 pathways as `"<label> | up"` and
+  `"<label> | down"`. Both rank the whole difexp as one list, not split
+  by `group_label` (categorical signatures are ranked per category). A
+  single signature therefore gives a `multihyp` for both tests, and
+  hypeR-native `signature` input for kstest is tested as given and
+  reversed.
+
+- `absolute` is removed from `runHypeR()`. hypeR marks it as not
+  implemented, and every run now uses `absolute = FALSE`.
+
+- `fdr = 1` (was 0.05) and `pval = 1` (new) match `hypeR::hypeR()`.
+
+- Hypergeometric runs follow the BS831 `hyperEnrichment()` conventions
+  (montilab.github.io/BS831), which differ from plain hypeR:
+
+  - `background = NULL` (the default) uses each signature’s measured
+    genes from its difexp, “the number of annotated genes in the
+    dataset”. It uses 23467 instead when there is no difexp (silently)
+    or when the difexp looks filtered (with a warning): a
+    transcriptomics difexp under 10,000 rows, a difexp no more than
+    twice its signature, or every `p_value`/`pvalue`/`adj_p` at most
+    0.05. kstest keeps 23467, since the ranked list is its universe.
+    Pass `background = 23467` for hypeR’s behaviour or `"difexp"` to
+    force the difexp.
+  - `min_query_genes = 4` skips, with a warning, a query with fewer than
+    4 genes found in the genesets (`min.drawsize`).
+  - `fdr_scope = "run"` adjusts p-values across every query and geneset
+    in the call (`mht = TRUE`); `fdr_scope = "query"` adjusts within
+    each query, as hypeR does. `pval`/`fdr` filter on the chosen FDR.
+    With a gene-vector or `"difexp"` background, a hypergeometric query
+    is first reduced to the background genes (hypeR reduces only the
+    genesets), with a warning, so a gene-vector background can give
+    different p-values than a plain `hypeR::hypeR()` call on the
+    unreduced query.
+
+- `genesets` is required: `genesets = "msigdb"` with `msigdb_collection`
+  (and optional `msigdb_species`, `msigdb_subcollection`), or your own
+  named list / `hypeR::gsets` / `hypeR::rgsets`. `msigdb_*` without
+  `"msigdb"` is an error.
+
+- `split_by_group` is now `split` and defaults to `TRUE` (one
+  hypergeometric vector per `group_label`). Categorical signatures with
+  scores are split by category and score sign
+  (`"<label> | <group> | up"`/`"| down"`), and kstest ranks each
+  category’s own difexp rows; a single categorical signature therefore
+  returns a `multihyp` for kstest.
+
+- kstest skips a ranking whose scores are all equal (`constant_score`)
+  or all one sign (`unsigned_score`), per category for categorical
+  signatures: such a ranking cannot say which class a geneset is
+  enriched in. `split_by_direction`, `feature_col` and `...` are
+  removed.
+
+- `prepareHypeRSignatures()` returns `list(signatures, info, skipped)`.
+
+- Signatures that cannot produce a query are skipped with a warning
+  instead of aborting the run.
+
+## New
+
+- `mergeDifexp()` merges the difexp tables of several signatures into
+  one numeric matrix, one row per feature and one column per signature,
+  the shape that signature-by-signature correlation, clustering, PCA and
+  reference databases for tools such as `signatureSearch` expect.
+  Signatures are given by id, by name or as `OmicSignature` objects, as
+  in `compareSignatures()`. `value_col` picks the difexp column that
+  fills the matrix (`"score"` by default; `"logfc"`, `"p_value"`,
+  `"adj_p"` or any other column work), `features` keeps the union or the
+  intersection of features, and `collapse` reduces a feature’s several
+  probe rows to one value: `"max_abs"` (default), `"min"` for p-value
+  columns, `"mean"` or `"first"`.
+
+- `searchExternal()` asks the public signature search engines what looks
+  like a SigRepo signature. Give it a signature by id, name or
+  `OmicSignature`, and it translates the features to gene symbols
+  (reference table first, then biomaRt for Ensembl IDs), picks the
+  organism, and queries Rummagene (gene sets mined from PMC
+  supplementary tables), RummaGEO (up/down gene sets computed from GEO
+  RNA-seq) and CORESH (GEO datasets ranked by how strongly the genes are
+  coregulated), one, two or all three in one call. Every result is a
+  data frame with the same first twelve columns, so the sources compare
+  side by side; `direction = "both"` sends the up and down features
+  separately. CORESH results carry the shareable results page as
+  `attr(x, "job_url")`. Human and mouse only for RummaGEO and CORESH, at
+  most 500 genes (#265, serves \#82).
+
+- `writeSignatureSearchScript()` writes an R script that runs a LINCS
+  connectivity search for one signature with Bioconductor’s
+  `signatureSearch`: which perturbations produce the signature’s
+  expression pattern, and which reverse it. SigRepo does not run the
+  search or depend on `signatureSearch`, whose reference database is
+  about 2.5 GB; the script is run wherever `signatureSearch` is
+  installed, and saves the result table as a CSV and a plot of the
+  strongest hits as a PDF. The query is the signature’s features by the
+  sign of `score`, strongest first. Only human transcriptomics
+  signatures with at least 10 features in each direction can be searched
+  (#252).
+
+- `runHypeR()`, `prepareHypeRSignatures()` and `getHypeRGenesets()`
+  document which arguments are required (the signatures and genesets,
+  plus `organism` and `test` for `runHypeR()`) and which are optional
+  with a default, including what `NULL` means for `background`,
+  `query_names` and `seed`. `getHypeRDifexp()`, `hypeRToExcel()`,
+  `hypeRDotData()`, `hypeREnrichmentData()`, `hypeRSignatureKey()`,
+  `plotHypeRDots()`, `plotHypeREnrichment()` and `plotHypeRMap()` have
+  the same section; most need only the result object, and the enrichment
+  functions also need `geneset` (and `query` for a result with several
+  queries). The error for a call with no signatures now names
+  `signature` alongside `signature_id`, `signature_name` and
+  `omic_signature`.
+
+- The annotation tutorial (`vignette("annotation-tutorial")`) walks
+  through searching SigRepo for signatures, running `runHypeR()` and
+  plotting the results.
+
+- Plotting for `runHypeR()` results, drawn from the result objects:
+  `plotHypeRDots()` (one column per query with the same top genesets for
+  every query, a readable -log10 significance scale, one-query results
+  supported, and `color_by = "score"` for NES/score),
+  `plotHypeREnrichment()` (running enrichment score with the leading
+  edge for kstest and fgsea, Venn diagram for hypergeometric, for any
+  geneset without `plotting = TRUE`) and `plotHypeRMap()` (hypeR’s
+  enrichment/hierarchy maps, returning `NULL` with a warning where hypeR
+  would error). Every plot is titled with the test that was run
+  (“Hypergeometric test”, “KS test”, “GSEA (fgsea)”) unless `title` is
+  given. Dot plots of several signatures group each signature’s columns
+  under a short code (`S1`, `S2`, …) labelled by group or direction,
+  with the full names in the caption (`hypeRSignatureKey()` returns that
+  key); a single signature is named in the subtitle.
+  `signature_key = FALSE` draws full query names at 45 degrees instead,
+  without clipping. For fgsea, `plotHypeREnrichment()` and
+  `hypeREnrichmentData()` take the signature name as `query` and name
+  the whole ranking rather than its up/down side (`summary$ranking`).
+  `hypeRDotData()` and `hypeREnrichmentData()` return the underlying
+  data. A kstest `| down` query ranks the negated scores, so its `score`
+  is negated back onto the original ranking and `color_by = "score"`
+  shows genesets enriched at the bottom as negative, as fgsea’s NES
+  does. `ggplot2` is in Suggests.
+
+- `runHypeR(test = "fgsea")` runs GSEA with `fgsea::fgseaMultilevel()`,
+  ported from hypeR’s fgsea vignette wrapper. Unlike hypeR’s kstest,
+  whose p-values ignore the score weights and test only the top of the
+  ranking, fgsea gives weighted permutation p-values, NES and the
+  leading edge for both tails in one run. Pathways are split by the sign
+  of their enrichment score into `"<query> | up"` and `"<query> | down"`
+  hyps. `seed = 1` makes the p-values reproducible without touching the
+  session’s random-number state; `fgsea_args` passes fgsea options such
+  as `minSize`/`maxSize`. The results work with `hyp_dots()`,
+  `hyp_emap()`, `rctbl_build()`, `hyp_to_rmd()` and `hypeRToExcel()`.
+
+- `getHypeRGenesets()` returns a named, versioned `hypeR::gsets` for
+  MSigDB. Mouse requests for human collections (e.g. C2, C5) now use
+  ortholog mapping.
+
+- `hypeRToExcel()` writes a `hyp`/`multihyp` with Excel-safe, unique
+  sheet names (hypeR’s `hyp_to_excel()` fails on names over 31
+  characters, which most SigRepo signature names are) and an `index`
+  sheet mapping each sheet to its query and signature.
+
+- kstest `ks_source = c("difexp", "signature")`: `"signature"` ranks the
+  signature table, for signatures stored without a difexp.
+
+- `query_names`: a function of the query info table that returns the
+  query names,
+  e.g. `function(info) paste(info$signature_id, info$group_label, sep = "_")`.
+
+- `prepareHypeRSignatures()$info` gains a `direction` column.
+
+- `signature =` takes hypeR-native input (a character vector, a named
+  numeric vector, or a named list of those) instead of SigRepo
+  signatures, and still gets backgrounds, the kstest guards, provenance
+  and the return-type rule.
+
+- `getHypeRDifexp()` returns each signature’s difexp with
+  `resolved_symbol`, so you can apply your own cutoffs and pass the
+  genes to `signature =`.
+
+- `background` can be a named list giving each signature its own
+  background (number, gene vector or `"difexp"`), keyed by signature
+  label or ID.
+
+- `hypeR (>= 2.0.0)` in Imports.
+
+## Fixes
+
+- A kstest query with a single geneset (passed that way, or left after
+  the zero-weight and full-coverage drops) now runs instead of failing
+  with hypeR’s “dim(X) must have a positive length”; its FDR equals its
+  p-value.
+
+- A gene-vector or `"difexp"` background now reduces kstest and fgsea
+  rankings to the background genes as well as the genesets, as it
+  already did for hypergeometric gene lists, with the same warning and
+  `SigRepo Query Genes Removed` count. A ranking left with no genes is
+  skipped.
+
+- Gene symbols resolve from the table’s symbol column, then
+  (hypergeometric) difexp symbols joined on `probe_id`, then the
+  reference table by `feature_name` and organism. `probe_id` is no
+  longer read as an identifier, and one signature’s symbol column no
+  longer leaks into the next.
+
+- The `probe_id` join to difexp symbols matches on (`probe_id`,
+  `feature_name`), so a `probe_id` repeated in difexp no longer hands a
+  row another feature’s symbol. Without `feature_name` it joins on
+  `probe_id` only when that is unique.
+
+- Query names are always unique (`"X | Up"`, `"X | Up (2)"`).
+
+- The kstest ranked list keeps the positive score when a gene’s scores
+  tie on `|score|` with opposite signs, so it no longer depends on
+  difexp row order.
+
+- `runHypeR()` errors on an invalid `background` (e.g. `"Difexp"`); both
+  functions error on a `split` that is not `TRUE`/`FALSE` and on
+  `omic_signature` supplied together with
+  `signature_id`/`signature_name`.
+
+- kstest drops, with a warning, genesets hypeR cannot score: those whose
+  hits all have score 0 (`power != 0`) and those containing every query
+  gene (any power). hypeR would otherwise error or put scores on the
+  wrong genesets. Dropped genesets are also left out of the FDR
+  adjustment, and are listed in each `hyp$info`.
+
+- With `plotting = FALSE`, the empty placeholder plots hypeR stores for
+  every geneset are removed. They were most of the object’s size (about
+  46 MB for a Hallmark `hyp`).
+
+- A signature’s gene symbols are resolved once per call, so a kstest
+  with `background = "difexp"` no longer looks up the reference table
+  twice.
+
+- With `background = "difexp"`, a hypergeometric query is reduced to the
+  genes its difexp measured, with a warning; hypeR reduces only the
+  genesets.
+
+- A query left with no genesets or no genes is skipped with a warning
+  instead of aborting the whole run.
+
+## Process
+
+- R CMD check and the validation workflow run on `dev` and on pull
+  requests into it, not only on `master`, so a change is checked before
+  it reaches the staging instance (#235).
+- CONTRIBUTING describes the dev model: `dev` is what gets worked on and
+  what staging runs, `master` is what sigrepo.org runs and gains commits
+  only through a release pull request, and a hotfix on `master` is
+  merged back into `dev` the same day. It also says that `Closes #NNN`
+  on a pull request into `dev` fires only when the release pull request
+  carries the change into `master` (#237, \#239).
+- The `connect-sigrepo-mcp` skill no longer lists the withdrawn
+  `run_enrichment` MCP tool and now names `rummagene_enrich`, so its
+  count of nine tools is right (#251).
+
 # SigRepo 1.0.0
 
 - Documentation: <https://montilab.github.io/SigRepo/>
@@ -9,6 +315,20 @@
   returning a signature id for an empty signature. Needs OmicSignature
   &gt;= 1.4.1, which keeps NA-score rows (#258,
   montilab/SigRepo\_Server#89).
+- `searchSignature()` searches instead of matching exactly: a term
+  matches a field exactly when an exact match exists anywhere in that
+  column, otherwise as a substring, so `signature_name = "M005"` finds
+  every name containing it while `sample_type = "liver"` still returns
+  only liver. Numbers match exactly, blank terms are ignored, and terms
+  are literal (no regular expressions; LIKE wildcards are escaped).
+  `type`, `assay_type`, `keywords`, `PMID`, `year`, `has_difexp`,
+  `description` and `covariates` are new filters, and `type` and
+  `assay_type` are validated against their declared members (#233,
+  \#230, \#231).
+- `R/hypeR_examples.R`, a Shiny UI module left over from prototyping the
+  server’s Annotate tab, is removed from the package source along with
+  its `.Rbuildignore` line. It was never built, exported or referenced
+  (#248).
 - `addUser()` and `updateUser()` now grant privileges on the database
   the connection is on instead of a hard-coded `sigrepo` schema, and
   `checkDBTable()` reads `SHOW TABLES` by position, so seeding and
diff --git a/R/externalCommon.R b/R/externalCommon.R
new file mode 100644
index 00000000..f9ae6ab5
--- /dev/null
+++ b/R/externalCommon.R
@@ -0,0 +1,137 @@
+############################################################
+# Shared plumbing for the public signature search engines
+# behind searchExternal(): Rummagene, RummaGEO and CORESH.
+# Every network call goes through externalPostJson() /
+# externalGetJson() so adapters can be tested offline by
+# mocking those two functions.
+############################################################
+
+EXTERNAL_SOURCES <- c("rummagene", "rummageo", "coresh")
+
+EXTERNAL_COLUMNS <- c(
+  "source", "direction", "rank", "id", "title", "url",
+  "score", "score_label", "pvalue", "adj_pvalue", "n_overlap", "n_set"
+)
+
+`%||%` <- function(a, b) if (base::is.null(a)) b else a
+
+#' @title externalUrl
+#' @description Base URL of an external search engine, overridable through
+#' options so tests and a future dev instance can redirect it.
+#' @param source One of "rummagene", "rummageo", "coresh".
+#' @return A single URL string.
+#' @keywords internal
+#' @noRd
+externalUrl <- function(source) {
+  base::switch(
+    source,
+    rummagene = base::getOption("sigrepo.rummagene_url", "https://rummagene.com/graphql"),
+    rummageo  = base::getOption("sigrepo.rummageo_url",  "https://rummageo.com/graphql"),
+    coresh    = base::getOption("sigrepo.coresh_url",    "https://alserglab.wustl.edu/coresh-back"),
+    base::stop(base::sprintf("Unknown external source '%s'.", source))
+  )
+}
+
+#' @title externalPostJson
+#' @description POST a JSON body and parse the JSON reply into nested lists.
+#' @keywords internal
+#' @noRd
+externalPostJson <- function(url, body, timeout = 60) {
+  res <- httr::POST(
+    url, body = body, encode = "json",
+    httr::content_type_json(), httr::timeout(timeout)
+  )
+  if (httr::status_code(res) >= 300) {
+    base::stop(base::sprintf("Request to %s failed (HTTP %s).", url, httr::status_code(res)))
+  }
+  jsonlite::fromJSON(httr::content(res, as = "text", encoding = "UTF-8"), simplifyVector = FALSE)
+}
+
+#' @title externalGetJson
+#' @description GET with query parameters and parse the JSON reply.
+#' @keywords internal
+#' @noRd
+externalGetJson <- function(url, query = base::list(), timeout = 60) {
+  res <- httr::GET(url, query = query, httr::timeout(timeout))
+  if (httr::status_code(res) >= 300) {
+    base::stop(base::sprintf("Request to %s failed (HTTP %s).", url, httr::status_code(res)))
+  }
+  jsonlite::fromJSON(httr::content(res, as = "text", encoding = "UTF-8"), simplifyVector = FALSE)
+}
+
+#' @title externalGraphql
+#' @description Run one GraphQL document; a payload carrying `errors` is an R error.
+#' @keywords internal
+#' @noRd
+externalGraphql <- function(url, query, variables = base::list(), timeout = 60) {
+  payload <- externalPostJson(url, base::list(query = query, variables = variables), timeout = timeout)
+  if (!base::is.null(payload$errors)) {
+    msg <- base::tryCatch(payload$errors[[1]]$message, error = function(e) NULL) %||% "unknown error"
+    base::stop(base::sprintf("GraphQL error from %s: %s", url, msg))
+  }
+  payload
+}
+
+#' @title emptyExternalFrame
+#' @description A zero-row data frame with the common external columns.
+#' @keywords internal
+#' @noRd
+emptyExternalFrame <- function(source, direction = "combined") {
+  base::data.frame(
+    source = base::character(), direction = base::character(), rank = base::integer(),
+    id = base::character(), title = base::character(), url = base::character(),
+    score = base::numeric(), score_label = base::character(),
+    pvalue = base::numeric(), adj_pvalue = base::numeric(),
+    n_overlap = base::integer(), n_set = base::integer(),
+    stringsAsFactors = FALSE
+  )
+}
+
+#' @title bindExternalHits
+#' @description Turn a list of per-hit named lists into the common data frame:
+#' common columns first (NA where a service has no value), service-specific
+#' extras after, `rank` by position.
+#' @keywords internal
+#' @noRd
+bindExternalHits <- function(source, direction, rows) {
+  if (base::length(rows) == 0) {
+    return(emptyExternalFrame(source, direction))
+  }
+  na_if_null <- function(x) if (base::is.null(x) || base::length(x) == 0) NA else x[[1]]
+  all_cols <- base::unique(base::unlist(base::lapply(rows, base::names)))
+  values <- base::lapply(all_cols, function(col) {
+    base::unlist(base::lapply(rows, function(r) na_if_null(r[[col]])))
+  })
+  base::names(values) <- all_cols
+  tbl <- base::as.data.frame(values, stringsAsFactors = FALSE, optional = TRUE)
+  for (col in base::setdiff(EXTERNAL_COLUMNS, c("source", "direction", "rank", base::colnames(tbl)))) {
+    tbl[[col]] <- NA
+  }
+  tbl$source <- source
+  tbl$direction <- direction
+  tbl$rank <- base::seq_len(base::nrow(tbl))
+  extras <- base::setdiff(base::colnames(tbl), EXTERNAL_COLUMNS)
+  tbl <- tbl[, c(EXTERNAL_COLUMNS, extras), drop = FALSE]
+  base::rownames(tbl) <- NULL
+  tbl
+}
+
+#' @title rbindExternalFrames
+#' @description rbind external frames whose extra columns may differ, filling
+#' the gaps with NA.
+#' @keywords internal
+#' @noRd
+rbindExternalFrames <- function(frames) {
+  frames <- base::Filter(Negate(base::is.null), frames)
+  if (base::length(frames) == 0) {
+    return(emptyExternalFrame("external"))
+  }
+  all_cols <- base::unique(base::unlist(base::lapply(frames, base::colnames)))
+  frames <- base::lapply(frames, function(f) {
+    for (col in base::setdiff(all_cols, base::colnames(f))) f[[col]] <- base::rep(NA, base::nrow(f))
+    f[, all_cols, drop = FALSE]
+  })
+  out <- base::do.call(base::rbind, frames)
+  base::rownames(out) <- NULL
+  out
+}
diff --git a/R/externalCoresh.R b/R/externalCoresh.R
new file mode 100644
index 00000000..3e88ed47
--- /dev/null
+++ b/R/externalCoresh.R
@@ -0,0 +1,117 @@
+############################################################
+# CORESH: ranks ~40k human and ~40k mouse GEO expression
+# datasets by how much variance a query gene set explains as
+# a coregulated block (Sukhov et al., NAR 2025,
+# doi 10.1093/nar/gkaf372). The web app's JSON backend has
+# no auth: submit a job, poll it, fetch the ranking.
+# Endpoints verified against the live service on 2026-10-07.
+############################################################
+
+#' @title coreshJobUrl
+#' @description Shareable results page for a CORESH job id.
+#' @keywords internal
+#' @noRd
+coreshJobUrl <- function(job_id) {
+  base::sprintf("https://alserglab.wustl.edu/coresh/load/%s", job_id)
+}
+
+#' @title externalCoresh
+#' @description Submit a translated query to CORESH, poll until the ranking is
+#' ready, and return the top `limit` datasets. Attributes `job_id` and
+#' `job_url` point at the shareable results page.
+#' @keywords internal
+#' @noRd
+externalCoresh <- function(query, limit = 25, calculate_pvalues = FALSE, timeout = 120) {
+  if (base::is.na(query$organism_code)) {
+    base::stop(base::sprintf(
+      "CORESH only supports Homo sapiens and Mus musculus; '%s' is '%s'.",
+      query$signature_name, query$organism
+    ))
+  }
+  base_url <- externalUrl("coresh")
+  pv_flag <- if (base::isTRUE(calculate_pvalues)) "true" else "false"
+  poll <- base::getOption("sigrepo.coresh_poll_seconds", 2)
+
+  submitted <- externalPostJson(
+    base::paste0(base_url, "/submit-genes"),
+    base::list(
+      organism = query$organism_code,
+      dbType = query$organism_code,
+      genes = base::as.list(query$genes),
+      calculatePvalues = base::isTRUE(calculate_pvalues)
+    ),
+    timeout = 60
+  )
+  job_id <- submitted$ID
+  if (base::is.null(job_id) || !base::nzchar(job_id)) {
+    base::stop("CORESH did not return a job id.")
+  }
+  deadline <- base::Sys.time() + timeout
+  timeout_msg <- base::sprintf(
+    "CORESH job %s did not finish within %s s. Results will appear at %s when done.",
+    job_id, timeout, coreshJobUrl(job_id)
+  )
+
+  repeat {
+    status <- externalGetJson(
+      base::paste0(base_url, "/check-job"),
+      base::list(jobid = job_id, organism = query$organism_code, calculatePvalues = pv_flag)
+    )
+    if (base::identical(status$failed, "True") || base::isTRUE(status$failed)) {
+      base::stop(base::sprintf("CORESH job %s failed.", job_id))
+    }
+    progress <- base::suppressWarnings(base::as.numeric(status$progress %||% 0))
+    if (base::isTRUE(progress >= 100)) break
+    if (base::Sys.time() > deadline) base::stop(timeout_msg)
+    base::Sys.sleep(poll)
+  }
+  repeat {
+    files <- externalGetJson(
+      base::paste0(base_url, "/check-result-files"),
+      base::list(jobid = job_id, calculatePvalues = pv_flag)
+    )
+    if (base::isTRUE(files$files_ready)) break
+    if (base::Sys.time() > deadline) base::stop(timeout_msg)
+    base::Sys.sleep(poll)
+  }
+
+  ranking <- externalGetJson(base::paste0(base_url, "/get-ranking-result"), base::list(jobid = job_id))
+  out <- parseCoreshRanking(ranking, query, limit = limit)
+  base::attr(out, "job_id") <- job_id
+  base::attr(out, "job_url") <- coreshJobUrl(job_id)
+  out
+}
+
+#' @title parseCoreshRanking
+#' @description Head of a get-ranking-result reply -> the common frame.
+#' `log10Padj` arrives as the string "NA" when p-values were not requested.
+#' @keywords internal
+#' @noRd
+parseCoreshRanking <- function(rows, query, limit = 25) {
+  rows <- rows %||% base::list()
+  total <- base::length(rows)
+  rows <- utils::head(rows, base::as.integer(limit))
+  hits <- base::lapply(rows, function(r) {
+    log10_padj <- base::suppressWarnings(base::as.numeric(r$log10Padj %||% NA))
+    base::list(
+      id = r$gseId,
+      title = r$gseTitle,
+      url = base::sprintf("https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=%s", r$gseId),
+      score = r$pctVar,
+      score_label = "% variance",
+      pvalue = NA_real_,
+      adj_pvalue = if (base::is.na(log10_padj)) NA_real_ else 10^log10_padj,
+      n_overlap = NA_integer_,
+      n_set = r$size,
+      gpl = r$gplId,
+      summary = r$gseSummary,
+      positive_words = r$positiveWords,
+      negative_words = r$negativeWords,
+      log10_padj = log10_padj
+    )
+  })
+  out <- bindExternalHits("coresh", query$direction, hits)
+  base::attr(out, "total_count") <- total
+  base::attr(out, "query") <- query
+  out
+}
diff --git a/R/externalQuery.R b/R/externalQuery.R
new file mode 100644
index 00000000..16517e69
--- /dev/null
+++ b/R/externalQuery.R
@@ -0,0 +1,246 @@
+############################################################
+# Translate a SigRepo signature into the one query shape the
+# external engines share: gene symbols + an organism code.
+############################################################
+
+#' @title organismCode
+#' @description "hsa" for Homo sapiens, "mmu" for Mus musculus, NA otherwise.
+#' @keywords internal
+#' @noRd
+organismCode <- function(organism) {
+  key <- base::tolower(base::trimws(base::as.character(organism %||% "")))
+  if (base::length(key) == 0 || base::is.na(key[1])) {
+    return(NA_character_)
+  }
+  if (key[1] %in% c("homo sapiens", "human", "hsa")) return("hsa")
+  if (key[1] %in% c("mus musculus", "mouse", "mmu")) return("mmu")
+  NA_character_
+}
+
+#' @title looksLikeGeneSymbol
+#' @description TRUE for names that are not Ensembl, Entrez or RefSeq ids.
+#' @keywords internal
+#' @noRd
+looksLikeGeneSymbol <- function(x) {
+  x <- base::as.character(x)
+  is_ensembl <- base::grepl("^ENS[A-Z]*[GTP][0-9]{6,}(\\.[0-9]+)?$", x)
+  is_entrez  <- base::grepl("^[0-9]+$", x)
+  is_refseq  <- base::grepl("^(NM|NR|XM|XR|NP|XP)_[0-9]+", x)
+  !(is_ensembl | is_entrez | is_refseq)
+}
+
+#' @title failedLookup
+#' @description An empty mapping that remembers why the lookup produced
+#' nothing, so the caller can tell the user instead of blaming the signature.
+#' @keywords internal
+#' @noRd
+failedLookup <- function(message) {
+  base::structure(base::character(), error = message)
+}
+
+#' @title lookupSymbolsInSigRepo
+#' @description feature_name -> gene_symbol from the transcriptomics
+#' reference table. Any failure (no connection, viewer without access,
+#' missing table) yields an empty mapping so the caller can fall back.
+#' @keywords internal
+#' @noRd
+lookupSymbolsInSigRepo <- function(conn_handler, feature_names, organism) {
+  if (base::is.null(conn_handler) || base::length(feature_names) == 0) {
+    return(base::character())
+  }
+  tbl <- base::tryCatch(
+    searchTranscriptomicsFeatureSet(
+      conn_handler = conn_handler, feature_name = feature_names, organism = NULL, verbose = FALSE
+    ),
+    error = function(e) e
+  )
+  if (base::inherits(tbl, "error")) {
+    return(failedLookup(base::sprintf("SigRepo reference-table lookup failed: %s", base::conditionMessage(tbl))))
+  }
+  if (base::is.null(tbl) || !base::all(c("feature_name", "gene_symbol") %in% base::colnames(tbl))) {
+    return(base::character())
+  }
+  sym <- base::trimws(base::as.character(tbl$gene_symbol))
+  keep <- !base::is.na(sym) & base::nzchar(sym)
+  tbl <- tbl[keep, , drop = FALSE]
+  tbl <- tbl[!base::duplicated(tbl$feature_name), , drop = FALSE]
+  stats::setNames(base::trimws(base::as.character(tbl$gene_symbol)), base::as.character(tbl$feature_name))
+}
+
+#' @title biomartSymbolTable
+#' @description The raw biomaRt call, isolated so tests can mock it.
+#' @keywords internal
+#' @noRd
+biomartSymbolTable <- function(ensembl_ids, organism) {
+  dataset <- base::switch(
+    organismCode(organism),
+    hsa = "hsapiens_gene_ensembl",
+    mmu = "mmusculus_gene_ensembl",
+    NA_character_
+  )
+  if (base::is.na(dataset)) {
+    return(NULL)
+  }
+  attribute <- symbolAttributeForOrganism(organism)
+  mart <- biomaRt::useEnsembl(biomart = "genes", dataset = dataset)
+  biomaRt::getBM(
+    attributes = c("ensembl_gene_id", attribute),
+    filters = "ensembl_gene_id",
+    values = base::unique(ensembl_ids),
+    mart = mart
+  )
+}
+
+#' @title lookupSymbolsInBiomart
+#' @description Ensembl gene ids (versioned or not) -> symbols via biomaRt.
+#' @keywords internal
+#' @noRd
+lookupSymbolsInBiomart <- function(feature_names, organism) {
+  ensembl_names <- feature_names[base::grepl("^ENS[A-Z]*G[0-9]+", feature_names)]
+  if (base::length(ensembl_names) == 0) {
+    return(base::character())
+  }
+  ids <- base::sub("\\.[0-9]+$", "", ensembl_names)
+  bm <- base::tryCatch(biomartSymbolTable(ids, organism), error = function(e) e)
+  if (base::inherits(bm, "error")) {
+    return(failedLookup(base::sprintf("biomaRt lookup failed: %s", base::conditionMessage(bm))))
+  }
+  if (base::is.null(bm) || base::nrow(bm) == 0) {
+    return(base::character())
+  }
+  attribute <- symbolAttributeForOrganism(organism)
+  sym <- base::trimws(base::as.character(bm[[attribute]]))
+  bm <- bm[!base::is.na(sym) & base::nzchar(sym), , drop = FALSE]
+  bm <- bm[!base::duplicated(bm$ensembl_gene_id), , drop = FALSE]
+  by_id <- stats::setNames(base::trimws(base::as.character(bm[[attribute]])), bm$ensembl_gene_id)
+  out <- by_id[ids]
+  base::names(out) <- ensembl_names
+  out[!base::is.na(out)]
+}
+
+#' @title mapFeaturesToSymbols
+#' @description Named character vector feature_name -> symbol; NA where no
+#' source could map the name. Symbols pass through untouched.
+#' @keywords internal
+#' @noRd
+mapFeaturesToSymbols <- function(feature_names, organism, conn_handler = NULL) {
+  feature_names <- base::unique(base::trimws(base::as.character(feature_names)))
+  feature_names <- feature_names[!base::is.na(feature_names) & base::nzchar(feature_names)]
+  symbol <- stats::setNames(base::rep(NA_character_, base::length(feature_names)), feature_names)
+  is_symbol <- looksLikeGeneSymbol(feature_names)
+  symbol[is_symbol] <- feature_names[is_symbol]
+
+  errors <- base::character()
+  pending <- base::names(symbol)[base::is.na(symbol)]
+  if (base::length(pending) > 0) {
+    hits <- lookupSymbolsInSigRepo(conn_handler, pending, organism)
+    errors <- c(errors, base::attr(hits, "error"))
+    hits <- hits[base::names(hits) %in% pending]
+    if (base::length(hits) > 0) symbol[base::names(hits)] <- base::unname(hits)
+  }
+  pending <- base::names(symbol)[base::is.na(symbol)]
+  if (base::length(pending) > 0) {
+    hits <- lookupSymbolsInBiomart(pending, organism)
+    errors <- c(errors, base::attr(hits, "error"))
+    hits <- hits[base::names(hits) %in% pending]
+    if (base::length(hits) > 0) symbol[base::names(hits)] <- base::unname(hits)
+  }
+  if (base::length(errors) > 0) base::attr(symbol, "lookup_errors") <- errors
+  symbol
+}
+
+#' @title buildExternalQuery
+#' @description Turn an OmicSignature into the query all three engines accept.
+#' @param omic_signature An OmicSignature (or anything with `$signature` and `$metadata`).
+#' @param direction "combined", "up" or "down". Up/down use the sign of `score`.
+#' @param conn_handler Optional; enables the reference-table symbol lookup.
+#' @param max_genes Cap on genes sent (CORESH refuses more than 500).
+#' @param verbose Print a one-line mapping summary.
+#' @return list(signature_name, organism, organism_code, direction, genes,
+#'   n_input, n_mapped, n_unmapped, truncated, unmapped)
+#' @keywords internal
+#' @noRd
+buildExternalQuery <- function(omic_signature, direction = "combined", conn_handler = NULL,
+                               max_genes = 500, verbose = TRUE) {
+  sig <- omic_signature$signature
+  meta <- omic_signature$metadata
+  name <- base::as.character(meta$signature_name %||% "signature")[1]
+  organism <- base::as.character(meta$organism %||% NA_character_)[1]
+  assay <- base::tolower(base::as.character(meta$assay_type %||% "transcriptomics")[1])
+
+  if (!base::identical(assay, "transcriptomics")) {
+    base::stop(base::sprintf(
+      "searchExternal() supports transcriptomics signatures only; '%s' has assay_type '%s'.", name, assay
+    ))
+  }
+  if (base::is.null(sig) || base::nrow(sig) == 0 || !"feature_name" %in% base::colnames(sig)) {
+    base::stop(base::sprintf("Signature '%s' has no features to search with.", name))
+  }
+
+  has_score <- "score" %in% base::colnames(sig) && base::any(!base::is.na(sig$score))
+  if (!base::identical(direction, "combined")) {
+    if (!has_score) {
+      base::stop(base::sprintf("Direction splitting needs a 'score' column; '%s' has none.", name))
+    }
+    keep <- if (base::identical(direction, "up")) sig$score > 0 else sig$score < 0
+    sig <- sig[keep %in% TRUE, , drop = FALSE]
+    if (base::nrow(sig) == 0) {
+      sign_word <- if (base::identical(direction, "up")) "positive" else "negative"
+      other <- if (base::identical(direction, "up")) "down" else "up"
+      base::stop(base::sprintf(
+        "'%s' has no features with a %s score; use direction = 'combined' or '%s'.", name, sign_word, other
+      ))
+    }
+  }
+  if (has_score) {
+    sig <- sig[base::order(-base::abs(sig$score), na.last = TRUE), , drop = FALSE]
+  }
+
+  feature_names <- base::as.character(sig$feature_name)
+  mapping <- mapFeaturesToSymbols(feature_names, organism, conn_handler)
+  symbols <- base::unname(mapping[base::trimws(feature_names)])
+  genes <- base::unique(symbols[!base::is.na(symbols) & base::nzchar(symbols)])
+
+  n_input <- base::length(base::unique(feature_names))
+  n_mapped <- base::length(genes)
+  unmapped <- base::names(mapping)[base::is.na(mapping)]
+  truncated <- n_mapped > max_genes
+  if (truncated) {
+    genes <- genes[base::seq_len(max_genes)]
+  }
+  lookup_errors <- base::attr(mapping, "lookup_errors") %||% base::character()
+  if (base::length(genes) < 2) {
+    base::stop(base::sprintf(
+      "Could not map enough of the %d features of '%s' to gene symbols (organism '%s'): %d mapped, need at least 2.%s",
+      n_input, name, organism, n_mapped,
+      if (base::length(lookup_errors) > 0) base::paste0(" ", base::paste(lookup_errors, collapse = " ")) else ""
+    ))
+  }
+  if (base::isTRUE(verbose)) {
+    for (err in lookup_errors) base::message(base::sprintf("[%s] %s: %s", direction, name, err))
+    base::message(base::sprintf(
+      "[%s] %s: %d of %d features mapped to gene symbols%s; the query is %s.",
+      direction, name, n_mapped, n_input,
+      if (base::length(unmapped) > 0) base::sprintf(" (%d unmapped)", base::length(unmapped)) else "",
+      if (truncated) {
+        base::sprintf("the %d strongest of the %d mapped genes by |score| (the engines accept at most %d)", max_genes, n_mapped, max_genes)
+      } else {
+        base::sprintf("all %d genes", n_mapped)
+      }
+    ))
+  }
+
+  base::list(
+    signature_name = name,
+    organism = organism,
+    organism_code = organismCode(organism),
+    direction = direction,
+    genes = genes,
+    n_input = n_input,
+    n_mapped = n_mapped,
+    n_unmapped = base::length(unmapped),
+    truncated = truncated,
+    unmapped = unmapped,
+    lookup_errors = lookup_errors
+  )
+}
diff --git a/R/externalRummagene.R b/R/externalRummagene.R
new file mode 100644
index 00000000..394b36b8
--- /dev/null
+++ b/R/externalRummagene.R
@@ -0,0 +1,83 @@
+############################################################
+# Rummagene: ~1M gene sets mined from PMC supplementary
+# tables (Communications Biology 2024, PMID 38643247).
+# Public GraphQL endpoint, no auth. Same document the SigRepo
+# server's Annotate tab uses.
+############################################################
+
+RUMMAGENE_ENRICH_QUERY <- "query enrich($genes:[String]!, $first:Int, $overlapGe:Int, $pvalueLe:Float){
+  currentBackground {
+    enrich(genes:$genes, first:$first, overlapGe:$overlapGe, pvalueLe:$pvalueLe){
+      totalCount
+      nodes {
+        pvalue adjPvalue oddsRatio nOverlap
+        geneSets { nodes { term description nGeneIds
+          geneSetPmcsById { nodes { pmcInfoByPmcid { pmcid title yr doi } } } } }
+      }
+    }
+  }
+}"
+
+#' @title externalRummagene
+#' @description Enrich a translated query against Rummagene. Symbols are sent
+#' upper-cased because Rummagene is keyed on human-style symbols.
+#' @keywords internal
+#' @noRd
+externalRummagene <- function(query, limit = 25, timeout = 60) {
+  variables <- base::list(
+    genes = base::as.list(base::toupper(query$genes)),
+    first = base::as.integer(limit),
+    overlapGe = 2L,
+    pvalueLe = 0.05
+  )
+  payload <- externalGraphql(externalUrl("rummagene"), RUMMAGENE_ENRICH_QUERY, variables, timeout = timeout)
+  parseRummagene(payload, query)
+}
+
+#' @title parseRummagene
+#' @description Flatten a Rummagene enrich payload into the common frame. A
+#' gene-set hash can be shared by several papers; the first is representative
+#' and `n_papers` says how many share it.
+#' @keywords internal
+#' @noRd
+parseRummagene <- function(payload, query) {
+  enrich <- base::tryCatch(payload$data$currentBackground$enrich, error = function(e) NULL)
+  rows <- base::lapply(enrich$nodes %||% base::list(), function(node) {
+    gs_nodes <- base::tryCatch(node$geneSets$nodes, error = function(e) NULL) %||% base::list()
+    if (base::length(gs_nodes) == 0) {
+      return(NULL)
+    }
+    gs <- gs_nodes[[1]]
+    pmc <- NULL
+    for (n in gs$geneSetPmcsById$nodes %||% base::list()) {
+      if (!base::is.null(n$pmcInfoByPmcid)) { pmc <- n$pmcInfoByPmcid; break }
+    }
+    term <- gs$term %||% NA_character_
+    pmcid <- pmc$pmcid
+    if (base::is.null(pmcid) && !base::is.na(term) && base::grepl("^PMC[0-9]+", term)) {
+      pmcid <- base::regmatches(term, base::regexpr("^PMC[0-9]+", term))
+    }
+    pmcid <- pmcid %||% NA_character_
+    base::list(
+      id = term,
+      title = pmc$title %||% term,
+      url = if (base::is.na(pmcid)) NA_character_ else base::sprintf("https://www.ncbi.nlm.nih.gov/pmc/articles/%s/", pmcid),
+      score = node$oddsRatio,
+      score_label = "odds ratio",
+      pvalue = node$pvalue,
+      adj_pvalue = node$adjPvalue,
+      n_overlap = node$nOverlap,
+      n_set = gs$nGeneIds,
+      pmcid = pmcid,
+      year = pmc$yr,
+      doi = pmc$doi,
+      description = gs$description,
+      n_papers = base::length(gs_nodes)
+    )
+  })
+  rows <- base::Filter(Negate(base::is.null), rows)
+  out <- bindExternalHits("rummagene", query$direction, rows)
+  base::attr(out, "total_count") <- enrich$totalCount %||% base::nrow(out)
+  base::attr(out, "query") <- query
+  out
+}
diff --git a/R/externalRummageo.R b/R/externalRummageo.R
new file mode 100644
index 00000000..f30c866d
--- /dev/null
+++ b/R/externalRummageo.R
@@ -0,0 +1,104 @@
+############################################################
+# RummaGEO: up/down gene sets auto-computed from GEO RNA-seq
+# (ARCHS4). Human and mouse live in separate "backgrounds";
+# we look the right one up by species, then enrich against it.
+############################################################
+
+RUMMAGEO_BACKGROUNDS_QUERY <- "{ backgrounds { nodes { id species } } }"
+
+RUMMAGEO_ENRICH_QUERY <- "query enrich($id:UUID!, $genes:[String]!, $first:Int, $overlapGe:Int){
+  background(id:$id) {
+    species
+    enrich(genes:$genes, first:$first, overlapGe:$overlapGe){
+      totalCount
+      nodes {
+        pvalue adjPvalue oddsRatio nOverlap
+        geneSet { term species nGeneIds geneSetGsesById { nodes { gse } } }
+      }
+    }
+  }
+}"
+
+#' @title rummageoBackgroundId
+#' @description UUID of the RummaGEO background for "hsa" (human) or "mmu" (mouse).
+#' @keywords internal
+#' @noRd
+rummageoBackgroundId <- function(organism_code, timeout = 60) {
+  species <- base::switch(organism_code, hsa = "human", mmu = "mouse",
+                          base::stop("RummaGEO only supports Homo sapiens and Mus musculus."))
+  payload <- externalGraphql(externalUrl("rummageo"), RUMMAGEO_BACKGROUNDS_QUERY, base::list(), timeout = timeout)
+  for (n in payload$data$backgrounds$nodes %||% base::list()) {
+    if (base::identical(n$species, species)) {
+      return(n$id)
+    }
+  }
+  base::stop(base::sprintf("RummaGEO has no %s background.", species))
+}
+
+#' @title externalRummageo
+#' @description Enrich a translated query against the RummaGEO background that
+#' matches its organism. Symbols are sent as-is (mouse symbols are mixed case).
+#' @keywords internal
+#' @noRd
+externalRummageo <- function(query, limit = 25, timeout = 60) {
+  if (base::is.na(query$organism_code)) {
+    base::stop(base::sprintf(
+      "RummaGEO only supports Homo sapiens and Mus musculus; '%s' is '%s'.",
+      query$signature_name, query$organism
+    ))
+  }
+  background_id <- rummageoBackgroundId(query$organism_code, timeout = timeout)
+  variables <- base::list(
+    id = background_id,
+    genes = base::as.list(query$genes),
+    first = base::as.integer(limit),
+    overlapGe = 2L
+  )
+  payload <- externalGraphql(externalUrl("rummageo"), RUMMAGEO_ENRICH_QUERY, variables, timeout = timeout)
+  parseRummageo(payload, query)
+}
+
+#' @title parseRummageo
+#' @description Flatten a RummaGEO enrich payload into the common frame. Terms
+#' look like "GSE123,GSE124-0-vs-1-human up" or "GSE1-0-vs-6-mouse.tsv up".
+#' @keywords internal
+#' @noRd
+parseRummageo <- function(payload, query) {
+  bg <- base::tryCatch(payload$data$background, error = function(e) NULL) %||%
+    base::tryCatch(payload$data$currentBackground, error = function(e) NULL)
+  enrich <- bg$enrich
+  rows <- base::lapply(enrich$nodes %||% base::list(), function(node) {
+    gs <- node$geneSet
+    if (base::is.null(gs)) {
+      return(NULL)
+    }
+    term <- gs$term %||% NA_character_
+    gses <- base::vapply(gs$geneSetGsesById$nodes %||% base::list(),
+                         function(n) base::as.character(n$gse %||% NA_character_), character(1))
+    gse <- if (base::length(gses) > 0 && !base::is.na(gses[1])) gses[1] else base::sub("-.*$", "", term)
+    first_gse <- base::strsplit(gse, ",", fixed = TRUE)[[1]][1]
+    rest <- base::sub("^[^-]*-", "", term)
+    regulation <- if (base::grepl(" up$", rest)) "up" else if (base::grepl(" (dn|down)$", rest)) "down" else NA_character_
+    contrast <- base::sub("-(human|mouse)(\\.tsv)? (up|dn|down)$", "", rest)
+    base::list(
+      id = term,
+      title = term,
+      url = base::sprintf("https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=%s", first_gse),
+      score = node$oddsRatio,
+      score_label = "odds ratio",
+      pvalue = node$pvalue,
+      adj_pvalue = node$adjPvalue,
+      n_overlap = node$nOverlap,
+      n_set = gs$nGeneIds,
+      gse = gse,
+      species = gs$species,
+      contrast = contrast,
+      regulation = regulation
+    )
+  })
+  rows <- base::Filter(Negate(base::is.null), rows)
+  out <- bindExternalHits("rummageo", query$direction, rows)
+  base::attr(out, "total_count") <- enrich$totalCount %||% base::nrow(out)
+  base::attr(out, "query") <- query
+  out
+}
diff --git a/R/hypeRClient.R b/R/hypeRClient.R
index dde937ab..a2e71235 100644
--- a/R/hypeRClient.R
+++ b/R/hypeRClient.R
@@ -148,7 +148,7 @@ resolveHypeRSignatures <- function(
 
   if (base::is.null(conn_handler)) {
     base::stop(
-      "\nProvide 'conn_handler' together with 'signature_id' or 'signature_name', or pass 'omic_signature'.\n"
+      "\nProvide the signatures to test: 'conn_handler' together with 'signature_id' or 'signature_name', 'omic_signature', or 'signature' (gene symbols or a named score vector).\n"
     )
   }
 
@@ -213,425 +213,689 @@ resolveHypeRSignatureLabels <- function(omic_signatures) {
   base::make.unique(labels)
 }
 
-resolveHypeRGenesets <- function(
-    genesets = NULL,
-    msigdb_species = NULL,
-    msigdb_collection = NULL,
-    msigdb_subcollection = NULL,
-    msigdb_clean = FALSE
-) {
-  msigdb_requested <- !base::is.null(msigdb_collection) &&
-    base::length(msigdb_collection) > 0 &&
-    !base::all(msigdb_collection %in% c("", NA))
-
-  if (!base::is.null(genesets) && msigdb_requested) {
-    base::stop(
-      "\nSupply either 'genesets' or 'msigdb_collection', but not both.\n"
-    )
-  }
 
-  if (msigdb_requested) {
-    if (!requireNamespace("hypeR", quietly = TRUE)) {
-      base::stop(
-        "\nPackage 'hypeR' is required to retrieve MSigDB genesets. Please install it first.\n"
-      )
-    }
+# A full transcriptomics difexp covers the measured transcriptome; on production
+# (2026-09) every transcriptomics difexp has either > 10,000 rows or <= 5,000.
+HYPER_MIN_TRANSCRIPTOME_DIFEXP_ROWS <- 10000L
 
-    msigdb_species <- if (
-      base::is.null(msigdb_species) ||
-      base::length(msigdb_species) == 0 ||
-      base::all(msigdb_species %in% c("", NA))
-    ) {
-      "Homo sapiens"
-    } else {
-      base::as.character(msigdb_species[[1]])
+#' Why a difexp looks filtered rather than a full list of measured genes, or NULL
+#'
+#' The default background uses a signature's difexp genes as the measured
+#' universe (BS831: "the number of annotated genes in the dataset"), which is
+#' only right when the difexp is complete. A truncated one shrinks the
+#' background and hides real enrichment.
+#' @noRd
+hypeRDifexpTruncation <- function(omic_signature) {
+  difexp <- omic_signature$difexp
+  n_difexp <- base::nrow(difexp)
+  n_signature <- if (methods::is(omic_signature$signature, "data.frame")) base::nrow(omic_signature$signature) else 0L
+  assay <- base::tolower(base::as.character(omic_signature$metadata$assay_type)[1])
+
+  if (base::identical(assay, "transcriptomics") && n_difexp < HYPER_MIN_TRANSCRIPTOME_DIFEXP_ROWS) {
+    return(base::sprintf("%d rows, fewer than a transcriptome's %d", n_difexp, HYPER_MIN_TRANSCRIPTOME_DIFEXP_ROWS))
+  }
+  if (n_signature > 0 && n_difexp <= 2L * n_signature) {
+    return(base::sprintf("%d rows for a %d-feature signature", n_difexp, n_signature))
+  }
+  for (col in base::intersect(c("p_value", "pvalue", "adj_p"), base::colnames(difexp))) {
+    p <- base::suppressWarnings(base::as.numeric(difexp[[col]]))
+    if (base::any(!base::is.na(p)) && base::max(p, na.rm = TRUE) <= 0.05) {
+      return(base::sprintf("every %s <= 0.05", col))
     }
+  }
+  NULL
+}
 
-    msigdb_collection <- base::as.character(msigdb_collection[[1]])
-    msigdb_subcollection <- if (
-      base::is.null(msigdb_subcollection) ||
-      base::length(msigdb_subcollection) == 0 ||
-      base::all(msigdb_subcollection %in% c("", NA))
-    ) {
-      NULL
-    } else {
-      base::as.character(msigdb_subcollection[[1]])
+#' Background for each query vector
+#'
+#' A number or gene vector is passed through for every query. "difexp" gives
+#' each query its own signature's measured genes; signatures without difexp
+#' symbols fall back to hypeR's default with one warning. A named list gives
+#' each signature its own background (any of those three forms), looked up by
+#' signature label, then by signature ID.
+#'
+#' @param inputs list(signatures, ids, labels) for every supplied signature,
+#'   including ones that built no query.
+#' NULL (the default) means "difexp" where a signature has a complete difexp
+#' with gene symbols and hypeR's 23467 otherwise: silently when there is no
+#' difexp, with a warning when the difexp looks filtered
+#' (hypeRDifexpTruncation()). An explicit "difexp" uses any difexp.
+#'
+#' @return list(values = unnamed list, one background per row of `info`;
+#'   sources = chr per row: "number", "genes", "difexp", "difexp-fallback" or
+#'   "difexp-truncated")
+#' @noRd
+resolveQueryBackgrounds <- function(background, info, inputs, resolve_symbols) {
+  if (base::is.list(background)) {
+    keys <- base::names(background)
+    unused <- keys[!keys %in% c(inputs$labels, inputs$ids[!base::is.na(inputs$ids)])]
+    if (base::length(unused) > 0) {
+      base::stop(base::sprintf(
+        "\nbackground names %s match no signature label or ID (labels: %s).\n",
+        base::paste(base::sprintf("'%s'", unused), collapse = ", "),
+        base::paste(base::sprintf("'%s'", inputs$labels), collapse = ", ")
+      ))
     }
-
-    return(
-      hypeR::msigdb_gsets(
-        species = msigdb_species,
-        collection = msigdb_collection,
-        subcollection = msigdb_subcollection,
-        clean = msigdb_clean
-      )
+    row_keys <- base::ifelse(
+      info$signature_name %in% keys, info$signature_name,
+      base::ifelse(!base::is.na(info$signature_id) & info$signature_id %in% keys, info$signature_id, NA_character_)
     )
+    if (base::anyNA(row_keys)) {
+      base::stop(base::sprintf(
+        "\nThe background list has no entry for %s; name each element by signature label or ID.\n",
+        base::paste(base::sprintf("'%s'", base::unique(info$signature_name[base::is.na(row_keys)])), collapse = ", ")
+      ))
+    }
+    specs <- base::unname(background[row_keys])
+  } else {
+    specs <- base::rep(base::list(background), base::nrow(info))
   }
 
-  if (base::is.null(genesets)) {
-    base::stop(
-      "\nProvide either 'genesets' or specify an MSigDB collection with 'msigdb_collection'.\n"
-    )
-  }
+  # NULL for hypeR-native input, which cannot use "difexp".
+  signatures_by_label <- if (base::is.null(inputs$signatures)) base::list() else stats::setNames(inputs$signatures, inputs$labels)
+  universes <- base::list()
+  fell_back <- base::character()
+  values <- base::vector("list", base::nrow(info))
+  sources <- base::character(base::nrow(info))
+
+  warn_fallback <- base::character()
+  truncated <- base::character()
+  truncation_notes <- base::character()
+  for (i in base::seq_len(base::nrow(info))) {
+    spec <- specs[[i]]
+    is_default <- base::is.null(spec)
+    if (is_default && base::is.null(inputs$signatures)) {
+      # hypeR-native input has no difexp to default to.
+      is_default <- FALSE
+      spec <- HYPER_DEFAULT_BACKGROUND
+    }
+    if (!is_default && !base::identical(spec, "difexp")) {
+      values[i] <- base::list(spec)
+      sources[i] <- if (base::is.character(spec)) "genes" else "number"
+      next
+    }
 
-  if (
-    methods::is(genesets, "gsets") ||
-    methods::is(genesets, "rgsets")
-  ) {
-    return(genesets)
+    label <- info$signature_name[i]
+    sig <- signatures_by_label[[label]]
+    has_difexp <- methods::is(sig$difexp, "data.frame") && base::nrow(sig$difexp) > 0
+    if (base::is.null(universes[[label]]) && is_default && has_difexp) {
+      note <- hypeRDifexpTruncation(sig)
+      if (!base::is.null(note)) {
+        truncated <- c(truncated, label)
+        truncation_notes <- c(truncation_notes, base::sprintf("'%s' (%s)", label, note))
+        universes[[label]] <- HYPER_DEFAULT_BACKGROUND
+      }
+    }
+    if (base::is.null(universes[[label]])) {
+      symbols <- if (has_difexp) {
+        resolve_symbols(sig, "difexp", label)$symbols
+      } else {
+        NA_character_
+      }
+      symbols <- base::unique(symbols[!base::is.na(symbols)])
+      if (base::length(symbols) == 0) {
+        fell_back <- c(fell_back, label)
+        if (!is_default) {
+          warn_fallback <- c(warn_fallback, label)
+        }
+        universes[[label]] <- HYPER_DEFAULT_BACKGROUND
+      } else {
+        universes[[label]] <- symbols
+      }
+    }
+    values[i] <- base::list(universes[[label]])
+    sources[i] <- if (label %in% truncated) "difexp-truncated" else if (label %in% fell_back) "difexp-fallback" else "difexp"
   }
 
-  if (!methods::is(genesets, "list") || base::length(genesets) == 0) {
-    base::stop(
-      "\n'genesets' must be a non-empty named list, a hypeR gsets object, or a hypeR rgsets object.\n"
+  if (base::length(truncation_notes) > 0) {
+    base::warning(
+      base::sprintf(
+        "Default background: the difexp looks filtered for %s, so it is not the measured gene universe; used background = %s instead. Pass background = \"difexp\" to use it anyway.",
+        base::paste(truncation_notes, collapse = ", "), HYPER_DEFAULT_BACKGROUND
+      ),
+      call. = FALSE
     )
   }
 
-  if (base::is.null(base::names(genesets)) || base::any(base::names(genesets) %in% c("", NA))) {
-    base::stop("\n'genesets' must be named.\n")
+  if (base::length(warn_fallback) > 0) {
+    base::warning(
+      base::sprintf(
+        "background = \"difexp\": no difexp gene symbols for %s; used background = %s instead.",
+        base::paste(base::sprintf("'%s'", base::unique(warn_fallback)), collapse = ", "),
+        HYPER_DEFAULT_BACKGROUND
+      ),
+      call. = FALSE
+    )
   }
 
-  genesets
+  base::list(values = values, sources = sources)
 }
 
-#' Build hypeR-ready signature vectors from SigRepo signatures
-#'
-#' @description Converts one or more SigRepo signatures into the query-vector
-#' format expected by \code{hypeR::hypeR()}. This helper can resolve signatures
-#' directly from the SigRepo database, so users do not need to call
-#' \code{getSignature()} manually first.
-#'
-#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
-#' Required unless \code{omic_signature} is supplied.
-#' @param signature_id One or more SigRepo signature IDs.
-#' @param signature_name One or more SigRepo signature names.
-#' @param omic_signature A single \code{OmicSignature} object or a list of
-#' \code{OmicSignature} objects.
-#' @param method One of \code{"hypergeo"}, \code{"kstest"}, or \code{"gsea"}.
-#' Hypergeometric enrichment uses the \code{signature} table. KS/GSEA-style
-#' enrichment use ranked scores from \code{difexp}.
-#' @param feature_col Column containing feature identifiers. Defaults to
-#' \code{"feature_name"}.
-#' @param score_col Column containing ranked scores for KS/GSEA-style enrichment.
-#' Defaults to \code{"score"}.
-#' @param split_by_group Logical; whether to create separate query vectors for
-#' each \code{group_label}. Defaults to \code{FALSE}.
-#' @param split_by_direction Logical; when \code{method = "hypergeo"}, whether
-#' to split each group into up- and down-direction feature sets using the sign
-#' of \code{score_col}. Defaults to \code{FALSE}.
-#' @param verbose Logical; whether or not to print diagnostic messages while
-#' retrieving signatures. Defaults to \code{TRUE}.
+# Excel caps a cell at 32767 characters; the dropped-geneset list goes into
+# hyp_to_excel()'s versioning sheet.
+HYPER_INFO_MAX_CHARS <- 32000L
+
+#' Append SigRepo provenance to a hyp object's info, in a fixed order
 #'
-#' @return A list with three elements:
-#' \describe{
-#'   \item{\code{signatures}}{A named list of query vectors for \code{hypeR}.}
-#'   \item{\code{metadata}}{A data frame describing each generated query vector.}
-#'   \item{\code{omic_signatures}}{The resolved \code{OmicSignature} objects.}
-#' }
+#' hypeR::hyp_to_excel() stacks info across a multihyp with mapply(), so every
+#' hyp must carry the same keys in the same order. Keys that do not apply are "".
 #'
-#' @export
-prepareHypeRSignatures <- function(
-    conn_handler = NULL,
-    signature_id = NULL,
-    signature_name = NULL,
-    omic_signature = NULL,
-    method = c("hypergeo", "kstest", "gsea"),
-    feature_col = "feature_name",
-    score_col = "score",
-    split_by_group = FALSE,
-    split_by_direction = FALSE,
-    verbose = TRUE
-){
+#' @param info_row One row of the prepared info data frame.
+#' @param run list(ranked_table, score_col, split (all chr, "" when not
+#'   applicable), background_source, query_genes_removed, genesets_dropped = chr,
+#'   fdr_scope).
+#' @noRd
+appendHypeRProvenance <- function(hyp_obj, info_row, run) {
+  blank_na <- function(x) if (base::is.na(x)) "" else base::as.character(x)
+  dropped_list <- base::paste(run$genesets_dropped, collapse = "; ")
+  if (base::nchar(dropped_list) > HYPER_INFO_MAX_CHARS) {
+    dropped_list <- base::paste0(base::substr(dropped_list, 1L, HYPER_INFO_MAX_CHARS), " ...")
+  }
 
-  method <- base::match.arg(method)
+  hyp_obj$info <- c(hyp_obj$info, base::list(
+    "SigRepo Signature ID" = blank_na(info_row$signature_id),
+    "SigRepo Signature Name" = base::as.character(info_row$signature_name),
+    "Group Label" = blank_na(info_row$group_label),
+    "Symbol Source" = blank_na(info_row$symbol_source),
+    "SigRepo Direction" = blank_na(info_row$direction),
+    "SigRepo Ranked Table" = run$ranked_table,
+    "SigRepo Score Column" = run$score_col,
+    "SigRepo Split" = run$split,
+    "SigRepo Background Source" = run$background_source,
+    "SigRepo Features Unmapped" = base::as.character(info_row$n_dropped),
+    "SigRepo Query Genes Removed" = base::as.character(run$query_genes_removed),
+    "SigRepo Genesets Dropped" = base::as.character(base::length(run$genesets_dropped)),
+    "SigRepo Genesets Dropped List" = dropped_list,
+    "SigRepo FDR Scope" = run$fdr_scope
+  ))
+  hyp_obj
+}
 
-  omic_signatures <- resolveHypeRSignatures(
-    conn_handler = conn_handler,
-    signature_id = signature_id,
-    signature_name = signature_name,
-    omic_signature = omic_signature,
-    verbose = verbose
-  )
-  signature_labels <- resolveHypeRSignatureLabels(omic_signatures)
+HYPER_PROVENANCE_KEYS <- c(
+  "SigRepo Signature ID", "SigRepo Signature Name", "Group Label", "Symbol Source",
+  "SigRepo Direction", "SigRepo Ranked Table", "SigRepo Score Column", "SigRepo Split",
+  "SigRepo Background Source", "SigRepo Features Unmapped", "SigRepo Query Genes Removed",
+  "SigRepo Genesets Dropped", "SigRepo Genesets Dropped List", "SigRepo FDR Scope"
+)
+
+isHypeRBackgroundValue <- function(background) {
+  is_number <- base::is.numeric(background) && base::length(background) == 1L &&
+    base::is.finite(background) && background > 0
+  is_genes <- base::is.character(background) && base::length(background) >= 2L
+  is_number || is_genes || base::identical(background, "difexp")
+}
 
-  build_group_component <- function(group_label, suffix = NULL) {
-    clean_group <- if (base::is.null(group_label) || base::is.na(group_label) || !base::nzchar(group_label)) {
-      "all_features"
-    } else {
-      base::gsub("[^A-Za-z0-9]+", "_", base::tolower(base::as.character(group_label)))
+#' Error unless background is NULL, a positive number, a gene vector, "difexp",
+#' or a named list of those
+#' @noRd
+checkHypeRBackground <- function(background) {
+  if (base::is.null(background)) {
+    return(base::invisible(background))
+  }
+  if (base::is.list(background)) {
+    keys <- base::names(background)
+    if (base::length(background) == 0 || base::is.null(keys) || base::any(base::is.na(keys) | !base::nzchar(keys)) ||
+        base::anyDuplicated(keys)) {
+      base::stop("\nA background list must name every element uniquely, by signature label or signature ID.\n")
     }
-
-    if (base::is.null(suffix) || !base::nzchar(suffix)) {
-      return(clean_group)
+    bad <- keys[!base::vapply(background, isHypeRBackgroundValue, base::logical(1))]
+    if (base::length(bad) > 0) {
+      base::stop(base::sprintf(
+        "\nbackground must be a number, a gene vector, or \"difexp\" for every list element; not for %s.\n",
+        base::paste(base::sprintf("'%s'", bad), collapse = ", ")
+      ))
     }
-
-    base::paste0(clean_group, "_", suffix)
+    return(base::invisible(background))
   }
+  if (!isHypeRBackgroundValue(background)) {
+    base::stop("\nbackground must be a number, a gene vector, or \"difexp\" (or a named list of those, one per signature).\n")
+  }
+  base::invisible(background)
+}
 
-  vectors <- base::list()
-  metadata <- base::list()
-  metadata_idx <- 0
+#' Drop genesets hypeR's kstest cannot score
+#'
+#' hypeR's kstest breaks on two kinds of geneset, erroring or silently shifting
+#' scores onto other genesets:
+#' \itemize{
+#'   \item (weighted kstest, `power != 0` only) every member present in `query`
+#'   has score exactly 0, so the hit weights sum to 0;
+#'   \item (any power) the members present in `query` number exactly
+#'   `length(query)`, so there are no misses and the miss step divides by 0.
+#' }
+#' Genesets with no members in `query` are kept.
+#'
+#' hypeR reduces genesets to a gene-vector background before the kstest, so
+#' when `background` is a character vector the checks use each geneset's
+#' members within it. The returned genesets are not reduced; hypeR still does
+#' that itself.
+#'
+#' @param genesets Named list, `hypeR::gsets` or `hypeR::rgsets`.
+#' @param query Named numeric vector (gene -> score).
+#' @param background The query's background; only a character vector matters.
+#' @param power hypeR's `power`; the zero-weight check runs only when it is not 0.
+#' @return list(genesets = same kind as the input, unchanged when nothing is
+#'   dropped, or NULL when every geneset is dropped (hypeR cannot build an
+#'   empty gsets); dropped = chr labels)
+#' @noRd
+dropZeroWeightGenesets <- function(genesets, query, background = NULL, power = 1) {
+  unchanged <- base::list(genesets = genesets, dropped = base::character())
+  # A character query is a ranking of gene names (no weights to be zero).
+  ranked_names <- base::is.character(query)
+  query_genes <- base::unique(if (ranked_names) query else base::names(query))
+  check_zero_weight <- power != 0 && !ranked_names
+  zero_genes <- if (ranked_names) base::character() else base::names(query)[query == 0]
+  nonzero_genes <- if (ranked_names) query_genes else base::names(query)[query != 0]
+
+  is_hyper_gsets <- methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")
+  members <- if (is_hyper_gsets) genesets$genesets else genesets
+  reduce_to_background <- base::is.character(background)
+  drop <- base::vapply(members, function(genes) {
+    if (reduce_to_background) {
+      genes <- genes[genes %in% background]
+    }
+    genes <- base::unique(genes)
+    zero_weight <- check_zero_weight && base::length(zero_genes) > 0 &&
+      base::any(genes %in% zero_genes) && !base::any(genes %in% nonzero_genes)
+    full_coverage <- base::sum(genes %in% query_genes) == base::length(query_genes)
+    zero_weight || full_coverage
+  }, base::logical(1))
+  if (!base::any(drop)) {
+    return(unchanged)
+  }
 
-  for (sig_idx in base::seq_along(omic_signatures)) {
-    sig_obj <- omic_signatures[[sig_idx]]
-    sig_name <- signature_labels[[sig_idx]]
+  kept_labels <- base::names(members)[!drop]
+  reduced <- if (base::length(kept_labels) == 0) {
+    NULL
+  } else if (methods::is(genesets, "rgsets")) {
+    genesets$subset(kept_labels)
+  } else if (methods::is(genesets, "gsets")) {
+    hypeR::gsets$new(members[!drop], name = genesets$name, version = genesets$version, quiet = TRUE)
+  } else {
+    genesets[!drop]
+  }
 
-    if (identical(method, "hypergeo")) {
-      signature_tbl <- sig_obj$signature
+  base::list(genesets = reduced, dropped = base::names(members)[drop])
+}
 
-      if (!methods::is(signature_tbl, "data.frame") || base::nrow(signature_tbl) == 0) {
-        base::stop(
-          base::sprintf("\nSignature '%s' does not contain a non-empty 'signature' table.\n", sig_name)
-        )
-      }
+#' Work around hypeR's kstest failing on a one-geneset list
+#'
+#' hypeR's `.ks_enrichment()` errors with "dim(X) must have a positive length"
+#' when given a single geneset. For that case this returns the geneset twice,
+#' the copy under a label that cannot collide. Both copies get the same
+#' p-value, so hypeR's BH FDR for the real row equals its p-value, as it would
+#' for a single test. Returns NULL when there is not exactly one geneset.
+#' @noRd
+duplicateSingleHypeRGeneset <- function(genesets) {
+  if (countHypeRGenesets(genesets) != 1L) {
+    return(NULL)
+  }
+  members <- if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) genesets$genesets else genesets
+  label <- base::names(members)[1]
+  copy_label <- base::paste0(label, " [SigRepo duplicate]")
+  duplicated_members <- stats::setNames(c(members, members), c(label, copy_label))
+  base::list(
+    genesets = hypeR::gsets$new(
+      duplicated_members,
+      name = if (base::is.list(genesets) && !methods::is(genesets, "R6")) "custom" else genesets$name,
+      version = if (base::is.list(genesets) && !methods::is(genesets, "R6")) "" else genesets$version,
+      quiet = TRUE
+    ),
+    label = label,
+    copy_label = copy_label
+  )
+}
 
-      if (!feature_col %in% base::colnames(signature_tbl)) {
-        base::stop(
-          base::sprintf("\nSignature '%s' is missing feature column '%s' in 'signature'.\n", sig_name, feature_col)
-        )
-      }
+#' Drop the duplicate geneset from a hyp run through duplicateSingleHypeRGeneset()
+#'
+#' Removes the copy's row and plot, and puts the caller's genesets (reduced to
+#' a gene-vector background, as hypeR does) back into `hyp$args`, so plots and
+#' curve data see the geneset the caller passed.
+#' @noRd
+restoreSingleHypeRGeneset <- function(hyp_obj, single, genesets, background) {
+  hyp_obj$data <- hyp_obj$data[hyp_obj$data$label != single$copy_label, , drop = FALSE]
+  base::rownames(hyp_obj$data) <- NULL
+  if (base::length(hyp_obj$plots) > 0) {
+    hyp_obj$plots <- hyp_obj$plots[base::names(hyp_obj$plots) != single$copy_label]
+  }
+  original <- if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) genesets else hypeR::gsets$new(genesets, quiet = TRUE)
+  hyp_obj$args$genesets <- if (base::is.character(background)) original$reduce(background) else original
+  base::invisible(hyp_obj)
+}
 
-      if (split_by_group && "group_label" %in% base::colnames(signature_tbl)) {
-        signature_tbl$group_label <- base::as.character(signature_tbl$group_label)
-      } else {
-        signature_tbl$group_label <- "all_features"
-      }
+#' Number of genesets in a named list, `hypeR::gsets` or `hypeR::rgsets` (0 for NULL)
+#' @noRd
+countHypeRGenesets <- function(genesets) {
+  if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) {
+    return(base::length(genesets$genesets))
+  }
+  base::length(genesets)
+}
 
-      if (split_by_direction) {
-        if (!score_col %in% base::colnames(signature_tbl)) {
-          base::stop(
-            base::sprintf(
-              "\nSignature '%s' is missing score column '%s', which is required for direction splitting.\n",
-              sig_name,
-              score_col
-            )
-          )
-        }
-        signature_tbl$score_value <- base::suppressWarnings(base::as.numeric(signature_tbl[[score_col]]))
-      }
+warnSkippedHypeRSignatures <- function(skipped) {
+  if (base::nrow(skipped) == 0) {
+    return(base::invisible(NULL))
+  }
+  base::warning(
+    base::sprintf(
+      "Skipped %d signature(s): %s",
+      base::nrow(skipped),
+      base::paste(base::sprintf("'%s' (%s: %s)", skipped$signature, skipped$reason, skipped$message), collapse = "; ")
+    ),
+    call. = FALSE
+  )
+}
 
-      for (group_label in base::unique(signature_tbl$group_label)) {
-        group_tbl <- signature_tbl[signature_tbl$group_label == group_label, , drop = FALSE]
-
-        if (split_by_direction) {
-          direction_specs <- base::list(
-            base::list(suffix = "up", keep = !base::is.na(group_tbl$score_value) & group_tbl$score_value >= 0),
-            base::list(suffix = "dn", keep = !base::is.na(group_tbl$score_value) & group_tbl$score_value < 0)
-          )
-
-          for (direction in direction_specs) {
-            query_features <- base::unique(base::as.character(group_tbl[[feature_col]][direction$keep]))
-            query_features <- query_features[!base::is.na(query_features) & query_features != ""]
-            if (base::length(query_features) == 0) {
-              next
-            }
-
-            component <- build_group_component(group_label, direction$suffix)
-            query_name <- base::sprintf("%s | %s", sig_name, component)
-            vectors[[query_name]] <- query_features
-
-            metadata_idx <- metadata_idx + 1
-            metadata[[metadata_idx]] <- base::data.frame(
-              query_name = query_name,
-              signature_name = sig_name,
-              method = method,
-              group_label = component,
-              n_features = base::length(query_features),
-              stringsAsFactors = FALSE
-            )
-          }
-        } else {
-          query_features <- base::unique(base::as.character(group_tbl[[feature_col]]))
-          query_features <- query_features[!base::is.na(query_features) & query_features != ""]
-          if (base::length(query_features) == 0) {
-            next
-          }
-
-          component <- build_group_component(group_label)
-          query_name <- if (identical(component, "all_features")) sig_name else base::sprintf("%s | %s", sig_name, component)
-          vectors[[query_name]] <- query_features
-
-          metadata_idx <- metadata_idx + 1
-          metadata[[metadata_idx]] <- base::data.frame(
-            query_name = query_name,
-            signature_name = sig_name,
-            method = method,
-            group_label = component,
-            n_features = base::length(query_features),
-            stringsAsFactors = FALSE
-          )
-        }
-      }
-    } else {
-      difexp_tbl <- sig_obj$difexp
-
-      if (!methods::is(difexp_tbl, "data.frame") || base::nrow(difexp_tbl) == 0) {
-        base::stop(
-          base::sprintf(
-            "\nSignature '%s' does not contain a non-empty 'difexp' table, which is required for '%s'.\n",
-            sig_name,
-            method
-          )
-        )
-      }
+#' Apply pval/fdr cutoffs to hyp results and record them in args and info
+#' @noRd
+filterHypeRResults <- function(results, pval, fdr) {
+  for (k in base::seq_along(results)) {
+    data <- results[[k]]$data
+    results[[k]]$data <- data[data$pval <= pval & data$fdr <= fdr, , drop = FALSE]
+    results[[k]]$args$pval <- pval
+    results[[k]]$args$fdr <- fdr
+    results[[k]]$info[["P-Value"]] <- base::as.character(pval)
+    results[[k]]$info[["FDR"]] <- base::as.character(fdr)
+  }
+  results
+}
 
-      missing_cols <- base::setdiff(c(feature_col, score_col), base::colnames(difexp_tbl))
-      if (base::length(missing_cols) > 0) {
-        base::stop(
-          base::sprintf(
-            "\nSignature '%s' is missing required difexp column(s): %s.\n",
-            sig_name,
-            base::paste0(missing_cols, collapse = ", ")
-          )
-        )
+#' FDR across every query of a run, then hypeR's pval/fdr filters
+#'
+#' BS831's hyperEnrichment() (mht = TRUE) adjusts p-values across all
+#' signatures x genesets tested, not per signature. hypeR keeps only p-values
+#' rounded to 2 significant digits, so the pooled FDR is computed from those,
+#' as hyperEnrichment() does. With a single query the FDR hypeR computed is
+#' kept. hypeR ran with pval = fdr = 1, so the filters are applied here and
+#' the hyp's args and info record the requested cutoffs.
+#' @noRd
+applyRunHypeRFdr <- function(results, pval, fdr) {
+  if (base::length(results) > 1L) {
+    n_rows <- base::vapply(results, function(h) base::nrow(h$data), base::integer(1))
+    pooled <- stats::p.adjust(base::unlist(base::lapply(results, function(h) h$data$pval), use.names = FALSE), method = "fdr")
+    ends <- base::cumsum(n_rows)
+    for (k in base::seq_along(results)) {
+      if (n_rows[k] > 0) {
+        results[[k]]$data$fdr <- base::signif(pooled[(ends[k] - n_rows[k] + 1L):ends[k]], 2)
       }
+    }
+  }
+  filterHypeRResults(results, pval, fdr)
+}
 
-      if (split_by_group && "group_label" %in% base::colnames(difexp_tbl)) {
-        difexp_tbl$group_label <- base::as.character(difexp_tbl$group_label)
-      } else {
-        difexp_tbl$group_label <- "all_features"
-      }
+#' FDR scope, filters and return type shared by every test in runHypeR()
+#'
+#' @param results Named list of hyp objects, one per query (or fgsea side).
+#' @return A hyp when the input is single and the call yields one hyp by
+#'   construction, otherwise a multihyp.
+#' @noRd
+finishHypeRRun <- function(results, fdr_scope, pval, fdr, test, split, inputs, native) {
+  if (base::identical(test, "fgsea")) {
+    # runFgseaQueries() already pooled the FDR (fdr_scope = "run", across
+    # every up/down side of every ranking) or
+    # kept fgsea's own per-ranking padj (fdr_scope = "query"); only the
+    # pval/fdr cutoffs remain to apply here, for both scopes.
+    results <- filterHypeRResults(results, pval = pval, fdr = fdr)
+  } else if (fdr_scope == "run") {
+    results <- applyRunHypeRFdr(results, pval = pval, fdr = fdr)
+  }
 
-      difexp_tbl$feature_value <- base::as.character(difexp_tbl[[feature_col]])
-      difexp_tbl$score_value <- base::suppressWarnings(base::as.numeric(difexp_tbl[[score_col]]))
-      difexp_tbl <- difexp_tbl[
-        !base::is.na(difexp_tbl$feature_value) & difexp_tbl$feature_value != "" &
-          !base::is.na(difexp_tbl$score_value),
-        ,
-        drop = FALSE
-      ]
-
-      for (group_label in base::unique(difexp_tbl$group_label)) {
-        group_tbl <- difexp_tbl[difexp_tbl$group_label == group_label, , drop = FALSE]
-        if (base::nrow(group_tbl) == 0) {
-          next
-        }
+  # The ranked tests always return an up and a down query per ranking.
+  one_by_construction <- base::identical(test, "hypergeometric") && (native || !split)
+  if (inputs$single && one_by_construction) {
+    return(results[[1]])
+  }
+  hypeR::multihyp$new(data = results)
+}
 
-        ranked_tbl <- group_tbl |>
-          dplyr::group_by(.data$feature_value) |>
-          dplyr::summarise(
-            score_value = .data$score_value[base::which.max(base::abs(.data$score_value))],
-            .groups = "drop"
-          ) |>
-          dplyr::arrange(dplyr::desc(.data$score_value))
-
-        ranked_vector <- stats::setNames(ranked_tbl$score_value, ranked_tbl$feature_value)
-        if (base::length(ranked_vector) == 0) {
-          next
-        }
+HYPER_TESTS <- c("hypergeometric", "kstest", "fgsea")
 
-        component <- build_group_component(group_label)
-        query_name <- if (identical(component, "all_features")) sig_name else base::sprintf("%s | %s", sig_name, component)
-        vectors[[query_name]] <- ranked_vector
-
-        metadata_idx <- metadata_idx + 1
-        metadata[[metadata_idx]] <- base::data.frame(
-          query_name = query_name,
-          signature_name = sig_name,
-          method = method,
-          group_label = component,
-          n_features = base::length(ranked_vector),
-          stringsAsFactors = FALSE
-        )
-      }
-    }
+#' runHypeR()'s required organism: one non-empty string
+#' @noRd
+checkHypeROrganism <- function(organism) {
+  if (base::is.null(organism) || !base::is.character(organism) || base::length(organism) != 1L ||
+      base::is.na(organism) || !base::nzchar(base::trimws(organism))) {
+    base::stop("\n'organism' is required: the organism of the signatures, e.g. organism = \"Homo sapiens\" or organism = \"Mus musculus\".\n", call. = FALSE)
   }
+  base::trimws(organism)
+}
 
-  if (base::length(vectors) == 0) {
-    base::stop(
-      base::sprintf(
-        "\nNo valid signatures were available to prepare '%s' enrichment inputs.\n",
-        method
-      )
-    )
+#' runHypeR()'s required test: exactly one of HYPER_TESTS
+#' @noRd
+checkHypeRTest <- function(test) {
+  if (base::is.null(test) || !base::is.character(test) || base::length(test) != 1L || !(test %in% HYPER_TESTS)) {
+    base::stop(base::sprintf(
+      "\n'test' is required: one of %s.\n",
+      base::paste(base::sprintf("test = \"%s\"", HYPER_TESTS), collapse = ", ")
+    ), call. = FALSE)
   }
+  test
+}
 
-  metadata_df <- if (metadata_idx > 0) {
-    dplyr::bind_rows(metadata)
-  } else {
-    base::data.frame(
-      query_name = character(),
-      signature_name = character(),
-      method = character(),
-      group_label = character(),
-      n_features = numeric(),
-      stringsAsFactors = FALSE
-    )
+#' Stop when any SigRepo signature is not of the requested organism
+#'
+#' Genesets hold one organism's gene symbols, so a call mixing organisms (or a
+#' signature of another organism) would test symbols that cannot match.
+#' @noRd
+checkHypeRSignatureOrganisms <- function(inputs, organism) {
+  found <- base::vapply(inputs$signatures, function(sig) {
+    value <- sig$metadata$organism
+    if (base::is.null(value) || base::length(value) == 0 || base::is.na(value[[1]])) "" else base::trimws(base::as.character(value[[1]]))
+  }, base::character(1))
+  wrong <- base::tolower(found) != base::tolower(organism)
+  if (!base::any(wrong)) {
+    return(base::invisible(TRUE))
   }
-
-  base::list(
-    signatures = vectors,
-    metadata = metadata_df,
-    omic_signatures = omic_signatures
-  )
+  base::stop(base::sprintf(
+    "\nEvery signature must be of organism = \"%s\"; run signatures of different organisms in separate runHypeR() calls. Not %s: %s.\n",
+    organism,
+    organism,
+    base::paste(base::sprintf("'%s' (%s)", inputs$labels[wrong], base::ifelse(base::nzchar(found[wrong]), found[wrong], "no organism recorded")), collapse = ", ")
+  ), call. = FALSE)
 }
 
-#' Run hypeR enrichment directly from SigRepo signatures
+#' Run hypeR enrichment on SigRepo signatures
 #'
-#' @description Resolves one or more signatures from SigRepo and runs
-#' \code{hypeR::hypeR()} on them without requiring the user to call
-#' \code{getSignature()} manually first.
+#' @description Builds hypeR query vectors from SigRepo signatures (see
+#' \code{prepareHypeRSignatures()}) and runs \code{hypeR::hypeR()} on them. The
+#' arguments after \code{query_names} are hypeR's own, with hypeR's defaults,
+#' and the result is hypeR's own object. Plot it with \code{plotHypeRDots()},
+#' \code{plotHypeREnrichment()} and \code{plotHypeRMap()}; hypeR's own
+#' \code{hypeR::hyp_dots()},
+#' \code{hyp_emap()}, \code{hyp_to_rmd()}, \code{hyp_to_table()} and
+#' \code{rctbl_build()} work on it directly, and \code{hyp_hmap()} does when
+#' \code{genesets} is a \code{hypeR::rgsets}. \code{hyp_show()} takes a single
+#' \code{hyp}, so pass one element of a \code{multihyp}, e.g.
+#' \code{hypeR::hyp_show(res$data[[1]])}; \code{hyp_to_graph()} also needs
+#' \code{rgsets} genesets.
 #'
-#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
-#' Required unless \code{omic_signature} is supplied.
-#' @param signature_id One or more SigRepo signature IDs.
-#' @param signature_name One or more SigRepo signature names.
-#' @param omic_signature A single \code{OmicSignature} object or a list of
-#' \code{OmicSignature} objects.
-#' @param genesets A named list of genesets, a \code{hypeR} \code{gsets}
-#' object, or a \code{hypeR} \code{rgsets} object supplied to \code{hypeR}.
-#' Alternatively, leave this as \code{NULL} and specify
-#' \code{msigdb_collection} to fetch genesets from MSigDB automatically.
-#' @param msigdb_species Species passed to \code{hypeR::msigdb_gsets()} when
-#' \code{msigdb_collection} is supplied. Defaults to \code{"Homo sapiens"}.
-#' @param msigdb_collection MSigDB collection identifier, such as \code{"H"}
-#' or \code{"C2"}. When supplied, \code{runHypeR()} retrieves genesets
-#' automatically via \code{hypeR::msigdb_gsets()}.
-#' @param msigdb_subcollection Optional MSigDB subcollection identifier, such as
-#' \code{"CP:KEGG_LEGACY"}.
-#' @param msigdb_clean Logical; whether to clean MSigDB geneset labels using
-#' \code{hypeR::msigdb_gsets(clean = ...)}. Defaults to \code{FALSE}.
-#' @param method One of \code{"hypergeo"}, \code{"kstest"}, or \code{"gsea"}.
-#' @param feature_col Column containing feature identifiers. Defaults to
-#' \code{"feature_name"}.
-#' @param score_col Column containing ranked scores for KS/GSEA-style enrichment.
-#' Defaults to \code{"score"}.
-#' @param split_by_group Logical; whether to create separate query vectors for
-#' each \code{group_label}. Defaults to \code{FALSE}.
-#' @param split_by_direction Logical; when \code{method = "hypergeo"}, whether
-#' to split each group into up- and down-direction feature sets using the sign
-#' of \code{score_col}. Defaults to \code{FALSE}.
-#' @param background Optional background size passed to \code{hypeR}.
-#' @param fdr FDR threshold passed to \code{hypeR}. Defaults to \code{0.05}.
-#' @param plotting Logical; whether to let \code{hypeR} generate plots.
-#' Defaults to \code{FALSE}.
-#' @param quiet Logical; whether to suppress \code{hypeR} messages.
-#' Defaults to \code{TRUE}.
-#' @param absolute Passed to \code{hypeR} for GSEA-style ranked enrichment.
-#' Defaults to \code{FALSE}.
-#' @param power Passed to \code{hypeR} for GSEA-style ranked enrichment.
-#' Defaults to \code{1}.
-#' @param ... Additional arguments passed directly to \code{hypeR::hypeR()}.
-#' Use this for extra tuning parameters such as \code{background} or other
-#' engine-specific options.
-#' @param verbose Logical; whether or not to print diagnostic messages while
-#' retrieving signatures. Defaults to \code{TRUE}.
+#' \code{hypeR::hyp_to_excel()} uses each query name as an Excel sheet name,
+#' which must be at most 31 characters and cannot contain
+#' \code{: \\ / ? * [ ]}; most SigRepo signature names are longer. Use
+#' \code{hypeRToExcel()}, which makes the sheet names safe and adds an index
+#' sheet, or shorten the names with \code{query_names}.
 #'
-#' @return A list with:
-#' \describe{
-#'   \item{\code{result}}{A \code{hyp} or \code{multihyp} object returned by \code{hypeR}.}
-#'   \item{\code{signatures}}{The query vectors passed into \code{hypeR}.}
-#'   \item{\code{metadata}}{A data frame describing each query vector.}
+#' @section Required and optional arguments:
+#' Four things are required and have no default:
+#' \itemize{
+#'   \item \strong{Signatures}, as exactly one of: \code{signature_id} or
+#'   \code{signature_name} (each with \code{conn_handler}),
+#'   \code{omic_signature}, or \code{signature} (hypeR-native gene symbols or
+#'   a named score vector). They cannot be combined.
+#'   \item \strong{\code{organism}}: the organism of every signature in the
+#'   call, e.g. \code{"Homo sapiens"}. A signature of another organism is an
+#'   error, so human and mouse signatures run in separate calls.
+#'   \item \strong{\code{test}}: \code{"hypergeometric"}, \code{"kstest"}
+#'   or \code{"fgsea"}.
+#'   \item \strong{\code{genesets}}: \code{"msigdb"} together with
+#'   \code{msigdb_collection}, or your own genesets (a named list,
+#'   \code{hypeR::gsets} or \code{hypeR::rgsets}).
 #' }
 #'
+#' Every other argument is optional: each has a default, listed with it below,
+#' and leaving it alone runs the lab's conventions (see the Details of
+#' \code{background}, \code{min_query_genes} and \code{fdr_scope}). The
+#' arguments that take \code{NULL} treat it as "choose for me" rather than
+#' "nothing": \code{background = NULL} picks the background per signature,
+#' \code{query_names = NULL} builds the default query names,
+#' \code{seed = NULL} leaves fgsea on the session's random-number state, and
+#' the \code{msigdb_*} arguments apply only with \code{genesets = "msigdb"}.
+#'
+#' @inheritParams prepareHypeRSignatures
+#' @inheritParams getHypeRGenesets
+#' @param organism Required. The organism of the signatures, e.g.
+#' \code{"Homo sapiens"} or \code{"Mus musculus"}, compared with each SigRepo
+#' signature's \code{metadata$organism} ignoring case. A signature of another
+#' organism, or with none recorded, is an error: one call tests one organism,
+#' because genesets are organism-specific gene symbols. With
+#' \code{genesets = "msigdb"} it is also the MSigDB species. With
+#' \code{signature} input there is no metadata to check, so it only chooses
+#' the MSigDB species.
+#' @param test Required: \code{"hypergeometric"} (a character vector of
+#' symbols from the signature table), \code{"kstest"} (a named numeric vector
+#' ranked by \code{score_col}, from the table named by \code{ks_source}) or
+#' \code{"fgsea"} (the same ranking as \code{"kstest"}, tested with
+#' \code{fgsea::fgseaMultilevel()}). With \code{"fgsea"}, \code{signature}
+#' input must be named numeric vectors.
+#' @param seed \code{test = "fgsea"} only: fgsea's p-values come from random
+#' sampling, so each ranking's run starts from \code{set.seed(seed)} and the
+#' caller's random-number state is restored afterwards. Defaults to \code{1};
+#' \code{NULL} uses the session's random-number state. Recorded as \code{Seed}
+#' in \code{info}.
+#' @param fgsea_args \code{test = "fgsea"} only: a named list of
+#' \code{fgsea::fgseaMultilevel()} arguments merged over the defaults
+#' \code{sampleSize = 101, minSize = 1, maxSize = Inf}, e.g.
+#' \code{list(minSize = 15, maxSize = 500, nproc = 4)}. \code{stats},
+#' \code{pathways} and \code{gseaParam} (set by \code{power}) cannot be given.
+#' @param min_query_genes Hypergeometric only: skip, with a warning, a query
+#' with fewer than this many genes found in the genesets. Defaults to \code{4},
+#' the \code{min.drawsize} of BS831's \code{hyperEnrichment()}.
+#' @param fdr_scope \code{"run"} (default) adjusts p-values for multiple testing
+#' across every query and geneset in the call, as BS831's
+#' \code{hyperEnrichment()} does across signatures; \code{"query"} adjusts
+#' within each query, as \code{hypeR::hypeR()} does for a named list. With one
+#' query both are the same. The pooled FDR is computed from hypeR's p-values,
+#' which are rounded to 2 significant digits. \code{pval} and \code{fdr} filter
+#' on the FDR of the chosen scope. For \code{test = "fgsea"}, \code{"run"}
+#' pools the up and down sides of every ranking in the call (also with a
+#' single ranking); \code{"query"} keeps
+#' fgsea's own per-ranking \code{padj}, which already covers both sides.
+#' @param background \code{NULL} (default) uses each signature's measured genes
+#' from its difexp table when it has difexp gene symbols, and \code{23467}
+#' otherwise (always \code{23467} for \code{signature} input). A difexp that
+#' looks filtered is not a measured-gene universe, so the default also uses
+#' \code{23467}, with a warning, when a transcriptomics difexp has fewer than
+#' 10,000 rows, a difexp has no more than twice its signature's rows, or every
+#' \code{p_value}, \code{pvalue} or \code{adj_p} is at most 0.05. For
+#' \code{test = "kstest"} the default is \code{23467}: the ranked list is the
+#' universe, so the background does not enter the test. \code{test = "fgsea"}
+#' defaults to \code{23467} as well and for the same reason (the ranking is
+#' the universe): a number has no effect on the fgsea result, while a gene
+#' vector or \code{"difexp"} still reduces the genesets and the ranking to
+#' those genes. Otherwise
+#' hypeR's background: a single number (population size), a
+#' character vector of background genes, or \code{"difexp"} to use each
+#' signature's measured genes from its difexp table. With an explicit
+#' \code{"difexp"}, signatures without difexp
+#' symbols fall back to \code{23467} with a warning. For a different background
+#' per signature, pass a named list of those forms, one element per signature,
+#' named by signature label (see \code{prepareHypeRSignatures()$info$signature_name};
+#' with \code{signature}, the list names) or by signature ID; arms of a split
+#' signature share its background. A name that matches no signature, or a
+#' signature with no entry, is an error. With a gene vector or
+#' \code{"difexp"}, every query (the hypergeometric gene list, or the kstest
+#' and fgsea ranking) is first reduced to the background genes, with a warning
+#' naming each query that lost genes: hypeR reduces only the genesets, and
+#' query genes outside the background would distort the p-values. A query left
+#' with no genes is skipped with a warning. Anything else (e.g.
+#' \code{"Difexp"}) is an error.
+#' @param power Exponent for the score weights: fgsea's \code{gseaParam} with
+#' \code{test = "fgsea"}, where it does change the p-values. For kstest it changes
+#' only the enrichment \code{score}. \code{1} (default) weights hits by
+#' |score|. \code{0} runs hypeR's ranked (unweighted) signature: the query is
+#' passed as gene names in rank order, so \code{score} and
+#' \code{Signature Type = "ranked"} match hypeR's documented ranked test. The
+#' \code{pval} and \code{fdr} come from hypeR's unweighted, one-sided KS test
+#' and do not depend on \code{power}. That test finds
+#' genesets enriched toward the top of the ranking, which is why every kstest
+#' also runs a \code{"| down"} query on the negated scores. hypeR's kstest also cannot score a geneset whose hits in
+#' a query all have score 0 (\code{power != 0}) or that contains every query
+#' gene (any power); such genesets are dropped for that query with a warning,
+#' which also removes them from the FDR adjustment. They are listed in the
+#' result's \code{info} (see Value). A kstest query left with a single geneset
+#' is still tested (hypeR itself errors on a one-geneset list); its FDR equals
+#' its p-value. hypeR's \code{absolute} option is not offered: hypeR marks it
+#' as not implemented, and \code{runHypeR()} always runs with
+#' \code{absolute = FALSE}.
+#' @param pval Keep results with p-value at or below this. Defaults to \code{1}.
+#' @param fdr Keep results with FDR at or below this. Defaults to \code{1}.
+#' @param plotting Logical; generate hypeR's per-geneset plots. Defaults to
+#' \code{FALSE}, in which case the empty placeholder plots hypeR stores anyway
+#' are removed (they are most of the object's size). fgsea makes no plots, so
+#' \code{TRUE} with \code{test = "fgsea"} warns and is ignored. To plot one
+#' geneset without storing every plot, use \code{plotHypeREnrichment()}.
+#' @param quiet Logical; suppress hypeR's logs. Defaults to \code{TRUE}. With
+#' \code{test = "fgsea"} this also suppresses fgsea's own console output
+#' (its progress bars).
+#'
+#' @return A \code{hyp} when the input is a single vector in \code{signature},
+#' or a single signature (one \code{OmicSignature}, or one id or name) and the
+#' test builds one query by construction (hypergeometric with
+#' \code{split = FALSE}, or a single \code{signature} vector). Otherwise a
+#' \code{multihyp} named by query, even when only one query is left: the
+#' ranked tests always return an \code{"| up"} and a \code{"| down"} query
+#' per ranking. This mirrors hypeR, where a vector gives a \code{hyp} and a
+#' named list a \code{multihyp}.
+#'
+#' With \code{test = "fgsea"}, each ranking runs
+#' \code{fgsea::fgseaMultilevel()} once, and its pathways are split by the sign
+#' of their enrichment score into \code{"<query> | up"} (ES > 0) and
+#' \code{"<query> | down"} (ES < 0) hyps; pathways with ES = 0 join
+#' neither. Their \code{data} has \code{label}, \code{pval}, \code{fdr},
+#' \code{lte} (log2err), \code{es}, \code{nes}, \code{signature},
+#' \code{geneset}, \code{overlap}, \code{le} and \code{hits} (the leading
+#' edge), and \code{info} adds \code{fgsea}, \code{Sample Size},
+#' \code{Min Size}, \code{Max Size}, \code{Seed} and \code{fgsea Args}
+#' before the SigRepo keys. fgsea's own FDR covers every pathway of the
+#' ranking, both sides.
+#'
+#' Each \code{hyp$info} ends with these keys, in this order (\code{""} when a
+#' key does not apply): \code{SigRepo Signature ID},
+#' \code{SigRepo Signature Name}, \code{Group Label}, \code{Symbol Source},
+#' \code{SigRepo Direction}, \code{SigRepo Ranked Table},
+#' \code{SigRepo Score Column}, \code{SigRepo Split},
+#' \code{SigRepo Background Source} (\code{number}, \code{genes},
+#' \code{difexp}, \code{difexp-fallback} or \code{difexp-truncated}),
+#' \code{SigRepo Features Unmapped}, \code{SigRepo Query Genes Removed},
+#' \code{SigRepo Genesets Dropped}, \code{SigRepo Genesets Dropped List} and
+#' \code{SigRepo FDR Scope}.
+#'
+#' Signatures that cannot produce a query are skipped with a warning; if none
+#' can, an error is raised. A query left with no genesets or no genes (after
+#' the drops described under \code{power} and \code{background}), or a
+#' hypergeometric query below \code{min_query_genes}, is skipped with a
+#' warning; if no query is left, an error is raised.
+#'
 #' @examples
 #' \dontrun{
-#' hyp_res <- SigRepo::runHypeR(
-#'   conn_handler = conn_handler,
-#'   signature_name = "example_signature",
-#'   msigdb_collection = "H",
-#'   method = "hypergeo",
-#'   background = 20000
+#' utils::data("LLFS_Aging_Gene_2023", package = "SigRepo")
+#' hallmark <- SigRepo::getHypeRGenesets("msigdb", msigdb_collection = "H")
+#'
+#' hyp <- SigRepo::runHypeR(
+#'   omic_signature = LLFS_Aging_Gene_2023,
+#'   organism = "Homo sapiens",
+#'   test = "hypergeometric",
+#'   genesets = hallmark,
+#'   fdr = 0.05
+#' )
+#' SigRepo::plotHypeRDots(hyp)
+#' SigRepo::hypeRToExcel(hyp, file_path = "llfs_hallmark.xlsx")
+#'
+#' ranked <- SigRepo::runHypeR(
+#'   omic_signature = LLFS_Aging_Gene_2023,
+#'   organism = "Homo sapiens",
+#'   test = "kstest",
+#'   genesets = hallmark
 #' )
 #' }
 #'
@@ -641,102 +905,366 @@ runHypeR <- function(
     signature_id = NULL,
     signature_name = NULL,
     omic_signature = NULL,
-    genesets = NULL,
-    msigdb_species = "Homo sapiens",
+    signature = NULL,
+    organism,
+    test,
+    genesets,
     msigdb_collection = NULL,
     msigdb_subcollection = NULL,
     msigdb_clean = FALSE,
-    method = c("hypergeo", "kstest", "gsea"),
-    feature_col = "feature_name",
+    split = TRUE,
+    ks_source = c("difexp", "signature"),
     score_col = "score",
-    split_by_group = FALSE,
-    split_by_direction = FALSE,
+    query_names = NULL,
+    min_query_genes = 4,
+    fdr_scope = c("run", "query"),
+    seed = 1,
+    fgsea_args = base::list(),
     background = NULL,
-    fdr = 0.05,
+    power = 1,
+    pval = 1,
+    fdr = 1,
     plotting = FALSE,
     quiet = TRUE,
-    absolute = FALSE,
-    power = 1,
-    ...,
     verbose = TRUE
-){
-
-  if (!requireNamespace("hypeR", quietly = TRUE)) {
-    base::stop(
-      "\nPackage 'hypeR' is required for runHypeR(). Please install it first.\n"
-    )
+) {
+  if (base::missing(organism)) {
+    organism <- NULL
+  }
+  if (base::missing(test)) {
+    test <- NULL
+  }
+  organism <- checkHypeROrganism(organism)
+  test <- checkHypeRTest(test)
+  ks_source <- base::match.arg(ks_source)
+  fdr_scope <- base::match.arg(fdr_scope)
+  if (base::identical(test, "fgsea")) {
+    checkHypeRFgseaArgs(seed = seed, fgsea_args = fgsea_args, plotting = plotting)
+  }
+  checkHypeRBackground(background)
+  checkHypeRSplit(split)
+  checkHypeRKstestArgs(test, ks_source)
+  checkHypeRQueryNames(query_names)
+  if (!(base::is.numeric(min_query_genes) && base::length(min_query_genes) == 1L && !base::is.na(min_query_genes) && min_query_genes >= 1)) {
+    base::stop("\n'min_query_genes' must be a single number of at least 1.\n")
   }
 
-  method <- base::match.arg(method)
-  hype_test <- if (identical(method, "hypergeo")) "hypergeometric" else "ks"
-  extra_args <- base::list(...)
-  resolved_genesets <- resolveHypeRGenesets(
+  if (base::missing(genesets)) {
+    genesets <- NULL
+  }
+  resolved_genesets <- getHypeRGenesets(
     genesets = genesets,
-    msigdb_species = msigdb_species,
+    msigdb_species = if (base::identical(genesets, "msigdb")) organism else NULL,
     msigdb_collection = msigdb_collection,
     msigdb_subcollection = msigdb_subcollection,
     msigdb_clean = msigdb_clean
   )
 
-  reserved_args <- c("signature", "genesets", "test")
-  duplicate_reserved <- base::intersect(base::names(extra_args), reserved_args)
-  if (base::length(duplicate_reserved) > 0) {
-    base::stop(
-      base::sprintf(
-        "\nThe following hypeR arguments are handled internally by runHypeR() and cannot be supplied in '...': %s.\n",
-        base::paste0(duplicate_reserved, collapse = ", ")
-      )
-    )
+  if (!base::is.null(signature) &&
+      (base::identical(background, "difexp") || (base::is.list(background) && base::any(base::vapply(background, base::identical, base::logical(1), "difexp"))))) {
+    base::stop("\nbackground = \"difexp\" needs SigRepo signatures; 'signature' input has no difexp. Pass a number or gene vector.\n")
   }
 
-  enrichment_inputs <- prepareHypeRSignatures(
-    conn_handler = conn_handler,
-    signature_id = signature_id,
-    signature_name = signature_name,
-    omic_signature = omic_signature,
-    method = method,
-    feature_col = feature_col,
-    score_col = score_col,
-    split_by_group = split_by_group,
-    split_by_direction = split_by_direction,
-    verbose = verbose
+  resolve_symbols <- newHypeRSymbolResolver(conn_handler)
+  collected <- collectAndBuildHypeRQueries(
+    conn_handler = conn_handler, signature_id = signature_id, signature_name = signature_name,
+    omic_signature = omic_signature, signature = signature, test = test, split = split,
+    ks_source = ks_source, score_col = score_col, query_names = query_names,
+    resolve_symbols = resolve_symbols, verbose = verbose
   )
+  inputs <- collected$inputs
+  prepared <- collected$prepared
+  if (!collected$native) {
+    checkHypeRSignatureOrganisms(inputs, organism)
+  }
 
-  signature_vectors <- enrichment_inputs$signatures
+  warnSkippedHypeRSignatures(prepared$skipped)
+  if (base::length(prepared$signatures) == 0) {
+    base::stop("\nNo signature produced a hypeR query vector; see the warning for each signature's reason.\n")
+  }
 
-  hype_signature <- if (base::length(signature_vectors) == 1) {
-    signature_vectors[[1]]
-  } else {
-    signature_vectors
+  # The default difexp universe matters for the hypergeometric test only; a
+  # ranked test's universe is its ranked list, so it keeps hypeR's number.
+  if (base::is.null(background) && test %in% c("kstest", "fgsea")) {
+    background <- HYPER_DEFAULT_BACKGROUND
+  }
+  backgrounds <- resolveQueryBackgrounds(background, prepared$info, inputs, resolve_symbols)
+
+  queries <- prepared$signatures
+  query_names_out <- base::names(queries)
+
+  # hypeR reduces genesets to a gene-vector background but not the query, so a
+  # query gene outside the background (in a hypergeometric gene list, or in a
+  # kstest/fgsea ranking) would distort the p-values. Keep each query inside
+  # its background.
+  removed <- base::integer(base::length(queries))
+  for (i in base::seq_along(queries)) {
+    if (base::is.character(backgrounds$values[[i]])) {
+      genes <- if (base::is.character(queries[[i]])) queries[[i]] else base::names(queries[[i]])
+      measured <- genes %in% backgrounds$values[[i]]
+      removed[i] <- base::sum(!measured)
+      queries[[i]] <- queries[[i]][measured]
+    }
+  }
+  # One warning per background kind, so each names what the genes were missing from.
+  for (kind in c("difexp", "genes")) {
+    hit <- removed > 0 & base::startsWith(backgrounds$sources, kind)
+    if (base::any(hit)) {
+      base::warning(
+        base::sprintf(
+          "%s: removed %s query gene(s) not %s from: %s",
+          if (kind == "genes") "background" else if (base::identical(background, "difexp")) "background = \"difexp\"" else "background (difexp)",
+          base::sum(removed[hit]),
+          if (kind == "difexp") "measured in difexp" else "in the background gene vector",
+          base::paste(base::sprintf("'%s' (%d)", query_names_out[hit], removed[hit]), collapse = ", ")
+        ),
+        call. = FALSE
+      )
+    }
   }
 
-  hype_args <- base::list(
-    signature = hype_signature,
-    genesets = resolved_genesets,
-    test = hype_test,
-    fdr = fdr,
-    plotting = plotting,
-    quiet = quiet
-  )
+  if (base::identical(test, "fgsea")) {
+    # A ranking left with no genes after the background reduction cannot run.
+    empty <- base::lengths(queries) == 0
+    if (base::any(empty)) {
+      base::warning(
+        base::sprintf(
+          "Skipped %d query(ies) with nothing left to test after removing unmeasured genes: %s",
+          base::sum(empty), base::paste(base::sprintf("'%s'", query_names_out[empty]), collapse = ", ")
+        ),
+        call. = FALSE
+      )
+      if (base::all(empty)) {
+        base::stop("\nNo query had genes left to test; see the warning for the skipped queries.\n")
+      }
+    }
+    keep <- !empty
+    prepared$signatures <- queries[keep]
+    prepared$info <- prepared$info[keep, , drop = FALSE]
+    results <- runFgseaQueries(
+      prepared = prepared, backgrounds = base::lapply(backgrounds, function(x) x[keep]),
+      genesets = resolved_genesets,
+      power = power, seed = seed, fgsea_args = fgsea_args, quiet = quiet, native = collected$native,
+      ks_source = ks_source, score_col = score_col, fdr_scope = fdr_scope, query_genes_removed = removed[keep]
+    )
+    return(finishHypeRRun(results, fdr_scope, pval, fdr, test, split, inputs, collected$native))
+  }
 
-  if (!base::is.null(background)) {
-    hype_args$background <- background
+  # hypeR's kstest cannot score some genesets (all hits score 0 under
+  # power != 0, or a geneset covering every query gene); it errors or
+  # misaligns scores, so drop those per query before calling hypeR.
+  query_genesets <- base::lapply(base::seq_along(queries), function(i) {
+    if (base::identical(test, "kstest")) {
+      dropZeroWeightGenesets(resolved_genesets, queries[[i]], background = backgrounds$values[[i]], power = power)
+    } else {
+      base::list(genesets = resolved_genesets, dropped = base::character())
+    }
+  })
+  dropped <- base::unique(base::unlist(base::lapply(query_genesets, `[[`, "dropped"), use.names = FALSE))
+  if (base::length(dropped) > 0) {
+    base::warning(
+      base::sprintf(
+        "Dropped %d geneset(s) that hypeR's kstest cannot score (all hits score 0, or the geneset covers every query gene): %s",
+        base::length(dropped),
+        base::paste(c(dropped[base::seq_len(base::min(10L, base::length(dropped)))], if (base::length(dropped) > 10) "..."), collapse = ", ")
+      ),
+      call. = FALSE
+    )
   }
 
-  if (identical(method, "gsea")) {
-    hype_args$absolute <- absolute
-    hype_args$power <- power
+  # A query with no genesets or no genes left cannot run; skip it rather than
+  # letting hypeR abort the whole batch.
+  runnable <- base::vapply(base::seq_along(queries), function(i) {
+    base::length(queries[[i]]) > 0 && countHypeRGenesets(query_genesets[[i]]$genesets) > 0
+  }, base::logical(1))
+  if (!base::all(runnable)) {
+    base::warning(
+      base::sprintf(
+        "Skipped %d query(ies) with nothing left to test after removing zero-weight genesets or unmeasured genes: %s",
+        base::sum(!runnable),
+        base::paste(base::sprintf("'%s'", query_names_out[!runnable]), collapse = ", ")
+      ),
+      call. = FALSE
+    )
   }
+  # BS831's hyperEnrichment() skips a draw with fewer than min.drawsize (4)
+  # genes found among the genesets: a p-value from one or two hits says little.
+  if (base::identical(test, "hypergeometric")) {
+    members <- if (methods::is(resolved_genesets, "gsets") || methods::is(resolved_genesets, "rgsets")) {
+      resolved_genesets$genesets
+    } else {
+      resolved_genesets
+    }
+    annotated <- base::unique(base::unlist(members, use.names = FALSE))
+    n_found <- base::vapply(queries, function(q) base::sum(q %in% annotated), base::integer(1))
+    too_small <- runnable & n_found < min_query_genes
+    if (base::any(too_small)) {
+      base::warning(
+        base::sprintf(
+          "Skipped %d query(ies) with fewer than min_query_genes = %s genes found in the genesets: %s",
+          base::sum(too_small), min_query_genes,
+          base::paste(base::sprintf("'%s' (%d)", query_names_out[too_small], n_found[too_small]), collapse = ", ")
+        ),
+        call. = FALSE
+      )
+      runnable <- runnable & !too_small
+    }
+  }
+  if (!base::any(runnable)) {
+    base::stop("\nNo query had genesets left to test; see the warnings for the dropped genesets and skipped queries.\n")
+  }
+  run_idx <- base::which(runnable)
+  is_kstest <- base::identical(test, "kstest")
 
-  if (base::length(extra_args) > 0) {
-    hype_args[base::names(extra_args)] <- extra_args
+  results <- base::lapply(run_idx, function(i) {
+    if (!quiet && base::length(run_idx) > 1) {
+      base::cat(base::sprintf("\n%s\n", query_names_out[i]))
+    }
+    # A character vector in rank order takes hypeR's ranked (unweighted)
+    # branch; a named numeric vector at power 0 would take the weighted branch
+    # with all weights 1, which scores differently.
+    query <- if (is_kstest && power == 0 && !base::is.character(queries[[i]])) base::names(queries[[i]]) else queries[[i]]
+    single <- if (is_kstest) duplicateSingleHypeRGeneset(query_genesets[[i]]$genesets) else NULL
+    hyp_obj <- hypeR::hypeR(
+      signature = query,
+      genesets = if (base::is.null(single)) query_genesets[[i]]$genesets else single$genesets,
+      test = test,
+      background = backgrounds$values[[i]],
+      power = power,
+      absolute = FALSE,
+      # With fdr_scope = "run" the FDR is recomputed across every query below,
+      # so hypeR must keep every row until then.
+      pval = if (fdr_scope == "run") 1 else pval,
+      fdr = if (fdr_scope == "run") 1 else fdr,
+      plotting = plotting,
+      quiet = quiet
+    )
+    if (!base::is.null(single)) {
+      restoreSingleHypeRGeneset(hyp_obj, single, query_genesets[[i]]$genesets, backgrounds$values[[i]])
+    }
+    if (!plotting) {
+      # hypeR stores one empty ggplot per geneset even with plotting = FALSE
+      # (about 1.4 MB each serialized); nothing downstream reads them.
+      hyp_obj$plots <- base::list()
+    }
+    appendHypeRProvenance(hyp_obj, prepared$info[i, , drop = FALSE], base::list(
+      ranked_table = if (is_kstest && !collected$native) ks_source else "",
+      score_col = if (is_kstest && !collected$native) score_col else "",
+      split = if (is_kstest || collected$native) "" else base::as.character(split),
+      background_source = backgrounds$sources[i],
+      query_genes_removed = removed[i],
+      genesets_dropped = query_genesets[[i]]$dropped,
+      fdr_scope = fdr_scope
+    ))
+  })
+  base::names(results) <- query_names_out[run_idx]
+
+  finishHypeRRun(results, fdr_scope, pval, fdr, test, split, inputs, collected$native)
+}
+
+#' Excel-safe, case-insensitively unique sheet names
+#'
+#' Excel sheet names are at most 31 characters, cannot contain
+#' \code{: \\ / ? * [ ]}, cannot start or end with an apostrophe, and are
+#' compared without regard to case.
+#' @noRd
+hypeRSheetNames <- function(x, reserved = base::character()) {
+  clean <- function(s) base::gsub("^'+|'+$", "", s)
+  x <- clean(base::trimws(base::gsub("[][*?/\\\\:]", "_", base::as.character(x))))
+  x[base::is.na(x) | !base::nzchar(x)] <- "sheet"
+
+  used <- base::tolower(reserved)
+  out <- base::character(base::length(x))
+  for (i in base::seq_along(x)) {
+    candidate <- clean(base::substr(x[i], 1L, 31L))
+    k <- 2L
+    while (!base::nzchar(candidate) || base::tolower(candidate) %in% used) {
+      suffix <- base::sprintf(" (%d)", k)
+      candidate <- base::paste0(clean(base::substr(x[i], 1L, 31L - base::nchar(suffix))), suffix)
+      k <- k + 1L
+    }
+    out[i] <- candidate
+    used <- c(used, base::tolower(candidate))
   }
+  out
+}
 
-  hyp_result <- do.call(hypeR::hypeR, hype_args)
+#' Write runHypeR() results to Excel with safe sheet names
+#'
+#' @description Writes a \code{hyp} or \code{multihyp} with
+#' \code{hypeR::hyp_to_excel()} after turning query names into valid Excel
+#' sheet names (at most 31 characters, none of \code{: \\ / ? * [ ]}, unique
+#' regardless of case). An \code{index} sheet, placed first, maps each sheet
+#' back to its full query name and SigRepo provenance. The object you pass is
+#' not modified.
+#'
+#' @section Required and optional arguments:
+#' \code{hyp_obj} and \code{file_path} are required. \code{cols},
+#' \code{versioning} and \code{index} are optional: by default every column is
+#' written, with hypeR's \code{versioning} sheet and the SigRepo \code{index}
+#' sheet. \code{cols = NULL} means "all columns", not "none".
+#'
+#' @param hyp_obj A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.
+#' @param file_path Path of the \code{.xlsx} file to write (overwritten).
+#' @param cols Passed to \code{hypeR::hyp_to_excel()}: columns of each result
+#' table to write. Defaults to all.
+#' @param versioning Passed to \code{hypeR::hyp_to_excel()}: add hypeR's
+#' \code{versioning} sheet with each query's \code{info}. Defaults to \code{TRUE}.
+#' @param index Logical; add the \code{index} sheet. Defaults to \code{TRUE}.
+#'
+#' @return Invisibly, the index as a data frame: \code{sheet}, \code{query},
+#' \code{signature_id}, \code{signature_name}, \code{group_label},
+#' \code{direction}.
+#'
+#' @examples
+#' \dontrun{
+#' hyp <- SigRepo::runHypeR(omic_signature = sig, organism = "Homo sapiens", test = "hypergeometric",
+#'                          genesets = "msigdb", msigdb_collection = "H")
+#' SigRepo::hypeRToExcel(hyp, file_path = "results.xlsx")
+#' }
+#'
+#' @export
+hypeRToExcel <- function(hyp_obj, file_path, cols = NULL, versioning = TRUE, index = TRUE) {
+  info_value <- function(h, key) {
+    value <- h$info[[key]]
+    if (base::is.null(value) || base::length(value) == 0 || base::is.na(value[1])) "" else base::as.character(value[1])
+  }
 
-  base::list(
-    result = hyp_result,
-    signatures = signature_vectors,
-    metadata = enrichment_inputs$metadata
+  if (methods::is(hyp_obj, "multihyp")) {
+    data <- hyp_obj$data
+  } else if (methods::is(hyp_obj, "hyp")) {
+    parts <- c(info_value(hyp_obj, "SigRepo Signature Name"), info_value(hyp_obj, "Group Label"), info_value(hyp_obj, "SigRepo Direction"))
+    parts <- parts[base::nzchar(parts)]
+    data <- stats::setNames(base::list(hyp_obj), if (base::length(parts) > 0) base::paste(parts, collapse = " | ") else "results")
+  } else {
+    base::stop("\n'hyp_obj' must be a hypeR hyp or multihyp object.\n")
+  }
+
+  reserved <- c(if (index) "index", if (versioning) "versioning")
+  sheets <- hypeRSheetNames(base::names(data), reserved = reserved)
+  hypeR::hyp_to_excel(
+    hypeR::multihyp$new(data = stats::setNames(data, sheets)),
+    file_path = file_path, cols = cols, versioning = versioning
+  )
+
+  index_df <- base::data.frame(
+    sheet = sheets,
+    query = base::names(data),
+    signature_id = base::vapply(data, info_value, base::character(1), key = "SigRepo Signature ID", USE.NAMES = FALSE),
+    signature_name = base::vapply(data, info_value, base::character(1), key = "SigRepo Signature Name", USE.NAMES = FALSE),
+    group_label = base::vapply(data, info_value, base::character(1), key = "Group Label", USE.NAMES = FALSE),
+    direction = base::vapply(data, info_value, base::character(1), key = "SigRepo Direction", USE.NAMES = FALSE),
+    stringsAsFactors = FALSE
   )
+
+  if (index) {
+    wb <- openxlsx::loadWorkbook(file_path)
+    openxlsx::addWorksheet(wb, sheetName = "index")
+    openxlsx::writeData(wb, sheet = "index", x = index_df, colNames = TRUE, rowNames = FALSE)
+    n_sheets <- base::length(base::names(wb))
+    openxlsx::worksheetOrder(wb) <- c(n_sheets, base::seq_len(n_sheets - 1L))
+    openxlsx::saveWorkbook(wb, file = file_path, overwrite = TRUE)
+  }
+
+  base::invisible(index_df)
 }
diff --git a/R/hypeRFgsea.R b/R/hypeRFgsea.R
new file mode 100644
index 00000000..1b79f22a
--- /dev/null
+++ b/R/hypeRFgsea.R
@@ -0,0 +1,215 @@
+# fgsea defaults of hypeR's vignette wrapper (hypeR vignettes/docs/fgsea.Rmd).
+HYPER_FGSEA_DEFAULT_ARGS <- base::list(sampleSize = 101, minSize = 1, maxSize = Inf)
+
+#' Evaluate `expr` after set.seed(seed), restoring the caller's RNG state
+#'
+#' `expr` is a promise, so it runs after set.seed(). seed = NULL evaluates it
+#' with the session RNG and leaves that RNG advanced.
+#' @noRd
+withHypeRSeed <- function(seed, expr) {
+  if (base::is.null(seed)) {
+    return(expr)
+  }
+  env <- base::globalenv()
+  had_seed <- base::exists(".Random.seed", envir = env, inherits = FALSE)
+  old_seed <- if (had_seed) base::get(".Random.seed", envir = env, inherits = FALSE) else NULL
+  base::on.exit({
+    if (had_seed) {
+      base::assign(".Random.seed", old_seed, envir = env)
+    } else if (base::exists(".Random.seed", envir = env, inherits = FALSE)) {
+      base::rm(".Random.seed", envir = env)
+    }
+  })
+  base::set.seed(seed)
+  expr
+}
+
+#' fgseaMultilevel() result as a hypeR-style data frame
+#'
+#' Columns follow hypeR's fgsea vignette wrapper, plus `hits` (the leading edge
+#' in hypeR's " , " format) so rctbl_build() works. Rows with an NA p-value are
+#' removed. A 0-row `raw` (e.g. every pathway dropped by `minSize`, or a
+#' background sharing no genes with the genesets) returns a 0-row table with
+#' the same 11 columns instead of erroring: `data.frame()` would otherwise try
+#' to recycle the scalar `signature` column against 0 rows.
+#' @noRd
+fgseaHypeRTable <- function(raw, stats, pathways) {
+  raw <- raw[!base::is.na(raw$pval), , drop = FALSE]
+  leading_edge <- raw$leadingEdge
+  n <- base::nrow(raw)
+  base::data.frame(
+    label = base::as.character(raw$pathway),
+    pval = base::signif(raw$pval, 2),
+    fdr = base::signif(raw$padj, 2),
+    lte = raw$log2err,
+    es = raw$ES,
+    nes = raw$NES,
+    signature = base::rep(base::length(stats), n),
+    geneset = base::as.integer(base::unname(base::lengths(pathways)[base::as.character(raw$pathway)])),
+    overlap = base::as.integer(raw$size),
+    le = base::vapply(leading_edge, function(x) base::paste(x, collapse = ","), base::character(1)),
+    hits = base::vapply(leading_edge, function(x) base::paste(x, collapse = " , "), base::character(1)),
+    stringsAsFactors = FALSE
+  )
+}
+
+#' One fgseaMultilevel() run on one ranking, split into up/down hyp objects
+#'
+#' @param stats Named numeric ranking (signed scores).
+#' @param genesets Named list, hypeR::gsets or hypeR::rgsets.
+#' @param background Number (no effect) or gene vector (genesets reduced to it).
+#' @param direction "up", "down" or "both".
+#' @return list(hyps = named list with "up" and/or "down" hyp, dropped = chr,
+#'   warnings = chr)
+#' @noRd
+runFgseaHyps <- function(stats, genesets, background, direction, power, seed, fgsea_args, quiet) {
+  gsets_obj <- if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) {
+    genesets
+  } else {
+    hypeR::gsets$new(genesets, quiet = TRUE)
+  }
+  if (base::is.character(background)) {
+    gsets_obj <- gsets_obj$reduce(background)
+  }
+  pathways <- gsets_obj$genesets
+  effective_args <- utils::modifyList(HYPER_FGSEA_DEFAULT_ARGS, fgsea_args)
+
+  warnings <- base::character()
+  run_fgsea <- function() {
+    base::do.call(fgsea::fgseaMultilevel, c(base::list(pathways = pathways, stats = stats, gseaParam = power), effective_args))
+  }
+  raw <- withHypeRSeed(seed, base::withCallingHandlers(
+    {
+      if (quiet) {
+        result <- NULL
+        utils::capture.output(result <- run_fgsea())
+        result
+      } else {
+        run_fgsea()
+      }
+    },
+    warning = function(w) {
+      warnings <<- c(warnings, base::conditionMessage(w))
+      base::invokeRestart("muffleWarning")
+    }
+  ))
+  raw <- base::as.data.frame(raw)
+
+  table <- fgseaHypeRTable(raw, stats, pathways)
+  dropped <- base::setdiff(base::names(pathways), table$label)
+
+  info <- base::list(
+    "hypeR" = base::paste0("v", utils::packageVersion("hypeR")),
+    "Signature Head" = base::paste(utils::head(base::names(stats)), collapse = ","),
+    "Signature Size" = base::length(stats),
+    "Signature Type" = "weighted",
+    "Genesets" = gsets_obj$info(),
+    "Background" = if (base::is.character(background)) base::length(background) else background,
+    "P-Value" = 1,
+    "FDR" = 1,
+    "Test" = "fgsea",
+    "Power" = power,
+    "Absolute" = FALSE,
+    "fgsea" = base::paste0("v", utils::packageVersion("fgsea")),
+    "Sample Size" = effective_args$sampleSize,
+    "Min Size" = effective_args$minSize,
+    "Max Size" = effective_args$maxSize,
+    "Seed" = if (base::is.null(seed)) "" else seed,
+    "fgsea Args" = if (base::length(fgsea_args) == 0) "" else base::paste(
+      base::sprintf("%s=%s", base::names(fgsea_args), base::vapply(fgsea_args, function(v) base::paste(base::format(v), collapse = ","), base::character(1))),
+      collapse = "; "
+    )
+  )
+  info <- base::lapply(info, base::as.character)
+  args <- base::list(
+    signature = stats, genesets = gsets_obj, test = "fgsea", background = background, power = power,
+    absolute = FALSE, pval = 1, fdr = 1, seed = seed, fgsea_args = effective_args
+  )
+
+  sides <- if (base::identical(direction, "both")) c("up", "down") else direction
+  hyps <- base::lapply(stats::setNames(sides, sides), function(side) {
+    rows <- if (side == "up") table$es > 0 else table$es < 0
+    side_data <- table[rows, , drop = FALSE]
+    side_data <- side_data[base::order(side_data$pval, side_data$es), , drop = FALSE]
+    base::rownames(side_data) <- NULL
+    hypeR::hyp$new(data = side_data, plots = base::list(), args = args, info = info)
+  })
+
+  base::list(hyps = hyps, dropped = dropped, warnings = base::unique(warnings))
+}
+
+#' Error or warn on arguments test = "fgsea" cannot use
+#' @noRd
+checkHypeRFgseaArgs <- function(seed, fgsea_args, plotting) {
+  if (!base::is.null(seed) && !(base::is.numeric(seed) && base::length(seed) == 1L && base::is.finite(seed))) {
+    base::stop("\n'seed' must be NULL or a single number.\n")
+  }
+  arg_names <- base::names(fgsea_args)
+  if (!base::is.list(fgsea_args) ||
+      (base::length(fgsea_args) > 0 && (base::is.null(arg_names) || base::any(base::is.na(arg_names) | !base::nzchar(arg_names))))) {
+    base::stop("\n'fgsea_args' must be a named list of fgsea::fgseaMultilevel() arguments.\n")
+  }
+  reserved <- base::intersect(arg_names, c("stats", "pathways", "gseaParam", "scoreType"))
+  if (base::length(reserved) > 0) {
+    base::stop(base::sprintf(
+      "\n'fgsea_args' cannot set %s; runHypeR() supplies them (gseaParam comes from 'power'; scoreType would change the ES-sign split runHypeR() relies on).\n",
+      base::paste(base::sprintf("'%s'", reserved), collapse = ", ")
+    ))
+  }
+  if (base::isTRUE(plotting)) {
+    base::warning("fgsea makes no per-geneset plots; plotting is ignored.", call. = FALSE)
+  }
+  base::invisible(NULL)
+}
+
+#' Run fgsea on every prepared ranking and build named, provenance-tagged hyps
+#'
+#' The multiple-testing family for `fdr_scope = "run"` is the up and down sides
+#' of every ranking in the call, pooled via `applyRunHypeRFdr()` (the same
+#' BH-over-2-significant-digit-pval pooling `finishHypeRRun()` uses).
+#'
+#' @return Named list of hyp objects, "<query> | up" and "<query> | down" per ranking.
+#' @noRd
+runFgseaQueries <- function(prepared, backgrounds, genesets, power, seed, fgsea_args, quiet,
+                            native, ks_source, score_col, fdr_scope,
+                            query_genes_removed = base::integer(base::length(prepared$signatures))) {
+  side_results <- base::list()
+  fgsea_warnings <- base::character()
+
+  for (i in base::seq_along(prepared$signatures)) {
+    query_name <- base::names(prepared$signatures)[i]
+    run <- runFgseaHyps(
+      stats = prepared$signatures[[i]], genesets = genesets, background = backgrounds$values[[i]],
+      direction = "both", power = power, seed = seed, fgsea_args = fgsea_args, quiet = quiet
+    )
+    fgsea_warnings <- c(fgsea_warnings, run$warnings)
+
+    for (side in base::names(run$hyps)) {
+      info_row <- prepared$info[i, , drop = FALSE]
+      info_row$direction <- side
+      hyp_name <- base::sprintf("%s | %s", query_name, side)
+      side_results[[hyp_name]] <- appendHypeRProvenance(run$hyps[[side]], info_row, base::list(
+        ranked_table = if (native) "" else ks_source,
+        score_col = if (native) "" else score_col,
+        split = "",
+        background_source = backgrounds$sources[i],
+        query_genes_removed = query_genes_removed[i],
+        genesets_dropped = run$dropped,
+        fdr_scope = fdr_scope
+      ))
+    }
+  }
+
+  for (message in base::unique(fgsea_warnings)) {
+    base::warning(base::paste0("fgsea: ", message), call. = FALSE)
+  }
+
+  if (base::identical(fdr_scope, "run")) {
+    # pval = fdr = 1 here: this only pools and stamps `data$fdr`; the caller's
+    # pval/fdr cutoffs are applied later by finishHypeRRun().
+    side_results <- applyRunHypeRFdr(side_results, pval = 1, fdr = 1)
+  }
+
+  base::names(side_results) <- disambiguateHypeRLabels(base::names(side_results))
+  side_results
+}
diff --git a/R/hypeRGenesets.R b/R/hypeRGenesets.R
new file mode 100644
index 00000000..2eb1f82f
--- /dev/null
+++ b/R/hypeRGenesets.R
@@ -0,0 +1,165 @@
+#' MSigDB database for a species/collection pair
+#'
+#' Mouse-native collections (MH, M1-M8) live in the mouse database. Every other
+#' request -- human, mouse against a human collection such as C2 or C5, or any
+#' other species -- uses the human database, which msigdbr maps to orthologs.
+#' hypeR::msigdb_download() gets both cases wrong: it always uses "MM" for mouse
+#' and has a `db_species == "HS"` typo for other species.
+#'
+#' @noRd
+msigdbDbSpecies <- function(species, collection) {
+  species <- base::tolower(base::trimws(base::as.character(species[[1]])))
+  collection <- base::toupper(base::trimws(base::as.character(collection[[1]])))
+
+  if (base::identical(species, "mus musculus") && base::grepl("^M(H|[0-9]+)$", collection)) {
+    return("MM")
+  }
+
+  "HS"
+}
+
+#' Thin wrapper so tests can replace the msigdbr call
+#' @noRd
+callMsigdbr <- function(args) {
+  base::do.call(msigdbr::msigdbr, args)
+}
+
+#' Fetch an MSigDB collection as a hypeR gsets object
+#' @noRd
+fetchMsigdbGsets <- function(species, collection, subcollection = NULL, clean = FALSE) {
+  args <- base::list(
+    species = species,
+    db_species = msigdbDbSpecies(species, collection),
+    collection = collection
+  )
+  if (!base::is.null(subcollection)) {
+    args$subcollection <- subcollection
+  }
+
+  response <- callMsigdbr(args)
+
+  if (base::nrow(response) == 0L) {
+    base::stop(base::sprintf(
+      "\nMSigDB returned no genesets for species = '%s', collection = '%s'%s. See msigdbr::msigdbr_collections() for valid combinations.\n",
+      species,
+      collection,
+      if (base::is.null(subcollection)) "" else base::sprintf(", subcollection = '%s'", subcollection)
+    ))
+  }
+
+  mdf <- base::unique(base::as.data.frame(response)[, c("gs_name", "gene_symbol")])
+  mdf <- mdf[!base::is.na(mdf$gene_symbol) & base::nzchar(mdf$gene_symbol), , drop = FALSE]
+  genesets <- base::split(mdf$gene_symbol, mdf$gs_name)
+
+  hypeR::gsets$new(
+    genesets,
+    name = if (base::is.null(subcollection)) collection else base::paste(collection, subcollection, sep = "."),
+    version = base::paste0("v", base::as.character(utils::packageVersion("msigdbr"))),
+    clean = clean,
+    quiet = TRUE
+  )
+}
+
+genesetsFormError <- function() {
+  "\n'genesets' must be \"msigdb\" (with msigdb_collection) or your own genesets: a named list, hypeR::gsets or hypeR::rgsets object.\n"
+}
+
+#' Resolve genesets for hypeR
+#'
+#' @description Returns genesets in a form \code{hypeR::hypeR()} accepts. Pass
+#' \code{genesets = "msigdb"} with \code{msigdb_collection} (and optionally
+#' \code{msigdb_species}, \code{msigdb_subcollection}) to fetch an MSigDB
+#' collection, or pass your own genesets object.
+#'
+#' @section Required and optional arguments:
+#' \code{genesets} is required, and \code{msigdb_collection} is required with
+#' \code{genesets = "msigdb"}. The other \code{msigdb_*} arguments are
+#' optional (species defaults to \code{"Homo sapiens"}, no subcollection, no
+#' label cleaning) and apply only to \code{"msigdb"}; passing them with your
+#' own genesets is an error.
+#'
+#' @param genesets Either the string \code{"msigdb"}, or your own genesets: a
+#' named list of character vectors, a \code{hypeR::gsets} object, or a
+#' \code{hypeR::rgsets} object.
+#' @param msigdb_species Species for MSigDB, e.g. \code{"Homo sapiens"} or
+#' \code{"Mus musculus"}. Defaults to \code{"Homo sapiens"}. Only valid with
+#' \code{genesets = "msigdb"}.
+#' @param msigdb_collection MSigDB collection, e.g. \code{"H"}, \code{"C2"},
+#' \code{"MH"}. Required with \code{genesets = "msigdb"}.
+#' @param msigdb_subcollection Optional MSigDB subcollection, e.g.
+#' \code{"CP:REACTOME"}. Only valid with \code{genesets = "msigdb"}.
+#' @param msigdb_clean Logical; clean geneset labels via
+#' \code{hypeR::gsets$new(clean = TRUE)}. Defaults to \code{FALSE}.
+#'
+#' @return For \code{"msigdb"}, a \code{hypeR::gsets} object named after the
+#' collection (e.g. \code{"C2.CP:REACTOME"}) and versioned by msigdbr. Otherwise
+#' the supplied genesets, unchanged.
+#'
+#' @details Mouse-native collections (\code{MH}, \code{M1}-\code{M8}) use the
+#' mouse MSigDB database; mouse requests for human collections and all other
+#' species use the human database with ortholog mapping.
+#'
+#' @examples
+#' \dontrun{
+#' hallmark <- SigRepo::getHypeRGenesets("msigdb", msigdb_collection = "H")
+#' reactome_mouse <- SigRepo::getHypeRGenesets(
+#'   "msigdb",
+#'   msigdb_species = "Mus musculus",
+#'   msigdb_collection = "C2",
+#'   msigdb_subcollection = "CP:REACTOME"
+#' )
+#' }
+#'
+#' @export
+getHypeRGenesets <- function(
+    genesets,
+    msigdb_species = NULL,
+    msigdb_collection = NULL,
+    msigdb_subcollection = NULL,
+    msigdb_clean = FALSE
+) {
+  if (base::missing(genesets) || base::is.null(genesets)) {
+    base::stop(genesetsFormError())
+  }
+
+  if (base::is.character(genesets)) {
+    if (!(base::length(genesets) == 1L && base::identical(genesets, "msigdb"))) {
+      base::stop(genesetsFormError())
+    }
+
+    if (base::is.null(msigdb_collection) || base::length(msigdb_collection) != 1L ||
+        base::is.na(msigdb_collection) || !base::nzchar(msigdb_collection)) {
+      base::stop("\ngenesets = \"msigdb\" requires 'msigdb_collection' (e.g. \"H\", \"C2\", \"MH\").\n")
+    }
+
+    return(fetchMsigdbGsets(
+      species = if (base::is.null(msigdb_species)) "Homo sapiens" else msigdb_species,
+      collection = msigdb_collection,
+      subcollection = msigdb_subcollection,
+      clean = msigdb_clean
+    ))
+  }
+
+  msigdb_supplied <- c(
+    msigdb_species = !base::is.null(msigdb_species),
+    msigdb_collection = !base::is.null(msigdb_collection),
+    msigdb_subcollection = !base::is.null(msigdb_subcollection)
+  )
+  if (base::any(msigdb_supplied)) {
+    base::stop(base::sprintf(
+      "\n%s only apply when genesets = \"msigdb\".\n",
+      base::paste(base::names(msigdb_supplied)[msigdb_supplied], collapse = ", ")
+    ))
+  }
+
+  if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) {
+    return(genesets)
+  }
+
+  if (methods::is(genesets, "list") && base::length(genesets) > 0 &&
+      !base::is.null(base::names(genesets)) && !base::any(base::names(genesets) %in% c("", NA))) {
+    return(genesets)
+  }
+
+  base::stop(genesetsFormError())
+}
diff --git a/R/hypeRPlotData.R b/R/hypeRPlotData.R
new file mode 100644
index 00000000..ccbe6d0a
--- /dev/null
+++ b/R/hypeRPlotData.R
@@ -0,0 +1,544 @@
+#' Hyps of a hypeR result as a named list, one element per query
+#'
+#' A multihyp keeps its names; a single hyp is named from its SigRepo
+#' provenance (see hypeRSingleQueryName()).
+#' @noRd
+hypeRResultHyps <- function(hyp_obj) {
+  if (methods::is(hyp_obj, "multihyp")) {
+    return(hyp_obj$data)
+  }
+  if (methods::is(hyp_obj, "hyp")) {
+    return(stats::setNames(base::list(hyp_obj), hypeRSingleQueryName(hyp_obj)))
+  }
+  base::stop("\n'hyp_obj' must be a hypeR hyp or multihyp object.\n")
+}
+
+#' One info value of a hyp as a string, or NA when absent or empty
+#' @noRd
+hypeRInfoValue <- function(hyp, key) {
+  value <- hyp$info[[key]]
+  if (base::is.null(value) || base::length(value) == 0 || base::is.na(value[1]) || !base::nzchar(value[1])) {
+    return(NA_character_)
+  }
+  base::as.character(value[1])
+}
+
+#' Query name for a single hyp: its signature name, group label and direction
+#' joined by " | ", or "query" when none is recorded
+#' @noRd
+hypeRSingleQueryName <- function(hyp) {
+  parts <- c(
+    hypeRInfoValue(hyp, "SigRepo Signature Name"),
+    hypeRInfoValue(hyp, "Group Label"),
+    hypeRInfoValue(hyp, "SigRepo Direction")
+  )
+  parts <- parts[!base::is.na(parts)]
+  if (base::length(parts) == 0) "query" else base::paste(parts, collapse = " | ")
+}
+
+#' One row per query: name and SigRepo provenance
+#' @noRd
+hypeRQueryInfo <- function(hyps) {
+  value <- function(key) base::vapply(hyps, hypeRInfoValue, base::character(1), key = key, USE.NAMES = FALSE)
+  base::data.frame(
+    query = base::names(hyps),
+    signature_id = value("SigRepo Signature ID"),
+    signature_name = value("SigRepo Signature Name"),
+    group_label = value("Group Label"),
+    direction = value("SigRepo Direction"),
+    test = value("Test"),
+    stringsAsFactors = FALSE
+  )
+}
+
+#' Signature of each query (its SigRepo name, or the query name when none is
+#' recorded) and its code, "S1", "S2", ... in order of first appearance
+#' @noRd
+hypeRQuerySignatures <- function(info) {
+  signature <- base::ifelse(base::is.na(info$signature_name), info$query, info$signature_name)
+  signatures <- base::unique(signature)
+  base::list(
+    code = base::paste0("S", base::match(signature, signatures)),
+    key = base::data.frame(
+      signature_code = base::paste0("S", base::seq_along(signatures)), signature_name = signatures,
+      stringsAsFactors = FALSE
+    )
+  )
+}
+
+#' What sets a query apart within its signature: group label and direction,
+#' e.g. "Old", "up" or "Subtype_A up"; "" when neither is recorded
+#' @noRd
+hypeRQueryGroups <- function(info) {
+  base::vapply(base::seq_len(base::nrow(info)), function(i) {
+    parts <- c(info$group_label[i], info$direction[i])
+    base::paste(parts[!base::is.na(parts)], collapse = " ")
+  }, base::character(1))
+}
+
+#' Display labels for queries: signature code and group ("S1 | Old"), the group
+#' alone for a single signature, the full names, or a user function of the info
+#' @noRd
+hypeRQueryLabels <- function(info, query_labels, signature_key = TRUE) {
+  if (base::is.null(query_labels)) {
+    labels <- info$query
+    if (base::isTRUE(signature_key)) {
+      signatures <- hypeRQuerySignatures(info)
+      groups <- hypeRQueryGroups(info)
+      labels <- if (base::nrow(signatures$key) > 1) {
+        base::ifelse(base::nzchar(groups), base::paste(signatures$code, groups, sep = " | "), signatures$code)
+      } else {
+        base::ifelse(base::nzchar(groups), groups, info$query)
+      }
+    }
+  } else {
+    if (!base::is.function(query_labels)) {
+      base::stop("\n'query_labels' must be NULL or a function that takes the query info data frame and returns one label per row.\n")
+    }
+    labels <- query_labels(info)
+    if (!base::is.character(labels) || base::length(labels) != base::nrow(info) ||
+        base::any(base::is.na(labels) | !base::nzchar(labels))) {
+      base::stop(base::sprintf(
+        "\n'query_labels' must return a character vector of %d non-empty label(s), one per query.\n",
+        base::nrow(info)
+      ))
+    }
+  }
+  disambiguateHypeRLabels(labels)
+}
+
+#' Truncate labels to `abrv` characters (adding "..."), keeping them unique
+#' @noRd
+hypeRAbbreviateLabels <- function(labels, abrv) {
+  short <- base::ifelse(base::nchar(labels) > abrv, base::paste0(base::substr(labels, 1L, abrv), "..."), labels)
+  disambiguateHypeRLabels(short)
+}
+
+#' Error unless x is a single number of at least `min`
+#' @noRd
+checkHypeRNumber <- function(x, name, min) {
+  if (!(base::is.numeric(x) && base::length(x) == 1L && !base::is.na(x) && x >= min)) {
+    base::stop(base::sprintf("\n'%s' must be a single number of at least %s.\n", name, min))
+  }
+  base::invisible(x)
+}
+
+#' 0-row hypeRDotData() frame, with the right columns and types
+#' @noRd
+emptyHypeRDotData <- function() {
+  base::data.frame(
+    query = base::character(), query_label = base::factor(), signature_code = base::character(),
+    query_group = base::character(), signature_name = base::character(),
+    group_label = base::character(), direction = base::character(), test = base::character(),
+    label = base::character(), label_abrv = base::factor(), pval = base::numeric(), fdr = base::numeric(),
+    significance = base::numeric(), score = base::numeric(), size = base::numeric(),
+    stringsAsFactors = FALSE
+  )
+}
+
+#' Dot-plot data for runHypeR() results
+#'
+#' @description Tidy data behind \code{plotHypeRDots()}: one row per query and
+#' geneset that passes the cutoffs, restricted to the \code{top} genesets
+#' shared by every query. Use it to draw your own figure or to serve the numbers
+#' to another front end.
+#'
+#' @section Required and optional arguments:
+#' Only \code{hyp_obj} is required. Every other argument is optional and has the
+#' default listed with it: genesets ranked by FDR, no p-value or FDR cutoff
+#' (\code{pval = 1}, \code{fdr = 1}), the 20 best genesets, sized by geneset
+#' size, queries labelled with signature codes. \code{query_labels = NULL} means
+#' "use the labels chosen by \code{signature_key}", not "no labels". Pass
+#' \code{fdr} (e.g. \code{0.05}) to keep only significant genesets.
+#'
+#' @param hyp_obj A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.
+#' @param val \code{"fdr"} (default) or \code{"pval"}: the value used to rank
+#' genesets and to compute \code{significance}.
+#' @param pval,fdr Keep rows with p-value / FDR at or below these. Default \code{1}.
+#' @param top Number of genesets to keep, chosen by their best (smallest)
+#' \code{val} across all queries, so every query shows the same genesets.
+#' Default \code{20}.
+#' @param size_by \code{"geneset"} (geneset size, default), \code{"overlap"} or
+#' \code{"none"}: what the \code{size} column holds.
+#' @param signature_key \code{TRUE} (default) labels queries by a short
+#' signature code and group, \code{"S1 | Old"}, with the codes listed by
+#' \code{hypeRSignatureKey()}; for a single signature the label is the group
+#' alone (\code{"Old"}). \code{FALSE} uses the full query names.
+#' @param query_labels \code{NULL} (default) for the labels chosen by
+#' \code{signature_key}, or a function that takes the query info data frame
+#' (\code{query}, \code{signature_id}, \code{signature_name},
+#' \code{group_label}, \code{direction}, \code{test}) and returns one non-empty
+#' label per row. Duplicates become \code{"label (2)"}.
+#' @param abrv Geneset labels longer than this many characters are truncated
+#' with \code{"..."}. Default \code{50}.
+#'
+#' @return A data frame with \code{query}, \code{query_label} (factor in query
+#' order), \code{signature_code} (\code{"S1"}, \code{"S2"}, ...; see
+#' \code{hypeRSignatureKey()}), \code{query_group} (the group label and
+#' direction that set the query apart within its signature, or \code{""}),
+#' \code{signature_name}, \code{group_label}, \code{direction},
+#' \code{test}, \code{label}, \code{label_abrv} (factor ordered so the most
+#' significant geneset is the last level, i.e. the top row of a plot),
+#' \code{pval}, \code{fdr}, \code{significance} (-log10 of \code{val}; values of
+#' 0 are floored to a tenth of the smallest positive value, or 1e-300),
+#' \code{score} (fgsea NES, kstest score, negated for a kstest \code{"| down"}
+#' query so it is on the original ranking; \code{NA} for hypergeometric) and
+#' \code{size}. It has 0 rows when nothing passes the cutoffs. Ties for the
+#' shared \code{top} genesets are broken by the best (smallest) \code{pval}
+#' across queries, then by label name.
+#'
+#' @examples
+#' \dontrun{
+#' dots <- SigRepo::hypeRDotData(hyp, fdr = 0.05, top = 15)
+#' }
+#'
+#' @export
+hypeRDotData <- function(
+    hyp_obj,
+    val = c("fdr", "pval"),
+    pval = 1,
+    fdr = 1,
+    top = 20,
+    size_by = c("geneset", "overlap", "none"),
+    signature_key = TRUE,
+    query_labels = NULL,
+    abrv = 50
+) {
+  val <- base::match.arg(val)
+  size_by <- base::match.arg(size_by)
+  checkHypeRNumber(top, "top", 1)
+  checkHypeRNumber(abrv, "abrv", 1)
+  checkHypeRNumber(pval, "pval", 0)
+  checkHypeRNumber(fdr, "fdr", 0)
+
+  hyps <- hypeRResultHyps(hyp_obj)
+  info <- hypeRQueryInfo(hyps)
+  query_label <- hypeRQueryLabels(info, query_labels, signature_key)
+  signature_code <- hypeRQuerySignatures(info)$code
+  query_group <- hypeRQueryGroups(info)
+
+  rows <- base::lapply(base::seq_along(hyps), function(i) {
+    data <- hyps[[i]]$data
+    keep <- data$pval <= pval & data$fdr <= fdr
+    data <- data[!base::is.na(keep) & keep, , drop = FALSE]
+    if (base::nrow(data) == 0) {
+      return(NULL)
+    }
+    if (size_by %in% c("geneset", "overlap") && !(size_by %in% base::colnames(data))) {
+      base::stop(base::sprintf("\nsize_by = \"%s\" needs a '%s' column in the results.\n", size_by, size_by))
+    }
+    score <- if ("nes" %in% base::colnames(data)) {
+      data$nes
+    } else if ("score" %in% base::colnames(data)) {
+      # A kstest down query ranks the negated scores; flip its score back so
+      # enrichment at the bottom of the original ranking is negative, as in fgsea.
+      if (base::identical(info$test[i], "kstest") && base::identical(info$direction[i], "down")) -data$score else data$score
+    } else {
+      NA_real_
+    }
+    base::data.frame(
+      query = info$query[i], query_label = query_label[i], signature_code = signature_code[i],
+      query_group = query_group[i], signature_name = info$signature_name[i],
+      group_label = info$group_label[i], direction = info$direction[i], test = info$test[i],
+      label = base::as.character(data$label), pval = data$pval, fdr = data$fdr, value = data[[val]],
+      score = base::as.numeric(score),
+      size = base::switch(size_by, geneset = base::as.numeric(data$geneset), overlap = base::as.numeric(data$overlap), none = NA_real_),
+      stringsAsFactors = FALSE
+    )
+  })
+  rows <- rows[!base::vapply(rows, base::is.null, base::logical(1))]
+  if (base::length(rows) == 0) {
+    return(emptyHypeRDotData())
+  }
+  dots <- base::do.call(base::rbind, rows)
+
+  best <- base::tapply(dots$value, dots$label, base::min)
+  best_p <- base::tapply(dots$pval, dots$label, base::min)
+  ranked_labels <- base::names(best)[base::order(best, best_p[base::names(best)], base::names(best))]
+  kept_labels <- ranked_labels[base::seq_len(base::min(top, base::length(ranked_labels)))]
+  dots <- dots[dots$label %in% kept_labels, , drop = FALSE]
+
+  value <- dots$value
+  positive <- value[value > 0]
+  value[value <= 0] <- if (base::length(positive) > 0) base::min(positive) / 10 else 1e-300
+  dots$significance <- -base::log10(value)
+
+  abbreviated <- stats::setNames(hypeRAbbreviateLabels(kept_labels, abrv), kept_labels)
+  dots$label_abrv <- base::factor(abbreviated[dots$label], levels = base::rev(base::unname(abbreviated)))
+  dots$query_label <- base::factor(dots$query_label, levels = query_label)
+
+  dots <- dots[base::order(base::match(dots$query, info$query), base::match(dots$label, kept_labels)), , drop = FALSE]
+  base::rownames(dots) <- NULL
+  dots[, base::colnames(emptyHypeRDotData())]
+}
+
+#' Signature codes used in dot-plot labels
+#'
+#' @description The key behind \code{hypeRDotData()}'s and
+#' \code{plotHypeRDots()}'s short query labels: one row per signature, coded
+#' \code{"S1"}, \code{"S2"}, ... in the order the signatures first appear in
+#' the result. A query without a recorded SigRepo signature name counts as its
+#' own signature, named by the query.
+#'
+#' @section Required and optional arguments:
+#' \code{hyp_obj} is the only argument, and it is required.
+#'
+#' @param hyp_obj A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.
+#'
+#' @return A data frame with \code{signature_code} and \code{signature_name}.
+#'
+#' @examples
+#' \dontrun{
+#' SigRepo::hypeRSignatureKey(hyp)
+#' }
+#'
+#' @export
+hypeRSignatureKey <- function(hyp_obj) {
+  hypeRQuerySignatures(hypeRQueryInfo(hypeRResultHyps(hyp_obj)))$key
+}
+
+#' Name of the ranking behind a query. fgsea's "<ranking> | up" and
+#' "<ranking> | down" hyps come from one run on one ranking, so for them this is
+#' the query name without the side; any other query is its own ranking
+#' (a kstest "down" query ranks the negated scores).
+#' @noRd
+hypeRRankingName <- function(name, hyp) {
+  direction <- hypeRInfoValue(hyp, "SigRepo Direction")
+  if (!base::identical(hypeRInfoValue(hyp, "Test"), "fgsea") || !direction %in% c("up", "down")) {
+    return(name)
+  }
+  suffix <- base::paste0(" | ", direction)
+  if (base::endsWith(name, suffix)) base::substr(name, 1L, base::nchar(name) - base::nchar(suffix)) else name
+}
+
+#' The hyp for one query of a result, with its name. With `geneset`, an fgsea
+#' ranking name (the query name without " | up"/" | down") also selects: the
+#' side whose table holds the geneset, else the up side.
+#' @noRd
+hypeRSelectHyp <- function(hyp_obj, query, geneset = NULL) {
+  hyps <- hypeRResultHyps(hyp_obj)
+  if (base::is.null(query)) {
+    if (base::length(hyps) == 1L) {
+      return(base::list(name = base::names(hyps), hyp = hyps[[1]]))
+    }
+    base::stop(base::sprintf(
+      "\n'query' is required for a result with %d queries: %s.\n",
+      base::length(hyps), base::paste(base::sprintf("'%s'", base::names(hyps)), collapse = ", ")
+    ))
+  }
+  if (!base::is.null(geneset) && base::is.character(query) && base::length(query) == 1L && !query %in% base::names(hyps)) {
+    sides <- base::paste(query, c("up", "down"), sep = " | ")
+    sides <- sides[sides %in% base::names(hyps)]
+    sides <- sides[base::vapply(sides, function(side) base::identical(hypeRRankingName(side, hyps[[side]]), query), base::logical(1))]
+    if (base::length(sides) > 0) {
+      holding <- sides[base::vapply(sides, function(side) geneset %in% hyps[[side]]$data$label, base::logical(1))]
+      query <- if (base::length(holding) > 0) holding[1] else sides[1]
+    }
+  }
+  if (!(base::is.character(query) && base::length(query) == 1L && query %in% base::names(hyps))) {
+    base::stop(base::sprintf(
+      "\n'query' must be one of: %s.\n",
+      base::paste(base::sprintf("'%s'", base::names(hyps)), collapse = ", ")
+    ))
+  }
+  base::list(name = query, hyp = hyps[[query]])
+}
+
+#' Members of one geneset as the test used it (after background reduction)
+#' @noRd
+hypeRGenesetMembers <- function(hyp, geneset) {
+  genesets <- hyp$args$genesets
+  members <- if (methods::is(genesets, "gsets") || methods::is(genesets, "rgsets")) genesets$genesets else genesets
+  if (!(base::is.character(geneset) && base::length(geneset) == 1L && geneset %in% base::names(members))) {
+    base::stop(base::sprintf("\nGeneset '%s' is not in this result's genesets.\n", base::paste(geneset, collapse = ", ")))
+  }
+  members[[geneset]]
+}
+
+#' hypeR's weighted kstest running sum (.kstest with weights), same arithmetic
+#' @noRd
+hypeRWeightedCurve <- function(stats, members, power) {
+  n <- base::length(stats)
+  hit <- base::names(stats) %in% members
+  n_hits <- base::sum(hit)
+  weights <- base::abs(stats)^power
+  weights[!hit] <- 0
+  if (n_hits == n || base::sum(weights) == 0) {
+    base::stop("\nThis geneset cannot be scored by hypeR's kstest (it covers every ranked gene, or all its hits score 0).\n")
+  }
+  p_hit <- base::cumsum(weights)
+  p_hit <- p_hit / p_hit[n]
+  p_mis <- base::cumsum(!hit)
+  p_mis <- p_mis / (n - n_hits)
+  running <- base::unname(p_hit - p_mis)
+  es_position <- base::which.max(base::abs(running))
+  base::list(positions = base::seq_len(n), running = running, es = running[es_position], es_position = es_position)
+}
+
+#' hypeR's unweighted (ranked) kstest statistic, same arithmetic as .kstest
+#' @noRd
+hypeRRankedCurve <- function(ranked_genes, members) {
+  n <- base::length(ranked_genes)
+  y <- base::match(members, ranked_genes)
+  y <- base::sort(y[!base::is.na(y)])
+  n_hits <- base::length(y)
+  if (n_hits == n) {
+    base::stop("\nThis geneset cannot be scored by hypeR's kstest (it covers every ranked gene).\n")
+  }
+  hit_step <- 1 / n_hits
+  miss_step <- 1 / n
+  # hypeR evaluates the statistic at each hit and the position just before it.
+  Y <- base::sort(c(y - 1, y))
+  Y <- Y[base::diff(Y) != 0]
+  D <- base::rep(0, base::length(Y))
+  D[base::match(y, Y)] <- base::seq_len(n_hits)
+  zero <- base::which(D == 0)[-1]
+  D[zero] <- D[zero - 1]
+  z <- D * hit_step - Y * miss_step
+  es_index <- base::which.max(base::abs(z))
+
+  positions <- base::seq_len(n)
+  hits_so_far <- base::cumsum(positions %in% y)
+  base::list(positions = positions, running = hits_so_far * hit_step - positions * miss_step,
+             es = z[es_index], es_position = Y[es_index])
+}
+
+#' fgsea's running sum and ES (calcGseaStat tie rule: an exact tie gives 0)
+#' @noRd
+hypeRFgseaCurve <- function(stats, members, power) {
+  plot_data <- fgsea::plotEnrichmentData(pathway = members, stats = stats, gseaParam = power)
+  curve <- base::as.data.frame(plot_data$curve)
+  es <- if (plot_data$posES > -plot_data$negES) {
+    plot_data$posES
+  } else if (plot_data$posES < -plot_data$negES) {
+    plot_data$negES
+  } else {
+    0
+  }
+  es_position <- if (es == 0) NA_integer_ else base::as.integer(curve$rank[base::which(curve$ES == es)[1]])
+  base::list(positions = curve$rank, running = curve$ES, es = es, es_position = es_position)
+}
+
+#' Running enrichment score data for one geneset of a kstest or fgsea result
+#'
+#' @description Recomputes the running-sum curve behind one geneset's
+#' enrichment score from the result itself (the ranking and genesets stored in
+#' \code{hyp$args}), so no per-geneset plots need to be kept.
+#'
+#' @section Required and optional arguments:
+#' \code{hyp_obj} (a kstest or fgsea result) and \code{geneset} are required.
+#' \code{query} is required only when \code{hyp_obj} holds more than one query;
+#' for a single \code{hyp}, or a \code{multihyp} with one query, it can be left
+#' out. For hypergeometric results use \code{plotHypeREnrichment()} instead.
+#'
+#' @param hyp_obj A \code{hyp} or \code{multihyp} from \code{runHypeR()} with
+#' \code{test = "kstest"} or \code{"fgsea"}.
+#' @param geneset Geneset label, e.g. \code{"HALLMARK_MYC_TARGETS_V1"}.
+#' @param query Query name (\code{names(hyp_obj$data)}); required for a
+#' \code{multihyp} with more than one query. For fgsea, whose
+#' \code{"<ranking> | up"} and \code{"<ranking> | down"} queries come from one
+#' run on one ranking, the ranking name alone also works: the side whose table
+#' holds \code{geneset} is used.
+#'
+#' @details The curve reproduces each test's own arithmetic, so \code{es}
+#' matches the result's \code{score} (kstest) or \code{es} (fgsea) to their 2
+#' significant digits, ties included:
+#' \itemize{
+#'   \item kstest with weights: hypeR's weighted running sum; the first
+#'   extremum is the enrichment score.
+#'   \item kstest with \code{power = 0}: hypeR's unweighted statistic.
+#'   \item fgsea: \code{fgsea::plotEnrichmentData()}; an exact tie between the
+#'   positive and negative extremum gives 0, as fgsea does.
+#' }
+#' The ranking is the one tested: for a kstest \code{"| down"} query it is the
+#' negated score. The leading edge follows the GSEA convention (hits
+#' up to the extremum for a positive score, from it for a negative score); for
+#' kstest with a negative score this can differ from hypeR's \code{hits}
+#' column, which always counts from the top.
+#'
+#' \code{absolute = TRUE} kstest results are not supported: hypeR scores them
+#' as \code{max(z) - min(z)}, which has no running-sum curve, so this errors
+#' for them.
+#'
+#' @return A list with \code{curve} (data frame: \code{position},
+#' \code{running_score}; for fgsea, \code{curve} holds fgsea's own step
+#' points, positions \code{0} to \code{N+1}, not one row per ranked gene
+#' \code{1..N}), \code{ticks} (data frame: \code{position},
+#' \code{gene}, \code{score}, \code{leading_edge}) and \code{summary} (list:
+#' \code{query}, \code{ranking} (the ranking the curve walks: for fgsea the
+#' query name without \code{" | up"}/\code{" | down"}, otherwise the query),
+#' \code{geneset}, \code{test}, \code{direction}, \code{n_ranked},
+#' \code{n_hits}, \code{es}, \code{es_position}, \code{leading_edge_genes},
+#' \code{pval}, \code{fdr}, \code{nes}, \code{score}; the last four are
+#' \code{NA} when the geneset is not in the result table).
+#'
+#' @examples
+#' \dontrun{
+#' curve <- SigRepo::hypeREnrichmentData(gsea, "HALLMARK_MYC_TARGETS_V1", query = "LLFS_Aging_Gene_2023")
+#' }
+#'
+#' @export
+hypeREnrichmentData <- function(hyp_obj, geneset, query = NULL) {
+  selected <- hypeRSelectHyp(hyp_obj, query, geneset)
+  hyp <- selected$hyp
+  test <- hypeRInfoValue(hyp, "Test")
+  if (!test %in% c("kstest", "fgsea")) {
+    base::stop("\nhypeREnrichmentData() needs kstest or fgsea results; use plotHypeREnrichment() for hypergeometric overlap.\n")
+  }
+  if (base::identical(test, "kstest") && base::isTRUE(hyp$args$absolute)) {
+    base::stop("\nabsolute = TRUE kstest results have no running-sum curve; hypeR scores them as max - min.\n")
+  }
+
+  members <- hypeRGenesetMembers(hyp, geneset)
+  stats <- hyp$args$signature
+  if (base::identical(test, "fgsea")) {
+    # fgsea::plotEnrichmentData() reorders the stats this way before it
+    # computes ticks and the leading edge; match its coordinates.
+    stats <- stats[base::order(base::rank(-stats))]
+  }
+  ranked_genes <- if (base::is.character(stats)) stats else base::names(stats)
+  if (!base::any(ranked_genes %in% members)) {
+    base::stop(base::sprintf("\n'%s' has no genes in this ranking.\n", geneset))
+  }
+  power <- if (base::is.null(hyp$args$power)) 1 else hyp$args$power
+
+  curve <- if (base::identical(test, "fgsea")) {
+    hypeRFgseaCurve(stats, members, power)
+  } else if (base::is.character(stats)) {
+    hypeRRankedCurve(stats, members)
+  } else {
+    hypeRWeightedCurve(stats, members, power)
+  }
+
+  hit_positions <- base::which(ranked_genes %in% members)
+  leading_edge <- if (curve$es > 0) {
+    hit_positions <= curve$es_position
+  } else if (curve$es < 0) {
+    hit_positions >= curve$es_position
+  } else {
+    base::rep(FALSE, base::length(hit_positions))
+  }
+  ticks <- base::data.frame(
+    position = hit_positions,
+    gene = ranked_genes[hit_positions],
+    score = if (base::is.character(stats)) NA_real_ else base::unname(stats[hit_positions]),
+    leading_edge = leading_edge,
+    stringsAsFactors = FALSE
+  )
+
+  row <- hyp$data[hyp$data$label == geneset, , drop = FALSE]
+  from_row <- function(column) if (base::nrow(row) > 0 && column %in% base::colnames(row)) row[[column]][1] else NA_real_
+
+  base::list(
+    curve = base::data.frame(position = curve$positions, running_score = curve$running),
+    ticks = ticks,
+    summary = base::list(
+      query = selected$name, ranking = hypeRRankingName(selected$name, hyp), geneset = geneset, test = test,
+      direction = hypeRInfoValue(hyp, "SigRepo Direction"),
+      n_ranked = base::length(ranked_genes), n_hits = base::length(hit_positions),
+      es = curve$es, es_position = curve$es_position,
+      leading_edge_genes = ticks$gene[ticks$leading_edge],
+      pval = from_row("pval"), fdr = from_row("fdr"), nes = from_row("nes"), score = from_row("score")
+    )
+  )
+}
diff --git a/R/hypeRPlots.R b/R/hypeRPlots.R
new file mode 100644
index 00000000..c6413d65
--- /dev/null
+++ b/R/hypeRPlots.R
@@ -0,0 +1,434 @@
+#' @importFrom rlang .data
+NULL
+
+#' Default plot title: the test(s) behind the hyps, e.g. "KS test"
+#' @noRd
+hypeRTestTitle <- function(hyps) {
+  tests <- base::vapply(hyps, hypeRInfoValue, base::character(1), key = "Test", USE.NAMES = FALSE)
+  tests <- base::unique(tests[!base::is.na(tests)])
+  if (base::length(tests) == 0) {
+    return("Enrichment")
+  }
+  known <- c(hypergeometric = "Hypergeometric test", kstest = "KS test", fgsea = "GSEA (fgsea)")
+  base::paste(base::ifelse(tests %in% base::names(known), known[tests], tests), collapse = ", ")
+}
+
+#' Dot plot of runHypeR() results across queries
+#'
+#' @description One column per query and one row per geneset, for a
+#' \code{hyp} or a \code{multihyp} of any length. Every query shows the same
+#' \code{top} genesets (the best by \code{val} across all queries); a blank cell
+#' means the geneset did not pass the cutoffs for that query. Significance is
+#' drawn as -log10 values on a plain scale, so axes and legends stay readable
+#' whatever the ggplot2 version. See \code{hypeRDotData()} for the data.
+#'
+#' @section Required and optional arguments:
+#' Only \code{hyp_obj} is required, so \code{plotHypeRDots(hyp)} works on any
+#' \code{runHypeR()} result. Every other argument is optional and has the
+#' default listed with it: the 20 best genesets by FDR with no cutoff, coloured
+#' by significance and sized by geneset size, with the title naming the test.
+#' \code{title = NULL} and \code{query_labels = NULL} mean "choose for me", not
+#' "none". \code{color_by = "score"} needs kstest or fgsea results.
+#'
+#' @inheritParams hypeRDotData
+#' @param color_by \code{"significance"} (default: -log10 of \code{val}) or
+#' \code{"score"} (NES for fgsea, the enrichment score for kstest) on a
+#' diverging scale centred at 0. \code{"score"} is an error for hypergeometric
+#' results.
+#' @param title Plot title; defaults to the test that was run
+#' (\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}).
+#'
+#' @details With \code{signature_key = TRUE} (the default) and several
+#' signatures, each signature's columns sit together under its code
+#' (\code{S1}, \code{S2}, ...), labelled by group or direction at 45 degrees,
+#' and the caption lists what each code stands for. A single signature is named
+#' in the subtitle, with its group labels horizontal while they fit. With
+#' \code{signature_key = FALSE} or \code{query_labels}, the labels are drawn
+#' at 45 degrees and the left margin grows when they reach past the geneset
+#' labels. Save with
+#' \code{ggplot2::ggsave()}. A readable size is roughly
+#' width = 5 + 0.085 x (longest geneset label, in characters) + 1.2 x (queries)
+#' inches, clamped to 7-20, and height = 1.6 + 0.30 x (genesets) + 0.05 x
+#' (longest query name, in characters) inches, clamped to 3.2-22.
+#'
+#' @return A \code{ggplot}. When nothing passes the cutoffs, a blank plot that
+#' says so.
+#'
+#' @examples
+#' \dontrun{
+#' SigRepo::plotHypeRDots(hyp, fdr = 0.05)
+#' SigRepo::plotHypeRDots(gsea, color_by = "score")
+#' }
+#'
+#' @export
+plotHypeRDots <- function(
+    hyp_obj,
+    val = c("fdr", "pval"),
+    pval = 1,
+    fdr = 1,
+    top = 20,
+    color_by = c("significance", "score"),
+    size_by = c("geneset", "overlap", "none"),
+    signature_key = TRUE,
+    query_labels = NULL,
+    abrv = 50,
+    title = NULL
+) {
+  val <- base::match.arg(val)
+  color_by <- base::match.arg(color_by)
+  size_by <- base::match.arg(size_by)
+
+  hyps <- hypeRResultHyps(hyp_obj)
+  tests <- base::vapply(hyps, hypeRInfoValue, base::character(1), key = "Test", USE.NAMES = FALSE)
+  if (base::identical(color_by, "score") && !base::all(tests %in% c("kstest", "fgsea"))) {
+    base::stop("\ncolor_by = \"score\" needs kstest or fgsea results.\n")
+  }
+  if (base::is.null(title)) {
+    title <- hypeRTestTitle(hyps)
+  }
+
+  dots <- hypeRDotData(hyp_obj, val = val, pval = pval, fdr = fdr, top = top, size_by = size_by,
+                       signature_key = signature_key, query_labels = query_labels, abrv = abrv)
+  if (base::nrow(dots) == 0) {
+    return(
+      ggplot2::ggplot() +
+        ggplot2::annotate("text", x = 0, y = 0, label = "No genesets pass the cutoffs") +
+        ggplot2::theme_void() +
+        ggplot2::labs(title = title)
+    )
+  }
+
+  point_aes <- if (base::identical(size_by, "none")) {
+    ggplot2::aes(colour = .data[[if (base::identical(color_by, "score")) "score" else "significance"]])
+  } else {
+    ggplot2::aes(colour = .data[[if (base::identical(color_by, "score")) "score" else "significance"]], size = .data$size)
+  }
+
+  # With the signature key, each signature is a facet named by its code (listed
+  # in the caption) and its queries are labelled by group; a single signature
+  # is named in the subtitle instead. Otherwise the query labels are drawn as they are.
+  info <- hypeRQueryInfo(hyps)
+  use_key <- base::isTRUE(signature_key) && base::is.null(query_labels)
+  signatures <- hypeRQuerySignatures(info)
+  groups <- hypeRQueryGroups(info)
+  query_levels <- base::levels(dots$query_label)
+  facet <- use_key && base::nrow(signatures$key) > 1 && base::any(base::nzchar(groups))
+  single_signature <- use_key && base::nrow(signatures$key) == 1
+  axis_text <- if (facet || single_signature) {
+    # The code (facet strip) or the subtitle already names the signature.
+    stats::setNames(groups, query_levels)
+  } else if (use_key) {
+    stats::setNames(base::ifelse(base::nzchar(groups), groups, query_levels), query_levels)
+  } else {
+    stats::setNames(query_levels, query_levels)
+  }
+
+  dots$signature_code <- base::factor(dots$signature_code, levels = signatures$key$signature_code)
+  plot <- ggplot2::ggplot(dots, ggplot2::aes(x = .data$query_label, y = .data$label_abrv)) +
+    (if (base::identical(size_by, "none")) ggplot2::geom_point(point_aes, size = 3) else ggplot2::geom_point(point_aes)) +
+    ggplot2::labs(x = NULL, y = NULL, title = title) +
+    ggplot2::theme_minimal()
+
+  if (facet) {
+    # Free x scales drop unused levels, so a blank layer keeps every query's column.
+    all_queries <- base::data.frame(
+      query_label = base::factor(query_levels, levels = query_levels),
+      label_abrv = base::factor(base::levels(dots$label_abrv)[1], levels = base::levels(dots$label_abrv)),
+      signature_code = base::factor(signatures$code, levels = signatures$key$signature_code)
+    )
+    plot <- plot +
+      ggplot2::geom_blank(data = all_queries) +
+      ggplot2::facet_grid(cols = ggplot2::vars(.data$signature_code), scales = "free_x", space = "free_x", switch = "x") +
+      ggplot2::scale_x_discrete(labels = function(x) base::unname(axis_text[x]))
+  } else {
+    plot <- plot + ggplot2::scale_x_discrete(drop = FALSE, labels = function(x) base::unname(axis_text[x]))
+  }
+  if (use_key && base::nrow(signatures$key) > 1) {
+    plot <- plot + ggplot2::labs(caption = base::paste(
+      base::sprintf("%s = %s", signatures$key$signature_code, signatures$key$signature_name), collapse = "\n"
+    ))
+  } else if (use_key) {
+    plot <- plot + ggplot2::labs(subtitle = signatures$key$signature_name)
+  }
+
+  plot <- if (base::identical(color_by, "score")) {
+    plot + ggplot2::scale_colour_gradient2(
+      low = "#2166AC", mid = "#D9D9D9", high = "#B2182B", midpoint = 0,
+      name = if (base::all(tests == "fgsea")) "NES" else "Score"
+    )
+  } else {
+    plot + ggplot2::scale_colour_gradient(
+      low = "#114357", high = "#E53935",
+      name = if (base::identical(val, "fdr")) "-log10(FDR)" else "-log10(p)"
+    )
+  }
+  if (!base::identical(size_by, "none")) {
+    plot <- plot + ggplot2::scale_size_continuous(name = if (base::identical(size_by, "geneset")) "Geneset size" else "Overlap")
+  }
+
+  # A single signature's group labels stay horizontal while they fit (about 40
+  # characters across all columns, e.g. Old/Young or up/down); any other labels
+  # are angled at 45 degrees, and the left margin grows by however far the
+  # longest one reaches past the geneset labels (estimated at 0.6 em per
+  # character) so it is not cut off. Legends hang from the top of the panel so a
+  # tall stack is not clipped.
+  horizontal <- single_signature &&
+    base::length(axis_text) * (base::max(base::nchar(axis_text)) + 2) <= 40
+  char_pt <- 0.6 * 8.8
+  overhang <- if (horizontal) {
+    0
+  } else {
+    base::max(base::nchar(axis_text)) * char_pt * base::sqrt(0.5) - base::max(base::nchar(base::levels(dots$label_abrv))) * char_pt
+  }
+  plot + ggplot2::theme(
+    axis.text.x = if (horizontal) ggplot2::element_text() else ggplot2::element_text(angle = 45, hjust = 1),
+    legend.justification = "top",
+    plot.margin = ggplot2::margin(5.5, 5.5, 5.5, 5.5 + base::max(0, overhang)),
+    plot.caption = ggplot2::element_text(hjust = 0, lineheight = 1.1),
+    plot.caption.position = "plot",
+    strip.placement = "outside",
+    strip.text = ggplot2::element_text(face = "bold"),
+    panel.spacing.x = grid::unit(6, "pt")
+  )
+}
+
+#' Format a number for a plot subtitle
+#' @noRd
+formatHypeRNumber <- function(x) base::format(base::signif(x, 2))
+
+#' Enrichment figure for one geneset of a runHypeR() result
+#'
+#' @description For kstest and fgsea results, the running enrichment score
+#' along the ranking with the geneset's hits marked below it (leading edge
+#' highlighted). For hypergeometric results, hypeR's Venn diagram of the query
+#' and the geneset. Both are drawn from the result itself, so they work for any
+#' geneset without \code{runHypeR(plotting = TRUE)} storing every plot.
+#'
+#' @section Required and optional arguments:
+#' \code{hyp_obj} and \code{geneset} (a geneset label from the result) are
+#' required. \code{query} is required only when \code{hyp_obj} holds more than
+#' one query; for a single \code{hyp}, or a \code{multihyp} with one query, it
+#' can be left out. For fgsea the ranking name without \code{" | up"} or
+#' \code{" | down"} is enough. \code{title} is optional and defaults to the test
+#' that was run.
+#'
+#' @inheritParams hypeREnrichmentData
+#' @param title Plot title; defaults to the test that was run
+#' (\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}).
+#' The geneset label is the first line of the subtitle.
+#'
+#' @return A \code{ggplot}.
+#'
+#' @examples
+#' \dontrun{
+#' SigRepo::plotHypeREnrichment(gsea, "HALLMARK_MYC_TARGETS_V1", query = "LLFS_Aging_Gene_2023")
+#' }
+#'
+#' @export
+plotHypeREnrichment <- function(hyp_obj, geneset, query = NULL, title = NULL) {
+  selected <- hypeRSelectHyp(hyp_obj, query, geneset)
+  hyp <- selected$hyp
+  plot_title <- if (base::is.null(title)) hypeRTestTitle(base::list(hyp)) else title
+
+  if (base::identical(hypeRInfoValue(hyp, "Test"), "hypergeometric")) {
+    members <- hypeRGenesetMembers(hyp, geneset)
+    row <- hyp$data[hyp$data$label == geneset, , drop = FALSE]
+    subtitle <- if (base::nrow(row) > 0) {
+      base::sprintf("%s\n%s\noverlap = %s, p = %s, FDR = %s", geneset, selected$name, row$overlap[1],
+                    formatHypeRNumber(row$pval[1]), formatHypeRNumber(row$fdr[1]))
+    } else {
+      base::sprintf("%s\n%s\nnot in the result table", geneset, selected$name)
+    }
+    return(hypeR::ggvenn(hyp$args$signature, members, "Query", "Geneset", plot_title) +
+             ggplot2::labs(subtitle = subtitle))
+  }
+
+  enrichment <- hypeREnrichmentData(hyp_obj, geneset, query = selected$name)
+  summary <- enrichment$summary
+  # fgsea's up and down queries share one ranking, so the subtitle names the
+  # ranking; the sign of ES and NES gives the direction.
+  subtitle <- base::paste0(geneset, "\n", summary$ranking, "\nES = ", formatHypeRNumber(summary$es))
+  if (base::is.na(summary$pval)) {
+    subtitle <- base::paste0(subtitle, ", not in the result table")
+  } else {
+    if (base::identical(summary$test, "fgsea")) {
+      subtitle <- base::paste0(subtitle, ", NES = ", formatHypeRNumber(summary$nes))
+    }
+    subtitle <- base::paste0(subtitle, ", p = ", formatHypeRNumber(summary$pval), ", FDR = ", formatHypeRNumber(summary$fdr))
+  }
+  negated <- base::identical(summary$test, "kstest") && base::identical(summary$direction, "down")
+
+  curve <- enrichment$curve
+  ticks <- enrichment$ticks
+  score_range <- base::range(c(curve$running_score, 0))
+  tick_height <- base::diff(score_range) * 0.08
+  ticks$y_start <- score_range[1] - tick_height * 0.5
+  ticks$y_end <- score_range[1] - tick_height * 1.5
+  ticks$hit_group <- base::factor(base::ifelse(ticks$leading_edge, "Leading edge", "Other hits"),
+                                  levels = c("Leading edge", "Other hits"))
+
+  plot <- ggplot2::ggplot(curve, ggplot2::aes(x = .data$position, y = .data$running_score)) +
+    ggplot2::geom_hline(yintercept = 0, colour = "grey60") +
+    ggplot2::geom_line(colour = "#1F4E79") +
+    ggplot2::geom_segment(
+      data = ticks,
+      ggplot2::aes(x = .data$position, xend = .data$position, y = .data$y_start, yend = .data$y_end, colour = .data$hit_group),
+      inherit.aes = FALSE
+    ) +
+    ggplot2::scale_colour_manual(values = c("Leading edge" = "#D04A02", "Other hits" = "#6C8AA5"), name = NULL, drop = FALSE) +
+    ggplot2::coord_cartesian(clip = "off") +
+    ggplot2::labs(
+      title = plot_title, subtitle = subtitle,
+      x = if (negated) "Rank in ranking (negated scores)" else "Rank in ranking",
+      y = "Running enrichment score"
+    ) +
+    ggplot2::theme_minimal() +
+    ggplot2::theme(legend.position = "top")
+  if (!base::is.na(summary$es_position)) {
+    plot <- plot + ggplot2::geom_vline(xintercept = summary$es_position, linetype = "dashed", colour = "grey40")
+  }
+  plot
+}
+
+#' Whether any pair of genesets reaches the similarity cutoff, as hypeR computes it
+#' @noRd
+hypeRAnyMapEdge <- function(members, similarity_metric, similarity_cutoff) {
+  if (base::length(members) < 2) {
+    return(FALSE)
+  }
+  for (i in base::seq_len(base::length(members) - 1L)) {
+    for (j in (i + 1L):base::length(members)) {
+      shared <- base::length(base::intersect(members[[i]], members[[j]]))
+      similarity <- if (base::identical(similarity_metric, "jaccard_similarity")) {
+        shared / base::length(base::union(members[[i]], members[[j]]))
+      } else {
+        shared / base::min(base::length(members[[i]]), base::length(members[[j]]))
+      }
+      if (similarity > 0 && similarity >= similarity_cutoff) {
+        return(TRUE)
+      }
+    }
+  }
+  FALSE
+}
+
+#' Title a visNetwork map: the test (or `title`) above the query name
+#' @noRd
+titleHypeRMap <- function(map, name, hyp, title) {
+  map$x$main <- base::list(
+    text = if (base::is.null(title)) hypeRTestTitle(base::list(hyp)) else title,
+    style = "font-family:Helvetica, Arial, sans-serif;font-weight:bold;font-size:18px;text-align:center;"
+  )
+  map$x$submain <- base::list(
+    text = name,
+    style = "font-family:Helvetica, Arial, sans-serif;font-size:13px;text-align:center;"
+  )
+  map
+}
+
+#' One query's map, or NULL with a warning when hypeR could not draw it
+#' @noRd
+plotHypeRMapOne <- function(name, hyp, type, val, pval, fdr, top, similarity_metric, similarity_cutoff, title = NULL) {
+  if (base::identical(type, "hmap") && !methods::is(hyp$args$genesets, "rgsets")) {
+    base::stop("\ntype = \"hmap\" needs rgsets genesets (e.g. hypeR::hyperdb_rgsets()).\n")
+  }
+  data <- hyp$data
+  keep <- data$pval <= pval & data$fdr <= fdr
+  data <- utils::head(data[!base::is.na(keep) & keep, , drop = FALSE], top)
+  if (base::nrow(data) == 0) {
+    base::warning(base::sprintf("No genesets pass the cutoffs for '%s'.", name), call. = FALSE)
+    return(NULL)
+  }
+  if (base::nrow(data) < 2) {
+    base::warning(base::sprintf(
+      "Only one geneset passes the cutoffs for '%s'; a map needs at least two.", name
+    ), call. = FALSE)
+    return(NULL)
+  }
+  if (base::identical(type, "hmap")) {
+    return(titleHypeRMap(hypeR::hyp_hmap(hyp, pval = pval, fdr = fdr, val = val, top = top), name, hyp, title))
+  }
+  members <- hyp$args$genesets$genesets[data$label]
+  if (!hypeRAnyMapEdge(members, similarity_metric, similarity_cutoff)) {
+    base::warning(base::sprintf(
+      "No geneset pair in '%s' reaches similarity_cutoff = %s; lower it to draw a map.",
+      name, similarity_cutoff
+    ), call. = FALSE)
+    return(NULL)
+  }
+  map <- hypeR::hyp_emap(hyp, similarity_metric = similarity_metric, similarity_cutoff = similarity_cutoff,
+                         pval = pval, fdr = fdr, val = val, top = top)
+  titleHypeRMap(map, name, hyp, title)
+}
+
+#' Enrichment or hierarchy map of runHypeR() results
+#'
+#' @description Draws hypeR's enrichment map (\code{hypeR::hyp_emap()}, genesets
+#' linked by shared genes) or hierarchy map (\code{hypeR::hyp_hmap()}, needs
+#' \code{rgsets} genesets), after checking the cases where hypeR would fail:
+#' no geneset passing the cutoffs, or no pair of genesets reaching
+#' \code{similarity_cutoff}. Those return \code{NULL} with a warning instead of
+#' an error.
+#'
+#' @section Required and optional arguments:
+#' Only \code{hyp_obj} is required. Every other argument is optional and has the
+#' default listed with it: an enrichment map (\code{type = "emap"}) of the
+#' first 25 rows with no p-value or FDR cutoff, nodes coloured by FDR, and edges
+#' where the Jaccard similarity is at least 0.2. \code{query = NULL} draws every
+#' query (one map for a single query, a named list for several), not "none".
+#' \code{type = "hmap"} also needs results run on \code{hypeR::rgsets}
+#' genesets.
+#'
+#' @inheritParams hypeRDotData
+#' @param val \code{"fdr"} (default) or \code{"pval"}: the value that colours
+#' the map's nodes. Unlike \code{hypeRDotData()}, it does not rank genesets or
+#' choose \code{top}.
+#' @param type \code{"emap"} (default) or \code{"hmap"}.
+#' @param query Query name; with \code{NULL} a \code{multihyp} of several queries
+#' gives a named list with one map per query.
+#' @param top The first \code{top} rows of each result table after the
+#' cutoffs, in table order (not chosen by \code{val}). Default \code{25}.
+#' @param similarity_metric,similarity_cutoff Passed to \code{hypeR::hyp_emap()}.
+#' @param title Map title; defaults to the test that was run
+#' (\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}),
+#' with the query name below it.
+#'
+#' @return A \code{visNetwork} widget, \code{NULL} (with a warning) when there is
+#' nothing to draw, or a named list of those for several queries.
+#'
+#' @examples
+#' \dontrun{
+#' SigRepo::plotHypeRMap(hyp, query = "LLFS_Aging_Gene_2023 | Group1", fdr = 0.05)
+#' }
+#'
+#' @export
+plotHypeRMap <- function(
+    hyp_obj,
+    type = c("emap", "hmap"),
+    query = NULL,
+    val = c("fdr", "pval"),
+    pval = 1,
+    fdr = 1,
+    top = 25,
+    similarity_metric = c("jaccard_similarity", "overlap_similarity"),
+    similarity_cutoff = 0.2,
+    title = NULL
+) {
+  type <- base::match.arg(type)
+  val <- base::match.arg(val)
+  similarity_metric <- base::match.arg(similarity_metric)
+  checkHypeRNumber(top, "top", 1)
+  checkHypeRNumber(similarity_cutoff, "similarity_cutoff", 0)
+  checkHypeRNumber(pval, "pval", 0)
+  checkHypeRNumber(fdr, "fdr", 0)
+
+  hyps <- hypeRResultHyps(hyp_obj)
+  draw <- function(name, hyp) {
+    plotHypeRMapOne(name, hyp, type, val, pval, fdr, top, similarity_metric, similarity_cutoff, title)
+  }
+  if (!base::is.null(query) || base::length(hyps) == 1L) {
+    selected <- hypeRSelectHyp(hyp_obj, query)
+    return(draw(selected$name, selected$hyp))
+  }
+  stats::setNames(base::lapply(base::names(hyps), function(name) draw(name, hyps[[name]])), base::names(hyps))
+}
diff --git a/R/hypeRSignatures.R b/R/hypeRSignatures.R
new file mode 100644
index 00000000..7a5b1c9d
--- /dev/null
+++ b/R/hypeRSignatures.R
@@ -0,0 +1,897 @@
+HYPER_DEFAULT_BACKGROUND <- 23467
+
+# Column names a signature or difexp table may carry gene symbols under. Kept
+# identical to SigRepo_Server's DIFEXP_SYMBOL_COLUMNS (api/lib/annotate.R).
+HYPER_SYMBOL_COLUMNS <- c("gene_symbol", "symbol", "geneSymbol", "gene", "hgnc_symbol", "mgi_symbol")
+
+cleanHypeRSymbols <- function(x) {
+  x <- base::trimws(base::as.character(x))
+  x[base::is.na(x) | !base::nzchar(x)] <- NA_character_
+  x
+}
+
+#' First symbol column that is present and populated, or NULL
+#' @noRd
+hypeRSymbolColumn <- function(tbl) {
+  if (!methods::is(tbl, "data.frame") || base::nrow(tbl) == 0) {
+    return(NULL)
+  }
+  for (col in HYPER_SYMBOL_COLUMNS) {
+    if (col %in% base::colnames(tbl) && base::any(!base::is.na(cleanHypeRSymbols(tbl[[col]])))) {
+      return(col)
+    }
+  }
+  NULL
+}
+
+#' feature_name -> gene_symbol from the reference table for one organism
+#'
+#' Reference tables are unique on (feature_name, organism_id), so the organism
+#' filter is required. lookup_table_sql() matches on trim(lower()), so callers
+#' must match the returned names case-insensitively.
+#'
+#' @return Named character vector (names = feature_name as stored).
+#' @noRd
+lookupReferenceSymbols <- function(conn_handler, assay_type, organism, feature_names) {
+  ref_table <- base::switch(
+    base::tolower(base::as.character(assay_type)[1]),
+    transcriptomics = "transcriptomics_features",
+    proteomics = "proteomics_features",
+    NULL
+  )
+  feature_names <- base::unique(feature_names[!base::is.na(feature_names) & base::nzchar(feature_names)])
+
+  if (base::is.null(conn_handler) || base::is.null(ref_table) || base::length(feature_names) == 0 ||
+      base::length(organism) == 0 || base::is.na(organism[1]) || !base::nzchar(organism[1])) {
+    return(base::character())
+  }
+
+  conn <- SigRepo::conn_init(conn_handler = conn_handler)
+  base::on.exit(base::try(DBI::dbDisconnect(conn), silent = TRUE), add = TRUE)
+
+  organism_tbl <- SigRepo::lookup_table_sql(
+    conn = conn,
+    db_table_name = "organisms",
+    return_var = c("organism_id", "organism"),
+    filter_coln_var = "organism",
+    filter_coln_val = base::list("organism" = organism[1]),
+    check_db_table = TRUE
+  )
+  if (base::nrow(organism_tbl) == 0) {
+    return(base::character())
+  }
+
+  ref_tbl <- SigRepo::lookup_table_sql(
+    conn = conn,
+    db_table_name = ref_table,
+    return_var = c("feature_name", "gene_symbol"),
+    filter_coln_var = c("feature_name", "organism_id"),
+    filter_coln_val = base::list("feature_name" = feature_names, "organism_id" = organism_tbl$organism_id[1]),
+    filter_var_by = "AND",
+    check_db_table = TRUE
+  )
+
+  symbols <- cleanHypeRSymbols(ref_tbl$gene_symbol)
+  keep <- !base::is.na(symbols)
+  stats::setNames(symbols[keep], base::as.character(ref_tbl$feature_name[keep]))
+}
+
+#' Gene symbols for each row of a signature's signature or difexp table
+#'
+#' First source that yields any symbol wins:
+#'   1. a symbol column in the table itself;
+#'   2. (signature table only) the difexp's symbol column joined on probe_id --
+#'      probe_id is an opaque key, used here only to join the two tables;
+#'   3. the reference table by feature_name + organism (needs conn_handler).
+#'
+#' @return list(symbols = chr aligned with rows, NA where unmapped; source = chr)
+#' @noRd
+resolveSignatureSymbols <- function(omic_signature, table = c("signature", "difexp"), conn_handler = NULL) {
+  table <- base::match.arg(table)
+  tbl <- omic_signature[[table]]
+  n_rows <- base::nrow(tbl)
+
+  own_col <- hypeRSymbolColumn(tbl)
+  if (!base::is.null(own_col)) {
+    return(base::list(symbols = cleanHypeRSymbols(tbl[[own_col]]), source = base::sprintf("%s$%s", table, own_col)))
+  }
+
+  if (base::identical(table, "signature")) {
+    difexp_tbl <- omic_signature$difexp
+    difexp_col <- hypeRSymbolColumn(difexp_tbl)
+    if (!base::is.null(difexp_col) && "probe_id" %in% base::colnames(tbl) && "probe_id" %in% base::colnames(difexp_tbl)) {
+      # A probe_id can repeat in difexp (multi-mapped probes, aptamers), so join
+      # on (probe_id, feature_name) when both tables have feature_name. Without
+      # it, join on probe_id only when that key is unique; otherwise a row could
+      # borrow another feature's symbol, so skip to the reference lookup.
+      join_key <- if ("feature_name" %in% base::colnames(tbl) && "feature_name" %in% base::colnames(difexp_tbl)) {
+        function(t) base::paste(base::as.character(t$probe_id), base::as.character(t$feature_name), sep = "\r")
+      } else if (!base::anyDuplicated(base::as.character(difexp_tbl$probe_id))) {
+        function(t) base::as.character(t$probe_id)
+      } else {
+        NULL
+      }
+      if (!base::is.null(join_key)) {
+        by_key <- stats::setNames(cleanHypeRSymbols(difexp_tbl[[difexp_col]]), join_key(difexp_tbl))
+        symbols <- base::unname(by_key[join_key(tbl)])
+        if (base::any(!base::is.na(symbols))) {
+          return(base::list(symbols = symbols, source = base::sprintf("difexp$%s via probe_id", difexp_col)))
+        }
+      }
+    }
+  }
+
+  if ("feature_name" %in% base::colnames(tbl)) {
+    feature_names <- base::trimws(base::as.character(tbl$feature_name))
+    # OmicSignature$new() sorts signature/difexp rows by desc(abs(score)) when a
+    # score column is present, so tbl's row order is not the caller's input
+    # order. Sort before the lookup call so it (and its provenance) is
+    # deterministic; row alignment below still keys off names, not order.
+    reference <- lookupReferenceSymbols(
+      conn_handler = conn_handler,
+      assay_type = omic_signature$metadata$assay_type,
+      organism = omic_signature$metadata$organism,
+      feature_names = base::sort(feature_names)
+    )
+    if (base::length(reference) > 0) {
+      base::names(reference) <- base::tolower(base::names(reference))
+      symbols <- base::unname(reference[base::tolower(feature_names)])
+      if (base::any(!base::is.na(symbols))) {
+        return(base::list(symbols = symbols, source = "reference feature_name"))
+      }
+    }
+  }
+
+  base::list(symbols = base::rep(NA_character_, n_rows), source = NA_character_)
+}
+
+#' resolveSignatureSymbols() memoised for one call
+#'
+#' A kstest run with background = "difexp" needs each signature's difexp
+#' symbols twice (query and background), and each resolution can be a
+#' reference-table query, so resolve each (signature, table) pair once.
+#'
+#' @param conn_handler Passed to resolveSignatureSymbols().
+#' @return function(omic_signature, table, key); `key` must be unique per
+#'   signature within the call (the signature's label).
+#' @noRd
+newHypeRSymbolResolver <- function(conn_handler) {
+  cache <- base::new.env(parent = base::emptyenv())
+  function(omic_signature, table, key) {
+    id <- base::paste(key, table, sep = "\r")
+    if (!base::exists(id, envir = cache, inherits = FALSE)) {
+      base::assign(id, resolveSignatureSymbols(omic_signature, table, conn_handler), envir = cache)
+    }
+    base::get(id, envir = cache, inherits = FALSE)
+  }
+}
+
+#' Error unless split is TRUE or FALSE
+#' @noRd
+checkHypeRSplit <- function(split) {
+  if (!(base::is.logical(split) && base::length(split) == 1L && !base::is.na(split))) {
+    base::stop("\n'split' must be TRUE or FALSE.\n")
+  }
+  base::invisible(split)
+}
+
+#' Error when ranked-test arguments are changed for a hypergeometric test
+#' @noRd
+checkHypeRKstestArgs <- function(test, ks_source) {
+  if (base::identical(test, "hypergeometric") && !base::identical(ks_source, "difexp")) {
+    base::stop("\n'ks_source' only applies when test = \"kstest\" or \"fgsea\".\n")
+  }
+  base::invisible(NULL)
+}
+
+#' Error unless query_names is NULL or a function
+#' @noRd
+checkHypeRQueryNames <- function(query_names) {
+  if (!base::is.null(query_names) && !base::is.function(query_names)) {
+    base::stop("\n'query_names' must be NULL or a function that takes the query info data frame and returns one name per row.\n")
+  }
+  base::invisible(query_names)
+}
+
+#' Apply a user query_names function to the info table
+#' @noRd
+applyHypeRQueryNames <- function(query_names, info) {
+  new_names <- query_names(info)
+  if (!base::is.character(new_names) || base::length(new_names) != base::nrow(info) ||
+      base::any(base::is.na(new_names) | !base::nzchar(new_names))) {
+    base::stop(base::sprintf(
+      "\n'query_names' must return a character vector of %d non-empty name(s), one per row of the query info.\n",
+      base::nrow(info)
+    ))
+  }
+  new_names
+}
+
+disambiguateHypeRLabels <- function(labels) {
+  used <- base::character()
+  for (i in base::seq_along(labels)) {
+    candidate <- labels[i]
+    suffix <- 2L
+    while (candidate %in% used) {
+      candidate <- base::sprintf("%s (%d)", labels[i], suffix)
+      suffix <- suffix + 1L
+    }
+    labels[i] <- candidate
+    used <- c(used, candidate)
+  }
+  labels
+}
+
+#' Resolve signatures plus their ids and display labels
+#' @noRd
+collectHypeRSignatures <- function(conn_handler, signature_id, signature_name, omic_signature, verbose) {
+  supplied <- function(x) base::length(x) > 0 && base::any(!x %in% c("", NA))
+  if (!base::is.null(omic_signature) && (supplied(signature_id) || supplied(signature_name))) {
+    base::stop("\nSupply either 'omic_signature' or 'signature_id'/'signature_name', not both.\n")
+  }
+
+  signatures <- resolveHypeRSignatures(
+    conn_handler = conn_handler,
+    signature_id = signature_id,
+    signature_name = signature_name,
+    omic_signature = omic_signature,
+    verbose = verbose
+  )
+
+  supplied_names <- if (!base::is.null(omic_signature) && !methods::is(omic_signature, "OmicSignature")) {
+    base::names(omic_signature)
+  } else {
+    NULL
+  }
+
+  fetched_by_id <- base::is.null(omic_signature) && base::length(signature_id) > 0 &&
+    base::any(!signature_id %in% c("", NA))
+  ids <- if (fetched_by_id) base::names(signatures) else base::rep(NA_character_, base::length(signatures))
+
+  labels <- base::vapply(base::seq_along(signatures), function(i) {
+    supplied <- supplied_names[i]
+    if (!base::is.null(supplied) && !base::is.na(supplied) && base::nzchar(supplied)) {
+      return(base::as.character(supplied))
+    }
+    resolveSignatureLabel(signatures[[i]], label = NULL, fallback = base::sprintf("sig_%s", i))
+  }, base::character(1))
+
+  # hypeR returns a hyp for a vector and a multihyp for a list; a single
+  # OmicSignature or a single id/name is SigRepo's equivalent of a vector.
+  single <- methods::is(omic_signature, "OmicSignature") ||
+    (base::is.null(omic_signature) && base::length(signatures) == 1L)
+
+  base::list(signatures = base::unname(signatures), ids = ids, labels = disambiguateHypeRLabels(labels), single = single)
+}
+
+emptyHypeRInfo <- function() {
+  base::data.frame(
+    query = base::character(), signature_id = base::character(), signature_name = base::character(),
+    group_label = base::character(), direction = base::character(), n_features = base::integer(),
+    n_dropped = base::integer(), symbol_source = base::character(), stringsAsFactors = FALSE
+  )
+}
+
+hypeRInfoRow <- function(query, signature_id, label, group_label, direction, n_features, n_dropped, symbol_source) {
+  base::data.frame(
+    query = query, signature_id = signature_id, signature_name = label, group_label = group_label,
+    direction = direction, n_features = base::as.integer(n_features), n_dropped = base::as.integer(n_dropped),
+    symbol_source = symbol_source, stringsAsFactors = FALSE
+  )
+}
+
+hypeRSkip <- function(reason, message) {
+  base::list(queries = base::list(), info = NULL, skip = base::list(reason = reason, message = message))
+}
+
+#' TRUE when a signature's metadata marks it categorical
+#' @noRd
+isCategoricalHypeRSignature <- function(omic_signature) {
+  type <- base::tryCatch(omic_signature$metadata$type, error = function(e) NULL)
+  base::length(type) > 0 && base::identical(base::tolower(base::trimws(base::as.character(type[1]))), "categorical")
+}
+
+#' Trimmed group labels for a table's rows ("" when missing)
+#' @noRd
+hypeRGroupLabels <- function(tbl) {
+  if (!"group_label" %in% base::colnames(tbl)) {
+    return(base::rep("", base::nrow(tbl)))
+  }
+  groups <- base::trimws(base::as.character(tbl$group_label))
+  groups[base::is.na(groups)] <- ""
+  groups
+}
+
+#' Why a ranking cannot carry a direction, or NULL when it can
+#'
+#' A ranked test needs a signed differential score (e.g. a t statistic): the
+#' top of the list is one class and the bottom the other. A constant score
+#' gives an arbitrary order, and all-positive (or all-negative) scores rank
+#' effect size without saying which side each gene is on.
+#' @return NULL or list(reason, message)
+#' @noRd
+hypeRRankingProblem <- function(scores, where) {
+  if (base::length(base::unique(scores)) <= 1L) {
+    return(base::list(
+      reason = "constant_score",
+      message = base::sprintf("Every score in %s is the same, so a ranking has no order.", where)
+    ))
+  }
+  if (base::all(scores >= 0) || base::all(scores <= 0)) {
+    return(base::list(
+      reason = "unsigned_score",
+      message = base::sprintf(
+        "Scores in %s are all %s 0; a ranked test needs a signed differential score (e.g. a t statistic or logFC).",
+        where, if (base::all(scores >= 0)) ">=" else "<="
+      )
+    ))
+  }
+  NULL
+}
+
+#' Hypergeometric query vectors for one signature
+#'
+#' split = TRUE gives one query per group_label. Uni- and bi-directional
+#' signatures carry their direction in group_label already; a categorical
+#' signature's group is a category, so when it has scores each category is
+#' further split by score sign into "<group> | up" (score > 0) and
+#' "<group> | down" (score < 0). Rows scoring exactly 0 join neither.
+#' @noRd
+buildHypergeometricQueries <- function(omic_signature, label, signature_id, split, resolve_symbols) {
+  tbl <- omic_signature$signature
+  if (!methods::is(tbl, "data.frame") || base::nrow(tbl) == 0) {
+    return(hypeRSkip("empty_signature", "The signature table is empty."))
+  }
+
+  resolved <- resolve_symbols(omic_signature, "signature", label)
+  if (base::all(base::is.na(resolved$symbols))) {
+    return(hypeRSkip("no_gene_symbols", "No gene symbols in the signature, its difexp, or the reference tables."))
+  }
+
+  groups <- if (base::isTRUE(split)) hypeRGroupLabels(tbl) else base::rep("", base::nrow(tbl))
+  scores <- if ("score" %in% base::colnames(tbl)) base::suppressWarnings(base::as.numeric(tbl$score)) else NULL
+  by_sign <- base::isTRUE(split) && isCategoricalHypeRSignature(omic_signature) &&
+    !base::is.null(scores) && base::any(!base::is.na(scores))
+  signs <- if (by_sign) {
+    base::ifelse(base::is.na(scores) | scores == 0, NA_character_, base::ifelse(scores > 0, "up", "down"))
+  } else {
+    base::rep("", base::nrow(tbl))
+  }
+
+  queries <- base::list()
+  info <- base::list()
+  # OmicSignature$new() sorts signature rows by desc(abs(score)) when a score
+  # column is present, so tbl's row order is not the caller's input order.
+  # Sort query vectors so output is deterministic regardless of that ordering
+  # (the hypergeometric test treats a query as an unordered set anyway).
+  for (group in base::sort(base::unique(groups))) {
+    in_group <- groups == group
+    for (sign in if (by_sign) c("up", "down") else "") {
+      rows <- in_group & if (by_sign) (!base::is.na(signs) & signs == sign) else TRUE
+      group_symbols <- resolved$symbols[rows]
+      query <- base::sort(base::unique(group_symbols[!base::is.na(group_symbols)]))
+      if (base::length(query) == 0) {
+        next
+      }
+      query_name <- base::paste(c(label, if (base::nzchar(group)) group, if (by_sign) sign), collapse = " | ")
+      queries[[query_name]] <- query
+      info[[base::length(info) + 1]] <- hypeRInfoRow(
+        query = query_name, signature_id = signature_id, label = label,
+        group_label = if (base::nzchar(group)) group else NA_character_,
+        direction = if (by_sign) sign else NA_character_,
+        n_features = base::length(query),
+        n_dropped = base::sum(base::is.na(group_symbols)),
+        symbol_source = resolved$source
+      )
+    }
+  }
+
+  base::list(queries = queries, info = base::do.call(base::rbind, info), skip = NULL)
+}
+
+#' Ranked kstest query vector(s) for one signature
+#'
+#' Ranks `ks_source`'s table by `score_col`. With `both = TRUE` (kstest) it
+#' returns two queries, "<label> | up" with the highest scores first and
+#' "<label> | down" ranking the negated scores so the lowest come first:
+#' hypeR's one-sided test only finds enrichment at the top, so testing both
+#' ends takes two runs. With `both = FALSE` (fgsea, which tests both tails in
+#' one run) it returns the single "up" ranking, named "<label>". A categorical
+#' signature is ranked once per group_label, using only that group's rows
+#' ("<label> | <group>", plus " | up"/" | down" for kstest), because its
+#' groups are separate contrasts. A ranking whose scores are constant or all
+#' one sign is skipped (see hypeRRankingProblem()).
+#' @noRd
+buildKstestQueries <- function(omic_signature, label, signature_id, score_col, both, ks_source, resolve_symbols) {
+  tbl <- omic_signature[[ks_source]]
+  if (!methods::is(tbl, "data.frame") || base::nrow(tbl) == 0) {
+    if (base::identical(ks_source, "difexp")) {
+      return(hypeRSkip("no_difexp", "kstest needs a difexp table and this signature has none."))
+    }
+    return(hypeRSkip("empty_signature", "The signature table is empty."))
+  }
+  if (!score_col %in% base::colnames(tbl)) {
+    return(hypeRSkip(
+      "missing_score_col",
+      base::sprintf("%s has no '%s' column (has: %s).", ks_source, score_col, base::paste(base::colnames(tbl), collapse = ", "))
+    ))
+  }
+
+  resolved <- resolve_symbols(omic_signature, ks_source, label)
+  scores <- base::suppressWarnings(base::as.numeric(tbl[[score_col]]))
+  keep <- !base::is.na(resolved$symbols) & !base::is.na(scores)
+  if (!base::any(keep)) {
+    return(hypeRSkip("no_gene_symbols", base::sprintf("No %s row has both a gene symbol and a numeric score.", ks_source)))
+  }
+
+  categorical <- isCategoricalHypeRSignature(omic_signature)
+  groups <- if (categorical) hypeRGroupLabels(tbl) else base::rep("", base::nrow(tbl))
+  if (categorical && !base::any(base::nzchar(groups[keep]))) {
+    return(hypeRSkip("no_group_label", base::sprintf("A categorical signature needs group_label in %s to rank each category.", ks_source)))
+  }
+
+  directions <- if (both) c("up", "down") else "up"
+  queries <- base::list()
+  info <- base::list()
+  group_skips <- base::list()
+  for (group in base::sort(base::unique(groups[keep & (base::nzchar(groups) | !categorical)]))) {
+    rows <- keep & groups == group
+    where <- if (categorical) base::sprintf("%s group '%s'", ks_source, group) else ks_source
+    problem <- hypeRRankingProblem(scores[rows], where)
+    if (!base::is.null(problem)) {
+      if (!categorical) {
+        return(hypeRSkip(problem$reason, problem$message))
+      }
+      group_skips[[base::length(group_skips) + 1]] <- base::data.frame(
+        signature = base::sprintf("%s | %s", label, group), reason = problem$reason, message = problem$message,
+        stringsAsFactors = FALSE
+      )
+      next
+    }
+
+    best <- base::vapply(
+      base::split(scores[rows], resolved$symbols[rows]),
+      # On an opposite-sign |score| tie keep the positive value, so the result
+      # does not depend on row order.
+      function(x) base::max(x[base::abs(x) == base::max(base::abs(x))]),
+      base::numeric(1)
+    )
+    for (d in directions) {
+      query_name <- base::paste(c(label, if (categorical) group, if (both) d), collapse = " | ")
+      queries[[query_name]] <- base::sort(if (base::identical(d, "down")) -best else best, decreasing = TRUE)
+      info[[base::length(info) + 1]] <- hypeRInfoRow(
+        query = query_name, signature_id = signature_id, label = label,
+        group_label = if (categorical) group else NA_character_, direction = d,
+        n_features = base::length(best), n_dropped = base::sum(!keep & groups == group), symbol_source = resolved$source
+      )
+    }
+  }
+
+  if (base::length(queries) == 0) {
+    first <- group_skips[[1]]
+    return(hypeRSkip(first$reason, base::paste(base::vapply(group_skips, `[[`, "", "message"), collapse = " ")))
+  }
+  base::list(
+    queries = queries, info = base::do.call(base::rbind, info), skip = NULL,
+    group_skips = if (base::length(group_skips) > 0) base::do.call(base::rbind, group_skips) else NULL
+  )
+}
+
+#' Build query vectors for already-collected signatures
+#' @noRd
+buildHypeRQueries <- function(inputs, test, split, score_col, resolve_symbols,
+                              ks_source = "difexp", query_names = NULL) {
+  queries <- base::list()
+  info <- base::list()
+  skipped <- base::list()
+
+  for (i in base::seq_along(inputs$signatures)) {
+    built <- if (base::identical(test, "hypergeometric")) {
+      buildHypergeometricQueries(inputs$signatures[[i]], inputs$labels[i], inputs$ids[i], split, resolve_symbols)
+    } else {
+      # kstest needs an up and a down ranking; fgsea tests both tails in one
+      # run, so it needs only the up ranking.
+      buildKstestQueries(inputs$signatures[[i]], inputs$labels[i], inputs$ids[i], score_col,
+                         both = base::identical(test, "kstest"), ks_source, resolve_symbols)
+    }
+
+    if (!base::is.null(built$skip)) {
+      skipped[[base::length(skipped) + 1]] <- base::data.frame(
+        signature = inputs$labels[i], reason = built$skip$reason, message = built$skip$message,
+        stringsAsFactors = FALSE
+      )
+      next
+    }
+
+    queries <- c(queries, built$queries)
+    info[[base::length(info) + 1]] <- built$info
+    if (!base::is.null(built$group_skips)) {
+      skipped[[base::length(skipped) + 1]] <- built$group_skips
+    }
+  }
+
+  info <- if (base::length(info) > 0) base::do.call(base::rbind, info) else emptyHypeRInfo()
+  if (base::identical(test, "fgsea") && base::nrow(info) > 0) {
+    info$direction <- "both"
+  }
+  if (base::length(queries) > 0) {
+    if (!base::is.null(query_names)) {
+      base::names(queries) <- applyHypeRQueryNames(query_names, info)
+    }
+    # Labels are unique per signature, but a label can still collide with
+    # another signature's "<label> | <group>" query name (or a user name can
+    # repeat), so de-duplicate the final names.
+    base::names(queries) <- disambiguateHypeRLabels(base::names(queries))
+    info$query <- base::names(queries)
+  }
+
+  base::list(
+    signatures = queries,
+    info = info,
+    skipped = if (base::length(skipped) > 0) {
+      base::do.call(base::rbind, skipped)
+    } else {
+      base::data.frame(signature = base::character(), reason = base::character(), message = base::character(), stringsAsFactors = FALSE)
+    }
+  )
+}
+
+#' Query vectors from hypeR-native input
+#'
+#' A character vector is a symbol set (hypergeometric) or a ranked list in the
+#' given order (kstest); a named numeric vector is a weighted kstest signature,
+#' used in the given order as hypeR does. A named list of those gives one query
+#' per element. NA and empty symbols are removed (counted in n_dropped), and a
+#' character vector keeps the first occurrence of each symbol.
+#'
+#' @return list(prepared = list(signatures, info, skipped), inputs = list(signatures
+#'   = NULL, ids, labels, single))
+#' @noRd
+buildNativeHypeRQueries <- function(signature, test, query_names) {
+  single <- !base::is.list(signature)
+  if (single) {
+    signature <- base::list(signature = signature)
+  } else {
+    labels <- base::names(signature)
+    if (base::length(signature) == 0 || base::is.null(labels) || base::any(base::is.na(labels) | !base::nzchar(labels)) ||
+        base::anyDuplicated(labels)) {
+      base::stop("\nA 'signature' list must be non-empty with a unique, non-empty name for every element.\n")
+    }
+  }
+
+  queries <- base::list()
+  info <- base::list()
+  skipped <- base::list()
+  for (label in base::names(signature)) {
+    x <- signature[[label]]
+    if (base::identical(test, "fgsea") && base::is.character(x)) {
+      base::stop(base::sprintf(
+        "\n'signature' element '%s': test = \"fgsea\" needs scores: pass a named numeric vector.\n",
+        label
+      ))
+    }
+    if (base::is.character(x) && !base::is.list(x)) {
+      symbols <- cleanHypeRSymbols(x)
+      query <- base::unique(symbols[!base::is.na(symbols)])
+      n_dropped <- base::sum(base::is.na(symbols))
+    } else if (base::is.numeric(x) && !base::is.null(base::names(x))) {
+      if (base::identical(test, "hypergeometric")) {
+        base::stop(base::sprintf(
+          "\n'signature' element '%s' is a named numeric vector; test = \"hypergeometric\" needs a character vector of gene symbols.\n",
+          label
+        ))
+      }
+      symbols <- cleanHypeRSymbols(base::names(x))
+      keep <- !base::is.na(symbols) & !base::is.na(x)
+      if (base::anyDuplicated(symbols[keep])) {
+        base::stop(base::sprintf("\n'signature' element '%s' has duplicated gene names; a weighted signature needs one score per gene.\n", label))
+      }
+      query <- stats::setNames(base::as.numeric(x[keep]), symbols[keep])
+      n_dropped <- base::sum(!keep)
+    } else {
+      base::stop(base::sprintf(
+        "\n'signature' element '%s' must be a character vector of gene symbols or a named numeric vector of scores.\n",
+        label
+      ))
+    }
+
+    if (base::length(query) == 0) {
+      skipped[[base::length(skipped) + 1]] <- base::data.frame(
+        signature = label, reason = "empty_signature", message = "No gene symbols left after removing NA and empty values.",
+        stringsAsFactors = FALSE
+      )
+      next
+    }
+    if (base::identical(test, "kstest")) {
+      # hypeR's KS test only finds enrichment at the top of the ranking, so the
+      # bottom is tested as a second query on the reversed ranking (negated
+      # scores for a weighted signature).
+      sides <- base::list(up = query, down = if (base::is.numeric(query)) base::rev(-query) else base::rev(query))
+      for (side in base::names(sides)) {
+        query_name <- base::paste(label, side, sep = " | ")
+        queries[[query_name]] <- sides[[side]]
+        info[[base::length(info) + 1]] <- hypeRInfoRow(
+          query = query_name, signature_id = NA_character_, label = label, group_label = NA_character_, direction = side,
+          n_features = base::length(query), n_dropped = n_dropped, symbol_source = "supplied"
+        )
+      }
+    } else {
+      queries[[label]] <- query
+      info[[base::length(info) + 1]] <- hypeRInfoRow(
+        query = label, signature_id = NA_character_, label = label, group_label = NA_character_, direction = NA_character_,
+        n_features = base::length(query), n_dropped = n_dropped, symbol_source = "supplied"
+      )
+    }
+  }
+
+  info <- if (base::length(info) > 0) base::do.call(base::rbind, info) else emptyHypeRInfo()
+  if (base::length(queries) > 0 && !base::is.null(query_names)) {
+    base::names(queries) <- disambiguateHypeRLabels(applyHypeRQueryNames(query_names, info))
+    info$query <- base::names(queries)
+  }
+
+  base::list(
+    prepared = base::list(
+      signatures = queries,
+      info = info,
+      skipped = if (base::length(skipped) > 0) {
+        base::do.call(base::rbind, skipped)
+      } else {
+        base::data.frame(signature = base::character(), reason = base::character(), message = base::character(), stringsAsFactors = FALSE)
+      }
+    ),
+    inputs = base::list(
+      signatures = NULL, ids = base::rep(NA_character_, base::length(signature)),
+      labels = base::names(signature), single = single
+    )
+  )
+}
+
+#' Collect signatures (SigRepo or hypeR-native) and build their query vectors
+#'
+#' Shared by prepareHypeRSignatures() and runHypeR().
+#' @return list(prepared, inputs, native = logical)
+#' @noRd
+collectAndBuildHypeRQueries <- function(conn_handler, signature_id, signature_name, omic_signature, signature,
+                                        test, split, ks_source, score_col, query_names,
+                                        resolve_symbols, verbose) {
+  if (!base::is.null(signature)) {
+    supplied <- function(x) base::length(x) > 0 && base::any(!x %in% c("", NA))
+    if (!base::is.null(omic_signature) || supplied(signature_id) || supplied(signature_name)) {
+      base::stop("\nSupply either 'signature' or SigRepo signatures ('omic_signature', 'signature_id', 'signature_name'), not both.\n")
+    }
+    if (!base::identical(ks_source, "difexp")) {
+      base::stop("\n'ks_source' applies to SigRepo signatures; with 'signature', order the vector yourself.\n")
+    }
+    native <- buildNativeHypeRQueries(signature, test, query_names)
+    if (base::identical(test, "fgsea") && base::nrow(native$prepared$info) > 0) {
+      native$prepared$info$direction <- "both"
+    }
+    return(c(native, base::list(native = TRUE)))
+  }
+
+  inputs <- collectHypeRSignatures(
+    conn_handler = conn_handler,
+    signature_id = signature_id,
+    signature_name = signature_name,
+    omic_signature = omic_signature,
+    verbose = verbose
+  )
+  prepared <- buildHypeRQueries(
+    inputs, test = test, split = split, score_col = score_col, resolve_symbols = resolve_symbols,
+    ks_source = ks_source, query_names = query_names
+  )
+  base::list(prepared = prepared, inputs = inputs, native = FALSE)
+}
+
+#' Difexp tables with resolved gene symbols
+#'
+#' @description Returns each signature's difexp table with the gene symbol
+#' \code{runHypeR()} would use for every row, so you can apply your own cutoffs
+#' (e.g. a stricter FDR or a fold-change threshold) and pass the resulting gene
+#' list to \code{runHypeR(signature = ...)}.
+#'
+#' @section Required and optional arguments:
+#' The signatures are required, as exactly one of \code{signature_id} or
+#' \code{signature_name} (each with \code{conn_handler}), or
+#' \code{omic_signature}; they cannot be combined. \code{signature} is not
+#' accepted here, because a plain gene vector has no difexp table. Everything
+#' else is optional: \code{verbose} defaults to \code{TRUE}. With
+#' \code{omic_signature}, \code{conn_handler} is still worth passing when the
+#' difexp has no symbol column of its own, since it is what looks symbols up in
+#' the reference feature table; without it those rows get
+#' \code{resolved_symbol = NA}.
+#'
+#' @inheritParams prepareHypeRSignatures
+#'
+#' @return A named list with one data frame per signature that has a difexp,
+#' named by signature label (list name, else \code{signature_name}). Each is the
+#' difexp table plus \code{resolved_symbol} (\code{NA} where no symbol was
+#' found) and \code{resolved_symbol_source}. Signatures without a difexp are
+#' left out with a warning.
+#'
+#' @details Symbols come from the difexp's own symbol column, else the
+#' reference feature table by \code{feature_name} and organism (needs
+#' \code{conn_handler}). \code{probe_id} is never read as a symbol.
+#' \code{runHypeR(signature = ...)} records \code{Symbol Source = "supplied"}
+#' and no signature ID, so keep the signature id with your results if you need
+#' it.
+#'
+#' @examples
+#' \dontrun{
+#' difexp <- SigRepo::getHypeRDifexp(omic_signature = sig)[[1]]
+#' strict_up <- difexp$resolved_symbol[difexp$adj_p < 0.001 & difexp$score > 0]
+#' hyp <- SigRepo::runHypeR(signature = list(strict_up = strict_up), organism = "Homo sapiens",
+#'                          test = "hypergeometric", genesets = hallmark)
+#' }
+#'
+#' @export
+getHypeRDifexp <- function(
+    conn_handler = NULL,
+    signature_id = NULL,
+    signature_name = NULL,
+    omic_signature = NULL,
+    verbose = TRUE
+) {
+  inputs <- collectHypeRSignatures(
+    conn_handler = conn_handler,
+    signature_id = signature_id,
+    signature_name = signature_name,
+    omic_signature = omic_signature,
+    verbose = verbose
+  )
+  resolve_symbols <- newHypeRSymbolResolver(conn_handler)
+
+  tables <- base::list()
+  no_difexp <- base::character()
+  for (i in base::seq_along(inputs$signatures)) {
+    sig <- inputs$signatures[[i]]
+    label <- inputs$labels[i]
+    if (!methods::is(sig$difexp, "data.frame") || base::nrow(sig$difexp) == 0) {
+      no_difexp <- c(no_difexp, label)
+      next
+    }
+    resolved <- resolve_symbols(sig, "difexp", label)
+    tbl <- sig$difexp
+    tbl$resolved_symbol <- resolved$symbols
+    tbl$resolved_symbol_source <- base::rep(resolved$source, base::nrow(tbl))
+    tables[[label]] <- tbl
+  }
+
+  if (base::length(no_difexp) > 0) {
+    base::warning(
+      base::sprintf("No difexp table for %s; left out.", base::paste(base::sprintf("'%s'", no_difexp), collapse = ", ")),
+      call. = FALSE
+    )
+  }
+  tables
+}
+
+#' Build hypeR query vectors from SigRepo signatures
+#'
+#' @description Turns SigRepo signatures into the query vectors
+#' \code{hypeR::hypeR()} takes, and reports how each was built. Use it to
+#' inspect exactly what \code{runHypeR()} will test.
+#'
+#' @section Required and optional arguments:
+#' The signatures are required, as exactly one of \code{signature_id} or
+#' \code{signature_name} (each with \code{conn_handler}),
+#' \code{omic_signature}, or \code{signature}; they cannot be combined. Every
+#' other argument is optional and has the default listed with it, which is what
+#' \code{runHypeR()} uses unless you pass something else. No genesets are
+#' needed: this builds the queries, it does not test them.
+#'
+#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
+#' Needed to fetch signatures by id/name and for reference-table symbol lookup.
+#' @param signature_id One or more SigRepo signature IDs.
+#' @param signature_name One or more SigRepo signature names.
+#' @param omic_signature An \code{OmicSignature} object or a list of them. List
+#' names, when given, become the query labels.
+#' @param signature hypeR-native input instead of SigRepo signatures: a
+#' character vector of gene symbols, a named numeric vector of scores (kstest
+#' only), or a named list of those, as \code{hypeR::hypeR()} takes. A vector is
+#' used in the order given (it is the ranking for kstest); NA and empty symbols
+#' are removed. Cannot be combined with \code{omic_signature},
+#' \code{signature_id} or \code{signature_name}; \code{split},
+#' \code{score_col} are ignored and \code{ks_source} must stay at its
+#' default. For \code{"kstest"}, each vector is tested as given
+#' (\code{"<name> | up"}) and reversed (\code{"<name> | down"}, with negated
+#' scores). Use \code{getHypeRDifexp()} to build a gene list from
+#' a signature's difexp with your own cutoffs.
+#' @param test \code{"hypergeometric"} (a character vector of symbols from the
+#' signature table), \code{"kstest"} (a named numeric vector ranked by
+#' \code{score_col}, from the table named by \code{ks_source}) or
+#' \code{"fgsea"} (the "up" ranking of \code{"kstest"}: one ranking per
+#' signature, or per category for a categorical signature, and
+#' \code{info$direction} is \code{"both"}). With \code{"fgsea"},
+#' \code{signature} input must be named numeric vectors. Both ranked tests
+#' always test both ends of the ranking: hypeR's KS test only finds genesets
+#' enriched toward the top, so \code{"kstest"} builds two queries per ranking,
+#' \code{"<label> | up"} (highest scores first) and \code{"<label> | down"}
+#' (the negated scores, so the lowest come first), whose p-values are adjusted
+#' for multiple testing together; \code{"fgsea"} tests both tails in one run
+#' and returns \code{"<label> | up"} (ES > 0) and \code{"<label> | down"}
+#' (ES < 0). A categorical signature is ranked separately within each
+#' \code{group_label}, using only that category's rows
+#' (\code{"<label> | <group> | up"} / \code{" | down"}). A ranking needs a
+#' signed score: one whose scores are all equal (\code{constant_score}) or all
+#' one sign (\code{unsigned_score}) is skipped, per category for categorical
+#' signatures.
+#' @param split Logical; for \code{"hypergeometric"}, build one vector per
+#' \code{group_label} (e.g. one per arm of a bi-directional signature). A
+#' categorical signature's groups are categories rather than directions, so when
+#' its signature table has scores each category is also split by score sign:
+#' \code{"<label> | <group> | up"} (score > 0) and \code{"... | down"}
+#' (score < 0); rows scoring exactly 0 join neither. Ignored by
+#' \code{"kstest"} and \code{"fgsea"}. Defaults to \code{TRUE}.
+#' @param ks_source For \code{"kstest"} and \code{"fgsea"} only: the table to
+#' rank. \code{"difexp"} (default) ranks every measured gene. \code{"signature"}
+#' ranks only the signature table, for signatures stored without a difexp; the
+#' KS test then compares genesets against the signature's genes rather than
+#' against everything measured, so its p-values answer a narrower question.
+#' @param score_col Column used to rank genes for \code{"kstest"} and
+#' \code{"fgsea"}, in the table named by \code{ks_source}. Defaults to
+#' \code{"score"}.
+#' @param query_names \code{NULL} (default) for names built as
+#' \code{"<label> | <group_label>"}, \code{"<label> | <direction>"} or
+#' \code{"<label>"}, or a function that takes the query info data frame (the
+#' \code{info} element described under Value, with those default names in
+#' \code{query}) and returns one non-empty name per row. Duplicates are made
+#' unique as \code{name (2)}. For example
+#' \code{function(info) paste(info$signature_id, info$group_label, sep = "_")}.
+#' @param verbose Logical; print messages while fetching signatures.
+#'
+#' @details Gene symbols come from the first source that works: a symbol column
+#' (\code{gene_symbol}, \code{symbol}, \code{geneSymbol}, \code{gene},
+#' \code{hgnc_symbol}, \code{mgi_symbol}) in the table itself; for the
+#' signature table, the difexp's symbol column joined on \code{probe_id};
+#' then the reference feature table by \code{feature_name} and organism (needs
+#' \code{conn_handler}). \code{probe_id} is never read as a symbol.
+#'
+#' @return A list with
+#' \describe{
+#'   \item{\code{signatures}}{Named list of query vectors, ready for \code{hypeR::hypeR()}.}
+#'   \item{\code{info}}{Data frame, one row per query: \code{query}, \code{signature_id},
+#'   \code{signature_name}, \code{group_label}, \code{direction} (kstest only),
+#'   \code{n_features}, \code{n_dropped} (rows without a gene symbol or score),
+#'   \code{symbol_source}.}
+#'   \item{\code{skipped}}{Data frame of signatures (or, for a categorical
+#'   kstest, \code{"<label> | <group>"} categories) that produced no query:
+#'   \code{signature}, \code{reason} (\code{empty_signature},
+#'   \code{no_gene_symbols}, \code{no_difexp}, \code{missing_score_col},
+#'   \code{no_group_label}, \code{constant_score}, \code{unsigned_score}),
+#'   \code{message}.}
+#' }
+#'
+#' @examples
+#' utils::data("LLFS_Aging_Gene_2023", package = "SigRepo")
+#' prepared <- SigRepo::prepareHypeRSignatures(omic_signature = LLFS_Aging_Gene_2023, verbose = FALSE)
+#' prepared$info
+#'
+#' @export
+prepareHypeRSignatures <- function(
+    conn_handler = NULL,
+    signature_id = NULL,
+    signature_name = NULL,
+    omic_signature = NULL,
+    signature = NULL,
+    test = c("hypergeometric", "kstest", "fgsea"),
+    split = TRUE,
+    ks_source = c("difexp", "signature"),
+    score_col = "score",
+    query_names = NULL,
+    verbose = TRUE
+) {
+  test <- base::match.arg(test)
+  ks_source <- base::match.arg(ks_source)
+  checkHypeRSplit(split)
+  checkHypeRKstestArgs(test, ks_source)
+  checkHypeRQueryNames(query_names)
+
+  collectAndBuildHypeRQueries(
+    conn_handler = conn_handler, signature_id = signature_id, signature_name = signature_name,
+    omic_signature = omic_signature, signature = signature, test = test, split = split,
+    ks_source = ks_source, score_col = score_col, query_names = query_names,
+    resolve_symbols = newHypeRSymbolResolver(conn_handler), verbose = verbose
+  )$prepared
+}
diff --git a/R/hypeR_examples.R b/R/hypeR_examples.R
deleted file mode 100644
index a292c7af..00000000
--- a/R/hypeR_examples.R
+++ /dev/null
@@ -1,2210 +0,0 @@
-annotate_module_ui <- function(id) {
-  ns <- NS(id)
-  page_selector <- paste0("#", ns("annotate_page"))
-  
-  tagList(
-    tags$style(HTML(paste0("
-      ", page_selector, " {
-        padding-top: 28px;
-        padding-bottom: 32px;
-      }
-
-      ", page_selector, " .annotate-hero {
-        margin-bottom: 18px;
-        padding: 24px 28px;
-        border-radius: 14px;
-        background: linear-gradient(135deg, #0f3b63 0%, #1b5d8f 100%);
-        color: #ffffff;
-        box-shadow: 0 10px 24px rgba(15, 59, 99, 0.18);
-      }
-
-      ", page_selector, " .annotate-hero h2 {
-        margin-top: 0;
-        margin-bottom: 8px;
-        font-weight: 700;
-      }
-
-      ", page_selector, " .annotate-hero p {
-        margin-bottom: 0;
-        color: rgba(255, 255, 255, 0.88);
-      }
-
-      ", page_selector, " .annotate-card {
-        margin-bottom: 18px;
-        padding: 20px 22px;
-        border: 1px solid #d9e3ec;
-        border-radius: 12px;
-        background: #ffffff;
-        box-shadow: 0 6px 18px rgba(15, 32, 56, 0.06);
-      }
-
-      ", page_selector, " .annotate-card h3,
-      ", page_selector, " .annotate-card h4 {
-        margin-top: 0;
-        margin-bottom: 12px;
-        color: #17324d;
-        font-weight: 600;
-      }
-
-      ", page_selector, " .annotate-step-label {
-        display: inline-block;
-        margin-bottom: 10px;
-        padding: 4px 10px;
-        border-radius: 999px;
-        background: #e9f2f9;
-        color: #0f4d7c;
-        font-size: 12px;
-        font-weight: 700;
-        letter-spacing: 0.04em;
-        text-transform: uppercase;
-      }
-
-      ", page_selector, " .annotate-summary-grid {
-        display: grid;
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-        gap: 12px;
-      }
-
-      ", page_selector, " .annotate-summary-item {
-        padding: 12px 14px;
-        border-radius: 10px;
-        background: #f6f9fc;
-        border: 1px solid #e1ebf2;
-      }
-
-      ", page_selector, " .annotate-summary-item strong {
-        display: block;
-        margin-bottom: 4px;
-        color: #0f3b63;
-        font-size: 12px;
-        text-transform: uppercase;
-        letter-spacing: 0.04em;
-      }
-
-      ", page_selector, " .annotate-summary-item span {
-        color: #17324d;
-        font-size: 15px;
-        font-weight: 600;
-      }
-
-      ", page_selector, " .annotate-feedback {
-        margin-top: 10px;
-      }
-
-      ", page_selector, " .annotate-actions {
-        display: flex;
-        gap: 10px;
-        flex-wrap: wrap;
-        margin-top: 14px;
-      }
-
-      ", page_selector, " .annotate-empty {
-        padding: 18px;
-        border: 1px dashed #c5d5e3;
-        border-radius: 10px;
-        background: #f8fbfd;
-        color: #4b647e;
-      }
-
-      ", page_selector, " .annotate-results-header {
-        display: flex;
-        justify-content: space-between;
-        align-items: center;
-        gap: 12px;
-        flex-wrap: wrap;
-        margin-bottom: 16px;
-      }
-
-      ", page_selector, " .annotate-results-actions .btn {
-        margin-left: 8px;
-      }
-
-      ", page_selector, " .annotate-results-body {
-        display: grid;
-        grid-template-columns: minmax(0, 1fr);
-        gap: 22px;
-      }
-
-      ", page_selector, " .annotate-results-section h4 {
-        margin-top: 0;
-        margin-bottom: 12px;
-        color: #17324d;
-        font-weight: 600;
-      }
-
-      ", page_selector, " .annotate-signature-key {
-        margin-top: 14px;
-      }
-
-      ", page_selector, " .annotate-signature-key .dataTables_wrapper {
-        font-size: 12px;
-      }
-
-      ", page_selector, " .geneset-filter-group {
-        padding: 16px;
-        border: 1px solid #d9e3ec;
-        border-radius: 10px;
-        background: #f8fbfd;
-      }
-
-      ", page_selector, " .geneset-filter-heading h4 {
-        margin-top: 0;
-        margin-bottom: 6px;
-      }
-
-      ", page_selector, " .geneset-filter-heading p {
-        margin-bottom: 14px;
-        color: #597189;
-      }
-
-      ", page_selector, " .geneset-filter-actions {
-        display: flex;
-        align-items: center;
-        justify-content: space-between;
-        gap: 12px;
-        flex-wrap: wrap;
-        margin-bottom: 12px;
-      }
-
-      ", page_selector, " .geneset-status {
-        display: inline-flex;
-        align-items: center;
-        gap: 8px;
-        padding: 8px 12px;
-        border-radius: 999px;
-        font-size: 13px;
-        font-weight: 600;
-      }
-
-      ", page_selector, " .geneset-status-pending {
-        background: #eef3f7;
-        color: #4b647e;
-      }
-
-      ", page_selector, " .geneset-status-ready {
-        background: #e7f5ec;
-        color: #21663c;
-      }
-
-      ", page_selector, " .geneset-summary-text {
-        margin-top: 10px;
-        margin-bottom: 0;
-        color: #3f5873;
-        font-size: 13px;
-      }
-    "))),
-    
-    div(
-      id = ns("annotate_page"),
-      
-      div(
-        class = "annotate-hero",
-        tags$h2("Annotate Signatures"),
-        tags$p(
-          "Configure an enrichment analysis, choose a geneset collection, review your selections, and run hypeR from a single workflow."
-        )
-      ),
-      
-      fluidRow(
-        column(
-          width = 4,
-          
-          div(
-            class = "annotate-card",
-            span(class = "annotate-step-label", "Step 1"),
-            tags$h3("Analysis Setup"),
-            textInput(
-              ns("experiment_label"),
-              "Experiment Label",
-              placeholder = "Example: Knockout Experiment"
-            ),
-            radioButtons(
-              ns("enrichment_type"),
-              "Enrichment Method",
-              choices = c(
-                "Hypergeometric" = "hypergeo",
-                "KS Test" = "kstest",
-                "GSEA" = "gsea",
-                "GEM Hypergeometric" = "gem_hypergeo",
-                "GEM Weighted" = "gem_weighted"
-              ),
-              inline = FALSE
-            ),
-            helpText(
-              "Hypergeometric uses feature lists. KS Test and GSEA expect ranked signatures. GEM modes map metabolite signatures to genes before enrichment."
-            ),
-            uiOutput(ns("gem_options")),
-            numericInput(
-              ns("enrichment_thresh"),
-              "FDR Threshold",
-              value = 0.05,
-              min = 0,
-              max = 1,
-              step = 0.01
-            ),
-            numericInput(
-              ns("enrichment_bg"),
-              "Background Gene Count",
-              value = 36000,
-              min = 1,
-              step = 100
-            )
-          ),
-          
-          div(
-            class = "annotate-card",
-            span(class = "annotate-step-label", "Step 2"),
-            tags$h3("Geneset Selection"),
-            tags$p(
-              "Use the filter set below to define the genesets included in this enrichment run."
-            ),
-            selectInput(
-              ns("species"),
-              "Species",
-              choices = msigdbr::msigdbr_species()$species_name,
-              selected = "Homo sapiens"
-            ),
-            genesets_hypeR_UI(ns("genesets"))
-          )
-        ),
-        
-        column(
-          width = 8,
-          
-          div(
-            class = "annotate-card",
-            span(class = "annotate-step-label", "Step 3"),
-            tags$h3("Select Signatures"),
-            tags$p(
-              "Choose up to 10 signatures from the repository, then add them to the analysis."
-            ),
-            DT::DTOutput(ns("signature_hypeR")),
-            div(
-              class = "annotate-actions",
-              actionButton(
-                ns("signature_add"),
-                "Add Selected Signatures",
-                class = "btn-primary"
-              )
-            ),
-            div(
-              class = "annotate-feedback",
-              uiOutput(ns("signature_feedback"))
-            )
-          ),
-          
-          div(
-            class = "annotate-card",
-            span(class = "annotate-step-label", "Step 4"),
-            tags$h3("Review and Run"),
-            uiOutput(ns("analysis_summary")),
-            div(
-              class = "annotate-actions",
-              actionButton(
-                ns("enrichment_do"),
-                "Run Enrichment",
-                class = "btn-primary"
-              ),
-              actionButton(
-                ns("experiment_reset"),
-                "New Experiment",
-                class = "btn-default"
-              )
-            )
-          ),
-          
-          div(
-            class = "annotate-card",
-            tags$h3("Current Selection"),
-            uiOutput(ns("signature_preview"))
-          )
-        )
-      ),
-      
-      div(
-        class = "annotate-card",
-        div(
-          class = "annotate-results-header",
-          div(
-            tagList(
-              span(class = "annotate-step-label", "Results"),
-              tags$h3("Experiment Results")
-            )
-          ),
-          div(
-            class = "annotate-results-actions",
-            downloadButton(ns("generate_report"), "Export Analysis Bundle"),
-            downloadButton(ns("export_hyp"), "Export Hype Object")
-          )
-        ),
-        uiOutput(ns("enrichment"))
-      )
-    )
-  )
-}
-
-
-hype_dotplot_data <- function(hyp, fdr_threshold, top = 30, abrv = 50) {
-  if (is.null(fdr_threshold) || length(fdr_threshold) == 0 || is.na(fdr_threshold)) {
-    fdr_threshold <- 1
-  }
-  
-  empty_df <- data.frame(
-    signature = character(),
-    label = character(),
-    fdr = numeric(),
-    geneset_size = numeric(),
-    stringsAsFactors = FALSE
-  )
-  
-  hyp_entries <- if (methods::is(hyp, "multihyp")) {
-    hyp$data
-  } else if (is.list(hyp) && all(c("info", "data") %in% names(hyp))) {
-    list(Enrichment = hyp)
-  } else if (is.list(hyp) && length(hyp) > 0 && all(vapply(hyp, function(x) is.list(x) && all(c("info", "data") %in% names(x)), logical(1)))) {
-    hyp
-  } else {
-    list(Enrichment = hyp)
-  }
-  
-  if (is.null(names(hyp_entries)) || any(!nzchar(names(hyp_entries)))) {
-    names(hyp_entries) <- paste("Signature", seq_along(hyp_entries))
-  }
-  
-  plot_dfs <- lapply(seq_along(hyp_entries), function(i) {
-    hyp_entry <- hyp_entries[[i]]
-    hyp_df <- if (is.data.frame(hyp_entry)) hyp_entry else hyp_entry$data
-    
-    if (is.null(hyp_df) || !is.data.frame(hyp_df) || nrow(hyp_df) == 0) {
-      return(NULL)
-    }
-    
-    if (!all(c("label", "fdr") %in% names(hyp_df))) {
-      return(NULL)
-    }
-    
-    hyp_df$fdr <- suppressWarnings(as.numeric(hyp_df$fdr))
-    hyp_df <- hyp_df[!is.na(hyp_df$fdr) & hyp_df$fdr <= fdr_threshold, , drop = FALSE]
-    
-    if (nrow(hyp_df) == 0) {
-      return(NULL)
-    }
-    
-    geneset_size <- rep(1, nrow(hyp_df))
-    if ("geneset" %in% names(hyp_df)) {
-      geneset_size <- suppressWarnings(as.numeric(hyp_df$geneset))
-      geneset_size[is.na(geneset_size) | geneset_size <= 0] <- 1
-    }
-    
-    data.frame(
-      signature = names(hyp_entries)[[i]],
-      label = substr(as.character(hyp_df$label), 1, abrv),
-      fdr = hyp_df$fdr,
-      geneset_size = geneset_size,
-      stringsAsFactors = FALSE
-    )
-  })
-  
-  plot_dfs <- plot_dfs[!vapply(plot_dfs, is.null, logical(1))]
-  
-  if (length(plot_dfs) == 0) {
-    return(empty_df)
-  }
-  
-  plot_df <- do.call(rbind, plot_dfs)
-  label_rank <- stats::aggregate(fdr ~ label, data = plot_df, FUN = min)
-  label_rank <- label_rank[order(label_rank$fdr), , drop = FALSE]
-  top_labels <- head(label_rank$label, top)
-  plot_df <- plot_df[plot_df$label %in% top_labels, , drop = FALSE]
-  plot_df[order(plot_df$fdr), , drop = FALSE]
-}
-
-
-build_dotplot_figure <- function(plot_df, title = "") {
-  ggplot2::ggplot(
-    plot_df,
-    ggplot2::aes(
-      x = signature_label,
-      y = label,
-      color = fdr_plot,
-      size = geneset_size
-    )
-  ) +
-    ggplot2::geom_point(alpha = 0.86) +
-    ggplot2::scale_color_continuous(
-      low = "#E53935",
-      high = "#114357",
-      trans = "log10",
-      guide = ggplot2::guide_colorbar(reverse = TRUE)
-    ) +
-    ggplot2::scale_size_continuous(trans = "log10") +
-    ggplot2::labs(
-      title = title,
-      x = NULL,
-      y = NULL,
-      color = "FDR",
-      size = "Geneset Size"
-    ) +
-    ggplot2::theme_minimal(base_size = 12) +
-    ggplot2::theme(
-      plot.title = ggplot2::element_text(hjust = 0.5, face = "bold"),
-      axis.text.x = ggplot2::element_text(face = "bold"),
-      panel.grid.major.y = ggplot2::element_line(color = "#e6edf3"),
-      panel.grid.minor = ggplot2::element_blank()
-    )
-}
-
-
-build_enrichment_signatures <- function(sig_objs, sig_list) {
-  extract_signature_table <- function(sig_obj) {
-    table_candidates <- list(sig_obj$signature, sig_obj$difexp)
-    
-    for (candidate in table_candidates) {
-      if (is.data.frame(candidate) && nrow(candidate) > 0) {
-        return(candidate)
-      }
-    }
-    
-    NULL
-  }
-  
-  find_first_column <- function(df, candidates) {
-    matched <- candidates[candidates %in% names(df)][1]
-    if (is.na(matched) || !nzchar(matched)) {
-      return(NULL)
-    }
-    matched
-  }
-  
-  build_group_component <- function(group_label, suffix = NULL) {
-    clean_group <- if (is.null(group_label) || is.na(group_label) || !nzchar(group_label)) {
-      "All Features"
-    } else {
-      group_label
-    }
-    
-    if (is.null(suffix) || !nzchar(suffix)) {
-      return(clean_group)
-    }
-    
-    if (identical(clean_group, "All Features")) {
-      return(suffix)
-    }
-    
-    paste0(clean_group, "_", suffix)
-  }
-  
-  recover_symbol_column <- function(signature_df, sig_obj, symbol_col) {
-    if (!is.null(symbol_col)) {
-      return(list(data = signature_df, symbol_col = symbol_col))
-    }
-    
-    difexp_df <- sig_obj$difexp
-    if (!is.data.frame(difexp_df) || nrow(difexp_df) == 0) {
-      return(list(data = signature_df, symbol_col = NULL))
-    }
-    
-    difexp_symbol_col <- find_first_column(
-      difexp_df,
-      c("symbol", "gene_symbol", "feature_name", "gene", "gene_name")
-    )
-    if (is.null(difexp_symbol_col)) {
-      return(list(data = signature_df, symbol_col = NULL))
-    }
-    
-    map_col <- NULL
-    if ("probe_id" %in% names(signature_df) && "probe_id" %in% names(difexp_df)) {
-      map_col <- "probe_id"
-    } else if ("feature_name" %in% names(signature_df) && "feature_name" %in% names(difexp_df)) {
-      map_col <- "feature_name"
-    }
-    
-    if (is.null(map_col)) {
-      return(list(data = signature_df, symbol_col = NULL))
-    }
-    
-    key_values <- as.character(difexp_df[[map_col]])
-    symbol_values <- as.character(difexp_df[[difexp_symbol_col]])
-    valid <- !is.na(key_values) & nzchar(key_values) & !is.na(symbol_values) & nzchar(symbol_values)
-    
-    if (!any(valid)) {
-      return(list(data = signature_df, symbol_col = NULL))
-    }
-    
-    symbol_map <- stats::setNames(symbol_values[valid], key_values[valid])
-    signature_keys <- as.character(signature_df[[map_col]])
-    recovered_symbols <- unname(symbol_map[signature_keys])
-    
-    if (all(is.na(recovered_symbols) | !nzchar(recovered_symbols))) {
-      return(list(data = signature_df, symbol_col = NULL))
-    }
-    
-    signature_df$symbol <- recovered_symbols
-    list(data = signature_df, symbol_col = "symbol")
-  }
-  
-  empty_result <- list(
-    vectors = list(),
-    metadata = data.frame(
-      signature = character(),
-      signature_name = character(),
-      group_label = character(),
-      signature_order = numeric(),
-      group_order = numeric(),
-      stringsAsFactors = FALSE
-    )
-  )
-  
-  if (length(sig_objs) == 0 || length(sig_list) == 0) {
-    return(empty_result)
-  }
-  
-  sig_names <- vapply(sig_list, `[[`, character(1), "signature_name")
-  vectors <- list()
-  metadata <- vector("list", length(sig_objs))
-  metadata_idx <- 0
-  
-  for (i in seq_along(sig_objs)) {
-    sig_obj <- sig_objs[[i]]
-    sig_name <- sig_names[[i]]
-    
-    signature_df <- extract_signature_table(sig_obj)
-    if (is.null(signature_df)) {
-      next
-    }
-    
-    symbol_col <- find_first_column(
-      signature_df,
-      c("symbol", "gene_symbol", "feature_name", "gene", "gene_name")
-    )
-    if (identical(symbol_col, "feature_name")) {
-      recovered <- recover_symbol_column(signature_df, sig_obj, NULL)
-      signature_df <- recovered$data
-      if (!is.null(recovered$symbol_col)) {
-        symbol_col <- recovered$symbol_col
-      }
-    } else if (is.null(symbol_col)) {
-      recovered <- recover_symbol_column(signature_df, sig_obj, symbol_col)
-      signature_df <- recovered$data
-      symbol_col <- recovered$symbol_col
-    }
-    
-    if (is.null(symbol_col)) {
-      next
-    }
-    
-    signature_df$symbol <- as.character(signature_df[[symbol_col]])
-    signature_df <- signature_df[!is.na(signature_df$symbol) & nzchar(signature_df$symbol), , drop = FALSE]
-    
-    if (nrow(signature_df) == 0) {
-      next
-    }
-    
-    if ("group_label" %in% names(signature_df)) {
-      signature_df$group_label <- as.character(signature_df$group_label)
-      signature_df$group_label[is.na(signature_df$group_label) | !nzchar(signature_df$group_label)] <- "All Features"
-    } else {
-      signature_df$group_label <- "All Features"
-    }
-    
-    score_col <- find_first_column(signature_df, c("score", "t_stat", "stat", "t", "logfc", "logFC"))
-    has_score <- !is.null(score_col)
-    if (has_score) {
-      signature_df$score_value <- suppressWarnings(as.numeric(signature_df[[score_col]]))
-      has_score <- any(!is.na(signature_df$score_value))
-    }
-    
-    group_levels <- unique(signature_df$group_label)
-    group_order_index <- 0
-    
-    for (group_label in group_levels) {
-      group_df <- signature_df[signature_df$group_label == group_label, , drop = FALSE]
-      
-      if (!has_score) {
-        group_symbols <- unique(group_df$symbol)
-        if (length(group_symbols) == 0) {
-          next
-        }
-        
-        group_component <- build_group_component(group_label)
-        signature_key <- sprintf("%s | %s", sig_name, group_component)
-        vectors[[signature_key]] <- group_symbols
-        
-        group_order_index <- group_order_index + 1
-        metadata_idx <- metadata_idx + 1
-        metadata[[metadata_idx]] <- data.frame(
-          signature = signature_key,
-          signature_name = sig_name,
-          group_label = group_component,
-          signature_order = i,
-          group_order = group_order_index,
-          stringsAsFactors = FALSE
-        )
-        next
-      }
-      
-      direction_specs <- list(
-        list(suffix = "up", keep = !is.na(group_df$score_value) & group_df$score_value >= 0),
-        list(suffix = "dn", keep = !is.na(group_df$score_value) & group_df$score_value < 0)
-      )
-      
-      for (direction in direction_specs) {
-        group_symbols <- unique(group_df$symbol[direction$keep])
-        if (length(group_symbols) == 0) {
-          next
-        }
-        
-        group_component <- build_group_component(group_label, direction$suffix)
-        signature_key <- sprintf("%s | %s", sig_name, group_component)
-        vectors[[signature_key]] <- group_symbols
-        
-        group_order_index <- group_order_index + 1
-        metadata_idx <- metadata_idx + 1
-        metadata[[metadata_idx]] <- data.frame(
-          signature = signature_key,
-          signature_name = sig_name,
-          group_label = group_component,
-          signature_order = i,
-          group_order = group_order_index,
-          stringsAsFactors = FALSE
-        )
-      }
-    }
-  }
-  
-  metadata <- metadata[seq_len(metadata_idx)]
-  metadata_df <- if (length(metadata) > 0) do.call(rbind, metadata) else empty_result$metadata
-  
-  list(
-    vectors = vectors,
-    metadata = metadata_df
-  )
-}
-
-
-build_ranked_enrichment_signatures <- function(sig_objs, sig_list, mode = c("ks", "gsea")) {
-  find_first_column <- function(df, candidates) {
-    matched <- candidates[candidates %in% names(df)][1]
-    if (is.na(matched) || !nzchar(matched)) {
-      return(NULL)
-    }
-    matched
-  }
-  
-  build_group_component <- function(group_label, suffix = NULL) {
-    clean_group <- if (is.null(group_label) || is.na(group_label) || !nzchar(group_label)) {
-      "All Features"
-    } else {
-      group_label
-    }
-    
-    if (is.null(suffix) || !nzchar(suffix)) {
-      return(clean_group)
-    }
-    
-    if (identical(clean_group, "All Features")) {
-      return(suffix)
-    }
-    
-    paste0(clean_group, "_", suffix)
-  }
-  
-  mode <- match.arg(mode)
-  empty_result <- list(
-    vectors = list(),
-    metadata = data.frame(
-      signature = character(),
-      signature_name = character(),
-      group_label = character(),
-      signature_order = numeric(),
-      group_order = numeric(),
-      stringsAsFactors = FALSE
-    )
-  )
-  
-  if (length(sig_objs) == 0 || length(sig_list) == 0) {
-    return(empty_result)
-  }
-  
-  sig_names <- vapply(sig_list, `[[`, character(1), "signature_name")
-  rank_candidates <- c("score", "t_stat", "stat", "t", "logfc", "logFC")
-  vectors <- list()
-  metadata <- vector("list", length(sig_objs) * 4)
-  metadata_idx <- 0
-  
-  for (i in seq_along(sig_objs)) {
-    sig_obj <- sig_objs[[i]]
-    sig_name <- sig_names[[i]]
-    difexp_df <- sig_obj$difexp
-    
-    if (is.null(difexp_df) || !is.data.frame(difexp_df) || nrow(difexp_df) == 0) {
-      next
-    }
-    
-    symbol_col <- find_first_column(
-      difexp_df,
-      c("symbol", "gene_symbol", "feature_name", "gene", "gene_name")
-    )
-    if (is.null(symbol_col)) {
-      next
-    }
-    
-    rank_col <- find_first_column(difexp_df, rank_candidates)
-    if (is.null(rank_col)) {
-      next
-    }
-    
-    difexp_df$symbol <- as.character(difexp_df[[symbol_col]])
-    difexp_df$rank_value <- suppressWarnings(as.numeric(difexp_df[[rank_col]]))
-    difexp_df <- difexp_df[!is.na(difexp_df$symbol) & nzchar(difexp_df$symbol) & !is.na(difexp_df$rank_value), , drop = FALSE]
-    
-    if (nrow(difexp_df) == 0) {
-      next
-    }
-    
-    if (identical(mode, "gsea")) {
-      rank_df <- difexp_df[, c("symbol", "rank_value"), drop = FALSE]
-      rank_df <- rank_df[order(-abs(rank_df$rank_value)), , drop = FALSE]
-      rank_df <- rank_df[!duplicated(rank_df$symbol), , drop = FALSE]
-      
-      if (nrow(rank_df) == 0) {
-        next
-      }
-      
-      ordered_df <- rank_df[order(rank_df$rank_value, decreasing = TRUE), , drop = FALSE]
-      ranked_signature <- stats::setNames(ordered_df$rank_value, ordered_df$symbol)
-      
-      if (length(ranked_signature) == 0) {
-        next
-      }
-      
-      signature_key <- sprintf("%s | Ranked", sig_name)
-      vectors[[signature_key]] <- ranked_signature
-      
-      metadata_idx <- metadata_idx + 1
-      metadata[[metadata_idx]] <- data.frame(
-        signature = signature_key,
-        signature_name = sig_name,
-        group_label = "Ranked",
-        signature_order = i,
-        group_order = 1,
-        stringsAsFactors = FALSE
-      )
-    } else {
-      if ("group_label" %in% names(difexp_df)) {
-        difexp_df$group_label <- as.character(difexp_df$group_label)
-        difexp_df$group_label[is.na(difexp_df$group_label) | !nzchar(difexp_df$group_label)] <- "All Features"
-      } else {
-        difexp_df$group_label <- "All Features"
-      }
-      
-      group_levels <- unique(difexp_df$group_label)
-      group_order_index <- 0
-      direction_specs <- list(
-        list(suffix = "up", decreasing = TRUE),
-        list(suffix = "dn", decreasing = FALSE)
-      )
-      
-      for (group_label in group_levels) {
-        group_df <- difexp_df[difexp_df$group_label == group_label, , drop = FALSE]
-        rank_df <- group_df[, c("symbol", "rank_value"), drop = FALSE]
-        rank_df <- rank_df[order(-abs(rank_df$rank_value)), , drop = FALSE]
-        rank_df <- rank_df[!duplicated(rank_df$symbol), , drop = FALSE]
-        
-        if (nrow(rank_df) == 0) {
-          next
-        }
-        
-        for (direction in direction_specs) {
-          ordered_df <- rank_df[order(rank_df$rank_value, decreasing = direction$decreasing), , drop = FALSE]
-          ranked_signature <- stats::setNames(ordered_df$rank_value, ordered_df$symbol)
-          
-          if (length(ranked_signature) == 0) {
-            next
-          }
-          
-          group_component <- build_group_component(group_label, direction$suffix)
-          signature_key <- sprintf("%s | %s", sig_name, group_component)
-          vectors[[signature_key]] <- ranked_signature
-          
-          group_order_index <- group_order_index + 1
-          metadata_idx <- metadata_idx + 1
-          metadata[[metadata_idx]] <- data.frame(
-            signature = signature_key,
-            signature_name = sig_name,
-            group_label = group_component,
-            signature_order = i,
-            group_order = group_order_index,
-            stringsAsFactors = FALSE
-          )
-        }
-      }
-    }
-  }
-  
-  metadata <- metadata[seq_len(metadata_idx)]
-  metadata_df <- if (length(metadata) > 0) do.call(rbind, metadata) else empty_result$metadata
-  
-  list(
-    vectors = vectors,
-    metadata = metadata_df
-  )
-}
-
-
-extract_hyp_results_table <- function(hyp) {
-  if (inherits(hyp, "multihyp")) {
-    result_list <- Map(function(signature_name, hyp_obj) {
-      df <- hyp_obj$data
-      if (is.null(df) || !is.data.frame(df) || nrow(df) == 0) {
-        return(NULL)
-      }
-      
-      df$signature <- signature_name
-      df
-    }, names(hyp$data), hyp$data)
-    
-    result_list <- result_list[!vapply(result_list, is.null, logical(1))]
-    
-    if (length(result_list) == 0) {
-      return(data.frame())
-    }
-    
-    return(do.call(rbind, result_list))
-  }
-  
-  if (is.list(hyp) && all(c("info", "data") %in% names(hyp))) {
-    df <- hyp$data
-    if (is.null(df) || !is.data.frame(df)) {
-      return(data.frame())
-    }
-    
-    if (!"signature" %in% names(df) || all(is.na(df$signature)) || !any(nzchar(as.character(df$signature)))) {
-      df$signature <- "Signature"
-    }
-    return(df)
-  }
-  
-  if (is.list(hyp) && length(hyp) > 0 && all(vapply(hyp, function(x) is.list(x) && all(c("info", "data") %in% names(x)), logical(1)))) {
-    result_list <- Map(function(signature_name, hyp_obj) {
-      df <- hyp_obj$data
-      if (is.null(df) || !is.data.frame(df) || nrow(df) == 0) {
-        return(NULL)
-      }
-      
-      df$signature <- signature_name
-      df
-    }, names(hyp), hyp)
-    
-    result_list <- result_list[!vapply(result_list, is.null, logical(1))]
-    
-    if (length(result_list) == 0) {
-      return(data.frame())
-    }
-    
-    return(do.call(rbind, result_list))
-  }
-  
-  df <- hyp$data
-  if (is.null(df) || !is.data.frame(df)) {
-    return(data.frame())
-  }
-  
-  if (!"signature" %in% names(df) || all(is.na(df$signature)) || !any(nzchar(as.character(df$signature)))) {
-    df$signature <- "Signature"
-  }
-  df
-}
-
-
-hypergem_available <- function() {
-  isTRUE(getOption("sigrepo.hypergem_available", FALSE)) ||
-    "hypeR.GEM" %in% loadedNamespaces() ||
-    requireNamespace("hypeR.GEM", quietly = TRUE)
-}
-
-
-hypergem_export <- function(name) {
-  getExportedValue("hypeR.GEM", name)
-}
-
-
-build_gem_enrichment_signatures <- function(sig_objs, sig_list, reference_key = "refmet_name") {
-  empty_result <- list(
-    signatures = list(),
-    metadata = data.frame(
-      signature = character(),
-      signature_name = character(),
-      group_label = character(),
-      signature_order = numeric(),
-      group_order = numeric(),
-      stringsAsFactors = FALSE
-    )
-  )
-  
-  if (length(sig_objs) == 0 || length(sig_list) == 0) {
-    return(empty_result)
-  }
-  
-  sig_names <- vapply(sig_list, `[[`, character(1), "signature_name")
-  signatures <- list()
-  metadata <- vector("list", length(sig_objs) * 4)
-  metadata_idx <- 0
-  
-  for (i in seq_along(sig_objs)) {
-    sig_obj <- sig_objs[[i]]
-    sig_name <- sig_names[[i]]
-    signature_df <- sig_obj$signature
-    
-    if (!is.data.frame(signature_df) || nrow(signature_df) == 0) {
-      next
-    }
-    
-    if (!reference_key %in% names(signature_df)) {
-      next
-    }
-    
-    signature_df <- signature_df[!is.na(signature_df[[reference_key]]) & nzchar(as.character(signature_df[[reference_key]])), , drop = FALSE]
-    if (nrow(signature_df) == 0) {
-      next
-    }
-    
-    if ("group_label" %in% names(signature_df)) {
-      signature_df$group_label <- as.character(signature_df$group_label)
-      signature_df$group_label[is.na(signature_df$group_label) | !nzchar(signature_df$group_label)] <- "All Features"
-    } else {
-      signature_df$group_label <- "All Features"
-    }
-    
-    score_candidates <- c("score", "logfc", "logFC")
-    score_col <- score_candidates[score_candidates %in% names(signature_df)][1]
-    has_score <- !is.na(score_col) && nzchar(score_col)
-    if (has_score) {
-      signature_df$score_value <- suppressWarnings(as.numeric(signature_df[[score_col]]))
-      has_score <- any(!is.na(signature_df$score_value))
-    }
-    
-    group_levels <- unique(signature_df$group_label)
-    group_order_index <- 0
-    
-    for (group_label in group_levels) {
-      group_df <- signature_df[signature_df$group_label == group_label, , drop = FALSE]
-      
-      if (!has_score) {
-        signature_key <- sprintf("%s | %s", sig_name, group_label)
-        signatures[[signature_key]] <- group_df
-        
-        group_order_index <- group_order_index + 1
-        metadata_idx <- metadata_idx + 1
-        metadata[[metadata_idx]] <- data.frame(
-          signature = signature_key,
-          signature_name = sig_name,
-          group_label = group_label,
-          signature_order = i,
-          group_order = group_order_index,
-          stringsAsFactors = FALSE
-        )
-        next
-      }
-      
-      direction_specs <- list(
-        list(suffix = "up", keep = !is.na(group_df$score_value) & group_df$score_value >= 0),
-        list(suffix = "dn", keep = !is.na(group_df$score_value) & group_df$score_value < 0)
-      )
-      
-      for (direction in direction_specs) {
-        split_df <- group_df[direction$keep, , drop = FALSE]
-        if (nrow(split_df) == 0) {
-          next
-        }
-        
-        group_component <- if (identical(group_label, "All Features")) {
-          direction$suffix
-        } else {
-          paste0(group_label, "_", direction$suffix)
-        }
-        
-        signature_key <- sprintf("%s | %s", sig_name, group_component)
-        signatures[[signature_key]] <- split_df
-        
-        group_order_index <- group_order_index + 1
-        metadata_idx <- metadata_idx + 1
-        metadata[[metadata_idx]] <- data.frame(
-          signature = signature_key,
-          signature_name = sig_name,
-          group_label = group_component,
-          signature_order = i,
-          group_order = group_order_index,
-          stringsAsFactors = FALSE
-        )
-      }
-    }
-  }
-  
-  metadata <- metadata[seq_len(metadata_idx)]
-  metadata_df <- if (length(metadata) > 0) do.call(rbind, metadata) else empty_result$metadata
-  
-  list(
-    signatures = signatures,
-    metadata = metadata_df
-  )
-}
-
-
-compute_gsea_curve_data <- function(ranked_signature, geneset_genes, power = 1) {
-  signature_scores <- as.numeric(ranked_signature)
-  signature_genes <- names(ranked_signature)
-  
-  valid <- !is.na(signature_scores) & !is.na(signature_genes) & nzchar(signature_genes)
-  signature_scores <- signature_scores[valid]
-  signature_genes <- signature_genes[valid]
-  
-  if (length(signature_scores) == 0) {
-    stop("Ranked signature did not contain any valid values.", call. = FALSE)
-  }
-  
-  geneset_genes <- unique(as.character(geneset_genes))
-  geneset_genes <- geneset_genes[!is.na(geneset_genes) & nzchar(geneset_genes)]
-  
-  hit_index <- which(signature_genes %in% geneset_genes)
-  if (length(hit_index) == 0) {
-    stop("Selected geneset has no overlap with the ranked signature.", call. = FALSE)
-  }
-  
-  hit_weights <- abs(signature_scores[hit_index])^power
-  weight_sum <- sum(hit_weights)
-  if (!is.finite(weight_sum) || weight_sum == 0) {
-    hit_weights <- rep(1, length(hit_index))
-    weight_sum <- sum(hit_weights)
-  }
-  
-  n_total <- length(signature_scores)
-  n_miss <- n_total - length(hit_index)
-  miss_penalty <- if (n_miss > 0) 1 / n_miss else 0
-  
-  increments <- rep(-miss_penalty, n_total)
-  increments[hit_index] <- hit_weights / weight_sum
-  running_score <- cumsum(increments)
-  
-  max_idx <- which.max(running_score)
-  min_idx <- which.min(running_score)
-  
-  if (abs(running_score[max_idx]) >= abs(running_score[min_idx])) {
-    es_index <- max_idx
-    es_score <- running_score[max_idx]
-    es_direction <- "positive"
-    leading_edge_hits <- hit_index[hit_index <= es_index]
-    trailing_edge_hits <- hit_index[hit_index > es_index]
-  } else {
-    es_index <- min_idx
-    es_score <- running_score[min_idx]
-    es_direction <- "negative"
-    leading_edge_hits <- hit_index[hit_index >= es_index]
-    trailing_edge_hits <- hit_index[hit_index < es_index]
-  }
-  
-  curve_df <- data.frame(
-    position = seq_len(n_total),
-    gene = signature_genes,
-    score = signature_scores,
-    running_score = running_score,
-    hit = seq_len(n_total) %in% hit_index,
-    edge_group = ifelse(
-      seq_len(n_total) %in% leading_edge_hits,
-      "Leading Edge",
-      ifelse(seq_len(n_total) %in% trailing_edge_hits, "Trailing Edge", "Other")
-    ),
-    stringsAsFactors = FALSE
-  )
-  
-  list(
-    curve = curve_df,
-    hit_index = hit_index,
-    es_index = es_index,
-    es_score = es_score,
-    es_direction = es_direction,
-    leading_edge_genes = signature_genes[leading_edge_hits],
-    trailing_edge_genes = signature_genes[trailing_edge_hits]
-  )
-}
-
-
-build_gsea_curve_figure <- function(curve_info) {
-  curve_df <- curve_info$curve
-  
-  hit_df <- curve_df[curve_df$hit, , drop = FALSE]
-  hit_df$hit_height <- ifelse(hit_df$edge_group == "Leading Edge", -0.08, -0.14)
-  
-  ggplot2::ggplot(curve_df, ggplot2::aes(x = position, y = running_score)) +
-    ggplot2::geom_hline(yintercept = 0, color = "#aab7c4", linewidth = 0.4) +
-    ggplot2::geom_line(color = "#0f4d7c", linewidth = 1) +
-    ggplot2::geom_vline(
-      xintercept = curve_info$es_index,
-      color = "#d04a02",
-      linetype = "dashed",
-      linewidth = 0.5
-    ) +
-    ggplot2::geom_segment(
-      data = hit_df,
-      ggplot2::aes(
-        x = position,
-        xend = position,
-        y = hit_height,
-        yend = 0,
-        color = edge_group
-      ),
-      inherit.aes = FALSE,
-      linewidth = 0.45,
-      show.legend = TRUE
-    ) +
-    ggplot2::scale_color_manual(
-      values = c("Leading Edge" = "#d04a02", "Trailing Edge" = "#6c8aa5", "Other" = "#6c8aa5"),
-      breaks = c("Leading Edge", "Trailing Edge"),
-      name = NULL
-    ) +
-    ggplot2::labs(
-      title = curve_info$geneset_name,
-      subtitle = sprintf(
-        "%s | ES = %.3f | Leading edge = %s genes | Trailing edge = %s genes",
-        curve_info$signature_key,
-        curve_info$es_score,
-        length(curve_info$leading_edge_genes),
-        length(curve_info$trailing_edge_genes)
-      ),
-      x = "Ranked Features",
-      y = "Running Enrichment Score"
-    ) +
-    ggplot2::coord_cartesian(clip = "off") +
-    ggplot2::theme_minimal(base_size = 12) +
-    ggplot2::theme(
-      plot.title = ggplot2::element_text(face = "bold"),
-      plot.subtitle = ggplot2::element_text(color = "#4e6782"),
-      panel.grid.minor = ggplot2::element_blank(),
-      legend.position = "top"
-    )
-}
-
-
-flatten_report_value <- function(value) {
-  if (is.null(value) || length(value) == 0) {
-    return(NA_character_)
-  }
-  
-  if (is.list(value)) {
-    named_parts <- names(value)
-    if (is.null(named_parts) || all(is.na(named_parts)) || !any(nzchar(named_parts))) {
-      return(paste(vapply(value, flatten_report_value, character(1)), collapse = "; "))
-    }
-    part_values <- mapply(
-      function(name, item) sprintf("%s=%s", name, flatten_report_value(item)),
-      named_parts,
-      value,
-      SIMPLIFY = TRUE,
-      USE.NAMES = FALSE
-    )
-    return(paste(part_values, collapse = "; "))
-  }
-  
-  pasted <- paste(as.character(value), collapse = ", ")
-  if (!nzchar(pasted)) {
-    NA_character_
-  } else {
-    pasted
-  }
-}
-
-
-`%||%` <- function(x, y) {
-  if (is.null(x) || length(x) == 0) y else x
-}
-
-
-build_signature_metadata_table <- function(sig_objs, sig_list) {
-  if (length(sig_objs) == 0 || length(sig_list) == 0) {
-    return(data.frame())
-  }
-  
-  sig_names <- vapply(sig_list, `[[`, character(1), "signature_name")
-  rows <- lapply(seq_along(sig_objs), function(i) {
-    sig_obj <- sig_objs[[i]]
-    metadata <- sig_obj$metadata
-    if (is.null(metadata)) {
-      metadata <- list()
-    }
-    
-    data.frame(
-      signature_name = sig_names[[i]],
-      signature_id = flatten_report_value(metadata$signature_id),
-      organism = flatten_report_value(metadata$organism),
-      assay_type = flatten_report_value(metadata$assay_type),
-      phenotype = flatten_report_value(metadata$phenotype),
-      # No direction_type fallback here (unlike the Shiny app's copy of this
-      # function in SigRepo_Server's annotate_module.R): this function's
-      # inputs are OmicSignature objects built by this same package, and
-      # checkOmicSignature() hard-fails on any object still carrying
-      # direction_type, so metadata$type is guaranteed to already be
-      # normalized by the time it reaches here. Deliberately collapsed to a
-      # single key rather than kept as belt-and-braces.
-      type = flatten_report_value(metadata$type),
-      description = flatten_report_value(metadata$description),
-      score_cutoff = flatten_report_value(metadata$score_cutoff),
-      adj_p_cutoff = flatten_report_value(metadata$adj_p_cutoff),
-      logfc_cutoff = flatten_report_value(metadata$logfc_cutoff),
-      p_value_cutoff = flatten_report_value(metadata$p_value_cutoff),
-      keywords = flatten_report_value(metadata$keywords),
-      sample_type = flatten_report_value(metadata$sample_type),
-      # Same reasoning as `type` above: no platform_name fallback needed.
-      platform = flatten_report_value(metadata$platform),
-      covariates = flatten_report_value(metadata$covariates),
-      author = flatten_report_value(metadata$author %||% metadata$user_name),
-      year = flatten_report_value(metadata$year),
-      others = flatten_report_value(metadata$others),
-      stringsAsFactors = FALSE
-    )
-  })
-  
-  do.call(rbind, rows)
-}
-
-
-sanitize_report_table <- function(df) {
-  if (!is.data.frame(df) || nrow(df) == 0) {
-    return(df)
-  }
-  
-  out <- df
-  for (col_name in names(out)) {
-    column <- out[[col_name]]
-    if (is.list(column)) {
-      out[[col_name]] <- vapply(column, flatten_report_value, character(1))
-    }
-  }
-  out
-}
-
-
-build_report_settings_table <- function(experiment_label, context, geneset_names, fdr_threshold, background) {
-  method_label <- if (is.null(context$method)) {
-    "Unknown"
-  } else {
-    dplyr::recode(
-      context$method,
-      hypergeo = "Hypergeometric",
-      kstest = "KS Test",
-      gsea = "GSEA",
-      gem_hypergeo = "GEM Hypergeometric",
-      gem_weighted = "GEM Weighted",
-      .default = as.character(context$method)
-    )
-  }
-  
-  data.frame(
-    Setting = c("Experiment", "Method", "Geneset Count", "FDR Threshold", "Background", "Generated"),
-    Value = c(
-      if (nzchar(experiment_label)) experiment_label else "Untitled analysis",
-      method_label,
-      length(geneset_names),
-      as.character(fdr_threshold),
-      as.character(background),
-      format(Sys.time(), "%Y-%m-%d %H:%M:%S %Z")
-    ),
-    stringsAsFactors = FALSE
-  )
-}
-
-
-annotate_module_server <- function(id, signature_db, user_conn_handler) {
-  moduleServer(id, function(input, output, session) {
-    max_signature_count <- 10
-    active_signatures <- reactiveVal(list())
-    run_feedback <- reactiveVal(NULL)
-    hyp_result <- reactiveVal(NULL)
-    enrichment_context <- reactiveVal(NULL)
-    signature_plot_metadata <- reactiveVal(
-      data.frame(
-        signature = character(),
-        signature_name = character(),
-        group_label = character(),
-        stringsAsFactors = FALSE
-      )
-    )
-    
-    output$signature_hypeR <- renderDT({
-      df <- signature_db()
-      
-      DatatableFX(
-        df = df,
-        hidden_columns = c(0, 6, 7, 8, 9, 11, 12, 14, 15, 16, 18, 19, 21, 22, 24, 25, 26),
-        scrollY = "300px",
-        row_selection = "multiple"
-      )
-    }, server = TRUE)
-    
-    genesets <- genesets_hypeR_Server(
-      id = "genesets",
-      species = reactive(input$species),
-      clean = TRUE
-    )
-    
-    output$gem_options <- renderUI({
-      if (!input$enrichment_type %in% c("gem_hypergeo", "gem_weighted")) {
-        return(NULL)
-      }
-      
-      tagList(
-        textInput(
-          session$ns("gem_reference_key"),
-          "Metabolite Reference Column",
-          value = "refmet_name",
-          placeholder = "Example: refmet_name"
-        ),
-        selectInput(
-          session$ns("gem_species"),
-          "GEM Species",
-          choices = c("Human", "Mouse", "Rat", "Zebrafish", "Worm", "Other"),
-          selected = "Human"
-        ),
-        checkboxInput(
-          session$ns("gem_directional"),
-          "Use directional GEM mapping",
-          value = FALSE
-        ),
-        checkboxInput(
-          session$ns("gem_merge"),
-          "Merge compartment-specific metabolites",
-          value = TRUE
-        ),
-        numericInput(
-          session$ns("gem_promiscuous_threshold"),
-          "Promiscuous Metabolite Threshold",
-          value = 500,
-          min = 0,
-          step = 10
-        ),
-        numericInput(
-          session$ns("gem_min_metabolite"),
-          "Minimum Driving Metabolites per Geneset",
-          value = 0,
-          min = 0,
-          step = 1
-        ),
-        if (identical(input$enrichment_type, "gem_weighted")) {
-          textInput(
-            session$ns("gem_weighted_by"),
-            "Weight Column",
-            value = "one_minus_fdr",
-            placeholder = "Example: one_minus_fdr"
-          )
-        } else {
-          NULL
-        },
-        if (!hypergem_available()) {
-          div(
-            class = "alert alert-warning",
-            if (!is.null(getOption("sigrepo.hypergem_error"))) {
-              sprintf("hypeR.GEM could not be loaded: %s", getOption("sigrepo.hypergem_error"))
-            } else {
-              "hypeR.GEM is not currently available in this app environment."
-            }
-          )
-        } else {
-          NULL
-        }
-      )
-    })
-    
-    observeEvent(input$signature_add, {
-      selected_rows <- input$signature_hypeR_rows_selected
-      
-      if (length(selected_rows) == 0) {
-        run_feedback(list(
-          type = "warning",
-          text = "Select at least one signature before adding it to the analysis."
-        ))
-        return()
-      }
-      
-      df <- signature_db()
-      req(!is.null(df))
-      
-      sig_rows <- df[selected_rows, , drop = FALSE]
-      current <- active_signatures()
-      added_count <- 0
-      skipped_limit_count <- 0
-      
-      for (i in seq_len(nrow(sig_rows))) {
-        sig_row <- sig_rows[i, ]
-        key <- sig_row$signature_name
-        
-        if (!key %in% names(current)) {
-          if (length(current) >= max_signature_count) {
-            skipped_limit_count <- skipped_limit_count + 1
-            next
-          }
-          
-          current[[key]] <- list(
-            experiment = input$experiment_label,
-            signature_name = sig_row$signature_name,
-            signature_id = sig_row$signature_id,
-            perturbation = if ("perturbation" %in% names(sig_row)) sig_row$perturbation else NA_character_
-          )
-          added_count <- added_count + 1
-        }
-      }
-      
-      active_signatures(current)
-      hyp_result(NULL)
-      enrichment_context(NULL)
-      signature_plot_metadata(signature_plot_metadata()[0, , drop = FALSE])
-      
-      run_feedback(list(
-        type = if (skipped_limit_count > 0) "warning" else if (added_count > 0) "success" else "info",
-        text = if (skipped_limit_count > 0) {
-          sprintf(
-            "%s signature(s) added. The analysis is limited to %s signatures, so %s selection(s) were skipped.",
-            added_count,
-            max_signature_count,
-            skipped_limit_count
-          )
-        } else if (added_count > 0) {
-          sprintf("%s signature(s) added to the analysis.", added_count)
-        } else {
-          "All selected signatures are already in the current analysis."
-        }
-      ))
-    })
-    
-    observeEvent(input$experiment_reset, {
-      active_signatures(list())
-      hyp_result(NULL)
-      enrichment_context(NULL)
-      run_feedback(NULL)
-      signature_plot_metadata(signature_plot_metadata()[0, , drop = FALSE])
-      
-      updateTextInput(session, "experiment_label", value = "")
-      updateRadioButtons(session, "enrichment_type", selected = "hypergeo")
-      updateNumericInput(session, "enrichment_thresh", value = 0.05)
-      updateNumericInput(session, "enrichment_bg", value = 36000)
-      
-      DT::selectRows(DT::dataTableProxy("signature_hypeR", session = session), NULL)
-      showNotification("Experiment selections and results were reset.", type = "message")
-    })
-    
-    output$signature_feedback <- renderUI({
-      feedback <- run_feedback()
-      if (is.null(feedback)) {
-        return(NULL)
-      }
-      
-      class_name <- switch(
-        feedback$type,
-        success = "alert alert-success",
-        warning = "alert alert-warning",
-        info = "alert alert-info",
-        "alert alert-info"
-      )
-      
-      tags$div(class = class_name, feedback$text)
-    })
-    
-    output$analysis_summary <- renderUI({
-      sig_list <- active_signatures()
-      gsets <- genesets()
-      
-      summary_value <- function(value, empty = "Not set") {
-        if (is.null(value) || identical(value, "") || (length(value) == 0)) empty else as.character(value)
-      }
-      
-      div(
-        class = "annotate-summary-grid",
-        div(
-          class = "annotate-summary-item",
-          tags$strong("Experiment"),
-          tags$span(summary_value(input$experiment_label, "Untitled analysis"))
-        ),
-        div(
-          class = "annotate-summary-item",
-          tags$strong("Method"),
-          tags$span(
-            dplyr::recode(
-              input$enrichment_type,
-              hypergeo = "Hypergeometric",
-              kstest = "KS Test",
-              gsea = "GSEA",
-              gem_hypergeo = "GEM Hypergeometric",
-              gem_weighted = "GEM Weighted"
-            )
-          )
-        ),
-        div(
-          class = "annotate-summary-item",
-          tags$strong("Selected Signatures"),
-          tags$span(sprintf("%s / %s", length(sig_list), max_signature_count))
-        ),
-        div(
-          class = "annotate-summary-item",
-          tags$strong("Selected Genesets"),
-          tags$span(length(gsets))
-        ),
-        div(
-          class = "annotate-summary-item",
-          tags$strong("FDR Threshold"),
-          tags$span(summary_value(input$enrichment_thresh))
-        ),
-        div(
-          class = "annotate-summary-item",
-          tags$strong("Background"),
-          tags$span(summary_value(input$enrichment_bg))
-        )
-      )
-    })
-    
-    output$signature_preview <- renderUI({
-      sig_list <- active_signatures()
-      gsets <- genesets()
-      
-      if (length(sig_list) == 0) {
-        return(
-          div(
-            class = "annotate-empty",
-            "No signatures have been added yet. Select signatures from the table above to start the analysis."
-          )
-        )
-      }
-      
-      sig_names <- vapply(sig_list, `[[`, character(1), "signature_name")
-      df <- signature_db()
-      req(df)
-      
-      selected_df <- df[df$signature_name %in% sig_names, , drop = FALSE]
-      preview_df <- selected_df[, intersect(c("signature_name", "signature_id", "perturbation"), names(selected_df)), drop = FALSE]
-      geneset_names <- names(gsets)
-      
-      tagList(
-        tags$p(
-          "Review the selected signatures and genesets before running enrichment."
-        ),
-        DT::datatable(
-          preview_df,
-          rownames = FALSE,
-          options = list(
-            scrollX = TRUE,
-            pageLength = 5,
-            dom = "tip"
-          ),
-          class = "compact stripe hover"
-        ),
-        tags$hr(),
-        tags$h4("Geneset Collections"),
-        if (length(geneset_names) > 0) {
-          tags$ul(lapply(head(geneset_names, 10), tags$li))
-        } else {
-          div(
-            class = "annotate-empty",
-            "No genesets have been fetched yet. Choose a collection and subcategory, then fetch genesets."
-          )
-        },
-        if (length(geneset_names) > 10) {
-          tags$p(sprintf("Showing 10 of %s genesets selected.", length(geneset_names)))
-        }
-      )
-    })
-    
-    observeEvent(input$enrichment_do, {
-      sig_list <- active_signatures()
-      gsets <- genesets()
-      
-      if (length(sig_list) == 0) {
-        showNotification("Add at least one signature before running enrichment.", type = "error")
-        return()
-      }
-      
-      if (length(gsets) == 0) {
-        showNotification("Fetch at least one geneset collection before running enrichment.", type = "error")
-        return()
-      }
-      
-      sig_ids <- vapply(sig_list, function(sig) as.numeric(sig$signature_id), numeric(1))
-      
-      sig_objs <- SigRepo::getSignature(
-        conn_handler = user_conn_handler(),
-        signature_id = sig_ids
-      )
-      
-      enrichment_method <- input$enrichment_type
-      is_gem_method <- enrichment_method %in% c("gem_hypergeo", "gem_weighted")
-      
-      if (is_gem_method) {
-        if (!hypergem_available()) {
-          showNotification("hypeR.GEM is not available in the current app environment.", type = "error")
-          return()
-        }
-        
-        reference_key <- trimws(input$gem_reference_key)
-        if (!nzchar(reference_key)) {
-          showNotification("Provide a metabolite reference column for GEM enrichment.", type = "error")
-          return()
-        }
-        
-        enrichment_inputs <- build_gem_enrichment_signatures(
-          sig_objs,
-          sig_list,
-          reference_key = reference_key
-        )
-        gem_signatures <- enrichment_inputs$signatures
-        
-        if (length(gem_signatures) == 0) {
-          showNotification(
-            sprintf("No selected signatures contained the required GEM reference column '%s'.", reference_key),
-            type = "error"
-          )
-          return()
-        }
-        
-        signature2gene_fn <- hypergem_export("signature2gene")
-        gem_enrichment_fn <- hypergem_export("enrichment")
-        
-        gem_obj <- signature2gene_fn(
-          signatures = gem_signatures,
-          species = input$gem_species,
-          directional = isTRUE(input$gem_directional),
-          merge = isTRUE(input$gem_merge),
-          reference_key = reference_key,
-          promiscuous_threshold = input$gem_promiscuous_threshold,
-          ensemble_id = FALSE,
-          background = NULL
-        )
-        
-        hyp <- gem_enrichment_fn(
-          hypeR_GEM_obj = gem_obj,
-          genesets = gsets,
-          genesets_name = "Selected Genesets",
-          method = if (identical(enrichment_method, "gem_weighted")) "weighted" else "unweighted",
-          weighted_by = if (!is.null(input$gem_weighted_by) && nzchar(input$gem_weighted_by)) input$gem_weighted_by else "one_minus_fdr",
-          min_metabolite = input$gem_min_metabolite,
-          background = input$enrichment_bg
-        )
-        
-        hyp_result(hyp)
-        enrichment_context(list(
-          method = enrichment_method,
-          test = "gem",
-          engine = "hypeR_GEM",
-          genesets = gsets,
-          gem_reference_key = reference_key
-        ))
-        signature_plot_metadata(enrichment_inputs$metadata)
-        showNotification("GEM enrichment analysis completed.", type = "message")
-      } else {
-        enrichment_test <- dplyr::recode(
-          input$enrichment_type,
-          hypergeo = "hypergeo",
-          kstest = "ks",
-          gsea = "ks"
-        )
-        
-        enrichment_inputs <- if (identical(enrichment_test, "hypergeo")) {
-          build_enrichment_signatures(sig_objs, sig_list)
-        } else if (identical(enrichment_method, "gsea")) {
-          build_ranked_enrichment_signatures(sig_objs, sig_list, mode = "gsea")
-        } else {
-          build_ranked_enrichment_signatures(sig_objs, sig_list, mode = "ks")
-        }
-        signature_vectors <- enrichment_inputs$vectors
-        
-        if (length(signature_vectors) == 0) {
-          showNotification(
-            if (identical(enrichment_test, "hypergeo")) {
-              "No valid signatures were available to run enrichment."
-            } else {
-              "No ranked signatures were available to run KS/GSEA-style enrichment. Check that the signatures contain numeric score columns."
-            },
-            type = "error"
-          )
-          return()
-        }
-        
-        hype_args <- list(
-          signature = signature_vectors,
-          genesets = gsets,
-          test = enrichment_test,
-          background = input$enrichment_bg,
-          fdr = input$enrichment_thresh,
-          plotting = FALSE,
-          quiet = TRUE
-        )
-        
-        if (identical(enrichment_method, "gsea")) {
-          hype_args$absolute <- FALSE
-          hype_args$power <- 1
-        }
-        
-        hyp <- do.call(hypeR::hypeR, hype_args)
-        
-        hyp_result(hyp)
-        enrichment_context(list(
-          method = enrichment_method,
-          test = enrichment_test,
-          engine = "hypeR",
-          signature_vectors = signature_vectors,
-          genesets = gsets
-        ))
-        signature_plot_metadata(enrichment_inputs$metadata)
-        showNotification(
-          if (identical(enrichment_method, "gsea")) {
-            "GSEA-style preranked enrichment completed."
-          } else {
-            "Enrichment analysis completed."
-          },
-          type = "message"
-        )
-      }
-    })
-    
-    dotplot_data <- reactive({
-      hyp <- hyp_result()
-      req(hyp)
-      
-      plot_df <- hype_dotplot_data(hyp, fdr_threshold = input$enrichment_thresh)
-      validate(need(nrow(plot_df) > 0, "No enriched genesets passed the selected FDR threshold."))
-      
-      plot_metadata <- signature_plot_metadata()
-      validate(need(nrow(plot_metadata) > 0, "Signature grouping metadata was not available for plotting."))
-      
-      signature_lookup <- unique(
-        plot_metadata[, c("signature", "signature_name", "group_label", "signature_order", "group_order"), drop = FALSE]
-      )
-      signature_lookup <- signature_lookup[order(signature_lookup$signature_order, signature_lookup$group_order), , drop = FALSE]
-      
-      signature_id_lookup <- unique(signature_lookup[, c("signature_name", "signature_order"), drop = FALSE])
-      signature_id_lookup <- signature_id_lookup[order(signature_id_lookup$signature_order), , drop = FALSE]
-      signature_id_lookup$plot_id <- paste0("S", seq_len(nrow(signature_id_lookup)))
-      
-      signature_lookup <- merge(
-        signature_lookup,
-        signature_id_lookup,
-        by = c("signature_name", "signature_order"),
-        all.x = TRUE,
-        sort = FALSE
-      )
-      signature_lookup <- signature_lookup[order(signature_lookup$signature_order, signature_lookup$group_order), , drop = FALSE]
-      signature_lookup$signature_label <- ifelse(
-        nzchar(signature_lookup$group_label) & signature_lookup$group_label != "All Features",
-        paste(signature_lookup$plot_id, signature_lookup$group_label),
-        signature_lookup$plot_id
-      )
-      
-      plot_df <- merge(plot_df, signature_lookup, by = "signature", all.x = TRUE, sort = FALSE)
-      plot_df$signature_label <- factor(plot_df$signature_label, levels = signature_lookup$signature_label)
-      plot_df$label <- factor(plot_df$label, levels = rev(unique(plot_df$label)))
-      
-      positive_fdr <- plot_df$fdr[plot_df$fdr > 0]
-      min_positive_fdr <- if (length(positive_fdr) > 0) min(positive_fdr, na.rm = TRUE) else .Machine$double.xmin
-      plot_df$fdr_plot <- pmax(plot_df$fdr, min_positive_fdr / 10)
-      
-      list(
-        plot_df = plot_df,
-        signature_lookup = signature_lookup[, c("plot_id", "signature_label", "signature_name", "group_label"), drop = FALSE]
-      )
-    })
-    
-    output$dotplot <- renderPlot({
-      plot_df <- dotplot_data()$plot_df
-      build_dotplot_figure(plot_df, title = input$experiment_label)
-    })
-    
-    output$dotplot_signature_key <- DT::renderDT({
-      key_df <- dotplot_data()$signature_lookup
-      names(key_df) <- c("Signature ID", "Plot Label", "Signature", "Group Label")
-      
-      DT::datatable(
-        key_df,
-        rownames = FALSE,
-        options = list(
-          pageLength = 10,
-          dom = "tip",
-          scrollX = TRUE
-        ),
-        class = "compact stripe hover"
-      )
-    })
-    
-    output$generic_results_table <- DT::renderDT({
-      hyp <- hyp_result()
-      req(hyp)
-      
-      results_df <- extract_hyp_results_table(hyp)
-      validate(need(nrow(results_df) > 0, "No results are available."))
-      
-      DT::datatable(
-        results_df,
-        rownames = FALSE,
-        options = list(
-          pageLength = 15,
-          scrollX = TRUE
-        ),
-        class = "compact stripe hover"
-      )
-    })
-    
-    gsea_detail_signature_choices <- reactive({
-      context <- enrichment_context()
-      req(context)
-      req(identical(context$method, "gsea"))
-      
-      metadata_df <- signature_plot_metadata()
-      req(nrow(metadata_df) > 0)
-      
-      signature_lookup <- unique(
-        metadata_df[, c("signature", "signature_name", "signature_order", "group_label"), drop = FALSE]
-      )
-      signature_lookup <- signature_lookup[order(signature_lookup$signature_order), , drop = FALSE]
-      
-      label_df <- unique(signature_lookup[, c("signature_name", "signature_order"), drop = FALSE])
-      label_df <- label_df[order(label_df$signature_order), , drop = FALSE]
-      label_df$plot_id <- paste0("S", seq_len(nrow(label_df)))
-      
-      signature_lookup <- merge(
-        signature_lookup,
-        label_df,
-        by = c("signature_name", "signature_order"),
-        all.x = TRUE,
-        sort = FALSE
-      )
-      signature_lookup$display_label <- paste(signature_lookup$plot_id, signature_lookup$group_label)
-      
-      stats::setNames(signature_lookup$signature, signature_lookup$display_label)
-    })
-    
-    gsea_results_table <- reactive({
-      context <- enrichment_context()
-      hyp <- hyp_result()
-      req(context, hyp)
-      req(identical(context$method, "gsea"))
-      
-      results_df <- extract_hyp_results_table(hyp)
-      validate(need(nrow(results_df) > 0, "No GSEA results are available."))
-      results_df
-    })
-    
-    observeEvent(gsea_detail_signature_choices(), {
-      choices <- gsea_detail_signature_choices()
-      selected <- isolate(input$gsea_detail_signature)
-      
-      if (is.null(selected) || !selected %in% unname(choices)) {
-        selected <- unname(choices)[[1]]
-      }
-      
-      updateSelectInput(
-        session,
-        "gsea_detail_signature",
-        choices = choices,
-        selected = selected
-      )
-    }, ignoreInit = FALSE)
-    
-    observeEvent(
-      list(gsea_results_table(), input$gsea_detail_signature),
-      {
-        results_df <- gsea_results_table()
-        signature_key <- input$gsea_detail_signature
-        if (is.null(signature_key) || !nzchar(signature_key)) {
-          return()
-        }
-        
-        signature_results <- results_df[results_df$signature == signature_key, , drop = FALSE]
-        signature_results <- signature_results[order(signature_results$fdr, -abs(signature_results$score)), , drop = FALSE]
-        
-        geneset_choices <- unique(signature_results$label)
-        if (length(geneset_choices) == 0) {
-          return()
-        }
-        
-        selected_geneset <- isolate(input$gsea_detail_geneset)
-        if (is.null(selected_geneset) || !selected_geneset %in% geneset_choices) {
-          selected_geneset <- geneset_choices[[1]]
-        }
-        
-        updateSelectInput(
-          session,
-          "gsea_detail_geneset",
-          choices = geneset_choices,
-          selected = selected_geneset
-        )
-      },
-      ignoreInit = FALSE
-    )
-    
-    gsea_curve_data <- reactive({
-      context <- enrichment_context()
-      req(context)
-      req(identical(context$method, "gsea"))
-      
-      signature_key <- input$gsea_detail_signature
-      geneset_name <- input$gsea_detail_geneset
-      req(signature_key, geneset_name)
-      
-      ranked_signature <- context$signature_vectors[[signature_key]]
-      geneset_genes <- context$genesets[[geneset_name]]
-      req(!is.null(ranked_signature), !is.null(geneset_genes))
-      
-      curve_info <- compute_gsea_curve_data(
-        ranked_signature = ranked_signature,
-        geneset_genes = geneset_genes,
-        power = 1
-      )
-      
-      curve_info$signature_key <- signature_key
-      curve_info$geneset_name <- geneset_name
-      curve_info
-    })
-    
-    output$gsea_detail_controls <- renderUI({
-      context <- enrichment_context()
-      
-      if (is.null(context) || !identical(context$method, "gsea")) {
-        return(NULL)
-      }
-      
-      tagList(
-        div(
-          class = "annotate-actions",
-          selectInput(
-            session$ns("gsea_detail_signature"),
-            "Signature",
-            choices = gsea_detail_signature_choices()
-          ),
-          selectInput(
-            session$ns("gsea_detail_geneset"),
-            "Geneset",
-            choices = character(0)
-          )
-        )
-      )
-    })
-    
-    output$gsea_curve_plot <- renderPlot({
-      curve_info <- gsea_curve_data()
-      build_gsea_curve_figure(curve_info)
-    })
-    
-    output$gsea_edge_summary <- renderUI({
-      curve_info <- gsea_curve_data()
-      
-      edge_text <- function(values) {
-        if (length(values) == 0) {
-          "None"
-        } else {
-          paste(utils::head(values, 12), collapse = ", ")
-        }
-      }
-      
-      tagList(
-        div(
-          class = "annotate-summary-grid",
-          div(
-            class = "annotate-summary-item",
-            tags$strong("Enrichment Score"),
-            tags$span(sprintf("%.3f", curve_info$es_score))
-          ),
-          div(
-            class = "annotate-summary-item",
-            tags$strong("Direction"),
-            tags$span(if (identical(curve_info$es_direction, "positive")) "Leading edge at top" else "Leading edge at bottom")
-          )
-        ),
-        tags$p(
-          class = "geneset-summary-text",
-          tags$strong("Leading Edge: "),
-          edge_text(curve_info$leading_edge_genes)
-        ),
-        tags$p(
-          class = "geneset-summary-text",
-          tags$strong("Trailing Edge: "),
-          edge_text(curve_info$trailing_edge_genes)
-        )
-      )
-    })
-    
-    output$enrichment <- renderUI({
-      hyp <- hyp_result()
-      context <- enrichment_context()
-      
-      if (is.null(hyp)) {
-        return(
-          div(
-            class = "annotate-empty",
-            "Results will appear here after you run an enrichment analysis."
-          )
-        )
-      }
-      
-      use_generic_results_table <- !is.null(context) && identical(context$engine, "hypeR_GEM")
-      
-      gsea_detail_section <- if (!is.null(context) && identical(context$method, "gsea")) {
-        div(
-          class = "annotate-results-section",
-          tags$h4("Enrichment Curve Detail"),
-          uiOutput(session$ns("gsea_detail_controls")),
-          plotOutput(session$ns("gsea_curve_plot"), height = "420px", width = "100%"),
-          uiOutput(session$ns("gsea_edge_summary"))
-        )
-      } else {
-        NULL
-      }
-      
-      div(
-        class = "annotate-results-body",
-        div(
-          class = "annotate-results-section",
-          tags$h4("Results Table"),
-          if (use_generic_results_table) {
-            DT::DTOutput(session$ns("generic_results_table"))
-          } else {
-            hypeR::rctbl_build(hyp)
-          }
-        ),
-        div(
-          class = "annotate-results-section",
-          tags$h4("Dotplot"),
-          plotOutput(session$ns("dotplot"), height = "400px", width = "100%"),
-          div(
-            class = "annotate-signature-key",
-            tags$h4("Signature Key"),
-            DT::DTOutput(session$ns("dotplot_signature_key"))
-          )
-        ),
-        gsea_detail_section
-      )
-    })
-    
-    output$generate_report <- downloadHandler(
-      filename = function() {
-        label <- input$experiment_label
-        if (is.null(label) || !nzchar(label)) {
-          label <- "sigrepo_annotate_analysis_bundle"
-        }
-        
-        safe_label <- gsub("[^A-Za-z0-9_-]+", "_", label)
-        sprintf("%s_%s.zip", safe_label, format(Sys.time(), "%Y%m%d_%H%M%S"))
-      },
-      content = function(file) {
-        hyp <- hyp_result()
-        context <- enrichment_context()
-        req(hyp, context)
-        
-        sig_list <- active_signatures()
-        sig_ids <- vapply(sig_list, function(sig) as.numeric(sig$signature_id), numeric(1))
-        sig_objs <- SigRepo::getSignature(
-          conn_handler = user_conn_handler(),
-          signature_id = sig_ids
-        )
-        
-        bundle_dir <- tempfile("annotate_analysis_bundle_")
-        dir.create(bundle_dir, recursive = TRUE, showWarnings = FALSE)
-        on.exit(unlink(bundle_dir, recursive = TRUE, force = TRUE), add = TRUE)
-        
-        plots_dir <- file.path(bundle_dir, "plots")
-        dir.create(plots_dir, recursive = TRUE, showWarnings = FALSE)
-        
-        plot_paths <- list()
-        
-        dotplot_payload <- tryCatch(dotplot_data(), error = function(e) NULL)
-        if (!is.null(dotplot_payload) && is.data.frame(dotplot_payload$plot_df) && nrow(dotplot_payload$plot_df) > 0) {
-          dotplot_path <- file.path(plots_dir, "dotplot.png")
-          ggplot2::ggsave(
-            filename = dotplot_path,
-            plot = build_dotplot_figure(dotplot_payload$plot_df, title = input$experiment_label),
-            width = 11,
-            height = 7,
-            dpi = 150
-          )
-          plot_paths$dotplot <- file.path("plots", "dotplot.png")
-        }
-        
-        if (identical(context$method, "gsea")) {
-          curve_info <- tryCatch(gsea_curve_data(), error = function(e) NULL)
-          if (!is.null(curve_info)) {
-            gsea_path <- file.path(plots_dir, "gsea_curve.png")
-            ggplot2::ggsave(
-              filename = gsea_path,
-              plot = build_gsea_curve_figure(curve_info),
-              width = 11,
-              height = 6,
-              dpi = 150
-            )
-            plot_paths$gsea_curve <- file.path("plots", "gsea_curve.png")
-          }
-        }
-        
-        results_df <- sanitize_report_table(extract_hyp_results_table(hyp))
-        signature_key_df <- sanitize_report_table(
-          tryCatch(dotplot_data()$signature_lookup, error = function(e) data.frame())
-        )
-        metadata_df <- sanitize_report_table(build_signature_metadata_table(sig_objs, sig_list))
-        settings_df <- build_report_settings_table(
-          experiment_label = input$experiment_label,
-          context = context,
-          geneset_names = names(context$genesets %||% list()),
-          fdr_threshold = input$enrichment_thresh,
-          background = input$enrichment_bg
-        )
-        
-        analysis_context <- list(
-          title = if (nzchar(input$experiment_label)) input$experiment_label else "SigRepo Annotate Analysis",
-          settings_df = settings_df,
-          signature_metadata_df = metadata_df,
-          signature_key_df = signature_key_df,
-          results_df = results_df,
-          geneset_names = names(context$genesets %||% list()),
-          plot_paths = plot_paths,
-          method = context$method %||% "unknown",
-          engine = context$engine %||% "hypeR"
-        )
-        
-        saveRDS(hyp, file.path(bundle_dir, "hyp_result.rds"))
-        saveRDS(analysis_context, file.path(bundle_dir, "analysis_context.rds"))
-        
-        readme_lines <- c(
-          "# SigRepo Annotate Analysis Bundle",
-          "",
-          "This bundle contains:",
-          "- `hyp_result.rds`: exported hype/hypGEM result object",
-          "- `analysis_context.rds`: analysis settings, metadata, results tables, and plot key",
-          "- `plots/`: exported figures captured at export time",
-          "",
-          "Suggested workflow:",
-          "1. Unzip this bundle.",
-          "2. Load `hyp_result.rds` and/or `analysis_context.rds` in R.",
-          "3. Reuse the PNG figures in `plots/` for slides or notes."
-        )
-        writeLines(readme_lines, con = file.path(bundle_dir, "README.md"))
-        
-        old_wd <- getwd()
-        on.exit(setwd(old_wd), add = TRUE)
-        setwd(bundle_dir)
-        utils::zip(
-          zipfile = file,
-          files = list.files(".", recursive = TRUE, all.files = FALSE)
-        )
-      }
-    )
-    
-    output$export_hyp <- downloadHandler(
-      filename = function() {
-        label <- input$experiment_label
-        if (is.null(label) || !nzchar(label)) {
-          label <- "sigrepo_enrichment"
-        }
-        
-        safe_label <- gsub("[^A-Za-z0-9_-]+", "_", label)
-        sprintf("%s_hype_%s.rds", safe_label, format(Sys.time(), "%Y%m%d_%H%M%S"))
-      },
-      content = function(file) {
-        hyp <- hyp_result()
-        req(hyp)
-        saveRDS(hyp, file)
-      }
-    )
-  })
-}
diff --git a/R/hyperGEMClient.R b/R/hyperGEMClient.R
index 77e01ca4..2c40eb02 100644
--- a/R/hyperGEMClient.R
+++ b/R/hyperGEMClient.R
@@ -308,7 +308,7 @@ runHyperGEM <- function(
     )
   }
 
-  resolved_genesets <- resolveHypeRGenesets(genesets = genesets)
+  resolved_genesets <- getHypeRGenesets(genesets = genesets)
   method <- base::match.arg(method)
 
   enrichment_inputs <- prepareHyperGEMSignatures(
diff --git a/R/mergeDifexp.R b/R/mergeDifexp.R
new file mode 100644
index 00000000..119ab00c
--- /dev/null
+++ b/R/mergeDifexp.R
@@ -0,0 +1,212 @@
+#' Merge the difexp tables of several signatures into one matrix
+#'
+#' @description
+#' Fetches signatures from the SigRepo database and/or takes OmicSignature
+#' objects supplied directly, and lines their difexp tables up into a single
+#' numeric matrix with one row per feature and one column per signature. The
+#' value in each cell is that signature's \code{value_col} for that feature,
+#' and \code{NA} where the signature's difexp table has no such feature.
+#'
+#' This is the "signature compendium" shape that signature-by-signature
+#' correlation, clustering, PCA and reference databases for tools such as
+#' signatureSearch expect. The thresholded signature tables are not used;
+#' only the full difexp tables are, since those cover every tested feature.
+#'
+#' Signatures are assembled the same way as in \code{compareSignatures()}:
+#' ids and names are resolved with \code{searchSignature()} and fetched with
+#' \code{getSignature()}, supplied objects come after them, and requests that
+#' cannot be honoured are reported in a warning and left out. Columns are
+#' named by the list names of supplied objects (their metadata
+#' \code{signature_name} when unnamed) and by the database
+#' \code{signature_name} of fetched ones.
+#'
+#' A difexp table often lists one feature several times, once per probe.
+#' Such rows are collapsed to one value per feature before merging, chosen by
+#' \code{collapse}. Signatures without a difexp table, or whose difexp table
+#' has no \code{value_col} or \code{feature_col} column, are dropped with a
+#' warning naming them; it is an error when that leaves nothing to merge.
+#'
+#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
+#'   Required whenever signatures are requested by id or name.
+#' @param signature_ids Database signature ids to fetch.
+#' @param signature_names Database signature names to fetch.
+#' @param omic_signatures An OmicSignature object, a list of OmicSignature
+#'   objects, or an OmicSignatureCollection to include directly.
+#' @param value_col The difexp column whose values fill the matrix. Defaults
+#'   to \code{"score"}; \code{"logfc"} is the other common choice.
+#' @param feature_col The difexp column holding feature identifiers, used as
+#'   row names.
+#' @param features \code{"union"} (the default) keeps every feature found in
+#'   any table, with \code{NA} where a table lacks it; \code{"intersect"} keeps
+#'   only features present in every table.
+#' @param collapse How to reduce several rows of the same feature within one
+#'   table to a single value: \code{"max_abs"} (the default) keeps the value
+#'   with the largest absolute size, \code{"min"} keeps the smallest value,
+#'   \code{"mean"} averages them, and \code{"first"} keeps the first row as
+#'   stored. Use \code{"min"} with a p-value column such as \code{"p_value"}
+#'   or \code{"adj_p"}, where the smallest value is the most significant;
+#'   \code{"max_abs"} would keep the least significant probe there.
+#' @param verbose Logical; whether to print diagnostic messages while
+#'   resolving and fetching signatures. Defaults to \code{FALSE}.
+#'
+#' @return A numeric matrix with features as row names and signatures as
+#'   column names, in the order the signatures were assembled.
+#'
+#' @seealso \code{compareSignatures()}, \code{getSignature()}.
+#'
+#' @examples
+#' # The bundled example signatures need no database
+#' utils::data("omic_signature_1", "omic_signature_2", "omic_signature_3", package = "SigRepo")
+#'
+#' m <- SigRepo::mergeDifexp(
+#'   omic_signatures = list(v1 = omic_signature_1, v2 = omic_signature_2, v3 = omic_signature_3)
+#' )
+#' dim(m)
+#' stats::cor(m, use = "pairwise.complete.obs")
+#'
+#' \dontrun{
+#' conn_handler <- SigRepo::newConnHandler(
+#'   dbname = "sigrepo", host = "localhost", port = 3306,
+#'   user = "your_username", password = "your_password"
+#' )
+#'
+#' m <- SigRepo::mergeDifexp(
+#'   conn_handler = conn_handler,
+#'   signature_ids = c(12, 34),
+#'   signature_names = "my_signature",
+#'   value_col = "logfc",
+#'   features = "intersect"
+#' )
+#'
+#' # Adjusted p-values: keep the most significant probe of a duplicated feature
+#' p <- SigRepo::mergeDifexp(
+#'   conn_handler = conn_handler,
+#'   signature_ids = c(12, 34),
+#'   value_col = "adj_p",
+#'   collapse = "min"
+#' )
+#' }
+#'
+#' @export
+mergeDifexp <- function(
+    conn_handler = NULL,
+    signature_ids = NULL,
+    signature_names = NULL,
+    omic_signatures = NULL,
+    value_col = "score",
+    feature_col = "feature_name",
+    features = c("union", "intersect"),
+    collapse = c("max_abs", "min", "mean", "first"),
+    verbose = FALSE) {
+
+  features <- base::match.arg(features)
+  collapse <- base::match.arg(collapse)
+
+  # Whether to print the diagnostic messages
+  SigRepo::print_messages(verbose = verbose)
+
+  signature_ids <- cleanCompareRequest(signature_ids)
+  signature_names <- cleanCompareRequest(signature_names)
+
+  needs_database <- base::length(c(signature_ids, signature_names)) > 0
+  if (needs_database && base::is.null(conn_handler)) {
+    base::stop("\n'conn_handler' is required to fetch signatures by 'signature_ids' or 'signature_names'.\n")
+  }
+
+  sig_list <- resolveCompareSignatureList(
+    conn_handler = conn_handler,
+    signature_ids = signature_ids,
+    signature_names = signature_names,
+    omic_signatures = omic_signatures,
+    arg_suffix = "",
+    verbose = verbose
+  )
+  if (base::length(sig_list) == 0) {
+    base::stop("\nProvide signatures through 'signature_ids', 'signature_names' and/or 'omic_signatures'.\n")
+  }
+
+  # One named numeric vector per usable signature: feature -> value.
+  columns <- base::list()
+  dropped <- base::character()
+  for (i in base::seq_along(sig_list)) {
+    sig_name <- base::names(sig_list)[i]
+    difexp <- sig_list[[i]]$difexp
+    if (base::is.null(difexp)) {
+      dropped <- c(dropped, base::sprintf("'%s' has no difexp table", sig_name))
+      next
+    }
+    missing_cols <- base::setdiff(c(feature_col, value_col), base::colnames(difexp))
+    if (base::length(missing_cols) > 0) {
+      dropped <- c(dropped, base::sprintf(
+        "'%s' has no %s column in its difexp table", sig_name,
+        base::paste(base::sprintf("'%s'", missing_cols), collapse = " or ")
+      ))
+      next
+    }
+    columns[[sig_name]] <- collapseDifexpValues(
+      feature = base::as.character(difexp[[feature_col]]),
+      value = base::as.numeric(difexp[[value_col]]),
+      collapse = collapse
+    )
+  }
+
+  if (base::length(dropped) > 0) {
+    if (base::length(columns) == 0) {
+      base::stop(
+        "\nNone of the signatures has a difexp table with '", feature_col, "' and '", value_col, "' columns:\n",
+        base::paste(dropped, collapse = "\n"), "\n"
+      )
+    }
+    base::warning(
+      "Some signatures were left out of the merged matrix:\n",
+      base::paste(dropped, collapse = "\n"),
+      call. = FALSE
+    )
+  }
+
+  feature_sets <- base::lapply(columns, base::names)
+  all_features <- if (features == "union") {
+    base::Reduce(base::union, feature_sets)
+  } else {
+    base::Reduce(base::intersect, feature_sets)
+  }
+
+  SigRepo::verbose(base::sprintf(
+    "Merging %d signature(s) over %d feature(s) (%s) by '%s'.\n",
+    base::length(columns), base::length(all_features), features, value_col
+  ))
+
+  merged <- base::vapply(columns, function(v) base::unname(v[all_features]), base::numeric(base::length(all_features)))
+  merged <- base::matrix(
+    merged,
+    nrow = base::length(all_features),
+    dimnames = base::list(all_features, base::names(columns))
+  )
+  merged
+}
+
+
+#' Reduce a difexp table to one value per feature
+#'
+#' @param feature Character vector of feature identifiers, one per row.
+#' @param value Numeric vector of the values to keep, one per row.
+#' @param collapse "max_abs", "min", "mean" or "first".
+#' @return A named numeric vector, one entry per distinct feature, in order of
+#'   first appearance. Rows with an empty or missing feature are ignored.
+#' @noRd
+collapseDifexpValues <- function(feature, value, collapse) {
+  keep <- !base::is.na(feature) & feature != ""
+  feature <- feature[keep]
+  value <- value[keep]
+  groups <- base::split(value, base::factor(feature, levels = base::unique(feature)))
+  reducer <- switch(collapse,
+    max_abs = function(v) {
+      v <- v[!base::is.na(v)]
+      if (base::length(v) == 0) NA_real_ else v[base::which.max(base::abs(v))]
+    },
+    min = function(v) if (base::all(base::is.na(v))) NA_real_ else base::min(v, na.rm = TRUE),
+    mean = function(v) if (base::all(base::is.na(v))) NA_real_ else base::mean(v, na.rm = TRUE),
+    first = function(v) v[1]
+  )
+  base::vapply(groups, reducer, base::numeric(1))
+}
diff --git a/R/searchExternal.R b/R/searchExternal.R
new file mode 100644
index 00000000..d38f1e72
--- /dev/null
+++ b/R/searchExternal.R
@@ -0,0 +1,145 @@
+#' @title searchExternal
+#' @description Search public signature engines with a SigRepo signature.
+#' The signature's features are translated into gene symbols (reference table
+#' first, then biomaRt for Ensembl IDs) plus an organism code, and sent to one
+#' or more of:
+#' \itemize{
+#'   \item \strong{Rummagene} (\url{https://rummagene.com}): ~1M gene sets mined
+#'   from PMC supplementary tables. Fisher overlap, any organism.
+#'   \item \strong{RummaGEO} (\url{https://rummageo.com}): up/down gene sets
+#'   auto-computed from GEO RNA-seq studies. Fisher overlap, human and mouse.
+#'   \item \strong{CORESH} (\url{https://alserglab.wustl.edu/coresh/}): GEO
+#'   expression datasets ranked by how much variance the query explains as a
+#'   coregulated block. Human and mouse; optional permutation p-values.
+#' }
+#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
+#' Required unless \code{omic_signature} is supplied. Also enables the
+#' reference-table symbol lookup.
+#' @param signature_id A single SigRepo signature ID.
+#' @param signature_name A single SigRepo signature name.
+#' @param omic_signature An \code{OmicSignature} object, instead of fetching one.
+#' @param source One or more of \code{"rummagene"}, \code{"rummageo"},
+#' \code{"coresh"}. Defaults to all three.
+#' @param direction Which features to send: \code{"combined"} (all),
+#' \code{"up"} / \code{"down"} (by the sign of \code{score}), or \code{"both"}
+#' (up and down as two separate queries, stacked with a \code{direction} column).
+#' @param limit Maximum hits per source (per direction for \code{"both"}).
+#' @param calculate_pvalues CORESH only: also compute permutation p-values
+#' (about a minute instead of seconds).
+#' @param timeout Seconds to wait for a CORESH job before giving up.
+#' @param verbose Logical; print diagnostic messages. Default \code{TRUE}.
+#'
+#' @return For a single \code{source}, a data frame; for several, a named list of
+#' data frames. Every data frame starts with the columns \code{source, direction,
+#' rank, id, title, url, score, score_label, pvalue, adj_pvalue, n_overlap, n_set},
+#' followed by service-specific extras, and carries attributes \code{query}
+#' (the translated query that was sent) and \code{total_count}. CORESH frames
+#' also carry \code{job_url}, a shareable results page.
+#'
+#' @export
+#' @examples
+#' \dontrun{
+#' hits <- SigRepo::searchExternal(
+#'   conn_handler = conn_handler,
+#'   signature_name = "my_signature",
+#'   source = "coresh"
+#' )
+#' attr(hits, "job_url")
+#'
+#' all_three <- SigRepo::searchExternal(omic_signature = my_omic_signature)
+#' all_three$rummagene
+#' }
+searchExternal <- function(
+    conn_handler = NULL,
+    signature_id = NULL,
+    signature_name = NULL,
+    omic_signature = NULL,
+    source = c("rummagene", "rummageo", "coresh"),
+    direction = c("combined", "up", "down", "both"),
+    limit = 25,
+    calculate_pvalues = FALSE,
+    timeout = 120,
+    verbose = TRUE
+){
+
+  source <- base::match.arg(source, choices = EXTERNAL_SOURCES, several.ok = TRUE)
+  direction <- base::match.arg(direction)
+  limit <- base::suppressWarnings(base::as.integer(limit[1]))
+  if (base::is.na(limit) || limit < 1) {
+    base::stop("\n'limit' must be a positive integer.\n")
+  }
+
+  omic_signature <- resolveComparisonSignature(
+    conn_handler = conn_handler,
+    signature_id = signature_id,
+    signature_name = signature_name,
+    omic_signature = omic_signature,
+    label = "signature",
+    verbose = verbose
+  )
+
+  directions <- if (base::identical(direction, "both")) c("up", "down") else direction
+  queries <- base::lapply(directions, function(d) {
+    buildExternalQuery(omic_signature, direction = d, conn_handler = conn_handler, max_genes = 500, verbose = verbose)
+  })
+  base::names(queries) <- directions
+
+  run_adapter <- function(src, query) {
+    base::switch(
+      src,
+      rummagene = externalRummagene(query, limit = limit, timeout = timeout),
+      rummageo  = externalRummageo(query, limit = limit, timeout = timeout),
+      coresh    = externalCoresh(query, limit = limit, calculate_pvalues = calculate_pvalues, timeout = timeout)
+    )
+  }
+
+  run_source <- function(src) {
+    frames <- base::lapply(directions, function(d) {
+      base::tryCatch(
+        run_adapter(src, queries[[d]]),
+        error = function(e) {
+          if (base::length(source) == 1) {
+            base::stop(e)
+          }
+          base::warning(base::sprintf("%s: %s", src, base::conditionMessage(e)), call. = FALSE)
+          emptyExternalFrame(src, d)
+        }
+      )
+    })
+    base::names(frames) <- directions
+    if (base::isTRUE(verbose)) {
+      for (d in directions) {
+        total <- base::attr(frames[[d]], "total_count")
+        n <- base::nrow(frames[[d]])
+        base::message(base::sprintf(
+          "%s%s: %s returned (limit = %d)%s",
+          src,
+          if (base::length(directions) > 1) base::sprintf(" [%s]", d) else "",
+          if (!base::is.null(total) && base::is.numeric(total)) {
+            base::sprintf("%d of %s matching hits", n, base::format(total, big.mark = ",", scientific = FALSE))
+          } else {
+            base::sprintf("%d hit%s", n, if (n == 1) "" else "s")
+          },
+          limit,
+          if (!base::is.null(base::attr(frames[[d]], "job_url"))) base::sprintf("; full ranking at %s", base::attr(frames[[d]], "job_url")) else ""
+        ))
+      }
+    }
+    out <- rbindExternalFrames(frames)
+    if (base::length(frames) == 1) {
+      base::attr(out, "query") <- queries[[1]]
+      base::attr(out, "total_count") <- base::attr(frames[[1]], "total_count")
+      base::attr(out, "job_url") <- base::attr(frames[[1]], "job_url")
+    } else {
+      base::attr(out, "query") <- queries
+      base::attr(out, "total_count") <- base::lapply(frames, base::attr, "total_count")
+      base::attr(out, "job_url") <- base::lapply(frames, base::attr, "job_url")
+    }
+    out
+  }
+
+  results <- base::lapply(source, run_source)
+  base::names(results) <- source
+  if (base::length(source) == 1) results[[1]] else results
+
+}
diff --git a/R/writeSignatureSearchScript.R b/R/writeSignatureSearchScript.R
new file mode 100644
index 00000000..140c72cb
--- /dev/null
+++ b/R/writeSignatureSearchScript.R
@@ -0,0 +1,276 @@
+
+# Fewest features per direction a LINCS query is written for. The LINCS
+# connectivity score is a weighted KS statistic over an up and a down set, and
+# on a handful of genes it is noise.
+SIGNATURE_SEARCH_MIN_FEATURES <- 10L
+
+
+#' Build the up and down query of a LINCS search from one signature
+#'
+#' Direction is the sign of \code{score}. \code{group_label} holds the
+#' biological contrast (e.g. "Older", "Younger") and carries no direction.
+#'
+#' @param omic_signature A single \code{OmicSignature} object.
+#'
+#' @return A list with \code{signature_name}, \code{id_type} (the
+#' \code{org.Hs.eg.db} keytype of the feature names) and the \code{up} and
+#' \code{down} feature names, each ordered from the strongest score.
+#'
+#' @noRd
+buildSignatureSearchQuery <- function(omic_signature) {
+
+  metadata <- omic_signature$metadata
+  signature_name <- base::as.character(metadata$signature_name)[1]
+
+  clean_value <- function(value) {
+    if (base::is.null(value) || base::length(value) == 0 || base::is.na(value[1])) {
+      return("")
+    }
+    base::trimws(base::as.character(value[1]))
+  }
+  organism <- clean_value(metadata$organism)
+  assay_type <- clean_value(metadata$assay_type)
+
+  # LINCS profiles are of human cell lines. Mouse genes could be carried over
+  # by orthology, but what that loses matters for a connectivity score.
+  if (!base::identical(base::tolower(organism), "homo sapiens")) {
+    base::stop(base::sprintf(
+      "\nLINCS is built from human cell lines, so the signature must be of organism Homo sapiens. '%s' is %s.\n",
+      signature_name,
+      if (base::nzchar(organism)) organism else "of no recorded organism"
+    ), call. = FALSE)
+  }
+
+  if (!base::identical(base::tolower(assay_type), "transcriptomics")) {
+    base::stop(base::sprintf(
+      "\nLINCS profiles are gene expression, so the signature must be of assay type transcriptomics. '%s' is %s.\n",
+      signature_name,
+      if (base::nzchar(assay_type)) assay_type else "of no recorded assay type"
+    ), call. = FALSE)
+  }
+
+  signature_tbl <- omic_signature$signature
+  missing_cols <- base::setdiff(c("feature_name", "score"), base::colnames(signature_tbl))
+  if (base::length(missing_cols) > 0) {
+    base::stop(base::sprintf(
+      "\nSignature '%s' is missing the column(s) %s, which the query is built from.\n",
+      signature_name,
+      base::paste0("'", missing_cols, "'", collapse = ", ")
+    ), call. = FALSE)
+  }
+
+  features <- base::trimws(base::as.character(signature_tbl$feature_name))
+  scores <- base::suppressWarnings(base::as.numeric(signature_tbl$score))
+
+  keep <- !base::is.na(features) & base::nzchar(features) & !base::is.na(scores) & scores != 0
+  features <- features[keep]
+  scores <- scores[keep]
+
+  # Ensembl gene IDs may carry a version (ENSG00000126353.4) that
+  # org.Hs.eg.db does not know.
+  id_type <- "SYMBOL"
+  if (base::length(features) > 0 && base::all(base::grepl("^ENSG[0-9]+(\\.[0-9]+)?$", features))) {
+    id_type <- "ENSEMBL"
+    features <- base::sub("\\.[0-9]+$", "", features)
+  }
+
+  strongest_first <- base::order(base::abs(scores), decreasing = TRUE)
+  features <- features[strongest_first]
+  scores <- scores[strongest_first]
+
+  up <- base::unique(features[scores > 0])
+  down <- base::unique(features[scores < 0])
+
+  # A feature scored in both directions would push the score both ways.
+  in_both <- base::intersect(up, down)
+  up <- base::setdiff(up, in_both)
+  down <- base::setdiff(down, in_both)
+
+  if (base::length(up) < SIGNATURE_SEARCH_MIN_FEATURES || base::length(down) < SIGNATURE_SEARCH_MIN_FEATURES) {
+    base::stop(base::sprintf(
+      "\nA LINCS query needs at least %d features in each direction, by the sign of 'score'. '%s' has %d up and %d down.\n",
+      SIGNATURE_SEARCH_MIN_FEATURES,
+      signature_name,
+      base::length(up),
+      base::length(down)
+    ), call. = FALSE)
+  }
+
+  base::list(
+    signature_name = signature_name,
+    id_type = id_type,
+    up = up,
+    down = down
+  )
+
+}
+
+
+#' Write a character vector as the R code of an assignment
+#'
+#' \code{deparse()} quotes and escapes every value, so nothing taken from a
+#' signature can end up in the script as code.
+#'
+#' @noRd
+deparseAssignment <- function(name, value) {
+  code <- base::deparse(value, width.cutoff = 80L)
+  code[1] <- base::paste(name, "<-", code[1])
+  code
+}
+
+
+#' @title writeSignatureSearchScript
+#' @description Write an R script that runs a LINCS connectivity search for
+#' one signature with Bioconductor's \code{signatureSearch}: which
+#' perturbations produce the signature's expression pattern, and which reverse
+#' it.
+#'
+#' SigRepo does not run the search, and does not depend on
+#' \code{signatureSearch}, whose reference database is about 2.5 GB. The script
+#' is run on a machine that has \code{signatureSearch},
+#' \code{ExperimentHub}, \code{rhdf5}, \code{AnnotationDbi},
+#' \code{org.Hs.eg.db} and \code{ggplot2} installed, and stops with the install command when one
+#' of them is missing.
+#'
+#' The query is built from the signature's feature set: features with a
+#' positive \code{score} are the up set and features with a negative
+#' \code{score} the down set, each ordered from the strongest score. A feature
+#' scored in both directions is left out. The script maps the features to
+#' Entrez IDs, keeps the genes LINCS measured, and searches with the strongest
+#' \code{n_genes} of each direction. It saves the result table, one row per
+#' perturbation and cell line, as a CSV, and a plot of the 10 perturbations
+#' that most resemble the signature and the 10 that most reverse it as a PDF.
+#'
+#' Only human transcriptomics signatures with at least 10 features in each
+#' direction can be searched; any other signature is an error.
+#'
+#' @param conn_handler An R object obtained from \code{SigRepo::newConnHandler()}.
+#' Required unless \code{omic_signature} is supplied.
+#' @param signature_id A single SigRepo signature ID.
+#' @param signature_name A single SigRepo signature name.
+#' @param omic_signature A single \code{OmicSignature} object.
+#' @param file Path of the script to write (required).
+#' @param n_genes Number of genes of each direction to search with. Defaults
+#' to \code{150}. It is a setting at the top of the script and can be changed
+#' there.
+#' @param overwrite Logical; whether to replace \code{file} when it exists.
+#' Defaults to \code{FALSE}.
+#' @param verbose Logical; whether or not to print the
+#' diagnostic messages. Default is \code{TRUE}.
+#'
+#' @return The path of the script, invisibly.
+#'
+#' @export
+#' @examples
+#' \dontrun{
+#' script <- SigRepo::writeSignatureSearchScript(
+#'   conn_handler = conn_handler,
+#'   signature_name = "LLFS_Aging_Gene_2023",
+#'   file = "LLFS_Aging_Gene_2023_lincs.R"
+#' )
+#'
+#' # Runs the search and saves LLFS_Aging_Gene_2023_lincs_results.csv and
+#' # LLFS_Aging_Gene_2023_lincs_top_hits.pdf
+#' source(script)
+#' }
+#'
+writeSignatureSearchScript <- function(
+    conn_handler = NULL,
+    signature_id = NULL,
+    signature_name = NULL,
+    omic_signature = NULL,
+    file,
+    n_genes = 150,
+    overwrite = FALSE,
+    verbose = TRUE
+) {
+
+  # Whether to print the diagnostic messages
+  SigRepo::print_messages(verbose = verbose)
+
+  if (base::missing(file) || !base::is.character(file) || base::length(file) != 1L ||
+      base::is.na(file) || !base::nzchar(base::trimws(file))) {
+    base::stop("\n'file' is required: the path of the script to write, e.g. file = \"lincs_search.R\".\n", call. = FALSE)
+  }
+
+  if (!(base::is.numeric(n_genes) && base::length(n_genes) == 1L && !base::is.na(n_genes) &&
+        n_genes >= SIGNATURE_SEARCH_MIN_FEATURES && n_genes == base::round(n_genes))) {
+    base::stop(base::sprintf(
+      "\n'n_genes' must be a single whole number of at least %d.\n",
+      SIGNATURE_SEARCH_MIN_FEATURES
+    ), call. = FALSE)
+  }
+
+  if (!base::dir.exists(base::dirname(file))) {
+    base::stop(base::sprintf("\nThe directory of 'file' does not exist: %s\n", base::dirname(file)), call. = FALSE)
+  }
+
+  if (base::file.exists(file) && !base::isTRUE(overwrite)) {
+    base::stop(base::sprintf("\n'%s' already exists. Use overwrite = TRUE to replace it.\n", file), call. = FALSE)
+  }
+
+  omic_signature <- resolveComparisonSignature(
+    conn_handler = conn_handler,
+    signature_id = signature_id,
+    signature_name = signature_name,
+    omic_signature = omic_signature,
+    label = "the signature",
+    verbose = verbose
+  )
+
+  query <- buildSignatureSearchQuery(omic_signature)
+
+  # Not base::system.file(): devtools::load_all() can only redirect the
+  # unqualified call to the source tree's inst/.
+  template <- system.file("templates", "signatureSearch_lincs.R", package = "SigRepo")
+  if (!base::nzchar(template)) {
+    base::stop("\nThe script template is missing from the installed SigRepo package.\n", call. = FALSE)
+  }
+
+  file_stem <- base::gsub("[^A-Za-z0-9._-]+", "_", query$signature_name)
+  output_file <- base::paste0(file_stem, "_lincs_results.csv")
+  plot_file <- base::paste0(file_stem, "_lincs_top_hits.pdf")
+
+  script <- c(
+    "# LINCS connectivity search for a SigRepo signature, with signatureSearch",
+    "# (https://bioconductor.org/packages/signatureSearch).",
+    "#",
+    base::sprintf(
+      "# Written by SigRepo::writeSignatureSearchScript(), SigRepo %s, on %s.",
+      base::as.character(utils::packageVersion("SigRepo")),
+      base::format(base::Sys.Date())
+    ),
+    "#",
+    "# Run it with source() or Rscript. The first run downloads the LINCS",
+    "# reference database (about 2.5 GB); the search itself takes a few minutes.",
+    "",
+    "## The signature ----",
+    "# Features by the sign of their score, strongest first.",
+    deparseAssignment("signature_name", query$signature_name),
+    deparseAssignment("id_type", query$id_type),
+    deparseAssignment("up_ids", query$up),
+    deparseAssignment("down_ids", query$down),
+    "",
+    "## Settings ----",
+    "# Genes of each direction to search with.",
+    deparseAssignment("n_genes", base::as.numeric(n_genes)),
+    "# Where the result table and the plot of the strongest hits are saved,",
+    "# relative to the working directory.",
+    deparseAssignment("output_file", output_file),
+    deparseAssignment("plot_file", plot_file),
+    base::readLines(template, warn = FALSE)
+  )
+
+  base::writeLines(script, con = file)
+
+  SigRepo::verbose(base::sprintf(
+    "Script written to %s: %d up and %d down features of '%s'. Run it with source() where signatureSearch is installed.\n",
+    file,
+    base::length(query$up),
+    base::length(query$down),
+    query$signature_name
+  ))
+
+  base::invisible(file)
+
+}
diff --git a/_pkgdown.yml b/_pkgdown.yml
index cac8e679..43ba06bf 100755
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -109,15 +109,31 @@ reference:
     desc: ~
     contents:
       - '`compareSignatures`'
+      - '`mergeDifexp`'
 
   - title: Enrichment Analysis
     desc: ~
     contents:
       - '`prepareHypeRSignatures`'
       - '`runHypeR`'
+      - '`getHypeRGenesets`'
+      - '`hypeRToExcel`'
+      - '`getHypeRDifexp`'
+      - '`plotHypeRDots`'
+      - '`plotHypeREnrichment`'
+      - '`plotHypeRMap`'
+      - '`hypeRDotData`'
+      - '`hypeRSignatureKey`'
+      - '`hypeREnrichmentData`'
       - '`runHyperGEM`'
       - '`hypergemAvailable`'
       - '`hypergemExport`'
+
+  - title: Search Beyond the Repository
+    desc: Ask Rummagene, RummaGEO and CORESH what resembles a signature, or write a script that searches LINCS for perturbations that mimic or reverse it
+    contents:
+      - '`searchExternal`'
+      - '`writeSignatureSearchScript`'
       
   - title: Build Signature Objects
     desc: Construct and validate OmicSignature and OmicSignatureCollection objects before depositing them
@@ -190,7 +206,7 @@ reference:
 navbar:
   title: SigRepo
   structure:
-    left: [home, signature, collection, reference, change_log]
+    left: [home, signature, collection, annotation, reference, change_log]
     right: [search, github, lightswitch]
   components:
     signature:
@@ -199,6 +215,9 @@ navbar:
     collection:
       text: "Upload Collection"
       href: articles/collection-tutorials.html        
+    annotation:
+      text: "Annotate Signatures"
+      href: articles/annotation-tutorial.html
     reference:
       text: "Reference"
       href: reference/index.html 
diff --git a/inst/templates/signatureSearch_lincs.R b/inst/templates/signatureSearch_lincs.R
new file mode 100644
index 00000000..0de8350c
--- /dev/null
+++ b/inst/templates/signatureSearch_lincs.R
@@ -0,0 +1,114 @@
+
+## Packages ----
+# signatureSearch and its reference data are Bioconductor packages that SigRepo
+# does not install. Nothing is installed from here either: the script stops
+# and says what is missing.
+required_packages <- c("signatureSearch", "ExperimentHub", "rhdf5", "AnnotationDbi", "org.Hs.eg.db", "ggplot2")
+missing_packages <- required_packages[
+  !vapply(required_packages, requireNamespace, logical(1), quietly = TRUE)
+]
+if (length(missing_packages) > 0) {
+  stop(
+    "Install the missing packages, then run this script again:\n",
+    "  install.packages(\"BiocManager\")\n",
+    "  BiocManager::install(c(", paste0("\"", missing_packages, "\"", collapse = ", "), "))",
+    call. = FALSE
+  )
+}
+
+# Attached, not only called as signatureSearch::, because the search annotates
+# its hits with data sets that R finds only in an attached package.
+suppressPackageStartupMessages(library(signatureSearch))
+
+## LINCS reference database ----
+# LINCS L1000 moderated z-scores (ExperimentHub EH3226). The first run
+# downloads about 2.5 GB into the ExperimentHub cache; later runs reuse it.
+lincs_db <- ExperimentHub::ExperimentHub()[["EH3226"]]
+lincs_gene_ids <- as.character(rhdf5::h5read(lincs_db, "rownames"))
+
+## Query ----
+# LINCS is keyed on Entrez IDs. Map each direction, keep the genes LINCS
+# measured, and take the strongest n_genes of what is left.
+min_genes <- 10
+
+to_lincs_entrez <- function(ids) {
+  entrez <- suppressMessages(AnnotationDbi::mapIds(
+    org.Hs.eg.db::org.Hs.eg.db,
+    keys = ids,
+    column = "ENTREZID",
+    keytype = id_type,
+    multiVals = "first"
+  ))
+  entrez <- unique(unname(entrez[!is.na(entrez)]))
+  entrez[entrez %in% lincs_gene_ids]
+}
+
+upset <- to_lincs_entrez(up_ids)
+downset <- to_lincs_entrez(down_ids)
+
+# Two features can map to the same gene. One that ends up in both directions
+# is left out of both.
+in_both <- intersect(upset, downset)
+upset <- utils::head(setdiff(upset, in_both), n_genes)
+downset <- utils::head(setdiff(downset, in_both), n_genes)
+
+message(sprintf(
+  "'%s': %d up and %d down features, of which %d up and %d down genes are in LINCS and used as the query.",
+  signature_name, length(up_ids), length(down_ids), length(upset), length(downset)
+))
+
+if (length(upset) < min_genes || length(downset) < min_genes) {
+  stop(
+    "The LINCS score needs at least ", min_genes, " genes in each direction, and only ",
+    length(upset), " up and ", length(downset), " down are in LINCS.",
+    call. = FALSE
+  )
+}
+
+## Search ----
+# NCS is the normalized connectivity score of one perturbation in one cell
+# line; NCSct summarizes a perturbation across cell lines. Positive scores
+# mean the perturbation resembles the signature, negative that it reverses it.
+query <- signatureSearch::qSig(
+  query = list(upset = upset, downset = downset),
+  gess_method = "LINCS",
+  refdb = lincs_db
+)
+search <- signatureSearch::gess_lincs(query, sortby = "NCSct", tau = FALSE)
+hits <- as.data.frame(signatureSearch::result(search))
+
+## Results ----
+utils::write.csv(hits, output_file, row.names = FALSE)
+message(sprintf("%d LINCS signatures scored. Results saved to %s", nrow(hits), output_file))
+
+print(utils::head(hits[, intersect(c("pert", "cell", "type", "NCS", "NCSct"), colnames(hits))], 20))
+
+## Plot ----
+# The 10 perturbations that most resemble the signature, then the 10 that most
+# reverse it, by NCSct. Each coloured point is one cell line's NCS; the black
+# points summarize the tumor and the normal cell lines. The results are
+# already saved, so a plot that cannot be drawn is reported and not an error.
+n_plotted <- 10
+per_perturbation <- hits[!duplicated(hits$pert), ]
+resembling <- utils::head(per_perturbation$pert[order(per_perturbation$NCSct, decreasing = TRUE)], n_plotted)
+reversing <- utils::head(per_perturbation$pert[order(per_perturbation$NCSct)], n_plotted)
+
+plotted <- tryCatch({
+  top_hits_plot <- suppressWarnings(
+    signatureSearch::gess_res_vis(hits, drugs = unique(c(resembling, reversing)), col = "NCS")
+  ) +
+    ggplot2::labs(
+      title = signature_name,
+      subtitle = "LINCS perturbations that most resemble the signature (left) and most reverse it (right)",
+      x = "Perturbation",
+      y = "Normalized connectivity score (NCS)"
+    )
+  ggplot2::ggsave(plot_file, top_hits_plot, width = 11, height = 7)
+  TRUE
+}, error = function(e) {
+  message("The plot could not be drawn: ", conditionMessage(e))
+  FALSE
+})
+if (plotted) {
+  message(sprintf("Plot saved to %s", plot_file))
+}
diff --git a/man/getHypeRDifexp.Rd b/man/getHypeRDifexp.Rd
new file mode 100644
index 00000000..e7056a7e
--- /dev/null
+++ b/man/getHypeRDifexp.Rd
@@ -0,0 +1,70 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRSignatures.R
+\name{getHypeRDifexp}
+\alias{getHypeRDifexp}
+\title{Difexp tables with resolved gene symbols}
+\usage{
+getHypeRDifexp(
+  conn_handler = NULL,
+  signature_id = NULL,
+  signature_name = NULL,
+  omic_signature = NULL,
+  verbose = TRUE
+)
+}
+\arguments{
+\item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
+Needed to fetch signatures by id/name and for reference-table symbol lookup.}
+
+\item{signature_id}{One or more SigRepo signature IDs.}
+
+\item{signature_name}{One or more SigRepo signature names.}
+
+\item{omic_signature}{An \code{OmicSignature} object or a list of them. List
+names, when given, become the query labels.}
+
+\item{verbose}{Logical; print messages while fetching signatures.}
+}
+\value{
+A named list with one data frame per signature that has a difexp,
+named by signature label (list name, else \code{signature_name}). Each is the
+difexp table plus \code{resolved_symbol} (\code{NA} where no symbol was
+found) and \code{resolved_symbol_source}. Signatures without a difexp are
+left out with a warning.
+}
+\description{
+Returns each signature's difexp table with the gene symbol
+\code{runHypeR()} would use for every row, so you can apply your own cutoffs
+(e.g. a stricter FDR or a fold-change threshold) and pass the resulting gene
+list to \code{runHypeR(signature = ...)}.
+}
+\details{
+Symbols come from the difexp's own symbol column, else the
+reference feature table by \code{feature_name} and organism (needs
+\code{conn_handler}). \code{probe_id} is never read as a symbol.
+\code{runHypeR(signature = ...)} records \code{Symbol Source = "supplied"}
+and no signature ID, so keep the signature id with your results if you need
+it.
+}
+\section{Required and optional arguments}{
+
+The signatures are required, as exactly one of \code{signature_id} or
+\code{signature_name} (each with \code{conn_handler}), or
+\code{omic_signature}; they cannot be combined. \code{signature} is not
+accepted here, because a plain gene vector has no difexp table. Everything
+else is optional: \code{verbose} defaults to \code{TRUE}. With
+\code{omic_signature}, \code{conn_handler} is still worth passing when the
+difexp has no symbol column of its own, since it is what looks symbols up in
+the reference feature table; without it those rows get
+\code{resolved_symbol = NA}.
+}
+
+\examples{
+\dontrun{
+difexp <- SigRepo::getHypeRDifexp(omic_signature = sig)[[1]]
+strict_up <- difexp$resolved_symbol[difexp$adj_p < 0.001 & difexp$score > 0]
+hyp <- SigRepo::runHypeR(signature = list(strict_up = strict_up), organism = "Homo sapiens",
+                         test = "hypergeometric", genesets = hallmark)
+}
+
+}
diff --git a/man/getHypeRGenesets.Rd b/man/getHypeRGenesets.Rd
new file mode 100644
index 00000000..ffde91e1
--- /dev/null
+++ b/man/getHypeRGenesets.Rd
@@ -0,0 +1,69 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRGenesets.R
+\name{getHypeRGenesets}
+\alias{getHypeRGenesets}
+\title{Resolve genesets for hypeR}
+\usage{
+getHypeRGenesets(
+  genesets,
+  msigdb_species = NULL,
+  msigdb_collection = NULL,
+  msigdb_subcollection = NULL,
+  msigdb_clean = FALSE
+)
+}
+\arguments{
+\item{genesets}{Either the string \code{"msigdb"}, or your own genesets: a
+named list of character vectors, a \code{hypeR::gsets} object, or a
+\code{hypeR::rgsets} object.}
+
+\item{msigdb_species}{Species for MSigDB, e.g. \code{"Homo sapiens"} or
+\code{"Mus musculus"}. Defaults to \code{"Homo sapiens"}. Only valid with
+\code{genesets = "msigdb"}.}
+
+\item{msigdb_collection}{MSigDB collection, e.g. \code{"H"}, \code{"C2"},
+\code{"MH"}. Required with \code{genesets = "msigdb"}.}
+
+\item{msigdb_subcollection}{Optional MSigDB subcollection, e.g.
+\code{"CP:REACTOME"}. Only valid with \code{genesets = "msigdb"}.}
+
+\item{msigdb_clean}{Logical; clean geneset labels via
+\code{hypeR::gsets$new(clean = TRUE)}. Defaults to \code{FALSE}.}
+}
+\value{
+For \code{"msigdb"}, a \code{hypeR::gsets} object named after the
+collection (e.g. \code{"C2.CP:REACTOME"}) and versioned by msigdbr. Otherwise
+the supplied genesets, unchanged.
+}
+\description{
+Returns genesets in a form \code{hypeR::hypeR()} accepts. Pass
+\code{genesets = "msigdb"} with \code{msigdb_collection} (and optionally
+\code{msigdb_species}, \code{msigdb_subcollection}) to fetch an MSigDB
+collection, or pass your own genesets object.
+}
+\details{
+Mouse-native collections (\code{MH}, \code{M1}-\code{M8}) use the
+mouse MSigDB database; mouse requests for human collections and all other
+species use the human database with ortholog mapping.
+}
+\section{Required and optional arguments}{
+
+\code{genesets} is required, and \code{msigdb_collection} is required with
+\code{genesets = "msigdb"}. The other \code{msigdb_*} arguments are
+optional (species defaults to \code{"Homo sapiens"}, no subcollection, no
+label cleaning) and apply only to \code{"msigdb"}; passing them with your
+own genesets is an error.
+}
+
+\examples{
+\dontrun{
+hallmark <- SigRepo::getHypeRGenesets("msigdb", msigdb_collection = "H")
+reactome_mouse <- SigRepo::getHypeRGenesets(
+  "msigdb",
+  msigdb_species = "Mus musculus",
+  msigdb_collection = "C2",
+  msigdb_subcollection = "CP:REACTOME"
+)
+}
+
+}
diff --git a/man/hypeRDotData.Rd b/man/hypeRDotData.Rd
new file mode 100644
index 00000000..54367abb
--- /dev/null
+++ b/man/hypeRDotData.Rd
@@ -0,0 +1,85 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlotData.R
+\name{hypeRDotData}
+\alias{hypeRDotData}
+\title{Dot-plot data for runHypeR() results}
+\usage{
+hypeRDotData(
+  hyp_obj,
+  val = c("fdr", "pval"),
+  pval = 1,
+  fdr = 1,
+  top = 20,
+  size_by = c("geneset", "overlap", "none"),
+  signature_key = TRUE,
+  query_labels = NULL,
+  abrv = 50
+)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.}
+
+\item{val}{\code{"fdr"} (default) or \code{"pval"}: the value used to rank
+genesets and to compute \code{significance}.}
+
+\item{pval, fdr}{Keep rows with p-value / FDR at or below these. Default \code{1}.}
+
+\item{top}{Number of genesets to keep, chosen by their best (smallest)
+\code{val} across all queries, so every query shows the same genesets.
+Default \code{20}.}
+
+\item{size_by}{\code{"geneset"} (geneset size, default), \code{"overlap"} or
+\code{"none"}: what the \code{size} column holds.}
+
+\item{signature_key}{\code{TRUE} (default) labels queries by a short
+signature code and group, \code{"S1 | Old"}, with the codes listed by
+\code{hypeRSignatureKey()}; for a single signature the label is the group
+alone (\code{"Old"}). \code{FALSE} uses the full query names.}
+
+\item{query_labels}{\code{NULL} (default) for the labels chosen by
+\code{signature_key}, or a function that takes the query info data frame
+(\code{query}, \code{signature_id}, \code{signature_name},
+\code{group_label}, \code{direction}, \code{test}) and returns one non-empty
+label per row. Duplicates become \code{"label (2)"}.}
+
+\item{abrv}{Geneset labels longer than this many characters are truncated
+with \code{"..."}. Default \code{50}.}
+}
+\value{
+A data frame with \code{query}, \code{query_label} (factor in query
+order), \code{signature_code} (\code{"S1"}, \code{"S2"}, ...; see
+\code{hypeRSignatureKey()}), \code{query_group} (the group label and
+direction that set the query apart within its signature, or \code{""}),
+\code{signature_name}, \code{group_label}, \code{direction},
+\code{test}, \code{label}, \code{label_abrv} (factor ordered so the most
+significant geneset is the last level, i.e. the top row of a plot),
+\code{pval}, \code{fdr}, \code{significance} (-log10 of \code{val}; values of
+0 are floored to a tenth of the smallest positive value, or 1e-300),
+\code{score} (fgsea NES, kstest score, negated for a kstest \code{"| down"}
+query so it is on the original ranking; \code{NA} for hypergeometric) and
+\code{size}. It has 0 rows when nothing passes the cutoffs. Ties for the
+shared \code{top} genesets are broken by the best (smallest) \code{pval}
+across queries, then by label name.
+}
+\description{
+Tidy data behind \code{plotHypeRDots()}: one row per query and
+geneset that passes the cutoffs, restricted to the \code{top} genesets
+shared by every query. Use it to draw your own figure or to serve the numbers
+to another front end.
+}
+\section{Required and optional arguments}{
+
+Only \code{hyp_obj} is required. Every other argument is optional and has the
+default listed with it: genesets ranked by FDR, no p-value or FDR cutoff
+(\code{pval = 1}, \code{fdr = 1}), the 20 best genesets, sized by geneset
+size, queries labelled with signature codes. \code{query_labels = NULL} means
+"use the labels chosen by \code{signature_key}", not "no labels". Pass
+\code{fdr} (e.g. \code{0.05}) to keep only significant genesets.
+}
+
+\examples{
+\dontrun{
+dots <- SigRepo::hypeRDotData(hyp, fdr = 0.05, top = 15)
+}
+
+}
diff --git a/man/hypeREnrichmentData.Rd b/man/hypeREnrichmentData.Rd
new file mode 100644
index 00000000..040a8988
--- /dev/null
+++ b/man/hypeREnrichmentData.Rd
@@ -0,0 +1,73 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlotData.R
+\name{hypeREnrichmentData}
+\alias{hypeREnrichmentData}
+\title{Running enrichment score data for one geneset of a kstest or fgsea result}
+\usage{
+hypeREnrichmentData(hyp_obj, geneset, query = NULL)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp} from \code{runHypeR()} with
+\code{test = "kstest"} or \code{"fgsea"}.}
+
+\item{geneset}{Geneset label, e.g. \code{"HALLMARK_MYC_TARGETS_V1"}.}
+
+\item{query}{Query name (\code{names(hyp_obj$data)}); required for a
+\code{multihyp} with more than one query. For fgsea, whose
+\code{"<ranking> | up"} and \code{"<ranking> | down"} queries come from one
+run on one ranking, the ranking name alone also works: the side whose table
+holds \code{geneset} is used.}
+}
+\value{
+A list with \code{curve} (data frame: \code{position},
+\code{running_score}; for fgsea, \code{curve} holds fgsea's own step
+points, positions \code{0} to \code{N+1}, not one row per ranked gene
+\code{1..N}), \code{ticks} (data frame: \code{position},
+\code{gene}, \code{score}, \code{leading_edge}) and \code{summary} (list:
+\code{query}, \code{ranking} (the ranking the curve walks: for fgsea the
+query name without \code{" | up"}/\code{" | down"}, otherwise the query),
+\code{geneset}, \code{test}, \code{direction}, \code{n_ranked},
+\code{n_hits}, \code{es}, \code{es_position}, \code{leading_edge_genes},
+\code{pval}, \code{fdr}, \code{nes}, \code{score}; the last four are
+\code{NA} when the geneset is not in the result table).
+}
+\description{
+Recomputes the running-sum curve behind one geneset's
+enrichment score from the result itself (the ranking and genesets stored in
+\code{hyp$args}), so no per-geneset plots need to be kept.
+}
+\details{
+The curve reproduces each test's own arithmetic, so \code{es}
+matches the result's \code{score} (kstest) or \code{es} (fgsea) to their 2
+significant digits, ties included:
+\itemize{
+  \item kstest with weights: hypeR's weighted running sum; the first
+  extremum is the enrichment score.
+  \item kstest with \code{power = 0}: hypeR's unweighted statistic.
+  \item fgsea: \code{fgsea::plotEnrichmentData()}; an exact tie between the
+  positive and negative extremum gives 0, as fgsea does.
+}
+The ranking is the one tested: for a kstest \code{"| down"} query it is the
+negated score. The leading edge follows the GSEA convention (hits
+up to the extremum for a positive score, from it for a negative score); for
+kstest with a negative score this can differ from hypeR's \code{hits}
+column, which always counts from the top.
+
+\code{absolute = TRUE} kstest results are not supported: hypeR scores them
+as \code{max(z) - min(z)}, which has no running-sum curve, so this errors
+for them.
+}
+\section{Required and optional arguments}{
+
+\code{hyp_obj} (a kstest or fgsea result) and \code{geneset} are required.
+\code{query} is required only when \code{hyp_obj} holds more than one query;
+for a single \code{hyp}, or a \code{multihyp} with one query, it can be left
+out. For hypergeometric results use \code{plotHypeREnrichment()} instead.
+}
+
+\examples{
+\dontrun{
+curve <- SigRepo::hypeREnrichmentData(gsea, "HALLMARK_MYC_TARGETS_V1", query = "LLFS_Aging_Gene_2023")
+}
+
+}
diff --git a/man/hypeRSignatureKey.Rd b/man/hypeRSignatureKey.Rd
new file mode 100644
index 00000000..77b48b93
--- /dev/null
+++ b/man/hypeRSignatureKey.Rd
@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlotData.R
+\name{hypeRSignatureKey}
+\alias{hypeRSignatureKey}
+\title{Signature codes used in dot-plot labels}
+\usage{
+hypeRSignatureKey(hyp_obj)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.}
+}
+\value{
+A data frame with \code{signature_code} and \code{signature_name}.
+}
+\description{
+The key behind \code{hypeRDotData()}'s and
+\code{plotHypeRDots()}'s short query labels: one row per signature, coded
+\code{"S1"}, \code{"S2"}, ... in the order the signatures first appear in
+the result. A query without a recorded SigRepo signature name counts as its
+own signature, named by the query.
+}
+\section{Required and optional arguments}{
+
+\code{hyp_obj} is the only argument, and it is required.
+}
+
+\examples{
+\dontrun{
+SigRepo::hypeRSignatureKey(hyp)
+}
+
+}
diff --git a/man/hypeRToExcel.Rd b/man/hypeRToExcel.Rd
new file mode 100644
index 00000000..6804e7b3
--- /dev/null
+++ b/man/hypeRToExcel.Rd
@@ -0,0 +1,50 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRClient.R
+\name{hypeRToExcel}
+\alias{hypeRToExcel}
+\title{Write runHypeR() results to Excel with safe sheet names}
+\usage{
+hypeRToExcel(hyp_obj, file_path, cols = NULL, versioning = TRUE, index = TRUE)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.}
+
+\item{file_path}{Path of the \code{.xlsx} file to write (overwritten).}
+
+\item{cols}{Passed to \code{hypeR::hyp_to_excel()}: columns of each result
+table to write. Defaults to all.}
+
+\item{versioning}{Passed to \code{hypeR::hyp_to_excel()}: add hypeR's
+\code{versioning} sheet with each query's \code{info}. Defaults to \code{TRUE}.}
+
+\item{index}{Logical; add the \code{index} sheet. Defaults to \code{TRUE}.}
+}
+\value{
+Invisibly, the index as a data frame: \code{sheet}, \code{query},
+\code{signature_id}, \code{signature_name}, \code{group_label},
+\code{direction}.
+}
+\description{
+Writes a \code{hyp} or \code{multihyp} with
+\code{hypeR::hyp_to_excel()} after turning query names into valid Excel
+sheet names (at most 31 characters, none of \code{: \\ / ? * [ ]}, unique
+regardless of case). An \code{index} sheet, placed first, maps each sheet
+back to its full query name and SigRepo provenance. The object you pass is
+not modified.
+}
+\section{Required and optional arguments}{
+
+\code{hyp_obj} and \code{file_path} are required. \code{cols},
+\code{versioning} and \code{index} are optional: by default every column is
+written, with hypeR's \code{versioning} sheet and the SigRepo \code{index}
+sheet. \code{cols = NULL} means "all columns", not "none".
+}
+
+\examples{
+\dontrun{
+hyp <- SigRepo::runHypeR(omic_signature = sig, organism = "Homo sapiens", test = "hypergeometric",
+                         genesets = "msigdb", msigdb_collection = "H")
+SigRepo::hypeRToExcel(hyp, file_path = "results.xlsx")
+}
+
+}
diff --git a/man/mergeDifexp.Rd b/man/mergeDifexp.Rd
new file mode 100644
index 00000000..a9db3c36
--- /dev/null
+++ b/man/mergeDifexp.Rd
@@ -0,0 +1,117 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mergeDifexp.R
+\name{mergeDifexp}
+\alias{mergeDifexp}
+\title{Merge the difexp tables of several signatures into one matrix}
+\usage{
+mergeDifexp(
+  conn_handler = NULL,
+  signature_ids = NULL,
+  signature_names = NULL,
+  omic_signatures = NULL,
+  value_col = "score",
+  feature_col = "feature_name",
+  features = c("union", "intersect"),
+  collapse = c("max_abs", "min", "mean", "first"),
+  verbose = FALSE
+)
+}
+\arguments{
+\item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
+Required whenever signatures are requested by id or name.}
+
+\item{signature_ids}{Database signature ids to fetch.}
+
+\item{signature_names}{Database signature names to fetch.}
+
+\item{omic_signatures}{An OmicSignature object, a list of OmicSignature
+objects, or an OmicSignatureCollection to include directly.}
+
+\item{value_col}{The difexp column whose values fill the matrix. Defaults
+to \code{"score"}; \code{"logfc"} is the other common choice.}
+
+\item{feature_col}{The difexp column holding feature identifiers, used as
+row names.}
+
+\item{features}{\code{"union"} (the default) keeps every feature found in
+any table, with \code{NA} where a table lacks it; \code{"intersect"} keeps
+only features present in every table.}
+
+\item{collapse}{How to reduce several rows of the same feature within one
+table to a single value: \code{"max_abs"} (the default) keeps the value
+with the largest absolute size, \code{"min"} keeps the smallest value,
+\code{"mean"} averages them, and \code{"first"} keeps the first row as
+stored. Use \code{"min"} with a p-value column such as \code{"p_value"}
+or \code{"adj_p"}, where the smallest value is the most significant;
+\code{"max_abs"} would keep the least significant probe there.}
+
+\item{verbose}{Logical; whether to print diagnostic messages while
+resolving and fetching signatures. Defaults to \code{FALSE}.}
+}
+\value{
+A numeric matrix with features as row names and signatures as
+  column names, in the order the signatures were assembled.
+}
+\description{
+Fetches signatures from the SigRepo database and/or takes OmicSignature
+objects supplied directly, and lines their difexp tables up into a single
+numeric matrix with one row per feature and one column per signature. The
+value in each cell is that signature's \code{value_col} for that feature,
+and \code{NA} where the signature's difexp table has no such feature.
+
+This is the "signature compendium" shape that signature-by-signature
+correlation, clustering, PCA and reference databases for tools such as
+signatureSearch expect. The thresholded signature tables are not used;
+only the full difexp tables are, since those cover every tested feature.
+
+Signatures are assembled the same way as in \code{compareSignatures()}:
+ids and names are resolved with \code{searchSignature()} and fetched with
+\code{getSignature()}, supplied objects come after them, and requests that
+cannot be honoured are reported in a warning and left out. Columns are
+named by the list names of supplied objects (their metadata
+\code{signature_name} when unnamed) and by the database
+\code{signature_name} of fetched ones.
+
+A difexp table often lists one feature several times, once per probe.
+Such rows are collapsed to one value per feature before merging, chosen by
+\code{collapse}. Signatures without a difexp table, or whose difexp table
+has no \code{value_col} or \code{feature_col} column, are dropped with a
+warning naming them; it is an error when that leaves nothing to merge.
+}
+\examples{
+# The bundled example signatures need no database
+utils::data("omic_signature_1", "omic_signature_2", "omic_signature_3", package = "SigRepo")
+
+m <- SigRepo::mergeDifexp(
+  omic_signatures = list(v1 = omic_signature_1, v2 = omic_signature_2, v3 = omic_signature_3)
+)
+dim(m)
+stats::cor(m, use = "pairwise.complete.obs")
+
+\dontrun{
+conn_handler <- SigRepo::newConnHandler(
+  dbname = "sigrepo", host = "localhost", port = 3306,
+  user = "your_username", password = "your_password"
+)
+
+m <- SigRepo::mergeDifexp(
+  conn_handler = conn_handler,
+  signature_ids = c(12, 34),
+  signature_names = "my_signature",
+  value_col = "logfc",
+  features = "intersect"
+)
+
+# Adjusted p-values: keep the most significant probe of a duplicated feature
+p <- SigRepo::mergeDifexp(
+  conn_handler = conn_handler,
+  signature_ids = c(12, 34),
+  value_col = "adj_p",
+  collapse = "min"
+)
+}
+
+}
+\seealso{
+\code{compareSignatures()}, \code{getSignature()}.
+}
diff --git a/man/plotHypeRDots.Rd b/man/plotHypeRDots.Rd
new file mode 100644
index 00000000..4023a95a
--- /dev/null
+++ b/man/plotHypeRDots.Rd
@@ -0,0 +1,100 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlots.R
+\name{plotHypeRDots}
+\alias{plotHypeRDots}
+\title{Dot plot of runHypeR() results across queries}
+\usage{
+plotHypeRDots(
+  hyp_obj,
+  val = c("fdr", "pval"),
+  pval = 1,
+  fdr = 1,
+  top = 20,
+  color_by = c("significance", "score"),
+  size_by = c("geneset", "overlap", "none"),
+  signature_key = TRUE,
+  query_labels = NULL,
+  abrv = 50,
+  title = NULL
+)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.}
+
+\item{val}{\code{"fdr"} (default) or \code{"pval"}: the value used to rank
+genesets and to compute \code{significance}.}
+
+\item{pval, fdr}{Keep rows with p-value / FDR at or below these. Default \code{1}.}
+
+\item{top}{Number of genesets to keep, chosen by their best (smallest)
+\code{val} across all queries, so every query shows the same genesets.
+Default \code{20}.}
+
+\item{color_by}{\code{"significance"} (default: -log10 of \code{val}) or
+\code{"score"} (NES for fgsea, the enrichment score for kstest) on a
+diverging scale centred at 0. \code{"score"} is an error for hypergeometric
+results.}
+
+\item{size_by}{\code{"geneset"} (geneset size, default), \code{"overlap"} or
+\code{"none"}: what the \code{size} column holds.}
+
+\item{signature_key}{\code{TRUE} (default) labels queries by a short
+signature code and group, \code{"S1 | Old"}, with the codes listed by
+\code{hypeRSignatureKey()}; for a single signature the label is the group
+alone (\code{"Old"}). \code{FALSE} uses the full query names.}
+
+\item{query_labels}{\code{NULL} (default) for the labels chosen by
+\code{signature_key}, or a function that takes the query info data frame
+(\code{query}, \code{signature_id}, \code{signature_name},
+\code{group_label}, \code{direction}, \code{test}) and returns one non-empty
+label per row. Duplicates become \code{"label (2)"}.}
+
+\item{abrv}{Geneset labels longer than this many characters are truncated
+with \code{"..."}. Default \code{50}.}
+
+\item{title}{Plot title; defaults to the test that was run
+(\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}).}
+}
+\value{
+A \code{ggplot}. When nothing passes the cutoffs, a blank plot that
+says so.
+}
+\description{
+One column per query and one row per geneset, for a
+\code{hyp} or a \code{multihyp} of any length. Every query shows the same
+\code{top} genesets (the best by \code{val} across all queries); a blank cell
+means the geneset did not pass the cutoffs for that query. Significance is
+drawn as -log10 values on a plain scale, so axes and legends stay readable
+whatever the ggplot2 version. See \code{hypeRDotData()} for the data.
+}
+\details{
+With \code{signature_key = TRUE} (the default) and several
+signatures, each signature's columns sit together under its code
+(\code{S1}, \code{S2}, ...), labelled by group or direction at 45 degrees,
+and the caption lists what each code stands for. A single signature is named
+in the subtitle, with its group labels horizontal while they fit. With
+\code{signature_key = FALSE} or \code{query_labels}, the labels are drawn
+at 45 degrees and the left margin grows when they reach past the geneset
+labels. Save with
+\code{ggplot2::ggsave()}. A readable size is roughly
+width = 5 + 0.085 x (longest geneset label, in characters) + 1.2 x (queries)
+inches, clamped to 7-20, and height = 1.6 + 0.30 x (genesets) + 0.05 x
+(longest query name, in characters) inches, clamped to 3.2-22.
+}
+\section{Required and optional arguments}{
+
+Only \code{hyp_obj} is required, so \code{plotHypeRDots(hyp)} works on any
+\code{runHypeR()} result. Every other argument is optional and has the
+default listed with it: the 20 best genesets by FDR with no cutoff, coloured
+by significance and sized by geneset size, with the title naming the test.
+\code{title = NULL} and \code{query_labels = NULL} mean "choose for me", not
+"none". \code{color_by = "score"} needs kstest or fgsea results.
+}
+
+\examples{
+\dontrun{
+SigRepo::plotHypeRDots(hyp, fdr = 0.05)
+SigRepo::plotHypeRDots(gsea, color_by = "score")
+}
+
+}
diff --git a/man/plotHypeREnrichment.Rd b/man/plotHypeREnrichment.Rd
new file mode 100644
index 00000000..ad1f13fe
--- /dev/null
+++ b/man/plotHypeREnrichment.Rd
@@ -0,0 +1,50 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlots.R
+\name{plotHypeREnrichment}
+\alias{plotHypeREnrichment}
+\title{Enrichment figure for one geneset of a runHypeR() result}
+\usage{
+plotHypeREnrichment(hyp_obj, geneset, query = NULL, title = NULL)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp} from \code{runHypeR()} with
+\code{test = "kstest"} or \code{"fgsea"}.}
+
+\item{geneset}{Geneset label, e.g. \code{"HALLMARK_MYC_TARGETS_V1"}.}
+
+\item{query}{Query name (\code{names(hyp_obj$data)}); required for a
+\code{multihyp} with more than one query. For fgsea, whose
+\code{"<ranking> | up"} and \code{"<ranking> | down"} queries come from one
+run on one ranking, the ranking name alone also works: the side whose table
+holds \code{geneset} is used.}
+
+\item{title}{Plot title; defaults to the test that was run
+(\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}).
+The geneset label is the first line of the subtitle.}
+}
+\value{
+A \code{ggplot}.
+}
+\description{
+For kstest and fgsea results, the running enrichment score
+along the ranking with the geneset's hits marked below it (leading edge
+highlighted). For hypergeometric results, hypeR's Venn diagram of the query
+and the geneset. Both are drawn from the result itself, so they work for any
+geneset without \code{runHypeR(plotting = TRUE)} storing every plot.
+}
+\section{Required and optional arguments}{
+
+\code{hyp_obj} and \code{geneset} (a geneset label from the result) are
+required. \code{query} is required only when \code{hyp_obj} holds more than
+one query; for a single \code{hyp}, or a \code{multihyp} with one query, it
+can be left out. For fgsea the ranking name without \code{" | up"} or
+\code{" | down"} is enough. \code{title} is optional and defaults to the test
+that was run.
+}
+
+\examples{
+\dontrun{
+SigRepo::plotHypeREnrichment(gsea, "HALLMARK_MYC_TARGETS_V1", query = "LLFS_Aging_Gene_2023")
+}
+
+}
diff --git a/man/plotHypeRMap.Rd b/man/plotHypeRMap.Rd
new file mode 100644
index 00000000..d2386c5d
--- /dev/null
+++ b/man/plotHypeRMap.Rd
@@ -0,0 +1,71 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hypeRPlots.R
+\name{plotHypeRMap}
+\alias{plotHypeRMap}
+\title{Enrichment or hierarchy map of runHypeR() results}
+\usage{
+plotHypeRMap(
+  hyp_obj,
+  type = c("emap", "hmap"),
+  query = NULL,
+  val = c("fdr", "pval"),
+  pval = 1,
+  fdr = 1,
+  top = 25,
+  similarity_metric = c("jaccard_similarity", "overlap_similarity"),
+  similarity_cutoff = 0.2,
+  title = NULL
+)
+}
+\arguments{
+\item{hyp_obj}{A \code{hyp} or \code{multihyp}, usually from \code{runHypeR()}.}
+
+\item{type}{\code{"emap"} (default) or \code{"hmap"}.}
+
+\item{query}{Query name; with \code{NULL} a \code{multihyp} of several queries
+gives a named list with one map per query.}
+
+\item{val}{\code{"fdr"} (default) or \code{"pval"}: the value that colours
+the map's nodes. Unlike \code{hypeRDotData()}, it does not rank genesets or
+choose \code{top}.}
+
+\item{pval, fdr}{Keep rows with p-value / FDR at or below these. Default \code{1}.}
+
+\item{top}{The first \code{top} rows of each result table after the
+cutoffs, in table order (not chosen by \code{val}). Default \code{25}.}
+
+\item{similarity_metric, similarity_cutoff}{Passed to \code{hypeR::hyp_emap()}.}
+
+\item{title}{Map title; defaults to the test that was run
+(\code{"Hypergeometric test"}, \code{"KS test"} or \code{"GSEA (fgsea)"}),
+with the query name below it.}
+}
+\value{
+A \code{visNetwork} widget, \code{NULL} (with a warning) when there is
+nothing to draw, or a named list of those for several queries.
+}
+\description{
+Draws hypeR's enrichment map (\code{hypeR::hyp_emap()}, genesets
+linked by shared genes) or hierarchy map (\code{hypeR::hyp_hmap()}, needs
+\code{rgsets} genesets), after checking the cases where hypeR would fail:
+no geneset passing the cutoffs, or no pair of genesets reaching
+\code{similarity_cutoff}. Those return \code{NULL} with a warning instead of
+an error.
+}
+\section{Required and optional arguments}{
+
+Only \code{hyp_obj} is required. Every other argument is optional and has the
+default listed with it: an enrichment map (\code{type = "emap"}) of the
+first 25 rows with no p-value or FDR cutoff, nodes coloured by FDR, and edges
+where the Jaccard similarity is at least 0.2. \code{query = NULL} draws every
+query (one map for a single query, a named list for several), not "none".
+\code{type = "hmap"} also needs results run on \code{hypeR::rgsets}
+genesets.
+}
+
+\examples{
+\dontrun{
+SigRepo::plotHypeRMap(hyp, query = "LLFS_Aging_Gene_2023 | Group1", fdr = 0.05)
+}
+
+}
diff --git a/man/prepareHypeRSignatures.Rd b/man/prepareHypeRSignatures.Rd
index 300083c6..99a2e247 100644
--- a/man/prepareHypeRSignatures.Rd
+++ b/man/prepareHypeRSignatures.Rd
@@ -1,64 +1,136 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/hypeRClient.R
+% Please edit documentation in R/hypeRSignatures.R
 \name{prepareHypeRSignatures}
 \alias{prepareHypeRSignatures}
-\title{Build hypeR-ready signature vectors from SigRepo signatures}
+\title{Build hypeR query vectors from SigRepo signatures}
 \usage{
 prepareHypeRSignatures(
   conn_handler = NULL,
   signature_id = NULL,
   signature_name = NULL,
   omic_signature = NULL,
-  method = c("hypergeo", "kstest", "gsea"),
-  feature_col = "feature_name",
+  signature = NULL,
+  test = c("hypergeometric", "kstest", "fgsea"),
+  split = TRUE,
+  ks_source = c("difexp", "signature"),
   score_col = "score",
-  split_by_group = FALSE,
-  split_by_direction = FALSE,
+  query_names = NULL,
   verbose = TRUE
 )
 }
 \arguments{
 \item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
-Required unless \code{omic_signature} is supplied.}
+Needed to fetch signatures by id/name and for reference-table symbol lookup.}
 
 \item{signature_id}{One or more SigRepo signature IDs.}
 
 \item{signature_name}{One or more SigRepo signature names.}
 
-\item{omic_signature}{A single \code{OmicSignature} object or a list of
-\code{OmicSignature} objects.}
+\item{omic_signature}{An \code{OmicSignature} object or a list of them. List
+names, when given, become the query labels.}
 
-\item{method}{One of \code{"hypergeo"}, \code{"kstest"}, or \code{"gsea"}.
-Hypergeometric enrichment uses the \code{signature} table. KS/GSEA-style
-enrichment use ranked scores from \code{difexp}.}
+\item{signature}{hypeR-native input instead of SigRepo signatures: a
+character vector of gene symbols, a named numeric vector of scores (kstest
+only), or a named list of those, as \code{hypeR::hypeR()} takes. A vector is
+used in the order given (it is the ranking for kstest); NA and empty symbols
+are removed. Cannot be combined with \code{omic_signature},
+\code{signature_id} or \code{signature_name}; \code{split},
+\code{score_col} are ignored and \code{ks_source} must stay at its
+default. For \code{"kstest"}, each vector is tested as given
+(\code{"<name> | up"}) and reversed (\code{"<name> | down"}, with negated
+scores). Use \code{getHypeRDifexp()} to build a gene list from
+a signature's difexp with your own cutoffs.}
 
-\item{feature_col}{Column containing feature identifiers. Defaults to
-\code{"feature_name"}.}
+\item{test}{\code{"hypergeometric"} (a character vector of symbols from the
+signature table), \code{"kstest"} (a named numeric vector ranked by
+\code{score_col}, from the table named by \code{ks_source}) or
+\code{"fgsea"} (the "up" ranking of \code{"kstest"}: one ranking per
+signature, or per category for a categorical signature, and
+\code{info$direction} is \code{"both"}). With \code{"fgsea"},
+\code{signature} input must be named numeric vectors. Both ranked tests
+always test both ends of the ranking: hypeR's KS test only finds genesets
+enriched toward the top, so \code{"kstest"} builds two queries per ranking,
+\code{"<label> | up"} (highest scores first) and \code{"<label> | down"}
+(the negated scores, so the lowest come first), whose p-values are adjusted
+for multiple testing together; \code{"fgsea"} tests both tails in one run
+and returns \code{"<label> | up"} (ES > 0) and \code{"<label> | down"}
+(ES < 0). A categorical signature is ranked separately within each
+\code{group_label}, using only that category's rows
+(\code{"<label> | <group> | up"} / \code{" | down"}). A ranking needs a
+signed score: one whose scores are all equal (\code{constant_score}) or all
+one sign (\code{unsigned_score}) is skipped, per category for categorical
+signatures.}
 
-\item{score_col}{Column containing ranked scores for KS/GSEA-style enrichment.
-Defaults to \code{"score"}.}
+\item{split}{Logical; for \code{"hypergeometric"}, build one vector per
+\code{group_label} (e.g. one per arm of a bi-directional signature). A
+categorical signature's groups are categories rather than directions, so when
+its signature table has scores each category is also split by score sign:
+\code{"<label> | <group> | up"} (score > 0) and \code{"... | down"}
+(score < 0); rows scoring exactly 0 join neither. Ignored by
+\code{"kstest"} and \code{"fgsea"}. Defaults to \code{TRUE}.}
 
-\item{split_by_group}{Logical; whether to create separate query vectors for
-each \code{group_label}. Defaults to \code{FALSE}.}
+\item{ks_source}{For \code{"kstest"} and \code{"fgsea"} only: the table to
+rank. \code{"difexp"} (default) ranks every measured gene. \code{"signature"}
+ranks only the signature table, for signatures stored without a difexp; the
+KS test then compares genesets against the signature's genes rather than
+against everything measured, so its p-values answer a narrower question.}
 
-\item{split_by_direction}{Logical; when \code{method = "hypergeo"}, whether
-to split each group into up- and down-direction feature sets using the sign
-of \code{score_col}. Defaults to \code{FALSE}.}
+\item{score_col}{Column used to rank genes for \code{"kstest"} and
+\code{"fgsea"}, in the table named by \code{ks_source}. Defaults to
+\code{"score"}.}
 
-\item{verbose}{Logical; whether or not to print diagnostic messages while
-retrieving signatures. Defaults to \code{TRUE}.}
+\item{query_names}{\code{NULL} (default) for names built as
+\code{"<label> | <group_label>"}, \code{"<label> | <direction>"} or
+\code{"<label>"}, or a function that takes the query info data frame (the
+\code{info} element described under Value, with those default names in
+\code{query}) and returns one non-empty name per row. Duplicates are made
+unique as \code{name (2)}. For example
+\code{function(info) paste(info$signature_id, info$group_label, sep = "_")}.}
+
+\item{verbose}{Logical; print messages while fetching signatures.}
 }
 \value{
-A list with three elements:
+A list with
 \describe{
-  \item{\code{signatures}}{A named list of query vectors for \code{hypeR}.}
-  \item{\code{metadata}}{A data frame describing each generated query vector.}
-  \item{\code{omic_signatures}}{The resolved \code{OmicSignature} objects.}
+  \item{\code{signatures}}{Named list of query vectors, ready for \code{hypeR::hypeR()}.}
+  \item{\code{info}}{Data frame, one row per query: \code{query}, \code{signature_id},
+  \code{signature_name}, \code{group_label}, \code{direction} (kstest only),
+  \code{n_features}, \code{n_dropped} (rows without a gene symbol or score),
+  \code{symbol_source}.}
+  \item{\code{skipped}}{Data frame of signatures (or, for a categorical
+  kstest, \code{"<label> | <group>"} categories) that produced no query:
+  \code{signature}, \code{reason} (\code{empty_signature},
+  \code{no_gene_symbols}, \code{no_difexp}, \code{missing_score_col},
+  \code{no_group_label}, \code{constant_score}, \code{unsigned_score}),
+  \code{message}.}
 }
 }
 \description{
-Converts one or more SigRepo signatures into the query-vector
-format expected by \code{hypeR::hypeR()}. This helper can resolve signatures
-directly from the SigRepo database, so users do not need to call
-\code{getSignature()} manually first.
+Turns SigRepo signatures into the query vectors
+\code{hypeR::hypeR()} takes, and reports how each was built. Use it to
+inspect exactly what \code{runHypeR()} will test.
+}
+\details{
+Gene symbols come from the first source that works: a symbol column
+(\code{gene_symbol}, \code{symbol}, \code{geneSymbol}, \code{gene},
+\code{hgnc_symbol}, \code{mgi_symbol}) in the table itself; for the
+signature table, the difexp's symbol column joined on \code{probe_id};
+then the reference feature table by \code{feature_name} and organism (needs
+\code{conn_handler}). \code{probe_id} is never read as a symbol.
+}
+\section{Required and optional arguments}{
+
+The signatures are required, as exactly one of \code{signature_id} or
+\code{signature_name} (each with \code{conn_handler}),
+\code{omic_signature}, or \code{signature}; they cannot be combined. Every
+other argument is optional and has the default listed with it, which is what
+\code{runHypeR()} uses unless you pass something else. No genesets are
+needed: this builds the queries, it does not test them.
+}
+
+\examples{
+utils::data("LLFS_Aging_Gene_2023", package = "SigRepo")
+prepared <- SigRepo::prepareHypeRSignatures(omic_signature = LLFS_Aging_Gene_2023, verbose = FALSE)
+prepared$info
+
 }
diff --git a/man/runHypeR.Rd b/man/runHypeR.Rd
index a3a13001..74d6fd7d 100644
--- a/man/runHypeR.Rd
+++ b/man/runHypeR.Rd
@@ -2,121 +2,314 @@
 % Please edit documentation in R/hypeRClient.R
 \name{runHypeR}
 \alias{runHypeR}
-\title{Run hypeR enrichment directly from SigRepo signatures}
+\title{Run hypeR enrichment on SigRepo signatures}
 \usage{
 runHypeR(
   conn_handler = NULL,
   signature_id = NULL,
   signature_name = NULL,
   omic_signature = NULL,
-  genesets = NULL,
-  msigdb_species = "Homo sapiens",
+  signature = NULL,
+  organism,
+  test,
+  genesets,
   msigdb_collection = NULL,
   msigdb_subcollection = NULL,
   msigdb_clean = FALSE,
-  method = c("hypergeo", "kstest", "gsea"),
-  feature_col = "feature_name",
+  split = TRUE,
+  ks_source = c("difexp", "signature"),
   score_col = "score",
-  split_by_group = FALSE,
-  split_by_direction = FALSE,
+  query_names = NULL,
+  min_query_genes = 4,
+  fdr_scope = c("run", "query"),
+  seed = 1,
+  fgsea_args = base::list(),
   background = NULL,
-  fdr = 0.05,
+  power = 1,
+  pval = 1,
+  fdr = 1,
   plotting = FALSE,
   quiet = TRUE,
-  absolute = FALSE,
-  power = 1,
-  ...,
   verbose = TRUE
 )
 }
 \arguments{
 \item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
-Required unless \code{omic_signature} is supplied.}
+Needed to fetch signatures by id/name and for reference-table symbol lookup.}
 
 \item{signature_id}{One or more SigRepo signature IDs.}
 
 \item{signature_name}{One or more SigRepo signature names.}
 
-\item{omic_signature}{A single \code{OmicSignature} object or a list of
-\code{OmicSignature} objects.}
+\item{omic_signature}{An \code{OmicSignature} object or a list of them. List
+names, when given, become the query labels.}
+
+\item{signature}{hypeR-native input instead of SigRepo signatures: a
+character vector of gene symbols, a named numeric vector of scores (kstest
+only), or a named list of those, as \code{hypeR::hypeR()} takes. A vector is
+used in the order given (it is the ranking for kstest); NA and empty symbols
+are removed. Cannot be combined with \code{omic_signature},
+\code{signature_id} or \code{signature_name}; \code{split},
+\code{score_col} are ignored and \code{ks_source} must stay at its
+default. For \code{"kstest"}, each vector is tested as given
+(\code{"<name> | up"}) and reversed (\code{"<name> | down"}, with negated
+scores). Use \code{getHypeRDifexp()} to build a gene list from
+a signature's difexp with your own cutoffs.}
+
+\item{organism}{Required. The organism of the signatures, e.g.
+\code{"Homo sapiens"} or \code{"Mus musculus"}, compared with each SigRepo
+signature's \code{metadata$organism} ignoring case. A signature of another
+organism, or with none recorded, is an error: one call tests one organism,
+because genesets are organism-specific gene symbols. With
+\code{genesets = "msigdb"} it is also the MSigDB species. With
+\code{signature} input there is no metadata to check, so it only chooses
+the MSigDB species.}
+
+\item{test}{Required: \code{"hypergeometric"} (a character vector of
+symbols from the signature table), \code{"kstest"} (a named numeric vector
+ranked by \code{score_col}, from the table named by \code{ks_source}) or
+\code{"fgsea"} (the same ranking as \code{"kstest"}, tested with
+\code{fgsea::fgseaMultilevel()}). With \code{"fgsea"}, \code{signature}
+input must be named numeric vectors.}
 
-\item{genesets}{A named list of genesets, a \code{hypeR} \code{gsets}
-object, or a \code{hypeR} \code{rgsets} object supplied to \code{hypeR}.
-Alternatively, leave this as \code{NULL} and specify
-\code{msigdb_collection} to fetch genesets from MSigDB automatically.}
+\item{genesets}{Either the string \code{"msigdb"}, or your own genesets: a
+named list of character vectors, a \code{hypeR::gsets} object, or a
+\code{hypeR::rgsets} object.}
 
-\item{msigdb_species}{Species passed to \code{hypeR::msigdb_gsets()} when
-\code{msigdb_collection} is supplied. Defaults to \code{"Homo sapiens"}.}
+\item{msigdb_collection}{MSigDB collection, e.g. \code{"H"}, \code{"C2"},
+\code{"MH"}. Required with \code{genesets = "msigdb"}.}
 
-\item{msigdb_collection}{MSigDB collection identifier, such as \code{"H"}
-or \code{"C2"}. When supplied, \code{runHypeR()} retrieves genesets
-automatically via \code{hypeR::msigdb_gsets()}.}
+\item{msigdb_subcollection}{Optional MSigDB subcollection, e.g.
+\code{"CP:REACTOME"}. Only valid with \code{genesets = "msigdb"}.}
 
-\item{msigdb_subcollection}{Optional MSigDB subcollection identifier, such as
-\code{"CP:KEGG_LEGACY"}.}
+\item{msigdb_clean}{Logical; clean geneset labels via
+\code{hypeR::gsets$new(clean = TRUE)}. Defaults to \code{FALSE}.}
 
-\item{msigdb_clean}{Logical; whether to clean MSigDB geneset labels using
-\code{hypeR::msigdb_gsets(clean = ...)}. Defaults to \code{FALSE}.}
+\item{split}{Logical; for \code{"hypergeometric"}, build one vector per
+\code{group_label} (e.g. one per arm of a bi-directional signature). A
+categorical signature's groups are categories rather than directions, so when
+its signature table has scores each category is also split by score sign:
+\code{"<label> | <group> | up"} (score > 0) and \code{"... | down"}
+(score < 0); rows scoring exactly 0 join neither. Ignored by
+\code{"kstest"} and \code{"fgsea"}. Defaults to \code{TRUE}.}
 
-\item{method}{One of \code{"hypergeo"}, \code{"kstest"}, or \code{"gsea"}.}
+\item{ks_source}{For \code{"kstest"} and \code{"fgsea"} only: the table to
+rank. \code{"difexp"} (default) ranks every measured gene. \code{"signature"}
+ranks only the signature table, for signatures stored without a difexp; the
+KS test then compares genesets against the signature's genes rather than
+against everything measured, so its p-values answer a narrower question.}
 
-\item{feature_col}{Column containing feature identifiers. Defaults to
-\code{"feature_name"}.}
+\item{score_col}{Column used to rank genes for \code{"kstest"} and
+\code{"fgsea"}, in the table named by \code{ks_source}. Defaults to
+\code{"score"}.}
 
-\item{score_col}{Column containing ranked scores for KS/GSEA-style enrichment.
-Defaults to \code{"score"}.}
+\item{query_names}{\code{NULL} (default) for names built as
+\code{"<label> | <group_label>"}, \code{"<label> | <direction>"} or
+\code{"<label>"}, or a function that takes the query info data frame (the
+\code{info} element described under Value, with those default names in
+\code{query}) and returns one non-empty name per row. Duplicates are made
+unique as \code{name (2)}. For example
+\code{function(info) paste(info$signature_id, info$group_label, sep = "_")}.}
 
-\item{split_by_group}{Logical; whether to create separate query vectors for
-each \code{group_label}. Defaults to \code{FALSE}.}
+\item{min_query_genes}{Hypergeometric only: skip, with a warning, a query
+with fewer than this many genes found in the genesets. Defaults to \code{4},
+the \code{min.drawsize} of BS831's \code{hyperEnrichment()}.}
 
-\item{split_by_direction}{Logical; when \code{method = "hypergeo"}, whether
-to split each group into up- and down-direction feature sets using the sign
-of \code{score_col}. Defaults to \code{FALSE}.}
+\item{fdr_scope}{\code{"run"} (default) adjusts p-values for multiple testing
+across every query and geneset in the call, as BS831's
+\code{hyperEnrichment()} does across signatures; \code{"query"} adjusts
+within each query, as \code{hypeR::hypeR()} does for a named list. With one
+query both are the same. The pooled FDR is computed from hypeR's p-values,
+which are rounded to 2 significant digits. \code{pval} and \code{fdr} filter
+on the FDR of the chosen scope. For \code{test = "fgsea"}, \code{"run"}
+pools the up and down sides of every ranking in the call (also with a
+single ranking); \code{"query"} keeps
+fgsea's own per-ranking \code{padj}, which already covers both sides.}
 
-\item{background}{Optional background size passed to \code{hypeR}.}
+\item{seed}{\code{test = "fgsea"} only: fgsea's p-values come from random
+sampling, so each ranking's run starts from \code{set.seed(seed)} and the
+caller's random-number state is restored afterwards. Defaults to \code{1};
+\code{NULL} uses the session's random-number state. Recorded as \code{Seed}
+in \code{info}.}
 
-\item{fdr}{FDR threshold passed to \code{hypeR}. Defaults to \code{0.05}.}
+\item{fgsea_args}{\code{test = "fgsea"} only: a named list of
+\code{fgsea::fgseaMultilevel()} arguments merged over the defaults
+\code{sampleSize = 101, minSize = 1, maxSize = Inf}, e.g.
+\code{list(minSize = 15, maxSize = 500, nproc = 4)}. \code{stats},
+\code{pathways} and \code{gseaParam} (set by \code{power}) cannot be given.}
 
-\item{plotting}{Logical; whether to let \code{hypeR} generate plots.
-Defaults to \code{FALSE}.}
+\item{background}{\code{NULL} (default) uses each signature's measured genes
+from its difexp table when it has difexp gene symbols, and \code{23467}
+otherwise (always \code{23467} for \code{signature} input). A difexp that
+looks filtered is not a measured-gene universe, so the default also uses
+\code{23467}, with a warning, when a transcriptomics difexp has fewer than
+10,000 rows, a difexp has no more than twice its signature's rows, or every
+\code{p_value}, \code{pvalue} or \code{adj_p} is at most 0.05. For
+\code{test = "kstest"} the default is \code{23467}: the ranked list is the
+universe, so the background does not enter the test. \code{test = "fgsea"}
+defaults to \code{23467} as well and for the same reason (the ranking is
+the universe): a number has no effect on the fgsea result, while a gene
+vector or \code{"difexp"} still reduces the genesets and the ranking to
+those genes. Otherwise
+hypeR's background: a single number (population size), a
+character vector of background genes, or \code{"difexp"} to use each
+signature's measured genes from its difexp table. With an explicit
+\code{"difexp"}, signatures without difexp
+symbols fall back to \code{23467} with a warning. For a different background
+per signature, pass a named list of those forms, one element per signature,
+named by signature label (see \code{prepareHypeRSignatures()$info$signature_name};
+with \code{signature}, the list names) or by signature ID; arms of a split
+signature share its background. A name that matches no signature, or a
+signature with no entry, is an error. With a gene vector or
+\code{"difexp"}, every query (the hypergeometric gene list, or the kstest
+and fgsea ranking) is first reduced to the background genes, with a warning
+naming each query that lost genes: hypeR reduces only the genesets, and
+query genes outside the background would distort the p-values. A query left
+with no genes is skipped with a warning. Anything else (e.g.
+\code{"Difexp"}) is an error.}
 
-\item{quiet}{Logical; whether to suppress \code{hypeR} messages.
-Defaults to \code{TRUE}.}
+\item{power}{Exponent for the score weights: fgsea's \code{gseaParam} with
+\code{test = "fgsea"}, where it does change the p-values. For kstest it changes
+only the enrichment \code{score}. \code{1} (default) weights hits by
+|score|. \code{0} runs hypeR's ranked (unweighted) signature: the query is
+passed as gene names in rank order, so \code{score} and
+\code{Signature Type = "ranked"} match hypeR's documented ranked test. The
+\code{pval} and \code{fdr} come from hypeR's unweighted, one-sided KS test
+and do not depend on \code{power}. That test finds
+genesets enriched toward the top of the ranking, which is why every kstest
+also runs a \code{"| down"} query on the negated scores. hypeR's kstest also cannot score a geneset whose hits in
+a query all have score 0 (\code{power != 0}) or that contains every query
+gene (any power); such genesets are dropped for that query with a warning,
+which also removes them from the FDR adjustment. They are listed in the
+result's \code{info} (see Value). A kstest query left with a single geneset
+is still tested (hypeR itself errors on a one-geneset list); its FDR equals
+its p-value. hypeR's \code{absolute} option is not offered: hypeR marks it
+as not implemented, and \code{runHypeR()} always runs with
+\code{absolute = FALSE}.}
 
-\item{absolute}{Passed to \code{hypeR} for GSEA-style ranked enrichment.
-Defaults to \code{FALSE}.}
+\item{pval}{Keep results with p-value at or below this. Defaults to \code{1}.}
 
-\item{power}{Passed to \code{hypeR} for GSEA-style ranked enrichment.
-Defaults to \code{1}.}
+\item{fdr}{Keep results with FDR at or below this. Defaults to \code{1}.}
 
-\item{...}{Additional arguments passed directly to \code{hypeR::hypeR()}.
-Use this for extra tuning parameters such as \code{background} or other
-engine-specific options.}
+\item{plotting}{Logical; generate hypeR's per-geneset plots. Defaults to
+\code{FALSE}, in which case the empty placeholder plots hypeR stores anyway
+are removed (they are most of the object's size). fgsea makes no plots, so
+\code{TRUE} with \code{test = "fgsea"} warns and is ignored. To plot one
+geneset without storing every plot, use \code{plotHypeREnrichment()}.}
 
-\item{verbose}{Logical; whether or not to print diagnostic messages while
-retrieving signatures. Defaults to \code{TRUE}.}
+\item{quiet}{Logical; suppress hypeR's logs. Defaults to \code{TRUE}. With
+\code{test = "fgsea"} this also suppresses fgsea's own console output
+(its progress bars).}
+
+\item{verbose}{Logical; print messages while fetching signatures.}
 }
 \value{
-A list with:
-\describe{
-  \item{\code{result}}{A \code{hyp} or \code{multihyp} object returned by \code{hypeR}.}
-  \item{\code{signatures}}{The query vectors passed into \code{hypeR}.}
-  \item{\code{metadata}}{A data frame describing each query vector.}
-}
+A \code{hyp} when the input is a single vector in \code{signature},
+or a single signature (one \code{OmicSignature}, or one id or name) and the
+test builds one query by construction (hypergeometric with
+\code{split = FALSE}, or a single \code{signature} vector). Otherwise a
+\code{multihyp} named by query, even when only one query is left: the
+ranked tests always return an \code{"| up"} and a \code{"| down"} query
+per ranking. This mirrors hypeR, where a vector gives a \code{hyp} and a
+named list a \code{multihyp}.
+
+With \code{test = "fgsea"}, each ranking runs
+\code{fgsea::fgseaMultilevel()} once, and its pathways are split by the sign
+of their enrichment score into \code{"<query> | up"} (ES > 0) and
+\code{"<query> | down"} (ES < 0) hyps; pathways with ES = 0 join
+neither. Their \code{data} has \code{label}, \code{pval}, \code{fdr},
+\code{lte} (log2err), \code{es}, \code{nes}, \code{signature},
+\code{geneset}, \code{overlap}, \code{le} and \code{hits} (the leading
+edge), and \code{info} adds \code{fgsea}, \code{Sample Size},
+\code{Min Size}, \code{Max Size}, \code{Seed} and \code{fgsea Args}
+before the SigRepo keys. fgsea's own FDR covers every pathway of the
+ranking, both sides.
+
+Each \code{hyp$info} ends with these keys, in this order (\code{""} when a
+key does not apply): \code{SigRepo Signature ID},
+\code{SigRepo Signature Name}, \code{Group Label}, \code{Symbol Source},
+\code{SigRepo Direction}, \code{SigRepo Ranked Table},
+\code{SigRepo Score Column}, \code{SigRepo Split},
+\code{SigRepo Background Source} (\code{number}, \code{genes},
+\code{difexp}, \code{difexp-fallback} or \code{difexp-truncated}),
+\code{SigRepo Features Unmapped}, \code{SigRepo Query Genes Removed},
+\code{SigRepo Genesets Dropped}, \code{SigRepo Genesets Dropped List} and
+\code{SigRepo FDR Scope}.
+
+Signatures that cannot produce a query are skipped with a warning; if none
+can, an error is raised. A query left with no genesets or no genes (after
+the drops described under \code{power} and \code{background}), or a
+hypergeometric query below \code{min_query_genes}, is skipped with a
+warning; if no query is left, an error is raised.
 }
 \description{
-Resolves one or more signatures from SigRepo and runs
-\code{hypeR::hypeR()} on them without requiring the user to call
-\code{getSignature()} manually first.
+Builds hypeR query vectors from SigRepo signatures (see
+\code{prepareHypeRSignatures()}) and runs \code{hypeR::hypeR()} on them. The
+arguments after \code{query_names} are hypeR's own, with hypeR's defaults,
+and the result is hypeR's own object. Plot it with \code{plotHypeRDots()},
+\code{plotHypeREnrichment()} and \code{plotHypeRMap()}; hypeR's own
+\code{hypeR::hyp_dots()},
+\code{hyp_emap()}, \code{hyp_to_rmd()}, \code{hyp_to_table()} and
+\code{rctbl_build()} work on it directly, and \code{hyp_hmap()} does when
+\code{genesets} is a \code{hypeR::rgsets}. \code{hyp_show()} takes a single
+\code{hyp}, so pass one element of a \code{multihyp}, e.g.
+\code{hypeR::hyp_show(res$data[[1]])}; \code{hyp_to_graph()} also needs
+\code{rgsets} genesets.
+
+\code{hypeR::hyp_to_excel()} uses each query name as an Excel sheet name,
+which must be at most 31 characters and cannot contain
+\code{: \\ / ? * [ ]}; most SigRepo signature names are longer. Use
+\code{hypeRToExcel()}, which makes the sheet names safe and adds an index
+sheet, or shorten the names with \code{query_names}.
+}
+\section{Required and optional arguments}{
+
+Four things are required and have no default:
+\itemize{
+  \item \strong{Signatures}, as exactly one of: \code{signature_id} or
+  \code{signature_name} (each with \code{conn_handler}),
+  \code{omic_signature}, or \code{signature} (hypeR-native gene symbols or
+  a named score vector). They cannot be combined.
+  \item \strong{\code{organism}}: the organism of every signature in the
+  call, e.g. \code{"Homo sapiens"}. A signature of another organism is an
+  error, so human and mouse signatures run in separate calls.
+  \item \strong{\code{test}}: \code{"hypergeometric"}, \code{"kstest"}
+  or \code{"fgsea"}.
+  \item \strong{\code{genesets}}: \code{"msigdb"} together with
+  \code{msigdb_collection}, or your own genesets (a named list,
+  \code{hypeR::gsets} or \code{hypeR::rgsets}).
+}
+
+Every other argument is optional: each has a default, listed with it below,
+and leaving it alone runs the lab's conventions (see the Details of
+\code{background}, \code{min_query_genes} and \code{fdr_scope}). The
+arguments that take \code{NULL} treat it as "choose for me" rather than
+"nothing": \code{background = NULL} picks the background per signature,
+\code{query_names = NULL} builds the default query names,
+\code{seed = NULL} leaves fgsea on the session's random-number state, and
+the \code{msigdb_*} arguments apply only with \code{genesets = "msigdb"}.
 }
+
 \examples{
 \dontrun{
-hyp_res <- SigRepo::runHypeR(
-  conn_handler = conn_handler,
-  signature_name = "example_signature",
-  msigdb_collection = "H",
-  method = "hypergeo",
-  background = 20000
+utils::data("LLFS_Aging_Gene_2023", package = "SigRepo")
+hallmark <- SigRepo::getHypeRGenesets("msigdb", msigdb_collection = "H")
+
+hyp <- SigRepo::runHypeR(
+  omic_signature = LLFS_Aging_Gene_2023,
+  organism = "Homo sapiens",
+  test = "hypergeometric",
+  genesets = hallmark,
+  fdr = 0.05
+)
+SigRepo::plotHypeRDots(hyp)
+SigRepo::hypeRToExcel(hyp, file_path = "llfs_hallmark.xlsx")
+
+ranked <- SigRepo::runHypeR(
+  omic_signature = LLFS_Aging_Gene_2023,
+  organism = "Homo sapiens",
+  test = "kstest",
+  genesets = hallmark
 )
 }
 
diff --git a/man/searchExternal.Rd b/man/searchExternal.Rd
new file mode 100644
index 00000000..c7ca7597
--- /dev/null
+++ b/man/searchExternal.Rd
@@ -0,0 +1,82 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/searchExternal.R
+\name{searchExternal}
+\alias{searchExternal}
+\title{searchExternal}
+\usage{
+searchExternal(
+  conn_handler = NULL,
+  signature_id = NULL,
+  signature_name = NULL,
+  omic_signature = NULL,
+  source = c("rummagene", "rummageo", "coresh"),
+  direction = c("combined", "up", "down", "both"),
+  limit = 25,
+  calculate_pvalues = FALSE,
+  timeout = 120,
+  verbose = TRUE
+)
+}
+\arguments{
+\item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
+Required unless \code{omic_signature} is supplied. Also enables the
+reference-table symbol lookup.}
+
+\item{signature_id}{A single SigRepo signature ID.}
+
+\item{signature_name}{A single SigRepo signature name.}
+
+\item{omic_signature}{An \code{OmicSignature} object, instead of fetching one.}
+
+\item{source}{One or more of \code{"rummagene"}, \code{"rummageo"},
+\code{"coresh"}. Defaults to all three.}
+
+\item{direction}{Which features to send: \code{"combined"} (all),
+\code{"up"} / \code{"down"} (by the sign of \code{score}), or \code{"both"}
+(up and down as two separate queries, stacked with a \code{direction} column).}
+
+\item{limit}{Maximum hits per source (per direction for \code{"both"}).}
+
+\item{calculate_pvalues}{CORESH only: also compute permutation p-values
+(about a minute instead of seconds).}
+
+\item{timeout}{Seconds to wait for a CORESH job before giving up.}
+
+\item{verbose}{Logical; print diagnostic messages. Default \code{TRUE}.}
+}
+\value{
+For a single \code{source}, a data frame; for several, a named list of
+data frames. Every data frame starts with the columns \code{source, direction,
+rank, id, title, url, score, score_label, pvalue, adj_pvalue, n_overlap, n_set},
+followed by service-specific extras, and carries attributes \code{query}
+(the translated query that was sent) and \code{total_count}. CORESH frames
+also carry \code{job_url}, a shareable results page.
+}
+\description{
+Search public signature engines with a SigRepo signature.
+The signature's features are translated into gene symbols (reference table
+first, then biomaRt for Ensembl IDs) plus an organism code, and sent to one
+or more of:
+\itemize{
+  \item \strong{Rummagene} (\url{https://rummagene.com}): ~1M gene sets mined
+  from PMC supplementary tables. Fisher overlap, any organism.
+  \item \strong{RummaGEO} (\url{https://rummageo.com}): up/down gene sets
+  auto-computed from GEO RNA-seq studies. Fisher overlap, human and mouse.
+  \item \strong{CORESH} (\url{https://alserglab.wustl.edu/coresh/}): GEO
+  expression datasets ranked by how much variance the query explains as a
+  coregulated block. Human and mouse; optional permutation p-values.
+}
+}
+\examples{
+\dontrun{
+hits <- SigRepo::searchExternal(
+  conn_handler = conn_handler,
+  signature_name = "my_signature",
+  source = "coresh"
+)
+attr(hits, "job_url")
+
+all_three <- SigRepo::searchExternal(omic_signature = my_omic_signature)
+all_three$rummagene
+}
+}
diff --git a/man/writeSignatureSearchScript.Rd b/man/writeSignatureSearchScript.Rd
new file mode 100644
index 00000000..aa9a6898
--- /dev/null
+++ b/man/writeSignatureSearchScript.Rd
@@ -0,0 +1,81 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/writeSignatureSearchScript.R
+\name{writeSignatureSearchScript}
+\alias{writeSignatureSearchScript}
+\title{writeSignatureSearchScript}
+\usage{
+writeSignatureSearchScript(
+  conn_handler = NULL,
+  signature_id = NULL,
+  signature_name = NULL,
+  omic_signature = NULL,
+  file,
+  n_genes = 150,
+  overwrite = FALSE,
+  verbose = TRUE
+)
+}
+\arguments{
+\item{conn_handler}{An R object obtained from \code{SigRepo::newConnHandler()}.
+Required unless \code{omic_signature} is supplied.}
+
+\item{signature_id}{A single SigRepo signature ID.}
+
+\item{signature_name}{A single SigRepo signature name.}
+
+\item{omic_signature}{A single \code{OmicSignature} object.}
+
+\item{file}{Path of the script to write (required).}
+
+\item{n_genes}{Number of genes of each direction to search with. Defaults
+to \code{150}. It is a setting at the top of the script and can be changed
+there.}
+
+\item{overwrite}{Logical; whether to replace \code{file} when it exists.
+Defaults to \code{FALSE}.}
+
+\item{verbose}{Logical; whether or not to print the
+diagnostic messages. Default is \code{TRUE}.}
+}
+\value{
+The path of the script, invisibly.
+}
+\description{
+Write an R script that runs a LINCS connectivity search for
+one signature with Bioconductor's \code{signatureSearch}: which
+perturbations produce the signature's expression pattern, and which reverse
+it.
+
+SigRepo does not run the search, and does not depend on
+\code{signatureSearch}, whose reference database is about 2.5 GB. The script
+is run on a machine that has \code{signatureSearch},
+\code{ExperimentHub}, \code{rhdf5}, \code{AnnotationDbi},
+\code{org.Hs.eg.db} and \code{ggplot2} installed, and stops with the install command when one
+of them is missing.
+
+The query is built from the signature's feature set: features with a
+positive \code{score} are the up set and features with a negative
+\code{score} the down set, each ordered from the strongest score. A feature
+scored in both directions is left out. The script maps the features to
+Entrez IDs, keeps the genes LINCS measured, and searches with the strongest
+\code{n_genes} of each direction. It saves the result table, one row per
+perturbation and cell line, as a CSV, and a plot of the 10 perturbations
+that most resemble the signature and the 10 that most reverse it as a PDF.
+
+Only human transcriptomics signatures with at least 10 features in each
+direction can be searched; any other signature is an error.
+}
+\examples{
+\dontrun{
+script <- SigRepo::writeSignatureSearchScript(
+  conn_handler = conn_handler,
+  signature_name = "LLFS_Aging_Gene_2023",
+  file = "LLFS_Aging_Gene_2023_lincs.R"
+)
+
+# Runs the search and saves LLFS_Aging_Gene_2023_lincs_results.csv and
+# LLFS_Aging_Gene_2023_lincs_top_hits.pdf
+source(script)
+}
+
+}
diff --git a/tests/testthat/helper-hypeR.R b/tests/testthat/helper-hypeR.R
new file mode 100644
index 00000000..9e7c527f
--- /dev/null
+++ b/tests/testthat/helper-hypeR.R
@@ -0,0 +1,209 @@
+# Fixtures for the hypeR client tests. testthat sources helper-*.R before the
+# test files. OmicSignature requires group_label to be a factor.
+
+hyper_sig_table <- function(symbols = TRUE) {
+  tbl <- data.frame(
+    probe_id = c("p1", "p2", "p3", "p4"),
+    feature_name = c("f1", "f2", "f3", "f4"),
+    score = c(3, 2, -2, -3),
+    group_label = factor(c("Old", "Old", "Young", "Young")),
+    stringsAsFactors = FALSE
+  )
+  if (symbols) {
+    tbl$symbol <- c("A", "B", "C", "D")
+  }
+  tbl
+}
+
+# Full difexp: gene_symbol column, symbol E measured twice (scores 0.5 and -1).
+hyper_difexp_table <- function() {
+  data.frame(
+    probe_id = paste0("p", 1:6),
+    feature_name = paste0("f", 1:6),
+    gene_symbol = c("A", "B", "C", "D", "E", "E"),
+    score = c(3, 2, -2, -3, 0.5, -1),
+    p_value = c(0.001, 0.01, 0.01, 0.001, 0.5, 0.2),
+    adj_p = c(0.01, 0.05, 0.05, 0.01, 0.6, 0.3),
+    group_label = factor(c("Old", "Old", "Young", "Young", "Old", "Young")),
+    stringsAsFactors = FALSE
+  )
+}
+
+make_hyper_sig <- function(name = "sig_a",
+                           signature = hyper_sig_table(),
+                           difexp = NULL,
+                           type = "bi-directional",
+                           organism = "Homo sapiens",
+                           assay_type = "transcriptomics") {
+  OmicSignature::OmicSignature$new(
+    metadata = list(
+      signature_name = name,
+      assay_type = assay_type,
+      phenotype = "test_phenotype",
+      organism = organism,
+      type = type,
+      others = list()
+    ),
+    signature = signature,
+    difexp = difexp,
+    print_message = FALSE
+  )
+}
+
+hyper_genesets <- function() {
+  list(
+    SET_AB = c("A", "B", "X1", "X2"),
+    SET_CD = c("C", "D", "X3"),
+    SET_E = c("E", "X4", "X5")
+  )
+}
+
+# Signature whose kstest vector is exactly c(A = 2, D = 1, B = 0, C = -1):
+# B scores exactly 0, so a geneset hitting only B has no weight.
+make_hyper_zero_score_sig <- function() {
+  make_hyper_sig(
+    name = "zero",
+    signature = data.frame(
+      probe_id = c("p1", "p4"), feature_name = c("f1", "f4"), score = c(2, 1),
+      group_label = factor(c("Up", "Up")), symbol = c("A", "D")
+    ),
+    difexp = data.frame(
+      probe_id = paste0("p", 1:4), feature_name = paste0("f", 1:4),
+      gene_symbol = c("A", "B", "C", "D"), score = c(2, 0, -1, 1),
+      p_value = 0.01, adj_p = 0.05, group_label = factor(c("Up", "Up", "Down", "Up"))
+    )
+  )
+}
+
+hyper_zero_score_genesets <- function() {
+  list(S1 = c("A", "D"), S2 = "B", S3 = "C")
+}
+
+# Signature whose kstest vector is exactly c(A = 3, B = 2, C = -1), for
+# genesets that contain every query gene.
+make_hyper_cover_sig <- function() {
+  make_hyper_sig(
+    name = "cover",
+    signature = data.frame(
+      probe_id = c("p1", "p2"), feature_name = c("f1", "f2"), score = c(3, 2),
+      group_label = factor(c("Up", "Up")), symbol = c("A", "B")
+    ),
+    difexp = data.frame(
+      probe_id = paste0("p", 1:3), feature_name = paste0("f", 1:3),
+      gene_symbol = c("A", "B", "C"), score = c(3, 2, -1),
+      p_value = 0.01, adj_p = 0.05, group_label = factor(c("Up", "Up", "Down"))
+    )
+  )
+}
+
+# runHypeR() for the toy fixtures. Their hypergeometric queries hold 1-4 genes,
+# below runHypeR()'s default min_query_genes = 4, so tests about anything else
+# lower it; every other argument keeps runHypeR()'s defaults.
+runToyHypeR <- function(..., min_query_genes = 1) {
+  SigRepo::runHypeR(..., min_query_genes = min_query_genes)
+}
+
+# Categorical signature with two categories (red, white). Signature table:
+# red up A, red down B, red C scores 0; white up D and F, white down E.
+# Difexp is long: one row per gene per category, each with that category's
+# signed score. `red_difexp_scores` overrides red's difexp scores (A-F).
+make_hyper_categorical_sig <- function(red_difexp_scores = c(2, -1, 0.5, -0.3, 0.2, 0.1)) {
+  OmicSignature::OmicSignature$new(
+    metadata = list(
+      signature_name = "cat",
+      assay_type = "transcriptomics",
+      phenotype = "test_phenotype",
+      organism = "Homo sapiens",
+      type = "categorical",
+      category_num = 2,
+      others = list()
+    ),
+    signature = data.frame(
+      probe_id = paste0("p", 1:6), feature_name = paste0("f", 1:6), symbol = c("A", "B", "C", "D", "E", "F"),
+      score = c(2, -1, 0, 3, -2, 1), group_label = factor(rep(c("red", "white"), each = 3)),
+      stringsAsFactors = FALSE
+    ),
+    difexp = data.frame(
+      probe_id = rep(paste0("p", 1:6), 2), feature_name = rep(paste0("f", 1:6), 2),
+      gene_symbol = rep(c("A", "B", "C", "D", "E", "F"), 2),
+      score = c(red_difexp_scores, -1, 0.4, -2, 3, 1, -0.5),
+      p_value = 0.01, adj_p = 0.05, group_label = factor(rep(c("red", "white"), each = 6)),
+      stringsAsFactors = FALSE
+    ),
+    print_message = FALSE
+  )
+}
+
+# A difexp the default background accepts as complete: proteomics (no
+# transcriptome row minimum), more than twice the 4-row signature, and p-values
+# up to 0.6. Measures A-E plus G-J.
+hyper_complete_difexp_table <- function() {
+  extra <- data.frame(
+    probe_id = paste0("p", 7:10), feature_name = paste0("f", 7:10), gene_symbol = c("G", "H", "I", "J"),
+    score = c(1.5, -1.5, 0.3, -0.3), p_value = 0.4, adj_p = 0.5, group_label = factor(c("Old", "Young", "Old", "Young")),
+    stringsAsFactors = FALSE
+  )
+  rbind(hyper_difexp_table(), extra)
+}
+
+# ---- fgsea fixtures ----
+
+# 40 genes G01-G40 with distinct signed scores, highest first: G01-G20 score
+# 4.0 down to 0.2, G21-G40 score -0.1 down to -3.9 (no score is 0).
+hyper_fgsea_stats <- function() {
+  stats::setNames(c(seq(4, 0.2, by = -0.2), seq(-0.1, -3.9, by = -0.2)), sprintf("G%02d", 1:40))
+}
+
+# TOP/TOP_MIX sit at the top (ES > 0) and share 4 genes; BOTTOM/BOTTOM_MIX sit
+# at the bottom (ES < 0) and share 4 genes, so hyp_emap() has an edge on each
+# side. MIDDLE straddles the centre symmetrically, so fgsea gives it ES = 0.
+hyper_fgsea_genesets <- function() {
+  genes <- sprintf("G%02d", 1:40)
+  list(
+    TOP = genes[1:8],
+    TOP_MIX = c(genes[1:4], genes[9:12]),
+    BOTTOM = genes[33:40],
+    BOTTOM_MIX = c(genes[37:40], genes[29:32]),
+    MIDDLE = genes[17:24],
+    SPREAD = genes[c(2, 11, 20, 29, 38)]
+  )
+}
+
+# Bi-directional signature whose difexp ranks to hyper_fgsea_stats().
+make_hyper_fgsea_sig <- function(name = "fg") {
+  stats <- hyper_fgsea_stats()
+  difexp <- data.frame(
+    probe_id = paste0("p", 1:40), feature_name = paste0("f", 1:40), gene_symbol = names(stats),
+    score = unname(stats), p_value = 0.01, adj_p = 0.05,
+    group_label = factor(ifelse(stats > 0, "Up", "Down")), stringsAsFactors = FALSE
+  )
+  make_hyper_sig(name, signature = difexp[c(1:4, 37:40), c("probe_id", "feature_name", "score", "group_label", "gene_symbol")],
+                 difexp = difexp)
+}
+
+# ---- plotting fixtures ----
+
+# A hypeR hyp built directly from a results table, for plot-data tests that
+# need exact p-values/FDRs. `extra` adds columns (e.g. nes, score); `info`
+# adds info keys on top of Test.
+make_dot_hyp <- function(labels, fdr, test = "hypergeometric", extra = list(), info = list()) {
+  data <- data.frame(
+    label = labels, pval = fdr / 2, fdr = fdr,
+    geneset = seq_along(labels) * 10L, overlap = seq_along(labels), stringsAsFactors = FALSE
+  )
+  for (column in names(extra)) {
+    data[[column]] <- extra[[column]]
+  }
+  hypeR::hyp$new(data = data, info = c(list(Test = test), info))
+}
+
+# 11 signed scores (no zero) and a geneset with a single hit at position 6: its
+# running sum reaches exactly +0.5 and -0.5 (weighted) or +/-5/11 (ranked), the
+# tie behind the production HALLMARK_NOTCH_SIGNALING case.
+hyper_tie_stats <- function() {
+  stats::setNames(c(5, 4, 3, 2, 1, 0.5, -1, -2, -3, -4, -5), sprintf("T%02d", 1:11))
+}
+
+hyper_tie_genesets <- function() {
+  list(TIE = "T06", TOP = c("T01", "T02", "T03"), BOT = c("T09", "T10", "T11"))
+}
diff --git a/tests/testthat/test_data/external/coresh_ranking.json b/tests/testthat/test_data/external/coresh_ranking.json
new file mode 100644
index 00000000..d307ebbb
--- /dev/null
+++ b/tests/testthat/test_data/external/coresh_ranking.json
@@ -0,0 +1,62 @@
+[
+ {
+  "rank": 1,
+  "gseTitle": "Cellular response to hepatitis E virus (HEV) infection",
+  "size": 11,
+  "pctVar": 20.8949,
+  "log10Padj": "NA",
+  "gseId": "GSE88731",
+  "gseSummary": "What happens in cells infected with HEV is largely unknown. We used a recently established genotype 3 HEV cell culture system and profiled the host responses by RNA-seq.",
+  "positiveWords": "{\"kernow\":0.999,\"genotype\":0.999}",
+  "negativeWords": "{\"mock-infected\":-0.999}",
+  "gplId": "GPL20301"
+ },
+ {
+  "rank": 2,
+  "gseTitle": "Differential gene expression in human THP-1 monocytes expressing the RdRP transgene (WT version) compared to THP-1 empty vector control cells",
+  "size": 12,
+  "pctVar": 20.5952,
+  "log10Padj": "NA",
+  "gseId": "GSE62753",
+  "gseSummary": "Previously, we reported that mice made transgenic for a picornaviral RdRP \u2013 the 3Dpol protein of Theiler\u2019s murine encephalomyelitis virus (TMEV) \u2013 suppress infection by diverse viruses. Using mouse genetic studies, we determined that uninfected RdRP transgenic mice inherently induce an arsenel of prominent antiviral effectors and that this phenotype is MDA5-, MAVS- and IFN\u03b1\u03b2R-dependent. To determine the mechanism underlying MDA5 activation and induction of constitutive antiviral signaling by the picornaviral RdRP, we constructed mutant RdRP transgenes. First, we introduced pervasive, coding-neutral point mutations into the RdRP cDNA to maximally disrupt primary and secondary RNA structure (RdRP\u2206rna). Another mutant, RdRP\u2206cat, lacks catalytic activity due to alanine substitution of the key catalytic center triad aspartate residues (D233, D328, and D329), but is otherwise intact at the nucleotide and amino acid levels. The WT,  RdRP\u2206rna, and RdRP\u2206cat versions of the RdRP transgenes were transduced with lentiviral vectors into human THP-1 monocytes, with RdRP mRNA transcription controlled by the Spleen Focus Forming Virus (SFFV) promoter. In parallel a control cell line transduced with a vector lacking any RdRP transgene (null THP-1) was generated.",
+  "positiveWords": "{\"wildtype\":1,\"rdrp\":1,\"transgene\":1}",
+  "negativeWords": "{\"null\":-1,\"empty\":-1,\"vector\":-1}",
+  "gplId": "GPL570"
+ },
+ {
+  "rank": 3,
+  "gseTitle": "mRNA expression levels in Jurkat cell lines treated with or without IFN-alpha and with shaking or static",
+  "size": 7,
+  "pctVar": 19.5755,
+  "log10Padj": "NA",
+  "gseId": "GSE135370",
+  "gseSummary": "Throuth RNA sequencing analyses, we report that shaking did not affect transcriptome in Jurkat cells and differential expressed genes by IFN-alpha were detected.",
+  "positiveWords": "{\"ifn-alpha\":0.999,\"treated\":0.999,\"non-shaking-with-ifn-alpha\":0.583,\"shaking-with-ifn-alpha\":0.57}",
+  "negativeWords": "{\"untreated\":-0.999,\"shaking\":-0.589,\"non-shaking\":-0.564}",
+  "gplId": "GPL16791"
+ },
+ {
+  "rank": 4,
+  "gseTitle": "Transfection experiment with the plasmid containing pri-mir-124 in HEK293 cells",
+  "size": 9,
+  "pctVar": 18.5536,
+  "log10Padj": "NA",
+  "gseId": "GSE119381",
+  "gseSummary": "The microRNAome is comprised of annotated canonical miRNAs (anomiR) and a variety of recently identified microRNA isoforms (isomiR). While anomiR is well-studied in the last two decades, the functionality of most isomiRs is largely illusive. Here, we conducted both computional and experimental assays to estimate the functionality of isomiRs expressed in brains.",
+  "positiveWords": "{\"pri-mir-124\":0.997,\"pri-mir-124-plasmid\":0.997}",
+  "negativeWords": "{\"nc-plasmid\":-0.997,\"empty\":-0.997,\"plasmid\":-0.997}",
+  "gplId": "GPL20301"
+ },
+ {
+  "rank": 5,
+  "gseTitle": "Transcriptional  changes following SARS-CoV-2 infection of primary astrocytes",
+  "size": 11,
+  "pctVar": 18.3934,
+  "log10Padj": "NA",
+  "gseId": "GSE198722",
+  "gseSummary": "We used bulk RNA seq to invistigate how SARS-CoV-2 changes host profile in astrocytes. SARS-CoV-2 infection of astrocytes induces type I interferon and inflammatory response.",
+  "positiveWords": "{\"sars-cov-2-astrocytes\":0.995,\"sars-cov-2\":0.995,\"moi-5\":0.563}",
+  "negativeWords": "{\"mock\":-0.995,\"mock-astrocytes\":-0.995}",
+  "gplId": "GPL11154"
+ }
+]
\ No newline at end of file
diff --git a/tests/testthat/test_data/external/coresh_words.json b/tests/testthat/test_data/external/coresh_words.json
new file mode 100644
index 00000000..7d5074e0
--- /dev/null
+++ b/tests/testthat/test_data/external/coresh_words.json
@@ -0,0 +1,47 @@
+[
+ {
+  "stem": "interferon",
+  "pval": 1.84259592534581e-54,
+  "padj": 7.55648588984316e-51,
+  "foldEnrichment": 11.5417440543601,
+  "freqInTop": 72,
+  "freq": 883,
+  "GSE": "GSE100928 GSE103363 GSE106522 GSE107307 GSE10943 GSE114284 GSE115138 GSE12002 GSE122031 GSE122252 GSE124922 GSE124939 GSE126090 GSE138567 GSE138569 GSE138841 GSE142015 GSE145496 GSE148542 GSE150003 GSE155031 GSE155447 GSE155448 GSE156779 GSE159462 GSE165428 GSE178901 GSE180663 GSE183458 GSE189613 GSE19392 GSE194396 GSE194429 GSE198722 GSE200447 GSE201508 GSE202350 GSE202852 GSE203384 GSE205567 GSE209536 GSE209541 GSE209601 GSE215259 GSE216851 GSE224325 GSE225949 GSE229339 GSE229741 GSE233003 GSE233197 GSE241570 GSE241571 GSE241572 GSE246082 GSE29384 GSE30536 GSE32893 GSE32902 GSE39199 GSE41291 GSE41960 GSE48400 GSE54970 GSE60572 GSE61413 GSE65040 GSE81853 GSE81860 GSE87110 GSE88771 GSE98422"
+ },
+ {
+  "stem": "virus",
+  "pval": 1.43108710063122e-34,
+  "padj": 2.93444409984432e-31,
+  "foldEnrichment": 5.95015591079534,
+  "freqInTop": 71,
+  "freq": 1689,
+  "GSE": "GSE100928 GSE104190 GSE104196 GSE106522 GSE114966 GSE115138 GSE122018 GSE122031 GSE126090 GSE130981 GSE131387 GSE133751 GSE137065 GSE138841 GSE142015 GSE145232 GSE146423 GSE152782 GSE159853 GSE162902 GSE164922 GSE173072 GSE174317 GSE181329 GSE186287 GSE189613 GSE19392 GSE199437 GSE205567 GSE206141 GSE206188 GSE207253 GSE209601 GSE210278 GSE210281 GSE216851 GSE224795 GSE225905 GSE225949 GSE226071 GSE233003 GSE233049 GSE233197 GSE237131 GSE241570 GSE241571 GSE244714 GSE245916 GSE246082 GSE30719 GSE32902 GSE34628 GSE36012 GSE38016 GSE40844 GSE41067 GSE47865 GSE48400 GSE60572 GSE60989 GSE62753 GSE62755 GSE65699 GSE67737 GSE68310 GSE73355 GSE77659 GSE88731 GSE93999 GSE97919 GSE9834"
+ },
+ {
+  "stem": "infection",
+  "pval": 1.58354803459998e-29,
+  "padj": 2.16471016329817e-26,
+  "foldEnrichment": 4.04691108868707,
+  "freqInTop": 85,
+  "freq": 2973,
+  "GSE": "GSE103204 GSE104190 GSE104196 GSE105152 GSE107549 GSE110564 GSE114907 GSE121627 GSE122031 GSE126090 GSE130005 GSE133751 GSE137065 GSE137850 GSE138841 GSE139498 GSE145232 GSE147538 GSE152782 GSE153447 GSE159853 GSE164922 GSE173072 GSE174380 GSE184697 GSE185442 GSE186287 GSE189613 GSE19392 GSE198722 GSE200447 GSE201508 GSE205567 GSE209920 GSE210278 GSE210281 GSE216851 GSE218153 GSE224795 GSE225949 GSE226071 GSE227163 GSE231200 GSE232843 GSE233049 GSE237131 GSE237132 GSE241570 GSE241571 GSE244714 GSE245916 GSE246082 GSE27973 GSE29384 GSE30536 GSE30719 GSE31473 GSE31474 GSE31475 GSE32902 GSE34628 GSE36012 GSE38016 GSE40844 GSE41067 GSE48400 GSE53543 GSE55276 GSE60572 GSE60989 GSE62753 GSE62755 GSE65699 GSE67737 GSE68310 GSE77659 GSE81853 GSE81860 GSE85244 GSE87110 GSE88731 GSE93999 GSE97919 GSE9834 GSE99081"
+ },
+ {
+  "stem": "mock",
+  "pval": 1.05676266991843e-27,
+  "padj": 1.08344592733387e-24,
+  "foldEnrichment": 7.78092787524367,
+  "freqInTop": 47,
+  "freq": 855,
+  "GSE": "GSE105152 GSE106522 GSE114907 GSE122031 GSE130005 GSE131387 GSE133751 GSE138567 GSE142015 GSE145232 GSE155447 GSE155448 GSE173072 GSE174380 GSE180663 GSE186287 GSE19392 GSE198722 GSE207116 GSE207253 GSE209601 GSE226071 GSE227163 GSE232843 GSE233003 GSE233049 GSE233197 GSE237131 GSE237132 GSE245916 GSE255279 GSE31473 GSE31474 GSE31475 GSE34628 GSE39199 GSE40844 GSE41960 GSE47865 GSE47866 GSE48367 GSE60572 GSE60574 GSE80598 GSE88731 GSE97919 GSE99081"
+ },
+ {
+  "stem": "I interferon",
+  "pval": 6.69220799193693e-27,
+  "padj": 5.48894899498667e-24,
+  "foldEnrichment": 15.9041198501873,
+  "freqInTop": 30,
+  "freq": 267,
+  "GSE": "GSE100928 GSE107307 GSE10943 GSE126090 GSE133218 GSE135370 GSE138841 GSE145496 GSE150003 GSE159462 GSE165428 GSE189613 GSE194429 GSE198722 GSE202350 GSE202852 GSE203384 GSE229339 GSE246082 GSE39199 GSE41291 GSE41960 GSE48400 GSE60572 GSE67737 GSE81853 GSE81860 GSE9481 GSE98372 GSE98422"
+ }
+]
\ No newline at end of file
diff --git a/tests/testthat/test_data/external/rummagene_enrich.json b/tests/testthat/test_data/external/rummagene_enrich.json
new file mode 100644
index 00000000..fca0b0e0
--- /dev/null
+++ b/tests/testthat/test_data/external/rummagene_enrich.json
@@ -0,0 +1,92 @@
+{
+ "data": {
+  "currentBackground": {
+   "enrich": {
+    "totalCount": 21423,
+    "nodes": [
+     {
+      "pvalue": 5.546085046176113e-38,
+      "adjPvalue": 4.867011300952217e-32,
+      "oddsRatio": 933.1363636363635,
+      "nOverlap": 12,
+      "geneSets": {
+       "nodes": [
+        {
+         "term": "PMC11278796-mmc3.docx-0-Target_gene",
+         "description": null,
+         "nGeneIds": 22,
+         "geneSetPmcsById": {
+          "nodes": [
+           {
+            "pmcInfoByPmcid": {
+             "pmcid": "PMC11278796",
+             "title": "Spontaneous NETosis and type I IFN signaling activation in resting neutrophils of chronic granulomatous disease patients with CYBB mutations",
+             "yr": 2023,
+             "doi": "10.1016/j.gendis.2023.101118"
+            }
+           }
+          ]
+         }
+        }
+       ]
+      }
+     },
+     {
+      "pvalue": 4.7030649554020735e-35,
+      "adjPvalue": 2.0636061380663664e-29,
+      "oddsRatio": 603.7941176470589,
+      "nOverlap": 12,
+      "geneSets": {
+       "nodes": [
+        {
+         "term": "PMC4452922-viruses-07-02618-s001.pdf-0-Gene_Symbol",
+         "description": "< 0.05 was considered significant. All primers used in this study are listed in **Supplementary Table S1**  Click here for additional data file",
+         "nGeneIds": 34,
+         "geneSetPmcsById": {
+          "nodes": [
+           {
+            "pmcInfoByPmcid": {
+             "pmcid": "PMC4452922",
+             "title": "Insights into Human Astrocyte Response to H5N1 Infection by Microarray Analysis",
+             "yr": 2015,
+             "doi": "10.3390/v7052618"
+            }
+           }
+          ]
+         }
+        }
+       ]
+      }
+     },
+     {
+      "pvalue": 2.954514747382774e-34,
+      "adjPvalue": 6.481895131709331e-29,
+      "oddsRatio": 940.9125,
+      "nOverlap": 11,
+      "geneSets": {
+       "nodes": [
+        {
+         "term": "PMC8783724-BMRI2022-7697558.nxml--Hub_gene",
+         "description": "shown in Figure 3(a). We present the top 20 genes in Figure 3(b) and **Table 3**  Topological result exploration for top 20 genesMX1IFIT1ISG15RSAD2IFI44LIFI44IFIT3OAS2OAS1IFI6XAF1IFIT2GBP1OAS3HERC5IRF7OASLIFI27EIF2AK2LY6E",
+         "nGeneIds": 20,
+         "geneSetPmcsById": {
+          "nodes": [
+           {
+            "pmcInfoByPmcid": {
+             "pmcid": "PMC8783724",
+             "title": "Bioinformatic Analysis Identifies Biomarkers and Treatment Targets in Primary Sj\u00f6gren's Syndrome Patients with Fatigue",
+             "yr": 2022,
+             "doi": "10.1155/2022/7697558"
+            }
+           }
+          ]
+         }
+        }
+       ]
+      }
+     }
+    ]
+   }
+  }
+ }
+}
\ No newline at end of file
diff --git a/tests/testthat/test_data/external/rummageo_enrich.json b/tests/testthat/test_data/external/rummageo_enrich.json
new file mode 100644
index 00000000..1ac2c71a
--- /dev/null
+++ b/tests/testthat/test_data/external/rummageo_enrich.json
@@ -0,0 +1,69 @@
+{
+ "data": {
+  "currentBackground": {
+   "species": "human",
+   "enrich": {
+    "totalCount": 18448,
+    "nodes": [
+     {
+      "pvalue": 2.526695532146911e-36,
+      "adjPvalue": 3.843926321589982e-31,
+      "oddsRatio": 1677.9583333333335,
+      "nOverlap": 11,
+      "geneSet": {
+       "id": "e0489e8b-27e7-49e8-ba6e-2ad685ebaf4a",
+       "term": "GSE218462,GSE218464-0-vs-1-human up",
+       "species": "human",
+       "nGeneIds": 34,
+       "geneSetGsesById": {
+        "nodes": [
+         {
+          "gse": "GSE218462,GSE218464"
+         }
+        ]
+       }
+      }
+     },
+     {
+      "pvalue": 4.40438421264965e-36,
+      "adjPvalue": 3.843926321589982e-31,
+      "oddsRatio": 818.9078947368422,
+      "nOverlap": 12,
+      "geneSet": {
+       "id": "eed483a7-2e33-4c9c-bda2-fe0b20351226",
+       "term": "GSE163959-4-vs-0-human up",
+       "species": "human",
+       "nGeneIds": 76,
+       "geneSetGsesById": {
+        "nodes": [
+         {
+          "gse": "GSE163959"
+         }
+        ]
+       }
+      }
+     },
+     {
+      "pvalue": 2.915779886183577e-35,
+      "adjPvalue": 1.6964979304444782e-30,
+      "oddsRatio": 707.2386363636364,
+      "nOverlap": 12,
+      "geneSet": {
+       "id": "c5ed9f0d-0b15-4b64-8358-059225de65ee",
+       "term": "GSE218462,GSE218464-0-vs-5-human up",
+       "species": "human",
+       "nGeneIds": 88,
+       "geneSetGsesById": {
+        "nodes": [
+         {
+          "gse": "GSE218462,GSE218464"
+         }
+        ]
+       }
+      }
+     }
+    ]
+   }
+  }
+ }
+}
\ No newline at end of file
diff --git a/tests/testthat/test_externalCommon.R b/tests/testthat/test_externalCommon.R
new file mode 100644
index 00000000..d9d9c600
--- /dev/null
+++ b/tests/testthat/test_externalCommon.R
@@ -0,0 +1,57 @@
+# Shared plumbing behind searchExternal(): URLs, HTTP wrappers and the common
+# data frame every external adapter returns. No network: externalGraphql is
+# tested with a mocked externalPostJson.
+
+test_that("externalUrl returns defaults and honours options", {
+  expect_equal(externalUrl("rummagene"), "https://rummagene.com/graphql")
+  expect_equal(externalUrl("rummageo"), "https://rummageo.com/graphql")
+  expect_equal(externalUrl("coresh"), "https://alserglab.wustl.edu/coresh-back")
+  withr::with_options(list(sigrepo.coresh_url = "http://localhost:8000"), {
+    expect_equal(externalUrl("coresh"), "http://localhost:8000")
+  })
+  expect_error(externalUrl("nope"), "Unknown external source")
+})
+
+test_that("emptyExternalFrame has the common columns and no rows", {
+  f <- emptyExternalFrame("coresh")
+  expect_s3_class(f, "data.frame")
+  expect_equal(nrow(f), 0)
+  expect_equal(colnames(f), EXTERNAL_COLUMNS)
+})
+
+test_that("bindExternalHits orders common columns first, fills gaps, ranks", {
+  rows <- list(
+    list(id = "a", title = "A", score = 2, pvalue = 0.01, extra = "x"),
+    list(id = "b", title = "B", score = 1, pvalue = NULL, extra = "y")
+  )
+  f <- bindExternalHits("rummagene", "up", rows)
+  expect_equal(nrow(f), 2)
+  expect_equal(colnames(f)[seq_along(EXTERNAL_COLUMNS)], EXTERNAL_COLUMNS)
+  expect_equal(f$source, c("rummagene", "rummagene"))
+  expect_equal(f$direction, c("up", "up"))
+  expect_equal(f$rank, 1:2)
+  expect_equal(f$extra, c("x", "y"))
+  expect_true(is.na(f$pvalue[2]))
+  expect_true(all(is.na(f$url)))
+})
+
+test_that("bindExternalHits with no rows returns the empty frame", {
+  f <- bindExternalHits("coresh", "combined", list())
+  expect_equal(nrow(f), 0)
+  expect_equal(colnames(f), EXTERNAL_COLUMNS)
+})
+
+test_that("rbindExternalFrames unions columns", {
+  a <- bindExternalHits("coresh", "up", list(list(id = "a", gpl = "GPL1")))
+  b <- emptyExternalFrame("coresh", "down")
+  f <- rbindExternalFrames(list(a, b))
+  expect_equal(nrow(f), 1)
+  expect_true("gpl" %in% colnames(f))
+})
+
+test_that("externalGraphql surfaces GraphQL errors", {
+  testthat::local_mocked_bindings(
+    externalPostJson = function(url, body, timeout = 60) list(errors = list(list(message = "boom")))
+  )
+  expect_error(externalGraphql("http://x", "{ q }", list()), "boom")
+})
diff --git a/tests/testthat/test_externalCoresh.R b/tests/testthat/test_externalCoresh.R
new file mode 100644
index 00000000..c035471c
--- /dev/null
+++ b/tests/testthat/test_externalCoresh.R
@@ -0,0 +1,93 @@
+# CORESH adapter. The ranking fixture is the head of a real get-ranking-result
+# reply captured on 2026-10-07 for a 12-gene interferon query. HTTP is mocked
+# so the submit / poll / fetch cycle runs offline.
+
+read_fixture <- function(name) {
+  jsonlite::fromJSON(testthat::test_path("test_data", "external", name), simplifyVector = FALSE)
+}
+ifn_query <- function(organism = "Homo sapiens", code = "hsa") {
+  base::list(signature_name = "ifn", organism = organism, organism_code = code, direction = "combined",
+             genes = c("ISG15", "IFI6", "MX1"), n_input = 3, n_mapped = 3, n_unmapped = 0,
+             truncated = FALSE, unmapped = character())
+}
+
+test_that("parseCoreshRanking maps GEO datasets into the common frame", {
+  out <- parseCoreshRanking(read_fixture("coresh_ranking.json"), ifn_query(), limit = 3)
+  expect_equal(nrow(out), 3)
+  expect_equal(colnames(out)[1:12], EXTERNAL_COLUMNS)
+  expect_equal(out$source[1], "coresh")
+  expect_equal(out$id[1], "GSE88731")
+  expect_match(out$title[1], "hepatitis E")
+  expect_equal(out$url[1], "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE88731")
+  expect_equal(out$score[1], 20.8949)
+  expect_equal(out$score_label[1], "% variance")
+  expect_true(is.na(out$pvalue[1]))
+  expect_true(is.na(out$adj_pvalue[1]))        # log10Padj is the string "NA" without p-values
+  expect_equal(out$n_set[1], 11)
+  expect_equal(out$gpl[1], "GPL20301")
+  expect_equal(attr(out, "total_count"), 5)
+})
+
+test_that("parseCoreshRanking converts log10Padj when present and tolerates limit > hits", {
+  rows <- read_fixture("coresh_ranking.json")
+  rows[[1]]$log10Padj <- -3
+  out <- parseCoreshRanking(rows, ifn_query(), limit = 100)
+  expect_equal(nrow(out), 5)
+  expect_equal(out$adj_pvalue[1], 1e-3)
+  expect_equal(out$log10_padj[1], -3)
+})
+
+test_that("externalCoresh submits, polls until done, and fetches the ranking", {
+  calls <- character()
+  progress <- c(40, 100)
+  testthat::local_mocked_bindings(
+    externalPostJson = function(url, body, timeout = 60) {
+      calls <<- c(calls, "submit")
+      expect_equal(body$organism, "hsa"); expect_equal(body$dbType, "hsa")
+      expect_false(body$calculatePvalues)
+      expect_equal(unlist(body$genes), c("ISG15", "IFI6", "MX1"))
+      list(ID = "20261007_test")
+    },
+    externalGetJson = function(url, query = list(), timeout = 60) {
+      if (grepl("check-job", url)) {
+        calls <<- c(calls, "check-job")
+        p <- progress[1]; progress <<- progress[-1]
+        return(list(progress = p, nbatches = 100, ncompleted = p))
+      }
+      if (grepl("check-result-files", url)) { calls <<- c(calls, "files"); return(list(files_ready = TRUE)) }
+      if (grepl("get-ranking-result", url)) {
+        calls <<- c(calls, "ranking"); expect_equal(query$jobid, "20261007_test")
+        return(read_fixture("coresh_ranking.json"))
+      }
+      stop("unexpected url ", url)
+    }
+  )
+  withr::local_options(list(sigrepo.coresh_poll_seconds = 0))
+  out <- externalCoresh(ifn_query(), limit = 2)
+  expect_equal(calls, c("submit", "check-job", "check-job", "files", "ranking"))
+  expect_equal(nrow(out), 2)
+  expect_equal(attr(out, "job_id"), "20261007_test")
+  expect_equal(attr(out, "job_url"), "https://alserglab.wustl.edu/coresh/load/20261007_test")
+})
+
+test_that("externalCoresh stops when the job reports failure", {
+  testthat::local_mocked_bindings(
+    externalPostJson = function(url, body, timeout = 60) list(ID = "bad_job"),
+    externalGetJson = function(url, query = list(), timeout = 60) list(progress = 10, failed = "True")
+  )
+  withr::local_options(list(sigrepo.coresh_poll_seconds = 0))
+  expect_error(externalCoresh(ifn_query()), "CORESH job bad_job failed")
+})
+
+test_that("externalCoresh times out with the job url in the message", {
+  testthat::local_mocked_bindings(
+    externalPostJson = function(url, body, timeout = 60) list(ID = "slow_job"),
+    externalGetJson = function(url, query = list(), timeout = 60) list(progress = 10)
+  )
+  withr::local_options(list(sigrepo.coresh_poll_seconds = 0))
+  expect_error(externalCoresh(ifn_query(), timeout = 0), "coresh/load/slow_job")
+})
+
+test_that("externalCoresh refuses organisms CORESH does not index", {
+  expect_error(externalCoresh(ifn_query("Danio rerio", NA_character_)), "only supports Homo sapiens and Mus musculus")
+})
diff --git a/tests/testthat/test_externalQuery.R b/tests/testthat/test_externalQuery.R
new file mode 100644
index 00000000..d3eb43ad
--- /dev/null
+++ b/tests/testthat/test_externalQuery.R
@@ -0,0 +1,169 @@
+# Translation of a signature into the query shape the external engines share.
+# No network and no database: the two symbol lookups are mocked.
+
+# A tiny OmicSignature-shaped stand-in: buildExternalQuery() only touches
+# $signature and $metadata, so a plain list is enough and keeps these tests
+# independent of OmicSignature's constructor checks.
+fake_signature <- function(feature_name, score = NULL, organism = "Homo sapiens",
+                           name = "fake_sig", assay_type = "transcriptomics") {
+  sig <- base::data.frame(
+    probe_id = base::seq_along(feature_name),
+    feature_name = feature_name,
+    stringsAsFactors = FALSE
+  )
+  if (!base::is.null(score)) sig$score <- score
+  base::list(
+    signature = sig,
+    metadata = base::list(signature_name = name, organism = organism, assay_type = assay_type)
+  )
+}
+
+test_that("organismCode maps human and mouse case-insensitively", {
+  expect_equal(organismCode("Homo sapiens"), "hsa")
+  expect_equal(organismCode("Homo Sapiens"), "hsa")
+  expect_equal(organismCode("mus musculus"), "mmu")
+  expect_true(is.na(organismCode("Rattus norvegicus")))
+  expect_true(is.na(organismCode(NULL)))
+})
+
+test_that("looksLikeGeneSymbol rejects Ensembl, Entrez and RefSeq ids", {
+  expect_equal(
+    looksLikeGeneSymbol(c("TP53", "ENSG00000141510", "ENSMUSG00000059552.7", "7157", "NM_000546", "Isg15")),
+    c(TRUE, FALSE, FALSE, FALSE, FALSE, TRUE)
+  )
+})
+
+test_that("mapFeaturesToSymbols passes symbols through and never calls lookups for them", {
+  called <- FALSE
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(conn_handler, feature_names, organism) { called <<- TRUE; character() },
+    lookupSymbolsInBiomart = function(feature_names, organism) { called <<- TRUE; character() }
+  )
+  m <- mapFeaturesToSymbols(c("TP53", "BRCA1", " TP53 "), "Homo sapiens")
+  expect_false(called)
+  expect_equal(unname(m), c("TP53", "BRCA1"))
+})
+
+test_that("mapFeaturesToSymbols uses SigRepo first, then biomaRt, and reports NA for the rest", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(conn_handler, feature_names, organism) c(ENSG00000141510 = "TP53"),
+    lookupSymbolsInBiomart = function(feature_names, organism) c(ENSG00000012048 = "BRCA1")
+  )
+  m <- mapFeaturesToSymbols(c("ENSG00000141510", "ENSG00000012048", "ENSG00000000000"), "Homo sapiens", conn_handler = NULL)
+  expect_equal(m[["ENSG00000141510"]], "TP53")
+  expect_equal(m[["ENSG00000012048"]], "BRCA1")
+  expect_true(is.na(m[["ENSG00000000000"]]))
+})
+
+test_that("lookupSymbolsInBiomart strips Ensembl versions and maps back to the original names", {
+  testthat::local_mocked_bindings(
+    biomartSymbolTable = function(ensembl_ids, organism) {
+      base::data.frame(ensembl_gene_id = "ENSG00000126353", hgnc_symbol = "CCR7", stringsAsFactors = FALSE)
+    }
+  )
+  m <- lookupSymbolsInBiomart(c("ENSG00000126353.12", "TP53"), "Homo sapiens")
+  expect_equal(m, c(ENSG00000126353.12 = "CCR7"))
+})
+
+test_that("buildExternalQuery splits by score sign and drops NA scores", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) character()
+  )
+  sig <- fake_signature(c("A1", "B1", "C1", "D1"), score = c(3, -2, NA, 1))
+  up <- buildExternalQuery(sig, direction = "up", verbose = FALSE)
+  expect_equal(up$genes, c("A1", "D1"))         # ordered by |score|
+  expect_equal(up$direction, "up")
+  # only B1 is negative: one gene is below the minimum of two
+  expect_error(buildExternalQuery(sig, direction = "down", verbose = FALSE), "Could not map enough")
+})
+
+test_that("buildExternalQuery errors when direction splitting has no score", {
+  sig <- fake_signature(c("A1", "B1"))
+  expect_error(buildExternalQuery(sig, direction = "up", verbose = FALSE), "needs a 'score' column")
+})
+
+test_that("buildExternalQuery truncates to max_genes by |score| and flags it", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) character()
+  )
+  sig <- fake_signature(paste0("G", 1:10), score = 10:1)
+  q <- buildExternalQuery(sig, max_genes = 3, verbose = FALSE)
+  expect_equal(q$genes, c("G1", "G2", "G3"))
+  expect_true(q$truncated)
+  expect_equal(q$n_input, 10)
+})
+
+test_that("buildExternalQuery errors when fewer than two symbols map", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) character()
+  )
+  sig <- fake_signature(c("ENSG00000000001", "ENSG00000000002"))
+  expect_error(buildExternalQuery(sig, verbose = FALSE), "Could not map enough")
+})
+
+test_that("buildExternalQuery refuses non-transcriptomics signatures", {
+  sig <- fake_signature(c("P12345", "Q67890"), assay_type = "proteomics")
+  expect_error(buildExternalQuery(sig, verbose = FALSE), "transcriptomics signatures only")
+})
+
+test_that("buildExternalQuery reports organism code and unmapped names", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) c(ENSG00000141510 = "TP53"),
+    lookupSymbolsInBiomart = function(...) character()
+  )
+  sig <- fake_signature(c("ENSG00000141510", "BRCA1", "ENSG00000000000"), organism = "Mus musculus")
+  q <- buildExternalQuery(sig, verbose = FALSE)
+  expect_equal(q$organism_code, "mmu")
+  expect_setequal(q$genes, c("TP53", "BRCA1"))
+  expect_equal(q$unmapped, "ENSG00000000000")
+  expect_equal(q$n_unmapped, 1)
+})
+
+test_that("lookupSymbolsInBiomart reports a failed lookup instead of swallowing it", {
+  testthat::local_mocked_bindings(
+    biomartSymbolTable = function(ensembl_ids, organism) stop("Ensembl site unresponsive (HTTP 503)")
+  )
+  m <- lookupSymbolsInBiomart(c("ENSG00000126353"), "Homo sapiens")
+  expect_length(m, 0)
+  expect_match(attr(m, "error"), "HTTP 503")
+})
+
+test_that("buildExternalQuery names the lookup failure when too few symbols map", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) structure(character(), error = "Ensembl site unresponsive (HTTP 503)")
+  )
+  sig <- fake_signature(c("ENSG00000000001", "ENSG00000000002"))
+  expect_error(buildExternalQuery(sig, verbose = FALSE), "HTTP 503")
+})
+
+test_that("buildExternalQuery surfaces lookup failures as messages when some symbols still map", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) structure(character(), error = "could not connect to the database"),
+    lookupSymbolsInBiomart = function(...) c(ENSG00000141510 = "TP53")
+  )
+  sig <- fake_signature(c("ENSG00000141510", "BRCA1"))
+  expect_message(q <- buildExternalQuery(sig, verbose = TRUE), "could not connect to the database")
+  expect_setequal(q$genes, c("TP53", "BRCA1"))
+  expect_match(q$lookup_errors, "could not connect")
+})
+
+test_that("buildExternalQuery says so when a direction has no features", {
+  sig <- fake_signature(c("A1", "B1", "C1"), score = c(3, 2, 1))
+  expect_error(buildExternalQuery(sig, direction = "down", verbose = FALSE), "no features with a negative score")
+  expect_error(buildExternalQuery(sig, direction = "down", verbose = FALSE), "direction = 'combined' or 'up'")
+})
+
+test_that("buildExternalQuery's message distinguishes the query genes from the hits", {
+  testthat::local_mocked_bindings(
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) character()
+  )
+  sig <- fake_signature(paste0("G", 1:10), score = 10:1)
+  expect_message(buildExternalQuery(sig, max_genes = 3, verbose = TRUE),
+                 "query is the 3 strongest of the 10 mapped genes by \\|score\\|")
+  expect_message(buildExternalQuery(sig, verbose = TRUE), "query is all 10 genes")
+})
diff --git a/tests/testthat/test_externalRummagene.R b/tests/testthat/test_externalRummagene.R
new file mode 100644
index 00000000..2f8255e8
--- /dev/null
+++ b/tests/testthat/test_externalRummagene.R
@@ -0,0 +1,53 @@
+# Rummagene adapter. Parsing runs against a saved response captured from
+# rummagene.com on 2026-10-07 with a 12-gene interferon query; the network
+# layer is mocked.
+
+read_fixture <- function(name) {
+  jsonlite::fromJSON(testthat::test_path("test_data", "external", name), simplifyVector = FALSE)
+}
+ifn_query <- function(organism = "Homo sapiens", code = "hsa") {
+  base::list(signature_name = "ifn", organism = organism, organism_code = code, direction = "combined",
+             genes = c("ISG15", "IFI6", "MX1"), n_input = 3, n_mapped = 3, n_unmapped = 0,
+             truncated = FALSE, unmapped = character())
+}
+
+test_that("parseRummagene flattens hits into the common frame", {
+  out <- parseRummagene(read_fixture("rummagene_enrich.json"), ifn_query())
+  expect_s3_class(out, "data.frame")
+  expect_equal(nrow(out), 3)
+  expect_equal(colnames(out)[1:12], EXTERNAL_COLUMNS)
+  expect_equal(out$source[1], "rummagene")
+  expect_equal(out$rank, 1:3)
+  expect_equal(out$id[1], "PMC11278796-mmc3.docx-0-Target_gene")
+  expect_match(out$title[1], "^Spontaneous NETosis")
+  expect_equal(out$url[1], "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11278796/")
+  expect_equal(out$score_label[1], "odds ratio")
+  expect_equal(out$n_overlap[1], 12)
+  expect_equal(out$n_set[1], 22)
+  expect_equal(out$pmcid[1], "PMC11278796")
+  expect_equal(out$year[1], 2023)
+  expect_equal(attr(out, "total_count"), 21423)
+  expect_equal(attr(out, "query")$signature_name, "ifn")
+})
+
+test_that("parseRummagene handles an empty result", {
+  payload <- list(data = list(currentBackground = list(enrich = list(totalCount = 0, nodes = list()))))
+  out <- parseRummagene(payload, ifn_query())
+  expect_equal(nrow(out), 0)
+  expect_equal(attr(out, "total_count"), 0)
+})
+
+test_that("externalRummagene upper-cases genes and passes limit", {
+  seen <- NULL
+  testthat::local_mocked_bindings(
+    externalGraphql = function(url, query, variables = list(), timeout = 60) {
+      seen <<- variables
+      read_fixture("rummagene_enrich.json")
+    }
+  )
+  q <- ifn_query("Mus musculus", "mmu"); q$genes <- c("Isg15", "Ifi6", "Mx1")
+  out <- externalRummagene(q, limit = 7)
+  expect_equal(unlist(seen$genes), c("ISG15", "IFI6", "MX1"))
+  expect_equal(seen$first, 7L)
+  expect_equal(nrow(out), 3)
+})
diff --git a/tests/testthat/test_externalRummageo.R b/tests/testthat/test_externalRummageo.R
new file mode 100644
index 00000000..712e77d2
--- /dev/null
+++ b/tests/testthat/test_externalRummageo.R
@@ -0,0 +1,65 @@
+# RummaGEO adapter. Parsing runs against a saved response captured from
+# rummageo.com on 2026-10-07 with a 12-gene interferon query; the network
+# layer is mocked.
+
+read_fixture <- function(name) {
+  jsonlite::fromJSON(testthat::test_path("test_data", "external", name), simplifyVector = FALSE)
+}
+ifn_query <- function(organism = "Homo sapiens", code = "hsa") {
+  base::list(signature_name = "ifn", organism = organism, organism_code = code, direction = "combined",
+             genes = c("ISG15", "IFI6", "MX1"), n_input = 3, n_mapped = 3, n_unmapped = 0,
+             truncated = FALSE, unmapped = character())
+}
+
+test_that("parseRummageo flattens hits and derives GEO links", {
+  out <- parseRummageo(read_fixture("rummageo_enrich.json"), ifn_query())
+  expect_equal(nrow(out), 3)
+  expect_equal(colnames(out)[1:12], EXTERNAL_COLUMNS)
+  expect_equal(out$source[1], "rummageo")
+  expect_equal(out$id[1], "GSE218462,GSE218464-0-vs-1-human up")
+  expect_equal(out$gse[1], "GSE218462,GSE218464")
+  expect_equal(out$url[1], "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE218462")
+  expect_equal(out$regulation[1], "up")
+  expect_equal(out$contrast[1], "0-vs-1")
+  expect_equal(out$score_label[1], "odds ratio")
+  expect_equal(out$n_overlap[1], 11)
+  expect_equal(out$n_set[1], 34)
+  expect_equal(attr(out, "total_count"), 18448)
+})
+
+test_that("rummageoBackgroundId picks the background by species", {
+  testthat::local_mocked_bindings(
+    externalGraphql = function(url, query, variables = list(), timeout = 60) {
+      list(data = list(backgrounds = list(nodes = list(
+        list(id = "mouse-id", species = "mouse"),
+        list(id = "human-id", species = "human")
+      ))))
+    }
+  )
+  expect_equal(rummageoBackgroundId("hsa"), "human-id")
+  expect_equal(rummageoBackgroundId("mmu"), "mouse-id")
+})
+
+test_that("externalRummageo refuses organisms RummaGEO does not index", {
+  q <- ifn_query("Rattus norvegicus", NA_character_)
+  expect_error(externalRummageo(q), "only supports Homo sapiens and Mus musculus")
+})
+
+test_that("externalRummageo sends mouse symbols unchanged with the mouse background", {
+  seen <- list()
+  testthat::local_mocked_bindings(
+    externalGraphql = function(url, query, variables = list(), timeout = 60) {
+      if (grepl("backgrounds", query, fixed = TRUE)) {
+        return(list(data = list(backgrounds = list(nodes = list(list(id = "mouse-id", species = "mouse"))))))
+      }
+      seen <<- variables
+      read_fixture("rummageo_enrich.json")
+    }
+  )
+  q <- ifn_query("Mus musculus", "mmu"); q$genes <- c("Isg15", "Ifi6", "Mx1")
+  out <- externalRummageo(q, limit = 5)
+  expect_equal(seen$id, "mouse-id")
+  expect_equal(unlist(seen$genes), c("Isg15", "Ifi6", "Mx1"))
+  expect_equal(seen$first, 5L)
+  expect_equal(nrow(out), 3)
+})
diff --git a/tests/testthat/test_external_live.R b/tests/testthat/test_external_live.R
new file mode 100644
index 00000000..b66b6b19
--- /dev/null
+++ b/tests/testthat/test_external_live.R
@@ -0,0 +1,36 @@
+# Hits the real services. Off by default; run with
+#   SIGREPO_LIVE_EXTERNAL=true Rscript -e 'devtools::test(filter = "external_live")'
+skip_unless_live <- function() {
+  testthat::skip_if_not(
+    base::identical(base::tolower(base::Sys.getenv("SIGREPO_LIVE_EXTERNAL")), "true"),
+    "SIGREPO_LIVE_EXTERNAL is not 'true'"
+  )
+}
+ifn_query <- base::list(
+  signature_name = "interferon_12", organism = "Homo sapiens", organism_code = "hsa", direction = "combined",
+  genes = c("ISG15", "IFI6", "IFI27", "MX1", "OAS1", "IFIT1", "IFIT3", "RSAD2", "IFI44L", "STAT1", "IRF7", "OASL"),
+  n_input = 12, n_mapped = 12, n_unmapped = 0, truncated = FALSE, unmapped = character()
+)
+
+test_that("live: Rummagene returns interferon papers", {
+  skip_unless_live()
+  out <- externalRummagene(ifn_query, limit = 5)
+  expect_gt(nrow(out), 0)
+  expect_equal(colnames(out)[1:12], EXTERNAL_COLUMNS)
+  expect_true(all(grepl("^PMC", out$pmcid[!is.na(out$pmcid)])))
+})
+
+test_that("live: RummaGEO returns human GEO contrasts", {
+  skip_unless_live()
+  out <- externalRummageo(ifn_query, limit = 5)
+  expect_gt(nrow(out), 0)
+  expect_true(all(out$species == "human"))
+})
+
+test_that("live: CORESH ranks datasets within the timeout", {
+  skip_unless_live()
+  out <- externalCoresh(ifn_query, limit = 5, timeout = 180)
+  expect_gt(nrow(out), 0)
+  expect_match(attr(out, "job_url"), "^https://alserglab.wustl.edu/coresh/load/")
+  expect_equal(out$score_label[1], "% variance")
+})
diff --git a/tests/testthat/test_hypeR_client.R b/tests/testthat/test_hypeR_client.R
index 2c63353b..12119f21 100644
--- a/tests/testthat/test_hypeR_client.R
+++ b/tests/testthat/test_hypeR_client.R
@@ -1,213 +1,1078 @@
-test_that("prepareHypeRSignatures builds hypergeometric query vectors", {
+test_that("hypergeometric results match a direct hypeR::hypeR() call", {
   testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
+  vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, split = FALSE, verbose = FALSE)$signatures[[1]]
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  direct <- hypeR::hypeR(vec, hyper_genesets(), test = "hypergeometric")
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
 
-  prepared <- SigRepo::prepareHypeRSignatures(
-    omic_signature = LLFS_Aging_Gene_2023,
-    method = "hypergeo",
-    verbose = FALSE
+  expect_true(inherits(res, "hyp"))
+  expect_equal(res$data, direct$data)
+})
+
+test_that("kstest results match a direct hypeR::hypeR() call: weighted at power 1, ranked at power 0", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+  vecs <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures
+
+  # fdr_scope = "query" keeps hypeR's own per-query FDR, so each side matches a direct call.
+  weighted <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", power = 1,
+                          fdr_scope = "query", verbose = FALSE)
+  for (side in c("sig_a | up", "sig_a | down")) {
+    expect_equal(weighted$data[[side]]$data, hypeR::hypeR(vecs[[side]], hyper_genesets(), test = "kstest", power = 1)$data)
+    expect_equal(weighted$data[[side]]$info[["Signature Type"]], "weighted")
+  }
+
+  # power = 0 is hypeR's ranked signature (gene names in rank order), not the
+  # weighted branch with all weights 1, which scores differently.
+  ranked <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", power = 0,
+                        fdr_scope = "query", verbose = FALSE)
+  for (side in c("sig_a | up", "sig_a | down")) {
+    expect_equal(ranked$data[[side]]$data, hypeR::hypeR(names(vecs[[side]]), hyper_genesets(), test = "kstest")$data)
+    expect_equal(ranked$data[[side]]$info[["Signature Type"]], "ranked")
+  }
+})
+
+test_that("split queries return a multihyp with aligned SigRepo provenance", {
+  testthat::skip_if_not_installed("hypeR")
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), verbose = FALSE)
+
+  expect_true(inherits(res, "multihyp"))
+  expect_equal(names(res$data), c("sig_a | Old", "sig_a | Young"))
+
+  provenance_keys <- SigRepo:::HYPER_PROVENANCE_KEYS
+  for (hyp_obj in res$data) {
+    expect_equal(utils::tail(names(hyp_obj$info), length(provenance_keys)), provenance_keys)
+  }
+  expect_equal(res$data[["sig_a | Old"]]$info[["Group Label"]], "Old")
+  expect_equal(res$data[["sig_a | Old"]]$info[["SigRepo Signature Name"]], "sig_a")
+  expect_equal(res$data[["sig_a | Old"]]$info[["SigRepo Signature ID"]], "")
+  expect_equal(res$data[["sig_a | Old"]]$info[["Symbol Source"]], "signature$symbol")
+})
+
+test_that("hypeR's own plotting and export functions work on the result", {
+  testthat::skip_if_not_installed("hypeR")
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), verbose = FALSE)
+
+  expect_no_error(hypeR::hyp_dots(res))
+
+  xlsx <- tempfile(fileext = ".xlsx")
+  on.exit(unlink(xlsx), add = TRUE)
+  expect_no_error(hypeR::hyp_to_excel(res, file_path = xlsx))
+  expect_true(file.exists(xlsx))
+})
+
+test_that("background = \"difexp\" uses each signature's measured genes", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), background = "difexp", verbose = FALSE)
+
+  expect_equal(res$data[["sig_a | Old"]]$info$Background, "5")
+  expect_equal(res$data[["sig_a | Young"]]$info$Background, "5")
+})
+
+test_that("background = \"difexp\" falls back to 23467 with a warning when there is no difexp", {
+  testthat::skip_if_not_installed("hypeR")
+
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(),
+                             background = "difexp", split = FALSE, verbose = FALSE),
+    "no difexp gene symbols for 'sig_a'; used background = 23467", fixed = TRUE
   )
+  expect_equal(res$info$Background, "23467")
+})
+
+test_that("unusable signatures are skipped with a warning; all unusable is an error", {
+  testthat::skip_if_not_installed("hypeR")
+  bad <- make_hyper_sig("bad", signature = hyper_sig_table(symbols = FALSE))
+
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = list(good = make_hyper_sig("good"), bad = bad),
+                             genesets = hyper_genesets(), split = FALSE, verbose = FALSE),
+    "Skipped 1 signature(s): 'bad' (no_gene_symbols", fixed = TRUE
+  )
+  # A list input stays a multihyp even when only one signature survives.
+  expect_true(inherits(res, "multihyp"))
+  expect_equal(names(res$data), "good")
 
-  expect_true(methods::is(prepared, "list"))
-  expect_true("signatures" %in% base::names(prepared))
-  expect_true("metadata" %in% base::names(prepared))
-  expect_equal(base::length(prepared$signatures), 1)
-  expect_true(base::length(prepared$signatures[[1]]) > 0)
-  expect_true(methods::is(prepared$metadata, "data.frame"))
+  expect_error(
+    suppressWarnings(runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = bad, genesets = hyper_genesets(), verbose = FALSE)),
+    "No signature produced a hypeR query vector", fixed = TRUE
+  )
 })
 
-test_that("prepareHypeRSignatures builds ranked query vectors for GSEA-style enrichment", {
+test_that("runHypeR requires genesets and rejects the removed arguments", {
   testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  expect_error(runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, verbose = FALSE), "'genesets' must be \"msigdb\"", fixed = TRUE)
+  expect_error(runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), method = "gsea"), "unused argument")
+  expect_error(runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "gsea"), "'test' is required", fixed = TRUE)
+})
 
-  prepared <- SigRepo::prepareHypeRSignatures(
-    omic_signature = LLFS_Aging_Gene_2023,
-    method = "gsea",
-    verbose = FALSE
+test_that("runHypeR requires organism and test, with no default for either", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
+
+  expect_error(SigRepo::runHypeR(omic_signature = sig, test = "hypergeometric", genesets = hyper_genesets()),
+               "'organism' is required", fixed = TRUE)
+  expect_error(SigRepo::runHypeR(omic_signature = sig, organism = "", test = "hypergeometric", genesets = hyper_genesets()),
+               "'organism' is required", fixed = TRUE)
+  expect_error(SigRepo::runHypeR(omic_signature = sig, organism = c("Homo sapiens", "Mus musculus"), test = "hypergeometric",
+                                 genesets = hyper_genesets()), "'organism' is required", fixed = TRUE)
+  expect_error(SigRepo::runHypeR(omic_signature = sig, organism = "Homo sapiens", genesets = hyper_genesets()),
+               "'test' is required: one of test = \"hypergeometric\", test = \"kstest\", test = \"fgsea\"", fixed = TRUE)
+  expect_error(SigRepo::runHypeR(omic_signature = sig, organism = "Homo sapiens", test = c("hypergeometric", "kstest"),
+                                 genesets = hyper_genesets()), "'test' is required", fixed = TRUE)
+})
+
+test_that("runHypeR errors when a signature is not of the requested organism, including mixed organisms", {
+  testthat::skip_if_not_installed("hypeR")
+  human <- make_hyper_sig("human_sig")
+  mouse <- make_hyper_sig("mouse_sig", organism = "Mus musculus")
+
+  expect_error(
+    runToyHypeR(omic_signature = mouse, organism = "Homo sapiens", test = "hypergeometric", genesets = hyper_genesets(), verbose = FALSE),
+    "Every signature must be of organism = \"Homo sapiens\"; run signatures of different organisms in separate runHypeR() calls. Not Homo sapiens: 'mouse_sig' (Mus musculus).",
+    fixed = TRUE
+  )
+  expect_error(
+    runToyHypeR(omic_signature = list(human, mouse), organism = "Homo sapiens", test = "kstest", genesets = hyper_genesets(), verbose = FALSE),
+    "'mouse_sig' (Mus musculus)", fixed = TRUE
+  )
+  expect_error(
+    runToyHypeR(omic_signature = list(human, mouse), organism = "Mus musculus", test = "hypergeometric", genesets = hyper_genesets(), verbose = FALSE),
+    "'human_sig' (Homo sapiens)", fixed = TRUE
+  )
+  # Case and surrounding spaces do not matter (production stores "Homo Sapiens" for some signatures).
+  expect_s3_class(
+    runToyHypeR(omic_signature = human, organism = " homo SAPIENS ", test = "hypergeometric", genesets = hyper_genesets(), split = FALSE, verbose = FALSE),
+    "hyp"
+  )
+  # hypeR-native input has no metadata, so any organism is accepted.
+  expect_s3_class(
+    runToyHypeR(signature = c("A", "B"), organism = "Mus musculus", test = "hypergeometric", genesets = hyper_genesets(), verbose = FALSE),
+    "hyp"
+  )
+})
+
+test_that("runHypeR passes organism to MSigDB as the species", {
+  seen <- NULL
+  testthat::local_mocked_bindings(
+    getHypeRGenesets = function(genesets, msigdb_species = NULL, msigdb_collection = NULL, msigdb_subcollection = NULL, msigdb_clean = FALSE) {
+      seen <<- list(genesets = genesets, msigdb_species = msigdb_species, msigdb_collection = msigdb_collection)
+      hyper_genesets()
+    }
+  )
+  runToyHypeR(omic_signature = make_hyper_sig(organism = "Mus musculus"), organism = "Mus musculus", test = "hypergeometric",
+              genesets = "msigdb", msigdb_collection = "MH", split = FALSE, verbose = FALSE)
+  expect_equal(seen, list(genesets = "msigdb", msigdb_species = "Mus musculus", msigdb_collection = "MH"))
+
+  runToyHypeR(omic_signature = make_hyper_sig(), organism = "Homo sapiens", test = "hypergeometric",
+              genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
+  expect_null(seen$msigdb_species)
+})
+
+# ---- Task 3c regressions (stress-test bugs B1, B2, B5, U1) ----
+
+test_that("B5/E08: runHypeR rejects a background that is not a number, a gene vector or \"difexp\"", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
+  called <- FALSE
+  testthat::local_mocked_bindings(
+    collectHypeRSignatures = function(...) {
+      called <<- TRUE
+      stop("signature work started")
+    },
+    .package = "SigRepo"
   )
 
-  expect_equal(base::length(prepared$signatures), 1)
-  expect_true(is.numeric(prepared$signatures[[1]]))
-  expect_true(!is.null(base::names(prepared$signatures[[1]])))
-  expect_true(base::length(prepared$signatures[[1]]) > 0)
+  for (bad in list("Difexp", "DIFEXP", "TP53", NA, -1, 0, Inf, c(100, 200), TRUE)) {
+    expect_error(
+      runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), background = bad, verbose = FALSE),
+      "background must be a number, a gene vector, or \"difexp\"", fixed = TRUE
+    )
+  }
+  expect_false(called)
+})
+
+test_that("B5/E09: runHypeR rejects a split that is not TRUE or FALSE", {
+  testthat::skip_if_not_installed("hypeR")
+  for (bad in list("yes", NA)) {
+    expect_error(
+      runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), split = bad, verbose = FALSE),
+      "'split' must be TRUE or FALSE", fixed = TRUE
+    )
+  }
+})
+
+test_that("B5/E10: runHypeR rejects omic_signature together with signature_id", {
+  testthat::skip_if_not_installed("hypeR")
+  expect_error(
+    runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", conn_handler = list(), signature_id = "1", omic_signature = make_hyper_sig(),
+                      genesets = hyper_genesets(), verbose = FALSE),
+    "Supply either 'omic_signature' or 'signature_id'/'signature_name', not both", fixed = TRUE
+  )
 })
 
-test_that("runHypeR runs hypergeometric enrichment on an OmicSignature object", {
+test_that("B2: runHypeR multihyp names are unique", {
   testthat::skip_if_not_installed("hypeR")
+  gs <- list(SET1 = c("TP53", "MYC", "EGFR", "KRAS"), SET2 = c("GENE_A", "GENE_B", "BRCA1"))
+  a <- make_hyper_sig("X", signature = data.frame(
+    probe_id = c("p1", "p2"), feature_name = c("f1", "f2"), score = c(2, -2),
+    group_label = factor(c("Up", "Down")), symbol = c("TP53", "MYC")
+  ))
+  b <- make_hyper_sig("X | Up", signature = data.frame(
+    probe_id = "p1", feature_name = "f1", score = 1, group_label = factor(NA), symbol = "EGFR"
+  ), type = "uni-directional")
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = list(a, b), genesets = gs, verbose = FALSE)
 
-  feature_hits <- base::unique(utils::head(LLFS_Aging_Gene_2023$signature$feature_name, 10))
-  genesets <- base::list(
-    hit_set = feature_hits,
-    miss_set = base::paste0("missing_", base::seq_len(10))
+  expect_equal(names(res$data), c("X | Down", "X | Up", "X | Up (2)"))
+  expect_equal(res$data[["X | Up (2)"]]$info[["SigRepo Signature Name"]], "X | Up")
+  xlsx <- tempfile(fileext = ".xlsx")
+  on.exit(unlink(xlsx), add = TRUE)
+  expect_no_error(hypeR::hyp_to_excel(res, file_path = xlsx))
+})
+
+test_that("B1: hypeRToExcel() writes long and unsafe query names as safe, unique sheets with an index", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("openxlsx")
+  gs <- list(SET1 = c("TP53", "MYC", "EGFR", "KRAS"), SET2 = c("GENE_A", "GENE_B", "BRCA1"))
+  arms <- function() data.frame(
+    probe_id = c("p1", "p2"), feature_name = c("f1", "f2"), score = c(2, -2),
+    group_label = factor(c("Up", "Down")), symbol = c("TP53", "MYC")
   )
+  long <- make_hyper_sig("Aging_Hs_SomeTissue_Treatment_vs_Control_Author2025", signature = arms())
+  colon <- make_hyper_sig("Aging: a/b [c]?*", signature = arms())
+  xlsx <- tempfile(fileext = ".xlsx")
+  on.exit(unlink(xlsx), add = TRUE)
+
+  hyp <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = list(long, colon), genesets = gs, verbose = FALSE)
+  original_names <- names(hyp$data)
+  expect_error(hypeR::hyp_to_excel(hyp, file_path = xlsx), "Max length is 31 characters", fixed = TRUE)
 
-  hyp_res <- SigRepo::runHypeR(
-    omic_signature = LLFS_Aging_Gene_2023,
-    genesets = genesets,
-    method = "hypergeo",
-    plotting = FALSE,
-    quiet = TRUE,
-    verbose = FALSE
+  index <- SigRepo::hypeRToExcel(hyp, file_path = xlsx)
+
+  sheets <- openxlsx::getSheetNames(xlsx)
+  expect_equal(sheets, c("index", index$sheet, "versioning"))
+  expect_true(all(nchar(sheets) <= 31))
+  expect_false(any(grepl("[][\\\\/?*:]", sheets)))
+  expect_equal(anyDuplicated(tolower(sheets)), 0L)
+  # The two long names share their first 31 characters, so they differ only by suffix.
+  expect_equal(index$sheet[1:2], c("Aging_Hs_SomeTissue_Treatment_v", "Aging_Hs_SomeTissue_Treatme (2)"))
+  expect_equal(index$query, original_names)
+  expect_equal(index$group_label, c("Down", "Up", "Down", "Up"))
+  expect_equal(openxlsx::read.xlsx(xlsx, sheet = "index")$query, original_names)
+  # The caller's object keeps its names.
+  expect_equal(names(hyp$data), original_names)
+})
+
+test_that("hypeRSheetNames sanitises, truncates and de-duplicates without regard to case", {
+  out <- SigRepo:::hypeRSheetNames(
+    c("Index", "a/b", "A_B", "'quoted'", "", strrep("x", 40), strrep("X", 40)),
+    reserved = c("index", "versioning")
   )
+  expect_equal(out, c("Index (2)", "a_b", "A_B (2)", "quoted", "sheet", strrep("x", 31), paste0(strrep("X", 27), " (2)")))
+  expect_true(all(nchar(out) <= 31))
+})
 
-  expect_true(methods::is(hyp_res, "list"))
-  expect_true("result" %in% base::names(hyp_res))
-  expect_s3_class(hyp_res$result, "R6")
-  expect_true("hyp" %in% class(hyp_res$result))
+test_that("hypeRToExcel() names a single hyp's sheet from its provenance and rejects other objects", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("openxlsx")
+  xlsx <- tempfile(fileext = ".xlsx")
+  on.exit(unlink(xlsx), add = TRUE)
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
+  expect_true(inherits(res, "hyp"))
+  index <- SigRepo::hypeRToExcel(res, file_path = xlsx, index = FALSE)
+  expect_equal(openxlsx::getSheetNames(xlsx), c("sig_a", "versioning"))
+  expect_equal(index$signature_name, "sig_a")
+
+  expect_error(SigRepo::hypeRToExcel(list(), file_path = xlsx), "must be a hypeR hyp or multihyp", fixed = TRUE)
 })
 
-test_that("runHypeR passes additional hypeR arguments through dots", {
+test_that("U1: weighted kstest drops genesets whose hits all score 0, with a warning", {
   testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_zero_score_sig()
+  vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures[["zero | up"]]
+  expect_equal(vec, c(A = 2, D = 1, B = 0, C = -1))
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_zero_score_genesets(),
+                             test = "kstest", power = 1, fdr_scope = "query", verbose = FALSE),
+    "Dropped 1 geneset(s) that hypeR's kstest cannot score (all hits score 0, or the geneset covers every query gene): S2", fixed = TRUE
+  )
+  up <- res$data[["zero | up"]]
+  expect_false("S2" %in% up$data$label)
 
-  feature_hits <- base::unique(utils::head(LLFS_Aging_Gene_2023$signature$feature_name, 10))
-  genesets <- base::list(
-    hit_set = feature_hits,
-    miss_set = base::paste0("missing_", base::seq_len(10))
+  direct <- hypeR::hypeR(vec, list(S1 = c("A", "D"), S3 = "C"), test = "kstest", power = 1)
+  expect_equal(up$data$score[up$data$label == "S1"], direct$data$score[direct$data$label == "S1"])
+  expect_equal(up$data, direct$data)
+})
+
+test_that("U1: power = 0 drops nothing and does not warn", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_zero_score_sig()
+  vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures[["zero | up"]]
+
+  expect_no_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_zero_score_genesets(),
+                             test = "kstest", power = 0, fdr_scope = "query", verbose = FALSE)
   )
+  expect_true("S2" %in% res$data[["zero | up"]]$data$label)
+  expect_equal(res$data[["zero | up"]]$data, hypeR::hypeR(names(vec), hyper_zero_score_genesets(), test = "kstest")$data)
+})
+
+test_that("U1: dropZeroWeightGenesets keeps the input kind and returns it unchanged when nothing is dropped", {
+  testthat::skip_if_not_installed("hypeR")
+  query <- c(A = 2, D = 1, B = 0, C = -1)
+  gs_list <- c(hyper_zero_score_genesets(), list(S4 = c("B", "Z"), S5 = "NOT_IN_QUERY"))
+
+  from_list <- SigRepo:::dropZeroWeightGenesets(gs_list, query)
+  expect_equal(from_list$genesets, gs_list[c("S1", "S3", "S5")])
+  expect_equal(from_list$dropped, c("S2", "S4"))
+
+  gsets_obj <- hypeR::gsets$new(gs_list, name = "test", version = "v1", quiet = TRUE)
+  from_gsets <- SigRepo:::dropZeroWeightGenesets(gsets_obj, query)
+  expect_true(inherits(from_gsets$genesets, "gsets"))
+  expect_equal(from_gsets$genesets$genesets, gs_list[c("S1", "S3", "S5")])
+  expect_equal(from_gsets$genesets$name, "test")
+  expect_equal(from_gsets$genesets$version, "v1")
 
-  hyp_res <- SigRepo::runHypeR(
-    omic_signature = LLFS_Aging_Gene_2023,
-    genesets = genesets,
-    method = "hypergeo",
-    plotting = FALSE,
-    quiet = TRUE,
-    verbose = FALSE,
-    background = 12345
+  nodes <- data.frame(label = names(gs_list), row.names = paste0("n", seq_along(gs_list)))
+  edges <- data.frame(from = "n1", to = "n2")
+  rgsets_obj <- hypeR::rgsets$new(gs_list, nodes, edges, name = "rtest", version = "v2", quiet = TRUE)
+  from_rgsets <- SigRepo:::dropZeroWeightGenesets(rgsets_obj, query)
+  expect_true(inherits(from_rgsets$genesets, "rgsets"))
+  expect_equal(names(from_rgsets$genesets$genesets), c("S1", "S3", "S5"))
+  expect_equal(from_rgsets$dropped, c("S2", "S4"))
+
+  no_zero <- c(A = 2, B = 1)
+  unchanged <- SigRepo:::dropZeroWeightGenesets(gsets_obj, no_zero)
+  expect_identical(unchanged$genesets, gsets_obj)
+  expect_identical(unchanged$dropped, character())
+})
+
+test_that("U1 fix round 1: the zero-weight check sees the gene-vector background reduction", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_zero_score_sig()
+  vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures[["zero | up"]]
+  gs <- list(S1 = c("A", "D"), S2 = c("B", "A"), S3 = "C", S4 = c("B", "A", "X"))
+  bg <- c("B", "C", "D")
+
+  # After reduction to bg, S2 and S4 hit only B (score 0); S1 keeps D, S3 keeps C.
+  # The ranking is reduced to bg as well, so A leaves it.
+  warnings <- character()
+  res <- withCallingHandlers(
+    runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "kstest", background = bg,
+                fdr_scope = "query", verbose = FALSE),
+    warning = function(w) { warnings <<- c(warnings, conditionMessage(w)); invokeRestart("muffleWarning") }
   )
+  expect_true("Dropped 2 geneset(s) that hypeR's kstest cannot score (all hits score 0, or the geneset covers every query gene): S2, S4" %in% warnings)
+  expect_true(any(grepl("background: removed 2 query gene(s) not in the background gene vector", warnings, fixed = TRUE)))
+
+  direct <- hypeR::hypeR(vec[names(vec) %in% bg], gs[c("S1", "S3")], test = "kstest", background = bg, power = 1)
+  expect_equal(res$data[["zero | up"]]$data, direct$data)
 
-  expect_equal(hyp_res$result$args$background, 12345)
+  # Helper: background is applied only to the check; the returned object is not reduced.
+  dz <- SigRepo:::dropZeroWeightGenesets(gs, vec, background = bg)
+  expect_equal(dz$dropped, c("S2", "S4"))
+  expect_identical(dz$genesets, gs[c("S1", "S3")])
+  expect_identical(SigRepo:::dropZeroWeightGenesets(gs, vec)$dropped, character())
+  expect_identical(SigRepo:::dropZeroWeightGenesets(gs, vec, background = 23467)$dropped, character())
 })
 
-test_that("runHypeR runs GSEA-style enrichment on an OmicSignature object", {
+# ---- Final-review fix wave (F1-F4) ----
+
+test_that("F1: kstest pval and fdr do not depend on power (only score does)", {
   testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+
+  by_label <- function(res) {
+    data <- do.call(rbind, lapply(names(res$data), function(q) cbind(query = q, res$data[[q]]$data)))
+    data[order(data$query, data$label), , drop = FALSE]
+  }
+  weighted <- by_label(runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", power = 1, verbose = FALSE))
+  unweighted <- by_label(runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", power = 0, verbose = FALSE))
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  expect_identical(weighted$label, unweighted$label)
+  expect_identical(weighted$pval, unweighted$pval)
+  expect_identical(weighted$fdr, unweighted$fdr)
+})
+
+test_that("F2: background = \"difexp\" removes hypergeometric query genes that difexp did not measure", {
+  testthat::skip_if_not_installed("hypeR")
+  sig_tbl <- hyper_sig_table()
+  sig_tbl$symbol <- c("A", "B", "C", "Z")
+  sig <- make_hyper_sig(signature = sig_tbl, difexp = hyper_difexp_table())
+  difexp_symbols <- unique(sig$difexp$gene_symbol)
+  expect_false("Z" %in% difexp_symbols)
 
-  feature_hits <- base::unique(utils::head(LLFS_Aging_Gene_2023$difexp$feature_name, 10))
-  genesets <- base::list(
-    hit_set = feature_hits,
-    miss_set = base::paste0("missing_", base::seq_len(10))
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), background = "difexp",
+                             split = FALSE, verbose = FALSE),
+    "background = \"difexp\": removed 1 query gene(s) not measured in difexp from: 'sig_a' (1)", fixed = TRUE
   )
 
-  hyp_res <- base::suppressWarnings(
-    SigRepo::runHypeR(
-      omic_signature = LLFS_Aging_Gene_2023,
-      genesets = genesets,
-      method = "gsea",
-      plotting = FALSE,
-      quiet = TRUE,
-      verbose = FALSE
+  direct <- hypeR::hypeR(c("A", "B", "C"), hyper_genesets(), test = "hypergeometric", background = difexp_symbols)
+  expect_equal(res$data, direct$data)
+})
+
+test_that("F3: a query with no genesets left is skipped and the rest of the batch still runs", {
+  testthat::skip_if_not_installed("hypeR")
+  zero_sig <- make_hyper_zero_score_sig()
+  other_sig <- make_hyper_sig(difexp = hyper_difexp_table())
+  other_vec <- SigRepo::prepareHypeRSignatures(omic_signature = other_sig, test = "kstest", verbose = FALSE)$signatures[["sig_a | up"]]
+
+  # The reviewer's reproduction used list(S2 = "B"), but hypeR 2.0.0's kstest
+  # errors on any one-geneset list ("dim(X) must have a positive length"), so
+  # other_sig could never return a result with it. S4 also hits only B.
+  gs <- list(S2 = "B", S4 = c("B", "X"))
+
+  warnings <- NULL
+  expect_no_error(
+    warnings <- testthat::capture_warnings(
+      res <- runToyHypeR(organism = "Homo sapiens", omic_signature = list(zero_sig, other_sig), genesets = gs,
+                               test = "kstest", fdr_scope = "query", verbose = FALSE)
     )
   )
 
-  expect_true("hyp" %in% class(hyp_res$result))
+  expect_length(warnings, 2)
+  expect_match(warnings[1], "Dropped 2 geneset(s) that hypeR's kstest cannot score (all hits score 0, or the geneset covers every query gene): S2, S4", fixed = TRUE)
+  expect_match(warnings[2], "Skipped 2 query(ies) with nothing left to test after removing zero-weight genesets or unmeasured genes: 'zero | up', 'zero | down'", fixed = TRUE)
+
+  expect_true(inherits(res, "multihyp"))
+  expect_equal(names(res$data), c("sig_a | up", "sig_a | down"))
+  expect_equal(res$data[[1]]$data, hypeR::hypeR(other_vec, gs, test = "kstest")$data)
+  expect_equal(res$data[[1]]$info[["SigRepo Signature Name"]], "sig_a")
+})
+
+test_that("F3: every query skipped is a clear error", {
+  testthat::skip_if_not_installed("hypeR")
+  expect_error(
+    suppressWarnings(runToyHypeR(organism = "Homo sapiens", omic_signature = make_hyper_zero_score_sig(), genesets = list(S2 = "B"),
+                                       test = "kstest", verbose = FALSE)),
+    "No query had genesets left to test", fixed = TRUE
+  )
+})
+
+test_that("F4: kstest drops a geneset that covers every query gene, at power 1 and power 0", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_cover_sig()
+  vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures[["cover | up"]]
+  expect_equal(vec, c(A = 3, B = 2, C = -1))
+  gs <- list(ALL = c("A", "B", "C", "X"), S2 = "A", S3 = "B")
+
+  for (pwr in c(1, 0)) {
+    expect_no_error(expect_warning(
+      res <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "kstest", power = pwr, fdr_scope = "query", verbose = FALSE),
+      "Dropped 1 geneset(s) that hypeR's kstest cannot score (all hits score 0, or the geneset covers every query gene): ALL",
+      fixed = TRUE
+    ))
+    expect_false("ALL" %in% res$data[["cover | up"]]$data$label)
+    direct_sig <- if (pwr == 0) names(vec) else vec
+    expect_equal(res$data[["cover | up"]]$data, hypeR::hypeR(direct_sig, list(S2 = "A", S3 = "B"), test = "kstest", power = pwr)$data)
+  }
+})
+
+# ---- Evaluation fixes (W1-W15) ----
+
+test_that("W3: the return type follows the input, not how many queries survive", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+  run <- function(..., test = "hypergeometric") runToyHypeR(organism = "Homo sapiens", test = test, genesets = hyper_genesets(), background = 23467, verbose = FALSE, ...)
+
+  expect_true(inherits(run(omic_signature = sig), "multihyp"))
+  expect_true(inherits(run(omic_signature = sig, split = FALSE), "hyp"))
+  # The ranked tests always give an up and a down query, so a multihyp.
+  expect_true(inherits(run(omic_signature = sig, test = "kstest"), "multihyp"))
+  expect_true(inherits(run(signature = c(A = 3, B = 1, C = -2), test = "kstest"), "multihyp"))
+  expect_true(inherits(run(signature = c("A", "B")), "hyp"))
+  expect_true(inherits(run(omic_signature = list(sig), split = FALSE), "multihyp"))
+  expect_true(inherits(run(omic_signature = list(sig), test = "kstest"), "multihyp"))
+
+  # A signature without group_label still gives a multihyp when split = TRUE.
+  tbl <- hyper_sig_table()
+  tbl$group_label <- NULL
+  uni <- make_hyper_sig(signature = tbl, type = "uni-directional")
+  uni_res <- run(omic_signature = uni)
+  expect_true(inherits(uni_res, "multihyp"))
+  expect_equal(names(uni_res$data), "sig_a")
 })
 
-test_that("runHypeR handles multiple signatures and returns multihyp", {
+test_that("W3: one id is a single input; several ids give a multihyp", {
   testthat::skip_if_not_installed("hypeR")
+  testthat::local_mocked_bindings(
+    getSignature = function(conn_handler, signature_id = NULL, signature_name = NULL, verbose = TRUE) {
+      list(make_hyper_sig(paste0("db_", signature_id)))
+    },
+    .package = "SigRepo"
+  )
+  one <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", conn_handler = list(), signature_id = 7, genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
+  expect_true(inherits(one, "hyp"))
+  expect_equal(one$info[["SigRepo Signature ID"]], "7")
+
+  two <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", conn_handler = list(), signature_id = c(7, 8), genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
+  expect_true(inherits(two, "multihyp"))
+  expect_equal(names(two$data), c("db_7", "db_8"))
+})
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+test_that("kstest always runs the up ranking and the negated down ranking, with FDR pooled across both", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+  up_vec <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)$signatures[["sig_a | up"]]
+  down_vec <- sort(-up_vec, decreasing = TRUE)
+  direct_up <- hypeR::hypeR(up_vec, hyper_genesets(), test = "kstest")$data
+  direct_down <- hypeR::hypeR(down_vec, hyper_genesets(), test = "kstest")$data
 
-  feature_hits <- base::unique(utils::head(LLFS_Aging_Gene_2023$signature$feature_name, 10))
-  genesets <- base::list(
-    hit_set = feature_hits,
-    miss_set = base::paste0("missing_", base::seq_len(10))
+  expect_error(
+    runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", direction = "down", verbose = FALSE),
+    "unused argument (direction = \"down\")", fixed = TRUE
   )
 
-  sig_list <- base::list(
-    first_sig = LLFS_Aging_Gene_2023,
-    second_sig = LLFS_Aging_Gene_2023
+  both <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", verbose = FALSE)
+  expect_equal(names(both$data), c("sig_a | up", "sig_a | down"))
+  keep <- setdiff(names(direct_up), "fdr")
+  expect_equal(both$data[["sig_a | up"]]$data[, keep], direct_up[, keep])
+  expect_equal(both$data[["sig_a | down"]]$data[, keep], direct_down[, keep])
+  expect_equal(unname(vapply(both$data, function(h) h$info[["SigRepo Direction"]], "")), c("up", "down"))
+  # One multiple-testing family: BH over the p-values of both runs together.
+  pooled <- signif(p.adjust(c(direct_up$pval, direct_down$pval), method = "fdr"), 2)
+  expect_equal(c(both$data[["sig_a | up"]]$data$fdr, both$data[["sig_a | down"]]$data$fdr), pooled)
+})
+
+test_that("W5: ks_source is rejected for a hypergeometric test", {
+  testthat::skip_if_not_installed("hypeR")
+  expect_error(
+    SigRepo::runHypeR(omic_signature = make_hyper_sig(), organism = "Homo sapiens", test = "hypergeometric", genesets = hyper_genesets(),
+                      ks_source = "signature", verbose = FALSE),
+    "'ks_source' only applies when test = \"kstest\"", fixed = TRUE
   )
+})
 
-  hyp_res <- SigRepo::runHypeR(
-    omic_signature = sig_list,
-    genesets = genesets,
-    method = "hypergeo",
-    plotting = FALSE,
-    quiet = TRUE,
-    verbose = FALSE
+test_that("W5: ks_source = \"signature\" runs kstest on a signature without difexp", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
+  expect_error(
+    suppressWarnings(runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", verbose = FALSE)),
+    "No signature produced a hypeR query vector", fixed = TRUE
   )
 
-  expect_true("multihyp" %in% class(hyp_res$result))
-  expect_equal(base::sort(base::names(hyp_res$signatures)), c("first_sig", "second_sig"))
-  expect_equal(base::sort(base::unique(hyp_res$metadata$signature_name)), c("first_sig", "second_sig"))
+  res <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_genesets(), test = "kstest", ks_source = "signature",
+                     fdr_scope = "query", verbose = FALSE)
+  up <- res$data[["sig_a | up"]]
+  expect_equal(up$data, hypeR::hypeR(c(A = 3, B = 2, C = -2, D = -3), hyper_genesets(), test = "kstest")$data)
+  expect_equal(up$info[["SigRepo Ranked Table"]], "signature")
+  expect_equal(up$info[["Symbol Source"]], "signature$symbol")
 })
 
-test_that("runHypeR accepts hypeR gsets objects directly", {
+test_that("W6: provenance records background source, split, score column and dropped genesets", {
   testthat::skip_if_not_installed("hypeR")
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), verbose = FALSE)$data[[1]]$info
+  expect_equal(
+    unlist(hyper[SigRepo:::HYPER_PROVENANCE_KEYS[5:14]], use.names = FALSE),
+    c("", "", "", "TRUE", "difexp-fallback", "0", "0", "0", "", "run")
+  )
 
-  feature_hits <- base::unique(utils::head(LLFS_Aging_Gene_2023$signature$feature_name, 10))
-  genesets <- hypeR::gsets$new(
-    genesets = base::list(
-      hit_set = feature_hits,
-      miss_set = base::paste0("missing_", base::seq_len(10))
-    ),
-    name = "test_sets",
-    version = "v1",
-    quiet = TRUE
+  expect_warning(
+    ks <- runToyHypeR(organism = "Homo sapiens", omic_signature = make_hyper_zero_score_sig(), genesets = hyper_zero_score_genesets(),
+                            test = "kstest", background = "difexp", verbose = FALSE),
+    "Dropped 1 geneset(s)", fixed = TRUE
   )
+  expect_equal(
+    unlist(ks$data[["zero | up"]]$info[SigRepo:::HYPER_PROVENANCE_KEYS[5:13]], use.names = FALSE),
+    c("up", "difexp", "score", "", "difexp", "0", "0", "1", "S2")
+  )
+  expect_equal(ks$data[["zero | down"]]$info[["SigRepo Direction"]], "down")
 
-  hyp_res <- SigRepo::runHypeR(
-    omic_signature = LLFS_Aging_Gene_2023,
-    genesets = genesets,
-    method = "hypergeo",
-    plotting = FALSE,
-    quiet = TRUE,
-    verbose = FALSE
+  expect_warning(
+    fallback <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(),
+                                  background = "difexp", split = FALSE, verbose = FALSE),
+    "no difexp gene symbols", fixed = TRUE
   )
+  expect_equal(fallback$info[["SigRepo Background Source"]], "difexp-fallback")
+  expect_equal(fallback$info[["SigRepo Split"]], "FALSE")
+})
 
-  expect_true("hyp" %in% class(hyp_res$result))
+test_that("W6: unmapped features and removed query genes are recorded per query", {
+  testthat::skip_if_not_installed("hypeR")
+  sig_tbl <- hyper_sig_table()
+  sig_tbl$symbol <- c("A", NA, "C", "Z")
+  sig <- make_hyper_sig(signature = sig_tbl, difexp = hyper_difexp_table())
+
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), background = "difexp", verbose = FALSE),
+    "removed 1 query gene(s) not measured in difexp from: 'sig_a | Young' (1)", fixed = TRUE
+  )
+  expect_equal(res$data[["sig_a | Old"]]$info[["SigRepo Features Unmapped"]], "1")
+  expect_equal(res$data[["sig_a | Old"]]$info[["SigRepo Query Genes Removed"]], "0")
+  expect_equal(res$data[["sig_a | Young"]]$info[["SigRepo Features Unmapped"]], "0")
+  expect_equal(res$data[["sig_a | Young"]]$info[["SigRepo Query Genes Removed"]], "1")
 })
 
-test_that("runHypeR can retrieve MSigDB genesets automatically", {
+test_that("W13: a gene-vector background also removes hypergeometric query genes outside it", {
   testthat::skip_if_not_installed("hypeR")
-  testthat::skip_if_not_installed("msigdbr")
+  bg <- c("A", "B", "C", "X1", "X2", "X3")
 
-  # This is the one test in the suite that needs MSigDB itself; every other
-  # hypeR test builds its gene sets inline. msigdbr 26.x stopped bundling the
-  # data and downloads it from zenodo.org on first use, so the test now depends
-  # on a third-party service being reachable.
-  #
-  # Probe that service through the exact call resolveHypeRGenesets() makes, and
-  # skip with the reason when it is down: an outage there is an environment
-  # failure, not a regression in runHypeR, and it should not turn the suite red
-  # for everyone. The probe also warms msigdbr's cache, so the call below does
-  # not download twice. A probe that SUCCEEDS leaves both assertions in force.
-  probe <- base::tryCatch(
-    {
-      base::suppressWarnings(
-        hypeR::msigdb_gsets(species = "Homo sapiens", collection = "H")
-      )
-      TRUE
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), background = bg,
+                             split = FALSE, verbose = FALSE),
+    "background: removed 1 query gene(s) not in the background gene vector from: 'sig_a' (1)", fixed = TRUE
+  )
+  expect_equal(res$data, hypeR::hypeR(c("A", "B", "C"), hyper_genesets(), background = bg)$data)
+  expect_equal(res$info[["SigRepo Background Source"]], "genes")
+  expect_equal(res$info[["SigRepo Query Genes Removed"]], "1")
+})
+
+test_that("W8: empty placeholder plots are removed unless plotting = TRUE", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig()
+
+  plain <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), split = FALSE, verbose = FALSE)
+  expect_length(plain$plots, 0L)
+  expect_equal(plain$data, hypeR::hypeR(c("A", "B", "C", "D"), hyper_genesets())$data)
+
+  plotted <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = hyper_genesets(), split = FALSE, plotting = TRUE, verbose = FALSE)
+  expect_gt(length(plotted$plots), 0L)
+})
+
+test_that("W14: difexp symbols are resolved once per signature for kstest with background = \"difexp\"", {
+  testthat::skip_if_not_installed("hypeR")
+  calls <- 0L
+  testthat::local_mocked_bindings(
+    lookupReferenceSymbols = function(conn_handler, assay_type, organism, feature_names) {
+      calls <<- calls + 1L
+      c(f1 = "A", f2 = "B", f3 = "C", f4 = "D", f5 = "E", f6 = "E")
     },
-    error = function(err) base::conditionMessage(err)
+    .package = "SigRepo"
   )
-  testthat::skip_if_not(
-    base::isTRUE(probe),
-    base::paste("MSigDB gene sets could not be downloaded:", probe)
+  difexp <- hyper_difexp_table()
+  difexp$gene_symbol <- NULL
+  sig <- make_hyper_sig(difexp = difexp)
+
+  res <- runToyHypeR(organism = "Homo sapiens", conn_handler = NULL, omic_signature = sig, genesets = hyper_genesets(),
+                           test = "kstest", background = "difexp", verbose = FALSE)
+  expect_equal(calls, 1L)
+  expect_equal(res$data[["sig_a | up"]]$info$Background, "5")
+  expect_equal(res$data[["sig_a | down"]]$info[["Symbol Source"]], "reference feature_name")
+})
+
+test_that("W2: query_names renames queries before hypeR runs", {
+  testthat::skip_if_not_installed("hypeR")
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", 
+    omic_signature = list(make_hyper_sig("first"), make_hyper_sig("second")), genesets = hyper_genesets(),
+    query_names = function(info) substr(info$group_label, 1, 1), verbose = FALSE
+  )
+  expect_equal(names(res$data), c("O", "Y", "O (2)", "Y (2)"))
+  expect_equal(res$data[["O (2)"]]$info[["SigRepo Signature Name"]], "second")
+
+  expect_error(
+    runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), query_names = "{label}", verbose = FALSE),
+    "'query_names' must be NULL or a function", fixed = TRUE
   )
+})
 
-  utils::data("LLFS_Aging_Gene_2023", package = "SigRepo", envir = environment())
+test_that("W11: hypeR's downstream functions accept runHypeR() results", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("igraph")
+  testthat::skip_if_not_installed("visNetwork")
+  testthat::skip_if_not_installed("reactable")
+  gs <- list(
+    SET_AB = c("A", "B", "X1", "X2"), SET_ABX = c("A", "B", "X1", "X3"), SET_CD = c("C", "D", "X3"),
+    SET_CDX = c("C", "D", "X4", "X5"), SET_E = c("E", "X4", "X5"), SET_AE = c("A", "E", "X6")
+  )
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = gs, background = 23467, verbose = FALSE)
 
-  hyp_res <- base::suppressWarnings(
-    SigRepo::runHypeR(
-      omic_signature = LLFS_Aging_Gene_2023,
-      msigdb_collection = "H",
-      method = "hypergeo",
-      plotting = FALSE,
-      quiet = TRUE,
-      verbose = FALSE
+  expect_no_error(hypeR::hyp_emap(res, top = 6, similarity_cutoff = 0.1))
+  expect_no_error(hypeR::hyp_dots(res, merge = TRUE))
+  expect_no_error(hypeR::hyp_show(res$data[[1]]))
+  expect_true(inherits(hypeR::rctbl_build(res), "shiny.tag"))
+
+  table_dir <- tempfile()
+  on.exit(unlink(table_dir, recursive = TRUE), add = TRUE)
+  hypeR::hyp_to_table(res, file_path = table_dir)
+  expect_setequal(list.files(table_dir), paste0(names(res$data), ".txt"))
+
+  nodes <- data.frame(label = names(gs), row.names = paste0("n", seq_along(gs)))
+  edges <- data.frame(from = c("n1", "n3"), to = c("n2", "n4"))
+  rg <- hypeR::rgsets$new(gs, nodes, edges, name = "toy", version = "v1", quiet = TRUE)
+  res_rg <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = rg, test = "kstest", verbose = FALSE)
+  expect_no_error(hypeR::hyp_hmap(res_rg, top = 6))
+  expect_no_error(hypeR::hyp_to_graph(res_rg$data[[1]]))
+})
+
+test_that("W11: hyp_to_rmd() renders a runHypeR() multihyp", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("rmarkdown")
+  testthat::skip_if_not(rmarkdown::pandoc_available())
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = make_hyper_sig(), genesets = hyper_genesets(), verbose = FALSE)
+  html <- tempfile(fileext = ".html")
+  on.exit(unlink(html), add = TRUE)
+
+  utils::capture.output(hypeR::hyp_to_rmd(res, file_path = html, title = "SigRepo hypeR"))
+  expect_true(file.exists(html))
+})
+
+# ---- W4: hypeR-native input ----
+
+test_that("W4: runHypeR(signature =) matches hypeR::hypeR() for a vector and a named list", {
+  testthat::skip_if_not_installed("hypeR")
+
+  single <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = c("A", "B", "C"), genesets = hyper_genesets(), verbose = FALSE)
+  expect_true(inherits(single, "hyp"))
+  expect_equal(single$data, hypeR::hypeR(c("A", "B", "C"), hyper_genesets())$data)
+  expect_equal(
+    unlist(single$info[SigRepo:::HYPER_PROVENANCE_KEYS], use.names = FALSE),
+    c("", "signature", "", "supplied", "", "", "", "", "number", "0", "0", "0", "", "run")
+  )
+
+  sigs <- list(first = c("A", "B"), second = c("C", "D", "E"))
+  listed <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sigs, genesets = hyper_genesets(), fdr_scope = "query", verbose = FALSE)
+  direct <- hypeR::hypeR(sigs, hyper_genesets())
+  expect_true(inherits(listed, "multihyp"))
+  expect_equal(names(listed$data), names(direct$data))
+  for (nm in names(sigs)) {
+    expect_equal(listed$data[[nm]]$data, direct$data[[nm]]$data)
+  }
+})
+
+test_that("W4: weighted native kstest matches hypeR, and power = 0 uses the ranked branch", {
+  testthat::skip_if_not_installed("hypeR")
+  weights <- c(A = 3, B = 2, E = -1, C = -2, D = -3)
+
+  weighted <- runToyHypeR(organism = "Homo sapiens", signature = weights, genesets = hyper_genesets(), test = "kstest", fdr_scope = "query", verbose = FALSE)
+  expect_equal(names(weighted$data), c("signature | up", "signature | down"))
+  expect_equal(weighted$data[["signature | up"]]$data, hypeR::hypeR(weights, hyper_genesets(), test = "kstest")$data)
+  expect_equal(weighted$data[["signature | down"]]$data, hypeR::hypeR(rev(-weights), hyper_genesets(), test = "kstest")$data)
+
+  ranked <- runToyHypeR(organism = "Homo sapiens", signature = weights, genesets = hyper_genesets(), test = "kstest", power = 0, fdr_scope = "query", verbose = FALSE)
+  expect_equal(ranked$data[["signature | up"]]$data, hypeR::hypeR(names(weights), hyper_genesets(), test = "kstest")$data)
+  expect_equal(ranked$data[["signature | down"]]$data, hypeR::hypeR(rev(names(weights)), hyper_genesets(), test = "kstest")$data)
+
+  # A character vector is a ranking as well: power = 0 uses it as given and reversed.
+  ranked_chr <- runToyHypeR(organism = "Homo sapiens", signature = names(weights), genesets = hyper_genesets(), test = "kstest", power = 0,
+                            fdr_scope = "query", verbose = FALSE)
+  expect_equal(ranked_chr$data[["signature | up"]]$data, ranked$data[["signature | up"]]$data)
+})
+
+test_that("W4: background = \"difexp\" is rejected for native input, also inside a background list", {
+  testthat::skip_if_not_installed("hypeR")
+  for (bg in list("difexp", list(a = "difexp"))) {
+    expect_error(
+      runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = list(a = c("A", "B")), genesets = hyper_genesets(), background = bg, verbose = FALSE),
+      "background = \"difexp\" needs SigRepo signatures", fixed = TRUE
     )
+  }
+})
+
+test_that("W4: getHypeRDifexp() then runHypeR(signature =) re-thresholds a signature", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+
+  difexp <- SigRepo::getHypeRDifexp(omic_signature = sig, verbose = FALSE)[[1]]
+  strict_up <- difexp$resolved_symbol[difexp$adj_p <= 0.01 & difexp$score > 0]
+  expect_equal(strict_up, "A")
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = list(strict_up = strict_up), genesets = hyper_genesets(),
+                           background = unique(difexp$resolved_symbol), verbose = FALSE)
+  expect_equal(res$data$strict_up$data, hypeR::hypeR("A", hyper_genesets(), background = c("A", "B", "C", "D", "E"))$data)
+})
+
+# ---- Per-signature backgrounds ----
+
+test_that("a background list gives each signature its own background, shared by its arms", {
+  testthat::skip_if_not_installed("hypeR")
+  first_bg <- c("A", "B", "C", "D", "X1", "X2", "X3")
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", 
+    omic_signature = list(first = make_hyper_sig("x"), second = make_hyper_sig("y", difexp = hyper_difexp_table())),
+    genesets = hyper_genesets(),
+    background = list(second = "difexp", first = first_bg),
+    fdr_scope = "query", verbose = FALSE
   )
 
-  expect_true("hyp" %in% class(hyp_res$result))
-  expect_true(base::grepl("H", hyp_res$result$info[["Genesets"]], fixed = TRUE))
+  info <- function(q, key) res$data[[q]]$info[[key]]
+  expect_equal(info("first | Old", "Background"), "7")
+  expect_equal(info("first | Young", "Background"), "7")
+  expect_equal(info("first | Old", "SigRepo Background Source"), "genes")
+  expect_equal(info("second | Old", "Background"), "5")
+  expect_equal(info("second | Young", "SigRepo Background Source"), "difexp")
+  expect_equal(res$data[["first | Old"]]$data, hypeR::hypeR(c("A", "B"), hyper_genesets(), background = first_bg)$data)
+})
+
+test_that("a background list can be keyed by signature ID and mixes numbers with gene vectors", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::local_mocked_bindings(
+    getSignature = function(conn_handler, signature_id = NULL, signature_name = NULL, verbose = TRUE) {
+      list(make_hyper_sig(paste0("db_", signature_id)))
+    },
+    .package = "SigRepo"
+  )
+
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", 
+    conn_handler = list(), signature_id = c(7, 8), genesets = hyper_genesets(), split = FALSE,
+    background = list("7" = 5000, db_8 = c("A", "B", "C", "D", "E")), verbose = FALSE
+  )
+  expect_equal(res$data$db_7$info$Background, "5000")
+  expect_equal(res$data$db_7$info[["SigRepo Background Source"]], "number")
+  expect_equal(res$data$db_8$info$Background, "5")
+})
+
+test_that("a background list must cover every signature and name only signatures", {
+  testthat::skip_if_not_installed("hypeR")
+  sigs <- list(first = make_hyper_sig("x"), second = make_hyper_sig("y"))
+  run <- function(bg) runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sigs, genesets = hyper_genesets(), background = bg, verbose = FALSE)
+
+  expect_error(run(list(first = 100)), "The background list has no entry for 'second'", fixed = TRUE)
+  expect_error(run(list(first = 100, second = 100, thrid = 100)), "background names 'thrid' match no signature label or ID", fixed = TRUE)
+  expect_error(run(list(first = 100, second = "Difexp")), "not for 'second'", fixed = TRUE)
+  expect_error(run(list(100, 200)), "A background list must name every element uniquely", fixed = TRUE)
+
+  # A skipped signature's entry is not an error.
+  bad <- make_hyper_sig("bad", signature = hyper_sig_table(symbols = FALSE))
+  expect_warning(
+    ok <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = list(first = make_hyper_sig("x"), bad = bad), genesets = hyper_genesets(),
+                            background = list(first = 100, bad = 200), split = FALSE, verbose = FALSE),
+    "Skipped 1 signature(s)", fixed = TRUE
+  )
+  expect_equal(ok$data$first$info$Background, "100")
+})
+
+test_that("a background list works with native input", {
+  testthat::skip_if_not_installed("hypeR")
+  res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", 
+    signature = list(a = c("A", "B"), b = c("C", "D")), genesets = hyper_genesets(),
+    background = list(a = 1000, b = 2000), verbose = FALSE
+  )
+  expect_equal(unname(vapply(res$data, function(h) h$info$Background, "")), c("1000", "2000"))
+})
+
+# ---- BS831 conventions: minimum query size, pooled FDR, default background ----
+
+test_that("hypergeometric queries with fewer than min_query_genes genes in the genesets are skipped", {
+  testthat::skip_if_not_installed("hypeR")
+  gs <- c(hyper_genesets(), list(SET_BIG = c("A", "B", "C", "D", "E", "F", "G")))
+  big <- make_hyper_sig("big", signature = data.frame(
+    probe_id = paste0("p", 1:5), feature_name = paste0("f", 1:5), score = 5:1,
+    group_label = factor(rep("Up", 5)), symbol = c("A", "B", "C", "D", "NOT_ANNOTATED")
+  ))
+  small <- make_hyper_sig("small")
+
+  expect_warning(
+    res <- SigRepo::runHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = list(big, small), genesets = gs, verbose = FALSE),
+    "Skipped 2 query(ies) with fewer than min_query_genes = 4 genes found in the genesets: 'small | Old' (2), 'small | Young' (2)",
+    fixed = TRUE
+  )
+  expect_equal(names(res$data), "big | Up")
+
+  expect_error(
+    suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = small, genesets = gs, verbose = FALSE)),
+    "No query had genesets left to test", fixed = TRUE
+  )
+  expect_no_warning(SigRepo::runHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = small, genesets = gs, min_query_genes = 2, verbose = FALSE))
+  expect_error(SigRepo::runHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = small, genesets = gs, min_query_genes = 0), "'min_query_genes' must be", fixed = TRUE)
+})
+
+test_that("min_query_genes does not apply to kstest", {
+  testthat::skip_if_not_installed("hypeR")
+  expect_no_warning(
+    SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_sig(difexp = hyper_difexp_table()), genesets = hyper_genesets(),
+                      test = "kstest", verbose = FALSE)
+  )
+})
+
+test_that("fdr_scope = \"run\" adjusts across every query; \"query\" matches hypeR per query", {
+  testthat::skip_if_not_installed("hypeR")
+  sigs <- list(first = c("A", "B", "X1", "X2"), second = c("C", "D", "X3", "E"))
+  gs <- hyper_genesets()
+
+  direct <- hypeR::hypeR(sigs, gs)
+  per_query <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sigs, genesets = gs, fdr_scope = "query", verbose = FALSE)
+  for (nm in names(sigs)) {
+    expect_equal(per_query$data[[nm]]$data, direct$data[[nm]]$data)
+  }
+
+  pooled <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sigs, genesets = gs, verbose = FALSE)
+  all_p <- c(direct$data$first$data$pval, direct$data$second$data$pval)
+  expected_fdr <- signif(p.adjust(all_p, method = "fdr"), 2)
+  expect_equal(c(pooled$data$first$data$fdr, pooled$data$second$data$fdr), expected_fdr)
+  expect_equal(pooled$data$first$data$pval, direct$data$first$data$pval)
+  expect_equal(pooled$data$first$info[["SigRepo FDR Scope"]], "run")
+})
+
+test_that("with fdr_scope = \"run\", pval and fdr filter on the pooled FDR and are recorded in info", {
+  testthat::skip_if_not_installed("hypeR")
+  sigs <- list(first = c("A", "B", "X1", "X2"), second = c("C", "D", "X3", "E"))
+
+  pooled_all <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sigs, genesets = hyper_genesets(), verbose = FALSE)
+  cutoff <- 0.01
+  filtered <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sigs, genesets = hyper_genesets(), fdr = cutoff, verbose = FALSE)
+  for (nm in names(sigs)) {
+    keep <- pooled_all$data[[nm]]$data$fdr <= cutoff
+    expect_equal(filtered$data[[nm]]$data, pooled_all$data[[nm]]$data[keep, , drop = FALSE])
+    expect_equal(filtered$data[[nm]]$info$FDR, "0.01")
+    expect_equal(filtered$data[[nm]]$args$fdr, cutoff)
+  }
+})
+
+test_that("a single query keeps hypeR's own FDR under either scope", {
+  testthat::skip_if_not_installed("hypeR")
+  run <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = c("A", "B", "C"), genesets = hyper_genesets(), fdr = 0.5, verbose = FALSE)
+  expect_equal(run$data, hypeR::hypeR(c("A", "B", "C"), hyper_genesets(), fdr = 0.5)$data)
+})
+
+test_that("the default background uses a complete difexp's genes, and 23467 silently without a difexp", {
+  testthat::skip_if_not_installed("hypeR")
+  sigs <- list(
+    with = make_hyper_sig("with", difexp = hyper_complete_difexp_table(), assay_type = "proteomics"),
+    without = make_hyper_sig("without")
+  )
+
+  expect_no_warning(res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sigs, genesets = hyper_genesets(), split = FALSE, verbose = FALSE))
+  expect_equal(res$data$with$info$Background, "9")
+  expect_equal(res$data$with$info[["SigRepo Background Source"]], "difexp")
+  expect_equal(res$data$without$info$Background, "23467")
+  expect_equal(res$data$without$info[["SigRepo Background Source"]], "difexp-fallback")
+
+  native <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = c("A", "B"), genesets = hyper_genesets(), verbose = FALSE)
+  expect_equal(native$info[["SigRepo Background Source"]], "number")
+
+  ks <- runToyHypeR(organism = "Homo sapiens", omic_signature = sigs$with, genesets = hyper_genesets(), test = "kstest", verbose = FALSE)
+  expect_equal(ks$data[[1]]$info[["SigRepo Background Source"]], "number")
+})
+
+test_that("the default background falls back to 23467, with a warning, for a difexp that looks filtered", {
+  testthat::skip_if_not_installed("hypeR")
+  small_transcriptome <- make_hyper_sig("small", difexp = hyper_complete_difexp_table())
+  near_signature <- make_hyper_sig("near", difexp = hyper_difexp_table(), assay_type = "proteomics")
+  filtered <- hyper_complete_difexp_table()
+  filtered$p_value <- 0.01
+  prefiltered <- make_hyper_sig("prefiltered", difexp = filtered, assay_type = "proteomics")
+
+  expect_equal(SigRepo:::hypeRDifexpTruncation(small_transcriptome), "10 rows, fewer than a transcriptome's 10000")
+  expect_equal(SigRepo:::hypeRDifexpTruncation(near_signature), "6 rows for a 4-feature signature")
+  expect_equal(SigRepo:::hypeRDifexpTruncation(prefiltered), "every p_value <= 0.05")
+  expect_null(SigRepo:::hypeRDifexpTruncation(make_hyper_sig(difexp = hyper_complete_difexp_table(), assay_type = "proteomics")))
+
+  expect_warning(
+    res <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = small_transcriptome, genesets = hyper_genesets(), split = FALSE, verbose = FALSE),
+    "Default background: the difexp looks filtered for 'small' (10 rows, fewer than a transcriptome's 10000)", fixed = TRUE
+  )
+  expect_equal(res$info$Background, "23467")
+  expect_equal(res$info[["SigRepo Background Source"]], "difexp-truncated")
+
+  forced <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = small_transcriptome, genesets = hyper_genesets(), split = FALSE,
+                        background = "difexp", verbose = FALSE)
+  expect_equal(forced$info$Background, "9")
+  expect_equal(forced$info[["SigRepo Background Source"]], "difexp")
+})
+
+test_that("a single categorical signature returns a multihyp for kstest, a hyp for split = FALSE", {
+  testthat::skip_if_not_installed("hypeR")
+  gs <- list(S1 = c("A", "C"), S2 = c("B", "D"), S3 = c("E", "F"))
+  sig <- make_hyper_categorical_sig()
+
+  ks <- runToyHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "kstest", verbose = FALSE)
+  expect_true(inherits(ks, "multihyp"))
+  expect_equal(names(ks$data), c("cat | red | up", "cat | red | down", "cat | white | up", "cat | white | down"))
+  expect_equal(ks$data[["cat | red | down"]]$info[["Group Label"]], "red")
+
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", omic_signature = sig, genesets = gs, split = FALSE, background = 23467, verbose = FALSE)
+  expect_true(inherits(hyper, "hyp"))
+})
+
+test_that("runHypeR does not offer hypeR's unimplemented absolute option", {
+  testthat::skip_if_not_installed("hypeR")
+  expect_false("absolute" %in% names(formals(SigRepo::runHypeR)))
+  expect_error(
+    runToyHypeR(organism = "Homo sapiens", test = "kstest", omic_signature = make_hyper_sig(difexp = hyper_difexp_table()),
+                genesets = hyper_genesets(), absolute = TRUE, verbose = FALSE),
+    "unused argument (absolute = TRUE)", fixed = TRUE
+  )
+  res <- runToyHypeR(organism = "Homo sapiens", test = "kstest", omic_signature = make_hyper_sig(difexp = hyper_difexp_table()),
+                     genesets = hyper_genesets(), verbose = FALSE)
+  expect_equal(res$data[[1]]$info[["Absolute"]], "FALSE")
+})
+
+test_that("kstest runs a single geneset, which hypeR itself cannot, and matches the multi-geneset result", {
+  testthat::skip_if_not_installed("hypeR")
+  stats <- hyper_fgsea_stats()
+  gs <- hyper_fgsea_genesets()
+  expect_error(hypeR::hypeR(stats, gs["TOP"], test = "kstest", plotting = FALSE, quiet = TRUE), "dim(X) must have a positive length", fixed = TRUE)
+
+  for (power in c(1, 0)) {
+    for (form in c("list", "gsets")) {
+      one <- if (form == "list") gs["TOP"] else hypeR::gsets$new(gs["TOP"], name = "H", version = "v1", quiet = TRUE)
+      single <- runToyHypeR(organism = "Homo sapiens", test = "kstest", signature = stats, genesets = one, power = power,
+                            fdr_scope = "query", verbose = FALSE)$data[["signature | up"]]
+      many <- runToyHypeR(organism = "Homo sapiens", test = "kstest", signature = stats, genesets = gs[c("TOP", "BOTTOM")], power = power,
+                          fdr_scope = "query", verbose = FALSE)$data[["signature | up"]]
+      expect_equal(single$data$label, "TOP")
+      top <- many$data[many$data$label == "TOP", ]
+      expect_equal(single$data[, c("score", "pval", "geneset", "signature", "overlap", "hits")],
+                   top[, c("score", "pval", "geneset", "signature", "overlap", "hits")], ignore_attr = TRUE)
+      # One test: the FDR is the p-value.
+      expect_equal(single$data$fdr, single$data$pval)
+      # The duplicate never shows up in the object.
+      expect_false(any(grepl("SigRepo duplicate", c(single$data$label, names(single$plots), names(single$args$genesets$genesets)), fixed = TRUE)))
+      expect_equal(names(single$args$genesets$genesets), "TOP")
+      if (form == "gsets") expect_equal(single$args$genesets$name, "H")
+      # Plots and curve data work on it.
+      expect_equal(SigRepo::hypeREnrichmentData(single, "TOP")$summary$n_hits, length(gs$TOP))
+      expect_equal(SigRepo::hypeREnrichmentData(single, "TOP")$summary$es, single$data$score, tolerance = 0.05)
+    }
+  }
+})
+
+test_that("kstest keeps a query whose zero-weight drops leave one geneset", {
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_zero_score_sig()
+  # S2 hits only B (score 0) and is dropped, leaving S1 alone.
+  res <- suppressWarnings(runToyHypeR(organism = "Homo sapiens", test = "kstest", omic_signature = sig,
+                                      genesets = list(S1 = c("A", "D"), S2 = "B"), verbose = FALSE))
+  for (side in c("zero | up", "zero | down")) {
+    expect_equal(res$data[[side]]$data$label, "S1")
+    expect_equal(res$data[[side]]$info[["SigRepo Genesets Dropped List"]], "S2")
+  }
+})
+
+test_that("a gene-vector background reduces kstest and fgsea rankings, not only hypergeometric gene lists", {
+  testthat::skip_if_not_installed("hypeR")
+  stats <- hyper_fgsea_stats()
+  gs <- hyper_fgsea_genesets()
+  bg <- names(stats)[-(1:4)]
+
+  expect_warning(
+    ks <- runToyHypeR(organism = "Homo sapiens", test = "kstest", signature = stats, genesets = gs, background = bg, verbose = FALSE),
+    "background: removed 8 query gene(s) not in the background gene vector from: 'signature | up' (4), 'signature | down' (4)", fixed = TRUE
+  )
+  expect_equal(names(ks$data[["signature | up"]]$args$signature), bg)
+  expect_equal(names(ks$data[["signature | down"]]$args$signature), rev(bg))
+  expect_equal(ks$data[["signature | up"]]$info[["SigRepo Query Genes Removed"]], "4")
+  direct <- hypeR::hypeR(stats[bg], gs, test = "kstest", background = bg, plotting = FALSE, quiet = TRUE)
+  expect_equal(ks$data[["signature | up"]]$data[, c("label", "score", "pval")], direct$data[, c("label", "score", "pval")], ignore_attr = TRUE)
+
+  testthat::skip_if_not_installed("fgsea")
+  expect_warning(
+    fg <- runToyHypeR(organism = "Homo sapiens", test = "fgsea", signature = stats, genesets = gs, background = bg, verbose = FALSE),
+    "background: removed 4 query gene(s)", fixed = TRUE
+  )
+  for (side in names(fg$data)) {
+    expect_equal(names(fg$data[[side]]$args$signature), bg)
+    expect_equal(fg$data[[side]]$info[["SigRepo Query Genes Removed"]], "4")
+  }
+  # A number leaves the ranking alone.
+  expect_no_warning(fg_all <- runToyHypeR(organism = "Homo sapiens", test = "fgsea", signature = stats, genesets = gs, background = 23467, verbose = FALSE))
+  expect_equal(fg_all$data[[1]]$info[["SigRepo Query Genes Removed"]], "0")
+
+  # A ranking with nothing left in the background is skipped; with none left the call errors.
+  expect_error(
+    suppressWarnings(runToyHypeR(organism = "Homo sapiens", test = "fgsea", signature = stats, genesets = gs, background = c("NOT_A_GENE", "ALSO_NOT_A_GENE"), verbose = FALSE)),
+    "No query had genes left to test", fixed = TRUE
+  )
 })
diff --git a/tests/testthat/test_hypeR_fgsea.R b/tests/testthat/test_hypeR_fgsea.R
new file mode 100644
index 00000000..fb984674
--- /dev/null
+++ b/tests/testthat/test_hypeR_fgsea.R
@@ -0,0 +1,307 @@
+# ---- Engine: runFgseaHyps() ----
+
+test_that("runFgseaHyps matches fgsea::fgseaMultilevel() with the same seed, split by ES sign", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  stats <- hyper_fgsea_stats()
+  gs <- hyper_fgsea_genesets()
+
+  run <- SigRepo:::runFgseaHyps(stats, gs, background = 23467, direction = "both", power = 1, seed = 1,
+                                fgsea_args = list(), quiet = TRUE)
+  set.seed(1)
+  direct <- as.data.frame(suppressWarnings(fgsea::fgseaMultilevel(gs, stats, sampleSize = 101, minSize = 1, maxSize = Inf, gseaParam = 1)))
+
+  expect_equal(names(run$hyps), c("up", "down"))
+  expect_equal(run$hyps$up$data$label, c("TOP", "TOP_MIX", "SPREAD"))
+  expect_equal(run$hyps$down$data$label, c("BOTTOM", "BOTTOM_MIX"))
+  ours <- rbind(run$hyps$up$data, run$hyps$down$data)
+  ref <- direct[match(ours$label, direct$pathway), ]
+  expect_identical(ours$pval, signif(ref$pval, 2))
+  expect_identical(ours$fdr, signif(ref$padj, 2))
+  expect_identical(ours$nes, ref$NES)
+  expect_identical(ours$es, ref$ES)
+  expect_identical(ours$le, vapply(ref$leadingEdge, paste, "", collapse = ","))
+  expect_identical(ours$hits, vapply(ref$leadingEdge, paste, "", collapse = " , "))
+  expect_equal(colnames(ours), c("label", "pval", "fdr", "lte", "es", "nes", "signature", "geneset", "overlap", "le", "hits"))
+  expect_true(all(run$hyps$up$data$es > 0))
+  expect_true(all(run$hyps$down$data$es < 0))
+})
+
+test_that("runFgseaHyps puts an ES = 0 pathway on neither side and does not list it as dropped", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  run <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "both", 1, 1, list(), TRUE)
+  expect_false("MIDDLE" %in% c(run$hyps$up$data$label, run$hyps$down$data$label))
+  expect_identical(run$dropped, character())
+})
+
+test_that("runFgseaHyps is reproducible with a seed and restores the caller's RNG state", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  run <- function(seed) SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "both", 1, seed, list(), TRUE)
+
+  set.seed(99)
+  before <- .Random.seed
+  first <- run(1)
+  expect_identical(.Random.seed, before)
+  second <- run(1)
+  expect_identical(first$hyps$up$data, second$hyps$up$data)
+  expect_identical(first$hyps$down$data, second$hyps$down$data)
+
+  set.seed(5)
+  before <- .Random.seed
+  run(NULL)
+  expect_false(identical(.Random.seed, before))
+})
+
+test_that("withHypeRSeed leaves no .Random.seed behind when the caller had none", {
+  had <- exists(".Random.seed", envir = globalenv(), inherits = FALSE)
+  saved <- if (had) get(".Random.seed", envir = globalenv()) else NULL
+  on.exit(if (had) assign(".Random.seed", saved, envir = globalenv()), add = TRUE)
+  if (had) rm(".Random.seed", envir = globalenv())
+
+  value <- SigRepo:::withHypeRSeed(1, stats::runif(1))
+  expect_false(exists(".Random.seed", envir = globalenv(), inherits = FALSE))
+  set.seed(1)
+  expect_equal(value, stats::runif(1))
+})
+
+test_that("runFgseaHyps keeps one side for direction up or down", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  up <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "up", 1, 1, list(), TRUE)
+  down <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "down", 1, 1, list(), TRUE)
+  expect_equal(names(up$hyps), "up")
+  expect_equal(names(down$hyps), "down")
+  expect_equal(down$hyps$down$data$label, c("BOTTOM", "BOTTOM_MIX"))
+})
+
+test_that("runFgseaHyps reduces genesets to a gene-vector background and records dropped pathways", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  bg <- sprintf("G%02d", 1:30)
+  reduced <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), bg, "up", 1, 1, list(), TRUE)
+  expect_equal(reduced$hyps$up$data$geneset[reduced$hyps$up$data$label == "SPREAD"], 4L)
+  expect_equal(reduced$hyps$up$info$Background, "30")
+  numbers <- lapply(c(100, 23467), function(n) SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), n, "up", 1, 1, list(), TRUE))
+  expect_identical(numbers[[1]]$hyps$up$data, numbers[[2]]$hyps$up$data)
+
+  sized <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "both", 1, 1, list(minSize = 6), TRUE)
+  expect_equal(sized$dropped, "SPREAD")
+  expect_equal(sized$hyps$up$info[["fgsea Args"]], "minSize=6")
+  expect_equal(sized$hyps$up$info[["Min Size"]], "6")
+})
+
+test_that("runFgseaHyps returns 0-row hyps instead of erroring when fgsea drops every pathway", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  run <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "both", 1, 1, list(minSize = 50), TRUE)
+  cols <- c("label", "pval", "fdr", "lte", "es", "nes", "signature", "geneset", "overlap", "le", "hits")
+  expect_equal(names(run$hyps), c("up", "down"))
+  expect_equal(nrow(run$hyps$up$data), 0L)
+  expect_equal(nrow(run$hyps$down$data), 0L)
+  expect_equal(colnames(run$hyps$up$data), cols)
+  expect_equal(colnames(run$hyps$down$data), cols)
+  expect_equal(run$dropped, names(hyper_fgsea_genesets()))
+})
+
+test_that("runFgseaHyps keeps a 0-row hyp for the empty side rather than dropping it", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  gs <- hyper_fgsea_genesets()[c("TOP", "TOP_MIX")]
+  run <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), gs, 23467, "both", 1, 1, list(), TRUE)
+  expect_equal(nrow(run$hyps$down$data), 0L)
+  expect_equal(nrow(run$hyps$up$data), 2L)
+})
+
+test_that("runFgseaHyps hyps carry hypeR's info keys first, then fgsea's, and gsets in args", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  run <- SigRepo:::runFgseaHyps(hyper_fgsea_stats(), hyper_fgsea_genesets(), 23467, "up", 1, 1, list(), TRUE)
+  info <- run$hyps$up$info
+  expect_equal(names(info), c(
+    "hypeR", "Signature Head", "Signature Size", "Signature Type", "Genesets", "Background", "P-Value", "FDR",
+    "Test", "Power", "Absolute", "fgsea", "Sample Size", "Min Size", "Max Size", "Seed", "fgsea Args"
+  ))
+  expect_true(all(vapply(info, is.character, TRUE)))
+  expect_equal(info$Test, "fgsea")
+  expect_equal(info$Seed, "1")
+  expect_true(inherits(run$hyps$up$args$genesets, "gsets"))
+  expect_length(run$hyps$up$plots, 0L)
+})
+
+# ---- Rankings: prepareHypeRSignatures(test = "fgsea") ----
+
+test_that("fgsea uses the kstest up ranking, one per signature, and always tests both directions", {
+  sig <- make_hyper_fgsea_sig()
+  ks <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)
+
+  both <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "fgsea", verbose = FALSE)
+  expect_equal(names(both$signatures), "fg")
+  expect_equal(both$signatures[["fg"]], ks$signatures[["fg | up"]])
+  expect_equal(both$info$direction, "both")
+})
+
+test_that("fgsea ranks a categorical signature once per category", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_categorical_sig(), test = "fgsea", verbose = FALSE)
+  expect_equal(names(prepared$signatures), c("cat | red", "cat | white"))
+  expect_equal(prepared$info$direction, c("both", "both"))
+})
+
+test_that("fgsea native input must be named numeric, tests both directions, and rejects ks_source", {
+  expect_error(
+    SigRepo::prepareHypeRSignatures(signature = c("A", "B"), test = "fgsea", verbose = FALSE),
+    "test = \"fgsea\" needs scores: pass a named numeric vector", fixed = TRUE
+  )
+  native <- SigRepo::prepareHypeRSignatures(signature = hyper_fgsea_stats(), test = "fgsea", verbose = FALSE)
+  expect_equal(native$info$direction, "both")
+  expect_error(
+    SigRepo::prepareHypeRSignatures(signature = hyper_fgsea_stats(), test = "fgsea", ks_source = "signature", verbose = FALSE),
+    "'ks_source' applies to SigRepo signatures", fixed = TRUE
+  )
+})
+
+# ---- runHypeR(test = "fgsea") ----
+
+test_that("runHypeR fgsea defaults to both sides and matches runFgseaHyps with provenance appended", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  sig <- make_hyper_fgsea_sig()
+  ranking <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "fgsea", verbose = FALSE)$signatures[[1]]
+
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = hyper_fgsea_genesets(), test = "fgsea",
+                           fdr_scope = "query", verbose = FALSE)
+  engine <- SigRepo:::runFgseaHyps(ranking, hyper_fgsea_genesets(), 23467, "both", 1, 1, list(), TRUE)
+
+  expect_true(inherits(res, "multihyp"))
+  expect_equal(names(res$data), c("fg | up", "fg | down"))
+  expect_equal(res$data[["fg | up"]]$data, engine$hyps$up$data)
+  expect_equal(res$data[["fg | down"]]$data, engine$hyps$down$data)
+
+  info <- res$data[["fg | down"]]$info
+  expect_equal(utils::tail(names(info), length(SigRepo:::HYPER_PROVENANCE_KEYS)), SigRepo:::HYPER_PROVENANCE_KEYS)
+  expect_equal(
+    unlist(info[c("Test", "SigRepo Direction", "SigRepo Ranked Table", "SigRepo Score Column", "SigRepo Split",
+                  "SigRepo Background Source", "SigRepo FDR Scope")], use.names = FALSE),
+    c("fgsea", "down", "difexp", "score", "", "number", "query")
+  )
+})
+
+test_that("runHypeR fgsea always returns both sides, as a multihyp, and has no direction argument", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  expect_false("direction" %in% names(formals(SigRepo::runHypeR)))
+  single <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(),
+                              test = "fgsea", verbose = FALSE)
+  expect_true(inherits(single, "multihyp"))
+  expect_equal(names(single$data), c("fg | up", "fg | down"))
+  expect_true(all(single$data[["fg | up"]]$data$es > 0))
+  expect_true(all(single$data[["fg | down"]]$data$es < 0))
+  expect_error(
+    SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(),
+                      test = "fgsea", direction = "up", verbose = FALSE),
+    "unused argument (direction = \"up\")", fixed = TRUE
+  )
+
+  native <- SigRepo::runHypeR(organism = "Homo sapiens", signature = hyper_fgsea_stats(), genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+  expect_true(inherits(native, "multihyp"))
+  expect_equal(names(native$data), c("signature | up", "signature | down"))
+  expect_equal(native$data[[1]]$info[["SigRepo Ranked Table"]], "")
+})
+
+test_that("runHypeR fgsea pools FDR across sides and rankings by default and filters on it", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  sigs <- list(a = make_hyper_fgsea_sig("a"), b = make_hyper_fgsea_sig("b"))
+  gs <- hyper_fgsea_genesets()
+
+  per_query <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sigs, genesets = gs, test = "fgsea", fdr_scope = "query", verbose = FALSE)
+  pooled <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sigs, genesets = gs, test = "fgsea", verbose = FALSE)
+
+  all_p <- unlist(lapply(per_query$data, function(h) h$data$pval), use.names = FALSE)
+  expect_equal(unlist(lapply(pooled$data, function(h) h$data$fdr), use.names = FALSE), signif(p.adjust(all_p, method = "fdr"), 2))
+  expect_equal(pooled$data[["a | up"]]$info[["SigRepo FDR Scope"]], "run")
+
+  filtered <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sigs, genesets = gs, test = "fgsea", fdr = 0.001, verbose = FALSE)
+  for (nm in names(pooled$data)) {
+    keep <- pooled$data[[nm]]$data$fdr <= 0.001
+    expect_equal(filtered$data[[nm]]$data, pooled$data[[nm]]$data[keep, , drop = FALSE])
+    expect_equal(filtered$data[[nm]]$info$FDR, "0.001")
+  }
+
+  query_filtered <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sigs, genesets = gs, test = "fgsea", fdr_scope = "query",
+                                      fdr = 0.001, verbose = FALSE)
+  expect_true(all(query_filtered$data[["b | down"]]$data$fdr <= 0.001))
+  expect_equal(query_filtered$data[["b | down"]]$args$fdr, 0.001)
+})
+
+test_that("runHypeR fgsea returns 0-row hyps instead of erroring when fgsea drops every pathway", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(), test = "fgsea",
+                           fgsea_args = list(minSize = 50), verbose = FALSE)
+  expect_true(inherits(res, "multihyp"))
+  expect_true(all(vapply(res$data, function(h) nrow(h$data) == 0L, logical(1))))
+})
+
+test_that("runHypeR fgsea runs each category of a categorical signature", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  gs <- list(S1 = c("A", "C"), S2 = c("B", "D"), S3 = c("E", "F"))
+  res <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_categorical_sig(), genesets = gs, test = "fgsea", verbose = FALSE))
+  expect_equal(names(res$data), c("cat | red | up", "cat | red | down", "cat | white | up", "cat | white | down"))
+  expect_equal(res$data[["cat | white | down"]]$info[["Group Label"]], "white")
+})
+
+test_that("runHypeR fgsea rejects absolute, bad seeds and reserved fgsea_args, and warns on plotting", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  run <- function(...) SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(),
+                                         test = "fgsea", verbose = FALSE, ...)
+
+  expect_error(run(absolute = TRUE), "unused argument (absolute = TRUE)", fixed = TRUE)
+  for (bad in list("1", c(1, 2), NA_real_, Inf)) {
+    expect_error(run(seed = bad), "'seed' must be NULL or a single number", fixed = TRUE)
+  }
+  expect_error(run(fgsea_args = list(15)), "'fgsea_args' must be a named list", fixed = TRUE)
+  expect_error(run(fgsea_args = list(gseaParam = 2, stats = 1)), "'fgsea_args' cannot set 'gseaParam', 'stats'", fixed = TRUE)
+  expect_error(run(fgsea_args = list(scoreType = "pos")), "'fgsea_args' cannot set 'scoreType'", fixed = TRUE)
+  expect_warning(run(plotting = TRUE), "fgsea makes no per-geneset plots; plotting is ignored.", fixed = TRUE)
+})
+
+test_that("runHypeR fgsea re-emits fgsea's warnings once with an fgsea: prefix", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  tied <- hyper_fgsea_stats()
+  tied[1:10] <- 2
+  warnings <- testthat::capture_warnings(
+    SigRepo::runHypeR(organism = "Homo sapiens", signature = list(x = tied, y = tied), genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+  )
+  ties <- grep("^fgsea: There are ties in the preranked stats", warnings, value = TRUE)
+  expect_length(ties, 1L)
+})
+
+test_that("runHypeR fgsea results work with hypeR's tooling and hypeRToExcel()", {
+  testthat::skip_if_not_installed("fgsea")
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("reactable")
+  testthat::skip_if_not_installed("visNetwork")
+  testthat::skip_if_not_installed("openxlsx")
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+
+  expect_no_error(hypeR::hyp_dots(res, merge = TRUE))
+  expect_true(inherits(hypeR::rctbl_build(res), "shiny.tag"))
+  expect_no_error(hypeR::hyp_emap(res))
+  xlsx <- tempfile(fileext = ".xlsx")
+  on.exit(unlink(xlsx), add = TRUE)
+  index <- SigRepo::hypeRToExcel(res, file_path = xlsx)
+  expect_equal(openxlsx::getSheetNames(xlsx), c("index", "fg | up", "fg | down", "versioning"))
+  expect_equal(index$direction, c("up", "down"))
+
+  testthat::skip_if_not_installed("rmarkdown")
+  testthat::skip_if_not(rmarkdown::pandoc_available())
+  html <- tempfile(fileext = ".html")
+  on.exit(unlink(html), add = TRUE)
+  utils::capture.output(hypeR::hyp_to_rmd(res, file_path = html, title = "fgsea"))
+  expect_true(file.exists(html))
+})
diff --git a/tests/testthat/test_hypeR_genesets.R b/tests/testthat/test_hypeR_genesets.R
new file mode 100644
index 00000000..686f76b4
--- /dev/null
+++ b/tests/testthat/test_hypeR_genesets.R
@@ -0,0 +1,110 @@
+test_that("msigdbDbSpecies maps species and collection to the MSigDB database", {
+  expect_equal(SigRepo:::msigdbDbSpecies("Homo sapiens", "C2"), "HS")
+  expect_equal(SigRepo:::msigdbDbSpecies("Homo Sapiens", "H"), "HS")
+  expect_equal(SigRepo:::msigdbDbSpecies("Mus musculus", "MH"), "MM")
+  expect_equal(SigRepo:::msigdbDbSpecies("Mus musculus", "M8"), "MM")
+  expect_equal(SigRepo:::msigdbDbSpecies("Mus musculus", "C2"), "HS")
+  expect_equal(SigRepo:::msigdbDbSpecies("Mus musculus", "H"), "HS")
+  expect_equal(SigRepo:::msigdbDbSpecies("Rattus norvegicus", "H"), "HS")
+})
+
+test_that("getHypeRGenesets passes a named list, gsets and rgsets through unchanged", {
+  testthat::skip_if_not_installed("hypeR")
+
+  gs <- list(SET_1 = c("A", "B"), SET_2 = c("C"))
+  expect_identical(SigRepo::getHypeRGenesets(gs), gs)
+
+  gsets_obj <- hypeR::gsets$new(gs, name = "custom", version = "v1", quiet = TRUE)
+  expect_identical(SigRepo::getHypeRGenesets(gsets_obj), gsets_obj)
+
+  rgsets_like <- structure(list(), class = c("rgsets", "R6"))
+  expect_identical(SigRepo::getHypeRGenesets(rgsets_like), rgsets_like)
+})
+
+test_that("getHypeRGenesets rejects anything that is not msigdb or a genesets object", {
+  form_error <- "'genesets' must be \"msigdb\""
+  expect_error(SigRepo::getHypeRGenesets("mygeneset"), form_error, fixed = TRUE)
+  expect_error(SigRepo::getHypeRGenesets(c("msigdb", "H")), form_error, fixed = TRUE)
+  expect_error(SigRepo::getHypeRGenesets(NULL), form_error, fixed = TRUE)
+  expect_error(SigRepo::getHypeRGenesets(list(c("A", "B"))), form_error, fixed = TRUE)
+  expect_error(SigRepo::getHypeRGenesets(list()), form_error, fixed = TRUE)
+})
+
+test_that("getHypeRGenesets requires msigdb_collection for msigdb and forbids msigdb_* otherwise", {
+  expect_error(
+    SigRepo::getHypeRGenesets("msigdb"),
+    "genesets = \"msigdb\" requires 'msigdb_collection'", fixed = TRUE
+  )
+  expect_error(
+    SigRepo::getHypeRGenesets(list(S = "A"), msigdb_collection = "H", msigdb_species = "Mus musculus"),
+    "msigdb_species, msigdb_collection only apply when genesets = \"msigdb\"", fixed = TRUE
+  )
+})
+
+test_that("getHypeRGenesets forwards msigdb arguments with a human default species", {
+  testthat::local_mocked_bindings(
+    fetchMsigdbGsets = function(species, collection, subcollection = NULL, clean = FALSE) {
+      list(species = species, collection = collection, subcollection = subcollection, clean = clean)
+    },
+    .package = "SigRepo"
+  )
+
+  out <- SigRepo::getHypeRGenesets("msigdb", msigdb_collection = "C2", msigdb_subcollection = "CP:REACTOME")
+  expect_equal(out, list(species = "Homo sapiens", collection = "C2", subcollection = "CP:REACTOME", clean = FALSE))
+})
+
+test_that("fetchMsigdbGsets builds a named, versioned gsets with the right db_species", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("msigdbr")
+
+  seen <- NULL
+  testthat::local_mocked_bindings(
+    callMsigdbr = function(args) {
+      seen <<- args
+      data.frame(
+        gs_name = c("SET_1", "SET_1", "SET_1", "SET_2"),
+        gene_symbol = c("Abc1", "Abc1", "Def2", NA),
+        stringsAsFactors = FALSE
+      )
+    },
+    .package = "SigRepo"
+  )
+
+  gs <- SigRepo:::fetchMsigdbGsets("Mus musculus", "C2", "CP:REACTOME")
+
+  expect_equal(seen, list(species = "Mus musculus", db_species = "HS", collection = "C2", subcollection = "CP:REACTOME"))
+  expect_true(methods::is(gs, "gsets"))
+  expect_equal(gs$name, "C2.CP:REACTOME")
+  expect_equal(gs$version, paste0("v", as.character(utils::packageVersion("msigdbr"))))
+  expect_equal(gs$genesets, list(SET_1 = c("Abc1", "Def2")))
+})
+
+test_that("fetchMsigdbGsets errors clearly when MSigDB returns nothing", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("msigdbr")
+
+  testthat::local_mocked_bindings(
+    callMsigdbr = function(args) data.frame(gs_name = character(), gene_symbol = character()),
+    .package = "SigRepo"
+  )
+
+  expect_error(
+    SigRepo:::fetchMsigdbGsets("Homo sapiens", "NOPE"),
+    "msigdbr::msigdbr_collections()", fixed = TRUE
+  )
+})
+
+test_that("fetchMsigdbGsets retrieves Hallmark from MSigDB", {
+  testthat::skip_on_cran()
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("msigdbr")
+
+  gs <- tryCatch(
+    SigRepo:::fetchMsigdbGsets("Homo sapiens", "H"),
+    error = function(e) testthat::skip(paste("MSigDB unavailable:", conditionMessage(e)))
+  )
+
+  expect_true(methods::is(gs, "gsets"))
+  expect_equal(gs$name, "H")
+  expect_true("HALLMARK_APOPTOSIS" %in% names(gs$genesets))
+})
diff --git a/tests/testthat/test_hypeR_plots.R b/tests/testthat/test_hypeR_plots.R
new file mode 100644
index 00000000..f546e928
--- /dev/null
+++ b/tests/testthat/test_hypeR_plots.R
@@ -0,0 +1,501 @@
+# ---- hypeRDotData() ----
+
+test_that("hypeRDotData keeps the top genesets by their best value across queries", {
+  testthat::skip_if_not_installed("hypeR")
+  q1 <- make_dot_hyp(c("S1", "S2", "S3"), c(0.01, 0.5, 0.2))
+  q2 <- make_dot_hyp(c("S2", "S4"), c(0.001, 0.3))
+  dots <- SigRepo::hypeRDotData(hypeR::multihyp$new(data = list(q1 = q1, q2 = q2)), top = 2)
+
+  expect_equal(dots$query, c("q1", "q1", "q2"))
+  expect_equal(dots$label, c("S2", "S1", "S2"))
+  expect_equal(levels(dots$label_abrv), c("S1", "S2"))
+  expect_equal(levels(dots$query_label), c("S1", "S2"))
+  expect_equal(dots$significance, -log10(c(0.5, 0.01, 0.001)))
+  expect_equal(dots$size, c(20, 10, 10))
+})
+
+test_that("hypeRDotData applies the cutoffs per query and floors zero values", {
+  testthat::skip_if_not_installed("hypeR")
+  q1 <- make_dot_hyp(c("S1", "S2"), c(0, 0.5))
+  q2 <- make_dot_hyp(c("S1", "S3"), c(0.02, 0.04))
+  dots <- SigRepo::hypeRDotData(hypeR::multihyp$new(data = list(q1 = q1, q2 = q2)), fdr = 0.1)
+
+  expect_equal(dots$label, c("S1", "S1", "S3"))
+  expect_equal(dots$significance[1], -log10(0.02 / 10))
+  expect_equal(levels(dots$query_label), c("S1", "S2"))
+
+  all_zero <- SigRepo::hypeRDotData(make_dot_hyp("S1", 0))
+  expect_equal(all_zero$significance, 300)
+})
+
+test_that("hypeRDotData takes score from nes (fgsea) or score (kstest), and size from size_by", {
+  testthat::skip_if_not_installed("hypeR")
+  fgsea <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), test = "fgsea", extra = list(nes = c(2.1, -1.5)))
+  kstest <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), test = "kstest", extra = list(score = c(0.6, -0.4)))
+  hyper <- make_dot_hyp(c("A", "B"), c(0.01, 0.02))
+
+  expect_equal(SigRepo::hypeRDotData(fgsea)$score, c(2.1, -1.5))
+  expect_equal(SigRepo::hypeRDotData(kstest)$score, c(0.6, -0.4))
+  # A kstest down query ranks the negated scores, so its score is flipped back
+  # onto the original ranking: enrichment at the bottom plots as negative.
+  kstest_down <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), test = "kstest", extra = list(score = c(0.6, -0.4)),
+                              info = list(`SigRepo Direction` = "down"))
+  expect_equal(SigRepo::hypeRDotData(kstest_down)$score, c(-0.6, 0.4))
+  expect_true(all(is.na(SigRepo::hypeRDotData(hyper)$score)))
+  expect_equal(SigRepo::hypeRDotData(hyper, size_by = "overlap")$size, c(1, 2))
+  expect_true(all(is.na(SigRepo::hypeRDotData(hyper, size_by = "none")$size)))
+  expect_equal(SigRepo::hypeRDotData(hyper, val = "pval")$significance, -log10(c(0.005, 0.01)))
+})
+
+test_that("hypeRDotData returns a 0-row frame with the same columns when nothing passes", {
+  testthat::skip_if_not_installed("hypeR")
+  dots <- SigRepo::hypeRDotData(make_dot_hyp(c("A", "B"), c(0.5, 0.6)), fdr = 0.05)
+  expect_equal(nrow(dots), 0L)
+  expect_equal(colnames(dots), c("query", "query_label", "signature_code", "query_group", "signature_name",
+                                 "group_label", "direction", "test",
+                                 "label", "label_abrv", "pval", "fdr", "significance", "score", "size"))
+})
+
+test_that("hypeRDotData truncates long geneset labels and keeps them unique", {
+  testthat::skip_if_not_installed("hypeR")
+  labels <- c("HALLMARK_VERY_LONG_SUFFIX_ONE", "HALLMARK_VERY_LONG_SUFFIX_TWO", "SHORT")
+  dots <- SigRepo::hypeRDotData(make_dot_hyp(labels, c(0.01, 0.02, 0.03)), abrv = 10)
+  expect_equal(as.character(dots$label_abrv), c("HALLMARK_V...", "HALLMARK_V... (2)", "SHORT"))
+})
+
+test_that("hypeRDotData labels queries by signature code and group", {
+  testthat::skip_if_not_installed("hypeR")
+  hyp <- function(signature, group = NULL, direction = NULL, fdr = 0.01) {
+    make_dot_hyp("A", fdr, info = c(list("SigRepo Signature Name" = signature), if (!is.null(group)) list("Group Label" = group),
+                                   if (!is.null(direction)) list("SigRepo Direction" = direction)))
+  }
+  bi <- hypeR::multihyp$new(data = list(
+    "sigA | Old" = hyp("sigA", "Old"), "sigA | Young" = hyp("sigA", "Young"),
+    "sigB | Old" = hyp("sigB", "Old"), "sigB | Young" = hyp("sigB", "Young")
+  ))
+  dots <- SigRepo::hypeRDotData(bi)
+  expect_equal(levels(dots$query_label), c("S1 | Old", "S1 | Young", "S2 | Old", "S2 | Young"))
+  expect_equal(dots$signature_code, c("S1", "S1", "S2", "S2"))
+  expect_equal(dots$query_group, c("Old", "Young", "Old", "Young"))
+  expect_equal(SigRepo::hypeRSignatureKey(bi), data.frame(signature_code = c("S1", "S2"), signature_name = c("sigA", "sigB")))
+  expect_equal(levels(SigRepo::hypeRDotData(bi, signature_key = FALSE)$query_label), names(bi$data))
+
+  categorical <- hypeR::multihyp$new(data = list(x = hyp("sigC", "Subtype_A", "up"), y = hyp("sigD", NULL, "down")))
+  expect_equal(levels(SigRepo::hypeRDotData(categorical)$query_label), c("S1 | Subtype_A up", "S2 | down"))
+
+  one_each <- hypeR::multihyp$new(data = list("sigA" = hyp("sigA"), "sigB" = hyp("sigB")))
+  expect_equal(levels(SigRepo::hypeRDotData(one_each)$query_label), c("S1", "S2"))
+
+  unnamed <- hypeR::multihyp$new(data = list(q1 = make_dot_hyp("A", 0.01), q2 = make_dot_hyp("A", 0.01)))
+  expect_equal(SigRepo::hypeRSignatureKey(unnamed)$signature_name, c("q1", "q2"))
+})
+
+test_that("hypeRDotData labels one signature by group, full name, a function, or errors on bad labels", {
+  testthat::skip_if_not_installed("hypeR")
+  info <- list("SigRepo Signature Name" = "LLFS_Aging_Gene_2023", "Group Label" = "Group1", "SigRepo Direction" = "")
+  single <- make_dot_hyp("A", 0.01, info = info)
+  expect_equal(SigRepo::hypeRDotData(single)$query, "LLFS_Aging_Gene_2023 | Group1")
+  expect_equal(as.character(SigRepo::hypeRDotData(single)$query_label), "Group1")
+  expect_equal(as.character(SigRepo::hypeRDotData(single, signature_key = FALSE)$query_label), "LLFS_Aging_Gene_2023 | Group1")
+  expect_equal(as.character(SigRepo::hypeRDotData(make_dot_hyp("A", 0.01, info = info[1]))$query_label), "LLFS_Aging_Gene_2023")
+
+  pair <- hypeR::multihyp$new(data = list(a = make_dot_hyp("A", 0.01, info = info), b = make_dot_hyp("A", 0.02, info = info)))
+  by_group <- SigRepo::hypeRDotData(pair, query_labels = function(info) info$group_label)
+  expect_equal(levels(by_group$query_label), c("Group1", "Group1 (2)"))
+
+  expect_error(SigRepo::hypeRDotData(pair, query_labels = "x"), "'query_labels' must be NULL or a function", fixed = TRUE)
+  expect_error(SigRepo::hypeRDotData(pair, query_labels = function(info) "one"),
+               "'query_labels' must return a character vector of 2 non-empty label(s)", fixed = TRUE)
+  expect_error(SigRepo::hypeRDotData(list()), "'hyp_obj' must be a hypeR hyp or multihyp object", fixed = TRUE)
+  expect_error(SigRepo::hypeRDotData(single, top = 0), "'top' must be a single number of at least 1", fixed = TRUE)
+})
+
+test_that("hypeRDotData errors with a named message when the size_by column is missing", {
+  testthat::skip_if_not_installed("hypeR")
+  no_geneset <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), extra = list(geneset = NULL))
+  expect_error(SigRepo::hypeRDotData(no_geneset, size_by = "geneset"),
+               "size_by = \"geneset\" needs a 'geneset' column in the results", fixed = TRUE)
+
+  no_overlap <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), extra = list(overlap = NULL))
+  expect_error(SigRepo::hypeRDotData(no_overlap, size_by = "overlap"),
+               "size_by = \"overlap\" needs a 'overlap' column in the results", fixed = TRUE)
+
+  # "none" needs neither column, so it is unaffected.
+  expect_equal(nrow(SigRepo::hypeRDotData(no_geneset, size_by = "none")), 2L)
+})
+
+test_that("hypeRDotData breaks shared top-N ties by best pval, then label", {
+  testthat::skip_if_not_installed("hypeR")
+  # Same fdr for both genesets ("S_A" sorts first alphabetically), but "S_Z"
+  # has the smaller pval and so must be the one kept at top = 1.
+  tied <- make_dot_hyp(c("S_A", "S_Z"), c(0.05, 0.05), extra = list(pval = c(0.02, 0.01)))
+  dots <- SigRepo::hypeRDotData(tied, top = 1)
+  expect_equal(dots$label, "S_Z")
+})
+
+# ---- hypeREnrichmentData() ----
+
+test_that("hypeREnrichmentData ES matches every fgsea and kstest score in the results", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("fgsea")
+  sig <- make_hyper_fgsea_sig()
+  gs <- hyper_fgsea_genesets()
+  results <- list(
+    fgsea = list(res = SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "fgsea", verbose = FALSE), column = "es"),
+    kstest = list(res = suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "kstest", verbose = FALSE)), column = "score"),
+    ranked = list(res = suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = sig, genesets = gs, test = "kstest", power = 0, verbose = FALSE)), column = "score")
+  )
+
+  for (case in names(results)) {
+    res <- results[[case]]$res
+    hyps <- if (inherits(res, "multihyp")) res$data else list(query = res)
+    for (query in names(hyps)) {
+      table <- hyps[[query]]$data
+      for (k in seq_len(nrow(table))) {
+        enrichment <- SigRepo::hypeREnrichmentData(res, table$label[k], query = if (inherits(res, "multihyp")) query else NULL)
+        expect_equal(signif(enrichment$summary$es, 2), signif(table[[results[[case]]$column]][k], 2),
+                     info = paste(case, query, table$label[k]))
+      }
+    }
+  }
+})
+
+test_that("hypeREnrichmentData reproduces the tie rules: first extremum for kstest, 0 for fgsea", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("fgsea")
+  run <- function(...) suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", signature = hyper_tie_stats(), genesets = hyper_tie_genesets(), verbose = FALSE, ...))
+
+  weighted <- run(test = "kstest")
+  expect_equal(SigRepo::hypeREnrichmentData(weighted, "TIE", query = "signature | up")$summary$es, -0.5)
+  up <- weighted$data[["signature | up"]]$data
+  expect_equal(up$score[up$label == "TIE"], -0.5)
+
+  ranked <- run(test = "kstest", power = 0)
+  tie_ranked <- SigRepo::hypeREnrichmentData(ranked, "TIE", query = "signature | up")
+  ranked_up <- ranked$data[["signature | up"]]$data
+  expect_equal(signif(tie_ranked$summary$es, 2), ranked_up$score[ranked_up$label == "TIE"])
+
+  gsea <- run(test = "fgsea")
+  tie_gsea <- SigRepo::hypeREnrichmentData(gsea, "TIE", query = "signature | up")
+  expect_equal(tie_gsea$summary$es, 0)
+  expect_true(is.na(tie_gsea$summary$es_position))
+  expect_true(is.na(tie_gsea$summary$pval))
+  expect_false(any(tie_gsea$ticks$leading_edge))
+})
+
+test_that("hypeREnrichmentData curve, ticks and leading edge follow the ranking", {
+  testthat::skip_if_not_installed("hypeR")
+  res <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", signature = hyper_tie_stats(), genesets = hyper_tie_genesets(),
+                                            test = "kstest", verbose = FALSE))
+  top <- SigRepo::hypeREnrichmentData(res, "TOP", query = "signature | up")
+  expect_equal(nrow(top$curve), 11L)
+  expect_equal(top$ticks$position, 1:3)
+  expect_equal(top$ticks$gene, c("T01", "T02", "T03"))
+  expect_equal(top$ticks$score, c(5, 4, 3))
+  expect_true(all(top$ticks$leading_edge))
+  expect_equal(top$summary$es_position, 3L)
+
+  bottom <- SigRepo::hypeREnrichmentData(res, "BOT", query = "signature | up")
+  expect_true(bottom$summary$es < 0)
+  expect_true(all(bottom$ticks$position[bottom$ticks$leading_edge] >= bottom$summary$es_position))
+  expect_equal(bottom$summary$leading_edge_genes, c("T09", "T10", "T11"))
+})
+
+test_that("hypeREnrichmentData weighted kstest running_score matches hand-derived values on the TIE fixture", {
+  testthat::skip_if_not_installed("hypeR")
+  res <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", signature = hyper_tie_stats(), genesets = hyper_tie_genesets(),
+                                            test = "kstest", verbose = FALSE))
+  tie <- SigRepo::hypeREnrichmentData(res, "TIE", query = "signature | up")
+  # By hand: TIE hits only T06 (score 0.5, position 6) of 11. p_hit is 0 until
+  # position 6 then 1 (all its weight is there); p_mis is cumsum(!hit)/10.
+  # running = p_hit - p_mis.
+  expect_equal(tie$curve$running_score, c(-0.1, -0.2, -0.3, -0.4, -0.5, 0.5, 0.4, 0.3, 0.2, 0.1, 0))
+})
+
+test_that("hypeREnrichmentData errors for absolute = TRUE kstest results", {
+  testthat::skip_if_not_installed("hypeR")
+  # runHypeR() no longer offers absolute, but a hypeR result made with it can still reach this function.
+  res <- hypeR::hypeR(hyper_tie_stats(), hyper_tie_genesets(), test = "kstest", absolute = TRUE, plotting = FALSE, quiet = TRUE)
+  expect_error(
+    SigRepo::hypeREnrichmentData(res, "TIE"),
+    "absolute = TRUE kstest results have no running-sum curve; hypeR scores them as max - min", fixed = TRUE
+  )
+})
+
+test_that("hypeREnrichmentData ticks and leading edge use fgsea's own (sorted) ranking, not signature order", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("fgsea")
+  set.seed(42)
+  stats <- hyper_fgsea_stats()
+  shuffled <- stats[sample(base::length(stats))]
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", signature = shuffled, genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+
+  hyps <- if (inherits(res, "multihyp")) res$data else list(query = res)
+  sorted_names <- base::names(base::sort(shuffled, decreasing = TRUE))
+  for (query in base::names(hyps)) {
+    table <- hyps[[query]]$data
+    for (k in base::seq_len(base::nrow(table))) {
+      geneset <- table$label[k]
+      enrichment <- SigRepo::hypeREnrichmentData(res, geneset, query = if (inherits(res, "multihyp")) query else NULL)
+
+      expected_le <- table$le[k]
+      expected_le <- if (base::nzchar(expected_le)) base::strsplit(expected_le, ",", fixed = TRUE)[[1]] else base::character()
+      expect_equal(sort(enrichment$summary$leading_edge_genes), sort(expected_le), info = paste(query, geneset))
+
+      ticks <- enrichment$ticks
+      expect_equal(ticks$gene, sorted_names[ticks$position], info = paste(query, geneset))
+    }
+  }
+})
+
+test_that("hypeREnrichmentData errors on hypergeometric results, bad queries and unusable genesets", {
+  testthat::skip_if_not_installed("hypeR")
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = list(a = c("A", "B"), b = c("C", "D")), genesets = hyper_genesets(), verbose = FALSE)
+  expect_error(SigRepo::hypeREnrichmentData(hyper, "SET_AB", query = "a"), "needs kstest or fgsea results", fixed = TRUE)
+
+  gs <- c(hyper_tie_genesets(), list(ABSENT = c("ZZ1", "ZZ2")))
+  ks <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", signature = list(x = hyper_tie_stats(), y = hyper_tie_stats()), genesets = gs,
+                                           test = "kstest", verbose = FALSE))
+  expect_error(SigRepo::hypeREnrichmentData(ks, "TOP"), "'query' is required for a result with 4 queries: 'x | up', 'x | down', 'y | up', 'y | down'", fixed = TRUE)
+  expect_error(SigRepo::hypeREnrichmentData(ks, "TOP", query = "z"), "'query' must be one of: 'x | up', 'x | down', 'y | up', 'y | down'", fixed = TRUE)
+  expect_error(SigRepo::hypeREnrichmentData(ks, "NOPE", query = "x | up"), "Geneset 'NOPE' is not in this result's genesets", fixed = TRUE)
+  expect_error(SigRepo::hypeREnrichmentData(ks, "ABSENT", query = "x | up"), "'ABSENT' has no genes in this ranking", fixed = TRUE)
+})
+
+# ---- plotHypeRDots() ----
+
+test_that("plotHypeRDots draws one column per query, including a one-query multihyp", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  one <- hypeR::multihyp$new(data = list(only = make_dot_hyp(c("A", "B", "C"), c(0.001, 0.01, 0.2))))
+  plot <- SigRepo::plotHypeRDots(one)
+  built <- ggplot2::ggplot_build(plot)
+
+  expect_equal(nrow(built$data[[1]]), 3L)
+  expect_equal(built$layout$panel_params[[1]]$y$get_labels(), c("C", "B", "A"))
+  expect_equal(built$layout$panel_params[[1]]$x$get_labels(), "")
+  expect_equal(plot$labels$subtitle, "only")
+  expect_equal(rlang::as_label(plot$layers[[1]]$mapping$colour), "significance")
+  expect_equal(plot$scales$get_scales("colour")$name, "-log10(FDR)")
+  expect_equal(plot$scales$get_scales("colour")$get_transformation()$name, "identity")
+  expect_equal(plot$scales$get_scales("size")$name, "Geneset size")
+})
+
+test_that("plotHypeRDots colours by score for ranked tests and rejects it for hypergeometric", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  fgsea <- make_dot_hyp(c("A", "B"), c(0.01, 0.02), test = "fgsea", extra = list(nes = c(2, -1)))
+  plot <- SigRepo::plotHypeRDots(fgsea, color_by = "score", size_by = "none")
+  expect_equal(plot$scales$get_scales("colour")$name, "NES")
+  expect_null(plot$scales$get_scales("size"))
+  expect_equal(SigRepo::plotHypeRDots(fgsea, val = "pval")$scales$get_scales("colour")$name, "-log10(p)")
+
+  kstest <- make_dot_hyp("A", 0.01, test = "kstest", extra = list(score = 0.5))
+  expect_equal(SigRepo::plotHypeRDots(kstest, color_by = "score")$scales$get_scales("colour")$name, "Score")
+  expect_error(SigRepo::plotHypeRDots(make_dot_hyp("A", 0.01), color_by = "score"),
+               "color_by = \"score\" needs kstest or fgsea results", fixed = TRUE)
+})
+
+test_that("plotHypeRDots shows an empty-state plot and angles all but one signature's group labels", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  empty <- SigRepo::plotHypeRDots(make_dot_hyp("A", 0.5), fdr = 0.05)
+  expect_equal(ggplot2::ggplot_build(empty)$data[[1]]$label, "No genesets pass the cutoffs")
+
+  many <- hypeR::multihyp$new(data = stats::setNames(lapply(1:5, function(i) make_dot_hyp("A", 0.01)), paste0("q", 1:5)))
+  expect_equal(SigRepo::plotHypeRDots(many)$theme$axis.text.x$angle, 45)
+  expect_null(SigRepo::plotHypeRDots(hypeR::multihyp$new(data = list(q1 = make_dot_hyp("A", 0.01))))$theme$axis.text.x$angle)
+  expect_null(SigRepo::plotHypeRDots(make_dot_hyp("A", 0.01))$theme$axis.text.x$angle)
+  expect_equal(SigRepo::plotHypeRDots(make_dot_hyp("A", 0.01), signature_key = FALSE)$theme$axis.text.x$angle, 45)
+  expect_equal(SigRepo::plotHypeRDots(many)$theme$legend.justification, "top")
+})
+
+test_that("plots are titled with the test unless a title is given", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  expect_equal(SigRepo::plotHypeRDots(make_dot_hyp("A", 0.01))$labels$title, "Hypergeometric test")
+  kstest <- make_dot_hyp("A", 0.01, test = "kstest", extra = list(score = 0.5))
+  expect_equal(SigRepo::plotHypeRDots(kstest)$labels$title, "KS test")
+  fgsea <- make_dot_hyp("A", 0.01, test = "fgsea", extra = list(nes = 1.5))
+  expect_equal(SigRepo::plotHypeRDots(fgsea)$labels$title, "GSEA (fgsea)")
+  expect_equal(SigRepo::plotHypeRDots(fgsea, title = "custom")$labels$title, "custom")
+  expect_equal(SigRepo::plotHypeRDots(make_dot_hyp("A", 0.5), fdr = 0.05)$labels$title, "Hypergeometric test")
+})
+
+test_that("plotHypeRDots widens the left margin for query labels longer than the geneset labels", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  left_margin <- function(plot) as.numeric(plot$theme$plot.margin)[4]
+  long_query <- hypeR::multihyp$new(data = list(Aging_Hs_PeripheralBlood_LLFS_Aging_MontiLab_Old = make_dot_hyp("A", 0.01)))
+  expect_gt(left_margin(SigRepo::plotHypeRDots(long_query, signature_key = FALSE)), 5.5)
+  expect_equal(left_margin(SigRepo::plotHypeRDots(long_query)), 5.5)
+  short_query <- hypeR::multihyp$new(data = list(q = make_dot_hyp("HALLMARK_INTERFERON_GAMMA_RESPONSE", 0.01)))
+  expect_equal(left_margin(SigRepo::plotHypeRDots(short_query, signature_key = FALSE)), 5.5)
+})
+
+test_that("plotHypeRDots groups several signatures under their codes with a key, and names one signature in the subtitle", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  hyp <- function(signature, group, fdr = 0.01) {
+    make_dot_hyp(c("A", "B"), c(fdr, fdr), info = list("SigRepo Signature Name" = signature, "Group Label" = group))
+  }
+  bi <- hypeR::multihyp$new(data = list(
+    "sigA | Old" = hyp("sigA", "Old"), "sigA | Young" = hyp("sigA", "Young", fdr = 0.9),
+    "sigB | Old" = hyp("sigB", "Old"), "sigB | Young" = hyp("sigB", "Young")
+  ))
+  plot <- SigRepo::plotHypeRDots(bi, fdr = 0.05)
+  expect_s3_class(plot$facet, "FacetGrid")
+  expect_equal(plot$labels$caption, "S1 = sigA\nS2 = sigB")
+  expect_null(plot$labels$subtitle)
+  built <- ggplot2::ggplot_build(plot)
+  expect_equal(nrow(built$layout$layout), 2L)
+  # sigA | Young passes nothing but keeps its column in S1's panel.
+  expect_equal(built$layout$panel_params[[1]]$x$get_labels(), c("Old", "Young"))
+  expect_equal(built$layout$panel_params[[2]]$x$get_labels(), c("Old", "Young"))
+  expect_equal(plot$theme$axis.text.x$angle, 45)
+
+  one <- SigRepo::plotHypeRDots(hypeR::multihyp$new(data = bi$data[1:2]))
+  expect_equal(one$labels$subtitle, "sigA")
+  expect_null(one$labels$caption)
+  expect_false(inherits(one$facet, "FacetGrid"))
+  expect_equal(ggplot2::ggplot_build(one)$layout$panel_params[[1]]$x$get_labels(), c("Old", "Young"))
+  expect_null(one$theme$axis.text.x$angle)
+  categories <- stats::setNames(lapply(paste0("Subtype_", LETTERS[1:3]), function(g) hyp("sigC", g)), paste0("Subtype_", LETTERS[1:3]))
+  categories <- c(categories, stats::setNames(lapply(paste0("Subtype_", LETTERS[1:3]), function(g) hyp("sigC", g)), paste0("x", 1:3)))
+  expect_equal(SigRepo::plotHypeRDots(hypeR::multihyp$new(data = categories))$theme$axis.text.x$angle, 45)
+
+  off <- SigRepo::plotHypeRDots(bi, signature_key = FALSE)
+  expect_false(inherits(off$facet, "FacetGrid"))
+  expect_null(off$labels$caption)
+  expect_equal(ggplot2::ggplot_build(off)$layout$panel_params[[1]]$x$get_labels(), names(bi$data))
+})
+
+# ---- plotHypeREnrichment() ----
+
+test_that("fgsea enrichment data and plots take the ranking name and use the side holding the geneset", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  testthat::skip_if_not_installed("fgsea")
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+
+  top <- SigRepo::hypeREnrichmentData(res, "TOP", query = "fg")
+  expect_equal(top$summary$query, "fg | up")
+  expect_equal(top$summary$ranking, "fg")
+  expect_equal(top, SigRepo::hypeREnrichmentData(res, "TOP", query = "fg | up"))
+
+  bottom <- SigRepo::hypeREnrichmentData(res, "BOTTOM", query = "fg")
+  expect_equal(bottom$summary$query, "fg | down")
+  expect_true(bottom$summary$nes < 0)
+  expect_equal(SigRepo::hypeREnrichmentData(res, "BOTTOM", query = "fg | down")$summary$ranking, "fg")
+
+  plot <- SigRepo::plotHypeREnrichment(res, "BOTTOM", query = "fg")
+  expect_match(plot$labels$subtitle, "^BOTTOM\nfg\nES = -1, NES = -[0-9.]+, p = .+, FDR = .+$")
+  expect_error(SigRepo::hypeREnrichmentData(res, "TOP", query = "nope"), "'query' must be one of", fixed = TRUE)
+})
+
+
+test_that("plotHypeREnrichment draws the running score, hits and ES for fgsea", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  testthat::skip_if_not_installed("fgsea")
+  res <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(), test = "fgsea", verbose = FALSE)
+  plot <- SigRepo::plotHypeREnrichment(res, "TOP", query = "fg | up")
+
+  geoms <- unname(vapply(plot$layers, function(layer) class(layer$geom)[1], ""))
+  expect_equal(geoms, c("GeomHline", "GeomLine", "GeomSegment", "GeomVline"))
+  expect_equal(plot$labels$title, "GSEA (fgsea)")
+  expect_match(plot$labels$subtitle, "^TOP\nfg\nES = 1, NES = [0-9.]+, p = .+, FDR = .+$")
+  expect_equal(plot$labels$x, "Rank in ranking")
+  expect_no_error(ggplot2::ggplot_build(plot))
+
+  filtered <- SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(), test = "fgsea",
+                                fdr = 1e-12, verbose = FALSE)
+  expect_match(SigRepo::plotHypeREnrichment(filtered, "TOP", query = "fg | up")$labels$subtitle, "not in the result table", fixed = TRUE)
+  expect_match(SigRepo::plotHypeREnrichment(filtered, "TOP", query = "fg")$labels$subtitle, "^TOP\nfg\nES = 1, not in the result table$")
+
+  tie <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", signature = hyper_tie_stats(), genesets = hyper_tie_genesets(), test = "fgsea", verbose = FALSE))
+  tie_geoms <- unname(vapply(SigRepo::plotHypeREnrichment(tie, "TIE", query = "signature | up")$layers, function(layer) class(layer$geom)[1], ""))
+  expect_false("GeomVline" %in% tie_geoms)
+})
+
+test_that("plotHypeREnrichment labels a kstest down ranking and draws a Venn for hypergeometric", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("ggplot2")
+  ks <- suppressWarnings(SigRepo::runHypeR(organism = "Homo sapiens", omic_signature = make_hyper_fgsea_sig(), genesets = hyper_fgsea_genesets(),
+                                           test = "kstest", verbose = FALSE))
+  ks_down <- SigRepo::plotHypeREnrichment(ks, "BOTTOM", query = "fg | down")
+  expect_equal(ks_down$labels$x, "Rank in ranking (negated scores)")
+  # A kstest down query is its own (negated) ranking, so it keeps its side.
+  expect_match(ks_down$labels$subtitle, "^BOTTOM\nfg \\| down\n")
+  expect_error(SigRepo::plotHypeREnrichment(ks, "BOTTOM", query = "fg"), "'query' must be one of", fixed = TRUE)
+
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = list(a = c("A", "B", "X1"), b = c("C", "D")), genesets = hyper_genesets(), verbose = FALSE)
+  venn <- SigRepo::plotHypeREnrichment(hyper, "SET_AB", query = "a", title = "custom")
+  expect_equal(unname(vapply(venn$layers, function(layer) class(layer$geom)[1], ""))[1], "GeomCircle")
+  expect_equal(venn$labels$subtitle, sprintf("SET_AB\na\noverlap = 3, p = %s, FDR = %s",
+                                            format(signif(hyper$data$a$data$pval[hyper$data$a$data$label == "SET_AB"], 2)),
+                                            format(signif(hyper$data$a$data$fdr[hyper$data$a$data$label == "SET_AB"], 2))))
+})
+
+# ---- plotHypeRMap() ----
+
+test_that("plotHypeRMap returns hypeR's enrichment map when geneset pairs share genes", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("visNetwork")
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = list(a = sprintf("G%02d", 1:12), b = sprintf("G%02d", 29:40)),
+                       genesets = hyper_fgsea_genesets(), verbose = FALSE)
+
+  map <- SigRepo::plotHypeRMap(hyper, query = "a")
+  expect_true(inherits(map, "visNetwork"))
+  expect_equal(map$x$main$text, "Hypergeometric test")
+  expect_equal(map$x$submain$text, "a")
+  expect_equal(SigRepo::plotHypeRMap(hyper, query = "a", title = "custom")$x$main$text, "custom")
+  both <- SigRepo::plotHypeRMap(hyper)
+  expect_equal(names(both), c("a", "b"))
+  expect_true(all(vapply(both, inherits, TRUE, "visNetwork")))
+})
+
+test_that("plotHypeRMap returns NULL with a warning when hypeR would fail", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("visNetwork")
+  disjoint <- list(A = c("X1", "X2", "X3"), B = c("Y1", "Y2", "Y3"), C = c("Z1", "Z2", "Z3"))
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = c("X1", "Y1", "Z1", "Q"), genesets = disjoint, verbose = FALSE)
+
+  expect_warning(
+    no_edges <- SigRepo::plotHypeRMap(hyper),
+    "No geneset pair in 'signature' reaches similarity_cutoff = 0.2; lower it to draw a map.", fixed = TRUE
+  )
+  expect_null(no_edges)
+  expect_warning(
+    no_rows <- SigRepo::plotHypeRMap(hyper, fdr = 1e-12),
+    "No genesets pass the cutoffs for 'signature'.", fixed = TRUE
+  )
+  expect_null(no_rows)
+})
+
+test_that("plotHypeRMap warns distinctly when top leaves only one geneset", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("visNetwork")
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sprintf("G%02d", 1:12), genesets = hyper_fgsea_genesets(), verbose = FALSE)
+
+  expect_warning(
+    one <- SigRepo::plotHypeRMap(hyper, top = 1),
+    "Only one geneset passes the cutoffs for 'signature'; a map needs at least two.", fixed = TRUE
+  )
+  expect_null(one)
+})
+
+test_that("plotHypeRMap hierarchy maps need rgsets genesets", {
+  testthat::skip_if_not_installed("hypeR")
+  testthat::skip_if_not_installed("visNetwork")
+  testthat::skip_if_not_installed("igraph")
+  gs <- hyper_fgsea_genesets()
+  hyper <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sprintf("G%02d", 1:12), genesets = gs, verbose = FALSE)
+  expect_error(SigRepo::plotHypeRMap(hyper, type = "hmap"), "type = \"hmap\" needs rgsets genesets", fixed = TRUE)
+
+  nodes <- data.frame(label = names(gs), row.names = paste0("n", seq_along(gs)))
+  edges <- data.frame(from = c("n1", "n3"), to = c("n2", "n4"))
+  rg <- hypeR::rgsets$new(gs, nodes, edges, name = "toy", version = "v1", quiet = TRUE)
+  hierarchical <- runToyHypeR(organism = "Homo sapiens", test = "hypergeometric", signature = sprintf("G%02d", 1:12), genesets = rg, verbose = FALSE)
+  expect_true(inherits(SigRepo::plotHypeRMap(hierarchical, type = "hmap"), "visNetwork"))
+})
diff --git a/tests/testthat/test_hypeR_signatures.R b/tests/testthat/test_hypeR_signatures.R
new file mode 100644
index 00000000..cb3b6ec9
--- /dev/null
+++ b/tests/testthat/test_hypeR_signatures.R
@@ -0,0 +1,455 @@
+test_that("hypeRSymbolColumn picks the first populated symbol column", {
+  tbl <- data.frame(gene_symbol = c(NA, ""), symbol = c("A", "B"), stringsAsFactors = FALSE)
+  expect_equal(SigRepo:::hypeRSymbolColumn(tbl), "symbol")
+  expect_null(SigRepo:::hypeRSymbolColumn(data.frame(feature_name = "f1")))
+  expect_null(SigRepo:::hypeRSymbolColumn(NULL))
+})
+
+test_that("lookupReferenceSymbols returns nothing without a connection", {
+  expect_identical(
+    SigRepo:::lookupReferenceSymbols(NULL, "transcriptomics", "Homo sapiens", c("f1", "f2")),
+    character()
+  )
+})
+
+test_that("hypergeometric splits by group_label using the signature's own symbols", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), c("sig_a | Old", "sig_a | Young"))
+  expect_equal(prepared$signatures[["sig_a | Old"]], c("A", "B"))
+  expect_equal(prepared$signatures[["sig_a | Young"]], c("C", "D"))
+  expect_equal(prepared$info$group_label, c("Old", "Young"))
+  expect_equal(prepared$info$symbol_source, c("signature$symbol", "signature$symbol"))
+  expect_equal(prepared$info$n_features, c(2L, 2L))
+  expect_equal(nrow(prepared$skipped), 0L)
+})
+
+test_that("split = FALSE gives one hypergeometric vector per signature", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), split = FALSE, verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), "sig_a")
+  expect_equal(prepared$signatures[["sig_a"]], c("A", "B", "C", "D"))
+  expect_true(is.na(prepared$info$group_label))
+})
+
+test_that("a signature without group_label gives one vector named after the signature", {
+  tbl <- hyper_sig_table()
+  tbl$group_label <- NULL
+  sig <- make_hyper_sig(signature = tbl, type = "uni-directional")
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = sig, verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), "sig_a")
+})
+
+test_that("hypergeometric falls back to difexp symbols joined on probe_id", {
+  sig <- make_hyper_sig(signature = hyper_sig_table(symbols = FALSE), difexp = hyper_difexp_table())
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = sig, verbose = FALSE)
+
+  expect_equal(prepared$signatures[["sig_a | Old"]], c("A", "B"))
+  expect_equal(prepared$info$symbol_source[1], "difexp$gene_symbol via probe_id")
+})
+
+test_that("hypergeometric falls back to the reference table by feature_name and organism", {
+  seen <- NULL
+  testthat::local_mocked_bindings(
+    lookupReferenceSymbols = function(conn_handler, assay_type, organism, feature_names) {
+      seen <<- list(assay_type = assay_type, organism = organism, feature_names = feature_names)
+      c(F1 = "A", F2 = "B", F3 = "C")
+    },
+    .package = "SigRepo"
+  )
+  sig <- make_hyper_sig(signature = hyper_sig_table(symbols = FALSE))
+
+  prepared <- SigRepo::prepareHypeRSignatures(conn_handler = list(), omic_signature = sig, verbose = FALSE)
+
+  expect_equal(seen$assay_type, "transcriptomics")
+  expect_equal(seen$organism, "Homo sapiens")
+  expect_equal(seen$feature_names, c("f1", "f2", "f3", "f4"))
+  expect_equal(prepared$signatures[["sig_a | Old"]], c("A", "B"))
+  expect_equal(prepared$signatures[["sig_a | Young"]], "C")
+  expect_equal(prepared$info$n_dropped, c(0L, 1L))
+  expect_equal(prepared$info$symbol_source[1], "reference feature_name")
+})
+
+test_that("probe_id is never used as a symbol: no symbols and no connection means skipped", {
+  sig <- make_hyper_sig(signature = hyper_sig_table(symbols = FALSE))
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = sig, verbose = FALSE)
+
+  expect_length(prepared$signatures, 0L)
+  expect_equal(prepared$skipped$signature, "sig_a")
+  expect_equal(prepared$skipped$reason, "no_gene_symbols")
+})
+
+test_that("kstest ranks the full difexp, collapsing duplicate symbols by max |score|", {
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), c("sig_a | up", "sig_a | down"))
+  expect_equal(prepared$signatures[["sig_a | up"]], c(A = 3, B = 2, E = -1, C = -2, D = -3))
+  expect_equal(prepared$info$symbol_source, rep("difexp$gene_symbol", 2))
+  expect_true(all(is.na(prepared$info$group_label)))
+})
+
+test_that("kstest skips signatures without difexp or without the score column", {
+  no_difexp <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), test = "kstest", verbose = FALSE)
+  expect_equal(no_difexp$skipped$reason, "no_difexp")
+
+  no_score <- SigRepo::prepareHypeRSignatures(
+    omic_signature = make_hyper_sig(difexp = hyper_difexp_table()),
+    test = "kstest", score_col = "logFC", verbose = FALSE
+  )
+  expect_equal(no_score$skipped$reason, "missing_score_col")
+  expect_match(no_score$skipped$message, "logFC", fixed = TRUE)
+})
+
+test_that("labels come from supplied list names, then signature_name, with (2) for duplicates", {
+  named <- SigRepo::prepareHypeRSignatures(
+    omic_signature = list(first = make_hyper_sig("x"), second = make_hyper_sig("y")),
+    split = FALSE, verbose = FALSE
+  )
+  expect_equal(names(named$signatures), c("first", "second"))
+
+  dupes <- SigRepo::prepareHypeRSignatures(
+    omic_signature = list(make_hyper_sig("dup"), make_hyper_sig("dup"), make_hyper_sig("dup")),
+    split = FALSE, verbose = FALSE
+  )
+  expect_equal(names(dupes$signatures), c("dup", "dup (2)", "dup (3)"))
+})
+
+test_that("signature ids are recorded when signatures are fetched by id", {
+  testthat::local_mocked_bindings(
+    getSignature = function(conn_handler, signature_id = NULL, signature_name = NULL, verbose = TRUE) {
+      list(make_hyper_sig("db_sig"))
+    },
+    .package = "SigRepo"
+  )
+
+  inputs <- SigRepo:::collectHypeRSignatures(
+    conn_handler = list(), signature_id = 101, signature_name = NULL,
+    omic_signature = NULL, verbose = FALSE
+  )
+
+  expect_equal(inputs$ids, "101")
+  expect_equal(inputs$labels, "db_sig")
+})
+
+test_that("prepareHypeRSignatures rejects the removed test aliases", {
+  expect_error(
+    SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), test = "gsea", verbose = FALSE),
+    "should be one of"
+  )
+})
+
+# ---- Task 3c regressions (stress-test bugs B2-B5) ----
+
+test_that("B2: query names are unique even when a label collides with another signature's group suffix", {
+  a <- make_hyper_sig("X", signature = data.frame(
+    probe_id = c("p1", "p2"), feature_name = c("f1", "f2"), score = c(2, -2),
+    group_label = factor(c("Up", "Down")), symbol = c("TP53", "MYC")
+  ))
+  b <- make_hyper_sig("X | Up", signature = data.frame(
+    probe_id = "p1", feature_name = "f1", score = 1, group_label = factor(NA), symbol = "EGFR"
+  ), type = "uni-directional")
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = list(a, b), verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), c("X | Down", "X | Up", "X | Up (2)"))
+  expect_identical(prepared$info$query, names(prepared$signatures))
+  expect_equal(prepared$info$signature_name, c("X", "X", "X | Up"))
+  expect_equal(prepared$signatures[["X | Up (2)"]], "EGFR")
+})
+
+test_that("B3: the probe_id join uses (probe_id, feature_name) so a repeated probe_id keeps its own symbol", {
+  d <- data.frame(probe_id = c("p1", "p1"), feature_name = c("f1", "f2"), gene_symbol = c("GENE_A", "GENE_B"),
+                  score = c(3, 2.9), p_value = .01, adj_p = .05, group_label = factor(c("Up", "Up")))
+  s <- data.frame(probe_id = "p1", feature_name = "f2", score = 2.9, group_label = factor("Up"))
+
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig("dup", s, d), verbose = FALSE)
+
+  expect_equal(prepared$signatures[[1]], "GENE_B")
+  expect_equal(prepared$info$symbol_source, "difexp$gene_symbol via probe_id")
+})
+
+test_that("B3: a non-unique probe_id without feature_name on both sides skips the probe_id join", {
+  meta <- list(assay_type = "transcriptomics", organism = "Homo sapiens")
+  difexp_no_fn <- data.frame(probe_id = c("p1", "p1", "p2"), gene_symbol = c("GENE_A", "GENE_B", "GENE_C"))
+
+  # Neither table has feature_name: nothing else to try, so no symbols.
+  neither <- SigRepo:::resolveSignatureSymbols(
+    list(metadata = meta, signature = data.frame(probe_id = c("p1", "p2")), difexp = difexp_no_fn),
+    "signature"
+  )
+  expect_true(all(is.na(neither$symbols)))
+  expect_true(is.na(neither$source))
+
+  # Only the signature has feature_name: fall through to the reference lookup.
+  testthat::local_mocked_bindings(
+    lookupReferenceSymbols = function(conn_handler, assay_type, organism, feature_names) c(f1 = "REF_1", f2 = "REF_2"),
+    .package = "SigRepo"
+  )
+  sig_only <- SigRepo:::resolveSignatureSymbols(
+    list(metadata = meta, signature = data.frame(probe_id = c("p1", "p2"), feature_name = c("f1", "f2")),
+         difexp = difexp_no_fn),
+    "signature", conn_handler = list()
+  )
+  expect_equal(sig_only$symbols, c("REF_1", "REF_2"))
+  expect_equal(sig_only$source, "reference feature_name")
+
+  # A unique probe_id without feature_name still joins on probe_id alone.
+  unique_probe <- SigRepo:::resolveSignatureSymbols(
+    list(metadata = meta, signature = data.frame(probe_id = c("p2", "p1")),
+         difexp = data.frame(probe_id = c("p1", "p2"), gene_symbol = c("GENE_A", "GENE_C"))),
+    "signature"
+  )
+  expect_equal(unique_probe$symbols, c("GENE_C", "GENE_A"))
+  expect_equal(unique_probe$source, "difexp$gene_symbol via probe_id")
+})
+
+test_that("B4: kstest collapse keeps the positive value on an opposite-sign |score| tie, whatever the row order", {
+  d <- data.frame(probe_id = paste0("p", 1:3), feature_name = paste0("f", 1:3), gene_symbol = c("TP53", "TP53", "MYC"),
+                  score = c(2, -2, 1), p_value = .01, adj_p = .05, group_label = factor(c("Up", "Down", "Up")))
+  s <- data.frame(probe_id = "p3", feature_name = "f3", score = 1, group_label = factor("Up"))
+  f <- function(dd) {
+    SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig("t", s, dd), test = "kstest",
+                                    verbose = FALSE)$signatures[[1]][["TP53"]]
+  }
+
+  expect_equal(c(f(d), f(d[c(2, 1, 3), ])), c(2, 2))
+})
+
+test_that("B5/E09: prepareHypeRSignatures rejects a split that is not TRUE or FALSE", {
+  for (bad in list("yes", NA, c(TRUE, FALSE), 1)) {
+    expect_error(
+      SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), split = bad, verbose = FALSE),
+      "'split' must be TRUE or FALSE", fixed = TRUE
+    )
+  }
+})
+
+test_that("B5/E10: omic_signature together with signature_id or signature_name is an error", {
+  expect_error(
+    SigRepo:::collectHypeRSignatures(conn_handler = list(), signature_id = "1", signature_name = NULL,
+                                     omic_signature = make_hyper_sig(), verbose = FALSE),
+    "Supply either 'omic_signature' or 'signature_id'/'signature_name', not both", fixed = TRUE
+  )
+  expect_error(
+    SigRepo::prepareHypeRSignatures(conn_handler = list(), signature_name = "x",
+                                    omic_signature = make_hyper_sig(), verbose = FALSE),
+    "Supply either 'omic_signature' or 'signature_id'/'signature_name', not both", fixed = TRUE
+  )
+  # Empty ids/names are not a conflict.
+  expect_no_error(
+    SigRepo::prepareHypeRSignatures(signature_id = c("", NA), signature_name = character(),
+                                    omic_signature = make_hyper_sig(), verbose = FALSE)
+  )
+})
+
+# ---- Evaluation fixes (W1, W2, W5) ----
+
+test_that("kstest always builds an up query and a down query on the negated scores", {
+  sig <- make_hyper_sig(difexp = hyper_difexp_table())
+
+  expect_false("direction" %in% names(formals(SigRepo::prepareHypeRSignatures)))
+  both <- SigRepo::prepareHypeRSignatures(omic_signature = sig, test = "kstest", verbose = FALSE)
+  expect_equal(names(both$signatures), c("sig_a | up", "sig_a | down"))
+  expect_equal(both$signatures[["sig_a | up"]], c(A = 3, B = 2, E = -1, C = -2, D = -3))
+  expect_equal(both$signatures[["sig_a | down"]], c(D = 3, C = 2, E = 1, B = -2, A = -3))
+  expect_equal(both$info$direction, c("up", "down"))
+  expect_equal(both$info$query, names(both$signatures))
+
+  hyper <- SigRepo::prepareHypeRSignatures(omic_signature = sig, verbose = FALSE)
+  expect_true(all(is.na(hyper$info$direction)))
+})
+
+test_that("W5: ks_source = \"signature\" ranks the signature table and reports its own skip reasons", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), test = "kstest",
+                                              ks_source = "signature", verbose = FALSE)
+  expect_equal(prepared$signatures[["sig_a | up"]], c(A = 3, B = 2, C = -2, D = -3))
+  expect_equal(prepared$info$symbol_source, rep("signature$symbol", 2))
+
+  no_score <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), test = "kstest",
+                                              ks_source = "signature", score_col = "logFC", verbose = FALSE)
+  expect_equal(no_score$skipped$reason, "missing_score_col")
+  expect_match(no_score$skipped$message, "signature has no 'logFC' column", fixed = TRUE)
+})
+
+test_that("W1/W5: kstest-only arguments are rejected for hypergeometric", {
+  expect_error(
+    SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), ks_source = "signature", verbose = FALSE),
+    "'ks_source' only applies when test = \"kstest\"", fixed = TRUE
+  )
+  expect_error(
+    SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), test = "kstest", direction = "down", verbose = FALSE),
+    "unused argument (direction = \"down\")", fixed = TRUE
+  )
+})
+
+test_that("W2: query_names receives the info table and its names are validated and de-duplicated", {
+  seen <- NULL
+  prepared <- SigRepo::prepareHypeRSignatures(
+    omic_signature = make_hyper_sig(),
+    query_names = function(info) {
+      seen <<- info
+      rep("same", nrow(info))
+    },
+    verbose = FALSE
+  )
+  expect_equal(seen$query, c("sig_a | Old", "sig_a | Young"))
+  expect_equal(names(prepared$signatures), c("same", "same (2)"))
+  expect_equal(prepared$info$query, c("same", "same (2)"))
+
+  for (bad in list(function(info) "one", function(info) c("a", NA), function(info) c("a", ""), function(info) 1:2)) {
+    expect_error(
+      SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), query_names = bad, verbose = FALSE),
+      "'query_names' must return a character vector of 2 non-empty name(s)", fixed = TRUE
+    )
+  }
+})
+
+test_that("collectHypeRSignatures marks a single OmicSignature as a single input and a list as not", {
+  expect_true(SigRepo:::collectHypeRSignatures(NULL, NULL, NULL, make_hyper_sig(), FALSE)$single)
+  expect_false(SigRepo:::collectHypeRSignatures(NULL, NULL, NULL, list(make_hyper_sig()), FALSE)$single)
+})
+
+# ---- W4: hypeR-native input and getHypeRDifexp() ----
+
+test_that("W4: a character vector is used as given, minus NA/empty symbols and repeats", {
+  prepared <- SigRepo::prepareHypeRSignatures(signature = c("B", NA, " ", "A", "B"), verbose = FALSE)
+  expect_equal(prepared$signatures, list(signature = c("B", "A")))
+  expect_equal(prepared$info$n_dropped, 2L)
+  expect_equal(prepared$info$symbol_source, "supplied")
+  expect_true(is.na(prepared$info$signature_id))
+})
+
+test_that("W4: a named list gives one query per element; a weighted vector keeps its order", {
+  prepared <- SigRepo::prepareHypeRSignatures(
+    signature = list(up = c("A", "B"), ranked = c(C = -1, A = 2, B = NA)),
+    test = "kstest", verbose = FALSE
+  )
+  expect_equal(names(prepared$signatures), c("up | up", "up | down", "ranked | up", "ranked | down"))
+  expect_equal(prepared$signatures[["ranked | up"]], c(C = -1, A = 2))
+  # The down query tests the other end: the reversed ranking, with negated scores.
+  expect_equal(prepared$signatures[["ranked | down"]], c(A = -2, C = 1))
+  expect_equal(prepared$signatures[["up | down"]], c("B", "A"))
+  expect_equal(prepared$info$direction, c("up", "down", "up", "down"))
+  expect_equal(prepared$info$n_dropped, c(0L, 0L, 1L, 1L))
+})
+
+test_that("W4: invalid hypeR-native input is rejected with a clear message", {
+  prep <- function(...) SigRepo::prepareHypeRSignatures(verbose = FALSE, ...)
+
+  expect_error(prep(signature = list(c("A", "B"))), "must be non-empty with a unique, non-empty name", fixed = TRUE)
+  expect_error(prep(signature = list(a = "A", a = "B")), "must be non-empty with a unique, non-empty name", fixed = TRUE)
+  expect_error(prep(signature = c(A = 1, B = 2)), "test = \"hypergeometric\" needs a character vector", fixed = TRUE)
+  expect_error(prep(signature = c(1, 2), test = "kstest"), "must be a character vector of gene symbols or a named numeric", fixed = TRUE)
+  expect_error(prep(signature = c(A = 1, A = 2), test = "kstest"), "has duplicated gene names", fixed = TRUE)
+  expect_error(prep(signature = "A", omic_signature = make_hyper_sig()), "Supply either 'signature' or SigRepo signatures", fixed = TRUE)
+  expect_error(prep(signature = "A", signature_id = 5), "Supply either 'signature' or SigRepo signatures", fixed = TRUE)
+  expect_error(prep(signature = "A", test = "kstest", ks_source = "signature"), "with 'signature', order the vector yourself", fixed = TRUE)
+})
+
+test_that("W4: an all-NA element is skipped, and query_names applies to native input", {
+  prepared <- SigRepo::prepareHypeRSignatures(
+    signature = list(a = c("A", "B"), empty = NA_character_),
+    query_names = function(info) toupper(info$query), verbose = FALSE
+  )
+  expect_equal(names(prepared$signatures), "A")
+  expect_equal(prepared$skipped$signature, "empty")
+  expect_equal(prepared$skipped$reason, "empty_signature")
+})
+
+test_that("W4: getHypeRDifexp adds resolved symbols and leaves out signatures without difexp", {
+  testthat::local_mocked_bindings(
+    lookupReferenceSymbols = function(conn_handler, assay_type, organism, feature_names) c(f1 = "A", f2 = "B"),
+    .package = "SigRepo"
+  )
+  difexp <- hyper_difexp_table()
+  difexp$gene_symbol <- NULL
+  with_difexp <- make_hyper_sig("with", difexp = difexp)
+
+  expect_warning(
+    tables <- SigRepo::getHypeRDifexp(omic_signature = list(with_difexp, make_hyper_sig("without")), verbose = FALSE),
+    "No difexp table for 'without'; left out.", fixed = TRUE
+  )
+  expect_equal(names(tables), "with")
+  tbl <- tables$with
+  expect_equal(nrow(tbl), nrow(difexp))
+  expect_equal(tbl$resolved_symbol[match(c("f1", "f2", "f3"), tbl$feature_name)], c("A", "B", NA))
+  expect_true(all(tbl$resolved_symbol_source == "reference feature_name"))
+})
+
+# ---- Direction types and ranking checks ----
+
+test_that("categorical hypergeometric splits each category by score sign; zero scores join neither", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_categorical_sig(), verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), c("cat | red | up", "cat | red | down", "cat | white | up", "cat | white | down"))
+  expect_equal(unname(prepared$signatures), list("A", "B", c("D", "F"), "E"))
+  expect_equal(prepared$info$group_label, c("red", "red", "white", "white"))
+  expect_equal(prepared$info$direction, c("up", "down", "up", "down"))
+  expect_false("C" %in% unlist(prepared$signatures))
+})
+
+test_that("categorical hypergeometric without scores splits by category only; split = FALSE gives one query", {
+  sig <- make_hyper_categorical_sig()
+  tbl <- sig$signature
+  tbl$score <- NA_real_
+  no_score <- list(metadata = sig$metadata, signature = tbl, difexp = sig$difexp)
+
+  by_group <- SigRepo:::buildHypergeometricQueries(no_score, "cat", NA_character_, TRUE, SigRepo:::newHypeRSymbolResolver(NULL))
+  expect_equal(names(by_group$queries), c("cat | red", "cat | white"))
+  expect_true(all(is.na(by_group$info$direction)))
+
+  one <- SigRepo::prepareHypeRSignatures(omic_signature = sig, split = FALSE, verbose = FALSE)
+  expect_equal(one$signatures, list(cat = c("A", "B", "C", "D", "E", "F")))
+})
+
+test_that("bi-directional hypergeometric still splits by group_label only, not by sign", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(), verbose = FALSE)
+  expect_equal(names(prepared$signatures), c("sig_a | Old", "sig_a | Young"))
+})
+
+test_that("categorical kstest ranks each category's own difexp rows, in both directions", {
+  prepared <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_categorical_sig(), test = "kstest", verbose = FALSE)
+
+  expect_equal(names(prepared$signatures), c("cat | red | up", "cat | red | down", "cat | white | up", "cat | white | down"))
+  expect_equal(prepared$signatures[["cat | red | up"]], c(A = 2, C = 0.5, E = 0.2, F = 0.1, D = -0.3, B = -1))
+  expect_equal(prepared$signatures[["cat | white | down"]], c(C = 2, A = 1, F = 0.5, B = -0.4, E = -1, D = -3))
+  expect_equal(prepared$info$group_label, c("red", "red", "white", "white"))
+})
+
+test_that("a categorical category with unsigned scores is skipped; the other categories still run", {
+  prepared <- SigRepo::prepareHypeRSignatures(
+    omic_signature = make_hyper_categorical_sig(c(2, 1, 0.5, 0.3, 0.2, 0.1)), test = "kstest", verbose = FALSE
+  )
+  expect_equal(names(prepared$signatures), c("cat | white | up", "cat | white | down"))
+  expect_equal(prepared$skipped$signature, "cat | red")
+  expect_equal(prepared$skipped$reason, "unsigned_score")
+})
+
+test_that("a categorical difexp without group_label is skipped for kstest", {
+  sig <- make_hyper_categorical_sig()
+  difexp <- sig$difexp
+  difexp$group_label <- NA
+  bare <- list(metadata = sig$metadata, signature = sig$signature, difexp = difexp)
+  built <- SigRepo:::buildKstestQueries(bare, "cat", NA_character_, "score", "up", "difexp", SigRepo:::newHypeRSymbolResolver(NULL))
+  expect_equal(built$skip$reason, "no_group_label")
+})
+
+test_that("kstest skips a ranking with constant or one-signed scores", {
+  unsigned <- hyper_difexp_table()
+  unsigned$score <- abs(unsigned$score)
+  skipped <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(difexp = unsigned), test = "kstest", verbose = FALSE)
+  expect_equal(skipped$skipped$reason, "unsigned_score")
+  expect_match(skipped$skipped$message, "all >= 0", fixed = TRUE)
+
+  tbl <- hyper_sig_table()
+  tbl$score <- 1
+  constant <- SigRepo::prepareHypeRSignatures(omic_signature = make_hyper_sig(signature = tbl, type = "uni-directional"),
+                                              test = "kstest", ks_source = "signature", verbose = FALSE)
+  expect_equal(constant$skipped$reason, "constant_score")
+})
diff --git a/tests/testthat/test_mergeDifexp.R b/tests/testthat/test_mergeDifexp.R
new file mode 100644
index 00000000..be0f6e62
--- /dev/null
+++ b/tests/testthat/test_mergeDifexp.R
@@ -0,0 +1,246 @@
+# Offline tests for mergeDifexp(). Signatures come from the bundled example
+# objects, and the database helpers it relies on -- searchSignature() and
+# getSignature() -- are replaced with local mocks, so the tests cover the
+# merge itself and the id/name resolution without a database.
+
+example_signatures <- function(){
+  env <- base::environment()
+  utils::data(
+    list = c("omic_signature_1", "omic_signature_2", "omic_signature_3"),
+    package = "SigRepo",
+    envir = env
+  )
+  base::list(v1 = env$omic_signature_1, v2 = env$omic_signature_2, v3 = env$omic_signature_3)
+}
+
+# A small hand-made signature whose difexp we control exactly. Metadata is
+# borrowed from a bundled signature so it passes OmicSignature's checks. ####
+toy_signature <- function(name, difexp){
+  metadata <- example_signatures()$v1$metadata
+  metadata$signature_name <- name
+  difexp$group_label <- base::factor(base::ifelse(difexp$score > 0, "up", "down"))
+  signature <- difexp[, c("probe_id", "feature_name", "score", "group_label")]
+  OmicSignature::OmicSignature$new(metadata = metadata, signature = signature, difexp = difexp)
+}
+
+toy_difexp <- function(probe_id, feature_name, score, p_value = 0.01, logfc = score / 2){
+  base::data.frame(
+    probe_id = base::as.character(probe_id), feature_name = feature_name, score = score,
+    logfc = logfc, p_value = p_value, adj_p = p_value, stringsAsFactors = FALSE
+  )
+}
+
+toy_pair <- function(){
+  a <- toy_signature("sigA", toy_difexp(
+    probe_id = 1:4, feature_name = c("G1", "G2", "G3", "G2"), score = c(1, -2, 3, 5)
+  ))
+  b <- toy_signature("sigB", toy_difexp(
+    probe_id = 1:3, feature_name = c("G1", "G3", "G4"), score = c(-1, 0.5, 2)
+  ))
+  base::list(a = a, b = b)
+}
+
+mock_database <- function(sigs, rows){
+  calls <- base::new.env()
+  calls$get <- base::list()
+  filter_rows <- function(signature_id, signature_name){
+    hits <- rows
+    if(base::length(signature_id) > 0){
+      hits <- hits[base::as.character(hits$signature_id) %in% base::trimws(base::as.character(signature_id)), , drop = FALSE]
+    }
+    if(base::length(signature_name) > 0){
+      hits <- hits[base::tolower(hits$signature_name) %in% base::tolower(base::trimws(signature_name)), , drop = FALSE]
+    }
+    hits
+  }
+  search_fn <- function(conn_handler = NULL, signature_id = NULL, signature_name = NULL, ..., verbose = TRUE){
+    filter_rows(signature_id, signature_name)[, c("signature_id", "signature_name", "user_name"), drop = FALSE]
+  }
+  get_fn <- function(conn_handler = NULL, signature_name = NULL, signature_id = NULL, verbose = TRUE){
+    calls$get[[base::length(calls$get) + 1L]] <- base::list(signature_id = signature_id, signature_name = signature_name)
+    hits <- filter_rows(signature_id, signature_name)
+    if(base::nrow(hits) == 0) return(NULL)
+    stats::setNames(sigs[hits$key], hits$signature_name)
+  }
+  base::list(calls = calls, search = search_fn, get = get_fn)
+}
+
+mock_conn_handler <- base::list(dbname = "sigrepo", host = "mock", port = 3306, user = "tester", password = "x")
+
+## Shape ####
+
+test_that("the result is a feature-by-signature matrix with the union of features", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs)
+
+  expect_true(base::is.matrix(m))
+  expect_type(m, "double")
+  expect_equal(base::colnames(m), c("a", "b"))
+  expect_setequal(base::rownames(m), c("G1", "G2", "G3", "G4"))
+  expect_equal(m["G1", ], c(a = 1, b = -1))
+  expect_equal(m["G3", ], c(a = 3, b = 0.5))
+  expect_true(base::is.na(m["G4", "a"]))
+  expect_true(base::is.na(m["G2", "b"]))
+})
+
+test_that("unnamed objects are named by their signature_name", {
+  sigs <- base::unname(toy_pair())
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs)
+
+  expect_equal(base::colnames(m), c("sigA", "sigB"))
+})
+
+test_that("features = 'intersect' keeps only features present in every table", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs, features = "intersect")
+
+  expect_setequal(base::rownames(m), c("G1", "G3"))
+  expect_false(base::anyNA(m))
+})
+
+## Duplicate features ####
+
+test_that("duplicate feature names collapse to the value with the largest absolute size by default", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs)
+
+  # G2 appears twice in sigA with scores -2 and 5.
+  expect_equal(m["G2", "a"], 5)
+  expect_equal(base::sum(base::rownames(m) == "G2"), 1L)
+})
+
+test_that("collapse = 'mean' averages duplicate feature names", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs, collapse = "mean")
+
+  expect_equal(m["G2", "a"], 1.5)
+})
+
+test_that("collapse = 'first' keeps the first row of a duplicated feature", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs, collapse = "first")
+
+  expect_equal(m["G2", "a"], -2)
+})
+
+test_that("collapse = 'min' keeps the smallest value of a duplicated feature", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs, collapse = "min")
+
+  expect_equal(m["G2", "a"], -2)
+  expect_equal(m["G1", "a"], 1)
+})
+
+test_that("collapse = 'min' on a p-value column keeps the most significant probe", {
+  a <- toy_signature("sigA", toy_difexp(
+    probe_id = 1:3, feature_name = c("G1", "G2", "G2"), score = c(1, 2, 3),
+    p_value = c(0.5, 0.2, 0.001)
+  ))
+
+  m <- SigRepo::mergeDifexp(omic_signatures = base::list(a = a), value_col = "p_value", collapse = "min")
+
+  expect_equal(m["G2", "a"], 0.001)
+  expect_equal(m["G1", "a"], 0.5)
+  expect_equal(base::sum(base::rownames(m) == "G2"), 1L)
+})
+
+test_that("collapse = 'min' ignores NA values within a feature and returns NA when all are NA", {
+  a <- toy_signature("sigA", toy_difexp(
+    probe_id = 1:4, feature_name = c("G1", "G1", "G2", "G2"), score = c(1, 2, 3, 4),
+    p_value = c(NA, 0.3, NA, NA)
+  ))
+
+  m <- SigRepo::mergeDifexp(omic_signatures = base::list(a = a), value_col = "p_value", collapse = "min")
+
+  expect_equal(m["G1", "a"], 0.3)
+  expect_true(base::is.na(m["G2", "a"]))
+})
+
+## Columns ####
+
+test_that("value_col picks another difexp column", {
+  sigs <- toy_pair()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs, value_col = "logfc")
+
+  expect_equal(m["G1", ], c(a = 0.5, b = -0.5))
+})
+
+test_that("a signature whose difexp lacks value_col is dropped with a warning", {
+  sigs <- toy_pair()
+  difexp <- sigs$b$difexp
+  difexp$logfc <- NULL
+  sigs$b$difexp <- difexp
+
+  expect_warning(
+    m <- SigRepo::mergeDifexp(omic_signatures = sigs, value_col = "logfc"),
+    "b"
+  )
+  expect_equal(base::colnames(m), "a")
+})
+
+## Missing difexp ####
+
+test_that("a signature without a difexp table is dropped with a warning", {
+  sigs <- toy_pair()
+  no_difexp <- OmicSignature::OmicSignature$new(metadata = sigs$b$metadata, signature = sigs$b$signature)
+  sigs$b <- no_difexp
+
+  expect_warning(m <- SigRepo::mergeDifexp(omic_signatures = sigs), "b")
+  expect_equal(base::colnames(m), "a")
+})
+
+test_that("it is an error when no signature has a usable difexp table", {
+  sigs <- toy_pair()
+  sigs <- base::lapply(sigs, function(s) OmicSignature::OmicSignature$new(metadata = s$metadata, signature = s$signature))
+
+  expect_error(
+    suppressWarnings(SigRepo::mergeDifexp(omic_signatures = sigs)),
+    "difexp"
+  )
+})
+
+test_that("it is an error when no signatures are given at all", {
+  expect_error(SigRepo::mergeDifexp(), "signature_ids")
+})
+
+## Bundled example signatures ####
+
+test_that("the bundled signatures merge into one matrix with every feature once", {
+  sigs <- example_signatures()
+
+  m <- SigRepo::mergeDifexp(omic_signatures = sigs)
+
+  expect_equal(base::colnames(m), c("v1", "v2", "v3"))
+  expect_setequal(base::rownames(m), base::unique(sigs$v1$difexp$feature_name))
+  expect_false(base::any(base::duplicated(base::rownames(m))))
+})
+
+## Database resolution ####
+
+test_that("signatures requested by id and name are fetched through getSignature", {
+  sigs <- toy_pair()
+  rows <- base::data.frame(
+    signature_id = c(21L, 22L), signature_name = c("sigA", "sigB"), user_name = "tester",
+    key = c("a", "b"), stringsAsFactors = FALSE
+  )
+  db <- mock_database(sigs, rows)
+  testthat::local_mocked_bindings(searchSignature = db$search, getSignature = db$get, .package = "SigRepo")
+
+  m <- SigRepo::mergeDifexp(conn_handler = mock_conn_handler, signature_ids = 21, signature_names = "sigB")
+
+  expect_equal(base::colnames(m), c("sigA", "sigB"))
+  expect_equal(base::length(db$calls$get), 2L)
+  expect_equal(m["G1", ], c(sigA = 1, sigB = -1))
+})
+
+test_that("a connection is required to fetch by id", {
+  expect_error(SigRepo::mergeDifexp(signature_ids = 1), "conn_handler")
+})
diff --git a/tests/testthat/test_searchExternal.R b/tests/testthat/test_searchExternal.R
new file mode 100644
index 00000000..a444d916
--- /dev/null
+++ b/tests/testthat/test_searchExternal.R
@@ -0,0 +1,103 @@
+# searchExternal() dispatcher. The signature resolver and the three adapters
+# are mocked, so this exercises argument handling, direction splitting,
+# fan-out and the return shape only.
+
+fake_signature <- function(feature_name, score = NULL, organism = "Homo sapiens", name = "fake_sig") {
+  sig <- base::data.frame(probe_id = base::seq_along(feature_name), feature_name = feature_name, stringsAsFactors = FALSE)
+  if (!base::is.null(score)) sig$score <- score
+  base::list(signature = sig, metadata = base::list(signature_name = name, organism = organism, assay_type = "transcriptomics"))
+}
+one_hit <- function(source, query) {
+  bindExternalHits(source, query$direction, list(list(id = paste0(source, "-hit"), title = "t", score = 1)))
+}
+
+test_that("searchExternal with one source returns a data frame", {
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    externalRummagene = function(query, limit, timeout) one_hit("rummagene", query)
+  )
+  out <- searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), source = "rummagene", verbose = FALSE)
+  expect_s3_class(out, "data.frame")
+  expect_equal(out$id, "rummagene-hit")
+  expect_equal(out$direction, "combined")
+})
+
+test_that("searchExternal with several sources returns a named list and survives one failure", {
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    externalRummagene = function(query, limit, timeout) one_hit("rummagene", query),
+    externalRummageo = function(query, limit, timeout) stop("rummageo is down"),
+    externalCoresh = function(query, limit, calculate_pvalues, timeout) one_hit("coresh", query)
+  )
+  expect_warning(
+    out <- searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), verbose = FALSE),
+    "rummageo: rummageo is down"
+  )
+  expect_type(out, "list")
+  expect_equal(names(out), c("rummagene", "rummageo", "coresh"))
+  expect_equal(nrow(out$rummageo), 0)
+  expect_equal(out$coresh$id, "coresh-hit")
+})
+
+test_that("searchExternal with a single failing source errors instead of warning", {
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    externalCoresh = function(query, limit, calculate_pvalues, timeout) stop("CORESH job x failed.")
+  )
+  expect_error(
+    searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), source = "coresh", verbose = FALSE),
+    "CORESH job x failed"
+  )
+})
+
+test_that("searchExternal direction = 'both' stacks up and down with a direction column", {
+  seen <- character()
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    externalRummagene = function(query, limit, timeout) { seen <<- c(seen, query$genes); one_hit("rummagene", query) }
+  )
+  sig <- fake_signature(c("UP1", "UP2", "DN1", "DN2"), score = c(2, 1, -1, -2))
+  out <- searchExternal(omic_signature = sig, source = "rummagene", direction = "both", verbose = FALSE)
+  expect_equal(out$direction, c("up", "down"))
+  expect_setequal(seen, c("UP1", "UP2", "DN1", "DN2"))
+  expect_equal(names(attr(out, "query")), c("up", "down"))
+})
+
+test_that("searchExternal passes limit and calculate_pvalues through to CORESH", {
+  seen <- list()
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    externalCoresh = function(query, limit, calculate_pvalues, timeout) {
+      seen <<- list(limit = limit, pv = calculate_pvalues, timeout = timeout)
+      one_hit("coresh", query)
+    }
+  )
+  searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), source = "coresh",
+                 limit = 7, calculate_pvalues = TRUE, timeout = 33, verbose = FALSE)
+  expect_equal(seen, list(limit = 7L, pv = TRUE, timeout = 33))
+})
+
+test_that("searchExternal validates its arguments", {
+  expect_error(searchExternal(omic_signature = fake_signature(c("A", "B")), source = "enrichr"), "should be one of")
+  expect_error(searchExternal(omic_signature = fake_signature(c("A", "B")), source = "coresh", limit = 0), "positive integer")
+})
+
+test_that("searchExternal reports how many hits came back per source when verbose", {
+  testthat::local_mocked_bindings(
+    resolveComparisonSignature = function(conn_handler, signature_id, signature_name, omic_signature, label, verbose) omic_signature,
+    lookupSymbolsInSigRepo = function(...) character(),
+    lookupSymbolsInBiomart = function(...) character(),
+    externalRummagene = function(query, limit, timeout) {
+      out <- one_hit("rummagene", query); attr(out, "total_count") <- 27875; out
+    },
+    externalCoresh = function(query, limit, calculate_pvalues, timeout) one_hit("coresh", query)
+  )
+  expect_message(
+    searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), source = "rummagene", limit = 25, verbose = TRUE),
+    "rummagene: 1 of 27,875 matching hits returned \\(limit = 25\\)"
+  )
+  expect_message(
+    searchExternal(omic_signature = fake_signature(c("TP53", "BRCA1")), source = "coresh", limit = 25, verbose = TRUE),
+    "coresh: 1 hit returned \\(limit = 25\\)"
+  )
+})
diff --git a/tests/testthat/test_writeSignatureSearchScript.R b/tests/testthat/test_writeSignatureSearchScript.R
new file mode 100644
index 00000000..a479641c
--- /dev/null
+++ b/tests/testthat/test_writeSignatureSearchScript.R
@@ -0,0 +1,218 @@
+# writeSignatureSearchScript() writes an R script and runs nothing, so these
+# tests need neither a database nor signatureSearch. They read the query back
+# out of the written script instead of trusting the function's return value.
+
+lincs_sig_table <- function(n_up = 12, n_down = 12) {
+  n <- n_up + n_down
+  data.frame(
+    probe_id = paste0("p", seq_len(n)),
+    feature_name = sprintf("ENSG%011d", seq_len(n)),
+    score = c(seq_len(n_up), -seq_len(n_down)),
+    group_label = factor(c(rep("Old", n_up), rep("Young", n_down))),
+    stringsAsFactors = FALSE
+  )
+}
+
+make_lincs_sig <- function(signature = lincs_sig_table(), ...) {
+  make_hyper_sig(name = "lincs_sig", signature = signature, ...)
+}
+
+local_script_path <- function(env = parent.frame()) {
+  withr::local_tempfile(fileext = ".R", .local_envir = env)
+}
+
+# The values the script assigns at top level, without running the search.
+script_values <- function(path) {
+  wanted <- c("signature_name", "id_type", "up_ids", "down_ids", "n_genes", "output_file", "plot_file")
+  env <- new.env()
+  for (expr in parse(path)) {
+    if (is.call(expr) && identical(expr[[1]], as.name("<-")) && as.character(expr[[2]])[1] %in% wanted) {
+      eval(expr, env)
+    }
+  }
+  as.list(env)
+}
+
+test_that("the script holds each direction's features, strongest score first", {
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE)
+
+  values <- script_values(path)
+  expect_equal(values$signature_name, "lincs_sig")
+  expect_equal(values$up_ids, sprintf("ENSG%011d", 12:1))
+  expect_equal(values$down_ids, sprintf("ENSG%011d", 24:13))
+})
+
+test_that("the script runs the LINCS search and saves the result", {
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE)
+
+  called <- all.names(parse(path))
+  expect_true(all(c("qSig", "gess_lincs", "write.csv") %in% called))
+})
+
+test_that("the script plots the strongest hits to a PDF named after the signature", {
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE)
+
+  expect_equal(script_values(path)$output_file, "lincs_sig_lincs_results.csv")
+  expect_equal(script_values(path)$plot_file, "lincs_sig_lincs_top_hits.pdf")
+  expect_true(all(c("gess_res_vis", "ggsave") %in% all.names(parse(path))))
+})
+
+# gess_lincs() annotates its hits with data sets it loads by name, which R
+# only finds in an attached package: called as signatureSearch::gess_lincs()
+# alone, the search runs and then fails with "object 'clue_moa_list' not found".
+test_that("the script attaches signatureSearch", {
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE)
+
+  expect_match(
+    paste(deparse(parse(path)), collapse = "\n"),
+    "library(signatureSearch)",
+    fixed = TRUE
+  )
+})
+
+test_that("the path is returned invisibly", {
+  path <- local_script_path()
+  out <- withVisible(SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE))
+
+  expect_false(out$visible)
+  expect_equal(normalizePath(out$value), normalizePath(path))
+})
+
+test_that("a feature scored in both directions is left out of both", {
+  tbl <- lincs_sig_table()
+  tbl$feature_name[24] <- tbl$feature_name[1]
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(tbl), file = path, verbose = FALSE)
+
+  values <- script_values(path)
+  expect_false(tbl$feature_name[1] %in% c(values$up_ids, values$down_ids))
+  expect_length(values$up_ids, 11)
+  expect_length(values$down_ids, 11)
+})
+
+test_that("features with a zero or missing score are left out", {
+  tbl <- lincs_sig_table(n_up = 13, n_down = 13)
+  tbl$score[13] <- 0
+  tbl$score[26] <- NA
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(tbl), file = path, verbose = FALSE)
+
+  values <- script_values(path)
+  expect_false(any(tbl$feature_name[c(13, 26)] %in% c(values$up_ids, values$down_ids)))
+})
+
+test_that("Ensembl IDs lose their version suffix and are mapped as ENSEMBL", {
+  tbl <- lincs_sig_table()
+  tbl$feature_name <- paste0(tbl$feature_name, ".", seq_len(nrow(tbl)))
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(tbl), file = path, verbose = FALSE)
+
+  values <- script_values(path)
+  expect_equal(values$id_type, "ENSEMBL")
+  expect_equal(values$up_ids, sprintf("ENSG%011d", 12:1))
+})
+
+test_that("feature names that are not Ensembl IDs are mapped as SYMBOL", {
+  tbl <- lincs_sig_table()
+  tbl$feature_name <- paste0("GENE", seq_len(nrow(tbl)))
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(tbl), file = path, verbose = FALSE)
+
+  values <- script_values(path)
+  expect_equal(values$id_type, "SYMBOL")
+  expect_equal(values$up_ids, paste0("GENE", 12:1))
+})
+
+test_that("n_genes is written into the script", {
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, n_genes = 50, verbose = FALSE)
+
+  expect_equal(script_values(path)$n_genes, 50)
+})
+
+test_that("a signature name with quotes and line breaks cannot alter the script", {
+  tbl <- lincs_sig_table()
+  name <- "evil\"); stop('injected')\n stop('injected') #"
+  sig <- make_hyper_sig(name = name, signature = tbl)
+  path <- local_script_path()
+  SigRepo::writeSignatureSearchScript(omic_signature = sig, file = path, verbose = FALSE)
+
+  expect_equal(script_values(path)$signature_name, name)
+  expect_false("injected" %in% unlist(lapply(parse(path), function(e) if (is.call(e) && identical(e[[1]], as.name("stop"))) as.character(e[[2]]))))
+})
+
+test_that("the organism check ignores case", {
+  path <- local_script_path()
+  # OmicSignature warns that this spelling is not in its organism list; the
+  # bundled LLFS_Aging_Gene_2023 is stored with it.
+  sig <- suppressWarnings(make_lincs_sig(organism = "Homo Sapiens"))
+
+  expect_no_error(SigRepo::writeSignatureSearchScript(omic_signature = sig, file = path, verbose = FALSE))
+})
+
+test_that("a signature that is not human is refused", {
+  path <- local_script_path()
+  sig <- make_lincs_sig(organism = "Mus musculus")
+
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = sig, file = path, verbose = FALSE),
+    "Homo sapiens.*Mus musculus"
+  )
+  expect_false(file.exists(path))
+})
+
+test_that("a signature that is not transcriptomics is refused", {
+  path <- local_script_path()
+  sig <- make_lincs_sig(assay_type = "proteomics")
+
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = sig, file = path, verbose = FALSE),
+    "transcriptomics.*proteomics"
+  )
+  expect_false(file.exists(path))
+})
+
+test_that("fewer than 10 features in a direction is refused", {
+  path <- local_script_path()
+  sig <- make_lincs_sig(lincs_sig_table(n_up = 12, n_down = 9))
+
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = sig, file = path, verbose = FALSE),
+    "12 up and 9 down"
+  )
+  expect_false(file.exists(path))
+})
+
+test_that("an existing file is kept unless overwrite = TRUE", {
+  path <- local_script_path()
+  writeLines("keep me", path)
+
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, verbose = FALSE),
+    "overwrite = TRUE"
+  )
+  expect_equal(readLines(path), "keep me")
+
+  SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, overwrite = TRUE, verbose = FALSE)
+  expect_equal(script_values(path)$signature_name, "lincs_sig")
+})
+
+test_that("file is required", {
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), verbose = FALSE),
+    "'file' is required"
+  )
+})
+
+test_that("n_genes below the 10-feature floor is refused", {
+  path <- local_script_path()
+
+  expect_error(
+    SigRepo::writeSignatureSearchScript(omic_signature = make_lincs_sig(), file = path, n_genes = 5, verbose = FALSE),
+    "'n_genes'"
+  )
+})
diff --git a/vignettes/annotation-tutorial.Rmd b/vignettes/annotation-tutorial.Rmd
new file mode 100644
index 00000000..758531b3
--- /dev/null
+++ b/vignettes/annotation-tutorial.Rmd
@@ -0,0 +1,325 @@
+---
+title: "Annotate signatures with hypeR"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Annotate signatures with hypeR}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE}
+# The code runs only when a SigRepo account is supplied through the
+# SIGREPO_TEST_DB_USER and SIGREPO_TEST_DB_PASSWORD environment variables;
+# otherwise the tutorial shows its code without running it. Credentials never
+# go in this file. Everything here only reads from the database.
+has_account <- base::nzchar(base::Sys.getenv("SIGREPO_TEST_DB_USER")) &&
+  base::nzchar(base::Sys.getenv("SIGREPO_TEST_DB_PASSWORD"))
+
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  message = FALSE,
+  fig.align = "center",
+  eval = has_account
+)
+```
+
+This tutorial will walk you through how to fetch, and annotate signatures with gene set enrichment, in three
+steps:
+
+1. Find the signatures you want to test with `searchSignature()`.
+2. Test them against a geneset collection with `runHypeR()`.
+3. Plot the results with `plotHypeRDots()` and `plotHypeREnrichment()`.
+
+The same analysis runs without code in the SigRepo website's Annotate tab; see
+[the end of this tutorial](#the-same-analysis-in-the-annotate-tab).
+
+# Load packages:
+All of the required packages for annotate (fgsea, hypeR) are built into SigRepo.
+
+```{r load packages}
+library(SigRepo)
+```
+
+# Connect to SigRepo
+
+Connect with your own SigRepo account.
+
+```{r connect, eval = FALSE}
+conn_handler <- SigRepo::newConnHandler(
+  # required: your SigRepo account
+  user = "montilab",
+  password = "sigrepo",
+  dbname = "sigrepo",
+  host = "sigrepo.org",
+  port = 3306
+)
+```
+
+```{r account, include = FALSE}
+conn_handler <- SigRepo::newConnHandler(
+  dbname = base::Sys.getenv("SIGREPO_TEST_DB_NAME", "sigrepo"),
+  host = base::Sys.getenv("SIGREPO_TEST_DB_HOST", "sigrepo.org"),
+  port = base::as.numeric(base::Sys.getenv("SIGREPO_TEST_DB_PORT", "3306")),
+  user = base::Sys.getenv("SIGREPO_TEST_DB_USER"),
+  password = base::Sys.getenv("SIGREPO_TEST_DB_PASSWORD"),
+  api_host = base::Sys.getenv("SIGREPO_TEST_API_HOST", "http://142.93.67.157:8020"),
+  api_port = base::as.numeric(base::Sys.getenv("SIGREPO_TEST_API_PORT", "8020"))
+)
+```
+
+# Step 1: Find the signatures to test
+
+`searchSignature()` returns one row per signature you can see, with its
+metadata. Here we look for human signatures:
+
+```{r search}
+human <- SigRepo::searchSignature(
+  # required:
+  conn_handler = conn_handler,
+
+  # optional filters, any combination:
+  organism = "Homo sapiens",
+  phenotype = NULL,
+  sample_type = NULL,
+  platform = NULL,
+  signature_name = NULL,
+  signature_id = NULL,
+  user_name = NULL,
+  verbose = FALSE
+)
+
+nrow(human)
+```
+
+Narrow the results down to the sample you want. Enrichment works best on
+signatures stored with their full differential expression table (`has_difexp`),
+because the ranked tests (KS and fgsea) rank every measured gene. Smaller difexp
+tables that already carry gene symbols run fastest. Here we take the same
+experiment in two breast cancer cell lines: knockdown of the aryl hydrocarbon
+receptor (AhR) in MDA-MB-231 and in SUM149PT cells, each compared with control
+cells (`CN`):
+
+```{r sample}
+experiments <- c(
+  "BreastCancer_Hs_MDA_AhR_KD_vs_CN_MontiLab",
+  "BreastCancer_Hs_SUM149PT_AhR_KD_vs_CN_MontiLab"
+)
+
+my_signatures <- human[
+  human$signature_name %in% experiments & human$has_difexp == 1,
+  c("signature_id", "signature_name", "assay_type", "num_of_difexp", "num_up_regulated", "num_down_regulated")
+]
+my_signatures
+```
+
+# Step 2: Run the enrichment
+
+For enrichment, SigRepo uses [hypeR](https://github.com/montilab/hypeR), an
+open-source R package for geneset enrichment developed by the Monti lab. You can
+read its documentation at
+[montilab.github.io/hypeR-docs](https://montilab.github.io/hypeR-docs/).
+`runHypeR()` turns SigRepo signatures into hypeR's input, runs the test in your R
+session, and returns hypeR's own result objects.
+
+`runHypeR()` tests every signature against a geneset collection and returns a
+hypeR result. Four things are required:
+
+- **which signatures**: `signature_id` (or `signature_name`) with `conn_handler`. Also takes OmicSignature objects read from `.rds` files, as `omic_signature`;
+- **`organism`**: the organism of every signature in the call;
+- **`test`**: `"hypergeometric"`, `"kstest"` or `"fgsea"`;
+- **`genesets`**: `"msigdb"` with an MSigDB collection, or your own genesets.
+
+## The three tests
+
+| `test` | Asks | Tests |
+|---|---|---|
+| `"hypergeometric"` | Are the signature's genes over-represented in a geneset? | the signature's genes, one query per `group_label` |
+| `"kstest"` | Do a geneset's genes sit toward the top or the bottom of the ranking? | every measured gene, ranked by score, then by the negated score |
+| `"fgsea"` | Do a geneset's genes sit toward the top or the bottom of the ranking? | every measured gene, ranked by score, with permutation p-values |
+
+The hypergeometric test only needs the signature's genes. The ranked tests
+(KS and fgsea) need signatures stored with their difexp table, rank all of its
+genes in one list rather than splitting them by `group_label`, and always test
+both ends of that list: each ranked result has a `| up` query (genesets toward
+the highest scores) and a `| down` query (toward the lowest). The sections
+below run each test in turn.
+
+## Hypergeometric test
+
+```{r hypergeometric}
+hyp <- SigRepo::runHypeR(
+  # required:
+  conn_handler = conn_handler,
+  signature_id = my_signatures$signature_id,  # or signature_name = my_signatures$signature_name
+  organism = "Homo sapiens",
+  test = "hypergeometric",
+  genesets = "msigdb",
+  msigdb_collection = "H",                    # required with genesets = "msigdb": "H", "C2", "C5", ...
+
+  # optional:
+  msigdb_subcollection = NULL,                # e.g. "CP:REACTOME" with msigdb_collection = "C2"
+  split = TRUE,                               # one query per group_label of each signature (here AhR / CN)
+  background = NULL,                          # NULL: the signature's measured genes; or a number or gene vector
+  min_query_genes = 4,                        # skip a query with fewer genes found in the genesets
+  fdr_scope = "run",                          # adjust p-values across the whole call ("query": per query)
+  pval = 1,                                   # keep genesets with p-value at or below this
+  fdr = 1,                                    # keep genesets with FDR at or below this
+  verbose = FALSE
+)
+
+names(hyp$data)
+head(hyp$data[[1]]$data[, c("label", "pval", "fdr", "overlap", "geneset")])
+```
+
+The result is a hypeR `multihyp`: one `hyp` per query in `hyp$data`, each with a
+results table in `$data` and the settings it ran with in `$info`. With
+`split = TRUE`, each signature gives one query per `group_label`, here `AhR`
+and `CN`.
+
+## GSEA with fgsea
+
+`fgsea` tests both ends of the ranking in one run and files each geneset under
+`| up` or `| down` by the sign of its enrichment score:
+
+
+```{r fgsea}
+gsea <- SigRepo::runHypeR(
+  # required:
+  conn_handler = conn_handler,
+  signature_id = my_signatures$signature_id,
+  organism = "Homo sapiens",
+  test = "fgsea",
+  genesets = "msigdb",
+  msigdb_collection = "H",
+
+  # optional for fgsea:
+  power = 1,                                  # weight of each gene's score (fgsea's gseaParam)
+  seed = 1,                                   # fgsea samples at random; the seed makes a run repeatable
+  fgsea_args = list(minSize = 15, maxSize = 500),  # other fgsea::fgseaMultilevel() settings
+  fdr = 1,
+  verbose = FALSE
+)
+
+
+# tables are split into up and down tables, in this instance there should be four seperate tables, two for each signature.
+names(gsea$data)
+# showing the result of one table
+head(gsea$data[["BreastCancer_Hs_SUM149PT_AhR_KD_vs_CN_MontiLab | down"]]$data[, c("label", "fdr", "nes", "overlap")], 3)
+```
+
+## KS test
+
+hypeR's KS test only finds genesets at the top of a ranking, so `runHypeR()`
+runs it twice: on the scores (`| up`) and on the negated scores (`| down`),
+adjusting the p-values of both runs for multiple testing together:
+
+```{r kstest}
+ks <- SigRepo::runHypeR(
+  # required:
+  conn_handler = conn_handler,
+  signature_id = my_signatures$signature_id[1],
+  organism = "Homo sapiens",
+  test = "kstest",
+  genesets = "msigdb",
+  msigdb_collection = "H",
+
+  # optional for kstest:
+  score_col = "score",                        # the difexp column that ranks the genes
+  power = 1,                                  # 0 for an unweighted ranked test
+  verbose = FALSE
+)
+
+head(ks$data)
+```
+
+## One organism per call
+
+Genesets are made of one organism's gene symbols, so every signature in a call
+must match `organism`. Asking for another organism, or mixing human and mouse
+signatures, stops with an error that names the signatures. Run each organism
+in its own call:
+
+```{r organism mismatch, error = TRUE}
+SigRepo::runHypeR(
+  conn_handler = conn_handler,
+  signature_id = my_signatures$signature_id[1],
+  organism = "Mus musculus",
+  test = "hypergeometric",
+  genesets = "msigdb",
+  msigdb_collection = "MH",
+  verbose = FALSE
+)
+```
+
+# Step 3: Visualize the results
+
+Every plot is drawn from the result object and titled with the test that was
+run. `plotHypeRDots()` and `plotHypeREnrichment()` return ggplot objects, which
+you can save with `ggplot2::ggsave()`.
+
+## Dot plot: every signature at once
+
+One column per query and one row per geneset; a blank cell means the geneset
+did not pass the cutoffs for that query. With several signatures, each
+signature's columns sit under a short code (`S1`, `S2`, ...) explained in the
+caption.
+
+```{r dots hypergeometric, fig.width = 8, fig.height = 6}
+
+# hypergeometric dot plot example
+
+SigRepo::plotHypeRDots(
+  # required:
+  hyp_obj = hyp,
+
+  # optional:
+  top = 15,                                   # number of genesets, the best by FDR across all queries
+  fdr = 0.25,                                 # hide genesets above this FDR
+  val = "fdr",                                # rank and colour by "fdr" or "pval"
+  color_by = "significance",                  # "score" (NES) for kstest and fgsea results
+  size_by = "geneset",                        # dot size: "geneset", "overlap" or "none"
+  signature_key = TRUE,                       # FALSE labels columns with the full query names
+  title = NULL                                # NULL: the test that was run
+)
+
+```
+
+For the ranked tests, `color_by = "score"` shows the direction of enrichment:
+
+```{r dots fgsea, fig.width = 8, fig.height = 6}
+SigRepo::plotHypeRDots(gsea, top = 15, fdr = 0.05, color_by = "score")
+SigRepo::plotHypeRDots(ks, fdr = 0.05, top = 15,  color_by = "score")
+```
+
+
+
+```{r enrichment hypergeometric, fig.width = 6, fig.height = 4.5}
+SigRepo::plotHypeREnrichment(
+  hyp_obj = hyp,
+  geneset = "HALLMARK_EPITHELIAL_MESENCHYMAL_TRANSITION",
+  query = "BreastCancer_Hs_SUM149PT_AhR_KD_vs_CN_MontiLab | AhR"
+)
+```
+
+# The same analysis in the Annotate tab
+
+The SigRepo website's Annotate tab is a front end to `runHypeR()` and follows the
+same rules:
+
+| In the tab | In R |
+|---|---|
+| Step 1: pick up to 10 signatures, upload OmicSignature `.rds` files, or type gene lists | `signature_id`, `omic_signature` or `signature` |
+| Step 2: **Organism (required)**, then MSigDB or custom genesets | `organism`, `genesets` |
+| Step 3: **Test (required)**, plus split and minimum genes for the hypergeometric test | `test`, `split`, `min_query_genes` |
+| Step 3: Background | `background` |
+
+- A run tests one organism. If a picked or uploaded signature is of another
+  organism, the tab names it and will not run until you change the organism or
+  remove the signature; previewing the queries still works.
+- There is no direction setting. KS and GSEA always rank the whole difexp and
+  return an `| up` and a `| down` query for every signature, as in R.
+- The R code tab writes the `runHypeR()` call and the plot calls that reproduce
+  the run, with `organism` and `test` always included.
+
+See `?runHypeR` and the help page of each plotting function for every argument.