Automation bridge: `tooltip` and `dumpTree` cannot reach an item-view cell, so per-cell tooltips are not provable

[skerker]

What

A way to read, or force-show, the tooltip of one cell in a QTableWidget / QTreeWidget / QListWidget over the automation bridge, and to read a cell's text and tooltip as data.

Why

tooltip <target> sends its QHelpEvent at the target widget's centre and reads the widget's static toolTip property (src/core/AutomationServer.cpp:9828, :9837; the property read is what produces target has no tooltip at :9825). An item view's tooltip is not on the widget: it is the item's Qt::ToolTipRole, resolved by QAbstractItemView::viewportEvent from the help event's position. So on any table the verb answers target has no tooltip, and dumpTree lists the table but not its items.

Hit tonight proving #5130: the Network Diagnostics → TCI Clients endpoint cell reads 127.0.0.1:56564 (Python) (provable from grab), and its tooltip carries the client's executable path and version — the thing the review asked about — but only a human hover could see it. A hand screenshot of a Qt tooltip is unreliable because the tip hides on mouse movement.

Sibling of #4849 (hover x/y + a tooltip read-back for the panadapter's position-dependent tips), not a duplicate: item views need a help event at a point (or a role read), not a mouse move, so #4849's hover <target> x y alone would not reach them.

Code references (origin/main 293240a7)

• src/core/AutomationServer.cpp:9793 doTooltip() — centre-only QHelpEvent, static-property read.
• src/core/AutomationServer.cpp:3847 doDumpTree() — widgets only; item-view rows/cells are not surfaced.
• docs/automation-bridge.md:1760 — the tooltip verb's reference entry.

Proposed change

Either or both, all inside AutomationServer + docs:

