onbuzz 4.3.0 → 4.5.0

package/src/modules/widget/runtime/webComponentBundle.js

@@ -0,0 +1,470 @@
+/**
+ * Web-Component runtime bundle — STRING, served to every webcomponent-mode iframe.
+ *
+ * Strictly smaller and simpler than the JSX bundle. Why this path exists:
+ * the JSX path keeps producing failures rooted in our custom runtime
+ * (htm parser quirks, hooks call-order, namespace whack-a-mole). Custom
+ * elements use only the platform — `class extends HTMLElement`,
+ * `customElements.define`, `connectedCallback` — APIs every modern
+ * browser ships and every LLM has thousands of training examples for.
+ *
+ * Ergonomic helper: `LoxiaElement` base class that absorbs the boilerplate
+ * (state, render, auto-binding for `data-bind` and `data-emit`). Agents
+ * who want raw `HTMLElement` can still use it; the runtime detects.
+ *
+ * The agent's code is expected to:
+ *   1. Define a class (extends LoxiaElement OR HTMLElement)
+ *   2. Call loxia.render(TheClass, initialProps)
+ *
+ * The runtime registers the class with a unique tag name, instantiates,
+ * mounts to #root, and wires the postMessage bridge.
+ */
+
+export const WIDGET_WC_RUNTIME = `
+/* ==== Loxia widget web-component runtime v1 ==== */
+(function () {
+  'use strict';
+
+  let _rootInstance = null;
+  let _tagCounter = 0;
+
+  /* ---------- LoxiaElement base class ---------- */
+  // Optional ergonomic base. Inherits from HTMLElement, adds:
+  //   - this.state                     — instance object, init in constructor or as a class field
+  //   - this.setState(updater)         — merges or replaces state, triggers re-render
+  //   - this.template(state) → string  — override; returned HTML is set on innerHTML
+  //   - this.emit(type, payload)       — sendEvent via postMessage to parent
+  //   - data-bind="key" auto-binding   — input/change events update state[key]
+  //   - data-emit="name" auto-binding  — clicks emit the named event
+  //   - this.handleUpdate(props)       — called when agent sends widget.update; default is setState(props)
+  //
+  // For raw HTMLElement subclasses (no LoxiaElement), widget.update sets
+  // attributes — agent's attributeChangedCallback handles re-render.
+  class LoxiaElement extends HTMLElement {
+    constructor() {
+      super();
+      // Attach a shadow root so:
+      //   1. \`this.shadowRoot\` is non-null — agents trained on web
+      //      components heavily expect it (was the #2 reported failure)
+      //   2. CSS scopes don't bleed between widget and parent iframe
+      //   3. Selectors like this.shadowRoot.querySelector work
+      // CSS custom properties pierce shadow boundaries, so theme tokens
+      // (--gray-500, --loxia-600) still apply inside the widget.
+      try { this.attachShadow({ mode: 'open' }); }
+      catch (_) { /* already attached or environment doesn\'t support */ }
+
+      // Allow subclasses to declare \`state = { ... }\` as a class field.
+      // \`super()\` runs before field initializers, so we can't depend on
+      // them being set yet. Default to {} and merge later.
+      if (this.state === undefined) this.state = {};
+    }
+    /** The render target — shadowRoot when available, otherwise the element itself. */
+    get _root() { return this.shadowRoot || this; }
+    setState(updater) {
+      this.state = (typeof updater === 'function')
+        ? updater(this.state)
+        : Object.assign({}, this.state, updater);
+      this.render();
+    }
+    connectedCallback() {
+      this.render();
+      try { if (this.onMount) this.onMount(); }
+      catch (err) { if (window.__loxiaReportError) window.__loxiaReportError(err, 'mount'); }
+    }
+    disconnectedCallback() {
+      try { if (this.onUnmount) this.onUnmount(); }
+      catch (err) { if (window.__loxiaReportError) window.__loxiaReportError(err, 'unmount'); }
+    }
+    render() {
+      let html = '';
+      try {
+        html = this.template ? this.template(this.state) : (this._root.innerHTML || '');
+      } catch (err) {
+        if (window.__loxiaReportError) window.__loxiaReportError(err, 'render');
+        return;
+      }
+      this._root.innerHTML = html;
+      // Normalize footgun shapes BEFORE wiring so the rewritten
+      // attributes (data-bind-click → data-on-click, etc.) participate
+      // in the standard binding pass and the buttons actually work.
+      this._normalizeFootguns();
+      this._wireBindings();
+      // afterRender(root) — sanctioned hook for agents who need to attach
+      // listeners that the auto-wiring doesn't cover (intersection
+      // observer, complex pointer drag, focus-trap, ...). Called AFTER
+      // every render — listeners attached here survive setState because
+      // they're re-attached on the fresh DOM. Without this, agents who
+      // call addEventListener in onMount() see their listeners die on
+      // the first re-render (innerHTML wipe) — and there's no error.
+      try { if (typeof this.afterRender === 'function') this.afterRender(this._root); }
+      catch (err) { if (window.__loxiaReportError) window.__loxiaReportError(err, 'afterRender'); }
+    }
+    /**
+     * Scan the freshly-rendered DOM for known typo shapes that LOOK like
+     * they should wire something up but DON'T. Reports each as a render
+     * error so agents see a clear message instead of "nothing happens".
+     *
+     * What's flagged:
+     *   - data-bind-<anything>  (data-bind-click, data-bind-input, ...)
+     *   - data-action, data-handler, data-click, data-onclick
+     *   - inline on*= attributes (onclick, onchange, onkeydown, ...)
+     *
+     * Each pattern includes a "did you mean ...?" hint pointing at the
+     * supported alternative. Reported once per attribute per render
+     * (de-duped via the global error infrastructure's "seen" map).
+     */
+    /**
+     * Scan the freshly-rendered DOM for known typo shapes that LOOK like
+     * they should wire something up but don't. For each detected typo:
+     *   1. Emit a non-fatal warning (so the agent learns the right shape)
+     *   2. Rewrite the attribute IN PLACE to the canonical equivalent
+     *      so the standard wiring pass picks it up — meaning the widget
+     *      actually works on this render, not just "next time the agent
+     *      ships a fix".
+     *
+     * Inline on*= attributes are warning-only — we can't safely transform
+     * a JS expression like onclick="this.foo()" into a method-name binding
+     * (we don't know the intent), so the agent has to fix those.
+     */
+    _normalizeFootguns() {
+      const root = this._root;
+      // Footgun detection is a LINT, not a fatal error. The widget itself
+      // rendered fine; only specific click-handler bindings are dead. Route
+      // through the warning channel so the user still sees the widget
+      // (with a small "scripts have warnings" badge) instead of a red
+      // "widget failed to load" screen replacing the whole thing.
+      // Unified emit: warnings if the warning channel is available,
+      // otherwise fall back to error reporting. Always passes a STRING
+      // message — the warning channel takes a string; the error channel
+      // accepts a string too via its toString() path.
+      const emit = (msg) => {
+        if (window.__loxiaReportWarning) {
+          window.__loxiaReportWarning(msg, 'lint');
+        } else if (window.__loxiaReportError) {
+          window.__loxiaReportError(new Error(msg), 'lint');
+        }
+      };
+      const FAKE_DATA_EXACT = {
+        'data-action':  'data-on-click="methodName"',
+        'data-handler': 'data-on-click="methodName"',
+        'data-click':   'data-on-click="methodName"',
+        'data-onclick': 'data-on-click="methodName"',
+      };
+      // Inline on*= attributes (onclick, onchange, ...) — these run in
+      // the iframe's GLOBAL scope, not bound to the LoxiaElement, so
+      // \`this.method()\` references silently miss the instance.
+      const INLINE_ON_RE = /^on[a-z]+$/;
+
+      // Rewrite an attribute on \`el\` from \`oldName\` to \`newName\`, keeping
+      // the value, but only if \`newName\` isn't already there (don't
+      // clobber a real binding the agent also wrote).
+      const rename = (el, oldName, newName) => {
+        const value = el.getAttribute(oldName);
+        el.removeAttribute(oldName);
+        if (!el.hasAttribute(newName)) el.setAttribute(newName, value);
+      };
+
+      root.querySelectorAll('*').forEach(function(el) {
+        if (!el.attributes) return;
+        // Iterate over a SNAPSHOT — we mutate attributes in this loop,
+        // and the live NamedNodeMap shifts indices when we removeAttribute.
+        const snapshot = [];
+        for (let i = 0; i < el.attributes.length; i++) {
+          snapshot.push(el.attributes[i].name);
+        }
+        for (const name of snapshot) {
+          if (!name) continue;
+
+          // 1. data-bind-<x>  →  data-on-<x>   (autofix)
+          if (name !== 'data-bind' && name.indexOf('data-bind-') === 0) {
+            const evt = name.slice('data-bind-'.length) || 'click';
+            const target = 'data-on-' + evt;
+            emit(
+              'Attribute "' + name + '" is NOT auto-wired — auto-rewrote to "' +
+              target + '". Update your template to use ' + target +
+              '="methodName" so this warning goes away. ' +
+              '(data-bind is for input→state binding; for event→method use data-on-<event>.)'
+            );
+            rename(el, name, target);
+            continue;
+          }
+
+          // 2. data-on:<x>  →  data-on-<x>   (autofix)
+          if (name.indexOf('data-on:') === 0) {
+            const evt = name.slice('data-on:'.length) || 'click';
+            const target = 'data-on-' + evt;
+            emit(
+              'Attribute "' + name + '" uses ":" but the runtime expects "-" — ' +
+              'auto-rewrote to "' + target + '". Update your template.'
+            );
+            rename(el, name, target);
+            continue;
+          }
+
+          // 3. data-action / data-handler / data-click / data-onclick
+          //    →  data-on-click   (autofix)
+          if (FAKE_DATA_EXACT[name]) {
+            emit(
+              'Attribute "' + name + '" is NOT auto-wired — auto-rewrote to "data-on-click". ' +
+              'Update your template to use ' + FAKE_DATA_EXACT[name] + '.'
+            );
+            rename(el, name, 'data-on-click');
+            continue;
+          }
+
+          // 4. Inline on*= attributes — WARNING ONLY. We can't safely
+          //    transform a JS expression like onclick="this.foo()" into
+          //    a method-name binding (we don't know the agent's intent).
+          //    The agent has to ship a fixed template. The widget still
+          //    renders fine; only this specific handler is dead.
+          if (INLINE_ON_RE.test(name)) {
+            const evt = name.slice(2);
+            emit(
+              'Inline attribute "' + name + '" runs in the iframe global scope ' +
+              '— "this" inside it is the element, not your LoxiaElement instance, ' +
+              'so "this.method()" silently fails. Use data-on-' + evt +
+              '="methodName" instead. (Cannot auto-rewrite — the value is a JS ' +
+              'expression, not a method name.)'
+            );
+            continue;
+          }
+
+          // 5. data-on / data-on- with no event name — agent forgot the
+          //    suffix. Can't autofix (we don't know which event).
+          if (name === 'data-on-' || name === 'data-on') {
+            emit(
+              'Attribute "' + name + '" is missing the event name. ' +
+              'Use data-on-click="methodName", data-on-input="methodName", etc.'
+            );
+          }
+        }
+      });
+    }
+    _wireBindings() {
+      const self = this;
+      // data-bind="key" — input/change/textContent updates state[key].
+      // Query against shadowRoot if present (where the agent\'s template
+      // was actually rendered) so bindings work in both shadow + light DOM.
+      this._root.querySelectorAll('[data-bind]').forEach(function(el) {
+        const key = el.dataset.bind;
+        const handler = function(e) {
+          const t = e.target;
+          let value;
+          if (t.type === 'checkbox') value = t.checked;
+          else if (t.type === 'number' || t.type === 'range') value = t.value === '' ? '' : Number(t.value);
+          else value = t.value;
+          self.setState(Object.assign({}, self.state, { [key]: value }));
+        };
+        el.oninput = handler;
+        el.onchange = handler;
+      });
+      // data-emit="name" — click sends an event to the agent.
+      this._root.querySelectorAll('[data-emit]').forEach(function(el) {
+        el.onclick = function(e) {
+          // Optional data-payload="{...}" for custom payloads.
+          let extra = {};
+          try { if (el.dataset.payload) extra = JSON.parse(el.dataset.payload); } catch (_) {}
+          self.emit(el.dataset.emit, Object.assign({ state: self.state }, extra));
+        };
+      });
+      // data-on-<event>="methodName" — call a LOCAL instance method when
+      // the named DOM event fires on the element. \`this\` inside the
+      // method is bound to the LoxiaElement instance; the DOM event is
+      // passed as the first argument.
+      //
+      // GENERIC: any \`data-on-<anything>\` attribute is wired via
+      // addEventListener — browser-supported event names just work.
+      // Confirmed to fire for the obvious set (click, input, change,
+      // submit, focus, blur, keydown, keyup, mouseenter, mouseleave,
+      // mouseover, mouseout, mousedown, mouseup, mousemove, dblclick,
+      // contextmenu, wheel, pointerdown, pointerup, pointermove,
+      // pointerenter, pointerleave, touchstart, touchend, touchmove,
+      // dragstart, drag, dragend, dragenter, dragleave, dragover, drop,
+      // copy, cut, paste, scroll, transitionend, animationend, ...).
+      //
+      // Why generic rather than an allowlist: agents shouldn't have to
+      // guess "is keypress wired? what about pointerdown?" — anything
+      // addEventListener accepts works. addEventListener silently
+      // ignores nonexistent event names, so typos in the EVENT name
+      // can't blow up the page; typos in the METHOD name (the more
+      // common mistake) are caught explicitly below.
+      self._root.querySelectorAll('*').forEach(function(el) {
+        if (!el.attributes) return;
+        for (let i = 0; i < el.attributes.length; i++) {
+          const attr = el.attributes[i];
+          if (!attr.name || attr.name.indexOf('data-on-') !== 0) continue;
+          const eventName = attr.name.slice('data-on-'.length);
+          if (!eventName) continue;
+          const methodName = attr.value;
+          const fn = self[methodName];
+          if (typeof fn !== 'function') {
+            // Surface the typo loudly so agents stop guessing attribute
+            // names. Without this, mistakes like data-bind-click silently
+            // do nothing — looks like a broken widget with no error.
+            //
+            // Routed through the WARNING channel: the rest of the widget
+            // mounted fine and we don't want to replace it with a red
+            // error screen because of one missing handler.
+            const warn = window.__loxiaReportWarning || window.__loxiaReportError;
+            if (warn) {
+              warn(
+                'data-on-' + eventName + '="' + methodName + '" but the class has no method named "' + methodName + '". Define it on your LoxiaElement subclass, or check the attribute spelling.',
+                'lint'
+              );
+            }
+            continue;
+          }
+          el.addEventListener(eventName, function(e) {
+            try { fn.call(self, e); }
+            catch (err) {
+              if (window.__loxiaReportError) window.__loxiaReportError(err, 'event-handler');
+            }
+          });
+        }
+      });
+    }
+    emit(type, payload) {
+      try {
+        window.parent.postMessage({
+          __loxia: true, type: 'event', widgetId: window.__loxiaWidgetId,
+          payload: Object.assign({ type: type }, payload || {})
+        }, '*');
+      } catch (_) {}
+    }
+    handleUpdate(newProps) {
+      // Default: merge into state. Subclasses can override for custom logic.
+      this.setState(newProps);
+    }
+  }
+
+  /* ---------- auto-resize ---------- */
+  let _heightDebounce = null;
+  function scheduleHeight() {
+    if (_heightDebounce) clearTimeout(_heightDebounce);
+    _heightDebounce = setTimeout(function () {
+      try {
+        window.parent.postMessage({
+          __loxia: true, type: 'resize', widgetId: window.__loxiaWidgetId,
+          height: Math.ceil(document.body.scrollHeight)
+        }, '*');
+      } catch (_) {}
+    }, 50);
+  }
+  if (typeof ResizeObserver !== 'undefined') {
+    document.addEventListener('DOMContentLoaded', function () {
+      const ro = new ResizeObserver(scheduleHeight);
+      ro.observe(document.body);
+    });
+  } else {
+    document.addEventListener('DOMContentLoaded', function () { setTimeout(scheduleHeight, 50); });
+  }
+
+  /* ---------- prop updates from agent → instance ---------- */
+  window.addEventListener('message', function (e) {
+    if (!e.data || e.data.__loxia !== true) return;
+    if (e.source !== window.parent) return;
+    if (e.data.type === 'update' && e.data.props && _rootInstance) {
+      try {
+        if (typeof _rootInstance.handleUpdate === 'function') {
+          _rootInstance.handleUpdate(e.data.props);
+        } else if (typeof _rootInstance.setState === 'function') {
+          _rootInstance.setState(e.data.props);
+        } else {
+          // Plain HTMLElement — set attributes and let attributeChangedCallback fire.
+          for (const k in e.data.props) {
+            if (Object.prototype.hasOwnProperty.call(e.data.props, k)) {
+              _rootInstance.setAttribute(k, String(e.data.props[k]));
+            }
+          }
+        }
+      } catch (err) {
+        if (window.__loxiaReportError) window.__loxiaReportError(err, 'update');
+      }
+    }
+  });
+
+  /* ---------- public API ---------- */
+  window.LoxiaElement = LoxiaElement;
+  window.loxia = window.loxia || {};
+
+  function uniqueTagName() {
+    return 'loxia-w-' + (++_tagCounter) + '-' + Math.random().toString(36).slice(2, 8);
+  }
+
+  Object.assign(window.loxia, {
+    LoxiaElement: LoxiaElement,
+    /**
+     * Register the class (with a fresh unique tag), create one instance,
+     * and mount it into #root. Agent calls this LAST. Don't call
+     * customElements.define yourself — this handles registration.
+     */
+    render: function (ElementClass, initialProps) {
+      if (typeof ElementClass !== 'function') {
+        throw new Error(
+          'loxia.render expects a class (extends LoxiaElement or HTMLElement). ' +
+          'Got: ' + typeof ElementClass + '. ' +
+          'Define your class then call loxia.render(YourClass, initialProps).'
+        );
+      }
+      // Pre-flight: prototype-chain check. customElements.define is
+      // permissive in some implementations and accepts classes that
+      // aren't HTMLElement subclasses (jsdom). Catching it ourselves
+      // means the agent sees a NAMED, actionable error.
+      if (!(ElementClass.prototype instanceof HTMLElement) && ElementClass.prototype !== HTMLElement.prototype) {
+        throw new Error(
+          'loxia.render expects a class that extends HTMLElement (or LoxiaElement, which is an HTMLElement subclass). ' +
+          'Your class does NOT. Rewrite as: class YourWidget extends LoxiaElement { template(state) { ... } }.'
+        );
+      }
+      const tagName = uniqueTagName();
+      try {
+        customElements.define(tagName, ElementClass);
+      } catch (err) {
+        throw new Error(
+          'customElements.define failed: ' + err.message + '. ' +
+          'If your class already calls customElements.define(...) itself, remove that line — loxia.render handles registration.'
+        );
+      }
+      const instance = document.createElement(tagName);
+      // Seed initial state. For LoxiaElement: use setState (or assign so
+      // connectedCallback's render uses the seed). For raw HTMLElement:
+      // set as attributes (the standard web-component idiom).
+      const props = initialProps || {};
+      if (instance instanceof LoxiaElement) {
+        // Assign before connectedCallback fires so first render sees the seed.
+        instance.state = Object.assign({}, instance.state || {}, props);
+      } else {
+        for (const k in props) {
+          if (Object.prototype.hasOwnProperty.call(props, k)) {
+            instance.setAttribute(k, String(props[k]));
+          }
+        }
+      }
+      const root = document.getElementById('root') || document.body;
+      root.innerHTML = '';
+      root.appendChild(instance);
+      _rootInstance = instance;
+      return instance;
+    },
+    sendEvent: function (evt) {
+      try {
+        window.parent.postMessage({
+          __loxia: true, type: 'event', widgetId: window.__loxiaWidgetId, payload: evt
+        }, '*');
+      } catch (_) {}
+    },
+    requestHeight: function (px) {
+      try {
+        window.parent.postMessage({
+          __loxia: true, type: 'resize', widgetId: window.__loxiaWidgetId, height: px
+        }, '*');
+      } catch (_) {}
+    },
+    // onUpdate is intentionally NOT mirrored from the JSX runtime —
+    // in webcomponent mode, the instance's handleUpdate(props) method
+    // is the right hook (instance has its own setState, etc.).
+  });
+})();
+`;
+
+export default WIDGET_WC_RUNTIME;

