README.md

Inspector

Status: DRAFT — This document is awaiting review by an XH developer. Content may be incomplete or inaccurate. Do not remove this banner until a human reviewer approves the doc.

The Inspector is a built-in developer and admin tool for real-time inspection of a running Hoist application's HoistModel, HoistService, and Store instances, along with memory and performance statistics. It renders by default as a resizable bottom panel within the desktop application UI, driven by the InspectorService in /svc/, and can also be popped out into a separate browser window (see Pop-Out Window below).

Overview

During development (or for admin troubleshooting), the Inspector answers questions like:

• How many models are alive right now? Are any leaking?
• What are the current observable property values on a specific model instance?
• When was a model's doLoadAsync() last called? Did it succeed?
• How is JS heap memory trending over time?

The Inspector provides two main views: Stats (timeseries of model counts and memory) and Instances (browsable list of all live instances with property inspection).

Architecture

inspector/
├── InspectorPanel.ts                # Top-level container (renders Stats + Instances panels)
├── InspectorModel.ts                # Hosts the UI docked in the app or in a popped-out window
├── Inspector.scss                   # Inspector-specific styles
├── instances/
│   ├── InstancesPanel.ts            # Instance grid (left) + tabbed properties/diagnostics (right)
│   ├── InstancesModel.ts            # Model managing instance/property grids, watchlist, getters
│   ├── DiagnosticsPanel.ts          # Data-pipeline diagnostics readout for selected instances
│   └── DiagnosticsModel.ts          # Model syncing op stats from selected instance diagnostics
└── stats/
    ├── StatsPanel.ts                # Chart + grid combo for timeseries stats
    └── StatsModel.ts                # Model tracking model count, heap memory, sync runs

The Inspector UI is rendered by InspectorPanel, which composes two side-by-side panels: a StatsPanel (resizable left) and an InstancesPanel. Both are backed by dedicated HoistModel subclasses.

The actual data collection happens in InspectorService (in /svc/), which:

• Maintains an observable activeInstances array synced from Hoist's internal instance registry
• Tracks stats (timestamped model count + heap memory snapshots)
• Provides activate()/deactivate() methods to start/stop collection

Enabling the Inspector

Configuration

The Inspector is controlled by an optional xhInspectorConfig soft config (AppConfig). When not present, the Inspector defaults to enabled for all users.

{
    "enabled": true,
    "requiresRole": "HOIST_ADMIN",
    "statsUpdateInterval": 30000
}

Config Key	Type	Description
enabled	boolean	Master switch. Default true
requiresRole	string	If set, only users with this role can access the Inspector
statsUpdateInterval	number	Milliseconds between background stats updates. Default 30000 (30s)

Activation Methods

The Inspector can be toggled via:

1. Version bar button — Desktop apps display a version bar at the bottom of the screen. When the Inspector is enabled, the version bar includes a toggle button
2. Programmatic — XH.inspectorService.activate() / XH.inspectorService.deactivate() / XH.inspectorService.toggleActive()

The active state is persisted to localStorage, so the Inspector will remain open across page refreshes.

Pop-Out Window

Because the docked Inspector renders as a standard part of the app's component tree, app-level masks and modal dialogs will cover and block it. A button in the Inspector's header pops it out into a separate browser window (e.g. onto a second monitor), leaving the app's viewport entirely to the app while keeping the Inspector fully live, with direct access to all app state.

Hosting and window lifecycle are managed by InspectorModel, which portals the same component tree rendered when docked into the popped-out window. Notes and limitations:

• The popped-out state is not restored on app load - browsers require a user gesture to open a window, so the Inspector returns docked after a refresh.
• Closing the popped-out window directly returns the Inspector to its docked state. Reloading or closing the main app window closes the popped-out window.
• Toasts and framework dialogs (e.g. the "Restore Defaults" confirm) always render within the main app window, even when triggered from a popped-out Inspector.

Stats View

The Stats panel shows a timeseries chart and grid tracking:

