From 9c650d055497d9cbbf0944586c11e90581c02564 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 13 Jun 2026 16:47:48 -0400 Subject: [PATCH] Docs: Add in-depth guide to ASCII UI Layout Map DSL --- docs/Readme.md | 1 + docs/guide_ascii_layout_map.md | 185 +++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 docs/guide_ascii_layout_map.md diff --git a/docs/Readme.md b/docs/Readme.md index c2c0390c..8c524cb0 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -40,6 +40,7 @@ This documentation suite provides comprehensive technical reference for the Manu | [Discussions](guide_discussions.md) | The Discussion system: 23-operation matrix A1-A7 (per-entry) + B1-B11 (discussion-level) + C1-C5 (undo/redo), Take naming convention (`_take_`), branching at any entry (`project_manager.branch_discussion`), promotion to top-level (`project_manager.promote_take`), user-managed role list (`app.disc_roles`), per-role filter linked to MMA persona focus, `_disc_entries_lock` thread-safety contract, Hook API session endpoints | | [State Lifecycle](guide_state_lifecycle.md) | Undo/redo via `HistoryManager` + `UISnapshot` (13 captured fields, 100-snapshot capacity, debounced change detection at render frame), reset flow (`_handle_reset_session` — clears 30+ fields, replaces project, preserves `active_project_path` per the 2026-06-08 regression fix), `App.__getattr__`/`__setattr__` state delegation to Controller, 8-thread io_pool with 11 lock-protected regions (per `IO_POOL_MAX_WORKERS = 8` in `src/io_pool.py:20`; bumped 4→8 in 4a338486 on 2026-06-06), hot-reload integration | | [Context Aggregation](guide_context_aggregation.md) | The `aggregate.py` (518-line) pipeline: 3 aggregation strategies (`auto`/`summarize`/`full`), 7 per-file view modes (`full`/`summary`/`skeleton`/`outline`/`masked`/`custom`/`none`), full `FileItem` schema (9 fields + `__post_init__` normalizer), `ContextPreset` schema and `ContextPresetManager`, Tier 3 worker variant (`build_tier3_context` with FuzzyAnchor re-resolution and focus-file handling), `force_full`/`auto_aggregate` short-circuits, output file numbering, cache strategy (static prefix + dynamic history) | +| [ASCII Layout Map](guide_ascii_layout_map.md) | Structured text DSL reference: core conventions and vocabulary (lexicon of widgets, borders, separators), high-resolution zooming micro-sketches, grid-based alignment overlay, state multiplicity conditional annotations, and SSDL operational flow mappings. | --- diff --git a/docs/guide_ascii_layout_map.md b/docs/guide_ascii_layout_map.md new file mode 100644 index 00000000..6e137d3d --- /dev/null +++ b/docs/guide_ascii_layout_map.md @@ -0,0 +1,185 @@ +# 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|` | `|C:\projects\slop|`| Bounded by pipes (`\|`), representing a text input field. | +| **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 + +```python +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.