@tmorrow/cre8-wc 2.0.8 → 2.1.0

package/a2ui/check-layer-parity.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * Asserts that every layer describing the component library agrees.
+ *
+ *   node a2ui/check-layer-parity.mjs
+ *
+ * The library is described six times over — the source that registers the
+ * elements, the MCP manifest, the A2UI catalog, the compact projection, the
+ * React manifest, and custom-elements.json — each generated by a different
+ * script from a different glob. Nothing forced them to agree, and they didn't:
+ * an analyzer glob one level too shallow dropped five components from all five
+ * derived layers at once, silently, for months.
+ *
+ * This is the check that makes that unmergeable. It compares the layers against
+ * each other rather than against a hardcoded expectation, so it keeps working as
+ * components are added.
+ *
+ * Deliberate omissions are legal but must be declared: `internalElements` in the
+ * manifest is the single place they live, and every one is re-verified here.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WC = join(HERE, '..');
+const REPO = join(WC, '..', '..');
+
+const read = (p) => JSON.parse(readFileSync(p, 'utf8'));
+
+const failures = [];
+const notes = [];
+function check(name, fn) {
+  try {
+    const note = fn();
+    if (note) notes.push(`  ok  ${name} — ${note}`);
+    else notes.push(`  ok  ${name}`);
+  } catch (err) {
+    failures.push(`FAIL  ${name}\n      ${err.message}`);
+  }
+}
+
+function assertSameSet(label, a, b, aName, bName) {
+  const missingFromB = [...a].filter((x) => !b.has(x)).sort();
+  const missingFromA = [...b].filter((x) => !a.has(x)).sort();
+  if (missingFromB.length || missingFromA.length) {
+    const parts = [];
+    if (missingFromB.length) parts.push(`in ${aName} but not ${bName}: ${missingFromB.join(', ')}`);
+    if (missingFromA.length) parts.push(`in ${bName} but not ${aName}: ${missingFromA.join(', ')}`);
+    throw new Error(`${label}\n      ${parts.join('\n      ')}`);
+  }
+}
+
+// ── Load every layer ─────────────────────────────────────────────────
+
+const manifest = read(join(WC, 'mcp-manifest.json'));
+const catalog = read(join(WC, 'a2ui', 'catalog.json'));
+const compact = read(join(WC, 'a2ui', 'catalog.compact.json'));
+
+const registered = new Set(
+  execSync(`grep -rho "customElements.define('[^']*'" "${join(WC, 'components')}" --include='*.ts' || true`)
+    .toString()
+    .split('\n')
+    .map((line) => (line.match(/'([^']+)'/) || [])[1])
+    .filter(Boolean)
+);
+
+const internal = new Set(manifest.internalElements ?? []);
+const publicSource = new Set([...registered].filter((n) => !internal.has(n)));
+
+const manifestNames = new Set(manifest.components.map((c) => c.name));
+const catalogNames = new Set(Object.keys(catalog.$defs.components));
+const compactNames = new Set(compact.components.map((c) => c.name));
+
+// ── Component-set parity ─────────────────────────────────────────────
+
+check('every registered element is accounted for', () => {
+  if (!registered.size) throw new Error('found no customElements.define calls — the grep is broken');
+  const unaccounted = [...registered].filter((n) => !manifestNames.has(n) && !internal.has(n));
+  if (unaccounted.length) {
+    throw new Error(
+      `element(s) register but appear in no layer and are not declared internal:\n` +
+        `      ${unaccounted.join(', ')}\n` +
+        `      Either export them, or add them to INTERNAL_ELEMENTS in scripts/generate-mcp-manifest.ts.`
+    );
+  }
+  return `${registered.size} registered, ${internal.size} declared internal`;
+});
+
+check('declared internals actually exist', () => {
+  const ghosts = [...internal].filter((n) => !registered.has(n));
+  if (ghosts.length) {
+    throw new Error(`declared internal but no longer registered: ${ghosts.join(', ')} — stale entry`);
+  }
+  const leaked = [...internal].filter((n) => manifestNames.has(n));
+  if (leaked.length) throw new Error(`declared internal but present in the manifest: ${leaked.join(', ')}`);
+  return internal.size ? [...internal].join(', ') : 'none';
+});
+
+check('source (minus internals) == manifest', () =>
+  assertSameSet('component sets differ', publicSource, manifestNames, 'source', 'manifest'));
+
+check('manifest == catalog', () =>
+  assertSameSet('component sets differ', manifestNames, catalogNames, 'manifest', 'catalog'));
+
+check('catalog == compact', () =>
+  assertSameSet('component sets differ', catalogNames, compactNames, 'catalog', 'compact'));
+
+const reactPath = join(WC, 'react-manifest.json');
+check('catalog == react manifest', () => {
+  if (!existsSync(reactPath)) throw new Error('react-manifest.json is missing');
+  const react = read(reactPath);
+  const names = new Set((react.components ?? []).map((c) => c.tagName ?? c.name));
+  assertSameSet('component sets differ', catalogNames, names, 'catalog', 'react');
+});
+
+const cemPath = join(REPO, 'custom-elements.json');
+check('catalog == custom-elements.json', () => {
+  if (!existsSync(cemPath)) throw new Error('custom-elements.json is missing');
+  const cem = read(cemPath);
+  const names = new Set(
+    (cem.modules ?? []).flatMap((m) => (m.declarations ?? []).map((d) => d.tagName).filter(Boolean))
+  );
+  assertSameSet(
+    'component sets differ (note: build:custom-elements.json uses a shallower glob than build:mcp-manifest)',
+    catalogNames,
+    names,
+    'catalog',
+    'custom-elements.json'
+  );
+});
+
+// ── Field-level parity ───────────────────────────────────────────────
+
+check('catalog and compact agree on every prop and enum', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const catProps = def.properties?.props?.properties ?? {};
+    const cmpProps = compactByName.get(name)?.props ?? {};
+    assertSameSet(`${name}: prop sets differ`, new Set(Object.keys(catProps)), new Set(Object.keys(cmpProps)), 'catalog', 'compact');
+    for (const [prop, spec] of Object.entries(catProps)) {
+      const a = spec.enum ?? null;
+      const b = cmpProps[prop]?.enum ?? null;
+      if (JSON.stringify(a) !== JSON.stringify(b)) {
+        throw new Error(`${name}.${prop}: enum differs — catalog ${JSON.stringify(a)} vs compact ${JSON.stringify(b)}`);
+      }
+    }
+  }
+  const total = Object.values(catalog.$defs.components).reduce(
+    (n, d) => n + Object.keys(d.properties?.props?.properties ?? {}).length, 0);
+  return `${total} props`;
+});
+
+check('catalog and compact agree on containment', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const cmp = compactByName.get(name);
+    const catChildren = def.properties?.children !== undefined;
+    if (catChildren !== (cmp.acceptsChildren === true)) {
+      throw new Error(`${name}: catalog children=${catChildren} vs compact acceptsChildren=${cmp.acceptsChildren === true}`);
+    }
+    const catSlots = new Set(Object.keys(def.properties?.slots?.properties ?? {}));
+    assertSameSet(`${name}: slot sets differ`, catSlots, new Set(cmp.slots ?? []), 'catalog', 'compact');
+  }
+});
+
+check('manifest, catalog metadata, catalog schema and compact agree on events', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  const native = new Set(catalog['x-native-events'] ?? []);
+  if (!native.size) throw new Error('catalog declares no x-native-events — the validator reads that list from here');
+
+  let total = 0;
+  for (const component of manifest.components) {
+    const fromManifest = new Set(Object.keys(component.events ?? {}));
+    const def = catalog.$defs.components[component.name];
+    const fromMetadata = new Set(Object.keys(def['x-events'] ?? {}));
+    const fromCompact = new Set(compactByName.get(component.name)?.events ?? []);
+
+    assertSameSet(`${component.name}: events differ`, fromManifest, fromMetadata, 'manifest', 'catalog x-events');
+    assertSameSet(`${component.name}: events differ`, fromMetadata, fromCompact, 'catalog x-events', 'compact');
+
+    // The validatable schema must admit every declared event, and must not
+    // invent any. Compared by admission rather than by set equality because a
+    // component may declare a custom event that shadows a native name —
+    // `cre8-tag` dispatches its own `change` — in which case the native branch
+    // legitimately absorbs it.
+    const names = def.properties?.events?.propertyNames;
+    if (!names) throw new Error(`${component.name}: no properties.events — events are not schema-validated`);
+    const branches = names.anyOf ?? [names];
+    const explicit = new Set(branches.flatMap((b) => b.enum ?? []));
+    const refsNative = branches.some((b) => b.$ref === '#/$defs/NativeEventName');
+    const admits = (n) => explicit.has(n) || (refsNative && native.has(n));
+
+    const unadmitted = [...fromMetadata].filter((n) => !admits(n));
+    if (unadmitted.length) {
+      throw new Error(`${component.name}: declared but not admitted by properties.events: ${unadmitted.join(', ')}`);
+    }
+    const invented = [...explicit].filter((n) => !fromMetadata.has(n) && !native.has(n));
+    if (invented.length) {
+      throw new Error(`${component.name}: properties.events admits undeclared event(s): ${invented.join(', ')}`);
+    }
+    total += fromManifest.size;
+  }
+  return `${total} events across ${manifest.components.length} components, ${native.size} native`;
+});
+
+check('the schema and the renderer agree on text children', () => {
+  const renderer = readFileSync(join(WC, 'a2ui', 'renderer.ts'), 'utf8');
+  const rendersText = /typeof\s+child\s*===\s*['"]string['"]/.test(renderer);
+  const child = catalog.$defs.Child;
+  const schemaAllowsText = !!child?.oneOf?.some((b) => b.type === 'string');
+
+  if (rendersText && !schemaAllowsText) {
+    throw new Error(
+      'renderer.ts turns string children into text nodes, but the schema does not permit them.\n' +
+        '      Text renders yet fails validation, and no schema-constrained generator can emit it.'
+    );
+  }
+  if (!rendersText && schemaAllowsText) {
+    throw new Error('the schema permits text children but the renderer no longer handles them');
+  }
+
+  // Every containment point must route through Child, or the ones that don't
+  // silently keep the old behaviour.
+  const offenders = [];
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const children = def.properties?.children;
+    if (children && children.items?.$ref !== '#/$defs/Child') offenders.push(`${name}.children`);
+    for (const [slot, spec] of Object.entries(def.properties?.slots?.properties ?? {})) {
+      if (spec.items?.$ref !== '#/$defs/Child') offenders.push(`${name}.slots.${slot}`);
+    }
+  }
+  if (offenders.length) {
+    throw new Error(`containment not routed through $defs/Child: ${offenders.slice(0, 5).join(', ')}`);
+  }
+
+  // A document root is a component; bare text is not a document.
+  if (catalog.properties?.root?.$ref !== '#/$defs/Component') {
+    throw new Error('the document root must be a Component, not a Child');
+  }
+  return `${offenders.length === 0 ? 'all containment routed through Child' : ''}`;
+});
+
+check('the runtime validator reads its native-event list from the catalog', () => {
+  const source = readFileSync(join(WC, 'a2ui', 'registry.ts'), 'utf8');
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+  if (!/x-native-events/.test(code)) {
+    throw new Error('registry.ts no longer reads x-native-events — it has grown a second copy of the list');
+  }
+  if (/const\s+NATIVE_DOM_EVENTS\s*=\s*new Set\(\[/.test(code)) {
+    throw new Error('registry.ts hardcodes a native-event list again; read catalog["x-native-events"] instead');
+  }
+});
+
+check('the catalog matches the manifest it was generated from', () => {
+  if (catalog['x-a2ui']?.libraryVersion !== manifest.version) {
+    throw new Error(
+      `catalog was built from version ${catalog['x-a2ui']?.libraryVersion}, manifest is ${manifest.version} — regenerate with build:a2ui:catalog`
+    );
+  }
+  if (compact.libraryVersion !== manifest.version) {
+    throw new Error(`compact was built from version ${compact.libraryVersion}, manifest is ${manifest.version}`);
+  }
+  return `all at ${manifest.version}`;
+});
+
+// ── Report ───────────────────────────────────────────────────────────
+
+for (const note of notes) console.log(note);
+if (failures.length) {
+  console.error('\n' + failures.join('\n'));
+  console.error(`\n${failures.length} layer(s) out of parity`);
+  process.exit(1);
+}
+console.log(`\nok — ${notes.length} parity checks passed; every layer agrees`);

package/a2ui/generate-catalog.mjs

@@ -6,11 +6,56 @@ import { dirname, resolve } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const manifestPath = resolve(__dirname, '..', 'mcp-manifest.json');
 const outPath = resolve(__dirname, 'catalog.json');
+const compactOutPath = resolve(__dirname, 'catalog.compact.json');
 
 const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
 
 const QUOTED_LITERAL = /^"([^"]*)"$/;
 
