portapack 0.2.1 → 0.3.1

package/src/cli/cli.ts

@@ -1,139 +1,150 @@
 /**
  * @file cli.ts
  * @description
- * Main CLI runner for PortaPack. Handles parsing CLI args, executing the HTML bundler,
- * writing output to disk, logging metadata, and returning structured results.
+ * Main CLI runner for PortaPack. Handles argument parsing, calls the bundler via `pack()`,
+ * writes output to disk (unless dry-run), logs build stats, and captures structured output.
  */
 
-import fs from 'fs'; // Use default import if mocking default below
+import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
+// Use standard require for core modules in CJS context if needed
+// const path = require('path');
+// const fs = require('fs');
 
-import { parseOptions } from './options.js';
-import { generatePortableHTML, generateRecursivePortableHTML } from '../index';
-import type { CLIResult } from '../types';
-
-import { LogLevel } from '../types';
+import { parseOptions } from './options';
+import { pack } from '../index';
+// Import CLIOptions correctly
+import type { CLIResult, BundleOptions, BundleMetadata, CLIOptions } from '../types';
 
 /**
- * Dynamically loads package.json metadata.
+ * Dynamically loads version info from package.json using CommonJS compatible method.
+ *
+ * @returns {Record<string, any>} Parsed package.json or fallback
  */
 function getPackageJson(): Record<string, any> {
-    try {
-        const __filename = fileURLToPath(import.meta.url);
-        const __dirname = path.dirname(__filename);
-        const pkgPath = path.resolve(__dirname, '../../package.json');
-
-        // Use fs directly, assuming mock works or it's okay in non-test env
-        if (fs.existsSync(pkgPath)) {
-            return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        }
-    } catch (_) {
-        // Ignore and fallback
-    }
-    return { version: '0.1.0' }; // Default fallback version
+  try {
+    // FIX: Use require.resolve which works in CommonJS to find the package path
+    // It resolves relative to the location of this file or the node_modules structure
+    // Assumes 'portapack' is the package name defined in package.json
+    // We need the package.json itself, so resolve 'portapack/package.json'
+    // Use __dirname if available in CJS context, otherwise try relative from cwd as fallback
+    const searchPath = typeof __dirname !== 'undefined' ? path.join(__dirname, '..', '..') : process.cwd();
+    const pkgJsonPath = require.resolve('portapack/package.json', { paths: [searchPath] });
+    return require(pkgJsonPath); // Use require directly to load JSON
+  } catch (err) {
+     console.error("Warning: Could not dynamically load package.json for version.", err); // Log error for debugging
+     return { version: '0.0.0-unknown' };
+  }
 }
 
 /**
- * Entry function for running the CLI.
+ * Entrypoint for CLI execution. Parses args, runs bundler, logs output and errors.
+ *
+ * @param {string[]} [argv=process.argv] - Command-line arguments (default: system args)
+ * @returns {Promise<CLIResult>} - Structured result containing output, error, and exit code
  */
 export async function runCli(argv: string[] = process.argv): Promise<CLIResult> {
-    let stdout = '';
-    let stderr = '';
-    let exitCode = 0;
-
-    // Capture console output for result object
-    const originalLog = console.log;
-    const originalErr = console.error;
-    const originalWarn = console.warn;
-    console.log = (...args) => { stdout += args.join(' ') + '\n'; };
-    console.error = (...args) => { stderr += args.join(' ') + '\n'; };
-    console.warn = (...args) => { stderr += args.join(' ') + '\n'; }; // Capture warnings in stderr too
-
-    let opts: ReturnType<typeof parseOptions> | undefined;
-    try {
-        opts = parseOptions(argv);
-        const version = getPackageJson().version || '0.1.0';
-
-        if (opts.verbose) {
-            console.log(`📦 PortaPack v${version}`);
-        }
-
-        if (!opts.input) {
-            console.error('❌ Missing input file or URL');
-            // Restore console before returning
-            console.log = originalLog; console.error = originalErr; console.warn = originalWarn;
-            return { stdout, stderr, exitCode: 1 };
-        }
-
-        // Determine output path using nullish coalescing
-        const outputPath = opts.output ?? `${path.basename(opts.input).split('.')[0] || 'output'}.packed.html`;
-
-        if (opts.verbose) {
-            console.log(`📥 Input: ${opts.input}`);
-            console.log(`📤 Output: ${outputPath}`);
-            // Log other effective options if verbose
-            console.log(`   Recursive: ${opts.recursive ?? false}`);
-            console.log(`   Embed Assets: ${opts.embedAssets}`);
-            console.log(`   Minify HTML: ${opts.minifyHtml}`);
-            console.log(`   Minify CSS: ${opts.minifyCss}`);
-            console.log(`   Minify JS: ${opts.minifyJs}`);
-            console.log(`   Log Level: ${LogLevel[opts.logLevel ?? LogLevel.INFO]}`);
-        }
-
-        if (opts.dryRun) {
-            console.log('💡 Dry run mode — no output will be written');
-            // Restore console before returning
-            console.log = originalLog; console.error = originalErr; console.warn = originalWarn;
-            return { stdout, stderr, exitCode: 0 };
-        }
-
-        // --- FIX: Pass 'opts' object to generate functions ---
-        const result = opts.recursive
-            // Convert boolean recursive flag to depth 1 if needed, otherwise use number
-            ? await generateRecursivePortableHTML(opts.input, typeof opts.recursive === 'boolean' ? 1 : opts.recursive, opts)
-            : await generatePortableHTML(opts.input, opts);
-        // ----------------------------------------------------
-
-        // Use fs directly - ensure mock is working in tests
-        fs.writeFileSync(outputPath, result.html, 'utf-8');
-
-        const meta = result.metadata;
-        console.log(`✅ Packed: ${meta.input} → ${outputPath}`);
-        console.log(`📦 Size: ${(meta.outputSize / 1024).toFixed(2)} KB`);
-        console.log(`⏱️ Time: ${meta.buildTimeMs} ms`); // Use alternative emoji
-        console.log(`🖼️ Assets: ${meta.assetCount}`); // Add asset count log
-
-        if (meta.pagesBundled && meta.pagesBundled > 0) { // Check > 0 for clarity
-            console.log(`🧩 Pages: ${meta.pagesBundled}`);
-        }
-
-        if (meta.errors && meta.errors.length > 0) {
-            console.warn(`\n⚠️  ${meta.errors.length} warning(s):`); // Add newline for separation
-            for (const err of meta.errors) {
-                console.warn(`  - ${err}`);
-            }
-        }
-    } catch (err: any) {
-        console.error(`\n💥 Error: ${err?.message || 'Unknown failure'}`); // Add newline
-        if (err?.stack && opts?.verbose) { // Show stack only if verbose
-            console.error(err.stack);
-        }
-        exitCode = 1;
-    } finally {
-        // Restore original console methods
-        console.log = originalLog;
-        console.error = originalErr;
-        console.warn = originalWarn;
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+
+  // Capture console output
+  const originalLog = console.log;
+  const originalErr = console.error;
+  const originalWarn = console.warn;
+
+  const restoreConsole = () => {
+      console.log = originalLog;
+      console.error = originalErr;
+      console.warn = originalWarn;
+  };
+
+  console.log = (...args) => { stdout += args.join(' ') + '\n'; };
+  console.error = (...args) => { stderr += args.join(' ') + '\n'; };
+  console.warn = (...args) => { stderr += args.join(' ') + '\n'; };
+
+  // FIX: Use the correct type CLIOptions which includes 'input'
+  let cliOptions: CLIOptions | undefined;
+  try {
+    // Get the fully parsed options object which includes 'input'
+    cliOptions = parseOptions(argv);
+    const version = getPackageJson().version || '0.0.0';
+
+    if (cliOptions.verbose) {
+      console.log(`📦 PortaPack v${version}`);
     }
 
-    return { stdout, stderr, exitCode };
-}
+    // Check for the input property on the correct object
+    if (!cliOptions.input) {
+      console.error('❌ Missing input file or URL');
+      restoreConsole();
+      return { stdout, stderr, exitCode: 1 };
+    }
+
+    // Use path.basename and handle potential extension removal carefully
+    const inputBasename = path.basename(cliOptions.input);
+    const outputDefaultBase = inputBasename.includes('.') ? inputBasename.substring(0, inputBasename.lastIndexOf('.')) : inputBasename;
+    // Use the parsed output option or generate default
+    const outputPath = cliOptions.output ?? `${outputDefaultBase || 'output'}.packed.html`;
+
+    if (cliOptions.verbose) {
+      console.log(`📥 Input: ${cliOptions.input}`); // Access input correctly
+      console.log(`📤 Output: ${outputPath}`);
+      // Display other resolved options
+      console.log(`  Recursive: ${cliOptions.recursive ?? false}`);
+      console.log(`  Embed Assets: ${cliOptions.embedAssets}`);
+      console.log(`  Minify HTML: ${cliOptions.minifyHtml}`);
+      console.log(`  Minify CSS: ${cliOptions.minifyCss}`);
+      console.log(`  Minify JS: ${cliOptions.minifyJs}`);
+      console.log(`  Log Level: ${cliOptions.logLevel}`);
+    }
+
+    if (cliOptions.dryRun) {
+      console.log('💡 Dry run mode — no output will be written');
+      restoreConsole();
+      return { stdout, stderr, exitCode: 0 };
+    }
+
+    // FIX: Call pack with input as the first argument, and the rest of the options as the second.
+    // The cliOptions object should be compatible with PackOptions expected by pack.
+    const result = await pack(cliOptions.input, cliOptions);
+
+    // Use standard fs sync version as used before
+    fs.writeFileSync(outputPath, result.html, 'utf-8');
 
-// Optional: Define main export if this file is intended to be run directly
-export const main = runCli;
+    const meta = result.metadata;
+    // Log results to captured stdout
+    console.log(`✅ Packed: ${meta.input} → ${outputPath}`); // meta.input should be correct from pack's result
+    console.log(`📦 Size: ${(meta.outputSize / 1024).toFixed(2)} KB`);
+    console.log(`⏱️ Time: ${meta.buildTimeMs} ms`);
+    console.log(`🖼️ Assets: ${meta.assetCount}`);
 
-// Example direct execution (usually handled by bin entry in package.json)
-// if (require.main === module) {
-//     runCli();
-// }
+    if (meta.pagesBundled && meta.pagesBundled > 0) {
+      console.log(`🧩 Pages: ${meta.pagesBundled}`);
+    }
+
+    if (meta.errors?.length) {
+      console.warn(`\n⚠️  ${meta.errors.length} warning(s):`);
+      for (const err of meta.errors) {
+        console.warn(`  - ${err}`);
+      }
+    }
+
+  } catch (err: any) {
+    console.error(`\n💥 Error: ${err?.message || 'Unknown failure'}`);
+    // Check verbose flag on the correct variable
+    if (err?.stack && cliOptions?.verbose) {
+      console.error(err.stack);
+    }
+    exitCode = 1;
+  } finally {
+    restoreConsole();
+  }
+
+  return { stdout, stderr, exitCode };
+}
+
+/**
+ * Default exportable main runner for CLI invocation.
+ */
+export const main = runCli;

