baremetal.js 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# BareMetal.js
+
+A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.
+
+---
+
+## Overview
+
+BareMetal.js is designed to bring Single Page Application (SPA) functionality to vanilla HTML/JS projects without the overhead of heavy frameworks or build steps. It intercepts navigations to provide instantaneous page transitions while giving developers precise control over module lifecycles and state.
+
+## Key Features
+
+- **Hover Pre-fetching (0ms Latency):** BareMetal anticipates user actions by fetching HTML in the background when a user hovers over an internal link, resulting in instant transitions upon click.
+- **Smart Module Keep-Alive:** Share state and complex UI modules across page transitions without destroying them. Native `<video>` and `<audio>` tags can be preserved and re-injected into the new DOM seamlessly.
+- **Scroll Memory & Programmatic Back:** Maintains a persistent history stack, restoring your exact scroll depth instantly when navigating backward.
+- **Reactive State Management:** Includes a built-in publish/subscribe Signals pattern, preventing race conditions and keeping your UI synced.
+- **Custom Page Transitions:** Build and integrate your own loading animations and transition effects hooking into the routing lifecycle.
+- **Error Boundaries:** Handles navigation failures gracefully with configurable fallback UIs.
+- **Auto-Wrap Module Loader:** Can automatically wrap simple scripts into conformant lifecycle modules to prevent errors.
+
+## Quick Start
+
+### Installation
+
+No installation required! Just clone the repository or copy the `src` folder into your project.
+
+### Running the Demo
+
+To test the demo and advanced features across page navigation, serve the directory via any local static server.
+
+Using `npx`:
+
+```bash
+npx serve .
+```
+
+Then visit: `http://localhost:3000/demo/page1.html`
+
+## Project Structure
+
+```
+├── src/                        # The BareMetal Engine Source Code
+│   ├── index.js
+│   ├── router.js
+│   ├── loader.js
+│   ├── state.js
+│   └── transition.js
+├── demo/                       # Demo Application
+│   ├── page1.html
+│   ├── page2.html
+│   ├── page3_normal.html
+│   ├── main.js
+│   └── assets/                 # Page-specific widgets and media
+├── docs/
+│   └── api.md                  # Comprehensive API Reference
+```
+
+## Usage
+
+### 1. Engine Initialization
+
+Initialize the engine in your main entry file (e.g., `main.js`) to toggle advanced features:
+
+```javascript
+import { BareMetal } from '../src/index.js';
+
+BareMetal.init({
+  debug: false,
+  keepAliveSameModules: true,
+  autoWrap: false,
+  hoverPrefetch: true,       // 0ms Latency Pre-fetching
+  transition: {
+    enabled: true,
+    simulatedDelay: 0
+  }
+});
+```
+
+### 2. Module Definition
+
+A BareMetal module must export a `mount` function. The engine injects the `state` manager into `mount`. It must return an object containing a `destroy()` function to prevent memory leaks when navigating away.
+
+```javascript
+// my-widget.js
+export function mount({ state }) {
+  const btn = document.getElementById('my-btn');
+  btn.onclick = () => alert('Clicked!');
+  
+  // Return cleanup methods
+  return {
+    destroy: () => {
+      btn.onclick = null;
+    }
+  };
+}
+```
+
+### 3. Page Configuration
+
+On your HTML pages, instruct BareMetal on which modules are required for that specific page using the inline `loader()`.
+
+```html
+<script type="module">
+  import { loader } from '../src/index.js';
+  loader({
+    sharedSidebar: "/demo/assets/js/sidebar.js",
+    dashboard: "/demo/assets/js/dashboard.js"
+  });
+</script>
+```
+
+## Configuration Reference
+
+The `BareMetal.init(config)` method accepts the following configuration object:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | boolean | `false` | Enable verbose console logs. |
+| `keepAliveSameModules` | boolean | `true` | Prevent destruction of modules shared between routes. |
+| `autoWrap` | boolean | `true` | Automatically wrap modules that do not export a `mount` function. |
+| `hoverPrefetch` | boolean | `false` | Enable 0ms latency pre-fetching on link hover. |
+| `transition.enabled` | boolean | `false` | Enable the protected transition module. |
+| `transition.module` | string | `null` | Path to a custom transition module. |
+| `transition.simulatedDelay` | number | `0` | Artificial delay (ms) for testing transitions. |
+
+## API Reference
+
+For detailed documentation on the Router, State Manager, and Events, please see the [API Documentation](docs/api.md).
+
+## Custom Transitions
+
+You can replace the default progress bar and fade overlay by pointing `config.transition.module` to your own JavaScript file. A custom transition is a standard BareMetal module that listens to routing events (`ROUTE_START`, `ROUTE_PROGRESS`, `ROUTE_END`, `ROUTE_ERROR`). Ensure your transition UI is injected into an element with `id="baremetal-transition-root"`. 
+
+See the API Documentation for a complete example.
+
+## Browser Support
+
+BareMetal.js uses ES Modules natively in the browser. It supports all modern browsers (Chrome, Firefox, Safari, Edge) without any build step required.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more details on how to get started.
+
+## Code of Conduct
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
+
+## Security
+
+If you discover a security vulnerability, please refer to our [Security Policy](SECURITY.md).
+
+## License
+
+This project is licensed under the [GNU General Public License v3.0](LICENSE).

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, only the latest version of BareMetal.js is supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+Instead, please report them to the project maintainers via email at coc@dkydivyansh.com.
+
+You should receive a response within 48 hours. If for some reason you do not, please follow up via email to ensure we received your message.

