From d709510a28dc710e05952f3ececda6e0f7ecbbc8 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Wed, 18 Feb 2026 16:38:12 -0500
Subject: [PATCH] docs(typescript): update conversion plan with accurate line
 counts and template analysis

---
 TYPESCRIPT_CONVERSION_PLAN.md | 1310 +++++++++++++++++++++++++--------
 1 file changed, 992 insertions(+), 318 deletions(-)

diff --git a/TYPESCRIPT_CONVERSION_PLAN.md b/TYPESCRIPT_CONVERSION_PLAN.md
index 6776e54..1e8e364 100644
--- a/TYPESCRIPT_CONVERSION_PLAN.md
+++ b/TYPESCRIPT_CONVERSION_PLAN.md
@@ -2,7 +2,7 @@
 
 ## Executive Summary
 
-Convert **~5,500 lines of inline JavaScript** across 13 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.
+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.
 
@@ -15,32 +15,38 @@ Convert **~5,500 lines of inline JavaScript** across 13 template files into orga
 |--------|--------|-------|---------|
 | `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` | ~100 | Header dropdowns, theme/user menus |
-| `web/src/device-management.ts` | `device-management.js` | ~70 | Device token copy/regeneration |
+| `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 (~5,500 lines)
+### Inline JavaScript in Templates (~2,800 lines)
 | Template | Script Lines | Primary Functions |
 |----------|--------------|-------------------|
-| `collection_rules.templ` | ~400 | Rule CRUD operations, testing |
-| `unlinked_books.templ` | ~650 | Book matching, linking, bulk operations |
-| `collections.templ` | ~500 | Bulk operations, filtering |
-| `devices.templ` | ~350 | Token regeneration, sync URL display |
-| `bookshelf.templ` | ~250 | Book viewing, pagination |
-| `dashboard.templ` | ~300 | Statistics, recent activity |
-| `api_explorer.templ` | ~200 | API testing, cURL generation |
-| `admin_library.templ` | ~250 | Admin library scan |
-| `admin_profile.templ` | ~150 | Admin profile management |
-| `admin.templ` | ~150 | Admin dashboard actions |
-| `index.templ` | ~100 | Landing page theme preview |
-| `login.templ` | ~100 | Login theme selection |
-| `progress.templ` | ~100 | Reading progress |
+| `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: ~5,500 lines of inline JavaScript to convert**
+**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.
 
 ---
 
@@ -83,98 +89,428 @@ Convert **~5,500 lines of inline JavaScript** across 13 template files into orga
 
 ## Proposed TypeScript Structure
 
+**Continuing with existing `web/src/` pattern:**
+
 ```
-web/ts/
-├── core/
-│   ├── toast.ts              # ✅ Already converted
-│   ├── theme.ts              # ✅ Already converted
-│   ├── storage.ts            # NEW: localStorage wrapper with types
-│   ├── dom.ts                # NEW: DOM utilities (escapeHtml, querySelector)
-│   └── api.ts                # NEW: API client wrapper with auth
-│
-├── features/
-│   ├── search/
-│   │   ├── search.ts         # Convert from search.js
-│   │   └── types.ts          # Search result types (match Go handlers)
-│   │
-│   ├── collections/
-│   │   ├── rules.ts          # Convert from inline JS
-│   │   ├── bulk.ts           # Convert from inline JS
-│   │   └── types.ts          # Reuse handlers.Rule, handlers.Collection
-│   │
-│   ├── linking/
-│   │   ├── matcher.ts        # Convert from inline JS
-│   │   ├── bulk-link.ts      # Convert from inline JS
-│   │   ├── manual-link.ts    # Convert from inline JS
-│   │   └── types.ts          # Reuse handlers.BookMatch, handlers.Progress
-│   │
-│   ├── devices/
-│   │   ├── token.ts          # Convert from inline JS
-│   │   └── types.ts          # Reuse handlers.Device types
-│   │
-│   ├── bookshelf/
-│   │   ├── display.ts        # Convert from inline JS
-│   │   ├── pagination.ts     # Convert from inline JS
-│   │   └── types.ts          # Reuse handlers.MediaItem types
-│   │
-│   ├── api-explorer/
-│   │   ├── request.ts        # Convert from inline JS
-│   │   ├── response.ts       # Convert from inline JS
-│   │   └── curl.ts           # Convert from inline JS
-│   │
-│   └── admin/
-│       ├── scan.ts           # Convert from inline JS
-│       └── stats.ts          # Convert from inline JS
-│
-└── shared/
-    ├── events.ts             # Event delegation utilities
-    └── auth.ts               # Token management helpers
+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
 
-### Principle: Reuse Go Handler Types
+### 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
-// Duplicating types from Go handlers
-interface Collection {
-    id: string;
-    name: string;
-    // ...
+// 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
-// Use types that match Go handlers exactly
-// These types are already defined in Go and returned by /api/*
-interface MediaItem {
+// 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;
+    author?: string;                    // Single author string, not array
     library_id: string;
     library_type_name: 'ebooks' | 'comics' | 'manga';
+    library_name: string;
     cover_image_path?: string;
 }
 
-// From handlers.CollectionData
+// Matches handlers.CollectionData JSON response
 interface CollectionData {
-    ID: string;
-    Name: string;
-    Description: string;
-    Color: string;
-    Icon: string;
+    id: string;
+    name: string;
+    description: string;
+    color: string;
+    icon: string;
 }
 ```
 
 **Why:**
