docs(webui): 制定大文件拆分计划

This commit is contained in:
Your Name committed 2026-05-31 10:32:56 +08:00
1 parent 18b75ceda4
commit ec2f044d8c
1 file changed
+982
@@ -0,0 +1,982 @@
# 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:
```powershell
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:
```text
py_compile: exit code 0
pytest: all selected tests PASS
```
Run these after every CSS or visual task:
```powershell
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:
```text
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:
```powershell
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:
```html
<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`:
```markdown
# 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`:
```markdown
# 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:
```html
<!-- WebUI CSS modules are loaded before the compatibility remainder. -->
<link rel="stylesheet" href="styles.css?v=console-20260520-theme-v35" />
```
```html
<!-- WebUI JS modules are loaded before the compatibility remainder. -->
<script src="app.js?v=console-20260520-theme-v35"></script>
```
- [ ] **Step 3: Verify**
Run:
```powershell
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**
```powershell
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:
```javascript
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:
```html
<!-- 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:
```powershell
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:
```powershell
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**
```powershell
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:
```javascript
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`**
```html
<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**
```powershell
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:
```javascript
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`**
```html
<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**
```powershell
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`:
```javascript
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:
```javascript
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`**
```html
<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**
```powershell
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`:
```javascript
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`**
```html
<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**
```powershell
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`:
```javascript
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`**
```html
<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**
```powershell
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`:
```javascript
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`**
```html
<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**
```powershell
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`:
```javascript
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:
```javascript
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**
```powershell
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`**
```html
<!-- 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**
```powershell
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**
```html
<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**
```powershell
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**
```html
<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**
```powershell
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:
```powershell
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:
```powershell
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:
```python
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)
```
```python
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`:
```python
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:
```python
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:
```powershell
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**
```powershell
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:
```powershell
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:
```markdown
## 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**
```powershell
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.