dsh-molbio-tools 0.22.2 → 0.24.1

package/docs/v24-plan.md

@@ -0,0 +1,178 @@
+# 0.24.0 施工计划（已实施）
+
+> 状态：**已实施（0.24.0）**。实际范围 = survey #11 + #12 + 接头表 RNA→DNA 静默错修复；
+> #9 / 2.9b / 2.9c 未纳入。下面的探索记录与备选方案保留原样，便于对照“计划 vs 落地”。
+> 0.23.0 已提交并推送（`4050aa6`）。
+
+## 0. 一句话结论
+
+**0.24.0 建议做 survey #11 + #12（若接受边界，再加 #9 的 perfect-duplex 子集）；
+2.9c 放到 0.25.0；2.9b 暂缓，先解决宿主侧写回 RPC。**
+
+| 候选 | 是否进 0.24.0 | 理由 |
+| --- | --- | --- |
+| survey #11 载体/接头污染筛查 | **建议加入** | 纯计算、已有接头表可复用、S–M、可直接加 benchmark |
+| survey #12 FASTQ 修剪/过滤 | **建议加入** | 现有解析器齐备，只缺写出与修剪层；M、用户价值高 |
+| survey #9 双链热力学 | **可选（只做 perfect duplex）** | 现有 `duplexThermo` 可导出；完整错配表/DMSO 是另一项工作 |
+| 2.9c 结构预览 | **0.25.0** | 可行且不需要宿主 RPC，但解析器 + 客户端查看器是 M–L，和上面三项同版风险偏高 |
+| 2.9b 文献库写回 | **暂缓** | `workspaceFiles` 明确只读；需要新增宿主 Typert Remote + 并发契约，属于架构项 |
+
+## 1. 评估口径
+
+沿用本仓库的既有约束：零运行时依赖、纯 JS、无外部二进制/数据库；工具行为变化必须
+更新 benchmark；客户端改动必须重建 `lib/client.js` 并通过四个客户端套件；不允许为了
+方便绕过 `ctx.fs`/sandboxPolicy。
+
+## 2. 逐项探索
+
+### 2.1 2.9b 文献库写回：被“只读 Remote”挡住
+
+现状：
+
+- `molbio_paper_*` 工具通过 `papers.mjs` 的 `loadLibrary`/`saveLibrary` 读写 `papers.json`；
+  `addPapers`/`updatePaper`/`removePaper` 已定义去重与字段合并语义。
+- 面板的 Papers 页只调用 `ctx.remote.workspaceFiles.read`，是刻意只读的
+  （[client-panel.md](client-panel.md) §3）。
+- DSH 的 `workspaceFiles` 服务在包 README 里写明 **“this service exposes no mutations”**，
+  类型里也只有 `read` / `readBytes` / `stat` / `list` / `changes`。
+- 本包客户端半**没有**宿主侧 RPC；这是为了避开 Typert Remote 的版本耦合而做的取舍
+  （[client-panel.md](client-panel.md) §3）。
+
+所以“面板里改笔记/标签”不是一个 UI 小功能，而是：
+
+1. 在宿主侧新增一个 Typert Remote 服务（或让面板走与工具相同的写路径）；
+2. 定义乐观版本号/串行化队列，避免与 `molbio_paper_update` 并发时丢更新；
+3. 客户端增加对该 Remote 的注入与失败降级；
+4. 处理 panel-only 包在没有该宿主服务时的行为。
+
+**结论：不在 0.24.0 做。** 如果要做，先做一个只含 `describe`/`mutate(expectedVersion)` 的
+宿主 Remote spike，再谈 UI；不要先做表单。
+
+### 2.2 2.9c 结构预览：可行，且不需要宿主 RPC
+
+DSH 的文档预览容器提供了两条可复用路径：
+
+- `ctx.documentPreviews.register({ id, extensions, priority, title, loading })` 注册元数据；
+- 在 keyed 座位 `sidebar.right.tab.document` 下用同一 `id` 注册正文；
+- 正文收到 `resourceAddress` 与 `content`；`loading: 'bytes-complete'` 时
+  `content.kind === 'bytes'`，可直接 `TextDecoder` 解码 PDB/mmCIF/SDF/MOL 文本。
+
+这与本包“浏览器里跑自己的纯模块”的模式一致，不需要新增宿主 RPC。需要新建：
+
+- `structure-preview.mjs`：PDB `ATOM/HETATM`、mmCIF `_atom_site`、SDF/MOL V2000
+  （V3000 可后续）解析；Cα 轨迹/键的 2D 投影（PCA 或给定 2D 坐标）；SVG。
+- 客户端正文：注册 preview + keyed body；空/坏/超大文件降级为说明；不抛异常。
+- 测试：纯解析器已知坐标/键数；客户端 stub 驱动 preview 注册与渲染；contract 计数更新。
+- 文档与 CHANGELOG；面板包 `0.1.8 → 0.1.9`（客户端产物变了）。
+
+**结论：技术上可行，但规模是 M–L，建议单独作为 0.25.0 的主功能。** 0.24.0 若也做，
+会把“纯工具版”变成“工具 + 新查看器”双线，测试面太大。
+
+### 2.3 survey #9 双链热力学：可做子集，完整版不急
+
+现状：
+
+- `lib.mjs` 已有 SantaLucia 1998 NN 表、`primerTm`（含 von Ahsen Mg²⁺ 等效盐校正）、
+  `duplexThermo`、`deltaG37`、`duplexTmFromThermo`；后三者目前是模块私有。
+- `molbio_primer_check` 只报 3' 端 5-mer 的 `end_stability_kcal`，没有整条双链的
+  ΔH/ΔS/ΔG°37。
+
+可低成本交付的 **perfect-duplex 子集**：
+
+- 输入一条链（另一条按反向互补生成），或两条链并校验完全互补；
+- 输出 `delta_h_kcal`、`delta_s_cal`、`delta_g37_kcal`、`tm_celsius`、盐条件；
+- 自互补链的 `Ct` 因子单独处理；
+- 明确写“只支持完全互补双链；错配、凸起、给定二级结构、DMSO 未建模”。
+
+完整版需要 Allawi/SantaLucia 错配表（转写 + 独立校验）、loop 表与 DMSO 经验校正，
+是 M 级且容易“数字看起来对、其实不可互换”。**建议：0.24.0 只在接受上述边界时加入；
+否则留给后续专门版本。**
+
+### 2.4 survey #11 载体/接头污染筛查：最合适的 0.24.0 候选
+
+现状：
+
+- `fastq-qc.mjs` 已有 `ADAPTERS`（Illumina Universal/Small RNA、Nextera、PolyA/PolyG）
+  与 read-level 的 adapter content 面板。
+- **已发现一个现有静默错**：Small RNA 5' 的条目是 RNA（`GUUCAG…`，含 U），而
+  `adapterContent` 直接拿它去 `indexOf` DNA reads；正向分子永远匹配不上，只有它的反向互补
+  能命中其中一条。实测两条（DNA 正向/反向互补）只报 1 条。修法是筛查前把表归一化成 DNA
+  （U→T）或分别生成 DNA 正向/反向 needle；#11 应把这条一起修，并加双向断言。
+- 但没有独立工具，也没有载体骨架签名；不能对单条序列/组装结果做筛查。
+
+建议实现：
+
+- 新建 `contamination.mjs`：把 `ADAPTERS` 移到这里并从 `fastq-qc.mjs` 再导出（保持兼容），
+  增加 `VECTORS`（pUC/pBR322、pET、pcDNA、Gateway attB/attR 等短签名）。
+- `screenContamination(sequenceOrEntries, { maxMismatches, sampleReads })`：
+  正/反向互补、位置、链、错配数、命中条目；序列输入与 FASTA/FASTQ 路径都支持。
+- 工具 `molbio_contamination_screen`；默认 exact，`max_mismatches` 可选 0–2。
+- 输出明确写“短签名筛查，不是 BLAST/全库比对；未命中不等于无污染”。
+
+规模 S–M；新增 1 个工具、1 条 benchmark；不需要客户端改动。
+风险是短签名假阳性/假阴性，必须把表来源、长度和局限写进描述与 README。
+
+### 2.5 survey #12 FASTQ 修剪/过滤：用户价值最高，但要把边界切清楚
+
+现状：
+
+- `seqio.mjs` 有 `parseFastq`（容忍多行）与 `toFasta`，**没有** `toFastq` 与修剪层；
+- `molbio_fasta_fastq` 只做 stats/extract/convert/qc；`molbio_fastq_qc` 只读不写。
+
+建议先做**一个**工具 `molbio_fastq_trim`，覆盖：
+
+- 3' 滑窗质量修剪（窗口均值阈值）与 5' 端低质量修剪；
+- poly-G / poly-A 尾部修剪；
+- 3' 接头 / 5' 引物精确或 seed 匹配修剪；
+- 最小长度、最大 N、可选 subsample；
+- Phred+33/+64 输入（输出保持同一编码）；
+- 写 FASTQ 或 FASTA（`ctx.fs` + sandboxPolicy）。
+
+明确不做：paired-end overlap merge、复杂 semiglobal adapter alignment、UMI 处理
+（这些是另一个规模；不要在一个工具里假装做了）。
+
+规模 M；新增 1 个工具、1 条 benchmark；不需要客户端改动。
+测试应钉住：每条 read 的修剪后长度/质量、poly-G/A 边界、adapter 位置、过滤计数、
+输出 FASTQ 四行结构与 round-trip。
+
+## 3. 推荐的 0.24.0 范围
+
+**主选（低风险、纯工具）：#11 + #12。**
+
+- 工具数 62 → **64**；benchmark 63 → **65**；覆盖 64/64。
+- 新增 `contamination.mjs`、`fastq-trim.mjs`；`seqio.mjs` 增加 `toFastq`。
+- `seqio.mjs` 新增 `toFastq` 会进入浏览器半，因此两个客户端产物需重建；面板包 0.1.8 → 0.1.9（行为未变，只是产物字节变了）。
+- 文档四处计数 + README 工具表 + benchmark tasks + CHANGELOG/history/roadmap。
+
+**可选加项：** #9 的 perfect-duplex 子集（工具数 65、benchmark 66），前提是接受
+“不支持错配/DMSO/指定二级结构”的边界，并在描述里写明。
+
+**不在 0.24.0：** 2.9b（宿主 RPC + 并发）、2.9c（M–L 客户端查看器）、#9 完整错配表。
+
+## 4. 施工顺序（若批准主选）
+
+1. `contamination.mjs` + 表 + `molbio_contamination_screen`；smoke 已知值；
+2. `fastq-trim.mjs` + `toFastq` + `molbio_fastq_trim`；smoke 已知值；
+3. 两条 benchmark 任务 + `verifications.mjs` invocation；`--offline` 先绿；
+4. `test/benchmark-coverage` 64/64；`test/benchmark-profile` 工具数；
+5. README/preset 描述/index 顶部注释/agent.cordis.yml 注释四处同步；
+6. `npm test`、`bench --offline`、定向模型 benchmark（`--tools contamination_screen,fastq_trim`）；
+7. CHANGELOG 0.24.0、docs/history、roadmap；版本 0.24.0；commit。
+
+## 5. 风险与开放问题
+
+- **#11 的签名表**：短签名会假阳性；必须给出来源、长度、默认 exact、未命中声明。
+  需要避免复制有许可证负担的长载体序列。
+- **#12 的“修剪到什么程度”**：滑窗阈值、poly-G 最小 run、adapter 最小匹配长度都要
+  有默认值与边界测试；不要一次把 Trimmomatic/fastp 的所有功能塞进来。
+- **#9 的自互补 Ct 因子**：若做，需用已知序列钉住公式，否则会和 `primerTm` 的
+  非自互补假设悄悄分叉。
+- **2.9c 的 documentPreviews 注入**：若在 0.25.0 做，先验证 `ctx.inject(['documentPreviews'])`
+  在没有该服务的 panel-only profile 中会安全跳过；不要把整个面板 entry 变成硬依赖。
+- **benchmark 成本**：每条新任务都是 full-only；发版前用 `--tools` 定向跑，不默认全量。
+
+## 6. 备选方案（若 0.24.0 想要“看得见”的功能）
+
+把 0.24.0 改成 **2.9c + #11**：结构预览作为主功能，#11 作为配套纯工具；
+#12 与 #9 推到 0.24.1/0.25.0。这个方案的用户可见价值更高，但客户端测试面明显更大，
+且 0.24.0 的发版周期会更长。默认不推荐。