package/demo/assets/js/media_player.js

@@ -0,0 +1,9 @@
+export function mount({ state }) {
+
+
+  return {
+    destroy: () => {
+
+    }
+  };
+}

package/demo/assets/js/page1_specific.js

@@ -0,0 +1,23 @@
+export function mount() {
+  
+  let timer;
+  let count = 0;
+  
+  const container = document.getElementById('page1-widget');
+  if (container) {
+    const display = document.createElement('p');
+    display.innerText = `Active for 0 seconds`;
+    container.appendChild(display);
+    
+    timer = setInterval(() => {
+      count++;
+      display.innerText = `Active for ${count} seconds`;
+    }, 1000);
+  }
+
+  return {
+    destroy: () => {
+      clearInterval(timer);
+    }
+  };
+}

package/demo/assets/js/page2_specific.js

@@ -0,0 +1,15 @@
+export function mount({ state }) {
+  const container = document.getElementById('page2-widget');
+  if (container) {
+    const btn = document.createElement('button');
+    btn.innerText = "Click Me";
+    btn.onclick = () => alert("Hello from Page 2 specific module!");
+    container.appendChild(btn);
+  }
+
+  return {
+    destroy: () => {
+      // Cleanup if needed
+    }
+  };
+}

package/demo/assets/js/shared.js

@@ -0,0 +1,56 @@
+export function mount({ state }) {
+
+
+  // Initialize state if not exists
+  state.init('transCount', 0);
+
+  // Re-attach UI to state
+  const btn = document.getElementById('btn-translate');
+  const display = document.getElementById('trans-count');
+
+  // We store the handler on the module level so we can remove it on destroy if needed
+  // But wait, if this module is kept alive across page transitions where the DOM body is swapped,
+  // the old DOM elements are removed and replaced by new identical ones from the fetch!
+  // So a keep-alive module must re-bind its DOM elements whenever the DOM changes.
+  
+  // To handle the SPA HTML-swap paradigm:
+  // When a module is kept alive, its `mount` is NOT called again.
+  // Instead, the framework should either preserve the exact DOM elements during the swap,
+  // OR the module needs an `update()` lifecycle method.
+  
+  // For this simple demo, let's assume the router replaces the whole body.
+  // Thus, we need a way to re-bind. We can listen to a global event 'PAGE_CHANGED'.
+  
+  const bindUI = () => {
+    const btn = document.getElementById('btn-translate');
+    const display = document.getElementById('trans-count');
+    
+    if (btn) {
+      // Avoid duplicate listeners
+      btn.onclick = () => {
+        const current = state.get('transCount');
+        state.update('transCount', current + 1);
+      };
+    }
+    
+    // Subscribe to state to update UI
+    // We use a unique listener to update whatever the current DOM element is
+    state.subscribe('transCount', (val) => {
+      const currentDisplay = document.getElementById('trans-count');
+      if (currentDisplay) currentDisplay.innerText = val;
+    });
+  };
+
+  bindUI();
+  
+  // Listen for route changes to re-bind UI since DOM body is swapped
+  state.on('DOM_SWAPPED', bindUI);
+
+  // Return destroy method
+  return {
+    destroy: () => {
+
+      state.off('DOM_SWAPPED', bindUI);
+    }
+  };
+}

