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

<!-- 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:

// 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

<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

<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

<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
• @kosmas10/folder-llm-analyzer
• @kosmas10/portal
• Any other single-file HTML app you create!