Document embedded client public Beta

content/en/docs/refguide/modeling/app-explorer/app/navigation/_index.md

@@ -25,8 +25,9 @@ The core of Mendix's navigation model is founded on the following profiles:
 * Phone web
     * Phone web offline
 * Native mobile (tablet & phone)
+* Embedded (Beta)
 
-Users that access the app via a particular device type are automatically redirected to the homepage of the appropriate profile based on the profile type (for details, see the [Redirection to Profiles](#redirection) section below).
+Users that access the app via a particular device type are automatically redirected to the homepage of the appropriate browser or mobile profile based on the profile type (for details, see the [Redirection to Profiles](#redirection) section below). The Embedded profile is not selected through device detection. It is used when a host application loads the embedded client.
 
 The device type of the currently logged-in user is available in [microflows](/refguide/microflows/) as the `$currentDeviceType` variable. The type of this variable is the [enumeration](/refguide/enumerations/) `System.DeviceType`, which has the values `Phone`, `Tablet`, and `Desktop`. You can use `$currentDeviceType` to perform different actions based on the device type. A typical example is to show different pages based on the device type.
 
@@ -56,6 +57,12 @@ The Mendix app will run in [offline-first](/refguide/offline-first/) mode. This
 You are required to enable anonymous users in your app's security settings and include anonymous user roles on native login pages. This is because there is no built-in login screen in the native profile; login pages are modeled as regular native pages. 
 {{% /alert %}}
 
+### Embedded
+
+The Embedded profile lets you use a Mendix web app as a component inside another web application. The host application loads the embedded client and owns browser-level navigation, while the Mendix app renders and navigates inside its mounted region.
+
+The Embedded profile defines a default home page and can also define an fallback page. When the configured home page expects page parameters, the host application can pass them through the `parameters` object in `render(...)`. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/).
+
 ## Redirection to Profiles {#redirection}
 
 Mendix Runtime automatically redirects users to the home page of the appropriate device type based on the device they are using. This happens by examining the `User-Agent` string that is sent by the device. The default configuration for this redirection is as follows:
@@ -98,6 +105,8 @@ The default home page indicates which [page](/refguide/page/) or [microflow](/re
 The default home page is visible to all unauthenticated users.
 {{% /alert %}}
 
+For the Embedded profile, the default home page is the first page shown when the host application calls `render(...)`.
+
 #### Role-Based Home Pages{#role-based}
 
 By using role-based home pages, you can show different home pages for different users. If a user logs in, the first role-based home page of which the user role matches the user role of the user is displayed. If no match is found, the default home page is used.
@@ -108,6 +117,8 @@ For each role-based home page, you can specify the user role it applies to and t
 
 The fallback page is a page or microflow that can be used to customize the application's behavior when trying to access a [microflow](/refguide/microflow/#url) or [page](/refguide/page-properties/#url) URL that does not exist. For more information, see [Setting a Fallback Page](/refguide/setting-up-the-navigation-structure/#fallback) in *Setting Up Navigation*.
 
+For Embedded profiles, you can configure a fallback page as well. This page is shown when the embedded app cannot open the configured home page during startup or navigation. Examples include page parameter values passed through `render(...)` that do not match the expected parameter types, or a configured home page that is not accessible for the signed-in user. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/).
+
 ### Authentication {#authentication}
 
 If a user, [anonymous](/refguide/anonymous-users/) or authenticated, tries to access a resource to which the user has no access, the configured [sign-in page](/refguide/authentication-widgets/) will be displayed, prompting the user to sign in.
@@ -145,4 +156,5 @@ For more details on the settings and when to use them, see the [Offline-First Re
 ## Read More
 
 * [App Explorer](/refguide/app-explorer/)
+* [Embedding the Client](/refguide/mendix-client/embedding-the-client/)
 * [Navigation Tree](/refguide/navigation-tree/)

content/en/docs/refguide/modeling/app-explorer/app/navigation/setting-up-the-navigation-structure.md

@@ -8,7 +8,7 @@ aliases:
 ---
 ## Introduction
 
-Once your app has some pages, create a navigation menu to give your users access to them. The navigation editor allows you define the navigation menu for different type of apps and devices (for example, for responsive, tablet browser, or native mobile apps). It also allows you to define which page is shown as a default home page depending on the user role.
+Once your app has some pages, create a navigation menu to give your users access to them. The navigation editor allows you define the navigation menu for different type of apps and devices (for example, for responsive, tablet browser, native mobile, or embedded apps). It also allows you to define which page is shown as a default home page depending on the user role.
 
 ## Setting a Default Home Page {#home}
 
@@ -35,6 +35,8 @@ Do the following:
 For online profiles, you can set a microflow as a default home page. Make sure a [Show Page](/refguide/show-page/) activity is called from the startup microflow for each possible execution flow. Otherwise, the user will see nothing during execution paths where the activity is missing.
 
 For the native mobile profile, you can set a nanoflow as a home page, either as a default or as a role-based. For more information, see the [Setting a Nanoflow as a Home Page](#nanoflow-home-page) section below.
+
+For the Embedded profile, the selected home page is the first page shown when the host application calls `render(...)`. When that page requires parameters, the host application passes them through the `parameters` object in `render(...)`. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/).
 {{% /alert %}}
 
 Now every time a user signs in to the application, the selected page/microflow is shown/triggered.
@@ -74,6 +76,12 @@ If a microflow is used as a fallback, it can have only one String parameter name
 
 The fallback page will only be used for URLs that start with a [URL Prefix](/refguide/runtime-tab/#url-prefix).
 
+## Setting an Error Page for an Embedded Profile
+
+The Embedded profile can use an error page when the configured home page cannot be opened during startup or navigation. This can happen when the values passed in `render(...)` do not match the expected page parameter types or when the signed-in user does not have access to the configured home page. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/).
+
+To configure an error page, open the Embedded profile in the **Navigation** editor and select the page you want to use.
+
 ## Setting a Nanoflow as a Home Page {#nanoflow-home-page}
 
 Instead of using a page, you can set a nanoflow as your app's home page as long as you are using a native profile. The nanoflow you selected will be executed during startup and will show your app's starting page. This is a normal nanoflow call, which means that you can implement custom logic that determines which page to show, creates objects, calls sub-nanoflows, uses JavaScript actions, and more.
@@ -134,3 +142,4 @@ To avoid adding the menu widget on every page in your app, you can use a layout.
 
 * [Atlas UI](/howto/front-end/atlas-ui/)
 * [Create Your First Two Overview and Detail Pages](/howto/front-end/create-your-first-two-overview-and-detail-pages/)
+* [Embedding the Client](/refguide/mendix-client/embedding-the-client/)

content/en/docs/refguide/runtime/mendix-client/_index.md

@@ -29,6 +29,8 @@ The Mendix Dojo Client is bootstrapped by loading a `mxui.js` script from an HTM
 
 The Mendix React client is bootstrapped in different way. It loads the `index.js` file which loads the `common.js` with the Mendix client. More JavaScript files that contain page, layout, and nanoflow definitions will be loaded after this.
 
+When you want to mount a Mendix web app inside another web application, you can also use the embedded client. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/).
+
 For **mobile applications**, the Mendix Client acts as a React Native application. This means that apps created by Mendix consist of two parts: a *wrapper* and a *bundle*. The wrapper is a native iOS or Android application that loads the bundle and exposes platform functionality to it. The bundle includes Client Core, Pluggable Widgets, and application-specific resources like nanoflows and pages.
 
 The three supported types of wrappers for mobile applications are as follows:

content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md

@@ -0,0 +1,195 @@
+---
+title: "Embedding the Client"
+url: /refguide/mendix-client/embedding-the-client/
+description: "Describes how to load a Mendix web app into another web application by using the embedded client."
+weight: 30
+beta: true
+---
+
+{{% alert color="warning" %}}
+This feature is in Public Beta. For more information, see [Release Status](/releasenotes/release-status/).
+{{% /alert %}}
+
+## Introduction
+
+The embedded client lets you use a Mendix web app as a component inside another web application. This makes it easier to add Mendix capabilities to broader digital experiences, support micro-frontend architectures, and integrate Mendix seamlessly with existing portals, products, or custom frontends. In this setup, the host application owns the surrounding page and browser-level experience, while the Mendix app owns the region where it is mounted.
+
+This page describes the following:
+
+* Configure an Embedded navigation profile in your Mendix app
+* Load the embedded client from a host application
+* Pass page parameters to the embedded home page
+* Understand how CSS behaves in an embedded app
+* Understand how navigation behaves in an embedded app
+* Understand authentication options for an embedded app
+* Configure host app requirements such as CORS and CSP
+* Mount and unmount the client at the correct lifecycle moment
+
+{{% alert color="info" %}}
+Embedding the Mendix client is only supported for the [Mendix React Client](/refguide/mendix-client/react/).
+{{% /alert %}}
+
+## How the Embedded Client Works
+
+When your app contains an Embedded navigation profile, the Mendix runtime exposes an embedded entry bundle at `/dist/embedded-index.js`.
+
+Your host application is responsible for the following:
+
+* Choosing the Mendix runtime URL
+* Loading the embedded bundle with a dynamic import
+* Creating a DOM element that Mendix can render into
+* Calling `render(...)` on the embedded bundle
+* Calling the returned unmount function when the host component is removed
+* Showing any loading or error state in the host UI
+
+The same integration pattern works in React, Vue, plain JavaScript, and other frontend frameworks.
+
+## Example host apps
+
+See the [embedded-mendix-demo-apps](https://github.com/mendix/embedded-mendix-demo-apps) GitHub repository for an example Mendix application that has been configured to be embedded, together with example host applications using Vue, React, and vanilla JavaScript.
+
+## Configuring the Embedded App
+
+To enable the embedded client for your Mendix app, do the following:
+
+1. Open your app in Studio Pro.
+2. Open **App** > **Navigation**.
+3. Click **Add navigation profile**.
+4. Select **Embedded**.
+5. Configure the **Default home page** for the Embedded profile.
+6. Configure an fallback page for the Embedded profile (optional).
+7. Run or deploy the app.
+
+{{< figure src="/attachments/refguide/mendix-client/embedding-the-client/nav-profile.png" alt="embedded navigation profile UI" class="no-border">}}
+
+After you add the Embedded profile, the Mendix runtime serves the following bundle:
+
+```text
+<runtime-url>/dist/embedded-index.js
+```
+
+For example, if your runtime URL is `http://localhost:8080`, the embedded bundle is served from `http://localhost:8080/dist/embedded-index.js`.
+
+The Embedded profile defines the starting page for the embedded app, which is the first page shown when the host calls `render(...)`, and it can also define an fallback page for startup or navigation failures. When the embedded home page requires page parameters, pass those values from the host application by using the `parameters` object in the `render(...)` configuration. The configured fallback page is shown when the parameters passed in `render(...)` do not match the expected parameter types of the embedded home page or when the selected home page is not accessible for the signed-in user.
+
+The parameter names in `parameters` must match the page parameters expected by the embedded home page.
+
+## Creating a Host Container
+
+Create an element in the host application where the Mendix app will be mounted.
+
+For example:
+
+```html
+<div id="embedded-mendix-host"></div>
+```
+
+Or in a framework component:
+
+```tsx
+<div ref={hostRef} />
+```
+
+The host only needs to provide a real DOM node.
+
+## Loading and Rendering the Embedded Client
+
+The embedded bundle exposes a `render(...)` function. A minimal framework-agnostic integration looks like this:
+
+```js
+const REMOTE_URL = "https://your-mendix-runtime.example.com/";
+
+export async function mountEmbeddedMendix(container) {
+    const embeddedModule = await import(`${REMOTE_URL}dist/embedded-index.js`);
+
+    return embeddedModule.render(container, {
+        remoteUrl: REMOTE_URL,
+        minHeight: "620px",
+        parameters: {
+            customerId: "12345"
+        }
+    });
+}
+```
+
+This code does the following:
+
+* Resolves the runtime URL
+* Loads the embedded bundle from the Mendix runtime
+* Passes page parameters to the embedded home page
+* Calls `render(...)` with the container element
+* Returns the unmount function from the embedded client
+
+{{% alert color="info" %}}
+If your host application uses Vite, add the `/* @vite-ignore */` comment to the dynamic import so Vite does not try to resolve the runtime URL during the host build.
+{{% /alert %}}
+
+## Mounting and Cleaning Up
+
+Call the embedding logic only after the container exists and store the returned unmount function.
+
+Typical lifecycle hooks include the following:
+
+* React: `useEffect(...)`
+* Vue: `onMounted(...)` and `onBeforeUnmount(...)`
+* Plain JavaScript: after locating the container with `getElementById(...)` and during your own teardown flow
+
+For example:
+
+```js
+const container = document.getElementById("embedded-mendix-host");
+const unmount = await mountEmbeddedMendix(container);
+
+// Call this when the host view is removed.
+unmount();
+```
+
+## Authentication
+
+In the current Public Beta, embedded apps require [anonymous users](/refguide/anonymous-users/) to be enabled. The embedded client does not include a platform-level mechanism to pass the host application's authentication context to the embedded Mendix app. If your embedded scenario requires signed-in access, implement a custom authentication approach that fits your architecture and security requirements.
+
+## CSS Behavior
+
+The embedded client runs inside a shadow root so that its styles stay isolated from the host app.
+
+To make common app styling keep working, Mendix rewrites CSS selectors that target `:root`, `html`, or `body` so they target `mx-app-container` instead. `mx-app-container` is the element that wraps the embedded client inside the shadow root. This allows CSS variables and other top-level styles to keep applying inside the embedded app.
+
+If a selector depends on attributes on `html` or `body`, those attributes are mirrored to the shadow root so those selectors can still work when the app is embedded.
+
+`@font-face` declarations are handled differently. Because shadow roots do not support font declarations in the same way, Mendix moves those declarations to a `style` tag in the host page's `head`.
+
+{{% alert color="info" %}}
+Not all custom CSS will behave exactly the same when an app is embedded. However, Atlas styling is supported.
+{{% /alert %}}
+
+## Embedded Navigation
+
+An embedded app does not react to changes in the browser address bar or to the browser's back and forward buttons. This is because the embedded app runs as a component inside the host app, and the host app should control browser navigation.
+
+The embedded Mendix app can still navigate internally. For example, it can open other pages by using [Show Page](/refguide/show-page/) actions or buttons that open a page. When the browser reloads, the Mendix app restarts as well, and the home page is shown.
+
+## Cross-Origin Requests
+
+If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/).
+
+## Content Security Policy
+
+If the host app uses Content Security Policy (CSP), make sure its policy allows JavaScript to load from the Mendix runtime domain. This is required because the host app loads the embedded bundle and other client resources from that domain. For more information, see [Content Security Policy](/howto/security/csp/).
+
+## Cross-site Cookies
+
+Cross-site cookies must be enabled in the browser when the Mendix application is hosted on a different domain from the host application.
+
+## Known Issues
+
+### Optional Parameters
+Omitting a parameter that is marked as optional from the `parameters` object will result in the fallback page being shown instead of the default value being passed.
+
+## Read More
+
+* [Mendix Client](/refguide/mendix-client/)
+* [Mendix React Client](/refguide/mendix-client/react/)
+* [Navigation](/refguide/navigation/)
+* [Setting Up Navigation](/refguide/setting-up-the-navigation-structure/)
+* [Configure CORS](/refguide/configure-cors/)
+* [Content Security Policy](/howto/security/csp/).