baremetal.js 1.0.1 → 1.2.1

package/docs/api.md

@@ -7,41 +7,25 @@ BareMetal exports its core engine as a global configuration object. Here are the
 ### `BareMetal.init(config)`
 Initializes the engine, sets up the Router, and binds global configurations.
 
-**Parameters:**
-- `config.debug` *(boolean)*: Enable verbose console logs (default: `false`).
-- `config.keepAliveSameModules` *(boolean)*: If true, modules shared between routes are not destroyed during navigation (default: `true`).
-- `config.autoWrap` *(boolean)*: If true, modules that do not export a `mount` function are automatically wrapped in a dynamic Blob URL to prevent syntax errors (default: `true`).
-- `config.transition` *(object)*: Configuration for the native page transition API.
-  - `config.transition.enabled` *(boolean)*: Enables the protected transition module.
-  - `config.transition.module` *(string)*: Optional path to a custom transition module (defaults to `/src/transition.js`).
-  - `config.transition.simulatedDelay` *(number)*: Optional artificial delay in milliseconds (useful for testing animations locally).
-  - `config.transition.useViewTransitions` *(boolean)*: Enables the native View Transitions API for smooth cross-fades during navigation (default: `false`).
-- `config.offline` *(object)*: Configuration for offline Progressive Web App (PWA) support.
-  - `config.offline.enabled` *(boolean)*: Enables Service Worker registration (default: `false`).
-  - `config.offline.version` *(string)*: Version identifier for the offline cache (e.g., `'1.0.0'`). Bump this to push updates to users.
-  - `config.offline.installType` *(string)*: `'auto'` (installs silently), `'consent'` (shows a popup), or `'custom'` (triggered manually via `BareMetal.offline.install()`).
-  - `config.offline.delay` *(number)*: Milliseconds to wait before auto-install or showing the consent popup.
-  - `config.offline.showInfo` *(boolean)*: If true, displays themed toast notifications at the bottom left during installation/updates.
-  - `config.offline.assets` *(string[])*: An array of URLs to strictly pre-cache upon installation.
+**Configuration Reference:**
+
+| 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. |
+| `persistState` | boolean | `false` | Automatically serialize `stateManager` to `sessionStorage` for F5 resilience. |
+| `virtualizeDom` | boolean | `false` | Inject the `Virtualizer` helper into module mount contexts. |
+| `showErrorNotification` | boolean | `false` | Enable floating error boundaries on navigation failures. |
+| `transition.enabled` | boolean | `false` | Enable the protected transition module. |
+| `transition.module` | string | `null` | Path to a custom transition module (defaults to `/src/transition.js`). |
+| `transition.simulatedDelay` | number | `0` | Artificial delay (ms) for testing transitions. |
+| `transition.useViewTransitions` | boolean | `false` | Enables the native View Transitions API for smooth cross-fades during navigation. |
 
 ---
 
-## 2. Offline Manager
-
-Accessible via `BareMetal.offline` when enabled.
-
-### `offline.install()`
-Manually triggers the background download of all resources specified in `config.offline.assets`.
-
-### `offline.update()`
-Triggers a background fetch to update the cached assets based on the current `config.offline.version`.
-
-### `offline.remove()`
-Unregisters the Service Worker and deletes all offline caches.
-
----
-
-## 3. Router Navigation
+## 2. Router Navigation
 
 ### `BareMetal.router.reload()`
 Executes a hard reload of the current SPA page by calling `window.location.reload()`. This is useful when you want to force the browser to wipe the entire SPA state and fetch fresh assets.
@@ -78,7 +62,7 @@ Listens for a Pub/Sub event.
 
 ---
 
-## 5. Writing Custom Page Transitions
+## 4. Writing Custom Page 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 just a standard BareMetal module that listens to routing events.
 
