From b55fd507a5ca43e5cbad93ef8af199eddcfbfda9 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 13:49:23 -0500
Subject: [PATCH 1/9] feat: new microfrontend component

---
 .../tools/dynamia/zk/ui/MicroFrontend.java    | 276 ++++++++++++++++++
 1 file changed, 276 insertions(+)
 create mode 100644 platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java

diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
new file mode 100644
index 00000000..145c47a5
--- /dev/null
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
@@ -0,0 +1,276 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.zk.ui;
+
+import org.zkoss.zk.ui.Page;
+import org.zkoss.zk.ui.WrongValueException;
+import org.zkoss.zk.ui.ext.AfterCompose;
+import org.zkoss.zk.ui.ext.DynamicPropertied;
+import org.zkoss.zk.ui.util.Clients;
+import org.zkoss.zul.Div;
+import tools.dynamia.commons.StringPojoParser;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * ZK component that embeds an external JavaScript bundle ("microfrontend") built with any
+ * framework (Vue, React, Svelte, plain JS, etc.) inside a ZUL page.
+ * <p>
+ * The bundle is loaded once per {@code src} (loads are cached/shared client-side across every
+ * {@code MicroFrontend} instance on the page) and mounted using one of two strategies, selected
+ * with {@link #setMode(String)}:
+ * <ul>
+ *     <li>{@link #MODE_CUSTOM_ELEMENT} (default): the bundle registers a
+ *     <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components">Custom Element</a>
+ *     (e.g. via {@code customElements.define(...)}, or Vue's {@code defineCustomElement}). This
+ *     component creates that element, assigns {@link #setProps(Map)} as properties/attributes and
+ *     appends it to its container. The browser mounts/unmounts it automatically through the
+ *     element's own {@code connectedCallback}/{@code disconnectedCallback}.</li>
+ *     <li>{@link #MODE_MOUNT_FN}: the bundle exposes global mount/unmount functions (a convention
+ *     similar to single-spa), invoked explicitly as {@code window[mountFn](container, props)} and
+ *     {@code window[unmountFn](container)} when this component is rendered and detached.</li>
+ * </ul>
+ * Any extra ZUL attribute not matching a bean property (via {@link DynamicPropertied}) is
+ * forwarded as a prop to the mounted microfrontend, e.g. {@code userId="${user.id}"}.
+ *
+ * Example:
+ * <pre>{@code
+ * <microfrontend src="/bundles/my-vue-app.js" tag="my-vue-app" userId="${user.id}"/>
+ * }</pre>
+ *
+ * @author Mario A. Serrano Leones
+ */
+public class MicroFrontend extends Div implements DynamicPropertied, AfterCompose {
+
+    /** Mounts the bundle's custom element (default mode). */
+    public static final String MODE_CUSTOM_ELEMENT = "custom-element";
+    /** Mounts the bundle through global {@code window[mountFn]/window[unmountFn]} functions. */
+    public static final String MODE_MOUNT_FN = "mount-fn";
+
+    private String src;
+    private String type = "module";
+    private String mode = MODE_CUSTOM_ELEMENT;
+    private String tag;
+    private String mountFn;
+    private String unmountFn;
+    private final Map<String, Object> props = new LinkedHashMap<>();
+    private boolean composed;
+
+    public MicroFrontend() {
+        setSclass("microfrontend");
+    }
+
+    /**
+     * Mounts the microfrontend once the component tree is composed. Property setters invoked
+     * while the ZUL page is still being parsed (e.g. {@code src}, {@code tag}, dynamic props such
+     * as {@code userId}) call {@link #mount()} eagerly to support runtime changes, but they are
+     * no-ops until this flag is set, so the initial mount happens exactly once, with every
+     * attribute already applied.
+     */
+    @Override
+    public void afterCompose() {
+        composed = true;
+        mount();
+    }
+
+    public String getSrc() {
+        return src;
+    }
+
+    /**
+     * Sets the URL of the JavaScript bundle to load, e.g. {@code /bundles/my-app.js}, and
+     * (re)mounts the microfrontend.
+     *
+     * @param src bundle URL
+     */
+    public void setSrc(String src) {
+        this.src = src;
+        mount();
+    }
+
+    public String getType() {
+        return type;
+    }
+
+    /**
+     * Sets the {@code <script type="...">} used to load the bundle. Defaults to {@code module}.
+     *
+     * @param type script type, e.g. {@code module} or {@code text/javascript}
+     */
+    public void setType(String type) {
+        this.type = type;
+    }
+
+    public String getMode() {
+        return mode;
+    }
+
+    /**
+     * Sets the mounting strategy: {@link #MODE_CUSTOM_ELEMENT} or {@link #MODE_MOUNT_FN}.
+     *
+     * @param mode mounting mode
+     */
+    public void setMode(String mode) {
+        this.mode = mode;
+        mount();
+    }
+
+    public String getTag() {
+        return tag;
+    }
+
+    /**
+     * Sets the custom element tag name to create, required when {@link #MODE_CUSTOM_ELEMENT} is
+     * used, e.g. {@code my-vue-app}.
+     *
+     * @param tag custom element tag name
+     */
+    public void setTag(String tag) {
+        this.tag = tag;
+        mount();
+    }
+
+    public String getMountFn() {
+        return mountFn;
+    }
+
+    /**
+     * Sets the name of the global function used to mount the bundle, required when
+     * {@link #MODE_MOUNT_FN} is used. Invoked as {@code window[mountFn](container, props)}.
+     *
+     * @param mountFn global mount function name
+     */
+    public void setMountFn(String mountFn) {
+        this.mountFn = mountFn;
+        mount();
+    }
+
+    public String getUnmountFn() {
+        return unmountFn;
+    }
+
+    /**
+     * Sets the name of the global function used to unmount the bundle, required when
+     * {@link #MODE_MOUNT_FN} is used. Invoked as {@code window[unmountFn](container)} when this
+     * component is detached from the page.
+     *
+     * @param unmountFn global unmount function name
+     */
+    public void setUnmountFn(String unmountFn) {
+        this.unmountFn = unmountFn;
+    }
+
+    public Map<String, Object> getProps() {
+        return props;
+    }
+
+    /**
+     * Replaces all props passed to the mounted microfrontend and remounts it.
+     *
+     * @param props props map, must be JSON-serializable
+     */
+    public void setProps(Map<String, Object> props) {
+        this.props.clear();
+        if (props != null) {
+            this.props.putAll(props);
+        }
+        mount();
+    }
+
+    /**
+     * Adds or replaces a single prop passed to the mounted microfrontend and remounts it.
+     *
+     * @param name  prop name
+     * @param value prop value, must be JSON-serializable
+     */
+    public void addProp(String name, Object value) {
+        props.put(name, value);
+        mount();
+    }
+
+    /**
+     * Builds the client-side configuration and instructs the browser to load (if not already
+     * cached) the bundle and mount it into this component's container element. No-op until the
+     * component is attached to a page and {@link #src} plus the mode-specific requirements
+     * ({@link #tag} or {@link #mountFn}) are set.
+     */
+    private void mount() {
+        if (!composed || getPage() == null || src == null || !isMountable()) {
+            return;
+        }
+        Clients.evalJavaScript("dynamiaMountMicrofrontend('" + getUuid() + "', " + buildConfig() + ");");
+    }
+
+    private boolean isMountable() {
+        if (MODE_CUSTOM_ELEMENT.equals(mode)) {
+            return tag != null;
+        }
+        return mountFn != null;
+    }
+
+    private String buildConfig() {
+        Map<String, Object> config = new LinkedHashMap<>();
+        config.put("src", src);
+        config.put("type", type);
+        config.put("mode", mode);
+        config.put("tag", tag);
+        config.put("mountFn", mountFn);
+        config.put("unmountFn", unmountFn);
+        config.put("props", props);
+        return StringPojoParser.convertMapToJson(config);
+    }
+
+    /**
+     * Unmounts the microfrontend client-side when this component leaves the page, preventing
+     * memory leaks from mounted framework instances (Vue apps, React roots, subscriptions, etc.)
+     * when using {@link #MODE_MOUNT_FN}. Components using {@link #MODE_CUSTOM_ELEMENT} are cleaned
+     * up automatically by the browser through the custom element's {@code disconnectedCallback}.
+     *
+     * @param page the page this component is detached from
+     */
+    @Override
+    public void onPageDetached(Page page) {
+        if (MODE_MOUNT_FN.equals(mode) && unmountFn != null) {
+            Clients.evalJavaScript("dynamiaUnmountMicrofrontend('" + getUuid() + "', " + buildConfig() + ");");
+        }
+        super.onPageDetached(page);
+    }
+
+    @Override
+    public boolean hasDynamicProperty(String name) {
+        return props.containsKey(name);
+    }
+
+    @Override
+    public Object getDynamicProperty(String name) {
+        return props.get(name);
+    }
+
+    /**
+     * Forwards any extra ZUL attribute not matching a bean property as a prop for the mounted
+     * microfrontend.
+     *
+     * @param name  prop name
+     * @param value prop value, must be JSON-serializable
+     */
+    @Override
+    public void setDynamicProperty(String name, Object value) throws WrongValueException {
+        props.put(name, value);
+        mount();
+    }
+}

From 2cc83aef547384b887e648a824d24abfa3ee6a13 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 13:49:35 -0500
Subject: [PATCH 2/9] feat: new microfrontend component

---
 .../resources/pages/microfrontend-demo.zul    | 29 ++++++++++++
 .../resources/static/js/microfrontend-demo.js | 44 +++++++++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
 create mode 100644 examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js

diff --git a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
new file mode 100644
index 00000000..b2a4b395
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
@@ -0,0 +1,29 @@
+<zk xmlns:n="native">
+
+    <zscript><![CDATA[
+        void toggle() {
+            if (wrapper.getParent() != null) {
+                wrapper.detach();
+            }
+        }
+    ]]></zscript>
+
+    <div hflex="1" vflex="1">
+        <n:h3>MicroFrontend Component Demo</n:h3>
+
+        <div id="wrapper" hflex="1">
+            <groupbox title="custom-element mode" width="50%">
+                <caption label="custom-element mode"/>
+                <microfrontend src="/static/js/microfrontend-demo.js" tag="demo-widget"
+                               mode="custom-element" userId="42" theme="dark"/>
+            </groupbox>
+            <groupbox title="mount-fn mode" width="50%">
+                <caption label="mount-fn mode"/>
+                <microfrontend src="/static/js/microfrontend-demo.js" mode="mount-fn"
+                               mountFn="mountDemoApp" unmountFn="unmountDemoApp" userId="99"/>
+            </groupbox>
+        </div>
+
+        <button label="Detach wrapper (verify unmount in console)" onClick="toggle()"/>
+    </div>
+</zk>
diff --git a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
new file mode 100644
index 00000000..26354cc2
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
@@ -0,0 +1,44 @@
+/**
+ * Fake "microfrontend" bundle used to manually verify tools.dynamia.zk.ui.MicroFrontend.
+ * Simulates what a Vue/React build would ship: a custom element AND a mount/unmount pair.
+ */
+(function () {
+    class DemoWidget extends HTMLElement {
+        connectedCallback() {
+            console.log('[demo-widget] connectedCallback', {userId: this.userId, theme: this.theme});
+            this.innerHTML =
+                '<div style="padding:1rem;border:2px dashed #6c5ce7;border-radius:8px">' +
+                '<strong>custom-element mode</strong><br/>' +
+                'userId: ' + this.userId + '<br/>' +
+                'theme: ' + this.theme + '<br/>' +
+                '<button id="inc">clicks: 0</button>' +
+                '</div>';
+            var btn = this.querySelector('#inc');
+            var clicks = 0;
+            btn.addEventListener('click', function () {
+                clicks++;
+                btn.textContent = 'clicks: ' + clicks;
+            });
+        }
+
+        disconnectedCallback() {
+            console.log('[demo-widget] disconnectedCallback (auto cleanup by browser)');
+        }
+    }
+
+    if (!customElements.get('demo-widget')) {
+        customElements.define('demo-widget', DemoWidget);
+    }
+
+    window.mountDemoApp = function (container, props) {
+        container.innerHTML =
+            '<div style="padding:1rem;border:2px solid #00b894;border-radius:8px">' +
+            '<strong>mount-fn mode</strong><br/>userId: ' + props.userId + '</div>';
+        console.log('[demo-app] mounted via mount-fn', props);
+    };
+
+    window.unmountDemoApp = function (container) {
+        container.innerHTML = '';
+        console.log('[demo-app] unmounted via mount-fn');
+    };
+})();

From 8d88a57e52ddc7b977fee95c4255f9dc5a8f13c0 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 13:49:39 -0500
Subject: [PATCH 3/9] feat: new microfrontend component

---
 .../main/resources/metainfo/zk/lang-addon.xml | 11 +++
 .../dynamia-tools/js/zk/dynamia-tools.js      | 92 +++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/platform/ui/zk/src/main/resources/metainfo/zk/lang-addon.xml b/platform/ui/zk/src/main/resources/metainfo/zk/lang-addon.xml
index 6f0ff675..bc3e44ea 100644
--- a/platform/ui/zk/src/main/resources/metainfo/zk/lang-addon.xml
+++ b/platform/ui/zk/src/main/resources/metainfo/zk/lang-addon.xml
@@ -258,6 +258,17 @@
         </mold>
     </component>
 
+    <component>
+        <component-name>microfrontend</component-name>
+        <component-class>tools.dynamia.zk.ui.MicroFrontend</component-class>
+        <widget-class>zul.wgt.Div</widget-class>
+
+        <mold>
+            <mold-name>default</mold-name>
+            <mold-uri>mold/div.js</mold-uri>
+        </mold>
+    </component>
+
 
     <component>
         <component-name>enumiconimage</component-name>
diff --git a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
index 08a0a0be..2b89707d 100644
--- a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
+++ b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
@@ -15,6 +15,98 @@
  * limitations under the License.
  */
 
+/**
+ * Registry used by the MicroFrontend ZK component (tools.dynamia.zk.ui.MicroFrontend) to cache
+ * bundle loading promises across component instances sharing the same "src".
+ */
+var DynamiaMicrofrontends = window.DynamiaMicrofrontends || {scripts: {}};
+
+/**
+ * Loads a JavaScript bundle once and caches the loading promise so multiple microfrontend
+ * instances pointing to the same src share a single <script> tag/network request.
+ * @param {string} src - Bundle URL.
+ * @param {string} type - Script type, e.g. "module" or "text/javascript".
+ * @returns {Promise<void>} Resolves once the bundle has loaded.
+ */
+function dynamiaLoadScript(src, type) {
+    if (!DynamiaMicrofrontends.scripts[src]) {
+        DynamiaMicrofrontends.scripts[src] = new Promise(function (resolve, reject) {
+            var script = document.createElement('script');
+            script.src = src;
+            script.type = type || 'module';
+            script.onload = function () {
+                resolve();
+            };
+            script.onerror = function () {
+                delete DynamiaMicrofrontends.scripts[src];
+                reject(new Error('Dynamia Microfrontend: failed to load bundle ' + src));
+            };
+            document.head.appendChild(script);
+        });
+    }
+    return DynamiaMicrofrontends.scripts[src];
+}
+
+/**
+ * Loads (if needed) and mounts a microfrontend bundle into the container element of a
+ * MicroFrontend ZK component.
+ * @param {string} containerId - Id of the component's container element (its ZK uuid).
+ * @param {object} config - {src, type, mode, tag, mountFn, unmountFn, props}.
+ */
+function dynamiaMountMicrofrontend(containerId, config) {
+    dynamiaLoadScript(config.src, config.type).then(function () {
+        var container = document.getElementById(containerId);
+        if (!container) {
+            return;
+        }
+        var props = config.props || {};
+        container.innerHTML = '';
+        if (config.mode === 'mount-fn') {
+            var mountFn = window[config.mountFn];
+            if (typeof mountFn === 'function') {
+                mountFn(container, props);
+            } else {
+                console.error('Dynamia Microfrontend: mount function "' + config.mountFn + '" not found on window');
+            }
+        } else {
+            var el = document.createElement(config.tag);
+            Object.keys(props).forEach(function (key) {
+                var value = props[key];
+                el[key] = value;
+                el.setAttribute(key, typeof value === 'object' ? JSON.stringify(value) : value);
+            });
+            container.appendChild(el);
+        }
+    }).catch(function (err) {
+        console.error(err);
+    });
+}
+
+/**
+ * Unmounts a microfrontend previously mounted with {@link dynamiaMountMicrofrontend} in
+ * "mount-fn" mode. Components using "custom-element" mode are cleaned up automatically by the
+ * browser when their DOM node is removed (disconnectedCallback), so this is a no-op for them.
+ * @param {string} containerId - Id of the component's container element (its ZK uuid).
+ * @param {object} config - {mode, unmountFn}.
+ */
+function dynamiaUnmountMicrofrontend(containerId, config) {
+    if (config.mode !== 'mount-fn' || !config.unmountFn) {
+        return;
+    }
+    var container = document.getElementById(containerId);
+    if (!container) {
+        return;
+    }
+    var unmountFn = window[config.unmountFn];
+    if (typeof unmountFn === 'function') {
+        try {
+            unmountFn(container);
+        } catch (err) {
+            console.error(err);
+        }
+    }
+}
+
 /**
  * Changes the browser URL hash or history state.
  * @param {string} value - The new hash value or page identifier.

From 37595908878bb1ac79f88e9c683d49de4ccd746b Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 13:49:52 -0500
Subject: [PATCH 4/9] feat: new microfrontend component

---
 examples/demo-zk-books/pom.xml                                  | 2 +-
 .../java/mybookstore/providers/MyBookStoreModuleProvider.java   | 1 +
 .../zk/src/main/java/tools/dynamia/zk/ComponentAliasIndex.java  | 1 +
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/examples/demo-zk-books/pom.xml b/examples/demo-zk-books/pom.xml
index fbe29497..186ce3e7 100644
--- a/examples/demo-zk-books/pom.xml
+++ b/examples/demo-zk-books/pom.xml
@@ -47,7 +47,7 @@
         <timestamp>${maven.build.timestamp}</timestamp>
         <maven.build.timestamp.format>yyyyMMdd</maven.build.timestamp.format>
 
-        <tools.version>26.6.0</tools.version>
+        <tools.version>26.7.0</tools.version>
 
     </properties>
 
diff --git a/examples/demo-zk-books/src/main/java/mybookstore/providers/MyBookStoreModuleProvider.java b/examples/demo-zk-books/src/main/java/mybookstore/providers/MyBookStoreModuleProvider.java
index 94662ba7..b88f99c9 100644
--- a/examples/demo-zk-books/src/main/java/mybookstore/providers/MyBookStoreModuleProvider.java
+++ b/examples/demo-zk-books/src/main/java/mybookstore/providers/MyBookStoreModuleProvider.java
@@ -45,6 +45,7 @@ public Module getModule() { //<2>
                         .addPage(
                                 new Page("components", "Custom Components", "classpath:/pages/custom-components.zul"),
                                 new Page("vue", "Vue Example", "classpath:/pages/vue-integration.zul"),
+                                new Page("microfrontend", "MicroFrontend", "classpath:/pages/microfrontend-demo.zul"),
                                 new Page("mvvm", "Standard ZK MVVM", "classpath:/pages/standard-mvvm.zul"),
                                 new Page("chartjs", "Charts for ZK", "classpath:/pages/chartjs.zul"),
                                 new Page("aceditor", "Ace Code Editor", "classpath:/pages/aceditor.zul"),
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ComponentAliasIndex.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ComponentAliasIndex.java
index e51fc592..cc755081 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/ComponentAliasIndex.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ComponentAliasIndex.java
@@ -86,6 +86,7 @@ public class ComponentAliasIndex extends HashMap<String, Class<? extends Compone
         getInstance().add("enumlabel", EnumLabel.class);
         getInstance().add(EnumListbox.class);
         getInstance().add(Import.class);
+        getInstance().add(MicroFrontend.class);
         getInstance().add(Infobox.class);
         getInstance().add("localebox", LocaleCombobox.class);
         getInstance().add("timezonebox", TimeZoneCombobox.class);

From e152b5eacef0aef76dd316ff3643c12a55a55b0c Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 15:49:33 -0500
Subject: [PATCH 5/9] feat: new microfrontend component

---
 .../viewmodel/MicroFrontendDemoVM.java        |  95 +++++++
 .../resources/pages/microfrontend-demo.zul    |  37 ++-
 .../static/css/microfrontend-demo.css         |  10 +
 .../resources/static/js/microfrontend-demo.js |  24 +-
 .../next/demo-app/assets/index-a1b2c3d4.js    |  18 ++
 .../next/demo-app/assets/index-e5f6g7h8.css   |   6 +
 .../resources/static/next/demo-app/index.html |  14 +
 .../tools/dynamia/zk/ui/MicroFrontend.java    | 183 ++++++++++++-
 .../dynamia-tools/js/zk/dynamia-tools.js      | 247 +++++++++++++++++-
 9 files changed, 601 insertions(+), 33 deletions(-)
 create mode 100644 examples/demo-zk-books/src/main/java/mybookstore/viewmodel/MicroFrontendDemoVM.java
 create mode 100644 examples/demo-zk-books/src/main/resources/static/css/microfrontend-demo.css
 create mode 100644 examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-a1b2c3d4.js
 create mode 100644 examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-e5f6g7h8.css
 create mode 100644 examples/demo-zk-books/src/main/resources/static/next/demo-app/index.html

diff --git a/examples/demo-zk-books/src/main/java/mybookstore/viewmodel/MicroFrontendDemoVM.java b/examples/demo-zk-books/src/main/java/mybookstore/viewmodel/MicroFrontendDemoVM.java
new file mode 100644
index 00000000..4e85cebc
--- /dev/null
+++ b/examples/demo-zk-books/src/main/java/mybookstore/viewmodel/MicroFrontendDemoVM.java
@@ -0,0 +1,95 @@
+package mybookstore.viewmodel;
+
+import org.zkoss.bind.annotation.BindingParam;
+import org.zkoss.bind.annotation.Command;
+import org.zkoss.bind.annotation.NotifyChange;
+
+import java.time.LocalTime;
+import java.time.format.DateTimeFormatter;
+import java.util.Random;
+
+/**
+ * Backs the "MVVM mode" panel of the MicroFrontend demo (microfrontend-demo.zul). Every bound
+ * value below is a plain bean property, so it works with {@code @bind(vm.xxx)} with zero extra
+ * code in tools.dynamia.zk.ui.MicroFrontend. {@link #getUser()} in particular proves that binding
+ * a Java object (not just Strings/numbers) reaches the browser as real JSON: MicroFrontend's
+ * buildConfig() serializes the whole props map through StringPojoParser.convertMapToJson, which is
+ * backed by Jackson and recursively serializes nested POJOs, not toString().
+ */
+public class MicroFrontendDemoVM {
+
+    private static final String[] ROLES = {"admin", "editor", "viewer"};
+    private static final DateTimeFormatter TIME_FORMAT = DateTimeFormatter.ofPattern("HH:mm:ss");
+    private final Random random = new Random();
+
+    private String theme = "dark";
+    private boolean shadow;
+    private DemoUser user = new DemoUser(1L, "Ada Lovelace", "admin");
+    private String lastEvent = "(none yet)";
+
+    public String getTheme() {
+        return theme;
+    }
+
+    public boolean isShadow() {
+        return shadow;
+    }
+
+    public DemoUser getUser() {
+        return user;
+    }
+
+    public String getLastEvent() {
+        return lastEvent;
+    }
+
+    @Command
+    @NotifyChange("theme")
+    public void toggleTheme() {
+        theme = "dark".equals(theme) ? "light" : "dark";
+    }
+
+    @Command
+    @NotifyChange("shadow")
+    public void toggleShadow() {
+        shadow = !shadow;
+    }
+
+    @Command
+    @NotifyChange("user")
+    public void randomizeUser() {
+        user = new DemoUser(random.nextLong(1000), "User " + random.nextInt(1000), ROLES[random.nextInt(ROLES.length)]);
+    }
+
+    @Command
+    @NotifyChange("lastEvent")
+    public void handleMicrofrontendEvent(@BindingParam("data") Object data) {
+        lastEvent = LocalTime.now().format(TIME_FORMAT) + " -> " + data;
+    }
+
+    /** Bound as a whole to the "user" prop, proving nested POJO-to-JSON serialization. */
+    public static class DemoUser {
+
+        private final Long id;
+        private final String name;
+        private final String role;
+
+        public DemoUser(Long id, String name, String role) {
+            this.id = id;
+            this.name = name;
+            this.role = role;
+        }
+
+        public Long getId() {
+            return id;
+        }
+
+        public String getName() {
+            return name;
+        }
+
+        public String getRole() {
+            return role;
+        }
+    }
+}
diff --git a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
index b2a4b395..85902797 100644
--- a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
+++ b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
@@ -6,21 +6,44 @@
                 wrapper.detach();
             }
         }
+
+        void handleMicrofrontendEvent(org.zkoss.zk.ui.event.Event event) {
+            Clients.showNotification("onMicrofrontendEvent: " + event.getData());
+        }
     ]]></zscript>
 
     <div hflex="1" vflex="1">
         <n:h3>MicroFrontend Component Demo</n:h3>
 
         <div id="wrapper" hflex="1">
