@squeditor/squeditor-framework 1.0.2 → 1.0.4

package/scripts/build-components.js

@@ -6,6 +6,7 @@ const projectRoot = process.cwd();
 const config = require(path.join(projectRoot, 'squeditor.config.js'));
 const fwRoot = path.resolve(projectRoot, config.framework); // resolves ..
 const manifest = require(path.join(fwRoot, 'uikit-manifest.json'));
+const resolvePages = require('./utils/resolve-pages');
 
 
 const selectedComponents = config.components || [];
@@ -82,12 +83,34 @@ console.log(`   Components included: _core, ${selectedComponents.join(', ')}`);
 // Generate src/config/active-components.php for the style-guide page
 const phpConfigDir = path.join(projectRoot, 'src/config');
 fs.mkdirSync(phpConfigDir, { recursive: true });
-const phpConfig = `<?php\n// Auto-generated by build-components.js — DO NOT EDIT\n$active_components = ${JSON.stringify(selectedComponents)};\n`;
+const phpComponentsArray = `[${selectedComponents.map(c => `'${c}'`).join(', ')}]`;
+const phpConfig = `<?php\n// Auto-generated by build-components.js — DO NOT EDIT\n$active_components = ${phpComponentsArray};\n`;
 fs.writeFileSync(
   path.join(phpConfigDir, 'active-components.php'),
   phpConfig
 );
 