package/docs/workflow.md

@@ -20,13 +20,13 @@
 | 使用 | 模型找得到、用得对吗？ | `benchmark/`（见 [benchmark/README.md](../benchmark/README.md)） |
 
 ```bash
-node test/smoke.mjs         # 插件：mock 注册表跑全部 60 个工具 + 输出 schema 校验
+node test/smoke.mjs         # 插件：mock 注册表跑全部 64 个工具 + 输出 schema 校验
 node test/svgpng.mjs        # 光栅化器：PNG 结构 + inflate 回像素断言 + 真实渲染器子集检查
 node test/svgio.mjs         # 共享绘图助手：几何手算值 + 每种助手拼一张文档后光栅化必须干净
 node test/charts.mjs        # 图表：CSV/TSV 读取层 + 八种图表（含色带）的统计量与光栅化
 node test/client.mjs        # 客户端产物：按加载器方式执行 + 面板数据通路（无浏览器）
 node test/panel-render.mjs  # 面板组件：最小钩子宿主里跑真实组件（无 React、无 DOM）
-node test/map-card.mjs      # 图谱调用卡：跨界 meta 投影断言
+node test/map-card.mjs      # 调用卡（图谱 + logo/gRNA）：跨界 meta 投影断言
 node test/client-mount.mjs  # 客户端挂载：复刻宿主侧图扫描，核对 web profile 的行与依赖
 node test/contract.mjs      # DSH 契约：官方是否改了规则或 API
 node test/preset-health.mjs # 组合：逐行按该包自己的 Config schema 校验 preset 可挂载性
@@ -50,7 +50,7 @@ node benchmark/run.mjs --offline # benchmark 的期望值是否仍等于工具
 
 ### 各套件到底在防什么
 
-- **`smoke.mjs`** 证明**插件**可用：mock 注册表运行全部 60 个工具，并用 harness 自身的
+- **`smoke.mjs`** 证明**插件**可用：mock 注册表运行全部 64 个工具，并用 harness 自身的
   `assertSupportedJsonSchema` / `validateJsonSchemaValue` 校验每个输出 schema 与返回值；
   覆盖已知值用例（EcoRI 酶切、ΔΔCt=-3 → fold 8、GenBank/SnapGene 解析、引物对一致性、
   SVG 文件写入与无旋转标签断言、克隆模拟手算序列比对、合成 ABIF 夹具、环状参考跨原点
@@ -218,7 +218,7 @@ benchmark 不是"每天跑一遍"的门禁，而是**行为的验收测试**—
 
 | 这次改了什么 | benchmark 要不要动 | 为什么 |
 | --- | --- | --- |
-| 新增一个工具 | **必须**：加任务 + `verifications.mjs` 的 invocation | `test/benchmark-coverage.mjs` 会**直接 FAIL**（`60/60 tools covered` 是断言） |
+| 新增一个工具 | **必须**：加任务 + `verifications.mjs` 的 invocation | `test/benchmark-coverage.mjs` 会**直接 FAIL**（`64/64 tools covered` 是断言） |
 | 改工具的参数、默认值、输出字段、渲染文本 | **必须**：更新受影响任务的断言，重跑 `--offline`，再重跑该任务 | 断言比对的是**渲染文本**，改了文本就改了对错 |
 | 改工具的描述或参数说明（prompt 面） | **必须**：重跑对应任务 | 这正是 benchmark 唯一能测的东西——模型是否还选得对 |
 | 改 `preset/molbio-lab/agent.cordis.yml`（行清单） | **必须**：先 `node test/benchmark-profile.mjs`，再重建 profile | 行清单变了，benchmark 的 headless profile 是**推导**出来的，守卫会 FAIL |
@@ -237,7 +237,7 @@ benchmark 不是"每天跑一遍"的门禁，而是**行为的验收测试**—
 
 ```bash
 node benchmark/run.mjs --offline    # 每条 where:"tool" 断言是否仍等于工具的真实渲染输出