-- Single source of truth (Go handlers)
-- API returns these types as JSON
-- TypeScript matches exactly what server provides
-- No duplication, no drift
+- 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;
+```
 
 ---
 
@@ -184,18 +520,32 @@ interface CollectionData {
 **Priority: High | Effort: 1 day | Dependencies: None**
 
 **Tasks:**
-1. Convert `web/static/search.js` → `web/ts/features/search/search.ts`
-2. Add proper types for search results (match `handlers.MediaItem`)
+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/ts/features/search/search.ts`
-- Create: `web/ts/features/search/types.ts`
+- Create: `web/src/search.ts`
 - Delete: `web/static/search.js`
-- Update: Templates referencing search functions
+- Update: Templates referencing search functions (header.templ)
 
 ---
 
@@ -203,33 +553,51 @@ interface CollectionData {
 **Priority: High | Effort: 1-2 days | Dependencies: None**
 
 **Tasks:**
-1. Create `web/ts/core/storage.ts`
+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
 
-2. Create `web/ts/core/dom.ts`
+3. Create `web/src/dom.ts`
    - escapeHtml utility
    - querySelector wrappers with null checks
    - Element creation helpers
 
-3. Create `web/ts/core/api.ts`
-   - API client wrapper
+4. Create `web/src/api.ts`
+   - API client functions (procedural, no classes)
    - Automatic auth header injection
    - Error handling integration with toast system
 
-4. Create `web/ts/shared/events.ts`
+5. Create `web/src/events.ts` (likely needed for dynamic content)
    - Event delegation helpers
    - Data attribute selectors
-   - Common event handlers
+   - 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/ts/core/storage.ts`
-- Create: `web/ts/core/dom.ts`
-- Create: `web/ts/core/api.ts`
-- Create: `web/ts/shared/events.ts`
+- 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)
 
 ---
 
@@ -239,35 +607,52 @@ interface CollectionData {
 **Tasks:**
 
 **3.1 Search Module (from Phase 1)**
-- Extract search logic from `search.ts`
-- Add debounced search with proper types
-- Keyboard navigation state management
-- Integration with `/api/media-items/search`
+- 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**
-- Extract from `header.ts` (already TS)
-- Add event delegation for dropdowns
-- Theme switching logic
-- User menu interactions
+**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
 
-**Deliverable:** Search, header, and admin features in TypeScript
+**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/ts/features/search/search.ts`
-- Update: `web/ts/features/search/types.ts`
-- Create: `web/ts/features/admin/scan.ts`
-- Create: `web/ts/features/admin/stats.ts`
-- Update: `web/src/header.ts` (add event delegation)
+- 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)
-**Priority: Medium | Effort: 4-5 days | Dependencies: Phase 2, 3**
+### Phase 4: Medium Complexity Features (Collections, Bookshelf, Devices, Queue)
+**Priority: Medium | Effort: 5-6 days | Dependencies: Phase 2, 3**
 
 **Tasks:**
 
