neo.mjs 10.2.1 → 10.3.1

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.2.1'
+         * @member {String} version='10.3.1'
          */
-        version: '10.2.1'
+        version: '10.3.1'
     }
 
     /**

package/apps/covid/view/MainContainer.mjs

@@ -30,7 +30,7 @@ class MainContainer extends Viewport {
          */
         items: [HeaderContainer, {
             module     : TabContainer,
-            activeIndex: null, // render no items initially
+            activeIndex: null, // mount no items initially
             flex       : 1,
             reference  : 'tab-container',
             sortable   : true,

package/apps/covid/view/country/Table.mjs

@@ -67,7 +67,7 @@ class Table extends Container {
                     cls : ['neo-country-column', 'neo-table-cell'],
                     html: [
                         '<div style="display: flex; align-items: center">',
-                        '<img style="height:20px; margin-right:10px; width:20px;" src="' + Util.getCountryFlagUrl(data.value) + '">' + data.value,
+                            '<img style="height:20px; margin-right:10px; width:20px;" src="' + Util.getCountryFlagUrl(data.value) + '">' + data.value,
                         '</div>'
                     ].join('')
                 }

package/apps/portal/index.html

@@ -16,7 +16,7 @@
         "@type": "Organization",
         "name": "Neo.mjs"
       },
-      "datePublished": "2025-07-30",
+      "datePublished": "2025-08-02",
       "publisher": {
         "@type": "Organization",
         "name": "Neo.mjs"

package/apps/portal/view/home/FooterContainer.mjs

@@ -108,7 +108,7 @@ class FooterContainer extends Container {
             }, {
                 module: Component,
                 cls   : ['neo-version'],
-                text  : 'v10.2.1'
+                text  : 'v10.3.1'
             }]
         }],
         /**

package/apps/portal/view/learn/ContentComponent.mjs

@@ -172,7 +172,7 @@ class ContentComponent extends Component {
         path += `${pagesFolder + record.id.replaceAll('.', '/')}.md`;
 
         if (record.isLeaf && path) {
-            baseConfigs = {appName, autoMount: true, autoRender: true, parentComponent: me, windowId};
+            baseConfigs = {appName, autoInitVnode: true, autoMount: true, parentComponent: me, windowId};
             data        = await fetch(path);
             content     = await data.text();
             // Update content sections (modifies markdown content with h1/h2/h3 tags and IDs)

package/apps/realworld/api/Base.mjs

@@ -62,10 +62,10 @@ class Base extends CoreBase {
                 me.afterConstructed()
             })
         } else {
-            if (Neo.apps['RealWorld'].rendered) {
+            if (Neo.apps['RealWorld'].vnodeInitialized) {
                 me.onAppRendered()
             } else {
-                Neo.apps['RealWorld'].on('render',me.onAppRendered, me)
+                Neo.apps['RealWorld'].on('vnodeInitialized',me.onAppRendered, me)
             }
         }
     }

package/apps/sharedcovid/view/MainContainer.mjs

@@ -31,7 +31,7 @@ class MainContainer extends Viewport {
         items: [HeaderContainer, {
             module              : TabContainer,
             activateInsertedTabs: true,
-            activeIndex         : null, // render no items initially
+            activeIndex         : null, // mount no items initially
             flex                : 1,
             reference           : 'tab-container',
             sortable            : true,

package/apps/sharedcovid/view/MainContainerController.mjs

@@ -299,7 +299,7 @@ class MainContainerController extends ComponentController {
         if (view) {
             NeoArray.add(me.connectedApps, name);
 
-            Neo.apps[name].on('render', () => {
+            Neo.apps[name].on('vnodeInitialized', () => {
                 me.timeout(100).then(() => {
                     me.getMainView(name).add(view)
                 })

package/buildScripts/buildAll.mjs

@@ -129,6 +129,10 @@ if (programOpts.info) {
             childProcess.status && process.exit(childProcess.status);
         }
 
+        console.log(chalk.blue('Bundling parse5...'));
+        childProcess = spawnSync('node', [`${neoPath}/buildScripts/bundleParse5.mjs`], cpOpts);
+        childProcess.status && process.exit(childProcess.status);
+
         if (themes === 'yes') {
             childProcess = spawnSync('node', [`${neoPath}/buildScripts/buildThemes.mjs`].concat(cpArgs), cpOpts);
             childProcess.status && process.exit(childProcess.status);

package/buildScripts/buildESModules.mjs

@@ -1,13 +1,12 @@
 import fs                   from 'fs-extra';
 import path                 from 'path';
-import {minify as minifyJs} from 'terser';
+import * as Terser          from 'terser';
 import {minifyHtml}         from './util/minifyHtml.mjs';
+import {processFileContent} from './util/astTemplateProcessor.mjs';
 
 const
     outputBasePath   = 'dist/esm/',
-    // Regex to find import statements with 'node_modules' in the path
-    // It captures the entire import statement (excluding the leading 'import') and the path itself.
-    regexImport      = /(import(?:\s*(?:[\w*{}\n\r\t, ]+from\s*)?|\s*\(\s*)?)(["'`])((?:(?!\2).)*node_modules(?:(?!\2).)*)\2/g,
+    regexImport      = /(import(?:\s*(?:[\w*{}\n\r\t, ]+from\s*)?|\s*\(\s*)?)(["`])((?:(?!\2).)*node_modules(?:(?!\2).)*)\2/g,
     root             = path.resolve(),
     requireJson      = path => JSON.parse(fs.readFileSync(path, 'utf-8')),
     packageJson      = requireJson(path.join(root, 'package.json')),
@@ -22,76 +21,45 @@ if (insideNeo) {
     inputDirectories = ['apps', 'docs', 'node_modules/neo.mjs/src', 'src']
 }
 
-/**
- * @param {String} match
- * @param {String} p1 will be "import {marked}    from " (or similar, including the 'import' keyword and everything up to the first quote)
- * @param {String} p2 will be the quote character (', ", or `)
- * @param {String} p3 will be the original path string (e.g., '../../../../node_modules/marked/lib/marked.esm.js')
- * @returns {String}
- */
 function adjustImportPathHandler(match, p1, p2, p3) {
     let newPath;
-
     if (p3.includes('/node_modules/neo.mjs/')) {
         newPath = p3.replace('/node_modules/neo.mjs/', '/')
     } else {
-        newPath = '../../' + p3; // Prepend 2 levels up
+        newPath = '../../' + p3;
     }
-
-    // Reconstruct the import statement with the new path
     return p1 + p2 + newPath + p2
 }
 