+// Generate src/config/active-themes.php for automatic PHP dev server theme detection
+// Map each page to its corresponding theme identifier
+const themePageMapping = {};
+if (config.themes) {
+  Object.keys(config.themes).forEach(themeKey => {
+    const rawPages = config.themes[themeKey].pages || [];
+    const absolutePages = resolvePages(rawPages, projectRoot);
+    absolutePages.forEach(page => {
+      // Clean leading slashes for normalization if desired, but here we just map exact values
+      themePageMapping[page] = themeKey;
+    });
+  });
+}
+const phpThemesArrayParts = Object.entries(themePageMapping).map(([page, theme]) => `'${page}' => '${theme}'`);
+const phpThemesConfig = `<?php\n// Auto-generated by build-components.js — DO NOT EDIT\n$active_themes = [${phpThemesArrayParts.join(', ')}];\n`;
+fs.writeFileSync(
+  path.join(phpConfigDir, 'active-themes.php'),
+  phpThemesConfig
+);
+
+
 // Inject all themes into main.scss so live-switching works in the Style Guide
 const mainScssPath = path.join(projectRoot, 'src/assets/scss/main.scss');
 if (fs.existsSync(mainScssPath) && config.themes) {
@@ -107,3 +130,57 @@ if (fs.existsSync(mainScssPath) && config.themes) {
   fs.writeFileSync(mainScssPath, mainScss);
   console.log(`[Squeditor] 🎨 Injected themes: ${Object.keys(config.themes).join(', ')}`);
 }
+
+// Generate Dynamic Slider Config Import
+const sliderConfig = config.slider || { library: false };
+const dynamicSliderPath = path.join(outputJsDir, '_slider_dynamic.js');
+let sliderImportCode = '// Auto-generated by build-components.js — DO NOT EDIT\n';
+if (sliderConfig.library === 'swiper') {
+    sliderImportCode += 'import \'./modules/swiper-init.js\';\n';
+} else if (sliderConfig.library === 'splide') {
+    sliderImportCode += 'import \'./modules/splide-init.js\';\n';
+}
+fs.writeFileSync(dynamicSliderPath, sliderImportCode);
+console.log(`[Squeditor] 🎠 Injected slider library: ${sliderConfig.library || 'none'}`);
+
+// Copy slider library CSS to src/assets/css/slider.min.css
+// This keeps the CSS separate from main.js and gives it a clear, descriptive filename
+const sliderCssDest = path.join(projectRoot, 'src/assets/css/slider.min.css');
+if (sliderConfig.library === 'splide') {
+    const splideCssPath = path.join(projectRoot, 'node_modules/@splidejs/splide/dist/css/splide.min.css');
+    if (fs.existsSync(splideCssPath)) {
+        fs.copyFileSync(splideCssPath, sliderCssDest);
+        console.log('[Squeditor] 📎 Copied Splide CSS → src/assets/css/slider.min.css');
+    } else {
+        console.warn('[Squeditor] ⚠️ Splide CSS not found at expected path.');
+        fs.writeFileSync(sliderCssDest, '/* Splide CSS not found */\n');
+    }
+} else if (sliderConfig.library === 'swiper') {
+    // Concatenate all Swiper CSS modules into a single file
+    const swiperCssParts = [
+        'node_modules/swiper/swiper.min.css',
+        'node_modules/swiper/modules/navigation.min.css',
+        'node_modules/swiper/modules/pagination.min.css',
+        'node_modules/swiper/modules/effect-fade.min.css',
+        'node_modules/swiper/modules/free-mode.min.css',
+    ];
+    let combinedCss = '/* Swiper CSS - auto-generated by build-components.js */\n';
+    for (const part of swiperCssParts) {
+        const fullPath = path.join(projectRoot, part);
+        if (fs.existsSync(fullPath)) {
+            combinedCss += fs.readFileSync(fullPath, 'utf8') + '\n';
+        }
+    }
+    fs.writeFileSync(sliderCssDest, combinedCss);
+    console.log('[Squeditor] 📎 Copied Swiper CSS → src/assets/css/slider.min.css');
+} else {
+    // No slider configured — write an empty placeholder so head.php link doesn't 404
+    fs.writeFileSync(sliderCssDest, '/* No slider library configured */\n');
+}
+
+// Generate src/config/active-slider.php for conditional CSS loading in head.php
+const phpSliderConfig = `<?php\n// Auto-generated by build-components.js — DO NOT EDIT\n$active_slider = ${sliderConfig.library ? `'${sliderConfig.library}'` : 'false'};\n`;
+fs.writeFileSync(
+  path.join(phpConfigDir, 'active-slider.php'),
+  phpSliderConfig
+);

package/scripts/copy-static.js

@@ -145,6 +145,32 @@ async function run() {
     } else {
         console.warn(`[Squeditor] ⚠️ Source directory for static assets not found: ${srcDir}`);
     }
+
+    // Post-Vite-build CSS renaming for clearer dist output
+    const distCssDir = path.join(projectRoot, config.snapshot.outputDir, 'assets/css');
+
+    // Rename main_css.css → main.min.css (SCSS entry output)
+    const mainCssSrc = path.join(distCssDir, 'main_css.css');
+    const mainCssDest = path.join(distCssDir, 'main.min.css');
+    if (fs.existsSync(mainCssSrc)) {
+        fs.renameSync(mainCssSrc, mainCssDest);
+        console.log('[Squeditor] 📎 Renamed main_css.css → main.min.css');
+    }
+
+    // Remove stale main.css (previously contained CSS-in-JS extracted by Vite, now handled separately)
+    const staleMainCss = path.join(distCssDir, 'main.css');
+    if (fs.existsSync(staleMainCss)) {
+        fs.unlinkSync(staleMainCss);
+    }
+
+    // Copy slider.min.css to dist (generated by build-components.js)
+    const sliderCssSrc = path.join(projectRoot, 'src/assets/css/slider.min.css');
+    const sliderCssDest = path.join(distCssDir, 'slider.min.css');
+    if (fs.existsSync(sliderCssSrc)) {
+        fs.mkdirSync(distCssDir, { recursive: true });
+        fs.copyFileSync(sliderCssSrc, sliderCssDest);
+        console.log('[Squeditor] 📎 Copied slider.min.css → dist/assets/css/');
+    }
 }
 
 run();

package/scripts/dev-router.php

@@ -19,5 +19,14 @@ if (preg_match('/\.html$/', $uri)) {
     }
 }
 
-// 3. Let PHP's core handle index.php fallback for directories or 404s
+// 3. If it is an extensionless request, route it to the equivalent PHP file
+if ($uri !== '/' && !pathinfo($uri, PATHINFO_EXTENSION)) {
+    $php_file = $uri . '.php';
+    if (file_exists($doc_root . $php_file)) {
+        require $doc_root . $php_file;
+        return true;
+    }
+}
+
+// 4. Let PHP's core handle index.php fallback for directories or 404s
 return false;

package/scripts/dev.js

@@ -23,6 +23,18 @@ async function startDev() {
             fwRoot = config.framework;
         }
     }
