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