@ti-engine/web-framework 1.19.0 → 1.20.0

package/bin/web-app-manager.js

@@ -1,663 +1,660 @@
-/*
- * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
-
-const exceptions = require( "@ti-engine/core/exceptions" );
-const tools = require( "@ti-engine/core/tools" );
-const localization = require( "@ti-engine/core/localization" );
-const path = require( "node:path" );
-const fs = require( "node:fs" );
-const configRegistry = require( "#config-registry" );
-const configService = require( "#config-service" );
-const authorization = require( "#authorization" );
-
-const RE_NONCE_ATTR = /\{ti-nonce-placeholder}/g;
-const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
-const RE_HTMX_CONFIG = /\{ti-htmx-config-placeholder}/g;
-const RE_CSP_NONCE = /^[A-Za-z0-9+/=_-]{16,}$/;
-const TI_NESTED_FRAME_PLACEHOLDER = "ti-nested-frame-placeholder";
-const OAUTH_METHODS = [ "openid-google", "openid-azure" ];
-const ALL_METHODS = [ "local", "openid-google", "openid-azure" ];
-const RE_AUTH_MARKERS = /<!--\/?ti-auth-(?:divider|social|none|method(?::[a-z-]+)?)-->/g;
-
-/**
- * Removes every `<openMarker>…<closeMarker>` span (inclusive) from `html` in a single linear pass. The markers are
- * matched as fixed strings via `indexOf`, so — unlike an `openMarker[\s\S]*?closeMarker` regular expression under a
- * global replace — this cannot exhibit super-linear backtracking on hostile input containing many opening markers
- * (CodeQL js/polynomial-redos). Matches the lazy-regex semantics: each opening marker pairs with the *next* closing
- * marker after it. An opening marker with no matching closing marker is left untouched (the caller strips any stray
- * markers afterwards with {@link RE_AUTH_MARKERS}).
- *
- * @param {string} html
- * @param {string} openMarker
- * @param {string} closeMarker
- * @returns {string}
- */
-function stripMarkerSpans( html, openMarker, closeMarker ) {
-    let result = "";
-    let cursor = 0;
-    for ( ; ; ) {
-        const open = html.indexOf( openMarker, cursor );
-        if ( open === -1 ) {
-            result += html.slice( cursor );
-            break;
-        }
-        const close = html.indexOf( closeMarker, open + openMarker.length );
-        if ( close === -1 ) {
-            result += html.slice( cursor );
-            break;
-        }
-        result += html.slice( cursor, open );
-        cursor = close + closeMarker.length;
-    }
-    return result;
-}
-
-/**
- * Gates the login-page authentication markup to the effective enabled methods. The login fragment delimits blocks
- * with HTML-comment markers: `<!--ti-auth-method:METHOD-->…<!--/ti-auth-method-->` around each method's control
- * (the `local` credentials form and each OpenID provider button), `<!--ti-auth-divider-->…<!--/ti-auth-divider-->`
- * around the "or continue with" separator, `<!--ti-auth-social-->…<!--/ti-auth-social-->` around the SSO button
- * group, and `<!--ti-auth-none-->…<!--/ti-auth-none-->` around a "no method configured" fallback. It removes the
- * block for any method that is not enabled, drops the social group when no SSO provider is enabled, shows the
- * divider only when a local form AND at least one SSO provider are both present, and shows the fallback only when
- * nothing is enabled. Any remaining markers are stripped so clean HTML ships. Fragments without these markers
- * (every non-login fragment) are returned unchanged.
- *
- * @param {string} html
- * @param {string[]} [enabledMethods] The effective enabled authentication methods.
- * @returns {string}
- */
-function applyAuthMethodVisibility( html, enabledMethods ) {
-    let result = String( html );
-    const enabled = Array.isArray( enabledMethods ) ? enabledMethods : [];
-    const localEnabled = enabled.includes( "local" );
-    const anyOAuth = OAUTH_METHODS.some( ( method ) => enabled.includes( method ) );
-
-    // Drop the block for each authentication method that is not enabled.
-    ALL_METHODS.forEach( ( method ) => {
-        if ( !enabled.includes( method ) ) {
-            result = stripMarkerSpans( result, "<!--ti-auth-method:" + method + "-->", "<!--/ti-auth-method-->" );
-        }
-    } );
-
-    // Drop the SSO button group when no OpenID provider is enabled.
-    if ( !anyOAuth ) {
-        result = stripMarkerSpans( result, "<!--ti-auth-social-->", "<!--/ti-auth-social-->" );
-    }
-
-    // Show the "or continue with" divider only when BOTH a local form and at least one SSO provider are present.
-    if ( !( localEnabled && anyOAuth ) ) {
-        result = stripMarkerSpans( result, "<!--ti-auth-divider-->", "<!--/ti-auth-divider-->" );
-    }
-
-    // Show the "no method configured" fallback only when nothing is enabled.
-    if ( localEnabled || anyOAuth ) {
-        result = stripMarkerSpans( result, "<!--ti-auth-none-->", "<!--/ti-auth-none-->" );
-    }
-
-    return result.replace( RE_AUTH_MARKERS, "" );
-}
-
-/**
- * A generic web application manager that handles the rendering and behavior of web application views. It is designed to be extended by specific web application
- * managers for each web application you want to implement with the ti-engine web framework.
- * <br/>
- * NOTE: You should not instantiate this class directly. Instead, extend it and override the abstract methods as needed. Additionally, you should configure your
- * ti-engine web server 'TiWebApplicationConfig' settings by specifying the 'classPath' that corresponds to your web application manager. The path should be
- * relative to the intended process's working directory.
- *
- * @class TiWebAppManager
- * @abstract
- * @public
- */
-class TiWebAppManager {
-
-    #webAppIdentifier;
-    #fragments = {};
-    #staticFileCache = {};
-    #staticFileCacheEnabled;
-    #enabledAuthMethods = [];
-
-    /**
-     * @constructor
-     * @param {string} identifier The identifier for this web application. Should be unique and recognizable.
-     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
-     */
-    constructor( identifier ) {
-        // Make sure this abstract class cannot be instantiated:
-        if ( new.target === TiWebAppManager ) {
-            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
-        }
-
-        this.#webAppIdentifier = identifier;
-        this.#staticFileCacheEnabled = ( process.env.TI_WEB_APP_STATIC_CACHE_DISABLED !== "true" );
-
-        // Define the default HTML fragments for the application:
-        this.#fragments[ 'home' ] = {
-            path: "index.html",
-            components: [ "component-notification-bar" ]
-        };
-        this.#fragments[ 'application-main' ] = {
-            title: "Application",
-            path: "fragments/frame-application.html",
-            components: [ "component-topbar", "component-sidebar", "component-notification-bar", "component-sidebar-flyout" ]
-        };
-        this.#fragments[ 'login' ] = {
-            title: "Login",
-            path: "fragments/frame-login.html"
-        };
-        this.#fragments[ 'dashboard' ] = {
-            title: "Dashboard",
-            path: "fragments/frame-dashboard.html"
-        };
-        this.#fragments[ 'administration' ] = {
-            title: "Administration",
-            path: "fragments/frame-administration.html"
-        };
-        this.#fragments[ 'profile' ] = {
-            title: "Profile",
-            path: "fragments/frame-profile.html"
-        };
-        this.#fragments[ 'not-found' ] = {
-            title: "Not Found",
-            path: "fragments/frame-not-found.html"
-        };
-    }
-
-    /* Public interface */
-
-    /**
-     * Returns the identifier for this web application.
-     *
-     * @property
-     * @returns {string}
-     * @public
-     */
-    get webAppIdentifier() {
-        return this.#webAppIdentifier;
-    }
-
-    /**
-     * Adds a new HTML fragment to the web application.
-     * <br/>
-     * NOTE: This method should only be called during the initialization phase of your web application manager.
-     *
-     * @method
-     * @param {string} identifier
-     * @param {Object} fragment The fragment descriptor (`{ title, path, components }`). May also carry an optional
-     * `roles` array (`Array<string|number>`): when present, the default {@link TiWebAppManager#verifyAccess} serves
-     * the fragment only to sessions holding at least one of those roles; omit it (or leave empty) for a public screen.
-     * @throws {TiException.E_GEN_UNALLOWED_OVERRIDE} If a fragment with the same identifier already exists.
-     * @public
-     */
-    addFragment( identifier, fragment ) {
-        if ( this.#fragments[ identifier ] === undefined ) {
-            this.#fragments[ identifier ] = fragment;
-        } else {
-            throw exceptions.raise( exceptions.exceptionCode.E_GEN_UNALLOWED_OVERRIDE, { identifier: identifier } );
-        }
-    }
-
-    /**
-     * Registers an editable configuration document with the framework config registry (JSON Schema + semantic
-     * validators + default value + editor metadata). Call during initialization. See {@link ConfigRegistry#register}.
-     *
-     * @method
-     * @param {string} configKey
-     * @param {Object} definition
-     * @returns {TiWebAppManager} this (chainable)
-     * @public
-     */
-    registerConfigDocument( configKey, definition ) {
-        configRegistry.instance.register( configKey, definition );
-        return this;
-    }
-
-    /**
-     * Registers a JSON Schema that is referenced (via `$ref`) by config-document schemas but is not itself a document.
-     *
-     * @method
-     * @param {Object} schema
-     * @returns {TiWebAppManager} this (chainable)
-     * @public
-     */
-    registerConfigSchema( schema ) {
-        configRegistry.instance.addSchema( schema );
-        return this;
-    }
-
-    /**
-     * Registers a composite (entity) editor with the framework config service — a `compose(docs)`/`decompose(edited,docs)`
-     * pair over one or more documents. Call during initialization. See {@link ConfigService#registerEditor}.
-     *
-     * @method
-     * @param {string} editorKey
-     * @param {Object} definition
-     * @returns {TiWebAppManager} this (chainable)
-     * @public
-     */
-    registerConfigEditor( editorKey, definition ) {
-        configService.instance.registerEditor( editorKey, definition );
-        return this;
-    }
-
-    /**
-     * Used to clear the static file cache. This is useful for testing purposes to ensure that the web server is always serving fresh content.
-     *
-     * @method
-     * @public
-     */
-    clearStaticFileCache() {
-        this.#staticFileCache = {};
-    }
-
-    /**
-     * Sets the effective enabled authentication methods used to gate login-page provider buttons. The web server
-     * calls this at startup, after the auth manager has dropped any enabled-but-unconfigured OpenID providers.
-     *
-     * @method
-     * @param {string[]} methods
-     * @public
-     */
-    setEnabledAuthMethods( methods ) {
-        this.#enabledAuthMethods = Array.isArray( methods ) ? [ ...methods ] : [];
-    }
-
-    /**
-     * Optional HTML transformation hook.
-     * <br/>
-     * NOTE: Override in subclasses to add nonces or other dynamic data to outgoing HTML.
-     *
-     * @method
-     * @param {string} html
-     * @param {Object} [options]
-     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
-     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
-     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
-     * @param {string} [options.title] Optional title to replace the placeholder in the HTML.
-     * @returns {Promise<string>}
-     * @virtual
-     * @public
-     */
-    transformHtml( html, options = {} ) {
-        return new Promise( ( resolve, reject ) => {
-            let transformedHtml = String( html );
-
-            // Insert nonce in all placeholder locations. If nonce is not provided or is invalid, this will use an empty string instead to remove the placeholder:
-            const nonce = ( typeof options?.nonce === "string" && RE_CSP_NONCE.test( options?.nonce ) ) ? options?.nonce : "";
-            transformedHtml = transformedHtml.replaceAll( RE_NONCE_ATTR, nonce );
-            if ( options.isHome ) {
-                let htmxConfig = {
-                    inlineScriptNonce: nonce,
-                    inlineStyleNonce: nonce,
-                    allowEval: false,
-                    refreshOnHistoryMiss: true,
-                    historyCacheSize: 0
-                };
-                transformedHtml = transformedHtml.replace( RE_HTMX_CONFIG, JSON.stringify( htmxConfig ) );
-            }
-
-            const csrfToken = ( typeof options?.csrfToken === "string" ) ? options?.csrfToken : "";
-            transformedHtml = transformedHtml.replaceAll( RE_CSRF_ATTR, csrfToken );
-
-            transformedHtml = transformedHtml.replace( "{ti-title-placeholder}", options.title || "" );
-
-            // Gate login-page OpenID provider buttons to the effective enabled auth methods (no-op on other fragments).
-            transformedHtml = applyAuthMethodVisibility( transformedHtml, this.#enabledAuthMethods );
-
-            resolve( transformedHtml );
-        } );
-    }
-
-    /**
-     * Used to assemble the complete HTML view for the requested route, including nested HTML fragments.
-     *
-     * @method
-     * @param {TiSession} session
-     * @param {string[]} staticContentPaths
-     * @param {string} route
-     * @param {Object} [options]
-     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
-     * @param {boolean} [options.isPartial] Optional flag to indicate whether the requested route is a partial load of a fragment.
-     * @param {string} [options.view] Optional view name to load within this route.
-     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
-     * @returns {Promise<string>}
-     * @public
-     */
-    assembleHtmlView( session, staticContentPaths, route, options = {} ) {
-        return new Promise( ( resolve, reject ) => {
-            let fragment;
-            let getHtmlPromises = [];
-            let localOptions = ( options && typeof options === "object" ) ? { ...options } : {};
-
-            if ( route === "/" ) {
-                fragment = this.#fragments[ 'home' ];
-                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, { ...localOptions, isHome: true } ) );
-            } else if ( route === "/app/error" ) {
-                // TODO: This endpoint is for testing purposes only. Remove later.
-                return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_METHOD ) );
-            } else if ( route === "/app" || route === "/app/enter" ) {
-                fragment = ( session && session.user ) ? this.#fragments[ 'application-main' ] : this.#fragments[ 'login' ];
-                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
-            } else if ( route === "/not-found" ) {
-                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], { ...localOptions, isHome: true, title: this.#fragments[ 'not-found' ].title } ) );
-                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'not-found' ], localOptions ) );
-            } else {
-                fragment = this.#fragments[ options.view ];
-                if ( !fragment ) {
-                    // Abort execution if the requested view is not found:
-                    return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
-                } else {
-                    // This handles application refreshes from nested frames:
-                    if ( options.isPartial !== true ) {
-                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], {
-                            ...localOptions,
-                            isHome: true,
-                            title: fragment.title
-                        } ) );
-                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'application-main' ], localOptions ) );
-                    }
-                    getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
-                }
-            }
-
-            Promise.all( getHtmlPromises ).then( ( filesData ) => {
-                let assembledHtml = undefined;
-                filesData.forEach( ( fileData ) => {
-                    // There should always be at most one ti-nested-frame-placeholder element in each HTML fragment:
-                    assembledHtml = ( assembledHtml ) ? this.#replacePlaceholderElement( assembledHtml, TI_NESTED_FRAME_PLACEHOLDER, fileData ) : fileData;
-                } );
-                resolve( assembledHtml );
-            } ).catch( ( error ) => {
-                reject( exceptions.raise( error ) );
-            } );
-        } );
-    }
-
-    /**
-     * Used to process a request for a data resource.
-     *
-     * @method
-     * @param {TiSession} session
-     * @param {string} view
-     * @param {Object} [options]
-     * @returns {Promise<Object>}
-     * @virtual
-     * @public
-     */
-    processDataRequest( session, view, options = {} ) {
-        return new Promise( ( resolve, reject ) => {
-            if ( view === "config" ) {
-                resolve( {
-                    labels: localization.getAllLabels( session?.language ),
-                    auth: {
-                        isAuthenticated: Boolean( session && session.user )
-                    }
-                } );
-            } else {
-                reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { view: view } ) );
-            }
-        } );
-    }
-
-    /**
-     * Used to process an application service request.
-     *
-     * @method
-     * @param {TiSession} session
-     * @param {string} service
-     * @param {Object} params
-     * @returns {Promise<Object>}
-     * @virtual
-     * @public
-     */
-    processServiceRequest( session, service, params ) {
-        return new Promise( ( resolve, reject ) => {
-            reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { service: service } ) );
-        } );
-    }
-
-    /**
-     * Used to verify whether the current user has access to the requested resource. The default implementation gates
-     * HTML fragments by their declared `roles`: a fragment registered via {@link TiWebAppManager#addFragment} with a
-     * `roles` array is served only to sessions holding at least one of those roles (see {@link addFragment}); a
-     * fragment with no `roles` is public to any authenticated user. This makes role-restricted screens unreachable by
-     * direct URL, not merely hidden in the UI. Override in subclasses only to implement additional/alternative checks.
-     *
-     * @method
-     * @virtual
-     * @param {TiSession} session
-     * @param {Object} resource The fragment descriptor; its optional `resource.roles` lists the roles permitted to load it.
-     * @returns {Promise}
-     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (403) When the session holds none of the fragment's required roles.
-     * @public
-     */
-    verifyAccess( session, resource ) {
-        return new Promise( ( resolve, reject ) => {
-            const requiredRoles = ( resource && resource.roles ) ? resource.roles : null;
-            const userRoles = ( session && session.user && session.user.roles ) || [];
-            if ( authorization.isAccessAllowed( requiredRoles, userRoles ) ) {
-                return resolve();
-            }
-            reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_403 ) );
-        } );
-    }
-
-    /* Private interface */
-
-    /**
-     * Returns the HTML fragment for the requested route.
-     *
-     * @method
-     * @param {TiSession} session
-     * @param {string[]} staticContentPaths
-     * @param {Object} fragment
-     * @param {Object} [options]
-     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
-     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
-     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
-     * @returns {Promise<string>}
-     * @private
-     */
-    #getHtmlFragment( session, staticContentPaths, fragment, options = {} ) {
-        return new Promise( ( resolve, reject ) => {
-            this.verifyAccess( session, fragment ).then( () => {
-                return this.#locateStaticFile( staticContentPaths, fragment.path );
-            } ).then( ( fileData ) => {
-                return this.#replaceComponentPlaceholders( fileData, staticContentPaths, fragment.components );
-            } ).then( ( fileData ) => {
-                return this.transformHtml( fileData, { ...options, title: fragment.title || options.title } );
-            } ).then( ( fileData ) => {
-                resolve( fileData );
-            } ).catch( ( error ) => {
-                reject( exceptions.raise( error ) );
-            } );
-        } );
-    }
-
-    /**
-     * Attempts to locate the requested static file in the provided static content paths.
-     *
-     * @method
-     * @param {string[]} staticContentPaths A list of directories to search for static content. If sent as expected by the web server, the first item in the array should be the system default path.
-     * @param {string} filePath Relative path to the static file to locate.
-     * @returns {Promise<string>}
-     * @private
-     */
-    #locateStaticFile( staticContentPaths, filePath ) {
-        return new Promise( ( resolve, reject ) => {
-            if ( this.#staticFileCacheEnabled === true && this.#staticFileCache[ filePath ] !== undefined ) {
-                resolve( this.#staticFileCache[ filePath ] );
-            } else {
-                let fullFilePath;
-                // Search for the file in the static content paths in reverse order so that the default system path is checked last. This will ensure that
-                // any fragment overrides are loaded first (i.e., fragments with the same relative path):
-                for ( let idx = staticContentPaths.length - 1; idx >= 0; idx-- ) {
-                    const staticContentPath = staticContentPaths[ idx ];
-                    let potentialFilePath = path.join( staticContentPath, filePath );
-                    if ( fs.existsSync( potentialFilePath ) ) {
-                        fullFilePath = potentialFilePath;
-                        break;
-                    }
-                }
-
-                if ( fullFilePath !== undefined ) {
-                    fs.promises.readFile( fullFilePath, "utf8" ).then( ( fileData ) => {
-                        if ( this.#staticFileCacheEnabled === true ) {
-                            this.#staticFileCache[ filePath ] = fileData;
-                        }
-                        resolve( fileData );
-                    } ).catch( ( error ) => {
-                        reject( exceptions.raise( error ) );
-                    } );
-                } else {
-                    reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
-                }
-            }
-        } );
-    }
-
-    /**
-     * Used to replace the component placeholders in the HTML with the actual component HTML.
-     *
-     * @method
-     * @param {string} html
-     * @param {string[]} staticContentPaths
-     * @param {Array<string>} components
-     * @returns {Promise<string>}
-     * @private
-     */
-    #replaceComponentPlaceholders( html, staticContentPaths, components ) {
-        return new Promise( ( resolve, reject ) => {
-            if ( components === undefined || components.length === 0 ) {
-                resolve( html );
-            } else {
-                let transformedHtml = String( html );
-                let promises = [];
-                const componentData = {};
-                tools.arrayUniques( components ).forEach( ( component ) => {
-                    promises.push( this.#locateStaticFile( staticContentPaths, `fragments/components/${ component }.html` ).then( ( fileData ) => {
-                        componentData[ component ] = fileData;
-                    } ) );
-                } );
-
-                Promise.all( promises ).then( () => {
-                    components.forEach( ( component ) => {
-                        transformedHtml = this.#replacePlaceholderElement( transformedHtml, `ti-${ component }-placeholder`, componentData[ component ] );
-                    } );
-                    resolve( transformedHtml );
-                } ).catch( ( error ) => {
-                    reject( exceptions.raise( error ) );
-                } );
-            }
-        } );
-    }
-
-    /**
-     * Used to replace a placeholder element in the HTML with the provided replacement.
-     * <br/>
-     * The placeholder's attributes are exposed to the replacement HTML as `{ti-<attr-name>}` tokens, allowing the
-     * component template to consume initial data without changing its `x-data` factory.
-     * <br/>
-     * If the replacement HTML contains a `<ti-slot></ti-slot>` (or self-closing `<ti-slot/>`) marker, the placeholder's
-     * inner content replaces it precisely; otherwise, inner content is appended before the replacement's last closing
-     * tag (legacy behaviour) so existing components keep working.
-     *
-     * @method
-     * @param {string} html
-     * @param {string} tagName
-     * @param {string} replacement
-     * @returns {string}
-     * @private
-     */
-    #replacePlaceholderElement( html, tagName, replacement ) {
-        const start = html.indexOf( `<${ tagName }` );
-        if ( start === -1 ) {
-            return html;
-        }
-        const gt = html.indexOf( ">", start );
-        if ( gt === -1 ) {
-            return html;
-        }
-        // Tolerate whitespace(s) before '/>' and attributes on the tag:
-        let p = gt - 1;
-        while ( p > start && /\s/.test( html[ p ] ) ) p--;
-        const isSelfClosing = html[ p ] === "/";
-        let end;
-        let inner = "";
-        if ( isSelfClosing ) {
-            end = gt + 1;
-        } else {
-            const close = `</${ tagName }>`;
-            end = html.indexOf( close, gt + 1 );
-            if ( end === -1 ) {
-                return html;
-            }
-            inner = html.slice( gt + 1, end );
-            end += close.length;
-        }
-
-        // Substitute the placeholder's attributes as `{ti-<name>}` tokens inside the replacement HTML:
-        const placeholderAttributes = this.#parsePlaceholderAttributes( html.slice( start, gt + 1 ) );
-        let processedReplacement = replacement;
-        Object.keys( placeholderAttributes ).forEach( ( name ) => {
-            const value = placeholderAttributes[ name ];
-            const token = `{ti-${ name }}`;
-            // Use split/join for a literal replaceAll without regex escaping concerns:
-            processedReplacement = processedReplacement.split( token ).join( value );
-        } );
-
-        let replacementWithInner = processedReplacement;
-        const slotMatch = processedReplacement.match( /<ti-slot\b[^>]*>[\s\S]*?<\/ti-slot>|<ti-slot\b[^>]*\/>/ );
-        if ( slotMatch ) {
-            // If a slot marker exists, the placeholder's inner content (when present) replaces it. When inner is
-            // empty, the slot's own default content (between <ti-slot> and </ti-slot>) is kept by unwrapping it:
-            if ( inner ) {
-                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], inner );
-            } else {
-                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], ( match ) => {
-                    const defaultMatch = match.match( /<ti-slot\b[^>]*>([\s\S]*?)<\/ti-slot>/ );
-                    return defaultMatch ? defaultMatch[ 1 ] : "";
-                } );
-            }
-        } else if ( inner ) {
-            const insertAt = processedReplacement.lastIndexOf( "</" );
-            if ( insertAt !== -1 ) {
-                replacementWithInner = processedReplacement.slice( 0, insertAt ) + inner + processedReplacement.slice( insertAt );
-            } else {
-                replacementWithInner = processedReplacement + inner;
-            }
-        }
-
-        return html.slice( 0, start ) + replacementWithInner + html.slice( end );
-    }
-
-    /**
-     * Parses the attribute name/value pairs declared on a placeholder element's opening tag.
-     *
-     * @method
-     * @param {string} openingTag The full opening tag text, e.g. `<ti-foo-placeholder bar="baz">`.
-     * @returns {Object<string, string>}
-     * @private
-     */
-    #parsePlaceholderAttributes( openingTag ) {
-        const attributes = {};
-        // Strip the element name and the surrounding angle brackets so only the attribute string remains:
-        const trimmed = openingTag.replace( /^<[^\s>/]+/, "" ).replace( /\/?>\s*$/, "" );
-        const regex = /([a-zA-Z_][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g;
-        let match;
-        while ( ( match = regex.exec( trimmed ) ) !== null ) {
-            attributes[ match[ 1 ] ] = match[ 2 ] ?? match[ 3 ] ?? match[ 4 ] ?? "";
-        }
-        return attributes;
-    }
-
-}
-
-module.exports = TiWebAppManager;
-module.exports.applyAuthMethodVisibility = applyAuthMethodVisibility;
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+const exceptions = require( "@ti-engine/core/exceptions" );
+const tools = require( "@ti-engine/core/tools" );
+const localization = require( "@ti-engine/core/localization" );
+const path = require( "node:path" );
+const fs = require( "node:fs" );
+const configRegistry = require( "#config-registry" );
+const configService = require( "#config-service" );
+const authorization = require( "#authorization" );
+
+/** @import { TiSession } from "#definitions" */
+
+const RE_NONCE_ATTR = /\{ti-nonce-placeholder}/g;
+const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
+const RE_HTMX_CONFIG = /\{ti-htmx-config-placeholder}/g;
+const RE_CSP_NONCE = /^[A-Za-z0-9+/=_-]{16,}$/;
+const TI_NESTED_FRAME_PLACEHOLDER = "ti-nested-frame-placeholder";
+const OAUTH_METHODS = [ "openid-google", "openid-azure" ];
+const ALL_METHODS = [ "local", "openid-google", "openid-azure" ];
+const RE_AUTH_MARKERS = /<!--\/?ti-auth-(?:divider|social|none|method(?::[a-z-]+)?)-->/g;
+
+/**
+ * Removes every `<openMarker>…<closeMarker>` span (inclusive) from `html` in a single linear pass. The markers are
+ * matched as fixed strings via `indexOf`, so — unlike an `openMarker[\s\S]*?closeMarker` regular expression under a
+ * global replace — this cannot exhibit super-linear backtracking on hostile input containing many opening markers
+ * (CodeQL js/polynomial-redos). Matches the lazy-regex semantics: each opening marker pairs with the *next* closing
+ * marker after it. An opening marker with no matching closing marker is left untouched (the caller strips any stray
+ * markers afterwards with {@link RE_AUTH_MARKERS}).
+ *
+ * @param {string} html
+ * @param {string} openMarker
+ * @param {string} closeMarker
+ * @returns {string}
+ */
+function stripMarkerSpans( html, openMarker, closeMarker ) {
+    let result = "";
+    let cursor = 0;
+    for ( ; ; ) {
+        const open = html.indexOf( openMarker, cursor );
+        if ( open === -1 ) {
+            result += html.slice( cursor );
+            break;
+        }
+        const close = html.indexOf( closeMarker, open + openMarker.length );
+        if ( close === -1 ) {
+            result += html.slice( cursor );
+            break;
+        }
+        result += html.slice( cursor, open );
+        cursor = close + closeMarker.length;
+    }
+    return result;
+}
+
+/**
+ * Gates the login-page authentication markup to the effective enabled methods. The login fragment delimits blocks
+ * with HTML-comment markers: `<!--ti-auth-method:METHOD-->…<!--/ti-auth-method-->` around each method's control
+ * (the `local` credentials form and each OpenID provider button), `<!--ti-auth-divider-->…<!--/ti-auth-divider-->`
+ * around the "or continue with" separator, `<!--ti-auth-social-->…<!--/ti-auth-social-->` around the SSO button
+ * group, and `<!--ti-auth-none-->…<!--/ti-auth-none-->` around a "no method configured" fallback. It removes the
+ * block for any method that is not enabled, drops the social group when no SSO provider is enabled, shows the
+ * divider only when a local form AND at least one SSO provider are both present, and shows the fallback only when
+ * nothing is enabled. Any remaining markers are stripped so clean HTML ships. Fragments without these markers
+ * (every non-login fragment) are returned unchanged.
+ *
+ * @param {string} html
+ * @param {string[]} [enabledMethods] The effective enabled authentication methods.
+ * @returns {string}
+ */
+function applyAuthMethodVisibility( html, enabledMethods ) {
+    let result = String( html );
+    const enabled = Array.isArray( enabledMethods ) ? enabledMethods : [];
+    const localEnabled = enabled.includes( "local" );
+    const anyOAuth = OAUTH_METHODS.some( ( method ) => enabled.includes( method ) );
+
+    // Drop the block for each authentication method that is not enabled.
+    ALL_METHODS.forEach( ( method ) => {
+        if ( !enabled.includes( method ) ) {
+            result = stripMarkerSpans( result, "<!--ti-auth-method:" + method + "-->", "<!--/ti-auth-method-->" );
+        }
+    } );
+
+    // Drop the SSO button group when no OpenID provider is enabled.
+    if ( !anyOAuth ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-social-->", "<!--/ti-auth-social-->" );
+    }
+
+    // Show the "or continue with" divider only when BOTH a local form and at least one SSO provider are present.
+    if ( !( localEnabled && anyOAuth ) ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-divider-->", "<!--/ti-auth-divider-->" );
+    }
+
+    // Show the "no method configured" fallback only when nothing is enabled.
+    if ( localEnabled || anyOAuth ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-none-->", "<!--/ti-auth-none-->" );
+    }
+
+    return result.replace( RE_AUTH_MARKERS, "" );
+}
+
+/**
+ * A generic web application manager that handles the rendering and behavior of web application views. It is designed to be extended by specific web application
+ * managers for each web application you want to implement with the ti-engine web framework.
+ * <br/>
+ * NOTE: You should not instantiate this class directly. Instead, extend it and override the abstract methods as needed. Additionally, you should configure your
+ * ti-engine web server 'TiWebApplicationConfig' settings by specifying the 'classPath' that corresponds to your web application manager. The path should be
+ * relative to the intended process's working directory.
+ *
+ * @class TiWebAppManager
+ * @abstract
+ * @public
+ */
+class TiWebAppManager {
+
+    #webAppIdentifier;
+    #fragments = {};
+    #staticFileCache = {};
+    #staticFileCacheEnabled;
+    #enabledAuthMethods = [];
+
+    /**
+     * @constructor
+     * @param {string} identifier The identifier for this web application. Should be unique and recognizable.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor( identifier ) {
+        // Make sure this abstract class cannot be instantiated:
+        if ( new.target === TiWebAppManager ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+
+        this.#webAppIdentifier = identifier;
+        this.#staticFileCacheEnabled = ( process.env.TI_WEB_APP_STATIC_CACHE_DISABLED !== "true" );
+
+        // Define the default HTML fragments for the application:
+        this.#fragments[ 'home' ] = {
+            path: "index.html",
+            components: [ "component-notification-bar" ]
+        };
+        this.#fragments[ 'application-main' ] = {
+            title: "Application",
+            path: "fragments/frame-application.html",
+            components: [ "component-topbar", "component-sidebar", "component-notification-bar", "component-sidebar-flyout" ]
+        };
+        this.#fragments[ 'login' ] = {
+            title: "Login",
+            path: "fragments/frame-login.html"
+        };
+        this.#fragments[ 'dashboard' ] = {
+            title: "Dashboard",
+            path: "fragments/frame-dashboard.html"
+        };
+        this.#fragments[ 'administration' ] = {
+            title: "Administration",
+            path: "fragments/frame-administration.html"
+        };
+        this.#fragments[ 'profile' ] = {
+            title: "Profile",
+            path: "fragments/frame-profile.html"
+        };
+        this.#fragments[ 'not-found' ] = {
+            title: "Not Found",
+            path: "fragments/frame-not-found.html"
+        };
+    }
+
+    /* Public interface */
+
+    /**
+     * Returns the identifier for this web application.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get webAppIdentifier() {
+        return this.#webAppIdentifier;
+    }
+
+    /**
+     * Adds a new HTML fragment to the web application.
+     * <br/>
+     * NOTE: This method should only be called during the initialization phase of your web application manager.
+     *
+     * @method
+     * @param {string} identifier
+     * @param {Object} fragment The fragment descriptor (`{ title, path, components }`). May also carry an optional
+     * `roles` array (`Array<string|number>`): when present, the default {@link TiWebAppManager#verifyAccess} serves
+     * the fragment only to sessions holding at least one of those roles; omit it (or leave empty) for a public screen.
+     * @throws {TiException.E_GEN_UNALLOWED_OVERRIDE} If a fragment with the same identifier already exists.
+     * @public
+     */
+    addFragment( identifier, fragment ) {
+        if ( this.#fragments[ identifier ] === undefined ) {
+            this.#fragments[ identifier ] = fragment;
+        } else {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_UNALLOWED_OVERRIDE, { identifier: identifier } );
+        }
+    }
+
+    /**
+     * Registers an editable configuration document with the framework config registry (JSON Schema + semantic
+     * validators + default value + editor metadata). Call during initialization. See {@link ConfigRegistry#register}.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigDocument( configKey, definition ) {
+        configRegistry.instance.register( configKey, definition );
+        return this;
+    }
+
+    /**
+     * Registers a JSON Schema that is referenced (via `$ref`) by config-document schemas but is not itself a document.
+     *
+     * @method
+     * @param {Object} schema
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigSchema( schema ) {
+        configRegistry.instance.addSchema( schema );
+        return this;
+    }
+
+    /**
+     * Registers a composite (entity) editor with the framework config service — a `compose(docs)`/`decompose(edited,docs)`
+     * pair over one or more documents. Call during initialization. See {@link ConfigService#registerEditor}.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigEditor( editorKey, definition ) {
+        configService.instance.registerEditor( editorKey, definition );
+        return this;
+    }
+
+    /**
+     * Used to clear the static file cache. This is useful for testing purposes to ensure that the web server is always serving fresh content.
+     *
+     * @method
+     * @public
+     */
+    clearStaticFileCache() {
+        this.#staticFileCache = {};
+    }
+
+    /**
+     * Sets the effective enabled authentication methods used to gate login-page provider buttons. The web server
+     * calls this at startup, after the auth manager has dropped any enabled-but-unconfigured OpenID providers.
+     *
+     * @method
+     * @param {string[]} methods
+     * @public
+     */
+    setEnabledAuthMethods( methods ) {
+        this.#enabledAuthMethods = Array.isArray( methods ) ? [ ...methods ] : [];
+    }
+
+    /**
+     * Optional HTML transformation hook.
+     * <br/>
+     * NOTE: Override in subclasses to add nonces or other dynamic data to outgoing HTML.
+     *
+     * @method
+     * @param {string} html
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @param {string} [options.title] Optional title to replace the placeholder in the HTML.
+     * @returns {Promise<string>}
+     * @virtual
+     * @public
+     */
+    transformHtml( html, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            let transformedHtml = String( html );
+
+            // Insert nonce in all placeholder locations. If nonce is not provided or is invalid, this will use an empty string instead to remove the placeholder:
+            const nonce = ( typeof options?.nonce === "string" && RE_CSP_NONCE.test( options?.nonce ) ) ? options?.nonce : "";
+            transformedHtml = transformedHtml.replaceAll( RE_NONCE_ATTR, nonce );
+            if ( options.isHome ) {
+                let htmxConfig = {
+                    inlineScriptNonce: nonce,
+                    inlineStyleNonce: nonce,
+                    allowEval: false,
+                    refreshOnHistoryMiss: true,
+                    historyCacheSize: 0
+                };
+                transformedHtml = transformedHtml.replace( RE_HTMX_CONFIG, JSON.stringify( htmxConfig ) );
+            }
+
+            const csrfToken = ( typeof options?.csrfToken === "string" ) ? options?.csrfToken : "";
+            transformedHtml = transformedHtml.replaceAll( RE_CSRF_ATTR, csrfToken );
+
+            transformedHtml = transformedHtml.replace( "{ti-title-placeholder}", options.title || "" );
+
+            // Gate login-page OpenID provider buttons to the effective enabled auth methods (no-op on other fragments).
+            transformedHtml = applyAuthMethodVisibility( transformedHtml, this.#enabledAuthMethods );
+
+            resolve( transformedHtml );
+        } );
+    }
+
+    /**
+     * Used to assemble the complete HTML view for the requested route, including nested HTML fragments.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string[]} staticContentPaths
+     * @param {string} route
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isPartial] Optional flag to indicate whether the requested route is a partial load of a fragment.
+     * @param {string} [options.view] Optional view name to load within this route.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @returns {Promise<string>}
+     * @public
+     */
+    assembleHtmlView( session, staticContentPaths, route, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            let fragment;
+            let getHtmlPromises = [];
+            let localOptions = ( options && typeof options === "object" ) ? { ...options } : {};
+
+            if ( route === "/" ) {
+                fragment = this.#fragments[ 'home' ];
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, { ...localOptions, isHome: true } ) );
+            } else if ( route === "/app/error" ) {
+                // TODO: This endpoint is for testing purposes only. Remove later.
+                return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_METHOD ) );
+            } else if ( route === "/app" || route === "/app/enter" ) {
+                fragment = ( session && session.user ) ? this.#fragments[ 'application-main' ] : this.#fragments[ 'login' ];
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
+            } else if ( route === "/not-found" ) {
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], { ...localOptions, isHome: true, title: this.#fragments[ 'not-found' ].title } ) );
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'not-found' ], localOptions ) );
+            } else {
+                fragment = this.#fragments[ options.view ];
+                if ( !fragment ) {
+                    // Abort execution if the requested view is not found:
+                    return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
+                } else {
+                    // This handles application refreshes from nested frames:
+                    if ( options.isPartial !== true ) {
+                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], {
+                            ...localOptions,
+                            isHome: true,
+                            title: fragment.title
+                        } ) );
+                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'application-main' ], localOptions ) );
+                    }
+                    getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
+                }
+            }
+
+            Promise.all( getHtmlPromises ).then( ( filesData ) => {
+                let assembledHtml = undefined;
+                filesData.forEach( ( fileData ) => {
+                    // There should always be at most one ti-nested-frame-placeholder element in each HTML fragment:
+                    assembledHtml = ( assembledHtml ) ? this.#replacePlaceholderElement( assembledHtml, TI_NESTED_FRAME_PLACEHOLDER, fileData ) : fileData;
+                } );
+                resolve( assembledHtml );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to process a request for a data resource.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} view
+     * @param {Object} [options]
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processDataRequest( session, view, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( view === "config" ) {
+                resolve( {
+                    labels: localization.getAllLabels( session?.language ),
+                    auth: {
+                        isAuthenticated: Boolean( session && session.user )
+                    }
+                } );
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { view: view } ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to process an application service request.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} service
+     * @param {Object} params
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processServiceRequest( session, service, params ) {
+        return new Promise( ( resolve, reject ) => {
+            reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { service: service } ) );
+        } );
+    }
+
+    /**
+     * Used to verify whether the current user has access to the requested resource. The default implementation gates
+     * HTML fragments by their declared `roles`: a fragment registered via {@link TiWebAppManager#addFragment} with a
+     * `roles` array is served only to sessions holding at least one of those roles (see {@link addFragment}); a
+     * fragment with no `roles` is public to any authenticated user. This makes role-restricted screens unreachable by
+     * direct URL, not merely hidden in the UI. Override in subclasses only to implement additional/alternative checks.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} resource The fragment descriptor; its optional `resource.roles` lists the roles permitted to load it.
+     * @returns {Promise}
+     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (403) When the session holds none of the fragment's required roles.
+     * @public
+     */
+    verifyAccess( session, resource ) {
+        return new Promise( ( resolve, reject ) => {
+            const requiredRoles = ( resource && resource.roles ) ? resource.roles : null;
+            const userRoles = ( session && session.user && session.user.roles ) || [];
+            if ( authorization.isAccessAllowed( requiredRoles, userRoles ) ) {
+                return resolve();
+            }
+            reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_403 ) );
+        } );
+    }
+
+    /* Private interface */
+
+    /**
+     * Returns the HTML fragment for the requested route.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string[]} staticContentPaths
+     * @param {Object} fragment
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @returns {Promise<string>}
+     */
+    #getHtmlFragment( session, staticContentPaths, fragment, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            this.verifyAccess( session, fragment ).then( () => {
+                return this.#locateStaticFile( staticContentPaths, fragment.path );
+            } ).then( ( fileData ) => {
+                return this.#replaceComponentPlaceholders( fileData, staticContentPaths, fragment.components );
+            } ).then( ( fileData ) => {
+                return this.transformHtml( fileData, { ...options, title: fragment.title || options.title } );
+            } ).then( ( fileData ) => {
+                resolve( fileData );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Attempts to locate the requested static file in the provided static content paths.
+     *
+     * @method
+     * @param {string[]} staticContentPaths A list of directories to search for static content. If sent as expected by the web server, the first item in the array should be the system default path.
+     * @param {string} filePath Relative path to the static file to locate.
+     * @returns {Promise<string>}
+     */
+    #locateStaticFile( staticContentPaths, filePath ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#staticFileCacheEnabled === true && this.#staticFileCache[ filePath ] !== undefined ) {
+                resolve( this.#staticFileCache[ filePath ] );
+            } else {
+                let fullFilePath;
+                // Search for the file in the static content paths in reverse order so that the default system path is checked last. This will ensure that
+                // any fragment overrides are loaded first (i.e., fragments with the same relative path):
+                for ( let idx = staticContentPaths.length - 1; idx >= 0; idx-- ) {
+                    const staticContentPath = staticContentPaths[ idx ];
+                    let potentialFilePath = path.join( staticContentPath, filePath );
+                    if ( fs.existsSync( potentialFilePath ) ) {
+                        fullFilePath = potentialFilePath;
+                        break;
+                    }
+                }
+
+                if ( fullFilePath !== undefined ) {
+                    fs.promises.readFile( fullFilePath, "utf8" ).then( ( fileData ) => {
+                        if ( this.#staticFileCacheEnabled === true ) {
+                            this.#staticFileCache[ filePath ] = fileData;
+                        }
+                        resolve( fileData );
+                    } ).catch( ( error ) => {
+                        reject( exceptions.raise( error ) );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
+                }
+            }
+        } );
+    }
+
+    /**
+     * Used to replace the component placeholders in the HTML with the actual component HTML.
+     *
+     * @method
+     * @param {string} html
+     * @param {string[]} staticContentPaths
+     * @param {Array<string>} components
+     * @returns {Promise<string>}
+     */
+    #replaceComponentPlaceholders( html, staticContentPaths, components ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( components === undefined || components.length === 0 ) {
+                resolve( html );
+            } else {
+                let transformedHtml = String( html );
+                let promises = [];
+                const componentData = {};
+                tools.arrayUniques( components ).forEach( ( component ) => {
+                    promises.push( this.#locateStaticFile( staticContentPaths, `fragments/components/${ component }.html` ).then( ( fileData ) => {
+                        componentData[ component ] = fileData;
+                    } ) );
+                } );
+
+                Promise.all( promises ).then( () => {
+                    components.forEach( ( component ) => {
+                        transformedHtml = this.#replacePlaceholderElement( transformedHtml, `ti-${ component }-placeholder`, componentData[ component ] );
+                    } );
+                    resolve( transformedHtml );
+                } ).catch( ( error ) => {
+                    reject( exceptions.raise( error ) );
+                } );
+            }
+        } );
+    }
+
+    /**
+     * Used to replace a placeholder element in the HTML with the provided replacement.
+     * <br/>
+     * The placeholder's attributes are exposed to the replacement HTML as `{ti-<attr-name>}` tokens, allowing the
+     * component template to consume initial data without changing its `x-data` factory.
+     * <br/>
+     * If the replacement HTML contains a `<ti-slot></ti-slot>` (or self-closing `<ti-slot/>`) marker, the placeholder's
+     * inner content replaces it precisely; otherwise, inner content is appended before the replacement's last closing
+     * tag (legacy behaviour) so existing components keep working.
+     *
+     * @method
+     * @param {string} html
+     * @param {string} tagName
+     * @param {string} replacement
+     * @returns {string}
+     */
+    #replacePlaceholderElement( html, tagName, replacement ) {
+        const start = html.indexOf( `<${ tagName }` );
+        if ( start === -1 ) {
+            return html;
+        }
+        const gt = html.indexOf( ">", start );
+        if ( gt === -1 ) {
+            return html;
+        }
+        // Tolerate whitespace(s) before '/>' and attributes on the tag:
+        let p = gt - 1;
+        while ( p > start && /\s/.test( html[ p ] ) ) p--;
+        const isSelfClosing = html[ p ] === "/";
+        let end;
+        let inner = "";
+        if ( isSelfClosing ) {
+            end = gt + 1;
+        } else {
+            const close = `</${ tagName }>`;
+            end = html.indexOf( close, gt + 1 );
+            if ( end === -1 ) {
+                return html;
+            }
+            inner = html.slice( gt + 1, end );
+            end += close.length;
+        }
+
+        // Substitute the placeholder's attributes as `{ti-<name>}` tokens inside the replacement HTML:
+        const placeholderAttributes = this.#parsePlaceholderAttributes( html.slice( start, gt + 1 ) );
+        let processedReplacement = replacement;
+        Object.keys( placeholderAttributes ).forEach( ( name ) => {
+            const value = placeholderAttributes[ name ];
+            const token = `{ti-${ name }}`;
+            // Use split/join for a literal replaceAll without regex escaping concerns:
+            processedReplacement = processedReplacement.split( token ).join( value );
+        } );
+
+        let replacementWithInner = processedReplacement;
+        const slotMatch = processedReplacement.match( /<ti-slot\b[^>]*>[\s\S]*?<\/ti-slot>|<ti-slot\b[^>]*\/>/ );
+        if ( slotMatch ) {
+            // If a slot marker exists, the placeholder's inner content (when present) replaces it. When inner is
+            // empty, the slot's own default content (between <ti-slot> and </ti-slot>) is kept by unwrapping it:
+            if ( inner ) {
+                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], inner );
+            } else {
+                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], ( match ) => {
+                    const defaultMatch = match.match( /<ti-slot\b[^>]*>([\s\S]*?)<\/ti-slot>/ );
+                    return defaultMatch ? defaultMatch[ 1 ] : "";
+                } );
+            }
+        } else if ( inner ) {
+            const insertAt = processedReplacement.lastIndexOf( "</" );
+            if ( insertAt !== -1 ) {
+                replacementWithInner = processedReplacement.slice( 0, insertAt ) + inner + processedReplacement.slice( insertAt );
+            } else {
+                replacementWithInner = processedReplacement + inner;
+            }
+        }
+
+        return html.slice( 0, start ) + replacementWithInner + html.slice( end );
+    }
+
+    /**
+     * Parses the attribute name/value pairs declared on a placeholder element's opening tag.
+     *
+     * @method
+     * @param {string} openingTag The full opening tag text, e.g. `<ti-foo-placeholder bar="baz">`.
+     * @returns {Object<string, string>}
+     */
+    #parsePlaceholderAttributes( openingTag ) {
+        const attributes = {};
+        // Strip the element name and the surrounding angle brackets so only the attribute string remains:
+        const trimmed = openingTag.replace( /^<[^\s>/]+/, "" ).replace( /\/?>\s*$/, "" );
+        const regex = /([a-zA-Z_][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g;
+        let match;
+        while ( ( match = regex.exec( trimmed ) ) !== null ) {
+            attributes[ match[ 1 ] ] = match[ 2 ] ?? match[ 3 ] ?? match[ 4 ] ?? "";
+        }
+        return attributes;
+    }
+
+}
+
+module.exports = TiWebAppManager;
+TiWebAppManager.applyAuthMethodVisibility = applyAuthMethodVisibility;