@stone-js/use-react 0.1.0

package/dist/index.js

@@ -0,0 +1,1859 @@
+import { isNotEmpty, isEmpty, InitializationError, isMetaClassModule, isMetaFactoryModule, isFunctionModule, isObjectLikeModule, isFunction, Logger, hasMetadata, getMetadata, isMatchedAdapter, mergeBlueprints, stoneBlueprint, classDecoratorLegacyWrapper, setMetadata, methodDecoratorLegacyWrapper, addMetadata, LIFECYCLE_HOOK_KEY, addBlueprint } from '@stone-js/core';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { renderToString } from 'react-dom/server';
+import { createContext, StrictMode, useContext, useState, useEffect } from 'react';
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { OutgoingHttpResponse, RedirectResponse, MetaStaticFileMiddleware, MetaCompressionMiddleware } from '@stone-js/http-core';
+import { OutgoingBrowserResponse, RedirectBrowserResponse } from '@stone-js/browser-core';
+import { Config } from '@stone-js/config';
+import { GET, NAVIGATION_EVENT, NODE_CONSOLE_PLATFORM, Router, RouteEvent } from '@stone-js/router';
+import { BROWSER_PLATFORM } from '@stone-js/browser-adapter';
+
+/**
+  * Stone DOM Attribute.
+  */
+const STONE_DOM_ATTR = 'data-stone-head';
+/**
+ * Apply meta tags to the document document.head.
+ *
+ * @param document - The document object.
+ * @param meta - The meta tag descriptor.
+ */
+const applyMeta = (document, meta) => {
+    const metaProp = isNotEmpty(meta.property) ? `meta[property="${meta.property}"]` : null;
+    const selector = isNotEmpty(meta.name) ? `meta[name="${meta.name}"]` : metaProp;
+    if (isEmpty(selector))
+        return;
+    const existing = document.head.querySelector(`${selector}[${STONE_DOM_ATTR}]`);
+    if (isNotEmpty(existing)) {
+        if (existing.content !== meta.content) {
+            existing.content = meta.content;
+        }
+    }
+    else {
+        const el = document.createElement('meta');
+        if (isNotEmpty(meta.name))
+            el.setAttribute('name', meta.name);
+        if (isNotEmpty(meta.property))
+            el.setAttribute('property', meta.property);
+        el.setAttribute('content', meta.content);
+        el.setAttribute(STONE_DOM_ATTR, '');
+        document.head.appendChild(el);
+    }
+};
+/**
+ * Apply link tags to the document document.head.
+ *
+ * @param document - The document object.
+ * @param link - The link tag descriptor.
+ */
+const applyLink = (document, link) => {
+    const selector = `link[rel="${link.rel}"][href="${link.href}"][${STONE_DOM_ATTR}]`;
+    const existing = document.head.querySelector(selector);
+    if (existing != null) {
+        let needsUpdate = false;
+        for (const [key, value] of Object.entries(link)) {
+            if (existing.getAttribute(key) !== value) {
+                needsUpdate = true;
+                break;
+            }
+        }
+        if (needsUpdate) {
+            for (const [key, value] of Object.entries(link)) {
+                existing.setAttribute(key, value);
+            }
+            existing.setAttribute(STONE_DOM_ATTR, '');
+        }
+    }
+    else {
+        const el = document.createElement('link');
+        for (const [key, value] of Object.entries(link)) {
+            el.setAttribute(key, value);
+        }
+        el.setAttribute(STONE_DOM_ATTR, '');
+        document.head.appendChild(el);
+    }
+};
+/**
+ * Update attributes of an HTML element.
+ *
+ * @param el - The HTML element to update.
+ * @param attrs - The attributes to set on the element.
+ */
+const updateAttributes = (el, attrs) => {
+    for (const [key, value] of Object.entries(attrs)) {
+        if (typeof value === 'boolean') {
+            value ? el.setAttribute(key, '') : el.removeAttribute(key);
+        }
+        else {
+            el.setAttribute(key, String(value));
+        }
+    }
+    el.setAttribute(STONE_DOM_ATTR, '');
+};
+/**
+ * Check if an element needs attribute updates.
+ *
+ * @param el - The HTML element to check.
+ * @param attrs - The attributes to compare against the element's current attributes.
+ * @returns True if any attribute needs updating, false otherwise.
+ */
+const needsAttributeUpdate = (el, attrs) => {
+    return Object.entries(attrs).some(([key, value]) => {
+        const attr = el.getAttribute(key);
+        return typeof value === 'boolean' ? attr !== '' : attr !== String(value);
+    });
+};
+/**
+ * Apply script tags to the document.head.
+ *
+ * @param document - The document object.
+ * @param script - The script tag descriptor.
+ */
+const applyScript = (document, script) => {
+    const selector = `script[src="${script.src}"][${STONE_DOM_ATTR}]`;
+    const existing = document.head.querySelector(selector);
+    if (existing != null) {
+        if (needsAttributeUpdate(existing, script)) {
+            updateAttributes(existing, script);
+        }
+    }
+    else {
+        const el = document.createElement('script');
+        updateAttributes(el, script);
+        document.head.appendChild(el);
+    }
+};
+/**
+ * Apply style tags to the document document.head.
+ *
+ * @param document - The document object.
+ * @param style - The style tag descriptor.
+ */
+const applyStyle = (document, style) => {
+    const existing = [...document.head.querySelectorAll(`style[${STONE_DOM_ATTR}]`)]
+        .find(s => s.textContent === style.content);
+    if (existing == null) {
+        const el = document.createElement('style');
+        if (isNotEmpty(style.type))
+            el.setAttribute('type', style.type);
+        if (isNotEmpty(style.media))
+            el.setAttribute('media', style.media);
+        el.textContent = style.content;
+        el.setAttribute(STONE_DOM_ATTR, '');
+        document.head.appendChild(el);
+    }
+};
+/**
+ * Apply the head context to the document document.head.
+ *
+ * @param document - The document object.
+ * @param context - The head context containing meta, link, script, and style descriptors.
+ */
+const applyHeadContextToDom = (document, context) => {
+    if (isNotEmpty(context.title) && document.title !== context.title) {
+        document.title = context.title;
+    }
+    if (isNotEmpty(context.description)) {
+        context.metas = context.metas ?? [];
+        context.metas.push({
+            name: 'description',
+            content: context.description
+        });
+    }
+    context.metas?.forEach(v => applyMeta(document, v));
+    context.links?.forEach(v => applyLink(document, v));
+    context.styles?.forEach(v => applyStyle(document, v));
+    context.scripts?.forEach(v => applyScript(document, v));
+};
+/**
+ * Escape HTML special characters in a string.
+ *
+ * @param input - The input string to escape.
+ * @returns The escaped string.
+ */
+const escapeHtml = (input) => input
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/'/g, ''')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+/**
+ * Escape HTML special characters in a string.
+ *
+ * @param context - The head context containing meta, link, script, and style descriptors.
+ * @param html - The HTML string to escape.
+ * @returns The escaped string.
+ */
+const applyHeadContextToHtmlString = (context, html) => {
+    if (isEmpty(context) || isEmpty(html))
+        return html;
+    // Replace the existing <title> tag with the new title (if provided)
+    if (isNotEmpty(context.title)) {
+        html = html.replace(/<title>.*?<\/title>/i, `<title>${escapeHtml(context.title)}</title>`);
+    }
+    // Build all additional head elements to insert into <!--app-head-->
+    const parts = [];
+    // Meta tags
+    context.metas?.forEach((meta) => {
+        const attrs = Object.entries(meta)
+            .map(([key, value]) => `${key}="${escapeHtml(value)}"`)
+            .join(' ');
+        parts.push(`<meta ${attrs}>`);
+    });
+    // Link tags
+    context.links?.forEach((link) => {
+        const attrs = Object.entries(link)
+            .map(([key, value]) => `${key}="${escapeHtml(String(value))}"`)
+            .join(' ');
+        parts.push(`<link ${attrs}>`);
+    });
+    // Script tags
+    context.scripts?.forEach((script) => {
+        const getKeyValue = (key, value) => isNotEmpty(value) ? `${key}` : '';
+        const attrs = Object.entries(script)
+            .map(([key, value]) => typeof value === 'boolean'
+            ? getKeyValue(key, value)
+            : `${key}="${escapeHtml(String(value))}"`)
+            .filter(Boolean)
+            .join(' ');
+        parts.push(`<script ${attrs}></script>`);
+    });
+    // Style tags
+    context.styles?.forEach((style) => {
+        const attrs = Object.entries(style)
+            .filter(([key]) => key !== 'content')
+            .map(([key, value]) => `${key}="${escapeHtml(String(value))}"`)
+            .join(' ');
+        const content = escapeHtml(style.content);
+        parts.push(`<style ${attrs}>${content}</style>`);
+    });
+    // Inject generated tags into the placeholder
+    const headString = parts.join('\n').concat('\n<!--app-head-->');
+    return html.replace('<!--app-head-->', headString);
+};
+
+/**
+ * Constants for the Stone SNAPSHOT
+ */
+const STONE_SNAPSHOT = '__STONE_SNAPSHOT__';
+/**
+ * Constants for the Stone Page Event Outlet
+ */
+const STONE_PAGE_EVENT_OUTLET = 'stone:inject:react-page:outlet';
+
+/**
+ * Stone context.
+ * Usefull to pass data to the components.
+ */
+const StoneContext = createContext({});
+
+/**
+ * Provides a scoped `StoneContext` for its children within a strict mode.
+ *
+ * - Wraps content in `React.StrictMode` for enhanced debugging.
+ * - Supplies a `StoneContext.Provider` to get access to the event, data and container.
+ *
+ * This component ensures that all child components have access to the provided
+ * context within a Stone.js application.
+ *
+ * @param options - The options to create the Stone Page.
+ * @returns The Stone Page component.
+ */
+const StonePage = ({ context, children }) => {
+    return (jsx(StrictMode, { children: jsx(StoneContext.Provider, { value: context, children: children }) }));
+};
+
+/**
+ * Stone Error.
+ */
+const StoneError = () => {
+    return (jsxs(Fragment, { children: [jsx("h1", { children: "An error occured" }), jsx("p", { children: "Sorry, something went wrong." })] }));
+};
+
+/**
+ * Custom error for react operations.
+ */
+class UseReactError extends InitializationError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'UseReactError';
+    }
+}
+
+/**
+ * Build the React application for the current route.
+ * Or for the main handler if the route is not defined.
+ *
+ * @param event - ReactIncomingEvent
+ * @param container - Service Container
+ * @param component - The component response.
+ * @param layout - The layout response.
+ * @param data - The data to pass to the component.
+ * @returns The resolved ReactNode.
+ */
+const buildAppComponent = async (event, container, component, layout, data, statusCode, error) => {
+    const componentElement = await buildPageComponent(event, container, component, data, statusCode, error);
+    const layoutElement = await buildLayoutComponent(container, componentElement, layout);
+    const context = { event, container, data };
+    const children = layoutElement ?? componentElement;
+    return jsx(StonePage, { context, children });
+};
+/**
+ * Get response layout in the current route for mutli pages application.
+ * Or get it from the blueprint configuration for single page application.
+ * Or get the default layout defined by the user.
+ * If not defined, return undefined.
+ *
+ * @param container - Service Container.
+ * @param children - The children to render.
+ * @param layoutName - The layout name.
+ * @returns The resolved layout element.
+ */
+const buildLayoutComponent = async (container, children, layoutName) => {
+    const metavalue = container
+        .make('blueprint')
+        .get(`stone.useReact.layout.${String(layoutName)}`);
+    const handler = await resolveComponent(container, metavalue);
+    const componentType = handler?.render.bind(handler);
+    if (componentType !== undefined) {
+        return jsx(componentType, { container, children, 'data-layout': layoutName });
+    }
+};
+/**
+ * Get response component in the current route.
+ * If not defined, return an empty object.
+ *
+ * @param event - ReactIncomingEvent
+ * @param container - Service Container
+ * @param component - The component response.
+ * @param data - The data to pass to the component.
+ * @param statusCode - The status code of the error.
+ * @param error - The error object.
+ * @returns The resolved component element.
+ */
+const buildPageComponent = (event, container, component, data, statusCode, error) => {
+    if (component !== undefined) {
+        return jsx(component, { event, container, data, statusCode, error });
+    }
+    return jsx('div', {});
+};
+/**
+ * Get adapter error component.
+ *
+ * This error handler is different from the kernel error handler.
+ * Because there is no container at adapter level.
+ *
+ * @param blueprint - The blueprint.
+ * @param context - The context of the adapter.
+ * @param statusCode - The status code of the error.
+ * @param error - The error object.
+ * @returns The resolved layout element.
+ */
+const buildAdapterErrorComponent = async (blueprint, context, statusCode, error) => {
+    const handlerMeta = blueprint.get(`stone.useReact.adapterErrorPages.${String(error?.name ?? 'default')}`);
+    const handlerMetavalue = await resolveLazyComponent(handlerMeta);
+    const layoutMetavalue = await resolveLazyComponent(blueprint.get(`stone.useReact.layout.${String(handlerMeta?.layout)}`));
+    let layoutHandler;
+    let handler;
+    if (isMetaClassModule(handlerMetavalue)) {
+        handler = new handlerMetavalue.module.prototype.constructor({ blueprint });
+    }
+    else if (isMetaFactoryModule(handlerMetavalue)) {
+        handler = handlerMetavalue.module({ blueprint });
+    }
+    if (isMetaClassModule(layoutMetavalue)) {
+        layoutHandler = new layoutMetavalue.module.prototype.constructor({ blueprint });
+    }
+    else if (isMetaFactoryModule(layoutMetavalue)) {
+        layoutHandler = layoutMetavalue.module({ blueprint });
+    }
+    await handler?.handle?.(error, context);
+    const componentType = handler?.render.bind(handler);
+    const layoutType = layoutHandler?.render.bind(layoutHandler);
+    if (componentType !== undefined && layoutType !== undefined) {
+        const children = jsx(componentType, { blueprint, error, statusCode });
+        return jsx(layoutType, { blueprint, children });
+    }
+    else if (componentType !== undefined) {
+        return jsx(componentType, { blueprint, error, statusCode });
+    }
+    else {
+        return jsx(StoneError, { blueprint, error, statusCode });
+    }
+};
+/**
+ * Resolve the event handler for the component.
+ *
+ * Can also resolve dynamically loaded components.
+ *
+ * @param container - The service container.
+ * @param metaComponent - The meta component event handler.
+ * @returns The resolved element type.
+ */
+const resolveComponent = async (container, metaComponent) => {
+    metaComponent = await resolveLazyComponent(metaComponent);
+    if (isMetaClassModule(metaComponent)) {
+        return container.resolve(metaComponent.module);
+    }
+    else if (isMetaFactoryModule(metaComponent)) {
+        return metaComponent.module(container);
+    }
+};
+/**
+ * Resolve lazy loaded components.
+ *
+ * @param metaComponent - The meta component event handler.
+ * @returns The resolved element type.
+ */
+const resolveLazyComponent = async (metaComponent) => {
+    if (metaComponent?.lazy === true &&
+        isFunctionModule(metaComponent?.module)) {
+        metaComponent.lazy = false;
+        metaComponent.module = await metaComponent.module();
+    }
+    return metaComponent;
+};
+/**
+ * Get the root element to render the React components.
+ *
+ * @param blueprint - The blueprint.
+ * @returns The root element to render the React components.
+ * @throws {UseReactError} If the root container is not found.
+ */
+const getAppRootElement = (blueprint) => {
+    const rootElementId = blueprint.get('stone.useReact.rootElementId', 'root');
+    const appContainer = document.getElementById(rootElementId) ?? undefined;
+    if (appContainer === undefined) {
+        throw new UseReactError('Root container is required to render React components.');
+    }
+    return appContainer;
+};
+/**
+ * Renders the React app.
+ *
+ * @param app - The React app to render.
+ * @param blueprint - The blueprint.
+ * @returns The React root instance.
+ */
+const renderReactApp = (app, blueprint) => {
+    const reactRoot = blueprint.get('stone.useReact.reactRoot') ??
+        createRoot(getAppRootElement(blueprint));
+    reactRoot.render(app);
+    blueprint.setIf('stone.useReact.reactRoot', reactRoot);
+    return reactRoot;
+};
+/**
+ * Hydrates the React app when SSR is enabled.
+ *
+ * @param app - The React app to hydrate.
+ * @param blueprint - The blueprint.
+ * @returns The React root instance.
+ */
+const hydrateReactApp = (app, blueprint) => {
+    const reactRoot = hydrateRoot(getAppRootElement(blueprint), app);
+    blueprint.setIf('stone.useReact.reactRoot', reactRoot);
+    return reactRoot;
+};
+/**
+ * Check if the current environment is the server.
+ *
+ * @returns True if the current environment is the server.
+ */
+const isServer = () => typeof window === 'undefined';
+/**
+ * Check if the current environment is the client.
+ *
+ * @returns True if the current environment is the client.
+ */
+const isClient = () => !isServer();
+/**
+ * Get the HTML template for the React application.
+ *
+ * @param blueprint - The blueprint.
+ * @returns The HTML template.
+ */
+const htmlTemplate = (blueprint) => {
+    const content = blueprint.get('stone.useReact.htmlTemplateContent');
+    if (isNotEmpty(content)) {
+        return content;
+    }
+    throw new UseReactError('HTML template content is required for server-side rendering. Please provide the `htmlTemplateContent` in the blueprint configuration.');
+};
+/**
+ * Determine if the application is running on the server side.
+ *
+ * @returns True if the application is running on the server side, false otherwise.
+ */
+function isSSR() {
+    return import.meta.env.SSR || typeof window === 'undefined';
+}
+/**
+ * Execute the handler.
+ *
+ * This method will try to get data from the snapshot
+ * If the snapshot is not present, it will execute the handler.
+ * If the handler is not present, it will return undefined.
+ *
+ * @param response - The response object.
+ * @returns The data from the response.
+ */
+async function executeHandler(event, response, snapshot, handler, error) {
+    let result = snapshot;
+    if (!snapshot.ssr) {
+        if (isNotEmpty(error) && isObjectLikeModule(handler)) {
+            result = await handler.handle?.(error, event);
+        }
+        else if (isObjectLikeModule(handler)) {
+            result = await handler.handle?.(event);
+        }
+        else {
+            result = undefined;
+        }
+    }
+    if (isNotEmpty(result?.statusCode)) {
+        response.setStatus(result.statusCode);
+    }
+    if (isNotEmpty(result?.headers) &&
+        isNotEmpty(response) &&
+        isFunction(response.setHeaders)) {
+        response.setHeaders(result.headers);
+    }
+    return result?.content ?? result?.data ?? result;
+}
+/**
+ * Keep track of the current layout.
+ * This is used to determine if the layout has changed.
+ * We make a full render each time the layout changes.
+ *
+ * @returns The current layout.
+ */
+let currentLayout;
+/**
+ * Get the browser content.
+ *
+ * @param app - The app component to render.
+ * @param component - The component to render.
+ * @param layout - The layout to use.
+ * @param snapshot - The response snapshot.
+ * @param head - The head context.
+ * @returns The browser response content.
+ */
+function getBrowserContent(app, component, layout, snapshot, head) {
+    const content = { head, app, component, fullRender: currentLayout !== layout, ssr: snapshot.ssr };
+    currentLayout = layout;
+    return content;
+}
+/**
+ * Get the server content.
+ *
+ * @param component - The React component to hydrate.
+ * @param data - The data to pass to the components.
+ * @param container - The service container.
+ * @param event - The incoming browser event.
+ * @param head - The head context.
+ * @returns A promise that resolves when the content is hydrated.
+ */
+async function getServerContent(component, data, container, event, head) {
+    const html = renderToString(component).concat('\n<!--app-html-->');
+    const template = await htmlTemplate(container.make('blueprint'));
+    const snapshot = snapshotResponse(event, container, data).concat('\n<!--app-head-->');
+    return applyHeadContextToHtmlString(head ?? {}, template)
+        .replace('<!--app-html-->', html)
+        .replace('<!--app-head-->', snapshot);
+}
+/**
+ * Get the response snapshot.
+ *
+ * @param event - The incoming browser event.
+ * @returns The response snapshot.
+ */
+function getResponseSnapshot(event, container) {
+    return container.make('snapshot').get(event.fingerprint(), { ssr: false });
+}
+/**
+ * Snapshot the response data.
+ *
+ * @param event - The incoming HTTP event.
+ * @param data - The data to snapshot.
+ */
+function snapshotResponse(event, container, data) {
+    const snapshot = container.make('snapshot');
+    return renderStoneSnapshot(snapshot.add(event.fingerprint(), { ...data, ssr: true }).toJson());
+}
+/**
+ * Render Stone snapshot.
+ *
+ * @param snapshot - The snapshot to render.
+ * @returns The script tag.
+ */
+function renderStoneSnapshot(snapshot) {
+    return `<script id="${STONE_SNAPSHOT}" type="application/json">${snapshot}</script>`;
+}
+/**
+ * Execute hooks.
+ *
+ * @param name - The name of the hook.
+ * @param context - The context of the adapter.
+ */
+async function executeHooks(name, context) {
+    const hooks = context.container.make('blueprint').get('stone.lifecycleHooks', {});
+    if (Array.isArray(hooks[name])) {
+        for (const listener of hooks[name]) {
+            await listener(context);
+        }
+    }
+}
+
+/**
+ * Class representing a ReactRuntime.
+ *
+ * This class is responsible for handling the React runtime environment,
+ * including create snapshots and managing errors.
+*/
+class ReactRuntime {
+    _snapshot;
+    container;
+    blueprint;
+    /**
+     * The ReactRuntime instance.
+     *
+     * @type {ReactRuntime}
+     */
+    static instance;
+    /**
+     * Create a ReactRuntime.
+     *
+     * @param options - ReactRuntime options.
+    */
+    constructor({ container, blueprint, snapshot }) {
+        this._snapshot = snapshot;
+        this.container = container;
+        this.blueprint = blueprint;
+    }
+    /**
+     * Create a snapshot.
+     *
+     * This method will create a snapshot of the current event.
+     * If the environment is server, it will create a snapshot.
+     * If the environment is client, it will return the snapshot.
+     *
+     * @param key - The key to store the snapshot.
+     * @param handler - The handler to create the snapshot.
+     * @returns The snapshot value.
+    */
+    async snapshot(key, handler) {
+        const event = this.container.make('event');
+        const snapshotKey = `${event.fingerprint()}.${key}`;
+        if (isServer()) {
+            const value = await handler(this.container);
+            this._snapshot.set(snapshotKey, value);
+            return value;
+        }
+        else {
+            return this._snapshot.get(snapshotKey) ?? await handler(this.container);
+        }
+    }
+    /**
+     * Set html head tags.
+     *
+     * This method will set the head elements in the document.
+     *
+     * @param value - The head context to set.
+     */
+    head(value) {
+        applyHeadContextToDom(document, value);
+    }
+    /**
+     * Throw an error.
+     *
+     * This method will handle the error and render the error component.
+     * If no error handler is found, the error will be thrown.
+     *
+     * @param error - The error to throw.
+     * @param statusCode - The status code to return.
+     * @returns void
+     * @throws error
+    */
+    async throwError(error, statusCode = 500) {
+        const metavalue = this.blueprint.get(`stone.useReact.errorPages.${String(error.name)}`, this.blueprint.get('stone.useReact.errorPages.default', {}));
+        if (isEmpty(metavalue)) {
+            throw error;
+        }
+        await this.renderErrorComponent(error, metavalue, statusCode);
+    }
+    /**
+     * Render an error component.
+     *
+     * This method will render the error component.
+     *
+     * @param error - The error to render.
+     * @param metavalue - The meta value to render.
+     * @param statusCode - The status code to return.
+     * @returns void
+    */
+    async renderErrorComponent(error, metavalue, statusCode = 500) {
+        let data;
+        const event = this.container.make('event');
+        const handler = await resolveComponent(this.container, { ...metavalue, error });
+        if (isObjectLikeModule(handler)) {
+            const response = await handler.handle?.(error, event);
+            data = response?.content ?? response;
+            statusCode = response?.statusCode ?? statusCode;
+        }
+        const componentType = handler?.render.bind(handler);
+        const appComponent = await buildAppComponent(event, this.container, componentType, metavalue.layout, data, statusCode, error);
+        // Render the component
+        renderReactApp(appComponent, this.blueprint);
+    }
+}
+/**
+ * MetaReactRuntime
+*/
+const MetaReactRuntime = { module: ReactRuntime, isClass: true, alias: 'reactRuntime', singleton: true };
+
+/**
+ * Class representing an UseReactBrowserErrorHandler.
+ *
+ * Adapter level error handler for React applications.
+ */
+class UseReactBrowserErrorHandler {
+    logger;
+    blueprint;
+    /**
+     * Create an UseReactBrowserErrorHandler.
+     *
+     * @param options - UseReactBrowserErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+        this.logger = Logger.getInstance();
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response.
+     */
+    async handle(error, context) {
+        this.logger.error(error.message, { error });
+        return context
+            .rawResponseBuilder
+            .add('render', async () => await this.renderError(error, context));
+    }
+    /**
+     * Get the error body.
+     *
+     * @param error - The error to handle.
+     * @returns The error body.
+     */
+    async renderError(error, context) {
+        const app = await buildAdapterErrorComponent(this.blueprint, context, error.statusCode ?? 500, error);
+        // Render the component
+        renderReactApp(app, this.blueprint);
+    }
+}
+
+/**
+ * A useReact event handler for processing incoming events
+ * For single event handler.
+ *
+ * Multiple event handlers will be processed by the router.
+ *
+ * @template IncomingEventType - The type representing the incoming event.
+ * @template OutgoingResponseType - The type representing the outgoing response.
+ */
+class UseReactEventHandler {
+    blueprint;
+    /**
+     * Constructs a `UseReactEventHandler` instance.
+     *
+     * @param options - The UseReactEventHandler options including blueprint.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+    }
+    /**
+     * Handle an incoming event.
+     *
+     * @returns The outgoing response.
+     */
+    handle() {
+        return this.getComponentEventHandler();
+    }
+    /**
+     * Get the component event handler.
+     *
+     * @returns The component event handler.
+     * @throws {UseReactError} If the component event handler is missing.
+     */
+    getComponentEventHandler() {
+        const handler = this.blueprint.get('stone.useReact.componentEventHandler');
+        if (isEmpty(handler)) {
+            throw new UseReactError('The component event handler is missing.');
+        }
+        return handler;
+    }
+}
+
+/**
+ * Prepare the page to render.
+ *
+ * Here we prepare the page to render by resolving
+ * the handler, handler the event, and rendering the component.
+ *
+ * @param event - The incoming HTTP event.
+ * @param response - The outgoing HTTP response.
+ * @param container - The service container.
+ * @param snapshot - The response snapshot.
+ */
+async function preparePage(event, response, container, snapshot) {
+    const { layout = 'default' } = response.content;
+    const page = await resolveComponent(container, response.content);
+    const data = await executeHandler(event, response, snapshot, page);
+    const componentType = page?.render.bind(page);
+    const head = await page?.head?.({ event, data, statusCode: response.statusCode });
+    await executeHooks('onPreparingPage', { event, response, container, snapshot, data, componentType, head });
+    const snapshotData = { data, layout, statusCode: response.statusCode };
+    const component = await buildPageComponent(event, container, componentType, data, response.statusCode);
+    const appComponent = await buildAppComponent(event, container, componentType, layout, data, response.statusCode);
+    response.setContent(isSSR()
+        ? await getServerContent(appComponent, snapshotData, container, event, head)
+        : getBrowserContent(appComponent, component, layout, snapshot, head));
+}
+/**
+ * Prepare the error page to render.
+ *
+ * Error pages are prepared sepatately because their handler
+ * is different from the normal page handler.
+ * Their handler takes an error as the first argument and the event as the second.
+ *
+ * @param event - The incoming HTTP event.
+ * @param response - The outgoing HTTP response.
+ * @param container - The service container.
+ * @param snapshot - The response snapshot.
+ */
+async function prepareErrorPage(event, response, container, snapshot) {
+    const { error = {}, layout } = response.content;
+    const errorPage = await resolveComponent(container, response.content);
+    const data = await executeHandler(event, response, snapshot, errorPage, error);
+    const componentType = errorPage?.render.bind(errorPage) ?? StoneError;
+    const head = await errorPage?.head?.({ event, data, statusCode: response.statusCode, error });
+    await executeHooks('onPreparingPage', { event, response, container, snapshot, data, componentType, head, error });
+    const snapshotData = { data, layout, statusCode: response.statusCode, error: { name: error.name } };
+    const component = await buildPageComponent(event, container, componentType, data, response.statusCode, error);
+    const appComponent = await buildAppComponent(event, container, componentType, layout, data, response.statusCode, error);
+    response.setContent(isSSR()
+        ? await getServerContent(appComponent, snapshotData, container, event, head)
+        : getBrowserContent(appComponent, component, layout, snapshot, head));
+}
+/**
+ * Prepare the fallback error page to render.
+ *
+ * We prepare a fallback error page if no event nor error handler is provided.
+ *
+ * @param event - The incoming event.
+ * @param response - The outgoing response.
+ * @param container - The service container.
+ * @param snapshot - The response snapshot.
+ */
+async function prepareFallbackErrorPage(event, response, container, snapshot) {
+    const { layout, error, statusCode = 500 } = snapshot;
+    const blueprint = container.make('blueprint');
+    const metavalue = blueprint.get(`stone.useReact.errorPages.${String(error?.name)}`, blueprint.get('stone.useReact.errorPages.default', {}));
+    const content = { ...metavalue, layout };
+    content.error = error ?? (response.content instanceof Error ? response.content : new Error('An error occurred.'));
+    response
+        .setContent(content)
+        .setStatus(statusCode);
+    await prepareErrorPage(event, response, container, snapshot);
+}
+
+/**
+ * Hook that runs just before preparing the response.
+ *
+ * @param context - The context of the hook.
+*/
+async function onPreparingResponse({ event, response, container }) {
+    const snapshot = getResponseSnapshot(event, container);
+    if (isNotEmpty(snapshot.error)) {
+        await prepareFallbackErrorPage(event, response, container, snapshot);
+    }
+    else if (response.isError()) {
+        await prepareErrorPage(event, response, container, snapshot);
+    }
+    else if (isFunction(response.content?.module)) {
+        await preparePage(event, response, container, snapshot);
+    }
+}
+
+/**
+ * Class representing an UseReactUseReactKernelErrorHandler.
+ *
+ * Kernel level error handler for React applications.
+ */
+class UseReactKernelErrorHandler {
+    blueprint;
+    /**
+     * Create an UseReactUseReactKernelErrorHandler.
+     *
+     * @param options - UseReactUseReactKernelErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @returns The outgoing http response.
+     */
+    handle(error) {
+        const metavalue = this.blueprint.get(`stone.useReact.errorPages.${String(error?.name)}`) ??
+            this.blueprint.get('stone.useReact.errorPages.default', {});
+        return { content: { ...metavalue, error }, statusCode: error?.statusCode ?? 500 };
+    }
+}
+
+/**
+ * Create an UseReact response.
+ *
+ * @param options - The options for creating the response.
+ * @returns The React response.
+ */
+const reactResponse = async (options) => {
+    if (isNotEmpty(options) &&
+        (isNotEmpty(options.url) ||
+            (isNotEmpty(options.content) && isNotEmpty(options.content.redirect)))) {
+        return await reactRedirectResponse(options);
+    }
+    return import.meta.env.SSR
+        ? OutgoingHttpResponse.create(options)
+        : OutgoingBrowserResponse.create(options);
+};
+/**
+ * Create an UseReact redirect response.
+ *
+ * @param options - The options for creating the response.
+ * @returns The React redirect response.
+ */
+const reactRedirectResponse = async (options) => {
+    return import.meta.env.SSR
+        ? RedirectResponse.create({ statusCode: 302, ...options })
+        : RedirectBrowserResponse.create({ statusCode: 302, ...options });
+};
+
+/**
+ * Class representing an UseReactServerErrorHandler.
+ *
+ * Adapter level error handler for React applications.
+ */
+class UseReactServerErrorHandler {
+    logger;
+    blueprint;
+    /**
+     * Create an UseReactServerErrorHandler.
+     *
+     * @param options - UseReactServerErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+        this.logger = Logger.getInstance();
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response.
+     */
+    async handle(error, context) {
+        this.logger.error(error.message, { error });
+        return context
+            .rawResponseBuilder
+            .add('statusCode', error.statusCode ?? 500)
+            .add('headers', new Headers({ 'Content-Type': 'text/html' }))
+            .add('body', await this.getErrorBody(error, context));
+    }
+    /**
+     * Get the error body.
+     *
+     * @param error - The error to handle.
+     * @returns The error body.
+    */
+    async getErrorBody(error, context) {
+        const statusCode = error.statusCode ?? 500;
+        const template = await htmlTemplate(this.blueprint);
+        const ClientApp = await buildAdapterErrorComponent(this.blueprint, context, statusCode, error);
+        return template.replace('<!--app-html-->', renderToString(ClientApp));
+    }
+}
+
+/**
+ * Use React Service Provider.
+ */
+class UseReactServiceProvider {
+    container;
+    /**
+     * Constructs a new `UseReactServiceProvider` instance.
+     *
+     * @param container - The container to register services in.
+     */
+    constructor(container) {
+        this.container = container;
+    }
+    /**
+     * Register method for the service provider.
+     */
+    register() {
+        this.registerSnapshot();
+    }
+    /**
+     * Boot method for the service provider.
+     */
+    boot() {
+        ReactRuntime.instance = this.container.make(ReactRuntime);
+    }
+    /**
+     * Register the snapshot.
+     *
+     * We save the snapshot on server side rendering and
+     * we use it to hydrate the application on the client side.
+    */
+    registerSnapshot() {
+        const textContent = isSSR() ? '{}' : (window.document.getElementById(STONE_SNAPSHOT)?.textContent ?? '{}');
+        this.container.singletonIf('snapshot', () => Config.fromJson(textContent));
+    }
+}
+/**
+ * MetaUseReactServiceProvider
+ */
+const MetaUseReactServiceProvider = { module: UseReactServiceProvider, isClass: true };
+
+/**
+ * Utility function to define an adapter error page.
+ *
+ * @param module - The adapter error page module.
+ * @param options - Optional adapter error page options.
+ * @returns The UseReactBlueprint.
+ */
+function defineAdapterErrorPage(module, options) {
+    const error = options?.error ?? 'default';
+    const adapterErrorPages = Object.fromEntries([error].flat().map((err) => [
+        err,
+        {
+            ...options,
+            module,
+            error: err,
+            isFactory: options?.isClass !== true
+        }
+    ]));
+    return {
+        stone: {
+            useReact: {
+                adapterErrorPages
+            }
+        }
+    };
+}
+
+/**
+ * Utility function to define a page.
+ *
+ * @param module - The EventHandler module.
+ * @param options - Page definition options.
+ * @returns The UseReactBlueprint.
+ */
+function definePage(module, options) {
+    return {
+        stone: {
+            router: {
+                definitions: [
+                    {
+                        ...options,
+                        method: GET,
+                        methods: [],
+                        children: undefined,
+                        handler: {
+                            module,
+                            isComponent: true,
+                            layout: options?.layout,
+                            isClass: options?.isClass,
+                            isFactory: options?.isClass !== true
+                        }
+                    }
+                ]
+            }
+        }
+    };
+}
+/**
+ * Utility function to define a page layout.
+ *
+ * @param module - The layout module.
+ * @param options - Optional page layout definition options.
+ * @returns The UseReactBlueprint.
+ */
+function definePageLayout(module, options) {
+    const name = options?.name ?? 'default';
+    return {
+        stone: {
+            useReact: {
+                layout: {
+                    [name]: {
+                        module,
+                        isClass: options?.isClass,
+                        isFactory: options?.isClass !== true
+                    }
+                }
+            }
+        }
+    };
+}
+/**
+ * Utility function to define an error page.
+ *
+ * @param module - The layout module.
+ * @param options - Optional page layout definition options.
+ * @returns The UseReactBlueprint.
+ */
+function defineErrorPage(module, options) {
+    const error = options?.error ?? 'default';
+    const errorPages = Object.fromEntries([error].flat().map((err) => [
+        err,
+        {
+            ...options,
+            module,
+            error: err,
+            isFactory: options?.isClass !== true
+        }
+    ]));
+    return {
+        stone: {
+            useReact: {
+                errorPages
+            }
+        }
+    };
+}
+
+/**
+ * Constants are defined here to prevent Circular dependency between modules
+ * This pattern must be applied to all Stone libraries or third party libraries.
+ */
+/**
+ * A unique symbol key to mark classes as React Page component.
+ */
+const REACT_PAGE_KEY = Symbol.for('ReactPage');
+/**
+ * A unique symbol key to mark classes as React Page layout component.
+ */
+const REACT_PAGE_LAYOUT_KEY = Symbol.for('ReactPageLayout');
+/**
+ * A unique symbol key to mark classes as React Error handler component.
+ */
+const REACT_ERROR_PAGE_KEY = Symbol.for('ReactErrorPage');
+/**
+ * A unique symbol key to mark classes as React Adapter Error handler component.
+ */
+const REACT_ADAPTER_ERROR_PAGE_KEY = Symbol.for('ReactAdapterErrorPage');
+/**
+ * A unique symbol key to mark classes as React Stone application entry point.
+ */
+const STONE_REACT_APP_KEY = Symbol.for('StoneReactApp');
+
+/**
+ * Adapter Middleware for handling outgoing responses and rendering them in the browser.
+ */
+class BrowserResponseMiddleware {
+    isRendered;
+    blueprint;
+    /**
+     * Create a BrowserResponseMiddleware.
+     *
+     * @param {blueprint} options - Options for creating the BrowserResponseMiddleware.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+        this.isRendered = blueprint.has('stone.useReact.reactRoot');
+    }
+    /**
+     * Handles the outgoing response, processes it, and invokes the next middleware in the pipeline.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @param next - The next middleware to be invoked in the pipeline.
+     * @returns A promise resolving to the processed context.
+     * @throws {NodeHttpAdapterError} If required components are missing in the context.
+     */
+    async handle(context, next) {
+        const rawResponseBuilder = await next(context);
+        this.ensureValidContext(context, rawResponseBuilder);
+        return rawResponseBuilder.add('render', async () => await this.renderComponent(context.outgoingResponse));
+    }
+    /**
+     * Ensures the context and response builder have the required components.
+     */
+    ensureValidContext(context, rawResponseBuilder) {
+        if (context.rawEvent === undefined ||
+            context.incomingEvent === undefined ||
+            context.outgoingResponse === undefined ||
+            rawResponseBuilder?.add === undefined) {
+            throw new UseReactError('The context is missing required components.');
+        }
+    }
+    /**
+     * Renders the provided React content.
+     *
+     * @param response - The response object.
+     */
+    async renderComponent(response) {
+        if (isEmpty(response)) {
+            throw new UseReactError('No response provided for rendering.');
+        }
+        const content = response.content;
+        const targetUrl = response.targetUrl;
+        if (isNotEmpty(targetUrl)) {
+            return this.handleRedirect(targetUrl);
+        }
+        if (isNotEmpty(content?.head)) {
+            applyHeadContextToDom(document, content.head);
+        }
+        if (content?.ssr === true && !this.isRendered && isNotEmpty(content?.app)) {
+            return this.hydrateReactApp(content.app);
+        }
+        if (isNotEmpty(content?.app) && (!this.isRendered || content?.fullRender === true)) {
+            return this.renderReactApp(content.app);
+        }
+        if (isNotEmpty(content?.component)) {
+            return await this.dispatchComponentToOutlet(content.component);
+        }
+        throw new UseReactError('Invalid content provided for rendering.');
+    }
+    /**
+     * Handles navigation redirection.
+     *
+     * @param path - The path to redirect to.
+     */
+    handleRedirect(path) {
+        window.history.pushState({ path }, '', path);
+        window.dispatchEvent(new Event(NAVIGATION_EVENT));
+    }
+    /**
+     * Hydrates the React app when SSR is enabled.
+     *
+     * @param app - The React app to hydrate.
+     */
+    hydrateReactApp(app) {
+        hydrateReactApp(app, this.blueprint);
+    }
+    /**
+     * Renders the React app.
+     *
+     * @param app - The React app to render.
+     */
+    renderReactApp(app) {
+        renderReactApp(app, this.blueprint);
+    }
+    /**
+     * Dispatches a component to the layout outlet when no layout is defined.
+     *
+     * @param component - The component to dispatch.
+     */
+    async dispatchComponentToOutlet(component) {
+        window.dispatchEvent(new CustomEvent(STONE_PAGE_EVENT_OUTLET, { detail: component }));
+    }
+}
+/**
+ * Meta Middleware for processing browser responses.
+ */
+const MetaBrowserResponseMiddleware = { module: BrowserResponseMiddleware, isClass: true };
+
+/**
+ * Blueprint middleware to dynamically set lifecycle hooks for react.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetUseReactHooksMiddleware(context, next)
+ * ```
+ */
+const SetUseReactHooksMiddleware = (context, next) => {
+    if (context.blueprint.get('stone.adapter.platform') !== NODE_CONSOLE_PLATFORM) {
+        context
+            .blueprint
+            .add('stone.lifecycleHooks.onPreparingResponse', [onPreparingResponse]);
+    }
+    return next(context);
+};
+/**
+ * Blueprint middleware to set BrowserResponseMiddleware for the Browser adapter.
+ *
+ * The MetaBrowserResponseMiddleware is an adapter middleware and is useful
+ * for handling outgoing responses and rendering them in the browser.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetBrowserResponseMiddlewareMiddleware(context, next)
+ * ```
+ */
+const SetBrowserResponseMiddlewareMiddleware = async (context, next) => {
+    if (context.blueprint.get('stone.adapter.platform') === BROWSER_PLATFORM) {
+        context.blueprint.add('stone.adapter.middleware', [MetaBrowserResponseMiddleware]);
+    }
+    return await next(context);
+};
+/**
+ * Blueprint middleware to process and register kernel error page definitions from modules.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetReactKernelErrorPageMiddleware(context, next)
+ * ```
+ */
+const SetReactKernelErrorPageMiddleware = (context, next) => {
+    context
+        .blueprint
+        .set('stone.kernel.errorHandlers.default', { module: UseReactKernelErrorHandler, isClass: true });
+    context
+        .modules
+        .filter(module => hasMetadata(module, REACT_ERROR_PAGE_KEY))
+        .forEach(module => {
+        const { error, layout } = getMetadata(module, REACT_ERROR_PAGE_KEY, { error: 'default' });
+        Array(error).flat().forEach(name => {
+            context
+                .blueprint
+                .set(`stone.useReact.errorPages.${name}`, { layout, module, isClass: true });
+        });
+    });
+    // Process both eager and lazy loaded error pages
+    Object
+        .keys(context.blueprint.get('stone.useReact.errorPages', {}))
+        .forEach((name) => {
+        context
+            .blueprint
+            .set(`stone.kernel.errorHandlers.${name}`, { module: UseReactKernelErrorHandler, isClass: true });
+    });
+    return next(context);
+};
+/**
+ * Blueprint middleware to process and register adapter error page definitions from modules.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetReactAdapterErrorPageMiddleware(context, next)
+ * ```
+ */
+const SetReactAdapterErrorPageMiddleware = (context, next) => {
+    const UseReactAdapterErrorHandler = import.meta.env.SSR
+        ? UseReactServerErrorHandler
+        : UseReactBrowserErrorHandler;
+    context
+        .blueprint
+        .set('stone.adapter.errorHandlers.default', { module: UseReactAdapterErrorHandler, isClass: true });
+    context
+        .modules
+        .filter(module => hasMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY))
+        .forEach(module => {
+        const { error, layout, adapterAlias, platform } = getMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY, { error: 'default' });
+        if (isMatchedAdapter(context.blueprint, platform, adapterAlias)) {
+            Array(error).flat().forEach(name => {
+                context
+                    .blueprint
+                    .set(`stone.useReact.adapterErrorPages.${name}`, { isClass: true, layout, module });
+            });
+        }
+    });
+    // Process both eager and lazy loaded error pages
+    Object
+        .keys(context.blueprint.get('stone.useReact.adapterErrorPages', {}))
+        .forEach((name) => {
+        context
+            .blueprint
+            .set(`stone.adapter.errorHandlers.${name}`, { module: UseReactAdapterErrorHandler, isClass: true });
+    });
+    return next(context);
+};
+/**
+ * Blueprint middleware to set StaticFileMiddleware for SSR adapter.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetSSRStaticFileMiddleware(context, next)
+ * ```
+ */
+const SetSSRStaticFileMiddleware = async (context, next) => {
+    import.meta.env.SSR && context.blueprint.add('stone.kernel.middleware', [MetaStaticFileMiddleware]);
+    return await next(context);
+};
+/**
+ * Blueprint middleware to set CompressionMiddleware for SSR adapter.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetSSRCompressionMiddleware(context, next)
+ * ```
+ */
+const SetSSRCompressionMiddleware = async (context, next) => {
+    import.meta.env.SSR && context.blueprint.add('stone.kernel.middleware', [MetaCompressionMiddleware]);
+    return await next(context);
+};
+/**
+ * Blueprint middleware to process and register route definitions from modules.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetReactRouteDefinitionsMiddleware(context, next)
+ * ```
+ */
+const SetReactRouteDefinitionsMiddleware = (context, next) => {
+    context
+        .modules
+        .filter(module => hasMetadata(module, REACT_PAGE_KEY))
+        .forEach(module => {
+        const options = getMetadata(module, REACT_PAGE_KEY, { path: '/' });
+        const definition = {
+            ...options,
+            handler: { ...options.handler, module }
+        };
+        context.blueprint.add('stone.router.definitions', [definition]);
+    });
+    return next(context);
+};
+/**
+ * Blueprint middleware to process and register layout definitions from modules.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetReactPageLayoutMiddleware(context, next)
+ * ```
+ */
+const SetReactPageLayoutMiddleware = (context, next) => {
+    context
+        .modules
+        .filter(module => hasMetadata(module, REACT_PAGE_LAYOUT_KEY))
+        .forEach(module => {
+        const { name = 'default' } = getMetadata(module, REACT_PAGE_LAYOUT_KEY, { name: 'default' });
+        context.blueprint.set(`stone.useReact.layout.${name}`, { isClass: true, module });
+    });
+    return next(context);
+};
+/**
+ * Blueprint middleware to set the UseReact as the main event handler for the application.
+ *
+ * Set as fallback event handler if none of the other event handlers are registered.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next function in the pipeline.
+ * @returns The updated blueprint.
+ *
+ * @example
+ * ```typescript
+ * SetUseReactEventHandlerMiddleware({ modules, blueprint }, next);
+ * ```
+ */
+async function SetUseReactEventHandlerMiddleware(context, next) {
+    const blueprint = await next(context);
+    const module = context.modules.find(module => hasMetadata(module, STONE_REACT_APP_KEY));
+    blueprint.setIf('stone.kernel.eventHandler', { module: UseReactEventHandler, isClass: true });
+    if (isNotEmpty(module)) {
+        blueprint.set('stone.useReact.componentEventHandler', { module, isComponent: true, isClass: true });
+    }
+    return blueprint;
+}
+/**
+ * Configuration for react processing middleware.
+ *
+ * This array defines a list of middleware pipes, each with a `pipe` function and a `priority`.
+ * These pipes are executed in the order of their priority values, with lower values running first.
+ */
+const metaUseReactBlueprintMiddleware = [
+    { module: SetSSRStaticFileMiddleware, priority: 10 },
+    { module: SetUseReactHooksMiddleware, priority: 10 },
+    { module: SetSSRCompressionMiddleware, priority: 10 },
+    { module: SetReactPageLayoutMiddleware, priority: 10 },
+    { module: SetUseReactEventHandlerMiddleware, priority: 2 },
+    { module: SetReactKernelErrorPageMiddleware, priority: 10 },
+    { module: SetReactAdapterErrorPageMiddleware, priority: 10 },
+    { module: SetReactRouteDefinitionsMiddleware, priority: 10 },
+    { module: SetBrowserResponseMiddlewareMiddleware, priority: 10 }
+];
+
+/**
+ * Default blueprint for a React-based Stone.js application.
+ *
+ * - Defines middleware, lifecycle hooks, and the default HTML template path.
+ */
+const useReactBlueprint = {
+    stone: {
+        useReact: {},
+        blueprint: {
+            middleware: metaUseReactBlueprintMiddleware
+        },
+        services: [MetaReactRuntime],
+        providers: [MetaUseReactServiceProvider]
+    }
+};
+
+/**
+ * Defines a Stone React app using a factory-based or class-based main handler.
+ *
+ * @param moduleOrOptions - A factory function or class constructor for the main page.
+ * @param optionsOrBlueprints - Optional application-level configuration.
+ * @param maybeBlueprints - Additional blueprints to merge.
+ * @returns A fully merged Stone blueprint.
+ */
+function defineStoneReactApp(moduleOrOptions = {}, optionsOrBlueprints, maybeBlueprints) {
+    let module;
+    let options = {};
+    let blueprints = [];
+    // Pattern: defineStoneReactApp(handler, options?, blueprints?)
+    if (isFunctionModule(moduleOrOptions)) {
+        module = moduleOrOptions;
+        if (isObjectLikeModule(optionsOrBlueprints)) {
+            options = optionsOrBlueprints;
+            blueprints = Array.isArray(maybeBlueprints) ? maybeBlueprints : [];
+        }
+    }
+    else if (isObjectLikeModule(moduleOrOptions)) { // Pattern: defineStoneReactApp(options, blueprints?)
+        options = moduleOrOptions;
+        blueprints = Array.isArray(optionsOrBlueprints) ? optionsOrBlueprints : [];
+    }
+    const stonePart = {
+        ...options,
+        useReact: {
+            ...options.useReact
+        }
+    };
+    if (isNotEmpty(module)) {
+        stonePart.useReact.componentEventHandler = {
+            module,
+            isComponent: true,
+            isClass: options.isClass,
+            isFactory: options.isClass !== true
+        };
+    }
+    return mergeBlueprints(stoneBlueprint, useReactBlueprint, ...blueprints, { stone: stonePart });
+}
+
+/**
+ * A class decorator for defining a class as a React Handler layout.
+ *
+ * @param options - Configuration options for the layout definition.
+ * @returns A method decorator to be applied to a class method.
+ *
+ * @example
+ * ```typescript
+ * import { AdapterErrorPage } from '@stone-js/use-react';
+ *
+ * @AdapterErrorPage({ error: 'UserNotFoundError' })
+ * class UserAdapterErrorPage {
+ *   render({ error }) {
+ *     return <h1>User name: {error.message}</h1>;
+ *   }
+ * }
+ * ```
+ */
+const AdapterErrorPage = (options) => {
+    return classDecoratorLegacyWrapper((_target, context) => {
+        setMetadata(context, REACT_ADAPTER_ERROR_PAGE_KEY, { ...options, isClass: true });
+    });
+};
+
+/**
+ * A class decorator for defining a class as a React Handler layout.
+ *
+ * @param options - Configuration options for the layout definition.
+ * @returns A method decorator to be applied to a class method.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorPage } from '@stone-js/use-react';
+ *
+ * @ErrorPage({ error: 'UserNotFoundError' })
+ * class UserErrorPage {
+ *   render({ error }) {
+ *     return <h1>User name: {error.message}</h1>;
+ *   }
+ * }
+ * ```
+ */
+const ErrorPage = (options) => {
+    return classDecoratorLegacyWrapper((_target, context) => {
+        setMetadata(context, REACT_ERROR_PAGE_KEY, { ...options, isClass: true });
+    });
+};
+
+/**
+ * Hook decorator to mark a method as a lifecycle hook
+ * And automatically add it to the global lifecycle hook registry.
+ *
+ * @example
+ * ```typescript
+ * class MyClass {
+ *    // ...
+ *    @Hook('onPreparingPage')
+ *    onPreparingPage () {}
+ * }
+ * ```
+ *
+ * @param name - The name of the lifecycle hook.
+ * @returns A class decorator function that sets the metadata using the provided options.
+ */
+const Hook = (name) => {
+    return methodDecoratorLegacyWrapper((_target, context) => {
+        addMetadata(context, LIFECYCLE_HOOK_KEY, { name, method: context.name });
+    });
+};
+
+/**
+ * A class decorator for defining a class as a React Page route action.
+ * Uses the `Match` decorator internally to register the route with the HTTP `GET` method.
+ *
+ * @param options - Configuration options for the route definition, excluding the `methods` property.
+ * @returns A method decorator to be applied to a class method.
+ *
+ * @example
+ * ```typescript
+ * import { Page } from '@stone-js/use-react';
+ *
+ * @Page('/user-profile')
+ * class UserPage {
+ *   handle({ event }): Record<string, string> {
+ *     return { name: 'Jane Doe' };
+ *   }
+ *
+ *   render({ data }) {
+ *     return <h1>User name: {data.name}</h1>;
+ *   }
+ * }
+ * ```
+ */
+const Page = (path, options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        setMetadata(context, REACT_PAGE_KEY, {
+            ...options,
+            path,
+            method: GET,
+            methods: [],
+            handler: { isClass: true, isComponent: true, layout: options.layout, module: target }
+        });
+    });
+};
+
+/**
+ * A class decorator for defining a class as a React Page layout.
+ *
+ * @param options - Configuration options for the layout definition.
+ * @returns A method decorator to be applied to a class method.
+ *
+ * @example
+ * ```typescript
+ * import { PageLayout } from '@stone-js/use-react';
+ *
+ * @PageLayout({ name: 'UserPageLayout' })
+ * class UserPageLayout {
+ *   render({ data }) {
+ *     return <h1>User name: {data.name}</h1>;
+ *   }
+ * }
+ * ```
+ */
+const PageLayout = (options) => {
+    return classDecoratorLegacyWrapper((_target, context) => {
+        setMetadata(context, REACT_PAGE_LAYOUT_KEY, { ...options, isClass: true });
+    });
+};
+
+/**
+ * Decorator to set the status code of the response.
+ *
+ * @param statusCode - The status code of the response.
+ * @param headers - The headers for the response.
+ * @returns A method decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Page, PageStatus } from '@stone-js/use-react';
+ *
+ * @Page('/user-profile')
+ * class UserPage {
+ *   @PageStatus()
+ *   handle() {
+ *     return { name: 'John Doe' };
+ *   }
+ * }
+ * ```
+ */
+const PageStatus = (statusCode = 200, headers = {}) => {
+    return methodDecoratorLegacyWrapper((target, _context) => {
+        return async function (...args) {
+            const content = await target.apply(this, args);
+            return { content, statusCode, headers };
+        };
+    });
+};
+
+/**
+ * Decorator to create a snapshot of the current data.
+ *
+ * @param name - The name of the snapshot.
+ * @returns A method decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@stone-js/core';
+ * import { Snapshot } from '@stone-js/use-react';
+ *
+ * @Service({ alias: 'userService' })
+ * class UserService {
+ *   @Snapshot()
+ *   showProfile() {
+ *     return { name: 'John Doe' };
+ *   }
+ * }
+ * ```
+ */
+const Snapshot = (name) => {
+    return methodDecoratorLegacyWrapper((target, context) => {
+        return async function (...args) {
+            name = name ?? `${String(Object.getPrototypeOf(this).constructor.name)}.${String(context.name)}`;
+            return await ReactRuntime.instance?.snapshot(name, () => target.apply(this, args));
+        };
+    });
+};
+
+/**
+ * UseReact decorator.
+ *
+ * UseReact is a class decorator that allows you to use React components in your Stone application.
+ * The decorator is used to define the React configuration for the class.
+ *
+ * @param options - UseReactOptions
+ * @returns ClassDecorator
+ */
+const UseReact = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        setMetadata(context, STONE_REACT_APP_KEY, { isComponent: true, isClass: true });
+        addBlueprint(target, context, useReactBlueprint, { stone: { useReact: options } });
+    });
+};
+
+/**
+ * Stone Client.
+ * This component is used to wrap content
+ * that should only be rendered on the client.
+ *
+ * @param options - The options to create the Stone Client.
+ */
+const StoneClient = ({ children }) => {
+    return isClient() ? jsx(Fragment, { children: children }) : jsx(Fragment, {});
+};
+
+/**
+ * Internal link component using Stone.js router.
+ */
+const InternalLink = ({ to, href, noRel, children, className, defaultNav, selectedClass = 'selected', ariaCurrentValue = 'page', rel = 'noopener noreferrer' }) => {
+    const router = useContext(StoneContext).container.resolve(Router);
+    const path = isObjectLikeModule(to) ? router.generate(to) : to ?? href;
+    const [currentRoute, setCurrentRoute] = useState(router.getCurrentRoute());
+    const selectedClassName = currentRoute?.path === path ? selectedClass : undefined;
+    const elemClassName = [className, selectedClassName].filter(Boolean).join(' ').trim();
+    const handleClick = (event) => {
+        event.preventDefault();
+        router.navigate(to ?? '');
+    };
+    useEffect(() => {
+        const routerEventHandler = (event) => {
+            setCurrentRoute(event.get('route'));
+        };
+        router.on(RouteEvent.ROUTED, routerEventHandler);
+        return () => {
+            router.off(RouteEvent.ROUTED, routerEventHandler);
+        };
+    }, [router]);
+    return defaultNav === true
+        ? (jsx("a", { href: path, className: elemClassName, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, children: children }))
+        : (jsx("button", { onClick: handleClick, className: elemClassName, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, children: children }));
+};
+/**
+ * External link component rendering a regular <a> tag.
+ */
+const ExternalLink = ({ to, href, noRel, target, children, className, ariaCurrentValue = 'page', rel = 'noopener noreferrer' }) => (jsx("a", { target: target, className: className, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, href: typeof to === 'string' ? to : href, children: children }));
+/**
+ * Main StoneLink component delegating to internal or external versions.
+ */
+const StoneLink = (props) => {
+    return props.external === true ? jsx(ExternalLink, { ...props }) : jsx(InternalLink, { ...props });
+};
+
+/**
+ * A dynamic rendering component that updates its content based on a global event.
+ *
+ * - Listens for `stone:inject:react-page:outlet` and updates its view when triggered.
+ * - Uses `useState` to manage the currently displayed content.
+ * - Automatically cleans up event listeners on unmount.
+ *
+ * This component enables dynamic content updates within a Stone.js application.
+ *
+ * @param options - The options to create the Stone Outlet.
+ * @returns The Stone Outlet component.
+ */
+const StoneOutlet = ({ children }) => {
+    const [currentView, setCurrentView] = useState(children);
+    useEffect(() => {
+        const eventName = STONE_PAGE_EVENT_OUTLET;
+        const handleEvent = (e) => {
+            if (isNotEmpty(e) && isNotEmpty(e.detail)) {
+                setCurrentView(e.detail);
+            }
+        };
+        window.addEventListener(eventName, handleEvent);
+        return () => window.removeEventListener(eventName, handleEvent);
+    }, []);
+    return jsx("div", { "data-stone-outlet": 'true', children: currentView });
+};
+
+/**
+ * Stone Server.
+ * This component is used to wrap content
+ * that should only be rendered on the server.
+ *
+ * @param options - The options to create the Stone Server.
+ */
+const StoneServer = ({ children }) => {
+    return isServer() ? jsx(Fragment, { children: children }) : jsx(Fragment, {});
+};
+
+export { AdapterErrorPage, BrowserResponseMiddleware, ErrorPage, Hook, MetaBrowserResponseMiddleware, MetaReactRuntime, MetaUseReactServiceProvider, Page, PageLayout, PageStatus, REACT_ADAPTER_ERROR_PAGE_KEY, REACT_ERROR_PAGE_KEY, REACT_PAGE_KEY, REACT_PAGE_LAYOUT_KEY, ReactRuntime, STONE_DOM_ATTR, STONE_PAGE_EVENT_OUTLET, STONE_REACT_APP_KEY, STONE_SNAPSHOT, SetBrowserResponseMiddlewareMiddleware, SetReactAdapterErrorPageMiddleware, SetReactKernelErrorPageMiddleware, SetReactPageLayoutMiddleware, SetReactRouteDefinitionsMiddleware, SetSSRCompressionMiddleware, SetSSRStaticFileMiddleware, SetUseReactEventHandlerMiddleware, SetUseReactHooksMiddleware, Snapshot, StoneClient, StoneContext, StoneError, StoneLink, StoneOutlet, StonePage, StoneServer, UseReact, UseReactBrowserErrorHandler, UseReactError, UseReactEventHandler, UseReactKernelErrorHandler, UseReactServerErrorHandler, UseReactServiceProvider, applyHeadContextToDom, applyHeadContextToHtmlString, applyMeta, buildAdapterErrorComponent, buildAppComponent, buildLayoutComponent, buildPageComponent, defineAdapterErrorPage, defineErrorPage, definePage, definePageLayout, defineStoneReactApp, executeHandler, executeHooks, getAppRootElement, getBrowserContent, getResponseSnapshot, getServerContent, htmlTemplate, hydrateReactApp, isClient, isSSR, isServer, metaUseReactBlueprintMiddleware, onPreparingResponse, prepareErrorPage, prepareFallbackErrorPage, preparePage, reactRedirectResponse, reactResponse, renderReactApp, renderStoneSnapshot, resolveComponent, resolveLazyComponent, snapshotResponse, useReactBlueprint };