Add JSON parameter files and complete the GUI workflow (#287)

.gitattributes

@@ -0,0 +1,3 @@
+# Keep the third-party parser separate in reviews and preserve upstream bytes.
+src/bin/nlohmann/json.hpp linguist-vendored
+src/bin/nlohmann/LICENSE.MIT linguist-vendored -whitespace

.github/workflows/build-wasm.yml

@@ -35,7 +35,7 @@ jobs:
           python scripts/wasm/test-downloads.py
           python scripts/wasm/test-vienna-release.py
       - name: Test input, worker lifecycle and CSV handling
-        run: npm test --prefix webinterface
+        run: npm test --prefix gui
       - name: Resolve newest stable ViennaRNA 2.x release and checksum
         env:
           GITHUB_TOKEN: ${{ github.token }}
@@ -68,7 +68,7 @@ jobs:
           python scripts/wasm/test-browser.py http://127.0.0.1:8765/site/ --browser firefox
       - uses: actions/upload-artifact@v4
         with:
-          name: intarna-webinterface
+          name: intarna-gui
           path: build-wasm/site
           if-no-files-found: error
 
@@ -82,14 +82,14 @@ jobs:
           path: _site
       - uses: actions/download-artifact@v4
         with:
-          name: intarna-webinterface
-          path: _site/webinterface
+          name: intarna-gui
+          path: _site/gui
       - name: Verify documentation and browser interface coexist
         run: |
           test -s _site/index.html
           test -s _site/api/index.html
-          test -s _site/webinterface/index.html
-          test -s _site/webinterface/wasm/intarna.wasm
+          test -s _site/gui/index.html
+          test -s _site/gui/wasm/intarna.wasm
       - uses: actions/upload-artifact@v4
         with:
           name: intarna-pages-preview

.gitignore

@@ -85,7 +85,7 @@ python/intarnapvalue.*
 
 # Browser build outputs and local test dependencies
 /build-wasm/
-/webinterface/wasm/
-/webinterface/node_modules/
+/gui/wasm/
+/gui/node_modules/
 
 /scripts/wasm/__pycache__/

ChangeLog

@@ -14,6 +14,35 @@
 
 ## Interface and handling
 
+- reorganize GUI parameters, add conditional seed/accessibility controls and
+  grouped CSV defaults, expand FASTA limits and refine result headers (PR #299)
+
+- retain computed GUI runs as named, foldable sessions with JSON input restoration,
+  independent outputs, per-session ZIP export and deletion (PR #297 review)
+
+- permit clearing inherited CSV sorting when replaying JSON as text reports;
+  validate JSON/GUI behavior in native release/debug and real browsers (#287)
+
+- show prediction/evaluation tasks as always-visible choices with task-specific
+  descriptions and an expanded Seeds/Accessibility heading (PR #287 review)
+
+- upload or drop local FASTA files into each GUI strand with validation and
+  protection against stale asynchronous reads (PR #287 review)
+
+- clear all inputs on GUI reset and load named examples from maintainable JSON
+  files through an Example menu (PR #287 review)
+
+- load/store GUI settings as portable JSON; ZIPs contain parameter.json with
+  embedded inputs/provenance and all outputs (PR #287 review)
+
+- use one embedded-input JSON parameter document for each WASM invocation
+  (PR #287 review)
+
+- accept JSON parameter files with embedded text inputs and personality defaults
+  through --parameterFile while retaining legacy configuration (PR #287 review)
+
+- rename the browser interface directory and Pages URL to gui (PR #287 review)
+
 - add selected-interaction vaRRI embeds and reproducible all-output ZIP downloads
   to the browser interface; compact parameters into accessible tabs and update
   the Freiburg group header and full-width result/footer notes (PR #287 review)
@@ -84,6 +113,9 @@
 
 ## Technical changes and Optimizations
 
+- record JSON/WASM/browser regression validation and preserve pinned JSON vendor
+  checksums while marking upstream files as vendored for review (PR #287)
+
 - build WASM with ViennaRNA 2.7.2 locally and the newest stable 2.x in CI;
   verify published archive checksums, isolate versioned caches and retain
   selected dependency provenance and notices (PR #292 review)
@@ -253,6 +285,115 @@ energies, restricted partition sums, and trackers.
 ################################################################################  
 ################################################################################
 
+261024 Alexander Mitrofanov
+ * gui/{app,options,columns}.js, gui/{index.html,styles.css}
+   * organize tabs/rows as Sequences, Seed, Output, Model & Energy, Query,
+     Target and CLI-only; align wrapped labels and place Compute first
+   + add a three-way seed selector, synchronized accessibility flags and
+     mode-dependent input availability; place SHAPE beside accessibility
+   * group compact CSV choices with descriptions and group selection actions;
+     default to 10 predictions and expanded task-specific energy columns,
+     explicitly preserving browser defaults in native-compatible JSON
+ * gui/{protocol,uploads,parameter-file}.js, gui/examples/
+   * accept 50 FASTA records per strand of 2-5,000 nt each, with longest
+     selected query x longest selected target <= 1,000,000; allow 1 MB FASTA
+   + warn about ignored FASTA header descriptions while using first-token IDs
+ * gui/{sessions,results}.js
+   * select results from the header/name, order Show/Hide before the name and
+     ZIP/delete actions, compact table headings and distinguish selected rows
+ * gui/tests/, scripts/wasm/test-browser.py, README.md, gui/docs/
+   + cover limits, native JSON replay/defaults, dependent controls, grouped CSV
+     choices, desktop/mobile alignment and result header selection
+   * address https://github.com/BackofenLab/IntaRNA/pull/299#issuecomment-6375752155
+
+261023 Alexander Mitrofanov
+ * gui/{app,sessions,results,visualization}.js, gui/{index.html,styles.css}
+   + retain successful runs in browser memory with unique IDs, editable names,
+     independent results/diagnostics and JSON snapshots of their computed inputs
+   * restore inputs and fold other output areas on selection; preserve sessions
+     across edits, reset, imports, failures and aborts; unload folded viewers
+   + export each session's original JSON/outputs from its header and delete it
+     without overwriting editable inputs; keep controls keyboard accessible
+ * scripts/wasm/{stage.sh,test-browser.py}, README.md, gui/docs/
+   * stage the sessions module, exercise session lifetime and archive isolation
+     in real browsers, and document temporary storage and updated reset behavior
+   * follow-up to https://github.com/BackofenLab/IntaRNA/pull/297#issuecomment-6367326708
+
+261023 Alexander Mitrofanov
+ * .gitattributes, gui/docs/json-workflow.md
+     + Preserve exact upstream license whitespace and mark the JSON header and
+       license as vendored. Record native release/debug, WASM replay, browser,
+       distribution and provenance validation for the PR #287 revisions.
+
+261023 Alexander Mitrofanov
+ * src/bin/CommandLineParsing.cpp, ParameterFile.h, tests/testParameterFile.py
+     * Accept an explicitly empty CSV sort value to clear a parameter-file
+       setting when reproducing non-CSV reports from the same JSON document.
+ * gui/app.js, gui/styles.css, scripts/wasm/test-browser.py
+     * Keep pending auxiliary-file reads from restoring reset inputs, return
+       Reset to Sequence input and make the entire task label clickable.
+ * doc/{Makefile.am,json-parameters.md}
+     + Include JSON format documentation in source distributions and record the
+       observed WASM footprint and reproducible dependency comparison (#287).
+
+261023 Alexander Mitrofanov
+ * gui/{index.html,app.js,styles.css}, scripts/wasm/test-browser.py
+     * Replace the task dropdown with visible, highlighted native radio choices
+       and task descriptions; update the heading to include Seeds/Accessibility.
+     * Keep Example, Reset, Load and Store adjacent and test keyboard selection
+       and responsive layout (PR #287 review).
+
+261023 Alexander Mitrofanov
+ * gui/{uploads.js,app.js,index.html,styles.css}, gui/docs/json-workflow.md
+     + Add Upload controls and file-drop hints to both FASTA headers; validate
+       file size/contents before replacing a strand and invalidate stale reads.
+ * gui/tests/uploads.test.mjs, scripts/wasm/{test-browser.py,stage.sh}
+     + Test local upload/drop, invalid files and reset during a pending read;
+       stage the file-input module (PR #287 review).
+
+261023 Alexander Mitrofanov
+ * gui/{app.js,index.html,styles.css,examples/}, gui/docs/json-workflow.md
+     * Reset clears inputs/results and restores defaults; example FASTA is shown
+       only as placeholders. Add a described Example dropdown beside Reset.
+     + Ship two editable JSON examples and a manifest, using the common importer.
+ * gui/tests/parameter-file.test.mjs, scripts/wasm/{stage.sh,test-browser.py}
+     + Validate/stage example files and check empty startup/reset behavior (#287).
+
+261023 Alexander Mitrofanov
+ * gui/parameter-file.js, archive.js, app.js, index.html, protocol.js
+     + Load and Store non-default settings and embedded inputs using native JSON;
+       validate imports before replacing the form and retain CSV selection order.
+     * ZIP exports contain only parameter.json and outputs. Record version and
+       native replay commands, including overrides for additional report formats.
+ * gui/tests/, scripts/wasm/{smoke-protocol.mjs,test-browser.py,stage.sh},
+   gui/docs/{json-workflow.md,step4-results-and-deployment.md}
+     + Test JSON round trips, invalid imports, real WASM replay and output equality;
+       stage the serializer and nlohmann/json license (PR #287 review).
+
+261023 Alexander Mitrofanov
+ * gui/protocol.js, gui/intarna-worker.js, gui/tests/protocol.test.mjs,
+   gui/docs/step2-worker-architecture.md
+     * Pass --parameterFile=/parameter.json to each WASM instance using the
+       native JSON format with embedded FASTA, SHAPE and accessibility text.
+       Preserve native output routing and independent report invocations (#287).
+
+261023 Alexander Mitrofanov
+ * src/bin/ParameterFile.{h,cpp}, CommandLineParsing.{h,cpp}, Makefile.am
+     + Detect JSON parameter files; reuse native CLI validation and precedence,
+       support embedded input text and retain files until computation finishes.
+     * Honor parameter-file personalities when selecting native defaults.
+ * src/bin/nlohmann/, doc/json-parameters.md, README.md, scripts/wasm/stage.sh
+     + Vendor nlohmann/json 3.12.0 with its license, document the schema,
+       dependency tradeoff and reproduction contract (PR #287 review).
+ * tests/runParameterFile.sh, tests/testParameterFile.py, tests/Makefile.am
+     + Check legacy/JSON equivalence, embedded inputs, precedence and errors.
+
+261023 Alexander Mitrofanov
+ * gui/, scripts/wasm/, .github/workflows/build-wasm.yml, README.md,
+   doc/api-documentation.md, .gitignore
+     * Rename webinterface to gui, including imports, staging, tests and the
+       combined Pages artifact at /IntaRNA/gui/ (PR #287 review).
+
 261022 Alexander Mitrofanov
  * scripts/wasm/{vienna-release.py,vienna-release.json}, build.sh
    + Resolve the newest stable ViennaRNA >=2.7.2 and <3 from all official GitHub

README.md

@@ -5,10 +5,12 @@
 **Efficient RNA-RNA interaction prediction incorporating accessibility and
 seeding of interaction sites**
 
-Predict short RNA pairs or evaluate supplied structures locally with the [browser interface](https://backofenlab.github.io/IntaRNA/webinterface/).
-Select an interaction to view it in vaRRI, or download a ZIP with inputs, compiled versions, reproducible parameters and all outputs.
-See the [WebAssembly build instructions](webinterface/docs/step1-wasm-compilation.md) and
-[interface/deployment notes](webinterface/docs/step4-results-and-deployment.md).
+Predict short RNA pairs or evaluate supplied structures locally with the [browser interface](https://backofenlab.github.io/IntaRNA/gui/).
+The browser accepts up to 50 records per strand, 2–5,000 nucleotides each, with longest selected query × longest selected target at most 1,000,000. Prediction defaults to 10 interactions per pair and includes opening and seed energies; evaluation selects all energy columns.
+Computed runs stay in separate, foldable sessions under Results in the current tab. Name and select sessions to restore their inputs and compare results; editing or resetting parameters keeps earlier runs.
+Select an interaction to view it in vaRRI, or download a session’s ZIP with inputs, compiled versions, reproducible parameters and all outputs. Sessions are temporary and are cleared when the page is reloaded.
+See the [WebAssembly build instructions](gui/docs/step1-wasm-compilation.md) and
+[interface/deployment notes](gui/docs/step4-results-and-deployment.md).
 
 
 During the last few years, several new small regulatory RNAs
@@ -30,7 +32,7 @@ as well as the existence of a user-definable seed interaction. We successfully a
 IntaRNA to the prediction of bacterial sRNA targets and determined the exact
 locations of the interactions with a higher accuracy than competing programs.
 
-For testing or ad hoc use of IntaRNA, you can use its webinterface at the
+For testing or ad hoc use of IntaRNA, you can use its gui at the
 
 **==> [Freiburg RNA tools IntaRNA webserver](http://rna.informatik.uni-freiburg.de/IntaRNA/) <==**
 
@@ -504,6 +506,11 @@ using `configure --disable-multithreading`.
 <br />
 <a name="parameterFile" />
 
+JSON parameter files, including embedded FASTA, accessibility, SHAPE and energy
+parameter text, are also accepted by `--parameterFile` with automatic format
+detection. See [JSON format, examples and precedence](doc/json-parameters.md).
+
+
 ## Load arguments from file
 
 If you are using IntaRNA with similar command line arguments (parameters), you 

doc/Makefile.am

@@ -6,6 +6,7 @@
 EXTRA_DIST =	\
 			conda.txt \
 			api-documentation.md \
+			json-parameters.md \
 			build-api.sh \
 			check-api.py \
 			doxygen.cfg \

doc/api-documentation.md

@@ -45,15 +45,15 @@ manually to inspect documentation artifacts. The documentation build uploads
 under `api/`.
 
 `build-wasm.yml` combines that artifact with the tested browser interface under
-`webinterface/` and publishes **one** Pages artifact. This preserves the existing
+`gui/` and publishes **one** Pages artifact. This preserves the existing
 guide and API; two independent publishers would overwrite each other's site.
 Only a push or manual dispatch on `BackofenLab/IntaRNA`'s `master` can deploy.
 Pull requests and forks cannot publish. The deployment job alone receives Pages
 and OIDC write permissions, and deployments share one concurrency group.
 
 - User guide: <https://backofenlab.github.io/IntaRNA/>
 - Development API: <https://backofenlab.github.io/IntaRNA/api/>
-- Browser interface: <https://backofenlab.github.io/IntaRNA/webinterface/>
+- Browser interface: <https://backofenlab.github.io/IntaRNA/gui/>
 
 ### Pages configuration
 
@@ -67,5 +67,5 @@ change live publishing settings. See GitHub's
 
 No generated HTML, access token, or separate documentation branch is committed.
 The `intarna-pages-preview` artifact contains the combined site for PR review.
-See [the browser deployment notes](../webinterface/docs/step4-results-and-deployment.md)
+See [the browser deployment notes](../gui/docs/step4-results-and-deployment.md)
 for the complete build and validation sequence.

doc/json-parameters.md

@@ -0,0 +1,79 @@
+# JSON parameter files
+
+`IntaRNA --parameterFile=parameter.json` accepts the same CLI option names and
+values as a legacy `key = value` file. Detection uses the first non-whitespace
+character, after an optional UTF-8 BOM, independent of the filename suffix.
+Legacy files remain supported. Explicit scalar CLI options override file values;
+composing options such as `out` accumulate as before. A file's `personality`
+selects defaults before parsing; an explicit CLI personality takes precedence.
+
+```json
+{
+  "schema": "IntaRNA-parameters-v1",
+  "_comment": ["Reproduce: IntaRNA --parameterFile=parameter.json"],
+  "parameters": {
+    "query": {"text": ">query\nGGGAGGAGGG\n"},
+    "target": {"text": ">target\nCCCUCCUCCC\n"},
+    "temperature": 25,
+    "outMode": "C",
+    "out": ["interactions.csv", "qPu:query-pu.txt"]
+  }
+}
+```
+
+`parameters` contains strings, JSON numbers and booleans. Repeated/composing
+options accept nonempty arrays. Flags without values accept `true` or `false`.
+Unknown options, duplicate keys, null values, unsupported nested values and
+recursive `parameterFile` are errors. Existing native type, range and cross-option
+validation still applies. JSON uses normal JSON escapes; `#`, whitespace and
+newlines in string values are not interpreted as legacy configuration syntax.
+
+The optional `_comment` field holds provenance and reproduction instructions as
+ordinary JSON data, so files work with standard JSON parsers. Optional `gui`
+metadata describes browser-only output selections and is ignored by the CLI.
+Other document fields and unsupported schema versions are rejected.
+
+## Embedded inputs
+
+For `query`, `target`, `qAccFile`, `tAccFile`, `qShape`, `tShape` and `energyVRNA`,
+use `{"text": "file contents"}` to embed UTF-8 text. FASTA may contain multiple
+records. Accessibility uses RNAplfold text; SHAPE and energy parameters retain
+their native formats. Ordinary strings retain their original meaning (sequence,
+preset or filesystem path). Relative paths remain relative to the working
+directory, as with legacy configuration files. Binary `.agz` caches can still be
+referenced by path; they are not a text encoding.
+
+For accessibility of multiple selected records, `{"texts": ["record 1 data",
+"record 2 data"]}` materializes files with the existing `-sN` suffixes, indexed by
+original FASTA record number. Use `text` when selecting a single record. No
+user-specified paths are used for embedded files. A private temporary directory
+keeps generated files alive for the entire prediction and removes them on normal
+exit or exception unwinding. WASM uses its private in-memory filesystem. Like
+other temporary resources, abrupt process termination can leave native files.
+
+## Dependency choice
+
+We evaluated [Boost.JSON](https://www.boost.org/doc/libs/1_87_0/libs/json/doc/html/json/overview.html)
+and [nlohmann/json](https://json.nlohmann.me/integration/). Both provide typed JSON
+and can avoid a separately linked JSON library. Boost.JSON would raise our
+current Boost 1.50 minimum to a release containing JSON, or require another
+vendored Boost component and its dependency integration. Boost.PropertyTree is
+already available but loses JSON scalar/array type distinctions needed here.
+
+We chose the unmodified, MIT-licensed nlohmann/json 3.12.0 single header (953,436
+bytes), compiled in one CLI translation unit. It adds no system package, linker
+flag, public library API or WASM build dependency. The tradeoff is a vendored
+header to maintain and extra compile/binary size; the parser is outside prediction
+loops. Checksums and update instructions live in `src/bin/nlohmann/README.md`.
+The source distribution and staged GUI include the license.
+
+### Observed WASM footprint
+
+With Emscripten 4.0.23, ViennaRNA 2.7.2 and Boost 1.87.0 using
+`scripts/wasm/build.sh`, the cached pre-JSON engine at `d44d7a6` is 3,217,224 bytes
+(781,737 bytes with Python `gzip.compress(..., mtime=0)`). The JSON-enabled engine
+is 3,362,458 bytes (823,241 gzip): an increase of 145,234 bytes raw and 41,504
+compressed. These are local artifact-size observations with matching dependency
+versions, not runtime benchmarks or guarantees for other toolchains. Reproduce
+by building both revisions, comparing `site/wasm/intarna.wasm`, and checking
+`site/build-info.json` for compiler/library provenance.