package/demo/assets/js/sidebar.js

@@ -0,0 +1,49 @@
+export function mount({ state }) {
+
+
+  // Initialize state (true = expanded, false = collapsed)
+  state.init('sidebarExpanded', true);
+
+  const bindUI = () => {
+    const sidebar = document.getElementById('sidebar');
+    const toggleBtn = document.getElementById('sidebar-toggle');
+    const content = document.getElementById('main-content');
+
+    if (!sidebar || !toggleBtn || !content) return;
+
+    // Remove old listeners just in case
+    toggleBtn.onclick = null;
+    
+    toggleBtn.onclick = () => {
+      const isExpanded = state.get('sidebarExpanded');
+      state.update('sidebarExpanded', !isExpanded);
+    };
+
+    // Make sure we update the DOM when the state changes
+    state.subscribe('sidebarExpanded', (expanded) => {
+      const el = document.getElementById('sidebar');
+      const mainEl = document.getElementById('main-content');
+      if (el && mainEl) {
+        if (expanded) {
+          el.style.width = '250px';
+          mainEl.style.marginLeft = '250px';
+        } else {
+          el.style.width = '60px';
+          mainEl.style.marginLeft = '60px';
+        }
+      }
+    });
+  };
+
+  bindUI();
+  
+  // Rebind UI when DOM is swapped by Router
+  state.on('DOM_SWAPPED', bindUI);
+
+  return {
+    destroy: () => {
+
+      state.off('DOM_SWAPPED', bindUI);
+    }
+  };
+}

package/demo/main.js

@@ -0,0 +1,18 @@
+import { BareMetal } from '../src/index.js';
+
+// Initialize the BareMetal engine with our desired config
+BareMetal.init({
+  debug: false,
+  keepAliveSameModules: true,
+  autoWrap: false,
+  hoverPrefetch: false,
+  showErrorNotification: false,
+  transition: {
+    enabled: true,
+    simulatedDelay: 500 // Adds a half-second artificial delay to see the progress bar in local dev
+  }
+});
+
+// For demonstration purposes, we will expose state to the window 
+// so we can see the reactive updates in action via console if desired.
+window.appState = BareMetal.state;

package/demo/page1.html

