docs: alive everywhere — autoplay, ambient micro-widgets across all pages

Every widget now autoplays when scrolled into view (pausing offscreen;
reduced-motion gets a rich pre-rendered frame, never an empty axis) and
heroes pre-warm so first paint already shows a running system.

Adds docs/viz/inline.js: ten parameterized ambient micro-widgets
(dist-strip, posterior-morph, trace-ticker, rhat-spark, shrinkage,
regression-mini, mixture-resp, logistic-boundary, elbo-climb, abc-eps)
with real math inside (split-R-hat and ESS ported from
src/inference/diagnostics.rs, EM responsibilities, conjugate updates),
embedded at the point of discussion across ~20 pages — including a
deliberately unconverged rhat-spark on debugging-models and a live
partial-pooling shrinkage widget on hierarchical-models.

Removes all "new in 0.2.0"-style callouts (13 sites incl. the
distributions widget's selector group) — version history lives in the
CHANGELOG, not the docs.

Browser-verified: all 25 widget-bearing pages animate on arrival, zero
console errors, zero >50ms long tasks during ambient play on the
busiest pages, reduced-motion renders rich static frames (fixed a
resize race that blanked paused micro-widgets).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DEAKcbnLVP8iSXub2Pqor2

Author: alexnodeland

docs/book.toml

@@ -18,7 +18,7 @@ preferred-dark-theme = "navy"
 git-repository-url = "https://github.com/alexnodeland/fugue"
 site-url = "/fugue/"
 additional-css = ["./mdbook-admonish.css", "fugue-viz.css"]
-additional-js = ["mermaid.min.js", "mermaid-init.js", "fugue-viz.js", "viz/anatomy.js", "viz/monad.js", "viz/metropolis.js", "viz/hmc.js", "viz/smc.js", "viz/distributions.js"]
+additional-js = ["mermaid.min.js", "mermaid-init.js", "fugue-viz.js", "viz/anatomy.js", "viz/monad.js", "viz/metropolis.js", "viz/hmc.js", "viz/smc.js", "viz/distributions.js", "viz/inline.js"]
 
 [output.html.fold]
 enable = true

docs/fugue-viz.css

@@ -254,3 +254,61 @@ html.rust .fv-btn.fv-primary {
     animation: none !important;
   }
 }
+
+/* ---- The micro-widget family (docs/viz/inline.js) ------------------------- */
+/* Ambient inline figures embeddable on any page. Tighter chrome than the
+   full-width hero explorables; a single pause/play glyph; an optional caption. */
+
+.fv-inline {
+  position: relative; /* anchor the pause/play glyph */
+  padding: 8px 10px;
+  border-radius: 6px;
+  margin: 1.1rem 0;
+}
+
+.fv-inline .fv-canvas {
+  border-radius: 5px;
+}
+
+/* The single unobtrusive pause/play glyph, top-right of the panel. */
+.fv-glyph {
+  position: absolute;
+  top: 6px;
+  right: 8px;
+  z-index: 2;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--fv-ink);
+  opacity: 0.35;
+  cursor: pointer;
+  font-size: 0.72rem;
+  line-height: 1;
+  font-family: inherit;
+  transition: opacity 0.15s ease;
+}
+
+.fv-glyph:hover {
+  opacity: 1;
+}
+
+.fv-glyph:focus-visible {
+  opacity: 1;
+  outline: 2px solid var(--fv-prior);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+/* Caption rendered under a micro-widget's canvas (data-caption). */
+.fv-caption {
+  font-style: italic;
+  opacity: 0.7;
+  font-size: 0.76rem;
+  margin-top: 6px;
+  line-height: 1.4;
+}

docs/fugue-viz.js

@@ -6,7 +6,7 @@
  * (docs/viz/*.js) call FugueViz.register("name", fn) and consume this API; they
  * MUST NOT duplicate what lives here.
  *
- * The distribution math mirrors fugue 0.2.0's src/core/distribution.rs EXACTLY
+ * The distribution math mirrors fugue's src/core/distribution.rs EXACTLY
  * (parameterizations, support, boundary limits). See the RETURN contract in the
  * foundation agent's report for the full per-distribution parameter list.
  */
@@ -131,7 +131,7 @@
   }
 
   // ==========================================================================
-  // Distribution math — parameterizations match fugue 0.2.0 exactly.
+  // Distribution math — parameterizations match fugue exactly.
   // logpdf/logpmf are pure log-space (no exp), finite for every finite input.
   // ==========================================================================
 
@@ -990,7 +990,21 @@
     } catch (e) {}
   }
 
