feat: expose stable /translate API endpoint and tidy UI

Add api_name="translate" to the submit handler so the deployed Space
presents a clean, documented text+language -> string endpoint. Mark the
two UI-only handlers (swap, button loading) as api_visibility="private"
so they no longer leak as _swap_languages / _translate_with_loading
endpoints; only /translate is public. Autofocus the input textbox.

Add tests for the stable api_name, the single-public-endpoint surface
(via get_api_info), and input autofocus. Update CLAUDE.md test counts
(53 total / 43 fast).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -25,8 +25,8 @@ uv run ruff format .
 uv run ty check
 
 # Test
-uv run pytest                     # all 50 tests (slow require CUDA + model download)
-uv run pytest -m "not slow"       # 40 fast tests only
+uv run pytest                     # all 53 tests (slow require CUDA + model download)
+uv run pytest -m "not slow"       # 43 fast tests only
 uv run pytest -m slow             # 10 model tests only (CUDA only)
 
 # Generate language mapping (dev only)
@@ -41,7 +41,7 @@ uv run scripts/generate_langmap.py <path-to-paper.pdf>
 
 **`scripts/`** — `generate_langmap.py` parses the MADLAD-400 paper PDF (Table 9, pages 16-22) using pdfplumber and generates the static language mapping with region assignments. Dev-only tool; requires `requirements-dev.txt` dependencies.
 
-**`tests/`** — 50 tests (40 fast, 10 slow). `test_langmap.py` has 10 fast tests for mapping validation (dict shape, regions, spot-checks). `test_app.py` has 30 fast tests (signatures, device fallback, UI layout with symmetric dropdowns, swap button, textbox config including toolbar buttons, handler wiring, no HTML elements, locale codes, no title) and 10 slow tests (translation with various parameters, language mapping). Slow tests require CUDA and model download; auto-skipped without CUDA.
+**`tests/`** — 53 tests (43 fast, 10 slow). `test_langmap.py` has 10 fast tests for mapping validation (dict shape, regions, spot-checks). `test_app.py` has 33 fast tests (signatures, device fallback, UI layout with symmetric dropdowns, swap button, textbox config including toolbar buttons and input autofocus, handler wiring, stable `translate` API endpoint with UI-only handlers kept private, no HTML elements, locale codes, no title) and 10 slow tests (translation with various parameters, language mapping). Slow tests require CUDA and model download; auto-skipped without CUDA.
 
 ## Tooling
 

app.py

@@ -128,6 +128,7 @@ def _build_demo() -> gr.Blocks:
                 lines=6,
                 max_length=2000,
                 show_label=False,
+                autofocus=True,
             )
             output_text = gr.Textbox(
                 placeholder="Translation",
@@ -139,20 +140,24 @@ def _build_demo() -> gr.Blocks:
 
         translate_btn = gr.Button("Translate", variant="primary")
 
+        # UI-only handlers: kept off the public API surface (private) so only /translate is exposed.
         swap_btn.click(
             fn=_swap_languages,
             inputs=[source_language, target_language, input_text, output_text],
             outputs=[source_language, target_language, input_text, output_text],
+            api_visibility="private",
         )
         translate_btn.click(
             fn=_translate_with_loading,
             inputs=[input_text, target_language],
             outputs=[translate_btn, output_text],
+            api_visibility="private",
         )
         input_text.submit(
             fn=translate,
             inputs=[input_text, target_language],
             outputs=output_text,
+            api_name="translate",
         )
 
     return demo

tests/test_app.py

@@ -153,6 +153,13 @@ def test_input_textbox_has_no_placeholder(demo):
     assert interactive[0].placeholder is None, f"Expected no placeholder, got {interactive[0].placeholder!r}"
 
 
+def test_input_textbox_autofocus(demo):
+    """Input textbox should autofocus so the cursor lands there on page load."""
+    textboxes = [b for b in demo.blocks.values() if type(b).__name__ == "Textbox"]
+    interactive = [t for t in textboxes if t.interactive is not False]
+    assert interactive[0].autofocus is True, f"Expected autofocus=True, got {interactive[0].autofocus!r}"
+
+
 def test_input_textbox_has_no_buttons(demo):
     """Input textbox should expose no toolbar buttons (gradio accepts invalid button values silently)."""
     textboxes = [b for b in demo.blocks.values() if type(b).__name__ == "Textbox"]
@@ -234,6 +241,21 @@ def test_all_handlers_wired(demo):
     assert len(demo.fns) == 3, f"Expected 3 handlers, found {len(demo.fns)}"
 
 
+def test_translate_endpoint_has_stable_api_name(demo):
+    """The lean submit handler (text + language -> string) should expose a stable 'translate' API endpoint."""
+    api_fns = [fn for fn in demo.fns.values() if getattr(fn, "api_name", None) == "translate"]
+    assert len(api_fns) == 1, "Expected exactly one handler with api_name='translate'"
+    fn = api_fns[0]
+    assert [type(i).__name__ for i in fn.inputs] == ["Textbox", "Dropdown"]
+    assert [type(o).__name__ for o in fn.outputs] == ["Textbox"]
+
+
+def test_only_translate_endpoint_is_public(demo):
+    """UI-only handlers (swap, button loading) should be private; only /translate is a public API endpoint."""
+    named = list(demo.get_api_info()["named_endpoints"].keys())
+    assert named == ["/translate"], f"Expected only ['/translate'] exposed, found {named}"
+
+
 def test_no_title(demo):
     """UI should not have an H1 title."""
     markdowns = [b for b in demo.blocks.values() if type(b).__name__ == "Markdown"]