@napster-corp/webmcp-toolkit 1.0.0

package/src/dev-panel.ts

@@ -0,0 +1,1318 @@
+// WebMCP Toolkit Dev Panel — opt-in, in-browser UI for testing tools by hand.
+//
+// Self-contained: no framework, no external CSS. It reads the STANDARD surface
+// (`document.modelContext` — tools via getTools()/executeTool(), live state via
+// the toolkit's resource extension), so it inspects exactly what a WebMCP agent
+// sees. Renders into a Shadow DOM so it is fully isolated from the host app.
+//
+// Mount with `installDevPanel()` from the app's entry point, behind a dev-mode
+// guard. The default keyboard shortcut (Cmd+Shift+E on Mac, Ctrl+Shift+E
+// elsewhere) toggles visibility.
+
+import { getModelContextWithResources } from './model-context.js';
+import { getTier } from './tiers.js';
+import type {
+  ModelContextWithResources,
+  ResourceUpdate,
+  SideEffect,
+  ToolInfo,
+} from './types.js';
+
+// ───────── Standard-surface adapter ───────────────────────────────────────
+// A small read/invoke layer over `document.modelContext`, so the rest of the
+// panel works in the same shape it did over the old EdgeMcp instance.
+
+const EMPTY_OBJECT_SCHEMA: Record<string, unknown> = { type: 'object', properties: {} };
+
+/** A tool as the panel renders it: standard info + the toolkit's recorded tier. */
+interface ToolView {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  tier: SideEffect;
+  idempotent: boolean;
+}
+
+async function listToolViews(mc: ModelContextWithResources): Promise<ToolView[]> {
+  const tools = await mc.getTools();
+  return tools.map((t: ToolInfo) => {
+    // Tier can't ride on the standard tool (getTools() drops annotations), so
+    // we read it from the toolkit-side registry. Tools registered with plain
+    // standard registerTool (no tier recorded) default to 'reversible'.
+    const tier = getTier(t.name);
+    return {
+      name: t.name,
+      description: t.description ?? '',
+      inputSchema: (t.inputSchema as Record<string, unknown>) ?? EMPTY_OBJECT_SCHEMA,
+      tier: tier?.tier ?? 'reversible',
+      idempotent: tier?.idempotent ?? false,
+    };
+  });
+}
+
+interface InvokeOutcome {
+  ok: boolean;
+  output?: string | null;
+  error?: string;
+}
+
+async function invokeTool(
+  mc: ModelContextWithResources,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<InvokeOutcome> {
+  try {
+    const tools = await mc.getTools();
+    const info = tools.find((t) => t.name === name);
+    if (!info) return { ok: false, error: `Unknown tool: ${name}` };
+    const output = await mc.executeTool(info, JSON.stringify(args));
+    return { ok: true, output };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+// ───────── Public API ─────────────────────────────────────────────────────
+
+export interface DevPanelOptions {
+  /** Keyboard shortcut to toggle the panel. Default: 'Cmd+Shift+E'. */
+  shortcut?: string;
+  /** Open the panel as soon as it mounts. Default: false. */
+  startOpen?: boolean;
+}
+
+/**
+ * Mount the dev panel against the standard `document.modelContext`.
+ *
+ * No argument is needed — the panel reads the standard surface that the
+ * toolkit's polyfill installs on import. If called more than once in the same
+ * runtime, the previous panel is removed first (so HMR re-runs cleanly).
+ *
+ * Outside the browser, or if no model context is present, this returns a no-op
+ * uninstaller — the panel needs `window`/`document`/`localStorage` and a
+ * `document.modelContext` to inspect.
+ *
+ * Returns an `uninstall` function that removes the panel and tears down its
+ * subscriptions.
+ */
+export function installDevPanel(options: DevPanelOptions = {}): () => void {
+  // SSR guard: the panel touches `document`, `localStorage`, and keyboard
+  // events. None of those exist outside the browser, so do nothing.
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return () => {
+      /* no-op uninstall */
+    };
+  }
+  const mc = getModelContextWithResources();
+  if (!mc) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[webmcp-toolkit dev panel] no document.modelContext found — is the toolkit imported?',
+    );
+    return () => {
+      /* no-op uninstall */
+    };
+  }
+  if (active) active.uninstall();
+  active = mountPanel(mc, options);
+  return active.uninstall;
+}
+
+// ───────── Module state (HMR singleton) ──────────────────────────────────
+
+let active: { uninstall: () => void } | null = null;
+
+// ───────── Constants ─────────────────────────────────────────────────────
+
+const STORAGE_PREFIX = 'webmcp-toolkit-dev-panel:args:';
+const MAX_LOG_ENTRIES = 200;
+const DEFAULT_SHORTCUT = 'Cmd+Shift+E';
+const TIER_ORDER: SideEffect[] = ['read', 'reversible', 'irreversible'];
+
+// ───────── Types ─────────────────────────────────────────────────────────
+
+type TabName = 'state' | 'capabilities' | 'log';
+
+interface LogEntry {
+  kind: 'call' | 'result' | 'state';
+  name: string;
+  payload: unknown;
+  ok?: boolean;
+  ts: number;
+}
+
+interface TabHandle {
+  element: HTMLElement;
+  onMount?: () => void;
+}
+
+// ───────── Mount ─────────────────────────────────────────────────────────
+
+function mountPanel(mc: ModelContextWithResources, opts: DevPanelOptions) {
+  // Host element lives at the very top of the z-stack so it floats above the
+  // app. Fixed at the viewport's bottom-right corner — the universal location
+  // for in-page dev tools — with a 16px inset.
+  const host = document.createElement('div');
+  host.setAttribute('data-edge-mcp-dev-panel', '');
+  host.style.cssText =
+    'position:fixed;bottom:16px;right:16px;z-index:2147483647;width:0;height:0;pointer-events:none;';
+
+  // Shadow DOM isolates the panel's styles from the host page.
+  const shadow = host.attachShadow({ mode: 'open' });
+  const style = document.createElement('style');
+  style.textContent = STYLES;
+  shadow.appendChild(style);
+
+  const panel = h('div', { class: 'panel' });
+  shadow.appendChild(panel);
+
+  // Visible affordance for opening the panel when closed. Without this,
+  // forgetting the keyboard shortcut leaves the panel discoverable only via
+  // DevTools — bad UX. The toggle hides itself when the panel is open.
+  const toggle = h(
+    'button',
+    {
+      class: 'toggle',
+      type: 'button',
+      title: 'Edge MCP dev panel — toggle',
+      'aria-label': 'Toggle Edge MCP dev panel',
+    },
+    'E',
+  );
+  shadow.appendChild(toggle);
+
+  // ---- Log + listeners -------------------------------------------------
+
+  const log: LogEntry[] = [];
+  const logListeners = new Set<(entry: LogEntry) => void>();
+
+  function addLog(entry: LogEntry): void {
+    log.unshift(entry);
+    if (log.length > MAX_LOG_ENTRIES) log.length = MAX_LOG_ENTRIES;
+    for (const fn of logListeners) fn(entry);
+  }
+
+  // ---- Tab content (built once, swapped in/out) -----------------------
+
+  const stateTab = buildStateTab(mc);
+  const capsTab = buildCapabilitiesTab(mc, addLog);
+  const logTab = buildLogTab(log, logListeners);
+
+  // ---- Header + tab bar ------------------------------------------------
+
+  let activeTab: TabName = 'capabilities';
+  const tabBar = h('div', { class: 'tabs' });
+  const tabContent = h('div', { class: 'content' });
+
+  function showTab(tab: TabName): void {
+    activeTab = tab;
+    Array.from(tabBar.querySelectorAll('.tab')).forEach((btn) => {
+      btn.classList.toggle('active', btn.getAttribute('data-tab') === tab);
+    });
+    tabContent.innerHTML = '';
+    const handle = tab === 'state' ? stateTab : tab === 'capabilities' ? capsTab : logTab;
+    tabContent.appendChild(handle.element);
+    handle.onMount?.();
+  }
+
+  const tabDefs: Array<{ name: TabName; label: string }> = [
+    { name: 'capabilities', label: 'Tools' },
+    { name: 'state', label: 'State' },
+    { name: 'log', label: 'Log' },
+  ];
+  for (const def of tabDefs) {
+    const btn = h(
+      'button',
+      { class: 'tab', 'data-tab': def.name, type: 'button' },
+      def.label,
+    );
+    btn.addEventListener('click', () => showTab(def.name));
+    tabBar.appendChild(btn);
+  }
+
+  const closeBtn = h('button', { class: 'close', type: 'button', title: 'Hide' }, '×');
+  closeBtn.addEventListener('click', () => setOpen(false));
+
+  const header = h(
+    'div',
+    { class: 'header' },
+    h('div', { class: 'title' }, 'WebMCP'),
+    tabBar,
+    closeBtn,
+  );
+
+  panel.appendChild(header);
+  panel.appendChild(tabContent);
+
+  // ---- Visibility / shortcut ------------------------------------------
+
+  let isOpen = !!opts.startOpen;
+
+  function setOpen(open: boolean): void {
+    isOpen = open;
+    panel.classList.toggle('open', open);
+    toggle.classList.toggle('hidden', open);
+    // Re-render the active tab on open so capabilities/state registered
+    // since the panel was last shown surface immediately. Renders are
+    // idempotent (each tab's onMount no-ops when nothing has changed) so
+    // existing form state isn't blown away.
+    if (open) {
+      const handle =
+        activeTab === 'state' ? stateTab : activeTab === 'capabilities' ? capsTab : logTab;
+      handle.onMount?.();
+    }
+  }
+
+  toggle.addEventListener('click', () => setOpen(!isOpen));
+
+  setOpen(isOpen);
+  showTab(activeTab);
+
+  const shortcut = parseShortcut(opts.shortcut ?? DEFAULT_SHORTCUT);
+  const onKey = (e: KeyboardEvent): void => {
+    if (matchShortcut(e, shortcut)) {
+      e.preventDefault();
+      setOpen(!isOpen);
+    }
+  };
+  document.addEventListener('keydown', onKey);
+
+  // ---- Live state updates → log + state tab in place ------------------
+  // Listen to the toolkit's `resourceupdated` event on document.modelContext
+  // (mirrors MCP's notifications/resources/updated). Payload is { uri, value }.
+
+  const onResourceUpdate = (evt: Event): void => {
+    const detail = (evt as CustomEvent<ResourceUpdate>).detail;
+    if (!detail) return;
+    addLog({ kind: 'state', name: detail.uri, payload: detail.value, ts: Date.now() });
+    // Only refresh the state tab when it's actually visible. When the user
+    // next switches to it, showTab() calls onMount which re-reads resources,
+    // so they see the current state then.
+    if (activeTab === 'state') {
+      stateTab.onMount?.();
+    }
+  };
+  mc.addEventListener('resourceupdated', onResourceUpdate);
+
+  // ---- Mount + report --------------------------------------------------
+
+  document.body.appendChild(host);
+  // eslint-disable-next-line no-console
+  console.info(
+    `[webmcp-toolkit dev panel] mounted (toggle: ${opts.shortcut ?? DEFAULT_SHORTCUT})`,
+  );
+
+  return {
+    uninstall: () => {
+      document.removeEventListener('keydown', onKey);
+      mc.removeEventListener('resourceupdated', onResourceUpdate);
+      logListeners.clear();
+      host.remove();
+      active = null;
+    },
+  };
+}
+
+// ───────── State tab ─────────────────────────────────────────────────────
+
+function buildStateTab(mc: ModelContextWithResources): TabHandle {
+  const container = h('div', { class: 'tab-pane' });
+  const empty = h(
+    'div',
+    { class: 'empty' },
+    'No live-state resources registered. ',
+    h(
+      'span',
+      { class: 'subtle' },
+      'Resources are reserved for out-of-band state — many apps need none.',
+    ),
+  );
+
+  // Per-resource rows, indexed by uri so we can update in place.
+  const rows = new Map<string, { row: HTMLElement; valueEl: HTMLElement; tsEl: HTMLElement }>();
+
+  function readAll(): Promise<Array<{ uri: string; name: string; value: unknown }>> {
+    // getResources() is metadata only (mirrors resources/list); read each value
+    // in parallel (mirrors resources/read). A failing read returns undefined.
+    const resources = mc.getResources();
+    return Promise.all(
+      resources.map(async (r) => ({ uri: r.uri, name: r.name, value: await mc.readResource(r.uri) })),
+    );
+  }
+
+  function render(): void {
+    container.innerHTML = '';
+    rows.clear();
+    void readAll().then((entries) => {
+      if (entries.length === 0) {
+        container.appendChild(empty);
+        return;
+      }
+      for (const e of entries.sort((a, b) => a.uri.localeCompare(b.uri))) {
+        appendResourceRow(e.uri, e.name, e.value);
+      }
+    });
+  }
+
+  function appendResourceRow(uri: string, name: string, value: unknown): void {
+    const valueEl = h('pre', { class: 'json' }, formatJson(value));
+    const tsEl = h('span', { class: 'ts' }, '(no push yet)');
+    const refresh = h('button', { class: 'mini', type: 'button' }, 'Refresh');
+    refresh.addEventListener('click', () => {
+      void mc.readResource(uri).then((v) => {
+        valueEl.textContent = formatJson(v);
+        tsEl.textContent = `refreshed ${formatTime(Date.now())}`;
+      });
+    });
+    const row = h(
+      'section',
+      { class: 'card' },
+      h(
+        'div',
+        { class: 'card-head' },
+        h(
+          'div',
+          { class: 'card-name' },
+          name,
+          h('span', { class: 'ts mono' }, `  ${uri}`),
+        ),
+        h('div', { class: 'card-meta' }, tsEl, refresh),
+      ),
+      valueEl,
+    );
+    container.appendChild(row);
+    rows.set(uri, { row, valueEl, tsEl });
+  }
+
+  // External hook — called whenever a resource push fires.
+  function refresh(): void {
+    void readAll().then((entries) => {
+      for (const e of entries) {
+        const existing = rows.get(e.uri);
+        if (existing) {
+          existing.valueEl.textContent = formatJson(e.value);
+          existing.tsEl.textContent = `updated ${formatTime(Date.now())}`;
+        } else {
+          // First time seeing this resource.
+          if (container.contains(empty)) container.removeChild(empty);
+          appendResourceRow(e.uri, e.name, e.value);
+        }
+      }
+    });
+  }
+
+  // Re-render whenever the tab is shown (catches newly registered resources).
+  return {
+    element: container,
+    onMount: () => {
+      if (rows.size === 0) render();
+      else refresh();
+    },
+  };
+}
+
+// ───────── Capabilities tab ──────────────────────────────────────────────
+
+function buildCapabilitiesTab(
+  mc: ModelContextWithResources,
+  addLog: (entry: LogEntry) => void,
+): TabHandle {
+  const container = h('div', { class: 'tab-pane' });
+  // Tracks which tool set was last rendered. Re-renders are skipped when the
+  // set hasn't changed, so user input in tool forms isn't blown away every
+  // time the tab is shown or the panel is reopened.
+  let lastRenderedSignature: string | null = null;
+
+  function render(): void {
+    void listToolViews(mc).then((tools) => {
+      // Include enough metadata that a change to a description, tier, flag, or
+      // schema triggers a re-render — without this the panel would show stale
+      // data after the customer tweaked their registration.
+      const signature = tools
+        .map(
+          (t) =>
+            [
+              t.name,
+              t.description,
+              t.tier,
+              t.idempotent ? '1' : '0',
+              JSON.stringify(t.inputSchema),
+            ].join('\x1f'),
+        )
+        .sort()
+        .join('\n');
+      if (signature === lastRenderedSignature) return;
+      lastRenderedSignature = signature;
+
+      container.innerHTML = '';
+      if (tools.length === 0) {
+        container.appendChild(
+          h(
+            'div',
+            { class: 'empty' },
+            'No tools registered yet. ',
+            h(
+              'span',
+              { class: 'subtle' },
+              'Register one (registerTool / registerStatefulTool) and reopen — the list refreshes.',
+            ),
+          ),
+        );
+        return;
+      }
+      // Group by tier, in safety order.
+      const byTier = new Map<SideEffect, ToolView[]>();
+      for (const tier of TIER_ORDER) byTier.set(tier, []);
+      for (const tool of tools) byTier.get(tool.tier)!.push(tool);
+      for (const tier of TIER_ORDER) {
+        const group = byTier.get(tier)!;
+        if (group.length === 0) continue;
+        container.appendChild(h('div', { class: 'group-head' }, tier));
+        group.sort((a, b) => a.name.localeCompare(b.name));
+        for (const tool of group) container.appendChild(renderToolCard(tool, mc, addLog));
+      }
+    });
+  }
+
+  return {
+    element: container,
+    onMount: render,
+  };
+}
+
+function renderToolCard(
+  tool: ToolView,
+  mc: ModelContextWithResources,
+  addLog: (entry: LogEntry) => void,
+): HTMLElement {
+  const form = buildForm(tool.inputSchema, loadArgs(tool.name));
+
+  const runBtn = h('button', { class: 'run', type: 'button' }, 'Run');
+  const resultEl = h('div', { class: 'result hidden' });
+
+  runBtn.addEventListener('click', () => {
+    const args = form.getValues();
+    saveArgs(tool.name, args);
+    runBtn.disabled = true;
+    runBtn.textContent = 'Running…';
+    addLog({ kind: 'call', name: tool.name, payload: args, ts: Date.now() });
+    void invokeTool(mc, tool.name, args).then((r) => {
+      runBtn.disabled = false;
+      runBtn.textContent = 'Run';
+      renderResult(resultEl, r, tool.tier);
+      addLog({
+        kind: 'result',
+        name: tool.name,
+        payload: r,
+        ok: r.ok,
+        ts: Date.now(),
+      });
+    });
+  });
+
+  const tierBadge = h('span', { class: `badge tier-${tool.tier}` }, tool.tier);
+  const flags: Node[] = [];
+  if (tool.idempotent) flags.push(h('span', { class: 'badge flag' }, 'idempotent'));
+
+  const header = h(
+    'div',
+    { class: 'card-head' },
+    h('div', { class: 'card-name mono' }, tool.name),
+    h('div', { class: 'card-meta' }, tierBadge, ...flags),
+  );
+
+  const desc = tool.description ? h('p', { class: 'desc' }, tool.description) : null;
+
+  const card = h('section', { class: 'card' }, header);
+  if (desc) card.appendChild(desc);
+  card.appendChild(form.element);
+  card.appendChild(h('div', { class: 'actions' }, runBtn));
+  card.appendChild(resultEl);
+
+  return card;
+}
+
+function renderResult(el: HTMLElement, r: InvokeOutcome, tier: SideEffect): void {
+  el.innerHTML = '';
+  el.classList.remove('hidden', 'ok', 'err');
+  if (r.ok) {
+    el.classList.add('ok');
+    el.appendChild(h('div', { class: 'result-head' }, `ok · ${tier}`));
+    // executeTool returns the tool's text output (a string), or null.
+    el.appendChild(h('pre', { class: 'json' }, r.output == null ? '(no output)' : r.output));
+  } else {
+    el.classList.add('err');
+    el.appendChild(h('div', { class: 'result-head' }, 'error'));
+    el.appendChild(h('pre', { class: 'json' }, r.error ?? 'unknown error'));
+  }
+}
+
+// ───────── Event log tab ─────────────────────────────────────────────────
+
+function buildLogTab(
+  log: LogEntry[],
+  listeners: Set<(entry: LogEntry) => void>,
+): TabHandle {
+  const list = h('div', { class: 'log' });
+  const empty = h(
+    'div',
+    { class: 'empty' },
+    'No activity yet. Run a capability or trigger a state change.',
+  );
+
+  function entryEl(e: LogEntry): HTMLElement {
+    const time = h('span', { class: 'log-ts' }, formatTime(e.ts));
+    const kind = h(
+      'span',
+      { class: `log-kind log-${e.kind}${e.kind === 'result' ? (e.ok ? ' ok' : ' err') : ''}` },
+      labelFor(e),
+    );
+    const name = h('span', { class: 'log-name mono' }, e.name);
+    const payload = h(
+      'pre',
+      { class: 'log-payload' },
+      truncate(formatJson(e.payload), 400),
+    );
+    return h('div', { class: 'log-entry' }, h('div', { class: 'log-row' }, time, kind, name), payload);
+  }
+
+  function render(): void {
+    list.innerHTML = '';
+    if (log.length === 0) {
+      list.appendChild(empty);
+      return;
+    }
+    for (const e of log) list.appendChild(entryEl(e));
+  }
+
+  // Subscribe to new entries.
+  listeners.add((entry) => {
+    if (list.contains(empty)) list.removeChild(empty);
+    list.insertBefore(entryEl(entry), list.firstChild);
+    // Trim DOM the same way we trim the in-memory log.
+    while (list.childElementCount > MAX_LOG_ENTRIES) list.lastElementChild?.remove();
+  });
+
+  return {
+    element: list,
+    onMount: render,
+  };
+}
+
+function labelFor(e: LogEntry): string {
+  if (e.kind === 'call') return 'CALL';
+  if (e.kind === 'state') return 'STATE';
+  return e.ok ? 'OK' : 'ERR';
+}
+
+// ───────── Form rendering (recursive, JSON-Schema-driven) ───────────────
+
+interface FormHandle {
+  element: HTMLElement;
+  getValues: () => Record<string, unknown>;
+}
+
+function buildForm(
+  schema: Record<string, unknown>,
+  initial: Record<string, unknown>,
+): FormHandle {
+  const form = h('div', { class: 'form' });
+  const type = getString(schema, 'type');
+
+  // Top-level must be an object schema; anything else falls back to a raw JSON
+  // input over the whole args payload.
+  if (type !== 'object') {
+    return rawJsonHandle(form, initial);
+  }
+
+  const props = getObject(schema, 'properties');
+  const required = new Set(getStringArray(schema, 'required'));
+
+  if (!props || Object.keys(props).length === 0) {
+    form.appendChild(
+      h('div', { class: 'subtle small' }, 'No arguments. Press Run.'),
+    );
+    return { element: form, getValues: () => ({}) };
+  }
+
+  const values: Record<string, unknown> = { ...initial };
+
+  for (const [key, fieldSchema] of Object.entries(props)) {
+    const field = buildField(key, fieldSchema as Record<string, unknown>, required.has(key), values[key], (v) => {
+      if (v === undefined) delete values[key];
+      else values[key] = v;
+    });
+    form.appendChild(field);
+  }
+
+  return {
+    element: form,
+    getValues: () => values,
+  };
+}
+
+function buildField(
+  key: string,
+  schema: Record<string, unknown>,
+  required: boolean,
+  initial: unknown,
+  onChange: (v: unknown) => void,
+): HTMLElement {
+  const type = getString(schema, 'type');
+  const description = getString(schema, 'description');
+  const enumValues = getArray(schema, 'enum');
+
+  const labelText = key + (required ? ' *' : '');
+  const wrap = h('div', { class: 'field' });
+  wrap.appendChild(h('label', { class: 'field-label' }, labelText));
+
+  let control: HTMLElement;
+
+  if (enumValues && enumValues.length > 0) {
+    control = enumControl(enumValues, initial, onChange);
+  } else if (type === 'string') {
+    control = stringControl(initial, onChange);
+  } else if (type === 'integer' || type === 'number') {
+    control = numberControl(type === 'integer', initial, onChange);
+  } else if (type === 'boolean') {
+    control = booleanControl(initial, onChange);
+  } else if (type === 'object') {
+    control = nestedObjectControl(schema, initial, onChange);
+  } else if (type === 'array') {
+    control = arrayControl(schema, initial, onChange);
+  } else {
+    control = jsonControl(initial, onChange);
+  }
+
+  wrap.appendChild(control);
+
+  if (description) {
+    wrap.appendChild(h('div', { class: 'hint' }, description));
+  }
+
+  return wrap;
+}
+
+function stringControl(initial: unknown, onChange: (v: unknown) => void): HTMLElement {
+  const input = h('input', { type: 'text', class: 'input' }) as HTMLInputElement;
+  if (typeof initial === 'string') input.value = initial;
+  input.addEventListener('input', () => {
+    onChange(input.value === '' ? undefined : input.value);
+  });
+  return input;
+}
+
+function numberControl(
+  integer: boolean,
+  initial: unknown,
+  onChange: (v: unknown) => void,
+): HTMLElement {
+  const input = h('input', { type: 'number', class: 'input' }) as HTMLInputElement;
+  if (integer) input.step = '1';
+  if (typeof initial === 'number') input.value = String(initial);
+  input.addEventListener('input', () => {
+    if (input.value === '') {
+      onChange(undefined);
+      return;
+    }
+    const n = integer ? parseInt(input.value, 10) : parseFloat(input.value);
+    onChange(Number.isNaN(n) ? undefined : n);
+  });
+  return input;
+}
+
+function booleanControl(initial: unknown, onChange: (v: unknown) => void): HTMLElement {
+  const input = h('input', { type: 'checkbox', class: 'check' }) as HTMLInputElement;
+  input.checked = !!initial;
+  // Always emit the current checked state.
+  onChange(input.checked);
+  input.addEventListener('change', () => onChange(input.checked));
+  return h('div', { class: 'check-wrap' }, input);
+}
+
+function enumControl(
+  values: unknown[],
+  initial: unknown,
+  onChange: (v: unknown) => void,
+): HTMLElement {
+  const select = h('select', { class: 'input' }) as HTMLSelectElement;
+  // Allow "unset" so an optional enum can be cleared.
+  const blank = h('option', { value: '' }, '— unset —') as HTMLOptionElement;
+  select.appendChild(blank);
+  for (const v of values) {
+    const opt = h('option', { value: String(v) }, String(v)) as HTMLOptionElement;
+    select.appendChild(opt);
+  }
+  if (initial !== undefined && initial !== null) select.value = String(initial);
+  select.addEventListener('change', () => {
+    if (select.value === '') onChange(undefined);
+    else {
+      // Match the original enum value's type where possible.
+      const match = values.find((v) => String(v) === select.value);
+      onChange(match);
+    }
+  });
+  return select;
+}
+
+function nestedObjectControl(
+  schema: Record<string, unknown>,
+  initial: unknown,
+  onChange: (v: unknown) => void,
+): HTMLElement {
+  const inner = buildForm(
+    schema,
+    initial && typeof initial === 'object' && !Array.isArray(initial)
+      ? (initial as Record<string, unknown>)
+      : {},
+  );
+  // Surface values out through the parent's onChange whenever an inner field
+  // changes — we re-walk the inner state.
+  const wrapper = h('div', { class: 'nested' }, inner.element);
+  // The inner form already mutates its `values` closure; we need to push it up
+  // on each mutation. Hook every input/change at this level.
+  wrapper.addEventListener('input', () => onChange(inner.getValues()));
+  wrapper.addEventListener('change', () => onChange(inner.getValues()));
+  // Initialize.
+  onChange(inner.getValues());
+  return wrapper;
+}
+
+function arrayControl(
+  schema: Record<string, unknown>,
+  initial: unknown,
+  onChange: (v: unknown) => void,
+): HTMLElement {
+  const items = getObject(schema, 'items');
+  const itemType = items ? getString(items, 'type') : undefined;
+
+  // Only render a row UI for primitive item types; anything else falls back
+  // to a raw JSON input over the whole array.
+  if (!items || !itemType || !['string', 'number', 'integer', 'boolean'].includes(itemType)) {
+    return jsonControl(initial, onChange);
+  }
+
+  const wrap = h('div', { class: 'array' });
+  const values: unknown[] = Array.isArray(initial) ? [...initial] : [];
+
+  function emit(): void {
+    onChange(values.length === 0 ? undefined : values);
+  }
+
+  function appendRow(index: number, value: unknown): void {
+    const row = h('div', { class: 'array-row' });
+    const field = buildField(
+      `[${index}]`,
+      items!,
+      false,
+      value,
+      (v) => {
+        values[index] = v;
+        emit();
+      },
+    );
+    const remove = h('button', { class: 'mini', type: 'button' }, '✕');
+    remove.addEventListener('click', () => {
+      values.splice(index, 1);
+      rebuild();
+    });
+    row.appendChild(field);
+    row.appendChild(remove);
+    wrap.insertBefore(row, addBtn);
+  }
+
+  function rebuild(): void {
+    // Clear rows, re-append everything (rebuilds correct indices).
+    Array.from(wrap.children).forEach((c) => {
+      if (c !== addBtn) wrap.removeChild(c);
+    });
+    values.forEach((v, i) => appendRow(i, v));
+    emit();
+  }
+
+  const addBtn = h('button', { class: 'mini add', type: 'button' }, '+ add');
+  addBtn.addEventListener('click', () => {
+    values.push(itemType === 'boolean' ? false : '');
+    rebuild();
+  });
+  wrap.appendChild(addBtn);
+  rebuild();
+
+  return wrap;
+}
+
+function jsonControl(initial: unknown, onChange: (v: unknown) => void): HTMLElement {
+  const ta = h('textarea', { class: 'input json-input', rows: '3' }) as HTMLTextAreaElement;
+  ta.value = initial === undefined ? '' : safeJson(initial);
+  ta.addEventListener('input', () => {
+    if (ta.value.trim() === '') {
+      onChange(undefined);
+      ta.classList.remove('invalid');
+      return;
+    }
+    try {
+      onChange(JSON.parse(ta.value));
+      ta.classList.remove('invalid');
+    } catch {
+      ta.classList.add('invalid');
+    }
+  });
+  return h(
+    'div',
+    { class: 'json-wrap' },
+    ta,
+    h('div', { class: 'hint' }, 'JSON — falls back to raw input for this schema fragment.'),
+  );
+}
+
+function rawJsonHandle(
+  form: HTMLElement,
+  initial: Record<string, unknown>,
+): FormHandle {
+  // Top-level args are not an object schema — give the developer a single JSON
+  // textarea over the whole args payload.
+  let value: unknown = initial;
+  const ta = h('textarea', { class: 'input json-input', rows: '6' }) as HTMLTextAreaElement;
+  ta.value = safeJson(initial);
+  ta.addEventListener('input', () => {
+    try {
+      value = JSON.parse(ta.value);
+      ta.classList.remove('invalid');
+    } catch {
+      ta.classList.add('invalid');
+    }
+  });
+  form.appendChild(
+    h(
+      'div',
+      { class: 'subtle small' },
+      'Top-level schema is not an object. Provide args as JSON.',
+    ),
+  );
+  form.appendChild(ta);
+  return {
+    element: form,
+    getValues: () => (value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {}),
+  };
+}
+
+// ───────── Storage ───────────────────────────────────────────────────────
+
+function loadArgs(name: string): Record<string, unknown> {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + name);
+    if (!raw) return {};
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* corrupt entry — ignore */
+  }
+  return {};
+}
+
+function saveArgs(name: string, args: unknown): void {
+  try {
+    localStorage.setItem(STORAGE_PREFIX + name, JSON.stringify(args));
+  } catch {
+    /* quota / private mode — ignore */
+  }
+}
+
+// ───────── Schema accessors (safe casts over `unknown`) ────────────────
+
+function getString(schema: Record<string, unknown>, key: string): string | undefined {
+  const v = schema[key];
+  return typeof v === 'string' ? v : undefined;
+}
+
+function getArray(schema: Record<string, unknown>, key: string): unknown[] | undefined {
+  const v = schema[key];
+  return Array.isArray(v) ? v : undefined;
+}
+
+function getStringArray(schema: Record<string, unknown>, key: string): string[] {
+  const arr = getArray(schema, key);
+  return arr ? arr.filter((x): x is string => typeof x === 'string') : [];
+}
+
+function getObject(
+  schema: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | undefined {
+  const v = schema[key];
+  if (v && typeof v === 'object' && !Array.isArray(v)) return v as Record<string, unknown>;
+  return undefined;
+}
+
+// ───────── Misc helpers ──────────────────────────────────────────────────
+
+function h<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  attrs?: Record<string, string>,
+  ...children: Array<Node | string>
+): HTMLElementTagNameMap[K] {
+  const el = document.createElement(tag);
+  if (attrs) {
+    for (const [k, v] of Object.entries(attrs)) {
+      if (k === 'class') el.className = v;
+      else el.setAttribute(k, v);
+    }
+  }
+  for (const c of children) {
+    if (c == null) continue;
+    el.appendChild(typeof c === 'string' ? document.createTextNode(c) : c);
+  }
+  return el;
+}
+
+function formatJson(v: unknown): string {
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+function safeJson(v: unknown): string {
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return '';
+  }
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + '\n… (truncated)';
+}
+
+function formatTime(ts: number): string {
+  const d = new Date(ts);
+  const pad = (n: number, w = 2): string => String(n).padStart(w, '0');
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(
+    d.getMilliseconds(),
+    3,
+  )}`;
+}
+
+// ───────── Keyboard shortcut ────────────────────────────────────────────
+
+interface ShortcutSpec {
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  alt: boolean;
+  key: string;
+}
+
+function parseShortcut(spec: string): ShortcutSpec {
+  const parts = spec.split('+').map((p) => p.trim());
+  const out: ShortcutSpec = { ctrl: false, meta: false, shift: false, alt: false, key: '' };
+  const isMac = typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+  for (const p of parts) {
+    const lower = p.toLowerCase();
+    if (lower === 'cmd') {
+      if (isMac) out.meta = true;
+      else out.ctrl = true;
+    } else if (lower === 'ctrl' || lower === 'control') out.ctrl = true;
+    else if (lower === 'shift') out.shift = true;
+    else if (lower === 'alt' || lower === 'option') out.alt = true;
+    else if (lower === 'meta' || lower === 'win') out.meta = true;
+    else out.key = lower;
+  }
+  return out;
+}
+
+function matchShortcut(e: KeyboardEvent, spec: ShortcutSpec): boolean {
+  return (
+    e.key.toLowerCase() === spec.key &&
+    e.ctrlKey === spec.ctrl &&
+    e.metaKey === spec.meta &&
+    e.shiftKey === spec.shift &&
+    e.altKey === spec.alt
+  );
+}
+
+// ───────── Styles ────────────────────────────────────────────────────────
+
+const STYLES = /* css */ `
+:host { all: initial; }
+* { box-sizing: border-box; font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.mono { font-family: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace; }
+
+.panel {
+  pointer-events: auto;
+  position: absolute;
+  bottom: 0;
+  right: 0;
+  width: 440px;
+  max-width: calc(100vw - 32px);
+  height: 600px;
+  max-height: 80vh;
+  background: #14161c;
+  color: #e6e8ed;
+  border: 1px solid #2a2f3b;
+  border-radius: 10px;
+  box-shadow: 0 14px 40px rgba(0,0,0,.35);
+  display: none;
+  flex-direction: column;
+  overflow: hidden;
+  font-size: 12.5px;
+  line-height: 1.45;
+}
+.panel.open { display: flex; }
+
+/* Toggle — always visible when the panel is closed, hidden when open. */
+.toggle {
+  pointer-events: auto;
+  position: absolute;
+  bottom: 0;
+  right: 0;
+  width: 36px;
+  height: 36px;
+  border-radius: 50%;
+  background: #14161c;
+  border: 1px solid #2a2f3b;
+  color: #cfd3dc;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: .04em;
+  font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 12px rgba(0,0,0,.25);
+  opacity: .7;
+  transition: opacity .12s ease, transform .12s ease;
+}
+.toggle:hover { opacity: 1; transform: scale(1.05); }
+.toggle.hidden { display: none; }
+
+/* Header */
+.header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-bottom: 1px solid #232732;
+  background: #181b23;
+}
+.title {
+  font-weight: 600;
+  letter-spacing: .02em;
+  font-size: 12px;
+  color: #cfd3dc;
+}
+.tabs { display: flex; gap: 2px; margin-left: 6px; flex: 1; }
+.tab {
+  background: transparent;
+  border: 1px solid transparent;
+  color: #9aa0ac;
+  padding: 4px 9px;
+  font-size: 12px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+.tab:hover { color: #cfd3dc; }
+.tab.active { background: #232732; color: #fff; }
+.close {
+  background: transparent;
+  border: 0;
+  color: #9aa0ac;
+  font-size: 18px;
+  line-height: 1;
+  padding: 0 4px;
+  cursor: pointer;
+}
+.close:hover { color: #fff; }
+
+/* Content */
+.content {
+  flex: 1;
+  overflow: auto;
+  padding: 10px;
+}
+.tab-pane { display: flex; flex-direction: column; gap: 10px; }
+.empty {
+  padding: 16px;
+  color: #9aa0ac;
+  text-align: center;
+  border: 1px dashed #2a2f3b;
+  border-radius: 8px;
+}
+.subtle { color: #6e7382; }
+.small { font-size: 11.5px; }
+.group-head {
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  font-size: 10px;
+  color: #6e7382;
+  padding: 6px 2px 0;
+}
+
+/* Cards (capabilities + state providers) */
+.card {
+  background: #181b23;
+  border: 1px solid #232732;
+  border-radius: 8px;
+  padding: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.card-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+.card-name { font-weight: 600; color: #e6e8ed; font-size: 13px; }
+.card-meta { display: flex; align-items: center; gap: 6px; }
+.desc { margin: 0; color: #9aa0ac; font-size: 12px; }
+.ts { color: #6e7382; font-size: 11px; }
+
+/* Badges */
+.badge {
+  font-size: 10.5px;
+  padding: 2px 6px;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+  background: #232732;
+  color: #cfd3dc;
+}
+.tier-read { background: #1e2e2a; color: #6ee0b8; }
+.tier-reversible { background: #2e2916; color: #f0c66a; }
+.tier-irreversible { background: #2e1a1a; color: #f08585; }
+.flag { background: #1b2535; color: #79a8e6; }
+
+/* Forms */
+.form { display: flex; flex-direction: column; gap: 8px; }
+.field { display: flex; flex-direction: column; gap: 3px; }
+.field-label { font-size: 11.5px; color: #cfd3dc; }
+.hint { font-size: 11px; color: #6e7382; }
+.input {
+  background: #0e1015;
+  color: #e6e8ed;
+  border: 1px solid #2a2f3b;
+  border-radius: 6px;
+  padding: 5px 8px;
+  font-size: 12.5px;
+  outline: none;
+  width: 100%;
+}
+.input:focus { border-color: #4d80ff; }
+.input.invalid { border-color: #f08585; }
+.json-wrap { display: flex; flex-direction: column; gap: 3px; }
+.json-input { font-family: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace; }
+.check-wrap { padding-top: 2px; }
+.check {
+  width: 14px; height: 14px; accent-color: #4d80ff;
+}
+.nested {
+  border-left: 2px solid #2a2f3b;
+  padding-left: 8px;
+}
+.array { display: flex; flex-direction: column; gap: 4px; }
+.array-row { display: flex; align-items: flex-end; gap: 6px; }
+.array-row .field { flex: 1; }
+.mini {
+  background: #232732;
+  color: #cfd3dc;
+  border: 1px solid #2a2f3b;
+  border-radius: 5px;
+  font-size: 11px;
+  padding: 3px 7px;
+  cursor: pointer;
+}
+.mini:hover { background: #2a2f3b; }
+
+/* Actions */
+.actions { display: flex; justify-content: flex-end; }
+.run {
+  background: #4d80ff;
+  color: #fff;
+  border: 0;
+  border-radius: 6px;
+  padding: 5px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+}
+.run:hover { background: #5e8eff; }
+.run:disabled { background: #34406c; cursor: progress; }
+
+/* Result */
+.result {
+  border-top: 1px dashed #232732;
+  padding-top: 6px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.result.hidden { display: none; }
+.result-head {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+}
+.result.ok .result-head { color: #6ee0b8; }
+.result.err .result-head { color: #f08585; }
+
+/* JSON */
+.json {
+  margin: 0;
+  padding: 6px 8px;
+  background: #0e1015;
+  border: 1px solid #232732;
+  border-radius: 6px;
+  font-family: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
+  font-size: 11.5px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 220px;
+  overflow: auto;
+  color: #cfd3dc;
+}
+
+/* Log */
+.log { display: flex; flex-direction: column; gap: 6px; }
+.log-entry {
+  background: #181b23;
+  border: 1px solid #232732;
+  border-radius: 6px;
+  padding: 6px 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.log-row { display: flex; align-items: center; gap: 6px; }
+.log-ts { color: #6e7382; font-size: 10.5px; font-family: ui-monospace, monospace; }
+.log-kind {
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: #232732;
+  color: #cfd3dc;
+}
+.log-call { background: #1b2535; color: #79a8e6; }
+.log-state { background: #2e2916; color: #f0c66a; }
+.log-result.ok { background: #1e2e2a; color: #6ee0b8; }
+.log-result.err { background: #2e1a1a; color: #f08585; }
+.log-name { font-size: 12px; }
+.log-payload {
+  margin: 0;
+  font-family: ui-monospace, monospace;
+  font-size: 11px;
+  color: #9aa0ac;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 120px;
+  overflow: auto;
+}
+`;