spine-runtimes/spine-flutter/generator.md

# Dart FFI Wrapper Generator

## Overview

A TypeScript-based code generator that extends the existing `spine-c/codegen` system to automatically generate clean, type-safe Dart wrapper classes over the raw FFI bindings. This eliminates the need for manual wrapper implementation while providing a native Dart API experience.

## Architecture

```
spine-cpp (C++ source)
    ↓ (existing type-extractor.ts)
spine-cpp-types.json (type definitions)
    ↓ (existing ir-generator.ts + c-writer.ts)
spine-c (C bindings: .h/.c files)
    ↓ (ffigen via generate_bindings.sh)
spine_flutter_bindings_generated.dart (raw FFI)
    ↓ (NEW: dart-generator.ts)
spine_flutter.dart (clean Dart API)
```

## Key Insights

### 1. Derivation vs Parsing
Instead of parsing the generated FFI bindings, we **derive** what ffigen produces using the same C type information that generates the headers. This works because ffigen follows predictable transformation rules:

### 2. Predictable Disposal Pattern
All C types follow a consistent disposal pattern (`spine_type_name` → `spine_type_name_dispose`), so we can derive disposal function names automatically instead of storing them.

### 3. Array Properties vs Regular Getters
C functions that return `spine_array_*` types become special **Array<T> properties** in Dart, requiring different generation logic than primitive getters.

### FFigen Transformation Rules

| C Code | Generated Dart FFI |
|--------|-------------------|
| `SPINE_C_API float spine_animation_get_duration(spine_animation self);` | `double spine_animation_get_duration(Pointer<spine_animation_wrapper> self)` |
| `SPINE_C_API void spine_animation_dispose(spine_animation self);` | `void spine_animation_dispose(Pointer<spine_animation_wrapper> self)` |
| `typedef enum { BLEND_NORMAL, BLEND_ADDITIVE } spine_blend_mode;` | `enum spine_blend_mode { BLEND_NORMAL(0), BLEND_ADDITIVE(1) }` |
| `SPINE_OPAQUE_TYPE(spine_animation)` | `typedef struct spine_animation_wrapper { char _dummy; } spine_animation_wrapper; typedef spine_animation_wrapper *spine_animation;` |
| `spine_array_timeline spine_animation_get_timelines(spine_animation self);` | `Pointer<spine_array_timeline_wrapper> spine_animation_get_timelines(Pointer<spine_animation_wrapper> self)` → **Array<Timeline> property** |

## Generator Components

### 1. Type Mapping System (`dart-types.ts`)

Defines the structure for Dart wrapper types:

```typescript
interface DartClass {
  name: string;                    // "Animation"
  cName: string;                   // "spine_animation" 
  nativeType: string;              // "Pointer<spine_animation_wrapper>"
  constructors: DartConstructor[];
  methods: DartMethod[];
  getters: DartGetter[];
  setters: DartSetter[];
  arrays: DartArrayGetter[];       // Properties that return Array<T> (e.g., animation.timelines)
}

interface DartMethod {
  name: string;                    // "apply"
  cFunctionName: string;           // "spine_animation_apply"
  returnType: DartType;
  parameters: DartParameter[];
  isStatic?: boolean;
}

interface DartGetter {
  name: string;                    // "duration"
  cFunctionName: string;           // "spine_animation_get_duration"
  returnType: DartType;
}

interface DartSetter {
  name: string;                    // "duration"
  cFunctionName: string;           // "spine_animation_set_duration"
  parameterType: DartType;
}

interface DartArrayGetter {
  name: string;                    // "timelines" (Dart property name)
  elementType: string;             // "Timeline" (element type inside Array<T>)
  cArrayType: string;              // "spine_array_timeline" (C array type returned)
  cGetterName: string;             // "spine_animation_get_timelines" (C function to call)
}

interface DartConstructor {
  cFunctionName: string;           // "spine_animation_create"
  parameters: DartParameter[];
}

interface DartParameter {
  name: string;
  type: DartType;
  cType: string;                   // Original C type for conversion
}

interface DartType {
  dart: string;                    // "double", "String", "Animation"
  isNullable?: boolean;
  isNative?: boolean;              // true for primitives, false for wrapper classes
}

interface DartEnum {
  name: string;                    // "BlendMode"
  cName: string;                   // "spine_blend_mode"
  values: DartEnumValue[];
}

interface DartEnumValue {
  name: string;                    // "normal"
  cName: string;                   // "SPINE_BLEND_MODE_NORMAL"  
  value: number;
}
```

