Generate UI safely

Use @aetherui-kit/agent when a model chooses interface elements at runtime. It accepts constrained JSON data rather than HTML or executable event handlers.

pnpm add @aetherui-kit/core @aetherui-kit/agent @aetherui-kit/tokens

Register only the elements the experience permits, then apply the same allowlist at the rendering seam:

import { defineAeButton, defineAeInput } from '@aetherui-kit/core';
import { renderAgentUi } from '@aetherui-kit/agent';
import '@aetherui-kit/tokens/light.css';

defineAeButton();
defineAeInput();

renderAgentUi(document.querySelector('#agent-surface')!, modelOutput, {
  allowedComponents: ['ae-button', 'ae-input'],
  maxDepth: 6,
  maxNodes: 30,
  onAction(action) {
    if (action.actionId === 'save-profile') saveProfile();
  },
});

Structured model output

Constrain model output with agent-ui.schema.json. The runtime validator adds semantic checks against the generated component catalog:

{
  "version": "1",
  "root": {
    "component": "ae-button",
    "id": "save",
    "props": { "variant": "primary" },
    "children": ["Save"],
    "actions": { "ae-button-click": "save-profile" }
  }
}

An action maps a documented custom event to an application-owned identifier. The model cannot provide callback code. Applications retain authority over what each identifier does.

Validation policy

validateAgentUi and renderAgentUi reject:

• unknown or policy-excluded elements;
• unknown fields on the document or its nodes;
• properties and events absent from the canonical component catalog;
• executable URL protocols;
• empty action identifiers;
• documents over the configured depth or node limits;
• cyclic or non-JSON property values.

The renderer builds DOM nodes with document.createElement, assigns validated properties, and never uses innerHTML.

maxNodes counts elements and text children, including the root and empty strings. Its default is 100, and the returned nodeCount follows the same rule. Component shadow DOM is excluded. maxDepth counts nested components, with the root at depth 1 (default limit: 12); maxPropertyDepth limits JSON property nesting (default: 32). Validation stops visiting siblings after exceeding the node budget and completes before replacing existing content. Bound incoming JSON size before parsing it as well.

Machine-readable references

• component-catalog.json contains properties, events, slots, CSS parts, and CSS properties.
• agent-ui.schema.json constrains structured model output.
• llms.txt provides a compact model-oriented index.
• llms-full.txt contains the complete generated interface reference.

MCP discovery

@aetherui-kit/mcp exposes the same catalog and schema to MCP hosts, plus read-only tools for focused component lookup and agent document validation:

{
  "mcpServers": {
    "aetherui": {
      "command": "npx",
      "args": ["-y", "@aetherui-kit/mcp"]
    }
  }
}

The MCP server does not render documents, execute generated handlers, or modify projects.