# Frontend JS Dependency Audit

**Version:** v0.28.3 cs2
**Date:** 2026-03-13
**Purpose:** Map every global, cross-file dependency, and init sequence
to prepare for module extraction.

---

## Summary

| Metric | Value |
|--------|-------|
| JS files | 47 |
| Total lines | 25,056 |
| Total bytes | 1,103,572 (~1.1 MB) |
| Top-level globals (original) | 431 |
| IIFE-wrapped files | 47 (all) |
| Explicit `window.*` exports | ~215 |
| Functions privatized | ~168 |
| Implicit globals remaining | 0 |
| Vendor libs | 3 (marked.min.js, purify.min.js, codemirror.bundle.js) |
| Inline `onclick` handlers (templates) | ~50 unique functions |
| Dynamic `onclick` in JS (innerHTML) | 143 total occurrences |

---

## Architecture: IIFE Modules (Post-Decomposition)

No module system (no ES modules, no bundler, no AMD). Every file is a
`<script>` tag loaded in dependency order. All 47 files are now wrapped
in IIFEs with explicit `window.*` exports:

```js
(function() {
'use strict';
// ... all code ...
window.MyGlobal = MyGlobal;
})();
```

**Phase 1 complete.** Zero implicit globals remain. ~168 functions
privatized. The next phase is onclick → addEventListener migration
(143 dynamic handlers in JS innerHTML + ~50 in Go templates), which
is the prerequisite for ES module conversion.

### IIFE Files

| File | Clean? | Leaks |
|------|--------|-------|
| `admin-handlers.js` | ✅ | None (all via inline onclick from globals) |
| `admin-scaffold.js` | ✅ | None |
| `editor-surface.js` | ✅ | None |
| `knowledge-ui.js` | ✅ | None |
| `pages-splash.js` | ✅ | None |
| `task-admin.js` | ❌ | `window._loadAdminTasks` |
| `task-settings.js` | ❌ | `window._createFromTemplate`, `window._loadSettingsTasks` |
| `task-sidebar.js` | ❌ | `window.TaskSidebar` |
| `tools-toggle.js` | ✅ | None |
| `workflow-admin.js` | ❌ | 5 functions (`_loadAdminWorkflows`, `_wfCreate`, `_wfOpen`, `_wfEditStage`, `_wfDeleteStage`) |
| `workflow-api.js` | ✅ | None (registers on App) |
| `workflow-queue.js` | ❌ | `window.WorkflowQueue` |

---

## Script Load Order

### base.html (shared — every surface)

```
 1. app-state.js        → const App = { ... }
 2. api.js              → const API = { ... }
 3. (inline)            → window.__BASE__, auth bootstrap
 4. events.js           → const Events = { ... }
 5. ui-primitives.js    → const UI = { ... }
 6. vendor/marked.min.js
 7. vendor/purify.min.js
 8. ui-format.js        → formatMessage(), toggleCodeCollapse(), etc.
 9. ui-core.js          → renderChatList(), renderMessages(), etc.
10. pages.js            → const Pages = { ... }
11. user-menu.js        → const UserMenu = { ... }
12. model-selector.js   → const ModelSelector = { ... }
13. file-tree.js        → const FileTree = { ... }
14. code-editor.js      → const CodeEditor = { ... }
15. note-editor.js      → const NoteEditor = { ... }
16. drag-resize.js      → const DragResize = { ... }
17. pane-container.js   → const PaneContainer = { ... }
18. (inline)            → Theme.init()
19. surfaces/{surface}/js/main.js  → surface CSS + scaffold
```

### chat.html (25 additional scripts + 1 vendor)

```
    vendor/codemirror/codemirror.bundle.js → window.CM (optional, onerror fallback)
20. extensions.js       → const Extensions = { ... }
21. panels.js           → const PanelRegistry = { ... }
22. ui-settings.js      → settings rendering (bare globals)
23. ui-admin.js         → admin rendering (bare globals)
24. tokens.js           → token counting (bare globals)
25. notes.js            → notes UI (bare globals)
26. note-graph.js       → graph visualization (bare globals)
27. files.js            → file upload/management (bare globals)
28. tools-toggle.js     → tool enable/disable (IIFE)
29. knowledge-ui.js     → KB picker (IIFE)
30. memory-ui.js        → memory panel (bare globals)
31. persona-kb.js       → persona KB bindings (bare globals)
32. projects-ui.js      → project management (bare globals, 78 top-level decls)
33. channel-models.js   → const ChannelModels = { ... }
34. notification-prefs.js → notification preferences (bare globals)
35. notifications.js    → const Notifications = { ... }
36. chat.js             → const ChatInput = { ... } + 29 top-level functions
37. settings-handlers.js → settings form handlers (bare globals, 24 decls)
38. admin-handlers.js   → admin form handlers (IIFE, 40 internal functions)
39. workflow-api.js     → workflow REST helpers (IIFE)
40. workflow-admin.js   → workflow admin UI (IIFE, 5 window.* leaks)
41. workflow-queue.js   → workflow queue sidebar (IIFE, window.WorkflowQueue)
42. task-sidebar.js     → task sidebar (IIFE, window.TaskSidebar)
43. app.js              → init(), startApp(), event listeners
44. debug.js            → debug console (bare globals)
45. repl.js             → REPL (bare globals)
```

