@xuda.io/runtime-bundle 1.0.1436 → 1.0.1438

package/js/xuda-worker-bundle.js

@@ -291,7 +291,30 @@ func.runtime.platform.emit = function (name, data) {
 };
 
 // ── Platform helpers for DOM-independent resource loading ──
-func.runtime.platform.load_script = function (url, type, callback) {
+func.runtime.platform.apply_element_attributes = function (node, attributes, excluded_keys = []) {
+  if (!node?.setAttribute || !attributes) {
+    return node;
+  }
+
+  const excluded = new Set(excluded_keys || []);
+  const attr_keys = Object.keys(attributes);
+  for (let index = 0; index < attr_keys.length; index++) {
+    const key = attr_keys[index];
+    if (!key || excluded.has(key)) {
+      continue;
+    }
+
+    const value = attributes[key];
+    if (value === false || typeof value === 'undefined') {
+      continue;
+    }
+
+    node.setAttribute(key, value === null ? '' : `${value}`);
+  }
+
+  return node;
+};
+func.runtime.platform.load_script = function (url, type, callback, attributes) {
   const doc = func.runtime.platform.get_document();
   if (!doc?.createElement || !doc?.head?.appendChild) {
     if (callback) {
@@ -299,19 +322,63 @@ func.runtime.platform.load_script = function (url, type, callback) {
     }
     return;
   }
+  const find_existing_script = function () {
+    const asset_key = attributes?.['data-xuda-asset-key'];
+    const scripts = doc.querySelectorAll ? Array.from(doc.querySelectorAll('script')) : [];
+    return scripts.find(function (script) {
+      if (asset_key && script.getAttribute('data-xuda-asset-key') === asset_key) {
+        return true;
+      }
+      return !!(url && script.getAttribute('src') === url);
+    }) || null;
+  };
+
+  const existing_script = find_existing_script();
+  if (existing_script) {
+    if (callback) {
+      if (existing_script.getAttribute('data-xuda-loaded') === 'true' || !url) {
+        callback();
+      } else {
+        existing_script.addEventListener('load', callback, { once: true });
+        existing_script.addEventListener('error', callback, { once: true });
+      }
+    }
+    return existing_script;
+  }
+
   const script = doc.createElement('script');
   script.src = url;
   if (type) script.type = type;
-  script.onload = callback;
+  func.runtime.platform.apply_element_attributes(script, attributes, ['src', 'type']);
+  script.onload = function () {
+    script.setAttribute('data-xuda-loaded', 'true');
+    if (callback) {
+      callback();
+    }
+  };
+  script.onerror = function () {
+    if (callback) {
+      callback();
+    }
+  };
   doc.head.appendChild(script);
+  return script;
 };
-func.runtime.platform.load_css = function (href) {
+func.runtime.platform.load_css = function (href, attributes) {
   const doc = func.runtime.platform.get_document();
   if (!doc?.createElement || !doc?.head) {
     return;
   }
   try {
-    if (doc.querySelector('link[href="' + href + '"]')) return;
+    const asset_key = attributes?.['data-xuda-asset-key'];
+    const existing_links = doc.querySelectorAll ? Array.from(doc.querySelectorAll('link')) : [];
+    const existing = existing_links.find(function (link) {
+      if (asset_key && link.getAttribute('data-xuda-asset-key') === asset_key) {
+        return true;
+      }
+      return !!(href && link.getAttribute('href') === href);
+    });
+    if (existing) return existing;
   } catch (err) {
     return;
   }
@@ -319,7 +386,9 @@ func.runtime.platform.load_css = function (href) {
   link.rel = 'stylesheet';
   link.type = 'text/css';
   link.href = href;
+  func.runtime.platform.apply_element_attributes(link, attributes, ['href']);
   doc.head.insertBefore(link, doc.head.firstChild);
+  return link;
 };
 func.runtime.platform.remove_js_css = function (filename, filetype) {
   const doc = func.runtime.platform.get_document();
@@ -353,6 +422,128 @@ func.runtime.platform.set_cursor = function (element, cursor) {
     node.style.cursor = cursor;
   }
 };
+func.runtime.program.normalize_doc_for_runtime = function (doc) {
+  if (!doc || doc.__xudaRuntimeNormalized || !Array.isArray(doc.progUi) || !doc.progUi.length) {
+    return doc;
+  }
+
+  const normalize_tag_name = function (tag_name) {
+    return `${tag_name || ''}`.trim().toLowerCase();
+  };
+  const merge_attributes = function (target, source) {
+    const merged = { ...(target || {}) };
+    const source_attributes = source || {};
+    const keys = Object.keys(source_attributes);
+
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index];
+      const value = source_attributes[key];
+      if (typeof value === 'undefined') {
+        continue;
+      }
+
+      if (key === 'class' && merged.class && value) {
+        const next_value = `${merged.class} ${value}`.trim();
+        merged.class = Array.from(new Set(next_value.split(/\s+/).filter(Boolean))).join(' ');
+        continue;
+      }
+
+      if (key === 'style' && merged.style && value) {
+        merged.style = `${merged.style}; ${value}`.trim();
+        continue;
+      }
+
+      if (typeof merged[key] === 'undefined') {
+        merged[key] = value;
+      }
+    }
+
+    return merged;
+  };
+  const normalize_nodes = function (nodes, state) {
+    const normalized_nodes = [];
+
+    for (let index = 0; index < (nodes || []).length; index++) {
+      const node = nodes[index];
+      if (!node || typeof node !== 'object') {
+        continue;
+      }
+
+      const tag_name = normalize_tag_name(node.tagName);
+
+      if (tag_name === '!doctype') {
+        state.changed = true;
+        continue;
+      }
+
+      if (tag_name === 'html') {
+        state.changed = true;
+        state.root_attributes = merge_attributes(state.root_attributes, node.attributes);
+        normalized_nodes.push.apply(normalized_nodes, normalize_nodes(node.children, state));
+        continue;
+      }
+
+      if (tag_name === 'head') {
+        state.changed = true;
+        normalized_nodes.push.apply(normalized_nodes, normalize_nodes(node.children, state));
+        continue;
+      }
+
+      if (tag_name === 'body') {
+        state.changed = true;
+        state.root_attributes = merge_attributes(state.root_attributes, node.attributes);
+        normalized_nodes.push.apply(normalized_nodes, normalize_nodes(node.children, state));
+        continue;
+      }
+
+      let next_node = node;
+      if (Array.isArray(node.children) && node.children.length) {
+        const next_children = normalize_nodes(node.children, state);
+        if (next_children !== node.children) {
+          next_node = {
+            ...node,
+            children: next_children,
+          };
+          state.changed = true;
+        }
+      }
+
+      normalized_nodes.push(next_node);
+    }
+
+    return normalized_nodes;
+  };
+
+  const [root_node, ...extra_nodes] = doc.progUi;
+  if (!root_node || typeof root_node !== 'object') {
+    return doc;
+  }
+
+  const state = {
+    changed: false,
+    root_attributes: {},
+  };
+
+  const normalized_children = normalize_nodes([...(root_node.children || []), ...extra_nodes], state);
+  const merged_attributes = merge_attributes(root_node.attributes, state.root_attributes);
+
+  if (!state.changed && !Object.keys(state.root_attributes).length) {
+    doc.__xudaRuntimeNormalized = true;
+    return doc;
+  }
+
+  return {
+    ...doc,
+    __xudaRuntimeNormalized: true,
+    progUi: [
+      {
+        ...root_node,
+        attributes: merged_attributes,
+        children: normalized_children,
+      },
+    ],
+  };
+};
 
 func.runtime.env = {
   get_url_params: function () {
@@ -610,6 +801,147 @@ func.runtime.workers.delete_promise = function (SESSION_ID, worker_id, promise_q
   delete registry_entry.promise_queue[promise_queue_id];
   return true;
 };
+func.runtime.render.clone_runtime_options = function (value) {
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch (_) {}
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(function (item) {
+      return func.runtime.render.clone_runtime_options(item);
+    });
+  }
+
+  if (value && typeof value === 'object') {
+    const cloned = {};
+    const keys = Object.keys(value);
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index];
+      cloned[key] = func.runtime.render.clone_runtime_options(value[key]);
+    }
+    return cloned;
+  }
+
+  return value;
+};
+func.runtime.render.normalize_runtime_bootstrap = function (raw_options = {}) {
+  const options = raw_options || {};
+  let app_computing_mode = options.app_computing_mode || '';
+  let app_render_mode = options.app_render_mode || '';
+  let app_client_activation = options.app_client_activation || '';
+  let ssr_payload = options.ssr_payload || null;
+
+  if (typeof ssr_payload === 'string') {
+    try {
+      ssr_payload = JSON.parse(ssr_payload);
+    } catch (_) {
+      ssr_payload = null;
+    }
+  }
+
+  if (ssr_payload && typeof ssr_payload === 'object') {
+    ssr_payload = func.runtime.render.clone_runtime_options(ssr_payload);
+  }
+
+  if (!app_computing_mode) {
+    if (app_render_mode === 'ssr_first_page' || app_render_mode === 'ssr_full') {
+      app_computing_mode = 'server';
+    } else {
+      app_computing_mode = 'main';
+    }
+  }
+
+  switch (app_computing_mode) {
+    case 'main':
+      app_render_mode = 'csr';
+      app_client_activation = 'none';
+      break;
+
+    case 'worker':
+      app_render_mode = 'csr';
+      app_client_activation = 'none';
+      break;
+
+    default:
+      app_computing_mode = 'server';
+      if (app_render_mode !== 'ssr_full') {
+        app_render_mode = 'ssr_first_page';
+      }
+      app_client_activation = app_render_mode === 'ssr_full' ? 'hydrate' : 'takeover';
+      break;
+  }
+
+  if (ssr_payload && typeof ssr_payload === 'object') {
+    if (!ssr_payload.app_render_mode) {
+      ssr_payload.app_render_mode = app_render_mode;
+    }
+    if (!ssr_payload.app_client_activation) {
+      ssr_payload.app_client_activation = app_client_activation;
+    }
+    if (!ssr_payload.app_computing_mode) {
+      ssr_payload.app_computing_mode = app_computing_mode;
+    }
+  }
+
+  return {
+    app_computing_mode,
+    app_render_mode,
+    app_client_activation,
+    ssr_payload,
+  };
+};
+func.runtime.render.apply_runtime_bootstrap_defaults = function (target = {}) {
+  const normalized = func.runtime.render.normalize_runtime_bootstrap(target);
+  target.app_computing_mode = normalized.app_computing_mode;
+  target.app_render_mode = normalized.app_render_mode;
+  target.app_client_activation = normalized.app_client_activation;
+  target.ssr_payload = normalized.ssr_payload;
+  return normalized;
+};
+func.runtime.render.is_server_render_mode = function (target = {}) {
+  const normalized = func.runtime.render.normalize_runtime_bootstrap(target?.opt || target);
+  return normalized.app_computing_mode === 'server' && normalized.app_render_mode !== 'csr';
+};
+func.runtime.render.is_takeover_mode = function (target = {}) {
+  const normalized = func.runtime.render.normalize_runtime_bootstrap(target?.opt || target);
+  return normalized.app_client_activation === 'takeover';
+};
+func.runtime.render.is_hydration_mode = function (target = {}) {
+  const normalized = func.runtime.render.normalize_runtime_bootstrap(target?.opt || target);
+  return normalized.app_client_activation === 'hydrate';
+};
+func.runtime.render.get_ssr_payload = function (target = {}) {
+  if (target?.opt?.ssr_payload) {
+    return target.opt.ssr_payload;
+  }
+  if (target?.ssr_payload) {
+    return target.ssr_payload;
+  }
+  const win = func.runtime.platform.get_window();
+  return win?.__XUDA_SSR__ || null;
+};
+func.runtime.render.should_use_ssr_payload = function (SESSION_ID, paramsP) {
+  const session = SESSION_OBJ?.[SESSION_ID];
+  const payload = func.runtime.render.get_ssr_payload(session);
+  if (!payload || payload._consumed) {
+    return false;
+  }
+  if (paramsP?.prog_id && payload.prog_id && payload.prog_id !== paramsP.prog_id) {
+    return false;
+  }
+  return true;
+};
+func.runtime.render.mark_ssr_payload_consumed = function (SESSION_ID) {
+  const session = SESSION_OBJ?.[SESSION_ID];
+  const payload = func.runtime.render.get_ssr_payload(session);
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  payload._consumed = true;
+  return true;
+};
 func.runtime.render.get_root_data_system = function (SESSION_ID) {
   return SESSION_OBJ[SESSION_ID]?.DS_GLB?.[0]?.data_system || null;
 };
@@ -1013,10 +1345,10 @@ func.runtime.resources.load_cdn = async function (SESSION_ID, resource) {
           await func.utils.load_js_on_demand(normalized_resource.src);
           break;
         case 'css':
-          await func.utils.load_js_on_demand(normalized_resource.src);
+          func.runtime.platform.load_css(normalized_resource.src);
           break;
         case 'module':
-          func.utils.load_js_on_demand(normalized_resource.src, 'module');
+          await func.utils.load_js_on_demand(normalized_resource.src, 'module');
           break;
         default:
           await func.utils.load_js_on_demand(normalized_resource.src);
@@ -2353,6 +2685,691 @@ func.common.fastHash = function (inputString) {
 };
 
 glb.new_xu_render = false;
+ func.runtime = func.runtime || {};
+func.runtime.ui = func.runtime.ui || {};
+func.runtime.render = func.runtime.render || {};
+func.runtime.widgets = func.runtime.widgets || {};
+
+// Shared render-tree contract helpers live here so browser and headless runtimes can resolve the same UI structure.
+
+func.runtime.render.TREE_CONTRACT_VERSION = func.runtime.render.TREE_CONTRACT_VERSION || 'xuda.render_tree.v1';
+func.runtime.render._tree_widget_capability_cache = func.runtime.render._tree_widget_capability_cache || {};
+
+func.runtime.render.safe_clone_tree_value = function (value) {
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch (_) {
+      // Fall through to the recursive clone below.
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(function (item) {
+      return func.runtime.render.safe_clone_tree_value(item);
+    });
+  }
+
+  if (value && typeof value === 'object') {
+    const cloned = {};
+    const keys = Object.keys(value);
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index];
+      cloned[key] = func.runtime.render.safe_clone_tree_value(value[key]);
+    }
+    return cloned;
+  }
+
+  return value;
+};
+func.runtime.render.sort_tree_debug_value = function (value) {
+  if (Array.isArray(value)) {
+    return value.map(function (item) {
+      return func.runtime.render.sort_tree_debug_value(item);
+    });
+  }
+
+  if (value && typeof value === 'object') {
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index];
+      sorted[key] = func.runtime.render.sort_tree_debug_value(value[key]);
+    }
+    return sorted;
+  }
+
+  return value;
+};
+func.runtime.render.is_tree_node = function (nodeP) {
+  return !!nodeP?.contract && nodeP.contract === func.runtime.render.TREE_CONTRACT_VERSION;
+};
+func.runtime.render.get_tree_source_node = function (nodeP) {
+  if (!func.runtime.render.is_tree_node(nodeP)) {
+    return nodeP || null;
+  }
+  return nodeP?.meta?.source_node || null;
+};
+func.runtime.render.get_tree_source_snapshot = function (nodeP) {
+  if (!func.runtime.render.is_tree_node(nodeP)) {
+    return func.runtime.render.safe_clone_tree_value(nodeP);
+  }
+  return nodeP?.meta?.source_snapshot || null;
+};
+func.runtime.render.get_tree_node_kind = function (nodeP) {
+  const tag_name = typeof nodeP?.tagName === 'string' ? nodeP.tagName.toLowerCase() : '';
+  const node_type = typeof nodeP?.type === 'string' ? nodeP.type.toLowerCase() : '';
+
+  if (tag_name === 'xu-widget') return 'widget';
+  if (tag_name === 'xu-single-view') return 'single_view';
+  if (tag_name === 'xu-multi-view') return 'multi_view';
+  if (tag_name === 'xu-panel') return 'panel';
+  if (tag_name === 'xu-teleport') return 'teleport';
+  if (tag_name === 'xurender') return 'placeholder';
+  if (tag_name === '#text' || node_type === 'text') return 'text';
+  if (!tag_name && typeof nodeP?.content === 'string' && !Array.isArray(nodeP?.children)) return 'text';
+  return 'element';
+};
+func.runtime.render.get_tree_node_id = function (nodeP, pathP) {
+  if (nodeP?.id) {
+    return nodeP.id;
+  }
+  if (nodeP?.id_org) {
+    return nodeP.id_org;
+  }
+  const normalized_path = Array.isArray(pathP) && pathP.length ? pathP.join('.') : 'root';
+  return `tree-node-${normalized_path}`;
+};
+func.runtime.render.get_tree_controls = function (attributes) {
+  const attrs = attributes || {};
+  const get_first_defined = function (keys) {
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index];
+      if (Object.prototype.hasOwnProperty.call(attrs, key)) {
+        return attrs[key];
+      }
+    }
+    return null;
+  };
+  return {
+    xu_for: get_first_defined(['xu-for', 'xu-exp:xu-for']),
+    xu_if: get_first_defined(['xu-if', 'xu-exp:xu-if']),
+    xu_render: get_first_defined(['xu-render', 'xu-exp:xu-render']),
+  };
+};
+func.runtime.render.get_tree_node_capabilities = async function (options) {
+  const attributes = options?.attributes || {};
+  const plugin_name = attributes['xu-widget'];
+  if (!plugin_name) {
+    return null;
+  }
+
+  const cache = func.runtime.render._tree_widget_capability_cache;
+  if (cache[plugin_name]) {
+    return func.runtime.render.safe_clone_tree_value(cache[plugin_name]);
+  }
+
+  let capabilities = {
+    browser: true,
+    headless: false,
+  };
+
+  try {
+    if (options.SESSION_ID && options.paramsP && func.runtime.widgets?.create_context && func.runtime.widgets?.get_definition) {
+      const widget_context = func.runtime.widgets.create_context(options.SESSION_ID, options.paramsP, attributes);
+      const definition = await func.runtime.widgets.get_definition(widget_context);
+      capabilities = func.runtime.widgets.normalize_capabilities(definition);
+    }
+  } catch (_) {
+    // Keep the safe browser-only default when the widget definition is unavailable.
+  }
+
+  cache[plugin_name] = capabilities;
+  return func.runtime.render.safe_clone_tree_value(capabilities);
+};
+func.runtime.render.ensure_tree_node = async function (options) {
+  if (!options?.nodeP) {
+    return null;
+  }
+  if (func.runtime.render.is_tree_node(options.nodeP)) {
+    return options.nodeP;
+  }
+  return await func.runtime.render.build_tree(options);
+};
+func.runtime.render.build_tree = async function (options) {
+  if (Array.isArray(options?.nodeP)) {
+    return await func.runtime.render.build_tree_list({
+      ...options,
+      nodesP: options.nodeP,
+    });
+  }
+
+  const nodeP = options?.nodeP;
+  if (!nodeP) {
+    return null;
+  }
+  if (func.runtime.render.is_tree_node(nodeP)) {
+    return nodeP;
+  }
+
+  const pathP = Array.isArray(options?.pathP) ? options.pathP.slice() : [];
+  const tree_path = pathP.length ? pathP.slice() : [0];
+  const attributes = func.runtime.render.safe_clone_tree_value(nodeP.attributes || {});
+  if (typeof nodeP.content !== 'undefined' && typeof attributes['xu-content'] === 'undefined') {
+    attributes['xu-content'] = func.runtime.render.safe_clone_tree_value(nodeP.content);
+  }
+
+  const widget_capabilities = await func.runtime.render.get_tree_node_capabilities({
+    SESSION_ID: options?.SESSION_ID,
+    paramsP: options?.paramsP,
+    attributes,
+  });
+  const children = [];
+  const child_nodes = Array.isArray(nodeP.children) ? nodeP.children : [];
+  const parent_tree_id = tree_path.join('.');
+
+  for (let index = 0; index < child_nodes.length; index++) {
+    const child_tree = await func.runtime.render.build_tree({
+      ...options,
+      nodeP: child_nodes[index],
+      pathP: tree_path.concat(index),
+      parent_tree_id: parent_tree_id,
+      keyP: index,
+      parent_nodeP: nodeP,
+    });
+    if (child_tree) {
+      children.push(child_tree);
+    }
+  }
+
+  const tree = {
+    contract: func.runtime.render.TREE_CONTRACT_VERSION,
+    id: func.runtime.render.get_tree_node_id(nodeP, tree_path),
+    xu_tree_id: `tree.${tree_path.join('.')}`,
+    kind: func.runtime.render.get_tree_node_kind(nodeP),
+    tagName: nodeP.tagName || null,
+    attributes,
+    text: typeof nodeP.text !== 'undefined' ? func.runtime.render.safe_clone_tree_value(nodeP.text) : null,
+    content: typeof nodeP.content !== 'undefined' ? func.runtime.render.safe_clone_tree_value(nodeP.content) : null,
+    children,
+    meta: {
+      tree_id: tree_path.join('.'),
+      path: tree_path,
+      parent_tree_id: options?.parent_tree_id || null,
+      key: typeof options?.keyP === 'undefined' ? null : options.keyP,
+      recordid: nodeP?.recordid || null,
+      dependency_fields: func.runtime.render.safe_clone_tree_value(nodeP?.dependency_fields || null),
+      iterate_info: func.runtime.render.safe_clone_tree_value(options?.parent_infoP?.iterate_info || nodeP?.iterate_info || null),
+      controls: func.runtime.render.get_tree_controls(attributes),
+      capabilities: widget_capabilities,
+      widget: attributes['xu-widget']
+        ? {
+            plugin_name: attributes['xu-widget'],
+            method: attributes['xu-method'] || '_default',
+            capabilities: widget_capabilities,
+          }
+        : null,
+      source_node_id: nodeP?.id || nodeP?.id_org || null,
+      source_node: nodeP,
+      source_snapshot: func.runtime.ui?.get_node_snapshot
+        ? func.runtime.ui.get_node_snapshot(nodeP)
+        : func.runtime.render.safe_clone_tree_value(nodeP),
+    },
+  };
+
+  return tree;
+};
+func.runtime.render.build_tree_list = async function (options) {
+  const nodes = Array.isArray(options?.nodesP) ? options.nodesP : [];
+  const trees = [];
+
+  for (let index = 0; index < nodes.length; index++) {
+    const tree = await func.runtime.render.build_tree({
+      ...options,
+      nodeP: nodes[index],
+      pathP: Array.isArray(options?.pathP) && options.pathP.length ? options.pathP.concat(index) : [index],
+      keyP: index,
+    });
+    if (tree) {
+      trees.push(tree);
+    }
+  }
+
+  return trees;
+};
+func.runtime.render.sanitize_tree_for_debug = function (treeP) {
+  if (Array.isArray(treeP)) {
+    return treeP.map(function (child) {
+      return func.runtime.render.sanitize_tree_for_debug(child);
+    });
+  }
+
+  if (!func.runtime.render.is_tree_node(treeP)) {
+    return func.runtime.render.sort_tree_debug_value(func.runtime.render.safe_clone_tree_value(treeP));
+  }
+
+  return {
+    contract: treeP.contract,
+    id: treeP.id,
+    xu_tree_id: treeP.xu_tree_id || null,
+    kind: treeP.kind,
+    tagName: treeP.tagName,
+    attributes: func.runtime.render.sort_tree_debug_value(treeP.attributes || {}),
+    text: treeP.text,
+    content: treeP.content,
+    children: treeP.children.map(function (child) {
+      return func.runtime.render.sanitize_tree_for_debug(child);
+    }),
+    meta: {
+      tree_id: treeP.meta?.tree_id || null,
+      path: func.runtime.render.safe_clone_tree_value(treeP.meta?.path || []),
+      parent_tree_id: treeP.meta?.parent_tree_id || null,
+      key: typeof treeP.meta?.key === 'undefined' ? null : treeP.meta.key,
+      recordid: treeP.meta?.recordid || null,
+      dependency_fields: func.runtime.render.sort_tree_debug_value(treeP.meta?.dependency_fields || null),
+      iterate_info: func.runtime.render.sort_tree_debug_value(treeP.meta?.iterate_info || null),
+      controls: func.runtime.render.sort_tree_debug_value(treeP.meta?.controls || null),
+      capabilities: func.runtime.render.sort_tree_debug_value(treeP.meta?.capabilities || null),
+      widget: treeP.meta?.widget
+        ? {
+            plugin_name: treeP.meta.widget.plugin_name,
+            method: treeP.meta.widget.method,
+            capabilities: func.runtime.render.sort_tree_debug_value(treeP.meta.widget.capabilities || null),
+          }
+        : null,
+      source_node_id: treeP.meta?.source_node_id || null,
+    },
+  };
+};
+func.runtime.render.serialize_tree = function (treeP, spacing = 2) {
+  return JSON.stringify(func.runtime.render.sanitize_tree_for_debug(treeP), null, spacing);
+};
+ func.runtime = func.runtime || {};
+func.runtime.ui = func.runtime.ui || {};
+func.runtime.render = func.runtime.render || {};
+func.runtime.widgets = func.runtime.widgets || {};
+
+// Shared string-renderer helpers live here so headless/server runtimes can materialize the render tree without a DOM.
+
+func.runtime.render.HTML_VOID_TAGS = func.runtime.render.HTML_VOID_TAGS || {
+  area: true,
+  base: true,
+  br: true,
+  col: true,
+  embed: true,
+  hr: true,
+  img: true,
+  input: true,
+  link: true,
+  meta: true,
+  param: true,
+  source: true,
+  track: true,
+  wbr: true,
+};
+func.runtime.render.escape_html = function (value) {
+  return `${value ?? ''}`
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#039;');
+};
+func.runtime.render.escape_html_attribute = function (value) {
+  return func.runtime.render.escape_html(value);
+};
+func.runtime.render.is_html_void_tag = function (tag_name) {
+  return !!func.runtime.render.HTML_VOID_TAGS[(tag_name || '').toLowerCase()];
+};
+func.runtime.render.is_falsey_render_value = function (value) {
+  if (value === false || value === null || typeof value === 'undefined') {
+    return true;
+  }
+  if (typeof value === 'number') {
+    return value === 0;
+  }
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    return normalized === '' || normalized === 'false' || normalized === '0' || normalized === 'null' || normalized === 'undefined' || normalized === 'off' || normalized === 'no';
+  }
+  return false;
+};
+func.runtime.render.should_render_tree_node = function (treeP) {
+  const controls = treeP?.meta?.controls || {};
+  if (controls.xu_if !== null && controls.xu_if !== undefined && func.runtime.render.is_falsey_render_value(controls.xu_if)) {
+    return false;
+  }
+  if (controls.xu_render !== null && controls.xu_render !== undefined && func.runtime.render.is_falsey_render_value(controls.xu_render)) {
+    return false;
+  }
+  return true;
+};
+func.runtime.render.is_tree_control_attribute = function (key) {
+  if (!key) {
+    return false;
+  }
+  return (
+    key.startsWith('xu-exp:') ||
+    key === 'xu-widget' ||
+    key === 'xu-method' ||
+    key === 'xu-for' ||
+    key === 'xu-for-key' ||
+    key === 'xu-for-val' ||
+    key === 'xu-if' ||
+    key === 'xu-render' ||
+    key === 'xu-bind' ||
+    key === 'xu-content' ||
+    key === 'xu-text' ||
+    key === 'xu-html' ||
+    key === 'xu-show' ||
+    key === 'xu-panel-program' ||
+    key === 'xu-teleport'
+  );
+};
+func.runtime.render.get_string_renderer_tag_name = function (treeP) {
+  switch (treeP?.kind) {
+    case 'widget':
+    case 'single_view':
+    case 'multi_view':
+    case 'panel':
+    case 'teleport':
+      return 'div';
+    case 'placeholder':
+      return null;
+    case 'text':
+      return null;
+    default:
+      return treeP?.tagName || 'div';
+  }
+};
+func.runtime.render.get_tree_terminal_content = function (treeP) {
+  const attributes = treeP?.attributes || {};
+  if (typeof attributes['xu-html'] !== 'undefined' && attributes['xu-html'] !== null) {
+    return {
+      value: `${attributes['xu-html']}`,
+      mode: 'html',
+    };
+  }
+  if (typeof attributes['xu-content'] !== 'undefined' && attributes['xu-content'] !== null) {
+    return {
+      value: `${attributes['xu-content']}`,
+      mode: 'html',
+    };
+  }
+  if (typeof attributes['xu-text'] !== 'undefined' && attributes['xu-text'] !== null) {
+    return {
+      value: `${attributes['xu-text']}`,
+      mode: 'text',
+    };
+  }
+  if (treeP?.kind === 'text') {
+    return {
+      value: typeof treeP?.text !== 'undefined' && treeP?.text !== null ? `${treeP.text}` : `${treeP?.content || ''}`,
+      mode: 'text',
+    };
+  }
+  return null;
+};
+func.runtime.render.render_tree_terminal_content = function (treeP) {
+  const terminal = func.runtime.render.get_tree_terminal_content(treeP);
+  if (!terminal) {
+    return null;
+  }
+  if (terminal.mode === 'html') {
+    return terminal.value;
+  }
+  return func.runtime.render.escape_html(terminal.value);
+};
+func.runtime.render.get_widget_fallback_markup = function (treeP) {
+  const widget_meta = treeP?.meta?.widget || {};
+  const capability_state = widget_meta?.capabilities?.headless ? 'headless-capable' : 'browser-only';
+  return `<!--xuda-widget:${func.runtime.render.escape_html(widget_meta.plugin_name || 'unknown')}:${capability_state}-->`;
+};
+func.runtime.render.get_tree_string_attributes = function (treeP, renderer_context) {
+  const attributes = func.runtime.render.safe_clone_tree_value(treeP?.attributes || {});
+  const attr_pairs = [];
+  const keys = Object.keys(attributes);
+
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index];
+    if (func.runtime.render.is_tree_control_attribute(key)) {
+      continue;
+    }
+    const value = attributes[key];
+    if (value === false || value === null || typeof value === 'undefined') {
+      continue;
+    }
+    if (value === true) {
+      attr_pairs.push(key);
+      continue;
+    }
+    const normalized_value = typeof value === 'object' ? JSON.stringify(value) : `${value}`;
+    attr_pairs.push(`${key}="${func.runtime.render.escape_html_attribute(normalized_value)}"`);
+  }
+
+  attr_pairs.push(`data-xuda-kind="${func.runtime.render.escape_html_attribute(treeP?.kind || 'element')}"`);
+  attr_pairs.push(`data-xuda-node-id="${func.runtime.render.escape_html_attribute(treeP?.id || treeP?.meta?.source_node_id || '')}"`);
+  attr_pairs.push(`data-xuda-tree-id="${func.runtime.render.escape_html_attribute(treeP?.meta?.tree_id || '')}"`);
+
+  if (treeP?.kind === 'widget' && treeP?.meta?.widget) {
+    attr_pairs.push(`data-xuda-widget="${func.runtime.render.escape_html_attribute(treeP.meta.widget.plugin_name || '')}"`);
+    attr_pairs.push(`data-xuda-widget-method="${func.runtime.render.escape_html_attribute(treeP.meta.widget.method || '_default')}"`);
+    attr_pairs.push(`data-xuda-widget-capability="${func.runtime.render.escape_html_attribute(treeP.meta.widget.capabilities?.headless ? 'headless' : 'browser')}"`);
+  }
+
+  if (treeP?.kind === 'teleport' && treeP?.attributes?.['xu-teleport']) {
+    attr_pairs.push(`data-xuda-teleport-target="${func.runtime.render.escape_html_attribute(treeP.attributes['xu-teleport'])}"`);
+  }
+
+  if ((treeP?.meta?.controls?.xu_for !== null && treeP?.meta?.controls?.xu_for !== undefined) && !renderer_context?.strip_iteration_markers) {
+    attr_pairs.push('data-xuda-xu-for="pending"');
+  }
+
+  return attr_pairs.length ? ' ' + attr_pairs.join(' ') : '';
+};
+func.runtime.render.render_tree_children_to_string = async function (treeP, renderer_context) {
+  if (!Array.isArray(treeP?.children) || !treeP.children.length) {
+    return '';
+  }
+  let html = '';
+  for (let index = 0; index < treeP.children.length; index++) {
+    html += await func.runtime.render.render_tree_to_string(treeP.children[index], {
+      ...renderer_context,
+      parent_tree: treeP,
+    });
+  }
+  return html;
+};
+func.runtime.render.render_tree_to_string = async function (treeP, renderer_context = {}) {
+  if (!treeP) {
+    return '';
+  }
+  if (Array.isArray(treeP)) {
+    let html = '';
+    for (let index = 0; index < treeP.length; index++) {
+      html += await func.runtime.render.render_tree_to_string(treeP[index], renderer_context);
+    }
+    return html;
+  }
+
+  const ensured_tree = await func.runtime.render.ensure_tree_node({
+    SESSION_ID: renderer_context?.SESSION_ID,
+    nodeP: treeP,
+    paramsP: renderer_context?.paramsP,
+    parent_infoP: renderer_context?.parent_infoP,
+    keyP: renderer_context?.keyP,
+    parent_nodeP: renderer_context?.parent_nodeP,
+  });
+
+  if (!ensured_tree || !func.runtime.render.should_render_tree_node(ensured_tree)) {
+    return '';
+  }
+
+  if (ensured_tree.kind === 'placeholder') {
+    if (renderer_context?.include_placeholders) {
+      return `<!--xuda-placeholder:${func.runtime.render.escape_html(ensured_tree.id || '')}-->`;
+    }
+    return '';
+  }
+
+  if (ensured_tree.kind === 'text') {
+    return func.runtime.render.render_tree_terminal_content(ensured_tree) || '';
+  }
+
+  const tag_name = func.runtime.render.get_string_renderer_tag_name(ensured_tree);
+  if (!tag_name || tag_name.toLowerCase() === 'script') {
+    return '';
+  }
+
+  const attributes = func.runtime.render.get_tree_string_attributes(ensured_tree, renderer_context);
+  const terminal_content = func.runtime.render.render_tree_terminal_content(ensured_tree);
+  let children_html = terminal_content !== null ? terminal_content : await func.runtime.render.render_tree_children_to_string(ensured_tree, renderer_context);
+
+  if (ensured_tree.kind === 'widget' && !children_html) {
+    children_html = func.runtime.render.get_widget_fallback_markup(ensured_tree);
+  }
+
+  if (func.runtime.render.is_html_void_tag(tag_name)) {
+    return `<${tag_name}${attributes}>`;
+  }
+
+  return `<${tag_name}${attributes}>${children_html}</${tag_name}>`;
+};
+func.runtime.render.render_to_string = async function (options = {}) {
+  const treeP = await func.runtime.render.ensure_tree_node({
+    SESSION_ID: options.SESSION_ID,
+    nodeP: options.treeP || options.nodeP,
+    paramsP: options.paramsP,
+    parent_infoP: options.parent_infoP,
+    keyP: options.keyP,
+    parent_nodeP: options.parent_nodeP,
+  });
+
+  return await func.runtime.render.render_tree_to_string(treeP, options);
+};
+func.runtime.render.get_server_render_mode = function (options = {}) {
+  const normalized = func.runtime.render.normalize_runtime_bootstrap({
+    app_computing_mode: options.app_computing_mode,
+    app_render_mode: options.app_render_mode,
+    app_client_activation: options.app_client_activation,
+  });
+
+  return normalized;
+};
+func.runtime.render.build_server_render_params = async function (options = {}) {
+  const SESSION_ID = options.SESSION_ID;
+  const prog_id = options.prog_id;
+  const dsSessionP = options.dsSessionP;
+  const _session = SESSION_OBJ?.[SESSION_ID] || {};
+  const _ds = _session?.DS_GLB?.[dsSessionP] || {};
+  const viewDoc = options.viewDoc || (await func.utils?.VIEWS_OBJ?.get?.(SESSION_ID, prog_id));
+
+  if (!viewDoc?.properties) {
+    throw new Error(`view document not found for ${prog_id}`);
+  }
+
+  const base_params = _ds?.screen_params ? func.runtime.render.safe_clone_tree_value(_ds.screen_params) : {};
+  const screenId = options.screenId || base_params.screenId || `ssr_${prog_id}_${dsSessionP || '0'}`;
+  const paramsP = {
+    ...base_params,
+    prog_id,
+    sourceScreenP: null,
+    $callingContainerP: null,
+    triggerIdP: null,
+    callingDataSource_objP: _ds,
+    rowIdP: typeof options.rowIdP !== 'undefined' ? options.rowIdP : (_ds?.currentRecordId || null),
+    renderType: viewDoc.properties?.renderType,
+    parameters_obj_inP: options.parameters_obj_inP || base_params.parameters_obj_inP || options.parameters_raw_obj || {},
+    source_functionP: options.source_functionP || base_params.source_functionP || 'render_string',
+    is_panelP: false,
+    screen_type: options.screen_type || base_params.screen_type || 'render_string',
+    screenInfo: viewDoc,
+    call_screen_propertiesP: base_params.call_screen_propertiesP,
+    parentDataSourceNoP: typeof _ds?.parentDataSourceNo === 'undefined' || _ds?.parentDataSourceNo === null ? 0 : _ds.parentDataSourceNo,
+    parameters_raw_obj: options.parameters_raw_obj || base_params.parameters_raw_obj || {},
+    dsSessionP,
+    screenId,
+    containerIdP: base_params.containerIdP || `ssr_container_${screenId}`,
+  };
+
+  if (_ds) {
+    _ds.screen_params = paramsP;
+  }
+
+  return paramsP;
+};
+func.runtime.render.build_prog_tree = async function (options = {}) {
+  const SESSION_ID = options.SESSION_ID;
+  const prog_id = options.prog_id;
+  const viewDoc = options.viewDoc || (await func.utils?.VIEWS_OBJ?.get?.(SESSION_ID, prog_id));
+
+  if (!viewDoc?.progUi?.length) {
+    throw new Error(`progUi not found for ${prog_id}`);
+  }
+
+  const paramsP = options.paramsP || (await func.runtime.render.build_server_render_params({
+    ...options,
+    SESSION_ID,
+    prog_id,
+    viewDoc,
+  }));
+  const root_index = typeof options.root_index === 'number' ? options.root_index : 0;
+  const root_node = func.runtime.render.safe_clone_tree_value(viewDoc.progUi[root_index]);
+  const tree = await func.runtime.render.build_tree({
+    SESSION_ID,
+    nodeP: root_node,
+    paramsP,
+  });
+
+  return {
+    tree,
+    paramsP,
+    viewDoc,
+  };
+};
+func.runtime.render.build_ssr_payload = function (render_program, options = {}) {
+  const runtime_profile = func.runtime.render.get_server_render_mode(options);
+  return {
+    contract: 'xuda.ssr.v1',
+    prog_id: options.prog_id,
+    screenId: render_program.paramsP.screenId,
+    containerId: render_program.paramsP.containerIdP,
+    app_computing_mode: runtime_profile.app_computing_mode,
+    app_render_mode: runtime_profile.app_render_mode,
+    app_client_activation: runtime_profile.app_client_activation,
+    tree_contract: func.runtime.render.TREE_CONTRACT_VERSION,
+  };
+};
+func.runtime.render.build_ssr_screen_html = function (html, render_program, options = {}) {
+  const payload = func.runtime.render.build_ssr_payload(render_program, options);
+  const screenId = func.runtime.render.escape_html_attribute(payload.screenId || '');
+  const containerId = func.runtime.render.escape_html_attribute(payload.containerId || '');
+  const activation = func.runtime.render.escape_html_attribute(payload.app_client_activation || 'takeover');
+
+  return `<div data-xuda-ssr-embed="true" class="xu_embed_div"><div id="${screenId}" class="xu_embed_container" data-xuda-ssr-screen="true" data-xuda-ssr-screen-id="${screenId}" data-xuda-activation="${activation}" style="display: contents;"><div id="${containerId}" data-xuda-ssr-root-frame="true" data-xuda-ssr-screen-id="${screenId}" data-xuda-activation="${activation}" style="display: contents;">${html}</div></div></div>`;
+};
+func.runtime.render.render_prog_to_string = async function (options = {}) {
+  const render_program = await func.runtime.render.build_prog_tree(options);
+  const html = await func.runtime.render.render_to_string({
+    ...options,
+    SESSION_ID: options.SESSION_ID,
+    treeP: render_program.tree,
+    paramsP: render_program.paramsP,
+  });
+  const ssr_payload = func.runtime.render.build_ssr_payload(render_program, options);
+  const screen_html = func.runtime.render.build_ssr_screen_html(html, render_program, options);
+
+  return {
+    prog_id: options.prog_id,
+    dsSessionP: render_program.paramsP.dsSessionP,
+    screenId: render_program.paramsP.screenId,
+    html,
+    screen_html,
+    tree_json: func.runtime.render.serialize_tree(render_program.tree),
+    paramsP: render_program.paramsP,
+    ssr_payload,
+  };
+};
  glb.DEBUG_INFO_OBJ = {};
 // var CONNECTION_ATTEMPTS = 0;
 glb.APP_INFO = {};
