phepex 0.2.0__tar.gz → 0.2.2__tar.gz

{phepex-0.2.0 → phepex-0.2.2}/.gitignore

@@ -8,3 +8,5 @@ docs/_doxygen/
 docs/Doxyfile
 include/phepex/version.hpp
 wheelhouse/
+docs/slides/*.pdf
+docs/_static/slides/

{phepex-0.2.0 → phepex-0.2.2}/CHANGELOG.md

@@ -9,6 +9,32 @@ numbers are derived from git tags (`vX.Y.Z`) by setuptools-scm (Python) and GitV
 
 ## [Unreleased]
 
+### Changed
+- The Deriche smoothing pass (`smooth_waveform` and its batched counterpart
+  `smooth_batched`) now evaluates its recursion entirely in float32. The coefficients are
+  narrowed to float once on entry, so the products in the forward and backward loops no
+  longer promote to double, and the backward pass carries float state. Measured with the
+  per-kernel micro-benchmark on Apple M1 Pro (1764-pixel FlashCam, 22 samples, upsampling
+  4): smoothing alone 163 -> 96 us/event (-41%), upsampling + smoothing 1148 -> 837
+  us/event (-27%), the tiled full sweep `preprocess up/pz/smoothing batch` 213 -> 165
+  us/event (-23%). The numerical deviation was quantified against a long double evaluation
+  of the same recursion in `tests/cpp/test_smoothing_precision.cpp`: ~10^-7 relative on
+  the samples, < 10^-3 p.e. on the extracted charge and < 10^-4 upsampled samples on the
+  centroid. The error does not accumulate with trace length; it grows with FWHM as
+  1/(1-r)^2, reaching ~10^-6 relative at FWHM 20. Both the impulse-response width and the
+  unity DC gain are preserved (< 10^-4 and ~10^-6 deviation respectively).
+
+## [0.2.1] - 2026-07-30
+
+### Changed
+- Documentation and docstrings revised for accuracy and consistency across the README, the
+  Sphinx pages, the C++ header comments and the Python/binding docstrings.
+
+### Added
+- Introductory slide deck (`docs/slides/phepex-intro.typ`, [Typst](https://typst.app)): eight
+  slides on where phepex sits relative to libdvr and ctapipe, the kernels it exposes, and the
+  0.2.0 benchmark figures.
+
 ## [0.2.0] - 2026-07-28
 
 ### Changed
@@ -206,6 +232,7 @@ numbers are derived from git tags (`vX.Y.Z`) by setuptools-scm (Python) and GitV
 - Unified Sphinx documentation covering the C++ (Doxygen + Breathe) and Python (autodoc)
   API surfaces, published to GitHub Pages.
 
-[Unreleased]: https://github.com/phepex/phepex/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/phepex/phepex/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/phepex/phepex/releases/tag/v0.2.1
 [0.2.0]: https://github.com/phepex/phepex/releases/tag/v0.2.0
 [0.1.0]: https://github.com/phepex/phepex/releases/tag/v0.1.0

{phepex-0.2.0 → phepex-0.2.2}/CMakeLists.txt

@@ -114,6 +114,7 @@ if(PHEPEX_BUILD_TESTS)
   enable_testing()
   add_executable(phepex_tests
       tests/cpp/test_phepex.cpp
+      tests/cpp/test_smoothing_precision.cpp
       third_party/catch2/catch_amalgamated.cpp)
   target_include_directories(phepex_tests PRIVATE third_party/catch2)
   target_link_libraries(phepex_tests PRIVATE phepex::phepex)

{phepex-0.2.0 → phepex-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phepex
-Version: 0.2.0
+Version: 0.2.2
 Summary: Photo-electron pulse extraction: fast PMT/SiPM waveform charge & timing extraction for Python.
 Keywords: waveform,charge-extraction,PMT,SiPM,Cherenkov,signal-processing,DSP
 Author: Max-Planck-Institut für Kernphysik
@@ -26,10 +26,11 @@ Description-Content-Type: text/markdown
 
 # phepex — photo-electron pulse extraction
 
-Fast numeric kernels for extracting charge and timing from digitised PMT/SiPM
-waveforms (e.g. Cherenkov telescopes or Water Cherenkov Detectors): pole-zero
+Compiled numeric kernels for extracting charge and timing from digitised PMT/SiPM
+waveforms (e.g. from Cherenkov telescopes or Water Cherenkov Detectors): pole-zero
 deconvolution + upsampling, neighbour-sum peak finding, soft clipping, window
-integration and leading-edge timing — plus a fast waveform generator for testing.
+integration and leading-edge timing — plus a waveform generator for tests and
+benchmarks.
 
 The heavy lifting runs in a compiled extension; `import phepex` needs only numpy.
 
@@ -43,14 +44,15 @@ pip install phepex
 
 ```python
 import phepex
-# phepex.deconvolve, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
+# phepex.preprocess, phepex.deconvolve, phepex.preprocess_valid_range,
+# phepex.deconvolve_valid_range, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
 # phepex.extract_around_peak, phepex.adaptive_centroid, phepex.generate_waveforms
 ```
 
 The ctapipe-integrated `phepex.extractor.FastFlashCamExtractor` — a drop-in
-accelerating ctapipe's `FlashCamExtractor` (typically ~5× faster end-to-end, with
-bit-exact / ~1e-7 agreement on signal pixels) — lives in a separate submodule
-imported on demand. It needs the `bench` extra:
+accelerating ctapipe's `FlashCamExtractor` (typically ~5× faster end-to-end, agreeing
+on signal-pixel charge to a median relative deviation of ~1e-7) — lives in a separate
+submodule imported on demand. It needs the `bench` extra:
 
 ```bash
 pip install phepex[bench]      # pulls in ctapipe

{phepex-0.2.0 → phepex-0.2.2}/README.md

@@ -1,16 +1,16 @@
 # phepex — photo-electron pulse extraction
 
 <!-- intro:start -->
-A small, dependency-free **C++17 library** of the numeric kernels used to extract charge and timing from digitised PMT/SiPM (e.g. Cherenkov telescopes or Water Cherenkov Detectors) waveforms — pole-zero deconvolution + upsampling, neighbour-sum peak finding, soft clipping, window integration and leading-edge timing — plus a fast waveform generator for testing.
+A dependency-free **C++17 library** of the numeric kernels used to extract charge and timing from digitised PMT/SiPM waveforms (e.g. from Cherenkov telescopes or Water Cherenkov Detectors) — pole-zero deconvolution + upsampling, neighbour-sum peak finding, soft clipping, window integration and leading-edge timing — plus a waveform generator for tests and benchmarks.
 
-Ships **`libphepex.so`** and **`libphepex.a`**, public headers under `phepex/`, and optional **Python bindings** (`import phepex`).
+Ships `libphepex.so` and `libphepex.a`, public headers under `phepex/`, and optional **Python bindings** (`import phepex`).
 
-The C++ library depends only on the C++ standard library, so it drops into any C++ project. `ctapipe` is used only by the Python benchmark/extractor layer, never by the library itself.
+The C++ library depends only on the C++ standard library, so it drops into any C++ project. `ctapipe` is used only by the Python benchmark/extractor layer, not by the library itself.
 <!-- intro:end -->
 
 ## Documentation
 
-Full API documentation covering **both** the C++ and Python surfaces is published to GitHub Pages: **https://phepex.github.io/phepex/** (built from source by the `docs` workflow on every push to `main`). Build it locally with:
+API documentation for both the C++ and Python surfaces is published to **https://phepex.github.io/phepex/**, rebuilt from source by the `docs` workflow on every push to `main`. Build it locally with:
 
 ```bash
 pip install .[bench] && pip install -r docs/requirements.txt
@@ -24,8 +24,10 @@ All kernels are free functions in namespace `phepex`, operating on caller-owned
 
 ```cpp
 #include <phepex/phepex.hpp>
-// phepex::preprocess_waveform(wf, n_samples, upsampling, pole_zero, smoothing, offset, scale, out);
-// phepex::pos_soft_clip / neighbor_peak_indices / extract_around_peak / adaptive_centroid / generate_waveforms
+// preprocess_waveform / preprocess_waveforms (batched) / preprocess_valid_range
+//   / calculate_smoothing_coefficients / preprocess_waveforms_scratch_size
+// pos_soft_clip / neighbor_peak_indices / extract_around_peak / adaptive_centroid
+// generate_waveforms / generate_shower_image
 ```
 
 Build & install:
@@ -64,7 +66,7 @@ bindings automatically.
 | `PHEPEX_BUILD_EXAMPLES` | `OFF` | Build the C++ example (`examples/example.cpp`). |
 | `PHEPEX_BUILD_TESTS` | `OFF` | Build the standalone C++ unit tests (vendored Catch2). |
 | `PHEPEX_BUILD_BENCHMARKS` | `OFF` | Build the C++ per-kernel micro-benchmark. |
-| `PHEPEX_NEIGHBOR_PAIRWISE_SUM` | `ON` | Accumulate the neighbour sum in `neighbor_peak_indices` pairwise (~18-22% faster on the benchmarked aarch64 core; see the CHANGELOG for the measurement). `OFF` selects the sequential sum, which is what ctapipe computes; pairwise grouping alters the float32 summation order, so the peak index can differ in near-ties within ~1 ULP. See the note in `include/phepex/neighbor.hpp`. |
+| `PHEPEX_NEIGHBOR_PAIRWISE_SUM` | `ON` | Accumulate the neighbour sum in `neighbor_peak_indices` pairwise (~18–22% faster on the benchmarked aarch64 core; see the CHANGELOG for the measurement). `OFF` selects the sequential sum, bit-identical to a left-to-right accumulation in CSR order; pairwise grouping alters the float32 summation order, so the peak index can differ in near-ties within ~1 ULP. See the note in `include/phepex/neighbor.hpp`. |
 | `PHEPEX_PREPROCESS_TILE_WIDTH` | `24` | Number of waveforms mapped onto SIMD lanes per tile in the batched `preprocess_waveforms` path. Bit-identical for any value `>= 1`; performance only. See the tuning notes below. |
 
 ### Tuning `PHEPEX_PREPROCESS_TILE_WIDTH`
@@ -83,9 +85,9 @@ Recommendations:
   that inside L1; above it the tiles spill and the gain reverses.
 - Build the micro-benchmark (`-DPHEPEX_BUILD_BENCHMARKS=ON
   -DCMAKE_CXX_FLAGS="-march=native" -DPHEPEX_PREPROCESS_TILE_WIDTH=K`) at a few widths and
-  compare the `preprocess up/pz(/smoothing) batch` rows
-- `24` (the default) works best for Apple Silicon (NEON) and Zen 4 architectures, even though
-  the latter supports AVX-512 (float SIMD width of 16).
+  compare the `preprocess up/pz(/smoothing) batch` rows.
+- `24` (the default) measured best on both Apple Silicon (NEON) and Zen 4, even though the
+  latter supports AVX-512 (float SIMD width of 16).
 
 To obtain an optimised Python wheel, pass it through scikit-build-core, e.g.
 `CMAKE_CXX_FLAGS="-march=native" pip install . -C cmake.define.PHEPEX_PREPROCESS_TILE_WIDTH=K`.
@@ -99,7 +101,8 @@ pip install .            # builds the phepex wheel (scikit-build-core + nanobind
 
 ```python
 import phepex
-# phepex.deconvolve, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
+# phepex.preprocess, phepex.deconvolve, phepex.preprocess_valid_range,
+# phepex.deconvolve_valid_range, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
 # phepex.extract_around_peak, phepex.adaptive_centroid, phepex.generate_waveforms
 ```
 
@@ -136,15 +139,17 @@ ctest --test-dir build --output-on-failure     # or: ./build/phepex_tests
 
 ## C++ micro-benchmark (no Python/ctapipe)
 
-`benchmarks/cpp/microbench.cpp` times each `phepex::` kernel in isolation on a realistic
-camera configuration, so a regression can be attributed to a specific kernel. It links only
-`libphepex` and reads the configuration at run time from a text file, so it needs neither
-Python nor ctapipe. One "op" is one full-camera sweep (the per-event cost). The input is one
-artificial event — a skewed-Gaussian shower image over ~200 pixels at ~1–100 p.e. with a
-~1 ns/pixel time gradient, plus 200 MHz NSB on a 200 LSB pedestal, digitised to 12-bit ADC
-counts — because the peak-search and centroid kernels are data-dependent. The image is sized
-in pixel pitches, so a config for another camera gives a comparable event without code
-changes.
+`benchmarks/cpp/microbench.cpp` times each `phepex::` kernel in isolation, so a regression
+can be attributed to a specific kernel. It links only `libphepex` and reads the camera
+configuration at run time from a text file, so it needs neither Python nor ctapipe. One "op"
+is one full-camera sweep (the per-event cost); the reported statistic is the minimum over
+all reps.
+
+Because the peak-search and centroid kernels are data-dependent, the input is one realistic
+artificial event: a skewed-Gaussian shower image over ~200 pixels at ~1–100 p.e. with a
+1 ns/pixel-pitch time gradient, plus 200 MHz NSB on a 200 LSB pedestal, digitised to 12-bit
+ADC counts. Image axes and gradient are expressed in pixel pitches, so a config for another
+camera gives a comparable event without code changes.
 
 ```bash
 cmake -S . -B build -DPHEPEX_BUILD_BENCHMARKS=ON -DCMAKE_CXX_FLAGS="-march=native"
@@ -172,7 +177,7 @@ python3 scripts/export-camera-config.py --camera FlashCam \
 python3 benchmarks/benchmark-fast-extractor.py --events 5000
 ```
 
-Typical result: **~5× faster** end-to-end (leading-edge timing on), with bit-exact / ~1e-7 agreement on signal pixels. Tests: `python3 -m pytest tests/ -q`.
+Typical result: **~5× faster** end-to-end (leading-edge timing on). Extracted charge agrees with stock ctapipe to a median relative deviation of ~1e-7 on signal pixels (99th percentile ~2e-5); a small tail differs materially where the neighbour peak search lands on a different local maximum. See `benchmarks/README.md` for the per-step breakdown and the cause of that tail. Tests: `python3 -m pytest tests/ -q`.
 <!-- benchmark:end -->
 
 ## Notes

{phepex-0.2.0 → phepex-0.2.2}/README.pypi.md

@@ -1,9 +1,10 @@
 # phepex — photo-electron pulse extraction
 
-Fast numeric kernels for extracting charge and timing from digitised PMT/SiPM
-waveforms (e.g. Cherenkov telescopes or Water Cherenkov Detectors): pole-zero
+Compiled numeric kernels for extracting charge and timing from digitised PMT/SiPM
+waveforms (e.g. from Cherenkov telescopes or Water Cherenkov Detectors): pole-zero
 deconvolution + upsampling, neighbour-sum peak finding, soft clipping, window
-integration and leading-edge timing — plus a fast waveform generator for testing.
+integration and leading-edge timing — plus a waveform generator for tests and
+benchmarks.
 
 The heavy lifting runs in a compiled extension; `import phepex` needs only numpy.
 
@@ -17,14 +18,15 @@ pip install phepex
 
 ```python
 import phepex
-# phepex.deconvolve, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
+# phepex.preprocess, phepex.deconvolve, phepex.preprocess_valid_range,
+# phepex.deconvolve_valid_range, phepex.pos_soft_clip, phepex.neighbor_peak_indices,
 # phepex.extract_around_peak, phepex.adaptive_centroid, phepex.generate_waveforms
 ```
 
 The ctapipe-integrated `phepex.extractor.FastFlashCamExtractor` — a drop-in
-accelerating ctapipe's `FlashCamExtractor` (typically ~5× faster end-to-end, with
-bit-exact / ~1e-7 agreement on signal pixels) — lives in a separate submodule
-imported on demand. It needs the `bench` extra:
+accelerating ctapipe's `FlashCamExtractor` (typically ~5× faster end-to-end, agreeing
+on signal-pixel charge to a median relative deviation of ~1e-7) — lives in a separate
+submodule imported on demand. It needs the `bench` extra:
 
 ```bash
 pip install phepex[bench]      # pulls in ctapipe

{phepex-0.2.0 → phepex-0.2.2}/benchmarks/README.md

@@ -1,7 +1,8 @@
 # Comparative benchmark: stock ctapipe vs phepex
 
 Compares ctapipe's `FlashCamExtractor` against `phepex.extractor.FastFlashCamExtractor`
-(same algorithm, numeric kernels in C++) on a realistic synthetic workload:
+(same algorithm bar one documented divergence, numeric kernels in C++) on a synthetic
+workload:
 
 - unique gamma-like events for a **1764-pixel FlashCam-MST** camera
 - **200 MHz night-sky background** (temporally-distributed Poisson p.e.)
@@ -26,10 +27,28 @@ python3 benchmarks/benchmark-fast-extractor.py --events 5000
 ```
 
 Typical result: **~5× faster** end-to-end with leading-edge timing on (~2700 →
-~600 µs/event), **~4.5×** off. The extracted charge/peak_time match stock ctapipe
-bit-exactly with no NSB and to ~1e-7 on signal pixels (validated in `tests/`).
+~600 µs/event), **~4.5×** off.
+
+Charge agreement with stock ctapipe, measured over 60 events (1764 pixels, upsampling 4,
+22 samples); relative deviations are over signal pixels (true charge > 1 p.e.):
+
+| | no NSB | 200 MHz NSB |
+| --- | --- | --- |
+| signal pixels bit-exact | 40% | 8% |
+| relative deviation, median | 7.4e-8 | 1.0e-7 |
+| relative deviation, 99th percentile | 2.7e-7 | 2.4e-5 |
+| relative deviation, max | 3.2e-7 | O(1) |
+
+Without NSB the deviation is pure float32 rounding, bounded at ~3e-7. With NSB, a small
+tail of pixels differs significantly: the neighbour-sum peak search resolves a near-tie
+between two local maxima differently, or the true peak falls in an edge margin this
+extractor excludes (see the notes below), and the integration window then lands elsewhere.
+`tests/test_extractor_equivalence.py` asserts bounds that admit this tail.
 
 ## Notes
 
 - The deconvolution (two pole-zero passes/event) dominates the extractor runtime (~50%);
   the phepex kernel is ~7–9× faster than ctapipe's scipy `deconvolve`/`repeat`/`filtfilt`.
+- `FastFlashCamExtractor` restricts the clip and neighbour peak search to the non-edge
+  deconvolution samples, so a peak inside an edge margin is found by stock ctapipe but not
+  here. This is the one intentional algorithmic difference.

phepex-0.2.2/docs/_static/slides-viewer.css

@@ -0,0 +1,113 @@
+/* In-page viewer for the Typst slide deck (see docs/slides.md, slides-viewer.js).
+ *
+ * The slides carry their own white background and accent colours, so they are framed rather
+ * than recoloured: inverting them in furo's dark theme would misrender the logo and the
+ * accent fills. The frame and controls follow the theme; the slide itself does not. */
+
+.phepex-deck {
+  margin: 1.5rem 0;
+}
+
+/* The `display` rules below are author-level and would otherwise beat the user agent's
+ * `[hidden] { display: none }`, leaving the controls visible without JavaScript and a broken
+ * image when no SVGs were exported. Class+attribute outranks the bare class, so this needs
+ * no !important. */
+.phepex-deck [hidden] {
+  display: none;
+}
+
+.phepex-deck-stage {
+  display: block;
+  width: 100%;
+  /* Reserve the box before the first SVG loads, so advancing never shifts the page. */
+  aspect-ratio: 16 / 9;
+  background: #fff;
+  border: 1px solid var(--color-background-border);
+  border-radius: 6px;
+  /* The deck is keyboard-operable, so it must show where focus is. */
+  outline-offset: 2px;
+}
+
+.phepex-deck-stage:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+}
+
+/* Click-to-advance only makes sense once the script is driving the deck. */
+.phepex-deck[data-ready="1"] .phepex-deck-stage {
+  cursor: pointer;
+}
+
+.phepex-deck-stage:fullscreen {
+  aspect-ratio: auto;
+  height: 100%;
+  border: 0;
+  border-radius: 0;
+  object-fit: contain;
+}
+
+.phepex-deck-bar {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  justify-content: center;
+  margin-top: 0.5rem;
+  font-size: var(--font-size--small);
+}
+
+.phepex-deck-bar button {
+  min-width: 2.2rem;
+  padding: 0.15rem 0.5rem;
+  color: var(--color-foreground-primary);
+  background: var(--color-background-secondary);
+  border: 1px solid var(--color-background-border);
+  border-radius: 4px;
+  cursor: pointer;
+  font: inherit;
+  line-height: 1.6;
+}
+
+.phepex-deck-bar button:hover {
+  border-color: var(--color-brand-primary);
+}
+
+.phepex-deck-position {
+  min-width: 4.5rem;
+  text-align: center;
+  color: var(--color-foreground-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+/* Shown only when no SVGs were exported; the script reveals it in that case. */
+.phepex-deck-unavailable {
+  color: var(--color-foreground-secondary);
+  font-size: var(--font-size--small);
+}
+
+/* The slide outline: the deck's text alternative, collapsed by default so it does not
+ * restate the slides to a reader who can see them. A plain <details> rather than a
+ * `:class: dropdown` admonition, which furo renders as an ordinary open block, and rather
+ * than a sphinx-design directive, which would add a dependency for one disclosure. Closing
+ * it hides nothing from Sphinx search or from slides-viewer.js: both read the text from the
+ * document, not from what is painted. */
+.phepex-deck-outline-details {
+  margin: 1rem 0;
+  padding: 0.4rem 0.75rem;
+  background: var(--color-background-secondary);
+  border: 1px solid var(--color-background-border);
+  border-radius: 6px;
+  font-size: var(--font-size--small);
+}
+
+.phepex-deck-outline-details > summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.phepex-deck-outline-details[open] > summary {
+  margin-bottom: 0.5rem;
+}
+
+.phepex-deck-outline-details > summary:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+  outline-offset: 2px;
+}

phepex-0.2.2/docs/_static/slides-viewer.js

@@ -0,0 +1,103 @@
+// In-page viewer for the Typst slide deck rendered on docs/slides.md.
+//
+// Each slide is one SVG file swapped into a single <img>, rather than eight SVGs inlined in
+// the page: Typst names every glyph <symbol id="..."> and those ids recur across slides, so
+// inlining would put duplicate ids in one document (see docs/conf.py). The trade-off is that
+// SVG text is glyph outlines, hence the authored outline list the page carries as the
+// accessible and searchable text alternative; alt text is taken from it here.
+//
+// Loaded on every page, so it must do nothing when there is no deck.
+function phepexInitDeck() {
+  "use strict";
+
+  const deck = document.querySelector(".phepex-deck");
+  if (!deck) return;
+
+  const stage = deck.querySelector(".phepex-deck-stage");
+  const bar = deck.querySelector(".phepex-deck-bar");
+  const position = deck.querySelector(".phepex-deck-position");
+  const note = deck.querySelector(".phepex-deck-unavailable");
+  const base = deck.dataset.base || "";
+
+  // One entry per slide, so the outline that supplies the alt text also fixes the slide
+  // count -- the two cannot drift apart here. docs/conf.py checks the list against the
+  // exported deck at build time.
+  const titles = Array.from(document.querySelectorAll(".phepex-deck-outline li"), (li) =>
+    (li.textContent || "").trim().replace(/\s+/g, " "),
+  );
+  const count = titles.length;
+
+  function unavailable() {
+    if (stage) stage.hidden = true;
+    if (bar) bar.hidden = true;
+    if (note) note.hidden = false;
+  }
+
+  // A docs build without Typst exports no SVGs, and nothing in the page says so: the markup
+  // is static and MyST does not substitute into it. Take the first image failing to load as
+  // the signal, which also covers a partial export.
+  if (count < 1 || !stage) return unavailable();
+  stage.addEventListener("error", unavailable);
+
+  const src = (i) => `${base}${i + 1}.svg`;
+  let current = -1;
+
+  function show(index, focus) {
+    const i = ((index % count) + count) % count;
+    if (i === current) return;
+    current = i;
+    stage.src = src(i);
+    const title = titles[i];
+    stage.alt = title
+      ? `Slide ${i + 1} of ${count}: ${title}`
+      : `Slide ${i + 1} of ${count}`;
+    if (position) position.textContent = `${i + 1} / ${count}`;
+    // replaceState, not pushState: paging through the deck must not fill the back button.
+    history.replaceState(null, "", `#slide-${i + 1}`);
+    if (focus) stage.focus();
+    // Warm the next slide so a click or arrow key paints without a fetch.
+    if (count > 1) new Image().src = src((i + 1) % count);
+  }
+
+  stage.addEventListener("click", () => show(current + 1, false));
+
+  stage.addEventListener("keydown", (event) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const step = { ArrowRight: 1, ArrowLeft: -1, PageDown: 1, PageUp: -1 }[event.key];
+    if (step !== undefined) show(current + step, false);
+    else if (event.key === "Home") show(0, false);
+    else if (event.key === "End") show(count - 1, false);
+    else return; // leave every other key to the page (furo binds "/" to search)
+    event.preventDefault();
+  });
+
+  deck.querySelector(".phepex-deck-prev")?.addEventListener("click", () => {
+    show(current - 1, true);
+  });
+  deck.querySelector(".phepex-deck-next")?.addEventListener("click", () => {
+    show(current + 1, true);
+  });
+  deck.querySelector(".phepex-deck-fullscreen")?.addEventListener("click", () => {
+    if (document.fullscreenElement) document.exitFullscreen?.();
+    else stage.requestFullscreen?.();
+  });
+
+  // Deep link: #slide-3 opens on that slide, and the hash stays shareable.
+  const fromHash = () => {
+    const match = /^#slide-(\d+)$/.exec(location.hash);
+    return match ? parseInt(match[1], 10) - 1 : 0;
+  };
+  window.addEventListener("hashchange", () => show(fromHash(), false));
+
+  if (bar) bar.hidden = false;
+  deck.dataset.ready = "1";
+  show(fromHash(), false);
+}
+
+// furo emits html_js_files at the end of <body>, so the deck is normally parsed by now; the
+// guard matches version-switcher.js and keeps this correct if that ever changes.
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", phepexInitDeck);
+} else {
+  phepexInitDeck();
+}