+
+    // Run build-components.js BEFORE starting servers to ensure
+    // active-themes.php, _uikit_dynamic.scss, _slider_dynamic.js etc. exist on first request
+    const buildComponentsPath = path.join(fwRoot, 'scripts/build-components.js');
+    console.log('[Squeditor] 🔧 Building dynamic components...');
+    const { execSync } = require('child_process');
+    try {
+        execSync(`node "${buildComponentsPath}"`, { stdio: 'inherit', cwd: projectRoot });
+    } catch (e) {
+        console.error('[Squeditor] ❌ Failed to build dynamic components:', e.message);
+    }
+
     const devRouterPath = path.join(fwRoot, 'scripts/dev-router.php');
 
     // Start PHP Server
@@ -35,7 +47,6 @@ async function startDev() {
         env: { ...process.env, SQUEDITOR_PHP_PORT: phpPort, SQUEDITOR_VITE_PORT: vitePort }
     });
 
-    // Start Vite
     const vite = spawn('npx', [
         'vite',
         '--port', vitePort.toString(),
@@ -45,6 +56,24 @@ async function startDev() {
         env: { ...process.env, SQUEDITOR_PHP_PORT: phpPort, SQUEDITOR_VITE_PORT: vitePort }
     });
 
+    // Watch squeditor.config.js for changes and rebuild dynamic components
+    if (fs.existsSync(configPath)) {
+        let rebuildTimeout;
+        fs.watch(configPath, (eventType) => {
+            if (eventType === 'change') {
+                // Debounce to prevent multiple triggers from IDE saves
+                clearTimeout(rebuildTimeout);
+                rebuildTimeout = setTimeout(() => {
+                    console.log(`\n[Squeditor] 🔄 Config changed. Rebuilding dynamic components...`);
+                    const buildScript = spawn('node', [path.join(fwRoot, 'scripts/build-components.js')], { stdio: 'inherit' });
+                    buildScript.on('close', (code) => {
+                        if (code === 0) console.log(`[Squeditor] ✨ Rebuild complete! (Vite will hot-reload automatically)`);
+                    });
+                }, 300);
+            }
+        });
+    }
+
     process.on('SIGINT', () => {
         php.kill();
         vite.kill();

package/scripts/package-customer.js

@@ -16,10 +16,11 @@ try {
     ffmpeg = require(path.join(projectRoot, 'node_modules/fluent-ffmpeg'));
 } catch (e) { }
 
-const customerBuildDir = path.join(projectRoot, 'build-customer-package');
+const customerBuildDir = path.join(projectRoot, config.name || 'customer-package');
 const distDir = path.join(projectRoot, 'dist');
 const srcDir = path.join(projectRoot, 'src');
-const zipName = config.dist.zipName ? config.dist.zipName.replace('.zip', '-customer.zip') : 'customer-package.zip';
+// Derive ZIP name from config.name directly to avoid double-suffix issues
+const zipName = (config.name || 'customer-package') + '.zip';
 const zipPath = path.join(projectRoot, zipName);
 
 const mediaConfig = config.media || {};
@@ -116,40 +117,61 @@ async function walkAndProcessMedia(currentSrc, currentDest, baseDir) {
 async function createCustomerPackage() {
     console.log('[Squeditor] 📦 Assembling Customer Package...');
 
+    if (path.resolve(customerBuildDir) === path.resolve(projectRoot)) {
+        console.error(`[Squeditor] 🚨 CRITICAL ERROR: customerBuildDir resolves to the active project workspace root!`);
+        console.error(`[Squeditor] Aborting immediately to prevent recursive deletion. Please update 'name' in your squeditor.config.js so it does not target the parent folder (e.g., avoid '../folder-name').`);
+        process.exit(1);
+    }
+
     if (fs.existsSync(customerBuildDir)) {
         try {
-            execSync(`rm -rf "${customerBuildDir}"`);
+            fs.rmSync(customerBuildDir, { recursive: true, force: true });
         } catch (e) {
-            console.warn(`   - ⚠️  Warning: Could not fully clean ${customerBuildDir}. You may need to run 'sudo rm -rf' on it manually.`);
+            console.warn(`   - ⚠️  Warning: Could not fully clean ${customerBuildDir}. You may need to remove it manually.`);
         }
     }
     if (fs.existsSync(zipPath)) {
         fs.unlinkSync(zipPath);
     }
 
-    fs.mkdirSync(path.join(customerBuildDir, 'src/assets'), { recursive: true });
+    fs.mkdirSync(path.join(customerBuildDir, 'dist/assets'), { recursive: true });
 
-    console.log('   - Copying compiled HTML to src/');
+    console.log('   - Copying compiled HTML to dist/ and src/');
     const distHtmlFiles = fs.readdirSync(distDir).filter(file => file.endsWith('.html'));
+    fs.mkdirSync(path.join(customerBuildDir, 'src'), { recursive: true });
 
     distHtmlFiles.forEach(file => {
         let htmlContent = fs.readFileSync(path.join(distDir, file), 'utf8');
-        htmlContent = htmlContent.replace(
-            /<link rel="stylesheet" href="assets\/css\/main_css\.css">/g,
-            '<link rel="stylesheet" href="assets/scss/main.scss">'
-        );
-        htmlContent = htmlContent.replace(
-            /<script src="assets\/js\/uikit-components\.js"><\/script>/g,
-            '<script type="module" src="assets/js/uikit-components.js"></script>'
-        );
-        fs.writeFileSync(path.join(customerBuildDir, 'src', file), htmlContent);
+        // dist/ gets production HTML referencing compiled CSS
+        fs.writeFileSync(path.join(customerBuildDir, 'dist', file), htmlContent);
+        // src/ gets dev HTML: rewrite CSS refs to raw SCSS for Vite HMR
+        let devHtml = htmlContent;
+        devHtml = devHtml.replace(/href="assets\/css\/main\.min\.css"/g, 'href="assets/scss/main.scss"');
+        devHtml = devHtml.replace(/href="assets\/css\/tailwind\.css"/g, 'href="assets/css/tailwind.css"');
+        fs.writeFileSync(path.join(customerBuildDir, 'src', file), devHtml);
     });
 
-    console.log('   - Copying necessary assets to src/assets');
+    console.log('   - Copying necessary developer source files to src/assets');
     fs.mkdirSync(path.join(customerBuildDir, 'src/assets/css'), { recursive: true });
+    // Also copy dist production files
+    fs.mkdirSync(path.join(customerBuildDir, 'dist/assets/css'), { recursive: true });
+    
     fs.copyFileSync(path.join(distDir, 'assets/css/tailwind.css'), path.join(customerBuildDir, 'src/assets/css/tailwind.css'));
+    fs.copyFileSync(path.join(distDir, 'assets/css/tailwind.css'), path.join(customerBuildDir, 'dist/assets/css/tailwind.css'));
+    
     if (fs.existsSync(path.join(distDir, 'assets/css/squeditor-icons.css'))) {
         fs.copyFileSync(path.join(distDir, 'assets/css/squeditor-icons.css'), path.join(customerBuildDir, 'src/assets/css/squeditor-icons.css'));
+        fs.copyFileSync(path.join(distDir, 'assets/css/squeditor-icons.css'), path.join(customerBuildDir, 'dist/assets/css/squeditor-icons.css'));
+    }
+    
+    if (fs.existsSync(path.join(distDir, 'assets/css/main.min.css'))) {
+        fs.copyFileSync(path.join(distDir, 'assets/css/main.min.css'), path.join(customerBuildDir, 'dist/assets/css/main.min.css'));
+    }
+
+    // slider.min.css contains the slider library CSS (Splide/Swiper)
+    if (fs.existsSync(path.join(distDir, 'assets/css/slider.min.css'))) {
+        fs.copyFileSync(path.join(distDir, 'assets/css/slider.min.css'), path.join(customerBuildDir, 'src/assets/css/slider.min.css'));
+        fs.copyFileSync(path.join(distDir, 'assets/css/slider.min.css'), path.join(customerBuildDir, 'dist/assets/css/slider.min.css'));
     }
 
     fs.cpSync(path.join(srcDir, 'assets/scss'), path.join(customerBuildDir, 'src/assets/scss'), { recursive: true });
@@ -167,13 +189,19 @@ async function createCustomerPackage() {
     }
 
     fs.mkdirSync(path.join(customerBuildDir, 'src/assets/js'), { recursive: true });
+    fs.mkdirSync(path.join(customerBuildDir, 'dist/assets/js'), { recursive: true });
     fs.copyFileSync(path.join(distDir, 'assets/js/uikit-components.js'), path.join(customerBuildDir, 'src/assets/js/uikit-components.js'));
+    fs.copyFileSync(path.join(distDir, 'assets/js/uikit-components.js'), path.join(customerBuildDir, 'dist/assets/js/uikit-components.js'));
     fs.copyFileSync(path.join(distDir, 'assets/js/main.js'), path.join(customerBuildDir, 'src/assets/js/main.js'));
+    fs.copyFileSync(path.join(distDir, 'assets/js/main.js'), path.join(customerBuildDir, 'dist/assets/js/main.js'));
 
     const staticDistPath = path.join(distDir, 'assets/static');
-    const staticCustomerPath = path.join(customerBuildDir, 'src/assets/static');
+    const staticCustomerSourcePath = path.join(customerBuildDir, 'src/assets/static');
+    const staticCustomerDistPath = path.join(customerBuildDir, 'dist/assets/static');
     if (fs.existsSync(staticDistPath)) {
-        await walkAndProcessMedia(staticDistPath, staticCustomerPath, staticDistPath);
+        await walkAndProcessMedia(staticDistPath, staticCustomerSourcePath, staticDistPath);
+        // Also move these final processed media assets directly from src/ back to dist/
+        fs.cpSync(staticCustomerSourcePath, staticCustomerDistPath, { recursive: true });
     }
 
     console.log('   - Generating lean package.json and vite.config.js');
@@ -256,13 +284,16 @@ ${rollupInputs}            },
     const postcssConfig = `module.exports = {\n  plugins: {\n    tailwindcss: {},\n    autoprefixer: {},\n  },\n}`;
     fs.writeFileSync(path.join(customerBuildDir, 'postcss.config.js'), postcssConfig);
 
-    const readmeContent = `# ${config.name} - Customer Package\n\nThis package contains everything you need to use, customize, and deploy your template.\n\n## Directory Structure\n- \`src/\`: Source HTML files.\n- \`src/assets/\`: Source files for customization (SCSS, JS, Images).\n\n## How to Customize Styles\n1. Install dependencies: \`npm install\`\n2. Run live development server: \`npm run dev\`\n3. Build production assets: \`npm run build\`\n`;
+    const readmeContent = `# ${config.name} - Customer Package\n\nThis package contains everything you need to use, customize, and deploy your template.\n\n## Directory Structure\n- \`src/\`: Developer Source files (\`npm run dev\` needed).\n- \`dist/\`: Production-ready compiled HTML snapshot (Drop into any hosting).\n\n## How to Customize Styles\n1. Install dependencies: \`npm install\`\n2. Run live development server: \`npm run dev\`\n3. Edit styles in \`src/assets/scss/main.scss\`\n4. Build production assets to \`dist/\`: \`npm run build\`\n`;
     fs.writeFileSync(path.join(customerBuildDir, 'README.md'), readmeContent);
 
+    // Format customer HTML files with Prettier (fallback in case snapshot.js Prettier was skipped)
     try {
         console.log('   - Formatting customer HTML files with Prettier...');
-        execSync('npx prettier --write "src/**/*.html" --print-width 10000 --tab-width 4', { cwd: customerBuildDir, stdio: 'ignore' });
-    } catch (e) { }
+        execSync('npx prettier --write "src/**/*.html" "dist/**/*.html" --print-width 10000 --tab-width 4', { cwd: customerBuildDir, stdio: 'ignore' });
+    } catch (e) {
+        console.warn('   - ⚠️  Prettier formatting skipped.');
+    }
 
     console.log(`[Squeditor] 📦 Zipping Customer Package to ${zipName}...`);
     try {

package/scripts/package-dist.js

@@ -20,7 +20,7 @@ try {
     // Explicitly clean up any .DS_Store files that might have been created by the OS
     execSync(`find "${distDir}" -name ".DS_Store" -delete`, { stdio: 'inherit' });
     execSync(`cd "${distDir}" && zip -r -9 "${zipPath}" . -x "*.DS_Store" -x "*/.DS_Store"`, { stdio: 'inherit' });
-    console.log(`[Squeditor] ✅ Customer Ready: ${zipName}`);
+    console.log(`[Squeditor] ✅ Dist ZIP Ready: ${zipName}`);
 } catch (e) {
     console.error(`[Squeditor] ❌ Failed to create ZIP archive using system zip.`, e);
 }

package/scripts/scaffold.js

@@ -52,7 +52,8 @@ const frameworkTargetDir = path.resolve(process.cwd(), 'squeditor-framework');
 
 if (!fs.existsSync(frameworkTargetDir)) {
     console.log(`[Squeditor] Installing local framework core at ./squeditor-framework...`);
-    const ignoreCoreList = ['project-template', 'showcase', 'node_modules', '.git', '.github'];
+    // Pass the name of the target directory to the ignore list to prevent infinite loop
+    const ignoreCoreList = ['project-template', 'showcase', 'node_modules', '.git', '.github', 'squeditor-framework'];
     copyDirectory(frameworkSourceDir, frameworkTargetDir, ignoreCoreList);
 }
 
@@ -71,8 +72,8 @@ if (fs.existsSync(pkgJsonPath)) {
 const configPath = path.join(targetDir, 'squeditor.config.js');
 if (fs.existsSync(configPath)) {
     let configContent = fs.readFileSync(configPath, 'utf8');
-    configContent = configContent.replace(/name:\s*['"][^'"]+['"]/, `name: '${projectName}'`);
-    configContent = configContent.replace(/zipName:\s*['"][^'"]+['"]/, `zipName: '${projectName}.zip'`);
+    configContent = configContent.replace(/name:\s*['"][^'"]+['"]/, `name: '${projectName}-customer'`);
+    configContent = configContent.replace(/zipName:\s*['"][^'"]+['"]/, `zipName: '${projectName}-customer.zip'`);
     fs.writeFileSync(configPath, configContent);
 }
 

package/scripts/snapshot.js

@@ -1,49 +1,114 @@
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
-const { spawn } = require('child_process');
+const { spawn, execSync } = require('child_process');
 
 const projectRoot = process.cwd();
 const config = require(path.join(projectRoot, 'squeditor.config.js'));
+const resolvePages = require('./utils/resolve-pages');
+const getAvailablePort = require('./get-port');
 
-const { baseUrl, pages, outputDir, rewriteExtension } = config.snapshot;
+const { outputDir, rewriteExtension } = config.snapshot;
 const distDir = path.join(projectRoot, outputDir);
 
-fs.mkdirSync(distDir, { recursive: true });
+// Build a reverse lookup: pagePath -> themeKey
+// This allows snapshot.pages to be the AUTHORITATIVE list while themes are applied per-page
+function buildThemeLookup() {
+    const lookup = {};
+    if (config.themes) {
+        for (const [themeKey, theme] of Object.entries(config.themes)) {
+            const resolvedThemePages = resolvePages(theme.pages || [], projectRoot);
+            for (const p of resolvedThemePages) {
+                lookup[p] = { themeKey, distSubfolder: theme.distSubfolder || '' };
+            }
+        }
+    }
+    return lookup;
+}
 
-// Start PHP built-in server
-const phpServer = spawn('php', [
-    '-S', '127.0.0.1:' + config.devServer.port,
-    '-t', path.join(projectRoot, 'src')
-], {
-    stdio: 'ignore',
-    env: { ...process.env, SQUEDITOR_SNAPSHOT: '1' }
-});
+// Poll the PHP server until it responds (max ~10 seconds)
+function waitForServer(url, maxRetries = 50, interval = 200) {
+    return new Promise((resolve, reject) => {
+        let attempts = 0;
+        const check = () => {
+            http.get(url, (res) => {
+                resolve();
+            }).on('error', () => {
+                attempts++;
+                if (attempts >= maxRetries) {
+                    reject(new Error('PHP server failed to start within timeout'));
+                } else {
+                    setTimeout(check, interval);
+                }
+            });
+        };
+        check();
+    });
+}
+
+async function runSnapshot() {
+    fs.mkdirSync(distDir, { recursive: true });
 
-// Wait for PHP server to start
-setTimeout(async () => {
-    console.log('[Squeditor] 📸 Starting snapshot...');
+    // Use a dynamic port to avoid collisions with a running dev server
+    const snapshotPort = await getAvailablePort(config.devServer.port + 100);
+    const snapshotBaseUrl = `http://127.0.0.1:${snapshotPort}`;
 
-    const themes = config.themes || { default: { pages: config.snapshot.pages, distSubfolder: '' } };
+    // Resolve dev-router path for proper .html and extensionless URL handling
+    const fwRoot = path.resolve(projectRoot, config.framework);
+    const devRouterPath = path.join(fwRoot, 'scripts/dev-router.php');
+
+    // Start PHP built-in server WITH the dev-router
+    const phpServer = spawn('php', [
+        '-S', `127.0.0.1:${snapshotPort}`,
+        '-t', path.join(projectRoot, 'src'),
+        devRouterPath
+    ], {
+        stdio: 'ignore',
+        env: { ...process.env, SQUEDITOR_SNAPSHOT: '1' }
+    });
 
-    for (const [themeKey, theme] of Object.entries(themes)) {
-        const themeDistDir = path.join(distDir, theme.distSubfolder || '');
-        fs.mkdirSync(themeDistDir, { recursive: true });
+    try {
+        // Wait for PHP server to be ready instead of a fixed timeout
+        await waitForServer(snapshotBaseUrl);
 
-        for (const pagePath of theme.pages) {
+        console.log('[Squeditor] 📸 Starting snapshot...');
+
+        // snapshot.pages is the AUTHORITATIVE list of pages to capture
+        const allPages = resolvePages(config.snapshot.pages || ['*'], projectRoot);
+        const themeLookup = buildThemeLookup();
+
+        for (const pagePath of allPages) {
             try {
+                // Determine which theme applies to this page (default if not in any theme)
+                const themeInfo = themeLookup[pagePath] || { themeKey: 'default', distSubfolder: '' };
+                const { themeKey, distSubfolder } = themeInfo;
+
                 console.log(`[Squeditor] Fetching ${pagePath} (Theme: ${themeKey})...`);
-                const urlToFetch = `${baseUrl}${pagePath}?theme=${themeKey}&snapshot=1`;
+
+                // Resolve fetch URI: '/' -> '/index.php'
+                let fetchUri = pagePath;
+                if (fetchUri === '/') fetchUri = '/index.php';
+
+                const normalizedPagePath = fetchUri.startsWith('/') ? fetchUri : `/${fetchUri}`;
+                const urlToFetch = `${snapshotBaseUrl}${normalizedPagePath}?theme=${themeKey}&snapshot=1`;
                 const html = await fetchPage(urlToFetch);
-                const rewrittenHtml = rewriteLinks(html);
 
-                // Remove leading slash for local save path
-                let savePath = pagePath.startsWith('/') ? pagePath.slice(1) : pagePath;
-                if (savePath === '') savePath = 'index.html';
-                if (rewriteExtension && savePath.endsWith('.php')) {
-                    savePath = savePath.replace(/\.php$/, '.html');
+                // Construct save path
+                let savePath = pagePath;
+                if (savePath === '/' || savePath === '') {
+                    savePath = 'index.html';
+                } else {
+                    savePath = savePath.startsWith('/') ? savePath.slice(1) : savePath;
+                    if (rewriteExtension && savePath.endsWith('.php')) {
+                        savePath = savePath.replace(/\.php$/, '.html');
+                    }
                 }
 
+                const themeDistDir = path.join(distDir, distSubfolder);
+                fs.mkdirSync(themeDistDir, { recursive: true });
+
+                const rewrittenHtml = rewriteLinks(html, savePath, distSubfolder);
+
                 const fullPath = path.join(themeDistDir, savePath);
                 fs.mkdirSync(path.dirname(fullPath), { recursive: true });
                 fs.writeFileSync(fullPath, rewrittenHtml);
@@ -51,15 +116,32 @@ setTimeout(async () => {
                 console.error(`[Squeditor] Failed to snapshot ${pagePath}:`, err.message);
             }
         }
+
+        // Format all generated HTML with Prettier
+        try {
+            console.log('[Squeditor] 💅 Formatting dist HTML with Prettier...');
+            execSync(`npx prettier --write "${outputDir}/**/*.html" --print-width 10000 --tab-width 4`, { cwd: projectRoot, stdio: 'ignore' });
+        } catch (e) {
+            console.warn('[Squeditor] ⚠️  Prettier formatting skipped (not installed or errored).');
+        }
+
+        console.log('[Squeditor] 🏁 Snapshot complete.');
+    } finally {
+        phpServer.kill();
     }
+}
 
-    phpServer.kill();
-    console.log('[Squeditor] 🏁 Snapshot complete.');
-}, 1500);
+runSnapshot().catch(err => {
+    console.error('[Squeditor] ❌ Snapshot failed:', err.message);
+    process.exit(1);
+});
 
 function fetchPage(url) {
     return new Promise((resolve, reject) => {
         http.get(url, (res) => {
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                return reject(new Error(`Status Code: ${res.statusCode} for ${url}`));
+            }
             let data = '';
             res.on('data', chunk => data += chunk);
             res.on('end', () => resolve(data));
@@ -67,8 +149,27 @@ function fetchPage(url) {
     });
 }
 
-function rewriteLinks(html) {
-    if (!rewriteExtension) return html;
-    // Replace .php hrefs with .html
-    return html.replace(/href="([^"]*?)\.php([^"]*?)"/g, 'href="$1.html$2"');
+function rewriteLinks(html, savePath, distSubfolder) {
+    let result = html;
+    
+    // Calculate relative path back to dist root
+    const subfolderDepth = distSubfolder ? distSubfolder.split('/').filter(Boolean).length : 0;
+    const savePathDepth = path.dirname(savePath) === '.' ? 0 : path.dirname(savePath).split('/').length;
+    
+    const totalDepth = subfolderDepth + savePathDepth;
+    const prefix = totalDepth > 0 ? '../'.repeat(totalDepth) : '';
+
+    // Rewrite root-relative and purely relative references to depth-adjusted references
+    result = result.replace(/(href|src)=["']\/?([^"']+)["']/g, (match, attr, targetPath) => {
+        if (targetPath.startsWith('http') || targetPath.startsWith('//') || targetPath.startsWith('#')) {
+            return match;
+        }
+        return `${attr}="${prefix}${targetPath}"`;
+    });
+
+    if (rewriteExtension) {
+        result = result.replace(/href=["']([^"']*?)\.php([^"']*?)["']/g, 'href="$1.html$2"');
+    }
+    
+    return result;
 }

package/scripts/utils/resolve-pages.js

@@ -0,0 +1,47 @@
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function resolvePages(pagesConfig, projectRoot) {
+    if (!pagesConfig || !Array.isArray(pagesConfig)) return [];
+    
+    // Check if any element has a glob (* or !)
+    const hasGlob = pagesConfig.some(p => p.includes('*') || p.startsWith('!'));
+    
+    if (hasGlob) {
+        let micromatch;
+        try {
+            micromatch = require(path.join(projectRoot, 'node_modules/micromatch'));
+        } catch (e) {
+            console.warn('[Squeditor] micromatch not found. Please run npm install.');
+            return [];
+        }
+
+        const srcDir = path.join(projectRoot, 'src');
+        if (!fs.existsSync(srcDir)) return [];
+        
+        // Exclude known non-page PHP files that should never be snapshotted
+        const NON_PAGE_FILES = ['init.php'];
+        const allFiles = fs.readdirSync(srcDir)
+            .filter(f => f.endsWith('.php') && !NON_PAGE_FILES.includes(f));
+        
+        // Micromatch expects naked filenames logically. 
+        // We ensure config patterns like '/' become 'index.php' for matching, 
+        // and remove leading slashes so they match naked filenames natively.
+        const normalizedConfig = pagesConfig.map(p => {
+            if (p === '/') return 'index.php';
+            if (p.startsWith('/')) return p.slice(1);
+            return p;
+        });
+        
+        const matched = micromatch(allFiles, normalizedConfig);
+        
+        // Convert back to URL-style paths that the rest of the application expects
+        return matched.map(f => f === 'index.php' ? '/' : `/${f}`);
+    } else {
+        // Direct explicit list (legacy map support)
+        return pagesConfig.map(p => {
+            if (p === '/') return '/';
+            return p.startsWith('/') ? p : `/${p}`;
+        });
+    }
+};