npm package: @kosmas10/html-app-loader
Description: Universal Stage 2 loader for HTML-based applications - dynamically loads single-file HTML apps from npm/CDN
Author: Kosmas Karadimitriou
Latest version: 1.0.6

# Universal HTML Application Loader (Stage 2)

**Version:** 1.0.6  
**Package:** `@kosmas10/html-app-loader`

## Overview

This is a **universal Stage 2 loader** for single-file HTML applications distributed via npm. It's part of a 3-stage loading architecture designed for maximum reliability and flexibility:

- **Stage 1 (Bootstrap)**: Ultra-minimal HTML file that users install locally - never changes
- **Stage 2 (This Package)**: Universal loader that handles complex HTML app loading - can be updated via npm
- **Stage 3 (Application)**: Any HTML application (Chat & Verify, Folder Analyzer, etc.) - updates frequently

## Purpose

This loader is **completely generic** and can load **any** single-file HTML application from npm, including:

- `@kosmas10/chat-and-verify` - Document chat with AI verification
- `@kosmas10/folder-llm-analyzer` - Batch LLM analysis tool
- `@kosmas10/portal` - Main launcher app
- Any other single-file HTML app you create

## Key Features

- **Universal**: Works with any HTML application, not tied to a specific app
- **Smart Defaults**: Automatically infers the HTML filename from package name
- **Flexible**: Supports both npm packages and direct URLs
- **Robust**: Handles external dependencies, styles, and scripts
- **Debuggable**: Comprehensive console logging
- **Updatable**: Can be improved via npm without user action

## Usage

### Basic Usage (npm package)

```
?app=@kosmas10/chat-and-verify
```

The loader will automatically:
1. Infer the file is `chat-and-verify.html` (from package name)
2. Load from: `https://cdn.jsdelivr.net/npm/@kosmas10/chat-and-verify@latest/chat-and-verify.html`

### Specify Custom File

```
?app=@kosmas10/my-package&appFile=custom.html
```

### Pin Specific Version

```
?app=@kosmas10/chat-and-verify&appVersion=1.2.3
```

### Local Testing

```
?appUrl=http://localhost:8889/path/to/app.html
```

### Complete Example

```html
<!-- Stage 1 Bootstrap -->
<script>
    var loaderUrl = 'https://cdn.jsdelivr.net/npm/@kosmas10/html-app-loader@latest/loader.js?app=@kosmas10/chat-and-verify';
    // Load the universal loader with the target app specified
</script>
```

## URL Parameters

| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
| `app` | Yes* | npm package name | `@kosmas10/chat-and-verify` |
| `appFile` | No | HTML filename (auto-inferred if not provided) | `custom.html` |
| `appVersion` | No | Package version (defaults to `latest`) | `1.2.3` |
| `appUrl` | Yes* | Direct URL for local testing | `http://localhost:8889/app.html` |

\* Either `app` or `appUrl` must be provided

## How It Works

1. **Parse Parameters**: Reads URL parameters to determine what to load
2. **Fetch HTML**: Downloads the HTML application from npm/CDN or direct URL
3. **Parse Document**: Uses DOMParser to extract head and body content
4. **Inject Styles**: Copies all `<style>` and `<link>` tags to document head
5. **Load Dependencies**: Loads external scripts (libraries) and waits for them
6. **Replace Content**: Replaces the body with the application content
7. **Execute Scripts**: Runs inline scripts with `DOMContentLoaded` interception
8. **Initialize**: The application initializes as if loaded normally

## Smart Filename Inference

The loader automatically infers the HTML filename from the package name:

| Package Name | Inferred Filename |
|--------------|-------------------|
| `@kosmas10/chat-and-verify` | `chat-and-verify.html` |
| `@kosmas10/folder-llm-analyzer` | `folder-llm-analyzer.html` |
| `@kosmas10/portal` | `portal.html` |
| `my-app` | `my-app.html` |

You can override this with the `appFile` parameter if needed.

## DOMContentLoaded Interception

The key innovation is intercepting `addEventListener('DOMContentLoaded', ...)` calls:

```javascript
// When the app tries to add a DOMContentLoaded listener:
window.addEventListener('DOMContentLoaded', function() {
    initializeApp();
});

// The loader intercepts it and executes immediately:
// (because DOM is already loaded at this point)
initializeApp();
```

This allows applications written for normal page loads to work seamlessly when dynamically loaded.

## Error Handling

If loading fails, the loader displays a user-friendly error message with:
- The specific error that occurred
- Package and version information (or URL)
- Possible causes and solutions
- Loader version for debugging

## Creating Bootstrap Files for Different Apps

### Chat & Verify Bootstrap

```html
<script>
    var loaderUrl = 'https://cdn.jsdelivr.net/npm/@kosmas10/html-app-loader@latest/loader.js?app=@kosmas10/chat-and-verify';
    // ... bootstrap code
</script>
```

### Folder Analyzer Bootstrap

```html
<script>
    var loaderUrl = 'https://cdn.jsdelivr.net/npm/@kosmas10/html-app-loader@latest/loader.js?app=@kosmas10/folder-llm-analyzer';
    // ... bootstrap code
</script>
```

### Portal Bootstrap

```html
<script>
    var loaderUrl = 'https://cdn.jsdelivr.net/npm/@kosmas10/html-app-loader@latest/loader.js?app=@kosmas10/portal';
    // ... bootstrap code
</script>
```

## Version History

### 1.0.6 (Current)
- Removed all non-error console output to prevent console popups during normal operation
- Cleaner console output - only shows errors when something goes wrong

### 1.0.5
- **Improved @latest handling**: Resolves `@latest` to specific version numbers by fetching package.json first
- Avoids CDN cache issues by using specific version numbers instead of `@latest` tag
- Fetches version from `package.json` with cache buster to ensure fresh data
- Falls back to `@latest` if version fetch fails for backward compatibility

### 1.0.4
- Bug fixes and improvements

### 1.0.3
- Bug fixes and improvements

### 1.0.2
- Bug fixes and improvements

### 1.0.1
- Bug fixes and improvements

### 1.0.0 (Initial Release)
- Universal HTML application loading from npm/CDN
- Smart filename inference from package name
- Style and script injection
- External dependency loading
- DOMContentLoaded interception
- Comprehensive error handling
- Support for both npm packages and direct URLs

## Architecture Benefits

✅ **Single Loader**: One loader package serves all your HTML apps  
✅ **Automatic Updates**: Fix bugs once, all apps benefit  
✅ **Consistent Behavior**: All apps load the same way  
✅ **Easy Maintenance**: Update one package instead of many  
✅ **Flexible**: Works with any single-file HTML app

## License

MIT License - See LICENSE file for details

## Support

For issues or questions, please visit:
https://github.com/kosmas10/ai-chat-extensions/issues

## Related Packages

This loader can load any of these packages:
- [@kosmas10/chat-and-verify](https://www.npmjs.com/package/@kosmas10/chat-and-verify)
- [@kosmas10/folder-llm-analyzer](https://www.npmjs.com/package/@kosmas10/folder-llm-analyzer)
- [@kosmas10/portal](https://www.npmjs.com/package/@kosmas10/portal)
- Any other single-file HTML app you create!