Remote Debugger Architecture

The remote debugger is a runtime inspection and control channel for Hosanna apps. It is used by the browser DevTools extension, the screen and CollectionView recorders, and the MCP debugger tools.

Components

DevTools extension     MCP server / agents
        |                    |
        | ws :59153          | stdio
        v                    v
      hst run:debugger management API :59150
        |                    |
        | ws :59151          | ws :59152
        v                    v
      Web app              Roku/device app

Component	Provided by	Purpose
RemoteDebugClient	hosanna-ui	Handles normal DevTools commands in the running app
MCPRemoteDebugClient	hosanna-ui	Extends the client with request IDs, MCP context, tracing, screenshots, slices, and recordings
hst run:debugger	@tantawowa/hosanna-tools	WebSocket and HTTP proxy between app, extension, and MCP
DevTools extension	hosanna-ui-browser-extension	Human UI for tree inspection, remote input, logs, recorders, registry, and styles
hst run:mcp / hosanna-mcp	@tantawowa/hosanna-tools	MCP server used by AI agents and automation

Enabling Remote Debugging

Remote debugging is controlled by assets/meta/debug-flags.dev.json:

{
  "remoteDebug": {
    "isEnabled": true,
    "isStartServerByDefault": true,
    "host": "localhost",
    "webAppServerPort": 59151,
    "deviceAppServerPort": 59152
  },
  "mcp": {
    "isEnabled": true
  }
}

When the app launches, BaseApp creates either RemoteDebugClient or MCPRemoteDebugClient, registers it, and connects to the proxy. Web builds usually connect to 59151; device builds use 59152.

Protocol Areas

The protocol covers these areas:

• Hosanna tree: GetHsViews, GetHsViewByHid, SetHSFields
• SceneGraph tree: GetSGViews, GetSGViewById, SetSGFields
• CollectionView: GetCollectionView, GetRowsSlice, row/cell details, field updates, refresh, recordings
• Focus and navigation: GetFocusedView, SetFocusedView, GetDebugContext, GetFocusGraph
• Highlighting: hover highlight, sticky selection highlight, element selection by coordinates
• Registry: read, add, update, remove, clear
• IoC and instance pools: inspect services and pooled instances
• Events and input: SendEvent, SendKeyEvent, simulated key events, typed text
• Text-to-speech: inspect status, current item, queue, completed items, pause/resume/clear
• Tracing: handler tracing, render tracing, lifecycle tracing, render frequency, CollectionView row lifecycle
• Screenshots and reload: web screenshot, Roku screenshot through ECP, web app reload
• Logs: app logs, Roku logs, search, clear, export

Data Safety

Debugger serializers avoid directly walking arbitrary cyclic objects. Tree and state payloads use safe copying, depth controls, and targeted commands when possible. For large apps, prefer targeted commands such as GetFocusedView, GetDebugContext, GetCollectionView, GetRowsSlice, or GetHsViewByHid over repeatedly requesting the full tree.

Coordinate Inspection

Coordinate-based inspection uses app design coordinates. The simulator and mouse inspection send { x, y } to HighlightItem or HighlightItemSelect; the app uses hit testing against Hosanna bounds and CollectionView row/cell geometry to find the matching view.

Holding Shift while clicking in the simulator selects the parent of the last selected view. This is useful for moving from a leaf label/image to the containing row, cell, group, or screen.

Multi-App Debugging

The debug proxy can track multiple connected apps. Use --appName with hst run:debugger or hst run:dev to make instances easier to identify:

npx hst run:debugger --appName fanduel-hosanna
npx hst run:dev --vitePort 5170 --appName fanduel-hosanna

The DevTools app selector and MCP get_connected_apps / health output use these registrations.