---
title: "The Shiny workbench"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{The Shiny workbench}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files:
  - figures/logo.svg
  - figures/logo-dark.svg
---

<!-- cttir-vignette-logo: start -->
<style>
.cttir-vignette-logo { float: right; width: 120px; max-width: 30%; margin: 0 0 1rem 1.5rem; }
.cttir-vignette-logo img { width: 100%; height: auto; border: 0; background: transparent; box-shadow: none; }
.cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
.cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
@media (prefers-color-scheme: dark) {
  .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
  .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
}
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
</style>
<div class="cttir-vignette-logo">
  <img class="cttir-vignette-logo-light" src="figures/logo.svg" alt="hypermodR logo" width="120" height="139" />
  <img class="cttir-vignette-logo-dark" src="figures/logo-dark.svg" alt="hypermodR logo" width="120" height="139" />
</div>
<!-- cttir-vignette-logo: end -->

```{r setup, include=FALSE}
library(hypermodR)
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", error = FALSE)
```
The workbench uses the same R objects and numerical functions. Its synthetic
example predicts continuous response with subject-grouped folds. Opening the
app does not install runtimes or download weights.

```{r app-state}
state <- hm_app_state()
if (!isTRUE(all(identical(state$status, "empty")))) {
  cli::cli_abort("Example assertion failed.", class = "hm_example_error")
}
x <- hm_example()
if (!isTRUE(all(methods::validObject(x)))) {
  cli::cli_abort("Example assertion failed.", class = "hm_example_error")
}
```

```{r launch, eval=FALSE}
hm_app(launch = TRUE, host = "127.0.0.1", port = NULL)
```

Use `hm_app(launch = FALSE)` to construct a `shiny.appobj` without starting a
server. Import an RDS `HMDataset`/`HMSequence` or start with the synthetic example, inspect wavelength and grouping metadata,
choose the supported task/model and training recipe, run, inspect the held-out
metrics, and export the reproducible configuration/results. A changed input or
configuration invalidates stale results. Keep subject IDs in split metadata;
individual spectra are not independent biological units.

Uploads are limited to 50 MiB while the app runs; stopping it restores the
previous Shiny upload limit. Use only trusted RDS files. Bounded fitting and
runtime setup require Linux with `taskset`, `prlimit` and `timeout`. On other
hosts the workbench shows this limitation before configuration and disables
those actions. Import, inspection and configuration remain available; use the
ordinary `hm_fit()` API for local R models.

`hm_submit_job()` starts an owned background job; `hm_job_status()` inspects it
and `hm_cancel_job()` cancels that owned job. `hm_export_result()` writes a new
export directory. Default exports omit individual-level data; private exports
require an explicit request. Read persisted package runs with `hm_read_run()`
and reproduce their task/workflow/split in an R script.
The export becomes complete only after its reproduction script and optional
private model files are written. A failed export keeps its reserved directory
for inspection and cannot be read as complete; retry with a new directory.

UI/server tests and real browser workflows are separate evidence. Full keyboard,
focus, both colour modes, narrow layout, cancellation/recovery, two-session
isolation and app-to-script equality must be inspected in a real browser before
claiming browser qualification. Optional app dependencies are Shiny, bslib,
callr and processx. The shared website uses themakR; the app uses bslib directly.

The current workbench supports grouped regression/classification with R engines.
Prepare ROI reductions through the API before import; an interactive annotation
editor is outside this workbench. Runtime metadata resolution, terms review and
installation are explicit user actions.
Each new runtime resolution clears the terms checkbox. Review its displayed
notices and check it again before installing; review of an earlier resolution
does not authorize the new set of artifacts.