@@ -288,22 +673,36 @@ interface CollectionData {
 - 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
 
-**Deliverable:** Collections, bookshelf, and devices features in TypeScript
+**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/ts/features/collections/rules.ts`
-- Create: `web/ts/features/collections/bulk.ts`
-- Create: `web/ts/features/collections/types.ts`
-- Create: `web/ts/features/bookshelf/display.ts`
-- Create: `web/ts/features/bookshelf/pagination.ts`
-- Create: `web/ts/features/devices/token.ts`
-- Create: `web/ts/features/devices/types.ts`
+- 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)
-**Priority: Low | Effort: 5-6 days | Dependencies: Phase 4**
+### Phase 5: High Complexity Features (Linking, Bulk Operations, Conflicts)
+**Priority: Low | Effort: 7-8 days | Dependencies: Phase 4**
 
 **Tasks:**
 
@@ -320,39 +719,65 @@ interface CollectionData {
 - cURL generation
 - History tracking
 
-**Deliverable:** Book linking and API explorer in TypeScript
+**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/ts/features/linking/matcher.ts`
-- Create: `web/ts/features/linking/bulk-link.ts`
-- Create: `web/ts/features/linking/manual-link.ts`
-- Create: `web/ts/features/linking/types.ts`
-- Create: `web/ts/features/api-explorer/request.ts`
-- Create: `web/ts/features/api-explorer/response.ts`
-- Create: `web/ts/features/api-explorer/curl.ts`
+- 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: 2-3 days | Dependencies: All phases**
+**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 `onclick="..."` handlers
-- Add `data-action` attributes for event delegation
-- Ensure progressive enhancement (pages work without 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
+- 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
-- Configure build process for all modules
-- Add source maps for debugging
+- 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
@@ -360,7 +785,27 @@ interface CollectionData {
 - Test form submissions
 - Validate error handling
 
-**Deliverable:** Clean templates, all inline JavaScript replaced with TypeScript modules
+**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
 
 ---
 
@@ -401,25 +846,43 @@ class RuleManager {
 
 ### 2. Type Definitions
 
-**Reuse Go Handler Types:**
+**Define TypeScript Interfaces Matching Go Handler JSON Tags:**
 ```typescript
-// From internal/handlers/book_matching.go
+// 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 {
-    ProgressID: string;
-    DeviceID: string;
-    TitleFromDevice: string;
-    SHA256: string;
-    PotentialMatches: PotentialMatchData[];
+    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 {
-    MediaItemID: string;
-    Title: string;
-    Author: string;
-    Confidence: number;
+    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
@@ -439,18 +902,18 @@ type ToastType = 'error' | 'success' | 'info';
 ```typescript
 async function deleteRule(ruleId: string): Promise<void> {
     try {
-        const response = await apiClient.delete(`/api/collections/rules/${ruleId}`);
+        const response = await (window as any).api.delete(`/collections/rules/${ruleId}`);
 
         if (!response.ok) {
             const error = await response.json();
-            window.showToast.error(error.message || 'Failed to delete rule');
+            (window as any).showToast.error(error.message || 'Failed to delete rule');
             return;
         }
 
-        window.showToast.success('Rule deleted');
+        (window as any).showToast.success('Rule deleted');
         removeRuleFromDOM(ruleId);
     } catch (error) {
-        window.showToast.error('Network error: Unable to connect to server');
+        (window as any).showToast.error('Network error: Unable to connect to server');
         console.error('Delete rule error:', error);
     }
 }
@@ -458,62 +921,83 @@ async function deleteRule(ruleId: string): Promise<void> {
 
 ### 4. API Client Pattern
 
-**Centralized API Client:**
+**Procedural API Client (No Classes):**
 ```typescript
-// web/ts/core/api.ts
-class APIClient {
-    private baseURL = '/api';
-    private getAuthHeader(): string {
-        const token = localStorage.getItem('token');
-        return token ? `Bearer ${token}` : '';
-    }
-
-    async get(url: string): Promise<Response> {
-        return fetch(`${this.baseURL}${url}`, {
-            headers: {
-                'Authorization': this.getAuthHeader(),
-                'Content-Type': 'application/json'
-            }
-        });
-    }
-
-    async post(url: string, data: unknown): Promise<Response> {
-        return fetch(`${this.baseURL}${url}`, {
-            method: 'POST',
-            headers: {
-                'Authorization': this.getAuthHeader(),
-                'Content-Type': 'application/json'
-            },
-            body: JSON.stringify(data)
-        });
-    }
-
-    async delete(url: string): Promise<Response> {
-        return fetch(`${this.baseURL}${url}`, {
-            method: 'DELETE',
-            headers: {
-                'Authorization': this.getAuthHeader()
-            }
-        });
-    }
+// web/src/api.ts
+function getAuthHeader(): string {
+    const token = localStorage.getItem('token');
+    return token ? `Bearer ${token}` : '';
 }
 
-export const apiClient = new APIClient();
+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 Delegation Pattern
+### 5. Event Handler Pattern (Pragmatic Mix)
 
-**Replace Inline Handlers:**
+**Use onclick for Simple Static Content:**
 ```html
-<!-- ❌ DON'T: Inline onclick -->
-<button onclick="deleteRule('{rule.id}')">Delete</button>
+<!-- ✅ 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
 
-<!-- ✅ DO: Data attributes -->
+**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>
 ```
 
-**Handle with Event Delegation:**
 ```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"]');
@@ -526,31 +1010,117 @@ document.addEventListener('click', async (e) => {
     }
 });
 ```
+**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
 
-**Ensure Works Without JavaScript:**
+**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
-<!-- Form submits with full page reload if JS fails -->
-<form action="/collections/{id}/rules" method="POST">
-    <input type="hidden" name="field" value="title">
-    <input type="hidden" name="operator" value="contains">
-    <input type="text" name="value" required>
-
-    <button type="submit">Add Rule</button>
-</form>
-
-<!-- TypeScript enhances with AJAX submit -->
-<script src="/static/features/collections/rules.js"></script>
+<!-- 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
 
-**Update `tsconfig.json`:**
+**Current `tsconfig.json` (already configured correctly):**
 ```json
 {
   "compilerOptions": {
@@ -558,21 +1128,19 @@ document.addEventListener('click', async (e) => {
     "module": "none",
     "lib": ["ES2020", "DOM"],
     "outDir": "./web/static",
-    "rootDir": "./web/ts",
+    "rootDir": "./web/src",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "declaration": false,
-    "sourceMap": true,
+    "sourceMap": false,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "resolveJsonModule": true
+    "noFallthroughCasesInSwitch": true
   },
   "include": [
-    "web/ts/**/*.ts",
     "web/src/**/*.ts"
   ],
   "exclude": [
@@ -581,63 +1149,54 @@ document.addEventListener('click', async (e) => {
 }
 ```
 
+**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
 
-**Update `package.json`:**
+**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",
-    "build:ts:prod": "tsc --sourceMap false",
-    "build:all": "npm run build:ts && npm run build:css:prod",
-    "dev": "npm run build:ts:watch & npm run build:css"
+    "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:**
+**Compiled JavaScript (flat structure in web/static/):**
 ```
 web/static/
-├── core/
-│   ├── toast.js              # ✅ Already exists
-│   ├── theme.js              # ✅ Already exists
-│   ├── header.js             # ✅ Already exists
-│   ├── device-management.js  # ✅ Already exists
-│   ├── storage.js            # NEW
-│   ├── dom.js                # NEW
-│   └── api.js                # NEW
-├── features/
-│   ├── search/
-│   │   └── search.js         # NEW
-│   ├── collections/
-│   │   ├── rules.js          # NEW
-│   │   └── bulk.js           # NEW
-│   ├── linking/
-│   │   ├── matcher.js        # NEW
-│   │   ├── bulk-link.js      # NEW
-│   │   └── manual-link.js    # NEW
-│   ├── bookshelf/
-│   │   ├── display.js        # NEW
-│   │   └── pagination.js     # NEW
-│   ├── devices/
-│   │   └── token.js          # NEW
-│   ├── api-explorer/
-│   │   ├── request.js        # NEW
-│   │   ├── response.js       # NEW
-│   │   └── curl.js           # NEW
-│   └── admin/
-│       ├── scan.js           # NEW
-│       └── stats.js          # NEW
-└── shared/
-    ├── events.js             # NEW
-    └── auth.js               # NEW
+├── 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
@@ -781,38 +1340,131 @@ git checkout backup-before-collections -- templates/collections.templ
 |-------|----------|--------------|--------------|
 | 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 | 3-4 days | Phase 2 | Search, header, admin in TS |
-| Phase 4: Medium Complexity | 4-5 days | Phase 2, 3 | Collections, bookshelf, devices in TS |
-| Phase 5: High Complexity | 5-6 days | Phase 4 | Linking, API explorer in TS |
-| Phase 6: Integration & Cleanup | 2-3 days | All phases | Clean templates, verified functionality |
-| **Total** | **16-21 days** | | **Full TypeScript conversion** |
+| 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 removed from templates
+- [ ] All inline JavaScript logic removed from templates (functions, fetch calls, state management)
 - [ ] All features work with TypeScript
 - [ ] TypeScript compilation passes with strict mode
-- [ ] Progressive enhancement maintained (pages work without JS)
+- [ ] No regression in existing progressive enhancement behavior (HTMX forms unchanged)
 - [ ] No type `any` (except for legacy API responses)
-- [ ] Event delegation replaces inline handlers
-- [ ] Build process integrated into npm scripts
+- [ ] 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
-3. **Begin Phase 2**: Create core utility modules
+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
+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
 
 ---
 
@@ -857,13 +1509,11 @@ git checkout backup-before-collections -- templates/collections.templ
 </script>
 ```
 
-### After: TypeScript Module + Event Delegation
+### After: TypeScript Module (Browser Globals)
 
 **TypeScript Module:**
 ```typescript
-// web/ts/features/collections/rules.ts
-import { apiClient } from '../../core/api.js';
-import { escapeHtml } from '../../core/dom.js';
+// web/src/collections.ts
 
 interface Rule {
     id: string;
@@ -872,21 +1522,15 @@ interface Rule {
     value: string;
 }
 
-function renderRules(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 data-action="delete-rule" data-rule-id="${rule.id}">Delete</button>
-        </div>
-    `).join('');
+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 apiClient.get(`/collections/${collectionId}/rules`);
+        const response = await (window as any).api.get(`/collections/${collectionId}/rules`);
 
         if (!response.ok) {
             throw new Error('Failed to load rules');
@@ -896,7 +1540,35 @@ async function loadRules(collectionId: string): Promise<void> {
         renderRules(rules);
     } catch (error) {
         console.error('Load rules error:', error);
-        window.showToast.error('Failed to load rules');
+        (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');
     }
 }
 
@@ -906,45 +1578,41 @@ async function deleteRule(collectionId: string, ruleId: string): Promise<void> {
     }
 
     try {
-        const response = await apiClient.delete(`/collections/${collectionId}/rules/${ruleId}`);
+        const response = await (window as any).api.delete(`/collections/${collectionId}/rules/${ruleId}`);
 
         if (!response.ok) {
             throw new Error('Failed to delete rule');
         }
 
-        window.showToast.success('Rule deleted');
+        (window as any).showToast.success('Rule deleted');
 
-        // Remove from DOM
         const ruleElement = document.querySelector(`[data-rule-id="${ruleId}"]`);
         ruleElement?.remove();
     } catch (error) {
         console.error('Delete rule error:', error);
-        window.showToast.error('Failed to delete rule');
+        (window as any).showToast.error('Failed to delete rule');
     }
 }
 
-// Event delegation for delete buttons
-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;
-        const collectionId = deleteBtn.dataset.collectionId;
-
-        if (ruleId && collectionId) {
-            deleteRule(collectionId, ruleId);
-        }
-    }
-});
+// Export to window for HTML access
+(window as any).loadRules = loadRules;
+(window as any).deleteRule = deleteRule;
 
 // Initialize on page load
-document.addEventListener('DOMContentLoaded', () => {
+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:**
@@ -954,9 +1622,9 @@ document.addEventListener('DOMContentLoaded', () => {
 <html>
 <head>
     <script src="/static/htmx.min.js"></script>
-    <script src="/static/core/toast.js"></script>
-    <script src="/static/core/api.js"></script>
-    <script src="/static/features/collections/rules.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">
@@ -964,9 +1632,7 @@ document.addEventListener('DOMContentLoaded', () => {
         { range .Rules }
         <div class="rule-item" data-rule-id="{ .ID }">
             <span>{ .Field }</span>
-            <button data-action="delete-rule"
-                    data-rule-id="{ .ID }"
-                    data-collection-id="{ collection.ID }">
+            <button onclick="window.deleteRule('{collection.ID}', '{.ID}')">
                 Delete
             </button>
         </div>
@@ -977,16 +1643,24 @@ document.addEventListener('DOMContentLoaded', () => {
 ```
 
 **Benefits:**
-- ✅ No inline JavaScript
-- ✅ Event delegation (one listener)
-- ✅ Type-safe API calls
-- ✅ Better error handling
-- ✅ Reusable module
+- ✅ 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*
+*Architecture: Hybrid SSR + TypeScript CRUD (Browser Globals, No ES Modules)*