juxscript 1.0.61 → 1.0.63

package/machinery/compiler.js

@@ -1,5 +1,5 @@
 import fs from 'fs';
-import path from 'path';
+import path, { parse } from 'path';
 import esbuild from 'esbuild';
 import * as acorn from 'acorn';
 
@@ -260,11 +260,11 @@ function findProjectFiles(dir, extensions, fileList = [], rootDir = dir, exclude
 
 /**
  * Bundle all .jux files into a single router-based main.js
- * ✅ MODIFIED: Vendor dependencies locally
+ * ✅ MODIFIED: Vendor dependencies locally + User Routes + Smart Import Merging
  */
 export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {}) {
   const startTime = performance.now();
-  const { routePrefix = '' } = options;
+  const { routePrefix = '', config } = options;
 
   console.log('🔀 Bundling .jux files into router...');
 
@@ -281,15 +281,20 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
     };
   }
 
-  console.log(`   Found ${juxFiles.length} .jux file(s)`);
+  const pages = config?.pages || {};
 
   const fileTimings = [];
   const views = [];
   const routes = [];
   const sharedModules = new Map(); // ✅ Map<filePath, exportCode>
-  const allImports = new Set();
+
+  // ✅ CHANGE: imports collection now stores context { code, filePath }
+  const allImports = [];
   const externalModules = new Set();  // ✅ NEW: Track external modules directly
 
+  // ✅ MAP for user config routing: Key = relative file path, Value = CleanFunctionName
+  const fileToFunction = new Map();
+
   for (const juxFile of juxFiles) {
     const fileStartTime = performance.now();
 
@@ -306,6 +311,11 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
       .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
       .join('');
 
+    // ✅ Store mapping for Config Route Resolution
+    // Store both 'path/file.jux' and normalized versions
+    fileToFunction.set(relativePath, cleanFunctionName);
+    fileToFunction.set(relativePath.split(path.sep).join('/'), cleanFunctionName);
+
     const routePath = routePrefix + '/' + (parsedPath.dir ? `${parsedPath.dir}/` : '') + parsedPath.name;
     const cleanRoutePath = routePath.replace(/\/+/g, '/');
 
@@ -321,7 +331,12 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
       ast.body.forEach(node => {
         if (node.type === 'ImportDeclaration') {
           const importStatement = juxContent.slice(node.start, node.end);
-          allImports.add(importStatement);
+
+          // ✅ Store Object with context instead of raw string
+          allImports.push({
+            code: importStatement,
+            filePath: relativePath // relative to projectRoot
+          });
 
           const moduleName = node.source.value;
           if (!moduleName.startsWith('.') &&
@@ -359,13 +374,52 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
     );
 
     views.push(viewFunction);
-    routes.push({ path: cleanRoutePath, functionName: cleanFunctionName });
+
+    // Auto-route based on filesystem
+    if (config?.defaults?.autoRoute !== false) {
+      routes.push({ path: cleanRoutePath, functionName: cleanFunctionName });
+    }
 
     const fileTime = performance.now() - fileStartTime;
     fileTimings.push({ file: relativePath, time: fileTime });
 
     const exportNote = hasExports ? ' [+exports]' : '';
-    console.log(`   ✓ ${relativePath} → ${cleanFunctionName}()${exportNote} (${fileTime.toFixed(1)}ms)`);
+    // console.log(`   ✓ ${relativePath} → ${cleanFunctionName}()${exportNote} (${fileTime.toFixed(1)}ms)`);
+  }
+
+  // ✅ PROCESS USER CONFIGURED ROUTES
+  if (pages) {
+    console.log('   🗺️  Mapping user-configured routes...');
+
+    const resolveAndAddRoute = (urlPath, targetFile) => {
+      // Clean up target file path (remove leading ./ and /)
+      const cleanTarget = targetFile.replace(/^(\.\/|\/)/, '');
+      const funcName = fileToFunction.get(cleanTarget);
+
+      if (funcName) {
+        // User routes take precedence (prepend to list)
+        routes.unshift({ path: urlPath, functionName: funcName });
+        console.log(`      ➕ ${urlPath} → ${funcName}`);
+      } else {
+        console.warn(`      ⚠️  Route target not found: ${targetFile} (Available keys: ${fileToFunction.size})`);
+      }
+    };
+
+    Object.entries(pages).forEach(([key, value]) => {
+      if (typeof value === 'string') {
+        // Direct mapping: '/' -> './experiments/state.jux'
+        resolveAndAddRoute(key, value);
+      } else if (typeof value === 'object') {
+        // Group mapping
+        const prefix = value.prefix || '';
+        const groupRoutes = value.routes || {};
+
+        Object.entries(groupRoutes).forEach(([routePath, targetFile]) => {
+          const fullPath = (prefix + routePath).replace(/\/+/g, '/');
+          resolveAndAddRoute(fullPath, targetFile);
+        });
+      }
+    });
   }
 
   // ✅ Show slowest files if any took >50ms
@@ -386,7 +440,7 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
 
   const vendoredPaths = await vendorExternalDependencies(externalModules, distDir);
 
-  const routerCode = generateRouterBundle(views, routes, sharedModules, allImports);
+  const routerCode = generateRouterBundle(views, routes, sharedModules, allImports, projectRoot);
   const bundleGenTime = performance.now() - bundleStartTime;
 
   const mainJsFilename = 'main.js';
@@ -578,6 +632,8 @@ function transformJuxToViewFunction(juxContent, functionName, pageName, relative
           });
         }
 
+        // ✅ CRITICAL FIX: Remove ALL imports so they don't break function scope
+        // They are hoisted by generateRouterBundle
         nodesToRemove.push({ start: node.start, end: node.end });
       }
 