-  function loop(widgetRootEl, tickFn) {
+  // loop(widgetRootEl, tickFn, opts) -> {play(), pause(), step(), playing, reduced}.
+  //
+  // Drives a rAF animation of tickFn(dt). Auto-pauses when the widget scrolls
+  // offscreen (IntersectionObserver) or the tab is hidden, and resumes on return.
+  //
+  // opts.autoplay (boolean): when true, the widget begins playing the moment it
+  // initializes — init is already lazy on scroll-into-view, so nobody lands on a
+  // dead canvas. Autoplay routes through play(), which is a no-op under
+  // prefers-reduced-motion and under the offscreen/hidden guards; so a
+  // reduced-motion visitor never gets autoplaying animation (the widget should
+  // render a fully-formed static frame instead), and an offscreen autoplay simply
+  // resumes once scrolled into view. The returned API is identical with or without
+  // opts — autoplay only changes whether play() is invoked once at the end of setup.
+  function loop(widgetRootEl, tickFn, opts) {
+    opts = opts || {};
     var raf = null;
     var playing = false;
     var onscreen = true;
@@ -1061,6 +1075,8 @@
         }
       });
     }
+    // Autoplay on init (respects reduced-motion / offscreen guards inside play()).
+    if (opts.autoplay) play();
     return api;
   }
 

docs/src/explorables/anatomy.md

