@vortexm/vjt 0.1.1 → 0.1.3

package/dist/index.js

@@ -3683,6 +3683,159 @@ function logRuntimeError(scope, error, details) {
   console.error("[VJT error]", payload);
 }
 
+// src/lib/security.ts
+var BLOCKED_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var TRUSTED_CONFIG_ONLY_KEYS = /* @__PURE__ */ new Set(["widget", "style", "css", "actions", "events", "onClick", "onRefresh"]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function escapeHtmlAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function coerceFiniteNumber(value, kind, path) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return kind === "int" ? Math.trunc(value) : value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = kind === "int" ? Number.parseInt(value, 10) : Number.parseFloat(value);
+    if (Number.isFinite(parsed)) {
+      return kind === "int" ? Math.trunc(parsed) : parsed;
+    }
+  }
+  throw new Error(`Invalid ${kind} at ${path}`);
+}
+function isBlockedObjectKey(key) {
+  return BLOCKED_OBJECT_KEYS.has(key);
+}
+function hasBlockedReferenceSegment(reference) {
+  return reference.split(".").some((segment) => isBlockedObjectKey(segment));
+}
+function isTrustedConfigOnlyKey(key) {
+  return TRUSTED_CONFIG_ONLY_KEYS.has(key);
+}
+function templateValueUsesReference(value) {
+  if (typeof value === "string") {
+    return value.includes("$ref:");
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) => templateValueUsesReference(entry));
+  }
+  if (isPlainObject(value)) {
+    return Object.values(value).some((entry) => templateValueUsesReference(entry));
+  }
+  return false;
+}
+function sanitizeConfigStyleMap(styleMap) {
+  const safe = {};
+  for (const [key, value] of Object.entries(styleMap)) {
+    if (isBlockedObjectKey(key) || typeof value !== "string") {
+      continue;
+    }
+    safe[key] = value;
+  }
+  return safe;
+}
+function sanitizeUrl(rawValue, options = {}) {
+  if (typeof rawValue !== "string") {
+    return null;
+  }
+  const value = rawValue.trim();
+  if (!value) {
+    return null;
+  }
+  if (/^(javascript|data|vbscript):/i.test(value)) {
+    return null;
+  }
+  if (value.startsWith("//")) {
+    return null;
+  }
+  const schemeMatch = value.match(/^([A-Za-z][A-Za-z\d+\-.]*):/);
+  if (!schemeMatch) {
+    return options.allowRelative !== false ? value : null;
+  }
+  const scheme = schemeMatch[1].toLowerCase();
+  if (scheme === "http" || scheme === "https") {
+    return value;
+  }
+  if (scheme === "mailto" && options.allowMailto) {
+    return value;
+  }
+  return null;
+}
+function sanitizeMarkdownSource(markdown) {
+  return markdown.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function sanitizeGeneratedHtml(html) {
+  const withoutDangerousTags = html.replace(/<\s*(script|style|iframe|object|embed|link|meta|base|form)\b[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, "").replace(/<\s*(script|style|iframe|object|embed|link|meta|base|form)\b[^>]*\/?>/gi, "").replace(/\son[a-z]+\s*=\s*(".*?"|'.*?'|[^\s>]+)/gi, "");
+  return withoutDangerousTags.replace(/\s(href|src)\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/gi, (_match, attributeName, _full, dq, sq, bare) => {
+    const rawUrl = dq ?? sq ?? bare ?? "";
+    const safeUrl = sanitizeUrl(rawUrl, {
+      allowRelative: true,
+      allowMailto: attributeName.toLowerCase() === "href"
+    });
+    const fallback = attributeName.toLowerCase() === "href" ? "#" : "";
+    return ` ${attributeName}="${escapeHtmlAttribute(safeUrl ?? fallback)}"`;
+  });
+}
+function sanitizeSchemaValue(schema, value, path = "value") {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (schema.type === "object") {
+    if (!isPlainObject(value)) {
+      throw new Error(`Expected object at ${path}`);
+    }
+    const result = {};
+    for (const property of schema.properties ?? []) {
+      if (!property.name || isBlockedObjectKey(property.name)) {
+        continue;
+      }
+      result[property.name] = sanitizeSchemaValue(property, value[property.name], `${path}.${property.name}`);
+    }
+    return result;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) {
+      throw new Error(`Expected array at ${path}`);
+    }
+    return value.map((entry, index) => sanitizeSchemaValue(schema.elements, entry, `${path}[${index}]`));
+  }
+  switch (schema.type) {
+    case "int":
+      return coerceFiniteNumber(value, "int", path);
+    case "float":
+      return coerceFiniteNumber(value, "float", path);
+    case "boolean":
+      if (typeof value === "boolean") {
+        return value;
+      }
+      if (value === "true" || value === "1" || value === 1) {
+        return true;
+      }
+      if (value === "false" || value === "0" || value === 0) {
+        return false;
+      }
+      throw new Error(`Invalid boolean at ${path}`);
+    case "string": {
+      const stringValue = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : (() => {
+        throw new Error(`Invalid string at ${path}`);
+      })();
+      if (typeof schema.maxLength === "number" && stringValue.length > schema.maxLength) {
+        throw new Error(`String too long at ${path}`);
+      }
+      if (typeof schema.regexp === "string" && schema.regexp) {
+        const regexp = new RegExp(schema.regexp);
+        if (!regexp.test(stringValue)) {
+          throw new Error(`String does not match regexp at ${path}`);
+        }
+      }
+      return stringValue;
+    }
+    default:
+      return value;
+  }
+}
+
 // src/lib/network.ts
 var NetworkRuntime = class {
   requestsMap;
@@ -3707,7 +3860,12 @@ var NetworkRuntime = class {
       if (!config?.url) {
         continue;
       }
-      const source = new EventSource(config.url);
+      const safeUrl = sanitizeUrl(config.url, { allowRelative: true });
+      if (!safeUrl) {
+        logRuntimeError("sseConfig", new Error("Blocked unsafe SSE url"), { url: config.url });
+        continue;
+      }
+      const source = new EventSource(safeUrl);
       this.eventSources.push(source);
       for (const eventDefinition of config.events ?? []) {
         if (!eventDefinition?.name) {
@@ -3717,7 +3875,7 @@ var NetworkRuntime = class {
           void this.handleSseEvent(eventDefinition, event).catch((error) => {
             logRuntimeError("handleSseEvent", error, {
               eventName: eventDefinition.name,
-              url: config.url
+              url: safeUrl
             });
           });
         });
@@ -3745,7 +3903,11 @@ var NetworkRuntime = class {
     if (!requestUrl) {
       throw new Error(`Request ${requestName} has no url in config`);
     }
-    const response = await fetch(requestUrl, {
+    const safeRequestUrl = sanitizeUrl(requestUrl, { allowRelative: true });
+    if (!safeRequestUrl) {
+      throw new Error(`Request ${requestName} has unsafe url`);
+    }
+    const response = await fetch(safeRequestUrl, {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
@@ -3765,7 +3927,13 @@ var NetworkRuntime = class {
     } catch {
       throw new Error(`Request ${requestName} returned non-JSON response: ${responseText.slice(0, 120)}`);
     }
-    const result = json.result;
+    if (json.error) {
+      throw new Error(`Request ${requestName} returned JSON-RPC error: ${String(json.error.message ?? "unknown error")}`);
+    }
+    if (!definition.response) {
+      throw new Error(`Request ${requestName} must define response schema`);
+    }
+    const result = sanitizeSchemaValue(definition.response, json.result, `response.${requestName}`);
     if (definition.onResponse?.length) {
       await this.runActions(definition.onResponse, null, {
         currentValue: null,
@@ -3778,7 +3946,7 @@ var NetworkRuntime = class {
     if (schema.type === "object") {
       const result = {};
       for (const property of schema.properties ?? []) {
-        if (!property.name) {
+        if (!property.name || isBlockedObjectKey(property.name)) {
           continue;
         }
         result[property.name] = await this.buildSchemaValue(property, currentValue, responseValue);
@@ -3834,12 +4002,15 @@ var NetworkRuntime = class {
     }
   }
   async handleSseEvent(eventDefinition, event) {
-    let message = {};
+    let parsedMessage = {};
     try {
-      message = event.data ? JSON.parse(event.data) : {};
+      parsedMessage = event.data ? JSON.parse(event.data) : {};
     } catch {
-      message = { value: event.data ?? "" };
+      parsedMessage = { value: event.data ?? "" };
     }
+    const message = eventDefinition.message ? sanitizeSchemaValue(eventDefinition.message, parsedMessage, `sse.${eventDefinition.name}`) : (() => {
+      throw new Error(`SSE event ${eventDefinition.name} must define message schema`);
+    })();
     if (!eventDefinition.onEvent?.length) {
       return;
     }
@@ -3852,12 +4023,15 @@ var NetworkRuntime = class {
 };
 
 // src/lib/references.ts
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readPath(target, path) {
   let current = target;
   for (const segment of path) {
+    if (isBlockedObjectKey(segment)) {
+      return void 0;
+    }
     if (current == null) {
       return void 0;
     }
@@ -3869,6 +4043,9 @@ function readPath(target, path) {
     if (typeof current !== "object") {
       return void 0;
     }
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+      return void 0;
+    }
     current = current[segment];
   }
   return current;
@@ -3895,6 +4072,18 @@ function stringifyReferenceValue(value) {
   }
   return JSON.stringify(value);
 }
+function isReferenceValueEmpty(value) {
+  if (value === null || value === void 0) {
+    return true;
+  }
+  if (typeof value === "string") {
+    return value.length === 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+  return false;
+}
 function getCookieValue(name) {
   if (typeof document === "undefined") {
     return void 0;
@@ -3919,16 +4108,27 @@ function getCookieValue(name) {
   }
   return void 0;
 }
-function setCookieValue(name, value) {
+function setCookieValue(name, value, ttlDays) {
   if (typeof document === "undefined") {
     return;
   }
-  document.cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}; path=/`;
+  const ttlValue = typeof ttlDays === "number" && Number.isFinite(ttlDays) ? ttlDays : null;
+  const expires = ttlValue !== null ? `; max-age=${Math.max(0, Math.round(ttlValue * 24 * 60 * 60))}` : "";
+  document.cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}; path=/${expires}`;
+}
+function getUrlParamValue(name) {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return new URLSearchParams(window.location.search).get(name) ?? void 0;
 }
 var ReferenceRuntime = class {
   constructor(host) {
     this.host = host;
   }
+  isEmptyReference(reference, currentValue, responseValue) {
+    return isReferenceValueEmpty(this.resolveReference(reference, currentValue, responseValue));
+  }
   resolveReference(reference, currentValue, responseValue) {
     if (reference === "current") {
       return currentValue;
@@ -3951,6 +4151,9 @@ var ReferenceRuntime = class {
     if (reference.startsWith("app.")) {
       return this.host.getAppValue(reference.slice(4));
     }
+    if (reference.startsWith("url.")) {
+      return getUrlParamValue(reference.slice(4));
+    }
     const [widgetId, ...rest] = reference.split(".");
     const state = this.host.stateById.get(widgetId);
     if (!state) {
@@ -3982,7 +4185,7 @@ var ReferenceRuntime = class {
       }
       return readPath(currentValue.descriptor, reference.split("."));
     }
-    if (isPlainObject(currentValue) || Array.isArray(currentValue)) {
+    if (isPlainObject2(currentValue) || Array.isArray(currentValue)) {
       return readPath(currentValue, reference.split("."));
     }
     return void 0;
@@ -4007,7 +4210,7 @@ var ReferenceRuntime = class {
         if (state.widget === "combobox") {
           const index = state.selected ?? 0;
           const entry = (state.comboboxElements ?? [])[index];
-          if (isPlainObject(entry)) {
+          if (isPlainObject2(entry)) {
             return entry.value ?? entry.text ?? index;
           }
           return index;
@@ -4015,7 +4218,7 @@ var ReferenceRuntime = class {
         if (state.widget === "listbox") {
           const index = state.selected ?? 0;
           const entry = (state.listboxElements ?? [])[index];
-          if (isPlainObject(entry)) {
+          if (isPlainObject2(entry)) {
             return entry.value ?? entry.text ?? index;
           }
           return index;
@@ -4064,12 +4267,12 @@ var ReferenceRuntime = class {
         return readPath(state, field.split("."));
     }
   }
-  assignReference(reference, inputValue, _currentValue) {
-    if (reference.startsWith("current.")) {
+  assignReference(reference, inputValue, _currentValue, options) {
+    if (reference.startsWith("current.") || hasBlockedReferenceSegment(reference)) {
       return;
     }
     if (reference.startsWith("cookies.")) {
-      setCookieValue(reference.slice(8), stringifyReferenceValue(inputValue));
+      setCookieValue(reference.slice(8), stringifyReferenceValue(inputValue), toFiniteNumber(options?.cookieTtl) ?? void 0);
       return;
     }
     if (reference.startsWith("app.")) {
@@ -4110,7 +4313,7 @@ var ReferenceRuntime = class {
       case "elements":
         if (state.widget === "list" || state.widget === "grid-view") {
           this.clearListElementState(state.key);
-          state.elements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject(item) && typeof item.widget === "string") : [];
+          state.elements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject2(item) && typeof item.widget === "string") : [];
           state.elements.forEach((element, index) => {
             const listNode = this.host.nodeById.get(widgetId);
             if (listNode?.widget === "list" || listNode?.widget === "grid-view") {
@@ -4119,10 +4322,10 @@ var ReferenceRuntime = class {
           });
         }
         if (state.widget === "listbox") {
-          state.listboxElements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject(item)) : [];
+          state.listboxElements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject2(item)) : [];
         }
         if (state.widget === "combobox") {
-          state.comboboxElements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject(item)) : [];
+          state.comboboxElements = Array.isArray(inputValue) ? inputValue.filter((item) => isPlainObject2(item)) : [];
         }
         break;
       default:
@@ -4161,9 +4364,15 @@ var ReferenceRuntime = class {
     if (Array.isArray(template)) {
       return template.map((entry) => this.resolveMappedValue(entry, currentValue, responseValue));
     }
-    if (isPlainObject(template)) {
+    if (isPlainObject2(template)) {
       const result = {};
       for (const [key, value] of Object.entries(template)) {
+        if (isBlockedObjectKey(key)) {
+          continue;
+        }
+        if (isTrustedConfigOnlyKey(key) && templateValueUsesReference(value)) {
+          continue;
+        }
         result[key] = this.resolveMappedValue(value, currentValue, responseValue);
       }
       return result;
@@ -4171,7 +4380,7 @@ var ReferenceRuntime = class {
     return template;
   }
   isListElementContext(value) {
-    return isPlainObject(value) && value.kind === "list-element" && typeof value.listId === "string" && typeof value.index === "number" && isPlainObject(value.descriptor) && typeof value.descriptor.widget === "string";
+    return isPlainObject2(value) && value.kind === "list-element" && typeof value.listId === "string" && typeof value.index === "number" && isPlainObject2(value.descriptor) && typeof value.descriptor.widget === "string";
   }
   findNamedWidget(node, name) {
     if (!node) {
@@ -4251,6 +4460,7 @@ var ActionRuntime = class {
   dispatchWidgetEventImpl;
   executeRequest;
   resolveReference;
+  isEmptyReference;
   assignReference;
   resolveMappedValue;
   setWidgetEnabled;
@@ -4258,6 +4468,7 @@ var ActionRuntime = class {
   setUiReference;
   refreshWidgetTree;
   renderWidgetTree;
+  navigateTo;
   getContextMenuPosition;
   setActiveContextMenu;
   setActiveModalId;
@@ -4273,6 +4484,7 @@ var ActionRuntime = class {
     this.dispatchWidgetEventImpl = options.dispatchWidgetEvent;
     this.executeRequest = options.executeRequest;
     this.resolveReference = options.resolveReference;
+    this.isEmptyReference = options.isEmptyReference;
     this.assignReference = options.assignReference;
     this.resolveMappedValue = options.resolveMappedValue;
     this.setWidgetEnabled = options.setWidgetEnabled;
@@ -4280,6 +4492,7 @@ var ActionRuntime = class {
     this.setUiReference = options.setUiReference;
     this.refreshWidgetTree = options.refreshWidgetTree;
     this.renderWidgetTree = options.renderWidgetTree;
+    this.navigateTo = options.navigateTo;
     this.getContextMenuPosition = options.getContextMenuPosition;
     this.setActiveContextMenu = options.setActiveContextMenu;
     this.setActiveModalId = options.setActiveModalId;
@@ -4289,7 +4502,7 @@ var ActionRuntime = class {
   }
   async dispatchWidgetEvent(node, eventName, key, inputValue = null, pointer = null) {
     try {
-      if ((eventName === "onClick" || eventName === "onUserValueChange") && !this.isWidgetEnabled(node, key)) {
+      if ((eventName === "onClick" || eventName === "onUserValueChange" || eventName === "onEnter" || eventName === "onShiftEnter" || eventName === "onControlEnter") && !this.isWidgetEnabled(node, key)) {
         return;
       }
       const actions = node.events?.[eventName] ?? (eventName === "onClick" ? this.getInlineActions(node) : void 0);
@@ -4365,6 +4578,10 @@ var ActionRuntime = class {
       const requestName = name.slice(8);
       return this.executeRequest(requestName, context.currentValue);
     }
+    if (name.startsWith("navigate ")) {
+      await this.navigateTo(name.slice(9));
+      return null;
+    }
     if (name.startsWith("showMenu ")) {
       const menuId = name.slice(9);
       const menuState = this.stateById.get(menuId);
@@ -4418,8 +4635,12 @@ var ActionRuntime = class {
     if (name.startsWith("equals ")) {
       return this.resolveReference(name.slice(7), context.currentValue, context.responseValue) === action.args;
     }
+    if (name.startsWith("isEmpty ")) {
+      return this.isEmptyReference(name.slice(8), context.currentValue, context.responseValue);
+    }
     if (name.startsWith("set ")) {
-      this.assignReference(name.slice(4), inputValue, context.currentValue);
+      const args = typeof action.args === "object" && action.args !== null && !Array.isArray(action.args) ? action.args : void 0;
+      this.assignReference(name.slice(4), inputValue, context.currentValue, args);
       return inputValue;
     }
     if (name.startsWith("filter ")) {
@@ -4448,7 +4669,7 @@ function isIfElseArgs(value) {
 }
 
 // src/lib/dom-state.ts
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function supportsTextSelection(element) {
@@ -4618,7 +4839,7 @@ function getListElementContextFromElement(element, stateByKey) {
   }
   const listState = stateByKey.get(listId);
   const descriptor = listState?.elements?.[index];
-  if (!descriptor || !isPlainObject2(descriptor) || typeof descriptor.widget !== "string") {
+  if (!descriptor || !isPlainObject3(descriptor) || typeof descriptor.widget !== "string") {
     return null;
   }
   return {
@@ -5135,7 +5356,7 @@ var renderMdText = (env, node, state, key) => {
   const verticalAlign = VERTICAL_ALIGN_MAP2[node["vert-align"] ?? "center"];
   const common = state.id ? ` id="${env.escapeHtml(state.id)}"` : "";
   const markdown = env.resolveI18nValue(state.text ?? node.text);
-  const html = markdownConverter.makeHtml(markdown);
+  const html = sanitizeGeneratedHtml(markdownConverter.makeHtml(sanitizeMarkdownSource(markdown)));
   const inlineStyle = [
     "display:flex",
     `align-items:${verticalAlign}`,
@@ -5241,7 +5462,7 @@ var renderCheckbox = (env, node, state, key) => {
 
 // src/lib/widgets/image.ts
 var renderImage = (env, node, state, key) => {
-  const url = env.escapeHtml(state.url ?? node.url ?? "");
+  const url = env.escapeHtml(sanitizeUrl(state.url ?? node.url ?? "", { allowRelative: true }) ?? "");
   const styleParts = [
     "box-sizing:border-box",
     "width:100%",
@@ -5268,7 +5489,7 @@ var renderLink = (env, node, state, key) => {
   const classes = `vjt-link vjt-link--${type}${enabled ? "" : " is-disabled"}`;
   const styleString = env.buildStyleString(node);
   const styleAttribute = styleString ? ` style="${env.escapeHtml(styleString)}"` : "";
-  const href = enabled && typeof node.url === "string" ? node.url : "#";
+  const href = enabled ? sanitizeUrl(state.url ?? node.url, { allowRelative: true, allowMailto: true }) ?? "#" : "#";
   const tabIndex = enabled ? "" : ' tabindex="-1" aria-disabled="true"';
   return `<a${state.id ? ` id="${env.escapeHtml(state.id)}"` : ""}${env.buildWidgetDataAttributes(key, node)} class="${classes}" data-widget="link" href="${env.escapeHtml(href)}"${tabIndex}${styleAttribute}>${text}</a>`;
 };
@@ -5386,6 +5607,31 @@ function renderContextMenuOverlay(env, menu) {
 }
 
 // src/lib/widgets/bindings.ts
+function bindKeyboardSubmitEvents(element, node, key, env) {
+  const hasKeyboardEvents = Boolean(
+    node.events?.onEnter?.length || node.events?.onShiftEnter?.length || node.events?.onControlEnter?.length
+  );
+  if (!hasKeyboardEvents) {
+    return;
+  }
+  element.addEventListener("keydown", (event) => {
+    if (event.key !== "Enter") {
+      return;
+    }
+    let eventName = null;
+    if (event.ctrlKey) {
+      eventName = "onControlEnter";
+    } else if (event.shiftKey) {
+      eventName = "onShiftEnter";
+    } else {
+      eventName = "onEnter";
+    }
+    if (!eventName || !node.events?.[eventName]?.length) {
+      return;
+    }
+    void env.dispatchWidgetEvent(node, eventName, key, env.getActionInputValueForElement(element, node), null);
+  });
+}
 function bindWidgetInputBehavior(root, env) {
   for (const input of Array.from(root.querySelectorAll(".vjt-edit"))) {
     if (!(input instanceof HTMLInputElement)) {
@@ -5453,6 +5699,7 @@ function bindWidgetEvents(root, env) {
       continue;
     }
     if (element instanceof HTMLInputElement && element.dataset.widget === "edit") {
+      bindKeyboardSubmitEvents(element, node, key, env);
       element.addEventListener("input", () => {
         const state = env.stateByKey.get(key);
         if (state) {
@@ -5470,6 +5717,7 @@ function bindWidgetEvents(root, env) {
       continue;
     }
     if (element instanceof HTMLTextAreaElement && element.dataset.widget === "textarea") {
+      bindKeyboardSubmitEvents(element, node, key, env);
       element.addEventListener("input", () => {
         const state = env.stateByKey.get(key);
         if (state) {
@@ -5487,6 +5735,7 @@ function bindWidgetEvents(root, env) {
       continue;
     }
     if (element instanceof HTMLInputElement && element.dataset.widget === "checkbox") {
+      bindKeyboardSubmitEvents(element, node, key, env);
       element.addEventListener("change", () => {
         const state = env.stateByKey.get(key);
         if (state) {
@@ -5504,6 +5753,7 @@ function bindWidgetEvents(root, env) {
       continue;
     }
     if (element instanceof HTMLSelectElement && (element.dataset.widget === "listbox" || element.dataset.widget === "combobox")) {
+      bindKeyboardSubmitEvents(element, node, key, env);
       element.addEventListener("change", () => {
         const state = env.stateByKey.get(key);
         if (state) {
@@ -5521,6 +5771,7 @@ function bindWidgetEvents(root, env) {
       continue;
     }
     if (element instanceof HTMLInputElement && element.dataset.widget === "radio-group") {
+      bindKeyboardSubmitEvents(element, node, key, env);
       element.addEventListener("change", () => {
         const state = env.stateByKey.get(key);
         if (state) {
@@ -5800,7 +6051,7 @@ function toFiniteNumber3(value) {
   }
   return null;
 }
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function deepClone(value) {
@@ -5810,6 +6061,9 @@ function sanitizeIdFragment2(value) {
   const cleaned = value.replaceAll(/[^A-Za-z0-9_-]+/g, "");
   return cleaned || "item";
 }
+function buildDefinitionSignature(value) {
+  return JSON.stringify(value) ?? "null";
+}
 function isGeneratedElementId(value) {
   return !value.includes(".") && !value.includes(":") && /Element\d+/.test(value);
 }
@@ -5855,6 +6109,7 @@ var RuntimeRenderer = class {
   actionsMap;
   requestsMap;
   sseConfigs;
+  systemEvents;
   resourceManager;
   actionFunctions;
   backendUrl;
@@ -5883,7 +6138,7 @@ var RuntimeRenderer = class {
   constructor(description, options = {}) {
     this.description = deepClone(description);
     this.resourceManager = options.resourceManager ?? null;
-    const customStyleMap = options.styleMap ?? this.resourceManager?.getStyleMap() ?? {};
+    const customStyleMap = sanitizeConfigStyleMap(options.styleMap ?? this.resourceManager?.getStyleMap() ?? {});
     this.styleMap = {
       ...DEFAULT_STYLE_MAP,
       ...customStyleMap
@@ -5895,6 +6150,7 @@ var RuntimeRenderer = class {
     this.requestsMap = options.requestsMap ?? this.resourceManager?.getRequestsMap() ?? {};
     const resolvedSseConfigs = options.sseConfigs ?? this.resourceManager?.getSseConfigs() ?? [];
     this.sseConfigs = Array.isArray(resolvedSseConfigs) ? resolvedSseConfigs : resolvedSseConfigs ? [resolvedSseConfigs] : [];
+    this.systemEvents = options.systemEvents ?? this.resourceManager?.getSystemEvents() ?? {};
     this.actionFunctions = options.actionFunctions ?? {};
     this.backendUrl = options.backendUrl;
     this.initialRuntimeSnapshot = options.runtimeSnapshot ? deepClone(options.runtimeSnapshot) : null;
@@ -5910,6 +6166,8 @@ var RuntimeRenderer = class {
             return this.language;
           case "theme":
             return this.theme;
+          case "urlPath":
+            return typeof window === "undefined" ? "" : window.location.pathname;
           default:
             return void 0;
         }
@@ -5923,6 +6181,15 @@ var RuntimeRenderer = class {
             this.theme = typeof value === "boolean" ? value ? "light" : "dark" : value === "light" || value === "dark" ? value : "dark";
             document.documentElement.dataset.vjtTheme = this.theme;
             break;
+          case "urlPath": {
+            if (typeof window === "undefined") {
+              break;
+            }
+            const nextPath = typeof value === "string" && value.trim() ? value.trim() : "/";
+            const normalizedPath = nextPath.startsWith("/") ? nextPath : `/${nextPath}`;
+            window.history.replaceState(window.history.state, "", `${normalizedPath}${window.location.search}${window.location.hash}`);
+            break;
+          }
           default:
             break;
         }
@@ -5948,7 +6215,8 @@ var RuntimeRenderer = class {
       dispatchWidgetEvent: (node, eventName, key, inputValue, pointer) => this.actionRuntime.dispatchWidgetEvent(node, eventName, key, inputValue, pointer),
       executeRequest: (requestName, currentValue) => this.networkRuntime.executeRequest(requestName, currentValue),
       resolveReference: (reference, currentValue, responseValue) => this.referenceRuntime.resolveReference(reference, currentValue, responseValue),
-      assignReference: (reference, inputValue, currentValue) => this.referenceRuntime.assignReference(reference, inputValue, currentValue),
+      isEmptyReference: (reference, currentValue, responseValue) => this.referenceRuntime.isEmptyReference(reference, currentValue, responseValue),
+      assignReference: (reference, inputValue, currentValue, options2) => this.referenceRuntime.assignReference(reference, inputValue, currentValue, options2),
       resolveMappedValue: (template, currentValue, responseValue) => this.referenceRuntime.resolveMappedValue(template, currentValue, responseValue),
       setWidgetEnabled: (widgetId, enabled) => this.setWidgetEnabled(widgetId, enabled),
       clearWidget: (widgetId) => this.clearWidget(widgetId),
@@ -5968,6 +6236,7 @@ var RuntimeRenderer = class {
       },
       refreshWidgetTree: (widgetId) => this.refreshWidgetTree(widgetId),
       renderWidgetTree: (widgetId) => this.renderWidgetTree(widgetId),
+      navigateTo: (url) => this.navigateTo(url),
       getContextMenuPosition: (menuId, pointer) => getContextMenuPosition(menuId, pointer ?? null, this.lastPointer, this.nodeById),
       setActiveContextMenu: (menu) => {
         this.activeContextMenu = menu;
@@ -5996,7 +6265,9 @@ var RuntimeRenderer = class {
     this.afterRender = options.afterRender;
     this.onRuntimeSnapshot = options.onRuntimeSnapshot ?? this.onRuntimeSnapshot;
     const render = async () => {
+      await this.runSystemEvent("onBeforeRender");
       await this.rerenderRoot();
+      await this.runSystemEvent("onAfterRender");
     };
     const renderSync = () => {
       void render().catch((error) => {
@@ -6064,6 +6335,31 @@ var RuntimeRenderer = class {
     }
     return Promise.resolve();
   }
+  async runSystemEvent(eventName) {
+    const actions = this.systemEvents[eventName];
+    if (!actions?.length) {
+      return;
+    }
+    await this.actionRuntime.runActions(actions, null, { currentValue: null });
+  }
+  async navigateTo(url) {
+    if (typeof window === "undefined" || !url.trim()) {
+      return;
+    }
+    const safeUrl = sanitizeUrl(url, { allowRelative: true });
+    if (!safeUrl) {
+      throw new Error("Blocked unsafe navigation url");
+    }
+    const nextUrl = new URL(safeUrl, window.location.href);
+    if (nextUrl.origin !== window.location.origin) {
+      window.location.assign(nextUrl.toString());
+      return;
+    }
+    window.history.pushState(window.history.state, "", `${nextUrl.pathname}${nextUrl.search}${nextUrl.hash}`);
+    await this.runSystemEvent("onBeforeNavigate");
+    await this.rerenderRoot();
+    await this.runSystemEvent("onAfterNavigate");
+  }
   reindexStaticTree() {
     this.nodeByKey.clear();
     this.nodeById.clear();
@@ -6292,6 +6588,7 @@ var RuntimeRenderer = class {
         existing.id = stateId2;
         this.stateById.set(stateId2, existing);
       }
+      this.syncStateDefinition(existing, node);
       return existing;
     }
     const stateId = node.id ?? (isGeneratedElementId(key) ? key : void 0);
@@ -6361,6 +6658,7 @@ var RuntimeRenderer = class {
           id: stateId,
           name: node.name,
           enabled: normalizeBoolean(node.enabled, true),
+          definitionSignature: buildDefinitionSignature(node.elements ?? []),
           elements: deepClone(node.elements ?? [])
         };
         break;
@@ -6371,6 +6669,7 @@ var RuntimeRenderer = class {
           id: stateId,
           name: node.name,
           enabled: normalizeBoolean(node.enabled, true),
+          definitionSignature: buildDefinitionSignature(node.elements ?? []),
           listboxElements: deepClone(node.elements ?? []),
           selected: toFiniteNumber3(node.selected) ?? 0
         };
@@ -6382,6 +6681,7 @@ var RuntimeRenderer = class {
           id: stateId,
           name: node.name,
           enabled: normalizeBoolean(node.enabled, true),
+          definitionSignature: buildDefinitionSignature(node.elements ?? []),
           comboboxElements: deepClone(node.elements ?? []),
           selected: toFiniteNumber3(node.selected) ?? 0
         };
@@ -6445,6 +6745,45 @@ var RuntimeRenderer = class {
     }
     return state;
   }
+  syncStateDefinition(state, node) {
+    if (state.widget !== node.widget) {
+      return;
+    }
+    switch (node.widget) {
+      case "list":
+      case "grid-view": {
+        const nextSignature = buildDefinitionSignature(node.elements ?? []);
+        if (state.definitionSignature !== nextSignature) {
+          if (state.widget === "list" || state.widget === "grid-view") {
+            this.clearListElementState(state.key);
+            state.elements = deepClone(node.elements ?? []);
+            state.definitionSignature = nextSignature;
+          }
+        }
+        break;
+      }
+      case "listbox": {
+        const nextSignature = buildDefinitionSignature(node.elements ?? []);
+        if (state.definitionSignature !== nextSignature) {
+          state.listboxElements = deepClone(node.elements ?? []);
+          state.selected = toFiniteNumber3(node.selected) ?? 0;
+          state.definitionSignature = nextSignature;
+        }
+        break;
+      }
+      case "combobox": {
+        const nextSignature = buildDefinitionSignature(node.elements ?? []);
+        if (state.definitionSignature !== nextSignature) {
+          state.comboboxElements = deepClone(node.elements ?? []);
+          state.selected = toFiniteNumber3(node.selected) ?? 0;
+          state.definitionSignature = nextSignature;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
   getStateForNode(node, fallbackPath) {
     const key = fallbackPath ? this.resolveNodeKey(node, fallbackPath) : node.id ?? this.resolveNodeKey(node, `auto:${node.widget}`);
     return this.ensureWidgetState(node, key);
@@ -6835,7 +7174,7 @@ var RuntimeRenderer = class {
       return;
     }
     const descriptor = listState.elements[indexValue];
-    if (!descriptor || !isPlainObject3(descriptor) || typeof descriptor.widget !== "string") {
+    if (!descriptor || !isPlainObject4(descriptor) || typeof descriptor.widget !== "string") {
       return;
     }
     mutate(descriptor);
@@ -7026,6 +7365,7 @@ var ResourceManager = class {
   actions = {};
   requests = {};
   sse = {};
+  systemEvents = {};
   i18n = {};
   styles = {};
   constructor(input = {}) {
@@ -7035,6 +7375,7 @@ var ResourceManager = class {
     this.actions = { ...input.actions ?? {} };
     this.requests = { ...input.requests ?? {} };
     this.sse = { ...input.sse ?? {} };
+    this.systemEvents = { ...input.systemEvents ?? {} };
     this.i18n = { ...input.i18n ?? {} };
     this.styles = { ...input.styles ?? {} };
   }
@@ -7053,6 +7394,9 @@ var ResourceManager = class {
   getSseConfigs() {
     return Object.values(this.sse);
   }
+  getSystemEvents() {
+    return this.systemEvents;
+  }
   getI18n() {
     return this.i18n;
   }

package/dist/lib/action-runtime.d.ts

@@ -19,13 +19,17 @@ type ActionRuntimeOptions = {
     } | null) => Promise<void>;
     executeRequest: (requestName: string, currentValue: unknown) => Promise<unknown>;
     resolveReference: (reference: string, currentValue: unknown, responseValue: unknown) => unknown;
-    assignReference: (reference: string, inputValue: unknown, currentValue: unknown) => void;
+    isEmptyReference: (reference: string, currentValue: unknown, responseValue: unknown) => boolean;
+    assignReference: (reference: string, inputValue: unknown, currentValue: unknown, options?: {
+        cookieTtl?: unknown;
+    }) => void;
     resolveMappedValue: (template: unknown, currentValue: unknown, responseValue: unknown) => unknown;
     setWidgetEnabled: (widgetId: string, enabled: boolean) => void;
     clearWidget: (widgetId: string) => void;
     setUiReference: (widgetId: string, resourceRef: string) => void;
     refreshWidgetTree: (widgetId: string) => Promise<void>;
     renderWidgetTree: (widgetId: string) => Promise<void>;
+    navigateTo: (url: string) => Promise<void>;
     getContextMenuPosition: (menuId: string, pointer?: {
         x: number;
         y: number;
@@ -52,6 +56,7 @@ export declare class ActionRuntime {
     private readonly dispatchWidgetEventImpl;
     private readonly executeRequest;
     private readonly resolveReference;
+    private readonly isEmptyReference;
     private readonly assignReference;
     private readonly resolveMappedValue;
     private readonly setWidgetEnabled;
@@ -59,6 +64,7 @@ export declare class ActionRuntime {
     private readonly setUiReference;
     private readonly refreshWidgetTree;
     private readonly renderWidgetTree;
+    private readonly navigateTo;
     private readonly getContextMenuPosition;
     private readonly setActiveContextMenu;
     private readonly setActiveModalId;

package/dist/lib/references.d.ts

@@ -13,10 +13,13 @@ type ReferenceRuntimeHost = {
 export declare class ReferenceRuntime {
     private readonly host;
     constructor(host: ReferenceRuntimeHost);
+    isEmptyReference(reference: string, currentValue: unknown, responseValue: unknown): boolean;
     resolveReference(reference: string, currentValue: unknown, responseValue: unknown): unknown;
     resolveCurrentReference(reference: string, currentValue: unknown): unknown;
     readWidgetField(state: WidgetState, field: string): unknown;
-    assignReference(reference: string, inputValue: unknown, _currentValue: unknown): void;
+    assignReference(reference: string, inputValue: unknown, _currentValue: unknown, options?: {
+        cookieTtl?: unknown;
+    }): void;
     clearListElementState(listKey: string): void;
     resolveMappedValue(template: unknown, currentValue: unknown, responseValue: unknown): unknown;
     isListElementContext(value: unknown): value is ListElementContext;

package/dist/lib/resource-manager.d.ts

@@ -1,9 +1,10 @@
-import type { ActionMap, DescriptionNode, I18nMap, RequestMap, SseConfig, StyleMap } from './types.js';
+import type { ActionMap, DescriptionNode, I18nMap, RequestMap, SseConfig, SystemEventsMap, StyleMap } from './types.js';
 export type ResourceManagerInput = {
     ui?: Record<string, DescriptionNode>;
     actions?: ActionMap;
     requests?: RequestMap;
     sse?: Record<string, SseConfig>;
+    systemEvents?: SystemEventsMap;
     i18n?: I18nMap;
     styles?: StyleMap;
 };
@@ -12,6 +13,7 @@ export declare class ResourceManager {
     private actions;
     private requests;
     private sse;
+    private systemEvents;
     private i18n;
     private styles;
     constructor(input?: ResourceManagerInput);
@@ -20,6 +22,7 @@ export declare class ResourceManager {
     getActionsMap(): ActionMap;
     getRequestsMap(): RequestMap;
     getSseConfigs(): SseConfig[];
+    getSystemEvents(): SystemEventsMap;
     getI18n(): I18nMap;
     getStyleMap(): StyleMap;
 }

package/dist/lib/security.d.ts

@@ -0,0 +1,13 @@
+import type { RequestSchema, StyleMap } from './types.js';
+export declare function isBlockedObjectKey(key: string): boolean;
+export declare function hasBlockedReferenceSegment(reference: string): boolean;
+export declare function isTrustedConfigOnlyKey(key: string): boolean;
+export declare function templateValueUsesReference(value: unknown): boolean;
+export declare function sanitizeConfigStyleMap(styleMap: StyleMap): StyleMap;
+export declare function sanitizeUrl(rawValue: unknown, options?: {
+    allowRelative?: boolean;
+    allowMailto?: boolean;
+}): string | null;
+export declare function sanitizeMarkdownSource(markdown: string): string;
+export declare function sanitizeGeneratedHtml(html: string): string;
+export declare function sanitizeSchemaValue(schema: RequestSchema, value: unknown, path?: string): unknown;

package/dist/lib/types.d.ts

@@ -3,7 +3,8 @@ export type LayoutType = 'vertical' | 'horizontal' | 'grid';
 export type TextAlign = 'left' | 'center' | 'right';
 export type VerticalAlign = 'top' | 'center' | 'bottom';
 export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-export type WidgetEventName = 'onClick' | 'onUserValueChange' | 'onRefresh';
+export type WidgetEventName = 'onClick' | 'onUserValueChange' | 'onRefresh' | 'onEnter' | 'onShiftEnter' | 'onControlEnter';
+export type SystemEventName = 'onBeforeRender' | 'onAfterRender' | 'onBeforeNavigate' | 'onAfterNavigate';
 export type PrimitiveRequestType = 'int' | 'float' | 'boolean' | 'string';
 export type ActionDefinition = {
     action: string;
@@ -84,11 +85,13 @@ export type I18nMap = Record<string, Record<string, string>>;
 export type ActionMap = Record<string, ActionDefinition[]>;
 export type RequestMap = Record<string, RequestDefinition>;
 export type SseConfigInput = SseConfig | SseConfig[];
+export type SystemEventsMap = Partial<Record<SystemEventName, ActionDefinition[]>>;
 export type WidgetState = {
     key: string;
     widget: DescriptionNode['widget'];
     id?: string;
     name?: string;
+    definitionSignature?: string;
     currentRef?: string;
     text?: string;
     url?: string;
@@ -132,6 +135,7 @@ export type RenderJsonOptions = {
     actionsMap?: ActionMap;
     requestsMap?: RequestMap;
     sseConfigs?: SseConfigInput;
+    systemEvents?: SystemEventsMap;
     actionFunctions?: Record<string, () => unknown>;
     backendUrl?: string;
     resourceManager?: ResourceManager;

package/dist/lib/widgets/bindings.d.ts

@@ -12,7 +12,7 @@ type BindingEnvironment = {
     }) => void;
     updatePointerFromEvent: (event: MouseEvent) => void;
     updateOwningListElementDescriptor: (element: HTMLElement, mutate: (descriptor: DescriptionNode) => void) => void;
-    dispatchWidgetEvent: (node: DescriptionNode, eventName: 'onClick' | 'onUserValueChange', key: string, inputValue?: unknown, pointer?: {
+    dispatchWidgetEvent: (node: DescriptionNode, eventName: 'onClick' | 'onUserValueChange' | 'onEnter' | 'onShiftEnter' | 'onControlEnter', key: string, inputValue?: unknown, pointer?: {
         x: number;
         y: number;
     } | null) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vortexm/vjt",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,12 +25,12 @@
   "scripts": {
     "build": "npm run build:lib && npm run build:examples && npm run build:types",
     "build:lib": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js --loader:.json=json",
-    "build:examples": "esbuild src/examples.ts --bundle --format=esm --outfile=dist/examples.js --loader:.json=json",
+    "build:examples": "esbuild examples/app/examples-app.ts --bundle --format=esm --outfile=dist/examples.js --loader:.json=json",
     "build:types": "tsc -p tsconfig.build.json",
-    "watch": "esbuild src/index.ts src/examples.ts --bundle --format=esm --outdir=dist --loader:.json=json --watch",
+    "watch": "esbuild src/index.ts examples/app/examples-app.ts --bundle --format=esm --outdir=dist --loader:.json=json --watch",
     "typecheck": "tsc -p tsconfig.json",
     "lint": "eslint \"src/**/*.ts\"",
-    "serve": "http-server . -c-1 -p 4173",
+    "serve": "node ./demo/examples-server.mjs",
     "serve:mock-backend": "node ./mock-backend/server.mjs",
     "dev": "concurrently \"npm:watch\" \"npm:serve\" \"npm:serve:mock-backend\"",
     "prepack": "npm run build"

package/vjt-styles.css

@@ -33,6 +33,33 @@ html {
   --vjt-font-heading: Georgia, "Times New Roman", serif;
 }
 
+:root {
+  background: var(--vjt-bg);
+  color: var(--vjt-text);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at top left, var(--vjt-bg-glow), transparent 28%),
+    linear-gradient(180deg, color-mix(in srgb, var(--vjt-bg) 88%, white) 0%, var(--vjt-bg) 100%);
+}
+
+#app {
+  width: 100%;
+  min-height: 100vh;
+}
+
 .vjt-static-text,
 .vjt-md-text,
 .vjt-edit,