package/src/modules/widget/schema.js

@@ -0,0 +1,181 @@
+/**
+ * Widget schema + validation.
+ *
+ * Tool actions:
+ *   render   → { widgetId?, kind, content, props? }  (creates or replaces)
+ *   update   → { widgetId, props }                   (replaces props on an existing widget)
+ *   destroy  → { widgetId }
+ *   list     → { }
+ *
+ * Kinds:
+ *   'html' — static HTML+CSS, sandbox="" (no scripts, no forms, no same-origin)
+ *   'jsx'  — Preact+htm render function, sandbox="allow-scripts" (scripts only)
+ *
+ * Size limits are deliberately generous for MVP but finite — agents should
+ * not be pushing multi-megabyte iframes into the chat feed.
+ */
+
+export const WIDGET_LIMITS = {
+  MAX_CONTENT_BYTES:   50 * 1024, // 50 KB per widget payload
+  MAX_WIDGET_ID_LEN:   128,
+  MAX_WIDGET_NAME_LEN: 80,        // human-friendly display name (not unique)
+  MAX_WIDGETS_PER_AGENT: 50,      // LRU-evicted beyond this
+  MAX_VERSIONS_PER_WIDGET: 20,    // history ring; older versions evicted
+};
+
+// Three kinds:
+//   'html'         — static HTML, sandbox="" (no scripts)
+//   'jsx'          — Preact + htm runtime; hooks, h(), html``
+//   'webcomponent' — class extends LoxiaElement / HTMLElement; standard
+//                    web platform APIs only (no JSX, no hooks, no
+//                    namespace imports). Recommended for interactive
+//                    widgets — eliminates an entire class of failures
+//                    rooted in custom-runtime quirks. The JSX path
+//                    stays for agents that prefer hooks.
+export const WIDGET_KINDS = Object.freeze(['html', 'jsx', 'webcomponent']);
+
+/**
+ * Validate a `render` payload.
+ * Returns { valid: true } or { valid: false, error: string }.
+ */
+/**
+ * Shared validator for the optional human-friendly display name.
+ * Names are NOT unique per agent — that's the widgetId's job. Names are
+ * purely cosmetic; multiple widgets named "Calculator" coexist fine.
+ */
+function validateName(name) {
+  if (name == null) return { valid: true };
+  if (typeof name !== 'string') return { valid: false, error: 'name must be a string' };
+  // Trim before length check so trailing whitespace doesn't push valid
+  // names over the cap; the canonical (trimmed) value is what we store.
+  const trimmed = name.trim();
+  if (trimmed.length === 0) {
+    return { valid: false, error: 'name must be non-empty (or omit it)' };
+  }
+  if (trimmed.length > WIDGET_LIMITS.MAX_WIDGET_NAME_LEN) {
+    return { valid: false, error: `name exceeds ${WIDGET_LIMITS.MAX_WIDGET_NAME_LEN} chars` };
+  }
+  // Reject control characters — names appear in card UIs and tooltips,
+  // a stray \r or \x00 would mangle layout.
+  if (/[\x00-\x1f\x7f]/.test(trimmed)) {
+    return { valid: false, error: 'name must not contain control characters' };
+  }
+  return { valid: true, normalized: trimmed };
+}
+
+/** Public wrapper so the tool can canonicalize the same way validators do. */
+export function normalizeName(name) {
+  const r = validateName(name);
+  return r.valid && r.normalized != null ? r.normalized : null;
+}
+
+export function validateRenderParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  const { kind, content, widgetId, props, name } = params;
+  const nameRes = validateName(name);
+  if (!nameRes.valid) return nameRes;
+
+  if (!WIDGET_KINDS.includes(kind)) {
+    return { valid: false, error: `kind must be one of: ${WIDGET_KINDS.join(', ')}` };
+  }
+  if (typeof content !== 'string' || !content.trim()) {
+    return { valid: false, error: 'content (string) is required' };
+  }
+  if (Buffer.byteLength(content, 'utf8') > WIDGET_LIMITS.MAX_CONTENT_BYTES) {
+    return {
+      valid: false,
+      error: `content exceeds ${WIDGET_LIMITS.MAX_CONTENT_BYTES} bytes — trim or split`,
+    };
+  }
+  // kind:'html' is sandbox="" — scripts won't run. Catch this here with a
+  // clear named error so the agent doesn't ship a static widget that
+  // silently loses its interactivity (browser only logs "Blocked script
+  // execution in about:srcdoc … allow-scripts not set" to the iframe
+  // console, which the agent never sees).
+  if (kind === 'html' && /<script\b/i.test(content)) {
+    return {
+      valid: false,
+      error:
+        "kind:'html' is a static-only mode (sandbox=\"\" — scripts are blocked). " +
+        "Your content contains a <script> tag, which will not execute. " +
+        "Switch to kind:'webcomponent' (recommended) or kind:'jsx' for interactive widgets. " +
+        "If you only need styling and layout, remove the <script> tag.",
+    };
+  }
+  if (widgetId != null) {
+    if (typeof widgetId !== 'string' || widgetId.length === 0 || widgetId.length > WIDGET_LIMITS.MAX_WIDGET_ID_LEN) {
+      return { valid: false, error: `widgetId must be a 1..${WIDGET_LIMITS.MAX_WIDGET_ID_LEN}-char string` };
+    }
+    // Conservative charset: agent-pickable ids, filesystem-safe, URL-safe.
+    if (!/^[a-zA-Z0-9._-]+$/.test(widgetId)) {
+      return { valid: false, error: 'widgetId may only contain [a-zA-Z0-9._-]' };
+    }
+  }
+  if (props != null && (typeof props !== 'object' || Array.isArray(props))) {
+    return { valid: false, error: 'props, if provided, must be a plain object' };
+  }
+  return { valid: true };
+}
+
+export function validateUpdateParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  const { widgetId, props } = params;
+  if (typeof widgetId !== 'string' || !widgetId) {
+    return { valid: false, error: 'widgetId is required' };
+  }
+  if (props == null || typeof props !== 'object' || Array.isArray(props)) {
+    return { valid: false, error: 'props (object) is required' };
+  }
+  return { valid: true };
+}
+
+export function validateDestroyParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  if (typeof params.widgetId !== 'string' || !params.widgetId) {
+    return { valid: false, error: 'widgetId is required' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate `list-versions` and `get-version` payloads. Both take a widgetId;
+ * `get-version` additionally requires a versionId.
+ */
+export function validateListVersionsParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  if (typeof params.widgetId !== 'string' || !params.widgetId) {
+    return { valid: false, error: 'widgetId is required' };
+  }
+  return { valid: true };
+}
+
+export function validateGetVersionParams(params) {
+  const base = validateListVersionsParams(params);
+  if (!base.valid) return base;
+  if (typeof params.versionId !== 'string' || !params.versionId) {
+    return { valid: false, error: 'versionId is required' };
+  }
+  return { valid: true };
+}
+
+/**
+ * `set-main { widgetId, versionId }` — promote a specific version to be the
+ * one rendered when the artifact is opened.
+ */
+export function validateSetMainParams(params) {
+  return validateGetVersionParams(params);
+}
+
+/**
+ * `rename { widgetId, name }` — set/clear the human-friendly display name.
+ * Pass null/empty name to clear. Names are NOT unique — widgetId is.
+ */
+export function validateRenameParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  if (typeof params.widgetId !== 'string' || !params.widgetId) {
+    return { valid: false, error: 'widgetId is required' };
+  }
+  // Allow explicit null/'' to CLEAR the name (revert to widgetId-as-display).
+  if (params.name === null || params.name === '') return { valid: true, clear: true };
+  return validateName(params.name);
+}