@@ -122,3 +122,7 @@ explorable.
 - **Next explorable:** [The Model Is a Score](./monad.md) — step through the
   interpreter that actually runs this program.
 - **API:** [`Beta`](https://docs.rs/fugue-ppl/latest/fugue/), [`adaptive_mcmc_chain`](https://docs.rs/fugue-ppl/latest/fugue/inference/mh/fn.adaptive_mcmc_chain.html).
+
+---
+
+Next: [The Model Is a Score](./monad.md)

docs/src/explorables/distributions.md

@@ -108,8 +108,7 @@ let model = prob!(
 
 ## The full field guide
 
-Every distribution in fugue 0.2.0. The `sample →` column is the natural return
-type; the seven marked **new in 0.2.0** arrived with this release.
+Every distribution in fugue. The `sample →` column is the natural return type.
 
 ### Continuous
 
@@ -121,6 +120,12 @@ type; the seven marked **new in 0.2.0** arrived with this release.
 | `Exponential` | [0, ∞) | `rate` > 0 | `f64` | the wait until the next memoryless event; mean = 1/rate. |
 | `Beta` | [0, 1] | `alpha`, `beta` > 0 | `f64` | a probability about a probability — the coin-bias prior. |
 | `Gamma` | (0, ∞) | `shape`, `rate` > 0 | `f64` | positive quantities; **rate**-parameterized, mean = shape/rate. |
+| `StudentT` | (−∞, ∞) | `df`, `loc`, `scale` > 0 | `f64` | a heavier-tailed Normal that tolerates outliers. |
+| `Cauchy` | (−∞, ∞) | `loc`, `scale` > 0 | `f64` | pathological tails — no mean, no variance. `StudentT(df=1)`. |
+| `Laplace` | (−∞, ∞) | `loc`, `scale` > 0 | `f64` | a sharp peak with exponential tails; the L1 / lasso prior. |
+| `Weibull` | [0, ∞) | `shape`, `scale` > 0 | `f64` | time-to-failure and survival modeling. |
+| `ChiSquared` | (0, ∞) | `k` > 0 | `f64` | sums of squared Normals; = `Gamma(k/2, ½)`. |
+| `InverseGamma` | (0, ∞) | `shape`, `rate` > 0 | `f64` | the conjugate prior for a Normal's variance. |
 
 ### Discrete
 
@@ -130,17 +135,6 @@ type; the seven marked **new in 0.2.0** arrived with this release.
 | `Categorical` | {0 … K−1} | `probs` sum to 1 | `usize` | picking one of K labels; index arrays safely. |
 | `Binomial` | {0 … n} | `n`, `p` ∈ [0, 1] | `u64` | successes in n independent trials. |
 | `Poisson` | {0, 1, 2, …} | `lambda` > 0 | `u64` | rare-event counts; mean = variance = λ. |
-
-### New in 0.2.0
-
-| Distribution | Support | Parameters | `sample →` | Reach for it when |
-|---|---|---|---|---|
-| `StudentT` | (−∞, ∞) | `df`, `loc`, `scale` > 0 | `f64` | a heavier-tailed Normal that tolerates outliers. |
-| `Cauchy` | (−∞, ∞) | `loc`, `scale` > 0 | `f64` | pathological tails — no mean, no variance. `StudentT(df=1)`. |
-| `Laplace` | (−∞, ∞) | `loc`, `scale` > 0 | `f64` | a sharp peak with exponential tails; the L1 / lasso prior. |
-| `Weibull` | [0, ∞) | `shape`, `scale` > 0 | `f64` | time-to-failure and survival modeling. |
-| `ChiSquared` | (0, ∞) | `k` > 0 | `f64` | sums of squared Normals; = `Gamma(k/2, ½)`. |
-| `InverseGamma` | (0, ∞) | `shape`, `rate` > 0 | `f64` | the conjugate prior for a Normal's variance. |
 | `DiscreteUniform` | {low … high} | `low` ≤ `high` | `i64` | a fair die over an integer range. |
 
 ```admonish note title="Gamma is rate-parameterized"
@@ -157,3 +151,7 @@ rate convention. If a value looks inverted, check whether you meant scale = 1/ra
   every constructor, its constraints, and its `log_prob`.
 - Next explorable: [Anatomy of a Probabilistic Program](anatomy.md) — put a
   `Beta` prior and `Bernoulli` data together and watch Bayes multiply them.
+
+---
+
+Next: [Explorables](./README.md)

docs/src/explorables/hmc.md

@@ -20,9 +20,10 @@ seed and you get the exact same momenta and trajectories every time.
 
 ## Things to try
 
-1. Press **Play**. Watch one violet **leapfrog trajectory** roll across parameter
-   space — a single proposal travelling much farther than a random-walk hop — while
-   its coral **fit line** swings across the data on the left.
+1. Watch the violet **leapfrog trajectory** roll across parameter space — a single
+   proposal travelling much farther than a random-walk hop — while its coral **fit
+   line** swings across the data on the left. (It is already rolling; the controls
+   let you pause, step, and steer.)
 2. **Drag the rightmost yellow point far up.** The posterior heatmap tilts toward
    steeper slopes and the coral ball rolls after it within a few transitions. This
    linked deformation is the whole point of the page.
@@ -140,7 +141,7 @@ fn main() {
 ```
 
 The same **ESS** you watch converge in the widget is a real diagnostic. Run a few
-chains and combine them with the multi-chain estimators (new in 0.2.0):
+chains and combine them with the multi-chain estimators:
 
 ```rust,ignore
 use fugue::*;
@@ -169,3 +170,7 @@ discrete latents.
   and [`HMCConfig`](https://docs.rs/fugue-ppl/latest/fugue/inference/hmc/struct.HMCConfig.html).
 - **Next:** [Particles That Tell Stories](./smc.md) — inference that moves through
   time instead of space.
+
+---
+
+Next: [Particles That Tell Stories](./smc.md)

docs/src/explorables/metropolis.md

@@ -24,14 +24,14 @@ A point in the right panel *is* a line in the left panel — watch them move tog
 The model is honest Bayesian linear regression:
 $y \sim \mathcal{N}(a\,x + b,\ \sigma_{\text{obs}})$ with $\sigma_{\text{obs}}$ fixed at
 $0.8$, and priors $a, b \sim \mathcal{N}(0, 2.5)$. The
-<span class="fv-c-post">split-R̂</span> and ESS readouts are fugue 0.2.0's real
+<span class="fv-c-post">split-R̂</span> and ESS readouts are fugue's real
 convergence diagnostics, computed live on the samples accruing on screen.
 
 ## Things to try
 
-1. **Press Play, then drag a point far off the line.** The right-hand heatmap morphs
-   and the whole chain migrates to the new best fit — same frame. This is the moment:
-   the data *is* the posterior, and you are reshaping it with your cursor.
+1. **The chains are already walking — drag a point far off the line.** The right-hand
+   heatmap morphs and the whole chain migrates to the new best fit — same frame. This
+   is the moment: the data *is* the posterior, and you are reshaping it with your cursor.
 2. **Drag `PROPOSAL σ` down to `0.02`.** Acceptance climbs toward 100% — every tiny
    step is safe — yet the coral dot barely crawls and R̂ stays stubbornly above 1. High
    acceptance is not the goal.
@@ -149,8 +149,8 @@ fn main() {
         chains.push(draws.into_iter().map(|(_, trace)| trace).collect());
     }
 
-    // Split-R-hat (Vehtari et al. 2021) and ESS — 0.2.0's diagnostics, the same
-    // numbers the widget shows.
+    // Split-R-hat (Vehtari et al. 2021) and ESS — the same convergence
+    // diagnostics the widget shows.
     let rhat = r_hat_f64(&chains, &addr!("slope"));
     let slope_chain0: Vec<f64> = chains[0]
         .iter()
@@ -179,3 +179,7 @@ full recording behind it. `r_hat_f64` is the coral/green R̂ readout;
   a chain misbehaves.
 - **API:** [`adaptive_mcmc_chain`](https://docs.rs/fugue-ppl/latest/fugue/fn.adaptive_mcmc_chain.html)
   · [`r_hat_f64`](https://docs.rs/fugue-ppl/latest/fugue/fn.r_hat_f64.html)
+
+---
+
+Next: [Rolling, Not Guessing: Hamiltonian Monte Carlo](./hmc.md)

docs/src/explorables/monad.md

@@ -201,3 +201,7 @@ with 100 000 sample sites is interpreted without overflowing the stack.
 - Next explorable: [Random Walks in Posterior Space](./metropolis.md) — now that
   the score has a value and a weight, how do we *listen* our way back to the
   posterior you just watched form?
+
+---
+
+Next: [Random Walks in Posterior Space](./metropolis.md)

docs/src/explorables/smc.md

@@ -198,3 +198,7 @@ dragging sliders is exactly what the library does under the hood.
   and [`effective_sample_size`](https://docs.rs/fugue-ppl/latest/fugue/inference/smc/fn.effective_sample_size.html).
 - Next explorable: [A Field Guide to Distributions](./distributions.md) — the
   building blocks every model above is made of.
+
+---
+
+Next: [A Field Guide to Distributions](./distributions.md)

docs/src/getting-started/README.md

@@ -127,6 +127,8 @@ graph TB
 
 **Fugue** makes this safe, fast, and composable in Rust.
 
+<div class="fugue-explorable fv-inline" data-viz="posterior-morph" data-kind="beta" data-caption="Step 3, Infer, in miniature: each yellow observation sharpens the green posterior around the blue prior."></div>
+
 ## Next Steps
 
 Ready to dive in?