### admin.html (14 additional)

Loads: ui-settings, ui-admin, admin-handlers, settings-handlers,
knowledge-ui, persona-kb, memory-ui, notifications, files,
admin-scaffold, workflow-api, workflow-admin, task-admin,
admin-surfaces.

### notes.html (14 additional)

Loads: chat, files, channel-models, tokens, extensions, notes,
note-graph, knowledge-ui, persona-kb, memory-ui, notifications,
panels, projects-ui, app.

### settings.html (9 additional)

Loads: ui-settings, settings-handlers, task-settings, knowledge-ui,
persona-kb, memory-ui, notifications, notification-prefs,
channel-models.

### editor.html (4 additional + 1 vendor)

Loads: vendor/codemirror, chat-pane, editor-surface, app.
Lightest surface — fewest dependencies.

---

## Core Globals (Dependency Roots)

These are referenced by 10+ other files. They form the "root set" that
must be extracted first.

| Global | Defined in | Referenced by | Role |
|--------|-----------|---------------|------|
| `App` | app-state.js | 20 files | State container (chats, models, user, settings, presence) |
| `API` | api.js | 36 files | REST client (all HTTP calls) |
| `UI` | ui-core.js | 32 files | DOM helpers (toast, confirm, modal, sidebar, theme) |
| `Events` | events.js | 9 files | Pub/sub event bus (WebSocket bridge) |

### Secondary Globals (3–9 references)

| Global | Defined in | Referenced by | Role |
|--------|-----------|---------------|------|
| `Pages` | pages.js | Templates + 3 files | Page-level actions (login, admin forms) |
| `ChannelModels` | channel-models.js | 4 files | Model roster per channel |
| `ChatInput` | chat.js | 3 files | Message input state + send |
| `Notifications` | notifications.js | Templates + 2 files | Bell dropdown, badge count |
| `ChatPane` | chat-pane.js | 3 files | Embedded chat component (editor) |
| `CM` | vendor/codemirror.bundle.js | 5 files | CodeMirror 6 editor (optional, graceful fallback) |
| `PanelRegistry` | panels.js | Templates + 1 file | Side panel management |

### Leaf Globals (1–2 references, mostly self-contained)

ModelSelector, FileTree, CodeEditor, NoteEditor, DragResize,
PaneContainer, UserMenu, WorkflowQueue, TaskSidebar, Extensions.

---

## Inline Handler Problem

143 `onclick=` patterns in JS files (innerHTML-generated HTML) plus
~50 in Go templates. These reference bare globals that **must remain
on `window`** or the handlers break. This is the primary blocker for
ES module migration.

**Top offenders (dynamic onclick in JS):**

| File | Count | Examples |
|------|-------|---------|
| ui-admin.js | 28 | Admin list row actions |
| projects-ui.js | 26 | Project CRUD, channel/KB/note associations |
| ui-core.js | 25 | Chat list, sidebar, context menus |
| ui-format.js | 10 | Code block copy/preview/download |
| ui-settings.js | 8 | Settings form toggles |
| notifications.js | 8 | Notification row actions |

**Template onclick (must remain global):**

UI.toggleSidebar, UI.toggleSidebarSection, UI.switchTeamTab,
Notifications.toggleDropdown, PanelRegistry.toggle, PanelRegistry.closeAll,
Pages.doLogin, Pages.saveSettings, Pages.saveProvider, Pages.saveTeam,
handleLogin, handleRegister, switchAuthTab, newChat, newFolder,
newChannelOrDM, sendMessage, createProject, closeLightbox,
toggleSidePanelFullscreen, plus ~15 more Pages.* admin form handlers.

---

## Cross-File Call Graph (Simplified)