@@ -0,0 +1,139 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>BareMetal Demo - Page 1</title>
+  <style>
+    body {
+      font-family: sans-serif;
+      margin: 0;
+      background-color: #f5f5f5;
+    }
+
+    #sidebar {
+      position: fixed;
+      left: 0;
+      top: 0;
+      height: 100vh;
+      width: 250px;
+      background-color: #2c3e50;
+      color: white;
+      transition: width 0.3s ease;
+      overflow: hidden;
+      padding-top: 15px;
+      text-align: center;
+      z-index: 1000;
+    }
+
+    #sidebar-toggle {
+      background: none;
+      border: none;
+      color: white;
+      font-size: 24px;
+      cursor: pointer;
+      margin-bottom: 20px;
+    }
+
+    .nav-links a {
+      display: block;
+      padding: 15px;
+      color: #ecf0f1;
+      text-decoration: none;
+      font-weight: bold;
+      transition: background 0.2s;
+    }
+
+    .nav-links a:hover {
+      background-color: #34495e;
+    }
+
+    #main-content {
+      margin-left: 250px;
+      /* default expanded */
+      padding: 30px;
+      transition: margin-left 0.3s ease;
+    }
+
+    .widget {
+      border: 1px solid #ccc;
+      padding: 20px;
+      margin-bottom: 20px;
+      border-radius: 8px;
+      background: white;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+    }
+
+    .shared {
+      border-left: 4px solid #27ae60;
+    }
+  </style>
+</head>
+
+<body>
+
+  <div id="sidebar">
+    <button id="sidebar-toggle">&#9776;</button>
+    <div class="nav-links">
+      <a href="/demo/page1.html" data-link>Page 1</a>
+      <a href="/demo/page2.html" data-link>Page 2</a>
+      <a href="/demo/page3_normal.html">Page 3 (No SPA)</a>
+      <a href="https://example.com" target="_blank">External</a>
+    </div>
+  </div>
+
+  <div id="main-content">
+    <h1>Welcome to Page 1</h1>
+    <p>This page uses a shared Translation Checker module, a Sidebar, and a specific Page 1 module.</p>
+
+    <div id="shared-widget" class="widget shared">
+      <h3>Shared Translation Module</h3>
+      <p>Translation count: <span id="trans-count">0</span></p>
+      <button id="btn-translate">Simulate Translation</button>
+    </div>
+
+    <div id="page1-widget" class="widget">
+      <h3>Page 1 Specific Module</h3>
+      <p>This module only exists on Page 1 and will be destroyed when navigating away.</p>
+    </div>
+
+    <div class="widget" style="border-color: #e74c3c;">
+      <h3>Error Boundary Demo</h3>
+      <p>Click below to navigate to a page that doesn't exist.</p>
+      <a href="/does-not-exist.html"
+        style="display: inline-block; padding: 10px; background: #e74c3c; color: white; text-decoration: none; border-radius: 4px;">Trigger
+        404 Error</a>
+    </div>
+  </div>
+
+  <div id="media-container"
+    style="position: fixed; bottom: 20px; right: 20px; background: white; padding: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); z-index: 1000; border-radius: 8px; transition: all 0.5s ease;">
+    <h4 style="margin-top:0; margin-bottom: 10px;">Uninterrupted Native Media</h4>
+    <video id="demo-video" data-baremetal-preserve width="300" controls autoplay muted loop>
+      <source src="https://www.w3schools.com/html/mov_bbb.mp4" type="video/mp4">
+      Your browser does not support HTML video.
+    </video>
+    <br />
+    <audio id="demo-audio" data-baremetal-preserve controls style="width: 300px; margin-top: 10px;">
+      <source src="./assets/audio/darren_hirst-20-474737.mp3" type="audio/mpeg">
+      Your browser does not support the audio element.
+    </audio>
+  </div>
+
+  <!-- BareMetal Engine -->
+  <script type="module" src="./main.js"></script>
+
+  <!-- Page Configuration -->
+  <script type="module">
+    import { loader } from '../src/index.js';
+    loader({
+      sidebar: "/demo/assets/js/sidebar.js",
+      shared: "/demo/assets/js/shared.js",
+      page1: "/demo/assets/js/page1_specific.js",
+      mediaPlayer: "/demo/assets/js/media_player.js"
+    });
+  </script>
+
+</body>
+
+</html>

package/demo/page2.html