@@ -128,5 +112,3 @@ export function mount({ state }) {
   };
 }
 ```
-
-

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "baremetal.js",
-  "version": "1.0.1",
+  "version": "1.2.1",
   "description": "A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.",
   "main": "src/index.js",
   "type": "module",
+  "files": [
+    "src",
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/api.md",
+    "README.md",
+    "SECURITY.md"
+  ],
   "scripts": {
-    "test": "echo \"No tests written yet.\" && exit 0"
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -20,10 +31,16 @@
     "baremetal",
     "performance"
   ],
-  "author": "Divyansh",
+  "author": "dkydivyansh",
   "license": "GPL-3.0",
   "bugs": {
     "url": "https://github.com/dkydivyansh/BareMetal.js/issues"
   },
-  "homepage": "https://BareMetal.dkydivyansh.com"
+  "homepage": "https://BareMetal.dkydivyansh.com",
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.0",
+    "jsdom": "^29.1.1",
+    "rollup": "^4.62.0",
+    "vitest": "^4.1.9"
+  }
 }

package/src/index.js

@@ -1,12 +1,21 @@
+/**
+ * baremetal.js v1.2.1
+ * A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.
+ * (c) 2026 dkydivyansh
+ * Released under the GPL-3.0 License
+ */
+
 import { stateManager } from './state.js';
 import { Loader, loader } from './loader.js';
 import { Router } from './router.js';
+import { virtualize } from './virtualize.js';
 
 const BareMetal = {
   state: stateManager,
-  events: stateManager, // Aliased for backward compatibility with Pub/Sub mental model
+  events: stateManager,
   loader: loader,
   router: Router,
+  virtualize: virtualize,
 
   init(config = {}) {
     if (config.debug !== undefined) Loader.setConfig({ debug: config.debug });
@@ -16,7 +25,16 @@ const BareMetal = {
     if (config.hoverPrefetch !== undefined) Loader.setConfig({ hoverPrefetch: config.hoverPrefetch });
     if (config.showErrorNotification !== undefined) Loader.setConfig({ showErrorNotification: config.showErrorNotification });
 
-    // Initialize Router
+    if (config.persistState !== undefined) {
+      Loader.setConfig({ persistState: config.persistState });
+      if (config.persistState) {
+        window.__baremetal_persist_state = true;
+        stateManager.initPersistence();
+      }
+    }
+
+    if (config.virtualizeDom !== undefined) Loader.setConfig({ virtualizeDom: config.virtualizeDom });
+
     Router.init();
     Loader.log("Initialized BareMetal Engine with config:", config);
   }

package/src/loader.js

@@ -1,9 +1,16 @@
+/**
+ * baremetal.js v1.2.1
+ * A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.
+ * (c) 2026 dkydivyansh
+ * Released under the GPL-3.0 License
+ */
+
 import { stateManager } from './state.js';
 
 export const Loader = {
-  activeModules: {}, // { key: { path: "./dash.js", module: exportedModule } }
-  config: { keepAliveSameModules: true, debug: false, autoWrap: true, hoverPrefetch: false, showErrorNotification: false, transition: { enabled: false, simulatedDelay: 0, module: null, useViewTransitions: false } },
-  
+  activeModules: {},
+  config: { keepAliveSameModules: true, debug: false, autoWrap: true, hoverPrefetch: false, showErrorNotification: false, persistState: false, virtualizeDom: false, transition: { enabled: false, simulatedDelay: 0, module: null, useViewTransitions: false } },
+
   setConfig(globalConfig) {
     this.config = { ...this.config, ...globalConfig };
   },
@@ -12,11 +19,8 @@ export const Loader = {
     if (this.config.debug) console.log('[BareMetal Loader]', ...args);
   },
 
-  /**
-   * Prepares the transition by destroying obsolete modules and identifying new ones.
-   */
   async prepare(newConfig) {
-    // Auto-inject transition module if enabled
+
     if (this.config.transition && this.config.transition.enabled) {
       const transitionPath = this.config.transition.module || '/src/transition.js';
       newConfig['__baremetal_transition'] = transitionPath;
@@ -28,17 +32,17 @@ export const Loader = {
 
     for (const [key, mod] of Object.entries(this.activeModules)) {
       const isImmortal = key === '__baremetal_transition';
-      if ((this.config.keepAliveSameModules || isImmortal) && newConfig[key] === mod.path) {
-        // Keep alive
+      const newPath = typeof newConfig[key] === 'string' ? newConfig[key] : (newConfig[key] ? newConfig[key].path : null);
+      if ((this.config.keepAliveSameModules || isImmortal) && newPath === mod.path) {
+
         modulesToKeep[key] = mod;
         this.log(`Keep-Alive: ${key} (${mod.path})`);
       } else {
-        // Mark for destruction
+
         modulesToDestroy.push(mod);
       }
     }
 
-    // Destroy obsolete modules
     for (const mod of modulesToDestroy) {
       this.log(`Destroying module: ${mod.path}`);
       if (mod.module && typeof mod.module.destroy === 'function') {
@@ -50,83 +54,108 @@ export const Loader = {
       }
     }
 
-    // Determine what's new
     for (const [key, path] of Object.entries(newConfig)) {
       if (!modulesToKeep[key]) {
         modulesToLoad[key] = path;
       }
     }
 
-    // Temporarily update active modules to only the kept ones
     this.activeModules = modulesToKeep;
 
     return modulesToLoad;
   },
 
-  /**
-   * Loads the prepared modules. Called by Router after DOM swap.
-   */
   async loadPrepared(modulesToLoad) {
     const total = Object.keys(modulesToLoad).length;
     let loaded = 0;
 
-    const loadPromises = Object.entries(modulesToLoad).map(async ([key, path]) => {
-      this.log(`Importing module: ${path}`);
-      try {
-        const resolvedPath = new URL(path, document.baseURI).href;
-        const loadPath = this.config.debug ? `${resolvedPath}?t=${Date.now()}` : resolvedPath;
-        
-        let module;
-
-        if (this.config.autoWrap) {
-          // Fetch source to check if it needs auto-wrapping
-          const response = await fetch(loadPath);
-          if (!response.ok) throw new Error(`Failed to fetch ${loadPath}`);
-          const sourceText = await response.text();
-
-          const hasMount = /export\s+(function|const|let|var)\s+mount\b/.test(sourceText) || /export\s+\{.*?\bmount\b.*?\}/.test(sourceText);
-
-          if (!hasMount) {
-            console.warn(`[BareMetal] WARNING: Module ${path} does not explicitly export a mount() function. Auto-wrapping it...`);
-            
-            const wrappedSource = `
-              export async function mount(context) {
-                const { state } = context;
-                ${sourceText}
-              }
-            `;
-            
-            const blob = new Blob([wrappedSource], { type: 'application/javascript' });
-            const blobUrl = URL.createObjectURL(blob);
-            module = await import(blobUrl);
-            URL.revokeObjectURL(blobUrl);
+    const loadPromises = Object.entries(modulesToLoad).map(async ([key, modDef]) => {
+      const path = typeof modDef === 'string' ? modDef : modDef.path;
+      const lazySelector = typeof modDef === 'string' ? null : modDef.lazy;
+
+      this.log(`Preparing module: ${path}`);
+
+      const doImport = async () => {
+        try {
+          const resolvedPath = new URL(path, document.baseURI).href;
+          const loadPath = this.config.debug ? `${resolvedPath}?t=${Date.now()}` : resolvedPath;
+
+          let module;
+
+          if (this.config.autoWrap) {
+            const response = await fetch(loadPath);
+            if (!response.ok) throw new Error(`Failed to fetch ${loadPath}`);
+            const sourceText = await response.text();
+
+            const hasMount = /export\s+(function|const|let|var)\s+mount\b/.test(sourceText) || /export\s+\{.*?\bmount\b.*?\}/.test(sourceText);
+
+            if (!hasMount) {
+              console.warn(`[BareMetal] WARNING: Module ${path} does not explicitly export a mount() function. Auto-wrapping it...`);
+              const wrappedSource = `export async function mount(context) { const { state } = context; ${sourceText} }`;
+              const blob = new Blob([wrappedSource], { type: 'application/javascript' });
+              const blobUrl = URL.createObjectURL(blob);
+              module = await import(blobUrl);
+              URL.revokeObjectURL(blobUrl);
+            } else {
+              module = await import(loadPath);
+            }
           } else {
             module = await import(loadPath);
           }
-        } else {
-          // Auto-wrapping disabled, load natively
-          module = await import(loadPath);
+
+          if (typeof module.mount === 'function') {
+            this.log(`Mounting module: ${path}`);
+
+            const context = { state: stateManager };
+            if (this.config.virtualizeDom) {
+              const { virtualize } = await import('./virtualize.js');
+              context.virtualize = virtualize;
+            }
+
+            const instance = await module.mount(context);
+
+            this.activeModules[key] = {
+              path: path,
+              module: instance ? { destroy: instance.destroy } : module
+            };
+          } else {
+            console.error(`[BareMetal] Module ${path} failed to provide a mount function even after wrapping.`);
+          }
+        } catch (err) {
+          console.error(`Failed to load module: ${path}`, err);
         }
-        
-        if (typeof module.mount === 'function') {
-          this.log(`Mounting module: ${path}`);
-          const instance = await module.mount({ state: stateManager });
-          
-          this.activeModules[key] = {
-            path: path,
-            module: instance ? { destroy: instance.destroy } : module
-          };
+      };
+
+      if (lazySelector) {
+        const element = document.querySelector(lazySelector);
+        if (element && window.IntersectionObserver) {
+          this.log(`Deferred loading of module ${path} until ${lazySelector} is visible`);
+          const observer = new IntersectionObserver((entries) => {
+            if (entries[0].isIntersecting) {
+              observer.disconnect();
+              doImport();
+            }
+          });
+          observer.observe(element);
+
+          loaded++;
+          if (total > 0) {
+            const progress = 50 + (loaded / total) * 50;
+            stateManager.publish('ROUTE_PROGRESS', { url: window.location.pathname, progress });
+          }
+          return Promise.resolve();
         } else {
-          console.error(`[BareMetal] Module ${path} failed to provide a mount function even after wrapping.`);
-        }
-      } catch (err) {
-        console.error(`Failed to load module: ${path}`, err);
-      } finally {
-        loaded++;
-        if (total > 0) {
-          const progress = 50 + (loaded / total) * 50;
-          stateManager.publish('ROUTE_PROGRESS', { url: window.location.pathname, progress });
+
+          await doImport();
         }
+      } else {
+        await doImport();
+      }
+
+      loaded++;
+      if (total > 0) {
+        const progress = 50 + (loaded / total) * 50;
+        stateManager.publish('ROUTE_PROGRESS', { url: window.location.pathname, progress });
       }
     });
 
@@ -134,16 +163,12 @@ export const Loader = {
     stateManager.publish('ROUTE_END', { url: window.location.pathname });
   },
 
-  /**
-   * Legacy standalone load (used on first page load directly)
-   */
   async load(config) {
     const modulesToLoad = await this.prepare(config);
     await this.loadPrepared(modulesToLoad);
   }
 };
 
-// The user-facing API
 export function loader(config) {
   return Loader.load(config);
 }

package/src/router.js

@@ -1,3 +1,10 @@
+/**
+ * baremetal.js v1.2.1
+ * A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.
+ * (c) 2026 dkydivyansh
+ * Released under the GPL-3.0 License
+ */
+
 import { Loader } from './loader.js';
 import { stateManager } from './state.js';
 
@@ -5,33 +12,30 @@ export const Router = {
   htmlCache: {},
   scrollMemory: {},
   historyStack: [],
+  currentAbortController: null,
 
   init() {
     if ('scrollRestoration' in history) {
       history.scrollRestoration = 'manual';
     }
     window.addEventListener('popstate', this.handleRoute.bind(this));
-    
-    // Intercept all link clicks
+
     document.body.addEventListener('click', e => {
-      // Find closest anchor tag
+
       const anchor = e.target.closest('a');
       if (!anchor) return;
 
-      // Ignore external domains, target="_blank", noreferrer, or downloads
       if (
-        anchor.origin !== window.location.origin || 
+        anchor.origin !== window.location.origin ||
         anchor.target === '_blank' ||
         (anchor.rel && anchor.rel.includes('noreferrer')) ||
         anchor.hasAttribute('download')
       ) {
-        return; // Let browser handle it naturally
+        return;
       }
 
-      // Intercept same-origin internal links
       e.preventDefault();
-      
-      // Save current state before navigating away
+
       this.historyStack.push(window.location.pathname);
       this.scrollMemory[window.location.pathname] = window.scrollY;
 
@@ -39,18 +43,17 @@ export const Router = {
       this.handleRoute();
     });
 
-    // Hover Pre-fetching
     document.body.addEventListener('mouseover', e => {
       if (!Loader.config.hoverPrefetch) return;
       const anchor = e.target.closest('a');
       if (!anchor) return;
       if (
-        anchor.origin === window.location.origin && 
-        anchor.target !== '_blank' && 
+        anchor.origin === window.location.origin &&
+        anchor.target !== '_blank' &&
         !anchor.hasAttribute('download') &&
         !this.htmlCache[anchor.href]
       ) {
-        this.htmlCache[anchor.href] = 'fetching'; // Prevent duplicate fetches
+        this.htmlCache[anchor.href] = 'fetching';
         fetch(anchor.href)
           .then(res => {
              if (res.ok) return res.text();
@@ -63,13 +66,13 @@ export const Router = {
   },
 
   back() {
-    // Custom programmatic back button
+
     if (this.historyStack.length > 0) {
       const prevUrl = this.historyStack.pop();
       history.pushState(null, '', prevUrl);
       this.handleRoute();
     } else {
-      history.back(); // Fallback to browser's native back
+      history.back();
     }
   },
 
@@ -77,7 +80,14 @@ export const Router = {
     window.location.reload();
   },
 
-  async handleRoute() {
+  async handleRoute(e) {
+
+    if (this.currentAbortController) {
+      this.currentAbortController.abort();
+    }
+    this.currentAbortController = new AbortController();
+    const signal = this.currentAbortController.signal;
+
     const url = window.location.pathname;
     try {
       Loader.log(`Navigating to ${url}`);
@@ -92,31 +102,30 @@ export const Router = {
 
       let htmlText;
       const fullUrl = new URL(url, document.baseURI).href;
-      
+
       if (Loader.config.hoverPrefetch && this.htmlCache[fullUrl] && this.htmlCache[fullUrl] !== 'fetching') {
         htmlText = this.htmlCache[fullUrl];
         Loader.log(`Used pre-fetched cache for ${url}`);
       } else {
-        const response = await fetch(url);
+        const response = await fetch(url, { signal });
         if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
         htmlText = await response.text();
       }
-      
+
       stateManager.publish('ROUTE_PROGRESS', { url, progress: 50 });
 
       const parser = new DOMParser();
       const doc = parser.parseFromString(htmlText, 'text/html');
-      
-      // 1. Extract Config
+
       let config = null;
       const scriptTags = doc.querySelectorAll('script');
       for (const script of scriptTags) {
         if (script.textContent.includes('loader(')) {
-          // Extract the JSON-like object from loader({...})
+
           const match = script.textContent.match(/loader\s*\(\s*(\{[\s\S]*?\})\s*\)/);
           if (match && match[1]) {
             try {
-              // Using Function to safely parse object string that might not be strict JSON
+
               config = new Function('return ' + match[1])();
             } catch (e) {
               console.error("Failed to parse loader config in new page", e);
@@ -125,61 +134,53 @@ export const Router = {
         }
       }
 
-      // If no BareMetal loader config is found, fallback to standard navigation
       if (!config) {
         Loader.log(`No BareMetal config found on ${url}. Falling back to native navigation.`);
         window.location.assign(url);
         return;
       }
 
-      // 2. Prepare transition: identify kept vs destroyed modules
       const modulesToLoad = await Loader.prepare(config);
 
-      // 3. Swap DOM and Head
       document.title = doc.title;
-      
-      // Swap Head Styles (prevent CSS leak)
+
       const oldStyles = document.head.querySelectorAll('link[data-baremetal="style"], style[data-baremetal="style"]');
       oldStyles.forEach(s => s.remove());
       const newStyles = doc.head.querySelectorAll('link[data-baremetal="style"], style[data-baremetal="style"]');
       newStyles.forEach(s => document.head.appendChild(s.cloneNode(true)));
 
-      // User Protected Elements (data-baremetal-preserve)
       const preservedNodes = [];
       const persistentElements = document.querySelectorAll('[data-baremetal-preserve]');
-      
+
       persistentElements.forEach(el => {
         if (!el.id) return;
         if (doc.getElementById(el.id)) {
-           // Synchronously detach the live node
+
            const placeholder = document.createElement('div');
            el.parentNode.replaceChild(placeholder, el);
            preservedNodes.push(el);
         }
       });
 
-      // Engine Protected Elements (Immortal)
       const transitionRoot = document.getElementById('baremetal-transition-root');
       if (transitionRoot) {
         transitionRoot.parentNode.removeChild(transitionRoot);
       }
 
-      // The actual synchronous DOM swap and restoration
       const executeDOMSwap = () => {
         document.body.innerHTML = doc.body.innerHTML;
 
-        // Restore User Protected Elements into their exact new positions
         preservedNodes.forEach(el => {
           const newEl = document.getElementById(el.id);
           if (newEl) {
-             // Sync attributes from the new HTML node so classes/styles update
+
              Array.from(el.attributes).forEach(attr => {
                if (attr.name !== 'id' && attr.name !== 'data-baremetal-preserve') el.removeAttribute(attr.name);
              });
              Array.from(newEl.attributes).forEach(attr => {
                if (attr.name !== 'id') el.setAttribute(attr.name, attr.value);
              });
-             
+
              newEl.parentNode.replaceChild(el, newEl);
           }
         });
@@ -188,7 +189,6 @@ export const Router = {
           document.body.appendChild(transitionRoot);
         }
 
-        // Notify keep-alive modules that the DOM has been swapped so they can re-bind UI elements
         stateManager.publish('DOM_SWAPPED', null);
       };
 
@@ -205,21 +205,23 @@ export const Router = {
         doSwap();
       }
 
-      // 4. Mount new modules (this emits ROUTE_END)
       await Loader.loadPrepared(modulesToLoad);
 
     } catch (err) {
+      if (err.name === 'AbortError') {
+        Loader.log(`Aborted fetch for ${url} due to new navigation.`);
+        return;
+      }
       console.error("Routing error:", err);
       stateManager.publish('ROUTE_ERROR', { url, error: err.message });
-      
+
       if (Loader.config.showErrorNotification) {
-        // Revert URL bar since we are aborting
+
         if (this.historyStack.length > 0) {
           const prev = this.historyStack.pop();
           history.replaceState(null, '', prev);
         }
 
-        // Show floating notification
         const notif = document.createElement('div');
         notif.style.position = 'fixed';
         notif.style.bottom = '20px';
@@ -233,16 +235,15 @@ export const Router = {
         notif.style.fontFamily = 'sans-serif';
         notif.style.transition = 'opacity 0.3s ease';
         notif.innerHTML = `<strong>Navigation Failed:</strong> ${err.message}`;
-        
+
         document.body.appendChild(notif);
-        
+
         setTimeout(() => {
           notif.style.opacity = '0';
           setTimeout(() => notif.remove(), 300);
         }, 4000);
       } else {
-        // Formal redirect to let server handle the error
-        // FIRST: Undo the pushState so we don't leave a phantom history entry that breaks the Back button!
+
         if (this.historyStack.length > 0) {
           const prev = this.historyStack.pop();
           history.replaceState(null, '', prev);