# 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.