-node test/benchmark-coverage.mjs    # 60/60 工具有任务覆盖、fixture 前提仍成立、tier 与占位符健全
+node test/benchmark-coverage.mjs    # 64/64 工具有任务覆盖、fixture 前提仍成立、tier 与占位符健全
 node test/benchmark-score.mjs       # 判分器对冻结的真实响应仍判对，且仍能判错
 ```
 
@@ -254,7 +254,7 @@ offline 证明"期望值仍然为真"，model 测量"模型是否仍然会用"
 | 改了**几个**工具 | `--tools a,b,c`（也接受 `molbio_` 前缀与 `primer_*` 通配） | 并集 |
 | 改了**一个**已知任务 | `--task <id>` | 一题 |
 | 改了**共享模块**，想知道影响面 | `--list --changed`（不花钱） | 0 |
-| 发版前 | `node --run bench:full` | 61 题 |
+| 发版前 | `node --run bench:full` | 65 题 |
 | 只是提交文档 | `--changed` 会回答"无事可跑" | 0 |
 
 ```bash
@@ -299,7 +299,7 @@ $ touch lib.mjs && node benchmark/run.mjs --list --changed
 1. **不可判定 → 全量**：没有 git / 没有 HEAD / 读不到插件结构，一律回落全量并打印原因；
 2. **认不出的文件 → 全量**：新模块、重命名的文件（`not in the plugin's module set`）；
 3. **`index.mjs` → 全量**：它是绑定全部工具的那个入口；
