juxscript 1.0.23 → 1.0.25

package/bin/cli.js

@@ -49,7 +49,6 @@ console.log(`   Output:   ${PATHS.frontendDist}`);
 console.log(`   Lib:      ${PATHS.juxLib}\n`);
 
 const command = process.argv[2];
-const subCommand = process.argv[3]; // For serve <pagename>
 const watchMode = process.argv.includes('--watch');
 const bundleMode = process.argv.includes('--bundle');
 
@@ -234,28 +233,31 @@ async function buildProject(isServe = false) {
     // Create structure
     fs.mkdirSync(juxDir, { recursive: true });
 
-    // Copy hey.jux from presets as starter template
-    const heyTemplatePath = path.join(PATHS.packageRoot, 'presets', 'hey.jux');
-    const heyTargetPath = path.join(juxDir, 'hey.jux');
+    // Copy hey.jux as the starter template
+    const heyJuxSrc = path.join(PATHS.packageRoot, 'presets', 'hey.jux');
+    const heyJuxDest = path.join(juxDir, 'index.jux');
 
-    if (fs.existsSync(heyTemplatePath)) {
-      fs.copyFileSync(heyTemplatePath, heyTargetPath);
-      console.log('+ Created jux/hey.jux (starter template)');
+    if (fs.existsSync(heyJuxSrc)) {
+      fs.copyFileSync(heyJuxSrc, heyJuxDest);
+      console.log('+ Created jux/index.jux from hey.jux template');
     } else {
-      console.warn('⚠️  hey.jux template not found in presets/');
+      console.warn('⚠️  hey.jux template not found, creating basic file');
+      const basicContent = `import { jux } from 'juxscript';\n\njux.heading('welcome').text('Welcome to JUX').render('#app');`;
+      fs.writeFileSync(heyJuxDest, basicContent);
+      console.log('+ Created jux/index.jux');
     }
 
-    // Copy over presets/*.css as styles/ to jux/
-    const presetsSrc = path.join(PATHS.packageRoot, 'presets');
+    // Copy preset styles from presets/styles/ to jux/styles/
+    const presetsStylesSrc = path.join(PATHS.packageRoot, 'presets', 'styles');
     const stylesDest = path.join(juxDir, 'styles');
 
-    if (fs.existsSync(presetsSrc)) {
+    if (fs.existsSync(presetsStylesSrc)) {
       fs.mkdirSync(stylesDest, { recursive: true });
 
-      const presetFiles = fs.readdirSync(presetsSrc);
-      presetFiles.forEach(file => {
+      const styleFiles = fs.readdirSync(presetsStylesSrc);
+      styleFiles.forEach(file => {
         if (file.endsWith('.css')) {
-          const srcFile = path.join(presetsSrc, file);
+          const srcFile = path.join(presetsStylesSrc, file);
           const destFile = path.join(stylesDest, file);
           fs.copyFileSync(srcFile, destFile);
           console.log(`+ Copied preset style: styles/${file}`);
@@ -279,7 +281,7 @@ async function buildProject(isServe = false) {
         }
       };
       fs.writeFileSync(pkgPath, JSON.stringify(pkgContent, null, 2));
-      console.log('✅ Created package.json');
+      console.log('+ Created package.json');
     }
 
     // Create .gitignore
@@ -294,9 +296,10 @@ node_modules/
       console.log('+ Created .gitignore');
     }
 
-    console.log('+ Created jux/ directory\n');
+    console.log('\n✅ JUX project initialized!\n');
     console.log('Next steps:');
-    console.log('  npx jux serve hey        # Start dev server for hey.jux\n');
+    console.log('  npm install              # Install dependencies');
+    console.log('  npx jux serve            # Start dev server with hot reload\n');
     console.log('Check out the docs: https://juxscript.com/docs\n');
 
   } else if (command === 'build') {
@@ -305,37 +308,35 @@ node_modules/
     console.log(`✅ Build complete: ${PATHS.frontendDist}`);
 
   } else if (command === 'serve') {
-    // ✅ Serve with optional page parameter
-    const pageName = subCommand; // e.g., "hey" from "npx jux serve hey"
-
-    if (pageName) {
-      console.log(`🎯 Serving specific page: ${pageName}\n`);
-    }
-
+    // ✅ Always serves router bundle
     await buildProject(true);
 
-    const port = pageName ? 3000 : (parseInt(subCommand) || 3000);
+    // Parse port arguments: npx jux serve [httpPort] [wsPort]
+    const httpPort = parseInt(process.argv[3]) || 3000;
+    const wsPort = parseInt(process.argv[4]) || 3001;
 
-    // Start server
-    await start(port, pageName);
+    await start(httpPort, wsPort);
 
   } else {
     console.log(`
 JUX CLI - A JavaScript UX authorship platform
 
 Usage:
-  npx jux init               Initialize a new JUX project
-  npx jux build              Build router bundle to ./jux-dist/
-  npx jux serve [page]       Start dev server (optionally for specific page)
-  npx jux serve [port]       Start dev server on custom port
+  npx jux init              Initialize a new JUX project
+  npx jux build             Build router bundle to ./jux-dist/
+  npx jux serve [http] [ws] Start dev server with hot reload
+
+Arguments:
+  [http]  HTTP server port (default: 3000)
+  [ws]    WebSocket port (default: 3001)
 
 Project Structure:
   my-project/
   ├── jux/              # Your .jux source files
-  │   ├── hey.jux       # Starter page (created by init)
-  │   └── pages/        # Additional pages
-  ├── jux-dist/         # Build output (git-ignore this)
-  ├── server/           # Your backend
+  │   ├── index.jux    # Entry point
+  │   └── pages/       # Additional pages
+  ├── jux-dist/        # Build output (git-ignore this)
+  ├── server/          # Your backend
   └── package.json
 
 Import Style:
@@ -344,17 +345,16 @@ Import Style:
   import 'juxscript/presets/notion.js';
 
 Getting Started:
-  1. npx jux init          # Create project structure
-  2. npm install           # Install dependencies
-  3. npx jux serve hey     # Dev server for hey.jux at localhost:3000/hey
-  4. npx jux serve         # Dev server for all pages
-  5. Serve jux-dist/ from your backend
+  1. npx jux init      # Create project structure
+  2. npm install       # Install dependencies
+  3. npx jux serve     # Dev server with hot reload
+  4. Serve jux-dist/ from your backend
 
 Examples:
-  npx jux build            Build production bundle
-  npx jux serve            Start dev server on port 3000 (all pages)
-  npx jux serve hey        Start dev server at localhost:3000/hey
-  npx jux serve 8080       Start dev server on port 8080
+  npx jux build        # Build production bundle
+  npx jux serve        # Dev server (ports 3000/3001)
+  npx jux serve 8080   # HTTP on 8080, WS on 3001
+  npx jux serve 8080 8081  # HTTP on 8080, WS on 8081
     `);
   }
 })();

package/lib/components/docs-data.json

@@ -2059,5 +2059,5 @@
     }
   ],
   "version": "1.0.0",
-  "lastUpdated": "2026-01-28T04:47:53.565Z"
+  "lastUpdated": "2026-01-28T14:47:56.941Z"
 }