-            <groupbox title="custom-element mode" width="50%">
+            <groupbox width="50%">
                 <caption label="custom-element mode"/>
-                <microfrontend src="/static/js/microfrontend-demo.js" tag="demo-widget"
-                               mode="custom-element" userId="42" theme="dark"/>
+                <microfrontend src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
+                               tag="demo-widget" mode="custom-element" userId="42" theme="dark"
+                               onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
+            </groupbox>
+            <groupbox width="50%">
+                <caption label="mount-fn mode, shadow DOM isolated"/>
+                <microfrontend src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
+                               mode="mount-fn" mountFn="mountDemoApp" unmountFn="unmountDemoApp" userId="99"
+                               shadow="true" onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
+            </groupbox>
+            <groupbox width="50%">
+                <caption label="app auto-discovery mode, self-mounting (no tag/mountFn)"/>
+                <microfrontend app="/static/next/demo-app"/>
             </groupbox>
-            <groupbox title="mount-fn mode" width="50%">
-                <caption label="mount-fn mode"/>
-                <microfrontend src="/static/js/microfrontend-demo.js" mode="mount-fn"
-                               mountFn="mountDemoApp" unmountFn="unmountDemoApp" userId="99"/>
+            <groupbox width="50%" viewModel="@id('vm') @init('mybookstore.viewmodel.MicroFrontendDemoVM')">
+                <caption label="MVVM mode: @bind, @command, POJO bound as JSON"/>
+                <microfrontend src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
+                               tag="demo-widget" theme="@bind(vm.theme)" shadow="@bind(vm.shadow)"
+                               user="@bind(vm.user)"
+                               onMicrofrontendEvent="@command('handleMicrofrontendEvent', data=event.data)"/>
+                <hbox>
+                    <button label="Toggle theme" onClick="@command('toggleTheme')"/>
+                    <button label="Toggle shadow" onClick="@command('toggleShadow')"/>
+                    <button label="Randomize user" onClick="@command('randomizeUser')"/>
+                </hbox>
+                <label value="@load(vm.lastEvent)"/>
             </groupbox>
         </div>
 
