274 lines
14 KiB
Markdown
274 lines
14 KiB
Markdown
# Guide to ASCII UI Layout Maps (DSL)
|
|
|
|
This document provides a comprehensive specification and reference manual for the **ASCII UI Layout Map DSL** used in the Manual Slop application. It establishes the conventions, visual grammar, widget vocabulary, and advanced techniques required to model dear imgui interfaces in structured text.
|
|
|
|
---
|
|
|
|
## 1. Core Paradigm: Text-Side UI Contracts
|
|
|
|
Manual Slop is built around a thread-safe, immediate-mode render pipeline in `src/gui_2.py`. In an environment where AI developer-agents operate with text-based tools and cannot directly view or interact with the runtime window, graphical user interfaces must be modeled as structured, human-auditable text contracts.
|
|
|
|
The ASCII UI Layout Map DSL solves this problem by defining a strict visual grammar. Because Dear ImGui layouts are rectilinear, immediate-mode, and deterministic, they map directly to rectangular text blocks. By pairing a visual **ASCII Layout Map** with an operational **SSDL (Spec/Sketch Description Language)** DAG, we can fully specify both the layout structure and the logic flow of a panel before writing any Python code.
|
|
|
|
---
|
|
|
|
## 2. Exhaustive Widget Vocabulary
|
|
|
|
To maintain visual clarity, the DSL maps ImGui widgets to specific text representations.
|
|
|
|
### 2.1 The Widget Reference Table
|
|
|
|
| ImGui Widget Type | Python Code Example | ASCII Layout Representation | Notes / Alignment Rules |
|
|
|---|---|---|---|
|
|
| **Window Frame** | `imgui.begin("Title")` | `+================= Title =================+` | Top/bottom borders use double horizontal bars or thick lines. |
|
|
| **Child Panel** | `imgui.begin_child("id")` | `+-----------------------------------------+` | Standard single-line border mapping child boundaries. |
|
|
| **Button** | `imgui.button("Save")` | `[Save]` | Square bracket boundaries. Fits text exactly. |
|
|
| **Checkbox (Off)** | `imgui.checkbox("A", False)` | `[ ] Option A` | Box containing a space, followed by the label. |
|
|
| **Checkbox (On)** | `imgui.checkbox("B", True)` | `[X] Option B` or `[✓] Option B` | Box containing `X` or checkmark `✓`. |
|
|
| **Radio Button (Off)**| `imgui.radio_button("X", False)`| `( ) Choice X` | Parentheses containing a space, followed by the label. |
|
|
| **Radio Button (On)** | `imgui.radio_button("Y", True)` | `(o) Choice Y` or `(•) Choice Y` | Parentheses containing `o` or bullet `•`. |
|
|
| **Dropdown / Combo** | `imgui.combo("##c", 0, opts)` | `[Selected Value v]` | Lowercase `v` represents the dropdown arrow. |
|
|
| **Named Dropdown** | `imgui.combo("Role", 1, roles)`| `[Role: Selected Value v]` | Combines parameter name with current selection. |
|
|
| **Text Input Box** | `imgui.input_text("##t", val)`| `|Current Value_______________________|` | Bounded by pipes (`\|`), underscores denote empty space. |
|
|
| **Slider / Drag** | `imgui.slider_float("##s", v)` | `[=======----------------] 0.70` | Shows progress track, slider handle, and numerical label. |
|
|
| **Closed Tree Node** | `imgui.tree_node("node")` | `> Node Label` | The `>` symbol denotes a collapsed section. |
|
|
| **Open Tree Node** | `imgui.tree_node("node")` | `v Node Label` | The lowercase `v` denotes an expanded section. |
|
|
| **Table Grid** | `imgui.table_next_column()` | `\| Cell 1 \| Cell 2 \|` | Cell bounds delimited by pipes (`\|`). |
|
|
| **Separator** | `imgui.separator()` | `---` | Standard horizontal dividing rule. |
|
|
|
|
---
|
|
|
|
## 3. Layout Mathematics & Spacing Alignment
|
|
|
|
ImGui's layout calculations (such as wrapping, horizontal nesting, and right-alignment) are captured in the ASCII DSL using specific alignment conventions.
|
|
|
|
### 3.1 Horizontal Nesting (`imgui.same_line()`)
|
|
In ImGui, widgets stack vertically by default. To place widgets on the same horizontal line, `imgui.same_line()` is invoked. In the ASCII DSL, this is represented by placing the brackets on the same text line separated by explicit spacing.
|
|
|
|
#### Python Code
|
|
```python
|
|
imgui.text("Model Parameter:")
|
|
imgui.same_line()
|
|
imgui.set_next_item_width(120)
|
|
imgui.combo("##model", active_idx, models)
|
|
imgui.same_line()
|
|
if imgui.button("Reset"):
|
|
reset_model()
|
|
```
|
|
|
|
#### ASCII Layout Representation
|
|
```
|
|
Model Parameter: [gemini-1.5-flash v] [Reset]
|
|
```
|
|
|
|
### 3.2 Right Alignment & Viewport Widths
|
|
To convey width ratios, the map uses proportional spacing. If a button is aligned to the right edge of a panel, it is placed at the far right of the ASCII boundary box.
|
|
|
|
#### Proportional Width Mappings
|
|
* **Fill Available:** `|Text Input Field_______________________________|` (width extends to boundary)
|
|
* **Fixed Width:** `[Close]` (width matches the label length)
|
|
* **Proportional Split:**
|
|
```
|
|
+-------------------------------------------------------------+
|
|
| Left Column (40%) | Right Column (60%) |
|
|
| |Input A________________| | |Input B_____________________| |
|
|
+-------------------------------------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Advanced High-Resolution Techniques
|
|
|
|
When laying out complex, feature-dense screens, a standard single-pane ASCII wireframe will run out of resolution. The DSL utilizes three advanced techniques to handle high-density layouts.
|
|
|
|
### 4.1 Feature Zooming (Macro/Micro Decomposition)
|
|
|
|
Feature Zooming decomposes a master interface into a parent macro-layout and multiple zoomed micro-layouts. The parent layout references zoomed sections using a target badge `[Zoom: Unique Name]`.
|
|
|
|
#### Macro-Layout (The Orchestration Dashboard)
|
|
```
|
|
+============================== Conductor Dashboard =============================+
|
|
| [Conductor Setup] [Epic Planner] |
|
|
+------------------------------------+-------------------------------------------+
|
|
| | |
|
|
| [Zoom: Conductor Track Sidebar] | [Zoom: Task Execution Pane] |
|
|
| | |
|
|
+------------------------------------+-------------------------------------------+
|
|
| [Zoom: Token Budget Footer] |
|
|
+================================================================================+
|
|
```
|
|
|
|
#### Micro-Layout: Zoom 1 (Conductor Track Sidebar)
|
|
```
|
|
[Zoom: Conductor Track Sidebar]
|
|
+----------------------------------+
|
|
| Track Browser: |
|
|
| v ACTIVE TRACKS |
|
|
| (o) mcp_refactor [======] 40%|
|
|
| ( ) type_strengths [ ] 0%|
|
|
| > COMPLETED TRACKS |
|
|
| > ARCHIVED TRACKS |
|
|
+----------------------------------+
|
|
```
|
|
|
|
#### Micro-Layout: Zoom 2 (Task Execution Pane)
|
|
```
|
|
[Zoom: Task Execution Pane]
|
|
+-------------------------------------------------------------+
|
|
| Active: mcp_refactor |
|
|
| Target Tier: [Tier 2 Tech Lead v] |
|
|
| --- |
|
|
| Ticket Queue: |
|
|
| [✓] t2_1: Extract File IO (Ready) |
|
|
| [✓] t2_2: Extract Python (Blocked) |
|
|
| +---------------------------------------------------------+ |
|
|
| | [I:ticket_details] -> [B:approve_spawn] => [B:execute] | |
|
|
| +---------------------------------------------------------+ |
|
|
| [Execute Selected] [Skip Selected] |
|
|
+-------------------------------------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
### 4.2 Grid-Based Focus Layouts
|
|
|
|
For complex table configurations or form layouts, the DSL overlays a coordinate grid (Columns `A, B, C...` and Rows `1, 2, 3...`). This coordinates precise width constraints, alignment boundaries, and event triggers.
|
|
|
|
```
|
|
Grid Focus Map:
|
|
A (30%) B (50%) C (20%)
|
|
+------------------------+-------------------------+--------------------+
|
|
1 | Provider: [gemini v] | Model: [1.5-flash v] | Status: [Local] |
|
|
+------------------------+-------------------------+--------------------+
|
|
2 | Temp: [=====-----] 0.7 | Top-P: [===-------] 0.4 | [Reset Defaults] |
|
|
+------------------------+-------------------------+--------------------+
|
|
```
|
|
|
|
#### Grid Alignment Reference
|
|
|
|
* **Cell A1:** Combobox for provider selection. Spans exactly 30% of the table width.
|
|
* **Cell B1:** Combobox for model selection. Spans exactly 50% of the table width, aligned horizontally with A1.
|
|
* **Cell C1:** Status badge. Right-aligned inside its column with a green success color tint.
|
|
* **Cell A2/B2:** Numeric parameter sliders. Underneath Row 1, matching column boundaries.
|
|
* **Cell C2:** Action button. Right-aligned, triggers parameter resets.
|
|
|
|
---
|
|
|
|
### 4.3 State Multiplicity Annotation
|
|
|
|
GUI elements often mutate structure based on runtime state variables. Rather than cluttering a single ASCII sketch with multiple options, separate sketches are annotated with `[State: Condition]` expressions.
|
|
|
|
#### Read-Only State Layout
|
|
```
|
|
[State: app.show_editing_panel == False]
|
|
+-----------------------------------------------------------------+
|
|
| System Prompt: coding-assistant |
|
|
| "You are an AI coding assistant designed to solve tasks..." |
|
|
| [Edit Prompt] |
|
|
+-----------------------------------------------------------------+
|
|
```
|
|
|
|
#### Editing State Layout
|
|
```
|
|
[State: app.show_editing_panel == True]
|
|
+-----------------------------------------------------------------+
|
|
| System Prompt: coding-assistant |
|
|
| +-------------------------------------------------------------+ |
|
|
| | You are an AI coding assistant designed to solve tasks... | |
|
|
| +-------------------------------------------------------------+ |
|
|
| [Save Changes] [Cancel] |
|
|
+-----------------------------------------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Integration with SSDL (Spec/Sketch Description Language)
|
|
|
|
SSDL defines the operational control flow and data mutation path through the immediate-mode graph. Every docstring in `gui_2.py` must align its visual **ASCII Layout Map** with its functional **SSDL** flow.
|
|
|
|
### 5.1 SSDL Primitive Dictionary
|
|
|
|
* `[I:name]` (Instruction): Represents a passive rendering unit (labels, static text, or headers).
|
|
* `->` (Sequential path): Represents linear vertical or horizontal flow.
|
|
* `=>` (Wide path): Denotes parallel branches, such as columns, tables, or tab item rendering.
|
|
* `[B:name]` (Branch): Points to conditional widgets (checkboxes, popups, or expandable trees).
|
|
* `[S:name]` (Stateful Mutation): Represents inputs, sliders, or buttons that modify data.
|
|
* `[Q:name]` (State Query): Reads parameters from the App config or state.
|
|
* `[N:name]` (Nil Sentinel): Represents safety check values to prevent rendering crashes.
|
|
|
|
### 5.2 Side-by-Side SSDL-to-ASCII Alignment
|
|
|
|
The SSDL sequence operates as a code-path map for the corresponding layout widgets:
|
|
|
|
```python
|
|
def render_example(app: App) -> None:
|
|
"""Renders the RAG status and rebuild control.
|
|
|
|
SSDL: `[Q:rag_enabled] -> [B:rag_checkbox] -> [I:status_label] => [S:rebuild_btn]`
|
|
|
|
ASCII Layout Map:
|
|
+---------------------------------------------------------+
|
|
| [X] Enable RAG Subsystem | <- [B:rag_checkbox] (reads [Q:rag_enabled])
|
|
| Status: READY | Chunk Size: 512 | <- [I:status_label]
|
|
| [Rebuild Vector Index] | <- [S:rebuild_btn]
|
|
+---------------------------------------------------------+
|
|
"""
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Step-by-Step Collaborative Design Workflow
|
|
|
|
To align implementations with user intent, developer-agents and human partners follow a 5-step workflow:
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Step 1: Pick Target Panel] --> B[Step 2: Establish Boundaries]
|
|
B --> C[Step 3: Initial ASCII Draft]
|
|
C --> D{Step 4: Critique & Iterate}
|
|
D -- Refine Sketch --> C
|
|
D -- Approved --> E[Step 5: Lock Design Contract]
|
|
```
|
|
|
|
### Collaborative Dialogue Example
|
|
|
|
1. **Step 1 (Agent):** Proposes target: "Let's update the layout for the Workspace Profile Saver."
|
|
2. **Step 2 (Human):** Establishes boundaries: "Yes, it must fit inside a popup modal, require a profile name, and have checkable scopes for Window Layout and Project Settings."
|
|
3. **Step 3 (Agent):** Drafts initial ASCII sketch:
|
|
```
|
|
+---------------------------------------------------------+
|
|
| Save Workspace Profile [X] |
|
|
+---------------------------------------------------------+
|
|
| Name: |my-profile_____________________________________| |
|
|
| Scopes: |
|
|
| [X] Window Positions & Layouts |
|
|
| [X] Active Project Settings |
|
|
| [Save Profile] [Cancel] |
|
|
+---------------------------------------------------------+
|
|
```
|
|
4. **Step 4 (Human):** Critiques: "The Save and Cancel buttons should be aligned to the right, and let's add a scope for Provider configuration."
|
|
5. **Step 4 (Agent):** Redrafts the sketch:
|
|
```
|
|
+---------------------------------------------------------+
|
|
| Save Workspace Profile [X] |
|
|
+---------------------------------------------------------+
|
|
| Name: |my-profile_____________________________________| |
|
|
| Scopes: |
|
|
| [X] Window Positions & Layouts |
|
|
| [X] Active Project Settings |
|
|
| [X] Provider Configuration |
|
|
| [Save] [Cancel] |
|
|
+---------------------------------------------------------+
|
|
```
|
|
6. **Step 5 (Human):** Approves: "This is perfect. Lock the design."
|
|
|
|
---
|
|
|
|
## 7. Verification & Audit Protocols
|
|
|
|
Once a design contract is locked and implemented, it must pass a three-tiered verification gate:
|
|
|
|
1. **AST Integrity:** Every docstring modification must pass `py_check_syntax` to ensure it doesn't break python parsing.
|
|
2. **Regression Check:** The test runner (`pytest tests/`) must be run to verify zero side-effects. Docstring additions must never alter execution logic.
|
|
3. **Puppeteer Visual Audit:** In visual simulation tests, the captured Dear ImGui layout boundaries and widget visibility flags are compared against the rows, columns, and conditional states defined in the ASCII design contract.
|