onbuzz 4.2.0 → 4.4.0

package/src/modules/widget/__tests__/runtime.test.js

@@ -0,0 +1,401 @@
+/**
+ * Runtime bundle smoke — we can't execute the bundle in node (it wants
+ * window/document), but we CAN pin the surface: named hooks the iframe
+ * page relies on must be present in the string, or jsx widgets silently
+ * break. This catches accidental renames + truncations.
+ *
+ * Also parses the string as JavaScript to catch syntax errors — a typo
+ * in the bundle currently has no compile-time check.
+ */
+import { describe, test, expect } from '@jest/globals';
+import vm from 'node:vm';
+import { WIDGET_RUNTIME } from '../runtime/bundle.js';
+
+describe('WIDGET_RUNTIME — surface + parseability', () => {
+  test('is a non-trivial string', () => {
+    expect(typeof WIDGET_RUNTIME).toBe('string');
+    expect(WIDGET_RUNTIME.length).toBeGreaterThan(1000);
+  });
+
+  test('parses as valid JavaScript', () => {
+    // new vm.Script() throws on parse errors. It does NOT execute.
+    expect(() => new vm.Script(WIDGET_RUNTIME)).not.toThrow();
+  });
+
+  test('exposes the public SDK surface on window.loxia', () => {
+    // Simple string assertions — the bundle IIFE writes these.
+    expect(WIDGET_RUNTIME).toMatch(/window\.loxia\s*=/);
+    for (const method of ['h', 'html', 'render', 'sendEvent', 'onUpdate', 'requestHeight']) {
+      expect(WIDGET_RUNTIME).toMatch(new RegExp(`\\b${method}\\b`));
+    }
+  });
+
+  test('exposes primitives catalog', () => {
+    for (const prim of ['LoxiaCard', 'LoxiaButton', 'LoxiaInput', 'LoxiaText', 'LoxiaMetric', 'LoxiaRow', 'LoxiaCol']) {
+      expect(WIDGET_RUNTIME).toMatch(new RegExp(`\\b${prim}\\b`));
+    }
+  });
+
+  test('does not hit the network from inside the sandbox', () => {
+    // No fetch/XHR references — CSP is meant to block them, but belt-and-braces:
+    // the runtime itself shouldn't invoke them.
+    expect(WIDGET_RUNTIME).not.toMatch(/\bfetch\s*\(/);
+    expect(WIDGET_RUNTIME).not.toMatch(/XMLHttpRequest/);
+    expect(WIDGET_RUNTIME).not.toMatch(/WebSocket/);
+  });
+
+  test('uses postMessage for parent communication (authenticated via source at receiver)', () => {
+    expect(WIDGET_RUNTIME).toMatch(/postMessage/);
+    expect(WIDGET_RUNTIME).toMatch(/__loxia/);
+  });
+
+  test('runs inside an IIFE (does not leak top-level identifiers)', () => {
+    // Strip leading /* ... */ comment (bundle header), then check IIFE shape.
+    const stripped = WIDGET_RUNTIME.replace(/^\s*\/\*[\s\S]*?\*\/\s*/, '').trim();
+    expect(stripped).toMatch(/^\(function\s*\(/);
+    expect(stripped).toMatch(/\}\)\(\);?\s*$/);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Hook integration — agents reflexively reach for useState; we support it
+// ────────────────────────────────────────────────────────────────────────
+
+describe('runtime hooks — integration via jsdom', () => {
+  let dom, window;
+
+  beforeEach(async () => {
+    const { JSDOM } = await import('jsdom');
+    dom = new JSDOM('<div id="root"></div>', { runScripts: 'outside-only', pretendToBeVisual: true });
+    window = dom.window;
+    window.__loxiaWidgetId = 'w';
+    window.__loxiaInitialProps = {};
+    new window.Function(WIDGET_RUNTIME).call(window);
+  });
+
+  test('useState is exported three ways (bare, on h, on loxia)', () => {
+    expect(typeof window.useState).toBe('function');
+    expect(typeof window.h.useState).toBe('function');
+    expect(typeof window.loxia.useState).toBe('function');
+  });
+
+  test('`const { useState } = h` destructure pattern works (this is the one agents write)', () => {
+    const { useState, useEffect, useMemo, useCallback, useRef } = window.h;
+    expect(typeof useState).toBe('function');
+    expect(typeof useEffect).toBe('function');
+    expect(typeof useMemo).toBe('function');
+    expect(typeof useCallback).toBe('function');
+    expect(typeof useRef).toBe('function');
+  });
+
+  // REGRESSION: agents trained on online htm/preact/React tutorials reach
+  // for varied namespace names: `htmPreact`, `preact`, `React`, `htm`, etc.
+  // Rather than reject those as "undefined," we alias every known name
+  // to the same bundle so the destructure pattern works however the
+  // agent decided to name it.
+  // Every known namespace alias (htmPreact / preactHooks / React / ...)
+  // must expose the full hooks surface — agents reach for any of them
+  // based on whatever snippet their training data surfaced.
+  test.each([
+    ['htmPreact'],     ['htm_preact'], ['preactHtm'],
+    ['htm'],           ['Htm'],
+    ['preact'],        ['Preact'],     ['preactjs'],
+    ['preactHooks'],   ['PreactHooks'], ['preact_hooks'],
+    ['hooks'],         ['Hooks'],
+    ['React'],         ['react'],
+    ['reactHooks'],    ['ReactHooks'],  ['react_hooks'],
+    ['preactStandalone'], ['preact_standalone'],
+  ])('namespace alias window.%s exposes { useState, useEffect, useMemo, useCallback, useRef, h, html }', (name) => {
+    const ns = window[name];
+    expect(ns).toBeDefined();
+    expect(typeof ns.useState).toBe('function');
+    expect(typeof ns.useEffect).toBe('function');
+    expect(typeof ns.useMemo).toBe('function');
+    expect(typeof ns.useCallback).toBe('function');
+    expect(typeof ns.useRef).toBe('function');
+    expect(typeof ns.h).toBe('function');
+    expect(typeof ns.html).toBe('function');
+    // createElement is an alias for h (React naming)
+    expect(ns.createElement).toBe(ns.h);
+  });
+
+  test('namespace supports `import X from "preact"` shape via .default self-reference', () => {
+    // Some transpiled snippets import the namespace's default: default
+    // points back at the namespace itself so X.useState still works.
+    expect(window.preact.default.useState).toBe(window.preact.useState);
+  });
+
+  test('namespace Proxy: unknown hooks throw a SPECIFIC "not implemented" error', () => {
+    // If an agent reaches for useLayoutEffect / useContext / forwardRef /
+    // etc., the Proxy returns a throwing stub so the error text names
+    // the missing API instead of a generic "undefined is not a function".
+    const notImplemented = [
+      'useLayoutEffect', 'useContext', 'forwardRef',
+      'memo', 'createContext', 'Suspense',
+    ];
+    // useReducer used to be in this list; it\'s implemented now. Assert
+    // the opposite so regressions trigger here.
+    expect(typeof window.preact.useReducer).toBe('function');
+    expect(() => window.preact.useReducer((s) => s, 0)).not.toThrow();
+    for (const key of notImplemented) {
+      const fn = window.preact[key];
+      expect(typeof fn).toBe('function');
+      expect(() => fn()).toThrow(new RegExp(`'${key}' is not implemented`));
+      expect(() => fn()).toThrow(/Supported hooks:/);
+    }
+  });
+
+  test('class components throw a NAMED error (Component / PureComponent)', () => {
+    // REGRESSION: prior behaviour was `Component` returning undefined,
+    // which gave "Class extends value undefined is not a constructor" —
+    // generic and unhelpful. Now the error names the class + the
+    // rewrite path.
+    for (const className of ['Component', 'PureComponent']) {
+      const Cls = window.React[className];
+      expect(typeof Cls).toBe('function');
+      // Direct call path (e.g. Component())
+      expect(() => Cls()).toThrow(new RegExp(`'${className}' is not implemented`));
+      // Also available as a bare global
+      expect(window[className]).toBeDefined();
+      expect(() => window[className]()).toThrow(new RegExp(`'${className}' is not implemented`));
+    }
+  });
+
+  test('bare-global not-implemented names throw named errors too (not just via namespace)', () => {
+    // Agents that reach for bare `useContext(x)` without a namespace also
+    // get the named error, not a generic ReferenceError.
+    expect(typeof window.useContext).toBe('function');
+    expect(() => window.useContext({})).toThrow(/'useContext' is not implemented/);
+    expect(typeof window.forwardRef).toBe('function');
+    expect(() => window.forwardRef(() => {})).toThrow(/'forwardRef' is not implemented/);
+  });
+
+  test('CONSISTENCY: every not-implemented name from the runtime is mentioned in the tool description', async () => {
+    // The tool description and the Proxy\'s not-implemented sets are
+    // independent — they can drift. Pin them: every name the runtime
+    // throws for MUST appear in the agent\'s context, or the agent gets
+    // a clear error without any guidance on how to avoid it next time.
+    const { WidgetTool } = await import('../widgetTool.js');
+    const desc = new WidgetTool().getDescription();
+
+    // The runtime bundle is a string — extract the literal names from
+    // the Sets via grepping the source (source of truth).
+    const { WIDGET_RUNTIME } = await import('../runtime/bundle.js');
+    const classesMatch = WIDGET_RUNTIME.match(/_notImplementedClasses\s*=\s*new Set\(\[([^\]]+)\]\)/);
+    const fnsMatch     = WIDGET_RUNTIME.match(/_notImplementedFns\s*=\s*new Set\(\[([^\]]+)\]\)/);
+    expect(classesMatch).toBeTruthy();
+    expect(fnsMatch).toBeTruthy();
+    const extract = (m) => {
+      // Strip `// ...` comments first — apostrophes inside comments (e.g.
+      // "don\'t implement") otherwise break the quoted-string regex.
+      const stripped = m[1].replace(/\/\/.*$/gm, '');
+      return (stripped.match(/'[^']+'/g) || []).map(s => s.slice(1, -1));
+    };
+    const allNames = [...new Set([...extract(classesMatch), ...extract(fnsMatch)])];
+    expect(allNames.length).toBeGreaterThan(10); // sanity
+
+    const missing = allNames.filter(n => !desc.includes(n));
+    expect(missing).toEqual([]);
+  });
+
+  test('namespace Proxy: truly-unknown keys (not in not-implemented list) return undefined', () => {
+    expect(window.preact.somethingCompletelyMadeUp).toBeUndefined();
+  });
+
+  test('window.htm exposes { html } (htm library convention)', () => {
+    expect(typeof window.htm).toBe('object');
+    expect(typeof window.htm.html).toBe('function');
+    expect(window.htm.html).toBe(window.html);
+  });
+
+  test('window.ReactDOM.render exists (even if minimal) so ReactDOM.render(vnode, el) doesn\'t ReferenceError', () => {
+    expect(typeof window.ReactDOM).toBe('object');
+    expect(typeof window.ReactDOM.render).toBe('function');
+  });
+
+  test('window.ReactDOM.createRoot(x).render(vnode) works (React 18 idiom)', () => {
+    const root = window.ReactDOM.createRoot(window.document.body);
+    expect(typeof root.render).toBe('function');
+    expect(typeof root.unmount).toBe('function');
+    // Just confirm the shape — actual render is the same path as ReactDOM.render.
+    expect(() => root.render(window.h('div'))).not.toThrow();
+  });
+
+  test('agent code using "const { useState } = preactHooks" (the pattern that triggered the Proxy expansion) works', () => {
+    const userCode = [
+      'const { useState } = preactHooks;',
+      'return function() {',
+      '  const [n, setN] = useState(10);',
+      '  return h("button", { onClick: () => setN(n + 1), id: "ph" }, "n=" + n);',
+      '};',
+    ].join('\n');
+    const fn = new window.Function(userCode);
+    window.loxia.render(fn, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('n=10');
+    window.document.getElementById('ph').click();
+    expect(root.textContent).toContain('n=11');
+  });
+
+  test('agent code using "const { useState } = htmPreact" (the pattern that triggered this fix) works', () => {
+    // Verbatim pattern from the failed tool invocation that prompted the alias.
+    const userCode = [
+      'const { useState, useCallback } = htmPreact;',
+      'const App = () => {',
+      '  const [n, setN] = useState(3);',
+      '  const inc = useCallback(() => setN(n + 1), [n]);',
+      '  return h("button", { onClick: inc, id: "htmp" }, "n=" + n);',
+      '};',
+      'return App();',
+    ].join('\n');
+    const fn = new window.Function(userCode);
+    window.loxia.render(fn, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('n=3');
+    window.document.getElementById('htmp').click();
+    expect(root.textContent).toContain('n=4');
+  });
+
+  test('useState drives a real click-to-increment counter', () => {
+    function App() {
+      const [count, setCount] = window.useState(0);
+      return window.h('div', null,
+        window.h('span', null, 'c=' + count),
+        window.h('button', { onClick: () => setCount(count + 1), id: 'btn' }, '+'),
+      );
+    }
+    window.loxia.render(App, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('c=0');
+    // Re-query button each click — renderToRoot replaces the DOM subtree.
+    window.document.getElementById('btn').click();
+    expect(root.textContent).toContain('c=1');
+    window.document.getElementById('btn').click();
+    expect(root.textContent).toContain('c=2');
+  });
+
+  test('useMemo caches until deps change', () => {
+    let computeCount = 0;
+    function App() {
+      const [n, setN] = window.useState(1);
+      const squared = window.useMemo(() => { computeCount++; return n * n; }, [n]);
+      return window.h('div', null,
+        window.h('span', null, 'sq=' + squared),
+        window.h('button', { onClick: () => setN(n + 1), id: 'b' }, '+'),
+      );
+    }
+    window.loxia.render(App, {});
+    expect(computeCount).toBe(1);
+    // Clicking changes n, which invalidates the memo
+    window.document.getElementById('b').click();
+    expect(computeCount).toBe(2);
+    expect(window.document.getElementById('root').textContent).toContain('sq=4');
+  });
+
+  test('functional setState (setCount(c => c + 1)) works', () => {
+    function App() {
+      const [n, setN] = window.useState(10);
+      return window.h('button', { onClick: () => setN(c => c + 5), id: 'b' }, 'n=' + n);
+    }
+    window.loxia.render(App, {});
+    window.document.getElementById('b').click();
+    expect(window.document.getElementById('root').textContent).toContain('n=15');
+  });
+
+  test('useReducer dispatches reducer and re-renders with new state', () => {
+    function App() {
+      const [state, dispatch] = window.useReducer((s, a) => {
+        if (a.type === 'inc') return { n: s.n + 1 };
+        if (a.type === 'dec') return { n: s.n - 1 };
+        return s;
+      }, { n: 10 });
+      return window.h('div', null,
+        window.h('span', null, 'n=' + state.n),
+        window.h('button', { id: 'inc', onClick: () => dispatch({ type: 'inc' }) }, '+'),
+        window.h('button', { id: 'dec', onClick: () => dispatch({ type: 'dec' }) }, '-'),
+      );
+    }
+    window.loxia.render(App, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('n=10');
+    window.document.getElementById('inc').click();
+    expect(root.textContent).toContain('n=11');
+    window.document.getElementById('dec').click();
+    window.document.getElementById('dec').click();
+    expect(root.textContent).toContain('n=9');
+  });
+
+  test('useReducer supports the (reducer, init, initFn) lazy-init form', () => {
+    function App() {
+      const [n, dispatch] = window.useReducer((s) => s + 1, 5, x => x * 10);
+      return window.h('button', { id: 'r', onClick: () => dispatch() }, 'v=' + n);
+    }
+    window.loxia.render(App, {});
+    // init(5) = 50 → lazy init applied once
+    expect(window.document.getElementById('root').textContent).toContain('v=50');
+    window.document.getElementById('r').click();
+    expect(window.document.getElementById('root').textContent).toContain('v=51');
+  });
+
+  test('identical setState value does not trigger re-render', () => {
+    let renderCount = 0;
+    function App() {
+      renderCount++;
+      const [v, setV] = window.useState('x');
+      return window.h('button', { onClick: () => setV('x'), id: 'b' }, 'v=' + v);
+    }
+    window.loxia.render(App, {});
+    expect(renderCount).toBe(1);
+    window.document.getElementById('b').click();
+    expect(renderCount).toBe(1); // unchanged — no re-render
+  });
+
+  // REGRESSION: when loxia.render is given a factory function (one that
+  // returns another function — the pattern `return function App(){...}`),
+  // it must promote the inner function to be the real component so hooks
+  // run in the right scope. Previously, the outer factory was treated as
+  // the component, hooks were called in its scope, state was captured at
+  // the first call, and the inner function was never invoked.
+  test('factory-style agent code: component returning a function is promoted + hooks work', () => {
+    function Factory() {
+      // This is the "outer wrapper" — it does NOT call hooks; it
+      // returns the real component function.
+      return function App() {
+        const [n, setN] = window.useState(0);
+        return window.h('button', { onClick: () => setN(n + 1), id: 'fb' }, 'n=' + n);
+      };
+    }
+    window.loxia.render(Factory, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('n=0');
+    window.document.getElementById('fb').click();
+    expect(root.textContent).toContain('n=1');
+    window.document.getElementById('fb').click();
+    expect(root.textContent).toContain('n=2');
+  });
+
+  // REGRESSION: parseTemplate used to reference `values` from the outer
+  // scope — except `values` only exists inside html(), not in parseTemplate.
+  // The first interpolated template the agent wrote blew up with
+  // "values is not defined". Fix is to use strings.length-1 as the
+  // "values remaining" check. This pins it.
+  test('html`…` with interpolations works (REGRESSION: parseTemplate had an out-of-scope ref)', () => {
+    const userCode = [
+      'return function App() {',
+      '  const [count, setCount] = useState(0);',
+      '  return html`<div>',
+      '    <span>c=${count}</span>',
+      '    <button id="b" onClick=${() => setCount(count + 1)}>+1</button>',
+      '  </div>`;',
+      '};',
+    ].join('\n');
+    const fn = new window.Function(userCode)();
+    window.loxia.render(fn, {});
+    const root = window.document.getElementById('root');
+    expect(root.textContent).toContain('c=0');
+    window.document.getElementById('b').click();
+    expect(root.textContent).toContain('c=1');
+    window.document.getElementById('b').click();
+    expect(root.textContent).toContain('c=2');
+  });
+});

package/src/modules/widget/__tests__/schema.test.js

@@ -0,0 +1,155 @@
+/**
+ * Schema validation — per-action contracts.
+ *
+ * These are the exact checks the tool uses before touching state. Every
+ * branch should be covered because agents will absolutely probe them —
+ * bad `widgetId` charsets, missing content, oversized payloads, wrong
+ * `kind` strings, array-as-props mistakes, etc.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  validateRenderParams,
+  validateUpdateParams,
+  validateDestroyParams,
+  WIDGET_LIMITS,
+  WIDGET_KINDS,
+} from '../schema.js';
+
+describe('WIDGET_LIMITS / WIDGET_KINDS', () => {
+  test('limits are sane positive numbers', () => {
+    expect(WIDGET_LIMITS.MAX_CONTENT_BYTES).toBeGreaterThan(0);
+    expect(WIDGET_LIMITS.MAX_WIDGET_ID_LEN).toBeGreaterThan(0);
+    expect(WIDGET_LIMITS.MAX_WIDGETS_PER_AGENT).toBeGreaterThan(0);
+  });
+  test('kinds are frozen to prevent accidental mutation', () => {
+    expect(Object.isFrozen(WIDGET_KINDS)).toBe(true);
+    expect(WIDGET_KINDS).toEqual(['html', 'jsx', 'webcomponent']);
+  });
+});
+
+describe('validateRenderParams', () => {
+  test('rejects non-object', () => {
+    expect(validateRenderParams(null).valid).toBe(false);
+    expect(validateRenderParams(undefined).valid).toBe(false);
+    expect(validateRenderParams('hi').valid).toBe(false);
+    expect(validateRenderParams(42).valid).toBe(false);
+  });
+
+  test('requires a valid kind', () => {
+    const r = validateRenderParams({ kind: 'iframe', content: 'x' });
+    expect(r.valid).toBe(false);
+    expect(r.error).toMatch(/kind/);
+  });
+
+  test('accepts html and jsx as kinds', () => {
+    expect(validateRenderParams({ kind: 'html', content: '<p/>' }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'jsx',  content: 'return () => ({type:"div"});' }).valid).toBe(true);
+  });
+
+  test('requires non-empty string content', () => {
+    expect(validateRenderParams({ kind: 'html' }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: '' }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: '   ' }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: 123 }).valid).toBe(false);
+  });
+
+  test('rejects content exceeding MAX_CONTENT_BYTES', () => {
+    const big = 'x'.repeat(WIDGET_LIMITS.MAX_CONTENT_BYTES + 1);
+    const r = validateRenderParams({ kind: 'html', content: big });
+    expect(r.valid).toBe(false);
+    expect(r.error).toMatch(/exceeds/);
+  });
+
+  test('measures size in UTF-8 bytes, not chars', () => {
+    // "🌟" is 4 bytes. Fill exactly one byte over the limit using it.
+    const emoji = '🌟'; // 4 bytes
+    const count = Math.floor(WIDGET_LIMITS.MAX_CONTENT_BYTES / 4) + 1;
+    const payload = emoji.repeat(count);
+    const r = validateRenderParams({ kind: 'html', content: payload });
+    expect(r.valid).toBe(false);
+  });
+
+  test('widgetId optional; when present, must be string of allowed charset', () => {
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: 'a_1' }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: 'my.widget-01' }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: 'bad char' }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: '' }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: 42 }).valid).toBe(false);
+    const tooLong = 'a'.repeat(WIDGET_LIMITS.MAX_WIDGET_ID_LEN + 1);
+    expect(validateRenderParams({ kind: 'html', content: 'x', widgetId: tooLong }).valid).toBe(false);
+  });
+
+  test('widgetId rejects path traversal / whitespace / special chars', () => {
+    for (const bad of ['../x', 'a b', 'a/b', 'a\\b', "a'b", 'a"b', 'a;b']) {
+      const r = validateRenderParams({ kind: 'html', content: 'x', widgetId: bad });
+      expect(r.valid).toBe(false);
+    }
+  });
+
+  // REGRESSION: agents would render kind:'html' with <script> tags
+  // expecting them to run, but html mode is sandbox="" — the browser
+  // silently blocks the scripts in the iframe console, the user sees
+  // a dead widget. Catch this at validation time with a named hint.
+  test('kind:html with <script> tag is rejected with a HELPFUL error', () => {
+    const cases = [
+      '<div><script>alert(1)</script></div>',
+      '<div></div><script type="module">x()</script>',
+      '<SCRIPT>x</SCRIPT>',  // case-insensitive
+      '<script src="..."></script>',
+    ];
+    for (const content of cases) {
+      const r = validateRenderParams({ kind: 'html', content });
+      expect(r.valid).toBe(false);
+      expect(r.error).toMatch(/static-only/);
+      expect(r.error).toMatch(/webcomponent/);
+      expect(r.error).toMatch(/jsx/);
+    }
+  });
+
+  test('kind:html WITHOUT <script> is accepted', () => {
+    expect(validateRenderParams({ kind: 'html', content: '<div>hello</div>' }).valid).toBe(true);
+    // The word "script" appearing in TEXT (not as a tag) is fine
+    expect(validateRenderParams({ kind: 'html', content: '<p>this script does nothing</p>' }).valid).toBe(true);
+  });
+
+  test('kind:webcomponent or kind:jsx with <script>-shaped strings is fine (they are JS source, not HTML)', () => {
+    // Agent's webcomponent code might LITERALLY contain the substring
+    // "<script>" inside a template literal it builds. Since the agent
+    // code goes through customElements/innerHTML rather than as HTML,
+    // we only check kind:'html'.
+    expect(validateRenderParams({ kind: 'webcomponent', content: 'class X extends LoxiaElement { template() { return "<script>foo</script>"; } } loxia.render(X);' }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'jsx', content: 'return html`<div>${"<script>"}</div>`;' }).valid).toBe(true);
+  });
+
+  test('props optional; must be plain object when provided', () => {
+    expect(validateRenderParams({ kind: 'html', content: 'x', props: {} }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'html', content: 'x', props: { a: 1 } }).valid).toBe(true);
+    expect(validateRenderParams({ kind: 'html', content: 'x', props: [] }).valid).toBe(false);
+    expect(validateRenderParams({ kind: 'html', content: 'x', props: 'no' }).valid).toBe(false);
+  });
+});
+
+describe('validateUpdateParams', () => {
+  test('rejects non-object params', () => {
+    expect(validateUpdateParams(null).valid).toBe(false);
+  });
+  test('requires widgetId and props', () => {
+    expect(validateUpdateParams({}).valid).toBe(false);
+    expect(validateUpdateParams({ widgetId: 'a' }).valid).toBe(false);
+    expect(validateUpdateParams({ widgetId: 'a', props: null }).valid).toBe(false);
+    expect(validateUpdateParams({ widgetId: 'a', props: [] }).valid).toBe(false);
+    expect(validateUpdateParams({ widgetId: 'a', props: {} }).valid).toBe(true);
+  });
+});
+
+describe('validateDestroyParams', () => {
+  test('rejects non-object', () => {
+    expect(validateDestroyParams(null).valid).toBe(false);
+  });
+  test('requires non-empty string widgetId', () => {
+    expect(validateDestroyParams({}).valid).toBe(false);
+    expect(validateDestroyParams({ widgetId: '' }).valid).toBe(false);
+    expect(validateDestroyParams({ widgetId: 'a' }).valid).toBe(true);
+  });
+});