Files
douyin_guaji-main/docs/superpowers/plans/2026-05-31-split-webui-large-files.md
T

29 KiB

Split WebUI Large Files Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Continue the large-file split after gui/gui_app.py by modularizing the WebUI frontend and, only after the frontend is stable, splitting the Web GUI Python server.

Architecture: Keep the current static WebUI behavior intact while moving code into focused webui/js/* and webui/css/* files. Each task changes one responsibility, preserves global names needed by DOMContentLoaded, runs focused tests, commits, and pushes before the next task.

Tech Stack: Plain HTML/CSS/JavaScript, Python http.server, pytest, browser smoke test for UI changes.


Current Evidence

From the current worktree on 2026-05-31:

File Lines Role
webui/styles.css 3745 WebUI visual system, layout, panels, logs, responsive rules
webui/app.js 2512 WebUI constants, state, API calls, rendering, polling, event wiring
gui/web_gui.py 1663 local HTTP server, runner, API routes, static file serving
webui/index.html 1232 WebUI DOM structure and config bindings

gui/gui_app.py is already down to about 130 lines and should not be the next split target. The next target is the WebUI bundle.

Stop Conditions

Stop this plan and write an outcome note when any one is true:

  1. webui/app.js is below 700 lines and webui/styles.css is below 1400 lines.
  2. The next split would require changing more than 3 of the large files in one task.
  3. Browser smoke finds a visual or runtime regression that cannot be fixed inside the current task boundary.
  4. Tests fail and the fix would require behavior changes outside the current responsibility.

Verification Commands

Run these after every JavaScript or HTML task:

python -m py_compile gui/web_gui.py tools/diagnostics/check_web_gui_config_sync.py > logs\webui_split_py_compile.log 2>&1
pytest tests/test_webgui.py tests/test_gui_webui_sync.py -q > logs\pytest_webui_split.log 2>&1

Expected:

py_compile: exit code 0
pytest: all selected tests PASS

Run these after every CSS or visual task:

python -m py_compile gui/web_gui.py > logs\webui_split_py_compile.log 2>&1
pytest tests/test_webgui.py -q > logs\pytest_webui_split.log 2>&1

Expected:

py_compile: exit code 0
pytest: all selected tests PASS

For frontend visual changes, also start the Web GUI and inspect it in a browser:

python gui\web_gui.py

Expected browser checks:

  • / loads without a blank page.
  • Console has no module load errors, syntax errors, or missing function errors.
  • Header buttons, tabs, logs panel, reservations panel, high-value panel, screenshot preview, and footer remain visible without overlap at desktop width.
  • At mobile width, command buttons wrap and panels remain readable.

Static Loading Decision

The current page loads:

<link rel="stylesheet" href="styles.css?v=console-20260520-theme-v35" />
<script src="app.js?v=console-20260520-theme-v35"></script>

Use classic scripts for the first JavaScript split instead of ES modules. This avoids a broad initialization rewrite and keeps inline event expectations simple. New scripts must be loaded before app.js if app.js depends on them.

For CSS, use multiple <link rel="stylesheet"> tags. Keep styles.css as the compatibility shell until the end of the CSS split.


Task 1: Add WebUI Static Asset Structure

Files:

  • Create: webui/js/README.md

  • Create: webui/css/README.md

  • Modify: webui/index.html

  • Step 1: Create asset directory docs

Create webui/js/README.md:

# WebUI JavaScript modules

Classic browser scripts loaded by `webui/index.html`.

Load order matters:

1. `constants.js`
2. `dom.js`
3. `api.js`
4. focused feature scripts
5. `app.js`

Keep behavior-preserving splits small. Do not introduce a build step unless a later plan explicitly replaces this static layout.

Create webui/css/README.md:

# WebUI CSS modules

Plain CSS files loaded by `webui/index.html`.

Recommended order:

1. `tokens.css`
2. `base.css`
3. `layout.css`
4. `components.css`
5. focused panel or feature CSS
6. `styles.css` compatibility remainder

Keep selectors stable so existing HTML and JavaScript continue to work.
  • Step 2: Add no-op load anchors to index.html

Insert comments around the existing assets:

  <!-- WebUI CSS modules are loaded before the compatibility remainder. -->
  <link rel="stylesheet" href="styles.css?v=console-20260520-theme-v35" />
  <!-- WebUI JS modules are loaded before the compatibility remainder. -->
  <script src="app.js?v=console-20260520-theme-v35"></script>
  • Step 3: Verify

Run:

pytest tests/test_webgui.py tests/test_gui_webui_sync.py -q > logs\pytest_webui_split.log 2>&1

Expected: selected tests PASS.

  • Step 4: Commit and push
git add webui/index.html webui/js/README.md webui/css/README.md
git commit -m "refactor(webui): add static module split structure"
git push

Task 2: Extract JavaScript Constants and Copy

Files:

  • Create: webui/js/constants.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create constants.js

Move these top-level constants from app.js into webui/js/constants.js unchanged:

const UI_LIMITS = Object.freeze({
  runLogMaxLines: 50000,
  runLogMaxChars: 200000,
  actionsLogMaxLines: 5000,
  scrollBottomThresholdPx: 5,
  screenshotPollMs: 1500,
  logPollMs: 800,
  statsPollMs: 1200,
});

const UI_CLASS = Object.freeze({
  busy: "isBusy",
  clickable: "isClickable",
  collapsed: "isCollapsed",
  listCollapsed: "isListCollapsed",
  reservationHeader: "reservationHeader",
  reservationBody: "reservationBody",
  reservationsList: "reservationsList",
  shotEmpty: "isShotEmpty",
  statusRunning: "statusRunning",
  statusIdle: "statusIdle",
  statusError: "statusError",
});

const RUN_TONE = Object.freeze({
  running: "running",
  idle: "idle",
  error: "error",
});

Also move UI_COPY, TIMELINE_SERIES_KEYS, TIMELINE_LAYOUT, TIMELINE_STROKES, and DEFAULTS unchanged.

  • Step 2: Remove moved constants from app.js

Delete only the moved constant declarations from webui/app.js. Keep state variables such as logIdx, pollTimer, runLogBuffer, and deviceOverviewState in app.js for now.

  • Step 3: Load constants.js before app.js

Change the bottom of webui/index.html to:

  <!-- WebUI JS modules are loaded before the compatibility remainder. -->
  <script src="js/constants.js?v=console-20260531-split-1"></script>
  <script src="app.js?v=console-20260531-split-1"></script>
  • Step 4: Verify

Run:

python -m py_compile gui/web_gui.py tools/diagnostics/check_web_gui_config_sync.py > logs\webui_split_py_compile.log 2>&1
pytest tests/test_webgui.py tests/test_gui_webui_sync.py -q > logs\pytest_webui_split.log 2>&1

Expected: both PASS.

  • Step 5: Browser smoke

Start:

python gui\web_gui.py

Open http://127.0.0.1:8765/ or the printed local URL. Confirm console has no UI_LIMITS is not defined, DEFAULTS is not defined, or fmtDuration is not defined errors.

  • Step 6: Commit and push
git add webui/index.html webui/app.js webui/js/constants.js
git commit -m "refactor(webui): extract frontend constants"
git push

Task 3: Extract DOM and Formatting Helpers

Files:

  • Create: webui/js/dom_utils.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create dom_utils.js

Move these functions from app.js into webui/js/dom_utils.js unchanged:

function $(id)
function setTextIfExists(id, text)
function clearEl(el)
function escapeHtml(s)
function fmtTime(ts)
function fmtNum(v)
function fmtDuration(seconds)

When implementing, copy the exact current function declarations and bodies from webui/app.js.

  • Step 2: Remove moved functions from app.js

Delete the moved function declarations only. Do not move UI initialization functions yet.

  • Step 3: Load dom_utils.js after constants.js
  <script src="js/constants.js?v=console-20260531-split-2"></script>
  <script src="js/dom_utils.js?v=console-20260531-split-2"></script>
  <script src="app.js?v=console-20260531-split-2"></script>
  • Step 4: Verify and smoke

Run the standard JavaScript verification commands. In browser console, confirm no $ is not defined, fmtDuration is not defined, or escapeHtml is not defined errors.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/dom_utils.js
git commit -m "refactor(webui): extract DOM and format helpers"
git push

Task 4: Extract API Client Helpers

Files:

  • Create: webui/js/api_client.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create api_client.js

Move these functions and state from app.js into webui/js/api_client.js unchanged:

let _apiFailStreak = 0;
const _apiFailThreshold = 2;
let _csrfToken = null;

function setConnState(state)
function notifyApiOk()
function notifyApiFail()
async function apiGet(path)
async function getCsrfToken()
async function apiPost(path, body)

When implementing, copy the exact current function declarations and bodies from webui/app.js.

  • Step 2: Remove moved declarations from app.js

Delete only the moved declarations. Keep feature-level functions such as refreshDevices, startRun, pollLogs, and pollStats in app.js.

  • Step 3: Load api_client.js after dom_utils.js
  <script src="js/constants.js?v=console-20260531-split-3"></script>
  <script src="js/dom_utils.js?v=console-20260531-split-3"></script>
  <script src="js/api_client.js?v=console-20260531-split-3"></script>
  <script src="app.js?v=console-20260531-split-3"></script>
  • Step 4: Verify and smoke

Run the standard JavaScript verification commands. In browser, click refresh devices and load config. Confirm API state footer updates and no apiGet is not defined or CSRF errors appear.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/api_client.js
git commit -m "refactor(webui): extract API client helpers"
git push

Task 5: Extract Log View Behavior

Files:

  • Create: webui/js/log_views.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create log_views.js

Move the log rendering and search functions from app.js into webui/js/log_views.js:

function classifyLogLine(line)
function renderLogLineNode(line)
function appendLog(lines)
function renderRunLog()
function appendRunLogLines(lines)
async function fetchActionsLog()
function renderActionsLog()

Keep these shared state variables in app.js for this task:

let runLogBuffer = [];
let runLogFilter = "";
let runLogMode = "filter";
let runSearchResultsBuffer = [];
let runSearchActive = false;
let actionsLogBuffer = [];
let actionsLogFilter = "";

Because classic scripts share global scope, log_views.js can keep using these names.

  • Step 2: Remove moved functions from app.js

Delete only the moved function declarations.

  • Step 3: Load log_views.js before app.js
  <script src="js/constants.js?v=console-20260531-split-4"></script>
  <script src="js/dom_utils.js?v=console-20260531-split-4"></script>
  <script src="js/api_client.js?v=console-20260531-split-4"></script>
  <script src="js/log_views.js?v=console-20260531-split-4"></script>
  <script src="app.js?v=console-20260531-split-4"></script>
  • Step 4: Verify and smoke

Run the standard JavaScript verification commands. In browser, check the run log filter/search and action log refresh.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/log_views.js
git commit -m "refactor(webui): extract log view behavior"
git push

Task 6: Extract Dashboard Renderers

Files:

  • Create: webui/js/dashboard_renderers.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create dashboard_renderers.js

Move these renderer functions from app.js into webui/js/dashboard_renderers.js:

function renderBars(containerId, dataMap, labelMap)
function renderTopContent(containerId, items)
function renderWinsTable(containerId, wins)
function renderTimeline(containerId, timeline)
function renderOverviewSparkline(svgId, timeline)
  • Step 2: Remove moved functions from app.js

Delete only the moved renderer declarations.

  • Step 3: Load dashboard_renderers.js before app.js
  <script src="js/dashboard_renderers.js?v=console-20260531-split-5"></script>
  <script src="app.js?v=console-20260531-split-5"></script>

Keep all earlier module script tags before dashboard_renderers.js.

  • Step 4: Verify and smoke

Run standard JavaScript verification. In browser, confirm stats charts, timeline tooltip, top content table, and wins table still render.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/dashboard_renderers.js
git commit -m "refactor(webui): extract dashboard renderers"
git push

Task 7: Extract Config Form Binding

Files:

  • Create: webui/js/config_form.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create config_form.js

Move these config-related functions from app.js into webui/js/config_form.js:

function getConfigBoundElements()
function syncMirrorFields()
function getConfigValue(cfg, key)
function coerceValue(type, raw, isCheckbox)
function applyConfigToUI(cfg)
function collectConfigFromUI()
async function loadConfig()
async function saveConfig()
  • Step 2: Remove moved functions from app.js

Delete only the moved config declarations.

  • Step 3: Load config_form.js before app.js
  <script src="js/config_form.js?v=console-20260531-split-6"></script>
  <script src="app.js?v=console-20260531-split-6"></script>

Keep all earlier module script tags before config_form.js.

  • Step 4: Verify and smoke

Run standard JavaScript verification and pytest tests/test_gui_webui_sync.py -q. In browser, load config, change one harmless UI field, save, reload, and confirm no config-binding error appears.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/config_form.js
git commit -m "refactor(webui): extract config form bindings"
git push

Task 8: Extract Polling and Device Actions

Files:

  • Create: webui/js/runtime_actions.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Create runtime_actions.js

Move these functions from app.js into webui/js/runtime_actions.js:

async function refreshDevices()
function decorateDeviceSelect()
function selectedDeviceId()
async function postDeviceAction(path, body, successPrefix)
async function forceStopRun()
async function sendBackKey()
async function wifiEnable()
async function wifiConnect()
async function wifiDisconnect()
async function tryAutoReconnectLastWifi()
async function wifiScan()
async function startRun()
async function testYanghao()
async function testComment()
async function stopRun()
async function pollLogs()
async function pollReservations()
async function pollHighValueRooms()
async function pollStats()
function startPolling()
function startStatsPolling()

Keep DOMContentLoaded event wiring in app.js.

  • Step 2: Remove moved functions from app.js

Delete only the moved runtime declarations.

  • Step 3: Load runtime_actions.js before app.js
  <script src="js/runtime_actions.js?v=console-20260531-split-7"></script>
  <script src="app.js?v=console-20260531-split-7"></script>

Keep all earlier module script tags before runtime_actions.js.

  • Step 4: Verify and smoke

Run standard JavaScript verification. In browser, click refresh devices, load config, start/stop if safe, refresh action log, and switch through all panels.

  • Step 5: Commit and push
git add webui/index.html webui/app.js webui/js/runtime_actions.js
git commit -m "refactor(webui): extract runtime actions and polling"
git push

Task 9: Reduce app.js to Initialization Glue

Files:

  • Create: webui/js/ui_init.js

  • Modify: webui/app.js

  • Modify: webui/index.html

  • Step 1: Move UI initialization helpers

Move these functions into webui/js/ui_init.js:

function initTheme()
function ensureToastContainer()
function toast(message, kind = "info", { duration = 3500 } = {})
function initConfigSearch()
function initFooter()
function attachCopyButtons()
function initKeyboardShortcuts()
function initHeaderScroll()
function initShotFullscreen()
function applyKbdHints()
function initStickySectionShadow()
function initShortcutsHelp()
function updateTabBadge(target, count)
function startReservationsCountdownTick()
function initTabs()
function attachNumberSteppers()
function pollShot()
function startShotPolling()
function setButtonBusy(id, busy)
function setRunOverview(state, meta, tone)
function updateDeviceOverview()
  • Step 2: Keep app.js as bootstrapping only

After this task, app.js should contain:

window.addEventListener("DOMContentLoaded", async () => {
  initTheme();
  initTabs();
  initConfigSearch();
  initFooter();
  attachCopyButtons();
  initShotFullscreen();
  initHeaderScroll();
  initKeyboardShortcuts();
  initShortcutsHelp();
  initStickySectionShadow();
  attachNumberSteppers();
  applyKbdHints();
  syncMirrorFields();
  await refreshDevices();
  await loadConfig();
  startPolling();
  startStatsPolling();
  startShotPolling();
  startReservationsCountdownTick();
  pollLogs();
  pollStats();
  pollShot();
  pollReservations();
  pollHighValueRooms();
});

During implementation, preserve the existing event listener bindings from the current DOMContentLoaded body. If the current body wires buttons or inputs, keep those bindings in app.js or move them into a clearly named bindAppEvents() function in ui_init.js.

  • Step 3: Verify and smoke

Run standard JavaScript verification. Browser smoke must cover initial load, tabs, theme, footer, shortcuts overlay, screenshot preview, logs, and config load/save.

  • Step 4: Commit and push
git add webui/index.html webui/app.js webui/js/ui_init.js
git commit -m "refactor(webui): reduce app script to initialization glue"
git push

Task 10: Split CSS Tokens and Base Rules

Files:

  • Create: webui/css/tokens.css

  • Create: webui/css/base.css

  • Modify: webui/styles.css

  • Modify: webui/index.html

  • Step 1: Extract theme tokens

Move these ranges from styles.css into webui/css/tokens.css:

  • :root { ... } light theme token block
  • :root[data-theme="dark"] { ... } dark theme token block
  • reduced-motion token or global animation defaults that are pure variables

Do not rename variables.

  • Step 2: Extract base element rules

Move base reset and generic element rules into webui/css/base.css:

  • *, html, body

  • button, input, select, textarea

  • generic focus-visible rules

  • global scrollbar rules

  • generic utility classes that are not tied to one panel

  • Step 3: Load extracted CSS before styles.css

  <!-- WebUI CSS modules are loaded before the compatibility remainder. -->
  <link rel="stylesheet" href="css/tokens.css?v=console-20260531-split-css-1" />
  <link rel="stylesheet" href="css/base.css?v=console-20260531-split-css-1" />
  <link rel="stylesheet" href="styles.css?v=console-20260531-split-css-1" />
  • Step 4: Verify and smoke

Run CSS verification commands. Browser smoke must compare light and dark theme basics, header, buttons, forms, and scrollbars.

  • Step 5: Commit and push
git add webui/index.html webui/styles.css webui/css/tokens.css webui/css/base.css
git commit -m "refactor(webui): extract CSS tokens and base rules"
git push

Task 11: Split CSS Layout and Shared Components

Files:

  • Create: webui/css/layout.css

  • Create: webui/css/components.css

  • Modify: webui/styles.css

  • Modify: webui/index.html

  • Step 1: Extract layout rules

Move app shell, header, workspace, panel grid, and footer layout rules into layout.css. Include responsive @media rules that only affect those layout selectors.

  • Step 2: Extract shared component rules

Move shared button, card, tab, field, table, tooltip, toast, skeleton, and shortcut overlay rules into components.css. Include related @media and prefers-reduced-motion blocks when they directly belong to those selectors.

  • Step 3: Load CSS in stable order
  <link rel="stylesheet" href="css/tokens.css?v=console-20260531-split-css-2" />
  <link rel="stylesheet" href="css/base.css?v=console-20260531-split-css-2" />
  <link rel="stylesheet" href="css/layout.css?v=console-20260531-split-css-2" />
  <link rel="stylesheet" href="css/components.css?v=console-20260531-split-css-2" />
  <link rel="stylesheet" href="styles.css?v=console-20260531-split-css-2" />
  • Step 4: Verify and smoke

Run CSS verification. Browser smoke must check desktop and mobile layout, tabs, cards, buttons, toast, tooltip, and shortcuts overlay.

  • Step 5: Commit and push
git add webui/index.html webui/styles.css webui/css/layout.css webui/css/components.css
git commit -m "refactor(webui): extract CSS layout and shared components"
git push

Task 12: Split CSS Feature Panels

Files:

  • Create: webui/css/panels.css

  • Create: webui/css/logs.css

  • Create: webui/css/charts.css

  • Modify: webui/styles.css

  • Modify: webui/index.html

  • Step 1: Extract panel-specific styles

Move screenshot preview, reservations, high-value room, realtime status, and panel-specific content rules into panels.css.

  • Step 2: Extract log styles

Move run log, action log, log line classification, log search, and log scrollbar rules into logs.css.

  • Step 3: Extract chart/table styles

Move chart blocks, timeline tooltip, bar rows, top content table, wins table, and related table rows into charts.css.

  • Step 4: Load CSS in stable order
  <link rel="stylesheet" href="css/tokens.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/base.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/layout.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/components.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/panels.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/logs.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="css/charts.css?v=console-20260531-split-css-3" />
  <link rel="stylesheet" href="styles.css?v=console-20260531-split-css-3" />
  • Step 5: Verify and smoke

Run CSS verification. Browser smoke must check screenshot preview, reservations, high-value room list, log panels, charts, and mobile wrapping.

  • Step 6: Commit and push
git add webui/index.html webui/styles.css webui/css/panels.css webui/css/logs.css webui/css/charts.css
git commit -m "refactor(webui): extract CSS feature panels"
git push

Task 13: Decide Whether to Split index.html

Files:

  • Modify: webui/index.html

  • Optional create: webui/partials/README.md

  • Step 1: Recount file sizes

Run:

rg --files -g "*.html" -g "*.js" -g "*.css" -g "*.py" | ForEach-Object { $lines=(Get-Content $_ | Measure-Object -Line).Lines; [PSCustomObject]@{Lines=$lines; Path=$_} } | Sort-Object Lines -Descending | Select-Object -First 20 | Format-Table -AutoSize
  • Step 2: Keep index.html intact unless it is still above 1000 lines

If index.html is at or below 1000 lines, do not split it in this plan. HTML partial loading would require server or build changes and is not needed yet.

If index.html remains above 1000 lines and the team wants smaller HTML files, write a separate spec before changing runtime behavior. That spec must choose one of:

  • server-side partial injection in gui/web_gui.py

  • client-side fetch of static partials

  • build-time HTML generation

  • Step 3: Commit only if docs are added

If webui/partials/README.md is created:

git add webui/partials/README.md
git commit -m "docs(webui): record HTML partial split decision"
git push

Task 14: Split gui/web_gui.py Only After Frontend Is Stable

Files:

  • Create: gui/web_gui_pkg/static_handler.py

  • Create: gui/web_gui_pkg/request_parsing.py

  • Create: gui/web_gui_pkg/routes.py

  • Modify: gui/web_gui.py

  • Test: tests/test_webgui.py

  • Step 1: Extract request parsing helpers

Move _send_json and _read_json behavior into functions that still receive the Handler instance:

def send_json(handler: BaseHTTPRequestHandler, obj: object, status: int = 200) -> None:
    data = json.dumps(obj, ensure_ascii=False).encode("utf-8")
    handler.send_response(status)
    handler.send_header("Content-Type", "application/json; charset=utf-8")
    handler.send_header("Cache-Control", "no-store")
    handler.send_header("Content-Length", str(len(data)))
    handler.end_headers()
    handler.wfile.write(data)
def read_json(handler: BaseHTTPRequestHandler) -> dict:
    n = int(handler.headers.get("Content-Length") or 0)
    raw = handler.rfile.read(n) if n > 0 else b"{}"
    try:
        value = json.loads(raw.decode("utf-8"))
    except Exception:
        return {}
    return value if isinstance(value, dict) else {}

Keep Handler._send_json and Handler._read_json as thin wrappers at first.

  • Step 2: Extract static file serving

Move _serve_static into gui/web_gui_pkg/static_handler.py:

def serve_static(
    handler: BaseHTTPRequestHandler,
    *,
    webui_dir: str,
    rel_path: str,
    log_error: Callable[[str], None],
) -> None:
    # paste current Handler._serve_static body and replace:
    # self -> handler
    # WEBUI_DIR -> webui_dir
    # _wg_log(...) -> log_error(...)

Keep Handler._serve_static as:

def _serve_static(self, rel_path: str) -> None:
    serve_static(
        self,
        webui_dir=WEBUI_DIR,
        rel_path=rel_path,
        log_error=lambda msg: _wg_log(msg, level="ERROR"),
    )
  • Step 3: Verify

Run:

python -m py_compile gui/web_gui.py gui/web_gui_pkg/static_handler.py gui/web_gui_pkg/request_parsing.py > logs\web_gui_split_py_compile.log 2>&1
pytest tests/test_webgui.py -q > logs\pytest_web_gui_split.log 2>&1

Expected: PASS.

  • Step 4: Commit and push
git add gui/web_gui.py gui/web_gui_pkg/static_handler.py gui/web_gui_pkg/request_parsing.py tests/test_webgui.py
git commit -m "refactor(webgui): extract request and static helpers"
git push

Task 15: Final Outcome Note

Files:

  • Modify: this plan file

  • Step 1: Record final sizes

Run:

rg --files -g "*.html" -g "*.js" -g "*.css" -g "*.py" | ForEach-Object { $lines=(Get-Content $_ | Measure-Object -Line).Lines; [PSCustomObject]@{Lines=$lines; Path=$_} } | Sort-Object Lines -Descending | Select-Object -First 20 | Format-Table -AutoSize
  • Step 2: Append outcome

Append:

## Outcome

- `webui/app.js`: 2512 -> actual final line count
- `webui/styles.css`: 3745 -> actual final line count
- `webui/index.html`: 1232 -> actual final line count
- `gui/web_gui.py`: 1663 -> actual final line count
- Extracted JS modules: actual module filenames
- Extracted CSS modules: actual module filenames
- Verification: exact pytest log path and browser smoke result
- Remaining large files: actual top remaining files from the final size command
  • Step 3: Commit and push
git add docs/superpowers/plans/2026-05-31-split-webui-large-files.md
git commit -m "docs(webui): record large-file split outcome"
git push

Execution Notes

  • Do not batch tasks. Each task must pass verification, commit, and push before starting the next one.
  • Keep query-string versions in index.html synchronized across all WebUI assets touched in a task.
  • Do not introduce a frontend build step in this plan.
  • Do not convert to ES modules until the classic-script split is complete and browser smoke is clean.
  • For JavaScript moves, copy exact function bodies first, verify, then optionally do tiny cleanup in a separate commit.
  • For CSS moves, preserve selector order unless the moved file load order proves an equivalent cascade.
  • Project rule: only stage files changed by the current task.