@mihcm/ai-ui

Zod-validated component descriptors and a safe renderer for AI-generated MiHCM UI.

This package is the only approved path for rendering model-generated UI. It keeps AI output constrained to an explicit component allowlist and validates every descriptor before render.

Current release

Current published version: 0.16.0.

This release tracks @mihcm/[email protected]. Descriptor validation and the renderer allowlist remain unchanged; the package stays aligned with the current UI surface (including the rebuilt sonner-backed Toast and the polished MainSidebar with whitelabel colorScheme support) and its dependency train.

Install

pnpm add @mihcm/ai-ui @mihcm/ui zod

Usage

import { renderComponentDescriptor, componentDescriptorSchema } from '@mihcm/ai-ui';

const descriptor = componentDescriptorSchema.parse({
  component: 'Button',
  props: {
    children: 'Approve request',
    variant: 'default',
  },
});

export function GeneratedAction() {
  return renderComponentDescriptor(descriptor);
}

What is included

• Zod schemas for supported MiHCM component descriptors.
• Shared safe schemas for text, class names, relative URLs, and HTTPS image URLs.
• Renderer switch for allowlisted components only.
• AI tool descriptions that reflect the live allowlist.
• Coverage governance that marks each UI primitive as supported, host-composed, or blocked.

Recent additions and fixes

• Added the Link descriptor and renderer case with safe relative, hash, or HTTPS href validation.
• Added semantic Text.as support for safe span, paragraph, label, emphasis, and heading tags.
• Updated coverage guidance so Button, Link, Text, and form-like descriptors preserve native HTML semantics and accessible names.
• Extended the SectionHeader descriptor with safe enum-backed spacing, surface, border, radius, and shadow props; raw class names remain host-owned.
• Added AI_UI_COMPONENT_COVERAGE so every UI primitive has an explicit AI-UI decision.
• Added the coverage test script that verifies coverage, schema files, renderer cases, and tool-prompt allowlist sync.
• Tightened URL validation for model-controlled Avatar images and Breadcrumb hrefs.
• Added shared safe URL schemas to prevent raw z.string().url() from allowing unsafe schemes.
• Updated tool descriptions to derive from the live allowlist instead of stale hardcoded examples.

Security contract

• Never use eval, new Function, dynamic imports, or model-provided component paths.
• Never render raw HTML from a descriptor.
• Never accept model-controlled filesystem paths.
• Only render components in the explicit allowlist.
• Validate descriptors with Zod before rendering.
• Validate navigation hrefs with safeHrefSchema; reject javascript:, protocol-relative URLs, and arbitrary schemes.
• Keep generated text structural: use Text.as for headings and paragraphs instead of relying on visual size alone.
• Keep unsafe or host-owned primitives marked as host-composed or blocked.

Supported vs host-composed

supported means a model may emit the descriptor directly.

host-composed means the host application owns state, async data, callbacks, or layout context and may compose the component itself after validating model intent.

blocked means the primitive is not safe or useful for model-controlled render output.

Maintainer checklist

When changing UI primitives:

1. Update AI_UI_COMPONENT_COVERAGE.
2. Add or update the Zod schema for supported descriptors.
3. Add or update the renderer switch case.
4. Keep model-controlled URLs on safe relative/hash/HTTPS schemas.
5. Run the AI-UI coverage test.
6. Update docs and add a changeset before publishing.

Build and test

cd src
pnpm -F @mihcm/ai-ui build
pnpm -F @mihcm/ai-ui typecheck
pnpm -F @mihcm/ai-ui test

Related docs

• src/apps/docs/app/ai-ui/page.mdx
• docs/security-playbook.md
• docs/CONVENTIONS.md