-```
+### Step 3: Replace (window as any).docsData with direct import
+**Location**: Line 73
+**Current** (lines 70-76):
```typescript
-// In TypeScript
-const container = document.getElementById('search-container')!;
-const searchIndex = JSON.parse(container.dataset.searchIndex!);
-const docsData = JSON.parse(container.dataset.docsData!);
+ .map((result: { ref: string }) => {
+ const doc = (window as any).docsData?.[result.ref];
+ if (!doc) return "";
```
-**Option C: Loader module** (best, most maintainable)
-
+**Change to**:
```typescript
-// web/src/search-data.ts (NEW FILE)
-let lunrIndex: any = null;
-let docsData: Record
= {};
-
-export async function loadSearchData() {
- const response = await fetch('/docs/search-index.json');
- const data = await response.json();
-
- // Build lunr index
- lunrIndex = lunr(function() {
- this.use(lunr.flex);
- this.ref('id');
- this.field('title', {boost: 10});
- this.field('content', {boost: 1});
- data.forEach(doc => this.add(doc));
- });
-
- docsData = data;
-}
-
-export { lunrIndex, docsData };
+ .map((result: { ref: string }) => {
+ const doc = docs[result.ref];
+ if (!doc) return "";
```
-```typescript
-// web/src/docs.ts
-import { lunrIndex, docsData, loadSearchData } from './search-data';
+### Step 4: Replace window export with Alpine global
+**Location**: Line 99
-document.addEventListener('DOMContentLoaded', async () => {
- await loadSearchData();
+**Current** (lines 98-99):
+```typescript
+document.addEventListener("DOMContentLoaded", () => {
initializeDocsSearch();
});
-function performDocsSearch(query: string) {
- // Use imported data, no globals
- const idx = lunrIndex;
- const doc = docsData[result.ref];
-}
+(window as any).toggleSidebar = toggleSidebar;
```
-#### Type 3: Function Exports for HTML (Should use event listeners)
-
-**Example**: `(window as any).toggleSidebar = toggleSidebar;`
-
-**Why**: Template uses `onclick="toggleSidebar()"`
-
-**Fix**: Replace `onclick` attributes with `addEventListener`
-
+**Change to**:
```typescript
-// Remove: (window as any).toggleSidebar = toggleSidebar;
-
-// Add event listener
-document.addEventListener('click', (e) => {
- const button = e.target.closest('[data-action="toggle-sidebar"]');
- if (button) toggleSidebar();
+document.addEventListener("DOMContentLoaded", () => {
+ initializeDocsSearch();
+
+ // Register with Alpine globally
+ if (typeof window.Alpine !== 'undefined') {
+ window.Alpine.effect(() => {
+ window.Alpine.global('docs', {
+ toggleSidebar
+ });
+ });
+ }
});
```
-```html
-
-
-```
-
-### Recommended Approach
-
-**Quick fix** (Types 1 + 2A):
-1. Import libraries directly (`import lunr from 'lunr'`)
-2. Add proper TypeScript declarations for SSR globals
-3. Keep function exports for now (can fix later)
-
-**Best practice** (All types):
-1. Import libraries directly
-2. Use Option C (loader module) for SSR data
-3. Replace all `onclick` with `addEventListener`
+**Why Alpine.global()**: Makes `toggleSidebar()` available to Alpine templates via `@click="docs.toggleSidebar()"`
---
-## Import Strategy
+## Phase 2: Migrate TypeScript Files to Alpine Registration
-### Principle: Import Where Used
+**Approach**: Replace `(window as any)` exports with Alpine.js global registration
-**❌ DON'T**: Import everything in main.ts
+### Architecture Note: Alpine.js for Client-Side State
+**Why Alpine over window exports**:
+- Modern, reactive framework (already in package.json)
+- Clean template syntax: `@click` instead of `onclick="window.func()"`
+- Built-in state management: `x-data`, `x-show`, `x-model`
+- Works with SSR (progressive enhancement)
+- No global namespace pollution
+
+**Hybrid approach**:
+- **Alpine**: Client-side state (modals, dropdowns, theme, forms)
+- **HTMX**: Server calls (already using for form submissions)
+
+### Step 1: Create Alpine Registration Helper
+
+**New file**: `web/src/alpine.ts`
```typescript
-// main.ts - DON'T DO THIS
-import './collections';
-import './docs';
-import 'htmx.org';
-import 'alpinejs';
-import 'lunr';
-import 'highlight.js/lib/common';
-// ... 29 more imports
-```
-
-This overwhelms main.ts and makes it hard to see what each file needs.
-
-**✅ DO**: Import in files that use it
-
-```typescript
-// main.ts - Keep simple!
-import './collections';
-import './toast';
-import './theme';
-// ... all page modules (29 total)
-```
-
-```typescript
-// web/src/collections.ts - Import what YOU use
import Alpine from 'alpinejs';
-// Use Alpine for checkbox state
-document.addEventListener('alpine:init', () => {
- Alpine.data('bookSelection', () => ({
- selectedBooks: new Set(),
- toggle(id: string) { /* ... */ }
- }));
+// Initialize Alpine
+window.Alpine = Alpine;
+Alpine.start();
+
+// Re-export Alpine for other modules to use
+export { Alpine };
+```
+
+**Add to main.ts**: Append this line at the end of `web/src/main.ts`:
+
+```typescript
+import './alpine';
+```
+
+### Step 2: Update TypeScript Files to Register with Alpine
+
+#### Pattern: Object Registration (Multiple Related Functions)
+
+**Example**: `web/src/toast.ts`
+
+**Current** (lines 229-236):
+```typescript
+(window as any).showToast = {
+ error: (message: string, duration?: number) =>
+ showToast(message, "error", duration),
+ success: (message: string, duration?: number) =>
+ showToast(message, "success", duration),
+ info: (message: string, duration?: number) =>
+ showToast(message, "info", duration),
+};
+```
+
+**Change to**:
+```typescript
+import { Alpine } from './alpine';
+
+// Register toast API with Alpine
+Alpine.global('showToast', {
+ error: (message: string, duration?: number) =>
+ showToast(message, "error", duration),
+ success: (message: string, duration?: number) =>
+ showToast(message, "success", duration),
+ info: (message: string, duration?: number) =>
+ showToast(message, "info", duration),
});
```
-```typescript
-// web/src/docs.ts - Import what YOU use
-import lunr from 'lunr';
-import hljs from 'highlight.js/lib/common';
-import 'highlight.js/lib/languages/bash';
-import 'highlight.js/lib/languages/go';
-import 'highlight.js/lib/languages/sql';
-import 'highlight.js/lib/languages/http';
-import 'highlight.js/lib/languages/json';
+**Usage in templates**:
+```html
+
+
+
-// Use lunr for search
-const idx = lunr(function() { /* ... */ });
-
-// Make hljs available globally (needed for docs template)
-if (typeof window !== 'undefined') {
- (window as any).hljs = hljs;
-}
+
+
+
```
-### ESBuild Handles the Rest
+#### Pattern: Namespace Registration (Grouping Related Functions)
-When you run `esbuild web/src/main.ts --bundle`:
+**Example**: `web/src/api.ts`
-1. Starts at `main.ts`
-2. Follows all imports through all modules
-3. Collects all dependencies
-4. Bundles everything into `main.js`
-5. Handles deduplication automatically
-6. Tree-shakes unused code
+**Current** (lines 90-99):
+```typescript
+(window as any).api = {
+ get: apiGet,
+ post: apiPost,
+ put: apiPut,
+ delete: apiDelete,
+ patch: apiPatch,
+ handleResponse,
+ handleVoidResponse,
+ handleError,
+};
+```
-**Result**: Single `main.js` with everything you need, nothing you don't.
+**Change to**:
+```typescript
+import { Alpine } from './alpine';
+
+Alpine.global('api', {
+ get: apiGet,
+ post: apiPost,
+ put: apiPut,
+ delete: apiDelete,
+ patch: apiPatch,
+ handleResponse,
+ handleVoidResponse,
+ handleError,
+});
+```
+
+**Usage in templates**:
+```html
+
+
+
+
+
+```
+
+#### Pattern: Stateful Components (Dropdowns, Modals)
+
+**Example**: `web/src/header.ts` (theme dropdown)
+
+**Current approach**: Multiple window exports
+
+**New approach**: Create Alpine component with state
+
+**Add to `web/src/header.ts`**:
+```typescript
+import { Alpine } from './alpine';
+
+// Register theme dropdown component
+Alpine.data('themeDropdown', () => ({
+ open: false,
+
+ toggle() {
+ this.open = !this.open;
+ },
+
+ changeTheme(theme: string) {
+ changeThemeTo(theme); // Reuse existing function
+ this.open = false;
+ },
+
+ init() {
+ // Load saved theme on init
+ applyTheme(loadTheme());
+ }
+}));
+```
+
+**Usage in templates**:
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
-**3. All other templates** (25 files)
-- Replace all ``
+**Line 119** - Back button:
+```templ
+
+