[maui-labs docs] Document DevFlow Web Inspector (browser-based interactive app mirror)

## Source PR

**PR**: https://github.com/dotnet/maui-labs/pull/295
**Title**: feat: DevFlow Web Inspector with AJAX refresh and modal support
**Author**: Matthew Leibowitz
**Merged**: 2026-07-08

## Summary of Changes

PR #295 adds the **DevFlow Web Inspector** — a browser-based interactive inspector that serves a running MAUI app as a live HTML page. When the DevFlow broker is running (`maui devflow broker start`), the inspector is served at:

```
(localhost/redacted)
```

Any browser or inspector tool can open this URL and see the native MAUI app rendered as a clickable, scrollable web page. Key capabilities:

- **Screenshot background** with positioned `(div)` elements overlaid for each UI element in the visual tree
- **Interactive**: click → tap, mouse wheel → scroll, pointer drag → swipe gesture — all transparently proxied to the real app
- **AJAX polling refresh** every 3 seconds (smart DOM diff — no full-page flash)
- **Modal support**: screenshots topmost page, element divs are offset-corrected for modals and sheets
- **Text input**: POST to `/api/fill` and `/api/key`
- **`data-*` attributes** on each element div — expose all DevFlow properties (`data-id`, `data-type`, `data-automationId`, `data-text`, `data-role`, `data-isVisible`, `data-isEnabled`, `data-isFocused`, `data-opacity`, `data-traits`, `data-gestures`, etc.)
- **WebSocket relay** at `/ws/events` for external clients that want push-based updates

A new public API field was also added to `ElementInfo`: `WindowBounds` (`windowBounds` in JSON) — the element's bounds relative to the window/screen, as distinct from page-relative `Bounds`.

## Documentation Pages Affected

- **New page needed**: `docs/developer-tools/devflow/web-inspector.md`
- **Update**: `docs/developer-tools/devflow/` landing or overview page — add link to new web-inspector page
- **Update**: `docs/TOC.yml` — add entry under the DevFlow section
- **Possibly update**: `docs/developer-tools/devflow/visual-tree.md` or equivalent API reference page — document the new `windowBounds` field on `ElementInfo`

## Suggested Changes

### 1. New page: `docs/developer-tools/devflow/web-inspector.md`

The in-repo draft at `docs/DevFlow/inspector.md` (in the maui-labs source repo) provides an excellent starting point. Key content to adapt:

**Title**: DevFlow Web Inspector

**Introductory paragraph** (suggested):

> The DevFlow Web Inspector serves a running MAUI app as a fully interactive HTML page. Open `(localhost/redacted) in any browser after starting the DevFlow broker to see your app rendered with a live screenshot background and clickable UI elements — no custom integration required.

**Getting started section**:

````bash
# 1. Start the broker (inspector is served at (localhost/redacted)
maui devflow broker start

# 2. Run your MAUI app with the DevFlow agent NuGet package installed.
# The agent auto-registers with the broker.

# 3. Open the inspector in your browser:
# (localhost/redacted) — agent list
# (localhost/redacted) — jump to the only connected agent
# (localhost/redacted) — specific agent by ID
```

**How it works** (architecture overview):