```
app-state.js (App)
  ↑ read/write by 20 files
  │
api.js (API)
  ↑ called by 36 files
  │
events.js (Events)
  ↑ subscribed by 9 files
  ├── chat.js (typing, message.created, presence)
  ├── notifications.js (notification.new/read)
  ├── extensions.js (tool.call/result)
  ├── repl.js (debug events)
  └── app.js (role.fallback banner)
  │
ui-primitives.js (UI)
  ↑ called by 32 files
  ├── toast(), confirm(), modal()
  ├── toggleSidebar(), toggleSidebarSection()
  └── theme, kbd shortcuts
  │
ui-format.js (formatMessage, etc.)
  ↑ called by ui-core.js, chat.js, notes.js, projects-ui.js
  ├── depends on: marked.min.js, purify.min.js
  │
ui-core.js (renderChatList, renderMessages, etc.)
  ↑ called by chat.js, app.js, projects-ui.js
  ├── depends on: App, API, UI, ui-format
  │
chat.js (ChatInput, sendMessage, selectChat, loadChats)
  ↑ called by app.js, templates
  ├── depends on: App, API, Events, UI, ui-core, ui-format,
  │               ChannelModels, tokens, files
  │
app.js (init, startApp)
  ↑ entry point — called by inline <script> in base.html
  ├── depends on: everything above + surface-specific modules
```

---

## Decomposition Strategy

### Phase 1: Extract Core Four (no bundler required)

Move `App`, `API`, `Events`, `UI` to a pattern where they're defined
as proper singletons with explicit exports. No ES modules yet — just
clean up the global registration so each file has a single `window.X`
export with a documented interface.

**Why no bundler yet:** 143 dynamic onclick handlers + 50 template
onclick handlers require globals on `window`. A bundler would need
either (a) a global shim layer or (b) converting all handlers to
`addEventListener`. Option (b) is the right answer but it's ~200
call sites across 16 files + 10 templates — too much churn for one
changeset.

### Phase 2: onclick → addEventListener migration

Convert dynamic HTML generation from:
```js
`<button onclick="deleteItem('${id}')">Delete</button>`
```
to:
```js
const btn = document.createElement('button');
btn.textContent = 'Delete';
btn.addEventListener('click', () => deleteItem(id));
```

This eliminates the global requirement. Target the top 6 files first
(ui-admin, projects-ui, ui-core, ui-format, ui-settings, notifications)
which account for 105 of 143 occurrences.

Template onclick handlers stay — Go templates can't do addEventListener.
These become the only remaining reason for `window.*` exports.

### Phase 3: ES Module conversion

Once onclick handlers are gone from JS, files can become ES modules:
```html
<script type="module" src="js/app.js"></script>
```

Import graph follows the dependency order already established by
`<script>` tag ordering. Vendor libs (marked, purify, codemirror) stay
as classic scripts since they self-register on `window`.

### Phase 4: Template handler shim

Create a thin `window.handlers = {}` object that ES modules register
into. Template onclick handlers call `handlers.doLogin()` etc. This
is the final bridge — once templates move to client-side rendering
(extension surface SDK), this shim disappears.

---

## Files by Decomposition Priority

### Tier 1 — Core (extract first, most dependents)

| File | Lines | Globals | Dependents | Notes |
|------|-------|---------|------------|-------|
| app-state.js | 96 | 3 | 20 | Clean singleton, easy extract |
| api.js | 1,159 | 3 | 36 | Large but self-contained |
| events.js | 261 | 1 | 9 | Clean singleton |
| ui-primitives.js | 1,316 | 18 | 32 | Large, many utility functions |

### Tier 2 — Rendering (depends on Tier 1)

| File | Lines | Globals | Dependents | Notes |
|------|-------|---------|------------|-------|
| ui-format.js | 573 | 20 | 4 | Markdown + code blocks |
| ui-core.js | 1,644 | 6 | 3 | Chat list, messages, sidebar |
| pages.js | 382 | 8 | Templates | Page-level orchestration |

### Tier 3 — Feature modules (leaf nodes, mostly self-contained)

| File | Lines | Notes |
|------|-------|-------|
| channel-models.js | 425 | Clean object literal |
| chat-pane.js | 143 | Clean object literal |
| notifications.js | 390 | Clean singleton, IIFE candidate |
| model-selector.js | 191 | Clean object literal |
| file-tree.js | 295 | Clean object literal |
| tokens.js | 143 | 4 globals, minimal deps |

### Tier 4 — Heavy pages (most onclick handlers, refactor last)

| File | Lines | onclick | Notes |
|------|-------|---------|-------|
| ui-admin.js | 1,922 | 28 | Admin rendering, deeply coupled |
| projects-ui.js | 1,794 | 26 | 78 top-level globals (!), biggest mess |
| ui-core.js | 1,644 | 25 | Already in Tier 2, but onclick heavy |
| ui-settings.js | 1,011 | 8 | Settings rendering |
| settings-handlers.js | 1,064 | 0 | But 24 globals called by ui-settings |
| admin-handlers.js | 952 | 2 | IIFE but 40 internal functions |