### 2. Type Mapping Rules (`dart-type-mapper.ts`)

Converts C types to Dart types:

```typescript
class DartTypeMapper {
  // Maps C types to Dart types
  private static readonly TYPE_MAP: Record<string, DartType> = {
    'float': { dart: 'double', isNative: true },
    'double': { dart: 'double', isNative: true },
    'int': { dart: 'int', isNative: true },
    'bool': { dart: 'bool', isNative: true },
    'char*': { dart: 'String', isNative: true },
    'const char*': { dart: 'String', isNative: true },
    'void': { dart: 'void', isNative: true },
    'spine_skeleton': { dart: 'Skeleton', isNative: false },
    'spine_animation': { dart: 'Animation', isNative: false },
    // ... more mappings
  };

  static mapCTypeToDart(cType: string): DartType {
    // Handle pointers
    if (cType.endsWith('*')) {
      const baseType = cType.slice(0, -1).trim();
      const mapped = this.TYPE_MAP[baseType];
      return mapped ? { ...mapped, isNullable: true } : this.mapSpineType(baseType);
    }
    
    // Handle direct mappings
    return this.TYPE_MAP[cType] || this.mapSpineType(cType);
  }

  private static mapSpineType(cType: string): DartType {
    if (cType.startsWith('spine_')) {
      // spine_animation -> Animation
      const dartName = toPascalCase(cType.replace('spine_', ''));
      return { dart: dartName, isNative: false };
    }
    
    // Default to dynamic for unknown types
    return { dart: 'dynamic', isNative: false };
  }
}
```

### 3. Naming Convention Utilities (`dart-naming.ts`)

Handles C to Dart naming conversions:

```typescript
export function toPascalCase(snakeCase: string): string {
  return snakeCase
    .split('_')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
    .join('');
}

export function toCamelCase(snakeCase: string): string {
  const pascal = toPascalCase(snakeCase);
  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
}

export function extractMethodName(cFunctionName: string, className: string): string {
  // spine_animation_get_duration -> getDuration
  // spine_animation_set_duration -> setDuration
  // spine_animation_apply -> apply
  
  const prefix = `spine_${toSnakeCase(className)}_`;
  if (!cFunctionName.startsWith(prefix)) {
    throw new Error(`Function ${cFunctionName} doesn't match expected prefix ${prefix}`);
  }
  
  const methodPart = cFunctionName.slice(prefix.length);
  return toCamelCase(methodPart);
}

export function isGetter(methodName: string): boolean {
  return methodName.startsWith('get_');
}

export function isSetter(methodName: string): boolean {
  return methodName.startsWith('set_');
}

export function extractPropertyName(methodName: string): string {
  // get_duration -> duration
  // set_duration -> duration
  if (methodName.startsWith('get_') || methodName.startsWith('set_')) {
    return methodName.slice(4);
  }
  return methodName;
}
```

### 4. Dart Code Generator (`dart-writer.ts`)

Generates the actual Dart wrapper files:

```typescript
export class DartWriter {
  constructor(private outputDir: string, private bindingsImport: string) {}

