@genesislcap/ts-builder 14.418.2 → 14.419.1

package/src/react-wrapper-generator.ts

@@ -0,0 +1,823 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+// ── CEM type shapes ──────────────────────────────────────────────────────────
+
+type CEMType = { text?: string };
+type CEMEvent = { name?: string; type?: CEMType; description?: string };
+type CEMSuperclass = { name?: string; package?: string };
+type CEMMember = {
+  name?: string;
+  fieldName?: string;
+  attribute?: string | null;
+  kind?: string;
+  privacy?: string;
+  type?: CEMType;
+};
+type CEMDeclaration = {
+  name?: string;
+  customElement?: boolean;
+  tagName?: string;
+  superclass?: CEMSuperclass;
+  members?: CEMMember[];
+  attributes?: CEMMember[];
+  events?: CEMEvent[];
+};
+type CEMModule = { path?: string; declarations?: CEMDeclaration[] };
+type CEMManifest = { modules?: CEMModule[] };
+type CEMElementEntry = { declaration: CEMDeclaration; modulePath: string };
+
+// ── Type import state ────────────────────────────────────────────────────────
+
+type TypeImportState = {
+  importsByIdentifier: Map<string, string>;
+  ambiguousIdentifiers: Set<string>;
+  usedImports: Map<string, Set<string>>;
+  wildcardExportModules: Set<string>;
+};
+
+// ── Public API return type ───────────────────────────────────────────────────
+
+type GenerateResult =
+  | { generated: true; path: string }
+  | { generated: false; reason: string };
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const PRIMITIVE_UNION_REGEX =
+  /^(?:\s*(?:string|number|boolean|bigint|null|undefined|unknown|any|void|'[^']*'|"[^"]*"|`[^`]*`|(?:\d+(?:\.\d+)?))\s*)(?:\|\s*(?:string|number|boolean|bigint|null|undefined|unknown|any|void|'[^']*'|"[^"]*"|`[^`]*`|(?:\d+(?:\.\d+)?))\s*)*$/;
+
+const IDENTIFIER_TOKEN_REGEX = /[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*/g;
+
+const PRIMITIVE_TOKENS = new Set([
+  'true', 'false', 'null', 'undefined', 'string', 'number', 'boolean',
+  'bigint', 'symbol', 'unknown', 'any', 'void', 'never',
+]);
+
+const KNOWN_TYPE_NAMES = new Set([
+  'Array', 'ReadonlyArray', 'Promise', 'Record', 'Partial', 'Required', 'Pick', 'Omit',
+  'Map', 'Set', 'WeakMap', 'WeakSet', 'Date', 'RegExp', 'Error', 'Node', 'Element',
+  'HTMLElement', 'SVGElement', 'Event', 'CustomEvent', 'MouseEvent', 'KeyboardEvent',
+  'FocusEvent', 'InputEvent', 'PointerEvent', 'WheelEvent', 'DragEvent', 'SubmitEvent',
+  'AbortSignal', 'DOMRect', 'Document', 'Window', 'URL', 'URLSearchParams',
+  'CSSStyleDeclaration', 'Intl.Locale',
+]);
+
+/**
+ * DOM event classes that map directly to `(event: T) => void`.
+ * Excludes bare `CustomEvent` which needs special handling for its detail type.
+ */
+const DOM_EVENT_CLASS_NAMES = new Set([
+  'Event', 'MouseEvent', 'KeyboardEvent', 'FocusEvent', 'InputEvent',
+  'PointerEvent', 'WheelEvent', 'DragEvent', 'SubmitEvent',
+]);
+
+/**
+ * React DOM reserves these `on*` prop names for native/synthetic events. When a CEM event
+ * name maps to the same handler (e.g. `click` → `onClick`), we must not emit a duplicate
+ * wrapper prop or it clashes with React's built-in typings.
+ *
+ * Resolved at startup from the consumer project's `@types/react/index.d.ts` so the set stays
+ * current without manual maintenance. Falls back to a static snapshot when `@types/react` is
+ * not installed (e.g. JS-only consumers — in that case the exclusion set is irrelevant anyway).
+ */
+function loadReactEventHandlerNames(): Set<string> {
+  try {
+    const typesPath = require.resolve('@types/react/index.d.ts');
+    const content = readFileSync(typesPath, 'utf-8');
+    const names = new Set<string>();
+    for (const m of content.matchAll(/\b(on[A-Z][a-zA-Z]+)\??\s*:/g)) {
+      names.add(m[1]);
+    }
+    if (names.size > 20) return names;
+  } catch {}
+  // Static snapshot — kept as fallback only.
+  return new Set([
+    'onCopy', 'onCut', 'onPaste', 'onCompositionEnd', 'onCompositionStart', 'onCompositionUpdate',
+    'onFocus', 'onBlur', 'onChange', 'onBeforeInput', 'onInput', 'onReset', 'onSubmit',
+    'onInvalid', 'onLoad', 'onError', 'onKeyDown', 'onKeyPress', 'onKeyUp', 'onAbort',
+    'onCanPlay', 'onCanPlayThrough', 'onDurationChange', 'onEmptied', 'onEncrypted', 'onEnded',
+    'onLoadedData', 'onLoadedMetadata', 'onLoadStart', 'onPause', 'onPlay', 'onPlaying',
+    'onProgress', 'onRateChange', 'onResize', 'onSeeked', 'onSeeking', 'onStalled', 'onSuspend',
+    'onTimeUpdate', 'onVolumeChange', 'onWaiting', 'onAuxClick', 'onClick', 'onContextMenu',
+    'onDoubleClick', 'onDrag', 'onDragEnd', 'onDragEnter', 'onDragExit', 'onDragLeave',
+    'onDragOver', 'onDragStart', 'onDrop', 'onMouseDown', 'onMouseEnter', 'onMouseLeave',
+    'onMouseMove', 'onMouseOut', 'onMouseOver', 'onMouseUp', 'onSelect', 'onTouchCancel',
+    'onTouchEnd', 'onTouchMove', 'onTouchStart', 'onPointerOver', 'onPointerEnter',
+    'onPointerDown', 'onPointerMove', 'onPointerUp', 'onPointerCancel', 'onPointerOut',
+    'onPointerLeave', 'onGotPointerCapture', 'onLostPointerCapture', 'onScroll', 'onWheel',
+    'onAnimationStart', 'onAnimationEnd', 'onAnimationIteration', 'onTransitionEnd', 'onToggle',
+  ]);
+}
+
+const REACT_NATIVE_EVENT_HANDLER_NAMES = loadReactEventHandlerNames();
+
+/**
+ * Emitted into every react.d.ts.
+ * onChange/onInput use method signatures for bivariant parameter checking so both
+ * native Event and CustomEvent callbacks are accepted without cast.
+ */
+const HELPER_TYPES = `\
+/** @internal Maps a web component class to its public props only.
+ * keyof T skips private/protected members, so this avoids the TS error
+ * "property may not be private or protected" on exported anonymous types. */
+type PublicOf<T> = { [K in keyof T]?: T[K] };
+
+/** @internal Safe React HTML attributes for web component wrappers.
+ * onChange/onInput use method signatures for bivariant parameter checking so both
+ * native Event and CustomEvent callbacks are accepted. */
+interface HTMLWCProps extends React.AriaAttributes {
+  className?: string; style?: React.CSSProperties; id?: string; slot?: string;
+  tabIndex?: number; dir?: string; lang?: string; title?: string;
+  onClick?: React.MouseEventHandler<HTMLElement>;
+  onDoubleClick?: React.MouseEventHandler<HTMLElement>;
+  onContextMenu?: React.MouseEventHandler<HTMLElement>;
+  onMouseEnter?: React.MouseEventHandler<HTMLElement>;
+  onMouseLeave?: React.MouseEventHandler<HTMLElement>;
+  onMouseDown?: React.MouseEventHandler<HTMLElement>;
+  onMouseUp?: React.MouseEventHandler<HTMLElement>;
+  onMouseMove?: React.MouseEventHandler<HTMLElement>;
+  onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
+  onKeyUp?: React.KeyboardEventHandler<HTMLElement>;
+  onFocus?: React.FocusEventHandler<HTMLElement>;
+  onBlur?: React.FocusEventHandler<HTMLElement>;
+  onScroll?: React.UIEventHandler<HTMLElement>;
+  onWheel?: React.WheelEventHandler<HTMLElement>;
+  onChange?(e: Event): void;
+  onInput?(e: Event): void;
+}
+`;
+
+// ── String utilities ─────────────────────────────────────────────────────────
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function normalizePropertyName(name: string): string | null {
+  let s = name.trim();
+  if (!s) return null;
+
+  const bracketQuoted = s.match(/^\[\s*['"](.+?)['"]\s*\]$/);
+  if (bracketQuoted) {
+    s = bracketQuoted[1];
+  } else {
+    const bracket = s.match(/^\[\s*(.+?)\s*\]$/);
+    if (bracket) s = bracket[1];
+    const quoted = s.match(/^['"](.+?)['"]$/);
+    if (quoted) s = quoted[1];
+  }
+
+  s = s.trim();
+  if (!s || s.includes('\n') || s.includes('\r')) return null;
+  return s;
+}
+
+function toPascalCase(value: string): string {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join('');
+}
+
+// ── Type resolution utilities ─────────────────────────────────────────────────
+
+function isPrimitiveToken(token: string): boolean {
+  return PRIMITIVE_TOKENS.has(token);
+}
+
+function isKnownTypeIdentifier(identifier: string): boolean {
+  return KNOWN_TYPE_NAMES.has(identifier) || identifier.startsWith('globalThis.');
+}
+
+function getIdentifierTokens(typeText: string): string[] {
+  return typeText.match(IDENTIFIER_TOKEN_REGEX) ?? [];
+}
+
+function createTypeImportState(): TypeImportState {
+  return {
+    importsByIdentifier: new Map(),
+    ambiguousIdentifiers: new Set(),
+    usedImports: new Map(),
+    wildcardExportModules: new Set(),
+  };
+}
+
+function registerTypeImport(state: TypeImportState, identifier: string, moduleSpecifier: string): void {
+  if (state.ambiguousIdentifiers.has(identifier)) return;
+
+  const existing = state.importsByIdentifier.get(identifier);
+  if (existing && existing !== moduleSpecifier) {
+    state.importsByIdentifier.delete(identifier);
+    state.ambiguousIdentifiers.add(identifier);
+    return;
+  }
+
+  if (!existing) {
+    state.importsByIdentifier.set(identifier, moduleSpecifier);
+  }
+}
+
+function trackImportedIdentifierUsage(state: TypeImportState, identifier: string, moduleSpecifier: string): void {
+  if (!state.usedImports.has(moduleSpecifier)) {
+    state.usedImports.set(moduleSpecifier, new Set());
+  }
+  state.usedImports.get(moduleSpecifier)!.add(identifier);
+}
+
+function isBareModuleSpecifier(moduleSpecifier: string): boolean {
+  return !!moduleSpecifier && !moduleSpecifier.startsWith('.') && !moduleSpecifier.startsWith('/');
+}
+
+function canUseComplexType(typeText: string, typeImportState?: TypeImportState): boolean {
+  if (!typeText) return false;
+  if (/[{};=]/.test(typeText) || /=>/.test(typeText)) return false;
+  if (!/^[A-Za-z0-9_$<>\[\]()|&,.?'"`\s:-]+$/.test(typeText)) return false;
+
+  for (const token of getIdentifierTokens(typeText)) {
+    if (isPrimitiveToken(token) || isKnownTypeIdentifier(token)) continue;
+
+    const root = token.split('.')[0];
+    if (
+      typeImportState &&
+      !typeImportState.ambiguousIdentifiers.has(root) &&
+      typeImportState.importsByIdentifier.has(root)
+    ) {
+      trackImportedIdentifierUsage(typeImportState, root, typeImportState.importsByIdentifier.get(root)!);
+      continue;
+    }
+
+    return false;
+  }
+
+  return true;
+}
+
+function toSafeType(typeText?: string, typeImportState?: TypeImportState): string {
+  if (!typeText) return 'unknown';
+  const normalized = normalizeWhitespace(typeText);
+  if (!normalized) return 'unknown';
+
+  if (PRIMITIVE_UNION_REGEX.test(normalized)) return normalized;
+
+  if (normalized.endsWith('[]') && PRIMITIVE_UNION_REGEX.test(normalized.slice(0, -2).trim())) {
+    return normalized;
+  }
+
+  return canUseComplexType(normalized, typeImportState) ? normalized : 'unknown';
+}
+
+function extractDetailTypeFromDescription(description?: string): string | undefined {
+  return description?.match(/detail:\s*`([^`]+)`/)?.[1]?.trim();
+}
+
+/**
+ * Maps a CEM event type string to a TypeScript handler signature.
+ *
+ * - Known DOM event classes (Event, MouseEvent, FocusEvent, etc.) → `(event: T) => void`
+ * - `CustomEvent<Detail>` → `(event: CustomEvent<Detail>) => void`
+ * - Bare `CustomEvent` or unresolvable types → `(event: CustomEvent<unknown>) => void`
+ */
+function toEventHandlerType(
+  typeText?: string,
+  typeImportState?: TypeImportState,
+  description?: string,
+): string {
+  if (typeText) {
+    const normalized = typeText.trim();
+
+    // Known DOM event classes map directly — not wrapped as CustomEvent<T> detail.
+    if (DOM_EVENT_CLASS_NAMES.has(normalized)) {
+      return `(event: ${normalized}) => void`;
+    }
+
+    if (normalized.startsWith('CustomEvent<')) {
+      const match = normalized.match(/^CustomEvent<(.+)>$/);
+      if (match) {
+        const detailType = toSafeType(match[1]?.trim(), typeImportState);
+        return `(event: CustomEvent<${detailType}>) => void`;
+      }
+    }
+
+    // For any other resolvable non-DOM type, treat it as the CustomEvent detail payload.
+    if (normalized !== 'CustomEvent') {
+      const safeType = toSafeType(normalized, typeImportState);
+      if (safeType !== 'unknown') {
+        return `(event: CustomEvent<${safeType}>) => void`;
+      }
+    }
+  }
+
+  const detailFromDesc = extractDetailTypeFromDescription(description);
+  if (detailFromDesc) {
+    return `(event: CustomEvent<${toSafeType(detailFromDesc, typeImportState)}>) => void`;
+  }
+
+  return '(event: CustomEvent<unknown>) => void';
+}
+
+// ── Path helpers ─────────────────────────────────────────────────────────────
+
+function getCEMManifestPath(cwd: string, packageJson: Record<string, unknown>): string {
+  if (typeof packageJson.customElements === 'string' && packageJson.customElements.trim()) {
+    return resolve(cwd, packageJson.customElements);
+  }
+  return resolve(cwd, 'dist/custom-elements.json');
+}
+
+// CEM paths are relative to src/ (e.g. "src/entities/entities.ts").
+// react.mjs/cjs live in dist/ while compiled JS lives in dist/esm/.
+function cemModulePathToJsImport(modulePath: string): string {
+  let p = modulePath.startsWith('src/') ? modulePath.slice(4) : modulePath;
+  if (p.endsWith('.tsx')) p = `${p.slice(0, -4)}.js`;
+  else if (p.endsWith('.ts')) p = `${p.slice(0, -3)}.js`;
+  return `./esm/${p}`;
+}
+
+function cemModulePathToDtsImport(modulePath: string): string {
+  let p = modulePath.startsWith('src/') ? modulePath.slice(4) : modulePath;
+  const lastDot = p.lastIndexOf('.');
+  return `./${lastDot !== -1 ? p.slice(0, lastDot) : p}`;
+}
+
+// ── CEM traversal ─────────────────────────────────────────────────────────────
+
+function collectCustomElements(manifest: CEMManifest): CEMElementEntry[] {
+  const elements: CEMElementEntry[] = [];
+  for (const mod of manifest.modules ?? []) {
+    const modulePath = mod.path ?? '';
+    for (const decl of mod.declarations ?? []) {
+      if (decl.customElement && decl.tagName) {
+        elements.push({ declaration: decl, modulePath });
+      }
+    }
+  }
+  return elements;
+}
+
+function mergeUniqueByKey<T>(base: T[], extra: T[], getKey: (item: T) => string | null): T[] {
+  const merged = [...base];
+  const knownKeys = new Set(base.map(getKey).filter((k): k is string => !!k));
+  for (const item of extra) {
+    const key = getKey(item);
+    if (!key || !knownKeys.has(key)) {
+      merged.push(item);
+      if (key) knownKeys.add(key);
+    }
+  }
+  return merged;
+}
+
+function mergeDeclarationMetadata(base: CEMDeclaration, inherited: CEMDeclaration): CEMDeclaration {
+  const attrKey = (a: CEMMember) => normalizePropertyName(a.fieldName ?? a.name ?? '');
+  const nameKey = (m: CEMMember) => normalizePropertyName(m.name ?? '');
+  const eventKey = (e: CEMEvent) => normalizePropertyName(e.name ?? '');
+  return {
+    ...base,
+    attributes: mergeUniqueByKey(base.attributes ?? [], inherited.attributes ?? [], attrKey),
+    members: mergeUniqueByKey(base.members ?? [], inherited.members ?? [], nameKey),
+    events: mergeUniqueByKey(base.events ?? [], inherited.events ?? [], eventKey),
+  };
+}
+
+function createDeclarationLookup(manifest: CEMManifest): {
+  byTagAndName: Map<string, CEMDeclaration>;
+  byTag: Map<string, CEMDeclaration>;
+} {
+  const byTagAndName = new Map<string, CEMDeclaration>();
+  const byTag = new Map<string, CEMDeclaration>();
+  for (const mod of manifest.modules ?? []) {
+    for (const decl of mod.declarations ?? []) {
+      if (!decl.customElement || !decl.tagName) continue;
+      if (decl.name) byTagAndName.set(`${decl.tagName}::${decl.name}`, decl);
+      if (!byTag.has(decl.tagName)) byTag.set(decl.tagName, decl);
+    }
+  }
+  return { byTagAndName, byTag };
+}
+
+async function mergeFastInheritanceFromManifest(
+  cwd: string,
+  entries: CEMElementEntry[],
+): Promise<CEMElementEntry[]> {
+  const fastManifestPath = resolve(cwd, 'ms-fast-components/custom-elements.json');
+  if (!(await fileExists(fastManifestPath))) return entries;
+
+  const fastManifest = JSON.parse(await readFile(fastManifestPath, 'utf8')) as CEMManifest;
+  const { byTagAndName, byTag } = createDeclarationLookup(fastManifest);
+
+  return entries.map((entry) => {
+    const { declaration } = entry;
+    if (!declaration.tagName || declaration.superclass?.package !== '@microsoft/fast-components') {
+      return entry;
+    }
+
+    const inherited =
+      byTagAndName.get(`${declaration.tagName}::${declaration.name ?? ''}`) ??
+      byTagAndName.get(`${declaration.tagName}::${declaration.superclass?.name ?? ''}`) ??
+      byTag.get(declaration.tagName);
+
+    return inherited ? { ...entry, declaration: mergeDeclarationMetadata(declaration, inherited) } : entry;
+  });
+}
+
+// ── Wrapper event helpers ─────────────────────────────────────────────────────
+
+function buildWrapperEventEntries(
+  declaration: CEMDeclaration,
+): Array<{ handlerName: string; eventName: string }> {
+  const result: Array<{ handlerName: string; eventName: string }> = [];
+  const seen = new Set<string>();
+  for (const event of declaration.events ?? []) {
+    if (!event.name) continue;
+    const normalized = normalizePropertyName(event.name);
+    if (!normalized) continue;
+    const handlerName = `on${toPascalCase(normalized)}`;
+    if (!handlerName || REACT_NATIVE_EVENT_HANDLER_NAMES.has(handlerName) || seen.has(handlerName)) continue;
+    seen.add(handlerName);
+    result.push({ handlerName, eventName: event.name });
+  }
+  return result;
+}
+
+function groupEntriesByPath(entries: CEMElementEntry[]): Map<string, CEMElementEntry[]> {
+  const byPath = new Map<string, CEMElementEntry[]>();
+  for (const entry of entries) {
+    if (!byPath.has(entry.modulePath)) byPath.set(entry.modulePath, []);
+    byPath.get(entry.modulePath)!.push(entry);
+  }
+  return byPath;
+}
+
+function cloneTypeImportStateForWrapper(original: TypeImportState): TypeImportState {
+  return {
+    importsByIdentifier: new Map(original.importsByIdentifier),
+    ambiguousIdentifiers: new Set(original.ambiguousIdentifiers),
+    usedImports: new Map(),
+    wildcardExportModules: new Set(original.wildcardExportModules),
+  };
+}
+
+// ── Code generation ───────────────────────────────────────────────────────────
+
+function renderImportLines(usedImports: Map<string, Set<string>>): string[] {
+  return [...usedImports.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([spec, ids]) => `import type { ${[...ids].sort().join(', ')} } from '${spec}';`);
+}
+
+function generateReactWrapperJs(entries: CEMElementEntry[], format: 'esm' | 'cjs'): string {
+  const valid = entries.filter((e) => e.declaration.name && e.modulePath);
+  if (!valid.length) return '';
+
+  const esm = format === 'esm';
+  const lines: string[] = [
+    '/**',
+    ' * AUTO-GENERATED FILE - DO NOT EDIT.',
+    ' * Generated from custom-elements manifest.',
+    ' */',
+    '',
+  ];
+
+  if (!esm) lines.push("'use strict';", '');
+
+  if (esm) {
+    lines.push(
+      "import { provideReactWrapper } from '@microsoft/fast-react-wrapper';",
+      "import React from 'react';",
+    );
+  } else {
+    lines.push(
+      "const { provideReactWrapper } = require('@microsoft/fast-react-wrapper');",
+      "const React = require('react');",
+    );
+  }
+
+  for (const [modulePath, pathEntries] of [...groupEntriesByPath(valid).entries()].sort()) {
+    const sorted = [...pathEntries].sort((a, b) => a.declaration.name!.localeCompare(b.declaration.name!));
+    const jsPath = cemModulePathToJsImport(modulePath);
+    if (esm) {
+      lines.push(`import { ${sorted.map((e) => `${e.declaration.name} as ${e.declaration.name}WC`).join(', ')} } from '${jsPath}';`);
+    } else {
+      lines.push(`const { ${sorted.map((e) => `${e.declaration.name}: ${e.declaration.name}WC`).join(', ')} } = require('${jsPath}');`);
+    }
+  }
+
+  lines.push('', 'const { wrap } = provideReactWrapper(React);', '');
+
+  for (const { declaration } of valid) {
+    const name = declaration.name!;
+    const events = buildWrapperEventEntries(declaration);
+    const prefix = esm ? 'export const' : 'const';
+    if (!events.length) {
+      lines.push(`${prefix} ${name} = wrap(${name}WC);`);
+    } else {
+      lines.push(`${prefix} ${name} = wrap(${name}WC, {`);
+      lines.push('  events: {');
+      for (const { handlerName, eventName } of events) lines.push(`    ${handlerName}: '${eventName}',`);
+      lines.push('  },');
+      lines.push('});');
+    }
+    lines.push('');
+  }
+
+  if (!esm) {
+    lines.push('module.exports = {');
+    for (const { declaration } of valid) lines.push(`  ${declaration.name},`);
+    lines.push('};', '');
+  }
+
+  return lines.join('\n');
+}
+
+function generateReactWrapperDts(entries: CEMElementEntry[], typeImportState: TypeImportState): string {
+  const valid = entries.filter((e) => e.declaration.name && e.modulePath);
+  if (!valid.length) return '';
+
+  const wrapperTypeState = cloneTypeImportStateForWrapper(typeImportState);
+
+  const classImports: string[] = [];
+  for (const [modulePath, pathEntries] of [...groupEntriesByPath(valid).entries()].sort()) {
+    const names = [...pathEntries]
+      .sort((a, b) => a.declaration.name!.localeCompare(b.declaration.name!))
+      .map((e) => `${e.declaration.name} as ${e.declaration.name}WC`)
+      .join(', ');
+    classImports.push(`import type { ${names} } from '${cemModulePathToDtsImport(modulePath)}';`);
+  }
+
+  const declarationLines: string[] = [];
+  for (const { declaration } of valid) {
+    const name = declaration.name!;
+
+    // Build event lookup scoped to this element to avoid cross-element type pollution.
+    const eventsByName = new Map(
+      (declaration.events ?? [])
+        .filter((e) => e.name)
+        .map((e) => [e.name!, e] as const),
+    );
+
+    const eventLines = buildWrapperEventEntries(declaration).map(({ handlerName, eventName }) => {
+      const event = eventsByName.get(eventName);
+      const handlerType = toEventHandlerType(event?.type?.text, wrapperTypeState, event?.description);
+      return `      ${handlerName}?: ${handlerType};`;
+    });
+
+    declarationLines.push(
+      `export declare const ${name}: React.ForwardRefExoticComponent<`,
+      `  React.PropsWithChildren<`,
+      `    Omit<PublicOf<${name}WC>, 'children' | 'style'> &`,
+      `    HTMLWCProps & {`,
+      ...eventLines,
+      '    }',
+      `  > & React.RefAttributes<${name}WC>`,
+      '>;',
+      '',
+    );
+  }
+
+  return [
+    '/**',
+    ' * AUTO-GENERATED FILE - DO NOT EDIT.',
+    ' * Generated from custom-elements manifest.',
+    ' */',
+    '',
+    "import type React from 'react';",
+    ...classImports,
+    ...renderImportLines(wrapperTypeState.usedImports),
+    '',
+    HELPER_TYPES,
+    ...declarationLines,
+    'export {};',
+    '',
+  ].join('\n');
+}
+
+// ── File system helpers ───────────────────────────────────────────────────────
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function collectFilesRecursively(
+  rootDirectory: string,
+  isTargetFile: (fileName: string) => boolean,
+): Promise<string[]> {
+  const files: string[] = [];
+  const stack: string[] = [rootDirectory];
+  while (stack.length) {
+    const dir = stack.pop()!;
+    const dirEntries = await readdir(dir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+      const fullPath = resolve(dir, entry.name);
+      if (entry.isDirectory()) stack.push(fullPath);
+      else if (entry.isFile() && isTargetFile(entry.name)) files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+async function collectTypeMetadataFiles(
+  distDirectory: string,
+): Promise<{ apiJsonFiles: string[]; dtsFiles: string[] }> {
+  const [apiJsonFiles, dtsFiles] = await Promise.all([
+    collectFilesRecursively(distDirectory, (n) => n.endsWith('.api.json')),
+    collectFilesRecursively(distDirectory, (n) => n.endsWith('.d.ts')),
+  ]);
+  return { apiJsonFiles, dtsFiles };
+}
+
+// ── Type import state builders ────────────────────────────────────────────────
+
+function addCanonicalReferenceFromValue(value: unknown, state: TypeImportState): void {
+  if (!value || typeof value !== 'object') return;
+
+  if (Array.isArray(value)) {
+    for (const item of value) addCanonicalReferenceFromValue(item, state);
+    return;
+  }
+
+  const record = value as Record<string, unknown>;
+  if (typeof record.canonicalReference === 'string') {
+    const match = record.canonicalReference.match(/^(@[^!]+)!([^:]+):/);
+    if (match) {
+      const [, moduleSpecifier, identifier] = match;
+      if (identifier && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier)) {
+        registerTypeImport(state, identifier, moduleSpecifier);
+      }
+    }
+  }
+
+  for (const nested of Object.values(record)) {
+    if (nested && typeof nested === 'object') addCanonicalReferenceFromValue(nested, state);
+  }
+}
+
+function parseImportsFromDtsContent(content: string, state: TypeImportState): void {
+  const blockRe = /(?:import|export)\s+(?:type\s+)?\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g;
+  for (const match of content.matchAll(blockRe)) {
+    const moduleSpecifier = match[2] ?? '';
+    if (!isBareModuleSpecifier(moduleSpecifier)) continue;
+    for (const raw of (match[1] ?? '').split(',')) {
+      const entry = raw.trim();
+      if (!entry) continue;
+      const alias = entry.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/);
+      if (alias) {
+        registerTypeImport(state, alias[2], moduleSpecifier);
+        continue;
+      }
+      if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(entry)) registerTypeImport(state, entry, moduleSpecifier);
+    }
+  }
+
+  const reExportRe = /export\s+\*\s+from\s+['"]([^'"]+)['"]/g;
+  for (const match of content.matchAll(reExportRe)) {
+    const moduleSpecifier = match[1] ?? '';
+    if (isBareModuleSpecifier(moduleSpecifier)) state.wildcardExportModules.add(moduleSpecifier);
+  }
+}
+
+async function parseApiJsonFiles(filePaths: string[], state: TypeImportState): Promise<void> {
+  await Promise.all(
+    filePaths.map(async (filePath) => {
+      const json = JSON.parse(await readFile(filePath, 'utf8')) as unknown;
+      addCanonicalReferenceFromValue(json, state);
+    }),
+  );
+}
+
+async function parseDtsFiles(filePaths: string[], state: TypeImportState): Promise<void> {
+  await Promise.all(
+    filePaths.map(async (filePath) => {
+      parseImportsFromDtsContent(await readFile(filePath, 'utf8'), state);
+    }),
+  );
+}
+
+function mergeTypeImportStateInto(target: TypeImportState, source: TypeImportState): void {
+  for (const id of source.ambiguousIdentifiers) {
+    target.importsByIdentifier.delete(id);
+    target.ambiguousIdentifiers.add(id);
+  }
+  for (const [identifier, spec] of source.importsByIdentifier) {
+    registerTypeImport(target, identifier, spec);
+  }
+  for (const mod of source.wildcardExportModules) {
+    target.wildcardExportModules.add(mod);
+  }
+}
+
+async function findWorkspaceRoot(startDirectory: string): Promise<string> {
+  let dir = startDirectory;
+  while (true) {
+    const [hasPackages, hasPackageJson] = await Promise.all([
+      fileExists(resolve(dir, 'packages')),
+      fileExists(resolve(dir, 'package.json')),
+    ]);
+    if (hasPackages && hasPackageJson) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return startDirectory;
+    dir = parent;
+  }
+}
+
+async function getWorkspacePackageDirectoryByName(
+  workspaceRoot: string,
+  packageName: string,
+): Promise<string | undefined> {
+  const packagesDir = resolve(workspaceRoot, 'packages');
+  if (!(await fileExists(packagesDir))) return undefined;
+
+  const packageJsonFiles = await collectFilesRecursively(packagesDir, (n) => n === 'package.json');
+  for (const jsonPath of packageJsonFiles) {
+    const pkg = JSON.parse(await readFile(jsonPath, 'utf8')) as Record<string, unknown>;
+    if (pkg.name === packageName) return dirname(jsonPath);
+  }
+  return undefined;
+}
+
+async function enrichFromWorkspaceWildcardExports(cwd: string, state: TypeImportState): Promise<void> {
+  const workspaceRoot = await findWorkspaceRoot(cwd);
+  // for...of over a Set processes items added inside the loop (spec-guaranteed behaviour).
+  const pending = new Set(
+    [...state.wildcardExportModules].filter((m) => m.startsWith('@genesislcap/')),
+  );
+
+  for (const moduleSpecifier of pending) {
+    const pkgDir = await getWorkspacePackageDirectoryByName(workspaceRoot, moduleSpecifier);
+    if (!pkgDir) continue;
+
+    const distDir = resolve(pkgDir, 'dist');
+    if (!(await fileExists(distDir))) continue;
+
+    const refState = createTypeImportState();
+    const { apiJsonFiles, dtsFiles } = await collectTypeMetadataFiles(distDir);
+    await parseApiJsonFiles(apiJsonFiles, refState);
+    await parseDtsFiles(dtsFiles, refState);
+    mergeTypeImportStateInto(state, refState);
+
+    for (const mod of refState.wildcardExportModules) {
+      if (mod.startsWith('@genesislcap/')) pending.add(mod);
+    }
+  }
+}
+
+async function buildTypeImportState(cwd: string): Promise<TypeImportState> {
+  const state = createTypeImportState();
+  const distDir = resolve(cwd, 'dist');
+  if (!(await fileExists(distDir))) return state;
+
+  const { apiJsonFiles, dtsFiles } = await collectTypeMetadataFiles(distDir);
+  await parseApiJsonFiles(apiJsonFiles, state);
+  await parseDtsFiles(dtsFiles, state);
+  await enrichFromWorkspaceWildcardExports(cwd, state);
+
+  return state;
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export async function generateReactWrappers(cwd: string): Promise<GenerateResult> {
+  const packageJsonPath = resolve(cwd, 'package.json');
+  if (!(await fileExists(packageJsonPath))) {
+    return { generated: false, reason: 'No package.json found.' };
+  }
+
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as Record<string, unknown>;
+  const manifestPath = getCEMManifestPath(cwd, packageJson);
+  if (!(await fileExists(manifestPath))) {
+    return { generated: false, reason: 'No custom elements manifest found.' };
+  }
+
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as CEMManifest;
+  const rawEntries = collectCustomElements(manifest);
+  if (!rawEntries.length) {
+    return { generated: false, reason: 'No custom elements discovered in manifest.' };
+  }
+
+  const entries = await mergeFastInheritanceFromManifest(cwd, rawEntries);
+  const hasEvents = entries.some((e) => (e.declaration.events ?? []).length > 0);
+  if (!hasEvents) {
+    return { generated: false, reason: 'No custom events found in any element.' };
+  }
+
+  const dtsRoot = resolve(cwd, 'dist/dts');
+  await mkdir(dtsRoot, { recursive: true });
+
+  const typeImportState = await buildTypeImportState(cwd);
+  const reactDtsPath = resolve(dtsRoot, 'react.d.ts');
+
+  await Promise.all([
+    writeFile(resolve(cwd, 'dist/react.mjs'), generateReactWrapperJs(entries, 'esm'), 'utf8'),
+    writeFile(resolve(cwd, 'dist/react.cjs'), generateReactWrapperJs(entries, 'cjs'), 'utf8'),
+    writeFile(reactDtsPath, generateReactWrapperDts(entries, typeImportState), 'utf8'),
+  ]);
+
+  return { generated: true, path: reactDtsPath };
+}