Crate eguidev

Expand description

Cross-target instrumentation for AI-assisted egui development.

eguidev captures widget state at frame boundaries and injects input through an egui plugin registered on the first instrumented frame, keeping automation aligned with the app’s real event loop. This crate is the instrumentation half of the automation stack: it is valid for native and wasm32 builds, and it intentionally does not ship the embedded script runtime, MCP server, or screenshot machinery.

§Quick start

Add a DevMcp handle to your app state and wrap each frame with FrameGuard. Input injection is automatic from there: the first FrameGuard registers an egui plugin that drains queued input into every pass of every viewport, so apps do not need any raw-input wiring. The handle stays inert until a native app opts into eguidev_runtime and attaches the embedded runtime in one bootstrap location.

use eframe::{App, egui};
use eguidev::{DevMcp, DevUiExt, FrameGuard};

struct MyApp {
    devmcp: DevMcp,
    name: String,
}

impl MyApp {
    fn new() -> Self {
        Self {
            devmcp: DevMcp::new(),
            name: String::new(),
        }
    }
}

impl App for MyApp {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        let ctx = ui.ctx().clone();
        let _guard = FrameGuard::new(&self.devmcp, &ctx);
        egui::Frame::central_panel(ui.style()).show(ui, |ui| {
            ui.dev_text_edit("app.name", &mut self.name);
            if ui.dev_button("app.submit", "Submit").clicked() {
                // ...
            }
        });
    }
}

§Build modes

Cross-target instrumentation: depend on eguidev only. DevMcp, FrameGuard, widget tagging, and fixtures all compile for native and wasm32 targets.
Native embedded runtime: add an app-local feature that enables the optional eguidev_runtime dependency, then call eguidev_runtime::attach(devmcp) in one bootstrap location. Keep that branch local to startup code instead of pushing #[cfg] into widget code.

§Instrumenting widgets

Use the DevUiExt trait for standard widgets. Each dev_* method takes an explicit string id and auto-populates role, label, and value metadata:

ui.dev_button("settings.save", "Save");
ui.dev_text_edit("settings.name", &mut name);
ui.dev_checkbox("settings.enabled", &mut enabled, "Enabled");
ui.dev_slider("settings.level", &mut level, 0.0..=100.0);

For custom widgets, use id (geometry only) or id_with_meta (explicit role/value/label). If you already have an egui::Response, use track_response_full to register it after the fact. Use container to annotate hierarchy so scripts can traverse parent/child relationships.

Custom widgets that should accept scripted set_value(...) calls must also consume queued overrides before rendering:

let id = "settings.mode";
if let Some(crate::WidgetValue::Int(index)) = take_widget_value_override(ui, id) {
    *selected = index as usize;
}

let response = render_custom_mode_picker(ui, selected);
track_response_full(
    id,
    &response,
    WidgetMeta {
        role: WidgetRole::ComboBox,
        value: Some(WidgetValue::Int(*selected as i64)),
        role_state: Some(RoleState::ComboBox {
            options: mode_labels.clone(),
        }),
        ..Default::default()
    },
);

Widget ids are the one canonical selector in the scripting API. Explicit ids must be unique within a captured frame; duplicates are treated as a hard automation fault.

§Fixtures

Apps register fixtures with DevMcp::fixtures and exactly one handler: DevMcp::on_fixture_runtime for automation-thread setup or DevMcp::on_fixture_ui for setup that must run on the egui UI thread. Each fixture must be independently invokable from any prior state and must leave the app in a baseline that can be described with readiness anchors. Use typed fixture params for controlled variants, preconditions for state that must already be true before the handler runs, and handler-returned values or anchors for dynamic fixture outcomes. Scripts call fixture("name", params?) to apply the named baseline, wait for fresh captures, verify static plus returned anchors, and receive the returned values. Widget and viewport handles resolve fresh across fixture boundaries, so rebinding root() after each fixture is usually unnecessary. Use fixture_raw("name", params?) only when you explicitly want the fire-and-forget behavior for debugging or manual setup flows.

§Scripting reference

The canonical Luau API, direct script evaluation helpers, and the smoketest runner all live in eguidev_runtime. edev serves those checked-in definitions through script_api and edev docs.

Structs§

Anchor: A single readiness anchor for a fixture baseline.
AutomationOptions
ButtonOptions: Options for selected-aware buttons.
CheckboxOptions: Options for third-state checkboxes.
ContainerGuard: RAII guard that pops a container scope when dropped.
DevMcp: DevMCP handle stored in app state.
DevMcpConfigError: Configuration error returned while building a crate::DevMcp handle.
DiagnosticError: Structured failure returned by an app diagnostic provider.
FixtureCall: Fixture call passed to a registered handler.
FixtureError: Structured fixture handler failure.
FixtureParam: One typed fixture parameter in a fixture catalog entry.
FixtureParams: Validated fixture params passed to a handler.
FixtureResponse: Successful fixture handler response.
FixtureSpec: Fixture metadata advertised by an app.
FrameGuard: RAII guard that calls begin_frame and end_frame automatically.
ProgressBarOptions: Options for progress bars.
ScriptPrelude: App Luau helpers evaluated before every script under an app namespace.
ScrollAreaMeta: Scroll metadata captured for a scroll area.
ScrollAreaState: Scroll area state tracker with one-shot offset jumps.
TextEditOptions: Options for text-edit widgets.
ViewportNameError: Error returned when a semantic viewport name is reserved or invalid.
ViewportSel: Explicit selector for a viewport.
ViewportSelParseError: Error returned when parsing a viewport selector string fails.
WidgetDataError: Error returned by strict widget data attachment.
WidgetLayout: Layout metadata captured for a widget when available.
WidgetMeta: Metadata for a widget used during tracking and layout analysis.
WidgetRange: Min/max bounds for a numeric widget.
WidgetState: Live widget snapshot exposed to scripting surfaces.

Enums§

AnchorCheck: Declarative readiness checks for fixture anchors.
ParamKind: Supported scalar kinds for fixture parameters.
RoleState: Role-specific widget metadata kept on internal registry entries.
WidgetRole: Widget role taxonomy for automation and scripting filters.
WidgetValue: Captured widget value for stateful controls.

Traits§

DevScrollAreaExt: Helper extensions for recording scroll areas with explicit ids.
DevUiExt: Helper extensions for recording common widgets with explicit ids.

Functions§

capture_layout: Capture layout metadata for an already-rendered custom widget response.
clear_viewport: Clear script-visible widgets for a viewport that is no longer rendered.
container: Run a closure within a container scope with an explicit id.
frame_scope: Wrap one viewport frame and register container_id as its root container.
id: Record a widget with an explicit id and geometry only.
id_with_meta: Record a widget with an explicit id and explicit metadata.
name_viewport: Register a semantic name for the viewport currently rendering in ctx.
publish_rect_meta: Publish metadata for a painter-drawn rect that has no egui::Response.
take_widget_value_override: Consume a queued widget value override for a custom instrumented widget.
track_response_full: Track an already-created widget response with explicit metadata.

Type Aliases§

DiagnosticResult: Result returned by an app diagnostic provider.
FixtureResult: Result returned by a fixture handler.

Crate eguidev

Crate eguidev Copy item path

§Quick start

§Build modes

§Instrumenting widgets

§Fixtures

§Scripting reference

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate eguidev