From baaef7c8fa61f9affe9b8b62511f004c9f95fb2c Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Tue, 18 Aug 2026 16:17:16 -0500
Subject: [PATCH] feat(docs): auto-generated web-apps landing page +
 generalized app hosting

- The docs workflow now hosts ANY component's web/ directory
  (components/*/web/*.html + .js) automatically instead of hardcoding the
  two existing dirs, and generates docs/apps/index.html afterward.
- New doc/generate_apps_index.py builds the landing page from each app's
  <title> and <meta name=description> -- a future app is listed by simply
  having those two tags, no registry to maintain. Theme-aware (light/dark),
  responsive card grid.
- Added <meta name=description> to all five existing apps (head-only edits).
- New doc/en/web_apps.rst (linked from the docs index) describing the hosted
  tools and the add-an-app convention.

Verified locally: the generator indexes all 5 apps with titles+descriptions
and the output parses cleanly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/build_and_publish_docs.yml  |  18 ++--
 .../odrive_ascii/web/hid_visualizer.html      |   1 +
 .../odrive_ascii/web/odrive_console.html      |   1 +
 .../web/odrive_control_panel.html             |   1 +
 .../web/odrive_webusb_console.html            |   1 +
 components/usb_device/web/board_console.html  |   1 +
 doc/en/index.rst                              |   4 +-
 doc/en/web_apps.rst                           |  32 ++++++
 doc/generate_apps_index.py                    | 102 ++++++++++++++++++
 9 files changed, 152 insertions(+), 9 deletions(-)
 create mode 100644 doc/en/web_apps.rst
 create mode 100644 doc/generate_apps_index.py

diff --git a/.github/workflows/build_and_publish_docs.yml b/.github/workflows/build_and_publish_docs.yml
index bc5866fb76..b8769a1053 100644
--- a/.github/workflows/build_and_publish_docs.yml
+++ b/.github/workflows/build_and_publish_docs.yml
@@ -53,22 +53,24 @@ jobs:
           # Host the interactive single-file web apps (Web Serial / WebUSB /
           # WebHID tools) alongside the docs. GitHub Pages serves over https
           # (a secure context), so the browser APIs work directly from these
-          # hosted copies.
+          # hosted copies. ANY component's web/ directory is hosted
+          # automatically -- drop an .html (plus optional same-origin .js
+          # assets) into components/<name>/web/ and it ships.
           mkdir -p ../docs/apps
           # nullglob makes a "no matches" case a no-op (the glob expands to
           # nothing) while a genuine copy error still fails the job, instead
           # of being swallowed by `|| true`.
           shopt -s nullglob
-          consoles=(../components/odrive_ascii/web/*.html)
-          if [ ${#consoles[@]} -gt 0 ]; then
-            cp "${consoles[@]}" ../docs/apps/
+          apps=(../components/*/web/*.html ../components/*/web/*.js)
+          if [ ${#apps[@]} -gt 0 ]; then
+            cp "${apps[@]}" ../docs/apps/
           else
-            echo "No hosted web consoles found to copy." >&2
+            echo "No hosted web apps found to copy." >&2
           fi
-          for f in ../components/usb_device/web/*.html ../components/usb_device/web/*.js; do
-            cp "$f" ../docs/apps/.
-          done
           shopt -u nullglob
+          # Generate the landing page (docs/apps/index.html) listing every
+          # hosted app by its <title> + <meta name="description">.
+          python3 generate_apps_index.py ../docs/apps
 
       - name: Build Documentation (PDF)
         run: |
diff --git a/components/odrive_ascii/web/hid_visualizer.html b/components/odrive_ascii/web/hid_visualizer.html
index 63efd2264d..5a0da898bd 100644
--- a/components/odrive_ascii/web/hid_visualizer.html
+++ b/components/odrive_ascii/web/hid_visualizer.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>WebHID Gamepad Input Visualizer</title>
+<meta name="description" content="WebHID input visualizer: connect any HID gamepad or device and watch its decoded buttons, sticks, and raw input reports live.">
   <!--
     WebHID Gamepad Input Visualizer
     ===============================
diff --git a/components/odrive_ascii/web/odrive_console.html b/components/odrive_ascii/web/odrive_console.html
index dbb830af5b..08c39db3b6 100644
--- a/components/odrive_ascii/web/odrive_console.html
+++ b/components/odrive_ascii/web/odrive_console.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>ODrive ASCII Web Serial Console</title>
+<meta name="description" content="Web Serial console for the ODrive ASCII protocol: interactive terminal, quick motor controls, and live position/velocity plotting.">
   <!--
     ODrive ASCII Web Serial Console
     ================================
diff --git a/components/odrive_ascii/web/odrive_control_panel.html b/components/odrive_ascii/web/odrive_control_panel.html
index 8ce462d356..d7a4a9c141 100644
--- a/components/odrive_ascii/web/odrive_control_panel.html
+++ b/components/odrive_ascii/web/odrive_control_panel.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>ODrive Native WebUSB Control Panel</title>
+<meta name="description" content="WebUSB control panel for the ODrive native (Fibre) binary protocol: endpoint tree browser, live multi-signal plots, and quick controls.">
   <!--
     ODrive Native (Fibre endpoint) WebUSB Control Panel
     ===================================================
diff --git a/components/odrive_ascii/web/odrive_webusb_console.html b/components/odrive_ascii/web/odrive_webusb_console.html
index 6c4995b1b4..91a48ccc6b 100644
--- a/components/odrive_ascii/web/odrive_webusb_console.html
+++ b/components/odrive_ascii/web/odrive_webusb_console.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>ODrive ASCII WebUSB Console</title>
+<meta name="description" content="WebUSB console speaking the ODrive ASCII protocol over the vendor bulk interface (no serial driver needed).">
   <!--
     ODrive ASCII WebUSB Console
     ===========================
diff --git a/components/usb_device/web/board_console.html b/components/usb_device/web/board_console.html
index 5e38d4701d..b7decbfd27 100644
--- a/components/usb_device/web/board_console.html
+++ b/components/usb_device/web/board_console.html
@@ -4,6 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>espp Board Console &amp; ESP Flasher</title>
+<meta name="description" content="General-purpose Web Serial board console and ESP flasher (esptool-js): serial monitor, reset/bootloader controls, and firmware flashing.">
   <!--
     espp Board Console + ESP Flasher (Web Serial)
     =============================================
diff --git a/doc/en/index.rst b/doc/en/index.rst
index e27655ce04..855edcfe6b 100755
--- a/doc/en/index.rst
+++ b/doc/en/index.rst
@@ -7,13 +7,15 @@ abstractions for building applications from reusable components.
 
 New here? Start with :doc:`getting_started`. The APIs below are grouped by
 capability; all supported development boards are collected under
-:doc:`dev_boards/index`.
+:doc:`dev_boards/index`. Browser tools for interacting with your hardware are
+collected under :doc:`web_apps`.
 
 .. toctree::
    :maxdepth: 1
    :caption: Introduction
 
    getting_started
+   web_apps
 
 .. toctree::
    :maxdepth: 1
diff --git a/doc/en/web_apps.rst b/doc/en/web_apps.rst
new file mode 100644
index 0000000000..54ed381e1c
--- /dev/null
+++ b/doc/en/web_apps.rst
@@ -0,0 +1,32 @@
+Web Apps
+********
+
+espp ships a growing set of **self-contained browser tools** that talk directly
+to your hardware using the Web Serial / WebUSB / WebHID APIs (Chromium-based
+browsers) — nothing to install. They are hosted alongside this documentation:
+
+    **→** `esp-cpp.github.io/espp/apps <https://esp-cpp.github.io/espp/apps/index.html>`_
+
+Highlights:
+
+- **Board Console & ESP Flasher** — a general-purpose Web Serial monitor with
+  reset / bootloader controls and an `esptool-js`-based firmware flasher.
+- **ODrive ASCII Web Serial console** and **WebUSB console** — interactive
+  terminals with quick motor controls and live plotting for the
+  :doc:`odrive_ascii <motor_control/odrive_ascii>` protocol server.
+- **ODrive Native WebUSB control panel** — endpoint-tree browser, live
+  multi-signal plots, and typed read/write for the ODrive native (Fibre)
+  binary protocol.
+- **WebHID input visualizer** — decoded buttons / sticks / raw reports for any
+  HID device, driven entirely by its report descriptor.
+
+Adding a new app
+----------------
+
+Any single-file app placed in a component's ``web/`` directory
+(``components/<name>/web/*.html``, plus optional same-origin ``.js`` assets) is
+hosted automatically by the docs workflow, and the `apps landing page
+<https://esp-cpp.github.io/espp/apps/index.html>`_ lists it using the file's
+``<title>`` and ``<meta name="description">`` tags — no registry to maintain.
+Apps must be fully self-contained (no CDN resources) so they work offline and
+under GitHub Pages' strict hosting.
diff --git a/doc/generate_apps_index.py b/doc/generate_apps_index.py
new file mode 100644
index 0000000000..6938734c34
--- /dev/null
+++ b/doc/generate_apps_index.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Generate docs/apps/index.html from the hosted single-file web apps.
+
+Run by .github/workflows/build_and_publish_docs.yml AFTER the per-component
+web apps (components/*/web/*.html) are copied into docs/apps/. Each app's
+card title comes from its <title> and its blurb from
+<meta name="description" content="...">, so a new app is listed automatically
+by simply having those two tags -- no registry to maintain.
+
+Usage: generate_apps_index.py <apps_dir>
+"""
+
+import html
+import re
+import sys
+from pathlib import Path
+
+
+def extract(path: Path):
+    text = path.read_text(encoding="utf-8", errors="replace")
+    title_m = re.search(r"<title>(.*?)</title>", text, re.S | re.I)
+    desc_m = re.search(
+        r'<meta\s+name=["\']description["\']\s+content=["\'](.*?)["\']', text, re.S | re.I)
+    title = html.unescape(title_m.group(1).strip()) if title_m else path.stem
+    desc = html.unescape(desc_m.group(1).strip()) if desc_m else ""
+    return title, desc
+
+
+def main() -> int:
+    apps_dir = Path(sys.argv[1])
+    apps = sorted(p for p in apps_dir.glob("*.html") if p.name != "index.html")
+    if not apps:
+        print(f"no apps found in {apps_dir}", file=sys.stderr)
+        return 1
+
+    cards = []
+    for app in apps:
+        title, desc = extract(app)
+        cards.append(
+            f'      <a class="card" href="{html.escape(app.name)}">\n'
+            f"        <h2>{html.escape(title)}</h2>\n"
+            f"        <p>{html.escape(desc) if desc else '&nbsp;'}</p>\n"
+            f"      </a>")
+        print(f"  indexed: {app.name} -> {title}")
+
+    page = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>espp Web Apps</title>
+<meta name="description" content="Browser tools hosted with the espp documentation: Web Serial / WebUSB / WebHID consoles, control panels, and flashers.">
+<style>
+  :root {{
+    --bg: #ffffff; --fg: #1a1a2e; --muted: #666; --card: #f6f7f9;
+    --border: #d9dce1; --accent: #2563eb;
+  }}
+  @media (prefers-color-scheme: dark) {{
+    :root {{
+      --bg: #14161a; --fg: #e6e6e6; --muted: #9aa0a6; --card: #1d2127;
+      --border: #333842; --accent: #7aa2ff;
+    }}
+  }}
+  * {{ box-sizing: border-box; }}
+  body {{ margin: 0; padding: 2rem 1rem; background: var(--bg); color: var(--fg);
+         font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }}
+  main {{ max-width: 60rem; margin: 0 auto; }}
+  h1 {{ margin: 0 0 .25rem; }}
+  .sub {{ color: var(--muted); margin: 0 0 2rem; }}
+  .grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr)); gap: 1rem; }}
+  .card {{ display: block; padding: 1rem 1.25rem; background: var(--card);
+          border: 1px solid var(--border); border-radius: .6rem;
+          color: inherit; text-decoration: none; }}
+  .card:hover {{ border-color: var(--accent); }}
+  .card h2 {{ margin: 0 0 .4rem; font-size: 1.05rem; color: var(--accent); }}
+  .card p {{ margin: 0; color: var(--muted); font-size: .92rem; }}
+  footer {{ margin-top: 2.5rem; color: var(--muted); font-size: .85rem; }}
+  footer a {{ color: var(--accent); }}
+</style>
+</head>
+<body>
+  <main>
+    <h1>espp Web Apps</h1>
+    <p class="sub">Self-contained browser tools hosted with the espp documentation.
+    They use the Web&nbsp;Serial / WebUSB / WebHID APIs (Chromium-based browsers)
+    and talk directly to your hardware &mdash; nothing to install.</p>
+    <div class="grid">
+{chr(10).join(cards)}
+    </div>
+    <footer>Part of the <a href="../index.html">espp documentation</a> &middot;
+    <a href="https://github.com/esp-cpp/espp">esp-cpp/espp</a></footer>
+  </main>
+</body>
+</html>
+"""
+    (apps_dir / "index.html").write_text(page, encoding="utf-8")
+    print(f"wrote {apps_dir / 'index.html'} ({len(apps)} apps)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())