portapack 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -204,7 +204,6 @@ declare class Logger {
 /**
  * @file bundler.ts
  * @description Core bundling functions to handle both single and multi-page HTML documents. This includes asset extraction, optional minification, and full inlining into a self-contained HTML file.
- * @version 1.3.0 // Assuming version based on previous context
  */
 
 /**
@@ -221,8 +220,6 @@ declare function bundleMultiPageHTML(pages: PageEntry[], logger?: Logger): strin
  * @file index.ts
  * @description Public API surface for PortaPack.
  * Exposes the unified `pack()` method and advanced helpers like recursive crawling and multi-page bundling.
- * @version 1.0.0 - (Add version if applicable)
- * @date 2025-04-11
  */
 
 /**

package/dist/index.js

@@ -112,7 +112,9 @@ var Logger = class _Logger {
       case "none":
         return new _Logger(0 /* NONE */);
       default:
-        console.warn(`[Logger] Invalid log level name "${levelName}". Defaulting to ${LogLevel[defaultLevel]}.`);
+        console.warn(
+          `[Logger] Invalid log level name "${levelName}". Defaulting to ${LogLevel[defaultLevel]}.`
+        );
         return new _Logger(defaultLevel);
     }
   }
@@ -209,7 +211,9 @@ function determineBaseUrl(inputPathOrUrl, logger) {
       logger?.debug(`Determined remote base URL: ${baseUrl}`);
       return baseUrl;
     } else if (inputPathOrUrl.includes("://") && !inputPathOrUrl.startsWith("file:")) {
-      logger?.warn(`Input "${inputPathOrUrl}" looks like a URL but uses an unsupported protocol. Cannot determine base URL.`);
+      logger?.warn(
+        `Input "${inputPathOrUrl}" looks like a URL but uses an unsupported protocol. Cannot determine base URL.`
+      );
       return void 0;
     } else {
       let resourcePath;
@@ -235,12 +239,16 @@ function determineBaseUrl(inputPathOrUrl, logger) {
       }
       const fileUrl = new URL2("file://" + normalizedPathForURL);
       const fileUrlString = fileUrl.href;
-      logger?.debug(`Determined base URL: ${fileUrlString} (from: ${inputPathOrUrl}, resolved base dir: ${baseDirPath})`);
+      logger?.debug(
+        `Determined base URL: ${fileUrlString} (from: ${inputPathOrUrl}, resolved base dir: ${baseDirPath})`
+      );
       return fileUrlString;
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    logger?.error(`\u{1F480} Failed to determine base URL for "${inputPathOrUrl}": ${message}${error instanceof Error && error.stack ? ` - Stack: ${error.stack}` : ""}`);
+    logger?.error(
+      `\u{1F480} Failed to determine base URL for "${inputPathOrUrl}": ${message}${error instanceof Error && error.stack ? ` - Stack: ${error.stack}` : ""}`
+    );
     return void 0;
   }
 }
@@ -255,7 +263,9 @@ function resolveAssetUrl(assetUrl, baseContextUrl, logger) {
       const base = new URL2(baseContextUrl);
       resolvableUrl = base.protocol + resolvableUrl;
     } catch (e) {
-      logger?.warn(`Could not extract protocol from base "${baseContextUrl}" for protocol-relative URL "${trimmedUrl}". Skipping.`);
+      logger?.warn(
+        `Could not extract protocol from base "${baseContextUrl}" for protocol-relative URL "${trimmedUrl}". Skipping.`
+      );
       return null;
     }
   }
@@ -269,9 +279,13 @@ function resolveAssetUrl(assetUrl, baseContextUrl, logger) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (!/^[a-z]+:/i.test(resolvableUrl) && !resolvableUrl.startsWith("/") && !baseContextUrl) {
-      logger?.warn(`Cannot resolve relative URL "${resolvableUrl}" - Base context URL was not provided or determined.`);
+      logger?.warn(
+        `Cannot resolve relative URL "${resolvableUrl}" - Base context URL was not provided or determined.`
+      );
     } else {
-      logger?.warn(`\u26A0\uFE0F Failed to parse/resolve URL "${resolvableUrl}" ${baseContextUrl ? 'against base "' + baseContextUrl + '"' : "(no base provided)"}: ${message}`);
+      logger?.warn(
+        `\u26A0\uFE0F Failed to parse/resolve URL "${resolvableUrl}" ${baseContextUrl ? 'against base "' + baseContextUrl + '"' : "(no base provided)"}: ${message}`
+      );
     }
     return null;
   }
