Help: Fn+h lists the keys of the screen you're on, and no screen names its keys any more (#69)

Fn+h on any screen, text fields included, and ? outside Text Entry, open a
panel over the content area: the screen's own keys, then the ones that work
everywhere. Every App declares its keys for the state it is in (pages,
viewers, dialogs and text fields answer for themselves); the App manager
opens the panel and takes every key while it is open.

About 30 hint lines are gone, from every App. What stays on a screen is
state. The first-start Setup keeps its hints and teaches the key; a device
set up before gets one Toast, once. The guide and the FAQ open with it.
`key help` over the consoles.

476 host tests (8 new). Checked on the device with key help and screenshots:
the Launcher, all nine Apps and several of their states. 8.5 KB of flash and
40 bytes of static RAM. Decisions Q196 to Q203 in docs/milestones/U1.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

test/test_app_manager/test_app_manager.cpp

@@ -20,6 +20,12 @@ struct FakeApp : App {
     }
     void update(uint32_t nowMs) override { lastUpdate = nowMs; }
     void draw(Canvas&) override {}
+    void help(std::vector<KeyHelp>& out) const override {
+        if (helpKey) out.push_back({helpKey, "does a thing"});
+    }
+    const char* helpTitle() const override { return scope; }
+    const char* helpKey = nullptr;
+    const char* scope = nullptr;
     uint32_t lastUpdate = 0;
     std::vector<KeyEvent> keys;
     bool handles = false;
@@ -181,6 +187,79 @@ void test_modal_app_cannot_be_switched_away_by_open() {
     TEST_ASSERT_EQUAL_PTR(&f.demo, &f.manager.foreground());
 }
 
