= { size, pixelRatio, dpi };
+ if (name) {
+ event.name = name;
+ }
+ if (trame && name) {
+ trame.state.set(name, event);
+ }
+ onChange?.(event);
+ }
+
+ const sizeObserver = new ResizeObserver(resize);
+ sizeObserver.observe(elem.current as Element);
+ return () => sizeObserver.disconnect();
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [name]);
+
+ return (
+
+ {slot ? slot() : null}
+
+ );
+}
diff --git a/react-app/src/components/TrameStyle.tsx b/react-app/src/components/TrameStyle.tsx
new file mode 100644
index 0000000..dfc42d2
--- /dev/null
+++ b/react-app/src/components/TrameStyle.tsx
@@ -0,0 +1,44 @@
+import { useEffect, useRef } from "react";
+
+let ID = 1;
+
+import type { SlotFn } from "../types";
+
+export default function TrameStyle({
+ css = "",
+ slot,
+}: {
+ css?: string;
+ slot?: SlotFn;
+}) {
+ const elemId = useRef(null);
+ if (elemId.current === null) {
+ elemId.current = `trame_style_elem_${ID++}`;
+ }
+
+ useEffect(() => {
+ let elem = document.querySelector(`#${elemId.current}`) as any;
+ if (css) {
+ if (!elem) {
+ elem = document.createElement("style");
+ elem.id = elemId.current as string;
+ document.head.appendChild(elem);
+ }
+ elem.innerHTML = css;
+ } else if (elem) {
+ elem.parentNode.removeChild(elem);
+ }
+ }, [css]);
+
+ useEffect(
+ () => () => {
+ const elem = document.querySelector(`#${elemId.current}`) as any;
+ if (elem) {
+ elem.parentNode.removeChild(elem);
+ }
+ },
+ [],
+ );
+
+ return slot ? slot() : null;
+}
diff --git a/react-app/src/components/TrameTemplate.tsx b/react-app/src/components/TrameTemplate.tsx
new file mode 100644
index 0000000..cbfd940
--- /dev/null
+++ b/react-app/src/components/TrameTemplate.tsx
@@ -0,0 +1,67 @@
+// Renders one server-defined template (trame__template_ state key).
+// The payload is the JSON component tree produced by trame_client
+// (utils/react.py) when the server runs with client_type="react".
+
+import { useEffect, useMemo } from "react";
+import vtkURLExtract from "@kitware/vtk.js/Common/Core/URLExtract";
+import TrameNode from "../renderer/TrameNode";
+import { useTrame, useTrameState } from "../renderer/hooks";
+import type { TrameJsonNode, TrameTemplatePayload } from "../types";
+
+function extractRoot(payload: unknown): TrameJsonNode | null {
+ if (!payload) return null;
+ if (typeof payload === "string") {
+ try {
+ const parsed = JSON.parse(payload) as TrameTemplatePayload;
+ return parsed.root ?? null;
+ } catch (e) {
+ console.error("trame: invalid react template payload", e);
+ return null;
+ }
+ }
+ const { root } = payload as TrameTemplatePayload;
+ return root ?? null;
+}
+
+export default function TrameTemplate({
+ templateName = "main",
+ urlKey = "ui",
+ useUrl = false,
+ stateKey = null,
+}: {
+ templateName?: string;
+ urlKey?: string;
+ useUrl?: boolean;
+ stateKey?: string | null;
+}) {
+ const trame = useTrame();
+ useTrameState(); // template-wide re-render on any dirty state
+
+ let name = templateName;
+ const urlParams = vtkURLExtract.extractURLParameters() as Record<
+ string,
+ string
+ >;
+ if (useUrl && urlParams[urlKey]) {
+ name = urlParams[urlKey];
+ }
+ const key = stateKey || `trame__template_${name}`;
+ const payload = trame.state.get(key);
+ const root = useMemo(() => extractRoot(payload), [payload]);
+
+ // favicon / title side effects (parity with vue clients)
+ const favicon = trame.state.get("trame__favicon");
+ const title = trame.state.get("trame__title");
+ useEffect(() => {
+ if (favicon) {
+ (document.querySelector("link[rel=icon]") as HTMLLinkElement).href =
+ favicon;
+ }
+ }, [favicon]);
+ useEffect(() => {
+ if (title) document.title = title;
+ }, [title]);
+
+ if (!root) return null;
+ return ;
+}
diff --git a/react-app/src/components/index.ts b/react-app/src/components/index.ts
new file mode 100644
index 0000000..e0ba926
--- /dev/null
+++ b/react-app/src/components/index.ts
@@ -0,0 +1,39 @@
+// Built-in component registration (react port of vue3-app use.js + registry)
+
+import TrameClientStateChange from "./TrameClientStateChange";
+import TrameClientTriggers from "./TrameClientTriggers";
+import TrameDeepReactive from "./TrameDeepReactive";
+import TrameExec from "./TrameExec";
+import TrameGetter from "./TrameGetter";
+import TrameHandler from "./TrameHandler";
+import TrameLifeCycleMonitor from "./TrameLifeCycleMonitor";
+import TrameLoading from "./TrameLoading";
+import TrameReconnect from "./TrameReconnect";
+import TrameScript from "./TrameScript";
+import TrameSizeObserver from "./TrameSizeObserver";
+import TrameStyle from "./TrameStyle";
+import TrameTemplate from "./TrameTemplate";
+
+const COMPONENTS = {
+ "trame-client-state-change": TrameClientStateChange,
+ "trame-client-triggers": TrameClientTriggers,
+ "trame-deep-reactive": TrameDeepReactive,
+ "trame-exec": TrameExec,
+ "trame-getter": TrameGetter,
+ "trame-handler": TrameHandler,
+ "trame-life-cycle-monitor": TrameLifeCycleMonitor,
+ "trame-loading": TrameLoading,
+ "trame-reconnect": TrameReconnect,
+ "trame-script": TrameScript,
+ "trame-size-observer": TrameSizeObserver,
+ "trame-style": TrameStyle,
+ "trame-template": TrameTemplate,
+};
+
+import type { Registry } from "../types";
+
+export default function registerComponents(registry: Registry) {
+ Object.entries(COMPONENTS).forEach(([tag, component]) => {
+ registry.register(tag, component);
+ });
+}
diff --git a/react-app/src/core/trame/decorators.js b/react-app/src/core/trame/decorators.js
new file mode 100644
index 0000000..2389ba6
--- /dev/null
+++ b/react-app/src/core/trame/decorators.js
@@ -0,0 +1,118 @@
+const CTX = {};
+
+function compareDecorator(a, b) {
+ return a.priority - b.priority;
+}
+
+export function setAddAttachment(fn) {
+ CTX.addAttachement = fn;
+}
+
+export const fileHandler = {
+ priority: 0,
+ async decorate(value) {
+ if (value === null || value === undefined) return value;
+ if (value.constructor && value.constructor === File) {
+ const { name, lastModified, size, type } = value;
+
+ // Will be null in the event of an error on read, DataView otherwise
+ let content = null;
+ // Will be an error string if content failed to read, null otherwise
+ let error = null;
+
+ try {
+ const arrayBuffer = await new Promise((resolve, reject) => {
+ const reader = new FileReader();
+ reader.addEventListener("loadend", () => {
+ resolve(reader.result);
+ });
+ reader.addEventListener("error", () => {
+ reject(reader.error);
+ });
+ reader.readAsArrayBuffer(value);
+ });
+
+ content = new DataView(arrayBuffer);
+ } catch (e) {
+ error = e?.message ?? String(e);
+ }
+
+ return {
+ name,
+ lastModified,
+ size,
+ type,
+ content,
+ error,
+ // used by server to prevent sending those fields back to JS
+ _filter: ["content"],
+ };
+ }
+ return value;
+ },
+};
+
+export const fileListHandler = {
+ priority: 0,
+ async decorate(value) {
+ if (value === null || value === undefined) return value;
+ if (typeof value === "string") {
+ return value;
+ }
+ if ((value.constructor && value.constructor === FileList) || value.length) {
+ const results = await Promise.allSettled(
+ Array.from(value).map((file) => fileHandler.decorate(file)),
+ );
+ return results.map((result) => result.value);
+ }
+ return value;
+ },
+};
+
+export const fileInObjectHandler = {
+ priority: 0,
+ async decorate(value) {
+ if (value === null || value === undefined) return value;
+ if (typeof value === "string") {
+ return value;
+ }
+ if (value.constructor && value.constructor === Object) {
+ const newValue = {};
+ const names = Object.keys(value);
+ /* eslint-disable no-await-in-loop */
+ for (let i = 0; i < names.length; i++) {
+ const name = names[i];
+ newValue[name] = value[name];
+ newValue[name] = await fileListHandler.decorate(newValue[name]);
+ newValue[name] = await fileHandler.decorate(newValue[name]);
+ }
+ /* eslint-enable no-await-in-loop */
+ return newValue;
+ }
+ return value;
+ },
+};
+
+// ----------------------------------------------------------------------------
+// API
+// ----------------------------------------------------------------------------
+
+const STATE_DECORATORS = [fileHandler, fileListHandler, fileInObjectHandler];
+
+export function registerDecorator(decorator) {
+ STATE_DECORATORS.push(decorator);
+ STATE_DECORATORS.sort(compareDecorator);
+}
+
+export async function decorate(value) {
+ let result = value;
+ /* eslint-disable no-await-in-loop */
+ for (let i = 0; i < STATE_DECORATORS.length; i++) {
+ if (result === null || result === undefined) {
+ return result;
+ }
+ result = await STATE_DECORATORS[i].decorate(result);
+ }
+ /* eslint-enable no-await-in-loop */
+ return result;
+}
diff --git a/react-app/src/core/trame/index.js b/react-app/src/core/trame/index.js
new file mode 100644
index 0000000..b9b42d3
--- /dev/null
+++ b/react-app/src/core/trame/index.js
@@ -0,0 +1,95 @@
+import wslink from "../wslink";
+import { SharedState } from "./state";
+import { decorate, setAddAttachment } from "./decorators";
+import utils from "../../utils";
+
+export function createTrameInstance(app) {
+ const trame = {
+ app,
+ client: null,
+ state: null,
+ config: null,
+ utils,
+ refs: {},
+ };
+ let listeners = [];
+ let initialized = false;
+
+ function isConnected() {
+ return initialized && trame?.client?.isConnected();
+ }
+
+ function notifyConnection() {
+ for (let i = 0; i < listeners.length; i++) {
+ listeners[i]();
+ }
+ }
+
+ trame.addConnectListener = function addConnectListener(listener) {
+ listeners.push(listener);
+ if (isConnected()) {
+ listener();
+ }
+ };
+
+ trame.removeConnectListener = function removeConnectListener(listener) {
+ listeners = listeners.filter((l) => l !== listener);
+ };
+
+ trame.connect = async function connect(config) {
+ if (!trame.client) {
+ trame.client = wslink.createClient();
+ }
+
+ if (trame.state) {
+ trame.state.delete();
+ trame.client = wslink.createClient();
+ }
+
+ if (!trame.client.isConnected()) {
+ await trame.client.connect(config);
+ }
+
+ setAddAttachment(trame.client.getConnection().getSession().addAttachment);
+ trame.state = new SharedState(trame.client);
+ trame.config = trame.client.getConfig();
+ await trame.state.loadState();
+
+ initialized = true;
+ notifyConnection();
+ return trame.config;
+ };
+
+ trame.trigger = async function trigger(name, args = [], kwargs = {}) {
+ let decoratedArgs = [];
+ const decoratedKwargs = {};
+
+ if (args) {
+ const decorateArgs = args.map((arg) => decorate(arg));
+ decoratedArgs = await Promise.all(decorateArgs);
+ }
+
+ if (kwargs) {
+ const keys = [];
+ const values = [];
+ Object.entries(kwargs).forEach((entry) => {
+ keys.push(entry[0]);
+ values.push(decorate(entry[1]));
+ });
+
+ const resolvedValues = await Promise.all(values);
+ for (let i = 0; i < keys.length; i++) {
+ decoratedKwargs[keys[i]] = resolvedValues[i];
+ }
+ }
+
+ return await trame.client
+ .getRemote()
+ .Trame.trigger(name, decoratedArgs, decoratedKwargs);
+ };
+
+ // Make it available globally
+ window.trame = trame;
+
+ return trame;
+}
diff --git a/react-app/src/core/trame/setup.js b/react-app/src/core/trame/setup.js
new file mode 100644
index 0000000..7c00f8a
--- /dev/null
+++ b/react-app/src/core/trame/setup.js
@@ -0,0 +1,154 @@
+// ----------------------------------------------------------------------------
+// Initialisation helpers
+// 1. trame__styles : list of url to load as css
+// 2. trame__scripts : list of url to load as scripts
+// 3. trame__react_use : list of registry plugins to load
+// 4. trame__favicon : favicon
+// 5. trame__title : browser tab title
+// ----------------------------------------------------------------------------
+
+var LOADED_URLS = [];
+
+function resolveWithError(resolve, msg) {
+ return () => {
+ console.error(msg);
+ resolve(false);
+ };
+}
+
+export function loadScript(url) {
+ return new Promise(function (resolve) {
+ if (LOADED_URLS.indexOf(url) === -1) {
+ LOADED_URLS.push(url);
+ var newScriptTag = document.createElement("script");
+ newScriptTag.type = "text/javascript";
+ newScriptTag.src = url;
+ newScriptTag.onload = resolve;
+ newScriptTag.onerror = resolveWithError(
+ resolve,
+ `Failed loading script ${url}`,
+ );
+ document.body.appendChild(newScriptTag);
+ } else {
+ resolve(false);
+ }
+ });
+}
+
+export function loadScriptAsModule(url) {
+ return new Promise(function (resolve) {
+ if (LOADED_URLS.indexOf(url) === -1) {
+ LOADED_URLS.push(url);
+ var newScriptTag = document.createElement("script");
+ newScriptTag.type = "module";
+ newScriptTag.src = url;
+ newScriptTag.onload = resolve;
+ newScriptTag.onerror = resolveWithError(
+ resolve,
+ `Failed loading script module ${url}`,
+ );
+ document.body.appendChild(newScriptTag);
+ } else {
+ resolve(false);
+ }
+ });
+}
+
+function loadCSS(url) {
+ return new Promise(function (resolve) {
+ if (LOADED_URLS.indexOf(url) === -1) {
+ LOADED_URLS.push(url);
+ var newScriptTag = document.createElement("link");
+ newScriptTag.rel = "stylesheet";
+ newScriptTag.href = url;
+ newScriptTag.onload = resolve;
+ newScriptTag.onerror = resolveWithError(
+ resolve,
+ `Failed loading css ${url}`,
+ );
+ document.head.appendChild(newScriptTag);
+ } else {
+ resolve(false);
+ }
+ });
+}
+
+async function serialLoad(urls, loadFn) {
+ for (let i = 0; i < urls.length; i++) {
+ /* eslint-disable no-await-in-loop */
+ await loadFn(urls[i]);
+ }
+}
+
+// ----------------------------------------------------------------------------
+
+function loadURLs(urls, loadFn) {
+ const mainGroup = [];
+ const serialGroups = {};
+ for (let i = 0; i < urls.length; i++) {
+ let container = mainGroup;
+ let url = urls[i];
+ if (Array.isArray(url)) {
+ const groupName = url[1].serial;
+ if (groupName) {
+ if (!serialGroups[groupName]) {
+ serialGroups[groupName] = [];
+ }
+ container = serialGroups[groupName];
+ }
+ [url] = url;
+ }
+ container.push(url);
+ }
+
+ const waitList = mainGroup.map(loadFn);
+ const serialScripts = Object.values(serialGroups);
+ for (let i = 0; i < serialScripts.length; i++) {
+ waitList.push(serialLoad(serialScripts[i], loadFn));
+ }
+
+ return Promise.all(waitList);
+}
+
+// ----------------------------------------------------------------------------
+// Resource management (script/css/react_use)
+// ----------------------------------------------------------------------------
+
+export async function handlePageResources(state) {
+ await loadURLs(state.trame__styles, loadCSS);
+ await loadURLs(state.trame__scripts, loadScript);
+ await loadURLs(state.trame__module_scripts, loadScriptAsModule);
+
+ if (state.trame__favicon) {
+ document.querySelector("link[rel=icon]").href = state.trame__favicon;
+ }
+
+ if (state.trame__title) {
+ document.title = state.trame__title;
+ }
+
+ const useEntries = state.trame__react_use || [];
+ return useEntries.map((libUseEntry) => {
+ let libKey = libUseEntry;
+ let libOptions = [];
+ if (Array.isArray(libUseEntry)) {
+ [libKey, ...libOptions] = libUseEntry;
+ }
+ let lib = window.eval(libKey);
+ for (let i = 0; i < libOptions.length; i++) {
+ const arg = libOptions[i];
+ if (arg.js_eval) {
+ libOptions[i] = window.eval(arg.js_eval);
+ }
+ }
+
+ // Invalid lib name
+ if (!lib) {
+ console.error(
+ `Lookup error: registry.use(${libKey}, ${JSON.stringify(libOptions)})`,
+ );
+ return;
+ }
+ return { name: libKey, plugin: lib, options: libOptions };
+ });
+}
diff --git a/react-app/src/core/trame/state.js b/react-app/src/core/trame/state.js
new file mode 100644
index 0000000..f3d2a98
--- /dev/null
+++ b/react-app/src/core/trame/state.js
@@ -0,0 +1,263 @@
+import { decorate, registerDecorator } from "./decorators";
+
+// ----------------------------------------------------------------------------
+// State helper
+// ----------------------------------------------------------------------------
+export class WatcherManager {
+ constructor() {
+ this.nextId = 1;
+ this.listeners = {};
+ }
+
+ watch(dependencies, callback) {
+ const key = `${this.nextId++}`;
+ this.listeners[key] = {
+ key,
+ dependencies,
+ callback,
+ };
+ const unsubscribe = () => delete this.listeners[key];
+ return unsubscribe;
+ }
+
+ notifyWatchers(changedKeys, fullState) {
+ const watchers = Object.values(this.listeners);
+ const keys = new Set(changedKeys);
+
+ for (let i = 0; i < watchers.length; i++) {
+ const { dependencies, callback } = watchers[i];
+ if (keys.intersection(new Set(dependencies)).size) {
+ const args = dependencies.map((v) => fullState[v]);
+ try {
+ callback(...args);
+ } catch (e) {
+ console.error(`Watcher error with dependencies: ${dependencies}`, e);
+ }
+ }
+ }
+ }
+
+ getWatchers() {
+ return Object.values(this.listeners);
+ }
+}
+
+export class SharedState {
+ constructor(client) {
+ this.name = "Default trame application";
+ this.client = client;
+ this.subscriptions = [];
+ this.dirtyKeys = new Set();
+ this.state = {};
+ this.keyTS = {};
+ this.mtime = 0;
+ this.listeners = [];
+ this.ready = false;
+ this._watchers = new WatcherManager();
+
+ // bind decorator helper
+ this.registerDecorator = registerDecorator;
+
+ const updateFromServer = async (serverState) => {
+ const updatedKeys = [];
+ const allKeys = Object.keys(serverState);
+ for (let i = 0; i < allKeys.length; i++) {
+ let modified = true;
+ const key = allKeys[i];
+ const value = serverState[key];
+
+ // Handle _filter field
+ if (value?._filter?.length) {
+ modified = false;
+ const prevValue = this.state[key];
+ const objKeys = Object.keys(value);
+ for (let j = 0; !modified && j < objKeys.length; j++) {
+ const subKey = objKeys[j];
+ if (subKey[0] === "_") {
+ continue;
+ }
+ if (
+ prevValue === undefined ||
+ prevValue[subKey] !== value[subKey]
+ ) {
+ modified = true;
+ }
+ }
+ }
+
+ if (modified) {
+ updatedKeys.push(key);
+ this.state[key] = value;
+ }
+ }
+
+ this.mtime += 1;
+ const newKeys = [];
+ for (let i = 0; i < updatedKeys.length; i++) {
+ const key = updatedKeys[i];
+ if (this.keyTS[key] === undefined) {
+ newKeys.push(key);
+ }
+ this.keyTS[key] = this.mtime;
+ }
+
+ if (newKeys.length > 0) {
+ this.notifyListeners({ type: "new-keys", keys: newKeys });
+ }
+
+ this.notifyListeners({ type: "dirty-state", keys: updatedKeys });
+ };
+
+ this.subscriptions.push(
+ this.client
+ .getRemote()
+ .Trame.subscribeToStateUpdate(([serverState]) =>
+ updateFromServer(serverState),
+ ),
+ );
+
+ this.subscriptions.push(
+ this.addListener(({ type, keys }) => {
+ if (type === "dirty-state") {
+ this._watchers.notifyWatchers(keys, this.state);
+ }
+ }),
+ );
+
+ // Keep it so we can call it on disconnect
+ this._updateFromServer = updateFromServer;
+ }
+
+ async loadState() {
+ const { state, name } = await this.client.getRemote().Trame.getState();
+ this.name = name;
+ this._updateFromServer(state);
+ this.notifyListeners({ type: "ready" });
+ this.ready = true;
+ }
+
+ notifyListeners(even) {
+ for (let i = 0; i < this.listeners.length; i++) {
+ this.listeners[i](even);
+ }
+ }
+
+ addListener(listener) {
+ this.listeners.push(listener);
+ }
+
+ removeListener(listener) {
+ this.listeners = this.listeners.filter((l) => l !== listener);
+ }
+
+ getAllKeys() {
+ return Object.keys(this.state);
+ }
+
+ getMutableStateKeys() {
+ const keysToRemove = new Set(this.state.trame__disable_mutation || []);
+ return this.getAllKeys().filter((v) => !keysToRemove.has(v));
+ }
+
+ delete() {
+ while (this.subscriptions.length) {
+ this.client.getRemote().Trame.unsubscribe(this.subscriptions.pop());
+ }
+ }
+
+ get(key) {
+ if (key === undefined) {
+ return this.state;
+ }
+ return this.state[key];
+ }
+
+ watch(keys, fn) {
+ const unsubscribe = this._watchers.watch(keys, fn);
+
+ // Call it right away with available values
+ fn(...keys.map((v) => this.state[v]));
+
+ return unsubscribe;
+ }
+
+ async set(key, value) {
+ // Prevent triggering change when same value is set
+ if (this.state[key] === value) {
+ return;
+ }
+
+ this.ts += 1;
+ this.state[key] = value;
+ this.keyTS[key] = this.ts;
+ this.dirty(key);
+ await this.flush();
+ }
+
+ async update(obj) {
+ this.ts += 1;
+ for (const [key, value] of Object.entries(obj)) {
+ if (this.state[key] !== value) {
+ this.state[key] = value;
+ this.keyTS[key] = this.ts;
+ this.dirty(key);
+ }
+ }
+ await this.flush();
+ }
+
+ canDirty(name) {
+ return !this.state.trame__client_only.includes(name);
+ }
+
+ dirty(...keys) {
+ keys.forEach((key) => {
+ if (this.canDirty(key)) {
+ this.dirtyKeys.add(key);
+ }
+ });
+ // Make sure client side is aware of that change...
+ this.notifyListeners({
+ type: "dirty-state",
+ keys,
+ });
+ }
+
+ async flush(...keys) {
+ if (keys.length) {
+ keys.forEach((key) => {
+ if (Array.isArray(key)) {
+ this.dirty(...key);
+ } else {
+ this.dirty(key);
+ }
+ });
+ }
+
+ if (this.dirtyKeys.size && !this.client.isBusy()) {
+ const waitOn = [];
+ const keys = [];
+ this.dirtyKeys.forEach((key) => {
+ waitOn.push(decorate(this.state[key]));
+ keys.push(key);
+ });
+ this.dirtyKeys.clear();
+ const values = await Promise.all(waitOn);
+ const deltaState = keys.map((key, i) => ({ key, value: values[i] }));
+ if (this.client.isConnected()) {
+ await this.client.getRemote().Trame.updateState(deltaState);
+ }
+
+ // Make sure we don't leave any pending update...
+ if (this.dirtyKeys.size) {
+ this.flush();
+ }
+ }
+
+ // when connection died, the client is busy...
+ if (!this.client.isConnected()) {
+ // Handle dynamic update once disconnected
+ this._updateFromServer(this.state);
+ }
+ }
+}
diff --git a/react-app/src/core/wslink/index.js b/react-app/src/core/wslink/index.js
new file mode 100644
index 0000000..c72a88f
--- /dev/null
+++ b/react-app/src/core/wslink/index.js
@@ -0,0 +1,92 @@
+import vtkURLExtract from "@kitware/vtk.js/Common/Core/URLExtract";
+import SmartConnect from "wslink/src/SmartConnect";
+import vtkWSLinkClient from "@kitware/vtk.js/IO/Core/WSLinkClient";
+
+import protocols from "./protocols";
+
+vtkWSLinkClient.setSmartConnectClass(SmartConnect);
+
+const WS_PROTOCOL = {
+ "http:": "ws:",
+ "https:": "wss:",
+ "ws:": "ws:",
+ "wss:": "wss:",
+};
+
+const NOT_BUSY_LIST = [
+ // *
+ "unsubscribe",
+ // SyncView
+ "subscribeToViewChange",
+ // Trame
+ "subscribeToStateUpdate",
+ "subscribeToActions",
+ "subscribeToViewChange",
+];
+
+function configDecorator(config) {
+ const outputConfig = { ...config };
+
+ // Process sessionURL
+ if (outputConfig.sessionURL) {
+ let sessionURL = outputConfig.sessionURL.toLowerCase();
+ const httpURL = window.location;
+
+ // handle protocol mapping http(s) => ws(s)
+ if (sessionURL.includes("use_")) {
+ const wsURL = new URL(sessionURL);
+ wsURL.protocol = WS_PROTOCOL[httpURL.protocol];
+ sessionURL = wsURL.toString();
+ }
+
+ // handle variable replacement
+ const use_mapping = {
+ use_hostname: httpURL.hostname,
+ use_host: httpURL.host,
+ };
+ for (const [key, value] of Object.entries(use_mapping)) {
+ sessionURL = sessionURL.replaceAll(key, value);
+ }
+
+ // update config
+ outputConfig.sessionURL = sessionURL;
+ }
+
+ // Extract app-name from html
+ outputConfig.application =
+ document.querySelector("html").dataset.appName || outputConfig.application;
+
+ // Extract retry from html
+ outputConfig.launcherRetry = JSON.parse(
+ document.querySelector("html").dataset.launcherRetry || "[]",
+ );
+
+ const sessionManagerURL =
+ document.querySelector("html").dataset.sessionManagerUrl ||
+ outputConfig.sessionManagerURL;
+ if (sessionManagerURL) {
+ outputConfig.sessionManagerURL = sessionManagerURL;
+ }
+
+ // Process arguments from URL
+ if (outputConfig.useUrl) {
+ return {
+ ...outputConfig,
+ ...vtkURLExtract.extractURLParameters(),
+ };
+ }
+ return outputConfig;
+}
+
+function createClient() {
+ return vtkWSLinkClient.newInstance({
+ protocols,
+ configDecorator,
+ notBusyList: NOT_BUSY_LIST,
+ });
+}
+
+export default {
+ configDecorator,
+ createClient,
+};
diff --git a/react-app/src/core/wslink/protocols/SyncView.js b/react-app/src/core/wslink/protocols/SyncView.js
new file mode 100644
index 0000000..b41b411
--- /dev/null
+++ b/react-app/src/core/wslink/protocols/SyncView.js
@@ -0,0 +1,30 @@
+export default (session) => ({
+ getArray(hash, binary = true) {
+ return session
+ .call("viewport.geometry.array.get", [hash, binary])
+ .then((res) => {
+ if (res.buffer) {
+ return new Blob([res]);
+ }
+ return res;
+ });
+ },
+ getViewState(viewId, newSubscription = false) {
+ return session.call("viewport.geometry.view.get.state", [
+ viewId,
+ newSubscription,
+ ]);
+ },
+ addViewObserver(viewId) {
+ return session.call("viewport.geometry.view.observer.add", [viewId]);
+ },
+ removeViewObserver(viewId) {
+ return session.call("viewport.geometry.view.observer.remove", [viewId]);
+ },
+ subscribeToViewChange(callback) {
+ return session.subscribe("viewport.geometry.view.subscription", callback);
+ },
+ unsubscribe(subscription) {
+ return session.unsubscribe(subscription);
+ },
+});
diff --git a/react-app/src/core/wslink/protocols/Trame.js b/react-app/src/core/wslink/protocols/Trame.js
new file mode 100644
index 0000000..088c491
--- /dev/null
+++ b/react-app/src/core/wslink/protocols/Trame.js
@@ -0,0 +1,26 @@
+export default (session) => ({
+ lifeCycleUpdate(phaseName) {
+ return session.call("trame.lifecycle.update", [phaseName]);
+ },
+ sendError(message) {
+ return session.call("trame.error.client", [message]);
+ },
+ getState() {
+ return session.call("trame.state.get", []);
+ },
+ trigger(name, args = [], kwargs = {}) {
+ return session.call("trame.trigger", [name, args, kwargs]);
+ },
+ updateState(changes) {
+ return session.call("trame.state.update", [changes]);
+ },
+ subscribeToStateUpdate(callback) {
+ return session.subscribe("trame.state.topic", callback);
+ },
+ subscribeToActions(callback) {
+ return session.subscribe("trame.actions.topic", callback);
+ },
+ unsubscribe(subscription) {
+ return session.unsubscribe(subscription);
+ },
+});
diff --git a/react-app/src/core/wslink/protocols/index.js b/react-app/src/core/wslink/protocols/index.js
new file mode 100644
index 0000000..4157b3b
--- /dev/null
+++ b/react-app/src/core/wslink/protocols/index.js
@@ -0,0 +1,7 @@
+import SyncView from "./SyncView";
+import Trame from "./Trame";
+
+export default {
+ SyncView,
+ Trame,
+};
diff --git a/react-app/src/main.tsx b/react-app/src/main.tsx
new file mode 100644
index 0000000..139d754
--- /dev/null
+++ b/react-app/src/main.tsx
@@ -0,0 +1,174 @@
+import "./style.css";
+import React from "react";
+import * as ReactDOMBase from "react-dom";
+import ReactDOM from "react-dom/client";
+import vtkURLExtract from "@kitware/vtk.js/Common/Core/URLExtract";
+import wslink from "./core/wslink";
+import { handlePageResources } from "./core/trame/setup";
+import { createTrameInstance } from "./core/trame";
+import { registerUserScripts } from "./user_script_handler";
+import { createMessageChannelWSFactory } from "./messageChannel";
+import registry from "./registry";
+import registerComponents from "./components";
+import TrameApp from "./components/TrameApp";
+import { TrameContext } from "./renderer/hooks";
+import type { TrameInstance } from "./types";
+
+// Widget library bundles build with react/react-dom as externals and resolve
+// them from the host page, so the whole page shares ONE React instance.
+// Expose the full react-dom namespace (createPortal, flushSync, ...) merged
+// with the client entry points (createRoot, hydrateRoot).
+window.React = React;
+window.ReactDOM = { ...ReactDOMBase, ...ReactDOM };
+
+function errorPayload(tag: string, message: string) {
+ return {
+ version: 1,
+ root: { tag, attrs: { message } },
+ };
+}
+
+async function start() {
+ // Check if we need to override websocket
+ try {
+ // Can throw exception if parent is cross-origin
+ const win = window as any;
+ if (!win.WSLINK && win?.parent?.trameJupyter?.init) {
+ win.WSLINK = win.parent.trameJupyter.init(window);
+ }
+ } catch {
+ // parent is cross-origin
+ }
+
+ const root = ReactDOM.createRoot(
+ document.querySelector("#app") as Element,
+ );
+ const trame = createTrameInstance(registry) as unknown as TrameInstance;
+ let config: any = wslink.configDecorator({
+ application: "trame",
+ useUrl: true,
+ });
+
+ // Clean URL params once config is generated
+ const params = new URL(window.location.href).searchParams;
+ const paramsToClean = [
+ "sessionURL",
+ "sessionManagerURL",
+ "secret",
+ "application",
+ "remove",
+ ].concat(params.get("remove")?.split(",") || []);
+ paramsToClean.forEach((v) => params.delete(v));
+ const cleanURL = `${window.location.pathname}${
+ params.size ? "?" : ""
+ }${params.toString()}${window.location.hash}`;
+ window.history.replaceState({}, document.title, cleanURL);
+
+ // Handle connection
+ trame.addConnectListener(() => {
+ trame.client.onConnectionError((httpReq: any) => {
+ reportWsError(httpReq?.response?.error || "Connection error");
+ });
+ trame.client.onConnectionClose((httpReq: any) => {
+ reportWsError(httpReq?.response?.error || "Connection closed");
+ });
+ });
+
+ // Handle client/server connection error
+ function reportWsError(message: string) {
+ if (trame && trame.state) {
+ trame.state.set("trame_error_report_msg", message);
+ let templateName = "trame__template_main";
+ const urlParams = vtkURLExtract.extractURLParameters() as any;
+ if (urlParams.ui) {
+ templateName = `trame__template_${urlParams.ui}`;
+ }
+ if (config.reconnect) {
+ trame.state.set(
+ templateName,
+ trame.state.get("trame__template_error_reconnect") ||
+ errorPayload("trame-reconnect", message),
+ );
+ } else {
+ trame.state.set(
+ templateName,
+ trame.state.get("trame__template_error") ||
+ errorPayload("trame-loading", message),
+ );
+ }
+ } else {
+ root.unmount();
+ const app = document.querySelector("#app");
+ if (app) app.innerHTML = message;
+ }
+ }
+
+ // Connect client to server
+ try {
+ config = await trame.connect(config);
+ } catch (e) {
+ reportWsError((e as any)?.response?.error || "try/catch on connect()");
+ return;
+ }
+
+ // Forward JS error to Python
+ const _error = console.error;
+ console.error = (...args) => {
+ try {
+ if (trame.client.isConnected()) {
+ trame.client.getRemote().Trame.sendError(args.join(" "));
+ }
+ } catch (e) {
+ _error(e);
+ } finally {
+ _error(...args);
+ }
+ };
+ window.addEventListener("error", (event) =>
+ console.error(`${event.type}: ${event.message}`),
+ );
+
+ // Setup trame app
+ registerComponents(registry);
+
+ // Load resources (js/css) and registry plugins
+ const uses: any[] = await handlePageResources(trame.state.state);
+ for (let i = 0; i < uses.length; i++) {
+ if (uses[i]) {
+ const { name, plugin, options } = uses[i];
+ registry.use(plugin, ...options);
+ console.info(`registry.use(${name})`);
+ }
+ }
+
+ root.render(
+
+
+ ,
+ );
+
+ registerUserScripts();
+}
+
+const urlParams = vtkURLExtract.extractURLParameters() as any;
+
+if (urlParams.wsChannel) {
+ window.addEventListener("message", (event) => {
+ // Waiting for message initializing channel communication
+ // for websocket proxying
+ if (event.data !== "trame-ws-channel-init") {
+ // not for us! skip
+ return;
+ }
+
+ // Grab communication port and register fake WebSocket
+ (window as any).WSLINK = {
+ createWebSocket: createMessageChannelWSFactory(event.ports[0]),
+ };
+
+ // Start trame client
+ start();
+ });
+} else {
+ start();
+}
diff --git a/react-app/src/messageChannel.js b/react-app/src/messageChannel.js
new file mode 100644
index 0000000..a5e893b
--- /dev/null
+++ b/react-app/src/messageChannel.js
@@ -0,0 +1,73 @@
+class MessageChannelWebSocket {
+ constructor(port) {
+ console.log("create MessageChannelWebSocket");
+ this._channel_port = port;
+ this.onmessage = null;
+ this.onclose = null;
+ this.onerror = null;
+
+ // Listen to channel messages
+ this._channel_port.onmessage = (e) => {
+ if (!this.onmessage) return;
+ const { a, b, t } = e.data;
+
+ if (a === "s") {
+ this.onmessage({ data: b || t });
+ return;
+ }
+ if (a === "c" && this.onclose) {
+ this.onclose(e.data.c);
+ return;
+ }
+ if (a === "e" && this.onerror) {
+ this.onerror(e.data.e);
+ return;
+ }
+ };
+ }
+
+ set onopen(callback) {
+ // Auto open but allow current listeners registration to complete before triggering
+ setTimeout(callback, 0);
+ }
+
+ send(data) {
+ console.log("send", data);
+ if (data.buffer) {
+ // may need a copy
+ if (data.buffer.byteLength !== data.length) {
+ const tmp = new Uint8Array(data.length);
+ tmp.set(data);
+ self._channel_port.postMessage(
+ {
+ a: "s",
+ b: tmp.buffer,
+ },
+ [tmp.buffer],
+ );
+ return;
+ }
+ self._channel_port.postMessage(
+ {
+ a: "s",
+ b: data.buffer,
+ },
+ [data.buffer],
+ );
+ return;
+ }
+ self._channel_port.postMessage({
+ a: "s",
+ t: data,
+ });
+ }
+
+ close() {
+ self._channel_port.postMessage({ a: "c", c: "Closing from client" });
+ self._channel_port.close();
+ }
+}
+
+export function createMessageChannelWSFactory(port) {
+ return () => new MessageChannelWebSocket(port);
+}
diff --git a/react-app/src/registry.ts b/react-app/src/registry.ts
new file mode 100644
index 0000000..fe52195
--- /dev/null
+++ b/react-app/src/registry.ts
@@ -0,0 +1,44 @@
+// Component registry: maps tags used in the server-sent JSON tree to React
+// components. Widget libraries (e.g. trame-mui) register their
+// components through the plugin interface:
+//
+// export default {
+// install(registry) {
+// registry.register("my-widget", MyWidget);
+// },
+// };
+
+import type { ComponentType } from "react";
+
+import type { Registry, RegistryPlugin } from "./types";
+
+const COMPONENTS = new Map>();
+
+export const registry: Registry = {
+ register(tag: string, component: ComponentType) {
+ if (COMPONENTS.has(tag)) {
+ console.warn(`registry: tag "${tag}" is being overridden`);
+ }
+ COMPONENTS.set(tag, component);
+ },
+ unregister(tag: string) {
+ COMPONENTS.delete(tag);
+ },
+ resolve(tag: string) {
+ return COMPONENTS.get(tag);
+ },
+ has(tag: string) {
+ return COMPONENTS.has(tag);
+ },
+ use(plugin: RegistryPlugin, ...options: unknown[]) {
+ if (typeof plugin === "object" && plugin?.install) {
+ plugin.install(registry, ...options);
+ } else if (typeof plugin === "function") {
+ plugin(registry, ...options);
+ } else {
+ console.error("registry.use: plugin has no install()", plugin);
+ }
+ },
+};
+
+export default registry;
diff --git a/react-app/src/renderer/TrameNode.tsx b/react-app/src/renderer/TrameNode.tsx
new file mode 100644
index 0000000..403809c
--- /dev/null
+++ b/react-app/src/renderer/TrameNode.tsx
@@ -0,0 +1,386 @@
+// Renders the server-sent JSON component tree (see trame_client/utils/react.py
+// for the schema) into React elements.
+//
+// Event mapping convention (locked per PLAN.md §4.0):
+// - native DOM tags: trame event "click" -> onClick, "mouseout.left.stop" ->
+// onMouseOut with modifiers applied; handler receives the React synthetic
+// event as $event.
+// - registered components: trame event "change" -> prop onChange; $event is
+// the first callback argument.
+// - v_model: native inputs get value/checked + onChange (modifiers: lazy ->
+// onBlur, number -> parseFloat, trim); registered components get
+// props[arg || "value"] + props["onUpdate" + Pascal(arg || "value")].
+
+import React from "react";
+import type { ReactNode } from "react";
+
+import registry from "../registry";
+import type {
+ Scope,
+ SlotFn,
+ TrameInstance,
+ TrameJsonChild,
+ TrameJsonNode,
+} from "../types";
+import { createScope, evalExpr, execStatement } from "./evaluate";
+
+const KEY_ALIASES: Record = {
+ enter: "Enter",
+ tab: "Tab",
+ delete: "Delete",
+ esc: "Escape",
+ space: " ",
+ left: "ArrowLeft",
+ up: "ArrowUp",
+ right: "ArrowRight",
+ down: "ArrowDown",
+};
+const MOUSE_BUTTONS: Record = { left: 0, middle: 1, right: 2 };
+
+const DOM_ATTR_MAP: Record = {
+ class: "className",
+ for: "htmlFor",
+ tabindex: "tabIndex",
+ readonly: "readOnly",
+ maxlength: "maxLength",
+ minlength: "minLength",
+ autocomplete: "autoComplete",
+ autofocus: "autoFocus",
+ spellcheck: "spellCheck",
+ contenteditable: "contentEditable",
+ crossorigin: "crossOrigin",
+ srcset: "srcSet",
+ colspan: "colSpan",
+ rowspan: "rowSpan",
+};
+
+function pascal(name: string): string {
+ return name
+ .split(/[-_:]/)
+ .map((t) => t.charAt(0).toUpperCase() + t.slice(1))
+ .join("");
+}
+
+export function styleStringToObject(style: unknown) {
+ if (typeof style !== "string") return style;
+ const result: Record = {};
+ style.split(";").forEach((rule) => {
+ const idx = rule.indexOf(":");
+ if (idx === -1) return;
+ const key = rule.slice(0, idx).trim();
+ const value = rule.slice(idx + 1).trim();
+ if (!key) return;
+ const reactKey = key.startsWith("--")
+ ? key
+ : key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+ result[reactKey] = value;
+ });
+ return result;
+}
+
+function domAttrName(name: string): string {
+ return DOM_ATTR_MAP[name] || name;
+}
+
+function eventPropName(eventName: string): string {
+ // "update:modelValue" -> onUpdateModelValue ; "click" -> onClick
+ // names already in handler form ("onReady") are kept as-is
+ if (/^on[A-Z]/.test(eventName)) return eventName;
+ return `on${pascal(eventName)}`;
+}
+
+type Handler = (event?: any, ...rest: unknown[]) => unknown;
+
+function wrapWithModifiers(handler: Handler, modifiers: string[]): Handler {
+ if (!modifiers.length) return handler;
+ const keys = modifiers.filter((m) => KEY_ALIASES[m] && !MOUSE_BUTTONS[m]);
+ let fired = false;
+ return (event?: any, ...rest: unknown[]) => {
+ if (event && typeof event === "object") {
+ if (modifiers.includes("self") && event.target !== event.currentTarget)
+ return;
+ if (
+ keys.length &&
+ event.key !== undefined &&
+ !keys.some((k) => event.key === KEY_ALIASES[k])
+ )
+ return;
+ if (
+ event.button !== undefined &&
+ modifiers.some((m) => m in MOUSE_BUTTONS) &&
+ !modifiers.some((m) => event.button === MOUSE_BUTTONS[m])
+ )
+ return;
+ if (modifiers.includes("stop")) event.stopPropagation();
+ if (modifiers.includes("prevent")) event.preventDefault();
+ }
+ if (modifiers.includes("once")) {
+ if (fired) return;
+ fired = true;
+ }
+ return handler(event, ...rest);
+ };
+}
+
+function parseEventKey(key: string) {
+ const [name, ...tokens] = key.split(".");
+ return { name, modifiers: tokens };
+}
+
+function buildEventProps(
+ on: Record | undefined,
+ scope: Scope,
+ props: Record,
+) {
+ Object.entries(on || {}).forEach(([key, body]) => {
+ const { name, modifiers } = parseEventKey(key);
+ const captureSuffix = modifiers.includes("capture") ? "Capture" : "";
+ const handler: Handler = ($event?: unknown) =>
+ execStatement(body, scope, $event);
+ props[`${eventPropName(name)}${captureSuffix}`] = wrapWithModifiers(
+ handler,
+ modifiers,
+ );
+ });
+}
+
+function buildModelProps(
+ models: TrameJsonNode["dirs"] extends infer D
+ ? D extends { models?: infer M }
+ ? M
+ : never
+ : never,
+ scope: Scope,
+ tag: string,
+ isDom: boolean,
+ props: Record,
+) {
+ (models || []).forEach(({ arg, modifiers, expr }) => {
+ const current = evalExpr(expr, scope);
+ const assign = (value: unknown) => {
+ let v = value;
+ if (modifiers.includes("number")) {
+ const n = parseFloat(v as string);
+ if (!Number.isNaN(n)) v = n;
+ }
+ if (modifiers.includes("trim") && typeof v === "string") v = v.trim();
+ // expr is a state variable name (possibly translated); assign via scope
+ execStatement(`${expr} = $event`, scope, v);
+ };
+
+ if (isDom) {
+ const isCheckbox = tag === "input" && props.type === "checkbox";
+ const isRadio = tag === "input" && props.type === "radio";
+ const lazy = modifiers.includes("lazy");
+ if (isCheckbox) {
+ props.checked = !!current;
+ props.onChange = (e: any) => assign(e.target.checked);
+ } else if (isRadio) {
+ props.checked = current === props.value;
+ props.onChange = (e: any) => assign(e.target.value);
+ } else {
+ props.value = current === undefined || current === null ? "" : current;
+ const apply = (e: any) => assign(e.target.value);
+ if (lazy) {
+ props.onBlur = apply;
+ props.onChange = () => {};
+ } else {
+ props.onChange = apply;
+ }
+ }
+ } else {
+ const propName = arg || "value";
+ props[propName] = current;
+ props[`onUpdate${pascal(propName)}`] = (value: unknown) => assign(value);
+ }
+ });
+}
+
+function buildProps(
+ node: TrameJsonNode,
+ scope: Scope,
+ isDom: boolean,
+ trame: TrameInstance,
+) {
+ const props: Record = {};
+ Object.entries(node.attrs || {}).forEach(([name, value]) => {
+ const key = isDom ? domAttrName(name) : name;
+ props[key] = key === "style" ? styleStringToObject(value) : value;
+ });
+ Object.entries(node.props || {}).forEach(([name, expr]) => {
+ const key = isDom ? domAttrName(name) : name;
+ const value = evalExpr(expr, scope);
+ props[key] = key === "style" ? styleStringToObject(value) : value;
+ });
+
+ const dirs = node.dirs || {};
+ if (dirs.bindObject) {
+ Object.assign(props, evalExpr(dirs.bindObject, scope) || {});
+ }
+ buildEventProps(node.on, scope, props);
+ if (dirs.onObject) {
+ const handlers = evalExpr(dirs.onObject, scope) || {};
+ Object.entries(handlers).forEach(([name, fn]) => {
+ props[eventPropName(name)] = fn;
+ });
+ }
+ buildModelProps(dirs.models || [], scope, node.tag, isDom, props);
+
+ if (dirs.show && !evalExpr(dirs.show, scope)) {
+ props.style = { ...(props.style || {}), display: "none" };
+ }
+ if (dirs.text !== undefined) {
+ props.children = evalExpr(dirs.text, scope);
+ }
+ if (dirs.html !== undefined) {
+ props.dangerouslySetInnerHTML = { __html: evalExpr(dirs.html, scope) };
+ }
+
+ // ref -> trame.refs registration (parity with vue clients)
+ if (typeof props.ref === "string") {
+ const refName: string = props.ref;
+ props.ref = (el: unknown) => {
+ trame.refs[refName] = el;
+ };
+ }
+ return props;
+}
+
+// Map slot props through the template's v-slot destructuring pattern,
+// e.g. "{ keyName: var_key, value }" exposes slotProps.keyName as `var_key`
+// and slotProps.value as `value` in the children scope.
+export function mapSlotLocals(
+ pattern: string | null | undefined,
+ slotProps: Record,
+): Record {
+ if (!pattern) return {};
+ const inner = pattern.trim().replace(/^\{/, "").replace(/\}$/, "");
+ const locals: Record = {};
+ inner.split(",").forEach((part) => {
+ const token = part.trim();
+ if (!token) return;
+ const [propName, localName] = token.split(":").map((t) => t.trim());
+ locals[localName || propName] = slotProps[propName];
+ });
+ return locals;
+}
+
+function renderNode(
+ node: TrameJsonNode,
+ scope: Scope,
+ trame: TrameInstance,
+ key: string,
+): ReactNode {
+ const dirs = node.dirs || {};
+
+ if (dirs.for) {
+ const { item, index, extra, source } = dirs.for;
+ const items = evalExpr(source, scope) || [];
+ const entries = Array.isArray(items) ? items : Object.entries(items);
+ return entries.map((value, i) => {
+ const locals = { [item]: value };
+ if (index) locals[index] = i;
+ if (extra) locals[extra] = i;
+ const childScope = createScope(trame, locals, scope);
+ const restDirs = { ...dirs };
+ delete restDirs.for;
+ const child = { ...node, dirs: restDirs };
+ return renderNode(child, childScope, trame, `${key}-${i}`);
+ });
+ }
+
+ const component = registry.resolve(node.tag);
+ const isDom = !component;
+ const type = component || node.tag;
+ const props = buildProps(node, scope, isDom, trame);
+ props.key = props.key !== undefined ? props.key : key;
+
+ let children;
+ if (props.children !== undefined) {
+ children = props.children; // v-text
+ delete props.children;
+ } else if (props.dangerouslySetInnerHTML) {
+ children = undefined;
+ } else if (!isDom) {
+ // Scoped slot support: the component decides when/with which variables
+ // its children render (e.g. TrameGetter exposes { value, update }).
+ const slotMapping = dirs.slot?.expr;
+ const slot: SlotFn = (slotProps = {}) =>
+ renderChildren(
+ node.children,
+ createScope(trame, mapSlotLocals(slotMapping, slotProps), scope),
+ trame,
+ );
+ props.slot = slot;
+ children = slotMapping ? undefined : slot();
+ } else {
+ children = renderChildren(node.children, scope, trame);
+ }
+
+ if (children === undefined || (Array.isArray(children) && !children.length)) {
+ return React.createElement(type, props);
+ }
+ return React.createElement(type, props, children);
+}
+
+export function renderChildren(
+ children: TrameJsonChild[] | undefined,
+ scope: Scope,
+ trame: TrameInstance,
+): ReactNode[] {
+ if (!children) return [];
+ const output: ReactNode[] = [];
+ let lastIfValue: boolean | null = null; // tracks v-if/v-else-if/v-else chain
+
+ children.forEach((child, i) => {
+ if (typeof child === "string") {
+ output.push(child);
+ lastIfValue = null;
+ return;
+ }
+ if ("expr" in child && !("tag" in child)) {
+ const value = evalExpr(child.expr, scope);
+ output.push(value === undefined || value === null ? "" : String(value));
+ lastIfValue = null;
+ return;
+ }
+
+ const dirs = (child as TrameJsonNode).dirs || {};
+ if (dirs.if !== undefined) {
+ lastIfValue = !!evalExpr(dirs.if, scope);
+ if (!lastIfValue) return;
+ } else if (dirs.elseIf !== undefined) {
+ if (lastIfValue) return;
+ lastIfValue = !!evalExpr(dirs.elseIf, scope);
+ if (!lastIfValue) return;
+ } else if (dirs.else) {
+ if (lastIfValue) return;
+ lastIfValue = null;
+ } else {
+ lastIfValue = null;
+ }
+
+ const rendered = renderNode(child as TrameJsonNode, scope, trame, `n${i}`);
+ if (Array.isArray(rendered)) {
+ output.push(...rendered);
+ } else {
+ output.push(rendered);
+ }
+ });
+
+ return output;
+}
+
+export default function TrameNode({
+ node,
+ trame,
+ scope,
+}: {
+ node: TrameJsonNode;
+ trame: TrameInstance;
+ scope?: Scope;
+}) {
+ const rootScope = scope || createScope(trame);
+ const result = renderNode(node, rootScope, trame, "root");
+ return Array.isArray(result) ? <>{result} : result;
+}
diff --git a/react-app/src/renderer/__tests__/renderer.test.jsx b/react-app/src/renderer/__tests__/renderer.test.jsx
new file mode 100644
index 0000000..686ae94
--- /dev/null
+++ b/react-app/src/renderer/__tests__/renderer.test.jsx
@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import TrameNode from "../TrameNode";
+import { createScope, evalExpr } from "../evaluate";
+import registry from "../../registry";
+
+function mockTrame(initial = {}) {
+ const store = { trame__client_only: [], ...initial };
+ return {
+ refs: {},
+ utils: {},
+ trigger: () => {},
+ state: {
+ get: (key) => (key === undefined ? store : store[key]),
+ set: (key, value) => {
+ store[key] = value;
+ },
+ update: (obj) => Object.assign(store, obj),
+ flush: () => {},
+ addListener: () => {},
+ removeListener: () => {},
+ },
+ };
+}
+
+const render = (node, trame) =>
+ renderToStaticMarkup();
+
+describe("evaluate", () => {
+ it("resolves state variables and globals", () => {
+ const scope = createScope(mockTrame({ count: 41 }));
+ expect(evalExpr("count + 1", scope)).toBe(42);
+ expect(evalExpr("Math.max(count, 100)", scope)).toBe(100);
+ });
+
+ it("resolves $event to the handler argument, not the scope", () => {
+ const trame = mockTrame({ count: 0 });
+ const scope = createScope(trame);
+ expect(evalExpr("$event + 1", scope, 41)).toBe(42);
+ });
+});
+
+describe("TrameNode", () => {
+ it("renders static attrs, bound props and text expressions", () => {
+ const trame = mockTrame({ count: 5 });
+ const node = {
+ tag: "div",
+ attrs: { id: "x", class: "a" },
+ props: { title: "'c=' + count" },
+ children: ["count: ", { expr: "count" }],
+ };
+ expect(render(node, trame)).toBe(
+ 'count: 5
',
+ );
+ });
+
+ it("handles v-if / v-else chains", () => {
+ const trame = mockTrame({ show: false });
+ const node = {
+ tag: "div",
+ children: [
+ { tag: "span", dirs: { if: "show" }, children: ["yes"] },
+ { tag: "span", dirs: { else: true }, children: ["no"] },
+ ],
+ };
+ expect(render(node, trame)).toBe("no
");
+ });
+
+ it("handles v-for", () => {
+ const trame = mockTrame({ items: ["a", "b"] });
+ const node = {
+ tag: "ul",
+ children: [
+ {
+ tag: "li",
+ dirs: { for: { item: "it", index: "i", source: "items" } },
+ children: [{ expr: "i" }, ":", { expr: "it" }],
+ },
+ ],
+ };
+ expect(render(node, trame)).toBe("");
+ });
+
+ it("handles v-show and style strings", () => {
+ const trame = mockTrame({ visible: false });
+ const node = {
+ tag: "div",
+ attrs: { style: "color: red; margin-top: 2px" },
+ dirs: { show: "visible" },
+ };
+ expect(render(node, trame)).toBe(
+ '',
+ );
+ });
+
+ it("renders v-model on native input from state", () => {
+ const trame = mockTrame({ name_var: "hello" });
+ const node = {
+ tag: "input",
+ dirs: { models: [{ arg: null, modifiers: [], expr: "name_var" }] },
+ };
+ expect(render(node, trame)).toBe('');
+ });
+
+ it("model onChange writes the input value back to state", async () => {
+ const { default: TestRenderer } = await import("react-dom/client");
+ void TestRenderer; // jsdom-free: exercise the handler directly
+ const trame = mockTrame({ count: 2 });
+ const node = {
+ tag: "input",
+ attrs: { type: "range" },
+ dirs: { models: [{ arg: null, modifiers: ["number"], expr: "count" }] },
+ };
+ // render to walk buildProps, then invoke the produced handler
+ let captured;
+ registry.register("probe-input", (props) => {
+ captured = props;
+ return ;
+ });
+ render({ ...node, tag: "probe-input" }, trame);
+ captured.onUpdateValue("7");
+ expect(trame.state.get("count")).toBe(7);
+ registry.unregister("probe-input");
+ });
+
+ it("resolves registered components and maps events to on props", () => {
+ const seen = {};
+ registry.register("my-widget", ({ label, onChange }) => {
+ seen.onChange = onChange;
+ return ;
+ });
+ const trame = mockTrame({ txt: "go" });
+ const node = {
+ tag: "my-widget",
+ props: { label: "txt" },
+ on: { change: "txt = 'done'" },
+ };
+ expect(render(node, trame)).toBe("");
+ seen.onChange("ignored");
+ expect(trame.state.get("txt")).toBe("done");
+ registry.unregister("my-widget");
+ });
+});
diff --git a/react-app/src/renderer/evaluate.ts b/react-app/src/renderer/evaluate.ts
new file mode 100644
index 0000000..0fe75f4
--- /dev/null
+++ b/react-app/src/renderer/evaluate.ts
@@ -0,0 +1,119 @@
+// Expression evaluation against the trame shared state.
+//
+// Expressions are the same JS snippets trame apps already use with the Vue
+// clients ("count > 3", "count++", "trigger('name', [count])"). They are
+// compiled once (cached) and invoked with a `with()` scope proxy backed by
+// trame.state, so bare identifiers resolve to state variables.
+
+import type { Scope, TrameInstance } from "../types";
+
+type CompiledFn = ((scope: Scope, $event?: unknown) => unknown) | null;
+
+const EXPR_CACHE = new Map();
+const STMT_CACHE = new Map();
+
+function compile(
+ body: string,
+ cache: Map,
+ wrap: (body: string) => string,
+): CompiledFn {
+ let fn = cache.get(body);
+ if (fn === undefined) {
+ try {
+ // eslint-disable-next-line no-new-func
+ fn = new Function("$scope", "$event", wrap(body)) as CompiledFn;
+ } catch (e) {
+ console.error(`trame: failed to compile expression "${body}"`, e);
+ fn = null;
+ }
+ cache.set(body, fn);
+ }
+ return fn;
+}
+
+export function createScope(
+ trame: TrameInstance,
+ extra: Record = {},
+ parent: Scope | null = null,
+): Scope {
+ const locals: Record = { ...extra };
+ const scope = new Proxy(locals, {
+ has(target, key) {
+ // claim every identifier so `with()` never falls through to globals
+ // implicitly — EXCEPT the handler arguments, which must resolve to the
+ // compiled function parameters ($event) instead of this scope.
+ return key !== "$event";
+ },
+ get(target, key: string | symbol) {
+ if (key === Symbol.unscopables) return undefined;
+ if (typeof key === "symbol") return (target as any)[key];
+ if (key in target) return target[key];
+ if (parent) {
+ const value = parent[key];
+ if (value !== undefined) return value;
+ }
+ const state = trame?.state?.get?.();
+ if (state && Object.prototype.hasOwnProperty.call(state, key)) {
+ return state[key];
+ }
+ // scope API + escape hatches
+ switch (key) {
+ case "trame":
+ return trame;
+ case "window":
+ return window;
+ case "utils":
+ return trame?.utils;
+ case "trigger":
+ return (name: string, args?: unknown[], kwargs?: Record) =>
+ trame.trigger(name, args, kwargs);
+ case "set":
+ return (name: string, value: unknown) => trame.state.set(name, value);
+ case "get":
+ return (name?: string) => trame.state.get(name);
+ case "setAll":
+ return (obj: Record) => trame.state.update(obj);
+ case "flushState":
+ return (...keys: unknown[]) => trame.state.flush(...keys);
+ default:
+ // globals (Math, JSON, console, ...)
+ return (globalThis as any)[key];
+ }
+ },
+ set(target, key: string, value: unknown) {
+ if (key in target) {
+ target[key] = value;
+ } else {
+ trame.state.set(key, value);
+ }
+ return true;
+ },
+ });
+ return scope;
+}
+
+export function evalExpr(expr: string, scope: Scope, $event?: unknown) {
+ const fn = compile(expr, EXPR_CACHE, (b) => `with($scope){return(${b});}`);
+ if (!fn) return undefined;
+ try {
+ return fn(scope, $event);
+ } catch (e) {
+ console.error(`trame: error evaluating "${expr}"`, e);
+ return undefined;
+ }
+}
+
+export function execStatement(body: string, scope: Scope, $event?: unknown) {
+ // event handlers may be statements ("count++; other = 1") or expressions
+ let fn = compile(body, EXPR_CACHE, (b) => `with($scope){return(${b});}`);
+ if (!fn) {
+ fn = compile(body, STMT_CACHE, (b) => `with($scope){${b}}`);
+ }
+ if (!fn) return undefined;
+ try {
+ return fn(scope, $event);
+ } catch (e) {
+ console.error(`trame: error executing "${body}"`, e);
+ return undefined;
+ }
+}
diff --git a/react-app/src/renderer/hooks.ts b/react-app/src/renderer/hooks.ts
new file mode 100644
index 0000000..b341e36
--- /dev/null
+++ b/react-app/src/renderer/hooks.ts
@@ -0,0 +1,54 @@
+// React hooks bridging the trame shared state to component re-renders.
+
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useRef,
+ useSyncExternalStore,
+} from "react";
+
+import type { TrameInstance, TrameStateEvent } from "../types";
+
+export const TrameContext = createContext(null);
+
+export function useTrame(): TrameInstance {
+ const trame = useContext(TrameContext);
+ if (!trame) {
+ throw new Error("useTrame must be used inside ");
+ }
+ return trame;
+}
+
+// Re-render when any watched state key becomes dirty.
+// keys === null -> re-render on every dirty-state event (template-level).
+export function useTrameState(keys: string[] | null = null): number {
+ const trame = useTrame();
+ const versionRef = useRef(0);
+ const keyList = keys ? keys.join(",") : null;
+
+ const subscribe = useCallback(
+ (onStoreChange: () => void) => {
+ const keySet = keyList !== null ? new Set(keyList.split(",")) : null;
+ const listener = ({ type, keys: dirtyKeys }: TrameStateEvent) => {
+ if (type !== "dirty-state" && type !== "new-keys") return;
+ if (!keySet || dirtyKeys?.some((k) => keySet.has(k))) {
+ versionRef.current += 1;
+ onStoreChange();
+ }
+ };
+ trame.state.addListener(listener);
+ return () => trame.state.removeListener(listener);
+ },
+ [trame, keyList],
+ );
+
+ return useSyncExternalStore(subscribe, () => versionRef.current);
+}
+
+// Subscribe to a single state value.
+export function useTrameValue(name: string): unknown {
+ const trame = useTrame();
+ useTrameState([name]);
+ return trame.state.get(name);
+}
diff --git a/react-app/src/style.css b/react-app/src/style.css
new file mode 100644
index 0000000..a639497
--- /dev/null
+++ b/react-app/src/style.css
@@ -0,0 +1,85 @@
+.text-no-select {
+ -webkit-user-select: none;
+ -moz-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.trame__loader {
+ display: block;
+ position: relative;
+ left: 50%;
+ top: calc(50% - 50px);
+ width: 150px;
+ height: 150px;
+ margin: -75px 0 0 -75px;
+ border-radius: 50%;
+ border: 10px solid transparent;
+ border-top-color: #ac262c;
+
+ -webkit-animation: spin 2s linear infinite; /* Chrome, Opera 15+, Safari 5+ */
+ animation: spin 2s linear infinite; /* Chrome, Firefox 16+, IE 10+, Opera */
+}
+
+.trame__loader:before {
+ content: "";
+ position: absolute;
+ top: 5px;
+ left: 5px;
+ right: 5px;
+ bottom: 5px;
+ border-radius: 50%;
+ border: 10px solid transparent;
+ border-top-color: #258e44;
+
+ -webkit-animation: spin 3s linear infinite; /* Chrome, Opera 15+, Safari 5+ */
+ animation: spin 3s linear infinite; /* Chrome, Firefox 16+, IE 10+, Opera */
+}
+
+.trame__loader:after {
+ content: "";
+ position: absolute;
+ top: 20px;
+ left: 20px;
+ right: 20px;
+ bottom: 20px;
+ border-radius: 50%;
+ border: 10px solid transparent;
+ border-top-color: #1c4678;
+
+ -webkit-animation: spin 1.5s linear infinite; /* Chrome, Opera 15+, Safari 5+ */
+ animation: spin 1.5s linear infinite; /* Chrome, Firefox 16+, IE 10+, Opera */
+}
+
+.trame__message {
+ position: absolute;
+ text-align: center;
+ width: 100%;
+ top: calc(50% + 50px);
+ font-size: 200%;
+ user-select: none;
+}
+
+@-webkit-keyframes spin {
+ 0% {
+ -webkit-transform: rotate(0deg); /* Chrome, Opera 15+, Safari 3.1+ */
+ -ms-transform: rotate(0deg); /* IE 9 */
+ transform: rotate(0deg); /* Firefox 16+, IE 10+, Opera */
+ }
+ 100% {
+ -webkit-transform: rotate(360deg); /* Chrome, Opera 15+, Safari 3.1+ */
+ -ms-transform: rotate(360deg); /* IE 9 */
+ transform: rotate(360deg); /* Firefox 16+, IE 10+, Opera */
+ }
+}
+@keyframes spin {
+ 0% {
+ -webkit-transform: rotate(0deg); /* Chrome, Opera 15+, Safari 3.1+ */
+ -ms-transform: rotate(0deg); /* IE 9 */
+ transform: rotate(0deg); /* Firefox 16+, IE 10+, Opera */
+ }
+ 100% {
+ -webkit-transform: rotate(360deg); /* Chrome, Opera 15+, Safari 3.1+ */
+ -ms-transform: rotate(360deg); /* IE 9 */
+ transform: rotate(360deg); /* Firefox 16+, IE 10+, Opera */
+ }
+}
diff --git a/react-app/src/types.ts b/react-app/src/types.ts
new file mode 100644
index 0000000..b8de7d9
--- /dev/null
+++ b/react-app/src/types.ts
@@ -0,0 +1,105 @@
+// Public contract between the trame react client, the renderer and widget
+// libraries (trame-mui, trame-vtk react-components, application components).
+
+import type { ComponentType, ReactNode } from "react";
+
+// ----------------------------------------------------------------------------
+// trame instance (created by core/trame, framework-agnostic JS)
+// ----------------------------------------------------------------------------
+
+export interface TrameState {
+ state: Record;
+ ready: boolean;
+ ts: number;
+ get(key?: string): any;
+ set(key: string, value: unknown): Promise;
+ update(obj: Record): Promise;
+ flush(...keys: unknown[]): Promise | void;
+ getAllKeys(): string[];
+ addListener(listener: TrameStateListener): void;
+ removeListener(listener: TrameStateListener): void;
+ registerDecorator(...args: unknown[]): void;
+ delete(): void;
+}
+
+export type TrameStateEvent = {
+ type: "dirty-state" | "new-keys" | "ready" | "refresh";
+ keys?: string[];
+};
+export type TrameStateListener = (event: TrameStateEvent) => void;
+
+export interface TrameInstance {
+ app: Registry;
+ client: any; // vtkWSLinkClient
+ state: TrameState;
+ config: Record | null;
+ utils: Record;
+ refs: Record;
+ connect(config?: Record): Promise>;
+ trigger(
+ name: string,
+ args?: unknown[],
+ kwargs?: Record,
+ ): Promise;
+ addConnectListener(listener: () => void): void;
+ removeConnectListener(listener: () => void): void;
+}
+
+// ----------------------------------------------------------------------------
+// Component registry (widget libraries plug in through `react_use`)
+// ----------------------------------------------------------------------------
+
+export interface Registry {
+ register(tag: string, component: ComponentType): void;
+ unregister(tag: string): void;
+ resolve(tag: string): ComponentType | undefined;
+ has(tag: string): boolean;
+ use(plugin: RegistryPlugin, ...options: unknown[]): void;
+}
+
+export type RegistryPlugin =
+ | { install(registry: Registry, ...options: unknown[]): void }
+ | ((registry: Registry, ...options: unknown[]) => void);
+
+// Registered components receive their children through the scoped-slot
+// render prop, and two-way bindings as `value` + `onUpdateValue`.
+export type SlotFn = (slotProps?: Record) => ReactNode;
+
+// ----------------------------------------------------------------------------
+// Serialized layout (wire schema produced by trame_client/utils/react.py)
+// ----------------------------------------------------------------------------
+
+export interface TrameNodeDirs {
+ if?: string;
+ elseIf?: string;
+ else?: boolean;
+ show?: string;
+ for?: { item: string; index?: string | null; source: string; extra?: string };
+ models?: { arg: string | null; modifiers: string[]; expr: string }[];
+ text?: string;
+ html?: string;
+ slot?: { arg: string | null; expr: string | null };
+ onObject?: string;
+ bindObject?: string;
+ custom?: Record;
+}
+
+export interface TrameJsonNode {
+ tag: string;
+ attrs?: Record;
+ props?: Record;
+ on?: Record;
+ dirs?: TrameNodeDirs;
+ raw?: string[];
+ children?: TrameJsonChild[];
+}
+
+export type TrameJsonChild = string | { expr: string } | TrameJsonNode;
+
+export interface TrameTemplatePayload {
+ version: number;
+ root: TrameJsonNode;
+}
+
+// Expression scope proxy (see renderer/evaluate.ts)
+export type Scope = Record;
diff --git a/react-app/src/user_script_handler.js b/react-app/src/user_script_handler.js
new file mode 100644
index 0000000..f26c1f7
--- /dev/null
+++ b/react-app/src/user_script_handler.js
@@ -0,0 +1,86 @@
+async function loadEsModule(path) {
+ try {
+ return await import(path);
+ } catch (e) {
+ if (e instanceof TypeError) {
+ // retry with forward slash
+ return await import("/" + path);
+ } else {
+ throw e;
+ }
+ }
+}
+
+function lookupUmdModule(global_var_name) {
+ const module = window[global_var_name];
+
+ if (module) {
+ return Promise.resolve(module);
+ }
+
+ const module_not_found_error = new ReferenceError(
+ `UMD module not found at window.${global_var_name}`,
+ );
+ return Promise.reject(module_not_found_error);
+}
+
+function register_handle({ module, module_path }, function_name, handle_id) {
+ const func = module[function_name];
+
+ if (!func) {
+ throw new ReferenceError(
+ `Could not find function ${function_name} on module ${module_path}. Did you pass the correct function identifier?`,
+ );
+ }
+
+ window.TRAME_EXTERNAL_SCRIPTS[handle_id] = {
+ func,
+ };
+}
+
+export async function registerUserScripts() {
+ window.TRAME_EXTERNAL_SCRIPTS = {};
+ const external_scripts =
+ window.trame.state.state.trame__client_external_scripts || [];
+
+ const module_registration_promises = [];
+
+ for (const external_script of external_scripts) {
+ console.debug("registering external_script ", external_script);
+
+ const get_module_fn =
+ external_script.module_type === "es" ? loadEsModule : lookupUmdModule;
+
+ const registering_module = get_module_fn(external_script.path)
+ .catch((e) => {
+ throw new Error(
+ `Could not load module ${external_script.path}. Did you pass the correct module path?`,
+ {
+ cause: e,
+ },
+ );
+ })
+ .then((module) => {
+ register_handle(
+ { module, module_path: external_script.path },
+ external_script.function,
+ external_script.id,
+ );
+ });
+
+ module_registration_promises.push(registering_module);
+ }
+
+ const preload_results = await Promise.allSettled(
+ module_registration_promises,
+ );
+ const failures = preload_results.filter(
+ (result) => result.status === "rejected",
+ );
+
+ if (failures.length > 0) {
+ const errors = failures.map((f) => f.reason);
+ console.error(errors);
+ throw new AggregateError(errors);
+ }
+}
diff --git a/react-app/src/utils/fmt/index.js b/react-app/src/utils/fmt/index.js
new file mode 100644
index 0000000..4f1be7c
--- /dev/null
+++ b/react-app/src/utils/fmt/index.js
@@ -0,0 +1,24 @@
+export function number(value, units = [], steps = 1000, fixed = 2) {
+ if (value === null) {
+ return null;
+ }
+ for (let i = 0; i < units.length; i++) {
+ const step = Array.isArray(steps) ? steps[i] : steps;
+ const unit = units[i];
+ if (value > step) {
+ value /= step;
+ } else {
+ return `${value.toFixed(fixed)} ${unit}`;
+ }
+ }
+ return `${value.toFixed(fixed)} ${steps[steps.length - 1]}`;
+}
+
+export function bytes(v, fixed = 2) {
+ return number(v, ["B", "KB", "MB", "GB", "TB", "PB"], 1024, fixed);
+}
+
+export default {
+ number,
+ bytes,
+};
diff --git a/react-app/src/utils/index.js b/react-app/src/utils/index.js
new file mode 100644
index 0000000..782cdde
--- /dev/null
+++ b/react-app/src/utils/index.js
@@ -0,0 +1,126 @@
+import vtk from "./vtk";
+import fmt from "./fmt";
+
+async function download(
+ filename,
+ contentOrPromise,
+ type = "application/octet-stream",
+) {
+ const content = await Promise.resolve(contentOrPromise);
+ const blob = new Blob([content], { type });
+ const url = URL.createObjectURL(blob);
+ const anchor = document.createElement("a");
+ anchor.setAttribute("href", url);
+ anchor.setAttribute("download", filename);
+ document.body.appendChild(anchor);
+ anchor.click();
+ document.body.removeChild(anchor);
+ setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+function get(path, obj = window) {
+ let current = obj;
+ const exec = path.endsWith("()");
+ const steps = (exec ? path.slice(0, -2) : path).split(".");
+ for (let i = 0; i < steps.length; i++) {
+ current = current[steps[i]];
+ }
+ if (exec) {
+ return current();
+ }
+ return current;
+}
+
+function safe(obj) {
+ try {
+ JSON.stringify(obj);
+ return obj;
+ } catch (e) {
+ // We need to look into object
+ }
+
+ const safeObj = {};
+ const keys = Object.keys(obj);
+ for (let i = 0; i < keys.length; i++) {
+ const key = keys[i];
+ const value = obj[key];
+ if (Array.isArray(value)) {
+ safeObj[key] = value.map(safe);
+ } else {
+ try {
+ JSON.stringify(value);
+ safeObj[key] = value;
+ } catch (e) {
+ continue;
+ }
+ }
+ }
+ return safeObj;
+}
+
+function toNode(id, key, value) {
+ const node = { id };
+ const prefix = key ? `${key}: ` : "";
+ if (Array.isArray(value)) {
+ node.name = `${prefix}[]`;
+ if (value.length) {
+ node.children = [];
+ }
+ return node;
+ }
+ if (value === null || !value) {
+ node.name = `${prefix}${value}`;
+ return node;
+ }
+ if (typeof value === "function") {
+ node.name = `${prefix}function`;
+ return node;
+ }
+ if (typeof value === "object") {
+ node.name = `${prefix}{}`;
+ if (Object.keys(value).length) {
+ node.children = [];
+ }
+ return node;
+ }
+ node.name = `${prefix}${value}`;
+ return node;
+}
+
+function registerItem(container, id, key, value) {
+ const node = toNode(id, key, value);
+ container.push(node);
+ if (node.children) {
+ registerList(id, node.children, value);
+ }
+}
+
+function registerList(parentId, container, obj) {
+ if (Array.isArray(obj)) {
+ const key = null;
+ for (let i = 0; i < obj.length; i++) {
+ registerItem(container, `${parentId}_${i}`, key, obj[i]);
+ }
+ } else {
+ const keys = Object.keys(obj);
+ for (let i = 0; i < keys.length; i++) {
+ const key = keys[i];
+ registerItem(container, `${parentId}_${i}`, key, obj[key]);
+ }
+ }
+}
+
+function tree(obj) {
+ const result = [];
+ registerList("", result, obj);
+ return result;
+}
+
+export default {
+ download,
+ get,
+ safe,
+ tree,
+ vtk,
+ fmt,
+};
diff --git a/react-app/src/utils/vtk/index.js b/react-app/src/utils/vtk/index.js
new file mode 100644
index 0000000..f3d4c59
--- /dev/null
+++ b/react-app/src/utils/vtk/index.js
@@ -0,0 +1,28 @@
+const VTK_EVENT_KEYS = [
+ "type",
+ "key",
+ "keyCode",
+ "controlKey",
+ "altKey",
+ "shiftKey",
+ "position",
+ "spinX",
+ "spinY",
+ "pixelX",
+ "pixelY",
+];
+
+function event(e) {
+ const result = {};
+ for (let i = 0; i < VTK_EVENT_KEYS.length; i++) {
+ const key = VTK_EVENT_KEYS[i];
+ if (key in e) {
+ result[key] = e[key];
+ }
+ }
+ return result;
+}
+
+export default {
+ event,
+};
diff --git a/react-app/tsconfig.json b/react-app/tsconfig.json
new file mode 100644
index 0000000..c009eb1
--- /dev/null
+++ b/react-app/tsconfig.json
@@ -0,0 +1,18 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "jsx": "react-jsx",
+ "strict": true,
+ "allowJs": true,
+ "checkJs": false,
+ "skipLibCheck": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "isolatedModules": true
+ },
+ "include": ["src"],
+ "exclude": ["src/**/__tests__"]
+}
diff --git a/react-app/vite.config.js b/react-app/vite.config.js
new file mode 100644
index 0000000..3245f50
--- /dev/null
+++ b/react-app/vite.config.js
@@ -0,0 +1,9 @@
+import react from "@vitejs/plugin-react";
+
+export default {
+ base: "./",
+ plugins: [react()],
+ build: {
+ outDir: "../src/trame_client/module/react-www",
+ },
+};
diff --git a/src/trame_client/module/.gitignore b/src/trame_client/module/.gitignore
index a2c09b1..9cc907b 100644
--- a/src/trame_client/module/.gitignore
+++ b/src/trame_client/module/.gitignore
@@ -1,3 +1,4 @@
www
vue2-www
vue3-www
+react-www
diff --git a/src/trame_client/module/__init__.py b/src/trame_client/module/__init__.py
index f38b501..cb9d08c 100644
--- a/src/trame_client/module/__init__.py
+++ b/src/trame_client/module/__init__.py
@@ -50,6 +50,11 @@ def setup(server, **kargs):
server.enable_module(vue3)
setup_handler_module(server)
+ elif client_type == "react":
+ from . import react
+
+ server.enable_module(react)
+ setup_handler_module(server)
else:
raise TypeError(
f"Trying to initialize trame_client with unknown client_type={client_type}"
diff --git a/src/trame_client/module/react.py b/src/trame_client/module/react.py
new file mode 100644
index 0000000..a1e9203
--- /dev/null
+++ b/src/trame_client/module/react.py
@@ -0,0 +1,3 @@
+from pathlib import Path
+
+www = str(Path(__file__).with_name("react-www").resolve())
diff --git a/src/trame_client/ui/core.py b/src/trame_client/ui/core.py
index f16e88f..973cc07 100644
--- a/src/trame_client/ui/core.py
+++ b/src/trame_client/ui/core.py
@@ -240,6 +240,15 @@ def html(self):
"""
return self.root.html
+ @property
+ def react(self):
+ """
+ Compute corresponding layout structure for the react client.
+ """
+ from ..utils.react import to_react_template
+
+ return to_react_template(self.root)
+
def __repr__(self):
return to_pretty_html(self.html)
@@ -276,7 +285,10 @@ def ready(self):
def flush_content(self):
"""Push new content to client"""
- self._server.state[self._template_name] = self.html
+ if getattr(self._server, "client_type", None) == "react":
+ self._server.state[self._template_name] = self.react
+ else:
+ self._server.state[self._template_name] = self.html
# -------------------------------------------------------------------------
# Resource manager
diff --git a/src/trame_client/utils/react.py b/src/trame_client/utils/react.py
new file mode 100644
index 0000000..e9fd560
--- /dev/null
+++ b/src/trame_client/utils/react.py
@@ -0,0 +1,212 @@
+"""React serialization of trame widget trees.
+
+When ``server.client_type == "react"`` the layout content is serialized as a
+JSON component tree rather than an HTML/template string. The React client
+(react-app) walks that tree with ``React.createElement`` and evaluates the
+embedded expressions against the trame shared state.
+
+Node schema (version 1)::
+
+ {
+ "tag": "div",
+ "attrs": {"id": "container"}, # static attributes
+ "props": {"disabled": "count > 3"}, # dynamic (JS expressions)
+ "on": {"click": "trigger('name')"}, # event name => JS body
+ "dirs": { # structural directives
+ "if": "expr",
+ "elseIf": "expr",
+ "else": True,
+ "show": "expr",
+ "for": {"item": "i", "index": "idx", "source": "expr"},
+ "models": [{"arg": None, "modifiers": [], "expr": "varName"}],
+ "text": "expr",
+ "html": "expr",
+ "slot": {"arg": "name", "expr": "slotProps"},
+ "onObject": "expr",
+ "bindObject": "expr",
+ },
+ "raw": ["v-anything='...'"], # raw_attrs passthrough
+ "children": [node | "text" | {"expr": "count + 1"}],
+ }
+"""
+
+import re
+
+MUSTACHE_RE = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
+V_FOR_RE = re.compile(
+ r"^\s*\(?\s*([\w$]+)\s*(?:,\s*([\w$]+))?\s*(?:,\s*([\w$]+))?\s*\)?"
+ r"\s+(?:in|of)\s+(.+?)\s*$",
+ re.DOTALL,
+)
+
+
+def split_text(text, server=None):
+ """Split a text child into plain strings and {"expr": ...} segments"""
+ segments = []
+ pos = 0
+ for m in MUSTACHE_RE.finditer(text):
+ if m.start() > pos:
+ segments.append(text[pos : m.start()])
+ expr = m.group(1).strip()
+ if server is not None:
+ expr = server.state.translator.translate_js_expression(server.state, expr)
+ segments.append({"expr": expr})
+ pos = m.end()
+ if pos < len(text):
+ segments.append(text[pos:])
+ return segments
+
+
+def parse_v_for(expression):
+ """Parse a "(item, index) in source" expression into a structure"""
+ m = V_FOR_RE.match(expression)
+ if m is None:
+ return {"item": "item", "index": None, "source": expression}
+ item, index, extra, source = m.groups()
+ result = {"item": item, "index": index, "source": source}
+ if extra:
+ result["extra"] = extra
+ return result
+
+
+def parse_directive_key(js_key):
+ """Split a "v-name:arg.mod1.mod2" key into (name, arg, modifiers)"""
+ body = js_key[2:] # strip "v-"
+ arg = None
+ if ":" in body:
+ body, arg = body.split(":", 1)
+ if "." in arg:
+ arg, *arg_modifiers = arg.split(".")
+ return body, arg, arg_modifiers
+ return body, arg, []
+ if "." in body:
+ body, *modifiers = body.split(".")
+ return body, arg, modifiers
+ return body, arg, []
+
+
+def _apply_directive(dirs, js_key, expr):
+ name, arg, modifiers = parse_directive_key(js_key)
+ if name == "if":
+ dirs["if"] = expr
+ elif name == "else-if":
+ dirs["elseIf"] = expr
+ elif name == "else":
+ dirs["else"] = True
+ elif name == "show":
+ dirs["show"] = expr
+ elif name == "for":
+ dirs["for"] = parse_v_for(expr)
+ elif name == "model":
+ dirs.setdefault("models", []).append(
+ {"arg": arg, "modifiers": modifiers, "expr": expr}
+ )
+ elif name == "text":
+ dirs["text"] = expr
+ elif name == "html":
+ dirs["html"] = expr
+ elif name == "slot":
+ dirs["slot"] = {"arg": arg, "expr": expr or None}
+ elif name == "on":
+ dirs["onObject"] = expr
+ elif name == "bind":
+ dirs["bindObject"] = expr
+ else:
+ # pre, once, memo, cloak, custom directives => passthrough
+ dirs.setdefault("custom", {})[js_key] = {
+ "arg": arg,
+ "modifiers": modifiers,
+ "expr": expr,
+ }
+
+
+def to_react_node(elem):
+ """Serialize an AbstractElement (or VirtualNode) into a react node dict"""
+ if isinstance(elem, str):
+ return {"tag": "__fragment", "children": split_text(elem)}
+
+ if not hasattr(elem, "_elem_name"):
+ # VirtualNode and other child containers
+ return {
+ "tag": "__fragment",
+ "children": _children_to_react(elem.children, elem.server),
+ }
+
+ node = {"tag": elem._elem_name}
+ attrs = {}
+ props = {}
+ on = {}
+ dirs = {}
+ raw = []
+
+ for entry in elem._attr_entries.values():
+ kind = entry["kind"]
+ if kind == "static":
+ attrs[entry["key"]] = entry["value"]
+ elif kind == "bind":
+ props[entry["key"]] = entry["expr"]
+ elif kind == "event":
+ on[entry["key"]] = entry["expr"]
+ elif kind == "directive":
+ _apply_directive(dirs, entry["key"], entry["expr"])
+ elif kind == "raw":
+ raw.append(entry["value"])
+
+ # Some widgets write directly into _attributes (e.g. Getter's v-slot,
+ # trame-vtk's ref= and :viewId=); capture whatever the structured
+ # entries missed.
+ for name, formatted in elem._attributes.items():
+ if name in elem._attr_entries:
+ continue
+ m = re.match(r'^(v-[\w:.-]+)="(.*)"$', formatted, re.DOTALL)
+ if m:
+ _apply_directive(dirs, m.group(1), m.group(2))
+ continue
+ m = re.match(r'^:([\w:.-]+)="(.*)"$', formatted, re.DOTALL)
+ if m:
+ props[m.group(1)] = m.group(2)
+ continue
+ m = re.match(r'^@([\w:.-]+)="(.*)"$', formatted, re.DOTALL)
+ if m:
+ on[m.group(1)] = m.group(2)
+ continue
+ m = re.match(r'^([\w-]+)="(.*)"$', formatted, re.DOTALL)
+ if m:
+ attrs[m.group(1)] = m.group(2)
+ continue
+ raw.append(formatted)
+
+ if attrs:
+ node["attrs"] = attrs
+ if props:
+ node["props"] = props
+ if on:
+ node["on"] = on
+ if dirs:
+ node["dirs"] = dirs
+ if raw:
+ node["raw"] = raw
+
+ children = _children_to_react(elem.children, elem.server)
+ if children:
+ node["children"] = children
+
+ return node
+
+
+def _children_to_react(children, server=None):
+ result = []
+ for child in children:
+ if isinstance(child, str):
+ result.extend(split_text(child, server))
+ elif hasattr(child, "react_node"):
+ result.append(child.react_node)
+ else:
+ result.append(to_react_node(child))
+ return result
+
+
+def to_react_template(root):
+ """Serialize a layout root into the native dict pushed to the client"""
+ node = root.react_node if hasattr(root, "react_node") else to_react_node(root)
+ return {"version": 1, "root": node}
diff --git a/src/trame_client/widgets/core.py b/src/trame_client/widgets/core.py
index 6c6b7d8..8e06af2 100644
--- a/src/trame_client/widgets/core.py
+++ b/src/trame_client/widgets/core.py
@@ -25,6 +25,22 @@
("v_once", "v-once"),
("v_memo", "v-memo"),
("v_cloak", "v-cloak"),
+ # r_* aliases: React-flavored spellings of the same structural directives,
+ # used by apps targeting client_type="react" (work with any client type).
+ ("r_text", "v-text"),
+ ("r_html", "v-html"),
+ ("r_show", "v-show"),
+ ("r_if", "v-if"),
+ ("r_else", "v-else"),
+ ("r_else_if", "v-else-if"),
+ ("r_for", "v-for"),
+ ("r_on", "v-on"),
+ ("r_bind", "v-bind"),
+ ("r_model", "v-model"),
+ ("r_model_lazy", "v-model.lazy"),
+ ("r_model_number", "v-model.number"),
+ ("r_model_trim", "v-model.trim"),
+ ("r_slot", "v-slot"),
]
KEY_ALIAS = [
"enter",
@@ -257,6 +273,15 @@ def html(self):
return "\n".join(out_buffer)
+ @property
+ def react_node(self):
+ """
+ Return a serializable react node representation of this VirtualNode
+ """
+ from trame_client.utils.react import to_react_node
+
+ return to_react_node(self)
+
# -------------------------------------------------------------------------
# Resource manager
# -------------------------------------------------------------------------
@@ -292,33 +317,31 @@ def __call__(self, layout=None, **kwargs):
HTML_CTX.add_child(self)
-def _event_value_processing(server, js_key, value):
+def _event_value_body(server, value):
+ """Return the JS body of an event handler or None if no match"""
if isinstance(value, str):
- translated_value = server.state.translator.translate_js_expression(
- server.state, value
- )
- return f'{js_key}="{translated_value}"'
+ return server.state.translator.translate_js_expression(server.state, value)
elif callable(value):
trigger_name = server.trigger_name(value)
- return f"{js_key}=\"trigger('{trigger_name}')\""
+ return f"trigger('{trigger_name}')"
elif isinstance(value, tuple):
trigger_name = value[0]
if callable(trigger_name):
trigger_name = server.trigger_name(trigger_name)
if len(value) == 1:
- return f"{js_key}=\"trigger('{trigger_name}')\""
+ return f"trigger('{trigger_name}')"
if len(value) == 2:
translated_value = server.state.translator.translate_js_expression(
server.state, value[1]
)
- return f"{js_key}=\"trigger('{trigger_name}', {translated_value})\""
+ return f"trigger('{trigger_name}', {translated_value})"
if len(value) == 3:
translated_value = server.state.translator.translate_js_expression(
server.state, value[1]
)
# We don't want to translate kwargs as we may change keys rather than just values
- return f"{js_key}=\"trigger('{trigger_name}', {translated_value}, {value[2]})\""
- return False
+ return f"trigger('{trigger_name}', {translated_value}, {value[2]})"
+ return None
def as_py_arg(iterable):
@@ -426,6 +449,7 @@ def __init__(
kwargs["style"] = " ".join([f"{k}: {v};" for k, v in style.items()])
self._attributes = {}
+ self._attr_entries = {}
self._py_attr = kwargs
self._used_py_attr = {"trame_server", "__properties", "__events"}
self._children = []
@@ -434,6 +458,7 @@ def __init__(
if raw_attrs:
for idx, raw_value in enumerate(raw_attrs):
self._attributes[f"_raw_{idx}"] = raw_value
+ self._attr_entries[f"_raw_{idx}"] = {"kind": "raw", "value": raw_value}
if children:
if isinstance(children, (list, tuple)):
@@ -490,6 +515,7 @@ def __setitem__(self, name, value):
if value is None:
self._py_attr.pop(name, value)
self._attributes.pop(name, value)
+ self._attr_entries.pop(name, None)
else:
self._py_attr[name] = value
@@ -514,6 +540,7 @@ def __setattr__(self, name, value):
if value is None:
self._py_attr.pop(name, value)
self._attributes.pop(name, value)
+ self._attr_entries.pop(name, None)
else:
self._py_attr[name] = value
@@ -537,6 +564,11 @@ def ttsSensitive(self):
of themself like VSelect in Vuetify.
"""
self._attributes["__tts"] = f':key="`w{self._id}-${{tts}}`"'
+ self._attr_entries["__tts"] = {
+ "kind": "bind",
+ "key": "key",
+ "expr": f"`w{self._id}-${{tts}}`",
+ }
return self
def attrs(self, *names):
@@ -551,7 +583,7 @@ def attrs(self, *names):
directives = [
name
for name in self._py_attr.keys()
- if name.startswith("v_model_") or name.startswith("v_bind_")
+ if name.startswith(("v_model_", "r_model_", "v_bind_", "r_bind_"))
]
self._used_py_attr.update(as_py_arg(directives))
self._used_py_attr.update(as_py_arg(names))
@@ -568,13 +600,13 @@ def attrs(self, *names):
value = self._py_attr[name]
# smart key handling
- if name.startswith("v_model_"):
+ if name.startswith(("v_model_", "r_model_")):
model_name, *modifiers = name.split("_")[2:]
if model_name in V_MODEL_MODIFIER and len(modifiers) == 0:
js_key = f"v-model.{model_name}"
else:
js_key = f"v-model:{model_name}{'.' if len(modifiers) else ''}{'.'.join(modifiers)}"
- elif name.startswith("v_bind_"):
+ elif name.startswith(("v_bind_", "r_bind_")):
prop_name, *modifiers = name.split("_")[2:]
js_key = f":{prop_name}{'.' if len(modifiers) else ''}{'.'.join(modifiers)}"
@@ -610,15 +642,47 @@ def attrs(self, *names):
logger.info("after: %s = %s", js_key, translated_value)
if js_key.startswith("v-"):
self._attributes[name] = f'{js_key}="{translated_value}"'
+ self._attr_entries[name] = {
+ "kind": "directive",
+ "key": js_key,
+ "expr": translated_value,
+ }
elif js_key.startswith(":"):
self._attributes[name] = f'{js_key}="{translated_value}"'
+ self._attr_entries[name] = {
+ "kind": "bind",
+ "key": js_key[1:],
+ "expr": translated_value,
+ }
else:
self._attributes[name] = f':{js_key}="{translated_value}"'
+ self._attr_entries[name] = {
+ "kind": "bind",
+ "key": js_key,
+ "expr": translated_value,
+ }
elif isinstance(value, bool):
if value:
self._attributes[name] = js_key
+ if js_key.startswith("v-"):
+ self._attr_entries[name] = {
+ "kind": "directive",
+ "key": js_key,
+ "expr": True,
+ }
+ else:
+ self._attr_entries[name] = {
+ "kind": "static",
+ "key": js_key,
+ "value": True,
+ }
else:
self._attributes[name] = f':{js_key}="false"'
+ self._attr_entries[name] = {
+ "kind": "bind",
+ "key": js_key,
+ "expr": "false",
+ }
elif isinstance(value, str):
if js_key.startswith("v-") or js_key.startswith(":"):
logger.info("before: %s = %s", js_key, value)
@@ -628,8 +692,31 @@ def attrs(self, *names):
logger.info("after: %s = %s", js_key, value)
self._attributes[name] = f'{js_key}="{value}"'
+ if js_key.startswith("v-"):
+ self._attr_entries[name] = {
+ "kind": "directive",
+ "key": js_key,
+ "expr": value,
+ }
+ elif js_key.startswith(":"):
+ self._attr_entries[name] = {
+ "kind": "bind",
+ "key": js_key[1:],
+ "expr": value,
+ }
+ else:
+ self._attr_entries[name] = {
+ "kind": "static",
+ "key": js_key,
+ "value": value,
+ }
elif isinstance(value, (int, float)):
self._attributes[name] = f'{js_key}="{value}"'
+ self._attr_entries[name] = {
+ "kind": "static",
+ "key": js_key,
+ "value": value,
+ }
else:
print(
"Error: Don't know how to handle attribute name "
@@ -664,12 +751,18 @@ def events(self, *names):
if value is None:
continue
- attribute = _event_value_processing(self.server, js_key, value)
+ body = _event_value_body(self.server, value)
+ attribute = False if body is None else f'{js_key}="{body}"'
if attribute is None:
# no match
pass
elif isinstance(attribute, str):
self._attributes[name] = attribute
+ self._attr_entries[name] = {
+ "kind": "event",
+ "key": js_key[1:],
+ "expr": body,
+ }
processed_event.add(name)
else:
print(
@@ -682,7 +775,7 @@ def events(self, *names):
if key_name in processed_event:
continue
- if key_name.startswith("v_on_"):
+ if key_name.startswith(("v_on_", "r_on_")):
tokens = key_name.split("_")[2:]
js_key = f"@{'.'.join(tokens)}"
value = self._py_attr[key_name]
@@ -690,13 +783,19 @@ def events(self, *names):
if value is None:
continue
- attribute = _event_value_processing(self.server, js_key, value)
+ body = _event_value_body(self.server, value)
+ attribute = False if body is None else f'{js_key}="{body}"'
if attribute is None:
# no match
pass
elif isinstance(attribute, str):
self._used_py_attr.add(key_name)
self._attributes[key_name] = attribute
+ self._attr_entries[key_name] = {
+ "kind": "event",
+ "key": js_key[1:],
+ "expr": body,
+ }
else:
print(
"Error: Don't know how to handle event name "
@@ -717,6 +816,11 @@ def hide(self):
Hide element while keeping it in the DOM. (display: none)
"""
self._attributes["__style"] = 'style="display: none"'
+ self._attr_entries["__style"] = {
+ "kind": "static",
+ "key": "style",
+ "value": "display: none",
+ }
def add_child(self, child):
"""
@@ -812,6 +916,31 @@ def html(self):
logger.error(e)
return f"<{self._elem_name} html-error />"
+ @property
+ def react_node(self):
+ """
+ Return a serializable react node representation of this element.
+ Used when server.client_type == "react".
+ """
+ from trame_client.utils.react import to_react_node
+
+ try:
+ # Build attributes
+ self.attrs(*self._attr_names)
+ self.events(*self._event_names)
+
+ if AbstractElement._debug and self.skipped_attributes:
+ logger.warning(
+ "Warning: <%s %s /> attributes will be skipped",
+ self._elem_name,
+ "=... ".join([*self.skipped_attributes, ""]),
+ )
+
+ return to_react_node(self)
+ except Exception as e:
+ logger.error(e)
+ return {"tag": self._elem_name, "attrs": {"data-error": True}}
+
def __repr__(self):
return to_pretty_html(self.html)
diff --git a/tests/test_react_client.py b/tests/test_react_client.py
new file mode 100644
index 0000000..d9a79ee
--- /dev/null
+++ b/tests/test_react_client.py
@@ -0,0 +1,40 @@
+from playwright.sync_api import expect
+import pytest
+
+
+@pytest.mark.parametrize("server_path", ["examples/test/reactivity_react.py"])
+def test_react_reactivity(server, page):
+ url = f"http://127.0.0.1:{server.port}/"
+ page.goto(url)
+
+ plus_button = page.locator(".plusButton")
+ count_value = page.locator(".countValue")
+
+ expect(count_value).to_have_text("1")
+ assert server.get("count") == 1
+ plus_button.click()
+ expect(count_value).to_have_text("2")
+ assert server.get("count") == 2
+ plus_button.click()
+ plus_button.click()
+ expect(count_value).to_have_text("4")
+ assert server.get("count") == 4
+ plus_button.click()
+ expect(count_value).to_have_text("5")
+ assert server.get("count") == 5
+
+
+@pytest.mark.parametrize("server_path", ["examples/test/model_react.py"])
+def test_react_model_slider(server, page):
+ url = f"http://127.0.0.1:{server.port}/"
+ page.goto(url)
+
+ slider = page.locator("input[type=range]")
+ expect(slider).to_have_value("2")
+ assert server.get("count") == 2
+ assert server.get("double") == 4
+
+ slider.fill("7")
+ expect(slider).to_have_value("7")
+ assert server.get("count") == 7
+ assert server.get("double") == 14
diff --git a/tests/test_react_serializer.py b/tests/test_react_serializer.py
new file mode 100644
index 0000000..e89491c
--- /dev/null
+++ b/tests/test_react_serializer.py
@@ -0,0 +1,154 @@
+from trame.app import get_server
+from trame.ui.html import DivLayout
+from trame.widgets import html
+from trame_client.utils.react import parse_directive_key, parse_v_for, split_text
+
+CLIENT_TYPE = "react"
+
+
+def test_split_text():
+ assert split_text("hello") == ["hello"]
+ assert split_text("{{ count }}") == [{"expr": "count"}]
+ assert split_text("a {{ b }} c") == ["a ", {"expr": "b"}, " c"]
+ assert split_text("{{ a }}{{ b + 1 }}") == [{"expr": "a"}, {"expr": "b + 1"}]
+
+
+def test_parse_v_for():
+ assert parse_v_for("item in items") == {
+ "item": "item",
+ "index": None,
+ "source": "items",
+ }
+ assert parse_v_for("(it, i) in items") == {
+ "item": "it",
+ "index": "i",
+ "source": "items",
+ }
+ assert parse_v_for("x of list.filter(v => v)") == {
+ "item": "x",
+ "index": None,
+ "source": "list.filter(v => v)",
+ }
+
+
+def test_parse_directive_key():
+ assert parse_directive_key("v-if") == ("if", None, [])
+ assert parse_directive_key("v-model.lazy") == ("model", None, ["lazy"])
+ assert parse_directive_key("v-model:hello.world") == ("model", "hello", ["world"])
+ assert parse_directive_key("v-slot:name") == ("slot", "name", [])
+
+
+def test_react_node_properties():
+ server = get_server("test_react_node_properties", client_type=CLIENT_TYPE)
+ widget = html.Div(
+ trame_server=server,
+ v_model_hello="world",
+ v_bind_hello="world",
+ id="static-id",
+ classes="a b",
+ tabindex=1,
+ )
+ node = widget.react_node
+ assert node["tag"] == "div"
+ assert node["attrs"] == {"id": "static-id", "class": "a b", "tabindex": 1}
+ assert node["props"] == {"hello": "world"}
+ assert node["dirs"]["models"] == [
+ {"arg": "hello", "modifiers": [], "expr": "world"}
+ ]
+
+
+def test_react_node_events():
+ server = get_server("test_react_node_events", client_type=CLIENT_TYPE)
+
+ def on_click(*_):
+ pass
+
+ widget = html.Div(
+ trame_server=server,
+ click="count++",
+ v_on_mouseout_left_stop="handler",
+ mousedown=(on_click, "[count]"),
+ )
+ node = widget.react_node
+ assert node["on"]["click"] == "count++"
+ assert node["on"]["mouseout.left.stop"] == "handler"
+ assert node["on"]["mousedown"].startswith("trigger('")
+ assert node["on"]["mousedown"].endswith("', [count])")
+
+
+def test_react_node_directives_and_children():
+ server = get_server("test_react_node_directives", client_type=CLIENT_TYPE)
+ with html.Div(trame_server=server, v_if=("show", True)) as root:
+ html.Span("value: {{ count }}", v_show="count > 0")
+ html.Li(v_for="(it, i) in items", key="i")
+
+ node = root.react_node
+ assert node["dirs"]["if"] == "show"
+ span, li = node["children"]
+ assert span["dirs"]["show"] == "count > 0"
+ assert span["children"] == ["value: ", {"expr": "count"}]
+ assert li["dirs"]["for"] == {"item": "it", "index": "i", "source": "items"}
+ assert li["props"] == {"key": "i"}
+ # tuple default registered in state
+ assert server.state["show"] is True
+
+
+def test_layout_flush_react_payload():
+ server = get_server("test_layout_flush_react", client_type=CLIENT_TYPE)
+ with DivLayout(server):
+ html.Button("Go", click="go()")
+
+ payload = server.state["trame__template_main"]
+ assert payload["version"] == 1
+ assert payload["root"]["tag"] == "div"
+ button = payload["root"]["children"][0]
+ assert button["tag"] == "button"
+ assert button["on"] == {"click": "go()"}
+ assert button["children"] == ["Go"]
+
+
+def test_r_star_aliases():
+ server = get_server("test_r_star_aliases", client_type=CLIENT_TYPE)
+ with html.Div(trame_server=server, r_if=("visible", True)) as root:
+ html.Span(r_show="count > 0")
+ html.Li(r_for="(it, i) in items", key="i")
+ html.Input(r_model="name_var")
+ html.Input(r_model_number="count")
+ html.Button(r_on_click_stop="count++")
+
+ node = root.react_node
+ span, li, input1, input2, button = node["children"]
+ assert node["dirs"]["if"] == "visible"
+ assert span["dirs"]["show"] == "count > 0"
+ assert li["dirs"]["for"] == {"item": "it", "index": "i", "source": "items"}
+ assert input1["dirs"]["models"] == [
+ {"arg": None, "modifiers": [], "expr": "name_var"}
+ ]
+ assert input2["dirs"]["models"] == [
+ {"arg": None, "modifiers": ["number"], "expr": "count"}
+ ]
+ assert button["on"]["click.stop"] == "count++"
+
+
+def test_direct_attribute_capture():
+ # Widgets like trame-vtk write formatted attributes into _attributes
+ server = get_server("test_direct_attr_capture", client_type=CLIENT_TYPE)
+ widget = html.Div(trame_server=server)
+ widget._attributes["ref"] = 'ref="view_1"'
+ widget._attributes["view_id"] = ':viewId="view_1Id"'
+ widget._attributes["evt"] = '@resize="onResize()"'
+ node = widget.react_node
+ assert node["attrs"]["ref"] == "view_1"
+ assert node["props"]["viewId"] == "view_1Id"
+ assert node["on"]["resize"] == "onResize()"
+
+
+def test_vue_html_untouched_by_capture():
+ # Same widget built for vue3 must serialize to the exact same HTML string
+ server = get_server("test_vue_html_untouched", client_type="vue3")
+ widget = html.Div(
+ trame_server=server,
+ v_model_hello="world",
+ v_bind_hello="world",
+ )
+ assert widget.html == ''