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

14 KiB
Raw Permalink Blame History

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_______________________
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

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:

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:

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.
View Git Blame Copy Permalink