@@ -6060,6 +7077,13 @@ func.utils.DOCS_OBJ = {};
 func.utils.DOCS_OBJ.get = async function (SESSION_ID, idP) {
   if (!idP || idP === '0') return;
 
+  const normalize_runtime_doc = function (doc) {
+    if (!doc || !func.runtime.program?.normalize_doc_for_runtime) {
+      return doc;
+    }
+    return func.runtime.program.normalize_doc_for_runtime(doc);
+  };
+
   var _session = SESSION_OBJ[SESSION_ID];
   const _app_id = _session.app_id;
   if (!DOCS_OBJ[_app_id]) {
@@ -6081,7 +7105,8 @@ func.utils.DOCS_OBJ.get = async function (SESSION_ID, idP) {
     }
     let val = _session.project_data?.programs?.[idP];
     if (val) {
-      return (DOCS_OBJ[_app_id][idP] = val);
+      DOCS_OBJ[_app_id][idP] = normalize_runtime_doc(val);
+      return DOCS_OBJ[_app_id][idP];
     }
   }
 
@@ -6089,7 +7114,7 @@ func.utils.DOCS_OBJ.get = async function (SESSION_ID, idP) {
     const module = await func.common.get_module(SESSION_ID, `xuda-progs-loader-module.mjs`);
 
     if (idP !== 'system') {
-      DOCS_OBJ[_app_id][idP] = await module.DOCS_OBJ_get(SESSION_ID, idP);
+      DOCS_OBJ[_app_id][idP] = normalize_runtime_doc(await module.DOCS_OBJ_get(SESSION_ID, idP));
       if (DOCS_OBJ[_app_id][idP] && xu_isEmpty(DOCS_OBJ[_app_id][idP])) {
         await func.utils.remove_cached_objects(SESSION_ID);