baol · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
@@ -15,16 +15,8 @@ PDFCube selects the matching shader dialect after the context is current.
 | Windows | GTK UCRT64 | Build, CLI, MSI assembly and extraction smoke test | Manual installed-MSI rendering test |
 | macOS | GTK/Homebrew | Build, CLI, DMG assembly and signature verification | Manual installed-DMG rendering test |
 
-KDE, GNOME, and other desktop environments are not separate renderer targets;
-they are covered through GTK's X11 and Wayland backends. GPU and driver
-combinations are only considered verified after they appear in this matrix.
+KDE, GNOME, and other desktop environments use GTK's X11 and Wayland backends.
 
-## Out of scope for the current release
-
-- OpenGL 2.x and OpenGL ES 2.x
-- Vulkan, Metal, and Direct3D renderers
-- Vendor-trusted Windows Authenticode signatures and Apple notarization
-
-Those trust integrations require project-owned signing identities. Automated
-CI packages are still checked for complete assembly and basic execution, but
-that does not replace rendering tests on installed native packages.
+Native packages use GTK's platform integration and bundle the supporting runtime
+libraries. Automated package checks cover assembly and basic execution; installed
+packages receive the rendering smoke tests listed above.
diff --git a/INSTALL b/INSTALL
@@ -7,8 +7,10 @@ Requirements
 PDFCube requires a C++20 compiler, Meson 1.3 or newer, Ninja, GTK 4.12 or
 newer, Poppler GLib 22.0 or newer, Cairo, libepoxy, and Boost Program Options.
 The renderer supports desktop OpenGL and OpenGL ES 3 contexts.
-Python 3, Xvfb, Xauth, and a software OpenGL driver such as Mesa DRI are
-needed to run the complete rendering test suite on Linux. Windows builds use
+Linux tests use Python 3, Pillow, EGL development headers, DejaVu fonts,
+dbus-run-session, and a software OpenGL driver such as Mesa DRI. Transition
+frames use surfaceless EGL; the GTK integration smoke test uses Xvfb and Xauth.
+See tests/README.md for the test contract. Windows builds use
 the MSYS2 UCRT64 GTK, Poppler, libepoxy, and Boost packages. macOS builds use
 their Homebrew equivalents.
 

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # PDFCube
 
-The [transition roadmap and review gallery](docs/transitions/README.md) describes
-new effects, their validation gates, and how to generate videos and contact sheets.
+The [transition design and gallery](docs/transitions/README.md) describes
+the effects and how to generate videos and contact sheets.
 Ready-to-open [example PDFs](examples/transitions/README.md) are included.
 A self-contained [LaTeX/Beamer showcase](examples/showcase/README.md) covers
 all standard PDF transitions with vector artwork and next-effect labels.
@@ -14,8 +14,8 @@ compressing slide blocks in all four PDF directions. Dissolve fractures the
 outgoing slide into deterministic glass shards that clear to reveal the next page.
 Glitter releases directional fragments with brief warm sparks. Wipe sweeps a
 3D wiper with a bowed spine, pressure brackets and subtle flex across the slide in all four cardinal directions, revealing