-4. **映射到的工具有题没覆盖 → 全量**（并由 `test/benchmark-coverage.mjs` 断言 60/60 覆盖）。
+4. **映射到的工具有题没覆盖 → 全量**（并由 `test/benchmark-coverage.mjs` 断言 64/64 覆盖）。
 
 反过来，**唯一会返回"无事可跑"的情况**是改动**可证明**不影响工具行为：`docs/`、
 `CHANGELOG.md`、`README.md`、`test/`、`benchmark/`、`package.json`。这不是走后门——
@@ -363,7 +363,7 @@ node test/client.mjs && node test/panel-render.mjs && node test/map-card.mjs &&
 两条实现纪律：投影**必须廉价且不抛**（它跑在调用成功之后，抛错会把这次调用标成失败；
 图谱标记因此走一份有界内存缓存而不是读文件），卡片**必须校验而非信任** meta（缺失/异种/
 异形/超限/失败一律降级为提示，绝不在对话里抛错）。新增卡片时：把工具名加进
-`build/client-entry.mjs` 的 `MAP_TOOL_KEYS`，并在 `test/map-card.mjs` 里补一条跨界断言。
+`build/client-entry.mjs` 的 `MAP_TOOL_KEYS`（图谱）或 `FIGURE_TOOL_KEYS`（图形），并在 `test/map-card.mjs` 里补一条跨界断言。
 另注意 `define()` 包装器会转发 `presentationMeta`——若哪天再包一层，别忘了这条。
 
 ### 安装与修复面板