```
Browser / Inspector Tool
↕ HTTP
CLI Inspector Server (localhost:19223, broker-hosted)
- Generates HTML from visual tree
- Proxies API calls
- WebSocket relay
↕ HTTP
DevFlow Agent (inside the MAUI app)
- Visual tree API
- Screenshot API
- Action endpoints
````

**Interactions table**:

| User action | Inspector action | DevFlow endpoint |
|-------------|-----------------|-----------------|
| Click | Tap at coordinates | `POST /api/tap` |
| Mouse wheel | Scroll by delta | `POST /api/scroll` |
| Pointer drag | Swipe gesture | `POST /api/gesture` |
| (automatic) | Navigate back | `POST /api/back` |
| (automatic) | Fill text | `POST /api/fill` |
| (automatic) | Send key | `POST /api/key` |

**Refresh strategy section**:

> The inspector uses AJAX polling (every 3 seconds). Each poll fetches a JSON state object containing a timestamped screenshot URL and rendered element HTML. The client performs a smart DOM diff — patching only changed elements so hover and selection state is preserved and there is no visible flash. A WebSocket relay at `/ws/events` is also available for external clients that want push-based updates.

**Element `data-*` attributes table** (important for users building custom tooling on top of the inspector):

| Attribute | Property | Description |
|-----------|----------|-------------|
| `data-id` | `id` | DevFlow element ID |
| `data-parentId` | `parentId` | Parent element ID |
| `data-type` | `type` | Short type name (e.g. `Button`, `Label`) |
| `data-fullType` | `fullType` | Full .NET type name |
| `data-framework` | `framework` | Always `maui` |
| `data-automationId` | `automationId` | `AutomationId` for testing |
| `data-text` | `text` | Text content |
| `data-value` | `value` | Value property |
| `data-role` | `role` | Accessibility role (`button`, `textbox`, `checkbox`, …) |
| `data-isVisible` | `isVisible` | Visibility state |
| `data-isEnabled` | `isEnabled` | Enabled state |
| `data-isFocused` | `isFocused` | Focus state |
| `data-opacity` | `opacity` | Opacity (0–1) |
| `data-traits` | `traits` | Comma-separated: `interactive`, `focusable`, `scrollable`, `header` |
| `data-gestures` | `gestures` | Comma-separated: `tap`, `swipe`, … |
| `data-styleClass` | `styleClass` | Comma-separated CSS style classes |
| `data-nativeType` | `nativeType` | Platform native type (e.g. `Android.Widget.Button`) |
| `data-nativeProperties` | `nativeProperties` | JSON-encoded native property dictionary |
| `data-frameworkProperties` | `frameworkProperties` | JSON-encoded MAUI property dictionary |

### 2. Update `docs/TOC.yml`

Add a `Web Inspector` entry under the DevFlow section, e.g.:

```yaml
- name: Web Inspector
href: developer-tools/devflow/web-inspector.md
```

### 3. Update `ElementInfo` API reference (if one exists)

Add documentation for the new `WindowBounds` property:

> **`WindowBounds`** (`windowBounds` in JSON): The element's bounding rectangle in window/screen coordinates, as distinct from the page-relative `Bounds`. Used by the Web Inspector to correctly position element overlays when modals or sheets are active.

### 4. Update DevFlow overview / feature list page

Add a bullet or row for the Web Inspector feature, e.g.:

> - **Web Inspector** — Open `(localhost/redacted) to browse your running app in any browser. Supports click, scroll, and gesture interaction, live AJAX refresh, and modal support.

## Notes for the docs author

- The in-repo draft `docs/DevFlow/inspector.md` in the maui-labs repository contains a versioned roadmap section clearly marking which parts are **implemented** vs **future work**. The docs page should cover only the implemented V1 features; the future roadmap items (standalone `maui devflow inspector` command, toolbar, deep-linking, property editing) should be omitted or clearly marked as planned.
- The inspector is currently hosted *inside the broker* — there is no separate `maui devflow inspector` CLI command yet. The entry point is `maui devflow broker start`.
- Platform support: all platforms supported by DevFlow (iOS, Android, macOS, Windows, Linux/GTK).

> Generated by [PR Documentation Check](https://github.com/dotnet/maui-labs/actions/runs/28928270957) for issue #295 · [◷](https://github.com/search?q=repo%3Adotnet%2Fdocs-maui+is%3Aissue+%22gh-aw-workflow-call-id%3A+dotnet%2Fmaui-labs%2Fpr-docs-check%22&type=issues)

Start with the in-repo draft at docs/DevFlow/inspector.md and inspect the DevFlow landing page plus docs/TOC.yml. Create docs/developer-tools/devflow/web-inspector.md covering implemented V1 behavior, link it from the overview and TOC, and check whether the ElementInfo API reference needs the windowBounds field. Done means the page documents the broker-hosted entry point, supported interactions, refresh behavior, and attributes without presenting roadmap items as implemented.

Written by the indexing model from the issue text.