juxscript 1.0.62 → 1.0.63

package/bin/cli.js

@@ -14,7 +14,9 @@ const command = process.argv[2];
 // ═══════════════════════════════════════════════════════════════════
 
 if (command === 'create') {
-  const projectName = process.argv[3] || 'my-jux-app';
+  const timestamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '').slice(0, 12);
+  const projectName = process.argv[3] || `my-jux-app-${timestamp}`;
+
   const projectPath = path.join(process.cwd(), projectName);
 
   console.log(`
@@ -64,16 +66,12 @@ if (command === 'create') {
       console.error(`\n   ⚠️  npm install failed, but continuing...`);
     }
 
-    console.log(`\n🎨 Initializing JUX project structure...`);
     execSync('npx jux init', { stdio: 'inherit' });
 
     console.log(`\n📝 Creating .gitignore...`);
     fs.writeFileSync('.gitignore', `.jux-dist/\nnode_modules/\n.DS_Store\n.env\n*.log\n`);
     console.log(`   ✓ .gitignore created`);
 
-    // ❌ REMOVE: Don't copy example file during create
-    // The working config is enough, users can view example on GitHub/npm
-
     console.log(`
 ╔═══════════════════════════════════════════════════════╗
 ║                                                       ║
@@ -120,7 +118,6 @@ Next steps:
 // ALL OTHER COMMANDS - Require dependencies to be installed
 // ═══════════════════════════════════════════════════════════════════
 
-// ✅ Now import dependencies (only needed for init, build, serve)
 import {
   copyLibToOutput,
   copyProjectAssets,
@@ -129,56 +126,39 @@ import {
   bundleJuxFilesToRouter,
   generateIndexHtml
 } from '../machinery/compiler.js';
-import { generateDocs } from '../machinery/doc-generator.js';
+import { verifyStaticBuild } from '../machinery/verifier.js'; // ✅ Import Verifier
+import { resolveConfig } from '../machinery/config.js'; // ✅ Import Config Resolver
 import { start } from '../machinery/server.js';
-import { loadConfig, runBootstrap } from '../machinery/config.js';
-
-// ✅ Load config BEFORE setting up PATHS
-const config = await loadConfig(process.cwd());
-
-// CLEAR PATH CONTRACT - CONVENTIONS
-const PATHS = {
-  // Where jux package is installed (in node_modules/juxscript or local dev)
-  packageRoot: path.resolve(__dirname, '..'),
-
-  // Where the user's project root is (where they run `npx jux`)
-  projectRoot: process.cwd(),
+// ❌ REMOVED static import of config to prevent crash on incorrect path
 
-  // Where user's .jux source files live (CONVENTION: ./jux/)
-  get juxSource() {
-    return path.join(this.projectRoot, config.sourceDir);
-  },
-
-  // Where jux lib files are (components, layouts, etc.)
-  get juxLib() {
-    return path.resolve(__dirname, '..', 'lib');
-  },
+/**
+ * Dynamically load and normalize juxconfig.js from the user's project root
+ */
+async function loadUserConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'juxconfig.js');
+  let rawConfig = {};
 
-  // Where frontend build output goes (CONVENTION: ./jux-dist/)
-  get frontendDist() {
-    return path.join(this.projectRoot, config.distDir);
+  if (fs.existsSync(configPath)) {
+    try {
+      const module = await import(configPath);
+      // Support export default defineConfig({...}) OR export const config = {...}
+      rawConfig = module.default || module.config || {};
+    } catch (err) {
+      console.warn(`⚠️  Error loading juxconfig.js: ${err.message}. Using defaults.`);
+    }
   }
-};
 
-console.log('📍 JUX Paths:');
-console.log(`   Package:  ${PATHS.packageRoot}`);
-console.log(`   Project:  ${PATHS.projectRoot}`);
-console.log(`   Source:   ${PATHS.juxSource} (from config: ${config.sourceDir})`);
-console.log(`   Output:   ${PATHS.frontendDist} (from config: ${config.distDir})`);
-console.log(`   Lib:      ${PATHS.juxLib}\n`);
+  // ✅ Normalize DX sugar (short paths, missing extensions, aliases) into strict config
+  return resolveConfig(rawConfig, projectRoot);
+}
 
-/**
- * Recursively find .jux files in a directory
- */
+// Recursively find .jux files
 function findJuxFiles(dir, fileList = []) {
   if (!fs.existsSync(dir)) return fileList;
-
   const files = fs.readdirSync(dir);
-
   files.forEach(file => {
     const filePath = path.join(dir, file);
     const stat = fs.statSync(filePath);
-
     if (stat.isDirectory()) {
       if (file !== 'node_modules' && file !== 'jux-dist' && file !== '.git' && file !== 'server') {
         findJuxFiles(filePath, fileList);
@@ -187,297 +167,185 @@ function findJuxFiles(dir, fileList = []) {
       fileList.push(filePath);
     }
   });
-
   return fileList;
 }
 
-/**
- * Build the entire JUX project (ALWAYS uses router bundle)
- * 
- * @param {boolean} isServe - Whether building for dev server
- */
-async function buildProject(isServe = false, wsPort = 3001) {
-  const buildStartTime = performance.now();
-  console.log('🔨 Building JUX frontend...\n');
+// ═══════════════════════════════════════════════════════════════════
+// MAIN EXECUTION BLOCK (Async)
+// ═══════════════════════════════════════════════════════════════════
+(async () => {
+  // 1. Resolve Configuration relative to CWD
+  const projectRoot = process.cwd();
+  const config = await loadUserConfig(projectRoot);
+
+  // 2. Define PATHS Contract
+  const PATHS = {
+    packageRoot: path.resolve(__dirname, '..'), // node_modules/juxscript
+    projectRoot: projectRoot,
+
+    // Use config values
+    get juxSource() { return path.join(this.projectRoot, config.directories?.source || 'jux'); },
+    get juxLib() { return path.resolve(this.packageRoot, 'lib'); },
+    get frontendDist() { return path.join(this.projectRoot, config.directories?.distribution || '.jux-dist'); }
+  };
+
+  console.log('📍 JUX Paths:');
+  console.log(`   Package:  ${PATHS.packageRoot}`);
+  console.log(`   Project:  ${PATHS.projectRoot}`);
+  console.log(`   Source:   ${PATHS.juxSource}`);
+  console.log(`   Output:   ${PATHS.frontendDist}`);
+  console.log(`   Lib:      ${PATHS.juxLib}\n`);
+
+  /**
+   * Build the entire JUX project
+   */
+  async function buildProject(isServe = false, wsPort = 3001) {
+    const buildStartTime = performance.now();
+    console.log('++ Building JUX frontend...\n');
 
-  try {
-    // Verify jux source directory exists
-    if (!fs.existsSync(PATHS.juxSource)) {
-      console.error(`❌ Source directory not found: ${PATHS.juxSource}`);
-      console.error(`   Please create a 'jux/' directory with your .jux files`);
-      process.exit(1);
-    }
+    try {
+      // Verify jux source directory exists
+      if (!fs.existsSync(PATHS.juxSource)) {
+        console.error(`❌ Source directory not found: ${PATHS.juxSource}`);
+        console.error(`   Please create a directory named '${config.directories?.source || 'jux'}'`);
+        process.exit(1);
+      }
 
-    // Clean and create frontend dist
-    if (fs.existsSync(PATHS.frontendDist)) {
-      fs.rmSync(PATHS.frontendDist, { recursive: true, force: true });
-    }
-    fs.mkdirSync(PATHS.frontendDist, { recursive: true });
+      // Clean and create frontend dist
+      if (fs.existsSync(PATHS.frontendDist)) {
+        fs.rmSync(PATHS.frontendDist, { recursive: true, force: true });
+      }
+      fs.mkdirSync(PATHS.frontendDist, { recursive: true });
+
+      // Copy dependencies
+      const libStartTime = performance.now();
+      await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
+      const libTime = performance.now() - libStartTime;
+      console.log(`⏱️  Lib copy time: ${libTime.toFixed(0)}ms\n`);
+
+      const presetsStartTime = performance.now();
+      await copyPresetsToOutput(PATHS.packageRoot, PATHS.frontendDist);
+      const presetsTime = performance.now() - presetsStartTime;
+      console.log(`⏱️  Presets copy time: ${presetsTime.toFixed(0)}ms\n`);
+
+      const assetsStartTime = performance.now();
+      await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
+      const assetsTime = performance.now() - assetsStartTime;
+      console.log(`⏱️  Assets copy time: ${assetsTime.toFixed(0)}ms\n`);
+
+      const tsStartTime = performance.now();
+      await transpileProjectTypeScript(PATHS.juxSource, PATHS.frontendDist);
+      const tsTime = performance.now() - tsStartTime;
+      console.log(`⏱️  TypeScript transpile time: ${tsTime.toFixed(0)}ms\n`);
+
+      // Bundle Routers
+      const projectJuxFiles = findJuxFiles(PATHS.juxSource);
+      console.log(`📝 Found ${projectJuxFiles.length} .jux file(s)\n`);
+
+      if (projectJuxFiles.length === 0) {
+        console.warn('⚠️  No .jux files found to bundle');
+        process.exit(1);
+      }
 
-    // Step 1: Generate documentation
-    /*
-    const docsStartTime = performance.now();
-    let docsTime = 0; // ✅ Declare with default value
-    console.log('📚 Generating documentation...');
-    try {
-      await generateDocs(PATHS.juxLib);
-      docsTime = performance.now() - docsStartTime;
-      console.log(`✅ Documentation generated (${docsTime.toFixed(0)}ms)\n`);
-    } catch (error) {
-      docsTime = performance.now() - docsStartTime; // ✅ Still calculate time even on error
-      console.warn(`⚠️  Failed to generate docs (${docsTime.toFixed(0)}ms):`, error.message);
-    }
-    */
-
-    // Step 2: Copy jux lib to frontend dist
-    const libStartTime = performance.now();
-    await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
-    const libTime = performance.now() - libStartTime;
-    console.log(`⏱️  Lib copy time: ${libTime.toFixed(0)}ms\n`);
-
-    // Step 3: Copy presets folder
-    const presetsStartTime = performance.now();
-    await copyPresetsToOutput(PATHS.packageRoot, PATHS.frontendDist);
-    const presetsTime = performance.now() - presetsStartTime;
-    console.log(`⏱️  Presets copy time: ${presetsTime.toFixed(0)}ms\n`);
-
-    // Step 4: Copy project assets (CSS, JS, images)
-    const assetsStartTime = performance.now();
-    await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
-    const assetsTime = performance.now() - assetsStartTime;
-    console.log(`⏱️  Assets copy time: ${assetsTime.toFixed(0)}ms\n`);
-
-    // Step 5: Transpile TypeScript files
-    const tsStartTime = performance.now();
-    await transpileProjectTypeScript(PATHS.juxSource, PATHS.frontendDist);
-    const tsTime = performance.now() - tsStartTime;
-    console.log(`⏱️  TypeScript transpile time: ${tsTime.toFixed(0)}ms\n`);
-
-    // Step 6: Bundle all .jux files into router
-    const projectJuxFiles = findJuxFiles(PATHS.juxSource);
-    console.log(`📝 Found ${projectJuxFiles.length} .jux file(s) in /jux\n`);
-
-    if (projectJuxFiles.length === 0) {
-      console.warn('⚠️  No .jux files found to bundle');
-      process.exit(1);
-    }
+      const bundleStartTime = performance.now();
+      const bundleResult = await bundleJuxFilesToRouter(PATHS.juxSource, PATHS.frontendDist, {
+        routePrefix: '',
+        config // Pass config to bundler
+      });
+      const bundleTime = performance.now() - bundleStartTime;
 
-    // ✅ Bundle and get the generated filename
-    const bundleStartTime = performance.now();
-    const bundleResult = await bundleJuxFilesToRouter(PATHS.juxSource, PATHS.frontendDist, {
-      routePrefix: ''
-    });
-    const bundleTime = performance.now() - bundleStartTime;
-
-    // ✅ Generate unified index.html
-    const indexStartTime = performance.now();
-    generateIndexHtml(PATHS.frontendDist, bundleResult);
-    const indexTime = performance.now() - indexStartTime;
-
-    const totalBuildTime = performance.now() - buildStartTime;
-
-    // ✅ FIX: Use bundleResult.mainJsFilename instead of bare mainJsFilename
-    console.log(`\n✅ Bundled ${projectJuxFiles.length} page(s) → ${PATHS.frontendDist}/${bundleResult.mainJsFilename}\n`);
-
-    // ✅ Build summary with timing breakdown
-    console.log(`📊 Build Summary:`);
-    console.log(`   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-    console.log(`   Library copy:      ${libTime.toFixed(0)}ms`);
-    console.log(`   Presets copy:      ${presetsTime.toFixed(0)}ms`);
-    console.log(`   Assets copy:       ${assetsTime.toFixed(0)}ms`);
-    console.log(`   TypeScript:        ${tsTime.toFixed(0)}ms`);
-    console.log(`   Router bundle:     ${bundleTime.toFixed(0)}ms`);
-    console.log(`   Index generation:  ${indexTime.toFixed(0)}ms`);
-    console.log(`   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-    console.log(`   Total build time:  ${totalBuildTime.toFixed(0)}ms\n`);
-
-    // Show usage
-    if (!isServe) {
-      console.log('📦 Serve from your backend:');
-      console.log(`   Express:  app.use(express.static('jux-dist'))`);
-      console.log(`   Flask:    app = Flask(__name__, static_folder='jux-dist')`);
-      console.log(`   FastAPI:  app.mount("/", StaticFiles(directory="jux-dist"), name="static")`);
-      console.log('');
-      console.log('📍 Available routes:');
-      // ✅ FIX: Use bundleResult.routes instead of local routes variable
-      bundleResult.routes.forEach(r => {
-        console.log(`   ${r.path}`);
+      const indexStartTime = performance.now();
+      generateIndexHtml(PATHS.frontendDist, bundleResult, {
+        isDev: isServe,
+        wsPort: isServe ? wsPort : undefined
       });
-      console.log('');
-    }
+      const indexTime = performance.now() - indexStartTime;
 
-  } catch (err) {
-    const failTime = performance.now() - buildStartTime;
-    console.error(`❌ Build error after ${failTime.toFixed(0)}ms:`, err.message);
-    console.error(err.stack);
-    process.exit(1);
+      // ✅ NEW: Post-Compilation Verification
+      if (!verifyStaticBuild(PATHS.frontendDist)) {
+        console.error('🛑 Critical Build Failure. Aborting.');
+        process.exit(1);
+      }
+
+      const totalBuildTime = performance.now() - buildStartTime;
+      console.log(`\n✅ Bundled → ${PATHS.frontendDist}/${bundleResult.mainJsFilename}\n`);
+
+      // Build Summary Log
+      console.log(`📊 Build Summary:`);
+      console.log(`   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+      console.log(`   Library copy:      ${libTime.toFixed(0)}ms`);
+      console.log(`   Router bundle:     ${bundleTime.toFixed(0)}ms`);
+      console.log(`   Total build time:  ${totalBuildTime.toFixed(0)}ms\n`);
+
+      if (!isServe) {
+        // ...existing code...
+      }
+
+    } catch (err) {
+      console.error(`❌ Build error:`, err.message);
+      console.error(err.stack);
+      process.exit(1);
+    }
   }
-}
 
-(async () => {
+  // ═══════════════════════════════════════════════════════════════
+  // COMMAND DISPATCHER
+  // ═══════════════════════════════════════════════════════════════
+
   if (command === 'init') {
     console.log('🎨 Initializing JUX project...\n');
-
     const juxDir = PATHS.juxSource;
-
     if (fs.existsSync(juxDir)) {
-      console.error('❌ jux/ directory already exists');
+      console.error('❌ Source directory already exists');
       process.exit(1);
     }
 
-    // Create jux/ structure
-    fs.mkdirSync(juxDir, { recursive: true });
-
-    // ✅ Copy presets/default/ directly to jux/ (no presets subfolder!)
-    const defaultPresetSrc = path.join(PATHS.packageRoot, 'presets', 'default');
+    fs.mkdirSync(juxDir, { recursive: true }); // create it.
 
+    // Copy default presets
+    const defaultPresetSrc = path.join(PATHS.packageRoot, 'create');
     if (fs.existsSync(defaultPresetSrc)) {
-      console.log('📦 Copying default preset boilerplate...');
-
       const entries = fs.readdirSync(defaultPresetSrc, { withFileTypes: true });
-      let copiedCount = 0;
-
       for (const entry of entries) {
-        const srcPath = path.join(defaultPresetSrc, entry.name);
-        const destPath = path.join(juxDir, entry.name);
-
         if (entry.isFile()) {
-          fs.copyFileSync(srcPath, destPath);
-          console.log(`+ Created jux/${entry.name}`);
-          copiedCount++;
+          fs.copyFileSync(path.join(defaultPresetSrc, entry.name), path.join(juxDir, entry.name));
+          // console.log(`+ Created ${entry.name}`);
         }
       }
-
-      console.log(`✅ Copied ${copiedCount} boilerplate file(s) to jux/\n`);
-    }
-
-    // ✅ Create a simple index.jux if none exists
-    const indexJuxDest = path.join(juxDir, 'index.jux');
-    if (!fs.existsSync(indexJuxDest)) {
-      const basicContent = `import { jux, state } from 'juxscript';
-
-jux.hero('welcome', {
-  title: 'Welcome to JUX',
-  subtitle: 'Start building your app'
-}).render('#app');
-
-const count = state(0);
-
-jux.button('increment')
-  .label('Click me!')
-  .bind('click', () => count.value++)
-  .style('margin: 2rem 0;')
-  .render('#app');
-
-jux.paragraph('counter')
-  .sync('text', count, val => \`Count: \${val}\`)
-  .render('#app');
-`;
-      fs.writeFileSync(indexJuxDest, basicContent);
-      console.log('+ Created jux/index.jux');
-    }
-
-    // Create package.json if it doesn't exist
-    const pkgPath = path.join(PATHS.projectRoot, 'package.json');
-    if (!fs.existsSync(pkgPath)) {
-      const projectName = path.basename(PATHS.projectRoot).toLowerCase().replace(/[^a-z0-9-]/g, '-');
-
-      const pkgContent = {
-        "name": projectName,
-        "version": "0.1.0",
-        "type": "module",
-        "scripts": {
-          "dev": "jux serve",
-          "build": "jux build"
-        },
-        "dependencies": {
-          "juxscript": "latest"
-        }
-      };
-      fs.writeFileSync(pkgPath, JSON.stringify(pkgContent, null, 2));
-      console.log('+ Created package.json');
     }
 
-    // Create .gitignore with config.distDir
-    const gitignorePath = path.join(PATHS.projectRoot, '.gitignore');
-    const gitignoreContent = `${config.distDir}/\nnode_modules/\n.DS_Store\n`;  // ✅ Uses config.distDir
-
-    if (!fs.existsSync(gitignorePath)) {
-      fs.writeFileSync(gitignorePath, gitignoreContent);
-      console.log('+ Created .gitignore');
-    }
-
-    // ✅ Copy juxconfig to root
+    // Create juxconfig.js
     const configExampleSrc = path.join(PATHS.packageRoot, 'juxconfig.example.js');
-
-    if (fs.existsSync(configExampleSrc)) {
-      const configDest = path.join(PATHS.projectRoot, 'juxconfig.js');
-      if (!fs.existsSync(configDest)) {
-        fs.copyFileSync(configExampleSrc, configDest);
-        console.log('+ Created juxconfig.js');
-      }
-
-      // ❌ REMOVE: Don't copy example - it's available in node_modules
-      // const configExampleDest = path.join(PATHS.projectRoot, 'juxconfig.example.js');
-      // if (!fs.existsSync(configExampleDest)) {
-      //   fs.copyFileSync(configExampleSrc, configExampleDest);
-      //   console.log('+ Created juxconfig.example.js (reference)');
-      // }
+    const configDest = path.join(PATHS.projectRoot, 'juxconfig.js');
+    if (fs.existsSync(configExampleSrc) && !fs.existsSync(configDest)) {
+      fs.copyFileSync(configExampleSrc, configDest);
+      console.log('+ Created juxconfig.js');
     }
 
-    console.log('\n✅ JUX project initialized!\n');
-    console.log('Project structure:');
-    console.log(`  ${config.sourceDir}/              # Your source files`);
-    console.log(`  ${config.distDir}/                # Build output (git-ignored)`);
-    console.log('  juxconfig.js      # Configuration');
-    console.log('  package.json      # Dependencies\n');
-    console.log('Next steps:');
-    console.log('  npm install       # Install dependencies');
-    console.log('  npm run dev       # Start dev server\n');
-    console.log('📖 Config reference: node_modules/juxscript/juxconfig.example.js\n');
+    console.log('\n✅ JUX project initialized!');
 
   } else if (command === 'build') {
-    // ✅ Run bootstrap before build
-    await runBootstrap(config.bootstrap);
     await buildProject(false);
     console.log(`✅ Build complete: ${PATHS.frontendDist}`);
 
   } else if (command === 'serve') {
-    // ✅ Use ports from config
-    const httpPort = parseInt(process.argv[3]) || config.ports.http;
-    const wsPort = parseInt(process.argv[4]) || config.ports.ws;
+    const httpPort = parseInt(process.argv[3]) || config.defaults?.httpPort || 3000;
+    const wsPort = parseInt(process.argv[4]) || config.defaults?.wsPort || 3001;
 
-    await runBootstrap(config.bootstrap);
     await buildProject(true, wsPort);
-    await start(httpPort, wsPort, PATHS.frontendDist);
+    await start(httpPort, wsPort, PATHS.frontendDist, config); // Pass config to server
 
   } else {
+    // ...existing code...
+    // (Help text)
     console.log(`
 JUX CLI - A JavaScript UX authorship platform
-
 Usage:
-  npx jux create [name]     Create a new JUX project
-  npx jux init              Initialize JUX in current directory
-  npx jux build             Build router bundle to ${config.distDir}/
-  npx jux serve [http] [ws] Start dev server with hot reload
-
-Project Structure:
-  my-project/
-  ├── ${config.distDir}/           # Build output (git-ignored, like .git)
-  │   ├── lib/
-  │   ├── main.js
-  │   └── index.html
-  ├── ${config.sourceDir}/            # Your .jux source files
-  │   ├── index.jux
-  │   ├── layout.css
-  │   └── layout.jux
-  ├── juxconfig.js     # Configuration
-  └── package.json
-
-Examples:
-  npx jux create my-app     Create new project
-  npx jux serve             Dev server (ports 3000/3001)
-  npx jux serve 8080 8081   Custom ports
-    `);
+  npx jux create [name]
+  npx jux init
+  npx jux build
+  npx jux serve
+`);
   }
+
 })();

package/docs/v2comps/HEADLESS.md

@@ -0,0 +1,83 @@
+# JUX HEADLESS LIBRARY
+**Formula:** `Logic (Engine) + View (Skin) = Component`
+
+## The Engine (Service Contract)
+The Engine defines the component's capabilities and data shape. It acts as the "Operating System" for the component.
+
+**1. Isomorphic & Headless**
+The Engine is pure TypeScript/JavaScript logic. It has **zero dependencies** on the DOM, `window`, or browser APIs.
+*   **Benefit:** Deeply testable in Node.js without fragile mocks or JSDOM.
+*   **Benefit:** Portable across environments (Server-Side Rendering, CLI tools, Native wrappers).
+
+**2. The Observer Pattern (The Wire)**
+The Engine manages subscriptions. Skins do not poll for changes; they subscribe.
+*   When state mutates, the Engine notifies all listeners immediately with a fresh snapshot.
+*   **Unidirectional Flow:** Skins cannot modify State directly. They must invoke Engine methods (commands).
+
+**3. State Management**
+State is the Engine's repository of truth. By default, it is in-memory and ephemeral.
+
+### Persistence Strategy
+State persistence is handled via **Dependency Injection**. A "Persistence Driver" can be passed to the Engine's constructor.
+*   **Separation of Concerns:** The Engine knows *when* data changes, but the Driver knows *how* to save it (LocalStorage, Database, FileSystem).
+*   **Decision Criteria:** Not every Engine needs persistence. Ideally, persist **Domain State** (User Data like 'List Items') but keep **UI State** (Transient data like 'Menu Open') in memory.
+
+## Why Distinct Engines?
+Why not one generic Engine?
+Engines encapsulate specific **Business Logic** and **Data Shapes**.
+*   A `ListEngine` methods: `addItem`, `removeItem`, `sort`.
+*   A `ButtonEngine` methods: `click`, `disable`, `enable`.
+*   A `FormEngine` methods: `validate`, `submit`, `reset`.
+
+Engines are thin layers that translate specific high-level intent (API) into low-level state patches.
+
+### The Public API
+**An Engine's Methods are the Public API.** 
+This is the primary interface for:
+1.  **The Application Developer**: To drive the component programmatically (e.g., `listEngine.addItem('Buy Milk')`).
+2.  **The Skin**: To wire up UI events (e.g., `button.onclick = () => engine.click()`).
+3.  **The Component Author**: To strictly define what mutations are valid, preventing "illegal" states.
+
+## BaseEngine
+The base engine serves as the 'State and Context' Manager for the Jux Ecosystem. You can gather the current state of any jux component by calling the `componentsEngineName.state`
+
+Example:
+```javascript
+// composer.js
+import { ListEngine } from './ListEngine.js';
+// 1. Initialize the Engine (The Logic)
+const listEngine = new ListEngine(['Apples', 'Oranges']); // Initialize List Engine
+
+// You can still trigger engine commands directly from the console!
+window.listEngine = listEngine; // Expose list engine to console
+/* call this directly from the console => 
+
+    console.log('List Engine State: ', listEngine.state);
+
+ */
+```
+```javascript
+
+// yields
+
+{
+    items: ['Apples', 'Oranges'],
+    listType: 'unordered'
+}*/
+
+```
+
+## Tests
+Both Engines and Skins require tests.
+
+**Skins** require use of an html emulator (in memory HTML generator like JSDOM). 
+For Skins our Unit Tests aim to assert the **"View Contract"**:
+1.  **Render Accuracy**: Does the resulting HTML match the State? (e.g., if state has 3 items, do we see 3 `<li>` tags?)
+2.  **Event Wiring**: Do DOM interactions (clicks, inputs) trigger the correct Engine methods?
+3.  **Reactivity**: When the Engine updates, does the DOM update automatically without full page reloads?
+
+**Engines** use simple Node.js execution. (node test.js etc.). 
+For Engines our Unit Tests aim to assert the **"Business Logic"**:
+1.  **State Transitions**: Given an initial state and an action (method call), is the resulting state correct?
+2.  **Invariants**: Are invalid actions prevented or handled gracefully?
+3.  **Zero-UI Dependency**: Can the logic run to completion without any DOM APIs present?

package/docs/v2comps/ISOMORPHISM.md

@@ -0,0 +1,10 @@
+Yes, your ListEngine is 100% Isomorphic (also known as "Universal").
+
+Why?
+
+No DOM Access: It never touches window, document, or HTMLElement. That is entirely delegated to ListSkin.
+No Node API Access: It doesn't use fs or http.
+Pure Logic: It only relies on standard JavaScript objects (Array, JSON) and your internal BaseEngine.
+This means the exact same file can be used to drive your UI in the browser and run your Unit Tests in Node.js (or Deno/Bun) without any mocking or compilation tricks.
+
+I will add a JSDoc tag to ListEngine.js to document this architectural trait.