@@ -456,7 +456,7 @@ git status --short           # lib/client.js 与 packages/molbio-panel/lib/clien
 ### DSH 升级后：preset 组合的维护（必做）
 
 `preset/molbio-lab/agent.cordis.yml` 是官方 `standard` 预设的**行清单**副本 + 末尾一行
-`tool-molbio`（当前基线：**dsh 0.2.1-rc.5**）。它不会自动跟随 DSH 升级，因此每次升级
+`tool-molbio`（当前基线：**dsh 0.2.2-rc.1**）。它不会自动跟随 DSH 升级，因此每次升级
 DSH 后：
 
 1. 取新版的 shipped `standard`：
@@ -469,7 +469,8 @@ DSH 后：
    只比结构，注释漂移抓不住，但下一次人工 diff 会；
 3. 跑 `node build/preset-patch.mjs` 重新生成根目录的 `cordis.patch.yml`；
 4. 跑 `node test/preset-health.mjs` 直到 `OK`（它把任何结构差异当**发布阻断**，不只是打印
-   note），再跑 `node test/drift-probe.mjs` 确认守卫仍能抓到漂移；
+   note；它还会按 Loader 的方式解析每个行名，上游删掉的子路径会在这里直接 FAIL），
+   再跑 `node test/drift-probe.mjs` 确认守卫仍能抓到漂移；
 5. 更新 `agent.cordis.yml` 头部"Baseline: …"那行里的 DSH 版本号；
 6. 跑 `node test/benchmark-profile.mjs`：benchmark 的 headless profile 是从这份行清单**推导**
    出来的，上游加行、改 config 都会在这里失败（它会把每一行逐字段比对），按提示把新行分类

package/dotplot.mjs

