# TypeScript Conversion Plan for Bookhoard

## Executive Summary

Convert **~2,800 lines of inline JavaScript** across 14 template files into organized TypeScript modules while **preserving the existing Hybrid SSR architecture**. The web UI will remain a client of the JSON API, alongside Kobo, KOReader, and future plugins.

**Core Strategy:** Server-Side Rendering (SSR) for initial page loads + TypeScript for CRUD operations via existing JSON API.

---

## Current Architecture Analysis

### Already Converted to TypeScript ✅
| Source | Output | Lines | Purpose |
|--------|--------|-------|---------|
| `web/src/toast.ts` | `toast.js` | 226 | Toast notifications, HTMX/fetch interceptors |
| `web/src/theme.ts` | `theme.js` | 130 | Theme management, smooth scrolling |
| `web/src/header.ts` | `header.js` | 114 | Header dropdowns, theme/user menus |
| `web/src/device-management.ts` | `device-management.js` | 102 | Device token copy/regeneration |

### Remaining Standalone JavaScript ❌
| File | Lines | Purpose |
|------|-------|---------|
| `web/static/search.js` | 275 | Header search with keyboard navigation, debouncing |

### Inline JavaScript in Templates (~2,800 lines)
| Template | Script Lines | Primary Functions |
|----------|--------------|-------------------|
| `dashboard.templ` | ~456 | Statistics, recent activity |
| `docs.templ` | ~392 | Documentation search, sidebar toggle |
| `devices.templ` | ~386 | Token regeneration, sync URL display |
| `collections.templ` | ~362 | Bulk operations, filtering |
| `unlinked_books.templ` | ~312 | Book matching, linking, bulk operations |
| `collection_rules.templ` | ~239 | Rule CRUD operations, testing |
| `admin_library.templ` | ~229 | Admin library scan |
| `bookshelf.templ` | ~200 | Book viewing, pagination |
| `api_explorer.templ` | ~103 | API testing, cURL generation |
| `admin.templ` | ~29 | Admin dashboard actions |
| `login.templ` | ~29 | Login theme selection |
| `index.templ` | ~24 | Landing page theme preview |
| `admin_profile.templ` | ~11 | Admin profile management |
| `progress.templ` | ~6 | Reading progress |
| `conflicts.templ` | 0 | **No inline JS - uses onclick handlers only** |
| `queue.templ` | 0 | **No inline JS - uses onclick handlers only** |
| `analytics.templ` | 0 | **No inline JS - uses onclick handlers only** |

**Total: ~2,800 lines of inline JavaScript to convert**

**Note:** `conflicts.templ`, `queue.templ`, and `analytics.templ` have NO `<script>` blocks. They use simple `onclick="window.functionName()"` handlers that call functions defined elsewhere. These templates only need TypeScript modules for their handler functions, no template cleanup required.

---

## Architecture: Hybrid SSR + TypeScript CRUD

### Current Pattern (Already Working)

```
┌─────────────────────────────────────────────────────────────┐
│              User visits /collections                        │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  1. Go handler: GET /collections                             │
│  2. Fetches data from CollectionService                      │
│  3. Renders templates.Collection(user, collections)          │
│  4. Returns complete HTML page with data                     │
└─────────────────────────────────────────────────────────────┘
                           ↓
              [Page displays instantly with data]
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  5. User clicks "Add Rule" button                            │
│  6. TypeScript: fetch POST /api/collections/{id}/rules       │
│  7. Server returns JSON                                      │
│  8. TypeScript updates DOM                                   │
└─────────────────────────────────────────────────────────────┘
```

### What This Preserves

✅ **Fast initial page loads** - SSR with data
✅ **Progressive enhancement** - Works without JavaScript
✅ **Single API** - All clients use `/api/*` endpoints
✅ **Service layer as source of truth** - All handlers use same services
✅ **No handler duplication** - No new HTML endpoints needed
✅ **Plugin ecosystem ready** - Plugins use JSON API

---

## Proposed TypeScript Structure

**Continuing with existing `web/src/` pattern:**

```
web/src/
├── types/
│   └── api.d.ts          # NEW: Centralized API type definitions (.d.ts = no JS output)
├── toast.ts              # ✅ Already converted
├── theme.ts              # ✅ Already converted
├── header.ts             # ✅ Already converted
├── device-management.ts  # ✅ Already converted
├── search.ts             # NEW: Convert from search.js
├── storage.ts            # NEW: localStorage wrapper with types
├── dom.ts                # NEW: DOM utilities (escapeHtml, querySelector)
├── api.ts                # NEW: API client functions with auth
├── events.ts             # NEW: Event delegation helpers (likely needed)
├── collections.ts        # NEW: Convert from inline JS (rules, bulk)
├── linking.ts            # NEW: Convert from inline JS (matcher, manual/bulk link)
├── bookshelf.ts          # NEW: Convert from inline JS (display, pagination)
├── api-explorer.ts       # NEW: Convert from inline JS (request, response, curl)
├── admin.ts              # NEW: Convert from inline JS (scan, stats)
├── analytics.ts          # NEW: Analytics data loading, Chart.js integration
├── queue.ts              # NEW: Queue management, filtering
├── conflicts.ts          # NEW: Conflict resolution, bulk operations
└── docs.ts               # NEW: Documentation search, sidebar toggle
```

**All TypeScript files compile to flat `web/static/` directory:**
- Source: `web/src/*.ts` → Output: `web/static/*.js`
- No subdirectories in output (TypeScript `module: "none"` = browser globals)
- All functions exported to `window` object for HTML attribute access

---

## Type Sharing Strategy

### Overview: Manual Type Definitions with Compile-Time Checking

**No code generation.** We manually maintain TypeScript types that match Go handler JSON responses.

**Why manual instead of code generation?**
- Go's `pgtype.Text`, `pgtype.Timestamp`, `pgtype.Numeric` don't map cleanly to TypeScript generators
- We only care about the JSON contract, not Go storage types
- API contracts change infrequently in stable applications
- Manual verification via Bruno tests is sufficient
- No additional tooling or build complexity

