ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
9c650d055497d9cbbf0944586c11e90581c02564
manual_slop/docs/guide_ascii_layout_map.md
T

9.9 KiB
Raw Blame History

Guide to ASCII UI Layout Maps (DSL)

This guide defines the syntax, visual vocabulary, and operational conventions of the ASCII UI Layout Map DSL used in the Manual Slop codebase. This DSL serves as a text-side design contract between the specification phase and the immediate-mode ImGui rendering implementation in src/gui_2.py and other UI components.

1. Rationale: Why ASCII for ImGui?

Immediate-mode graphical user interfaces (IMGUIs) like dear imgui have three properties that make them highly compatible with structured ASCII text representations:

  1. Rectilinear Layouts: IMGUI widgets are strictly rectangular, aligned horizontally or vertically, and positioned deterministically.
  2. Regular Grammar: Widget patterns (collapsible trees, sliders, combos, and tables) follow standard, recurring visual cues.
  3. Information-Dense, Not Ornate: Layout Maps focus on what information is presented and how it is structured, rather than pixel-perfect colors, paddings, or border-radius values.

Using ASCII Layout Maps allows developer-agents and users to share, iterate, and lock down user interface specifications directly within the text medium before committing to complex GUI implementation.

2. Core Conventions & Vocabulary

The ASCII UI Layout Map DSL uses a fixed set of symbols to represent standard ImGui controls.

Widget Lexicon

Widget Class ASCII Symbol Example Specification
Window Container =...= +=== My Window ===+ Represents a top-level OS or ImGui window wrapper.
Child Panel / Pane +---+ +----------------+ Represents a scrollable or bounded child section (imgui.begin_child).
Button [Label] [Save] Bounded by square brackets; no internal padding by default.
Checkbox (Unchecked) [ ] [ ] Word-wrap Interactive checkbox in the off/inactive state.
Checkbox (Checked) [X] or [✓] [X] Auto-Scroll Interactive checkbox in the on/active state.
Radio Button (Off) ( ) ( ) Global Mutually exclusive option in the inactive state.
Radio Button (On) (o) or (•) (o) Project Mutually exclusive option in the active state.
Dropdown / Combo [Value v] [gemini v] The lowercase v indicates a dropdown picker.
Dropdown (Selected) [Label: Value v] [Role: AI v] Displays both the field name and its active selection.
Text Input (Single) ` Value `
Slider / Drag Int [===-----] [=====---] 62% Represents a slider or drag-float/int showing current progress.
Tree Node (Closed) > Label > file_io A collapsible header or directory node in the collapsed state.
Tree Node (Open) v Label v file_io A collapsible header or directory node in the expanded state.
Table / Columns | | Name | Size | Columns separated by single pipes, indicating a tabular layout.
Separator --- --- A horizontal rule (imgui.separator).
Truncation Marker ... ...rest of 8KB... Indicates content or elements cropped out for layout brevity.

3. High-Resolution Challenges & Advanced Techniques

When a panel is highly complex, dense, or dynamically nested, a single, low-resolution ASCII map may fail to convey the necessary layout details. In these scenarios, the DSL utilizes three advanced layout techniques: Feature Zooming, Grid-Based Focus, and State Multiplicity Annotation.

3.1 Feature Zooming

Feature Zooming decomposes a complex interface into a parent macro-layout and multiple zoomed micro-layouts. The macro-layout uses a descriptive placeholder badge [Zoom: Component Name] to signal that a detailed sub-layout exists below.

Macro-Layout (High-Level Grid)

+========================= Workspace Hub =========================+
| Tabs: [Discussion] [Files] [Settings]                           |
+-----------------------------------------------------------------+
|                                                                 |
|  [Zoom: Files Sidebar]    |    [Zoom: Details Editor]           |
|                           |                                 |
+=================================================================+

Micro-Layout: Zoom 1 (Files Sidebar)

[Zoom: Files Sidebar]
+--------------------------+
| Filter: |*.py|           |
| v src                    |
|   [x] gui_2.py     (8KB) |
|   [ ] ai_client.py (4KB) |
| > tests                  |
+--------------------------+

Micro-Layout: Zoom 2 (Details Editor)