  async writeClass(dartClass: DartClass): Promise<void> {
    const lines: string[] = [];
    
    // File header
    lines.push("// AUTO GENERATED FILE, DO NOT EDIT.");
    lines.push("// Generated by spine-c dart-wrapper generator");
    lines.push("");
    lines.push(`import '${this.bindingsImport}';`);
    lines.push("import 'dart:ffi';");
    lines.push("import 'array.dart';");
    lines.push("");
    
    // Class declaration
    lines.push(`class ${dartClass.name} {`);
    lines.push(`  final ${dartClass.nativeType} _ptr;`);
    lines.push(`  final SpineFlutterBindings _bindings;`);
    lines.push("");
    
    // Private constructor
    lines.push(`  ${dartClass.name}._(this._ptr, this._bindings);`);
    lines.push("");
    
    // Public constructors
    for (const constructor of dartClass.constructors) {
      lines.push(this.writeConstructor(dartClass, constructor));
      lines.push("");
    }
    
    // Getters
    for (const getter of dartClass.getters) {
      lines.push(this.writeGetter(getter));
    }
    
    // Setters  
    for (const setter of dartClass.setters) {
      lines.push(this.writeSetter(setter));
    }
    
    // Array getters
    for (const arrayGetter of dartClass.arrays) {
      lines.push(this.writeArrayGetter(arrayGetter));
    }
    
    // Methods
    for (const method of dartClass.methods) {
      lines.push(this.writeMethod(method));
      lines.push("");
    }
    
    // Disposal method (derived from class name)
    lines.push(`  void dispose() => _bindings.${dartClass.cName}_dispose(_ptr);`);
    
    lines.push("}");
    
    // Write to file
    const fileName = `${toSnakeCase(dartClass.name)}.dart`;
    const filePath = path.join(this.outputDir, fileName);
    await fs.writeFile(filePath, lines.join('\n'));
  }

  private writeConstructor(dartClass: DartClass, constructor: DartConstructor): string {
    const params = constructor.parameters.map(p => 
      `${p.type.dart} ${p.name}`
    ).join(', ');
    
    const args = constructor.parameters.map(p => 
      this.convertDartToC(p.name, p.type, p.cType)
    ).join(', ');
    
    return [
      `  factory ${dartClass.name}.create(SpineFlutterBindings bindings${params ? ', ' + params : ''}) {`,
      `    final ptr = bindings.${constructor.cFunctionName}(${args});`,
      `    return ${dartClass.name}._(ptr, bindings);`,
      `  }`
    ].join('\n');
  }

  private writeGetter(getter: DartGetter): string {
    if (getter.returnType.isNative) {
      return `  ${getter.returnType.dart} get ${getter.name} => _bindings.${getter.cFunctionName}(_ptr);`;
    } else {
      return [
        `  ${getter.returnType.dart} get ${getter.name} {`,
        `    final ptr = _bindings.${getter.cFunctionName}(_ptr);`,
        `    return ${getter.returnType.dart}._(ptr, _bindings);`,
        `  }`
      ].join('\n');
    }
  }

  private writeSetter(setter: DartSetter): string {
    const conversion = this.convertDartToC('value', setter.parameterType, '');
    return `  set ${setter.name}(${setter.parameterType.dart} value) => _bindings.${setter.cFunctionName}(_ptr, ${conversion});`;
  }

  private writeArrayGetter(arrayGetter: DartArrayGetter): string {
    return [
      `  Array<${arrayGetter.elementType}> get ${arrayGetter.name} {`,
      `    final array = _bindings.${arrayGetter.cGetterName}(_ptr);`,
      `    return Array.create<${arrayGetter.elementType}>(array, _bindings, ${arrayGetter.elementType}._);`,
      `  }`
    ].join('\n');
  }

  private writeMethod(method: DartMethod): string {
    const params = method.parameters.map(p => 
      `${p.type.dart} ${p.name}`
    ).join(', ');
    
    const args = ['_ptr', ...method.parameters.map(p => 
      this.convertDartToC(p.name, p.type, p.cType)
    )].join(', ');
    
    if (method.returnType.dart === 'void') {
      return [
        `  void ${method.name}(${params}) {`,
        `    _bindings.${method.cFunctionName}(${args});`,
        `  }`
      ].join('\n');
    } else if (method.returnType.isNative) {
      return [
        `  ${method.returnType.dart} ${method.name}(${params}) {`,
        `    return _bindings.${method.cFunctionName}(${args});`,
        `  }`
      ].join('\n');
    } else {
      return [
        `  ${method.returnType.dart} ${method.name}(${params}) {`,
        `    final ptr = _bindings.${method.cFunctionName}(${args});`,
        `    return ${method.returnType.dart}._(ptr, _bindings);`,
        `  }`
      ].join('\n');
    }
  }