1. cell <target> <row> <col> — read verb returning the item's text, toolTip (Qt::ToolTipRole), accessibleText, and whether the row is selected. Data, no hover, no timing. This alone makes a per-cell tooltip assertable in one round trip and is the shape evidence wants.
2. tooltip <target> <row> <col> — send the QHelpEvent at that cell's visualRect() centre on the view's viewport, so the existing grab QTipLabel path works for item views too (the same extension automation bridge: hover verb ignores x/y, so point-hover tooltips aren't provable #4849 asks of hover).

Both resolve the view through the existing target rules; a target that is not a QAbstractItemView errors.

Acceptance

• cell networkDiagnosticsTciClients 0 1 (or the table's resolved target) returns the endpoint cell's text and its tooltip on a connected TCI client.
• tooltip <table> 0 1 shows the tip and grab QTipLabel captures it.
• bridge_docs_check passes with both verbs documented in docs/automation-bridge.md.
• Non-item-view targets return a clear error, existing tooltip <target> behaviour unchanged.

Non-goals

Moving the OS cursor; reading tips raised by app code via QToolTip::showText (that read-back is #4849's ask 2).

Refs #4849, #5130.

— authored by agent (Claude Code) on behalf of @skerker

[aethersdr-agent]

Triage: confirmed against origin/main 293240a7. The diagnosis in the report is accurate, and the proposal is well-shaped. maintainer-review.

Root cause — verified

doTooltip() (src/core/AutomationServer.cpp:9793) is widget-only on both axes:

• Text comes from the static widget property: const QString text = value.isEmpty() ? w->toolTip() : value; (:9824), and the empty case is exactly the target has no tooltip: error at :9825. A QTableWidget never sets its own toolTip(), so any table hits that branch before an event is ever sent.
• The event is posted at the widget centre — QPoint center(w->width()/2, w->height()/2) (:9828) — and delivered to w itself (:9838), not to view->viewport(). QAbstractItemView::viewportEvent() is what turns a QHelpEvent into an item's Qt::ToolTipRole lookup via indexAt(pos), and it only sees events on the viewport.

describeWidget() serialises a widget's toolTip (:377) and, for combos, the full items list (:469-475) — but there is no item-view branch, so doDumpTree() (:3847) surfaces the table widget and stops. Confirmed: no cell/table-read verb exists anywhere in the registry.

The precedent for the fix is already in the file. invoke has two QAbstractItemView branches — select-by-text (:4412, recursive model->index() walk) and selectRow (:4465, bounds-checked rowCount()/columnCount(), scrollTo) — so target resolution, model traversal, and range-error wording can be lifted verbatim.

Also verified: no item view in the app overrides viewportEvent() to build a tooltip dynamically (the QEvent::ToolTip handlers at SpectrumWidget.cpp:11492, ClientCompEditorCanvas.cpp:169, MainWindow_Shortcuts.cpp:542/:552 are all non-item-view). So proposal 1 (Qt::ToolTipRole read) is sufficient for every table in the tree today; 2 is the belt-and-braces path for a future custom view and for the grab QTipLabel screenshot shape.

Proposed fix — all in AutomationServer.cpp + docs/automation-bridge.md

1. cell <target> <row> <col> — new read verb. Resolve via resolveWidget, qobject_cast<QAbstractItemView*>, err("view has no model"), bounds-check both axes with the :4472 message shape. Return text (Qt::DisplayRole), toolTip (Qt::ToolTipRole — this covers both QTableWidgetItem::setToolTip and model-supplied tips), accessibleText, selected (selectionModel()->isSelected), plus rows/cols so a driver can iterate without guessing. Read model->data(), not QTableWidget::item(), so it works for any view.
2. tooltip, cell form — scrollTo(index) first (visualRect() is empty for a scrolled-out row, so the help event would land nowhere), then send QHelpEvent at view->visualRect(index).center() on view->viewport(), with global = viewport->mapToGlobal(...). Keep the existing QPointer guard from :9852.

Three implementation notes for whoever picks this up:

• Arg-parsing collision. The current parser (:2950-2967) treats every token after the target as either hide or an override tooltip string (vjoin(p, 2)). Bare tooltip <t> 0 1 is therefore indistinguishable from an override reading "0 1". Acceptance bullet 4 says existing behaviour must be unchanged, so use an explicit keyword — tooltip <t> cell <row> <col> — plus row/col fields in the JSON form, rather than sniffing for two integers.
• The acceptance target does not exist. There is no networkDiagnosticsTciClients. m_tciClientTable is constructed at src/gui/NetworkDiagnosticsDialog.cpp:1084 with no setObjectName, unlike its siblings in the same dialog (networkDiagnosticsSearch :287, networkDiagnosticsPages :345). m_tciLogTable (:1211) and m_audioStreamsTable (:793) are unnamed too. Add the three object names in the same PR, or the acceptance test has to resolve by bare class and will tie against the other tables in the dialog.
• Trees. <row> <col> is a flat top-level index; QTreeWidget children are unreachable by it. Fine for v1 — document the limitation rather than leaving it implied.

Scope note on evidence: on main the endpoint cell is plain addr + ":" + port with no tooltip (NetworkDiagnosticsDialog.cpp:1275), and TciClientInfo (src/core/TciServer.h:38-46) carries no exe/version fields. The 127.0.0.1:56564 (Python) cell and its exe-path tooltip come from PR #5130's branch, which is still open — consistent with the report ("hit tonight proving #5130"), just worth stating so nobody greps main for it. That also means the acceptance check can only run against #5130's branch until it merges.

bridge_docs_check: the verb table between the GENERATED markers is derived from the add(...) registrations by tools/gen_bridge_docs.py, so re-run it after registering cell, and add a ### cell section near the ### tooltip entry (docs/automation-bridge.md:1760) — the script's duplicate-heading lint will catch a stray second heading.

Handoff

Known: exact mechanism, exact lines, existing in-file precedent to copy, and no dynamic-tooltip views to worry about. To fix: two verbs in AutomationServer.cpp, three setObjectName calls in NetworkDiagnosticsDialog.cpp, one docs section + regenerated table. Self-contained, no engine or protocol surface, no radio required to test.

---

_{🤖 aethersdr-agent · cost: $1.8633 · model: claude-opus-5}

---

_{📍 Citation health check (Foundry Constitution Principle I): 4 resolved, 4 unresolved against /Users/aetherclaude/workspace/AetherSDR at origin/main.}

Unresolved citations (4)

Citation	Reason
ClientCompEditorCanvas.cpp:169	file not found in workspace
MainWindow_Shortcuts.cpp:542	file not found in workspace
NetworkDiagnosticsDialog.cpp:1275	file not found in workspace
SpectrumWidget.cpp:11492	file not found in workspace