package/machinery/compiler.js

@@ -580,8 +580,23 @@ ${routeTable}
 const app = document.getElementById('app');
 
 function render() {
-  const path = location.pathname;
-  const view = routes[path] || JuxNotFound;
+  let path = location.pathname;
+  
+  // Try exact match first
+  let view = routes[path];
+  
+  // If no match and path ends with /, try appending 'index'
+  if (!view && path.endsWith('/')) {
+    view = routes[path + 'index'] || routes[path.slice(0, -1) + '/index'];
+  }
+  
+  // If still no match and path doesn't end with /, try appending '/index'
+  if (!view && !path.endsWith('/')) {
+    view = routes[path + '/index'];
+  }
+  
+  // Fall back to 404
+  view = view || JuxNotFound;
   
   app.innerHTML = '';
   app.removeAttribute('data-jux-page');

package/machinery/server.js

@@ -9,7 +9,45 @@ import { WebSocketServer } from 'ws';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-async function serve(port = 3000, distDir = './jux-dist') {
+/**
+ * Try to start a server on a port, with fallback to next port if busy
+ * Returns the actual port that was successfully allocated
+ */
+async function tryPort(startPort, maxAttempts = 5, reservedPorts = []) {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const port = startPort + attempt;
+
+    // Skip if this port is already reserved
+    if (reservedPorts.includes(port)) {
+      continue;
+    }
+
+    try {
+      // Test if port is available
+      await new Promise((resolve, reject) => {
+        const testServer = http.createServer();
+        testServer.once('error', reject);
+        testServer.once('listening', () => {
+          testServer.close();
+          resolve(port);
+        });
+        testServer.listen(port);
+      });
+      return port;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        if (attempt < maxAttempts - 1) {
+          console.log(`   Port ${port} in use, trying ${port + 1}...`);
+        }
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`Could not find available port after ${maxAttempts} attempts starting from ${startPort}`);
+}
+
+async function serve(httpPort = 3000, wsPort = 3001, distDir = './jux-dist') {
   const app = express();
   const absoluteDistDir = path.resolve(distDir);
   const projectRoot = path.resolve('.');
@@ -22,50 +60,46 @@ async function serve(port = 3000, distDir = './jux-dist') {
     process.exit(1);
   }
 
-  // ✅ Strong cache prevention for main.js
+  // Strong cache prevention
   app.use((req, res, next) => {
     res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
     res.setHeader('Pragma', 'no-cache');
     res.setHeader('Expires', '0');
-
-    // ✅ Add ETag prevention
     res.setHeader('ETag', 'W/"' + Date.now() + '"');
-
-    next();
-  });
-
-  // Disable caching in dev mode
-  app.use((req, res, next) => {
-    res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
-    res.setHeader('Pragma', 'no-cache');
-    res.setHeader('Expires', '0');
     next();
   });
 
-  // Serve static files (CSS, JS, images, etc.)
+  // Serve static files
   app.use(express.static(absoluteDistDir));
 
-  // SPA fallback: only for requests that accept HTML (not static files)
+  // SPA fallback
   app.get('*', (req, res) => {
-    // If request accepts HTML, serve index.html
     if (req.accepts('html')) {
       const indexPath = path.join(absoluteDistDir, 'index.html');
       if (fs.existsSync(indexPath)) {
         res.sendFile(indexPath);
       } else {
-        res.status(404).send('index.html not found. Run `npx jux bundle` first.');
+        res.status(404).send('index.html not found. Run `npx jux build` first.');
       }
     } else {
-      // For non-HTML requests (like .js, .css), return 404
       res.status(404).send('Not found');
     }
   });
 
+  // Find available ports sequentially to avoid collision
+  console.log('🔍 Finding available ports...');
+
+  // First, find HTTP port
+  const availableHttpPort = await tryPort(httpPort);
+
+  // Then find WS port, excluding the HTTP port we just allocated
+  const availableWsPort = await tryPort(wsPort, 5, [availableHttpPort]);
+
   // Create HTTP server
   const server = http.createServer(app);
 
   // WebSocket server for hot reload
-  const wss = new WebSocketServer({ port: 3001 });
+  const wss = new WebSocketServer({ port: availableWsPort });
   const clients = [];
 
   wss.on('connection', (ws) => {
@@ -83,16 +117,13 @@ async function serve(port = 3000, distDir = './jux-dist') {
     });
   });
 
-  console.log('🔌 WebSocket server running at ws://localhost:3001');
+  console.log(`🔌 WebSocket server running at ws://localhost:${availableWsPort}`);
 
   // Start HTTP server
-  server.listen(port, () => {
-    console.log(`\n🚀 JUX dev server running`);
-    console.log(`   Local: http://localhost:${port}${pageName ? '/' + pageName : ''}`);
-    if (pageName) {
-      console.log(`   (Root redirects to /${pageName})`);
-    }
-    console.log('');
+  server.listen(availableHttpPort, () => {
+    console.log(`🚀 JUX dev server running at http://localhost:${availableHttpPort}`);
+    console.log(`   Serving: ${absoluteDistDir}`);
+    console.log(`   Press Ctrl+C to stop\n`);
   });
 
   // Start file watcher
@@ -113,30 +144,9 @@ async function serve(port = 3000, distDir = './jux-dist') {
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
 
-  return { server };
+  return { server, httpPort: availableHttpPort, wsPort: availableWsPort };
 }
 
-export async function start(port = 3000, pageName = null) {
-  const app = express();
-  
-  // ...existing code for static files...
-  
-  // If pageName specified, redirect root to that page
-  if (pageName) {
-    app.get('/', (req, res) => {
-      res.redirect(`/${pageName}`);
-    });
-    console.log(`🎯 Root (/) redirects to /${pageName}`);
-  }
-  
-  // ...existing code...
-  
-  app.listen(port, () => {
-    console.log(`\n🚀 JUX dev server running`);
-    console.log(`   Local: http://localhost:${port}${pageName ? '/' + pageName : ''}`);
-    if (pageName) {
-      console.log(`   (Root redirects to /${pageName})`);
-    }
-    console.log('');
-  });
+export async function start(httpPort = 3000, wsPort = 3001) {
+  return serve(httpPort, wsPort, './jux-dist');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "lib/jux.js",

package/presets/hey.jux

@@ -1,7 +1,7 @@
 import { jux } from 'juxscript';
 
-// Welcome page - edit this to build your app
-jux.hero('welcome-hero', {
+// Welcome page with examples
+jux.hero('welcome', {
     title: 'Welcome to JUX',
     subtitle: 'A JavaScript UX authorship platform'
 }).render('#app');
@@ -12,35 +12,49 @@ jux.container('getting-started')
     .style('max-width: 800px; margin: 2rem auto; padding: 2rem;')
     .render('#app');
 
-jux.heading('gs-title')
+jux.heading('start-heading')
     .level(2)
     .text('Getting Started')
     .render('#getting-started');
 
-jux.paragraph('gs-intro')
-    .text('Edit jux/hey.jux to start building your application.')
+jux.paragraph('start-intro')
+    .text('Edit this file to build your app. Here are some quick tips:')
     .style('margin: 1rem 0;')
     .render('#getting-started');
 
-jux.list('gs-steps', {
+jux.list('quick-tips', {
     items: [
-        'Run npx jux build to compile',
-        'Run npx jux serve to dev with hot reload',
-        'Run npx jux serve hey to serve just this page',
-        'Serve jux-dist/ from your backend in production'
+        'Run npx jux serve for dev mode with hot reload',
+        'Run npx jux build to compile for production',
+        'Serve jux-dist/ from your backend',
+        'Check out the docs at juxscript.com/docs'
     ]
 }).render('#getting-started');
 
 jux.divider().render('#app');
 
-jux.button('demo-button')
-    .label('Click Me!')
-    .variant('primary')
-    .bind('click', () => {
-        jux.alert('demo-alert')
-            .type('success')
-            .message('Button clicked! You are ready to build with JUX.')
-            .render('#app');
-    })
-    .style('margin: 2rem auto; display: block;')
+jux.container('example-container')
+    .style('max-width: 800px; margin: 2rem auto; padding: 2rem; background: #f9fafb; border-radius: 8px;')
     .render('#app');
+
+jux.heading('example-heading')
+    .level(3)
+    .text('Quick Example')
+    .render('#example-container');
+
+jux.code('example-code')
+    .language('javascript')
+    .code(`import { jux, state } from 'juxscript';
+
+// Create a reactive counter
+const count = state(0);
+
+jux.button('increment')
+  .label('Click me!')
+  .bind('click', () => count.value++)
+  .render('#app');
+
+jux.paragraph('counter')
+  .sync('text', count, val => \`Count: \${val}\`)
+  .render('#app');`)
+    .render('#example-container');