  private convertDartToC(dartValue: string, dartType: DartType, cType: string): string {
    if (dartType.isNative) {
      // Handle string conversion
      if (dartType.dart === 'String') {
        return `${dartValue}.toNativeUtf8().cast<Char>()`;
      }
      return dartValue;
    } else {
      // Wrapper class - extract the pointer
      return `${dartValue}._ptr`;
    }
  }
}
```

### 5. Generic Array Implementation (`dart-array-writer.ts`)

Generates a single reusable Array class:

```typescript
export class DartArrayWriter {
  async writeArrayClass(outputDir: string): Promise<void> {
    const content = `
// AUTO GENERATED FILE, DO NOT EDIT.
// Generated by spine-c dart-wrapper generator

import 'dart:collection';
import 'dart:ffi';
import 'spine_flutter_bindings_generated.dart';

class Array<T> extends ListBase<T> {
  final Pointer _nativeArray;
  final SpineFlutterBindings _bindings;
  final T Function(Pointer) _elementFactory;
  final String _arrayTypeName;

  Array._(
    this._nativeArray,
    this._bindings,
    this._elementFactory,
    this._arrayTypeName,
  );

  static Array<T> create<T>(
    Pointer nativeArray,
    SpineFlutterBindings bindings,
    T Function(Pointer) elementFactory,
  ) {
    final typeName = T.toString().toLowerCase();
    return Array._(nativeArray, bindings, elementFactory, 'spine_array_\$typeName');
  }

  @override
  int get length {
    // Use dynamic function lookup based on type
    switch (_arrayTypeName) {
      case 'spine_array_timeline':
        return _bindings.spine_array_timeline_get_size(_nativeArray.cast());
      case 'spine_array_bone_data':
        return _bindings.spine_array_bone_data_get_size(_nativeArray.cast());
      case 'spine_array_slot_data':
        return _bindings.spine_array_slot_data_get_size(_nativeArray.cast());
      // Add more cases as needed
      default:
        throw UnsupportedError('Unknown array type: \$_arrayTypeName');
    }
  }

  @override
  T operator [](int index) {
    if (index < 0 || index >= length) {
      throw RangeError.index(index, this);
    }

    Pointer elementPtr;
    switch (_arrayTypeName) {
      case 'spine_array_timeline':
        elementPtr = _bindings.spine_array_timeline_get(_nativeArray.cast(), index);
        break;
      case 'spine_array_bone_data':
        elementPtr = _bindings.spine_array_bone_data_get(_nativeArray.cast(), index);
        break;
      case 'spine_array_slot_data':
        elementPtr = _bindings.spine_array_slot_data_get(_nativeArray.cast(), index);
        break;
      // Add more cases as needed
      default:
        throw UnsupportedError('Unknown array type: \$_arrayTypeName');
    }

    return _elementFactory(elementPtr);
  }

  @override
  void operator []=(int index, T value) {
    throw UnsupportedError('Array is read-only');
  }

  @override
  set length(int newLength) {
    throw UnsupportedError('Array is read-only');
  }
}
`;

    const filePath = path.join(outputDir, 'array.dart');
    await fs.writeFile(filePath, content.trim());
  }
}
```

### 6. Enum Generator (`dart-enum-writer.ts`)

Generates Dart enum wrappers:

```typescript
export class DartEnumWriter {
  async writeEnum(dartEnum: DartEnum, outputDir: string): Promise<void> {
    const lines: string[] = [];
    
    // File header
    lines.push("// AUTO GENERATED FILE, DO NOT EDIT.");
    lines.push("// Generated by spine-c dart-wrapper generator");
    lines.push("");
    
    // Enum declaration
    lines.push(`enum ${dartEnum.name} {`);
    
    // Enum values
    for (let i = 0; i < dartEnum.values.length; i++) {
      const value = dartEnum.values[i];
      const comma = i < dartEnum.values.length - 1 ? ',' : '';
      lines.push(`  ${value.name}(${value.value})${comma}`);
    }
    
    lines.push("");
    lines.push("  const ${dartEnum.name}(this.value);");
    lines.push("  final int value;");
    lines.push("");
    
    // From native conversion
    lines.push(`  static ${dartEnum.name} fromNative(int value) {`);
    lines.push("    switch (value) {");
    for (const value of dartEnum.values) {
      lines.push(`      case ${value.value}: return ${dartEnum.name}.${value.name};`);
    }
    lines.push(`      default: throw ArgumentError('Unknown ${dartEnum.name} value: \$value');`);
    lines.push("    }");
    lines.push("  }");
    lines.push("}");
    
    // Write to file
    const fileName = `${toSnakeCase(dartEnum.name)}.dart`;
    const filePath = path.join(outputDir, fileName);
    await fs.writeFile(filePath, lines.join('\n'));
  }
}
```

### 7. Main Generator Orchestrator (`dart-generator.ts`)

Coordinates the entire generation process:

```typescript
import { CClassOrStruct, CEnum, CArrayType } from './c-types';
import { DartClass, DartEnum } from './dart-types';
import { DartTypeMapper } from './dart-type-mapper';
import { DartWriter } from './dart-writer';
import { DartEnumWriter } from './dart-enum-writer';
import { DartArrayWriter } from './dart-array-writer';
import { extractMethodName, isGetter, isSetter, extractPropertyName } from './dart-naming';

