Module app 

GUI application state and rendering.

State: the loaded Model, a live session::Engine (built over all derived measures), the current derived-measure snapshot, and the selected measure. The panels and windows (model browser, pivot grid, formula editor, Info panel) are all rendered each frame from this state. The GUI is a pure view/controller over improv_engine + the model; it adds no modeling semantics (see .agent/steering/AGENT_GUI_STEERING.md §9.3).

The engine is rebuilt (a structural rebuild) only when the measure structure changes — a formula edit or a new derived measure. Plain cell-value edits go through engine.set incrementally.

Structs

FormulaRow

One row of the formula pane: a single derived measure’s formula as the reference’s numbered, checkable list shows it (✓ 1. Gross Margin = Sum of Revenue - Sum of Cost of Sales).

GutterRects 🔒

The measured screen geometry of the grid’s margin gutters and the table they frame, as laid out in the last frame.

ImprovApp

The running GUI application.

InspectorData 🔒

Read-only facts about a measure, assembled for the Info panel.

Matrix 🔒

One matrix on the canvas: a measure, that matrix’s OWN pivot / filter / cursor / cell-editor state, and where it sits (rect).

Enums

Axis

Which grid axis a category is assigned to.

FilterReq 🔒

A filter change asked for from a category tile’s menu, applied to that tile’s matrix after the gutters are laid out (like a re-pivot move).

FormulaEditor 🔒

One of the formula pane’s two editors.

Constants

CASCADE 🔒

How far a newly added matrix is offset from the last one, in points, so a fresh matrix never lands exactly on top of its predecessor (the classic cascade). See ImprovApp::add_matrix.

DISABLED_MARKER 🔒

The reserved leading marker in [Measure::description] that flags a derived measure’s formula as disabled — the reference’s cleared ✓ (see docs/reviews/2026-09-22-gui-reconstruction-plan.md Step 2).

EDGE_EPS 🔒

Tolerance, in points, for the gutter-adjacency invariant. The edges are computed from the same panel cursor so they agree exactly; half a point of slack only guards against rounding in egui’s pixel alignment.

GRID_MIN_H 🔒

Height a worksheet window keeps for its gutters and grid: its formula pane grows (or defaults) no taller than what leaves this much above it.

INITIAL_WINDOW

Initial window inner size: room for the menu, a default matrix and the Info panel side by side on the workspace.

MARKER_SEP 🔒

Separator between the marker and the user’s own description text.

MATRIX_MIN_H 🔒

MATRIX_MIN_W 🔒

Smallest a worksheet window can be resized to. Below roughly this it has no room for its gutters and a cell, so shrinking further would only hide its own chrome; gutters_have_room is the same judgement about the window.

MENU_CLEAR 🔒

Where a fresh canvas’s first matrix starts on the workspace: right of the application menu (at x 4, about 110 wide), as in the NeXT layout.

MIN_WINDOW

Minimum window inner size. Smaller windows still never overdraw the side panels (the canvas clips), but the matrix would be mostly scrolled away.

STATUS_TTL 🔒

Seconds a status message stays up before the status bar clears it.

TILE_H 🔒

A category tile’s height (the NeXT tiles are 17 px tall).

UNDO_DEPTH 🔒

How many model states the undo (and redo) stack keeps; older entries are evicted.

Functions

aggregation_dsl 🔒

AGG(args…) with its OVER clause after the first reduced argument (the parser accepts it after any), the window or WHERE there too. None when the shape has no spelling (a reduced argument that is not a plain reference, reduced arguments with different OVER lists, EXCEPT).

anchored_rect 🔒

The rect to show NxWindow win at: home on the workspace until the user moves or resizes it, then where they left it. The workspace settles over the first frames and follows the native window’s size, so a plain default_rect would keep the first frame’s guess.

assisted_formula_edit 🔒

A formula editor with autocomplete (crate::completion): while a name is typed (at or after byte from), a list of what may complete it drops under the edit (Up/Down select, Tab or Enter accept, Esc closes; a click accepts too), the rest of the selected name and its parameters trail the caret in light gray, and a tooltip shows the signature of the function being completed or called, the current argument in bold. With the list closed every key reaches the edit, so Enter still commits.

bound_dsl 🔒

A window bound literal as written: FIRST, LAST, THIS, THIS-2.

build_engine 🔒

Build a live engine over all derived measures in model, plus its initial snapshot. Falls back to no engine (inputs still render) on build failure.

call_dsl 🔒

caret_byte 🔒

Byte offset of the caret in text edit id over text (its end when the edit has none yet).

category_name 🔒

cell_key_multi 🔒

The sorted CoordKey for a cell when categories are STACKED on each axis: row_cats[i] binds to row_tuple[i], col_cats[j] to col_tuple[j], plus the pinned page dims. Tuples come from axis_tuples so they align with the category list. The general form of cell_key.

child_dsl 🔒

expr_dsl, parenthesized when e binds more loosely than its context.

completion_list 🔒