[Zoom: Details Editor]
+-------------------------------------------------------------+
| Active: gui_2.py                                            |
| File Mode: [masked v]   [Force Full]  [x] Auto-Aggregate    |
| ---                                                         |
| Fuzzy Anchor Slices:                                        |
| [New Slice]                                                 |
| | #L12-30: class App |                                      |
+-------------------------------------------------------------+

3.2 Grid-Based Focus Layouts

Grid-Based Focus overlays a logical coordinate system (columns A, B, C... and rows 1, 2, 3...) onto the layout map. This is particularly useful for specifying precise immediate-mode alignment (imgui.same_line()) and relative widths under high layout density.

Grid Focus Map:
    A                       B                      C
  +-----------------------+----------------------+--------------------+
1 | Preset: [default v]   | [Save Preset]        | [Delete]           |
  +-----------------------+----------------------+--------------------+
2 | Temp: [=============] | [ ] Show Advanced                         |
  +-----------------------+-------------------------------------------+

Alignment & Layout Matrix

  • Row 1:
    • A1: Width 40% of viewport. Combo box selecting layout presets.
    • B1: same_line() called with 10px spacing. Fixed-width button.
    • C1: same_line() called, right-aligned to content region edge. Fixed-width warning-tinted button.
  • Row 2:
    • A2: Width 60% of viewport. Float slider for temperature.
    • B2: same_line() called. Toggle checkbox spanning the remaining region.

3.3 State Multiplicity Annotation

Immediate-mode UI layouts change shape based on state variables (e.g. read mode vs. edit mode). A Layout Map can document these variations by appending a [State: Variable == Value] condition block above or inline with the layout.

Read Mode Layout

[State: app.discussion_mode == "read"]
+-----------------------------------------------------------------+
| [Role: User] @ 12:34:56                                  [Edit] |
|                                                                 |
| "How does the RAG aggregation logic handle file summaries?"    |
+-----------------------------------------------------------------+

Edit Mode Layout

[State: app.discussion_mode == "edit"]
+-----------------------------------------------------------------+
| [Role: User v] @ 12:34:56                                [Read] |
|                                                                 |
| +-------------------------------------------------------------+ |
| | How does the RAG aggregation logic handle file summaries?   | |
| +-------------------------------------------------------------+ |
| [Save Changes]  [Discard]                                       |
+-----------------------------------------------------------------+

4. Integration with SSDL (DAG Context)

ASCII Layout Maps must correspond to the SSDL (Spec/Sketch Description Language) operational flow defined in the function's docstring. SSDL maps the control flow and data mutation path through the immediate-mode graph.

Mapping SSDL Primitives to Layout Widgets

  • [I:widget_name] (Instruction) maps to a static widget, label, or display field.
  • [B:widget_name] (Branch) maps to interactive elements (e.g., checkboxes, dropdowns, popups) that fork control flow or toggle visibility of subsequent blocks.
  • [S:widget_name] (Stateful Mutation) maps to input fields, sliders, or action buttons that alter values on the App or Controller state.
  • => (Wide path) maps to multi-column layouts, tables, or tabs where rendering branches concurrently.

Example Alignment

def render_example_panel(app: App) -> None:
 """Renders a simple model parameter panel.
 
 SSDL: `[I:header] -> [B:enable_override] -> [S:temp_slider] => [B:status_badge]`
 
 ASCII Layout Map:
   +---------------------------------------------------------+
   | Model Parameters                                        | <- [I:header]
   | [X] Override Default Parameters                         | <- [B:enable_override]
   |   Temperature: [=======---------] 0.70                  | <- [S:temp_slider] (indented if enabled)
   | ---                                                     |
   | Status: READY                                           | <- [B:status_badge] (green if ready)
   +---------------------------------------------------------+
 """

5. Development & Verification Loop

When modifying or implementing layout panels, developers must follow a strict verification sequence to ensure that layout maps align with source code without introducing runtime bugs:

  1. AST Check: Run py_check_syntax on the modified file immediately after editing the docstrings.
  2. Regression Check: Run pytest tests/ to confirm that docstring formatting changes have not caused runtime syntax or encoding errors.
  3. Fidelity Comparison: Under the Puppeteer testing pattern, run visual simulations to capture actual ImGui viewport coordinates and ensure they correspond to the rows, columns, and zoom structures mapped in the ASCII DSL contract.
View Git Blame Copy Permalink