labforge 0.1.1__tar.gz → 0.3.0__tar.gz

labforge-0.3.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+Notable changes to labforge. Versions follow [semantic versioning](https://semver.org).
+
+## 0.3.0 — 2026-07-22
+
+- **Wordmark animation** — hovering the app title blows its letters apart and
+  keeps them floating until the pointer leaves; they spring back into the
+  wordmark on exit.
+- **Motion** — rail navigation cross-fades between pages; a re-rendered figure
+  or recomputed result fades over its predecessor instead of flashing; the run
+  gate dissolves into the first output; the scan toggle fades between slider
+  and comma field; and the RUNNING status pulses gently while a run is in
+  flight.
+- **Reading measure** — every page constrains its content to a 720 px column,
+  so prose keeps a comfortable line length and control rows stay compact
+  instead of stretching across the window. Displayed equations sit centered in
+  the measure, and figures scale down to fit it (staying crisp on high-dpi
+  screens) instead of clipping at the pane edge.
+- **Uniform control rows** — text fields share the sliders' fixed label column
+  and the house field styling (hairline outline, square corners), and a new
+  `help` string on `Param` surfaces as a tooltip on the row label.
+- **Parse feedback** — an unreadable text or comma-list entry now flags the
+  field ("invalid, kept ...") while the last good value stays live, instead of
+  falling back silently.
+- **Error tone** — a worker, viz or analysis exception shows its status line in
+  the theme's error colour rather than the muted telemetry tone.
+- **Scan progress** — a running scan reports `RUNNING · k/N` as the grid fills
+  in; `run_worker` and `LabState.run` accept an optional `progress(done, total)`
+  callback.
+- **Explorable pre-run pages** — the Visualization and Analysis tabs, their
+  descriptions and controls now show before the first Run; the NO DATA card
+  sits only in the output slot. Tab labels speak the app's monospace voice.
+- **Enter to run** — pressing Enter in any text field fires its section's
+  Run/Render/Compute action.
+
+## 0.2.0 — 2026-07-22
+
+- **`choice` param** — `Param(kind="choice", options=[...])` renders a Dropdown
+  and commits the selected string like any other control. The default must be
+  one of the options and the options must be non-empty (checked at registration);
+  a choice cannot be scanned.
+- **Theory-page selector** — `set_theory_selector(name, param, theory)` puts a
+  `choice` control on the Theory page whose value both rebuilds the theory
+  markdown (via a `theory(selection) -> markdown` callback) and writes the lab's
+  shared context. The static `set_theory` behavior is unchanged; the selector
+  takes precedence when both are set.
+- **Model-driven worker selector** — `set_theory_selector(..., selects_worker=True)`
+  makes the Theory dropdown the model switch: its options name registered workers,
+  and choosing one makes that worker active. The Simulation page then shows the
+  active worker as a single tab so it matches the tabbed Visualization and
+  Analysis pages.
+- **Shared context** — a per-session lab-level context that the Theory selector
+  writes and any worker, viz or analysis reads by declaring a `context`
+  parameter (injected at call time, never rendered as a control). So a choice is
+  made once and every page sees it.
+- **Multiple workers** — call `add_worker` more than once to build a lab with
+  several workers. Each worker keeps its own workspace (controls, last result,
+  and per-tab settings), and the `add_viz` / `add_analysis` calls after each
+  `add_worker` attach that worker's own tabs. Several workers need a way to choose
+  among them, checked at build: a `selects_worker` model selector, or
+  `worker_view="tabs"` to lay the workers out as Simulation-page tabs (sharing one
+  set of visualizations and analyses). There is no top-bar worker dropdown.
+  Single-worker labs are unchanged. (`worker_view` is `"panels"` by default, or
+  `"tabs"`.)
+- **Bundled fonts** — the app now ships its typefaces (Inter and Roboto Mono),
+  so the browser view renders the same faces and weights as the desktop window
+  instead of falling back to the platform default.
+- **Clearer theory errors** — `set_theory` now raises on a mistyped file path
+  (a missing `Path`, or a bare `".md"` string) instead of silently rendering the
+  path as a one-line page.
+- **Non-blocking Run** — the worker now runs off the UI thread, so a slow worker
+  no longer freezes the window. Run shows a `RUNNING…` status and disables the
+  button until the run settles. Fast workers are unaffected.
+
+## 0.1.1 — 2026-07-22
+
+Packaging and documentation only; no functional change.
+
+- Complete PyPI metadata: `readme`, keywords, trove classifiers, and project
+  URLs, so the project page renders the README and links back to the repository.
+- README image links use absolute URLs, so screenshots and the theme gallery
+  render on the PyPI project page rather than showing as broken images.
+
+## 0.1.0 — 2026-07-22
+
+Initial release.
+
+- **`Lab`** — register plain Python functions (one worker, any number of
+  visualization and analysis functions) and a markdown theory source, then
+  `open()` the assembled app: as a native desktop window or served to the
+  browser, laid out as four rail-navigated pages or one continuous scrolling
+  page. All registration is validated on the spot, so a malformed app fails at
+  assembly rather than mid-navigation.
+- **`Param` specs** — each worker/viz/analysis kwarg gets a UI control from its
+  `Param` (or a shorthand string such as `"int"` or `"scalar or array"`);
+  bounded params render as sliders with live readouts, unbounded ones as
+  validated text fields, tuples as per-element fields. Defaults are inferred
+  from the function signature.
+- **Parameter scans** — a kwarg declared `scan=True` accepts comma-separated
+  values; the worker runs once per point of the cartesian grid and downstream
+  functions receive a `ScanResult` of `(params, result)` records.
+- **Analysis dispatch** — an analysis may return a dict (two-column table), a
+  list of dicts or a DataFrame (table), a string (markdown), or a matplotlib
+  figure; the return shape picks the rendering.
+- **Themes** — eight palettes selected by `open(theme=...)`, four dark and
+  four light; chrome, plot palette and equation ink move together, and
+  `labforge.palette()` / `labforge.style(fig, ax)` let an author's figures
+  follow the active theme.
+- **LaTeX theory** — `$$...$$` blocks in the theory markdown render as crisp
+  equation images via system LaTeX, falling back to matplotlib mathtext.
+- **MIT licensed.**

{labforge-0.1.1 → labforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labforge
-Version: 0.1.1
+Version: 0.3.0
 Summary: Wrap plain Python functions into a small scientific Flet desktop app: theory, simulation, visualization, analysis.
 Project-URL: Homepage, https://github.com/laroccod/labforge
 Project-URL: Repository, https://github.com/laroccod/labforge
@@ -35,15 +35,15 @@ Description-Content-Type: text/markdown
 
 *By Daniel La Rocco*
 
-## **Turn plain Python scripts into a small scientific desktop app.**
+## **Turn plain Python scripts into small scientific desktop apps.**
 
-labforge wraps a simulation you already have — a function that produces data,
+`labforge` wraps a simulation you already have — a function that produces data,
 a function that plots it, a function that summarizes it — into a polished
 four-section app following the **theory → simulation → visualization →
 analysis** workflow. Pure Python, rendered with [Flet](https://flet.dev); no
 HTML, no JavaScript, no callbacks to wire up.
 
-You provide the science and labforge supplies the app shell, the parameter controls
+You provide the science and `labforge` supplies the app shell, the parameter controls
 generated from your function signatures, the parameter-scan engine,
 LaTeX rendering for your theory notes, and eight instrument-panel themes, four
 dark and four light.
@@ -69,7 +69,7 @@ def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
 
 
 lab.add_worker(sample, {
-    "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
+    "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
     "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
     "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
     "seed": "int",
@@ -108,7 +108,9 @@ lab.open()
 That is the whole app. `lab.open()` opens a native window with four pages —
 Theory, Simulation, Visualization, Analysis — a slider for every bounded
 parameter, a Run button, and tabs for each registered visualization and
-analysis.
+analysis. Content keeps a book-like reading measure, navigation and result
+updates cross-fade rather than cut, and every page is explorable before the
+first Run.
 
 An extended version of this example — same lab plus a fitted-density overlay
 and a Q-Q plot tab — lives at [`examples/demo_lab.py`](examples/demo_lab.py):
@@ -133,21 +135,28 @@ spec nothing:
 | `Param(default=1.0)` / `"scalar"` / `"int"` | validated text field |
 | `Param(..., scan=True)` / `"scalar or array"` / `"int or array"` | scannable (see below) |
 | `"N-tuple"` (e.g. `"2-tuple"`) | one field per element |
+| `Param(kind="choice", options=["a", "b"])` | dropdown |
+
+Every `Param` also takes `label=` to rename its control and `help=` for a
+tooltip on the control's label. Pressing Enter in any text field runs the
+section it belongs to, and an entry that fails to parse flags the field while
+the last good value stays live.
 
 Validation happens at registration: unknown spec keys, defaults outside
 bounds, or a scan spec on a non-worker function raise `ValueError` when the
 app is assembled, never mid-use.
 
 **Parameter scans.** A kwarg declared `scan=True` gets a scan toggle (bounded)
-or a comma-separated field (unbounded). Enter `0, 1, 2` and labforge calls the
+or a comma-separated field (unbounded). Enter `0, 1, 2` and `labforge` calls the
 worker once per point of the cartesian grid across all scanned parameters —
-the worker itself always receives scalars. Downstream functions then receive a
+the worker itself always receives scalars. A long scan reports its progress in
+the status line as the grid fills in. Downstream functions then receive a
 `ScanResult`: a list of `(params, result)` records with `keys`, `values()` and
 `axis(name)` helpers, distinguished with `isinstance(data, ScanResult)`.
 
 **Visualizations.** Functions `viz(data, **kwargs)` returning a matplotlib
 figure (bare or `(fig, ax)`). Each gets a tab with its own controls and a
-Render button. Figures are yours — labforge only serializes them; the house
+Render button. Figures are yours — `labforge` only serializes them; the house
 style (`labforge.style(fig, ax)`) is strictly opt-in.
 
 **Analyses.** Functions `analysis(data, **kwargs)` — the return shape picks
@@ -161,6 +170,35 @@ the rendering:
 | Figure or `(fig, ax)` | image |
 | anything else | its `repr` |
 
+**Multiple workers.** Call `add_worker` more than once for a lab with several
+workers. Each worker keeps its own workspace — its controls, its last result and
+its per-tab settings — and the `add_viz` / `add_analysis` calls after each
+`add_worker` attach that worker's own tabs, so switching workers and back
+restores exactly what was there. Several workers need a way to choose among them
+(checked at build): a `selects_worker` model selector, or `worker_view="tabs"`
+to lay the workers out as Simulation-page tabs.
+
+The clean way is a Theory-page selector with `selects_worker=True`: its options
+name the workers, so choosing one both swaps the theory and makes that worker
+active. There is no top-bar dropdown; the Simulation page shows the active
+worker as a single tab, matching the tabbed Visualization and Analysis pages.
+The demo (`examples/demo_lab.py`) uses this to switch between a normal and a
+gamma model:
+
+```python
+lab.set_theory_selector(
+    "model",
+    Param(kind="choice", options=["Normal", "Gamma"]),
+    theory_for,                 # theory_for(selection) -> markdown
+    label="Distribution",
+    selects_worker=True,
+)
+lab.add_worker(sample, {...}, name="Normal")   # its own viz/analysis tabs
+lab.add_worker(sample_gamma, {...}, name="Gamma")
+```
+
+![The Theory model selector driving the active worker: choosing Gamma shows the gamma theory and the gamma worker as a single Simulation tab](https://raw.githubusercontent.com/laroccod/labforge/main/assets/multi_worker.png)
+
 **Theory.** A markdown file or string. Displayed `$$...$$` equations render as
 crisp images — through your system LaTeX toolchain when one is installed
 (with the Euler math font), falling back to matplotlib's mathtext otherwise.
@@ -209,7 +247,7 @@ Requires Python ≥ 3.10.
 pip install labforge
 ```
 
-Or from a clone, to hack on it:
+Or from a clone, if you want to work on the code directly:
 
 ```bash
 git clone https://github.com/laroccod/labforge.git

{labforge-0.1.1 → labforge-0.3.0}/README.md

@@ -2,15 +2,15 @@
 
 *By Daniel La Rocco*
 
-## **Turn plain Python scripts into a small scientific desktop app.**
+## **Turn plain Python scripts into small scientific desktop apps.**
 
-labforge wraps a simulation you already have — a function that produces data,
+`labforge` wraps a simulation you already have — a function that produces data,
 a function that plots it, a function that summarizes it — into a polished
 four-section app following the **theory → simulation → visualization →
 analysis** workflow. Pure Python, rendered with [Flet](https://flet.dev); no
 HTML, no JavaScript, no callbacks to wire up.
 
-You provide the science and labforge supplies the app shell, the parameter controls
+You provide the science and `labforge` supplies the app shell, the parameter controls
 generated from your function signatures, the parameter-scan engine,
 LaTeX rendering for your theory notes, and eight instrument-panel themes, four
 dark and four light.
@@ -36,7 +36,7 @@ def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
 
 
 lab.add_worker(sample, {
-    "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
+    "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
     "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
     "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
     "seed": "int",
@@ -75,7 +75,9 @@ lab.open()
 That is the whole app. `lab.open()` opens a native window with four pages —
 Theory, Simulation, Visualization, Analysis — a slider for every bounded
 parameter, a Run button, and tabs for each registered visualization and
-analysis.
+analysis. Content keeps a book-like reading measure, navigation and result
+updates cross-fade rather than cut, and every page is explorable before the
+first Run.
 
 An extended version of this example — same lab plus a fitted-density overlay
 and a Q-Q plot tab — lives at [`examples/demo_lab.py`](examples/demo_lab.py):
@@ -100,21 +102,28 @@ spec nothing:
 | `Param(default=1.0)` / `"scalar"` / `"int"` | validated text field |
 | `Param(..., scan=True)` / `"scalar or array"` / `"int or array"` | scannable (see below) |
 | `"N-tuple"` (e.g. `"2-tuple"`) | one field per element |
+| `Param(kind="choice", options=["a", "b"])` | dropdown |
+
+Every `Param` also takes `label=` to rename its control and `help=` for a
+tooltip on the control's label. Pressing Enter in any text field runs the
+section it belongs to, and an entry that fails to parse flags the field while
+the last good value stays live.
 
 Validation happens at registration: unknown spec keys, defaults outside
 bounds, or a scan spec on a non-worker function raise `ValueError` when the
 app is assembled, never mid-use.
 
 **Parameter scans.** A kwarg declared `scan=True` gets a scan toggle (bounded)
-or a comma-separated field (unbounded). Enter `0, 1, 2` and labforge calls the
+or a comma-separated field (unbounded). Enter `0, 1, 2` and `labforge` calls the
 worker once per point of the cartesian grid across all scanned parameters —
-the worker itself always receives scalars. Downstream functions then receive a
+the worker itself always receives scalars. A long scan reports its progress in
+the status line as the grid fills in. Downstream functions then receive a
 `ScanResult`: a list of `(params, result)` records with `keys`, `values()` and
 `axis(name)` helpers, distinguished with `isinstance(data, ScanResult)`.
 
 **Visualizations.** Functions `viz(data, **kwargs)` returning a matplotlib
 figure (bare or `(fig, ax)`). Each gets a tab with its own controls and a
-Render button. Figures are yours — labforge only serializes them; the house
+Render button. Figures are yours — `labforge` only serializes them; the house
 style (`labforge.style(fig, ax)`) is strictly opt-in.
 
 **Analyses.** Functions `analysis(data, **kwargs)` — the return shape picks
@@ -128,6 +137,35 @@ the rendering:
 | Figure or `(fig, ax)` | image |
 | anything else | its `repr` |
 
+**Multiple workers.** Call `add_worker` more than once for a lab with several
+workers. Each worker keeps its own workspace — its controls, its last result and
+its per-tab settings — and the `add_viz` / `add_analysis` calls after each
+`add_worker` attach that worker's own tabs, so switching workers and back
+restores exactly what was there. Several workers need a way to choose among them
+(checked at build): a `selects_worker` model selector, or `worker_view="tabs"`
+to lay the workers out as Simulation-page tabs.
+
+The clean way is a Theory-page selector with `selects_worker=True`: its options
+name the workers, so choosing one both swaps the theory and makes that worker
+active. There is no top-bar dropdown; the Simulation page shows the active
+worker as a single tab, matching the tabbed Visualization and Analysis pages.
+The demo (`examples/demo_lab.py`) uses this to switch between a normal and a
+gamma model:
+
+```python
+lab.set_theory_selector(
+    "model",
+    Param(kind="choice", options=["Normal", "Gamma"]),
+    theory_for,                 # theory_for(selection) -> markdown
+    label="Distribution",
+    selects_worker=True,
+)
+lab.add_worker(sample, {...}, name="Normal")   # its own viz/analysis tabs
+lab.add_worker(sample_gamma, {...}, name="Gamma")
+```
+
+![The Theory model selector driving the active worker: choosing Gamma shows the gamma theory and the gamma worker as a single Simulation tab](https://raw.githubusercontent.com/laroccod/labforge/main/assets/multi_worker.png)
+
 **Theory.** A markdown file or string. Displayed `$$...$$` equations render as
 crisp images — through your system LaTeX toolchain when one is installed
 (with the Euler math font), falling back to matplotlib's mathtext otherwise.
@@ -176,7 +214,7 @@ Requires Python ≥ 3.10.
 pip install labforge
 ```
 
-Or from a clone, to hack on it:
+Or from a clone, if you want to work on the code directly:
 
 ```bash
 git clone https://github.com/laroccod/labforge.git

labforge-0.3.0/examples/demo_lab.py

@@ -0,0 +1,271 @@
+"""
+Demo lab
+
+Two samplers on one lab, to show off multiple workers and the Theory-page model
+selector. A normal worker carries a histogram (with fitted density), a Q-Q plot
+and a moments table; a gamma worker carries its own histogram and a
+method-of-moments fit. The Theory-page dropdown is the single model switch
+(selects_worker=True): choosing Normal or Gamma swaps the theory math and makes
+that worker active, so the Simulation page shows its parameters as one tab and
+the Visualization and Analysis pages show its own tabs. No top-bar worker
+dropdown is needed. Each worker handles both a single run and a parameter scan.
+Launch with `python examples/demo_lab.py`; add `--browser [port]` to serve it to
+the default web browser instead, `--scroll` for one continuous scrolling page
+instead of four, and/or `--theme <name>` to try a colour scheme (see
+labforge.themes()).
+"""
+
+import argparse
+from math import gamma as gamma_func
+from pathlib import Path
+from statistics import NormalDist
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import labforge
+from labforge import Lab, Param, ScanResult
+
+lab = Lab("statlab")
+
+# The Theory page carries a dropdown that swaps the whole page between the two
+# families; each option maps to its own markdown source.
+THEORY = {
+    "Normal": Path(__file__).with_name("theory.md").read_text(encoding="utf-8"),
+    "Gamma": Path(__file__).with_name("theory_gamma.md").read_text(encoding="utf-8"),
+}
+
+
+def theory_for(model):
+    """The theory markdown for the selected distribution."""
+    return THEORY[model]
+
+
+lab.set_theory_selector(
+    "model",
+    Param(kind="choice", options=["Normal", "Gamma"], default="Normal"),
+    theory_for,
+    label="Distribution",
+    selects_worker=True,
+)
+
+
+def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
+    """Draw n normal variates; reproducible for a given seed."""
+    return np.random.default_rng(seed).normal(mu, sigma, n)
+
+
+lab.add_worker(
+    sample,
+    {
+        "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
+        "sigma": Param(
+            default=1.0, bounds=(0.1, 4), scan=True, help="Standard deviation of the distribution"
+        ),
+        "n": Param(kind="int", default=2000, bounds=(10, 100_000), help="Sample size of the draw"),
+        "seed": Param(kind="int", help="Seed of the random generator"),
+    },
+    name="Normal",
+)
+
+
+def histogram(data, bins=40):
+    """Density histogram of the draw; a scan overlays one histogram per point."""
+    fig, ax = plt.subplots(figsize=(7, 3.4))
+    if isinstance(data, ScanResult):
+        for params, draws in data:
+            label = ", ".join(f"{key} = {params[key]:g}" for key in data.keys)
+            ax.hist(draws, bins=bins, density=True, alpha=0.5, label=label)
+    else:
+        colors = labforge.palette()
+        ax.hist(data, bins=bins, density=True, color=colors.data, label="draw")
+        # The density fitted by maximum likelihood, over the sample's own range.
+        mean, std = np.mean(data), np.std(data, ddof=1)
+        x = np.linspace(np.min(data), np.max(data), 400)
+        pdf = np.exp(-((x - mean) ** 2) / (2 * std**2)) / (std * np.sqrt(2 * np.pi))
+        ax.plot(x, pdf, color=colors.model, linewidth=1.6, label="fitted density")
+    ax.legend()
+    ax.set_xlabel("x")
+    ax.set_ylabel("density")
+    labforge.style(fig, ax)
+    return fig, ax
+
+
+lab.add_viz(
+    histogram,
+    "Histogram",
+    "Density-normalized histogram of the most recent draw, with the "
+    "maximum-likelihood normal density on top. On a scan, one translucent "
+    "histogram per grid point shows how μ shifts and σ stretches the density.",
+    {"bins": Param(kind="int", default=40, bounds=(5, 200))},
+)
+
+
+def qq_plot(data):
+    """Standardized order statistics against normal quantiles; scans overlay grid points."""
+    fig, ax = plt.subplots(figsize=(7, 3.4))
+    colors = labforge.palette()
+
+    def quantiles(draws):
+        draws = np.asarray(draws)
+        probs = (np.arange(1, len(draws) + 1) - 0.5) / len(draws)
+        theory = np.array([NormalDist().inv_cdf(p) for p in probs])
+        sample = np.sort((draws - np.mean(draws)) / np.std(draws, ddof=1))
+        return theory, sample
+
+    if isinstance(data, ScanResult):
+        for params, draws in data:
+            theory, sample = quantiles(draws)
+            label = ", ".join(f"{key} = {params[key]:g}" for key in data.keys)
+            ax.plot(theory, sample, linewidth=1.2, alpha=0.7, label=label)
+    else:
+        theory, sample = quantiles(data)
+        ax.plot(theory, sample, linewidth=0, marker=".", markersize=3, color=colors.data)
+    lims = ax.get_xlim()
+    ax.plot(lims, lims, color=colors.model, linewidth=1.2, linestyle="--", label="diagonal")
+    ax.legend()
+    ax.set_xlabel("normal quantile")
+    ax.set_ylabel("sample quantile")
+    labforge.style(fig, ax)
+    return fig, ax
+
+
+lab.add_viz(
+    qq_plot,
+    "Q-Q plot",
+    "Standardized order statistics of the draw against standard-normal "
+    "quantiles. A Gaussian sample lies on the dashed diagonal, and "
+    "standardizing collapses every grid point of a scan onto the same line.",
+)
+
+
+def moments(data):
+    """Sample moments and the standard error of the mean; one row per grid point on a scan."""
+
+    def row(draws):
+        mean, std = float(np.mean(draws)), float(np.std(draws, ddof=1))
+        return {"mean": mean, "std": std, "se(mean)": std / np.sqrt(len(draws))}
+
+    if isinstance(data, ScanResult):
+        return [{**params, **row(draws)} for params, draws in data]
+    return row(data)
+
+
+lab.add_analysis(
+    moments,
+    "Moments",
+    "The sample mean and standard deviation estimate μ and σ directly, and "
+    "for the normal family they are also the maximum-likelihood estimators. "
+    "The standard error of the mean shrinks like 1/√n.",
+)
+
+
+# The gamma worker. Registering a second worker turns the top bar into a model
+# selector, and add_viz/add_analysis below attach to this worker, not the normal
+# one, so each model owns its own tabs.
+def sample_gamma(shape=2.0, scale=1.0, n=2000, seed=42):
+    """Draw n gamma variates; reproducible for a given seed."""
+    return np.random.default_rng(seed).gamma(shape, scale, n)
+
+
+lab.add_worker(
+    sample_gamma,
+    {
+        "shape": Param(default=2.0, bounds=(0.5, 10), scan=True, help="Shape parameter k"),
+        "scale": Param(default=1.0, bounds=(0.1, 4), scan=True, help="Scale parameter θ"),
+        "n": Param(kind="int", default=2000, bounds=(10, 100_000), help="Sample size of the draw"),
+        "seed": Param(kind="int", help="Seed of the random generator"),
+    },
+    name="Gamma",
+)
+
+
+def gamma_density(x, shape, scale):
+    """The gamma density at x for shape k and scale θ."""
+    return x ** (shape - 1) * np.exp(-x / scale) / (scale**shape * gamma_func(shape))
+
+
+def gamma_histogram(data, bins=40):
+    """Density histogram of the draw; a scan overlays one histogram per point."""
+    fig, ax = plt.subplots(figsize=(7, 3.4))
+    if isinstance(data, ScanResult):
+        for params, draws in data:
+            label = ", ".join(f"{key} = {params[key]:g}" for key in data.keys)
+            ax.hist(draws, bins=bins, density=True, alpha=0.5, label=label)
+    else:
+        colors = labforge.palette()
+        ax.hist(data, bins=bins, density=True, color=colors.data, label="draw")
+        # The method-of-moments fit: shape and scale from the sample mean and variance.
+        mean, var = np.mean(data), np.var(data, ddof=1)
+        shape, scale = mean**2 / var, var / mean
+        x = np.linspace(np.min(data), np.max(data), 400)
+        ax.plot(
+            x,
+            gamma_density(x, shape, scale),
+            color=colors.model,
+            linewidth=1.6,
+            label="fitted density",
+        )
+    ax.legend()
+    ax.set_xlabel("x")
+    ax.set_ylabel("density")
+    labforge.style(fig, ax)
+    return fig, ax
+
+
+lab.add_viz(
+    gamma_histogram,
+    "Histogram",
+    "Density-normalized histogram of the most recent draw, with the "
+    "method-of-moments gamma density on top. On a scan, one translucent "
+    "histogram per grid point shows how the shape sharpens and the scale "
+    "stretches the density.",
+    {"bins": Param(kind="int", default=40, bounds=(5, 200))},
+)
+
+
+def gamma_fit(data):
+    """Method-of-moments shape and scale from the sample moments; one row per grid point on a scan."""
+
+    def row(draws):
+        mean, var = float(np.mean(draws)), float(np.var(draws, ddof=1))
+        return {"shape": mean**2 / var, "scale": var / mean, "mean": mean}
+
+    if isinstance(data, ScanResult):
+        return [{**params, **row(draws)} for params, draws in data]
+    return row(data)
+
+
+lab.add_analysis(
+    gamma_fit,
+    "Fit",
+    "The mean is kθ and the variance is kθ², so the method of moments recovers "
+    "the shape as X̄²/s² and the scale as s²/X̄. The maximum-likelihood shape "
+    "has no closed form for this family, so the sample moments are the quick "
+    "estimate.",
+)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run the labforge Gaussian demo.")
+    parser.add_argument(
+        "--browser",
+        nargs="?",
+        const=0,
+        type=int,
+        metavar="PORT",
+        help="serve to the default web browser (0 picks a free port)",
+    )
+    parser.add_argument("--scroll", action="store_true", help="one scrolling page, no rail")
+    parser.add_argument("--theme", choices=labforge.themes(), help="colour scheme")
+    args = parser.parse_args()
+
+    # Only pass theme when --theme asks for one: open() already defaults to it,
+    # so the demo never carries its own copy to drift.
+    opts = {"layout": "scroll" if args.scroll else "pages"}
+    if args.theme:
+        opts["theme"] = args.theme
+    if args.browser is not None:
+        lab.open("browser", port=args.browser, **opts)
+    else:
+        lab.open(**opts)