@@ -0,0 +1,257 @@
+/**
+ * dsh-molbio-tools/dotplot.mjs
+ *
+ * Self-comparison dotplot by exact word matching: a dot at (i, j) means the
+ * k-mer starting at i equals the k-mer starting at j (direct repeat), and a red
+ * dot means it equals the reverse complement of the k-mer at j (inverted
+ * repeat). Pure computation; the SVG is binned into a fixed pixel grid so a
+ * repetitive sequence cannot produce a million-element document.
+ *
+ * Deliberately NOT a window/identity dotplot (EMBOSS dotmatcher-style): this is
+ * the k-mer view, which is exact, deterministic and needs no scoring matrix.
+ */
+import { MolbioInputError, normalizeSequence } from './lib.mjs';
+import { axis, linearScale, niceTicks, panel, rect, svgDocument, textRun } from './svgio.mjs';
+
+/** Accepted ranges and work caps. */
+export const DOTPLOT_LIMITS = {
+  minWord: 4,
+  maxWord: 12,
+  maxLength: 20_000,
+  maxPairs: 200_000,
+  maxCells: 60_000,
+  grid: 400,
+};
+
+const round = (value, digits = 3) => Math.round(value * 10 ** digits) / 10 ** digits;
+
+/** Reverse complement of one canonical k-mer (A/C/G/T only). */
+function rcWord(word) {
+  let out = '';
+  for (let index = word.length - 1; index >= 0; index--) {
+    const base = word[index];
+    out += base === 'A' ? 'T' : base === 'C' ? 'G' : base === 'G' ? 'C' : 'A';
+  }
+  return out;
+}
+
+/**
+ * Compute the self-comparison dotplot.
+ *
+ * @param {string} raw DNA sequence (IUPAC; ambiguous k-mers are skipped).
+ * @param {{word?: number, mode?: 'direct'|'inverted'|'both', grid?: number}} [options]
+ * @returns {{length: number, word: number, mode: string, direct_matches: number,
+ *   inverted_matches: number, direct_cells: number, inverted_cells: number,
+ *   ambiguous_bases: number, truncated: boolean, plot_truncated: boolean,
+ *   grid: number, directGrid: Set<number>, invertedGrid: Set<number>}}
+ */
+export function dotplot(raw, options = {}) {
+  const sequence = normalizeSequence(raw, 'sequence');
+  if (sequence.length > DOTPLOT_LIMITS.maxLength) {
+    throw new MolbioInputError('the sequence is ' + sequence.length + ' bp; the dotplot limit is ' + DOTPLOT_LIMITS.maxLength + ' bp');
+  }
+  const word = options.word ?? 8;
+  if (!Number.isInteger(word) || word < DOTPLOT_LIMITS.minWord || word > DOTPLOT_LIMITS.maxWord) {
+    throw new MolbioInputError('word must be an integer between ' + DOTPLOT_LIMITS.minWord + ' and ' + DOTPLOT_LIMITS.maxWord);
+  }
+  if (sequence.length < word * 2) {
+    throw new MolbioInputError('the sequence is ' + sequence.length + ' bp; at word ' + word + ' it needs at least ' + word * 2 + ' bp to show a repeat');
+  }
+  const mode = options.mode ?? 'both';
+  if (!['direct', 'inverted', 'both'].includes(mode)) {
+    throw new MolbioInputError('mode must be "direct", "inverted" or "both"');
+  }
+  const grid = options.grid ?? DOTPLOT_LIMITS.grid;
+  if (!Number.isInteger(grid) || grid < 50 || grid > 1000) {
+    throw new MolbioInputError('grid must be an integer between 50 and 1000');
+  }
+
+  const index = new Map();
+  let ambiguousBases = 0;
+  for (let start = 0; start + word <= sequence.length; start++) {
+    const wordText = sequence.slice(start, start + word);
+    let canonical = true;
+    for (const base of wordText) {
+      if (base !== 'A' && base !== 'C' && base !== 'G' && base !== 'T') {
+        canonical = false;
+        break;
+      }
+    }
+    if (!canonical) {
+      ambiguousBases++;
+      continue;
+    }
+    const list = index.get(wordText);
+    if (list === undefined) index.set(wordText, [start]);
+    else list.push(start);
+  }
+
+  const length = sequence.length;
+  const cellOf = (position) => Math.min(grid - 1, Math.floor((position / length) * grid));
+  const directGrid = new Set();
+  const invertedGrid = new Set();
+  let directMatches = 0;
+  let invertedMatches = 0;
+  let truncated = false;
+  let plotTruncated = false;
+  let work = 0;
+
+  const addCell = (set, x, y) => {
+    const key = x * 4096 + y;
+    if (set.has(key)) return;
+    // Bound the RENDERED cells, not just the match count: a dense plot must not
+    // produce a document with one <rect> per match.
+    if (directGrid.size + invertedGrid.size >= DOTPLOT_LIMITS.maxCells) {
+      plotTruncated = true;
+      return;
+    }
+    set.add(key);
+  };
+
+  outer: for (const [wordText, positions] of index) {
+    if (mode === 'direct' || mode === 'both') {
+      for (let a = 0; a < positions.length; a++) {
+        for (let b = 0; b < positions.length; b++) {
+          if (work >= DOTPLOT_LIMITS.maxPairs) {
+            truncated = true;
+            break outer;
+          }
+          work++;
+          directMatches++;
+          addCell(directGrid, cellOf(positions[a]), cellOf(positions[b]));
+        }
+      }
+    }
+    if (mode === 'inverted' || mode === 'both') {
+      const rc = rcWord(wordText);
+      if (rc === wordText) continue; // a palindromic word would double-count the same pairs
+      const rcPositions = index.get(rc);
+      if (rcPositions === undefined) continue;
+      for (const from of positions) {
+        for (const to of rcPositions) {
+          if (work >= DOTPLOT_LIMITS.maxPairs) {
+            truncated = true;
+            break outer;
+          }
+          work++;
+          invertedMatches++;
+          addCell(invertedGrid, cellOf(from), cellOf(to));
+        }
+      }
+    }
+  }
+
+  return {
+    length,
+    word,
+    mode,
+    direct_matches: directMatches,
+    inverted_matches: invertedMatches,
+    direct_cells: directGrid.size,
+    inverted_cells: invertedGrid.size,
+    ambiguous_bases: ambiguousBases,
+    truncated,
+    plot_truncated: plotTruncated,
+    grid,
+    directGrid,
+    invertedGrid,
+  };
+}
+
+/**
+ * Render a computed dotplot as an SVG document. The grid is binned: one
+ * `<rect>` per occupied cell, so the document size is bounded by the grid, not
+ * by the number of matches.
+ *
+ * @param {ReturnType<typeof dotplot>} data
+ * @param {{title?: string}} [options]
+ * @returns {string} SVG text.
+ */
+export function renderDotplot(data, options = {}) {
+  const width = 720;
+  // The x axis needs a title line BELOW its tick labels, and the legend needs a
+  // home INSIDE the panel. At 720 px the plot was 628 px square and the title /
+  // legend fell on (or outside) the bottom border; 760 px keeps the plot square
+  // (same 628 px) while giving both a row of their own. `bottom: 66` is what
+  // preserves that square: 728 (frame) - 34 (top) - 66 = 628.
+  const height = 760;
+  const frame = panel({
+    x: 16,
+    y: 16,
+    width: width - 32,
+    height: height - 32,
+    inset: { top: 34, right: 14, bottom: 66, left: 46 },
+    title: options.title ?? 'Sequence dotplot',
+    subtitle: data.length + ' bp · word ' + data.word + ' · ' + data.mode + ' · ' + data.direct_matches + ' direct / ' + data.inverted_matches + ' inverted match(es)'
+      + (data.truncated ? ' · scan capped' : '') + (data.ambiguous_bases > 0 ? ' · ' + data.ambiguous_bases + ' ambiguous k-mer(s) skipped' : ''),
+  });
+  const plot = frame.plot;
+  const x = linearScale([1, data.length], [plot.x, plot.x + plot.width]);
+  const y = linearScale([1, data.length], [plot.y + plot.height, plot.y]);
+  const cellWidth = plot.width / data.grid;
+  const cellHeight = plot.height / data.grid;
+  const parts = [frame.markup];
+  const drawCells = (set, fill, opacity) => {
+    const cells = [];
+    for (const key of set) {
+      const cx = Math.floor(key / 4096);
+      const cy = key - cx * 4096;
+      cells.push(rect({
+        x: round(plot.x + cx * cellWidth, 2),
+        y: round(plot.y + cy * cellHeight, 2),
+        width: Math.max(1, round(cellWidth, 2)),
+        height: Math.max(1, round(cellHeight, 2)),
+        fill,
+        fillOpacity: opacity,
+      }));
+    }
+    return cells.join('\n');
+  };
+  if (data.invertedGrid.size > 0) parts.push(drawCells(data.invertedGrid, '#cf222e', 0.55));
+  if (data.directGrid.size > 0) parts.push(drawCells(data.directGrid, '#24292f', 0.7));
+  parts.push(axis({
+    from: plot.x,
+    to: plot.x + plot.width,
+    at: plot.y + plot.height,
+    ticks: niceTicks([1, data.length], 6).map((tick) => x.of(tick)),
+    orientation: 'x',
+    tickLabel: (pixel) => String(Math.round(x.invert(pixel))),
+    title: 'position (bp)',
+  }));
+  parts.push(axis({
+    from: plot.y,
+    to: plot.y + plot.height,
+    at: plot.x,
+    ticks: niceTicks([1, data.length], 6).map((tick) => y.of(tick)),
+    orientation: 'y',
+    tickLabel: (pixel) => String(Math.round(y.invert(pixel))),
+    title: 'position (bp)',
+  }));
+  parts.push(legend(data));
+  return svgDocument({
+    width,
+    height,
+    title: options.title ?? 'Sequence dotplot',
+    description: 'Exact ' + data.word + '-mer self-comparison of a ' + data.length + ' bp sequence; black cells are direct repeats, red cells are inverted repeats.',
+    body: parts.join('\n'),
+  });
+}
+
+/** A compact legend; omitted when the corresponding mode produced no cells. */
+function legend(data) {
+  const entries = [];
+  // Only label a class that was actually computed AND has dots: in
+  // inverted-only mode a black "direct repeat" key would claim a measurement
+  // that never ran.
+  if (data.directGrid.size > 0) entries.push(['#24292f', 'direct repeat']);
+  if (data.invertedGrid.size > 0) entries.push(['#cf222e', 'inverted repeat']);
+  let x = 28;
+  const y = 730;
+  const parts = [];
+  for (const [color, label] of entries) {
+    parts.push(rect({ x, y: y - 8, width: 9, height: 9, fill: color }));
+    parts.push(textRun({ x: x + 13, y, text: label, size: 9, fill: '#57606a' }));
+    x += 130;
+  }
+  return parts.join('\n');
+}

