@adia-ai/a2ui-runtime 0.3.0

package/registry.js

@@ -0,0 +1,205 @@
+/**
+ * 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'],
+  ['Skeleton',         'skeleton-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'],
+  ['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'],
+  ['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'],
+  ['Chart',            'chart-ui'],
+  ['Embed',            'embed-ui'],
+  ['Swiper',           'swiper-ui'],
+  ['Slideshow',        'swiper-ui'],
+  ['Carousel',         'swiper-ui'],
+
+  // Navigation
+  ['Breadcrumb',       'breadcrumb-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'],
+  ['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'],
+  ['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'],
+  ['Segmented',        'segmented-ui'],
+  ['OTP',              'otp-input-ui'],
+]);
+
+/**
+ * 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.js

@@ -0,0 +1,395 @@
+/**
+ * A2UI Renderer — processes A2UI messages and renders AdiaUI components.
+ *
+ * Usage:
+ *   import { A2UIRenderer } from './renderer.js';
+ *   const renderer = new A2UIRenderer(container);
+ *   renderer.process(message);
+ */
+
+import { resolveTag, registry } from './registry.js';
+
+export class A2UIRenderer {
+  #container;
+  #registry;
+  #surfaces = new Map();
+  #elements = new Map();
+  #prevProps = new Map();
+  #queue = [];
+  #rafId = null;
+  #batching = false;
+
+  constructor(container, reg = registry, { batch = false } = {}) {
+    this.#container = container;
+    this.#registry = reg;
+    this.#batching = batch;
+  }
+
+  process(message) {
+    if (!message) return;
+    if (this.#batching) {
+      this.#queue.push(message);
+      if (this.#rafId === null) {
+        this.#rafId = requestAnimationFrame(() => this.#flush());
+      }
+    } else {
+      this.#processOne(message);
+    }
+  }
+
+  #flush() {
+    this.#rafId = null;
+    const batch = this.#queue.splice(0);
+    for (const msg of batch) this.#processOne(msg);
+  }
+
+  #processOne(message) {
+    switch (message.type || message.messageType) {
+      case 'createSurface':    this.#createSurface(message); break;
+      case 'updateComponents': this.#updateComponents(message); break;
+      case 'updateDataModel':  this.#updateDataModel(message); break;
+      case 'wireComponents':   this.#wireComponents(message); break;
+      case 'deleteSurface':    this.#deleteSurface(message); break;
+      case 'meta':             break; // LLM self-critique — not renderable
+      default: console.warn('A2UI: unknown message type', message.type);
+    }
+  }
+
+  // ── wireComponents (lazy-loaded) ──
+
+  #wiringEngine = null;
+
+  async #wireComponents(message) {
+    if (!this.#wiringEngine) {
+      const { WiringEngine } = await import('./wiring-engine.js');
+      this.#wiringEngine = new WiringEngine({
+        updateDataModel: (surfaceId, path, data) => {
+          this.#updateDataModel({ surfaceId, path, value: data });
+        },
+        getElement: (surfaceId, componentId) => {
+          const surface = this.#surfaces.get(surfaceId);
+          return surface?.elements.get(componentId) || null;
+        },
+      });
+    }
+    await this.#wiringEngine.process(message);
+  }
+
+  async processStream(stream) {
+    for await (const message of stream) this.process(message);
+  }
+
+  // ── createSurface ──
+
+  #createSurface({ surfaceId, catalogId, root: rootId }) {
+    if (this.#surfaces.has(surfaceId)) return;
+
+    const root = document.createElement('div');
+    root.setAttribute('data-a2ui-surface', surfaceId);
+    if (catalogId) root.setAttribute('data-catalog', catalogId);
+    this.#container.appendChild(root);
+
+    this.#surfaces.set(surfaceId, {
+      root,
+      // `rootId` = the id of the component to attach as the surface's
+      // rendered root. Honors the A2UI protocol's `createSurface.root`
+      // field when present; falls back to the legacy `'root'` convention
+      // that earlier docs baked in. See #updateComponents attach step.
+      rootId: typeof rootId === 'string' && rootId ? rootId : 'root',
+      elements: new Map(),
+      dataModel: {},
+      bindings: new Map(),
+    });
+  }
+
+  // ── updateComponents ──
+
+  #updateComponents({ surfaceId, components }) {
+    let surface = this.#surfaces.get(surfaceId);
+
+    if (!surface) {
+      surface = {
+        root: this.#container,
+        // Synthetic surfaces (updateComponents without a prior
+        // createSurface) default to the legacy 'root' convention.
+        rootId: 'root',
+        elements: new Map(),
+        dataModel: {},
+        bindings: new Map(),
+      };
+      this.#surfaces.set(surfaceId, surface);
+    }
+
+    // First pass: create/update elements
+    for (const comp of components) {
+      if (!comp.id && comp.id !== 0) continue;
+      if (comp.component === 'ContextBindings') {
+        surface.contextBindings = comp;
+        continue;
+      }
+
+      try {
+        let el = surface.elements.get(comp.id);
+        const tagName = comp.component === 'Text'
+          ? this.#resolveTextTag(comp.variant, comp)
+          : resolveTag(comp.component, this.#registry);
+
+        if (!tagName) {
+          if (!el) {
+            el = document.createElement('div');
+            el.setAttribute('data-a2ui-id', comp.id);
+            el.setAttribute('data-a2ui-unknown', comp.component);
+            el.textContent = `[unknown: ${comp.component}]`;
+            surface.elements.set(comp.id, el);
+            this.#elements.set(comp.id, el);
+          }
+          continue;
+        }
+
+        if (!el) {
+          el = document.createElement(tagName);
+          el.setAttribute('data-a2ui-id', comp.id);
+          surface.elements.set(comp.id, el);
+          this.#elements.set(comp.id, el);
+        } else if (el.localName !== tagName) {
+          const newEl = document.createElement(tagName);
+          newEl.setAttribute('data-a2ui-id', comp.id);
+          el.replaceWith(newEl);
+          el = newEl;
+          surface.elements.set(comp.id, el);
+          this.#elements.set(comp.id, el);
+        }
+
+        comp._surfaceId = surfaceId;
+
+        const hasBindings = Object.values(comp).some(v => v && typeof v === 'object' && v.path);
+        if (hasBindings) surface.bindings.set(comp.id, comp);
+
+        this.#applyProps(el, comp);
+      } catch (err) {
+        console.warn(`A2UI: component "${comp.id}" (${comp.component}) failed:`, err.message);
+      }
+    }
+
+    // Build parent map for cycle detection
+    const parentMap = new Map();
+    for (const comp of components) {
+      for (const childId of (Array.isArray(comp.children) ? comp.children : [])) {
+        parentMap.set(childId, comp.id);
+      }
+      if (comp.child) parentMap.set(comp.child, comp.id);
+    }
+
+    const wouldCycle = (parentId, childId) => {
+      const visited = new Set();
+      let cursor = parentId;
+      while (cursor != null) {
+        if (cursor === childId) return true;
+        if (visited.has(cursor)) return true;
+        visited.add(cursor);
+        cursor = parentMap.get(cursor);
+      }
+      return false;
+    };
+
+    // Second pass: build tree
+    for (const comp of components) {
+      const el = surface.elements.get(comp.id);
+      if (!el) continue;
+
+      try {
+        const childIds = Array.isArray(comp.children) ? comp.children : [];
+        for (const childId of childIds) {
+          if (childId === comp.id || wouldCycle(comp.id, childId)) continue;
+          const childEl = surface.elements.get(childId);
+          if (childEl && childEl.parentElement !== el) el.appendChild(childEl);
+        }
+
+        if (comp.child && comp.child !== comp.id && !wouldCycle(comp.id, comp.child)) {
+          const childEl = surface.elements.get(comp.child);
+          if (childEl && childEl.parentElement !== el) el.appendChild(childEl);
+        }
+      } catch (err) {
+        console.warn(`A2UI: tree build failed for "${comp.id}":`, err.message);
+      }
+    }
+
+    // Attach root — use the surface's declared rootId (from
+    // createSurface.root) if present, else fall back to the legacy
+    // 'root' convention. Both surface.rootId and the fallback are
+    // looked up in the same elements Map.
+    const attachId = surface.rootId ?? 'root';
+    const rootComp = components.find(c => c.id === attachId);
+    if (rootComp) {
+      const rootEl = surface.elements.get(attachId);
+      if (rootEl && rootEl.parentElement !== surface.root) {
+        surface.root.appendChild(rootEl);
+      }
+    }
+  }
+
+  // ── Apply props ──
+
+  static #JS_PROPS = new Set(['data', 'columns', 'options', 'itemRenderer', 'textContent']);
+
+  // Tags where setting `textContent` is safe — pure text-bearing leaves.
+  // On a container (alert-ui, card-ui, button-ui, …) `el.textContent = value`
+  // would wipe slotted children + trailing-pass appended children, leaving a
+  // bare text node sandwiched between attributes and children. When an LLM
+  // emits `{ component: "Alert", textContent: "…" }` we instead want to set
+  // the `text=` attribute, which the component's own connected()/render()
+  // routes into its `<span slot="content">` slot.
+  static #TEXT_TAG_OK = new Set([
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'p', 'small', 'span', 'em', 'strong', 'code',
+    'text-ui',
+  ]);
+
+  // Semantic HTML variants — these render as native tags (h1, p, small)
+  // Everything else renders as <text-ui> which is now display:inline
+  static #TEXT_TAG_MAP = {
+    h1: 'h1', h2: 'h2', h3: 'h3', h4: 'h4', h5: 'h5', h6: 'h6',
+    body: 'p', caption: 'small',
+  };
+
+  #resolveTextTag(variant, comp) {
+    // Semantic HTML variants get native tags (accessibility)
+    if (!comp?.slot && A2UIRenderer.#TEXT_TAG_MAP[variant]) {
+      return A2UIRenderer.#TEXT_TAG_MAP[variant];
+    }
+    // Everything else → text-ui (inline, supports truncate/lines/variant)
+    return 'text-ui';
+  }
+
+  #applyProps(el, comp) {
+    const skip = new Set(['id', 'component', 'children', 'child', '_surfaceId']);
+    // Skip variant attr when the tag IS the variant (h1 for h1, p for body, small for caption)
+    if (comp.component === 'Text' && comp.variant && !comp.slot && A2UIRenderer.#TEXT_TAG_MAP[comp.variant]) {
+      skip.add('variant');
+    }
+
+    const prev = this.#prevProps.get(comp.id);
+    const next = {};
+
+    for (const [key, value] of Object.entries(comp)) {
+      if (skip.has(key)) continue;
+
+      const isBinding = value && typeof value === 'object' && value.path;
+      const resolved = this.#resolveValue(value, comp._surfaceId);
+      next[key] = resolved;
+
+      if (prev && Object.is(prev[key], resolved)) continue;
+
+      if (key === 'style' && typeof resolved === 'string') {
+        el.style.cssText = resolved;
+        continue;
+      }
+
+      if (A2UIRenderer.#JS_PROPS.has(key) && resolved != null) {
+        // Guard against destructive `el.textContent = …` on container
+        // elements: it wipes slotted children + the trailing-pass tree.
+        // For non-text-bearing tags, route the value to the `text=`
+        // attribute instead (which Alert/Button/Badge/etc. read in
+        // their own render loop and slot correctly).
+        if (key === 'textContent' && !A2UIRenderer.#TEXT_TAG_OK.has(el.localName)) {
+          el.setAttribute('text', String(resolved));
+          continue;
+        }
+        el[key] = resolved;
+        continue;
+      }
+
+      if (typeof resolved === 'boolean') {
+        if (resolved) el.setAttribute(key, '');
+        else el.removeAttribute(key);
+      } else if (resolved != null) {
+        el.setAttribute(this.#toAttr(key), String(resolved));
+      } else if (isBinding) {
+        el.removeAttribute(this.#toAttr(key));
+      }
+    }
+
+    if (prev) {
+      for (const key of Object.keys(prev)) {
+        if (!(key in next) && !skip.has(key)) el.removeAttribute(this.#toAttr(key));
+      }
+    }
+
+    this.#prevProps.set(comp.id, next);
+  }
+
+  #toAttr(name) {
+    return name.replace(/([A-Z])/g, '-$1').toLowerCase();
+  }
+
+  #resolveValue(value, surfaceId) {
+    if (value == null) return null;
+    if (typeof value !== 'object') return value;
+    if (value.path) {
+      const surface = surfaceId ? this.#surfaces.get(surfaceId) : null;
+      return surface ? this.#getByPath(surface.dataModel, value.path) : value.path;
+    }
+    return value;
+  }
+
+  #getByPath(obj, path) {
+    if (!path || path === '/') return obj;
+    return path.split('/').filter(Boolean).reduce((o, k) => o?.[k], obj);
+  }
+
+  // ── updateDataModel ──
+
+  #updateDataModel({ surfaceId, path, value }) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+
+    if (!path || path === '/') {
+      surface.dataModel = value ?? {};
+    } else {
+      const parts = path.split('/').filter(Boolean);
+      let cur = surface.dataModel;
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (cur[parts[i]] == null) cur[parts[i]] = {};
+        cur = cur[parts[i]];
+      }
+      cur[parts[parts.length - 1]] = value;
+    }
+
+    for (const [compId, comp] of surface.bindings) {
+      const el = surface.elements.get(compId);
+      if (el) this.#applyProps(el, comp);
+    }
+  }
+
+  // ── deleteSurface ──
+
+  #deleteSurface({ surfaceId }) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+    this.#wiringEngine?.teardown(surfaceId);
+    for (const [id] of surface.elements) this.#elements.delete(id);
+    surface.root.remove();
+    this.#surfaces.delete(surfaceId);
+  }
+
+  // ── Public ──
+
+  getSurface(id) { return this.#surfaces.get(id); }
+  getElement(id) { return this.#elements.get(id); }
+  get surfaces() { return [...this.#surfaces.keys()]; }
+
+  reset() {
+    if (this.#rafId !== null) { cancelAnimationFrame(this.#rafId); this.#rafId = null; }
+    this.#queue.length = 0;
+    for (const [, s] of this.#surfaces) {
+      if (s.root === this.#container) s.root.innerHTML = '';
+      else s.root.remove();
+    }
+    this.#surfaces.clear();
+    this.#elements.clear();
+    this.#prevProps.clear();
+  }
+
+  set batching(v) { this.#batching = !!v; }
+  get batching() { return this.#batching; }
+}