Add SSDL-style docstrings to context helper widgets (files and media, batch actions, presets, screenshots, snapshot tab)

2026-06-12 21:55:20 -04:00
parent 06b6d4794f
commit c3edbd9543
2 changed files with 94 additions and 29 deletions
@@ -421,35 +421,35 @@ class App:
  self._editing_preset_scope = "project"
  self._editing_preset_is_new = False
  self._presets_list: dict[str, dict] = {}
-  self._selected_preset_idx = -1
-  self._show_save_preset_modal = False
-  self._editing_tool_preset_name = ''
-  self._editing_tool_preset_categories = {}
-  self._editing_tool_preset_scope = 'project'
-  self._selected_tool_preset_idx = -1
-  self._editing_bias_profile_name = ""
-  self._editing_bias_profile_tool_weights: dict[str, int] = {}
+  self._selected_preset_idx                      = -1
+  self._show_save_preset_modal                   = False
+  self._editing_tool_preset_name                 = ''
+  self._editing_tool_preset_categories           = {}
+  self._editing_tool_preset_scope                = 'project'
+  self._selected_tool_preset_idx                 = -1
+  self._editing_bias_profile_name                = ""
+  self._editing_bias_profile_tool_weights        : dict[str, int] = {}
  self._editing_bias_profile_category_multipliers: dict[str, float] = {}
-  self._editing_bias_profile_scope = "project"
-  self._selected_bias_profile_idx = -1
-  self._new_bias_tool_name = "run_powershell"
-  self._new_bias_category_name = "General"
-  self._editing_persona_name = ""
-  self._editing_persona_description = ""
-  self._editing_persona_provider = ""
-  self._editing_persona_model = ""
-  self._editing_persona_system_prompt = ""
-  self._editing_persona_temperature = 0.7
-  self._editing_persona_top_p = 1.0
-  self._editing_persona_max_tokens = 4096
-  self._editing_persona_tool_preset_id = ""
-  self._editing_persona_bias_profile_id = ""
-  self._editing_persona_context_preset_id = ""
-  self._editing_persona_aggregation_strategy = ""
-  self._editing_persona_preferred_models_list: list[dict] = []
-  self._editing_persona_scope = "project"
-  self._editing_persona_is_new = True
-  self._persona_editor_opened = False
+  self._editing_bias_profile_scope               = "project"
+  self._selected_bias_profile_idx                = -1
+  self._new_bias_tool_name                       = "run_powershell"
+  self._new_bias_category_name                   = "General"
+  self._editing_persona_name                     = ""
+  self._editing_persona_description              = ""
+  self._editing_persona_provider                 = ""
+  self._editing_persona_model                    = ""
+  self._editing_persona_system_prompt            = ""
+  self._editing_persona_temperature              = 0.7
+  self._editing_persona_top_p                    = 1.0
+  self._editing_persona_max_tokens               = 4096
+  self._editing_persona_tool_preset_id           = ""
+  self._editing_persona_bias_profile_id          = ""
+  self._editing_persona_context_preset_id        = ""
+  self._editing_persona_aggregation_strategy     = ""
+  self._editing_persona_preferred_models_list    : list[dict] = []
+  self._editing_persona_scope                    = "project"
+  self._editing_persona_is_new                   = True
+  self._persona_editor_opened                    = False
  self._personas_list: dict[str, dict] = {}
  # --- Layout State ---
  self._persona_split_v = 0.4
@@ -3305,6 +3305,17 @@ def render_persona_editor_window(app: App, is_embedded: bool = False) -> None:

 def render_files_and_media(app: App) -> None:
 """
+ Renders the inventory of files and screenshots. Allows adding files or directories to the inventory
+ and attaching files or screenshots to the active context.
+
+ State Mutations:
+   app.files (updates inventory)
+   app.context_files (appends new files)
+   app.screenshots (appends or removes screenshot image paths)
+
+ SSDL Shape:
+   `[I:inventory] -> [B:add_files_folders] -> [I:screenshots] => [B:add_screenshots]`
+
 [C: tests/test_gui_fast_render.py:test_render_files_and_media_fast]
 """
 if imgui.collapsing_header("Files", imgui.TreeNodeFlags_.default_open):
