feat: interactive tutorial mode for new users - #28
Merged
striderZA merged 2 commits intoAug 8, 2026
Conversation
New users only had a static "How to Use" reference panel — nothing that actively pointed at a panel and walked them through a real end-to-end workflow, and no notion of a first launch. Adds a `tutorial/` module (sibling to `help/`/`layout/`) providing a data-driven 6-step guided walkthrough that outlines the panel each step talks about and offers Back/Next/Skip/Exit at every point. Changes: - Add tutorial module: TutorialStep catalog, TutorialState (pure navigation + persistence), TutorialWidget (foreground-drawlist highlight + guide window) - Persist completion in an exe-relative .tutorial_completed marker, mirroring LayoutManager, so first-run works on Linux/macOS as well as Windows (SessionState is a Windows-only no-op) - Wire Help > Tutorial and a one-time first-run modal into RfSimulatorApp - Route tutorial start through the existing unsaved-changes guard via PendingAction::Tutorial, so the user's project is never silently discarded - Point users at the tutorial from the help panel - Add tests/test_tutorial_state.cpp (68 assertions) as a standalone binary, matching test_component_authoring's MinGW TEST_CASE-limit workaround - Add 5 ImGui Test Engine UI tests covering menu launch, the dirty-project guard, step navigation, completion persistence, and the first-run prompt - DOX: add tutorial/AGENTS.md, update root, app/, and tests/ docs Fixes #17
Resolve 3 additive conflicts (tutorial module vs. plugin extension system, both landed independently): - app/CMakeLists.txt: keep both new app/src/*.cpp sources (extension manifest/manager, external tool runner, pfb view manager, project serializer) and simulator::tutorial link; use master's RFSIM_APP_VERSION (PROJECT_VERSION is clobbered by FetchContent). - app/include/app.h: keep both new test accessors and both new method declarations (requestTutorial/startTutorial + rewireInputs). - tests/CMakeLists.txt: keep test_tutorial_state alongside master's new standalone test executables.
striderZA
marked this pull request as ready for review
August 8, 2026 14:27
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an interactive, data-driven tutorial mode that guides new users through adding, connecting, configuring, and probing a component, launched from
Help > Tutorialor a one-time first-run prompt.Related issue
Closes #17
Type of change
Test plan
cmake -B build -G Ninja && cmake --build build— clean build, no warningsctest --test-dir build --output-on-failure -E "Benchmark"— 73/73 passedDISPLAY=:0 ./build/bin/test_ui— 27/27 UI tests passed (22 pre-existing + 5 new)build/bin/tiny-rf-simulatorwith the marker file removed — first-run prompt appears once, no crash, marker correctly withheld until dismissed/completedChecklist
.clang-format)clang-format -ion changed files (clang-format-18 --dry-run --Werrorclean on all 11 changed/added C++ files)tests/test_tutorial_state.cpp, 5 new UI tests intest_engine/ui_tests.cpp)What's new
tutorial/module (sibling tohelp//layout/):TutorialCatalog(6-step data-driven catalog),TutorialState(pure navigation state machine + cross-platform exe-relative marker-file persistence),TutorialWidget(highlight border viaGetForegroundDrawList()+ floating guide window with Back/Next/Skip/Exit).Help > Tutorialmenu item launches the walkthrough on demand; a one-time first-run modal offers it on first launch (no marker file present).PendingAction::Tutorial), so an in-progress project is never silently discarded — same flow as New/Open/Exit.LayoutManager's exe-dir detection), since the existingSessionStateis Windows-only and would never persist on Linux/macOS.Notable implementation decisions (see
implementation.mdfor full rationale)OpenPopup/BeginPopupModalbool-flag pattern (matchingm_show_save_layout_dialogprecedent).Skipjumps to the last step (stays active) rather than duplicatingExit's behavior, delivering three genuinely distinct actions as the issue requested.test_tutorial_state.cpp) are a standalone Catch2 executable rather than appended toTEST_SOURCES, because the MinGW-w64 CI toolchain silently dropsTEST_CASEs registered beyond the ~217 already linked intotests.exe.startTutorial()forces the four target panels visible (m_show_node_editor/m_show_properties/m_show_spectrum/m_show_library) so every step actually has something to highlight, even on a default launch where the Component Library panel starts hidden.Known follow-ups (out of scope for this PR)
scripts/format.sh'sDIRSlist and the CI format job don't yet coverhelp/,layout/, or the newtutorial/— new sources were verified clean manually but aren't gated by the automated check.help_widget.cpp's pre-existing "Zoom: mouse wheel" bullet describes a gesture with no backing implementation in the codebase (confirmed via grep); left unchanged as it predates this PR and zoom is out of scope.