@optiaxiom/proteus 3.0.6 → 3.1.0

package/dist/esm/assets/src/proteus-chart/{ProteusChart.css.ts.vanilla-ByPSKREp.css → ProteusChart.css.ts.vanilla-BcGBUwbD.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusChart__jmlqij1 {
     border-radius: 16px;
   }

package/dist/esm/assets/src/proteus-chart/{ProteusChartTooltipContent.css.ts.vanilla-DnR_C5ly.css → ProteusChartTooltipContent.css.ts.vanilla-BthlShlk.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusChartTooltipContent__1gsvq810 {
     min-width: 128px;
     position: absolute;

package/dist/esm/assets/src/proteus-document/{ProteusDocumentShell.css.ts.vanilla-CVOes7es.css → ProteusDocumentShell.css.ts.vanilla-BugeP59E.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusDocumentShell__vpuvfj1 {
     margin: -4px;
   }

package/dist/esm/assets/src/proteus-image-carousel/{ProteusImageCarousel.css.ts.vanilla-DXF3wHYt.css → ProteusImageCarousel.css.ts.vanilla-DhXdg25-.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusImageCarousel__1t6qej70 {
     outline: none;
     user-select: none;

package/dist/esm/assets/src/proteus-markdown/{ProteusMarkdown.css.ts.vanilla-Cjmk3X5z.css → ProteusMarkdown.css.ts.vanilla-BM9-lPyj.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusMarkdown__1ibq5ae0 > * {
     margin-bottom: 1em;
     margin-top: 0;

package/dist/esm/assets/src/proteus-question/{ProteusQuestion.css.ts.vanilla-DVFRsIPp.css → ProteusQuestion.css.ts.vanilla-1u353vmb.css}

@@ -1,5 +1,5 @@
-@layer optiaxiom._1dfr2ib;
-@layer optiaxiom._1dfr2ib {
+@layer optiaxiom.st6wia;
+@layer optiaxiom.st6wia {
   .ProteusQuestion__8f590p0 {
     outline: none;
   }

package/dist/esm/proteus-action/ProteusAction.js

@@ -33,7 +33,7 @@ function ProteusAction({ children, onClick, type = "button", ...props }) {
 * available — so the document-root event handler can apply it unambiguously.
 */
 function resolveEventPath(event, parentPath) {
-	if (event && typeof event === "object" && "action" in event && (event.action === "pushValue" || event.action === "removeValue")) {
+	if (event && typeof event === "object" && "action" in event && (event.action === "pushValue" || event.action === "removeValue" || event.action === "setValue")) {
 		const { path } = event;
 		const resolved = path === "" ? parentPath : path.startsWith("/") ? path : `${parentPath}/${path}`;
 		return {

package/dist/esm/proteus-chart/ProteusChart-css.js

@@ -1,4 +1,4 @@
-import "./../assets/src/proteus-chart/ProteusChart.css.ts.vanilla-ByPSKREp.css";
+import "./../assets/src/proteus-chart/ProteusChart.css.ts.vanilla-BcGBUwbD.css";
 import { recipe } from "@optiaxiom/react/css-runtime";
 //#region src/proteus-chart/ProteusChart.css.ts
 var chart = recipe({ base: [

package/dist/esm/proteus-chart/ProteusChartTooltipContent-css.js

@@ -1,5 +1,5 @@
 import { recipe } from "@optiaxiom/react/css-runtime";
-import "./../assets/src/proteus-chart/ProteusChartTooltipContent.css.ts.vanilla-DnR_C5ly.css";
+import "./../assets/src/proteus-chart/ProteusChartTooltipContent.css.ts.vanilla-BthlShlk.css";
 //#region src/proteus-chart/ProteusChartTooltipContent.css.ts
 var tooltip = recipe({ base: [{
 	bg: "bg.default",

package/dist/esm/proteus-document/ProteusDocumentShell-css.js

@@ -1,5 +1,5 @@
 import { recipe } from "@optiaxiom/react/css-runtime";
-import "./../assets/src/proteus-document/ProteusDocumentShell.css.ts.vanilla-CVOes7es.css";
+import "./../assets/src/proteus-document/ProteusDocumentShell.css.ts.vanilla-BugeP59E.css";
 //#region src/proteus-document/ProteusDocumentShell.css.ts
 var body = recipe({
 	base: [{

package/dist/esm/proteus-document/ProteusDocumentShell.js

@@ -3,6 +3,8 @@ import { ProteusDocumentProvider } from "./ProteusDocumentContext.js";
 import { resolveProteusValue } from "./resolveProteusValue.js";
 import { useEffectEvent } from "../hooks/useEffectEvent.js";
 import { downloadFile } from "../proteus-image/downloadFile.js";
+import { useProteusScripts } from "../proteus-script/useProteusScripts.js";
+import { isSafeUrl } from "./isSafeUrl.js";
 import { body, scrollIndicator } from "./ProteusDocumentShell-css.js";
 import { Box, Disclosure, DisclosureContent, DisclosureTrigger, Group, Heading, Text, Tooltip } from "@optiaxiom/react";
 import { useEffect, useRef, useState } from "react";
@@ -41,6 +43,73 @@ function ProteusDocumentShell({ collapsible: collapsibleProp, data = {}, default
 	const collapsible = collapsibleProp && element.appName;
 	const Trigger = collapsible ? DisclosureTrigger : Box;
 	const inline = resolveProteusValue(element.appearance, data, "", []) === "inline";
+	const onEvent = useEffectEvent(async (event) => {
+		if ("interaction" in event) return await onInteraction?.(event.interaction, event.params);
+		else if ("message" in event) await onMessage?.(event.message);
+		else if ("script" in event) return await runScript(event.script, event.params);
+		else if (event.action === "download") {
+			const urls = [];
+			if (typeof event.url === "string") urls.push(event.url);
+			else if (Array.isArray(event.url)) for (const u of event.url) {
+				if (typeof u !== "string") throw new Error("Invalid URL in download array");
+				urls.push(u);
+			}
+			else throw new Error("Invalid URL for download action");
+			for (const u of urls) if (!isSafeUrl(u)) {
+				if (strict) throw new Error(`download: unsafe URL "${u}"`);
+				return;
+			}
+			if (onDownload) await onDownload(urls);
+			else await Promise.all(urls.map((u) => downloadFile(u)));
+		} else if (event.action === "openLink") {
+			if (isSafeUrl(event.url)) window.open(event.url, "_blank", "noopener,noreferrer");
+			else if (strict) throw new Error(`openLink: unsafe URL "${String(event.url)}"`);
+		} else if (event.action === "preview") await onPreview?.(event.file);
+		else if (event.action === "pushValue") {
+			const { path, value } = event;
+			onDataChange?.((prev) => {
+				const next = structuredClone(prev);
+				const current = get(next, path);
+				if (current !== void 0 && !Array.isArray(current)) {
+					if (strict) throw new Error(`pushValue: expected array at "${path}"`);
+					return prev;
+				}
+				set(next, path, [...current ?? [], value]);
+				return next;
+			});
+		} else if (event.action === "removeValue") {
+			const { path } = event;
+			const slash = path.lastIndexOf("/");
+			const parent = slash > 0 ? path.slice(0, slash) : "";
+			const index = Number(path.slice(slash + 1));
+			if (!parent || !Number.isInteger(index)) {
+				if (strict) throw new Error(`removeValue: "${path}" is not an array index`);
+				return;
+			}
+			onDataChange?.((prev) => {
+				const next = structuredClone(prev);
+				const arr = get(next, parent);
+				if (!Array.isArray(arr)) {
+					if (strict) throw new Error(`removeValue: "${parent}" is not an array`);
+					return prev;
+				}
+				set(next, parent, arr.filter((_, i) => i !== index));
+				return next;
+			});
+		} else if (event.action === "setValue") {
+			const { path, value } = event;
+			onDataChange?.((prev) => {
+				const next = structuredClone(prev);
+				set(next, path, value);
+				return next;
+			});
+		}
+	});
+	const runScript = useProteusScripts({
+		data,
+		onEmit: onEvent,
+		scripts: element.scripts
+	});
 	return /* @__PURE__ */ jsx(ProteusDocumentProvider, {
 		data,
 		icons,
@@ -51,55 +120,7 @@ function ProteusDocumentShell({ collapsible: collapsibleProp, data = {}, default
 				return next;
 			});
 		}),
-		onEvent: useEffectEvent(async (event) => {
-			if ("interaction" in event) return await onInteraction?.(event.interaction, event.params);
-			else if ("message" in event) await onMessage?.(event.message);
-			else if (event.action === "download") {
-				const urls = [];
-				if (typeof event.url === "string") urls.push(event.url);
-				else if (Array.isArray(event.url)) for (const u of event.url) {
-					if (typeof u !== "string") throw new Error("Invalid URL in download array");
-					urls.push(u);
-				}
-				else throw new Error("Invalid URL for download action");
-				if (onDownload) await onDownload(urls);
-				else await Promise.all(urls.map((u) => downloadFile(u)));
-			} else if (event.action === "openLink") {
-				if (typeof event.url === "string") window.open(event.url, "_blank", "noopener,noreferrer");
-			} else if (event.action === "preview") await onPreview?.(event.file);
-			else if (event.action === "pushValue") {
-				const { path, value } = event;
-				onDataChange?.((prev) => {
-					const next = structuredClone(prev);
-					const current = get(next, path);
-					if (current !== void 0 && !Array.isArray(current)) {
-						if (strict) throw new Error(`pushValue: expected array at "${path}"`);
-						return prev;
-					}
-					set(next, path, [...current ?? [], value]);
-					return next;
-				});
-			} else if (event.action === "removeValue") {
-				const { path } = event;
-				const slash = path.lastIndexOf("/");
-				const parent = slash > 0 ? path.slice(0, slash) : "";
-				const index = Number(path.slice(slash + 1));
-				if (!parent || !Number.isInteger(index)) {
-					if (strict) throw new Error(`removeValue: "${path}" is not an array index`);
-					return;
-				}
-				onDataChange?.((prev) => {
-					const next = structuredClone(prev);
-					const arr = get(next, parent);
-					if (!Array.isArray(arr)) {
-						if (strict) throw new Error(`removeValue: "${parent}" is not an array`);
-						return prev;
-					}
-					set(next, parent, arr.filter((_, i) => i !== index));
-					return next;
-				});
-			}
-		}),
+		onEvent,
 		onTrack: useEffectEvent((event, properties) => {
 			onTrack?.(event, properties);
 		}),

package/dist/esm/proteus-document/isSafeUrl.js

@@ -0,0 +1,22 @@
+//#region src/proteus-document/isSafeUrl.ts
+/**
+* Whether a URL is safe to hand to `window.open` from a document-triggered
+* action (`openLink` / `download`).
+*
+* Documents — and now scripts, via `ctx.emit` — supply these URLs, so we only
+* allow navigable web schemes and reject dangerous ones like `javascript:`
+* (script injection) and `data:` (can host arbitrary HTML/JS in a new tab).
+* Relative URLs are resolved against the current document.
+*/
+function isSafeUrl(url) {
+	if (typeof url !== "string") return false;
+	let parsed;
+	try {
+		parsed = new URL(url, window.location.href);
+	} catch {
+		return false;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
+//#endregion
+export { isSafeUrl };

package/dist/esm/proteus-element/ProteusElement.js

@@ -82,7 +82,16 @@ const ProteusElement = ({ element: elementProp }) => {
 			const { filled, name, ...rest } = resolve(element);
 			const IconComp = icons?.[name];
 			if (!IconComp) {
-				if (strict) throw new Error(`Icon "${name}" not registered. Pass it via the \`icons\` prop on ProteusDocumentRenderer.`);
+				if (typeof name === "string" && /^(?:https?:\/\/|data:)/.test(name)) return /* @__PURE__ */ jsx(Box, {
+					asChild: true,
+					...rest,
+					children: /* @__PURE__ */ jsx("img", {
+						alt: "",
+						"aria-hidden": "true",
+						src: name
+					})
+				});
+				if (strict) throw new Error(`Icon "${name}" not registered and not a URL. Pass it via the \`icons\` prop on ProteusDocumentRenderer, or use an http(s):// or data: URL.`);
 				return null;
 			}
 			return /* @__PURE__ */ jsx(Box, {

package/dist/esm/proteus-image-carousel/ProteusImageCarousel-css.js

@@ -1,5 +1,5 @@
 import { recipe } from "@optiaxiom/react/css-runtime";
-import "./../assets/src/proteus-image-carousel/ProteusImageCarousel.css.ts.vanilla-DXF3wHYt.css";
+import "./../assets/src/proteus-image-carousel/ProteusImageCarousel.css.ts.vanilla-DhXdg25-.css";
 //#region src/proteus-image-carousel/ProteusImageCarousel.css.ts
 var carousel = recipe({ base: [{
 	flexDirection: "column",

package/dist/esm/proteus-markdown/ProteusMarkdown-css.js

@@ -1,5 +1,5 @@
 import { recipe } from "@optiaxiom/react/css-runtime";
-import "./../assets/src/proteus-markdown/ProteusMarkdown.css.ts.vanilla-Cjmk3X5z.css";
+import "./../assets/src/proteus-markdown/ProteusMarkdown.css.ts.vanilla-BM9-lPyj.css";
 //#region src/proteus-markdown/ProteusMarkdown.css.ts
 var code = recipe({ base: [{
 	bg: "bg.secondary",

package/dist/esm/proteus-question/ProteusQuestion-css.js

@@ -1,5 +1,5 @@
 import { recipe } from "@optiaxiom/react/css-runtime";
-import "./../assets/src/proteus-question/ProteusQuestion.css.ts.vanilla-DVFRsIPp.css";
+import "./../assets/src/proteus-question/ProteusQuestion.css.ts.vanilla-1u353vmb.css";
 //#region src/proteus-question/ProteusQuestion.css.ts
 var addon = recipe({
 	base: [{

package/dist/esm/proteus-script/useProteusScripts.js

@@ -0,0 +1,164 @@
+"use client";
+"use client";
+import { useEffectEvent } from "../hooks/useEffectEvent.js";
+import { WORKER_SCRIPT } from "./workerScript.js";
+import { useEffect, useRef } from "react";
+import { get } from "jsonpointer";
+//#region src/proteus-script/useProteusScripts.ts
+/**
+* How long a single handler run may take before we give up on it. A script
+* with an infinite loop cannot block the main thread (it runs in the worker),
+* but its `invoke` promise would otherwise never resolve — wedging the
+* triggering control in a `loading` state forever. On timeout we resolve the
+* run to `undefined` (the fail-silent default) and terminate the worker so the
+* runaway handler stops burning a core; the next run lazily respawns it.
+*/
+const INVOKE_TIMEOUT_MS = 5e3;
+/**
+* Spins up a single sandbox Web Worker for the document's `scripts` and returns
+* a `runScript(handler, params)` that invokes a named handler inside it. Events
+* a handler or watcher emits are routed back through `onEmit` (the shell
+* dispatcher) and their results returned to the worker, so `ctx.emit`
+* round-trips work.
+*
+* Watchers (`watch(path, fn)` in a script) are driven from here: the worker
+* reports its watched paths after `init`, and this hook edge-detects each path
+* against `data` on every change, posting `runWatcher` when the value there
+* changes. A watcher does NOT re-fire on data changes caused by a script's own
+* `emit` (see `emitDepthRef`) — watchers observe user/host state changes, which
+* both prevents emit→watcher→emit loops and gives a predictable "reacts to what
+* the user did" semantic.
+*
+* Returns a no-op runner when the document ships no scripts — the worker is
+* spawned eagerly when scripts exist (watchers can fire before any interaction).
+*/
+function useProteusScripts({ data, onEmit, scripts }) {
+	const dataRef = useRef(data);
+	dataRef.current = data;
+	const emit = useEffectEvent(onEmit);
+	const hasScripts = !!scripts && Object.keys(scripts).length > 0;
+	const pending = useRef(/* @__PURE__ */ new Map()).current;
+	const nextId = useRef(1);
+	const workerRef = useRef(null);
+	const watchedPaths = useRef([]);
+	const lastEval = useRef([]);
+	const emitDepth = useRef(0);
+	/** Snapshot every watched path from `data` into `lastEval` without firing. */
+	const seedWatchers = useEffectEvent((data) => {
+		lastEval.current = watchedPaths.current.map((path) => JSON.stringify(getByPointer(data, path) ?? null));
+	});
+	/** Resolve a pending run (if still pending) and clear its timeout. */
+	const settle = useEffectEvent((invokeId, result) => {
+		const entry = pending.get(invokeId);
+		if (!entry) return;
+		clearTimeout(entry.timer);
+		pending.delete(invokeId);
+		entry.resolve(result);
+	});
+	const spawnWorker = useEffectEvent(() => {
+		const url = URL.createObjectURL(new Blob([WORKER_SCRIPT], { type: "text/javascript" }));
+		const instance = new Worker(url);
+		URL.revokeObjectURL(url);
+		instance.postMessage({
+			scripts,
+			type: "init"
+		});
+		instance.addEventListener("message", async (e) => {
+			const msg = e.data;
+			if (msg.type === "emit") {
+				emitDepth.current += 1;
+				let result;
+				try {
+					result = await emit(msg.event);
+				} finally {
+					emitDepth.current -= 1;
+				}
+				instance.postMessage({
+					emitId: msg.emitId,
+					result,
+					type: "emitResult"
+				});
+			} else if (msg.type === "invokeResult") settle(msg.invokeId, msg.result);
+			else if (msg.type === "watchers") {
+				watchedPaths.current = msg.paths;
+				seedWatchers(dataRef.current);
+			}
+		});
+		return instance;
+	});
+	/** Ensure the worker exists, spawning it on first need. */
+	const ensureWorker = useEffectEvent(() => {
+		if (!workerRef.current) workerRef.current = spawnWorker();
+		return workerRef.current;
+	});
+	/** Tear down the current worker and abandon every in-flight run. */
+	const teardown = useEffectEvent(() => {
+		workerRef.current?.terminate();
+		workerRef.current = null;
+		watchedPaths.current = [];
+		lastEval.current = [];
+		for (const [invokeId] of pending) settle(invokeId, void 0);
+	});
+	useEffect(() => {
+		teardown();
+		if (hasScripts) ensureWorker();
+		return teardown;
+	}, [scripts, hasScripts]);
+	useEffect(() => {
+		const worker = workerRef.current;
+		if (!worker || watchedPaths.current.length === 0) return;
+		if (emitDepth.current > 0) {
+			seedWatchers(data);
+			return;
+		}
+		watchedPaths.current.forEach((path, watchId) => {
+			const current = getByPointer(data, path) ?? null;
+			const serialized = JSON.stringify(current);
+			const prevSerialized = lastEval.current[watchId];
+			if (serialized !== prevSerialized) {
+				lastEval.current[watchId] = serialized;
+				const previous = prevSerialized === void 0 ? void 0 : JSON.parse(prevSerialized);
+				worker.postMessage({
+					current,
+					data,
+					previous,
+					type: "runWatcher",
+					watchId
+				});
+			}
+		});
+	}, [data]);
+	return useEffectEvent((handler, params) => {
+		if (!hasScripts) return Promise.resolve(void 0);
+		const worker = ensureWorker();
+		const invokeId = nextId.current++;
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				settle(invokeId, void 0);
+				teardown();
+			}, INVOKE_TIMEOUT_MS);
+			pending.set(invokeId, {
+				resolve,
+				timer
+			});
+			worker.postMessage({
+				data: dataRef.current,
+				handler,
+				invokeId,
+				params: params ?? {},
+				type: "invoke"
+			});
+		});
+	});
+}
+/** Read a JSON-pointer slice, matching the worker's getByPointer semantics. */
+function getByPointer(data, path) {
+	if (!path || path === "/") return data;
+	try {
+		return get(data, path);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { useProteusScripts };

package/dist/esm/proteus-script/workerScript.js

@@ -0,0 +1,149 @@
+//#region src/proteus-script/workerScript.ts
+/**
+* Source of the sandbox Web Worker, authored as a self-contained string so it
+* can be turned into a Blob URL and run without a separate chunk or same-origin
+* file (mirrors how `ProteusBridge` inlines its shim script).
+*
+* The worker has no DOM, no `window.parent`, and communicates only via
+* structured-clone `postMessage` — a strictly tighter sandbox than an iframe.
+* A handler's sole capability is `ctx.emit`, which posts an existing Proteus
+* event back to the host to be re-dispatched. See `protocol.ts` for the message
+* shapes and `ScriptContext`.
+*
+* INVARIANT: script isolation depends on this worker holding no privileged
+* globals. We `new Function(...)` the document's source below, which is only
+* safe because there is nothing sensitive in scope. Do NOT add `importScripts`,
+* pass host capabilities in via `postMessage`, or expose any API to handler
+* scope — doing so turns `new Function` into an escape hatch.
+*/
+const WORKER_SCRIPT = `
+"use strict";
+
+const handlers = new Map();
+const watchers = [];
+const pendingEmits = new Map();
+let nextEmitId = 1;
+
+// Minimal JSON-pointer getter (same semantics as the host's getProteusValue).
+function getByPointer(data, path) {
+  if (!path || path === "/") return data;
+  const parts = path.replace(/^\\//, "").split("/");
+  let current = data;
+  for (const raw of parts) {
+    if (current == null) return undefined;
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    current = current[key];
+  }
+  return current;
+}
+
+function register(name, fn) {
+  if (typeof name !== "string" || typeof fn !== "function") {
+    throw new Error("register(name, fn) requires a string name and a function");
+  }
+  handlers.set(name, fn);
+}
+
+function watch(path, fn) {
+  if (typeof path !== "string" || typeof fn !== "function") {
+    throw new Error("watch(path, fn) requires a string path and a function");
+  }
+  watchers.push({ fn, path });
+}
+
+// Evaluate one module's source in a scope that exposes \`register\` and \`watch\`.
+// Handlers are keyed by "moduleName:handlerName" via a per-module register
+// wrapper; watchers are collected globally (order = watch id).
+function loadModule(moduleName, source) {
+  const scopedRegister = (name, fn) => register(moduleName + ":" + name, fn);
+  // eslint-disable-next-line no-new-func
+  const factory = new Function("register", "watch", source);
+  factory(scopedRegister, watch);
+}
+
+function emit(event) {
+  const emitId = nextEmitId++;
+  return new Promise((resolve) => {
+    pendingEmits.set(emitId, resolve);
+    self.postMessage({ emitId, event, type: "emit" });
+  });
+}
+
+self.onmessage = async (e) => {
+  const msg = e.data;
+
+  if (msg.type === "init") {
+    for (const [moduleName, source] of Object.entries(msg.scripts ?? {})) {
+      try {
+        loadModule(moduleName, source);
+      } catch (err) {
+        // A broken module leaves its handlers unregistered; invokes for them
+        // surface a "not found" error at call time.
+      }
+    }
+    // Report watched paths so the host can edge-detect and drive runWatcher.
+    self.postMessage({ paths: watchers.map((w) => w.path), type: "watchers" });
+    return;
+  }
+
+  if (msg.type === "emitResult") {
+    const resolve = pendingEmits.get(msg.emitId);
+    if (resolve) {
+      pendingEmits.delete(msg.emitId);
+      resolve(msg.result);
+    }
+    return;
+  }
+
+  if (msg.type === "invoke") {
+    const { data, handler, invokeId, params } = msg;
+    const fn = handlers.get(handler);
+    if (!fn) {
+      self.postMessage({
+        error: 'No script handler registered for "' + handler + '"',
+        invokeId,
+        result: undefined,
+        type: "invokeResult",
+      });
+      return;
+    }
+    const ctx = {
+      emit,
+      getValue: (path) => getByPointer(data, path),
+    };
+    try {
+      const result = await fn(ctx, params ?? {});
+      self.postMessage({ invokeId, result, type: "invokeResult" });
+    } catch (err) {
+      self.postMessage({
+        error: err && err.message ? String(err.message) : String(err),
+        invokeId,
+        result: undefined,
+        type: "invokeResult",
+      });
+    }
+    return;
+  }
+
+  if (msg.type === "runWatcher") {
+    const { current, data, previous, watchId } = msg;
+    const watcher = watchers[watchId];
+    if (!watcher) {
+      return;
+    }
+    const ctx = {
+      emit,
+      getValue: (path) => getByPointer(data, path),
+    };
+    try {
+      // Fire-and-forget: watchers return nothing to any caller. Errors are
+      // swallowed to match the fail-silent default of the other ops.
+      await watcher.fn(ctx, current, previous);
+    } catch (err) {
+      // Intentionally ignored.
+    }
+  }
+};
+`;
+//#endregion
+export { WORKER_SCRIPT };

package/dist/esm/schema/public-schema.js

@@ -1210,6 +1210,32 @@ var public_schema_default = {
 						"gap": "16"
 					}],
 					"title": "Create Test Plan"
+				},
+				{
+					"$type": "Document",
+					"actions": [{
+						"$type": "Action",
+						"appearance": "primary",
+						"children": "Greet",
+						"onClick": {
+							"params": { "name": {
+								"$type": "Value",
+								"path": "/name"
+							} },
+							"script": "main:greet"
+						}
+					}],
+					"appName": "Opal",
+					"body": [{
+						"$type": "Field",
+						"children": {
+							"$type": "Input",
+							"name": "name"
+						},
+						"label": "Your name"
+					}],
+					"scripts": { "main": "register('greet', (ctx) => ctx.emit({ message: `Hello, ${ctx.params.name}!` }))" },
+					"title": "Scripted Greeting"
 				}
 			],
 			"properties": {
@@ -1252,6 +1278,11 @@ var public_schema_default = {
 					"type": "object"
 				},
 				"meta": { "description": "Additional metadata not directly consumed by Proteus. Use this to pass along any extra data." },
+				"scripts": {
+					"additionalProperties": { "type": "string" },
+					"description": "Map of module name to JavaScript source. Each module runs in a sandboxed Web Worker and registers named handlers via `register(name, fn)`. Trigger a handler from any event source with `{ script: 'module:handler', params }`; handlers receive a single `ctx` ({ emit, getValue, params }) and can only affect the document by emitting the existing Proteus events through `ctx.emit`.",
+					"type": "object"
+				},
 				"subtitle": {
 					"$ref": "#/definitions/ProteusNode",
 					"description": "A brief description or tagline that provides additional context about the Proteus document's purpose."
@@ -1338,6 +1369,23 @@ var public_schema_default = {
 					"required": ["interaction"],
 					"type": "object"
 				},
+				{
+					"additionalProperties": false,
+					"description": "Scripted action - runs a named handler from the document's `scripts` map in a sandboxed Web Worker. The handler can emit the other Proteus events via `ctx.emit`.",
+					"properties": {
+						"params": {
+							"additionalProperties": {},
+							"description": "Parameters passed to the handler as `ctx.params`. Values can be ProteusExpressions that resolve at call time.",
+							"type": "object"
+						},
+						"script": {
+							"description": "Handler to run, addressed as `module:handler` (the module key comes from the document's `scripts` map).",
+							"type": "string"
+						}
+					},
+					"required": ["script"],
+					"type": "object"
+				},
 				{
 					"additionalProperties": false,
 					"description": "Client-side message action",
@@ -1441,6 +1489,24 @@ var public_schema_default = {
 					},
 					"required": ["action", "path"],
 					"type": "object"
+				},
+				{
+					"additionalProperties": false,
+					"description": "Runtime data operation - writes `value` at `path` in form data, replacing any existing value (e.g. `/tags/2`). Path resolves like `Value` (absolute `/x`, relative to current parentPath, or `''` for parentPath itself).",
+					"properties": {
+						"action": {
+							"const": "setValue",
+							"description": "The action type",
+							"type": "string"
+						},
+						"path": {
+							"description": "JSON pointer path to write to",
+							"type": "string"
+						},
+						"value": { "description": "The value to write; primitives or objects" }
+					},
+					"required": ["action", "path"],
+					"type": "object"
 				}
 			],
 			"description": "Handler for user interactions - a server-side interaction call, client-side message, or client-side component action"

package/dist/esm/schema/runtime-schema.js

@@ -1197,6 +1197,32 @@ var definitions = {
 					"gap": "16"
 				}],
 				"title": "Create Test Plan"
+			},
+			{
+				"$type": "Document",
+				"actions": [{
+					"$type": "Action",
+					"appearance": "primary",
+					"children": "Greet",
+					"onClick": {
+						"params": { "name": {
+							"$type": "Value",
+							"path": "/name"
+						} },
+						"script": "main:greet"
+					}
+				}],
+				"appName": "Opal",
+				"body": [{
+					"$type": "Field",
+					"children": {
+						"$type": "Input",
+						"name": "name"
+					},
+					"label": "Your name"
+				}],
+				"scripts": { "main": "register('greet', (ctx) => ctx.emit({ message: `Hello, ${ctx.params.name}!` }))" },
+				"title": "Scripted Greeting"
 			}
 		],
 		"properties": {
@@ -1239,6 +1265,11 @@ var definitions = {
 				"type": "object"
 			},
 			"meta": { "description": "Additional metadata not directly consumed by Proteus. Use this to pass along any extra data." },
+			"scripts": {
+				"additionalProperties": { "type": "string" },
+				"description": "Map of module name to JavaScript source. Each module runs in a sandboxed Web Worker and registers named handlers via `register(name, fn)`. Trigger a handler from any event source with `{ script: 'module:handler', params }`; handlers receive a single `ctx` ({ emit, getValue, params }) and can only affect the document by emitting the existing Proteus events through `ctx.emit`.",
+				"type": "object"
+			},
 			"subtitle": {
 				"$ref": "#/definitions/ProteusNode",
 				"description": "A brief description or tagline that provides additional context about the Proteus document's purpose."
@@ -1324,6 +1355,22 @@ var definitions = {
 				"required": ["interaction"],
 				"type": "object"
 			},
+			{
+				"description": "Scripted action - runs a named handler from the document's `scripts` map in a sandboxed Web Worker. The handler can emit the other Proteus events via `ctx.emit`.",
+				"properties": {
+					"params": {
+						"additionalProperties": {},
+						"description": "Parameters passed to the handler as `ctx.params`. Values can be ProteusExpressions that resolve at call time.",
+						"type": "object"
+					},
+					"script": {
+						"description": "Handler to run, addressed as `module:handler` (the module key comes from the document's `scripts` map).",
+						"type": "string"
+					}
+				},
+				"required": ["script"],
+				"type": "object"
+			},
 			{
 				"description": "Client-side message action",
 				"properties": { "message": {
@@ -1421,6 +1468,23 @@ var definitions = {
 				},
 				"required": ["action", "path"],
 				"type": "object"
+			},
+			{
+				"description": "Runtime data operation - writes `value` at `path` in form data, replacing any existing value (e.g. `/tags/2`). Path resolves like `Value` (absolute `/x`, relative to current parentPath, or `''` for parentPath itself).",
+				"properties": {
+					"action": {
+						"const": "setValue",
+						"description": "The action type",
+						"type": "string"
+					},
+					"path": {
+						"description": "JSON pointer path to write to",
+						"type": "string"
+					},
+					"value": { "description": "The value to write; primitives or objects" }
+				},
+				"required": ["action", "path"],
+				"type": "object"
 			}
 		],
 		"description": "Handler for user interactions - a server-side interaction call, client-side message, or client-side component action"

package/dist/index.d.ts

@@ -432,6 +432,8 @@ type ProteusDocumentShellProps = Pick<ComponentPropsWithoutRef<typeof Disclosure
   element: ProteusDocument$2;
   /**
    * Map of icon name to React component. Referenced by `{ $type: "Icon", name }` elements.
+   * If `name` is not in the map but starts with `http(s)://` or `data:`, it is
+   * rendered as `<img src={name}>` instead.
    */
   icons?: ProteusIconMap;
   /**
@@ -492,6 +494,7 @@ type ProteusDocument$2 = {
   blocking?: boolean;
   body: ReactNode;
   compact?: boolean;
+  scripts?: Record<string, string>;
   subtitle?: ReactNode;
   title?: ReactNode;
   titleIcon?: string;
@@ -540,11 +543,18 @@ type ProteusEventHandler = {
 } | {
   action: "removeValue";
   path: string;
+} | {
+  action: "setValue";
+  path: string;
+  value?: unknown;
 } | {
   interaction: string;
   params?: Record<string, unknown>;
 } | {
   message: string | StructuredMessage;
+} | {
+  params?: Record<string, unknown>;
+  script: string;
 };
 type ProteusPreviewFile = {
   extension: string;
@@ -619,6 +629,7 @@ type ProteusDocument = {
   blocking?: boolean;
   body: unknown;
   compact?: boolean;
+  scripts?: Record<string, string>;
   subtitle?: unknown;
   title?: unknown;
   titleIcon?: string;

package/package.json

@@ -7,7 +7,7 @@
     "url": "git+https://github.com/optimizely-axiom/optiaxiom.git"
   },
   "type": "module",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "files": [
     "dist/**",
     "LICENSE"
@@ -42,7 +42,7 @@
     "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",
     "@optiaxiom/icons": "^1.3.0",
-    "@optiaxiom/react": "^3.1.2"
+    "@optiaxiom/react": "^3.1.4"
   },
   "devDependencies": {
     "@emotion/hash": "^0.9.2",