[prete]

Summary

CELLxGENE H5ADs store /var/feature_name as a categorical group (codes + categories, encoding-type "categorical"). readGeneNames only accepted plain string datasets, so those files listed genes by the var index. The Census Visium adult heart (fe5b3268-ddd8-415a-9432-f1f95bfdb500, 32,397 genes, 32,381 categories) showed only ENSG IDs, and searching MYH7 or NPPA found nothing.

• Gene names: readGeneNames decodes categorical groups and legacy /var/__categories/<key> sidecars as well as string datasets. The rules are unchanged: the first of gene_symbols, gene_symbol, feature_name, name with one value per gene and at least one non-empty value replaces the index, missing codes become var-N, and duplicates get -2, -3 suffixes (16 genes in the heart file). A legacy sidecar used to fail the whole load ("Expected H5AD /var/feature_name to contain strings."). The obs readers now share the categorical helpers. The h5wasm, kerchunk-reference and SpatialData table backends all use this path.
• Ensembl IDs as aliases: when a column replaces the index, each gene's index name is kept as an alias (geneAliases() on the H5AD and SpatialData datasets, aliases on the ready gene-panel state). The Gene selection search and Gene set symbols match aliases, and the gene list tooltip shows them (MYH7 (ENSG00000092054)). Selections, shared links and manifest defaults.genes use the listed names only, so an older link with genes=ENSG… no longer colours these files.
• Docs: docs/modalities/h5ad.md, docs/host-your-own-data.md, docs/ui-reference.md.

Test plan

• New unit tests: categorical feature_name as a group and as a legacy sidecar (h5wasm) and over a kerchunk reference; missing and duplicate codes; all-missing codes falling back to the index; index-only files having no aliases; alias search, gene-set parsing, tooltip, lifecycle plumbing. The categorical tests fail against the old reader.
• npm run lint, npm run typecheck, npx prettier --check .
• npm test. Two failures in the full run were unrelated: the App.test.tsx 50k-cell "all slide cells" test (timed out under load, passes alone) and hyparquetBitPacked.test.ts (that worktree's node_modules predated the hyparquet patch; passes after npx patch-package).
• Browser, dev server, Census heart H5AD: 32,397 genes, MYH7 listed and selectable (2,571 positive of 4,992 spots, scale 0–4.55), ensg00000175206 finds NPPA, no console errors.

Follow-up: #20 can then default the heart example to MYH7.