aura-view: Previewing AURA files

aura-view displays dialogs, screens, components and preview blocks from .aura files through the dynamic loader. The native tool uses BasicHost: a gray background, full-area screens, components with a margin, and dialogs centered on a white frame. Options supply themes, assets and fonts.

Arguments receive placeholders unless a preview supplies values ("test-<name>", 0, false, #808080); records receive values per field and lists of records one entry. Errors leave the last valid version visible and report file, line and column. The preview does not execute an application workflow.

Architecture: Core and host

A custom preview tool can implement Host and pass its factory to run():

int main(int argc, char** argv)
{
	return aura::preview::run(argc, argv, MyHost::create,
		{.name = "my-view"});
}

Usage

build/dev/tools/aura-view/aura-view examples/hello

Pixel comparison

build/dev/tools/aura-view/aura-view examples/hello --render-previews /tmp/aura-previews
build/dev/tools/aura-view/aura-view examples/hello --render-previews /tmp/aura-previews --compare references

Output is stored under default/. Only declared previews are rendered; animations remain at their initial state. Values set later by application C++ code are absent. Review reference images visually after changes.

Unsaved content

aura-view reads from a shadow copy in /tmp/aura-view-<pid>, rather than directly from <dir>.

• Content: The copy consists of files from disk. If the editor has sent unsaved content, it replaces the corresponding file.
• Writing: Only changed files are rewritten.
• Error messages: Paths in loader messages are mapped back to <dir>.

This avoids requiring a separate loader interface for editor content.

Server protocol

JSON travels over stdin/stdout, one line per request and one line per response, in the same order. Logging goes to stderr.

Fields in every request: An optional "id" is returned in the response.

Contents of every response:

• Selection: roots with name, type (Dialog, Screen, Component, Preview), target (the displayed element), file, line, and signals, plus current.
• Host state: Additional response fields come from Host::state(); BasicHost supplies no device selector or language options.
• Controls: controls for the displayed element: {name, kind: "state", values, value}, {name, kind: "bool", value}, or kind "text", "int", "real".
• Theme: theme: every theme.<name> from the host (Host::themeValues()) with its type (color, string, bool, number) for completion; themeColors: colors as #aarrggbb (for editor color swatches). Set values apply per element until aura-view exits.
• Display: width, height. Host-specific options go through Host::setOptions(); BasicHost implements no language or accessibility options.
• Errors and signals: diagnostics with file, line, column, and message. signals contains signals triggered since the previous response, with names and arguments as AURA literals. If error is present, the request itself was invalid.
• Image: png as Base64 if the image changed.
• Animations: animating is true while an animation is running (spin, pressSink, ripple) or a Scroll continues moving after a drag. Time only advances in the server with frame; without frame, animations stand still.

The first response arrives on startup without a request (id is null).

VS Code

The extension tools/aura-vscode (from 0.3.0; animations from 0.4.0; states and previews from 0.10.0; devices and sidebar from 0.12.0; Preview dropdown and “State …” from 0.13.0; inspector from 0.14.0; values, gallery, colors, definition, and rename from 0.15.0) starts aura-view --server for aura.preview.directory (default app/ui) when the active .aura file is inside it, or for the file's own folder otherwise.

Open it with “AURA: Open Preview”, the preview button in the editor title bar, or Ctrl+K V.

• Live: While typing (after aura.preview.delay, default 150 ms), unsaved content is sent to the server. Saving or closing switches back to disk, and disk changes trigger refresh.
• Selection: The preview displays the dialog, component, or preview containing the cursor (“Follow Cursor”). Choosing another entry in the selection list disables following. Opening or switching to another .aura file enables it again; if the file belongs to a different tree, aura-view restarts for that tree. “Source” jumps to the definition.
• Errors: Errors appear as diagnostics in the editor and Problems panel. The preview then displays the last error-free version with a red border.
• Values: Text and number properties of the displayed element appear in the “Values” menu and update while typing (after 250 ms).
• Gallery: “Gallery” displays all previews from the displayed element's file as tiles, with components cropped. Clicking displays that preview. Tiles follow changes to files and options.
• Colors in the editor: Colors such as #c3000f and #80ffffff have a swatch and color picker. theme.mainColor and similar values display a swatch using the running preview's value (from the host theme); hovering shows the value.
• Go to Definition (F12) and Rename (F2): Components, records, dialogs, and screens throughout the UI tree; IDs within their root; root properties, states, and signals. label: on an instance or view: in a preview also leads to the declaration; line.description or row.tiles (including through repeat variables) leads to the record field. Rename supports components, records, dialogs, screens, and IDs; occurrences in C++ code (views::Name, buildName, NameArgs, ->id) are reported, not modified.
• Inspector: Holding Ctrl (Cmd) shows the element under the mouse with a frame, type, ID, size, and source. Ctrl+click jumps to its location in the .aura file, preferring the displayed element's file (a component instance there rather than the component's internals); a displayed preview remains selected. The loader records the origin on every node (Node::origin, dynamic mode only).
• Clicks: Holding the mouse button means finger down, enabling the pressed state. Releasing is the tap. Triggered signals appear below the image.
• States: Below the toolbar are the displayed element's states (dropdown) and bool properties (checkboxes); changes apply immediately without rebuilding.
• Devices and options: Device selection, language and accessibility require a custom host. BasicHost takes its size from --device at startup.
• Previews: If the displayed element has previews, select one in the “Preview” dropdown next to the states (“Default” = placeholders). States are labeled “State view”, etc.: they change a value live, like the application; a preview supplies a fixed set of values. The selection list only contains dialogs, screens, and components.
• Options: “Large Text” and “High Contrast” in the “Accessibility” menu (which indicates what is enabled), language, and zoom (fit, 50–200%, Ctrl + mouse wheel).
• Sidebar: The AURA icon in the activity bar opens preview settings (device, accessibility, language, follow cursor, animations, restart).
• Animations: With “Play”, the preview requests frames while the server reports animating: at most every 33 ms, one at a time, using actual elapsed time (at most 100 ms per frame). Without an active animation this costs nothing. “Pause” stops time, including pressSink when clicking. The choice applies to all previews and is retained.
• Restart: Restarts aura-view, for example after a build. If the server has crashed, the preview reports it. Output appears in the “AURA Preview” channel.

Configuration for a native AURA workspace (settings.json):

{
  "aura.preview.directory": "${workspaceFolder}/examples/hello",
  "aura.preview.command": "${workspaceFolder}/build/dev/tools/aura-view/aura-view",
  "aura.preview.env": {},
  "aura.preview.args": [],
  "aura.preview.delay": 150
}

Limitations

• Application state: Values the application sets through IDs after building (LEDs, selected tabs, rows and cells built by C++) are absent.
• Animations: Only animations defined in AURA run (pressSink, spin, Rive), not application animations (video, flyouts). --render shows the initial state.
• Background: Dialogs have the simple background behind them, rather than the screen over which the dialog opens in the application.

Interactive property signals

The preview does not execute the C++ application. For a signal following the pattern countChanged(int value), it automatically copies the single argument into the mutable count property. Names and value types must match; states only accept declared values. Other signals are displayed as before. The value survives a preview rebuild.

Inline handlers such as onTap: { state.count += 1; } run in the application, loader and preview; see Inline scripts.