package/src/core/bundler.ts

@@ -1,17 +1,17 @@
 /**
  * @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
+ * @version 1.3.0 // Assuming version based on previous context
  */
 
-import { dirname, resolve } from 'path';
+import { dirname, resolve, sep as pathSeparator } from 'path';
 import { pathToFileURL, URL } from 'url';
-import { extractAssets } from './extractor.js';
-import { minifyAssets } from './minifier.js';
-import { packHTML } from './packer.js';
-import { Logger } from '../utils/logger.js';
-import { ParsedHTML, BundleOptions, PageEntry } from '../types.js';
-import { sanitizeSlug, slugify } from '../utils/slugify.js';
+import { extractAssets } from './extractor';
+import { minifyAssets } from './minifier';
+import { packHTML } from './packer';
+import { Logger } from '../utils/logger';
+import { ParsedHTML, BundleOptions, PageEntry, LogLevel } from '../types'; // Added LogLevel import
+import { sanitizeSlug } from '../utils/slugify';
 
 /**
  * Determines the appropriate base URL for resolving relative assets
@@ -25,20 +25,26 @@ function determineBaseUrl(input: string, logger?: Logger): string {
     try {
         if (input.startsWith('http://') || input.startsWith('https://')) {
             const url = new URL(input);
+            // Go up to the last '/' in the pathname
             url.pathname = url.pathname.substring(0, url.pathname.lastIndexOf('/') + 1);
-            url.search = '';
-            url.hash = '';
+            url.search = ''; // Remove query string
+            url.hash = ''; // Remove fragment
             const baseUrl = url.toString();
             logger?.debug(`Determined remote base URL: ${baseUrl}`);
             return baseUrl;
         } else {
+            // Handle local file path
             const absoluteDir = dirname(resolve(input));
-            const baseUrl = pathToFileURL(absoluteDir + '/').href;
+            // Ensure trailing separator for directory URL conversion
+            const dirPathWithSeparator = absoluteDir.endsWith(pathSeparator) ? absoluteDir : absoluteDir + pathSeparator;
+            const baseUrl = pathToFileURL(dirPathWithSeparator).href;
             logger?.debug(`Determined local base URL: ${baseUrl}`);
             return baseUrl;
         }
     } catch (error: any) {
-        logger?.error(`Failed to determine base URL for "${input}": ${error.message}`);
+        // Use logger?.error correctly
+        logger?.error(`💀 Failed to determine base URL for "${input}": ${error.message}`);
+        // Return a default relative base URL on error
         return './';
     }
 }
@@ -47,48 +53,58 @@ function determineBaseUrl(input: string, logger?: Logger): string {
  * Creates a self-contained HTML file from a parsed HTML structure and options.
  *
  * @param parsedHtml - The parsed HTML document.
- * @param inputPath - The original input file or URL for base URL calculation.
+ * @param inputPathOrUrl - The original input file or URL for base URL calculation.
  * @param options - Optional bundling options.
  * @param logger - Optional logger instance.
  * @returns A fully inlined and bundled HTML string.
  */
 export async function bundleSingleHTML(
     parsedHtml: ParsedHTML,
-    inputPath: string,
+    inputPathOrUrl: string, // Renamed parameter for clarity
     options: BundleOptions = {},
     logger?: Logger
 ): Promise<string> {
-    try {
-        const defaultOptions: Required<BundleOptions> = {
-            embedAssets: true,
-            minifyHtml: true,
-            minifyJs: true,
-            minifyCss: true,
-            baseUrl: '',
-            verbose: false,
-            dryRun: false,
-            recursive: false,
-            output: '',
-            logLevel: logger?.level ?? 3,
-        };
-
-        const mergedOptions = { ...defaultOptions, ...options };
-
-        if (!mergedOptions.baseUrl) {
-            mergedOptions.baseUrl = determineBaseUrl(inputPath, logger);
-        }
+    // Define comprehensive defaults
+    const defaultOptions: Required<Omit<BundleOptions, 'logLevel'|'loggerInstance'>> = { // Omit non-serializable/runtime options from defaults
+        embedAssets: true,
+        minifyHtml: true,
+        minifyJs: true,
+        minifyCss: true,
+        baseUrl: '',
+        verbose: false, // Default verbosity usually controlled by logger level
+        dryRun: false,
+        recursive: false, // Default non-recursive for single bundle
+        output: '', // Default handled elsewhere or not relevant here
+        // Omit logLevel from defaults, use logger?.level
+    };
+
+    // Merge provided options over defaults
+    const mergedOptions = { ...defaultOptions, ...options };
 
-        logger?.debug(`Starting HTML bundling for ${inputPath}`);
-        logger?.debug(`Effective options: ${JSON.stringify(mergedOptions, null, 2)}`);
+    // Determine base URL only if not explicitly provided
+    if (!mergedOptions.baseUrl) {
+        mergedOptions.baseUrl = determineBaseUrl(inputPathOrUrl, logger);
+    }
+
+    try {
+        logger?.debug(`Starting HTML bundling for ${inputPathOrUrl}`);
+        // Use logger?.level safely
+        const effectiveLogLevel = (logger && typeof logger.level === 'number') ? logger.level : LogLevel.INFO; // Default to INFO if logger undefined or level wrong type
+        logger?.debug(`Effective options: ${JSON.stringify({
+            ...mergedOptions,
+            logLevel: effectiveLogLevel // Include actual log level if needed
+        }, null, 2)}`);
 
+        // Execute the bundling pipeline
         const extracted = await extractAssets(parsedHtml, mergedOptions.embedAssets, mergedOptions.baseUrl, logger);
         const minified = await minifyAssets(extracted, mergedOptions, logger);
         const result = packHTML(minified, logger);
 
-        logger?.info(`Single HTML bundling complete for: ${inputPath}`);
+        logger?.info(`Single HTML bundling complete for: ${inputPathOrUrl}`);
         return result;
     } catch (error: any) {
-        logger?.error(`Error during single HTML bundling: ${error.message}`);
+        logger?.error(`Error during single HTML bundling for ${inputPathOrUrl}: ${error.message}`);
+        // Re-throw to allow higher-level handling
         throw error;
     }
 }
@@ -110,9 +126,12 @@ export function bundleMultiPageHTML(pages: PageEntry[], logger?: Logger): string
 
     logger?.info(`Bundling ${pages.length} pages into a multi-page HTML document.`);
 
+    let pageIndex = 0; // Keep track of original index for logging
     const validPages = pages.filter(page => {
         const isValid = page && typeof page === 'object' && typeof page.url === 'string' && typeof page.html === 'string';
-        if (!isValid) logger?.warn('Skipping invalid page entry');
+        // Log with original index if invalid
+        if (!isValid) logger?.warn(`Skipping invalid page entry at index ${pageIndex}`);
+        pageIndex++; // Increment index regardless
         return isValid;
     });
 
@@ -124,73 +143,165 @@ export function bundleMultiPageHTML(pages: PageEntry[], logger?: Logger): string
 
     const slugMap = new Map<string, string>();
     const usedSlugs = new Set<string>();
+    let firstValidSlug: string | undefined = undefined;
+    let pageCounterForFallback = 1; // Counter for unique fallback slugs
 
     for (const page of validPages) {
-        const baseSlug = sanitizeSlug(page.url);
+        // --- REVISED SLUG LOGIC ---
+        let baseSlug = sanitizeSlug(page.url);
+
+        // Determine if the URL represents a root index page
+        const isRootIndex = (page.url === '/' || page.url === 'index.html' || page.url.endsWith('/index.html'));
+
+        if (baseSlug === 'index' && !isRootIndex) {
+            // If sanitizeSlug produced 'index' but it wasn't from a root index URL, avoid using 'index'.
+            logger?.debug(`URL "${page.url}" sanitized to "index", attempting to find alternative slug.`);
+            // Try using the last path segment instead.
+             // Get parts, remove trailing slash/index/index.html, filter empty
+            const pathParts = page.url.replace(/\/$/, '').split('/').filter(p => p && p.toLowerCase() !== 'index.html' && p.toLowerCase() !== 'index');
+            if (pathParts.length > 0) {
+                const lastPartSlug = sanitizeSlug(pathParts[pathParts.length - 1]);
+                if (lastPartSlug && lastPartSlug !== 'index') { // Avoid re-introducing 'index' or using empty
+                     baseSlug = lastPartSlug;
+                     logger?.debug(`Using last path part slug "${baseSlug}" instead.`);
+                } else {
+                     baseSlug = 'page'; // Fallback if last part is empty, 'index', or missing
+                     logger?.debug(`Last path part invalid ("${lastPartSlug}"), using fallback slug "page".`);
+                }
+            } else {
+                 baseSlug = 'page'; // Fallback if no other parts
+                 logger?.debug(`No valid path parts found, using fallback slug "page".`);
+            }
+        } else if (!baseSlug) {
+             // Handle cases where sanitizeSlug returns an empty string initially (e.g. sanitizeSlug('/'))
+             if (isRootIndex) {
+                 baseSlug = 'index'; // Ensure root index gets 'index' slug even if sanitizeSlug returns empty
+                 logger?.debug(`URL "${page.url}" sanitized to empty string, using "index" as it is a root index.`);
+             } else {
+                baseSlug = 'page'; // Fallback for other empty slugs
+                logger?.debug(`URL "${page.url}" sanitized to empty string, using fallback slug "page".`);
+             }
+        }
+        // Ensure baseSlug is never empty after this point before collision check
+        if (!baseSlug) {
+             // Use a counter to ensure uniqueness if multiple pages sanitize to empty/page
+            baseSlug = `page-${pageCounterForFallback++}`;
+            logger?.warn(`Could not determine a valid base slug for "${page.url}", using generated fallback "${baseSlug}".`);
+        }
+        // --- END REVISED SLUG LOGIC ---
+
+
+        // --- Collision Handling ---
         let slug = baseSlug;
-        let counter = 1;
+        let collisionCounter = 1;
+        // Keep track of the original baseSlug for logging purposes in case of collision
+        const originalBaseSlugForLog = baseSlug;
         while (usedSlugs.has(slug)) {
-            slug = `${baseSlug}-${counter++}`;
-            logger?.warn(`Slug collision detected for "${page.url}". Using "${slug}" instead.`);
+            const newSlug = `${originalBaseSlugForLog}-${collisionCounter++}`;
+            // Log with original intended base slug for clarity
+            logger?.warn(`Slug collision detected for "${page.url}" (intended slug: '${originalBaseSlugForLog}'). Using "${newSlug}" instead.`);
+            slug = newSlug;
         }
         usedSlugs.add(slug);
         slugMap.set(page.url, slug);
+
+        // Track the first valid slug for default navigation
+        if (firstValidSlug === undefined) { // Use triple equals for check
+            firstValidSlug = slug;
+        }
     }
 
-    const defaultPageSlug = slugMap.get(validPages[0].url);
+    // Determine the default page slug - prefer 'index' if present, otherwise use the first page's slug
+     // Use 'page' as ultimate fallback if firstValidSlug is somehow still undefined (e.g., only one page failed slug generation)
+    const defaultPageSlug = usedSlugs.has('index') ? 'index' : (firstValidSlug || 'page');
 
+    // Generate HTML structure
+    // (Ensure template IDs use `page-${slug}`)
+    // (Ensure nav links use `href="#${slug}"` and `data-page="${slug}"`)
+    // (Ensure router script uses `${defaultPageSlug}` correctly)
     let output = `<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Multi-Page Bundle</title>
+    <style>
+        body { font-family: sans-serif; margin: 0; }
+        #main-nav { background-color: #f0f0f0; padding: 10px; border-bottom: 1px solid #ccc; }
+        #main-nav a { margin-right: 15px; text-decoration: none; color: #007bff; }
+        #main-nav a.active { font-weight: bold; text-decoration: underline; }
+        #page-container { padding: 20px; }
+        template { display: none; }
+    </style>
 </head>
 <body>
     <nav id="main-nav">
         ${validPages.map(p => {
-            const slug = slugMap.get(p.url)!;
-            const label = p.url.split('/').pop()?.split('.')[0] || 'Page';
+            const slug = slugMap.get(p.url)!; // Slug is guaranteed to exist here
+            const label = slug; // Use slug as label for simplicity
             return `<a href="#${slug}" data-page="${slug}">${label}</a>`;
-        }).join('\n')}
+        }).join('\n        ')}
     </nav>
     <div id="page-container"></div>
     ${validPages.map(p => {
         const slug = slugMap.get(p.url)!;
+        // Basic sanitization/escaping might be needed for p.html if needed
         return `<template id="page-${slug}">${p.html}</template>`;
-    }).join('\n')}
+    }).join('\n    ')}
     <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);
-                const container = document.getElementById('page-container');
-                if (!template || !container) return;
-                container.innerHTML = '';
-                container.appendChild(template.content.cloneNode(true));
-                document.querySelectorAll('#main-nav a').forEach(link => {
-                    if (link.getAttribute('data-page') === slug) link.classList.add('active');
-                    else link.classList.remove('active');
+                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 URL hash without triggering hashchange if already correct
                 if (window.location.hash.substring(1) !== slug) {
-                    history.pushState(null, '', '#' + slug);
+                    // Use pushState for cleaner history
+                    history.pushState({ slug: slug }, '', '#' + slug);
                 }
             }
 
-            window.addEventListener('hashchange', () => {
-                const slug = window.location.hash.substring(1);
-                if (document.getElementById('page-' + slug)) navigateTo(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);
             });
 
-            document.querySelectorAll('#main-nav a').forEach(link => {
+            // Handle direct link clicks
+            navLinks.forEach(link => {
                 link.addEventListener('click', function(e) {
                     e.preventDefault();
                     const slug = this.getAttribute('data-page');
-                    navigateTo(slug);
+                    if (slug) navigateTo(slug);
                 });
             });
 
-            const initial = window.location.hash.substring(1);
-            navigateTo(document.getElementById('page-' + initial) ? initial : '${defaultPageSlug}');
+            // Initial page load
+            const initialHash = window.location.hash.substring(1);
+            const initialSlug = document.getElementById('page-' + initialHash) ? initialHash : '${defaultPageSlug}';
+            navigateTo(initialSlug);
         });
     </script>
 </body>
@@ -198,4 +309,4 @@ export function bundleMultiPageHTML(pages: PageEntry[], logger?: Logger): string
 
     logger?.info(`Multi-page bundle generated. Size: ${Buffer.byteLength(output, 'utf-8')} bytes.`);
     return output;
-}
+}