Metric	Description
Model Count	Total number of live HoistModel instances
Model Count Change (#Δ)	Delta from previous snapshot (positive = models created, negative = destroyed)
Used JS Heap	Current used JavaScript heap memory (Chromium only, via performance.memory)
Total JS Heap	Total allocated heap
% Limit	Used heap as percentage of the browser's heap size limit

The chart renders three series: model count (area), used heap (line), and count delta (column). Clicking a row in the stats grid sets a "selected sync run" filter that can cross-filter the Instances view to show only instances created during that sync batch.

Sync runs: Each time the Inspector detects new instances in the registry, it increments a sync run counter. This groups instances by when they appeared, making it easier to identify which navigation or load action created them.

Instances View

The Instances panel is a split layout with:

• Instances grid (left, resizable) — Lists all live HoistModel, HoistService, Store, Cube, and View instances with their xhName (when set), class name, creation time, linked status, and sync run
• Properties grid (right) — Shows properties of the selected instance(s), including observable values with live updates
• Diagnostics panel (tabbed with properties) — Live readout of the data-pipeline diagnostics published by selected Stores, Cube Views, and GridModels

Instance Grid Features

• Grouping — Toggle "Show in Groups" to group by type (Models, Services, Stores)
• XH impl filtering — Toggle "Show XH Impl" to show/hide Hoist's internal framework instances (marked with xhImpl = true)
• Favorites — Star any instance with an xhName to pin it, then toggle "Favorites" to show only pinned instances. Keyed by {className}:{xhName} and persisted, so the same set of objects can be followed across reloads. Favorites with no live instance show as muted placeholder rows - un-star one to drop it
• Actions — Log instance to devtools console, trigger loadAsync() on models with LoadSupport
• Multi-select — Select multiple instances to compare their properties side-by-side

Properties Grid Features

• Observable tracking — Observable properties (via @observable, @bindable) are marked with an eye icon and their values update reactively in the grid
• Getter evaluation — Getter properties show as get(?) by default to avoid side effects. Click to evaluate on demand, or use "Load All Getters" to evaluate all at once
• Watchlist — Star properties to pin them to a persistent "Watchlist" group that aggregates watched properties across multiple instances
• Filtering — Toggle filters for: own properties only, observable properties only, hide underscore-prefixed properties
• Navigation — When a property value is a HoistModel, HoistService, Store, Cube, or View, clicking its value navigates to that instance in the instances grid
• Console logging — Double-click a property or use the action button to log its value to the browser devtools console

Diagnostics Panel

Store, Cube View, and GridModel publish diagnostics reporting on each data-pipeline operation they perform - see Diagnostics in the data package README. When any selected instance publishes diagnostics, this panel shows one row per operation kind with the last op's type (the path taken - e.g. an incremental patch vs. a full rebuild), the work done, its timing, and cumulative count/average stats. Selecting a Cube reports via its internal Store, where its data ops actually land.

• Log operations to console — Streams each op performed by the selected instances to the devtools console, by escalating their per-instance diagnostics.logLevel - no need to raise the app-wide XH.logLevel. Sticky per instance - logging continues when the selection moves elsewhere, and any number of instances can log at once.
• Reset — Clears counts and timings for the selected instances.

Select the instances along a data-change's path - e.g. a Cube's Store, a View on that cube, and the GridModel displaying its results - to localize the cost of the change to the stage responsible for it.

Persistence

Inspector state is persisted to localStorage under the key xhInspector.{clientAppCode}.*. This includes:

• Panel sizes (stats panel, instances panel)
• Grid column state for both grids
• Quick filter selections (grouping, xhImpl visibility, favorites, property filters)
• Favorited instances
• Store filter text
• Active/inactive state

The "Restore Defaults" button in the Inspector header clears all persisted state and restarts.

Usage Patterns

Development Workflow

The Inspector is most useful during active development:

1. Enable the Inspector via the version bar toggle
2. Navigate your app normally — watch the Stats chart for model count trends
3. If model count grows without bound on navigation, you may have a model leak
4. Select a suspicious instance in the Instances grid to inspect its properties
5. Add key properties to the Watchlist for persistent monitoring
6. Use sync run filtering to isolate instances created during a specific action

Detecting Model Leaks

A common development issue is models that are created but never destroyed (e.g. models created in render() without proper @managed cleanup). The Stats chart makes this visible:

• Healthy pattern: Model count rises on navigation, falls when navigating away (destruction cascade cleans up)
• Leak pattern: Model count only rises, never falling back down

Filter the Instances grid by sync run to identify which models were created during a particular navigation step, then inspect their class names to determine which component is leaking.

Common Pitfalls

Heap Memory Only Available in Chromium

The performance.memory API used by the Stats view is non-standard and only available in Chromium-based browsers (Chrome, Edge). In Firefox or Safari, heap-related columns will be empty.

Inspector Overhead

When active, the Inspector runs an autorun (throttled to 300ms) that reads observable properties from all tracked instances, plus a background stats timer. This adds some overhead — deactivate the Inspector when not actively debugging.

Getter Side Effects

Evaluating getters in the Properties grid can trigger side effects if the getter performs computation, network requests, or state mutations. The Inspector avoids evaluating getters automatically for this reason — they show as get(?) until explicitly triggered.

Related Packages

• /svc/ — InspectorService provides the data backing for the Inspector UI
• /core/ — HoistBase, HoistModel, HoistService are the instance types tracked by the Inspector
• /data/ — Store instances are also tracked in the Instances view