@@ -301,14 +315,18 @@ async function fetchAsset(resolvedUrl, logger, timeout = 1e4) {
         timeout
         // Apply network timeout
       });
-      logger?.debug(`Workspaceed remote asset ${resolvedUrl.href} (Status: ${response.status}, Type: ${response.headers["content-type"] || "N/A"}, Size: ${response.data?.byteLength ?? 0} bytes)`);
+      logger?.debug(
+        `Workspaceed remote asset ${resolvedUrl.href} (Status: ${response.status}, Type: ${response.headers["content-type"] || "N/A"}, Size: ${response.data?.byteLength ?? 0} bytes)`
+      );
       return Buffer.from(response.data);
     } else if (protocol === "file:") {
       let filePath;
       try {
         filePath = fileURLToPath(resolvedUrl);
       } catch (e) {
-        logger?.error(`Could not convert file URL to path: ${resolvedUrl.href}. Error: ${e.message}`);
+        logger?.error(
+          `Could not convert file URL to path: ${resolvedUrl.href}. Error: ${e.message}`
+        );
         return null;
       }
       const normalizedForLog = path2.normalize(filePath);
@@ -342,9 +360,13 @@ async function fetchAsset(resolvedUrl, logger, timeout = 1e4) {
         logger?.warn(`\u26A0\uFE0F Failed to read local asset ${failedPath}: ${error.message}`);
       }
     } else if (error instanceof Error) {
-      logger?.warn(`\u26A0\uFE0F An unexpected error occurred processing asset ${resolvedUrl.href}: ${error.message}`);
+      logger?.warn(
+        `\u26A0\uFE0F An unexpected error occurred processing asset ${resolvedUrl.href}: ${error.message}`
+      );
     } else {
-      logger?.warn(`\u26A0\uFE0F An unknown and unexpected error occurred processing asset ${resolvedUrl.href}: ${String(error)}`);
+      logger?.warn(
+        `\u26A0\uFE0F An unknown and unexpected error occurred processing asset ${resolvedUrl.href}: ${String(error)}`
+      );
     }
     return null;
   }
