proxymix-tutorial

Interactive HTML primer for the proxymix R package, targeted at Adelaide University Mathematics and Statistics undergraduates (default reading depth) and postgraduates / PhD readers (via the in-page dial).

The rendered page is a single HTML file with no Internet dependencies. It works on the web (when hosted on GitHub Pages) and on your computer (when you double-click it from a shared drive, email attachment, or USB stick), on both macOS and Windows.

Sharing the tutorial

There is just one file to send: proxymix_tutorial.html (~2.3 MB). Everything — the precomputed state space, KaTeX math rendering, fonts, JavaScript widgets — is inlined into that one file.

How recipients open it

Platform	What to do	Tested browsers
macOS	Double-click the .html file. Safari opens it by default; Chrome and Firefox work the same way (drag the file onto the browser icon, or right-click → Open With).	Safari 17+, Chrome 120+, Firefox 120+, Edge 120+
Windows	Double-click the .html file. Edge opens it by default; Chrome and Firefox work the same way.	Edge 120+, Chrome 120+, Firefox 120+
Web	Visit the hosted URL (when published to GitHub Pages).	All modern browsers.

Internet Explorer is not supported (end-of-life since 2022).

Why the single-file design

Earlier scaffolds of this primer fetched the precomputed state files (states/banana.json, states/observe.json) at runtime. That works on GitHub Pages, but most browsers block fetch() from the local filesystem (file://) under CORS — so the widgets would silently fail on a double-clicked HTML. The current build inlines the state files into <script type="application/json"> blocks directly in the HTML, removing all runtime network and filesystem dependencies. Result: the page loads identically on the web and on disk.

What is in here

tutorial/
├── proxymix_tutorial.qmd        # Quarto source (renders to a single HTML)
├── proxymix_tutorial.html       # generated artefact, ~2.3 MB
├── assets/
│   ├── dial.css                 # two-axis dial + widget styles
│   ├── dial.js                  # depth × show-code state machine
│   ├── scenario.js              # JSON loader + SVG renderer
│   └── states-inline.html       # <script> blocks with inlined JSON (generated)
├── scripts/
│   └── precompute_states.R      # deterministic state-space precompute
├── states/
│   ├── banana.json              # Scenario A states (~36 KB; also inlined)
│   └── observe.json             # Scenario B states (~131 KB; also inlined)
├── .github/workflows/
│   └── tutorial.yml             # CI: re-run precompute, render, size + grep
└── README.md

Reading depths

The page presents two reading depths, switchable from the dial in the header:

• Guided (default) — year-2 Adelaide M&S undergraduate audience.
• Technical — postgraduate / PhD audience.

A third "no-statistics" depth is planned for v0.2.

Code visibility is an independent toggle (Show R code). Both controls persist in localStorage.

Live R in the browser (opt-in)

The header Run live in R button lazy-loads webR on first click (one-time fetch from webr.r-wasm.org, ~10 s) and opens an in-page R console at the bottom of the page. The console runs base R in WebAssembly; no server, no R install. The page works fully without ever clicking the button — that path is purely opt-in.

Caveats for v0:

• The first click needs Internet. If the file is opened on an offline machine, the button shows a graceful error and the rest of the page continues to work.
• proxymix itself is not yet on the webR repository, so library(proxymix) will not load there in v0. v0.2 plans full proxymix-on-webR integration. Until then, base R and any package on the webR repository are available.
• Closing the console removes it cleanly; the page returns to its precomputed-only state.

Reproducing the precomputed states

Rscript scripts/precompute_states.R

The script runs against proxymix 0.3.0 at fixed seed 1L. It writes:

• states/banana.json + states/observe.json (sidecar files for GitHub Pages mode, indexed by meta.inputs_sha256);
• assets/states-inline.html (the same payload wrapped in <script type="application/json"> tags for the inlined-into-HTML mode, which is what the single-file build uses).

CI re-runs the script and fails the build if the regenerated files drift from the committed copies.

Rendering locally

quarto render proxymix_tutorial.qmd

Produces a self-contained proxymix_tutorial.html. Current size is ~2.3 MB (CI cap 3 MB).

Size note

KaTeX dominates the file: ~1.4 MB is inlined font assets (ttf + woff

• woff2, served for browser compatibility, only woff2 is needed on any modern browser). A v0.2 optimisation can strip the legacy formats and save ~1 MB. Until then, the CI size cap is 3 MB rather than the 2 MB targeted in the v0.1.1 plan.

Licence

MIT, matching the proxymix package.