objcjs-types 0.2.0 → 0.3.0

package/generator/emitter.ts

@@ -0,0 +1,2026 @@
+/**
+ * Generates TypeScript declaration files from parsed ObjC class data.
+ */
+
+import type {
+  ObjCClass,
+  ObjCMethod,
+  ObjCProperty,
+  ObjCProtocol,
+  ObjCIntegerEnum,
+  ObjCStringEnum,
+  ObjCStringEnumValue,
+  ObjCFunction
+} from "./ast-parser.ts";
+import type { FrameworkConfig } from "./frameworks.ts";
+import {
+  selectorToJS,
+  mapReturnType,
+  mapParamType,
+  qualTypeToEncoding,
+  STRUCT_TS_TYPES,
+  getKnownIntegerEnums,
+  getKnownStringEnums
+} from "./type-mapper.ts";
+
+const AUTOGEN_HEADER = `// AUTO-GENERATED by objcjs-types generator — DO NOT EDIT`;
+
+// --- Cached lookup maps for O(1) entity→framework resolution ---
+// Built lazily on first use, then reused for all subsequent calls.
+let _classFrameworkMap: Map<string, string> | null = null;
+let _protocolFrameworkMap: Map<string, string> | null = null;
+let _enumFrameworkMap: Map<string, string> | null = null;
+
+/** Build and cache the class→framework lookup map from the frameworks list. */
+function buildClassFrameworkMap(frameworks: FrameworkConfig[]): Map<string, string> {
+  if (_classFrameworkMap) return _classFrameworkMap;
+  _classFrameworkMap = new Map();
+  for (const fw of frameworks) {
+    for (const cls of fw.classes) {
+      _classFrameworkMap.set(cls, fw.name);
+    }
+  }
+  return _classFrameworkMap;
+}
+
+/** Build and cache the protocol→framework lookup map from the frameworks list. */
+function buildProtocolFrameworkMap(frameworks: FrameworkConfig[]): Map<string, string> {
+  if (_protocolFrameworkMap) return _protocolFrameworkMap;
+  _protocolFrameworkMap = new Map();
+  for (const fw of frameworks) {
+    if (fw.protocols) {
+      for (const proto of fw.protocols) {
+        _protocolFrameworkMap.set(proto, fw.name);
+      }
+    }
+  }
+  return _protocolFrameworkMap;
+}
+
+/** Build and cache the enum→framework lookup map from the frameworks list. */
+function buildEnumFrameworkMap(frameworks: FrameworkConfig[]): Map<string, string> {
+  if (_enumFrameworkMap) return _enumFrameworkMap;
+  _enumFrameworkMap = new Map();
+  for (const fw of frameworks) {
+    for (const name of fw.integerEnums) {
+      _enumFrameworkMap.set(name, fw.name);
+    }
+    for (const name of fw.stringEnums) {
+      _enumFrameworkMap.set(name, fw.name);
+    }
+  }
+  return _enumFrameworkMap;
+}
+
+/**
+ * Group class names that would collide on a case-insensitive filesystem.
+ * Returns a Map from the canonical filename (the name that survives — last in
+ * sorted order, since classes are emitted alphabetically and the last write wins)
+ * to the list of all class names that share that filename.
+ *
+ * Only groups with 2+ members represent actual collisions.
+ */
+export function groupCaseCollisions(classNames: string[]): Map<string, string[]> {
+  // Group by lowercased name
+  const byLower = new Map<string, string[]>();
+  for (const name of classNames) {
+    const key = name.toLowerCase();
+    if (!byLower.has(key)) {
+      byLower.set(key, []);
+    }
+    byLower.get(key)!.push(name);
+  }
+
+  const result = new Map<string, string[]>();
+  for (const group of byLower.values()) {
+    if (group.length < 2) continue;
+    // Sort so the "canonical" name (last write on disk) is deterministic.
+    // Classes are emitted in sorted order, so the last one in sort order is the survivor.
+    group.sort();
+    const canonical = group[group.length - 1]!;
+    result.set(canonical, group);
+  }
+  return result;
+}
+
+/**
+ * Given an ObjCClass, determine which struct type names it references
+ * (for import statements from ../structs/).
+ */
+function collectReferencedStructs(cls: ObjCClass): Set<string> {
+  const refs = new Set<string>();
+
+  function extractStructRefs(typeStr: string): void {
+    for (const structName of STRUCT_TS_TYPES) {
+      // Match the struct name as a whole word in the mapped type string.
+      // Struct types appear as bare names (e.g., "CGRect") or in union (e.g., "CGRect | null").
+      if (typeStr === structName || typeStr.startsWith(structName + " ")) {
+        refs.add(structName);
+      }
+    }
+  }
+
+  const allMethods = [...cls.instanceMethods, ...cls.classMethods];
+  for (const method of allMethods) {
+    extractStructRefs(mapReturnType(method.returnType, cls.name));
+    for (const param of method.parameters) {
+      extractStructRefs(mapParamType(param.type, cls.name));
+    }
+  }
+  for (const prop of cls.properties) {
+    extractStructRefs(mapReturnType(prop.type, cls.name));
+    // Setter param uses mapParamType, same type
+    extractStructRefs(mapParamType(prop.type, cls.name));
+  }
+
+  return refs;
+}
+
+/**
+ * Given an ObjCClass, determine which other class/protocol names it references
+ * (for import statements). Only includes classes/protocols we're generating.
+ */
+function collectReferencedClasses(
+  cls: ObjCClass,
+  allKnownClasses: Set<string>,
+  allKnownProtocols?: Set<string>
+): Set<string> {
+  const refs = new Set<string>();
+
+  // Superclass
+  if (cls.superclass && allKnownClasses.has(cls.superclass)) {
+    refs.add(cls.superclass);
+  }
+
+  // Conformed protocols (for the declaration-merging interface line)
+  if (allKnownProtocols) {
+    for (const protoName of cls.protocols) {
+      if (allKnownProtocols.has(protoName)) {
+        refs.add(protoName);
+      }
+    }
+  }
+
+  function extractClassRefs(typeStr: string): void {
+    // Find all _ClassName references that mapType would produce
+    const regex = /_(\w+)/g;
+    let match;
+    while ((match = regex.exec(typeStr)) !== null) {
+      const name = match[1]!;
+      if (name === cls.name) continue;
+      if (allKnownClasses.has(name) || allKnownProtocols?.has(name)) {
+        refs.add(name);
+      }
+    }
+  }
+
+  // Check all method signatures
+  const allMethods = [...cls.instanceMethods, ...cls.classMethods];
+  for (const method of allMethods) {
+    const retType = mapReturnType(method.returnType, cls.name);
+    extractClassRefs(retType);
+    for (const param of method.parameters) {
+      const pType = mapParamType(param.type, cls.name);
+      extractClassRefs(pType);
+    }
+  }
+
+  // Check properties (both getter return type and setter param type,
+  // which may differ due to conformer union expansion)
+  for (const prop of cls.properties) {
+    extractClassRefs(mapReturnType(prop.type, cls.name));
+    extractClassRefs(mapParamType(prop.type, cls.name));
+  }
+
+  // Remove self-reference
+  refs.delete(cls.name);
+
+  return refs;
+}
+
+/**
+ * Determine which framework a referenced class belongs to.
+ */
+function getClassFramework(className: string, frameworks: FrameworkConfig[]): string | null {
+  const map = buildClassFrameworkMap(frameworks);
+  return map.get(className) ?? null;
+}
+
+/**
+ * Determine which framework a class or protocol belongs to.
+ * Checks classes first, then protocols.
+ */
+function getEntityFramework(name: string, frameworks: FrameworkConfig[]): string | null {
+  const classMap = buildClassFrameworkMap(frameworks);
+  const classResult = classMap.get(name);
+  if (classResult) return classResult;
+  const protoMap = buildProtocolFrameworkMap(frameworks);
+  return protoMap.get(name) ?? null;
+}
+
+/**
+ * Custom JSDoc annotations for well-known methods that need additional context.
+ * Keyed by ObjC selector. These are prepended to any existing description.
+ */
+const METHOD_JSDOC_OVERRIDES: Record<string, string> = {
+  retain:
+    "**Do not call.** objc-js uses ARC — object lifetimes are managed automatically. Calling `retain()` will leak memory.",
+  release:
+    "**Do not call.** objc-js uses ARC — object lifetimes are managed automatically. Calling `release()` risks a double-free crash.",
+  autorelease:
+    "**Do not call.** objc-js uses ARC — object lifetimes are managed automatically. Calling `autorelease()` is unnecessary and unsafe.",
+  dealloc:
+    "**Do not call.** objc-js uses ARC — objects are deallocated automatically when the JavaScript garbage collector collects the wrapper.",
+  retainCount:
+    "**Do not use.** objc-js uses ARC — manual reference counting is not applicable. The value returned by this method is meaningless."
+};
+
+/**
+ * Build a JSDoc comment block from a description and/or deprecation info.
+ * Returns an array of lines (without trailing newline) or empty array.
+ */
+function buildJSDoc(opts: {
+  description?: string;
+  isDeprecated?: boolean;
+  deprecationMessage?: string;
+  indent?: string;
+  selector?: string;
+}): string[] {
+  const { description, isDeprecated, deprecationMessage, indent = "  ", selector } = opts;
+  const override = selector ? METHOD_JSDOC_OVERRIDES[selector] : undefined;
+  if (!description && !isDeprecated && !override) return [];
+
+  const parts: string[] = [];
+  if (override) {
+    parts.push(override);
+  }
+  if (description) {
+    // Strip any embedded "*/" that would prematurely close the JSDoc comment
+    parts.push(description.replace(/\*\//g, "").trim());
+  }
+  if (isDeprecated) {
+    parts.push(deprecationMessage ? `@deprecated ${deprecationMessage}` : "@deprecated");
+  }
+
+  // Single-line JSDoc for short content
+  if (parts.length === 1 && parts[0]!.length < 80) {
+    return [`${indent}/** ${parts[0]} */`];
+  }
+
+  // Multi-line JSDoc
+  const lines: string[] = [];
+  lines.push(`${indent}/**`);
+  for (let i = 0; i < parts.length; i++) {
+    if (i > 0 && parts[i - 1] !== "" && !parts[i]!.startsWith("@")) {
+      lines.push(`${indent} *`);
+    }
+    lines.push(`${indent} * ${parts[i]}`);
+  }
+  lines.push(`${indent} */`);
+  return lines;
+}
+
+/**
+ * Generate the method signature string for a single method.
+ */
+function emitMethodSignature(method: ObjCMethod, containingClass: string): string | null {
+  const jsName = selectorToJS(method.selector);
+  const returnType = mapReturnType(method.returnType, containingClass);
+
+  // Build parameter list (with deduplication for repeated names)
+  const params: string[] = [];
+  const seenNames = new Map<string, number>();
+  for (const param of method.parameters) {
+    const tsType = mapParamType(param.type, containingClass);
+    // Sanitize param name (avoid TS reserved words)
+    let safeName = sanitizeParamName(param.name);
+    // Deduplicate: append numeric suffix for repeated parameter names
+    const prev = seenNames.get(safeName) ?? 0;
+    seenNames.set(safeName, prev + 1);
+    if (prev > 0) {
+      safeName = `${safeName}${prev + 1}`;
+    }
+    params.push(`${safeName}: ${tsType}`);
+  }
+
+  const prefix = method.isClassMethod ? "static " : "";
+  const jsdoc = buildJSDoc({
+    description: method.description,
+    isDeprecated: method.isDeprecated,
+    deprecationMessage: method.deprecationMessage,
+    selector: method.selector
+  });
+  const jsdocStr = jsdoc.length > 0 ? jsdoc.join("\n") + "\n" : "";
+  return `${jsdocStr}  ${prefix}${jsName}(${params.join(", ")}): ${returnType};`;
+}
+
+const TS_RESERVED = new Set([
+  "break",
+  "case",
+  "catch",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "in",
+  "instanceof",
+  "new",
+  "return",
+  "switch",
+  "this",
+  "throw",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "class",
+  "const",
+  "enum",
+  "export",
+  "extends",
+  "import",
+  "super",
+  "implements",
+  "interface",
+  "let",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "static",
+  "yield",
+  "object",
+  "string",
+  "number",
+  "boolean",
+  "symbol",
+  "any",
+  "never",
+  "unknown",
+  // Not keywords, but cannot be used as parameter names in strict mode (modules)
+  "arguments",
+  "eval"
+]);
+
+export function sanitizeParamName(name: string): string {
+  if (TS_RESERVED.has(name)) return `${name}_`;
+  if (!name || /^\d/.test(name)) return `arg`;
+  return name;
+}
+
+/**
+ * Resolve a class/protocol name to its on-disk filename stem.
+ * For case-colliding classes, this returns the canonical name (the file that
+ * contains all colliding classes). For everything else, returns the name itself.
+ */
+function resolveFileName(name: string, classToFile?: Map<string, string>): string {
+  return classToFile?.get(name) ?? name;
+}
+
+/**
+ * Emit import statements for a set of referenced classes/protocols, grouped by framework.
+ */
+function emitImports(
+  refs: Set<string>,
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[],
+  classToFile?: Map<string, string>
+): string[] {
+  const lines: string[] = [];
+
+  // Group refs by framework
+  const importsByFramework = new Map<string, string[]>();
+  for (const refClass of refs) {
+    const fw = getEntityFramework(refClass, allFrameworks);
+    if (!fw) continue;
+    if (!importsByFramework.has(fw)) {
+      importsByFramework.set(fw, []);
+    }
+    importsByFramework.get(fw)!.push(refClass);
+  }
+
+  // When multiple classes are imported from the same file (because they were merged
+  // due to case collisions), combine them into a single import statement.
+  for (const [fwName, classes] of importsByFramework) {
+    classes.sort();
+
+    // Group classes by their resolved filename
+    const byFile = new Map<string, string[]>();
+    for (const refClass of classes) {
+      const fileName = resolveFileName(refClass, classToFile);
+      if (!byFile.has(fileName)) {
+        byFile.set(fileName, []);
+      }
+      byFile.get(fileName)!.push(refClass);
+    }
+
+    for (const [fileName, names] of byFile) {
+      const specifiers = names.map((n) => `_${n}`).join(", ");
+      if (fwName === currentFramework.name) {
+        lines.push(`import type { ${specifiers} } from "./${fileName}.js";`);
+      } else {
+        lines.push(`import type { ${specifiers} } from "../${fwName}/${fileName}.js";`);
+      }
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Cache for getMergedProtocols — avoids recomputing the same class's merged
+ * protocol set when multiple subclasses reference the same ancestor.
+ */
+const _mergedProtocolsCache = new Map<string, Set<string>>();
+
+/** Reset the merged protocols cache (call between generation runs). */
+export function resetMergedProtocolsCache(): void {
+  _mergedProtocolsCache.clear();
+}
+
+/**
+ * Determine which of a class's declared protocols can be safely merged via
+ * TypeScript declaration merging without causing type conflicts.
+ *
+ * A protocol conflicts if any of its methods/properties (including those
+ * inherited through extended protocols) have incompatible signatures with
+ * what the class inherits from its superclass chain + the protocols
+ * already merged onto ancestor classes.
+ *
+ * Returns the set of protocol names that are conflict-free and can be
+ * included in the `export interface _ClassName extends ...` merge line.
+ */
+function getMergedProtocols(
+  cls: ObjCClass,
+  allParsedClasses: Map<string, ObjCClass>,
+  allParsedProtocols: Map<string, ObjCProtocol>,
+  allKnownProtocols: Set<string>
+): Set<string> {
+  if (_mergedProtocolsCache.has(cls.name)) {
+    return _mergedProtocolsCache.get(cls.name)!;
+  }
+
+  // Build the inherited signature map: what TypeScript sees as the type of this
+  // class based on (a) superclass chain methods/properties, and (b) protocols
+  // ACTUALLY merged onto ancestor classes.
+  interface Sig {
+    returnType: string;
+    paramTypes: string[];
+    /** Whether this signature came from a protocol (optional in TS) vs a class body (non-optional). */
+    isOptional: boolean;
+  }
+  const inherited = new Map<string, Sig>();
+
+  // Walk the superclass chain (farthest ancestor first, so nearer ancestors
+  // override — but we use "first writer wins" so walk order matters: we want
+  // to walk from immediate parent upward)
+  let current = cls.superclass;
+  while (current) {
+    const parentCls = allParsedClasses.get(current);
+    if (!parentCls) break;
+
+    // Class's own instance properties (skip class properties — they're static
+    // in TS and don't conflict with protocol instance members in declaration merging)
+    for (const prop of parentCls.properties) {
+      if (prop.isClassProperty) continue;
+      if (!inherited.has(prop.name)) {
+        inherited.set(prop.name, {
+          returnType: mapReturnType(prop.type, parentCls.name),
+          paramTypes: [],
+          isOptional: false
+        });
+      }
+      if (!prop.readonly) {
+        const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+        if (!inherited.has(setterName)) {
+          inherited.set(setterName, {
+            returnType: "void",
+            paramTypes: [mapParamType(prop.type, parentCls.name)],
+            isOptional: false
+          });
+        }
+      }
+    }
+
+    // Class's own instance methods (skip class methods — they're static in TS
+    // and live on the constructor type, not the instance type, so they can't
+    // conflict with protocol interface members in declaration merging)
+    for (const method of parentCls.instanceMethods) {
+      const jsName = selectorToJS(method.selector);
+      if (!inherited.has(jsName)) {
+        inherited.set(jsName, {
+          returnType: mapReturnType(method.returnType, parentCls.name),
+          paramTypes: method.parameters.map((p) => mapParamType(p.type, parentCls.name)),
+          isOptional: false
+        });
+      }
+    }
+
+    // Only include protocols that were ACTUALLY merged onto this ancestor
+    // (i.e., passed conflict detection for that ancestor class)
+    const mergedProtos = getMergedProtocols(parentCls, allParsedClasses, allParsedProtocols, allKnownProtocols);
+    for (const mergedProtoName of mergedProtos) {
+      const mp = allParsedProtocols.get(mergedProtoName);
+      if (!mp) continue;
+      collectProtocolSignatures(mp, parentCls.name, inherited, allParsedProtocols);
+    }
+
+    current = parentCls.superclass ?? "";
+  }
+
+  // Also include this class's own instance method/property signatures
+  // (only instance-level — class/static members don't participate in
+  // interface declaration merging)
+  for (const method of cls.instanceMethods) {
+    const jsName = selectorToJS(method.selector);
+    if (!inherited.has(jsName)) {
+      inherited.set(jsName, {
+        returnType: mapReturnType(method.returnType, cls.name),
+        paramTypes: method.parameters.map((p) => mapParamType(p.type, cls.name)),
+        isOptional: false
+      });
+    }
+  }
+  for (const prop of cls.properties) {
+    if (prop.isClassProperty) continue;
+    if (!inherited.has(prop.name)) {
+      inherited.set(prop.name, {
+        returnType: mapReturnType(prop.type, cls.name),
+        paramTypes: [],
+        isOptional: false
+      });
+    }
+  }
+
+  // Now determine which of this class's declared protocols are conflict-free
+  const merged = new Set<string>();
+  for (const protoName of cls.protocols) {
+    if (!allKnownProtocols.has(protoName)) continue;
+    const proto = allParsedProtocols.get(protoName);
+    if (!proto) continue;
+    if (!checkProtocolConflicts(proto, cls.name, inherited, allParsedProtocols)) {
+      merged.add(protoName);
+    }
+  }
+
+  _mergedProtocolsCache.set(cls.name, merged);
+  return merged;
+}
+
+/**
+ * Check whether a protocol would conflict with a class's inherited signatures.
+ * Used by `getMergedProtocols` — prefer calling that function directly.
+ */
+function protocolConflictsWithClass(
+  cls: ObjCClass,
+  protoName: string,
+  allParsedClasses: Map<string, ObjCClass>,
+  allParsedProtocols: Map<string, ObjCProtocol>,
+  allKnownProtocols: Set<string>
+): boolean {
+  const merged = getMergedProtocols(cls, allParsedClasses, allParsedProtocols, allKnownProtocols);
+  return !merged.has(protoName);
+}
+
+/**
+ * Recursively collect method/property signatures from a protocol and its
+ * extended protocols into the given map.
+ */
+function collectProtocolSignatures(
+  proto: ObjCProtocol,
+  containingClass: string,
+  sigs: Map<string, { returnType: string; paramTypes: string[]; isOptional: boolean }>,
+  allParsedProtocols: Map<string, ObjCProtocol>
+): void {
+  // Only collect instance methods — class methods from protocols are not emitted
+  // in the TS interface, so they can't cause declaration merging conflicts.
+  for (const method of proto.instanceMethods) {
+    const jsName = selectorToJS(method.selector);
+    if (!sigs.has(jsName)) {
+      sigs.set(jsName, {
+        returnType: mapReturnType(method.returnType, containingClass),
+        paramTypes: method.parameters.map((p) => mapParamType(p.type, containingClass)),
+        isOptional: true
+      });
+    }
+  }
+  // Only collect instance properties (not class properties)
+  for (const prop of proto.properties) {
+    if (prop.isClassProperty) continue;
+    if (!sigs.has(prop.name)) {
+      sigs.set(prop.name, {
+        returnType: mapReturnType(prop.type, containingClass),
+        paramTypes: [],
+        isOptional: true
+      });
+    }
+    if (!prop.readonly) {
+      const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+      if (!sigs.has(setterName)) {
+        sigs.set(setterName, {
+          returnType: "void",
+          paramTypes: [mapParamType(prop.type, containingClass)],
+          isOptional: true
+        });
+      }
+    }
+  }
+  // Recurse into extended protocols
+  for (const ext of proto.extendedProtocols) {
+    const extProto = allParsedProtocols.get(ext);
+    if (extProto) {
+      collectProtocolSignatures(extProto, containingClass, sigs, allParsedProtocols);
+    }
+  }
+}
+
+/**
+ * Check if a protocol's methods/properties conflict with inherited signatures.
+ * Recursively checks extended protocols too.
+ *
+ * Only checks instance methods/properties since protocol class methods are not
+ * emitted in the TypeScript interface and can't cause declaration merging conflicts.
+ */
+function checkProtocolConflicts(
+  proto: ObjCProtocol,
+  containingClass: string,
+  inherited: Map<string, { returnType: string; paramTypes: string[]; isOptional: boolean }>,
+  allParsedProtocols: Map<string, ObjCProtocol>
+): boolean {
+  // Check this protocol's own instance methods (class methods are not emitted
+  // in the TS interface, so they can't conflict)
+  for (const method of proto.instanceMethods) {
+    const jsName = selectorToJS(method.selector);
+    const parentSig = inherited.get(jsName);
+    if (!parentSig) continue;
+
+    const retType = mapReturnType(method.returnType, containingClass);
+    if (retType !== parentSig.returnType) return true;
+
+    // Protocol methods are emitted as optional (foo?()) but class methods are
+    // non-optional (foo()). TypeScript considers these "not identical" in an
+    // interface extends clause, producing TS2320.
+    if (!parentSig.isOptional) return true;
+
+    const paramTypes = method.parameters.map((p) => mapParamType(p.type, containingClass));
+    if (paramTypes.length === parentSig.paramTypes.length) {
+      for (let i = 0; i < paramTypes.length; i++) {
+        if (paramTypes[i] !== parentSig.paramTypes[i]) return true;
+      }
+    }
+  }
+
+  // Check instance properties only (class properties are static in TS)
+  for (const prop of proto.properties) {
+    if (prop.isClassProperty) continue;
+    const parentSig = inherited.get(prop.name);
+    if (parentSig) {
+      const tsType = mapReturnType(prop.type, containingClass);
+      if (tsType !== parentSig.returnType) return true;
+      if (!parentSig.isOptional) return true;
+    }
+    if (!prop.readonly) {
+      const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+      const parentSetterSig = inherited.get(setterName);
+      if (parentSetterSig) {
+        if (!parentSetterSig.isOptional) return true;
+        const paramType = mapParamType(prop.type, containingClass);
+        if (parentSetterSig.paramTypes.length > 0 && paramType !== parentSetterSig.paramTypes[0]) {
+          return true;
+        }
+      }
+    }
+  }
+
+  // Recursively check extended protocols
+  for (const ext of proto.extendedProtocols) {
+    const extProto = allParsedProtocols.get(ext);
+    if (extProto && checkProtocolConflicts(extProto, containingClass, inherited, allParsedProtocols)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Generate a .ts file for a single ObjC class.
+ */
+export function emitClassFile(
+  cls: ObjCClass,
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[],
+  allKnownClasses: Set<string>,
+  allParsedClasses?: Map<string, ObjCClass>,
+  allKnownProtocols?: Set<string>,
+  classToFile?: Map<string, string>,
+  allParsedProtocols?: Map<string, ObjCProtocol>
+): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push(`import type { NobjcObject } from "objc-js";`);
+
+  // Collect referenced classes for imports
+  const refs = collectReferencedClasses(cls, allKnownClasses, allKnownProtocols);
+  lines.push(...emitImports(refs, currentFramework, allFrameworks, classToFile));
+
+  // Collect and emit struct type imports (one import per struct file)
+  const structRefs = collectReferencedStructs(cls);
+  if (structRefs.size > 0) {
+    for (const name of [...structRefs].sort()) {
+      lines.push(`import type { ${name} } from "../structs/${name}.js";`);
+    }
+  }
+
+  // Collect and emit enum type imports
+  const enumRefs = collectReferencedEnums(cls);
+  lines.push(...emitEnumImports(enumRefs, currentFramework, allFrameworks));
+
+  lines.push("");
+  lines.push(...emitClassBody(cls, allKnownClasses, allParsedClasses));
+
+  // Emit protocol conformance via TypeScript declaration merging.
+  // This establishes the subtyping relationship: _ClassName is assignable to _ProtocolName.
+  // Skip protocols whose methods conflict with the class's inherited signatures
+  // (e.g., different return types for the same method name).
+  if (allKnownProtocols && cls.protocols.length > 0) {
+    let knownProtos = cls.protocols.filter((p) => allKnownProtocols.has(p));
+    if (allParsedClasses && allParsedProtocols) {
+      knownProtos = knownProtos.filter(
+        (p) => !protocolConflictsWithClass(cls, p, allParsedClasses, allParsedProtocols, allKnownProtocols)
+      );
+    }
+    if (knownProtos.length > 0) {
+      const extendsList = knownProtos.map((p) => `_${p}`).join(", ");
+      lines.push(`export interface _${cls.name} extends ${extendsList} {}`);
+    }
+  }
+
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate a single .ts file containing multiple classes that share the same
+ * filename on a case-insensitive filesystem (e.g., MTROTAFoo and MTROtaFoo).
+ *
+ * Classes are topologically sorted so that superclasses within the group
+ * appear before their subclasses. All sibling classes are excluded from
+ * imports since they coexist in the same file.
+ */
+export function emitMergedClassFile(
+  classes: ObjCClass[],
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[],
+  allKnownClasses: Set<string>,
+  allParsedClasses?: Map<string, ObjCClass>,
+  allKnownProtocols?: Set<string>,
+  classToFile?: Map<string, string>,
+  allParsedProtocols?: Map<string, ObjCProtocol>
+): string {
+  // Set of class names in this merged file — these are "siblings"
+  const siblingNames = new Set(classes.map((c) => c.name));
+
+  // Topological sort: superclasses in the group come first.
+  // Build adjacency: if cls.superclass is a sibling, cls depends on it.
+  const sorted: ObjCClass[] = [];
+  const visited = new Set<string>();
+
+  function visit(cls: ObjCClass): void {
+    if (visited.has(cls.name)) return;
+    visited.add(cls.name);
+    // If superclass is a sibling, visit it first
+    if (cls.superclass && siblingNames.has(cls.superclass)) {
+      const parent = classes.find((c) => c.name === cls.superclass);
+      if (parent) visit(parent);
+    }
+    sorted.push(cls);
+  }
+
+  for (const cls of classes) {
+    visit(cls);
+  }
+
+  // Collect all referenced classes/structs/enums across all siblings
+  const allRefs = new Set<string>();
+  const allStructRefs = new Set<string>();
+  const allEnumRefs = new Set<string>();
+
+  for (const cls of sorted) {
+    const refs = collectReferencedClasses(cls, allKnownClasses, allKnownProtocols);
+    for (const ref of refs) {
+      // Exclude siblings — they're defined in this same file
+      if (!siblingNames.has(ref)) {
+        allRefs.add(ref);
+      }
+    }
+    const structs = collectReferencedStructs(cls);
+    for (const s of structs) {
+      allStructRefs.add(s);
+    }
+    const enums = collectReferencedEnums(cls);
+    for (const e of enums) {
+      allEnumRefs.add(e);
+    }
+  }
+
+  // Build the file
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push(`import type { NobjcObject } from "objc-js";`);
+
+  // Emit imports using shared helper (resolves case-collision filenames)
+  lines.push(...emitImports(allRefs, currentFramework, allFrameworks, classToFile));
+
+  // Emit struct imports (one import per struct file)
+  if (allStructRefs.size > 0) {
+    for (const name of [...allStructRefs].sort()) {
+      lines.push(`import type { ${name} } from "../structs/${name}.js";`);
+    }
+  }
+
+  // Emit enum imports
+  lines.push(...emitEnumImports(allEnumRefs, currentFramework, allFrameworks));
+
+  // Emit each class declaration
+  for (const cls of sorted) {
+    lines.push("");
+    lines.push(...emitClassBody(cls, allKnownClasses, allParsedClasses));
+
+    // Emit protocol conformance via TypeScript declaration merging.
+    // Skip protocols whose methods conflict with the class's inherited signatures.
+    if (allKnownProtocols && cls.protocols.length > 0) {
+      let knownProtos = cls.protocols.filter((p) => allKnownProtocols.has(p));
+      if (allParsedClasses && allParsedProtocols) {
+        knownProtos = knownProtos.filter(
+          (p) => !protocolConflictsWithClass(cls, p, allParsedClasses, allParsedProtocols, allKnownProtocols)
+        );
+      }
+      if (knownProtos.length > 0) {
+        const extendsList = knownProtos.map((p) => `_${p}`).join(", ");
+        lines.push(`export interface _${cls.name} extends ${extendsList} {}`);
+      }
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Emit the class declaration body (extends clause, methods, properties)
+ * without the file-level header/imports. Used by both emitClassFile and
+ * emitMergedClassFile.
+ */
+export function emitClassBody(
+  cls: ObjCClass,
+  allKnownClasses: Set<string>,
+  allParsedClasses?: Map<string, ObjCClass>
+): string[] {
+  const lines: string[] = [];
+
+  // Determine superclass type
+  let superType: string;
+  if (cls.superclass && allKnownClasses.has(cls.superclass)) {
+    superType = `_${cls.superclass}`;
+  } else {
+    superType = "NobjcObject";
+  }
+
+  lines.push(`export declare class _${cls.name} extends ${superType} {`);
+
+  // Emit instancetype overrides for alloc/new/init on subclasses.
+  const selfType = `_${cls.name}`;
+  const ownClassSelectors = new Set(cls.classMethods.map((m) => m.selector));
+  const ownInstanceSelectors = new Set(cls.instanceMethods.map((m) => m.selector));
+
+  if (cls.superclass) {
+    const instancetypeOverrides: string[] = [];
+
+    if (!ownClassSelectors.has("alloc")) {
+      instancetypeOverrides.push(`  static alloc(): ${selfType};`);
+    }
+    if (!ownClassSelectors.has("new")) {
+      instancetypeOverrides.push(`  static new(): ${selfType};`);
+    }
+    if (!ownInstanceSelectors.has("init")) {
+      instancetypeOverrides.push(`  init(): ${selfType};`);
+    }
+
+    for (const line of instancetypeOverrides) {
+      lines.push(line);
+    }
+  }
+
+  // Build parent signature map for override conflict detection
+  interface ParentSig {
+    returnType: string;
+    paramTypes: string[];
+  }
+  const parentSignatures = new Map<string, ParentSig>();
+  if (allParsedClasses && cls.superclass) {
+    let current = cls.superclass;
+    while (current) {
+      const parentCls = allParsedClasses.get(current);
+      if (!parentCls) break;
+      for (const prop of parentCls.properties) {
+        const tsType = mapReturnType(prop.type, parentCls.name);
+        if (!parentSignatures.has(prop.name)) {
+          parentSignatures.set(prop.name, { returnType: tsType, paramTypes: [] });
+        }
+        if (!prop.readonly) {
+          const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+          if (!parentSignatures.has(setterName)) {
+            const paramType = mapParamType(prop.type, parentCls.name);
+            parentSignatures.set(setterName, { returnType: "void", paramTypes: [paramType] });
+          }
+        }
+      }
+      for (const method of [...parentCls.instanceMethods, ...parentCls.classMethods]) {
+        const jsName = selectorToJS(method.selector);
+        if (!parentSignatures.has(jsName)) {
+          const retType = mapReturnType(method.returnType, parentCls.name);
+          const paramTypes = method.parameters.map((p) => mapParamType(p.type, parentCls.name));
+          parentSignatures.set(jsName, { returnType: retType, paramTypes });
+        }
+      }
+      current = parentCls.superclass ?? "";
+    }
+  }
+
+  function shouldSkipOverride(jsName: string, tsReturnType: string, childParamTypes?: string[]): boolean {
+    const parentSig = parentSignatures.get(jsName);
+    if (!parentSig) return false;
+
+    // Rule 1: Child returns NobjcObject but parent is more specific — skip
+    if (tsReturnType === "NobjcObject" && parentSig.returnType !== "NobjcObject") {
+      return true;
+    }
+    // Rule 2: Child adds nullability that parent doesn't have — skip
+    if (tsReturnType.includes(" | null") && !parentSig.returnType.includes(" | null")) {
+      return true;
+    }
+    // Rule 3: Return types differ — skip unless child is a known subclass of parent
+    const childBase = tsReturnType.replace(/ \| null$/, "");
+    const parentBase = parentSig.returnType.replace(/ \| null$/, "");
+    if (childBase !== parentBase && parentBase !== "NobjcObject") {
+      // Extract class names from _ClassName types and walk inheritance
+      const childClassName = childBase.startsWith("_") ? childBase.slice(1) : null;
+      const parentClassName = parentBase.startsWith("_") ? parentBase.slice(1) : null;
+      if (childClassName && parentClassName && allParsedClasses) {
+        let current: string | undefined = childClassName;
+        let isSubclass = false;
+        while (current) {
+          if (current === parentClassName) {
+            isSubclass = true;
+            break;
+          }
+          const parentCls = allParsedClasses.get(current);
+          if (!parentCls) break;
+          current = parentCls.superclass ?? undefined;
+        }
+        if (!isSubclass) return true;
+      } else if (childBase !== parentBase) {
+        // Can't verify subclass relationship (e.g. protocol types) — skip to be safe
+        return true;
+      }
+    }
+    // Rule 4: Parameter types differ — skip
+    if (childParamTypes && parentSig.paramTypes.length === childParamTypes.length) {
+      for (let i = 0; i < childParamTypes.length; i++) {
+        const childParam = childParamTypes[i]!;
+        const parentParam = parentSig.paramTypes[i]!;
+        if (childParam === parentParam) continue;
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Split properties into class and instance
+  const classProps = cls.properties.filter((p) => p.isClassProperty);
+  const instanceProps = cls.properties.filter((p) => !p.isClassProperty);
+
+  // Emit class methods (static), excluding class property accessors
+  const classPropertyNames = new Set(classProps.map((p) => p.name));
+  const classMethods = cls.classMethods.filter((m) => !classPropertyNames.has(m.selector));
+
+  const hasClassSection = classMethods.length > 0 || classProps.length > 0;
+  if (hasClassSection) {
+    lines.push("  // Class methods");
+    for (const method of classMethods) {
+      const jsName = selectorToJS(method.selector);
+      const retType = mapReturnType(method.returnType, cls.name);
+      const paramTypes = method.parameters.map((p) => mapParamType(p.type, cls.name));
+      if (shouldSkipOverride(jsName, retType, paramTypes)) continue;
+      const sig = emitMethodSignature(method, cls.name);
+      if (sig) lines.push(sig);
+    }
+    for (const prop of classProps) {
+      const tsType = mapReturnType(prop.type, cls.name);
+      if (shouldSkipOverride(prop.name, tsType, [])) continue;
+      const jsdoc = buildJSDoc({
+        description: prop.description,
+        isDeprecated: prop.isDeprecated,
+        deprecationMessage: prop.deprecationMessage
+      });
+      lines.push(...jsdoc);
+      lines.push(`  static ${prop.name}(): ${tsType};`);
+      if (!prop.readonly) {
+        const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+        const paramType = mapParamType(prop.type, cls.name);
+        if (!shouldSkipOverride(setterName, "void", [paramType])) {
+          lines.push(`  static ${setterName}(value: ${paramType}): void;`);
+        }
+      }
+    }
+  }
+
+  // Emit instance methods
+  const instancePropertyNames = new Set(instanceProps.map((p) => p.name));
+  const regularMethods = cls.instanceMethods.filter((m) => !instancePropertyNames.has(m.selector));
+
+  if (regularMethods.length > 0) {
+    if (hasClassSection) lines.push("");
+    lines.push("  // Instance methods");
+    for (const method of regularMethods) {
+      const jsName = selectorToJS(method.selector);
+      const retType = mapReturnType(method.returnType, cls.name);
+      const paramTypes = method.parameters.map((p) => mapParamType(p.type, cls.name));
+      if (shouldSkipOverride(jsName, retType, paramTypes)) continue;
+      const sig = emitMethodSignature(method, cls.name);
+      if (sig) lines.push(sig);
+    }
+  }
+
+  // Emit instance properties
+  if (instanceProps.length > 0) {
+    if (regularMethods.length > 0 || hasClassSection) lines.push("");
+    lines.push("  // Properties");
+    for (const prop of instanceProps) {
+      const tsType = mapReturnType(prop.type, cls.name);
+      if (shouldSkipOverride(prop.name, tsType, [])) continue;
+      const jsdoc = buildJSDoc({
+        description: prop.description,
+        isDeprecated: prop.isDeprecated,
+        deprecationMessage: prop.deprecationMessage
+      });
+      lines.push(...jsdoc);
+      lines.push(`  ${prop.name}(): ${tsType};`);
+      if (!prop.readonly) {
+        const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+        const paramType = mapParamType(prop.type, cls.name);
+        if (!shouldSkipOverride(setterName, "void", [paramType])) {
+          lines.push(`  ${setterName}(value: ${paramType}): void;`);
+        }
+      }
+    }
+  }
+
+  lines.push("}");
+
+  return lines;
+}
+
+/**
+ * Given an ObjCClass, determine which enum type names it references
+ * (for import statements). Checks mapped types against known integer and string enums.
+ */
+function collectReferencedEnums(cls: ObjCClass): Set<string> {
+  const refs = new Set<string>();
+  const intEnums = getKnownIntegerEnums();
+  const strEnums = getKnownStringEnums();
+
+  function extractEnumRefs(typeStr: string): void {
+    // Enum types appear as bare names (e.g., "ASAuthorizationPublicKeyCredentialAttestationKind")
+    // or in union with null (e.g., "ASAuthorizationPublicKeyCredentialAttestationKind | null").
+    // Split on " | " to handle union types.
+    for (const part of typeStr.split(" | ")) {
+      const trimmed = part.trim();
+      if (intEnums.has(trimmed) || strEnums.has(trimmed)) {
+        refs.add(trimmed);
+      }
+    }
+  }
+
+  const allMethods = [...cls.instanceMethods, ...cls.classMethods];
+  for (const method of allMethods) {
+    extractEnumRefs(mapReturnType(method.returnType, cls.name));
+    for (const param of method.parameters) {
+      extractEnumRefs(mapParamType(param.type, cls.name));
+    }
+  }
+  for (const prop of cls.properties) {
+    extractEnumRefs(mapReturnType(prop.type, cls.name));
+    extractEnumRefs(mapParamType(prop.type, cls.name));
+  }
+
+  return refs;
+}
+
+/**
+ * Given an ObjCProtocol, determine which enum type names it references.
+ */
+function collectProtocolReferencedEnums(proto: ObjCProtocol): Set<string> {
+  const refs = new Set<string>();
+  const intEnums = getKnownIntegerEnums();
+  const strEnums = getKnownStringEnums();
+
+  function extractEnumRefs(typeStr: string): void {
+    for (const part of typeStr.split(" | ")) {
+      const trimmed = part.trim();
+      if (intEnums.has(trimmed) || strEnums.has(trimmed)) {
+        refs.add(trimmed);
+      }
+    }
+  }
+
+  const allMethods = [...proto.instanceMethods, ...proto.classMethods];
+  for (const method of allMethods) {
+    extractEnumRefs(mapReturnType(method.returnType, proto.name));
+    for (const param of method.parameters) {
+      extractEnumRefs(mapParamType(param.type, proto.name));
+    }
+  }
+  for (const prop of proto.properties) {
+    extractEnumRefs(mapReturnType(prop.type, proto.name));
+    extractEnumRefs(mapParamType(prop.type, proto.name));
+  }
+
+  return refs;
+}
+
+/**
+ * Emit import statements for a set of referenced enum types, grouped by framework.
+ * Enum imports use the bare name (no `_` prefix), unlike class imports.
+ */
+function emitEnumImports(
+  refs: Set<string>,
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[]
+): string[] {
+  if (refs.size === 0) return [];
+
+  const lines: string[] = [];
+  const enumFwMap = buildEnumFrameworkMap(allFrameworks);
+
+  // Group refs by framework
+  const importsByFramework = new Map<string, string[]>();
+  for (const enumName of refs) {
+    const fw = enumFwMap.get(enumName);
+    if (!fw) continue;
+    if (!importsByFramework.has(fw)) {
+      importsByFramework.set(fw, []);
+    }
+    importsByFramework.get(fw)!.push(enumName);
+  }
+
+  for (const [fwName, enums] of importsByFramework) {
+    enums.sort();
+    for (const enumName of enums) {
+      if (fwName === currentFramework.name) {
+        lines.push(`import type { ${enumName} } from "./${enumName}.js";`);
+      } else {
+        lines.push(`import type { ${enumName} } from "../${fwName}/${enumName}.js";`);
+      }
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Given an ObjCProtocol, determine which struct type names it references.
+ */
+function collectProtocolReferencedStructs(proto: ObjCProtocol): Set<string> {
+  const refs = new Set<string>();
+
+  function extractStructRefs(typeStr: string): void {
+    for (const structName of STRUCT_TS_TYPES) {
+      if (typeStr === structName || typeStr.startsWith(structName + " ")) {
+        refs.add(structName);
+      }
+    }
+  }
+
+  const allMethods = [...proto.instanceMethods, ...proto.classMethods];
+  for (const method of allMethods) {
+    extractStructRefs(mapReturnType(method.returnType, proto.name));
+    for (const param of method.parameters) {
+      extractStructRefs(mapParamType(param.type, proto.name));
+    }
+  }
+  for (const prop of proto.properties) {
+    extractStructRefs(mapReturnType(prop.type, proto.name));
+    extractStructRefs(mapParamType(prop.type, proto.name));
+  }
+
+  return refs;
+}
+
+/**
+ * Given an ObjCProtocol, determine which other class/protocol names it references.
+ */
+function collectProtocolReferencedClasses(
+  proto: ObjCProtocol,
+  allKnownClasses: Set<string>,
+  allKnownProtocols?: Set<string>
+): Set<string> {
+  const refs = new Set<string>();
+
+  function extractClassRefs(typeStr: string): void {
+    const regex = /_(\w+)/g;
+    let match;
+    while ((match = regex.exec(typeStr)) !== null) {
+      const name = match[1]!;
+      if (allKnownClasses.has(name) || allKnownProtocols?.has(name)) {
+        refs.add(name);
+      }
+    }
+  }
+
+  const allMethods = [...proto.instanceMethods, ...proto.classMethods];
+  for (const method of allMethods) {
+    const retType = mapReturnType(method.returnType, proto.name);
+    extractClassRefs(retType);
+    for (const param of method.parameters) {
+      const pType = mapParamType(param.type, proto.name);
+      extractClassRefs(pType);
+    }
+  }
+
+  for (const prop of proto.properties) {
+    extractClassRefs(mapReturnType(prop.type, proto.name));
+    extractClassRefs(mapParamType(prop.type, proto.name));
+  }
+
+  // Remove self-reference
+  refs.delete(proto.name);
+
+  return refs;
+}
+
+/**
+ * Generate a .ts file for a single ObjC protocol.
+ * Protocols are emitted as TypeScript interfaces with optional methods,
+ * representing the method map shape for NobjcProtocol.implement().
+ */
+export function emitProtocolFile(
+  proto: ObjCProtocol,
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[],
+  allKnownClasses: Set<string>,
+  allKnownProtocols: Set<string>,
+  classToFile?: Map<string, string>
+): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push(`import type { NobjcObject } from "objc-js";`);
+
+  // Collect referenced classes for imports
+  const refs = collectProtocolReferencedClasses(proto, allKnownClasses, allKnownProtocols);
+
+  // Add extended protocols to the refs set so they go through emitImports too
+  // (protocols are entities just like classes in terms of import resolution)
+  for (const extProto of proto.extendedProtocols) {
+    if (allKnownProtocols.has(extProto)) {
+      refs.add(extProto);
+    }
+  }
+
+  lines.push(...emitImports(refs, currentFramework, allFrameworks, classToFile));
+
+  // Collect and emit struct type imports (one import per struct file)
+  const structRefs = collectProtocolReferencedStructs(proto);
+  if (structRefs.size > 0) {
+    for (const name of [...structRefs].sort()) {
+      lines.push(`import type { ${name} } from "../structs/${name}.js";`);
+    }
+  }
+
+  // Collect and emit enum type imports
+  const enumRefs = collectProtocolReferencedEnums(proto);
+  lines.push(...emitEnumImports(enumRefs, currentFramework, allFrameworks));
+
+  lines.push("");
+
+  // Build extends clause from extended protocols we have types for
+  const extendsClauses: string[] = [];
+  for (const extProto of proto.extendedProtocols) {
+    if (allKnownProtocols.has(extProto)) {
+      extendsClauses.push(`_${extProto}`);
+    }
+  }
+  const extendsStr = extendsClauses.length > 0 ? ` extends ${extendsClauses.join(", ")}` : "";
+
+  lines.push(`export interface _${proto.name}${extendsStr} {`);
+
+  // Split properties into class and instance
+  const instanceProps = proto.properties.filter((p) => !p.isClassProperty);
+
+  // Emit instance methods (all optional with ? syntax)
+  const instancePropertyNames = new Set(instanceProps.map((p) => p.name));
+  const regularMethods = proto.instanceMethods.filter((m) => !instancePropertyNames.has(m.selector));
+
+  if (regularMethods.length > 0) {
+    lines.push("  // Instance methods");
+    for (const method of regularMethods) {
+      const jsName = selectorToJS(method.selector);
+      const returnType = mapReturnType(method.returnType, proto.name);
+      const params: string[] = [];
+      const seenNames = new Map<string, number>();
+      for (const param of method.parameters) {
+        const tsType = mapParamType(param.type, proto.name);
+        let safeName = sanitizeParamName(param.name);
+        // Deduplicate: append numeric suffix for repeated parameter names
+        const prev = seenNames.get(safeName) ?? 0;
+        seenNames.set(safeName, prev + 1);
+        if (prev > 0) {
+          safeName = `${safeName}${prev + 1}`;
+        }
+        params.push(`${safeName}: ${tsType}`);
+      }
+      const jsdoc = buildJSDoc({
+        description: method.description,
+        isDeprecated: method.isDeprecated,
+        deprecationMessage: method.deprecationMessage,
+        selector: method.selector
+      });
+      if (jsdoc.length > 0) lines.push(...jsdoc);
+      lines.push(`  ${jsName}?(${params.join(", ")}): ${returnType};`);
+    }
+  }
+
+  // Emit instance properties (as optional getter methods)
+  if (instanceProps.length > 0) {
+    if (regularMethods.length > 0) lines.push("");
+    lines.push("  // Properties");
+    for (const prop of instanceProps) {
+      const tsType = mapReturnType(prop.type, proto.name);
+      const jsdoc = buildJSDoc({
+        description: prop.description,
+        isDeprecated: prop.isDeprecated,
+        deprecationMessage: prop.deprecationMessage
+      });
+      if (jsdoc.length > 0) lines.push(...jsdoc);
+      lines.push(`  ${prop.name}?(): ${tsType};`);
+      if (!prop.readonly) {
+        const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
+        const paramType = mapParamType(prop.type, proto.name);
+        lines.push(`  ${setterName}?(value: ${paramType}): void;`);
+      }
+    }
+  }
+
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Determine which framework a protocol belongs to.
+ */
+function getProtocolFramework(protocolName: string, frameworks: FrameworkConfig[]): string | null {
+  const map = buildProtocolFrameworkMap(frameworks);
+  return map.get(protocolName) ?? null;
+}
+
+// --- Enum file generation ---
+
+/**
+ * Generate a .ts file for an integer enum (NS_ENUM / NS_OPTIONS).
+ *
+ * Emits a const object with the computed values and a companion type
+ * that resolves to the union of its values. The enum prefix is stripped
+ * from constant names to produce short keys.
+ *
+ * Example output:
+ * ```ts
+ * export const ASAuthorizationPublicKeyCredentialLargeBlobSupportRequirement = {
+ *   Required: 0,
+ *   Preferred: 1,
+ * } as const;
+ * export type ASAuthorizationPublicKeyCredentialLargeBlobSupportRequirement =
+ *   typeof ASAuthorizationPublicKeyCredentialLargeBlobSupportRequirement[
+ *     keyof typeof ASAuthorizationPublicKeyCredentialLargeBlobSupportRequirement
+ *   ];
+ * ```
+ */
+export function emitIntegerEnumFile(enumDef: ObjCIntegerEnum): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push("");
+
+  // Strip the enum name prefix from constant names to get short keys.
+  // e.g., "ASAuthorizationPublicKeyCredentialLargeBlobSupportRequirementRequired"
+  //     → "Required"
+  const prefix = enumDef.name;
+  const entries: { key: string; value: string }[] = [];
+
+  for (const v of enumDef.values) {
+    let key = v.name;
+    if (key.startsWith(prefix)) {
+      key = key.slice(prefix.length);
+    }
+    // If stripping left an empty key or a key starting with a digit, use the full name
+    if (!key || /^\d/.test(key)) {
+      key = v.name;
+    }
+    entries.push({ key, value: v.value ?? "0" });
+  }
+
+  lines.push(`export const ${enumDef.name} = {`);
+  for (const entry of entries) {
+    lines.push(`  ${entry.key}: ${entry.value},`);
+  }
+  lines.push(`} as const;`);
+
+  // NS_OPTIONS bitmask types should accept any numeric combination of flags.
+  // `number & {}` widens the type to accept any number while preserving
+  // autocomplete for the known constant values.
+  const optionsPrefix = enumDef.isOptions ? "number & {} | " : "";
+
+  lines.push(`export type ${enumDef.name} =`);
+  lines.push(`  ${optionsPrefix}typeof ${enumDef.name}[keyof typeof ${enumDef.name}];`);
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Generate a .ts file for a string enum (NS_TYPED_EXTENSIBLE_ENUM etc.).
+ *
+ * Emits a const object mapping short names to their resolved string values,
+ * plus a companion type. The actual values are read from the framework binary
+ * at generation time via dlopen/dlsym.
+ *
+ * Example output:
+ * ```ts
+ * export const ASAuthorizationPublicKeyCredentialUserVerificationPreference = {
+ *   Preferred: "preferred",
+ *   Required: "required",
+ *   Discouraged: "discouraged",
+ * } as const;
+ * export type ASAuthorizationPublicKeyCredentialUserVerificationPreference =
+ *   typeof ASAuthorizationPublicKeyCredentialUserVerificationPreference[
+ *     keyof typeof ASAuthorizationPublicKeyCredentialUserVerificationPreference
+ *   ];
+ * ```
+ */
+export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkName: string): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push("");
+
+  // Filter to values that were successfully resolved
+  const resolvedValues = enumDef.values.filter((v) => v.value !== null);
+
+  if (resolvedValues.length > 0) {
+    lines.push(`export const ${enumDef.name} = {`);
+    const seenShortNames = new Set<string>();
+    for (const v of resolvedValues) {
+      if (seenShortNames.has(v.shortName)) continue;
+      seenShortNames.add(v.shortName);
+      // JSON.stringify handles escaping of special characters in the value
+      lines.push(`  ${v.shortName}: ${JSON.stringify(v.value)},`);
+    }
+    lines.push(`} as const;`);
+
+    lines.push(`export type ${enumDef.name} =`);
+    lines.push(`  typeof ${enumDef.name}[keyof typeof ${enumDef.name}];`);
+  } else {
+    // Fallback: if no values could be resolved, emit short names as a JSDoc comment
+    // and a type alias that accepts any string (for forward compatibility)
+    const shortNames = enumDef.values.map((v) => v.shortName);
+    if (shortNames.length > 0) {
+      lines.push(`/**`);
+      lines.push(` * Known values: ${shortNames.join(", ")}`);
+      lines.push(` * Values could not be resolved from the framework binary.`);
+      lines.push(` */`);
+    }
+    lines.push(`export type ${enumDef.name} = string;`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// --- Struct definitions for code generation ---
+// Each struct defines its TypeScript interface and factory function.
+// Field info comes from the objc-js native bridge's KNOWN_STRUCT_FIELDS table
+// (see struct-utils.h). Structs not in that table get positional names (field0, field1, ...).
+
+export interface StructFieldDef {
+  name: string;
+  type: string; // TypeScript type: "number" or a struct interface name
+}
+
+export type StructDef =
+  | {
+      /** The TypeScript interface/function name (e.g., "CGPoint") */
+      tsName: string;
+      /** Fields with their names and types */
+      fields: StructFieldDef[];
+      /** Factory function parameter list — for nested structs, these are flat params */
+      factoryParams?: { name: string; type: string }[];
+      /** Factory function body expression */
+      factoryBody?: string;
+    }
+  | {
+      /** The TypeScript alias name (e.g., "NSPoint") */
+      tsName: string;
+      /** If this is an alias for another struct (e.g., NSPoint = CGPoint) */
+      aliasOf: string;
+    };
+
+/**
+ * Generate a single struct .ts file (one per struct definition).
+ *
+ * For primary structs: emits an interface + factory function.
+ * For aliases: emits type alias + const re-export, with import of the target.
+ *
+ * @param def - The struct definition to emit.
+ * @param allDefs - All struct definitions (needed to look up nested struct deps).
+ */
+export function emitStructFile(def: StructDef, allDefs: StructDef[]): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+
+  if ("aliasOf" in def) {
+    // Alias file: import target struct, re-export as alias
+    lines.push(`import { ${def.aliasOf} } from "./${def.aliasOf}.js";`);
+    lines.push(`import type { ${def.aliasOf} as _${def.aliasOf} } from "./${def.aliasOf}.js";`);
+    lines.push("");
+    lines.push(`export type ${def.tsName} = _${def.aliasOf};`);
+    lines.push(`export const ${def.tsName} = ${def.aliasOf};`);
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  // Collect nested struct dependencies for imports
+  const deps = new Set<string>();
+  for (const field of def.fields) {
+    if (field.type !== "number") {
+      deps.add(field.type);
+    }
+  }
+
+  // Import each dependency
+  for (const dep of [...deps].sort()) {
+    lines.push(`import type { ${dep} } from "./${dep}.js";`);
+  }
+  if (deps.size > 0) {
+    lines.push("");
+  }
+
+  // Interface
+  lines.push("");
+  lines.push(`export interface ${def.tsName} {`);
+  for (const field of def.fields) {
+    lines.push(`  ${field.name}: ${field.type};`);
+  }
+  lines.push(`}`);
+
+  // Factory function
+  const params = def.factoryParams ?? def.fields.map((f: StructFieldDef) => ({ name: f.name, type: f.type }));
+  const paramStr = params.map((p: { name: string; type: string }) => `${p.name}: ${p.type}`).join(", ");
+  const body = def.factoryBody ?? `{ ${def.fields.map((f: StructFieldDef) => f.name).join(", ")} }`;
+
+  lines.push("");
+  lines.push(`export function ${def.tsName}(${paramStr}): ${def.tsName} {`);
+  lines.push(`  return ${body};`);
+  lines.push(`}`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate the barrel index.ts for src/structs/.
+ * Re-exports all struct types and factory functions.
+ */
+export function emitStructIndex(structDefs: StructDef[]): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push("");
+
+  for (const def of structDefs) {
+    lines.push(`export * from "./${def.tsName}.js";`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// --- C function file generation ---
+
+/**
+ * Generate a functions.ts file for a framework containing typed wrappers
+ * around `callFunction()` / `callVariadicFunction()` from objc-js.
+ *
+ * Each C function gets a TypeScript wrapper that:
+ * - Has typed parameters and return type
+ * - Passes the function name and type encoding options to the runtime
+ * - For variadic functions, uses `callVariadicFunction()` with the fixed arg count
+ *
+ * Example output:
+ * ```ts
+ * import { callFunction, callVariadicFunction } from "objc-js";
+ * import type { _NSString } from "./NSString.js";
+ *
+ * export function NSHomeDirectory(): _NSString {
+ *   return callFunction("NSHomeDirectory", { returns: "@" }) as _NSString;
+ * }
+ * export function NSLog(format: _NSString, ...args: any[]): void {
+ *   callVariadicFunction("NSLog", 1, format, ...args);
+ * }
+ * ```
+ */
+export function emitFunctionsFile(
+  functions: ObjCFunction[],
+  currentFramework: FrameworkConfig,
+  allFrameworks: FrameworkConfig[],
+  classToFile?: Map<string, string>
+): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+
+  // Determine which runtime imports we need
+  const hasNonVariadic = functions.some((f) => !f.isVariadic);
+  const hasVariadic = functions.some((f) => f.isVariadic);
+  const runtimeImports: string[] = [];
+  if (hasNonVariadic) runtimeImports.push("callFunction");
+  if (hasVariadic) runtimeImports.push("callVariadicFunction");
+  lines.push(`import { ${runtimeImports.join(", ")} } from "objc-js";`);
+
+  // Collect all referenced types for imports
+  const classRefs = new Set<string>();
+  const structRefs = new Set<string>();
+  const enumRefs = new Set<string>();
+  const intEnums = getKnownIntegerEnums();
+  const strEnums = getKnownStringEnums();
+  let needsNobjcObject = false;
+
+  for (const func of functions) {
+    // Check return type
+    const retType = mapReturnType(func.returnType, "");
+    if (retType.includes("NobjcObject")) needsNobjcObject = true;
+    extractFunctionTypeRefs(retType, classRefs, structRefs, enumRefs, intEnums, strEnums);
+    // Check param types
+    for (const param of func.parameters) {
+      const paramType = mapParamType(param.type, "");
+      if (paramType.includes("NobjcObject")) needsNobjcObject = true;
+      extractFunctionTypeRefs(paramType, classRefs, structRefs, enumRefs, intEnums, strEnums);
+    }
+  }
+
+  if (needsNobjcObject) {
+    lines.push(`import type { NobjcObject } from "objc-js";`);
+  }
+
+  // Emit class/protocol imports
+  if (classRefs.size > 0) {
+    lines.push(...emitImports(classRefs, currentFramework, allFrameworks, classToFile));
+  }
+
+  // Emit struct imports
+  for (const name of [...structRefs].sort()) {
+    lines.push(`import type { ${name} } from "../structs/${name}.js";`);
+  }
+
+  // Emit enum imports
+  lines.push(...emitEnumImports(enumRefs, currentFramework, allFrameworks));
+
+  lines.push("");
+
+  // Sort functions alphabetically for deterministic output
+  const sorted = [...functions].sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const func of sorted) {
+    const tsReturnType = mapReturnType(func.returnType, "");
+    const returnEncoding = qualTypeToEncoding(func.returnType);
+    const isVoidReturn = tsReturnType === "void";
+
+    // Build parameter list
+    const params: string[] = [];
+    const paramNames: string[] = [];
+    const seenNames = new Map<string, number>();
+
+    for (const param of func.parameters) {
+      const tsType = mapParamType(param.type, "");
+      let safeName = sanitizeParamName(param.name);
+      const prev = seenNames.get(safeName) ?? 0;
+      seenNames.set(safeName, prev + 1);
+      if (prev > 0) {
+        safeName = `${safeName}${prev + 1}`;
+      }
+      params.push(`${safeName}: ${tsType}`);
+      paramNames.push(safeName);
+    }
+
+    if (func.isVariadic) {
+      params.push("...args: any[]");
+    }
+
+    const paramStr = params.join(", ");
+    const returnTypeStr = tsReturnType;
+
+    if (func.isVariadic) {
+      // Variadic function: callVariadicFunction(name, fixedArgCount, ...allArgs)
+      lines.push(`export function ${func.name}(${paramStr}): ${returnTypeStr} {`);
+      const fixedCount = func.parameters.length;
+      const allArgNames = [...paramNames, "...args"];
+      if (isVoidReturn) {
+        lines.push(`  callVariadicFunction("${func.name}", ${fixedCount}, ${allArgNames.join(", ")});`);
+      } else {
+        lines.push(
+          `  return callVariadicFunction("${func.name}", ${fixedCount}, ${allArgNames.join(", ")}) as ${tsReturnType};`
+        );
+      }
+      lines.push(`}`);
+    } else {
+      // Non-variadic function: callFunction(name, options, ...args)
+      lines.push(`export function ${func.name}(${paramStr}): ${returnTypeStr} {`);
+
+      // Build options object
+      const optionParts: string[] = [];
+      if (!isVoidReturn && returnEncoding) {
+        optionParts.push(`returns: "${returnEncoding}"`);
+      }
+
+      // Build arg encodings array if any param needs explicit encoding
+      const argEncodings: (string | null)[] = func.parameters.map((p) => qualTypeToEncoding(p.type));
+      const needsArgEncodings = argEncodings.some((e) => e !== null && e !== "@");
+      if (needsArgEncodings && argEncodings.length > 0) {
+        const encodingStrs = argEncodings.map((e) => (e ? `"${e}"` : `"@"`));
+        optionParts.push(`args: [${encodingStrs.join(", ")}]`);
+      }
+
+      const hasOptions = optionParts.length > 0;
+      const optionsStr = hasOptions ? `{ ${optionParts.join(", ")} }` : "";
+
+      if (isVoidReturn) {
+        if (hasOptions) {
+          lines.push(`  callFunction("${func.name}", ${optionsStr}, ${paramNames.join(", ")});`);
+        } else if (paramNames.length > 0) {
+          lines.push(`  callFunction("${func.name}", undefined, ${paramNames.join(", ")});`);
+        } else {
+          lines.push(`  callFunction("${func.name}");`);
+        }
+      } else {
+        if (hasOptions) {
+          if (paramNames.length > 0) {
+            lines.push(
+              `  return callFunction("${func.name}", ${optionsStr}, ${paramNames.join(", ")}) as ${tsReturnType};`
+            );
+          } else {
+            lines.push(`  return callFunction("${func.name}", ${optionsStr}) as ${tsReturnType};`);
+          }
+        } else if (paramNames.length > 0) {
+          lines.push(`  return callFunction("${func.name}", undefined, ${paramNames.join(", ")}) as ${tsReturnType};`);
+        } else {
+          lines.push(`  return callFunction("${func.name}") as ${tsReturnType};`);
+        }
+      }
+      lines.push(`}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Extract class, struct, and enum references from a mapped TS type string
+ * (used by emitFunctionsFile for collecting imports).
+ */
+function extractFunctionTypeRefs(
+  typeStr: string,
+  classRefs: Set<string>,
+  structRefs: Set<string>,
+  enumRefs: Set<string>,
+  intEnums: Set<string>,
+  strEnums: Set<string>
+): void {
+  // Class/protocol references: _ClassName
+  const classRegex = /_(\w+)/g;
+  let match;
+  while ((match = classRegex.exec(typeStr)) !== null) {
+    classRefs.add(match[1]!);
+  }
+
+  // Struct references
+  for (const structName of STRUCT_TS_TYPES) {
+    if (typeStr === structName || typeStr.startsWith(structName + " ")) {
+      structRefs.add(structName);
+    }
+  }
+
+  // Enum references
+  for (const part of typeStr.split(" | ")) {
+    const trimmed = part.trim();
+    if (intEnums.has(trimmed) || strEnums.has(trimmed)) {
+      enumRefs.add(trimmed);
+    }
+  }
+}
+
+/**
+ * Generate the barrel index.ts for a framework.
+ *
+ * @param caseCollisions - Map from canonical filename to all class names in
+ *   that file. Colliding classes import from the canonical file rather than
+ *   their own name. Pass an empty map when there are no collisions.
+ * @param generatedIntegerEnums - Names of integer enums generated for this framework.
+ * @param generatedStringEnums - Names of string enums with resolved values (value + type export).
+ * @param generatedStringEnumsTypeOnly - Names of string enums without resolved values (type-only export).
+ * @param enumToFile - Map from colliding enum name → canonical filename (for case-insensitive collision handling).
+ * @param hasFunctions - Whether a functions.ts file was generated for this framework.
+ */
+export function emitFrameworkIndex(
+  framework: FrameworkConfig,
+  generatedClasses: string[],
+  generatedProtocols?: string[],
+  caseCollisions?: Map<string, string[]>,
+  generatedIntegerEnums?: string[],
+  generatedStringEnums?: string[],
+  generatedStringEnumsTypeOnly?: string[],
+  enumToFile?: Map<string, string>,
+  hasFunctions?: boolean
+): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push(`import { NobjcLibrary } from "objc-js";`);
+  if (generatedClasses.length > 0) {
+    lines.push(`import { _bindClass } from "../bind.js";`);
+  }
+  lines.push("");
+
+  // Use a different variable name for the library if a class has the same name
+  // as the framework (e.g. IOSurface framework has an IOSurface class)
+  const classNames = new Set(generatedClasses);
+  const libVar = classNames.has(framework.name) ? `${framework.name}_lib` : framework.name;
+  lines.push(`export const ${libVar} = new NobjcLibrary("${framework.libraryPath}");`);
+  lines.push("");
+
+  // Build a reverse lookup: className → canonical filename for collision groups
+  const classToFile = new Map<string, string>();
+  if (caseCollisions) {
+    for (const [canonical, group] of caseCollisions) {
+      for (const name of group) {
+        classToFile.set(name, canonical);
+      }
+    }
+  }
+
+  for (const className of generatedClasses) {
+    const fileName = classToFile.get(className) ?? className;
+    lines.push(`import type { _${className} } from "./${fileName}.js";`);
+    lines.push(`export const ${className} = _bindClass<typeof _${className}>(${libVar}, "${className}");`);
+    lines.push(`export type { _${className} };`);
+    lines.push("");
+  }
+
+  // Export protocol types (type-only, no runtime value)
+  if (generatedProtocols && generatedProtocols.length > 0) {
+    for (const protoName of generatedProtocols) {
+      lines.push(`import type { _${protoName} } from "./${protoName}.js";`);
+      lines.push(`export type { _${protoName} };`);
+      lines.push("");
+    }
+  }
+
+  // Export integer enums (re-export value + type)
+  if (generatedIntegerEnums && generatedIntegerEnums.length > 0) {
+    for (const enumName of generatedIntegerEnums) {
+      const fileName = enumToFile?.get(enumName) ?? enumName;
+      lines.push(`export { ${enumName} } from "./${fileName}.js";`);
+      lines.push("");
+    }
+  }
+
+  // Export string enums (re-export value + type)
+  if (generatedStringEnums && generatedStringEnums.length > 0) {
+    for (const enumName of generatedStringEnums) {
+      const fileName = enumToFile?.get(enumName) ?? enumName;
+      lines.push(`export { ${enumName} } from "./${fileName}.js";`);
+      lines.push("");
+    }
+  }
+
+  // Export unresolved string enums (type-only, no runtime value available)
+  if (generatedStringEnumsTypeOnly && generatedStringEnumsTypeOnly.length > 0) {
+    for (const enumName of generatedStringEnumsTypeOnly) {
+      const fileName = enumToFile?.get(enumName) ?? enumName;
+      lines.push(`export type { ${enumName} } from "./${fileName}.js";`);
+      lines.push("");
+    }
+  }
+
+  // Export C functions (re-export everything from functions.ts)
+  if (hasFunctions) {
+    lines.push(`export * from "./functions.js";`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate the top-level src/index.ts barrel.
+ * Only exports structs and delegates — frameworks are imported via
+ * subpath exports (e.g., "objcjs-types/AppKit") to avoid loading
+ * all framework types into the editor at once.
+ */
+export function emitTopLevelIndex(frameworkNames: string[]): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push("");
+
+  lines.push(`export * from "./structs/index.js";`);
+  lines.push(`export { createDelegate } from "./delegates.js";`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate src/delegates.ts — a ProtocolMap interface mapping ObjC protocol
+ * name strings to their TypeScript interface types, plus a type-safe
+ * createDelegate() wrapper around NobjcProtocol.implement().
+ */
+export function emitDelegatesFile(
+  frameworks: FrameworkConfig[],
+  generatedProtocolsByFramework: Map<string, string[]>
+): string {
+  const lines: string[] = [];
+  lines.push(AUTOGEN_HEADER);
+  lines.push(`import { NobjcProtocol } from "objc-js";`);
+  lines.push(`import type { NobjcObject } from "objc-js";`);
+  lines.push("");
+
+  // Collect all generated protocols with their framework for imports
+  const allProtocols: { name: string; framework: string }[] = [];
+  for (const fw of frameworks) {
+    const generated = generatedProtocolsByFramework.get(fw.name) ?? [];
+    for (const name of generated) {
+      allProtocols.push({ name, framework: fw.name });
+    }
+  }
+
+  // Sort for deterministic output
+  allProtocols.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Emit imports
+  for (const proto of allProtocols) {
+    lines.push(`import type { _${proto.name} } from "./${proto.framework}/${proto.name}.js";`);
+  }
+  lines.push("");
+
+  // Emit ProtocolMap interface
+  lines.push(`/** Maps ObjC protocol name strings to their TypeScript interface types. */`);
+  lines.push(`export interface ProtocolMap {`);
+  for (const proto of allProtocols) {
+    lines.push(`  ${proto.name}: _${proto.name};`);
+  }
+  lines.push(`}`);
+  lines.push("");
+
+  // Emit createDelegate function
+  lines.push(`/**`);
+  lines.push(` * Create a type-safe Objective-C delegate object.`);
+  lines.push(` *`);
+  lines.push(` * Wraps NobjcProtocol.implement() with full type inference —`);
+  lines.push(` * method names, parameter types, and return types are all inferred`);
+  lines.push(` * from the protocol name string.`);
+  lines.push(` *`);
+  lines.push(` * @example`);
+  lines.push(` * const delegate = createDelegate("NSWindowDelegate", {`);
+  lines.push(` *   windowDidResize$(notification) {`);
+  lines.push(` *     console.log("Window resized!");`);
+  lines.push(` *   },`);
+  lines.push(` * });`);
+  lines.push(` */`);
+  lines.push(`export function createDelegate<K extends keyof ProtocolMap>(`);
+  lines.push(`  protocolName: K,`);
+  lines.push(`  methods: Partial<ProtocolMap[K]>,`);
+  lines.push(`): NobjcObject {`);
+  lines.push(`  return NobjcProtocol.implement(`);
+  lines.push(`    protocolName,`);
+  lines.push(`    methods as Record<string, (...args: any[]) => any>,`);
+  lines.push(`  );`);
+  lines.push(`}`);
+  lines.push("");
+
+  return lines.join("\n");
+}