The completion list under (or, without room, over) the edit resp, sel highlighted; its rect is kept under rid so a press on it can pick a row. Returns whether it went below.

consume_enter 🔒

Swallow this frame’s Enter once a text field has acted on it, so the grid (drawn later, and now seeing no focus) doesn’t start a cell edit.

decode 🔒

engine_model 🔒

model as the ENGINE must see it: every measure whose formula is disabled flattened to MeasureKind::Input, keeping its (still-stored) formula out of the dataflow entirely.

expr_dsl 🔒

formula_disabled 🔒

Whether m’s formula is disabled (see DISABLED_MARKER). Always false for an input measure, which has no formula to disable.

formula_dsl 🔒

Render formula as symbolic-DSL source text that parser::parse_expr parses back to the identical AST, or None when the v1 grammar has no exact spelling for the shape (a bare ref carrying over/except, a multi-category OVER, an empty measure/category name, an enum/error/negative/exponent literal, an unknown function id). Callers fall back to the controlled-English description for those, which commit_formula also accepts.

formula_error_lines 🔒

A formula error under its row, indented past the checkbox and number: the message, and under it the hint, dimmed.

formula_fault 🔒

An engine-build failure for formula text, located in it; None for a failed save, which is no fault of the text.

formula_text_edit 🔒

A formula editor: a single-line edit of text with id id, highlighted, the error span underlined, filling the row. keep_tab: Tab stays in the edit rather than moving the focus.

func_name 🔒

The DSL name of a built-in function id, from the function registry.

grid_keys_enabled 🔒

Whether the grid’s single-key bindings (cursor motion, paging, measure cycling, undo/redo) should act this frame.

gutters_frame_table 🔒

Whether the gutters genuinely frame the table: the row gutter’s right edge is the table’s left edge, the column gutter’s bottom edge is the table’s top edge, each gutter spans the table along its other axis, and the corner well sits below the table at the row gutter’s left edge.

gutters_have_room 🔒

Whether the window left the gutters enough room to be laid out at all.

ident 🔒

The DSL spelling of name as an identifier: the bare form when the tokenizer reads it back as a single non-keyword identifier, else the quoted form ('Unit Price') the grammar gained in plan Step 4a.

is_aggregation 🔒

Whether func aggregates (SUM(x OVER T)), per the function registry.

is_bare_ident 🔒

Whether name survives a round trip through the tokenizer as one bare identifier that the grammar will not mistake for a keyword.

join_marker 🔒

Rebuild a description from the two parts split_marker takes apart — its inverse for every input split_marker can produce.

literal_dsl 🔒

matrix_window_id 🔒

The crate::nxwin::NxWindow id of the worksheet window of the matrix whose uid is uid.

natural_axis_order 🔒

The measure’s categories in natural (declared) order (empty if none/absent).

next_matrix_uid 🔒

A fresh Matrix uid.

nth_tuple 🔒

The i-th line of the Cartesian product of lists (outer category first), by mixed-radix decoding of i across the list lengths — the inner (last) category is the least-significant digit, matching axis_tuples’ ordering (which increments the inner category fastest). Returns the bound (ItemId, name) per category.

parse_typed 🔒

Parse cell text as declared, the measure’s declared type. The declared type WINS over the text’s shape: "42" for a Text measure is text, not a number. Unparsable text is an error (never a coerced value), so a bad edit leaves the prior typed cell untouched.

pick_default_measure 🔒

prec 🔒

Binding tightness, mirroring parser’s grammar levels (higher binds tighter). Used to emit exactly the parentheses needed to round-trip.

product_len 🔒

The number of axis lines the Cartesian product of lists produces: the product of each list’s length (empty lists -> 1, the scalar axis; any empty list -> 0, no lines). Mirrors axis_tuples(..).len() but is O(k) in the number of categories, never materializing the product.

push_bounded 🔒

Push state onto a bounded history stack, evicting the oldest entry once UNDO_DEPTH is reached.

ref_dsl 🔒

set_caret 🔒

Put the caret of text edit id over text at byte at.

signature_tooltip 🔒

The signature tooltip over (above) or under the edit resp: name’s parameters with argument arg bold and underlined, then d’s description and category.

split_marker 🔒

Split a measure description into (formula disabled, the user's own text).

try_build_engine 🔒

Build a live engine over every enabled derived measure in model, propagating a build failure (cycle, type/dimension error) instead of swallowing it. A measure whose formula is disabled (DISABLED_MARKER) is excluded, via engine_model.

white_selection 🔒

Give ui’s selected rows a white face. The palette makes egui’s selection fill and hover fill the same gray as the panel, so a selected selectable_label would look merely hovered. Call inside a ui.scope (or a child ui) so text-edit selection keeps the theme’s color.

Type Aliases

ChartAxes 🔒

The resolved pivot for the chart: the ROW category stack, the COLUMN stack, and the pinned (category, item) for every PAGE dimension.

GridScroll 🔒

A grid’s horizontal scroll area, wrapping its table’s vertical one and the rect that vertical scroller was laid out in.