@@ -355,7 +377,8 @@ function extractUrlsFromCSS(cssContent, cssBaseContextUrl, logger) {
   const urlRegex = /url\(\s*(['"]?)(.*?)\1\s*\)/gi;
   const importRegex = /@import\s+(?:url\(\s*(['"]?)(.*?)\1\s*\)|(['"])(.*?)\3)\s*;/gi;
   const processFoundUrl = (rawUrl, ruleType) => {
-    if (!rawUrl || rawUrl.trim() === "" || rawUrl.startsWith("data:") || rawUrl.startsWith("#")) return;
+    if (!rawUrl || rawUrl.trim() === "" || rawUrl.startsWith("data:") || rawUrl.startsWith("#"))
+      return;
     const resolvedUrl = resolveCssRelativeUrl(rawUrl, cssBaseContextUrl, logger);
     if (resolvedUrl && !processedInThisParse.has(resolvedUrl)) {
       processedInThisParse.add(resolvedUrl);
@@ -367,7 +390,9 @@ function extractUrlsFromCSS(cssContent, cssBaseContextUrl, logger) {
         content: void 0
         // Content will be fetched later if needed
       });
-      logger?.debug(`Discovered nested ${assetType} asset (${ruleType}) in CSS ${cssBaseContextUrl}: ${resolvedUrl}`);
+      logger?.debug(
+        `Discovered nested ${assetType} asset (${ruleType}) in CSS ${cssBaseContextUrl}: ${resolvedUrl}`
+      );
     }
   };
   let match;
@@ -381,14 +406,20 @@ function extractUrlsFromCSS(cssContent, cssBaseContextUrl, logger) {
   return newlyDiscovered;
 }
 async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger) {
-  logger?.info(`\u{1F680} Starting asset extraction! Embed: ${embedAssets}. Input: ${inputPathOrUrl || "(HTML content only)"}`);
+  logger?.info(
+    `\u{1F680} Starting asset extraction! Embed: ${embedAssets}. Input: ${inputPathOrUrl || "(HTML content only)"}`
+  );
   const initialAssets = parsed.assets || [];
   const finalAssetsMap = /* @__PURE__ */ new Map();
   let assetsToProcess = [];
   const processedOrQueuedUrls = /* @__PURE__ */ new Set();
   const htmlBaseContextUrl = determineBaseUrl(inputPathOrUrl || "", logger);
-  if (!htmlBaseContextUrl && initialAssets.some((a) => !/^[a-z]+:/i.test(a.url) && !a.url.startsWith("data:") && !a.url.startsWith("#") && !a.url.startsWith("/"))) {
-    logger?.warn("\u{1F6A8} No valid base path/URL determined for the HTML source! Resolution of relative asset paths from HTML may fail.");
+  if (!htmlBaseContextUrl && initialAssets.some(
+    (a) => !/^[a-z]+:/i.test(a.url) && !a.url.startsWith("data:") && !a.url.startsWith("#") && !a.url.startsWith("/")
+  )) {
+    logger?.warn(
+      "\u{1F6A8} No valid base path/URL determined for the HTML source! Resolution of relative asset paths from HTML may fail."
+    );
   } else if (htmlBaseContextUrl) {
     logger?.debug(`Using HTML base context URL: ${htmlBaseContextUrl}`);
   }
@@ -420,9 +451,13 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
   while (assetsToProcess.length > 0) {
     iterationCount++;
     if (iterationCount > MAX_ASSET_EXTRACTION_ITERATIONS) {
-      logger?.error(`\u{1F6D1} Asset extraction loop limit hit (${MAX_ASSET_EXTRACTION_ITERATIONS})! Aborting.`);
+      logger?.error(
+        `\u{1F6D1} Asset extraction loop limit hit (${MAX_ASSET_EXTRACTION_ITERATIONS})! Aborting.`
+      );
       const remainingUrls = assetsToProcess.map((a) => a.url).slice(0, 10).join(", ");
-      logger?.error(`Remaining queue sample (${assetsToProcess.length} items): ${remainingUrls}...`);
+      logger?.error(
+        `Remaining queue sample (${assetsToProcess.length} items): ${remainingUrls}...`
+      );
       assetsToProcess.forEach((asset) => {
         if (!finalAssetsMap.has(asset.url)) {
           finalAssetsMap.set(asset.url, { ...asset, content: void 0 });
@@ -448,7 +483,9 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
         try {
           assetUrlObj = new URL2(asset.url);
         } catch (urlError) {
-          logger?.warn(`Cannot create URL object for "${asset.url}", skipping fetch. Error: ${urlError instanceof Error ? urlError.message : String(urlError)}`);
+          logger?.warn(
+            `Cannot create URL object for "${asset.url}", skipping fetch. Error: ${urlError instanceof Error ? urlError.message : String(urlError)}`
+          );
           finalAssetsMap.set(asset.url, { ...asset, content: void 0 });
           continue;
         }
@@ -484,7 +521,9 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
               cssContentForParsing = textContent;
             }
           } else {
-            logger?.warn(`Could not decode ${asset.type} asset ${asset.url} as valid UTF-8 text.${embedAssets ? " Falling back to base64 data URI." : ""}`);
+            logger?.warn(
+              `Could not decode ${asset.type} asset ${asset.url} as valid UTF-8 text.${embedAssets ? " Falling back to base64 data URI." : ""}`
+            );
             cssContentForParsing = void 0;
             if (embedAssets) {
               finalContent = `data:${effectiveMime};base64,${assetContentBuffer.toString("base64")}`;
@@ -505,14 +544,18 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
             try {
               const attemptedTextContent = assetContentBuffer.toString("utf-8");
               if (isUtf8DecodingLossy(assetContentBuffer, attemptedTextContent)) {
-                logger?.warn(`Couldn't embed unclassified asset ${asset.url} as text due to invalid UTF-8 sequences. Falling back to base64 (octet-stream).`);
+                logger?.warn(
+                  `Couldn't embed unclassified asset ${asset.url} as text due to invalid UTF-8 sequences. Falling back to base64 (octet-stream).`
+                );
                 finalContent = `data:application/octet-stream;base64,${assetContentBuffer.toString("base64")}`;
               } else {
                 finalContent = attemptedTextContent;
                 logger?.debug(`Successfully embedded unclassified asset ${asset.url} as text.`);
               }
             } catch (decodeError) {
-              logger?.warn(`Error during text decoding for unclassified asset ${asset.url}: ${decodeError instanceof Error ? decodeError.message : String(decodeError)}. Falling back to base64.`);
+              logger?.warn(
+                `Error during text decoding for unclassified asset ${asset.url}: ${decodeError instanceof Error ? decodeError.message : String(decodeError)}. Falling back to base64.`
+              );
               finalContent = `data:application/octet-stream;base64,${assetContentBuffer.toString("base64")}`;
             }
           } else {
@@ -526,7 +569,9 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
       finalAssetsMap.set(asset.url, { ...asset, url: asset.url, content: finalContent });
       if (asset.type === "css" && cssContentForParsing) {
         const cssBaseContextUrl = determineBaseUrl(asset.url, logger);
-        logger?.debug(`CSS base context for resolving nested assets within ${asset.url}: ${cssBaseContextUrl}`);
+        logger?.debug(
+          `CSS base context for resolving nested assets within ${asset.url}: ${cssBaseContextUrl}`
+        );
         if (cssBaseContextUrl) {
           const newlyDiscoveredAssets = extractUrlsFromCSS(
             cssContentForParsing,
@@ -535,25 +580,33 @@ async function extractAssets(parsed, embedAssets = true, inputPathOrUrl, logger)
             logger
           );
           if (newlyDiscoveredAssets.length > 0) {
-            logger?.debug(`Discovered ${newlyDiscoveredAssets.length} nested assets in CSS ${asset.url}. Checking against queue...`);
+            logger?.debug(
+              `Discovered ${newlyDiscoveredAssets.length} nested assets in CSS ${asset.url}. Checking against queue...`
+            );
             for (const newAsset of newlyDiscoveredAssets) {
               if (!processedOrQueuedUrls.has(newAsset.url)) {
                 processedOrQueuedUrls.add(newAsset.url);
                 assetsToProcess.push(newAsset);
                 logger?.debug(` -> Queued new nested asset: ${newAsset.url}`);
               } else {
-                logger?.debug(` -> Skipping already processed/queued nested asset: ${newAsset.url}`);
+                logger?.debug(
+                  ` -> Skipping already processed/queued nested asset: ${newAsset.url}`
+                );
               }
             }
           }
         } else {
-          logger?.warn(`Could not determine base URL context for CSS file ${asset.url}. Cannot resolve nested relative paths within it.`);
+          logger?.warn(
+            `Could not determine base URL context for CSS file ${asset.url}. Cannot resolve nested relative paths within it.`
+          );
         }
       }
     }
   }
   const finalIterationCount = iterationCount > MAX_ASSET_EXTRACTION_ITERATIONS ? `${MAX_ASSET_EXTRACTION_ITERATIONS}+ (limit hit)` : iterationCount;
-  logger?.info(`\u2705 Asset extraction COMPLETE! Found ${finalAssetsMap.size} unique assets in ${finalIterationCount} iterations.`);
+  logger?.info(
+    `\u2705 Asset extraction COMPLETE! Found ${finalAssetsMap.size} unique assets in ${finalIterationCount} iterations.`
+  );
   return {
     htmlContent: parsed.htmlContent,
     assets: Array.from(finalAssetsMap.values())
@@ -633,7 +686,7 @@ async function minifyAssets(parsed, options = {}, logger) {
   logger?.debug(`Minification flags: ${JSON.stringify(minifyFlags)}`);
   const minifiedAssets = await Promise.all(
     currentAssets.map(async (asset) => {
-      let processedAsset = { ...asset };
+      const processedAsset = { ...asset };
       if (typeof processedAsset.content !== "string" || processedAsset.content.length === 0) {
         return processedAsset;
       }
@@ -648,13 +701,17 @@ async function minifyAssets(parsed, options = {}, logger) {
             logger?.warn(`\u26A0\uFE0F CleanCSS failed for ${assetIdentifier}: ${result.errors.join(", ")}`);
           } else {
             if (result.warnings && result.warnings.length > 0) {
-              logger?.debug(`CleanCSS warnings for ${assetIdentifier}: ${result.warnings.join(", ")}`);
+              logger?.debug(
+                `CleanCSS warnings for ${assetIdentifier}: ${result.warnings.join(", ")}`
+              );
             }
             if (result.styles) {
               newContent = result.styles;
               logger?.debug(`CSS minified successfully: ${assetIdentifier}`);
             } else {
-              logger?.warn(`\u26A0\uFE0F CleanCSS produced no styles but reported no errors for ${assetIdentifier}. Keeping original.`);
+              logger?.warn(
+                `\u26A0\uFE0F CleanCSS produced no styles but reported no errors for ${assetIdentifier}. Keeping original.`
+              );
             }
           }
         }
@@ -667,15 +724,21 @@ async function minifyAssets(parsed, options = {}, logger) {
           } else {
             const terserError = result.error;
             if (terserError) {
-              logger?.warn(`\u26A0\uFE0F Terser failed for ${assetIdentifier}: ${terserError.message || terserError}`);
+              logger?.warn(
+                `\u26A0\uFE0F Terser failed for ${assetIdentifier}: ${terserError.message || terserError}`
+              );
             } else {
-              logger?.warn(`\u26A0\uFE0F Terser produced no code but reported no errors for ${assetIdentifier}. Keeping original.`);
+              logger?.warn(
+                `\u26A0\uFE0F Terser produced no code but reported no errors for ${assetIdentifier}. Keeping original.`
+              );
             }
           }
         }
       } catch (err) {
         const errorMessage = err instanceof Error ? err.message : String(err);
-        logger?.warn(`\u26A0\uFE0F Failed to minify asset ${assetIdentifier} (${processedAsset.type}): ${errorMessage}`);
+        logger?.warn(
+          `\u26A0\uFE0F Failed to minify asset ${assetIdentifier} (${processedAsset.type}): ${errorMessage}`
+        );
       }
       processedAsset.content = newContent;
       return processedAsset;
@@ -777,7 +840,9 @@ function inlineAssets($, assets, logger) {
       logger?.debug(`Inlining image via ${srcAttr}: ${asset.url}`);
       element.attr(srcAttr, asset.content);
     } else if (src) {
-      logger?.warn(`Could not inline image via ${srcAttr}: ${src}. Content missing or not a data URI.`);
+      logger?.warn(
+        `Could not inline image via ${srcAttr}: ${src}. Content missing or not a data URI.`
+      );
     }
   });
   $("img[srcset], source[srcset]").each((_, el) => {
@@ -899,7 +964,9 @@ function bundleMultiPageHTML(pages, logger) {
     } else if (!baseSlug) {
       if (isRootIndex) {
         baseSlug = "index";
-        logger?.debug(`URL "${page.url}" sanitized to empty string, using "index" as it is a root index.`);
+        logger?.debug(
+          `URL "${page.url}" sanitized to empty string, using "index" as it is a root index.`
+        );
       } else {
         baseSlug = "page";
         logger?.debug(`URL "${page.url}" sanitized to empty string, using fallback slug "page".`);
@@ -907,14 +974,18 @@ function bundleMultiPageHTML(pages, logger) {
     }
     if (!baseSlug) {
       baseSlug = `page-${pageCounterForFallback++}`;
-      logger?.warn(`Could not determine a valid base slug for "${page.url}", using generated fallback "${baseSlug}".`);
+      logger?.warn(
+        `Could not determine a valid base slug for "${page.url}", using generated fallback "${baseSlug}".`
+      );
     }
     let slug = baseSlug;
     let collisionCounter = 1;
     const originalBaseSlugForLog = baseSlug;
     while (usedSlugs.has(slug)) {
       const newSlug = `${originalBaseSlugForLog}-${collisionCounter++}`;
-      logger?.warn(`Slug collision detected for "${page.url}" (intended slug: '${originalBaseSlugForLog}'). Using "${newSlug}" instead.`);
+      logger?.warn(
+        `Slug collision detected for "${page.url}" (intended slug: '${originalBaseSlugForLog}'). Using "${newSlug}" instead.`
+      );
       slug = newSlug;
     }
     usedSlugs.add(slug);
@@ -924,7 +995,8 @@ function bundleMultiPageHTML(pages, logger) {
     }
   }
   const defaultPageSlug = usedSlugs.has("index") ? "index" : firstValidSlug || "page";
-  let output = `<!DOCTYPE html>
+  const output = `
+<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
@@ -940,74 +1012,74 @@ function bundleMultiPageHTML(pages, logger) {
     </style>
 </head>
 <body>
-    <nav id="main-nav">
-        ${validPages.map((p) => {
+<nav id="main-nav">
+    ${validPages.map((p) => {
     const slug = slugMap.get(p.url);
     const label = slug;
     return `<a href="#${slug}" data-page="${slug}">${label}</a>`;
   }).join("\n        ")}
-    </nav>
-    <div id="page-container"></div>
-    ${validPages.map((p) => {
+</nav>
+<div id="page-container"></div>
+${validPages.map((p) => {
     const slug = slugMap.get(p.url);
     return `<template id="page-${slug}">${p.html}</template>`;
   }).join("\n    ")}
-    <script id="router-script">
-        document.addEventListener('DOMContentLoaded', function() {
-            const pageContainer = document.getElementById('page-container');
-            const navLinks = document.querySelectorAll('#main-nav a');
+<script id="router-script">
+    document.addEventListener('DOMContentLoaded', function() {
+        const pageContainer = document.getElementById('page-container');
+        const navLinks = document.querySelectorAll('#main-nav a');
 
-            function navigateTo(slug) {
-                const template = document.getElementById('page-' + slug);
-                if (!template || !pageContainer) {
-                    console.warn('Navigation failed: Template or container not found for slug:', slug);
-                    // Maybe try navigating to default page? Or just clear container?
-                    if (pageContainer) pageContainer.innerHTML = '<p>Page not found.</p>';
-                    return;
-                }
-                // Clear previous content and append new content
-                pageContainer.innerHTML = ''; // Clear reliably
-                pageContainer.appendChild(template.content.cloneNode(true));
+        function navigateTo(slug) {
+            const template = document.getElementById('page-' + slug);
+            if (!template || !pageContainer) {
+                console.warn('Navigation failed: Template or container not found for slug:', slug);
+                // Maybe try navigating to default page? Or just clear container?
+                if (pageContainer) pageContainer.innerHTML = '<p>Page not found.</p>';
+                return;
+            }
+            // Clear previous content and append new content
+            pageContainer.innerHTML = ''; // Clear reliably
+            pageContainer.appendChild(template.content.cloneNode(true));
 
-                // Update active link styling
-                navLinks.forEach(link => {
-                    link.classList.toggle('active', link.getAttribute('data-page') === slug);
-                });
+            // Update active link styling
+            navLinks.forEach(link => {
+                link.classList.toggle('active', link.getAttribute('data-page') === slug);
+            });
 
-                // Update URL hash without triggering hashchange if already correct
-                if (window.location.hash.substring(1) !== slug) {
-                    // Use pushState for cleaner history
-                    history.pushState({ slug: slug }, '', '#' + slug);
-                }
+            // Update URL hash without triggering hashchange if already correct
+            if (window.location.hash.substring(1) !== slug) {
+                // Use pushState for cleaner history
+                history.pushState({ slug: slug }, '', '#' + slug);
             }
+        }
 
-            // Handle back/forward navigation
-            window.addEventListener('popstate', (event) => {
-                let slug = window.location.hash.substring(1);
-                // If popstate event has state use it, otherwise fallback to hash or default
-                if (event && event.state && event.state.slug) { // Check event exists
-                    slug = event.state.slug;
-                }
-                // Ensure the target page exists before navigating, fallback to default slug
-                const targetSlug = document.getElementById('page-' + slug) ? slug : '${defaultPageSlug}';
-                navigateTo(targetSlug);
-            });
+        // Handle back/forward navigation
+        window.addEventListener('popstate', (event) => {
+            let slug = window.location.hash.substring(1);
+            // If popstate event has state use it, otherwise fallback to hash or default
+            if (event && event.state && event.state.slug) { // Check event exists
+                slug = event.state.slug;
+            }
+            // Ensure the target page exists before navigating, fallback to default slug
+            const targetSlug = document.getElementById('page-' + slug) ? slug : '${defaultPageSlug}';
+            navigateTo(targetSlug);
+        });
 
-            // Handle direct link clicks
-            navLinks.forEach(link => {
-                link.addEventListener('click', function(e) {
-                    e.preventDefault();
-                    const slug = this.getAttribute('data-page');
-                    if (slug) navigateTo(slug);
-                });
+        // Handle direct link clicks
+        navLinks.forEach(link => {
+            link.addEventListener('click', function(e) {
+                e.preventDefault();
+                const slug = this.getAttribute('data-page');
+                if (slug) navigateTo(slug);
             });
-
-            // Initial page load
-            const initialHash = window.location.hash.substring(1);
-            const initialSlug = document.getElementById('page-' + initialHash) ? initialHash : '${defaultPageSlug}';
-            navigateTo(initialSlug);
         });
-    </script>
+
+        // Initial page load
+        const initialHash = window.location.hash.substring(1);
+        const initialSlug = document.getElementById('page-' + initialHash) ? initialHash : '${defaultPageSlug}';
+        navigateTo(initialSlug);
+    });
+</script>
 </body>
 </html>`;
   logger?.info(`Multi-page bundle generated. Size: ${Buffer.byteLength(output, "utf-8")} bytes.`);
@@ -1074,7 +1146,9 @@ async function fetchAndPackWebPage(url, logger, timeout = DEFAULT_PAGE_TIMEOUT,
       throw pageError;
     }
   } catch (launchError) {
-    logger?.error(`Critical error during browser launch or page setup for ${url}: ${launchError.message}`);
+    logger?.error(
+      `Critical error during browser launch or page setup for ${url}: ${launchError.message}`
+    );
     if (browser) {
       try {
         await browser.close();
@@ -1087,7 +1161,9 @@ async function fetchAndPackWebPage(url, logger, timeout = DEFAULT_PAGE_TIMEOUT,
     throw launchError;
   } finally {
     if (browser) {
-      logger?.warn(`Closing browser in final cleanup for ${url}. This might indicate an unusual error path.`);
+      logger?.warn(
+        `Closing browser in final cleanup for ${url}. This might indicate an unusual error path.`
+      );
       try {
         await browser.close();
       } catch (closeErr) {
@@ -1204,21 +1280,26 @@ async function crawlWebsite(startUrl, options) {
 }
 async function recursivelyBundleSite(startUrl, outputFile, maxDepth = 1, loggerInstance) {
   const logger = loggerInstance || new Logger();
-  logger.info(`Starting recursive site bundle for ${startUrl} to ${outputFile} (maxDepth: ${maxDepth})`);
+  logger.info(
+    `Starting recursive site bundle for ${startUrl} to ${outputFile} (maxDepth: ${maxDepth})`
+  );
   try {
     const crawlOptions = {
       maxDepth,
       logger
-      /* Add other options like timeout, userAgent if needed */
     };
     const pages = await crawlWebsite(startUrl, crawlOptions);
     if (pages.length === 0) {
-      logger.warn("Crawl completed but found 0 pages. Output file may be empty or reflect an empty bundle.");
+      logger.warn(
+        "Crawl completed but found 0 pages. Output file may be empty or reflect an empty bundle."
+      );
     } else {
       logger.info(`Crawl successful, found ${pages.length} pages. Starting bundling.`);
     }
     const bundledHtml = bundleMultiPageHTML(pages, logger);
-    logger.info(`Bundling complete. Output size: ${Buffer.byteLength(bundledHtml, "utf-8")} bytes.`);
+    logger.info(
+      `Bundling complete. Output size: ${Buffer.byteLength(bundledHtml, "utf-8")} bytes.`
+    );
     logger.info(`Writing bundled HTML to ${outputFile}`);
     await fs2.writeFile(outputFile, bundledHtml, "utf-8");
     logger.info(`Successfully wrote bundled output to ${outputFile}`);