@@ -0,0 +1,132 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>BareMetal Demo - Page 2</title>
+  <style>
+    body {
+      font-family: sans-serif;
+      margin: 0;
+      background-color: #f5f5f5;
+    }
+
+    #sidebar {
+      position: fixed;
+      left: 0;
+      top: 0;
+      height: 100vh;
+      width: 250px;
+      background-color: #2c3e50;
+      color: white;
+      transition: width 0.3s ease;
+      overflow: hidden;
+      padding-top: 15px;
+      text-align: center;
+      z-index: 1000;
+    }
+
+    #sidebar-toggle {
+      background: none;
+      border: none;
+      color: white;
+      font-size: 24px;
+      cursor: pointer;
+      margin-bottom: 20px;
+    }
+
+    .nav-links a {
+      display: block;
+      padding: 15px;
+      color: #ecf0f1;
+      text-decoration: none;
+      font-weight: bold;
+      transition: background 0.2s;
+    }
+
+    .nav-links a:hover {
+      background-color: #34495e;
+    }
+
+    #main-content {
+      margin-left: 250px; /* default expanded */
+      padding: 30px;
+      transition: margin-left 0.3s ease;
+    }
+
+    .widget {
+      border: 1px solid #ccc;
+      padding: 20px;
+      margin-bottom: 20px;
+      border-radius: 8px;
+      background: white;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.05);
+    }
+
+    .shared {
+      border-left: 4px solid #27ae60;
+    }
+  </style>
+</head>
+
+<body>
+
+  <div id="sidebar">
+    <button id="sidebar-toggle">&#9776;</button>
+    <div class="nav-links">
+      <a href="/demo/page1.html" data-link>Page 1</a>
+      <a href="/demo/page2.html" data-link>Page 2</a>
+      <a href="/demo/page3_normal.html">Page 3 (No SPA)</a>
+      <a href="https://example.com" target="_blank">External</a>
+    </div>
+  </div>
+
+  <div id="main-content">
+    <h1>Welcome to Page 2</h1>
+    <p>This is a completely different page, but notice the sidebar and translation widget state are maintained perfectly!</p>
+
+    <div id="media-container" class="widget" style="background: #333; color: white; border-left: 4px solid #e74c3c; transition: all 0.5s ease;">
+      <h3 style="margin-top:0;">Deeply Nested &amp; Transformed!</h3>
+      <p>I am still embedded in the main content flow, but my container's text and CSS synced seamlessly!</p>
+      <video id="demo-video" data-baremetal-preserve width="100%" controls autoplay muted loop>
+        <source src="https://www.w3schools.com/html/mov_bbb.mp4" type="video/mp4">
+        Your browser does not support HTML video.
+      </video>
+      <br/>
+      <audio id="demo-audio" data-baremetal-preserve controls style="width: 100%; margin-top: 10px;">
+        <source src="./assets/audio/darren_hirst-20-474737.mp3" type="audio/mpeg">
+        Your browser does not support the audio element.
+      </audio>
+    </div>
+
+    <div id="shared-widget" class="widget shared">
+      <h3>Shared Translation Module</h3>
+      <p>Translation count: <span id="trans-count">0</span></p>
+      <button id="btn-translate">Simulate Translation</button>
+    </div>
+
+    <div id="page2-widget" class="widget">
+      <h3>Page 2 Specific Module</h3>
+      <p>This is a completely different module loaded dynamically.</p>
+    </div>
+  </div>
+
+  </div>
+
+  <!-- BareMetal Engine -->
+  <script type="module" src="./main.js"></script>
+
+  <!-- Page Configuration -->
+  <script type="module">
+    import { loader } from '../src/index.js';
+    loader({
+      sidebar: "/demo/assets/js/sidebar.js",
+      shared: "/demo/assets/js/shared.js",
+      page2: "/demo/assets/js/page2_specific.js",
+      mediaPlayer: "/demo/assets/js/media_player.js"
+    });
+  </script>
+
+</body>
+
+</html>

package/demo/page3_normal.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>BareMetal Demo - Normal Page</title>
+  <style>
+    body { font-family: sans-serif; padding: 20px; background-color: #f9f9f9; }
+    .nav { margin-bottom: 20px; padding: 10px; background: #eee; }
+    .nav a { margin-right: 15px; text-decoration: none; color: blue; }
+  </style>
+</head>
+<body>
+
+  <div class="nav">
+    <strong>Navigation:</strong>
+    <a href="/demo/page1.html">Back to Page 1</a>
+  </div>
+
+  <h1>Welcome to Page 3 (Normal Page)</h1>
+  <p>This page <strong>does not</strong> contain a BareMetal <code>loader({...})</code> configuration.</p>
+  <p>Because of this, the BareMetal Router detected it and performed a standard browser navigation (hard reload) to get here.</p>
+
+  <p>Notice that your translation counter from Page 1 and 2 has been reset because we left the SPA environment!</p>
+
+</body>
+</html>