-the next page without stretching either image. Fade remains the next planned
-effect; Replace is instant.
+the next page with each image fitted to its own aspect ratio. Fade exchanges
+light between stationary slides with gently eased timing; Replace is instant.
 
 [![CI](https://github.com/baol/pdfcube/actions/workflows/ci.yml/badge.svg)](https://github.com/baol/pdfcube/actions/workflows/ci.yml)
 
@@ -24,10 +24,8 @@ transitions, programmed slide timing, and keyboard-controlled zoom regions.
 It is especially useful for slide decks produced by LaTeX Beamer and office
 suites.
 
-The current PDFCube release is a complete modernization of the original
-application. It uses C++20, GTK 4 `GtkGLArea`, shader-based OpenGL/OpenGL ES 3,
-libepoxy, Poppler GLib, Cairo, Boost Program Options, and Meson. The obsolete
-GtkGLExt, fixed-function OpenGL, and Autotools implementation has been removed.
+PDFCube uses C++20, GTK 4 `GtkGLArea`, shader-based OpenGL/OpenGL ES 3,
+libepoxy, Poppler GLib, Cairo, Boost Program Options, and Meson.
 
 <!-- showcase-video:start -->
 
@@ -57,8 +55,8 @@ sudo apt install python3 python3-pil dbus-daemon libegl-dev libgl1-mesa-dri font
 ```
 
 Frame tests render explicit progress values in one headless context per case;
-they do not wait through animation durations. Every test has a 500 ms
-timing SLO, checked before pushing, including cold graphics setup. Timing misses are
+synthetic progress makes each capture independent of playback duration.
+Every test has a 500 ms timing SLO, checked before pushing, including cold graphics setup. Timing misses are
 reported separately from functional failures. See
 [the test contract](tests/README.md). The optional review gallery additionally
 requires Xvfb, Xauth, and ffmpeg.
@@ -78,8 +76,7 @@ pacman -S --needed mingw-w64-ucrt-x86_64-{toolchain,meson,ninja,python,gtk4,libe
 The renderer selects GLSL 1.30 or GLSL ES 3.00 to match the context supplied
 by GTK. Linux is tested on X11 and Wayland; CI also compiles and exercises the
 command-line interface on Windows and macOS. Actual GPU/driver combinations
-are tracked in [COMPATIBILITY.md](COMPATIBILITY.md) rather than assumed to work
-untested.
+are tracked in [COMPATIBILITY.md](COMPATIBILITY.md) with their validation status.
 
 ## Build and install
 
@@ -93,9 +90,9 @@ sudo meson install -C build
 Build the Beamer showcase explicitly with `meson compile -C build doc`.
 This documentation target requires TeX Live with Beamer and PGF/TikZ;
 see the [showcase build instructions](examples/showcase/README.md).
-The default application build does not build documentation.
+The `doc` target builds documentation separately from the default application target.
 
-For a local build without installation:
+Run directly from a local build:
 
 ```sh
 ./build/src/pdfcube presentation.pdf
@@ -116,7 +113,7 @@ options remain available:
 - `--program n:x:...` programs durations and transition types, including cube
   (`c`), plain (`p`), and the documented PDF effects.
 - `--performance-log timings.csv` buffers animation frame timings and writes
-  them on exit, without file I/O during motion.
+  them on exit, keeping file I/O outside active animation.
 - `--no-fullscreen` starts in a window.
 
 When no PDF is supplied, PDFCube opens a GTK file chooser. Options can also
@@ -135,20 +132,19 @@ See `man pdfcube` for the full list.
 
 ### Frame pacing
 
-PDFCube follows GTK's compositor-synchronized frame clock rather than imposing
-a fixed frame rate. Full-resolution previous and next pages are rendered in the
+PDFCube follows GTK's compositor-synchronized frame clock. Full-resolution previous and next pages are rendered in the
 background and uploaded to the GPU while the current slide is idle. If a page
 is not ready when navigation is requested, the transition remains at its exact
-first frame until preparation finishes; PDF rendering and texture upload do not
-consume the active animation clock.
+first frame until preparation finishes. The animation clock starts once both
+full-resolution textures are ready.
 
 Use `--performance-log timings.csv` with a representative presentation. The CSV
 records displayed-frame intervals, CPU submission time, and whether a frame was
 the stationary preparation frame. At 60 Hz, animation-frame intervals
 should remain close to 16,667 microseconds; at 120 Hz, close to 8,333. CPU
-submission does not include asynchronous GPU completion, but interval spikes
-expose visible compositor or rendering stalls. Slide texture resolution is never
-reduced to meet a frame budget.
+submission measures CPU work; GPU completion is asynchronous. Interval spikes
+help identify compositor or rendering stalls. Slides retain full texture resolution
+throughout the animation.
 
 ## Tests
 
@@ -157,10 +153,13 @@ meson test -C build --print-errorlogs
 ```
 
 The suite checks the public command-line contract and produces deterministic
-headless rendering snapshots under Xvfb. It covers page rendering, cube and
+headless rendering snapshots in surfaceless EGL contexts, plus one GTK
+integration snapshot under Xvfb. It covers page rendering, cube and
 plain programs, configured colors, and command-line-over-config precedence.
 `--snapshot` and `--snapshot-progress` are private regression-test hooks.
 
+See the [documentation and usability roadmap](docs/ROADMAP.md) for planned improvements.
+
 ## Release and packaging
 
 Meson can produce a tested source archive with:

diff --git a/RELEASING.md b/RELEASING.md
@@ -50,14 +50,10 @@ Linux, macOS, and Windows packages build independently. The publish job waits
 for all three platforms, verifies every expected artifact, and only then creates
 the automatic tag and GitHub Release. Pull requests build and smoke-test the DMG
 and MSI as downloadable workflow artifacts, preventing release-only failures.
-The current automated packages are ad-hoc signed on macOS and unsigned on
-Windows; notarization and Authenticode signing require project-owned signing
-identities and should be added before presenting either package as trusted by
-the operating-system vendor.
 
 The release build explicitly enables `-Dinstall_docs=true` and invokes the
 Meson `doc` target before staging the AppImage. Debian's build rules enable
-that option and invoke `doc` independently, so packages do not depend on a PDF
-left over from another build. The standalone PDF is copied into `release-assets`
+that option and invoke `doc` independently, producing the PDF during each package
+build. The standalone PDF is copied into `release-assets`
 before checksums are generated. Missing documentation fails the package or
 release checks.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -0,0 +1,115 @@
+# Documentation and usability roadmap
+
+This review covers the README, manual, install instructions, compatibility guide,
+transition design, diagnostic examples, Beamer showcase, CLI help, and application
+key handling. It compares their descriptions with the current source code.
+
+## 1. Give readers a clear first-run path
+
+The README opens with a long catalogue of rendering details; installation and
+controls come later. Release binaries are described in the packaging section,
+while the opening path assumes a source build.
+
+Lead with a short product description, the showcase, a link to release downloads,
+and one command to open a PDF. Follow with a compact controls table and links to
+source builds, transition design, and maintainer documentation. Keep the detailed
+motion descriptions in the transition document.
+
+Acceptance: a new user can find a suitable download, open a deck, advance, go
+back, toggle automatic playback, and quit from the first screen of instructions.
+Check the path on Linux, Windows, and macOS.
+
+## 2. Make the feature and control reference consistent
+
+Fade reached the renderer before the README, showcase labels, manual, and CLI
+help were updated. The numeric-page formula in the manual used an internal
+zero-based index. Test dependencies also differed between README and INSTALL.
+The accompanying documentation edits align these descriptions; CLI help still
+needs Fade added to its effect list.
+
+Create a small authoritative effect catalogue for names, program tokens, PDF
+mapping, and applicable parameters. Use it for CLI help and documentation checks.
+Keep one user-facing controls reference linked from the README and showcase.
+Describe `/Dur`, `/Trans /D`, programmed dwell, and automatic playback together,
+with one worked example. Include `t` in the README's common controls.
+
+Acceptance: every implemented effect appears in help, the manual, diagnostic
+examples, and showcase with matching names. Examples match the parser. Page
+shortcuts use visible page numbers. Validate local links and the generated man
+page as part of documentation checks.
+
+## 3. Complete and validate `--program`
+
+The current implementation selects every implemented effect, including Fade,
+through `duration:type` pairs. It repeats the final pair and applies each effect
+to the following slide, including wraparound. Animation duration is fixed at
+750 ms; axis, direction, and other effect parameters come from the PDF.
+
+The remaining work is input validation and a complete, documented contract.
+Unknown effect names currently select an instant change. Duration parsing uses
+`std::stod` with a conversion to integer milliseconds, accepting numeric prefixes
+and leaving finite-value and range checks implicit. Incomplete pairs, empty
+fields, and entries beyond the page count also need explicit handling. CLI help
+needs to list Fade.
+
+Define the grammar and validate the entire program before applying it. Require
+complete pairs, recognized tokens, and finite durations representable in the
+scheduler's millisecond range. Return actionable errors identifying the offending
+pair. Define zero-duration behavior, the final-pair repetition rule, wraparound,
+and precedence over PDF timing. Preserve the existing `c` and `p` tokens.
+Use the shared effect catalogue from priority 2 for program names and help.
+
+Assess whether full programming should also expose animation duration, direction,
+axis, and Fly parameters. Record the chosen scope before extending the syntax;
+keep existing programs compatible and document PDF parameter inheritance.
+
+Acceptance: parser and playback tests cover every effect token, fractional and
+zero dwell times, repeated final pairs, wraparound, one-page decks, PDF overrides,
+and CLI/config precedence. Invalid-input cases cover unknown tokens, empty or
+incomplete pairs, trailing garbage, negative/nonfinite/overflowing durations, and
+extra pairs. Validate every input pair even when the deck is shorter than the
+program. Tests assert deterministic errors and scheduled delays using injected
+time and a recording scheduler.
+
+## 4. Add help at the moment of presentation
+
+Application key handling exposes many commands, while discovering them requires
+leaving the presentation to read the manual. Automatic playback toggles with `t`
+but provides no explicit mode indicator in the current key-handling path.
+File and renderer errors are printed to standard error, which makes failures
+hard to discover when launching from the desktop.
+
+Add a keyboard-help overlay opened by `?` or F1. Group controls into navigation,
+zoom, playback, and exit. Show the current page and automatic-playback state in
+a short-lived status overlay when those states change. Show file and graphics
+errors in an actionable dialog with a way to choose another PDF or exit. Keep focus and keyboard
+behavior predictable when overlays open and close.
+
+Acceptance: help is readable over light and dark slides, works in fullscreen
+and windowed modes, and can be dismissed by keyboard. Page numbers match the
+manual. Desktop-launched failures produce a visible explanation. Overlay
+visibility follows injected time and scheduler tests; exported
+frames remain tied to the presentation content.
+
+## 5. Keep the presentation and documentation current
+
+The transition document accumulated implementation history, profiling results,
+approval labels, and product descriptions in one place. The accompanying rewrite
+makes it a reference for current behavior. Historical measurements belong in
+commit/PR records; future changes belong here.
+
+Use the Beamer showcase as the main visual introduction and diagnostic PDFs for
+parameter inspection. Add a short documentation checklist to feature changes:
+help, manual, examples, showcase labels, and transition design. Generate or
+validate repeated feature lists and check local links. Keep platform evidence in
+the compatibility guide and test procedures in the test contract.
+
+Acceptance: product docs describe current behavior in positive terms; future
+work is collected in the roadmap. Showcase labels describe the rendered effect,
+and generated media identifies its source revision. A reviewer can trace each
+example to its generator and reproduce its output.
+
+Implement in this order: first-run documentation, reference consistency,
+`--program` completion, presentation help, then automated documentation checks.
+Program validation and presentation help are separate application changes; the
+documentation and consistency work can ship in small increments.