@codenotch/codenotch.react 1.0.82 → 2.0.1

package/src/index.ts

@@ -1,386 +1,400 @@
-import ReactDOM from "react-dom";
-import { SignalR } from "./core/SignalR";
-import ProcessUtils from "./core/ProcessUtils";
-import { IDisposable } from "./models/Misc";
-import { ICodenotchApi, ICodenotchDialog, ICodenotchEnv, IProcessResult } from "./models/Codenotch";
-import { v4 } from "uuid";
-import CodeEditor from "./components/CodeEditor";
-
-var signalR: SignalR | undefined = undefined;
-
-/**
- * The Codenotch runtime environment, populated by {@link init}.
- * Prefer reading it through `useCodenotch().env`.
- */
-const env: ICodenotchEnv = {};
-
-const MISSING_CLUSTER_URL_ERROR = "Codenotch cluster URL is not defined. Please set it in the Codenotch configuration.";
-const MISSING_SERVICE_NAME_ERROR = "Codenotch service name is not defined. Please set it in the Codenotch configuration.";
-const MISSING_TENANT_NAME_ERROR = "Codenotch tenant name is not defined. Please set it in the Codenotch configuration.";
-
-/**
- * Initialize the Codenotch environment from the given key-value pairs.
- *
- * This is normally called once, by the page hosting the application, with the
- * environment variables injected by the Codenotch runtime (URL parameters or
- * any other source). It must be called before `useCodenotch()` is used.
- *
- * Recognized key formats:
- * - `i18n.<key>.<language>` — a translation, stored in `env.i18n[language][key]`.
- *   The first language found becomes the current language if none is set.
- * - `GLOBAL.<name>` — JSON value assigned to `window[name]` (or `globalThis`).
- * - `appManifest` / `projectManifest` — parsed as JSON into the environment.
- * - anything else — copied as-is onto {@link env}.
- *
- * The UI theme is resolved from the `_theme` URL parameter, or from
- * `prefers-color-scheme` as a fallback.
- *
- * @param envVariables An object containing the Codenotch environment variables as key-value pairs.
- * @example
- * import { init } from 'codenotch-react';
- * init({
- *     clusterUrl: 'https://cluster.example.com',
- *     serviceName: 'myproject',
- *     tenantName: 'acme',
- *     'i18n.welcome.en': 'Welcome',
- *     'i18n.welcome.fr': 'Bienvenue'
- * });
- */
-function init(envVariables: any): void {
-
-
-    // Ensure envVariables is an object
-    if (typeof envVariables === 'object' && envVariables !== null) {
-
-        let i18nLanguages = new Set<string>();
-
-        Object.keys(envVariables).forEach((key) => {
-            try {
-                if (key.startsWith('GLOBAL.')) {
-                    // Global variable, we set it directly on the window object
-                    let globalKey = key.substring('GLOBAL.'.length);
-                    let globalObject = typeof window !== 'undefined' ? window : globalThis;
-                    (globalObject as any)[globalKey] = JSON.parse(envVariables[key]);
-                    console.log(`Codenotch global variable ${globalKey} set!`);
-                    return;
-                }
-                else if (key.startsWith("i18n.")) {
-                    // Special case
-                    let parts = key.split("."); // i18n.someKey.fr
-                    let language = parts[parts.length - 1]; // fr
-                    let keyName = parts.slice(1, parts.length - 1).join("."); // someKey
-                    i18nLanguages.add(language);
-
-                    let value = `${envVariables[key]}`.trim();
-                    if (value.startsWith('"') && value.endsWith('"')) {
-                        // Parse like json
-                        value = JSON.parse(value);
-                    }
-
-                    env.i18n = env.i18n ?? {};
-                    env.i18n[language] = env.i18n[language] ?? {};
-                    env.i18n[language][keyName] = value;
-                }
-                else {
-                    (env as any)[key] = envVariables[key];
-
-                    if (['appManifest', 'projectManifest'].includes(key)) {
-                        // Must be Json
-                        try {
-                            (env as any)[key] = JSON.parse(envVariables[key]);
-                        }
-                        catch (error) {
-                            console.warn(`Codenotch environment variable ${key} is not a valid JSON string. Using raw value.`);
-                        }
-                    }
-
-                    console.log(`Codenotch environment variable ${key} set to ${(env as any)[key]}`);
-                }
-            }
-            catch (error) {
-                console.error(`Error processing Codenotch environment variable ${key}:`, error);
-            }
-        });
-
-        if (env.language === undefined) {
-            // If current language is not defined, we set it to the first language found in i18n
-            if (i18nLanguages.size > 0) {
-                env.language = Array.from(i18nLanguages)[0];
-                console.log(`Codenotch current language set to ${env.language}`);
-            }
-        }
-
-    }
-
-    // Instantiate SignalR for further use in the API
-    if (env.clusterUrl && env.serviceName) {
-        signalR = new SignalR(env.clusterUrl, env.serviceName, false, env.accessToken);
-    }
-
-    // Get theme like AEC does
-    try {
-        let urlParams = Object.fromEntries(new URLSearchParams(window.location.search).entries());
-        if (urlParams["_theme"]) {
-            let theme = urlParams["_theme"].toLowerCase();
-            if (theme === "light" || theme === "dark") {
-                env.theme = theme;
-            }
-        }
-        else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
-            env.theme = 'dark';
-        }
-        else {
-            env.theme = 'light';
-        }
-    }
-    catch {
-    }
-}
-
-/**
- * Return the Codenotch client API bound to the current environment.
- *
- * Despite its name this is NOT a React hook — it is a plain function with no
- * hook rules attached: it can be called anywhere (components, handlers, plain
- * modules). `init()` must have been called first, which the Codenotch runtime
- * does automatically when serving the application.
- *
- * @returns The Codenotch API: BPMN processes, CNQL queries, i18n, signals, theme…
- * @example
- * import { useCodenotch } from 'codenotch-react';
- *
- * const MyApp: React.FC = () => {
- *     const cn = useCodenotch();
- *     return <h1>{cn.i18n('welcome')}</h1>;
- * };
- */
-function useCodenotch(): ICodenotchApi {
-    return {
-        env: env,
-        uuid: () => v4(),
-        getProjectFileUrl: (relativePath: string): string => {
-            if (env.clusterUrl === undefined) throw new Error(MISSING_CLUSTER_URL_ERROR);
-            if (env.serviceName === undefined) throw new Error(MISSING_SERVICE_NAME_ERROR);
-            relativePath = relativePath.replace(/\\/g, "/");
-            if (relativePath.startsWith("/")) relativePath = relativePath.substring(1);
-            let url = `${env.clusterUrl}/${env.serviceName}/project/file?name=""&path=${encodeURIComponent(relativePath)}`;
-            return url;
-        },
-        getProjectFile: async (relativePath: string): Promise<string | undefined> => {
-            let url = useCodenotch().getProjectFileUrl(relativePath);
-            let resp = await fetch(url);
-            if (resp.status.toString().startsWith('2') === false) {
-                throw new Error(`Failed to fetch file content: ${resp.status} ${resp.statusText}`);
-            }
-            let content = await resp.text();
-            return content;
-        },
-        requestCnql: async (cnql: string, verbose?: boolean): Promise<any> => {
-            if (env.clusterUrl === undefined) throw new Error(MISSING_CLUSTER_URL_ERROR);
-            if (env.serviceName === undefined) throw new Error(MISSING_SERVICE_NAME_ERROR);
-
-            const request: RequestInit = {
-                method: 'POST',
-                mode: 'cors',
-                credentials: 'same-origin',
-                headers: { 'Content-Type': 'application/json' },
-                body: `"${cnql.replace(/\"/g, '\\\"')}"`
-            };
-
-            if (`${env.accessToken ?? ''}`.trim() !== "") {
-                if (env.tenantName === undefined) throw new Error(MISSING_TENANT_NAME_ERROR);
-                request.headers = {
-                    ...request.headers, [`${env.tenantName}AccessToken`]: env.accessToken!
-                };
-            }
-
-            const response = await fetch(`${env.clusterUrl}/${env.serviceName}/cnql${verbose ? "?v=true" : ""}`, request);
-            if (!response.ok) {
-                const error = await response.text();
-                throw new Error(error);
-            }
-
-            return await response.json();
-        },
-        i18n: (key: string, ...args: any[]): string => {
-            try {
-                if (env.i18n === undefined || Object.keys(env.i18n).length === 0) {
-                    console.warn("Codenotch i18n is not defined. Please set it in the Codenotch configuration.");
-                    return key;
-                }
-
-                let language = env.language ?? "en";
-                let isLanguageExists = env.i18n[language] !== undefined;
-                if (isLanguageExists === false) {
-                    let fallbackLanguage = Object.keys(env.i18n)[0];
-                    console.warn(`Codenotch i18n language ${language} is not defined. Falling back to ${fallbackLanguage}. Please set the correct language in the Codenotch configuration.`);
-                    language = fallbackLanguage;
-                }
-
-                let dico = env.i18n[language];
-                let value = dico[key];
-
-                if (typeof value !== "string") {
-                    console.warn(`Codenotch i18n key ${key} is not defined for language ${language}. Please set it in the Codenotch configuration.`);
-                    return key;
-                }
-                args = args ?? [];
-
-                let result = value.replace(/{([\d ]*)}/g, (match, p1) => {
-                    let argValue = args[p1.trim()];
-                    // Instead of returning 'undefined', returns an empty string
-                    return argValue !== undefined ? argValue : "";
-                });
-
-                return result;
-            }
-            catch (error) {
-                console.error("Error in i18n function:", error);
-                return key;
-            }
-        },
-        startProcess: async (processName: any, startNodeId: any, inputs: any): Promise<IProcessResult> => {
-            if (env.clusterUrl === undefined) throw new Error(MISSING_CLUSTER_URL_ERROR);
-            if (env.serviceName === undefined) throw new Error(MISSING_SERVICE_NAME_ERROR);
-            if (env.tenantName === undefined) throw new Error(MISSING_TENANT_NAME_ERROR);
-            if (signalR === undefined) throw new Error("SignalR not available. Cannot start process.");
-            return ProcessUtils.startProcess((processInstanceId, callbacks) => signalR!.subscribeToProcessInstance(processInstanceId, callbacks),
-                env.clusterUrl,
-                env.tenantName,
-                env.serviceName,
-                processName,
-                inputs,
-                undefined,
-                startNodeId ?? 'start',
-                env.accessToken);
-        },
-        getUrlParams: () => {
-            let result: { [key: string]: string } = {};
-            if (typeof window !== 'undefined') {
-                const params = new URL(window.location.href).searchParams;
-                params.forEach((value: string, key: string) => {
-                    if (result[key] === undefined) {
-                        result[key] = value;
-                    }
-                });
-            }
-            return result;
-        },
-        showDialog: (node: JSX.Element): ICodenotchDialog => {
-            let dialogId = "codenotch-dialog-" + Math.random().toString(36).substring(2, 9);
-            let result: ICodenotchDialog = {
-                id: dialogId,
-                close: () => {
-                    let dialogElement = document.getElementById(dialogId);
-                    if (dialogElement) {
-                        dialogElement.remove();
-                    }
-                }
-            };
-
-            // Find "cn-dialog-container" element in the page
-            let container = document.getElementById("cn-dialog-container");
-            if (container === null) {
-                container = document.createElement("div");
-                container.id = "cn-dialog-container";
-                container.style.zIndex = "9999";
-                container.style.position = "fixed";
-                container.style.top = "0";
-                container.style.left = "0";
-                container.style.minWidth = "100vw";
-                container.style.minHeight = "100vh";
-                container.style.maxWidth = "100vw";
-                container.style.maxHeight = "100vh";
-                container.style.display = "flex";
-                container.style.alignItems = "center";
-                container.style.justifyContent = "center";
-                container.style.pointerEvents = 'none';
-                document.body.appendChild(container);
-            }
-
-            let dialogElement = document.createElement('dialog');
-            dialogElement.id = dialogId;
-            dialogElement.style.zIndex = "9999";
-            dialogElement.style.position = "fixed";
-            dialogElement.style.top = "0";
-            dialogElement.style.left = "0";
-            dialogElement.style.minWidth = "100vw";
-            dialogElement.style.minHeight = "100vh";
-            dialogElement.style.maxWidth = "100vw";
-            dialogElement.style.maxHeight = "100vh";
-            dialogElement.style.display = "flex";
-            dialogElement.style.alignItems = "center";
-            dialogElement.style.justifyContent = "center";
-            dialogElement.style.pointerEvents = 'all';
-            dialogElement.style.background = '#78787822';
-            dialogElement.style.backdropFilter = 'blur(2px)';
-
-            container.appendChild(dialogElement);
-
-            ReactDOM.render(node, dialogElement, () => {
-                dialogElement.showModal();
-            });
-
-            return result;
-        },
-        listenSignal: async (signalId: string, callback: (data: any) => void): Promise<IDisposable> => {
-
-            if (!signalR) {
-                throw new Error("SignalR not available. Cannot listen to signal.");
-            }
-
-            let unsubscribeFunc = await signalR.subscribeToSignal(signalId, callback);
-
-            return {
-                dispose: () => {
-                    unsubscribeFunc();
-                }
-            };
-
-        },
-        setTheme: (theme: 'light' | 'dark') => {
-            if (env.theme === theme) return;
-            if (env.theme) document.documentElement.classList.remove(env.theme);
-
-            env.theme = theme;
-            document.documentElement.classList.add(theme);
-        },
-        setLanguage: (lang: string) => {
-            if (env.language === lang) return;
-            env.language = lang;
-        },
-        getLanguages: () => {
-            return env.projectManifest?.languages ?? [];
-        },
-        getLanguage: () => {
-            return env.language;
-        },
-        getTheme: () => {
-            return env.theme;
-        },
-        getProjectManifest: () => {
-            if (env.projectManifest === undefined) {
-                throw new Error("Project manifest is not defined in Codenotch environment. Please set it in the Codenotch configuration.");
-            }
-            return env.projectManifest;
-        },
-        getAppManifest: () => {
-            return env.appManifest;
-        }
-    };
-}
-
-export {
-    env,
-    useCodenotch,
-    init,
-    CodeEditor
-};
-
-// Public models. Re-exported from the package root so that the typings
-// generated by the Codenotch IDE (typings/i18n.d.ts and typings/process.d.ts,
-// which augment the 'codenotch-react' module) merge with the real
-// TranslationRegistry / ProcessRegistry declarations.
-export * from "./models/Codenotch";
-export * from "./models/Misc";
+import { createElement, useSyncExternalStore, type ComponentType, type ComponentProps, type FunctionComponent, type ReactNode, type RefAttributes } from "react";
+import { flushSync } from "react-dom";
+import { createRoot, Root } from "react-dom/client";
+import { IDisposable } from "./models/Misc";
+import { ICodenotchApi, ICodenotchDialog, ICodenotchEnv, IProcessResult, WithCodenotchProps } from "./models/Codenotch";
+import { v4 } from "uuid";
+import CodeEditor from "./components/CodeEditor";
+
+/**
+ * The Codenotch runtime environment, populated by {@link init}.
+ * Prefer reading it through `useCodenotch().env`.
+ */
+const env: ICodenotchEnv = {};
+
+const MISSING_CLUSTER_URL_ERROR = "Codenotch cluster URL is not defined. Please set it in the Codenotch configuration.";
+const MISSING_SERVICE_NAME_ERROR = "Codenotch service name is not defined. Please set it in the Codenotch configuration.";
+const MISSING_TENANT_NAME_ERROR = "Codenotch tenant name is not defined. Please set it in the Codenotch configuration.";
+
+// ---------------------------------------------------------------------------
+// Change tracking. `env` is a plain mutable object; every mutation done through
+// the public API (init, setTheme, setLanguage) goes through notify(), which
+// rotates the API object (so React sees a new reference) and wakes up the
+// subscribers: useCodenotch() via useSyncExternalStore, withCodenotch(),
+// and any listener registered with onCodenotchChange().
+// ---------------------------------------------------------------------------
+const listeners = new Set<() => void>();
+let currentApi: ICodenotchApi;
+
+function notify(): void {
+    currentApi = createApi();
+    listeners.forEach((listener) => {
+        try { listener(); }
+        catch (error) { console.error("Error in Codenotch change listener:", error); }
+    });
+}
+
+function subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+
+/**
+ * Initialize the Codenotch environment from the given key-value pairs.
+ *
+ * This is normally called once, by the page hosting the application, with the
+ * environment variables injected by the Codenotch runtime (URL parameters or
+ * any other source). It must be called before `useCodenotch()` is used.
+ *
+ * Recognized key formats:
+ *   The first language found becomes the current language if none is set.
+ * - `GLOBAL.<name>` — JSON value assigned to `window[name]` (or `globalThis`).
+ * - `appManifest` / `projectManifest` — parsed as JSON into the environment.
+ * - anything else — copied as-is onto {@link env}.
+ *
+ * The UI theme is resolved from the `_theme` URL parameter, or from
+ * `prefers-color-scheme` as a fallback.
+ *
+ * @param envVariables An object containing the Codenotch environment variables as key-value pairs.
+ * @example
+ * import { init } from 'codenotch-react';
+ * init({
+ *     clusterUrl: 'https://cluster.example.com',
+ *     serviceName: 'myproject',
+ *     tenantName: 'acme'
+ * });
+ */
+function init(envVariables: any): void {
+
+
+    // Ensure envVariables is an object
+    if (typeof envVariables === 'object' && envVariables !== null) {
+
+        Object.keys(envVariables).forEach((key) => {
+            try {
+                if (key.startsWith('GLOBAL.')) {
+                    // Global variable, we set it directly on the window object
+                    let globalKey = key.substring('GLOBAL.'.length);
+                    let globalObject = typeof window !== 'undefined' ? window : globalThis;
+                    (globalObject as any)[globalKey] = JSON.parse(envVariables[key]);
+                    console.log(`Codenotch global variable ${globalKey} set!`);
+                    return;
+                }
+                else {
+                    (env as any)[key] = envVariables[key];
+
+                    if (['appManifest', 'projectManifest'].includes(key)) {
+                        // Must be Json
+                        try {
+                            (env as any)[key] = JSON.parse(envVariables[key]);
+                        }
+                        catch (error) {
+                            console.warn(`Codenotch environment variable ${key} is not a valid JSON string. Using raw value.`);
+                        }
+                    }
+
+                    console.log(`Codenotch environment variable ${key} set to ${(env as any)[key]}`);
+                }
+            }
+            catch (error) {
+                console.error(`Error processing Codenotch environment variable ${key}:`, error);
+            }
+        });
+    }
+
+    // Get theme like AEC does
+    try {
+        let urlParams = Object.fromEntries(new URLSearchParams(window.location.search).entries());
+        if (urlParams["_theme"]) {
+            let theme = urlParams["_theme"].toLowerCase();
+            if (theme === "light" || theme === "dark") {
+                env.theme = theme;
+            }
+        }
+        else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+            env.theme = 'dark';
+        }
+        else {
+            env.theme = 'light';
+        }
+    }
+    catch {
+    }
+
+    notify();
+}
+
+/**
+ * Build the API object bound to {@link env}. Every method reads `env` lazily,
+ * so an instance never goes stale; a new one is created by {@link notify} only
+ * to give React a fresh reference when the environment changes.
+ */
+function createApi(): ICodenotchApi {
+    const api: ICodenotchApi = {
+        env: env,
+        uuid: () => v4(),
+        getProjectFileUrl: (relativePath: string): string => {
+            if (env.clusterUrl === undefined) throw new Error(MISSING_CLUSTER_URL_ERROR);
+            if (env.serviceName === undefined) throw new Error(MISSING_SERVICE_NAME_ERROR);
+            relativePath = relativePath.replace(/\\/g, "/");
+            if (relativePath.startsWith("/")) relativePath = relativePath.substring(1);
+            let url = `${env.clusterUrl}/${env.serviceName}/project/file?name=""&path=${encodeURIComponent(relativePath)}`;
+            return url;
+        },
+        getProjectFile: async (relativePath: string): Promise<string | undefined> => {
+            let url = api.getProjectFileUrl(relativePath);
+            let resp = await fetch(url);
+            if (resp.status.toString().startsWith('2') === false) {
+                throw new Error(`Failed to fetch file content: ${resp.status} ${resp.statusText}`);
+            }
+            let content = await resp.text();
+            return content;
+        },
+        requestCnql: async (cnql: string, verbose?: boolean): Promise<any> => {
+            if (env.clusterUrl === undefined) throw new Error(MISSING_CLUSTER_URL_ERROR);
+            if (env.serviceName === undefined) throw new Error(MISSING_SERVICE_NAME_ERROR);
+
+            const request: RequestInit = {
+                method: 'POST',
+                mode: 'cors',
+                credentials: 'same-origin',
+                headers: { 'Content-Type': 'application/json' },
+                body: `"${cnql.replace(/\"/g, '\\\"')}"`
+            };
+
+            if (`${env.accessToken ?? ''}`.trim() !== "") {
+                if (env.tenantName === undefined) throw new Error(MISSING_TENANT_NAME_ERROR);
+                request.headers = {
+                    ...request.headers, [`${env.tenantName}AccessToken`]: env.accessToken!
+                };
+            }
+
+            const response = await fetch(`${env.clusterUrl}/${env.serviceName}/cnql${verbose ? "?v=true" : ""}`, request);
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(error);
+            }
+
+            return await response.json();
+        },
+        startProcess: async <TProcess, TInput, TOutput>(process: TProcess, inputs: TInput): Promise<IProcessResult<TOutput>> => {
+            throw new Error('Not implemented.');
+        },
+        getUrlParams: () => {
+            let result: { [key: string]: string } = {};
+            if (typeof window !== 'undefined') {
+                const params = new URL(window.location.href).searchParams;
+                params.forEach((value: string, key: string) => {
+                    if (result[key] === undefined) {
+                        result[key] = value;
+                    }
+                });
+            }
+            return result;
+        },
+        showDialog: (node: ReactNode): ICodenotchDialog => {
+            let dialogId = "codenotch-dialog-" + Math.random().toString(36).substring(2, 9);
+            let root: Root | undefined = undefined;
+            let result: ICodenotchDialog = {
+                id: dialogId,
+                close: () => {
+                    // Unmount the React tree first so effects are cleaned up and nothing leaks,
+                    // then drop the <dialog> element itself.
+                    root?.unmount();
+                    root = undefined;
+                    let dialogElement = document.getElementById(dialogId);
+                    if (dialogElement) {
+                        dialogElement.remove();
+                    }
+                }
+            };
+
+            // Find "cn-dialog-container" element in the page
+            let container = document.getElementById("cn-dialog-container");
+            if (container === null) {
+                container = document.createElement("div");
+                container.id = "cn-dialog-container";
+                container.style.zIndex = "9999";
+                container.style.position = "fixed";
+                container.style.top = "0";
+                container.style.left = "0";
+                container.style.minWidth = "100vw";
+                container.style.minHeight = "100vh";
+                container.style.maxWidth = "100vw";
+                container.style.maxHeight = "100vh";
+                container.style.display = "flex";
+                container.style.alignItems = "center";
+                container.style.justifyContent = "center";
+                container.style.pointerEvents = 'none';
+                document.body.appendChild(container);
+            }
+
+            let dialogElement = document.createElement('dialog');
+            dialogElement.id = dialogId;
+            dialogElement.style.zIndex = "9999";
+            dialogElement.style.position = "fixed";
+            dialogElement.style.top = "0";
+            dialogElement.style.left = "0";
+            dialogElement.style.minWidth = "100vw";
+            dialogElement.style.minHeight = "100vh";
+            dialogElement.style.maxWidth = "100vw";
+            dialogElement.style.maxHeight = "100vh";
+            dialogElement.style.display = "flex";
+            dialogElement.style.alignItems = "center";
+            dialogElement.style.justifyContent = "center";
+            dialogElement.style.pointerEvents = 'all';
+            dialogElement.style.background = '#78787822';
+            dialogElement.style.backdropFilter = 'blur(2px)';
+
+            container.appendChild(dialogElement);
+
+            // React 19: ReactDOM.render() is gone. Render synchronously through a dedicated root
+            // so the content is in the DOM before showModal() moves the focus into the dialog.
+            root = createRoot(dialogElement);
+            flushSync(() => root!.render(node));
+            dialogElement.showModal();
+
+            return result;
+        },
+        setTheme: (theme: 'light' | 'dark') => {
+            if (env.theme === theme) return;
+            if (env.theme) document.documentElement.classList.remove(env.theme);
+
+            env.theme = theme;
+            document.documentElement.classList.add(theme);
+            notify();
+        },
+        setLanguage: (lang: string) => {
+            if (env.language === lang) return;
+            env.language = lang;
+            notify();
+        },
+        getLanguages: () => {
+            return env.projectManifest?.languages ?? [];
+        },
+        getLanguage: () => {
+            return env.language;
+        },
+        getTheme: () => {
+            return env.theme;
+        },
+        getProjectManifest: () => {
+            if (env.projectManifest === undefined) {
+                throw new Error("Project manifest is not defined in Codenotch environment. Please set it in the Codenotch configuration.");
+            }
+            return env.projectManifest;
+        },
+        getAppManifest: () => {
+            return env.appManifest;
+        }
+    };
+    return api;
+}
+
+currentApi = createApi();
+
+/**
+ * Return the Codenotch client API bound to the current environment, from
+ * anywhere: event handlers, plain modules, class components, services…
+ *
+ * This is a plain function (not a hook). The returned object is never stale —
+ * its methods always read the live environment — but it does not trigger any
+ * re-render when the language or theme changes: inside React components prefer
+ * {@link useCodenotch} (function components) or {@link withCodenotch}
+ * (class components), which do.
+ *
+ * `init()` must have been called first, which the Codenotch runtime does
+ * automatically when serving the application.
+ *
+ * @example
+ * import { getCodenotch } from 'codenotch-react';
+ *
+ * export async function loadTodos(userId: string) {
+ *     const result = await getCodenotch().startProcess('getTodos', 'start', { UserId: userId });
+ *     return result.output.todos;
+ * }
+ */
+function getCodenotch(): ICodenotchApi {
+    return currentApi;
+}
+
+/**
+ * React hook returning the Codenotch client API.
+ *
+ * The reference is stable across renders and only changes when the environment
+ * changes (`setLanguage`, `setTheme`, `init`), in which case every component
+ * using the hook re-renders output follows the current
+ * language automatically, and the object is safe to use in `useMemo` /
+ * `useEffect` dependency arrays.
+ *
+ * Regular hook rules apply (call it unconditionally at the top of a function
+ * component or a custom hook). Outside of components — handlers defined in
+ * plain modules, services, class components — use {@link getCodenotch} or
+ * {@link withCodenotch} instead.
+ */
+function useCodenotch(): ICodenotchApi {
+    return useSyncExternalStore(subscribe, getCodenotch, getCodenotch);
+}
+
+/**
+ * Register a listener called each time the Codenotch environment changes
+ * (`setLanguage`, `setTheme`, `init`). Escape hatch for code that cannot use
+ * {@link useCodenotch} or {@link withCodenotch}, e.g. a class component that
+ * wants to `forceUpdate()` itself, or a non-React module caching translations.
+ *
+ * @returns A disposable — call `dispose()` to stop listening.
+ * @example
+ * componentDidMount() {
+ *     this.sub = onCodenotchChange(() => this.forceUpdate());
+ * }
+ * componentWillUnmount() {
+ *     this.sub.dispose();
+ * }
+ */
+function onCodenotchChange(listener: () => void): IDisposable {
+    const unsubscribe = subscribe(listener);
+    return { dispose: unsubscribe };
+}
+
+/** Props of a component wrapped by {@link withCodenotch}, without the injected `cn`. */
+type WithoutCodenotchProps<P> = Omit<P, keyof WithCodenotchProps>;
+
+/** Instance type of a component (class components only), used to type the forwarded `ref`. */
+type ComponentInstance<C> = C extends new (...args: any[]) => infer I ? I : never;
+
+/**
+ * Higher-order component injecting the Codenotch API as a `cn` prop.
+ *
+ * Meant for class components, which cannot call {@link useCodenotch}: the
+ * wrapped component receives `this.props.cn` and re-renders whenever the
+ * environment changes (language, theme…), exactly like the hook. A `ref`
+ * passed to the wrapper is forwarded to the wrapped component instance.
+ *
+ * @param Component A component whose props extend {@link WithCodenotchProps}.
+ * @returns A component with the same props minus `cn`.
+ */
+function withCodenotch<C extends ComponentType<any>>(
+    Component: C
+): FunctionComponent<WithoutCodenotchProps<ComponentProps<C>> & RefAttributes<ComponentInstance<C>>> {
+    const Wrapped = (props: WithoutCodenotchProps<ComponentProps<C>> & RefAttributes<ComponentInstance<C>>) => {
+        const cn = useCodenotch();
+        // React 19: `ref` is a regular prop, so spreading `props` forwards it.
+        return createElement(Component, { ...props, cn });
+    };
+    Wrapped.displayName = `withCodenotch(${Component.displayName || Component.name || "Component"})`;
+    return Wrapped;
+}
+
+export {
+    env,
+    useCodenotch,
+    getCodenotch,
+    withCodenotch,
+    onCodenotchChange,
+    init,
+    CodeEditor
+};
+
+export * from "./models/Codenotch";
+export * from "./models/Misc";
 export * from "@codenotch/codenotch.core";