-/**
- *
- * @param {String} inputDir
- * @param {String} outputDir
- * @returns {Promise<void>}
- */
 async function minifyDirectory(inputDir, outputDir) {
     if (fs.existsSync(inputDir)) {
         fs.mkdirSync(outputDir, {recursive: true});
-
         const dirents = fs.readdirSync(inputDir, {recursive: true, withFileTypes: true});
-
         for (const dirent of dirents) {
-            // Intended to skip the docs/output folder, since the content is already minified
             if (dirent.path.includes('/docs/output/')) {
                 continue
             }
-
             if (dirent.isFile()) {
                 const
                     inputPath    = path.join(dirent.path, dirent.name),
                     relativePath = path.relative(inputDir, inputPath),
                     outputPath   = path.join(outputDir, relativePath),
                     content      = fs.readFileSync(inputPath, 'utf8');
-
                 await minifyFile(content, outputPath)
-            }
-            // Copy resources folders
-            else if (dirent.name === 'resources') {
+            } else if (dirent.name === 'resources') {
                 const
                     inputPath    = path.join(dirent.path, dirent.name),
                     relativePath = path.relative(inputDir, inputPath),
                     outputPath   = path.join(outputDir, relativePath);
-
                 fs.mkdirSync(path.dirname(outputPath), {recursive: true});
-
                 fs.copySync(inputPath, outputPath);
-
-                // Minify all JSON files inside the copied folder
                 const resourcesEntries = fs.readdirSync(outputPath, {recursive: true, withFileTypes: true});
-
                 for (const resource of resourcesEntries) {
-                    if (resource.isFile()) {
-                        if (resource.name.endsWith('.json')) {
-                            const
-                                resourcePath = path.join(resource.path, resource.name),
-                                content      = fs.readFileSync(resourcePath, 'utf8');
-
-                            fs.writeFileSync(resourcePath, JSON.stringify(JSON.parse(content)))
-                        }
+                    if (resource.isFile() && resource.name.endsWith('.json')) {
+                        const
+                            resourcePath = path.join(resource.path, resource.name),
+                            content      = fs.readFileSync(resourcePath, 'utf8');
+                        fs.writeFileSync(resourcePath, JSON.stringify(JSON.parse(content)))
                     }
                 }
             }
@@ -99,57 +67,42 @@ async function minifyDirectory(inputDir, outputDir) {
     }
 }
 
-/**
- * @param {String} content
- * @param {String} outputPath
- * @returns {Promise<void>}
- */
 async function minifyFile(content, outputPath) {
     fs.mkdirSync(path.dirname(outputPath), {recursive: true});
 
     try {
-        // Minify JSON files
         if (outputPath.endsWith('.json')) {
             const jsonContent = JSON.parse(content);
-
             if (outputPath.endsWith('neo-config.json')) {
                 Object.assign(jsonContent, {
-                    basePath      : '../../' + jsonContent.basePath,
-                    environment   : 'dist/esm',
-                    mainPath      : './Main.mjs',
+                    basePath: '../../' + jsonContent.basePath,
+                    environment: 'dist/esm',
+                    mainPath: './Main.mjs',
                     workerBasePath: jsonContent.basePath + 'src/worker/'
                 });
-
                 if (!insideNeo) {
                     jsonContent.appPath = jsonContent.appPath.substring(6)
                 }
             }
-
             fs.writeFileSync(outputPath, JSON.stringify(jsonContent));
             console.log(`Minified JSON: ${outputPath}`)
-        }
-        // Minify HTML files
-        else if (outputPath.endsWith('.html')) {
+        } else if (outputPath.endsWith('.html')) {
             const minifiedContent = await minifyHtml(content);
-
             fs.writeFileSync(outputPath, minifiedContent);
             console.log(`Minified HTML: ${outputPath}`)
-        }
-        // Minify JS files
-        else if (outputPath.endsWith('.mjs')) {
+        } else if (outputPath.endsWith('.mjs')) {
             let adjustedContent = content.replace(regexImport, adjustImportPathHandler);
 
-            const result = await minifyJs(adjustedContent, {
+            // AST-based processing for html templates
+            const result = processFileContent(adjustedContent, outputPath);
+
+            const minifiedResult = await Terser.minify(result.content, {
                 module: true,
-                compress: {
-                    dead_code: true
-                },
-                mangle: {
-                    toplevel: true
-                }
+                compress: {dead_code: true},
+                mangle: {toplevel: true}
             });
 
-            fs.writeFileSync(outputPath, result.code);
+            fs.writeFileSync(outputPath, minifiedResult.code);
             console.log(`Minified JS: ${outputPath}`)
         }
     } catch (e) {
@@ -161,26 +114,21 @@ const
     swContent = fs.readFileSync(path.resolve(root, 'ServiceWorker.mjs'), 'utf8'),
     promises  = [minifyFile(swContent, path.resolve(root, outputBasePath, 'ServiceWorker.mjs'))];
 
-// Execute the minification
 inputDirectories.forEach(folder => {
     const outputPath = path.resolve(root, outputBasePath, folder.replace('node_modules/neo.mjs/', ''));
-
     promises.push(minifyDirectory(path.resolve(root, folder), outputPath)
         .catch(err => {
             console.error('dist/esm Minification failed:', err);
-            process.exit(1) // Exit with error code
+            process.exit(1)
         })
     )
 });
 
 Promise.all(promises).then(() => {
-    // Copying the already skipped and minified docs/output folder
     const docsOutputPath = path.resolve(root, 'docs/output');
-
     if (fs.existsSync(docsOutputPath)) {
         fs.copySync(docsOutputPath, path.resolve(root, outputBasePath, 'docs/output'))
     }
-
     const processTime = (Math.round((new Date - startDate) * 100) / 100000).toFixed(2);
     console.log(`\nTotal time for dist/esm: ${processTime}s`);
     process.exit()

package/buildScripts/bundleParse5.mjs

@@ -0,0 +1,27 @@
+import esbuild from 'esbuild';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const build = async () => {
+    try {
+        await esbuild.build({
+            entryPoints: ['node_modules/parse5/dist/index.js'],
+            bundle: true,
+            minify: true,
+            format: 'esm',
+            outfile: path.join(__dirname, '../dist/parse5.mjs'),
+            banner: {
+                js: '/* eslint-disable */'
+            }
+        });
+        console.log('Successfully bundled and minified parse5 to dist/parse5.mjs');
+    } catch (error) {
+        console.error('Error bundling parse5:', error);
+        process.exit(1);
+    }
+};
+
+build();

package/buildScripts/util/astTemplateProcessor.mjs

@@ -0,0 +1,210 @@
+import * as acorn                   from 'acorn';
+import {generate}                   from 'astring';
+import {processHtmlTemplateLiteral} from './templateBuildProcessor.mjs';
+
+/**
+ * This module provides a self-contained, reusable pipeline for transforming `html` tagged
+ * template literals within a JavaScript file into standard Neo.mjs VDOM objects.
+ * It is designed to be called from any build script (`dist/esm`, Webpack, etc.) to ensure
+ * consistent template processing across all build environments.
+ *
+ * The core strategy is a full Abstract Syntax Tree (AST) transformation:
+ * 1. A string of JS code is parsed into an AST using `acorn`.
+ * 2. The AST is traversed to find all `html` tagged template expressions.
+ * 3. Each found template is processed by `templateBuildProcessor.mjs`, which converts the
+ *    HTML-like syntax into a serializable VDOM object, carefully preserving any
+ *    embedded JavaScript expressions as placeholders.
+ * 4. This VDOM object is then converted back into a valid AST `ObjectExpression` node.
+ * 5. The original `TaggedTemplateExpression` node is replaced in the main AST with the
+ *    new `ObjectExpression` node.
+ * 6. Finally, the modified AST is converted back into a string of JavaScript code using `astring`.
+ *
+ * This AST-centric approach is robust and correctly handles complex scenarios like nested
+ * templates and varied JavaScript expressions, which are difficult to manage with
+ * simpler methods like regular expressions.
+ */
+
+const regexHtml = /html\s*`/;
+
+/**
+ * Converts a serializable VDOM object into a valid Acorn AST `ObjectExpression`.
+ * This function is the critical bridge between the intermediate VDOM representation and the
+ * final, executable code. It recursively builds the AST, paying special attention to the
+ * `##__NEO_EXPR__...##` placeholders.
+ *
+ * When a placeholder is found, this function extracts the raw expression string and uses
+ * `acorn.parseExpressionAt` to parse it into a proper AST node. This ensures that runtime
+ * expressions are injected directly into the final AST, preserving them perfectly for
+ * when the code is executed in the browser.
+ *
+ * @param {object} json The JSON-like VDOM object from the template processor.
+ * @returns {object} A valid Acorn AST node representing the VDOM.
+ * @private
+ */
+function jsonToAst(json) {
+    if (json === null) {
+        return { type: 'Literal', value: null };
+    }
+    switch (typeof json) {
+        case 'string':
+            const exprMatch = json.match(/^##__NEO_EXPR__(.*)##__NEO_EXPR__##$/s);
+            if (exprMatch) {
+                try {
+                    return acorn.parseExpressionAt(exprMatch[1], 0, {ecmaVersion: 'latest'});
+                } catch (e) {
+                    console.error(`Failed to parse expression: ${exprMatch[1]}`, e);
+                    return { type: 'Literal', value: json };
+                }
+            }
+            return { type: 'Literal', value: json };
+        case 'number':
+        case 'boolean':
+            return { type: 'Literal', value: json };
+        case 'object':
+            if (json.__neo_component_name__) {
+                return { type: 'Identifier', name: json.__neo_component_name__ };
+            }
+            if (Array.isArray(json)) {
+                return {
+                    type: 'ArrayExpression',
+                    elements: json.map(jsonToAst)
+                };
+            }
+            const properties = Object.entries(json).map(([key, value]) => {
+                const keyNode = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+                    ? { type: 'Identifier', name: key }
+                    : { type: 'Literal', value: key };
+                return {
+                    type: 'Property',
+                    key: keyNode,
+                    value: jsonToAst(value),
+                    kind: 'init',
+                    computed: keyNode.type === 'Literal'
+                };
+            });
+            return { type: 'ObjectExpression', properties };
+        default:
+            return { type: 'Literal', value: null };
+    }
+}
+
+/**
+ * Performs a true post-order traversal of the AST (children before parent).
+ * This traversal strategy is essential for this transformation. By processing the innermost
+ * `html` templates first, we ensure that a nested template is already converted into an
+ * `ObjectExpression` before its parent template is processed. The parent can then treat
+ * the nested result as just another expression, leading to a clean, recursive solution.
+ * @param {object} node The current AST node to start traversal from.
+ * @param {function} visitor The visitor function to call on each node after its children have been visited.
+ * @private
+ */
+function postOrderWalk(node, visitor) {
+    if (!node) return;
+
+    Object.entries(node).forEach(([key, value]) => {
+        if (key === 'parent') return;
+        if (Array.isArray(value)) {
+            value.forEach(child => postOrderWalk(child, visitor));
+        } else if (typeof value === 'object' && value !== null) {
+            postOrderWalk(value, visitor);
+        }
+    });
+
+    visitor(node);
+}
+
+/**
+ * Recursively adds parent pointers to each node in the AST.
+ * While ASTs are typically one-way trees, having a back-reference to the parent makes
+ * node replacement trivial. Instead of complex logic to find and splice a node in its
+ * parent's `body` or `expressions` array, we can simply access `node.parent` to perform
+ * the replacement.
+ * @param {object} node The current AST node.
+ * @param {object|null} parent The parent of the current node.
+ * @private
+ */
+function addParentLinks(node, parent) {
+    if (!node || typeof node !== 'object') return;
+    node.parent = parent;
+    for (const key in node) {
+        if (key === 'parent') continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            child.forEach(c => addParentLinks(c, node));
+        } else {
+            addParentLinks(child, node);
+        }
+    }
+}
+
+/**
+ * The main exported function for this module. It orchestrates the entire transformation.
+ * As an optimization, it first performs a quick regex check to see if a template
+ * likely exists, avoiding the expensive AST parsing for the vast majority of files.
+ * @param {string} fileContent The raw source code of the file to process.
+ * @param {string} filePath The path to the file, used for logging errors.
+ * @returns {{content: string, hasChanges: boolean}} An object containing the transformed
+ * code and a flag indicating if any changes were made.
+ */
+export function processFileContent(fileContent, filePath) {
+    // Optimization: a quick regex check is much faster than parsing every file.
+    if (!regexHtml.test(fileContent)) {
+        return { content: fileContent, hasChanges: false };
+    }
+
+    try {
+        const ast = acorn.parse(fileContent, {ecmaVersion: 'latest', sourceType: 'module'});
+        addParentLinks(ast, null);
+
+        let hasChanges = false;
+
+        postOrderWalk(ast, (node) => {
+            if (node.type === 'TaggedTemplateExpression' && node.tag.type === 'Identifier' && node.tag.name === 'html') {
+                hasChanges = true;
+
+                // As a quality-of-life feature, if a template is the return value of a method
+                // named `render`, we automatically rename the method to `createVdom`.
+                let current = node;
+                while (current.parent) {
+                    const parent = current.parent;
+                    if ((parent.type === 'MethodDefinition' || parent.type === 'Property') && parent.key.name === 'render') {
+                        parent.key.name = 'createVdom';
+                        break;
+                    }
+                    current = parent;
+                }
+
+                const templateLiteral = node.quasi;
+                const strings = templateLiteral.quasis.map(q => q.value.cooked);
+                const expressionCodeStrings = templateLiteral.expressions.map(exprNode => generate(exprNode));
+
+                const vdom = processHtmlTemplateLiteral(strings, expressionCodeStrings);
+                const vdomAst = jsonToAst(vdom);
+
+                const parent = node.parent;
+                for (const key in parent) {
+                    if (parent[key] === node) {
+                        parent[key] = vdomAst;
+                        return;
+                    }
+                    if (Array.isArray(parent[key])) {
+                        const index = parent[key].indexOf(node);
+                        if (index > -1) {
+                            parent[key][index] = vdomAst;
+                            return;
+                        }
+                    }
+                }
+            }
+        });
+
+        return {
+            content: hasChanges ? generate(ast) : fileContent,
+            hasChanges
+        };
+    } catch (e) {
+        console.error(`Error processing HTML template in: ${filePath}`);
+        console.error(e);
+        return { content: fileContent, hasChanges: false };
+    }
+}