Skip to content

Make a page (by hand and with AI) and add it to the navigation

Goal: a page of your own — a few components showing workers or live values — reachable from a tab.

What the TUI can do today, and what it cannot

TUI Web app
Write and share a page spec (cfg.page.<name>, openspec page-specs) No — pages are written and shared in the web app's Pages view Yes
Make a page with AI No — the catalog has no page operation, so the AI tab cannot write one See https://app.docs.virtufin.com/
Show a shared page Yes — Config › Pages, Enter Yes
Put a shared page in your navigation Yes — by hand in navigation.json ("page": "<name>") Yes
Edit the navigation shared on the context (cfg.navigation) No — web app only Yes
Make a page by hand in the TUI Yes — a custom pane (a Python file), local to your machine —

A: Show a shared page and add it to your tabs

Prerequisites: someone shared a page on the context from the web app.

  1. Open Pages: Config top tab, 1 (Pages). Each row: Name, Title, Detail (valid or the page's first validation error).
  2. Preview: highlight a page, Enter. It renders below the list. The TUI draws Stack, Heading, Text, WorkerTable and ValueStream; a whole-view component (WorkerBrowser, ConnectionBrowser, ...) opens that pane in its place; any other component shows a placeholder.
  3. Make the navigation your own if it is not yet: on Config › Navigation do any edit (e.g. ctrl+down then ctrl+up on an entry). The structure in use is then written to ~/.config/virtufin/tui/navigation.json.
  4. Add the page node by hand: edit navigation.json and put a node with page where you want it, e.g. under Trading:

    {"id": "overview", "label": "My overview", "page": "stopped_workers"}
    

    page is the shared page's name (the Pages list's Name); id must be unique. 5. Restart the TUI. The node is a sub-tab (My overview); a node nested in a group is labelled with its groups (Analytics › My overview).

B: Make a page by hand — a custom pane

Prerequisites: Python; for a live pane, some Textual.

  1. Write the file in ~/.config/virtufin/tui/panes/ (created automatically). Either:

    • Script + form pane: <name>.py plus <name>.form.json — a form that runs the script with the fields in VIRTUFIN_TUI_FORM_DATA (same contract as Scripts); or
    • Live widget pane: <name>.py defining a class named exactly Pane:
    from textual.widgets import Static
    
    from virtufin_tui.screens._page import Page
    
    
    class Pane(Page):
        def compose(self):
            yield Static("", id="out")
    
        def on_mount(self):
            self.set_interval(1.0, self.update_view)
    
        def update_view(self):
            workers = self._stores.workers.get() or []
            self.query_one("#out", Static).update(f"{len(workers)} workers")
    

    self._stores is the dashboard's DataPump, self._client the active TuiClient. 2. Add it to the navigation: Config › Navigation. Your pane is listed under Available views and custom panes (kind script_form or widget). Highlight the navigation entry it should follow, then highlight the pane in the available table and press a (or Enter). Or press t for a new top-level tab holding it (prompts for id and label). 3. It appears at once; the structure is saved to navigation.json.

What you should see

  • The new sub-tab with your page or pane; </> reach sub-tabs past the tenth.
  • The Navigation pane's line In use: the user structure.

Troubleshooting

Symptom Cause and fix
Pages status line: pages: 0 — share one from the web app's Pages view No page is shared on this context.
A page row's Detail shows an error The spec does not validate; fix it in the web app.
A page sub-tab shows a placeholder The page or one of its components is not one the TUI draws.
Your custom pane is not in the available list The file has neither a sibling .form.json nor a class Pane; it is skipped with a warning in ~/.local/state/virtufin/tui/tui.log.
A hand-edited navigation.json is ignored It does not validate; the Navigation pane says why the structure was skipped and which one is in use.
You want the shared structure back Use the shared structure (delete navigation.json) on Config › Navigation.

Reference: Tabs, pages & custom panes.