+/**
+ * Native DOM events, bindable on every component.
+ *
+ * Emitted into the catalog as `x-native-events` so the runtime validator can
+ * read it from there rather than keeping its own copy. Two lists that must stay
+ * equal is exactly the drift this pipeline is supposed to prevent, so there is
+ * one list and it lives here, next to the schema it produces.
+ *
+ * A component's `@fires` tags describe only what it dispatches itself, so these
+ * can never be discovered from source — binding `click` to a button is both the
+ * most common thing an agent does and undocumentable by the analyzer.
+ */
+const NATIVE_DOM_EVENTS = [
+  'click', 'dblclick', 'contextmenu',
+  'mousedown', 'mouseup', 'mouseenter', 'mouseleave', 'mouseover', 'mouseout', 'mousemove',
+  'pointerdown', 'pointerup', 'pointerenter', 'pointerleave',
+  'touchstart', 'touchend', 'touchmove', 'touchcancel',
+  'keydown', 'keyup', 'keypress',
+  'focus', 'blur', 'focusin', 'focusout',
+  'input', 'change', 'submit', 'reset', 'invalid', 'select',
+  'scroll', 'wheel', 'resize',
+  'copy', 'cut', 'paste',
+  'drag', 'dragstart', 'dragend', 'dragenter', 'dragleave', 'dragover', 'drop',
+  'load', 'error',
+];
+
+/** Mirrors the `EventBinding` union in types.ts. */
+const EVENT_BINDING_SCHEMA = {
+  description: 'A handler name, or an object naming the handler plus dispatch options.',
+  oneOf: [
+    { type: 'string', minLength: 1 },
+    {
+      type: 'object',
+      required: ['handler'],
+      additionalProperties: false,
+      properties: {
+        handler: { type: 'string', minLength: 1 },
+        stopPropagation: { type: 'boolean' },
+        preventDefault: { type: 'boolean' },
+      },
+    },
+  ],
+};
+
 const SELECT_OPTION_SCHEMA = {
   type: 'object',
   required: ['label', 'value'],
@@ -291,7 +336,7 @@ function buildComponent(c) {
     def.properties.children = {
       type: 'array',
       description: (rawSlots.default?.description || '').trim() || 'Child instances rendered into the default slot.',
-      items: { $ref: '#/$defs/Component' },
+      items: { $ref: '#/$defs/Child' },
     };
   } else if (hasSlots) {
     const slotProps = {};
@@ -301,7 +346,7 @@ function buildComponent(c) {
       slotProps[name] = {
         type: 'array',
         description: (slot.description || '').trim(),
-        items: { $ref: '#/$defs/Component' },
+        items: { $ref: '#/$defs/Child' },
       };
       slotDescriptions[name] = (slot.description || '').trim();
     }
@@ -316,6 +361,24 @@ function buildComponent(c) {
 
   if (Object.keys(events).length) def['x-events'] = events;
 
+  // Events are declared under `properties`, alongside props and slots, rather
+  // than living only in `x-events` metadata. Previously the component defs were
+  // `additionalProperties: false` with no `events` key at all, so events were
+  // documented but second-class — and an invented event name validated cleanly.
+  // Native events are always permitted; declared custom events are added on top.
+  def.properties.events = {
+    type: 'object',
+    description:
+      'Event bindings. Each key is an event name; the value names the handler to emit.',
+    // Native names are `$ref`'d rather than inlined. Repeating all 46 on each of
+    // 85 components cost ~57 KB and made the catalog a third larger for no
+    // information gain.
+    propertyNames: Object.keys(events).length
+      ? { anyOf: [{ $ref: '#/$defs/NativeEventName' }, { enum: Object.keys(events).sort() }] }
+      : { $ref: '#/$defs/NativeEventName' },
+    additionalProperties: { $ref: '#/$defs/EventBinding' },
+  };
+
   return def;
 }
 
@@ -332,6 +395,9 @@ const catalog = {
   $id: `https://cre8.dev/a2ui/catalogs/cre8-wc/${manifest.version}`,
   title: 'cre8-wc A2UI Catalog',
   description: manifest.description,
+  // Single source of truth for the native-event allowlist. The runtime validator
+  // reads it from here instead of keeping a second copy that could drift.
+  'x-native-events': NATIVE_DOM_EVENTS,
   'x-a2ui': {
     catalogId: 'cre8-wc',
     library: manifest.library,
@@ -349,6 +415,24 @@ const catalog = {
       description: 'A component instance in the cre8-wc catalog.',
       oneOf: componentRefs,
     },
+    // Slot content is a component *or* literal text. `renderer.ts` has always
+    // turned a bare string into a text node, but the schema never said so, and
+    // that gap is load-bearing rather than cosmetic: 56 of 85 components carry
+    // no text-bearing prop, so their entire visible content arrives this way. A
+    // schema-constrained generator — guided decoding, or any JSON-Schema-
+    // constrained model — could not give those components any content at all.
+    //
+    // `root` stays a Component deliberately: a document cannot be bare text.
+    Child: {
+      description:
+        'Slot content: either a nested component instance or literal text, which renders as a text node.',
+      oneOf: [{ $ref: '#/$defs/Component' }, { type: 'string' }],
+    },
+    EventBinding: EVENT_BINDING_SCHEMA,
+    NativeEventName: {
+      description: 'A native DOM event, bindable on any component.',
+      enum: [...NATIVE_DOM_EVENTS].sort(),
+    },
     components,
   },
 };
@@ -357,3 +441,57 @@ writeFileSync(outPath, JSON.stringify(catalog, null, 2) + '\n');
 console.log(
   `Wrote ${outPath} (${manifest.components.length} components, ${(JSON.stringify(catalog).length / 1024).toFixed(1)} KB)`
 );
+
+// The compact projection: the minimum a model needs to emit valid A2UI. Prose is
+// ~90% of the catalog's bytes and none of its decoding constraint, so dropping it
+// is what lets a small-context model see the design system at all.
+//
+// Emitted here rather than in a separate script so it cannot drift from the
+// catalog it projects.
+function compactProps(propsNode) {
+  const out = {};
+  for (const [name, spec] of Object.entries(propsNode?.properties ?? {})) {
+    out[name] = spec.enum ? { enum: spec.enum } : { type: spec.type ?? 'string' };
+  }
+  return out;
+}
+
+const compactComponents = Object.entries(components)
+  .map(([name, def]) => {
+    const props = def.properties ?? {};
+    const entry = { name, category: def['x-category'] ?? 'Uncategorized' };
+
+    if (props.props) {
+      entry.props = compactProps(props.props);
+      if (props.props.required?.length) entry.required = props.props.required;
+    }
+    // Containment is expressed two ways and consumers need both: `children` for
+    // plain containers, `slots` for named regions. Dropping either makes a
+    // container look like a leaf.
+    if (props.children) entry.acceptsChildren = true;
+    if (props.slots) entry.slots = Object.keys(props.slots.properties ?? {});
+    // Events live under `x-events`, not under `properties`, which makes them easy
+    // to miss — the studio's hand-rolled summary looked for them in the wrong
+    // place and so showed the model none of the 22 events the library emits.
+    const events = Object.keys(def['x-events'] ?? {});
+    if (events.length) entry.events = events;
+    return entry;
+  })
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+const compact = {
+  contractVersion: 1,
+  sourceCatalog: catalog.$id,
+  libraryVersion: manifest.version,
+  componentCount: compactComponents.length,
+  components: compactComponents,
+};
+
+writeFileSync(compactOutPath, JSON.stringify(compact, null, 2) + '\n');
+
+const fullBytes = JSON.stringify(components).length;
+const compactBytes = JSON.stringify(compact).length;
+console.log(
+  `Wrote ${compactOutPath} (${compactComponents.length} components, ` +
+    `${(compactBytes / 1024).toFixed(1)} KB, ${(fullBytes / compactBytes).toFixed(1)}x smaller)`
+);

package/a2ui/registry.js

@@ -87,6 +87,17 @@ function describeType(v) {
         return 'array';
     return typeof v;
 }
+/**
+ * Native DOM events, bindable on any component.
+ *
+ * Read from the catalog's `x-native-events` rather than kept here, so there is
+ * one list rather than two that must be held equal. A component's `@fires` tags
+ * describe only what it dispatches itself, so these can never be derived from
+ * source — `click` on a button is legitimate and undocumentable.
+ */
+function nativeEvents(catalog) {
+    return new Set(catalog.schema['x-native-events'] ?? []);
+}
 export function validateSpec(spec, catalog, path = '$') {
     if (!spec || typeof spec !== 'object') {
         throw new Error(`${path}: spec must be an object`);
@@ -131,7 +142,24 @@ export function validateSpec(spec, catalog, path = '$') {
         if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
             throw new Error(`${path}.events: must be an object`);
         }
+        // Custom event *names* are checked against the catalog, the same way props
+        // and slots are. Previously only the binding shape was validated, so an
+        // invented event bound cleanly and then silently never fired — the worst
+        // failure mode available, since the UI renders and simply does nothing.
+        //
+        // Native DOM events are always allowed: `addEventListener` handles them on
+        // any element, and `@fires` documents only what a component dispatches
+        // itself. `click` on a button is legitimate and undocumented by design.
+        const declaredEvents = new Set(Object.keys(def['x-events'] ?? {}));
+        const native = nativeEvents(catalog);
         for (const [evtName, binding] of Object.entries(s.events)) {
+            if (!native.has(evtName) && !declaredEvents.has(evtName)) {
+                const available = [...declaredEvents].sort().join(', ');
+                throw new Error(`${path}.events.${evtName}: not a declared event on ${s.component}. ` +
+                    (available
+                        ? `Custom events available: ${available}`
+                        : `${s.component} declares no custom events`));
+            }
             if (typeof binding === 'string')
                 continue;
             if (!binding || typeof binding !== 'object') {

package/a2ui/registry.ts

@@ -100,6 +100,18 @@ function describeType(v: unknown): string {
   return typeof v;
 }
 
+/**
+ * Native DOM events, bindable on any component.
+ *
+ * Read from the catalog's `x-native-events` rather than kept here, so there is
+ * one list rather than two that must be held equal. A component's `@fires` tags
+ * describe only what it dispatches itself, so these can never be derived from
+ * source — `click` on a button is legitimate and undocumentable.
+ */
+function nativeEvents(catalog: RegisteredCatalog): Set<string> {
+  return new Set(catalog.schema['x-native-events'] ?? []);
+}
+
 export function validateSpec(spec: unknown, catalog: RegisteredCatalog, path = '$'): asserts spec is ComponentSpec {
   if (!spec || typeof spec !== 'object') {
     throw new Error(`${path}: spec must be an object`);
@@ -147,7 +159,26 @@ export function validateSpec(spec: unknown, catalog: RegisteredCatalog, path = '
     if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
       throw new Error(`${path}.events: must be an object`);
     }
+    // Custom event *names* are checked against the catalog, the same way props
+    // and slots are. Previously only the binding shape was validated, so an
+    // invented event bound cleanly and then silently never fired — the worst
+    // failure mode available, since the UI renders and simply does nothing.
+    //
+    // Native DOM events are always allowed: `addEventListener` handles them on
+    // any element, and `@fires` documents only what a component dispatches
+    // itself. `click` on a button is legitimate and undocumented by design.
+    const declaredEvents = new Set(Object.keys(def['x-events'] ?? {}));
+    const native = nativeEvents(catalog);
     for (const [evtName, binding] of Object.entries(s.events as Record<string, unknown>)) {
+      if (!native.has(evtName) && !declaredEvents.has(evtName)) {
+        const available = [...declaredEvents].sort().join(', ');
+        throw new Error(
+          `${path}.events.${evtName}: not a declared event on ${s.component}. ` +
+            (available
+              ? `Custom events available: ${available}`
+              : `${s.component} declares no custom events`)
+        );
+      }
       if (typeof binding === 'string') continue;
       if (!binding || typeof binding !== 'object') {
         throw new Error(`${path}.events.${evtName}: must be a string or { handler } object`);

package/a2ui/smoke-test.mjs

@@ -73,9 +73,43 @@ try {
   console.log('slot reject:', e.message);
 }
 
+// An invented custom event used to bind cleanly and then never fire — the UI
+// renders and silently does nothing, which is worse than an error.
+const badEvent = { component: 'cre8-modal', events: { 'totally-made-up': 'x' } };
+try {
+  validateSpec(badEvent, cat);
+  console.error('FAIL: expected rejection of undeclared event');
+  process.exit(1);
+} catch (e) {
+  console.log('event reject:', e.message);
+}
+
+// Binding a real event to the wrong component is the same failure wearing a
+// disguise: the name exists in the library, just not on this component.
+const misattributed = { component: 'cre8-button', events: { 'modal-close': 'x' } };
+try {
+  validateSpec(misattributed, cat);
+  console.error('FAIL: expected rejection of an event from another component');
+  process.exit(1);
+} catch (e) {
+  console.log('misattributed event reject:', e.message);
+}
+
+// Native DOM events stay bindable on anything — `@fires` documents only what a
+// component dispatches itself, so the catalog can never list `click`.
+for (const native of ['click', 'input', 'submit', 'keydown', 'focus']) {
+  validateSpec({ component: 'cre8-button', events: { [native]: 'h' } }, cat);
+}
+console.log('native events accepted on an undocumented component: ok');
+
+// Binds one native event and one custom event, on the component that actually
+// dispatches the custom one. It used to bind `split-button-text-click` to a
+// plain `cre8-button`, which no `cre8-button` ever fires — a binding that
+// renders cleanly and then silently does nothing. Event-name validation now
+// rejects that, so the example has to be a real pairing.
 const eventSpec = {
-  component: 'cre8-button',
-  props: { text: 'Save', variant: 'primary' },
+  component: 'cre8-split-button',
+  props: { buttonText: 'Save' },
   events: {
     click: { handler: 'save-record', stopPropagation: true },
     'split-button-text-click': 'emit-telemetry',

package/a2ui/types.d.ts

@@ -24,6 +24,11 @@ export interface CatalogSchema {
     $defs?: {
         components?: Record<string, CatalogComponentDef>;
     };
+    /**
+     * Native DOM events bindable on any component. The single source of truth —
+     * the runtime validator reads this rather than keeping its own copy.
+     */
+    'x-native-events'?: string[];
     'x-a2ui'?: {
         catalogId?: string;
         library?: string;

package/a2ui/types.ts

@@ -30,6 +30,11 @@ export interface CatalogSchema {
   $defs?: {
     components?: Record<string, CatalogComponentDef>;
   };
+  /**
+   * Native DOM events bindable on any component. The single source of truth —
+   * the runtime validator reads this rather than keeping its own copy.
+   */
+  'x-native-events'?: string[];
   'x-a2ui'?: {
     catalogId?: string;
     library?: string;

package/lib/a2ui/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../a2ui/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAKxE;AA+FD,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,SAAM,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,CA+EjH"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../a2ui/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAKxE;AA2GD,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,SAAM,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,CAkGjH"}