@@ -652,35 +708,111 @@ function resolveImportPath(importPath, currentFilePath) {
 
 /**
  * Generate complete router bundle
+ * ✅ IMPROVED: Context-Aware Import Resolution (resolves ../paths before dedupe)
  */
-function generateRouterBundle(views, routes, sharedModules = new Map(), allImports = new Set()) {
-  const libImport = './lib/jux.js';
+function generateRouterBundle(views, routes, sharedModules = new Map(), allImports = [], projectRoot = '') {
+  const libImport = '/lib/jux.js'; // ✅ Use absolute path for core lib
 
-  // ✅ Filter out redundant imports
-  const filteredImports = Array.from(allImports)
-    .filter(imp => {
-      const impStr = imp.trim();
+  // Map<NormalizedSource, { defaults: Set<string>, named: Set<string>, namespace: string|null }>
+  const mergedImports = new Map();
 
-      // Remove imports from 'juxscript' (already imported)
-      if (impStr.includes("from 'juxscript'") || impStr.includes('from "juxscript"')) {
-        return false;
-      }
+  // Helper to resolve relative paths to a canonical string
+  const getCanonicalSource = (source, contextFilePath) => {
+    // 1. Keep externals/aliases/css/http as-is
+    if (!source.startsWith('.')) return source;
+    if (source.includes('.jux')) return source; // Skipped later anyway
 
-      // Remove imports from 'juxscript/reactivity' (already available)
-      if (impStr.includes("from 'juxscript/reactivity'") || impStr.includes('from "juxscript/reactivity"')) {
-        return false;
-      }
+    // 2. Resolve relative paths against the file they came from
+    // contextFilePath is relative to projectRoot (e.g. 'experiments/list.jux')
+    const dir = path.dirname(contextFilePath);
 
-      // ✅ CRITICAL: Remove ANY import that references a .jux file
-      if (impStr.includes('.jux')) {
-        return false;
+    // joinedPath is relative to projectRoot (e.g. '../lib/componentsv2')
+    const joinedPath = path.join(dir, source);
+
+    // 3. Normalize to alias if it points to lib
+    // Matches 'lib/componentsv2' or '../lib/componentsv2' variants
+    if (joinedPath.includes('lib/componentsv2')) {
+      return 'juxscript/componentsv2';
+    }
+    if (joinedPath.includes('lib/components')) {
+      return 'juxscript/components';
+    }
+
+    // 4. Fallback: return as-is (but normalized separators)
+    return joinedPath.replace(/\\/g, '/');
+  };
+
+  const importList = Array.isArray(allImports) ? allImports : Array.from(allImports);
+
+  for (const item of importList) {
+    const code = typeof item === 'string' ? item : item.code;
+    const filePath = typeof item === 'string' ? '' : item.filePath; // Context file path
+
+    try {
+      const ast = acorn.parse(code.trim(), { ecmaVersion: 'latest', sourceType: 'module' });
+      const node = ast.body[0];
+
+      if (node && node.type === 'ImportDeclaration') {
+        const rawSource = node.source.value;
+
+        // Skip base libs handled manually
+        if (rawSource === 'juxscript' || rawSource === 'juxscript/reactivity') continue;
+        if (rawSource.endsWith('.jux')) continue;
+
+        // ✅ RESOLVE SOURCE USING CONTEXT (Fixes ./lib/.. vs ../../lib/..)
+        const source = getCanonicalSource(rawSource, filePath);
+
+        if (!mergedImports.has(source)) {
+          mergedImports.set(source, { defaults: new Set(), named: new Set(), namespace: null });
+        }
+        const storage = mergedImports.get(source);
+
+        node.specifiers.forEach(spec => {
+          if (spec.type === 'ImportDefaultSpecifier') {
+            storage.defaults.add(spec.local.name);
+          } else if (spec.type === 'ImportSpecifier') {
+            if (spec.imported.name !== spec.local.name) {
+              storage.named.add(`${spec.imported.name} as ${spec.local.name}`);
+            } else {
+              storage.named.add(spec.imported.name);
+            }
+          } else if (spec.type === 'ImportNamespaceSpecifier') {
+            storage.namespace = spec.local.name;
+          }
+        });
       }
+    } catch (e) {
+      console.warn('⚠️  Failed to parse collected import:', code);
+    }
+  }
 
-      // Keep everything else (external libraries like axios, etc.)
-      return impStr.length > 0;
-    });
+  // Generate cleaned export list
+  const filteredImports = [];
+
+  mergedImports.forEach((storage, source) => {
+    // Namespace imports usually stand alone
+    if (storage.namespace) {
+      filteredImports.push(`import * as ${storage.namespace} from '${source}';`);
+    }
 
-  // ✅ Generate shared modules section (deduplicated by file)
+    const parts = [];
+    if (storage.defaults.size > 0) {
+      const arr = Array.from(storage.defaults);
+      parts.push(arr[0]);
+    }
+
+    if (storage.named.size > 0) {
+      parts.push(`{ ${Array.from(storage.named).sort().join(', ')} }`);
+    }
+
+    if (storage.defaults.size === 0 && storage.named.size === 0 && !storage.namespace) {
+      filteredImports.push(`import '${source}';`);
+    } else if (parts.length > 0) {
+      filteredImports.push(`import ${parts.join(', ')} from '${source}';`);
+    }
+  });
+
+  // Generate shared modules section (deduplicated by file)
   const sharedModulesCode = Array.from(sharedModules.values())
     .filter(code => code.trim())
     .join('\n\n');
@@ -807,9 +939,9 @@ render();
 
 /**
  * Generate a unified index.html for router bundle
- * ✅ MODIFIED: Use vendored paths instead of CDN
+ * ✅ MODIFIED: Use vendored paths instead of CDN + Hot Reload Script injection
  */
-export function generateIndexHtml(distDir, bundleResult) {
+export function generateIndexHtml(distDir, bundleResult, options = {}) {
   // ✅ ADD: Defensive check and fallback
   if (!bundleResult) {
     console.warn('⚠️  generateIndexHtml called without bundleResult, using defaults');
@@ -821,12 +953,36 @@ export function generateIndexHtml(distDir, bundleResult) {
   }
 
   const { mainJsFilename = 'main.js', routes = [], vendoredPaths = {} } = bundleResult;
+  const { isDev = false, wsPort = 3001 } = options;
 
   console.log('📄 Generating index.html...');
 
   // ✅ Use vendor import map
   const importMapScript = generateVendorImportMap(vendoredPaths);
 
+  // ✅ Client-side Hot Reload Script
+  const hotReloadScript = isDev ? `
+  <script>
+    (function() {
+      console.log('🔌 JUX Hot Reload: Connecting to port ${wsPort}...');
+      let ws = new WebSocket('ws://' + window.location.hostname + ':${wsPort}');
+      
+      ws.onopen = () => console.log('✅ JUX Hot Reload: Connected');
+      
+      ws.onmessage = (msg) => {
+        try {
+          const data = JSON.parse(msg.data);
+          if (data.type === 'reload') {
+            console.log('🔄 JUX Hot Reload: Refeshing...');
+            window.location.reload();
+          }
+        } catch(e) { console.error('HMR Error:', e); }
+      };
+      
+      ws.onclose = () => console.log('❌ JUX Hot Reload: Disconnected');
+    })();
+  </script>` : '';
+
   const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -838,6 +994,7 @@ export function generateIndexHtml(distDir, bundleResult) {
   <div id="app"></div>
   ${importMapScript}
   <script type="module" src="/${mainJsFilename}"></script>
+  ${hotReloadScript}
 </body>
 </html>`;
 
@@ -932,15 +1089,21 @@ async function vendorExternalDependencies(externalDeps, distDir) {
  * ✅ NEW: Generate import map with local vendor paths
  */
 function generateVendorImportMap(vendoredPaths) {
+  // ✅ FIX: Use ABSOLUTE paths (start with /) to support nested routes (e.g. /app/dashboard)
+  // When using ./, paths are resolved relative to the current URL, which breaks on sub-pages.
   const imports = {
-    "juxscript": "./lib/jux.js",
-    "juxscript/": "./lib/",
-    "juxscript/reactivity": "./lib/reactivity/state.js",
-    "juxscript/presets/": "./presets/",
-    "juxscript/components/": "./lib/components/",
+    "juxscript/componentsv2": "/lib/componentsv2/index.js",  //
+    "juxscript/componentsv2/": "/lib/componentsv2/",        //
     ...vendoredPaths  // ✅ These are LOCAL paths: "./vendor/axios.js"
   };
 
+  // Ensure all paths start with / to survive pushState routing
+  Object.keys(imports).forEach(key => {
+    if (imports[key].startsWith('./')) {
+      imports[key] = imports[key].substring(1);
+    }
+  });
+
   return `<script type="importmap">
 ${JSON.stringify({ imports }, null, 2)}
 </script>`;

package/machinery/config.js

@@ -23,12 +23,12 @@ export const defaultConfig = {
 // Load user configuration
 export async function loadConfig(projectRoot) {
   const configPath = path.join(projectRoot, 'juxconfig.js');
-  
+
   if (fs.existsSync(configPath)) {
     try {
       const configModule = await import(`file://${configPath}`);
       const userConfig = configModule.default || configModule;
-      
+
       return {
         ...defaultConfig,
         ...userConfig,
@@ -41,7 +41,7 @@ export async function loadConfig(projectRoot) {
       return defaultConfig;
     }
   }
-  
+
   console.log('ℹ️  No juxconfig.js found, using defaults');
   return defaultConfig;
 }
@@ -51,9 +51,9 @@ export async function runBootstrap(bootstrapFunctions = []) {
   if (!Array.isArray(bootstrapFunctions) || bootstrapFunctions.length === 0) {
     return;
   }
-  
+
   console.log('🚀 Running bootstrap functions...\n');
-  
+
   for (const fn of bootstrapFunctions) {
     if (typeof fn === 'function') {
       try {
@@ -63,6 +63,93 @@ export async function runBootstrap(bootstrapFunctions = []) {
       }
     }
   }
-  
+
   console.log('✅ Bootstrap complete\n');
+}
+
+/**
+ * Type helper for JUX Configuration (Identity function for Autocomplete)
+ * Used in juxconfig.js to provide Intellisense.
+ * @param {import('../types/config').JuxConfig} config
+ * @returns {import('../types/config').JuxConfig}
+ */
+export function defineConfig(config) {
+  return config;
+}
+
+/**
+ * Normalizes user configuration into the strict format used by the compiler/server.
+ * Handles "DX Sugar" like:
+ * - Inferring file extensions (.jux, .css)
+ * - Mapping 'dist' -> 'distribution'
+ * - Resolving shortcuts (e.g. layouts)
+ * - Defaulting ports
+ */
+export function resolveConfig(userConfig, projectRoot = process.cwd()) {
+  const root = userConfig.root || projectRoot;
+
+  // 1. Directories (Map 'dist' alias to 'distribution')
+  const dirs = userConfig.directories || {};
+  const directories = {
+    source: dirs.source || 'jux',
+    distribution: dirs.dist || dirs.distribution || '.jux-dist',
+    themes: dirs.themes || 'themes',
+    layouts: dirs.layouts || 'themes/layouts',
+    assets: dirs.assets || 'themes/assets'
+  };
+
+  // 2. Defaults (Infer extensions)
+  const defs = userConfig.defaults || {};
+  const httpPort = defs.port || defs.httpPort || 3000;
+
+  const defaults = {
+    httpPort,
+    wsPort: defs.wsPort || (httpPort + 1),
+    autoRoute: defs.autoRoute !== false, // default true
+    layout: ensureExt(defs.layout, '.jux') || 'base.jux',
+    theme: ensureExt(defs.theme, '.css') || 'base.css'
+  };
+
+  // 3. Pages Normalization (Recursively fix route paths)
+  const pages = normalizePages(userConfig.pages || {});
+
+  // 4. Return Normalized Config
+  return {
+    root,
+    directories,
+    defaults,
+    pages,
+    hooks: userConfig.hooks || {}
+  };
+}
+
+/**
+ * Helper: Appends extension if missing
+ */
+function ensureExt(file, ext) {
+  if (!file) return file;
+  return file.endsWith(ext) ? file : `${file}${ext}`;
+}
+
+/**
+ * Helper: Recursively normalizes page routes
+ */
+function normalizePages(pages) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(pages)) {
+    if (typeof value === 'string') {
+      // Direct route: '/' -> 'experiments/index'
+      // Becomes: '/' -> 'experiments/index.jux'
+      normalized[key] = ensureExt(value, '.jux');
+    } else if (typeof value === 'object') {
+      // Route Group
+      normalized[key] = {
+        ...value,
+        layout: value.layout ? ensureExt(value.layout, '.jux') : undefined,
+        theme: value.theme ? ensureExt(value.theme, '.css') : undefined,
+        routes: normalizePages(value.routes || {})
+      };
+    }
+  }
+  return normalized;
 }

package/machinery/diagnose.js

@@ -0,0 +1,72 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { bundleJuxFilesToRouter, generateIndexHtml } from './compiler.js';
+import { verifyStaticBuild } from './verifier.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+const DIST_DIR = path.join(__dirname, '.temp_dist_test');
+
+// Setup temp dir
+if (!fs.existsSync(DIST_DIR)) fs.mkdirSync(DIST_DIR);
+
+async function runTest(fileName, description) {
+    console.log(`\n🧪 TEST: ${description} (${fileName})`);
+    console.log('   Context: Trying to build a broken file...');
+
+    const srcFile = path.join(FIXTURES_DIR, fileName);
+
+    // Mock finding files by explicitly passing our bad file as the "source"
+    // Since bundleJuxFilesToRouter takes a directory, we need to create a temp source dir
+    const tempSrcDir = path.join(__dirname, '.temp_src_' + Date.now());
+    fs.mkdirSync(tempSrcDir);
+    fs.copyFileSync(srcFile, path.join(tempSrcDir, 'index.jux'));
+
+    let buildSuccess = false;
+
+    try {
+        // 1. Attempt Bundle
+        const result = await bundleJuxFilesToRouter(tempSrcDir, DIST_DIR, { routePrefix: '' });
+
+        // 2. Generate HTML (needed for verifier to check import map)
+        generateIndexHtml(DIST_DIR, result);
+
+        // 3. Run Verifier
+        const verified = verifyStaticBuild(DIST_DIR);
+
+        if (!verified) {
+            console.log('   ✅ SUCCESS: Verifier correctly caught the error!');
+            buildSuccess = false;
+        } else {
+            console.log('   ❌ FAILURE: Build passed but should have failed verification.');
+            buildSuccess = true;
+        }
+
+    } catch (e) {
+        console.log(`   ✅ SUCCESS: Compiler threw error as expected:`);
+        console.log(`      "${e.message.split('\n')[0]}"`);
+        buildSuccess = false;
+    } finally {
+        // Cleanup
+        fs.rmSync(tempSrcDir, { recursive: true, force: true });
+    }
+
+    return !buildSuccess;
+}
+
+async function main() {
+    console.log('🩺 JUX FAILURE DIAGNOSTICS\n');
+
+    // Test 1: bad_syntax.jux (Should throw during compile)
+    await runTest('bad_syntax.jux', 'Syntax Error Detection');
+
+    // Test 2: ghost_dep.jux (Should pass compile, fail verification)
+    await runTest('ghost_dep.jux', 'Ghost Dependency Detection');
+
+    // Cleanup Dist
+    fs.rmSync(DIST_DIR, { recursive: true, force: true });
+    console.log('\n🏁 Diagnostics Complete');
+}
+
+main();

package/machinery/jux-module-pattern.md

@@ -0,0 +1,118 @@
+# JUX Module Pattern
+
+## Overview
+A `.jux` file can export a component-like interface with:
+- Configuration options
+- Public API methods
+- Event emissions (EDR pattern)
+- Internal/shared state
+- Props (getters)
+
+## Pattern Structure
+
+```javascript
+// calendar.jux
+import { jux, state } from 'juxscript';
+
+// ═══════════════════════════════════════════════════════════════════
+// MODULE DEFINITION
+// ═══════════════════════════════════════════════════════════════════
+
+export default function Calendar(id, options = {}) {
+    // Internal state
+    const today = new Date();
+    const currentMonth = state(options.initialMonth ?? today.getMonth());
+    const currentYear = state(options.initialYear ?? today.getFullYear());
+    const selectedDate = state(null);
+    
+    // Event emitters (EDR pattern)
+    const events = {
+        dateSelect: [],
+        monthChange: [],
+        yearChange: []
+    };
+    
+    // Emit helper
+    const emit = (eventName, data) => {
+        events[eventName]?.forEach(handler => handler(data));
+    };
+    
+    // Public API
+    const api = {
+        // Props (getters)
+        get currentMonth() { return currentMonth.value; },
+        get currentYear() { return currentYear.value; },
+        get selectedDate() { return selectedDate.value; },
+        
+        // Methods
+        nextMonth() {
+            let month = currentMonth.value + 1;
+            let year = currentYear.value;
+            if (month > 11) { month = 0; year++; }
+            currentMonth.set(month);
+            currentYear.set(year);
+            emit('monthChange', { month, year });
+            return api;
+        },
+        
+        prevMonth() {
+            let month = currentMonth.value - 1;
+            let year = currentYear.value;
+            if (month < 0) { month = 11; year--; }
+            currentMonth.set(month);
+            currentYear.set(year);
+            emit('monthChange', { month, year });
+            return api;
+        },
+        
+        selectDate(date) {
+            selectedDate.set(date);
+            emit('dateSelect', { date });
+            return api;
+        },
+        
+        // Event binding (EDR consumer registration)
+        on(eventName, handler) {
+            if (events[eventName]) {
+                events[eventName].push(handler);
+            }
+            return api;
+        },
+        
+        // Render
+        render(targetId) {
+            // Build UI components...
+            return api;
+        },
+        
+        // Expose for chaining
+        id
+    };
+    
+    return api;
+}
+```
+
+## Usage
+
+```javascript
+// app.jux
+import Calendar from './calendar.jux';
+
+const cal = Calendar('my-calendar', {
+    initialMonth: 11,
+    initialYear: 2024
+})
+.on('dateSelect', ({ date }) => {
+    console.log('Date selected:', date);
+})
+.on('monthChange', ({ month, year }) => {
+    console.log('Month changed:', month, year);
+})
+.render('#app');
+
+// Public API
+cal.nextMonth();
+cal.prevMonth();
+console.log(cal.currentMonth); // getter
+```