**How it works:**
- All API types defined in `web/src/types/api.d.ts` (.d.ts files don't generate JS output)
- Import types using `import type { ... }` for compile-time checking
- TypeScript erases type imports (no runtime dependencies)
- When adding new API fields, update the type definition
- Reference Go handler files in comments for cross-checking
- Bruno tests catch contract mismatches

**Template-Handler Type Sharing:**
- Go templates import handlers directly: `import "bookhoard/internal/handlers"`
- Templates use handler types for SSR data: `handlers.CollectionData`, `handlers.BookInfo`
- TypeScript interfaces must match the SAME JSON responses that templates receive
- Example: If template uses `handlers.BookInfo`, TypeScript uses matching `BookInfo` interface
- This ensures SSR and TypeScript code work with identical data structures

### Principle: Define TypeScript Interfaces That Match Go Handler JSON Responses

**❌ DON'T DO THIS:**
```typescript
// Using PascalCase when API returns snake_case
interface MediaItem {
    ID: string;        // Wrong: JSON has "id"
    Title: string;     // Wrong: JSON has "title"
    LibraryID: string; // Wrong: JSON has "library_id"
}
```

**✅ DO THIS:**
```typescript
// Define TypeScript interfaces that MATCH Go JSON tag names exactly
// These types are returned by /api/* endpoints as JSON

// Matches database.SearchMediaItemsRow JSON response from /api/media-items/search
// Source: internal/database/queries.sql.go (SearchMediaItemsRow struct)
// Note: internal/handlers/search.go has an unused MediaItemSummary struct - ignore it
interface MediaItemSummary {
    id: string;
    title: string;
    author?: string;                    // Single author string, not array
    library_id: string;
    library_type_name: 'ebooks' | 'comics' | 'manga';
    library_name: string;
    cover_image_path?: string;
}

// Matches handlers.CollectionData JSON response
interface CollectionData {
    id: string;
    name: string;
    description: string;
    color: string;
    icon: string;
}
```

**Why:**
- Go structs use PascalCase for field names but JSON tags use snake_case
- API responses are JSON with snake_case field names
- TypeScript interfaces must match the JSON output, not Go struct names
- Easy to verify: check the `json:"..."` tag in Go handler code
- Example: `type BookInfo struct { MediaItemID string \`json:"media_item_id"\` }` → TypeScript uses `media_item_id`

**Important:** Some handlers return database rows directly (e.g., `SearchMediaItemsRow`), not handler-defined structs. Always check what the endpoint actually returns, not just what handler structs are defined.

### Example: Type Definition File

```typescript
// web/src/types/api.d.ts
// ============================================
// API Type Definitions
// ============================================
// These types match the JSON responses from /api/* endpoints.
// Source of truth: Check what the endpoint ACTUALLY returns:
// 1. Database layer: internal/database/queries.sql.go (SearchMediaItemsRow, etc.)
// 2. Handler structs: internal/handlers/*.go (check json:"..." tags)
// 3. Test by calling endpoint and inspecting JSON response
//
// When API contracts change:
// 1. Find the endpoint function in internal/handlers/*.go
// 2. Check what it returns (database row or struct)
// 3. Check the JSON tags: `json:"field_name"`
// 4. Map pgtype fields to TypeScript types:
//    - pgtype.Text → string | undefined
//    - pgtype.UUID → string
//    - pgtype.Timestamp → string (ISO datetime)
//    - pgtype.Numeric → number or string (for precision)
// 5. Update the interface below with snake_case field names
// 6. Run Bruno tests to verify
// ============================================

// Matches database.SearchMediaItemsRow from /api/media-items/search
// Source: internal/database/queries.sql.go:SearchMediaItemsRow
// Endpoint: internal/handlers/media.go:SearchMediaItems()
// Note: internal/handlers/search.go has an unused MediaItemSummary - ignore it
// Used in: search.ts
export interface MediaItemSummary {
    id: string;
    title: string;
    author?: string;                    // Single author string from database
    library_id: string;
    library_type_name: 'ebooks' | 'comics' | 'manga';
    library_name: string;
    cover_image_path?: string;
}

// Matches handlers.CollectionData JSON response
// Used in: collections.ts
export interface CollectionData {
    id: string;
    name: string;
    description: string;
    color: string;
    icon: string;
    created_at: string;
}

// Matches handlers.BookInfo JSON response (internal/handlers/collections.go:66-71)
// JSON tags: media_item_id, title, author, cover_image_path
// Used in: collections.templ (server-rendered), collections.ts
export interface BookInfo {
    media_item_id: string;
    title: string;
    author: string;
    cover_image_path: string;
}

// Matches handlers.UnlinkedBookData JSON response
// Used in: unlinked_books.ts, unlinked_books.templ
export interface UnlinkedBookData {
    progress_id: string;
    device_id: string;
    device_name: string;
    device_type: 'koreader' | 'kobo' | 'web';
    title_from_device: string;
    file_path: string;
    sha256: string;
    last_sync_time: string;
    confidence_score: number;
    potential_matches: PotentialMatchData[];
}

export interface PotentialMatchData {
    media_item_id: string;
    title: string;
    author: string;
    confidence: number;
    cover_image_path?: string;
}

// Matches collection rule objects
// Used in: collection_rules.ts
export interface CollectionRule {
    id: string;
    field: 'genre' | 'series' | 'author' | 'language' | 'publisher' | 'copyright_year' | 'tags';
    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'less_than';
    value: string;
    enabled: boolean;
    priority: number;
}

// Matches API test rule responses
// Used in: collection_rules.ts (test results)
export interface TestRuleMatch {
    title: string;
    author: string;
    cover_image_path?: string;
}

// Matches handlers.SearchResponse (internal/handlers/search.go)
export interface SearchResponse {
    results: SearchBookResponse[];
    total: number;
}

export interface SearchBookResponse {
    id: string;
    title: string;
    authors: SearchAuthor[];
}

export interface SearchAuthor {
    first_name: string;
    last_name: string;
}

// Matches AuthResponse (internal/handlers/auth.go:59-65)
export interface AuthResponse {
    access_token: string;
    refresh_token?: string;
    token_type: string;
    expires_in: number;
    user: UserProfile;
}

export interface UserProfile {
    id: string;
    email: string;
    username: string;
    first_name?: string;
    last_name?: string;
    role: string;
    theme?: string;
}

// Matches handlers.ReadingStatsResponse (internal/handlers/analytics.go:26-35)
// Used in: analytics.ts
export interface ReadingStatsResponse {
    total_books_read: number;
    total_pages_read: number;
    total_reading_time_minutes: number;
    average_session_time_minutes: number;
    longest_session_minutes: number;
    most_active_day_of_week: string;
    completion_rate: number;
    daily_reading_minutes: DailyReading[];
}

export interface DailyReading {
    date: string;
    minutes: number;
    pages: number;
}

// Matches handlers.DeviceUsageResponse (internal/handlers/analytics.go:43-45)
// Note: Response is wrapped: { devices: DeviceUsage[] }
// Used in: analytics.ts
export interface DeviceUsageResponse {
    devices: DeviceUsage[];
}

export interface DeviceUsage {
    device_id: string;
    device_name: string;
    device_type: string;
    sync_count: number;
    last_sync: string;
    total_time_seconds: number;
    total_time_minutes: number;
}

// Matches handlers.PopularBooksResponse (internal/handlers/analytics.go:57-59)
// Note: Response is wrapped: { books: PopularBook[] }
// Used in: analytics.ts
export interface PopularBooksResponse {
    books: PopularBook[];
}

export interface PopularBook {
    media_item_id: string;
    title: string;
    author: string;
    read_count: number;
    avg_completion: number;
    last_read: string;
}

// Matches handlers.QueueItemResponse (internal/handlers/queue.go:35-51)
// Used in: queue.ts
export interface QueueItemResponse {
    id: string;
    device_id: string;
    device_name: string;
    device_type: string;
    media_item_id?: string;
    media_title?: string;
    user_email: string;
    sync_type: string;
    priority: number;
    attempts: number;
    max_attempts: number;
    status: string;
    error_message?: string;
    created_at: string;
    processed_at?: string;
}

// Matches handlers.QueueStatsResponse (internal/handlers/queue.go:27-33)
// Used in: queue.ts
export interface QueueStatsResponse {
    pending_count: number;
    processing_count: number;
    failed_count: number;
    completed_count: number;
    total_count: number;
}

// Matches handlers.ConflictDetailResponse (internal/handlers/conflicts.go:42-53)
// Used in: conflicts.ts
export interface ConflictDetailResponse {
    id: string;
    media_item_id: string;
    media_item_title: string;
    conflict_type: string;
    conflict_data: Record<string, ConflictSourceData>;
    resolution_status: string;
    resolution_data?: Record<string, unknown>;
    resolved_by?: string;
    resolved_at?: string;
    created_at: string;
}

// Matches handlers.ConflictSourceData (internal/handlers/conflicts.go:36-40)
export interface ConflictSourceData {
    source: string;
    timestamp: string;
    data: Record<string, unknown>;
}

// Matches handlers.ConflictListResponse (internal/handlers/conflicts.go:55-59)
// Used in: conflicts.ts
export interface ConflictListResponse {
    conflicts: ConflictDetailResponse[];
    total: number;
    unresolved: number;
}

// Matches handlers.ConflictResolveResponse (internal/handlers/conflicts.go:61-65)
// Used in: conflicts.ts
export interface ConflictResolveResponse {
    conflict_resolved: boolean;
    applied_to: Record<string, boolean>;
    devices_synced: string[];
}

// Matches handlers.BulkResolveResponse (internal/handlers/conflicts.go:424-429)
// Used in: conflicts.ts
export interface BulkResolveResponse {
    results: ConflictResult[];
    total: number;
    success: number;
    failed: number;
}

// Matches handlers.ConflictResult (internal/handlers/conflicts.go:431-436)
export interface ConflictResult {
    conflict_id: string;
    status: string;
    error?: string;
    winner?: string;
}
```

### Importing Types (No ES Modules Required)

With `module: "none"` in tsconfig.json, use `import type` for compile-time checking:

```typescript
// web/src/collections.ts
import type { CollectionData, MediaItemSummary } from './types/api';

function renderCollection(collection: CollectionData): HTMLElement {
    const div = document.createElement('div');
    div.textContent = collection.name;
    return div;
}

// Export to window for HTML access
(window as any).renderCollection = renderCollection;
```

**What happens at compile time:**
- TypeScript verifies types match the interfaces
- The `import type` statement is **erased** (no runtime import)
- Output JavaScript has no `require()` or `import` statements
- `web/src/types/api.d.ts` produces no `.js` file (.d.ts = type-only)

**Output (`web/static/collections.js`):**
```javascript
function renderCollection(collection) {
    var div = document.createElement('div');
    div.textContent = collection.name;
    return div;
}

window.renderCollection = renderCollection;
```

---

## Conversion Phases

### Phase 1: Complete Standalone File Conversion
**Priority: High | Effort: 1 day | Dependencies: None**

**Tasks:**
1. Convert `web/static/search.js` → `web/src/search.ts`
2. Add proper types for search results (use `MediaItemSummary` with snake_case fields)
3. Extract keyboard navigation logic into pure functions
4. Update templates to use new TypeScript module

**Important:** Use snake_case field names matching JSON responses:
- `item.id` (not `item.ID`)
- `item.title` (not `item.Title`)
- `item.author` (single string, not `item.Authors` array)
- `item.library_id` (not `item.LibraryID`)
- `item.library_type_name` (not `item.LibraryTypeName`)

**Note:** Ignore the `MediaItemSummary` struct in `internal/handlers/search.go` (it's unused and incorrect). The actual API returns `SearchMediaItemsRow` from the database layer, which has the correct fields.

**Build Verification:**
- Run `npm run build:ts` to verify compilation
- Confirm `web/static/search.js` is generated
- Test search functionality in browser
- Verify keyboard navigation (up/down arrows, Enter, Escape)

**Deliverable:** All standalone JavaScript converted to TypeScript

**Files:**
- Create: `web/src/search.ts`
- Delete: `web/static/search.js`
- Update: Templates referencing search functions (header.templ)

---

### Phase 2: Core Utilities (Shared Infrastructure)
**Priority: High | Effort: 1-2 days | Dependencies: None**

**Tasks:**
1. Create `web/src/types/api.d.ts`
    - Centralized type definitions for all API responses
    - **Critical:** Check what endpoints ACTUALLY return (database rows or structs)
    - Reference source files in comments:
      - `internal/database/queries.sql.go` for database rows
      - `internal/handlers/*.go` for handler-defined structs
    - **Critical:** Use snake_case field names matching Go JSON tags
    - Example: `json:"media_item_id"` → `media_item_id: string`
    - Use `.d.ts` extension (no JS output)
    - **Warning:** Some handler structs are unused/incorrect (e.g., search.go's MediaItemSummary)
    - Always verify by checking the endpoint's actual return statement

2. Create `web/src/storage.ts`
   - localStorage wrapper with type safety
   - Token management helpers
   - Theme persistence

3. Create `web/src/dom.ts`
   - escapeHtml utility
   - querySelector wrappers with null checks
   - Element creation helpers

4. Create `web/src/api.ts`
   - API client functions (procedural, no classes)
   - Automatic auth header injection
   - Error handling integration with toast system

5. Create `web/src/events.ts` (likely needed for dynamic content)
   - Event delegation helpers
   - Data attribute selectors
   - Reusable event handler patterns

**Build Verification:**
- Run `npm run build:ts` to verify all modules compile
- Confirm `.js` files generated in `web/static/`
- Verify `types/api.d.ts` produces no `.js` file
- Test utility functions in browser console

**Deliverable:** Reusable utilities for all feature modules

**Files:**
- Create: `web/src/storage.ts`
- Create: `web/src/dom.ts`
- Create: `web/src/api.ts`
- Optionally: `web/src/events.ts` (if event delegation is needed)

---

### Phase 3: Low Complexity Features (Search, Header, Admin)
**Priority: Medium | Effort: 3-4 days | Dependencies: Phase 2**

**Tasks:**

**3.1 Search Module (from Phase 1)**
- Refine search logic in `web/src/search.ts` (created in Phase 1)
- Verify keyboard navigation works correctly
- Add proper types from `types/api.d.ts`
- Test debounced search functionality

**3.2 Header Dropdowns (Review Only)**
- Review `web/src/header.ts` (already converted to TypeScript)
- Ensure patterns are consistent and can serve as reference
- Verify event delegation follows best practices
- Confirm theme switching logic is correct

**3.3 Admin Actions**
- Quick scan trigger
- System stats display
- Admin profile updates

**3.4 Analytics Module**
- Create `web/src/analytics.ts`
- `loadAnalytics()` function - fetches stats from `/api/analytics/stats`, `/api/analytics/devices`, `/api/analytics/popular`
- Chart.js initialization:
  - Daily reading minutes chart
  - Device usage chart
  - Popular books display
- Date range filtering
- **Note:** This is pure client-side data loading (no SSR data passed to template)
- Uses Chart.js CDN (already included in template)

**Build Verification:**
- Run `npm run build:ts` to verify compilation
- Confirm `web/static/admin.js` and `web/static/analytics.js` are generated
- Test admin and analytics functionality in browser
- Verify analytics page loads data and displays charts
- Test date range filtering

**Deliverable:** Search, header, admin, and analytics features in TypeScript

**Files:**
- Refine: `web/src/search.ts` (created in Phase 1, add types)
- Review: `web/src/header.ts` (already converted, ensure patterns consistent)
- Create: `web/src/admin.ts` (scan, stats, profile management)
- Create: `web/src/analytics.ts` (data loading, Chart.js integration)

---

### Phase 4: Medium Complexity Features (Collections, Bookshelf, Devices, Queue)
**Priority: Medium | Effort: 5-6 days | Dependencies: Phase 2, 3**

**Tasks:**

**4.1 Collection Rules**
- Convert rule CRUD from `collection_rules.templ`
- Use `/api/collections/{id}/rules` endpoints
- Rule testing functionality
- Bulk rule operations

**4.2 Bookshelf Display**
- Convert from `bookshelf.templ`
- Pagination logic
- Library selection state
- Book viewing interactions

**4.3 Device Management**
- Convert from `devices.templ`
- Token regeneration
- Sync URL display
- Device registration
- **Note:** `web/src/device-management.ts` already exists for some functionality
- Integrate with existing device-management module as needed

**4.4 Queue Management**
- Create `web/src/queue.ts`
- `processPendingItems()` - POST to `/api/queue/process`
- `clearFailedItems()` - DELETE to `/api/queue/failed`
- `clearAllItems()` - DELETE to `/api/queue/all`
- `filterQueue()` - client-side filtering by status, type, device
- `refreshQueue()` - reload queue data from server
- Modal for queue item details
- **Note:** Template uses SSR for initial queue data (receives `QueueItemResponse`, `QueueStatsResponse`)
- CRUD operations happen via TypeScript

**Build Verification:**
- Run `npm run build:ts` to verify compilation
- Confirm `.js` files generated for collections, bookshelf, devices, and queue
- Test all functionality in browser

**Deliverable:** Collections, bookshelf, devices, and queue features in TypeScript

**Files:**
- Create: `web/src/collections.ts` (rules CRUD, bulk operations, rule testing)
- Create: `web/src/bookshelf.ts` (display, pagination, library selection)
- Note: Device management functionality already exists in `web/src/device-management.ts`; integrate with devices.templ conversion as needed

---

### Phase 5: High Complexity Features (Linking, Bulk Operations, Conflicts)
**Priority: Low | Effort: 7-8 days | Dependencies: Phase 4**

**Tasks:**

**5.1 Book Linking**
- Convert matching logic from `unlinked_books.templ`
- Search and match functionality
- Manual link modal
- Bulk auto-link
- Bulk get suggestions

**5.2 API Explorer**
- Convert from `api_explorer.templ`
- Request/response display
- cURL generation
- History tracking

**5.3 Conflict Resolution**
- Create `web/src/conflicts.ts`
- `filterConflicts()` - client-side filtering by status
- `dismissAllResolved()` - POST to `/api/conflicts/dismiss-resolved`
- `bulkResolve()` - POST to `/api/conflicts/bulk-resolve` with strategy (most_recent, highest_progress)
- `bulkDismiss()` - POST to `/api/conflicts/bulk-dismiss`
- `handleResolveConflict()` - POST to `/api/conflicts/{id}/resolve`
  - Select winner device (koreader, kobo, web, manual)
  - Manual override inputs (percentage, page, epubcfi, chapter)
  - Resolution reason
- `showConflictModal()`, `hideConflictModal()` - modal management
- `updateBulkActions()` - update UI based on selected conflicts
- `toggleAllConflicts()` - select/deselect all conflicts
- **Note:** Template uses SSR for initial conflicts list (receives `ConflictDetailResponse`)
- All resolution operations happen via TypeScript

**Build Verification:**
- Run `npm run build:ts` to verify compilation
- Confirm `.js` files generated for linking, api-explorer, and conflicts
- Test all functionality in browser
- Verify conflict resolution (individual and bulk)
- Test modal interactions

**Deliverable:** Book linking, API explorer, and conflict resolution in TypeScript

**Files:**
- Create: `web/src/linking.ts` (matching, manual/bulk link, suggestions)
- Create: `web/src/api-explorer.ts` (request, response, cURL generation, history)
- Create: `web/src/conflicts.ts` (conflict resolution, bulk operations, modals)

---

### Phase 6: Template Integration & Cleanup
**Priority: High | Effort: 3-4 days | Dependencies: All phases**

**Tasks:**

**6.1 Update Templates**
- Replace `<script>` blocks with `<script src="/static/[feature].js">`
- Remove inline logic (functions, fetch calls, state management)
- Keep simple `onclick="window.functionName()"` calls where appropriate
- Use `data-action` attributes only for dynamic content or when event delegation simplifies code

**6.1.1 Login Template Cleanup (Explicit Task)**
- **File:** `templates/login.templ`
- **Remove:** Lines 62-88 (duplicate `applyTheme`, `loadTheme`, `changeTheme` functions)
- **Add:** `<script src="/static/theme.js"></script>` in `<head>`
- **Why:** Theme logic already exists in `web/src/theme.ts`, remove duplication
- **Verify:** Theme dropdown still works after cleanup

**6.2 Verify Progressive Enhancement**
- Test all pages with JavaScript disabled
- Ensure forms submit with full page reload (see Progressive Enhancement Pattern below)
- Verify critical paths work without JS

**6.3 Build Configuration**
- Update `tsconfig.json` with new file structure (if needed)
- Verify all `.ts` files compile to `.js` in `web/static/`
- Add source maps for debugging (optional)

**6.4 Testing**
- Verify all features work with TypeScript
- Check keyboard navigation
- Test form submissions
- Validate error handling

**6.5 Documentation Search Integration**
- Create `web/src/docs.ts`
- `toggleSidebar()` - sidebar visibility toggle for mobile
- Documentation search functionality:
  - Initialize lunr.js search index
  - Search input debouncing
  - Display search results
  - Navigate to search results
- Remove inline script from `docs.templ`
- **Note:** Template uses external libraries (lunr.js, lunr-flex.js) for search
- Keep it simple - no complex search UI, just basic functionality

**Build Verification:**
- Run `npm run build:ts` to verify entire project compiles
- Confirm all `.js` files generated in `web/static/`
- No TypeScript compilation errors
- Full manual testing of all features
- Test documentation search functionality
- Verify sidebar toggle works on mobile

**Deliverable:** Clean templates, all inline JavaScript replaced with TypeScript modules, documentation search functional

---

## Code Style Guidelines

### 1. Procedural/Imperative with Functional Techniques

**✅ GOOD:**
```typescript
// Pure function, no classes
function createRuleItem(rule: Rule): HTMLElement {
    const div = document.createElement('div');
    div.className = 'rule-item';
    div.innerHTML = renderRuleHTML(rule);
    return div;
}

// Event delegation (one listener)
document.addEventListener('click', (e) => {
    const target = e.target as HTMLElement;
    const deleteBtn = target.closest('[data-action="delete-rule"]');
    if (deleteBtn) {
        const ruleId = deleteBtn.dataset.ruleId;
        deleteRule(ruleId);
    }
});
```

**❌ BAD:**
```typescript
// Class-based, OOP
class RuleManager {
    private rules: Rule[] = [];
    constructor() { ... }
    addRule(rule: Rule) { ... }
}
```

### 2. Type Definitions

**Define TypeScript Interfaces Matching Go Handler JSON Tags:**
```typescript
// Matches internal/handlers/book_matching.go
// Check JSON tags: `json:"progress_id"`, `json:"device_id"`, etc.
// Reference: Find struct definition in Go handler file
interface UnlinkedBookData {
    progress_id: string;
    device_id: string;
    device_name: string;
    device_type: 'koreader' | 'kobo' | 'web';
    title_from_device: string;
    file_path: string;
    sha256: string;
    last_sync_time: string;
    confidence_score: number;
    potential_matches: PotentialMatchData[];
}

interface PotentialMatchData {
    media_item_id: string;
    title: string;
    author: string;
    confidence: number;
    cover_image_path?: string;
}
```

**Important: Database Rows vs Handler Structs**
Some endpoints return database rows directly (e.g., `SearchMediaItemsRow`), not handler-defined structs. Always check the endpoint's return statement:

```go
// internal/handlers/media.go:SearchMediaItems()
return c.JSON(http.StatusOK, partialResults)  // Returns []SearchMediaItemsRow from database
```

When in doubt, grep the endpoint function and check what it actually returns.

**Only Create Frontend-Specific Types When Necessary:**
```typescript
// OK: Frontend-specific state
type SearchState = {
    query: string;
    results: MediaItem[];
    selectedIndex: number;
};

// OK: UI-specific config
type ToastType = 'error' | 'success' | 'info';
```

### 3. Error Handling

**Integrate with Toast System:**
```typescript
async function deleteRule(ruleId: string): Promise<void> {
    try {
        const response = await (window as any).api.delete(`/collections/rules/${ruleId}`);

        if (!response.ok) {
            const error = await response.json();
            (window as any).showToast.error(error.message || 'Failed to delete rule');
            return;
        }

        (window as any).showToast.success('Rule deleted');
        removeRuleFromDOM(ruleId);
    } catch (error) {
        (window as any).showToast.error('Network error: Unable to connect to server');
        console.error('Delete rule error:', error);
    }
}
```

### 4. API Client Pattern

**Procedural API Client (No Classes):**
```typescript
// web/src/api.ts
function getAuthHeader(): string {
    const token = localStorage.getItem('token');
    return token ? `Bearer ${token}` : '';
}

async function apiGet(url: string): Promise<Response> {
    return fetch(`/api${url}`, {
        headers: {
            'Authorization': getAuthHeader(),
            'Content-Type': 'application/json'
        }
    });
}

async function apiPost(url: string, data: unknown): Promise<Response> {
    return fetch(`/api${url}`, {
        method: 'POST',
        headers: {
            'Authorization': getAuthHeader(),
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });
}

async function apiDelete(url: string): Promise<Response> {
    return fetch(`/api${url}`, {
        method: 'DELETE',
        headers: {
            'Authorization': getAuthHeader()
        }
    });
}

async function apiPut(url: string, data: unknown): Promise<Response> {
    return fetch(`/api${url}`, {
        method: 'PUT',
        headers: {
            'Authorization': getAuthHeader(),
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });
}

// Export to window for use in other modules
(window as any).api = {
    get: apiGet,
    post: apiPost,
    delete: apiDelete,
    put: apiPut
};
```

### 5. Event Handler Pattern (Pragmatic Mix)

**Use onclick for Simple Static Content:**
```html
<!-- ✅ GOOD: Simple onclick for server-rendered content -->
<button onclick="window.deleteRule('{rule.id}')">Delete</button>
```
**When to use:**
- Static server-rendered HTML
- Simple function calls to well-named functions
- When you want explicit, readable HTML

**Use data-action + Event Delegation for Dynamic Content:**
```html
<!-- ✅ GOOD: Event delegation for dynamically added rows -->
<button data-action="delete-rule" data-rule-id="{rule.id}">Delete</button>
```

```typescript
// Event delegation (one listener handles all dynamic items)
document.addEventListener('click', async (e) => {
    const target = e.target as HTMLElement;
    const deleteBtn = target.closest('[data-action="delete-rule"]');

    if (deleteBtn) {
        const ruleId = deleteBtn.dataset.ruleId;
        if (ruleId && confirm('Are you sure you want to delete this rule?')) {
            await deleteRule(ruleId);
        }
    }
});
```
**When to use:**
- Dynamic content (rows added after page load)
- Lists where every item needs the same handler
- When event delegation genuinely simplifies the code

**Use Form Interception for Progressive Enhancement:**
```html
<!-- ✅ GOOD: Form works without JavaScript, enhanced with JS -->
<form action="/collections/{id}/rules" method="POST">
    <input type="text" name="value" required>
    <button type="submit">Add Rule</button>
</form>
```
**When to use:**
- Forms that must work without JavaScript
- Progressive enhancement is required
- Critical user flows

**❌ DON'T:**
- Mandate data-action everywhere (over-engineering)
- Remove all onclick handlers (unnecessary refactoring)

**✅ DO:**
- Remove inline `<script>` blocks with complex logic
- Extract to TypeScript modules attached to window
- Match existing patterns from toast.ts, theme.ts, header.ts
- Use the pattern that makes sense for each specific case

### 6. Progressive Enhancement

**Progressive Enhancement Pattern:**

All critical user flows must work without JavaScript. The application uses HTMX for most forms, which provides progressive enhancement automatically.

**⚠️ Current HTMX Forms Limitation (VERIFIED):**

The existing HTMX forms do NOT have `action` attributes, meaning they **will NOT work without JavaScript**. This is a pre-existing condition, not something this conversion plan introduces:

```html
<!-- Current forms LACK action attributes -->
<form hx-post="/api/auth/login" hx-target="#result">  <!-- NO action/method -->
```

**Options (outside scope of this plan):**
1. Add `action` attributes to HTMX forms for true progressive enhancement
2. Accept that login/register flows require JavaScript (current state)
3. Create separate server-rendered login fallback pages

**This conversion plan maintains the current behavior** - it does not fix or worsen progressive enhancement. The goal is to convert inline JavaScript to TypeScript without breaking existing functionality.

**HTMX Forms (Current State):**
```html
<!-- login.templ - Uses HTMX, but no action fallback -->
<form hx-post="/api/auth/login" hx-target="#result" hx-swap="innerHTML">
    <input type="text" name="login" required>
    <input type="password" name="password" required>
    <button type="submit">Sign In</button>
</form>
<div id="result"></div>
```

**How Current HTMX Forms Work:**
- With JavaScript: HTMX intercepts submit, posts to API, updates DOM without reload
- Without JavaScript: **Form does NOT submit** (no action attribute)
- This is pre-existing behavior - not introduced by this conversion

**When to Add TypeScript Form Interception:**
Use TypeScript interception only when you need custom behavior beyond HTMX:

```typescript
// Example: Custom form handling with redirect
// web/src/auth.ts
document.addEventListener('DOMContentLoaded', () => {
    const form = document.querySelector('form[action="/api/auth/login"]') as HTMLFormElement;
    if (!form) return;

    form.addEventListener('submit', async (e) => {
        e.preventDefault();

        const formData = new FormData(form);
        const response = await fetch('/api/auth/login', {
            method: 'POST',
            body: formData
        });

        if (response.ok) {
            const data = await response.json();
            localStorage.setItem('token', data.access_token);
            window.location.href = '/dashboard';
        } else {
            (window as any).showToast.error('Login failed');
        }
    });
});
```

**Guidelines:**
- Prefer HTMX for forms (already progressive enhanced)
- Add TypeScript only when you need custom logic
- All forms must have `action` and `method` attributes
- Test with JavaScript disabled before completing conversion
- HTMX: works without JS, enhanced with JS
- Custom TypeScript: must handle both cases

---

## Build & Deployment

### TypeScript Configuration

**Current `tsconfig.json` (already configured correctly):**
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "none",
    "lib": ["ES2020", "DOM"],
    "outDir": "./web/static",
    "rootDir": "./web/src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": false,
    "sourceMap": false,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": [
    "web/src/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}
```

**Key points:**
- `module: "none"` = Browser globals (no ES modules)
- `rootDir: "./web/src"` = All TypeScript in src/
- `outDir: "./web/static"` = Flat output structure
- No bundler needed - TypeScript compiles directly to browser-compatible JavaScript

### Build Scripts

**Current `package.json` (no changes needed):**
```json
{
  "scripts": {
    "build:css": "tailwindcss -i ./web/static/input.css -o ./web/static/style.css --watch",
    "build:css:prod": "tailwindcss -i ./web/static/input.css -o ./web/static/style.css --minify",
    "build:ts": "tsc",
    "build:ts:watch": "tsc --watch"
  }
}
```

**Note:** No additional build scripts needed. Docker handles production builds, and `tsc` compilation is environment-agnostic. Run `npm run build:ts:watch` for development.

### Output Structure

**Compiled JavaScript (flat structure in web/static/):**
```
web/static/
├── toast.js              # ✅ Already exists
├── theme.js              # ✅ Already exists
├── header.js             # ✅ Already exists
├── device-management.js  # ✅ Already exists
├── search.js             # NEW (from search.js)
├── storage.js            # NEW
├── dom.js                # NEW
├── api.js                # NEW
├── collections.js        # NEW
├── linking.js            # NEW
├── bookshelf.js          # NEW
├── api-explorer.js       # NEW
├── admin.js              # NEW
├── analytics.js          # NEW
├── queue.js              # NEW
├── conflicts.js          # NEW
└── docs.js               # NEW
```

**No subdirectories** - TypeScript with `module: "none"` compiles to flat output matching source structure.

---

## Testing Strategy

### 1. Unit Testing (Optional)
Test pure functions that don't depend on DOM:
```typescript
// Test utilities
describe('escapeHtml', () => {
    it('should escape HTML entities', () => {
        expect(escapeHtml('<script>')).to.equal('&lt;script&gt;');
    });
});

// Test formatters
describe('formatConfidence', () => {
    it('should format confidence as percentage', () => {
        expect(formatConfidence(0.95)).to.equal('95%');
    });
});
```

### 2. Integration Testing
Test API interactions:
```typescript
describe('deleteRule', () => {
    it('should call DELETE /api/collections/rules/{id}', async () => {
        const fetchSpy = sinon.stub(global, 'fetch');
        await deleteRule('rule-123');

        expect(fetchSpy.calledWith('/api/collections/rules/rule-123', {
            method: 'DELETE'
        })).to.be.true;
    });
});
```

### 3. Manual Testing Checklist
- [ ] All CRUD operations work (create, read, update, delete)
- [ ] Toast notifications display correctly
- [ ] Error handling works (network errors, 500 errors, 404 errors)
- [ ] Keyboard navigation works (search, modals)
- [ ] Forms submit correctly
- [ ] Bulk operations work
- [ ] Progressive enhancement (test with JS disabled)
- [ ] All pages load with SSR data
- [ ] No console errors

### 4. Browser Testing
Test in:
- Chrome/Edge (Chromium)
- Firefox
- Safari (if available)
- Mobile browsers (responsive testing)

---

## Progressive Enhancement Verification

### Test Without JavaScript

**Disable JavaScript in browser:**
1. Open DevTools
2. Settings → Disable JavaScript
3. Reload page
4. Verify critical functionality works

**What Should Work:**
- ✅ Page loads with SSR data
- ✅ Navigation links work (full page reload)
- ✅ Forms submit (full page reload, not AJAX)
- ✅ All data visible on initial load

**What Won't Work (Expected):**
- ❌ Dynamic updates without page reload
- ❌ Toast notifications
- ❌ Keyboard navigation
- ❌ Modal dialogs
- ❌ Auto-complete search

**Mitigation:**
- Ensure forms have proper `action` and `method` attributes
- Provide submit buttons for all operations
- Include helpful error messages in HTML responses

---

## Risk Mitigation

### Potential Issues

**1. Breaking Changes During Conversion**
- **Risk**: Converting inline JS breaks functionality
- **Mitigation**: Convert incrementally, test each feature
- **Rollback**: Keep inline JS until TypeScript is verified

**2. Type Mismatches with Go Handlers**
- **Risk**: TypeScript types don't match JSON responses
- **Mitigation**: Use Go handler types as source of truth
- **Validation**: Test API responses match TypeScript types

**3. Progressive Enhancement Regression**
- **Risk**: Pages require JavaScript to function
- **Mitigation**: Test with JS disabled before/after
- **Validation**: Forms must have action/method attributes

**4. Build Complexity**
- **Risk**: TypeScript compilation becomes bottleneck
- **Mitigation**: Use existing `tsc` setup, add watch mode
- **Validation**: Build time under 5 seconds

**5. Bundle Size**
- **Risk**: Too much JavaScript loaded
- **Mitigation**: Split by feature, load per-page
- **Validation**: Monitor bundle sizes, code splitting

### Rollback Strategy

**If conversion fails:**
1. Git revert TypeScript files
2. Inline JavaScript still works (wasn't deleted yet)
3. Fix issues and retry
4. Delete inline JS only after TypeScript verified

**Per-feature rollback:**
```bash
# Before converting feature
git branch backup-before-collections

# If collections conversion breaks
git checkout backup-before-collections -- templates/collections.templ

# Fix TypeScript and try again
```

---

## Estimated Timeline

| Phase | Duration | Dependencies | Deliverables |
|-------|----------|--------------|--------------|
| Phase 1: Standalone Conversion | 1 day | None | Search converted to TS |
| Phase 2: Core Utilities | 1-2 days | None | Storage, DOM, API, events modules |
| Phase 3: Low Complexity | 2-3 days | Phase 2 | Search, header, admin, analytics in TS |
| Phase 4: Medium Complexity | 3-4 days | Phase 2, 3 | Collections, bookshelf, devices, queue in TS |
| Phase 5: High Complexity | 4-5 days | Phase 4 | Linking, API explorer, conflicts in TS |
| Phase 6: Integration & Cleanup | 2-3 days | All phases | Clean templates, docs search, verified functionality |
| **Total** | **13-18 days** | | **Full TypeScript conversion** |

**Note:** Timeline reduced from initial estimate based on actual line count verification (~2,800 lines vs original ~6,300 estimate). Three templates (conflicts, queue, analytics) have NO inline script blocks and only need TypeScript modules for their onclick handlers.

---

## Success Criteria

- [ ] All inline JavaScript logic removed from templates (functions, fetch calls, state management)
- [ ] All features work with TypeScript
- [ ] TypeScript compilation passes with strict mode
- [ ] No regression in existing progressive enhancement behavior (HTMX forms unchanged)
- [ ] No type `any` (except for legacy API responses)
- [ ] Event handlers use pragmatic mix of onclick, data-action, and form interception as appropriate
- [ ] **Type definitions use snake_case field names matching actual API responses**
- [ ] **Type definitions verified against endpoint returns (not just handler structs)**
- [ ] Type definition comments reference source files:
  - Database rows: `// Matches internal/database/queries.sql.go:SearchMediaItemsRow`
  - Handler structs: `// Matches handlers.BookInfo JSON: media_item_id, title, author`
- [ ] `import type { ... } from './types/api'` pattern used for type checking
- [ ] Full manual testing completed
- [ ] No regression in functionality
- [ ] Bundle sizes monitored and optimized
- [ ] SSR still works for all initial page loads
- [ ] All CRUD operations use existing `/api/*` endpoints
- [ ] Login template duplicate theme logic removed (lines 62-88)
- [ ] Search functionality uses correct types matching database SearchMediaItemsRow
- [ ] Analytics page loads data and displays charts correctly
- [ ] Queue management CRUD operations work (process, clear, filter)
- [ ] Conflict resolution works (individual and bulk operations)
- [ ] Documentation search functionality works
- [ ] All 10 missing type definitions added (analytics, queue, conflicts)
- [ ] Total converted: ~2,800 lines of inline script blocks

---

## Next Steps

1. **Review and approve** this plan
2. **Setup Phase 1**: Convert `search.js` → TypeScript (ensure snake_case field names)
3. **Begin Phase 2**: Create core utility modules (including `types/api.d.ts` with snake_case types)
4. **Iterate** through phases 3-5 (feature conversion)
5. **Phase 6**: Final integration and cleanup (remove login.templ duplicate theme code, lines 62-88)

---

## Appendix: Common Pitfalls

### Database Rows vs Handler Structs

**Problem:** Some handler files define structs that don't match what the endpoint actually returns.

**Example:**
```go
// internal/handlers/search.go
// This struct is DEFINED but never used!
type MediaItemSummary struct {
    ID      string         `json:"id"`
    Title   string         `json:"title"`
    Authors []SearchAuthor `json:"authors"`  // Wrong! API returns string, not array
}

// internal/handlers/media.go
// The endpoint actually returns database rows:
func (mh *MediaHandler) SearchMediaItems(c echo.Context) error {
    partialResults, err := mh.db.SearchMediaItems(...) // Returns []SearchMediaItemsRow
    return c.JSON(http.StatusOK, partialResults)      // Has library_id, author (string), etc.
}
```

**Solution:**
1. Grep the endpoint function to find what it actually returns
2. Check the return statement: `return c.JSON(..., variable)`
3. Find that variable's type definition
4. Use that type's JSON tags, not some unrelated handler struct

**Verification:**
```bash
# Find endpoint implementation
rg "func.*SearchMediaItems" internal/handlers/
# Check what it returns
rg -A 5 "return c.JSON" internal/handlers/media.go
# Find the returned type
rg "type SearchMediaItemsRow" internal/database/
```

---

## Appendix: Progressive Enhancement Test Checklist

Use this checklist when converting templates to ensure progressive enhancement is maintained:

**Before removing inline JavaScript:**
- [ ] Identify all forms in the template
- [ ] Verify each form has `action` and `method` attributes
- [ ] Verify each form has a submit button (not just button with onclick)
- [ ] Test form submission works with JavaScript disabled
- [ ] Identify all critical user flows (login, create, update, delete)
- [ ] Verify each critical flow has a non-JavaScript fallback

**After TypeScript conversion:**
- [ ] Test with JavaScript disabled (DevTools → Disable JavaScript)
- [ ] Verify forms still submit with full page reload
- [ ] Verify navigation links work (full page reload)
- [ ] Verify all data is visible on initial load (SSR)
- [ ] Test critical user flows work without JavaScript
- [ ] Enable JavaScript and verify enhanced experience

**What to test without JavaScript:**
- [ ] Page loads and displays data
- [ ] Forms can be submitted
- [ ] Navigation links work
- [ ] No console errors

**What requires JavaScript (expected to fail without JS):**
- [ ] Toast notifications
- [ ] AJAX form submission (no page reload)
- [ ] Modal dialogs
- [ ] Dynamic content updates
- [ ] Keyboard navigation shortcuts
- [ ] Auto-complete search

---

## Appendix: Template Integration Examples

### Before: Inline JavaScript

```html
<!-- templates/collection_rules.templ -->
<script>
    let collectionId = '{ collection.ID }';

    function renderRules(rules) {
        const container = document.getElementById('rules-container');
        container.innerHTML = rules.map((rule, index) => `
            <div class="rule-item">
                <span>${rule.field}</span>
                <button onclick="deleteRule('${rule.id}')">Delete</button>
            </div>
        `).join('');
    }

    function deleteRule(ruleId) {
        fetch(`/api/collections/${collectionId}/rules/${ruleId}`, {
            method: 'DELETE',
            headers: { 'Authorization': 'Bearer ' + localStorage.getItem('token') }
        }).then(response => {
            if (response.ok) {
                loadRules();
                showToast('Rule deleted');
            }
        });
    }

    function loadRules() {
        fetch(`/api/collections/${collectionId}/rules`)
            .then(response => response.json())
            .then(rules => renderRules(rules));
    }

    loadRules();
</script>
```

### After: TypeScript Module (Browser Globals)

**TypeScript Module:**
```typescript
// web/src/collections.ts

interface Rule {
    id: string;
    field: string;
    operator: string;
    value: string;
}

function escapeHtml(text: string): string {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
}

async function loadRules(collectionId: string): Promise<void> {
    try {
        const response = await (window as any).api.get(`/collections/${collectionId}/rules`);

        if (!response.ok) {
            throw new Error('Failed to load rules');
        }

        const rules: Rule[] = await response.json();
        renderRules(rules);
    } catch (error) {
        console.error('Load rules error:', error);
        (window as any).showToast.error('Failed to load rules');
    }
}

function renderRules(collectionId: string, rules: Rule[]): void {
    const container = document.getElementById('rules-container');
    if (!container) return;

    container.innerHTML = rules.map(rule => `
        <div class="rule-item" data-rule-id="${rule.id}">
            <span>${escapeHtml(rule.field)}</span>
            <button onclick="window.deleteRule('${collectionId}', '${rule.id}')">Delete</button>
        </div>
    `).join('');
}

async function loadRules(collectionId: string): Promise<void> {
    try {
        const response = await (window as any).api.get(`/collections/${collectionId}/rules`);

        if (!response.ok) {
            throw new Error('Failed to load rules');
        }

        const rules: Rule[] = await response.json();
        renderRules(collectionId, rules);
    } catch (error) {
        console.error('Load rules error:', error);
        (window as any).showToast.error('Failed to load rules');
    }
}

async function deleteRule(collectionId: string, ruleId: string): Promise<void> {
    if (!confirm('Are you sure you want to delete this rule?')) {
        return;
    }

    try {
        const response = await (window as any).api.delete(`/collections/${collectionId}/rules/${ruleId}`);

        if (!response.ok) {
            throw new Error('Failed to delete rule');
        }

        (window as any).showToast.success('Rule deleted');

        const ruleElement = document.querySelector(`[data-rule-id="${ruleId}"]`);
        ruleElement?.remove();
    } catch (error) {
        console.error('Delete rule error:', error);
        (window as any).showToast.error('Failed to delete rule');
    }
}

// Export to window for HTML access
(window as any).loadRules = loadRules;
(window as any).deleteRule = deleteRule;

// Initialize on page load
if (typeof document !== 'undefined') {
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', initializeCollectionRules);
    } else {
        initializeCollectionRules();
    }
}

function initializeCollectionRules() {
    const collectionId = document.body.dataset.collectionId;
    if (collectionId) {
        loadRules(collectionId);
    }
}
```

**Cleaned Template:**
```html
<!-- templates/collection_rules.templ -->
<!DOCTYPE html>
<html>
<head>
    <script src="/static/htmx.min.js"></script>
    <script src="/static/toast.js"></script>
    <script src="/static/api.js"></script>
    <script src="/static/collections.js"></script>
</head>
<body data-collection-id="{ collection.ID }">
    <div id="rules-container">
        <!-- SSR: Initial rules rendered server-side -->
        { range .Rules }
        <div class="rule-item" data-rule-id="{ .ID }">
            <span>{ .Field }</span>
            <button onclick="window.deleteRule('{collection.ID}', '{.ID}')">
                Delete
            </button>
        </div>
        { end }
    </div>
</body>
</html>
```

**Benefits:**
- ✅ No inline JavaScript logic (functions, fetch calls, state management)
- ✅ Simple onclick calls are explicit and easy to understand
- ✅ Type-safe API calls through procedural api module
- ✅ Better error handling with toast integration
- ✅ Reusable module attached to window
- ✅ SSR still works (initial rules in HTML)
- ✅ Progressive enhancement (form can submit without JS)
- ✅ No ES modules or bundler needed (browser globals)

---

*Generated: 2025-02-17*
*Updated: 2025-02-18 (Revised to match existing codebase patterns)*
*Updated: 2025-02-18 (Fixed file paths, removed unnecessary build scripts, added manual type sync strategy)*
*Updated: 2025-02-18 (Changed to .d.ts for type definitions, added build verification steps, documented progressive enhancement pattern)*
*Updated: 2025-02-18 (Corrected type definitions to use snake_case matching Go JSON tags, simplified progressive enhancement section, added missing types)*
*Updated: 2025-02-18 (Clarified database row vs handler struct confusion, documented template-handler type sharing, added HTMX progressive enhancement details, added common pitfalls appendix)*
*Updated: 2025-02-18 (Added missing templates: analytics, queue, conflicts, docs; added 10 missing type definitions; updated line counts to ~6,300; revised timeline to 20-25 days; added all missing phases and tasks)*
*Updated: 2025-02-18 (VERIFIED CORRECTIONS: Fixed line counts (~2,800 actual vs ~6,300 estimated), corrected analytics/queue/conflicts type definitions to match actual Go structs, noted HTMX forms lack action attributes, reduced timeline to 13-18 days)*
*Follows: PROJECT_GUIDELINES.md*
*Architecture: Hybrid SSR + TypeScript CRUD (Browser Globals, No ES Modules)*