package/fastq-qc.mjs

@@ -28,6 +28,11 @@
  */
 
 import { MolbioInputError } from './lib.mjs';
+import { ADAPTERS } from './contamination.mjs';
+
+// Re-exported for callers that used this module's adapter table directly. The
+// table now lives in contamination.mjs and is DNA-normalized there.
+export { ADAPTERS } from './contamination.mjs';
 import {
   axis,
   escapeXml,
@@ -63,15 +68,7 @@ export const FASTQ_QC_DEFAULTS = {
   duplication_bins: 10,
 };
 
-/** Public adapter/primer fragments used for the adapter-content screen. */
-export const ADAPTERS = [
-  { name: 'Illumina Universal', sequence: 'AGATCGGAAGAG' },
-  { name: 'Illumina Small RNA 3\'', sequence: 'TGGAATTCTCGG' },
-  { name: 'Illumina Small RNA 5\'', sequence: 'GUUCAGAGUUCUACAGUCCGACGAUC' },
-  { name: 'Nextera Transposase', sequence: 'CTGTCTCTTATA' },
-  { name: 'PolyA', sequence: 'AAAAAAAAAAAA' },
-  { name: 'PolyG', sequence: 'GGGGGGGGGGGG' },
-];
+/** Public adapter/primer fragments: see contamination.mjs (DNA-normalized). */
 
 /** Phred+33 decoding, with the offending read id in the message. */
 function phredOf(character) {
@@ -118,7 +115,10 @@ function entropyOf(counts) {
  * that tapers is not mistaken for a quality drop.
  */
 function perPosition(entries, maxBases) {
-  const longest = Math.max(...entries.map((entry) => entry.sequence.length));
+  // A loop, not Math.max(...lengths): a 200k-read run is within the supported
+  // cap and would otherwise overflow the argument limit with a RangeError.
+  let longest = 0;
+  for (const entry of entries) if (entry.sequence.length > longest) longest = entry.sequence.length;
   const length = Math.min(longest, maxBases);
   const rows = [];
   for (let position = 0; position < length; position++) {
@@ -414,9 +414,24 @@ export function fastqQcReport(entries, options = {}) {
   }
 
   const perBase = perPosition(selected, settings.max_plot_bases);
-  const summaryQualities = selected.flatMap((entry) => [...entry.quality].map(phredOf));
-  const q20 = summaryQualities.filter((value) => value >= 20).length;
-  const q30 = summaryQualities.filter((value) => value >= 30).length;
+  // One streaming pass over the qualities. The previous version materialised
+  // every Phred score of every sampled read in one array (200k reads x 150 bp
+  // is 30 million numbers) and then filtered it twice; the counters need none
+  // of that memory, and the statistics are unchanged.
+  let qualitySum = 0;
+  let qualityCount = 0;
+  let q20 = 0;
+  let q30 = 0;
+  for (const entry of selected) {
+    for (const character of entry.quality) {
+      const value = phredOf(character);
+      qualitySum += value;
+      qualityCount++;
+      if (value >= 20) q20++;
+      if (value >= 30) q30++;
+    }
+  }
+  if (qualityCount === 0) throw new MolbioInputError('the FASTQ reads contain no quality values');
   const gcCount = selected.reduce((sum, entry) => {
     let gc = 0;
     for (const base of entry.sequence) if (base === 'G' || base === 'C') gc++;
@@ -444,9 +459,9 @@ export function fastqQcReport(entries, options = {}) {
     gc_percent: Math.round(gcFraction * 10000) / 100,
     n_bases: nCount,
     n_percent: Math.round((nCount / allBases) * 10000) / 100,
-    quality_mean: Math.round(mean(summaryQualities) * 100) / 100,
-    quality_q20_percent: Math.round((q20 / summaryQualities.length) * 10000) / 100,
-    quality_q30_percent: Math.round((q30 / summaryQualities.length) * 10000) / 100,
+    quality_mean: Math.round((qualitySum / qualityCount) * 100) / 100,
+    quality_q20_percent: Math.round((q20 / qualityCount) * 10000) / 100,
+    quality_q30_percent: Math.round((q30 / qualityCount) * 10000) / 100,
     quality_tail_below_30: tailPosition(perBase, 30),
     quality_tail_below_20: tailPosition(perBase, 20),
     per_base: perBase,