core/docs/REFACTOR-0.10.3.md

v0.10.3 — Frontend Refactor Plan

Problem

Two monolith files accumulate every feature:

File	Lines	Role
app.js	2,940	All application logic + listeners
ui.js	2,582	All rendering + admin + settings
api.js	575	HTTP client (fine)
debug.js	580	Debug logger (fine)
events.js	327	EventBus WebSocket (fine)
Total	7,004

The v0.10.2 syntax bug (orphan brace nesting everything from notes through banners) is a direct consequence: in a 2,940-line file, a misplaced insertion is invisible.

Constraints

• Vanilla JS — no build step, no bundler, no ES modules.
• Global functions — HTML onclick handlers call ~25 named globals. These must stay on window. No renaming.
• Load order via <script> tags — dependencies load first.
• Service worker — sw.js pre-caches the file list; must be updated.
• Cache busting — all <script> tags use ?v=%%APP_VERSION%%.
• Docker entrypoint — COPY src/ covers everything. No changes needed.
• CI syntax check — already runs node --check on src/js/*.js.

Architecture

The UI object stays as a single global with methods. Domain files extend it via Object.assign(UI, { ... }). The App state object stays in app.js. All functions stay global.

Load order (dependency graph, top to bottom):

vendor/marked.min.js, vendor/purify.min.js
  ↓
debug.js, events.js
  ↓
api.js
  ↓
ui-format.js          ← esc(), markdown rendering (used by everything)
  ↓
ui-core.js            ← UI object: sidebar, chat list, messages, streaming, model selector
  ↓
ui-settings.js        ← Object.assign(UI, { settings/team methods })
ui-admin.js           ← Object.assign(UI, { admin modal methods })
  ↓
tokens.js             ← Tokens object, context tracking
notes.js              ← Notes panel
chat.js               ← Chat ops, send, regen, edit, branch, summarize
settings-handlers.js  ← Provider CRUD, command palette, save handlers
admin-handlers.js     ← Admin actions, presets, team management
  ↓
app.js                ← State, init, boot, auth, listeners (orchestrator)

File Breakdown

Unchanged (3 files, 1,482 lines)

File	Lines	Notes
api.js	575	Clean. Self-contained HTTP client.
debug.js	580	Clean. Debug logger + modal.
events.js	327	Clean. EventBus WebSocket.

From ui.js → 4 files

ui-format.js (~280 lines)

Extract from ui.js bottom section + helpers.

Formatting (L2241-2462):
  _renderMarkdown(text)
  _renderCodeBlocks(html)
  _copyCodeBlock(btn)
  _formatTokenCount(n)
  _formatCost(c)

Helpers (L2519-2583):
  esc(s)                    ← global function, used everywhere
  _formatTimestamp(ts)
  _formatRelativeTime(ts)
  _truncate(s, n)
  openSidePanel(panelId)    ← global, called from notes/search
  closeSidePanel()          ← global, HTML onclick

Side Panel Resize (L2463-2518):
  _initSidePanelResize()

Why separate: Formatting is a pure utility layer. Every other UI file depends on esc() and _renderMarkdown(). Loading first eliminates forward references.

ui-core.js (~650 lines)

The UI object definition with core rendering methods.

const UI = {
  // Sidebar (L189-216)
  toggleSidebar(), restoreSidebar(),
  toggleUserMenu(), closeUserMenu(),

  // Chat List (L217-284)
  renderChatList(),

  // Messages (L285-454)
  renderMessages(), showEmptyState(),
  _messageHTML(), _summaryHTML(), _isSummaryMessage(),
  toggleSummarizedHistory(),

  // Streaming (L455-596)
  streamResponse(),

  // Model Selector (L597-727)
  getModelValue(), setModelValue(),
  updateModelSelector(), initModelDropdown(),

  // Capability Badges (L728-774)
  getSelectedModelCaps(), updateCapabilityBadges(),

  // User / Connection (L775-811)
  updateUser(), showAdminButton(),

  // Generating State (L812-862)
  setGenerating(), showRegenerate(),

  // Toast (L863-873)
  toast(),

  // Settings Modal (L874-921) — thin dispatcher
  openSettings(), switchSettingsTab(),

  // Export (L2191-2214)
  exportMarkdown(), exportJSON(),

  // Message Actions (L2215-2240)
  (delegated action handlers)

  // Scroll (L2226-2240)
  scrollToBottom(),
};

Also includes the top-level _avatarHTML() helper (L5-24) and summary message helpers (L167-188).

ui-settings.js (~550 lines)

Extends UI with all settings modal tab content.

Object.assign(UI, {
  // Preset Form Component (L25-166) — _presetFormHTML(), etc.

  // Appearance (L922-1267)
  loadAppearanceSettings(), initAppearance(),

  // Providers (L1444-1480)
  loadProviderList(), hideProviderForm(),

  // Profile (L994-1002)
  loadProfileIntoSettings(),

  // Teams (L1003-1267)
  loadMyTeams(), loadTeamsTab(), openTeamManage(),
  showTeamPicker(), loadTeamManageMembers(),
  loadTeamManageProviders(), loadTeamManagePresets(),
  loadTeamAuditLog(), loadTeamPresetModelDropdown(),
  switchTeamTab(),

  // Usage (L1160-1267)
  loadMyUsage(), loadTeamUsage(),

  // User Model Roles (L1268-1328)
  loadUserRoles(),

  // User Models & Presets (L2118-2190)
  loadUserModels(), loadUserPresets(),

  // checkUserProvidersAllowed(), checkUserPresetsAllowed()
});

ui-admin.js (~650 lines)

Extends UI with all admin modal content.

Object.assign(UI, {
  // Admin Modal (L1481-1604)
  openTeamAdmin(), switchAdminTab(),

  // Users (L1549-1588)
  loadAdminUsers(),

  // Stats (L1589-1604)
  loadAdminStats(),

  // Roles (L1605-1658)
  loadAdminRoles(),

  // Usage + Audit (L1659-1813)
  loadAdminUsage(), loadAuditLog(),

  // Providers (L1814-1835)
  loadAdminProviders(),

  // Models (L1836-1863)
  loadAdminModels(),

  // Presets (L1864-1939)
  loadAdminPresets(),

  // Teams (L1940-2117)
  loadAdminTeams(), openTeamDetail(),
  loadTeamMembers(), loadMemberUserDropdown(),

  // Settings (L2037-2117)
  loadAdminSettings(), updateBannerPreview(),
});

From app.js → 6 files

tokens.js (~120 lines)

Already has its own Tokens namespace — clean extraction.

const Tokens = { ... };  // L36-74
function updateInputTokens()      // L78-106
function updateContextWarning()   // L108-147
function dismissContextWarning()  // L148-152

notes.js (~300 lines)

Self-contained with own state variables.

var _editingNoteId = null;
var _notesSelectMode = false;
var _selectedNoteIds = new Set();
var _notesSort = 'updated_desc';

openNotes(), loadNotesList(), _noteListItem()
_highlightHeadline()
_enterSelectMode(), _exitSelectMode()
_toggleNoteSelect(), _toggleSelectAll()
_updateSelectedCount(), _bulkDeleteSelected()
loadNoteFolders(), showNotesList()
copyNoteContent(), openNoteEditor()
_populateEditFields(), _clearEditFields()
_showNoteReadMode(), _showNoteEditMode()
_showNotePreview()
saveNote(), deleteNote()
_initNotesListeners()   ← NEW: extracted from initListeners

chat.js (~500 lines)

All conversation operations.

// Chat management
loadChats(), selectChat(), newChat(), deleteChat()

// Per-chat model persistence
_saveChatModel(), _restoreChatModel()

// Send + stream
sendMessage(), stopGeneration()

// Active path
reloadActivePath()

// Regenerate
regenerateMessage(), regenerate()

// Edit
editMessage(), submitEdit(), cancelEdit()

// Branch navigation
switchSibling()

// Summarize & Continue
summarizeAndContinue()

// Preview
clearPreview()

_initChatListeners()   ← NEW: extracted from initListeners

settings-handlers.js (~400 lines)

Settings-related handlers + command palette.

// Settings
handleSaveSettings(), loadSettings(), saveSettings()

// Avatar
updateAvatarPreview()

// Providers
handleCreateProvider(), deleteProvider()
refreshProviderModels(), editProvider()

// Admin settings save
handleSaveAdminSettings()

// User model roles
userRoleProviderChanged(), saveUserRole(), clearUserRole()

// Command Palette
_cmdCommands[], toggleCmdPalette(), openCmdPalette()
closeCmdPalette(), _handleCmdKey(), _highlightCmdItem()
_getVisibleCommands(), _renderCmdResults(), executeCmdAction()

_initSettingsListeners()  ← NEW: extracted from initListeners

admin-handlers.js (~450 lines)

Admin actions + team management.

// Admin user management
toggleUserActive(), showApproveForm(), hideApproveForm()
handleApproveUser(), resetUserPassword(), promoteUser()
createAdminUser()

// Admin roles
adminSaveRole(), adminRoleProviderChanged()

// User model preferences
toggleModelVisibility(), bulkSetVisibility()
bulkSetUserModelVisibility(), deleteUserPreset()

// Admin presets
_adminPresetForm, ensureAdminPresetForm()
editAdminPreset(), createAdminPreset()
toggleAdminPreset(), deleteAdminPreset()

// Team admin (system admin)
toggleTeamActive(), deleteTeam()
updateTeamMember(), removeTeamMember()

// Team admin (settings-side)
settingsUpdateTeamMember(), settingsRemoveTeamMember()
settingsDeleteTeamPreset(), settingsToggleTeamProvider()
settingsDeleteTeamProvider(), settingsEditTeamProvider()

_initAdminListeners()  ← NEW: extracted from initListeners

app.js (~400 lines) — the orchestrator

What remains after extraction.

// State
const App = { ... };

// Models
resolveCapabilities(), fetchModels()

// Init + Boot
init(), startApp()

// Auth flow
showSplash(), hideSplash()
handleLogin(), handleRegister(), handleLogout()
switchAuthTab(), setAuthError(), setAuthLoading()

// Modal helpers
openModal(), closeModal()
checkTabsOverflow(), updateTabArrows()

// Branding + Banners
initBranding(), initBanners()

// Listeners — thin dispatcher
function initListeners() {
    if (_listenersInit) return;
    _listenersInit = true;
    _initChatListeners();       // from chat.js
    _initSettingsListeners();   // from settings-handlers.js
    _initAdminListeners();      // from admin-handlers.js
    _initNotesListeners();      // from notes.js
    _initGlobalKeyboard();      // local: Escape, Ctrl+K, resize
    _initSidePanelResize();     // from ui-format.js
}

// Boot
document.addEventListener('DOMContentLoaded', init);

Execution Steps

1. Preparation (before any splits)

• Branch from merged v0.10.2
• Add node --check validation to a quick local script: for f in src/js/*.js; do node --check "$f" || exit 1; done
• Run all frontend tests as baseline: node --test src/js/__tests__/*.test.js

2. Extract ui-format.js

• Create src/js/ui-format.js
• Move: esc(), formatting functions, side panel resize, helpers
• Remove from ui.js
• Add <script> tag in index.html before ui.js
• Add to sw.js SHELL_FILES
• Run syntax check + tests

3. Extract ui-settings.js

• Create src/js/ui-settings.js
• Move settings/team UI methods out of UI object in ui.js
• Add Object.assign(UI, { ... }) wrapper
• Add <script> tag after ui.js
• Add to sw.js
• Run syntax check + tests

4. Extract ui-admin.js

• Create src/js/ui-admin.js
• Move admin UI methods out of UI object
• Add Object.assign(UI, { ... }) wrapper
• Add <script> tag after ui.js
• Add to sw.js
• Run syntax check + tests

5. Extract tokens.js

• Create src/js/tokens.js
• Move Tokens object + updateInputTokens + updateContextWarning + dismissContextWarning
• Remove from app.js
• Add <script> tag before app.js
• Add to sw.js
• Run syntax check + tests

6. Extract notes.js

• Create src/js/notes.js
• Move all notes state + functions
• Extract _initNotesListeners() from initListeners() — cut the notes-related event bindings into a new function, call it from initListeners()
• Add <script> tag before app.js
• Add to sw.js
• Run syntax check + tests

7. Extract chat.js

• Create src/js/chat.js
• Move chat management, send, regen, edit, branch, summarize, model persistence
• Extract _initChatListeners() from initListeners() — cut chat input, Enter-to-send, message action delegation, etc.
• Add <script> tag before app.js
• Add to sw.js
• Run syntax check + tests

8. Extract settings-handlers.js

• Create src/js/settings-handlers.js
• Move settings handlers, provider CRUD, command palette, avatar, user roles
• Extract _initSettingsListeners() from initListeners()
• Add <script> tag before app.js
• Add to sw.js
• Run syntax check + tests

9. Extract admin-handlers.js

• Create src/js/admin-handlers.js
• Move admin actions, presets, team management
• Extract _initAdminListeners() from initListeners()
• Add <script> tag before app.js
• Add to sw.js
• Run syntax check + tests

10. Final validation

• node --check all JS files
• node --test src/js/__tests__/*.test.js — all 159 tests pass
• Verify index.html script order matches dependency graph
• Verify sw.js SHELL_FILES lists all new files
• Manual smoke test: login, chat, settings, admin, notes, debug
• Grep for any remaining forward references / undefined calls
• Update ROADMAP: mark v0.10.3 complete
• Update CHANGELOG

Target State

File	Lines	Domain
api.js	575	HTTP client, auth tokens
debug.js	580	Debug logger + modal
events.js	327	EventBus WebSocket
ui-format.js	~280	Markdown, code blocks, esc(), helpers
ui-core.js	~650	UI object: rendering, model selector, streaming
ui-settings.js	~550	Settings tabs, teams, providers, user prefs
ui-admin.js	~650	Admin tabs, users, roles, usage, teams
tokens.js	~120	Context tracking, token estimation
notes.js	~300	Notes panel, editor, multi-select
chat.js	~500	Chat ops, send, regen, edit, branch, summarize
settings-handlers.js	~400	Settings save, provider CRUD, command palette
admin-handlers.js	~450	Admin actions, presets, team management
app.js	~400	State, init, boot, auth, listener dispatch
Total	~5,782	13 files (was 5)

Line count drops slightly due to removed duplicate section headers and consolidated comments. Average file: ~445 lines. Largest: ~650.

Risk Mitigation

Forward references: Function declarations are hoisted within a <script>, but not across scripts. All functions called by initListeners() must be defined in scripts loaded before app.js. The load order above ensures this.

UI object extension: Object.assign(UI, { ... }) in ui-settings.js and ui-admin.js means UI must be defined first (in ui-core.js). The load order handles this.

Regression testing: Each extraction step ends with syntax check + test run. If anything breaks, it's isolated to the last extraction.

Rollback: Each step is a single commit. Revert any step independently.

What This Does NOT Change

• No ES modules, no import/export, no bundler
• No function renaming (HTML onclick handlers untouched)
• No new dependencies
• No architectural changes to backend
• No feature additions
• The UI object is still a single global — just defined across files
• All tests continue to work unchanged