+// Issue #69: Fn+h lists the foreground App's keys, then the ones that work everywhere.
+void test_help_lists_the_apps_keys_then_the_global_ones() {
+    Fixture f;
+    f.manager.begin();
+    f.manager.open("notes");
+    f.notes.helpKey = "n";
+    f.manager.handleKey(KeyEvent::of(Key::Help));
+    TEST_ASSERT_TRUE(f.manager.help().isOpen());
+    TEST_ASSERT_EQUAL_STRING("Notes", f.manager.help().title().c_str());
+    const auto& rows = f.manager.help().rows();
+    TEST_ASSERT_EQUAL_STRING("n", rows[0].keys);
+    TEST_ASSERT_EQUAL_STRING("Everywhere", rows[1].keys);
+    TEST_ASSERT_NULL(rows[1].action);  // a heading
+    TEST_ASSERT_TRUE(rows.size() > 3);
+    TEST_ASSERT_EQUAL(0, f.notes.keys.size());  // the App never saw the key
+    TEST_ASSERT_TRUE(f.manager.takeRedraw());
+}
+
+void test_help_is_titled_with_the_scope_when_the_app_names_one() {
+    Fixture f;
+    f.manager.begin();
+    f.manager.handleKey(KeyEvent::of(Key::Help));
+    TEST_ASSERT_EQUAL_STRING("Launcher", f.manager.help().title().c_str());
+    f.manager.handleKey(KeyEvent::of(Key::Select));  // closes it
+    f.manager.open("notes");
+    f.notes.scope = "Notes: editor";
+    f.manager.handleKey(KeyEvent::of(Key::Help));
+    TEST_ASSERT_EQUAL_STRING("Notes: editor", f.manager.help().title().c_str());
+}
+
+void test_open_help_takes_every_key_and_any_but_the_arrows_closes_it() {
+    Fixture f;
+    f.manager.begin();
+    f.manager.open("notes");
+    f.manager.handleKey(KeyEvent::of(Key::Help));
+    f.manager.handleKey(KeyEvent::of(Key::Down));  // scrolls
+    TEST_ASSERT_TRUE(f.manager.help().isOpen());
+    f.manager.handleKey(KeyEvent::of(Key::Home));  // closes; doesn't go home
+    TEST_ASSERT_FALSE(f.manager.help().isOpen());
+    TEST_ASSERT_TRUE(&f.manager.foreground() == &f.notes);
+    TEST_ASSERT_EQUAL(0, f.notes.keys.size());
+    f.manager.handleKey(KeyEvent::character('x'));  // closed: keys reach the App again
+    TEST_ASSERT_EQUAL(1, f.notes.keys.size());
+}
+
+void test_help_works_in_a_modal_app_and_closes_when_the_app_changes() {
+    Fixture f;
+    f.manager.begin();
+    f.manager.openModal("demo");
+    f.manager.handleKey(KeyEvent::of(Key::Help));
+    TEST_ASSERT_TRUE(f.manager.help().isOpen());
+    f.manager.endModal();
+    TEST_ASSERT_FALSE(f.manager.help().isOpen());
+}
+
+void test_the_help_panel_scrolls_within_its_rows() {
+    HelpModel m(3);
+    std::vector<KeyHelp> rows;
+    for (int i = 0; i < 8; i++) rows.push_back({"k", "a"});
+    m.open("T", rows);
+    m.onKey(KeyEvent::of(Key::Up));
+    TEST_ASSERT_EQUAL(0, m.top());
+    m.onKey(KeyEvent::of(Key::Right));  // a page
+    TEST_ASSERT_EQUAL(3, m.top());
+    for (int i = 0; i < 9; i++) m.onKey(KeyEvent::of(Key::Down));
+    TEST_ASSERT_EQUAL(5, m.top());  // the last row at the bottom, no further
+    m.onKey(KeyEvent::of(Key::Left));
+    TEST_ASSERT_EQUAL(2, m.top());
+    m.onKey(KeyEvent::of(Key::Tab));
+    TEST_ASSERT_FALSE(m.isOpen());
+    TEST_ASSERT_EQUAL(0, m.rows().size());
+}
+
 int main() {
     UNITY_BEGIN();
     RUN_TEST(test_launcher_is_in_foreground_after_begin);
@@ -199,5 +278,10 @@ int main() {
     RUN_TEST(test_modal_app_keeps_home_and_back);
     RUN_TEST(test_ending_the_modal_returns_to_launcher_and_unlocks_home);
     RUN_TEST(test_modal_app_cannot_be_switched_away_by_open);
+    RUN_TEST(test_help_lists_the_apps_keys_then_the_global_ones);
+    RUN_TEST(test_help_is_titled_with_the_scope_when_the_app_names_one);
+    RUN_TEST(test_open_help_takes_every_key_and_any_but_the_arrows_closes_it);
+    RUN_TEST(test_help_works_in_a_modal_app_and_closes_when_the_app_changes);
+    RUN_TEST(test_the_help_panel_scrolls_within_its_rows);
     return UNITY_END();
 }

test/test_key_mapper/test_key_mapper.cpp

@@ -220,6 +220,42 @@ void test_shifted_arrow_keys_type_their_symbols_when_not_typing() {
     TEST_ASSERT_EQUAL(':', press(m, r)[0].ch);
 }
 
+// Issue #69, Q196: Fn+h everywhere, ? when it wouldn't be typed.
+void test_fn_h_is_help_in_both_modes() {
+    for (bool typing : {true, false}) {
+        KeyMapper m;
+        m.setTextEntry(typing);
+        auto ev = press(m, withFn({'h'}));
+        TEST_ASSERT_EQUAL(1, ev.size());
+        TEST_ASSERT_EQUAL(static_cast<int>(Key::Help), static_cast<int>(ev[0].key));
+    }
+}
+
+void test_plain_h_still_types() {
+    for (bool typing : {true, false}) {
+        KeyMapper m;
+        m.setTextEntry(typing);
+        auto ev = press(m, chars({'h'}));
+        TEST_ASSERT_EQUAL(1, ev.size());
+        TEST_ASSERT_EQUAL(static_cast<int>(Key::Char), static_cast<int>(ev[0].key));
+        TEST_ASSERT_EQUAL('h', ev[0].ch);
+    }
+}
+
+void test_question_mark_is_help_only_when_not_typing() {
+    KeyMapper m;
+    m.setTextEntry(false);
+    auto ev = press(m, chars({'?'}));
+    TEST_ASSERT_EQUAL(1, ev.size());
+    TEST_ASSERT_EQUAL(static_cast<int>(Key::Help), static_cast<int>(ev[0].key));
+    release(m);
+    m.setTextEntry(true);
+    ev = press(m, chars({'?'}));
+    TEST_ASSERT_EQUAL(1, ev.size());
+    TEST_ASSERT_EQUAL(static_cast<int>(Key::Char), static_cast<int>(ev[0].key));
+    TEST_ASSERT_EQUAL('?', ev[0].ch);
+}
+
 int main() {
     UNITY_BEGIN();
     RUN_TEST(test_plain_character);
@@ -241,5 +277,8 @@ int main() {
     RUN_TEST(test_fn_arrows_work_in_both_modes);
     RUN_TEST(test_other_characters_still_type_when_not_typing);
     RUN_TEST(test_shifted_arrow_keys_type_their_symbols_when_not_typing);
+    RUN_TEST(test_fn_h_is_help_in_both_modes);
+    RUN_TEST(test_plain_h_still_types);
+    RUN_TEST(test_question_mark_is_help_only_when_not_typing);
     return UNITY_END();
 }