# DIY Transcriptomics - Project Engineering Rules ## 1. WebR Package Tier Architecture & Isolation Rules When developing or modifying WebR engine scripts (`js/src/webr/webr-engine.js`, `step-catalog.js`): ### Tier 1: WebAssembly CRAN Packages (Native WASM) * **Packages:** `tidyverse` (readr, dplyr, ggplot2, tidyr, tibble, purrr, stringr), `plotly`, `gt`, `DT`, `pheatmap`, `RColorBrewer`, `cowplot`, `matrixStats`, `jsonlite`, `scales`, `base64enc`, `hexbin`. * **Invariants:** 1. **NEVER** add these packages to `desktopShimmed` in `ensurePackages()`. 2. **NEVER** add these packages to `webr_shims$desktop_pkgs`. 3. **NEVER** assign functions from these packages directly to `.GlobalEnv` (e.g. `assign("gt", ...)`, `assign("ggplotly", ...)`, `assign("datatable", ...)`). Assigning to `.GlobalEnv` masks genuine attached packages in R's search path. 4. Always declare them in `requiredPackages` in `js/src/webr/step-catalog.js` for steps that utilize them (e.g. `step-2`, `step-3`, `step-5`). 5. S3 print hooks (`print.gt_tbl`, `print.plotly`, `print.datatables`) must intercept genuine package objects and emit delimited markers (`---WEBR_HTML_VIEWER_START---`, `---WEBR_PLOTLY_START---`, `---WEBR_DATATABLE_START---`) to render authentic aesthetics in the **Viewer** pane. ### Tier 2: Desktop-Only Dependencies (Curated Shims) * **Packages:** `edgeR`, `limma`, `rhdf5`, `tximport`, `ensembldb`, `EnsDb.Hsapiens.v86`, `biomaRt`, `slinky`, `csaw`, `gameofthrones`, `d3heatmap`, `msigdbr`, `clusterProfiler`, `DropletUtils`, `Seurat`, `scater`, `scran`, `SingleR`, `celldex`, `Azimuth`, `SingleCellExperiment`. * **Invariants:** 1. Shimmed because they depend on multi-gigabyte Bioconductor databases or native C++ compilation unavailable in the browser. 2. Maintained with mathematical parity against native R packages using pre-computed course artifacts and zero-dependency algorithms. ### Tier 3: Search Path Isolation for Fallback Shims * All fallback implementations must reside inside the `webr_shims` environment, which is attached to the search path (`attach(webr_shims, name = "webr_shims")`). * This ensures that whenever a real package is loaded (`library(plotly)`), `package:plotly` at `pos = 2` automatically takes precedence over `webr_shims`. --- ## 2. Mandatory Documentation Policy * **Every modification to shims, rendering logic, or WebR data handling MUST be documented in [`docs/WEBR_SHIMS_ARCHITECTURE.md`](file:///Users/danielbeiting/github/DIYtranscriptomics.github.io/docs/WEBR_SHIMS_ARCHITECTURE.md).** * Keep the shim inventory numbers and behavioral descriptions up to date. --- ## 3. Build & Test Verification Gate * Before completing any changes, run: ```bash npm run build && bundle exec jekyll build ``` * `npm run build` runs `scripts/verify-webr-architecture.js`, which automatically validates: - R code template syntax via `parse()`. - Absence of Tier 1 WASM packages in `desktopShimmed` and `desktop_pkgs`. - Absence of `.GlobalEnv` shadowing for Tier 1 functions. - Presence of required packages in `step-catalog.js`. - Integrity of S3 print hooks and HTML viewer filters.