export class DartGenerator {
  private typeMapper = new DartTypeMapper();
  private writer: DartWriter;
  private enumWriter = new DartEnumWriter();
  private arrayWriter = new DartArrayWriter();

  constructor(
    private cTypes: CClassOrStruct[],
    private cEnums: CEnum[],
    private cArrayTypes: CArrayType[],
    private outputDir: string,
    private bindingsImport: string = 'spine_flutter_bindings_generated.dart'
  ) {
    this.writer = new DartWriter(outputDir, bindingsImport);
  }

  async generateAll(): Promise<void> {
    // Ensure output directory exists
    await fs.mkdir(this.outputDir, { recursive: true });

    console.log(`Generating ${this.cTypes.length} Dart wrapper classes...`);
    
    // Generate wrapper classes
    for (const cType of this.cTypes) {
      const dartClass = this.convertCTypeToDartClass(cType);
      await this.writer.writeClass(dartClass);
      console.log(`Generated: ${dartClass.name}`);
    }

    console.log(`Generating ${this.cEnums.length} Dart enums...`);
    
    // Generate enums
    for (const cEnum of this.cEnums) {
      const dartEnum = this.convertCEnumToDartEnum(cEnum);
      await this.enumWriter.writeEnum(dartEnum, this.outputDir);
      console.log(`Generated enum: ${dartEnum.name}`);
    }

    // Generate generic Array class
    await this.arrayWriter.writeArrayClass(this.outputDir);
    console.log('Generated: Array<T>');

    console.log('Dart wrapper generation complete!');
  }

  private convertCTypeToDartClass(cType: CClassOrStruct): DartClass {
    const className = toPascalCase(cType.name.replace('spine_', ''));
    
    // Separate getters, setters, and regular methods
    const getters: DartGetter[] = [];
    const setters: DartSetter[] = [];
    const methods: DartMethod[] = [];
    const constructors: DartConstructor[] = [];
    const arrays: DartArrayGetter[] = [];

    for (const method of cType.methods) {
      const methodName = extractMethodName(method.name, cType.name);
      
      if (method.name.includes('_create')) {
        // Constructor
        constructors.push({
          cFunctionName: method.name,
          parameters: method.parameters.slice(0, -1).map(p => ({
            name: p.name,
            type: this.typeMapper.mapCTypeToDart(p.type),
            cType: p.type
          }))
        });
      } else if (isGetter(methodName)) {
        // Getter
        const propertyName = extractPropertyName(methodName);
        const returnType = this.typeMapper.mapCTypeToDart(method.returnType);
        
        // Check if this is an array getter
        if (method.returnType.startsWith('spine_array_')) {
          const elementType = this.extractArrayElementType(method.returnType);
          arrays.push({
            name: propertyName,
            elementType,
            cArrayType: method.returnType,
            cGetterName: method.name
          });
        } else {
          getters.push({
            name: propertyName,
            cFunctionName: method.name,
            returnType
          });
        }
      } else if (isSetter(methodName)) {
        // Setter
        const propertyName = extractPropertyName(methodName);
        const paramType = this.typeMapper.mapCTypeToDart(method.parameters[1].type);
        setters.push({
          name: propertyName,
          cFunctionName: method.name,
          parameterType: paramType
        });
      } else {
        // Regular method
        methods.push({
          name: methodName,
          cFunctionName: method.name,
          returnType: this.typeMapper.mapCTypeToDart(method.returnType),
          parameters: method.parameters.slice(1).map(p => ({
            name: p.name,
            type: this.typeMapper.mapCTypeToDart(p.type),
            cType: p.type
          }))
        });
      }
    }

    return {
      name: className,
      cName: cType.name,
      nativeType: `Pointer<${cType.name}_wrapper>`,
      constructors,
      methods,
      getters,
      setters,
      arrays
    };
  }

