docs: add a web apps guide for Streamlit, Dash and Gradio

[jvdd]

Closes #73.

What changed

• New guide docs/guides/web-apps.md (nav entry after Embedding). It shows a FlexViz dashboard inside a web app, on the same server and port:
  • Streamlit 1.57+: st.App(routes=[Mount("/flexviz", app=flexviz.app)]), a relative share_url(server_url="/flexviz"), st.iframe.
  • Dash 4.2+ with the FastAPI backend: mount_into(app.server). The Flask backend uses the Flask recipe on app.server.
  • Gradio: mount_into() on the FastAPI app before gr.mount_gradio_app(path="/").
  • FastAPI or Starlette frameworks such as NiceGUI: mount_into().
  • Flask and other WSGI apps: a2wsgi.ASGIMiddleware inside DispatcherMiddleware.
  • Limits, plus security: no authentication on the mounted routes, Streamlit binds all interfaces, and a TrustedHostMiddleware wrap against DNS rebinding.
• Embedding guide: the WSGI advice pointed to a bare DispatcherMiddleware. That cannot call an ASGI app. The guide now links to the a2wsgi recipe.
• mount_into() docstring and error: same fix, now naming a2wsgi.ASGIMiddleware. The test asserts the new hint.
• CHANGELOG: Added (guide) and Fixed (hint).

Facts behind the guide

• Every code block in the guide ran in headless Chromium against this branch, and each check passed: Streamlit 1.64, Dash 4.4.1, Gradio 6.29, NiceGUI 3.17.1, Flask 3.1.3 + a2wsgi 1.10.10. Dash on the Flask backend, and Streamlit with --server.baseUrlPath, also passed.
• The old Flask advice fails on each request with TypeError: FastAPI.__call__() missing 1 required positional argument: 'send'.
• Gradio mounted before FlexViz at / makes /flexviz/view return 404.
• Streamlit reruns the page script after each widget change. Without st.cache_data, each rerun builds new uids, so a new URL, and the iframe reloads and loses zoom and selections. With the cache, the iframe stays.
• st.iframe falls back to 400 px for this URL. The guide gives the real heights: 400 px panel, 45 px toolbar, 45 px active-filter bar.
• TrustedHostMiddleware(flexviz.app, ...) returned 400 for a foreign Host and 200 for a loopback one, in both a FastAPI mount and a Flask/a2wsgi mount.

Checks

• mkdocs build --strict passes. The anchors #who-owns-width-and-height, #in-an-iframe and #flask-and-other-wsgi-apps resolve.
• ruff format --check and ruff check are clean. tests/test_integration.py and tests/test_server.py: 121 passed. The new assertion fails on main.

Review follow-up (6fe06a4)

• Example data: a short make_data.py writes the readings.parquet that the examples read. Without the file, the first chart update returned 500.
• Data contract: a registered source must not change while the server runs. With cache=True, a changed file gives a stale first view. Without the cache, the updates fail: Polars keeps the metadata of a scanned file after the first collect, and then panics (os error 22). The guide says to restart the server, and links to the caching guide. Repro posted on Cache: invalidate a cache=True source when its data changes #39.
• History: the Security section says that a mount also serves /flexviz/h/N from .flexviz/history.jsonl, and links to the agent safety notes. The code change is Server: do not serve /h/{n} from the mountable app #142.
• The Dash, Gradio and Flask iframes have a title. Streamlit cannot take one: st.iframe has no title parameter and sets title="st.iframe".
• Each paragraph and list is now either instructions or description, not both.
• I extracted every code block again and ran it in the browser (Streamlit, Dash, Gradio, Flask): all pass, with the iframe titles present. mkdocs build --strict passes.

Not in this PR

• Dashboard: share_url() without data gives a URL whose updates fail #143: Dashboard() without data, plus share_url(source_name=...), writes source=None into every figure, so each update returns 500.
• Server: do not serve /h/{n} from the mountable app #142: serve /h/{n} only from flexviz serve and show(), not from the mountable app.

[codspeed]

Merging this PR will not alter performance

✅ 32 untouched benchmarks

---

_{Comparing docs/web-app-integrations (6fe06a4) with main (c3d788a)}