@adia-ai/gen-ui 0.8.37

package/compose/transpiler/transpiler-maps.js

@@ -0,0 +1,675 @@
+/**
+ * Transpiler Maps — Static tag mapping tables and attribute extractors
+ * for the HTML → A2UI transpiler.
+ *
+ * Three mapping layers:
+ *   1. Reverse A2UI registry (tag → type, for *-n elements)
+ *   2. HTML tag map (native HTML → A2UI type)
+ *   3. Input type / ARIA role sub-maps
+ *
+ * §163 (v0.5.4) — Prop-fidelity fix: extractProps() now runs a
+ * catalog-driven generic pass AFTER the legacy per-type blocks. The
+ * catalog (`@adia-ai/gen-ui/corpus`'s v0.9 sidecars) is the single source
+ * of truth for which attributes are first-class props per component
+ * type. Pre-§163, the per-type blocks hardcoded an allowlist that
+ * omitted `label`, `icon`, literal `variant=`, and similar — see
+ * `.brain/postmortems/2026-05-14-lossy-transpiler-boundary.md`.
+ * The catalog-driven pass closes the drift class: when a new prop is
+ * added to the catalog (regenerated from `<name>.yaml`), the extractor
+ * picks it up automatically without manual sync.
+ */
+
+import catalogData from '../../corpus/catalog-a2ui_0_9.json' with { type: 'json' };
+
+import { registry } from '@adia-ai/a2ui';
+
+// ── §163 Catalog-driven prop schema ──────────────────────────────────────
+//
+// Build CATALOG_PROPS at module-init by reading the v0.9 catalog. Each
+// component's `properties` block declares its first-class props with
+// type hints (string / boolean / number / enum). The transpiler uses
+// this map to extract any prop the catalog declares, closing the
+// pre-§163 drift class where the per-type allowlists (lines ~155-249
+// below) omitted `label`, `icon`, literal `variant=`, etc.
+//
+// Aliasing: the runtime registry maps multiple A2UI type names to the
+// same tag (e.g. CheckBox → check-ui, Toggle → switch-ui, Select →
+// select-ui = ChoicePicker). The catalog is keyed by ONE canonical
+// name per tag (e.g. `Check`, `Switch`, `ChoicePicker`). We build an
+// alias map below so `extractProps(el, 'CheckBox')` resolves to the
+// `Check` catalog entry.
+
+// TKT-0010: dynamic props are compiled to a bare `$ref` (DynamicString /
+// DynamicNumber / DynamicBoolean / DynamicStringList / DynamicObjectList),
+// which carries no inline `type` — so `pdef.type || 'string'` below silently
+// treated EVERY dynamic array prop (Chart.data, Table.data) as a string,
+// copying the raw `data='[...]'` attribute text through unparsed instead of
+// JSON-parsing it into a real array. Resolve the ref name to its primitive
+// kind first so extractCatalogProps' array branch actually fires.
+const REF_TYPE_MAP = {
+  DynamicString: 'string',
+  DynamicNumber: 'number',
+  DynamicBoolean: 'boolean',
+  DynamicStringList: 'array',
+  DynamicObjectList: 'array',
+};
+
+/** @type {Map<string, {props: Map<string, {type: string, enum?: string[]}>, canonical: string}>} */
+const CATALOG_PROPS = (() => {
+  const map = new Map();
+  const components = catalogData?.components || {};
+  for (const [name, def] of Object.entries(components)) {
+    const props = def?.properties || {};
+    const propMap = new Map();
+    for (const [pname, pdef] of Object.entries(props)) {
+      // Skip internal/computed props that aren't HTML attributes
+      if (pname === 'component' || pname === 'textContent') continue;
+      if (typeof pdef !== 'object' || !pdef) continue;
+      let type = pdef.type;
+      if (!type && typeof pdef.$ref === 'string') {
+        const refName = pdef.$ref.split('/').pop();
+        type = REF_TYPE_MAP[refName];
+      }
+      propMap.set(pname, {
+        type: type || 'string',
+        enum: pdef.enum || null,
+      });
+    }
+    map.set(name, { props: propMap, canonical: name });
+  }
+  return map;
+})();
+
+/**
+ * Map an A2UI type name (which may be an alias used by the runtime
+ * registry but not the catalog) to the canonical catalog name.
+ *
+ * Examples (driven by runtime/registry.js mappings):
+ *   CheckBox → Check  (registry: CheckBox→check-ui; catalog: Check)
+ *   Toggle   → Switch (registry: Toggle→switch-ui; catalog: Switch)
+ *   Select   → ChoicePicker (registry: Select→select-ui; catalog: ChoicePicker)
+ *
+ * Strategy: for every registry alias type, find the catalog entry whose
+ * tag (= kebab-cased catalog name + '-ui', or registry forward-lookup)
+ * matches the alias's runtime tag. The catalog often uses a name that
+ * is NOT in the registry as a forward entry (e.g. `Check` is in the
+ * catalog but the registry only has `CheckBox → check-ui`).
+ *
+ * Cached at module-init.
+ */
+const TYPE_ALIAS = (() => {
+  const m = new Map();
+  // Pre-pass: every catalog name maps to itself (catalog names ARE valid A2UI types
+  // even when the runtime registry doesn't carry them as forward entries — e.g.
+  // `Check` is in catalog but registry only has `CheckBox → check-ui`).
+  for (const catName of CATALOG_PROPS.keys()) {
+    m.set(catName, catName);
+  }
+  // First pass: direct match (typeName IS the catalog canonical)
+  for (const typeName of registry.keys()) {
+    if (CATALOG_PROPS.has(typeName)) {
+      m.set(typeName, typeName);
+    }
+  }
+  // Second pass: type's tag matches another registry entry that's in the catalog
+  for (const [typeName, tagName] of registry.entries()) {
+    if (m.has(typeName)) continue;
+    for (const [otherType, otherTag] of registry.entries()) {
+      if (otherTag === tagName && CATALOG_PROPS.has(otherType)) {
+        m.set(typeName, otherType);
+        break;
+      }
+    }
+  }
+  // Third pass: derive canonical from tag — `check-ui` → `Check`,
+  // `switch-ui` → `Switch`. The catalog often has the canonical
+  // PascalCase that the registry doesn't list as a forward entry.
+  // We convert tag kebab → PascalCase and check the catalog.
+  for (const [typeName, tagName] of registry.entries()) {
+    if (m.has(typeName)) continue;
+    // 'check-ui' → 'Check'; 'switch-ui' → 'Switch'; 'list-item-ui' → 'ListItem'
+    const stripped = tagName.replace(/-ui$/, '');
+    const pascal = stripped.split('-').map(s => s[0]?.toUpperCase() + s.slice(1)).join('');
+    if (CATALOG_PROPS.has(pascal)) {
+      m.set(typeName, pascal);
+    }
+  }
+  return m;
+})();
+
+/**
+ * §163 generic extractor: pull every catalog-declared prop from the
+ * element's attributes. Type-aware (booleans become true on presence,
+ * numbers parse, enums validate optimistically).
+ *
+ * Runs AFTER the legacy per-type blocks below — so type-specific
+ * extraction (e.g. Button.text from textContent, Image.alt) wins on
+ * conflict. The generic pass FILLS IN props the legacy blocks miss
+ * (the prop-fidelity gap this fix closes).
+ *
+ * @param {object} el — DOM element or MinimalElement
+ * @param {string} a2uiType — Resolved A2UI type name (may be alias)
+ * @returns {Record<string, unknown>}
+ */
+function extractCatalogProps(el, a2uiType) {
+  const canonical = TYPE_ALIAS.get(a2uiType);
+  if (!canonical) return {};
+  const schema = CATALOG_PROPS.get(canonical);
+  if (!schema) return {};
+  const attr = (name) => el.getAttribute?.(name) ?? el.attributes?.get?.(name) ?? null;
+  const props = {};
+  for (const [pname, pdef] of schema.props.entries()) {
+    // gh#853: camelCase catalog prop names (e.g. `channelEnabled`,
+    // `hrefPattern`) are authored as kebab-case HTML attributes per the
+    // yaml's own `attribute:` override — but that override isn't preserved
+    // into the generated catalog (catalog-a2ui_0_9.json keys stay
+    // camelCase), and HTML attribute names are always lowercased on parse
+    // (`channelenabled` !== `channelEnabled`), so the direct lookup below
+    // silently missed every one of them. Fall back to the kebab-cased form.
+    const kebab = pname.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    const raw = attr(pname) ?? (kebab !== pname ? attr(kebab) : null);
+    if (raw === null || raw === undefined) continue;
+
+    if (pdef.type === 'boolean') {
+      // HTML boolean attr convention: presence (incl. empty string) = true.
+      //   <input required>            → raw === ''      → true
+      //   <input required="">         → raw === ''      → true
+      //   <input required="required"> → raw === 'required' → true
+      //   <input required="false">    → raw === 'false' → false (defensive)
+      props[pname] = raw !== 'false';
+    } else if (pdef.type === 'number' || pdef.type === 'integer') {
+      if (raw === '') continue;
+      const n = Number(raw);
+      props[pname] = Number.isFinite(n) ? n : raw;
+    } else if (pdef.type === 'array') {
+      // TKT-0010: declarative JSON-array attribute (e.g. chart-ui/table-ui's
+      // data='[{...}]'), hydrated once at connect per those components' own
+      // yaml docs. Parse it — the raw string never satisfies the catalog's
+      // array schema, and per chart.yaml's own contract a non-array value
+      // is meant to render empty, so a parse failure/non-array is skipped,
+      // not passed through.
+      if (raw === '') continue;
+      try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) props[pname] = parsed;
+      } catch { /* not valid JSON — skip */ }
+    } else if (pdef.type === 'object') {
+      // gh#853 sibling of the array branch above: object-typed props (e.g.
+      // InvoiceDetail.invoice, NotificationPreferences.channelEnabled) are
+      // JSON-encoded HTML attributes too — same declarative-data convention,
+      // just a plain object instead of an array.
+      if (raw === '') continue;
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) props[pname] = parsed;
+      } catch { /* not valid JSON — skip */ }
+    } else {
+      // string (incl. enum) — skip empty
+      if (raw === '') continue;
+      props[pname] = raw;
+    }
+  }
+  return props;
+}
+
+// ── Alias types to skip in reverse registry (prefer primary type) ────────
+
+const ALIAS_TYPES = new Set([
+  'Select', 'LoadingIndicator', 'ErrorContainer', 'Keyboard',
+  'DatePicker', 'CommandPalette', 'Segmented', 'OTP', 'SideNav', 'IconSource',
+]);
+
+// ── Reverse Registry: tag → primary A2UI type ────────────────────────────
+
+/** @type {Map<string, string>} */
+export const reverseRegistry = new Map();
+
+for (const [type, tag] of registry) {
+  if (ALIAS_TYPES.has(type)) continue;
+  // First-write wins — skip if tag already mapped (avoids alias overwrite)
+  if (!reverseRegistry.has(tag)) {
+    reverseRegistry.set(tag, type);
+  }
+}
+
+// ── HTML Tag → A2UI Type ─────────────────────────────────────────────────
+
+/** @type {Record<string, { type: string, props?: Record<string, unknown> }>} */
+export const HTML_TAG_MAP = {
+  // §210 (v0.5.7, FEEDBACK-17 §1): map native heading levels to working
+  // text-ui variants. Pre-§210 these mapped to `h1`-`h6` strings that
+  // text.css had no `:scope[variant=…]` rule for — silent body-default
+  // rendering. The retired variants (`h1`-`h6` + `subheading`) were
+  // removed from text.yaml/text.d.ts/text.a2ui.json in §210 because no
+  // matching tokens shipped. Replacement mapping prefers role tokens
+  // that actually render:
+  //   <h1> → 'display' (largest type — marketing hero)
+  //   <h2> → 'title'   (page title)
+  //   <h3> → 'heading' (section division)
+  //   <h4> → 'subsection' (sub-grouping inside a heading section)
+  //   <h5>, <h6> → 'subsection' (no smaller subsection token ships;
+  //                               consistent fallback over silent
+  //                               body-default)
+  h1:         { type: 'Text', props: { variant: 'display' } },
+  h2:         { type: 'Text', props: { variant: 'title' } },
+  h3:         { type: 'Text', props: { variant: 'heading' } },
+  h4:         { type: 'Text', props: { variant: 'subsection' } },
+  h5:         { type: 'Text', props: { variant: 'subsection' } },
+  h6:         { type: 'Text', props: { variant: 'subsection' } },
+  p:          { type: 'Text', props: { variant: 'body' } },
+  small:      { type: 'Text', props: { variant: 'caption' } },
+  strong:     { type: 'Text', props: { variant: 'body' } },
+  em:         { type: 'Text', props: { variant: 'body' } },
+  blockquote: { type: 'Text', props: { variant: 'body' } },
+  code:       { type: 'Code' },
+  pre:        { type: 'Code' },
+  kbd:        { type: 'Kbd' },
+  button:     { type: 'Button' },
+  select:     { type: 'ChoicePicker' },
+  textarea:   { type: 'TextArea' },
+  form:       { type: 'FormContainer' },
+  img:        { type: 'Image' },
+  video:      { type: 'Embed' },
+  iframe:     { type: 'Embed' },
+  audio:      { type: 'Embed' },
+  table:      { type: 'Table' },
+  ul:         { type: 'List' },
+  ol:         { type: 'List' },
+  li:         { type: 'Text', props: { variant: 'body' } },
+  // gh#848 — description lists. `<dl>` IS description-list-ui (it renders a
+  // native dl), and its documented children are native `<dt>`/`<dd>`
+  // (description-list.yaml slots: "Consumer passes <dt>/<dd> children
+  // inline"). Without these three the pair fell to the Unknown fallback and
+  // the term/detail grid collapsed into nested containers.
+  dl:         { type: 'DescriptionList' },
+  dt:         { type: 'DescriptionTerm' },
+  dd:         { type: 'DescriptionDetail' },
+  // gh#853 — `<figure>` is a self-contained content unit (image + caption),
+  // the same "self-contained block" semantic already given to `<article>`
+  // (→ Card). `<figcaption>` is the annotation UNDER that unit — text.yaml's
+  // own `caption` variant docstring names this exact use case ("Annotation
+  // under a primary line … Use for image captions, footnotes."), so it maps
+  // there rather than falling to the generic `body` variant every other
+  // untyped inline tag gets.
+  figure:     { type: 'Card' },
+  figcaption: { type: 'Text', props: { variant: 'caption' } },
+  // gh#853 — `<s>` (strikethrough) has no dedicated A2UI decoration prop
+  // (text.yaml carries no strike/decoration prop today — a platform gap
+  // beyond this tag-mapping fix). Until one exists, treat it as the phrasing
+  // content it is, same as the `strong`/`em`/`blockquote` mappings above.
+  s:          { type: 'Text', props: { variant: 'body' } },
+  nav:        { type: 'Nav' },
+  aside:      { type: 'Sidebar' },
+  main:       { type: 'Column' },
+  article:    { type: 'Card' },
+  details:    { type: 'Accordion' },
+  summary:    { type: 'Text', props: { variant: 'subsection' } },
+  dialog:     { type: 'Modal' },
+  hr:         { type: 'Divider' },
+  a:          { type: 'Link' },  // §47 — was: Button + variant=ghost (button.yaml line 60: "for inline navigation use `<link-ui>` instead")
+  header:     { type: 'Header' },
+  footer:     { type: 'Footer' },
+  section:    { type: 'Section' },
+  label:      { type: 'Text', props: { variant: 'body' } },
+  span:       { type: 'Text', props: { variant: 'body' } },
+};
+
+// ── Input Type Sub-Map ───────────────────────────────────────────────────
+
+/** @type {Record<string, { type: string, props?: Record<string, unknown> }>} */
+export const INPUT_TYPE_MAP = {
+  text:              { type: 'TextField' },
+  email:             { type: 'TextField', props: { type: 'email' } },
+  password:          { type: 'TextField', props: { type: 'password' } },
+  number:            { type: 'TextField', props: { type: 'number' } },
+  tel:               { type: 'TextField', props: { type: 'tel' } },
+  url:               { type: 'TextField', props: { type: 'url' } },
+  search:            { type: 'Search' },
+  checkbox:          { type: 'CheckBox' },
+  radio:             { type: 'Radio' },
+  range:             { type: 'Slider' },
+  date:              { type: 'DateTimeInput' },
+  time:              { type: 'DateTimeInput' },
+  'datetime-local':  { type: 'DateTimeInput' },
+  file:              { type: 'Upload' },
+  color:             { type: 'ColorPicker' },
+  submit:            { type: 'Button', props: { variant: 'primary', type: 'submit' } },
+  reset:             { type: 'Button', props: { variant: 'outline', type: 'reset' } },
+};
+
+// ── ARIA Role Map ────────────────────────────────────────────────────────
+
+/** @type {Record<string, string>} */
+export const ARIA_ROLE_MAP = {
+  tablist:       'Tabs',
+  tab:           'Tab',
+  tabpanel:      'Panel',
+  alert:         'Alert',
+  alertdialog:   'Dialog',
+  dialog:        'Modal',
+  navigation:    'Nav',
+  progressbar:   'Progress',
+  slider:        'Slider',
+  switch:        'Toggle',
+  menu:          'Menu',
+  menubar:       'Menu',
+  toolbar:       'Toolbar',
+  tooltip:       'Tooltip',
+  search:        'Search',
+  banner:        'Header',
+  contentinfo:   'Footer',
+  complementary: 'Sidebar',
+};
+
+// ── Skip Tags ────────────────────────────────────────────────────────────
+
+export const SKIP_TAGS = new Set([
+  'script', 'style', 'link', 'meta', 'head', 'br', 'wbr',
+  'noscript', 'template', 'slot', 'svg', 'path', 'circle',
+  'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'use',
+]);
+
+// ── Attribute Extractors ─────────────────────────────────────────────────
+
+/**
+ * Extract A2UI props from an HTML element based on the resolved A2UI type.
+ *
+ * @param {object} el — DOM element or MinimalElement
+ * @param {string} a2uiType — Resolved A2UI type name
+ * @returns {Record<string, unknown>}
+ */
+export function extractProps(el, a2uiType) {
+  const props = {};
+  const attr = (name) => el.getAttribute?.(name) ?? el.attributes?.get?.(name) ?? null;
+
+  // Universal: preserve [slot] for every element. Slot is a layout-bearing
+  // HTML attribute that card-ui / drawer-ui / etc. depend on via :has(> [slot])
+  // grid activation. Yamls don't declare slot as a prop (it's an HTML standard
+  // attribute, not a component prop), so the catalog pass below won't pick it up.
+  const slotAttr = attr('slot');
+  if (slotAttr) props.slot = slotAttr;
+
+  // Universal: preserve [span] for every element. Span is a layout-bearing
+  // attribute grid-ui's child reads via a pure CSS attribute selector
+  // (grid.css: `& > [span="3"] { grid-column: span 3; }`) — it belongs to
+  // "whatever this grid child happens to be," never to a specific
+  // component's own prop schema, so no .yaml declares it and the
+  // catalog-driven pass below silently drops it (TKT-0002: collapsed the
+  // admin-dashboard Overview/Recent Sales 3:2 split to two equal, unspanned
+  // columns).
+  const spanAttr = attr('span');
+  if (spanAttr) props.span = spanAttr;
+
+  // §163 (v0.5.4) — Catalog-driven generic extraction FIRST. Fills in
+  // every prop the v0.9 catalog declares for this type (label, icon,
+  // variant=, etc.). Legacy per-type blocks below run AFTER and can
+  // overwrite specific values (e.g. Button.text inferred from
+  // textContent when no `text=` attribute is set).
+  Object.assign(props, extractCatalogProps(el, a2uiType));
+
+  // ── Text content (for leaf elements) ──
+  if (['Text', 'Kbd', 'Code'].includes(a2uiType)) {
+    const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    if (text) props.textContent = text;
+  }
+
+  // ── Button ──
+  if (a2uiType === 'Button') {
+    if (props.text === undefined) {
+      const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+      if (text) props.text = text;
+    }
+    if (props.type === undefined) {
+      const type = attr('type');
+      if (type && type !== 'button') props.type = type;
+    }
+    if (props.disabled === undefined && attr('disabled') !== null) props.disabled = true;
+    // Variant inference from class (only if generic pass didn't already extract literal `variant=` attr)
+    if (props.variant === undefined) {
+      const cls = attr('class') || '';
+      if (cls.includes('primary')) props.variant = 'primary';
+      else if (cls.includes('danger')) props.variant = 'danger';
+      else if (cls.includes('ghost')) props.variant = 'ghost';
+      else if (cls.includes('outline')) props.variant = 'outline';
+    }
+  }
+
+  // ── Tag ── (TKT-0004: tag-ui renders its label via CSS attr(text) —
+  // tag.yaml documents textContent as routing to the text attribute. The
+  // authored form is light-DOM content (<tag-ui size="sm">label</tag-ui>),
+  // so fall back to textContent when no text= attribute is set.)
+  if (a2uiType === 'Tag' && props.text === undefined) {
+    const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    if (text) props.text = text;
+  }
+
+  // ── Link ── (§47 — <a> tags map to Link, not Button; carries href, target, rel)
+  if (a2uiType === 'Link') {
+    const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    if (text) props.text = text;
+    const href = attr('href');
+    if (href) props.href = href;
+    const target = attr('target');
+    if (target) props.target = target;
+    const rel = attr('rel');
+    if (rel) props.rel = rel;
+  }
+
+  // ── TextField / Input ──
+  if (['TextField', 'Search'].includes(a2uiType)) {
+    for (const name of ['placeholder', 'name', 'value', 'pattern', 'min', 'max', 'minlength', 'maxlength', 'autocomplete']) {
+      const v = attr(name);
+      if (v !== null && v !== '') props[name] = v;
+    }
+    if (attr('required') !== null) props.required = true;
+    if (attr('disabled') !== null) props.disabled = true;
+    if (attr('readonly') !== null) props.readonly = true;
+    const type = attr('type');
+    if (type && type !== 'text') props.type = type;
+  }
+
+  // ── CheckBox / Toggle / Radio ──
+  if (['CheckBox', 'Toggle', 'Radio'].includes(a2uiType)) {
+    const name = attr('name');
+    if (name) props.name = name;
+    const value = attr('value');
+    if (value) props.value = value;
+    if (attr('checked') !== null) props.checked = true;
+    if (attr('disabled') !== null) props.disabled = true;
+    if (attr('required') !== null) props.required = true;
+  }
+
+  // ── Slider ──
+  if (a2uiType === 'Slider') {
+    for (const name of ['min', 'max', 'value', 'step', 'name']) {
+      if (props[name] !== undefined) continue;  // catalog pass already filled this
+      const v = attr(name);
+      if (v !== null && v !== '') props[name] = name === 'step' ? v : Number(v) || v;
+    }
+    if (props.disabled === undefined && attr('disabled') !== null) props.disabled = true;
+  }
+
+  // ── Image ──
+  if (a2uiType === 'Image') {
+    const src = attr('src');
+    if (src) props.src = src;
+    const alt = attr('alt');
+    if (alt) props.alt = alt;
+  }
+
+  // ── TextArea ──
+  if (a2uiType === 'TextArea') {
+    for (const name of ['placeholder', 'name', 'rows', 'cols', 'minlength', 'maxlength']) {
+      const v = attr(name);
+      if (v !== null && v !== '') props[name] = v;
+    }
+    if (attr('required') !== null) props.required = true;
+    if (attr('disabled') !== null) props.disabled = true;
+    const text = (el.textContent || '').trim();
+    if (text) props.value = text;
+  }
+
+  // ── Embed ──
+  if (a2uiType === 'Embed') {
+    const src = attr('src');
+    if (src) props.src = src;
+  }
+
+  // ── Layout (Column, Row, Grid) ──
+  if (['Column', 'Row', 'Grid', 'List'].includes(a2uiType)) {
+    const gap = attr('gap');
+    if (gap) props.gap = gap;
+  }
+
+  // ── Label extraction from adjacent <label> or aria-label ──
+  if (['TextField', 'CheckBox', 'Toggle', 'Radio', 'Slider', 'Search', 'TextArea', 'ChoicePicker', 'DateTimeInput'].includes(a2uiType)) {
+    const ariaLabel = attr('aria-label');
+    if (ariaLabel) props.label = ariaLabel;
+  }
+
+  // ── ChoicePicker / Select, Combobox, Command — build the options[]
+  //    model from declarative <option> / <optgroup> children (FB-79;
+  //    extended to Combobox per gh#860, to Command per gh#887).
+  //    <select-ui>/<combobox-ui>/<command-ui> render natively from
+  //    `el.options = [{value, label, disabled?}]` (select.yaml /
+  //    combobox.yaml / command.yaml `options`), so the options must
+  //    travel as a PROP. Without this, the tree walker emits each
+  //    <option> as a Text child, which the component rejects (renders
+  //    empty + "ignoring unrecognized child element" warning).
+  //    command.yaml's option model additionally carries data-icon/
+  //    data-shortcut per <option> — extractSelectOptions captures those
+  //    only for Command (withIcons) so ChoicePicker/Combobox's model
+  //    stays exactly {value, label, disabled?} (no unused fields).
+  if (a2uiType === 'ChoicePicker' || a2uiType === 'Combobox' || a2uiType === 'Command') {
+    const options = extractSelectOptions(el, { withIcons: a2uiType === 'Command' });
+    if (options.length) {
+      props.options = options;
+    }
+    // Mirror <option selected> into the value when not set via attr,
+    // matching select-ui/combobox-ui #parseOptions. Command has no
+    // `value` prop (command.yaml declares only open/placeholder) — no
+    // value to mirror there.
+    if (a2uiType !== 'Command' && (props.value === undefined || props.value === '')) {
+      const selected = collectSelectedOptionValues(el);
+      if (selected.length) {
+        // gh#887 adjacent finding: combobox-ui is single-select —
+        // first-selected-wins, matching its own #parseOptions (which
+        // only sets `preSelected` from the FIRST `<option selected>` it
+        // sees). select-ui's [multiple] mode is the one that legitimately
+        // comma-joins several selected values.
+        props.value = a2uiType === 'Combobox' ? selected[0] : selected.join(',');
+      }
+    }
+  }
+
+  // ── Data attributes pass-through ──
+  if (el.attributes) {
+    const attrs = el.attributes instanceof Map ? el.attributes : el.attributes;
+    if (typeof attrs[Symbol.iterator] === 'function') {
+      for (const a of attrs) {
+        const name = a.name || a[0];
+        const value = a.value || a[1];
+        if (name?.startsWith('data-') && name !== 'data-a2ui-id') {
+          props[name] = value;
+        }
+      }
+    }
+  }
+
+  return props;
+}
+
+// ── Select option model (FB-79) ──────────────────────────────────────────
+
+/**
+ * Build the <select-ui> / <combobox-ui> / <command-ui> options[] model
+ * from an element's declarative <option> / <optgroup> children. Mirrors
+ * select-ui #parseOptions:
+ *   <option value disabled>Label</option> → { value, label, disabled? }
+ *   <optgroup label>…</optgroup>           → { label, options: [...] }
+ *
+ * @param {object} el — DOM element or MinimalElement
+ * @param {{withIcons?: boolean}} [opts] — withIcons: also capture
+ *   data-icon/data-shortcut per <option> (command.yaml's option model,
+ *   gh#887) — select/combobox's model has no such fields.
+ * @returns {Array<object>}
+ */
+function extractSelectOptions(el, { withIcons = false } = {}) {
+  const out = [];
+  for (const child of (el.children || [])) {
+    const ctag = (child.tagName || '').toLowerCase();
+    if (ctag === 'option') {
+      out.push(optionToModel(child, { withIcons }));
+    } else if (ctag === 'optgroup') {
+      const label = optionAttr(child, 'label') || '';
+      const groupOptions = [];
+      for (const opt of (child.children || [])) {
+        if ((opt.tagName || '').toLowerCase() === 'option') groupOptions.push(optionToModel(opt, { withIcons }));
+      }
+      out.push({ label, options: groupOptions });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} opt
+ * @param {{withIcons?: boolean}} [modelOpts]
+ * @returns {{value: string, label: string, disabled?: boolean, icon?: string, shortcut?: string}}
+ */
+function optionToModel(opt, { withIcons = false } = {}) {
+  const value = optionAttr(opt, 'value');
+  const label = (opt.textContent || '').trim().replace(/\s+/g, ' ');
+  const model = { value: value != null ? value : label, label };
+  if (optionAttr(opt, 'disabled') !== null) model.disabled = true;
+  if (withIcons) {
+    const icon = optionAttr(opt, 'data-icon');
+    const shortcut = optionAttr(opt, 'data-shortcut');
+    if (icon) model.icon = icon;
+    if (shortcut) model.shortcut = shortcut;
+  }
+  return model;
+}
+
+/** Collect values of <option selected> children (recursing <optgroup>). */
+function collectSelectedOptionValues(el) {
+  const values = [];
+  const walk = (nodes) => {
+    for (const child of (nodes || [])) {
+      const ctag = (child.tagName || '').toLowerCase();
+      if (ctag === 'option') {
+        if (optionAttr(child, 'selected') !== null) {
+          const v = optionAttr(child, 'value');
+          values.push(v != null ? v : (child.textContent || '').trim().replace(/\s+/g, ' '));
+        }
+      } else if (ctag === 'optgroup') {
+        walk(child.children);
+      }
+    }
+  };
+  walk(el.children);
+  return values;
+}
+
+/** Read an attribute from either a DOM element or a MinimalElement. */
+function optionAttr(el, name) {
+  return el.getAttribute?.(name) ?? el.attributes?.get?.(name) ?? null;
+}
+
+// ── Gap Inference ────────────────────────────────────────────────────────
+
+/**
+ * Map a pixel gap value to a token size.
+ * @param {string} gapValue — CSS gap value (e.g., "8px", "1rem")
+ * @returns {string} — "xs" | "sm" | "md" | "lg" | "xl"
+ */
+export function inferGap(gapValue) {
+  if (!gapValue) return 'md';
+  const px = parseFloat(gapValue);
+  if (isNaN(px)) return 'md';
+  if (px <= 4) return 'xs';
+  if (px <= 8) return 'sm';
+  if (px <= 16) return 'md';
+  if (px <= 24) return 'lg';
+  return 'xl';
+}

package/compose/transpiler/transpiler.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};