@adia-ai/a2ui 0.8.37

package/prop-apply.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The attribute-vs-property mapping AdiaUI components expect for one
+ * already-resolved prop value. Shared by A2UIRenderer and the genui
+ * WidgetAdapter (packages/genui/adia-adapter) — see prop-apply.js.
+ */
+
+/** Kebab-cases `name` for attribute use, except HTML-standard single-token
+ *  names (autocomplete, tabindex, …), which stay lowercase-unhyphenated. */
+export declare function toAttr(name: string): string;
+
+/** Applies one already-resolved prop value to `el` per AdiaUI's
+ *  attribute-vs-property policy. No diffing, no binding resolution. */
+export declare function applyResolvedProp(el: Element, key: string, value: unknown): void;

package/prop-apply.js

@@ -0,0 +1,113 @@
+/**
+ * prop-apply.js — the attribute-vs-property mapping AdiaUI components expect
+ * for ONE already-resolved prop value. Extracted from A2UIRenderer's
+ * `#applyProps` (renderer.js) so the same policy is shared, rather than
+ * forked, by:
+ *   - A2UIRenderer (the legacy DOM-string streaming renderer), and
+ *   - the genui WidgetAdapter (packages/genui/adia-adapter) — its `setProp`
+ *     receives one resolved value per call, with no diffing to do, so this
+ *     module is exactly the slice it needs.
+ *
+ * Policy encoded here (do not duplicate elsewhere — fix it once, here):
+ *   - `style` (string) → `el.style.cssText`.
+ *   - JS-property props (data/columns/options/itemRenderer/textContent) →
+ *     set as a JS property, not an attribute — components read these as
+ *     arrays/objects, not markup strings. `textContent` on a non-text-bearing
+ *     tag (a container like card-ui/alert-ui) is redirected to the `text=`
+ *     attribute instead of `el.textContent = …`, which would wipe slotted +
+ *     appended children.
+ *   - A JSON-looking string ('[' / '{' prefixed) destined for a JS-property
+ *     prop is parsed — corpus templates encode `data`/`columns` as JSON
+ *     strings; components expect arrays.
+ *   - boolean → attribute presence (`setAttribute(key, '')` / removeAttribute).
+ *   - everything else → `setAttribute(toAttr(key), String(value))`.
+ */
+
+// Props components read as a JS property (array/object), never a markup
+// string — see #JS_PROPS in renderer.js (kept in sync; this IS that set now).
+const JS_PROPS = new Set(['data', 'columns', 'options', 'itemRenderer', 'textContent']);
+
+// Tags where `el.textContent = value` is safe — pure text-bearing leaves.
+// On a container, textContent would wipe slotted + appended children.
+const TEXT_TAG_OK = new Set([
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'p', 'small', 'span', 'em', 'strong', 'code',
+  'text-ui',
+  'kbd-ui', // "Content via innerHTML", no text= attribute fallback (TKT-0025)
+]);
+
+// HTML-standard single-token attribute names (all-lowercase in the HTML
+// spec) — passed through unchanged rather than naive-kebabbed, which would
+// mangle e.g. autoComplete → "auto-complete" (HTML attr is "autocomplete").
+const HTML_LOWERCASE_ATTRS = new Set([
+  'autocomplete', 'autofocus', 'autocapitalize', 'autocorrect',
+  'inputmode', 'enterkeyhint', 'spellcheck',
+  'maxlength', 'minlength', 'readonly', 'novalidate', 'formnovalidate',
+  'formaction', 'formenctype', 'formmethod', 'formtarget',
+  'multiple', 'pattern', 'placeholder', 'required',
+  'tabindex', 'accesskey',
+  'autoplay', 'autopictureinpicture', 'controls', 'crossorigin',
+  'disablepictureinpicture', 'disableremoteplayback',
+  'loop', 'muted', 'playsinline', 'preload',
+  'srcset', 'srcdoc', 'srclang', 'sizes', 'loading',
+  'decoding', 'fetchpriority', 'ismap', 'usemap',
+  'hreflang', 'referrerpolicy', 'download',
+  'contenteditable', 'contextmenu', 'draggable',
+  'dirname', 'colspan', 'rowspan', 'headers',
+  'allowfullscreen', 'allowpaymentrequest',
+  'itemid', 'itemprop', 'itemref', 'itemscope', 'itemtype',
+  'nomodule', 'nonce',
+]);
+
+/**
+ * Kebab-cases a camelCase prop name for attribute use, except for the
+ * HTML-standard single-token names above, which stay lowercase-unhyphenated.
+ */
+export function toAttr(name) {
+  if (HTML_LOWERCASE_ATTRS.has(name.toLowerCase())) return name.toLowerCase();
+  return name.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/**
+ * Applies one already-resolved prop value to `el` per AdiaUI's
+ * attribute-vs-property policy. No diffing, no binding resolution — the
+ * caller has already decided this value needs writing.
+ */
+export function applyResolvedProp(el, key, value) {
+  if (key === 'style' && typeof value === 'string') {
+    el.style.cssText = value;
+    return;
+  }
+
+  if (JS_PROPS.has(key) && value != null) {
+    if (key === 'textContent' && !TEXT_TAG_OK.has(el.localName)) {
+      el.setAttribute('text', String(value));
+      return;
+    }
+    let v = value;
+    if (typeof v === 'string' && (v.startsWith('[') || v.startsWith('{'))) {
+      try { v = JSON.parse(v); } catch { /* keep as string on parse failure */ }
+    }
+    el[key] = v;
+    return;
+  }
+
+  if (typeof value === 'boolean') {
+    // toAttr(key) — not the raw camelCase key. Every prior boolean prop
+    // through this path (disabled/checked/…) is a single lowercase word,
+    // so toAttr is the identity and this was invisible; allowEmpty is the
+    // first camelCase boolean, and the raw-key branch wrote
+    // `allowempty=""` while segmented-ui observes `allow-empty` — the
+    // property never flipped and the connect-time self-select still ran
+    // (gh#693 follow-up, caught in review before merge).
+    if (value) el.setAttribute(toAttr(key), '');
+    else el.removeAttribute(toAttr(key));
+    return;
+  }
+
+  if (value != null) {
+    el.setAttribute(toAttr(key), String(value));
+  } else {
+    el.removeAttribute(toAttr(key));
+  }
+}

package/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A2UI Registry — maps A2UI type names to AdiaUI custom element tag names.
+ */
+
+/** The global registry Map from A2UI type name → custom element tag name. */
+export declare const registry: Map<string, string>;
+
+/**
+ * Resolve an A2UI component type to an AdiaUI tag name.
+ * Returns null (not undefined) when the type is unknown.
+ */
+export declare function resolveTag(type: string): string | null;
+
+/**
+ * Register a custom component type mapping.
+ */
+export declare function registerType(type: string, tagName: string): void;

package/registry.js

@@ -0,0 +1,418 @@
+/**
+ * A2UI Registry — maps A2UI type names to AdiaUI custom element tag names.
+ *
+ * Usage:
+ *   import { registry, resolveTag } from './registry.js';
+ *   resolveTag('Button')        // → 'button-ui'
+ *   resolveTag('ChoicePicker')  // → 'select-ui'
+ *   resolveTag('Toggle')        // → 'switch-ui'
+ */
+
+export const registry = new Map([
+
+  // ══════════════════════════════════════════════════════
+  // A2UI Protocol Types (standard catalog)
+  // ══════════════════════════════════════════════════════
+
+  // Layout
+  ['Row',              'row-ui'],
+  ['Column',           'col-ui'],
+  ['List',             'list-ui'],
+  ['ListItem',         'list-item-ui'],
+  ['Grid',             'grid-ui'],
+  ['Stack',            'stack-ui'],
+  ['Block',            'block-ui'],
+
+  // Display
+  ['Text',             'text-ui'],
+  ['Image',            'image-ui'],
+  ['Icon',             'icon-ui'],
+  ['Divider',          'divider-ui'],
+  ['Badge',            'badge-ui'],
+  ['Avatar',           'avatar-ui'],
+  ['AvatarGroup',      'avatar-group-ui'],
+  ['Progress',         'progress-ui'],
+  ['ProgressRow',      'progress-row-ui'],
+  ['DateRangePicker',  'date-range-picker-ui'],
+  ['DatetimePicker',   'datetime-picker-ui'],
+  ['CalendarGrid',     'calendar-grid-ui'],
+  ['CalendarPicker',   'calendar-picker-ui'],
+  ['Combobox',         'combobox-ui'],
+  ['Skeleton',         'skeleton-ui'],
+  ['Stepper',          'stepper-ui'],
+  ['StepperItem',      'stepper-item-ui'],
+  ['Tour',             'tour-ui'],
+  ['TourStep',         'tour-step-ui'],
+  ['IntegrationCard',  'integration-card-ui'],
+  ['Code',             'code-ui'],
+  ['Stat',             'stat-ui'],
+  ['EmptyState',       'empty-state-ui'],
+
+  // Input
+  ['Input',            'input-ui'],
+  ['TextField',        'input-ui'],
+  ['TextArea',         'textarea-ui'],
+  ['Field',            'field-ui'],
+  ['CheckBox',         'check-ui'],
+  ['Toggle',           'switch-ui'],
+  ['Switch',           'switch-ui'],
+  ['Slider',           'slider-ui'],
+  ['Range',            'range-ui'],
+  ['Rating',           'rating-ui'],
+  ['ChoicePicker',     'select-ui'],
+  ['Select',           'select-ui'],
+  ['Radio',            'radio-ui'],
+  ['RadioGroup',       'radio-group-ui'],
+  ['DateTimeInput',    'calendar-picker-ui'],
+  ['CalendarPicker',   'calendar-picker-ui'],
+  ['ColorPicker',      'color-picker-ui'],
+  // Search deprecated — use Input type="search" prefix="magnifying-glass"
+  ['Upload',           'upload-ui'],
+  ['OtpInput',         'otp-input-ui'],
+
+  // Action
+  ['Button',           'button-ui'],
+
+  // System State
+  ['LoadingIndicator', 'progress-ui'],
+  ['ErrorContainer',   'card-ui'],
+
+  // Container
+  ['Card',             'card-ui'],
+  ['Tabs',             'tabs-ui'],
+  ['Tab',              'tab-ui'],
+  ['Panel',            'pane-ui'],
+  ['Pane',             'pane-ui'],
+  ['Modal',            'modal-ui'],
+  ['Dialog',           'modal-ui'],
+  ['Drawer',           'drawer-ui'],
+  ['Toast',            'toast-ui'],
+  ['AnchorBar',        'anchor-bar-ui'],
+  ['Popover',          'popover-ui'],
+  ['Accordion',        'accordion-ui'],
+  ['AccordionItem',    'accordion-item-ui'],
+  ['Alert',            'alert-ui'],
+  ['Tooltip',          'tooltip-ui'],
+  ['Menu',             'menu-ui'],
+
+  // Card children (native HTML elements styled by card.css)
+  ['Section',          'section'],
+  ['Header',           'header'],
+  ['Footer',           'footer'],
+
+  // Agent / Specialized
+  ['Stream',           'stream-ui'],
+  ['Table',            'table-ui'],
+  ['ColDef',           'col-def'],   // declarative column definition child of table-ui
+  ['Chart',            'chart-ui'],
+  ['Embed',            'embed-ui'],
+  ['Swiper',           'swiper-ui'],
+  ['Slideshow',        'swiper-ui'],
+  ['Carousel',         'swiper-ui'],
+
+  // Navigation
+  ['Breadcrumb',       'breadcrumb-ui'],
+  ['Link',             'link-ui'],
+  ['Anchor',           'link-ui'],
+  ['Hyperlink',        'link-ui'],
+  ['NavLink',          'link-ui'],
+  ['Nav',              'nav-ui'],
+  ['NavGroup',         'nav-group-ui'],
+  ['NavItem',          'nav-item-ui'],
+  ['Noodles',          'noodles-ui'],
+  ['Pagination',       'pagination-ui'],
+  ['SegmentedControl', 'segmented-ui'],
+  ['Segment',          'segment-ui'],
+  ['ToggleGroup',      'toggle-group-ui'],
+
+  // Utility
+  ['Command',          'command-ui'],
+  ['Kbd',              'kbd-ui'],
+  ['Toolbar',          'toolbar-ui'],
+  // gh#535 — missing entry made toolbar-group-ui an UNKNOWN tag: the docs
+  // transpiler Column-wrapped every group, so the floating bulk-action bar
+  // rendered as vertical col-ui stacks on its site route. Catalog already
+  // carries ToolbarGroup.
+  ['ToolbarGroup',     'toolbar-group-ui'],
+  ['Tag',              'tag-ui'],
+  ['Timeline',         'timeline-ui'],
+  ['TimelineItem',     'timeline-item-ui'],
+
+  // ══════════════════════════════════════════════════════
+  // AgentUI Aliases (backwards compat with -ui tags)
+  // ══════════════════════════════════════════════════════
+  ['button-ui',        'button-ui'],
+  ['card-ui',          'card-ui'],
+  ['text-ui',          'text-ui'],
+  ['input-ui',         'input-ui'],
+  ['text-field-ui',    'input-ui'],
+  ['select-ui',        'select-ui'],
+  ['toggle-ui',        'switch-ui'],
+  ['check-ui',         'check-ui'],
+  ['slider-ui',        'slider-ui'],
+  ['badge-ui',         'badge-ui'],
+  ['avatar-ui',        'avatar-ui'],
+  ['icon-ui',          'icon-ui'],
+  ['image-ui',         'image-ui'],
+  ['divider-ui',       'divider-ui'],
+  ['progress-ui',      'progress-ui'],
+  ['skeleton-ui',      'skeleton-ui'],
+  ['tabs-ui',          'tabs-ui'],
+  ['tab-ui',           'tab-ui'],
+  ['modal-ui',         'modal-ui'],
+  ['dialog-ui',        'modal-ui'],
+  ['drawer-ui',        'drawer-ui'],
+  ['toast-ui',         'toast-ui'],
+  ['popover-ui',       'popover-ui'],
+  ['panel-ui',         'pane-ui'],
+  ['accordion-ui',     'accordion-ui'],
+  ['alert-ui',         'alert-ui'],
+  ['tooltip-ui',       'tooltip-ui'],
+  ['menu-ui',          'menu-ui'],
+  ['table-ui',         'table-ui'],
+  ['chart-ui',         'chart-ui'],
+  ['code-ui',          'code-ui'],
+  ['textarea-ui',      'textarea-ui'],
+  ['radio-ui',         'radio-ui'],
+  ['tag-ui',           'tag-ui'],
+  ['search-ui',        'search-ui'],
+  ['upload-ui',        'upload-ui'],
+  ['breadcrumb-ui',    'breadcrumb-ui'],
+  ['link-ui',          'link-ui'],
+  ['nav-ui',           'nav-ui'],
+  ['noodles-ui',       'noodles-ui'],
+  ['pagination-ui',    'pagination-ui'],
+  ['segmented-control-ui', 'segmented-ui'],
+  ['segment-ui',       'segment-ui'],
+  ['command-ui',       'command-ui'],
+  ['calendar-picker-ui', 'calendar-picker-ui'],
+  ['color-picker-ui',  'color-picker-ui'],
+  ['kbd-ui',           'kbd-ui'],
+  ['toolbar-ui',       'toolbar-ui'],
+  ['otp-input-ui',     'otp-input-ui'],
+  ['embed-ui',         'embed-ui'],
+  ['stream-ui',        'stream-ui'],
+  ['row-ui',           'row-ui'],
+  ['col-ui',           'col-ui'],
+  ['grid-ui',          'grid-ui'],
+  ['stack-ui',         'stack-ui'],
+  ['block-ui',         'block-ui'],
+  ['list-ui',          'list-ui'],
+  ['range-ui',         'range-ui'],
+  ['datetime-ui',      'calendar-picker-ui'],
+  ['timeline-ui',      'timeline-ui'],
+  ['timeline-item-ui', 'timeline-item-ui'],
+  ['avatar-group-ui',  'avatar-group-ui'],
+
+  // Aliases (alternate names)
+  ['Keyboard',         'kbd-ui'],
+  ['DatePicker',       'calendar-picker-ui'],
+  ['CommandPalette',   'command-ui'],
+  ['FormContainer',    'form'],  // §45 — transpiler maps <form> → FormContainer; no form-ui component exists, so render as native <form>
+  ['Sidebar',          'admin-sidebar'], // §48 — transpiler maps <aside> → Sidebar; routed to the AdminSidebar web-module (packages/web-modules/shell/admin-sidebar/). Per-user directive in §49: prefer admin-sidebar over native <aside> for sidebar affordances.
+  ['Segmented',        'segmented-ui'],
+  ['OTP',              'otp-input-ui'],
+
+  // Missing PascalCase entries discovered by verify:corpus (§39, 2026-05-12).
+  // Composition corpus used these names; registry didn't map them so the
+  // renderer would have silently dropped these components.
+  ['Textarea',         'textarea-ui'],          // case alias for TextArea
+  ['RichText',         'richtext-ui'],
+  ['Richtext',         'richtext-ui'],          // case alias
+  ['DescriptionList',  'description-list-ui'],
+  ['ActionItem',       'action-item-ui'],
+  ['ActionList',       'action-list-ui'],
+  ['Inspector',        'inspector-ui'],
+  ['Heatmap',          'heatmap-ui'],
+  // §176 (v0.5.5): removed legacy `['Chat', 'chat-ui']` alias. Renamed
+  // to chat-thread-ui in pre-0.2.0; zero usage in current codebase
+  // (verified with `grep -rE '<chat-ui|\\bChat\\b\\s*\\(' packages apps`
+  // returning no real callers). Was a §175 baseline orphan; removing
+  // the registry entry closes it cleanly.
+  ['ChatThread',       'chat-thread'],          // §49 — re-routed to the chat web-module (was: chat-thread-ui primitive). The module owns scroll-to-bottom + streaming; primitive remains accessible via bare `chat-thread-ui` tag.
+  ['ChatInput',        'chat-input-ui'],
+  ['OptionCard',       'option-card-ui'],
+  ['Option',           'option-card-ui'],       // bare Option → option-card-ui
+
+  // §49 — web-module catalog mappings (packages/web-modules/<cluster>/).
+  // These are module-tier components that compose primitives into full
+  // surface affordances (page shells, sidebars, chat surfaces, editor
+  // surfaces, theme panel). Without these entries, A2UI corpus records
+  // emitting any of them produce unknown-component criticals (same
+  // pattern caught reactively for FormContainer §45 + Sidebar §48).
+  // Discovered via a transpiler-vs-registry audit across §49.
+
+  // Admin shell cluster — chrome surfaces for SaaS admin/dashboard surfaces
+  ['AdminCommand',     'admin-command'],
+  ['AdminContent',     'admin-content'],
+  ['AdminPage',        'admin-page'],
+  ['AdminPageBody',    'admin-page-body'],
+  ['AdminPageHeader',  'admin-page-header'],
+  ['AdminScroll',      'admin-scroll'],
+  ['AdminShell',       'admin-shell'],
+  ['AdminSidebar',     'admin-sidebar'],         // canonical PascalCase mapping; the Sidebar alias above resolves through this
+  ['AdminStatusbar',   'admin-statusbar'],
+  ['AdminTopbar',      'admin-topbar'],
+
+  // Chat cluster — LLM-streaming conversation surfaces
+  ['ChatComposer',     'chat-composer'],
+  ['ChatEmpty',        'chat-empty'],
+  ['ChatHeader',       'chat-header'],
+  ['ChatShell',        'chat-shell'],
+  ['ChatSidebar',      'chat-sidebar'],
+  ['ChatStatus',       'chat-status'],
+
+  // Editor cluster — A2UI canvas editor surfaces
+  ['EditorCanvas',     'editor-canvas'],
+  ['EditorCanvasEmpty', 'editor-canvas-empty'],
+  ['EditorShell',      'editor-shell'],
+  ['EditorSidebar',    'editor-sidebar'],
+  ['EditorStatusbar',  'editor-statusbar'],
+  ['EditorToolbar',    'editor-toolbar'],
+
+  // Runtime / simple / theme — singleton surfaces
+  ['GenRoot',          'gen-root'],
+  ['SimpleContent',    'simple-content'],
+  ['SimpleHero',       'simple-hero'],
+  ['SimpleShell',      'simple-shell'],
+  ['ThemePanel',       'theme-panel'],
+
+  // gh#645 — 50 catalog types with NO registry mapping, found by the
+  // patient-visit browser probe: `resolveTag()` returned null for every
+  // one below even though `effectiveCatalog()` (derived from all 138
+  // sidecars) already knew the type, so `createAdiaAdapter` rendered
+  // literal `[unknown: X]` text instead of the real element. Each tag
+  // is read straight off the component's own `.a2ui.json` sidecar
+  // (`x-adiaui.tag`), not guessed from the type name — see
+  // `check:genui-catalog`'s new `resolveTag` assertion, which now fails
+  // the build the moment a catalog type ships without a registry entry.
+  ['AdiaMark',          'adia-mark-ui'],
+  ['AdiaWordmark',      'adia-wordmark-ui'],
+  ['AgentArtifact',     'agent-artifact-ui'],
+  ['AgentFeedbackBar',  'agent-feedback-bar-ui'],
+  ['AgentQuestions',    'agent-questions-ui'],
+  ['AgentReasoning',    'agent-reasoning-ui'],
+  ['AgentSuggestions',  'agent-suggestions-ui'],
+  ['AgentTrace',        'agent-trace-ui'],
+  ['Aside',             'aside-ui'],
+  ['Blockquote',        'blockquote-ui'],
+  ['Canvas',            'canvas-ui'],
+  ['ChartLegend',       'chart-legend-ui'],
+  ['ColorInput',        'color-input-ui'],
+  ['ContextMenu',       'context-menu-ui'],
+  ['DemoToggle',        'demo-toggle-ui'],
+  ['DisplayField',      'display-field-ui'],
+  ['Feed',              'feed-ui'],
+  ['FeedItem',          'feed-item-ui'],
+  ['Fields',            'fields-ui'],
+  ['Frame',             'frame-ui'],
+  ['InlineEdit',        'inline-edit-ui'],
+  ['InlineMessage',     'inline-message-ui'],
+  ['ListWindow',        'list-window-ui'],
+  ['LoadingOverlay',    'loading-overlay-ui'],
+  ['Mark',              'mark-ui'],
+  ['MenuDivider',       'menu-divider-ui'],
+  ['MenuItem',          'menu-item-ui'],
+  ['MenuLabel',         'menu-label-ui'],
+  ['NumberFormat',      'number-format-ui'],
+  ['Page',              'page-ui'],
+  ['PasswordStrength',  'password-strength-ui'],
+  ['PipelineStatus',    'pipeline-status-ui'],
+  ['Preview',           'preview-ui'],
+  ['QRCode',            'qr-code-ui'],
+  ['RelativeTime',      'relative-time-ui'],
+  ['Search',            'search-ui'],
+  ['SkipNav',           'skip-nav-ui'],
+  ['Spinner',           'spinner-ui'],
+  ['StepProgress',      'step-progress-ui'],
+  ['Swatch',            'swatch-ui'],
+  // sidecar directory is `toc/toc.a2ui.json`; catalog title is TableOfContents
+  // but the component's own tag is the shorter `toc-ui` (x-adiaui.tag) — not
+  // the naive `table-of-contents-ui` kebab expansion of the type name.
+  ['TableOfContents',   'toc-ui'],
+  ['TableToolbar',      'table-toolbar-ui'],
+  ['TagsInput',         'tags-input-ui'],
+  // No `-ui` suffix — ThemeProvider is infra (a constructable-stylesheet
+  // provider), registered the same bare-tag way as the other singleton
+  // surfaces above (GenRoot, SimpleShell, ThemePanel).
+  ['ThemeProvider',     'theme-provider'],
+  ['TimePicker',        'time-picker-ui'],
+  ['ToggleOption',      'toggle-option-ui'],
+  ['ToggleScheme',      'toggle-scheme-ui'],
+  ['Tree',              'tree-ui'],
+  ['TreeItem',          'tree-item-ui'],
+  ['VisuallyHidden',    'visually-hidden-ui'],
+
+  // gh#848 — 18 shipping web-module composites that ship a full contract
+  // (`<c>.yaml` + derived `<c>.a2ui.json` + `customElements.define`) but
+  // never got a registry entry, so `reverseRegistry` could not resolve
+  // their tags and the docs transpiler's "6. Unknown" fallback converted
+  // each one to an EMPTY Column — 24 site pages rendered a blank shell
+  // where the component belongs (surfaced by gh#847's loud-degrade
+  // instrumentation). Every type name below is the component's own
+  // `component:` field and every tag its own `tag:` field, read from the
+  // yaml SoT — never kebab-guessed from the type name (gh#645's rule;
+  // `embed-shell` and `admin-entity-item` both break the naive
+  // kebab + "-ui" pattern, and `embed-shell` declares `component: AppShell`).
+  ['AdminEntityItem',       'admin-entity-item'],
+  ['AdminRoster',           'admin-roster-ui'],
+  ['AdminSettings',         'admin-settings-ui'],
+  ['AgentAdmin',            'agent-admin-ui'],
+  ['AppShell',              'embed-shell'],
+  ['BillingOverview',       'billing-overview-ui'],
+  ['ConfirmDialog',         'confirm-dialog-ui'],
+  ['DashboardLayout',       'dashboard-layout-ui'],
+  ['DateRangeSelector',     'date-range-selector-ui'],
+  ['FormPopover',           'form-popover-ui'],
+  ['IntegrationsPage',      'integrations-page-ui'],
+  ['InvoiceDetail',         'invoice-detail-ui'],
+  ['InvoiceHistory',        'invoice-history-ui'],
+  ['NotificationPreferences', 'notification-preferences-ui'],
+  ['OnboardingChecklist',   'onboarding-checklist-ui'],
+  ['PaymentMethodForm',     'payment-method-form-ui'],
+  ['PaymentMethodList',     'payment-method-list-ui'],
+  ['PlanPicker',            'plan-picker-ui'],
+
+  // gh#848 — the same gap for two components whose PascalCase name is
+  // already claimed by a DIFFERENT element, so they get the registry's
+  // established bare-tag alias shape instead (`['row-ui','row-ui']`, …).
+  // derive-genui-catalog.mjs:207 skips name===tag pairs as canonical-name
+  // candidates, so neither entry perturbs the derived catalog.
+  //   chat-thread-ui — `ChatThread` routes to the chat WEB-MODULE
+  //     (`chat-thread`) since §49; that entry's own comment already names
+  //     the bare tag as the primitive's access path. This makes it real.
+  //   section-ui — `Section` must keep resolving to the NATIVE `section`:
+  //     card.css scopes `& > section` and carries no `section-ui` rule at
+  //     all, so retargeting the type would silently unstyle every
+  //     converted card body. `section-ui` is the page/sidebar-tier stub
+  //     (page.css:70-84, admin-shell.sidebar.css:139) and needs its own
+  //     handle. The Section/section-ui double-booking itself is a catalog
+  //     design call, recorded in gh#848 — not resolved here.
+  ['chat-thread-ui',    'chat-thread-ui'],
+  ['section-ui',        'section-ui'],
+
+  // gh#848 — description-list children. `<description-list-ui>` renders a
+  // native `<dl>` and its contract (description-list.yaml `slots`) is
+  // "consumer passes <dt>/<dd> children inline", so the pair are native
+  // elements, registered the same way as the `Section`/`Header`/`Footer`
+  // card children above. Without them the transpiled description list is
+  // a `dl` full of Columns and the term/detail grid collapses.
+  ['DescriptionTerm',   'dt'],
+  ['DescriptionDetail', 'dd'],
+]);
+
+/**
+ * Resolve an A2UI component type to a AdiaUI tag name.
+ * @param {string} type — A2UI type name or AgentUI tag
+ * @returns {string|null} — AdiaUI tag name or null
+ */
+export function resolveTag(type) {
+  return registry.get(type) || null;
+}
+
+/**
+ * Register a custom component type.
+ */
+export function registerType(type, tagName) {
+  registry.set(type, tagName);
+}

package/renderer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A2UI Renderer — processes A2UI messages and renders AdiaUI components into the DOM.
+ */
+
+import type { A2UIMessage } from './index.js';
+
+/** Options for A2UIRenderer constructor. */
+export interface A2UIRendererOptions {
+  /** Enable RAF-batched rendering. Default: false. */
+  batch?: boolean;
+}
+
+/** Surface state returned by getSurface(). */
+export interface SurfaceState {
+  root: HTMLElement;
+  rootId: string;
+  elements: Map<string, HTMLElement>;
+  dataModel: Record<string, unknown>;
+  bindings: Map<string, unknown>;
+}
+
+export declare class A2UIRenderer {
+  /**
+   * @param container - Root DOM element to render surfaces into.
+   * @param reg       - Optional custom registry (defaults to the built-in registry Map).
+   * @param options   - Renderer options.
+   */
+  constructor(
+    container: HTMLElement,
+    reg?: Map<string, string>,
+    options?: A2UIRendererOptions,
+  );
+
+  /**
+   * Process a single A2UI message, rendering it into the container.
+   * In batching mode messages are queued and flushed on the next animation frame.
+   */
+  process(message: A2UIMessage | Record<string, unknown>): void;
+
+  /**
+   * Consume an async iterable of messages, processing each in turn.
+   */
+  processStream(stream: AsyncIterable<A2UIMessage | Record<string, unknown>>): Promise<void>;
+
+  /**
+   * Get the internal surface state for a surface ID (useful for testing).
+   */
+  getSurface(id: string): SurfaceState | undefined;
+
+  /**
+   * Get a DOM element by component ID across all surfaces.
+   */
+  getElement(id: string): HTMLElement | undefined;
+
+  /**
+   * IDs of all active surfaces.
+   */
+  readonly surfaces: string[];
+
+  /**
+   * Remove all rendered surfaces and cancel any pending frame.
+   */
+  reset(): void;
+
+  /** Enable or disable RAF batching at runtime. */
+  batching: boolean;
+}