diff --git a/examples/demo-zk-books/src/main/resources/static/css/microfrontend-demo.css b/examples/demo-zk-books/src/main/resources/static/css/microfrontend-demo.css
new file mode 100644
index 00000000..022c38b2
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/static/css/microfrontend-demo.css
@@ -0,0 +1,10 @@
+/* Loaded via the MicroFrontend "css" attribute, proves external stylesheets ship with a bundle. */
+.demo-widget-emit-btn {
+    margin-top: .5rem;
+    background: #6c5ce7;
+    color: #fff;
+    border: none;
+    border-radius: 6px;
+    padding: .4rem .8rem;
+    cursor: pointer;
+}
diff --git a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
index 26354cc2..8f80f551 100644
--- a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
+++ b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
@@ -5,13 +5,19 @@
 (function () {
     class DemoWidget extends HTMLElement {
         connectedCallback() {
-            console.log('[demo-widget] connectedCallback', {userId: this.userId, theme: this.theme});
+            console.log('[demo-widget] connectedCallback', {userId: this.userId, theme: this.theme, user: this.user});
+            var userLine = '';
+            if (this.user && typeof this.user === 'object') {
+                userLine = 'user: ' + JSON.stringify(this.user) + ' (typeof ' + typeof this.user + ')<br/>';
+            }
             this.innerHTML =
                 '<div style="padding:1rem;border:2px dashed #6c5ce7;border-radius:8px">' +
                 '<strong>custom-element mode</strong><br/>' +
                 'userId: ' + this.userId + '<br/>' +
                 'theme: ' + this.theme + '<br/>' +
-                '<button id="inc">clicks: 0</button>' +
+                userLine +
+                '<button id="inc">clicks: 0</button><br/>' +
+                '<button id="emit" class="demo-widget-emit-btn">emit event to server</button>' +
                 '</div>';
             var btn = this.querySelector('#inc');
             var clicks = 0;
@@ -19,6 +25,12 @@
                 clicks++;
                 btn.textContent = 'clicks: ' + clicks;
             });
+            var dynamiaEmit = this.dynamiaEmit;
+            this.querySelector('#emit').addEventListener('click', function () {
+                if (typeof dynamiaEmit === 'function') {
+                    dynamiaEmit({from: 'custom-element', clicks: clicks});
+                }
+            });
         }
 
         disconnectedCallback() {
@@ -33,7 +45,13 @@
     window.mountDemoApp = function (container, props) {
         container.innerHTML =
             '<div style="padding:1rem;border:2px solid #00b894;border-radius:8px">' +
-            '<strong>mount-fn mode</strong><br/>userId: ' + props.userId + '</div>';
+            '<strong>mount-fn mode</strong><br/>userId: ' + props.userId + '<br/>' +
+            '<button id="emit" class="demo-widget-emit-btn">emit event to server</button></div>';
+        container.querySelector('#emit').addEventListener('click', function () {
+            if (typeof props.dynamiaEmit === 'function') {
+                props.dynamiaEmit({from: 'mount-fn', userId: props.userId});
+            }
+        });
         console.log('[demo-app] mounted via mount-fn', props);
     };
 
diff --git a/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-a1b2c3d4.js b/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-a1b2c3d4.js
new file mode 100644
index 00000000..abbbf8da
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-a1b2c3d4.js
@@ -0,0 +1,18 @@
+/**
+ * Fake hashed Vite chunk used to manually verify MicroFrontend's "app" auto-discovery + "auto"
+ * mount mode: a plain self-mounting SPA bundle, like `createApp(App).mount('#demo-app-root')`
+ * would produce, with no custom element and no window mount/unmount functions.
+ */
+(function () {
+    var root = document.getElementById('demo-app-root');
+    if (!root) {
+        console.error('[demo-app] #demo-app-root not found, was the index.html body replicated?');
+        return;
+    }
+    console.log('[demo-app] self-mounted into #demo-app-root');
+    root.innerHTML =
+        '<div class="demo-app-widget-box">' +
+        '<strong>app auto-discovery mode</strong><br/>' +
+        'self-mounted, no tag/mountFn needed' +
+        '</div>';
+})();
diff --git a/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-e5f6g7h8.css b/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-e5f6g7h8.css
new file mode 100644
index 00000000..af2078b0
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/static/next/demo-app/assets/index-e5f6g7h8.css
@@ -0,0 +1,6 @@
+/* Fake hashed Vite CSS chunk, loaded automatically via MicroFrontend's "app" discovery. */
+.demo-app-widget-box {
+    padding: 1rem;
+    border: 2px dotted #e17055;
+    border-radius: 8px;
+}
diff --git a/examples/demo-zk-books/src/main/resources/static/next/demo-app/index.html b/examples/demo-zk-books/src/main/resources/static/next/demo-app/index.html
new file mode 100644
index 00000000..0897a72f
--- /dev/null
+++ b/examples/demo-zk-books/src/main/resources/static/next/demo-app/index.html
@@ -0,0 +1,14 @@
+<!-- Mimics a Vite `dist/index.html` output for a self-mounting SPA (not a custom-element library
+     build), used to manually verify MicroFrontend's "app" auto-discovery + "auto" mount mode. -->
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8"/>
+    <title>demo-app</title>
+    <script type="module" crossorigin src="/static/next/demo-app/assets/index-a1b2c3d4.js"></script>
+    <link rel="stylesheet" crossorigin href="/static/next/demo-app/assets/index-e5f6g7h8.css">
+</head>
+<body>
+<div id="demo-app-root"></div>
+</body>
+</html>
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
index 145c47a5..1569db7d 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
@@ -18,8 +18,10 @@
 
 import org.zkoss.zk.ui.Page;
 import org.zkoss.zk.ui.WrongValueException;
+import org.zkoss.zk.ui.event.Events;
 import org.zkoss.zk.ui.ext.AfterCompose;
 import org.zkoss.zk.ui.ext.DynamicPropertied;
+import org.zkoss.zk.ui.sys.ComponentCtrl;
 import org.zkoss.zk.ui.util.Clients;
 import org.zkoss.zul.Div;
 import tools.dynamia.commons.StringPojoParser;
@@ -44,13 +46,68 @@
  *     <li>{@link #MODE_MOUNT_FN}: the bundle exposes global mount/unmount functions (a convention
  *     similar to single-spa), invoked explicitly as {@code window[mountFn](container, props)} and
  *     {@code window[unmountFn](container)} when this component is rendered and detached.</li>
+ *     <li>{@link #MODE_AUTO}: for a bundle that self-mounts into a hardcoded selector at import
+ *     time, as a default {@code vite build} of an app (not a custom-element library) does, e.g.
+ *     {@code createApp(App).mount('#app')}. Selected automatically when {@link #setApp(String)} is
+ *     used and neither {@link #setTag} nor {@link #setMountFn} is set: the {@code <body>} markup
+ *     of the discovered {@code index.html} (its mount target element(s), stripped of any
+ *     {@code <script>} tags) is copied into this component's container <em>before</em> the bundle
+ *     loads, so the bundle's own bootstrap code finds its target and mounts itself, no
+ *     {@link #setTag} or {@link #setMountFn} required. There is no unmount hook for this mode (the
+ *     bundle exposes none), and it mounts only once — it does not support remounting into a new
+ *     container on prop changes. Only one live instance of a given {@link #app} is allowed per
+ *     page: its script runs once and self-mounts via a hardcoded id from its own index.html, so a
+ *     second simultaneous instance would either duplicate that id or silently render nothing; it
+ *     is refused with a console error instead. {@link #setProps(Map)}/dynamic props and
+ *     {@code dynamiaEmit} are <strong>not</strong> delivered to the bundle in this mode: a
+ *     self-mounting bundle has no defined channel to receive them, so it must fetch its own
+ *     data/config independently. Use {@link #MODE_CUSTOM_ELEMENT} or {@link #MODE_MOUNT_FN} — both
+ *     of which support multiple simultaneous instances cleanly — if the server needs to pass props
+ *     in, receive events back, or embed the same app more than once on one page.</li>
  * </ul>
  * Any extra ZUL attribute not matching a bean property (via {@link DynamicPropertied}) is
  * forwarded as a prop to the mounted microfrontend, e.g. {@code userId="${user.id}"}.
+ * <p>
+ * {@link #setShadow(boolean)} mounts the bundle inside a
+ * <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM">shadow
+ * root</a> attached to this component's container, isolating its CSS/DOM from the host ZK page in
+ * both directions (host styles don't leak in, the microfrontend's styles don't leak out). Any
+ * {@link #setCss} / auto-discovered stylesheet is loaded as an inline {@code <style>} inside the
+ * shadow root instead of the document {@code <head>}. Supported with {@link #MODE_CUSTOM_ELEMENT}
+ * (the created element and a {@code <style>} are appended to the shadow root) and
+ * {@link #MODE_MOUNT_FN} ({@code mountFn} receives a plain {@code <div>} created inside the shadow
+ * root instead of the container itself). <strong>Not</strong> supported with {@link #MODE_AUTO}:
+ * the bundle finds its mount target via a page-level {@code document.getElementById(...)} call it
+ * makes itself, which cannot see inside a shadow root by design — {@code shadow=true} with app
+ * auto-discovery and no {@code tag}/{@code mountFn} is refused client-side with a console error.
+ * <p>
+ * Instead of {@link #setSrc} / {@link #setCss}, {@link #setApp(String)} points to the root folder
+ * of a bundler's production build (e.g. Vite's {@code dist/} copied as-is into a static folder).
+ * The browser fetches {@code {app}/index.html} and extracts the {@code <script type="module">}
+ * and {@code <link rel="stylesheet">} tags it references, so hashed output filenames
+ * (e.g. {@code assets/index-mU_jDp6H.js}) never need to be hardcoded. This relies on the
+ * conventional single-entry {@code index.html} that Vite/Rollup/Webpack SPA builds produce; it
+ * has only been verified against Vite output — check the generated {@code index.html} manually if
+ * you use another bundler.
+ * <p>
+ * All bean properties ({@link #setSrc}, {@link #setMode}, {@link #setProps}, dynamic props, etc.)
+ * are plain getter/setter pairs, so they work with ZK MVVM data binding out of the box, e.g.
+ * {@code src="@bind(vm.bundleUrl)"} or {@code userId="@bind(vm.userId)"}. For the reverse
+ * direction, the mounted microfrontend can call the {@code dynamiaEmit(data)} function injected
+ * into its props to notify the server, which fires {@value #ON_EVENT} and can be bound with
+ * {@code onMicrofrontendEvent="@command('handleIt', data=event.data)"}.
  *
  * Example:
  * <pre>{@code
- * <microfrontend src="/bundles/my-vue-app.js" tag="my-vue-app" userId="${user.id}"/>
+ * <microfrontend src="/bundles/my-vue-app.js" css="/bundles/my-vue-app.css" tag="my-vue-app"
+ *                userId="${user.id}" onMicrofrontendEvent="@command('handleIt', data=event.data)"/>
+ *
+ * <microfrontend app="/static/next/subscription" tag="my-vue-app" userId="${user.id}"/>
+ *
+ * <microfrontend app="/static/next/subscription" userId="${user.id}"/>
+ *
+ * <microfrontend src="/bundles/my-vue-app.js" css="/bundles/my-vue-app.css" mode="mount-fn"
+ *                mountFn="mount" unmountFn="unmount" shadow="true"/>
  * }</pre>
  *
  * @author Mario A. Serrano Leones
@@ -61,18 +118,36 @@ public class MicroFrontend extends Div implements DynamicPropertied, AfterCompos
     public static final String MODE_CUSTOM_ELEMENT = "custom-element";
     /** Mounts the bundle through global {@code window[mountFn]/window[unmountFn]} functions. */
     public static final String MODE_MOUNT_FN = "mount-fn";
+    /** Mounts a self-bootstrapping {@link #setApp(String)} bundle by replicating its index.html body. */
+    public static final String MODE_AUTO = "auto";
+    /** Event fired when the mounted microfrontend calls the injected {@code dynamiaEmit(data)} function. */
+    public static final String ON_EVENT = "onMicrofrontendEvent";
+    /** Internal, server-only event used to coalesce bursts of {@link #mount()} calls; never sent by the client. */
+    private static final String EVT_MOUNT = "onMicrofrontendMount";
+
+    static {
+        addClientEvent(MicroFrontend.class, ON_EVENT, ComponentCtrl.CE_IMPORTANT);
+    }
 
     private String src;
+    private String css;
+    private String app;
     private String type = "module";
     private String mode = MODE_CUSTOM_ELEMENT;
     private String tag;
     private String mountFn;
     private String unmountFn;
     private final Map<String, Object> props = new LinkedHashMap<>();
+    private boolean shadow;
     private boolean composed;
+    private boolean mountScheduled;
 
     public MicroFrontend() {
         setSclass("microfrontend");
+        addEventListener(EVT_MOUNT, event -> {
+            mountScheduled = false;
+            doMount();
+        });
     }
 
     /**
@@ -103,6 +178,56 @@ public void setSrc(String src) {
         mount();
     }
 
+    public String getCss() {
+        return css;
+    }
+
+    /**
+     * Sets the stylesheet(s) to load alongside the bundle, e.g. a Vite/webpack build's separate
+     * {@code index.css} chunk. Accepts a single URL or a comma-separated list, e.g.
+     * {@code css="/bundles/app.css,/bundles/app-vendor.css"}. Loads are cached/shared client-side
+     * the same way as {@link #setSrc}.
+     *
+     * @param css stylesheet URL(s), comma-separated
+     */
+    public void setCss(String css) {
+        this.css = css;
+        mount();
+    }
+
+    public String getApp() {
+        return app;
+    }
+
+    /**
+     * Sets the root folder of a bundler production build (e.g. Vite's {@code dist/}) to
+     * auto-discover the bundle and stylesheet(s) from, instead of setting {@link #setSrc} /
+     * {@link #setCss} manually. See the class Javadoc for how discovery works and its
+     * limitations. When set, it takes precedence over {@link #src} / {@link #css}.
+     *
+     * @param app root URL of the build output, e.g. {@code /static/next/subscription}
+     */
+    public void setApp(String app) {
+        this.app = app;
+        mount();
+    }
+
+    public boolean isShadow() {
+        return shadow;
+    }
+
+    /**
+     * Sets whether to mount the bundle inside a shadow root attached to this component's
+     * container, isolating its CSS/DOM from the host page. See the class Javadoc for supported
+     * modes and limitations.
+     *
+     * @param shadow whether to use a shadow root
+     */
+    public void setShadow(boolean shadow) {
+        this.shadow = shadow;
+        mount();
+    }
+
     public String getType() {
         return type;
     }
@@ -204,33 +329,71 @@ public void addProp(String name, Object value) {
     }
 
     /**
-     * Builds the client-side configuration and instructs the browser to load (if not already
-     * cached) the bundle and mount it into this component's container element. No-op until the
-     * component is attached to a page and {@link #src} plus the mode-specific requirements
-     * ({@link #tag} or {@link #mountFn}) are set.
+     * Schedules a (re)mount, coalescing every {@link #mount()} call made within the same request
+     * into a single actual mount: MVVM binding resolves several {@code @bind}-ed properties one
+     * setter call at a time (e.g. {@code theme}, then {@code shadow}, then {@code user}), each of
+     * which would otherwise trigger its own flickering remount with a partially-updated
+     * configuration. {@link #EVT_MOUNT} is posted to the current execution (processed after the
+     * request's other handlers finish, still within the same response, no client round trip) where
+     * {@link #doMount()} runs once with the final state. No-op until the component is attached to
+     * a page and either {@link #app}, or {@link #src} plus the mode-specific requirements
+     * ({@link #tag} or {@link #mountFn}), are set.
      */
     private void mount() {
-        if (!composed || getPage() == null || src == null || !isMountable()) {
+        if (!composed || getPage() == null || (src == null && app == null) || !isMountable()) {
+            return;
+        }
+        if (mountScheduled) {
             return;
         }
+        mountScheduled = true;
+        Events.postEvent(EVT_MOUNT, this, null);
+    }
+
+    private void doMount() {
         Clients.evalJavaScript("dynamiaMountMicrofrontend('" + getUuid() + "', " + buildConfig() + ");");
     }
 
+    /**
+     * Resolves the actual mounting strategy to use, defaulting {@link #setApp(String)} without a
+     * {@link #tag}/{@link #mountFn} to {@link #MODE_AUTO} regardless of {@link #mode}'s default
+     * value, so ZUL authors don't have to set {@code mode="auto"} explicitly.
+     */
+    private String effectiveMode() {
+        if (MODE_MOUNT_FN.equals(mode) && mountFn != null) {
+            return MODE_MOUNT_FN;
+        }
+        if (tag != null) {
+            return MODE_CUSTOM_ELEMENT;
+        }
+        if (app != null) {
+            return MODE_AUTO;
+        }
+        return mode;
+    }
+
     private boolean isMountable() {
-        if (MODE_CUSTOM_ELEMENT.equals(mode)) {
-            return tag != null;
+        String effective = effectiveMode();
+        if (MODE_MOUNT_FN.equals(effective)) {
+            return mountFn != null;
+        }
+        if (MODE_AUTO.equals(effective)) {
+            return app != null;
         }
-        return mountFn != null;
+        return tag != null;
     }
 
     private String buildConfig() {
         Map<String, Object> config = new LinkedHashMap<>();
         config.put("src", src);
+        config.put("css", css);
+        config.put("app", app);
         config.put("type", type);
-        config.put("mode", mode);
+        config.put("mode", effectiveMode());
         config.put("tag", tag);
         config.put("mountFn", mountFn);
         config.put("unmountFn", unmountFn);
+        config.put("shadow", shadow);
         config.put("props", props);
         return StringPojoParser.convertMapToJson(config);
     }
diff --git a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
index 2b89707d..b4dce0d8 100644
--- a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
+++ b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
@@ -1,4 +1,4 @@
-/*
+ /*
  * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
  * Colombia / South America
  *
@@ -17,9 +17,10 @@
 
 /**
  * Registry used by the MicroFrontend ZK component (tools.dynamia.zk.ui.MicroFrontend) to cache
- * bundle loading promises across component instances sharing the same "src".
+ * bundle/stylesheet/app-discovery loading promises across component instances sharing the same
+ * "src"/"css"/"app".
  */
-var DynamiaMicrofrontends = window.DynamiaMicrofrontends || {scripts: {}};
+var DynamiaMicrofrontends = window.DynamiaMicrofrontends || {scripts: {}, styles: {}, styleTexts: {}, apps: {}};
 
 /**
  * Loads a JavaScript bundle once and caches the loading promise so multiple microfrontend
@@ -47,24 +48,236 @@ function dynamiaLoadScript(src, type) {
     return DynamiaMicrofrontends.scripts[src];
 }
 
+/**
+ * Loads a stylesheet once and caches the loading promise, the same way {@link dynamiaLoadScript}
+ * does for bundles.
+ * @param {string} href - Stylesheet URL.
+ * @returns {Promise<void>} Resolves once the stylesheet has loaded (or failed, which only logs).
+ */
+function dynamiaLoadStyle(href) {
+    if (!DynamiaMicrofrontends.styles[href]) {
+        DynamiaMicrofrontends.styles[href] = new Promise(function (resolve) {
+            var link = document.createElement('link');
+            link.rel = 'stylesheet';
+            link.href = href;
+            link.onload = function () {
+                resolve();
+            };
+            link.onerror = function () {
+                delete DynamiaMicrofrontends.styles[href];
+                console.error('Dynamia Microfrontend: failed to load stylesheet ' + href);
+                resolve();
+            };
+            document.head.appendChild(link);
+        });
+    }
+    return DynamiaMicrofrontends.styles[href];
+}
+
+/**
+ * Loads every stylesheet in a comma-separated list, e.g. a Vite/webpack build's separate CSS
+ * chunk(s) shipped alongside the JS bundle.
+ * @param {string} css - Comma-separated stylesheet URL(s), may be null/empty.
+ * @returns {Promise<void>} Resolves once every stylesheet has loaded.
+ */
+function dynamiaLoadStyles(css) {
+    if (!css) {
+        return Promise.resolve();
+    }
+    var hrefs = css.split(',').map(function (href) {
+        return href.trim();
+    }).filter(Boolean);
+    return Promise.all(hrefs.map(dynamiaLoadStyle));
+}
+
+/**
+ * Fetches a stylesheet's text once and caches the promise, so it can be inlined as a
+ * {@code <style>} into any number of shadow roots (a {@code <link>} element, unlike a fetched
+ * text, can only ever live in one place in the DOM).
+ * @param {string} href - Stylesheet URL.
+ * @returns {Promise<string>} Resolves to the stylesheet text, or "" if it failed to load (logged).
+ */
+function dynamiaFetchStyleText(href) {
+    if (!DynamiaMicrofrontends.styleTexts[href]) {
+        DynamiaMicrofrontends.styleTexts[href] = fetch(href).then(function (res) {
+            if (!res.ok) {
+                throw new Error('Dynamia Microfrontend: failed to fetch stylesheet ' + href + ' (' + res.status + ')');
+            }
+            return res.text();
+        }).catch(function (err) {
+            delete DynamiaMicrofrontends.styleTexts[href];
+            console.error(err);
+            return '';
+        });
+    }
+    return DynamiaMicrofrontends.styleTexts[href];
+}
+
+/**
+ * Loads every stylesheet in a comma-separated list as inline {@code <style>} tags appended to a
+ * shadow root, the shadow-DOM equivalent of {@link dynamiaLoadStyles}.
+ * @param {string} css - Comma-separated stylesheet URL(s), may be null/empty.
+ * @param {ShadowRoot} root - Shadow root to append the resulting <style> tags to.
+ * @returns {Promise<void>} Resolves once every stylesheet has been inlined.
+ */
+function dynamiaLoadStylesIntoShadow(css, root) {
+    if (!css) {
+        return Promise.resolve();
+    }
+    var hrefs = css.split(',').map(function (href) {
+        return href.trim();
+    }).filter(Boolean);
+    return Promise.all(hrefs.map(dynamiaFetchStyleText)).then(function (texts) {
+        texts.forEach(function (text) {
+            if (text) {
+                var style = document.createElement('style');
+                style.textContent = text;
+                root.appendChild(style);
+            }
+        });
+    });
+}
+
+/**
+ * Resolves a URL found in a build's index.html against its app root: absolute (starting with "/"
+ * or a scheme) URLs are used as-is, relative ones (e.g. "assets/x.js" or "./assets/x.js") are
+ * joined to the app root, matching how the browser itself would resolve them relative to that
+ * index.html.
+ * @param {string} appRoot - App root URL, e.g. "/static/next/subscription" (no trailing slash).
+ * @param {string} url - URL found in the index.html.
+ * @returns {string} Resolved absolute-path URL.
+ */
+function dynamiaResolveAppUrl(appRoot, url) {
+    if (/^([a-z]+:)?\//i.test(url)) {
+        return url;
+    }
+    return appRoot + '/' + url.replace(/^\.\//, '');
+}
+
+/**
+ * Auto-discovers the bundle, stylesheet(s) and self-mount target of a bundler production build
+ * (e.g. Vite's {@code dist/}) by fetching its {@code index.html} and extracting the entry
+ * {@code <script type="module">}, {@code <link rel="stylesheet">} tags, and {@code <body>} markup
+ * (stripped of any {@code <script>} tags) it contains, so hashed output filenames never need to be
+ * hardcoded and self-mounting bundles (e.g. {@code createApp(App).mount('#app')}) find their
+ * target. Only verified against Vite output.
+ * @param {string} appRoot - App root URL, e.g. "/static/next/subscription".
+ * @returns {Promise<{src: string, css: string, bodyHtml: string}>} Discovered bundle/stylesheet URLs and body markup.
+ */
+function dynamiaResolveApp(appRoot) {
+    if (!DynamiaMicrofrontends.apps[appRoot]) {
+        var base = appRoot.replace(/\/$/, '');
+        DynamiaMicrofrontends.apps[appRoot] = fetch(base + '/index.html').then(function (res) {
+            if (!res.ok) {
+                throw new Error('Dynamia Microfrontend: failed to fetch ' + base + '/index.html (' + res.status + ')');
+            }
+            return res.text();
+        }).then(function (html) {
+            var scriptTag = (html.match(/<script[^>]*type=["']module["'][^>]*>/i) || [])[0];
+            var src = scriptTag && (scriptTag.match(/\ssrc=["']([^"']+)["']/i) || [])[1];
+            if (!src) {
+                throw new Error('Dynamia Microfrontend: no <script type="module" src="..."> found in ' + base + '/index.html');
+            }
+            var css = (html.match(/<link[^>]*rel=["']stylesheet["'][^>]*>/gi) || [])
+                .map(function (tag) {
+                    return (tag.match(/\shref=["']([^"']+)["']/i) || [])[1];
+                })
+                .filter(Boolean)
+                .map(function (href) {
+                    return dynamiaResolveAppUrl(base, href);
+                })
+                .join(',');
+            var bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+            var bodyHtml = bodyMatch ? bodyMatch[1].replace(/<script[\s\S]*?<\/script>/gi, '') : '';
+            return {src: dynamiaResolveAppUrl(base, src), css: css, bodyHtml: bodyHtml};
+        }).catch(function (err) {
+            delete DynamiaMicrofrontends.apps[appRoot];
+            throw err;
+        });
+    }
+    return DynamiaMicrofrontends.apps[appRoot];
+}
+
 /**
  * Loads (if needed) and mounts a microfrontend bundle into the container element of a
- * MicroFrontend ZK component.
+ * MicroFrontend ZK component. Injects a {@code dynamiaEmit(data)} function into the mounted
+ * bundle's props so it can notify the server-side ZK component, which fires "onMicrofrontendEvent"
+ * (bindable in MVVM with {@code onMicrofrontendEvent="@command(...)"}). In "auto" mode the bundle
+ * self-mounts, so its discovered index.html body markup is placed into the container before the
+ * bundle loads, and nothing further is done once it loads. Auto mode only supports one live
+ * instance of a given "app" per page at a time (its bundle runs once and self-mounts via a
+ * hardcoded id from its own index.html): remounting the same container (e.g. a ZK MVVM prop
+ * change, or the page redrawing the same component) is allowed, but a genuinely different,
+ * still-live container for the same app is refused with a console error instead of silently
+ * rendering nothing. With {@code config.shadow}, "custom-element"/"mount-fn" mount inside
+ * a shadow root attached to the container (its stylesheet(s) inlined into that root instead of
+ * document head) for CSS/DOM isolation from the host page; "auto" cannot be combined with shadow
+ * since its bundle looks up its mount target with a page-level document.getElementById() call.
  * @param {string} containerId - Id of the component's container element (its ZK uuid).
- * @param {object} config - {src, type, mode, tag, mountFn, unmountFn, props}.
+ * @param {object} config - {src, css, app, type, mode, tag, mountFn, unmountFn, shadow, props}.
  */
 function dynamiaMountMicrofrontend(containerId, config) {
-    dynamiaLoadScript(config.src, config.type).then(function () {
+    if (config.mode === 'auto') {
+        if (config.shadow) {
+            console.error('Dynamia Microfrontend: shadow=true is not supported with "auto" mode — the bundle finds ' +
+                'its mount target via a page-level document.getElementById() call it makes itself, which cannot see ' +
+                'inside a shadow root. Use tag= (custom element) or mountFn=/unmountFn= instead.');
+            return;
+        }
+        DynamiaMicrofrontends.autoMounted = DynamiaMicrofrontends.autoMounted || {};
+        var owner = DynamiaMicrofrontends.autoMounted[config.app];
+        if (owner && owner !== containerId && document.getElementById(owner)) {
+            console.error('Dynamia Microfrontend: "' + config.app + '" is already auto-mounted on this page. ' +
+                'Auto mode self-mounts via a hardcoded id from the bundle\'s own index.html and its script ' +
+                'only runs once, so it cannot support a second simultaneous instance of the same app. ' +
+                'Rebuild it as a custom element (use tag=) or expose mount/unmount functions ' +
+                '(mountFn=/unmountFn=) if you need more than one instance.');
+            return;
+        }
+        DynamiaMicrofrontends.autoMounted[config.app] = containerId;
+    }
+    var resolved = config.app ? dynamiaResolveApp(config.app) : Promise.resolve({src: config.src, css: config.css, bodyHtml: ''});
+    resolved.then(function (bundle) {
         var container = document.getElementById(containerId);
         if (!container) {
+            return null;
+        }
+        if (config.mode === 'auto') {
+            container.innerHTML = bundle.bodyHtml || '';
+            return Promise.all([dynamiaLoadScript(bundle.src, config.type), dynamiaLoadStyles(bundle.css)]).then(function () {
+                return null;
+            });
+        }
+        var root = container;
+        var cssPromise;
+        if (config.shadow) {
+            root = container.shadowRoot || container.attachShadow({mode: 'open'});
+            cssPromise = dynamiaLoadStylesIntoShadow(bundle.css, root);
+        } else {
+            cssPromise = dynamiaLoadStyles(bundle.css);
+        }
+        root.innerHTML = '';
+        var mountTarget = root;
+        if (config.shadow) {
+            mountTarget = document.createElement('div');
+            root.appendChild(mountTarget);
+        }
+        return Promise.all([dynamiaLoadScript(bundle.src, config.type), cssPromise]).then(function () {
+            return {root: root, mountTarget: mountTarget};
+        });
+    }).then(function (result) {
+        if (!result) {
             return;
         }
+        var root = result.root, mountTarget = result.mountTarget;
         var props = config.props || {};
-        container.innerHTML = '';
+        props.dynamiaEmit = function (data) {
+            zAu.send(new zk.Event(zk.Widget.$(containerId), 'onMicrofrontendEvent', data));
+        };
         if (config.mode === 'mount-fn') {
             var mountFn = window[config.mountFn];
             if (typeof mountFn === 'function') {
-                mountFn(container, props);
+                mountFn(mountTarget, props);
             } else {
                 console.error('Dynamia Microfrontend: mount function "' + config.mountFn + '" not found on window');
             }
@@ -73,9 +286,11 @@ function dynamiaMountMicrofrontend(containerId, config) {
             Object.keys(props).forEach(function (key) {
                 var value = props[key];
                 el[key] = value;
-                el.setAttribute(key, typeof value === 'object' ? JSON.stringify(value) : value);
+                if (typeof value !== 'function') {
+                    el.setAttribute(key, typeof value === 'object' ? JSON.stringify(value) : value);
+                }
             });
-            container.appendChild(el);
+            root.appendChild(el);
         }
     }).catch(function (err) {
         console.error(err);
@@ -85,9 +300,11 @@ function dynamiaMountMicrofrontend(containerId, config) {
 /**
  * Unmounts a microfrontend previously mounted with {@link dynamiaMountMicrofrontend} in
  * "mount-fn" mode. Components using "custom-element" mode are cleaned up automatically by the
- * browser when their DOM node is removed (disconnectedCallback), so this is a no-op for them.
+ * browser when their DOM node is removed (disconnectedCallback), so this is a no-op for them. With
+ * {@code config.shadow}, passes the same shadow-root-scoped <div> that was originally passed to
+ * mountFn, not the container itself.
  * @param {string} containerId - Id of the component's container element (its ZK uuid).
- * @param {object} config - {mode, unmountFn}.
+ * @param {object} config - {mode, unmountFn, shadow}.
  */
 function dynamiaUnmountMicrofrontend(containerId, config) {
     if (config.mode !== 'mount-fn' || !config.unmountFn) {
@@ -97,10 +314,14 @@ function dynamiaUnmountMicrofrontend(containerId, config) {
     if (!container) {
         return;
     }
+    var target = container;
+    if (config.shadow && container.shadowRoot) {
+        target = container.shadowRoot.firstElementChild || container.shadowRoot;
+    }
     var unmountFn = window[config.unmountFn];
     if (typeof unmountFn === 'function') {
         try {
-            unmountFn(container);
+            unmountFn(target);
         } catch (err) {
             console.error(err);
         }

From 381d05a1fc8917d1cd718c890431a597921eda30 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 16:25:39 -0500
Subject: [PATCH 6/9] feat(microfrontend): update mounted instance in place
 instead of destroying and recreating it

MVVM binding resolves each @bind-ed property with its own setter call, and every one of
them triggered a full unmount+remount, wiping any state the mounted app held (e.g. a
form the user is filling in). When only props change and the bundle/tag/mountFn/shadow
stay the same, custom-element mode now just reassigns the existing element's properties,
and mount-fn mode calls an optional updateFn(container, props) hook (single-spa-style)
instead of a full teardown; without updateFn it still falls back to unmount+remount.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../resources/pages/microfrontend-demo.zul    | 13 ++-
 .../resources/static/js/microfrontend-demo.js | 19 ++++-
 .../tools/dynamia/zk/ui/MicroFrontend.java    | 34 +++++++-
 .../dynamia-tools/js/zk/dynamia-tools.js      | 79 +++++++++++++++++--
 4 files changed, 131 insertions(+), 14 deletions(-)

diff --git a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
index 85902797..468d2f39 100644
--- a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
+++ b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
@@ -10,6 +10,10 @@
         void handleMicrofrontendEvent(org.zkoss.zk.ui.event.Event event) {
             Clients.showNotification("onMicrofrontendEvent: " + event.getData());
         }
+
+        void randomizeMountFnUserId() {
+            mountFnDemo.addProp("userId", (int) (Math.random() * 1000));
+        }
     ]]></zscript>
 
     <div hflex="1" vflex="1">
@@ -23,10 +27,11 @@
                                onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
             </groupbox>
             <groupbox width="50%">
-                <caption label="mount-fn mode, shadow DOM isolated"/>
-                <microfrontend src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
-                               mode="mount-fn" mountFn="mountDemoApp" unmountFn="unmountDemoApp" userId="99"
-                               shadow="true" onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
+                <caption label="mount-fn mode, shadow DOM isolated, update in place"/>
+                <microfrontend id="mountFnDemo" src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
+                               mode="mount-fn" mountFn="mountDemoApp" unmountFn="unmountDemoApp" updateFn="updateDemoApp"
+                               userId="99" shadow="true" onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
+                <button label="Change userId (updates in place, no remount)" onClick="randomizeMountFnUserId()"/>
             </groupbox>
             <groupbox width="50%">
                 <caption label="app auto-discovery mode, self-mounting (no tag/mountFn)"/>
diff --git a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
index 8f80f551..26c2126a 100644
--- a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
+++ b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
@@ -42,19 +42,36 @@
         customElements.define('demo-widget', DemoWidget);
     }
 
-    window.mountDemoApp = function (container, props) {
+    function renderMountDemoApp(container, props) {
         container.innerHTML =
             '<div style="padding:1rem;border:2px solid #00b894;border-radius:8px">' +
             '<strong>mount-fn mode</strong><br/>userId: ' + props.userId + '<br/>' +
+            'in-place updates: ' + (container._dynamiaUpdateCount || 0) + '<br/>' +
             '<button id="emit" class="demo-widget-emit-btn">emit event to server</button></div>';
         container.querySelector('#emit').addEventListener('click', function () {
             if (typeof props.dynamiaEmit === 'function') {
                 props.dynamiaEmit({from: 'mount-fn', userId: props.userId});
             }
         });
+    }
+
+    window.mountDemoApp = function (container, props) {
+        container._dynamiaUpdateCount = 0;
+        renderMountDemoApp(container, props);
         console.log('[demo-app] mounted via mount-fn', props);
     };
 
+    /**
+     * Optional single-spa-style "update" hook (MicroFrontend's updateFn=): called instead of
+     * unmount+mount when only props changed, so the bundle can preserve its own state. Here we
+     * just bump a counter on the container to prove in the UI/console that no full remount happened.
+     */
+    window.updateDemoApp = function (container, props) {
+        container._dynamiaUpdateCount = (container._dynamiaUpdateCount || 0) + 1;
+        renderMountDemoApp(container, props);
+        console.log('[demo-app] updated in place via updateFn (#' + container._dynamiaUpdateCount + ')', props);
+    };
+
     window.unmountDemoApp = function (container) {
         container.innerHTML = '';
         console.log('[demo-app] unmounted via mount-fn');
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
index 1569db7d..e9a1a208 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
@@ -45,7 +45,10 @@
  *     element's own {@code connectedCallback}/{@code disconnectedCallback}.</li>
  *     <li>{@link #MODE_MOUNT_FN}: the bundle exposes global mount/unmount functions (a convention
  *     similar to single-spa), invoked explicitly as {@code window[mountFn](container, props)} and
- *     {@code window[unmountFn](container)} when this component is rendered and detached.</li>
+ *     {@code window[unmountFn](container)} when this component is rendered and detached. If the
+ *     bundle also exposes {@link #setUpdateFn}, prop-only changes call
+ *     {@code window[updateFn](container, props)} instead of unmounting/remounting, so the bundle
+ *     can preserve its internal state (e.g. an in-progress form) across a reactive prop update.</li>
  *     <li>{@link #MODE_AUTO}: for a bundle that self-mounts into a hardcoded selector at import
  *     time, as a default {@code vite build} of an app (not a custom-element library) does, e.g.
  *     {@code createApp(App).mount('#app')}. Selected automatically when {@link #setApp(String)} is
@@ -68,6 +71,16 @@
  * Any extra ZUL attribute not matching a bean property (via {@link DynamicPropertied}) is
  * forwarded as a prop to the mounted microfrontend, e.g. {@code userId="${user.id}"}.
  * <p>
+ * When only {@link #setProps}/dynamic props change and everything else ({@link #src}/{@link #app},
+ * {@link #tag}/{@link #mountFn}, {@link #isShadow}) stays the same, the client updates the already
+ * mounted instance in place instead of destroying and recreating it — important once props are
+ * driven by MVVM (each {@code @bind}-ed property change would otherwise wipe any state the mounted
+ * app holds, e.g. a form the user is filling in). For {@link #MODE_CUSTOM_ELEMENT} this just
+ * reassigns the element's properties (the browser/framework's own reactivity takes it from there);
+ * for {@link #MODE_MOUNT_FN} it calls {@link #setUpdateFn} if provided, otherwise it falls back to
+ * a full unmount+remount. Any actual change to {@code src}/{@code app}/{@code tag}/{@code mountFn}/
+ * {@code shadow} still tears down the previous instance and mounts fresh.
+ * <p>
  * {@link #setShadow(boolean)} mounts the bundle inside a
  * <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM">shadow
  * root</a> attached to this component's container, isolating its CSS/DOM from the host ZK page in
@@ -137,6 +150,7 @@ public class MicroFrontend extends Div implements DynamicPropertied, AfterCompos
     private String tag;
     private String mountFn;
     private String unmountFn;
+    private String updateFn;
     private final Map<String, Object> props = new LinkedHashMap<>();
     private boolean shadow;
     private boolean composed;
@@ -300,6 +314,23 @@ public void setUnmountFn(String unmountFn) {
         this.unmountFn = unmountFn;
     }
 
+    public String getUpdateFn() {
+        return updateFn;
+    }
+
+    /**
+     * Sets the name of an optional global function used to update an already-mounted
+     * {@link #MODE_MOUNT_FN} instance in place when only props change, instead of a full
+     * unmount+remount. Invoked as {@code window[updateFn](container, props)}. If not set, prop-only
+     * changes fall back to unmount+remount.
+     *
+     * @param updateFn global update function name
+     */
+    public void setUpdateFn(String updateFn) {
+        this.updateFn = updateFn;
+        mount();
+    }
+
     public Map<String, Object> getProps() {
         return props;
     }
@@ -393,6 +424,7 @@ private String buildConfig() {
         config.put("tag", tag);
         config.put("mountFn", mountFn);
         config.put("unmountFn", unmountFn);
+        config.put("updateFn", updateFn);
         config.put("shadow", shadow);
         config.put("props", props);
         return StringPojoParser.convertMapToJson(config);
diff --git a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
index b4dce0d8..e9307dcc 100644
--- a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
+++ b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
@@ -213,8 +213,16 @@ function dynamiaResolveApp(appRoot) {
  * a shadow root attached to the container (its stylesheet(s) inlined into that root instead of
  * document head) for CSS/DOM isolation from the host page; "auto" cannot be combined with shadow
  * since its bundle looks up its mount target with a page-level document.getElementById() call.
+ *
+ * When a previous instance is already mounted in this container with the same shape (mode, resolved
+ * bundle src, tag/mountFn, shadow), only props changed: the existing instance is updated in place
+ * instead of destroyed and recreated (important once props are MVVM-bound, since every single
+ * @bind-ed property change would otherwise wipe any state the mounted app holds). "custom-element"
+ * just reassigns the existing element's properties; "mount-fn" calls "updateFn" if configured,
+ * otherwise it tears the old instance down (via unmountFn) and mounts fresh, same as any other
+ * structural change (src/app/tag/mountFn/shadow actually changing).
  * @param {string} containerId - Id of the component's container element (its ZK uuid).
- * @param {object} config - {src, css, app, type, mode, tag, mountFn, unmountFn, shadow, props}.
+ * @param {object} config - {src, css, app, type, mode, tag, mountFn, unmountFn, updateFn, shadow, props}.
  */
 function dynamiaMountMicrofrontend(containerId, config) {
     if (config.mode === 'auto') {
@@ -236,6 +244,7 @@ function dynamiaMountMicrofrontend(containerId, config) {
         }
         DynamiaMicrofrontends.autoMounted[config.app] = containerId;
     }
+    DynamiaMicrofrontends.instances = DynamiaMicrofrontends.instances || {};
     var resolved = config.app ? dynamiaResolveApp(config.app) : Promise.resolve({src: config.src, css: config.css, bodyHtml: ''});
     resolved.then(function (bundle) {
         var container = document.getElementById(containerId);
@@ -248,6 +257,28 @@ function dynamiaMountMicrofrontend(containerId, config) {
                 return null;
             });
         }
+
+        var prev = DynamiaMicrofrontends.instances[containerId];
+        var canUpdateInPlace = prev && prev.mode === config.mode && prev.src === bundle.src &&
+            prev.shadow === !!config.shadow &&
+            (config.mode === 'mount-fn'
+                ? prev.mountFn === config.mountFn && !!config.updateFn
+                : prev.tag === config.tag);
+        if (canUpdateInPlace) {
+            return {update: true, prev: prev};
+        }
+
+        if (prev && prev.mode === 'mount-fn' && prev.unmountFn) {
+            var oldUnmount = window[prev.unmountFn];
+            if (typeof oldUnmount === 'function') {
+                try {
+                    oldUnmount(prev.mountTarget);
+                } catch (err) {
+                    console.error(err);
+                }
+            }
+        }
+
         var root = container;
         var cssPromise;
         if (config.shadow) {
@@ -263,17 +294,44 @@ function dynamiaMountMicrofrontend(containerId, config) {
             root.appendChild(mountTarget);
         }
         return Promise.all([dynamiaLoadScript(bundle.src, config.type), cssPromise]).then(function () {
-            return {root: root, mountTarget: mountTarget};
+            return {update: false, root: root, mountTarget: mountTarget, src: bundle.src};
         });
     }).then(function (result) {
         if (!result) {
             return;
         }
-        var root = result.root, mountTarget = result.mountTarget;
         var props = config.props || {};
         props.dynamiaEmit = function (data) {
             zAu.send(new zk.Event(zk.Widget.$(containerId), 'onMicrofrontendEvent', data));
         };
+
+        if (result.update) {
+            var prev = result.prev;
+            if (config.mode === 'mount-fn') {
+                var updateFn = window[config.updateFn];
+                if (typeof updateFn === 'function') {
+                    updateFn(prev.mountTarget, props);
+                } else {
+                    console.error('Dynamia Microfrontend: update function "' + config.updateFn + '" not found on window');
+                }
+            } else {
+                Object.keys(props).forEach(function (key) {
+                    var value = props[key];
+                    prev.el[key] = value;
+                    if (typeof value !== 'function') {
+                        prev.el.setAttribute(key, typeof value === 'object' ? JSON.stringify(value) : value);
+                    }
+                });
+            }
+            prev.unmountFn = config.unmountFn;
+            return;
+        }
+
+        var root = result.root, mountTarget = result.mountTarget;
+        var instance = {
+            mode: config.mode, src: result.src, tag: config.tag, mountFn: config.mountFn,
+            unmountFn: config.unmountFn, shadow: !!config.shadow, root: root, mountTarget: mountTarget
+        };
         if (config.mode === 'mount-fn') {
             var mountFn = window[config.mountFn];
             if (typeof mountFn === 'function') {
@@ -291,22 +349,27 @@ function dynamiaMountMicrofrontend(containerId, config) {
                 }
             });
             root.appendChild(el);
+            instance.el = el;
         }
+        DynamiaMicrofrontends.instances[containerId] = instance;
     }).catch(function (err) {
         console.error(err);
     });
 }
 
 /**
- * Unmounts a microfrontend previously mounted with {@link dynamiaMountMicrofrontend} in
- * "mount-fn" mode. Components using "custom-element" mode are cleaned up automatically by the
- * browser when their DOM node is removed (disconnectedCallback), so this is a no-op for them. With
- * {@code config.shadow}, passes the same shadow-root-scoped <div> that was originally passed to
- * mountFn, not the container itself.
+ * Unmounts a microfrontend previously mounted with {@link dynamiaMountMicrofrontend} and clears its
+ * update-in-place tracking. In "mount-fn" mode it calls "unmountFn" explicitly. Components using
+ * "custom-element" mode are cleaned up automatically by the browser when their DOM node is removed
+ * (disconnectedCallback). With {@code config.shadow}, passes the same shadow-root-scoped <div> that
+ * was originally passed to mountFn, not the container itself.
  * @param {string} containerId - Id of the component's container element (its ZK uuid).
  * @param {object} config - {mode, unmountFn, shadow}.
  */
 function dynamiaUnmountMicrofrontend(containerId, config) {
+    if (DynamiaMicrofrontends.instances) {
+        delete DynamiaMicrofrontends.instances[containerId];
+    }
     if (config.mode !== 'mount-fn' || !config.unmountFn) {
         return;
     }

From d95ad8672ad140d8752132651f1e93e61860ce88 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 16:28:35 -0500
Subject: [PATCH 7/9] feat(microfrontend): inject registered host-context
 providers as a dynamiaHost prop

Every microfrontend needs the same cross-cutting values (tenant, locale, current user,
API base URL, auth token...), and today each ZUL author has to wire them by hand as
regular props. MicroFrontendHostContextProvider lets app code register one or more
Spring beans that get merged and injected as a "dynamiaHost" prop on every mount
(except MODE_AUTO, which has no prop channel at all), resolved entirely server-side
via Containers.findObjects() with no client-side changes needed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../providers/DemoHostContextProvider.java    | 24 +++++++
 .../resources/static/js/microfrontend-demo.js | 12 +++-
 .../tools/dynamia/zk/ui/MicroFrontend.java    | 32 +++++++++-
 .../ui/MicroFrontendHostContextProvider.java  | 64 +++++++++++++++++++
 4 files changed, 129 insertions(+), 3 deletions(-)
 create mode 100644 examples/demo-zk-books/src/main/java/mybookstore/providers/DemoHostContextProvider.java
 create mode 100644 platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontendHostContextProvider.java

diff --git a/examples/demo-zk-books/src/main/java/mybookstore/providers/DemoHostContextProvider.java b/examples/demo-zk-books/src/main/java/mybookstore/providers/DemoHostContextProvider.java
new file mode 100644
index 00000000..b8280347
--- /dev/null
+++ b/examples/demo-zk-books/src/main/java/mybookstore/providers/DemoHostContextProvider.java
@@ -0,0 +1,24 @@
+package mybookstore.providers;
+
+import tools.dynamia.integration.sterotypes.Component;
+import tools.dynamia.zk.ui.MicroFrontendHostContextProvider;
+
+import java.util.Map;
+
+/**
+ * Demonstrates tools.dynamia.zk.ui.MicroFrontendHostContextProvider: every value returned here
+ * reaches every mounted microfrontend on this app automatically as the "dynamiaHost" prop, without
+ * any ZUL author having to bind it by hand. See microfrontend-demo.zul.
+ */
+@Component
+public class DemoHostContextProvider implements MicroFrontendHostContextProvider {
+
+    @Override
+    public Map<String, Object> getHostContext() {
+        return Map.of(
+                "tenantId", "demo-bookstore",
+                "locale", "es_CO",
+                "apiBaseUrl", "/api"
+        );
+    }
+}
diff --git a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
index 26c2126a..518201fc 100644
--- a/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
+++ b/examples/demo-zk-books/src/main/resources/static/js/microfrontend-demo.js
@@ -5,17 +5,23 @@
 (function () {
     class DemoWidget extends HTMLElement {
         connectedCallback() {
-            console.log('[demo-widget] connectedCallback', {userId: this.userId, theme: this.theme, user: this.user});
+            console.log('[demo-widget] connectedCallback', {
+                userId: this.userId, theme: this.theme, user: this.user, dynamiaHost: this.dynamiaHost
+            });
             var userLine = '';
             if (this.user && typeof this.user === 'object') {
                 userLine = 'user: ' + JSON.stringify(this.user) + ' (typeof ' + typeof this.user + ')<br/>';
             }
+            var hostLine = '';
+            if (this.dynamiaHost && typeof this.dynamiaHost === 'object') {
+                hostLine = 'dynamiaHost: ' + JSON.stringify(this.dynamiaHost) + '<br/>';
+            }
             this.innerHTML =
                 '<div style="padding:1rem;border:2px dashed #6c5ce7;border-radius:8px">' +
                 '<strong>custom-element mode</strong><br/>' +
                 'userId: ' + this.userId + '<br/>' +
                 'theme: ' + this.theme + '<br/>' +
-                userLine +
+                userLine + hostLine +
                 '<button id="inc">clicks: 0</button><br/>' +
                 '<button id="emit" class="demo-widget-emit-btn">emit event to server</button>' +
                 '</div>';
@@ -43,9 +49,11 @@
     }
 
     function renderMountDemoApp(container, props) {
+        var hostLine = props.dynamiaHost ? ('dynamiaHost: ' + JSON.stringify(props.dynamiaHost) + '<br/>') : '';
         container.innerHTML =
             '<div style="padding:1rem;border:2px solid #00b894;border-radius:8px">' +
             '<strong>mount-fn mode</strong><br/>userId: ' + props.userId + '<br/>' +
+            hostLine +
             'in-place updates: ' + (container._dynamiaUpdateCount || 0) + '<br/>' +
             '<button id="emit" class="demo-widget-emit-btn">emit event to server</button></div>';
         container.querySelector('#emit').addEventListener('click', function () {
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
index e9a1a208..31b9ad68 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
@@ -25,6 +25,7 @@
 import org.zkoss.zk.ui.util.Clients;
 import org.zkoss.zul.Div;
 import tools.dynamia.commons.StringPojoParser;
+import tools.dynamia.integration.Containers;
 
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -109,6 +110,11 @@
  * direction, the mounted microfrontend can call the {@code dynamiaEmit(data)} function injected
  * into its props to notify the server, which fires {@value #ON_EVENT} and can be bound with
  * {@code onMicrofrontendEvent="@command('handleIt', data=event.data)"}.
+ * <p>
+ * Every registered {@link MicroFrontendHostContextProvider} bean is automatically merged into a
+ * {@code dynamiaHost} prop on every mount (except {@link #MODE_AUTO}), so cross-cutting values
+ * (tenant, locale, current user, API base URL, auth token) reach every microfrontend without each
+ * ZUL author wiring them by hand.
  *
  * Example:
  * <pre>{@code
@@ -426,10 +432,34 @@ private String buildConfig() {
         config.put("unmountFn", unmountFn);
         config.put("updateFn", updateFn);
         config.put("shadow", shadow);
-        config.put("props", props);
+        config.put("props", resolveProps());
         return StringPojoParser.convertMapToJson(config);
     }
 
+    /**
+     * Merges every registered {@link MicroFrontendHostContextProvider}'s context into a
+     * {@code dynamiaHost} entry alongside the regular props, without mutating {@link #props}
+     * itself. Skipped for {@link #MODE_AUTO}, which has no prop channel to the bundle at all.
+     */
+    private Map<String, Object> resolveProps() {
+        if (MODE_AUTO.equals(effectiveMode())) {
+            return props;
+        }
+        Map<String, Object> host = new LinkedHashMap<>();
+        for (MicroFrontendHostContextProvider provider : Containers.get().findObjects(MicroFrontendHostContextProvider.class)) {
+            Map<String, Object> context = provider.getHostContext();
+            if (context != null) {
+                host.putAll(context);
+            }
+        }
+        if (host.isEmpty()) {
+            return props;
+        }
+        Map<String, Object> merged = new LinkedHashMap<>(props);
+        merged.put("dynamiaHost", host);
+        return merged;
+    }
+
     /**
      * Unmounts the microfrontend client-side when this component leaves the page, preventing
      * memory leaks from mounted framework instances (Vue apps, React roots, subscriptions, etc.)
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontendHostContextProvider.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontendHostContextProvider.java
new file mode 100644
index 00000000..3659f987
--- /dev/null
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontendHostContextProvider.java
@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.zk.ui;
+
+import java.util.Map;
+
+/**
+ * Supplies cross-cutting context values (tenant id, locale, current user, API base URL, auth
+ * token, feature flags, etc.) that every {@link MicroFrontend} instance on the page automatically
+ * receives, so ZUL authors don't have to wire the same values by hand on every
+ * {@code <microfrontend>} tag.
+ * <p>
+ * Register an implementation as a Spring bean (e.g. annotate it with
+ * {@code tools.dynamia.integration.sterotypes.Component}); every registered provider found via
+ * {@link tools.dynamia.integration.Containers#findObjects(Class)} is called and merged (later
+ * providers overriding earlier ones on key collisions) into the {@code dynamiaHost} prop of every
+ * mounted microfrontend. The mounted bundle reads it like any other prop, e.g. {@code this.dynamiaHost}
+ * in a custom element, or {@code props.dynamiaHost} in a mount-fn.
+ * <p>
+ * Not delivered when {@link MicroFrontend#getMode()} resolves to {@link MicroFrontend#MODE_AUTO}:
+ * that mode has no prop channel at all, since the bundle self-mounts independently.
+ *
+ * Example:
+ * <pre>{@code
+ * @Component
+ * public class TenantHostContextProvider implements MicroFrontendHostContextProvider {
+ *     @Override
+ *     public Map<String, Object> getHostContext() {
+ *         Account account = AccountServiceAPI.getCurrentAccount();
+ *         return Map.of(
+ *             "tenantId", account.getId(),
+ *             "locale", LocaleUtils.getCurrentLocale().toLanguageTag(),
+ *             "apiBaseUrl", "/api"
+ *         );
+ *     }
+ * }
+ * }</pre>
+ *
+ * @author Mario A. Serrano Leones
+ */
+public interface MicroFrontendHostContextProvider {
+
+    /**
+     * Returns context values to merge into the {@code dynamiaHost} prop of every mounted
+     * microfrontend.
+     *
+     * @return context values, must be JSON-serializable; null is treated as empty
+     */
+    Map<String, Object> getHostContext();
+}

From 9477215a5cb95ec208d301ce43b491588076fa0a Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 16:32:27 -0500
Subject: [PATCH 8/9] feat(microfrontend): fire
 onMicrofrontendReady/onMicrofrontendError lifecycle events

Loading/mounting failures (404 on the bundle or its stylesheet, a missing index.html
in "auto" mode, an undeclared mountFn/updateFn, an exception from the bundle itself)
previously only reached the browser console, with no way for the ZUL page to react
(loading indicator, retry button, fallback message). onMicrofrontendReady now fires
once a (re)mount/update succeeds and onMicrofrontendError fires with a {message} data
payload whenever it doesn't, both bindable with @command(...) like onMicrofrontendEvent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../resources/pages/microfrontend-demo.zul    | 23 ++++++++-
 .../tools/dynamia/zk/ui/MicroFrontend.java    | 16 ++++++-
 .../dynamia-tools/js/zk/dynamia-tools.js      | 48 +++++++++++++++----
 3 files changed, 76 insertions(+), 11 deletions(-)

diff --git a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
index 468d2f39..196f0f95 100644
--- a/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
+++ b/examples/demo-zk-books/src/main/resources/pages/microfrontend-demo.zul
@@ -11,9 +11,21 @@
             Clients.showNotification("onMicrofrontendEvent: " + event.getData());
         }
 
+        void handleMicrofrontendReady(org.zkoss.zk.ui.event.Event event) {
+            System.out.println("[MicroFrontend] onMicrofrontendReady: " + event.getTarget());
+        }
+
+        void handleMicrofrontendError(org.zkoss.zk.ui.event.Event event) {
+            Clients.showNotification("onMicrofrontendError: " + event.getData(), "error", null, "top_center", 4000);
+        }
+
         void randomizeMountFnUserId() {
             mountFnDemo.addProp("userId", (int) (Math.random() * 1000));
         }
+
+        void breakBundle() {
+            brokenDemo.setSrc("/static/js/does-not-exist.js");
+        }
     ]]></zscript>
 
     <div hflex="1" vflex="1">
@@ -21,10 +33,11 @@
 
         <div id="wrapper" hflex="1">
             <groupbox width="50%">
-                <caption label="custom-element mode"/>
+                <caption label="custom-element mode (see server console for onMicrofrontendReady)"/>
                 <microfrontend src="/static/js/microfrontend-demo.js" css="/static/css/microfrontend-demo.css"
                                tag="demo-widget" mode="custom-element" userId="42" theme="dark"
-                               onMicrofrontendEvent="handleMicrofrontendEvent(event)"/>
+                               onMicrofrontendEvent="handleMicrofrontendEvent(event)"
+                               onMicrofrontendReady="handleMicrofrontendReady(event)"/>
             </groupbox>
             <groupbox width="50%">
                 <caption label="mount-fn mode, shadow DOM isolated, update in place"/>
@@ -50,6 +63,12 @@
                 </hbox>
                 <label value="@load(vm.lastEvent)"/>
             </groupbox>
+            <groupbox width="50%">
+                <caption label="onMicrofrontendError demo"/>
+                <microfrontend id="brokenDemo" src="/static/js/microfrontend-demo.js" tag="demo-widget"
+                               onMicrofrontendError="handleMicrofrontendError(event)"/>
+                <button label="Point src at a missing file (fires onMicrofrontendError)" onClick="breakBundle()"/>
+            </groupbox>
         </div>
 
         <button label="Detach wrapper (verify unmount in console)" onClick="toggle()"/>
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
index 31b9ad68..eb568c3a 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/ui/MicroFrontend.java
@@ -109,7 +109,10 @@
  * {@code src="@bind(vm.bundleUrl)"} or {@code userId="@bind(vm.userId)"}. For the reverse
  * direction, the mounted microfrontend can call the {@code dynamiaEmit(data)} function injected
  * into its props to notify the server, which fires {@value #ON_EVENT} and can be bound with
- * {@code onMicrofrontendEvent="@command('handleIt', data=event.data)"}.
+ * {@code onMicrofrontendEvent="@command('handleIt', data=event.data)"}. {@value #ON_READY} fires
+ * once the bundle has (re)mounted successfully (e.g. to hide a loading indicator), and
+ * {@value #ON_ERROR} fires if loading/mounting fails for any reason (e.g. to show a retry button),
+ * with {@code event.getData()} a {@code Map} containing a {@code message} entry.
  * <p>
  * Every registered {@link MicroFrontendHostContextProvider} bean is automatically merged into a
  * {@code dynamiaHost} prop on every mount (except {@link #MODE_AUTO}), so cross-cutting values
@@ -141,11 +144,22 @@ public class MicroFrontend extends Div implements DynamicPropertied, AfterCompos
     public static final String MODE_AUTO = "auto";
     /** Event fired when the mounted microfrontend calls the injected {@code dynamiaEmit(data)} function. */
     public static final String ON_EVENT = "onMicrofrontendEvent";
+    /** Event fired once the bundle/stylesheet(s) have loaded and the microfrontend has (re)mounted successfully. */
+    public static final String ON_READY = "onMicrofrontendReady";
+    /**
+     * Event fired when loading or mounting the bundle fails (script/stylesheet 404, missing
+     * index.html in {@link #MODE_AUTO}, missing {@link #mountFn}/{@link #tag} on window, an
+     * exception thrown by the bundle itself, etc). {@link org.zkoss.zk.ui.event.Event#getData()} is
+     * a {@code Map} with a {@code message} entry.
+     */
+    public static final String ON_ERROR = "onMicrofrontendError";
     /** Internal, server-only event used to coalesce bursts of {@link #mount()} calls; never sent by the client. */
     private static final String EVT_MOUNT = "onMicrofrontendMount";
 
     static {
         addClientEvent(MicroFrontend.class, ON_EVENT, ComponentCtrl.CE_IMPORTANT);
+        addClientEvent(MicroFrontend.class, ON_READY, ComponentCtrl.CE_IMPORTANT);
+        addClientEvent(MicroFrontend.class, ON_ERROR, ComponentCtrl.CE_IMPORTANT);
     }
 
     private String src;
diff --git a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
index e9307dcc..dbe496b8 100644
--- a/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
+++ b/platform/ui/zk/src/main/resources/static/dynamia-tools/js/zk/dynamia-tools.js
@@ -198,6 +198,17 @@ function dynamiaResolveApp(appRoot) {
     return DynamiaMicrofrontends.apps[appRoot];
 }
 
+/**
+ * Sends a named event with a data payload from a MicroFrontend ZK component's container back to
+ * its server-side component.
+ * @param {string} containerId - Id of the component's container element (its ZK uuid).
+ * @param {string} name - Event name, e.g. "onMicrofrontendReady"/"onMicrofrontendError".
+ * @param {*} data - Event data, or null.
+ */
+function dynamiaFireHostEvent(containerId, name, data) {
+    zAu.send(new zk.Event(zk.Widget.$(containerId), name, data));
+}
+
 /**
  * Loads (if needed) and mounts a microfrontend bundle into the container element of a
  * MicroFrontend ZK component. Injects a {@code dynamiaEmit(data)} function into the mounted
@@ -221,25 +232,33 @@ function dynamiaResolveApp(appRoot) {
  * just reassigns the existing element's properties; "mount-fn" calls "updateFn" if configured,
  * otherwise it tears the old instance down (via unmountFn) and mounts fresh, same as any other
  * structural change (src/app/tag/mountFn/shadow actually changing).
+ *
+ * Fires "onMicrofrontendReady" once mounting/updating succeeds, or "onMicrofrontendError" (with
+ * {message} data) if loading or mounting fails for any reason, both bindable server-side with
+ * onMicrofrontendReady/onMicrofrontendError="@command(...)".
  * @param {string} containerId - Id of the component's container element (its ZK uuid).
  * @param {object} config - {src, css, app, type, mode, tag, mountFn, unmountFn, updateFn, shadow, props}.
  */
 function dynamiaMountMicrofrontend(containerId, config) {
     if (config.mode === 'auto') {
         if (config.shadow) {
-            console.error('Dynamia Microfrontend: shadow=true is not supported with "auto" mode — the bundle finds ' +
+            var shadowAutoMsg = 'Dynamia Microfrontend: shadow=true is not supported with "auto" mode — the bundle finds ' +
                 'its mount target via a page-level document.getElementById() call it makes itself, which cannot see ' +
-                'inside a shadow root. Use tag= (custom element) or mountFn=/unmountFn= instead.');
+                'inside a shadow root. Use tag= (custom element) or mountFn=/unmountFn= instead.';
+            console.error(shadowAutoMsg);
+            dynamiaFireHostEvent(containerId, 'onMicrofrontendError', {message: shadowAutoMsg});
             return;
         }
         DynamiaMicrofrontends.autoMounted = DynamiaMicrofrontends.autoMounted || {};
         var owner = DynamiaMicrofrontends.autoMounted[config.app];
         if (owner && owner !== containerId && document.getElementById(owner)) {
-            console.error('Dynamia Microfrontend: "' + config.app + '" is already auto-mounted on this page. ' +
+            var duplicateAppMsg = 'Dynamia Microfrontend: "' + config.app + '" is already auto-mounted on this page. ' +
                 'Auto mode self-mounts via a hardcoded id from the bundle\'s own index.html and its script ' +
                 'only runs once, so it cannot support a second simultaneous instance of the same app. ' +
                 'Rebuild it as a custom element (use tag=) or expose mount/unmount functions ' +
-                '(mountFn=/unmountFn=) if you need more than one instance.');
+                '(mountFn=/unmountFn=) if you need more than one instance.';
+            console.error(duplicateAppMsg);
+            dynamiaFireHostEvent(containerId, 'onMicrofrontendError', {message: duplicateAppMsg});
             return;
         }
         DynamiaMicrofrontends.autoMounted[config.app] = containerId;
@@ -254,7 +273,7 @@ function dynamiaMountMicrofrontend(containerId, config) {
         if (config.mode === 'auto') {
             container.innerHTML = bundle.bodyHtml || '';
             return Promise.all([dynamiaLoadScript(bundle.src, config.type), dynamiaLoadStyles(bundle.css)]).then(function () {
-                return null;
+                return {auto: true};
             });
         }
 
@@ -300,9 +319,13 @@ function dynamiaMountMicrofrontend(containerId, config) {
         if (!result) {
             return;
         }
+        if (result.auto) {
+            dynamiaFireHostEvent(containerId, 'onMicrofrontendReady', null);
+            return;
+        }
         var props = config.props || {};
         props.dynamiaEmit = function (data) {
-            zAu.send(new zk.Event(zk.Widget.$(containerId), 'onMicrofrontendEvent', data));
+            dynamiaFireHostEvent(containerId, 'onMicrofrontendEvent', data);
         };
 
         if (result.update) {
@@ -312,7 +335,10 @@ function dynamiaMountMicrofrontend(containerId, config) {
                 if (typeof updateFn === 'function') {
                     updateFn(prev.mountTarget, props);
                 } else {
-                    console.error('Dynamia Microfrontend: update function "' + config.updateFn + '" not found on window');
+                    var noUpdateFnMsg = 'Dynamia Microfrontend: update function "' + config.updateFn + '" not found on window';
+                    console.error(noUpdateFnMsg);
+                    dynamiaFireHostEvent(containerId, 'onMicrofrontendError', {message: noUpdateFnMsg});
+                    return;
                 }
             } else {
                 Object.keys(props).forEach(function (key) {
@@ -324,6 +350,7 @@ function dynamiaMountMicrofrontend(containerId, config) {
                 });
             }
             prev.unmountFn = config.unmountFn;
+            dynamiaFireHostEvent(containerId, 'onMicrofrontendReady', null);
             return;
         }
 
@@ -337,7 +364,10 @@ function dynamiaMountMicrofrontend(containerId, config) {
             if (typeof mountFn === 'function') {
                 mountFn(mountTarget, props);
             } else {
-                console.error('Dynamia Microfrontend: mount function "' + config.mountFn + '" not found on window');
+                var noMountFnMsg = 'Dynamia Microfrontend: mount function "' + config.mountFn + '" not found on window';
+                console.error(noMountFnMsg);
+                dynamiaFireHostEvent(containerId, 'onMicrofrontendError', {message: noMountFnMsg});
+                return;
             }
         } else {
             var el = document.createElement(config.tag);
@@ -352,8 +382,10 @@ function dynamiaMountMicrofrontend(containerId, config) {
             instance.el = el;
         }
         DynamiaMicrofrontends.instances[containerId] = instance;
+        dynamiaFireHostEvent(containerId, 'onMicrofrontendReady', null);
     }).catch(function (err) {
         console.error(err);
+        dynamiaFireHostEvent(containerId, 'onMicrofrontendError', {message: err && err.message ? err.message : String(err)});
     });
 }
 

From e115c462cd63142193711ed4852d8a23209e6fca Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Mon, 20 Jul 2026 16:37:03 -0500
Subject: [PATCH 9/9] feat(microfrontend-bridge): add
 @dynamia-tools/microfrontend-bridge npm package

Bundle authors integrating with tools.dynamia.zk.ui.MicroFrontend had to know its
ad-hoc protocol (a dynamiaEmit callback injected into props, a dynamiaHost prop with
server-registered context) and duck-type it by hand. This package wraps it in three
small, fully-typed, zero-runtime-dependency functions - emitToHost, getHostContext,
isDynamiaHost - that work the same whether the bundle is a custom element or a
mount-fn/updateFn app, following the same build/publish conventions as the existing
sdk/vue packages. Typecheck, tests (6 passing) and build verified locally.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../packages/microfrontend-bridge/README.md   | 110 ++++++++++++++++++
 .../microfrontend-bridge/package.json         |  72 ++++++++++++
 .../microfrontend-bridge/src/bridge.ts        |  44 +++++++
 .../microfrontend-bridge/src/index.ts         |   2 +
 .../microfrontend-bridge/src/types.ts         |  36 ++++++
 .../microfrontend-bridge/test/bridge.test.ts  |  41 +++++++
 .../microfrontend-bridge/tsconfig.build.json  |  11 ++
 .../microfrontend-bridge/tsconfig.json        |   8 ++
 .../microfrontend-bridge/vite.config.ts       |  27 +++++
 .../microfrontend-bridge/vitest.config.ts     |  12 ++
 pnpm-lock.yaml                                |  21 ++++
 11 files changed, 384 insertions(+)
 create mode 100644 platform/packages/microfrontend-bridge/README.md
 create mode 100644 platform/packages/microfrontend-bridge/package.json
 create mode 100644 platform/packages/microfrontend-bridge/src/bridge.ts
 create mode 100644 platform/packages/microfrontend-bridge/src/index.ts
 create mode 100644 platform/packages/microfrontend-bridge/src/types.ts
 create mode 100644 platform/packages/microfrontend-bridge/test/bridge.test.ts
 create mode 100644 platform/packages/microfrontend-bridge/tsconfig.build.json
 create mode 100644 platform/packages/microfrontend-bridge/tsconfig.json
 create mode 100644 platform/packages/microfrontend-bridge/vite.config.ts
 create mode 100644 platform/packages/microfrontend-bridge/vitest.config.ts

diff --git a/platform/packages/microfrontend-bridge/README.md b/platform/packages/microfrontend-bridge/README.md
new file mode 100644
index 00000000..e923bfc6
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/README.md
@@ -0,0 +1,110 @@
+# @dynamia-tools/microfrontend-bridge
+
+> Typed helpers for JS/TS bundles (Vue, React, Svelte, plain JS) embedded via `tools.dynamia.zk.ui.MicroFrontend`.
+
+`MicroFrontend` embeds an external JS bundle inside a ZK page and talks to it through a small,
+ad-hoc protocol: an injected `dynamiaEmit(data)` callback to notify the server, and a
+`dynamiaHost` prop with server-registered context (tenant, locale, API base URL, ...). This
+package wraps that protocol in three small, fully-typed functions so bundle authors don't have to
+know the wire details or duck-type props by hand.
+
+Zero runtime dependencies, works with any bundler/framework — this only touches plain objects.
+
+## Installation
+
+```bash
+npm install @dynamia-tools/microfrontend-bridge
+```
+
+## API
+
+- `isDynamiaHost(target)` — whether `dynamiaEmit` was actually injected (false in local/standalone
+  dev, and always false in `MicroFrontend`'s `"auto"` mode, which has no prop channel at all).
+- `emitToHost(target, data)` — sends `data` back to the server, which fires `onMicrofrontendEvent`.
+  No-ops with a console warning (never throws) when not running inside a Dynamia host.
+- `getHostContext(target)` — reads the merged `dynamiaHost` context, or `{}` if none was registered.
+- Types: `DynamiaMicrofrontendProps`, `DynamiaHostContext`.
+
+In every function, `target` is whatever object actually carries the props: the custom element
+instance itself (`this`) in `MODE_CUSTOM_ELEMENT`, or the `props` argument in `MODE_MOUNT_FN`'s
+`mountFn`/`updateFn`.
+
+## Usage
+
+### Custom element (e.g. Vue's `defineCustomElement`)
+
+```ts
+import { defineCustomElement } from 'vue';
+import { emitToHost, getHostContext, type DynamiaMicrofrontendProps } from '@dynamia-tools/microfrontend-bridge';
+import App from './App.vue';
+
+const MyWidget = defineCustomElement({
+  props: ['userId'],
+  setup(props) {
+    // `this` inside a Vue defineCustomElement's methods is the element instance itself,
+    // which is exactly what MicroFrontend assigns dynamiaEmit/dynamiaHost onto.
+    function notifyHost(data: unknown) {
+      emitToHost(this as unknown as DynamiaMicrofrontendProps, data);
+    }
+    const host = getHostContext(this as unknown as DynamiaMicrofrontendProps);
+    // ...use props.userId, host.tenantId, host.locale, etc.
+  },
+});
+
+customElements.define('my-widget', MyWidget);
+```
+
+```xml
+<!-- ZUL side -->
+<microfrontend src="/bundles/my-widget.js" tag="my-widget" userId="${user.id}"
+               onMicrofrontendEvent="@command('handleWidgetEvent', data=event.data)"/>
+```
+
+### `mount-fn` convention (single-spa style)
+
+```ts
+import { emitToHost, getHostContext, type DynamiaMicrofrontendProps } from '@dynamia-tools/microfrontend-bridge';
+
+window.mountMyApp = (container: HTMLElement, props: DynamiaMicrofrontendProps) => {
+  const host = getHostContext(props);
+  fetch(`${host.apiBaseUrl ?? '/api'}/things?tenant=${host.tenantId}`)
+    .then((res) => res.json())
+    .then((things) => render(container, things, () => emitToHost(props, { type: 'clicked' })));
+};
+
+window.updateMyApp = (container: HTMLElement, props: DynamiaMicrofrontendProps) => {
+  // called instead of a full unmount+mount when only props changed (MicroFrontend's updateFn=)
+  rerender(container, props);
+};
+
+window.unmountMyApp = (container: HTMLElement) => {
+  container.innerHTML = '';
+};
+```
+
+```xml
+<!-- ZUL side -->
+<microfrontend src="/bundles/my-app.js" mode="mount-fn"
+               mountFn="mountMyApp" unmountFn="unmountMyApp" updateFn="updateMyApp"/>
+```
+
+## Providing host context (Java side)
+
+```java
+@Component
+public class TenantHostContextProvider implements MicroFrontendHostContextProvider {
+    @Override
+    public Map<String, Object> getHostContext() {
+        Account account = AccountServiceAPI.getCurrentAccount();
+        return Map.of(
+            "tenantId", account.getId(),
+            "locale", LocaleUtils.getCurrentLocale().toLanguageTag(),
+            "apiBaseUrl", "/api"
+        );
+    }
+}
+```
+
+## License
+
+Apache-2.0
diff --git a/platform/packages/microfrontend-bridge/package.json b/platform/packages/microfrontend-bridge/package.json
new file mode 100644
index 00000000..40a6e13e
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/package.json
@@ -0,0 +1,72 @@
+{
+  "name": "@dynamia-tools/microfrontend-bridge",
+  "version": "26.7.0",
+  "website": "https://dynamia.tools",
+  "description": "Typed helpers for JS/TS bundles (Vue, React, Svelte, plain JS) embedded via tools.dynamia.zk.ui.MicroFrontend",
+  "keywords": [
+    "dynamia",
+    "dynamia-platform",
+    "microfrontend",
+    "zk",
+    "custom-elements",
+    "typescript"
+  ],
+  "homepage": "https://dynamia.tools",
+  "bugs": {
+    "url": "https://github.com/dynamiatools/framework/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dynamiatools/framework.git",
+    "directory": "platform/packages/microfrontend-bridge"
+  },
+  "license": "Apache-2.0",
+  "author": "Dynamia Soluciones IT SAS",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run build && pnpm run test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.4",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}
diff --git a/platform/packages/microfrontend-bridge/src/bridge.ts b/platform/packages/microfrontend-bridge/src/bridge.ts
new file mode 100644
index 00000000..71891a9e
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/src/bridge.ts
@@ -0,0 +1,44 @@
+import type { DynamiaHostContext, DynamiaMicrofrontendProps } from './types.js';
+
+/**
+ * Whether `target` looks like it's actually running inside a `tools.dynamia.zk.ui.MicroFrontend`
+ * host, i.e. `dynamiaEmit` was injected. False for MicroFrontend's "auto" mode (no prop channel at
+ * all) and for local/standalone dev runs outside any Dynamia host.
+ *
+ * @param target a custom element instance (pass `this`) or the props object a mount-fn/updateFn receives
+ */
+export function isDynamiaHost(target: DynamiaMicrofrontendProps | null | undefined): boolean {
+    return typeof target?.dynamiaEmit === 'function';
+}
+
+/**
+ * Sends `data` back to the server-side MicroFrontend component hosting this bundle, which fires
+ * "onMicrofrontendEvent" server-side (bindable with `onMicrofrontendEvent="@command(...)"`). Works
+ * the same whether `target` is a custom element instance (pass `this`) or the `props` object a
+ * mount-fn/updateFn receives — both carry `dynamiaEmit` the same way. No-ops with a console warning
+ * instead of throwing when not running inside a Dynamia host (see {@link isDynamiaHost}), so
+ * bundles keep working standalone during local development.
+ *
+ * @param target a custom element instance (pass `this`) or the props object a mount-fn/updateFn receives
+ * @param data JSON-serializable payload, delivered as `event.getData()` server-side
+ */
+export function emitToHost(target: DynamiaMicrofrontendProps, data: unknown): void {
+    if (typeof target?.dynamiaEmit === 'function') {
+        target.dynamiaEmit(data);
+    } else if (typeof console !== 'undefined') {
+        console.warn(
+            '[@dynamia-tools/microfrontend-bridge] emitToHost() called but dynamiaEmit is not available ' +
+            '- not running inside a MicroFrontend host, or this is "auto" mode (no prop channel).'
+        );
+    }
+}
+
+/**
+ * Returns the host context merged from every registered `MicroFrontendHostContextProvider`, or
+ * `{}` if none were registered (or not running inside a Dynamia host).
+ *
+ * @param target a custom element instance (pass `this`) or the props object a mount-fn/updateFn receives
+ */
+export function getHostContext(target: DynamiaMicrofrontendProps | null | undefined): DynamiaHostContext {
+    return target?.dynamiaHost ?? {};
+}
diff --git a/platform/packages/microfrontend-bridge/src/index.ts b/platform/packages/microfrontend-bridge/src/index.ts
new file mode 100644
index 00000000..9df9a699
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/src/index.ts
@@ -0,0 +1,2 @@
+export {emitToHost, getHostContext, isDynamiaHost} from './bridge.js';
+export type {DynamiaHostContext, DynamiaMicrofrontendProps} from './types.js';
diff --git a/platform/packages/microfrontend-bridge/src/types.ts b/platform/packages/microfrontend-bridge/src/types.ts
new file mode 100644
index 00000000..1816e92c
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/src/types.ts
@@ -0,0 +1,36 @@
+/**
+ * Cross-cutting context values registered server-side via one or more
+ * `tools.dynamia.zk.ui.MicroFrontendHostContextProvider` beans, merged and delivered as the
+ * `dynamiaHost` prop on every mount (except MicroFrontend's "auto" mode, which has no prop channel
+ * at all). Shape is entirely app-defined; the fields below are just common examples.
+ */
+export interface DynamiaHostContext {
+    tenantId?: string;
+    locale?: string;
+    apiBaseUrl?: string;
+
+    [key: string]: unknown;
+}
+
+/**
+ * Shape of what `tools.dynamia.zk.ui.MicroFrontend` actually delivers to a mounted bundle:
+ * - In "custom-element" mode, these are assigned as properties directly on the element instance
+ *   (`this.dynamiaEmit`, `this.dynamiaHost`, ...).
+ * - In "mount-fn" mode, they're the second argument passed to `mountFn(container, props)` /
+ *   `updateFn(container, props)`.
+ *
+ * Any other key is an app-defined prop bound via a ZUL attribute (e.g. `userId="@bind(vm.userId)"`)
+ * or `MicroFrontend#addProp`/`#setProps`.
+ */
+export interface DynamiaMicrofrontendProps {
+    /**
+     * Sends `data` back to the server-side MicroFrontend component, which fires
+     * "onMicrofrontendEvent" (bindable with `onMicrofrontendEvent="@command(...)"`). Undefined
+     * when not running inside a Dynamia host — see {@link isDynamiaHost}.
+     */
+    dynamiaEmit?: (data: unknown) => void;
+    /** Merged {@link DynamiaHostContext} from every registered MicroFrontendHostContextProvider. */
+    dynamiaHost?: DynamiaHostContext;
+
+    [key: string]: unknown;
+}
diff --git a/platform/packages/microfrontend-bridge/test/bridge.test.ts b/platform/packages/microfrontend-bridge/test/bridge.test.ts
new file mode 100644
index 00000000..c5c8c7d6
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/test/bridge.test.ts
@@ -0,0 +1,41 @@
+import {describe, expect, it, vi} from 'vitest';
+import {emitToHost, getHostContext, isDynamiaHost} from '../src/bridge.js';
+
+describe('isDynamiaHost', () => {
+    it('is true when dynamiaEmit is a function', () => {
+        expect(isDynamiaHost({dynamiaEmit: () => undefined})).toBe(true);
+    });
+
+    it('is false when dynamiaEmit is missing or not a function', () => {
+        expect(isDynamiaHost({})).toBe(false);
+        expect(isDynamiaHost(null)).toBe(false);
+        expect(isDynamiaHost(undefined)).toBe(false);
+    });
+});
+
+describe('emitToHost', () => {
+    it('calls dynamiaEmit with the given data', () => {
+        const dynamiaEmit = vi.fn();
+        emitToHost({dynamiaEmit}, {foo: 'bar'});
+        expect(dynamiaEmit).toHaveBeenCalledWith({foo: 'bar'});
+    });
+
+    it('warns instead of throwing when dynamiaEmit is missing', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        expect(() => emitToHost({}, {foo: 'bar'})).not.toThrow();
+        expect(warn).toHaveBeenCalledOnce();
+        warn.mockRestore();
+    });
+});
+
+describe('getHostContext', () => {
+    it('returns dynamiaHost when present', () => {
+        expect(getHostContext({dynamiaHost: {tenantId: 't1'}})).toEqual({tenantId: 't1'});
+    });
+
+    it('returns {} when absent', () => {
+        expect(getHostContext({})).toEqual({});
+        expect(getHostContext(null)).toEqual({});
+        expect(getHostContext(undefined)).toEqual({});
+    });
+});
diff --git a/platform/packages/microfrontend-bridge/tsconfig.build.json b/platform/packages/microfrontend-bridge/tsconfig.build.json
new file mode 100644
index 00000000..8bfff951
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/tsconfig.build.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}
diff --git a/platform/packages/microfrontend-bridge/tsconfig.json b/platform/packages/microfrontend-bridge/tsconfig.json
new file mode 100644
index 00000000..d6d13237
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "customConditions": ["development"],
+    "noEmit": true
+  },
+  "include": ["src", "test"]
+}
diff --git a/platform/packages/microfrontend-bridge/vite.config.ts b/platform/packages/microfrontend-bridge/vite.config.ts
new file mode 100644
index 00000000..8246c875
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/vite.config.ts
@@ -0,0 +1,27 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import { resolve } from 'path';
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: ['src'],
+      outDir: 'dist',
+      insertTypesEntry: true,
+      tsconfigPath: './tsconfig.build.json',
+    }),
+  ],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'DynamiaMicrofrontendBridge',
+      formats: ['es', 'cjs'],
+      fileName: (format) => (format === 'es' ? 'index.js' : 'index.cjs'),
+    },
+    rollupOptions: {
+      external: [],
+    },
+    sourcemap: true,
+    minify: false,
+  },
+});
diff --git a/platform/packages/microfrontend-bridge/vitest.config.ts b/platform/packages/microfrontend-bridge/vitest.config.ts
new file mode 100644
index 00000000..001cbcb7
--- /dev/null
+++ b/platform/packages/microfrontend-bridge/vitest.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+    },
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a30c73b3..f1d75dfa 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -127,6 +127,27 @@ importers:
         specifier: ^6.0.3
         version: 6.0.3
 
+  platform/packages/microfrontend-bridge:
+    devDependencies:
+      '@types/node':
+        specifier: ^26.1.1
+        version: 26.1.1
+      '@vitest/coverage-v8':
+        specifier: ^4.1.10
+        version: 4.1.10(vitest@4.1.10)
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+      vite:
+        specifier: ^8.1.4
+        version: 8.1.4(@types/node@26.1.1)
+      vite-plugin-dts:
+        specifier: ^5.0.3
+        version: 5.0.3(rolldown@1.1.5)(typescript@6.0.3)(vite@8.1.4(@types/node@26.1.1))
+      vitest:
+        specifier: ^4.1.10
+        version: 4.1.10(@types/node@26.1.1)(@vitest/coverage-v8@4.1.10)(vite@8.1.4(@types/node@26.1.1))
+
   platform/packages/sdk:
     devDependencies:
       '@types/node':