  private convertCEnumToDartEnum(cEnum: CEnum): DartEnum {
    return {
      name: toPascalCase(cEnum.name.replace('spine_', '')),
      cName: cEnum.name,
      values: cEnum.values.map(value => ({
        name: toCamelCase(value.name.replace(/^SPINE_.*?_/, '')),
        cName: value.name,
        value: value.value
      }))
    };
  }

  private extractArrayElementType(arrayType: string): string {
    // spine_array_timeline -> Timeline
    // spine_array_bone_data -> BoneData
    const match = arrayType.match(/spine_array_(.+)/);
    if (!match) throw new Error(`Invalid array type: ${arrayType}`);
    
    return toPascalCase(match[1]);
  }
}
```

### 8. Integration with Existing Codegen (`index.ts` modifications)

Extend the existing main function:

```typescript
// Add to existing imports
import { DartGenerator } from './dart-generator';

// Add to existing main() function after C generation
async function main() {
    // ... existing C generation code ...

    // Write all C files to disk
    const cWriter = new CWriter(path.join(__dirname, '../../src/generated'));
    await cWriter.writeAll(cTypes, cEnums, cArrayTypes);

    console.log('C code generation complete!');

    // NEW: Generate Dart wrappers
    const dartOutputDir = path.join(__dirname, '../../../lib/src/generated');
    const dartGenerator = new DartGenerator(
        cTypes,
        cEnums, 
        cArrayTypes,
        dartOutputDir
    );
    
    await dartGenerator.generateAll();

    console.log('All code generation complete!');
}
```

## Generated Output Structure

After running the generator, the output structure will be:

```
lib/
├── spine_flutter.dart                    # Main export file
├── spine_flutter_bindings_generated.dart # Raw FFI bindings (from ffigen)
└── src/
    └── generated/
        ├── array.dart                    # Generic Array<T> implementation
        ├── animation.dart                # Animation wrapper class
        ├── skeleton.dart                 # Skeleton wrapper class
        ├── bone_data.dart               # BoneData wrapper class
        ├── blend_mode.dart              # BlendMode enum
        └── ...                          # More generated classes and enums
```

## Usage Examples

### Before (Manual FFI Usage)
```dart
// Raw FFI - error-prone and verbose
final skeletonDataPtr = bindings.spine_skeleton_data_create_from_file('skeleton.json'.toNativeUtf8().cast());
final bonesArrayPtr = bindings.spine_skeleton_data_get_bones(skeletonDataPtr);
final numBones = bindings.spine_skeleton_data_get_num_bones(skeletonDataPtr);

for (int i = 0; i < numBones; i++) {
  final bonePtr = bindings.spine_array_bone_data_get(bonesArrayPtr, i);
  final namePtr = bindings.spine_bone_data_get_name(bonePtr);
  final name = namePtr.cast<Utf8>().toDartString();
  print('Bone: $name');
}

bindings.spine_skeleton_data_dispose(skeletonDataPtr);
```

### After (Generated Wrapper Usage)
```dart
// Clean, type-safe API
final skeletonData = SkeletonData.fromFile(bindings, 'skeleton.json');
final bones = skeletonData.bones;  // Array<BoneData>

for (final bone in bones) {  // Natural Dart iteration
  print('Bone: ${bone.name}');  // Direct property access
}

skeletonData.dispose();  // Clean disposal
```

### Advanced Usage
```dart
// Complex operations made simple
final skeleton = Skeleton.create(bindings, skeletonData);
final animState = AnimationState.create(bindings, animStateData);

// Arrays work like native Dart Lists
final animations = skeleton.data.animations;
final firstAnim = animations[0];
final animCount = animations.length;

// Functional programming support
final animNames = animations.map((a) => a.name).toList();
final longAnims = animations.where((a) => a.duration > 5.0).toList();