@@ -3394,6 +3405,20 @@ def render_files_and_media(app: App) -> None:
 return

 def render_context_batch_actions(app: App, total_lines: int, total_ast: int) -> None:
+ """
+ Renders a batch actions control bar. Allows batch-changing view modes of selected files,
+ selecting/deselecting all, adding files, and generating context preview markdown.
+
+ State Mutations:
+   app.context_files[index].view_mode (batch sets view modes)
+   app.ui_selected_context_files (selects or clears selection set)
+   app.context_files (updates context files list)
+   app.context_preview_text (stores preview markdown)
+   app.show_windows["Context Preview"]
+
+ SSDL Shape:
+   `[I:context_files] -> [B:mode_batch_buttons] -> [B:selection_buttons] -> [B:all_add_del] => [B:preview]`
+ """
 imgui.text("Batch:")
 for mode in ["full", "summary", "skeleton", "outline", "masked", "none"]:
  if imgui.button(f"{mode.capitalize()}##batch"):
@@ -3772,6 +3797,17 @@ def render_save_workspace_profile_modal(app: App) -> None:
  imgui.end_popup()

 def render_context_presets_panel(app: App) -> None:
+ """
+ Renders the Context Presets configuration panel. Enables naming, saving, loading,
+ and deleting context presets.
+
+ State Mutations:
+   app.ui_new_context_preset_name (stores input preset name)
+   app.controller.project['context_presets'] (saves new presets)
+
+ SSDL Shape:
+   `[I:presets_list] -> [B:save_new_preset] => [B:presets_action_buttons]`
+ """
 imgui.text_colored(C_IN(), "Context Presets")
 imgui.separator()
 changed, new_name = imgui.input_text("Preset Name##new_ctx", app.ui_new_context_preset_name)
@@ -3794,6 +3830,15 @@ def render_context_presets_panel(app: App) -> None:
  if imgui.button(f"Delete##{name}"): app.delete_context_preset(name)

 def render_context_screenshots(app: App) -> None:
+ """
+ Renders a list of the currently attached screenshot image files.
+
+ State Mutations:
+   None directly.
+
+ SSDL Shape:
+   `[I:screenshots]`
+ """
 for i, s in enumerate(app.screenshots): imgui.text(s)

 def render_context_files_table(app: App) -> None:
@@ -3918,6 +3963,17 @@ def render_context_files_table(app: App) -> None:
        imgui.text_colored(theme.get_color("status_warning"), "[Slices Active]")

 def render_context_presets(app: App) -> None:
+ """
+ Renders context preset management controls (combobox selector, update button, save-as, and delete active).
+
+ State Mutations:
+   app.ui_active_context_preset (updates active context preset name)
+   app.ui_new_context_preset_name (stores input name)
+   app.controller (saves or deletes presets)
+
+ SSDL Shape:
+   `[I:presets] -> [B:presets_combo] -> [B:save_as_button] => [B:delete_active]`
+ """
 presets      = app.controller.project.get('context_presets', {})
 preset_names = [""] + sorted(presets.keys())
 active = getattr(app, "ui_active_context_preset", "")
@@ -4006,6 +4062,15 @@ def render_context_presets(app: App) -> None:
    app.ui_active_context_preset = ""

 def render_snapshot_tab(app: App) -> None:
+ """
+ Renders the Snapshot tab-bar, containing the resolved aggregate markdown and active system prompts.
+
+ State Mutations:
+   app._focus_md_cache (caches aggregated markdown per persona)
+
+ SSDL Shape:
+   `[I:aggregate_text] -> [B:copy_buttons] => [I:preview_panes]`
+ """
 with imscope.tab_bar("snapshot_tabs"):
  with imscope.tab_item("Aggregate MD") as (exp, _):
   if exp: