Cursor rule

1---
2description: crit — frontend architecture
3alwaysApply: false
4---
5 
6# Frontend Architecture
7 
8## Two-Paradigm Page Fork
9 
10`index.html` serves both modes from a single HTML shell. A script block at load time checks `window.location.pathname`:
11- `/live` → live mode (iframe-based pin review)
12- Everything else → code-review mode (file tree + diff/document views)
13 
14Each mode dynamically loads its own script set. They share: theme pill, settings overlay, and extracted modules.
15 
16## Module Pattern
17 
18All custom JS uses the IIFE + dual-export pattern:
19 
20```javascript
21(function () {
22  'use strict';
23  // ... implementation ...
24  var api = { publicFn1, publicFn2 };
25  if (typeof window !== 'undefined') {
26    window.crit = window.crit || {};
27    window.crit.<namespace> = api;
28  }
29  if (typeof module === 'object' && module.exports) {
30    module.exports = api;
31  }
32})();
33```
34 
35- Runtime: accessed via `window.crit.<namespace>`
36- Tests: required via `module.exports` (Node.js `--test`)
37- Never use ES modules (`import`/`export`) — no build step exists
38 
39## Shared Modules (used by both modes)
40 
41| Module | Namespace | Purpose |
42|--------|-----------|---------|
43| `crit-shared.js` | `window.crit.shared` | Cookie helpers, theme, tip rotation, image upload |
44| `crit-renderer.js` | `window.crit.renderer` | ContentRenderer registry (register/deregister/current) |
45| `crit-sse.js` | `window.crit.sse` | SSE client factory (createSSE) |
46| `crit-draft.js` | `window.crit.draft` | Autosave drafts to localStorage |
47| `crit-comment-templates.js` | `window.crit.commentTemplates` | Template bar + saved-snippet CRUD |
48| `crit-comment-form.js` | `window.crit.commentForm` | Shared comment form creation |
49| `crit-comment-card.js` | `window.crit.commentCard` | Comment card rendering + reply threading |
50| `crit-comment-card-helpers.js` | `window.crit.commentCardHelpers` | Author colors, timestamps, markdown rendering |
51| `crit-settings-overlay.js` | `window.crit.settingsOverlay` | Settings dialog lifecycle |
52| `crit-settings-panes.js` | `window.crit.settingsPanes` | Settings tab content |
53 
54## Code-Review Modules (used only by code-review mode)
55 
56| Module | Namespace | Purpose |
57|--------|-----------|---------|
58| `crit-icons.js` | `window.crit.icons` | SVG icon constants (ICON_CHEVRON, ICON_EDIT, etc.) |
59| `crit-line-blocks.js` | `window.crit.lineBlocks` | buildLineBlocks, splitHighlightedCode, buildCodeLineBlocks |
60| `crit-diff-renderer.js` | `window.crit.diffRenderer` | Word-level diff computation (lineSimilarity, wordDiff, etc.) |
61 
62## ContentRenderer Interface
63 
64Modes register a renderer that the shared chrome (comment cards, settings) can call without knowing the active mode:
65 
66```javascript
67window.crit.renderer.register({
68  scrollToAnchor(anchor),     // scroll viewport to a comment's target
69  highlightAnchor(anchor),    // visually highlight the target
70  clearHighlight(),           // remove highlight
71  onAnnotationIntent(cb),     // subscribe to "user wants to comment here"
72  getMode(),                  // "code-review" | "live"
73  getAnchorType(),            // "line" | "dom"
74});
75```
76 
77Code-review registers its renderer in `app.js`. Live-mode registers in `live-mode.js`.
78 
79## Script Loading
80 
81No bundler. Scripts are loaded dynamically with `async=false` (preserves execution order while loading in parallel). A Promise-based boot gate waits for all dependencies before loading the mode's main entry point:
82 
831. Early scripts (shared helpers) load first
842. `liveDeps` array lists all sub-modules
853. `Promise.all(bootGate)` waits for all load events
864. Only then loads `live-mode.js` (or `app.js` for code-review)
87 
88When adding a new shared module:
89- Add to `liveDeps` array in `index.html` if live-mode needs it
90- Add to the code-review script chain if code-review needs it
91- Both modes must load shared modules BEFORE their main entry point
92 
93## Live-Mode Sub-Modules
94 
95Live-mode splits into focused files under `window.crit.live.<name>`:
96 
97| File | Namespace | Concern |
98|------|-----------|---------|
99| `live-mode.dispatch.js` | `.live.dispatch` | Message dispatch table |
100| `live-mode.toggle.js` | `.live.toggle` | Pin/Browse mode toggle |
101| `live-mode.composer.js` | `.live.composer` | Comment composition UI |
102| `live-mode.panel.js` | `.live.panel` | Side panel lifecycle |
103| `live-mode.panel-render.js` | `.live.panelRender` | Panel card rendering |
104| `live-mode.sse.js` | `.live.sse` | Live-mode SSE handlers |
105| `live-mode.size.js` | `.live.size` | Panel resize logic |
106| `live-mode.queue.js` | `.live.queue` | Batched pin push queue |
107| `live-mode.origin.js` | `.live.origin` | Origin/proxy URL resolution |
108| `live-mode.row.js` | `.live.row` | Per-route section rendering |
109 
110## Adding a New Module
111 
1121. Create the IIFE file with the dual-export pattern
1132. Add it to `liveDeps` or code-review script chain in `index.html`
1143. Create a matching `web/__tests__/<name>.test.js` using Node's `--test`
1154. Add the test file to `Makefile` `e2e-live-utils` target (if live-mode)
1165. Document dependencies in a header comment (which `window.crit.*` namespaces it reads)
117