// Enum usage
skeleton.setSkin('goblin');
animState.setAnimation(0, firstAnim, true);
animState.setMixByName('idle', 'walk', 0.2);

// Chaining operations
skeleton.data.bones
  .where((bone) => bone.parent != null)
  .forEach((bone) => print('Child bone: ${bone.name}'));
```

## Build Integration

### 1. Update `generate_bindings.sh`

Add Dart wrapper generation to the existing script:

```bash
#!/bin/bash

# ... existing FFI generation code ...

# Generate Dart wrappers
echo "Generating Dart wrapper classes..."
cd src/spine-c/codegen
npm run generate-dart

echo "✅ All code generation completed!"
```

### 2. Add npm script to `spine-c/codegen/package.json`

```json
{
  "scripts": {
    "build": "tsc",
    "generate": "npm run build && node dist/index.js",
    "generate-dart": "npm run build && node dist/index.js --dart-only",
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}
```

### 3. Update `pubspec.yaml` dependencies

The generated code will require:

```yaml
dependencies:
  flutter:
    sdk: flutter
  ffi: ^2.1.0
  # ... existing dependencies
```

## Benefits

### 1. **Developer Experience**
- **Type Safety**: Compile-time checking prevents FFI pointer errors
- **IDE Support**: Full autocomplete, documentation, and refactoring
- **Familiar API**: Uses standard Dart patterns (getters, setters, Lists)
- **Memory Safety**: Automatic lifetime management with dispose patterns

### 2. **Performance**
- **Zero Copy**: Arrays provide lazy access to native data
- **Minimal Overhead**: Thin wrappers over FFI calls
- **Batch Operations**: Array operations can be optimized in native code

### 3. **Maintainability**
- **Automatic Updates**: Changes to C++ API automatically flow through
- **Consistent Patterns**: All classes follow the same conventions
- **Documentation**: Generated code includes comprehensive docs
- **Testing**: Type-safe API makes unit testing straightforward

### 4. **Reliability**
- **No Manual Coding**: Eliminates human error in wrapper implementation
- **Validated Generation**: Uses proven C type information
- **Comprehensive Coverage**: Every C function gets a Dart wrapper

## Implementation Timeline

### Phase 1: Core Infrastructure (1-2 weeks)
- [ ] Set up TypeScript generator project structure
- [ ] Implement basic type mapping system
- [ ] Create simple class generator for basic types
- [ ] Test with a few example classes (Animation, Skeleton)

### Phase 2: Array Support (1 week)
- [ ] Implement generic Array<T> class
- [ ] Add array detection and generation logic
- [ ] Test array functionality with timeline/bone arrays

### Phase 3: Enum Support (3-5 days)
- [ ] Add enum detection and generation
- [ ] Implement enum value mapping
- [ ] Test with BlendMode and other enums

### Phase 4: Advanced Features (1 week)
- [ ] Add constructor detection and generation
- [ ] Implement property getter/setter pairing
- [ ] Add disposal pattern detection
- [ ] Memory management best practices

### Phase 5: Integration & Polish (3-5 days)
- [ ] Integrate with existing build pipeline
- [ ] Add comprehensive documentation
- [ ] Create migration guide from manual FFI
- [ ] Performance testing and optimization

### Phase 6: Testing & Validation (1 week)
- [ ] Unit tests for all generated wrappers
- [ ] Integration tests with actual Spine files
- [ ] Performance benchmarks vs raw FFI
- [ ] Documentation and examples

**Total Estimated Time: 4-6 weeks**

## Future Enhancements

### 1. **Advanced Memory Management**
- Automatic disposal when objects go out of scope
- Reference counting for shared objects
- Memory leak detection in debug mode

### 2. **Performance Optimizations**
- Cached property access
- Batch array operations
- Native collection implementations

### 3. **Developer Tools**
- Debug visualizations for Spine objects
- Memory usage monitoring
- Performance profiling integration

### 4. **API Enhancements**
- Async/Future support for long operations
- Stream-based event handling
- Reactive programming patterns

This comprehensive generator will transform the Spine Flutter experience from low-level FFI manipulation to a clean, type-safe, and performant Dart API that feels native to the Flutter ecosystem.