From aafdf3acc6409ac3622eed7c9e46c56804344577 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Fri, 12 Jun 2026 22:38:38 -0400 Subject: [PATCH] Docstrings: SSDL + ASCII Layout Map for Misc Tools and remaining MMA sub-functions --- src/gui_2.py | 323 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 315 insertions(+), 8 deletions(-) diff --git a/src/gui_2.py b/src/gui_2.py index 4068943d..97fd2d35 100644 --- a/src/gui_2.py +++ b/src/gui_2.py @@ -5979,14 +5979,21 @@ def render_approve_script_modal(app: App) -> None: Renders the modal dialog for approving AI-generated PowerShell scripts. Supports full script editing or markdown code blocks preview. - State Mutations: - app._pending_dialog_open - app.ui_approve_modal_preview - dlg._script (allows direct script mutation prior to approval) - app._pending_dialog (resets active pending dialog lock) - SSDL Shape: `[I:command_details] -> [B:preview_checkbox] -> [I:preview_box_or_editor] => [B:approve_reject]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Approve PowerShell Command | + | The AI wants to run the following PowerShell script: | + | base_dir: C:\projects\manual_slop | + | [ ] Read-only Full Preview | + | +-----------------------------------------------------+ | + | | Get-Content .\src\gui_2.py | Select-String 'def' | | + | | ... | | + | +-----------------------------------------------------+ | + | [Approve & Run] [Reject] | + +---------------------------------------------------------+ """ with app._pending_dialog_lock: dlg = app._pending_dialog @@ -6037,6 +6044,33 @@ def render_approve_script_modal(app: App) -> None: #region: Misc Tools def render_theme_panel(app: App) -> None: + """ + Renders the Theme configuration window. Covers palette selection, panel pop-out toggles, + font path/size, DPI scale, transparency sliders, background shader, CRT filter, and + per-palette tone mapping (brightness/contrast/gamma). + + SSDL Shape: + `[I:palette_combo] -> [B:panel_popout_toggles] -> [I:font_config] -> [I:scale_sliders] -> [I:tone_mapping]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Theme [x] | + | Palette: [Nerv v] | + | [ ] Separate Message [ ] Separate Response | + | [ ] Separate Tool Calls | + | Font: [path/to/font.ttf___________] [Browse] | + | Size (px): [14.0] [Apply Font (Requires Restart)] | + | UI Scale (DPI): [====|====] 1.00 | + | Panel Transparency: [======|===] 0.90 | + | Panel Item Transparency: [=====|====] 0.85 | + | [x] Animated Background Shader [ ] CRT Filter | + | Tone Mapping (Per-Palette) | + | Brightness: [====|=] 1.00 | + | Contrast: [====|=] 1.00 | + | Gamma: [====|=] 1.00 | + | [Reset Tone Mapping] | + +---------------------------------------------------------+ + """ if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_theme_panel") exp, opened = imgui.begin("Theme", app.show_windows["Theme"]) app.show_windows["Theme"] = bool(opened) @@ -6141,7 +6175,21 @@ def render_theme_panel(app: App) -> None: def render_shader_live_editor(app: App) -> None: """ - [C: tests/test_shader_live_editor.py:test_shader_live_editor_renders] + Renders the Shader Live Editor window. Exposes real-time sliders for CRT curvature, + scanline intensity, and bloom threshold. + + SSDL Shape: + `[I:shader_uniforms] => [I:slider_controls]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Shader Editor [x] | + | CRT Curvature: [======|=====] 0.80 | + | Scanline Intensity: [==|=========] 0.20 | + | Bloom Threshold: [===|========] 0.30 | + +---------------------------------------------------------+ + + [C: tests/test_shader_live_editor.py:test_shader_live_editor_renders] """ if app.show_windows.get('Shader Editor', False): with imscope.window('Shader Editor', app.show_windows['Shader Editor']) as (exp, opened): @@ -6152,6 +6200,27 @@ def render_shader_live_editor(app: App) -> None: changed_bloom, app.shader_uniforms['bloom'] = imgui.slider_float('Bloom Threshold', app.shader_uniforms['bloom'], 0.0, 1.0) def render_markdown_test(app: App) -> None: + """ + Renders a static markdown test panel used to validate the markdown renderer. + Displays headers, bold/italic text, lists, links, and a code block. + + SSDL Shape: + `[I:static_md_sample] => [I:rendered_markdown]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Markdown Test Panel | + | # Header 1 | + | ## Header 2 | + | This is **bold** text and *italic* text... | + | * List item 1 | + | * Sub-item | + | [Link to Google](https://google.com) | + | ```python | + | def hello(): ... | + | ``` | + +---------------------------------------------------------+ + """ imgui.text("Markdown Test Panel") imgui.separator() md = """ @@ -6212,6 +6281,23 @@ def render_project_stale_tint(app: App) -> None: def render_heavy_text(app: App, label: str, content: str, id_suffix: str = "") -> None: + """ + Renders a labelled heavy-text field: a [+] button to pop content into the Text Viewer, + a truncated inline preview, and a scrollable child panel showing the full content + (markdown-rendered for message/text/content/system labels; plain text otherwise). + + SSDL Shape: + `[B:pop_out_viewer] -> [I:label_preview] -> [I:content_child]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | [+] message: "You are a helpful assistant that..." | + | +-----------------------------------------------------+ | + | | You are a helpful assistant that specializes in... | | + | | ...full rendered content... | | + | +-----------------------------------------------------+ | + +---------------------------------------------------------+ + """ if imgui.button(f"[+]##{label}{id_suffix}"): app.text_viewer_type = 'markdown' if label in ('message', 'text', 'content', 'system') else 'json' if label in ('tool_calls', 'data') else 'powershell' if label == 'script' else 'text' app.text_viewer_title = label @@ -6292,7 +6378,32 @@ def render_mma_dashboard(app: App) -> None: if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_mma_dashboard") def render_mma_modals(app: App) -> None: - """Renders all MMA-specific approval and info modals.""" + """ + Renders all MMA-specific approval and info modals: Tool Execution Approval, + MMA Step Approval (with optional payload edit), MMA Spawn Approval (with + prompt/context editing), and the Cycle Detected error modal. + + SSDL Shape: + `[I:pending_queues] => [I:tool_approval_modal] | [I:step_approval_modal] | [I:spawn_approval_modal] | [I:cycle_modal]` + + ASCII Layout Map: + Conditionally opens (at most one at a time): + + [Approve Tool Execution modal] + Tool: py_get_definition | Args: {...} | [Approve] [Deny] + + [MMA Step Approval modal] + Ticket T-003 waiting... | payload preview or edit + [Approve] [Edit Payload / Show Original] [Abort Ticket] + + [MMA Spawn Approval modal] + Spawning Tier 3 for Ticket T-003 + Prompt + Context MD preview or edit + [Approve] [Edit Mode / Preview Mode] [Abort] + + [Cycle Detected! modal] + Circular dependency found. [OK] + """ is_nerv = theme.is_nerv_active() # Tool Execution Approval if app._pending_ask_dialog: @@ -6368,6 +6479,22 @@ def render_mma_modals(app: App) -> None: imgui.end_popup() def render_mma_track_summary(app: App) -> None: + """ + Renders the active-track summary row: track name, MMA pipeline status, and running + cost estimate, followed by a colour-coded progress bar and a 4-column breakdown table + (Completed / In Progress / Blocked / Todo) and ETA estimation. + + SSDL Shape: + `[I:track_name] -> [I:status_badge] -> [I:cost] -> [I:progress_bar] -> [I:stats_table] -> [I:eta]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Track: my-feature | Status: RUNNING | Cost: $0.0024 | + | [========================= ] 52.3% | + | Completed: 6 | In Progress: 1 | Blocked: 0 | Todo: 5 | + | ETA: ~14m (6 tickets remaining) | + +---------------------------------------------------------+ + """ is_nerv = theme.is_nerv_active() track_name = app.active_track.description if app.active_track else "None" if getattr(app, "ui_project_execution_mode", "native") == "beads": track_name = "Beads Graph" @@ -6416,10 +6543,50 @@ def render_mma_epic_planner(app: App) -> None: if imgui.button('Plan Epic (Tier 1)', imgui.ImVec2(-1, 0)): app._cb_plan_epic() def render_mma_conductor_setup(app: App) -> None: + """ + Renders the Conductor Setup panel. Runs a one-shot project-structure scan and + shows the summarised output in a read-only text area. + + SSDL Shape: + `[B:run_scan] => [I:summary_text]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | [Run Setup Scan] | + | +-----------------------------------------------------+ | + | | Project: manual_slop | | + | | Tracks found: 3 | Active: my-feature-20260612 | | + | | Tickets: 12 todo, 3 done | | + | +-----------------------------------------------------+ | + +---------------------------------------------------------+ + """ if imgui.button("Run Setup Scan"): app._cb_run_conductor_setup() if app.ui_conductor_setup_summary: imgui.input_text_multiline("##setup_summary", app.ui_conductor_setup_summary, imgui.ImVec2(-1, 120), imgui.InputTextFlags_.read_only) def render_mma_track_browser(app: App) -> None: + """ + Renders the Track Browser: a table listing all known tracks with status, progress bar, + and a [Load] button per row. Below the table is a form for creating a new track. + + SSDL Shape: + `[I:tracks_table] -> [B:load_button] -> [I:create_track_form] => [B:create_track]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Track Browser | + | +------------------+--------+----------+---------+ | + | | Title | Status | Progress | Actions | | + | +------------------+--------+----------+---------+ | + | | my-feature-0612 | ACTIVE | [===== ] [Load] | | + | | chore-cleanup | NEW | [ ] [Load] | | + | +------------------+--------+----------+---------+ | + | Create New Track | + | Name: [___________] | + | Description: [_____________________________] | + | Type: [feature v] | + | [Create Track] | + +---------------------------------------------------------+ + """ imgui.text("Track Browser") if imgui.begin_table("mma_tracks_table", 4, imgui.TableFlags_.borders | imgui.TableFlags_.row_bg | imgui.TableFlags_.resizable): imgui.table_setup_column("Title"); imgui.table_setup_column("Status"); imgui.table_setup_column("Progress"); imgui.table_setup_column("Actions"); imgui.table_headers_row() @@ -6446,6 +6613,22 @@ def render_mma_track_browser(app: App) -> None: app.ui_new_track_name = ""; app.ui_new_track_desc = "" def render_mma_global_controls(app: App) -> None: + """ + Renders the MMA global controls bar: Step Mode (HITL) toggle, pipeline status label, + Pause/Resume engine button, active tier badge, approval-pending blink indicator, and + the Hot Reload shortcut. + + SSDL Shape: + `[B:step_mode] -> [I:status] -> [B:pause_resume] -> [I:active_tier] -> [I:approval_blink] -> [B:hot_reload]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | [ ] Step Mode (HITL) Status: RUNNING [Pause] | + | | Active: Tier 3 | + | *** APPROVAL PENDING *** [Go to Approval] | + | Hot Reload: [Reload GUI] (Ctrl+Alt+R) | + +---------------------------------------------------------+ + """ changed, app.mma_step_mode = imgui.checkbox("Step Mode (HITL)", app.mma_step_mode) imgui.same_line(); imgui.text(f"Status: {app.mma_status.upper()}") if app.controller and hasattr(app.controller, 'engine') and app.controller.engine and hasattr(app.controller.engine, '_pause_event'): @@ -6474,6 +6657,27 @@ def render_mma_global_controls(app: App) -> None: imgui.same_line(); imgui.text_disabled("(Ctrl+Alt+R)") def render_mma_usage_section(app: App) -> None: + """ + Renders the Tier Usage table (tokens and estimated cost per tier) and, when expanded, + a collapsible Tier Model Config section with per-tier provider, model, tool-preset, + and persona overrides. + + SSDL Shape: + `[I:usage_table] -> [B:tier_model_config_header] => [I:combos_per_tier]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Tier Usage (Tokens & Cost) | + | +--------+------------------+-------+-------+--------+ | + | | Tier | Model | Input | Output | Cost | | + | +--------+------------------+-------+-------+--------+ | + | | Tier 1 | gemini-2.5-flash | 1,200 | 400 | $0.001 | | + | | TOTAL | | | | $0.004 | | + | +--------+------------------+-------+-------+--------+ | + | > Tier Model Config (collapsible) | + | Tier 1: [gemini v] [gemini-2.5-flash v] [None v] | + +---------------------------------------------------------+ + """ imgui.text("Tier Usage (Tokens & Cost)") if imgui.begin_table("mma_usage", 5, imgui.TableFlags_.borders | imgui.TableFlags_.row_bg): imgui.table_setup_column("Tier"); imgui.table_setup_column("Model"); imgui.table_setup_column("Input"); imgui.table_setup_column("Output"); imgui.table_setup_column("Est. Cost"); imgui.table_headers_row() @@ -6587,6 +6791,34 @@ def render_mma_agent_streams(app: App) -> None: imgui.end_tab_bar() def render_tier_stream_panel(app: App, tier_key: str, stream_key: str | None) -> None: + """ + Renders a single tier's live streaming text panel. For Tier 1, 2, and 4 a single scrollable + selectable text area is shown; for Tier 3 (stream_key=None), each worker ticket gets + its own labelled, colour-coded sub-child with an auto-scroll behaviour. + + SSDL Shape: + `[I:stream_text] => [I:single_scroll] | [I:worker_sub_children]` + + ASCII Layout Map (single-stream, e.g. Tier 1): + +---------------------------------------------------------+ + | +-----------------------------------------------------+ | + | | Tier 1 stream output text... | | + | | ... | | + | +-----------------------------------------------------+ | + +---------------------------------------------------------+ + + ASCII Layout Map (Tier 3 multi-worker): + +---------------------------------------------------------+ + | T-001 [running] | + | +-----------------------------------------------------+ | + | | Worker output for T-001... | | + | +-----------------------------------------------------+ | + | T-002 [completed] | + | +-----------------------------------------------------+ | + | | Worker output for T-002... | | + | +-----------------------------------------------------+ | + +---------------------------------------------------------+ + """ if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_tier_stream_panel") if app.is_viewing_prior_session: imgui.text_colored(theme.get_color("status_warning"), "HISTORICAL VIEW - READ ONLY") @@ -6634,6 +6866,28 @@ def render_tier_stream_panel(app: App, tier_key: str, stream_key: str | None) -> if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_tier_stream_panel") def render_track_proposal_modal(app: App) -> None: + """ + Renders the Track Proposal modal. Shows Tier 1's generated implementation tracks + with editable title and goal fields, and buttons to remove, start individual tracks, + accept all, or cancel. + + SSDL Shape: + `[I:proposed_tracks] -> [B:edit_title/goal] -> [B:remove/start] => [B:accept_all | B:cancel]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Proposed Implementation Tracks | + | Title: [my-feature-core_______________] | + | Goal: [Implement the rendering pipeline...] | + | [Remove] [Start This Track] | + | --- | + | Title: [my-feature-tests______________] | + | Goal: [Write unit tests for...] | + | [Remove] [Start This Track] | + | --- | + | [Accept] [Cancel] | + +---------------------------------------------------------+ + """ if app._show_track_proposal_modal: imgui.open_popup("Track Proposal") if imgui.begin_popup_modal("Track Proposal", True, imgui.WindowFlags_.always_auto_resize)[0]: @@ -6679,6 +6933,27 @@ def render_track_proposal_modal(app: App) -> None: imgui.end_popup() def render_ticket_queue(app: App) -> None: + """ + Renders the Ticket Queue Management panel. Provides select-all/none controls, + bulk action buttons, a 7-column scrollable table of tickets with drag-to-reorder, + priority/model combos, status labels, and per-row Kill/Block/Unblock actions. + + SSDL Shape: + `[B:select_all/none] -> [B:bulk_actions] -> [I:ticket_table] => [I:ticket_editor?]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Ticket Queue Management | + | [Select All] [Select None] [Bulk Execute] [Bulk Skip] | + | [Bulk Block] | + | +---+-------+----------+-------+----------+----------+ | + | |[ ]| ID | Priority | Model | Status | Desc ... | | + | +---+-------+----------+-------+----------+----------+ | + | |[x]| T-001 | [high v] |[def v]| in_prog | Impl ... | | + | |[ ]| T-002 | [med v] |[def v]| todo | Write... | | + | +---+-------+----------+-------+----------+----------+ | + +---------------------------------------------------------+ + """ imgui.text("Ticket Queue Management") if not app.active_track: imgui.text_disabled("No active track.") @@ -6952,6 +7227,26 @@ def render_task_dag_panel(app: App) -> None: # 4. Task DAG Visualizer imgui.text_disabled("No active MMA track or tickets.") def render_beads_tab(app: App) -> None: + """ + Renders the Beads Graph tab. Checks for `dolt` and `bd` CLI availability, + shows a warning if missing, then lists beads from the Dolt-backed BeadsClient + in a 3-column table (ID / Status / Title). + + SSDL Shape: + `[I:dep_check] -> [B:refresh] -> [I:beads_table]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Beads Graph (Dolt-backed) [Refresh Beads] | + | ⚠ Warning: 'dolt' not found in PATH. (if missing) | + | +------+-----------+---------------------------------+ | + | | ID | Status | Title | | + | +------+-----------+---------------------------------+ | + | | bd-1 | todo | Implement render pipeline | | + | | bd-2 | complete | Write tests | | + | +------+-----------+---------------------------------+ | + +---------------------------------------------------------+ + """ imgui.text("Beads Graph (Dolt-backed)") if imgui.button("Refresh Beads"): pass @@ -6993,6 +7288,18 @@ def render_beads_tab(app: App) -> None: imgui.text_colored(theme.get_color("status_error"), f"Error loading beads: {e}") def render_mma_focus_selector(app: App) -> None: + """ + Renders the Focus Agent selector. Filters the discussion entries list to show + only the output of the chosen tier agent (or All). Includes a clear [x] button. + + SSDL Shape: + `[I:focus_combo] -> [B:clear_x?]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Focus Agent: [All v] (or [Tier 2 v] [x]) | + +---------------------------------------------------------+ + """ imgui.text("Focus Agent:"); imgui.same_line() focus_label = app.ui_focus_agent or "All" if imgui.begin_combo("##focus_agent", focus_label, imgui.ComboFlags_.width_fit_preview):